@letterstory/cli 0.90.0 → 0.92.0

package/lib/cli.mjs

@@ -57,7 +57,7 @@ import {
 } from "./commands.mjs";
 
 // Keep in sync with cli/package.json.
-export const VERSION = "0.90.0";
+export const VERSION = "0.92.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
@@ -121,6 +121,8 @@ export const BOOLEAN_FLAGS = new Set([
 	// `phantom-onboard collection --enable-planner`, `strategy sitemap --posts-only`, and the
 	// `strategy positioning set --clear-*` switches: value-less, and each sits next to a value.
 	"enable-planner",
+	// `phantom-onboard primitives --retry [<domain>]` re-reads a domain whose read failed.
+	"retry",
 	"posts-only",
 	"clear-topics",
 	"clear-stances",
@@ -135,9 +137,10 @@ export const BOOLEAN_FLAGS = new Set([
 	"no-enrich",
 	// `offerings set-collection <id> --none` (the org itself is the subject again).
 	"none",
-	// `prospects import|source --one-per-company`, `prospects source --enrich`.
+	// `prospects import|source --one-per-company`, `prospects source --enrich`, `prospects import --find-emails`.
 	"one-per-company",
 	"enrich",
+	"find-emails",
 	// `targets update <id> --clear-framing`; `targets subqueries --retired`,
 	// `targets subquery update <id> --retire` / `--restore`.
 	"clear-framing",
@@ -580,6 +583,9 @@ Propose lane (the Fleet wizard's Plan and Name screens; persists nothing, spends
                                                        (--plan '<json>' inline, or - for stdin).
 
 What does this org still need? (the router — reads only, decides nothing):
+  ${bin === "phantom" ? "onboard" : "phantom-onboard"} primitives [<domain>] [--retry]  The primitives that fit a domain (default:
+                                                       yours), each with the exact call that sets
+                                                       it up — the plan Instances shows
   ${bin === "phantom" ? "onboard" : "phantom-onboard"} plan                         Every onboarding step (context, main blog,
                                                        Planner, CMS, phantom) with its status:
                                                        done / running / ready / blocked, and what
@@ -992,9 +998,10 @@ Sequences (multi-step cold email sent from your mailers; approving or enrolling
            [--[no-]opt-out-footer] [--[no-]postal-address-footer] [--[no-]unsubscribe-links] [--[no-]detect-reply-opt-outs]
            [--[no-]test-mode] [--default-lede <fallback opener line>]
            [--send-window-start <HH:MM>] [--send-window-end <HH:MM>] [--send-window-timezone <IANA tz>]
-           [--enroll-on-cake paid|scheduled|out_for_delivery|delivered|none]
+           [--enroll-on-cake paid|scheduled|out_for_delivery|delivered|none] [--enroll-on-cake-list <list-id>|none]
                                                        --test-mode (internal accounts only): walks as live, sends nothing
                                                        --enroll-on-cake: start it when a recipient's Daymaker cake reaches that stage
+                                                       --enroll-on-cake-list: only for prospects in that list (none = any)
   sequences pause|resume <sequence-id>                 Stop / restart sending
   sequences enroll <sequence-id> (--list <list-id> | --email <addr>... | --recipients '<json>'|--recipients-file <path>)
   sequences stop <sequence-id> <enrollment-id>         Stop one recipient
@@ -1023,6 +1030,9 @@ Prospects (who you write to):
   prospects get <prospect-id>
   prospects create-list --name <n>
   prospects import --csv-file <path|-> [--list <list-id>|--list-name <n>] [--one-per-company]
+           [--find-emails [--max-email-lookups <1..100>]]
+                                                       --find-emails: look up the business email of rows with a
+                                                       LinkedIn URL and no email (paid; default 25 lookups)
   prospects source --description <who you want> [--list <list-id>|--list-name <n>] [--limit <1..100>]
            [--one-per-company] [--enrich]              Fill a list from paid data providers (background);
                                                        --enrich starts enrichment as soon as the pull lands

package/lib/commands/onboard.mjs

@@ -174,6 +174,12 @@ export const ARGS = {
 	get_phantom_launch_status: {
 		job_id: { internal: "the job id plan_phantom just returned" },
 	},
+	// The primitive plan: a domain (default: the org's own) read into the calls that would
+	// stand each primitive up. Printed, never run — approving an item is running its call.
+	propose_primitive_plan: {
+		domain: { positional: 0, label: "domain" },
+		retry: { flag: "retry", type: "bool" },
+	},
 	propose_phantom_plan: {
 		client_domain: { positional: 0, label: "client-domain" },
 		direction: ["about", "direction"],
@@ -752,8 +758,62 @@ async function cmdOnboardNext(ctx) {
 	return 0;
 }
 
+// `onboard primitives [<domain>]` — what Letterstory would stand up for this company: one
+// read of propose_primitive_plan, printed as a table whose last column is the exact
+// `call` that sets each item up. Nothing runs; approving an item is running its line.
+// A first read crawls the site; `pending` means one is already in flight, so wait and ask.
+function shellQuote(json) {
+	return `'${json.replace(/'/g, "'\\''")}'`;
+}
+
+function formatPrimitivePlan(ctx) {
+	return (res) => {
+		if (res.status !== "complete") {
+			return res.status === "pending"
+				? `Still reading ${res.domain} — run this again in a few seconds.`
+				: `Couldn't read ${res.domain}: ${res.error ?? "unknown error"} (retry with --retry)`;
+		}
+		const { plan } = res;
+		const lines = [`${plan.company_name} (${plan.domain})`, `  ${plan.priority_topics.join(" · ")}`, ""];
+		for (const item of plan.items) {
+			// A part of its parent's setup prints indented under it.
+			const pad = item.parent ? "    " : "";
+			const mark = item.status === "exists" ? "running " : "proposed";
+			lines.push(`${pad}${mark}  ${item.title}`);
+			lines.push(
+				item.status === "exists"
+					? `${pad}          already: ${item.existing.map((e) => e.name).join(", ")}`
+					: `${pad}          ${item.detail}`
+			);
+			if (item.call) {
+				lines.push(
+					`${pad}          ${ctx.bin} call ${item.call.tool} --args ${shellQuote(JSON.stringify(item.call.args))}`
+				);
+				for (const [arg, ref] of Object.entries(item.refs ?? {})) {
+					lines.push(`${pad}          with ${arg} = ${ref.field} from ${ref.item}`);
+				}
+				if (item.after?.length) lines.push(`${pad}          after: ${item.after.join(", ")}`);
+				if (item.poll) lines.push(`${pad}          then poll: ${item.poll.tool}`);
+			}
+		}
+		return lines.join("\n");
+	};
+}
+
+async function cmdOnboardPrimitives(ctx) {
+	const args = argsFromFlags(ARGS.propose_primitive_plan, ctx.flags, ctx.positionals);
+	ok(ctx, "Reading the domain…");
+	const res = await ctx.client.callTool("propose_primitive_plan", args);
+	printResult(ctx.io, ctx.flags, res, formatPrimitivePlan(ctx));
+	return 0;
+}
+
 export async function cmdOnboard(ctx) {
 	const { client, flags, io } = ctx;
+	// `onboard primitives [<domain>]` — the primitive plan and the call behind each item.
+	if (ctx.positionals[0] === "primitives") {
+		return cmdOnboardPrimitives({ ...ctx, positionals: ctx.positionals.slice(1) });
+	}
 	// `onboard plan` / `onboard next` — the router: what does this org still need?
 	if (ctx.positionals[0] === "plan") return cmdOnboardPlan(ctx);
 	if (ctx.positionals[0] === "next") return cmdOnboardNext(ctx);

package/lib/commands/outbound.mjs

@@ -93,6 +93,13 @@ const SEQUENCE_WINDOW_ARGS = {
 // reaches it; `none` clears it.
 const CAKE_TRIGGER_STAGES = ["paid", "scheduled", "out_for_delivery", "delivered"];
 const CAKE_STAGES = ["draft", ...CAKE_TRIGGER_STAGES, "delivery_failed", "cancelled"];
+const enrollOnCakeList = {
+	value: (flags) => {
+		const raw = flagStr(flags["enroll-on-cake-list"]);
+		if (raw === undefined) return undefined;
+		return raw === "none" ? null : raw;
+	},
+};
 const enrollOnCake = {
 	value: (flags) => {
 		const raw = flagStr(flags["enroll-on-cake"]);
@@ -163,6 +170,7 @@ export const ARGS = {
 		...SEQUENCE_RAIL_ARGS,
 		...SEQUENCE_WINDOW_ARGS,
 		enroll_on_cake: enrollOnCake,
+		enroll_on_cake_list_id: enrollOnCakeList,
 	},
 	update_sequence: {
 		sequence_id: { positional: 0, label: "sequence-id", required: true },
@@ -173,6 +181,7 @@ export const ARGS = {
 		...SEQUENCE_RAIL_ARGS,
 		...SEQUENCE_WINDOW_ARGS,
 		enroll_on_cake: enrollOnCake,
+		enroll_on_cake_list_id: enrollOnCakeList,
 	},
 	list_cakes: {
 		stage: { flag: "stage", enum: CAKE_STAGES },
@@ -265,6 +274,8 @@ export const ARGS = {
 				return csv;
 			},
 		},
+		find_emails: { flag: "find-emails", type: "bool" },
+		max_email_lookups: { flag: "max-email-lookups", type: "num" },
 		one_per_company: { flag: "one-per-company", type: "bool" },
 		list_id: "list",
 		list_name: "list-name",
@@ -378,20 +389,8 @@ export const ARGS = {
 	},
 };
 
-// Flags the computed `value` sources read (refuseUnknownFlags can't see them).
-const VALUE_FLAGS = {
-	create_sequence: ["flow", "flow-file", "mailer", "send-window-start", "send-window-end"],
-	update_sequence: ["flow", "flow-file", "mailer", "send-window-start", "send-window-end"],
-	enroll_in_sequence: ["recipients", "recipients-file", "email"],
-	update_review_item: ["body", "file", "personalize", "personalize-mode"],
-	delete_prospects: ["id"],
-	import_prospects_csv: ["csv", "csv-file"],
-	update_prospect: ["custom"],
-	set_mailer_forwarding: ["to", "clear"],
-};
-
 async function run(ctx, tool, message) {
-	refuseUnknownFlags(ctx, ARGS[tool], VALUE_FLAGS[tool] ?? []);
+	refuseUnknownFlags(ctx, ARGS[tool]);
 	const result = await ctx.client.callTool(tool, argsFromFlags(ARGS[tool], ctx.flags, ctx.positionals));
 	if (message) ok(ctx, message);
 	printResult(ctx.io, ctx.flags, result);

package/lib/commands/shared.mjs

@@ -83,6 +83,35 @@ export const GLOBAL_FLAGS = new Set([
 	"profile",
 ]);
 
+/**
+ * The flags a computed `{ value }` source reads, found by running it against
+ * no flags and recording each key it looks up. A value source names its flags
+ * inside code the map can't see, so `sequences update --enroll-on-cake` was
+ * refused by a command whose help and parser both took it.
+ */
+export function valueSourceFlags(value) {
+	const read = new Set();
+	const flags = new Proxy(
+		{},
+		{
+			get: (_target, key) => {
+				if (typeof key === "string") read.add(key);
+				return undefined;
+			},
+			has: (_target, key) => {
+				if (typeof key === "string") read.add(key);
+				return false;
+			},
+		}
+	);
+	try {
+		value(flags, []);
+	} catch {
+		// A required source throws when its flag is absent; the read was recorded first.
+	}
+	return read;
+}
+
 /**
  * Refuse a flag this command does not understand.
  *
@@ -105,6 +134,8 @@ export function refuseUnknownFlags(ctx, argsMap, own = []) {
 		else if (source && typeof source === "object" && source.flag) {
 			allowed.add(source.flag);
 			if (source.negate) allowed.add(source.negate);
+		} else if (source && typeof source === "object" && typeof source.value === "function") {
+			valueSourceFlags(source.value).forEach((f) => allowed.add(f));
 		}
 	}
 	const unknown = Object.keys(ctx.flags).filter((f) => !allowed.has(f));

package/package.json

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