@letterstory/cli 0.27.1 → 0.29.0

package/lib/commands/phantom.mjs

@@ -0,0 +1,217 @@
+// `phantom` — Phantomstory: a collection Letterstory hosts as an independent publication.
+//
+// Hosting only: the site, its identity and theme, its domain, its rebuilds, its balance.
+// Publishing a post to it is `collection run --collection <its collection_id>`; its
+// editorial file is `collection config <its collection_id>` (or `phantom config <id>`,
+// which shows both joined). Phantoms are metered in SITES live at once (`phantom balance`),
+// not runs.
+
+import { readFileSync } from "node:fs";
+import { CliError } from "../client.mjs";
+import { flagStr, requirePositional, printResult, ok, toolField, followJob, argsFromFlags } from "./shared.mjs";
+
+function readJsonFileFlag(flags, flag) {
+	const path = flagStr(flags[flag]);
+	if (path === undefined) return undefined;
+	let text;
+	try {
+		text = readFileSync(path, "utf8");
+	} catch (error) {
+		throw new CliError(
+			`Could not read --${flag} ${path}: ${error instanceof Error ? error.message : String(error)}`
+		);
+	}
+	try {
+		return JSON.parse(text);
+	} catch {
+		throw new CliError(`--${flag} ${path} is not valid JSON.`);
+	}
+}
+function readJsonObjectFlag(flags, name) {
+	const inline = flagStr(flags[name]);
+	if (inline !== undefined) {
+		let parsed;
+		try {
+			parsed = JSON.parse(inline);
+		} 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;
+	}
+	return readJsonFileFlag(flags, `${name}-file`);
+}
+function stripScheme(domain) {
+	return String(domain)
+		.replace(/^https?:\/\//i, "")
+		.replace(/\/+$/, "");
+}
+
+export const ARGS = {
+	list_phantoms: { limit: { flag: "limit", type: "num" } },
+	get_phantom: { phantom_id: { positional: 0, label: "phantom-id", required: true } },
+	create_phantom: {
+		name: { flag: "name", required: true },
+		description: "description",
+		theme: "theme",
+		collection_id: { flag: "collection" },
+		customer_ref: { flag: "customer-ref" },
+		configure: { value: (flags) => (flags["no-configure"] === true ? false : undefined) },
+		config: { value: (flags) => readJsonObjectFlag(flags, "config") },
+		client_domain: { flag: "client-domain" },
+		dry_run: { flag: "dry-run", type: "bool" },
+	},
+	get_phantom_config: { phantom_id: { positional: 0, label: "phantom-id", required: true } },
+	set_phantom_config: {
+		phantom_id: { positional: 0, label: "phantom-id", required: true },
+		config: {
+			object: {
+				name: "name",
+				description: "description",
+				theme: "theme",
+				customer_ref: { flag: "customer-ref" },
+				collection_id: { flag: "collection" },
+			},
+		},
+		collection: { value: (flags) => readJsonObjectFlag(flags, "collection-config") },
+		configure: { flag: "configure", type: "bool" },
+		dry_run: { flag: "dry-run", type: "bool" },
+	},
+	delete_phantom: { phantom_id: { positional: 0, label: "phantom-id", required: true } },
+	rebuild_phantom: { phantom_id: { positional: 0, label: "phantom-id", required: true } },
+	get_phantom_diagnostics: { phantom_id: { positional: 0, label: "phantom-id", required: true } },
+	get_phantom_balance: {},
+	check_domain: {
+		domain: { value: (flags, positionals) => stripScheme(requirePositional(positionals, 0, "domain")) },
+	},
+	buy_domain: {
+		phantom_id: { positional: 0, label: "phantom-id", required: true },
+		domain: { value: (flags, positionals) => stripScheme(requirePositional(positionals, 1, "domain")) },
+	},
+	connect_domain: {
+		phantom_id: { positional: 0, label: "phantom-id", required: true },
+		domain: { value: (flags, positionals) => stripScheme(requirePositional(positionals, 1, "domain")) },
+	},
+};
+
+export async function cmdPhantom(ctx) {
+	const sub = ctx.positionals[0];
+	const rest = { ...ctx, positionals: ctx.positionals.slice(1) };
+	switch (sub) {
+		case "list":
+		case "ls":
+			return call(rest, "list_phantoms");
+		case "get":
+		case "show":
+		case "status":
+			return call(rest, "get_phantom");
+		case "new":
+		case "create":
+			return phantomCreate(rest);
+		case "config":
+			return phantomConfig(rest);
+		case "delete":
+		case "rm":
+			if (rest.flags.yes !== true) {
+				rest.io.error("Refusing to tear down without --yes.");
+				return 1;
+			}
+			return call(rest, "delete_phantom");
+		case "rebuild":
+			return call(rest, "rebuild_phantom");
+		case "diagnostics":
+		case "diag":
+			return call(rest, "get_phantom_diagnostics");
+		case "balance":
+			return call(rest, "get_phantom_balance");
+		case "domain":
+			return phantomDomain(rest);
+		default:
+			throw new CliError(
+				`Unknown phantom subcommand: ${sub ?? "(none)"}. Try: list, get, new, config, delete, rebuild, diagnostics, balance, domain`
+			);
+	}
+}
+
+async function call(ctx, tool) {
+	const result = await ctx.client.callTool(tool, argsFromFlags(ARGS[tool], ctx.flags, ctx.positionals));
+	printResult(ctx.io, ctx.flags, result);
+	return 0;
+}
+
+async function phantomCreate(ctx) {
+	const { client, flags, io, bin } = ctx;
+	const result = await client.callTool("create_phantom", argsFromFlags(ARGS.create_phantom, flags));
+	if (toolField(result, "dry_run")) {
+		printResult(io, flags, result);
+		return 0;
+	}
+	const id = toolField(result, "phantom")?.phantom_id ?? toolField(result, "phantom_id");
+	if (flags["no-wait"] === true || !id) {
+		ok(ctx, `Phantom ${id ?? "?"} provisioning. Poll with: ${bin} phantom get ${id ?? "<phantom-id>"}`);
+		printResult(io, flags, result);
+		return 0;
+	}
+	io.log(`Phantom ${id} provisioning — following…`);
+	let last = "";
+	const followed = await followJob(
+		io,
+		async () => {
+			const r = await client.callTool("get_phantom", { phantom_id: id });
+			const p = toolField(r, "phantom") ?? r;
+			const line = `${p.status}${p.phase ? ` · ${p.phase}` : ""}`;
+			if (line !== last) {
+				io.log(`  … ${line}`);
+				last = line;
+			}
+			return { done: p.status === "live" || p.status === "error", value: p };
+		},
+		{ intervalMs: 5000, ceilingMs: 10 * 60 * 1000 }
+	);
+	const p = followed.value;
+	if (p?.status === "live")
+		ok(ctx, `Live at ${p.url}. Configuration continues in the background: ${bin} phantom config ${id}`);
+	else if (p?.status === "error") io.error(`Provisioning failed: ${p.last_error ?? "unknown"}`);
+	else io.log(`Still provisioning. Poll with: ${bin} phantom get ${id}`);
+	printResult(io, flags, p ?? result);
+	return 0;
+}
+
+// `phantom config <id>` prints the joined file; any patch flag, --collection-config, or --configure applies.
+async function phantomConfig(ctx) {
+	const { client, flags, io, positionals } = ctx;
+	const args = argsFromFlags(ARGS.set_phantom_config, flags, positionals);
+	const patching = args.config !== undefined || args.collection !== undefined || args.configure !== undefined;
+	if (!patching) {
+		const result = await client.callTool(
+			"get_phantom_config",
+			argsFromFlags(ARGS.get_phantom_config, flags, positionals)
+		);
+		printResult(io, flags, result);
+		return 0;
+	}
+	const result = await client.callTool("set_phantom_config", args);
+	ok(ctx, `Applied: ${(toolField(result, "applied") ?? []).join(", ") || "nothing (dry run)"}.`);
+	printResult(io, flags, result);
+	return 0;
+}
+
+async function phantomDomain(ctx) {
+	const sub = ctx.positionals[0];
+	const rest = { ...ctx, positionals: ctx.positionals.slice(1) };
+	switch (sub) {
+		case "check":
+			return call(rest, "check_domain");
+		case "buy":
+			if (rest.flags.yes !== true) {
+				rest.io.error("Buying a domain spends real money. Re-run with --yes.");
+				return 1;
+			}
+			return call(rest, "buy_domain");
+		case "connect":
+			return call(rest, "connect_domain");
+		default:
+			throw new CliError(`Unknown phantom domain subcommand: ${sub ?? "(none)"}. Try: check, buy, connect`);
+	}
+}

package/lib/commands.mjs

@@ -1,12 +1,13 @@
 // Command handlers, split into focused modules under ./commands/*.mjs as the surface
-// grew past a single-file's worth of clarity (auth, discovery, deploy/domain, posts,
+// grew past a single-file's worth of clarity (auth, discovery, collection/phantom, posts,
 // collections, flows, connectors, strategy, insights). This file re-exports
 // everything so `cli.mjs` — and any test importing straight from "commands.mjs" —
 // keep a single, stable import path regardless of how the implementation is split.
 
 export * from "./commands/auth.mjs";
 export * from "./commands/discovery.mjs";
-export * from "./commands/deploy.mjs";
+export * from "./commands/collection.mjs";
+export * from "./commands/phantom.mjs";
 export * from "./commands/mcp.mjs";
 export * from "./commands/posts.mjs";
 export * from "./commands/reviewers.mjs";
@@ -23,7 +24,8 @@ export * from "./commands/arena.mjs";
 export * from "./commands/templates.mjs";
 export * from "./commands/autopen.mjs";
 export * from "./commands/kernel.mjs";
-export * from "./commands/phantom-job.mjs";
+export * from "./commands/lede.mjs";
+
 export * from "./commands/onboard.mjs";
 export * from "./commands/seers.mjs";
 export * from "./commands/shredder.mjs";

package/lib/documents.mjs

@@ -0,0 +1,141 @@
+// Document `--file` flags, resolved through the app's extraction door before any command runs.
+//
+// WHY THE CLI DOES NOT PARSE ANYTHING ITSELF. `--file` used to be `readFileSync(path, "utf8")`,
+// full stop. That is correct for a .md or .txt and silently wrong for everything else: a
+// `letterstory kernel write --file report.docx` sent the zip's raw bytes as the article input,
+// so decompose was handed `PK\x03\x04…` and asked to find a thesis in it. A .pdf was the same.
+// No error, no warning, just a run spent on noise.
+//
+// The app already had a real extractor (mammoth, pdf-parse, and the rest — src/lib/uploads),
+// so the fix is to USE it rather than grow a second one here: the bytes go to
+// `POST /api/documents/extract` and come back as text. One engine, one format list, one
+// refusal message, whether the document arrived from the Studio's dropzone, an MCP tool or
+// this flag. A CLI-local parser would have been the same mistake the browser copy was.
+//
+// Formats we can read without help (.md, .txt, …) are still read locally — no round trip for
+// the common case, and `letterstory` keeps working against a file when the network does not.
+//
+// And only formats the door actually reads are touched at all: `--file` means different things
+// to different commands (see NEEDS_EXTRACTION), so anything else is passed through untouched.
+
+import { readFileSync, statSync } from "node:fs";
+import { basename, extname } from "node:path";
+import { CliError } from "./client.mjs";
+
+/**
+ * Extensions whose bytes a model CANNOT use as they stand — a zip (docx, odt), a binary
+ * container (pdf), or control-word soup (rtf). Only these go to the extraction door.
+ *
+ * NARROW ON PURPOSE, twice over.
+ *
+ * It is an ALLOWLIST rather than "anything not plain text", because `--file` is OVERLOADED
+ * across the CLI: a prose body for `kernel write`, a JSON manifest for `seers apply`, an
+ * output DESTINATION for `seers export`. Resolving every non-plain-text `--file` sent
+ * `seers export --file seers.json` to the door and broke a command that was only ever going
+ * to WRITE that path.
+ *
+ * And it EXCLUDES html/markdown/csv/captions even though the door can read them, because
+ * those already are what the primitives take. `run_shred` accepts HTML and returns it with
+ * its images, embeds, links and attributes exactly as they arrived — extracting first would
+ * strip the scripts, styles and comments the shredder was asked to preserve, and
+ * `cli-shred-kernel-e2e` asserts those bytes cross the wire untouched. Passing them through
+ * is both lossless and what shipped.
+ *
+ * Kept honest by `__tests__/unit/lib/uploads/surface-parity.test.ts`, which asserts this set
+ * equals the registry's `plainText: false` rows rather than trusting them to stay aligned.
+ */
+const NEEDS_EXTRACTION = new Set(["docx", "pdf", "odt", "rtf"]);
+
+/**
+ * The `(inlineFlag, fileFlag)` pairs `readTextInput` reads, which is what makes this
+ * interception possible without touching 75 `argsFromFlags` call sites: the inline value
+ * WINS over the path, so resolving a document means setting the inline flag to its text and
+ * leaving the path alone.
+ *
+ * Adding a new `--x-file` flag means adding its pair here. The CLI parity test asserts that
+ * every `readTextInput` call in the tree has a row.
+ */
+export const DOCUMENT_FLAG_PAIRS = [
+	["body", "file"],
+	["brief", "brief-file"],
+	["text", "text-file"],
+];
+
+/**
+ * `readTextInput` pairs that are STRUCTURED ARGUMENTS, not documents — JSON a command parses
+ * immediately, so extraction must never touch them (a .json is not a document format, and
+ * routing one through the door would refuse it outright).
+ *
+ * Declared rather than merely omitted so the choice is a decision somebody made: the parity
+ * test asserts every `readTextInput` pair in the CLI appears in exactly ONE of these two
+ * lists, so a new `--x-file` flag cannot be added without answering "prose or JSON?".
+ */
+export const JSON_ARG_FLAG_PAIRS = [
+	// A topic plan, or a whole saved proposal (onboard.mjs readTopicPlan).
+	["plan", "plan-file"],
+	// A reviewed plan handed back to be applied verbatim (onboard.mjs readAcceptedPlan).
+	["accept-plan-json", "accept-plan"],
+];
+
+/** Lower-case extension without the dot. */
+function extOf(path) {
+	return extname(path).replace(/^\./, "").toLowerCase();
+}
+
+/**
+ * Extract a document's text by posting it to the app's door.
+ *
+ * Uses the same authenticated client every other command uses, so an expired session or a
+ * missing key fails the way it does everywhere else rather than as an opaque upload error.
+ */
+async function extractViaDoor(client, path) {
+	let bytes;
+	try {
+		bytes = readFileSync(path);
+	} catch (error) {
+		throw new CliError(`Could not read ${path}: ${error.message}`);
+	}
+	const form = new FormData();
+	form.append("file", new Blob([bytes]), basename(path));
+
+	const result = await client.postForm("/api/documents/extract", form);
+	if (typeof result?.text !== "string" || !result.text.trim()) {
+		throw new CliError(`${basename(path)} had no readable text.`);
+	}
+	// Worth saying out loud: a Google Docs export's images are gone, and a silent removal is
+	// how someone wonders later why the article came back without its figure.
+	if (result.notice) process.stderr.write(`${basename(path)}: ${result.notice}\n`);
+	return result.text;
+}
+
+/**
+ * Resolve every document `--*-file` flag in `flags` to text, in place.
+ *
+ * Plain-text formats are read locally; everything else goes through the door. A flag whose
+ * inline twin is already set is left alone — an explicit `--body` beats a `--file`, which is
+ * the precedence `readTextInput` has always had.
+ *
+ * `-` (stdin) is deliberately NOT handled here: it is always text by definition, and
+ * `readTextInput` already reads it.
+ */
+export async function resolveDocumentFlags(client, flags) {
+	for (const [inlineFlag, fileFlag] of DOCUMENT_FLAG_PAIRS) {
+		const path = flags[fileFlag];
+		if (typeof path !== "string" || !path || path === "-") continue;
+		// An explicit inline value wins; nothing to resolve.
+		if (flags[inlineFlag] !== undefined) continue;
+		// Not a format the door reads — leave the flag completely alone, whatever the command
+		// means by it (a JSON manifest, an output path, plain text readTextInput handles).
+		if (!NEEDS_EXTRACTION.has(extOf(path))) continue;
+
+		let size;
+		try {
+			size = statSync(path).size;
+		} catch (error) {
+			throw new CliError(`Could not read --${fileFlag} ${path}: ${error.message}`);
+		}
+		if (size === 0) throw new CliError(`--${fileFlag} ${path} is empty.`);
+
+		flags[inlineFlag] = await extractViaDoor(client, path);
+	}
+}

package/package.json

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