@letterstory/cli 0.25.2 → 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.2";
+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/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.2",
+	"version": "0.25.3",
 	"description": "Spin up and manage Letterstory phantom blogs from your terminal.",
 	"type": "module",
 	"license": "UNLICENSED",