@taurgis/bonsai 1.0.0

package/dist/commands/research/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 = '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

@@ -0,0 +1,13 @@
+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

@@ -0,0 +1,86 @@
+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 ?? ''));
+    }
+}

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

@@ -0,0 +1,25 @@
+import { BaseCommand } from '../../base-command.js';
+export default class ResearchList extends BaseCommand<typeof ResearchList> {
+    static id: string;
+    static summary: string;
+    static description: string;
+    static examples: {
+        description: string;
+        command: string;
+    }[];
+    static flags: {
+        topic: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        tags: import("@oclif/core/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        freshness: import("@oclif/core/interfaces").OptionFlag<"fresh" | "stale_grace" | "stale_expired" | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'artifact-type': import("@oclif/core/interfaces").OptionFlag<"source" | "research_note" | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'capture-method': import("@oclif/core/interfaces").OptionFlag<"static_fetch" | "browser_fallback" | "agent_supplied" | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        limit: import("@oclif/core/interfaces").OptionFlag<number, import("@oclif/core/interfaces").CustomOptions>;
+    };
+    static stdoutIsPrimaryData: boolean;
+    init(): Promise<void>;
+    private validateListFlags;
+    private matchesFilters;
+    private scanCacheDirForList;
+    private logListResults;
+    execute(): Promise<unknown>;
+}

package/dist/commands/research/list.js

@@ -0,0 +1,143 @@
+import { Flags } from '@oclif/core';
+import { BaseCommand } from '../../base-command.js';
+import { scanCacheDirs } from '../../lib/research/storage.js';
+import { loadStoreRoots } from '../../lib/research/store-roots.js';
+import { evaluateFreshness } from '../../lib/research/freshness.js';
+export default class ResearchList extends BaseCommand {
+    static id = 'research list';
+    static summary = 'List cached research artifacts by metadata filters.';
+    static description = 'Lists cached research artifacts, including metadata details like path, source count, freshness, token estimates, and quality metrics without printing full content.';
+    static examples = [
+        {
+            description: 'List all cached entries',
+            command: '<%= config.bin %> research list',
+        },
+        {
+            description: 'List cached entries for a specific topic with JSON output',
+            command: '<%= config.bin %> research list --topic "React Suspense" --json',
+        },
+        {
+            description: 'List only fresh entries filtered by tags',
+            command: '<%= config.bin %> research list --freshness fresh --tags node --tags url',
+        },
+    ];
+    static flags = {
+        topic: Flags.string({
+            char: 't',
+            description: 'Filter by exact topic (case-insensitive).',
+        }),
+        tags: Flags.string({
+            char: 'g',
+            description: 'Filter by tags (must match all tags specified).',
+            multiple: true,
+        }),
+        freshness: Flags.option({
+            description: 'Filter by freshness state.',
+            options: ['fresh', 'stale_grace', 'stale_expired'],
+        })(),
+        'artifact-type': Flags.option({
+            description: 'Filter by artifact type.',
+            options: ['source', 'research_note'],
+        })(),
+        'capture-method': Flags.option({
+            description: 'Filter by capture method.',
+            options: ['static_fetch', 'browser_fallback', 'agent_supplied'],
+        })(),
+        limit: Flags.integer({
+            description: 'Maximum number of results to return (default 50, max 100).',
+            default: 50,
+        }),
+    };
+    static stdoutIsPrimaryData = true;
+    async init() {
+        await super.init();
+        const { flags } = await this.parse(ResearchList);
+        this.flags = flags;
+    }
+    validateListFlags() {
+        const limit = this.flags.limit;
+        if (limit !== undefined && (limit < 1 || limit > 100)) {
+            this.error('Limit must be between 1 and 100.', { exit: 2 });
+        }
+    }
+    matchesFilters(meta, freshness) {
+        if (this.flags.topic &&
+            (!meta.topic || meta.topic.trim().toLowerCase() !== this.flags.topic.trim().toLowerCase())) {
+            return false;
+        }
+        if (this.flags.tags && this.flags.tags.length > 0) {
+            const metaTagsLower = (meta.tags || []).map((t) => t.toLowerCase());
+            const hasAllTags = this.flags.tags.every((t) => metaTagsLower.includes(t.toLowerCase()));
+            if (!hasAllTags) {
+                return false;
+            }
+        }
+        if (this.flags['artifact-type'] && meta.artifact_type !== this.flags['artifact-type']) {
+            return false;
+        }
+        if (this.flags['capture-method'] && meta.capture_method !== this.flags['capture-method']) {
+            return false;
+        }
+        if (this.flags.freshness && freshness !== this.flags.freshness) {
+            return false;
+        }
+        return true;
+    }
+    scanCacheDirForList(readRoots, currentTime) {
+        return scanCacheDirs(readRoots, (artifact, filePath) => {
+            if (artifact.metadata.status !== 'active')
+                return null;
+            const freshness = evaluateFreshness(artifact.metadata, currentTime, null);
+            if (!this.matchesFilters(artifact.metadata, freshness))
+                return null;
+            return {
+                cacheKey: artifact.metadata.cache_key,
+                path: filePath,
+                artifactType: artifact.metadata.artifact_type,
+                sourceUrls: artifact.metadata.source_urls,
+                topic: artifact.metadata.topic,
+                tags: artifact.metadata.tags,
+                freshness,
+                captureMethod: artifact.metadata.capture_method,
+                tokenEstimate: artifact.metadata.token_estimate,
+                qualityNotes: artifact.metadata.quality_notes,
+                fetchedAt: artifact.metadata.fetched_at,
+                validatedAt: artifact.metadata.validated_at,
+            };
+        });
+    }
+    logListResults(finalResults) {
+        if (this.requestedJson())
+            return;
+        if (finalResults.length === 0) {
+            this.log('No cached research entries found matching filters.');
+            return;
+        }
+        this.log(`Found ${finalResults.length} cached research entries:\n`);
+        finalResults.forEach((res, index) => {
+            this.log(`${index + 1}. [${res.topic || 'No Topic'}] Key: ${res.cacheKey}`);
+            this.log(`   Type: ${res.artifactType} | Freshness: ${res.freshness}`);
+            this.log(`   Tokens: compressed=${res.tokenEstimate?.compressed || 0}, detailed=${res.tokenEstimate?.detailed || 0}`);
+            this.log(`   Source URLs: ${res.sourceUrls.join(', ')}\n`);
+        });
+    }
+    async execute() {
+        this.validateListFlags();
+        const roots = loadStoreRoots({
+            configDir: this.config.configDir,
+            cwd: process.cwd(),
+            dataDir: this.config.dataDir,
+        });
+        const currentTime = new Date();
+        const results = this.scanCacheDirForList(roots.readRoots, currentTime);
+        // Sort by validated_at or fetched_at descending (most recent first)
+        results.sort((a, b) => {
+            const timeA = new Date(a.validatedAt || a.fetchedAt || 0).getTime();
+            const timeB = new Date(b.validatedAt || b.fetchedAt || 0).getTime();
+            return timeB - timeA;
+        });
+        const finalResults = results.slice(0, this.flags.limit);
+        this.logListResults(finalResults);
+        return finalResults;
+    }
+}

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

@@ -0,0 +1,24 @@
+import { BaseCommand } from '../../base-command.js';
+export default class ResearchPrune extends BaseCommand<typeof ResearchPrune> {
+    static id: string;
+    static summary: string;
+    static description: string;
+    static examples: {
+        description: string;
+        command: string;
+    }[];
+    static flags: {
+        'older-than': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        inactive: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'artifact-type': import("@oclif/core/interfaces").OptionFlag<"source" | "research_note" | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'dry-run': import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        yes: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+    };
+    static stdoutIsPrimaryData: boolean;
+    init(): Promise<void>;
+    private validatePruneFlags;
+    private shouldPrune;
+    private findPruneCandidates;
+    private deletePruneCandidates;
+    execute(): Promise<unknown>;
+}