@letterstory/cli 0.146.0 → 0.147.0

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

@@ -65,7 +65,7 @@ import {
 
 // Matches cli/package.json; publish-cli.yml rewrites both to the published version.
 // Matches cli/package.json; publish-cli.yml rewrites both to the published version.
-export const VERSION = "0.146.0";
+export const VERSION = "0.147.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
@@ -844,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
@@ -936,7 +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 "…"]
+          | cap <org-id> <dollars|off> [--why "…"] | cancel <org-id> --why "…" --yes
                                                        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
@@ -1094,7 +1103,7 @@ 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 "…"]]
+  org billing [cap <dollars|off> [--why "…"] | request [--note "…"] | cancel [--why "…"] --yes]
                                                        Usage billing: plan, this period against the
                                                        allowance and spend cap, failed payments; set
                                                        the cap (admins) or ask the admins for more

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 = [
@@ -5090,7 +5213,8 @@ const LAGO_USAGE = `Usage: admin billing lago <command>
   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
-  cap <org-id> <dollars|off> [--why "…"]  set an account's monthly spend cap on overage (off: no cap)`;
+  cap <org-id> <dollars|off> [--why "…"]  set an account's monthly spend cap on overage (off: no cap)
+  cancel <org-id> --why "…" --yes          end an account's Lago plan now and refund its first invoice`;
 
 /** admin billing lago … — staff operations on Lago (docs/billing/lago-integration.md). */
 async function cmdAdminBilling(ctx) {
@@ -5213,6 +5337,23 @@ async function cmdAdminBilling(ctx) {
 			);
 			return 0;
 		}
+		case "cancel": {
+			const orgId = positionals[2];
+			if (!orgId || !flagStr(flags.why)) throw new CliError(LAGO_USAGE);
+			if (!flagBool(flags.yes))
+				throw new CliError(
+					"This ends the plan now and refunds its first invoice. Run again with --yes to do it."
+				);
+			const result = await staffRequest(ctx, "POST", `${LAGO}/cancel`, { orgId, reason: flagStr(flags.why) });
+			printResult(
+				io,
+				flags,
+				result,
+				(r) =>
+					`Cancelled ${orgId}: first invoice ${r.firstInvoice}${r.refundedCents ? `, $${(r.refundedCents / 100).toFixed(2)} refunded` : ""}.`
+			);
+			return 0;
+		}
 		case "cap": {
 			const orgId = positionals[2];
 			const value = positionals[3];
@@ -5259,8 +5400,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

@@ -33,6 +33,7 @@ export const ARGS = {
 		reason: { flag: "why" },
 	},
 	request_billing_tokens: { note: { flag: "note" } },
+	cancel_billing_plan: { reason: { flag: "why" } },
 	list_integrations: {},
 	get_linear_connection: {},
 	list_linear_targets: { team_id: { flag: "team" } },
@@ -125,6 +126,20 @@ async function orgBilling(ctx) {
 		);
 		return 0;
 	}
+	if (positionals[0] === "cancel") {
+		refuseUnknownFlags(ctx, ARGS.cancel_billing_plan, ["yes"]);
+		if (!flagBool(flags.yes))
+			throw new CliError("This ends the plan now and refunds its first invoice. Run again with --yes to do it.");
+		const result = await client.callTool("cancel_billing_plan", argsFromFlags(ARGS.cancel_billing_plan, flags, []));
+		printResult(io, flags, result, (r) =>
+			r.firstInvoice === "refunded"
+				? `Plan cancelled; $${(r.refundedCents / 100).toFixed(2)} refunded to the card.`
+				: r.firstInvoice === "voided"
+					? "Plan cancelled; its unpaid first invoice is voided."
+					: "Plan cancelled."
+		);
+		return 0;
+	}
 	if (positionals[0] === "request") {
 		refuseUnknownFlags(ctx, ARGS.request_billing_tokens, []);
 		const result = await client.callTool(

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.146.0",
+	"version": "0.147.0",
 	"description": "Spin up and manage Letterstory phantom blogs from your terminal.",
 	"type": "module",
 	"license": "UNLICENSED",