@letterstory/cli 0.176.87 → 0.176.88

package/lib/cli.mjs

@@ -66,6 +66,7 @@ import {
 	cmdRepo,
 	cmdBuild,
 	cmdAsk,
+	cmdIdeas,
 	cmdPlan,
 	cmdSite,
 	cmdEvals,
@@ -85,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.87";
+export const VERSION = "0.176.88";
 
 /** 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;
@@ -1736,26 +1737,32 @@ Mail:
                                                        (any phone format; country as a name or a 2-letter code)
 
 Insights:
-  ask [<words…>] [--outcome geo|seo|…] [--more] [--lens fix|build] [--site host]
-                                                       Ask Letterpress what to do next: the plan for an outcome (the
-                                                       Plan tab's box), what's broken (--lens fix, most pressing
-                                                       first), what to build (--lens build), or your own words. Nothing asked:
-                                                       each list's head. The same answer as the console and Slack.
+  ideas [--goal all|geo|seo|agent_conviction|inbound_conversion|<strategy-id>] [--count 3|5|all] [--site host]
+                                                       Ideas, as the app lists them: every idea that fits (filtered to a
+                                                       goal, or a goal you typed), the top 3 by default; each with its
+                                                       state (ready, needs you, waiting, PR open, done), what it waits
+                                                       on, why, its steps, and what starting it does.
+  ask [<words…>] [--outcome geo|seo|…] [--strategy <id>] [--more] [--lens fix|build] [--site host]
+                                                       Ask Letterpress what to do next: Ideas for a goal (--outcome, or
+                                                       --strategy for a goal you typed; --more for every idea that fits),
+                                                       what's broken (--lens fix, most pressing first), what to build
+                                                       (--lens build), or your own words. Nothing asked: each list's head.
+                                                       The same answer as the app and Slack.
   plan auto [activate|disable] [--site host] [--veto-hours <1-168>|off] [--pace-hours <1-168>]
             [--delivery build|build_pr|build_merge]
             [--aggression low|medium|high|xhigh] [--strategies geo,seo,agent_conviction,inbound_conversion|any]
             [--slack-channel <C…>|none]
                                                        Auto-Plan on a site: Letterpress picks its strategies and builds
-                                                       them under the site's strategies (--strategies, any by default; the Plan reads the same set); each pick waits --veto-hours for a veto. Settings shown when none given.
+                                                       them under the site's strategies (--strategies, any by default); each pick waits --veto-hours for a veto. Settings shown when none given.
   plan pending [--site host]                           What Auto-Plan picked and is waiting to build
   plan veto <proposal-id>                              Veto one: it is never built
   plan start <proposal-id>                             Start one now (a Needs you pick, or one waiting out its review window)
   plan preview [--site host]                           What Auto-Plan would do first, before it is on
-  plan later <action-id> [--outcome geo|…] [--site host]  Queue a Plan row for later: Auto-Plan starts it once it's ready
+  plan later <action-id> [--outcome geo|…] [--site host]  Queue an idea for later: Auto-Plan starts it once it's ready
   plan later remove <queued-id>                        Take a queued row back off
-  plan strategies [--site host] [--archived]           The goals typed on the Plan, each a strategy
+  plan strategies [--site host] [--archived]           The goals typed on Ideas, each a strategy
   plan strategy add "<words…>" [--site host]           Keep a goal in your words as a strategy
-  plan strategy archive <strategy-id> [--restore]      Put one away (its card leaves the Plan), or bring it back
+  plan strategy archive <strategy-id> [--restore]      Put one away (its goal leaves Ideas), or bring it back
   insights summary [--period …] [--part <block>]...    Measure Overview: AI named/cited rates, share of voice, search, targets
   insights reads [--period …] [--site all|own|phantoms|<key>]... [--path <path>] [--engine <operator>]
                                                        Measure → Reads: AI engines and people reading your sites, counted one way
@@ -2125,6 +2132,7 @@ const CLIENT_COMMANDS = {
 	repo: cmdRepo,
 	build: cmdBuild,
 	ask: cmdAsk,
+	ideas: cmdIdeas,
 	plan: cmdPlan,
 	site: cmdSite,
 	evals: cmdEvals,

package/lib/commands/ask.mjs

@@ -1,11 +1,20 @@
 // `ask` — ask Letterpress, the one door (docs/architecture/one-recipe-engine.md §9b): what should
-// this account do next. The same answer as the console's Plan, Build and Fix tabs and Slack.
+// this account do next. The same answer as Ideas, Build and Fix and Slack.
 //   ask                              → each list's head: what's broken, what to build
-//   ask --outcome geo|seo|…          → the plan for that outcome (Ideas filtered to it); --more: every row that fits
-//   ask --strategy <id>              → a typed strategy's next actions (plan strategies)
+//   ask --outcome geo|seo|…          → Ideas for that goal; --more: every idea that fits
+//   ask --strategy <id>              → a goal you typed (plan strategies), the same door as its words
 //   ask --lens fix | --lens build    → what's broken (most pressing first) | what to build
 //   ask "<words…>"                   → in your own words; what nothing does comes back as unmet
 //   ask "<words…>" --found "<…>"     → with what you read outside the account for them (a case study)
+//
+// `ideas` — Ideas as the app shows it (docs/architecture/plan-strategies.md, "Ideas: one flat list"): every idea that
+// fits, read through the same door with `more`, a goal filter and a count. A projection of ask_letterpress, never a
+// list of its own:
+//   ideas [--goal all|geo|seo|agent_conviction|inbound_conversion|<strategy-id>] [--count 3|5|all] [--site host]
+//
+// Each row is printed as Ideas shows it: its title and state in words (the door's `badge`: ready, needs you,
+// waiting, PR open, done), what it waits on (`waiting`), why, why now, its steps (`detail`), what is queued on it
+// (`queued`) and what starting it does (`start`); never a raw status or a tool's name.
 
 import { CliError } from "../client.mjs";
 import { argsFromFlags, flagStr, printResult, refuseUnknownFlags } from "./shared.mjs";
@@ -13,20 +22,52 @@ import { argsFromFlags, flagStr, printResult, refuseUnknownFlags } from "./share
 export const ARGS = {
 	ask_letterpress: {
 		outcome: "outcome",
-		// --strategy <id>: a typed strategy's next actions (plan strategies), the same door as its words.
+		// --strategy <id>: a goal you typed (plan strategies), the same door as its words.
 		strategy_id: "strategy",
 		lens: "lens",
 		words: { value: (flags, positionals) => flagStr(flags.words) ?? (positionals.join(" ").trim() || undefined) },
 		// --found: what was read outside the account for the words (a case study, a competitor), as findings.
 		found: "found",
-		// --refresh: decide every strategy again from the facts as they are now (the standing fit is read otherwise).
+		// --refresh: decide every idea again from the facts as they are now (the standing fit is read otherwise).
 		refresh: { flag: "refresh", type: "bool" },
-		// --more: every row that fits, not only the top ones (the Ideas list's Show all); alone, Ideas under All.
+		// --more: every idea that fits, not only the top ones (Ideas' All); alone, Ideas under All.
 		more: { flag: "more", type: "bool" },
 		domain: "site",
 	},
 };
 
+/** A row's state in words, as its badge says it; an older server's raw status said the same way. */
+const STATUS_WORDS = { ready: "ready", blocked: "waiting", running: "running", done: "done" };
+
+/** Pure: the lines one item prints as, numbered `n` (1-based), indented under its title. */
+export function ideaLines(item, n) {
+	const pad = "     ";
+	const state = item.badge?.label ?? STATUS_WORDS[item.status] ?? item.status;
+	const lines = [`${String(n).padStart(3)}. ${item.title}  [${state}]`];
+	const waiting = item.waiting ?? (item.blocked_by?.length ? item.blocked_by.join("; ") : null);
+	if (waiting) lines.push(`${pad}Waiting on: ${waiting}`);
+	if (item.why) lines.push(`${pad}${item.why}`);
+	if (item.why_now && item.why_now !== item.why) lines.push(`${pad}Why now: ${item.why_now}`);
+	// What the row does and its steps ("Next: …", "Turns on … in Automations"), as Ideas shows them.
+	if (item.detail && item.detail !== item.why) lines.push(`${pad}${item.detail}`);
+	if (item.queued?.line) lines.push(`${pad}${item.queued.line}`);
+	if (item.start) lines.push(`${pad}${item.start.label}: ${item.start.does}`);
+	else if (item.action && !item.action.callable && item.action.href && item.status === "ready")
+		lines.push(`${pad}Done in the app: ${item.action.href}`);
+	return lines;
+}
+
+/** Pure: an answer's footer: what nothing does, and a first read still under way. */
+function tailLines(r) {
+	const lines = [];
+	if (r.unmet) lines.push(`Not something we do yet: ${r.unmet}`);
+	if (r.status === "pending")
+		lines.push(
+			`Still reading${r.waiting_on?.length ? `: ${r.waiting_on.join("; ")}` : " the site"}. Ask again in a few seconds.`
+		);
+	return lines;
+}
+
 export async function cmdAsk(ctx) {
 	const { client, flags, io } = ctx;
 	refuseUnknownFlags(ctx, {}, ["outcome", "strategy", "lens", "words", "found", "site", "refresh", "more"]);
@@ -34,23 +75,56 @@ export async function cmdAsk(ctx) {
 	if ([args.outcome, args.strategy_id, args.lens, args.words].filter(Boolean).length > 1)
 		throw new CliError("One ask at a time: --outcome, --strategy <id>, --lens fix|build, or your words.");
 	const result = await client.callTool("ask_letterpress", args);
+	printResult(io, flags, result, (r) =>
+		[r.message, ...r.items.flatMap((i, at) => ideaLines(i, at + 1)), ...tailLines(r)].join("\n")
+	);
+	return 0;
+}
+
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+/**
+ * Pure: the ask behind Ideas' goal filter (AccountPlanView `askOfIdeasFilter`): All is the outcome `other`, a goal its
+ * outcome, a typed goal its strategy id; always every idea that fits (`more`), the count is the terminal's to apply.
+ * Which goals exist is the door's to say: a name it doesn't take comes back as its error.
+ */
+export function askOfIdeasGoal(goal) {
+	const g = (goal ?? "all").trim();
+	if (!g || g.toLowerCase() === "all") return { outcome: "other", more: true };
+	if (UUID.test(g)) return { strategy_id: g, more: true };
+	return { outcome: g.toLowerCase().replace(/[\s-]+/g, "_"), more: true };
+}
+
+/** Pure: how many ideas --count shows: 3 (the default), 5, or every one (null). */
+export function ideasCount(count) {
+	const c = flagStr(count)?.trim().toLowerCase();
+	if (c === undefined || c === "" || c === "3") return 3;
+	if (c === "5") return 5;
+	if (c === "all") return null;
+	throw new CliError("--count takes 3, 5 or all.");
+}
+
+export async function cmdIdeas(ctx) {
+	const { client, flags, io } = ctx;
+	refuseUnknownFlags(ctx, {}, ["goal", "count", "site"]);
+	if (ctx.positionals.length)
+		throw new CliError(
+			'ideas takes no words: --goal all|geo|seo|agent_conviction|inbound_conversion|<strategy-id>, --count 3|5|all. For your own words, `ask "<words…>"`.'
+		);
+	const count = ideasCount(flags.count);
+	const site = flagStr(flags.site);
+	const result = await client.callTool("ask_letterpress", {
+		...askOfIdeasGoal(flagStr(flags.goal)),
+		...(site ? { domain: site } : {}),
+	});
 	printResult(io, flags, result, (r) => {
-		const lines = [r.message];
-		for (const i of r.items) {
-			const waits = i.blocked_by?.length ? `  (waits on: ${i.blocked_by.join("; ")})` : "";
-			const how = i.action
-				? i.action.callable
-					? `  → ${i.action.tool}`
-					: i.action.href
-						? `  → ${i.action.href}`
-						: ""
-				: "";
-			lines.push(`  ${i.status.padEnd(7)} ${i.title}${how}${waits}`, `          ${i.why}`);
-			// What the row does and its steps ("Next: …", "Turns on … in Automations"), as Ideas shows them.
-			if (i.detail && i.detail !== i.why) lines.push(`          ${i.detail}`);
-		}
-		if (r.unmet) lines.push(`Not something we do yet: ${r.unmet}`);
-		if (r.status === "pending") lines.push("(reading the site; ask again in a few seconds)");
+		const shown = count === null ? r.items : r.items.slice(0, count);
+		if (!r.items.length)
+			return [r.status === "pending" ? "Coming up with your ideas…" : r.message, ...tailLines(r)].join("\n");
+		const lines = [`Ideas${site ? ` for ${site}` : ""}: ${shown.length} of ${r.items.length}.`];
+		shown.forEach((i, at) => lines.push(...ideaLines(i, at + 1)));
+		if (shown.length < r.items.length) lines.push(`More with --count ${count === 3 ? "5 or --count all" : "all"}.`);
+		lines.push(...tailLines(r));
 		return lines.join("\n");
 	});
 	return 0;

package/lib/commands/plan.mjs

@@ -196,8 +196,10 @@ export async function cmdPlan(ctx) {
 							(p) =>
 								`  ${p.status.padEnd(8)} ${p.title}  ${
 									p.queued_by
-										? `(later${p.waits_on ? `, waits on ${p.waits_on}` : ""})`
-										: `(builds ${p.due_at})`
+										? `(later${p.waits_on ? `: ${p.waits_on}` : ""})`
+										: p.waits_on
+											? "(yours to start)"
+											: `(builds ${p.due_at})`
 								}  ${p.id}`
 						)
 						.join("\n")

package/package.json

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