@taurgis/bonsai 1.0.4 → 1.0.6

package/dist/commands/fetch.js

@@ -1,4 +1,4 @@
-import { Args, Flags } from '@oclif/core';
+import { Args, Flags, ux } from '@oclif/core';
 import { mkdtempSync, rmSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
@@ -6,13 +6,12 @@ import { BaseCommand } from '../base-command.js';
 import { writeArtifact, getArtifactPath } from '../lib/research/storage.js';
 import { writeArtifactSecurely } from '../lib/research/secure-write.js';
 import { loadSummaryLevel } from '../lib/config/index.js';
-import { evaluateFreshness, parseTtlToMs, checkMaxAgeExpired } from '../lib/research/freshness.js';
+import { evaluateFreshness, checkMaxAgeExpired, durationFlagError, } 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 { applyAutoTags } from '../lib/research/keywords.js';
 import { detectSite } from '../sites/index.js';
 const CAPTURE_DEPS = {
@@ -24,69 +23,69 @@ export default class FetchCommand extends BaseCommand {
     static id = 'fetch';
     static hidden = true;
     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 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 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 of the data (e.g., "2h", "7d", "3m").',
+            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'],
         })(),
     };
@@ -183,20 +182,27 @@ export default class FetchCommand extends BaseCommand {
     }
     // 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 });
-            }
+        for (const msg of [durationFlagError('--ttl', ttl), durationFlagError('--max-age', maxAge)]) {
+            if (msg)
+                this.error(msg, { exit: 2, code: 'INVALID_DURATION' });
         }
     }
+    // Re-emit a runtime fetch failure with actionable next steps. Deep fetch/extract code throws plain
+    // Errors that otherwise reach the user as a bare "what broke" line with no "what to do"; this
+    // attaches recovery hints (e.g. import an auth-blocked page). Everything reaching here is a runtime
+    // failure — validation errors (bad flags/URL) exit before the try — so the contract's runtime code
+    // (1) applies. Suggestions render on stderr for humans only; under --json the envelope carries just
+    // the message (toErrorJson), so machine output is unchanged.
+    emitFetchError(err, url) {
+        const message = err instanceof Error ? err.message : String(err);
+        const guidance = fetchFailureGuidance(message, url);
+        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.
     async resolveArtifact(normalizedUrl, cacheKey, roots, tmpDir, currentTime, located, summaryLevel) {
@@ -210,9 +216,12 @@ export default class FetchCommand extends BaseCommand {
         }
         const artifact = await this.executeCacheMiss(normalizedUrl, currentTime, cacheKey, summaryLevel);
         const { dir, redirectedToGlobal } = this.persistFreshArtifact(roots, tmpDir, cacheKey, artifact);
+        // No entry existed at lookup, so there is no prior freshness to report. 'none' (not
+        // 'stale_expired') keeps the field honest — nothing expired; the page was simply uncached and
+        // has now been fetched fresh. Mirrors the `status` command's miss reporting.
         return {
             cacheStatus: 'miss',
-            freshnessState: 'stale_expired',
+            freshnessState: 'none',
             artifact,
             storageDir: dir,
             redirectedToGlobal,
@@ -249,27 +258,30 @@ export default class FetchCommand extends BaseCommand {
         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 target = this.resolveResearchTargetOrFail(url, {
+            flagOverride: this.flags.storage,
+            lookup: !this.flags.force,
+        });
         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();
         try {
+            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()) {
@@ -277,6 +289,16 @@ export default class FetchCommand extends BaseCommand {
             }
             return resultData;
         }
+        catch (err) {
+            if (!this.jsonEnabled()) {
+                ux.action.stop('failed');
+            }
+            // 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);
+        }
         finally {
             if (tmpDir) {
                 rmSync(tmpDir, { recursive: true, force: true });
@@ -284,6 +306,59 @@ export default class FetchCommand extends BaseCommand {
         }
     }
 }
+// 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';
+    // 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`;
+    // 401/403: an auth wall or anti-scraping WAF. Bonsai has no authenticated-fetch path in v1.
+    if (/failed with status 40[13]\b/.test(message)) {
+        return {
+            suggestions: ['The page requires authentication or blocks automated requests.', importHint],
+            ref,
+        };
+    }
+    if (/failed with status 404\b/.test(message)) {
+        return { suggestions: ['Check the URL is correct and the page still exists.'] };
+    }
+    if (/failed with status 5\d\d\b/.test(message)) {
+        return {
+            suggestions: ['The server returned an error. Retry later or verify the host is healthy.'],
+        };
+    }
+    // Server returned a non-HTML body (JSON, binary, or no Content-Type at all). Scope the opener to
+    // the real failure: --rendered does produce HTML, so "only scrapes HTML" would read as misleading.
+    if (/Rejected content type|does not look like HTML/.test(message)) {
+        return {
+            suggestions: [
+                'The server returned a non-HTML response (e.g. JSON or binary).',
+                'If the page is rendered by client-side JavaScript, retry with --rendered.',
+                importHint,
+            ],
+            ref,
+        };
+    }
+    if (/DNS resolution failed/.test(message)) {
+        return {
+            suggestions: ['Check the hostname is spelled correctly and resolves on a public network.'],
+        };
+    }
+    // A hostname that only resolves to a private/local IP at request time (literal private addresses
+    // are rejected earlier with exit 2). Blocked to prevent SSRF; only public hosts can be fetched.
+    if (/blocked local or private target/.test(message)) {
+        return {
+            suggestions: [
+                'The hostname resolves to a private or local address, which is blocked to prevent SSRF. Only public http(s) hosts can be fetched.',
+            ],
+            ref,
+        };
+    }
+    return undefined;
+}
 // Copies Phase 2 capability provenance from a capture outcome onto the artifact metadata.
 function applyCaptureMetadata(artifact, capture) {
     const meta = artifact.metadata;
@@ -302,10 +377,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

@@ -23,12 +23,16 @@ export default class ResearchImport extends BaseCommand<typeof ResearchImport> {
         storage: import("@oclif/core/interfaces").OptionFlag<"global" | "project" | undefined, import("@oclif/core/interfaces").CustomOptions>;
     };
     static stdoutIsPrimaryData: boolean;
+    protected stdinIsInteractive(): boolean;
     private readStdin;
     private getSourceUrls;
     private validateSourceMode;
     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

@@ -1,4 +1,4 @@
-import { Args, Flags } from '@oclif/core';
+import { Args, Errors, Flags } from '@oclif/core';
 import { createHash } from 'node:crypto';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
@@ -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,65 +19,74 @@ 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',
         },
     ];
     static args = {
         url: Args.string({
             required: false,
-            description: 'The single source URL of the page (only for single-source import).',
+            // oclif fills an omitted optional arg from piped stdin unless ignoreStdin is set. Without
+            // 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)',
         }),
     };
     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',
         }),
         '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'],
         })(),
     };
     static stdoutIsPrimaryData = true;
+    // Isolated so tests can force the interactive branch; `isTTY` is `true` only on a real terminal and
+    // falsy (undefined) for pipes, files, and /dev/null. See https://nodejs.org/api/process.html#processstdin
+    stdinIsInteractive() {
+        return process.stdin.isTTY === true;
+    }
     async readStdin(limitBytes = 1024 * 1024) {
         return new Promise((resolve, reject) => {
             let data = '';
@@ -112,28 +121,38 @@ export default class ResearchImport extends BaseCommand {
                 return normalizeUrl(u);
             }
             catch (err) {
-                this.error(`Invalid URL: ${err.message}`, { exit: 2 });
+                this.error(`Invalid URL: ${err.message}`, { exit: 2, code: 'INVALID_URL' });
             }
         });
         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) {
@@ -145,35 +164,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 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) {
-            try {
-                const rawInput = await this.readStdin();
-                if (!rawInput.trim()) {
-                    this.error('Empty stdin content provided.', { exit: 2 });
-                }
-                return rawInput;
-            }
-            catch (err) {
-                this.error(err.message, { exit: 1 });
+            const rawInput = await this.readStdinWithGuard();
+            if (!rawInput.trim()) {
+                this.error('Empty stdin content provided.', { exit: 2, code: 'EMPTY_INPUT' });
             }
+            return rawInput;
         }
         if (this.flags.file) {
             const filePath = path.resolve(this.flags.file);
@@ -181,10 +235,15 @@ export default class ResearchImport extends BaseCommand {
                 return this.readAndValidateFile(filePath);
             }
             catch (err) {
-                this.error(`Failed to read file: ${err.message}`, { exit: 1 });
+                // readAndValidateFile raises usage errors (missing/not-a-file/empty) via this.error,
+                // which throw CLIErrors carrying their own exit code and message — preserve those.
+                // 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, 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) {
@@ -260,6 +319,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);
@@ -279,8 +341,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,6 +3,10 @@ export default class ResearchInspect extends BaseCommand<typeof ResearchInspect>
     static id: string;
     static summary: string;
     static description: string;
+    static examples: {
+        description: string;
+        command: string;
+    }[];
     static args: {
         url: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
     };