Skip to content

docs: catalog plan and apply boundary #7

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
mkczarkowski merged 1 commit into from
Jul 27, 2026
Merged

docs: catalog plan and apply boundary #7

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 11 additions & 1 deletion context/examples/catalog.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

<!-- GENERATED by tools/examples-catalog/build.mjs — do not hand-edit. Run `bun run examples:catalog`. -->

> Source of truth: `tools/examples-catalog/config.mjs`. Exemplar status: all 10 exemplar files pass oxlint.
> Source of truth: `tools/examples-catalog/config.mjs`. Exemplar status: all 12 exemplar files pass oxlint.

The reference shape for each kind of unit in this repo. Copy the linked exemplar
instead of inventing a shape. Every entry points at real, in-repo code that
Expand Down Expand Up @@ -60,6 +60,16 @@ passes lint and (where paired) ships with its test — no throwaway samples.
- Node built-ins imported explicitly; no hidden globals.
- Ships WITH its test — no untested lib modules.

### Read-only plan / filesystem apply boundary

- **Exemplar:** `./src/lib/writer.ts`
- **Paired with:** `./tests/writer-plan.test.ts`
- **When to use:** Adding preview, dry-run, or conflict reporting to a filesystem workflow without letting read-only and mutating paths drift.
- **Shape:**
- planBundle classifies every action without writing or prompting; applyBundle consumes that same plan.
- The shared result vocabulary covers created, unchanged, updated, and conflict outcomes.
- Parity tests prove planner classifications match apply results across the important state transitions.

### API client seam (allowlisted hosts)

- **Exemplar:** `./src/lib/api-client.ts`
Expand Down
14 changes: 14 additions & 0 deletions tools/examples-catalog/config.mjs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -84,6 +84,20 @@ export const examples = [
'Ships WITH its test — no untested lib modules.',
],
},
{
id: 'plan-apply-boundary',
category: 'lib',
title: 'Read-only plan / filesystem apply boundary',
file: 'src/lib/writer.ts',
subject: 'tests/writer-plan.test.ts',
whenToUse:
'Adding preview, dry-run, or conflict reporting to a filesystem workflow without letting read-only and mutating paths drift.',
shape: [
'planBundle classifies every action without writing or prompting; applyBundle consumes that same plan.',
'The shared result vocabulary covers created, unchanged, updated, and conflict outcomes.',
'Parity tests prove planner classifications match apply results across the important state transitions.',
],
},
{
id: 'api-seam',
category: 'lib',
Expand Down