alexion/kitchen-md
Archived
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore: scaffold Bun workspace monorepo

Browse Source 
Sets up the initial project structure: two packages (@kitchen-md/core
and @kitchen-md/bin), shared tsconfig, shared fixtures, per-package
test stubs (unit, integration, smoke), .gitignore, and project
CLAUDE.md with Conventional Commits convention.
This commit is contained in:
alexion
2026-07-08 21:33:20 -04:00
commit 220f73d8f7
19 changed files with 312 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

12
.claude/CLAUDE.md Normal file
View File

@@ -0,0 +1,12 @@
# kitchen-md
## Commit Messages
Commit messages must follow the Conventional Commits specification.
See [CONVENTIONAL-COMMITS.md](../CONVENTIONAL-COMMITS.md) for the full summary and specification.
Format: `<type>[optional scope]: <description>`
Common types: `feat`, `fix`, `docs`, `chore`, `test`, `refactor`, `build`.
Once files are staged, you may create the commit without waiting for the user to ask.

63
.claude/spec/project-scaffold.md Normal file
View File

@@ -0,0 +1,63 @@
## Problem Statement
The `kitchen-md` repository is a fresh git init with no files.
Before any implementation can begin, the project needs a complete structural scaffold: a monorepo layout, two packages, TypeScript configuration, and a testing infrastructure organised by tier.
## Solution
A Bun-workspaces monorepo containing two packages (`@kitchen-md/core` and `@kitchen-md/bin`), a shared TypeScript base configuration, and per-package test scaffolding organised into unit, integration, and smoke tiers.
Synthetic test fixtures are shared at the workspace root so both packages can reference the same canonical recipe files.
## User Stories
1. As a developer, I want a Bun workspace root so that I can manage both packages with a single toolchain and no additional runtime.
2. As a developer, I want `@kitchen-md/core` isolated as its own package so that it can be consumed by a future Obsidian plugin without bundling the CLI.
3. As a developer, I want `@kitchen-md/bin` isolated as its own package so that the CLI binary can be compiled and distributed independently of the library.
4. As a developer, I want a shared TypeScript base configuration at the workspace root so that both packages inherit consistent compiler settings without duplication.
5. As a developer, I want unit test files co-located with their source module so that the test for a module is always findable next to the module itself.
6. As a developer, I want integration test files co-located with the code they exercise so that cross-module test coverage is discoverable alongside the relevant source.
7. As a developer, I want smoke tests in `@kitchen-md/bin` that invoke the CLI directly so that end-to-end user-story coverage is separated from unit-level coverage.
8. As a developer, I want synthetic recipe fixture files at the workspace root so that both packages can reference the same canonical test inputs without duplication.
## Implementation Decisions
- Bun is the single toolchain for the entire project: package manager, runtime, test runner, and native binary compiler (`bun --compile`).
No Node.js runtime is required on target machines.
- The workspace root `package.json` declares Bun workspaces pointing to `packages/core` and `packages/bin`.
- `@kitchen-md/core` lives in `packages/core/` and is structured as a publishable library with a single entry point.
- `@kitchen-md/bin` lives in `packages/bin/`, declares `@kitchen-md/core` as a workspace dependency, and declares a `bin` entry named `kitchen` pointing at the CLI entry point.
- A `tsconfig.json` at the workspace root defines shared compiler settings (strict mode, ESNext target and module, bundler module resolution, Bun types).
Each package's `tsconfig.json` extends the root config.
- A `fixtures/` directory at the workspace root holds synthetic `.md` recipe files.
The primary fixture covers every annotation type (ingredient, cookware, timer) and all format features.
Additional fixture files are acceptable for regression cases or edge cases that cannot fit cleanly into the primary file.
## Testing Decisions
- Tests assert external behaviour only — given an input, assert the output — never implementation internals.
- **Unit tests**: co-located with the source file they test, named `{module}_test.ts`.
All test data is inline raw strings within the test file; no filesystem access.
Both packages have unit tests.
- **Integration tests**: co-located with the source they exercise, naming is flexible.
Integration tests read from the shared `fixtures/` directory.
Both packages have integration tests where they cross file boundaries.
- **Smoke tests**: present only in `@kitchen-md/bin`.
Each smoke test invokes the CLI directly (via subprocess or equivalent) and asserts its output against expected results.
Smoke tests use the shared `fixtures/` directory as input.
Smoke test coverage maps directly to the CLI user stories in the recipe format spec.
- The Bun test runner discovers test files via `*_test.ts` and `*.test.ts` patterns; all test files must match one of these patterns to be picked up automatically.
## Out of Scope
- Parser implementation (covered by the recipe format spec).
- CLI command design and subcommand structure.
- Aisle mapping file format.
- Shopping list generator.
- Publishing either package to a registry.
- CI/CD configuration.
## Further Notes
- The `$` sigil for cookware and the choice of Bun over other runtimes are decisions from the recipe format spec; this scaffold spec assumes them and does not re-litigate them.
- The binary is named `kitchen` (the `bin` key in `@kitchen-md/bin`'s `package.json`), not `kitchen-md` or `kmd`.
- Smoke tests differ from integration tests in degree, not kind: they test the CLI as a black box from the outside rather than testing module interactions from the inside.