@plebeiantech/lat.md 0.12.3-fork.2 → 0.12.3-fork.21

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

@@ -0,0 +1,184 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { styleText } from 'node:util';
+import { contentHash, readFileHash, } from '@plebeiantech/lat.md-core/init-version';
+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`, `GEMINI.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',
+    'GEMINI.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';
+export 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>;