hey-axi 0.2.0 → 0.3.0

package/src/activity.js

@@ -0,0 +1,160 @@
+// Session lifecycle capture (AXI principle 7). Once `hey-axi setup hooks` has been run,
+// hey-axi notes what it did in each directory scope (command paths and numeric ids only:
+// no subjects, bodies or addresses) in a local journal. The session-end hook
+// (`hey-axi hook session-end`) folds the journal into a one-line summary of the session,
+// and the next session's home view shows it, so new sessions start knowing which drafts
+// are waiting and what was already triaged. `setup hooks --remove` turns capture off and
+// deletes the journal.
+//
+// State lives in $HEY_AXI_STATE_DIR, else $XDG_STATE_HOME/hey-axi, else ~/.local/state/hey-axi.
+
+import { appendFileSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { createHash } from "node:crypto";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+export function stateDir(env = process.env) {
+  if (env.HEY_AXI_STATE_DIR) return env.HEY_AXI_STATE_DIR;
+  return join(env.XDG_STATE_HOME || join(homedir(), ".local", "state"), "hey-axi");
+}
+
+const files = (dir = stateDir()) => ({
+  dir,
+  enabled: join(dir, "capture-enabled"),
+  journal: join(dir, "activity.jsonl"),
+  sessions: join(dir, "sessions"),
+});
+
+export function captureEnabled() {
+  return existsSync(files().enabled);
+}
+
+export function enableCapture() {
+  const f = files();
+  mkdirSync(f.dir, { recursive: true });
+  if (existsSync(f.enabled)) return false;
+  writeFileSync(f.enabled, "hey-axi session capture is on; `hey-axi setup hooks --remove` turns it off\n");
+  return true;
+}
+
+export function disableCapture() {
+  const f = files();
+  const had = existsSync(f.enabled) || existsSync(f.journal) || existsSync(f.sessions);
+  rmSync(f.enabled, { force: true });
+  rmSync(f.journal, { force: true });
+  rmSync(f.sessions, { recursive: true, force: true });
+  return had;
+}
+
+// The agent session a command ran in, when the harness says: Claude Code sets
+// CLAUDE_CODE_SESSION_ID and Codex CODEX_THREAD_ID in the commands they run, matching the
+// session_id their session-end hooks receive. HEY_AXI_SESSION_ID overrides both.
+export function sessionIdFrom(env = process.env) {
+  return env.HEY_AXI_SESSION_ID || env.CLAUDE_CODE_SESSION_ID || env.CODEX_THREAD_ID || env.CODEX_SESSION_ID || env.OPENCODE_SESSION_ID || "";
+}
+
+const SUMMARY_LIMIT = 300;
+
+const scopeKey = (scopeDir) => createHash("sha256").update(scopeDir).digest("hex").slice(0, 16);
+
+const READ_WORDS = new Set(["list", "view", "show", "read", "status", "history", "categories", "current", "filters", "preview", "senders", "token", "day", "week", "trusted-locals"]);
+const READ_COMMANDS = new Set(["search", "box", "label", "collection", "bundle", "workflow", "set-aside", "set-aside group", "doctor", "version", "commands", "config show"]);
+
+// "read", "mutation" or null (not worth remembering).
+export function activityKind(path) {
+  if (path === "thread read") return "read";
+  const last = path.split(" ").pop();
+  if (READ_WORDS.has(last) || READ_COMMANDS.has(path) || path.startsWith("auth") || path.startsWith("setup") || path.startsWith("shell-completion") || path === "watch") return null;
+  return "mutation";
+}
+
+// Append one entry. Never throws: capture must not break a command.
+export function recordActivity({ path, positionals = [], staged = false, sent = false, scopeDir }) {
+  try {
+    if (!captureEnabled()) return;
+    const kind = staged ? "draft" : sent ? "sent" : activityKind(path);
+    if (!kind) return;
+    const ids = positionals.filter((word) => /^\d+$/.test(word)).slice(0, 20);
+    const f = files();
+    const session = sessionIdFrom();
+    appendFileSync(f.journal, `${JSON.stringify({ at: new Date().toISOString(), scope: scopeKey(scopeDir), ...(session ? { session } : {}), path, kind, ids })}\n`);
+  } catch {
+    // capture is best-effort
+  }
+}
+
+function readJournal(f) {
+  if (!existsSync(f.journal)) return [];
+  return readFileSync(f.journal, "utf8").split("\n").filter(Boolean).flatMap((line) => {
+    try {
+      return [JSON.parse(line)];
+    } catch {
+      return [];
+    }
+  });
+}
+
+function summarize(entries) {
+  const groups = new Map();
+  for (const entry of entries) {
+    const key = entry.kind === "draft" ? `${entry.path} (saved as draft, not sent)` : entry.kind === "sent" ? `${entry.path} (sent)` : entry.path;
+    const group = groups.get(key) || { count: 0, ids: [] };
+    group.count += 1;
+    group.ids.push(...entry.ids);
+    groups.set(key, group);
+  }
+  const line = [...groups].map(([key, { count, ids }]) => {
+    const shown = [...new Set(ids)].slice(0, 5);
+    return `${key} ×${count}${shown.length ? ` [${shown.join(", ")}${ids.length > shown.length ? ", …" : ""}]` : ""}`;
+  }).join("; ");
+  // Session-start context loads every session: keep it to one short line.
+  return line.length > SUMMARY_LIMIT ? `${line.slice(0, SUMMARY_LIMIT)}… (${groups.size} kinds of action)` : line;
+}
+
+// The session-end hook: fold this session's journal entries (in this scope) into the
+// scope's last-session summary. With a session id, only that session's entries (and
+// entries whose session is unknown) are taken, so concurrent sessions in the same
+// directory don't merge. A session with no hey-axi activity leaves the previous
+// summary in place.
+export function endSession(scopeDir, sessionId = "") {
+  const f = files();
+  if (!existsSync(f.enabled)) return { captured: 0 };
+  const key = scopeKey(scopeDir);
+  const entries = readJournal(f);
+  const isMine = (entry) => entry.scope === key && (!sessionId || !entry.session || entry.session === sessionId);
+  const mine = entries.filter(isMine);
+  if (!mine.length) return { captured: 0 };
+  mkdirSync(f.sessions, { recursive: true });
+  const summary = {
+    ended_at: new Date().toISOString(),
+    started_at: mine[0].at,
+    summary: summarize(mine),
+    drafts: mine.filter((entry) => entry.kind === "draft").length,
+  };
+  writeFileSync(join(f.sessions, `${key}.json`), `${JSON.stringify(summary)}\n`);
+  const rest = entries.filter((entry) => !isMine(entry));
+  writeFileSync(f.journal, rest.map((entry) => `${JSON.stringify(entry)}\n`).join(""));
+  return { captured: mine.length };
+}
+
+function localTime(iso) {
+  const date = new Date(iso);
+  const pad = (n) => String(n).padStart(2, "0");
+  const offset = -date.getTimezoneOffset();
+  const sign = offset >= 0 ? "+" : "-";
+  return `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())} ${pad(date.getHours())}:${pad(date.getMinutes())} (UTC${sign}${pad(Math.floor(Math.abs(offset) / 60))}:${pad(Math.abs(offset) % 60)})`;
+}
+
+// { line, drafts } for the home view, or null.
+export function lastSession(scopeDir) {
+  try {
+    const f = files();
+    if (!existsSync(f.enabled)) return null;
+    const path = join(f.sessions, `${scopeKey(scopeDir)}.json`);
+    if (!existsSync(path)) return null;
+    const summary = JSON.parse(readFileSync(path, "utf8"));
+    return { line: `ended ${localTime(summary.ended_at)}: ${summary.summary}`, drafts: summary.drafts };
+  } catch {
+    return null;
+  }
+}

package/src/args.js

@@ -8,7 +8,7 @@ export const GLOBAL_BOOLEAN_FLAGS = ["json", "quiet", "ids-only", "count", "mark
 export const GLOBAL_SHORTHANDS = ["-v", "-h"];
 
 // hey-axi's own flags. Never forwarded to HEY.
-export const AXI_BOOLEAN_FLAGS = ["allow-send", "allow-secret", "full"];
+export const AXI_BOOLEAN_FLAGS = ["allow-send", "allow-secret", "full", "interactive"];
 export const AXI_VALUE_FLAGS = ["fields"];
 
 // Output selectors that make HEY print something other than a JSON envelope. When any is
@@ -31,11 +31,15 @@ export function valueFlagSet(commands) {
   return names;
 }
 
-// Split argv into positional words (for routing) and flag names (for mode selection).
-// The argv itself is never reordered: HEY (cobra) accepts flags anywhere.
+// Split argv into positional words (for routing and arity) and flag names (for mode
+// selection). Also returns each flag's value and the value flags that are missing one
+// (`--limit` at the end, or followed by another flag). The argv itself is never
+// reordered: HEY (cobra) accepts flags anywhere.
 export function scanArgs(argv, valueFlags) {
   const words = [];
   const flags = new Set();
+  const values = [];
+  const missing = [];
   for (let i = 0; i < argv.length; i += 1) {
     const arg = argv[i];
     if (arg === "--") {
@@ -43,14 +47,51 @@ export function scanArgs(argv, valueFlags) {
       break;
     }
     if (arg.startsWith("-") && arg !== "-") {
-      const [name] = arg.split("=", 1);
+      // Shorthand with its value attached (`-mhi`) or stacked shorthands (`-vv`).
+      if (/^-[A-Za-z]./.test(arg) && !arg.startsWith("--")) {
+        // Each letter is a shorthand until one takes a value; the rest is its value.
+        // Every letter is recorded, so an unknown one (`-vZ`) is rejected by name.
+        for (let j = 1; j < arg.length; j += 1) {
+          const name = `-${arg[j]}`;
+          if (arg[j] === "=") {
+            values.push([`-${arg[j - 1]}`, arg.slice(j + 1)]);
+            break;
+          }
+          flags.add(name);
+          if (valueFlags.has(name)) {
+            values.push([name, arg.slice(arg[j + 1] === "=" ? j + 2 : j + 1)]);
+            break;
+          }
+        }
+        continue;
+      }
+      const eq = arg.indexOf("=");
+      const name = eq === -1 ? arg : arg.slice(0, eq);
       flags.add(name);
-      if (!arg.includes("=") && valueFlags.has(name)) i += 1;
+      if (eq !== -1) values.push([name, arg.slice(eq + 1)]);
+      else if (valueFlags.has(name)) {
+        const next = argv[i + 1];
+        if (next === undefined || looksLikeFlag(next)) missing.push(name);
+        else {
+          values.push([name, next]);
+          i += 1;
+        }
+      }
       continue;
     }
     words.push(arg);
   }
-  return { words, flags };
+  return { words, flags, values, missing: [...new Set(missing)] };
+}
+
+// "-5" and "-" are values; "--to" and "-m" are flags.
+function looksLikeFlag(arg) {
+  return arg === "--" || (arg.startsWith("-") && arg !== "-" && !/^-\d/.test(arg));
+}
+
+// The value flags of one command, plus the global and hey-axi ones.
+export function nodeValueFlags(node) {
+  return valueFlagSet(node ? [{ flags: node.flags }] : []);
 }
 
 export function hasAny(flags, names) {
@@ -92,23 +133,47 @@ const flagName = (flag) => (flag.startsWith("--") ? flag : flag.slice(0, 2));
 
 export function flagLabel(flag) {
   const short = flag.shorthand ? `, -${flag.shorthand}` : "";
-  return `--${flag.name}${short}${flag.value ? " <value>" : ""}`;
+  return `--${flag.name}${short}${flag.value ? ` <${flag.type || "value"}>` : ""}`;
 }
 
-// AXI: reject unknown flags (and missing required ones) before HEY is ever called.
-// Returns null, or { unknown: [...] } / { missing: [...] }.
-export function validateFlags(node, flags) {
+const GLOBAL_TYPES = { "--account": "string", "--jq": "string", "--base-url": "string", "--fields": "string" };
+const GO_DURATION = /^(0|([0-9]+(\.[0-9]+)?(ns|us|µs|ms|s|m|h))+)$/;
+
+function typeError(name, type, value) {
+  if (type === "int" && !/^-?\d+$/.test(value)) return `${name} needs a whole number, got "${value}"`;
+  if (type === "duration" && !GO_DURATION.test(value)) return `${name} needs a duration such as 30s, 10m or 1h, got "${value}"`;
+  // A switch is on when present and off when absent; an explicit value (`--draft=false`)
+  // is refused so that what hey-axi's policy sees is exactly what HEY would do.
+  if (type === "bool") return `${name} is a switch and takes no value: pass ${name} to turn it on, or leave it out (got ${name}=${value})`;
+  if (type === "count" && !/^\d+$/.test(value)) return `${name} counts repeats (${name} ${name}) or takes a whole number, got "${value}"`;
+  return null;
+}
+
+// AXI: reject unknown flags, flags without their value, values of the wrong type and
+// missing required flags before HEY is ever called.
+// Returns null, or { unknown } / { missingValue } / { badValue } / { missing }.
+export function validateFlags(node, flags, { values = [], missingValues = [] } = {}) {
   const allowed = new Set([
     ...[...GLOBAL_VALUE_FLAGS, ...GLOBAL_BOOLEAN_FLAGS, ...AXI_BOOLEAN_FLAGS, ...AXI_VALUE_FLAGS].map((name) => `--${name}`),
     ...GLOBAL_SHORTHANDS,
   ]);
+  const types = new Map(Object.entries(GLOBAL_TYPES));
+  for (const name of [...GLOBAL_BOOLEAN_FLAGS, ...AXI_BOOLEAN_FLAGS]) types.set(`--${name}`, "bool");
   for (const flag of node.flags || []) {
     allowed.add(`--${flag.name}`);
     if (flag.shorthand) allowed.add(`-${flag.shorthand}`);
+    const type = flag.value ? flag.type || "string" : flag.type === "count" ? "count" : "bool";
+    types.set(`--${flag.name}`, type);
+    if (flag.shorthand) types.set(`-${flag.shorthand}`, type);
   }
   const unknown = [...flags].map(flagName).filter((flag) => !allowed.has(flag));
   if (unknown.length) return { unknown: [...new Set(unknown)] };
   if (flags.has("--help") || flags.has("-h")) return null;
+  if (missingValues.length) return { missingValue: missingValues };
+  for (const [name, value] of values) {
+    const problem = typeError(name, types.get(name), value);
+    if (problem) return { badValue: problem };
+  }
   const missing = (node.flags || [])
     .filter((flag) => /\(required\)$/.test(flag.desc || ""))
     .filter((flag) => !flags.has(`--${flag.name}`) && !(flag.shorthand && flags.has(`-${flag.shorthand}`)))

package/src/arity.js

@@ -0,0 +1,94 @@
+// Positional-argument checks from HEY's own USAGE lines (bundled in src/manifest.json),
+// so a missing id or a stray extra word fails loud (exit 2) before HEY runs.
+//
+//   hey thread read <thread-id> [flags]            one required argument
+//   hey seen <box-item-id>... [flags]              one or more
+//   hey journal write [date] [content] [flags]     up to two, both optional
+//   hey bubble up <id>... (--now | --on <date> | --tomorrow) [flags]
+//                                                  plus exactly one of those flags
+
+// Parse one USAGE line. Returns null for group lines (`hey box <command> [flags]`).
+export function parseSynopsis(line, path) {
+  const prefix = `hey ${path}`;
+  if (!line.startsWith(prefix)) return null;
+  let rest = line.slice(prefix.length);
+  const oneOf = [];
+  rest = rest.replace(/\(([^)]*)\)/g, (_, group) => {
+    oneOf.push(group.split("|").map((part) => part.trim().split(/\s+/)[0]).filter((flag) => flag.startsWith("-")));
+    return " ";
+  });
+  const args = [];
+  for (const token of rest.trim().split(/\s+/).filter(Boolean)) {
+    if (token === "[flags]") continue;
+    if (token === "<command>") return null;
+    const match = token.match(/^([<[])([^>\]]+)[>\]](\.\.\.)?$/);
+    if (!match) continue;
+    args.push({ name: match[2], required: match[1] === "<", variadic: Boolean(match[3]) });
+  }
+  return { args, oneOf };
+}
+
+// Every argument pattern that applies when `node` is run with leftover words.
+// A group run by its shortcut (`box imbox`) uses HEY's compatibility usage.
+export function patternsFor(node) {
+  const lines = [...(node.synopsis || [])];
+  if (node.usage) lines.push(`hey ${node.usage}`);
+  return lines.map((line) => parseSynopsis(line, node.path)).filter(Boolean);
+}
+
+const describe = (args) => args.map(({ name, required, variadic }) => `${required ? `<${name}>` : `[${name}]`}${variadic ? "..." : ""}`).join(" ");
+
+function fits(pattern, count) {
+  const min = pattern.args.filter((arg) => arg.required).length;
+  const max = pattern.args.some((arg) => arg.variadic) ? Infinity : pattern.args.length;
+  return count >= min && count <= max;
+}
+
+// Returns null when the positionals and one-of flag groups fit, or { error, expected }.
+export function checkArity(node, positionals, flags) {
+  const patterns = patternsFor(node);
+  if (!patterns.length) return null;
+  const matching = patterns.filter((pattern) => fits(pattern, positionals.length));
+  if (!matching.length) {
+    const most = Math.max(...patterns.map((pattern) => (pattern.args.some((arg) => arg.variadic) ? Infinity : pattern.args.length)));
+    const expected = patterns.map((pattern) => describe(pattern.args)).filter(Boolean);
+    if (positionals.length > most) {
+      const extra = positionals.slice(most);
+      const takes = most === 0 ? "takes no arguments" : `takes at most ${most}: ${expected.join(" or ")}`;
+      return {
+        error: `unexpected argument${extra.length > 1 ? "s" : ""} ${extra.map((word) => `"${word}"`).join(" ")} for \`${node.path}\` (${takes})`,
+        hint: most >= 1 ? "quote text that contains spaces, e.g. \"two words\"" : undefined,
+      };
+    }
+    const pattern = patterns.find((candidate) => candidate.args.filter((arg) => arg.required).length > positionals.length) || patterns[0];
+    const missing = pattern.args.filter((arg) => arg.required).slice(positionals.length).map((arg) => `<${arg.name}>`);
+    return { error: `missing argument ${missing.join(" ")} for \`${node.path}\`` };
+  }
+  for (const group of matching[0].oneOf) {
+    const present = group.filter((flag) => flags.has(flag));
+    if (present.length !== 1) {
+      return {
+        error: present.length
+          ? `${present.join(" and ")} can't be combined for \`${node.path}\`; pass exactly one of ${group.join(", ")}`
+          : `\`${node.path}\` needs one of ${group.join(", ")}`,
+      };
+    }
+  }
+  return null;
+}
+
+// Required/optional arguments for --help, e.g. "<thread-id> (required)".
+export function argumentHelp(node) {
+  const seen = new Map();
+  for (const pattern of patternsFor(node)) {
+    for (const arg of pattern.args) {
+      const key = arg.name;
+      if (!seen.has(key)) seen.set(key, `${arg.required ? `<${arg.name}>` : `[${arg.name}]`}${arg.variadic ? "..." : ""}  ${arg.required ? "required" : "optional"}${arg.variadic ? ", one or more" : ""}`);
+    }
+  }
+  return [...seen.values()];
+}
+
+export function oneOfHelp(node) {
+  return patternsFor(node).flatMap((pattern) => pattern.oneOf).map((group) => `exactly one of ${group.join(", ")} (required)`);
+}