@letterstory/cli 0.2.1 → 0.3.0

package/README.md

@@ -9,13 +9,38 @@ manifest an agent sees, so it never drifts from the API.
 The CLI is plain ESM with **zero dependencies** and needs no build step (Node ≥ 20).
 
 ```bash
-# from a checkout of this repo
+npm install -g @letterstory/cli   # puts `letterstory` (and `phantom`) on your PATH
+# …or run it without installing:
+npx @letterstory/cli --help
+```
+
+Contributing to the CLI itself? Run it straight from a checkout instead:
+
+```bash
 cd cli
-npm link          # puts `letterstory` (and `phantom`) on your PATH
+npm link          # puts `letterstory` (and `phantom`) on your PATH, pointing at this checkout
 # …or run it directly without linking:
 node cli/bin/letterstory.mjs --help
 ```
 
+## Updating
+
+The CLI checks npm for a newer published version at most once every 24 hours (cached
+alongside your config, so most runs make no extra network call) and prints a one-line
+nudge on stderr when one's available:
+
+```
+Update available: 0.2.1 → 0.3.0. Run `npm install -g @letterstory/cli@latest` to upgrade.
+```
+
+To upgrade immediately:
+
+```bash
+npm install -g @letterstory/cli@latest
+```
+
+Set `LETTERSTORY_NO_UPDATE_CHECK=1` to disable the check entirely (e.g. in CI).
+
 ## `phantom` — the same CLI, Phantomstory-branded
 
 `phantom` is a ghost-branded entry point for demos and presentations — same binary, same
@@ -32,6 +57,22 @@ otherwise runs the exact same code path as `letterstory`.
 
 ## Authenticate
 
+Two ways in — pick whichever fits how you're running the CLI.
+
+**Sign in via your browser** (the default — best for interactive use on your own machine):
+
+```bash
+letterstory login
+# opens your browser to https://app.letterstory.com, or override with --url
+```
+
+This runs a browser-based OAuth 2.1 flow (PKCE, loopback redirect — RFC 8252) against your
+account. It comes back with a full-access session and a refresh token, so there's no API key
+to mint or scope up front. Tokens are saved to `~/.letterstory/config.json` (mode 600) and
+refresh automatically. Run `letterstory logout` to revoke the session and forget it.
+
+**Or use a static API key** (for CI/automation, or when you want scoped-down access):
+
 You need a Letterstory API key (starts with `ls_`; legacy `lb_` keys still work) with the `deployment:read` and
 `deployment:write` capabilities — mint one in the app under **Settings → API keys**.
 Add `deployment:domain` too if you plan to buy custom domains.
@@ -44,8 +85,9 @@ letterstory login --key ls_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
 Credentials resolve from `--key`/`--url` flags, then `LETTERSTORY_API_KEY` /
 `LETTERSTORY_API_URL`, then `~/.letterstory/config.json` (written by `login`, mode 600).
 
-Run `letterstory whoami` (alias `status`) any time to confirm which key/url resolved and
-see your company profile.
+Run `letterstory whoami` (alias `status`) any time to confirm which key/url (or OAuth session)
+resolved and see your company profile. Run `letterstory config` to see the resolved url and
+credential source without making a network call.
 
 ## Spin up a blog
 

package/lib/cli.mjs

@@ -3,6 +3,7 @@
 // never throws for user-facing problems (those become a printed CliError + code 1).
 
 import { LetterstoryClient, CliError, resolveConfig, readConfigFile, writeConfigFile } from "./client.mjs";
+import { checkForUpdate } from "./update-check.mjs";
 import {
 	cmdLogin,
 	cmdLogout,
@@ -24,10 +25,12 @@ import {
 	cmdStrategy,
 	cmdOnboarding,
 	cmdInsights,
+	cmdKernel,
+	cmdPhantomJob,
 } from "./commands.mjs";
 
 // Keep in sync with cli/package.json.
-export const VERSION = "0.2.1";
+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.
@@ -169,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]
@@ -227,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
@@ -244,6 +262,9 @@ export function defaultIo() {
 		sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
 		pollIntervalMs: envInt("LETTERSTORY_POLL_INTERVAL_MS", 4000),
 		maxPolls: envInt("LETTERSTORY_MAX_POLLS", 90),
+		// Only a *real* CLI invocation (never a test, which always builds its own io)
+		// gets the background update-version check — see the `finally` block in run().
+		updateCheck: true,
 	};
 }
 
@@ -298,5 +319,18 @@ export async function run(argv, io = defaultIo()) {
 			return 1;
 		}
 		throw err;
+	} finally {
+		// Fire-and-await (bounded by checkForUpdate's own short fetch timeout) so the
+		// nudge, if any, is printed before the bin's process.exit() — but a warm cache
+		// (the common case) resolves with no network call at all, so this is normally
+		// instant. --json output stays machine-clean; real errors above already returned.
+		if (io.updateCheck && !flags.json) {
+			try {
+				const notice = await checkForUpdate({ currentVersion: VERSION });
+				if (notice) io.error(notice);
+			} catch {
+				// Never let the update nudge itself become the reason a command fails.
+			}
+		}
 	}
 }

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/lib/update-check.mjs

@@ -0,0 +1,94 @@
+// Best-effort "a newer version is out" nudge. Checks the npm registry at most once
+// every 24h and caches the result next to the config file, so a warm cache never
+// touches the network and a cold/offline check never slows or breaks a command —
+// every failure mode (no network, slow DNS, registry down, unwritable home) is
+// swallowed and just means no nudge gets printed.
+
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, dirname } from "node:path";
+
+const REGISTRY_URL = "https://registry.npmjs.org/@letterstory/cli/latest";
+const CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000;
+const FETCH_TIMEOUT_MS = 500;
+
+function cachePath() {
+	const home = process.env.LETTERSTORY_CONFIG_HOME || homedir();
+	return join(home, ".letterstory", "update-check.json");
+}
+
+function readCache() {
+	try {
+		if (!existsSync(cachePath())) return null;
+		return JSON.parse(readFileSync(cachePath(), "utf8"));
+	} catch {
+		return null;
+	}
+}
+
+function writeCache(data) {
+	try {
+		const path = cachePath();
+		mkdirSync(dirname(path), { recursive: true });
+		writeFileSync(path, JSON.stringify(data));
+	} catch {
+		// Read-only home, no disk space, etc. — caching is an optimization, not a requirement.
+	}
+}
+
+// Plain dotted-numeric semver compare — this CLI's versions are always X.Y.Z, no
+// prerelease/build metadata to worry about.
+function isNewer(latest, current) {
+	const a = String(latest).split(".").map(Number);
+	const b = String(current).split(".").map(Number);
+	for (let i = 0; i < Math.max(a.length, b.length); i++) {
+		const x = a[i] || 0;
+		const y = b[i] || 0;
+		if (x !== y) return x > y;
+	}
+	return false;
+}
+
+async function fetchLatestVersion(fetchImpl) {
+	const controller = new AbortController();
+	const timer = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
+	try {
+		const res = await fetchImpl(REGISTRY_URL, { signal: controller.signal });
+		if (!res.ok) return null;
+		const body = await res.json();
+		return typeof body.version === "string" ? body.version : null;
+	} catch {
+		return null; // offline, timed out, registry down, malformed response — no nudge, not an error
+	} finally {
+		clearTimeout(timer);
+	}
+}
+
+/**
+ * Returns a one-line nudge string if a newer version is published on npm, else null.
+ * Never throws. `fetchImpl`/`now` are injectable for tests; real callers use the
+ * defaults (global fetch, current time).
+ *
+ * @param {{ currentVersion: string, fetchImpl?: (url: string, init?: { signal?: AbortSignal }) => Promise<{ ok: boolean, json: () => Promise<any> }>, now?: number }} opts
+ * @returns {Promise<string | null>}
+ */
+export async function checkForUpdate({ currentVersion, fetchImpl = globalThis.fetch, now = Date.now() }) {
+	if (process.env.LETTERSTORY_NO_UPDATE_CHECK) return null;
+
+	const cache = readCache();
+	let latest = cache?.latestVersion;
+	const stale = !cache || typeof cache.checkedAt !== "number" || now - cache.checkedAt > CHECK_INTERVAL_MS;
+
+	if (stale) {
+		const fetched = await fetchLatestVersion(fetchImpl);
+		if (fetched) {
+			latest = fetched;
+			writeCache({ checkedAt: now, latestVersion: fetched });
+		} else if (!cache) {
+			return null; // first-ever check failed (e.g. offline) — nothing to compare against yet
+		}
+	}
+
+	if (!latest || !isNewer(latest, currentVersion)) return null;
+	return `Update available: ${currentVersion} → ${latest}. Run \`npm install -g @letterstory/cli@latest\` to upgrade. (Set LETTERSTORY_NO_UPDATE_CHECK=1 to silence this.)`;
+}

package/package.json

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