@agentcomms/resend 0.13.0 → 0.13.1

package/README.md

@@ -17,9 +17,9 @@ code, but the key itself would not stop anything else that held it. A sending-on
 enforces that — and it cannot read anything, so reads with it are reported as unavailable. `agent-resend doctor`
 says this on every run.
 
-**Nothing is sent without a person.** A send is prepared, previewed — every recipient, BCC included, the reach
-(unique recipients), the From domain and whether it is verified — and approved: a yes in the conversation under the
-account's `chat` policy, or `agent-resend approve <id>` and a typed code under `confirm`. Above ten recipients, or to
+**Nothing is sent without a person.** A send is prepared, previewed — every recipient, BCC included, the reach (unique
+recipients), the From domain and whether it is verified — and approved: a yes in the conversation under the account's
+`chat` policy, or the approve command the result gives and a typed code under `confirm`. Above ten recipients, or to
 an address that arrived in mail read here, a person at a terminal approves, whatever the policy. The approval id is
 the request's `Idempotency-Key` and an `agentcomms_approval` tag; a send whose outcome is unknown is never repeated,
 only checked.
@@ -98,7 +98,7 @@ terminal), `approve` (under `confirm`, a person at a terminal) and `mcp` (it sta
 | `agent-resend send status <approvalId>` | `resend_send_status` |
 | `agent-resend scheduled list` | `resend_scheduled_list` |
 | `agent-resend scheduled cancel <id>` | `resend_scheduled_cancel` |
-| `agent-resend approve <approvalId>` | — a person at a terminal |
+| `agent-resend approve <approvalId>` | — a person at a terminal, with the command the result gives |
 | `agent-resend mcp` | — it starts the server |
 | `agent-resend mcp install --client <client>` | `comms_server_install` (core) |
 | `agent-resend mcp prune` | `comms_server_prune` (core) |

package/dist/cli.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { $ as inlineCommand, B as agentMarker, C as policyChange, D as sendPolicyOf, E as removeAccountChange, F as CHANNEL_SERVERS, H as approvalsOf, I as CommsError, J as commandPathOf, L as EXIT_CODES, N as checkNewName, O as showAccount, Q as gatedChangeAtTerminal, R as SEND_LOOKUP, S as policyApprovalRefusal, T as policyWanted, U as approveChangeAtTerminal, V as approvalKind, W as canPrompt, X as exemptFromUpdateGate, Y as escapeForDisplay, _ as runDoctor, a as revokeSendApproval, at as renderPrune, b as listAccounts, c as downloadReceived, ct as serverInstallChange, d as listReceived, dt as terminalUpdateHooks, et as installExitStatus, f as listScheduled, g as showSentEmail, gt as writeResult, h as showReceived, i as prepareSend, it as renderInstall, k as ResendContext, l as getMetrics, lt as serverPruneChange, m as listSuppressions, mt as updateGateAtTerminal, n as executeSend, nt as paint, o as sendStatus, ot as runCommand, p as listSentEmails, pt as truncateDisplay, q as colorEnabled, r as finishSendApproval, rt as refuseUnclaimedApproval, s as cancelScheduledChange, st as runUpdateCheckChild, t as beginSendApproval, tt as openCore, u as listDomains, ut as shellCommand, v as addAccountChange, w as policyReport, x as modeOf, xt as VERSION, y as inspectKey, z as UPDATE_CHECK_CHILD_COMMAND } from "./send-D2ZOWO_6.mjs";
+import { B as UPDATE_CHECK_CHILD_COMMAND, C as policyChange, D as sendPolicyOf, Dt as VERSION, E as removeAccountChange, F as CHANNEL_SERVERS, G as canPrompt, H as approvalKind, I as CommsError, J as cliHandoffs, L as EXIT_CODES, N as checkNewName, O as showAccount, Q as exemptFromUpdateGate, R as PATH_OPTIONS, S as policyApprovalRefusal, St as RESEND_CALLER, T as policyWanted, U as approvalsOf, V as agentMarker, W as approveChangeAtTerminal, X as commandPathOf, Y as colorEnabled, Z as escapeForDisplay, _ as runDoctor, _t as truncateDisplay, a as revokeSendApproval, at as paint, b as listAccounts, bt as writeResult, c as downloadReceived, ct as renderInstall, d as listReceived, dt as runCommand, et as gatedChangeAtTerminal, f as listScheduled, ft as runUpdateCheckChild, g as showSentEmail, h as showReceived, ht as terminalUpdateHooks, i as prepareSend, it as openCore, k as ResendContext, l as getMetrics, lt as renderPrune, m as listSuppressions, mt as serverPruneChange, n as executeSend, nt as handoffSentenceToFill, o as sendStatus, ot as pathOverridesFromCliOptions, p as listSentEmails, pt as serverInstallChange, r as finishSendApproval, rt as installExitStatus, s as cancelScheduledChange, st as refuseUnclaimedApproval, t as beginSendApproval, tt as handoffSentence, u as listDomains, ut as resolvePaths, v as addAccountChange, vt as updateGateAtTerminal, w as policyReport, x as modeOf, y as inspectKey, z as SEND_LOOKUP } from "./send-DtBNDnE4.mjs";
 import path from "node:path";
 import { createInterface } from "node:readline/promises";
 import { stripVTControlCharacters } from "node:util";
@@ -3040,12 +3040,12 @@ const KEY_SHAPE = /^re_[A-Za-z0-9_]{8,200}$/;
 async function readApiKey(env, streams, options) {
 	const marker = agentMarker(env);
 	if (marker) throw new CommsError("AUTH_REQUIRED", "a Resend API key is added by a person at their own terminal, not by an agent", {
-		hint: `Ask the user to run ${inlineCommand(options.command)} in their own terminal. Never paste a key into a chat: the transcript keeps it.`,
+		hint: `${handoffSentence(options.command, (command) => `Ask the user to run ${command} in their own terminal.`)} Never paste a key into a chat: the transcript keeps it.`,
 		details: { marker }
 	});
 	let key = env["RESEND_API_KEY"]?.trim() ?? "";
 	if (key === "") {
-		if (!canPrompt(env, streams, { json: options.json })) throw new CommsError("AUTH_REQUIRED", "a Resend API key is needed, and there is no terminal to ask for it", { hint: `A person runs ${inlineCommand(options.command)} in a terminal, which asks for the key without showing it, or sets ${KEY_ENV} for that one command.` });
+		if (!canPrompt(env, streams, { json: options.json })) throw new CommsError("AUTH_REQUIRED", "a Resend API key is needed, and there is no terminal to ask for it", { hint: handoffSentence(options.command, (command) => `A person runs ${command} in a terminal, which asks for the key without showing it, or sets ${KEY_ENV} for that one command.`) });
 		key = (await askHidden(streams, "Resend API key (https://resend.com/api-keys; it is not shown as you type): ")).trim();
 	}
 	if (!KEY_SHAPE.test(key)) throw new CommsError("BAD_DATA", "that does not look like a Resend API key (they start with re_)", { hint: "Nothing was stored. Copy the key again from the Resend dashboard." });
@@ -3069,8 +3069,9 @@ function renderAccount(view, color) {
 		`  ${view.guarantee}`
 	].join("\n");
 }
-function renderAccounts(result, color) {
-	if (result.accounts.length === 0) return "No Resend account yet. A person adds one with `agent-resend account add <org/resend>`.";
+/** The accounts; with none, how a person adds one — this installation's own command, `handoffs`'s, or why there is none. */
+function renderAccounts(result, color, handoffs) {
+	if (result.accounts.length === 0) return handoffSentenceToFill(handoffs.own(["account", "add"]), ["<org/resend>"], (command) => `No Resend account yet. A person adds one with ${command}.`, { instead: "No Resend account yet." });
 	return result.accounts.map((view) => renderAccount(view, color)).join("\n\n");
 }
 function renderAdded(view, color) {
@@ -3131,6 +3132,17 @@ function withoutOptionValues(text) {
 	return text.replace(/'(-{1,2}[^'=\s]+)=[^']*'/g, "'$1=…'").replace(/\bre_[A-Za-z0-9_]{4,}/g, "re_…");
 }
 const collect = (value, previous = []) => [...previous, value];
+/** What a usage error tells the person: this installation's own `--help`, located — or why there is none here. */
+function usageHint(help) {
+	return handoffSentence(help, (command) => `Run ${command} to see the commands.`);
+}
+/**
+* What a command line that ran nothing says. Commander shows the help for an empty one itself, so this is the fallback
+* for a parse that ends with no command run and no error — never a bare name either way.
+*/
+function nothingToDo(help) {
+	return handoffSentence(help, (command) => `Nothing to do. Try ${command}.`);
+}
 /** `--expect-to a@x.test,b@x.test`, or `none`: a list is always written out, so a permission prompt shows it. */
 function expectList(raw, flag) {
 	const value = String(raw ?? "").trim();
@@ -3155,17 +3167,44 @@ async function run(argv, deps = {}) {
 		writeErr: (text) => streams.stderr.write(text),
 		outputError: (text, write) => write(withoutOptionValues(text))
 	}).addHelpText("after", `
-Getting started:
-  agent-resend account add acme/resend            a person types the key; it goes into the keychain
-  agent-resend doctor                              what works, and who enforces what
-  agent-resend domains --account acme/resend
-  agent-resend received list --account acme/resend
-  agent-resend mcp install --client claude-code   register the server with an agent, once a person approves it
+Getting started — run these with this CLI:
+  account add acme/resend            a person types the key; it goes into the keychain
+  doctor                              what works, and who enforces what
+  domains --account acme/resend
+  received list --account acme/resend
+  mcp install --client claude-code   register the server with an agent, once a person approves it
 
 Exit codes: 0 ok · 1 unexpected · 10 a send or a change was refused or needs approval · 11 an update
-is out: update first, or put it off (agentcomms update, agentcomms update --later) · 64 usage ·
+is out: update first, or put it off (the stop names both commands) · 64 usage ·
 65 bad data · 66 not found · 69 provider or secret store unavailable · 75 temporary (retry later) ·
 77 key or permission needed · 78 configuration problem.`).exitOverride();
+	for (const { flag } of PATH_OPTIONS) program.addOption(new Option(`${flag} <dir>`, "pin this suite directory for this run").argParser((value) => {
+		if (value.length === 0) throw new InvalidArgumentError(`${flag} needs a non-empty directory`);
+		return value;
+	}));
+	let invocationCore;
+	const coreForInvocation = () => {
+		if (invocationCore) return invocationCore;
+		const options = program.opts();
+		const pathOverrides = pathOverridesFromCliOptions(Object.fromEntries(PATH_OPTIONS.map(({ key, option }) => [option, options[key]])));
+		invocationCore = Object.keys(pathOverrides).length === 0 && deps.core ? deps.core : openCore({
+			env,
+			platform,
+			pathOverrides,
+			caller: RESEND_CALLER
+		});
+		return invocationCore;
+	};
+	/** This installation's own `--help`, for a usage error or an empty command line: it opens no folder, so pins none. */
+	const help = () => cliHandoffs({
+		caller: RESEND_CALLER,
+		paths: resolvePaths({
+			env,
+			platform
+		}),
+		platform,
+		env
+	}).own(["--help"], { uses: [] });
 	const globals = () => {
 		const options = program.opts();
 		return {
@@ -3182,7 +3221,7 @@ is out: update first, or put it off (agentcomms update, agentcomms update --late
 	program.hook("preAction", async (_program, command) => {
 		const path = commandPathOf(command);
 		if (exemptFromUpdateGate(path, ["update-check-child"])) return;
-		const core = openCore({ env });
+		const core = coreForInvocation();
 		let ended = null;
 		const code = await runCommand(output(), async () => {
 			ended = await updateGateAtTerminal({
@@ -3194,13 +3233,11 @@ is out: update first, or put it off (agentcomms update, agentcomms update --late
 				output: output(),
 				noInput: false,
 				streams,
-				approveCommand: "agent-resend approve",
 				approvals: approvalsOf(command),
 				approvalClaim: path.join(" ") === "send status" ? SEND_LOOKUP : void 0,
 				...terminalUpdateHooks(core, env, {
 					output: output(),
-					streams,
-					approveCommand: "agent-resend approve"
+					streams
 				})
 			});
 		}, streams);
@@ -3213,24 +3250,29 @@ is out: update first, or put it off (agentcomms update, agentcomms update --late
 			exitCode = gated;
 			return;
 		}
+		const core = coreForInvocation();
 		const context = new ResendContext({
 			...deps,
+			core,
 			env,
+			pathOverrides: core.pathOverrides,
 			surface: "cli"
 		});
 		exitCode = await runCommand(output(), () => body(context, globals(), ...args), streams);
 		if (exitCode === 0 && softExit !== null) exitCode = softExit;
 	};
-	/** A change the way every changing command runs one: core's `gatedChangeAtTerminal`. */
-	const changeAt = (context, change, flags, command) => gatedChangeAtTerminal(context.core, change, {
+	/**
+	* A change the way every changing command runs one: core's `gatedChangeAtTerminal`. `rerun` is this command's words
+	* after the program, which core locates as Resend's own and runs again with `--approval <id>`.
+	*/
+	const changeAt = (context, change, flags, rerun) => gatedChangeAtTerminal(context.core, change, {
 		approvalId: flags.approval === void 0 ? void 0 : String(flags.approval),
 		env,
 		output: output(),
-		command,
-		approveCommand: "agent-resend approve",
+		rerun,
 		streams
 	});
-	const approvalOption = (command) => command.option("--approval <approvalId>", "apply a change a person approved: said yes to in chat, or approved with `agent-resend approve`");
+	const approvalOption = (command) => command.option("--approval <approvalId>", "apply a change a person approved: said yes to in chat, or approved with the approve command it gave");
 	const accountOption = (command) => command.requiredOption("--account <name>", "which account, as `organisation/resend`");
 	const account = program.command("account").description("connect, inspect, re-police and remove Resend accounts");
 	approvalOption(account.command("add <name>").description("connect a Resend API key, typed by a person at this terminal (or RESEND_API_KEY); never from a chat").addOption(new Option("--mode <mode>", "read (the default for a full-access key) or send").choices(["read", "send"])).addOption(new Option("--send <policy>", "how its sends are approved; the machine default if left out").choices([
@@ -3239,19 +3281,18 @@ is out: update first, or put it off (agentcomms update, agentcomms update --late
 		"never"
 	])).option("--domain <domain>", "for a sending-only key restricted to one domain: that domain")).action(act(async (context, options, name, flags) => {
 		const mode = modeOf(flags.mode);
-		const command = shellCommand([
-			"agent-resend",
+		const rerun = [
 			"account",
 			"add",
 			name,
 			...mode ? ["--mode", mode] : [],
 			...flags.send ? ["--send", String(flags.send)] : [],
 			...flags.domain ? ["--domain", String(flags.domain)] : []
-		], platform);
-		checkNewName(await context.config(), name, context.platform);
+		];
+		checkNewName(await context.config(), name, context.handoffs);
 		const key = await readApiKey(env, streams, {
 			json: options.json,
-			command
+			command: context.handoffs.own(rerun)
 		});
 		const inspection = await inspectKey(context, key);
 		const added = await changeAt(context, addAccountChange(context, {
@@ -3260,24 +3301,23 @@ is out: update first, or put it off (agentcomms update, agentcomms update --late
 			mode,
 			sendPolicy: sendPolicyOf(flags.send),
 			domain: flags.domain === void 0 ? void 0 : String(flags.domain)
-		}, inspection), flags, command);
+		}, inspection), flags, rerun);
 		writeResult(added, output(), (data) => renderAdded(data, options.color), streams);
 	}));
 	account.command("list").description("the Resend accounts this machine can use, and what each may do").action(act(async (context, options) => {
 		const result = await listAccounts(context);
-		writeResult(result, output(), (data) => renderAccounts(data, options.color), streams);
+		writeResult(result, output(), (data) => renderAccounts(data, options.color, context.handoffs), streams);
 	}));
 	account.command("show <name>").description("one account: its key’s permission, its mode, its send policy, and who enforces what").action(act(async (context, options, name) => {
 		const result = await showAccount(context, name);
 		writeResult(result, output(), (data) => renderAccount(data, options.color), streams);
 	}));
 	approvalOption(account.command("remove <name>").description("forget an account and delete its key, once a person approves it")).action(act(async (context, _options, name, flags) => {
-		const removed = await changeAt(context, removeAccountChange(context, name), flags, shellCommand([
-			"agent-resend",
+		const removed = await changeAt(context, removeAccountChange(context, name), flags, [
 			"account",
 			"remove",
 			name
-		], platform));
+		]);
 		writeResult(removed, output(), renderRemoved, streams);
 	}));
 	approvalOption(account.command("policy <name>").description("report how its sends and changes are approved, or set --send, --mode and --change; loosening is approved by a person").option("--send <policy>", "chat, confirm or never").option("--mode <mode>", "read or send").option("--change <policy>", "how a loosening of this account is approved: chat or confirm")).action(act(async (context, _options, name, flags) => {
@@ -3288,15 +3328,14 @@ is out: update first, or put it off (agentcomms update, agentcomms update --late
 		});
 		const reporting = wanted.send === void 0 && wanted.mode === void 0 && wanted.change === void 0;
 		if (reporting) refuseUnclaimedApproval(flags.approval, policyApprovalRefusal("cli"));
-		const result = reporting ? await policyReport(context, name) : await changeAt(context, policyChange(context, name, wanted), flags, shellCommand([
-			"agent-resend",
+		const result = reporting ? await policyReport(context, name) : await changeAt(context, policyChange(context, name, wanted), flags, [
 			"account",
 			"policy",
 			name,
 			...wanted.send ? ["--send", wanted.send] : [],
 			...wanted.mode ? ["--mode", wanted.mode] : [],
 			...wanted.change ? ["--change", wanted.change] : []
-		], platform));
+		]);
 		writeResult(result, output(), renderPolicy, streams);
 	}));
 	program.command("doctor").description("check what has to work, and say who enforces what — read-only is this package’s promise, not the key’s").option("--account <name>", "check only this account").option("--offline", "do not ask Resend anything", false).action(act(async (context, options, flags) => {
@@ -3397,31 +3436,23 @@ is out: update first, or put it off (agentcomms update, agentcomms update --late
 		writeResult(result, output(), (data) => renderRead(data, options.color), streams);
 	}));
 	approvalOption(accountOption(scheduled.command("cancel <id>")).description("cancel a scheduled email; one this machine did not schedule is approved by a person first")).action(act(async (context, _options, id, flags) => {
-		const cancelled = await changeAt(context, cancelScheduledChange(context, String(flags.account), id), flags, shellCommand([
-			"agent-resend",
+		const cancelled = await changeAt(context, cancelScheduledChange(context, String(flags.account), id), flags, [
 			"scheduled",
 			"cancel",
 			id,
 			"--account",
 			String(flags.account)
-		], platform));
+		]);
 		writeResult(cancelled, output(), renderCancelled, streams);
 	}));
 	program.command("approve <approvalId>").description("approve a send or a change at this terminal: read it, then type the code back").action(act(async (context, options, approvalId) => {
 		const marker = agentMarker(env);
+		const approve = context.handoffs.own(["approve", approvalId]);
 		if (marker) throw new CommsError("APPROVAL_REQUIRED", "only a person can approve a send or a change, not an agent", {
-			hint: `Ask the user to run ${inlineCommand(shellCommand([
-				"agent-resend",
-				"approve",
-				approvalId
-			], context.platform))} in their own terminal.`,
+			hint: handoffSentence(approve, (command) => `Ask the user to run ${command} in their own terminal.`),
 			details: { marker }
 		});
-		if (!canPrompt(env, streams, { json: options.json })) throw new CommsError("APPROVAL_REQUIRED", "approving needs an interactive terminal", { hint: `Run ${inlineCommand(shellCommand([
-			"agent-resend",
-			"approve",
-			approvalId
-		], context.platform))} directly in a terminal.` });
+		if (!canPrompt(env, streams, { json: options.json })) throw new CommsError("APPROVAL_REQUIRED", "approving needs an interactive terminal", { hint: handoffSentence(approve, (command) => `Run ${command} directly in a terminal.`) });
 		const pending = await context.core.approvals.get(approvalId);
 		if (pending && approvalKind(pending) === "change") {
 			const outcome = await approveChangeAtTerminal(context.core, approvalId, env, {
@@ -3445,10 +3476,14 @@ is out: update first, or put it off (agentcomms update, agentcomms update --late
 	}));
 	const mcp = program.command("mcp").description("run the MCP server on stdio, for a coding agent to connect to").option("--account <name>", "pin the server to one account; every tool then acts on it and no other").action(async (flags) => {
 		ran = true;
-		const { startResendStdioServer } = await import("./stdio-entry-BCnq_EyF.mjs");
+		const startResendStdioServer = deps.startMcp ?? (await import("./stdio-entry-CUFTANFM.mjs")).startResendStdioServer;
+		const core = coreForInvocation();
 		await startResendStdioServer({
 			...deps,
+			core,
 			env,
+			pathOverrides: core.pathOverrides,
+			platform,
 			...flags.account ? { account: String(flags.account) } : {}
 		});
 	});
@@ -3465,12 +3500,16 @@ is out: update first, or put it off (agentcomms update, agentcomms update --late
 		"npx",
 		"local"
 	])).option("--no-verify", "do not start the server to check the entry works").option("--force", "replace this server's own earlier entry — this is how you upgrade", false).option("--print", "only print what would be written", false).option("--approval <approvalId>", "register the server this approval was given for").action(act(async (context, options, flags) => {
-		if (!flags.client) throw new CommsError("USAGE", "name the client with --client", { hint: "For example: `agent-resend mcp install --client claude-code`." });
+		if (!flags.client) throw new CommsError("USAGE", "name the client with --client", { hint: handoffSentence(context.handoffs.own([
+			"mcp",
+			"install",
+			"--client",
+			"claude-code"
+		]), (command) => `For example: ${command}.`) });
 		const pinned = flags.account ?? mcp.opts().account;
 		const launcher = flags.launcher;
 		const name = flags.name;
-		const again = shellCommand([
-			"agent-resend",
+		const again = [
 			"mcp",
 			"install",
 			"--client",
@@ -3480,7 +3519,7 @@ is out: update first, or put it off (agentcomms update, agentcomms update --late
 			...launcher !== void 0 ? ["--launcher", launcher] : [],
 			...flags.verify === false ? ["--no-verify"] : [],
 			...flags.force === true ? ["--force"] : []
-		], platform);
+		];
 		const result = await changeAt(context, serverInstallChange(context.core, env, {
 			channel: "resend",
 			client: flags.client,
@@ -3500,12 +3539,11 @@ is out: update first, or put it off (agentcomms update, agentcomms update --late
 			channel: "resend",
 			dryRun: flags.dryRun === true,
 			includePrinted: flags.includePrinted === true
-		}, RESEND_MCP), flags, shellCommand([
-			"agent-resend",
+		}, RESEND_MCP), flags, [
 			"mcp",
 			"prune",
 			...flags.includePrinted === true ? ["--include-printed"] : []
-		], platform));
+		]);
 		writeResult(result, output(), () => renderPrune(result, options.color), streams);
 	}));
 	program.command(`${UPDATE_CHECK_CHILD_COMMAND} <claimedAt>`, { hidden: true }).description("internal: finish the day's update check a command handed on").action(act(async (context, _options, claimedAt) => {
@@ -3522,13 +3560,13 @@ is out: update first, or put it off (agentcomms update, agentcomms update --late
 			].includes(error.code)) return 0;
 			const message = withoutOptionValues(error.message.replace(/^error: /, ""));
 			return runCommand(output(), async () => {
-				throw new CommsError("USAGE", message, { hint: "Run `agent-resend --help` to see the commands." });
+				throw new CommsError("USAGE", message, { hint: usageHint(help()) });
 			}, streams);
 		}
 		throw error;
 	}
 	if (!ran) {
-		streams.stderr.write(`${paint(globals().color, "dim", "Nothing to do. Try `agent-resend --help`.")}\n`);
+		streams.stderr.write(`${paint(globals().color, "dim", nothingToDo(help()))}\n`);
 		return 64;
 	}
 	return exitCode;