hey-axi 0.2.0 → 0.3.1

package/src/errors.js

@@ -1,28 +1,108 @@
-// Turn a failed HEY run into hey-axi's error shape, keeping HEY's own error envelope
-// ({ok:false,error,code,hint,meta}, written to stderr in --json mode) when there is one.
-// HEY may print plain warning lines (e.g. about the keyring) before the envelope; those
-// are kept as `warning`. Suggestions name hey-axi commands, and when HEY gives no hint
-// a `help` line for the exit code says what to do next.
+// Turn a failed HEY run into hey-axi's error shape (AXI principle 6):
+//   - HEY's own error envelope ({ok:false,error,code,hint,meta}) is kept, with hints
+//     rewritten to name hey-axi commands
+//   - anything else is translated: one cleaned line of HEY's text (no warnings, stack
+//     frames or terminal escapes) under a hey-axi message for the failure kind
+//   - plain warning lines HEY prints first (e.g. about the keyring) go to stderr, not stdout
+//   - exit codes follow AXI: 2 for usage errors, 1 for everything else that failed
+// A `help` line always says what to do next.
 
 import { heyToAxi } from "./text.js";
 
-// HEY's exit codes (`hey help exit-codes`) → the next step for an agent.
-const NEXT_STEP = {
-  1: "Run `hey-axi <command> --help` to check the arguments",
-  2: "Check the id; list commands such as `hey-axi box view imbox` show valid ids (threads use topic_id)",
-  3: "Ask the user to run `hey auth login` in their terminal, then `hey-axi auth status`",
-  4: "This account can't do that; check `hey-axi account list` and --account",
-  5: "Rate limited by HEY: wait a minute, then retry",
-  6: "Network problem reaching HEY: check the connection, then retry",
-  7: "HEY's API returned an error: retry later, or run `hey-axi doctor`",
-  8: "More than one match: pass an exact id instead of a name",
-  127: "Install the HEY CLI (curl -fsSL https://hey.com/install-cli | bash) or set HEY_BIN",
+// HEY's exit codes (`hey help exit-codes`) → a kind, a message and the next step.
+const KINDS = {
+  1: { kind: "command_error", message: "the command failed", help: "Run `hey-axi <command> --help` to check the arguments" },
+  2: { kind: "not_found", message: "not found", help: "Check the id; list commands such as `hey-axi box view imbox` show valid ids (threads use topic_id)" },
+  3: { kind: "auth", message: "not signed in to HEY", help: "Run `hey-axi auth login --token <token>` if you have a token; otherwise ask the user to run `hey-axi auth login --interactive` in their terminal. Check with `hey-axi auth status`" },
+  4: { kind: "forbidden", message: "this account can't do that", help: "Check `hey-axi account list` and --account" },
+  5: { kind: "rate_limited", message: "rate limited by HEY", help: "Wait a minute, then retry" },
+  6: { kind: "network", message: "couldn't reach HEY", help: "Check the network connection, then retry" },
+  7: { kind: "api_error", message: "HEY's API returned an error", help: "Retry later, or run `hey-axi doctor`" },
+  8: { kind: "ambiguous", message: "more than one match", help: "Pass an exact id instead of a name" },
+  127: { kind: "hey_missing", message: "HEY CLI not found", help: "Install the HEY CLI (curl -fsSL https://hey.com/install-cli | bash) or set HEY_BIN" },
 };
 
-function withHelp(failure) {
-  if (failure.hint) failure.hint = heyToAxi(failure.hint);
-  else if (NEXT_STEP[failure.exit_code]) failure.help = NEXT_STEP[failure.exit_code];
-  return failure;
+const USAGE_CODES = new Set(["usage", "invalid_argument", "invalid_flag", "validation"]);
+
+// AXI exit code for a failed HEY run.
+export function axiExitCode(status, code) {
+  if (status === 0) return 0;
+  if (USAGE_CODES.has(code)) return 2;
+  return 1;
+}
+
+const ANSI = /\u001b\[[0-9;?]*[ -/]*[@-~]/g;
+const NOISE = /^(warning:|panic:|fatal error:|\[signal |runtime error|\s+at |goroutine \d|\s*[\w./-]+\.go:\d+|exit status \d+$|\[\w+\]\s)/i;
+
+// The one line of HEY's plain-text output worth showing an agent.
+// Programming-language errors from inside HEY or its libraries say nothing an agent can
+// act on: they are dropped, and the failure's own message (by kind) stands alone.
+const INTERNAL = /^(Uncaught )?(TypeError|ReferenceError|SyntaxError|RangeError|InternalError|AssertionError|panic|fatal|runtime error|invalid memory address|nil pointer|unexpected end of JSON|json: |SIGSEGV)\b/i;
+// Any other "<Something>Error:" / "<Something>Exception:" line, a Ruby/Python-style
+// class path (Foo::Bar, foo.bar.BazError) or a traceback is a dependency's own error
+// (SqliteError, PG::ConnectionBad, sqlalchemy.exc.OperationalError): dropped the same way.
+const DEPENDENCY = /^(Uncaught\s+)?([\w$]+(\.[\w$]+|::[\w$]+)*(Error|Exception|Fault)\b|[A-Z]\w*(::[A-Z]\w*)+\b|Traceback\b|Caused by\b|node:internal\b)/;
+// Names of HTTP/database libraries; a short value that is just one of these says nothing.
+const LIBRARY = /\b(undici|axios|node-fetch|got|superagent|sqlite3?|better-sqlite3|sequel|activerecord|faraday|net\/http|go-http-client|libcurl|openssl|electron|node(\.js)?|v8)\b/i;
+// Low-level network codes become plain words.
+const NETWORK = [
+  [/\bECONNRESET\b/, "the connection was reset"], [/\bECONNREFUSED\b/, "the connection was refused"],
+  [/\bETIMEDOUT\b|\bi\/o timeout\b|context deadline exceeded/i, "the request timed out"], [/\bENOTFOUND\b|no such host/i, "the server name could not be resolved"],
+  [/\bEAI_AGAIN\b/, "DNS lookup failed"], [/\bcertificate\b|\bx509\b|\bTLS\b/i, "a TLS/certificate problem"],
+  // Local database codes (HEY's cache) become plain words too.
+  [/\bSQLITE_(BUSY|LOCKED)\b|database is locked/i, "the local database is busy; retry in a moment"], [/\bSQLITE_[A-Z]+\b/, "a local database error"],
+];
+
+export function cleanLine(text) {
+  const lines = String(text || "").replace(ANSI, "").split(/\r?\n/).map((line) => line.trimEnd()).filter((line) => line.trim() && !NOISE.test(line));
+  if (!lines.length) return "";
+  let line = lines[0].trim().replace(/^(error|Error|ERROR):\s*/, "");
+  const network = NETWORK.find(([pattern]) => pattern.test(line));
+  if (network) return network[1];
+  if (INTERNAL.test(line) || DEPENDENCY.test(line)) return "";
+  // Library prefixes ("axios:", "fetch failed:", "Get \"https://…\":") and raw URLs add nothing.
+  line = line.replace(/^((axios|undici|node-fetch|got|faraday|sqlite3?|better-sqlite3)(\s*error)?|fetch failed|request failed|(get|post|put|patch|delete) "[^"]*"):?\s*/i, "")
+    .replace(/\bhttps?:\/\/\S+/g, "the HEY server")
+    // File paths and source locations (/usr/lib/…/x.js:12:3, C:\\…) are internal detail.
+    .replace(/(^|\s)(\/|~\/|[A-Za-z]:\\)[^\s:]+(:\d+)*/g, "$1a local file").replace(/\s{2,}/g, " ").trim();
+  // A line that is still a dependency error after its prefix came off is dropped too.
+  if (!line || INTERNAL.test(line) || DEPENDENCY.test(line) || /^[\w./-]+$/.test(line) && LIBRARY.test(line)) return "";
+  return heyToAxi(line.length > 200 ? `${line.slice(0, 200)}…` : line);
+}
+
+// HEY's stderr after a successful run, minus terminal escapes and debug noise (stack
+// frames, panics): warnings and notices such as `next_page: …` stay, on stderr.
+export function warningLines(text) {
+  return String(text || "").replace(ANSI, "").split(/\r?\n/).map((line) => line.trimEnd())
+    .filter((line) => line.trim() && (/^warning:/i.test(line.trim()) || !NOISE.test(line)))
+    .map((line) => heyToAxi(line));
+}
+
+// Keys in HEY's error meta that only carry debugging detail.
+const DEBUG_KEYS = /stack|trace|backtrace|panic|goroutine|debug|caller|frames?$/i;
+
+// HEY's error meta without debugging detail: stack-like keys are dropped and
+// multi-line strings are cut to their one meaningful line.
+export function cleanMeta(value, depth = 0) {
+  if (typeof value === "string") {
+    if (/[\r\n\u001b]/.test(value) || value.length > 200) return cleanLine(value);
+    // Short values are kept as they are, unless they are a dependency's error or name.
+    const bare = value.trim().replace(/^(error|Error|ERROR):\s*/, "");
+    return INTERNAL.test(bare) || DEPENDENCY.test(bare) || (/^[\w./@ -]{1,40}$/.test(bare) && LIBRARY.test(bare) && !/\s\w+\s\w+/.test(bare)) ? undefined : value;
+  }
+  if (!value || typeof value !== "object" || depth > 3) return depth > 3 ? undefined : value;
+  if (Array.isArray(value)) return value.slice(0, 20).map((item) => cleanMeta(item, depth + 1)).filter((item) => item !== undefined && item !== "");
+  const out = {};
+  for (const [key, item] of Object.entries(value)) {
+    if (DEBUG_KEYS.test(key)) continue;
+    const cleaned = cleanMeta(item, depth + 1);
+    if (cleaned !== undefined && cleaned !== "") out[key] = cleaned;
+  }
+  return Object.keys(out).length ? out : undefined;
+}
+
+function warnings(text) {
+  return String(text || "").replace(ANSI, "").split(/\r?\n/).filter((line) => /^warning:/i.test(line.trim())).map((line) => line.trim());
 }
 
 function findEnvelope(text) {
@@ -43,19 +123,36 @@ function findEnvelope(text) {
   return null;
 }
 
-export function heyFailure(result) {
-  if (result.error) return withHelp({ ok: false, error: result.error, exit_code: result.status });
+// Returns { failure, exitCode, warnings }: the object to print, hey-axi's exit code,
+// and diagnostic lines for stderr.
+export function translateFailure(result, { path } = {}) {
+  const raw = KINDS[result.status] || KINDS[1];
+  const info = path ? { ...raw, help: raw.help.replace("<command>", path) } : raw;
+  if (result.error) {
+    return { failure: { ok: false, error: result.error, kind: info.kind, help: info.help }, exitCode: 1, warnings: [] };
+  }
   for (const text of [result.stderr, result.stdout]) {
     const found = findEnvelope(text);
     if (!found) continue;
-    const failure = { ok: false, error: found.envelope.error };
-    for (const key of ["code", "hint", "meta"]) {
-      if (found.envelope[key] !== undefined && found.envelope[key] !== "") failure[key] = found.envelope[key];
-    }
-    if (found.prefix) failure.warning = found.prefix;
-    failure.exit_code = result.status;
-    return withHelp(failure);
+    const { envelope } = found;
+    // Even HEY's own envelope is translated: one clean line, no stack frames or escapes.
+    const failure = { ok: false, error: cleanLine(String(envelope.error)) || info.message, kind: info.kind };
+    if (envelope.code !== undefined && envelope.code !== "" && envelope.code !== "unknown") failure.code = String(envelope.code);
+    const meta = envelope.meta === undefined || envelope.meta === "" ? undefined : cleanMeta(envelope.meta);
+    if (meta !== undefined) failure.meta = meta;
+    const usage = USAGE_CODES.has(envelope.code) || /^usage: /i.test(String(envelope.error));
+    if (usage) failure.kind = "usage";
+    const hint = envelope.hint ? cleanLine(String(envelope.hint)) : "";
+    if (hint && !/^Run 'hey(-axi)? --help'/.test(hint)) failure.hint = hint;
+    failure.help = usage ? `Run \`hey-axi ${path || "<command>"} --help\` for its arguments and flags` : info.help;
+    return { failure, exitCode: usage ? 2 : axiExitCode(result.status, envelope.code), warnings: warnings(found.prefix) };
   }
-  const message = (result.stderr || "").trim() || (result.stdout || "").trim() || "hey command failed";
-  return withHelp({ ok: false, error: message, exit_code: result.status });
+  const detail = cleanLine(result.stderr) || cleanLine(result.stdout);
+  const failure = { ok: false, error: detail ? `${info.message}: ${detail}` : info.message, kind: info.kind, help: info.help };
+  return { failure, exitCode: axiExitCode(result.status), warnings: [...warnings(result.stderr), ...warnings(result.stdout)] };
+}
+
+// Kept for callers that only need the object (the home view).
+export function heyFailure(result) {
+  return translateFailure(result).failure;
 }

package/src/examples.js

@@ -0,0 +1,57 @@
+// Per-command help details (AXI principle 10): every flag's default, and two or three
+// usage examples for every command. HEY's own examples come first; commands HEY gives
+// fewer than two for get examples built from their USAGE line and flags.
+
+import { heyToAxi } from "./text.js";
+import { patternsFor } from "./arity.js";
+import { LIST_FIELDS, parseField } from "./shape.js";
+import { userOnlyPaths } from "./policy.js";
+
+// "(default …)" text for one flag, including zero, false and empty defaults.
+export function flagDefault(flag) {
+  const value = flag.default;
+  if (!flag.value) return `default ${value === "true" ? "true" : "false"}`;
+  if (value === undefined || value === "" || value === "[]") return "default: none";
+  if (flag.name === "limit" && value === "0") return "default 0: no limit set, HEY returns its first page";
+  if (value === "0s") return "default 0s: no timeout";
+  return `default ${value}`;
+}
+
+const placeholder = (flag) => {
+  if (flag.type === "int") return "10";
+  if (flag.type === "duration") return "10m";
+  return `<${flag.name}>`;
+};
+
+function synthesized(node) {
+  const pattern = patternsFor(node)[0];
+  const args = (pattern?.args || []).filter((arg) => arg.required).map((arg) => `<${arg.name}>`);
+  const oneOf = pattern?.oneOf?.[0]?.[0];
+  const fromHey = (node.examples || [])[0];
+  const base = fromHey ? heyToAxi(fromHey) : ["hey-axi", node.path, ...args, ...(oneOf ? [oneOf] : [])].join(" ");
+  const out = [base];
+  const own = (node.flags || []).filter((flag) => !(pattern?.oneOf || []).flat().includes(`--${flag.name}`));
+  const valued = own.find((flag) => flag.value && !/\(required\)$/.test(flag.desc || ""));
+  const required = own.filter((flag) => /\(required\)$/.test(flag.desc || ""));
+  if (required.length && !fromHey) {
+    out[0] = `${base} ${required.map((flag) => `--${flag.name} ${placeholder(flag)}`).join(" ")}`;
+  }
+  if (valued && !out[0].includes(`--${valued.name}`)) out.push(`${out[0]} --${valued.name} ${placeholder(valued)}`);
+  const list = LIST_FIELDS[node.path];
+  if (list) out.push(`${out[0]} --fields ${list.slice(0, 2).map((spec) => parseField(spec).key).join(",")}`);
+  out.push(`${out[0]} --json`);
+  out.push(`${out[0]} --account <id>`);
+  return out;
+}
+
+// Two or three examples, HEY's own first.
+export function examplesFor(node) {
+  const examples = (node.examples || []).map(heyToAxi);
+  for (const example of synthesized(node)) {
+    if (examples.length >= 3 || (examples.length >= 2 && (node.examples || []).length >= 2)) break;
+    if (!examples.includes(example)) examples.push(example);
+  }
+  // Person-only commands run only with --interactive, so their examples say so.
+  const person = userOnlyPaths().includes(node.path);
+  return examples.slice(0, 3).map((example) => (person && !/--(interactive|token|cookie)\b/.test(example) ? `${example} --interactive` : example));
+}

package/src/guide.js

@@ -1,9 +1,11 @@
 // Static guidance shared by the no-args home view and the generated part of
 // skills/hey-axi/SKILL.md (scripts/gen-skill.js), so the two never drift.
 
+import { withSelectors } from "./shape.js";
+
 export const DESCRIPTION = "HEY email, calendars and todos for agents: compact TOON over Basecamp's HEY CLI; outgoing mail is saved as a draft unless --allow-send";
 
-// How many Imbox threads the home view (and the session hook) shows.
+// How many threads the home view (and the session hook) shows by default.
 export const HOME_LIMIT = 10;
 
 export const HOME_HELP = [
@@ -15,13 +17,30 @@ export const HOME_HELP = [
   "Run `hey-axi --help` for all commands; lists take --fields a,b / --fields all, long text --full",
 ];
 
+// The live home view's help: the static lines, pointed at the scope's command, with the
+// scope's --account carried into every suggestion, plus "see the rest" / --full /
+// review-drafts hints when they apply.
+export function homeHelp({ base = "hey-axi box view imbox", carry = [], more = false, total, truncated = false, drafts = false, search = false } = {}) {
+  const lines = HOME_HELP.map((line) => {
+    if (line.includes("box view imbox --limit 50")) {
+      if (!more) return `Run \`${withSelectors("hey-axi box list", carry)}\` for other boxes (feed, papertrail, aside, later)`;
+      const count = total !== undefined ? `all ${total}` : "more";
+      return search ? `Run \`${base}\` for ${count}` : `Run \`${base} --all\` for ${count} (or --limit <n>)`;
+    }
+    return line.replace(/`(hey-axi [^`]*)`/, (_, command) => (command === "hey-axi --help" ? `\`${command}\`` : `\`${withSelectors(command, carry)}\``));
+  }).filter(Boolean);
+  if (truncated) lines.push(`Run \`${base} --full\` to see complete content`);
+  if (drafts) lines.unshift(`Run \`${withSelectors("hey-axi draft list", carry)}\` to review drafts saved last session (not sent)`);
+  return lines;
+}
+
 export const SETUP_HELP = {
   missing: [
     "Install the HEY CLI: curl -fsSL https://hey.com/install-cli | bash (or brew install --cask basecamp/tap/hey)",
     "If it is installed outside PATH, set HEY_BIN=/path/to/hey",
   ],
   auth: [
-    "Ask the user to run `hey auth login` in their own terminal (it opens a browser)",
+    "Ask the user to run `hey-axi auth login --interactive` in their own terminal (it opens a browser), or run `hey-axi auth login --token <token>`",
     "Run `hey-axi auth status` to check afterwards",
   ],
   other: ["Run `hey-axi doctor` to find login and configuration problems"],

package/src/home-path.js

@@ -0,0 +1,12 @@
+// The absolute path of a file, with the user's home directory collapsed to `~`, for
+// paths shown to agents.
+import { homedir } from "node:os";
+import { resolve, sep } from "node:path";
+
+export function collapse(path, home = homedir()) {
+  if (!path) return path;
+  const absolute = resolve(path);
+  if (!home) return absolute;
+  if (absolute === home) return "~";
+  return absolute.startsWith(home.endsWith(sep) ? home : home + sep) ? `~${absolute.slice(home.replace(/[\\/]$/, "").length)}` : absolute;
+}

package/src/home.js

@@ -1,21 +1,36 @@
-// The no-args home view (AXI principles 8 and 10): who this is, then live Imbox state,
-// then the next commands. Also what the session hook prints. It never fails hard:
+// The no-args home view (AXI principles 7, 8 and 10): who this is, the directory scope,
+// live mail for that scope with its count, what the last session in this directory did,
+// then the next commands. It is also what the session hook prints. It never fails hard:
 // a missing or signed-out HEY is reported as `status` with the fix (exit 0), so a
 // session hook still gives the agent something useful.
 
-import { homedir } from "node:os";
-import { DESCRIPTION, HOME_HELP, HOME_LIMIT, SETUP_HELP } from "./guide.js";
-import { shapeData } from "./shape.js";
+import { DESCRIPTION, SETUP_HELP, homeHelp } from "./guide.js";
+import { carrySelectors, countLine, listSize, shapeData, findList } from "./shape.js";
 import { heyFailure } from "./errors.js";
 import { heyToAxi } from "./text.js";
+import { ScopeError, findScope, scopeQuery } from "./scope.js";
+import { lastSession } from "./activity.js";
+import { collapse } from "./home-path.js";
 
-export function collapse(path, home = homedir()) {
-  return path && home && path.startsWith(home) ? `~${path.slice(home.length)}` : path;
-}
+export { collapse };
 
-export async function homeView(runHey, { execPath = process.argv[1] } = {}) {
+export async function homeView(runHey, { execPath = process.argv[1], cwd = process.cwd() } = {}) {
   const out = { bin: collapse(execPath), description: DESCRIPTION };
-  const result = await runHey(["box", "view", "imbox", "--limit", String(HOME_LIMIT)], ["--json"]);
+  let scope = null;
+  try {
+    scope = findScope(cwd);
+  } catch (error) {
+    if (!(error instanceof ScopeError)) throw error;
+    out.status = error.message;
+    out.help = ["Fix or delete that file, then run `hey-axi` again", "Run `hey-axi setup scope --help` for the format"];
+    return out;
+  }
+  const query = scopeQuery(scope);
+  out.scope = query.label;
+  const previous = lastSession(scope?.dir || cwd);
+  if (previous) out.last_session = previous.line;
+
+  const result = await runHey(query.argv, ["--json"]);
   if (result.status === 127) {
     out.status = result.error || "HEY CLI not found";
     out.help = SETUP_HELP.missing;
@@ -30,6 +45,7 @@ export async function homeView(runHey, { execPath = process.argv[1] } = {}) {
       out.status = `HEY error: ${heyToAxi(failure.error)}`;
       out.help = [...(failure.hint ? [heyToAxi(failure.hint)] : []), ...SETUP_HELP.other];
     }
+    out.help = out.help.map((line) => carrySelectors(line, query.carry || []));
     return out;
   }
   let envelope;
@@ -40,11 +56,27 @@ export async function homeView(runHey, { execPath = process.argv[1] } = {}) {
     out.help = SETUP_HELP.other;
     return out;
   }
-  const { data, empty } = shapeData(envelope.data, { path: "box view" });
-  const threads = Array.isArray(data) ? data : data?.postings;
-  out.imbox = envelope.summary || `${threads?.length ?? 0} threads`;
-  if (empty || !threads?.length) out.imbox = "0 threads: the Imbox is empty";
-  else out.threads = threads;
-  out.help = HOME_HELP;
+  const body = envelope && typeof envelope === "object" && "data" in envelope ? envelope.data : envelope;
+  const found = findList(body);
+  const size = listSize(envelope, found ? found.list.length : 0, found?.container);
+  // search has no --limit: keep the first `limit` rows here.
+  if (found && found.list.length > query.limit) {
+    // More rows than shown, but no total unless HEY gave one.
+    size.more = true;
+  }
+  const { data, truncated } = shapeData(body, { path: query.path });
+  let threads = Array.isArray(data) ? data : data?.[found?.key];
+  if (threads && threads.length > query.limit) threads = threads.slice(0, query.limit);
+  size.shown = threads?.length ?? 0;
+  if (!threads?.length && (size.more || size.total > 0)) {
+    // An empty page while HEY reports more: say exactly that, not "nothing".
+    out.count = countLine(size);
+    out.mail = `0 threads on this page; HEY reports ${size.total > 0 ? `${size.total} in total` : "more"}`;
+  } else if (!threads?.length) out.mail = `0 threads: nothing in ${query.label.split(" (")[0]}`;
+  else {
+    out.count = countLine(size);
+    out.threads = threads;
+  }
+  out.help = homeHelp({ base: query.base, carry: query.carry, more: size.more, total: size.total, truncated, drafts: previous?.drafts > 0, search: query.path === "search" });
   return out;
 }