@taurgis/bonsai 3.1.0 → 3.2.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@taurgis/bonsai",
-  "version": "3.1.0",
+  "version": "3.2.2",
   "description": "Bonsai is a standalone local research cache CLI for AI agents",
   "repository": {
     "type": "git",
@@ -20,9 +20,18 @@
     "README.md"
   ],
   "lint-staged": {
-    "src/**/*.ts": "prettier --write",
-    "scripts/**/*.ts": "prettier --write",
-    "tests/**/*.ts": "prettier --write"
+    "src/**/*.ts": [
+      "prettier --write",
+      "eslint --fix --max-warnings 0"
+    ],
+    "scripts/**/*.ts": [
+      "prettier --write",
+      "eslint --fix --max-warnings 0"
+    ],
+    "tests/**/*.ts": [
+      "prettier --write",
+      "eslint --fix --max-warnings 0"
+    ]
   },
   "dependencies": {
     "@mozilla/readability": "^0.5.0",
@@ -40,6 +49,7 @@
     "@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",
@@ -47,6 +57,7 @@
     "oclif": "^4.23.21",
     "prettier": "^3.8.1",
     "typescript": "^5.9.3",
+    "typescript-eslint": "^8.64.0",
     "vitepress": "^1.6.4",
     "vitest": "^4.0.17",
     "vue": "^3.5.39"
@@ -61,7 +72,7 @@
   "oclif": {
     "bin": "bonsai",
     "dirname": "bonsai",
-    "description": "Bonsai is a standalone local research cache CLI for AI agents.\nResearch and cache a web page by passing its URL directly:\n\n  $ bonsai https://nodejs.org/api/url.html\n\nThe URL form is shorthand for fetching and caching the page; run `bonsai help fetch` for its full reference. The commands listed below inspect, list, import, and prune the local research cache.",
+    "description": "Bonsai is a standalone local research cache CLI for AI agents.\nResearch and cache a web page by passing its URL directly:\n\n  $ bonsai https://nodejs.org/api/url.html\n\nThe URL form is shorthand for fetching and caching the page; run `bonsai help fetch` for URL-form flags. Commands below inspect, list, import, and prune the local research cache.\n\nShort flags are command-local; check each command's --help before reusing -f, -g, -t, or -l.",
     "plugins": [
       "@oclif/plugin-autocomplete"
     ],
@@ -76,7 +87,7 @@
     },
     "topics": {
       "config": {
-        "description": "Manage research cache storage configuration (global vs project)"
+        "description": "Manage research cache configuration"
       }
     }
   },
@@ -86,7 +97,8 @@
     "changeset:status": "changeset status --verbose",
     "format": "prettier --write \"src/**/*.ts\" \"tests/**/*.ts\" \"scripts/**/*.ts\"",
     "format:check": "prettier --check \"src/**/*.ts\" \"tests/**/*.ts\" \"scripts/**/*.ts\"",
-    "lint": "pnpm lint:line-counts && pnpm lint:health",
+    "lint": "pnpm lint:eslint && pnpm lint:line-counts && pnpm lint:health",
+    "lint:eslint": "eslint \"src/**/*.ts\" \"tests/**/*.ts\" \"scripts/**/*.ts\" --max-warnings 0",
     "lint:line-counts": "node scripts/check-line-counts.ts --all",
     "lint:health": "pnpm test:coverage && pnpm exec fallow health --format human",
     "postinstall": "node -e \"if (process.env.CI || process.env.FORWARD_NEXUS_SKIP_SYNC) { console.log('Skipping forward-nexus sync.'); process.exit(0); } require('node:child_process').execFileSync('npx', ['forward-nexus', 'sync', '--pull'], { stdio: 'inherit' });\"",

package/agents/agents/official-docs-researcher.agent.md

@@ -1,87 +0,0 @@
----
-name: 'Official Docs Researcher'
-description: 'Researches official documentation through Bonsai and returns source-cited findings'
-model: 'Auto'
-tools: ['vscode/askQuestions', 'execute', 'read', 'search', 'web', 'vscode/memory']
-argument-hint: 'What topic should I research in official docs?'
-metadata:
-  version: '4.0.0'
----
-
-# Official Docs Researcher Agent
-
-You are a Forward documentation research specialist. Your job is to find current official documentation, cache it through Bonsai, and return concise source-cited findings that another agent can apply safely.
-
-## Scope
-
-Use this agent for technical changes, platform behavior, APIs, SDKs, standards, release notes, changelogs, beta docs, security advisories, and other documentation-sensitive work.
-
-Do not research from memory alone. Training-data knowledge does not satisfy this workflow.
-
-## Invocation
-
-Run Bonsai as `npx @taurgis/bonsai ...`. Add `--json` when you need structured output.
-
-## Default Workflow
-
-1. Identify the product, version, edition, and source authority needed for the request.
-2. Locate official source URLs. Prefer vendor docs, standards bodies, API references, and official release notes. Use your native web/search tools when you do not yet know the URL.
-3. Capture each source through Bonsai:
-
-   ```bash
-   npx @taurgis/bonsai <official-url> --format detailed
-   ```
-
-4. Use `--rendered` for SPAs or pages where static extraction is incomplete:
-
-   ```bash
-   npx @taurgis/bonsai <official-url> --rendered --format detailed
-   ```
-
-5. Summarize only what the official sources support. Include source URLs, validation time when available, version notes, and any important limitations.
-
-For structured output:
-
-```bash
-npx @taurgis/bonsai <official-url> --format detailed --json
-```
-
-## Freshness Policy
-
-Choose the freshness tier based on the source:
-
-- `stable`: standards, specs, MDN reference pages, pinned major-version docs.
-- `standard`: vendor API docs, SDK docs, normal technical references.
-- `volatile`: release notes, changelogs, latest pages, security advisories, beta docs.
-
-Stale volatile sources must be revalidated before they are trusted. Never overwrite a good cache entry with an error response.
-
-## Fallbacks
-
-If direct web access was unavoidable because Bonsai could not fetch the content, import the synthesized notes back into Bonsai before returning:
-
-```bash
-npx @taurgis/bonsai import <url> --file <path>
-```
-
-For multi-source synthesis:
-
-```bash
-npx @taurgis/bonsai import \
-  --topic "<descriptive topic>" \
-  --source-url <url1> \
-  --source-url <url2> \
-  --file <path>
-```
-
-## Response Contract
-
-Return:
-
-- Answer summary.
-- Official source URLs used.
-- Version, edition, or date constraints.
-- Cache status or validation timestamp when Bonsai output provides it.
-- Gaps or uncertainty where official docs do not answer the question.
-
-Keep stdout clean when using `--json`; warnings and diagnostic notes belong in stderr or in the final prose summary.

package/agents/instructions/web-research.instructions.md

@@ -1,44 +0,0 @@
----
-description: 'Verify current official docs before technical repo changes — inline via the web-research skill for minor research, via the Official Docs Researcher subagent for extensive research.'
-applyTo: '**'
-skills:
-  - web-research
-metadata:
-  version: '4.0.0'
----
-
-# Web Research Requirement
-
-## Mandatory Pre-Step
-
-- Verify the relevant current official documentation **in the same task** before creating, updating, refactoring, scaffolding, or deleting technical content.
-- Apply what you find — cite official source URLs when the change relies on platform behavior or standards.
-- Research is the requirement; how you run it scales with scope (below). Training-data knowledge never satisfies this — only docs fetched in the current task do.
-
-## Choose How to Research by Scope
-
-- **Minor research — run it inline.** For a single known page, one platform, or a quick flag/API/version check, the main agent invokes the **web-research** skill directly. A separate subagent is not required.
-- **Extensive research — delegate to a subagent.** For multiple sources or platforms, unfamiliar territory, broad audits, or anything that produces verbose output you do not want in the main context, run the **Official Docs Researcher** subagent and apply its findings.
-- The main agent may always use the **web-research** skill directly — choose the subagent to isolate large research, not because inline research is disallowed.
-- When unsure, start inline and escalate to the subagent once the work spans several sources.
-
-## Shared Cache
-
-- **Invocation**: Run Bonsai as `npx @taurgis/bonsai ...`.
-- **URL discovery**: When you do not yet know the official URL, discover it with your native web/search tools, then fetch the page through Bonsai so it is cached for future agents.
-- If Bonsai is configured for project storage and `.bonsai/research/` is not ignored by git, treat those cache artifacts as intentional shared project files. It is OK to check them in, and agents must not delete them as incidental generated output without an explicit request.
-- Re-running on a recent topic is cheap — research the topic rather than skipping it to "save" a fetch.
-
-## When Not to Use
-
-- No technical content is being modified (purely editorial changes).
-- You already fetched and applied official docs **in the current task**. Training-data knowledge does not satisfy this — only docs fetched in the same task do.
-- The request is too simple to warrant research (typo, lint fix not involving platform behavior).
-
-## Examples
-
-- ✅ Confirming one platform's current flag or frontmatter field before a small edit → run the web-research skill inline.
-- ✅ Comparing conventions across several platforms, or auditing/refactoring source broadly → delegate to the Official Docs Researcher subagent.
-- ✅ Before editing instructions, prompts, agents, skills, workflows, or docs — reading source code does not replace checking current platform guidance.
-- ✅ Include official source URLs when the change references platform behavior or standards.
-- ❌ Don't modify technical content without researching first, and don't treat cached or training knowledge as equivalent — official guidance evolves and must be verified per task.

package/agents/skills/web-research/SKILL.md

@@ -1,118 +0,0 @@
----
-name: web-research
-description: 'Bonsai-backed official documentation and web research workflow. Use before technical changes that depend on platform behavior, when fetching documentation or web pages, when listing/pruning the local research cache, or when importing manually gathered notes.'
-license: Forward Proprietary
-compatibility: VS Code 1.x+, GitHub Copilot
-metadata:
-  version: '3.0.0'
----
-
-# Web Research Skill
-
-Use Bonsai as the cache-first research path for official documentation and web content. Prefer current official sources, keep research reusable, and avoid direct one-off web fetches when Bonsai can capture the same page.
-
-## Invocation
-
-Always run Bonsai through the published npm package:
-
-```bash
-npx @taurgis/bonsai <command> [flags]
-```
-
-Add `--json` when you need machine-readable output for agent callers.
-
-## Required Pre-Step
-
-Before creating, updating, refactoring, scaffolding, or deleting technical content, verify relevant current official documentation in the same task.
-
-When you do not yet know the official URL, discover it with your native web/search tools first. Once you have a URL, capture it through Bonsai:
-
-```bash
-npx @taurgis/bonsai <official-url> --format detailed
-```
-
-For agent callers that need structured output:
-
-```bash
-npx @taurgis/bonsai <official-url> --format detailed --json
-```
-
-## Source Rules
-
-- Prefer official vendor docs, standards, API references, SDK docs, release notes, changelogs, and security advisories.
-- Include official source URLs when the change relies on platform behavior or standards.
-- Use `--tier stable`, `--tier standard`, or `--tier volatile` when the source class is clear.
-- Treat volatile sources as needing fresh validation before trusting them.
-- Do not use the retired manual `artifacts/online-research/` protocol for new research.
-
-## Fetch Rules
-
-Use `--format compressed` for context-budgeted reading and `--format detailed` for exact technical details, links, tables, and code examples.
-
-Use `--rendered` when static extraction is incomplete or the page is an SPA:
-
-```bash
-npx @taurgis/bonsai <official-url> --rendered --format detailed
-```
-
-Never reach for direct `WebFetch` or `WebSearch` to retrieve a specific page when Bonsai can fetch it. Bonsai returns reusable Markdown and keeps it cached for future agents.
-
-## Manual Fallbacks
-
-If direct web access was unavoidable because of authentication, browser interaction, or a tool constraint, import the result into Bonsai before returning.
-
-Single-source import:
-
-```bash
-npx @taurgis/bonsai import <url> --file path/to/notes.md
-```
-
-Stdin import:
-
-```bash
-echo "# My Synthesis Note" | npx @taurgis/bonsai import <url> --stdin
-```
-
-Multi-source synthesis:
-
-```bash
-npx @taurgis/bonsai import \
-  --topic "<descriptive topic>" \
-  --source-url <url1> \
-  --source-url <url2> \
-  --file path/to/synthesized-notes.md
-```
-
-## Cache Operations
-
-Check status without fetching:
-
-```bash
-npx @taurgis/bonsai status <url>
-```
-
-Inspect stored metadata:
-
-```bash
-npx @taurgis/bonsai inspect <url>
-```
-
-List cached entries by metadata:
-
-```bash
-npx @taurgis/bonsai list --tags node
-```
-
-Preview pruning before deleting:
-
-```bash
-npx @taurgis/bonsai prune --older-than 90d --dry-run
-npx @taurgis/bonsai prune --older-than 90d --yes
-```
-
-## When This Does Not Apply
-
-- No technical content or web content is involved.
-- You already fetched and applied current official docs in the current task.
-- The request is a trivial typo or formatting fix that does not involve platform behavior.
-- `npx @taurgis/bonsai` is unavailable in the environment; use the best available official-source workflow and import notes later.