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

A template may declare a first ask in forge.json that fills a new forge's ask box #13994

Merged opened this

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

Merged

scout/forge:scout/13972-a-template-may-declare-a-first-ask-in-fo → main 5 commits fork 3 threads · 3 unresolved

  • Merged. scout/13972-a-template-may-declare-a-first-ask-in-fo was merged into main as 9225567.

Review

Sign in to review this change.
11 files changed +269 −9
docs/features/first-ask.md +8 −6
@@ -1,8 +1,10 @@
1 # Refused first asks (#11525)
1 # A template's first ask
22
3 When the forge refuses a first ask, it keeps one row: who asked, the first 200 characters and the refusal's words. No claim code, token or email is kept.
3 A template may start a new forge's ask box with a sentence, so the forge opens with a good next thought ready.
44
5 - **Where they are read:** `/forges/refused` (the newest 20, newest first), linked from `/forges` (with the count, once there is one) and from `/system`; the same rows are in the terminal. Only a forge admin who is a person may read them; anyone else gets what `/forges` gives.
6 - **Capped at 20 per person per hour:** past that, the next refusal is dropped silently.
7 - **Kept 30 days:** older rows are pruned on write and never listed.
8 - Code: `src/core/first_ask_refusals.ts`, `src/web/pages/forges-refused.ts`; tests in `test/forges-refused.test.ts`.
5 - **Declare it:** `"firstAsk": "Add a weekly menu page"` at the top level of the template's `forge.json`. A string of 1 to 280 characters of plain text (a newline is allowed); an empty, longer or non-string value makes the file invalid, and a stored value that fails the same check is ignored.
6 - **Read once:** when a forge is made from a template repository (`template: "owner/name"`), `copyInto` reads `firstAsk` at the template's default branch and keeps it in the new forge's `parent.json` (`template.firstAsk`). Later edits to the template do not change a forge already made.
7 - **Shown:** on the new forge's home before its first ask, the box holds the sentence, escaped and editable; leading newlines are trimmed. The terminal's "What do you want built?" prompt (`t` on the home) starts with the same text (`readyAsk`).
8 - **Nothing declared:** the box is empty, as before.
9 - **Not done:** the template's own page does not show its first ask.
10 - Code: `src/apps/first_ask.ts`, `src/spawn/template_first_ask.ts`, `readyAsk` in `src/spawn/template_record.ts`. Tests: `test/template-first-ask.test.ts`, `test/tui-first-ask.test.ts`.
src/actions/spawn.ts +5
@@ -47,6 +47,7 @@ import { lendIncludedCredit } from "../spawn/included_credit.ts";
4747 import { seedStarterCrew } from "../spawn/starter_crew.ts";
4848 import { repoTemplateRef, templateNotMarked, templateNotReadable } from "../spawn/templates.ts";
4949 import { birthFromTemplate, type TemplateMark } from "../spawn/template_birth.ts";
50 import { templateFirstAsk } from "../spawn/template_first_ask.ts";
5051 import { writePrivate } from "../kernel/file_modes.ts";
5152 import { sha256 } from "../kernel/hash.ts";
5253 import { secret } from "../kernel/id.ts";
@@ -643,6 +644,10 @@ async function copyInto(
643644 // The commit a template repository was read at, kept with the template (#13038).
644645 if (fromRepo !== undefined && forgeCode.value !== undefined && forgeCode.value.tip !== "")
645646 templateMark = { id: fromRepo, repo: fromRepo, tip: forgeCode.value.tip };
647 if (fromRepo !== undefined) {
648 const ask = await templateFirstAsk(app, fromRepo);
649 if (ask !== undefined) templateMark = { ...(templateMark ?? { id: fromRepo, repo: fromRepo }), firstAsk: ask };

The spawn path that writes firstAsk into parent.json is untested end to end. Add a test that spawns from a template repo and reads the new forge's box.

650 }
646651
647652 step = "crew";
648653 for (const b of plan.briefs) {
src/apps/first_ask.ts added +31
@@ -0,0 +1,31 @@
1 /**
2 * A template's first ask: `firstAsk` at the top of its forge.json is a sentence that fills the ask
3 * box of a forge made from it, so the new forge opens with a good next thought ready. Plain text,
4 * one to 280 characters, no control characters other than a newline; anything else is refused where
5 * the file is checked and ignored where it is read.
6 */
7
8 export const FIRST_ASK_MAX = 280;
9
10 /** The problem with a declared `firstAsk`, or undefined when it is fine (or absent). */
11 export function firstAskProblem(raw: unknown): string | undefined {
12 if (raw === undefined) return undefined;
13 if (typeof raw !== "string") return "forge.json: firstAsk must be a string";
14 if (raw.trim() === "") return "forge.json: firstAsk must not be empty";
15 if (raw.length > FIRST_ASK_MAX) return `forge.json: firstAsk must be at most ${FIRST_ASK_MAX} characters`;
16 if (/[\x00-\x09\x0b-\x1f\x7f]/.test(raw)) return "forge.json: firstAsk must be plain text";
17 return undefined;
18 }
19
20 /** The first ask a forge.json text declares; undefined when none or when it is not valid. */
21 export function firstAskOf(forgeJson: string | undefined): string | undefined {
22 if (forgeJson === undefined) return undefined;
23 try {
24 const doc: unknown = JSON.parse(forgeJson);
25 if (typeof doc !== "object" || doc === null) return undefined;
26 const raw = (doc as Record<string, unknown>)["firstAsk"];
27 return firstAskProblem(raw) === undefined ? (raw as string | undefined)?.trim() : undefined;
28 } catch {
29 return undefined;
30 }
31 }
src/apps/manifest.ts +3
@@ -23,6 +23,7 @@ import { parseSchedules, type ScheduleSpec } from "./schedule_spec.ts";
2323 import { parseBeat, type BeatSpec } from "./beat_spec.ts";
2424 import { parseFeature, scheduleSpecs } from "./feature.ts";
2525 import { PREVIEW_MODES } from "./prepared.ts";
26 import { firstAskProblem } from "./first_ask.ts";
2627
2728 export interface AppManifest {
2829 /** The command that serves on `$PORT`. Run through `sh -c`, `exec`-ed. */
@@ -158,6 +159,8 @@ export function parseManifest(
158159
159160 const parsed = parseJson(forgeJson, "forge.json");
160161 if (!parsed.ok) return parsed;
162 const askProblem = firstAskProblem(parsed.value["firstAsk"]);
163 if (askProblem !== undefined) return invalid(askProblem);
161164 const app = parsed.value["app"];
162165 if (app === undefined) return err({ kind: "not_an_app" });
163166 if (!isObject(app)) return invalid("forge.json: app must be an object");
src/spawn/template_birth.ts +2
@@ -22,6 +22,8 @@ export interface TemplateMark {
2222 readonly repo?: string;
2323 /** The commit a template repository was read at (#13038). */
2424 readonly tip?: string;
25 /** The template's `firstAsk` at that commit: what the new forge's ask box starts with. */
26 readonly firstAsk?: string;
2527 }
2628
2729 /** The files a built-in template holds, for the app's name and description. */
src/spawn/template_first_ask.ts added +19
@@ -0,0 +1,19 @@
1 /**
2 * The first ask a template repository declares in its forge.json, read at its default branch's tip.
3 */
4
5 import type { App } from "../app.ts";
6 import { readFileAt } from "../apps/checkout.ts";
7 import { firstAskOf } from "../apps/first_ask.ts";
8 import { getRepo } from "../core/repos.ts";
9 import { resolveOid } from "../git/merge.ts";
10 import { repoDir } from "../git/repos.ts";
11
12 export async function templateFirstAsk(app: App, slug: string): Promise<string | undefined> {
13 const [o = "", n = ""] = slug.split("/");
14 const repo = getRepo(app.db, o, n);
15 if (!repo) return undefined;
16 const dir = repoDir(app.reposRoot, repo.ownerName, repo.name);
17 const oid = await resolveOid(dir, `refs/heads/${repo.defaultBranch}`);
18 return oid ? firstAskOf(await readFileAt(dir, oid, "forge.json")) : undefined;
19 }
src/spawn/template_record.ts +10 −2
@@ -6,6 +6,7 @@
66
77 import { readFileSync } from "node:fs";
88 import { join } from "node:path";
9 import { firstAskProblem } from "../apps/first_ask.ts";
910 import { DEFAULT_TEMPLATE, TEMPLATES } from "./templates.ts";
1011
1112 export interface MadeFrom {
@@ -55,6 +56,8 @@ export interface StartedFrom {
5556 readonly name: string;
5657 /** The template repository, as `owner/name`; absent for a built-in template. */
5758 readonly repo?: string;
59 /** The template's declared first ask, when it has one. */
60 readonly firstAsk?: string;
5861 }
5962
6063 /** The record's `template` entry, validated; undefined for none, `blank` or anything malformed. */
@@ -62,8 +65,10 @@ export function startedFromDoc(doc: unknown): StartedFrom | undefined {
6265 if (typeof doc !== "object" || doc === null) return undefined;
6366 const t = (doc as Record<string, unknown>)["template"];
6467 if (typeof t !== "object" || t === null) return undefined;
65 const { id, repo } = t as Record<string, unknown>;
66 if (typeof repo === "string" && REPO.test(repo)) return { name: repo, repo };
68 const { id, repo, firstAsk } = t as Record<string, unknown>;
69 // Trimmed: a leading newline would be swallowed by the parser inside a <textarea>.
70 const ask = typeof firstAsk === "string" && firstAskProblem(firstAsk) === undefined ? { firstAsk: firstAsk.trim() } : {};
71 if (typeof repo === "string" && REPO.test(repo)) return { name: repo, repo, ...ask };
6772 const built = typeof id === "string" ? TEMPLATES.find((b) => b.id === id && b.id !== DEFAULT_TEMPLATE) : undefined;
6873 if (built !== undefined) return { name: built.title };
6974 return typeof id === "string" && REPO.test(id) ? { name: id, repo: id } : undefined;
@@ -77,3 +82,6 @@ export function startedFromOf(dataDir: string): StartedFrom | undefined {
7782 return undefined;
7883 }
7984 }
85
86 /** What a new forge's ask box starts with, on either door: its template's first ask, or "". */
87 export const readyAsk = (dataDir: string): string => startedFromOf(dataDir)?.firstAsk ?? "";
src/tui/screens/dashboard.ts +3
@@ -14,6 +14,7 @@
1414 * whole of this screen's design.
1515 */
1616
17 import { readyAsk } from "../../spawn/template_record.ts";
1718 import { DEFAULT_WEIGHTS, frontWeights, type FrontWeights } from "../../core/front.ts";
1819 import { exploreCount, exploreFiltered, exploreLine, isExploreLine, exploreNote, exploreSuggestion, explorePage, parseExploreQuery, readExploreLine, whyOf, figuresOf, type ExploreRow } from "../../actions/explore.ts";
1920 import { protectionNotice } from "../../kernel/protection.ts";
@@ -1421,6 +1422,8 @@ export function dashboardScreen(f: Session, ctx: Ctx): Screen {
14211422 title: "What do you want built?",
14221423 label: "Your request",
14231424 hint: "enter sends",
1425 // The template's first ask, when it declared one: the same start as the page's box.
1426 value: readyAsk(f.app.config.dataDir),
14241427 onSubmit: (said) => {
14251428 if (said.trim() === "") return SAY_SOMETHING_WORDS;
14261429 // The page's own first ask: one new app made from the sentence, the ask filed on it.
src/web/pages/next-steps.ts +4 −1
@@ -26,6 +26,7 @@ import { btn, row } from "../ui.ts";
2626 import { askRepos, askStatus, type AskStatus } from "../../core/ask-status.ts";
2727 import { crewCanRun, crewFirstLine } from "../studio/crew_key.ts";
2828 import { NEW_APP_TARGET } from "../studio/feed.ts";
29 import { readyAsk } from "../../spawn/template_record.ts";
2930 import { COMPOSER_FIELDS, TELL_MAX } from "../share_target.ts";
3031
3132 /** The apps whose crew row shows beside the ask's: a builder at work is said once, so while the ask is building, its app's row goes. */
@@ -67,11 +68,13 @@ export function secondPasskeyLine(ctx: Ctx, user: User): Html | null {
6768
6869 /** Before the first tell: one box, "say what you want built", and one line about what pays for the crew. */
6970 function firstTell(ctx: Ctx, user: User): Html {
71 // The template's first ask, if it declared one: the box starts with it.
72 const ready = readyAsk(ctx.app.config.dataDir);
outdated

Over 100 columns on the const line; also a prefill that begins with a newline loses it inside <textarea>. The terminal ask screen needs the same prefill (both doors).

7073 return html`<section id="next-steps" data-first-tell>
7174 <h2>What do you want built?</h2>
7275 <form id="composer" class="stack" method="post" action="/tell">
7376 <input type="hidden" name="${COMPOSER_FIELDS.app}" value="${NEW_APP_TARGET}" />
74 <textarea class="input" name="${COMPOSER_FIELDS.text}" rows="3" maxlength="${String(TELL_MAX)}" required placeholder="A weekly menu page for the bakery" aria-label="Your request" data-draft="${user.id}"></textarea>
77 <textarea class="input" name="${COMPOSER_FIELDS.text}" rows="3" maxlength="${String(TELL_MAX)}" required placeholder="A weekly menu page for the bakery" aria-label="Your request" data-draft="${user.id}">${ready}</textarea>
7578 <div class="bar">${btn("Tell the crew", { variant: "primary" })}</div>
7679 </form>
7780 <p class="small muted" id="crew-credit-note">${crewFirstLine(ctx.app, ctx.auth.user?.isAdmin === true)}</p>
test/template-first-ask.test.ts added +135
@@ -0,0 +1,135 @@
1 /**
2 * A template may declare `firstAsk` in forge.json (#13972): checked to 280 characters, read from
3 * the template, kept in the new forge's record, and shown — escaped and editable — in its ask box.
4 */
5 import { afterAll, beforeAll, expect, test } from "bun:test";
6 import { readFileSync, writeFileSync } from "node:fs";
7 import { join } from "node:path";
8 import { childDirOf, spawnForge } from "../src/actions/spawn.ts";
9 import { hostedPlacement } from "../src/spawn/placement.ts";
10 import { commitToBranch, createRepo } from "../src/actions/repos.ts";
11 import { firstAskOf, firstAskProblem } from "../src/apps/first_ask.ts";
12 import { parseManifest } from "../src/apps/manifest.ts";
13 import { getUserByName } from "../src/core/users.ts";
14 import { templateFirstAsk } from "../src/spawn/template_first_ask.ts";
15 import { startedFromDoc, startedFromOf } from "../src/spawn/template_record.ts";
16 import { startedForge, type StartedForge } from "./helpers/claimed-forge.ts";
17 import { quietLogs } from "./helpers/globals.ts";
18
19 quietLogs();
20
21 const app = { run: "bun main.ts" };
22 const doc = (firstAsk?: unknown) => JSON.stringify({ app, ...(firstAsk === undefined ? {} : { firstAsk }) });
23
24 test("firstAsk is validated: a string of 1 to 280 characters of plain text", () => {
25 expect(firstAskProblem(undefined)).toBeUndefined();
26 expect(firstAskProblem("x".repeat(280))).toBeUndefined();
27 expect(firstAskProblem("x".repeat(281))).toContain("280");
28 expect(firstAskProblem(" ")).toContain("empty");
29 expect(firstAskProblem(7)).toContain("string");
30 expect(firstAskProblem("a\u0000b")).toContain("plain text");
31 expect(parseManifest(doc("A page for the menu"), undefined).ok).toBe(true);
32 expect(parseManifest(doc("x".repeat(281)), undefined).ok).toBe(false);
33 expect(firstAskOf(doc(" Add a menu "))).toBe("Add a menu");
34 expect(firstAskOf(doc("x".repeat(281)))).toBeUndefined();
35 expect(firstAskOf(doc())).toBeUndefined();
36 expect(firstAskOf("not json")).toBeUndefined();
37 });
38
39 test("the record keeps a valid first ask only", () => {
40 const rec = (firstAsk: unknown) => startedFromDoc({ template: { id: "a/b", repo: "a/b", firstAsk } });
41 expect(rec("Add a menu")?.firstAsk).toBe("Add a menu");
42 expect(rec("x".repeat(281))?.firstAsk).toBeUndefined();
43 expect(rec(5)?.firstAsk).toBeUndefined();
44 });
45
46 let forge: StartedForge;
47 let cookie = "";
48 let orgName = "";
49 beforeAll(async () => {
50 forge = await startedForge("template-first-ask-");
51 const name = orgName = forge.child.db.query<{ username: string }, []>("SELECT username FROM user WHERE kind = 'org' LIMIT 1").get()!.username;
52 const res = await fetch(`${forge.base}/claim`, {
53 method: "POST",
54 headers: { origin: forge.base },
55 body: new URLSearchParams({ token: forge.token, username: name, email: "[email protected]", password: "a-long-enough-password" }),
56 redirect: "manual",
57 });
58 if (res.status !== 303) throw new Error(`claim ${res.status}`);
59 cookie = (res.headers.get("set-cookie") ?? "").split(";")[0]!;
60 }, 60_000);
61 afterAll(() => forge.stop());
62
63 const record = (template: unknown) => {
64 const path = join(forge.child.config.dataDir, "parent.json");
65 writeFileSync(path, JSON.stringify({ ...JSON.parse(readFileSync(path, "utf8")), template }));
66 };
67 const box = async () => {
68 const html = await (await fetch(`${forge.base}/`, { headers: { cookie } })).text();
69 const card = html.slice(html.indexOf("data-first-tell"));
70 return /<textarea[^>]*>([\s\S]*?)<\/textarea>/.exec(card)?.[1];
outdated

Issue box 3 wants a forge started from a template with and without firstAsk. This only reads the template; hand-writes parent.json in the next test. Connect the two.

71 };
72
73 test("a template's forge.json is read for its first ask, with and without", async () => {
74 const owner = getUserByName(forge.child.db, orgName)!;
75 const make = async (n: string, json: string) => {
76 const r = await createRepo(forge.child, owner, { name: n, visibility: "public", description: "" });
77 if (!r.ok) throw new Error(n);
78 await commitToBranch(forge.child, owner, r.value, { message: "seed", files: [{ path: "forge.json", content: json }] });
79 return `${r.value.ownerName}/${n}`;
80 };
81 expect(await templateFirstAsk(forge.child, await make("with-ask", doc("Add a weekly menu page")))).toBe("Add a weekly menu page");
82 expect(await templateFirstAsk(forge.child, await make("without-ask", doc()))).toBeUndefined();
83 });
84
85 test("the ask box starts with the first ask, escaped and editable; without one it is empty", async () => {
86 record({ id: "a/b", repo: "a/b", firstAsk: `Add a <b>menu</b> & "hours"` });
87 const shown = await box();
88 expect(shown).toBe("Add a &lt;b&gt;menu&lt;/b&gt; &amp; &quot;hours&quot;");
89 const html = await (await fetch(`${forge.base}/`, { headers: { cookie } })).text();
90 expect(html).not.toContain("<b>menu</b>");
91 expect(html).toMatch(/<textarea(?![^>]*readonly)[^>]*name=/);
92 record({ id: "a/b", repo: "a/b" });
93 expect(await box()).toBe("");
94 });
95
96 test("a forge spawned from a template repo carries its first ask to the home box; without one the box is empty", async () => {
97 const owner = getUserByName(forge.child.db, orgName)!;
98 const make = async (n: string, json: string) => {
99 const r = await createRepo(forge.child, owner, { name: n, visibility: "public", description: "" });
100 if (!r.ok) throw new Error(n);
101 await commitToBranch(forge.child, owner, r.value, { message: "seed", files: [{ path: "forge.json", content: json }] });
102 forge.child.db.query("UPDATE repo SET is_template = 1 WHERE id = ?").run(r.value.id);
103 return `${r.value.ownerName}/${n}`;
104 };
105 const spawn = async (name: string, template: string) => {
106 const born = await spawnForge(
107 forge.child,
108 owner,
109 { name, org: name, apps: [], carryBriefs: false, carrySubscriptions: false, template },
110 { catalog: [], briefs: [], subscriptions: [] },
111 {
112 placement: hostedPlacement({ host: "root.test" }),
113 request: new Request("https://root.test/x", { method: "POST", headers: { origin: "https://root.test" } }),
114 url: new URL("https://root.test/x"),
115 },
116 );
117 if (!born.ok) throw new Error(JSON.stringify(born.error));
118 return childDirOf(forge.child, born.value.bodyId);
119 };
120 const withAsk = await spawn("fa-with", await make("tpl-with", doc("Add a weekly menu page")));
121 const without = await spawn("fa-without", await make("tpl-without", doc()));
122 // What birth wrote into each new forge's parent.json is what its box starts with.
123 expect(startedFromOf(withAsk)?.firstAsk).toBe("Add a weekly menu page");
124 expect(startedFromOf(without)?.firstAsk).toBeUndefined();
125 record(JSON.parse(readFileSync(join(withAsk, "parent.json"), "utf8")).template);
126 expect(await box()).toBe("Add a weekly menu page");
127 record(JSON.parse(readFileSync(join(without, "parent.json"), "utf8")).template);
128 expect(await box()).toBe("");
129 }, 60_000);
130
131 test("a first ask that starts with a newline is kept without it, so the box shows every word", async () => {
132 expect(startedFromDoc({ template: { id: "a/b", repo: "a/b", firstAsk: "\n\nAdd a menu" } })?.firstAsk).toBe("Add a menu");
133 record({ id: "a/b", repo: "a/b", firstAsk: "\nAdd a menu" });
134 expect(await box()).toBe("Add a menu");
135 });
test/tui-first-ask.test.ts added +49
@@ -0,0 +1,49 @@
1 /**
2 * The terminal's "What do you want built?" prompt starts with the template's first ask (#13972),
3 * as the page's box does; without one it starts empty.
4 */
5 import { afterAll, beforeAll, expect, test } from "bun:test";
6 import { readFileSync, writeFileSync } from "node:fs";
7 import { join } from "node:path";
8 import { getUserById } from "../src/core/users.ts";
9 import { createForgeApp } from "../src/tui/forge.ts";
10 import { headlessTerminal } from "../src/tui/term/terminal.ts";
11 import { claimedForge, type ClaimedForge } from "./helpers/claimed-forge.ts";
12 import { quietLogs } from "./helpers/globals.ts";
13 import { settleApp } from "./helpers/tui.ts";
14
15 quietLogs();
16
17 let forge: ClaimedForge;
18 beforeAll(async () => {
19 forge = await claimedForge("forge-tui-first-ask-");
20 }, 60_000);
21 afterAll(() => forge.stop());
22
23 async function prompt(): Promise<string> {
24 const row = forge.child.db.query<{ id: string }, []>("SELECT id FROM user WHERE is_admin = 1 AND is_agent = 0 AND kind = 'user' LIMIT 1").get()!;
25 const user = getUserById(forge.child.db, row.id)!;
26 const { app } = createForgeApp(
27 forge.child,
28 { sshUsername: user.username, remoteAddress: "127.0.0.1", fingerprint: "SHA256:t", user },
29 { terminal: headlessTerminal(200, 32), exitHooks: false },
30 );
31 app.start();
32 await settleApp(app);
33 app.dispatch({ type: "key", key: "t", ctrl: false, alt: false, shift: false });
34 await settleApp(app);
35 const text = app.screen.toText();
36 app.stop();
37 return text;
38 }
39
40 test("the prompt starts with the template's first ask, and is empty without one", async () => {
41 const path = join(forge.child.config.dataDir, "parent.json");
42 const base = (() => { try { return JSON.parse(readFileSync(path, "utf8")); } catch { return {}; } })();
43 writeFileSync(path, JSON.stringify({ ...base, template: { id: "a/b", repo: "a/b", firstAsk: "Add a weekly menu page" } }));
44 expect(await prompt()).toContain("Add a weekly menu page");
45 writeFileSync(path, JSON.stringify({ ...base, template: { id: "a/b", repo: "a/b" } }));
46 const bare = await prompt();
47 expect(bare).toContain("What do you want built?");
48 expect(bare).not.toContain("Add a weekly menu page");
49 });

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs