@letterstory/cli 0.145.3 → 0.146.1

package/README.md

@@ -442,6 +442,18 @@ letterstory admin recipes save --name "Get cited" --prompt "…" --goals geo --c
 letterstory admin recipes save <id> --disable           # retire one (delete <id> --yes removes it)
 ```
 
+### Staff: Build's suggestion recipes
+
+```bash
+# The same staff key (recipes:read / recipes:write). Build's suggestion recipes are plain-language
+# ways Letterpress finds what a site should build: what to look at, what an obvious yes is, what is
+# not one, an example. Guidance, never rules: each proposal still cites evidence and passes Jev.
+letterstory admin suggestion-recipes export --out suggestion-recipes.json
+letterstory admin suggestion-recipes import suggestion-recipes.json --dry-run
+letterstory admin suggestion-recipes save --name "Docs it already writes" --look-at "…" --obvious-yes "…"
+letterstory admin suggestion-recipes stats              # per recipe: shown, dismissed, and why
+```
+
 ### Staff: the CRM pipeline
 
 ```bash

package/lib/cli.mjs

@@ -64,7 +64,8 @@ import {
 } from "./commands.mjs";
 
 // Matches cli/package.json; publish-cli.yml rewrites both to the published version.
-export const VERSION = "0.145.3";
+// Matches cli/package.json; publish-cli.yml rewrites both to the published version.
+export const VERSION = "0.146.1";
 
 // 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
@@ -843,6 +844,15 @@ 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 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,
+                                                       obvious yes, not a yes, example). stats: per recipe,
+                                                       suggestions shown and dismissed, with the reasons.
+  admin suggestion-recipes save [<id>] [--file r.json] [--name …] [--look-at …] [--obvious-yes …] [--not-a-yes …]
+                     [--example …] [--company-types a,b|none] [--enable|--disable] [--position n]
+                                                       Create one (no id) or change one. Needs recipes:write.
+  admin suggestion-recipes delete <id> --yes           Delete for good (save --disable retires and keeps it).
   admin brand-detection <org-id> [--term <t>]... [--exact <t>]... [--exclude <phrase>]... [--note "…"] | --clear [--note "…"]
                                                        How a client's brand is detected in AI answers, with
                                                        every earlier setting; with flags, set the exact set
@@ -935,6 +945,7 @@ Admin (STAFF key — --staff-key / LETTERSTORY_STAFF_API_KEY; acts before an org
           | reconcile [--org <org-id>] | forward
           | 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 "…"]
                                                        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
@@ -1092,6 +1103,10 @@ Seers (event-driven signals -> drafts):
   org export --split <dir>                             …as one file per record (for keeping config in git)
   org join <dir> [--file <path>]                       Rebuild the bundle from a --split directory
   org integrations                                     Every integration and whether it's connected
+  org billing [cap <dollars|off> [--why "…"] | request [--note "…"]]
+                                                       Usage billing: plan, this period against the
+                                                       allowance and spend cap, failed payments; set
+                                                       the cap (admins) or ask the admins for more
   org linear [teams [--team <id|key>] | set --team <id|key> [--project <id>|none] | disconnect]
                                                        Where Letter files Linear issues (connect in Settings)
   org diff <file|dir>                                  What applying a bundle would change (reads only)

package/lib/commands/admin.mjs

@@ -4885,6 +4885,129 @@ async function cmdAdminRepublish(ctx) {
 	return failed.length ? 1 : 0;
 }
 
+const SUGGESTION_RECIPES = "/api/superadmin/suggestion-recipes";
+const SUGGESTION_RECIPE_FIELDS = [
+	"id",
+	"name",
+	"look_at",
+	"obvious_yes",
+	"not_a_yes",
+	"example",
+	"company_types",
+	"enabled",
+	"position",
+];
+const SUGGESTION_RECIPES_USAGE =
+	"Usage: admin suggestion-recipes list | export [--out <file>] | import <file> [--dry-run] [--retire-missing] | save [<id>] [--name …] [--look-at …] [--obvious-yes …] [--not-a-yes …] [--example …] [--company-types a,b|none] [--enable|--disable] [--position n] | delete <id> --yes | stats";
+
+const suggestionRecipeForFile = (r) => Object.fromEntries(SUGGESTION_RECIPE_FIELDS.map((k) => [k, r[k]]));
+
+/**
+ * `admin suggestion-recipes …` — the ways Build's suggestion pass looks for what a site should
+ * build (src/lib/suggestion-recipes): guidance Letterpress reads, never rules. The loop is
+ * `export --out recipes.json` → edit → `import recipes.json --dry-run` → `import recipes.json`,
+ * and `stats` says how each recipe's suggestions fare (shown, dismissed, why). Reads need
+ * recipes:read on the staff key, writes recipes:write.
+ */
+async function cmdAdminSuggestionRecipes(ctx) {
+	const { flags, positionals, io } = ctx;
+	const all = async () => (await staffRequest(ctx, "GET", SUGGESTION_RECIPES)).recipes ?? [];
+	switch (positionals[0]) {
+		case "list": {
+			const recipes = await all();
+			printResult(io, flags, { recipes }, (r) =>
+				r.recipes.length
+					? r.recipes
+							.map(
+								(x) =>
+									`${String(x.position).padStart(4)}  ${x.enabled ? "on " : "off"}  ${x.name}  [${x.company_types?.length ? x.company_types.join(",") : "every kind"}]  ${x.id}`
+							)
+							.join("\n")
+					: "No recipes yet."
+			);
+			return 0;
+		}
+		case "export": {
+			const file = { recipes: (await all()).map(suggestionRecipeForFile) };
+			const out = flagStr(flags.out);
+			if (out) {
+				writeFileSync(out, `${JSON.stringify(file, null, 2)}\n`);
+				ok(ctx, `Wrote ${file.recipes.length} recipe(s) to ${out}.`);
+			} else io.log(JSON.stringify(file, null, 2));
+			return 0;
+		}
+		case "import": {
+			const path = requirePositional(positionals, 1, "file");
+			const parsed = readJson(path);
+			const recipes = Array.isArray(parsed) ? parsed : parsed?.recipes;
+			if (!Array.isArray(recipes)) throw new CliError(`${path}: expected { "recipes": [...] } or an array`);
+			const result = await staffPost(ctx, `${SUGGESTION_RECIPES}/import`, {
+				recipes: recipes.map((r) => compact(suggestionRecipeForFile(r))),
+				dry_run: flagBool(flags["dry-run"]),
+				retire_missing: flagBool(flags["retire-missing"]),
+			});
+			printResult(io, flags, result, (r) =>
+				[
+					...r.results.map(
+						(row) =>
+							`${row.action.padEnd(9)} ${row.name}${row.changed.length && row.action !== "create" ? `  (${row.changed.join(", ")})` : ""}${row.error ? `  → ${row.error}` : ""}`
+					),
+					r.dry_run ? "Nothing was written (--dry-run)." : "",
+				]
+					.filter(Boolean)
+					.join("\n")
+			);
+			return result.results?.some((r) => r.action === "failed") ? 1 : 0;
+		}
+		case "save": {
+			const fields = compact({
+				name: flagStr(flags.name),
+				look_at: flagStr(flags["look-at"]),
+				obvious_yes: flagStr(flags["obvious-yes"]),
+				not_a_yes: flagStr(flags["not-a-yes"]),
+				example: flagStr(flags.example),
+				company_types: recipeListFlag(flags, "company-types"),
+				enabled: flagBool(flags.disable) ? false : flagBool(flags.enable) ? true : undefined,
+				position: flagNum(flags.position),
+			});
+			const id = positionals[1];
+			const result = id
+				? await staffRequest(ctx, "PATCH", `${SUGGESTION_RECIPES}/${encodeURIComponent(id)}`, fields)
+				: await staffPost(ctx, SUGGESTION_RECIPES, fields);
+			ok(ctx, `${result.created ? "Created" : "Saved"} "${result.recipe.name}" (${result.recipe.id}).`);
+			printResult(io, flags, result);
+			return 0;
+		}
+		case "delete": {
+			const id = requirePositional(positionals, 1, "id");
+			if (!flagBool(flags.yes)) {
+				io.error(`Re-run with --yes to delete for good (save ${id} --disable retires one and keeps it).`);
+				return 1;
+			}
+			const result = await staffRequest(ctx, "DELETE", `${SUGGESTION_RECIPES}/${encodeURIComponent(id)}`);
+			ok(ctx, `Deleted ${id}.`);
+			printResult(io, flags, result);
+			return 0;
+		}
+		case "stats": {
+			const result = await staffRequest(ctx, "GET", `${SUGGESTION_RECIPES}/stats`);
+			printResult(io, flags, result, (r) =>
+				r.stats.length
+					? r.stats
+							.map(
+								(s) =>
+									`${String(s.shown).padStart(5)} shown  ${String(s.dismissed).padStart(4)} dismissed  ${s.recipe}${s.reasons.length ? `\n        why: ${s.reasons.slice(0, 3).join(" · ")}` : ""}`
+							)
+							.join("\n")
+					: "No suggestions from the pass yet."
+			);
+			return 0;
+		}
+		default:
+			throw new CliError(SUGGESTION_RECIPES_USAGE);
+	}
+}
+
 const RECIPES = "/api/superadmin/plan-recipes";
 /** The fields a recipe file carries: what import_plan_recipes reads back. */
 const RECIPE_FILE_FIELDS = [
@@ -5089,7 +5212,8 @@ const LAGO_USAGE = `Usage: admin billing lago <command>
   payments [--org <org-id>] [--open]     failed payments and what the retry loop did about each
   payments retry <lago-invoice-id>       charge one failed invoice again now
   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`;
+  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)`;
 
 /** admin billing lago … — staff operations on Lago (docs/billing/lago-integration.md). */
 async function cmdAdminBilling(ctx) {
@@ -5212,6 +5336,27 @@ async function cmdAdminBilling(ctx) {
 			);
 			return 0;
 		}
+		case "cap": {
+			const orgId = positionals[2];
+			const value = positionals[3];
+			if (!orgId || value === undefined) throw new CliError(LAGO_USAGE);
+			const off = ["off", "none", "null"].includes(value.toLowerCase());
+			const capUsd = off ? null : Number(value.replace(/^\$/, ""));
+			if (capUsd !== null && (!Number.isFinite(capUsd) || capUsd < 0))
+				throw new CliError(`Not a cap: ${value}. Give dollars (0 stops at the allowance) or off.`);
+			const result = await staffRequest(
+				ctx,
+				"POST",
+				`${LAGO}/cap`,
+				compact({ orgId, cap_usd: capUsd, reason: flagStr(flags.why) })
+			);
+			printResult(io, flags, result, (r) =>
+				r.spendCap
+					? `Spend cap: $${r.spendCap.usd} of overage a month (alerts: ${r.alert}).`
+					: "No spend cap: overage is on."
+			);
+			return 0;
+		}
 		default:
 			throw new CliError(LAGO_USAGE);
 	}
@@ -5237,8 +5382,10 @@ 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 === "suggestion-recipes")
+		return cmdAdminSuggestionRecipes({ ...ctx, positionals: ctx.positionals.slice(1) });
 	throw new CliError(
-		'Usage: admin 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 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/lib/commands/org.mjs

@@ -28,6 +28,11 @@ export const ARGS = {
 	describe_org_config_fields: {},
 	get_org_config_source: {},
 	get_billing_payments: {},
+	set_billing_spend_cap: {
+		cap_usd: { value: (_flags, positionals) => capFrom(requirePositional(positionals, 0, "dollars|off")) },
+		reason: { flag: "why" },
+	},
+	request_billing_tokens: { note: { flag: "note" } },
 	list_integrations: {},
 	get_linear_connection: {},
 	list_linear_targets: { team_id: { flag: "team" } },
@@ -90,9 +95,45 @@ async function orgIntegrations(ctx) {
 	return 0;
 }
 
-/** `org billing`: the org's plan on Lago, whether it is past due, and its failed payments (get_billing_payments). */
+/** A cap from the command line: dollars, or `off` (no cap). */
+function capFrom(value) {
+	if (["off", "none", "null"].includes(String(value).toLowerCase())) return null;
+	const usd = Number(String(value).replace(/^\$/, ""));
+	if (!Number.isFinite(usd) || usd < 0)
+		throw new CliError(`Not a cap: ${value}. Give dollars (0 stops at the allowance) or off.`);
+	return usd;
+}
+
+const usd = (n) => `$${Number(n).toFixed(2)}`;
+
+/**
+ * `org billing`: the org's plan on Lago, this period against its allowance and spend cap, whether
+ * it is past due, and its failed payments (get_billing_payments). `org billing cap <dollars|off>`
+ * sets the cap (set_billing_spend_cap, admins); `org billing request` asks the admins for more
+ * (request_billing_tokens).
+ */
 async function orgBilling(ctx) {
-	const { client, flags, io } = ctx;
+	const { client, flags, io, positionals } = ctx;
+	if (positionals[0] === "cap") {
+		refuseUnknownFlags(ctx, ARGS.set_billing_spend_cap, []);
+		const args = argsFromFlags(ARGS.set_billing_spend_cap, flags, positionals.slice(1));
+		const result = await client.callTool("set_billing_spend_cap", args);
+		printResult(io, flags, result, (r) =>
+			r.spendCap
+				? `Spend cap: ${usd(r.spendCap.usd)} of overage a month${r.spendCap.usd === 0 ? " (work stops at the allowance)" : ""}.${r.alert === "failed" ? " The alerts couldn't be moved; the cap holds." : ""}`
+				: "No spend cap: overage is on."
+		);
+		return 0;
+	}
+	if (positionals[0] === "request") {
+		refuseUnknownFlags(ctx, ARGS.request_billing_tokens, []);
+		const result = await client.callTool(
+			"request_billing_tokens",
+			argsFromFlags(ARGS.request_billing_tokens, flags, [])
+		);
+		printResult(io, flags, result, (r) => `Asked ${r.emailedTo} admin${r.emailedTo === 1 ? "" : "s"} for more.`);
+		return 0;
+	}
 	refuseUnknownFlags(ctx, {}, []);
 	const result = await client.callTool("get_billing_payments", {});
 	printResult(io, flags, result, (r) =>
@@ -100,6 +141,16 @@ async function orgBilling(ctx) {
 			r.plan
 				? `Plan: ${r.plan.name}${r.plan.ratio !== 1 ? ` (${r.plan.ratio}x)` : ""}`
 				: "Not billed by usage yet.",
+			...(r.usage
+				? [
+						`This period (${r.usage.periodFrom.slice(0, 10)} to ${r.usage.periodTo.slice(0, 10)}): ${r.usage.usedTokens} of ${r.usage.allowanceTokens} tokens included${r.usage.overageUsd > 0 ? `, ${usd(r.usage.overageUsd)} of overage` : ""}.`,
+					]
+				: []),
+			r.spendCap
+				? `Spend cap: ${usd(r.spendCap.usd)} of overage a month${r.usage?.availableTokens != null ? `, ${Math.max(0, r.usage.availableTokens)} tokens left under it` : ""}.`
+				: r.plan
+					? "No spend cap: overage is on."
+					: null,
 			...(r.pastDueAt ? [`Past due since ${r.pastDueAt}.`] : []),
 			...(r.payments.length
 				? r.payments.map(
@@ -107,7 +158,9 @@ async function orgBilling(ctx) {
 							`  ${p.invoiceNumber ?? p.invoiceId}  $${(p.amountCents / 100).toFixed(2)}  ${p.status}${p.nextAttemptAt ? `, next try ${p.nextAttemptAt}` : ""}${p.payUrl ? `  pay: ${p.payUrl}` : ""}`
 					)
 				: ["No failed payments."]),
-		].join("\n")
+		]
+			.filter((line) => line !== null)
+			.join("\n")
 	);
 	return 0;
 }

package/lib/commands/site.mjs

@@ -3,6 +3,7 @@
 //   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 research-builds <host> → research_builds (Build's suggestion pass: propose, check, Jev, store)
 //   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
@@ -83,6 +84,9 @@ const ARGS = {
 		host: { positional: 0, required: true, label: "host" },
 		limit: { flag: "limit", type: "num" },
 	},
+	research_builds: {
+		host: { positional: 0, required: true, label: "host" },
+	},
 	get_site_metrics: {
 		host: { positional: 0, required: true, label: "host" },
 		path: { positional: 1, label: "path" },
@@ -204,6 +208,8 @@ export async function cmdSite(ctx) {
 			return siteUnmap(rest);
 		case "tree":
 			return siteTree(rest);
+		case "research-builds":
+			return siteResearchBuilds(rest);
 		case "builds":
 			return siteBuilds(rest);
 		case "metrics":
@@ -406,6 +412,28 @@ async function siteBuilds(ctx) {
 		);
 		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(", ")}`);
+		lines.push(
+			r.pass
+				? `Suggestion pass ${r.pass.ranAt}: kept ${r.pass.kept}, dropped ${r.pass.rejected}.`
+				: "Suggestion pass: never run (site research-builds <host>)."
+		);
+		return lines.join("\n");
+	});
+	return 0;
+}
+
+async function siteResearchBuilds(ctx) {
+	const { client, flags, io } = ctx;
+	refuseUnknownFlags(ctx, ARGS.research_builds);
+	const result = await client.callTool(
+		"research_builds",
+		argsFromFlags(ARGS.research_builds, flags, ctx.positionals)
+	);
+	printResult(io, flags, result, (r) => {
+		if (!r.ran) return `Not run (${r.reason ?? "fresh"}); list_build_suggestions shows the stored pass.`;
+		const lines = r.suggestions.map((s) => `KEPT ${s.summary}\n  ${s.relevance}\n  ${s.id}`);
+		for (const x of r.rejected) lines.push(`DROPPED ${x.summary || x.surface}: ${x.reason}`);
+		if (!r.suggestions.length) lines.push("Nothing passed: zero is a valid result.");
 		return lines.join("\n");
 	});
 	return 0;

package/package.json

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