feat(tsforge): add scaffold manifest as config-surface source of truth#224
Merged
Conversation
The tsforge setup wizard reads .tsforge/scaffold-manifest.json to drive a greenfield scaffold of BoringStack: it generates the wizard questions, the container-topology preview, the required-secrets checklist, and the .env from this declarative file. tsforge holds no stack knowledge of its own. Document the contract in AGENTS.md (AI-first repo): agents must update the manifest in the same change that alters the env/toggle/provider/secret surface; tsforge's completeness alarm fails the build on drift.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Adds
.tsforge/scaffold-manifest.json— a declarative description of BoringStack's entire configurable surface — and documents the contract inAGENTS.md.The tsforge setup wizard clones BoringStack and reads this file to drive a greenfield scaffold: the questions it asks, the container-topology preview (5 vs ~20 services depending on toggles), the required-secrets checklist, and the
.envit writes. tsforge holds no stack knowledge of its own — it all lives here, next to the code it describes.The manifest models, per field
toggle/one-of/multi/secret/text),group, per-STACKdefaultsaddsServices— which containers a toggle spawns (e.g.WITH_OBSERVABILITY→ prometheus/grafana/loki/tempo/alertmanager)requiresSecrets(+requiresSecretsWhento gate on an enabling toggle, e.g. AI provider keys;requiresSecretsProdOnlyfor dev-autogenerated infra secrets)crossRules—implies/excludes(OAuth ⇒ Valkey;EMAIL_PROVIDER=smtp⇒WITH_MAILPIT; OTel vs Sentry "don't double-instrument")envFileByGroup/envFile— which.enveach value is written to (infra/identity →infra/compose/compose/.env, app features →apps/api/.env)Validated against the current
.env.examplefiles: parses cleanly, zero coverage gaps, dev defaults resolve to the full 14-service topology.Keep-in-sync contract (AI-first repo)
AGENTS.mdgains a "Scaffold manifest — keep it in sync" section: agents must update this file in the same change that alters any env toggle / provider / secret / service mapping. This is enforced — tsforge's scaffold suite runs a completeness alarm that fails the build if a watchedWITH_*/*_ENABLEDtoggle in.env.exampleis neither modelled here nor waived viawatchIgnore. A drifted manifest is a red build, not a silent gap.Notes
defaultRef: "main"— tsforge records the resolved SHA per-scaffold for replay.