@letterstory/cli 0.81.1 → 0.82.0

package/lib/cli.mjs

@@ -57,11 +57,12 @@ import {
 } from "./commands.mjs";
 
 // Keep in sync with cli/package.json.
-export const VERSION = "0.81.1";
+export const VERSION = "0.82.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.
-const BOOLEAN_FLAGS = new Set([
+// can't accidentally swallow the id as --json's value. Every `type: "bool"` flag (and its
+// `negate` spelling) in a command's ARGS map must be listed; boolean-flags.test.ts enforces it.
+export const BOOLEAN_FLAGS = new Set([
 	"json",
 	"yes",
 	"confirm-missing-target",
@@ -75,6 +76,7 @@ const BOOLEAN_FLAGS = new Set([
 	"verbose",
 	"no-color",
 	"dry-run",
+	"prune",
 	"buy",
 	"rebuild",
 	"print-key",
@@ -128,8 +130,68 @@ const BOOLEAN_FLAGS = new Set([
 	// `prospects import|source --one-per-company`, `prospects source --enrich`.
 	"one-per-company",
 	"enrich",
-	// `targets update <id> --clear-framing`.
+	// `targets update <id> --clear-framing`; `targets subqueries --retired`,
+	// `targets subquery update <id> --retire` / `--restore`.
 	"clear-framing",
+	"retired",
+	"retire",
+	"restore",
+	// Bool flags from command ARGS maps that were missing here.
+	"apply-rules",
+	"async",
+	"configure",
+	"detect-reply-opt-outs",
+	"experience-claims",
+	"maverick",
+	"no-detect-reply-opt-outs",
+	"no-maverick",
+	"no-notify-staff",
+	"no-opt-out-footer",
+	"no-postal-address-footer",
+	"no-redesign",
+	"no-test-mode",
+	"no-unsubscribe-links",
+	"now",
+	"opt-out-footer",
+	"postal-address-footer",
+	"redesign",
+	"release-mailbox",
+	"rival",
+	"shred",
+	"shred-judge",
+	"shred-skip-voice-bearing",
+	"shred-turnover-avoid-list",
+	"test-mode",
+	"unsubscribe-links",
+	// Switches read directly (`flags["x"] === true` / `flagBool(flags["x"])`) or once read
+	// through `value:` functions.
+	"active-only",
+	"clear-seer",
+	"flag-wrong",
+	"ledger-scope",
+	"lift-budget",
+	"no-configure",
+	"no-produce",
+	"no-publish",
+	"no-rebuild",
+	"null-check",
+	"replied",
+	"sent",
+	"sweep",
+	// Switches read in dot form (`flags.x === true` / `flagBool(flags.x)`).
+	"all",
+	"byok",
+	"clear",
+	"closed",
+	"create",
+	"live",
+	"regrade",
+	"rule",
+	"sql",
+	"steps",
+	"suggested",
+	"sync",
+	"texts",
 ]);
 
 // Tiny argv parser: `--flag value`, `--flag=value`, boolean `--flag`, and positionals.
@@ -380,6 +442,9 @@ Ranking targets (what the org wants to be THE answer for — company-wide or on
   targets cap <offering-id|company> <n|default>        Active targets allowed in that scope (preset 5; default =
                                                        inherit the company's cap / back to the preset)
   targets suggest [--offering <offering-id|company>]   Evidence-informed suggestions (nothing saved)
+  targets subqueries [<target-id>] [--retired]         The phrasings asked under each target (who retired one, and why)
+  targets subquery add <target-id> <phrasing>          Another way your buyers ask a target's question
+  targets subquery update <subquery-id> [--text <t>] [--retire | --restore]
 
 Arenas (adversarial clusters of research agents -> a sourced, fact-checked outline):
   arena run --topic <text> [--source <url> …] [--must-include <text> …] [--depth barebones|fleshed_out]
@@ -929,6 +994,9 @@ Mail:
 
 Insights:
   insights summary [--period …] [--part <block>]...    Measure Overview: AI named/cited rates, share of voice, search, targets
+  insights competitors [--period 14d|30d|90d]          GEO → Competitors: share of mentions per brand, is it moving, by engine/question
+  insights question <key> [--period 14d|30d|90d] [--filter all|named_you|rival_not_you|no_one] [--limit n]
+                                                       One By-question row: the wordings asked and the AI answers
   insights site [--period 14d|30d|90d] [--collection <uuid>]
   insights post <article-id> [--period 14d|30d|90d]
   insights top [--period 14d|30d|90d] [--collection <uuid>] [--limit <n>] [--sort clicks|impressions]

package/lib/commands/authors.mjs

@@ -98,7 +98,7 @@ async function authorsEdit(ctx) {
 		role: flagStr(flags.role),
 		expertise: flagList(flags.expertise),
 		started_at: flagStr(flags["started-at"]),
-		active: flagBool(flags.active),
+		active: flags.active === true || flags.active === "true" ? true : flags.active === "false" ? false : undefined,
 	});
 	if (Object.keys(patch).length <= 2) {
 		throw new CliError(
@@ -156,7 +156,7 @@ async function authorsAssign(ctx) {
 		author_id: authorId,
 		article_ids: all ? undefined : articleIds,
 		all: all ? true : undefined,
-		rebuild: flags["no-rebuild"] ? false : undefined,
+		rebuild: flags["no-rebuild"] === true ? false : undefined,
 	});
 	const result = await client.callTool("assign_collection_authors", args);
 	ok(ctx, authorId ? "Reassigned bylines to the chosen author." : "Auto-distributed bylines across active authors.");

package/lib/commands/collection.mjs

@@ -79,12 +79,12 @@ export const ARGS = {
 		must_include: { flag: "must-include", type: "list" },
 		research_depth: { flag: "depth", enum: ["barebones", "fleshed_out"] },
 		kernel_id: { flag: "kernel" },
-		verify: { value: (flags) => (flags["no-verify"] === true ? false : undefined) },
+		verify: { flag: "no-verify", type: "bool", invert: true },
 		shred: { flag: "shred", type: "bool" },
 		mention_degree: { flag: "mention", enum: ["off", "subtle", "woven"] },
 		approval_mode: { flag: "approval", enum: ["autopilot", "review_window", "manual"] },
-		publish: { value: (flags) => (flags["no-publish"] === true ? false : undefined) },
-		rebuild: { value: (flags) => (flags["no-rebuild"] === true ? false : undefined) },
+		publish: { flag: "no-publish", type: "bool", invert: true },
+		rebuild: { flag: "no-rebuild", type: "bool", invert: true },
 		schedule_for: { flag: "at" },
 	},
 	get_collection_run: {

package/lib/commands/insights.mjs

@@ -27,6 +27,12 @@ export const ARGS = {
 	get_share_of_voice_detail: {
 		period: { flag: "period", enum: PERIODS },
 	},
+	get_share_of_voice_question: {
+		question_key: { positional: 0, label: "question-key", required: true },
+		period: { flag: "period", enum: PERIODS },
+		filter: { flag: "filter", enum: ["all", "named_you", "rival_not_you", "no_one"] },
+		limit: { flag: "limit", type: "num" },
+	},
 };
 
 export async function cmdInsights(ctx) {
@@ -47,9 +53,11 @@ export async function cmdInsights(ctx) {
 			return call(rest, "get_measure_summary");
 		case "competitors":
 			return call(rest, "get_share_of_voice_detail");
+		case "question":
+			return call(rest, "get_share_of_voice_question");
 		default:
 			throw new CliError(
-				`Unknown insights subcommand: ${sub ?? "(none)"}. Try: summary, competitors, site, post, top, bank, access`
+				`Unknown insights subcommand: ${sub ?? "(none)"}. Try: summary, competitors, question, site, post, top, bank, access`
 			);
 	}
 }

package/lib/commands/lede.mjs

@@ -56,7 +56,7 @@ export const ARGS = {
 		// Your own fallback line, returned (unbilled, still no_match) when nothing qualifies.
 		default_lede: { flag: "default-lede" },
 		// Enrichment is ON by default server-side; `--no-enrich` skips it for latency.
-		enrich: { value: (flags) => (flags["no-enrich"] === true ? false : undefined) },
+		enrich: { flag: "no-enrich", type: "bool", invert: true },
 		// A latency budget: optional evidence that cannot arrive in time is left out.
 		deadline_ms: { flag: "deadline-ms", type: "num" },
 		// Advanced: keep specific library lines out of this run (repeatable, by line id).
@@ -75,7 +75,7 @@ export const ARGS = {
 	},
 	// The state of the quality exercise: which evals still count above zero.
 	lede_eval_briefing: {
-		sweep: { value: (flags) => (flags.sweep === true ? true : undefined) },
+		sweep: { flag: "sweep", type: "bool" },
 	},
 	// What has already been said to an account, so the next send does not repeat it.
 	lede_account_history: {
@@ -90,10 +90,10 @@ export const ARGS = {
 	report_lede_outcome: {
 		run_id: { positional: 0, label: "run-id", required: true },
 		shipped_template_id: { flag: "shipped-template" },
-		sent: { value: (flags) => (flags.sent === true ? true : undefined) },
-		replied: { value: (flags) => (flags.replied === true ? true : undefined) },
+		sent: { flag: "sent", type: "bool" },
+		replied: { flag: "replied", type: "bool" },
 		reply_sentiment: { flag: "sentiment", enum: ["positive", "neutral", "negative"] },
-		flagged_wrong: { value: (flags) => (flags["flag-wrong"] === true ? true : undefined) },
+		flagged_wrong: { flag: "flag-wrong", type: "bool" },
 		flagged_reason: { flag: "reason" },
 	},
 	// Per line: picked, sent, replied, positive, flagged wrong.

package/lib/commands/org.mjs

@@ -118,7 +118,7 @@ export function joinBundle(dir) {
 
 async function orgExport(ctx) {
 	const { client, flags, io } = ctx;
-	refuseUnknownFlags(ctx, ARGS, ["split", "file"]);
+	refuseUnknownFlags(ctx, ARGS.export_org_config, ["split", "file"]);
 	const { config } = await client.callTool("export_org_config", argsFromFlags(ARGS.export_org_config, flags));
 	const split = flagStr(flags.split);
 	const file = flagStr(flags.file);
@@ -186,7 +186,7 @@ export function formatPlan(plan) {
 
 async function orgDiff(ctx) {
 	const { client, flags, io } = ctx;
-	refuseUnknownFlags(ctx, ARGS);
+	refuseUnknownFlags(ctx, ARGS.diff_org_config);
 	const { plan } = await client.callTool(
 		"diff_org_config",
 		argsFromFlags(ARGS.diff_org_config, flags, ctx.positionals)
@@ -210,7 +210,7 @@ export function formatApply(result) {
 
 async function orgApply(ctx) {
 	const { client, flags, io } = ctx;
-	refuseUnknownFlags(ctx, ARGS, ["yes"]);
+	refuseUnknownFlags(ctx, ARGS.apply_org_config, ["yes"]);
 	if (flagBool(flags.prune) && !flagBool(flags["dry-run"]) && !flagBool(flags.yes))
 		throw new CliError("--prune deletes records missing from the bundle. Review with --dry-run, then add --yes.");
 	const { result } = await client.callTool(

package/lib/commands/phantom.mjs

@@ -57,7 +57,7 @@ export const ARGS = {
 		theme: "theme",
 		collection_id: { flag: "collection" },
 		customer_ref: { flag: "customer-ref" },
-		configure: { value: (flags) => (flags["no-configure"] === true ? false : undefined) },
+		configure: { flag: "no-configure", type: "bool", invert: true },
 		config: { value: (flags) => readJsonObjectFlag(flags, "config") },
 		composition: { value: (flags) => readJsonObjectFlag(flags, "composition") },
 		client_domain: { flag: "client-domain" },

package/lib/commands/seers.mjs

@@ -39,7 +39,7 @@ export const ARGS = {
 	run_seer: {
 		seer_id: { positional: 0, label: "seer-id", required: true },
 		dry_run: { flag: "dry-run", type: "bool" },
-		produce: { value: (flags) => (flags["no-produce"] === true ? false : undefined) },
+		produce: { flag: "no-produce", type: "bool", invert: true },
 		async: { flag: "async", type: "bool" },
 	},
 	get_seer_run: {

package/lib/commands/targets.mjs

@@ -86,9 +86,35 @@ export const ARGS = {
 		},
 	},
 	suggest_ranking_targets: { offering_id: offering },
+	list_ranking_subqueries: {
+		target_id: { positional: 0, label: "target-id" },
+		include_retired: { flag: "retired", type: "bool" },
+	},
+	add_ranking_subquery: {
+		target_id: { positional: 0, label: "target-id", required: true },
+		// The phrasing is every positional after the target, so it needs no quotes.
+		text: {
+			value: (_flags, positionals) => {
+				const text = positionals.slice(1).join(" ").trim();
+				if (!text) throw new CliError("Missing required <phrasing>");
+				return text;
+			},
+		},
+	},
+	update_ranking_subquery: {
+		subquery_id: { positional: 0, label: "subquery-id", required: true },
+		text: "text",
+		status: {
+			value: (flags) => {
+				if (flags.retire === true && flags.restore === true)
+					throw new CliError("Pass --retire or --restore, not both");
+				return flags.retire === true ? "retired" : flags.restore === true ? "active" : undefined;
+			},
+		},
+	},
 };
 
-const USAGE = `Usage: targets <list|add|update|activate|deactivate|cap|suggest>
+const USAGE = `Usage: targets <list|add|update|activate|deactivate|cap|suggest|subqueries|subquery>
   targets list [--offering <offering-id|company>]
   targets add <phrase> [--framing <f>] [--offering <offering-id|company>] [--priority high|normal|low]
   targets update <target-id> [--phrase <p>] [--framing <f> | --clear-framing] [--offering <offering-id|company>]
@@ -96,7 +122,10 @@ const USAGE = `Usage: targets <list|add|update|activate|deactivate|cap|suggest>
   targets activate <target-id>
   targets deactivate <target-id>
   targets cap <offering-id|company> <n|default>
-  targets suggest [--offering <offering-id|company>]`;
+  targets suggest [--offering <offering-id|company>]
+  targets subqueries [<target-id>] [--retired]            the phrasings asked under each target
+  targets subquery add <target-id> <phrasing>
+  targets subquery update <subquery-id> [--text <t>] [--retire | --restore]`;
 
 export async function cmdTargets(ctx) {
 	const sub = ctx.positionals[0];
@@ -117,6 +146,10 @@ export async function cmdTargets(ctx) {
 			return targetsCap(rest);
 		case "suggest":
 			return targetsSuggest(rest);
+		case "subqueries":
+			return subqueriesList(rest);
+		case "subquery":
+			return subqueryWrite(rest);
 		default:
 			throw new CliError(USAGE);
 	}
@@ -239,3 +272,56 @@ async function targetsSuggest(ctx) {
 	});
 	return 0;
 }
+
+function formatSubquery(q) {
+	const who = q.source === "user" ? "  (yours)" : "";
+	const retired = q.status === "retired" ? `  [retired by ${q.retired_by ?? "?"}: ${q.retired_reason ?? ""}]` : "";
+	return `  ${q.id}  ${q.text}${who}${retired}`;
+}
+
+async function subqueriesList(ctx) {
+	const { client, flags, positionals, io } = ctx;
+	const result = await client.callTool(
+		"list_ranking_subqueries",
+		argsFromFlags(ARGS.list_ranking_subqueries, flags, positionals)
+	);
+	printResult(io, flags, result, (r) => {
+		const items = r.items ?? [];
+		if (!items.length)
+			return "No phrasings yet — the next GEO cycle proposes them, or add one: targets subquery add";
+		const byTarget = new Map();
+		for (const q of items) byTarget.set(q.target_id, [...(byTarget.get(q.target_id) ?? []), q]);
+		return [...byTarget]
+			.map(([target, qs]) => [`Target ${target}`, ...qs.map(formatSubquery)].join("\n"))
+			.join("\n\n");
+	});
+	return 0;
+}
+
+// `subquery add <target-id> <phrasing>` / `subquery update <subquery-id> [--text] [--retire|--restore]`
+async function subqueryWrite(ctx) {
+	const { client, flags, io } = ctx;
+	const action = ctx.positionals[0];
+	const positionals = ctx.positionals.slice(1);
+	if (action === "add") {
+		refuseUnknownFlags(ctx, ARGS.add_ranking_subquery);
+		const result = await client.callTool(
+			"add_ranking_subquery",
+			argsFromFlags(ARGS.add_ranking_subquery, flags, positionals)
+		);
+		ok(ctx, "Added — it is asked from the next GEO cycle.");
+		printResult(io, flags, result, (r) => formatSubquery(r.subquery));
+		return 0;
+	}
+	if (action === "update") {
+		refuseUnknownFlags(ctx, ARGS.update_ranking_subquery, ["retire", "restore"]);
+		const args = argsFromFlags(ARGS.update_ranking_subquery, flags, positionals);
+		if (Object.keys(args).length === 1)
+			throw new CliError("Nothing to update — pass --text, --retire or --restore.");
+		const result = await client.callTool("update_ranking_subquery", args);
+		ok(ctx, `Saved — ${result.subquery?.status}.`);
+		printResult(io, flags, result, (r) => formatSubquery(r.subquery));
+		return 0;
+	}
+	throw new CliError(USAGE);
+}

package/package.json

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