@letterstory/cli 0.27.1 → 0.28.0

package/README.md

@@ -341,6 +341,16 @@ letterstory arena endpoint create --name "Docs research" --defaults '{"depth":"b
 letterstory arena endpoint config <arena-id> [--file cfg.json]
 letterstory arena endpoint delete <arena-id> --yes
 
+# Ledes: a prospect's context in, ready-to-send opening lines out (chosen from a
+# hand-approved library, never generated; the top choice is flagged). Synchronous.
+letterstory lede create --name "Clay outbound table"
+letterstory lede run <endpoint-id> --first-name Jane --company Acme --company-url acme.com --years 3
+letterstory lede run <endpoint-id> --email jane@acme.com --tone direct --candidates 3
+letterstory lede run <endpoint-id> --company Acme --default-lede "Came across {{company}} this week."
+letterstory lede runs --limit 20
+letterstory lede balance
+letterstory lede endpoint config <endpoint-id> [--file cfg.json]
+
 # 2. Have a kernel write the draft
 letterstory kernel list
 letterstory kernel run --article <uuid> --kernel <uuid> [--brief "…" | --brief-file brief.md]

package/lib/cli.mjs

@@ -39,12 +39,13 @@ import {
 	cmdSeers,
 	cmdTemplates,
 	cmdShredder,
+	cmdLede,
 	cmdLandings,
 	cmdAdmin,
 } from "./commands.mjs";
 
 // Keep in sync with cli/package.json.
-export const VERSION = "0.27.1";
+export const VERSION = "0.28.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.
@@ -538,6 +539,24 @@ Shredder (diversify content produced outside Letterstory; structure preserved):
   shredder job <job-id>                                Poll a queued shred and print it when it lands
   shredder runs [--endpoint <id>] [--limit <n>]        Recent shred calls (telemetry), newest first
 
+Ledes (opening lines for cold email, chosen per prospect from a hand-approved library):
+  lede list                                            Your lede endpoints + run counts
+  lede create --name <n>                               New endpoint (returns a callable public id)
+  lede delete <endpoint-id> --yes
+  lede endpoint config <endpoint-id> [--file cfg.json] Print the endpoint's config, or replace it
+  lede run <endpoint-id> [--first-name <n>] [--name <full>] [--email <e>] [--title <t>]
+           [--company <c>] [--company-url <url>] [--school <s>] [--city <c>] [--country <c>]
+           [--years <n>] [--linkedin <url>] [--notes <text>]
+           [--candidates <1..10>] [--tone warm|direct|playful|formal] [--no-enrich]
+                                                       Synchronous: prints the candidate lines with the
+                                                       top choice flagged. Needs at least one of
+                                                       --first-name, --name, --email, --company or
+                                                       --company-url. Only a match consumes a lede;
+                                                       no_match is free. --no-enrich skips the company
+                                                       lookup when latency matters more than fit.
+  lede runs [--endpoint <id>] [--limit <n>]            Recent lede calls (telemetry), newest first
+  lede balance                                         Ledes left on this org
+
 Landings (a link + context; auto-mentioned in articles by collections you enable):
   landings list                                        Your landing pages + mention counts
   landings get <landing-id>                            Show one landing page
@@ -615,6 +634,8 @@ const CLIENT_COMMANDS = {
 	seers: cmdSeers,
 	templates: cmdTemplates,
 	shredder: cmdShredder,
+	lede: cmdLede,
+	ledes: cmdLede,
 	landings: cmdLandings,
 	// Platform-scoped (staff key) — the only commands that act BEFORE an org exists.
 	admin: cmdAdmin,

package/lib/commands/lede.mjs

@@ -0,0 +1,225 @@
+// `lede` — create lede endpoints and turn a prospect's context (name, email, company,
+// school, city...) into ready-to-send opening lines for cold email, chosen from a
+// hand-approved library and scored by fit. A run is SYNCHRONOUS: one call returns the
+// candidates in seconds (up to a minute for a company the enrichment has never seen),
+// with the top choice flagged. Only a matched run consumes a lede; no_match is free.
+
+import { readFileSync } from "node:fs";
+import { CliError } from "../client.mjs";
+import { flagStr, requirePositional, printResult, ok, argsFromFlags } from "./shared.mjs";
+
+/** `--<flag> <path>` → the file's parsed JSON, or undefined when the flag is not set. */
+function readJsonFileFlag(flags, flag) {
+	const path = flagStr(flags[flag]);
+	if (path === undefined) return undefined;
+	let text;
+	try {
+		text = readFileSync(path, "utf8");
+	} catch (error) {
+		throw new CliError(
+			`Could not read --${flag} ${path}: ${error instanceof Error ? error.message : String(error)}`
+		);
+	}
+	try {
+		return JSON.parse(text);
+	} catch {
+		throw new CliError(`--${flag} ${path} is not valid JSON.`);
+	}
+}
+
+/**
+ * How every command in this file sources its tool's inputs — see `argsFromFlags` in
+ * shared.mjs and `scripts/parity-check.ts`, which diffs these keys against each tool's
+ * published schema. Every lede tool is mapped: a field added to one of them and
+ * forgotten here fails CI.
+ */
+export const ARGS = {
+	run_lede: {
+		endpoint_id: { positional: 0, label: "endpoint-id", required: true },
+		first_name: "first-name",
+		last_name: "last-name",
+		name: "name",
+		email: "email",
+		title: "title",
+		company: "company",
+		company_url: "company-url",
+		school: "school",
+		city: "city",
+		country: "country",
+		years_at_company: { flag: "years", type: "num" },
+		linkedin_url: "linkedin",
+		notes: "notes",
+		max_candidates: { flag: "candidates", type: "num" },
+		tone: { flag: "tone", enum: ["warm", "direct", "playful", "formal"] },
+		// Your own fallback line, returned (unbilled, still no_match) when nothing qualifies.
+		default_lede: { flag: "default-lede" },
+		// Enrichment is ON by default server-side; `--no-enrich` skips it for latency.
+		enrich: { value: (flags) => (flags["no-enrich"] === true ? false : undefined) },
+	},
+	list_lede_runs: {
+		endpoint_id: "endpoint",
+		limit: { flag: "limit", type: "num" },
+	},
+	list_lede_endpoints: {},
+	get_lede_balance: {},
+	create_lede_endpoint: {
+		name: { flag: "name", required: true },
+	},
+	delete_lede_endpoint: {
+		endpoint_id: { positional: 1, label: "endpoint-id", required: true },
+	},
+	// The endpoint's configuration as ONE file: `lede endpoint config <id>` prints it,
+	// `lede endpoint config <id> --file cfg.json` replaces it with the file's document.
+	get_lede_endpoint_config: {
+		endpoint_id: { positional: 1, label: "endpoint-id", required: true },
+	},
+	set_lede_endpoint_config: {
+		endpoint_id: { positional: 1, label: "endpoint-id", required: true },
+		config: { value: (flags) => readJsonFileFlag(flags, "file") },
+	},
+};
+
+export async function cmdLede(ctx) {
+	const sub = ctx.positionals[0];
+	const rest = { ...ctx, positionals: ctx.positionals.slice(1) };
+	switch (sub) {
+		case "list":
+		case "ls":
+			return ledeList(rest);
+		case "new":
+		case "create":
+			return ledeCreate(rest);
+		case "delete":
+		case "rm":
+			return ledeDelete(rest);
+		case "endpoint":
+			return ledeEndpoint(rest);
+		case "run":
+			return ledeRun(rest);
+		case "runs":
+		case "telemetry":
+			return ledeRuns(rest);
+		case "balance":
+			return ledeBalance(rest);
+		default:
+			throw new CliError(
+				`Unknown lede subcommand: ${sub ?? "(none)"}. Try: list, create, delete, endpoint, run, runs, balance`
+			);
+	}
+}
+
+async function ledeList(ctx) {
+	const { client, flags, io } = ctx;
+	const result = await client.callTool("list_lede_endpoints", argsFromFlags(ARGS.list_lede_endpoints, flags));
+	printResult(io, flags, result);
+	return 0;
+}
+
+async function ledeCreate(ctx) {
+	const { client, flags, positionals, io } = ctx;
+	const args = argsFromFlags(ARGS.create_lede_endpoint, flags, positionals);
+	const result = await client.callTool("create_lede_endpoint", args);
+	ok(ctx, `Created lede endpoint "${args.name}".`);
+	printResult(io, flags, result);
+	return 0;
+}
+
+async function ledeDelete(ctx) {
+	const { client, positionals, flags, io } = ctx;
+	const id = requirePositional(positionals, 0, "endpoint-id");
+	if (!flags.yes) {
+		io.error(`Re-run with --yes to confirm: ${ctx.bin} lede delete ${id} --yes`);
+		return 1;
+	}
+	// `lede delete <id>` and `lede endpoint delete <id>` are the same act; the ARGS map
+	// is written for the latter's positional layout.
+	const result = await client.callTool("delete_lede_endpoint", { endpoint_id: id });
+	ok(ctx, "Lede endpoint deleted.");
+	printResult(io, flags, result);
+	return 0;
+}
+
+/**
+ * `lede endpoint config|delete` — the endpoint's own configuration and lifecycle, the
+ * same shape `shredder endpoint …` and `kernel endpoint …` have, so the primitives read
+ * the same way.
+ */
+async function ledeEndpoint(ctx) {
+	const { client, positionals, flags, io } = ctx;
+	const action = positionals[0];
+	if (action === "delete" || action === "rm") {
+		const id = requirePositional(positionals, 1, "endpoint-id");
+		if (!flags.yes) {
+			io.error(`Re-run with --yes to confirm: ${ctx.bin} lede endpoint delete ${id} --yes`);
+			return 1;
+		}
+		const result = await client.callTool(
+			"delete_lede_endpoint",
+			argsFromFlags(ARGS.delete_lede_endpoint, flags, positionals)
+		);
+		ok(ctx, "Lede endpoint deleted.");
+		printResult(io, flags, result);
+		return 0;
+	}
+	if (action === "config") {
+		const id = requirePositional(positionals, 1, "endpoint-id");
+		if (flagStr(flags.file) === undefined) {
+			const result = await client.callTool(
+				"get_lede_endpoint_config",
+				argsFromFlags(ARGS.get_lede_endpoint_config, flags, positionals)
+			);
+			// The document itself, so `> cfg.json` round-trips into `--file cfg.json`.
+			printResult(io, flags, result, (r) => JSON.stringify(r?.config ?? r, null, 2));
+			return 0;
+		}
+		const args = argsFromFlags(ARGS.set_lede_endpoint_config, flags, positionals);
+		const result = await client.callTool("set_lede_endpoint_config", args);
+		ok(ctx, `Replaced the configuration of lede endpoint ${id}.`);
+		printResult(io, flags, result);
+		return 0;
+	}
+	throw new CliError(`Unknown lede endpoint action: ${action ?? "(none)"}. Try: config, delete`);
+}
+
+async function ledeRun(ctx) {
+	const { client, positionals, flags, io } = ctx;
+	const args = argsFromFlags(ARGS.run_lede, flags, positionals);
+	const hasAnchor = !!(args.first_name || args.name || args.email || args.company || args.company_url);
+	if (!hasAnchor) {
+		throw new CliError(
+			"Give the prospect at least one of --first-name, --name, --email, --company or --company-url."
+		);
+	}
+	const result = await client.callTool("run_lede", args);
+	// The operator ran this to get LINES, so print the lines: the top choice first with
+	// its confidence, then the rest. `--json` still gets the whole payload (enrichment,
+	// candidate ids for repeat-avoidance), which is what a script piping this wants.
+	printResult(io, flags, result, (r) => {
+		if (r?.status === "no_match" && !(r?.candidates ?? []).length) {
+			return "No line cleared the confidence floor for this person (not charged). More fields usually turn this into a match.";
+		}
+		const lines = (r?.candidates ?? []).map(
+			(c, i) => `${i + 1}. ${c.text}  [${Math.round((c.confidence ?? 0) * 100)}%${c.top ? ", top choice" : ""}]`
+		);
+		const prefix =
+			r?.status === "no_match"
+				? "No line cleared the confidence floor (not charged); showing your default:\n"
+				: "";
+		return prefix + (lines.join("\n") || JSON.stringify(r, null, 2));
+	});
+	return 0;
+}
+
+async function ledeRuns(ctx) {
+	const { client, flags, io } = ctx;
+	const result = await client.callTool("list_lede_runs", argsFromFlags(ARGS.list_lede_runs, flags));
+	printResult(io, flags, result);
+	return 0;
+}
+
+async function ledeBalance(ctx) {
+	const { client, flags, io } = ctx;
+	const result = await client.callTool("get_lede_balance", argsFromFlags(ARGS.get_lede_balance, flags));
+	printResult(io, flags, result);
+	return 0;
+}

package/lib/commands.mjs

@@ -23,6 +23,7 @@ export * from "./commands/arena.mjs";
 export * from "./commands/templates.mjs";
 export * from "./commands/autopen.mjs";
 export * from "./commands/kernel.mjs";
+export * from "./commands/lede.mjs";
 export * from "./commands/phantom-job.mjs";
 export * from "./commands/onboard.mjs";
 export * from "./commands/seers.mjs";

package/package.json

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