@plebeiantech/lat.md 0.12.3-fork.1

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

@@ -0,0 +1,12 @@
+export interface ChecklistOption {
+    label: string;
+    value: string;
+}
+/**
+ * Display an interactive multi-select checklist with arrow-key navigation.
+ * Returns an array of checked values.
+ *
+ * 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[]>;

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

@@ -0,0 +1,111 @@
+import { styleText } from 'node:util';
+/**
+ * Display an interactive multi-select checklist with arrow-key navigation.
+ * Returns an array of checked values.
+ *
+ * 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) {
+    if (options.length === 0)
+        return [];
+    if (!process.stdin.isTTY)
+        return [];
+    return new Promise((resolve) => {
+        let cursor = 0;
+        const checked = new Set();
+        const stdin = process.stdin;
+        const wasRaw = stdin.isRaw;
+        stdin.setRawMode(true);
+        stdin.resume();
+        stdin.setEncoding('utf-8');
+        function render() {
+            process.stdout.write('\x1B[?25l'); // hide cursor
+            const lines = [];
+            if (prompt) {
+                lines.push(styleText('bold', prompt));
+            }
+            for (let i = 0; i < options.length; i++) {
+                const opt = options[i];
+                const selected = i === cursor;
+                const box = checked.has(i) ? '[x]' : '[ ]';
+                if (selected) {
+                    lines.push(`  ${box} ${styleText(['bgCyan', 'black', 'bold'], ` ${opt.label} `)}`);
+                }
+                else {
+                    lines.push(`  ${box} ${styleText('dim', opt.label)}`);
+                }
+            }
+            lines.push('');
+            lines.push(styleText('dim', '  space: toggle  enter: confirm'));
+            process.stdout.write(lines.join('\n') + '\n');
+        }
+        function clearRender() {
+            const totalLines = options.length + (prompt ? 1 : 0) + 2; // +2 for blank line + hint
+            for (let i = 0; i < totalLines; i++) {
+                process.stdout.write('\x1B[A\x1B[2K');
+            }
+        }
+        function cleanup() {
+            stdin.setRawMode(wasRaw ?? false);
+            stdin.pause();
+            process.stdout.write('\x1B[?25h'); // show cursor
+            stdin.removeListener('data', onData);
+        }
+        function onData(data) {
+            const key = data.toString();
+            // Ctrl+C
+            if (key === '\x03') {
+                clearRender();
+                cleanup();
+                console.log('');
+                process.exit(130);
+            }
+            // Enter — confirm
+            if (key === '\r' || key === '\n') {
+                clearRender();
+                cleanup();
+                const result = [...checked].sort().map((i) => options[i].value);
+                // Print summary
+                if (prompt) {
+                    const labels = [...checked]
+                        .sort()
+                        .map((i) => options[i].label)
+                        .join(', ');
+                    console.log(styleText('bold', prompt) +
+                        ' ' +
+                        (labels ? styleText('green', labels) : styleText('dim', 'None')));
+                }
+                resolve(result);
+                return;
+            }
+            // Space — toggle
+            if (key === ' ') {
+                clearRender();
+                if (checked.has(cursor)) {
+                    checked.delete(cursor);
+                }
+                else {
+                    checked.add(cursor);
+                }
+                render();
+                return;
+            }
+            // Arrow keys
+            if (key === '\x1B[A' || key === 'k') {
+                // Up
+                clearRender();
+                cursor = (cursor - 1 + options.length) % options.length;
+                render();
+            }
+            else if (key === '\x1B[B' || key === 'j') {
+                // Down
+                clearRender();
+                cursor = (cursor + 1) % options.length;
+                render();
+            }
+        }
+        stdin.on('data', onData);
+        render();
+    });
+}

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

@@ -0,0 +1,16 @@
+import { type ToolInput } from './comment-reminder.js';
+export type PreToolUseInput = {
+    hook_event_name?: string;
+    session_id?: string;
+    cwd?: string;
+    tool_name?: string;
+    tool_input?: ToolInput;
+};
+/**
+ * PreToolUse entry point. Lives here rather than in `hook.ts` so the upstream
+ * file carries only an import and a `case` — see the fork's upstream-divergence
+ * constraint. `readStdin` is injected for the same reason: it is `hook.ts`'s
+ * private helper and exporting it would widen that file's diff.
+ */
+export declare function handlePreToolUse(readStdin: () => Promise<string>): Promise<void>;
+export declare function computeCommentBlock(input: PreToolUseInput): string | null;

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

@@ -0,0 +1,111 @@
+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])/;
+function buildReason(opts) {
+    const where = opts.hasTree
+        ? '  1. Put the reasoning in a lat.md/ section. Verbatim is fine — it does\n' +
+            '     not need rewriting. Use `lat search` / `lat locate` to find where it\n' +
+            '     belongs; create a new section only if nothing existing fits.'
+        : '  1. This project has no lat.md/ tree yet. Run `lat init` to create one\n' +
+            '     (or create lat.md/ by hand), then put the reasoning in a section there.';
+    return (`Blocked by the lat.md comment convention: this edit writes ${opts.count} ` +
+        `comment lines into ${opts.base}.\n\n` +
+        'A code comment states a bare fact only — a unit, a bound, what null means, ' +
+        'an issue id, or an `@lat:` pointer. A comment that explains WHY (a reason, ' +
+        'a trade-off, a rejected alternative, a constraint, or the rationale behind ' +
+        'an invariant) is documentation, and documentation does not live in source.\n\n' +
+        'Do this instead:\n' +
+        `${where}\n` +
+        '  2. Leave a pointer in the code where the prose was:\n' +
+        `       ${opts.marker} @lat: [[section-id]]\n` +
+        '  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.');
+}
+/**
+ * Returns the denial reason for a single Edit/Write/MultiEdit call, or `null`
+ * to let the edit through. Pure and synchronous: every fallible bit (fs, git)
+ * is wrapped internally and degrades to "allow", never to a thrown error. A
+ * gate that crashes must fail open — refusing every edit because `git` is
+ * missing would be far worse than missing a comment.
+ */
+function outputDeny(reason) {
+    process.stdout.write(JSON.stringify({
+        hookSpecificOutput: {
+            hookEventName: 'PreToolUse',
+            permissionDecision: 'deny',
+            permissionDecisionReason: reason,
+        },
+    }));
+}
+/**
+ * PreToolUse entry point. Lives here rather than in `hook.ts` so the upstream
+ * file carries only an import and a `case` — see the fork's upstream-divergence
+ * constraint. `readStdin` is injected for the same reason: it is `hook.ts`'s
+ * private helper and exporting it would widen that file's diff.
+ */
+export async function handlePreToolUse(readStdin) {
+    try {
+        const raw = await readStdin();
+        const input = JSON.parse(raw);
+        const toolName = input.tool_name ?? '';
+        if (!/^(Edit|Write|MultiEdit)$/.test(toolName))
+            return;
+        const reason = computeCommentBlock(input);
+        if (reason)
+            outputDeny(reason);
+    }
+    catch {
+        // Fail open: never block a tool call over a malformed payload or fs error.
+    }
+}
+export function computeCommentBlock(input) {
+    const toolInput = input.tool_input ?? {};
+    const filePath = toolInput.file_path;
+    if (!filePath)
+        return null;
+    // `FAMILIES` is the single place that decides which files are eligible, and
+    // no family matches `.md` — markdown, where prose belongs, is never gated.
+    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)
+        return null;
+    const projectRoot = resolveProjectRoot(filePath, input.cwd);
+    if (!projectRoot)
+        return null;
+    return buildReason({
+        base: filePath.split('/').pop() ?? filePath,
+        count: candidates.length,
+        marker: family.marker,
+        hasTree: hasLatTree(projectRoot),
+    });
+}

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

@@ -0,0 +1,62 @@
+/**
+ * Ports `hooks/comment-docref-reminder.sh` from the Diátaxis plugin into a
+ * lat.md hook event. The read side of lat.md surfaces knowledge behind a
+ * `// @lat:` pointer that already exists; nothing acts on WRITING one, so an
+ * agent that writes a nine-line rationale comment gets no signal at all — the
+ * write succeeds and looks correct. This is that missing half.
+ *
+ * Deliberately a reminder, not a gate: it always resolves without throwing,
+ * and the caller (`hookCmd`) always exits 0. Judging whether a comment
+ * explains WHY is not mechanically decidable, so the decision stays with the
+ * model — this only guarantees the question gets asked, once per file per
+ * session.
+ */
+export type CommentFamily = {
+    /** Matches the file's basename (Rakefile, Dockerfile, etc. carry the
+     * language in the name, not an extension, so this matches on basename). */
+    basenameRe: RegExp;
+    /** A line that opens or continues a comment in this family. */
+    commentRe: RegExp;
+    /** Machine directives (shebangs, magic comments, linter/type pragmas) that
+     * are not prose and can never move into a doc. */
+    pragmaRe: RegExp;
+    /** The `@lat:` marker syntax for this family, e.g. `#` or `//`. */
+    marker: string;
+};
+export declare function matchFamily(filePath: string): CommentFamily | null;
+export type ToolInput = {
+    file_path?: string;
+    content?: string;
+    new_string?: string;
+    edits?: {
+        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:
+ *   - a line that already carries a `@lat:` pointer (the compliant state)
+ *   - 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[];
+/** 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`. */
+export declare function resolveProjectRoot(filePath: string, payloadCwd?: string): string | null;
+export declare function hasLatTree(projectRoot: string): boolean;
+export type PostToolUseInput = {
+    hook_event_name?: string;
+    session_id?: string;
+    cwd?: string;
+    tool_name?: string;
+    tool_input?: ToolInput;
+};
+/**
+ * Computes the reminder context for a single Edit/Write call, or `null` if
+ * nothing warrants one. Pure and synchronous so it's trivial to unit test —
+ * all the fallible bits (fs, git, marker dedup) are wrapped internally and
+ * degrade to "say nothing" or "say it again", never to a thrown error.
+ */
+export declare function computeCommentReminder(input: PostToolUseInput): string | null;

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

@@ -0,0 +1,210 @@
+import { execSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, writeFileSync, statSync, lstatSync, } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { basename, dirname, join } from 'node:path';
+const FAMILIES = [
+    // Ruby, Python, shell, Rake, Dockerfile, Make, Terraform, YAML, TOML
+    {
+        basenameRe: /^(.*\.(rb|rake|py|sh|bash|zsh|dockerfile|mk|tf|tfvars|yml|yaml|toml)|Rakefile|Dockerfile(\..*)?|Makefile|makefile|GNUmakefile)$/,
+        commentRe: /^\s*#/,
+        pragmaRe: /^\s*#\s*(frozen_string_literal|encoding|coding[:=]|typed|rubocop|standard|:nodoc:|-\*-|type:|noqa|pylint|pyright|pragma:|fmt:|mypy:|ruff:|isort:|shellcheck|syntax=|escape=|tflint-ignore|yamllint|checkov:|terraform-docs)/,
+        marker: '#',
+    },
+    // TS/JS, Rust, Java, Go, C/C++, Kotlin, Swift, PHP, Scala. The `{/*` arm is
+    // JSX in practice but costs nothing elsewhere. Rust `///`/`//!` and Java
+    // `/**` are deliberately in scope — a doc comment explaining why is still
+    // prose that belongs in a doc with a pointer behind it.
+    //
+    // A bare `*` only opens/continues a comment when followed by whitespace, a
+    // slash, or end of line — otherwise `*count += 1;` (a pointer dereference)
+    // reads as a comment.
+    {
+        basenameRe: /\.(ts|tsx|js|jsx|mjs|cjs|mts|cts|rs|java|go|kt|kts|swift|php|scala|sc|c|h|cc|cpp|cxx|hpp|hh|hxx|m|mm)$/,
+        commentRe: /^\s*(\/\/|\/\*|\{\/\*|\*([\s/]|$))/,
+        pragmaRe: /^\s*(\/\/|\/\*)\s*(eslint|prettier-ignore|biome-ignore|istanbul|c8 |v8 |@ts-|<reference|CHECKSTYLE|NOPMD|\$NON-NLS|go:|\+build|nolint|clang-format|NOLINT|IWYU|swiftlint:|ktlint-|phpcs:|psalm-|@codingStandardsIgnore)/,
+        marker: '//',
+    },
+    // SQL. `#` is there for the MySQL dialect, which accepts it alongside `--`.
+    {
+        basenameRe: /\.sql$/,
+        commentRe: /^\s*(--|\/\*|#|\*([\s/]|$))/,
+        pragmaRe: /^\s*(--|#)\s*(noqa|sqlfluff|sqlformat)/,
+        marker: '--',
+    },
+];
+export function matchFamily(filePath) {
+    const base = basename(filePath);
+    for (const family of FAMILIES) {
+        if (family.basenameRe.test(base))
+            return family;
+    }
+    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 = [];
+    if (typeof toolInput.content === 'string')
+        parts.push(toolInput.content);
+    if (typeof toolInput.new_string === 'string')
+        parts.push(toolInput.new_string);
+    if (Array.isArray(toolInput.edits)) {
+        for (const edit of toolInput.edits) {
+            if (typeof edit?.new_string === 'string')
+                parts.push(edit.new_string);
+        }
+    }
+    return parts.join('\n');
+}
+/** Comment lines worth reminding about. Dropped before counting:
+ *   - a line that already carries a `@lat:` pointer (the compliant state)
+ *   - 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));
+}
+/** 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`. */
+export function resolveProjectRoot(filePath, payloadCwd) {
+    if (payloadCwd)
+        return payloadCwd;
+    try {
+        const dir = dirname(filePath);
+        const out = execSync('git rev-parse --show-toplevel', {
+            cwd: dir,
+            encoding: 'utf-8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+            timeout: 2000,
+        }).trim();
+        return out || null;
+    }
+    catch {
+        return null;
+    }
+}
+export function hasLatTree(projectRoot) {
+    try {
+        return statSync(join(projectRoot, 'lat.md')).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/** Once per file per session. A private per-user temp dir; if a marker
+ * already exists (or can't be checked), the caller treats it as "already
+ * reminded" only when the file actually exists, never on error — a dedup
+ * failure should fire the reminder again, not suppress it forever. */
+function alreadyReminded(sessionId, filePath) {
+    const noop = { seen: false, markAsSeen: () => { } };
+    try {
+        const dir = join(tmpdir(), `lat-comment-reminder-${process.getuid?.() ?? 0}`);
+        if (!existsSync(dir)) {
+            mkdirSync(dir, { recursive: true, mode: 0o700 });
+        }
+        else {
+            // Refuse a symlinked or world-writable directory — same reasoning as
+            // lib.sh's private_dir: dedup state must not be steerable by another
+            // user on a shared machine.
+            const st = lstatSync(dir);
+            if (st.isSymbolicLink() || (st.mode & 0o022) !== 0)
+                return noop;
+        }
+        const hash = createHash('sha256')
+            .update(`${sessionId}:${filePath}`)
+            .digest('hex');
+        const marker = join(dir, hash);
+        if (existsSync(marker))
+            return { seen: true, markAsSeen: () => { } };
+        return {
+            seen: false,
+            markAsSeen: () => {
+                try {
+                    writeFileSync(marker, '');
+                }
+                catch {
+                    // best-effort — a missed marker just means the reminder repeats
+                }
+            },
+        };
+    }
+    catch {
+        return noop;
+    }
+}
+function buildMessage(opts) {
+    const where = opts.hasTree
+        ? '  1. Move it — verbatim is fine, it does not need rewriting — into a\n' +
+            '     lat.md/ section describing this behavior, decision, or design\n' +
+            '     intent. Use `lat search`/`lat locate` to find where it belongs;\n' +
+            '     create a new section only if nothing existing fits.'
+        : '  1. This project has no lat.md/ tree yet. Run `lat init` to create one\n' +
+            '     (or create lat.md/ by hand), then put the prose in a section there.';
+    return (`lat.md convention: you just wrote ${opts.count} comment line(s) in ${opts.base}.\n\n` +
+        'A code comment states a bare fact only — a unit, a bound, what null means, ' +
+        'an issue id, or an `@lat:` pointer. If a comment explains WHY (a reason, a ' +
+        "trade-off, a rejected alternative, a constraint, or an invariant's " +
+        'rationale) then it is documentation, not a comment.\n\n' +
+        'If any of what you just wrote explains why:\n' +
+        `${where}\n` +
+        '  2. Leave a pointer behind in the code:\n' +
+        `       ${opts.marker} @lat: [[section-id]]\n\n` +
+        'Never narrate what the code does: if a reader could write the comment ' +
+        'from the code alone, delete it.');
+}
+/**
+ * Computes the reminder context for a single Edit/Write call, or `null` if
+ * nothing warrants one. Pure and synchronous so it's trivial to unit test —
+ * all the fallible bits (fs, git, marker dedup) are wrapped internally and
+ * degrade to "say nothing" or "say it again", never to a thrown error.
+ */
+export function computeCommentReminder(input) {
+    const toolInput = input.tool_input ?? {};
+    const filePath = toolInput.file_path;
+    if (!filePath)
+        return null;
+    if (/\.md$/i.test(filePath))
+        return null;
+    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)
+        return null;
+    const sessionId = input.session_id;
+    let dedup = null;
+    if (sessionId) {
+        dedup = alreadyReminded(sessionId, filePath);
+        if (dedup.seen)
+            return null;
+    }
+    const projectRoot = resolveProjectRoot(filePath, input.cwd);
+    if (!projectRoot)
+        return null;
+    const hasTree = hasLatTree(projectRoot);
+    const base = basename(filePath);
+    const message = buildMessage({
+        base,
+        count: candidates.length,
+        marker: family.marker,
+        hasTree,
+    });
+    dedup?.markAsSeen();
+    return message;
+}

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

@@ -0,0 +1,11 @@
+import type { CmdContext, Styler } from '../context.js';
+export type { CmdContext };
+export declare function makeStyler(): Styler;
+export declare function resolveContext(opts: {
+    dir?: string;
+    color?: boolean;
+}): CmdContext;
+export declare function resolveCheckContext(opts: {
+    dir?: string;
+    color?: boolean;
+}, target?: string): CmdContext;

package/dist/src/cli/context.js

@@ -0,0 +1,58 @@
+import { statSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { styleText } from 'node:util';
+import { findLatticeDir } from '../lattice.js';
+export function makeStyler() {
+    return {
+        bold: (s) => styleText('bold', s),
+        dim: (s) => styleText('dim', s),
+        red: (s) => styleText('red', s),
+        cyan: (s) => styleText('cyan', s),
+        white: (s) => styleText('white', s),
+        green: (s) => styleText('green', s),
+        yellow: (s) => styleText('yellow', s),
+        boldWhite: (s) => styleText(['bold', 'white'], s),
+    };
+}
+export function resolveContext(opts) {
+    const color = opts.color !== false;
+    if (!color) {
+        process.env.NO_COLOR = '1';
+    }
+    const latDir = findLatticeDir(opts.dir) ?? '';
+    if (!latDir) {
+        console.error(styleText('red', 'No lat.md directory found'));
+        console.error(styleText('dim', 'Run `lat init` to create one.'));
+        process.exit(1);
+    }
+    const projectRoot = dirname(latDir);
+    return { latDir, projectRoot, styler: makeStyler(), mode: 'cli' };
+}
+export function resolveCheckContext(opts, target) {
+    if (target === undefined)
+        return resolveContext(opts);
+    if (opts.color === false) {
+        process.env.NO_COLOR = '1';
+    }
+    const projectRoot = resolve(opts.dir ?? process.cwd());
+    const latDir = resolve(projectRoot, target);
+    try {
+        if (!statSync(latDir).isDirectory()) {
+            console.error(styleText('red', `Check target is not a directory: ${target}`));
+            process.exit(1);
+        }
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+        console.error(styleText('red', `Check directory not found: ${target}`));
+        process.exit(1);
+    }
+    return {
+        latDir,
+        projectRoot,
+        styler: makeStyler(),
+        mode: 'cli',
+        headless: true,
+    };
+}

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

@@ -0,0 +1,8 @@
+import { type Section } from '../lattice.js';
+import type { CmdContext, CmdResult } from '../context.js';
+/**
+ * Resolve [[refs]] in text and return the expanded output.
+ * Returns null if there are no wiki links, or if resolution fails.
+ */
+export declare function expandPrompt(ctx: CmdContext, text: string, preloadedSections?: Section[]): Promise<string | null>;
+export declare function expandCommand(ctx: CmdContext, text: string): Promise<CmdResult>;