@letterstory/cli 0.15.5 → 0.17.0

package/lib/cli.mjs

@@ -44,7 +44,7 @@ import {
 } from "./commands.mjs";
 
 // Keep in sync with cli/package.json.
-export const VERSION = "0.15.5";
+export const VERSION = "0.17.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.
@@ -290,10 +290,26 @@ Cover images (which image model draws the post's cover):
 
 Writing kernels (kernels write the draft; they do not research — run research first):
   kernel list                                          List available writing kernels
+
+  Into an article you already have (metered on the AI-usage gate):
   kernel run --article <uuid> --kernel <uuid> [--brief <text>|--brief-file <path>]
                                                         Submit a run; takes 15-20 min
   kernel status <kernel-job-id>                        Check a run's status
 
+  Standalone — prose back, nothing saved into an article (metered in kernel-run credits):
+  kernel endpoints                                     Your kernel endpoints
+  kernel write <endpoint-id> (--body <text>|--file <path>|--file -)
+                             [--kernel <uuid>] [--words <n>] [--no-wait]
+                                                        WRITE a new article from a headline,
+                                                        outline, notes or a finished post.
+                                                        Follows the run unless --no-wait.
+  kernel polish <endpoint-id> (--body <html>|--file <path>) [--format auto|html]
+                                                        POLISH the document you have: prose
+                                                        reworded, your own markup kept
+  kernel run-status <run-id>                           Poll a write started with 'kernel write'
+  kernel runs [--endpoint <id>] [--limit <n>]          Recent endpoint writes (telemetry)
+  kernel balance                                       Kernel runs left on this org
+
 Phantom orchestrator:
   phantom-job create --topic <text> --collection <uuid> [--kernel <uuid>]
                                                         Topic -> draft -> publish -> rebuild
@@ -434,7 +450,13 @@ Shredder (diversify content produced outside Letterstory; structure preserved):
                                                        standard (default) keeps the piece's own terminology;
                                                        high rewrites more and may reword recurring terms;
                                                        max rewrites hardest — expect vocabulary drift
-                                                       Shred prose through an endpoint (logs telemetry)
+                                                       [--no-wait]  queue it and print the job id, don't follow it
+                                                       [--sync]     wait inside one request (only for a few
+                                                                    sentences — anything longer is cut off)
+                                                       Shred prose through an endpoint (logs telemetry).
+                                                       Queues the work and follows it; a shred takes minutes
+                                                       and keeps running on the server if you stop waiting.
+  shredder job <job-id>                                Poll a queued shred and print it when it lands
   shredder runs [--endpoint <id>] [--limit <n>]        Recent shred calls (telemetry), newest first
 
 Landings (a link + context; auto-mentioned in articles by collections you enable):

package/lib/commands/kernel.mjs

@@ -1,7 +1,19 @@
-// `kernel` — list writing kernels, submit a run against an article, and check a
-// run's status. A run can take 15-20 minutes, so unlike `deploy create` this does
-// not block waiting for it: `run` returns as soon as the job is queued and `status`
-// checks on demand, same shape as `flows run` / `flows status`.
+// `kernel` — the writing kernels, on both of their doors.
+//
+// TWO PRODUCTS SHARE THIS NOUN, and the subcommands are split along that line because
+// confusing them wastes fifteen minutes and a credit:
+//
+//   kernel run/status        writes INTO an article you already have (submit_kernel_run).
+//                            Metered on the AI-usage gate; needs --article.
+//   kernel write/…           the STANDALONE endpoint (run_kernel) — you get prose back and
+//                            nothing is saved into an article. Metered in kernel-run
+//                            credits, the balance the Kernels page shows.
+//
+// The standalone door had MCP tools and no CLI at all, so the only way to reach the product
+// the Kernels page bills for was `letterstory mcp call run_kernel` with hand-written JSON.
+//
+// Neither door blocks: a write runs for minutes, so `write` submits and then follows the run
+// unless you tell it not to.
 
 import { CliError } from "../client.mjs";
 import { flagStr, requireFlag, requirePositional, printResult, compact, ok, readBodyInput } from "./shared.mjs";
@@ -17,8 +29,22 @@ export async function cmdKernel(ctx) {
 			return kernelRun(rest);
 		case "status":
 			return kernelStatus(rest);
+		case "endpoints":
+			return kernelEndpoints(rest);
+		case "write":
+			return kernelWrite(rest);
+		case "polish":
+			return kernelPolish(rest);
+		case "run-status":
+			return kernelRunStatus(rest);
+		case "runs":
+			return kernelRuns(rest);
+		case "balance":
+			return kernelBalance(rest);
 		default:
-			throw new CliError(`Unknown kernel subcommand: ${sub ?? "(none)"}. Try: list, run, status`);
+			throw new CliError(
+				`Unknown kernel subcommand: ${sub ?? "(none)"}. Try: list, endpoints, write, polish, run-status, runs, balance, run, status`
+			);
 	}
 }
 
@@ -48,3 +74,122 @@ async function kernelStatus(ctx) {
 	printResult(io, flags, result);
 	return 0;
 }
+
+/* ------------------------------------------------------------------ */
+/* The standalone endpoint: prose back, nothing written into an article */
+/* ------------------------------------------------------------------ */
+
+/** A kernel write runs for minutes (median ~8), so this is about feeling alive. */
+const POLL_INTERVAL_MS = 20_000;
+/** Stop following after this; the run keeps going and `run-status` picks it up. */
+const POLL_CEILING_MS = 45 * 60 * 1000;
+
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+/** The tool result is a text payload holding JSON; pull one field out, leniently. */
+function readToolField(result, field) {
+	const raw = result?.content?.[0]?.text;
+	if (typeof raw !== "string") return undefined;
+	try {
+		return JSON.parse(raw)?.[field];
+	} catch {
+		return undefined;
+	}
+}
+
+async function kernelEndpoints(ctx) {
+	const { client, flags, io } = ctx;
+	const result = await client.callTool("list_kernel_endpoints", {});
+	printResult(io, flags, result);
+	return 0;
+}
+
+async function kernelWrite(ctx) {
+	const { client, positionals, flags, io } = ctx;
+	const endpointId = requirePositional(positionals, 0, "endpoint-id");
+	const brief = readBodyInput(flags);
+	if (brief === undefined) {
+		throw new CliError("Provide the brief with --body <text>, --file <path>, or --file - (stdin).");
+	}
+	const args = compact({
+		endpoint_id: endpointId,
+		brief,
+		kernel_id: flagStr(flags.kernel),
+		target_word_count: flags.words === undefined ? undefined : Number(flags.words),
+		content_type: flagStr(flags["content-type"]),
+	});
+	const result = await client.callTool("run_kernel", args);
+	const runId = readToolField(result, "run_id");
+	if (!runId) {
+		printResult(io, flags, result);
+		return 0;
+	}
+	if (flags["no-wait"] === true) {
+		ok(ctx, `Write started as ${runId}. Follow it with: letterstory kernel run-status ${runId}`);
+		printResult(io, flags, result);
+		return 0;
+	}
+
+	ok(ctx, `Write started as ${runId}. Waiting — this keeps running on the server if you stop.`);
+	const deadline = Date.now() + POLL_CEILING_MS;
+	for (;;) {
+		await sleep(POLL_INTERVAL_MS);
+		const polled = await client.callTool("get_kernel_endpoint_run", { run_id: runId });
+		const status = readToolField(polled, "status");
+		if (status && status !== "running") {
+			ok(ctx, `Write ${status}.`);
+			printResult(io, flags, polled);
+			return status === "done" ? 0 : 1;
+		}
+		if (Date.now() > deadline) {
+			ok(ctx, `Still running after 45 minutes. Follow it with: letterstory kernel run-status ${runId}`);
+			printResult(io, flags, polled);
+			return 0;
+		}
+	}
+}
+
+/** The OTHER door: reword the document you already have, keeping its own markup. */
+async function kernelPolish(ctx) {
+	const { client, positionals, flags, io } = ctx;
+	const endpointId = requirePositional(positionals, 0, "endpoint-id");
+	const document = readBodyInput(flags);
+	if (document === undefined) {
+		throw new CliError("Provide the document with --body <text>, --file <path>, or --file - (stdin).");
+	}
+	const args = compact({
+		endpoint_id: endpointId,
+		document,
+		format: flagStr(flags.format),
+	});
+	// Synchronous by nature: a polish is one pass over the sentences, not a multi-round write.
+	const result = await client.callTool("run_kernel", args);
+	printResult(io, flags, result);
+	return 0;
+}
+
+async function kernelRunStatus(ctx) {
+	const { client, positionals, flags, io } = ctx;
+	const runId = requirePositional(positionals, 0, "run-id");
+	const result = await client.callTool("get_kernel_endpoint_run", { run_id: runId });
+	printResult(io, flags, result);
+	return 0;
+}
+
+async function kernelRuns(ctx) {
+	const { client, flags, io } = ctx;
+	const args = compact({
+		endpoint_id: flagStr(flags.endpoint),
+		limit: flags.limit === undefined ? undefined : Number(flags.limit),
+	});
+	const result = await client.callTool("list_kernel_endpoint_runs", args);
+	printResult(io, flags, result);
+	return 0;
+}
+
+async function kernelBalance(ctx) {
+	const { client, flags, io } = ctx;
+	const result = await client.callTool("get_kernel_run_balance", {});
+	printResult(io, flags, result);
+	return 0;
+}

package/lib/commands/shredder.mjs

@@ -31,11 +31,16 @@ export async function cmdShredder(ctx) {
 		case "run":
 		case "shred":
 			return shredderRun(rest);
+		case "job":
+		case "poll":
+			return shredderJob(rest);
 		case "runs":
 		case "telemetry":
 			return shredderRuns(rest);
 		default:
-			throw new CliError(`Unknown shredder subcommand: ${sub ?? "(none)"}. Try: list, create, delete, run, runs`);
+			throw new CliError(
+				`Unknown shredder subcommand: ${sub ?? "(none)"}. Try: list, create, delete, run, job, runs`
+			);
 	}
 }
 
@@ -68,6 +73,18 @@ async function shredderDelete(ctx) {
 	return 0;
 }
 
+/**
+ * How long to wait between polls of a queued shred, and for how long in total.
+ *
+ * A shred runs for minutes and starts on the next advance-shreds tick, so the interval is
+ * about feeling alive rather than being quick. The ceiling exists so `--wait` on a document
+ * that will never finish returns the job id instead of hanging a terminal forever.
+ */
+const POLL_INTERVAL_MS = 15_000;
+const POLL_CEILING_MS = 30 * 60 * 1000;
+
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
 async function shredderRun(ctx) {
 	const { client, positionals, flags, io } = ctx;
 	const id = requirePositional(positionals, 0, "endpoint-id");
@@ -75,6 +92,14 @@ async function shredderRun(ctx) {
 	if (text === undefined) {
 		throw new CliError("Provide the prose to shred with --body <text>, --file <path>, or --file - (stdin).");
 	}
+	// ASYNCHRONOUS BY DEFAULT, and `--sync` is the opt-out rather than the other way round.
+	//
+	// A shred has no workable synchronous ceiling — the identical article took 203s, 541s and
+	// 599s against the live service — and the MCP endpoint behind this is a 300s function. A
+	// synchronous run on anything past a few sentences is killed by the platform before it can
+	// answer, so the caller gets no text, no error, and no record. Defaulting the other way
+	// made the common case the broken one.
+	const sync = flags.sync === true;
 	const args = compact({
 		endpoint_id: id,
 		text,
@@ -82,9 +107,63 @@ async function shredderRun(ctx) {
 		attempts_per_unit: flagNum(flags.attempts),
 		// How hard to rewrite. Validated service-side; sent only when the caller asked.
 		...(flags.aggression ? { aggression: String(flags.aggression) } : {}),
+		...(sync ? {} : { async: true }),
 	});
 	const result = await client.callTool("run_shred", args);
-	ok(ctx, "Shred complete.");
+	if (sync) {
+		ok(ctx, "Shred complete.");
+		printResult(io, flags, result);
+		return 0;
+	}
+
+	const jobId = readJobId(result);
+	if (!jobId) {
+		// The service answered something we do not recognise. Show it rather than swallow it.
+		printResult(io, flags, result);
+		return 0;
+	}
+	if (flags.wait === false || flags["no-wait"] === true) {
+		ok(ctx, `Shred queued as ${jobId}. Poll it with: letterstory shredder job ${jobId}`);
+		printResult(io, flags, result);
+		return 0;
+	}
+
+	ok(ctx, `Shred queued as ${jobId}. Waiting — this keeps running on the server if you stop.`);
+	const deadline = Date.now() + POLL_CEILING_MS;
+	for (;;) {
+		await sleep(POLL_INTERVAL_MS);
+		const polled = await client.callTool("get_shred_job", { job_id: jobId });
+		const status = readStatus(polled);
+		if (status && status !== "queued" && status !== "running") {
+			ok(ctx, `Shred ${status}.`);
+			printResult(io, flags, polled);
+			return status === "done" ? 0 : 1;
+		}
+		if (Date.now() > deadline) {
+			ok(ctx, `Still ${status ?? "running"} after 30 minutes. Poll it with: letterstory shredder job ${jobId}`);
+			printResult(io, flags, polled);
+			return 0;
+		}
+	}
+}
+
+/** The tool result is a text payload holding JSON; pull one field out of it, leniently. */
+function readToolField(result, field) {
+	const raw = result?.content?.[0]?.text;
+	if (typeof raw !== "string") return undefined;
+	try {
+		return JSON.parse(raw)?.[field];
+	} catch {
+		return undefined;
+	}
+}
+const readJobId = (result) => readToolField(result, "job_id");
+const readStatus = (result) => readToolField(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 });
 	printResult(io, flags, result);
 	return 0;
 }

package/package.json

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