@letterstory/cli 0.176.90 → 0.176.92

package/lib/cli.mjs

@@ -86,7 +86,7 @@ import {
 import { fetchParkedSections, withoutParked } from "./parked.mjs";
 
 // Matches cli/package.json; publish-cli.yml rewrites both to the published version.
-export const VERSION = "0.176.90";
+export const VERSION = "0.176.92";
 
 /** The exit code for a gate refusal (CARD_REQUIRED, PAYMENT_FAILED, OUT_OF_TOKENS): 1 is a plain error. */
 export const EXIT_PAYMENT_REQUIRED = 3;
@@ -1276,7 +1276,7 @@ Admin (STAFF key — --staff-key / LETTERSTORY_STAFF_API_KEY; acts before an org
   admin billing free exposure | backfill --why "…" [--apply]
                                                        Who the free paywall would stop today; the one-time
                                                        signup grant for self-serve orgs with none
-  admin billing free grant <org-id> <tokens> --why "…" [--key k] | grants [--org <org-id>] | revoke <org-id> <ref> --why "…"
+  admin billing free grant <org-id|name> <tokens> --why "…" [--key k] | grants [--org <org-id>] | revoke <org-id> <ref> --why "…"
                                                        Give an org free tokens (a Lago org: a one-off wallet),
                                                        list staff grants, take one back; posted to #billing
   admin billing desk [--card-forms-since ISO] [--json] The Billing desk: switches, failed payments, the
@@ -1286,6 +1286,8 @@ Admin (STAFF key — --staff-key / LETTERSTORY_STAFF_API_KEY; acts before an org
                                                        error codes, one verdict. Read only.
   admin billing free preflight [--json]                Who the paywall stops the moment it is enforced:
                                                        out of tokens, low, paying but covered, undecided
+  admin billing org find <name> [--limit n]           Orgs whose name holds the words, with each one's id and
+                                                       how it is billed (free, lago, legacy, …). Read only.
   admin billing org test <org-id> --why "…" [--off]   Mark an org a test org (never gated or billed), or with
                                                        --off not one; kept with who and why. Not for a payer.
   admin billing emails [--bounced] [--org <org-id>] [--limit N]

package/lib/commands/admin.mjs

@@ -5172,6 +5172,8 @@ function recipeDetail(r) {
 		`${pad}recipe:           ${v.recipe || "—"}`,
 		`${pad}when to use:      ${v.when_to_use || "—"}`,
 		`${pad}when not to use:  ${v.when_not_to_use || "—"}`,
+		// The facts it cannot run without (the fit holds it back in code); unset is the legacy rule until reviewed.
+		`${pad}required inputs:  ${v.requires == null ? "not reviewed (the legacy rule)" : v.requires.join(", ") || "none"}`,
 	];
 	return [
 		`${r.name}  weight ${r.weight}/10  ${r.id}`,
@@ -5186,8 +5188,13 @@ function recipeDetail(r) {
 					`  its prompt:       ${r.automation.prompt}`,
 				]
 			: []),
-		...(r.primitives_access ? ["  letter's tools:   its build may use them (primitives_access)"] : []),
-		...(r.immediate ? ["  immediate:        a quick win: the Plan puts one in every top three"] : []),
+		...(r.tool_access
+			? [
+					`  letter's tools:   its build needs ${r.tool_access.required?.join(", ") || "none named"}; may write ${r.tool_access.writes?.join(", ") || "nothing"} (tool_access)`,
+				]
+			: r.primitives_access
+				? ["  letter's tools:   its build may read the account through them (primitives_access)"]
+				: []),
 		...(variations.length > 1
 			? variations.flatMap((v, i) => [`  variation ${i + 1}: ${v.name}`, ...fields(v, "    ")])
 			: fields(r, "  ")),
@@ -5240,7 +5247,7 @@ function recipeFromFlags(flags) {
 		// --primitives-access true hands a start's build Letter's own tools; false takes them away.
 		primitives_access:
 			flags["primitives-access"] === undefined ? undefined : String(flags["primitives-access"]) === "true",
-		// --immediate true marks a quick win (live within a day): the Plan puts one in every top three.
+		// --immediate is accepted for old scripts and read by nothing: a quick row is one whose runs is empty.
 		immediate: flags.immediate === undefined ? undefined : String(flags.immediate) === "true",
 		// --reads llms_txt,github declares the facts its conditions rest on; --reads "" clears them.
 		reads: flagStr(flags.reads)
@@ -6131,7 +6138,7 @@ async function cmdAdminBillingLegacyUnmark(ctx) {
 const FREE_USAGE = `Usage: admin billing free exposure [--json]               who the free paywall covers, and who is unassigned
        admin billing free backfill --why "…" [--apply]    signup grant for self-serve orgs with none; a dry run unless --apply
        admin billing free repair-subjects --why "…" [--apply]   staff-address signup subjects fixed, refused orgs granted (R1); a dry run unless --apply
-       admin billing free grant <org-id> <tokens> --why "…" [--key k]   give an org free tokens (a Lago org: a one-off wallet); the same key is one grant
+       admin billing free grant <org-id|name> <tokens> --why "…" [--key k]   give an org free tokens (a Lago org: a one-off wallet); the same key is one grant
        admin billing free grants [--org <org-id>] [--limit n]   staff grants, newest first, live and revoked
        admin billing free revoke <org-id> <ref> --why "…"   take a staff grant back (ref from the list: grant:<id> or wallet:staff_…)
        admin billing free preflight [--json]               who the paywall stops the moment it is enforced, and whether it is ready`;
@@ -6237,12 +6244,13 @@ async function cmdAdminBillingFree(ctx) {
 		return 0;
 	}
 	if (positionals[1] === "grant") {
-		const [orgId, tokensArg] = [positionals[2], positionals[3]];
+		const [orgArg, tokensArg] = [positionals[2], positionals[3]];
 		const tokens = Number(String(tokensArg ?? "").replace(/[,_]/g, ""));
-		if (!orgId || !Number.isInteger(tokens) || tokens <= 0) throw new CliError(FREE_USAGE);
+		if (!orgArg || !Number.isInteger(tokens) || tokens <= 0) throw new CliError(FREE_USAGE);
 		const why = flagStr(flags.why);
 		if (!why) throw new CliError(`Say why (--why "…"): it is kept with the grant.\n${FREE_USAGE}`);
 		const key = flagStr(flags.key);
+		const { orgId, name } = await resolveBillingOrg(ctx, orgArg);
 		const r = await staffPost(ctx, "/api/superadmin/billing/free-tokens/grants", {
 			orgId,
 			tokens,
@@ -6260,7 +6268,7 @@ async function cmdAdminBillingFree(ctx) {
 			const what = x.kind === "wallet" ? "as a one-off wallet on Lago" : "as a free-token grant";
 			const lines = [
 				x.granted
-					? `Gave ${x.tokens.toLocaleString("en-US")} tokens ${what} (${x.ref}).`
+					? `Gave ${name ? `${name} ` : ""}${x.tokens.toLocaleString("en-US")} tokens ${what} (${x.ref}).`
 					: `Already given under this key (${x.ref}); nothing new.`,
 			];
 			if (x.standing.before !== x.standing.after)
@@ -6441,13 +6449,49 @@ async function cmdAdminBillingEmails(ctx) {
 	return 0;
 }
 
-const ORG_TEST_USAGE = `Usage: admin billing org test <org-id> --why "…" [--off]
+const ORG_TEST_USAGE = `Usage: admin billing org find <name> [--limit n]
+  Orgs whose name holds the words (or the org with that id), each with its id and how it is billed.
+       admin billing org test <org-id> --why "…" [--off]
   Mark an org a test org (never gated or billed, out of the fleet's customer numbers), or with --off not
   one any more. Kept with who and why, posted to #billing. Refused for an org that pays us. Billing admins.`;
 
-/** admin billing org test <org-id> --why "…" [--off] — setOrgTest (lib/billing/org-test.ts). */
+/** GET /api/superadmin/billing/orgs: orgs by name (or id), each with how it is billed (lib/billing/find-orgs.ts). */
+async function findBillingOrgs(ctx, q, limit) {
+	const qs = new URLSearchParams({ q, ...(limit ? { limit } : {}) });
+	return staffRequest(ctx, "GET", `/api/superadmin/billing/orgs?${qs}`);
+}
+
+const orgLine = (o) => `  ${o.orgId}  ${o.name}  (${o.standing}, made ${o.createdAt.slice(0, 10)})`;
+
+/**
+ * An org named by its id or by its name: the id as given, or the one org the name finds (the exact name when
+ * several hold it). Anything else is refused with the orgs it found, so nothing is done to a guessed org.
+ */
+async function resolveBillingOrg(ctx, words) {
+	if (UUID_PATTERN.test(words)) return { orgId: words, name: null };
+	const { orgs } = await findBillingOrgs(ctx, words);
+	const exact = orgs.filter((o) => o.name.toLowerCase() === words.trim().toLowerCase());
+	const one = exact.length === 1 ? exact[0] : orgs.length === 1 ? orgs[0] : null;
+	if (one) return { orgId: one.orgId, name: one.name };
+	if (!orgs.length) throw new CliError(`No org's name holds "${words}".`);
+	throw new CliError(`"${words}" could be any of these; give the org's id:\n${orgs.map(orgLine).join("\n")}`);
+}
+
+/**
+ * admin billing org find <name> — findBillingOrgs; admin billing org test <org-id> --why "…" [--off] —
+ * setOrgTest (lib/billing/org-test.ts).
+ */
 async function cmdAdminBillingOrg(ctx) {
 	const { flags, positionals, io } = ctx;
+	if (positionals[1] === "find") {
+		const q = positionals.slice(2).join(" ").trim();
+		if (!q) throw new CliError(ORG_TEST_USAGE);
+		const r = await findBillingOrgs(ctx, q, flagStr(flags.limit));
+		printResult(io, flags, r, (x) =>
+			x.orgs.length ? x.orgs.map(orgLine).join("\n") : `No org's name holds "${q}".`
+		);
+		return 0;
+	}
 	const orgId = positionals[2];
 	if (positionals[1] !== "test" || !orgId) throw new CliError(ORG_TEST_USAGE);
 	const why = flagStr(flags.why);

package/package.json

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