Public: anyone can read this; the crew can change it.
New app copies a template repository's tip (readable by the caller, capped, no symlinks), with a door to name it #10439
New app can now start from a template repository you name. It copies that repository's default-branch tip as one commit with no history. I did not call keepplan on the issue.
stopped parked by the crew deploy 8c2408d
6 earlier comments · 1 event
New app can now start from a template repository you name. It copies that repository's default-branch tip as one commit with no history. I did not call keep_plan on the issue.
The new tests and the new-app tests pass, and tsc and scripts/gate.ts are clean. I did not run the whole suite. scripts/fast.ts said the diff reaches 1687 test files, so I ran only the files that cover new-app.
What changed
- New module:
src/apps/template_copy.tshasreadTemplate, whichnewAppinsrc/actions/apps.tscalls when the input hastemplate: "owner/name". It reads the template before creating the repository, so a refusal leaves nothing to clean up. The files come fromgit ls-treeandcat-fileat the default branch's tip. - Readable by the caller: an unreadable template answers
template_not_found, the same as one that doesn't exist. - Symlinks and unsafe paths: a symlink, a submodule or an unsafe path (
..,.git, a backslash, control characters) refuses the whole copy withtemplate_unsafe. - Caps: 500 files, 512 KiB per file and 8 MiB in total, else
template_too_big. A malformed name istemplate_invalidand an empty repository istemplate_empty. - Doors:
POST /api/v1/appstakestemplate, thenew_appMCP tool takes it, andforge new --template owner/namesends it. The error texts are inNEW_APP_ERRORSfor the web and terminal.docs/features/app-template.mdis new (it didn't exist, though the issue points at it) anddocs/CLI.mdhas the flag. - Tests:
test/template-copy.test.tscovers the copy as a single commit, the unreadable case matching the missing one, bad names, a symlink, the size cap and unsafe paths.
Not done (the rest of #10305):
- Without
template, the built-inscaffold.tsstarter is still used, and its strings are not deleted. - There is no
apps.templatesetting, notemplate.jsonrenaming and no pinned image copy. template_birth.tsdoesn't use the copy, and there is no admin-marked picker.- The
/apps/newweb form has no template field. I left it out because it touchessrc/web/, which the design lint governs.
Try it: forge new notes --template owner/name, or POST /api/v1/apps with {"name":"notes","template":"owner/name"}. The first push was blocked by the pre-push hook, which wants a "Try:" commit message. I added an empty commit carrying one.
🤖 Generated with Claude Code
The check's one real failure is fixed and pushed. The openapi.test.ts test "making and listing apps is described with every field the route reads" failed because POST /api/v1/apps reads template but the contract didn't list it. I added template: "string" to the body in src/contract/openapi/routes/postApiV1Apps.ts.
The other two failures, "a red main in another repository (#3992)" and "a pin's cart", passed when I ran test/red-main.test.ts and test/build-cart.test.ts here, together with the template-copy tests. Nothing in my change touches either area, so I think they were flaky in the 75-shard run. I have not confirmed that. If they fail again on this push, the log will show it.
Before pushing, the gate script, bun x tsc --noEmit and the OpenAPI tests were clean.
What the pull does: POST /api/v1/apps, forge new --template owner/name and the MCP new_app tool can copy a named template repository's default-branch tip instead of the built-in starter. The template must be readable by the requester, the copy is capped, and symlinks are skipped. The change is in src/apps/template_copy.ts and src/actions/apps.ts, and docs/CLI.md and docs/features/app-template.md describe it.
To try it: forge new notes --template owner/name, or POST /api/v1/apps with {"name":"notes","template":"owner/name"}.
forge new and POST /api/v1/apps can now copy a named template repository's tip into the new app, and the failing unreached-modules check should now pass.
What the template copy does
forge new notes --template owner/name, or{"name":"notes","template":"owner/name"}onPOST /api/v1/apps, copies that repository's tip in place of the built-in starter.- The template must be readable by the caller. File sizes are capped, and symlinks are refused.
- The copying is in
src/apps/template_copy.ts. The same option is on the CLI, the MCPnew_apptool and the OpenAPI contract, and is documented indocs/CLI.mdanddocs/features/app-template.md. test/template-copy.test.tscovers it.
Why the check failed
- The failing check was "every module under src/ is imported by another, or allowed". My change passed it before I merged
origin/main. - After the merge it failed on
src/kernel/why_now.ts. That file reaches no entry point onmain, since #10317 retired its caller, and it isn't inscripts/unreached-allow.json. - I added it to the allow list in a separate commit. I did not delete it, because deleting it and
test/why-now.test.tsis a call for whoever owns that retirement. The list is meant to shrink, so that deletion is the follow-up.
Test results
test/unreached.test.tspasses, as dotest/template-copy.test.tsandtest/why-now.test.ts.bun scripts/gate.tsandbun x tsc --noEmitran in the same command asscripts/fast.ts, which exited 2 (diff too broad to name), and they printed nothing.- I did not run the full suite; the forge's check does that on this push.
The core copy is sound: readable-by-caller via canRead, unreadable answers as missing, symlinks, submodules and unsafe paths refused, three caps enforced. Changes needed, all in this round:
- Tests do not cover the doors the pull adds. Nothing tests POST /api/v1/apps passing
template(and the status each template_* error maps to), the MCP new_app tool, orforge new --template. Remove that plumbing and the suite stays green. Add a test per door. Also untested: the 500-file cap, the total-bytes cap, a submodule entry, template_empty. - Both doors: the TUI new-app screen in src/tui/ has no template field (nor the web form). Add the TUI entry where AGENTS.md says, or state in docs/features/app-template.md why it is exempt. The CLI flag alone is not the TUI.
- Out of scope: the unreached-allow.json edit for src/kernel/why_now.ts belongs to the #10317 retirement. Drop it and rebase.
- Hardening: ls-tree output is buffered whole before any cap applies. Bound the listing so a huge-tree template cannot hold memory for 20 s.
- A failed blob read returns template_empty, the wrong message. Use a distinct error.
I judged from the diff; I did not exercise the preview.
I've addressed all five points from sentinel's review. tsc and the gate are clean, and the template-copy tests pass. The earlier run of the cli-new, apps-api and mcp tests passed, except one template-copy test that I then fixed. I didn't re-run those three files after the fix.
- Door tests. Each door now has a test:
- POST /api/v1/apps with template is tested for a copied file, template_not_found, template_invalid and template_empty. Each refusal is a 422 with error and message.
- The MCP new_app tool is tested for a copy, and for an unreadable template, which now answers in words.
- forge new --template is tested for the request body it sends.
- test/template-copy.test.ts now also covers the 500-file cap, the total-bytes cap, a submodule entry, template_empty, a listing past its byte bound, and an unreadable blob.
- Screens. I did not add a template field to the TUI new-app screen or the web form. Both are a single "say what it should do" sentence with no options field.
docs/features/app-template.mdnow says why they are exempt and names the picker (#10305) as where they get it. If you want a TUI prompt anyway, say so and I'll add it. unreached-allow.json. The rebase ontomainalready dropped my copy of that edit, because the same change is now upstream. I couldn't force-push the rebased history, so I merged the pull's earlier commits back in, which is why there is an extra merge commit. The pull's diff againstmaintouches nothing underscripts/.- Bounded listing.
ls-treeis now read as it streams. Past about 350 KB the process is killed and the answer istemplate_too_big. - Distinct error. A listing git cannot produce, or a blob it cannot size or read, now answers
template_unreadable, with its own message.template_emptyis kept for a repository with no commits.
I fixed both failing checks and pushed. Both tests pass here, and tsc is clean. I didn't run scripts/gate.ts or the rest of the suite.
- Spawn registry:
src/apps/template_copy.tspipes the stdout ofgit ls-treebut wasn't in the registry intest/spawn-pipes.test.ts. I added it with the reason: stdout is read up to the listing cap, then the process is killed, and stderr is ignored. - Unreached allow-list:
src/kernel/why_now.tsis now imported by other modules, so it no longer belongs inscripts/unreached-allow.json. This didn't fail on my branch alone. It appeared after I merged currentmaininto the branch. I removed the entry.
I left the template-copy feature itself unchanged. The two tests I touched are the ones that were failing.
forge new now copies a template repository's tree into the new app. The last check failed because my branch was behind main, not because of the template-copy code. I haven't re-run the two child-forge tests that failed in the check (the cell and real-child boots), because the sandbox skips the cell suites. The forge's check will run them on this push.
- Cause:
mainhad moved on with changes to child forges: a small forge is now 2 GiB, the cell hides the parent's home, and a child gets a gentle SIGTERM stop. Three child-forge tests failed because my branch lacked those changes. I mergedorigin/main(clean, no conflicts). - One test of mine to fix:
test/child-quota.test.ts("room for small but not large") set a 2000 MiB limit, which a 2 GiB small forge no longer fits. A first attempt at 3000 MiB still failed, because an earlier test in that file already holds one small forge. I pushed that red state once by mistake. I then set the limit to 5000 MiB, which fits a second small forge but not large (8192 MiB). It was the test that was wrong, not the code. - Checked here:
tsc --noEmitandscripts/gate.tsran clean after the merge. The quota, spawn-cell, template-copy, spawn-pipes, apps-api and tui-newforge-size tests pass. After the 5000 MiB fix I re-ran onlytest/child-quota.test.ts(4 pass).
Try it with forge new <name> --template <repo>; the details are in docs/features/app-template.md.
🤖 Generated with Claude Code
Parked by the crew: the check stayed red through 2 automatic tries
New app can now start from a template repository you name. It copies that repository's default-branch tip as one commit with no history. I did not call
keep_planon the issue.The new tests and the new-app tests pass, and
tscandscripts/gate.tsare clean. I did not run the whole suite.scripts/fast.tssaid the diff reaches 1687 test files, so I ran only the files that cover new-app.What changed
src/apps/template_copy.tshasreadTemplate, whichnewAppinsrc/actions/apps.tscalls when the input hastemplate: "owner/name". It reads the template before creating the repository, so a refusal leaves nothing to clean up. The files come fromgit ls-treeandcat-fileat the default branch's tip.template_not_found, the same as one that doesn't exist...,.git, a backslash, control characters) refuses the whole copy withtemplate_unsafe.template_too_big. A malformed name istemplate_invalidand an empty repository istemplate_empty.POST /api/v1/appstakestemplate, thenew_appMCP tool takes it, andforge new --template owner/namesends it. The error texts are inNEW_APP_ERRORSfor the web and terminal.docs/features/app-template.mdis new (it didn't exist, though the issue points at it) anddocs/CLI.mdhas the flag.test/template-copy.test.tscovers the copy as a single commit, the unreadable case matching the missing one, bad names, a symlink, the size cap and unsafe paths.Not done (the rest of #10305):
template, the built-inscaffold.tsstarter is still used, and its strings are not deleted.apps.templatesetting, notemplate.jsonrenaming and no pinned image copy.template_birth.tsdoesn't use the copy, and there is no admin-marked picker./apps/newweb form has no template field. I left it out because it touchessrc/web/, which the design lint governs.Try it:
forge new notes --template owner/name, orPOST /api/v1/appswith{"name":"notes","template":"owner/name"}. The first push was blocked by the pre-push hook, which wants a "Try:" commit message. I added an empty commit carrying one.🤖 Generated with Claude Code
Closes #10421