@taurgis/bonsai 1.0.5 → 3.0.0

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

@@ -1,31 +0,0 @@
-import { ConfigCommand } from './base.js';
-export default class ResearchConfigSet extends ConfigCommand<typeof ResearchConfigSet> {
-    static id: string;
-    static summary: string;
-    static description: string;
-    static examples: {
-        description: string;
-        command: string;
-    }[];
-    static args: {
-        key: import("@oclif/core/interfaces").Arg<string | undefined, Record<string, unknown>>;
-        value: import("@oclif/core/interfaces").Arg<string | undefined, Record<string, unknown>>;
-    };
-    static flags: {
-        'dry-run': import("@oclif/core/interfaces").BooleanFlag<boolean>;
-        global: import("@oclif/core/interfaces").BooleanFlag<boolean>;
-        local: import("@oclif/core/interfaces").BooleanFlag<boolean>;
-    };
-    static stdoutIsPrimaryData: boolean;
-    init(): Promise<void>;
-    execute(): Promise<unknown>;
-}
-/**
- * Accept the `key=value` convenience form alongside the canonical `key value`.
- * Splits only when no separate value positional was supplied, and on the FIRST `=`
- * so a value may itself contain `=`.
- */
-export declare function splitInlineKeyValue(rawKey: string | undefined, rawValue: string | undefined): {
-    keyArg: string | undefined;
-    valueArg: string | undefined;
-};

package/dist/commands/research/config/set.js

@@ -1,94 +0,0 @@
-import { Args, Flags } from '@oclif/core';
-import { ConfigCommand, configScopeFlags } from './base.js';
-import { KEY_META, writeUserConfig, writeProjectConfig } from '../../../lib/config/index.js';
-export default class ResearchConfigSet extends ConfigCommand {
-    static id = 'research config set';
-    static summary = 'Set a research configuration key.';
-    static description = 'Persist a configuration value. Writes user-level config by default; pass --local to write the project-level config (.bonsai.json in cwd).\n\n' +
-        'Valid keys: storage. The inline form `<key>=<value>` is also accepted.';
-    static examples = [
-        {
-            description: 'Store research cache inside the current project',
-            command: '<%= config.bin %> research config set storage project --local',
-        },
-        {
-            description: 'Set the user-level default using the inline key=value form',
-            command: '<%= config.bin %> research config set storage=global',
-        },
-    ];
-    static args = {
-        key: Args.string({ required: false, description: 'The configuration key to set.' }),
-        value: Args.string({ required: false, description: 'The value to assign.' }),
-    };
-    static flags = {
-        ...configScopeFlags({
-            global: 'Write to user-level config (default).',
-            local: 'Write to project-level config (.bonsai.json in cwd).',
-        }),
-        'dry-run': Flags.boolean({
-            description: 'Show what would be written without saving.',
-            default: false,
-        }),
-    };
-    static stdoutIsPrimaryData = true;
-    async init() {
-        await super.init();
-        const { args, flags } = await this.parse(ResearchConfigSet);
-        this.args = args;
-        this.flags = flags;
-    }
-    async execute() {
-        const { keyArg, valueArg } = splitInlineKeyValue(this.args.key, this.args.value);
-        if (!keyArg) {
-            this.error('Missing required argument: key', { exit: 2 });
-        }
-        this.assertKnownKey(keyArg);
-        this.assertScopeFlagsExclusive(this.flags.global, this.flags.local);
-        const meta = KEY_META[keyArg];
-        if (valueArg === undefined) {
-            this.error(`Missing required argument: value for key "${keyArg}"`, { exit: 2 });
-        }
-        const parsed = meta.parseValue(valueArg);
-        if (!meta.isValid(parsed)) {
-            const guidance = meta.values ? `Valid values: ${meta.values.join(', ')}.` : meta.description;
-            this.error(`Invalid value "${valueArg}" for "${keyArg}". ${guidance}`, { exit: 2 });
-        }
-        const scope = this.writeScope(this.flags.local);
-        const formatted = meta.format(parsed);
-        if (this.flags['dry-run']) {
-            if (!this.requestedJson())
-                this.log(`[dry-run] Would set ${keyArg} = ${formatted} (${scope})`);
-            return { key: keyArg, value: parsed, scope, dryRun: true };
-        }
-        const patch = { [keyArg]: parsed };
-        if (scope === 'project') {
-            writeProjectConfig(process.cwd(), patch);
-        }
-        else {
-            const configDir = this.config.configDir;
-            if (!configDir) {
-                this.error('Could not determine user config directory. Use --local to write project config.', {
-                    exit: 1,
-                });
-            }
-            writeUserConfig(configDir, patch);
-        }
-        if (!this.requestedJson())
-            this.log(`Set ${keyArg} = ${formatted} (${scope})`);
-        return { key: keyArg, value: parsed, scope, dryRun: false };
-    }
-}
-/**
- * Accept the `key=value` convenience form alongside the canonical `key value`.
- * Splits only when no separate value positional was supplied, and on the FIRST `=`
- * so a value may itself contain `=`.
- */
-export function splitInlineKeyValue(rawKey, rawValue) {
-    if (rawValue === undefined && rawKey !== undefined) {
-        const eq = rawKey.indexOf('=');
-        if (eq !== -1) {
-            return { keyArg: rawKey.slice(0, eq), valueArg: rawKey.slice(eq + 1) };
-        }
-    }
-    return { keyArg: rawKey, valueArg: rawValue };
-}

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

@@ -1,21 +0,0 @@
-import { ConfigCommand } from './base.js';
-export default class ResearchConfigUnset extends ConfigCommand<typeof ResearchConfigUnset> {
-    static id: string;
-    static summary: string;
-    static description: string;
-    static examples: {
-        description: string;
-        command: string;
-    }[];
-    static args: {
-        key: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
-    };
-    static flags: {
-        'dry-run': import("@oclif/core/interfaces").BooleanFlag<boolean>;
-        global: import("@oclif/core/interfaces").BooleanFlag<boolean>;
-        local: import("@oclif/core/interfaces").BooleanFlag<boolean>;
-    };
-    static stdoutIsPrimaryData: boolean;
-    init(): Promise<void>;
-    execute(): Promise<unknown>;
-}

package/dist/commands/research/config/unset.js

@@ -1,59 +0,0 @@
-import { Args, Flags } from '@oclif/core';
-import { ConfigCommand, configScopeFlags } from './base.js';
-import { writeUserConfig, writeProjectConfig } from '../../../lib/config/index.js';
-export default class ResearchConfigUnset extends ConfigCommand {
-    static id = 'research config unset';
-    static summary = 'Remove a research configuration key.';
-    static description = 'Delete a key from user-level config (default) or project-level config (--local), restoring the built-in default.\n\nValid keys: storage.';
-    static examples = [
-        { description: 'Remove the user-level storage setting', command: '<%= config.bin %> research config unset storage' },
-        {
-            description: 'Remove the project-level storage setting',
-            command: '<%= config.bin %> research config unset storage --local',
-        },
-    ];
-    static args = {
-        key: Args.string({ required: true, description: 'The configuration key to remove.' }),
-    };
-    static flags = {
-        ...configScopeFlags({
-            global: 'Remove from user-level config (default).',
-            local: 'Remove from project-level config (.bonsai.json in cwd).',
-        }),
-        'dry-run': Flags.boolean({ description: 'Show what would be removed without saving.', default: false }),
-    };
-    static stdoutIsPrimaryData = true;
-    async init() {
-        await super.init();
-        const { args, flags } = await this.parse(ResearchConfigUnset);
-        this.args = args;
-        this.flags = flags;
-    }
-    async execute() {
-        const key = this.args.key;
-        this.assertKnownKey(key);
-        this.assertScopeFlagsExclusive(this.flags.global, this.flags.local);
-        const scope = this.writeScope(this.flags.local);
-        if (this.flags['dry-run']) {
-            if (!this.requestedJson())
-                this.log(`[dry-run] Would unset ${key} (${scope})`);
-            return { key, scope, dryRun: true };
-        }
-        const patch = { [key]: undefined };
-        if (scope === 'project') {
-            writeProjectConfig(process.cwd(), patch);
-        }
-        else {
-            const configDir = this.config.configDir;
-            if (!configDir) {
-                this.error('Could not determine user config directory. Use --local to remove project config.', {
-                    exit: 1,
-                });
-            }
-            writeUserConfig(configDir, patch);
-        }
-        if (!this.requestedJson())
-            this.log(`Unset ${key} (${scope})`);
-        return { key, scope, dryRun: false };
-    }
-}

package/dist/commands/research/import.d.ts

@@ -1,38 +0,0 @@
-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/research/import.js

@@ -1,313 +0,0 @@
-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 = 'research 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 %> research import https://example.com/docs --stdin',
-        },
-        {
-            description: 'Import research synthesized from multiple source URLs',
-            command: 'echo "# Synthesized" | <%= config.bin %> research 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 %> research 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: 'research 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,
-        };
-    }
-}

package/dist/commands/research/inspect.d.ts

@@ -1,13 +0,0 @@
-import { BaseCommand } from '../../base-command.js';
-export default class ResearchInspect extends BaseCommand<typeof ResearchInspect> {
-    static id: string;
-    static summary: string;
-    static description: string;
-    static args: {
-        url: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
-    };
-    static stdoutIsPrimaryData: boolean;
-    init(): Promise<void>;
-    execute(): Promise<unknown>;
-    private findSections;
-}

package/dist/commands/research/inspect.js

@@ -1,86 +0,0 @@
-import { Args } from '@oclif/core';
-import { BaseCommand } from '../../base-command.js';
-import { normalizeUrl } from '../../lib/research/url.js';
-import { deriveCacheKey } from '../../lib/research/cache-key.js';
-import { locateArtifact, scanCacheDirs } from '../../lib/research/storage.js';
-import { loadStoreRoots } from '../../lib/research/store-roots.js';
-export default class ResearchInspect extends BaseCommand {
-    static id = 'research 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 args = {
-        url: Args.string({
-            required: true,
-            description: 'The URL to inspect.',
-        }),
-    };
-    static stdoutIsPrimaryData = true;
-    async init() {
-        await super.init();
-        const { args } = await this.parse(ResearchInspect);
-        this.args = args;
-    }
-    async execute() {
-        const { url } = this.args;
-        let normalizedUrl;
-        let cacheKey;
-        try {
-            normalizedUrl = normalizeUrl(url);
-            cacheKey = deriveCacheKey(normalizedUrl);
-        }
-        catch (err) {
-            this.error(`Invalid URL: ${err.message}`, { exit: 2 });
-        }
-        const roots = loadStoreRoots({
-            configDir: this.config.configDir,
-            cwd: process.cwd(),
-            dataDir: this.config.dataDir,
-        });
-        const located = locateArtifact(roots.readRoots, cacheKey);
-        if (!located) {
-            this.error(`No cached research found for URL: ${normalizedUrl}`, { exit: 1 });
-        }
-        const cached = located.artifact;
-        const artifactPath = located.path;
-        const sections = this.findSections(roots.readRoots, cacheKey);
-        if (!this.requestedJson()) {
-            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}`);
-                }
-            }
-            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}`);
-                }
-            }
-        }
-        return {
-            cacheKey,
-            cachePath: artifactPath,
-            metadata: cached.metadata,
-            sections,
-        };
-    }
-    // Section children link back via parent_cache_key; list the active ones for this page (T-22).
-    findSections(readRoots, parentKey) {
-        return scanCacheDirs(readRoots, (artifact) => {
-            const meta = artifact.metadata;
-            if (meta.parent_cache_key !== parentKey || meta.status !== 'active')
-                return null;
-            return {
-                cacheKey: meta.cache_key,
-                anchor: meta.section_anchor,
-                headingPath: meta.section_heading_path,
-                tokenEstimate: meta.token_estimate,
-            };
-        }).sort((a, b) => (a.headingPath ?? '').localeCompare(b.headingPath ?? ''));
-    }
-}