@letterstory/cli 0.13.0 → 0.15.0

package/README.md

@@ -229,6 +229,38 @@ letterstory onboarding status
 letterstory onboarding step --complete connect_domain
 ```
 
+### One-shot domain onboarding
+
+A bare company domain in, a fully-configured organization out — as ONE durable job that
+composes the existing engines: the main blog (imported from its sitemap or a connected
+CMS, content areas, topic map, SEO, series, company GEO probing, headlines), org visuals
+inferred from the site, the main blog's Enhance flow configured (new posts are enhanced;
+imported posts are left as published), a phantom provisioned + configured + seeded with
+posts that are actually written and published, and Seers in suggest mode when they fit.
+The job finishes from a readback: it waits (default 2h) for the seed posts to publish and
+the first GEO probe to land, then reports what landed.
+
+```bash
+# On the org behind your key (its registered domain is the source):
+letterstory phantom-onboard domain --about "payroll for platform teams" --posts 3 --watch
+letterstory phantom-onboard domain --sitemap https://acme.com/sitemap.xml --seers skip --no-visuals
+letterstory phantom-onboard domain --attach <job-id> --watch     # watch a job started elsewhere
+letterstory phantom-onboard domain --status                      # the org's latest domain onboarding
+
+# Staff: the key exchange (create the org first) needs a STAFF key with org:create —
+# mint your OWN, don't share one. --watch makes the whole recipe ONE command: the
+# freshly-minted org key is used only in this process's memory to poll to completion.
+LETTERSTORY_STAFF_API_KEY=<your staff key with org:create> \
+  letterstory admin create-org --domain acme.com --onboard --watch --about "payroll for platform teams"
+
+# Without --watch, it prints the org id, a fresh ORG-scoped API key (once), and the job
+# id — watch it yourself with:
+#   LETTERSTORY_API_KEY=<the printed key> letterstory phantom-onboard domain --attach <job-id> --watch
+```
+
+Everything the parent job does is also its own tool for existing orgs:
+`ensure_collection_enhance_flow`, `provision_org_visuals`, `propose_seers` (`--args '{"apply":true}'`).
+
 ## Content series
 
 A series is a coverage obligation, not a keyword bet: "content that looks like this",

package/lib/cli.mjs

@@ -37,10 +37,11 @@ import {
 	cmdTemplates,
 	cmdShredder,
 	cmdLandings,
+	cmdAdmin,
 } from "./commands.mjs";
 
 // Keep in sync with cli/package.json.
-export const VERSION = "0.13.0";
+export const VERSION = "0.15.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.
@@ -71,6 +72,16 @@ const BOOLEAN_FLAGS = new Set([
 	"stock-only",
 	"gate",
 	"skip",
+	// `phantom-onboard domain` / `admin create-org --onboard` switches.
+	"watch",
+	"status",
+	"no-phantom",
+	"no-visuals",
+	"no-enhance",
+	"no-key",
+	"onboard",
+	"test",
+	"real",
 ]);
 
 // Tiny argv parser: `--flag value`, `--flag=value`, boolean `--flag`, and positionals.
@@ -309,6 +320,39 @@ Collection onboarding (your OWN blog, on your org's domain — no provisioning):
                                                        --watch polls to completion, printing each
                                                        review note as it lands.
 
+Domain onboarding (ONE SHOT: a bare domain in, a fully-configured organization out):
+  ${bin === "phantom" ? "onboard" : "phantom-onboard"} domain [--about "the direction"] [--sitemap <url>] [--cms <provider>]
+          [--name "<main collection name>"] [--posts N] [--no-phantom] [--phantom-name X]
+          [--site-domain host] [--domain-mode subdomain|buy_now|connect_later]
+          [--seers suggest|skip] [--no-visuals] [--no-enhance] [--test]
+          [--readiness-minutes N] [--watch]
+                                                       On the org behind the key (its registered
+                                                       domain): onboard the main blog (the
+                                                       collection recipe), infer org visuals from
+                                                       the site, configure the main blog's Enhance
+                                                       flow, provision + configure + seed a phantom
+                                                       (default 3 posts, written and published),
+                                                       and create Seers in suggest mode when they
+                                                       fit — then wait (default 2h) for the seeds
+                                                       to publish and report what landed.
+  ${bin === "phantom" ? "onboard" : "phantom-onboard"} domain --attach <job-id> [--watch]
+                                                       Watch / read a job started elsewhere.
+  ${bin === "phantom" ? "onboard" : "phantom-onboard"} domain --status  Latest domain onboarding on this org.
+
+Admin (STAFF key — --staff-key / LETTERSTORY_STAFF_API_KEY; acts before an org exists):
+  admin create-org --domain <bare-domain> [--name "Acme"] [--test] [--no-key]
+          [--key-name N] [--capabilities a,b] [--onboard] [--watch] [+ the onboard domain flags]
+                                                       The key exchange: create the client org from
+                                                       its domain (one org per domain), mint an
+                                                       ORG-scoped API key and print it ONCE. With
+                                                       --onboard the domain onboarding starts in the
+                                                       same call; add --watch to poll it to
+                                                       completion in this same command — the org key
+                                                       is used only in memory for the poll, never
+                                                       written to disk or printed twice — a bare
+                                                       domain in, a fully-configured org out, one
+                                                       command.
+
 Seers (event-driven signals -> drafts):
   seers list                                           List seers with recent activity
   seers get <seer-id>                                  One seer's full config + poll state
@@ -428,6 +472,8 @@ const CLIENT_COMMANDS = {
 	templates: cmdTemplates,
 	shredder: cmdShredder,
 	landings: cmdLandings,
+	// Platform-scoped (staff key) — the only commands that act BEFORE an org exists.
+	admin: cmdAdmin,
 };
 
 // LETTERSTORY_POLL_INTERVAL_MS / LETTERSTORY_MAX_POLLS let an operator (or an

package/lib/commands/admin.mjs

@@ -0,0 +1,184 @@
+// `admin` — the PLATFORM-scoped commands, for staff. Everything else in this CLI is
+// org-scoped and rides the MCP endpoint with an org API key; these ride a STAFF API key
+// (`x-staff-api-key`, minted at Settings → Staff keys) against the superadmin REST
+// routes, because they exist precisely to act BEFORE an org exists.
+//
+//   admin create-org --domain acme.com [--name "Acme"] [--test] [--no-key] [--key-name N]
+//                    [--capabilities a,b] [--onboard] [--about "…"] [--sitemap <url>]
+//                    [--cms <provider>] [--posts N] [--seers suggest|skip] [--no-visuals]
+//                    [--no-enhance] [--readiness-minutes N] [--watch]
+//
+// The KEY EXCHANGE: create the client org from its domain (one org per domain; an existing
+// owner is adopted), mint an ORG-scoped API key for it and print the plaintext ONCE. With
+// --onboard, the one-shot domain onboarding (main blog + org visuals + enhance + phantom +
+// seers) starts in the same call. --onboard --watch makes the whole recipe ONE command: the
+// freshly-minted org key is used ONLY in this process's memory (never written to disk, never
+// re-printed) to poll the job to completion, reusing the exact same loop
+// `phantom-onboard domain --watch` uses. Without --watch, watch it afterwards with
+//   LETTERSTORY_API_KEY=<printed key> letterstory phantom-onboard domain --watch --attach <job-id>
+//
+// The staff key comes from --staff-key or LETTERSTORY_STAFF_API_KEY; the base URL from the
+// usual --url / LETTERSTORY_API_URL / config resolution.
+
+import { CliError, LetterstoryClient } from "../client.mjs";
+import { flagStr, flagNum, flagBool, flagList, printResult, compact, ok } from "./shared.mjs";
+import { watchDomainJob } from "./onboard.mjs";
+
+const SEER_MODES = ["suggest", "skip"];
+const CMS_PROVIDERS = ["webflow", "framer", "sanity", "contentful"];
+
+function staffKeyFrom(flags) {
+	const key = flagStr(flags["staff-key"]) || process.env.LETTERSTORY_STAFF_API_KEY || null;
+	if (!key) {
+		throw new CliError(
+			"admin commands need a STAFF API key: pass --staff-key <key> or set LETTERSTORY_STAFF_API_KEY " +
+				"(mint one at Settings → Staff keys with the org:create capability)."
+		);
+	}
+	return key;
+}
+
+/** POST a superadmin route with the staff key; surfaces the server's error text on non-2xx. */
+async function staffPost(ctx, path, body) {
+	const { client, flags } = ctx;
+	const url = `${client.url}${path}`;
+	const res = await client.fetch(url, {
+		method: "POST",
+		headers: { "content-type": "application/json", "x-staff-api-key": staffKeyFrom(flags) },
+		body: JSON.stringify(body),
+	});
+	let payload = null;
+	try {
+		payload = await res.json();
+	} catch {
+		payload = null;
+	}
+	if (!res.ok) {
+		const message = payload?.error ?? `${res.status} ${res.statusText}`;
+		throw new CliError(`${path} failed: ${message}`);
+	}
+	return payload ?? {};
+}
+
+function onboardOptionsFromFlags(flags) {
+	const seers = flagStr(flags.seers);
+	if (seers !== undefined && !SEER_MODES.includes(seers)) {
+		throw new CliError(`--seers must be one of: ${SEER_MODES.join(", ")}`);
+	}
+	const cms = flagStr(flags.cms);
+	if (cms !== undefined && !CMS_PROVIDERS.includes(cms)) {
+		throw new CliError(`--cms must be one of: ${CMS_PROVIDERS.join(", ")}`);
+	}
+	const posts = flagNum(flags.posts);
+	const options = compact({
+		phantom:
+			posts !== undefined || flagBool(flags["no-phantom"])
+				? compact({ enabled: flagBool(flags["no-phantom"]) ? false : undefined, posts_to_seed: posts })
+				: undefined,
+		seers,
+		visuals: flagBool(flags["no-visuals"]) ? false : undefined,
+		enhance: flagBool(flags["no-enhance"]) ? false : undefined,
+		readiness_minutes: flagNum(flags["readiness-minutes"]),
+	});
+	return compact({
+		direction: flagStr(flags.about) ?? flagStr(flags.direction),
+		sitemap_url: flagStr(flags.sitemap),
+		cms_provider: cms,
+		options: Object.keys(options).length ? options : undefined,
+	});
+}
+
+function formatCreateOrg(r) {
+	const lines = [
+		`${r.org_created ? "Created" : "Reused"} organization "${r.org_name}" (${r.domain})`,
+		`  org_id: ${r.org_id}`,
+	];
+	if (r.api_key) {
+		lines.push(
+			`  api key "${r.api_key.name}" (${(r.api_key.capabilities ?? []).length} capabilities):`,
+			`    ${r.api_key.plain_key}`,
+			`  ${r.api_key.warning ?? "Save this key now — it is not shown again."}`
+		);
+	}
+	if (r.job_id) {
+		lines.push(
+			`  domain onboarding started: job ${r.job_id}`,
+			`  watch it: LETTERSTORY_API_KEY=<the key above> letterstory phantom-onboard domain --attach ${r.job_id} --watch`
+		);
+	}
+	if (r.error) lines.push(`  error: ${r.error}`);
+	return lines.join("\n");
+}
+
+async function cmdAdminCreateOrg(ctx) {
+	const { flags, io, client } = ctx;
+	const domain = flagStr(flags.domain);
+	if (!domain) throw new CliError("admin create-org requires --domain <bare-domain>.");
+
+	const watch = flagBool(flags.watch);
+	if (watch && !flagBool(flags.onboard)) {
+		throw new CliError("--watch needs --onboard (nothing to watch without a job).");
+	}
+	if (watch && flagBool(flags["no-key"])) {
+		throw new CliError("--watch needs an org key to poll with — drop --no-key.");
+	}
+
+	// --capabilities a,b or repeated --capabilities a --capabilities b.
+	const capabilities = flagList(flags.capabilities)
+		.flatMap((v) => v.split(","))
+		.map((v) => v.trim())
+		.filter(Boolean);
+	const key = flagBool(flags["no-key"])
+		? false
+		: capabilities?.length || flagStr(flags["key-name"])
+			? compact({
+					name: flagStr(flags["key-name"]),
+					capabilities: capabilities?.length ? capabilities : undefined,
+				})
+			: true;
+
+	const body = compact({
+		domain,
+		name: flagStr(flags.name),
+		is_test: flagBool(flags.test) ? true : undefined,
+		key,
+		onboard: flagBool(flags.onboard) ? onboardOptionsFromFlags(flags) : undefined,
+	});
+
+	ok(ctx, `Provisioning ${domain}…`);
+	const result = await staffPost(ctx, "/api/superadmin/orgs", body);
+
+	if (!watch) {
+		printResult(io, flags, result, formatCreateOrg);
+		return 0;
+	}
+
+	// --watch: everything spins up from this one command. The org key exists ONLY in this
+	// process's memory for the rest of the run — never written to disk, never printed again
+	// after the summary above — and is used to build a second, throwaway MCP client that
+	// polls the SAME loop `phantom-onboard domain --watch` uses. `ok(...)` here (not
+	// printResult) so the key/warning above are still shown before the poll starts.
+	ok(ctx, formatCreateOrg(result));
+	if (!result.job_id) {
+		ok(ctx, "No job to watch (the org call didn't start one — see the error above, if any).");
+		return 0;
+	}
+	if (!result.api_key?.plain_key) {
+		throw new CliError("No org key came back to watch with (did --no-key sneak in?).");
+	}
+	const orgClient = new LetterstoryClient({
+		url: client.url,
+		key: result.api_key.plain_key,
+		fetchImpl: client.fetch,
+		verbose: client.verbose,
+		verboseLog: client.verboseLog,
+		bin: ctx.bin,
+	});
+	return watchDomainJob({ ...ctx, client: orgClient }, result.job_id);
+}
+
+export async function cmdAdmin(ctx) {
+	const sub = ctx.positionals[0];
+	if (sub === "create-org") return cmdAdminCreateOrg({ ...ctx, positionals: ctx.positionals.slice(1) });
+	throw new CliError("Usage: admin create-org --domain <bare-domain> [--onboard] … (see --help)");
+}

package/lib/commands/onboard.mjs

@@ -18,6 +18,14 @@
 // posts are written by background jobs (20-40min each); they're reported as job ids and
 // this command does not block on them — poll with `phantom-job status <job-id>`.
 
+// `onboard domain` is the ONE-SHOT parent: a bare company domain in (the org's registered
+// domain, from the API key), a fully-configured organization out — the main blog onboarded
+// (the `collection` recipe), org visuals inferred from the site, the main blog's Enhance
+// flow configured, a phantom provisioned + configured + seeded, Seers in suggest mode —
+// driven by `onboard_domain` + `get_domain_onboard_status`. `--watch` polls to completion;
+// `--attach <job-id>` watches a job started elsewhere (e.g. `admin create-org --onboard`).
+// To create the ORG itself headlessly, use `admin create-org` with a staff key first.
+
 // `onboard collection` is the CLIENT-blog sibling: the same recipe minus provisioning,
 // driven by `onboard_collection` + `get_collection_onboard_status`. The org (and its
 // domain) comes from the API key — the job reads the org's registered domain, imports
@@ -216,12 +224,157 @@ async function cmdOnboardSyncSitemap(ctx) {
 	return 0;
 }
 
+const SEER_MODES = ["suggest", "skip"];
+const CMS_PROVIDERS = ["webflow", "framer", "sanity", "contentful"];
+
+// Final readback of a domain-onboarding job — the counts the engine PERSISTED.
+export function formatDomainStatus(s) {
+	const r = s.result ?? {};
+	const lines = [
+		`Domain onboarding ${s.status} at stage "${s.stage}" (${s.domain})`,
+		`  org:            ${s.org_id}`,
+		`  main blog:      ${s.collection_id ?? "(pending)"}${s.collection_job_id ? ` (job ${s.collection_job_id})` : ""}`,
+		`  phantom job:    ${s.phantom_job_id ?? "(none)"}`,
+	];
+	if (s.error) lines.push(`  error:          ${s.error}`);
+	if (r.collection) {
+		lines.push(
+			`  posts imported: ${r.collection.posts_imported ?? 0} · content areas ${r.collection.coverage_areas ?? 0} · pillars ${r.collection.pillars ?? 0} · headlines ${r.collection.headlines_suggested ?? 0}`
+		);
+	}
+	if (r.visuals) {
+		lines.push(
+			`  org visuals:    ${r.visuals.skipped_reason ? `skipped (${r.visuals.skipped_reason})` : `${r.visuals.created} created, ${r.visuals.reused} reused; bound ${(r.visuals.bound ?? []).join("/") || "nothing"}`}`
+		);
+	}
+	if (r.enhance)
+		lines.push(`  enhance flow:   ${r.enhance.action}${r.enhance.flow_id ? ` (${r.enhance.flow_id})` : ""}`);
+	if (r.phantom) {
+		lines.push(
+			`  phantom:        ${r.phantom.site_url ?? r.phantom.deployment_id ?? "(no site)"} — ${r.phantom.status}, seeds ${r.phantom.seeds_published}/${r.phantom.seeds_total} published`
+		);
+	}
+	if (r.seers) {
+		lines.push(
+			`  seers:          ${r.seers.skipped_reason ? `skipped (${r.seers.skipped_reason})` : `${r.seers.created} created (suggest mode), ${r.seers.reused} reused`}`
+		);
+	}
+	if (r.probes) lines.push(`  GEO probes:     ${r.probes.runs} run(s), ${r.probes.responses} answers`);
+	for (const w of r.warnings ?? []) lines.push(`  warning:        ${w}`);
+	return lines.join("\n");
+}
+
+// Exported so `admin create-org --onboard --watch` can drive the SAME poll loop against a
+// freshly-minted org key, instead of duplicating it — see admin.mjs.
+export async function watchDomainJob(ctx, jobId) {
+	const { client, flags } = ctx;
+	let printed = 0;
+	let lastStage = null;
+	const final = await pollUntil(
+		ctx.io,
+		async () => {
+			const s = await client.callTool("get_domain_onboard_status", { job_id: jobId });
+			if (s.stage !== lastStage) {
+				ok(ctx, `  … ${s.stage}`);
+				lastStage = s.stage;
+			}
+			const review = Array.isArray(s.review) ? s.review : [];
+			for (; printed < review.length; printed++) ok(ctx, `    ${review[printed]}`);
+			if (s.status === "failed") {
+				throw new CliError(
+					`Domain onboarding failed at stage "${s.stage}": ${s.error ?? "unknown error"} (the main blog job, if it ran, keeps what it imported).`
+				);
+			}
+			return { done: s.status !== "running", value: s };
+		},
+		// The readiness stage waits for seed posts (default up to 2h); the watch window
+		// covers the default and a little slack.
+		{ label: "domain onboarding to finish", timeoutMs: 150 * 60 * 1000, intervalMs: 10000 }
+	);
+	printResult(ctx.io, flags, final, formatDomainStatus);
+	return 0;
+}
+
+// `onboard domain` — the one-shot parent. The org and its domain come from the API key.
+async function cmdOnboardDomain(ctx) {
+	const { client, flags } = ctx;
+
+	// Attach to a job started elsewhere (admin create-org --onboard prints one).
+	const attach = flagStr(flags.attach);
+	if (attach) {
+		if (!flagBool(flags.watch)) {
+			const s = await client.callTool("get_domain_onboard_status", { job_id: attach });
+			printResult(ctx.io, flags, s, formatDomainStatus);
+			return 0;
+		}
+		return watchDomainJob(ctx, attach);
+	}
+	if (flagBool(flags.status)) {
+		const s = await client.callTool("get_domain_onboard_status", {});
+		printResult(ctx.io, flags, s, formatDomainStatus);
+		return 0;
+	}
+
+	const seers = flagStr(flags.seers);
+	if (seers !== undefined && !SEER_MODES.includes(seers)) {
+		throw new CliError(`--seers must be one of: ${SEER_MODES.join(", ")}`);
+	}
+	const cms = flagStr(flags.cms);
+	if (cms !== undefined && !CMS_PROVIDERS.includes(cms)) {
+		throw new CliError(`--cms must be one of: ${CMS_PROVIDERS.join(", ")}`);
+	}
+	const posts = flagNum(flags.posts);
+	const phantom = compact({
+		enabled: flagBool(flags["no-phantom"]) ? false : undefined,
+		posts_to_seed: posts,
+		name: flagStr(flags["phantom-name"]),
+		site_domain: flagStr(flags["site-domain"]),
+		domain_mode: flagStr(flags["domain-mode"]),
+	});
+	const args = compact({
+		direction: flagStr(flags.about) ?? flagStr(flags.direction),
+		sitemap_url: flagStr(flags.sitemap),
+		cms_provider: cms,
+		collection_name: flagStr(flags.name),
+		phantom: Object.keys(phantom).length ? phantom : undefined,
+		seers,
+		visuals: flagBool(flags["no-visuals"]) ? false : undefined,
+		enhance: flagBool(flags["no-enhance"]) ? false : undefined,
+		is_test: flagBool(flags.test) ? true : undefined,
+		readiness_minutes: flagNum(flags["readiness-minutes"]),
+	});
+
+	ok(ctx, "Starting domain onboarding…");
+	const started = await client.callTool("onboard_domain", args);
+	if (!started.job_id) throw new CliError("onboard_domain did not return a job id.");
+	ok(ctx, `Job ${started.job_id} running for ${started.domain}.`);
+
+	if (!flagBool(flags.watch)) {
+		printResult(ctx.io, flags, started, (s) =>
+			[
+				`Domain onboarding started (stage "${s.stage}").`,
+				`  job:    ${s.job_id}`,
+				`  org:    ${s.org_id}`,
+				`  domain: ${s.domain}`,
+				`Watch it with:  ${ctx.bin} ${ctx.positionals.length ? "phantom-onboard" : "onboard"} domain --attach ${s.job_id} --watch, or poll:`,
+				`  ${ctx.bin} call get_domain_onboard_status --args '{"job_id":"${s.job_id}"}'`,
+			].join("\n")
+		);
+		return 0;
+	}
+	return watchDomainJob(ctx, started.job_id);
+}
+
 export async function cmdOnboard(ctx) {
 	const { client, flags, io } = ctx;
 	// `onboard collection …` — the client-blog variant (no <domain>; org from the key).
 	if (ctx.positionals[0] === "collection") {
 		return cmdOnboardCollection({ ...ctx, positionals: ctx.positionals.slice(1) });
 	}
+	// `onboard domain …` — the one-shot parent (org + domain from the key).
+	if (ctx.positionals[0] === "domain") {
+		return cmdOnboardDomain({ ...ctx, positionals: ctx.positionals.slice(1) });
+	}
 	// `onboard sync-sitemap --collection <uuid>` — refresh an already-onboarded blog.
 	if (ctx.positionals[0] === "sync-sitemap") {
 		return cmdOnboardSyncSitemap({ ...ctx, positionals: ctx.positionals.slice(1) });

package/lib/commands.mjs

@@ -25,3 +25,4 @@ export * from "./commands/onboard.mjs";
 export * from "./commands/seers.mjs";
 export * from "./commands/shredder.mjs";
 export * from "./commands/landings.mjs";
+export * from "./commands/admin.mjs";

package/package.json

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