@letterstory/cli 0.121.7 → 0.123.0

package/README.md

@@ -423,6 +423,22 @@ The ledger behind Kernel Tuning's Experiments tab
 (docs/architecture/kernel-experiment-agent.md): every question asked of the kernels,
 how it was tested, and what we learned and why.
 
+### Staff: plan recipes
+
+```bash
+# Needs a STAFF key with recipes:read (reads) and recipes:write (writes): mint it on
+# /superadmin/plan-recipes → "Your agent's key". Recipes are global: one library behind every
+# account's Plan. The same routes and functions as that page.
+export LETTERSTORY_STAFF_API_KEY=<your staff key with recipes:read,recipes:write>
+
+letterstory admin recipes vocab                          # what a recipe can say: fields, goals, kinds, primitives
+letterstory admin recipes export --out recipes.json      # the library as a file
+letterstory admin recipes import recipes.json --dry-run  # what would be created / changed / retired
+letterstory admin recipes import recipes.json            # write it (matched by id, else name)
+letterstory admin recipes save --name "Get cited" --prompt "…" --goals geo --company-types devtools
+letterstory admin recipes save <id> --disable           # retire one (delete <id> --yes removes it)
+```
+
 ### Staff: the CRM pipeline
 
 ```bash

package/lib/cli.mjs

@@ -61,7 +61,7 @@ import {
 } from "./commands.mjs";
 
 // Keep in sync with cli/package.json.
-export const VERSION = "0.121.7";
+export const VERSION = "0.123.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
@@ -101,6 +101,11 @@ export const BOOLEAN_FLAGS = new Set([
 	"verbose",
 	"no-color",
 	"dry-run",
+	// admin recipes list --enabled-only, save --enable|--disable, import --retire-missing
+	"enabled-only",
+	"enable",
+	"disable",
+	"retire-missing",
 	// admin crm record-outcome --draft
 	"draft",
 	// admin crm reach-outs --fresh
@@ -757,6 +762,21 @@ Admin (STAFF key — --staff-key / LETTERSTORY_STAFF_API_KEY; acts before an org
                                                        read-only SQL across every org; --sql prints
                                                        the queries behind the answer. Needs the
                                                        fleet:query capability on the staff key.
+  admin recipes list [--enabled-only] | show <id|name> | vocab [--json]
+                                                       Plan recipes: Letterstory's one global library behind
+                                                       every account's Plan (/superadmin/plan-recipes). vocab
+                                                       says what a recipe can say (fields, goals, company
+                                                       types, primitives). Needs recipes:read.
+  admin recipes export [--out recipes.json]            The library as a file import reads back.
+  admin recipes import <file> [--dry-run] [--retire-missing]
+                                                       Write a library in one call: each recipe matched by id,
+                                                       else name, then changed or created. --dry-run writes
+                                                       nothing; --retire-missing retires every enabled recipe
+                                                       the file leaves out. Exits 1 if any row failed.
+  admin recipes save [<id>] [--file <recipe.json>] [--name …] [--prompt …] [--audience …] [--example …]...
+                     [--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 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
@@ -831,7 +851,8 @@ Admin (STAFF key — --staff-key / LETTERSTORY_STAFF_API_KEY; acts before an org
           | add --vendor V --amount N --from D [--to D] --area A --category C [--basis billed|estimated] …
           | import <file.csv> [--vendor Concentrate] [--area A] [--ledger-key K] [--dry-run]
           | import <file.csv> [--vendor Concentrate] [--area A] [--keep-ledger-key] [--dry-run]
-          | usage <events.json>                       per-call costs as kernels/lettertrace push them
+          | usage <events.json>                       per-call costs as kernels/lettertrace/models push them
+          | usage list --source models --from D --to D   one source's calls back, newest first
           | remove <entry-id> | services | service <slug> [--owner …] [--monthly N|none] [--renewal D] [--units N|none]
                                                        Where Letter's money goes (spending.letter.dev):
                                                        totals, run rate, area/vendor/provider/model/

package/lib/commands/admin.mjs

@@ -18,6 +18,7 @@
 //   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)
+//   admin recipes list|show|vocab|export|import|save|delete …                        (recipes:read / recipes:write)
 //   admin replays [--org <id>] [--target <id>] [--status …] [--limit n]                (fleet:read)
 //   admin replay --org <id> [<response-id> | --target <id>] [--surface …]           (fleet:replay)
 //   admin create-org --domain acme.com [--name "Acme"] [--test] [--no-key] [--key-name N]
@@ -42,7 +43,7 @@
 // The staff key comes from --staff-key or LETTERSTORY_STAFF_API_KEY; the base URL from the
 // usual --url / LETTERSTORY_API_URL / config resolution.
 
-import { readFileSync } from "node:fs";
+import { readFileSync, writeFileSync } from "node:fs";
 import { CliError, LetterstoryClient } from "../client.mjs";
 import {
 	flagStr,
@@ -4042,7 +4043,34 @@ async function cmdAdminSpend(ctx) {
 			return 0;
 		}
 		case "usage": {
-			// Per-call model costs, as kernels / lettertrace push them (POST /api/superadmin/spend/usage):
+			if (positionals[1] === "list") {
+				// One source's calls back, newest first (GET /api/superadmin/spend/usage).
+				const source = flagStr(flags.source);
+				const from = flagStr(flags.from);
+				const to = flagStr(flags.to);
+				if (!source || !from || !to)
+					throw new CliError(
+						"Usage: admin spend usage list --source models --from YYYY-MM-DD --to YYYY-MM-DD [--limit N]"
+					);
+				const params = new URLSearchParams(
+					compact({ source, from, to, limit: flagNum(flags.limit)?.toString() })
+				);
+				const result = await staffRequest(ctx, "GET", `${SPEND}/usage?${params}`);
+				printResult(
+					io,
+					flags,
+					result,
+					(r) =>
+						(r.events ?? [])
+							.map(
+								(e) =>
+									`${e.occurred_at}  ${e.model.padEnd(16)} ${e.operation.padEnd(10)} ${(e.outcome ?? "").padEnd(8)} ${String(e.latency_ms ?? "").padStart(7)}ms  ${usd(e.cost_usd).padStart(9)}  ${e.key_label}`
+							)
+							.join("\n") + (r.next ? "\n… more (narrow --from/--to or raise --limit)" : "")
+				);
+				return 0;
+			}
+			// Per-call model costs, as kernels / lettertrace / models push them (POST /api/superadmin/spend/usage):
 			// a JSON file holding { events: [...] } or a bare array. Idempotent on each event_id.
 			const path = positionals[1];
 			if (!path) throw new CliError("Usage: admin spend usage <events.json>   ({ events: [...] } or an array)");
@@ -4192,7 +4220,7 @@ async function cmdAdminSpend(ctx) {
 		}
 		default:
 			throw new CliError(
-				"Usage: admin spend summary [--range day|week|month|year | --from D --to D] [--grain day|week|month] | reconcile [--from D --to D] | pnl [--range …] | reference add … | stripe-sync --from D --to D | entries [--from D] [--to D] [--vendor V] [--area A] [--source S] | add --vendor V --amount N --from D … | import <file.csv> … | usage <events.json> | remove <entry-id> | services | service <slug> --owner … --monthly …"
+				"Usage: admin spend summary [--range day|week|month|year | --from D --to D] [--grain day|week|month] | reconcile [--from D --to D] | pnl [--range …] | reference add … | stripe-sync --from D --to D | entries [--from D] [--to D] [--vendor V] [--area A] [--source S] | add --vendor V --amount N --from D … | import <file.csv> … | usage <events.json> | usage list --source S --from D --to D | remove <entry-id> | services | service <slug> --owner … --monthly …"
 			);
 	}
 }
@@ -4538,6 +4566,201 @@ async function cmdAdminRepublish(ctx) {
 	return failed.length ? 1 : 0;
 }
 
+const RECIPES = "/api/superadmin/plan-recipes";
+/** The fields a recipe file carries: what import_plan_recipes reads back. */
+const RECIPE_FILE_FIELDS = [
+	"id",
+	"name",
+	"audience",
+	"examples",
+	"prompt",
+	"primitives",
+	"goals",
+	"company_types",
+	"enabled",
+	"position",
+];
+const RECIPES_USAGE =
+	"Usage: admin recipes list [--enabled-only] | show <id|name> | vocab | export [--out <file>] | import <file> [--dry-run] [--retire-missing] | save [<id>] [--file <recipe.json>] [--name …] [--prompt …] [--audience …] [--example …]… [--primitives a,b|none] [--goals a,b|none] [--company-types a,b|none] [--enable|--disable] [--position n] | delete <id> --yes";
+
+const recipeForFile = (r) => Object.fromEntries(RECIPE_FILE_FIELDS.map((k) => [k, r[k]]));
+
+function recipeLine(r) {
+	const scope = [
+		r.goals?.length ? `goals ${r.goals.join(",")}` : "every goal",
+		r.company_types?.length ? `kinds ${r.company_types.join(",")}` : "every kind",
+		`stands up ${r.primitives?.length ? r.primitives.join(",") : "nothing"}`,
+	].join(" · ");
+	return `${String(r.position).padStart(4)}  ${r.enabled ? "on " : "off"}  ${r.name}  [${scope}]  ${r.id}`;
+}
+
+function recipeDetail(r) {
+	return [
+		`${r.name}  ${r.enabled ? "(enabled)" : "(retired)"}  ${r.id}`,
+		`  position:   ${r.position}`,
+		`  goals:      ${r.goals?.join(", ") || "every goal"}`,
+		`  kinds:      ${r.company_types?.join(", ") || "every kind"}`,
+		`  stands up:  ${r.primitives?.join(", ") || "nothing"}`,
+		`  audience:   ${r.audience || "—"}`,
+		`  examples:   ${r.examples?.join("; ") || "—"}`,
+		`  prompt:\n    ${r.prompt.split("\n").join("\n    ")}`,
+	].join("\n");
+}
+
+function readJson(path) {
+	try {
+		return JSON.parse(readFileSync(path, "utf8"));
+	} catch (err) {
+		throw new CliError(`${path}: ${err.message}`);
+	}
+}
+
+/** A recipes file: `{ recipes: [...] }` (what export writes) or a bare array. */
+function readRecipesFile(path) {
+	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 of recipes`);
+	return recipes.map((r) => compact(recipeForFile(r)));
+}
+
+/** A list flag for save: `a,b` (repeatable), `none` to clear it; a bare flag is a mistake. */
+function recipeListFlag(flags, name) {
+	const v = flags[name];
+	if (v === undefined) return undefined;
+	if (v === true) throw new CliError(`--${name} needs a value: a,b or none`);
+	return flagStr(v) === "none" ? [] : flagCsv(v);
+}
+
+/** The fields `admin recipes save` sets: one recipe from --file (or show --json's output), then flags over it. */
+function recipeFromFlags(flags) {
+	const path = flagStr(flags.file);
+	const parsed = path ? readJson(path) : {};
+	const base = parsed?.recipe ?? parsed;
+	if (!base || typeof base !== "object" || Array.isArray(base) || Array.isArray(base.recipes)) {
+		throw new CliError("--file holds one recipe object; use admin recipes import for several");
+	}
+	const examples = flagList(flags.example);
+	return compact({
+		...compact(recipeForFile(base)),
+		name: flagStr(flags.name),
+		audience: flagStr(flags.audience),
+		prompt: flagStr(flags.prompt),
+		examples: examples.length ? examples : undefined,
+		primitives: recipeListFlag(flags, "primitives"),
+		goals: recipeListFlag(flags, "goals"),
+		company_types: recipeListFlag(flags, "company-types"),
+		enabled: flagBool(flags.disable) ? false : flagBool(flags.enable) ? true : undefined,
+		position: flagNum(flags.position),
+	});
+}
+
+/**
+ * `admin recipes …` — the Plan recipes page (/superadmin/plan-recipes) for an agent: Letterstory's
+ * one global library of recipes behind every account's Plan. The loop for building it out is
+ * `vocab` (what a recipe can say) → `export --out recipes.json` → edit → `import recipes.json
+ * --dry-run` → `import recipes.json`. Reads need recipes:read on the staff key, writes
+ * recipes:write; every write is recorded as the key holder's.
+ */
+async function cmdAdminRecipes(ctx) {
+	const { flags, positionals, io } = ctx;
+	const sub = positionals[0];
+	const all = async () => (await staffRequest(ctx, "GET", RECIPES)).recipes ?? [];
+	switch (sub) {
+		case "list": {
+			const recipes = (await all()).filter((r) => !flagBool(flags["enabled-only"]) || r.enabled);
+			printResult(io, flags, { recipes }, (r) =>
+				r.recipes.length ? r.recipes.map(recipeLine).join("\n") : "No recipes yet."
+			);
+			return 0;
+		}
+		case "show": {
+			const key = requirePositional(positionals, 1, "id|name");
+			const recipe = (await all()).find((r) => r.id === key || r.name === key);
+			if (!recipe) throw new CliError(`No recipe with id or name "${key}".`);
+			printResult(io, flags, { recipe }, (r) => recipeDetail(r.recipe));
+			return 0;
+		}
+		case "vocab": {
+			const v = await staffRequest(ctx, "GET", `${RECIPES}/vocabulary`);
+			printResult(io, flags, v, (r) =>
+				[
+					...r.how_recipes_are_read.map((line) => `· ${line}`),
+					"",
+					"Fields:",
+					...r.fields.map((f) => `  ${f.name}: ${f.description}`),
+					"",
+					"Goals:",
+					...r.goals.map((g) => `  ${g.id}${g.available ? "" : " (not available yet)"}: ${g.brief}`),
+					"",
+					`Company types: ${r.company_types.map((t) => `${t.id} (${t.label})`).join(", ")}`,
+					`Primitives:    ${r.primitives.map((p) => `${p.id} (${p.label})`).join(", ")}`,
+				].join("\n")
+			);
+			return 0;
+		}
+		case "export": {
+			const file = { recipes: (await all()).map(recipeForFile) };
+			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 result = await staffPost(ctx, `${RECIPES}/import`, {
+				recipes: readRecipesFile(path),
+				dry_run: flagBool(flags["dry-run"]),
+				retire_missing: flagBool(flags["retire-missing"]),
+			});
+			const verb = {
+				create: "create",
+				update: "update",
+				unchanged: "same  ",
+				retire: "retire",
+				failed: "FAILED",
+			};
+			printResult(io, flags, result, (r) =>
+				[
+					...r.results.map(
+						(row) =>
+							`${verb[row.action] ?? row.action}  ${row.name}${row.changed.length && row.action !== "create" ? `  (${row.changed.join(", ")})` : ""}${row.error ? `  → ${row.error}` : ""}`
+					),
+					`${r.dry_run ? "Would create" : "Created"} ${r.counts.created}, ${r.dry_run ? "update" : "updated"} ${r.counts.updated}, retire${r.dry_run ? "" : "d"} ${r.counts.retired}; ${r.counts.unchanged} unchanged, ${r.counts.failed} failed.${r.dry_run ? " Nothing was written (--dry-run)." : ""}`,
+				].join("\n")
+			);
+			return result.counts?.failed ? 1 : 0;
+		}
+		case "save": {
+			const fields = recipeFromFlags(flags);
+			const id = positionals[1] ?? fields.id;
+			delete fields.id;
+			const result = id
+				? await staffRequest(ctx, "PATCH", `${RECIPES}/${encodeURIComponent(id)}`, fields)
+				: await staffPost(ctx, RECIPES, fields);
+			ok(ctx, `${result.created ? "Created" : "Saved"} "${result.recipe.name}" (${result.recipe.id}).`);
+			printResult(io, flags, result, (r) => recipeDetail(r.recipe));
+			return 0;
+		}
+		case "delete": {
+			const id = requirePositional(positionals, 1, "id");
+			if (!flagBool(flags.yes)) {
+				io.error(
+					`Re-run with --yes to delete for good: ${ctx.bin} admin recipes delete ${id} --yes (save --disable retires one and keeps it)`
+				);
+				return 1;
+			}
+			const result = await staffRequest(ctx, "DELETE", `${RECIPES}/${encodeURIComponent(id)}`);
+			ok(ctx, `Deleted ${id}.`);
+			printResult(io, flags, result);
+			return 0;
+		}
+		default:
+			throw new CliError(RECIPES_USAGE);
+	}
+}
+
 export async function cmdAdmin(ctx) {
 	const sub = ctx.positionals[0];
 	if (sub === "replays" || sub === "replay")
@@ -4555,8 +4778,9 @@ export async function cmdAdmin(ctx) {
 	if (sub === "evals") return cmdAdminEvals({ ...ctx, positionals: ctx.positionals.slice(1) });
 	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) });
 	throw new CliError(
-		'Usage: 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 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/package.json

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