@andespindola/brainlink 1.0.5 → 1.0.6

package/dist/cli/commands/write/index-commands.js

@@ -0,0 +1,205 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { indexVault, indexVaultWithOptions } from '../../../application/index-vault.js';
+import { startVaultWatcher } from '../../../application/watch-vault.js';
+import { loadBrainlinkConfig } from '../../../infrastructure/config.js';
+import { parsePositiveInteger, print, resolveOptions } from '../../runtime.js';
+import { formatBytes } from './shared.js';
+const formatMs = (value) => Number.isFinite(value) && value != null ? `${value.toFixed(value >= 100 ? 0 : 1)}ms` : 'n/a';
+const benchEventLabel = (event) => `${event.phase}:${event.status}`;
+const printBenchRealtimeEvent = (json, event) => {
+    print(json, {
+        event: 'bench-progress',
+        ...event
+    }, () => `[bench] ${benchEventLabel(event)} ${event.message} (${formatMs(event.elapsedMs)})`);
+};
+const printBenchSummary = (json, trigger, vault, result) => {
+    print(json, {
+        event: 'bench-result',
+        trigger,
+        vault,
+        result
+    }, () => {
+        const packs = result.packs;
+        const compression = packs?.compression;
+        const savedPercent = compression && compression.inputBytes > 0
+            ? `${((1 - compression.ratio) * 100).toFixed(1)}%`
+            : 'n/a';
+        return [
+            `[bench] trigger=${trigger}`,
+            `documents=${result.documentCount} chunks=${result.chunkCount} links=${result.linkCount}`,
+            `changedDocuments=${result.changedDocumentCount ?? 0} totalElapsed=${formatMs(result.elapsedMs)}`,
+            `packsRebuilt=${packs?.rebuilt ? 'yes' : 'no'} reason=${packs?.reason ?? 'n/a'}`,
+            packs?.rebuilt
+                ? `packCount=${packs.packCount ?? 0} packDuration=${formatMs(packs.durationMs)} input=${formatBytes(compression?.inputBytes)} output=${formatBytes(compression?.outputBytes)} saved=${savedPercent}`
+                : 'packCompression=n/a'
+        ].join('\n');
+    });
+};
+const benchHistoryPath = (vaultPath) => join(vaultPath, '.brainlink', 'benchmarks', 'latest.json');
+const readBenchHistory = async (vaultPath) => {
+    try {
+        const parsed = JSON.parse(await readFile(benchHistoryPath(vaultPath), 'utf8'));
+        if (typeof parsed.elapsedMs !== 'number' || typeof parsed.timestamp !== 'string') {
+            return null;
+        }
+        return {
+            elapsedMs: parsed.elapsedMs,
+            timestamp: parsed.timestamp,
+            ...(typeof parsed.compressionRatio === 'number' ? { compressionRatio: parsed.compressionRatio } : {})
+        };
+    }
+    catch {
+        return null;
+    }
+};
+const writeBenchHistory = async (vaultPath, result) => {
+    await mkdir(dirname(benchHistoryPath(vaultPath)), { recursive: true });
+    const payload = {
+        elapsedMs: result.elapsedMs ?? 0,
+        timestamp: new Date().toISOString(),
+        ...(typeof result.packs?.compression?.ratio === 'number' ? { compressionRatio: result.packs.compression.ratio } : {})
+    };
+    await writeFile(benchHistoryPath(vaultPath), `${JSON.stringify(payload, null, 2)}\n`, 'utf8');
+};
+const evaluateBenchGuardrails = (config, result, baseline) => {
+    const compressionRatio = result.packs?.compression?.ratio;
+    const compressionSavingsPercent = typeof compressionRatio === 'number' ? Math.max(0, (1 - compressionRatio) * 100) : undefined;
+    const compressionPass = compressionSavingsPercent != null
+        ? compressionSavingsPercent >= config.searchPack.guardrailMinSavingsPercent
+        : undefined;
+    const latencyRegressionPercent = baseline && baseline.elapsedMs > 0 && typeof result.elapsedMs === 'number'
+        ? ((result.elapsedMs - baseline.elapsedMs) / baseline.elapsedMs) * 100
+        : undefined;
+    const latencyPass = latencyRegressionPercent != null
+        ? latencyRegressionPercent <= config.searchPack.guardrailMaxLatencyRegressionPercent
+        : undefined;
+    return {
+        ...(compressionSavingsPercent != null ? { compressionSavingsPercent } : {}),
+        ...(compressionPass != null ? { compressionPass } : {}),
+        ...(latencyRegressionPercent != null ? { latencyRegressionPercent } : {}),
+        ...(latencyPass != null ? { latencyPass } : {})
+    };
+};
+const printBenchGuardrails = (json, vault, config, guardrails) => {
+    print(json, {
+        event: 'bench-guardrails',
+        vault,
+        thresholds: {
+            minSavingsPercent: config.searchPack.guardrailMinSavingsPercent,
+            maxLatencyRegressionPercent: config.searchPack.guardrailMaxLatencyRegressionPercent
+        },
+        guardrails
+    }, () => {
+        const savings = guardrails.compressionSavingsPercent;
+        const latency = guardrails.latencyRegressionPercent;
+        return [
+            '[bench] guardrails',
+            `minSavings=${config.searchPack.guardrailMinSavingsPercent.toFixed(1)}% maxLatencyRegression=${config.searchPack.guardrailMaxLatencyRegressionPercent.toFixed(1)}%`,
+            `compressionSavings=${savings != null ? `${savings.toFixed(2)}%` : 'n/a'} pass=${guardrails.compressionPass != null ? (guardrails.compressionPass ? 'yes' : 'no') : 'n/a'}`,
+            `latencyRegression=${latency != null ? `${latency.toFixed(2)}%` : 'n/a'} pass=${guardrails.latencyPass != null ? (guardrails.latencyPass ? 'yes' : 'no') : 'n/a'}`
+        ].join('\n');
+    });
+};
+export const registerIndexCommands = (program) => {
+    program
+        .command('index')
+        .option('-v, --vault <vault>', 'vault directory')
+        .option('--full', 'force a complete reindex from Markdown source without reusing unchanged index entries')
+        .option('--json', 'print machine-readable JSON')
+        .description('index markdown notes, links, tags and chunks')
+        .action(async (options) => {
+        const resolved = await resolveOptions(options);
+        const result = await indexVault(resolved.vault, {
+            full: options.full === true
+        });
+        print(options.json, result, () => options.full === true
+            ? `Fully reindexed ${result.documentCount} documents, ${result.chunkCount} chunks and ${result.linkCount} links`
+            : `Indexed ${result.documentCount} documents, ${result.chunkCount} chunks and ${result.linkCount} links`);
+    });
+    program
+        .command('bench')
+        .option('-v, --vault <vault>', 'vault directory')
+        .option('-w, --watch', 'watch markdown changes and re-run benchmark in realtime')
+        .option('--debounce <ms>', 'watch debounce in milliseconds', '350')
+        .option('--json', 'print machine-readable JSON events')
+        .description('benchmark indexing in realtime, including compressed pack behavior')
+        .action(async (options) => {
+        const resolved = await resolveOptions(options);
+        const config = await loadBrainlinkConfig();
+        const emitProgress = (event) => {
+            printBenchRealtimeEvent(options.json, event);
+        };
+        const printBenchError = (error) => {
+            const message = error instanceof Error ? error.message : String(error);
+            print(options.json, { event: 'bench-error', message }, () => `[bench] error ${message}`);
+        };
+        const runAndPrint = async (trigger) => {
+            const baseline = await readBenchHistory(resolved.vault);
+            const result = await indexVaultWithOptions(resolved.vault, {
+                onProgress: emitProgress
+            });
+            printBenchSummary(options.json, trigger, resolved.vault, result);
+            const guardrails = evaluateBenchGuardrails(config, result, baseline);
+            printBenchGuardrails(options.json, resolved.vault, config, guardrails);
+            await writeBenchHistory(resolved.vault, result);
+            return result;
+        };
+        if (!options.watch) {
+            await runAndPrint('manual');
+            return;
+        }
+        const debounceMs = parsePositiveInteger(options.debounce ?? '350', 350);
+        await runAndPrint('manual');
+        print(options.json, {
+            event: 'bench-watching',
+            vault: resolved.vault,
+            debounceMs
+        }, () => `[bench] watching ${resolved.vault} (debounce=${debounceMs}ms)`);
+        const watcher = startVaultWatcher({
+            vaultPath: resolved.vault,
+            debounceMs,
+            onProgress: emitProgress,
+            onIndex: (result) => {
+                printBenchSummary(options.json, 'watch', resolved.vault, result);
+            },
+            onError: printBenchError
+        });
+        await new Promise((resolveSignal) => {
+            const shutdown = () => {
+                watcher.close();
+                resolveSignal();
+            };
+            process.once('SIGINT', shutdown);
+            process.once('SIGTERM', shutdown);
+        });
+    });
+    program
+        .command('watch')
+        .option('-v, --vault <vault>', 'vault directory')
+        .option('--json', 'print machine-readable JSON events')
+        .description('watch markdown files and reindex on changes')
+        .action(async (options) => {
+        const resolved = await resolveOptions(options);
+        const initial = await indexVault(resolved.vault);
+        const watcher = startVaultWatcher({
+            vaultPath: resolved.vault,
+            onIndex: (result) => {
+                print(options.json, { event: 'indexed', result }, () => `Indexed ${result.documentCount} documents, ${result.chunkCount} chunks and ${result.linkCount} links`);
+            },
+            onError: (error) => {
+                const message = error instanceof Error ? error.message : String(error);
+                print(options.json, { event: 'error', message }, () => message);
+            }
+        });
+        print(options.json, { event: 'watching', vault: resolved.vault, initial }, () => `Watching ${resolved.vault}`);
+        process.once('SIGINT', () => {
+            watcher.close();
+            process.exit(0);
+        });
+        process.once('SIGTERM', () => {
+            watcher.close();
+            process.exit(0);
+        });
+    });
+};

package/dist/cli/commands/write/link-commands.js

@@ -0,0 +1,68 @@
+import { indexVault } from '../../../application/index-vault.js';
+import { migrateContextLinks } from '../../../application/migrate-context-links.js';
+import { canonicalizeContextLinks } from '../../../application/canonical-context-links.js';
+import { parsePositiveInteger, print, resolveOptions } from '../../runtime.js';
+export const registerLinkCommands = (program) => {
+    program
+        .command('migrate-context-links')
+        .option('-v, --vault <vault>', 'vault directory')
+        .option('-a, --agent <agent>', 'agent memory namespace')
+        .option('-l, --limit <limit>', 'maximum context links to add per note', '5')
+        .option('--dry-run', 'preview context-link migration without writing files')
+        .option('--no-index', 'skip reindexing after migration')
+        .option('--json', 'print machine-readable JSON')
+        .description('add concise Context Links sections from existing wiki-link mentions')
+        .action(async (options) => {
+        const resolved = await resolveOptions(options);
+        const result = await migrateContextLinks(resolved.vault, {
+            dryRun: options.dryRun === true,
+            limit: parsePositiveInteger(options.limit ?? '5', 5),
+            agentId: resolved.agent
+        });
+        const shouldIndex = options.index !== false && !result.dryRun && result.changed > 0;
+        const index = shouldIndex ? await indexVault(resolved.vault, { full: true }) : undefined;
+        print(options.json, {
+            vault: resolved.vault,
+            agent: resolved.agent ?? 'shared',
+            ...result,
+            ...(index ? { index } : {})
+        }, () => {
+            const mode = result.dryRun ? 'Previewed' : 'Migrated';
+            const indexMessage = index
+                ? ` Fully reindexed ${index.documentCount} documents, ${index.chunkCount} chunks and ${index.linkCount} context links.`
+                : '';
+            return `${mode} ${result.scanned} notes: changed=${result.changed}, skipped=${result.skipped}, limit=${result.limit}.${indexMessage}`;
+        });
+    });
+    program
+        .command('canonicalize-context-links')
+        .option('-v, --vault <vault>', 'vault directory')
+        .option('-a, --agent <agent>', 'agent memory namespace')
+        .option('--dry-run', 'preview canonical context links without writing files')
+        .option('--no-create-hubs', 'do not create missing context hub notes')
+        .option('--no-index', 'skip reindexing after canonicalization')
+        .option('--json', 'print machine-readable JSON')
+        .description('ensure notes have canonical Context Links to their inferred context hubs')
+        .action(async (options) => {
+        const resolved = await resolveOptions(options);
+        const result = await canonicalizeContextLinks(resolved.vault, {
+            dryRun: options.dryRun === true,
+            agentId: resolved.agent,
+            createMissingHubs: options.createHubs !== false
+        });
+        const shouldIndex = options.index !== false && !result.dryRun && result.changed > 0;
+        const index = shouldIndex ? await indexVault(resolved.vault, { full: true }) : undefined;
+        print(options.json, {
+            vault: resolved.vault,
+            agent: resolved.agent ?? 'shared',
+            ...result,
+            ...(index ? { index } : {})
+        }, () => {
+            const mode = result.dryRun ? 'Previewed' : 'Canonicalized';
+            const indexMessage = index
+                ? ` Fully reindexed ${index.documentCount} documents, ${index.chunkCount} chunks and ${index.linkCount} context links.`
+                : '';
+            return `${mode} ${result.scanned} notes: changed=${result.changed}, createdHubs=${result.createdHubs}, skipped=${result.skipped}.${indexMessage}`;
+        });
+    });
+};

package/dist/cli/commands/write/note-commands.js

@@ -0,0 +1,146 @@
+import { relative, resolve } from 'node:path';
+import { addNoteWithMetadata } from '../../../application/add-note.js';
+import { deleteNote } from '../../../application/delete-note.js';
+import { scanDuplicateNotes } from '../../../application/dedupe-notes.js';
+import { importFile } from '../../../application/import-file.js';
+import { indexVault } from '../../../application/index-vault.js';
+import { ensureVault } from '../../../infrastructure/file-system-vault.js';
+import { addVolatileMemory, clearVolatileMemory } from '../../../infrastructure/volatile-memory.js';
+import { parsePositiveInteger, print, resolveOptions } from '../../runtime.js';
+import { resolveAddContent } from './shared.js';
+export const registerNoteCommands = (program) => {
+    program
+        .command('volatile')
+        .option('-c, --content <content>', 'temporary memory content to add')
+        .option('--ttl <minutes>', 'time-to-live in minutes', '240')
+        .option('--tag <tag...>', 'volatile memory tag')
+        .option('-v, --vault <vault>', 'vault directory')
+        .option('-a, --agent <agent>', 'agent memory namespace')
+        .option('--clear', 'clear volatile memory for the current agent namespace')
+        .option('--json', 'print machine-readable JSON')
+        .description('add or clear temporary agent-decided memory')
+        .action(async (options) => {
+        const resolved = await resolveOptions(options);
+        if (options.clear) {
+            const cleared = await clearVolatileMemory(resolved.vault, resolved.agent);
+            print(options.json, { cleared, agent: resolved.agent ?? 'shared' }, () => `Cleared ${cleared} volatile memories.`);
+            return;
+        }
+        if (!options.content || options.content.trim().length === 0) {
+            throw new Error('Use --content to add volatile memory, or --clear to remove it.');
+        }
+        const entry = await addVolatileMemory(resolved.vault, options.content, resolved.agent ?? 'shared', parsePositiveInteger(options.ttl ?? '240', 240), options.tag ?? []);
+        print(options.json, { entry }, () => `Stored volatile memory until ${entry.expiresAt}.`);
+    });
+    program
+        .command('add')
+        .argument('<title>', 'note title')
+        .option('-c, --content <content>', 'markdown content')
+        .option('-f, --content-file <contentFile>', 'read markdown content from a file')
+        .option('-v, --vault <vault>', 'vault directory')
+        .option('-a, --agent <agent>', 'agent memory namespace')
+        .option('--allow-sensitive', 'allow writing content that looks like a secret')
+        .option('--no-auto-context-links', 'skip canonical Context Links for this note')
+        .option('--no-auto-index', 'skip reindexing after add')
+        .option('--json', 'print machine-readable JSON')
+        .description('add a markdown note to the vault')
+        .action(async (title, options) => {
+        const resolved = await resolveOptions(options);
+        const content = resolveAddContent(options);
+        const added = await addNoteWithMetadata(resolved.vault, title, content, resolved.agent, {
+            allowSensitive: Boolean(options.allowSensitive),
+            autoContextLinks: options.autoContextLinks !== false && resolved.config.autoCanonicalContextLinks
+        });
+        const shouldAutoIndex = options.autoIndex !== false && resolved.config.autoIndexOnWrite;
+        const index = shouldAutoIndex ? await indexVault(resolved.vault) : undefined;
+        const absoluteVaultPath = await ensureVault(resolved.vault);
+        const focusPath = added.path.startsWith(absoluteVaultPath)
+            ? relative(absoluteVaultPath, added.path).replaceAll('\\', '/')
+            : added.path.includes('agents/')
+                ? added.path.slice(added.path.indexOf('agents/')).replaceAll('\\', '/')
+                : undefined;
+        const possibleDuplicates = await scanDuplicateNotes(resolved.vault, {
+            agentId: resolved.agent,
+            focusPath,
+            limit: 5,
+            minSemanticScore: 0.92,
+            includeSemantic: true
+        });
+        print(options.json, {
+            title,
+            agent: resolved.agent ?? 'shared',
+            path: added.path,
+            writeConnectivity: {
+                autoLinked: added.autoLinked,
+                linkTarget: added.linkTarget,
+                context: added.context,
+                hubCreated: added.hubCreated,
+                guaranteedEdge: added.autoLinked
+            },
+            possibleDuplicates,
+            ...(index ? { index } : {})
+        }, () => {
+            const duplicateMessage = possibleDuplicates.length > 0
+                ? `\nPotential duplicates: ${possibleDuplicates.length}. Use "blink dedupe --json" or "blink dedupe-resolve".`
+                : '';
+            const linkMessage = added.autoLinked ? ` Linked to [[${added.linkTarget}]].` : '';
+            return `Created note at ${added.path}.${linkMessage}${duplicateMessage}`;
+        });
+    });
+    program
+        .command('import-file')
+        .argument('<file>', 'file to convert and import into the vault')
+        .option('-t, --title <title>', 'note title; defaults to the source filename')
+        .option('-v, --vault <vault>', 'vault directory')
+        .option('-a, --agent <agent>', 'agent memory namespace')
+        .option('--allow-sensitive', 'allow writing converted content that looks like a secret')
+        .option('--no-auto-context-links', 'skip canonical Context Links for this imported note')
+        .option('--no-auto-index', 'skip reindexing after import')
+        .option('--json', 'print machine-readable JSON')
+        .description('convert a document with Docling and import it as a Markdown note')
+        .action(async (file, options) => {
+        const resolved = await resolveOptions(options);
+        const result = await importFile({
+            vaultPath: resolved.vault,
+            filePath: resolve(file),
+            title: options.title,
+            agentId: resolved.agent,
+            allowSensitive: Boolean(options.allowSensitive),
+            autoContextLinks: options.autoContextLinks !== false && resolved.config.autoCanonicalContextLinks,
+            autoIndex: options.autoIndex !== false && resolved.config.autoIndexOnWrite
+        });
+        print(options.json, {
+            vault: resolved.vault,
+            agent: resolved.agent ?? 'shared',
+            ...result
+        }, () => {
+            const linkMessage = result.writeConnectivity.autoLinked ? ` Linked to [[${result.writeConnectivity.linkTarget}]].` : '';
+            const indexMessage = result.index ? ` Indexed ${result.index.documentCount} documents.` : '';
+            return `Imported ${result.sourceName} as "${result.title}" at ${result.path}.${linkMessage}${indexMessage}`;
+        });
+    });
+    program
+        .command('delete-note')
+        .option('-v, --vault <vault>', 'vault directory')
+        .option('-a, --agent <agent>', 'agent memory namespace when deleting by title')
+        .option('--title <title>', 'note title to delete')
+        .option('--path <path>', 'vault-relative or absolute markdown note path to delete')
+        .option('--yes', 'confirm note deletion')
+        .option('--no-auto-index', 'skip reindexing after delete')
+        .option('--json', 'print machine-readable JSON')
+        .description('delete a Markdown note from the vault after explicit confirmation')
+        .action(async (options) => {
+        const resolved = await resolveOptions(options);
+        const result = await deleteNote(resolved.vault, {
+            title: options.title,
+            path: options.path,
+            agentId: resolved.agent,
+            confirm: Boolean(options.yes),
+            autoIndex: options.autoIndex !== false
+        });
+        print(options.json, {
+            vault: resolved.vault,
+            ...result
+        }, () => `Deleted note ${result.relativePath}.`);
+    });
+};