@taurgis/bonsai 1.0.0

package/dist/commands/fetch.js

@@ -0,0 +1,311 @@
+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 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 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;
+    envelopeCommandId() {
+        return this.config.bin;
+    }
+    async init() {
+        await super.init();
+        const { args, flags } = await this.parse(FetchCommand);
+        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/import.d.ts

@@ -0,0 +1,38 @@
+import * as fs from 'node:fs';
+import { BaseCommand } from '../base-command.js';
+export default class ResearchImport extends BaseCommand<typeof ResearchImport> {
+    static id: string;
+    static summary: string;
+    static description: string;
+    static examples: {
+        description: string;
+        command: string;
+    }[];
+    static args: {
+        url: import("@oclif/core/interfaces").Arg<string | undefined, Record<string, unknown>>;
+    };
+    static flags: {
+        stdin: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        file: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'input-format': import("@oclif/core/interfaces").OptionFlag<"compressed" | "detailed", import("@oclif/core/interfaces").CustomOptions>;
+        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>;
+        tier: import("@oclif/core/interfaces").OptionFlag<"stable" | "standard" | "volatile", import("@oclif/core/interfaces").CustomOptions>;
+        'source-url': import("@oclif/core/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        ttl: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        storage: import("@oclif/core/interfaces").OptionFlag<"global" | "project" | undefined, import("@oclif/core/interfaces").CustomOptions>;
+    };
+    static stdoutIsPrimaryData: boolean;
+    init(): Promise<void>;
+    private readStdin;
+    private getSourceUrls;
+    private validateSourceMode;
+    protected fsExistsSync(filePath: string): boolean;
+    protected fsStatSync(filePath: string): fs.Stats;
+    protected fsReadFileSync(filePath: string): string;
+    private readAndValidateFile;
+    private readAndValidateInput;
+    private deriveImportCacheKey;
+    private buildImportArtifact;
+    execute(): Promise<unknown>;
+}

package/dist/commands/import.js

@@ -0,0 +1,313 @@
+import { Args, Flags } from '@oclif/core';
+import { createHash } from 'node:crypto';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { BaseCommand } from '../base-command.js';
+import { normalizeUrl } from '../lib/research/url.js';
+import { deriveCacheKey } from '../lib/research/cache-key.js';
+import { getArtifactPath } from '../lib/research/storage.js';
+import { loadStoreRoots } from '../lib/research/store-roots.js';
+import { writeArtifactSecurely } from '../lib/research/secure-write.js';
+import { getPolicy } from '../lib/research/freshness.js';
+import { compressMarkdown } from '../lib/research/compress.js';
+import { estimateTokens } from '../lib/research/token-estimate.js';
+export default class ResearchImport extends BaseCommand {
+    static id = 'import';
+    static summary = 'Import agent-supplied clean Markdown notes into the local cache.';
+    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',
+            command: 'echo "# My Article" | <%= config.bin %> import https://example.com/docs --stdin',
+        },
+        {
+            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',
+            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).',
+        }),
+    };
+    static flags = {
+        stdin: Flags.boolean({
+            description: 'Read Markdown from stdin.',
+            default: false,
+        }),
+        file: Flags.string({
+            description: 'Path to a Markdown file containing research notes to import.',
+        }),
+        'input-format': Flags.option({
+            description: 'Format of the input provided.',
+            options: ['compressed', 'detailed'],
+            default: 'detailed',
+        })(),
+        topic: Flags.string({
+            char: 't',
+            description: 'The main topic for this research note.',
+        }),
+        tags: Flags.string({
+            char: 'g',
+            description: 'Taxonomic tags (can be repeated).',
+            multiple: true,
+        }),
+        tier: Flags.option({
+            description: 'Freshness tier policy.',
+            options: ['stable', 'standard', 'volatile'],
+            default: 'standard',
+        })(),
+        'source-url': Flags.string({
+            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").',
+        }),
+        storage: Flags.option({
+            description: 'Override where this note is cached (overrides configured default). Secret-bearing notes are always stored globally.',
+            options: ['global', 'project'],
+        })(),
+    };
+    static stdoutIsPrimaryData = true;
+    async init() {
+        await super.init();
+        const { args, flags } = await this.parse(ResearchImport);
+        this.args = args;
+        this.flags = flags;
+    }
+    async readStdin(limitBytes = 1024 * 1024) {
+        return new Promise((resolve, reject) => {
+            let data = '';
+            let bytesRead = 0;
+            process.stdin.setEncoding('utf8');
+            const onData = (chunk) => {
+                bytesRead += Buffer.byteLength(chunk, 'utf8');
+                if (bytesRead > limitBytes) {
+                    process.stdin.removeListener('data', onData);
+                    reject(new Error('stdin size limit exceeded (max 1 MiB)'));
+                    return;
+                }
+                data += chunk;
+            };
+            process.stdin.on('data', onData);
+            const onEnd = () => {
+                process.stdin.removeListener('data', onData);
+                resolve(data);
+            };
+            process.stdin.once('end', onEnd);
+            process.stdin.once('error', (err) => {
+                process.stdin.removeListener('data', onData);
+                process.stdin.removeListener('end', onEnd);
+                reject(err);
+            });
+        });
+    }
+    getSourceUrls(hasMulti, multiUrls, singleUrl) {
+        const urls = hasMulti ? multiUrls : singleUrl ? [singleUrl] : [];
+        const normalized = urls.map((u) => {
+            try {
+                return normalizeUrl(u);
+            }
+            catch (err) {
+                this.error(`Invalid URL: ${err.message}`, { exit: 2 });
+            }
+        });
+        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 });
+        }
+        if (!hasSingle && !hasMulti) {
+            this.error('Must specify either positional <url> (for single-source) or --source-url (for multi-source) import.', { exit: 2 });
+        }
+        if (hasMulti && !this.flags.topic) {
+            this.error('Multi-source import requires the --topic flag.', { exit: 2 });
+        }
+        if (!this.flags.stdin && !this.flags.file) {
+            this.error('Either --stdin or --file <path> must be specified to import content.', {
+                exit: 2,
+            });
+        }
+        if (this.flags.stdin && this.flags.file) {
+            this.error('Cannot specify both --stdin and --file <path>. Choose one.', { exit: 2 });
+        }
+    }
+    fsExistsSync(filePath) {
+        return fs.existsSync(filePath);
+    }
+    fsStatSync(filePath) {
+        return fs.statSync(filePath);
+    }
+    fsReadFileSync(filePath) {
+        return fs.readFileSync(filePath, 'utf8');
+    }
+    readAndValidateFile(filePath) {
+        if (!this.fsExistsSync(filePath)) {
+            this.error(`File does not exist: ${filePath}`, { exit: 2 });
+        }
+        const stat = this.fsStatSync(filePath);
+        if (!stat.isFile()) {
+            this.error(`Path is not a file: ${filePath}`, { exit: 2 });
+        }
+        if (stat.size > 1024 * 1024) {
+            this.error('File size limit exceeded (max 1 MiB).', { exit: 1 });
+        }
+        const content = this.fsReadFileSync(filePath);
+        if (!content.trim()) {
+            this.error('Empty file content provided.', { exit: 2 });
+        }
+        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 });
+            }
+        }
+        if (this.flags.file) {
+            const filePath = path.resolve(this.flags.file);
+            try {
+                return this.readAndValidateFile(filePath);
+            }
+            catch (err) {
+                this.error(`Failed to read file: ${err.message}`, { exit: 1 });
+            }
+        }
+        this.error('No input source specified.', { exit: 2 });
+    }
+    deriveImportCacheKey(hasSingle, singleNormalizedUrl, sourceUrls) {
+        if (hasSingle) {
+            return deriveCacheKey(singleNormalizedUrl);
+        }
+        const normalizedTopic = this.flags.topic.trim().toLowerCase();
+        const combinedString = [normalizedTopic, ...sourceUrls].join('|');
+        return createHash('sha256').update(combinedString).digest('hex');
+    }
+    buildImportArtifact(hasSingle, singleNormalizedUrl, sourceUrls, cacheKey, rawInput) {
+        const currentTime = new Date();
+        const tier = this.flags.tier;
+        const ttl = this.flags.ttl || null;
+        const { freshWindowMs } = getPolicy(tier, ttl);
+        const staleAfterTime = new Date(currentTime.getTime() + freshWindowMs);
+        const inputFormat = this.flags['input-format'];
+        const detailed = rawInput;
+        const compressed = inputFormat === 'detailed' ? compressMarkdown(rawInput) : rawInput;
+        const contentHash = createHash('sha256').update(detailed).digest('hex');
+        const metadata = {
+            schema_version: 1,
+            artifact_type: hasSingle ? 'source' : 'research_note',
+            source_url: hasSingle ? this.args.url : '',
+            source_urls: sourceUrls,
+            normalized_url: singleNormalizedUrl,
+            cache_key: cacheKey,
+            topic: this.flags.topic || null,
+            tags: this.flags.tags || [],
+            format_available: ['compressed', 'detailed'],
+            tier,
+            ttl,
+            fetched_at: null,
+            validated_at: currentTime.toISOString(),
+            stale_after: staleAfterTime.toISOString(),
+            capture_method: 'agent_supplied',
+            extraction_status: 'agent_supplied',
+            extraction_confidence: 'high',
+            quality_notes: ['agent-supplied research import'],
+            supplied_at: currentTime.toISOString(),
+            supplied_by: null,
+            etag: null,
+            last_modified: null,
+            content_hash: contentHash,
+            token_estimate: {
+                compressed: estimateTokens(compressed),
+                detailed: estimateTokens(detailed),
+            },
+            status: 'active',
+            site_module_id: null,
+            docs_engine: null,
+            docs_framework: null,
+            source_doc_url: null,
+            search_provider: null,
+            parent_cache_key: null,
+            section_anchor: null,
+            section_heading_path: null,
+        };
+        return {
+            metadata,
+            summary: `Synthesized research for ${hasSingle ? singleNormalizedUrl : this.flags.topic}`,
+            compressed,
+            detailed,
+            provenance: `Imported via agent-supplied research at ${currentTime.toISOString()}`,
+        };
+    }
+    async execute() {
+        const hasSingle = Boolean(this.args.url);
+        const multiUrls = this.flags['source-url'] || [];
+        const hasMulti = multiUrls.length > 0;
+        this.validateSourceMode(hasSingle, hasMulti, multiUrls);
+        const rawInput = await this.readAndValidateInput();
+        const sourceUrls = this.getSourceUrls(hasMulti, multiUrls, this.args.url);
+        const singleNormalizedUrl = hasSingle ? sourceUrls[0] || '' : '';
+        const cacheKey = this.deriveImportCacheKey(hasSingle, singleNormalizedUrl, sourceUrls);
+        const artifact = this.buildImportArtifact(hasSingle, singleNormalizedUrl, sourceUrls, cacheKey, rawInput);
+        const roots = loadStoreRoots({
+            configDir: this.config.configDir,
+            cwd: process.cwd(),
+            dataDir: this.config.dataDir,
+            flagOverride: this.flags.storage,
+        });
+        const writeResult = writeArtifactSecurely(roots, cacheKey, artifact);
+        const storagePath = getArtifactPath(writeResult.dataDir, cacheKey);
+        if (writeResult.redirected) {
+            this.warn(`Detected ${writeResult.secretLabel} in the imported content; stored in the global cache instead of the project to avoid committing secrets.`);
+        }
+        if (!this.requestedJson()) {
+            this.log(`Successfully imported research artifact.`);
+            this.log(`Cache Key: ${cacheKey}`);
+            this.log(`Storage Path: ${storagePath}`);
+        }
+        const inputFormat = this.flags['input-format'];
+        return {
+            schemaVersion: 1,
+            command: 'import',
+            cache: {
+                key: cacheKey,
+                status: 'imported',
+                freshness: 'fresh',
+                path: storagePath,
+                storage: roots.mode,
+                redirectedToGlobal: writeResult.redirected,
+            },
+            source: {
+                url: hasSingle ? this.args.url : '',
+                normalizedUrl: singleNormalizedUrl,
+                captureMethod: 'agent_supplied',
+                extractionStatus: 'agent_supplied',
+                extractionConfidence: 'high',
+                qualityNotes: ['agent-supplied research import'],
+                fetchedAt: null,
+                validatedAt: artifact.metadata.validated_at,
+                staleAfter: artifact.metadata.stale_after,
+            },
+            format: inputFormat,
+            tokenEstimate: inputFormat === 'compressed'
+                ? artifact.metadata.token_estimate.compressed
+                : artifact.metadata.token_estimate.detailed,
+            content: inputFormat === 'compressed' ? artifact.compressed : artifact.detailed,
+        };
+    }
+}