@andespindola/brainlink 0.1.0-beta.167 → 0.1.0-beta.168

package/README.md

@@ -717,6 +717,21 @@ When the configured default vault is changed manually in config files, Brainlink
 Use `--global` to write to `$BRAINLINK_HOME/brainlink.config.json`, `--no-migrate` to skip migration, and `--no-index` to skip post-migration indexing.
 `config doctor` is dry-run by default; use `--fix` to apply safe config normalization and allowlist fixes.
 
+### `vaults`
+
+```bash
+blink vaults list
+blink vaults list --json
+blink vaults use /absolute/path/to/vault
+blink vaults use /absolute/path/to/vault --global
+blink vaults delete /absolute/path/to/vault --yes
+blink vaults delete /absolute/path/to/vault --yes --prune-config
+```
+
+Lists known vaults from the configured default, `allowedVaults`, and the built-in default at `$HOME/.brainlink/vault`.
+`vaults use` chooses the default vault without migrating memory; use `migrate-vault` or `config set-vault --migrate-from` when you want to copy Markdown memory between vaults.
+`vaults delete` only deletes local filesystem vaults, requires `--yes`, refuses bucket vaults, and refuses deleting the current default vault. Choose another default first with `vaults use`.
+
 ### `migrate-vault`
 
 ```bash

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

@@ -0,0 +1,182 @@
+import { readdir, readFile, rm, stat } from 'node:fs/promises';
+import { extname, isAbsolute, join } from 'node:path';
+import { doctorVault } from '../../application/analyze-vault.js';
+import { defaultBrainlinkConfig, loadBrainlinkConfig, loadRawConfig, writeRawConfig } from '../../infrastructure/config.js';
+import { assertVaultAllowed, isBucketVaultPath, resolveVaultPath } from '../../infrastructure/file-system-vault.js';
+import { print } from '../runtime.js';
+const excludedDirectories = new Set(['.git', 'node_modules', 'dist']);
+const resolveScope = (globalOption) => globalOption ? 'global' : 'local';
+const normalizeVaultPath = (vault) => assertVaultAllowed(vault, []);
+const uniqueValues = (values) => Array.from(new Set(values));
+const sameVault = (left, right) => normalizeVaultPath(left) === normalizeVaultPath(right);
+const isDirectory = async (path) => {
+    try {
+        return (await stat(path)).isDirectory();
+    }
+    catch {
+        return false;
+    }
+};
+const countMarkdownFiles = async (directory) => {
+    const entries = await readdir(directory, { withFileTypes: true });
+    const counts = await Promise.all(entries.map(async (entry) => {
+        const absolutePath = join(directory, entry.name);
+        if (entry.isDirectory()) {
+            return excludedDirectories.has(entry.name) ? 0 : countMarkdownFiles(absolutePath);
+        }
+        return entry.isFile() && extname(entry.name).toLowerCase() === '.md' ? 1 : 0;
+    }));
+    return counts.reduce((total, count) => total + count, 0);
+};
+const readIndexedDocumentCount = async (vaultPath) => {
+    try {
+        const raw = await readFile(join(vaultPath, '.brainlink', 'index.json'), 'utf8');
+        const parsed = JSON.parse(raw);
+        return Array.isArray(parsed.documents) ? parsed.documents.length : null;
+    }
+    catch {
+        return null;
+    }
+};
+const addCandidate = (state, path, source) => {
+    const normalized = normalizeVaultPath(path);
+    const current = state.get(normalized);
+    return new Map(state).set(normalized, {
+        path: normalized,
+        sources: uniqueValues([...(current?.sources ?? []), source])
+    });
+};
+const listVaultEntries = async () => {
+    const config = await loadBrainlinkConfig();
+    const candidates = [config.vault, ...config.allowedVaults, defaultBrainlinkConfig.vault].reduce((state, path, index) => addCandidate(state, path, index === 0 ? 'configured' : path === defaultBrainlinkConfig.vault ? 'default' : 'allowed'), new Map());
+    const entries = await Promise.all(Array.from(candidates.values()).map(async (candidate) => {
+        if (isBucketVaultPath(candidate.path)) {
+            return {
+                path: candidate.path,
+                sources: candidate.sources,
+                current: sameVault(candidate.path, config.vault),
+                kind: 'bucket',
+                exists: null,
+                markdownCount: null,
+                indexedDocumentCount: null
+            };
+        }
+        const path = resolveVaultPath(candidate.path);
+        const exists = await isDirectory(path);
+        return {
+            path,
+            sources: candidate.sources,
+            current: sameVault(path, config.vault),
+            kind: 'local',
+            exists,
+            markdownCount: exists ? await countMarkdownFiles(path) : null,
+            indexedDocumentCount: exists ? await readIndexedDocumentCount(path) : null
+        };
+    }));
+    return entries.sort((left, right) => Number(right.current) - Number(left.current) || left.path.localeCompare(right.path));
+};
+const removeVaultFromAllowedVaults = async (vaultPath) => {
+    const scopes = ['local', 'global'];
+    await Promise.all(scopes.map(async (scope) => {
+        const rawConfig = await loadRawConfig(scope);
+        const allowedVaults = Array.isArray(rawConfig.allowedVaults)
+            ? rawConfig.allowedVaults.filter((path) => typeof path === 'string')
+            : [];
+        const nextAllowedVaults = allowedVaults.filter((path) => !sameVault(path, vaultPath));
+        if (nextAllowedVaults.length === allowedVaults.length) {
+            return;
+        }
+        await writeRawConfig(scope, {
+            ...rawConfig,
+            allowedVaults: nextAllowedVaults
+        });
+    }));
+};
+export const registerVaultCommands = (program) => {
+    const vaultsCommand = program.command('vaults').description('list, choose and delete Brainlink vaults');
+    vaultsCommand
+        .command('list')
+        .option('--json', 'print machine-readable JSON')
+        .description('list known Brainlink vaults from config and defaults')
+        .action(async (options) => {
+        const config = await loadBrainlinkConfig();
+        const vaults = await listVaultEntries();
+        print(options.json, {
+            currentVault: config.vault,
+            vaults
+        }, () => vaults
+            .map((vault) => {
+            const status = vault.exists === null ? 'remote' : vault.exists ? 'exists' : 'missing';
+            const counts = vault.markdownCount === null
+                ? ''
+                : ` markdown=${vault.markdownCount} indexed=${vault.indexedDocumentCount ?? 'unknown'}`;
+            return `${vault.current ? '* ' : '  '}${vault.path} [${vault.sources.join(',')}; ${status}; ${vault.kind}]${counts}`;
+        })
+            .join('\n'));
+    });
+    vaultsCommand
+        .command('use <vault>')
+        .option('--global', 'write to global config in $BRAINLINK_HOME/brainlink.config.json')
+        .option('--no-allowlist', 'do not append the vault to allowedVaults in the target config file')
+        .option('--json', 'print machine-readable JSON')
+        .description('choose the default Brainlink vault without migrating memory')
+        .action(async (vault, options) => {
+        const scope = resolveScope(options.global);
+        const before = await loadBrainlinkConfig();
+        const targetVault = normalizeVaultPath(vault);
+        const rawConfig = await loadRawConfig(scope);
+        const shouldAllowlist = options.allowlist !== false;
+        const allowedVaults = Array.isArray(rawConfig.allowedVaults)
+            ? rawConfig.allowedVaults.filter((path) => typeof path === 'string')
+            : [];
+        const nextAllowedVaults = shouldAllowlist ? uniqueValues([...allowedVaults, targetVault]) : allowedVaults;
+        const configPath = await writeRawConfig(scope, {
+            ...rawConfig,
+            vault: targetVault,
+            allowedVaults: nextAllowedVaults
+        });
+        const doctor = await doctorVault(targetVault);
+        print(options.json, {
+            scope,
+            configPath,
+            previousVault: before.vault,
+            vault: targetVault,
+            doctor
+        }, () => `Default ${scope} vault set to ${targetVault} in ${configPath}.`);
+    });
+    vaultsCommand
+        .command('delete <vault>')
+        .option('--yes', 'confirm destructive vault deletion')
+        .option('--prune-config', 'remove the vault from allowedVaults after deletion')
+        .option('--json', 'print machine-readable JSON')
+        .description('delete a local filesystem vault after explicit confirmation')
+        .action(async (vault, options) => {
+        const config = await loadBrainlinkConfig();
+        const targetVault = normalizeVaultPath(vault);
+        if (isBucketVaultPath(targetVault)) {
+            throw new Error('Refusing to delete bucket vaults from the CLI. Remove bucket data with your storage provider tooling.');
+        }
+        const absoluteVault = resolveVaultPath(targetVault);
+        if (!isAbsolute(absoluteVault)) {
+            throw new Error(`Refusing to delete non-absolute vault path: ${absoluteVault}`);
+        }
+        if (sameVault(absoluteVault, config.vault)) {
+            throw new Error('Refusing to delete the current default vault. Choose another default with `blink vaults use <vault>` first.');
+        }
+        if (options.yes !== true) {
+            throw new Error('Refusing to delete vault without --yes.');
+        }
+        const existed = await isDirectory(absoluteVault);
+        if (existed) {
+            await rm(absoluteVault, { recursive: true, force: false });
+        }
+        if (options.pruneConfig) {
+            await removeVaultFromAllowedVaults(absoluteVault);
+        }
+        print(options.json, {
+            vault: absoluteVault,
+            deleted: existed,
+            prunedConfig: options.pruneConfig === true
+        }, () => `${existed ? 'Deleted' : 'Vault did not exist'}: ${absoluteVault}`);
+    });
+};

package/dist/cli/main.js

@@ -6,6 +6,7 @@ import { fileURLToPath } from 'node:url';
 import { registerAgentCommands } from './commands/agent-commands.js';
 import { registerConfigCommands } from './commands/config-commands.js';
 import { registerReadCommands } from './commands/read-commands.js';
+import { registerVaultCommands } from './commands/vault-commands.js';
 import { registerWriteCommands } from './commands/write-commands.js';
 const readPackageVersion = () => {
     const packagePath = join(dirname(fileURLToPath(import.meta.url)), '../../package.json');
@@ -24,6 +25,7 @@ program
 registerWriteCommands(program);
 registerReadCommands(program);
 registerConfigCommands(program);
+registerVaultCommands(program);
 registerAgentCommands(program);
 program.parseAsync().catch((error) => {
     const message = error instanceof Error ? error.message : String(error);

package/docs/AGENT_USAGE.md

@@ -385,6 +385,19 @@ blink config set-vault /absolute/path/to/vault --global
 
 `config set-vault` updates Brainlink config through CLI. By default it writes local `brainlink.config.json`, appends the vault to `allowedVaults`, and migrates markdown when the target is empty.
 
+### Manage Known Vaults
+
+```bash
+blink vaults list
+blink vaults use /absolute/path/to/vault
+blink vaults use /absolute/path/to/vault --global
+blink vaults delete /absolute/path/to/vault --yes
+```
+
+`vaults list` shows the configured default vault, allowlisted vaults and the built-in default vault, including local existence and Markdown/index counts when available.
+`vaults use` switches the default vault without migrating memory.
+`vaults delete` deletes only local filesystem vaults, requires `--yes`, and refuses deleting the current default vault.
+
 ### Migrate Vaults Explicitly
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@andespindola/brainlink",
-  "version": "0.1.0-beta.167",
+  "version": "0.1.0-beta.168",
   "description": "Local-first knowledge memory for agents with Markdown, backlinks, indexing and context retrieval.",
   "type": "module",
   "license": "MIT",