@letterstory/cli 0.31.1 → 0.33.0

package/README.md

@@ -276,6 +276,25 @@ LETTERSTORY_STAFF_API_KEY=<your staff key with org:create> \
 Everything the parent job does is also its own tool for existing orgs:
 `ensure_collection_enhance_flow`, `provision_org_visuals`, `propose_seers` (`--args '{"apply":true}'`).
 
+### Staff: ask the fleet a question
+
+```bash
+# Needs a STAFF key with the fleet:query capability. The answer is derived from
+# read-only SQL across every org -- nothing here can write, and credential columns
+# are unreadable, so this is safe to point at production because it cannot be
+# anything else.
+LETTERSTORY_STAFF_API_KEY=<your staff key with fleet:query> \
+  letterstory admin ask "which writing kernels are hooked up to the most clients?"
+
+# --sql prints every query behind the answer, which is what makes a scripted answer
+# checkable; --json emits the whole result (answer + steps) for a caller that wants
+# the queries as data.
+letterstory admin ask "which clients published nothing in the last 30 days?" --sql
+```
+
+This is the headless half of `/superadmin/ask` — same function, same schema — so a
+long-running agent can watch the fleet on a schedule without a browser.
+
 ### Propose, then onboard a phantom
 
 The Fleet wizard's Plan and Name screens as two commands: pick the beat, then the name,

package/lib/cli.mjs

@@ -24,6 +24,7 @@ import {
 	cmdFlows,
 	cmdConnectors,
 	cmdStrategy,
+	cmdDirectives,
 	cmdProbes,
 	cmdSuggestions,
 	cmdOnboarding,
@@ -44,7 +45,7 @@ import {
 } from "./commands.mjs";
 
 // Keep in sync with cli/package.json.
-export const VERSION = "0.31.1";
+export const VERSION = "0.33.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.
@@ -286,6 +287,10 @@ Strategy & onboarding:
   strategy topics set --collection <uuid> (--topic <topic-id> | --suggestion <suggestion-id>)
   suggestions list <collection_id>                     List pending strategy suggestions + their auto-apply countdown
   suggestions approve | dismiss | snooze <verdict|proposal> <id> [--days <n>]
+  directives list <collection_id>                      What is steering this collection right now
+  directives propose <collection_id> <what you want>   Read one instruction back as concrete levers (applies nothing)
+  directives apply <directive_id> --effect <id>...     Commit the levers you kept (or --reason to decline them all)
+  directives off <directive_id> --reason <why>         Stop a live instruction; the reason is read back by the next proposal
   probes list [--collection <uuid>] [--active-only] [--kind mention|citation|page]
   probes keep | pause | resume <probe_id>              Keep = protect an AI probe from rotation (no pause)
   probes edit <probe_id> <new question text>           Fix/sharpen a generated probe
@@ -463,6 +468,11 @@ Domain onboarding (ONE SHOT: a bare domain in, a fully-configured organization o
   ${bin === "phantom" ? "onboard" : "phantom-onboard"} domain --status  Latest domain onboarding on this org.
 
 Admin (STAFF key — --staff-key / LETTERSTORY_STAFF_API_KEY; acts before an org exists):
+  admin ask "<question>" [--sql] [--json]              Ask the whole fleet a question in English.
+                                                       Answered from the live database with
+                                                       read-only SQL across every org; --sql prints
+                                                       the queries behind the answer. Needs the
+                                                       fleet:query capability on the staff key.
   admin create-org --domain <bare-domain> [--name "Acme"] [--test] [--no-key]
           [--key-name N] [--capabilities a,b] [--onboard] [--watch] [+ the onboard domain flags]
                                                        The key exchange: create the client org from
@@ -640,6 +650,7 @@ const CLIENT_COMMANDS = {
 	flows: cmdFlows,
 	connectors: cmdConnectors,
 	strategy: cmdStrategy,
+	directives: cmdDirectives,
 	probes: cmdProbes,
 	suggestions: cmdSuggestions,
 	onboarding: cmdOnboarding,

package/lib/commands/admin.mjs

@@ -3,6 +3,7 @@
 // (`x-staff-api-key`, minted at Settings → Staff keys) against the superadmin REST
 // routes, because they exist precisely to act BEFORE an org exists.
 //
+//   admin ask "which kernels are hooked up to the most clients?" [--sql] [--json]
 //   admin create-org --domain acme.com [--name "Acme"] [--test] [--no-key] [--key-name N]
 //                    [--capabilities a,b] [--onboard] [--about "…"] [--sitemap <url>]
 //                    [--cms <provider>] [--posts N] [--seers suggest|skip] [--no-visuals]
@@ -17,6 +18,11 @@
 // `phantom-onboard domain --watch` uses. Without --watch, watch it afterwards with
 //   LETTERSTORY_API_KEY=<printed key> letterstory phantom-onboard domain --watch --attach <job-id>
 //
+// `admin ask` is the headless half of /superadmin/ask: the same question, the same
+// function, the same read-only SQL across every org — no browser. That projection is the
+// point rather than a convenience, because a background agent that watches the fleet
+// cannot open a console (AGENTS.md principle 5). Needs a staff key with `fleet:query`.
+//
 // The staff key comes from --staff-key or LETTERSTORY_STAFF_API_KEY; the base URL from the
 // usual --url / LETTERSTORY_API_URL / config resolution.
 
@@ -178,8 +184,47 @@ async function cmdAdminCreateOrg(ctx) {
 	return watchDomainJob({ ...ctx, client: orgClient }, result.job_id);
 }
 
+/**
+ * `admin ask "<question>"` — one fleet question, one answer.
+ *
+ * Prints the prose by default. `--sql` also prints every query behind it, which is
+ * what makes a scripted answer checkable; `--json` emits the whole result for a
+ * caller that wants the steps as data.
+ */
+async function cmdAdminAsk(ctx) {
+	const question = ctx.positionals.join(" ").trim();
+	if (question.length < 3) {
+		throw new CliError('Usage: admin ask "which clients published nothing in the last 30 days?"');
+	}
+
+	const result = await staffPost(ctx, "/api/superadmin/ask", { question });
+
+	if (flagBool(ctx.flags.json)) {
+		printResult(ctx.io, ctx.flags, result);
+		return;
+	}
+
+	// The partial-answer warning goes to stderr, so `admin ask ... > answer.md` still
+	// captures only the answer while a human at a terminal still sees the caveat.
+	if (result.stopped_by && result.stopped_by !== "end_turn") {
+		ctx.io.error(`! Run ended on ${result.stopped_by} — the answer below is partial.`);
+	}
+	ctx.io.log(result.answer || "(no answer)");
+
+	if (flagBool(ctx.flags.sql)) {
+		for (const step of result.steps ?? []) {
+			if (!step.sql) continue;
+			ctx.io.log(`\n-- ${step.tool}${step.ok ? "" : " (failed)"}${step.truncated ? " (truncated)" : ""}`);
+			ctx.io.log(step.sql);
+		}
+	}
+}
+
 export async function cmdAdmin(ctx) {
 	const sub = ctx.positionals[0];
 	if (sub === "create-org") return cmdAdminCreateOrg({ ...ctx, positionals: ctx.positionals.slice(1) });
-	throw new CliError("Usage: admin create-org --domain <bare-domain> [--onboard] … (see --help)");
+	if (sub === "ask") return cmdAdminAsk({ ...ctx, positionals: ctx.positionals.slice(1) });
+	throw new CliError(
+		'Usage: admin create-org --domain <bare-domain> [--onboard] … | admin ask "<question>" (see --help)'
+	);
 }

package/lib/commands/directives.mjs

@@ -0,0 +1,147 @@
+// `directives` — tell one collection what to do, and see what you've already told it.
+//
+// Thin wrappers over the four MCP tools (propose / apply / list / revoke), which
+// call the same lib functions the app's routes do — so a script or an agent gets
+// exactly the sentence-to-levers interpretation a person gets, and reads back the
+// same "what is steering this collection" list.
+//
+// `propose` PERSISTS NOTHING you'd notice: it writes one proposal row nothing
+// consumes and returns the levers, so `--json | jq` is a legitimate way to ask
+// "what would you do?" without doing it. Applying is a second, explicit call.
+
+import { CliError } from "../client.mjs";
+import { flagStr, flagList, requirePositional, printResult, argsFromFlags, ok } from "./shared.mjs";
+
+// How every tool this module calls gets its arguments — see `argsFromFlags` in shared.mjs.
+// `scripts/parity-check.ts` compares these keys against each tool's published input schema.
+export const ARGS = {
+	propose_collection_directive: {
+		collection_id: { positional: 0, label: "collection-id", required: true },
+		// The instruction is the REST of the line, joined — quoting a sentence on a
+		// shell is exactly the friction that makes people type one word instead.
+		text: { value: (_flags, positionals) => positionals.slice(1).join(" ").trim() || undefined },
+	},
+	apply_collection_directive: {
+		directive_id: { positional: 0, label: "directive-id", required: true },
+		accepted_effect_ids: { flag: "effect", type: "list" },
+		rejection_reason: "reason",
+	},
+	list_collection_directives: {
+		collection_id: { positional: 0, label: "collection-id", required: true },
+	},
+	revoke_collection_directive: {
+		directive_id: { positional: 0, label: "directive-id", required: true },
+		reason: { flag: "reason", required: true },
+	},
+};
+
+export async function cmdDirectives(ctx) {
+	const sub = ctx.positionals[0];
+	const rest = { ...ctx, positionals: ctx.positionals.slice(1) };
+	switch (sub) {
+		case "list":
+		case "ls":
+			return directivesList(rest);
+		case "propose":
+			return directivesPropose(rest);
+		case "apply":
+			return directivesApply(rest);
+		case "off":
+		case "revoke":
+			return directivesRevoke(rest);
+		default:
+			throw new CliError("Usage: directives <list|propose|apply|off>");
+	}
+}
+
+function formatEffect(e) {
+	const where = e.clusterName ? ` (${e.clusterName})` : "";
+	const life = e.ongoing ? "keeps applying" : "once";
+	return `  ${e.id}  ${e.label}${where}  [${life}]\n      why: ${e.rationale}`;
+}
+
+async function directivesList(ctx) {
+	const { client, flags, positionals, io } = ctx;
+	const result = await client.callTool(
+		"list_collection_directives",
+		argsFromFlags(ARGS.list_collection_directives, flags, positionals)
+	);
+	printResult(io, flags, result, (r) => {
+		const list = r.directives ?? [];
+		if (!list.length) return "Nothing is steering this collection.";
+		return list
+			.map((d) => {
+				const until = d.expiresAt ? `  stops ${d.expiresAt.slice(0, 10)}` : "";
+				const who = d.decidedBy ? "set by a person" : "set without a person in the loop";
+				const head = `${d.id}  ${d.body}${until}\n    (${who}, ${d.createdAt.slice(0, 10)})`;
+				return [head, ...(d.effects ?? []).map(formatEffect)].join("\n");
+			})
+			.join("\n\n");
+	});
+	return 0;
+}
+
+async function directivesPropose(ctx) {
+	const { client, flags, positionals, io } = ctx;
+	if (!positionals.slice(1).join(" ").trim()) {
+		throw new CliError(
+			"Usage: directives propose <collection-id> <what you want>\n  e.g. directives propose abc-123 focus on the pricing area"
+		);
+	}
+	const result = await client.callTool(
+		"propose_collection_directive",
+		argsFromFlags(ARGS.propose_collection_directive, flags, positionals)
+	);
+	printResult(io, flags, result, (r) => {
+		const p = r.proposal ?? {};
+		const lines = [p.interpretation || p.body, "", `directive: ${p.directiveId}`];
+		for (const e of p.effects ?? []) lines.push(formatEffect(e));
+		if (!(p.effects ?? []).length) lines.push("  (no levers — nothing here we can currently do)");
+		if (p.unsupported) lines.push("", `Can't express: ${p.unsupported}`);
+		for (const s of p.supersedes ?? []) lines.push("", `Accepting turns off: "${s.body}"`);
+		lines.push(
+			"",
+			`Then: directives apply ${p.directiveId} --effect <id> [--effect <id>]`,
+			`  or: directives apply ${p.directiveId} --reason "why none of these"`
+		);
+		return lines.join("\n");
+	});
+	return 0;
+}
+
+async function directivesApply(ctx) {
+	const { client, flags, positionals } = ctx;
+	const args = argsFromFlags(ARGS.apply_collection_directive, flags, positionals);
+	const effects = flagList(flags.effect);
+	// Declining everything is a legitimate answer, but it has to say why — the next
+	// proposal reads the reason back, and one that doesn't is a dismissal.
+	if (!effects.length && !flagStr(flags.reason)) {
+		throw new CliError('Pass --effect <id> to apply one, or --reason "why" to decline the lot.');
+	}
+	args.accepted_effect_ids = effects;
+	const result = await client.callTool("apply_collection_directive", args);
+	const applied = result.applied ?? {};
+	const failed = (applied.results ?? []).filter((r) => !r.ok);
+	if (!effects.length) {
+		ok(ctx, "Noted — we won't suggest that again.");
+	} else if (failed.length) {
+		ok(
+			ctx,
+			`Applied ${effects.length - failed.length}/${effects.length}. ${failed.map((f) => f.detail).join(" ")}`
+		);
+	} else {
+		ok(ctx, `Applied ${effects.length} change${effects.length === 1 ? "" : "s"}.`);
+	}
+	return 0;
+}
+
+async function directivesRevoke(ctx) {
+	const { client, flags, positionals } = ctx;
+	requirePositional(positionals, 0, "directive-id");
+	await client.callTool(
+		"revoke_collection_directive",
+		argsFromFlags(ARGS.revoke_collection_directive, flags, positionals)
+	);
+	ok(ctx, "Turned off.");
+	return 0;
+}

package/lib/commands.mjs

@@ -16,6 +16,7 @@ export * from "./commands/authors.mjs";
 export * from "./commands/flows.mjs";
 export * from "./commands/connectors.mjs";
 export * from "./commands/strategy.mjs";
+export * from "./commands/directives.mjs";
 export * from "./commands/probes.mjs";
 export * from "./commands/series.mjs";
 export * from "./commands/insights.mjs";

package/package.json

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