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

A template's page says what a new forge gets: its apps, their crew roles and its budget, in plain words #13325

Merged opened this

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

Merged

scout/forge:scout/13303-a-template-s-page-says-what-a-new-forge → main 3 commits fork 6 threads · 6 unresolved

  • Merged. scout/13303-a-template-s-page-says-what-a-new-forge was merged into main as 7104538.

Review

Sign in to review this change.
7 files changed +175 −14
docs/features/packs.md +3
@@ -34,3 +34,6 @@ The seeded repo lists are the owner's and are not checked against a forge here:
3434
3535 ## A source may not point inside (#11971)
3636 Before a pack's source is cloned, `src/packs/source_guard.ts` resolves its host and refuses it when any answer is loopback, private, link-local, unique-local, CGNAT/tailnet or unspecified (the list in `src/kernel/outbound.ts`, the forge's one). Git then dials the address that was judged and follows no redirect. Only port 443 is allowed, unless the forge itself is the source. `parsePack` drops an internal address literal at once; the port rule is the guard's alone, because only it knows the forge's own address. Every deploy path runs the guard on the address the pack names, even when a test clones from elsewhere.
37
38 ## What a new forge gets (#13303)
39 A `pack.json` pack's page (`/packs/<name>`), the terminal's pack screen and the MCP `templates` tool (its `packs` list, the same as `GET /api/v1/forges/templates`) say what a forge made from it gets: the apps it creates, each crew member's roles and per-run budget. Anything the pack does not state reads "not stated". Code: `src/packs/facts.ts`; test: `test/pack-facts.test.ts`.
src/http/mcp/tools/templates.ts +1 −1
@@ -3,7 +3,7 @@ import { good, type Tool } from "../shared.ts";
33
44 export const tool: Tool = {
55 name: "templates",
6 doc: "the templates a child forge may start from (`blank` first, the default), each with id, title, one sentence and source; pass an id as `spawn`'s `template`; so may the `owner/name` of a repository marked as a template",
6 doc: "the templates a child forge may start from (`blank` first, the default), each with id, title, one sentence and source, and `packs` (apps, crew roles, budget, \"not stated\" if the pack is silent); pass an id as `spawn`'s `template`; so may the `owner/name` of a repository marked as a template",
77 description: "The templates a child forge may start from.",
88 inputSchema: { type: "object", properties: {} },
99 writes: false,
src/packs/facts.ts added +43
@@ -0,0 +1,43 @@
1 /**
2 * What a forge made from a pack gets, in plain words: its apps, the crew each seat holds
3 * and what each may spend. Read from the pack itself; a thing the pack does not say is
4 * "not stated", never guessed. One place, so the page, the terminal and the MCP agree.
5 */
6
7 import type { Pack } from "./pack.ts";
8
9 export const NOT_STATED = "not stated";
10
11 export interface PackFacts {
12 readonly name: string;
13 readonly title: string;
14 readonly apps: readonly { readonly name: string; readonly says: string; readonly source: string }[];
15 readonly crew: readonly { readonly name: string; readonly roles: readonly string[]; readonly budget: string; readonly brief: string }[];
16 }
17
18 const dollars = (n: number): string => `$${Number.isInteger(n) ? n : n.toFixed(2)} a run`;
19
20 export function packFacts(p: Pack): PackFacts {
21 const crew = p.crew.map((c) => ({
22 name: c.username,
23 roles: c.roles,
24 budget: c.budgetUsd === undefined ? NOT_STATED : dollars(c.budgetUsd),
25 brief: c.brief,
26 }));
27 return {
28 name: p.name,
29 title: p.title,
30 apps: p.apps.map((a) => ({ name: a.name, says: a.description, source: a.source })),
31 crew,
32 };
33 }
34
outdated

The starter budget string just repeats each member's budget joined with commas, and uses c.budgetUsd! . It is not a starter budget, it duplicates crew[].budget. Either the pack states a real starter budget and you read it, or drop this field and the second display.

35 /** The same facts as lines of text, for the terminal. */
36 export function factLines(f: PackFacts): string[] {
37 return [
38 `Apps it creates: ${f.apps.length === 0 ? NOT_STATED : f.apps.map((a) => a.name).join(", ")}`,
39 ...(f.crew.length === 0
40 ? ["Crew: not stated"]
41 : ["Crew:", ...f.crew.map((c) => ` ${c.name}: ${c.roles.join(", ")}; budget ${c.budget}`)]),
42 ];
43 }
src/spawn/templates.ts +13 −3
@@ -6,6 +6,9 @@
66 */
77
88 import { err, ok, type Result } from "../kernel/result.ts";
9 import { catalog } from "../packs/catalog.ts";
10 import { packFacts, type PackFacts } from "../packs/facts.ts";
11 import type { Pack } from "../packs/pack.ts";
912
1013 export interface Template {
1114 readonly id: string;
@@ -71,7 +74,14 @@ export function templateOf(id: string): Template {
7174 export const templateNotMarked = (ref: string): string => `${ref} is not marked as a template`;
7275 export const templateNotReadable = (ref: string): string => `${ref} is not readable by you`;
7376
74 /** What each template is, for a page or an agent to offer. */
75 export function templatesView(): { templates: readonly Template[]; default: string } {
76 return { templates: TEMPLATES, default: DEFAULT_TEMPLATE };
77 /**
78 * What each template is, for a page or an agent to offer; `packs` says what a forge made from
79 * each listed pack gets: its apps, crew roles and budget, "not stated" where the pack is silent.
80 */
81 export function templatesView(packs: readonly Pack[] = catalog().packs): {
82 templates: readonly Template[];
83 default: string;
84 packs: readonly PackFacts[];
85 } {
86 return { templates: TEMPLATES, default: DEFAULT_TEMPLATE, packs: packs.map(packFacts) };
7787 }
src/tui/screens/packs.ts +7 −2
@@ -12,6 +12,7 @@ import { newForgeScreen } from "./newforge.ts";
1212 import { promptScreen } from "./common.ts";
1313 import { catalog, refreshCatalogQuietly } from "../../packs/catalog.ts";
1414 import type { App } from "../../app.ts";
15 import { factLines, packFacts } from "../../packs/facts.ts";
1516 import type { Pack } from "../../packs/pack.ts";
1617 import { BRINGS_WORDS, deployCommands, STRANGER_WORDS } from "../../packs/words.ts";
1718 import type { Ctx, Screen } from "../app/app.ts";
@@ -30,7 +31,8 @@ export function packLines(p: Pack, origin: string | undefined, width = 80): stri
3031 "",
3132 "Apps",
3233 ...p.apps.map((a) => ` ${a.name} ${a.source}`),
33 ...(p.crew.length === 0 ? [] : ["", "Crew", ...p.crew.map((c) => ` ${c.username} ${c.roles.join(", ")}`)]),
34 "",
35 ...factLines(packFacts(p)).flatMap((l) => wrap(l, w)),

wrap() on the indented crew lines may trim the leading indent; check the screen. Also the import of facts.ts is out of order and the curatedScreen comment rewrap below is unrelated to this change - revert it.

3436 "",
3537 ...wrap(BRINGS_WORDS, w),
3638 "",
@@ -155,7 +157,10 @@ export function curatedScreen(session: Session, ctx: Ctx, name: string): Screen
155157 return screen;
156158 }
157159
158 /** The list: curated packs first (Enter opens one, a person admin's n makes one), then the deployable pack.json ones. */
160 /**
161 * The list: curated packs first (Enter opens one, a person admin's n makes one), then the
162 * deployable pack.json ones.
163 */
159164 export function packsScreen(ctx: Ctx, origin: string | undefined, app?: App, session?: Session): Screen {
160165 if (app !== undefined) void refreshCatalogQuietly(app, 2_000).then(() => ctx.invalidate());
161166 let at = 0;
src/web/pages/packs.ts +13 −8
@@ -11,6 +11,7 @@ import { refreshCatalogQuietly } from "../../packs/catalog.ts";
1111 import type { Ctx } from "../../http/context.ts";
1212 import { notFoundPage, pageHead } from "../chrome.ts";
1313 import { deployCommands } from "../../packs/words.ts";
14 import { NOT_STATED, packFacts } from "../../packs/facts.ts";
1415 import { html } from "../html.ts";
1516 import { flashTo, page } from "../layout.ts";
1617 import { mirrorPacks, reportWords } from "../../packs/mirror.ts";
@@ -191,6 +192,7 @@ export async function packPage(ctx: Ctx): Promise<Response> {
191192 const pack = (await refreshCatalogQuietly(ctx.app, CATALOG_FRESH_MS)).packs.find((p) => p.name === (ctx.params.name ?? ""));
192193 if (pack === undefined) return notFoundPage(ctx);
193194 const commands = deployCommands(pack, ctx.app.config.url);
195 const facts = packFacts(pack);
194196 const body = html`${pageHead(`${pack.title} pack`, { sub: pack.description })}
195197 <section class="stack">
outdated

Principle 1 and 8: 'Make a forge from this' opens the plain /forges/new form, which does not start from this pack (the PR description admits it). The label promises what it does not do. Either carry the pack through (prefill/start from it) or name it honestly ('Start a forge') and keep it where the old quiet link was, not as the page's primary action above the deploy command.

196198 <h2>Deploy it on your own machine</h2>
@@ -199,20 +201,23 @@ export async function packPage(ctx: Ctx): Promise<Response> {
199201 })}
200202 <p class="muted small">No data, secrets or variables come with it.</p>
201203 </section>
202 <section class="stack">
204 <section class="stack" id="pack-facts">
203205 <h2>What it brings</h2>
204 <ul class="list">${pack.apps.map((a) =>
206 <h3>Apps it creates</h3>
207 <ul class="list">${facts.apps.map((a) =>
205208 row({
206209 title: html`<a href="${a.source}" rel="noopener noreferrer">${a.name}</a>`,
207 meta: html`${a.description}`,
210 meta: html`${a.says}`,
208211 }),
209212 )}</ul>
210 ${pack.crew.length === 0
211 ? null
212 : html`<h3>The crew it starts with</h3>
213 <ul class="list">${pack.crew.map((c) => row({ title: c.username, meta: html`${c.roles.join(", ")}. ${c.brief}` }))}</ul>`}
213 <h3>The crew it starts with</h3>
214 ${facts.crew.length === 0
215 ? html`<p class="muted">Crew: ${NOT_STATED}.</p>`
216 : html`<dl class="status-rows">${facts.crew.map(
217 (c) => html`<div class="status-row"><dt>${c.name}</dt><dd>${c.roles.join(", ")}. Budget: ${c.budget}. ${c.brief}</dd></div>`,
outdated

Build the rows from facts.crew only (add brief to PackFacts) instead of iterating pack.crew with facts.crew[i]! - two arrays tied by index and a non-null assertion is fragile. Also the budget text appears here per member and again below as Starter budget: say it once (principle 1).

218 )}</dl>`}
214219 </section>
outdated

Principle 7: a fact is a dl row, not a free paragraph under an h3. Render the starter budget as a dl row (or fold it into the crew rows) and drop the extra h3.

215 <p class="muted small"><a href="/forges/new">Start your own forge</a> to help build these apps.</p>`;
220 <p class="muted small"><a href="/forges/new">Start a forge</a> of your own.</p>`;
216221 const response = page({ ctx, title: `${pack.title} pack`, body });
217222 notePhase(ctx.request, "render", performance.now() - started);
218223 return response;
test/pack-facts.test.ts added +95
@@ -0,0 +1,95 @@
1 /**
2 * What it brings from a pack, in plain words: apps, crew roles, budget, and
3 * "not stated" where the pack is silent (#13303). The page, terminal and MCP share `packFacts`.
4 */
5 import { afterAll, beforeAll, expect, test } from "bun:test";
6 import { mkdtemp, rm } from "node:fs/promises";
7 import { tmpdir } from "node:os";
8 import { join } from "node:path";
9 import { createApp, type App } from "../src/app.ts";
10 import { serve, type Servers } from "../src/http/server.ts";
11 import { factLines, packFacts } from "../src/packs/facts.ts";
12 import { parsePack } from "../src/packs/pack.ts";
13 import { templatesView } from "../src/spawn/templates.ts";
14 import { packLines } from "../src/tui/screens/packs.ts";
15 import { seedPacks } from "./helpers/packs.ts";
16
17 const make = (crew: unknown[]) => {
18 const r = parsePack(
19 JSON.stringify({
20 pack: 1,
21 name: "demo",
22 title: "Demo",
23 version: "1.0.0",
24 description: "A demo.",
25 apps: [{ name: "todo", description: "A list.", source: "https://example.com/a/todo" }],
26 crew,
27 }),
28 );
29 if (!r.ok) throw new Error(r.error);
30 return r.value;
31 };
32
33 test("facts name each app, each crew role and each budget", () => {
34 const f = packFacts(
35 make([
36 { username: "maker", roles: ["builder"], brief: "Build.", budgetUsd: 2.5 },
37 { username: "looker", roles: ["reviewer", "planner"], brief: "Review." },
38 ]),
39 );
40 expect(f.apps.map((a) => a.name)).toEqual(["todo"]);
41 expect(f.crew).toEqual([
42 { name: "maker", roles: ["builder"], budget: "$2.50 a run", brief: "Build." },
43 { name: "looker", roles: ["reviewer", "planner"], budget: "not stated", brief: "Review." },
44 ]);
45 expect(factLines(f).join("\n")).toContain("looker: reviewer, planner; budget not stated");
46 });
47
48 test("a pack that says nothing of crew or budget says 'not stated'", () => {
49 const f = packFacts(make([]));
50 expect(factLines(f)).toContain("Crew: not stated");
51 expect(packLines(make([]), undefined).join("\n")).toContain("Crew: not stated");
52 });
53
54 test("the terminal screen keeps the indent of each crew line", () => {
55 const lines = packLines(make([{ username: "maker", roles: ["builder"], brief: "Build.", budgetUsd: 2.5 }]), undefined);
56 expect(lines).toContain(" maker: builder; budget $2.50 a run");
57 });
58
59 test("the templates view (API and MCP) carries the facts", () => {
60 const view = templatesView([make([{ username: "maker", roles: ["builder"], brief: "Build.", budgetUsd: 1 }])]);
61 expect(view.packs[0]!.crew[0]!.budget).toBe("$1 a run");
62 });
63
64 let app: App;
65 let servers: Servers;
66 let dir: string;
67 beforeAll(async () => {
68 dir = await mkdtemp(join(tmpdir(), "pack-facts-"));
69 app = createApp({ dataDir: dir, port: 0 });
70 await seedPacks(app);
71 servers = await serve(app);
72 });
73 afterAll(async () => {
74 await servers?.stop();
75 app?.close();
76 await rm(dir, { recursive: true, force: true });
77 });
78
79 test("a pack's page shows each crew row with its roles and a 'not stated' budget", async () => {
80 const html = await (await fetch(`${servers.url}/packs/games`)).text();
81 expect(html).toContain("Apps it creates");
82 expect(html).toContain("<dt>arcade-builder</dt>");
outdated

The page test only checks static headings that render for any pack. Assert a real crew row and its budget (and 'not stated' on the page for a silent pack), so dropping the crew rows fails the test. Also cover the MCP/API path through the route, not only templatesView.

83 expect(html).toContain("builder. Budget: not stated.");
84 expect(html).toContain("<dt>arcade-reviewer</dt>");
85 expect(html).not.toContain("Starter budget");
86 expect(html).not.toContain("Make a forge from this");
87 });
88
89 test("the public templates API carries each pack's crew and budget", async () => {
90 const body = (await (await fetch(`${servers.url}/api/v1/forges/templates`)).json()) as {
91 packs: { name: string; crew: { name: string; roles: string[]; budget: string }[] }[];
92 };
93 const games = body.packs.find((p) => p.name === "games")!;
94 expect(games.crew[0]).toMatchObject({ name: "arcade-builder", roles: ["builder"], budget: "not stated" });
95 });

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs