@letterstory/cli 0.57.0 → 0.59.0

package/README.md

@@ -360,6 +360,7 @@ letterstory admin tuning comparison <id>               # per-measure verdicts (b
 letterstory admin tuning picks <id>                    # the blind queue; then: admin tuning pick <id> --cell <key> --pick left|right|tie
 letterstory admin tuning reading-list <id> --n 10      # your next blind pairs as links (Text A / Text B), to read off the screen; pick in the console
 letterstory admin tuning pair <id> --cell <key>        # one pair named: live and candidate, both texts, the measures per arm (a key reads every pair)
+letterstory admin tuning side-by-side <id>,<id>,<id> [--cell <key>]   # several writers as one board: each one's measures against live; with --cell, every writer's text on that input
 letterstory admin tuning candidates --kernels all --patch '{"writer":"echo/echo"}' --note "Echo"   # the same change as a candidate of each kernel
 letterstory admin tuning session-new --title "Echo round 1" --kernel Hazel --input-file brief.md --kind outline [--version 22]
 letterstory admin tuning propose <session> --text "Echo with rarity on; live with the shred after" --create   # trials from words, over the dials
@@ -595,6 +596,23 @@ it to `0` in CI so a test does not wait on a real interval.
 `collection run --topic "…" --collection <uuid>` runs topic → draft → publish → rebuild
 end to end, with `collection run-status <job-id>` to follow it.
 
+### Enhancing
+
+The passes that run after the writer — visuals, internal links, external links (citations),
+metadata — as one versioned file per collection (models and settings), each run recorded.
+
+```bash
+letterstory enhance run <article-id> --pass internal_links    # run one pass on a post now
+letterstory enhance runs --article <article-id>               # what each pass did (also --auto-pen, --outcome skipped)
+letterstory enhance get <run-id>                              # one run: version, models, what it added, cost
+letterstory enhance file <collection-id> > enhancer.json      # the file the collection's passes run
+letterstory enhance file <collection-id> --patch '{"internalLinks":{"maxPerPost":3}}'
+letterstory enhance versions <collection-id>                  # your copy's versions and our releases
+letterstory enhance pin <collection-id> <version-id|none>     # pin one of our releases, or follow live
+letterstory enhance offer <collection-id> [--accept]          # our newer version, over your own changes
+letterstory autopen run --article <id> --skip finish,metadata # leave passes out of one run
+```
+
 ## Seers — event-driven signals
 
 A **seer** watches an external source (a GitHub repo, a Notion workspace, a spec URL, a

package/lib/cli.mjs

@@ -40,6 +40,7 @@ import {
 	cmdTemplates,
 	cmdCompositions,
 	cmdShredder,
+	cmdEnhance,
 	cmdLede,
 	cmdLandings,
 	cmdSequences,
@@ -54,7 +55,7 @@ import {
 } from "./commands.mjs";
 
 // Keep in sync with cli/package.json.
-export const VERSION = "0.57.0";
+export const VERSION = "0.59.0";
 
 // Flags that never take a value. Listing them explicitly means `deploy get --json <id>`
 // can't accidentally swallow the id as --json's value.
@@ -936,6 +937,8 @@ const CLIENT_COMMANDS = {
 	templates: cmdTemplates,
 	compositions: cmdCompositions,
 	shredder: cmdShredder,
+	enhance: cmdEnhance,
+	enhancer: cmdEnhance,
 	lede: cmdLede,
 	ledes: cmdLede,
 	landings: cmdLandings,

package/lib/commands/admin.mjs

@@ -430,6 +430,7 @@ async function cmdAdminTuningContext(ctx) {
  *   admin tuning pick <comparison-id> --cell <key> --pick left|right|tie   record a blind pick
  *   admin tuning reading-list <comparison-id> [--n 10]          your next blind pairs as links, to read off the screen
  *   admin tuning pair <comparison-id> --cell <key>             one pair named: live and candidate, both texts, the measures per arm
+ *   admin tuning side-by-side <id>,<id>[,…] [--cell <key>]     several comparisons as one board: each writer's measures against live, and one input's texts
  *   admin tuning candidates --kernels Hazel,Aspen|all --patch '{…}' [--base N] [--note "…"]   the same changes as a candidate of each kernel
  *   admin tuning promote <experiment-id> --versions <service-kernel-id>:<version>,…   promote from a "ship" decision
  *
@@ -463,6 +464,13 @@ async function cmdAdminTuningContext(ctx) {
  *   admin tuning shredders | shredder <version-id>             our shredder's versions / one version's file and diff
  *   admin tuning shredder-candidate --patch '{…}' | --file f.json [--of <version-id>] [--note "…"]   save a candidate
  *   admin tuning promote-shredder <experiment-id> --version <shredder-version-id>   promote our shredder from a "ship" decision (blind picks required)
+ *
+ * Enhance (Phase 5): our enhancer's versions as files, enhance comparisons, the deploy split.
+ *   admin tuning enhancers | enhancer <version-id>             our enhancer's versions / one version's file and diff
+ *   admin tuning enhancer-candidate --patch '{…}' | --file f.json [--of <version-id>] [--note "…"]   save a candidate
+ *   admin tuning enhance-compare --title "…" (--candidate <version-id> | --patch '{…}' | --null-check) [--keys …]
+ *   admin tuning enhance-inputs [--set v1] | enhance-split [--since-hours 72] [--at <iso>,…] | enhance-standing
+ *   admin tuning promote-enhancer <experiment-id> --version <enhancer-version-id>   promote our enhancer from a "ship" decision (picks when it changes visuals)
  */
 /** `--flag '<json>'` → the parsed object, or undefined when the flag is absent. */
 function jsonFlag(raw, name) {
@@ -633,6 +641,34 @@ async function cmdAdminTuning(ctx) {
 				await staffRequest(ctx, "GET", `${T}/comparisons/${id}/pair?${new URLSearchParams({ cell })}`)
 			);
 		}
+		case "side-by-side": {
+			const ids = (id ?? "")
+				.split(",")
+				.map((x) => x.trim())
+				.filter(Boolean);
+			if (!ids?.length) throw new CliError("Usage: admin tuning side-by-side <id>,<id>[,…] [--cell <key>]");
+			const cell = flagStr(flags.cell);
+			const r = await staffRequest(
+				ctx,
+				"GET",
+				`${T}/comparisons/side-by-side?${new URLSearchParams(compact({ ids: ids.join(","), cell }))}`
+			);
+			if (json) return printResult(io, flags, r);
+			for (const w of r.writers) {
+				const m = (measure) => w.measures.find((x) => x.measure === measure);
+				const q = m("quality");
+				io.log(
+					`${w.label} (${w.writers.join(", ") || "—"}, ${w.settled_pairs} pairs, ${w.status}): quality ${q?.mean_delta ?? "—"} [${q?.ci95?.join(" … ") ?? "—"}] ${q?.verdict ?? ""} · seconds ${m("latency_s")?.mean_candidate ?? "—"} vs ${m("latency_s")?.mean_control ?? "—"} · picks ${w.picks.candidate}–${w.picks.control}`
+				);
+			}
+			if (r.input) {
+				for (const t of [r.input.live, ...r.input.texts].filter(Boolean))
+					io.log(
+						`\n=== ${t.label} ${t.writer ?? ""}${t.version ? ` v${t.version}` : ""} (${t.access})\n${t.text ?? "(no text)"}`
+					);
+			} else io.log(`\ninputs: ${r.inputs.map((i) => i.key).join(", ")}  (add --cell <key> for the texts)`);
+			return;
+		}
 		case "candidates": {
 			const patch = jsonFlag(flags.patch, "--patch");
 			const wanted = flagList(flags.kernels);
@@ -1011,6 +1047,106 @@ async function cmdAdminTuning(ctx) {
 				)
 			);
 		}
+		// --- Enhance: our enhancer's versions as files, comparisons, the deploy split ---
+		case "enhance-compare": {
+			const title = flagStr(flags.title);
+			const versionId = flagStr(flags.candidate);
+			const patch = jsonFlag(flags.patch, "--patch");
+			const nullCheck = flagBool(flags["null-check"]);
+			const named = [versionId !== undefined, patch !== undefined, nullCheck === true].filter(Boolean).length;
+			if (!title || named !== 1)
+				throw new CliError(
+					"Usage: admin tuning enhance-compare --title \"…\" (--candidate <version-id> | --patch '{…}' | --null-check) [--keys k1,k2] [--concurrency 6] [--experiment <id>]"
+				);
+			const candidate = versionId ? { version_id: versionId } : patch ? { patch } : { null_check: true };
+			const r = await staffRequest(
+				ctx,
+				"POST",
+				`${T}/comparisons`,
+				compact({
+					primitive: "enhance",
+					title,
+					candidate,
+					keys: flagList(flags.keys),
+					concurrency: flagNum(flags.concurrency),
+					experiment_id: flagStr(flags.experiment),
+				})
+			);
+			return json ? printResult(io, flags, r) : io.log(`enhance comparison ${r.comparison?.id ?? ""} started`);
+		}
+		case "enhance-inputs": {
+			const set = flagStr(flags.set);
+			return printResult(
+				io,
+				{ ...flags, json: true },
+				await staffRequest(ctx, "GET", `${T}/enhance/inputs${set ? `?${new URLSearchParams({ set })}` : ""}`)
+			);
+		}
+		case "enhance-split": {
+			const q = new URLSearchParams(
+				compact({
+					since_hours: flagStr(flags["since-hours"]),
+					window_hours: flagStr(flags["window-hours"]),
+					at: flagStr(flags.at),
+				})
+			);
+			return printResult(
+				io,
+				{ ...flags, json: true },
+				await staffRequest(ctx, "GET", `${T}/enhance/deploy-split${q.size ? `?${q}` : ""}`)
+			);
+		}
+		case "enhance-standing":
+			return printResult(io, { ...flags, json: true }, await staffRequest(ctx, "GET", `${T}/enhance/standing`));
+		case "enhancers": {
+			const r = await staffRequest(ctx, "GET", `${T}/enhancer-files`);
+			if (json) return printResult(io, flags, r);
+			return io.log(
+				r.versions
+					.map((v) => `${v.label.padEnd(18)} ${v.status.padEnd(9)} ${v.id}${v.note ? `  ${v.note}` : ""}`)
+					.join("\n") || "(no versions)"
+			);
+		}
+		case "enhancer": {
+			if (!id) throw new CliError("Usage: admin tuning enhancer <version-id>");
+			return printResult(
+				io,
+				{ ...flags, json: true },
+				await staffRequest(ctx, "GET", `${T}/enhancer-files/${id}`)
+			);
+		}
+		case "enhancer-candidate": {
+			const patch = jsonFlag(flags.patch, "--patch");
+			const file = jsonFile({ "enhancer-file": flags.file }, "enhancer");
+			if ((patch === undefined) === (file === undefined))
+				throw new CliError(
+					'Usage: admin tuning enhancer-candidate --patch \'{"internalLinks":{"maxPerPost":3}}\' | --file enhancer.json [--of <version-id>] [--note "…"]'
+				);
+			const r = await staffRequest(
+				ctx,
+				"POST",
+				`${T}/enhancer-files`,
+				compact({ patch, file, patch_of: flagStr(flags.of), note: flagStr(flags.note) })
+			);
+			return json ? printResult(io, flags, r) : io.log(`saved candidate ${r.version.label} (${r.version.id})`);
+		}
+		case "promote-enhancer": {
+			const version = flagStr(flags.version);
+			if (!id || !version)
+				throw new CliError(
+					"Usage: admin tuning promote-enhancer <experiment-id> --version <enhancer-version-id>"
+				);
+			return printResult(
+				io,
+				{ ...flags, json: true },
+				await staffRequest(
+					ctx,
+					"POST",
+					`${EXPERIMENTS}/${id}/promote`,
+					compact({ enhancer_version_id: version, actor: actorFrom(flags) })
+				)
+			);
+		}
 		case "promote": {
 			const list = flagList(flags.versions);
 			if (!id || !list?.length)
@@ -1034,7 +1170,7 @@ async function cmdAdminTuning(ctx) {
 		}
 		default:
 			throw new CliError(
-				"Usage: admin tuning kernels|kernel|candidate|compare|comparisons|comparison|picks|pick|reading-list|pair|candidates|base-kernels|base-versions|sessions|session|session-new|propose|trial-add|trial-run|trial-save|promote|arenas|arena|arena-candidate|research-compare|research-inputs|research-split|research-standing|promote-arena|shred-compare|shred-inputs|shred-split|shred-standing|shredders|shredder|shredder-candidate|promote-shredder (see --help)"
+				"Usage: admin tuning kernels|kernel|candidate|compare|comparisons|comparison|picks|pick|reading-list|pair|side-by-side|candidates|base-kernels|base-versions|sessions|session|session-new|propose|trial-add|trial-run|trial-save|promote|arenas|arena|arena-candidate|research-compare|research-inputs|research-split|research-standing|promote-arena|shred-compare|shred-inputs|shred-split|shred-standing|shredders|shredder|shredder-candidate|promote-shredder|enhance-compare|enhance-inputs|enhance-split|enhance-standing|enhancers|enhancer|enhancer-candidate|promote-enhancer (see --help)"
 			);
 	}
 }

package/lib/commands/autopen.mjs

@@ -18,6 +18,8 @@ export const ARGS = {
 	run_auto_pen: {
 		article_id: { flag: "article", required: true },
 		from_scratch: { flag: "from-scratch", type: "bool" },
+		// --skip finish,metadata: leave those steps out of this run only.
+		skip_steps: { flag: "skip", type: "list" },
 	},
 };
 

package/lib/commands/enhance.mjs

@@ -0,0 +1,152 @@
+// `enhance` — the passes that run after the writer: visuals, internal links, external links
+// (citations) and metadata. Run one on a post now, read what each run did, and read or change the
+// enhance file a collection's passes run (its models and settings), the same versioned-file pattern
+// as a kernel, an arena and a shredder. Every command is a projection of one tool (docs/api).
+
+import { readFileSync } from "node:fs";
+import { CliError } from "../client.mjs";
+import { flagStr, printResult, ok, toolField, argsFromFlags } from "./shared.mjs";
+
+const PASSES = ["visuals", "internal_links", "external_links", "metadata"];
+const OUTCOMES = ["added", "none", "skipped", "failed"];
+
+/** `--file <path>` → the file's parsed JSON, or undefined when the flag is not set. */
+function readJsonFile(flags) {
+	const path = flagStr(flags.file);
+	if (path === undefined) return undefined;
+	try {
+		return JSON.parse(readFileSync(path, "utf8"));
+	} catch (error) {
+		throw new CliError(`--file ${path}: ${error instanceof Error ? error.message : String(error)}`);
+	}
+}
+
+/** `--patch '<json>'` → a JSON object, or undefined. */
+function readPatch(flags) {
+	const inline = flagStr(flags.patch);
+	if (inline === undefined) return undefined;
+	let parsed;
+	try {
+		parsed = JSON.parse(inline);
+	} catch (err) {
+		throw new CliError(`--patch is not valid JSON: ${err.message}`);
+	}
+	if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed))
+		throw new CliError("--patch must be a JSON object");
+	return parsed;
+}
+
+/**
+ * How every command sources its tool's inputs (shared.mjs `argsFromFlags`; scripts/parity-check.ts
+ * diffs these keys against each tool's published schema).
+ */
+export const ARGS = {
+	run_enhance_pass: {
+		article_id: { positional: 0, label: "article-id", required: true },
+		pass: { flag: "pass", required: true, enum: PASSES },
+	},
+	get_enhance_run: {
+		run_id: { positional: 0, label: "run-id", required: true },
+	},
+	list_enhance_runs: {
+		article_id: "article",
+		auto_pen_id: "auto-pen",
+		collection_id: "collection",
+		pass: { flag: "pass", enum: PASSES },
+		outcome: { flag: "outcome", enum: OUTCOMES },
+		since: "since",
+		limit: { flag: "limit", type: "num" },
+	},
+	get_enhancer_file: {
+		collection_id: { positional: 0, label: "collection-id", required: true },
+	},
+	save_enhancer_file: {
+		collection_id: { positional: 0, label: "collection-id", required: true },
+		file: { value: (flags) => readJsonFile(flags) },
+		patch: { value: (flags) => readPatch(flags) },
+		note: "note",
+	},
+	list_enhancer_versions: {
+		collection_id: { positional: 0, label: "collection-id", required: true },
+	},
+	pin_enhancer_version: {
+		collection_id: { positional: 0, label: "collection-id", required: true },
+		version_id: {
+			value: (_flags, positionals) => {
+				const v = positionals[1];
+				if (v === undefined) throw new CliError("Missing required <version-id|none>");
+				return v === "none" ? null : v;
+			},
+		},
+	},
+	accept_enhancer_offer: {
+		collection_id: { positional: 0, label: "collection-id", required: true },
+	},
+};
+
+export async function cmdEnhance(ctx) {
+	const sub = ctx.positionals[0];
+	const rest = { ...ctx, positionals: ctx.positionals.slice(1) };
+	switch (sub) {
+		case "run":
+			return enhanceTool(rest, "run_enhance_pass");
+		case "runs":
+			return enhanceTool(rest, "list_enhance_runs");
+		case "get":
+		case "show":
+			return enhanceTool(rest, "get_enhance_run");
+		case "file":
+			return enhanceFile(rest);
+		case "versions":
+			return enhanceTool(rest, "list_enhancer_versions");
+		case "pin":
+			return enhanceTool(rest, "pin_enhancer_version");
+		case "offer":
+			return rest.flags.accept === true ? enhanceTool(rest, "accept_enhancer_offer") : enhanceOffer(rest);
+		default:
+			throw new CliError(
+				`Unknown enhance subcommand: ${sub ?? "(none)"}. Try: run <article-id> --pass <pass>, runs, get <run-id>, file <collection-id>, versions, pin, offer`
+			);
+	}
+}
+
+async function enhanceTool(ctx, tool) {
+	const result = await ctx.client.callTool(tool, argsFromFlags(ARGS[tool], ctx.flags, ctx.positionals));
+	printResult(ctx.io, ctx.flags, result);
+	return 0;
+}
+
+async function enhanceFile(ctx) {
+	const { client, flags, io } = ctx;
+	const saving = flagStr(flags.file) !== undefined || flagStr(flags.patch) !== undefined;
+	if (!saving) {
+		const result = await client.callTool(
+			"get_enhancer_file",
+			argsFromFlags(ARGS.get_enhancer_file, flags, ctx.positionals)
+		);
+		printResult(io, flags, result, (r) => JSON.stringify(r?.file ?? r, null, 2));
+		return 0;
+	}
+	const result = await client.callTool(
+		"save_enhancer_file",
+		argsFromFlags(ARGS.save_enhancer_file, flags, ctx.positionals)
+	);
+	ok(
+		ctx,
+		`Saved ${toolField(result, "version")?.label ?? "a new version"}; the collection's passes run it from now on.`
+	);
+	printResult(io, flags, result);
+	return 0;
+}
+
+async function enhanceOffer(ctx) {
+	const { client, flags, io } = ctx;
+	const result = await client.callTool(
+		"get_enhancer_file",
+		argsFromFlags(ARGS.get_enhancer_file, flags, ctx.positionals)
+	);
+	const offer = toolField(result, "offer");
+	if (!offer) ok(ctx, "No offer: the collection runs our latest version, or a copy based on it.");
+	printResult(io, flags, result, (r) => JSON.stringify(r?.offer ?? null, null, 2));
+	return 0;
+}

package/lib/commands/evals.mjs

@@ -16,7 +16,7 @@
 import { CliError } from "../client.mjs";
 import { flagStr, readBodyInput, printResult, ok, argsFromFlags } from "./shared.mjs";
 
-const STAGES = ["research", "brief", "links", "mentions", "accuracy", "pipeline", "shred"];
+const STAGES = ["research", "brief", "links", "mentions", "accuracy", "pipeline", "shred", "enhance"];
 const STATUSES = ["proposed", "open", "guarding", "retired", "rejected"];
 
 /** `--keys a,b,c` (or repeated `--keys`) → ["a", "b", "c"]; undefined when unset. */

package/lib/commands.mjs

@@ -32,6 +32,7 @@ export * from "./commands/lede.mjs";
 export * from "./commands/onboard.mjs";
 export * from "./commands/seers.mjs";
 export * from "./commands/shredder.mjs";
+export * from "./commands/enhance.mjs";
 export * from "./commands/landings.mjs";
 export * from "./commands/outbound.mjs";
 export * from "./commands/offerings.mjs";

package/package.json

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