@letterstory/cli 0.121.4 → 0.121.6

package/README.md

@@ -146,6 +146,17 @@ letterstory posts list [--limit <n>] [--collection <uuid>]
 letterstory posts show <article-id>
 letterstory posts new --title "…" --collection <uuid> --body "…" [--article-id <uuid>]   # or --file <path|->; --article-id updates that article instead of creating one
 letterstory posts new --title "…" --collection <uuid> --body "…" --context "Internal data from 120 accounts: disputes fell 38%."   # your own data: stated in the post with your attribution
+letterstory posts update <article-id> --title "…" --summary "…" --tag seo --tag ai   # only what you pass changes; --body/--file for the HTML body
+letterstory posts edit <article-id> --instruction "Tighten the intro"                   # AI rewrite, saved as your edit
+letterstory posts mentions <article-id>                                                # re-apply the brand-mention & competitor policy
+letterstory posts history <article-id>
+letterstory posts restore <article-id> <version>                                       # comes back as the newest version
+letterstory posts export <article-id> --format pdf --out post.pdf                      # or --format md (prints the Markdown)
+letterstory posts comments <article-id>
+letterstory posts comments add <article-id> --body "Source?" --quote "grew 40%"
+letterstory posts comments update <article-id> <comment-id> --resolve                  # or --reopen, --body "…"
+letterstory posts comments resolve-ai <article-id> <comment-id>                        # AI makes the change the comment asks for
+letterstory reviewers invite <article-id> --email editor@client.com --name "Sam"       # a guest reviewer: link + PIN by email
 letterstory posts publish <article-id>
 letterstory posts unpublish <article-id>
 letterstory posts delete --id <uuid> [--id <uuid> ...]                # permanent; content, history, and any published copy are all removed

package/lib/cli.mjs

@@ -19,6 +19,7 @@ import {
 	cmdPosts,
 	cmdPublished,
 	cmdReviewers,
+	cmdAutomations,
 	cmdCollections,
 	cmdAuthors,
 	cmdFlows,
@@ -60,7 +61,7 @@ import {
 } from "./commands.mjs";
 
 // Keep in sync with cli/package.json.
-export const VERSION = "0.121.4";
+export const VERSION = "0.121.6";
 
 // Flags that never take a value. Listing them explicitly means `deploy get --json <id>`
 // can't accidentally swallow the id as --json's value. Every `type: "bool"` flag (and its
@@ -136,6 +137,9 @@ export const BOOLEAN_FLAGS = new Set([
 	"stock-only",
 	"gate",
 	"no-verify",
+	// `posts comments update <article-id> <comment-id> --resolve | --reopen`.
+	"resolve",
+	"reopen",
 	"skip",
 	// `phantom-onboard domain` / `admin create-org --onboard` switches.
 	"watch",
@@ -185,6 +189,11 @@ export const BOOLEAN_FLAGS = new Set([
 	"retired",
 	"retire",
 	"restore",
+	// `posts list --mine`: only your posts.
+	"mine",
+	// `automations set --pause | --resume`.
+	"pause",
+	"resume",
 	// `collection add "<headline>" --collection <id> --queue`.
 	"queue",
 	// Bool flags from command ARGS maps that were missing here.
@@ -376,9 +385,29 @@ Phantomstory (a collection Letterstory hosts as an independent publication):
   phantom delete <phantom-id> --yes
 
 Content:
-  posts list [--limit <n>] [--collection <uuid>]     List your articles
+  posts list [--limit <n>] [--offset <n>] [--collection <uuid>] [--search <words>] [--mine]
+                                                       List your articles
   posts show <article-id>                            Show one article
   posts new --title <t> --collection <uuid> (--body <text> | --file <path|->) [--article-id <uuid>] [--context <text>]
+  posts update <article-id> [--title <t>] [--body <html> | --file <path|->] [--status draft|published|archived]
+          [--summary <dek>] [--tag <t> ...] [--owner <user-id> ...] [--due <YYYY-MM-DD>] [--author <name>]
+          [--author-id <id>] [--slug <s>] [--meta-title <t>] [--meta-description <d>] [--published-url <url>]
+          [--template <key|none|inherit>] [--mention off|subtle|woven|inherit] [--direction-gate on|off|inherit]
+          [--paper-trail '<json>'] [--metadata-json '<json>']
+                                                     Edit a post; only what you pass changes
+  posts edit <article-id> --instruction "<what to change>"
+                                                     Rewrite the post with AI from an instruction
+  posts mentions <article-id>                        Re-apply the brand-mention & competitor policy
+  posts history <article-id>                         The post's versions, newest first
+  posts restore <article-id> <version>               Bring a version back as the latest
+  posts export <article-id> --format md|pdf [--out <path>]
+                                                     The draft as Markdown or PDF
+  posts comments <article-id>                        The post's comments and replies
+  posts comments add <article-id> --body <text> [--quote <text> [--prefix <t>] [--suffix <t>]]
+          [--kind note|ai_esque] [--scope sentence|document] [--reply-to <comment-id>] [--mention <user-id> ...]
+  posts comments update <article-id> <comment-id> [--body <text>] [--resolve | --reopen] [--mention <user-id> ...]
+  posts comments delete <article-id> <comment-id>
+  posts comments resolve-ai <article-id> <comment-id> Make the change the comment asks for, with AI
   posts publish <article-id>                         Publish an article
   posts unpublish <article-id>                       Unpublish an article
   posts delete --id <uuid> [--id <uuid> ...]         Permanently delete article(s)
@@ -391,6 +420,16 @@ Reviewers:
                                                          guest reviewer on every future
                                                          finished draft (no email sent now)
   reviewers standing remove <reviewer-id>              Stop future auto-invites
+  reviewers assigned                                   Posts waiting on your review, across letterbases
+  automations list --collection <id>                   What a letterbase writes, how often, and why
+  automations show <automation-id> --collection <id>  What it covers, its queued posts, its next ideas
+  automations add topic|series|signal|best --collection <id> [--topic <id>] [--goal <target-id>]
+                  [--seer <id>] [--pace <n>]           Add one (refused if it says the same as another)
+  automations set <automation-id> --collection <id> [--pace <n>] [--pause | --resume] [--goal <id>]
+  automations remove <automation-id> --collection <id>
+  reviewers invite <article-id> --email <e> [--name <n>]
+                                                       Invite a guest to review one post
+                                                         (emails them a link and a PIN)
 
 Collections:
   collections list                                   List your collections
@@ -1343,6 +1382,7 @@ const CLIENT_COMMANDS = {
 	posts: cmdPosts,
 	published: cmdPublished,
 	reviewers: cmdReviewers,
+	automations: cmdAutomations,
 	collections: cmdCollections,
 	authors: cmdAuthors,
 	flows: cmdFlows,

package/lib/commands/automations.mjs

@@ -0,0 +1,68 @@
+// `automations` — a letterbase's automations (docs/architecture/automations.md): what it writes,
+// how often, and why. list / show / add / set / remove, through the same tools the app uses.
+// Same flag/positional/io conventions as posts.mjs — no commander, no color.
+
+import { CliError } from "../client.mjs";
+import { printResult, ok, argsFromFlags, refuseUnknownFlags } from "./shared.mjs";
+
+/** See `argsFromFlags` in shared.mjs; `scripts/parity-check.ts` diffs these keys against the tool. */
+export const ARGS = {
+	list_automations: {
+		collection_id: { flag: "collection", required: true },
+	},
+	get_automation: {
+		collection_id: { flag: "collection", required: true },
+		automation_id: { positional: 0, label: "automation-id", required: true },
+	},
+	create_automation: {
+		collection_id: { flag: "collection", required: true },
+		kind: { positional: 0, label: "kind", required: true, enum: ["topic", "series", "signal", "best"] },
+		cluster_id: { flag: "topic" },
+		target_id: { flag: "goal" },
+		seer_id: { flag: "seer" },
+		pace_per_week: { flag: "pace", type: "num" },
+	},
+	update_automation: {
+		collection_id: { flag: "collection", required: true },
+		automation_id: { positional: 0, label: "automation-id", required: true },
+		pace_per_week: { flag: "pace", type: "num" },
+		paused: {
+			value: (flags) => (flags.pause === true ? true : flags.resume === true ? false : undefined),
+		},
+		target_id: { flag: "goal" },
+	},
+	delete_automation: {
+		collection_id: { flag: "collection", required: true },
+		automation_id: { positional: 0, label: "automation-id", required: true },
+	},
+};
+
+export async function cmdAutomations(ctx) {
+	const sub = ctx.positionals[0];
+	const rest = { ...ctx, positionals: ctx.positionals.slice(1) };
+	switch (sub) {
+		case "list":
+		case "ls":
+			return run(rest, "list_automations");
+		case "show":
+			return run(rest, "get_automation");
+		case "add":
+			return run(rest, "create_automation", "Added.");
+		case "set":
+			refuseUnknownFlags(rest, ARGS.update_automation, ["pause", "resume"]);
+			return run(rest, "update_automation", "Changed.");
+		case "remove":
+		case "rm":
+			return run(rest, "delete_automation", "Removed.");
+		default:
+			throw new CliError(`Unknown automations subcommand: ${sub ?? "(none)"}. Try: list, show, add, set, remove`);
+	}
+}
+
+async function run(ctx, tool, said) {
+	const { client, flags, io } = ctx;
+	const result = await client.callTool(tool, argsFromFlags(ARGS[tool], flags, ctx.positionals));
+	if (said) ok(ctx, said);
+	printResult(io, flags, result);
+	return 0;
+}

package/lib/commands/autopen.mjs

@@ -20,6 +20,9 @@ export const ARGS = {
 		from_scratch: { flag: "from-scratch", type: "bool" },
 		// --skip finish,metadata: leave those steps out of this run only.
 		skip_steps: { flag: "skip", type: "list" },
+		// --source <url> … / --must-include <t> …: what this run's research reads first and covers.
+		source_urls: { flag: "source", type: "list" },
+		must_include: { flag: "must-include", type: "list" },
 	},
 };
 

package/lib/commands/posts.mjs

@@ -2,6 +2,7 @@
 // Ported from phantomstory-cli's posts.ts — same tool calls, same shape, adapted to
 // this CLI's flag/positional/io conventions (no commander, no color).
 
+import { writeFileSync } from "node:fs";
 import { CliError } from "../client.mjs";
 import {
 	flagStr,
@@ -13,16 +14,130 @@ import {
 	ok,
 	readBodyInput,
 	argsFromFlags,
+	refuseUnknownFlags,
 } from "./shared.mjs";
 
+const ARTICLE = { positional: 0, label: "article-id", required: true };
+const COMMENT = { positional: 1, label: "comment-id", required: true };
+
+/** `--<name> '<json>'` → a JSON object, or undefined when the flag is not set. */
+function jsonObjectFlag(flags, name) {
+	const raw = flagStr(flags[name]);
+	if (raw === undefined) return undefined;
+	let parsed;
+	try {
+		parsed = JSON.parse(raw);
+	} catch (err) {
+		throw new CliError(`--${name} is not valid JSON: ${err.message}`);
+	}
+	if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed))
+		throw new CliError(`--${name} must be a JSON object`);
+	return parsed;
+}
+
+/** A per-post override: a value, or `inherit` (null: back to the collection's). */
+function overrideFlag(flags, name, allowed) {
+	const raw = flagStr(flags[name]);
+	if (raw === undefined) return undefined;
+	if (raw === "inherit") return null;
+	if (allowed && !allowed.includes(raw))
+		throw new CliError(`--${name} must be one of: ${[...allowed, "inherit"].join(", ")}`);
+	return raw;
+}
+
+/** `--direction-gate on|off|inherit`. */
+function directionGateFlag(flags) {
+	const raw = overrideFlag(flags, "direction-gate", ["on", "off"]);
+	return raw === undefined || raw === null ? raw : raw === "on";
+}
+
 /** See `argsFromFlags` in shared.mjs; `scripts/parity-check.ts` diffs these keys against the tool. */
 export const ARGS = {
 	publish_article: {
-		article_id: { positional: 0, label: "article-id", required: true },
+		article_id: ARTICLE,
 	},
 	delete_article: {
 		article_ids: { flag: "id", type: "list", required: true, label: "id" },
 	},
+	update_article: {
+		article_id: ARTICLE,
+		title: "title",
+		content: { value: (flags) => readBodyInput(flags) },
+		status: { flag: "status", enum: ["draft", "published", "archived"] },
+		metadata: { value: (flags) => jsonObjectFlag(flags, "metadata-json") },
+		metadataPatch: {
+			object: {
+				summary: "summary",
+				tags: { flag: "tag", type: "list" },
+				owners: { flag: "owner", type: "list" },
+				due_date: "due",
+				author: "author",
+				author_id: "author-id",
+				slug: "slug",
+				meta_title: "meta-title",
+				meta_description: "meta-description",
+				published_url: "published-url",
+				template_key: { value: (flags) => overrideFlag(flags, "template") },
+				mention_degree: { value: (flags) => overrideFlag(flags, "mention", ["off", "subtle", "woven"]) },
+				direction_gate: { value: (flags) => directionGateFlag(flags) },
+				paper_trail: { value: (flags) => jsonObjectFlag(flags, "paper-trail") },
+			},
+		},
+	},
+	edit_article_with_prompt: {
+		article_id: ARTICLE,
+		instruction: { flag: "instruction", required: true },
+	},
+	run_mention_pass: {
+		article_id: ARTICLE,
+	},
+	get_article_history: {
+		article_id: ARTICLE,
+	},
+	restore_article_version: {
+		article_id: ARTICLE,
+		// Positional, not `--version`: that is the global "print the CLI version" switch.
+		version: {
+			value: (_flags, positionals) => {
+				const n = flagNum(positionals[1]);
+				if (n === undefined) throw new CliError("Missing required <version>");
+				return n;
+			},
+		},
+	},
+	export_article: {
+		article_id: ARTICLE,
+		format: { flag: "format", required: true, enum: ["md", "pdf"] },
+	},
+	list_article_comments: {
+		article_id: ARTICLE,
+	},
+	add_article_comment: {
+		article_id: ARTICLE,
+		body: { flag: "body", required: true },
+		kind: { flag: "kind", enum: ["note", "ai_esque"] },
+		scope: { flag: "scope", enum: ["sentence", "document"] },
+		parent_id: "reply-to",
+		quote: "quote",
+		quote_prefix: "prefix",
+		quote_suffix: "suffix",
+		mentioned_user_ids: { flag: "mention", type: "list" },
+	},
+	update_article_comment: {
+		article_id: ARTICLE,
+		comment_id: COMMENT,
+		body: "body",
+		resolved: { flag: "resolve", type: "bool", negate: "reopen" },
+		mentioned_user_ids: { flag: "mention", type: "list" },
+	},
+	delete_article_comment: {
+		article_id: ARTICLE,
+		comment_id: COMMENT,
+	},
+	resolve_comment_with_ai: {
+		article_id: ARTICLE,
+		comment_id: COMMENT,
+	},
 };
 
 export async function cmdPosts(ctx) {
@@ -36,6 +151,20 @@ export async function cmdPosts(ctx) {
 			return postsShow(rest);
 		case "new":
 			return postsNew(rest);
+		case "update":
+			return postsWrite(rest, "update_article", "Updated.");
+		case "edit":
+			return postsWrite(rest, "edit_article_with_prompt", "Edited.");
+		case "mentions":
+			return postsWrite(rest, "run_mention_pass", "Mention pass done.");
+		case "history":
+			return postsRead(rest, "get_article_history");
+		case "restore":
+			return postsWrite(rest, "restore_article_version", "Restored as the latest version.");
+		case "export":
+			return postsExport(rest);
+		case "comments":
+			return postsComments(rest);
 		case "publish":
 			return postsPublish(rest);
 		case "unpublish":
@@ -45,14 +174,85 @@ export async function cmdPosts(ctx) {
 			return postsDelete(rest);
 		default:
 			throw new CliError(
-				`Unknown posts subcommand: ${sub ?? "(none)"}. Try: list, show, new, publish, unpublish, delete`
+				`Unknown posts subcommand: ${sub ?? "(none)"}. Try: list, show, new, update, edit, mentions, history, restore, export, comments, publish, unpublish, delete`
 			);
 	}
 }
 
+// Each tool named once, literally, so scripts/parity-check.ts sees which command calls it.
+const CALL = {
+	update_article: (client, args) => client.callTool("update_article", args),
+	edit_article_with_prompt: (client, args) => client.callTool("edit_article_with_prompt", args),
+	run_mention_pass: (client, args) => client.callTool("run_mention_pass", args),
+	get_article_history: (client, args) => client.callTool("get_article_history", args),
+	restore_article_version: (client, args) => client.callTool("restore_article_version", args),
+	list_article_comments: (client, args) => client.callTool("list_article_comments", args),
+	add_article_comment: (client, args) => client.callTool("add_article_comment", args),
+	update_article_comment: (client, args) => client.callTool("update_article_comment", args),
+	delete_article_comment: (client, args) => client.callTool("delete_article_comment", args),
+	resolve_comment_with_ai: (client, args) => client.callTool("resolve_comment_with_ai", args),
+};
+
+/** A write: refuse a flag its ARGS map does not declare, then call the tool. */
+async function postsWrite(ctx, tool, done) {
+	const { client, flags, io, positionals } = ctx;
+	refuseUnknownFlags(ctx, ARGS[tool]);
+	const result = await CALL[tool](client, argsFromFlags(ARGS[tool], flags, positionals));
+	ok(ctx, done);
+	printResult(io, flags, result);
+	return 0;
+}
+
+async function postsRead(ctx, tool) {
+	const { client, flags, io, positionals } = ctx;
+	const result = await CALL[tool](client, argsFromFlags(ARGS[tool], flags, positionals));
+	printResult(io, flags, result);
+	return 0;
+}
+
+// `--out <path>` writes the file (a PDF's bytes decoded); without it the result prints.
+async function postsExport(ctx) {
+	const { client, flags, io, positionals } = ctx;
+	const result = await client.callTool("export_article", argsFromFlags(ARGS.export_article, flags, positionals));
+	const out = flagStr(flags.out);
+	if (out === undefined) {
+		if (!flags.json && result?.encoding === "utf8") io.log(result.content);
+		else printResult(io, flags, result);
+		return 0;
+	}
+	const bytes = result.encoding === "base64" ? Buffer.from(result.content, "base64") : result.content;
+	try {
+		writeFileSync(out, bytes);
+	} catch (err) {
+		throw new CliError(`Could not write --out ${out}: ${err.message}`);
+	}
+	ok(ctx, `Wrote ${out}.`);
+	return 0;
+}
+
+// `posts comments <article-id>` lists; `posts comments add|update|delete|resolve-ai <article-id> …` write.
+async function postsComments(ctx) {
+	const verbs = {
+		add: ["add_article_comment", "Commented."],
+		update: ["update_article_comment", "Updated."],
+		delete: ["delete_article_comment", "Deleted."],
+		rm: ["delete_article_comment", "Deleted."],
+		"resolve-ai": ["resolve_comment_with_ai", "Resolved with AI."],
+	};
+	const verb = verbs[ctx.positionals[0]];
+	if (!verb) return postsRead(ctx, "list_article_comments");
+	return postsWrite({ ...ctx, positionals: ctx.positionals.slice(1) }, verb[0], verb[1]);
+}
+
 async function postsList(ctx) {
 	const { client, flags, io } = ctx;
-	const args = compact({ limit: flagNum(flags.limit), collection_id: flagStr(flags.collection) });
+	const args = compact({
+		limit: flagNum(flags.limit),
+		offset: flagNum(flags.offset),
+		collection_id: flagStr(flags.collection),
+		search: flagStr(flags.search),
+		mine: flags.mine === true ? true : undefined,
+	});
 	const result = await client.callTool("list_articles", args);
 	printResult(io, flags, result);
 	return 0;

package/lib/commands/reviewers.mjs

@@ -5,7 +5,26 @@
 // 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";
+import {
+	flagStr,
+	requireFlag,
+	requirePositional,
+	printResult,
+	compact,
+	ok,
+	argsFromFlags,
+	refuseUnknownFlags,
+} from "./shared.mjs";
+
+/** See `argsFromFlags` in shared.mjs; `scripts/parity-check.ts` diffs these keys against the tool. */
+export const ARGS = {
+	list_assigned_reviews: {},
+	invite_guest_reviewer: {
+		article_id: { positional: 0, label: "article-id", required: true },
+		email: { flag: "email", required: true },
+		name: "name",
+	},
+};
 
 export async function cmdReviewers(ctx) {
 	const sub = ctx.positionals[0];
@@ -13,11 +32,33 @@ export async function cmdReviewers(ctx) {
 	switch (sub) {
 		case "standing":
 			return cmdStandingReviewers(rest);
+		case "invite":
+			return inviteGuest(rest);
+		case "assigned":
+			return assigned(rest);
 		default:
-			throw new CliError(`Unknown reviewers subcommand: ${sub ?? "(none)"}. Try: standing`);
+			throw new CliError(`Unknown reviewers subcommand: ${sub ?? "(none)"}. Try: assigned, standing, invite`);
 	}
 }
 
+// `reviewers invite <article-id> --email <e> [--name <n>]` — a guest reviewer on one post.
+async function inviteGuest(ctx) {
+	const { client, flags, io, positionals } = ctx;
+	refuseUnknownFlags(ctx, ARGS.invite_guest_reviewer);
+	const result = await client.callTool(
+		"invite_guest_reviewer",
+		argsFromFlags(ARGS.invite_guest_reviewer, flags, positionals)
+	);
+	ok(
+		ctx,
+		result?.email_sent
+			? `Invited ${flags.email}: the link and PIN are on their way.`
+			: `Invited ${flags.email}, but the email could not be sent: share the link and PIN yourself.`
+	);
+	printResult(io, flags, result);
+	return 0;
+}
+
 async function cmdStandingReviewers(ctx) {
 	const sub = ctx.positionals[0];
 	const rest = { ...ctx, positionals: ctx.positionals.slice(1) };
@@ -60,3 +101,11 @@ async function standingRemove(ctx) {
 	printResult(io, flags, result);
 	return 0;
 }
+
+// `reviewers assigned` — the posts waiting on your review, across every letterbase.
+async function assigned(ctx) {
+	const { client, flags, io } = ctx;
+	const result = await client.callTool("list_assigned_reviews", argsFromFlags(ARGS.list_assigned_reviews, flags));
+	printResult(io, flags, result);
+	return 0;
+}

package/lib/commands.mjs

@@ -11,6 +11,7 @@ export * from "./commands/phantom.mjs";
 export * from "./commands/mcp.mjs";
 export * from "./commands/posts.mjs";
 export * from "./commands/reviewers.mjs";
+export * from "./commands/automations.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.121.4",
+	"version": "0.121.6",
 	"description": "Spin up and manage Letterstory phantom blogs from your terminal.",
 	"type": "module",
 	"license": "UNLICENSED",