@letterstory/cli 0.177.16 → 0.177.18

package/lib/cli.mjs

@@ -88,7 +88,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.177.16";
+export const VERSION = "0.177.18";
 
 /** 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;
@@ -106,6 +106,10 @@ export const BOOLEAN_FLAGS = new Set([
 	"pull-requests",
 	"make-orgs",
 	"no-refit",
+	// build --check: read every gate a start meets and start nothing.
+	"check",
+	// admin invariants: press every startable row as a check too.
+	"presses",
 	// admin targets check: check every target again, checked or not.
 	"recheck",
 	// build list: also move the builds' open changes along while polling.
@@ -1126,6 +1130,10 @@ Admin (STAFF key — --staff-key / LETTERSTORY_STAFF_API_KEY; acts before an org
   admin recipes reread --org <id>,…                    Read these companies from their sites again: what was
                                                        only ever inferred is replaced, what the company changed
                                                        is kept. Refit them after. Needs recipes:write.
+  admin invariants [--org <id>,…] [--limit 50] [--presses]
+                                                       The Ideas invariants over production, read only: rows a
+                                                       start would refuse, builds whose reading disagrees with
+                                                       what they hold, grouped with ids. Exits 1 on any.
   admin targets check [--org <id>,…] [--recheck] [--limit 10]
                                                        Check ranking targets' phrases (buyer intent, self-named,
                                                        search demand, fit) and store each verdict: --org those

package/lib/commands/admin.mjs

@@ -23,6 +23,7 @@
 //   admin letterpress beyond [--limit N] [--before ISO]  (what members asked that went past the library)
 //   admin letterpress endings [--days N] [--write-cases]  (how turns and repo changes ended when not done, by owner)
 //   admin letterpress settings|flip|set …                                             (recipes:read / recipes:write)
+//   admin invariants [--org <id>,…] [--limit N] [--presses]                               (staff)
 //   admin demo guide|list|show|set|reset|check|ideas …                                           (demo:read / demo:write)
 //   admin deployments [--health down|failing|blocked|setting_up|live|paused|archived] [--org <id>] [--q <text>] [--archived] [--test] [--no-host]   (fleet:read)
 //   admin models runs|run|star|unstar|scoreboard|requests|request|sampling …       (models:read / models:write)
@@ -62,7 +63,42 @@ import {
 	compact,
 	ok,
 	requirePositional,
+	argsFromFlags,
 } from "./shared.mjs";
+
+// `admin invariants`: the one tool it calls, its flags declared (scripts/parity-check.ts reads this map).
+export const ARGS = {
+	check_ideas_invariants: {
+		org_ids: { value: (flags) => (flags.org ? flagCsv(flags.org) : undefined) },
+		limit: { flag: "limit", type: "num" },
+		presses: { flag: "presses", type: "bool" },
+	},
+};
+
+const INVARIANT_LIMIT = 30;
+
+// `admin invariants` — the Ideas invariants over production (docs/architecture/ideas-invariants.md), read only:
+// check_ideas_invariants, grouped by invariant with ids. Exits 1 when any holds false.
+async function cmdAdminInvariants(ctx) {
+	const { client, flags, io } = ctx;
+	const result = await client.callTool("check_ideas_invariants", argsFromFlags(ARGS.check_ideas_invariants, flags));
+	printResult(io, flags, result, (r) =>
+		[
+			`${r.total} violation(s) on ${r.accounts} account(s)${r.unread.length ? `, ${r.unread.length} not read` : ""}.`,
+			...r.by_invariant.map((g) =>
+				[
+					`\n${g.invariant}  ${g.count}  (${g.owner})`,
+					...g.violations
+						.slice(0, INVARIANT_LIMIT)
+						.map((v) => `  ${v.host}  ${v.org_id}  ${v.subject}\n    ${v.evidence}`),
+					...(g.count > INVARIANT_LIMIT ? [`  … ${g.count - INVARIANT_LIMIT} more (--json for all)`] : []),
+				].join("\n")
+			),
+			...r.unread.map((u) => `not read: ${u.org_id}: ${u.error}`),
+		].join("\n")
+	);
+	return result.total > 0 ? 1 : 0;
+}
 import { watchDomainJob } from "./onboard.mjs";
 
 const SEER_MODES = ["suggest", "skip"];
@@ -5141,12 +5177,14 @@ const RECIPE_FILE_FIELDS = [
 	"tool_access",
 	"primitives_access",
 	"immediate",
+	// Whether its row must name what it acts on (2026-11-11); left out here, an export would drop it.
+	"names_subject",
 	"status",
 	"needs",
 	"variations",
 ];
 const RECIPES_USAGE =
-	"Usage: admin recipes list [--kind recipe|known_issue] [--status live|parked] [--approach seo|geo|agent_conviction|inbound_conversion|outbound|other] | show <id|name> | runs <id|name> [--days 1..90] [--limit n] | vocab | stats | export [--out <file>] | import <file> [--dry-run] | refit [--org <id>,…] [--recipe <id|name>] [--limit n] | save [<id>] [--file <recipe.json>] [--kind recipe|known_issue] [--name …] [--description …] [--recipe …] [--when-to-use …] [--when-not-to-use …] [--weight 1..10] [--approaches seo,geo,…] [--reads llms_txt,github,…] [--runs <catalog action id>] [--primitives-access true|false] [--immediate true|false] [--status live|parked] [--needs <what a parked recipe is missing>] | delete <id> --yes";
+	"Usage: admin recipes list [--kind recipe|known_issue] [--status live|parked] [--approach seo|geo|agent_conviction|inbound_conversion|outbound|other] | show <id|name> | runs <id|name> [--days 1..90] [--limit n] | vocab | stats | export [--out <file>] | import <file> [--dry-run] | refit [--org <id>,…] [--recipe <id|name>] [--limit n] | save [<id>] [--file <recipe.json>] [--kind recipe|known_issue] [--name …] [--description …] [--recipe …] [--when-to-use …] [--when-not-to-use …] [--weight 1..10] [--approaches seo,geo,…] [--reads llms_txt,github,…] [--runs <catalog action id>] [--primitives-access true|false] [--immediate true|false] [--names-subject true|false] [--status live|parked] [--needs <what a parked recipe is missing>] | delete <id> --yes";
 
 const recipeForFile = (r) => Object.fromEntries(RECIPE_FILE_FIELDS.map((k) => [k, r[k]]));
 
@@ -5196,6 +5234,7 @@ function recipeDetail(r) {
 			: r.primitives_access
 				? ["  letter's tools:   its build may read the account through them (primitives_access)"]
 				: []),
+		...(r.names_subject ? ["  title:            names what it acts on, or it is a no (names_subject)"] : []),
 		...(variations.length > 1
 			? variations.flatMap((v, i) => [`  variation ${i + 1}: ${v.name}`, ...fields(v, "    ")])
 			: fields(r, "  ")),
@@ -5250,6 +5289,8 @@ function recipeFromFlags(flags) {
 			flags["primitives-access"] === undefined ? undefined : String(flags["primitives-access"]) === "true",
 		// --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",
+		// --names-subject true: its row names what it acts on, or is a no; false: it may keep its general name.
+		names_subject: flags["names-subject"] === undefined ? undefined : String(flags["names-subject"]) === "true",
 		// --reads llms_txt,github declares the facts its conditions rest on; --reads "" clears them.
 		reads: flagStr(flags.reads)
 			?.split(",")
@@ -7344,10 +7385,11 @@ export async function cmdAdmin(ctx) {
 	if (sub === "letterpress") return cmdAdminLetterpress({ ...ctx, positionals: ctx.positionals.slice(1) });
 	if (sub === "demo") return cmdAdminDemo({ ...ctx, positionals: ctx.positionals.slice(1) });
 	if (sub === "targets") return cmdAdminTargets({ ...ctx, positionals: ctx.positionals.slice(1) });
+	if (sub === "invariants") return cmdAdminInvariants({ ...ctx, positionals: ctx.positionals.slice(1) });
 	if (sub === "deployments" || sub === "deploys")
 		return cmdAdminDeployments({ ...ctx, positionals: ctx.positionals.slice(1) });
 	throw new CliError(
-		'Usage: admin recipes … | admin letterpress … | admin demo … | admin targets … | admin deployments … | 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 letterpress … | admin demo … | admin targets … | admin invariants … | admin deployments … | 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/build.mjs

@@ -105,6 +105,8 @@ const ARGS = {
 		site_name: "site-name",
 		// --plan-only: answer what it would do and start nothing (--json for the plan to send back).
 		plan_only: { flag: "plan-only", type: "bool" },
+		// --check: read every gate and say whether a press would start it, starting and recording nothing.
+		check: { flag: "check", type: "bool" },
 		// --plan-only always plans what it's given, as /plan does: it was asked for by name.
 		asked_to_plan: { value: (flags) => (flags["plan-only"] ? true : undefined) },
 		// --plan-file <path>: build exactly the plan --plan-only answered.
@@ -281,6 +283,7 @@ async function buildStart(ctx) {
 		"plan-only",
 		"plan-file",
 		"branch",
+		"check",
 		...FILE_FLAGS,
 	]);
 	const files = await attachedFiles(ctx);
@@ -294,6 +297,7 @@ async function buildStart(ctx) {
 				...r.plan.changes.map((c) => `  ${c.title ?? c.instructions}`),
 				...r.plan.actions.map((a) => `  ${a.title}`),
 			].join("\n");
+		if (r.status === "would_start") return r.message ?? "This would start now.";
 		if (r.status !== "started") return r.message ?? r.status;
 		const steps = (r.build?.steps ?? []).map((s) => `  ${s.status}  ${s.title}${s.note ? `: ${s.note}` : ""}`);
 		return [`Started: ${r.build.title}  (${r.build.id})`, ...steps].join("\n");

package/package.json

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