@andespindola/brainlink 1.0.5 → 1.0.7

package/dist/mcp/tools/maintenance-tools.js

@@ -0,0 +1,409 @@
+import { resolve } from 'node:path';
+import { z } from 'zod';
+import { getBrokenLinksReport, getOrphansReport, getStats, validateVault } from '../../application/analyze-vault.js';
+import { buildContextPackage } from '../../application/build-context.js';
+import { canonicalizeContextLinks } from '../../application/canonical-context-links.js';
+import { resolveDuplicateNotes, scanDuplicateNotes } from '../../application/dedupe-notes.js';
+import { indexVault } from '../../application/index-vault.js';
+import { closeSession, initializeProjectMemory } from '../../application/operational-workflows.js';
+import { repairBrokenLinks } from '../../application/repair-broken-links.js';
+import { sanitizeContextStrategy, sanitizeSearchMode } from '../../infrastructure/config.js';
+import { getBootstrapPolicy, getBootstrapSessionStatus, getContextSessionStatus, setBootstrapPolicy, touchBootstrapSession, touchContextSession } from '../../infrastructure/session-state.js';
+import { getRuntimeMetadata } from '../runtime.js';
+import { agentInput, contextStrategyInput, ensureBootstrapReady, ensureContextReady, isTruthy, jsonResult, optionalPositiveInteger, positiveInteger, resolveExecutionContext, searchModeInput, vaultInput, withNextActions } from './shared.js';
+export const canonicalizeContextLinksInputSchema = {
+    ...vaultInput,
+    ...agentInput,
+    dryRun: z.boolean().optional().default(false).describe('Preview canonical context-link writes without changing Markdown.'),
+    createHubs: z.boolean().optional().default(true).describe('Create missing context hub notes when needed.'),
+    autoIndex: z.boolean().optional().default(true).describe('Reindex after canonicalization when files changed.')
+};
+export const indexInputSchema = {
+    ...vaultInput,
+    full: z
+        .boolean()
+        .optional()
+        .default(false)
+        .describe('Force a complete reindex from Markdown source without reusing unchanged index entries.')
+};
+export const repairLinksInputSchema = {
+    ...vaultInput,
+    ...agentInput,
+    dryRun: z.boolean().optional().default(false).describe('Preview repairs without writing files.'),
+    createMissing: z.boolean().optional().default(true).describe('Create placeholder notes for unresolved targets without a safe existing match.'),
+    autoIndex: z.boolean().optional().default(true).describe('Reindex vault after repairs.'),
+    minScore: z.number().min(0).max(1).optional().default(0.88).describe('Minimum similarity score for automatic retargeting.'),
+    margin: z.number().min(0).max(1).optional().default(0.12).describe('Minimum score gap between first and second candidate.')
+};
+export const syncInputSchema = {
+    ...vaultInput,
+    ...agentInput,
+    contextQuery: z.string().min(1).optional().describe('Optional context smoke query. Omit to skip context probe.'),
+    mode: z.enum(['fts', 'semantic', 'hybrid']).optional().describe('Search mode for the optional context probe. Defaults to config value.'),
+    strategy: z.enum(['rag', 'cag', 'auto']).optional().describe('Context strategy for the optional context probe. Defaults to the Brainlink config value.'),
+    contextLimit: optionalPositiveInteger().describe('Context smoke result limit when contextQuery is provided.'),
+    contextTokens: optionalPositiveInteger().describe('Context smoke token target when contextQuery is provided.')
+};
+export const bootstrapInputSchema = {
+    ...vaultInput,
+    ...agentInput,
+    ...searchModeInput,
+    ...contextStrategyInput,
+    query: z
+        .string()
+        .min(1)
+        .optional()
+        .describe('Optional task query. When provided, Brainlink also returns a context package in the same call.'),
+    limit: optionalPositiveInteger().describe('Context limit used when query is provided.'),
+    tokens: optionalPositiveInteger().describe('Context token target used when query is provided.')
+};
+export const policyInputSchema = {
+    ...vaultInput,
+    ...agentInput,
+    preset: z.enum(['fully-auto', 'strict']).optional().describe('Apply an opinionated policy preset before explicit overrides.'),
+    enforceBootstrap: z.boolean().optional().describe('Enable or disable bootstrap enforcement for MCP read tools.'),
+    enforceContextFirst: z.boolean().optional().describe('Require brainlink_context before other MCP read tools.'),
+    autoBootstrapOnRead: z
+        .boolean()
+        .optional()
+        .describe('When bootstrap is missing/stale, run automatic bootstrap on read tools instead of returning preflight-required responses.'),
+    autoBootstrapOnStartup: z
+        .boolean()
+        .optional()
+        .describe('Run automatic bootstrap during MCP server startup using configured default vault/agent.'),
+    staleAfterMinutes: positiveInteger(120).describe('Bootstrap freshness window in minutes before read tools require a new bootstrap.')
+};
+export const sessionCloseInputSchema = {
+    ...vaultInput,
+    ...agentInput,
+    content: z.string().min(1).optional().describe('Optional extra session notes to include in the handoff.'),
+    cwd: z.string().min(1).optional().describe('Workspace path used for git status. Defaults to current process working directory.'),
+    dryRun: z.boolean().optional().default(false).describe('Preview handoff note without writing it.'),
+    autoIndex: z.boolean().optional().default(true).describe('Reindex vault after writing handoff.')
+};
+export const projectInitInputSchema = {
+    ...vaultInput,
+    ...agentInput,
+    projectPath: z.string().min(1).optional().describe('Project path to inspect. Defaults to current process working directory.')
+};
+export const dedupeInputSchema = {
+    ...vaultInput,
+    ...agentInput,
+    limit: optionalPositiveInteger().describe('Maximum duplicate candidate pairs to return.'),
+    minScore: z.number().min(0).max(1).optional().describe('Minimum semantic similarity score between 0 and 1.'),
+    semantic: z.boolean().optional().default(true).describe('Enable semantic duplicate detection in addition to exact content hash matches.')
+};
+export const dedupeResolveInputSchema = {
+    ...vaultInput,
+    leftPath: z.string().min(1).describe('Left note path from dedupe results.'),
+    rightPath: z.string().min(1).describe('Right note path from dedupe results.'),
+    action: z.enum(['merge', 'link', 'ignore']).describe('Resolution action.'),
+    autoIndex: z.boolean().optional().default(true).describe('Reindex after duplicate resolution.')
+};
+export const canonicalizeContextLinksTool = async (input) => {
+    const context = await resolveExecutionContext(input);
+    const result = await canonicalizeContextLinks(context.vault, {
+        agentId: context.agent,
+        dryRun: input.dryRun === true,
+        createMissingHubs: input.createHubs !== false
+    });
+    const index = input.autoIndex !== false && !result.dryRun && result.changed > 0
+        ? await indexVault(context.vault, { full: true })
+        : undefined;
+    return jsonResult({
+        vault: context.vault,
+        agent: context.agent,
+        ...result,
+        ...(index ? { index } : {})
+    });
+};
+export const indexTool = async (input) => {
+    const context = await resolveExecutionContext(input);
+    const result = await indexVault(context.vault, {
+        full: input.full === true
+    });
+    return jsonResult({
+        vault: context.vault,
+        ...result
+    });
+};
+export const repairLinksTool = async (input) => {
+    const context = await resolveExecutionContext(input);
+    const result = await repairBrokenLinks(context.vault, {
+        agentId: context.agent,
+        dryRun: input.dryRun,
+        createMissing: input.createMissing,
+        autoIndex: input.autoIndex,
+        minScore: input.minScore,
+        margin: input.margin
+    });
+    return jsonResult({
+        vault: context.vault,
+        agent: context.agent,
+        ...result
+    });
+};
+export const syncTool = async (input) => {
+    const context = await resolveExecutionContext(input);
+    const readiness = await ensureBootstrapReady(context, input, 'brainlink_sync');
+    if (readiness.preflight) {
+        return readiness.preflight;
+    }
+    const contextReadiness = await ensureContextReady(context, input, 'brainlink_sync');
+    if (contextReadiness.preflight) {
+        return contextReadiness.preflight;
+    }
+    const index = await indexVault(context.vault);
+    const stats = await getStats(context.vault, context.agent);
+    const validation = await validateVault(context.vault, context.agent);
+    const brokenLinks = await getBrokenLinksReport(context.vault, context.agent);
+    const orphans = await getOrphansReport(context.vault, context.agent);
+    const response = {
+        vault: context.vault,
+        agent: context.agent,
+        ...(readiness.bootstrap ? { bootstrap: readiness.bootstrap } : {}),
+        ...(contextReadiness.context ? { contextReadiness: contextReadiness.context } : {}),
+        index,
+        stats,
+        validation,
+        brokenLinks,
+        orphans
+    };
+    if (!input.contextQuery) {
+        return jsonResult(response);
+    }
+    const mode = sanitizeSearchMode(input.mode, context.defaults.defaultSearchMode);
+    const strategy = sanitizeContextStrategy(input.strategy, context.defaults.defaultContextStrategy);
+    const contextLimit = input.contextLimit ?? context.defaults.defaultSearchLimit;
+    const contextTokens = input.contextTokens ?? context.defaults.defaultContextTokens;
+    const contextPackage = await buildContextPackage(context.vault, input.contextQuery, contextLimit, contextTokens, context.agent, mode, strategy, context.defaults.defaultContextCacheTtlMs);
+    const contextSession = await touchContextSession(context.vault, context.agent);
+    return jsonResult({
+        ...response,
+        context: {
+            mode,
+            strategy,
+            contextSession,
+            ...contextPackage
+        }
+    });
+};
+export const bootstrapTool = async (input) => {
+    const context = await resolveExecutionContext(input);
+    const index = await indexVault(context.vault);
+    const stats = await getStats(context.vault, context.agent);
+    const validation = await validateVault(context.vault, context.agent);
+    const mode = sanitizeSearchMode(input.mode, context.defaults.defaultSearchMode);
+    const strategy = sanitizeContextStrategy(input.strategy, context.defaults.defaultContextStrategy);
+    const limit = input.limit ?? context.defaults.defaultSearchLimit;
+    const tokens = input.tokens ?? context.defaults.defaultContextTokens;
+    const contextPackage = input.query
+        ? await buildContextPackage(context.vault, input.query, limit, tokens, context.agent, mode, strategy, context.defaults.defaultContextCacheTtlMs)
+        : undefined;
+    const contextSession = input.query ? await touchContextSession(context.vault, context.agent) : undefined;
+    const guidance = stats.documentCount === 0
+        ? 'Vault indexed with zero documents. Add durable notes with brainlink_add_note, then run brainlink_bootstrap again.'
+        : input.query
+            ? 'Use returned context as grounding baseline, then write durable updates with brainlink_add_note when needed.'
+            : 'Run brainlink_context with the current task query to retrieve grounded context before answering.';
+    const session = await touchBootstrapSession(context.vault, context.agent);
+    const policy = await getBootstrapPolicy();
+    const nextActions = stats.documentCount === 0
+        ? [
+            {
+                tool: 'brainlink_add_note',
+                reason: 'No indexed documents were found. Add durable Markdown memory first.',
+                args: {
+                    vault: context.vault,
+                    ...(context.agent ? { agent: context.agent } : {}),
+                    title: 'Architecture',
+                    content: 'Durable memory with explicit [[links]] and #tags.'
+                }
+            },
+            {
+                tool: 'brainlink_bootstrap',
+                reason: 'Re-run bootstrap after writing notes so context tools can work on fresh index state.',
+                args: {
+                    vault: context.vault,
+                    ...(context.agent ? { agent: context.agent } : {}),
+                    mode
+                }
+            }
+        ]
+        : input.query
+            ? [
+                {
+                    tool: 'brainlink_add_note',
+                    reason: 'Persist relevant outcomes from this task as durable memory.',
+                    args: {
+                        vault: context.vault,
+                        ...(context.agent ? { agent: context.agent } : {}),
+                        title: 'Task Update',
+                        content: 'Summarize durable findings and connect with [[existing notes]].'
+                    }
+                }
+            ]
+            : [
+                {
+                    tool: 'brainlink_context',
+                    reason: 'Fetch grounded context for the current task.',
+                    args: {
+                        vault: context.vault,
+                        ...(context.agent ? { agent: context.agent } : {}),
+                        query: '<task>',
+                        mode,
+                        strategy,
+                        limit,
+                        tokens
+                    }
+                }
+            ];
+    return jsonResult(withNextActions({
+        vault: context.vault,
+        agent: context.agent,
+        mode,
+        strategy,
+        limit,
+        tokens,
+        index,
+        stats,
+        validation,
+        policy,
+        session,
+        guidance,
+        ...(contextPackage ? { context: contextPackage } : {}),
+        ...(contextSession ? { contextSession } : {})
+    }, nextActions));
+};
+export const policyTool = async (input) => {
+    const context = await resolveExecutionContext(input);
+    const presetPatch = input.preset === 'strict'
+        ? {
+            enforceBootstrap: true,
+            enforceContextFirst: true,
+            autoBootstrapOnRead: false,
+            autoBootstrapOnStartup: false
+        }
+        : input.preset === 'fully-auto'
+            ? {
+                enforceBootstrap: true,
+                enforceContextFirst: true,
+                autoBootstrapOnRead: true,
+                autoBootstrapOnStartup: true
+            }
+            : {};
+    const policy = input.preset !== undefined ||
+        typeof input.enforceBootstrap === 'boolean' ||
+        typeof input.enforceContextFirst === 'boolean' ||
+        typeof input.autoBootstrapOnRead === 'boolean' ||
+        typeof input.autoBootstrapOnStartup === 'boolean' ||
+        typeof input.staleAfterMinutes === 'number'
+        ? await setBootstrapPolicy({
+            ...presetPatch,
+            ...(typeof input.enforceBootstrap === 'boolean' ? { enforceBootstrap: input.enforceBootstrap } : {}),
+            ...(typeof input.enforceContextFirst === 'boolean' ? { enforceContextFirst: input.enforceContextFirst } : {}),
+            ...(typeof input.autoBootstrapOnRead === 'boolean' ? { autoBootstrapOnRead: input.autoBootstrapOnRead } : {}),
+            ...(typeof input.autoBootstrapOnStartup === 'boolean' ? { autoBootstrapOnStartup: input.autoBootstrapOnStartup } : {}),
+            ...(typeof input.staleAfterMinutes === 'number' ? { staleAfterMinutes: input.staleAfterMinutes } : {})
+        })
+        : await getBootstrapPolicy();
+    const bootstrapStatus = await getBootstrapSessionStatus(context.vault, context.agent);
+    const contextStatus = await getContextSessionStatus(context.vault, context.agent);
+    const nextActions = bootstrapStatus.ready
+        ? []
+        : [
+            {
+                tool: 'brainlink_bootstrap',
+                reason: 'Bootstrap status is not ready. Run bootstrap before using read tools.',
+                args: {
+                    vault: context.vault,
+                    ...(context.agent ? { agent: context.agent } : {}),
+                    mode: context.defaults.defaultSearchMode,
+                    strategy: context.defaults.defaultContextStrategy
+                }
+            }
+        ];
+    const withContextAction = policy.enforceContextFirst && !contextStatus.ready
+        ? [
+            ...nextActions,
+            {
+                tool: 'brainlink_context',
+                reason: 'Context-first policy is enabled. Load context before other read tools.',
+                args: {
+                    vault: context.vault,
+                    ...(context.agent ? { agent: context.agent } : {}),
+                    query: '<task>',
+                    mode: context.defaults.defaultSearchMode,
+                    strategy: context.defaults.defaultContextStrategy,
+                    limit: context.defaults.defaultSearchLimit,
+                    tokens: context.defaults.defaultContextTokens
+                }
+            }
+        ]
+        : nextActions;
+    return jsonResult(withNextActions({
+        vault: context.vault,
+        agent: context.agent,
+        runtime: getRuntimeMetadata(),
+        policy,
+        bootstrapStatus,
+        contextStatus,
+        ...(input.preset ? { presetApplied: input.preset } : {})
+    }, withContextAction));
+};
+export const sessionCloseTool = async (input) => {
+    const context = await resolveExecutionContext(input);
+    const result = await closeSession({
+        vaultPath: context.vault,
+        agentId: context.agent,
+        cwd: resolve(input.cwd ?? process.cwd()),
+        content: input.content,
+        write: input.dryRun !== true,
+        autoIndex: input.autoIndex
+    });
+    return jsonResult({
+        vault: context.vault,
+        agent: context.agent,
+        dryRun: input.dryRun === true,
+        ...result
+    });
+};
+export const projectInitTool = async (input) => {
+    const context = await resolveExecutionContext(input);
+    const result = await initializeProjectMemory({
+        vaultPath: context.vault,
+        projectPath: resolve(input.projectPath ?? process.cwd()),
+        agentId: context.agent
+    });
+    return jsonResult({
+        agent: context.agent,
+        ...result
+    });
+};
+export const dedupeTool = async (input) => {
+    const context = await resolveExecutionContext(input);
+    const duplicates = await scanDuplicateNotes(context.vault, {
+        agentId: context.agent,
+        limit: input.limit ?? 25,
+        minSemanticScore: input.minScore ?? 0.92,
+        includeSemantic: input.semantic !== false
+    });
+    return jsonResult({
+        vault: context.vault,
+        agent: context.agent,
+        duplicates
+    });
+};
+export const dedupeResolveTool = async (input) => {
+    const context = await resolveExecutionContext(input);
+    const result = await resolveDuplicateNotes(context.vault, {
+        leftPath: input.leftPath,
+        rightPath: input.rightPath,
+        action: input.action,
+        autoIndex: isTruthy(input.autoIndex)
+    });
+    return jsonResult({
+        vault: context.vault,
+        ...result
+    });
+};