hey-axi 0.3.0 → 0.3.1

package/README.md

@@ -1,5 +1,7 @@
 # hey-axi
 
+[![skills.sh](https://skills.sh/b/TangentialSolutions/hey-axi)](https://skills.sh/TangentialSolutions/hey-axi)
+
 An agent-friendly wrapper for [HEY CLI](https://github.com/basecamp/hey-cli) (`hey`), Basecamp's command line for HEY email, calendars, todos, habits, time tracking and journals.
 
 hey-axi runs `hey`, asks for its JSON response envelope, and prints it as [TOON](https://github.com/toon-format/toon). It follows the [AXI](https://axi.md) principles: a live home view, minimal default fields, truncated long text, definitive empty states, and unknown flags rejected up front. On our synthetic benchmark that's **~89% fewer tokens than `hey --json`** ([docs/benchmarks.md](docs/benchmarks.md)). It also adds a few safety rails. It covers **every command in HEY CLI v1.7.0** (154 runnable command paths, including the `login`/`logout` aliases, plus the `box <id>`-style shortcuts) by routing from a snapshot of HEY's own `hey commands --json` catalog. See [CHANGELOG.md](CHANGELOG.md) for what changed in each release.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hey-axi",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Agent-ergonomic AXI wrapper for Basecamp's HEY CLI: TOON output, send-to-draft safety, and a shareable agent skill",
   "keywords": [
     "axi",

package/skills/hey-axi/references/commands.md

@@ -32,7 +32,7 @@ Flags every command accepts: `--account <id|all>`, `--json`, `--quiet`, `--field
 | `calendar list` | List calendars |  | fields: id, name, kind, owned |
 | `clip create` | Save text from an email entry | `--content <v>` |  |
 | `clip delete` | Delete a saved clip |  |  |
-| `clip list` | List the newest page of passages clipped from email |  | fields: id, content, topic_id, at |
+| `clip list` | List the newest page of passages clipped from email |  | fields: id, topic_id, at |
 | `collection` | List and manage email collections | `--all` `--limit <v>` `--page <v>` | fields: id, topic_id, from, subject |
 | `collection add` | Add email threads to a collection | `--to <v>` |  |
 | `collection create` | Create a collection | `--summary <v>` |  |
@@ -79,7 +79,7 @@ Flags every command accepts: `--account <id|all>`, `--json`, `--quiet`, `--field
 | `habit list` | List habits | `--all` `--date <v>` `--limit <v>` | fields: id, title, days |
 | `habit uncomplete` | Remove a habit completion for a date | `--date <v>` |  |
 | `ignore` | Ignore email threads |  |  |
-| `journal list` | List journal entries | `--all` `--calendar <v>` `--ends-on <v>` `--limit <v>` `--starts-on <v>` | fields: id, starts_at, content |
+| `journal list` | List journal entries | `--all` `--calendar <v>` `--ends-on <v>` `--limit <v>` `--starts-on <v>` | fields: id, date |
 | `journal read` | Read a journal entry (default: today) |  |  |
 | `journal write` | Write or edit a journal entry (default: today) | `--content <v>` `--content-html <v>` |  |
 | `label` | List and manage email labels | `--all` `--limit <v>` `--page <v>` | fields: id, topic_id, from, subject |
@@ -122,7 +122,7 @@ Flags every command accepts: `--account <id|all>`, `--json`, `--quiet`, `--field
 | `skill install` | Install the hey skill globally for your coding agents |  |  |
 | `snippet create` | Create a reusable email snippet | `--content <v>` `--content-html <v>` `--name <v>` |  |
 | `snippet delete` | Delete a reusable email snippet |  |  |
-| `snippet list` | List reusable email snippets |  | fields: id, name, content |
+| `snippet list` | List reusable email snippets |  | fields: id, name |
 | `snippet update` | Update a reusable email snippet | `--content <v>` `--content-html <v>` `--name <v>` |  |
 | `spam` | Mark email threads as spam |  |  |
 | `stop-ignoring` | Stop ignoring email threads |  |  |

package/src/cli.js

@@ -568,7 +568,7 @@ if (!full && !quiet && !plainText && shaped && typeof shaped === "object" && sha
       ? `Run \`${withSelectors(`hey-axi ${sibling.path} --help`, carry)}\` to see how to add one`
       : sibling
       ? `Run \`${withSelectors(`hey-axi ${sibling.path} <id>`, carry)}\` to see one in full`
-      : shaped.empty ? `Run \`hey-axi ${path} --help\` to check the filters` : `Run \`${commandLine} --fields all\` to see every field`;
+      : shaped.empty ? `Run \`${withSelectors(`hey-axi ${path} --help`, carry)}\` to check the filters` : `Run \`${commandLine} --fields all\` to see every field`;
     shaped.help = [next, ...help];
   }
 }

package/src/errors.js

@@ -38,11 +38,19 @@ const NOISE = /^(warning:|panic:|fatal error:|\[signal |runtime error|\s+at |gor
 // 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) {
@@ -51,10 +59,14 @@ export function cleanLine(text) {
   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)) return "";
+  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|fetch failed|request failed|(get|post|put|patch|delete) "[^"]*"):?\s*/i, "").replace(/\bhttps?:\/\/\S+/g, "the HEY server").trim();
-  if (!line) return "";
+  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);
 }
 
@@ -72,7 +84,12 @@ const DEBUG_KEYS = /stack|trace|backtrace|panic|goroutine|debug|caller|frames?$/
 // 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") return /[\r\n\u001b]/.test(value) || value.length > 200 ? cleanLine(value) : value;
+  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 = {};

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.1";