@letterstory/cli 0.8.0 → 0.10.0

package/lib/cli.mjs

@@ -40,7 +40,7 @@ import {
 } from "./commands.mjs";
 
 // Keep in sync with cli/package.json.
-export const VERSION = "0.8.0";
+export const VERSION = "0.10.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.
@@ -254,12 +254,32 @@ Phantom orchestrator:
   phantom-job status <job-id>                          Check a job's stage
 
 Phantom onboarding recipe (domain -> live phantom blog with first posts):
-  ${bin === "phantom" ? "onboard" : "phantom-onboard"} <domain> [--name X] [--posts N] [--cadence N]
-          [--cover editorial_image|full_ai|line_art] [--theme T] [--accept] [--dry-run]
+  ${bin === "phantom" ? "onboard" : "phantom-onboard"} <domain> [--about "the beat"] [--name X]
+          [--posts N] [--cadence N] [--cover editorial_image|full_ai|line_art] [--theme T]
+          [--real] [--domain host] [--domain-mode subdomain|buy_now|connect_later]
+          [--accept] [--dry-run]
                                                        Plan (read-only) then, with --accept
                                                        or an override flag, provision + configure
-                                                       + seed. --name is committed at create (it
-                                                       seeds the URL); pass it before applying.
+                                                       + seed. --about becomes the planner's
+                                                       steering prompt, so it shapes the topic map
+                                                       and every post — use it for a client's
+                                                       second phantom. --name is committed at
+                                                       create (it seeds the URL); pass it before
+                                                       applying. --domain-mode buy_now SPENDS
+                                                       money (2/org, $30 cap).
+
+Collection onboarding (your OWN blog, on your org's domain — no provisioning):
+  ${bin === "phantom" ? "onboard" : "phantom-onboard"} collection [--collection <uuid>] [--name "<collection name>"]
+          [--about "the direction"] [--sitemap <url>] [--watch]
+                                                       Import the existing blog from its sitemap
+                                                       (auto-discovered from the org's domain unless
+                                                       --sitemap pins one), derive content areas +
+                                                       series, build the topic map, bind SEO demand,
+                                                       and stock Headlines & Queue. Omit --collection
+                                                       to create a fresh one (--name, default Blog).
+                                                       The Planner stays OFF (manual approval).
+                                                       --watch polls to completion, printing each
+                                                       review note as it lands.
 
 Seers (event-driven signals -> drafts):
   seers list                                           List seers with recent activity

package/lib/commands/onboard.mjs

@@ -6,15 +6,30 @@
 //     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).
 //
+// `--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
+// the name. Use it when the client already has a phantom and this one needs a different beat.
+//
+// `--domain <host>` records a custom domain; nothing is bought unless you also pass
+// `--domain-mode buy_now`, which SPENDS money against a 2-per-org, $30-per-domain cap.
+//
 // IMPORTANT: the masthead name is committed when the site is created (it seeds the URL),
 // so to use a name other than the inferred one, pass --name BEFORE applying. The first
 // 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 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
+// the existing blog from its sitemap, derives content areas + series, builds the topic
+// map, binds SEO demand, and stocks the Headlines tab. `--watch` polls to completion,
+// printing each review note as the job writes it.
+
 import { CliError } from "../client.mjs";
 import { flagStr, flagNum, flagBool, requirePositional, printResult, compact, ok, pollUntil } from "./shared.mjs";
 
 const COVER_STYLES = ["editorial_image", "full_ai", "line_art"];
+const DOMAIN_MODES = ["subdomain", "buy_now", "connect_later"];
 
 function formatPlan(plan) {
 	const lines = [
@@ -23,6 +38,10 @@ function formatPlan(plan) {
 		`  description:   ${plan.description}`,
 		`  defaults:      ${plan.defaults.cadence_per_week}/week · ${plan.defaults.cover_canvas} · seed ${plan.defaults.posts_to_seed}`,
 	];
+	if (plan.direction) lines.push(`  direction:     ${plan.direction}`);
+	if (plan.domain_plan?.site_domain) {
+		lines.push(`  domain:        ${plan.domain_plan.site_domain} (${plan.domain_plan.mode})`);
+	}
 	if (plan.strategy) {
 		lines.push(`  topics:        ${(plan.strategy.priority_topics ?? []).slice(0, 5).join(", ") || "(none)"}`);
 	} else {
@@ -54,17 +73,121 @@ function overridesFromFlags(flags) {
 	if (cover !== undefined && !COVER_STYLES.includes(cover)) {
 		throw new CliError(`--cover must be one of: ${COVER_STYLES.join(", ")}`);
 	}
+	const domainMode = flagStr(flags["domain-mode"]);
+	if (domainMode !== undefined && !DOMAIN_MODES.includes(domainMode)) {
+		throw new CliError(`--domain-mode must be one of: ${DOMAIN_MODES.join(", ")}`);
+	}
+	const siteDomain = flagStr(flags.domain);
+	// 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 (domainMode && domainMode !== "subdomain" && !siteDomain) {
+		throw new CliError(`--domain-mode ${domainMode} needs --domain <bare-domain>`);
+	}
 	return compact({
 		name: flagStr(flags.name),
 		cadence_per_week: flagNum(flags.cadence),
 		cover_canvas: cover,
 		theme: flagStr(flags.theme),
 		posts_to_seed: flagNum(flags.posts),
+		// The highest-leverage override: it becomes the planner's steering prompt, so it
+		// shapes the topic map and every post, not just the masthead.
+		direction: flagStr(flags.about) ?? flagStr(flags.direction),
+		site_domain: siteDomain,
+		domain_mode: domainMode,
+		is_test: flagBool(flags["real"]) ? false : undefined,
 	});
 }
 
+// Final readback of a collection-onboarding job — the counts the engine PERSISTED.
+function formatCollectionStatus(s) {
+	const r = s.result ?? {};
+	const lines = [
+		`Onboarding ${s.status} at stage "${s.stage}"`,
+		`  collection:  ${s.collection_id}`,
+		`  blog found:  ${s.has_blog === null ? "(not yet determined)" : s.has_blog ? (s.sitemap_url ?? "yes") : "no — onboarded from positioning"}`,
+	];
+	if (s.error) lines.push(`  error:       ${s.error}`);
+	if (s.status === "done") {
+		lines.push(
+			`  posts imported:      ${r.posts_imported ?? 0}`,
+			`  content areas (org): ${r.coverage_areas ?? 0}`,
+			`  pillars:             ${r.pillars ?? 0}`,
+			`  series:              ${r.series ?? 0}`,
+			`  open topics:         ${r.spokes_open ?? 0} (${r.spokes_seo_bound ?? 0} SEO-bound)`,
+			`  headlines suggested: ${r.headlines_suggested ?? 0}`,
+			`  Review them in Headlines & Queue — the Planner is configured but OFF (manual approval).`
+		);
+	}
+	return lines.join("\n");
+}
+
+// `onboard collection` — onboard the caller's own (client-brand) blog. The org and its
+// domain come from the API key, so there's no <domain> positional; pin the sitemap with
+// --sitemap when auto-discovery from the org's domain won't find it.
+async function cmdOnboardCollection(ctx) {
+	const { client, flags } = ctx;
+	// The phantom variant's --domain means "custom site domain to buy/connect"; here the
+	// site is the org's own, read from the API key. Refuse rather than silently ignore.
+	if (flagStr(flags.domain) !== undefined) {
+		throw new CliError(
+			"onboard collection uses your organization's registered domain (from the API key). " +
+				"To pin where posts import from, pass --sitemap <https://…/sitemap.xml> instead."
+		);
+	}
+
+	const args = compact({
+		collection_id: flagStr(flags.collection),
+		collection_name: flagStr(flags.name),
+		direction: flagStr(flags.about) ?? flagStr(flags.direction),
+		sitemap_url: flagStr(flags.sitemap),
+	});
+
+	ok(ctx, "Starting collection onboarding…");
+	const started = await client.callTool("onboard_collection", args);
+	if (!started.job_id) throw new CliError("onboard_collection did not return a job id.");
+	ok(ctx, `Job ${started.job_id} running for collection ${started.collection_id}.`);
+
+	if (!flagBool(flags.watch)) {
+		printResult(ctx.io, flags, started, (s) =>
+			[
+				`Onboarding started (stage "${s.stage}").`,
+				`  job:        ${s.job_id}`,
+				`  collection: ${s.collection_id}`,
+				`Watch it with:  --watch (re-running is safe), or poll:`,
+				`  ${ctx.bin} call get_collection_onboard_status --args '{"job_id":"${s.job_id}"}'`,
+			].join("\n")
+		);
+		return 0;
+	}
+
+	// Watch: poll to a terminal state, printing each review note as the job writes it.
+	let printed = 0;
+	const final = await pollUntil(
+		ctx.io,
+		async () => {
+			const s = await client.callTool("get_collection_onboard_status", { job_id: started.job_id });
+			const review = Array.isArray(s.review) ? s.review : [];
+			for (; printed < review.length; printed++) ok(ctx, `  … ${review[printed]}`);
+			if (s.status === "failed") {
+				throw new CliError(
+					`Onboarding failed at stage "${s.stage}": ${s.error ?? "unknown error"} (re-running the command retries — the job is idempotent).`
+				);
+			}
+			return { done: s.status !== "running", value: s };
+		},
+		{ label: "collection onboarding to finish", timeoutMs: 30 * 60 * 1000, intervalMs: 5000 }
+	);
+
+	printResult(ctx.io, flags, final, formatCollectionStatus);
+	return 0;
+}
+
 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) });
+	}
 	const domain = requirePositional(ctx.positionals, 0, "domain");
 	const overrides = overridesFromFlags(flags);
 
@@ -84,7 +207,7 @@ export async function cmdOnboard(ctx) {
 	if (!flagBool(flags.accept) && !overrideGiven) {
 		ok(
 			ctx,
-			"Re-run with --accept to apply, or pass --name/--cadence/--cover/--posts/--theme to adjust. " +
+			"Re-run with --accept to apply, or pass --about/--name/--cadence/--cover/--posts/--theme/--domain to adjust. " +
 				"Note: --name is committed at create (it seeds the URL)."
 		);
 		return 0;

package/package.json

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