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

New app picks from admin-marked template repositories, and a repository may hold several templates #10458

Parked opened this
Closed without merging

New app can now start from a template repository that an admin has marked, and a repository can hold several templates. The new test file and the related suites pass (253 tests), and bun scripts/gate.ts, tsc and the design lint are clean.

Notes

stopped parked by the crew deploy 455165d

opened this

New app can now start from a template repository that an admin has marked, and a repository can hold several templates. The new test file and the related suites pass (253 tests), and bun scripts/gate.ts, tsc and the design lint are clean. bun scripts/fast.ts found the diff too broad to name tests, so I ran the New app, event-audience, OpenAPI and MCP suites by hand. I did not run the full suite; the forge's check does that on push. I did not try the pages against a running preview.

What changed

  • Marking: admins (a person, not an agent) edit "Template repositories" at the foot of /apps/new, one owner/repo per line. If an admin never sets it, the list is trevato/app-template. Each change is recorded in forge_setting_change and emitted as an app_templates.changed event. That event kind is listed as admin-only in core/event_audience.ts.
  • What counts as a template: a marked repository is one template if its root holds TEMPLATE.md and template.json. Otherwise each top-level folder holding both is its own template, with id owner/repo/folder.
  • Picker: /apps/new shows "Start from" when you are offered more than one template. It shows a single line when you are offered exactly one. With none, the starter app is used. POST /api/v1/apps and the new_app MCP tool take template, and the OpenAPI route lists it and its two refusals.
  • Copying: newApp fills template.json's literals and copies the files into the new repository. It never runs anything, so a template's new.mjs is copied as a plain file. TEMPLATE.md, template.json, .git, symlinks and submodules are left out.
  • Read check and caps: a template is offered and copied only if the caller can read its repository. Anything else answers no_such_template. The caps are 20 marked repositories, 30 folders per repository, 200 files, 256 KB per file, 2 MB in all, and 8 levels deep. Over a cap, the app is refused with template_too_large before any repository is created.
  • Where: the logic is in src/apps/templates.ts, with test/app-templates.test.ts and docs/features/app-template.md.

Choices I made

  • docs/features/app-template.md did not exist, so I wrote it from the issue. The template.json format is mine: {title, description, literals: {"<text>": "name"|"description"}}. If the design notes meant something different, that is the one thing to change.

Left out

  • Admin marking is only the web form. There is no API route, MCP tool or terminal screen for it.
  • Templates are not cached. Each page load reads the marked repositories' trees, which is cheap with the 20-repository cap but not free.
  • Template template.json literals only substitute the app's name and description.

Try it: as an admin, open /apps/new, add a repository under Template repositories, then choose it under Start from.

Closes #10437

3 earlier comments
commented

New app can now start from a template repository that an admin has marked, and a repository can hold several templates. The new test file and the related suites pass (253 tests), and bun scripts/gate.ts, tsc and the design lint are clean. bun scripts/fast.ts found the diff too broad to name tests, so I ran the New app, event-audience, OpenAPI and MCP suites by hand. I did not run the full suite; the forge's check does that on push. I did not try the pages against a running preview.

What changed

  • Marking: admins (a person, not an agent) edit "Template repositories" at the foot of /apps/new, one owner/repo per line. If an admin never sets it, the list is trevato/app-template. Each change is recorded in forge_setting_change and emitted as an app_templates.changed event. That event kind is listed as admin-only in core/event_audience.ts.
  • What counts as a template: a marked repository is one template if its root holds TEMPLATE.md and template.json. Otherwise each top-level folder holding both is its own template, with id owner/repo/folder.
  • Picker: /apps/new shows "Start from" when you are offered more than one template. It shows a single line when you are offered exactly one. With none, the starter app is used. POST /api/v1/apps and the new_app MCP tool take template, and the OpenAPI route lists it and its two refusals.
  • Copying: newApp fills template.json's literals and copies the files into the new repository. It never runs anything, so a template's new.mjs is copied as a plain file. TEMPLATE.md, template.json, .git, symlinks and submodules are left out.
  • Read check and caps: a template is offered and copied only if the caller can read its repository. Anything else answers no_such_template. The caps are 20 marked repositories, 30 folders per repository, 200 files, 256 KB per file, 2 MB in all, and 8 levels deep. Over a cap, the app is refused with template_too_large before any repository is created.
  • Where: the logic is in src/apps/templates.ts, with test/app-templates.test.ts and docs/features/app-template.md.

Choices I made

  • docs/features/app-template.md did not exist, so I wrote it from the issue. The template.json format is mine: {title, description, literals: {"<text>": "name"|"description"}}. If the design notes meant something different, that is the one thing to change.

Left out

  • Admin marking is only the web form. There is no API route, MCP tool or terminal screen for it.
  • Templates are not cached. Each page load reads the marked repositories' trees, which is cheap with the 20-repository cap but not free.
  • Template template.json literals only substitute the app's name and description.

Try it: as an admin, open /apps/new, add a repository under Template repositories, then choose it under Start from.

commented

The new-app form's template picker is unchanged. I fixed one of the three failing checks and pushed (9cb1a0d52); the other two I couldn't reproduce.

  • "every module under src/ is imported by another, or allowed": this one failed after I merged current main. main retired the gate's direction in 54dacba00, which left src/kernel/why_now.ts imported by nothing, though test/why-now.test.ts still tests it. I added it to scripts/unreached-allow.json. Deleting it, or deleting its test too, would be a cleaner follow-up for whoever owns that retirement.
  • "a repository name with markup in it is escaped in the select, never raw": it passes here, both on my branch before the merge and after it. I changed nothing for it.
  • "the screen shows the share, the budgets…": it lives in test/tui-crawlers.test.ts, which also passes here before and after the merge. I changed nothing for it. These two are probably order-dependent or flaky in the sharded run. If either fails again, the new log should say.

After the merge and the allow-list entry, test/unreached.test.ts, test/feed-composer-language.test.ts, test/tui-crawlers.test.ts and test/app-templates.test.ts pass (16 tests), and bun x tsc --noEmit is clean. I did not run the full suite; the forge's check will.

commented

The failing check is fixed and pushed. The unreached test passes locally and bun x tsc --noEmit printed nothing. I didn't run the rest of the suite; the forge's check does that on this push.

The cause was that main deleted src/kernel/why_now.ts, so it no longer counted as unreached. The branch's earlier fix, 9cb1a0d52, had added it to scripts/unreached-allow.json. After I merged the new main, the "allowed module that has become reached leaves the list" test failed on that stale entry.

I merged origin/main into the branch and removed the src/kernel/why_now.ts entry from the list.

This is only a fix to the allow-list; nothing else in the pull changed.

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