@plebeiantech/lat.md 0.12.3-fork.1

package/dist/src/cli/link-scheme.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Decide whether a Markdown link destination points inside the lattice or
+ * out at the wider world.
+ *
+ * This exists as its own module because two callers need the same answer and
+ * a second, differently-behaved copy of the rule is exactly how the two
+ * drift: `parseIndexEntries` in check.ts decides which index bullets are
+ * generated entries, and `spliceIndexContent` in gen-index.ts decides which
+ * bullets belong to the region `--fix` is allowed to rewrite. If those two
+ * ever disagree about a line, `--fix` rewrites a bullet the checker does not
+ * track, or leaves one it does.
+ *
+ * `localLinkTarget` in check.ts applies the same rule inline for
+ * relative-link validation. It is upstream code and is deliberately left
+ * alone here; if this ever moves upstream, that is the call site to fold in.
+ */
+/**
+ * True when `url` carries a URL scheme (`https:`, `mailto:`, `file:`) and is
+ * therefore not a path inside the lattice.
+ *
+ * A Windows drive letter is the one case that looks like a scheme and is not
+ * — `C:\docs\a.md` matches the scheme grammar because a drive letter is a
+ * single ASCII letter followed by a colon. Treat it as a path, the same way
+ * `localLinkTarget` does, so the two agree.
+ */
+export declare function hasUrlScheme(url: string): boolean;
+/**
+ * True when `url` is a destination the lattice can own: no scheme, and not
+ * rooted at the filesystem root. A root-absolute path is excluded for the
+ * same reason `localLinkTarget` excludes it — it names a location outside
+ * the lattice tree, so it is never a child entry of a directory index.
+ */
+export declare function isLatticeLocalDest(url: string): boolean;
+/**
+ * Reduce a Markdown link destination to the name of the directory child it
+ * refers to, or null when it refers to no child of this directory at all.
+ *
+ * The naive reading — take the first `/`-separated segment — is wrong in
+ * four distinct ways, and each one was observed producing a bogus entry
+ * name that `lat check` then reported as a stale entry that "does not
+ * exist":
+ *
+ *   https://example.com/docs  ->  "https:"   a scheme is not a path segment
+ *   ./notes.md                ->  "."        a no-op prefix is not a child
+ *   ../siblings/x.md          ->  ".."       this escapes the directory
+ *   notes.md#intro            ->  "notes.md#intro"  fragments are not names
+ *
+ * Order is load-bearing. The fragment and query are split off BEFORE
+ * percent-decoding, and the path is split on `/` BEFORE decoding too, for
+ * the same reason `localLinkTarget` does it: `%23` and `%2F` decode to `#`
+ * and `/`, and decoding first would let a filename that legitimately
+ * contains either one truncate or split itself.
+ */
+export declare function indexEntryNameFromDest(dest: string): string | null;

package/dist/src/cli/link-scheme.js

@@ -0,0 +1,101 @@
+/**
+ * Decide whether a Markdown link destination points inside the lattice or
+ * out at the wider world.
+ *
+ * This exists as its own module because two callers need the same answer and
+ * a second, differently-behaved copy of the rule is exactly how the two
+ * drift: `parseIndexEntries` in check.ts decides which index bullets are
+ * generated entries, and `spliceIndexContent` in gen-index.ts decides which
+ * bullets belong to the region `--fix` is allowed to rewrite. If those two
+ * ever disagree about a line, `--fix` rewrites a bullet the checker does not
+ * track, or leaves one it does.
+ *
+ * `localLinkTarget` in check.ts applies the same rule inline for
+ * relative-link validation. It is upstream code and is deliberately left
+ * alone here; if this ever moves upstream, that is the call site to fold in.
+ */
+/**
+ * True when `url` carries a URL scheme (`https:`, `mailto:`, `file:`) and is
+ * therefore not a path inside the lattice.
+ *
+ * A Windows drive letter is the one case that looks like a scheme and is not
+ * — `C:\docs\a.md` matches the scheme grammar because a drive letter is a
+ * single ASCII letter followed by a colon. Treat it as a path, the same way
+ * `localLinkTarget` does, so the two agree.
+ */
+export function hasUrlScheme(url) {
+    const u = url.trim();
+    if (/^[a-zA-Z]:\\/.test(u))
+        return false;
+    return /^[a-zA-Z][a-zA-Z0-9+.-]*:/.test(u);
+}
+/**
+ * True when `url` is a destination the lattice can own: no scheme, and not
+ * rooted at the filesystem root. A root-absolute path is excluded for the
+ * same reason `localLinkTarget` excludes it — it names a location outside
+ * the lattice tree, so it is never a child entry of a directory index.
+ */
+export function isLatticeLocalDest(url) {
+    const u = url.trim();
+    if (u === '')
+        return false;
+    if (u.startsWith('/'))
+        return false;
+    return !hasUrlScheme(u);
+}
+/**
+ * Reduce a Markdown link destination to the name of the directory child it
+ * refers to, or null when it refers to no child of this directory at all.
+ *
+ * The naive reading — take the first `/`-separated segment — is wrong in
+ * four distinct ways, and each one was observed producing a bogus entry
+ * name that `lat check` then reported as a stale entry that "does not
+ * exist":
+ *
+ *   https://example.com/docs  ->  "https:"   a scheme is not a path segment
+ *   ./notes.md                ->  "."        a no-op prefix is not a child
+ *   ../siblings/x.md          ->  ".."       this escapes the directory
+ *   notes.md#intro            ->  "notes.md#intro"  fragments are not names
+ *
+ * Order is load-bearing. The fragment and query are split off BEFORE
+ * percent-decoding, and the path is split on `/` BEFORE decoding too, for
+ * the same reason `localLinkTarget` does it: `%23` and `%2F` decode to `#`
+ * and `/`, and decoding first would let a filename that legitimately
+ * contains either one truncate or split itself.
+ */
+export function indexEntryNameFromDest(dest) {
+    if (!isLatticeLocalDest(dest))
+        return null;
+    const u = dest.trim();
+    const queryAt = u.indexOf('?');
+    const fragmentAt = u.indexOf('#');
+    const pathEnd = Math.min(queryAt === -1 ? u.length : queryAt, fragmentAt === -1 ? u.length : fragmentAt);
+    let path = u.slice(0, pathEnd);
+    // `./` contributes nothing to the path, and may be repeated.
+    while (path.startsWith('./'))
+        path = path.slice(2);
+    // `..` leaves the directory whose index this is, so whatever it names is
+    // by definition not a child of it.
+    if (path === '..' || path.startsWith('../'))
+        return null;
+    if (path === '' || path === '.')
+        return null;
+    const segment = path.split('/')[0];
+    if (segment === '')
+        return null;
+    let decoded;
+    try {
+        decoded = decodeURIComponent(segment);
+    }
+    catch {
+        decoded = segment;
+    }
+    // A percent-encoded `.` or `..` (e.g. `%2e%2e`) decodes to the same
+    // traversal segment the raw check above already rejects. Re-check after
+    // decoding so both spellings agree — this is a consistency fix, not a
+    // security one: parseIndexEntries only compares names, it never builds a
+    // filesystem path from one.
+    if (decoded === '.' || decoded === '..')
+        return null;
+    return decoded;
+}

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

@@ -0,0 +1,2 @@
+import type { CmdContext, CmdResult } from '../context.js';
+export declare function locateCommand(ctx: CmdContext, query: string): Promise<CmdResult>;

package/dist/src/cli/locate.js

@@ -0,0 +1,17 @@
+import { loadAllSections, findSections } from '../lattice.js';
+import { formatResultList } from '../format.js';
+export async function locateCommand(ctx, query) {
+    const stripped = query.replace(/^\[\[|\]\]$/g, '');
+    const sections = await loadAllSections(ctx.latDir);
+    const matches = findSections(sections, stripped);
+    if (matches.length === 0) {
+        const s = ctx.styler;
+        return {
+            output: s.red(`No sections matching "${stripped}" (no exact, substring, or fuzzy matches)`),
+            isError: true,
+        };
+    }
+    return {
+        output: formatResultList(ctx, `Sections matching "${stripped}":`, matches),
+    };
+}

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

@@ -0,0 +1,22 @@
+import { type Section, type SectionMatch } from '../lattice.js';
+import type { CmdContext, CmdResult } from '../context.js';
+export type Scope = 'md' | 'code' | 'md+code';
+export type RefsFound = {
+    kind: 'found';
+    target: Section;
+    mdRefs: SectionMatch[];
+    codeRefs: string[];
+};
+export type RefsError = {
+    kind: 'no-match';
+    suggestions: SectionMatch[];
+};
+export type RefsResult = RefsFound | RefsError;
+/**
+ * Find all sections and code locations that reference a given section or
+ * source file. Accepts section ids (full-path, short-form) and source file
+ * paths (e.g. src/app.rs#foo). Source file queries match wiki links directly
+ * without section resolution.
+ */
+export declare function findRefs(ctx: CmdContext, query: string, scope: Scope): Promise<RefsResult>;
+export declare function refsCommand(ctx: CmdContext, query: string, scope: Scope): Promise<CmdResult>;

package/dist/src/cli/refs.js

@@ -0,0 +1,229 @@
+import { readFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { extname, join, relative } from 'node:path';
+import { listLatticeFiles, loadAllSections, findSections, extractRefs, flattenSections, buildFileIndex, buildSectionSlugIndex, resolveRef, } from '../lattice.js';
+import { formatResultList } from '../format.js';
+import { scanCodeRefs } from '../code-refs.js';
+/** Extensions recognized as source code for ref queries. */
+const SOURCE_EXTS = new Set([
+    '.ts',
+    '.tsx',
+    '.js',
+    '.jsx',
+    '.py',
+    '.rs',
+    '.go',
+    '.c',
+    '.h',
+]);
+/**
+ * Check if a query looks like a source file path (has a recognized extension
+ * and the file exists on disk).
+ */
+function isSourceQuery(query, projectRoot) {
+    const hashIdx = query.indexOf('#');
+    const filePart = hashIdx === -1 ? query : query.slice(0, hashIdx);
+    const symbolPart = hashIdx === -1 ? '' : query.slice(hashIdx + 1);
+    const ext = extname(filePart);
+    if (!SOURCE_EXTS.has(ext))
+        return null;
+    if (!existsSync(join(projectRoot, filePart)))
+        return null;
+    return { filePart, symbolPart };
+}
+/**
+ * Find references to a source file or symbol across lat.md and code files.
+ * For file-level queries (no #symbol), matches all wiki links targeting
+ * that file or any symbol in it.
+ */
+async function findSourceRefs(latDir, projectRoot, query, scope) {
+    const hashIdx = query.indexOf('#');
+    const filePart = hashIdx === -1 ? query : query.slice(0, hashIdx);
+    const isFileLevel = hashIdx === -1;
+    const queryLower = query.toLowerCase();
+    const fileLower = filePart.toLowerCase();
+    // Build a synthetic Section for the target
+    const target = {
+        id: query,
+        heading: hashIdx === -1 ? filePart : query.slice(hashIdx + 1),
+        depth: 0,
+        file: filePart,
+        filePath: filePart,
+        children: [],
+        startLine: 0,
+        endLine: 0,
+        firstParagraph: '',
+    };
+    // Try to get real line info from the source parser
+    try {
+        const { resolveSourceSymbol } = await import('../source-parser.js');
+        if (hashIdx !== -1) {
+            const symbolPart = query.slice(hashIdx + 1);
+            const { found, symbols } = await resolveSourceSymbol(filePart, symbolPart, projectRoot);
+            if (found) {
+                const parts = symbolPart.split('#');
+                const sym = symbols.find((s) => parts.length === 1
+                    ? s.name === parts[0] && !s.parent
+                    : s.name === parts[1] && s.parent === parts[0]);
+                if (sym) {
+                    target.startLine = sym.startLine;
+                    target.endLine = sym.endLine;
+                    target.firstParagraph = sym.signature;
+                }
+            }
+        }
+    }
+    catch {
+        // source parser unavailable — proceed without line info
+    }
+    const allSections = await loadAllSections(latDir);
+    const flat = flattenSections(allSections);
+    const mdRefs = [];
+    const codeRefs = [];
+    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 targetLower = ref.target.toLowerCase();
+                const matches = isFileLevel
+                    ? targetLower === fileLower || targetLower.startsWith(fileLower + '#')
+                    : targetLower === queryLower;
+                if (matches) {
+                    matchingFromSections.add(ref.fromSection.toLowerCase());
+                }
+            }
+        }
+        if (matchingFromSections.size > 0) {
+            const referrers = flat.filter((s) => matchingFromSections.has(s.id.toLowerCase()));
+            for (const s of referrers) {
+                mdRefs.push({ section: s, reason: 'wiki link' });
+            }
+        }
+    }
+    if (scope === 'code' || scope === 'md+code') {
+        const { refs: scannedRefs } = await scanCodeRefs(projectRoot);
+        for (const ref of scannedRefs) {
+            const targetLower = ref.target.toLowerCase();
+            const matches = isFileLevel
+                ? targetLower === fileLower || targetLower.startsWith(fileLower + '#')
+                : targetLower === queryLower;
+            if (matches) {
+                const displayPath = relative(process.cwd(), join(projectRoot, ref.file));
+                codeRefs.push(`${displayPath}:${ref.line}`);
+            }
+        }
+    }
+    return { kind: 'found', target, mdRefs, codeRefs };
+}
+/**
+ * Find all sections and code locations that reference a given section or
+ * source file. Accepts section ids (full-path, short-form) and source file
+ * paths (e.g. src/app.rs#foo). Source file queries match wiki links directly
+ * without section resolution.
+ */
+export async function findRefs(ctx, query, scope) {
+    query = query.replace(/^\[\[|\]\]$/g, '');
+    // Source file queries bypass section resolution
+    if (isSourceQuery(query, ctx.projectRoot)) {
+        return findSourceRefs(ctx.latDir, ctx.projectRoot, query, scope);
+    }
+    const allSections = await loadAllSections(ctx.latDir);
+    const flat = flattenSections(allSections);
+    const sectionIds = new Set(flat.map((s) => s.id.toLowerCase()));
+    const fileIndex = buildFileIndex(allSections);
+    const slugIndex = buildSectionSlugIndex(allSections);
+    const { resolved } = resolveRef(query, sectionIds, fileIndex, slugIndex);
+    const q = resolved.toLowerCase();
+    let exactMatch = flat.find((s) => s.id.toLowerCase() === q);
+    // If resolveRef didn't land on an exact id, use findSections as fallback
+    const matches = !exactMatch ? findSections(allSections, query) : [];
+    if (!exactMatch && matches.length >= 1) {
+        const top = matches[0];
+        const isConfident = top.reason === 'exact match' ||
+            top.reason.startsWith('file stem expanded') ||
+            top.reason === 'section name match';
+        if (isConfident) {
+            exactMatch = top.section;
+        }
+    }
+    if (!exactMatch) {
+        const suggestions = matches.length > 0 ? matches : findSections(allSections, query);
+        return { kind: 'no-match', suggestions };
+    }
+    const targetId = exactMatch.id.toLowerCase();
+    const mdRefs = [];
+    const codeRefs = [];
+    if (scope === 'md' || scope === 'md+code') {
+        const files = await listLatticeFiles(ctx.latDir);
+        const matchingFromSections = new Set();
+        for (const file of files) {
+            const content = await readFile(file, 'utf-8');
+            const fileRefs = extractRefs(file, content, ctx.projectRoot);
+            for (const ref of fileRefs) {
+                const { resolved: refResolved } = resolveRef(ref.target, sectionIds, fileIndex, slugIndex);
+                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) {
+                mdRefs.push({ section: s, reason: 'wiki link' });
+            }
+        }
+    }
+    if (scope === 'code' || scope === 'md+code') {
+        const { refs: scannedRefs } = await scanCodeRefs(ctx.projectRoot);
+        for (const ref of scannedRefs) {
+            const { resolved: codeResolved } = resolveRef(ref.target, sectionIds, fileIndex, slugIndex);
+            if (codeResolved.toLowerCase() === targetId) {
+                const displayPath = relative(process.cwd(), join(ctx.projectRoot, ref.file));
+                codeRefs.push(`${displayPath}:${ref.line}`);
+            }
+        }
+    }
+    return { kind: 'found', target: exactMatch, mdRefs, codeRefs };
+}
+export async function refsCommand(ctx, query, scope) {
+    const result = await findRefs(ctx, query, scope);
+    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 section matching "${query}"`),
+            isError: true,
+        };
+    }
+    const { target, mdRefs, codeRefs } = result;
+    if (mdRefs.length === 0 && codeRefs.length === 0) {
+        return {
+            output: ctx.styler.yellow(`No references to "${target.id}" found`),
+            isError: true,
+        };
+    }
+    const s = ctx.styler;
+    const parts = [];
+    if (mdRefs.length > 0) {
+        parts.push(formatResultList(ctx, `References to "${target.id}":`, mdRefs));
+    }
+    if (codeRefs.length > 0) {
+        parts.push('## Code references:' +
+            '\n\n' +
+            codeRefs.map((l) => `${s.dim('*')} ${l}`).join('\n'));
+    }
+    return { output: parts.join('\n') };
+}

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

@@ -0,0 +1,13 @@
+import type { CmdContext, CmdResult } from '../context.js';
+/**
+ * Rebuild the embedding index. Honors the durable per-repo backend preference:
+ * a repo pinned to local rebuilds local and ignores the key. `--local` forces
+ * local; `--remote` forces re-resolving from the key (the escape hatch back to
+ * hosted); a bare run on an unpinned repo decides from the env. If a key is set
+ * but rejected, offers to switch to local (`--yes` answers non-interactively).
+ */
+export declare function reindexCommand(ctx: CmdContext, opts: {
+    local?: boolean;
+    remote?: boolean;
+    yes?: boolean;
+}): Promise<CmdResult>;

package/dist/src/cli/reindex.js

@@ -0,0 +1,136 @@
+import readline from 'node:readline/promises';
+import { openDb, ensureMeta, setStoredModel, ensureSectionsSchema, dropSections, closeDb, } from '../search/db.js';
+import { embedderFromEnv, localEmbedder, modelKey, EmbeddingAuthError, } from '../search/embedder.js';
+import { getLlmKey, getRepoEmbedding, setRepoEmbedding } from '../config.js';
+import { indexSections } from '../search/index.js';
+const SPINNER = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+async function confirmUseLocal(ctx, status, assumeYes) {
+    const s = ctx.styler;
+    process.stderr.write(s.yellow(`LAT_LLM_KEY was rejected by the provider (${status}).`) + '\n');
+    if (assumeYes)
+        return true;
+    // Can't prompt when not attached to a terminal (agents, CI, MCP).
+    if (ctx.mode !== 'cli' || !process.stdin.isTTY)
+        return false;
+    const rl = readline.createInterface({
+        input: process.stdin,
+        output: process.stderr,
+    });
+    const ans = (await rl.question('Use local offline embeddings instead? [Y/n] '))
+        .trim()
+        .toLowerCase();
+    rl.close();
+    return ans === '' || ans === 'y' || ans === 'yes';
+}
+/**
+ * Rebuild the embedding index. Honors the durable per-repo backend preference:
+ * a repo pinned to local rebuilds local and ignores the key. `--local` forces
+ * local; `--remote` forces re-resolving from the key (the escape hatch back to
+ * hosted); a bare run on an unpinned repo decides from the env. If a key is set
+ * but rejected, offers to switch to local (`--yes` answers non-interactively).
+ */
+export async function reindexCommand(ctx, opts) {
+    const s = ctx.styler;
+    let key;
+    try {
+        key = getLlmKey();
+    }
+    catch (err) {
+        return { output: err.message, isError: true };
+    }
+    if (opts.remote && !key) {
+        return {
+            output: s.red('--remote requires LAT_LLM_KEY to be set.'),
+            isError: true,
+        };
+    }
+    const pinnedLocal = getRepoEmbedding(ctx.latDir) === 'local';
+    let embedder;
+    if (opts.local || (pinnedLocal && !opts.remote)) {
+        // Explicit --local, or the repo is already pinned to local: use local and
+        // ignore the key. Say so when a key is present, so it's not a silent drop.
+        if (!opts.local && key) {
+            process.stderr.write(s.dim('Local embeddings configured for this repo; ignoring LAT_LLM_KEY.\n'));
+        }
+        embedder = await localEmbedder();
+    }
+    else if (!key) {
+        embedder = await localEmbedder();
+    }
+    else {
+        // Resolve from the env key (bare + unpinned, or explicit --remote). Verify
+        // it with a tiny probe first, so an invalid key doesn't wipe a working index.
+        try {
+            const remote = await embedderFromEnv();
+            await remote.embed(['lat reindex: verifying embedding key']);
+            embedder = remote;
+        }
+        catch (err) {
+            // A malformed/unsupported key prefix throws from embedderFromEnv (a plain
+            // Error, not EmbeddingAuthError) — surface it cleanly instead of crashing.
+            if (!(err instanceof EmbeddingAuthError)) {
+                return { output: err.message, isError: true };
+            }
+            if (!(await confirmUseLocal(ctx, err.status, !!opts.yes))) {
+                return {
+                    output: ' Fix the key, or re-run ' +
+                        s.cyan('lat reindex --local') +
+                        ' to switch to the offline model.',
+                    isError: true,
+                };
+            }
+            embedder = await localEmbedder();
+        }
+    }
+    const db = openDb(ctx.latDir);
+    const interactive = ctx.mode === 'cli' && !!process.stderr.isTTY;
+    try {
+        await ensureMeta(db);
+        await dropSections(db);
+        await ensureSectionsSchema(db, embedder.dimensions);
+        const label = `Reindexing with ${embedder.name}`;
+        // Interactive terminals get a live progress line driven per embed-chunk
+        // (frame + done/total). Elsewhere (agents, CI, MCP) a single plain line
+        // keeps logs clean. Progress is event-driven, not timer-based, so it stays
+        // accurate even though the local WASM forward pass is synchronous.
+        let frame = 0;
+        const onProgress = interactive
+            ? (done, total) => {
+                const f = SPINNER[frame++ % SPINNER.length];
+                process.stderr.write(`\r\x1b[K${f} ${s.dim(`${label} — ${done}/${total}`)}`);
+            }
+            : undefined;
+        if (interactive)
+            process.stderr.write(`${SPINNER[0]} ${s.dim(label + '…')}`);
+        else
+            process.stderr.write(s.dim(label + '…\n'));
+        let stats;
+        try {
+            stats = await indexSections(ctx.latDir, db, embedder, onProgress);
+            // Pin the backend only after a successful build, so a failed reindex never
+            // records a model that doesn't match a completed index.
+            await setStoredModel(db, modelKey(embedder));
+        }
+        catch (err) {
+            // Build failed: drop the half-built table so the DB is left clean. `meta`
+            // still holds the prior model, so the next run rebuilds it consistently.
+            await dropSections(db);
+            throw err;
+        }
+        finally {
+            if (interactive)
+                process.stderr.write('\r\x1b[K'); // clear the progress line
+        }
+        // Durably remember the choice so it survives a `.cache` wipe / fresh clone:
+        // local pins local (ignore the key thereafter); remote clears the pin so the
+        // env decides again.
+        setRepoEmbedding(ctx.latDir, embedder.name.startsWith('local:') ? 'local' : null);
+        return {
+            output: s.green(`Reindexed ${stats.added} sections`) +
+                ` using ${s.cyan(embedder.name)}.`,
+        };
+    }
+    finally {
+        await closeDb(db);
+    }
+}

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

@@ -0,0 +1,36 @@
+import type { CmdContext, CmdResult, Styler } from '../context.js';
+import { type IndexStats } from '../search/index.js';
+import { type Section, type SectionMatch } from '../lattice.js';
+export type SearchResult = {
+    query: string;
+    matches: SectionMatch[];
+};
+export type IndexProgress = {
+    /** Called before indexing starts. `isEmpty` is true on first run. */
+    beforeIndex?: (isEmpty: boolean) => void;
+    /** Called after indexing completes with stats. */
+    afterIndex?: (stats: IndexStats, isEmpty: boolean) => void;
+};
+/**
+ * Run a semantic search across lat.md sections.
+ * Handles indexing (with optional progress callback). Returns matched sections.
+ *
+ * `opts.buildIndex: false` is read-only mode (the UserPromptSubmit hook): search
+ * an existing index but never build or update it — so a user's first prompt in a
+ * fresh repo isn't blocked by a full local embed pass. Building the index is
+ * `lat search` / `lat reindex`. With nothing indexed yet, returns no matches
+ * without even loading the embedder to embed the query.
+ */
+export declare function runSearch(latDir: string, query: string, limit: number, progress?: IndexProgress, opts?: {
+    buildIndex?: boolean;
+    preloadedSections?: Section[];
+}): Promise<SearchResult>;
+/**
+ * Index-only mode (no query) — builds the index on first use. Rebuilding is
+ * `lat reindex`, not a flag here.
+ */
+export declare function runIndex(latDir: string, progress?: IndexProgress): Promise<void>;
+export declare function cliProgress(s: Styler): IndexProgress;
+export declare function searchCommand(ctx: CmdContext, query: string | undefined, opts: {
+    limit: number;
+}, progress?: IndexProgress): Promise<CmdResult>;