lat.md 0.6.0 → 0.7.1

package/dist/src/init-version.js

@@ -0,0 +1,49 @@
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+/**
+ * Bump this number whenever `lat init` setup changes in a way that
+ * requires users to re-run it (e.g. new hooks, AGENTS.md changes,
+ * MCP config changes).
+ */
+export const INIT_VERSION = 1;
+function cachePath(latDir) {
+    return join(latDir, '.cache', 'lat_init.json');
+}
+function readMeta(latDir) {
+    const p = cachePath(latDir);
+    if (!existsSync(p))
+        return null;
+    try {
+        return JSON.parse(readFileSync(p, 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+}
+export function readInitVersion(latDir) {
+    const meta = readMeta(latDir);
+    if (!meta)
+        return null;
+    return typeof meta.init_version === 'number' ? meta.init_version : null;
+}
+export function readFileHash(latDir, relPath) {
+    const meta = readMeta(latDir);
+    return meta?.file_hashes?.[relPath] ?? null;
+}
+export function contentHash(content) {
+    return createHash('sha256').update(content).digest('hex');
+}
+export function writeInitMeta(latDir, fileHashes) {
+    const cacheDir = join(latDir, '.cache');
+    mkdirSync(cacheDir, { recursive: true });
+    // Merge with existing hashes so we don't lose entries from agents
+    // that weren't selected this run
+    const existing = readMeta(latDir);
+    const mergedHashes = { ...existing?.file_hashes, ...fileHashes };
+    const data = {
+        init_version: INIT_VERSION,
+        file_hashes: mergedHashes,
+    };
+    writeFileSync(cachePath(latDir), JSON.stringify(data, null, 2) + '\n');
+}

package/dist/src/lattice.d.ts

@@ -7,7 +7,7 @@ export type Section = {
     children: Section[];
     startLine: number;
     endLine: number;
-    body: string;
+    firstParagraph: string;
 };
 export type Ref = {
     target: string;
@@ -19,7 +19,6 @@ export type LatFrontmatter = {
     requireCodeMention?: boolean;
 };
 export declare function parseFrontmatter(content: string): LatFrontmatter;
-export declare function stripFrontmatter(content: string): string;
 export declare function findLatticeDir(from?: string): string | null;
 export declare function findProjectRoot(from?: string): string | null;
 export declare function listLatticeFiles(latticeDir: string): Promise<string[]>;

package/dist/src/lattice.js

@@ -15,9 +15,6 @@ export function parseFrontmatter(content) {
     }
     return result;
 }
-export function stripFrontmatter(content) {
-    return content.replace(/^---\n[\s\S]*?\n---\n*/, '');
-}
 export function findLatticeDir(from) {
     let dir = resolve(from ?? process.cwd());
     while (true) {
@@ -69,7 +66,7 @@ function lastLine(content) {
     return lines[lines.length - 1] === '' ? lines.length - 1 : lines.length;
 }
 export function parseSections(filePath, content, projectRoot) {
-    const tree = parse(stripFrontmatter(content));
+    const tree = parse(content);
     const file = projectRoot
         ? relative(projectRoot, filePath).replace(/\.md$/, '')
         : basename(filePath, '.md');
@@ -98,7 +95,7 @@ export function parseSections(filePath, content, projectRoot) {
             children: [],
             startLine,
             endLine: 0,
-            body: '',
+            firstParagraph: '',
         };
         if (parent) {
             parent.children.push(section);
@@ -119,7 +116,7 @@ export function parseSections(filePath, content, projectRoot) {
             flat[i].endLine = fileLastLine;
         }
     }
-    // Extract body: first paragraph after each heading
+    // Extract firstParagraph: first paragraph after each heading
     const children = tree.children;
     let headingIdx = 0;
     for (let i = 0; i < children.length; i++) {
@@ -130,7 +127,7 @@ export function parseSections(filePath, content, projectRoot) {
                 if (children[j].type === 'heading')
                     break;
                 if (children[j].type === 'paragraph') {
-                    flat[headingIdx].body = inlineText(children[j]);
+                    flat[headingIdx].firstParagraph = inlineText(children[j]);
                     break;
                 }
             }
@@ -522,7 +519,7 @@ export function findSections(sections, query) {
     ];
 }
 export function extractRefs(filePath, content, projectRoot) {
-    const tree = parse(stripFrontmatter(content));
+    const tree = parse(content);
     const file = projectRoot
         ? relative(projectRoot, filePath).replace(/\.md$/, '')
         : basename(filePath, '.md');

package/dist/src/mcp/server.js

@@ -1,33 +1,18 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { z } from 'zod';
-import { dirname, join, relative } from 'node:path';
-import { findLatticeDir, loadAllSections, findSections, flattenSections, buildFileIndex, resolveRef, extractRefs, listLatticeFiles, } from '../lattice.js';
-import { scanCodeRefs } from '../code-refs.js';
-import { checkMd, checkCodeRefs, checkIndex } from '../cli/check.js';
-import { readFile } from 'node:fs/promises';
-function formatSection(s, projectRoot) {
-    const relPath = relative(process.cwd(), join(projectRoot, s.filePath));
-    const kind = s.id.includes('#') ? 'Section' : 'File';
-    const lines = [
-        `* ${kind}: [[${s.id}]]`,
-        `  Defined in ${relPath}:${s.startLine}-${s.endLine}`,
-    ];
-    if (s.body) {
-        const truncated = s.body.length > 200 ? s.body.slice(0, 200) + '...' : s.body;
-        lines.push('', `  > ${truncated}`);
-    }
-    return lines.join('\n');
-}
-function formatMatches(header, matches, projectRoot) {
-    const lines = [header, ''];
-    for (let i = 0; i < matches.length; i++) {
-        if (i > 0)
-            lines.push('');
-        lines.push(formatSection(matches[i].section, projectRoot) +
-            ` (${matches[i].reason})`);
-    }
-    return lines.join('\n');
+import { dirname } from 'node:path';
+import { findLatticeDir } from '../lattice.js';
+import { plainStyler } from '../context.js';
+import { locateCommand } from '../cli/locate.js';
+import { sectionCommand } from '../cli/section.js';
+import { searchCommand } from '../cli/search.js';
+import { expandCommand } from '../cli/expand.js';
+import { checkAllCommand } from '../cli/check.js';
+import { refsCommand } from '../cli/refs.js';
+function toMcp(result) {
+    const content = [{ type: 'text', text: result.output }];
+    return result.isError ? { content, isError: true } : { content };
 }
 export async function startMcpServer() {
     const latDir = findLatticeDir();
@@ -36,32 +21,20 @@ export async function startMcpServer() {
         process.exit(1);
     }
     const projectRoot = dirname(latDir);
+    const ctx = {
+        latDir,
+        projectRoot,
+        styler: plainStyler,
+        mode: 'mcp',
+    };
     const server = new McpServer({
         name: 'lat',
         version: '1.0.0',
     });
-    server.tool('lat_locate', 'Find sections by name (exact, fuzzy, subsequence matching)', { query: z.string().describe('Section name or id to search for') }, async ({ query }) => {
-        const sections = await loadAllSections(latDir);
-        const matches = findSections(sections, query.replace(/^\[\[|\]\]$/g, ''));
-        if (matches.length === 0) {
-            return {
-                content: [
-                    {
-                        type: 'text',
-                        text: `No sections matching "${query}"`,
-                    },
-                ],
-            };
-        }
-        return {
-            content: [
-                {
-                    type: 'text',
-                    text: formatMatches(`Sections matching "${query}":`, matches, projectRoot),
-                },
-            ],
-        };
-    });
+    server.tool('lat_locate', 'Find sections by name (exact, fuzzy, subsequence matching)', { query: z.string().describe('Section name or id to search for') }, async ({ query }) => toMcp(await locateCommand(ctx, query)));
+    server.tool('lat_section', 'Show a section with its content, outgoing wiki link targets, and incoming references', {
+        query: z.string().describe('Section id to look up (short or full form)'),
+    }, async ({ query }) => toMcp(await sectionCommand(ctx, query)));
     server.tool('lat_search', 'Semantic search across lat.md sections using embeddings', {
         query: z.string().describe('Search query in natural language'),
         limit: z
@@ -69,151 +42,9 @@ export async function startMcpServer() {
             .optional()
             .default(5)
             .describe('Max results (default 5)'),
-    }, async ({ query, limit }) => {
-        const { getLlmKey } = await import('../config.js');
-        let key;
-        try {
-            key = getLlmKey();
-        }
-        catch (err) {
-            return {
-                content: [{ type: 'text', text: err.message }],
-                isError: true,
-            };
-        }
-        if (!key) {
-            return {
-                content: [
-                    {
-                        type: 'text',
-                        text: 'No LLM key found. Provide a key via LAT_LLM_KEY, LAT_LLM_KEY_FILE, LAT_LLM_KEY_HELPER, or run `lat init`.',
-                    },
-                ],
-                isError: true,
-            };
-        }
-        const { detectProvider } = await import('../search/provider.js');
-        const { openDb, ensureSchema, closeDb } = await import('../search/db.js');
-        const { indexSections } = await import('../search/index.js');
-        const { searchSections } = await import('../search/search.js');
-        const provider = detectProvider(key);
-        const db = openDb(latDir);
-        try {
-            await ensureSchema(db, provider.dimensions);
-            await indexSections(latDir, db, provider, key);
-            const results = await searchSections(db, query, provider, key, limit);
-            if (results.length === 0) {
-                return {
-                    content: [{ type: 'text', text: 'No results found.' }],
-                };
-            }
-            const allSections = await loadAllSections(latDir);
-            const flat = flattenSections(allSections);
-            const byId = new Map(flat.map((s) => [s.id, s]));
-            const matched = results
-                .map((r) => byId.get(r.id))
-                .filter((s) => !!s)
-                .map((s) => ({ section: s, reason: 'semantic match' }));
-            return {
-                content: [
-                    {
-                        type: 'text',
-                        text: formatMatches(`Search results for "${query}":`, matched, projectRoot),
-                    },
-                ],
-            };
-        }
-        finally {
-            await closeDb(db);
-        }
-    });
-    server.tool('lat_prompt', 'Expand [[refs]] in text to resolved lat.md section paths with context', { text: z.string().describe('Text containing [[refs]] to expand') }, async ({ text }) => {
-        const WIKI_LINK_RE = /\[\[([^\]]+)\]\]/g;
-        const allSections = await loadAllSections(latDir);
-        const refs = [...text.matchAll(WIKI_LINK_RE)];
-        if (refs.length === 0) {
-            return {
-                content: [{ type: 'text', text }],
-            };
-        }
-        const resolved = new Map();
-        const errors = [];
-        for (const match of refs) {
-            const target = match[1];
-            if (resolved.has(target))
-                continue;
-            const matches = findSections(allSections, target);
-            if (matches.length >= 1) {
-                resolved.set(target, {
-                    target,
-                    best: matches[0],
-                    alternatives: matches.slice(1),
-                });
-            }
-            else {
-                errors.push(`No section found for [[${target}]]`);
-            }
-        }
-        if (errors.length > 0) {
-            return {
-                content: [{ type: 'text', text: errors.join('\n') }],
-                isError: true,
-            };
-        }
-        let output = text.replace(WIKI_LINK_RE, (_match, target) => {
-            const ref = resolved.get(target);
-            return `[[${ref.best.section.id}]]`;
-        });
-        output += '\n\n<lat-context>\n';
-        for (const ref of resolved.values()) {
-            const isExact = ref.best.reason === 'exact match' ||
-                ref.best.reason.startsWith('file stem expanded');
-            const all = isExact ? [ref.best] : [ref.best, ...ref.alternatives];
-            if (isExact) {
-                output += `* [[${ref.target}]] is referring to:\n`;
-            }
-            else {
-                output += `* [[${ref.target}]] might be referring to either of the following:\n`;
-            }
-            for (const m of all) {
-                const reason = isExact ? '' : ` (${m.reason})`;
-                const relPath = relative(process.cwd(), join(projectRoot, m.section.filePath));
-                output += `  * [[${m.section.id}]]${reason}\n`;
-                output += `    * ${relPath}:${m.section.startLine}-${m.section.endLine}\n`;
-                if (m.section.body) {
-                    output += `    * ${m.section.body}\n`;
-                }
-            }
-        }
-        output += '</lat-context>\n';
-        return {
-            content: [{ type: 'text', text: output }],
-        };
-    });
-    server.tool('lat_check', 'Validate all wiki links, code references, and directory indexes in lat.md', {}, async () => {
-        const md = await checkMd(latDir);
-        const code = await checkCodeRefs(latDir);
-        const indexErrors = await checkIndex(latDir);
-        const allErrors = [...md.errors, ...code.errors];
-        const lines = [];
-        for (const err of allErrors) {
-            lines.push(`${err.file}:${err.line}: ${err.message}`);
-        }
-        for (const err of indexErrors) {
-            lines.push(`${err.dir}: ${err.message}`);
-        }
-        const totalErrors = allErrors.length + indexErrors.length;
-        if (totalErrors === 0) {
-            return {
-                content: [{ type: 'text', text: 'All checks passed' }],
-            };
-        }
-        lines.push(`\n${totalErrors} error${totalErrors === 1 ? '' : 's'} found`);
-        return {
-            content: [{ type: 'text', text: lines.join('\n') }],
-            isError: true,
-        };
-    });
+    }, async ({ query, limit }) => toMcp(await searchCommand(ctx, query, { limit })));
+    server.tool('lat_expand', 'Expand [[refs]] in text to resolved lat.md section paths with context', { text: z.string().describe('Text containing [[refs]] to expand') }, async ({ text: input }) => toMcp(await expandCommand(ctx, input)));
+    server.tool('lat_check', 'Validate all wiki links, code references, and directory indexes in lat.md', {}, async () => toMcp(await checkAllCommand(ctx)));
     server.tool('lat_refs', 'Find sections that reference a given section via wiki links or @lat code comments', {
         query: z.string().describe('Section id to find references for'),
         scope: z
@@ -221,91 +52,7 @@ export async function startMcpServer() {
             .optional()
             .default('md')
             .describe('Where to search: md, code, or md+code'),
-    }, async ({ query, scope }) => {
-        const allSections = await loadAllSections(latDir);
-        const flat = flattenSections(allSections);
-        const sectionIds = new Set(flat.map((s) => s.id.toLowerCase()));
-        const fileIndex = buildFileIndex(allSections);
-        const { resolved } = resolveRef(query, sectionIds, fileIndex);
-        const q = resolved.toLowerCase();
-        const exactMatch = flat.find((s) => s.id.toLowerCase() === q);
-        if (!exactMatch) {
-            const matches = findSections(allSections, query);
-            if (matches.length > 0) {
-                const suggestions = matches
-                    .map((m) => `  * ${m.section.id} (${m.reason})`)
-                    .join('\n');
-                return {
-                    content: [
-                        {
-                            type: 'text',
-                            text: `No exact section "${query}" found. Did you mean:\n${suggestions}`,
-                        },
-                    ],
-                };
-            }
-            return {
-                content: [
-                    {
-                        type: 'text',
-                        text: `No section matching "${query}"`,
-                    },
-                ],
-            };
-        }
-        const targetId = exactMatch.id.toLowerCase();
-        const mdMatches = [];
-        const codeLines = [];
-        if (scope === 'md' || scope === 'md+code') {
-            const files = await listLatticeFiles(latDir);
-            const matchingFromSections = new Set();
-            for (const file of files) {
-                const content = await readFile(file, 'utf-8');
-                const fileRefs = extractRefs(file, content, projectRoot);
-                for (const ref of fileRefs) {
-                    const { resolved: refResolved } = resolveRef(ref.target, sectionIds, fileIndex);
-                    if (refResolved.toLowerCase() === targetId) {
-                        matchingFromSections.add(ref.fromSection.toLowerCase());
-                    }
-                }
-            }
-            if (matchingFromSections.size > 0) {
-                const referrers = flat.filter((s) => matchingFromSections.has(s.id.toLowerCase()));
-                for (const s of referrers) {
-                    mdMatches.push({ section: s, reason: 'wiki link' });
-                }
-            }
-        }
-        if (scope === 'code' || scope === 'md+code') {
-            const { refs: codeRefs } = await scanCodeRefs(projectRoot);
-            for (const ref of codeRefs) {
-                const { resolved: codeResolved } = resolveRef(ref.target, sectionIds, fileIndex);
-                if (codeResolved.toLowerCase() === targetId) {
-                    codeLines.push(`${ref.file}:${ref.line}`);
-                }
-            }
-        }
-        if (mdMatches.length === 0 && codeLines.length === 0) {
-            return {
-                content: [
-                    {
-                        type: 'text',
-                        text: `No references to "${exactMatch.id}" found`,
-                    },
-                ],
-            };
-        }
-        const parts = [];
-        if (mdMatches.length > 0) {
-            parts.push(formatMatches(`References to "${exactMatch.id}":`, mdMatches, projectRoot));
-        }
-        if (codeLines.length > 0) {
-            parts.push('Code references:\n' + codeLines.map((l) => `* ${l}`).join('\n'));
-        }
-        return {
-            content: [{ type: 'text', text: parts.join('\n\n') }],
-        };
-    });
+    }, async ({ query, scope }) => toMcp(await refsCommand(ctx, query, scope)));
     const transport = new StdioServerTransport();
     await server.connect(transport);
 }

package/dist/src/parser.js

@@ -1,9 +1,11 @@
 import { unified } from 'unified';
 import remarkParse from 'remark-parse';
 import remarkStringify from 'remark-stringify';
+import remarkFrontmatter from 'remark-frontmatter';
 import { wikiLinkSyntax, wikiLinkFromMarkdown, wikiLinkToMarkdown, } from './extensions/wiki-link/index.js';
 const processor = unified()
     .use(remarkParse)
+    .use(remarkFrontmatter)
     .use(remarkStringify)
     .data('micromarkExtensions', [wikiLinkSyntax()])
     .data('fromMarkdownExtensions', [wikiLinkFromMarkdown()])