sanook-cli 0.5.1 → 0.5.5

package/dist/brain-doctor.js

@@ -0,0 +1,318 @@
+import { readdir, readFile, stat } from 'node:fs/promises';
+import { join, posix, win32 } from 'node:path';
+import { appHomePath } from './brand.js';
+import { FOLDERS } from './brain.js';
+import { INDEX_PATH } from './search/store.js';
+export const BRAIN_HOT_FILES = [
+    'SANOOK.md',
+    'Shared/AI-Context-Index.md',
+    'Vault Structure Map.md',
+    'Shared/Operating-State/current-state.md',
+];
+const DEFAULT_INDEX_FRESHNESS_TOLERANCE_MS = 1000;
+const SKIP_DIRS = new Set(['.git', '.obsidian', 'node_modules']);
+function isRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function normalizeSlashes(path) {
+    return path.trim().replace(/\\/g, '/');
+}
+function normalizeFolderReference(path) {
+    const normalized = posix
+        .normalize(normalizeSlashes(path))
+        .replace(/^\/+/, '')
+        .replace(/\/+$/, '');
+    return normalized === '.' ? '' : normalized;
+}
+function isVaultRelativeFolderReference(path) {
+    const trimmed = path.trim();
+    const slashed = normalizeSlashes(trimmed);
+    const hasWindowsDriveSpecifier = /^[A-Za-z]:/.test(trimmed);
+    return (!posix.isAbsolute(slashed) &&
+        !win32.isAbsolute(trimmed) &&
+        !hasWindowsDriveSpecifier &&
+        !slashed.split('/').includes('..'));
+}
+function normalizeExpectedFolders(expectedFolders) {
+    const folders = new Set();
+    const invalid = new Set();
+    for (const dir of expectedFolders) {
+        const slashed = normalizeSlashes(dir);
+        if (!slashed)
+            continue;
+        const folder = normalizeFolderReference(dir);
+        if (!isVaultRelativeFolderReference(dir)) {
+            invalid.add(slashed.replace(/\/+$/, ''));
+            continue;
+        }
+        if (!folder)
+            continue;
+        folders.add(folder);
+    }
+    return { folders: [...folders], invalid: [...invalid] };
+}
+function extractFolderReferences(map) {
+    const references = new Set();
+    for (const match of map.matchAll(/`([^`]+)`/g)) {
+        if (!isVaultRelativeFolderReference(match[1]))
+            continue;
+        const normalized = normalizeFolderReference(match[1]);
+        if (normalized)
+            references.add(normalized);
+    }
+    return references;
+}
+async function fileExists(path) {
+    try {
+        return (await stat(path)).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+async function directoryExists(path) {
+    try {
+        return (await stat(path)).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+async function latestMarkdownMtimeMs(root) {
+    let latest = 0;
+    async function walk(dir) {
+        let entries;
+        try {
+            entries = await readdir(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (entry.isDirectory()) {
+                if (!SKIP_DIRS.has(entry.name))
+                    await walk(join(dir, entry.name));
+                continue;
+            }
+            if (!entry.isFile() || !entry.name.endsWith('.md'))
+                continue;
+            try {
+                latest = Math.max(latest, (await stat(join(dir, entry.name))).mtimeMs);
+            }
+            catch {
+                // File disappeared between readdir and stat; ignore the race.
+            }
+        }
+    }
+    await walk(root);
+    return latest;
+}
+export async function checkBrainHotFiles(brainPath) {
+    const missing = [];
+    for (const rel of BRAIN_HOT_FILES) {
+        if (!(await fileExists(join(brainPath, rel))))
+            missing.push(rel);
+    }
+    if (missing.length) {
+        return {
+            id: 'brain.hot-files',
+            status: 'fail',
+            message: `Missing ${missing.length} required second-brain file${missing.length === 1 ? '' : 's'}.`,
+            path: brainPath,
+            details: missing,
+        };
+    }
+    return {
+        id: 'brain.hot-files',
+        status: 'pass',
+        message: 'Required second-brain hot files are present.',
+        path: brainPath,
+    };
+}
+export async function checkBrainFolders(brainPath, expectedFolders = FOLDERS.map((f) => f.dir)) {
+    const expected = normalizeExpectedFolders(expectedFolders);
+    if (expected.invalid.length) {
+        return {
+            id: 'brain.folders',
+            status: 'fail',
+            message: `Invalid expected second-brain folder reference${expected.invalid.length === 1 ? '' : 's'}.`,
+            path: brainPath,
+            details: expected.invalid,
+        };
+    }
+    const missing = [];
+    for (const dir of expected.folders) {
+        if (!(await directoryExists(join(brainPath, dir))))
+            missing.push(dir);
+    }
+    if (missing.length) {
+        return {
+            id: 'brain.folders',
+            status: 'fail',
+            message: `Missing ${missing.length} expected second-brain folder${missing.length === 1 ? '' : 's'}.`,
+            path: brainPath,
+            details: missing,
+        };
+    }
+    return {
+        id: 'brain.folders',
+        status: 'pass',
+        message: 'Expected second-brain folders are present.',
+        path: brainPath,
+    };
+}
+export async function checkVaultStructureMap(brainPath, expectedFolders = FOLDERS.map((f) => f.dir)) {
+    const mapPath = join(brainPath, 'Vault Structure Map.md');
+    let map;
+    try {
+        map = await readFile(mapPath, 'utf8');
+    }
+    catch {
+        return {
+            id: 'brain.structure-map',
+            status: 'fail',
+            message: 'Vault Structure Map.md is missing or unreadable.',
+            path: mapPath,
+        };
+    }
+    const expected = normalizeExpectedFolders(expectedFolders);
+    if (expected.invalid.length) {
+        return {
+            id: 'brain.structure-map',
+            status: 'fail',
+            message: `Invalid expected second-brain folder reference${expected.invalid.length === 1 ? '' : 's'}.`,
+            path: mapPath,
+            details: expected.invalid,
+        };
+    }
+    const folderReferences = extractFolderReferences(map);
+    const missing = expected.folders.filter((dir) => !folderReferences.has(dir));
+    if (missing.length) {
+        return {
+            id: 'brain.structure-map',
+            status: 'fail',
+            message: `Vault Structure Map.md is missing ${missing.length} folder reference${missing.length === 1 ? '' : 's'}.`,
+            path: mapPath,
+            details: missing,
+        };
+    }
+    return {
+        id: 'brain.structure-map',
+        status: 'pass',
+        message: 'Vault Structure Map.md covers the expected folder manifest.',
+        path: mapPath,
+    };
+}
+export async function checkSearchIndexFreshness(brainPath, indexPath = INDEX_PATH, toleranceMs = DEFAULT_INDEX_FRESHNESS_TOLERANCE_MS) {
+    const latestVaultMtimeMs = await latestMarkdownMtimeMs(brainPath);
+    if (latestVaultMtimeMs === 0) {
+        return {
+            id: 'brain.search-index',
+            status: 'warn',
+            message: 'No markdown files were found in the configured second-brain vault.',
+            path: brainPath,
+        };
+    }
+    let indexMtimeMs = 0;
+    try {
+        indexMtimeMs = (await stat(indexPath)).mtimeMs;
+    }
+    catch {
+        return {
+            id: 'brain.search-index',
+            status: 'warn',
+            message: 'Search index is missing; run `sanook index` to build it.',
+            path: indexPath,
+        };
+    }
+    if (indexMtimeMs + toleranceMs < latestVaultMtimeMs) {
+        return {
+            id: 'brain.search-index',
+            status: 'warn',
+            message: 'Search index is older than the second-brain markdown files.',
+            path: indexPath,
+            details: [`index_mtime_ms=${Math.round(indexMtimeMs)}`, `vault_latest_mtime_ms=${Math.round(latestVaultMtimeMs)}`],
+        };
+    }
+    return {
+        id: 'brain.search-index',
+        status: 'pass',
+        message: 'Search index is present and fresh enough for the vault.',
+        path: indexPath,
+    };
+}
+export async function checkBrainMcpWiring(brainPath, mcpConfigPath = appHomePath('mcp.json')) {
+    let raw;
+    try {
+        raw = JSON.parse(await readFile(mcpConfigPath, 'utf8'));
+    }
+    catch {
+        return {
+            id: 'brain.mcp',
+            status: 'warn',
+            message: 'MCP config is missing or unreadable; `sanook brain init` can wire the vault.',
+            path: mcpConfigPath,
+        };
+    }
+    const servers = isRecord(raw) && isRecord(raw.mcpServers) ? raw.mcpServers : undefined;
+    const server = servers && isRecord(servers['second-brain']) ? servers['second-brain'] : undefined;
+    const args = server && Array.isArray(server.args) ? server.args : [];
+    if (!args.includes(brainPath)) {
+        return {
+            id: 'brain.mcp',
+            status: 'warn',
+            message: 'MCP server `second-brain` is not wired to the configured vault path.',
+            path: mcpConfigPath,
+        };
+    }
+    return {
+        id: 'brain.mcp',
+        status: 'pass',
+        message: 'MCP server `second-brain` points at the configured vault path.',
+        path: mcpConfigPath,
+    };
+}
+export async function checkBrain(options = {}) {
+    const checks = [];
+    const brainPath = options.brainPath;
+    if (!brainPath) {
+        checks.push({
+            id: 'brain.configured',
+            status: 'fail',
+            message: 'No second-brain path is configured.',
+        });
+        return { ok: false, checks };
+    }
+    try {
+        if (!(await stat(brainPath)).isDirectory()) {
+            checks.push({
+                id: 'brain.path',
+                status: 'fail',
+                message: 'Configured second-brain path is not a directory.',
+                path: brainPath,
+            });
+            return { ok: false, checks };
+        }
+    }
+    catch {
+        checks.push({
+            id: 'brain.path',
+            status: 'fail',
+            message: 'Configured second-brain path does not exist.',
+            path: brainPath,
+        });
+        return { ok: false, checks };
+    }
+    checks.push({
+        id: 'brain.path',
+        status: 'pass',
+        message: 'Configured second-brain path exists.',
+        path: brainPath,
+    });
+    checks.push(await checkBrainFolders(brainPath, options.expectedFolders));
+    checks.push(await checkBrainHotFiles(brainPath));
+    checks.push(await checkVaultStructureMap(brainPath, options.expectedFolders));
+    checks.push(await checkSearchIndexFreshness(brainPath, options.indexPath, options.indexFreshnessToleranceMs ?? DEFAULT_INDEX_FRESHNESS_TOLERANCE_MS));
+    checks.push(await checkBrainMcpWiring(brainPath, options.mcpConfigPath));
+    return { ok: !checks.some((check) => check.status === 'fail'), checks };
+}

package/dist/brain-eval.js

@@ -0,0 +1,186 @@
+import { readFile, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { FOLDERS } from './brain.js';
+import { validateFinalGateContent } from './brain-final.js';
+import { checkBrainFolders, checkSearchIndexFreshness, checkVaultStructureMap } from './brain-doctor.js';
+import { inspectBrainContext } from './brain-context.js';
+import { search } from './search/engine.js';
+import { INDEX_PATH } from './search/store.js';
+const STATIC_CASES = ['SB-01', 'SB-02', 'SB-03', 'SB-04', 'SB-05', 'SB-06', 'SB-07', 'SB-08', 'SB-09', 'SB-10'];
+const RETRIEVAL_CASES = [
+    { id: 'RET-01', query: 'memory write protocol merge dont append', expectedPath: 'Shared/Rules/memory-write-protocol.md' },
+    { id: 'RET-02', query: 'context assembly policy small context', expectedPath: 'Shared/Rules/context-assembly-policy.md' },
+    { id: 'RET-03', query: 'quality ledger retrieval hit grounded', expectedPath: 'Evals/quality-ledger.md' },
+];
+async function fileExists(path) {
+    try {
+        return (await stat(path)).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+async function readText(path) {
+    try {
+        return await readFile(path, 'utf8');
+    }
+    catch {
+        return '';
+    }
+}
+function caseResult(id, title, passed, evidence = [], details = [], partial = false) {
+    const status = passed ? 'pass' : partial ? 'partial' : 'fail';
+    return {
+        id,
+        title,
+        status,
+        score: status === 'pass' ? 1 : status === 'partial' ? 0.5 : 0,
+        maxScore: 1,
+        evidence,
+        details,
+    };
+}
+function summarize(cases, brainPath) {
+    const score = cases.reduce((sum, item) => sum + item.score, 0);
+    const maxScore = cases.reduce((sum, item) => sum + item.maxScore, 0);
+    const percent = maxScore ? (score / maxScore) * 100 : 0;
+    return { ok: cases.every((item) => item.status === 'pass'), brainPath, score, maxScore, percent, cases };
+}
+async function benchmarkFileCase(brainPath) {
+    const path = join(brainPath, 'Evals', 'second-brain-benchmarks.md');
+    const content = await readText(path);
+    if (!content)
+        return caseResult('SB-00', 'Benchmark file exists', false, [path]);
+    const missing = STATIC_CASES.filter((id) => !content.includes(id));
+    return caseResult('SB-00', 'Benchmark file exists and names static cases', missing.length === 0, [path], missing.length ? [`missing case ids: ${missing.join(', ')}`] : [], missing.length > 0 && missing.length < STATIC_CASES.length);
+}
+async function routingCase(brainPath) {
+    const folderCheck = await checkBrainFolders(brainPath);
+    const mapCheck = await checkVaultStructureMap(brainPath);
+    const missingIndexes = [];
+    for (const folder of FOLDERS) {
+        if (!(await fileExists(join(brainPath, folder.dir, '_Index.md'))))
+            missingIndexes.push(`${folder.dir}/_Index.md`);
+    }
+    const pass = folderCheck.status === 'pass' && mapCheck.status === 'pass' && missingIndexes.length === 0;
+    return caseResult('SB-02', 'Routing map and destination indexes are complete', pass, [join(brainPath, 'Vault Structure Map.md')], [...(folderCheck.details ?? []), ...(mapCheck.details ?? []), ...missingIndexes], folderCheck.status === 'pass' || mapCheck.status === 'pass');
+}
+async function requiredFilesCase(brainPath, id, title, relPaths, tokens = []) {
+    const missing = [];
+    const evidence = [];
+    const tokenMisses = [];
+    for (const rel of relPaths) {
+        const path = join(brainPath, rel);
+        const content = await readText(path);
+        if (!content) {
+            missing.push(rel);
+            continue;
+        }
+        evidence.push(path);
+        for (const token of tokens) {
+            if (!content.toLowerCase().includes(token.toLowerCase()))
+                tokenMisses.push(`${rel}: missing "${token}"`);
+        }
+    }
+    const details = [...missing.map((m) => `missing ${m}`), ...tokenMisses];
+    return caseResult(id, title, details.length === 0, evidence, details, evidence.length > 0 && missing.length < relPaths.length);
+}
+async function finalGateCase(brainPath) {
+    const relPaths = ['Templates/final.md', 'Templates/final-lite.md', 'Shared/Tech-Standards/verification-standard.md'];
+    const evidence = [];
+    const details = [];
+    for (const rel of relPaths) {
+        const path = join(brainPath, rel);
+        const content = await readText(path);
+        if (!content) {
+            details.push(`missing ${rel}`);
+            continue;
+        }
+        evidence.push(path);
+        if (!content.includes('If a row has no evidence'))
+            details.push(`${rel}: missing evidence rule`);
+    }
+    for (const rel of ['Templates/final.md', 'Templates/final-lite.md']) {
+        const content = await readText(join(brainPath, rel));
+        if (!content)
+            continue;
+        const validation = validateFinalGateContent(content.replace('note_type: template', 'note_type: final-gate'));
+        const structuralWarnings = validation.warnings.filter((warning) => warning.startsWith('Missing'));
+        details.push(...structuralWarnings.map((warning) => `${rel}: ${warning}`));
+    }
+    return caseResult('SB-FINAL', 'Final gate templates and validator contract exist', details.length === 0, evidence, details, evidence.length > 0);
+}
+async function contextCase(brainPath, indexPath) {
+    const report = await inspectBrainContext({ brainPath, indexPath });
+    const structuralWarnings = report.warnings.filter((warning) => !warning.includes('Search index is missing') && !warning.includes('Search index is older'));
+    return caseResult('SB-09', 'Hot context assembles without missing or oversized sources', report.ok && report.contextChars > 0 && structuralWarnings.length === 0, report.sources.map((source) => source.path), structuralWarnings, report.contextChars > 0);
+}
+async function indexCase(brainPath, indexPath) {
+    const check = await checkSearchIndexFreshness(brainPath, indexPath);
+    return caseResult('SB-IDX', 'Search index exists and is fresh enough', check.status === 'pass', [indexPath], check.status === 'pass' ? [] : [check.message, ...(check.details ?? [])], check.status === 'warn');
+}
+async function retrievalCase(brainPath, item, searchImpl) {
+    const res = await searchImpl(item.query, { mode: 'fts', limit: 5, sources: ['vault'] });
+    const hit = res.hits.find((candidate) => candidate.path === item.expectedPath);
+    return caseResult(item.id, `Retrieval finds ${item.expectedPath}`, !!hit, hit ? [join(brainPath, hit.path ?? item.expectedPath)] : [], hit ? [] : [`query="${item.query}" did not return ${item.expectedPath}`], res.hits.length > 0);
+}
+export async function runBrainEval(options = {}) {
+    const brainPath = options.brainPath;
+    if (!brainPath) {
+        return summarize([
+            caseResult('SB-CONFIG', 'Second-brain path is configured', false, [], ['Run `sanook brain init [path]` first.']),
+        ]);
+    }
+    try {
+        if (!(await stat(brainPath)).isDirectory()) {
+            return summarize([
+                caseResult('SB-CONFIG', 'Second-brain path is a directory', false, [brainPath], ['Configured brainPath is not a directory.']),
+            ], brainPath);
+        }
+    }
+    catch {
+        return summarize([
+            caseResult('SB-CONFIG', 'Second-brain path exists', false, [brainPath], ['Configured brainPath does not exist.']),
+        ], brainPath);
+    }
+    const indexPath = options.indexPath ?? INDEX_PATH;
+    const cases = [
+        await benchmarkFileCase(brainPath),
+        await requiredFilesCase(brainPath, 'SB-01', 'AI context entrypoint exists', ['Shared/AI-Context-Index.md'], ['Vault Structure Map']),
+        await routingCase(brainPath),
+        await requiredFilesCase(brainPath, 'SB-03', 'Memory write protocol is documented', ['Shared/Rules/memory-write-protocol.md'], ['ADD', 'UPDATE', 'DELETE', 'NOOP']),
+        await requiredFilesCase(brainPath, 'SB-04', 'External ingest quarantine/provenance path exists', ['Runbooks/ingest-quarantine.md', 'Shared/Provenance/ingest-log.md']),
+        await requiredFilesCase(brainPath, 'SB-05', 'Coding verification standard exists', ['Shared/Tech-Standards/verification-standard.md']),
+        await requiredFilesCase(brainPath, 'SB-06', 'Owner-facing response examples exist', ['Shared/User-Memory/response-examples.md']),
+        await requiredFilesCase(brainPath, 'SB-07', 'Framework improvement evidence paths exist', ['Evals/quality-ledger.md', 'Research/_Index.md', 'Sessions/_Index.md']),
+        await requiredFilesCase(brainPath, 'SB-08', 'Multi-agent coordination paths exist', ['Shared/Coordination/task-board.md', 'Shared/Coordination/task-board/_Index.md']),
+        await contextCase(brainPath, indexPath),
+        await requiredFilesCase(brainPath, 'SB-10', 'Learning loop ledger and session index exist', ['Evals/quality-ledger.md', 'Sessions/_Index.md']),
+        await finalGateCase(brainPath),
+        await indexCase(brainPath, indexPath),
+    ];
+    if (options.runRetrieval !== false) {
+        const searchImpl = options.searchImpl ?? search;
+        for (const item of RETRIEVAL_CASES)
+            cases.push(await retrievalCase(brainPath, item, searchImpl));
+    }
+    return summarize(cases, brainPath);
+}
+function statusLabel(status) {
+    return status.toUpperCase().padEnd(7);
+}
+export function formatBrainEvalReport(report) {
+    const lines = [
+        'Sanook brain eval',
+        `vault: ${report.brainPath ?? '(not configured)'}`,
+        `score: ${report.score.toFixed(1)}/${report.maxScore} (${report.percent.toFixed(1)}%)`,
+    ];
+    for (const item of report.cases) {
+        lines.push(`[${statusLabel(item.status)}] ${item.id} — ${item.title}`);
+        for (const evidence of item.evidence ?? [])
+            lines.push(`       ${evidence}`);
+        for (const detail of item.details ?? [])
+            lines.push(`       - ${detail}`);
+    }
+    return lines.join('\n');
+}