@plebeiantech/lat.md 0.12.3-fork.3 → 0.12.3-fork.5

package/README.md

@@ -62,6 +62,8 @@ npm i -g --prefix ~/.local/lat https://github.com/PlebeianTech/lat.md/releases/l
 
 That last one wants `~/.local/lat/bin` on your `PATH`. A fixed prefix keeps the install independent of whichever Node version is active.
 
+Pick one route and stay on it. A Release-route install left on `PATH` shadows a mise-managed one — `mise upgrade` then reports a new version while the shell keeps running the old binary.
+
 Then run `lat init` in the repo you want to use lat in.
 
 ### As a Claude Code plugin

package/dist/src/cli/check-mode.js

@@ -18,7 +18,11 @@ export const MODE_DIRS = {
     explanation: 'explanation',
 };
 /** Reverse lookup: first path segment -> mode. Built once, not per file. */
-const DIR_TO_MODE = Object.fromEntries(DIATAXIS_MODES.map((mode) => [MODE_DIRS[mode], mode]));
+// Null-prototype: the key is a directory name read off disk.
+const DIR_TO_MODE = Object.create(null);
+for (const mode of DIATAXIS_MODES) {
+    DIR_TO_MODE[MODE_DIRS[mode]] = mode;
+}
 const OUTCOME_RE = /\b(outcome|by the end|you will (build|learn|have|create)|what you (will )?(build|learn|have|create))\b/i;
 /**
  * Imperative verbs that flag a command inside an explanation document.

package/dist/src/cli/comment-guard.d.ts

@@ -1,4 +1,18 @@
 import { type ToolInput } from './comment-reminder.js';
+/**
+ * The blocking half of the comment convention. `computeCommentReminder` runs
+ * at PostToolUse and only advises: by then the prose is already on disk, and
+ * it is deduped to once per file per session, so the second rationale block
+ * in a file draws no signal at all.
+ *
+ * This runs at PreToolUse instead, where `tool_input` is visible before the
+ * edit is applied and the hook can answer `deny`. A multi-line comment is
+ * refused outright and the agent is told to put the reasoning in `lat.md/`
+ * and leave a `@lat:` pointer behind.
+ *
+ * There is deliberately no per-session dedup here. A gate that fires once is
+ * not a gate.
+ */
 export type PreToolUseInput = {
     hook_event_name?: string;
     session_id?: string;

package/dist/src/cli/comment-guard.js

@@ -1,28 +1,4 @@
-import { candidateCommentLines, extractWrittenText, hasLatTree, matchFamily, resolveProjectRoot, } from './comment-reminder.js';
-/**
- * The blocking half of the comment convention. `computeCommentReminder` runs
- * at PostToolUse and only advises: by then the prose is already on disk, and
- * it is deduped to once per file per session, so the second rationale block
- * in a file draws no signal at all.
- *
- * This runs at PreToolUse instead, where `tool_input` is visible before the
- * edit is applied and the hook can answer `deny`. A multi-line comment is
- * refused outright and the agent is told to put the reasoning in `lat.md/`
- * and leave a `@lat:` pointer behind.
- *
- * There is deliberately no per-session dedup here. A gate that fires once is
- * not a gate.
- */
-/** Minimum candidate comment lines in one write before the edit is refused.
- *  A single line ("// bytes, not chars") is the bare-fact case the convention
- *  explicitly allows; two or more is a block of prose. */
-const BLOCK_THRESHOLD = 2;
-/** Explicit, reviewable opt-out. Spelled the same as the `lat:ignore` token
- *  [[src/code-refs.ts]] already honours, so a project has one escape hatch to
- *  learn rather than two. It suppresses only the line it appears on, which
- *  keeps a deliberate exception visible in the diff instead of silently
- *  disarming the gate for a whole file. */
-const LAT_IGNORE_RE = /(?<![\w])lat:ignore(?![-\w])/;
+import { hasLatTree, judgeWrittenComments, matchFamily, resolveProjectRoot, } from './comment-reminder.js';
 function buildReason(opts) {
     const where = opts.hasTree
         ? '  1. Put the reasoning in a lat.md/ section. Verbatim is fine — it does\n' +
@@ -43,8 +19,12 @@ function buildReason(opts) {
         '  3. Re-apply the edit with the prose replaced by that one pointer line.\n\n' +
         'If a comment only narrates what the code does, delete it rather than ' +
         'moving it — a reader could reconstruct it from the code.\n\n' +
-        `To keep a specific line anyway, put \`lat:ignore\` on it. That is an ` +
-        'explicit, reviewable exception, not a way to silence the gate.');
+        'Two exits, if neither applies:\n' +
+        '  - Put `lat:ignore` on a specific line to keep it. An explicit, ' +
+        'reviewable exception, not a way to silence the gate.\n' +
+        '  - Use `Edit` rather than a whole-file `Write`. Re-emitting a comment ' +
+        'the file already holds is free in either shape, but an `Edit` puts far ' +
+        'less text in front of the count.');
 }
 /**
  * Returns the denial reason for a single Edit/Write/MultiEdit call, or `null`
@@ -93,18 +73,15 @@ export function computeCommentBlock(input) {
     const family = matchFamily(filePath);
     if (!family)
         return null;
-    const written = extractWrittenText(toolInput);
-    if (!written)
-        return null;
-    const candidates = candidateCommentLines(written, family).filter((line) => !LAT_IGNORE_RE.test(line));
-    if (candidates.length < BLOCK_THRESHOLD)
+    const verdict = judgeWrittenComments(toolInput, family, 'before-write');
+    if (!verdict.flagged)
         return null;
     const projectRoot = resolveProjectRoot(filePath, input.cwd);
     if (!projectRoot)
         return null;
     return buildReason({
         base: filePath.split('/').pop() ?? filePath,
-        count: candidates.length,
+        count: verdict.count,
         marker: family.marker,
         hasTree: hasLatTree(projectRoot),
     });

package/dist/src/cli/comment-reminder.d.ts

@@ -27,20 +27,79 @@ export declare function matchFamily(filePath: string): CommentFamily | null;
 export type ToolInput = {
     file_path?: string;
     content?: string;
+    old_string?: string;
     new_string?: string;
     edits?: {
+        old_string?: string;
         new_string?: string;
     }[];
 };
-/** Only the NEW text — reading the file would fire on every pre-existing
- * comment in it, nagging about prose the agent did not write. */
-export declare function extractWrittenText(toolInput: ToolInput): string;
-/** Comment lines worth reminding about. Dropped before counting:
+/**
+ * Which side of the tool call the caller is on.
+ *
+ * `'before-write'` — PreToolUse. The file on disk is still the pre-edit state,
+ * so it is usable as a baseline for a whole-file `Write`, which carries no
+ * other record of what it replaced.
+ *
+ * `'after-write'` — PostToolUse. The write has landed, so the file contains
+ * every line of `content` by construction. Diffing against it there cancels
+ * the whole payload and the caller sees nothing at all.
+ *
+ * An `Edit` carries its own `old_string` and needs neither reading: its
+ * baseline is phase-independent, which is the shape to prefer.
+ *
+ * The parameter is required so a third call site has to answer the question
+ * rather than inherit whichever default happened to suit the first two.
+ */
+export type WritePhase = 'before-write' | 'after-write';
+/** Explicit, reviewable per-line opt-out, spelled the same as the token
+ * [[src/code-refs.ts]] already honours so a project has one escape hatch to
+ * learn rather than two. It lives here, not in the guard, because the
+ * advisory and blocking halves have to agree on it: an exemption that the
+ * gate honours but the reminder does not just relocates the nag.
+ * It suppresses only the line it appears on, keeping a deliberate exception
+ * visible in the diff instead of silently disarming the convention for a
+ * whole file. */
+export declare const LAT_IGNORE_RE: RegExp;
+/** Whether one line is a comment worth counting. Not counted:
  *   - a line that already carries a `@lat:` pointer (the compliant state)
+ *   - a line carrying the explicit opt-out token
  *   - machine directives: shebangs, magic comments, linter/type pragmas
  *   - decoration with no alphanumeric character (`# ----`, `//////`, a bare
- *     `*​/` closing a block) */
-export declare function candidateCommentLines(written: string, family: CommentFamily): string[];
+ *     `*​/` closing a block)
+ *
+ * Both halves of the convention call this and nothing else, so the gate and
+ * the reminder cannot drift apart on what counts as prose. */
+export declare function isCandidateCommentLine(line: string, family: CommentFamily): boolean;
+export type CommentVerdict = {
+    /** Candidate comment lines this call is answerable for. Names the number
+     * printed in the denial or the reminder. */
+    count: number;
+    /** Whether the call warrants a denial from the gate or a reminder from its
+     * advisory half. */
+    flagged: boolean;
+};
+/**
+ * What one Edit/Write/MultiEdit call did to the comments in a file.
+ *
+ * Two rules, because neither alone survives contact with an agent:
+ *
+ * A run of `PROSE_THRESHOLD` or more *adjacent* comment lines is flagged as
+ * soon as any one of them is new. Counting only the new lines lets a block be
+ * grown one line per `Edit` and never reach the threshold — and the denial
+ * text itself recommends `Edit` over `Write`, so the technique is advertised.
+ * What matters is the block the edit leaves behind, not the increment.
+ *
+ * Isolated new comment lines are flagged once `PROSE_THRESHOLD` of them
+ * accumulate anywhere in the call. Two one-line comments in different places
+ * are still two lines of prose; without this a scattered write walks past the
+ * adjacency rule.
+ *
+ * Neither rule counts a line that was already there, so re-emitting a
+ * comment — the whole of a `Write`'s payload, or the lines bracketing an
+ * `Edit` — stays free.
+ */
+export declare function judgeWrittenComments(toolInput: ToolInput, family: CommentFamily, phase: WritePhase): CommentVerdict;
 /** Resolvable project root, required so a scratch file in /tmp is not treated
  * as a project. `cwd` is preferred (matches CLAUDE_PROJECT_DIR / payload cwd
  * conventions); falls back to `git rev-parse --show-toplevel`. */

package/dist/src/cli/comment-reminder.js

@@ -1,6 +1,6 @@
 import { execSync } from 'node:child_process';
 import { createHash } from 'node:crypto';
-import { existsSync, mkdirSync, writeFileSync, statSync, lstatSync, } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, writeFileSync, statSync, lstatSync, } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { basename, dirname, join } from 'node:path';
 const FAMILIES = [
@@ -41,35 +41,174 @@ export function matchFamily(filePath) {
     }
     return null;
 }
-/** Only the NEW text — reading the file would fire on every pre-existing
- * comment in it, nagging about prose the agent did not write. */
-export function extractWrittenText(toolInput) {
-    const parts = [];
+/** Line multiset of `text`, used as the baseline a written fragment is new
+ * against. */
+function lineCounts(text) {
+    const counts = new Map();
+    for (const line of text.split('\n')) {
+        counts.set(line, (counts.get(line) ?? 0) + 1);
+    }
+    return counts;
+}
+/** Baseline taken from the file itself, or `null` when there is no readable
+ * file — a brand-new path, a directory, a permission error, a payload naming
+ * no file. `null` means every line counts as new, which is what makes an
+ * unreadable file fail closed: the gate denies rather than waving the write
+ * through on evidence it could not gather. */
+function fileBaseline(filePath) {
+    if (!filePath)
+        return null;
+    try {
+        return lineCounts(readFileSync(filePath, 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The fragments one tool call writes, each against the narrowest baseline
+ * available for it.
+ *
+ * `old_string` is preferred over the file wherever the payload carries one,
+ * because the file is the wrong scope: matching a written line against
+ * *anywhere* in the file forgives a genuinely new block whenever one of its
+ * lines happens to duplicate an unrelated line elsewhere. `old_string` is the
+ * exact text being replaced, so the difference is the real delta.
+ *
+ * Baselines are per fragment rather than shared across a `MultiEdit`: two
+ * hunks that each re-emit the same surrounding comment are both re-emitting
+ * it, and charging the second one for it would deny exactly the edit this is
+ * here to allow.
+ */
+function writtenFragments(toolInput, phase) {
+    let diskRead = false;
+    let disk = null;
+    const fromFile = () => {
+        if (phase !== 'before-write')
+            return null;
+        if (!diskRead) {
+            disk = fileBaseline(toolInput.file_path);
+            diskRead = true;
+        }
+        return disk;
+    };
+    const baselineFor = (oldString) => typeof oldString === 'string' ? lineCounts(oldString) : fromFile();
+    const fragments = [];
     if (typeof toolInput.content === 'string')
-        parts.push(toolInput.content);
+        fragments.push({ text: toolInput.content, baseline: fromFile() });
     if (typeof toolInput.new_string === 'string')
-        parts.push(toolInput.new_string);
+        fragments.push({
+            text: toolInput.new_string,
+            baseline: baselineFor(toolInput.old_string),
+        });
     if (Array.isArray(toolInput.edits)) {
         for (const edit of toolInput.edits) {
             if (typeof edit?.new_string === 'string')
-                parts.push(edit.new_string);
+                fragments.push({
+                    text: edit.new_string,
+                    baseline: baselineFor(edit.old_string),
+                });
         }
     }
-    return parts.join('\n');
+    return fragments;
 }
-/** Comment lines worth reminding about. Dropped before counting:
+/** Explicit, reviewable per-line opt-out, spelled the same as the token
+ * [[src/code-refs.ts]] already honours so a project has one escape hatch to
+ * learn rather than two. It lives here, not in the guard, because the
+ * advisory and blocking halves have to agree on it: an exemption that the
+ * gate honours but the reminder does not just relocates the nag.
+ * It suppresses only the line it appears on, keeping a deliberate exception
+ * visible in the diff instead of silently disarming the convention for a
+ * whole file. */
+export const LAT_IGNORE_RE = /(?<![\w])lat:ignore(?![-\w])/;
+/** Whether one line is a comment worth counting. Not counted:
  *   - a line that already carries a `@lat:` pointer (the compliant state)
+ *   - a line carrying the explicit opt-out token
  *   - machine directives: shebangs, magic comments, linter/type pragmas
  *   - decoration with no alphanumeric character (`# ----`, `//////`, a bare
- *     `*​/` closing a block) */
-export function candidateCommentLines(written, family) {
-    return written
-        .split('\n')
-        .filter((line) => family.commentRe.test(line))
-        .filter((line) => !line.includes('@lat:'))
-        .filter((line) => !/^\s*#!/.test(line))
-        .filter((line) => !family.pragmaRe.test(line))
-        .filter((line) => /[a-zA-Z0-9]/.test(line));
+ *     `*​/` closing a block)
+ *
+ * Both halves of the convention call this and nothing else, so the gate and
+ * the reminder cannot drift apart on what counts as prose. */
+export function isCandidateCommentLine(line, family) {
+    return (family.commentRe.test(line) &&
+        !line.includes('@lat:') &&
+        !LAT_IGNORE_RE.test(line) &&
+        !/^\s*#!/.test(line) &&
+        !family.pragmaRe.test(line) &&
+        /[a-zA-Z0-9]/.test(line));
+}
+/** Candidate comment lines in one write before either half reacts. A single
+ * line ("// bytes, not chars") is the bare-fact case the convention allows;
+ * two is a block of prose. */
+const PROSE_THRESHOLD = 2;
+/**
+ * What one Edit/Write/MultiEdit call did to the comments in a file.
+ *
+ * Two rules, because neither alone survives contact with an agent:
+ *
+ * A run of `PROSE_THRESHOLD` or more *adjacent* comment lines is flagged as
+ * soon as any one of them is new. Counting only the new lines lets a block be
+ * grown one line per `Edit` and never reach the threshold — and the denial
+ * text itself recommends `Edit` over `Write`, so the technique is advertised.
+ * What matters is the block the edit leaves behind, not the increment.
+ *
+ * Isolated new comment lines are flagged once `PROSE_THRESHOLD` of them
+ * accumulate anywhere in the call. Two one-line comments in different places
+ * are still two lines of prose; without this a scattered write walks past the
+ * adjacency rule.
+ *
+ * Neither rule counts a line that was already there, so re-emitting a
+ * comment — the whole of a `Write`'s payload, or the lines bracketing an
+ * `Edit` — stays free.
+ */
+export function judgeWrittenComments(toolInput, family, phase) {
+    const fragments = writtenFragments(toolInput, phase);
+    if (!fragments.some((fragment) => fragment.text !== ''))
+        return { count: 0, flagged: false };
+    let inFlaggedRuns = 0;
+    let isolatedNew = 0;
+    for (const fragment of fragments) {
+        const lines = fragment.text.split('\n');
+        const unclaimed = fragment.baseline ? new Map(fragment.baseline) : null;
+        const isNew = [];
+        const isComment = [];
+        for (const line of lines) {
+            let fresh = true;
+            if (unclaimed) {
+                const left = unclaimed.get(line) ?? 0;
+                if (left > 0) {
+                    unclaimed.set(line, left - 1);
+                    fresh = false;
+                }
+            }
+            isNew.push(fresh);
+            isComment.push(isCandidateCommentLine(line, family));
+        }
+        let i = 0;
+        while (i < lines.length) {
+            if (!isComment[i]) {
+                i += 1;
+                continue;
+            }
+            let end = i;
+            while (end < lines.length && isComment[end])
+                end += 1;
+            let fresh = 0;
+            for (let k = i; k < end; k += 1)
+                if (isNew[k])
+                    fresh += 1;
+            if (end - i >= PROSE_THRESHOLD && fresh > 0)
+                inFlaggedRuns += end - i;
+            else
+                isolatedNew += fresh;
+            i = end;
+        }
+    }
+    return {
+        count: inFlaggedRuns + isolatedNew,
+        flagged: inFlaggedRuns > 0 || isolatedNew >= PROSE_THRESHOLD,
+    };
 }
 /** Resolvable project root, required so a scratch file in /tmp is not treated
  * as a project. `cwd` is preferred (matches CLAUDE_PROJECT_DIR / payload cwd
@@ -176,16 +315,13 @@ export function computeCommentReminder(input) {
     const family = matchFamily(filePath);
     if (!family)
         return null;
-    const written = extractWrittenText(toolInput);
-    if (!written)
-        return null;
     // A single-line comment ("// increment the counter") almost always states
     // a bare fact, not a rationale — the acceptance case for this hook. Only a
-    // multi-line block is treated as prose worth a reminder; the model still
-    // makes the real judgment call, this just filters the overwhelmingly
-    // common one-liner before it ever reaches that question.
-    const candidates = candidateCommentLines(written, family);
-    if (candidates.length < 2)
+    // block is treated as prose worth a reminder; the model still makes the
+    // real judgment call, this just filters the overwhelmingly common one-liner
+    // before it ever reaches that question.
+    const verdict = judgeWrittenComments(toolInput, family, 'after-write');
+    if (!verdict.flagged)
         return null;
     const sessionId = input.session_id;
     let dedup = null;
@@ -201,7 +337,7 @@ export function computeCommentReminder(input) {
     const base = basename(filePath);
     const message = buildMessage({
         base,
-        count: candidates.length,
+        count: verdict.count,
         marker: family.marker,
         hasTree,
     });

package/dist/src/cli/index.js

@@ -6,8 +6,18 @@ if (!process.argv.includes('--verbose')) {
 import { existsSync, readFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { Command } from 'commander';
+import { Command, InvalidArgumentError } from 'commander';
 import { resolveCheckContext, resolveContext } from './context.js';
+function parsePort(value) {
+    if (!/^\d+$/.test(value)) {
+        throw new InvalidArgumentError('port must be an integer from 1 to 65535');
+    }
+    const port = Number(value);
+    if (port < 1 || port > 65_535) {
+        throw new InvalidArgumentError('port must be an integer from 1 to 65535');
+    }
+    return port;
+}
 /** Reserve `-- <directory>` for an explicit check target. */
 function splitCheckTarget(args) {
     let commandIndex = -1;
@@ -90,13 +100,28 @@ program
     const { sectionCommand } = await import('./section.js');
     handleResult(await sectionCommand(ctx, query));
 });
-program
+const ui = program
     .command('ui')
     .description('Open lat.md in a local browser')
-    .action(async () => {
+    .option('--logo-text <text>', 'top-left logo text')
+    .option('--port <number>', 'server port (default: 4242; explicit ports are strict)', parsePort)
+    .action(async (opts) => {
     const ctx = resolveContext(program.opts());
     const { uiCommand } = await import('./ui.js');
-    handleResult(await uiCommand(ctx));
+    handleResult(await uiCommand(ctx, { logoText: opts.logoText, port: opts.port }));
+});
+ui.command('build')
+    .description('Export lat.md as a static website')
+    .argument('[output]', 'output directory relative to the project', 'lat-ui')
+    .option('--base <path>', 'deployment base 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,
+        logoText: opts.logoText ?? ui.opts().logoText,
+    }));
 });
 program
     .command('refs')

package/dist/src/cli/search.js

@@ -73,10 +73,12 @@ async function resolveMatches(latDir, results, preloadedSections) {
     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' }));
+    return results.flatMap((result) => {
+        const section = byId.get(result.id);
+        return section
+            ? [{ section, reason: 'semantic match', score: result.score }]
+            : [];
+    });
 }
 /**
  * Run a semantic search across lat.md sections.

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

@@ -0,0 +1,4 @@
+import type { CmdContext, CmdResult } from '../context.js';
+import { type StaticViewBuildOptions } from '../view/static-build.js';
+/** Export the current vault as a serverless, read-only Lat UI. */
+export declare function uiBuildCommand(ctx: CmdContext, output?: string, options?: StaticViewBuildOptions): Promise<CmdResult>;

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

@@ -0,0 +1,13 @@
+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 = {}) {
+    try {
+        const result = await buildStaticView(ctx, output, options);
+        return {
+            output: `Built ${result.documents} documents and ${result.sources} source views at ${result.outputDir}`,
+        };
+    }
+    catch (error) {
+        return { output: error.message, isError: true };
+    }
+}

package/dist/src/cli/ui.js

@@ -21,9 +21,25 @@ export function openBrowser(url) {
 }
 /** Start `lat ui`, report its URL, and launch the default browser. */
 export async function uiCommand(ctx, options = {}) {
-    const server = await startViewServer(ctx, options);
+    let server;
+    try {
+        server = await startViewServer(ctx, options);
+    }
+    catch (error) {
+        if (options.port !== undefined &&
+            error.code === 'EADDRINUSE') {
+            return {
+                isError: true,
+                output: `Port ${options.port} is already in use. Choose another with --port <number>.`,
+            };
+        }
+        throw error;
+    }
     options.onStarted?.(server);
-    const lines = [`Viewing lat.md at ${server.url}`];
+    const lines = [
+        `Viewing lat.md at ${server.url}`,
+        'Note: you can use `lat ui build` to build a static version of the UI',
+    ];
     try {
         await (options.openBrowser ?? openBrowser)(server.url);
     }

package/dist/src/code-refs.js

@@ -1,6 +1,6 @@
 import { readFile } from 'node:fs/promises';
 import { execFile } from 'node:child_process';
-import { join, relative } from 'node:path';
+import { join, posix, relative } from 'node:path';
 import { toPosix, walkEntries } from './walk.js';
 /** Glob patterns used to exclude directories/files from code-ref scanning.
  *  Shared between rg args and the TS fallback's walkFiles filter. */
@@ -9,7 +9,10 @@ const EXCLUDE_GLOBS = ['*.md'];
 /** Walk project files for code-ref scanning. Uses walkEntries for .gitignore
  *  support, then additionally skips .md files, lat.md/, .claude/, and sub-projects. */
 export async function walkFiles(dir) {
-    const entries = await walkEntries(dir);
+    const entries = (await walkEntries(dir)).map(toPosix);
+    const generatedOutputs = new Set(entries
+        .filter((entry) => entry.endsWith('/.lat-ui-build'))
+        .map((entry) => `${posix.dirname(entry)}/`));
     // Collect directories that contain their own lat.md/ (sub-projects)
     const subProjects = new Set();
     for (const e of entries) {
@@ -21,6 +24,7 @@ export async function walkFiles(dir) {
         .filter((e) => !e.endsWith('.md') &&
         !e.startsWith('lat.md/') &&
         !e.startsWith('.claude/') &&
+        ![...generatedOutputs].some((prefix) => e.startsWith(prefix)) &&
         ![...subProjects].some((prefix) => e.startsWith(prefix)))
         .map((e) => join(dir, e));
 }
@@ -148,8 +152,22 @@ async function findSubProjects(projectRoot) {
     }
     return [...subProjects];
 }
+/** Find static UI exports so generated JSON and bundles never become code refs. */
+async function findGeneratedOutputs(projectRoot) {
+    const out = await tryExec('rg', ['--files', '--hidden', '--glob', '**/.lat-ui-build', '.'], projectRoot);
+    if (!out)
+        return [];
+    return [
+        ...new Set(out
+            .split('\n')
+            .filter(Boolean)
+            .map((line) => toPosix(line).replace(/^\.\//, ''))
+            .filter((line) => line.endsWith('/.lat-ui-build'))
+            .map((line) => posix.dirname(line))),
+    ];
+}
 /** Build rg glob exclusion args. */
-function rgExcludeArgs(subProjects) {
+function rgExcludeArgs(subProjects, generatedOutputs) {
     const args = [];
     for (const dir of EXCLUDE_DIRS)
         args.push('--glob', `!${dir}/`);
@@ -157,6 +175,8 @@ function rgExcludeArgs(subProjects) {
         args.push('--glob', `!${glob}`);
     for (const sp of subProjects)
         args.push('--glob', `!${sp}/`);
+    for (const output of generatedOutputs)
+        args.push('--glob', `!${output}/`);
     return args;
 }
 /**
@@ -167,7 +187,8 @@ function rgExcludeArgs(subProjects) {
 async function tryRipgrep(projectRoot) {
     // Detect sub-projects first so we can exclude them from all rg calls
     const subProjects = await findSubProjects(projectRoot);
-    const excludes = rgExcludeArgs(subProjects);
+    const generatedOutputs = await findGeneratedOutputs(projectRoot);
+    const excludes = rgExcludeArgs(subProjects, generatedOutputs);
     // Search for @lat refs
     const searchArgs = [
         '--no-heading',

package/dist/src/fork/upstream-drift-cli.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/fork/upstream-drift-cli.js

@@ -0,0 +1,2 @@
+import { main } from './upstream-drift.js';
+process.exit(main(process.argv.slice(2)));

package/dist/src/fork/upstream-drift.d.ts

@@ -0,0 +1,26 @@
+export declare const UPSTREAM_URL = "https://github.com/vercel-labs/lat.md.git";
+export declare const UPSTREAM_REF = "refs/remotes/upstream/main";
+export type Drift = {
+    upstream: string;
+    ahead: number;
+    behind: number;
+    upstreamFiles: string[];
+    forkFiles: string[];
+    overlap: string[];
+    conflicts: string[];
+    mergesCleanly: boolean;
+};
+/**
+ * Conflicting paths from `git merge-tree --write-tree --name-only`, whose
+ * output is the written tree id, then one path per line, then a blank line
+ * and the human-readable log. Everything after that blank line is prose.
+ */
+export declare function parseMergeTree(stdout: string): string[];
+export declare function fetchUpstream(repo: string, url: string, ref: string): void;
+export declare function analyzeDrift(opts: {
+    repo: string;
+    syncPoint: string;
+    upstreamRef: string;
+}): Drift;
+export declare function formatDrift(drift: Drift): string;
+export declare function main(argv: string[]): number;