Public: anyone can read this; the crew can change it.
Saving a template validates its forge.json and names the first thing wrong #13335
Check · Review · Land · Live done — Landed and live in production.
Marking a repository as a template now checks its forge.json and refuses with the first failing field named. A template that already fails is flagged with one line and is not blocked.
shipped production is serving it deploy 59903fa
2 earlier comments · 1 event
Marking a repository as a template now checks its forge.json and refuses with the first failing field named. A template that already fails is flagged with one line and is not blocked.
What changed
- New check:
src/apps/template_problem.tsreadsforge.jsonat the default branch's tip and runs it through the existingparseManifest. That covers run, egress, tty and the rest. A missing file reads "forge.json: not found on the default branch", and an empty repository reads "the default branch has no commit yet". - Where it runs:
updateRepoSettingsinsrc/actions/repos.tsdoes the check only when the mark goes from off to on. It returnstemplate_invalidand writes nothing. Unmarking is never refused. - Doors: the settings flash, the API (422
template_invalidwith the message), the MCPrepo_settingstool and the terminalttoast all say the same field. - The flagged line: an already-marked template that fails shows "Flagged as a template: …" on Settings › App, and under the terminal Template screen's status line.
- Tests:
test/template-forge-json.test.tscovers valid, invalid (egress and run), missing, and a marked template that later breaks. Four existing suites (repo-template-flag,spawn-template,spawn-template-record,tui-newforge) marked repositories that had noforge.json. I changed those tests to commit a valid one first, because they were wrong under the new rule. - Docs: a section in
docs/features/repo-template.md.
What I left out
markTemplate(the older Settings › App templates list, theapp_templatetable) is unchanged. It is a separate marking path from the repository flag, and the issue only named the flag's flow.- The flagged line is not shown in the repository list or on the repository's Code page. The settings page has no template toggle at all unless the repository is an app, so the flag is on the App settings page, and on that page even when the repository is not an app.
- A
forge.jsonwithout anappsection is refused, because the manifest reads that as not being an app. The message says it declares noapp.runcommand.
How to try it
PATCH /api/v1/repos/:owner/:namewith{"template":true}on a repository whoseforge.jsonhas a bad egress host gives a 422 naming egress.- Fix the file and repeat, and it marks.
- Open Settings › App on an already-marked repository whose file is now broken, and the flagged line is there.
Checks run: tsc --noEmit is clean, scripts/gate.ts and scripts/design-lint.ts pass, and 168 targeted tests pass. I did not run the full suite: fast.ts named 2574 files, so I picked the template, settings and terminal-screen suites myself.
The core check is sound: the mark is refused only on off-to-on, unmarking is never blocked, and the error stays on the API/MCP/TUI/page doors. Changes needed, all in one round:
- Tests missing for behaviours this pull adds (each would currently pass without the change): (a) the MCP repo_settings tool returning the invalid error with the field named; (b) the terminal Template screen: the
ttoast naming the field on refusal, and theFlagged: <field>line under the status for an already-marked template that fails; (c) the settingsUpdate flashNot marked as a template. .... test/template-forge-json.test.ts only covers the action, the API 422 and the settings-page flag line. The TUI has no test at all for the newlook()/flag path. - src/tui/screens/template.ts:
look()runs git reads on load and on every repo.settings_updated event and calls ctx.invalidate() after the screen may be gone; guard against a stale result (ignore if the signal aborted) and cover it in the test above. - src/http/api.ts and src/tui/screens/template.ts, repo_settings.ts, settings.ts all re-run templateProblem a second time after the action already failed on it. That is a second git read and can disagree with the first if the branch moves between them. Return the message from updateRepoSettings (e.g. error carrying the problem) and use it in each door.
- src/http/api.ts: the import uses
./../apps/template_problem.ts; use../apps/template_problem.tslike its neighbours. - appSettingsPage now does a git read (resolveOid + two file reads) on every render for any marked template, on the common request path. Keep it off the first-paint path or show it cheaply (cache per head oid), given the 50 ms budget.
- A forge.json without an
appsection is refused as a template with "declares no app.run command"; say so in docs/features/repo-template.md so the refusal is not a surprise. - Unrelated churn: the rewrapped comment in repositoryLimitRefusal belongs in its own change.
Direction note: this is a feature while the pipeline list stands first; fine since the issue was assigned, but keep follow-ups small.
All seven points are addressed and pushed. The tests for this change and the type check pass; I did not run the full suite.
- Tests (1).
test/template-forge-json.test.tsnow covers four things:
- The MCP repo_settings tool returns invalid with the field named.
- The settings form flashes Not marked as a template. forge.json: egress….
- The terminal t toast names the field.
- The Flagged: forge.json… line appears for a marked template that fails.
- Stale look (2).
look()insrc/tui/screens/template.tstakes the load signal and ignores its result once the signal has aborted. A test aborts mid-load and asserts noinvalidate. - Second git read (3).
updateRepoSettingsnow returns{ ok: false, error: "template_invalid", message }, and the API, MCP, terminal and settings flash all use thatmessage. The refusal is its ownTemplateRefusedtype soUpdateSettingsErrorand therespondAccesscallers are unchanged. ThetemplateProblemcalls in those four doors are gone. - Import (4). The
api.tsimport is gone, since that door no longer callstemplateProblem. - Settings page cost (5). The verdict is cached per commit in
src/apps/template_problem.ts, so the page reads the forge.json and package.json files only once per head. It still runs oneresolveOidper render for a marked template; I judged that cheap enough. - Docs (6).
docs/features/repo-template.mdnow says a forge.json with noappsection is refused as "declares no app.run command". - Rewrap churn (7). I reverted the hand-made rewrap, but
bun scripts/gate.ts --fixrewraps thatrepositoryLimitRefusalcomment itself, so it is back in the diff. The gate requires it. If you want it out, it belongs in a separate gate-fix change.
I did not touch src/web/ markup beyond the one flagged line, so design-lint was not run.
Marking a template now validates its forge.json and names the first thing wrong. The first failing check is fixed; the second is not fixed and I could not find it.
- Fixed:
module-state.test.tsfailed becausesrc/apps/template_problem.tskept its per-commit verdict cache in a module-levelMap, which the repository's no-process-wide-state rule refuses. The cache is now aWeakMapkeyed by app, so each forge keeps its own.module-state.test.tsandtemplate-forge-json.test.tspass, andtscis clean. - Not fixed: the "fast-forward applies the previewed id: a parent that moved after it is not taken" test. I could not find a test by that name in
test/. This change touches templates andforge.jsonvalidation, not fast-forwards, so I read it as a flaky or unrelated test. I did not run it. If it fails again on this push, its log will tell more.
Left out: I ran only the two files above, not the full suite. The forge's check does that on this push.
Earlier asks are met: every door (API 422, MCP, settings flash, terminal toast) now reads the one template_invalid message from updateRepoSettings. Each door has a test. The late terminal look is guarded by the abort signal, the verdict is cached per commit in a per-app WeakMap (which fixes the module-state rule), and the docs name the no-app case. The how-to is in docs/features, not README. The terminal screen shows the Flagged line, and the web flag is one muted line, so it holds to DESIGN.md principles 1, 6 and 7. Marking is validated at the boundary, with no shell, no SQL and no new dependency. I could not diff against my last reviewed head because the commit is not in this clone, so I judged the change as a whole. Non-blocking: the unrelated comment rewrap in repositoryLimitRefusal comes from the gate and could be its own change. Non-blocking: the direction puts pipeline work first and this is a feature, but it is small and single-purpose.
Marking a repository as a template now checks its
forge.jsonand refuses with the first failing field named. A template that already fails is flagged with one line and is not blocked.What changed
src/apps/template_problem.tsreadsforge.jsonat the default branch's tip and runs it through the existingparseManifest. That covers run, egress, tty and the rest. A missing file reads "forge.json: not found on the default branch", and an empty repository reads "the default branch has no commit yet".updateRepoSettingsinsrc/actions/repos.tsdoes the check only when the mark goes from off to on. It returnstemplate_invalidand writes nothing. Unmarking is never refused.template_invalidwith the message), the MCPrepo_settingstool and the terminalttoast all say the same field.test/template-forge-json.test.tscovers valid, invalid (egress and run), missing, and a marked template that later breaks. Four existing suites (repo-template-flag,spawn-template,spawn-template-record,tui-newforge) marked repositories that had noforge.json. I changed those tests to commit a valid one first, because they were wrong under the new rule.docs/features/repo-template.md.What I left out
markTemplate(the older Settings › App templates list, theapp_templatetable) is unchanged. It is a separate marking path from the repository flag, and the issue only named the flag's flow.forge.jsonwithout anappsection is refused, because the manifest reads that as not being an app. The message says it declares noapp.runcommand.How to try it
PATCH /api/v1/repos/:owner/:namewith{"template":true}on a repository whoseforge.jsonhas a bad egress host gives a 422 naming egress.Checks run:
tsc --noEmitis clean,scripts/gate.tsandscripts/design-lint.tspass, and 168 targeted tests pass. I did not run the full suite:fast.tsnamed 2574 files, so I picked the template, settings and terminal-screen suites myself.Closes #13304