@letterstory/cli 0.15.5 → 0.16.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.16.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.
@@ -434,7 +434,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/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.16.0",
 	"description": "Spin up and manage Letterstory phantom blogs from your terminal.",
 	"type": "module",
 	"license": "UNLICENSED",