@taurgis/bonsai 3.2.2 → 4.1.0

package/oclif.manifest.json

@@ -1,5 +1,54 @@
 {
   "commands": {
+    "context": {
+      "aliases": [],
+      "args": {},
+      "description": "Print a short summary of the current research cache: total entries, a freshness breakdown, and the most recently touched pages. This is what `bonsai setup` wires into a SessionStart hook, so a session starts with the cache's state already visible.",
+      "examples": [
+        {
+          "description": "preview what a SessionStart hook would show",
+          "command": "<%= config.bin %> context"
+        },
+        {
+          "description": "get the dashboard as JSON",
+          "command": "<%= config.bin %> context --json"
+        }
+      ],
+      "flags": {
+        "json": {
+          "description": "Format output as json.",
+          "helpGroup": "GLOBAL",
+          "name": "json",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "read-only": {
+          "aliases": [
+            "plan"
+          ],
+          "description": "(alias: --plan) block filesystem writes/deletes; network fetches still run; also honored via BONSAI_READ_ONLY/BONSAI_PLAN_MODE",
+          "name": "read-only",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "toon": {
+          "description": "emit the same envelope as --json, encoded as TOON (fewer tokens); cannot be combined with --json",
+          "name": "toon",
+          "allowNo": false,
+          "type": "boolean"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "context",
+      "pluginAlias": "@taurgis/bonsai",
+      "pluginName": "@taurgis/bonsai",
+      "pluginType": "core",
+      "strict": true,
+      "summary": "Show a compact cache dashboard for ambient session context",
+      "enableJsonFlag": true,
+      "stdoutIsPrimaryData": true
+    },
     "fetch": {
       "aliases": [],
       "args": {
@@ -18,6 +67,10 @@
         {
           "description": "cache a volatile page with compressed JSON output",
           "command": "<%= config.bin %> https://news.ycombinator.com/ --format compressed --ttl 2h --json"
+        },
+        {
+          "description": "fetch multiple URLs in one batch (space-separated)",
+          "command": "<%= config.bin %> https://docs.nestjs.com/ https://docs.nestjs.com/first-steps"
         }
       ],
       "flags": {
@@ -37,9 +90,15 @@
           "allowNo": false,
           "type": "boolean"
         },
+        "toon": {
+          "description": "emit the same envelope as --json, encoded as TOON (fewer tokens); cannot be combined with --json",
+          "name": "toon",
+          "allowNo": false,
+          "type": "boolean"
+        },
         "topic": {
           "char": "t",
-          "description": "main research topic for metadata",
+          "description": "main research topic for metadata (max 200 chars)",
           "name": "topic",
           "hasDynamicHelp": false,
           "multiple": false,
@@ -47,7 +106,7 @@
         },
         "tags": {
           "char": "g",
-          "description": "taxonomic tags for this research (can be repeated)",
+          "description": "taxonomic tags for this research (can be repeated, max 100 chars each)",
           "name": "tags",
           "hasDynamicHelp": false,
           "multiple": true,
@@ -187,6 +246,12 @@
           "allowNo": false,
           "type": "boolean"
         },
+        "toon": {
+          "description": "emit the same envelope as --json, encoded as TOON (fewer tokens); cannot be combined with --json",
+          "name": "toon",
+          "allowNo": false,
+          "type": "boolean"
+        },
         "stdin": {
           "description": "read Markdown from stdin",
           "name": "stdin",
@@ -215,7 +280,7 @@
         },
         "topic": {
           "char": "t",
-          "description": "main topic for this research note",
+          "description": "main topic for this research note (max 200 chars)",
           "name": "topic",
           "hasDynamicHelp": false,
           "multiple": false,
@@ -223,7 +288,7 @@
         },
         "tags": {
           "char": "g",
-          "description": "taxonomic tags (can be repeated)",
+          "description": "taxonomic tags (can be repeated, max 100 chars each)",
           "name": "tags",
           "hasDynamicHelp": false,
           "multiple": true,
@@ -304,6 +369,10 @@
         {
           "description": "inspect cached metadata as JSON",
           "command": "<%= config.bin %> <%= command.id %> https://example.com/docs --json"
+        },
+        {
+          "description": "inspect multiple URLs in one batch (space-separated)",
+          "command": "<%= config.bin %> <%= command.id %> https://example.com/docs https://example.com/api"
         }
       ],
       "flags": {
@@ -322,6 +391,12 @@
           "name": "read-only",
           "allowNo": false,
           "type": "boolean"
+        },
+        "toon": {
+          "description": "emit the same envelope as --json, encoded as TOON (fewer tokens); cannot be combined with --json",
+          "name": "toon",
+          "allowNo": false,
+          "type": "boolean"
         }
       },
       "hasDynamicHelp": false,
@@ -338,7 +413,7 @@
     "list": {
       "aliases": [],
       "args": {},
-      "description": "List page-level cached artifacts with source URLs, topic, tags, freshness, capture method, and token estimates.",
+      "description": "List page-level cached artifacts by source URL, topic, freshness, and token estimate. Pass --full for every metadata field (cache key, path, artifact type, tags, capture method, quality notes, timestamps).",
       "examples": [
         {
           "description": "list cached entries",
@@ -355,6 +430,10 @@
         {
           "description": "list entries matching a URL glob",
           "command": "<%= config.bin %> list --url \"https://react.dev/*\""
+        },
+        {
+          "description": "list every metadata field instead of the minimal default row",
+          "command": "<%= config.bin %> list --full --json"
         }
       ],
       "flags": {
@@ -374,6 +453,12 @@
           "allowNo": false,
           "type": "boolean"
         },
+        "toon": {
+          "description": "emit the same envelope as --json, encoded as TOON (fewer tokens); cannot be combined with --json",
+          "name": "toon",
+          "allowNo": false,
+          "type": "boolean"
+        },
         "topic": {
           "char": "t",
           "description": "exact topic (case-insensitive)",
@@ -436,12 +521,24 @@
           "type": "option"
         },
         "limit": {
-          "description": "result count (default 50, max 100)",
+          "description": "result count (max 100, default 10)",
           "name": "limit",
-          "default": 50,
+          "default": 10,
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
+        },
+        "full": {
+          "description": "include every metadata field (cache key, path, artifact type, tags, capture method, quality notes, timestamps); default output is a minimal row (source URLs, topic, freshness, token estimate)",
+          "name": "full",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "identity": {
+          "hidden": true,
+          "name": "identity",
+          "allowNo": false,
+          "type": "boolean"
         }
       },
       "hasDynamicHelp": false,
@@ -458,7 +555,7 @@
     "prune": {
       "aliases": [],
       "args": {},
-      "description": "Delete cached artifacts by content age, idle time, URL glob, or artifact type.",
+      "description": "Delete cached artifacts by content age, idle time, URL glob, artifact type, topic, or tags.",
       "examples": [
         {
           "description": "preview pruning entries older than 30 days",
@@ -471,6 +568,10 @@
         {
           "description": "prune entries matching a URL glob",
           "command": "<%= config.bin %> prune --url \"https://react.dev/*\" --yes"
+        },
+        {
+          "description": "prune entries tagged as deprecated",
+          "command": "<%= config.bin %> prune --tags deprecated --yes"
         }
       ],
       "flags": {
@@ -490,6 +591,12 @@
           "allowNo": false,
           "type": "boolean"
         },
+        "toon": {
+          "description": "emit the same envelope as --json, encoded as TOON (fewer tokens); cannot be combined with --json",
+          "name": "toon",
+          "allowNo": false,
+          "type": "boolean"
+        },
         "older-than": {
           "description": "content age threshold (fetched_at, else validated_at), e.g. \"30d\"",
           "name": "older-than",
@@ -511,6 +618,22 @@
           "multiple": false,
           "type": "option"
         },
+        "topic": {
+          "char": "t",
+          "description": "exact topic (case-insensitive)",
+          "name": "topic",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "tags": {
+          "char": "g",
+          "description": "tags to require (must match all)",
+          "name": "tags",
+          "hasDynamicHelp": false,
+          "multiple": true,
+          "type": "option"
+        },
         "artifact-type": {
           "description": "artifact type to prune, including section children",
           "name": "artifact-type",
@@ -549,6 +672,236 @@
       "enableJsonFlag": true,
       "stdoutIsPrimaryData": true
     },
+    "search": {
+      "aliases": [],
+      "args": {},
+      "description": "Rank cached page-level artifacts by a --query matched against topic, tags, summary, and compressed content, plus the same metadata filters as `list` (topic, tags, URL, freshness, artifact type, capture method). Reads only the token-cheap indexed summary/compressed text, never the full detailed body, so ranking a large cache stays fast. Pass --full for every metadata field.",
+      "examples": [
+        {
+          "description": "search content and tags for a keyword",
+          "command": "<%= config.bin %> search --query \"suspense boundary\""
+        },
+        {
+          "description": "match any of several terms instead of requiring all",
+          "command": "<%= config.bin %> search --query \"suspense streaming\" --match-any"
+        },
+        {
+          "description": "combine a query with metadata filters",
+          "command": "<%= config.bin %> search --query cache --tags react --freshness fresh"
+        },
+        {
+          "description": "filter by tags/topic alone, ranked like list (no --query)",
+          "command": "<%= config.bin %> search --tags node --json"
+        }
+      ],
+      "flags": {
+        "json": {
+          "description": "Format output as json.",
+          "helpGroup": "GLOBAL",
+          "name": "json",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "read-only": {
+          "aliases": [
+            "plan"
+          ],
+          "description": "(alias: --plan) block filesystem writes/deletes; network fetches still run; also honored via BONSAI_READ_ONLY/BONSAI_PLAN_MODE",
+          "name": "read-only",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "toon": {
+          "description": "emit the same envelope as --json, encoded as TOON (fewer tokens); cannot be combined with --json",
+          "name": "toon",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "query": {
+          "char": "q",
+          "description": "keyword(s) to search across topic, tags, summary, and compressed content (case-insensitive); every term must match somewhere unless --match-any is set",
+          "name": "query",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "match-any": {
+          "description": "match any query term instead of requiring all of them (OR instead of AND)",
+          "name": "match-any",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "topic": {
+          "char": "t",
+          "description": "exact topic (case-insensitive)",
+          "name": "topic",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "tags": {
+          "char": "g",
+          "description": "tags to require (must match all)",
+          "name": "tags",
+          "hasDynamicHelp": false,
+          "multiple": true,
+          "type": "option"
+        },
+        "url": {
+          "description": "source URL glob (case-insensitive, supports * wildcard)",
+          "name": "url",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "freshness": {
+          "description": "freshness state",
+          "name": "freshness",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "options": [
+            "fresh",
+            "stale_grace",
+            "stale_expired"
+          ],
+          "type": "option"
+        },
+        "artifact-type": {
+          "description": "artifact type; section children are omitted from search - use inspect to see them",
+          "name": "artifact-type",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "options": [
+            "source",
+            "research_note",
+            "index"
+          ],
+          "type": "option"
+        },
+        "capture-method": {
+          "description": "capture method",
+          "name": "capture-method",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "options": [
+            "static_fetch",
+            "browser_fallback",
+            "agent_supplied",
+            "route_markdown",
+            "github_source"
+          ],
+          "type": "option"
+        },
+        "limit": {
+          "description": "result count (max 100, default 10)",
+          "name": "limit",
+          "default": 10,
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "full": {
+          "description": "include every metadata field (cache key, path, artifact type, tags, capture method, quality notes, timestamps) alongside score/matchedFields/snippet; default output is a minimal row (source URLs, topic, freshness, token estimate, score, matchedFields, snippet)",
+          "name": "full",
+          "allowNo": false,
+          "type": "boolean"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "search",
+      "pluginAlias": "@taurgis/bonsai",
+      "pluginName": "@taurgis/bonsai",
+      "pluginType": "core",
+      "strict": true,
+      "summary": "Search cached research artifacts by tags and content",
+      "enableJsonFlag": true,
+      "stdoutIsPrimaryData": true
+    },
+    "setup": {
+      "aliases": [],
+      "args": {
+        "agent": {
+          "description": "agent to install the hook for (claude-code, codex)",
+          "name": "agent",
+          "required": true
+        }
+      },
+      "description": "Writes (or repairs) a SessionStart hook entry that runs `bonsai context` at the start of every session, so the agent sees the cache state before doing anything. Project-scoped by default (shareable via version control); pass --global for a user-level, machine-only install. Re-running is idempotent: an unchanged install is a no-op, and a stale executable path is repaired.",
+      "examples": [
+        {
+          "description": "install the hook for this project (Claude Code)",
+          "command": "<%= config.bin %> setup claude-code"
+        },
+        {
+          "description": "install the hook for this project (Codex)",
+          "command": "<%= config.bin %> setup codex"
+        },
+        {
+          "description": "preview a user-level install without writing anything",
+          "command": "<%= config.bin %> setup claude-code --global --dry-run --json"
+        }
+      ],
+      "flags": {
+        "json": {
+          "description": "Format output as json.",
+          "helpGroup": "GLOBAL",
+          "name": "json",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "read-only": {
+          "aliases": [
+            "plan"
+          ],
+          "description": "(alias: --plan) block filesystem writes/deletes; network fetches still run; also honored via BONSAI_READ_ONLY/BONSAI_PLAN_MODE",
+          "name": "read-only",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "toon": {
+          "description": "emit the same envelope as --json, encoded as TOON (fewer tokens); cannot be combined with --json",
+          "name": "toon",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "global": {
+          "char": "g",
+          "description": "install to the user-level config instead of the project (default: project)",
+          "name": "global",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "local": {
+          "aliases": [
+            "project"
+          ],
+          "charAliases": [
+            "p"
+          ],
+          "description": "install to the project config (default; explicit form of the default)",
+          "name": "local",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "dry-run": {
+          "description": "preview the install without writing anything",
+          "name": "dry-run",
+          "allowNo": false,
+          "type": "boolean"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "setup",
+      "pluginAlias": "@taurgis/bonsai",
+      "pluginName": "@taurgis/bonsai",
+      "pluginType": "core",
+      "strict": true,
+      "summary": "Install a SessionStart hook that shows live cache context",
+      "enableJsonFlag": true,
+      "stdoutIsPrimaryData": true
+    },
     "status": {
       "aliases": [],
       "args": {
@@ -567,6 +920,10 @@
         {
           "description": "evaluate status with a specific tier and TTL",
           "command": "<%= config.bin %> <%= command.id %> https://example.com/docs --tier volatile --ttl 2h"
+        },
+        {
+          "description": "check multiple URLs in one batch (space-separated)",
+          "command": "<%= config.bin %> <%= command.id %> https://example.com/docs https://example.com/api"
         }
       ],
       "flags": {
@@ -586,6 +943,12 @@
           "allowNo": false,
           "type": "boolean"
         },
+        "toon": {
+          "description": "emit the same envelope as --json, encoded as TOON (fewer tokens); cannot be combined with --json",
+          "name": "toon",
+          "allowNo": false,
+          "type": "boolean"
+        },
         "tier": {
           "description": "freshness tier policy to evaluate; when omitted, uses the cached entry's own tier",
           "name": "tier",
@@ -655,6 +1018,12 @@
           "name": "read-only",
           "allowNo": false,
           "type": "boolean"
+        },
+        "toon": {
+          "description": "emit the same envelope as --json, encoded as TOON (fewer tokens); cannot be combined with --json",
+          "name": "toon",
+          "allowNo": false,
+          "type": "boolean"
         }
       },
       "hasDynamicHelp": false,
@@ -677,7 +1046,7 @@
           "required": false
         }
       },
-      "description": "Print a config value. Without --global/--local, shows the merged effective value, in precedence order: a per-command override flag (e.g. `fetch --storage`) > env var > project file > user file > built-in default.\n\nValid keys: storage, summary.",
+      "description": "Print a config value. Without --global/--local, shows the merged effective value, in precedence order: a per-command override flag (e.g. `fetch --storage`) > env var > project file > user file > built-in default.\n\nValid keys: storage (global|project), summary (conservative|balanced|aggressive).",
       "examples": [
         {
           "description": "get the effective storage mode",
@@ -705,6 +1074,12 @@
           "allowNo": false,
           "type": "boolean"
         },
+        "toon": {
+          "description": "emit the same envelope as --json, encoded as TOON (fewer tokens); cannot be combined with --json",
+          "name": "toon",
+          "allowNo": false,
+          "type": "boolean"
+        },
         "global": {
           "char": "g",
           "description": "read user-level config only",
@@ -738,7 +1113,7 @@
     "config:list": {
       "aliases": [],
       "args": {},
-      "description": "Show every configuration key with its current value. Use --global/--local to show a single scope.\n\nValid keys: storage, summary.",
+      "description": "Show every configuration key with its current value. Use --global/--local to show a single scope.\n\nValid keys: storage (global|project), summary (conservative|balanced|aggressive).",
       "examples": [
         {
           "description": "show all effective config values",
@@ -766,6 +1141,12 @@
           "allowNo": false,
           "type": "boolean"
         },
+        "toon": {
+          "description": "emit the same envelope as --json, encoded as TOON (fewer tokens); cannot be combined with --json",
+          "name": "toon",
+          "allowNo": false,
+          "type": "boolean"
+        },
         "global": {
           "char": "g",
           "description": "show user-level config only",
@@ -810,7 +1191,7 @@
           "required": false
         }
       },
-      "description": "Persist a configuration value. Writes user-level config by default; pass --local for project-level config (.bonsai.json in cwd).\n\nValid keys: storage, summary. The inline form `<key>=<value>` is also accepted.",
+      "description": "Persist a configuration value. Writes user-level config by default; pass --local for project-level config (.bonsai.json in cwd).\n\nValid keys: storage (global|project), summary (conservative|balanced|aggressive). The inline form `<key>=<value>` is also accepted.",
       "examples": [
         {
           "description": "store research cache in the current project",
@@ -838,6 +1219,12 @@
           "allowNo": false,
           "type": "boolean"
         },
+        "toon": {
+          "description": "emit the same envelope as --json, encoded as TOON (fewer tokens); cannot be combined with --json",
+          "name": "toon",
+          "allowNo": false,
+          "type": "boolean"
+        },
         "global": {
           "char": "g",
           "description": "write user-level config (default)",
@@ -883,7 +1270,7 @@
           "required": false
         }
       },
-      "description": "Delete a key from user-level config (default) or project-level config (--local), restoring the built-in default.\n\nValid keys: storage, summary.",
+      "description": "Delete a key from user-level config (default) or project-level config (--local), restoring the built-in default.\n\nValid keys: storage (global|project), summary (conservative|balanced|aggressive).",
       "examples": [
         {
           "description": "remove the user-level storage setting",
@@ -911,6 +1298,12 @@
           "allowNo": false,
           "type": "boolean"
         },
+        "toon": {
+          "description": "emit the same envelope as --json, encoded as TOON (fewer tokens); cannot be combined with --json",
+          "name": "toon",
+          "allowNo": false,
+          "type": "boolean"
+        },
         "global": {
           "char": "g",
           "description": "remove from user-level config (default)",
@@ -948,5 +1341,5 @@
       "stdoutIsPrimaryData": true
     }
   },
-  "version": "3.2.2"
+  "version": "4.1.0"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@taurgis/bonsai",
-  "version": "3.2.2",
+  "version": "4.1.0",
   "description": "Bonsai is a standalone local research cache CLI for AI agents",
   "repository": {
     "type": "git",
@@ -37,6 +37,7 @@
     "@mozilla/readability": "^0.5.0",
     "@oclif/core": "^4.11.4",
     "@oclif/plugin-autocomplete": "^3.2.52",
+    "@toon-format/toon": "^4.0.0",
     "linkedom": "^0.18.12",
     "turndown": "^7.2.0",
     "undici": "^8.7.0",