@taurgis/bonsai 1.0.6 → 3.0.1

package/oclif.manifest.json

@@ -128,7 +128,7 @@
       "pluginAlias": "@taurgis/bonsai",
       "pluginName": "@taurgis/bonsai",
       "pluginType": "core",
-      "strict": true,
+      "strict": false,
       "summary": "An advanced, locally cached web research tool optimized for LLM ingestion.",
       "enableJsonFlag": true,
       "stdoutIsPrimaryData": true
@@ -155,6 +155,10 @@
         {
           "description": "import research from a local Markdown file",
           "command": "<%= config.bin %> import https://example.com/docs --file path/to/notes.md"
+        },
+        {
+          "description": "import research from stdin using the standard file placeholder",
+          "command": "cat notes.md | <%= config.bin %> import https://example.com/docs --file -"
         }
       ],
       "flags": {
@@ -172,7 +176,7 @@
           "type": "boolean"
         },
         "file": {
-          "description": "path to a Markdown file containing research notes to import",
+          "description": "path to a Markdown file containing research notes to import, or \"-\" for stdin",
           "name": "file",
           "hasDynamicHelp": false,
           "multiple": false,
@@ -292,7 +296,7 @@
       "pluginAlias": "@taurgis/bonsai",
       "pluginName": "@taurgis/bonsai",
       "pluginType": "core",
-      "strict": true,
+      "strict": false,
       "summary": "Inspect cached research metadata for a URL.",
       "enableJsonFlag": true,
       "stdoutIsPrimaryData": true
@@ -313,6 +317,10 @@
         {
           "description": "list only fresh entries filtered by tags",
           "command": "<%= config.bin %> list --freshness fresh --tags node --tags url"
+        },
+        {
+          "description": "list entries matching a specific URL glob",
+          "command": "<%= config.bin %> list --url \"https://react.dev/*\""
         }
       ],
       "flags": {
@@ -339,6 +347,13 @@
           "multiple": true,
           "type": "option"
         },
+        "url": {
+          "description": "filter by source URL glob pattern (case-insensitive, supports * wildcard)",
+          "name": "url",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
         "freshness": {
           "description": "filter by freshness state",
           "name": "freshness",
@@ -409,6 +424,10 @@
         {
           "description": "actually prune entries older than 30 days that are source scrapes",
           "command": "<%= config.bin %> prune --older-than 30d --artifact-type source --yes"
+        },
+        {
+          "description": "prune entries matching a URL glob pattern",
+          "command": "<%= config.bin %> prune --url \"https://react.dev/*\" --yes"
         }
       ],
       "flags": {
@@ -433,6 +452,13 @@
           "multiple": false,
           "type": "option"
         },
+        "url": {
+          "description": "filter pruning to source URL glob pattern (case-insensitive, supports * wildcard)",
+          "name": "url",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
         "artifact-type": {
           "description": "filter pruning to specific artifact type",
           "name": "artifact-type",
@@ -471,107 +497,6 @@
       "enableJsonFlag": true,
       "stdoutIsPrimaryData": true
     },
-    "search": {
-      "aliases": [],
-      "args": {
-        "query": {
-          "description": "the search query containing terms to match",
-          "name": "query",
-          "required": true
-        }
-      },
-      "description": "Scans the local research cache database and ranks matching entries based on topic, tags, source URLs, summary, and content.",
-      "examples": [
-        {
-          "description": "search for cached notes containing specific keywords",
-          "command": "<%= config.bin %> <%= command.id %> \"authentication flow\""
-        },
-        {
-          "description": "search with remote docs fallback",
-          "command": "<%= config.bin %> <%= command.id %> \"router\" --remote https://react.dev"
-        },
-        {
-          "description": "search local cache with tag filtering",
-          "command": "<%= config.bin %> <%= command.id %> \"setup\" --tags node --tags tutorial"
-        }
-      ],
-      "flags": {
-        "json": {
-          "description": "Format output as json.",
-          "helpGroup": "GLOBAL",
-          "name": "json",
-          "allowNo": false,
-          "type": "boolean"
-        },
-        "topic": {
-          "char": "t",
-          "description": "filter results by exact topic (case-insensitive)",
-          "name": "topic",
-          "hasDynamicHelp": false,
-          "multiple": false,
-          "type": "option"
-        },
-        "tags": {
-          "char": "g",
-          "description": "filter results by tags (must match all tags specified)",
-          "name": "tags",
-          "hasDynamicHelp": false,
-          "multiple": true,
-          "type": "option"
-        },
-        "artifact-type": {
-          "description": "filter results by artifact type",
-          "name": "artifact-type",
-          "hasDynamicHelp": false,
-          "multiple": false,
-          "options": [
-            "source",
-            "research_note",
-            "index",
-            "section"
-          ],
-          "type": "option"
-        },
-        "limit": {
-          "description": "maximum number of results to return (default 10, max 50)",
-          "name": "limit",
-          "default": 10,
-          "hasDynamicHelp": false,
-          "multiple": false,
-          "type": "option"
-        },
-        "include-stale": {
-          "description": "include stale expired cache entries in the search results",
-          "name": "include-stale",
-          "allowNo": false,
-          "type": "boolean"
-        },
-        "domain": {
-          "description": "search a documentation site directly (requires compatible site module)",
-          "name": "domain",
-          "hasDynamicHelp": false,
-          "multiple": false,
-          "type": "option"
-        },
-        "remote": {
-          "description": "discover uncached docs via public search or index (falls back to local cache)",
-          "name": "remote",
-          "hasDynamicHelp": false,
-          "multiple": false,
-          "type": "option"
-        }
-      },
-      "hasDynamicHelp": false,
-      "hiddenAliases": [],
-      "id": "search",
-      "pluginAlias": "@taurgis/bonsai",
-      "pluginName": "@taurgis/bonsai",
-      "pluginType": "core",
-      "strict": true,
-      "summary": "Search locally cached research artifacts by keywords.",
-      "enableJsonFlag": true,
-      "stdoutIsPrimaryData": true
-    },
     "status": {
       "aliases": [],
       "args": {
@@ -635,7 +560,7 @@
       "pluginAlias": "@taurgis/bonsai",
       "pluginName": "@taurgis/bonsai",
       "pluginType": "core",
-      "strict": true,
+      "strict": false,
       "summary": "Check the cache status of a URL without fetching or writing.",
       "enableJsonFlag": true,
       "stdoutIsPrimaryData": true
@@ -918,5 +843,5 @@
       "stdoutIsPrimaryData": true
     }
   },
-  "version": "1.0.6"
+  "version": "3.0.1"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@taurgis/bonsai",
-  "version": "1.0.6",
+  "version": "3.0.1",
   "description": "Bonsai is a standalone local research cache CLI for AI agents",
   "repository": {
     "type": "git",
@@ -19,27 +19,6 @@
     "oclif.manifest.json",
     "README.md"
   ],
-  "scripts": {
-    "build": "tsc -b && oclif manifest",
-    "prepack": "pnpm build",
-    "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:line-counts": "node scripts/check-line-counts.ts --all",
-    "lint:health": "pnpm test:coverage && pnpm exec fallow health --format human",
-    "prepare": "husky",
-    "regression:suite": "tsc -b && node testing/regression/run-suite.mjs",
-    "regression:promote": "tsc -b && node testing/regression/run-suite.mjs --promote",
-    "regression:check": "tsc -b && node testing/regression/run-suite.mjs --strict",
-    "audit:cli": "node testing/manual-audit.mjs",
-    "nexus:sync": "npx forward-nexus update && npx forward-nexus sync",
-    "test": "vitest",
-    "test:coverage": "vitest run --coverage",
-    "type-check": "tsc --noEmit",
-    "docs:dev": "vitepress dev docs",
-    "docs:build": "vitepress build docs",
-    "docs:preview": "vitepress preview docs"
-  },
   "lint-staged": {
     "src/**/*.ts": "prettier --write",
     "scripts/**/*.ts": "prettier --write",
@@ -51,9 +30,11 @@
     "@oclif/plugin-autocomplete": "^3.2.52",
     "linkedom": "^0.18.12",
     "turndown": "^7.2.0",
+    "undici": "^8.7.0",
     "update-notifier": "^7.3.1"
   },
   "devDependencies": {
+    "@changesets/cli": "^2.31.0",
     "@types/jsdom": "^21.1.7",
     "@types/mozilla-readability": "^0.2.1",
     "@types/node": "^22.10.0",
@@ -71,13 +52,16 @@
     "vue": "^3.5.39"
   },
   "engines": {
-    "node": ">=22"
+    "node": ">=22.19.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
   },
-  "packageManager": "pnpm@10.17.1",
   "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. The commands listed below search, 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 its full reference. The commands listed below inspect, list, import, and prune the local research cache.",
     "plugins": [
       "@oclif/plugin-autocomplete"
     ],
@@ -95,5 +79,30 @@
         "description": "Manage research cache storage configuration (global vs project)"
       }
     }
+  },
+  "scripts": {
+    "build": "tsc -b && oclif manifest",
+    "changeset": "changeset",
+    "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: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' });\"",
+    "publish:snapshot": "changeset version --snapshot snapshot && changeset publish --tag snapshot",
+    "release": "changeset publish",
+    "regression:suite": "tsc -b && node testing/regression/run-suite.mjs",
+    "regression:promote": "tsc -b && node testing/regression/run-suite.mjs --promote",
+    "regression:check": "tsc -b && node testing/regression/run-suite.mjs --strict",
+    "audit:cli": "node testing/manual-audit.mjs",
+    "nexus:sync": "npx forward-nexus update && npx forward-nexus sync",
+    "test": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "type-check": "tsc --noEmit",
+    "version-packages": "changeset version",
+    "docs:dev": "vitepress dev docs",
+    "docs:build": "vitepress build docs",
+    "docs:preview": "vitepress preview docs"
   }
-}
+}

package/dist/commands/index.d.ts

@@ -1,35 +0,0 @@
-import { BaseCommand } from '../base-command.js';
-export default class Bonsai extends BaseCommand<typeof Bonsai> {
-    static summary: string;
-    static description: string;
-    static examples: {
-        description: string;
-        command: string;
-    }[];
-    static args: {
-        url: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
-    };
-    static flags: {
-        topic: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
-        tags: import("@oclif/core/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/interfaces").CustomOptions>;
-        format: import("@oclif/core/interfaces").OptionFlag<"compressed" | "detailed", import("@oclif/core/interfaces").CustomOptions>;
-        tier: import("@oclif/core/interfaces").OptionFlag<"stable" | "standard" | "volatile", import("@oclif/core/interfaces").CustomOptions>;
-        ttl: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
-        'max-age': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
-        force: import("@oclif/core/interfaces").BooleanFlag<boolean>;
-        'dry-run': import("@oclif/core/interfaces").BooleanFlag<boolean>;
-        'allow-stale': import("@oclif/core/interfaces").BooleanFlag<boolean>;
-        rendered: import("@oclif/core/interfaces").BooleanFlag<boolean>;
-        storage: import("@oclif/core/interfaces").OptionFlag<"global" | "project" | undefined, import("@oclif/core/interfaces").CustomOptions>;
-    };
-    static stdoutIsPrimaryData: boolean;
-    init(): Promise<void>;
-    private executeCacheHit;
-    private executeCacheMiss;
-    private buildResultData;
-    private validateDurationFlags;
-    private resolveArtifact;
-    private persistFreshArtifact;
-    private persistSectionsIfFresh;
-    execute(): Promise<unknown>;
-}

package/dist/commands/index.js

@@ -1,306 +0,0 @@
-import { Args, Flags } from '@oclif/core';
-import { mkdtempSync, rmSync } from 'node:fs';
-import { tmpdir } from 'node:os';
-import { join } from 'node:path';
-import { BaseCommand } from '../base-command.js';
-import { writeArtifact, getArtifactPath } from '../lib/research/storage.js';
-import { writeArtifactSecurely } from '../lib/research/secure-write.js';
-import { evaluateFreshness, parseTtlToMs, checkMaxAgeExpired } from '../lib/research/freshness.js';
-import { revalidateCache, createArtifactFromFetch } from '../lib/research/revalidate.js';
-import { fetchStaticHtml, fetchText } from '../lib/research/fetcher.js';
-import { fetchRenderedHtml } from '../lib/research/browser.js';
-import { capturePage } from '../lib/research/capture.js';
-import { persistSectionArtifacts } from '../lib/research/docs/section-artifacts.js';
-import { resolveResearchTarget } from '../lib/research/resolve-target.js';
-import { detectSite } from '../sites/index.js';
-const CAPTURE_DEPS = {
-    fetchStatic: (url) => fetchStaticHtml(url),
-    fetchRendered: (url) => fetchRenderedHtml(url),
-    fetchText: (url) => fetchText(url),
-};
-export default class Bonsai extends BaseCommand {
-    static summary = 'An advanced, locally cached web research tool optimized for LLM ingestion.';
-    static description = 'Scrapes the specified URL, strips HTML boilerplate, converts the semantic payload into clean Markdown format, and caches the result locally using dynamic TTL rules.';
-    static examples = [
-        {
-            description: 'Research a URL with detailed output, tagged with topic and tags',
-            command: '<%= config.bin %> https://docs.nestjs.com/ --topic "Backend Frameworks" --tags "Node" --tags "NestJS" --format detailed --ttl 30d',
-        },
-        {
-            description: 'Research a volatile page with compressed output and short TTL, returned as JSON',
-            command: '<%= config.bin %> https://news.ycombinator.com/ --format compressed --ttl 2h --json',
-        },
-    ];
-    static args = {
-        url: Args.string({
-            required: true,
-            description: 'The full HTTP/HTTPS URL of the web page to research.',
-        }),
-    };
-    static flags = {
-        topic: Flags.string({
-            char: 't',
-            description: 'The main category/topic of the research for metadata tagging.',
-        }),
-        tags: Flags.string({
-            char: 'g',
-            description: 'Taxonomic tags for this research (can be repeated).',
-            multiple: true,
-        }),
-        format: Flags.option({
-            char: 'f',
-            description: 'Desired data density.',
-            options: ['compressed', 'detailed'],
-            default: 'compressed',
-        })(),
-        tier: Flags.option({
-            description: 'Freshness tier policy.',
-            options: ['stable', 'standard', 'volatile'],
-            default: 'standard',
-        })(),
-        ttl: Flags.string({
-            char: 'l',
-            description: 'Predicted lifespan of the data (e.g., "2h", "7d", "3m").',
-        }),
-        'max-age': Flags.string({
-            description: 'Maximum age of cache to accept (e.g., "1d", "30d").',
-        }),
-        force: Flags.boolean({
-            description: 'Force a fresh fetch, ignoring any cached entries.',
-            default: false,
-        }),
-        'dry-run': Flags.boolean({
-            description: 'Perform validation and fetch without saving to local cache.',
-            default: false,
-        }),
-        'allow-stale': Flags.boolean({
-            description: 'Allow serving stale cache if the remote server is unreachable.',
-            default: false,
-        }),
-        rendered: Flags.boolean({
-            description: 'Force using a browser-rendered scraping path for dynamic pages.',
-            default: false,
-        }),
-        storage: Flags.option({
-            description: 'Override where this result is cached (overrides configured default). Secret-bearing pages are always stored globally.',
-            options: ['global', 'project'],
-        })(),
-    };
-    static stdoutIsPrimaryData = true;
-    async init() {
-        await super.init();
-        const { args, flags } = await this.parse(Bonsai);
-        this.args = args;
-        this.flags = flags;
-    }
-    async executeCacheHit(cached, targetDir, currentTime) {
-        const { ttl, 'max-age': maxAge, 'allow-stale': allowStale, rendered } = this.flags;
-        const isExpired = checkMaxAgeExpired(cached, currentTime, maxAge);
-        const freshnessState = isExpired
-            ? 'stale_expired'
-            : evaluateFreshness(cached.metadata, currentTime, ttl);
-        if (freshnessState === 'fresh') {
-            return { cacheStatus: 'hit', freshnessState, artifact: cached };
-        }
-        const revalResult = await revalidateCache(targetDir, cached, currentTime, {
-            allowStale: Boolean(allowStale),
-            ttlOverride: ttl,
-            rendered: Boolean(rendered),
-        });
-        handleStaleRevalidationResult(this, revalResult);
-        return {
-            cacheStatus: revalResult.status,
-            freshnessState,
-            artifact: revalResult.artifact,
-        };
-    }
-    async executeCacheMiss(normalizedUrl, currentTime, cacheKey) {
-        const { topic, tags, tier, ttl, rendered } = this.flags;
-        const siteModule = detectSite(normalizedUrl);
-        const useRendered = rendered || Boolean(siteModule?.defaults?.rendered);
-        let fetchResult;
-        let extraction;
-        let capture = null;
-        if (siteModule?.fetchPage) {
-            // Custom site modules own their fetch/extract strategy; the generic capture path is skipped.
-            ({ fetchResult, extraction } = await siteModule.fetchPage(normalizedUrl));
-        }
-        else {
-            capture = await capturePage(normalizedUrl, { forceRendered: useRendered }, CAPTURE_DEPS);
-            fetchResult = capture.fetchResult;
-            extraction = capture.extraction;
-        }
-        const artifact = createArtifactFromFetch(normalizedUrl, normalizedUrl, cacheKey, fetchResult, extraction, tier, ttl || null, currentTime);
-        artifact.metadata.topic = topic || null;
-        artifact.metadata.tags = tags || [];
-        artifact.metadata.site_module_id = siteModule?.id ?? null;
-        if (capture) {
-            applyCaptureMetadata(artifact, capture);
-        }
-        else if (useRendered) {
-            artifact.metadata.capture_method = 'browser_fallback';
-        }
-        return artifact;
-    }
-    buildResultData(url, normalizedUrl, cacheKey, storageDir, storageMode, cacheStatus, freshnessState, format, artifact, content, redirectedToGlobal) {
-        return {
-            schemaVersion: 1,
-            command: this.config.bin,
-            cache: {
-                key: cacheKey,
-                status: cacheStatus,
-                freshness: freshnessState,
-                path: getArtifactPath(storageDir, cacheKey),
-                storage: storageMode,
-                redirectedToGlobal,
-            },
-            source: {
-                url,
-                normalizedUrl,
-                captureMethod: artifact.metadata.capture_method,
-                extractionStatus: artifact.metadata.extraction_status,
-                extractionConfidence: artifact.metadata.extraction_confidence,
-                qualityNotes: artifact.metadata.quality_notes,
-                fetchedAt: artifact.metadata.fetched_at,
-                validatedAt: artifact.metadata.validated_at,
-                staleAfter: artifact.metadata.stale_after,
-            },
-            artifactType: artifact.metadata.artifact_type,
-            docsEngine: artifact.metadata.docs_engine,
-            docsFramework: artifact.metadata.docs_framework,
-            sourceDocUrl: artifact.metadata.source_doc_url,
-            searchProvider: artifact.metadata.search_provider,
-            format,
-            tokenEstimate: format === 'compressed'
-                ? artifact.metadata.token_estimate.compressed
-                : artifact.metadata.token_estimate.detailed,
-            content,
-        };
-    }
-    // Validates the duration flags up front, exiting with code 2 on a malformed value.
-    validateDurationFlags(ttl, maxAge) {
-        for (const [label, value] of [
-            ['TTL', ttl],
-            ['max-age', maxAge],
-        ]) {
-            if (!value)
-                continue;
-            try {
-                parseTtlToMs(value);
-            }
-            catch (err) {
-                this.error(`Invalid ${label}: ${err.message}`, { exit: 2 });
-            }
-        }
-    }
-    // Serves the cache when a fresh/revalidatable entry exists, otherwise fetches fresh. Reads fall
-    // back project→global; the resolved artifact is returned with the dir it lives in / landed in.
-    async resolveArtifact(normalizedUrl, cacheKey, roots, tmpDir, currentTime, located) {
-        if (located) {
-            // Revalidate where the entry already lives; on dry-run use the throwaway dir so the cache is
-            // never mutated. ponytail: revalidation rewrites in place, so a refreshed project entry that
-            // gains a secret is not re-routed — only first-time project writes are scanned.
-            const revalDir = tmpDir ?? located.dataDir;
-            const hit = await this.executeCacheHit(located.artifact, revalDir, currentTime);
-            return { ...hit, storageDir: located.dataDir, redirectedToGlobal: false };
-        }
-        const artifact = await this.executeCacheMiss(normalizedUrl, currentTime, cacheKey);
-        const { dir, redirectedToGlobal } = this.persistFreshArtifact(roots, tmpDir, cacheKey, artifact);
-        return {
-            cacheStatus: 'miss',
-            freshnessState: 'stale_expired',
-            artifact,
-            storageDir: dir,
-            redirectedToGlobal,
-        };
-    }
-    // Writes a freshly fetched artifact, honoring dry-run (throwaway dir) and the secret-safety
-    // redirect (project→global). Returns the data dir reported to the user and whether a redirect
-    // occurred (so the JSON envelope mirrors `import`).
-    persistFreshArtifact(roots, tmpDir, cacheKey, artifact) {
-        if (tmpDir) {
-            writeArtifact(tmpDir, cacheKey, artifact);
-            // Report the real would-be location, not the throwaway dir that is about to be deleted.
-            return { dir: roots.writeRoot, redirectedToGlobal: false };
-        }
-        const result = writeArtifactSecurely(roots, cacheKey, artifact);
-        if (result.redirected) {
-            this.warn(`Detected ${result.secretLabel} in the page content; stored in the global cache instead of the project to avoid committing secrets.`);
-        }
-        return { dir: result.dataDir, redirectedToGlobal: result.redirected };
-    }
-    // Long references are split into searchable/inspectable section children whenever the page artifact
-    // is freshly written (T-22). Best-effort: never let chunking break the main result.
-    persistSectionsIfFresh(targetDir, artifact, currentTime, cacheStatus) {
-        if (cacheStatus !== 'miss' && cacheStatus !== 'refreshed')
-            return;
-        try {
-            persistSectionArtifacts(targetDir, artifact, currentTime);
-        }
-        catch {
-            /* section generation is non-essential; ignore failures */
-        }
-    }
-    async execute() {
-        const { url } = this.args;
-        const { format, ttl, 'max-age': maxAge, 'dry-run': dryRun } = this.flags;
-        this.validateDurationFlags(ttl, maxAge);
-        let target;
-        try {
-            target = resolveResearchTarget({
-                configDir: this.config.configDir,
-                cwd: process.cwd(),
-                dataDir: this.config.dataDir,
-                flagOverride: this.flags.storage,
-                lookup: !this.flags.force,
-                url,
-            });
-        }
-        catch (err) {
-            this.error(`Invalid URL: ${err.message}`, { exit: 2 });
-        }
-        const { cacheKey, located, normalizedUrl, roots } = target;
-        const tmpDir = dryRun ? mkdtempSync(join(tmpdir(), 'fnr-dry-run-')) : null;
-        const currentTime = new Date();
-        try {
-            const { cacheStatus, freshnessState, artifact, storageDir, redirectedToGlobal } = await this.resolveArtifact(normalizedUrl, cacheKey, roots, tmpDir, currentTime, located);
-            this.persistSectionsIfFresh(tmpDir ?? storageDir, artifact, currentTime, cacheStatus);
-            const content = format === 'compressed' ? artifact.compressed : artifact.detailed;
-            const resultData = this.buildResultData(url, normalizedUrl, cacheKey, storageDir, roots.mode, cacheStatus, freshnessState, format, artifact, content, redirectedToGlobal);
-            if (!this.requestedJson()) {
-                this.log(content);
-            }
-            return resultData;
-        }
-        finally {
-            if (tmpDir) {
-                rmSync(tmpDir, { recursive: true, force: true });
-            }
-        }
-    }
-}
-// Copies Phase 2 capability provenance from a capture outcome onto the artifact metadata.
-function applyCaptureMetadata(artifact, capture) {
-    const meta = artifact.metadata;
-    meta.capture_method = capture.captureMethod;
-    meta.docs_engine = capture.capabilities.docsEngine ?? null;
-    meta.docs_framework = capture.capabilities.framework ?? null;
-    meta.source_doc_url = capture.sourceDocUrl;
-    meta.search_provider = capture.capabilities.search?.provider ?? null;
-    if (capture.extraction.isIndexHub)
-        meta.artifact_type = 'index';
-    if (capture.sourceDocUrl && !meta.source_urls.includes(capture.sourceDocUrl)) {
-        meta.source_urls.push(capture.sourceDocUrl);
-    }
-}
-function handleStaleRevalidationResult(command, revalResult) {
-    if (revalResult.status !== 'stale')
-        return;
-    if (revalResult.allowed) {
-        command.warn(`Serving stale content: revalidation failed: ${revalResult.error}`);
-    }
-    else {
-        command.warn(`Serving stale content (exit 5): revalidation failed: ${revalResult.error}`);
-        process.exitCode = 5;
-    }
-}

package/dist/commands/research/config/base.d.ts

@@ -1,23 +0,0 @@
-import { Command } from '@oclif/core';
-import { BaseCommand } from '../../../base-command.js';
-import type { ConfigKey, ConfigScope } from '../../../lib/config/index.js';
-/**
- * Shared base for the four `research config` subcommands: the mutually-exclusive
- * scope-flag guard, the binary write-scope helper, and known-key validation.
- */
-export declare abstract class ConfigCommand<T extends typeof Command> extends BaseCommand<T> {
-    protected assertScopeFlagsExclusive(global?: boolean, local?: boolean): void;
-    /** `--local` writes/reads the project file; otherwise the user-level file. */
-    protected writeScope(local?: boolean): 'user' | 'project';
-    /** Read scope for get/list: an explicit `--global`/`--local`, else the merged effective view. */
-    protected readScope(global?: boolean, local?: boolean): ConfigScope;
-    protected assertKnownKey(keyArg: string): asserts keyArg is ConfigKey;
-}
-/** Build the `--global`/`--local` scope-flag pair with per-command descriptions. */
-export declare function configScopeFlags(descriptions: {
-    global: string;
-    local: string;
-}): {
-    global: import("@oclif/core/interfaces").BooleanFlag<boolean>;
-    local: import("@oclif/core/interfaces").BooleanFlag<boolean>;
-};