@letterstory/cli 0.135.0 → 0.136.0

package/README.md

@@ -254,6 +254,7 @@ letterstory strategy company set --name "Acme" --domain acme.com --manifesto "
 
 letterstory strategy positioning get
 letterstory strategy positioning set --topic seo --topic ai --stance "…" --clear-avoid
+letterstory strategy positioning set --company-kind devtools --stage seed --motion product-led --category "AI visibility"   # the company model; `none` clears a field
 
 letterstory strategy competitors list
 letterstory strategy competitors add "Rival Co" rival.com

package/lib/cli.mjs

@@ -62,7 +62,7 @@ import {
 } from "./commands.mjs";
 
 // Keep in sync with cli/package.json.
-export const VERSION = "0.135.0";
+export const VERSION = "0.136.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
@@ -288,6 +288,8 @@ export const BOOLEAN_FLAGS = new Set([
 	"todo",
 	// admin spend margin: list nested work (never billed twice) beside its parent.
 	"nested",
+	// admin billing lago catalog --apply --include-drafts
+	"include-drafts",
 ]);
 
 // Tiny argv parser: `--flag value`, `--flag=value`, boolean `--flag`, and positionals.
@@ -908,6 +910,13 @@ Admin (STAFF key — --staff-key / LETTERSTORY_STAFF_API_KEY; acts before an org
                                                        cover what the app ledger cannot see; a CSV
                                                        import sums Concentrate's log export.
                                                        Needs spend:read (reads) / spend:write (writes).
+  admin billing lago catalog [--apply] [--include-drafts]
+          | provision <org-id> --plan starter|growth|scale [--ratio 1|2|4|8 (8 needs --why "…")] [--complimentary N] [--stripe-customer cus_…] [--start ISO] [--review D]
+          | reconcile [--org <org-id>] | forward
+                                                       Usage billing on Lago: the plan catalog, an org's
+                                                       plan and gifted ratio, Lago's tokens against ours,
+                                                       and forwarding usage now. Needs spend:read (reads)
+                                                       / billing:write (writes).
   admin crm import <file.csv> [--source <name>] [--tag "…"] [--dry-run]
           | capture [shot.png …] [--text "…" | --text-file f] [--context "this is for acme.com"]
                     [--account <id>] [--dry-run] [--retry]   screenshots / a thread / a note → a lead

package/lib/commands/admin.mjs

@@ -4996,12 +4996,88 @@ async function cmdAdminRecipes(ctx) {
 	}
 }
 
+const LAGO = "/api/superadmin/billing/lago";
+const LAGO_USAGE = `Usage: admin billing lago <command>
+  catalog [--apply] [--include-drafts]   what the plan catalog would change in Lago; --apply makes it so
+  provision <org-id> --plan starter [--ratio 4] [--why "…" above 4x] [--complimentary 20000] [--stripe-customer cus_…] [--start 2026-11-02T00:00:00Z] [--review 2027-05-01]
+  reconcile [--org <org-id>]             Lago's tokens this period against what we rated and forwarded
+  forward                                forward billable usage to Lago now (the cron's pass)`;
+
+/** admin billing lago … — staff operations on Lago (docs/billing/lago-integration.md). */
+async function cmdAdminBilling(ctx) {
+	const { flags, positionals, io } = ctx;
+	if (positionals[0] !== "lago") throw new CliError(LAGO_USAGE);
+	const sub = positionals[1];
+	switch (sub) {
+		case "catalog": {
+			const result = flagBool(flags.apply)
+				? await staffPost(
+						ctx,
+						`${LAGO}/catalog`,
+						compact({ includeDrafts: flagBool(flags["include-drafts"]) || undefined })
+					)
+				: await staffRequest(ctx, "GET", `${LAGO}/catalog`);
+			const changed = (result.changes ?? []).filter((c) => c.action === "create" || c.action === "update");
+			ok(
+				ctx,
+				`${result.dryRun ? "Would change" : "Changed"} ${changed.length} of ${(result.changes ?? []).length}.`
+			);
+			printResult(io, flags, result);
+			return 0;
+		}
+		case "provision": {
+			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}/provision`,
+				compact({
+					orgId,
+					planCode: plan,
+					ratio: flagNum(flags.ratio),
+					exceptionReason: flagStr(flags.why),
+					complimentaryTokens: flagNum(flags.complimentary),
+					stripeCustomerId: flagStr(flags["stripe-customer"]),
+					startAt: flagStr(flags.start),
+					reviewAt: flagStr(flags.review),
+				})
+			);
+			ok(
+				ctx,
+				`${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;
+		}
+		case "reconcile": {
+			const params = new URLSearchParams(compact({ orgId: flagStr(flags.org) }));
+			const result = await staffRequest(ctx, "GET", `${LAGO}/reconcile${params.size ? `?${params}` : ""}`);
+			ok(ctx, result.ok ? "Lago agrees with us." : "Lago and we disagree: see the orgs below.");
+			printResult(io, flags, result);
+			return result.ok ? 0 : 1;
+		}
+		case "forward": {
+			const result = await staffPost(ctx, `${LAGO}/forward`, {});
+			ok(
+				ctx,
+				`Sent ${result.sent}, already there ${result.duplicates}, held ${result.held}, refused ${result.refused}.`
+			);
+			printResult(io, flags, result);
+			return 0;
+		}
+		default:
+			throw new CliError(LAGO_USAGE);
+	}
+}
+
 export async function cmdAdmin(ctx) {
 	const sub = ctx.positionals[0];
 	if (sub === "replays" || sub === "replay")
 		return cmdAdminReplays({ ...ctx, positionals: ctx.positionals.slice(1) }, sub);
 	if (sub === "crm") return cmdAdminCrm({ ...ctx, positionals: ctx.positionals.slice(1) });
 	if (sub === "spend") return cmdAdminSpend({ ...ctx, positionals: ctx.positionals.slice(1) });
+	if (sub === "billing") return cmdAdminBilling({ ...ctx, positionals: ctx.positionals.slice(1) });
 	if (sub === "models") return cmdAdminModels({ ...ctx, positionals: ctx.positionals.slice(1) });
 	if (sub === "create-org") return cmdAdminCreateOrg({ ...ctx, positionals: ctx.positionals.slice(1) });
 	if (sub === "ask") return cmdAdminAsk({ ...ctx, positionals: ctx.positionals.slice(1) });

package/lib/commands/site.mjs

@@ -2,6 +2,7 @@
 // (src/lib/site). One subcommand per tool:
 //   site list                → list_sites               site map <host>            → map_site
 //   site tree <host> [path]  → get_site_tree            site page <host> <path>    → get_site_page
+//   site builds <host>       → list_build_suggestions  (--limit n)
 //   site metrics <host> [path] → get_site_metrics  (--window 7d|28d|90d, --page <path>…, --no-compare)
 //   site observations <host> → list_site_observations   site observe <host>        → observe_site
 //   site dismiss <host> <id> → dismiss_site_observation
@@ -78,6 +79,10 @@ const ARGS = {
 			},
 		},
 	},
+	list_build_suggestions: {
+		host: { positional: 0, required: true, label: "host" },
+		limit: { flag: "limit", type: "num" },
+	},
 	get_site_metrics: {
 		host: { positional: 0, required: true, label: "host" },
 		path: { positional: 1, label: "path" },
@@ -199,6 +204,8 @@ export async function cmdSite(ctx) {
 			return siteUnmap(rest);
 		case "tree":
 			return siteTree(rest);
+		case "builds":
+			return siteBuilds(rest);
 		case "metrics":
 			return siteMetrics(rest);
 		case "page":
@@ -229,7 +236,7 @@ export async function cmdSite(ctx) {
 			return siteHighlight(rest);
 		default:
 			throw new CliError(
-				`Unknown site subcommand: ${sub ?? "(none)"}. Try: list, map, refresh, unmap, tree, metrics, page, observations, observe, dismiss, families, decide-family, proposals, propose, decide, fix, competitors, watch-competitors, highlight`
+				`Unknown site subcommand: ${sub ?? "(none)"}. Try: list, map, refresh, unmap, tree, builds, metrics, page, observations, observe, dismiss, families, decide-family, proposals, propose, decide, fix, competitors, watch-competitors, highlight`
 			);
 	}
 }
@@ -243,7 +250,26 @@ function describeNode(node, indent = "") {
 		: "";
 	const changed = `${node.rollup.added ? ` +${node.rollup.added}` : ""}${node.rollup.removed ? ` -${node.rollup.removed}` : ""}`;
 	const counts = node.hasChildren ? ` (${node.rollup.pages} pages${changed})` : node.page?.added ? " (new)" : "";
-	const out = [`${indent}${glyph.padEnd(2)} ${node.name}${counts}${line ? `  ${line}` : ""}`];
+	// A folder's measured pages, only where the source is measured (null draws nothing: never zero).
+	const m = node.rollup.measured ?? {};
+	const measured = [
+		m.indexed != null ? `${m.indexed} indexed` : null,
+		m.cited != null ? `${m.cited} cited` : null,
+		m.read != null ? `${m.read} read` : null,
+	].filter(Boolean);
+	const coverage = node.rollup.coverage
+		? `${node.rollup.coverage.covered} of ${node.rollup.coverage.total} covered`
+		: null;
+	const rollup =
+		node.hasChildren && (measured.length || coverage)
+			? `  [${[...measured, coverage].filter(Boolean).join(" · ")}]`
+			: "";
+	const out = [`${indent}${glyph.padEnd(2)} ${node.name}${counts}${rollup}${line ? `  ${line}` : ""}`];
+	// What is next in the pattern the folder keeps: violet on the Site, its state the letterbase's.
+	if (node.next) {
+		const owner = node.next.owner ? `${node.next.owner.name} · ${node.next.state}` : "next in the pattern";
+		out.push(`${indent}  ◇  ${node.next.path ?? node.next.title}  ${node.next.why}  (${owner})`);
+	}
 	for (const child of node.children ?? []) out.push(describeNode(child, `${indent}  `));
 	return out.join("\n");
 }
@@ -366,6 +392,25 @@ async function siteTree(ctx) {
 	return 0;
 }
 
+async function siteBuilds(ctx) {
+	const { client, flags, io } = ctx;
+	refuseUnknownFlags(ctx, ARGS.list_build_suggestions);
+	const result = await client.callTool(
+		"list_build_suggestions",
+		argsFromFlags(ARGS.list_build_suggestions, flags, ctx.positionals)
+	);
+	printResult(io, flags, result, (r) => {
+		const lines = r.suggestions.map(
+			(s) =>
+				`${s.summary}  [${s.sources.join(", ")}]${s.action === "article" ? "  (an article: the letterbase's)" : ""}\n  ${s.relevance}\n  ${s.id}`
+		);
+		if (!lines.length) lines.push("Nothing to build: no source makes a surface this site's right now.");
+		if (r.skipped.length) lines.push(`Not read: ${r.skipped.join(", ")}`);
+		return lines.join("\n");
+	});
+	return 0;
+}
+
 async function siteMetrics(ctx) {
 	const { client, flags, io } = ctx;
 	refuseUnknownFlags(ctx, ARGS.get_site_metrics);

package/lib/commands/strategy.mjs

@@ -16,6 +16,18 @@ const clearableList = (flag, clearFlag) => ({
 	},
 });
 
+// A scalar the API clears with an explicit null: `--stage none` sends null, a value sends it
+// (one of `values` when given), nothing sends nothing.
+const clearable = (flag, values) => ({
+	value: (flags) => {
+		const v = flagStr(flags[flag]);
+		if (v === undefined || v === null || v === "") return undefined;
+		if (v === "none") return null;
+		if (values && !values.includes(v)) throw new CliError(`--${flag} must be one of: ${values.join(", ")}, none`);
+		return v;
+	},
+});
+
 // How every tool this module calls gets its arguments — see `argsFromFlags` in shared.mjs.
 // `scripts/parity-check.ts` compares these keys against each tool's published input schema.
 export const ARGS = {
@@ -40,6 +52,21 @@ export const ARGS = {
 		priority_topics: clearableList("topic", "clear-topics"),
 		stances: clearableList("stance", "clear-stances"),
 		avoid_topics: clearableList("avoid", "clear-avoid"),
+		// The company model (lib/positioning/company-model.ts): a vocabulary word, or "none" to clear.
+		company_kind: clearable("company-kind", [
+			"b2b_saas",
+			"devtools",
+			"ai_product",
+			"ecommerce",
+			"marketplace",
+			"agency",
+			"consumer",
+			"media",
+			"local_business",
+		]),
+		stage: clearable("stage", ["pre-seed", "seed", "series-a-plus", "established"]),
+		motion: clearable("motion", ["self-serve", "sales-led", "product-led", "open-source"]),
+		category: clearable("category"),
 	},
 	list_competitors: {},
 	add_competitor: {
@@ -155,7 +182,9 @@ async function positioningSet(ctx) {
 	const { client, flags, io } = ctx;
 	const args = argsFromFlags(ARGS.set_positioning, flags);
 	if (Object.keys(args).length === 0) {
-		throw new CliError("Pass at least one --topic/--stance/--avoid (or a --clear-* flag).");
+		throw new CliError(
+			"Pass at least one --topic/--stance/--avoid (or a --clear-* flag), or --company-kind/--stage/--motion/--category (none clears)."
+		);
 	}
 	const result = await client.callTool("set_positioning", args);
 	ok(ctx, "Positioning updated.");

package/package.json

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