@taurgis/bonsai 1.0.5 → 3.0.0

package/dist/commands/fetch.js

@@ -1,4 +1,4 @@
-import { Args, Flags } from '@oclif/core';
+import { Args, Flags, ux, Errors } from '@oclif/core';
 import { mkdtempSync, rmSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
@@ -12,7 +12,6 @@ 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 { applyAutoTags } from '../lib/research/keywords.js';
 import { detectSite } from '../sites/index.js';
 const CAPTURE_DEPS = {
@@ -27,66 +26,67 @@ export default class FetchCommand extends BaseCommand {
     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.\n\nUsually invoked via the shorthand `bonsai <url>` rather than `bonsai fetch <url>`.';
     static examples = [
         {
-            description: 'Research a URL with detailed output, tagged with topic and tags',
+            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',
+            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 strict = false;
     static args = {
         url: Args.string({
             required: true,
-            description: 'The full HTTP/HTTPS URL of the web page to research.',
+            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.',
+            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).',
+            description: 'taxonomic tags for this research (can be repeated)',
             multiple: true,
         }),
         format: Flags.option({
             char: 'f',
-            description: 'Desired data density.',
+            description: 'desired data density',
             options: ['compressed', 'detailed'],
             default: 'compressed',
         })(),
         tier: Flags.option({
-            description: 'Freshness tier policy.',
+            description: 'freshness tier policy',
             options: ['stable', 'standard', 'volatile'],
             default: 'standard',
         })(),
         ttl: Flags.string({
             char: 'l',
-            description: 'Predicted lifespan: number + h/d/w/m/y (m = months), e.g. "2h", "7d", "6m".',
+            description: 'predicted lifespan: number + h/d/w/m/y (m = months), e.g. "2h", "7d", "6m"',
         }),
         'max-age': Flags.string({
-            description: 'Maximum age of cache to accept (e.g., "1d", "30d").',
+            description: 'maximum age of cache to accept (e.g., "1d", "30d")',
         }),
         force: Flags.boolean({
-            description: 'Force a fresh fetch, ignoring any cached entries.',
+            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.',
+            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.',
+            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.',
+            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.',
+            description: 'override where this result is cached (secrets always stored globally)',
             options: ['global', 'project'],
         })(),
     };
@@ -185,7 +185,7 @@ export default class FetchCommand extends BaseCommand {
     validateDurationFlags(ttl, maxAge) {
         for (const msg of [durationFlagError('--ttl', ttl), durationFlagError('--max-age', maxAge)]) {
             if (msg)
-                this.error(msg, { exit: 2 });
+                this.error(msg, { exit: 2, code: 'INVALID_DURATION' });
         }
     }
     // Re-emit a runtime fetch failure with actionable next steps. Deep fetch/extract code throws plain
@@ -197,7 +197,12 @@ export default class FetchCommand extends BaseCommand {
     emitFetchError(err, url) {
         const message = err instanceof Error ? err.message : String(err);
         const guidance = fetchFailureGuidance(message, url);
-        this.error(message, { exit: 1, suggestions: guidance?.suggestions, ref: guidance?.ref });
+        this.error(message, {
+            exit: 1,
+            code: 'FETCH_FAILED',
+            suggestions: guidance?.suggestions,
+            ref: guidance?.ref,
+        });
     }
     // 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.
@@ -251,43 +256,31 @@ export default class FetchCommand extends BaseCommand {
         }
     }
     async run() {
-        const { url } = this.args;
+        const urls = this.parsedArgv;
         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 summaryLevel = loadSummaryLevel(this.config.configDir, process.cwd());
         const tmpDir = dryRun ? mkdtempSync(join(tmpdir(), 'fnr-dry-run-')) : null;
         const currentTime = new Date();
+        const results = [];
         try {
-            const { cacheStatus, freshnessState, artifact, storageDir, redirectedToGlobal } = await this.resolveArtifact(normalizedUrl, cacheKey, roots, tmpDir, currentTime, located, summaryLevel);
-            this.persistSectionsIfFresh(tmpDir ?? storageDir, artifact, currentTime, cacheStatus, summaryLevel);
-            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.jsonEnabled()) {
-                this.log(content);
+            for (const url of urls) {
+                results.push(await this.fetchSingleTarget(url, currentTime, tmpDir, summaryLevel, format, urls.length > 1));
             }
-            return resultData;
+            return urls.length === 1 ? results[0] : results;
         }
         catch (err) {
+            if (!this.jsonEnabled()) {
+                ux.action.stop('failed');
+            }
+            if (err instanceof Errors.CLIError)
+                throw err;
             // Stale-serve (exit 5) signals via process.exitCode and never throws, so it bypasses this
             // path; only genuine fetch/extract failures land here and get classified guidance. Use the
             // normalized URL in hints so the copy-paste command is canonical (and never echoes raw,
             // unsanitized user input back to the terminal).
-            this.emitFetchError(err, normalizedUrl);
+            const failedUrl = urls[results.length] || urls[0] || '';
+            this.emitFetchError(err, failedUrl);
         }
         finally {
             if (tmpDir) {
@@ -295,13 +288,44 @@ export default class FetchCommand extends BaseCommand {
             }
         }
     }
+    async fetchSingleTarget(url, currentTime, tmpDir, summaryLevel, format, showSeparator) {
+        const target = this.resolveResearchTargetOrFail(url, {
+            flagOverride: this.flags.storage,
+            lookup: !this.flags.force,
+        });
+        const { cacheKey, located, normalizedUrl, roots } = target;
+        if (!this.jsonEnabled()) {
+            ux.action.start('Fetching ' + normalizedUrl);
+        }
+        const { cacheStatus, freshnessState, artifact, storageDir, redirectedToGlobal } = await this.resolveArtifact(normalizedUrl, cacheKey, roots, tmpDir, currentTime, located, summaryLevel);
+        this.persistSectionsIfFresh(tmpDir ?? storageDir, artifact, currentTime, cacheStatus, summaryLevel);
+        if (!this.jsonEnabled()) {
+            const CACHE_STATUS_LABEL = {
+                hit: 'cached',
+                miss: 'done',
+                refreshed: 'refreshed',
+                revalidated: 'revalidated',
+                stale: 'served stale',
+            };
+            ux.action.stop(CACHE_STATUS_LABEL[cacheStatus] ?? 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.jsonEnabled()) {
+            this.log(content);
+            if (showSeparator) {
+                this.log('\n' + '='.repeat(40) + '\n');
+            }
+        }
+        return resultData;
+    }
 }
 // Maps a runtime fetch failure to recovery steps keyed off its message. Returns undefined for
 // unrecognized failures, which then surface with their original message and no extra hint. The
 // patterns match the thrown text in fetcher.ts/browser.ts; keep them in sync if those messages
 // change. Resolutions mirror the published troubleshooting guide.
 export function fetchFailureGuidance(message, url) {
-    const ref = 'https://taurgis.github.io/bonsai/troubleshooting';
+    const ref = 'https://bonsai.rhino-inquisitor.com/troubleshooting';
     // Name the pipe step explicitly: bare `import --stdin` blocks waiting for input, so a reader (or
     // an agent) running the hint verbatim would hang. Show the content being piped in from a file.
     const importHint = `Open it in a browser, save the page, then import it: cat page.md | bonsai import ${url} --stdin`;
@@ -367,10 +391,10 @@ function handleStaleRevalidationResult(command, revalResult) {
     if (revalResult.status !== 'stale')
         return;
     if (revalResult.allowed) {
-        command.warn(`Serving stale content: revalidation failed: ${revalResult.error}`);
+        command.warn(`Serving stale content within grace period: revalidation failed (${revalResult.error}).`);
     }
     else {
-        command.warn(`Serving stale content (exit 5): revalidation failed: ${revalResult.error}`);
+        command.warn(`Serving stale content within grace period (exit 5): revalidation failed (${revalResult.error}).`);
         process.exitCode = 5;
     }
 }

package/dist/commands/import.d.ts

@@ -30,6 +30,9 @@ export default class ResearchImport extends BaseCommand<typeof ResearchImport> {
     protected fsExistsSync(filePath: string): boolean;
     protected fsStatSync(filePath: string): fs.Stats;
     protected fsReadFileSync(filePath: string): string;
+    private stdinImportSuggestions;
+    /** Non-interactive stdin that never receives data (open pipe with no writer) must not hang forever. */
+    private readStdinWithGuard;
     private readAndValidateFile;
     private readAndValidateInput;
     private deriveImportCacheKey;

package/dist/commands/import.js

@@ -9,7 +9,7 @@ import { getArtifactPath } from '../lib/research/storage.js';
 import { loadStoreRoots } from '../lib/research/store-roots.js';
 import { writeArtifactSecurely } from '../lib/research/secure-write.js';
 import { loadSummaryLevel } from '../lib/config/index.js';
-import { getPolicy } from '../lib/research/freshness.js';
+import { durationFlagError, getPolicy } from '../lib/research/freshness.js';
 import { buildCompressed } from '../lib/research/compress.js';
 import { applyAutoTags } from '../lib/research/keywords.js';
 import { estimateTokens } from '../lib/research/token-estimate.js';
@@ -19,17 +19,21 @@ export default class ResearchImport extends BaseCommand {
     static description = 'Accepts a synthesized Markdown note via stdin and registers it under the single target URL or multiple source URLs.';
     static examples = [
         {
-            description: 'Import detailed research for a single URL via stdin',
+            description: 'import detailed research for a single URL via stdin',
             command: 'echo "# My Article" | <%= config.bin %> import https://example.com/docs --stdin',
         },
         {
-            description: 'Import research synthesized from multiple source URLs',
+            description: 'import research synthesized from multiple source URLs',
             command: 'echo "# Synthesized" | <%= config.bin %> import --stdin --topic "React docs" --source-url https://react.dev/a --source-url https://react.dev/b',
         },
         {
-            description: 'Import research from a local Markdown file',
+            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 -',
+        },
     ];
     static args = {
         url: Args.string({
@@ -38,46 +42,46 @@ export default class ResearchImport extends BaseCommand {
             // this, the Markdown piped for `--stdin` is swallowed into `url`, making multi-source import
             // (`import --stdin --source-url ...`) wrongly look like it also got a positional URL.
             ignoreStdin: true,
-            description: 'The single source URL of the page (only for single-source import).',
+            description: 'the single source URL of the page (only for single-source import)',
         }),
     };
     static flags = {
         stdin: Flags.boolean({
-            description: 'Read Markdown from stdin.',
+            description: 'read Markdown from stdin',
             default: false,
         }),
         file: Flags.string({
-            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',
         }),
         'input-format': Flags.option({
-            description: 'Format of the input provided.',
+            description: 'format of the input provided',
             options: ['compressed', 'detailed'],
             default: 'detailed',
         })(),
         topic: Flags.string({
             char: 't',
-            description: 'The main topic for this research note.',
+            description: 'the main topic for this research note',
         }),
         tags: Flags.string({
             char: 'g',
-            description: 'Taxonomic tags (can be repeated).',
+            description: 'taxonomic tags (can be repeated)',
             multiple: true,
         }),
         tier: Flags.option({
-            description: 'Freshness tier policy.',
+            description: 'freshness tier policy',
             options: ['stable', 'standard', 'volatile'],
             default: 'standard',
         })(),
         'source-url': Flags.string({
-            description: 'Repeated source URLs for multi-source import.',
+            description: 'repeated source URLs for multi-source import',
             multiple: true,
         }),
         ttl: Flags.string({
             char: 'l',
-            description: 'Predicted lifespan of the data (e.g. "24h", "7d").',
+            description: 'predicted lifespan of the data (e.g. "24h", "7d")',
         }),
         storage: Flags.option({
-            description: 'Override where this note is cached (overrides configured default). Secret-bearing notes are always stored globally.',
+            description: 'override where this note is cached (secrets always stored globally)',
             options: ['global', 'project'],
         })(),
     };
@@ -121,28 +125,40 @@ export default class ResearchImport extends BaseCommand {
                 return normalizeUrl(u);
             }
             catch (err) {
-                this.error(`Invalid URL: ${err.message}`, { exit: 2 });
+                // Shared exit point: a forgotten scheme reports MISSING_URL_SCHEME like every other command,
+                // while genuinely malformed input stays INVALID_URL.
+                this.failInvalidUrl(u, err.message);
             }
         });
         return hasMulti ? normalized.sort() : normalized;
     }
     validateSourceMode(hasSingle, hasMulti, multiUrls) {
         if (hasSingle && hasMulti) {
-            this.error('Cannot specify both positional <url> and --source-url flags.', { exit: 2 });
+            this.error('Cannot specify both positional <url> and --source-url flags.', {
+                exit: 2,
+                code: 'CONFLICTING_FLAGS',
+            });
         }
         if (!hasSingle && !hasMulti) {
-            this.error('Must specify either positional <url> (for single-source) or --source-url (for multi-source) import.', { exit: 2 });
+            this.error('Must specify either positional <url> (for single-source) or --source-url (for multi-source) import.', { exit: 2, code: 'MISSING_URL' });
         }
         if (hasMulti && !this.flags.topic) {
-            this.error('Multi-source import requires the --topic flag.', { exit: 2 });
+            this.error('Multi-source import requires the --topic flag.', {
+                exit: 2,
+                code: 'MISSING_TOPIC',
+            });
         }
         if (!this.flags.stdin && !this.flags.file) {
             this.error('Either --stdin or --file <path> must be specified to import content.', {
                 exit: 2,
+                code: 'MISSING_INPUT',
             });
         }
         if (this.flags.stdin && this.flags.file) {
-            this.error('Cannot specify both --stdin and --file <path>. Choose one.', { exit: 2 });
+            this.error('Cannot specify both --stdin and --file <path>. Choose one.', {
+                exit: 2,
+                code: 'CONFLICTING_FLAGS',
+            });
         }
     }
     fsExistsSync(filePath) {
@@ -154,51 +170,70 @@ export default class ResearchImport extends BaseCommand {
     fsReadFileSync(filePath) {
         return fs.readFileSync(filePath, 'utf8');
     }
+    stdinImportSuggestions() {
+        const bin = this.config.bin;
+        return [
+            `Pipe Markdown content, e.g. cat notes.md | ${bin} import <url> --stdin`,
+            `Or use the standard stdin placeholder: cat notes.md | ${bin} import <url> --file -`,
+            `Or read from a file: ${bin} import <url> --file notes.md`,
+        ];
+    }
+    /** Non-interactive stdin that never receives data (open pipe with no writer) must not hang forever. */
+    async readStdinWithGuard(limitBytes = 1024 * 1024) {
+        if (this.stdinIsInteractive()) {
+            this.error('No data piped to --stdin.', {
+                exit: 2,
+                code: 'MISSING_STDIN',
+                suggestions: this.stdinImportSuggestions(),
+            });
+        }
+        const timeoutMs = 1000;
+        let rawInput = '';
+        try {
+            rawInput = await Promise.race([
+                this.readStdin(limitBytes),
+                new Promise((_, reject) => setTimeout(() => reject(new Error('STDIN_TIMEOUT')), timeoutMs)),
+            ]);
+        }
+        catch (err) {
+            if (err.message === 'STDIN_TIMEOUT') {
+                this.error('No stdin data received. Pipe content or use --file.', {
+                    exit: 2,
+                    code: 'MISSING_STDIN',
+                    suggestions: this.stdinImportSuggestions(),
+                });
+            }
+            if (err.message.includes('stdin size limit exceeded')) {
+                this.error(err.message, { exit: 1, code: 'STDIN_TOO_LARGE' });
+            }
+            // Genuine stream failure reading stdin → I/O failure (exit 1).
+            this.error(err.message, { exit: 1, code: 'IO_ERROR' });
+        }
+        return rawInput;
+    }
     readAndValidateFile(filePath) {
         if (!this.fsExistsSync(filePath)) {
-            this.error(`File does not exist: ${filePath}`, { exit: 2 });
+            this.error(`File does not exist: ${filePath}`, { exit: 2, code: 'FILE_NOT_FOUND' });
         }
         const stat = this.fsStatSync(filePath);
         if (!stat.isFile()) {
-            this.error(`Path is not a file: ${filePath}`, { exit: 2 });
+            this.error(`Path is not a file: ${filePath}`, { exit: 2, code: 'NOT_A_FILE' });
         }
         if (stat.size > 1024 * 1024) {
-            this.error('File size limit exceeded (max 1 MiB).', { exit: 1 });
+            this.error('File size limit exceeded (max 1 MiB).', { exit: 1, code: 'FILE_TOO_LARGE' });
         }
         const content = this.fsReadFileSync(filePath);
         if (!content.trim()) {
-            this.error('Empty file content provided.', { exit: 2 });
+            this.error('Empty file content provided.', { exit: 2, code: 'EMPTY_INPUT' });
         }
         return content;
     }
     async readAndValidateInput() {
-        if (this.flags.stdin) {
-            // On an interactive terminal with nothing piped, reading stdin blocks forever waiting for EOF —
-            // a silent hang with no feedback. Fail fast with a usage error instead; piped/redirected input
-            // (the agent and CI path) has isTTY falsy and reads normally.
-            if (this.stdinIsInteractive()) {
-                this.error('No data piped to --stdin.', {
-                    exit: 2,
-                    suggestions: [
-                        'Pipe Markdown content, e.g. cat notes.md | bonsai import <url> --stdin',
-                        'Or read from a file: bonsai import <url> --file notes.md',
-                    ],
-                });
-            }
-            // Initialized so the post-catch read below never depends on this.error()'s `never` return type
-            // for definite assignment; the empty-content guard rejects '' as a usage error anyway.
-            let rawInput = '';
-            try {
-                rawInput = await this.readStdin();
-            }
-            catch (err) {
-                // Genuine stream/size failure reading stdin → I/O failure (exit 1).
-                this.error(err.message, { exit: 1 });
-            }
-            // Empty input is a usage error (exit 2), not an I/O failure — keep it out of the
-            // catch above so its exit code is not clobbered to 1.
+        const fileReadsStdin = this.flags.file === '-';
+        if (this.flags.stdin || fileReadsStdin) {
+            const rawInput = await this.readStdinWithGuard();
             if (!rawInput.trim()) {
-                this.error('Empty stdin content provided.', { exit: 2 });
+                this.error('Empty stdin content provided.', { exit: 2, code: 'EMPTY_INPUT' });
             }
             return rawInput;
         }
@@ -213,10 +248,10 @@ export default class ResearchImport extends BaseCommand {
                 // Only an unexpected read failure becomes a wrapped I/O failure (exit 1).
                 if (err instanceof Errors.CLIError)
                     throw err;
-                this.error(`Failed to read file: ${err.message}`, { exit: 1 });
+                this.error(`Failed to read file: ${err.message}`, { exit: 1, code: 'IO_ERROR' });
             }
         }
-        this.error('No input source specified.', { exit: 2 });
+        this.error('No input source specified.', { exit: 2, code: 'MISSING_INPUT' });
     }
     deriveImportCacheKey(hasSingle, singleNormalizedUrl, sourceUrls) {
         if (hasSingle) {
@@ -292,6 +327,9 @@ export default class ResearchImport extends BaseCommand {
         const hasSingle = Boolean(this.args.url);
         const multiUrls = this.flags['source-url'] || [];
         const hasMulti = multiUrls.length > 0;
+        const ttlErr = durationFlagError('--ttl', this.flags.ttl);
+        if (ttlErr)
+            this.error(ttlErr, { exit: 2, code: 'INVALID_DURATION' });
         this.validateSourceMode(hasSingle, hasMulti, multiUrls);
         const rawInput = await this.readAndValidateInput();
         const sourceUrls = this.getSourceUrls(hasMulti, multiUrls, this.args.url);
@@ -311,8 +349,8 @@ export default class ResearchImport extends BaseCommand {
         }
         if (!this.jsonEnabled()) {
             this.log(`Successfully imported research artifact.`);
-            this.log(`Cache Key: ${cacheKey}`);
-            this.log(`Storage Path: ${storagePath}`);
+            this.log(`${'Cache Key:'.padEnd(25)} ${cacheKey}`);
+            this.log(`${'Storage Path:'.padEnd(25)} ${storagePath}`);
         }
         const inputFormat = this.flags['input-format'];
         return {

package/dist/commands/inspect.d.ts

@@ -3,10 +3,18 @@ export default class ResearchInspect extends BaseCommand<typeof ResearchInspect>
     static id: string;
     static summary: string;
     static description: string;
+    static examples: {
+        description: string;
+        command: string;
+    }[];
+    static strict: boolean;
     static args: {
         url: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
     };
     static stdoutIsPrimaryData: boolean;
     run(): Promise<unknown>;
+    private logMetadata;
+    private logSections;
+    private inspectSingleTarget;
     private findSections;
 }

package/dist/commands/inspect.js

@@ -1,56 +1,85 @@
 import { Args } from '@oclif/core';
 import { BaseCommand } from '../base-command.js';
 import { scanCacheDirs } from '../lib/research/storage.js';
-import { resolveResearchTarget } from '../lib/research/resolve-target.js';
+import { colors } from '../lib/color.js';
 export default class ResearchInspect extends BaseCommand {
     static id = 'inspect';
     static summary = 'Inspect cached research metadata for a URL.';
     static description = 'Inspects local storage and displays full frontmatter metadata for the URL (without printing the content body).';
+    static examples = [
+        {
+            description: 'inspect cached research metadata for a specific URL',
+            command: '<%= config.bin %> <%= command.id %> https://example.com/docs',
+        },
+        {
+            description: 'output the full metadata as JSON for use by other tools',
+            command: '<%= config.bin %> <%= command.id %> https://example.com/docs --json',
+        },
+    ];
+    static strict = false;
     static args = {
         url: Args.string({
             required: true,
-            description: 'The URL to inspect.',
+            description: 'the URL to inspect',
         }),
     };
     static stdoutIsPrimaryData = true;
     async run() {
-        const { url } = this.args;
-        let target;
-        try {
-            target = resolveResearchTarget({
-                configDir: this.config.configDir,
-                cwd: process.cwd(),
-                dataDir: this.config.dataDir,
-                url,
+        const urls = this.parsedArgv;
+        const results = [];
+        const missingUrls = [];
+        for (const url of urls) {
+            const target = this.resolveResearchTargetOrFail(url);
+            if (!target.located) {
+                missingUrls.push(target.normalizedUrl);
+                continue;
+            }
+            results.push(this.inspectSingleTarget(target, urls.length > 1));
+        }
+        if (missingUrls.length > 0) {
+            const firstMissing = missingUrls[0];
+            const suggestions = missingUrls.map((u) => `Fetch and cache it first: ${this.config.bin} ${u}`);
+            this.error(`No cached research found for URL: ${firstMissing}` +
+                (missingUrls.length > 1 ? ` and ${missingUrls.length - 1} other URLs` : ''), {
+                exit: 1,
+                code: 'CACHE_MISS',
+                suggestions,
             });
         }
-        catch (err) {
-            this.error(`Invalid URL: ${err.message}`, { exit: 2 });
+        return urls.length === 1 ? results[0] : results;
+    }
+    logMetadata(metadata) {
+        this.log(colors.cyan(`--- Metadata ---`));
+        for (const [key, val] of Object.entries(metadata)) {
+            const paddedKey = colors.cyan((key + ':').padEnd(Math.max(25, key.length + 2)));
+            if (typeof val === 'object' && val !== null) {
+                this.log(`${paddedKey} ${colors.bold(JSON.stringify(val))}`);
+            }
+            else {
+                this.log(`${paddedKey} ${colors.bold(String(val))}`);
+            }
         }
-        const { cacheKey, located, normalizedUrl, roots } = target;
-        if (!located) {
-            this.error(`No cached research found for URL: ${normalizedUrl}`, { exit: 1 });
+    }
+    logSections(sections) {
+        this.log(colors.cyan(`--- Sections (${sections.length}) ---`));
+        for (const s of sections) {
+            this.log(`${colors.cyan(s.headingPath || '')} [${colors.yellow(s.anchor || '')}] (${colors.magenta(String(s.tokenEstimate.detailed || 0))} tokens) ${colors.gray(s.cacheKey)}`);
         }
+    }
+    inspectSingleTarget(target, showSeparator) {
+        const { cacheKey, located, roots } = target;
         const cached = located.artifact;
         const artifactPath = located.path;
         const sections = this.findSections(roots.readRoots, cacheKey);
         if (!this.jsonEnabled()) {
-            this.log(`Cache Key: ${cacheKey}`);
-            this.log(`Cache Path: ${artifactPath}`);
-            this.log(`--- Metadata ---`);
-            for (const [key, val] of Object.entries(cached.metadata)) {
-                if (typeof val === 'object' && val !== null) {
-                    this.log(`${key}: ${JSON.stringify(val)}`);
-                }
-                else {
-                    this.log(`${key}: ${val}`);
-                }
-            }
+            this.log(`${colors.cyan('Cache Key:'.padEnd(25))} ${colors.bold(cacheKey)}`);
+            this.log(`${colors.cyan('Cache Path:'.padEnd(25))} ${colors.gray(artifactPath)}`);
+            this.logMetadata(cached.metadata);
             if (sections.length) {
-                this.log(`--- Sections (${sections.length}) ---`);
-                for (const s of sections) {
-                    this.log(`${s.headingPath} [${s.anchor}] (${s.tokenEstimate.detailed} tokens) ${s.cacheKey}`);
-                }
+                this.logSections(sections);
+            }
+            if (showSeparator) {
+                this.log('='.repeat(40));
             }
         }
         return {