@letterstory/cli 0.114.0 → 0.115.0

package/lib/cli.mjs

@@ -60,7 +60,7 @@ import {
 } from "./commands.mjs";
 
 // Keep in sync with cli/package.json.
-export const VERSION = "0.114.0";
+export const VERSION = "0.115.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
@@ -786,7 +786,7 @@ Admin (STAFF key — --staff-key / LETTERSTORY_STAFF_API_KEY; acts before an org
           | slack-channels [--all] | link-slack <account-id> <channel-id|none>
           | white-glove [--suggested] | set-white-glove <account-id> on|off [--note "…"]
           | churn [--months 12] | record-churn <account-id> <reason> [--note "…"] [--at ISO]
-            [--mrr-cents N] | undo-churn <account-id>
+            [--mrr-cents N] | undo-churn <account-id> | draft-churn-reason <account-id>
           | onboard <account-id> --domain acme.com [--name "Acme"] [--site "<direction>"]… [--sites N]
                    [--slack a@acme.com,b@acme.com] [--invite a@acme.com[:admin]]… [--no-checklist]
           | onboarding <account-id> | retry-onboarding <onboarding-id>
@@ -802,6 +802,9 @@ Admin (STAFF key — --staff-key / LETTERSTORY_STAFF_API_KEY; acts before an org
                                                        Churn: 30/90-day logo + revenue rates, who
                                                        churned and why; Stripe cancellations are
                                                        only suggestions until a person records one.
+                                                       draft-churn-reason drafts a reason from
+                                                       what the CRM kept; a person confirms it in
+                                                       the proposals queue.
                                                        Onboard runs org → link → phantom sites →
                                                        Slack channel → checklist → app invites →
                                                        stage in one call (--site "" = infer the
@@ -1403,7 +1406,9 @@ export async function run(argv, io = defaultIo()) {
 		await resolveDocumentFlags(client, flags);
 
 		const ctx = { client, config, positionals: positionals.slice(1), flags, io, bin };
-		return await handler(ctx);
+		// A handler may return what its last `io.log` returned (`true`): only a number is an exit code.
+		const code = await handler(ctx);
+		return typeof code === "number" ? code : 0;
 	} catch (err) {
 		if (err instanceof CliError) {
 			io.error(`Error: ${err.message}`);

package/lib/commands/admin.mjs

@@ -14,7 +14,7 @@
 //      The old names — evals, eval-add, eval-set, proposals, propose-eval, capture-eval, reject-eval — still work.)
 //   admin evals scoreboard|cases|runs|run|triage|guard|retire …                      (fleet:read / tuning:experiment)
 //   admin fleet-experiments list|articles|clients|mark|unmark|new|assign|assign-eligible|assign-orgs|spin-up|apply|start|stop|decide …  (fleet:read / fleet:experiment)
-//   admin crm import|capture|outreach|signals|record|signal|accounts|account|score|slack-channels|link-slack|white-glove|set-white-glove|churn|revenue|record-churn|undo-churn|onboard|onboarding|retry-onboarding|onboard-plan|payment-link …  (crm:read / crm:write)
+//   admin crm import|capture|outreach|signals|record|signal|accounts|account|score|slack-channels|link-slack|white-glove|set-white-glove|churn|revenue|record-churn|draft-churn-reason|undo-churn|onboard|onboarding|retry-onboarding|onboard-plan|payment-link …  (crm:read / crm:write)
 //   admin spend summary|reconcile|pnl|entries|add|import|usage|remove|reference|stripe-sync|services|service …  (spend:read / spend:write)
 //   admin brand-detection <org-id>                                                   (fleet:read)
 //   admin brand-detection <org-id> [--term t]... [--exact t]... [--exclude p]... [--note "…"] | --clear [--note "…"]   (fleet:instrument)
@@ -44,7 +44,17 @@
 
 import { readFileSync } from "node:fs";
 import { CliError, LetterstoryClient } from "../client.mjs";
-import { flagStr, flagNum, flagBool, flagList, printResult, compact, ok, requirePositional } from "./shared.mjs";
+import {
+	flagStr,
+	flagNum,
+	flagBool,
+	flagList,
+	flagCsv,
+	printResult,
+	compact,
+	ok,
+	requirePositional,
+} from "./shared.mjs";
 import { watchDomainJob } from "./onboard.mjs";
 
 const SEER_MODES = ["suggest", "skip"];
@@ -682,6 +692,21 @@ async function cmdAdminTuningContext(ctx) {
  *   admin tuning enhance-inputs [--set v1] | enhance-split [--since-hours 72] [--at <iso>,…] | enhance-standing
  *   admin tuning promote-enhancer <experiment-id> --version <enhancer-version-id>   promote our enhancer from a "ship" decision (picks when it changes visuals)
  */
+/** `--flag '<json array>'` → the parsed array of objects, or undefined when the flag is absent. */
+function jsonArrayFlag(raw, name) {
+	const text = flagStr(raw);
+	if (text === undefined) return undefined;
+	let v;
+	try {
+		v = JSON.parse(text);
+	} catch (err) {
+		throw new CliError(`${name} is not JSON: ${err.message}`);
+	}
+	if (!Array.isArray(v) || v.some((x) => !x || typeof x !== "object" || Array.isArray(x)))
+		throw new CliError(`${name} is a JSON array of objects: '[{…},{…}]'`);
+	return v;
+}
+
 /** `--flag '<json>'` → the parsed object, or undefined when the flag is absent. */
 function jsonFlag(raw, name) {
 	const text = flagStr(raw);
@@ -846,7 +871,7 @@ async function cmdAdminTuning(ctx) {
 		}
 		case "compare": {
 			const title = flagStr(flags.title);
-			const list = flagList(flags.candidates);
+			const list = flagCsv(flags.candidates);
 			if (!title || !list?.length)
 				throw new CliError(
 					'Usage: admin tuning compare --title "…" --candidates Hazel:21,Aspen:20 [--experiment <id>] [--pairs 20]  (default 10 pairs)'
@@ -2178,10 +2203,8 @@ async function cmdAdminTuning(ctx) {
 			const versionId = flagStr(flags.candidate);
 			const patch = jsonFlag(flags.patch, "--patch");
 			const nullCheck = flagBool(flags["null-check"]);
-			const versionIds = flagList(flags.candidates);
-			const patches = jsonFlag(flags.patches, "--patches");
-			if (patches !== undefined && !Array.isArray(patches))
-				throw new CliError("--patches is a JSON array of patches: '[{…},{…}]'");
+			const versionIds = flagCsv(flags.candidates);
+			const patches = jsonArrayFlag(flags.patches, "--patches");
 			const named = [
 				versionId !== undefined,
 				patch !== undefined,
@@ -2217,7 +2240,7 @@ async function cmdAdminTuning(ctx) {
 					candidates: several,
 					// The kernel that writes every arm into a finished article (the arena the only difference).
 					write: flagStr(flags.write) ? { kernel: flagStr(flags.write) } : undefined,
-					keys: flagList(flags.keys),
+					keys: flagCsv(flags.keys),
 					concurrency: flagNum(flags.concurrency),
 					experiment_id: flagStr(flags.experiment),
 				})
@@ -2244,7 +2267,7 @@ async function cmdAdminTuning(ctx) {
 		case "comparison-extend": {
 			// A Write comparison grows by the next N pairs; one on fixed inputs by named keys or all.
 			const pairs = flagNum(flags.pairs);
-			const keys = flagBool(flags.all) ? "all" : flagList(flags.keys);
+			const keys = flagBool(flags.all) ? "all" : flagCsv(flags.keys);
 			const usage =
 				"Usage: admin tuning comparison-extend <comparison-id> --pairs N | --keys k1 --keys k2 | --all";
 			if (!id || (pairs === undefined && !keys?.length) || (pairs !== undefined && keys?.length))
@@ -2304,7 +2327,7 @@ async function cmdAdminTuning(ctx) {
 					primitive: "shred",
 					title,
 					candidate,
-					keys: flagList(flags.keys),
+					keys: flagCsv(flags.keys),
 					concurrency: flagNum(flags.concurrency),
 					experiment_id: flagStr(flags.experiment),
 				})
@@ -2422,7 +2445,7 @@ async function cmdAdminTuning(ctx) {
 					primitive: "enhance",
 					title,
 					candidate,
-					keys: flagList(flags.keys),
+					keys: flagCsv(flags.keys),
 					concurrency: flagNum(flags.concurrency),
 					experiment_id: flagStr(flags.experiment),
 				})
@@ -3366,6 +3389,23 @@ async function cmdAdminCrm(ctx) {
 					`${x.change === "updated" ? "churn updated" : "churn recorded"}: ${accountLine(x.account)} · ${x.account.churnMrrCents == null ? "no MRR on file" : `$${Math.round(x.account.churnMrrCents / 100)}/mo lost`}`
 			);
 		}
+		case "draft-churn-reason": {
+			// admin crm draft-churn-reason <account-id> — draft why a churned account left, from
+			// what the CRM kept. The draft waits in the proposals queue for a person to confirm.
+			if (!id) throw new CliError("Usage: admin crm draft-churn-reason <account-id>");
+			const r = await staffPost(ctx, `${CRM}/accounts/${id}/churn/draft-reason`, {});
+			return out(r, (x) =>
+				x.status === "drafted"
+					? [
+							`drafted: ${x.reason}${x.contributing.length ? ` (also ${x.contributing.join(", ")})` : ""} · ${x.cause} · proposal ${x.proposalId}`,
+							`  "${x.quote}"`,
+							x.summary ? `  ${x.summary}` : null,
+						]
+							.filter(Boolean)
+							.join("\n")
+					: `${x.status.replaceAll("_", " ")}${x.detail ? ` (${x.detail.replaceAll("_", " ")})` : ""}`
+			);
+		}
 		case "undo-churn": {
 			// admin crm undo-churn <account-id> — clear the churn and move back to active.
 			if (!id) throw new CliError("Usage: admin crm undo-churn <account-id>");
@@ -3420,7 +3460,7 @@ async function cmdAdminCrm(ctx) {
 		}
 		default:
 			throw new CliError(
-				"Usage: admin crm import|capture|outreach|signals|record|signal|accounts|account|score|slack-channels|link-slack|white-glove|set-white-glove|churn|record-churn|undo-churn|onboard|onboarding|retry-onboarding|onboard-plan|payment-link … (see --help)"
+				"Usage: admin crm import|capture|outreach|signals|record|signal|accounts|account|score|slack-channels|link-slack|white-glove|set-white-glove|churn|record-churn|draft-churn-reason|undo-churn|onboard|onboarding|retry-onboarding|onboard-plan|payment-link … (see --help)"
 			);
 	}
 }

package/lib/commands/shared.mjs

@@ -32,6 +32,19 @@ export function flagList(v) {
 	return typeof v === "string" ? [v] : [];
 }
 
+/**
+ * A list of ids or keys, repeatable AND comma-separated: `--keys a,b --keys c` → `["a","b","c"]`.
+ * `flagList` keeps each occurrence whole (free text such as `--stance` may carry a comma); the id
+ * and key flags whose usage says `k1,k2` read through this instead, or the whole string went to the
+ * server as one id and failed validation.
+ */
+export function flagCsv(v) {
+	return flagList(v)
+		.flatMap((x) => x.split(","))
+		.map((x) => x.trim())
+		.filter(Boolean);
+}
+
 /**
  * `--prefer <site>` (repeatable or comma-separated) → preferred_sources `[{ url }]` (a site; a URL is read as its site); `--prefer none`
  * → `[]` (clears a standing list); absent → undefined.

package/package.json

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