Skip to content

refactor: add options through slots instead of exact-line edits - #4

Merged
SibilSoren merged 3 commits into
mainfrom
refactor/feature-composition
Nov 13, 2026
Merged

SibilSoren merged 3 commits into
mainfrom
refactor/feature-composition

Conversation

@SibilSoren

Copy link
Copy Markdown
Owner

Description

Options are now added through named slots in the template, with one file describing each option, instead of find-and-replace on exact lines. Nothing changes for users. This comes before the database options, because Gatekeeper, Drizzle and Prisma would all have edited the same files the old way.

Stacked on #3. Merge that first, and I'll rebase this onto main.

Type of Change

  • 🐛 Bug fix
  • ✨ New feature
  • 📝 Documentation update
  • 🔧 Refactor / chore
  • 💥 Breaking change

Changes Made

  • Slots. Template files get marker lines such as // @slot middleware (# @slot in YAML and Dockerfiles, <!-- @slot --> in Markdown). An option adds its code there, and projects without it lose the line.
  • One file per option. src/features/gatekeeper.ts lists Gatekeeper's dependency and what it adds at the imports and middleware slots in app.ts. Files that are new to the project go in features/<id>/ and can't replace an existing file.
  • package.json. Options add dependencies and scripts. Two options that disagree on an entry, or an option that changes a template entry, stop the scaffold with an error.
  • Tests. tests/features.test.ts checks every registered option: its slots appear exactly once, it doesn't ship a template file, and it changes nothing outside package.json, the files it adds to and its own files. There are unit tests for slots, the package.json merge and composing.
  • features is in the package's files, with a test, so option files reach npm users.
  • "Adding an Option" in CONTRIBUTING.md, and a changelog entry under Unreleased.

Testing

  • I've tested the CLI tool locally (npx tsx src/index.ts test-project)
  • The generated project boots successfully (npm run dev)
  • The generated project's tests pass (npm test)
  • I've run npm run lint with no errors

At every commit, I generated all four combinations (npm and pnpm, with and without Gatekeeper) and compared them with the output from #3. All 150 files were byte-for-byte the same. Every commit also passes the CLI checks, and both generated variants pass typecheck, build, tests, lint, the format check and the boot checks from ci.yml.

When I deleted the middleware slot from the template, 8 tests failed and named it.

Checklist

  • My code follows the project's code style
  • I've updated documentation if needed
  • I've added an entry to CHANGELOG.md (if user-facing change)

@SibilSoren
SibilSoren changed the base branch from fix/template-safety to main November 13, 2026 07:13
Slots are marker lines such as "// @slot middleware" in template files. An
option adds its code there, and projects without it lose the line. This is
to replace find-and-replace on exact lines, which breaks as soon as two
options edit the same file.

Nothing uses these yet.
Gatekeeper is now described in src/features/gatekeeper.ts and added at two
slots in app.ts, instead of by matching exact lines. New options follow the
same pattern: one file each, extra files in features/<id>/, and no changes
to template files outside slots.

Generated projects are byte-for-byte the same for npm and pnpm, with and
without Gatekeeper. New tests check every registered option: its slots
exist exactly once, it doesn't replace template files, and it changes
nothing it doesn't declare. The features folder is in the published
package, with a test so it stays there.
@SibilSoren
SibilSoren force-pushed the refactor/feature-composition branch from 59f4e5e to 60301d5 Compare November 13, 2026 07:13
@SibilSoren
SibilSoren merged commit 874ac2e into main Nov 13, 2026
14 checks passed
@SibilSoren
SibilSoren deleted the refactor/feature-composition branch November 17, 2026 07:31
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant