@letterstory/cli 0.125.0 → 0.126.1

package/lib/cli.mjs

@@ -56,12 +56,13 @@ import {
 	cmdSite,
 	cmdEvals,
 	cmdOfferings,
+	cmdEnclosures,
 	cmdTargets,
 	cmdVisits,
 } from "./commands.mjs";
 
 // Keep in sync with cli/package.json.
-export const VERSION = "0.125.0";
+export const VERSION = "0.126.1";
 
 // 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
@@ -72,6 +73,13 @@ export const BOOLEAN_FLAGS = new Set([
 	"starred",
 	// shredder file / arena file: save the version as a candidate beside live.
 	"candidate",
+	// enclosures create/update: what it needs, and the AI-edited label.
+	"browser",
+	"image-model",
+	"record",
+	"stealth",
+	"disclosure",
+	"no-disclosure",
 	// site tree: include children a fold-by-default family would hide; items over the whole subtree.
 	"unfold",
 	"subtree",
@@ -96,6 +104,7 @@ export const BOOLEAN_FLAGS = new Set([
 	"own-beat",
 	"refresh",
 	"preview",
+	"with-preview",
 	"accept",
 	"help",
 	"version",
@@ -523,6 +532,14 @@ Strategy & onboarding:
   directives apply <directive_id> --effect <id>...     Commit the levers you kept (or --reason to decline them all)
   directives off <directive_id> --reason <why>         Stop a live instruction; the reason is read back by the next proposal
 
+Enclosures (pictures, clips and sentences made for each prospect; each output is a Prospects column):
+  enclosures list                                      The org's enclosures with print counts
+  enclosures show <enclosure-id>                       One enclosure + its versions
+  enclosures create --name <n> --output key:shape:Label… [--instructions <text>] [--input website…] [--browser]
+                    [--login <app-connection-id>] [--tool run_site_audit…] [--skip-when <sentence>]
+  enclosures update <enclosure-id> [same flags]        Outputs are fixed once a version is in use
+  enclosures prints <enclosure-id> [--status <s>]      Its current prints, newest first
+
 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
@@ -885,6 +902,8 @@ Admin (STAFF key — --staff-key / LETTERSTORY_STAFF_API_KEY; acts before an org
           | renewals [--days 90]
           | reach-outs [--day YYYY-MM-DD] [--fresh]   the day's reach-outs, N of 5 (#crm-reminders' count)
           | track-record [--since YYYY-MM-DD] | at-risk | expansion-signals
+          | collections [--org-ids a,b | --account-stages won,active]
+          | delivery-flags [--org-ids a,b | --account-stages won,active] [--include collections]
           | case <account-id> [--outcome <outcome-id>]
           | onboard <account-id> --domain acme.com [--name "Acme"] [--site "<direction>"]… [--sites N]
                    [--slack a@acme.com,b@acme.com] [--invite a@acme.com[:admin]]… [--no-checklist]
@@ -1312,8 +1331,9 @@ Repo changes (Claude Code edits your repo in a sandbox; the Letterstory GitHub A
   repo slack-test                                      Post a test into the Send to Slack channel
   repo start --repo <owner/name> --instructions <text>|--instructions-file <path|->
              [--branch <base>] [--attach <path>]... [--attach-url <name>=<https url>]...
-             [--action build|build_pr|build_merge|slack|linear] [--wait]
+             [--action build|build_pr|build_merge|slack|linear] [--with-preview] [--wait]
                                                        Start a change (attached files go to the sandbox);
+                                                       --with-preview keeps a preview up next to the PR;
                                                        --wait follows it to the PR
   repo fix-audit --issue <issue-type>... [--audit <id>] [--branch <base>] [--action build|build_pr|build_merge|slack|linear] [--wait]
                                                        One PR fixing site-audit issues (repeat --issue to bundle) on every affected page,
@@ -1417,6 +1437,7 @@ const CLIENT_COMMANDS = {
 	strategy: cmdStrategy,
 	directives: cmdDirectives,
 	offerings: cmdOfferings,
+	enclosures: cmdEnclosures,
 	targets: cmdTargets,
 	probes: cmdProbes,
 	suggestions: cmdSuggestions,

package/lib/commands/admin.mjs

@@ -14,7 +14,7 @@
 //      The old names — evals, eval-add, eval-set, proposals, propose-eval, capture-eval, reject-eval — still work.)
 //   admin evals scoreboard|cases|runs|run|triage|guard|retire …                      (fleet:read / tuning:experiment)
 //   admin fleet-experiments list|articles|clients|mark|unmark|new|assign|assign-eligible|assign-orgs|spin-up|apply|start|stop|decide …  (fleet:read / fleet:experiment)
-//   admin crm import|capture|outreach|signals|record|signal|accounts|account|score|slack-channels|link-slack|white-glove|set-white-glove|churn|revenue|reach-outs|record-churn|draft-churn-reason|undo-churn|outcomes|record-outcome|renewals|track-record|at-risk|expansion-signals|case|onboard|onboarding|retry-onboarding|onboard-plan|payment-link …  (crm:read / crm:write)
+//   admin crm import|capture|outreach|signals|record|signal|accounts|account|score|slack-channels|link-slack|white-glove|set-white-glove|churn|revenue|reach-outs|record-churn|draft-churn-reason|undo-churn|outcomes|record-outcome|renewals|track-record|at-risk|expansion-signals|collections|delivery-flags|case|onboard|onboarding|retry-onboarding|onboard-plan|payment-link …  (crm:read / crm:write)
 //   admin spend summary|reconcile|pnl|entries|add|import|usage|remove|reference|stripe-sync|services|service …  (spend:read / spend:write)
 //   admin brand-detection <org-id>                                                   (fleet:read)
 //   admin brand-detection <org-id> [--term t]... [--exact t]... [--exclude p]... [--note "…"] | --clear [--note "…"]   (fleet:instrument)
@@ -3572,6 +3572,46 @@ async function cmdAdminCrm(ctx) {
 					: "(no next-product verdicts)"
 			);
 		}
+		case "collections": {
+			// admin crm collections [--org-ids a,b | --account-stages won,active] — what we publish for each client.
+			const params = new URLSearchParams(
+				compact({ org_ids: flagStr(flags["org-ids"]), account_stages: flagStr(flags["account-stages"]) })
+			);
+			return out(await staffRequest(ctx, "GET", `${CRM}/collections?${params}`), (r) =>
+				r.orgs.length
+					? r.orgs
+							.map(
+								(o) =>
+									`${o.orgName}  ${o.phantomCount} phantom · ${o.mainBlogCount} blog · ${o.postsLast30d} posts in 30d${o.internal.value ? `  (${o.internal.label ?? o.internal.source})` : ""}${o.issues.length ? `  ${o.issues.map((i) => i.message).join("; ")}` : ""}  ${o.orgId}`
+							)
+							.join("\n")
+					: "(no org with a collection in that scope)"
+			);
+		}
+		case "delivery-flags": {
+			// admin crm delivery-flags [--org-ids a,b | --account-stages won,active] [--include collections]
+			// — does what we spend on a client match what they pay? Findings per org, worst first.
+			const params = new URLSearchParams(
+				compact({
+					org_ids: flagStr(flags["org-ids"]),
+					account_stages: flagStr(flags["account-stages"]),
+					include: flagStr(flags.include),
+				})
+			);
+			return out(await staffRequest(ctx, "GET", `${CRM}/delivery-flags?${params}`), (r) => {
+				if (!r.accounts)
+					return "Billing cannot say who pays yet, so there are no flags (collections are in --json).";
+				const flagged = r.accounts.filter((a) => a.findings.length);
+				return flagged.length
+					? flagged
+							.map(
+								(a) =>
+									`${a.owedDelivery ? "owed  " : a.notPaying ? "unpaid" : "      "}  ${a.orgName}  ${a.findings.map((f) => f.message).join("; ")}  ${a.orgId}`
+							)
+							.join("\n")
+					: `(${r.accounts.length} org${r.accounts.length === 1 ? "" : "s"}, nothing flagged)`;
+			});
+		}
 		case "case": {
 			// admin crm case <account-id> [--outcome <id>] — the 90 days before an outcome, or before today.
 			if (!id) throw new CliError("Usage: admin crm case <account-id> [--outcome <outcome-id>]");
@@ -3650,7 +3690,7 @@ async function cmdAdminCrm(ctx) {
 		}
 		default:
 			throw new CliError(
-				"Usage: admin crm import|capture|outreach|signals|record|signal|accounts|account|score|slack-channels|link-slack|white-glove|set-white-glove|churn|revenue|reach-outs|record-churn|draft-churn-reason|undo-churn|outcomes|record-outcome|renewals|track-record|at-risk|expansion-signals|case|onboard|onboarding|retry-onboarding|onboard-plan|payment-link … (see --help)"
+				"Usage: admin crm import|capture|outreach|signals|record|signal|accounts|account|score|slack-channels|link-slack|white-glove|set-white-glove|churn|revenue|reach-outs|record-churn|draft-churn-reason|undo-churn|outcomes|record-outcome|renewals|track-record|at-risk|expansion-signals|collections|delivery-flags|case|onboard|onboarding|retry-onboarding|onboard-plan|payment-link … (see --help)"
 			);
 	}
 }

package/lib/commands/enclosures.mjs

@@ -0,0 +1,210 @@
+// `enclosures` — pictures, clips and sentences made for each prospect (generated
+// prospect columns). Each output IS a Prospects column that sequence emails read as
+// {{custom:<key>}}. Thin wrappers over the MCP tools, which call the same store functions
+// the app's /api/generators routes do.
+
+import { CliError } from "../client.mjs";
+import {
+	flagStr,
+	flagNum,
+	flagList,
+	requirePositional,
+	printResult,
+	argsFromFlags,
+	refuseUnknownFlags,
+	readTextInput,
+	ok,
+} from "./shared.mjs";
+
+const SHAPES = ["text", "image", "animation", "video"];
+
+// `--output key:shape:Label` (repeatable), e.g. --output audit_shot:image:"Site audit".
+function readOutputs(flags) {
+	const raw = flagList(flags.output);
+	if (!raw.length) return undefined;
+	return raw.map((entry) => {
+		const [key, shape, ...label] = entry.split(":");
+		if (!key || !SHAPES.includes(shape) || !label.length) {
+			throw new CliError(
+				`--output takes key:shape:Label with shape one of ${SHAPES.join(", ")} (got "${entry}")`
+			);
+		}
+		return { key, shape, label: label.join(":") };
+	});
+}
+
+// --browser, --login <app-connection-id>, --stealth, --record, --region, --image-model, --tool <op>…
+function readNeeds(flags) {
+	const browser = {};
+	if (flagStr(flags.login)) browser.login = flagStr(flags.login);
+	if (flags.stealth === true) browser.stealth = true;
+	if (flags.record === true) browser.record = true;
+	if (flagStr(flags.region)) browser.region = flagStr(flags.region);
+	const needs = {};
+	if (flags.browser === true || Object.keys(browser).length) needs.browser = browser;
+	if (flags["image-model"] === true) needs.image_model = true;
+	const tools = flagList(flags.tool);
+	if (tools.length) needs.tools = tools;
+	return Object.keys(needs).length ? needs : undefined;
+}
+
+const inputs = (flags) => {
+	const v = flagList(flags.input);
+	return v.length ? v : undefined;
+};
+
+const fields = {
+	name: "name",
+	instructions: { value: (flags) => readTextInput(flags, "instructions", "instructions-file") },
+	inputs: { value: inputs },
+	outputs: { value: readOutputs },
+	needs: { value: readNeeds },
+	cache_scope: { flag: "share", enum: ["prospect", "company_domain"] },
+	freshness_days: { flag: "fresh-days", type: "num" },
+	budget_per_person_usd: { flag: "budget", type: "num" },
+	no_fit_rule: "skip-when",
+	disclosure: { flag: "disclosure", type: "bool", negate: "no-disclosure" },
+};
+
+// Flags the computed sources above read (refuseUnknownFlags can't see inside `value`).
+const FIELD_FLAGS = [
+	"instructions",
+	"instructions-file",
+	"input",
+	"output",
+	"browser",
+	"login",
+	"stealth",
+	"record",
+	"region",
+	"image-model",
+	"tool",
+];
+
+// 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 = {
+	list_generators: {},
+	get_generator: {
+		generator_id: { positional: 0, label: "enclosure-id", required: true },
+	},
+	create_generator: {
+		key: "key",
+		...fields,
+		name: { flag: "name", required: true },
+	},
+	update_generator: {
+		generator_id: { positional: 0, label: "enclosure-id", required: true },
+		...fields,
+	},
+	list_generations: {
+		generator_id: { positional: 0, label: "enclosure-id", required: true },
+		status: { flag: "status", enum: ["queued", "running", "done", "no_fit", "failed", "skipped"] },
+		limit: { flag: "limit", type: "num" },
+	},
+};
+
+const USAGE = `Usage: enclosures <list|show|create|update|prints>
+  enclosures list
+  enclosures show <enclosure-id>
+  enclosures create --name <n> --output key:shape:Label… [--key <k>] [--instructions <text>|--instructions-file <path>]
+                    [--input website…] [--browser] [--login <app-connection-id>] [--stealth] [--record] [--region us-east|eu-west]
+                    [--image-model] [--tool run_site_audit…] [--share prospect|company_domain] [--fresh-days <n>]
+                    [--budget <usd>] [--skip-when <sentence>] [--no-disclosure]
+  enclosures update <enclosure-id> [same flags]
+  enclosures prints <enclosure-id> [--status done|failed|no_fit|…] [--limit <n>]`;
+
+export async function cmdEnclosures(ctx) {
+	const sub = ctx.positionals[0];
+	const rest = { ...ctx, positionals: ctx.positionals.slice(1) };
+	switch (sub) {
+		case "list":
+		case "ls":
+			return enclosuresList(rest);
+		case "show":
+		case "get":
+			return enclosuresShow(rest);
+		case "create":
+			return enclosuresCreate(rest);
+		case "update":
+			return enclosuresUpdate(rest);
+		case "prints":
+			return enclosuresPrints(rest);
+		default:
+			throw new CliError(USAGE);
+	}
+}
+
+function formatEnclosure(g) {
+	const c = g.counts ?? {};
+	const lines = [
+		`${g.id}  ${g.key}  ${g.name}  [${g.status}${g.current_version ? `, version ${g.current_version}` : ""}]`,
+	];
+	lines.push(`  columns: ${(g.outputs ?? []).map((o) => `${o.label} {{custom:${o.key}}} (${o.shape})`).join(", ")}`);
+	if (g.inputs?.length) lines.push(`  reads: ${g.inputs.join(", ")}`);
+	lines.push(
+		`  prints: ${c.done ?? 0} ready, ${(c.queued ?? 0) + (c.running ?? 0)} making, ${c.no_fit ?? 0} no fit, ${c.failed ?? 0} failed`
+	);
+	return lines.join("\n");
+}
+
+async function enclosuresList(ctx) {
+	const { client, flags, io } = ctx;
+	const result = await client.callTool("list_generators", argsFromFlags(ARGS.list_generators, flags));
+	printResult(io, flags, result, (r) => {
+		const all = r.generators ?? [];
+		if (!all.length) return "No enclosures yet.";
+		return all.map(formatEnclosure).join("\n\n");
+	});
+	return 0;
+}
+
+async function enclosuresShow(ctx) {
+	const { client, flags, positionals, io } = ctx;
+	const result = await client.callTool("get_generator", argsFromFlags(ARGS.get_generator, flags, positionals));
+	printResult(io, flags, result, (r) => {
+		const lines = [formatEnclosure(r.generator)];
+		for (const v of r.generator.versions ?? []) {
+			lines.push(
+				`  version ${v.version} (${v.author}): ${v.steps} steps${v.change_summary ? `, ${v.change_summary}` : ""}`
+			);
+		}
+		return lines.join("\n");
+	});
+	return 0;
+}
+
+async function enclosuresCreate(ctx) {
+	const { client, flags, positionals, io } = ctx;
+	refuseUnknownFlags(ctx, ARGS.create_generator, FIELD_FLAGS);
+	const result = await client.callTool("create_generator", argsFromFlags(ARGS.create_generator, flags, positionals));
+	ok(ctx, `Created ${result.generator?.name} (${result.generator?.id}).`);
+	printResult(io, flags, result, (r) => formatEnclosure(r.generator));
+	return 0;
+}
+
+async function enclosuresUpdate(ctx) {
+	const { client, flags, positionals, io } = ctx;
+	refuseUnknownFlags(ctx, ARGS.update_generator, FIELD_FLAGS);
+	const args = argsFromFlags(ARGS.update_generator, flags, positionals);
+	if (Object.keys(args).length === 1) throw new CliError("Nothing to update. Pass a field flag.");
+	const result = await client.callTool("update_generator", args);
+	ok(ctx, `Updated ${result.generator?.name}.`);
+	printResult(io, flags, result, (r) => formatEnclosure(r.generator));
+	return 0;
+}
+
+async function enclosuresPrints(ctx) {
+	const { client, flags, positionals, io } = ctx;
+	requirePositional(positionals, 0, "enclosure-id");
+	if (flags.limit !== undefined) flagNum(flags.limit);
+	const result = await client.callTool("list_generations", argsFromFlags(ARGS.list_generations, flags, positionals));
+	printResult(io, flags, result, (r) => {
+		const all = r.generations ?? [];
+		if (!all.length) return "No prints yet.";
+		return all
+			.map((g) => `${g.status.padEnd(8)} ${g.prospect?.email ?? g.prospect_id}${g.error ? `  ${g.error}` : ""}`)
+			.join("\n");
+	});
+	return 0;
+}

package/lib/commands/repo.mjs

@@ -63,6 +63,8 @@ const ARGS = {
 		files: { value: (_flags, _positionals, extra) => (extra.files?.length ? extra.files : undefined) },
 		action: { flag: "action", enum: ["build", "build_pr", "build_merge", "slack", "linear"] },
 		preview: { flag: "preview", type: "bool" },
+		// --with-preview: the PR opens straight away and a preview of the change stays up next to it.
+		with_preview: { flag: "with-preview", type: "bool" },
 	},
 	create_repo_change_upload: { file_names: { internal: "the basenames of the --attach files" } },
 	list_repo_sites: {},
@@ -320,6 +322,7 @@ async function repoStart(ctx) {
 		"attach-url",
 		"action",
 		"preview",
+		"with-preview",
 		"wait",
 	]);
 	const files = [

package/lib/commands/site.mjs

@@ -178,6 +178,8 @@ const ARGS = {
 		base_branch: { flag: "base-branch" },
 		preview: { flag: "preview", type: "bool" },
 		action: { flag: "action", enum: ["build", "build_pr", "build_merge", "slack", "linear"] },
+		// --with-preview: the PR opens straight away and a preview of the fix stays up next to it.
+		with_preview: { flag: "with-preview", type: "bool" },
 	},
 };
 

package/lib/commands.mjs

@@ -38,6 +38,7 @@ export * from "./commands/enhance.mjs";
 export * from "./commands/landings.mjs";
 export * from "./commands/outbound.mjs";
 export * from "./commands/offerings.mjs";
+export * from "./commands/enclosures.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.125.0",
+	"version": "0.126.1",
 	"description": "Spin up and manage Letterstory phantom blogs from your terminal.",
 	"type": "module",
 	"license": "UNLICENSED",