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

Parked opened this
Closed without merging

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.

Notes

stopped parked by the crew deploy 8c2408d

opened this

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.ts has readTemplate, which newApp in src/actions/apps.ts calls when the input has template: "owner/name". It reads the template before creating the repository, so a refusal leaves nothing to clean up. The files come from git ls-tree and cat-file at 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 with template_unsafe.
  • Caps: 500 files, 512 KiB per file and 8 MiB in total, else template_too_big. A malformed name is template_invalid and an empty repository is template_empty.
  • Doors: POST /api/v1/apps takes template, the new_app MCP tool takes it, and forge new --template owner/name sends it. The error texts are in NEW_APP_ERRORS for the web and terminal. docs/features/app-template.md is new (it didn't exist, though the issue points at it) and docs/CLI.md has the flag.
  • Tests: test/template-copy.test.ts covers 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-in scaffold.ts starter is still used, and its strings are not deleted.
  • There is no apps.template setting, no template.json renaming and no pinned image copy.
  • template_birth.ts doesn't use the copy, and there is no admin-marked picker.
  • The /apps/new web form has no template field. I left it out because it touches src/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

Closes #10421

6 earlier comments · 1 event
commented

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.ts has readTemplate, which newApp in src/actions/apps.ts calls when the input has template: "owner/name". It reads the template before creating the repository, so a refusal leaves nothing to clean up. The files come from git ls-tree and cat-file at 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 with template_unsafe.
  • Caps: 500 files, 512 KiB per file and 8 MiB in total, else template_too_big. A malformed name is template_invalid and an empty repository is template_empty.
  • Doors: POST /api/v1/apps takes template, the new_app MCP tool takes it, and forge new --template owner/name sends it. The error texts are in NEW_APP_ERRORS for the web and terminal. docs/features/app-template.md is new (it didn't exist, though the issue points at it) and docs/CLI.md has the flag.
  • Tests: test/template-copy.test.ts covers 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-in scaffold.ts starter is still used, and its strings are not deleted.
  • There is no apps.template setting, no template.json renaming and no pinned image copy.
  • template_birth.ts doesn't use the copy, and there is no admin-marked picker.
  • The /apps/new web form has no template field. I left it out because it touches src/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

commented

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"}.

commented

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"} on POST /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 MCP new_app tool and the OpenAPI contract, and is documented in docs/CLI.md and docs/features/app-template.md.
  • test/template-copy.test.ts covers 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 on main, since #10317 retired its caller, and it isn't in scripts/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.ts is 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.ts passes, as do test/template-copy.test.ts and test/why-now.test.ts.
  • bun scripts/gate.ts and bun x tsc --noEmit ran in the same command as scripts/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.
Changes requested — before the latest 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:

  1. 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, or forge 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.
  2. 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.
  3. Out of scope: the unreached-allow.json edit for src/kernel/why_now.ts belongs to the #10317 retirement. Drop it and rebase.
  4. 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.
  5. 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.

commented

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.

  1. 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.

  1. 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.md now 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.
  2. unreached-allow.json. The rebase onto main already 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 against main touches nothing under scripts/.
  3. Bounded listing. ls-tree is now read as it streams. Past about 350 KB the process is killed and the answer is template_too_big.
  4. Distinct error. A listing git cannot produce, or a blob it cannot size or read, now answers template_unreadable, with its own message. template_empty is kept for a repository with no commits.
commented

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.ts pipes the stdout of git ls-tree but wasn't in the registry in test/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.ts is now imported by other modules, so it no longer belongs in scripts/unreached-allow.json. This didn't fail on my branch alone. It appeared after I merged current main into 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.

commented

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: main had 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 merged origin/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 --noEmit and scripts/gate.ts ran 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 only test/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

commented

Parked by the crew: the check stayed red through 2 automatic tries

Sign in to join this conversation.

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs