pnpm audit --prod --audit-level=critical (the new CI gate) failed on
vitest <3.2.6 (critical, arbitrary file read/execute via the UI
server). Bump vitest + @vitest/coverage-v8 in-range across the
workspace and add @vitest/coverage-v8 to every package that runs
vitest but lacked it (core-audit, core-cms, core-eslint, core-testing,
core-trpc, apps/cms, web-next, web-tanstack, turbo/generators) so
'pnpm test -- --coverage' works in every package. No compound test
scripts exist, so the vitest-last pass-through concern does not apply.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Three generator fixes:
- templates/feature/vitest.config.ts.hbs lacked an include for
.test.{ts,tsx}; the node base only includes .test.ts, so scaffolded
UI component tests never executed
- gen event consume emitted an unguarded bus.subscribe although
ctx.bus is optional in BindContext — now wrapped in if (bus) {}
- e2e repo clones now exclude /dist and /.next build outputs, and
every dep-stripping e2e strips the scaffolded package from EVERY
workspace package.json via globSync instead of a hardcoded dependent
list that drifts as packages gain or drop the dependency
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
InMemoryEventBus.publish and PayloadJobsEventBus.publish called
descriptor.schema.parse(payload) but discarded the result, so handlers
and enqueued jobs received the raw input — zod defaults, catches,
transforms and strips never applied. Both bus templates now fan out the
parsed value; regression tests added to both test templates and the
events snapshot hashes regenerated (template-tree sha over
hbs-stripped paths — only the four touched files differ).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
- turbo/generators/config.ts used require() inside the reader generator
action (no-require-imports); use the top-level node:fs imports
- auth authentication.service.ts used a literal self-assertion
("users" as "users"); prefer-as-const
- apps/cms lacked web-next's next-env.d.ts triple-slash-reference
override, and the committed next-env.d.ts now references
.next/types/routes.d.ts
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
The core-package trpc removal e2e was only stripping @repo/core-trpc
from the two app package.json files. blog, marketing-pages, and
navigation also depend on core-trpc for their ./ui hooks, so pnpm
install in the simulated post-removal state failed to resolve the
workspace dep. Strip the dep from every package that references it.
- Add ReadOnly<F> phantom brand to core-shared/conformance (compile-time
enforcement that readers only wrap non-mutating use cases)
- Add isReadOnly runtime predicate for boot-time assertReaderPurity
- Scaffold pnpm turbo gen reader: creates integrations/readers/ with
interface, implementation, test, barrel, and adds ./reader export
subpath to package.json
Webpack (Next.js transpilePackages) resolves from .ts source directly
and cannot find .js files. The bind-production binders already used
extensionless imports; align bind-dev-seed to match. Also fixes the
turbo gen feature template so new features are consistent.
The core-package e2e tests cover each generator in isolation. None
exercised generators running in sequence — so the feature template
shipping without an integrations/cms/index.ts barrel went unnoticed
until `gen job` failed against a scaffolded feature.
This test scaffolds a feature, then runs `gen job` against it. `gen job`
throws at its `<gen:job-tasks>` anchor assertion if the barrel is
missing, so the composition gap now fails loudly.
Each core-package e2e test's `onTestFinished` cleanup `rmSync`-es a temp
clone containing a full installed `node_modules`. That delete can exceed
vitest's 10s default hook timeout under load, failing 2-8 of the 8 e2e
tests per run. Set `hookTimeout: 120_000` to match the per-test timeout.
The feature generator emitted no `src/integrations/cms/index.ts`, but
`gen job` and `gen event consume` both `assertAnchors` on that file's
`<gen:job-tasks>` anchor — so they failed on any freshly-scaffolded
feature. Add a `cms/index.ts.hbs` template carrying the anchor, wire the
add action into the generator, and export `./cms` from the package.json
template to match all five existing features.
The analytics, consent, and dsr optional-core generators lacked the
byte-identical reconstruction e2e tests the other five optional cores
already have. Add the three tests and their snapshots.
Adding three more tests exposed a latent flaw in the suite: each test
does a full `pnpm install` in a temp clone, and running all eight in
parallel saturated vitest's workers (RPC timeout) while the never-cleaned
temp dirs filled the disk. Run the suite sequentially via
`fileParallelism: false` and remove each temp clone with `onTestFinished`;
also exclude the local `.pnpm-store` from the clone.
- Add consent to CORE_PACKAGE_GENERATORS in turbo/generators/config.ts so
pnpm turbo gen core-package consent is a valid command (not hand-rollable)
- Create turbo/generators/templates/core-package/consent/ mirroring the
analytics template shape (AGENTS.md, package.json, tsconfig, turbo, vitest,
eslint, src/index.ts scaffolds)
- Regenerate packages/core-consent/ from the new template (replaces the
previous hand-rolled attempt that violated the generator-first rule)
- Add __consentChecked to withCapture PROPAGATED_BRANDS so the brand bubbles
through the full withSpan→withCapture wrapper chain to the outermost binding
that assertFeatureConformance reads
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Add optional `analyticsEvents?: readonly string[]` to `UseCaseManifest`
in `define-feature.ts` so manifests can declare which analytics events a
use case emits. Field defaults to absent (treated as []) — all existing
manifests remain valid without changes.
Update the feature generator template to emit `analyticsEvents: []` so
newly scaffolded features are analytics-declaration-ready from day one.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Add the `pnpm turbo gen core-package analytics` generator template and
run it to scaffold the @repo/core-analytics workspace package. The
package lands in placeholder state (empty barrel export) ready for the
IAnalytics + NoopAnalytics implementation in the next commit.
Includes:
- turbo/generators/templates/core-package/analytics/ templates
- turbo/generators/config.ts analytics generator registration
- packages/core-analytics/ placeholder scaffold
- apps/web-next/next.config.mjs transpilePackages entry
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Each of the five optional core package generators (events, realtime, audit,
trpc, ui) now copies pre-written decision: approved trace files into
docs/library-decisions/ at scaffold time, covering every direct runtime
dependency of that core package.
This prevents a pre-commit gate failure the first time a developer runs
pnpm turbo gen core-package <name> — the generator is the policy-compliant
path, so the traces land by construction.
- Added docs/library-decisions/*.md.hbs trace files under each of the five
core-package template directories (15 files total)
- Updated generator config to emit traces into workspace docs/library-decisions/
via a second emitTemplateTree call per core package
- Updated all five __snapshots__/core-package/*.snapshot.json to include the
new trace file entries
- Added verify-doc-shas.test.ts to pin SHA256 hashes of all 15 trace templates
so snapshot and file content cannot drift independently
ADR refs: events→ADR-015, realtime→ADR-016, audit→ADR-018;
trpc and ui cite closest ADR or null where no specific ADR exists.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Replace inline withSpan(withCapture(factory(deps))) form in the binder
templates with wireUseCase({...}) calls so newly scaffolded features are
consistent with the migrated production features.
Also add assertFeatureConformance to bind-dev-seed.ts.hbs (aligns with
the migrated auth/navigation pattern) and fix bind-dev-seed.test.ts.hbs
to call binders with the ctx object form (BindContext) instead of the old
two-argument (tracer, logger) form.
Verified by running turbo gen feature testfeature and confirming:
- Generated binders use wireUseCase for use cases
- All 5 conformance gates pass on the scaffold
- Scaffold cleaned up post-verification
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Closes the user's gap: when `pnpm turbo gen feature <name>` scaffolds
a new feature, that feature must also be tracked by release-please —
otherwise it sits outside the versioning + changelog pipeline.
The generator now performs three release-please integrations:
1. **CHANGELOG.md seeded at v0.1.0** — new template at
templates/feature/CHANGELOG.md.hbs emits a baseline entry pointing
at ADR-021 + docs/guides/releasing.md so the consumer immediately
sees where future entries will appear.
2. **package.json version field bumped** — templates/feature/
package.json.hbs: "0.0.0" -> "0.1.0", matching the per-feature
baseline established when release-please was set up.
3. **Manifest + config registration via a new custom action** —
lib/release-please-utils.ts exports
registerFeatureInReleasePlease(repoRoot, name) which:
- Reads .release-please-manifest.json, adds
`"packages/<name>": "0.1.0"`, writes back with sorted keys
(root stays first, rest alphabetical) so diffs stay minimal
- Reads release-please-config.json, adds the per-package config
block (package-name, component, changelog-path), writes back
with the same sort
- Idempotent — re-running on an already-tracked feature is a
no-op
- Throws fast if either file is missing (ADR-021 requires
release-please to be set up BEFORE features can register)
The generator wires this in via a function action between the last
file `add` and the next-steps printout. Its return string surfaces
in the generator log so the user sees "Registered @repo/<name> in
release-please tracking".
Tested: 5/5 unit tests cover the happy path, idempotency, sort
order, and both missing-file error paths. Smoke-tested against the
real repo configs (adding a synthetic "demo" feature, then
restoring) — manifest entry appears in the correct sorted position;
config block has the right shape.
Future `pnpm turbo gen feature` invocations cannot leave a feature
untracked. Existing features (auth, blog, media, marketing-pages,
navigation) were registered manually when the release-please epic
landed.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Lands L3 of the agent-first coverage architecture (ADR-020) — the
mutation-testing layer. Stryker on entities + use-cases (the pure
business-logic surface) catches the third dimension of test quality:
tests that exist + execute the code but assert nothing.
Deps (root devDependencies):
- @stryker-mutator/core ^8.7.0
- @stryker-mutator/vitest-runner ^8.7.0
Shared base: packages/core-testing/stryker.base.json
- testRunner: vitest (uses each feature's vitest.config.ts)
- mutate: src/entities/** + src/application/use-cases/** (excludes
tests, factories, contracts)
- thresholds: high 90 / low 80 / break 80
- reporters: progress + html + json (reports/mutation/{index.html,
mutation.json})
- incremental mode enabled, concurrency 4, timeout 10s
- exposed via @repo/core-testing/stryker.base.json subpath export
Per-feature config: packages/auth/stryker.config.json
- 4-line file that extends the shared base
- Proof-of-concept; other features get a config when L0 unification
closes their existing test gaps
Driver: scripts/coverage/mutate.mjs (zero-dep Node ESM)
- discoverStrykerConfigs: walks packages/* and apps/* for
stryker.config.json
- Supports --filter <name>, --since <ref> (incremental), --json
- Runs Stryker per-feature via node_modules/.bin/stryker run
- Surfaces per-package pass/fail summary; exits 1 on any failure
- Tests: scripts/coverage/mutate.test.mjs (3 tests, all green)
CI: .github/workflows/mutation-nightly.yml
- Cron at 02:30 UTC + workflow_dispatch with filter input
- Uploads reports/mutation/** as artifact (30-day retention)
- On failure, opens a tracking issue labelled mutation-testing
- permissions: contents: read, issues: write
- 60-min timeout (Stryker is slow by design)
Generator: turbo gen feature now scaffolds stryker.config.json from
turbo/generators/templates/feature/stryker.config.json.hbs — new
features ship mutation-ready out of the box.
Guide: docs/guides/coverage.md L3 section fleshed out with run
syntax, config shape, base config inventory, CI behavior, and a
"what you're looking for" primer on mutation scores.
Lockfile churn: pnpm regenerated the lockfile for the new deps;
~5K-line net reduction is collateral (pnpm version drift) but
mechanical.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Adds the day-to-day cookbook for the 4-layer coverage architecture
(ADR-020) and threads it into the discovery path:
docs/guides/coverage.md (new):
- 4 layers at a glance + when each fires
- Single-source-of-truth pattern (feature.manifest.ts coverage:
section) and the three readers (vitest, assertFeatureConformance,
coverage:diff)
- Daily workflow: pnpm test --coverage -> aggregate -> diff
- How to read a failure (stderr human + stdout JSON examples)
- How to fix uncovered slices (TDD walkthrough)
- The full allowlist (test files, configs, docs, scripts, dev
tooling, per-feature excludes)
- Adjusting bands (manifest-first, when to override vitest)
- CI behavior (two workflows: validate + coverage-snapshot)
- Reading the committed trend via git log -- coverage/summary.json
- Mutation testing primer (L3, opt-in, scope, lands in next story)
- Troubleshooting
CLAUDE.md Read First gets the new guide pinned between audit and
template-tiers, with the L0-L3 layer summary inline so agents see the
shape at a glance.
Feature generator updates (turbo/generators/templates/feature/):
- feature.manifest.ts.hbs: new `coverage:` block at <gen:coverage>
anchor scaffolded with the documented defaults + mutationTargets
- vitest.config.ts.hbs: now uses vitestThresholdsFromBands(
DEFAULT_COVERAGE_BANDS) instead of the duplicated literal — new
features ship conformance-compliant by default
Next features generated via `pnpm turbo gen feature` are coverage-
aware from the first commit: bands declared in manifest, vitest
config consumes the helper, no duplication to drift.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Final sweep for setup-process bookkeeping not caught by template-reset-v1.
ADRs drop Plan-N qualifiers; spec collapses the historical 11-phase
migration table; scaffolding guide drops "Phase added" column; comment
prefixes referencing R-numbers in test describes / eslint inline comments
are normalized. Architecture-level rule IDs (R40, R52, E0, J0, etc.) are
preserved where they serve as stable cross-references in ADRs.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- Regenerate audit + realtime core-package e2e snapshots (template
Phase-label changes altered file hashes)
- Fix pre-existing lint error in auth authentication.service.ts:
rename unused params to _user / _sessionId, drop stale eslint-disable
comments that were on wrong lines
- Mark story tasks 1-9 done; rebuild _state.json
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The template's AGENTS.md.hbs describes the 4-file component pattern under
`## Structure` but didn't tell agents how to scaffold one. After Phase 4
shipped the generator, an agent reading core-ui's AGENTS.md still wouldn't
discover `pnpm turbo gen core-ui-component` and would build files manually.
Added a one-line note immediately under the Structure heading pointing at
the generator. Snapshot hash for AGENTS.md updated to match.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Adds the setGenerator("core-ui-component") block, coreUiComponentActions
helper (2 guards + 4 add + 1 modify + 1 print = 8 actions), and
printCoreUiComponentNextSteps to config.ts; covers all three paths with
3 new unit tests in config.test.ts (registration shape, action shape per
tier, PascalCase validator). Generator test count: 17 → 20.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
The turbo/generators package shipped without `lint` or `typecheck` scripts,
so `pnpm lint` / `pnpm typecheck` at the root silently skipped it. This
masked 2 ESLint errors (unused imports) and 11 TypeScript errors (relative
imports missing the `.js` extension required by `moduleResolution: NodeNext`,
plus JSON imports missing the `with { type: "json" }` attribute).
- Add `lint` and `typecheck` scripts to turbo/generators/package.json so the
turbo pipeline picks them up (lint: 14/14, was 13/13).
- Add `.js` extensions to 7 relative imports across config.test.ts,
lib/core-package-utils.test.ts, lib/snapshot.test.ts, and the 4 e2e tests.
- Add `with { type: "json" }` attributes to 4 snapshot JSON imports in the
e2e tests.
- Remove unused `existsSync` and `splicePluginImportsAt` imports from
lib/core-package-utils.test.ts.
- Declare `@repo/core-typescript` + `typescript` devDependencies so the
generators package can run `tsc --noEmit` for typecheck.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- AGENTS.md bind-production code block: shows the slim default state
(no @repo/core-events / @repo/core-realtime imports, BindProductionContext
with no generic args) with a comment pointing to the scaffold workflow.
The previous block showed a fully-wired post-scaffold state without
signaling that none of those packages exist in main.
- bind-protocols.test.ts: top-of-file comment clarifies what these tests
actually verify (protocol shapes have required methods) vs what the
spec text might suggest (full assignability of optional packages'
interfaces — that's verified by the e2e reconstruction tests, not here).
- core-package-generator.md: drops two stale "Until Phases 3-6 land"
parentheticals — the phases shipped.
- config.test.ts: extends the choices assertion to cover all 4 names
(realtime, events, trpc, ui).
- marketing-pages bind-* comments: reverse the inverted optional/required
language. queue (IJobQueue) is from core-shared and always present;
bus is the optional one (from @repo/core-events when scaffolded).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Add EVENTS_RULE_BLOCK constant, events entry in CORE_PACKAGE_GENERATORS
dispatch table, events choice in prompts, and printEventsNextSteps helper.
Events entry emits 15 template files + transpilePackages splice + ESLint
no-restricted-syntax splice (E1 + J blocks). Add byte-identical e2e test
that strips @repo/core-events deps before pnpm install, scaffolds via
gen core-package events, and diffs against the snapshot.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Compute SHA-256 snapshot of packages/core-events (15 files) using the
shared computeSnapshot helper. The e2e test will diff a fresh scaffold
against this snapshot to guarantee byte-identical reconstruction.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Mirror packages/core-events/** into turbo/generators/templates/core-package/events/**/*.hbs.
15 files total (6 top-level + 9 src). No Handlebars interpolation needed
since none of the source files contain {{ }} patterns.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Adds turbo/generators to pnpm-workspace.yaml and declares its actual
dependencies so pnpm turbo boundaries reports zero issues.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
