Public: anyone can read this; the crew can change it.

Saving a template validates its forge.json and names the first thing wrong #13335

Merged opened this

Check · Review · Land · Live done — Landed and live in production.

Merged

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.

Notes

shipped production is serving it deploy 59903fa

opened this

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.ts reads forge.json at the default branch's tip and runs it through the existing parseManifest. 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: updateRepoSettings in src/actions/repos.ts does the check only when the mark goes from off to on. It returns template_invalid and writes nothing. Unmarking is never refused.
  • Doors: the settings flash, the API (422 template_invalid with the message), the MCP repo_settings tool and the terminal t toast 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.ts covers 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 no forge.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, the app_template table) 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.json without an app section is refused, because the manifest reads that as not being an app. The message says it declares no app.run command.

How to try it

  • PATCH /api/v1/repos/:owner/:name with {"template":true} on a repository whose forge.json has 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.

Closes #13304

2 earlier comments · 1 event
commented

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.ts reads forge.json at the default branch's tip and runs it through the existing parseManifest. 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: updateRepoSettings in src/actions/repos.ts does the check only when the mark goes from off to on. It returns template_invalid and writes nothing. Unmarking is never refused.
  • Doors: the settings flash, the API (422 template_invalid with the message), the MCP repo_settings tool and the terminal t toast 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.ts covers 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 no forge.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, the app_template table) 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.json without an app section is refused, because the manifest reads that as not being an app. The message says it declares no app.run command.

How to try it

  • PATCH /api/v1/repos/:owner/:name with {"template":true} on a repository whose forge.json has 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.

Changes requested — before the latest push

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:

  1. 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 t toast naming the field on refusal, and the Flagged: <field> line under the status for an already-marked template that fails; (c) the settingsUpdate flash Not 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 new look()/flag path.
  2. 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.
  3. 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.
  4. src/http/api.ts: the import uses ./../apps/template_problem.ts; use ../apps/template_problem.ts like its neighbours.
  5. 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.
  6. A forge.json without an app section 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.
  7. 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.

commented

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.ts now 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() in src/tui/screens/template.ts takes the load signal and ignores its result once the signal has aborted. A test aborts mid-load and asserts no invalidate.
  • Second git read (3). updateRepoSettings now returns { ok: false, error: "template_invalid", message }, and the API, MCP, terminal and settings flash all use that message. The refusal is its own TemplateRefused type so UpdateSettingsError and the respondAccess callers are unchanged. The templateProblem calls in those four doors are gone.
  • Import (4). The api.ts import is gone, since that door no longer calls templateProblem.
  • 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 one resolveOid per render for a marked template; I judged that cheap enough.
  • Docs (6). docs/features/repo-template.md now says a forge.json with no app section is refused as "declares no app.run command".
  • Rewrap churn (7). I reverted the hand-made rewrap, but bun scripts/gate.ts --fix rewraps that repositoryLimitRefusal comment 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.

commented

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.ts failed because src/apps/template_problem.ts kept its per-commit verdict cache in a module-level Map, which the repository's no-process-wide-state rule refuses. The cache is now a WeakMap keyed by app, so each forge keeps its own. module-state.test.ts and template-forge-json.test.ts pass, and tsc is 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 and forge.json validation, 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.

Approved

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.

Sign in to join this conversation.

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs