@letterstory/cli 0.114.0 → 0.117.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.117.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
@@ -98,6 +98,8 @@ export const BOOLEAN_FLAGS = new Set([
 	"verbose",
 	"no-color",
 	"dry-run",
+	// admin crm record-outcome --draft
+	"draft",
 	"prune",
 	// org git sync --force
 	"force",
@@ -786,7 +788,13 @@ 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] [--cause voluntary|involuntary|unknown] [--notice-at ISO] | undo-churn <account-id> | draft-churn-reason <account-id>
+          | outcomes [--account <id>] [--kind churn|contraction|expansion|reactivation|save]
+                     [--status draft|confirmed|discarded] [--since ISO] [--until ISO] [--limit N]
+          | record-outcome <account-id> <kind> [--reason code] [--also a,b] [--cause …] [--notice-at ISO]
+                     [--at ISO] [--mrr-before N] [--mrr-after N] [--note "…"] [--save-offer …]
+                     [--save-result …] [--draft]
+          | renewals [--days 90]
           | 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>
@@ -800,8 +808,18 @@ Admin (STAFF key — --staff-key / LETTERSTORY_STAFF_API_KEY; acts before an org
                                                        White glove is a person's decision: the
                                                        desk only suggests ($1K+/mo post-sales).
                                                        Churn: 30/90-day logo + revenue rates, who
-                                                       churned and why; Stripe cancellations are
-                                                       only suggestions until a person records one.
+                                                       churned and why, split voluntary /
+                                                       involuntary, and payments failing now;
+                                                       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.
+                                                       Outcomes keep every churn, contraction,
+                                                       expansion, reactivation and save with its
+                                                       reason; a key records drafts a person
+                                                       confirms. Renewals: contracts renewing
+                                                       within N days, and Stripe cancels scheduled.
                                                        Onboard runs org → link → phantom sites →
                                                        Slack channel → checklist → app invites →
                                                        stage in one call (--site "" = infer the
@@ -1403,7 +1421,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|outcomes|record-outcome|renewals|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),
 				})
@@ -2539,6 +2562,16 @@ function signalLine(s) {
 	return `${s.id}  [${s.status} · ${s.intent}]  ${s.occurredAt.slice(0, 10)}  ${s.source}/${s.kind}  ${s.title}${who ? `\n    ${who}` : ""}`;
 }
 
+/** One outcome on a line: when, kind, status, reason, MRR move, id. */
+function outcomeLine(o) {
+	const usd = (c) => (c == null ? "?" : `$${Math.round(c / 100).toLocaleString("en-US")}`);
+	const mrr =
+		o.mrrBeforeCents != null || o.mrrAfterCents != null
+			? `  ${usd(o.mrrBeforeCents)} → ${usd(o.mrrAfterCents)}/mo`
+			: "";
+	return `${o.effectiveAt.slice(0, 10)}  ${o.kind}  ${o.status}  ${o.primaryReason ?? "no reason"}${mrr}${o.note ? `  — ${o.note}` : ""}  ${o.id}`;
+}
+
 function accountLine(a) {
 	const score = a.likelihood == null ? "—" : a.likelihood.toFixed(2);
 	return `${a.id}  [${a.stage}]  ${score}  ${a.name}${a.domain ? ` (${a.domain})` : ""}${a.isYc ? " · YC" : ""}`;
@@ -3299,12 +3332,23 @@ async function cmdAdminCrm(ctx) {
 			return out(r, () => (action === "on" ? "moved to white glove" : "left white glove"));
 		}
 		case "churn": {
-			// admin crm churn [--months 12] — the 30/90-day rates, who churned and why, likely churns.
+			// admin crm churn [--months 12] — the 30/90-day rates split voluntary / involuntary,
+			// who churned and why, likely churns, and payments failing now.
 			const params = new URLSearchParams(compact({ months: flagStr(flags.months) }));
 			const pct = (x) => (x == null ? "—" : `${(x * 100).toFixed(1)}%`);
 			const usd = (cents) => `$${Math.round(cents / 100).toLocaleString("en-US")}`;
+			const split = (b) =>
+				b
+					? `    voluntary ${b.voluntary.churned} · ${usd(b.voluntary.mrrLostCents)}/mo  involuntary ${b.involuntary.churned} · ${usd(b.involuntary.mrrLostCents)}/mo  unknown ${b.unknown.churned} · ${usd(b.unknown.mrrLostCents)}/mo`
+					: null;
 			const win = (label, w) =>
-				`${label}: ${w.churned}/${w.customersAtStart} customers (${pct(w.rate)}) · ${usd(w.mrrLostCents)}/mo lost (${pct(w.revenueRate)} of MRR)`;
+				[
+					`${label}: ${w.churned}/${w.customersAtStart} customers (${pct(w.rate)}) · ${usd(w.mrrLostCents)}/mo lost (${pct(w.revenueRate)} of MRR)`,
+					split(w.byCause),
+				]
+					.filter(Boolean)
+					.join("\n");
+			const cause = (x) => (x.cause ? `  [${x.cause}${x.causeSignal ? `: ${x.causeSignal}` : ""}]` : "");
 			return out(await staffRequest(ctx, "GET", `${CRM}/churn?${params}`), (r) =>
 				[
 					win("30d", r.window.days30),
@@ -3314,14 +3358,24 @@ async function cmdAdminCrm(ctx) {
 					...(r.churned.length
 						? r.churned.map(
 								(c) =>
-									`  ${c.churnedAt.slice(0, 10)}${c.churnedAtSource === "undated" ? "?" : ""}  ${c.account.name}  ${c.reason ?? "unrecorded"}  ${usd(c.mrrLostCents)}/mo${c.note ? `  — ${c.note}` : ""}`
+									`  ${c.churnedAt.slice(0, 10)}${c.churnedAtSource === "undated" ? "?" : ""}  ${c.account.name}  ${c.reason ?? "unrecorded"}  ${usd(c.mrrLostCents)}/mo${cause(c)}${c.note ? `  — ${c.note}` : ""}`
 							)
 						: ["  (none)"]),
 					"",
 					"Likely churned (not recorded):",
 					...(r.likely.length
-						? r.likely.map((l) => `  ${accountLine(l.account)}\n    ${l.signal}`)
+						? r.likely.map((l) => `  ${accountLine(l.account)}${cause(l)}\n    ${l.signal}`)
 						: ["  (none)"]),
+					"",
+					"Payments failing now:",
+					...(r.failing == null
+						? ["  (unavailable: the billing read failed, so this is not an all-clear)"]
+						: r.failing.length
+							? r.failing.map(
+									(f) =>
+										`  ${f.name}  ${f.amountCents == null ? "amount unknown" : usd(f.amountCents)}${f.since ? `  since ${f.since.slice(0, 10)}` : ""}${f.attempts != null ? `  ${f.attempts} attempt${f.attempts === 1 ? "" : "s"}` : ""}  → ${f.action ?? (f.nudgeInHours != null ? `wait ${f.nudgeInHours}h (Stripe retrying)` : "none")}  (${f.accountId ?? "no account"})\n    ${f.reason}`
+								)
+							: ["  (none)"]),
 				].join("\n")
 			);
 		}
@@ -3358,6 +3412,8 @@ async function cmdAdminCrm(ctx) {
 					note: flagStr(flags.note),
 					churned_at: flagStr(flags.at),
 					mrr_cents: flagNum(flags["mrr-cents"]),
+					cause: flagStr(flags.cause),
+					notice_at: flagStr(flags["notice-at"]),
 				})
 			);
 			return out(
@@ -3366,6 +3422,86 @@ 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 "outcomes": {
+			// admin crm outcomes [--account id] [--kind …] [--status …] [--since ISO] [--until ISO] [--limit N]
+			const params = new URLSearchParams(
+				compact({
+					account_id: flagStr(flags.account),
+					kind: flagStr(flags.kind),
+					status: flagStr(flags.status),
+					since: flagStr(flags.since),
+					until: flagStr(flags.until),
+					limit: flagStr(flags.limit),
+				})
+			);
+			return out(await staffRequest(ctx, "GET", `${CRM}/outcomes?${params}`), (r) =>
+				r.outcomes.length ? r.outcomes.map(outcomeLine).join("\n") : "(no outcomes)"
+			);
+		}
+		case "record-outcome": {
+			// admin crm record-outcome <account-id> <kind> [--reason code] [--also a,b] … [--draft]
+			if (!id || !action) {
+				throw new CliError(
+					'Usage: admin crm record-outcome <account-id> <churn|contraction|expansion|reactivation|save> [--reason code] [--also a,b] [--cause voluntary|involuntary|unknown] [--notice-at ISO] [--at ISO] [--mrr-before N] [--mrr-after N] [--note "…"] [--save-offer discount|pause|downgrade|fix|other] [--save-result kept|lost|pending] [--draft]'
+				);
+			}
+			const also = flagStr(flags.also);
+			const r = await staffPost(
+				ctx,
+				`${CRM}/outcomes`,
+				compact({
+					account_id: id,
+					kind: action,
+					status: flagBool(flags.draft) ? "draft" : undefined,
+					primary_reason: flagStr(flags.reason),
+					contributing_reasons: also ? also.split(",").map((x) => x.trim()) : undefined,
+					cause: flagStr(flags.cause),
+					notice_at: flagStr(flags["notice-at"]),
+					effective_at: flagStr(flags.at),
+					mrr_before_cents: flagNum(flags["mrr-before"]),
+					mrr_after_cents: flagNum(flags["mrr-after"]),
+					note: flagStr(flags.note),
+					save_offer: flagStr(flags["save-offer"]),
+					save_result: flagStr(flags["save-result"]),
+				})
+			);
+			return out(
+				r,
+				(x) =>
+					`${x.outcome.status === "draft" ? "drafted (a person confirms it)" : "recorded"}: ${outcomeLine(x.outcome)}`
+			);
+		}
+		case "renewals": {
+			// admin crm renewals [--days 90] — contracts renewing soon, and Stripe cancels scheduled.
+			const params = new URLSearchParams(compact({ days: flagStr(flags.days) }));
+			return out(await staffRequest(ctx, "GET", `${CRM}/renewals?${params}`), (r) =>
+				r.renewals.length
+					? r.renewals
+							.map(
+								(x) =>
+									`${x.daysLeft == null ? "  ?" : String(x.daysLeft).padStart(3)}d  ${x.name}  ${x.renewsAt ? `renews ${x.renewsAt}${x.noticeBy ? ` (notice by ${x.noticeBy})` : ""}` : ""}${x.cancelScheduledAt ? `  cancel scheduled${x.cancelsAt ? `, ends ${x.cancelsAt.slice(0, 10)}` : ""}` : ""}  ${x.accountId}`
+							)
+							.join("\n")
+					: `(nothing in the next ${r.days} days)`
+			);
+		}
 		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 +3556,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|outcomes|record-outcome|renewals|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.117.0",
 	"description": "Spin up and manage Letterstory phantom blogs from your terminal.",
 	"type": "module",
 	"license": "UNLICENSED",