@letterstory/cli 0.28.0 → 0.29.1

package/lib/commands/collection.mjs

@@ -0,0 +1,279 @@
+// `collection` — the content engine as a primitive, on both of its doors.
+//
+// A collection is a publication with a one-file configuration that produces and publishes
+// posts on a cadence; `collection run` produces ONE post on it (sourced, written, gated,
+// published, and — when Letterstory hosts the site — rebuilt). Runs are 20–60 minutes, so
+// `collection run` submits and then follows the run unless you tell it not to
+// (`--no-wait`); `collection run-status` picks it up later. A direct run spends the
+// collection's weekly cadence budget (its posts_per_week); the planner's own slots are the
+// budget being spent as designed.
+
+import { readFileSync } from "node:fs";
+import { CliError } from "../client.mjs";
+import { flagStr, 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`);
+}
+
+const TERMINAL = new Set(["published", "failed", "skipped", "cancelled"]);
+
+/**
+ * How every command in this file sources its tool inputs — see `argsFromFlags` in
+ * shared.mjs and `scripts/parity-check.ts`, which compares these keys against each tool's
+ * published input schema.
+ */
+export const ARGS = {
+	list_collections: {},
+	create_collection: {
+		name: { flag: "name", required: true },
+		description: "description",
+		config: { value: (flags) => readJsonObjectFlag(flags, "config") },
+	},
+	get_collection_config: {
+		collection_id: { positional: 0, label: "collection-id", required: true },
+	},
+	set_collection_config: {
+		collection_id: { positional: 0, label: "collection-id", required: true },
+		config: { value: (flags) => readJsonObjectFlag(flags, "config") },
+	},
+	delete_collection: {
+		collection_id: { positional: 0, label: "collection-id", required: true },
+	},
+	run_collection: {
+		collection_id: { flag: "collection", required: true },
+		topic: "topic",
+		topic_id: { flag: "spoke" },
+		suggestion_id: { flag: "headline" },
+		source_urls: { flag: "source", type: "list" },
+		must_include: { flag: "must-include", type: "list" },
+		research_depth: { flag: "depth", enum: ["barebones", "fleshed_out"] },
+		kernel_id: { flag: "kernel" },
+		verify: { value: (flags) => (flags["no-verify"] === true ? false : undefined) },
+		shred: { flag: "shred", type: "bool" },
+		mention_degree: { flag: "mention", enum: ["off", "subtle", "woven"] },
+		approval_mode: { flag: "approval", enum: ["autopilot", "review_window", "manual"] },
+		publish: { value: (flags) => (flags["no-publish"] === true ? false : undefined) },
+		rebuild: { value: (flags) => (flags["no-rebuild"] === true ? false : undefined) },
+		schedule_for: { flag: "at" },
+	},
+	get_collection_run: {
+		run_id: { positional: 0, label: "run-id", required: true },
+	},
+	list_collection_runs: {
+		collection_id: { flag: "collection" },
+		status: {
+			flag: "status",
+			enum: [
+				"scheduled",
+				"sourcing",
+				"writing",
+				"ready",
+				"publishing",
+				"published",
+				"failed",
+				"skipped",
+				"cancelled",
+			],
+		},
+		limit: { flag: "limit", type: "num" },
+	},
+	approve_collection_run: {
+		run_id: { positional: 0, label: "run-id", required: true },
+		publish_now: { flag: "now", type: "bool" },
+	},
+	cancel_collection_run: {
+		run_id: { positional: 0, label: "run-id", required: true },
+	},
+};
+
+export async function cmdCollection(ctx) {
+	const sub = ctx.positionals[0];
+	const rest = { ...ctx, positionals: ctx.positionals.slice(1) };
+	switch (sub) {
+		case "list":
+		case "ls":
+			return collectionList(rest);
+		case "new":
+		case "create":
+			return collectionCreate(rest);
+		case "config":
+			return collectionConfig(rest);
+		case "delete":
+		case "rm":
+			return collectionDelete(rest);
+		case "run":
+			return collectionRun(rest);
+		case "run-status":
+		case "status":
+			return collectionRunStatus(rest);
+		case "runs":
+			return collectionRuns(rest);
+		case "approve":
+			return collectionApprove(rest);
+		case "cancel":
+			return collectionCancel(rest);
+		default:
+			throw new CliError(
+				`Unknown collection subcommand: ${sub ?? "(none)"}. Try: list, new, config, delete, run, run-status, runs, approve, cancel`
+			);
+	}
+}
+
+async function collectionList(ctx) {
+	const result = await ctx.client.callTool("list_collections", argsFromFlags(ARGS.list_collections, ctx.flags));
+	printResult(ctx.io, ctx.flags, result);
+	return 0;
+}
+
+async function collectionCreate(ctx) {
+	const result = await ctx.client.callTool(
+		"create_collection",
+		argsFromFlags(ARGS.create_collection, ctx.flags, ctx.positionals)
+	);
+	ok(
+		ctx,
+		`Collection ${toolField(result, "collection.name") ?? ""} created (${toolField(result, "collection.collection_id") ?? "?"}).`
+	);
+	printResult(ctx.io, ctx.flags, result);
+	return 0;
+}
+
+// `collection config <id>` prints the one file; `--config '<json>'` or `--config-file cfg.json` patches it.
+async function collectionConfig(ctx) {
+	const { client, flags, io, positionals } = ctx;
+	const patch = readJsonObjectFlag(flags, "config");
+	if (patch === undefined) {
+		const result = await client.callTool(
+			"get_collection_config",
+			argsFromFlags(ARGS.get_collection_config, flags, positionals)
+		);
+		printResult(io, flags, result);
+		return 0;
+	}
+	const result = await client.callTool(
+		"set_collection_config",
+		argsFromFlags(ARGS.set_collection_config, flags, positionals)
+	);
+	ok(ctx, `Applied: ${(toolField(result, "applied") ?? []).join(", ") || "nothing"}.`);
+	printResult(io, flags, result);
+	return 0;
+}
+
+async function collectionDelete(ctx) {
+	if (ctx.flags.yes !== true) {
+		ctx.io.error("Refusing to delete without --yes.");
+		return 1;
+	}
+	const result = await ctx.client.callTool(
+		"delete_collection",
+		argsFromFlags(ARGS.delete_collection, ctx.flags, ctx.positionals)
+	);
+	printResult(ctx.io, ctx.flags, result);
+	return 0;
+}
+
+async function collectionRun(ctx) {
+	const { client, flags, io, bin } = ctx;
+	const args = argsFromFlags(ARGS.run_collection, flags, ctx.positionals);
+	const result = await client.callTool("run_collection", args);
+	const runId = toolField(result, "run_id");
+	if (flags["no-wait"] === true || !runId) {
+		ok(ctx, `Run started as ${runId ?? "?"}. Follow it with: ${bin} collection run-status ${runId ?? "<run-id>"}`);
+		printResult(io, flags, result);
+		return 0;
+	}
+	io.log(`Run ${runId} started — following (20–60 min; Ctrl-C and use run-status to pick it up later)…`);
+	let lastLine = "";
+	const followed = await followJob(
+		io,
+		async () => {
+			const r = await client.callTool("get_collection_run", { run_id: runId });
+			const run = toolField(r, "run") ?? r;
+			const line = `${run.status}${run.phase ? ` · ${run.phase}` : ""}${run.phase_detail ? ` — ${run.phase_detail}` : ""}`;
+			if (line !== lastLine) {
+				io.log(`  … ${line}`);
+				lastLine = line;
+			}
+			if (run.status === "ready" && run.approval?.mode !== "autopilot" && !run.approval?.approved_at)
+				return { done: true, value: run };
+			return { done: TERMINAL.has(run.status), value: run };
+		},
+		{ intervalMs: 30000, ceilingMs: 90 * 60 * 1000 }
+	);
+	const run = followed.value;
+	if (run?.status === "ready") {
+		ok(ctx, `Written and waiting for approval. Approve with: ${bin} collection approve ${runId} [--now]`);
+	} else if (!followed.settled) {
+		io.log(`Still running. Pick it up with: ${bin} collection run-status ${runId}`);
+	}
+	printResult(io, flags, run ?? result);
+	return 0;
+}
+
+async function collectionRunStatus(ctx) {
+	const result = await ctx.client.callTool(
+		"get_collection_run",
+		argsFromFlags(ARGS.get_collection_run, ctx.flags, ctx.positionals)
+	);
+	printResult(ctx.io, ctx.flags, result);
+	return 0;
+}
+
+async function collectionRuns(ctx) {
+	const result = await ctx.client.callTool(
+		"list_collection_runs",
+		argsFromFlags(ARGS.list_collection_runs, ctx.flags)
+	);
+	printResult(ctx.io, ctx.flags, result);
+	return 0;
+}
+
+async function collectionApprove(ctx) {
+	const result = await ctx.client.callTool(
+		"approve_collection_run",
+		argsFromFlags(ARGS.approve_collection_run, ctx.flags, ctx.positionals)
+	);
+	ok(ctx, `Approved${ctx.flags.now === true ? " — publishing now" : ""}.`);
+	printResult(ctx.io, ctx.flags, result);
+	return 0;
+}
+
+async function collectionCancel(ctx) {
+	const result = await ctx.client.callTool(
+		"cancel_collection_run",
+		argsFromFlags(ARGS.cancel_collection_run, ctx.flags, ctx.positionals)
+	);
+	ok(ctx, toolField(result, "cancelled") ? "Cancelled." : "Nothing was in flight.");
+	printResult(ctx.io, ctx.flags, result);
+	return 0;
+}

package/lib/commands/collections.mjs

@@ -3,6 +3,7 @@
 
 import { CliError } from "../client.mjs";
 import { flagStr, printResult, ok, argsFromFlags } from "./shared.mjs";
+import { cmdCollection } from "./collection.mjs";
 
 // `--flag none|off|""` clears a nullable field; the server takes null for that.
 const clearable = (flag) => ({
@@ -21,11 +22,6 @@ const stringBool = (flag) => ({
 // How every tool this module calls gets its arguments — see `argsFromFlags` in shared.mjs.
 // `scripts/parity-check.ts` compares these keys against each tool's published input schema.
 export const ARGS = {
-	list_collections: {},
-	create_collection: {
-		name: { flag: "name", required: true },
-		description: "description",
-	},
 	update_collection: {
 		collection_id: { positional: 0, label: "collection-id", required: true },
 		name: "name",
@@ -35,9 +31,6 @@ export const ARGS = {
 		cover_canvas_type_id: clearable("cover-canvas-type-id"),
 		seo_market: "seo-market",
 	},
-	delete_collection: {
-		collection_id: { positional: 0, label: "collection-id", required: true },
-	},
 	assign_article_to_collection: {
 		article_id: { positional: 0, label: "article-id", required: true },
 		collection_id: { positional: 1, label: "collection-id", required: true },
@@ -83,17 +76,23 @@ export async function cmdCollections(ctx) {
 	const sub = ctx.positionals[0];
 	const rest = { ...ctx, positionals: ctx.positionals.slice(1) };
 	switch (sub) {
+		// The primitive's own commands live in collection.mjs (one door: `collection run`);
+		// `collections` keeps the legacy verbs and forwards the shared ones.
 		case "list":
 		case "ls":
-			return collectionsList(rest);
 		case "new":
 		case "create":
-			return collectionsNew(rest);
-		case "update":
-			return collectionsUpdate(rest);
 		case "delete":
 		case "rm":
-			return collectionsDelete(rest);
+		case "config":
+		case "run":
+		case "run-status":
+		case "runs":
+		case "approve":
+		case "cancel":
+			return cmdCollection(ctx);
+		case "update":
+			return collectionsUpdate(rest);
 		case "assign":
 			return collectionsAssign(rest);
 		case "autopen":
@@ -130,22 +129,6 @@ async function collectionsActivate(ctx) {
 	return 0;
 }
 
-async function collectionsList(ctx) {
-	const { client, flags, io } = ctx;
-	const result = await client.callTool("list_collections", {});
-	printResult(io, flags, result);
-	return 0;
-}
-
-async function collectionsNew(ctx) {
-	const { client, flags, io } = ctx;
-	const args = argsFromFlags(ARGS.create_collection, flags);
-	const result = await client.callTool("create_collection", args);
-	ok(ctx, `Created collection "${args.name}".`);
-	printResult(io, flags, result);
-	return 0;
-}
-
 async function collectionsUpdate(ctx) {
 	const { client, positionals, flags, io } = ctx;
 	const patch = argsFromFlags(ARGS.update_collection, flags, positionals);
@@ -160,19 +143,6 @@ async function collectionsUpdate(ctx) {
 	return 0;
 }
 
-async function collectionsDelete(ctx) {
-	const { client, positionals, flags, io } = ctx;
-	const args = argsFromFlags(ARGS.delete_collection, flags, positionals);
-	if (!flags.yes) {
-		io.error(`Re-run with --yes to confirm: ${ctx.bin} collections delete ${args.collection_id} --yes`);
-		return 1;
-	}
-	const result = await client.callTool("delete_collection", args);
-	ok(ctx, "Collection deleted.");
-	printResult(io, flags, result);
-	return 0;
-}
-
 async function collectionsAssign(ctx) {
 	const { client, positionals, flags, io } = ctx;
 	const result = await client.callTool(

package/lib/commands/onboard.mjs

@@ -1,10 +1,10 @@
 // `onboard` — the one-shot phantom onboarding recipe: a client domain in, a live phantom
-// blog with its first post(s) out. It drives ONE server tool, `onboard_phantom`:
+// blog with its first post(s) out. It drives ONE server tool, `plan_phantom`:
 //   - a bare `onboard <domain>` is a safe DRY RUN (accept:false) — it prints the proposed
 //     plan (masthead name, description, strategy, cadence/cover/seed defaults) and stops.
-//   - `--accept` (or any override flag) APPLIES: `onboard_phantom{accept:true}` starts a
+//   - `--accept` (or any override flag) APPLIES: `plan_phantom{accept:true}` starts a
 //     durable onboarding job server-side and returns a job_id; this command then polls
-//     `get_phantom_onboard_status` until the job is done (provision → configure → seed).
+//     `get_phantom_launch_status` until the job is done (provision → configure → seed).
 //
 // `--about "<the beat>"` is the highest-leverage flag: it becomes the publication's planner
 // steering prompt, so it shapes the topic map and every post the site ever writes — not just
@@ -120,7 +120,7 @@ export const ARGS = {
 	get_domain_onboard_status: {
 		job_id: "attach",
 	},
-	onboard_phantom: {
+	plan_phantom: {
 		domain: { positional: 0, label: "domain", required: true },
 		// --accept gates the two-call flow below (dry run, then apply) rather than being
 		// forwarded: the first call never sends it, the second always sends true.
@@ -152,8 +152,8 @@ export const ARGS = {
 			},
 		},
 	},
-	get_phantom_onboard_status: {
-		job_id: { internal: "the job id onboard_phantom just returned" },
+	get_phantom_launch_status: {
+		job_id: { internal: "the job id plan_phantom just returned" },
 	},
 	propose_phantom_plan: {
 		client_domain: { positional: 0, label: "client-domain" },
@@ -372,7 +372,7 @@ async function cmdOnboardMastheads(ctx) {
 function overridesFromFlags(flags) {
 	// A chosen topic plan pins direction + pillars; an explicit --about still wins on direction.
 	const plan = readTopicPlan(flags);
-	const overrides = argsFromFlags(ARGS.onboard_phantom.overrides.object, flags, [], { plan });
+	const overrides = argsFromFlags(ARGS.plan_phantom.overrides.object, flags, [], { plan });
 	// buy_now spends real money against a 2-per-org cap; refusing the mismatch here beats
 	// silently downgrading it to a subdomain launch the caller didn't ask for.
 	if (overrides.domain_mode && overrides.domain_mode !== "subdomain" && !overrides.site_domain) {
@@ -768,7 +768,7 @@ export async function cmdOnboard(ctx) {
 	if (!reviewedPlan) {
 		// Step 1: dry-run plan (accept defaults to false server-side). Persists nothing.
 		const dryRun = await client.callTool(
-			"onboard_phantom",
+			"plan_phantom",
 			compact({ domain, overrides: Object.keys(overrides).length ? overrides : undefined })
 		);
 		ok(ctx, "Onboarding plan:");
@@ -801,7 +801,7 @@ export async function cmdOnboard(ctx) {
 	// Step 3: apply — start the durable onboarding job.
 	ok(ctx, "Applying — starting the onboarding job…");
 	const started = await client.callTool(
-		"onboard_phantom",
+		"plan_phantom",
 		compact({
 			domain,
 			accept: true,
@@ -810,14 +810,14 @@ export async function cmdOnboard(ctx) {
 		})
 	);
 	const jobId = started.job_id;
-	if (!jobId) throw new CliError("onboard_phantom did not return a job id.");
+	if (!jobId) throw new CliError("plan_phantom did not return a job id.");
 
 	// Step 4: poll the job to a terminal state, printing stage transitions.
 	let lastStage = null;
 	const final = await pollUntil(
 		io,
 		async () => {
-			const s = await client.callTool("get_phantom_onboard_status", { job_id: jobId });
+			const s = await client.callTool("get_phantom_launch_status", { job_id: jobId });
 			if (s.status === "failed")
 				throw new CliError(`Onboarding failed at stage "${s.stage}": ${s.error ?? "unknown error"}`);
 			if (s.stage !== lastStage) {

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`);
+	}
+}