@letterstory/cli 0.2.2 → 0.3.0

package/lib/cli.mjs

@@ -25,10 +25,12 @@ import {
 	cmdStrategy,
 	cmdOnboarding,
 	cmdInsights,
+	cmdKernel,
+	cmdPhantomJob,
 } from "./commands.mjs";
 
 // Keep in sync with cli/package.json.
-export const VERSION = "0.2.2";
+export const VERSION = "0.3.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.
@@ -170,9 +172,22 @@ 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>]
 
+Writing kernels:
+  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]
@@ -228,6 +243,8 @@ const CLIENT_COMMANDS = {
 	strategy: cmdStrategy,
 	onboarding: cmdOnboarding,
 	insights: cmdInsights,
+	kernel: cmdKernel,
+	"phantom-job": cmdPhantomJob,
 };
 
 // LETTERSTORY_POLL_INTERVAL_MS / LETTERSTORY_MAX_POLLS let an operator (or an

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/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

@@ -14,3 +14,5 @@ export * from "./commands/flows.mjs";
 export * from "./commands/connectors.mjs";
 export * from "./commands/strategy.mjs";
 export * from "./commands/insights.mjs";
+export * from "./commands/kernel.mjs";
+export * from "./commands/phantom-job.mjs";

package/package.json

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