lat.md 0.5.0 → 0.7.0

package/dist/src/cli/search.js

@@ -1,67 +1,107 @@
-import chalk from 'chalk';
 import { openDb, ensureSchema, closeDb } from '../search/db.js';
 import { detectProvider } from '../search/provider.js';
 import { indexSections } from '../search/index.js';
 import { searchSections } from '../search/search.js';
-import { loadAllSections, flattenSections } from '../lattice.js';
+import { loadAllSections, flattenSections, } from '../lattice.js';
 import { formatResultList } from '../format.js';
-import { getLlmKey, getConfigPath } from '../config.js';
-export async function searchCmd(ctx, query, opts) {
-    let key;
-    try {
-        key = getLlmKey();
-    }
-    catch (err) {
-        console.error(chalk.red(err.message));
-        process.exit(1);
-    }
-    if (!key) {
-        console.error(chalk.red('No API key configured.') +
-            ' Provide a key via LAT_LLM_KEY, LAT_LLM_KEY_FILE, LAT_LLM_KEY_HELPER, or run ' +
-            chalk.cyan('lat init') +
-            ' to save one in ' +
-            chalk.dim(getConfigPath()) +
-            '.');
-        process.exit(1);
-    }
+async function withDb(latDir, key, progress, fn) {
     const provider = detectProvider(key);
-    const db = openDb(ctx.latDir);
+    const db = openDb(latDir);
     try {
         await ensureSchema(db, provider.dimensions);
-        // Check if index needs updating
         const countResult = await db.execute('SELECT COUNT(*) as n FROM sections');
         const isEmpty = countResult.rows[0].n === 0;
-        if (isEmpty || opts.reindex) {
-            const label = opts.reindex ? 'Re-indexing' : 'Building index';
-            process.stderr.write(chalk.dim(`${label}...`));
-            const stats = await indexSections(ctx.latDir, db, provider, key);
-            process.stderr.write(chalk.dim(` done (${stats.added} added, ${stats.updated} updated, ${stats.removed} removed)\n`));
-        }
-        else {
-            // Incremental update
-            const stats = await indexSections(ctx.latDir, db, provider, key);
-            if (stats.added + stats.updated + stats.removed > 0) {
-                process.stderr.write(chalk.dim(`Index updated: ${stats.added} added, ${stats.updated} updated, ${stats.removed} removed\n`));
-            }
-        }
-        if (!query)
-            return;
-        const results = await searchSections(db, query, provider, key, opts.limit);
+        progress?.beforeIndex?.(isEmpty);
+        const stats = await indexSections(latDir, db, provider, key);
+        progress?.afterIndex?.(stats, isEmpty);
+        return await fn(db, provider);
+    }
+    finally {
+        await closeDb(db);
+    }
+}
+/**
+ * Run a semantic search across lat.md sections.
+ * Handles indexing (with optional progress callback). Returns matched sections.
+ */
+export async function runSearch(latDir, query, key, limit, progress) {
+    return withDb(latDir, key, progress, async (db, provider) => {
+        const results = await searchSections(db, query, provider, key, limit);
         if (results.length === 0) {
-            console.log(chalk.dim('No results found.'));
-            return;
+            return { query, matches: [] };
         }
-        // Load sections for formatting with location info
-        const allSections = await loadAllSections(ctx.latDir);
+        const allSections = await loadAllSections(latDir);
         const flat = flattenSections(allSections);
         const byId = new Map(flat.map((s) => [s.id, s]));
-        const matched = results
+        const matches = results
             .map((r) => byId.get(r.id))
             .filter((s) => !!s)
             .map((s) => ({ section: s, reason: 'semantic match' }));
-        console.log(formatResultList(`Search results for "${query}":`, matched, ctx.latDir));
+        return { query, matches };
+    });
+}
+/**
+ * Index-only mode (no query). Used by `lat search --reindex`.
+ */
+export async function runIndex(latDir, key, progress) {
+    await withDb(latDir, key, progress, async () => { });
+}
+export function cliProgress(reindex, s) {
+    return {
+        beforeIndex(isEmpty) {
+            if (isEmpty || reindex) {
+                const label = reindex ? 'Re-indexing' : 'Building index';
+                process.stderr.write(s.dim(`${label}...`));
+            }
+        },
+        afterIndex(stats, isEmpty) {
+            if (isEmpty || reindex) {
+                process.stderr.write(s.dim(` done (${stats.added} added, ${stats.updated} updated, ${stats.removed} removed)\n`));
+            }
+            else if (stats.added + stats.updated + stats.removed > 0) {
+                process.stderr.write(s.dim(`Index updated: ${stats.added} added, ${stats.updated} updated, ${stats.removed} removed\n`));
+            }
+        },
+    };
+}
+export async function searchCommand(ctx, query, opts, progress) {
+    const { getLlmKey, getConfigPath } = await import('../config.js');
+    let key;
+    try {
+        key = getLlmKey();
     }
-    finally {
-        await closeDb(db);
+    catch (err) {
+        return { output: err.message, isError: true };
+    }
+    if (!key) {
+        const s = ctx.styler;
+        return {
+            output: s.red('No API key configured.') +
+                ' Provide a key via LAT_LLM_KEY, LAT_LLM_KEY_FILE, LAT_LLM_KEY_HELPER, or run ' +
+                s.cyan('lat init') +
+                (ctx.mode === 'cli'
+                    ? ' to save one in ' + s.dim(getConfigPath())
+                    : '') +
+                '.',
+            isError: true,
+        };
+    }
+    if (!query) {
+        await runIndex(ctx.latDir, key, progress);
+        return { output: '' };
+    }
+    const result = await runSearch(ctx.latDir, query, key, opts.limit, progress);
+    if (result.matches.length === 0) {
+        return { output: 'No results found.' };
     }
+    const navHints = ctx.mode === 'cli'
+        ? '- `lat section "section#id"` \u2014 show full content with outgoing/incoming refs\n' +
+            '- `lat search "new query"` \u2014 search for something else'
+        : '- `lat_section` \u2014 show full content with outgoing/incoming refs\n' +
+            '- `lat_search` \u2014 search for something else';
+    return {
+        output: formatResultList(ctx, `Search results for "${query}":`, result.matches) +
+            '\nTo navigate further:\n' +
+            navHints,
+    };
 }

package/dist/src/cli/section.d.ts

@@ -0,0 +1,26 @@
+import { type Section, type SectionMatch } from '../lattice.js';
+import type { CmdContext, CmdResult } from '../context.js';
+export type SectionFound = {
+    kind: 'found';
+    section: Section;
+    content: string;
+    outgoingRefs: {
+        target: string;
+        resolved: Section;
+    }[];
+    incomingRefs: SectionMatch[];
+};
+export type SectionResult = SectionFound | {
+    kind: 'no-match';
+    suggestions: SectionMatch[];
+};
+/**
+ * Look up a section by id, return its content, outgoing wiki link targets,
+ * and incoming references from other sections.
+ */
+export declare function getSection(ctx: CmdContext, query: string): Promise<SectionResult>;
+/**
+ * Format a successful section result with styling.
+ */
+export declare function formatSectionOutput(ctx: CmdContext, result: SectionFound): string;
+export declare function sectionCommand(ctx: CmdContext, query: string): Promise<CmdResult>;

package/dist/src/cli/section.js

@@ -0,0 +1,133 @@
+import { readFile } from 'node:fs/promises';
+import { join, relative } from 'node:path';
+import { loadAllSections, findSections, flattenSections, extractRefs, buildFileIndex, resolveRef, listLatticeFiles, } from '../lattice.js';
+import { formatSectionId } from '../format.js';
+/**
+ * Look up a section by id, return its content, outgoing wiki link targets,
+ * and incoming references from other sections.
+ */
+export async function getSection(ctx, query) {
+    query = query.replace(/^\[\[|\]\]$/g, '');
+    const allSections = await loadAllSections(ctx.latDir);
+    const matches = findSections(allSections, query);
+    if (matches.length === 0) {
+        return { kind: 'no-match', suggestions: [] };
+    }
+    // Accept the top match if confident
+    const top = matches[0];
+    const isConfident = top.reason === 'exact match' ||
+        top.reason.startsWith('file stem expanded') ||
+        top.reason === 'section name match';
+    if (!isConfident) {
+        return { kind: 'no-match', suggestions: matches };
+    }
+    const section = top.section;
+    // Read raw content between startLine and endLine
+    const absPath = join(ctx.projectRoot, section.filePath);
+    const fileContent = await readFile(absPath, 'utf-8');
+    const lines = fileContent.split('\n');
+    const content = lines
+        .slice(section.startLine - 1, section.endLine)
+        .join('\n');
+    // Find outgoing wiki link targets within this section's content
+    const flat = flattenSections(allSections);
+    const sectionIds = new Set(flat.map((s) => s.id.toLowerCase()));
+    const fileIndex = buildFileIndex(allSections);
+    const sectionRefs = extractRefs(absPath, fileContent, ctx.projectRoot);
+    const sectionId = section.id.toLowerCase();
+    const outgoingRefs = [];
+    const seen = new Set();
+    for (const ref of sectionRefs) {
+        if (ref.fromSection.toLowerCase() !== sectionId)
+            continue;
+        const { resolved } = resolveRef(ref.target, sectionIds, fileIndex);
+        const resolvedLower = resolved.toLowerCase();
+        if (seen.has(resolvedLower))
+            continue;
+        seen.add(resolvedLower);
+        const targetSection = flat.find((s) => s.id.toLowerCase() === resolvedLower);
+        if (targetSection) {
+            outgoingRefs.push({ target: ref.target, resolved: targetSection });
+        }
+    }
+    // Find incoming references: other sections that link to this one
+    const incomingRefs = [];
+    const files = await listLatticeFiles(ctx.latDir);
+    const incomingSections = new Set();
+    for (const file of files) {
+        const fc = await readFile(file, 'utf-8');
+        const fileRefs = extractRefs(file, fc, ctx.projectRoot);
+        for (const ref of fileRefs) {
+            const { resolved } = resolveRef(ref.target, sectionIds, fileIndex);
+            if (resolved.toLowerCase() === sectionId &&
+                ref.fromSection.toLowerCase() !== sectionId) {
+                if (!incomingSections.has(ref.fromSection.toLowerCase())) {
+                    incomingSections.add(ref.fromSection.toLowerCase());
+                    const fromSection = flat.find((s) => s.id.toLowerCase() === ref.fromSection.toLowerCase());
+                    if (fromSection) {
+                        incomingRefs.push({ section: fromSection, reason: 'wiki link' });
+                    }
+                }
+            }
+        }
+    }
+    return { kind: 'found', section, content, outgoingRefs, incomingRefs };
+}
+function truncate(s, max) {
+    return s.length > max ? s.slice(0, max) + '...' : s;
+}
+/**
+ * Format a successful section result with styling.
+ */
+export function formatSectionOutput(ctx, result) {
+    const s = ctx.styler;
+    const { section, content, outgoingRefs, incomingRefs } = result;
+    const relPath = relative(process.cwd(), join(ctx.projectRoot, section.filePath));
+    const loc = `${s.cyan(relPath)}${s.dim(`:${section.startLine}-${section.endLine}`)}`;
+    const parts = [
+        `${s.bold('[[' + formatSectionId(section.id, s) + ']]')} (${loc})`,
+        '',
+        content,
+    ];
+    if (outgoingRefs.length > 0) {
+        parts.push('', s.bold('This section references:'), '');
+        for (const ref of outgoingRefs) {
+            const body = ref.resolved.firstParagraph
+                ? ` ${s.dim('—')} ${truncate(ref.resolved.firstParagraph, 120)}`
+                : '';
+            parts.push(`${s.dim('*')} [[${formatSectionId(ref.resolved.id, s)}]]${body}`);
+        }
+    }
+    if (incomingRefs.length > 0) {
+        parts.push('', s.bold('Referenced by:'), '');
+        for (const ref of incomingRefs) {
+            const body = ref.section.firstParagraph
+                ? ` ${s.dim('—')} ${truncate(ref.section.firstParagraph, 120)}`
+                : '';
+            parts.push(`${s.dim('*')} [[${formatSectionId(ref.section.id, s)}]]${body}`);
+        }
+    }
+    return parts.join('\n');
+}
+export async function sectionCommand(ctx, query) {
+    const result = await getSection(ctx, query);
+    if (result.kind === 'no-match') {
+        const s = ctx.styler;
+        if (result.suggestions.length > 0) {
+            const suggestions = result.suggestions
+                .map((m) => `  ${s.dim('*')} ${s.white(m.section.id)} ${s.dim(`(${m.reason})`)}`)
+                .join('\n');
+            return {
+                output: s.red(`No section "${query}" found.`) +
+                    ' Did you mean:\n' +
+                    suggestions,
+                isError: true,
+            };
+        }
+        return {
+            output: s.red(`No sections matching "${query}"`),
+            isError: true,
+        };
+    }
+    return { output: formatSectionOutput(ctx, result) };
+}

package/dist/src/code-refs.js

@@ -39,7 +39,8 @@ export async function scanCodeRefs(projectRoot) {
         try {
             content = await readFile(file, 'utf-8');
         }
-        catch {
+        catch (err) {
+            process.stderr.write(`Error: failed to read ${file}: ${err.message}\n`);
             continue;
         }
         const lines = content.split('\n');

package/dist/src/config.js

@@ -16,8 +16,9 @@ export function readConfig() {
     try {
         return JSON.parse(readFileSync(configPath, 'utf-8'));
     }
-    catch {
-        return {};
+    catch (err) {
+        process.stderr.write(`Error: failed to parse config ${configPath}: ${err.message}\n`);
+        process.exit(1);
     }
 }
 export function writeConfig(config) {

package/dist/src/context.d.ts

@@ -0,0 +1,21 @@
+export type Styler = {
+    bold: (s: string) => string;
+    dim: (s: string) => string;
+    red: (s: string) => string;
+    cyan: (s: string) => string;
+    white: (s: string) => string;
+    green: (s: string) => string;
+    yellow: (s: string) => string;
+    boldWhite: (s: string) => string;
+};
+export declare const plainStyler: Styler;
+export type CmdContext = {
+    latDir: string;
+    projectRoot: string;
+    styler: Styler;
+    mode: 'cli' | 'mcp';
+};
+export type CmdResult = {
+    output: string;
+    isError?: boolean;
+};

package/dist/src/context.js

@@ -0,0 +1,11 @@
+const identity = (s) => s;
+export const plainStyler = {
+    bold: identity,
+    dim: identity,
+    red: identity,
+    cyan: identity,
+    white: identity,
+    green: identity,
+    yellow: identity,
+    boldWhite: identity,
+};

package/dist/src/format.d.ts

@@ -1,6 +1,7 @@
 import type { Section, SectionMatch } from './lattice.js';
-export declare function formatSectionId(id: string): string;
-export declare function formatSectionPreview(section: Section, latticeDir: string, opts?: {
+import type { CmdContext, Styler } from './context.js';
+export declare function formatSectionId(id: string, s: Styler): string;
+export declare function formatSectionPreview(ctx: CmdContext, section: Section, opts?: {
     reason?: string;
 }): string;
-export declare function formatResultList(header: string, matches: SectionMatch[], latticeDir: string): string;
+export declare function formatResultList(ctx: CmdContext, header: string, matches: SectionMatch[]): string;

package/dist/src/format.js

@@ -1,35 +1,31 @@
-import { relative } from 'node:path';
-import chalk from 'chalk';
-export function formatSectionId(id) {
+import { join, relative } from 'node:path';
+export function formatSectionId(id, s) {
     const parts = id.split('#');
     return parts.length === 1
-        ? chalk.bold.white(parts[0])
-        : chalk.dim(parts.slice(0, -1).join('#') + '#') +
-            chalk.bold.white(parts[parts.length - 1]);
+        ? s.boldWhite(parts[0])
+        : s.dim(parts.slice(0, -1).join('#') + '#') +
+            s.boldWhite(parts[parts.length - 1]);
 }
-export function formatSectionPreview(section, latticeDir, opts) {
-    const relPath = relative(process.cwd(), latticeDir + '/' + section.file + '.md');
+export function formatSectionPreview(ctx, section, opts) {
+    const s = ctx.styler;
+    const relPath = relative(process.cwd(), join(ctx.projectRoot, section.filePath));
     const kind = section.id.includes('#') ? 'Section' : 'File';
-    const reasonSuffix = opts?.reason ? ' ' + chalk.dim(`(${opts.reason})`) : '';
+    const reasonSuffix = opts?.reason ? ' ' + s.dim(`(${opts.reason})`) : '';
     const lines = [
-        `${chalk.dim('*')} ${chalk.dim(kind + ':')} [[${formatSectionId(section.id)}]]${reasonSuffix}`,
-        `  ${chalk.dim('Defined in')} ${chalk.cyan(relPath)}${chalk.dim(`:${section.startLine}-${section.endLine}`)}`,
+        `${s.dim('*')} ${s.dim(kind + ':')} [[${formatSectionId(section.id, s)}]]${reasonSuffix}`,
+        `  ${s.dim('Defined in')} ${s.cyan(relPath)}${s.dim(`:${section.startLine}-${section.endLine}`)}`,
     ];
-    if (section.body) {
-        const truncated = section.body.length > 200
-            ? section.body.slice(0, 200) + '...'
-            : section.body;
-        lines.push('');
-        lines.push(`  ${chalk.dim('>')} ${truncated}`);
+    if (section.firstParagraph) {
+        lines.push('', `  ${s.dim('>')} ${section.firstParagraph}`);
     }
     return lines.join('\n');
 }
-export function formatResultList(header, matches, latticeDir) {
-    const lines = ['', chalk.bold(header), ''];
+export function formatResultList(ctx, header, matches) {
+    const lines = ['', ctx.styler.bold(header), ''];
     for (let i = 0; i < matches.length; i++) {
         if (i > 0)
             lines.push('');
-        lines.push(formatSectionPreview(matches[i].section, latticeDir, {
+        lines.push(formatSectionPreview(ctx, matches[i].section, {
             reason: matches[i].reason,
         }));
     }

package/dist/src/init-version.d.ts

@@ -0,0 +1,10 @@
+/**
+ * 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 declare const INIT_VERSION = 1;
+export declare function readInitVersion(latDir: string): number | null;
+export declare function readFileHash(latDir: string, relPath: string): string | null;
+export declare function contentHash(content: string): string;
+export declare function writeInitMeta(latDir: string, fileHashes: Record<string, string>): void;

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

@@ -3,10 +3,11 @@ export type Section = {
     heading: string;
     depth: number;
     file: string;
+    filePath: string;
     children: Section[];
     startLine: number;
     endLine: number;
-    body: string;
+    firstParagraph: string;
 };
 export type Ref = {
     target: string;
@@ -20,13 +21,18 @@ export type LatFrontmatter = {
 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[]>;
-export declare function parseSections(filePath: string, content: string, latticeDir?: string): Section[];
+export declare function parseSections(filePath: string, content: string, projectRoot?: string): Section[];
 export declare function loadAllSections(latticeDir: string): Promise<Section[]>;
 export declare function flattenSections(sections: Section[]): Section[];
 /**
- * Build an index mapping bare file stems to their full vault-relative paths.
- * Used by resolveRef to allow short references when a stem is unambiguous.
+ * Build an index mapping path suffixes to their full vault-relative paths.
+ * Used by resolveRef to allow short references when a suffix is unambiguous.
+ *
+ * For a file like `lat.md/guides/setup`, indexes both `guides/setup` and `setup`.
+ * This ensures backward-compatible short refs after the vault root moved to the
+ * project root (so section IDs now include the `lat.md/` prefix).
  */
 export declare function buildFileIndex(sections: Section[]): Map<string, string[]>;
 export type ResolveResult = {
@@ -50,4 +56,4 @@ export type SectionMatch = {
     reason: string;
 };
 export declare function findSections(sections: Section[], query: string): SectionMatch[];
-export declare function extractRefs(filePath: string, content: string, latticeDir?: string): Ref[];
+export declare function extractRefs(filePath: string, content: string, projectRoot?: string): Ref[];