@letterstory/cli 0.9.0 → 0.11.0

package/lib/cli.mjs

@@ -40,7 +40,7 @@ import {
 } from "./commands.mjs";
 
 // Keep in sync with cli/package.json.
-export const VERSION = "0.9.0";
+export const VERSION = "0.11.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.
@@ -268,6 +268,27 @@ Phantom onboarding recipe (domain -> live phantom blog with first posts):
                                                        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).
+  ${bin === "phantom" ? "onboard" : "phantom-onboard"} sync-sitemap --collection <uuid>
+                                                       Re-check an already-onboarded blog's sitemap
+                                                       right now instead of waiting for its cadence
+                                                       (default every 14 days). Skips pages whose
+                                                       <lastmod> hasn't moved, imports new posts,
+                                                       refreshes changed ones. Only for collections
+                                                       with no CMS connected — once one is, use the
+                                                       CMS pull/reconcile path instead.
+                                                       --watch polls to completion, printing each
+                                                       review note as it lands.
+
 Seers (event-driven signals -> drafts):
   seers list                                           List seers with recent activity
   seers get <seer-id>                                  One seer's full config + poll state

package/lib/commands/onboard.mjs

@@ -18,6 +18,13 @@
 // 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";
 
@@ -91,8 +98,132 @@ function overridesFromFlags(flags) {
 	});
 }
 
+// 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;
+}
+
+// `onboard sync-sitemap --collection <uuid>` — the periodic-refresh sibling: re-check a
+// collection's sitemap right now instead of waiting for its cadence
+// (collections.sitemap_sync_cadence_days). One-shot, no polling — the underlying work is
+// bounded per run, so it returns synchronously.
+async function cmdOnboardSyncSitemap(ctx) {
+	const { client, flags } = ctx;
+	const collectionId = flagStr(flags.collection);
+	if (!collectionId) {
+		throw new CliError("onboard sync-sitemap requires --collection <uuid>.");
+	}
+
+	ok(ctx, "Re-checking the sitemap…");
+	const result = await client.callTool("sync_collection_sitemap", { collection_id: collectionId });
+
+	printResult(ctx.io, flags, result, (r) =>
+		[
+			`Sitemap sync complete — ${r.checked} post${r.checked === 1 ? "" : "s"} checked.`,
+			`  created:   ${r.created}`,
+			`  updated:   ${r.updated}`,
+			`  unchanged: ${r.unchanged} (skipped — <lastmod> hadn't moved)`,
+			r.skipped ? `  skipped:   ${r.skipped} (nothing readable)` : null,
+			r.failed
+				? `  failed:    ${r.failed}${r.failure_reasons?.length ? ` (${r.failure_reasons.join("; ")})` : ""}`
+				: null,
+			r.truncated ? `  capped this run — rerun (or wait for the cadence) to catch up the rest.` : null,
+		]
+			.filter(Boolean)
+			.join("\n")
+	);
+	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) });
+	}
+	// `onboard sync-sitemap --collection <uuid>` — refresh an already-onboarded blog.
+	if (ctx.positionals[0] === "sync-sitemap") {
+		return cmdOnboardSyncSitemap({ ...ctx, positionals: ctx.positionals.slice(1) });
+	}
 	const domain = requirePositional(ctx.positionals, 0, "domain");
 	const overrides = overridesFromFlags(flags);
 

package/package.json

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