@letterstory/cli 0.1.1 → 0.2.1

package/lib/commands/discovery.mjs

@@ -0,0 +1,238 @@
+// Discovery / generic passthrough: `tools` (browse the manifest — list + show) and
+// `call`/`tool` (invoke any tool by name). This is the escape hatch that keeps every
+// tool reachable even ones with no dedicated command group. `discover()` is the same
+// unauthenticated GET both `tools list` and `tools show` read from — there's no
+// separate bundled/static manifest to keep in sync (unlike phantomstory-cli's
+// manifest.ts), so there's no `--live` flag here: it's always live, by construction.
+
+import { readFileSync } from "node:fs";
+import { CliError } from "../client.mjs";
+import { flagStr, flagList, requirePositional } from "./shared.mjs";
+
+// --- tools: list / show -----------------------------------------------------
+
+export async function cmdTools(ctx) {
+	const sub = ctx.positionals[0];
+	if (sub === undefined || sub === "list" || sub === "ls") {
+		const rest = { ...ctx, positionals: ctx.positionals.slice(sub === undefined ? 0 : 1) };
+		return toolsList(rest);
+	}
+	if (sub === "show") {
+		return toolsShow({ ...ctx, positionals: ctx.positionals.slice(1) });
+	}
+	throw new CliError(`Unknown tools subcommand: ${sub}. Try: list, show <name>`);
+}
+
+async function toolsList(ctx) {
+	const { client, io, flags } = ctx;
+	const doc = await client.discover();
+	const tools = doc.tools ?? [];
+	if (flags.json) {
+		io.log(JSON.stringify(tools, null, 2));
+		return 0;
+	}
+	io.log(`${tools.length} tools available at ${client.url}:\n`);
+	for (const t of tools) io.log(`  ${t.name} — ${t.description ?? ""}`);
+	io.log(``);
+	io.log(`  Run \`${ctx.bin} tools show <name>\` for a tool's full argument schema.`);
+	return 0;
+}
+
+async function toolsShow(ctx) {
+	const { client, positionals, flags, io } = ctx;
+	const name = requirePositional(positionals, 0, "name");
+	const doc = await client.discover();
+	const tool = (doc.tools ?? []).find((t) => t.name === name);
+	if (!tool) {
+		throw new CliError(`No tool named "${name}". See \`${ctx.bin} tools list\`.`);
+	}
+	if (flags.json) {
+		io.log(JSON.stringify(tool, null, 2));
+		return 0;
+	}
+	renderTool(io, tool);
+	return 0;
+}
+
+function renderTool(io, tool) {
+	io.log(tool.name);
+	io.log(`  ${tool.description ?? ""}`);
+	io.log(``);
+	io.log(`  capability: ${tool.capability ?? "(none)"}`);
+	const props = tool.inputSchema?.properties ?? {};
+	const required = new Set(tool.inputSchema?.required ?? []);
+	const names = Object.keys(props);
+	if (names.length === 0) {
+		io.log(`  (no arguments)`);
+		return;
+	}
+	io.log(``);
+	io.log(`  arguments:`);
+	for (const name of names) {
+		const req = required.has(name) ? "required" : "optional";
+		const detail = detailOf(props[name]);
+		io.log(`    ${name} (${typeLabel(props[name])}, ${req})${detail ? ` — ${detail}` : ""}`);
+	}
+}
+
+function typeLabel(prop) {
+	if (!prop) return "any";
+	if (prop.enum) return "enum";
+	if (typeof prop.type === "string") return prop.type;
+	if (Array.isArray(prop.type)) return prop.type.filter((t) => t !== "null").join("|") || "any";
+	if (prop.anyOf) {
+		const types = prop.anyOf.map((a) => (typeof a.type === "string" ? a.type : "any")).filter((t) => t !== "null");
+		return [...new Set(types)].join("|") || "any";
+	}
+	return "any";
+}
+
+function detailOf(prop) {
+	const parts = [];
+	if (prop.description) parts.push(prop.description);
+	if (prop.enum) parts.push(`one of: ${prop.enum.map(String).join(", ")}`);
+	if (prop.default !== undefined) parts.push(`default: ${JSON.stringify(prop.default)}`);
+	return parts.join(" · ");
+}
+
+// --- call / tool: raw dispatcher --------------------------------------------
+
+// Escape hatch: call any tool by name. Args come from --args '<json>', or from
+// individual string flags (everything after the tool name). Keeps the whole
+// manifest reachable without a bespoke subcommand per tool. This is the original,
+// stable spelling; `tool` (below) is Mathew's phantomstory-cli name for the same
+// idea, with schema-aware argument coercion added on top.
+export async function cmdCall(ctx) {
+	const { client, positionals, flags, io } = ctx;
+	const name = requirePositional(positionals, 0, "tool");
+	let args = {};
+	if (flags.args !== undefined) {
+		try {
+			args = JSON.parse(flagStr(flags.args) ?? "");
+		} catch {
+			throw new CliError(`--args must be a JSON object, e.g. --args '{"name":"My Blog"}'`);
+		}
+	} else {
+		for (const [k, v] of Object.entries(flags)) {
+			if (k === "json" || k === "url" || k === "key") continue;
+			args[k] = v;
+		}
+	}
+	const result = await client.callTool(name, args);
+	io.log(typeof result === "string" ? result : JSON.stringify(result, null, 2));
+	return 0;
+}
+
+// `tool <name> [--arg k=v ...] [--json-args '{…}'] [--stdin]` — phantomstory-cli's
+// raw dispatcher. Unlike `call`, args are coerced toward the tool's real schema
+// (`--arg limit=5` becomes a number, `--arg tags=a,b` an array), and can be piped in
+// as JSON. Precedence low-to-high: --stdin, then --json-args, then --arg (most
+// specific wins) — matches phantomstory-cli's tools.ts.
+export async function cmdTool(ctx) {
+	const { client, positionals, flags, io } = ctx;
+	const name = requirePositional(positionals, 0, "tool");
+	const doc = await client.discover();
+	const tool = (doc.tools ?? []).find((t) => t.name === name);
+	if (!tool && !flags.quiet) {
+		io.error(`Warning: "${name}" is not in the discovered catalog; sending anyway.`);
+	}
+
+	let args = {};
+	if (flags.stdin) args = { ...args, ...asObject(readStdinJson()) };
+	const jsonArgs = flagStr(flags["json-args"]);
+	if (jsonArgs !== undefined) {
+		let parsed;
+		try {
+			parsed = JSON.parse(jsonArgs);
+		} catch (err) {
+			throw new CliError(`Invalid --json-args: ${err.message}`);
+		}
+		args = { ...args, ...asObject(parsed) };
+	}
+	const pairs = coerceToSchema(parseKeyVals(flagList(flags.arg)), tool?.inputSchema);
+	args = { ...args, ...pairs };
+
+	const result = await client.callTool(name, args);
+	io.log(typeof result === "string" ? result : JSON.stringify(result, null, 2));
+	return 0;
+}
+
+function asObject(v) {
+	if (v && typeof v === "object" && !Array.isArray(v)) return v;
+	throw new CliError("Arguments must be a JSON object.");
+}
+
+function readStdinJson() {
+	if (process.stdin.isTTY) {
+		throw new CliError("No data on stdin — pipe input in, or omit --stdin.");
+	}
+	let raw;
+	try {
+		raw = readFileSync(0, "utf8");
+	} catch (err) {
+		throw new CliError(`Could not read stdin: ${err.message}`);
+	}
+	if (!raw) return {};
+	try {
+		return JSON.parse(raw);
+	} catch (err) {
+		throw new CliError(`Invalid JSON on stdin: ${err.message}`);
+	}
+}
+
+function parseKeyVals(items) {
+	const out = {};
+	for (const item of items) {
+		const eq = item.indexOf("=");
+		if (eq === -1) throw new CliError(`Malformed --arg "${item}", expected key=value.`);
+		out[item.slice(0, eq)] = item.slice(eq + 1);
+	}
+	return out;
+}
+
+function coerceToSchema(raw, schema) {
+	const props = schema?.properties ?? {};
+	const out = {};
+	for (const [key, value] of Object.entries(raw)) out[key] = coerceValue(value, props[key]);
+	return out;
+}
+
+function coerceValue(value, prop) {
+	switch (resolveType(prop)) {
+		case "integer":
+		case "number": {
+			const n = Number(value);
+			return Number.isNaN(n) ? value : n;
+		}
+		case "boolean":
+			if (value === "true") return true;
+			if (value === "false") return false;
+			return value;
+		case "array":
+			return value
+				.split(",")
+				.map((s) => s.trim())
+				.filter((s) => s.length > 0);
+		case "object":
+			try {
+				return JSON.parse(value);
+			} catch (err) {
+				throw new CliError(`Invalid object value for --arg: ${err.message}`);
+			}
+		default:
+			return value;
+	}
+}
+
+function resolveType(prop) {
+	if (!prop) return undefined;
+	if (typeof prop.type === "string") return prop.type;
+	if (Array.isArray(prop.type)) return prop.type.find((t) => t !== "null");
+	if (prop.anyOf) {
+		for (const alt of prop.anyOf) {
+			const t = resolveType(alt);
+			if (t && t !== "null") return t;
+		}
+	}
+	return undefined;
+}

package/lib/commands/flows.mjs

@@ -0,0 +1,83 @@
+// `flows` — run editorial passes over articles, check run status, and manage the
+// flow_run.completed completion webhook. Ported from phantomstory-cli's flows.ts.
+
+import { CliError } from "../client.mjs";
+import { flagStr, requirePositional, printResult, compact, ok } from "./shared.mjs";
+
+export async function cmdFlows(ctx) {
+	const sub = ctx.positionals[0];
+	const rest = { ...ctx, positionals: ctx.positionals.slice(1) };
+	switch (sub) {
+		case "list":
+		case "ls":
+			return flowsList(rest);
+		case "run":
+			return flowsRun(rest);
+		case "status":
+			return flowsStatus(rest);
+		case "webhook":
+			return flowsWebhook(rest);
+		default:
+			throw new CliError(`Unknown flows subcommand: ${sub ?? "(none)"}. Try: list, run, status, webhook`);
+	}
+}
+
+async function flowsList(ctx) {
+	const { client, flags, io } = ctx;
+	const result = await client.callTool("list_flows", {});
+	printResult(io, flags, result);
+	return 0;
+}
+
+async function flowsRun(ctx) {
+	const { client, positionals, flags, io } = ctx;
+	const flowId = requirePositional(positionals, 0, "flow-id");
+	const articleId = requirePositional(positionals, 1, "article-id");
+	const result = await client.callTool("run_flow", { flow_id: flowId, article_id: articleId });
+	ok(ctx, "Flow run started.");
+	printResult(io, flags, result);
+	return 0;
+}
+
+async function flowsStatus(ctx) {
+	const { client, positionals, flags, io } = ctx;
+	const runId = requirePositional(positionals, 0, "run-id");
+	const result = await client.callTool("get_run_status", { flow_run_id: runId });
+	printResult(io, flags, result);
+	return 0;
+}
+
+async function flowsWebhook(ctx) {
+	const sub = ctx.positionals[0];
+	const rest = { ...ctx, positionals: ctx.positionals.slice(1) };
+	switch (sub) {
+		case "get":
+			return webhookGet(rest);
+		case "set":
+			return webhookSet(rest);
+		default:
+			throw new CliError(`Unknown flows webhook subcommand: ${sub ?? "(none)"}. Try: get, set`);
+	}
+}
+
+async function webhookGet(ctx) {
+	const { client, flags, io } = ctx;
+	const result = await client.callTool("get_webhook", {});
+	printResult(io, flags, result);
+	return 0;
+}
+
+async function webhookSet(ctx) {
+	const { client, flags, io } = ctx;
+	const url = flagStr(flags.url);
+	if (url === undefined) throw new CliError('Missing required --url (an https URL, or "none"/"off" to disable)');
+	const disable = ["none", "off", ""].includes(url.toLowerCase());
+	const args = compact({ webhook_secret: flagStr(flags.secret) });
+	// webhook_url is required and may legitimately be null; set it after compact()
+	// since compact() drops undefined (not null) — this assignment is deliberate.
+	args.webhook_url = disable ? null : url;
+	const result = await client.callTool("set_webhook", args);
+	ok(ctx, disable ? "Webhook disabled." : "Webhook set.");
+	printResult(io, flags, result);
+	return 0;
+}

package/lib/commands/insights.mjs

@@ -0,0 +1,51 @@
+// `insights` — Search Console impressions/clicks across the phantom network, at the
+// network, single-post, and top-posts levels. Ported from phantomstory-cli's
+// insights.ts.
+
+import { CliError } from "../client.mjs";
+import { flagStr, flagNum, requirePositional, printResult, compact } from "./shared.mjs";
+
+export async function cmdInsights(ctx) {
+	const sub = ctx.positionals[0];
+	const rest = { ...ctx, positionals: ctx.positionals.slice(1) };
+	switch (sub) {
+		case "site":
+			return insightsSite(rest);
+		case "post":
+			return insightsPost(rest);
+		case "top":
+			return insightsTop(rest);
+		default:
+			throw new CliError(`Unknown insights subcommand: ${sub ?? "(none)"}. Try: site, post, top`);
+	}
+}
+
+async function insightsSite(ctx) {
+	const { client, flags, io } = ctx;
+	const args = compact({ period: flagStr(flags.period), collection_id: flagStr(flags.collection) });
+	const result = await client.callTool("get_site_performance", args);
+	printResult(io, flags, result);
+	return 0;
+}
+
+async function insightsPost(ctx) {
+	const { client, positionals, flags, io } = ctx;
+	const articleId = requirePositional(positionals, 0, "article-id");
+	const args = compact({ article_id: articleId, period: flagStr(flags.period) });
+	const result = await client.callTool("get_post_performance", args);
+	printResult(io, flags, result);
+	return 0;
+}
+
+async function insightsTop(ctx) {
+	const { client, flags, io } = ctx;
+	const args = compact({
+		period: flagStr(flags.period),
+		collection_id: flagStr(flags.collection),
+		limit: flagNum(flags.limit),
+		sort: flagStr(flags.sort),
+	});
+	const result = await client.callTool("list_top_posts", args);
+	printResult(io, flags, result);
+	return 0;
+}

package/lib/commands/mcp.mjs

@@ -0,0 +1,52 @@
+// `mcp` — print ready-to-paste configuration for wiring the Letterstory MCP server
+// into an agent (Claude Code, Claude Desktop, Cursor, …). Same endpoint/auth header
+// the CLI itself uses (see client.mjs's `mcpEndpoint` / `x-integrations-key`), just
+// packaged for copy-paste instead of for this process's own requests.
+
+import { flagStr } from "./shared.mjs";
+
+export function cmdMcp(ctx) {
+	const { config, flags, io } = ctx;
+	const name = flagStr(flags.name) ?? "letterstory";
+	const endpoint = `${config.url}/api/mcp`;
+	const header = "x-integrations-key";
+	const printKey = Boolean(flags["print-key"]);
+	const keyValue = printKey && config.key ? config.key : "${LETTERSTORY_API_KEY}";
+
+	const jsonConfig = {
+		mcpServers: {
+			[name]: {
+				type: "http",
+				url: endpoint,
+				headers: { [header]: keyValue },
+			},
+		},
+	};
+
+	if (flags.json) {
+		io.log(JSON.stringify(jsonConfig, null, 2));
+		return 0;
+	}
+
+	const masked = config.key ? `${config.key.slice(0, 6)}…${config.key.slice(-4)}` : undefined;
+
+	io.log(`Letterstory MCP`);
+	io.log(`  endpoint:  ${endpoint}`);
+	io.log(`  transport: streamable-http`);
+	io.log(`  auth:      ${header}: ${masked ?? "(no key found — run `" + ctx.bin + " login` first)"}`);
+
+	io.log(``);
+	io.log(`Claude Code:`);
+	io.log(`  claude mcp add --transport http ${name} ${endpoint} \\`);
+	io.log(`      --header "${header}: ${printKey && config.key ? config.key : "YOUR_KEY"}"`);
+
+	io.log(``);
+	io.log(`Claude Desktop / Cursor (mcpServers block):`);
+	for (const line of JSON.stringify(jsonConfig, null, 2).split("\n")) io.log(`  ${line}`);
+
+	if (!printKey) {
+		io.log(``);
+		io.log(`Tip: export LETTERSTORY_API_KEY=…, or re-run with --print-key to inline it.`);
+	}
+	return 0;
+}

package/lib/commands/posts.mjs

@@ -0,0 +1,122 @@
+// `posts` (draft/read/publish articles) and `published` (the frozen public view).
+// 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 { CliError } from "../client.mjs";
+import {
+	flagStr,
+	flagNum,
+	requireFlag,
+	requirePositional,
+	printResult,
+	compact,
+	ok,
+	readBodyInput,
+} from "./shared.mjs";
+
+export async function cmdPosts(ctx) {
+	const sub = ctx.positionals[0];
+	const rest = { ...ctx, positionals: ctx.positionals.slice(1) };
+	switch (sub) {
+		case "list":
+		case "ls":
+			return postsList(rest);
+		case "show":
+			return postsShow(rest);
+		case "new":
+			return postsNew(rest);
+		case "publish":
+			return postsPublish(rest);
+		case "unpublish":
+			return postsUnpublish(rest);
+		default:
+			throw new CliError(
+				`Unknown posts subcommand: ${sub ?? "(none)"}. Try: list, show, new, publish, unpublish`
+			);
+	}
+}
+
+async function postsList(ctx) {
+	const { client, flags, io } = ctx;
+	const args = compact({ limit: flagNum(flags.limit), collection_id: flagStr(flags.collection) });
+	const result = await client.callTool("list_articles", args);
+	printResult(io, flags, result);
+	return 0;
+}
+
+async function postsShow(ctx) {
+	const { client, positionals, flags, io } = ctx;
+	const id = requirePositional(positionals, 0, "article-id");
+	const result = await client.callTool("get_article", { article_id: id });
+	printResult(io, flags, result);
+	return 0;
+}
+
+async function postsNew(ctx) {
+	const { client, flags, io } = ctx;
+	const title = requireFlag(flags, "title");
+	const collection = requireFlag(flags, "collection");
+	const body = readBodyInput(flags);
+	if (!body) throw new CliError("Provide --body or --file <path>.");
+	const result = await client.callTool("ingest_article", { title, body, collection_id: collection });
+	ok(ctx, `Created draft "${title}".`);
+	printResult(io, flags, result);
+	return 0;
+}
+
+async function postsPublish(ctx) {
+	const { client, positionals, flags, io } = ctx;
+	const id = requirePositional(positionals, 0, "article-id");
+	const result = await client.callTool("publish_article", { article_id: id });
+	ok(ctx, "Published.");
+	printResult(io, flags, result);
+	return 0;
+}
+
+async function postsUnpublish(ctx) {
+	const { client, positionals, flags, io } = ctx;
+	const id = requirePositional(positionals, 0, "article-id");
+	const result = await client.callTool("unpublish_article", { article_id: id });
+	ok(ctx, "Unpublished.");
+	printResult(io, flags, result);
+	return 0;
+}
+
+// --- published (frozen public view) -----------------------------------------
+
+export async function cmdPublished(ctx) {
+	const sub = ctx.positionals[0];
+	const rest = { ...ctx, positionals: ctx.positionals.slice(1) };
+	switch (sub) {
+		case "list":
+		case "ls":
+			return publishedList(rest);
+		case "show":
+			return publishedShow(rest);
+		default:
+			throw new CliError(`Unknown published subcommand: ${sub ?? "(none)"}. Try: list, show`);
+	}
+}
+
+async function publishedList(ctx) {
+	const { client, flags, io } = ctx;
+	const args = compact({
+		limit: flagNum(flags.limit),
+		collection_id: flagStr(flags.collection),
+		format: flagStr(flags.format),
+	});
+	const result = await client.callTool("list_published", args);
+	printResult(io, flags, result);
+	return 0;
+}
+
+async function publishedShow(ctx) {
+	const { client, flags, io } = ctx;
+	const id = flagStr(flags.id);
+	const slug = flagStr(flags.slug);
+	if (id === undefined && slug === undefined) throw new CliError("Pass --id or --slug.");
+	const args = compact({ article_id: id, slug, format: flagStr(flags.format) });
+	const result = await client.callTool("get_published", args);
+	printResult(io, flags, result);
+	return 0;
+}

package/lib/commands/shared.mjs

@@ -0,0 +1,95 @@
+// Helpers shared by every command module: flag/positional readers, JSON-vs-formatted
+// output, and the --quiet-aware success line. Kept dependency-free like the rest of
+// the CLI — no formatting library, just small string builders.
+
+import { readFileSync } from "node:fs";
+import { CliError } from "../client.mjs";
+
+// A flag with no value parses to `true`; coerce that back to undefined so a bare
+// `--name` reads as "missing", not the string "true". A repeated flag (see cli.mjs's
+// parseArgs) parses to an array — also "missing" for a single-value read.
+export function flagStr(v) {
+	return typeof v === "string" ? v : undefined;
+}
+
+export function flagNum(v) {
+	const s = flagStr(v);
+	if (s === undefined) return undefined;
+	const n = Number(s);
+	if (!Number.isFinite(n)) throw new CliError(`Expected a number, got "${s}"`);
+	return n;
+}
+
+export function flagBool(v) {
+	return v === true;
+}
+
+// Repeatable flags (e.g. `--topic a --topic b`) accumulate into an array in
+// parseArgs; a single occurrence stays a plain string. Normalize both to a list.
+export function flagList(v) {
+	if (v === undefined) return [];
+	if (Array.isArray(v)) return v.filter((x) => typeof x === "string");
+	return typeof v === "string" ? [v] : [];
+}
+
+export function requireFlag(flags, name) {
+	const v = flagStr(flags[name]);
+	if (v === undefined) throw new CliError(`Missing required --${name}`);
+	return v;
+}
+
+export function requirePositional(positionals, index, label) {
+	const v = positionals[index];
+	if (v === undefined) throw new CliError(`Missing required <${label}>`);
+	return v;
+}
+
+// Drop undefined entries so callTool args only carry fields the user actually set.
+export function compact(obj) {
+	const out = {};
+	for (const [k, v] of Object.entries(obj)) {
+		if (v !== undefined) out[k] = v;
+	}
+	return out;
+}
+
+export function printResult(io, flags, value, formatter) {
+	if (flags.json || !formatter) {
+		io.log(JSON.stringify(value, null, 2));
+	} else {
+		io.log(formatter(value));
+	}
+}
+
+// A success line that stays quiet under --quiet or --json (scripting doesn't want
+// chatter mixed into a parseable stream). Existing commands (deploy/domain) print
+// directly through io.log and are intentionally left alone; this gate is for the
+// new command groups only.
+export function ok(ctx, message) {
+	if (ctx.flags.quiet || ctx.flags.json) return;
+	ctx.io.log(message);
+}
+
+// Read a text body from --body, or --file (a path, or "-" for stdin). Returns
+// undefined if neither flag was given, so callers can decide whether that's an error.
+export function readBodyInput(flags) {
+	const body = flagStr(flags.body);
+	if (body !== undefined) return body;
+	const file = flagStr(flags.file);
+	if (file === undefined) return undefined;
+	if (file === "-") {
+		if (process.stdin.isTTY) {
+			throw new CliError("No data on stdin. Pipe input in, or use --body/--file <path> instead of --file -.");
+		}
+		try {
+			return readFileSync(0, "utf8");
+		} catch (err) {
+			throw new CliError(`Could not read stdin: ${err.message}`);
+		}
+	}
+	try {
+		return readFileSync(file, "utf8");
+	} catch (err) {
+		throw new CliError(`Could not read --file ${file}: ${err.message}`);
+	}
+}