@letterstory/cli 0.25.1 → 0.25.3

package/lib/cli.mjs

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

@@ -78,28 +78,32 @@ export const ARGS = {
 		// it from a path. Omit both to write from the article as it stands.
 		brief: { value: (flags) => flagStr(flags.brief) ?? readBodyInput({ file: flagStr(flags["brief-file"]) }) },
 	},
-	// The standalone door. Two subcommands share this one tool: `write` sends a `brief`,
-	// `polish` sends a `document`; the map is one, so a field the tool gains is a field
-	// BOTH subcommands must learn (or knowingly gap) — that is the ratchet.
+	// The standalone door. Two subcommands share this one tool: `write` and `polish` both
+	// send `input`, `polish` forcing content_kind to "document" — the map is one, so a field
+	// the tool gains is a field BOTH subcommands must learn (or knowingly gap) — that is the
+	// ratchet.
 	run_kernel: {
 		endpoint_id: { positional: 0, label: "endpoint-id", required: true },
-		brief: { value: (flags, _p, extra) => (extra.door === "brief" ? readBodyInput(flags) : undefined) },
-		document: { value: (flags, _p, extra) => (extra.door === "document" ? readBodyInput(flags) : undefined) },
-		// Documented dead field on the tool; accepted so an old --format still validates.
-		format: { flag: "format", enum: ["auto", "html", "markdown"] },
+		input: { value: (flags) => readBodyInput(flags) },
 		kernel_id: "kernel",
 		target_word_count: { flag: "words", type: "num" },
-		content_type: "content-type",
+		label: "label",
 		// The flag is --read-as, which is what shipped; an earlier draft called it --brief-mode.
-		brief_mode: { flag: "read-as", enum: ["auto", "brief", "content", "blog", "outline", "research", "notes"] },
+		content_kind: {
+			flag: "read-as",
+			enum: ["auto", "instruction", "document", "article", "outline", "research", "notes"],
+		},
 		// The two products, in one run: every round is shredded before the kernel's jury sees
 		// it, so the verdict lands on the text that actually ships. Costs a shred as well as a
 		// run.
 		shredder_endpoint_id: "shredder",
 		shred_aggression: { flag: "shred-aggression", enum: ["standard", "high", "max"] },
-		person: { flag: "person", enum: ["third", "first_plural", "first_singular"] },
-		author_name: "author",
-		allow_experience_claims: { flag: "experience-claims", type: "bool" },
+		voice: {
+			object: {
+				person: { flag: "person", enum: ["third", "first_plural", "first_singular"] },
+				allow_experience_claims: { flag: "experience-claims", type: "bool" },
+			},
+		},
 		// The mechanism's full contract, declared on the door (2026-09-17, Kernels wave step 1).
 		// A shape and a typed brief are files, not flags — `--skeleton-file shape.json` is the
 		// field a template resolves to, sent by a caller who has their own.
@@ -123,12 +127,13 @@ export const ARGS = {
 				evidence: { value: (flags) => readTextFileFlag(flags, "shred-evidence-file") },
 			},
 		},
-		// Named-entity treatment (2026-09-17): a list, not a scalar flag, so it's a file like
-		// skeleton/brief_json — `--entities-file entities.json` of `[{"name":"...","treatment":
-		// "never"|"name_only"|"subtle"|"woven"|"lead"}, ...]`.
+		// Named-entity treatment (2026-09-17, renamed 2026-09-18): a list, not a scalar flag,
+		// so it's a file like skeleton/brief_json — `--entities-file entities.json` of
+		// `[{"name":"...","treatment":"never"|"mention_once"|"mention_often"|"lead_company",
+		// "linkable":false}, ...]` (linkable optional, default true).
 		entities: { value: (flags) => readJsonFileFlag(flags, "entities-file") },
-		// document-only: hold the document's own shape through the edit. Default true; pass
-		// --no-preserve-shape to let the kernel restructure freely.
+		// content_kind "document" only: hold the document's own shape through the edit. Default
+		// true; pass --no-preserve-shape to let the kernel restructure freely.
 		preserve_shape: { flag: "preserve-shape", type: "bool" },
 	},
 	create_kernel_endpoint: {
@@ -228,8 +233,8 @@ async function kernelEndpoints(ctx) {
 
 async function kernelWrite(ctx) {
 	const { client, positionals, flags, io } = ctx;
-	const args = argsFromFlags(ARGS.run_kernel, flags, positionals, { door: "brief" });
-	if (args.brief === undefined) {
+	const args = argsFromFlags(ARGS.run_kernel, flags, positionals);
+	if (args.input === undefined) {
 		throw new CliError("Provide the brief with --body <text>, --file <path>, or --file - (stdin).");
 	}
 	const result = await client.callTool("run_kernel", args);
@@ -322,22 +327,24 @@ async function kernelEndpoint(ctx) {
 
 /**
  * The OTHER door: run the same pipeline against a document you already have, instead of
- * writing a new one. Skips generation only — the rules, the in-loop shred and the jury all
- * still run, which is what keeps your own markup (images, embeds, links, tables, anchors,
- * shortcodes) intact through a real pass rather than an unguarded shortcut.
+ * writing a new one. Decomposed into a brief and GENERATED FRESH (content_kind: "document",
+ * forced below) — not edited in place — with your own headings and embedded media (images,
+ * tables) extracted first and spliced back into the generated draft afterward, so they
+ * survive a pass that would otherwise be text-only and lose them.
  *
  * ASYNCHRONOUS, same as `write` — this used to be a separate, synchronous, unmetered "polish"
- * that answered in one request. That path was deleted (2026-09-15, letterstory#1783): it
- * worked by skipping the rules and the jury, and that was the actual cost of being instant
- * and free. `document` now costs a run and follows the identical submit-and-poll shape
+ * that answered in one request, and before that an EARLIER `document` mode that skipped
+ * generation to hold shape "in place." Neither exists any more (2026-09-15, letterstory#1783;
+ * 2026-09-17). `document` now costs a run and follows the identical submit-and-poll shape
  * `write` does, so this command does too — `--no-wait` behaves the same way here.
  */
 async function kernelPolish(ctx) {
 	const { client, positionals, flags, io } = ctx;
-	const args = argsFromFlags(ARGS.run_kernel, flags, positionals, { door: "document" });
-	if (args.document === undefined) {
+	const args = argsFromFlags(ARGS.run_kernel, flags, positionals);
+	if (args.input === undefined) {
 		throw new CliError("Provide the document with --body <text>, --file <path>, or --file - (stdin).");
 	}
+	args.content_kind = args.content_kind ?? "document";
 	const result = await client.callTool("run_kernel", args);
 	const runId = toolField(result, "run_id");
 	if (!runId) {

package/lib/commands/shredder.mjs

@@ -1,44 +1,101 @@
 // `shredder` — create shredder endpoints and run content produced OUTSIDE Letterstory
 // through the cross-provider shredder. A shred rewrites each sentence across multiple
 // LLM providers to diversify, leaving structure (headings, lists, tables) untouched, and
-// logs every call to telemetry.
+// logs every call to telemetry against the org's shred balance.
 
+import { readFileSync } from "node:fs";
 import { CliError } from "../client.mjs";
 import {
 	flagStr,
-	flagNum,
-	requireFlag,
 	requirePositional,
 	readBodyInput,
 	printResult,
-	compact,
 	ok,
 	toolField,
 	followJob,
 	argsFromFlags,
 } 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.`);
+	}
+}
+
+/** `--<flag> <path>` → the file's text, or undefined when the flag is not set. */
+function readTextFileFlag(flags, flag) {
+	const path = flagStr(flags[flag]);
+	if (path === undefined) return undefined;
+	try {
+		return readFileSync(path, "utf8");
+	} catch (error) {
+		throw new CliError(
+			`Could not read --${flag} ${path}: ${error instanceof Error ? error.message : String(error)}`
+		);
+	}
+}
+
 /**
- * How `shredder run` sources `run_shred`'s inputs — see `argsFromFlags` in shared.mjs and
- * `scripts/parity-check.ts`, which diffs these keys against the tool's published schema.
- * The rest of this module predates the ratchet and stays in UNMAPPED_TOOLS.
+ * How every command in this file sources its tool's inputs — see `argsFromFlags` in
+ * shared.mjs and `scripts/parity-check.ts`, which diffs these keys against each tool's
+ * published schema. Every shredder tool is mapped: a field added to one of them and
+ * forgotten here fails CI.
  */
 export const ARGS = {
 	run_shred: {
 		endpoint_id: { positional: 0, label: "endpoint-id", required: true },
 		text: { value: (flags) => readBodyInput(flags) },
-		coverage: { flag: "coverage", type: "num" },
-		attempts_per_unit: { flag: "attempts", type: "num" },
 		// What the text IS. Without this an HTML file could only go through the `auto`
 		// heuristic, which misreads a markdown post carrying an embed.
 		format: { flag: "format", enum: ["auto", "html", "markdown"] },
 		// How hard to rewrite. Validated service-side; sent only when the caller asked.
 		aggression: { flag: "aggression", enum: ["standard", "high", "max"] },
+		coverage: { flag: "coverage", type: "num" },
+		attempts_per_unit: { flag: "attempts", type: "num" },
 		// Hold every rewrite to the live writing rules. A trade, not a free win.
 		apply_rules: { flag: "apply-rules", type: "bool" },
+		// The facts each rewrite must conserve — a file, since it is a document's worth of text.
+		evidence: { value: (flags) => readTextFileFlag(flags, "evidence-file") },
 		// ASYNCHRONOUS BY DEFAULT — `--sync` is the opt-out (see shredderRun for why).
 		async: { value: (flags) => (flags.sync === true ? undefined : true) },
 	},
+	get_shred_job: {
+		job_id: { positional: 0, label: "job-id", required: true },
+	},
+	list_shred_runs: {
+		endpoint_id: "endpoint",
+		limit: { flag: "limit", type: "num" },
+	},
+	list_shredder_endpoints: {},
+	get_shred_balance: {},
+	create_shredder_endpoint: {
+		name: { flag: "name", required: true },
+	},
+	delete_shredder_endpoint: {
+		endpoint_id: { positional: 1, label: "endpoint-id", required: true },
+	},
+	// The endpoint's configuration as ONE file: `shredder endpoint config <id>` prints it,
+	// `shredder endpoint config <id> --file cfg.json` replaces it with the file's document.
+	get_shredder_endpoint_config: {
+		endpoint_id: { positional: 1, label: "endpoint-id", required: true },
+	},
+	set_shredder_endpoint_config: {
+		endpoint_id: { positional: 1, label: "endpoint-id", required: true },
+		config: { value: (flags) => readJsonFileFlag(flags, "file") },
+	},
 };
 
 export async function cmdShredder(ctx) {
@@ -54,6 +111,8 @@ export async function cmdShredder(ctx) {
 		case "delete":
 		case "rm":
 			return shredderDelete(rest);
+		case "endpoint":
+			return shredderEndpoint(rest);
 		case "run":
 		case "shred":
 			return shredderRun(rest);
@@ -63,25 +122,27 @@ export async function cmdShredder(ctx) {
 		case "runs":
 		case "telemetry":
 			return shredderRuns(rest);
+		case "balance":
+			return shredderBalance(rest);
 		default:
 			throw new CliError(
-				`Unknown shredder subcommand: ${sub ?? "(none)"}. Try: list, create, delete, run, job, runs`
+				`Unknown shredder subcommand: ${sub ?? "(none)"}. Try: list, create, delete, endpoint, run, job, runs, balance`
 			);
 	}
 }
 
 async function shredderList(ctx) {
 	const { client, flags, io } = ctx;
-	const result = await client.callTool("list_shredder_endpoints", {});
+	const result = await client.callTool("list_shredder_endpoints", argsFromFlags(ARGS.list_shredder_endpoints, flags));
 	printResult(io, flags, result);
 	return 0;
 }
 
 async function shredderCreate(ctx) {
-	const { client, flags, io } = ctx;
-	const name = requireFlag(flags, "name");
-	const result = await client.callTool("create_shredder_endpoint", { name });
-	ok(ctx, `Created shredder endpoint "${name}".`);
+	const { client, flags, positionals, io } = ctx;
+	const args = argsFromFlags(ARGS.create_shredder_endpoint, flags, positionals);
+	const result = await client.callTool("create_shredder_endpoint", args);
+	ok(ctx, `Created shredder endpoint "${args.name}".`);
 	printResult(io, flags, result);
 	return 0;
 }
@@ -93,12 +154,55 @@ async function shredderDelete(ctx) {
 		io.error(`Re-run with --yes to confirm: ${ctx.bin} shredder delete ${id} --yes`);
 		return 1;
 	}
+	// `shredder delete <id>` and `shredder endpoint delete <id>` are the same act; the ARGS
+	// map is written for the latter's positional layout.
 	const result = await client.callTool("delete_shredder_endpoint", { endpoint_id: id });
 	ok(ctx, "Shredder endpoint deleted.");
 	printResult(io, flags, result);
 	return 0;
 }
 
+/**
+ * `shredder endpoint config|delete` — the endpoint's own configuration and lifecycle, the
+ * same shape `kernel endpoint …` has, so the two primitives read the same way.
+ */
+async function shredderEndpoint(ctx) {
+	const { client, positionals, flags, io } = ctx;
+	const action = positionals[0];
+	if (action === "delete" || action === "rm") {
+		const id = requirePositional(positionals, 1, "endpoint-id");
+		if (!flags.yes) {
+			io.error(`Re-run with --yes to confirm: ${ctx.bin} shredder endpoint delete ${id} --yes`);
+			return 1;
+		}
+		const result = await client.callTool(
+			"delete_shredder_endpoint",
+			argsFromFlags(ARGS.delete_shredder_endpoint, flags, positionals)
+		);
+		ok(ctx, "Shredder endpoint deleted.");
+		printResult(io, flags, result);
+		return 0;
+	}
+	if (action === "config") {
+		const id = requirePositional(positionals, 1, "endpoint-id");
+		if (flagStr(flags.file) === undefined) {
+			const result = await client.callTool(
+				"get_shredder_endpoint_config",
+				argsFromFlags(ARGS.get_shredder_endpoint_config, flags, positionals)
+			);
+			// The document itself, so `> cfg.json` round-trips into `--file cfg.json`.
+			printResult(io, flags, result, (r) => JSON.stringify(r?.config ?? r, null, 2));
+			return 0;
+		}
+		const args = argsFromFlags(ARGS.set_shredder_endpoint_config, flags, positionals);
+		const result = await client.callTool("set_shredder_endpoint_config", args);
+		ok(ctx, `Replaced the configuration of shredder endpoint ${id}.`);
+		printResult(io, flags, result);
+		return 0;
+	}
+	throw new CliError(`Unknown shredder endpoint action: ${action ?? "(none)"}. Try: config, delete`);
+}
+
 /**
  * How long to wait between polls of a queued shred, and for how long in total.
  *
@@ -175,19 +279,21 @@ const readStatus = (result) => toolField(result, "status");
 
 async function shredderJob(ctx) {
 	const { client, positionals, flags, io } = ctx;
-	const jobId = requirePositional(positionals, 0, "job-id");
-	const result = await client.callTool("get_shred_job", { job_id: jobId });
+	const result = await client.callTool("get_shred_job", argsFromFlags(ARGS.get_shred_job, flags, positionals));
 	printResult(io, flags, result);
 	return 0;
 }
 
 async function shredderRuns(ctx) {
 	const { client, flags, io } = ctx;
-	const args = compact({
-		endpoint_id: flagStr(flags.endpoint),
-		limit: flagNum(flags.limit),
-	});
-	const result = await client.callTool("list_shred_runs", args);
+	const result = await client.callTool("list_shred_runs", argsFromFlags(ARGS.list_shred_runs, flags));
+	printResult(io, flags, result);
+	return 0;
+}
+
+async function shredderBalance(ctx) {
+	const { client, flags, io } = ctx;
+	const result = await client.callTool("get_shred_balance", argsFromFlags(ARGS.get_shred_balance, flags));
 	printResult(io, flags, result);
 	return 0;
 }

package/package.json

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