@taurgis/bonsai 1.0.0

package/dist/commands/prune.js

@@ -0,0 +1,141 @@
+import { Flags } from '@oclif/core';
+import { unlinkSync } from 'node:fs';
+import { join } from 'node:path';
+import { BaseCommand } from '../base-command.js';
+import { scanCacheDir } from '../lib/research/storage.js';
+import { loadStoreRoots } from '../lib/research/store-roots.js';
+import { parseTtlToMs } from '../lib/research/freshness.js';
+export default class ResearchPrune extends BaseCommand {
+    static id = 'prune';
+    static summary = 'Clean up old or inactive research cache entries.';
+    static description = 'Prunes cached research entries based on age, inactivity, or artifact type to free up disk space.';
+    static examples = [
+        {
+            description: 'Perform a dry run of pruning entries older than 90 days',
+            command: '<%= config.bin %> prune --older-than 90d --dry-run',
+        },
+        {
+            description: 'Actually prune entries older than 30 days that are source scrapes',
+            command: '<%= config.bin %> prune --older-than 30d --artifact-type source --yes',
+        },
+    ];
+    static flags = {
+        'older-than': Flags.string({
+            description: 'Prune entries older than duration (e.g. "30d", "90d").',
+        }),
+        inactive: Flags.string({
+            description: 'Prune entries inactive (unvalidated/unfetched) for duration (e.g. "14d", "30d").',
+        }),
+        'artifact-type': Flags.option({
+            description: 'Filter pruning to specific artifact type.',
+            options: ['source', 'research_note'],
+        })(),
+        'dry-run': Flags.boolean({
+            description: 'List files that would be deleted without actually deleting them.',
+            default: false,
+        }),
+        yes: Flags.boolean({
+            char: 'y',
+            description: 'Skip confirmation prompt and prune files.',
+            default: false,
+        }),
+    };
+    static stdoutIsPrimaryData = true;
+    async init() {
+        await super.init();
+        const { flags } = await this.parse(ResearchPrune);
+        this.flags = flags;
+    }
+    validatePruneFlags() {
+        if (!this.flags['older-than'] && !this.flags.inactive && !this.flags['artifact-type']) {
+            this.error('Must specify at least one pruning filter: --older-than, --inactive, or --artifact-type.', { exit: 2 });
+        }
+        if (!this.flags['dry-run'] && !this.flags.yes) {
+            this.error('Safety check: Please specify --yes to confirm pruning, or --dry-run to list files that would be deleted.', { exit: 2 });
+        }
+    }
+    shouldPrune(meta, currentTime) {
+        const fetched = meta.fetched_at ? new Date(meta.fetched_at).getTime() : 0;
+        const validated = meta.validated_at ? new Date(meta.validated_at).getTime() : 0;
+        const baseTime = Math.max(fetched, validated);
+        const ageMs = currentTime.getTime() - baseTime;
+        if (this.flags['artifact-type'] && meta.artifact_type !== this.flags['artifact-type']) {
+            return false;
+        }
+        if (this.flags['older-than']) {
+            const olderThanMs = parseTtlToMs(this.flags['older-than']);
+            if (ageMs < olderThanMs) {
+                return false;
+            }
+        }
+        if (this.flags.inactive) {
+            const inactiveMs = parseTtlToMs(this.flags.inactive);
+            if (ageMs < inactiveMs) {
+                return false;
+            }
+        }
+        return true;
+    }
+    // Prune across every read root (project + global). No cross-root dedup: each file is a distinct
+    // deletion target, so a cache key present in both locations is pruned in both.
+    findPruneCandidates(readRoots, currentTime) {
+        return readRoots.flatMap((dataDir) => scanCacheDir(join(dataDir, 'research'), (artifact, filePath) => {
+            if (!this.shouldPrune(artifact.metadata, currentTime))
+                return null;
+            return {
+                cacheKey: artifact.metadata.cache_key,
+                path: filePath,
+                topic: artifact.metadata.topic,
+                url: artifact.metadata.source_url,
+            };
+        }));
+    }
+    deletePruneCandidates(filesToPrune) {
+        let prunedCount = 0;
+        for (const f of filesToPrune) {
+            try {
+                unlinkSync(f.path);
+                prunedCount++;
+            }
+            catch (err) {
+                this.warn(`Failed to delete cache file ${f.path}: ${err.message}`);
+            }
+        }
+        return prunedCount;
+    }
+    async execute() {
+        this.validatePruneFlags();
+        const roots = loadStoreRoots({
+            configDir: this.config.configDir,
+            cwd: process.cwd(),
+            dataDir: this.config.dataDir,
+        });
+        const currentTime = new Date();
+        const filesToPrune = this.findPruneCandidates(roots.readRoots, currentTime);
+        const dryRun = this.flags['dry-run'];
+        const count = filesToPrune.length;
+        if (dryRun) {
+            if (!this.requestedJson()) {
+                this.log(`[Dry Run] Found ${count} research cache entries that would be pruned:\n`);
+                filesToPrune.forEach((f) => {
+                    this.log(`- [${f.topic || 'No Topic'}] Key: ${f.cacheKey} (${f.url || 'Imported note'})`);
+                });
+            }
+        }
+        else {
+            const prunedCount = this.deletePruneCandidates(filesToPrune);
+            if (!this.requestedJson()) {
+                this.log(`Successfully pruned ${prunedCount} of ${count} research cache entries.`);
+            }
+        }
+        return {
+            dryRun,
+            prunedCount: dryRun ? 0 : filesToPrune.length,
+            candidateCount: filesToPrune.length,
+            files: filesToPrune.map((f) => ({
+                cacheKey: f.cacheKey,
+                path: f.path,
+            })),
+        };
+    }
+}

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

@@ -0,0 +1,23 @@
+import { Command } from '@oclif/core';
+import { BaseCommand } from '../../../base-command.js';
+import type { ConfigKey, ConfigScope } from '../../../lib/config/index.js';
+/**
+ * Shared base for the four `research config` subcommands: the mutually-exclusive
+ * scope-flag guard, the binary write-scope helper, and known-key validation.
+ */
+export declare abstract class ConfigCommand<T extends typeof Command> extends BaseCommand<T> {
+    protected assertScopeFlagsExclusive(global?: boolean, local?: boolean): void;
+    /** `--local` writes/reads the project file; otherwise the user-level file. */
+    protected writeScope(local?: boolean): 'user' | 'project';
+    /** Read scope for get/list: an explicit `--global`/`--local`, else the merged effective view. */
+    protected readScope(global?: boolean, local?: boolean): ConfigScope;
+    protected assertKnownKey(keyArg: string): asserts keyArg is ConfigKey;
+}
+/** Build the `--global`/`--local` scope-flag pair with per-command descriptions. */
+export declare function configScopeFlags(descriptions: {
+    global: string;
+    local: string;
+}): {
+    global: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+    local: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+};

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

@@ -0,0 +1,46 @@
+import { Flags } from '@oclif/core';
+import { BaseCommand } from '../../../base-command.js';
+import { isKnownKey, suggestKey, validKeysHint } from '../../../lib/config/index.js';
+/**
+ * Shared base for the four `research config` subcommands: the mutually-exclusive
+ * scope-flag guard, the binary write-scope helper, and known-key validation.
+ */
+export class ConfigCommand extends BaseCommand {
+    assertScopeFlagsExclusive(global, local) {
+        if (global && local) {
+            this.error('--global and --local are mutually exclusive.', { exit: 2 });
+        }
+    }
+    /** `--local` writes/reads the project file; otherwise the user-level file. */
+    writeScope(local) {
+        return local ? 'project' : 'user';
+    }
+    /** Read scope for get/list: an explicit `--global`/`--local`, else the merged effective view. */
+    readScope(global, local) {
+        if (global)
+            return 'global';
+        if (local)
+            return 'local';
+        return 'effective';
+    }
+    assertKnownKey(keyArg) {
+        if (!isKnownKey(keyArg)) {
+            const suggestion = suggestKey(keyArg);
+            const hint = suggestion ? ` Did you mean: ${suggestion}?` : '';
+            this.error(`Unknown config key: "${keyArg}".${hint} Valid keys: ${validKeysHint()}.`, {
+                exit: 2,
+            });
+        }
+    }
+}
+/** Build the `--global`/`--local` scope-flag pair with per-command descriptions. */
+export function configScopeFlags(descriptions) {
+    return {
+        global: Flags.boolean({ char: 'g', description: descriptions.global }),
+        local: Flags.boolean({
+            description: descriptions.local,
+            aliases: ['project'],
+            charAliases: ['p'],
+        }),
+    };
+}

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

@@ -0,0 +1,20 @@
+import { ConfigCommand } from './base.js';
+export default class ResearchConfigGet extends ConfigCommand<typeof ResearchConfigGet> {
+    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: {
+        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/get.js

@@ -0,0 +1,45 @@
+import { Args } from '@oclif/core';
+import { ConfigCommand, configScopeFlags } from './base.js';
+import { KEY_META, BUILT_IN_DEFAULTS, readScopedConfig } from '../../../lib/config/index.js';
+export default class ResearchConfigGet extends ConfigCommand {
+    static id = 'research config get';
+    static summary = 'Get the effective value of a research configuration key.';
+    static description = 'Print a config value. Without --global/--local, shows the merged effective value (flag > env > project > user > default).\n\nValid keys: storage.';
+    static examples = [
+        { description: 'Get the effective storage mode', command: '<%= config.bin %> research config get storage' },
+        {
+            description: 'Read only the project-level value',
+            command: '<%= config.bin %> research config get storage --local',
+        },
+    ];
+    static args = {
+        key: Args.string({ required: true, description: 'The configuration key to read.' }),
+    };
+    static flags = {
+        ...configScopeFlags({
+            global: 'Read from user-level config only.',
+            local: 'Read from project-level config only.',
+        }),
+    };
+    static stdoutIsPrimaryData = true;
+    async init() {
+        await super.init();
+        const { args, flags } = await this.parse(ResearchConfigGet);
+        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.readScope(this.flags.global, this.flags.local);
+        const value = readScopedConfig(scope, this.config.configDir, process.cwd())[key];
+        const meta = KEY_META[key];
+        const displayValue = value !== undefined ? value : BUILT_IN_DEFAULTS[key];
+        const formatted = meta.format(displayValue);
+        const suffix = value === undefined ? ' (not configured)' : '';
+        if (!this.requestedJson())
+            this.log(formatted + suffix);
+        return { key, value: displayValue };
+    }
+}

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

@@ -0,0 +1,17 @@
+import { ConfigCommand } from './base.js';
+export default class ResearchConfigList extends ConfigCommand<typeof ResearchConfigList> {
+    static id: string;
+    static summary: string;
+    static description: string;
+    static examples: {
+        description: string;
+        command: string;
+    }[];
+    static flags: {
+        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/list.js

@@ -0,0 +1,42 @@
+import { ConfigCommand, configScopeFlags } from './base.js';
+import { ALL_KEYS, KEY_META, BUILT_IN_DEFAULTS, readScopedConfig } from '../../../lib/config/index.js';
+export default class ResearchConfigList extends ConfigCommand {
+    static id = 'research config list';
+    static summary = 'List all research configuration keys and their effective values.';
+    static description = 'Show every configuration key with its current value. Use --global/--local to show a single scope.\n\nValid keys: storage.';
+    static examples = [
+        { description: 'Show all effective config values', command: '<%= config.bin %> research config list' },
+        { description: 'Show only project-level config', command: '<%= config.bin %> research config list --local' },
+    ];
+    static flags = {
+        ...configScopeFlags({
+            global: 'Show user-level config only.',
+            local: 'Show project-level config only.',
+        }),
+    };
+    static stdoutIsPrimaryData = true;
+    async init() {
+        await super.init();
+        const { flags } = await this.parse(ResearchConfigList);
+        this.flags = flags;
+    }
+    async execute() {
+        this.assertScopeFlagsExclusive(this.flags.global, this.flags.local);
+        const scope = this.readScope(this.flags.global, this.flags.local);
+        const scoped = readScopedConfig(scope, this.config.configDir, process.cwd());
+        if (!this.requestedJson()) {
+            const width = Math.max(...ALL_KEYS.map((k) => k.length)) + 2;
+            for (const key of ALL_KEYS) {
+                const raw = scoped[key];
+                const formatted = raw !== undefined ? KEY_META[key].format(raw) : '(not configured)';
+                this.log(`${key.padEnd(width)}${formatted}`);
+            }
+        }
+        const values = {};
+        for (const key of ALL_KEYS) {
+            const raw = scoped[key];
+            values[key] = raw !== undefined ? raw : BUILT_IN_DEFAULTS[key];
+        }
+        return values;
+    }
+}

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

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

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

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

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

@@ -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>;
+}