@letterstory/cli 0.15.4 → 0.16.0

package/lib/cli.mjs

@@ -19,6 +19,7 @@ import {
 	cmdDomains,
 	cmdPosts,
 	cmdPublished,
+	cmdReviewers,
 	cmdCollections,
 	cmdAuthors,
 	cmdFlows,
@@ -43,7 +44,7 @@ import {
 } from "./commands.mjs";
 
 // Keep in sync with cli/package.json.
-export const VERSION = "0.15.4";
+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.
@@ -183,6 +184,13 @@ Content:
   published list [--limit <n>] [--collection <uuid>] [--format html|md]
   published show (--id <uuid> | --slug <slug>) [--format html|md]
 
+Reviewers:
+  reviewers standing list                             List the org's standing reviewers
+  reviewers standing add --email <e> [--name <n>]      Auto-invite this contact as a
+                                                         guest reviewer on every future
+                                                         finished draft (no email sent now)
+  reviewers standing remove <reviewer-id>              Stop future auto-invites
+
 Collections:
   collections list                                   List your collections
   collections new --name <n> [--description <text>]
@@ -422,7 +430,17 @@ Shredder (diversify content produced outside Letterstory; structure preserved):
   shredder create --name <n>                           New endpoint (returns a callable public id)
   shredder delete <endpoint-id> --yes
   shredder run <endpoint-id> (--body <text>|--file <path>|--file -) [--coverage <0..1>] [--attempts <n>]
-                                                       Shred prose through an endpoint (logs telemetry)
+                                                       [--aggression standard|high|max]
+                                                       standard (default) keeps the piece's own terminology;
+                                                       high rewrites more and may reword recurring terms;
+                                                       max rewrites hardest — expect vocabulary drift
+                                                       [--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):
@@ -482,6 +500,7 @@ const CLIENT_COMMANDS = {
 	domains: cmdDomains,
 	posts: cmdPosts,
 	published: cmdPublished,
+	reviewers: cmdReviewers,
 	collections: cmdCollections,
 	authors: cmdAuthors,
 	flows: cmdFlows,

package/lib/commands/reviewers.mjs

@@ -0,0 +1,62 @@
+// `reviewers standing` — an org's standing reviewers (organization_standing_reviewers):
+// external contacts auto-invited as a guest reviewer on every article that reaches a
+// finished, never-published draft (src/lib/services/standing-reviewers.ts + the
+// notify-standing-reviewers cron), instead of inviting them by hand on each article.
+// Same flag/positional/io conventions as posts.mjs — no commander, no color.
+
+import { CliError } from "../client.mjs";
+import { flagStr, requireFlag, requirePositional, printResult, compact, ok } from "./shared.mjs";
+
+export async function cmdReviewers(ctx) {
+	const sub = ctx.positionals[0];
+	const rest = { ...ctx, positionals: ctx.positionals.slice(1) };
+	switch (sub) {
+		case "standing":
+			return cmdStandingReviewers(rest);
+		default:
+			throw new CliError(`Unknown reviewers subcommand: ${sub ?? "(none)"}. Try: standing`);
+	}
+}
+
+async function cmdStandingReviewers(ctx) {
+	const sub = ctx.positionals[0];
+	const rest = { ...ctx, positionals: ctx.positionals.slice(1) };
+	switch (sub) {
+		case "list":
+		case "ls":
+			return standingList(rest);
+		case "add":
+			return standingAdd(rest);
+		case "remove":
+		case "rm":
+			return standingRemove(rest);
+		default:
+			throw new CliError(`Unknown reviewers standing subcommand: ${sub ?? "(none)"}. Try: list, add, remove`);
+	}
+}
+
+async function standingList(ctx) {
+	const { client, flags, io } = ctx;
+	const result = await client.callTool("list_standing_reviewers", {});
+	printResult(io, flags, result);
+	return 0;
+}
+
+async function standingAdd(ctx) {
+	const { client, flags, io } = ctx;
+	const email = requireFlag(flags, "email");
+	const args = compact({ email, name: flagStr(flags.name) });
+	const result = await client.callTool("add_standing_reviewer", args);
+	ok(ctx, `Added ${email} as a standing reviewer.`);
+	printResult(io, flags, result);
+	return 0;
+}
+
+async function standingRemove(ctx) {
+	const { client, positionals, flags, io } = ctx;
+	const id = requirePositional(positionals, 0, "reviewer-id");
+	const result = await client.callTool("remove_standing_reviewer", { reviewer_id: id });
+	ok(ctx, "Removed.");
+	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,14 +92,78 @@ 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,
 		coverage: flagNum(flags.coverage),
 		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/lib/commands.mjs

@@ -9,6 +9,7 @@ export * from "./commands/discovery.mjs";
 export * from "./commands/deploy.mjs";
 export * from "./commands/mcp.mjs";
 export * from "./commands/posts.mjs";
+export * from "./commands/reviewers.mjs";
 export * from "./commands/collections.mjs";
 export * from "./commands/authors.mjs";
 export * from "./commands/flows.mjs";

package/package.json

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