@andespindola/brainlink 1.0.7 → 1.2.0

package/dist/cli/commands/vault-sync-commands.js

@@ -0,0 +1,137 @@
+import { cloneVault, commitVault, initVaultGit, pullVault, pushVault, restoreVault, vaultGitStatus, vaultHistory } from '../../application/vault-git.js';
+import { provisionVaultRepo } from '../../application/provision-vault.js';
+import { exportVaultSnapshot, importVaultSnapshot } from '../../application/vault-snapshot.js';
+import { print, resolveOptions } from '../runtime.js';
+export const registerVaultSyncCommands = (program) => {
+    program
+        .command('vault-init-git')
+        .option('--vault <vault>', 'vault directory')
+        .option('--remote <url>', 'git remote URL (SSH or credential-helper backed; inline tokens are rejected)')
+        .option('--json', 'print machine-readable JSON')
+        .description('initialize git versioning for the vault (ignores the derived .brainlink/)')
+        .action(async (options) => {
+        const { vault } = await resolveOptions(options);
+        const result = await initVaultGit(vault, { remote: options.remote });
+        print(options.json, result, () => `${result.initialized ? 'Initialized' : 'Reused'} git repo at ${result.root}${options.remote ? ` (origin: ${options.remote})` : ''}.`);
+    });
+    program
+        .command('vault-provision')
+        .option('--vault <vault>', 'vault directory')
+        .option('--name <name>', 'repository name to create', 'brainlink-vault')
+        .option('--public', 'create a public repository instead of private')
+        .option('--no-auto-version', 'do not enable autoVersion after provisioning')
+        .option('--no-encrypt', 'commit plaintext Markdown instead of encrypted ciphertext')
+        .option('-m, --message <message>', 'initial commit message')
+        .option('--json', 'print machine-readable JSON')
+        .description('create a private GitHub repo for the vault via gh, push it, and enable encrypted auto-versioning')
+        .action(async (options) => {
+        const { vault } = await resolveOptions(options);
+        const result = await provisionVaultRepo(vault, {
+            name: options.name,
+            private: options.public !== true,
+            enableAutoVersion: options.autoVersion !== false,
+            encrypt: options.encrypt !== false,
+            message: options.message
+        });
+        print(options.json, result, () => `${result.created ? 'Created' : 'Reused'} ${result.repo} and pushed the vault${result.encrypted ? ' (encrypted)' : ''}${result.autoVersionEnabled ? '; autoVersion enabled' : ''}.`);
+    });
+    program
+        .command('vault-commit')
+        .requiredOption('-m, --message <message>', 'commit message')
+        .option('--vault <vault>', 'vault directory')
+        .option('--json', 'print machine-readable JSON')
+        .description('commit the vault Markdown')
+        .action(async (options) => {
+        const { vault } = await resolveOptions(options);
+        const hash = await commitVault(vault, options.message ?? 'Update vault');
+        print(options.json, { committed: hash != null, hash }, () => hash ? `Committed ${hash.slice(0, 10)}.` : 'Nothing to commit.');
+    });
+    program
+        .command('vault-status')
+        .option('--vault <vault>', 'vault directory')
+        .option('--json', 'print machine-readable JSON')
+        .description('show git status of the vault Markdown')
+        .action(async (options) => {
+        const { vault } = await resolveOptions(options);
+        const status = await vaultGitStatus(vault);
+        print(options.json, status, () => `Branch ${status.branch}; ${status.dirty ? `${status.changedMarkdown.length} changed markdown file(s)` : 'clean'}.`);
+    });
+    program
+        .command('vault-history')
+        .option('--vault <vault>', 'vault directory')
+        .option('--limit <n>', 'number of entries', '20')
+        .option('--json', 'print machine-readable JSON')
+        .description('show vault commit history')
+        .action(async (options) => {
+        const { vault } = await resolveOptions(options);
+        const entries = await vaultHistory(vault, Number.parseInt(options.limit ?? '20', 10));
+        print(options.json, entries, () => entries.map((entry) => `${entry.hash.slice(0, 10)}  ${entry.date}  ${entry.subject}`).join('\n') || 'No history.');
+    });
+    program
+        .command('vault-push')
+        .option('--vault <vault>', 'vault directory')
+        .option('--json', 'print machine-readable JSON')
+        .description('push the vault to its git remote')
+        .action(async (options) => {
+        const { vault } = await resolveOptions(options);
+        await pushVault(vault);
+        print(options.json, { pushed: true }, () => 'Pushed to origin.');
+    });
+    program
+        .command('vault-pull')
+        .option('--vault <vault>', 'vault directory')
+        .option('--no-index', 'skip reindexing after pull')
+        .option('--json', 'print machine-readable JSON')
+        .description('pull the vault from git and reindex changed notes')
+        .action(async (options) => {
+        const { vault } = await resolveOptions(options);
+        const result = await pullVault(vault, { skipIndex: options.index === false });
+        print(options.json, result, () => `Pulled. ${result.changedMarkdown.length} markdown file(s) changed${result.index ? `; reindexed ${result.index.documentCount} docs` : ''}.`);
+    });
+    program
+        .command('vault-restore')
+        .argument('<ref>', 'git ref (commit, tag, branch) to restore Markdown from')
+        .option('--vault <vault>', 'vault directory')
+        .option('--no-index', 'skip reindexing after restore')
+        .option('--json', 'print machine-readable JSON')
+        .description('restore vault Markdown from a git ref and reindex')
+        .action(async (ref, options) => {
+        const { vault } = await resolveOptions(options);
+        const result = await restoreVault(vault, ref, { skipIndex: options.index === false });
+        print(options.json, result, () => `Restored from ${ref}. ${result.changedMarkdown.length} markdown file(s) changed${result.index ? `; reindexed ${result.index.documentCount} docs` : ''}.`);
+    });
+    program
+        .command('vault-clone')
+        .argument('<remote>', 'git remote URL')
+        .argument('<dir>', 'target directory')
+        .option('--no-index', 'skip building the index after clone')
+        .option('--json', 'print machine-readable JSON')
+        .description('clone a remote vault and build its index')
+        .action(async (remote, dir, options) => {
+        const result = await cloneVault(remote, dir, { skipIndex: options.index === false });
+        print(options.json, result, () => `Cloned to ${result.root}${result.index ? `; indexed ${result.index.documentCount} docs` : ''}.`);
+    });
+    program
+        .command('vault-export')
+        .requiredOption('-o, --output <file>', 'output .blvault file')
+        .option('--vault <vault>', 'vault directory')
+        .option('--json', 'print machine-readable JSON')
+        .description('export the vault Markdown to a portable .blvault snapshot')
+        .action(async (options) => {
+        const { vault } = await resolveOptions(options);
+        const result = await exportVaultSnapshot(vault, options.output ?? 'vault.blvault');
+        print(options.json, result, () => `Exported ${result.fileCount} files to ${result.file} (${result.bytes} bytes).`);
+    });
+    program
+        .command('vault-import')
+        .argument('<file>', 'input .blvault file')
+        .option('--vault <vault>', 'vault directory')
+        .option('--no-index', 'skip reindexing after import')
+        .option('--json', 'print machine-readable JSON')
+        .description('import a .blvault snapshot into the vault and reindex')
+        .action(async (file, options) => {
+        const { vault } = await resolveOptions(options);
+        const result = await importVaultSnapshot(file, vault, { skipIndex: options.index === false });
+        print(options.json, result, () => `Imported ${result.imported} files (${result.conflicted} conflicts)${result.index ? `; reindexed ${result.index.documentCount} docs` : ''}.`);
+    });
+};

package/dist/cli/commands/write/vault-lifecycle-commands.js

@@ -204,7 +204,7 @@ export const registerVaultLifecycleCommands = (program) => {
         const policy = await getBootstrapPolicy();
         const bootstrapStatus = await getBootstrapSessionStatus(resolved.vault, resolved.agent);
         const context = options.query
-            ? await buildContextPackage(resolved.vault, options.query, limit, tokens, resolved.agent, mode, strategy, resolved.defaults.defaultContextCacheTtlMs)
+            ? await buildContextPackage(resolved.vault, options.query, limit, tokens, resolved.agent, mode, strategy, resolved.defaults.defaultContextCacheTtlMs, resolved.defaults.cagPackTtlMs)
             : null;
         const agentIntegration = options.installAgent === false
             ? null

package/dist/cli/main.js

@@ -10,6 +10,7 @@ import { registerConfigCommands } from './commands/config-commands.js';
 import { registerPracticalCommands } from './commands/practical-commands.js';
 import { registerReadCommands } from './commands/read-commands.js';
 import { registerVaultCommands } from './commands/vault-commands.js';
+import { registerVaultSyncCommands } from './commands/vault-sync-commands.js';
 import { registerWriteCommands } from './commands/write-commands.js';
 const readPackageMetadata = () => {
     const packagePath = join(dirname(fileURLToPath(import.meta.url)), '../../package.json');
@@ -63,6 +64,7 @@ registerReadCommands(program);
 registerPracticalCommands(program);
 registerConfigCommands(program);
 registerVaultCommands(program);
+registerVaultSyncCommands(program);
 registerAgentCommands(program);
 await maybePrintUpdateNotice(packageMetadata);
 program.parseAsync().catch((error) => {

package/dist/infrastructure/config.js

@@ -11,16 +11,21 @@ export const defaultBrainlinkConfig = {
     defaultAgent: undefined,
     autoIndexOnWrite: true,
     autoCanonicalContextLinks: true,
+    autoVersion: false,
+    vaultEncryption: false,
     autoUpdateCheck: true,
     updateCheckIntervalMs: 86_400_000,
     defaultSearchLimit: 8,
     defaultContextTokens: 1500,
     defaultContextStrategy: 'auto',
     defaultContextCacheTtlMs: 120_000,
+    cagPackTtlMs: 0,
     embeddingProvider: 'local',
     embedding: {},
     defaultSearchMode: 'hybrid',
     chunkSize: 1200,
+    storageBackend: 'binary',
+    hybridFusion: 'rrf',
     searchPack: {
         rowChunkSize: 5_000,
         compressionLevel: 5,
@@ -47,6 +52,10 @@ const isRecord = (value) => typeof value === 'object' && value !== null && !Arra
 const embeddingProviders = new Set(['none', 'local', 'ollama', 'openai']);
 const searchModes = new Set(['fts', 'semantic', 'hybrid']);
 const contextStrategies = new Set(['rag', 'cag', 'auto']);
+const storageBackends = new Set(['json', 'binary', 'lmdb']);
+const hybridFusions = new Set(['rrf', 'linear']);
+const sanitizeStorageBackend = (value) => typeof value === 'string' && storageBackends.has(value) ? value : defaultBrainlinkConfig.storageBackend;
+const sanitizeHybridFusion = (value) => typeof value === 'string' && hybridFusions.has(value) ? value : defaultBrainlinkConfig.hybridFusion;
 const sanitizeEmbeddingProvider = (value) => typeof value === 'string' && embeddingProviders.has(value) ? value : defaultBrainlinkConfig.embeddingProvider;
 const sanitizeOptionalString = (value) => typeof value === 'string' && value.trim().length > 0 ? value.trim() : undefined;
 const sanitizeEmbeddingConfig = (value) => {
@@ -204,6 +213,8 @@ const sanitizeConfig = (value) => ({
     autoCanonicalContextLinks: typeof value.autoCanonicalContextLinks === 'boolean'
         ? value.autoCanonicalContextLinks
         : defaultBrainlinkConfig.autoCanonicalContextLinks,
+    autoVersion: typeof value.autoVersion === 'boolean' ? value.autoVersion : defaultBrainlinkConfig.autoVersion,
+    vaultEncryption: typeof value.vaultEncryption === 'boolean' ? value.vaultEncryption : defaultBrainlinkConfig.vaultEncryption,
     autoUpdateCheck: typeof value.autoUpdateCheck === 'boolean' ? value.autoUpdateCheck : defaultBrainlinkConfig.autoUpdateCheck,
     updateCheckIntervalMs: typeof value.updateCheckIntervalMs === 'number' && Number.isFinite(value.updateCheckIntervalMs) && value.updateCheckIntervalMs > 0
         ? Math.floor(value.updateCheckIntervalMs)
@@ -218,8 +229,11 @@ const sanitizeConfig = (value) => ({
     defaultContextCacheTtlMs: typeof value.defaultContextCacheTtlMs === 'number' && Number.isFinite(value.defaultContextCacheTtlMs) && value.defaultContextCacheTtlMs > 0
         ? Math.floor(value.defaultContextCacheTtlMs)
         : defaultBrainlinkConfig.defaultContextCacheTtlMs,
+    cagPackTtlMs: sanitizeIntegerInRange(value.cagPackTtlMs, defaultBrainlinkConfig.cagPackTtlMs, 0, 2_147_483_647),
     allowedVaults: [...sanitizeAllowedVaults(value.allowedVaults), ...readAllowedVaultsFromEnv()],
     chunkSize: typeof value.chunkSize === 'number' && value.chunkSize > 0 ? value.chunkSize : defaultBrainlinkConfig.chunkSize,
+    storageBackend: sanitizeStorageBackend(value.storageBackend),
+    hybridFusion: sanitizeHybridFusion(value.hybridFusion),
     searchPack: sanitizeSearchPackConfig(value.searchPack),
     embeddingProvider: sanitizeEmbeddingProvider(value.embeddingProvider),
     embedding: sanitizeEmbeddingConfig(value.embedding),
@@ -234,7 +248,8 @@ export const resolveAgentRuntimeDefaults = (config, agent) => {
         defaultContextTokens: profile?.defaultContextTokens ?? config.defaultContextTokens,
         defaultSearchMode: profile?.defaultSearchMode ?? config.defaultSearchMode,
         defaultContextStrategy: profile?.defaultContextStrategy ?? config.defaultContextStrategy,
-        defaultContextCacheTtlMs: profile?.defaultContextCacheTtlMs ?? config.defaultContextCacheTtlMs
+        defaultContextCacheTtlMs: profile?.defaultContextCacheTtlMs ?? config.defaultContextCacheTtlMs,
+        cagPackTtlMs: config.cagPackTtlMs
     };
 };
 const mergeConfigLayers = (layers) => layers.reduce((state, config) => ({

package/dist/infrastructure/context-packs.js

@@ -1,6 +1,7 @@
 import { createHash } from 'node:crypto';
 import { mkdir, readFile, readdir, rm, stat, writeFile } from 'node:fs/promises';
 import { basename, join } from 'node:path';
+const storedPackVersion = 2;
 const normalizePackKey = (key) => ({
     query: key.query.trim().toLowerCase(),
     limit: key.limit,
@@ -13,12 +14,35 @@ export const contextPackPath = (vaultPath, key) => {
     const digest = createHash('sha256').update(JSON.stringify(normalizePackKey(key))).digest('hex');
     return join(contextPacksDirectory(vaultPath), `${digest}.json`);
 };
+// Signature of a single file, matching the volatile/index signatures used
+// elsewhere (floored mtime + size). A missing file collapses to a stable
+// sentinel so a deleted dependency reliably differs from its recorded value.
+const fileSignature = async (path) => {
+    try {
+        const info = await stat(path);
+        return `${Math.floor(info.mtimeMs)}:${info.size}`;
+    }
+    catch {
+        return '0:0';
+    }
+};
+// Durable (non-volatile) section source paths, deduplicated. Volatile sections
+// come from turn memory rather than vault files, so they are tracked through the
+// separate volatile signature instead of per-document dependencies.
+const dependencyPaths = (context) => {
+    const paths = context.sections.filter((section) => !section.volatile).map((section) => section.path);
+    return Array.from(new Set(paths));
+};
+const computeDependencies = async (vaultPath, context) => Promise.all(dependencyPaths(context).map(async (path) => ({ path, signature: await fileSignature(join(vaultPath, path)) })));
 const isStoredContextPack = (value) => {
     if (!value || typeof value !== 'object') {
         return false;
     }
     const candidate = value;
-    return candidate.version === 1 && typeof candidate.dataSignature === 'string' && Boolean(candidate.context);
+    return (candidate.version === storedPackVersion &&
+        Array.isArray(candidate.dependencies) &&
+        typeof candidate.volatileSignature === 'string' &&
+        Boolean(candidate.context));
 };
 const readStoredContextPack = async (path) => {
     try {
@@ -29,30 +53,43 @@ const readStoredContextPack = async (path) => {
         return null;
     }
 };
-const toContextPackSummary = async (path, dataSignature) => {
-    const [info, stored] = await Promise.all([
-        stat(path),
-        readStoredContextPack(path)
-    ]);
-    const stale = !stored || (typeof dataSignature === 'string' && stored.dataSignature !== dataSignature);
+// A pack is fresh while it is within its optional TTL, its volatile signature
+// matches, and every cited document is unchanged on disk. Reads no vault index,
+// so the CAG fast path stays cheap: a few stats over the cited files.
+const isPackFresh = async (vaultPath, stored, freshness, now) => {
+    if (freshness.ttlMs > 0) {
+        const age = now - Date.parse(stored.createdAt);
+        if (!Number.isFinite(age) || age > freshness.ttlMs) {
+            return false;
+        }
+    }
+    if (stored.volatileSignature !== freshness.volatileSignature) {
+        return false;
+    }
+    const current = await Promise.all(stored.dependencies.map((dependency) => fileSignature(join(vaultPath, dependency.path))));
+    return stored.dependencies.every((dependency, index) => dependency.signature === current[index]);
+};
+const toContextPackSummary = async (path, vaultPath, freshness) => {
+    const [info, stored] = await Promise.all([stat(path), readStoredContextPack(path)]);
+    const stale = !stored || (freshness ? !(await isPackFresh(vaultPath, stored, freshness, Date.now())) : false);
     return {
         path,
         filename: basename(path),
         createdAt: stored?.createdAt ?? null,
-        dataSignature: stored?.dataSignature ?? null,
+        dependencyCount: stored?.dependencies.length ?? null,
         key: stored?.key ?? null,
         sizeBytes: info.size,
         stale
     };
 };
-export const listContextPacks = async (vaultPath, dataSignature) => {
+export const listContextPacks = async (vaultPath, freshness) => {
     const directory = contextPacksDirectory(vaultPath);
     try {
         const entries = await readdir(directory, { withFileTypes: true });
         const paths = entries
             .filter((entry) => entry.isFile() && entry.name.endsWith('.json'))
             .map((entry) => join(directory, entry.name));
-        const summaries = await Promise.all(paths.map((path) => toContextPackSummary(path, dataSignature)));
+        const summaries = await Promise.all(paths.map((path) => toContextPackSummary(path, vaultPath, freshness)));
         return summaries.sort((left, right) => (right.createdAt ?? '').localeCompare(left.createdAt ?? '') || left.filename.localeCompare(right.filename));
     }
     catch (error) {
@@ -63,20 +100,20 @@ export const listContextPacks = async (vaultPath, dataSignature) => {
     }
 };
 export const clearContextPacks = async (vaultPath, options = {}) => {
-    const packs = await listContextPacks(vaultPath, options.dataSignature);
+    const packs = await listContextPacks(vaultPath, options.freshness);
     const removed = options.staleOnly ? packs.filter((pack) => pack.stale) : packs;
     const kept = options.staleOnly ? packs.filter((pack) => !pack.stale) : [];
     await Promise.all(removed.map((pack) => rm(pack.path, { force: true })));
     return { removed, kept };
 };
-export const readContextPack = async (vaultPath, key, dataSignature) => {
+export const readContextPack = async (vaultPath, key, freshness) => {
     const path = contextPackPath(vaultPath, key);
     try {
         const parsed = await readStoredContextPack(path);
         if (!parsed) {
             return { status: 'stale', path };
         }
-        if (parsed.dataSignature !== dataSignature) {
+        if (!(await isPackFresh(vaultPath, parsed, freshness, Date.now()))) {
             return { status: 'stale', path };
         }
         return {
@@ -88,7 +125,7 @@ export const readContextPack = async (vaultPath, key, dataSignature) => {
                 cache: {
                     storage: 'context-pack',
                     status: 'hit',
-                    dataSignature,
+                    dataSignature: parsed.volatileSignature,
                     path
                 }
             }
@@ -98,12 +135,14 @@ export const readContextPack = async (vaultPath, key, dataSignature) => {
         return { status: 'miss', path };
     }
 };
-export const writeContextPack = async (vaultPath, key, dataSignature, context) => {
+export const writeContextPack = async (vaultPath, key, context, meta) => {
     const path = contextPackPath(vaultPath, key);
+    const dependencies = await computeDependencies(vaultPath, context);
     const stored = {
-        version: 1,
+        version: storedPackVersion,
         createdAt: new Date().toISOString(),
-        dataSignature,
+        dependencies,
+        volatileSignature: meta.volatileSignature,
         key: normalizePackKey(key),
         context: {
             ...context,
@@ -111,7 +150,7 @@ export const writeContextPack = async (vaultPath, key, dataSignature, context) =
             cache: {
                 storage: 'context-pack',
                 status: 'refresh',
-                dataSignature,
+                dataSignature: meta.volatileSignature,
                 path
             }
         }