@taurgis/bonsai 4.0.0 → 4.1.1

package/oclif.manifest.json

@@ -1,5 +1,60 @@
 {
   "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,
+      "isESM": true,
+      "relativePath": [
+        "dist",
+        "commands",
+        "context.js"
+      ]
+    },
     "fetch": {
       "aliases": [],
       "args": {
@@ -150,7 +205,13 @@
       "strict": false,
       "summary": "Fetch and cache URL research Markdown",
       "enableJsonFlag": true,
-      "stdoutIsPrimaryData": true
+      "stdoutIsPrimaryData": true,
+      "isESM": true,
+      "relativePath": [
+        "dist",
+        "commands",
+        "fetch.js"
+      ]
     },
     "import": {
       "aliases": [],
@@ -300,7 +361,13 @@
       "strict": true,
       "summary": "Import agent-supplied Markdown into cache",
       "enableJsonFlag": true,
-      "stdoutIsPrimaryData": true
+      "stdoutIsPrimaryData": true,
+      "isESM": true,
+      "relativePath": [
+        "dist",
+        "commands",
+        "import.js"
+      ]
     },
     "inspect": {
       "aliases": [],
@@ -359,7 +426,13 @@
       "strict": false,
       "summary": "Inspect cached research metadata for a URL",
       "enableJsonFlag": true,
-      "stdoutIsPrimaryData": true
+      "stdoutIsPrimaryData": true,
+      "isESM": true,
+      "relativePath": [
+        "dist",
+        "commands",
+        "inspect.js"
+      ]
     },
     "list": {
       "aliases": [],
@@ -472,9 +545,9 @@
           "type": "option"
         },
         "limit": {
-          "description": "result count (max 100)",
+          "description": "result count (max 100, default 10)",
           "name": "limit",
-          "default": 50,
+          "default": 10,
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
@@ -484,6 +557,12 @@
           "name": "full",
           "allowNo": false,
           "type": "boolean"
+        },
+        "identity": {
+          "hidden": true,
+          "name": "identity",
+          "allowNo": false,
+          "type": "boolean"
         }
       },
       "hasDynamicHelp": false,
@@ -495,7 +574,13 @@
       "strict": true,
       "summary": "List cached research artifacts by metadata",
       "enableJsonFlag": true,
-      "stdoutIsPrimaryData": true
+      "stdoutIsPrimaryData": true,
+      "isESM": true,
+      "relativePath": [
+        "dist",
+        "commands",
+        "list.js"
+      ]
     },
     "prune": {
       "aliases": [],
@@ -615,30 +700,34 @@
       "strict": true,
       "summary": "Prune cached research artifacts",
       "enableJsonFlag": true,
-      "stdoutIsPrimaryData": true
+      "stdoutIsPrimaryData": true,
+      "isESM": true,
+      "relativePath": [
+        "dist",
+        "commands",
+        "prune.js"
+      ]
     },
-    "status": {
+    "search": {
       "aliases": [],
-      "args": {
-        "url": {
-          "description": "URL to check",
-          "name": "url",
-          "required": true
-        }
-      },
-      "description": "Report cache hit/miss state, freshness, and the action the URL shorthand would take.",
+      "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": "check whether a URL is cached",
-          "command": "<%= config.bin %> <%= command.id %> https://example.com/docs"
+          "description": "search content and tags for a keyword",
+          "command": "<%= config.bin %> search --query \"suspense boundary\""
         },
         {
-          "description": "evaluate status with a specific tier and TTL",
-          "command": "<%= config.bin %> <%= command.id %> https://example.com/docs --tier volatile --ttl 2h"
+          "description": "match any of several terms instead of requiring all",
+          "command": "<%= config.bin %> search --query \"suspense streaming\" --match-any"
         },
         {
-          "description": "check multiple URLs in one batch (space-separated)",
-          "command": "<%= config.bin %> <%= command.id %> https://example.com/docs https://example.com/api"
+          "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": {
@@ -664,57 +753,135 @@
           "allowNo": false,
           "type": "boolean"
         },
-        "tier": {
-          "description": "freshness tier policy to evaluate; when omitted, uses the cached entry's own tier",
-          "name": "tier",
+        "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": [
-            "stable",
-            "standard",
-            "volatile"
+            "fresh",
+            "stale_grace",
+            "stale_expired"
           ],
           "type": "option"
         },
-        "ttl": {
-          "char": "l",
-          "description": "TTL duration to evaluate freshness (e.g. \"2h\", \"7d\", \"6m\")",
-          "name": "ttl",
+        "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"
         },
-        "max-age": {
-          "description": "maximum cache age to accept (e.g. \"2h\", \"7d\", \"6m\")",
-          "name": "max-age",
+        "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": "status",
+      "id": "search",
       "pluginAlias": "@taurgis/bonsai",
       "pluginName": "@taurgis/bonsai",
       "pluginType": "core",
-      "strict": false,
-      "summary": "Check cache status without fetching or writing",
+      "strict": true,
+      "summary": "Search cached research artifacts by tags and content",
       "enableJsonFlag": true,
-      "stdoutIsPrimaryData": true
+      "stdoutIsPrimaryData": true,
+      "isESM": true,
+      "relativePath": [
+        "dist",
+        "commands",
+        "search.js"
+      ]
     },
-    "config": {
+    "setup": {
       "aliases": [],
-      "args": {},
-      "description": "Show config subcommands for reading and writing Bonsai research cache configuration.",
+      "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": "get a configuration value",
-          "command": "<%= config.bin %> <%= command.id %> get storage"
+          "description": "install the hook for this project (Claude Code)",
+          "command": "<%= config.bin %> setup claude-code"
         },
         {
-          "description": "set project storage mode",
-          "command": "<%= config.bin %> <%= command.id %> set storage project --local"
+          "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": {
@@ -739,18 +906,141 @@
           "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": "config",
+      "id": "setup",
       "pluginAlias": "@taurgis/bonsai",
       "pluginName": "@taurgis/bonsai",
       "pluginType": "core",
       "strict": true,
-      "summary": "Manage research cache configuration",
+      "summary": "Install a SessionStart hook that shows live cache context",
+      "enableJsonFlag": true,
+      "stdoutIsPrimaryData": true,
+      "isESM": true,
+      "relativePath": [
+        "dist",
+        "commands",
+        "setup.js"
+      ]
+    },
+    "status": {
+      "aliases": [],
+      "args": {
+        "url": {
+          "description": "URL to check",
+          "name": "url",
+          "required": true
+        }
+      },
+      "description": "Report cache hit/miss state, freshness, and the action the URL shorthand would take.",
+      "examples": [
+        {
+          "description": "check whether a URL is cached",
+          "command": "<%= config.bin %> <%= command.id %> https://example.com/docs"
+        },
+        {
+          "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": {
+        "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"
+        },
+        "tier": {
+          "description": "freshness tier policy to evaluate; when omitted, uses the cached entry's own tier",
+          "name": "tier",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "options": [
+            "stable",
+            "standard",
+            "volatile"
+          ],
+          "type": "option"
+        },
+        "ttl": {
+          "char": "l",
+          "description": "TTL duration to evaluate freshness (e.g. \"2h\", \"7d\", \"6m\")",
+          "name": "ttl",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "max-age": {
+          "description": "maximum cache age to accept (e.g. \"2h\", \"7d\", \"6m\")",
+          "name": "max-age",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "status",
+      "pluginAlias": "@taurgis/bonsai",
+      "pluginName": "@taurgis/bonsai",
+      "pluginType": "core",
+      "strict": false,
+      "summary": "Check cache status without fetching or writing",
       "enableJsonFlag": true,
-      "stdoutIsPrimaryData": true
+      "stdoutIsPrimaryData": true,
+      "isESM": true,
+      "relativePath": [
+        "dist",
+        "commands",
+        "status.js"
+      ]
     },
     "config:get": {
       "aliases": [],
@@ -823,7 +1113,70 @@
       "pluginType": "core",
       "strict": true,
       "summary": "Get a research configuration value",
-      "stdoutIsPrimaryData": true
+      "stdoutIsPrimaryData": true,
+      "isESM": true,
+      "relativePath": [
+        "dist",
+        "commands",
+        "config",
+        "get.js"
+      ]
+    },
+    "config": {
+      "aliases": [],
+      "args": {},
+      "description": "Show config subcommands for reading and writing Bonsai research cache configuration.",
+      "examples": [
+        {
+          "description": "get a configuration value",
+          "command": "<%= config.bin %> <%= command.id %> get storage"
+        },
+        {
+          "description": "set project storage mode",
+          "command": "<%= config.bin %> <%= command.id %> set storage project --local"
+        }
+      ],
+      "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": "config",
+      "pluginAlias": "@taurgis/bonsai",
+      "pluginName": "@taurgis/bonsai",
+      "pluginType": "core",
+      "strict": true,
+      "summary": "Manage research cache configuration",
+      "enableJsonFlag": true,
+      "stdoutIsPrimaryData": true,
+      "isESM": true,
+      "relativePath": [
+        "dist",
+        "commands",
+        "config",
+        "index.js"
+      ]
     },
     "config:list": {
       "aliases": [],
@@ -890,7 +1243,14 @@
       "pluginType": "core",
       "strict": true,
       "summary": "List research configuration values",
-      "stdoutIsPrimaryData": true
+      "stdoutIsPrimaryData": true,
+      "isESM": true,
+      "relativePath": [
+        "dist",
+        "commands",
+        "config",
+        "list.js"
+      ]
     },
     "config:set": {
       "aliases": [],
@@ -974,7 +1334,14 @@
       "pluginType": "core",
       "strict": true,
       "summary": "Set a research configuration key",
-      "stdoutIsPrimaryData": true
+      "stdoutIsPrimaryData": true,
+      "isESM": true,
+      "relativePath": [
+        "dist",
+        "commands",
+        "config",
+        "set.js"
+      ]
     },
     "config:unset": {
       "aliases": [],
@@ -1053,8 +1420,15 @@
       "pluginType": "core",
       "strict": true,
       "summary": "Remove a research configuration key",
-      "stdoutIsPrimaryData": true
+      "stdoutIsPrimaryData": true,
+      "isESM": true,
+      "relativePath": [
+        "dist",
+        "commands",
+        "config",
+        "unset.js"
+      ]
     }
   },
-  "version": "4.0.0"
+  "version": "4.1.1"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@taurgis/bonsai",
-  "version": "4.0.0",
+  "version": "4.1.1",
   "description": "Bonsai is a standalone local research cache CLI for AI agents",
   "repository": {
     "type": "git",
@@ -35,27 +35,23 @@
   },
   "dependencies": {
     "@mozilla/readability": "^0.5.0",
-    "@oclif/core": "^4.11.4",
-    "@oclif/plugin-autocomplete": "^3.2.52",
+    "@oclif/core": "^5.1.8",
+    "@oclif/plugin-autocomplete": "^4.0.4",
     "@toon-format/toon": "^4.0.0",
-    "linkedom": "^0.18.12",
+    "linkedom": "^0.18.13",
     "turndown": "^7.2.0",
-    "undici": "^8.7.0",
-    "update-notifier": "^7.3.1"
+    "undici": "^8.12.2"
   },
   "devDependencies": {
     "@changesets/cli": "^2.31.0",
-    "@types/jsdom": "^21.1.7",
-    "@types/mozilla-readability": "^0.2.1",
     "@types/node": "^22.10.0",
     "@types/turndown": "^5.0.5",
     "@vitest/coverage-istanbul": "^4.0.18",
     "eslint": "^10.7.0",
     "fallow": "^2.102.0",
     "husky": "^9.1.7",
-    "jsdom": "^26.0.0",
     "lint-staged": "^16.2.7",
-    "oclif": "^4.23.21",
+    "oclif": "^6.0.8",
     "prettier": "^3.8.1",
     "typescript": "^5.9.3",
     "typescript-eslint": "^8.64.0",
@@ -78,9 +74,8 @@
       "@oclif/plugin-autocomplete"
     ],
     "commands": {
-      "strategy": "explicit",
-      "target": "./dist/commands.js",
-      "identifier": "commands"
+      "strategy": "pattern",
+      "target": "./dist/commands"
     },
     "topicSeparator": " ",
     "hooks": {