@letterstory/cli 0.136.0 → 0.137.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.137.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
@@ -1494,6 +1500,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.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.137.0",
 	"description": "Spin up and manage Letterstory phantom blogs from your terminal.",
 	"type": "module",
 	"license": "UNLICENSED",