@letterstory/cli 0.19.0 → 0.23.0

package/lib/commands/shared.mjs

@@ -53,6 +53,138 @@ export function compact(obj) {
 	return out;
 }
 
+// Flags every command accepts: transport, output shape, and the ones the runner
+// consumes before a command ever sees them.
+export const GLOBAL_FLAGS = new Set([
+	"url",
+	"key",
+	"staff-key",
+	"json",
+	"quiet",
+	"verbose",
+	"help",
+	"version",
+	"yes",
+	"no-color",
+	"profile",
+]);
+
+/**
+ * Refuse a flag this command does not understand.
+ *
+ * On a WRITE command an unrecognised flag is not cosmetic. `phantom-onboard
+ * collection --status` used to fall straight through to `onboard_collection`
+ * and START A SECOND ONBOARDING — a read verb that spent money and left a
+ * duplicate collection behind — because nothing checked that `--status` meant
+ * anything here. Its sibling `phantom-onboard domain --status` reads, so the
+ * same flag meant "read" on one subcommand and "spend" on the other.
+ *
+ * `own` is the flags the command handles itself; the ARGS map supplies the
+ * rest, so the map that BUILDS the call is also the list of what may be passed
+ * to it — one source, the same principle the maps exist for.
+ */
+export function refuseUnknownFlags(ctx, argsMap, own = []) {
+	const allowed = new Set([...GLOBAL_FLAGS, ...own]);
+	for (const source of Object.values(argsMap ?? {})) {
+		if (typeof source === "string") allowed.add(source);
+		else if (Array.isArray(source)) source.forEach((f) => allowed.add(f));
+		else if (source && typeof source === "object" && source.flag) allowed.add(source.flag);
+	}
+	const unknown = Object.keys(ctx.flags).filter((f) => !allowed.has(f));
+	if (unknown.length) {
+		throw new CliError(
+			`Unknown flag${unknown.length > 1 ? "s" : ""} for this command: ${unknown.map((f) => `--${f}`).join(", ")}. ` +
+				"This command writes, so it refuses rather than ignoring a flag it does not understand."
+		);
+	}
+}
+
+// ---------------------------------------------------------------------------------
+// ARGS maps: the one place a curated command says how each tool input key is sourced.
+//
+// A command module exports `ARGS = { <tool name>: { <schema key>: <source> } }` and builds
+// its `callTool` payload with `argsFromFlags(ARGS[tool], flags, positionals)`. The map IS
+// the implementation — not a second copy of it — so `scripts/parity-check.ts` can import it
+// and compare its keys against the tool's published input schema. A tool that gains a
+// parameter the command never learned then FAILS parity instead of drifting silently
+// (#1731 shipped enable_planner to MCP and REST and the CLI never got the flags; nothing
+// noticed, because the old check compared tool NAMES only).
+//
+// Source forms, one per schema key:
+//   "flag"                              a string flag, --flag <value>
+//   ["about", "direction"]              the first of these string flags that is set
+//   { flag, type?, required?, enum?, invert?, negate?, positional?, label? }
+//       type:      "str" (default) | "num" | "bool" | "list" (a repeatable flag)
+//       required:  throw "Missing required --flag" when absent
+//       enum:      throw "--flag must be one of: …" on any other value
+//       invert:    (bool) a set --flag sends FALSE (e.g. --no-phantom → enabled:false)
+//       negate:    (bool) a second flag that sends FALSE (e.g. --no-auto-deploy)
+//       positional: an index into positionals instead of a flag (label names it in errors)
+//   { object: { <sub key>: <source> } } a nested object, omitted when every sub key is absent
+//   { value: (flags, positionals, extra) => v }
+//                                       computed from several flags or an earlier result;
+//                                       still DECLARED, so parity counts the key as exposed
+//   { internal: "why" }                 supplied by the command from a prior tool result
+//                                       (a job id it just received), never from the user
+export function argsFromFlags(spec, flags, positionals = [], extra = {}) {
+	const out = {};
+	for (const [key, source] of Object.entries(spec)) {
+		const v = readArgSource(key, source, flags, positionals, extra);
+		if (v !== undefined) out[key] = v;
+	}
+	return out;
+}
+
+function readArgSource(key, source, flags, positionals, extra) {
+	if (typeof source === "string") return flagStr(flags[source]);
+	if (Array.isArray(source)) {
+		for (const name of source) {
+			const v = flagStr(flags[name]);
+			if (v !== undefined) return v;
+		}
+		return undefined;
+	}
+	if (!source || typeof source !== "object") {
+		throw new CliError(`ARGS.${key}: unsupported source ${JSON.stringify(source)}`);
+	}
+	if (source.internal !== undefined) return undefined;
+	if (typeof source.value === "function") return source.value(flags, positionals, extra);
+	if (source.object) {
+		const nested = argsFromFlags(source.object, flags, positionals, extra);
+		return Object.keys(nested).length ? nested : undefined;
+	}
+	if (source.positional !== undefined) {
+		const v = positionals[source.positional];
+		if (v === undefined && source.required) {
+			throw new CliError(`Missing required <${source.label ?? key}>`);
+		}
+		return v;
+	}
+	const raw = flags[source.flag];
+	let v;
+	switch (source.type ?? "str") {
+		case "num":
+			v = flagNum(raw);
+			break;
+		case "bool":
+			if (source.negate && flags[source.negate] === true) return false;
+			v = raw === true ? (source.invert ? false : true) : undefined;
+			break;
+		case "list": {
+			const list = flagList(raw);
+			v = list.length ? list : undefined;
+			break;
+		}
+		default:
+			v = flagStr(raw);
+	}
+	if (v === undefined && source.required) throw new CliError(`Missing required --${source.flag}`);
+	if (v !== undefined && source.enum && !source.enum.includes(v)) {
+		throw new CliError(`--${source.flag} must be one of: ${source.enum.join(", ")}`);
+	}
+	return v;
+}
+
 export function printResult(io, flags, value, formatter) {
 	if (flags.json || !formatter) {
 		io.log(JSON.stringify(value, null, 2));
@@ -89,6 +221,58 @@ export async function pollUntil(io, poll, opts = {}) {
 	}
 }
 
+// Pull one field out of a tool result.
+//
+// `client.callTool` ALREADY unwraps the MCP envelope and parses the JSON, so a
+// tool result here is the payload itself. Two commands used to reach for
+// `result.content[0].text` — the envelope shape — which is always undefined
+// after unwrapping, so the job id was never found, the follow loop never ran,
+// and `--no-wait` never printed its hint. The envelope fallback below is kept
+// only so a raw result passed in from somewhere else still reads correctly.
+export function toolField(result, field) {
+	if (result && typeof result === "object" && field in result) return result[field];
+	const raw = result?.content?.[0]?.text;
+	if (typeof raw === "string") {
+		try {
+			return JSON.parse(raw)?.[field];
+		} catch {
+			return undefined;
+		}
+	}
+	return undefined;
+}
+
+// Follow a queued job to a terminal state, SLEEPING FIRST.
+//
+// Unlike `pollUntil`, which checks immediately: a shred or a kernel run takes
+// minutes and starts on the next tick, so an instant first poll only ever says
+// "queued". Sleeping first is also what makes the interval the operator's —
+// both loops used a file-local `setTimeout`, so `io.sleep` (and with it
+// LETTERSTORY_POLL_INTERVAL_MS) was ignored and nobody could pace them.
+//
+// Returns `{ settled, value }`. `settled:false` means the ceiling passed — the
+// caller decides what to say, because the job is still running on the server
+// and that is not an error.
+export async function followJob(io, poll, opts = {}) {
+	// The default is the command's own (a shred is slow; polling fast only burns
+	// requests). An operator who EXPLICITLY sets LETTERSTORY_POLL_INTERVAL_MS
+	// means it, and that is what makes the interval theirs — a CI run or a test
+	// harness sets it to 0 and the same loop runs without the wait.
+	const explicit = process.env.LETTERSTORY_POLL_INTERVAL_MS;
+	const intervalMs =
+		explicit !== undefined && explicit !== "" && Number.isFinite(Number(explicit))
+			? Number(explicit)
+			: (opts.intervalMs ?? 15000);
+	const ceilingMs = opts.ceilingMs ?? 30 * 60 * 1000;
+	const deadline = Date.now() + ceilingMs;
+	for (;;) {
+		await io.sleep(intervalMs);
+		const { done, value } = await poll();
+		if (done) return { settled: true, value };
+		if (Date.now() > deadline) return { settled: false, value };
+	}
+}
+
 // Read a text value from an inline flag, or from a file flag (a path, or "-" for
 // stdin). Returns undefined if neither flag was given, so callers can decide whether
 // that's an error. `readBodyInput` is the --body/--file pairing; the propose lane reads

package/lib/commands/shredder.mjs

@@ -13,6 +13,8 @@ import {
 	printResult,
 	compact,
 	ok,
+	toolField,
+	followJob,
 } from "./shared.mjs";
 
 export async function cmdShredder(ctx) {
@@ -83,8 +85,6 @@ async function shredderDelete(ctx) {
 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");
@@ -105,6 +105,9 @@ async function shredderRun(ctx) {
 		text,
 		coverage: flagNum(flags.coverage),
 		attempts_per_unit: flagNum(flags.attempts),
+		// What the text IS. Without this an HTML file could only go through the
+		// `auto` heuristic, which misreads a markdown post carrying an embed.
+		...(flags.format ? { format: String(flags.format) } : {}),
 		// How hard to rewrite. Validated service-side; sent only when the caller asked.
 		...(flags.aggression ? { aggression: String(flags.aggression) } : {}),
 		// Hold every rewrite to the live writing rules. A trade, not a free win: refused rewrites
@@ -132,36 +135,35 @@ async function shredderRun(ctx) {
 	}
 
 	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;
-		}
-	}
-}
+	let lastStatus;
+	const { settled, value: polled } = await followJob(
+		io,
+		async () => {
+			const result = await client.callTool("get_shred_job", { job_id: jobId });
+			lastStatus = readStatus(result);
+			const terminal = !!lastStatus && lastStatus !== "queued" && lastStatus !== "running";
+			return { done: terminal, value: result };
+		},
+		{ intervalMs: POLL_INTERVAL_MS, ceilingMs: POLL_CEILING_MS }
+	);
 
-/** 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;
+	if (!settled) {
+		ok(ctx, `Still ${lastStatus ?? "running"} after 30 minutes. Poll it with: letterstory shredder job ${jobId}`);
+		printResult(io, flags, polled);
+		return 0;
 	}
+	ok(ctx, `Shred ${lastStatus}.`);
+	// The operator followed this job to get their DOCUMENT, so print the document
+	// and not the envelope around it. `--json` still gets the whole payload, which
+	// is what a script piping this wants.
+	printResult(io, flags, polled, (v) => (typeof v?.text === "string" ? v.text : JSON.stringify(v, null, 2)));
+	// A job that landed as error or degraded is not a success, and a script that
+	// pipes this needs to know without parsing the payload.
+	return lastStatus === "done" ? 0 : 1;
 }
-const readJobId = (result) => readToolField(result, "job_id");
-const readStatus = (result) => readToolField(result, "status");
+
+const readJobId = (result) => toolField(result, "job_id");
+const readStatus = (result) => toolField(result, "status");
 
 async function shredderJob(ctx) {
 	const { client, positionals, flags, io } = ctx;

package/lib/commands/strategy.mjs

@@ -4,16 +4,72 @@
 // mirrored here as two exported handlers for the same reason.
 
 import { CliError } from "../client.mjs";
-import {
-	flagStr,
-	requireFlag,
-	requirePositional,
-	printResult,
-	compact,
-	flagList,
-	ok,
-	readBodyInput,
-} from "./shared.mjs";
+import { flagStr, printResult, flagList, ok, readBodyInput, argsFromFlags } from "./shared.mjs";
+
+// A list flag the API clears with an explicit empty array (which compact() keeps):
+// `--clear-topics` sends [], a repeated --topic sends the list, neither sends nothing.
+const clearableList = (flag, clearFlag) => ({
+	value: (flags) => {
+		if (flags[clearFlag]) return [];
+		const list = flagList(flags[flag]);
+		return list.length ? list : undefined;
+	},
+});
+
+// How every tool this module calls gets its arguments — see `argsFromFlags` in shared.mjs.
+// `scripts/parity-check.ts` compares these keys against each tool's published input schema.
+export const ARGS = {
+	get_company_info: {},
+	set_company_info: {
+		name: "name",
+		domain: "domain",
+		// The API clears the manifesto with an empty string, which a plain flag read would
+		// drop — so it is set explicitly whenever the user supplied a source (text or file).
+		manifesto: {
+			value: (flags) => {
+				const inline = flagStr(flags.manifesto);
+				const file = flagStr(flags["manifesto-file"]);
+				if (inline === undefined && file === undefined) return undefined;
+				return inline ?? readBodyInput({ file }) ?? "";
+			},
+		},
+		market: "market",
+	},
+	get_positioning: {},
+	set_positioning: {
+		priority_topics: clearableList("topic", "clear-topics"),
+		stances: clearableList("stance", "clear-stances"),
+		avoid_topics: clearableList("avoid", "clear-avoid"),
+	},
+	list_competitors: {},
+	add_competitor: {
+		name: { positional: 0, label: "name", required: true },
+		domain: { positional: 1, label: "domain", required: true },
+	},
+	import_sitemap: {
+		collection_id: { flag: "collection", required: true },
+		sitemap_url: { flag: "url", required: true },
+		sitemap_urls: { flag: "sub", type: "list" },
+		url_pattern: "pattern",
+		posts_only: { flag: "posts-only", type: "bool" },
+	},
+	list_topics: {
+		collection_id: { flag: "collection", required: true },
+	},
+	set_topic: {
+		collection_id: { flag: "collection", required: true },
+		topic_id: "topic",
+		suggestion_id: "suggestion",
+	},
+	get_onboarding_status: {},
+	// Step ids are the server's to define (the registry is the authority); forwarded as given.
+	set_onboarding_step: {
+		current_step: "current",
+		complete_step: "complete",
+		skip_step: "skip",
+		status: "status",
+	},
+};
 
 export async function cmdStrategy(ctx) {
 	const sub = ctx.positionals[0];
@@ -60,16 +116,11 @@ async function companyGet(ctx) {
 
 async function companySet(ctx) {
 	const { client, flags, io } = ctx;
-	const args = compact({ name: flagStr(flags.name), domain: flagStr(flags.domain) });
-	// The API clears the manifesto with an empty string, which compact() would drop —
-	// so set it explicitly whenever the user supplied a source (text or file).
-	const manifesto = flagStr(flags.manifesto);
-	const manifestoFile = flagStr(flags["manifesto-file"]);
-	if (manifesto !== undefined || manifestoFile !== undefined) {
-		args.manifesto = manifesto ?? readBodyInput({ file: manifestoFile }) ?? "";
-	}
+	const args = argsFromFlags(ARGS.set_company_info, flags);
 	if (Object.keys(args).length === 0) {
-		throw new CliError('Nothing to set — pass --name/--domain/--manifesto (empty --manifesto "" clears it).');
+		throw new CliError(
+			'Nothing to set — pass --name/--domain/--manifesto/--market (empty --manifesto "" clears it).'
+		);
 	}
 	const result = await client.callTool("set_company_info", args);
 	ok(ctx, "Company profile updated.");
@@ -101,15 +152,7 @@ async function positioningGet(ctx) {
 
 async function positioningSet(ctx) {
 	const { client, flags, io } = ctx;
-	const topics = flagList(flags.topic);
-	const stances = flagList(flags.stance);
-	const avoid = flagList(flags.avoid);
-	// The API clears a list with an explicit empty array (which compact() keeps).
-	const args = compact({
-		priority_topics: flags["clear-topics"] ? [] : topics.length ? topics : undefined,
-		stances: flags["clear-stances"] ? [] : stances.length ? stances : undefined,
-		avoid_topics: flags["clear-avoid"] ? [] : avoid.length ? avoid : undefined,
-	});
+	const args = argsFromFlags(ARGS.set_positioning, flags);
 	if (Object.keys(args).length === 0) {
 		throw new CliError("Pass at least one --topic/--stance/--avoid (or a --clear-* flag).");
 	}
@@ -144,10 +187,9 @@ async function competitorsList(ctx) {
 
 async function competitorsAdd(ctx) {
 	const { client, positionals, flags, io } = ctx;
-	const name = requirePositional(positionals, 0, "name");
-	const domain = requirePositional(positionals, 1, "domain");
-	const result = await client.callTool("add_competitor", { name, domain });
-	ok(ctx, `Added competitor ${name}.`);
+	const args = argsFromFlags(ARGS.add_competitor, flags, positionals);
+	const result = await client.callTool("add_competitor", args);
+	ok(ctx, `Added competitor ${args.name}.`);
 	printResult(io, flags, result);
 	return 0;
 }
@@ -156,15 +198,7 @@ async function competitorsAdd(ctx) {
 
 async function strategySitemap(ctx) {
 	const { client, flags, io } = ctx;
-	const collection = requireFlag(flags, "collection");
-	const url = requireFlag(flags, "url");
-	const sub = flagList(flags.sub);
-	const args = compact({
-		collection_id: collection,
-		sitemap_url: url,
-		sitemap_urls: sub.length ? sub : undefined,
-		url_pattern: flagStr(flags.pattern),
-	});
+	const args = argsFromFlags(ARGS.import_sitemap, flags);
 	const result = await client.callTool("import_sitemap", args);
 	ok(ctx, "Sitemap import started.");
 	printResult(io, flags, result);
@@ -189,21 +223,17 @@ async function strategyTopics(ctx) {
 
 async function topicsList(ctx) {
 	const { client, flags, io } = ctx;
-	const collection = requireFlag(flags, "collection");
-	const result = await client.callTool("list_topics", { collection_id: collection });
+	const result = await client.callTool("list_topics", argsFromFlags(ARGS.list_topics, flags));
 	printResult(io, flags, result);
 	return 0;
 }
 
 async function topicsSet(ctx) {
 	const { client, flags, io } = ctx;
-	const collection = requireFlag(flags, "collection");
-	const topicId = flagStr(flags.topic);
-	const suggestionId = flagStr(flags.suggestion);
-	if ((topicId === undefined) === (suggestionId === undefined)) {
+	const args = argsFromFlags(ARGS.set_topic, flags);
+	if ((args.topic_id === undefined) === (args.suggestion_id === undefined)) {
 		throw new CliError("Pass exactly one of --topic <topic-id> or --suggestion <suggestion-id>.");
 	}
-	const args = compact({ collection_id: collection, topic_id: topicId, suggestion_id: suggestionId });
 	const result = await client.callTool("set_topic", args);
 	ok(ctx, "Topic queued.");
 	printResult(io, flags, result);
@@ -234,12 +264,7 @@ async function onboardingStatus(ctx) {
 
 async function onboardingStep(ctx) {
 	const { client, flags, io } = ctx;
-	const args = compact({
-		current_step: flagStr(flags.current),
-		complete_step: flagStr(flags.complete),
-		skip_step: flagStr(flags.skip),
-		status: flagStr(flags.status),
-	});
+	const args = argsFromFlags(ARGS.set_onboarding_step, flags);
 	if (Object.keys(args).length === 0) {
 		throw new CliError("Pass --current/--complete/--skip/--status.");
 	}

package/package.json

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