@letterstory/cli 0.2.2 → 0.4.0

package/README.md

@@ -207,6 +207,35 @@ letterstory onboarding status
 letterstory onboarding step --complete connect_domain
 ```
 
+## Research and writing kernels
+
+Two different steps, in this order. The **research agent** reads the live web and writes a
+sourced outline into the post; a **writing kernel** writes the draft from the brief it's
+given and does no retrieval of its own. Both take minutes, so both are start-then-poll:
+
+```bash
+# 1. Research the topic and write an outline into the post
+letterstory research start --article <uuid> --topic "payroll solutions" \
+  --url https://example.com/a --must-include "Pricing" --depth fleshed_out
+letterstory research status --article <uuid>       # phases, sources, outline
+letterstory research cancel --article <uuid>
+
+# …with --gate, the run pauses for you to pick the angle:
+letterstory research start --article <uuid> --gate
+letterstory research status --article <uuid>       # status: awaiting_direction + direction_options
+letterstory research direction --article <uuid> --choice 1
+letterstory research direction --article <uuid> --custom "Lead with the hidden costs"
+letterstory research direction --article <uuid> --skip     # let the agent decide
+
+# 2. Have a kernel write the draft
+letterstory kernel list
+letterstory kernel run --article <uuid> --kernel <uuid> [--brief "…" | --brief-file brief.md]
+letterstory kernel status <kernel-job-id>
+```
+
+`phantom-job create --topic "…" --collection <uuid>` runs topic → draft → publish → rebuild
+end to end, with `phantom-job status <job-id>` to follow it.
+
 ## Insights
 
 Search Console performance, network-wide, per post, or top posts:

package/lib/cli.mjs

@@ -20,15 +20,19 @@ import {
 	cmdPosts,
 	cmdPublished,
 	cmdCollections,
+	cmdAuthors,
 	cmdFlows,
 	cmdConnectors,
 	cmdStrategy,
 	cmdOnboarding,
 	cmdInsights,
+	cmdResearch,
+	cmdKernel,
+	cmdPhantomJob,
 } from "./commands.mjs";
 
 // Keep in sync with cli/package.json.
-export const VERSION = "0.2.2";
+export const VERSION = "0.4.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.
@@ -148,10 +152,20 @@ Content:
 Collections:
   collections list                                   List your collections
   collections new --name <n> [--description <text>]
-  collections update <id> [--name] [--description] [--cadence-target <n>] [--cadence-period week|month]
+  collections update <id> [--name] [--description] [--cadence-target <n>] [--cadence-period week|month] [--cover-canvas-type-id <uuid>|none]
   collections delete <id> --yes
   collections assign <article-id> <collection-id>
 
+Authors (the per-collection author bank — recurring bylines):
+  authors list <collection-id>                        List the bank + byline distribution
+  authors generate <collection-id> [--count <n>]      Generate a believable masthead
+  authors add <collection-id> --name <n> [--bio <t>] [--role <t>] [--expertise a,b] [--started-at YYYY-MM-DD]
+  authors edit <collection-id> <author-id> [--name] [--bio] [--role] [--expertise a,b] [--started-at] [--active true|false]
+  authors retire <collection-id> <author-id>          Stop assigning new posts to them
+  authors delete <collection-id> <author-id> --yes
+  authors assign <collection-id> (--all | --articles id,id) [--author <id>] [--no-rebuild]
+                                                      Batch-swap bylines (auto-distribute, or --author to pin one)
+
 Flows:
   flows list                                          List available editorial flows
   flows run <flow-id> <article-id>                    Start a flow run
@@ -170,9 +184,31 @@ Strategy & onboarding:
                                  [--clear-topics] [--clear-stances] [--clear-avoid]
   strategy competitors list | add <name> <domain>
   strategy sitemap --collection <uuid> --url <sitemap_url> [--sub <url> …] [--pattern <glob>]
+  strategy topics list --collection <uuid>             List the topic map's clusters/spokes
+  strategy topics set --collection <uuid> (--topic <topic-id> | --suggestion <suggestion-id>)
   onboarding status                                    Show the onboarding checklist
   onboarding step [--current <step>] [--complete <step>] [--skip <step>] [--status <status>]
 
+Research agent (deep research -> outline written into the post):
+  research start --article <uuid> [--topic <text>] [--url <url> …] [--must-include <text> …]
+                 [--depth barebones|fleshed_out] [--gate]
+                                                        Start a run; takes minutes
+  research status --article <uuid>                      Phases, sources, outline
+  research direction --article <uuid> (--choice <n> | --custom <text> | --skip)
+                                                        Answer the --gate pause
+  research cancel --article <uuid>                      Cancel a run in flight
+
+Writing kernels (kernels write the draft; they do not research — run research first):
+  kernel list                                          List available writing kernels
+  kernel run --article <uuid> --kernel <uuid> [--brief <text>|--brief-file <path>]
+                                                        Submit a run; takes 15-20 min
+  kernel status <kernel-job-id>                        Check a run's status
+
+Phantom orchestrator:
+  phantom-job create --topic <text> --collection <uuid> [--kernel <uuid>]
+                                                        Topic -> draft -> publish -> rebuild
+  phantom-job status <job-id>                          Check a job's stage
+
 Insights:
   insights site [--period 14d|30d|90d] [--collection <uuid>]
   insights post <article-id> [--period 14d|30d|90d]
@@ -223,11 +259,15 @@ const CLIENT_COMMANDS = {
 	posts: cmdPosts,
 	published: cmdPublished,
 	collections: cmdCollections,
+	authors: cmdAuthors,
 	flows: cmdFlows,
 	connectors: cmdConnectors,
 	strategy: cmdStrategy,
 	onboarding: cmdOnboarding,
 	insights: cmdInsights,
+	research: cmdResearch,
+	kernel: cmdKernel,
+	"phantom-job": cmdPhantomJob,
 };
 
 // LETTERSTORY_POLL_INTERVAL_MS / LETTERSTORY_MAX_POLLS let an operator (or an

package/lib/commands/authors.mjs

@@ -0,0 +1,165 @@
+// `authors` — manage a collection's author bank: the recurring bylines its posts
+// publish under, instead of a fresh throwaway name per article. The editable-at-
+// scale escape hatch behind the in-app Authors panel.
+
+import { CliError } from "../client.mjs";
+import {
+	flagStr,
+	flagNum,
+	flagBool,
+	flagList,
+	requireFlag,
+	requirePositional,
+	printResult,
+	compact,
+	ok,
+} from "./shared.mjs";
+
+export async function cmdAuthors(ctx) {
+	const sub = ctx.positionals[0];
+	const rest = { ...ctx, positionals: ctx.positionals.slice(1) };
+	switch (sub) {
+		case "list":
+		case "ls":
+			return authorsList(rest);
+		case "generate":
+			return authorsGenerate(rest);
+		case "add":
+		case "create":
+			return authorsAdd(rest);
+		case "edit":
+		case "update":
+			return authorsEdit(rest);
+		case "retire":
+			return authorsSetActive(rest, false);
+		case "activate":
+			return authorsSetActive(rest, true);
+		case "delete":
+		case "rm":
+			return authorsDelete(rest);
+		case "assign":
+		case "swap":
+			return authorsAssign(rest);
+		default:
+			throw new CliError(
+				`Unknown authors subcommand: ${sub ?? "(none)"}. Try: list, generate, add, edit, retire, activate, delete, assign`
+			);
+	}
+}
+
+/** Positional 0 is the collection id for every subcommand except delete/edit (which take an author id too). */
+function collectionId(ctx) {
+	return requirePositional(ctx.positionals, 0, "collection-id");
+}
+
+async function authorsList(ctx) {
+	const { client, flags, io } = ctx;
+	const result = await client.callTool("list_collection_authors", { collection_id: collectionId(ctx) });
+	printResult(io, flags, result);
+	return 0;
+}
+
+async function authorsGenerate(ctx) {
+	const { client, flags, io } = ctx;
+	const args = compact({ collection_id: collectionId(ctx), count: flagNum(flags.count) });
+	const result = await client.callTool("generate_collection_authors", args);
+	ok(ctx, "Generated authors.");
+	printResult(io, flags, result);
+	return 0;
+}
+
+async function authorsAdd(ctx) {
+	const { client, flags, io } = ctx;
+	const cid = collectionId(ctx);
+	const name = requireFlag(flags, "name");
+	const args = compact({
+		collection_id: cid,
+		name,
+		bio: flagStr(flags.bio),
+		role: flagStr(flags.role),
+		expertise: flagList(flags.expertise),
+		started_at: flagStr(flags["started-at"]),
+	});
+	const result = await client.callTool("upsert_collection_author", args);
+	ok(ctx, `Added author "${name}".`);
+	printResult(io, flags, result);
+	return 0;
+}
+
+async function authorsEdit(ctx) {
+	const { client, positionals, flags, io } = ctx;
+	const cid = requirePositional(positionals, 0, "collection-id");
+	const authorId = requirePositional(positionals, 1, "author-id");
+	const patch = compact({
+		collection_id: cid,
+		author_id: authorId,
+		name: flagStr(flags.name),
+		bio: flagStr(flags.bio),
+		role: flagStr(flags.role),
+		expertise: flagList(flags.expertise),
+		started_at: flagStr(flags["started-at"]),
+		active: flagBool(flags.active),
+	});
+	if (Object.keys(patch).length <= 2) {
+		throw new CliError(
+			"Nothing to edit — pass at least one of --name/--bio/--role/--expertise/--started-at/--active."
+		);
+	}
+	const result = await client.callTool("upsert_collection_author", patch);
+	ok(ctx, "Updated author.");
+	printResult(io, flags, result);
+	return 0;
+}
+
+async function authorsSetActive(ctx, active) {
+	const { client, positionals, flags, io } = ctx;
+	const cid = requirePositional(positionals, 0, "collection-id");
+	const authorId = requirePositional(positionals, 1, "author-id");
+	const result = await client.callTool("upsert_collection_author", {
+		collection_id: cid,
+		author_id: authorId,
+		active,
+	});
+	ok(ctx, active ? "Author activated." : "Author retired.");
+	printResult(io, flags, result);
+	return 0;
+}
+
+async function authorsDelete(ctx) {
+	const { client, positionals, flags, io } = ctx;
+	const cid = requirePositional(positionals, 0, "collection-id");
+	const authorId = requirePositional(positionals, 1, "author-id");
+	if (!flags.yes) {
+		io.error(`Re-run with --yes to confirm: ${ctx.bin} authors delete ${cid} ${authorId} --yes`);
+		return 1;
+	}
+	const result = await client.callTool("delete_collection_author", { collection_id: cid, author_id: authorId });
+	ok(ctx, "Author deleted.");
+	printResult(io, flags, result);
+	return 0;
+}
+
+async function authorsAssign(ctx) {
+	const { client, flags, io } = ctx;
+	const cid = collectionId(ctx);
+	// --author <id> pins one author; omit it to auto-distribute by topic.
+	// --all reassigns every post; otherwise pass --articles <id,id,...>.
+	const authorId = flagStr(flags.author);
+	const articleIds = flagList(flags.articles);
+	const all = flagBool(flags.all) === true;
+	if (!all && (!articleIds || articleIds.length === 0)) {
+		throw new CliError("Provide --all to reassign every post, or --articles <id,id,...> for specific posts.");
+	}
+	const args = compact({
+		collection_id: cid,
+		mode: authorId ? "set" : "auto",
+		author_id: authorId,
+		article_ids: all ? undefined : articleIds,
+		all: all ? true : undefined,
+		rebuild: flags["no-rebuild"] ? false : undefined,
+	});
+	const result = await client.callTool("assign_collection_authors", args);
+	ok(ctx, authorId ? "Reassigned bylines to the chosen author." : "Auto-distributed bylines across active authors.");
+	printResult(io, flags, result);
+	return 0;
+}

package/lib/commands/collections.mjs

@@ -48,6 +48,7 @@ async function collectionsNew(ctx) {
 async function collectionsUpdate(ctx) {
 	const { client, positionals, flags, io } = ctx;
 	const id = requirePositional(positionals, 0, "collection-id");
+	const coverCanvasTypeId = flagStr(flags["cover-canvas-type-id"]);
 	const patch = compact({
 		collection_id: id,
 		name: flagStr(flags.name),
@@ -55,9 +56,16 @@ async function collectionsUpdate(ctx) {
 		cadence_target: flagNum(flags["cadence-target"]),
 		cadence_period: flagStr(flags["cadence-period"]),
 	});
+	if (coverCanvasTypeId !== undefined) {
+		// compact() drops undefined, not null — set it after so "none"/"off" can clear
+		// the field instead of being dropped. Same convention as `webhook set --url none`.
+		patch.cover_canvas_type_id = ["none", "off", ""].includes(coverCanvasTypeId.toLowerCase())
+			? null
+			: coverCanvasTypeId;
+	}
 	if (Object.keys(patch).length <= 1) {
 		throw new CliError(
-			"Nothing to update — pass at least one of --name/--description/--cadence-target/--cadence-period."
+			"Nothing to update — pass at least one of --name/--description/--cadence-target/--cadence-period/--cover-canvas-type-id."
 		);
 	}
 	const result = await client.callTool("update_collection", patch);

package/lib/commands/kernel.mjs

@@ -0,0 +1,50 @@
+// `kernel` — list writing kernels, submit a run against an article, and check a
+// run's status. A run can take 15-20 minutes, so unlike `deploy create` this does
+// not block waiting for it: `run` returns as soon as the job is queued and `status`
+// checks on demand, same shape as `flows run` / `flows status`.
+
+import { CliError } from "../client.mjs";
+import { flagStr, requireFlag, requirePositional, printResult, compact, ok, readBodyInput } from "./shared.mjs";
+
+export async function cmdKernel(ctx) {
+	const sub = ctx.positionals[0];
+	const rest = { ...ctx, positionals: ctx.positionals.slice(1) };
+	switch (sub) {
+		case "list":
+		case "ls":
+			return kernelList(rest);
+		case "run":
+			return kernelRun(rest);
+		case "status":
+			return kernelStatus(rest);
+		default:
+			throw new CliError(`Unknown kernel subcommand: ${sub ?? "(none)"}. Try: list, run, status`);
+	}
+}
+
+async function kernelList(ctx) {
+	const { client, flags, io } = ctx;
+	const result = await client.callTool("list_kernels", {});
+	printResult(io, flags, result);
+	return 0;
+}
+
+async function kernelRun(ctx) {
+	const { client, flags, io } = ctx;
+	const article = requireFlag(flags, "article");
+	const kernelId = requireFlag(flags, "kernel");
+	const brief = flagStr(flags.brief) ?? readBodyInput({ file: flagStr(flags["brief-file"]) });
+	const args = compact({ article_id: article, kernel_id: kernelId, brief });
+	const result = await client.callTool("submit_kernel_run", args);
+	ok(ctx, `Kernel run started. Check progress with: kernel status ${result?.kernel_job_id ?? "<kernel-job-id>"}`);
+	printResult(io, flags, result);
+	return 0;
+}
+
+async function kernelStatus(ctx) {
+	const { client, positionals, flags, io } = ctx;
+	const jobId = requirePositional(positionals, 0, "kernel-job-id");
+	const result = await client.callTool("get_kernel_run_status", { kernel_job_id: jobId });
+	printResult(io, flags, result);
+	return 0;
+}

package/lib/commands/phantom-job.mjs

@@ -0,0 +1,41 @@
+// `phantom-job` — the topic-to-published-article orchestrator: kick off a job with
+// a topic + collection, then check its stage (topic_set -> kernel_running ->
+// publishing -> rebuilding -> done, or failed). The underlying kernel run alone can
+// take 15-20 minutes, so `create` returns as soon as the job is queued rather than
+// blocking — same shape as `flows run` / `flows status`, not `deploy create`'s
+// wait-until-live loop.
+
+import { CliError } from "../client.mjs";
+import { flagStr, requireFlag, requirePositional, printResult, compact, ok } from "./shared.mjs";
+
+export async function cmdPhantomJob(ctx) {
+	const sub = ctx.positionals[0];
+	const rest = { ...ctx, positionals: ctx.positionals.slice(1) };
+	switch (sub) {
+		case "create":
+			return phantomJobCreate(rest);
+		case "status":
+			return phantomJobStatus(rest);
+		default:
+			throw new CliError(`Unknown phantom-job subcommand: ${sub ?? "(none)"}. Try: create, status`);
+	}
+}
+
+async function phantomJobCreate(ctx) {
+	const { client, flags, io } = ctx;
+	const topic = requireFlag(flags, "topic");
+	const collection = requireFlag(flags, "collection");
+	const args = compact({ topic, collection_id: collection, kernel_id: flagStr(flags.kernel) });
+	const result = await client.callTool("create_phantom_from_topic", args);
+	ok(ctx, `Phantom job started. Check progress with: phantom-job status ${result?.job_id ?? "<job-id>"}`);
+	printResult(io, flags, result);
+	return 0;
+}
+
+async function phantomJobStatus(ctx) {
+	const { client, positionals, flags, io } = ctx;
+	const jobId = requirePositional(positionals, 0, "job-id");
+	const result = await client.callTool("get_phantom_job_status", { job_id: jobId });
+	printResult(io, flags, result);
+	return 0;
+}

package/lib/commands/research.mjs

@@ -0,0 +1,89 @@
+// `research` — the deep-research agent: read supplied URLs, search the live web, and
+// write a sourced outline into a post. Same shape as `kernel`: a run takes minutes, so
+// `start` returns as soon as the run is queued and `status` checks on demand. Writing
+// kernels do NOT research — `research start` then `kernel run` is the full pipeline.
+
+import { CliError } from "../client.mjs";
+import { flagStr, flagNum, flagBool, flagList, requireFlag, printResult, compact, ok } from "./shared.mjs";
+
+export async function cmdResearch(ctx) {
+	const sub = ctx.positionals[0];
+	const rest = { ...ctx, positionals: ctx.positionals.slice(1) };
+	switch (sub) {
+		case "start":
+		case "run":
+			return researchStart(rest);
+		case "status":
+			return researchStatus(rest);
+		case "direction":
+			return researchDirection(rest);
+		case "cancel":
+			return researchCancel(rest);
+		default:
+			throw new CliError(
+				`Unknown research subcommand: ${sub ?? "(none)"}. Try: start, status, direction, cancel`
+			);
+	}
+}
+
+async function researchStart(ctx) {
+	const { client, flags, io } = ctx;
+	const article = requireFlag(flags, "article");
+	const depth = flagStr(flags.depth);
+	if (depth !== undefined && depth !== "barebones" && depth !== "fleshed_out") {
+		throw new CliError(`--depth must be barebones or fleshed_out, got "${depth}"`);
+	}
+	const sourceUrls = flagList(flags.url);
+	const mustInclude = flagList(flags["must-include"]);
+	const args = compact({
+		article_id: article,
+		topic: flagStr(flags.topic),
+		source_urls: sourceUrls.length ? sourceUrls : undefined,
+		must_include: mustInclude.length ? mustInclude : undefined,
+		depth,
+		direction_gate: flagBool(flags.gate) ? true : undefined,
+	});
+	const result = await client.callTool("start_research", args);
+	ok(ctx, `Research started. Check progress with: research status --article ${article}`);
+	printResult(io, flags, result);
+	return 0;
+}
+
+async function researchStatus(ctx) {
+	const { client, flags, io } = ctx;
+	const article = requireFlag(flags, "article");
+	const result = await client.callTool("get_research_status", { article_id: article });
+	printResult(io, flags, result);
+	return 0;
+}
+
+async function researchDirection(ctx) {
+	const { client, flags, io } = ctx;
+	const article = requireFlag(flags, "article");
+	const choice = flagNum(flags.choice);
+	const custom = flagStr(flags.custom);
+	const skip = flagBool(flags.skip);
+	const given = [choice !== undefined, custom !== undefined, skip].filter(Boolean).length;
+	if (given !== 1) {
+		throw new CliError("Provide exactly one of --choice <n>, --custom <text>, --skip");
+	}
+	const args = compact({
+		article_id: article,
+		choice,
+		custom,
+		skip: skip ? true : undefined,
+	});
+	const result = await client.callTool("submit_research_direction", args);
+	ok(ctx, "Direction recorded; the run resumed into synthesis.");
+	printResult(io, flags, result);
+	return 0;
+}
+
+async function researchCancel(ctx) {
+	const { client, flags, io } = ctx;
+	const article = requireFlag(flags, "article");
+	const result = await client.callTool("cancel_research", { article_id: article });
+	ok(ctx, result?.cancelled ? "Research run cancelled." : "No research run was in flight.");
+	printResult(io, flags, result);
+	return 0;
+}

package/lib/commands/strategy.mjs

@@ -27,9 +27,11 @@ export async function cmdStrategy(ctx) {
 			return strategyCompetitors(rest);
 		case "sitemap":
 			return strategySitemap(rest);
+		case "topics":
+			return strategyTopics(rest);
 		default:
 			throw new CliError(
-				`Unknown strategy subcommand: ${sub ?? "(none)"}. Try: company, positioning, competitors, sitemap`
+				`Unknown strategy subcommand: ${sub ?? "(none)"}. Try: company, positioning, competitors, sitemap, topics`
 			);
 	}
 }
@@ -169,6 +171,45 @@ async function strategySitemap(ctx) {
 	return 0;
 }
 
+// -- topics ---------------------------------------------------------------
+
+async function strategyTopics(ctx) {
+	const sub = ctx.positionals[0];
+	const rest = { ...ctx, positionals: ctx.positionals.slice(1) };
+	switch (sub) {
+		case "list":
+		case "ls":
+			return topicsList(rest);
+		case "set":
+			return topicsSet(rest);
+		default:
+			throw new CliError(`Unknown strategy topics subcommand: ${sub ?? "(none)"}. Try: list, set`);
+	}
+}
+
+async function topicsList(ctx) {
+	const { client, flags, io } = ctx;
+	const collection = requireFlag(flags, "collection");
+	const result = await client.callTool("list_topics", { collection_id: collection });
+	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)) {
+		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);
+	return 0;
+}
+
 // --- onboarding ---------------------------------------------------------
 
 export async function cmdOnboarding(ctx) {

package/lib/commands.mjs

@@ -10,7 +10,11 @@ export * from "./commands/deploy.mjs";
 export * from "./commands/mcp.mjs";
 export * from "./commands/posts.mjs";
 export * from "./commands/collections.mjs";
+export * from "./commands/authors.mjs";
 export * from "./commands/flows.mjs";
 export * from "./commands/connectors.mjs";
 export * from "./commands/strategy.mjs";
 export * from "./commands/insights.mjs";
+export * from "./commands/research.mjs";
+export * from "./commands/kernel.mjs";
+export * from "./commands/phantom-job.mjs";

package/package.json

@@ -1,18 +1,18 @@
 {
 	"name": "@letterstory/cli",
-	"version": "0.2.2",
+	"version": "0.4.0",
 	"description": "Spin up and manage Letterstory phantom blogs from your terminal.",
 	"type": "module",
 	"license": "UNLICENSED",
 	"author": "Letterstory",
-	"homepage": "https://github.com/letterstory/Letterbrace/tree/main/cli#readme",
+	"homepage": "https://github.com/letterstory/letterstory/tree/main/cli#readme",
 	"repository": {
 		"type": "git",
-		"url": "git+https://github.com/letterstory/Letterbrace.git",
+		"url": "git+https://github.com/letterstory/letterstory.git",
 		"directory": "cli"
 	},
 	"bugs": {
-		"url": "https://github.com/letterstory/Letterbrace/issues"
+		"url": "https://github.com/letterstory/letterstory/issues"
 	},
 	"keywords": [
 		"letterstory",