@plebeiantech/lat.md 0.12.3-fork.1

package/dist/src/cli/search.js

@@ -0,0 +1,217 @@
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { openDb, ensureMeta, getStoredModel, setStoredModel, ensureSectionsSchema, dropSections, closeDb, } from '../search/db.js';
+import { getLlmKey } from '../config.js';
+import { embedderForIndex, modelKey, ReindexRequiredError, EmbeddingAuthError, } from '../search/embedder.js';
+import { indexSections } from '../search/index.js';
+import { searchSections } from '../search/search.js';
+import { loadAllSections, flattenSections, } from '../lattice.js';
+import { formatSectionPreview, formatNavHints } from '../format.js';
+import { provenanceNote, formatProvenanceNote } from './check-status.js';
+async function withDb(latDir, progress, fn) {
+    const db = openDb(latDir);
+    try {
+        await ensureMeta(db);
+        const stored = await getStoredModel(db);
+        // The stored model is authoritative — no silent backend switch. Throws
+        // ReindexRequiredError if the environment can't serve the stored index.
+        // Rebuilding / switching backends is `lat reindex`, never `lat search`.
+        const embedder = await embedderForIndex(stored, latDir);
+        await ensureSectionsSchema(db, embedder.dimensions);
+        const countResult = await db.execute('SELECT COUNT(*) as n FROM sections');
+        let isEmpty = countResult.rows[0].n === 0;
+        // Legacy cache: a version before the model was recorded left rows behind
+        // with no `meta.embedding_model`. Those vectors may be a different backend
+        // (and dimension) than the resolved embedder, and `CREATE TABLE IF NOT
+        // EXISTS` won't migrate the column width — so drop and rebuild from scratch
+        // under the resolved backend rather than querying a mismatched table.
+        if (!stored && !isEmpty) {
+            await dropSections(db);
+            await ensureSectionsSchema(db, embedder.dimensions);
+            isEmpty = true;
+        }
+        // If the repo is pinned to local but a key is set, say so — otherwise it
+        // looks like the key is being silently ignored.
+        if (isEmpty && embedder.name.startsWith('local:') && process.stderr.isTTY) {
+            let hasKey = false;
+            try {
+                hasKey = !!getLlmKey();
+            }
+            catch {
+                /* key source misconfigured — irrelevant, we're local */
+            }
+            if (hasKey) {
+                process.stderr.write('This repo is configured for local embeddings; ignoring LAT_LLM_KEY.\n');
+            }
+        }
+        progress?.beforeIndex?.(isEmpty);
+        try {
+            const stats = await indexSections(latDir, db, embedder);
+            // Pin the backend only after a successful index, so a failed build never
+            // leaves the repo wrongly pinned to an empty index.
+            if (!stored)
+                await setStoredModel(db, modelKey(embedder));
+            progress?.afterIndex?.(stats, isEmpty);
+        }
+        catch (err) {
+            // Failed fresh build → drop the half-created table so the next run is
+            // truly fresh (re-resolves the backend cleanly) rather than stuck.
+            if (!stored)
+                await dropSections(db);
+            throw err;
+        }
+        return await fn(db, embedder);
+    }
+    finally {
+        await closeDb(db);
+    }
+}
+/** Resolve raw search hits (by id) to full section matches. */
+async function resolveMatches(latDir, results, preloadedSections) {
+    if (results.length === 0)
+        return [];
+    const allSections = preloadedSections ?? (await loadAllSections(latDir));
+    const flat = flattenSections(allSections);
+    const byId = new Map(flat.map((s) => [s.id, s]));
+    return results
+        .map((r) => byId.get(r.id))
+        .filter((s) => !!s)
+        .map((s) => ({ section: s, reason: 'semantic match' }));
+}
+/**
+ * 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 async function runSearch(latDir, query, limit, progress, opts) {
+    if (opts?.buildIndex === false) {
+        const db = openDb(latDir);
+        try {
+            await ensureMeta(db);
+            const stored = await getStoredModel(db);
+            // Never built (or a legacy pre-versioning cache) — leave building to
+            // `lat search`; don't load the embedder just to embed the query.
+            if (stored === null)
+                return { query, matches: [] };
+            const embedder = await embedderForIndex(stored, latDir);
+            await ensureSectionsSchema(db, embedder.dimensions);
+            const results = await searchSections(db, query, embedder, limit);
+            return {
+                query,
+                matches: await resolveMatches(latDir, results, opts?.preloadedSections),
+            };
+        }
+        finally {
+            await closeDb(db);
+        }
+    }
+    return withDb(latDir, progress, async (db, embedder) => {
+        const results = await searchSections(db, query, embedder, limit);
+        return {
+            query,
+            matches: await resolveMatches(latDir, results, opts?.preloadedSections),
+        };
+    });
+}
+/**
+ * Index-only mode (no query) — builds the index on first use. Rebuilding is
+ * `lat reindex`, not a flag here.
+ */
+export async function runIndex(latDir, progress) {
+    await withDb(latDir, progress, async () => { });
+}
+export function cliProgress(s) {
+    return {
+        beforeIndex(isEmpty) {
+            if (isEmpty) {
+                process.stderr.write(s.dim('Building index...'));
+            }
+        },
+        afterIndex(stats, isEmpty) {
+            if (isEmpty) {
+                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`));
+            }
+        },
+    };
+}
+/**
+ * Render search matches with each one's provenance.
+ *
+ * `formatResultList` in format.ts renders a bare list and is shared with
+ * `lat locate` and `lat refs`. Search is the surface where an agent picks a
+ * claim to act on without opening the document, so it is the one that has to
+ * say whether a person ever checked that claim. Frontmatter is read once per
+ * file rather than once per match, since several matches routinely share one.
+ */
+async function formatSearchMatches(ctx, query, matches) {
+    const notes = new Map();
+    for (const match of matches) {
+        const filePath = match.section.filePath;
+        if (notes.has(filePath))
+            continue;
+        try {
+            const content = await readFile(join(ctx.projectRoot, filePath), 'utf-8');
+            notes.set(filePath, provenanceNote(content));
+        }
+        catch {
+            notes.set(filePath, null);
+        }
+    }
+    const lines = ['', `## Search results for "${query}":`, ''];
+    for (let i = 0; i < matches.length; i++) {
+        if (i > 0)
+            lines.push('');
+        lines.push(formatSectionPreview(ctx, matches[i].section, {
+            reason: matches[i].reason,
+        }));
+        const note = notes.get(matches[i].section.filePath);
+        if (note)
+            lines.push(`  ${formatProvenanceNote(note, ctx.styler)}`);
+    }
+    lines.push('');
+    return lines.join('\n');
+}
+export async function searchCommand(ctx, query, opts, progress) {
+    const s = ctx.styler;
+    try {
+        if (!query) {
+            await runIndex(ctx.latDir, progress);
+            return { output: '' };
+        }
+        const result = await runSearch(ctx.latDir, query, opts.limit, progress);
+        if (result.matches.length === 0) {
+            return { output: 'No results found.' };
+        }
+        return {
+            output: (await formatSearchMatches(ctx, query, result.matches)) +
+                formatNavHints(ctx),
+        };
+    }
+    catch (err) {
+        // The stored index can't be served in the current environment — never
+        // switch backends silently; direct the user to `lat reindex`.
+        if (err instanceof ReindexRequiredError) {
+            return { output: s.red(err.message), isError: true };
+        }
+        if (err instanceof EmbeddingAuthError) {
+            return {
+                output: s.red(`LAT_LLM_KEY was rejected by the provider (${err.status}).`) +
+                    ' Run ' +
+                    s.cyan('lat reindex') +
+                    ' to fix the key or switch to the local model.',
+                isError: true,
+            };
+        }
+        // Config/key resolution errors (e.g. empty LAT_LLM_KEY_FILE) or other
+        // failures — surface the message rather than crashing.
+        return { output: err.message, isError: true };
+    }
+}

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

@@ -0,0 +1,43 @@
+import { type Section, type SectionMatch } from '../lattice.js';
+import type { CmdContext, CmdResult } from '../context.js';
+import { type ProvenanceNote } from './check-status.js';
+export type CodeBackRef = {
+    file: string;
+    line: number;
+    snippet: string;
+};
+export type SourceRef = {
+    target: string;
+    file: string;
+    line: number;
+    endLine: number;
+    snippet: string;
+};
+export type SectionFound = {
+    kind: 'found';
+    section: Section;
+    content: string;
+    /** Provenance of the document holding this section, or null if unmarked. */
+    status: ProvenanceNote | null;
+    outgoingRefs: {
+        target: string;
+        resolved: Section;
+    }[];
+    outgoingSourceRefs: SourceRef[];
+    incomingRefs: SectionMatch[];
+    codeRefs: CodeBackRef[];
+};
+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,252 @@
+import { readFile } from 'node:fs/promises';
+import { extname, join, relative } from 'node:path';
+import { loadAllSections, findSections, flattenSections, extractRefs, buildFileIndex, buildSectionSlugIndex, resolveRef, listLatticeFiles, } from '../lattice.js';
+import { scanCodeRefs } from '../code-refs.js';
+import { SOURCE_EXTENSIONS, resolveSourceSymbol } from '../source-parser.js';
+import { formatSectionId, formatNavHints } from '../format.js';
+import { provenanceNote, formatProvenanceNote, } from './check-status.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 the end of the last descendant
+    const absPath = join(ctx.projectRoot, section.filePath);
+    const fileContent = await readFile(absPath, 'utf-8');
+    const lines = fileContent.split('\n');
+    const end = fullEndLine(section);
+    const content = lines.slice(section.startLine - 1, end).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 slugIndex = buildSectionSlugIndex(allSections);
+    const sectionRefs = extractRefs(absPath, fileContent, ctx.projectRoot);
+    const sectionId = section.id.toLowerCase();
+    const outgoingRefs = [];
+    const outgoingSourceRefs = [];
+    const seen = new Set();
+    for (const ref of sectionRefs) {
+        if (ref.fromSection.toLowerCase() !== sectionId)
+            continue;
+        // Detect source code references by file extension
+        const hashIdx = ref.target.indexOf('#');
+        const filePart = hashIdx === -1 ? ref.target : ref.target.slice(0, hashIdx);
+        const ext = extname(filePart);
+        if (SOURCE_EXTENSIONS.has(ext)) {
+            const targetLower = ref.target.toLowerCase();
+            if (!seen.has(targetLower)) {
+                seen.add(targetLower);
+                const symbolPart = hashIdx === -1 ? '' : ref.target.slice(hashIdx + 1);
+                let line = 0;
+                let endLine = 0;
+                let snippet = '';
+                if (symbolPart) {
+                    const { found, symbols } = await resolveSourceSymbol(filePart, symbolPart, ctx.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) {
+                            line = sym.startLine;
+                            endLine = sym.endLine;
+                            try {
+                                const src = await readFile(join(ctx.projectRoot, filePart), 'utf-8');
+                                const srcLines = src.split('\n');
+                                const start = sym.startLine - 1;
+                                const end = Math.min(srcLines.length, start + 5);
+                                snippet = srcLines.slice(start, end).join('\n');
+                            }
+                            catch {
+                                // file unreadable
+                            }
+                        }
+                    }
+                }
+                outgoingSourceRefs.push({
+                    target: ref.target,
+                    file: filePart,
+                    line,
+                    endLine,
+                    snippet,
+                });
+            }
+            continue;
+        }
+        const { resolved } = resolveRef(ref.target, sectionIds, fileIndex, slugIndex);
+        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, slugIndex);
+            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' });
+                    }
+                }
+            }
+        }
+    }
+    // Find code back-references: @lat: comments pointing to this section
+    const codeRefs = [];
+    const { refs: scannedRefs } = await scanCodeRefs(ctx.projectRoot);
+    for (const ref of scannedRefs) {
+        const { resolved: codeResolved } = resolveRef(ref.target, sectionIds, fileIndex, slugIndex);
+        if (codeResolved.toLowerCase() === sectionId) {
+            const absFile = join(ctx.projectRoot, ref.file);
+            let snippet = '';
+            try {
+                const src = await readFile(absFile, 'utf-8');
+                const srcLines = src.split('\n');
+                const start = Math.max(0, ref.line - 1 - 2);
+                const end = Math.min(srcLines.length, ref.line - 1 + 3);
+                snippet = srcLines.slice(start, end).join('\n');
+            }
+            catch {
+                // file unreadable — skip snippet
+            }
+            codeRefs.push({ file: ref.file, line: ref.line, snippet });
+        }
+    }
+    return {
+        kind: 'found',
+        section,
+        content,
+        status: provenanceNote(fileContent),
+        outgoingRefs,
+        outgoingSourceRefs,
+        incomingRefs,
+        codeRefs,
+    };
+}
+function fullEndLine(section) {
+    if (section.children.length === 0)
+        return section.endLine;
+    return fullEndLine(section.children[section.children.length - 1]);
+}
+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, status, outgoingRefs, outgoingSourceRefs, incomingRefs, codeRefs, } = result;
+    const relPath = relative(process.cwd(), join(ctx.projectRoot, section.filePath));
+    const loc = `${s.cyan(relPath)}${s.dim(`:${section.startLine}-${section.endLine}`)}`;
+    const quoted = content
+        .split('\n')
+        .map((line) => (line ? `> ${line}` : '>'))
+        .join('\n');
+    const parts = [
+        `${s.bold('[[' + formatSectionId(section.id, s) + ']]')} (${loc})`,
+    ];
+    // Above the text, not below it: a reader who acts on the first line of a
+    // quoted section has already acted before a trailing caveat reaches them.
+    if (status)
+        parts.push(formatProvenanceNote(status, s));
+    parts.push('', quoted);
+    if (outgoingRefs.length > 0 || outgoingSourceRefs.length > 0) {
+        parts.push('', '## 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}`);
+        }
+        for (const ref of outgoingSourceRefs) {
+            const loc = ref.line
+                ? ref.endLine && ref.endLine !== ref.line
+                    ? `${s.dim(` (${ref.file}:${ref.line}-${ref.endLine})`)}`
+                    : `${s.dim(` (${ref.file}:${ref.line})`)}`
+                : `${s.dim(` (${ref.file})`)}`;
+            parts.push(`${s.dim('*')} [[${s.cyan(ref.target)}]]${loc}`);
+            if (ref.snippet) {
+                const snippetLines = ref.snippet.split('\n');
+                for (const line of snippetLines) {
+                    parts.push(`  ${s.dim('|')} ${line}`);
+                }
+            }
+        }
+    }
+    if (incomingRefs.length > 0) {
+        parts.push('', '## 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}`);
+        }
+    }
+    if (codeRefs.length > 0) {
+        parts.push('', '## Referenced by code:', '');
+        for (const ref of codeRefs) {
+            const codeRelPath = relative(process.cwd(), join(ctx.projectRoot, ref.file));
+            parts.push(`${s.dim('*')} ${s.cyan(codeRelPath)}${s.dim(`:${ref.line}`)}`);
+            if (ref.snippet) {
+                const snippetLines = ref.snippet.split('\n');
+                for (const line of snippetLines) {
+                    parts.push(`  ${s.dim('|')} ${line}`);
+                }
+            }
+        }
+    }
+    parts.push(formatNavHints(ctx));
+    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/cli/select-menu.d.ts

@@ -0,0 +1,13 @@
+export interface SelectOption {
+    label: string;
+    value: string;
+    /** If true, this option uses a distinct highlight style (e.g. for "done" actions). */
+    accent?: boolean;
+}
+/**
+ * Display an interactive select menu with arrow-key navigation.
+ * Returns the selected option's value, or null if the user pressed Ctrl+C.
+ *
+ * @param defaultIndex - initial cursor position (defaults to 0)
+ */
+export declare function selectMenu(options: SelectOption[], prompt?: string, defaultIndex?: number): Promise<string | null>;

package/dist/src/cli/select-menu.js

@@ -0,0 +1,100 @@
+import { styleText } from 'node:util';
+/**
+ * Display an interactive select menu with arrow-key navigation.
+ * Returns the selected option's value, or null if the user pressed Ctrl+C.
+ *
+ * @param defaultIndex - initial cursor position (defaults to 0)
+ */
+export async function selectMenu(options, prompt, defaultIndex) {
+    if (options.length === 0)
+        return null;
+    if (!process.stdin.isTTY) {
+        // Non-interactive fallback: return first option
+        return options[0].value;
+    }
+    return new Promise((resolve) => {
+        let cursor = defaultIndex ?? 0;
+        const stdin = process.stdin;
+        // Save original stdin state
+        const wasRaw = stdin.isRaw;
+        stdin.setRawMode(true);
+        stdin.resume();
+        stdin.setEncoding('utf-8');
+        function render() {
+            process.stdout.write('\x1B[?25l'); // hide cursor
+            const lines = [];
+            if (prompt) {
+                lines.push(styleText('bold', prompt));
+            }
+            for (let i = 0; i < options.length; i++) {
+                const opt = options[i];
+                const selected = i === cursor;
+                const pointer = selected ? '❯' : ' ';
+                if (selected) {
+                    if (opt.accent) {
+                        lines.push(`  ${pointer} ${styleText(['bgGreen', 'black', 'bold'], ` ${opt.label} `)}`);
+                    }
+                    else {
+                        lines.push(`  ${pointer} ${styleText(['bgCyan', 'black', 'bold'], ` ${opt.label} `)}`);
+                    }
+                }
+                else {
+                    lines.push(`  ${pointer} ${styleText('dim', opt.label)}`);
+                }
+            }
+            process.stdout.write(lines.join('\n') + '\n');
+        }
+        function clearRender() {
+            const totalLines = options.length + (prompt ? 1 : 0);
+            // Move up and clear each line
+            for (let i = 0; i < totalLines; i++) {
+                process.stdout.write('\x1B[A\x1B[2K');
+            }
+        }
+        function cleanup() {
+            stdin.setRawMode(wasRaw ?? false);
+            stdin.pause();
+            process.stdout.write('\x1B[?25h'); // show cursor
+            stdin.removeListener('data', onData);
+        }
+        function onData(data) {
+            const key = data.toString();
+            // Ctrl+C
+            if (key === '\x03') {
+                clearRender();
+                cleanup();
+                console.log('');
+                process.exit(130);
+            }
+            // Enter
+            if (key === '\r' || key === '\n') {
+                clearRender();
+                cleanup();
+                const selected = options[cursor];
+                // Print the selection
+                if (prompt) {
+                    console.log(styleText('bold', prompt) +
+                        ' ' +
+                        styleText('green', selected.label));
+                }
+                resolve(selected.value);
+                return;
+            }
+            // Arrow keys (escape sequences)
+            if (key === '\x1B[A' || key === 'k') {
+                // Up
+                clearRender();
+                cursor = (cursor - 1 + options.length) % options.length;
+                render();
+            }
+            else if (key === '\x1B[B' || key === 'j') {
+                // Down
+                clearRender();
+                cursor = (cursor + 1) % options.length;
+                render();
+            }
+        }
+        stdin.on('data', onData);
+        render();
+    });
+}

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

@@ -0,0 +1 @@
+export declare function findTemplatesDir(): string;

package/dist/src/cli/templates.js

@@ -0,0 +1,15 @@
+import { existsSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+export function findTemplatesDir() {
+    let dir = dirname(fileURLToPath(import.meta.url));
+    while (true) {
+        const candidate = join(dir, 'templates');
+        if (existsSync(candidate))
+            return candidate;
+        const parent = dirname(dir);
+        if (parent === dir)
+            throw new Error('templates directory not found');
+        dir = parent;
+    }
+}

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

@@ -0,0 +1,11 @@
+import type { CmdContext, CmdResult } from '../context.js';
+import { type ViewServer, type ViewServerOptions } from '../view/server.js';
+type UiCommandOptions = ViewServerOptions & {
+    openBrowser?: (url: string) => Promise<void>;
+    onStarted?: (server: ViewServer) => void;
+};
+/** Launch the platform browser without passing the URL through a shell. */
+export declare function openBrowser(url: string): Promise<void>;
+/** Start `lat ui`, report its URL, and launch the default browser. */
+export declare function uiCommand(ctx: CmdContext, options?: UiCommandOptions): Promise<CmdResult>;
+export {};