kitchen-md/.claude/spec/project-scaffold.md

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.