@plebeiantech/lat.md 0.12.3-fork.15 → 0.12.3-fork.17

package/README.md

@@ -103,7 +103,7 @@ Alternatively, install `@plebeiantech/lat.md` via npm/mise, run `lat init` in yo
 
 ## How it works
 
-Run `lat init` to scaffold a `lat.md/` directory, then write markdown files describing your architecture, business logic, test specs — whatever matters. Link between sections using `[[file#Section#Subsection]]` syntax. Link to source code symbols with `[[src/auth.ts#validateToken]]`. Annotate source code with `// @lat: [[section-id]]` (or `# @lat: [[section-id]]` in Python) comments to tie implementation back to concepts.
+Run `lat init` to scaffold a `lat.md/` directory, then write markdown files describing your architecture, business logic, test specs — whatever matters. Link between sections using `[[file#Section#Subsection]]` syntax. Link to source code symbols with `[[src/auth.ts#validateToken]]`. Annotate source code with `// @lat: [[section-id]]` (or `# @lat: [[section-id]]` in Python and PHP) comments to tie implementation back to concepts.
 
 ```
 my-project/

package/dist/src/cli/checklist-menu.d.ts

@@ -5,8 +5,9 @@ export interface ChecklistOption {
 /**
  * Display an interactive multi-select checklist with arrow-key navigation.
  * Returns an array of checked values.
+ * Known initial values start checked; unknown values are ignored.
  *
  * Keys: Up/Down (j/k) to move, Space to toggle, Enter to confirm, Ctrl+C to exit.
  * Non-TTY fallback: returns [].
  */
-export declare function checklistMenu(options: ChecklistOption[], prompt?: string): Promise<string[]>;
+export declare function checklistMenu(options: ChecklistOption[], prompt?: string, initialValues?: readonly string[]): Promise<string[]>;

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

@@ -2,18 +2,19 @@ import { styleText } from 'node:util';
 /**
  * Display an interactive multi-select checklist with arrow-key navigation.
  * Returns an array of checked values.
+ * Known initial values start checked; unknown values are ignored.
  *
  * Keys: Up/Down (j/k) to move, Space to toggle, Enter to confirm, Ctrl+C to exit.
  * Non-TTY fallback: returns [].
  */
-export async function checklistMenu(options, prompt) {
+export async function checklistMenu(options, prompt, initialValues = []) {
     if (options.length === 0)
         return [];
     if (!process.stdin.isTTY)
         return [];
     return new Promise((resolve) => {
         let cursor = 0;
-        const checked = new Set();
+        const checked = new Set(options.flatMap((option, index) => initialValues.includes(option.value) ? [index] : []));
         const stdin = process.stdin;
         const wasRaw = stdin.isRaw;
         stdin.setRawMode(true);

package/dist/src/cli/index.js

@@ -8,7 +8,7 @@ import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { Command, InvalidArgumentError } from 'commander';
 import { resolveCheckContext, resolveContext } from './context.js';
-import { DEFAULT_SEARCH_LIMIT, DEFAULT_SEARCH_THRESHOLD, } from '../search/search.js';
+import { DEFAULT_SEARCH_LIMIT, DEFAULT_MIN_SIMILARITY, } from '../search/search.js';
 function parsePort(value) {
     if (!/^\d+$/.test(value)) {
         throw new InvalidArgumentError('port must be an integer from 1 to 65535');
@@ -19,10 +19,22 @@ function parsePort(value) {
     }
     return port;
 }
+function parseUiServerBuildTarget(value) {
+    if (value !== 'node' && value !== 'vercel') {
+        throw new InvalidArgumentError('target must be node or vercel');
+    }
+    return value;
+}
+function configureUiRun(command) {
+    return command
+        .option('--logo-text <text>', 'top-left logo text')
+        .option('--no-git', 'disable Git working-tree integration')
+        .option('--port <number>', 'server port (default: 4242; explicit ports are strict)', parsePort);
+}
 function parseSimilarityThreshold(value) {
     const threshold = Number(value);
     if (!Number.isFinite(threshold) || threshold < 0 || threshold > 1) {
-        throw new InvalidArgumentError('threshold must be a number from 0 to 1');
+        throw new InvalidArgumentError('min-similarity must be a number from 0 to 1');
     }
     return threshold;
 }
@@ -108,27 +120,52 @@ program
     const { sectionCommand } = await import('./section.js');
     handleResult(await sectionCommand(ctx, query));
 });
-const ui = program
-    .command('ui')
-    .description('Open lat.md in a local browser')
-    .option('--logo-text <text>', 'top-left logo text')
-    .option('--port <number>', 'server port (default: 4242; explicit ports are strict)', parsePort)
-    .action(async (opts) => {
+async function runUi(opts) {
     const ctx = resolveContext(program.opts());
     const { uiCommand } = await import('./ui.js');
-    handleResult(await uiCommand(ctx, { logoText: opts.logoText, port: opts.port }));
+    handleResult(await uiCommand(ctx, {
+        git: opts.git,
+        logoText: opts.logoText,
+        port: opts.port,
+    }));
+}
+const ui = configureUiRun(program.command('ui').description('Run or build the Lat UI')).action(runUi);
+configureUiRun(ui.command('run').description('Run the local Lat UI server')).action(async (opts) => {
+    await runUi(opts);
 });
-ui.command('build')
-    .description('Export lat.md as a static website')
-    .argument('[output]', 'output directory relative to the project', 'lat-ui')
+const uiBuild = ui.command('build').description('Build a deployable Lat UI');
+uiBuild
+    .command('static')
+    .description('Build a fully static, read-only Lat UI')
+    .argument('[output]', 'output directory relative to the project (default: .lat-build/static)', '.lat-build/static')
     .option('--base <path>', 'deployment base path', '/')
+    .option('--force', 'replace an existing output path')
     .option('--logo-text <text>', 'top-left logo text')
     .action(async (output, opts) => {
     const ctx = resolveContext(program.opts());
     const { uiBuildCommand } = await import('./ui-build.js');
     handleResult(await uiBuildCommand(ctx, output, {
         basePath: opts.base,
+        force: opts.force,
+        logoText: opts.logoText ?? ui.opts().logoText,
+    }));
+});
+uiBuild
+    .command('server')
+    .description('Build a static Lat UI with a portable search server')
+    .argument('[output]', 'output directory (default: .lat-build/server for node, .vercel/output for vercel)')
+    .option('--base <path>', 'deployment base path', '/')
+    .option('--force', 'replace an existing output path')
+    .option('--logo-text <text>', 'top-left logo text')
+    .option('--target <target>', 'deployment target: node or vercel', parseUiServerBuildTarget, 'node')
+    .action(async (output, opts) => {
+    const ctx = resolveContext(program.opts());
+    const { uiBuildServerCommand } = await import('./ui-build-server.js');
+    handleResult(await uiBuildServerCommand(ctx, output, {
+        basePath: opts.base,
+        force: opts.force,
         logoText: opts.logoText ?? ui.opts().logoText,
+        target: opts.target,
     }));
 });
 program
@@ -302,11 +339,16 @@ program
 });
 program
     .command('search')
-    .description('Semantic search across lat.md sections')
+    .description('Hybrid search across lat.md sections')
     .argument('[query]', 'search query in plain English')
     .option('--limit <n>', `max results (default: ${DEFAULT_SEARCH_LIMIT})`, String(DEFAULT_SEARCH_LIMIT))
-    .option('--debug', 'show result similarity scores')
-    .option('--threshold <score>', `minimum cosine similarity score (default: ${DEFAULT_SEARCH_THRESHOLD})`, parseSimilarityThreshold)
+    .option('--preview <variant>', 'preview passage, intro, or both', (value) => {
+    if (!['passage', 'intro', 'both'].includes(value))
+        throw new InvalidArgumentError('preview must be passage, intro, or both');
+    return value;
+}, 'passage')
+    .option('--debug', 'show retrieval scores and candidate diagnostics')
+    .option('--min-similarity <score>', `minimum cosine similarity score (default: ${DEFAULT_MIN_SIMILARITY})`, parseSimilarityThreshold)
     .action(async (query, opts) => {
     const ctx = resolveContext(program.opts());
     const { searchCommand, cliProgress } = await import('./search.js');
@@ -314,7 +356,8 @@ program
     const result = await searchCommand(ctx, query, {
         limit: parseInt(opts.limit),
         debug: opts.debug,
-        threshold: opts.threshold,
+        minSimilarity: opts.minSimilarity,
+        preview: opts.preview,
     }, progress);
     handleResult(result);
 });

package/dist/src/cli/init-preferences.d.ts

@@ -0,0 +1,4 @@
+/** Read machine-local checklist defaults without inferring installed agents. */
+export declare function readInitAgents(latDir: string): string[];
+/** Update just the confirmed selection, preserving other YAML and comments. */
+export declare function writeInitAgents(latDir: string, agents: string[]): void;

package/dist/src/cli/init-preferences.js

@@ -0,0 +1,35 @@
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { isMap, parseDocument } from 'yaml';
+function readPreferences(latDir) {
+    const path = join(latDir, 'config.local.yaml');
+    const document = parseDocument(existsSync(path) ? readFileSync(path, 'utf8') : '');
+    if (document.errors.length > 0) {
+        throw new Error(`Cannot parse ${path}: ${document.errors[0].message}`);
+    }
+    if (document.contents !== null && !isMap(document.contents)) {
+        throw new Error(`${path} must be a mapping`);
+    }
+    if (document.has('init') && !isMap(document.get('init', true))) {
+        throw new Error(`${path}: init must be a mapping`);
+    }
+    return { path, document };
+}
+/** Read machine-local checklist defaults without inferring installed agents. */
+export function readInitAgents(latDir) {
+    const { path, document } = readPreferences(latDir);
+    const agents = document.toJS()?.init?.agents;
+    if (agents === undefined)
+        return [];
+    if (!Array.isArray(agents) ||
+        agents.some((agent) => typeof agent !== 'string')) {
+        throw new Error(`${path}: init.agents must be a list of strings`);
+    }
+    return agents;
+}
+/** Update just the confirmed selection, preserving other YAML and comments. */
+export function writeInitAgents(latDir, agents) {
+    const { path, document } = readPreferences(latDir);
+    document.setIn(['init', 'agents'], agents);
+    writeFileSync(path, document.toString());
+}

package/dist/src/cli/init.js

@@ -8,7 +8,7 @@ import { findTemplatesDir } from './templates.js';
 import { readAgentsTemplate, readCursorRulesTemplate, readPiExtensionTemplate, readOpenCodePluginTemplate, readSkillTemplate, } from './gen.js';
 import { getLlmKey, getRepoEmbedding, setRepoEmbedding } from '../config.js';
 import { makeStyler } from './context.js';
-import { closeDb, ensureMeta, getStoredModel, openDb } from '../search/db.js';
+import { closeDb, getStoredModel, openDb } from '../search/db.js';
 import { modelKey } from '../search/embedder.js';
 import { reindexCommand } from './reindex.js';
 import { INIT_VERSION, writeInitMeta, readInitVersion, readFileHash, contentHash, } from '../init-version.js';
@@ -18,6 +18,7 @@ import { checklistMenu } from './checklist-menu.js';
 import { writeForkInstructions } from './fork-instructions.js';
 import { offerRequireMode, writeForkScaffold } from './fork-scaffold.js';
 import { setupAntigravity } from '../fork/antigravity-init.js';
+import { readInitAgents, writeInitAgents } from './init-preferences.js';
 async function confirm(rl, message) {
     while (true) {
         let answer;
@@ -667,11 +668,10 @@ async function setupCodex(root, latDir, hashes, ask, style) {
         ' Run /hooks in Codex to review and trust the project hooks.');
 }
 async function readStoredEmbeddingModel(latDir) {
-    if (!existsSync(join(latDir, '.cache', 'vectors.db')))
+    if (!existsSync(join(latDir, '.cache', 'search.db')))
         return null;
-    const db = openDb(latDir);
+    const db = openDb(latDir, undefined, true);
     try {
-        await ensureMeta(db);
         return await getStoredModel(db);
     }
     finally {
@@ -916,6 +916,7 @@ export async function initCmd(targetDir) {
             writeForkScaffold(latDir);
         }
         ensureLatLocalConfigIgnored(latDir);
+        ensureGitignored(root, '.lat-build');
         // Step 2: Configure fresh/outdated setups, ask interactive users about an
         // available key, and offer to rebuild an index whose backend differs. This
         // happens before agent selection so "no agents" still completes it.
@@ -931,7 +932,7 @@ export async function initCmd(targetDir) {
             { label: 'Codex', value: 'codex' },
             { label: 'Antigravity / Gemini', value: 'antigravity' },
         ];
-        const selectedAgents = await checklistMenu(allAgents, 'Which coding agents do you use?');
+        const selectedAgents = await checklistMenu(allAgents, 'Which coding agents do you use?', readInitAgents(latDir));
         const useClaudeCode = selectedAgents.includes('claude');
         const usePi = selectedAgents.includes('pi');
         const useCursor = selectedAgents.includes('cursor');
@@ -978,6 +979,8 @@ export async function initCmd(targetDir) {
             // agent. Stamp the version so future non-interactive runs do not reapply
             // fresh/outdated defaults and overwrite the chosen backend.
             writeInitMeta(latDir, {});
+            if (interactive)
+                writeInitAgents(latDir, selectedAgents);
             console.log('');
             console.log(styleText('dim', 'No agents selected. You can re-run') +
                 ' lat init ' +
@@ -1049,6 +1052,8 @@ export async function initCmd(targetDir) {
         await writeForkInstructions(root, latDir, fileHashes, ask);
         // Record init version and file hashes so `lat check` can detect stale setups
         writeInitMeta(latDir, fileHashes);
+        if (interactive)
+            writeInitAgents(latDir, selectedAgents);
         console.log('');
         console.log(styleText('green', 'Done!') +
             ' Run ' +

package/dist/src/cli/reindex.js

@@ -1,5 +1,6 @@
+import { writeIndex } from '../search/cache.js';
 import readline from 'node:readline/promises';
-import { openDb, ensureMeta, setStoredModel, ensureSectionsSchema, dropSections, closeDb, } from '../search/db.js';
+import { ensureMeta, setStoredModel, ensureSectionsSchema, dropSections, } 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';
@@ -83,11 +84,9 @@ export async function reindexCommand(ctx, opts) {
             embedder = await localEmbedder();
         }
     }
-    const db = openDb(ctx.latDir);
     const interactive = ctx.mode === 'cli' && !!process.stderr.isTTY;
-    try {
+    return writeIndex(ctx.latDir, undefined, true, async (db) => {
         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
@@ -130,8 +129,5 @@ export async function reindexCommand(ctx, opts) {
             output: s.green(`Reindexed ${stats.added} sections`) +
                 ` using ${s.cyan(embedder.name)}.`,
         };
-    }
-    finally {
-        await closeDb(db);
-    }
+    });
 }

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

@@ -27,7 +27,7 @@ export declare function runSearch(latDir: string, query: string, limit: number,
     buildIndex?: boolean;
     project?: MarkdownProjectAnalysis;
     sectionById?: ReadonlyMap<string, Section>;
-    threshold?: number;
+    minSimilarity?: number;
     cacheDir?: string;
 }): Promise<SearchResult>;
 /**
@@ -41,5 +41,6 @@ export declare function cliProgress(s: Styler): IndexProgress;
 export declare function searchCommand(ctx: CmdContext, query: string | undefined, opts: {
     limit: number;
     debug?: boolean;
-    threshold?: number;
+    minSimilarity?: number;
+    preview?: 'passage' | 'intro' | 'both';
 }, progress?: IndexProgress): Promise<CmdResult>;

package/dist/src/cli/search.js

@@ -1,71 +1,55 @@
 import { readFile } from 'node:fs/promises';
+import { LEXICAL_VERSION } from '../search/lexical.js';
+import { hasIndex } from '../search/db.js';
+import { embeddingFingerprint } from '../search/chunks.js';
+import { writeIndex } from '../search/cache.js';
 import { dirname, join } from 'node:path';
-import { openDb, ensureMeta, getStoredModel, setStoredModel, ensureSectionsSchema, dropSections, closeDb, } from '../search/db.js';
-import { getLlmKey } from '../config.js';
+import { openDb, getStoredModel, setStoredModel, ensureSectionsSchema, closeDb, } from '../search/db.js';
 import { embedderForIndex, modelKey, ReindexRequiredError, EmbeddingAuthError, } from '../search/embedder.js';
-import { indexSections } from '../search/index.js';
+import { indexSections, projectFingerprint, } from '../search/index.js';
 import { searchSections } from '../search/search.js';
-import { searchIndexedSections } from '../search/query.js';
+import { resolveSearchMatches, searchIndexedSections, } from '../search/query.js';
 import { analyzeMarkdownProject, commandProjectAnalysis, } from '../project-analysis.js';
 import { formatSectionPreview, formatNavHints } from '../format.js';
 import { provenanceNote, formatProvenanceNote } from './check-status.js';
 async function withDb(latDir, progress, project, cacheDir, fn) {
-    const db = openDb(latDir, cacheDir);
-    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);
+    if (hasIndex(cacheDir ?? join(latDir, '.cache'))) {
+        const db = openDb(latDir, cacheDir, true);
         try {
-            const stats = await indexSections(latDir, db, embedder, undefined, project);
-            // 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);
+            const stored = await getStoredModel(db);
+            const embedder = await embedderForIndex(stored, latDir);
+            const metadata = new Map((await db.execute('SELECT key,value FROM meta')).rows.map((row) => [
+                row.key,
+                row.value,
+            ]));
+            if (metadata.get('fingerprint') !== embeddingFingerprint(embedder))
+                throw new ReindexRequiredError('Search chunking or embedding model changed; run lat reindex.');
+            if (stored &&
+                metadata.get('lexical_version') === LEXICAL_VERSION &&
+                metadata.get('project_hash') === projectFingerprint(project)) {
+                progress?.afterIndex?.({
+                    added: 0,
+                    updated: 0,
+                    removed: 0,
+                    unchanged: project.sections.length,
+                }, false);
+                return await fn(db, embedder, project);
+            }
         }
-        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;
+        finally {
+            await closeDb(db);
         }
-        return await fn(db, embedder, project);
-    }
-    finally {
-        await closeDb(db);
     }
+    return writeIndex(latDir, cacheDir, false, async (db, stored) => {
+        const embedder = await embedderForIndex(stored, latDir);
+        await ensureSectionsSchema(db, embedder.dimensions);
+        const isEmpty = (await db.execute('SELECT COUNT(*) AS n FROM sections')).rows[0].n === 0;
+        progress?.beforeIndex?.(isEmpty);
+        const stats = await indexSections(latDir, db, embedder, undefined, project);
+        await setStoredModel(db, modelKey(embedder));
+        progress?.afterIndex?.(stats, isEmpty);
+        return fn(db, embedder, project);
+    });
 }
 /**
  * Run a semantic search across lat.md sections.
@@ -86,7 +70,7 @@ export async function runSearch(latDir, query, limit, progress, opts) {
             })).sectionById;
         return searchIndexedSections(latDir, query, limit, sectionById, {
             cacheDir: opts.cacheDir,
-            threshold: opts.threshold,
+            minSimilarity: opts.minSimilarity,
         });
     }
     const project = opts?.project ??
@@ -94,15 +78,10 @@ export async function runSearch(latDir, query, limit, progress, opts) {
             executor: 'auto',
         }));
     return withDb(latDir, progress, project, opts?.cacheDir, async (db, embedder, analyzed) => {
-        const results = await searchSections(db, query, embedder, limit, opts?.threshold);
+        const results = await searchSections(db, query, embedder, limit, opts?.minSimilarity);
         return {
             query,
-            matches: results.flatMap((result) => {
-                const section = analyzed.sectionById.get(result.id.toLowerCase());
-                return section
-                    ? [{ section, reason: 'semantic match', score: result.score }]
-                    : [];
-            }),
+            matches: resolveSearchMatches(results, analyzed.sectionById),
         };
     });
 }
@@ -163,7 +142,32 @@ async function formatSearchMatches(ctx, query, matches, opts) {
             lines.push('');
         lines.push(formatSectionPreview(ctx, matches[i].section, {
             reason: matches[i].reason,
-            score: opts?.showScores ? matches[i].score : undefined,
+            spans: opts?.preview === 'intro'
+                ? undefined
+                : matches[i].evidence?.[0]?.spans,
+            score: opts?.showScores ? matches[i].rankScore : undefined,
+            text: opts?.preview === 'intro'
+                ? undefined
+                : matches[i].evidence?.length
+                    ? (opts?.preview === 'both'
+                        ? matches[i].section.firstParagraph + '\n\n'
+                        : '') + matches[i].evidence[0].text
+                    : undefined,
+            debug: opts?.showScores && matches[i].rankScore !== undefined
+                ? JSON.stringify({
+                    lexicalRank: matches[i].lexicalRank,
+                    semanticRank: matches[i].semanticRank,
+                    lexicalScore: matches[i].lexicalScore,
+                    semanticSimilarity: matches[i].semanticSimilarity,
+                    lexicalContribution: matches[i].lexicalRank
+                        ? 1 / (60 + matches[i].lexicalRank)
+                        : 0,
+                    semanticContribution: matches[i].semanticRank
+                        ? 1 / (60 + matches[i].semanticRank)
+                        : 0,
+                    ...matches[i].diagnostics,
+                })
+                : undefined,
         }));
         const note = notes.get(matches[i].section.filePath);
         if (note)
@@ -182,7 +186,7 @@ export async function searchCommand(ctx, query, opts, progress) {
         const project = await commandProjectAnalysis(ctx);
         const result = await runSearch(ctx.latDir, query, opts.limit, progress, {
             project,
-            threshold: opts.threshold,
+            minSimilarity: opts.minSimilarity,
         });
         if (result.matches.length === 0) {
             return { output: 'No results found.' };
@@ -190,6 +194,7 @@ export async function searchCommand(ctx, query, opts, progress) {
         return {
             output: (await formatSearchMatches(ctx, query, result.matches, {
                 showScores: opts.debug,
+                preview: opts.preview ?? 'passage',
             })) + formatNavHints(ctx),
         };
     }

package/dist/src/cli/ui-build-server.d.ts

@@ -0,0 +1,12 @@
+import type { CmdContext, CmdResult } from '../context.js';
+import { buildServerView, type ServerViewBuildOptions, type ServerViewBuildResult } from '../view/server-build.js';
+export type ServerViewBuildTarget = 'node' | 'vercel';
+export type UiBuildServerOptions = ServerViewBuildOptions & {
+    target?: ServerViewBuildTarget;
+};
+export type UiBuildServerDependencies = {
+    buildNode: typeof buildServerView;
+    buildVercel?: (ctx: CmdContext, output: string, options: ServerViewBuildOptions) => Promise<ServerViewBuildResult>;
+};
+/** Export immutable UI data with a Node or Vercel semantic-search service. */
+export declare function uiBuildServerCommand(ctx: CmdContext, output: string | undefined, options?: UiBuildServerOptions, dependencies?: UiBuildServerDependencies): Promise<CmdResult>;

package/dist/src/cli/ui-build-server.js

@@ -0,0 +1,26 @@
+import { buildServerView, } from '../view/server-build.js';
+const defaultDependencies = {
+    buildNode: buildServerView,
+};
+/** Export immutable UI data with a Node or Vercel semantic-search service. */
+export async function uiBuildServerCommand(ctx, output, options = {}, dependencies = defaultDependencies) {
+    try {
+        const { target = 'node', ...buildOptions } = options;
+        const resolvedOutput = output ?? (target === 'vercel' ? '.vercel/output' : '.lat-build/server');
+        let result;
+        if (target === 'vercel') {
+            const buildVercel = dependencies.buildVercel ??
+                (await import('../view/vercel-server-build.js')).buildVercelServerView;
+            result = await buildVercel(ctx, resolvedOutput, buildOptions);
+        }
+        else {
+            result = await dependencies.buildNode(ctx, resolvedOutput, buildOptions);
+        }
+        return {
+            output: `Built ${result.documents} documents and ${result.sources} source views for ${target} at ${result.outputDir}`,
+        };
+    }
+    catch (error) {
+        return { output: error.message, isError: true };
+    }
+}

package/dist/src/cli/ui-build.js

@@ -1,6 +1,6 @@
 import { buildStaticView, } from '../view/static-build.js';
 /** Export the current vault as a serverless, read-only Lat UI. */
-export async function uiBuildCommand(ctx, output = 'lat-ui', options = {}) {
+export async function uiBuildCommand(ctx, output = '.lat-build/static', options = {}) {
     try {
         const result = await buildStaticView(ctx, output, options);
         return {

package/dist/src/cli/ui.js

@@ -38,7 +38,7 @@ export async function uiCommand(ctx, options = {}) {
     options.onStarted?.(server);
     const lines = [
         `Viewing lat.md at ${server.url}`,
-        'Note: you can use `lat ui build` to build a static version of the UI',
+        'Note: use `lat ui build static` or `lat ui build server` to build a deployable UI',
     ];
     try {
         await (options.openBrowser ?? openBrowser)(server.url);

package/dist/src/format.d.ts

@@ -1,11 +1,16 @@
+import type { SourceSpan } from './search/types.js';
 import type { Section, SectionMatch } from './lattice-model.js';
 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;
     score?: number;
+    text?: string;
+    debug?: string;
+    spans?: SourceSpan[];
 }): string;
 export declare function formatResultList(ctx: CmdContext, header: string, matches: SectionMatch[], opts?: {
     showScores?: boolean;
+    preview?: 'passage' | 'intro' | 'both';
 }): string;
 export declare function formatNavHints(ctx: CmdContext): string;

package/dist/src/format.js

@@ -12,6 +12,7 @@ export function formatSectionPreview(ctx, section, opts) {
     const kind = section.id.includes('#') ? 'Section' : 'File';
     const details = [
         opts?.reason,
+        opts?.debug,
         opts?.score === undefined ? undefined : `score: ${opts.score.toFixed(6)}`,
     ].filter((detail) => detail !== undefined);
     const detailsSuffix = details.length > 0 ? ' ' + s.dim(`(${details.join(', ')})`) : '';
@@ -19,9 +20,11 @@ export function formatSectionPreview(ctx, section, opts) {
         `${s.dim('*')} ${s.dim(kind + ':')} [[${formatSectionId(section.id, s)}]]${detailsSuffix}`,
         `  ${s.dim('Defined in')} ${s.cyan(relPath)}${s.dim(`:${section.startLine}-${section.endLine}`)}`,
     ];
-    if (section.firstParagraph) {
-        lines.push('', `  ${s.dim('>')} ${section.firstParagraph}`);
-    }
+    if (opts?.spans?.length)
+        lines.push(`  ${s.dim('Matched lines:')} ${opts.spans.map((span) => `${span.startLine}-${span.endLine}`).join(', ')}`);
+    const text = opts?.text ?? section.firstParagraph;
+    if (text)
+        lines.push('', ...text.split('\n').map((line) => `  ${s.dim('>')} ${line}`));
     return lines.join('\n');
 }
 export function formatResultList(ctx, header, matches, opts) {
@@ -31,7 +34,32 @@ export function formatResultList(ctx, header, matches, opts) {
             lines.push('');
         lines.push(formatSectionPreview(ctx, matches[i].section, {
             reason: matches[i].reason,
-            score: opts?.showScores ? matches[i].score : undefined,
+            spans: opts?.preview === 'intro'
+                ? undefined
+                : matches[i].evidence?.[0]?.spans,
+            score: opts?.showScores ? matches[i].rankScore : undefined,
+            text: opts?.preview === 'intro'
+                ? undefined
+                : matches[i].evidence?.length
+                    ? (opts?.preview === 'both'
+                        ? matches[i].section.firstParagraph + '\n\n'
+                        : '') + matches[i].evidence[0].text
+                    : undefined,
+            debug: opts?.showScores && matches[i].rankScore !== undefined
+                ? JSON.stringify({
+                    lexicalRank: matches[i].lexicalRank,
+                    semanticRank: matches[i].semanticRank,
+                    lexicalScore: matches[i].lexicalScore,
+                    semanticSimilarity: matches[i].semanticSimilarity,
+                    lexicalContribution: matches[i].lexicalRank
+                        ? 1 / (60 + matches[i].lexicalRank)
+                        : 0,
+                    semanticContribution: matches[i].semanticRank
+                        ? 1 / (60 + matches[i].semanticRank)
+                        : 0,
+                    ...matches[i].diagnostics,
+                })
+                : undefined,
         }));
     }
     lines.push('');