@plebeiantech/lat.md 0.12.3-fork.1

package/dist/src/mcp/server.d.ts

@@ -0,0 +1 @@
+export declare function startMcpServer(): Promise<void>;

package/dist/src/mcp/server.js

@@ -0,0 +1,58 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+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();
+    if (!latDir) {
+        process.stderr.write('No lat.md directory found\n');
+        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 }) => 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
+            .number()
+            .optional()
+            .default(5)
+            .describe('Max results (default 5)'),
+    }, 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', 'Run full lat.md validation: links, code references, indexes, and section structure', {}, 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
+            .enum(['md', 'code', 'md+code'])
+            .optional()
+            .default('md+code')
+            .describe('Where to search: md, code, or md+code'),
+    }, async ({ query, scope }) => toMcp(await refsCommand(ctx, query, scope)));
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}

package/dist/src/parser.d.ts

@@ -0,0 +1,3 @@
+import type { Root } from 'mdast';
+export declare function parse(markdown: string): Root;
+export declare function toMarkdown(tree: Root): string;

package/dist/src/parser.js

@@ -0,0 +1,18 @@
+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()])
+    .data('toMarkdownExtensions', [wikiLinkToMarkdown()]);
+export function parse(markdown) {
+    return processor.parse(markdown);
+}
+export function toMarkdown(tree) {
+    return processor.stringify(tree);
+}

package/dist/src/search/db.d.ts

@@ -0,0 +1,16 @@
+import { type Client } from '@libsql/client';
+export declare function openDb(latDir: string): Client;
+/** Create the `meta` key/value table if absent. */
+export declare function ensureMeta(db: Client): Promise<void>;
+/**
+ * The embedding backend this index was built with, e.g. `local:minilm-l6-v2:384`
+ * or `openai:1536`. This record is *authoritative*: it governs which backend
+ * `lat search` uses. Null when the index has never been built.
+ */
+export declare function getStoredModel(db: Client): Promise<string | null>;
+export declare function setStoredModel(db: Client, value: string): Promise<void>;
+/** Create the `sections` table (fixed-width vector column) + index if absent. */
+export declare function ensureSectionsSchema(db: Client, dimensions: number): Promise<void>;
+/** Drop the vector table (used by `lat reindex` before a full rebuild). */
+export declare function dropSections(db: Client): Promise<void>;
+export declare function closeDb(db: Client): Promise<void>;

package/dist/src/search/db.js

@@ -0,0 +1,54 @@
+import { createClient } from '@libsql/client';
+import { mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+export function openDb(latDir) {
+    const cacheDir = join(latDir, '.cache');
+    mkdirSync(cacheDir, { recursive: true });
+    const client = createClient({
+        url: `file:${join(cacheDir, 'vectors.db')}`,
+    });
+    return client;
+}
+/** Create the `meta` key/value table if absent. */
+export async function ensureMeta(db) {
+    await db.execute(`CREATE TABLE IF NOT EXISTS meta (
+      key TEXT PRIMARY KEY,
+      value TEXT NOT NULL
+    )`);
+}
+/**
+ * The embedding backend this index was built with, e.g. `local:minilm-l6-v2:384`
+ * or `openai:1536`. This record is *authoritative*: it governs which backend
+ * `lat search` uses. Null when the index has never been built.
+ */
+export async function getStoredModel(db) {
+    const rows = await db.execute("SELECT value FROM meta WHERE key = 'embedding_model'");
+    return rows.rows[0]?.value ?? null;
+}
+export async function setStoredModel(db, value) {
+    await db.execute({
+        sql: "INSERT OR REPLACE INTO meta (key, value) VALUES ('embedding_model', ?)",
+        args: [value],
+    });
+}
+/** Create the `sections` table (fixed-width vector column) + index if absent. */
+export async function ensureSectionsSchema(db, dimensions) {
+    await db.execute(`CREATE TABLE IF NOT EXISTS sections (
+      id TEXT PRIMARY KEY,
+      file TEXT NOT NULL,
+      heading TEXT NOT NULL,
+      content TEXT NOT NULL,
+      content_hash TEXT NOT NULL,
+      embedding F32_BLOB(${dimensions}),
+      updated_at INTEGER NOT NULL
+    )`);
+    await db.execute(`CREATE INDEX IF NOT EXISTS sections_vec_idx
+     ON sections (libsql_vector_idx(embedding))`);
+}
+/** Drop the vector table (used by `lat reindex` before a full rebuild). */
+export async function dropSections(db) {
+    await db.execute('DROP TABLE IF EXISTS sections');
+}
+export async function closeDb(db) {
+    db.close();
+}

package/dist/src/search/embedder.d.ts

@@ -0,0 +1,25 @@
+import { EmbeddingAuthError, type Embedder } from '@lat.md/embed';
+export type { Embedder };
+export { EmbeddingAuthError };
+/** `meta.embedding_model` value for an embedder, e.g. `local:minilm-l6-v2:384`. */
+export declare function modelKey(embedder: Embedder): string;
+/** Thrown when the stored index can't be served by the current environment and
+ *  a `lat reindex` is required (wrong/absent key, or model mismatch). */
+export declare class ReindexRequiredError extends Error {
+    constructor(message: string);
+}
+/** Build an embedder from the environment (key → remote, else local). Used for
+ *  a fresh index and by `lat reindex` when re-deciding the backend. */
+export declare function embedderFromEnv(): Promise<Embedder>;
+/** Local (offline) embedder, ignoring any configured key. */
+export declare function localEmbedder(): Promise<Embedder>;
+/**
+ * Resolve the embedder `lat search` must use, given the index's recorded model
+ * and the repo dir. The stored model is authoritative — the env var never
+ * silently flips the backend. A local index ignores the key; a remote index
+ * requires a matching key (used to embed every query) or throws
+ * {@link ReindexRequiredError}. On a fresh index (no stored model — e.g. the
+ * regenerable `.cache` was wiped) the durable per-repo preference wins over the
+ * env, so a repo switched to local stays local across cache loss.
+ */
+export declare function embedderForIndex(storedModel: string | null, latDir: string): Promise<Embedder>;

package/dist/src/search/embedder.js

@@ -0,0 +1,58 @@
+import { createEmbedder, EmbeddingAuthError, } from '@lat.md/embed';
+import minilm from '@lat.md/embed-minilm-fp16';
+import { getLlmKey, getRepoEmbedding } from '../config.js';
+export { EmbeddingAuthError };
+/** `meta.embedding_model` value for an embedder, e.g. `local:minilm-l6-v2:384`. */
+export function modelKey(embedder) {
+    return `${embedder.name}:${embedder.dimensions}`;
+}
+/** Thrown when the stored index can't be served by the current environment and
+ *  a `lat reindex` is required (wrong/absent key, or model mismatch). */
+export class ReindexRequiredError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ReindexRequiredError';
+    }
+}
+/** Build an embedder from the environment (key → remote, else local). Used for
+ *  a fresh index and by `lat reindex` when re-deciding the backend. */
+export async function embedderFromEnv() {
+    const key = getLlmKey();
+    return key ? createEmbedder({ key }) : createEmbedder({ model: minilm });
+}
+/** Local (offline) embedder, ignoring any configured key. */
+export function localEmbedder() {
+    return createEmbedder({ model: minilm });
+}
+/**
+ * Resolve the embedder `lat search` must use, given the index's recorded model
+ * and the repo dir. The stored model is authoritative — the env var never
+ * silently flips the backend. A local index ignores the key; a remote index
+ * requires a matching key (used to embed every query) or throws
+ * {@link ReindexRequiredError}. On a fresh index (no stored model — e.g. the
+ * regenerable `.cache` was wiped) the durable per-repo preference wins over the
+ * env, so a repo switched to local stays local across cache loss.
+ */
+export async function embedderForIndex(storedModel, latDir) {
+    if (storedModel === null) {
+        if (getRepoEmbedding(latDir) === 'local')
+            return localEmbedder();
+        // No durable preference — decide from the environment, record it later.
+        return embedderFromEnv();
+    }
+    if (storedModel.startsWith('local:')) {
+        return localEmbedder(); // ignores LAT_LLM_KEY entirely
+    }
+    // Remote-pinned index: needs a key that resolves to the same model.
+    const key = getLlmKey();
+    if (!key) {
+        throw new ReindexRequiredError(`This index was built with '${storedModel}', but no LAT_LLM_KEY is set. ` +
+            `Run 'lat reindex' to switch to the local model or restore the key.`);
+    }
+    const embedder = await createEmbedder({ key });
+    if (modelKey(embedder) !== storedModel) {
+        throw new ReindexRequiredError(`This index was built with '${storedModel}', but the current key resolves ` +
+            `to '${modelKey(embedder)}'. Run 'lat reindex' to rebuild.`);
+    }
+    return embedder;
+}

package/dist/src/search/index.d.ts

@@ -0,0 +1,9 @@
+import type { Client } from '@libsql/client';
+import type { Embedder } from './embedder.js';
+export type IndexStats = {
+    added: number;
+    updated: number;
+    removed: number;
+    unchanged: number;
+};
+export declare function indexSections(latDir: string, db: Client, embedder: Embedder, onProgress?: (done: number, total: number) => void): Promise<IndexStats>;

package/dist/src/search/index.js

@@ -0,0 +1,66 @@
+import { createHash } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { loadAllSections, flattenSections } from '../lattice.js';
+function hashContent(text) {
+    return createHash('sha256').update(text).digest('hex');
+}
+async function sectionContent(section, projectRoot) {
+    const filePath = join(projectRoot, section.filePath);
+    const content = await readFile(filePath, 'utf-8');
+    const lines = content.split('\n');
+    return lines.slice(section.startLine - 1, section.endLine).join('\n');
+}
+export async function indexSections(latDir, db, embedder, onProgress) {
+    const projectRoot = dirname(latDir);
+    const allSections = await loadAllSections(latDir);
+    const flat = flattenSections(allSections);
+    // Build current state: id -> { section, content, hash }
+    const current = new Map();
+    for (const s of flat) {
+        const text = await sectionContent(s, projectRoot);
+        current.set(s.id, { section: s, content: text, hash: hashContent(text) });
+    }
+    // Get existing hashes from DB
+    const existing = new Map();
+    const rows = await db.execute('SELECT id, content_hash FROM sections');
+    for (const row of rows.rows) {
+        existing.set(row.id, row.content_hash);
+    }
+    // Partition into new, changed, unchanged, deleted
+    const toEmbed = [];
+    let unchanged = 0;
+    for (const [id, entry] of current) {
+        const existingHash = existing.get(id);
+        if (existingHash === entry.hash) {
+            unchanged++;
+        }
+        else {
+            toEmbed.push({ id, content: entry.content, section: entry.section });
+        }
+    }
+    const toDelete = [...existing.keys()].filter((id) => !current.has(id));
+    // Embed new/changed sections
+    if (toEmbed.length > 0) {
+        const texts = toEmbed.map((e) => e.content);
+        const vectors = await embedder.embed(texts, onProgress);
+        const now = Date.now();
+        for (let i = 0; i < toEmbed.length; i++) {
+            const { id, content, section } = toEmbed[i];
+            const hash = current.get(id).hash;
+            const vecJson = JSON.stringify(vectors[i]);
+            await db.execute({
+                sql: `INSERT OR REPLACE INTO sections (id, file, heading, content, content_hash, embedding, updated_at)
+              VALUES (?, ?, ?, ?, ?, vector(?), ?)`,
+                args: [id, section.file, section.heading, content, hash, vecJson, now],
+            });
+        }
+    }
+    // Delete removed sections
+    for (const id of toDelete) {
+        await db.execute({ sql: 'DELETE FROM sections WHERE id = ?', args: [id] });
+    }
+    const added = toEmbed.filter((e) => !existing.has(e.id)).length;
+    const updated = toEmbed.filter((e) => existing.has(e.id)).length;
+    return { added, updated, removed: toDelete.length, unchanged };
+}

package/dist/src/search/search.d.ts

@@ -0,0 +1,9 @@
+import type { Client } from '@libsql/client';
+import type { Embedder } from './embedder.js';
+export type SearchResult = {
+    id: string;
+    file: string;
+    heading: string;
+    content: string;
+};
+export declare function searchSections(db: Client, query: string, embedder: Embedder, limit?: number): Promise<SearchResult[]>;

package/dist/src/search/search.js

@@ -0,0 +1,16 @@
+export async function searchSections(db, query, embedder, limit = 5) {
+    const [queryVec] = await embedder.embed([query]);
+    const vecJson = JSON.stringify(queryVec);
+    const rows = await db.execute({
+        sql: `SELECT s.id, s.file, s.heading, s.content
+          FROM vector_top_k('sections_vec_idx', vector(?), ?) AS v
+          JOIN sections AS s ON s.rowid = v.id`,
+        args: [vecJson, limit],
+    });
+    return rows.rows.map((row) => ({
+        id: row.id,
+        file: row.file,
+        heading: row.heading,
+        content: row.content,
+    }));
+}

package/dist/src/source-parser.d.ts

@@ -0,0 +1,27 @@
+import type { Section } from './lattice.js';
+export type SourceSymbol = {
+    name: string;
+    kind: 'function' | 'class' | 'const' | 'type' | 'interface' | 'method' | 'variable';
+    parent?: string;
+    startLine: number;
+    endLine: number;
+    signature: string;
+};
+/** All source file extensions that lat can parse (derived from grammarMap). */
+export declare const SOURCE_EXTENSIONS: ReadonlySet<string>;
+export declare function parseSourceSymbols(filePath: string, content: string): Promise<SourceSymbol[]>;
+/** Clear the symbol cache. Call between top-level operations. */
+export declare function clearSymbolCache(): void;
+/**
+ * Check whether a source file path (relative to projectRoot) has a given symbol.
+ * Used by lat check to validate source code wiki links lazily.
+ */
+export declare function resolveSourceSymbol(filePath: string, symbolPath: string, projectRoot: string): Promise<{
+    found: boolean;
+    symbols: SourceSymbol[];
+    error?: string;
+}>;
+/**
+ * Convert source symbols to Section objects for uniform handling.
+ */
+export declare function sourceSymbolsToSections(symbols: SourceSymbol[], filePath: string): Section[];