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

/templates says what each template holds before you start from it: its top files and what its forge.json runs #13876

Merged opened this

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

Merged

/templates now shows what each template holds, under its row and Start button. Starter app: it lists its top-level files and the run and check lines from its forge.json. The run line is app.run, and the check line is check.run.

Notes

shipped production is serving it deploy 4adf612

opened this

/templates now shows what each template holds, under its row and Start button.

  • Starter app: it lists its top-level files and the run and check lines from its forge.json. The run line is app.run, and the check line is check.run. A flat run or check string is read as well.
  • Template repositories: these are read at their default branch. Files are cut at 12, followed by "and N more", and folders come first. The run and check lines are shown in <code>, escaped.
  • Blank: it says "Holds no files."
  • Unreadable repositories: a repository with no readable default branch, or no forge.json, still lists. A repository with no readable branch says "contents not available". One with no forge.json shows its files and no run or check lines.
  • Caching: the new module src/spawn/template_holds.ts keeps each template's result in memory for 60 seconds, so the page does not read git on every request. The cache is per process and is not shared across restarts.

I ran test/templates-page.test.ts and the TUI and template-page tests (all pass), plus tsc and the design lint. I did not run the full suite. templatesPage is now async. The New forge picker still calls templateRows without the new argument, so it is unchanged.

The new tests are in test/templates-page.test.ts. They cover:

  • the starter's files and its run and check lines;
  • blank's sentence;
  • a 14-file repository showing "and 3 more", with its run and check lines;
  • a repository with no commits showing "contents not available".

The pre-push hook refused my first push because the commit message had no "Try:" line, so I added one.

Closes #13855

7 earlier comments · 1 event
commented

/templates now shows what each template holds, under its row and Start button.

  • Starter app: it lists its top-level files and the run and check lines from its forge.json. The run line is app.run, and the check line is check.run. A flat run or check string is read as well.
  • Template repositories: these are read at their default branch. Files are cut at 12, followed by "and N more", and folders come first. The run and check lines are shown in <code>, escaped.
  • Blank: it says "Holds no files."
  • Unreadable repositories: a repository with no readable default branch, or no forge.json, still lists. A repository with no readable branch says "contents not available". One with no forge.json shows its files and no run or check lines.
  • Caching: the new module src/spawn/template_holds.ts keeps each template's result in memory for 60 seconds, so the page does not read git on every request. The cache is per process and is not shared across restarts.

I ran test/templates-page.test.ts and the TUI and template-page tests (all pass), plus tsc and the design lint. I did not run the full suite. templatesPage is now async. The New forge picker still calls templateRows without the new argument, so it is unchanged.

The new tests are in test/templates-page.test.ts. They cover:

  • the starter's files and its run and check lines;
  • blank's sentence;
  • a 14-file repository showing "and 3 more", with its run and check lines;
  • a repository with no commits showing "contents not available".

The pre-push hook refused my first push because the commit message had no "Try:" line, so I added one.

commented

<!-- look-pages d79dff5b23dd --> Look pages for d79dff5, from the gate:

  • look pages (none): this pull changes src/web/pages/templates.ts but the forge could not trace the route of /settings/security/controls (an inline or wrapped handler), so it could not infer a page; the reviewer decides. A "Looks: <path>" line naming the nearest page, or a "No look: <why>" line (10+ characters), says it
commented

The gate now exits 0 locally. I pushed a new commit, 89536530c, so the forge will re-run the check on it. I haven't seen that run's verdict.

The failure was the "both doors" rule: this pull adds src/spawn/template_holds.ts but no terminal screen and no docs/features/ how-to. I added no code and no screen. The new commit is empty and its message carries the gate lines:

  • No door: the holds are read-only detail on the /templates page. The terminal's app_templates screen lists the same templates, and showing the holds there too is left for a follow-up.
  • Looks: /templates: the gate prints a warning that /templates is not a page of app.looks in forge.json. The gate exits 0 anyway, so it is advisory. If it blocks, a No look: <why> line in a new commit should clear it.

What the pull does: /templates now shows each template's top files and its run and check lines. The code is in src/spawn/template_holds.ts and src/web/pages/templates.ts, with tests in test/templates-page.test.ts.

How to try it: open /templates on the preview and read the files and run line under Starter app.

commented

<!-- look-pages 89536530cfff --> Look pages for 8953653, from the gate:

  • look pages (none): "Looks: /templates" is not a page of app.looks in forge.json; this pull changes src/web/pages/templates.ts but the forge could not trace the route of /settings/security/controls (an inline or wrapped handler), so it could not infer a page; the reviewer decides. A "Looks: <path>" line naming the nearest page, or a "No look: <why>" line (10+ characters), says it
commented

I fixed both failing tests and pushed 91550d185. Locally, tsc is clean and test/templates-page.test.ts, test/module-state.test.ts and test/unused-exports.test.ts pass. The full suite is not run here, so the forge's check on the new push is the real verdict.

Why it failed: src/spawn/template_holds.ts kept a module-level Map as a one-minute cache of what each template holds. That tripped the process-wide state test. Its test-only forgetHolds export had no caller in src/, which tripped the dead-code test.

What changed:

  • The cache and forgetHolds are gone, so /templates reads each template's holds on every request. A template repository now costs a git tree read per request instead of one per minute. I judged that cheap enough and have not timed it.
  • templateHolds no longer takes a now argument.
  • The test no longer calls forgetHolds.

Look-pages warning: scripts/gate.ts still prints a warning that it can't trace the route for the /templates page. The new commit message carries a No look: line for it. The warning did not fail the gate earlier.

Not done: the earlier No door: line stands. There is still no terminal screen for the holds, and I left that for a follow-up.

Changes requested — before the latest push

Changes needed, in one round:

  1. FIRST: both doors. The terminal's app_templates screen (src/tui/) lists the same templates but shows no holds, and there is no docs/features/<name>.md how-to. 'No door' in a commit message is not an exemption; add the holds to the TUI screen (reusing templateHolds) and write the how-to (not in README).
  2. Box 1 says 'cached with the page'. The cache was dropped, so every /templates request, signed-out included, does a git tree read plus a forge.json blob read per template repository. Cache with the page in a way the module-state test accepts (e.g. state on the app object, or carried in the template list read), invalidated by the tip.
  3. Design: the facts are hand-rolled 'Files:/run:/check:' paragraphs. Per principle 7 a fact is a dl row; use dl rows with the existing muted/small tokens. Principle 8: 'contents not available' should read as a sentence ('Contents not available.').
  4. Clean: holdsView took over templateRows' doc comment (templates.ts line 22); the original is now orphaned. holdsView is exported with no reason to be. Also the template_holds.ts header comment has a stray wrap.
  5. Tests: the starter test has a redundant regex assertion and a '.replace("&&","&amp;&amp;")' on a literal that should just be written escaped. The 'cannot be read' test depends on a pre-seeded tess/open-kit fixture; create the unreadable repo in the test so it is self-evident. Add a no-forge.json repo case.
  6. Looks: the gate could not trace a page; add a Looks/No look line that names /templates properly.

Boxes 2, 3, 4 are met; box 1 is not (no caching).

commented

All six points are addressed on the branch and pushed as d38ebedfd. Locally the gate and tsc are clean and design-lint passes. These pass:

  • test/templates-page.test.ts
  • test/tui-app-templates.test.ts
  • test/module-state.test.ts
  • test/unused-exports.test.ts
  • test/preview-looks.test.ts

I did not run the full suite; the forge's check does that on this push.

  1. Both doors.
    • Terminal: the App templates screen now shows Files:, Run: and Check: under the cursor, from the same templateHolds the page uses. A template that can't be read shows "Contents not available."
    • How-to: docs/features/template-holds.md is new.
    • Commit message: the earlier "No door" line no longer applies.
  2. Caching. Holds are kept per app in a WeakMap, keyed by the default-branch tip. A request costs one ref read, and the tree and forge.json are read again only when the tip moves. The module-state test accepts this. A test checks that the same tip returns the same object and that a new commit shows up.
  3. Design. Facts are dl.status-rows with Files, Run and Check rows, using the existing small and muted classes. The unreadable message is now "Contents not available."
  4. Clean. The templateRows doc comment is restored and holdsView has its own, and holdsView is no longer exported. The header comment in template_holds.ts is rewrapped.
  5. Tests.
    • Starter: it asserts the dl rows with the escaped &amp;&amp; written literally; the redundant regex is gone.
    • Repo cases: each builds its own repository. The three cases are a repository with no forge.json, a repository with no commits, and one with many files. The test no longer depends on the tess/open-kit fixture.
  6. Looks. /templates was not one of app.looks, so a Looks: line alone could not name it. I added /templates to app.looks in forge.json so the preview seeds that page, and the commit carries Looks: /templates. The look-pages gate no longer warns.

The desk hold says production is rolling and changes to it should wait. This change touches only /templates, the terminal screen and forge.json looks. The branch is a pull, not a merge to main, so I pushed it and left the merge timing to you.

commented

/templates now lists what each template holds, and I've pushed a fix for the failures the check reported. That fix is two small changes:

  • forge.json: I removed /templates from app.looks. An earlier commit on this branch had added it, but test/forge-looks.test.ts keeps /templates on its not-a-page list, so the two disagreed.
  • docs/features/README.md: I added the missing row for template-holds.md. This fixes both feature-note tests, the orphan check and the one-row-per-note check.

The earlier commits add three rows under each template's name on /templates: its top-level files (at most 12, then "and N more"), its run line and its check line. A row that the template's forge.json doesn't say is left out. The rows are read per request, with no process-wide cache, and they also show in the terminal screen. The how-to is docs/features/template-holds.md. I did not give /templates a picture in app.looks.

These tests pass locally: the looks, feature-orphans, behaviors-rule, displays and idle-preview files, test/templates-page.test.ts and test/tui-app-templates.test.ts. The gate and tsc --noEmit are clean.

Two of the six reported failures I did not trace to a cause. The /displays and idle-preview tests failed in the check but pass here. The idle-preview run logged denied outbound connections to *.forge.test hosts, which is the sandbox blocking them. The behaviors-rule failure was already red on main in the check log, so it isn't counted against this pull. It passes locally.

To try it, open /templates and read the rows under each template's name.

commented

The "pipeline first" gate failed because this pull adds a feature without changing the pipeline. It should pass now: I added an empty commit carrying a Direction: line, and bun scripts/gate.ts passes locally. The forge's check hasn't run on it yet.

The line reads: issue 13855 asks /templates to say what each template holds, a reader-facing fix that does not wait on a pipeline item.

Earlier, my forge.json edit (adding /templates to app.looks) happened to count as a pipeline change. I reverted it because test/forge-looks.test.ts requires /templates to stay out of that list. A Direction: line is therefore the honest route, since no pipeline change belongs in this pull. I did not run tsc or the tests again, since this commit changes no files.

The pull still does what it did before. /templates shows each template's top-level files, its run line and its check line, and the same rows appear in the terminal screen. A row the template's forge.json doesn't say is left out. To try it, open /templates.

Approved

Earlier asks are met: the terminal screen shows Files/Run/Check, docs/features/template-holds.md exists and README.md is untouched, the cache is a per-app WeakMap keyed by the branch tip, and facts are dl rows in muted small type. The preview shows starter files, run and check lines, blank saying it holds no files, and a marked template repo listing. Next two things: (1) Non-blanking: the TUI screen hard-codes "Contents not available." where the page uses HOLDS_NONE; use the constant. (2) Non-blocking: templateHolds is awaited in parallel for each row; cap the number of concurrent git reads if the template list grows. Direction: this is a reader-facing fix that does not wait on pipeline items, and the commit carries a Direction line saying so.

Sign in to join this conversation.

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs