@letterstory/cli 0.16.0 → 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.16.0";
+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

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/package.json

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