@letterstory/cli 0.176.80 → 0.176.82

package/lib/cli.mjs

@@ -85,7 +85,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.80";
+export const VERSION = "0.176.82";
 
 /** 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;
@@ -119,12 +119,10 @@ export const BOOLEAN_FLAGS = new Set([
 	"keep-key",
 	"delete-key",
 	"keep",
-	// automate add/set: on or off; only identified visitors marked hot leads; run the prompt in a Build sandbox.
+	// automate add/set: on or off; only identified visitors marked hot leads.
 	"on",
 	"off",
 	"hot-leads-only",
-	"sandbox",
-	"no-sandbox",
 	// admin crm prospect-org: start (or retry) the org prepared for the booked call.
 	"start",
 	// site research-builds: run now even when the stored pass is under an hour old.
@@ -566,6 +564,7 @@ Collections (the content engine as a primitive — one door, 'collection run'):
   collection cancel <run-id>
   collection inventory <id>                            Where every piece is; each finished draft's publish-on-its-own time
   collection links <id> [--refresh]                    Internal-link refresh: on/off, posts due (--refresh runs the next batch now)
+  collection mentions <id> --apply                     Apply the add-the-mention suggestions past their review window
   collection delete <id> --yes
 
 Phantomstory (a collection Letter hosts as an independent publication):
@@ -656,25 +655,29 @@ Reviewers:
                                                        and what Letterpress then does
   automate show <automation-id>
   automate add [--template post_new_issues|recommended_actions|competitor_pages|competitor_takes|
-                           competitor_changes|icp_visitors|vc_visitors|plan_updates|weekly_release_notes|monthly_page_refresh]
+                           competitor_changes|icp_visitors|vc_visitors|plan_updates|weekly_release_notes|monthly_page_refresh|
+                           relink_posts|mention_revisions|fix_autopilot|auto_plan] [--letterbase <id>|--host <site>]
                [--name <n>] [--trigger competitor_page|competitor_change|visitor_identified|issue_found|build_suggestion|plan_update|custom|
                            schedule]
                [--prompt <what Letterpress does with each event>] [--slack-channel <C…>] [--instruction <which events>]
                [--event <name>] [--kind post|landing] [--competitor <host>] [--site <host>]
-               [--every <n> --unit hours|days|weeks|months] [--facts <a,b>] [--sandbox] [--recipe <id>]
+               [--every <n> --unit hours|days|weeks|months] [--facts <a,b>] [--recipe <id>]
                [--hot-leads-only] [--per-day <n>] [--backfill all|<YYYY-MM-DD>] [--off]
                                                        Make one (a template fills what you leave out): it starts
                                                        from now (--backfill also runs it on past events, oldest
                                                        first), acts on its own, and posts each event it acts on
                                                        to --slack-channel with its buttons. --trigger schedule
                                                        --every 2 --unit weeks is a recurring one (on the calendar:
-                                                       Monday, the 1st); --sandbox always runs its prompt in a Build
-                                                       sandbox (off, Letterpress decides per event); --facts
+                                                       Monday, the 1st); Letterpress decides per run whether
+                                                       its prompt needs a Build sandbox; --facts
                                                        names what each tick carries (merged_changes, page_reads,
                                                        new_pages_unlinked, striking_queries, losing_pages);
-                                                       --recipe makes a Plan recipe's own
+                                                       --recipe makes a Plan recipe's own; a job Letter runs
+                                                       (relink_posts, mention_revisions: --letterbase;
+                                                       auto_plan: --host; fix_autopilot) is made, or added
+                                                       back where someone removed it, acting as Letter
   automate set <automation-id> [--name <n>] [--instruction <text>] [--prompt <text>] [--slack-channel <C…>|none]
-               [--sandbox|--no-sandbox] [--backfill all|<YYYY-MM-DD>] [--on|--off] ...
+               [--backfill all|<YYYY-MM-DD>] [--on|--off] ...
   automate try [<automation-id>] [--trigger <t> --prompt <text> --instruction <text> ...] [--limit <n>]
                                                        What it would do with the latest events (acts on none)
   automate runs [--automation <id>] [--status acting|acted|skipped|failed|proposed|rejected] [--limit <n>]
@@ -684,6 +687,12 @@ Reviewers:
   automate send <event-name> --title <what happened> [--key <id>] [--url <u>] [--fact k=v ...]
                 [--email <e>] [--person <name>] [--company <c>]
                                                        Send an event from your own systems
+  automate findings [--state new|acted|dismissed|expired] [--automation <id>] [--site <host>] [--page <url>]
+                   [--limit <n>] [--cursor <t>]
+                                                       What the automations noticed: evidence, what it's about,
+                                                       the button that acts on it, and how it ended
+  automate act <finding-id>                            Make the call a finding stores, as you
+  automate dismiss <finding-id> [--reason <why>]       Set a finding aside
   automate remove <automation-id>
   reviewers invite <article-id> --email <e> [--name <n>]
                                                        Invite a guest to review one post

package/lib/commands/automate.mjs

@@ -1,10 +1,10 @@
 // `automate` — Letterpress → Automations (docs/architecture/event-automations.md): an event, read
 // against your filter (--instruction), then done by Letterpress as your prompt (--prompt) says.
-// options / list / show / add / set / try / runs / approve / reject / send / remove, through the
+// options / list / show / add / set / try / runs / approve / reject / send / findings / act / dismiss / remove, through the
 // same tools the app uses. (A letterbase's writing automations are made and paced with `automations`.) `list` also
-// shows the jobs Letter runs for the account (source "letter": internal links, the blog's sync, the site's re-audit,
-// Fix autopilot, add-your-name suggestions, Auto-Plan, and each letterbase's writing automations), each with its
-// scope; `set <id> --on|--off` turns one on or off.
+// shows the jobs Letter runs for the account (source "letter": a letterbase's internal links, its add-your-name
+// suggestions, Fix autopilot, Auto-Plan, and each letterbase's writing automations), each with its scope: changed with
+// `set`, removed with `remove`, and made or added back with `add --template <job> --letterbase <id>|--host <host>`.
 // Same flag/positional/io conventions as posts.mjs — no commander, no color.
 
 import { CliError } from "../client.mjs";
@@ -31,9 +31,15 @@ const TEMPLATES = [
 	"plan_updates",
 	"weekly_release_notes",
 	"monthly_page_refresh",
+	// The jobs Letter runs: one per letterbase (--letterbase), site (--host) or the organization.
+	"relink_posts",
+	"mention_revisions",
+	"fix_autopilot",
+	"auto_plan",
 ];
 const UNITS = ["hours", "days", "weeks", "months"];
 const STATUSES = ["pending", "proposed", "acting", "acted", "answered", "skipped", "failed", "rejected"];
+const FINDING_STATES = ["new", "acted", "dismissed", "expired"];
 
 const triggerParams = {
 	object: {
@@ -50,10 +56,6 @@ const triggerParams = {
 		facts: { flag: "facts", type: "list" },
 	},
 };
-// --sandbox / --no-sandbox: always run the prompt in a Build sandbox (the repo and Letter's tools); off, Letterpress decides per event.
-const sandbox = {
-	value: (flags) => (flags["no-sandbox"] === true ? false : flags.sandbox === true ? true : undefined),
-};
 // --slack-channel C0123ABCD (repo slack-targets), or none to post nothing.
 const slackChannel = {
 	value: (flags) =>
@@ -107,6 +109,16 @@ const destination = {
 	},
 };
 
+// --letterbase <collection-id> or --host <site>: where a job Letter runs runs (its template's scope).
+const scope = {
+	value: (flags) => {
+		const letterbase = flagStr(flags.letterbase);
+		const host = flagStr(flags.host);
+		if (letterbase && host) throw new CliError("Pass --letterbase or --host, not both.");
+		return letterbase ? { collection_id: letterbase } : host ? { host } : undefined;
+	},
+};
+
 export const ARGS = {
 	describe_automation_options: {},
 	list_event_automations: {},
@@ -116,6 +128,7 @@ export const ARGS = {
 	create_event_automation: {
 		destination,
 		template: { flag: "template", enum: TEMPLATES },
+		scope,
 		// --recipe <id>: make the automation a Plan recipe carries (the Plan row's own call).
 		recipe: { flag: "recipe" },
 		name: { flag: "name" },
@@ -124,7 +137,6 @@ export const ARGS = {
 		instruction: { flag: "instruction" },
 		prompt: { flag: "prompt" },
 		slack_channel: slackChannel,
-		sandbox,
 		enabled,
 		backfill,
 	},
@@ -137,7 +149,6 @@ export const ARGS = {
 		instruction: { flag: "instruction" },
 		prompt: { flag: "prompt" },
 		slack_channel: slackChannel,
-		sandbox,
 		enabled,
 		backfill,
 	},
@@ -164,6 +175,29 @@ export const ARGS = {
 		decision: { internal: "approve or reject, from the subcommand" },
 		reason: { flag: "reason" },
 	},
+	// What the automations noticed (docs/architecture/automation-findings.md): read, act on, dismiss.
+	list_findings: {
+		automation_id: { flag: "automation" },
+		state: { flag: "state", enum: FINDING_STATES },
+		about: {
+			object: {
+				host: { flag: "site" },
+				page_url: { flag: "page" },
+				collection_id: { flag: "letterbase" },
+				question: { flag: "question" },
+				target_id: { flag: "target" },
+			},
+		},
+		limit: { flag: "limit", type: "num" },
+		cursor: { flag: "cursor" },
+	},
+	act_on_finding: {
+		finding_id: { positional: 0, label: "finding-id", required: true },
+	},
+	dismiss_finding: {
+		finding_id: { positional: 0, label: "finding-id", required: true },
+		reason: { flag: "reason" },
+	},
 	send_automation_event: {
 		event: { positional: 0, label: "event-name", required: true },
 		key: { flag: "key" },
@@ -207,12 +241,18 @@ export async function cmdAutomate(ctx) {
 			return run(rest, "decide_automation_run", "Rejected.", { decision: "reject" });
 		case "send":
 			return run(rest, "send_automation_event");
+		case "findings":
+			return run(rest, "list_findings");
+		case "act":
+			return run(rest, "act_on_finding", "Done.");
+		case "dismiss":
+			return run(rest, "dismiss_finding", "Dismissed.");
 		case "remove":
 		case "rm":
 			return run(rest, "delete_event_automation", "Removed.");
 		default:
 			throw new CliError(
-				`Unknown automate subcommand: ${sub ?? "(none)"}. Try: options, list, show, add, set, try, runs, approve, reject, send, remove`
+				`Unknown automate subcommand: ${sub ?? "(none)"}. Try: options, list, show, add, set, try, runs, approve, reject, send, findings, act, dismiss, remove`
 			);
 	}
 }

package/lib/commands/collection.mjs

@@ -147,6 +147,9 @@ export const ARGS = {
 	refresh_internal_links: {
 		collection_id: { positional: 0, label: "collection-id", required: true },
 	},
+	apply_mention_suggestions: {
+		collection_id: { positional: 0, label: "collection-id", required: true },
+	},
 };
 
 export async function cmdCollection(ctx) {
@@ -190,9 +193,11 @@ export async function cmdCollection(ctx) {
 			return collectionOverview(rest);
 		case "links":
 			return collectionLinks(rest);
+		case "mentions":
+			return collectionMentions(rest);
 		default:
 			throw new CliError(
-				`Unknown collection subcommand: ${sub ?? "(none)"}. Try: list, overview, new, config, delete, run, add, queue, headline, run-status, runs, approve, move, cancel, inventory, links`
+				`Unknown collection subcommand: ${sub ?? "(none)"}. Try: list, overview, new, config, delete, run, add, queue, headline, run-status, runs, approve, move, cancel, inventory, links, mentions`
 			);
 	}
 }
@@ -470,3 +475,25 @@ async function collectionLinks(ctx) {
 	);
 	return 0;
 }
+
+// `collection mentions <id> --apply` applies the add-the-mention suggestions whose review window has passed: what
+// the collection's "Add your name where AI cites your posts" automation does on each tick.
+async function collectionMentions(ctx) {
+	const { client, flags, positionals, io } = ctx;
+	refuseUnknownFlags(ctx, {}, ["apply"]);
+	if (flags.apply !== true)
+		throw new CliError("Pass --apply to apply the suggestions past their review window (see: suggestions list).");
+	const r = await client.callTool(
+		"apply_mention_suggestions",
+		argsFromFlags(ARGS.apply_mention_suggestions, flags, positionals)
+	);
+	printResult(io, flags, r, (x) =>
+		x.cards.length
+			? [
+					`Applied ${x.applied}, failed ${x.failed}, skipped ${x.skipped}.`,
+					...x.cards.map((c) => `  ${c.title} (${c.posts} posts): ${c.outcome}`),
+				].join("\n")
+			: "Nothing due: no add-the-mention suggestion is past its review window."
+	);
+	return 0;
+}

package/package.json

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