@letterstory/cli 0.26.0 → 0.27.0

package/lib/cli.mjs

@@ -44,7 +44,7 @@ import {
 } from "./commands.mjs";
 
 // Keep in sync with cli/package.json.
-export const VERSION = "0.26.0";
+export const VERSION = "0.27.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.

package/lib/commands/arena.mjs

@@ -80,6 +80,21 @@ const RUN_OPTIONS = {
  * shared.mjs and `scripts/parity-check.ts`, which compares these keys against each tool's
  * published input schema.
  */
+/** `--var Name=Value` (repeatable) → `{ Name: "Value" }` for a template's {Variables}. */
+function templateVariablesFromFlags(flags) {
+	const raw = flags.var;
+	if (raw === undefined) return undefined;
+	const list = Array.isArray(raw) ? raw : [raw];
+	const out = {};
+	for (const entry of list) {
+		const text = String(entry);
+		const eq = text.indexOf("=");
+		if (eq <= 0) throw new CliError(`--var must be Name=Value (got "${text}").`);
+		out[text.slice(0, eq).trim()] = text.slice(eq + 1).trim();
+	}
+	return Object.keys(out).length ? out : undefined;
+}
+
 export const ARGS = {
 	run_arena: {
 		arena_id: { flag: "arena" },
@@ -87,6 +102,19 @@ export const ARGS = {
 		source_urls: { flag: "source", type: "list" },
 		must_include: { flag: "must-include", type: "list" },
 		shape: { value: (flags) => readJsonObjectFlag(flags, "shape") },
+		// A TEMPLATE INSTEAD OF LISTING THE SHAPE BY HAND. Resolving one fills both
+		// `must_include` and `shape`; the `constraints` it returns come back on the run, and
+		// passing them to `kernel write --template-constraints` is what stops the same template
+		// being resolved twice into two different sets of section labels.
+		template: {
+			object: {
+				key: { flag: "template" },
+				blocks: { value: (flags) => readJsonFileFlag(flags, "template-blocks") },
+				title: { flag: "title" },
+				variables: { value: (flags) => templateVariablesFromFlags(flags) },
+				constraints: { value: (flags) => readJsonFileFlag(flags, "template-constraints") },
+			},
+		},
 		existing_content: { value: (flags) => flagStr(flags["existing-content"]) },
 		article_id: { flag: "article" },
 		...RUN_OPTIONS,

package/lib/commands/kernel.mjs

@@ -69,6 +69,21 @@ function readTextFileFlag(flags, flag) {
  * The rest of this module predates the field-level ratchet and is covered by the
  * frozen UNMAPPED_TOOLS list. New commands declare; that list only shrinks.
  */
+/** `--var Name=Value` (repeatable) → `{ Name: "Value" }` for a template's {Variables}. */
+function variablesFromFlags(flags) {
+	const raw = flags.var;
+	if (raw === undefined) return undefined;
+	const list = Array.isArray(raw) ? raw : [raw];
+	const out = {};
+	for (const entry of list) {
+		const text = String(entry);
+		const eq = text.indexOf("=");
+		if (eq <= 0) throw new CliError(`--var must be Name=Value (got "${text}").`);
+		out[text.slice(0, eq).trim()] = text.slice(eq + 1).trim();
+	}
+	return Object.keys(out).length ? out : undefined;
+}
+
 export const ARGS = {
 	// The article-bound door: submit a kernel run INTO an article you already have.
 	submit_kernel_run: {
@@ -109,6 +124,22 @@ export const ARGS = {
 		// field a template resolves to, sent by a caller who has their own.
 		skeleton: { value: (flags) => readJsonFileFlag(flags, "skeleton-file") },
 		brief_json: { value: (flags) => readJsonFileFlag(flags, "brief-json-file") },
+		// A TEMPLATE INSTEAD OF HAND-BUILDING THOSE. `--template <key>` resolves one of your
+		// templates against the material you sent and fills `skeleton`, `target_word_count` and
+		// `brief_json` for this call — and the finished run comes back ASSEMBLED rather than as
+		// the scaffolding the kernel writes. `--template-constraints <path>` passes back the
+		// answer `templates resolve` already gave, so the same template is not resolved twice
+		// (which would relabel the sections the outline planned). `--var Name=Value` fills a
+		// {Variable} the template declares.
+		template: {
+			object: {
+				key: { flag: "template" },
+				blocks: { value: (flags) => readJsonFileFlag(flags, "template-blocks") },
+				title: { flag: "title" },
+				variables: { value: (flags) => variablesFromFlags(flags) },
+				constraints: { value: (flags) => readJsonFileFlag(flags, "template-constraints") },
+			},
+		},
 		max_iterations: { flag: "max-iterations", type: "num" },
 		kernel_version: { flag: "kernel-version", type: "num" },
 		// In-loop shred tuning. Only sent when a flag is set; ignored when no shred runs.

package/lib/commands/seers.mjs

@@ -14,7 +14,7 @@
 
 import { readFileSync, writeFileSync } from "node:fs";
 import { CliError } from "../client.mjs";
-import { flagStr, flagBool, requirePositional, printResult, ok, argsFromFlags } from "./shared.mjs";
+import { flagStr, flagBool, printResult, ok, argsFromFlags } from "./shared.mjs";
 
 // A single-value flag the API clears with an explicit `null` (same idiom as
 // strategy.mjs's clearableList): `--clear-collection` sends null, `--collection <uuid>`
@@ -721,123 +721,3 @@ async function seersApply(ctx) {
 	}
 	return 0;
 }
-
-// --- Templates ---------------------------------------------------------------------
-
-export async function cmdTemplates(ctx) {
-	const sub = ctx.positionals[0];
-	const rest = { ...ctx, positionals: ctx.positionals.slice(1) };
-	switch (sub) {
-		case "list":
-		case "ls":
-			return templatesList(rest);
-		case "show":
-		case "get":
-			return templatesShow(rest);
-		case "create":
-		case "new":
-			return templatesCreate(rest);
-		case "update":
-			return templatesUpdate(rest);
-		case "delete":
-		case "rm":
-			return templatesDelete(rest);
-		default:
-			throw new CliError(
-				`Unknown templates subcommand: ${sub ?? "(none)"}. Try: list, show, create, update, delete`
-			);
-	}
-}
-
-async function templatesList(ctx) {
-	const { client, flags, io } = ctx;
-	const result = await client.callTool("list_templates", {});
-	printResult(io, flags, result, (r) => {
-		const custom = (r.templates ?? []).map((t) => `  ${t.key}  ${t.name} — ${t.angle} (id ${t.id})`);
-		const builtIn = (r.built_ins ?? []).map((t) => `  ${t.key}  ${t.name}`);
-		return [
-			custom.length ? "Custom templates:" : "No custom templates yet.",
-			...custom,
-			"",
-			"Built-in templates (read-only):",
-			...builtIn,
-		].join("\n");
-	});
-	return 0;
-}
-
-async function templatesShow(ctx) {
-	const { client, positionals, flags, io } = ctx;
-	const templateId = requirePositional(positionals, 0, "template-id");
-	const result = await client.callTool("get_template", { template_id: templateId });
-	printResult(io, flags, result);
-	return 0;
-}
-
-function templateBlocksFromFlags(flags) {
-	const inline = flagStr(flags.blocks);
-	const file = flagStr(flags["blocks-file"]);
-	if (inline === undefined && file === undefined) return undefined;
-	const raw = inline !== undefined ? inline : readFileOrThrow(file, "--blocks-file");
-	let parsed;
-	try {
-		parsed = JSON.parse(raw);
-	} catch (err) {
-		throw new CliError(`--blocks is not valid JSON: ${err.message}`);
-	}
-	if (!Array.isArray(parsed)) throw new CliError("--blocks must be a JSON array of block objects");
-	return parsed;
-}
-
-async function templatesCreate(ctx) {
-	const { client, flags, io } = ctx;
-	const name = flagStr(flags.name);
-	const angle = flagStr(flags.angle);
-	const blocks = templateBlocksFromFlags(flags);
-	if (!name) throw new CliError("Missing required --name");
-	// `--angle` is OPTIONAL, and omitting it is the better answer. It was required here while
-	// the server schema had already made it optional and the app had dropped the field: a
-	// template constrains a post's SHAPE and never says what it is about, so an angle belongs
-	// to the post — which already has one, from its research direction.
-	if (!blocks) throw new CliError("Missing required --blocks '<json>' or --blocks-file <path>");
-	const result = await client.callTool("create_template", { name, blocks, ...(angle ? { angle } : {}) });
-	ok(ctx, `Template created — key ${result.template?.key}.`);
-	printResult(io, flags, result);
-	return 0;
-}
-
-async function templatesUpdate(ctx) {
-	const { client, positionals, flags, io } = ctx;
-	const templateId = requirePositional(positionals, 0, "template-id");
-	const name = flagStr(flags.name);
-	const angle = flagStr(flags.angle);
-	const blocks = templateBlocksFromFlags(flags);
-	// update_template replaces the whole template; fetch current values for any
-	// field the caller didn't pass so a partial edit doesn't blank the rest.
-	let current;
-	if (!name || !angle || !blocks) {
-		const existing = await client.callTool("get_template", { template_id: templateId });
-		current = existing.template;
-	}
-	const result = await client.callTool("update_template", {
-		template_id: templateId,
-		name: name ?? current.name,
-		angle: angle ?? current.angle,
-		blocks: blocks ?? current.blocks,
-	});
-	ok(ctx, "Template updated.");
-	printResult(io, flags, result);
-	return 0;
-}
-
-async function templatesDelete(ctx) {
-	const { client, positionals, flags, io } = ctx;
-	const templateId = requirePositional(positionals, 0, "template-id");
-	if (!flagBool(flags.yes)) {
-		throw new CliError("Seers bound to this template fall back to defaults. Re-run with --yes to delete.");
-	}
-	const result = await client.callTool("delete_template", { template_id: templateId });
-	ok(ctx, "Template deleted.");
-	printResult(io, flags, result);
-	return 0;
-}

package/lib/commands/templates.mjs

@@ -0,0 +1,267 @@
+// `templates` — the Templates FORMAT: authoring it, and the two operations that make it
+// composable.
+//
+// MOVED OUT OF `seers.mjs` (2026-09-18) for the same reason `src/lib/templates/` moved out of
+// `src/lib/seers/`: a template stopped being seer-owned when collections, series and per-article
+// overrides started binding them, and two of the primitives that consume one have nothing to do
+// with seers at all.
+//
+// A template is not a primitive: no endpoint, no run, no balance, nothing to poll. It is a SHAPE
+// two primitives consume — what sections an article has, in what order, in what form. What it has
+// instead of a door is a RESOLUTION:
+//
+//   templates resolve <key>                    the SHAPE: feeds `arena run --template`
+//   templates resolve <key> --file material.md the PLAN too: skeleton, budget and brief for `kernel write`
+//   templates assemble --spans s.json --file a.md   a templated run's output, turned back into the article
+//
+// Resolve ONCE and pass `--constraints` back on every later call. Resolving twice is a model call
+// twice and two different sets of section labels — and the writer writes each section under its
+// label while assembly matches output back by that label, so a second resolution files sections
+// under headings the outline never planned.
+//
+// For a single write with no research, skip all of this: `kernel write --template <key>` resolves
+// through the same function and returns the article already assembled.
+
+import { readFileSync } from "node:fs";
+import { CliError } from "../client.mjs";
+import { flagStr, flagBool, requirePositional, printResult, ok, argsFromFlags, readBodyInput } from "./shared.mjs";
+
+/** `--<flag> <path>` → the file's parsed JSON, or undefined when the flag is not set. */
+function readJsonFileFlag(flags, flag) {
+	const path = flagStr(flags[flag]);
+	if (path === undefined) return undefined;
+	let text;
+	try {
+		text = readFileSync(path, "utf8");
+	} catch (error) {
+		throw new CliError(
+			`Could not read --${flag} ${path}: ${error instanceof Error ? error.message : String(error)}`
+		);
+	}
+	try {
+		return JSON.parse(text);
+	} catch {
+		throw new CliError(`--${flag} ${path} is not valid JSON.`);
+	}
+}
+
+/** Read a file, or throw a CLI error naming the flag that asked for it. */
+function readFileOrThrow(path, flag) {
+	try {
+		return readFileSync(path, "utf8");
+	} catch (error) {
+		throw new CliError(`Could not read ${flag} ${path}: ${error instanceof Error ? error.message : String(error)}`);
+	}
+}
+
+/** `--var Name=Value` (repeatable) → `{ Name: "Value" }`. */
+function variablesFromFlags(flags) {
+	const raw = flags.var;
+	if (raw === undefined) return undefined;
+	const list = Array.isArray(raw) ? raw : [raw];
+	const out = {};
+	for (const entry of list) {
+		const text = String(entry);
+		const eq = text.indexOf("=");
+		if (eq <= 0) throw new CliError(`--var must be Name=Value (got "${text}").`);
+		out[text.slice(0, eq).trim()] = text.slice(eq + 1).trim();
+	}
+	return Object.keys(out).length ? out : undefined;
+}
+
+/**
+ * How the RESOLVE and ASSEMBLE commands source their arguments — see `argsFromFlags` in
+ * shared.mjs, and `scripts/parity-check.ts`, which compares these keys against each tool's
+ * published input schema. The CRUD commands below predate the field-level ratchet and are
+ * covered by the frozen `UNMAPPED_TOOLS` list, which only shrinks.
+ */
+export const ARGS = {
+	resolve_template: {
+		key: { positional: 0, label: "template-key" },
+		blocks: { value: (flags) => readJsonFileFlag(flags, "blocks-file") },
+		title: "title",
+		material: { value: (flags) => readBodyInput(flags) },
+		variables: { value: variablesFromFlags },
+		constraints: { value: (flags) => readJsonFileFlag(flags, "constraints") },
+		// The brand a {Brand}-style variable names. Omitted = this org's own; an org with no
+		// positioning simply resolves no brand variable rather than failing.
+		brand: {
+			object: {
+				name: { flag: "brand" },
+				one_liner: { flag: "brand-one-liner" },
+			},
+		},
+	},
+	// Declared rather than re-frozen. These two were on the `UNMAPPED_TOOLS` list while they lived
+	// in `seers.mjs`; moving the file is not a reason to re-freeze them, and they are one
+	// positional each.
+	get_template: {
+		template_id: { positional: 0, label: "template-id", required: true },
+	},
+	delete_template: {
+		template_id: { positional: 0, label: "template-id", required: true },
+	},
+	assemble_template: {
+		spans: { value: (flags) => readJsonFileFlag(flags, "spans") },
+		article: { value: (flags) => readBodyInput(flags) },
+	},
+};
+
+export async function cmdTemplates(ctx) {
+	const sub = ctx.positionals[0];
+	const rest = { ...ctx, positionals: ctx.positionals.slice(1) };
+	switch (sub) {
+		case "list":
+		case "ls":
+			return templatesList(rest);
+		case "show":
+		case "get":
+			return templatesShow(rest);
+		case "create":
+		case "new":
+			return templatesCreate(rest);
+		case "update":
+			return templatesUpdate(rest);
+		case "delete":
+		case "rm":
+			return templatesDelete(rest);
+		case "resolve":
+			return templatesResolve(rest);
+		case "assemble":
+			return templatesAssemble(rest);
+		default:
+			throw new CliError(
+				`Unknown templates subcommand: ${sub ?? "(none)"}. Try: list, show, create, update, delete, resolve, assemble`
+			);
+	}
+}
+
+async function templatesList(ctx) {
+	const { client, flags, io } = ctx;
+	const result = await client.callTool("list_templates", {});
+	printResult(io, flags, result, (r) => {
+		const custom = (r.templates ?? []).map((t) => `  ${t.key}  ${t.name} — ${t.angle} (id ${t.id})`);
+		const builtIn = (r.built_ins ?? []).map((t) => `  ${t.key}  ${t.name}`);
+		return [
+			custom.length ? "Custom templates:" : "No custom templates yet.",
+			...custom,
+			"",
+			"Built-in templates (read-only):",
+			...builtIn,
+		].join("\n");
+	});
+	return 0;
+}
+
+async function templatesShow(ctx) {
+	const { client, positionals, flags, io } = ctx;
+	requirePositional(positionals, 0, "template-id");
+	const result = await client.callTool("get_template", argsFromFlags(ARGS.get_template, flags, positionals));
+	printResult(io, flags, result);
+	return 0;
+}
+
+function templateBlocksFromFlags(flags) {
+	const inline = flagStr(flags.blocks);
+	const file = flagStr(flags["blocks-file"]);
+	if (inline === undefined && file === undefined) return undefined;
+	const raw = inline !== undefined ? inline : readFileOrThrow(file, "--blocks-file");
+	let parsed;
+	try {
+		parsed = JSON.parse(raw);
+	} catch (err) {
+		throw new CliError(`--blocks is not valid JSON: ${err.message}`);
+	}
+	if (!Array.isArray(parsed)) throw new CliError("--blocks must be a JSON array of block objects");
+	return parsed;
+}
+
+async function templatesCreate(ctx) {
+	const { client, flags, io } = ctx;
+	const name = flagStr(flags.name);
+	const angle = flagStr(flags.angle);
+	const blocks = templateBlocksFromFlags(flags);
+	if (!name) throw new CliError("Missing required --name");
+	// `--angle` is OPTIONAL, and omitting it is the better answer. It was required here while
+	// the server schema had already made it optional and the app had dropped the field: a
+	// template constrains a post's SHAPE and never says what it is about, so an angle belongs
+	// to the post — which already has one, from its research direction.
+	if (!blocks) throw new CliError("Missing required --blocks '<json>' or --blocks-file <path>");
+	const result = await client.callTool("create_template", { name, blocks, ...(angle ? { angle } : {}) });
+	ok(ctx, `Template created — key ${result.template?.key}.`);
+	printResult(io, flags, result);
+	return 0;
+}
+
+async function templatesUpdate(ctx) {
+	const { client, positionals, flags, io } = ctx;
+	const templateId = requirePositional(positionals, 0, "template-id");
+	const name = flagStr(flags.name);
+	const angle = flagStr(flags.angle);
+	const blocks = templateBlocksFromFlags(flags);
+	// update_template replaces the whole template; fetch current values for any
+	// field the caller didn't pass so a partial edit doesn't blank the rest.
+	let current;
+	if (!name || !angle || !blocks) {
+		const existing = await client.callTool("get_template", { template_id: templateId });
+		current = existing.template;
+	}
+	const result = await client.callTool("update_template", {
+		template_id: templateId,
+		name: name ?? current.name,
+		angle: angle ?? current.angle,
+		blocks: blocks ?? current.blocks,
+	});
+	ok(ctx, "Template updated.");
+	printResult(io, flags, result);
+	return 0;
+}
+
+async function templatesDelete(ctx) {
+	const { client, positionals, flags, io } = ctx;
+	requirePositional(positionals, 0, "template-id");
+	if (!flagBool(flags.yes)) {
+		throw new CliError("Seers bound to this template fall back to defaults. Re-run with --yes to delete.");
+	}
+	const result = await client.callTool("delete_template", argsFromFlags(ARGS.delete_template, flags, positionals));
+	ok(ctx, "Template deleted.");
+	printResult(io, flags, result);
+	return 0;
+}
+
+/**
+ * `templates resolve <key> [--title t] [--body/--file material] [--var K=V] [--constraints c.json]`
+ *
+ * THE ONE PLACE A TEMPLATE BECOMES CONSTRAINTS. Without material: the SHAPE — `must_include`,
+ * `gather_hints`, `form_guidance`, which is what `arena run` takes. With it: the PLAN as well —
+ * `skeleton`, `target_word_count`, `brief`, `brief_json`, `spans`, which is what `kernel write`
+ * takes. Pass `--constraints` back on the second call so nothing is re-decided.
+ */
+async function templatesResolve(ctx) {
+	const { client, positionals, flags, io } = ctx;
+	const args = argsFromFlags(ARGS.resolve_template, flags, positionals);
+	if (args.key === undefined && args.blocks === undefined) {
+		throw new CliError(
+			"Name the template: `templates resolve <template-key>`, or --blocks-file <path> for an inline one."
+		);
+	}
+	const result = await client.callTool("resolve_template", args);
+	printResult(io, flags, result);
+	return 0;
+}
+
+/** `templates assemble --spans spans.json --file article.md` — the way back. */
+async function templatesAssemble(ctx) {
+	const { client, positionals, flags, io } = ctx;
+	const args = argsFromFlags(ARGS.assemble_template, flags, positionals);
+	if (args.spans === undefined) {
+		throw new CliError("--spans <path> is required: the spans `templates resolve` returned.");
+	}
+	if (args.article === undefined) {
+		throw new CliError("Provide the run's output with --body <text>, --file <path>, or --file - (stdin).");
+	}
+	const result = await client.callTool("assemble_template", args);
+	// The article itself, so `> post.html` works.
+	printResult(io, flags, result, (r) => r?.article ?? "");
+	return 0;
+}

package/lib/commands.mjs

@@ -20,6 +20,7 @@ export * from "./commands/series.mjs";
 export * from "./commands/insights.mjs";
 export * from "./commands/covers.mjs";
 export * from "./commands/arena.mjs";
+export * from "./commands/templates.mjs";
 export * from "./commands/autopen.mjs";
 export * from "./commands/kernel.mjs";
 export * from "./commands/phantom-job.mjs";

package/package.json

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