@letterstory/cli 0.136.0 → 0.138.0

package/lib/cli.mjs

@@ -57,12 +57,13 @@ import {
 	cmdEvals,
 	cmdOfferings,
 	cmdEnclosures,
+	cmdCampaigns,
 	cmdTargets,
 	cmdVisits,
 } from "./commands.mjs";
 
 // Keep in sync with cli/package.json.
-export const VERSION = "0.136.0";
+export const VERSION = "0.138.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. Every `type: "bool"` flag (and its
@@ -568,6 +569,11 @@ Enclosures (pictures, clips and sentences made for each prospect; each output is
   enclosures apps connect <sign-in-url> [--no-remember] A sign-in link a person opens (no password passes through)
   enclosures apps disconnect <app-id> --yes            Remove it here and at the browser provider
 
+Campaigns (one prompt, and Letter's agent builds the whole cold-email campaign; nothing sends until you approve):
+  campaigns build "<prompt>" [--limit <n>] [--watch]   The list, the picture (tested on 3), the email, the review desk
+  campaigns show <build-id> [--watch]                   Its stage, what it built, and what it is doing
+  campaigns list | cancel <build-id> | suggest          Its builds; stop one (what it built is kept); three to build
+
 Offerings (context layered org → offering → collection; a layer sets only what it overrides):
   offerings list                                       The org's offerings (things you'd name when recommending them)
   offerings show <offering-id>                         One offering + its competitor overrides
@@ -1323,6 +1329,7 @@ Insights:
   insights reads [--period …] [--site all|own|phantoms|<key>]... [--path <path>] [--engine <operator>]
                                                        Measure → Reads: AI engines and people reading your sites, counted one way
   insights questions [--period 14d|30d|90d]            Measure → Questions: every question we ask, named / share / change / cited
+  insights pages [--period 14d|30d|90d] [--site own|phantoms|<key>]  Measure → Pages: your pages AI answers cited, won questions first
   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
@@ -1395,6 +1402,9 @@ Repo changes (Claude Code edits your repo in a sandbox; the Letterstory GitHub A
   repo install-letterprove --repo <owner/name> [--branch <base>] [--action build|build_pr|build_merge|slack|linear] [--wait]
                                                        One PR adding Letterprove's script and identify calls
                                                        (pick the repo where users sign in)
+  repo install-visitors [--site <id>] [--repo <owner/name>] [--branch <base>] [--action build|build_pr|build_merge|slack|linear] [--wait]
+                                                       One PR adding the Visitors script tag to the repo that
+                                                       builds the site (--repo: another repo)
   repo sites [--detect [--force]]                      Which website each repo builds, and the evidence
   repo set-site --repo <owner/name> --site <host> [--not] [--branch <name>|none]
                                                        Say which site a repo builds (--not: correct a wrong label)
@@ -1408,7 +1418,7 @@ Repo changes (Claude Code edits your repo in a sandbox; the Letterstory GitHub A
   repo status <run-id>                                 Phase, spend, PR link and Claude's summary
   repo activity <run-id> [--follow]                    What the sandbox is doing, line by line (--follow: until it stops)
   repo list [--status running|succeeded|no_changes|failed|cancelled] [--limit n] [--audit <id>]
-             [--source site_audit_issue|site_quick_check|letterprove_install]
+             [--source site_audit_issue|site_quick_check|letterprove_install|visitors_install]
   repo publish <run-id>                                Make PR on a preview in review
   repo revise <run-id> --instructions <text>|--instructions-file <path|->
                                                        Ask for more on a preview; it takes over the preview's link
@@ -1494,6 +1504,7 @@ const CLIENT_COMMANDS = {
 	directives: cmdDirectives,
 	offerings: cmdOfferings,
 	enclosures: cmdEnclosures,
+	campaigns: cmdCampaigns,
 	targets: cmdTargets,
 	probes: cmdProbes,
 	suggestions: cmdSuggestions,

package/lib/commands/campaigns.mjs

@@ -0,0 +1,159 @@
+// `campaigns` — one prompt, and Letter's agent builds the whole cold-email campaign: the list, the
+// enclosure (tested on 3 and chosen), the sequence email that carries each person's picture, and
+// the launch into review. Thin wrappers over the campaign build tools, which call the same
+// functions the app's /api/campaign-builds routes do.
+
+import { CliError } from "../client.mjs";
+import { argsFromFlags, flagNum, pollUntil, printResult, refuseUnknownFlags, 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 = {
+	build_campaign: {
+		prompt: {
+			value: (_flags, positionals) => {
+				const words = positionals.join(" ").trim();
+				if (!words)
+					throw new CliError(
+						'Say what to build, e.g. campaigns build "Cold-email 10 SaaS founders with an audit of their own site"'
+					);
+				return words;
+			},
+		},
+		people_limit: { flag: "limit", type: "num" },
+	},
+	get_campaign_build: { build_id: { positional: 0, label: "build-id", required: true } },
+	list_campaign_builds: { limit: { flag: "limit", type: "num" } },
+	cancel_campaign_build: { build_id: { positional: 0, label: "build-id", required: true } },
+	suggest_campaigns: {},
+};
+
+const USAGE = `Usage:
+  campaigns build "<prompt>" [--limit <n>] [--watch]   Build a whole campaign from one prompt (at most 50 people)
+  campaigns show <build-id> [--watch]                   Its stage, what it built, and what it is doing
+  campaigns list [--limit <n>]                          This org's builds, newest first
+  campaigns cancel <build-id>                           Stop it; what it built is kept
+  campaigns suggest                                     Three campaigns to build in one step`;
+
+const STAGES = { who: "Who", picture: "The picture", test: "Tested on 3", email: "The email", desk: "On the desk" };
+
+export async function cmdCampaigns(ctx) {
+	const sub = ctx.positionals[0];
+	const rest = { ...ctx, positionals: ctx.positionals.slice(1) };
+	switch (sub) {
+		case "build":
+			return campaignsBuild(rest);
+		case "show":
+		case "get":
+			return campaignsShow(rest);
+		case "list":
+		case "ls":
+			return campaignsList(rest);
+		case "cancel":
+			return campaignsCancel(rest);
+		case "suggest":
+			return campaignsSuggest(rest);
+		default:
+			throw new CliError(USAGE);
+	}
+}
+
+function formatBuild(b) {
+	const a = b.artifacts ?? {};
+	const lines = [`${b.id}  [${b.status}, ${STAGES[b.stage] ?? b.stage}]  ${b.prompt}`];
+	if (a.list)
+		lines.push(
+			`  who: ${a.list.people} people on "${a.list.name}"${a.list.pulling ? " (still finding them)" : ""}`
+		);
+	if (a.enclosure) {
+		const p = a.enclosure.prints ?? {};
+		lines.push(
+			`  picture: ${a.enclosure.name}${a.enclosure.current_version ? `, version ${a.enclosure.current_version}` : ", testing"}: ${p.done ?? 0} ready, ${p.making ?? 0} making, ${p.no_fit ?? 0} no fit, ${p.failed ?? 0} failed`
+		);
+	}
+	if (a.sequence) lines.push(`  email: ${a.sequence.name} [${a.sequence.status}]`);
+	if (a.desk)
+		lines.push(
+			`  desk: ${a.desk.waiting} copies waiting (${a.desk.with_picture} with their picture), ${a.desk.on_the_way} on the way`
+		);
+	lines.push(`  spent: $${Number(b.cost_usd).toFixed(2)} of $${Number(b.budget_usd).toFixed(2)}`);
+	if (b.summary) lines.push(`  ${b.summary}`);
+	if (b.error) lines.push(`  ${b.error}`);
+	return lines.join("\n");
+}
+
+const formatLine = (l) => `${l.at.slice(11, 19)}  ${l.kind === "say" ? "" : `${l.kind}: `}${l.text}`;
+
+// Follow a build: print each new activity line as it lands, until it stops.
+async function follow(ctx, buildId) {
+	const { client, io } = ctx;
+	let shown = 0;
+	return pollUntil(
+		io,
+		async () => {
+			const { build } = await client.callTool("get_campaign_build", { build_id: buildId });
+			const lines = build.activity ?? [];
+			for (const line of lines.slice(shown)) io.log(formatLine(line));
+			shown = Math.max(shown, lines.length);
+			return { done: build.status !== "running", value: build };
+		},
+		{ intervalMs: 5000, timeoutMs: 60 * 60_000, label: "the campaign build" }
+	);
+}
+
+async function campaignsBuild(ctx) {
+	const { client, flags, positionals, io } = ctx;
+	refuseUnknownFlags(ctx, ARGS.build_campaign, ["watch"]);
+	if (flags.limit !== undefined) flagNum(flags.limit);
+	const result = await client.callTool("build_campaign", argsFromFlags(ARGS.build_campaign, flags, positionals));
+	ok(ctx, `Building it (${result.build.id}). It takes 10 to 20 minutes; nothing sends until you approve a copy.`);
+	const build = flags.watch === true && !flags.json ? await follow(ctx, result.build.id) : result.build;
+	printResult(io, flags, flags.watch === true ? { build } : result, (r) => formatBuild(r.build));
+	return 0;
+}
+
+async function campaignsShow(ctx) {
+	const { client, flags, positionals, io } = ctx;
+	refuseUnknownFlags(ctx, ARGS.get_campaign_build, ["watch"]);
+	const args = argsFromFlags(ARGS.get_campaign_build, flags, positionals);
+	if (flags.watch === true && !flags.json) {
+		const build = await follow(ctx, args.build_id);
+		io.log(formatBuild(build));
+		return 0;
+	}
+	const result = await client.callTool("get_campaign_build", args);
+	printResult(io, flags, result, (r) =>
+		[formatBuild(r.build), ...(r.build.activity ?? []).slice(-15).map(formatLine)].join("\n")
+	);
+	return 0;
+}
+
+async function campaignsList(ctx) {
+	const { client, flags, io } = ctx;
+	if (flags.limit !== undefined) flagNum(flags.limit);
+	const result = await client.callTool("list_campaign_builds", argsFromFlags(ARGS.list_campaign_builds, flags));
+	printResult(io, flags, result, (r) =>
+		r.builds?.length ? r.builds.map(formatBuild).join("\n\n") : "No campaign builds yet."
+	);
+	return 0;
+}
+
+async function campaignsCancel(ctx) {
+	const { client, flags, positionals, io } = ctx;
+	const result = await client.callTool(
+		"cancel_campaign_build",
+		argsFromFlags(ARGS.cancel_campaign_build, flags, positionals)
+	);
+	ok(ctx, "Stopped. What it built is kept.");
+	printResult(io, flags, result, (r) => formatBuild(r.build));
+	return 0;
+}
+
+async function campaignsSuggest(ctx) {
+	const { client, flags, io } = ctx;
+	const result = await client.callTool("suggest_campaigns", {});
+	printResult(io, flags, result, (r) =>
+		(r.suggestions ?? []).map((s) => `${s.title}\n  letterstory campaigns build "${s.prompt}"`).join("\n\n")
+	);
+	return 0;
+}

package/lib/commands/insights.mjs

@@ -2,7 +2,7 @@
 // network, single-post, and top-posts levels (ported from phantomstory-cli's
 // insights.ts); plus Measure's Overview (`summary`), GEO → Competitors
 // (`competitors`), AI Visibility Bank (`bank`) and phantom Page Access (`access`);
-// Measure → Reads (`reads`) and Questions (`questions`), and the live feed of what
+// Measure → Reads (`reads`), Questions (`questions`) and Pages (`pages`), and the live feed of what
 // is reading the phantom sites (`activity`) — the same reads the web app renders.
 
 import { CliError } from "../client.mjs";
@@ -38,6 +38,10 @@ export const ARGS = {
 	list_measure_questions: {
 		period: { flag: "period", enum: PERIODS },
 	},
+	list_cited_pages: {
+		period: { flag: "period", enum: PERIODS },
+		sites: { flag: "site", type: "list" },
+	},
 	get_recent_activity: {
 		phantom_id: { flag: "phantom" },
 		limit: { flag: "limit", type: "num" },
@@ -76,11 +80,13 @@ export async function cmdInsights(ctx) {
 			return call(rest, "get_reads");
 		case "questions":
 			return call(rest, "list_measure_questions");
+		case "pages":
+			return call(rest, "list_cited_pages");
 		case "activity":
 			return call(rest, "get_recent_activity");
 		default:
 			throw new CliError(
-				`Unknown insights subcommand: ${sub ?? "(none)"}. Try: summary, reads, questions, competitors, question, detection, activity, site, post, top, bank, access`
+				`Unknown insights subcommand: ${sub ?? "(none)"}. Try: summary, reads, questions, pages, competitors, question, detection, activity, site, post, top, bank, access`
 			);
 	}
 }

package/lib/commands/repo.mjs

@@ -8,6 +8,7 @@
 //   repo repos   → list_github_app_repos  repo branches → list_repo_branches
 //   repo prs     → list_open_pull_requests (every open PR, whoever opened it)
 //   repo install-letterprove → letterprove_open_install_pr
+//   repo install-visitors → visitors_open_install_pr
 //   repo secrets → list_repo_preview_secrets  repo set-secret → set_repo_preview_secret
 //   repo delete-secret → delete_repo_preview_secret
 //   repo suggestions → list_suggested_fixes
@@ -117,6 +118,13 @@ const ARGS = {
 		base_branch: "branch",
 		action: { flag: "action", enum: ["build", "build_pr", "build_merge", "slack", "linear"] },
 	},
+	visitors_open_install_pr: {
+		site_id: "site",
+		repo_owner: { value: (flags) => splitRepo(flags).owner },
+		repo_name: { value: (flags) => splitRepo(flags).name },
+		base_branch: "branch",
+		action: { flag: "action", enum: ["build", "build_pr", "build_merge", "slack", "linear"] },
+	},
 	get_repo_change_settings: {},
 	list_suggested_fixes: {},
 	list_slack_fix_targets: {},
@@ -187,7 +195,13 @@ const ARGS = {
 		audit_id: "audit",
 		source_kind: {
 			flag: "source",
-			enum: ["site_audit_issue", "site_quick_check", "letterprove_install", "collection_publish"],
+			enum: [
+				"site_audit_issue",
+				"site_quick_check",
+				"letterprove_install",
+				"visitors_install",
+				"collection_publish",
+			],
 		},
 		site_host: "site",
 	},
@@ -247,6 +261,8 @@ export async function cmdRepo(ctx) {
 			return repoFixAudit(rest);
 		case "install-letterprove":
 			return repoInstallLetterprove(rest);
+		case "install-visitors":
+			return repoInstallVisitors(rest);
 		case "sites":
 			return repoSites(rest);
 		case "set-site":
@@ -283,7 +299,7 @@ export async function cmdRepo(ctx) {
 			return repoSlackTest(rest);
 		default:
 			throw new CliError(
-				`Unknown repo subcommand: ${sub ?? "(none)"}. Try: start, fix-audit, install-letterprove, sites, set-site, reset-site, secrets, set-secret, delete-secret, status, list, publish, cancel, repos, branches, prs, settings, suggestions, slack-targets, slack-test`
+				`Unknown repo subcommand: ${sub ?? "(none)"}. Try: start, fix-audit, install-letterprove, install-visitors, sites, set-site, reset-site, secrets, set-secret, delete-secret, status, list, publish, cancel, repos, branches, prs, settings, suggestions, slack-targets, slack-test`
 			);
 	}
 }
@@ -434,6 +450,22 @@ async function repoInstallLetterprove(ctx) {
 	return followRun(ctx, result.run);
 }
 
+/** `repo install-visitors [--site id] [--repo owner/name] [--branch b] [--wait]`: the Visitors script tag → one PR. */
+async function repoInstallVisitors(ctx) {
+	const { client, flags, io } = ctx;
+	refuseUnknownFlags(ctx, {}, ["site", "repo", "owner", "name", "branch", "action", "wait"]);
+	const result = await client.callTool(
+		"visitors_open_install_pr",
+		argsFromFlags(ARGS.visitors_open_install_pr, flags, ctx.positionals)
+	);
+	ok(ctx, result.message);
+	if (!flags.wait) {
+		printResult(io, flags, result.run, describe);
+		return 0;
+	}
+	return followRun(ctx, result.run);
+}
+
 /** `repo sites [--detect] [--force]`: which website each repo builds, and why. */
 async function repoSites(ctx) {
 	const { client, flags, io } = ctx;

package/lib/commands.mjs

@@ -39,6 +39,7 @@ export * from "./commands/landings.mjs";
 export * from "./commands/outbound.mjs";
 export * from "./commands/offerings.mjs";
 export * from "./commands/enclosures.mjs";
+export * from "./commands/campaigns.mjs";
 export * from "./commands/targets.mjs";
 export * from "./commands/admin.mjs";
 export * from "./commands/feedback.mjs";

package/package.json

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