@letterstory/cli 0.39.1 → 0.40.0

package/README.md

@@ -172,6 +172,9 @@ letterstory collection run-status <run-id>                      # status, steps,
 letterstory collection runs --collection <id> --status ready
 letterstory collection approve <run-id> --now
 letterstory collection cancel <run-id>
+letterstory collection inventory <id>                           # every piece; each finished draft's publish-on-its-own time
+letterstory collection links <id>                               # internal-link refresh: on/off, posts due
+letterstory collection links <id> --refresh                     # run the next batch now
 letterstory collection delete <id> --yes
 
 # the legacy verbs still work under `collections`
@@ -245,6 +248,23 @@ letterstory onboarding status
 letterstory onboarding step --complete connect_domain
 ```
 
+### What needs you — the collection's "needs you" strip, from the terminal
+
+Everything in the strip either applies itself after its countdown or waits for your
+decision; the same reads and decisions are here.
+
+```bash
+letterstory suggestions list <collection-id>          # strategy cards + when each applies itself
+letterstory suggestions dismiss proposal <id>         # reject one inside its window
+letterstory collection inventory <collection-id>      # finished drafts + when each publishes on its own
+letterstory collection links <collection-id>          # internal links due for a refresh
+
+# proposed edits to live posts: a mention an AI citation earned, or fresher internal links
+letterstory revisions list --collection <collection-id>
+letterstory revisions accept <revision-id>                     # every change; live where we publish
+letterstory revisions reject <revision-id> --change <change-id> --note "not this one"
+```
+
 ### Offerings — one org, many products
 
 Context is layered **org → offering → collection**. An offering is anything the org would

package/lib/cli.mjs

@@ -27,6 +27,7 @@ import {
 	cmdDirectives,
 	cmdProbes,
 	cmdSuggestions,
+	cmdRevisions,
 	cmdOnboarding,
 	cmdSeries,
 	cmdInsights,
@@ -51,7 +52,7 @@ import {
 } from "./commands.mjs";
 
 // Keep in sync with cli/package.json.
-export const VERSION = "0.39.1";
+export const VERSION = "0.40.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.
@@ -208,6 +209,8 @@ Collections (the content engine as a primitive — one door, 'collection run'):
   collection runs [--collection <id>] [--status <s>] [--limit <n>]
   collection approve <run-id> [--now]                  Answer the gate (--now publishes immediately)
   collection cancel <run-id>
+  collection inventory <id>                            Where every piece is; each finished draft's publish-on-its-own time
+  collection links <id> [--refresh]                    Internal-link refresh: on/off, posts due (--refresh runs the next batch now)
   collection delete <id> --yes
 
 Phantomstory (a collection Letterstory hosts as an independent publication):
@@ -306,6 +309,9 @@ Strategy & onboarding:
   strategy topics set --collection <uuid> (--topic <topic-id> | --suggestion <suggestion-id>)
   suggestions list <collection_id>                     List pending strategy suggestions + their auto-apply countdown
   suggestions approve | dismiss | snooze <verdict|proposal> <id> [--days <n>]
+  revisions list [--collection <uuid>]                 Proposed edits to live posts waiting for a decision
+  revisions accept | reject <revision-id> [--change <change-id>] [--note <text>]
+                                                       Decide one change or all; accepting goes live where we publish
   directives list <collection_id>                      What is steering this collection right now
   directives propose <collection_id> <what you want>   Read one instruction back as concrete levers (applies nothing)
   directives apply <directive_id> --effect <id>...     Commit the levers you kept (or --reason to decline them all)
@@ -826,6 +832,7 @@ const CLIENT_COMMANDS = {
 	targets: cmdTargets,
 	probes: cmdProbes,
 	suggestions: cmdSuggestions,
+	revisions: cmdRevisions,
 	onboarding: cmdOnboarding,
 	series: cmdSeries,
 	insights: cmdInsights,

package/lib/commands/collection.mjs

@@ -10,7 +10,7 @@
 
 import { readFileSync } from "node:fs";
 import { CliError } from "../client.mjs";
-import { flagStr, printResult, ok, toolField, followJob, argsFromFlags } from "./shared.mjs";
+import { flagStr, printResult, ok, toolField, followJob, argsFromFlags, refuseUnknownFlags } from "./shared.mjs";
 
 function readJsonFileFlag(flags, flag) {
 	const path = flagStr(flags[flag]);
@@ -114,6 +114,15 @@ export const ARGS = {
 	cancel_collection_run: {
 		run_id: { positional: 0, label: "run-id", required: true },
 	},
+	get_collection_inventory: {
+		collection_id: { positional: 0, label: "collection-id", required: true },
+	},
+	get_internal_link_status: {
+		collection_id: { positional: 0, label: "collection-id", required: true },
+	},
+	refresh_internal_links: {
+		collection_id: { positional: 0, label: "collection-id", required: true },
+	},
 };
 
 export async function cmdCollection(ctx) {
@@ -142,9 +151,13 @@ export async function cmdCollection(ctx) {
 			return collectionApprove(rest);
 		case "cancel":
 			return collectionCancel(rest);
+		case "inventory":
+			return collectionInventory(rest);
+		case "links":
+			return collectionLinks(rest);
 		default:
 			throw new CliError(
-				`Unknown collection subcommand: ${sub ?? "(none)"}. Try: list, new, config, delete, run, run-status, runs, approve, cancel`
+				`Unknown collection subcommand: ${sub ?? "(none)"}. Try: list, new, config, delete, run, run-status, runs, approve, cancel, inventory, links`
 			);
 	}
 }
@@ -277,3 +290,72 @@ async function collectionCancel(ctx) {
 	printResult(ctx.io, ctx.flags, result);
 	return 0;
 }
+
+// `collection inventory <id>` — where every piece is, and each finished draft's
+// publish-on-its-own time (the collection room's Work tab + "needs you" strip).
+function formatInventory(r) {
+	const lines = [
+		`Planner: ${r.planner?.enabled ? "on" : "off"} (${r.planner?.approvalMode ?? "?"})`,
+		`Live ${r.live?.count ?? 0} · written, not live ${r.readyNotLive?.count ?? 0} · being written ${r.beingWritten?.count ?? 0} · imported ${r.imported?.count ?? 0}`,
+	];
+	const pending = r.pendingReview?.items ?? [];
+	if (pending.length) {
+		lines.push(`Finished drafts (${r.pendingReview.count}):`);
+		for (const d of pending) {
+			const when = d.autoPublishAt ? `publishes on its own ${d.autoPublishAt}` : "waits for a person";
+			lines.push(`  ${d.articleId}  ${d.title}  [${when}]`);
+		}
+	}
+	return lines.join("\n");
+}
+
+async function collectionInventory(ctx) {
+	refuseUnknownFlags(ctx, {});
+	const result = await ctx.client.callTool(
+		"get_collection_inventory",
+		argsFromFlags(ARGS.get_collection_inventory, ctx.flags, ctx.positionals)
+	);
+	printResult(ctx.io, ctx.flags, result, formatInventory);
+	return 0;
+}
+
+// `collection links <id>` reads the internal-link refresh; `--refresh` runs the next
+// batch now (republished, or proposed for approval on a manual-approval collection).
+async function collectionLinks(ctx) {
+	const { client, flags, positionals, io } = ctx;
+	refuseUnknownFlags(ctx, {}, ["refresh"]);
+	if (flags.refresh === true) {
+		const r = await client.callTool(
+			"refresh_internal_links",
+			argsFromFlags(ARGS.refresh_internal_links, flags, positionals)
+		);
+		const parts = [];
+		if (r.posts_started) parts.push(`${r.posts_started} refreshing (each republishes when it finishes)`);
+		if (r.posts_proposed) parts.push(`${r.posts_proposed} proposed for approval (see: revisions list)`);
+		if (r.posts_skipped) parts.push(`${r.posts_skipped} busy with another run`);
+		if (!parts.length) {
+			parts.push(
+				r.skipped?.no_sitemap
+					? "no sitemap to link from"
+					: r.next_due_in_days === null
+						? "nothing due: every post already links to everything published since"
+						: `nothing due yet (next in ${r.next_due_in_days ?? "?"} days)`
+			);
+		}
+		ok(ctx, `Internal links: ${parts.join("; ")}.`);
+		if (flags.json) printResult(io, flags, r);
+		return 0;
+	}
+	const s = await client.callTool(
+		"get_internal_link_status",
+		argsFromFlags(ARGS.get_internal_link_status, flags, positionals)
+	);
+	printResult(io, flags, s, (r) =>
+		[
+			`Internal links: ${r.enabled ? "on" : "off"}`,
+			`Due now: ${r.due}`,
+			`Next due: ${r.next_due_in_days === null ? "only when something new publishes" : `in ${r.next_due_in_days} days`}`,
+		].join("\n")
+	);
+	return 0;
+}

package/lib/commands/revisions.mjs

@@ -0,0 +1,81 @@
+// `revisions` — proposed edits to already-live posts, waiting for a decision: the
+// Approvals queue in a collection's "needs you" strip. A mention an AI citation
+// earned (review-posture collection), or internal links the nightly refresh would
+// add (manual-approval or client-CMS collection). Thin wrappers over the MCP tools
+// list_revisions / decide_revision, which call the same lib/revisions functions the
+// web queue does — accepting on a page we publish puts it live.
+
+import { CliError } from "../client.mjs";
+import { printResult, argsFromFlags, refuseUnknownFlags, ok } from "./shared.mjs";
+
+const DECISIONS = ["accepted", "rejected"];
+
+// 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 = {
+	list_revisions: { collection_id: "collection" },
+	decide_revision: {
+		revision_id: { positional: 0, label: "revision-id", required: true },
+		// `accept` / `reject` set this for you.
+		decision: { flag: "decision", enum: DECISIONS },
+		change_id: "change",
+		note: "note",
+	},
+};
+
+const USAGE = `Usage: revisions <list|accept|reject>
+  revisions list [--collection <uuid>]
+  revisions accept <revision-id> [--change <change-id>]
+  revisions reject <revision-id> [--change <change-id>] [--note <text>]`;
+
+export async function cmdRevisions(ctx) {
+	const sub = ctx.positionals[0];
+	const rest = { ...ctx, positionals: ctx.positionals.slice(1) };
+	switch (sub) {
+		case "list":
+		case "ls":
+			return revisionsList(rest);
+		case "accept":
+			return revisionsDecide(rest, "accepted");
+		case "reject":
+			return revisionsDecide(rest, "rejected");
+		default:
+			throw new CliError(USAGE);
+	}
+}
+
+function formatRevision(r) {
+	const where = r.publish_control === "platform" ? "goes live on accept" : "apply it in your CMS after accepting";
+	const lines = [
+		`${r.id}  ${r.article_title ?? "Untitled"}  (${r.source}; ${where})${r.is_stale ? "  [STALE — needs recomputing]" : ""}`,
+	];
+	if (r.reason) lines.push(`  ${r.reason}`);
+	for (const c of r.changes ?? []) {
+		const state = c.decision ?? "undecided";
+		lines.push(`  - ${c.id} [${state}] ${c.before ? `${c.before} → ` : ""}${c.after}`);
+	}
+	return lines.join("\n");
+}
+
+async function revisionsList(ctx) {
+	const { client, flags, io } = ctx;
+	refuseUnknownFlags(ctx, ARGS.list_revisions);
+	const result = await client.callTool("list_revisions", argsFromFlags(ARGS.list_revisions, flags));
+	printResult(io, flags, result, (r) => {
+		const items = r.revisions ?? [];
+		return items.length ? items.map(formatRevision).join("\n\n") : "No proposed edits waiting.";
+	});
+	return 0;
+}
+
+async function revisionsDecide(ctx, decision) {
+	const { client, flags, positionals, io } = ctx;
+	refuseUnknownFlags(ctx, ARGS.decide_revision);
+	const result = await client.callTool(
+		"decide_revision",
+		argsFromFlags(ARGS.decide_revision, { ...flags, decision }, positionals)
+	);
+	ok(ctx, result.applied ?? `Revision is ${result.status}.`);
+	if (flags.json) printResult(io, flags, result);
+	return 0;
+}

package/lib/commands.mjs

@@ -18,6 +18,7 @@ export * from "./commands/connectors.mjs";
 export * from "./commands/strategy.mjs";
 export * from "./commands/directives.mjs";
 export * from "./commands/probes.mjs";
+export * from "./commands/revisions.mjs";
 export * from "./commands/series.mjs";
 export * from "./commands/insights.mjs";
 export * from "./commands/covers.mjs";

package/package.json

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