@letterstory/cli 0.71.0 → 0.72.2

package/lib/cli.mjs

@@ -56,7 +56,7 @@ import {
 } from "./commands.mjs";
 
 // Keep in sync with cli/package.json.
-export const VERSION = "0.71.0";
+export const VERSION = "0.72.2";
 
 // Flags that never take a value. Listing them explicitly means `deploy get --json <id>`
 // can't accidentally swallow the id as --json's value.
@@ -645,7 +645,10 @@ Admin (STAFF key — --staff-key / LETTERSTORY_STAFF_API_KEY; acts before an org
                                                        trial-run, trial-save, the Write input bank
                                                        (inputs, input, inputs-harvest, input-save),
                                                        screens (screen-new, screens, screen,
-                                                       screen-advance),
+                                                       screen-advance), the bake-off (bakeoff,
+                                                       bakeoff-pick, bakeoff-merge), programmes
+                                                       (programmes, programme, programme-new,
+                                                       programme-stop, programme-advance),
                                                        and the arena, shredder
                                                        and enhancer twins (every flag is listed in
                                                        cli/lib/commands/admin.mjs).

package/lib/commands/admin.mjs

@@ -505,6 +505,24 @@ async function cmdAdminTuningContext(ctx) {
  *   admin tuning screens | screen <id>                         list / one screen: per candidate, each measure against the Base, with its noise
  *   admin tuning screen-advance <id>                           queue what the caps allow now (the cron does it every minute)
  *
+ * The bake-off: a screen's versions graded item by item against the checklist (the eval list's
+ * confirmed and unvetted categories, and the craft axes commitment / economy / movement), the winner
+ * per item tallied across the inputs, and a merge that composes the best of each into one candidate.
+ * Deterministic; a person overrides a grade and confirms the merge, which is a hypothesis until the
+ * eye test confirms it.
+ *   admin tuning bakeoff <screen-id> [--regrade]                 the winners table: item, trusted, leader, wins per version, graded; then the conflicts a merge would meet
+ *   admin tuning bakeoff-pick <screen-id> --input <key> --item <category:id|axis:id> --winner <version|none>   a person's grade on one input and item (replaces the machine's)
+ *   admin tuning bakeoff-merge <screen-id> [--resolve item=version,…] [--note "…"] [--compare 10]   save the merged file as a candidate of the base kernel (never live); --compare starts a comparison against live on that many pairs
+ *
+ * Programmes: the bake-off run by the machine, generation after generation, on the cron, with a run
+ * budget and stop rules (the budget; N flat generations; a finalist that won its picks). Each
+ * generation screens the base against its challengers, merges the winners, compares the merge
+ * against live; a merge that cleared the gates and lost no craft becomes the base. People pick.
+ *   admin tuning programmes | programme <id>                   list / one programme: every generation, its table, merge and comparison, and what happens next
+ *   admin tuning programme-new --title "…" --kernel <kernel-id|service-kernel-id> --seeds 21,22,23 [--inputs id,…|--n 8] [--filter "…"] [--pairs 10] --budget 200 [--flat 2]
+ *   admin tuning programme-stop <id> [--reason "…"]            stop it by hand
+ *   admin tuning programme-advance <id>                        one manual tick (the cron takes the same step every minute)
+ *
  * Research (Phase 3): our arena's versions as files, research comparisons, the deploy split.
  *   admin tuning arenas | arena <version-id>                   our arena's versions / one version's file and diff
  *   admin tuning arena-candidate --patch '{…}' | --file f.json [--of <version-id>] [--note "…"]   save a candidate
@@ -564,6 +582,49 @@ function tagFilterParams(raw) {
  * A session as an agent reads it: each trial's changes and runs with their headline numbers, and
  * (with `texts`) the latest finished text per trial. The full session (traces, records) is `--json`.
  */
+/** A programme as a person reads it: the row, then one block per generation, then what happens next. */
+function printProgramme(io, r) {
+	const p = r.programme;
+	io.log(
+		`programme ${p.title} (${p.id}): ${p.status}${p.stop_reason ? ` — ${p.stop_reason}` : ""} · generation ${p.generation} · base ${p.base_version === null ? "live" : `v${p.base_version}`} · ${p.runs_used}/${p.budget_runs} runs · seeds v${p.seed_versions.join(", v")} · ${p.pairs} pairs/generation · stop after ${p.max_flat_generations} flat`
+	);
+	for (const g of r.generations) {
+		const sm = g.summary ?? {};
+		io.log("");
+		io.log(
+			`generation ${g.generation}: ${g.status} · screen ${g.screen_id} · v${g.versions.join(", v")}${g.merged_version !== null ? ` · merged v${g.merged_version}` : ""}${g.comparison_id ? ` · comparison ${g.comparison_id}` : ""}`
+		);
+		if (sm.from)
+			io.log(
+				`  from: base ${sm.from.base === null ? "live" : `v${sm.from.base}`}${sm.from.seeds ? ` · seeds v${sm.from.seeds.join(", v")}` : ""}${sm.from.strongest?.length ? ` · strongest v${sm.from.strongest.join(", v")}` : ""}${sm.from.merged != null ? ` · merged v${sm.from.merged}` : ""}${sm.from.mutations?.length ? ` · mutations ${sm.from.mutations.map((m) => `${m.category} → v${m.version}`).join(", ")}` : ""}`
+			);
+		if (sm.leader !== undefined)
+			io.log(
+				`  leader ${sm.leader === null ? "none" : `v${sm.leader}`}${sm.flat ? " · flat (nothing moved off the base)" : ""}`
+			);
+		for (const row of sm.table ?? [])
+			if (row.leader !== null && row.leader !== sm.base)
+				io.log(
+					`    ${row.item.id.padEnd(32)} ${row.trusted ? "trusted  " : "unvetted "} v${row.leader}  ${Object.entries(
+						row.wins
+					)
+						.map(([v, n]) => `v${v}:${n}`)
+						.join(" ")}`
+				);
+		if (sm.merge)
+			io.log(
+				`  merge: from v${sm.merge.base} → v${sm.merge.version}; applied ${sm.merge.applied.map((a) => `${a.item} from v${a.from}`).join(", ") || "nothing"}${sm.merge.conflicts.length ? `; conflicts kept the base: ${sm.merge.conflicts.map((c) => c.path).join(", ")}` : ""}`
+			);
+		if (sm.comparison)
+			io.log(
+				`  comparison: quality ${sm.comparison.quality ?? "unread"}${sm.comparison.guards_worse.length ? ` · guards worse: ${sm.comparison.guards_worse.join(", ")}` : " · gates clean"} · ${sm.comparison.finalist ? "finalist" : "not a finalist"}${sm.comparison.picks ? ` · picks ${sm.comparison.picks}` : ""}${sm.comparison.delta?.ceiling != null ? ` · ceiling ${sm.comparison.delta.ceiling > 0 ? "+" : ""}${sm.comparison.delta.ceiling}` : ""}${sm.comparison.next_arm.length ? ` · next arm: ${sm.comparison.next_arm.map((a) => `${a.category}${a.patch ? " (patch)" : ""}`).join(", ")}` : ""}`
+			);
+		if (sm.error) io.log(`  error: ${sm.error}`);
+	}
+	io.log("");
+	io.log(`next: ${r.next}`);
+}
+
 function sessionSummary(session, texts) {
 	const runsOf = (trialId) => session.runs.filter((r) => r.trialId === trialId);
 	return {
@@ -1534,6 +1595,187 @@ async function cmdAdminTuning(ctx) {
 				? printResult(io, flags, r)
 				: io.log(`queued ${r.queued} run(s)${r.waiting ? `; waiting: ${r.waiting}` : ""}`);
 		}
+		// --- The bake-off: a screen's versions graded item by item, the winners table, the merge ---
+		case "bakeoff": {
+			if (!id) throw new CliError("Usage: admin tuning bakeoff <screen-id> [--regrade]");
+			const r = await staffRequest(
+				ctx,
+				"GET",
+				`${T}/screens/${id}/bakeoff${flagBool(flags.regrade) ? "?regrade=1" : ""}`
+			);
+			if (json) return printResult(io, flags, r);
+			io.log(
+				`bake-off ${r.screen.title}: v${r.versions.join(", v")} on ${r.inputs.length} input(s); leader ${r.leader === null ? "none" : `v${r.leader}`}`
+			);
+			if (r.unversioned.length) io.log(`left out (not a saved version): ${r.unversioned.join(", ")}`);
+			io.log("");
+			io.log(
+				`${"item".padEnd(32)} ${"trusted".padEnd(8)} ${"leader".padEnd(7)} ${r.versions.map((v) => `v${v}`.padStart(6)).join("")}  graded`
+			);
+			for (const row of r.table)
+				io.log(
+					`${row.item.id.padEnd(32)} ${(row.trusted ? "yes" : "no").padEnd(8)} ${(row.leader === null ? "—" : `v${row.leader}`).padEnd(7)} ${r.versions.map((v) => String(row.wins[v] ?? 0).padStart(6)).join("")}  ${row.graded}`
+				);
+			io.log("");
+			io.log(
+				r.conflicts_if_merged.length
+					? `conflicts if merged: ${r.conflicts_if_merged.map((c) => `${c.path} ← ${c.candidates.map((x) => `${x.item} v${x.version}`).join(" | ")}`).join("; ")}`
+					: "conflicts if merged: none"
+			);
+			return;
+		}
+		case "bakeoff-pick": {
+			const input = flagStr(flags.input);
+			const item = flagStr(flags.item);
+			const winner = flagStr(flags.winner);
+			if (!id || !input || !item || !winner)
+				throw new CliError(
+					"Usage: admin tuning bakeoff-pick <screen-id> --input <key> --item <category:id|axis:id> --winner <version|none>"
+				);
+			const winnerVersion = winner === "none" ? null : Number(winner);
+			if (winnerVersion !== null && !(Number.isInteger(winnerVersion) && winnerVersion > 0))
+				throw new CliError("--winner is a version number, or none");
+			const r = await staffRequest(ctx, "POST", `${T}/screens/${id}/bakeoff/pick`, {
+				input_key: input,
+				item_id: item,
+				winner_version: winnerVersion,
+			});
+			if (json) return printResult(io, flags, r);
+			const row = r.read.table.find((x) => x.item.id === item);
+			return io.log(
+				`graded ${item} on ${input}: ${winnerVersion === null ? "none" : `v${winnerVersion}`}${row ? ` · leader now ${row.leader === null ? "none" : `v${row.leader}`}` : ""}`
+			);
+		}
+		case "bakeoff-merge": {
+			if (!id)
+				throw new CliError(
+					'Usage: admin tuning bakeoff-merge <screen-id> [--resolve item=version,…] [--note "…"] [--compare 10]'
+				);
+			const resolve = {};
+			for (const pair of flagList(flags.resolve).flatMap((x) =>
+				x
+					.split(",")
+					.map((y) => y.trim())
+					.filter(Boolean)
+			)) {
+				const [item, version] = pair.split("=").map((x) => x.trim());
+				const v = Number(version);
+				if (!item || !(Number.isInteger(v) && v > 0))
+					throw new CliError(`--resolve: "${pair}" is not item=version`);
+				resolve[item] = v;
+			}
+			const compare = flags.compare === undefined ? undefined : { pairs: flagNum(flags.compare) ?? 10 };
+			const r = await staffRequest(
+				ctx,
+				"POST",
+				`${T}/screens/${id}/bakeoff/merge`,
+				compact({
+					resolve: Object.keys(resolve).length ? resolve : undefined,
+					note: flagStr(flags.note),
+					compare,
+				})
+			);
+			if (json) return printResult(io, flags, r);
+			io.log(
+				`merged from v${r.base} → candidate v${r.version}${r.comparison_id ? ` · comparison ${r.comparison_id}` : ""}`
+			);
+			for (const p of r.provenance)
+				io.log(`  ${p.applied ? "applied" : `skipped (${p.skipped})`}  ${p.item}  ${p.path}  from v${p.from}`);
+			if (r.conflicts.length)
+				io.log(
+					`conflicts left (the base's value kept): ${r.conflicts.map((c) => `${c.path} ← ${c.candidates.map((x) => `${x.item} v${x.version}`).join(" | ")}`).join("; ")}`
+				);
+			return;
+		}
+		// --- Programmes: the bake-off run by the machine over generations ---
+		case "programmes": {
+			const r = await staffRequest(ctx, "GET", `${T}/programmes?limit=${flagNum(flags.limit) ?? 30}`);
+			if (json) return printResult(io, flags, r);
+			return io.log(
+				r.programmes
+					.map(
+						(x) =>
+							`${x.id}  ${x.status.padEnd(7)} ${x.title} · generation ${x.generation} · base ${x.base_version === null ? "live" : `v${x.base_version}`} · ${x.runs_used}/${x.budget_runs} runs${x.stop_reason ? ` · ${x.stop_reason}` : ""}`
+					)
+					.join("\n") || "(no programmes)"
+			);
+		}
+		case "programme": {
+			if (!id) throw new CliError("Usage: admin tuning programme <programme-id>");
+			const r = await staffRequest(ctx, "GET", `${T}/programmes/${id}`);
+			if (json) return printResult(io, flags, r);
+			printProgramme(io, r);
+			return;
+		}
+		case "programme-new": {
+			const title = flagStr(flags.title);
+			const kernel = flagStr(flags.kernel);
+			const seeds = flagList(flags.seeds)
+				.flatMap((x) => x.split(","))
+				.map((x) => Number(x.trim()))
+				.filter((x) => Number.isFinite(x));
+			const budget = flagNum(flags.budget);
+			if (!title || !kernel || !seeds.length || budget === undefined)
+				throw new CliError(
+					'Usage: admin tuning programme-new --title "…" --kernel <kernel-id|service-kernel-id> --seeds 21,22,23 [--inputs id,…|--n 8] [--filter "…"] [--pairs 10] --budget 200 [--flat 2]'
+				);
+			const filter = Object.fromEntries(
+				Object.entries(tagFilterParams(flagStr(flags.filter))).map(([k, v]) => [
+					k,
+					v
+						.split(",")
+						.map((x) => x.trim())
+						.filter(Boolean),
+				])
+			);
+			const inputIds = flagList(flags.inputs).flatMap((x) =>
+				x
+					.split(",")
+					.map((y) => y.trim())
+					.filter(Boolean)
+			);
+			const r = await staffRequest(
+				ctx,
+				"POST",
+				`${T}/programmes`,
+				compact({
+					title,
+					base_kernel_id: kernel,
+					seed_versions: seeds,
+					input_ids: inputIds.length ? inputIds : undefined,
+					n: flagNum(flags.n),
+					filter: Object.keys(filter).length ? filter : undefined,
+					pairs: flagNum(flags.pairs),
+					budget_runs: budget,
+					max_flat_generations: flagNum(flags.flat),
+				})
+			);
+			if (json) return printResult(io, flags, r);
+			return io.log(
+				`programme ${r.programme.id}: generation 1 screening v${r.programme.seed_versions.join(", v")} against live; budget ${r.programme.budget_runs} runs · ${r.next}`
+			);
+		}
+		case "programme-stop": {
+			if (!id) throw new CliError('Usage: admin tuning programme-stop <programme-id> [--reason "…"]');
+			const r = await staffRequest(
+				ctx,
+				"POST",
+				`${T}/programmes/${id}/stop`,
+				compact({ reason: flagStr(flags.reason) })
+			);
+			if (json) return printResult(io, flags, r);
+			return io.log(`programme ${r.programme.id} ${r.programme.status}: ${r.programme.stop_reason}`);
+		}
+		case "programme-advance": {
+			if (!id) throw new CliError("Usage: admin tuning programme-advance <programme-id>");
+			const r = await staffRequest(ctx, "POST", `${T}/programmes/${id}/advance`, {});
+			if (json) return printResult(io, flags, r);
+			if (!r.transitions.length) io.log("nothing to do yet");
+			for (const t of r.transitions)
+				io.log(`generation ${t.generation}: ${t.from} → ${t.to}${t.note ? ` (${t.note})` : ""}`);
+			if (r.read) io.log(`next: ${r.read.next}`);
+			return;
+		}
 		// --- Research: our arena's versions, research comparisons, the deploy split ---
 		case "arenas": {
 			const r = await staffRequest(ctx, "GET", `${T}/arena-files`);

package/lib/commands/phantom.mjs

@@ -73,6 +73,12 @@ export const ARGS = {
 				theme: "theme",
 				customer_ref: { flag: "customer-ref" },
 				collection_id: { flag: "collection" },
+				redesign: { flag: "redesign", type: "bool", negate: "no-redesign" },
+				// `--layout none` clears the choice (the site's theme then suggests one).
+				layout: {
+					value: (flags) =>
+						flags.layout === undefined ? undefined : flags.layout === "none" ? null : String(flags.layout),
+				},
 			},
 		},
 		collection: { value: (flags) => readJsonObjectFlag(flags, "collection-config") },

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@letterstory/cli",
-	"version": "0.71.0",
+	"version": "0.72.2",
 	"description": "Spin up and manage Letterstory phantom blogs from your terminal.",
 	"type": "module",
 	"license": "UNLICENSED",