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
Check · Review · Land · Live done — Landed and live in production.
scout/forge:scout/13303-a-template-s-page-says-what-a-new-forge → main 3 commits fork 6 threads · 6 unresolved
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: | ||
| 34 | 34 | |
| 35 | 35 | ## A source may not point inside (#11971) |
| 36 | 36 | 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"; | ||
| 3 | 3 | |
| 4 | 4 | export const tool: Tool = { |
| 5 | 5 | 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", | |
| 7 | 7 | description: "The templates a child forge may start from.", |
| 8 | 8 | inputSchema: { type: "object", properties: {} }, |
| 9 | 9 | 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 | ||
| 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 @@ | ||
| 6 | 6 | */ |
| 7 | 7 | |
| 8 | 8 | 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"; | |
| 9 | 12 | |
| 10 | 13 | export interface Template { |
| 11 | 14 | readonly id: string; |
| @@ -71,7 +74,14 @@ export function templateOf(id: string): Template { | ||
| 71 | 74 | export const templateNotMarked = (ref: string): string => `${ref} is not marked as a template`; |
| 72 | 75 | export const templateNotReadable = (ref: string): string => `${ref} is not readable by you`; |
| 73 | 76 | |
| 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) }; | |
| 77 | 87 | } |
src/tui/screens/packs.ts +7 −2
| @@ -12,6 +12,7 @@ import { newForgeScreen } from "./newforge.ts"; | ||
| 12 | 12 | import { promptScreen } from "./common.ts"; |
| 13 | 13 | import { catalog, refreshCatalogQuietly } from "../../packs/catalog.ts"; |
| 14 | 14 | import type { App } from "../../app.ts"; |
| 15 | import { factLines, packFacts } from "../../packs/facts.ts"; | |
| 15 | 16 | import type { Pack } from "../../packs/pack.ts"; |
| 16 | 17 | import { BRINGS_WORDS, deployCommands, STRANGER_WORDS } from "../../packs/words.ts"; |
| 17 | 18 | import type { Ctx, Screen } from "../app/app.ts"; |
| @@ -30,7 +31,8 @@ export function packLines(p: Pack, origin: string | undefined, width = 80): stri | ||
| 30 | 31 | "", |
| 31 | 32 | "Apps", |
| 32 | 33 | ...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. |
||
| 34 | 36 | "", |
| 35 | 37 | ...wrap(BRINGS_WORDS, w), |
| 36 | 38 | "", |
| @@ -155,7 +157,10 @@ export function curatedScreen(session: Session, ctx: Ctx, name: string): Screen | ||
| 155 | 157 | return screen; |
| 156 | 158 | } |
| 157 | 159 | |
| 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 | */ | |
| 159 | 164 | export function packsScreen(ctx: Ctx, origin: string | undefined, app?: App, session?: Session): Screen { |
| 160 | 165 | if (app !== undefined) void refreshCatalogQuietly(app, 2_000).then(() => ctx.invalidate()); |
| 161 | 166 | let at = 0; |
src/web/pages/packs.ts +13 −8
| @@ -11,6 +11,7 @@ import { refreshCatalogQuietly } from "../../packs/catalog.ts"; | ||
| 11 | 11 | import type { Ctx } from "../../http/context.ts"; |
| 12 | 12 | import { notFoundPage, pageHead } from "../chrome.ts"; |
| 13 | 13 | import { deployCommands } from "../../packs/words.ts"; |
| 14 | import { NOT_STATED, packFacts } from "../../packs/facts.ts"; | |
| 14 | 15 | import { html } from "../html.ts"; |
| 15 | 16 | import { flashTo, page } from "../layout.ts"; |
| 16 | 17 | import { mirrorPacks, reportWords } from "../../packs/mirror.ts"; |
| @@ -191,6 +192,7 @@ export async function packPage(ctx: Ctx): Promise<Response> { | ||
| 191 | 192 | const pack = (await refreshCatalogQuietly(ctx.app, CATALOG_FRESH_MS)).packs.find((p) => p.name === (ctx.params.name ?? "")); |
| 192 | 193 | if (pack === undefined) return notFoundPage(ctx); |
| 193 | 194 | const commands = deployCommands(pack, ctx.app.config.url); |
| 195 | const facts = packFacts(pack); | |
| 194 | 196 | const body = html`${pageHead(`${pack.title} pack`, { sub: pack.description })} |
| 195 | 197 | <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. |
||
| 196 | 198 | <h2>Deploy it on your own machine</h2> |
| @@ -199,20 +201,23 @@ export async function packPage(ctx: Ctx): Promise<Response> { | ||
| 199 | 201 | })} |
| 200 | 202 | <p class="muted small">No data, secrets or variables come with it.</p> |
| 201 | 203 | </section> |
| 202 | <section class="stack"> | |
| 204 | <section class="stack" id="pack-facts"> | |
| 203 | 205 | <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) => | |
| 205 | 208 | row({ |
| 206 | 209 | title: html`<a href="${a.source}" rel="noopener noreferrer">${a.name}</a>`, |
| 207 | meta: html`${a.description}`, | |
| 210 | meta: html`${a.says}`, | |
| 208 | 211 | }), |
| 209 | 212 | )}</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>`} | |
| 214 | 219 | </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>`; | |
| 216 | 221 | const response = page({ ctx, title: `${pack.title} pack`, body }); |
| 217 | 222 | notePhase(ctx.request, "render", performance.now() - started); |
| 218 | 223 | 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 | }); |
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.