@letterstory/cli 0.135.0 → 0.137.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

@@ -57,12 +57,13 @@ import {
 	cmdEvals,
 	cmdOfferings,
 	cmdEnclosures,
+	cmdCampaigns,
 	cmdTargets,
 	cmdVisits,
 } from "./commands.mjs";
 
 // Keep in sync with cli/package.json.
-export const VERSION = "0.135.0";
+export const VERSION = "0.137.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 +289,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.
@@ -566,6 +569,11 @@ Enclosures (pictures, clips and sentences made for each prospect; each output is
   enclosures apps connect <sign-in-url> [--no-remember] A sign-in link a person opens (no password passes through)
   enclosures apps disconnect <app-id> --yes            Remove it here and at the browser provider
 
+Campaigns (one prompt, and Letter's agent builds the whole cold-email campaign; nothing sends until you approve):
+  campaigns build "<prompt>" [--limit <n>] [--watch]   The list, the picture (tested on 3), the email, the review desk
+  campaigns show <build-id> [--watch]                   Its stage, what it built, and what it is doing
+  campaigns list | cancel <build-id> | suggest          Its builds; stop one (what it built is kept); three to build
+
 Offerings (context layered org → offering → collection; a layer sets only what it overrides):
   offerings list                                       The org's offerings (things you'd name when recommending them)
   offerings show <offering-id>                         One offering + its competitor overrides
@@ -908,6 +916,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
@@ -1485,6 +1500,7 @@ const CLIENT_COMMANDS = {
 	directives: cmdDirectives,
 	offerings: cmdOfferings,
 	enclosures: cmdEnclosures,
+	campaigns: cmdCampaigns,
 	targets: cmdTargets,
 	probes: cmdProbes,
 	suggestions: cmdSuggestions,

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/campaigns.mjs

@@ -0,0 +1,159 @@
+// `campaigns` — one prompt, and Letter's agent builds the whole cold-email campaign: the list, the
+// enclosure (tested on 3 and chosen), the sequence email that carries each person's picture, and
+// the launch into review. Thin wrappers over the campaign build tools, which call the same
+// functions the app's /api/campaign-builds routes do.
+
+import { CliError } from "../client.mjs";
+import { argsFromFlags, flagNum, pollUntil, printResult, refuseUnknownFlags, ok } from "./shared.mjs";
+
+// 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 = {
+	build_campaign: {
+		prompt: {
+			value: (_flags, positionals) => {
+				const words = positionals.join(" ").trim();
+				if (!words)
+					throw new CliError(
+						'Say what to build, e.g. campaigns build "Cold-email 10 SaaS founders with an audit of their own site"'
+					);
+				return words;
+			},
+		},
+		people_limit: { flag: "limit", type: "num" },
+	},
+	get_campaign_build: { build_id: { positional: 0, label: "build-id", required: true } },
+	list_campaign_builds: { limit: { flag: "limit", type: "num" } },
+	cancel_campaign_build: { build_id: { positional: 0, label: "build-id", required: true } },
+	suggest_campaigns: {},
+};
+
+const USAGE = `Usage:
+  campaigns build "<prompt>" [--limit <n>] [--watch]   Build a whole campaign from one prompt (at most 50 people)
+  campaigns show <build-id> [--watch]                   Its stage, what it built, and what it is doing
+  campaigns list [--limit <n>]                          This org's builds, newest first
+  campaigns cancel <build-id>                           Stop it; what it built is kept
+  campaigns suggest                                     Three campaigns to build in one step`;
+
+const STAGES = { who: "Who", picture: "The picture", test: "Tested on 3", email: "The email", desk: "On the desk" };
+
+export async function cmdCampaigns(ctx) {
+	const sub = ctx.positionals[0];
+	const rest = { ...ctx, positionals: ctx.positionals.slice(1) };
+	switch (sub) {
+		case "build":
+			return campaignsBuild(rest);
+		case "show":
+		case "get":
+			return campaignsShow(rest);
+		case "list":
+		case "ls":
+			return campaignsList(rest);
+		case "cancel":
+			return campaignsCancel(rest);
+		case "suggest":
+			return campaignsSuggest(rest);
+		default:
+			throw new CliError(USAGE);
+	}
+}
+
+function formatBuild(b) {
+	const a = b.artifacts ?? {};
+	const lines = [`${b.id}  [${b.status}, ${STAGES[b.stage] ?? b.stage}]  ${b.prompt}`];
+	if (a.list)
+		lines.push(
+			`  who: ${a.list.people} people on "${a.list.name}"${a.list.pulling ? " (still finding them)" : ""}`
+		);
+	if (a.enclosure) {
+		const p = a.enclosure.prints ?? {};
+		lines.push(
+			`  picture: ${a.enclosure.name}${a.enclosure.current_version ? `, version ${a.enclosure.current_version}` : ", testing"}: ${p.done ?? 0} ready, ${p.making ?? 0} making, ${p.no_fit ?? 0} no fit, ${p.failed ?? 0} failed`
+		);
+	}
+	if (a.sequence) lines.push(`  email: ${a.sequence.name} [${a.sequence.status}]`);
+	if (a.desk)
+		lines.push(
+			`  desk: ${a.desk.waiting} copies waiting (${a.desk.with_picture} with their picture), ${a.desk.on_the_way} on the way`
+		);
+	lines.push(`  spent: $${Number(b.cost_usd).toFixed(2)} of $${Number(b.budget_usd).toFixed(2)}`);
+	if (b.summary) lines.push(`  ${b.summary}`);
+	if (b.error) lines.push(`  ${b.error}`);
+	return lines.join("\n");
+}
+
+const formatLine = (l) => `${l.at.slice(11, 19)}  ${l.kind === "say" ? "" : `${l.kind}: `}${l.text}`;
+
+// Follow a build: print each new activity line as it lands, until it stops.
+async function follow(ctx, buildId) {
+	const { client, io } = ctx;
+	let shown = 0;
+	return pollUntil(
+		io,
+		async () => {
+			const { build } = await client.callTool("get_campaign_build", { build_id: buildId });
+			const lines = build.activity ?? [];
+			for (const line of lines.slice(shown)) io.log(formatLine(line));
+			shown = Math.max(shown, lines.length);
+			return { done: build.status !== "running", value: build };
+		},
+		{ intervalMs: 5000, timeoutMs: 60 * 60_000, label: "the campaign build" }
+	);
+}
+
+async function campaignsBuild(ctx) {
+	const { client, flags, positionals, io } = ctx;
+	refuseUnknownFlags(ctx, ARGS.build_campaign, ["watch"]);
+	if (flags.limit !== undefined) flagNum(flags.limit);
+	const result = await client.callTool("build_campaign", argsFromFlags(ARGS.build_campaign, flags, positionals));
+	ok(ctx, `Building it (${result.build.id}). It takes 10 to 20 minutes; nothing sends until you approve a copy.`);
+	const build = flags.watch === true && !flags.json ? await follow(ctx, result.build.id) : result.build;
+	printResult(io, flags, flags.watch === true ? { build } : result, (r) => formatBuild(r.build));
+	return 0;
+}
+
+async function campaignsShow(ctx) {
+	const { client, flags, positionals, io } = ctx;
+	refuseUnknownFlags(ctx, ARGS.get_campaign_build, ["watch"]);
+	const args = argsFromFlags(ARGS.get_campaign_build, flags, positionals);
+	if (flags.watch === true && !flags.json) {
+		const build = await follow(ctx, args.build_id);
+		io.log(formatBuild(build));
+		return 0;
+	}
+	const result = await client.callTool("get_campaign_build", args);
+	printResult(io, flags, result, (r) =>
+		[formatBuild(r.build), ...(r.build.activity ?? []).slice(-15).map(formatLine)].join("\n")
+	);
+	return 0;
+}
+
+async function campaignsList(ctx) {
+	const { client, flags, io } = ctx;
+	if (flags.limit !== undefined) flagNum(flags.limit);
+	const result = await client.callTool("list_campaign_builds", argsFromFlags(ARGS.list_campaign_builds, flags));
+	printResult(io, flags, result, (r) =>
+		r.builds?.length ? r.builds.map(formatBuild).join("\n\n") : "No campaign builds yet."
+	);
+	return 0;
+}
+
+async function campaignsCancel(ctx) {
+	const { client, flags, positionals, io } = ctx;
+	const result = await client.callTool(
+		"cancel_campaign_build",
+		argsFromFlags(ARGS.cancel_campaign_build, flags, positionals)
+	);
+	ok(ctx, "Stopped. What it built is kept.");
+	printResult(io, flags, result, (r) => formatBuild(r.build));
+	return 0;
+}
+
+async function campaignsSuggest(ctx) {
+	const { client, flags, io } = ctx;
+	const result = await client.callTool("suggest_campaigns", {});
+	printResult(io, flags, result, (r) =>
+		(r.suggestions ?? []).map((s) => `${s.title}\n  letterstory campaigns build "${s.prompt}"`).join("\n\n")
+	);
+	return 0;
+}

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/lib/commands.mjs

@@ -39,6 +39,7 @@ export * from "./commands/landings.mjs";
 export * from "./commands/outbound.mjs";
 export * from "./commands/offerings.mjs";
 export * from "./commands/enclosures.mjs";
+export * from "./commands/campaigns.mjs";
 export * from "./commands/targets.mjs";
 export * from "./commands/admin.mjs";
 export * from "./commands/feedback.mjs";

package/package.json

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