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

`forge new --template NAME` starts a forge from a template, listing templates when NAME is missing #13955

Merged opened this

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

Merged

forge new --template NAME now makes a forge from a template. When NAME is missing or unknown, it lists the templates and exits 2. tsc, the gate, test/cli-new-template.test.ts and test/cli-new.test.ts pass; I did not run the full suite or try it against a preview.

Notes

shipped production is serving it deploy 4adf612

opened this

forge new <name> --template NAME now makes a forge from a template. When NAME is missing or unknown, it lists the templates and exits 2. tsc, the gate, test/cli-new-template.test.ts and test/cli-new.test.ts pass; I did not run the full suite or try it against a preview.

What changed

  • Known NAME: it posts to POST /api/v1/forges, which runs spawnDoor, the same function the /forges/new page and the /templates buttons use. It then prints the claim link.
  • Missing or unknown NAME: it prints the templates from GET /api/v1/forges/templates and exits 2. Nothing is made.
  • Code: the command is in src/cli/commands/new_template.ts, with templates() and newForge() added to src/cli/api.ts. new.ts branches on --template, template is now a value flag in main.ts, and docs/CLI.md documents it.
  • Tests: test/cli-new-template.test.ts covers the three outcomes against a fake API, and the missing-NAME and unknown-NAME cases assert nothing is posted or made.

Left out

  • Repository templates: the list shows only the built-in templates (blank, starter), because the public templates endpoint returns only those. An owner/name repository template is still passed to the door and accepted if it is valid, but it is not listed.
  • Budget, apps, size and the other form fields: forge new --template only sets the name and template.
  • Forge name: the issue only mentions NAME, so I chose forge new <name> --template NAME. The forge's name is the first argument.
  • Ambiguous arguments: forge new --template kids reads kids as the template and lists, since no forge name was given.

Try it: forge new kids --template starter makes the forge and prints the link. forge new kids --template or forge new kids --template nope lists the templates.

🤖 Generated with Claude Code

Closes #13945

3 earlier comments · 2 events
commented

forge new <name> --template NAME now makes a forge from a template. When NAME is missing or unknown, it lists the templates and exits 2. tsc, the gate, test/cli-new-template.test.ts and test/cli-new.test.ts pass; I did not run the full suite or try it against a preview.

What changed

  • Known NAME: it posts to POST /api/v1/forges, which runs spawnDoor, the same function the /forges/new page and the /templates buttons use. It then prints the claim link.
  • Missing or unknown NAME: it prints the templates from GET /api/v1/forges/templates and exits 2. Nothing is made.
  • Code: the command is in src/cli/commands/new_template.ts, with templates() and newForge() added to src/cli/api.ts. new.ts branches on --template, template is now a value flag in main.ts, and docs/CLI.md documents it.
  • Tests: test/cli-new-template.test.ts covers the three outcomes against a fake API, and the missing-NAME and unknown-NAME cases assert nothing is posted or made.

Left out

  • Repository templates: the list shows only the built-in templates (blank, starter), because the public templates endpoint returns only those. An owner/name repository template is still passed to the door and accepted if it is valid, but it is not listed.
  • Budget, apps, size and the other form fields: forge new --template only sets the name and template.
  • Forge name: the issue only mentions NAME, so I chose forge new <name> --template NAME. The forge's name is the first argument.
  • Ambiguous arguments: forge new --template kids reads kids as the template and lists, since no forge name was given.

Try it: forge new kids --template starter makes the forge and prints the link. forge new kids --template or forge new kids --template nope lists the templates.

🤖 Generated with Claude Code

commented

forge new <name> --template NAME now starts a forge from a template. With no NAME, or one the forge doesn't know, it lists the templates and exits 2. A known NAME prints the claim link to send.

The failing check was a layout rule, not a behaviour bug. Every file in src/cli/commands/ must be a command in the table, and new_template.ts was only a helper. I moved it to src/cli/new_template.ts; commands/new.ts imports it from there.

test/cli-commands.test.ts and test/cli-new-template.test.ts pass, and tsc and scripts/gate.ts --fix are clean. I did not run the full suite.

The pull still needs a forge.json check; the forge runs it on this push.

  • What I left out: no new flags beyond --template.
  • How to try it: run forge new kids --template starter, or forge new kids --template to list the templates.

🤖 Generated with Claude Code

Changes requested — before the latest push

Works as the issue asks. I checked the door against the preview: the real unknown-template answer is a 404 with code unknown_template, which the command handles, and the three outcomes are tested. One change needed: the doc comment for newApp is now stranded above templates() because the two new methods were inserted between the comment and its function. Move templates() and newForge() above that comment (or after newApp) so newApp keeps its doc. Optional, not blocking: the 404 body already carries the template ids, so listing could reuse it instead of a second request, and a test for the missing forge name would cover that branch.

commented

forge new <name> --template NAME starts a forge from a template. With no NAME, or one the forge doesn't know, it lists the templates and exits 2. A known NAME prints the claim link to send.

Since the last push:

  • Doc comment: newApp's comment was stranded above templates(). I moved templates() and newForge() above it, so newApp has its doc again and templates() has its own.
  • Helper module: the template helper now lives at src/cli/new_template.ts, outside commands/, because commands/ holds one module per command.

tsc and scripts/gate.ts --fix are clean, and test/cli-new-template.test.ts (3 tests) passes. I did not run the full suite.

Not done, both optional in the review:

  • Template listing: it still makes a second request. Reusing the template ids from the 404 body would save that request.
  • Missing-name branch: it has no test yet.

To try it: forge new kids --template starter, or forge new kids --template to list the templates.

🤖 Generated with Claude Code

Changes requested — before the latest push

The command works against the real door: the preview's /api/v1/forges/templates returns blank and starter, and the three outcomes are tested. Two misses against the bar, fix both in one round.

  1. Untested behaviour. The missing-forge-name branch (forge new --template starter with no name, exit 2, nothing posted) has no test. Add one. The server-error and 401 exit mappings also have none; add at least the 401 to EXIT.notConfigured.
  2. No how-to under docs/features/. The new flag is documented only as a line in docs/CLI.md. Add docs/features/new-forge-from-cli.md (or extend new-forge-template.md) saying how to use forge new <name> --template NAME, the list-and-exit-2 behaviour, and the claim link.

Not blocking: the 404 body already has the ids, so the list could reuse it and skip a second request.

Ticks: boxes 1 and 2 are met. Box 3 is left until the missing-name branch has its test.

commented

forge new <name> --template NAME makes a forge from a template, through the same door as the page (POST /api/v1/forges), and prints the claim link.

  • Listing: with no NAME, or one the forge doesn't know (the door's 404 unknown_template), it lists the templates /templates offers and exits 2 without making anything.
  • Missing forge name: it says what to type and exits 2.
  • Errors: a 401 exits 3 (EXIT.notConfigured), 403, 409 and 422 exit 5 (EXIT.refused) with the forge's sentence, and anything else exits 1.

The command is in src/cli/new_template.ts, outside commands/, which holds one module per command. The two calls, templates() and newForge(), are in src/cli/api.ts, above newApp's doc comment.

What changed this round:

  • Tests: test/cli-new-template.test.ts now also covers a missing forge name (exit 2, nothing posted), a refused token (401, exit 3, nothing posted) and a server error (500, exit 1, the forge's sentence shown). All six tests pass.
  • How-to: docs/features/new-forge-template.md has a new section, "From the command line: forge new --template", with usage, the list-and-exit-2 cases, the claim link and the exit codes. It extends that how-to instead of adding a new page.

Not done: the list still makes a second request instead of reusing the template ids in the 404 body. The review marked this as not blocking, and the extra request only happens on a typo.

tsc and scripts/gate.ts --fix are clean. scripts/fast.ts named 125 test files, an estimated 10 minutes, over its 5-minute budget. I ran a subset instead: every test/cli-* file plus the features, feature-orphans, unused-exports, src-imports, words, tree, hollow, unreached and module-state checks, 287 passing. The forge's check runs the rest on this push.

To try it: forge new kids --template starter against the preview, forge new kids --template to see the list, and forge new --template starter for the missing-name message.

🤖 Generated with Claude Code

Approved

Earlier asks: (1) newApp doc comment stranded above templates() — met, templates()/newForge() now sit above it. (2) missing forge-name test — met, plus 401 and 500 tests. (3) how-to — met, extends docs/features/new-forge-template.md and README is untouched. The extra list request on a typo is left, which I had marked optional. The command goes through the same door as the page, validates at the boundary, escapes output with inert(), and has exit codes that match the docs. Next, non-blocking: (a) reuse the template ids in the unknown_template 404 body instead of a second request; (b) a test that a repository template owner/name is passed through to the door.

Sign in to join this conversation.

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs