hey-axi 0.3.0 → 0.3.2

package/src/policy.js

@@ -1,7 +1,7 @@
 // What hey-axi will and won't run, beyond "is it a HEY command".
 
 // hey-axi's own flags. Stripped before anything is forwarded to HEY.
-export const AXI_FLAGS = ["--allow-send", "--allow-secret"];
+export const AXI_FLAGS = ["--allow-send", "--allow-secret", "--allow-destructive"];
 
 // Commands that deliver email.
 //   safe:  HEY flags that already mean nothing is sent
@@ -20,6 +20,18 @@ export const DRAFT_NOTICE = "Saved as a DRAFT. Nothing was sent. Pass --allow-se
 // Commands that print a credential into the agent's context.
 const SECRET_COMMANDS = new Set(["auth token"]);
 
+// Commands that destroy a whole set of things at once, with no confirmation from HEY and
+// no single command that undoes them. Refused unless --allow-destructive (or
+// HEY_AXI_ALLOW_DESTRUCTIVE=1).
+//   what:    what the command would do, in the refusal
+//   instead: what to do first, in the refusal
+const DESTRUCTIVE_COMMANDS = new Map([
+  ["screener clear", {
+    what: "moves everything waiting in the Screener to Trash (the whole queue for the account, every sender, not one; shared threads lose your access instead) without asking. It approves or denies no one, so those senders come back to the Screener on their next email",
+    instead: "check what is waiting with `hey-axi screener list`, and decide one sender at a time with `hey-axi screener deny <clearance-id>` (or `screener approve`); to really clear the whole queue, confirm with the user, then pass --allow-destructive (or set HEY_AXI_ALLOW_DESTRUCTIVE=1)",
+  }],
+]);
+
 // How a command runs. Anything not listed is "json": captured, parsed, rendered as TOON.
 //   stream: long-running NDJSON, relayed event by event as it arrives (TOON, or NDJSON with --json)
 //   raw:    prints non-JSON (a script, a CSV); relayed untouched
@@ -157,14 +169,27 @@ const NAMED_CONTAINER = /\b(?:label|collection|group|workflow|box)\s+["'“]?([^
 export function noopFor(path, failure, positionals = [], values = {}) {
   const text = `${failure.error || ""} ${failure.hint || ""}`;
   const target = positionals.length ? ` ${positionals.join(" ")}` : "";
-  if (DELETES.has(path) && failure.kind === "not_found" && (GENERIC_NOT_FOUND.test(failure.error || "") || DELETES.get(path).test(failure.error || ""))) {
+  // One day of a repeating event (--occurrence) is not "already gone" on a not-found:
+  // the day may simply not be in the series (a wrong date), so it stays an error.
+  const occurrence = path === "event delete" && values.occurrence;
+  if (DELETES.has(path) && !occurrence && failure.kind === "not_found" && (GENERIC_NOT_FOUND.test(failure.error || "") || DELETES.get(path).test(failure.error || ""))) {
     return { ok: true, noop: true, command: path, result: `nothing to delete:${target || " it"} is already gone (no-op)`, note: "if you expected it to exist, check the id with the matching list command" };
   }
   const endState = END_STATES[path];
-  // Several targets: if HEY names some of them, it must name all of them.
+  if (!endState) return null;
+  // The ids asked for must be the ones HEY's message is about. Every number the message
+  // names has to be one of them (or the --to/--from container), and when it names any,
+  // it has to name them all: "1 already seen" is not about `seen 2`, and "5 already
+  // seen" is not about `seen 5 6`. A bare count is only accepted for the whole batch
+  // ("all 2 already seen"). A message naming no number at all ("Already seen") stands.
   const ids = positionals.filter((word) => /^\d+$/.test(word));
-  if (ids.length > 1) {
-    const named = ids.filter((id) => new RegExp(`\\b${id}\\b`).test(text));
+  if (ids.length) {
+    const allowed = new Set([...ids, ...["to", "from"].map((key) => values[key]).filter((value) => value !== undefined).map(String)]);
+    const numbers = [...text.matchAll(/(?<![\w.-])\d+(?![\w.-])/g)].map((match) => match[0]);
+    const strangers = numbers.filter((number) => !allowed.has(number));
+    const wholeBatch = strangers.length === 1 && Number(strangers[0]) === ids.length && new RegExp(`\\ball ${strangers[0]}\\b`, "i").test(text);
+    if (strangers.length && !wholeBatch) return null;
+    const named = ids.filter((id) => numbers.includes(id));
     if (named.length && named.length < ids.length) return null;
   }
   if (CONTAINER[path]) {
@@ -177,7 +202,7 @@ export function noopFor(path, failure, positionals = [], values = {}) {
   if (DESTINATION[path] && (!destination || !text.toLowerCase().includes(String(destination).toLowerCase()))) return null;
   // A failure that also reports a failed part ("1 already seen; 2 failed") is not a no-op.
   if (/\b(failed|cannot|can'?t|could ?n[o']t|unable|error)\b/i.test(failure.error || "")) return null;
-  if (endState && failure.kind !== "auth" && failure.kind !== "forbidden" && failure.kind !== "not_found" && endState.test(text)) {
+  if (failure.kind !== "auth" && failure.kind !== "forbidden" && failure.kind !== "not_found" && endState.test(text)) {
     return { ok: true, noop: true, command: path, result: `already done${target ? ` for${target}` : ""} (no-op)`, detail: failure.error };
   }
   return null;
@@ -193,6 +218,14 @@ export function sendCommands() {
   return [...SEND_COMMANDS.keys()];
 }
 
+export function destructiveCommands() {
+  return [...DESTRUCTIVE_COMMANDS.keys()];
+}
+
+function destructiveAllowed(flags, env) {
+  return flags.has("--allow-destructive") || truthy(env.HEY_AXI_ALLOW_DESTRUCTIVE);
+}
+
 function sendAllowed(flags, env) {
   return flags.has("--allow-send") || truthy(env.HEY_AXI_ALLOW_SEND);
 }
@@ -230,5 +263,15 @@ export function checkPolicy(path, flags, env = process.env, io = { stdin: proces
       hint: "pass --allow-secret (or set HEY_AXI_ALLOW_SECRETS=1) if you really need it",
     };
   }
+
+  if (DESTRUCTIVE_COMMANDS.has(path) && !destructiveAllowed(flags, env)) {
+    const rule = DESTRUCTIVE_COMMANDS.get(path);
+    return {
+      error: "destructive command blocked",
+      command: path,
+      reason: `this command ${rule.what}. hey-axi did not run it, so nothing was changed`,
+      hint: rule.instead,
+    };
+  }
   return null;
 }

package/src/router.js

@@ -38,6 +38,17 @@ export function normalizeCatalog(nodes, types = {}) {
   });
 }
 
+// Which HEY the manifest covers, in words: "v1.7.0", or for a snapshot of an unreleased
+// branch ("1.7.0+main.9dfe00f") "v1.7.0 plus the commands on HEY main as of 2026-10-06
+// (commit 9dfe00f, unreleased)".
+export function coverageLabel(manifest) {
+  const version = String(manifest.hey_version || "unknown");
+  const match = version.match(/^(\d+\.\d+\.\d+)\+([\w.-]+)\.([0-9a-f]{7,})$/);
+  if (!match) return /^\d/.test(version) ? `v${version}` : version;
+  const date = manifest.hey_commit_date ? ` as of ${manifest.hey_commit_date}` : "";
+  return `v${match[1]} plus the commands on HEY ${match[2]}${date} (commit ${match[3]}, unreleased)`;
+}
+
 export function loadBundledManifest() {
   return JSON.parse(readFileSync(new URL("./manifest.json", import.meta.url), "utf8"));
 }

package/src/send.js

@@ -0,0 +1,121 @@
+// Reading what HEY says about outgoing mail.
+//
+// HEY CLI v1.7.0 answers a send with a summary only. HEY's main branch (unreleased as of
+// 2026-10-06, commit 9dfe00f) also:
+//   - names what went out: data.id (the message), data.topic_id (its thread), subject,
+//     and delayed (true while Undo Send holds it back; the thread doesn't show it yet)
+//   - fails a send HEY refused (usually the sending limit) with code not_delivered (exit 7),
+//     naming the draft HEY kept in meta.draft_id; sending again only makes another draft
+//   - refuses a --to/--cc/--bcc address it would otherwise drop (code usage,
+//     "not a valid email address: X") before anything is sent
+// hey-axi reads both shapes. It also refuses clearly broken addresses itself, before HEY
+// runs, so a v1.7.0 HEY can't silently drop a recipient either.
+
+// Commands whose recipient flags HEY checks (compose, reply, forward, draft edit).
+export const RECIPIENT_COMMANDS = new Set(["compose", "reply", "forward", "draft edit"]);
+const RECIPIENT_FLAGS = new Set(["--to", "--cc", "--bcc"]);
+
+// Split a recipient list on commas outside quotes, comments and angle brackets
+// ("Bryan, Annie" <annie@example.com> is one recipient).
+export function splitAddresses(text) {
+  const out = [];
+  let current = "";
+  let quoted = false;
+  let depth = 0;
+  let angled = false;
+  for (const char of String(text)) {
+    if (char === "\"" && depth === 0) quoted = !quoted;
+    else if (!quoted && char === "(") depth += 1;
+    else if (!quoted && char === ")" && depth > 0) depth -= 1;
+    else if (!quoted && depth === 0 && char === "<") angled = true;
+    else if (!quoted && depth === 0 && char === ">") angled = false;
+    if (char === "," && !quoted && depth === 0 && !angled) {
+      if (current.trim()) out.push(current.trim());
+      current = "";
+    } else current += char;
+  }
+  if (current.trim()) out.push(current.trim());
+  return out;
+}
+
+// A deliberately loose check: a local part, an @, and a domain with a dot and a top-level
+// part of two or more characters. Anything it refuses, HEY refuses too (or, before its
+// main branch, silently drops); HEY's own, stricter check still runs after it.
+const ADDRESS = /^[^\s@<>()",;]+@[^\s@<>()",;]+\.[^\s@<>()",;.]{2,}$/u;
+
+export function invalidAddress(entry) {
+  const angle = entry.match(/<([^<>]*)>\s*$/);
+  const address = (angle ? angle[1] : entry).trim();
+  return ADDRESS.test(address) ? null : address || entry;
+}
+
+// Returns null, or a refusal (exit 2) naming the first address HEY would drop.
+export function recipientProblem(path, values = []) {
+  if (!RECIPIENT_COMMANDS.has(path)) return null;
+  for (const [name, value] of values) {
+    if (!RECIPIENT_FLAGS.has(name)) continue;
+    for (const entry of splitAddresses(value)) {
+      const bad = invalidAddress(entry);
+      if (bad) return recipientRefusal(path, bad);
+    }
+  }
+  return null;
+}
+
+export function recipientRefusal(path, address) {
+  return {
+    error: `not a valid email address: ${address}`,
+    command: path,
+    sent: false,
+    reason: "HEY would drop this recipient without saying so (no domain, or no top-level domain); nothing was sent",
+    hint: `fix or remove "${address}": every recipient needs a full address such as name@example.com`,
+  };
+}
+
+// HEY's own refusal of a recipient, as its error line words it.
+export const HEY_BAD_ADDRESS = /^not a valid email address: (.+)$/i;
+
+// The draft HEY kept when it refused a send: meta.draft_id, else the id in its hint or message.
+export function keptDraftId(envelope) {
+  const fromMeta = envelope?.meta?.draft_id;
+  if (fromMeta !== undefined && fromMeta !== null && /^\d+$/.test(String(fromMeta))) return String(fromMeta);
+  const text = `${envelope?.hint || ""} ${envelope?.error || ""}`;
+  const match = text.match(/\bdraft(?: send)? (\d+)\b/i);
+  return match ? match[1] : null;
+}
+
+// The failure for a send HEY refused and kept as a draft: never retry the send.
+export function notDelivered(envelope) {
+  const draft = keptDraftId(envelope);
+  const failure = {
+    ok: false,
+    kind: "not_delivered",
+    sent: false,
+    error: draft
+      ? `not sent: HEY kept the message as draft ${draft} instead of sending it (usually the account's sending limit)`
+      : "not sent: HEY kept the message as a draft instead of sending it (usually the account's sending limit)",
+  };
+  if (draft) failure.draft_id = draft;
+  failure.help = draft
+    ? [
+      `Run \`hey-axi draft show ${draft}\` to review it`,
+      `Run \`hey-axi draft send ${draft} --allow-send\` later, once the account can send again; don't repeat the send, which only makes another draft`,
+    ]
+    : ["Run `hey-axi draft list` to find the draft HEY kept; don't repeat the send, which only makes another draft"];
+  return failure;
+}
+
+// Mark a delivered message's result. `data` is HEY's answer: v1.7.0 names nothing; main
+// names id, topic_id, subject and delayed. Nothing is guessed when HEY leaves it out.
+export function markSent(result) {
+  if (!result || typeof result !== "object" || Array.isArray(result)) return result;
+  const data = result.data && typeof result.data === "object" && !Array.isArray(result.data) ? result.data : {};
+  const marker = { sent: true };
+  if (data.delayed === true) {
+    // topic_id is the thread it is on (forward's thread_id names the thread forwarded).
+    const thread = data.topic_id;
+    marker.held = `Undo Send is holding it back: it goes out when HEY releases it, and until then ${thread !== undefined ? `\`hey-axi thread read ${thread}\`` : "the thread"} won't show it (a thread it starts reads as not found)`;
+  }
+  const { ok, ...rest } = result;
+  return ok === undefined ? { ...marker, ...rest } : { ok, ...marker, ...rest };
+}

package/src/shape.js

@@ -38,7 +38,7 @@ export const LIST_FIELDS = {
   "event week": EVENTS,
   "todo list": ["id", "title", "starts_at", "completed_at"],
   "habit list": ["id", "title=title|name", "days"],
-  "journal list": ["id", "starts_at", "content"],
+  "journal list": ["id", "date=date|starts_at"],
   "draft list": ["id", "subject", "summary", "at=updated_at|created_at"],
   "contact list": ["id", "name", "email_address"],
   "label list": NAMED,
@@ -46,8 +46,8 @@ export const LIST_FIELDS = {
   "workflow list": NAMED,
   "calendar list": ["id", "name", "kind", "owned"],
   "attachment list": ["id", "filename", "content_type", "byte_size"],
-  "clip list": ["id", "content", "topic_id", "at=created_at"],
-  "snippet list": ["id", "name", "content"],
+  "clip list": ["id", "topic_id=topic_id|topic.id", "at=created_at"],
+  "snippet list": ["id", "name"],
   "timetrack list": ["id", "starts_at", "ends_at", "category"],
   "timetrack categories": ["id", "title"],
   "account list": ["id", "email=email|email_address", "name", "active"],
@@ -55,6 +55,14 @@ export const LIST_FIELDS = {
 };
 
 // Detail views keep their long text (truncated), but drop URLs and duplicated fields.
+// Lists whose entries are long-form content: the list shows ids and dates only, and a help
+// line says how to get the content (AXI principle 2: long text belongs in detail views).
+export const CONTENT_LISTS = {
+  "journal list": (line, carry) => `Run \`${withSelectors("hey-axi journal read <date>", carry)}\` to read one entry, or \`${line} --fields id,starts_at,content\` to include previews`,
+  "clip list": (line) => `Run \`${line} --fields id,content\` to include each clip's content`,
+  "snippet list": (line) => `Run \`${line} --fields id,name,content\` to include each snippet's content`,
+};
+
 export const DETAIL_FIELDS = {
   "thread read": ["id", "at=created_at", "from=creator.name|sender.name", "email=creator.email_address|sender.email_address", "to=recipients.to[].email_address", "cc=recipients.cc[].email_address", "body=body|summary"],
 };
@@ -279,7 +287,8 @@ export function listSize(envelope, shown, container = null) {
 export function countLine({ shown, total, more, complete, all = false }) {
   if (total !== undefined) return `${shown} of ${total} total`;
   if (more) return `${shown} shown; more available`;
-  return complete || all || shown === 0 ? `${shown} total` : `${shown} shown; no more pages reported`;
+  // An empty page is only "0 total" when HEY says nothing is left (or --all fetched everything).
+  return complete || all ? `${shown} total` : `${shown} shown; no more pages reported`;
 }
 
 // Append the invocation's selectors (`--account 2`) to a suggested command, unless the
@@ -372,6 +381,7 @@ export function shapeEnvelope(envelope, { path, fields = null, commandLine, carr
   const more = (size || multiSize) && moreHelp(size || multiSize, { commandLine, pageFlags });
   if (more) help.push(more);
   if (truncated) help.push(`Run \`${commandLine} --full\` to see complete content`);
+  if (CONTENT_LISTS[path] && !fields && !empty && found) help.push(CONTENT_LISTS[path](commandLine, carry));
   if (help.length) out.help = help;
   if (enveloped && !quiet && envelope.meta && typeof envelope.meta === "object") {
     const meta = { ...envelope.meta };

package/src/version.js

@@ -1,3 +1,3 @@
 // Leaf module: no imports, so `hey-axi --version` answers before the CLI graph loads.
 // test/version.test.js keeps this in sync with package.json.
-export const VERSION = "0.3.0";
+export const VERSION = "0.3.2";