@plebeiantech/lat.md 0.12.3-fork.1 → 0.12.3-fork.10

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/fork-instructions.d.ts

@@ -0,0 +1,19 @@
+export declare function readForkConventions(): string;
+/**
+ * Replace the fork block in `content`, or append one when absent.
+ *
+ * Returns null when the block is already byte-identical, so the caller can
+ * stay quiet rather than announce a write that did not happen.
+ */
+export declare function spliceForkBlock(content: string, body: string): string | null;
+/** Read the body currently fenced by the fork markers, or null if absent. */
+export declare function extractForkBlock(content: string): string | null;
+/**
+ * Write the fork's conventions into every instruction file and skill directory
+ * the selected agents produced.
+ *
+ * `fileHashes` is upstream's record, threaded through so `writeInitMeta`
+ * persists these entries alongside its own; a stored hash is what lets a later
+ * run tell "the user edited our block" from "the template moved on".
+ */
+export declare function writeForkInstructions(root: string, latDir: string, fileHashes: Record<string, string>, ask: (message: string) => Promise<boolean>): Promise<void>;

package/dist/src/cli/fork-instructions.js

@@ -0,0 +1,183 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { styleText } from 'node:util';
+import { contentHash, readFileHash } from '../init-version.js';
+import { findTemplatesDir } from './templates.js';
+/**
+ * The fork's own instruction channel into a consumer project.
+ *
+ * Upstream teaches a consumer's agent through `templates/AGENTS.md` and
+ * `templates/skill/SKILL.md`. Both are upstream files, and both are the ones
+ * upstream is most likely to rewrite, so every sentence this fork adds to them
+ * is a merge conflict bought on credit. The fork's Diátaxis block cost 13
+ * lines in one and 14 in the other before this module existed.
+ *
+ * Everything here writes into fork-owned paths instead. The entire upstream
+ * footprint is one import and one call in `initCmd`.
+ *
+ * Two shapes, because the destinations behave differently:
+ *
+ * - Always-loaded instruction files (`CLAUDE.md`, `AGENTS.md`,
+ *   `.github/copilot-instructions.md`) already carry upstream's
+ *   `%% lat:begin %%` block, so this appends a *second* block under its own
+ *   `%% lat-fork:begin %%` markers. Upstream's `appendTemplateSection` slices
+ *   between its own markers and leaves anything after them intact, so the two
+ *   blocks do not fight on re-run.
+ * - Skill directories get a separate `lat-md-conventions/SKILL.md`. Upstream
+ *   writes its `lat-md` skill with a whole-file hash comparison, so appending
+ *   to that file would make every later `lat init` report it as
+ *   user-modified and prompt.
+ */
+const FORK_BEGIN = '%% lat-fork:begin %%';
+const FORK_END = '%% lat-fork:end %%';
+/**
+ * Hash-map key for a fork block inside a file upstream also owns. Suffixed so
+ * it can never collide with upstream's entry for the same path — both live in
+ * one flat `file_hashes` record.
+ */
+function forkHashKey(relPath) {
+    return `${relPath}#lat-fork`;
+}
+/** Instruction files that use upstream's marker-append shape. */
+const BLOCK_TARGETS = [
+    'CLAUDE.md',
+    'AGENTS.md',
+    '.github/copilot-instructions.md',
+];
+/**
+ * Skill roots every agent integration installs into. Written to only when the
+ * directory already exists, which is what keeps this list from creating skill
+ * directories for agents the user did not select.
+ */
+const SKILL_ROOTS = [
+    '.claude/skills',
+    '.pi/skills',
+    '.agents/skills',
+    '.codex/skills',
+];
+const SKILL_NAME = 'lat-md-conventions';
+const SKILL_FRONTMATTER = `---
+name: ${SKILL_NAME}
+description: >-
+  Rules lat check enforces in this project: Diátaxis mode placement for every
+  lat.md/ document, mandatory @lat: code refs starting at the application
+  entrypoint, and test specs wired to their tests. Load alongside lat-md
+  whenever creating or editing files under lat.md/.
+---
+
+`;
+export function readForkConventions() {
+    return readFileSync(join(findTemplatesDir(), 'fork', 'conventions.md'), 'utf-8');
+}
+function wrapBlock(body) {
+    return `${FORK_BEGIN}\n${body}${body.endsWith('\n') ? '' : '\n'}${FORK_END}\n`;
+}
+/**
+ * Replace the fork block in `content`, or append one when absent.
+ *
+ * Returns null when the block is already byte-identical, so the caller can
+ * stay quiet rather than announce a write that did not happen.
+ */
+export function spliceForkBlock(content, body) {
+    const wrapped = wrapBlock(body);
+    const begin = content.indexOf(FORK_BEGIN);
+    const end = content.indexOf(FORK_END);
+    if (begin === -1 || end === -1 || end <= begin) {
+        let base = content;
+        if (base.length > 0 && !base.endsWith('\n'))
+            base += '\n';
+        return base + (base.length > 0 ? '\n' : '') + wrapped;
+    }
+    const endWithMarker = end + FORK_END.length;
+    const endWithNl = content[endWithMarker] === '\n' ? endWithMarker + 1 : endWithMarker;
+    const existing = content.slice(begin, endWithNl);
+    if (existing === wrapped)
+        return null;
+    return content.slice(0, begin) + wrapped + content.slice(endWithNl);
+}
+/** Read the body currently fenced by the fork markers, or null if absent. */
+export function extractForkBlock(content) {
+    const begin = content.indexOf(FORK_BEGIN);
+    const end = content.indexOf(FORK_END);
+    if (begin === -1 || end === -1 || end <= begin)
+        return null;
+    return content.slice(begin + FORK_BEGIN.length + 1, end);
+}
+/**
+ * Write the fork's conventions into every instruction file and skill directory
+ * the selected agents produced.
+ *
+ * `fileHashes` is upstream's record, threaded through so `writeInitMeta`
+ * persists these entries alongside its own; a stored hash is what lets a later
+ * run tell "the user edited our block" from "the template moved on".
+ */
+export async function writeForkInstructions(root, latDir, fileHashes, ask) {
+    const body = readForkConventions();
+    const bodyHash = contentHash(body);
+    const written = [];
+    for (const relPath of BLOCK_TARGETS) {
+        const absPath = join(root, relPath);
+        if (!existsSync(absPath))
+            continue;
+        const current = readFileSync(absPath, 'utf-8');
+        const existingBlock = extractForkBlock(current);
+        if (existingBlock !== null) {
+            const existingHash = contentHash(existingBlock);
+            if (existingHash === bodyHash) {
+                fileHashes[forkHashKey(relPath)] = bodyHash;
+                continue;
+            }
+            const storedHash = readFileHash(latDir, forkHashKey(relPath));
+            if (storedHash && existingHash !== storedHash) {
+                console.log(styleText('yellow', `  ${relPath}`) +
+                    ' lat-fork section has been modified.');
+                if (!(await ask('  Replace lat-fork section with latest template?'))) {
+                    console.log(styleText('dim', '  Kept existing section.'));
+                    continue;
+                }
+            }
+        }
+        const updated = spliceForkBlock(current, body);
+        if (updated === null) {
+            fileHashes[forkHashKey(relPath)] = bodyHash;
+            continue;
+        }
+        writeFileSync(absPath, updated);
+        fileHashes[forkHashKey(relPath)] = bodyHash;
+        written.push(relPath);
+    }
+    const skillBody = SKILL_FRONTMATTER + body;
+    const skillHash = contentHash(skillBody);
+    for (const skillRoot of SKILL_ROOTS) {
+        const rootAbs = join(root, skillRoot);
+        if (!existsSync(rootAbs))
+            continue;
+        const relPath = `${skillRoot}/${SKILL_NAME}/SKILL.md`;
+        const absPath = join(root, relPath);
+        if (existsSync(absPath)) {
+            const current = readFileSync(absPath, 'utf-8');
+            if (contentHash(current) === skillHash) {
+                fileHashes[relPath] = skillHash;
+                continue;
+            }
+            const storedHash = readFileHash(latDir, relPath);
+            if (storedHash && contentHash(current) !== storedHash) {
+                console.log(styleText('yellow', `  ${relPath}`) + ' has been modified.');
+                if (!(await ask('  Overwrite with latest lat template?'))) {
+                    console.log(styleText('dim', '  Kept existing file.'));
+                    continue;
+                }
+            }
+        }
+        mkdirSync(join(absPath, '..'), { recursive: true });
+        writeFileSync(absPath, skillBody);
+        fileHashes[relPath] = skillHash;
+        written.push(relPath);
+    }
+    if (written.length > 0) {
+        console.log('');
+        console.log(styleText('green', '  lat.md conventions') +
+            ' written to ' +
+            written.join(', '));
+    }
+}

package/dist/src/cli/fork-scaffold.d.ts

@@ -0,0 +1,106 @@
+/** What the root index says about the gate today. */
+export type RequireModeState = 'on' | 'off' | 'unset' | 'invalid';
+/**
+ * Read the gate straight from a root index's frontmatter.
+ *
+ * Four states rather than a boolean, because `checkMode` enforces on `=== true`
+ * and anything looser here disagrees with it. A root index reading
+ * `require-mode: yes` is a string to this parser: treating that as "set" left
+ * the user believing the gate was on, `checkMode` enforcing nothing, and the
+ * one prompt that would have said so permanently silenced by the same value.
+ * `invalid` is reported rather than assumed either way.
+ */
+export declare function requireModeState(content: string): RequireModeState;
+/** What `planRequireMode` decided, before anything is written or asked. */
+export type StampPlan = 
+/** Already `true`; nothing to do. */
+{
+    kind: 'on';
+}
+/** Explicitly `false`. A deliberate opt-out is not re-offered. */
+ | {
+    kind: 'off';
+}
+/** The edited document, ready to write. */
+ | {
+    kind: 'stamped';
+    content: string;
+    movedRootKey: boolean;
+}
+/** Present but neither `true` nor `false`. */
+ | {
+    kind: 'invalid';
+    detail: string;
+}
+/** The frontmatter does not parse, so no field on it is read at all. */
+ | {
+    kind: 'unparseable';
+    detail: string;
+}
+/** `lat:` holds something that cannot carry a mapping key. */
+ | {
+    kind: 'unsupported';
+    detail: string;
+};
+/**
+ * Decide what turning the gate on in this document would do, without doing it.
+ *
+ * Parsed and re-emitted through the YAML document API rather than edited line
+ * by line. Line surgery looked cheaper — it preserves the file byte for byte
+ * except where it inserts — but it has to answer, from raw text, every question
+ * the parser already answers: which line opens the block, which lines are the
+ * `lat:` mapping's own children rather than a later key's, how far they are
+ * indented, and whether the value on the `lat:` line is a flow mapping, an
+ * anchor or a block scalar. Each wrong answer was its own defect: a flow
+ * mapping and an anchor were refused although both merge cleanly, an empty
+ * `lat:` beside a sibling list was refused because the scan walked past the end
+ * of the block, and one shape produced frontmatter that no longer parsed at
+ * all. `parseDocument` answers all of it, and round-trips comments and blank
+ * lines while doing so.
+ *
+ * The one thing the document API does not give for free is that the fields
+ * already there survive, so that is asserted below rather than assumed.
+ */
+export declare function planRequireMode(content: string): StampPlan;
+/** The edited document when the gate can be turned on, the input when not. */
+export declare function stampRequireMode(content: string): string;
+/**
+ * Append the four mode directories to the root index.
+ *
+ * Without this a fresh `lat init` leaves `lat check index` reporting four
+ * missing entries, which is a poor first impression of a tool whose whole
+ * pitch is that the check passes. Each directory is tested for separately: an
+ * index that already links `reference/` used to suppress the other three, so
+ * the three unlinked directories this had just created turned a passing
+ * `lat check index` into a failing one.
+ */
+export declare function listModeDirs(content: string): string;
+/**
+ * Scaffold the four mode directories and turn the gate on.
+ *
+ * Nothing at all happens when the gate cannot land in the root index. A tree
+ * left with four new directories and the gate still off is worse than one left
+ * alone: `checkMode` passes on it, so nothing ever says the adoption stopped
+ * half way — and if the index was not rewritten to list them, `lat check index`
+ * fails instead, on four directories the user never asked for.
+ */
+export declare function writeForkScaffold(latDir: string): void;
+/**
+ * Offer the gate to a tree `lat init` did not create.
+ *
+ * `writeForkScaffold` runs only on the branch that creates `lat.md/`, which
+ * left the flag unreachable for every project that already had one — that is,
+ * for every project that needs it. Restructuring someone's tree without asking
+ * is still wrong, so this asks.
+ *
+ * Whether the flag *can* be written is decided before anything is asked and
+ * before anything is written. Asking first cost a tree four directories and a
+ * rewritten index in exchange for a gate that never landed, and the user was
+ * told in the same breath that nothing could be edited.
+ *
+ * Silent when the flag is already set either way, when a previous run was told
+ * no, and when there is no TTY to ask — the non-interactive path prints the
+ * count and the manual edit instead, and records nothing, so a later
+ * interactive run still offers.
+ */
+export declare function offerRequireMode(latDir: string, interactive: boolean, ask: (message: string) => Promise<boolean>): Promise<void>;