@letterstory/cli 0.148.3 → 0.149.0

package/lib/cli.mjs

@@ -66,7 +66,7 @@ import {
 
 // Matches cli/package.json; publish-cli.yml rewrites both to the published version.
 // Matches cli/package.json; publish-cli.yml rewrites both to the published version.
-export const VERSION = "0.148.3";
+export const VERSION = "0.149.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. Every `type: "bool"` flag (and its
@@ -134,6 +134,12 @@ export const BOOLEAN_FLAGS = new Set([
 	"verbose",
 	"no-color",
 	"dry-run",
+	// admin demo list --enrollable, show --moves, set --enroll|--unenroll
+	"enrollable",
+	"moves",
+	"enroll",
+	"unenroll",
+	"clean-slate",
 	// admin recipes list --enabled-only, save --enable|--disable, import --retire-missing
 	"enabled-only",
 	"enable",
@@ -850,6 +856,19 @@ Admin (STAFF key — --staff-key / LETTERSTORY_STAFF_API_KEY; acts before an org
                      [--primitives a,b|none] [--goals a,b|none] [--company-types a,b|none] [--enable|--disable] [--position n]
                                                        Create one (no id) or change one. Needs recipes:write.
   admin recipes delete <id> --yes                      Delete for good (save --disable retires and keeps it).
+  admin demo guide                                     How to run a demo, step by step, and what every knob and
+                                                       seed shows on screen. Read it first.
+  admin demo list [--enrollable] | show <org-id> [--moves]
+                                                       Demo orgs (/superadmin/demo): what each shows beside
+                                                       what it really has. Needs demo:read.
+  admin demo set <org-id> [--enroll] [--phantom parked] [--search-console hidden] [--inject <key>]... [--save-as n]
+                                                       Set what a demo org shows (merged); 'shown' puts a thing
+                                                       back. --file takes a scenario as JSON. Needs demo:write.
+  admin demo reset <org-id> <scenario> [--clean-slate] [--close-prs since_applied|all_open|none]
+                                                       Undo the last take (its PRs closed, builds archived), then
+                                                       show a scenario: real, fresh_geo, fresh_seo, after_approve
+                                                       or a saved one. --clean-slate closes every open PR and
+                                                       archives every build.
   admin suggestion-recipes list|export [--out f.json]|import <f.json> [--dry-run] [--retire-missing]|stats
                                                        Build's suggestion recipes: plain-language ways
                                                        Letterpress finds what a site should build (look at,
@@ -952,6 +971,8 @@ Admin (STAFF key — --staff-key / LETTERSTORY_STAFF_API_KEY; acts before an org
           | payments [--org <org-id>] [--open] | payments retry <lago-invoice-id> | payments run [--dry]
           | signups [--status open|card_saved|provisioned|paid|abandoned]
           | cap <org-id> <dollars|off> [--why "…"] | cancel <org-id> --why "…" --yes
+          | move <org-id> --plan starter|growth|scale [--ratio N [--why "…"]] [--reason "…"] [--stripe-subscription sub_…] [--dry]
+          | changes [--org <org-id>] | changes cancel <org-id>
                                                        Usage billing on Lago: the plan catalog, an org's
                                                        plan and gifted ratio, Lago's tokens against ours,
                                                        forwarding usage now, failed payments and the

package/lib/commands/admin.mjs

@@ -19,6 +19,7 @@
 //   admin brand-detection <org-id>                                                   (fleet:read)
 //   admin brand-detection <org-id> [--term t]... [--exact t]... [--exclude p]... [--note "…"] | --clear [--note "…"]   (fleet:instrument)
 //   admin recipes list|show|vocab|export|import|save|delete …                        (recipes:read / recipes:write)
+//   admin demo guide|list|show|set|reset …                                                 (demo:read / demo:write)
 //   admin models runs|run|star|unstar|scoreboard|requests|request|sampling …       (models:read / models:write)
 //   admin replays [--org <id>] [--target <id>] [--status …] [--limit n]                (fleet:read)
 //   admin replay --org <id> [<response-id> | --target <id>] [--surface …]           (fleet:replay)
@@ -5214,7 +5215,11 @@ const LAGO_USAGE = `Usage: admin billing lago <command>
   payments run [--dry]                   one pass of the failed-payment loop now (--dry: report only)
   signups [--status open|card_saved|provisioned|paid|abandoned]   new paying orgs on their way onto Lago
   cap <org-id> <dollars|off> [--why "…"]  set an account's monthly spend cap on overage (off: no cap)
-  cancel <org-id> --why "…" --yes          end an account's Lago plan now and refund its first invoice`;
+  cancel <org-id> --why "…" --yes          end an account's Lago plan now and refund its first invoice
+  move <org-id> --plan starter [--ratio 4] [--why "…" above 4x] [--reason "…"] [--complimentary 20000] [--review 2027-05-01] [--stripe-subscription sub_…] [--dry]
+                                         move an existing customer from Stripe to Lago at their renewal
+  changes [--org <org-id>]               term changes waiting to take effect (moves, cheaper plans, new ratios)
+  changes cancel <org-id>                take back an org's scheduled change before it takes effect`;
 
 /** admin billing lago … — staff operations on Lago (docs/billing/lago-integration.md). */
 async function cmdAdminBilling(ctx) {
@@ -5258,7 +5263,9 @@ async function cmdAdminBilling(ctx) {
 			);
 			ok(
 				ctx,
-				`${result.action === "created" ? "On Lago" : "Already on Lago"}: ${result.subscriptionId}, ${result.includedTokens} tokens included, overage $${result.overageUsdPerToken} a token, from ${result.startsAt}.`
+				result.action === "scheduled"
+					? `Scheduled: from ${result.effectiveAt}, ${result.includedTokens} tokens included, overage $${result.overageUsdPerToken} a token (Lago bills today's terms until then).`
+					: `${result.action === "created" ? "On Lago" : "Already on Lago"}: ${result.subscriptionId}, ${result.includedTokens} tokens included, overage $${result.overageUsdPerToken} a token, from ${result.startsAt}.`
 			);
 			printResult(io, flags, result);
 			return 0;
@@ -5359,6 +5366,55 @@ async function cmdAdminBilling(ctx) {
 			);
 			return 0;
 		}
+		case "move": {
+			const orgId = requirePositional(positionals, 2, "org-id");
+			const plan = flagStr(flags.plan);
+			if (!plan) throw new CliError(LAGO_USAGE);
+			const result = await staffPost(
+				ctx,
+				`${LAGO}/move`,
+				compact({
+					orgId,
+					planCode: plan,
+					ratio: flagNum(flags.ratio),
+					exceptionReason: flagStr(flags.why),
+					reason: flagStr(flags.reason),
+					complimentaryTokens: flagNum(flags.complimentary),
+					reviewAt: flagStr(flags.review),
+					stripeSubscriptionId: flagStr(flags["stripe-subscription"]),
+					dryRun: flags.dry ? true : undefined,
+				})
+			);
+			const p = result.plan;
+			ok(
+				ctx,
+				`${result.dryRun ? "Would move" : "Moving"} ${p.orgId} from Stripe ${p.from.stripeSubscriptionId} (${p.from.product ?? "subscription"}) to Lago ${p.to.plan} at its renewal ${p.from.renewsAt}: Stripe stops then, Lago charges $${(p.to.amountCents / 100).toFixed(2)} then (${p.to.includedTokens} tokens included, overage $${p.to.overageUsdPerToken} a token).`
+			);
+			printResult(io, flags, result);
+			return 0;
+		}
+		case "changes": {
+			if (positionals[2] === "cancel") {
+				const orgId = requirePositional(positionals, 3, "org-id");
+				const result = await staffRequest(ctx, "DELETE", `${LAGO}/changes`, { orgId });
+				ok(ctx, `Taken back: the ${result.canceled.kind} scheduled for ${result.canceled.effective_at}.`);
+				printResult(io, flags, result);
+				return 0;
+			}
+			const params = new URLSearchParams(compact({ orgId: flagStr(flags.org) }));
+			const result = await staffRequest(ctx, "GET", `${LAGO}/changes${params.size ? `?${params}` : ""}`);
+			printResult(io, flags, result, (r) =>
+				r.changes.length
+					? r.changes
+							.map(
+								(c) =>
+									`${c.effective_at}  ${c.kind.padEnd(9)} ${c.organizations?.name ?? c.org_id} → ${c.plan_code} ${c.ratio}x (by ${c.requested_by}${c.last_error ? `; waiting: ${c.last_error}` : ""})`
+							)
+							.join("\n")
+					: "Nothing scheduled."
+			);
+			return 0;
+		}
 		case "cap": {
 			const orgId = positionals[2];
 			const value = positionals[3];
@@ -5385,6 +5441,134 @@ async function cmdAdminBilling(ctx) {
 	}
 }
 
+// `admin demo` — demo control (docs/architecture/demo-control.md): what each demo org shows,
+// set, rehearsed and reset. The staff routes behind /superadmin/demo, the same functions and
+// schema as list_demo_orgs / get_demo_state / set_demo_state / reset_demo_state.
+const DEMO = "/api/superadmin/demo";
+const DEMO_ITEM_FLAGS = [
+	"phantom",
+	"main-blog",
+	"visitors",
+	"probes",
+	"cms",
+	"publish-target",
+	"search-console",
+	"github",
+	"domain",
+	"setup",
+];
+const DEMO_USAGE =
+	"Usage: admin demo guide | list [--enrollable] | show <org-id> [--moves] | set <org-id> [--enroll] [--unenroll] [--file <state.json>] [--phantom parked|shown] [--main-blog …] [--visitors …] [--probes not_run|shown] [--cms hidden|shown] [--publish-target …] [--search-console …] [--github …] [--domain …] [--setup fresh|finished] [--domain-cap n] [--inject <key>]... [--hide <key>]... [--save-as <name>] | reset <org-id> <scenario> [--clean-slate] [--close-prs since_applied|all_open|none]";
+
+async function cmdAdminDemo(ctx) {
+	const { flags, positionals, io } = ctx;
+	const sub = positionals[0];
+	switch (sub) {
+		case "guide": {
+			const guide = await staffRequest(ctx, "GET", `${DEMO}/guide`);
+			printResult(io, flags, guide, (g) =>
+				[
+					"How to run a demo",
+					...g.steps.map(
+						(s) => `\n${s.title}\n  ${s.do}\n  page: ${s.page}\n  cli:  ${s.cli}\n  -> ${s.result}`
+					),
+					"\nWhat each knob and seed shows",
+					...g.entries.map(
+						(e) =>
+							`\n${e.label} (${e.values})\n  ${e.what}\n${e.shows_as.map((x) => `  · ${x}`).join("\n")}${
+								e.on_camera ? `\n  on camera: ${e.on_camera}` : ""
+							}${e.mind.length ? `\n${e.mind.map((m) => `  ! ${m}`).join("\n")}` : ""}`
+					),
+				].join("\n")
+			);
+			return 0;
+		}
+		case "list": {
+			const result = await staffRequest(
+				ctx,
+				"GET",
+				`${DEMO}${flagBool(flags.enrollable) ? "?candidates=1" : ""}`
+			);
+			printResult(io, flags, result, (r) =>
+				r.orgs.length
+					? r.orgs
+							.map(
+								(o) =>
+									`${o.enrolled ? "demo" : "test"}  ${o.name}  ${o.domain ?? "—"}  ${o.scenario ?? ""}${
+										o.differs?.length ? `  [${o.differs.join(", ")}]` : ""
+									}  ${o.org_id}`
+							)
+							.join("\n")
+					: "No demo orgs yet."
+			);
+			return 0;
+		}
+		case "show": {
+			const orgId = requirePositional(positionals, 1, "org-id");
+			const result = await staffRequest(
+				ctx,
+				"GET",
+				`${DEMO}/${encodeURIComponent(orgId)}${flagBool(flags.moves) ? "?moves=1" : ""}`
+			);
+			printResult(io, flags, result, (r) =>
+				[
+					`${r.org.name}  ${r.org.domain ?? "no domain"}  scenario ${r.state.scenario ?? "—"}`,
+					...r.knobs.map((k) => `  ${k.item.padEnd(16)} real: ${k.real}  ·  shown: ${k.shown}  (${k.how})`),
+					`  observations open: ${r.observations.open.map((o) => `${o.key}${o.injected ? " (demo)" : ""}`).join(", ") || "none"}`,
+					`  answers: ${r.answers.map((q) => `${q.named}/${q.answers} ${q.text}`).join("; ") || "never probed"}`,
+				].join("\n")
+			);
+			return 0;
+		}
+		case "set": {
+			const orgId = requirePositional(positionals, 1, "org-id");
+			const file = flagStr(flags.file);
+			const state = file ? JSON.parse(readFileSync(file, "utf8")) : {};
+			for (const flag of DEMO_ITEM_FLAGS) {
+				const value = flagStr(flags[flag]);
+				if (value) state[flag.replace(/-/g, "_")] = value;
+			}
+			const cap = flagNum(flags["domain-cap"]);
+			if (cap !== undefined && cap !== null) state.domain_cap = cap;
+			const inject = flagList(flags.inject);
+			const hide = flagList(flags.hide);
+			if (inject.length || hide.length)
+				state.observations = {
+					...state.observations,
+					...(inject.length ? { inject } : {}),
+					...(hide.length ? { hide } : {}),
+				};
+			const body = compact({
+				...(Object.keys(state).length ? { state } : {}),
+				enroll: flagBool(flags.enroll) || undefined,
+				unenroll: flagBool(flags.unenroll) || undefined,
+				save_as: flagStr(flags["save-as"]),
+			});
+			if (!Object.keys(body).length) throw new CliError(DEMO_USAGE);
+			const result = await staffRequest(ctx, "PATCH", `${DEMO}/${encodeURIComponent(orgId)}`, body);
+			printResult(io, flags, result, (r) => r.notes.join("\n") || "No change.");
+			return 0;
+		}
+		case "reset": {
+			const orgId = requirePositional(positionals, 1, "org-id");
+			const scenario = requirePositional(positionals, 2, "scenario");
+			const result = await staffPost(
+				ctx,
+				`${DEMO}/${encodeURIComponent(orgId)}/reset`,
+				compact({
+					scenario,
+					close_prs: flagStr(flags["close-prs"]),
+					clean_slate: flagBool(flags["clean-slate"]) || undefined,
+				})
+			);
+			printResult(io, flags, result, (r) => r.notes.join("\n"));
+			return 0;
+		}
+		default:
+			throw new CliError(DEMO_USAGE);
+	}
+}
+
 export async function cmdAdmin(ctx) {
 	const sub = ctx.positionals[0];
 	if (sub === "replays" || sub === "replay")
@@ -5405,10 +5589,11 @@ export async function cmdAdmin(ctx) {
 	if (sub === "brand-detection") return cmdAdminBrandDetection({ ...ctx, positionals: ctx.positionals.slice(1) });
 	if (sub === "republish") return cmdAdminRepublish({ ...ctx, positionals: ctx.positionals.slice(1) });
 	if (sub === "recipes") return cmdAdminRecipes({ ...ctx, positionals: ctx.positionals.slice(1) });
+	if (sub === "demo") return cmdAdminDemo({ ...ctx, positionals: ctx.positionals.slice(1) });
 	if (sub === "suggestion-recipes")
 		return cmdAdminSuggestionRecipes({ ...ctx, positionals: ctx.positionals.slice(1) });
 	throw new CliError(
-		'Usage: admin recipes … | admin suggestion-recipes … | admin republish … | admin create-org --domain <bare-domain> [--onboard] … | admin ask "<question>" | admin patterns … | admin experiments … | admin fleet-experiments … | admin crm … | admin spend … | admin evals … | admin brand-detection … | admin tuning … | admin tuning-context | admin replays … (see --help)'
+		'Usage: admin recipes … | admin demo … | admin suggestion-recipes … | admin republish … | admin create-org --domain <bare-domain> [--onboard] … | admin ask "<question>" | admin patterns … | admin experiments … | admin fleet-experiments … | admin crm … | admin spend … | admin evals … | admin brand-detection … | admin tuning … | admin tuning-context | admin replays … (see --help)'
 	);
 }
 

package/package.json

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