@thesmurph/agentlink 0.1.0

package/dist/convention.js

@@ -0,0 +1,187 @@
+import { existsSync, lstatSync, mkdirSync, readFileSync, readlinkSync, renameSync } from "node:fs";
+import path from "node:path";
+import { writeFileAtomic } from "./link.js";
+export const BEGIN_MARKER = "<!-- agentlink:begin v1 -->";
+export const END_MARKER = "<!-- agentlink:end -->";
+/** Whole-line markers only: prose mentioning the marker is not the marker. */
+const BEGIN_LINE = /^<!-- agentlink:begin v1 -->[ \t]*$/m;
+const END_LINE = /^<!-- agentlink:end -->[ \t]*$/m;
+const PROJECT_CLAUSE = `${BEGIN_MARKER}
+## Agent docs and skills: one source of truth
+
+This repository keeps exactly one copy of every agent instruction file and skill.
+Paths such as \`CLAUDE.md\`, \`GEMINI.md\`, \`.claude/skills/\` and \`.cursor/skills/\`
+are symlinks maintained by \`agentlink\`. Never edit a symlink, and never create a
+file next to one — edit or create the source it points to.
+
+- **Instructions** live in \`AGENTS.md\` at the repository root.
+- **Skills** live in \`.agents/skills/<skill-name>/SKILL.md\`, one directory per skill.
+- **Extra documentation** goes under \`.agents/\` (for example \`.agents/testing.md\`),
+  or in an \`AGENTS.md\` in the subdirectory it applies to.
+- **Naming**: the skill directory and its frontmatter \`name\` are the same
+  lowercase-hyphenated string, 1-64 characters (\`pdf-forms\`, not \`PDF_Forms\`).
+  \`SKILL.md\` needs frontmatter with \`name\` and a \`description\` that states what
+  the skill does *and* when to use it. Keep scripts and references inside the
+  skill directory and link them with relative paths.
+- **After adding, renaming, or moving a skill or doc**, run \`agentlink sync\`
+  so every harness picks up the change.
+${END_MARKER}`;
+const GLOBAL_CLAUSE = `${BEGIN_MARKER}
+## Personal agent setup
+
+This is your user-level instructions file, loaded by every session regardless of
+project. Personal skills live once, in \`~/.agents/skills/<skill-name>/SKILL.md\`.
+Paths such as \`~/.claude/CLAUDE.md\` and \`~/.claude/skills/\` are symlinks
+maintained by \`agentlink\`; never edit a symlink, and never create a file or
+skill directory next to one.
+
+A project that carries its own \`AGENTS.md\` and \`.agents/skills/\` takes
+precedence over anything here, so keep this file to preferences that apply
+everywhere: how you like work done, what to ask before doing, personal tooling.
+
+- **Naming**: skill directory and frontmatter \`name\` are the same
+  lowercase-hyphenated string, 1-64 characters.
+- **After adding, renaming, or moving a personal skill**, run
+  \`agentlink sync --global\`.
+${END_MARKER}`;
+/**
+ * The clause agentlink appends to AGENTS.md.
+ *
+ * Its job is to tell a *future agent* — one that has never heard of agentlink —
+ * where documentation and skills belong and how to name them, so the convention
+ * survives without a human enforcing it. The text differs by scope because a
+ * global file is loaded in every project, including ones that do not use this
+ * convention, so it must not claim anything about "this repository".
+ */
+export function clauseFor(scope) {
+    return scope === "global" ? GLOBAL_CLAUSE : PROJECT_CLAUSE;
+}
+/** The repository-scope clause, kept as a named export for documentation. */
+export const CLAUSE = PROJECT_CLAUSE;
+export function hasClause(text) {
+    return BEGIN_LINE.test(text);
+}
+/**
+ * Insert the clause, or replace the existing one in place.
+ *
+ * A lone marker is left untouched: the text after an unterminated block might be
+ * the user's own prose, and guessing would delete it.
+ */
+export function upsertClause(text, scope = "project") {
+    const clause = clauseFor(scope);
+    const begin = BEGIN_LINE.exec(text);
+    const end = END_LINE.exec(text);
+    if (begin && !end)
+        return { text, changed: false, action: "malformed" };
+    if (!begin && end)
+        return { text, changed: false, action: "malformed" };
+    if (begin && end) {
+        const endIndex = end.index;
+        const existing = text.slice(begin.index, endIndex + end[0].length);
+        if (existing === clause)
+            return { text, changed: false, action: "unchanged" };
+        const next = `${text.slice(0, begin.index)}${clause}${text.slice(endIndex + end[0].length)}`;
+        return { text: next, changed: true, action: "updated" };
+    }
+    const trimmed = text.replace(/\s+$/, "");
+    const separator = trimmed.length === 0 ? "" : "\n\n";
+    return { text: `${trimmed}${separator}${clause}\n`, changed: true, action: "inserted" };
+}
+export function ensureClause(paths, options = {}) {
+    const file = paths.instructions;
+    if (!existsSync(file))
+        return { changed: false, action: "unchanged", file };
+    const before = readFileSync(file, "utf8");
+    const { text, changed, action } = upsertClause(before, paths.scope);
+    if (changed && !options.dryRun)
+        writeFileAtomic(file, text);
+    return { changed, action, file };
+}
+/** Create AGENTS.md and .agents/skills/ when they do not exist yet. */
+export function initConvention(paths, options = {}) {
+    const createdFile = !existsSync(paths.instructions);
+    if (createdFile && !options.dryRun) {
+        const title = path.basename(paths.root) || "project";
+        const heading = paths.scope === "global" ? "Global agent instructions" : title;
+        const body = paths.scope === "global"
+            ? "<!-- Preferences that apply in every project. Project AGENTS.md files take precedence. -->"
+            : "<!-- One or two sentences: what this is, who it is for. -->";
+        writeFileAtomic(paths.instructions, `# ${heading}\n\n${body}\n\n${clauseFor(paths.scope)}\n`);
+    }
+    else if (!options.dryRun) {
+        ensureClause(paths, options);
+    }
+    const createdSkillsDir = !existsSync(paths.skills);
+    if (createdSkillsDir && !options.dryRun)
+        mkdirSync(paths.skills, { recursive: true });
+    return {
+        createdFile,
+        createdSkillsDir,
+        file: paths.instructions,
+        skills: paths.skills,
+    };
+}
+/**
+ * Migrate a harness instructions file into the canonical AGENTS.md.
+ *
+ * Only the unambiguous case is handled: AGENTS.md is absent and exactly one real
+ * (non-symlink) harness file exists. A rename keeps `git log --follow` intact and
+ * leaves the old path as a symlink afterwards. When both files exist as real
+ * content, merging is a judgement call and we refuse.
+ */
+export function adoptInstructions(paths, options = {}) {
+    const candidates = ["CLAUDE.md", "GEMINI.md", "QWEN.md", "CRUSH.md", "WARP.md", "CONTEXT.md"];
+    const present = candidates
+        .map((name) => path.join(paths.root, name))
+        .filter((file) => existsSync(file) && !isSymlink(file));
+    if (existsSync(paths.instructions)) {
+        if (isSymlink(paths.instructions)) {
+            // AGENTS.md is itself an alias, so something else holds the real content.
+            const link = isSymlink(paths.instructions) ? targetsOf(paths.instructions) : undefined;
+            return {
+                performed: false,
+                needsInvert: true,
+                reason: `AGENTS.md is a symlink${link ? ` to ${link}` : ""} — make AGENTS.md the real file and link the other name to it`,
+            };
+        }
+        if (present.length > 0) {
+            return {
+                performed: false,
+                reason: `AGENTS.md and ${present.map((p) => path.basename(p)).join(", ")} both contain real content — merge them by hand, then re-run`,
+            };
+        }
+        return { performed: false, reason: "AGENTS.md already exists" };
+    }
+    if (present.length === 0)
+        return { performed: false, reason: "no harness instructions file to adopt" };
+    if (present.length > 1) {
+        const names = present.map((p) => path.basename(p));
+        return {
+            performed: false,
+            reason: `several candidates (${names.join(", ")}) — keep one, delete or merge the others, then re-run`,
+        };
+    }
+    const from = present[0];
+    if (options.dryRun) {
+        return { performed: false, reason: "dry run", from, to: paths.instructions };
+    }
+    // A rename keeps the original bytes and shows up as a rename in git.
+    renameSync(from, paths.instructions);
+    return { performed: true, from, to: paths.instructions };
+}
+function isSymlink(file) {
+    try {
+        return lstatSync(file).isSymbolicLink();
+    }
+    catch {
+        return false;
+    }
+}
+function targetsOf(file) {
+    try {
+        return readlinkSync(file);
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/detect.js

@@ -0,0 +1,37 @@
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import path from "node:path";
+import { HARNESSES } from "./harnesses.js";
+/** Look the binary up in PATH without shelling out. */
+export function isOnPath(bins) {
+    const dirs = (process.env.PATH ?? "").split(path.delimiter).filter(Boolean);
+    const exts = process.platform === "win32" ? (process.env.PATHEXT ?? ".EXE").split(";") : [""];
+    for (const bin of bins) {
+        for (const dir of dirs) {
+            for (const ext of exts) {
+                const candidate = path.join(dir, bin + ext);
+                if (existsSync(candidate))
+                    return candidate;
+            }
+        }
+    }
+    return undefined;
+}
+/**
+ * A harness counts as present when its binary is on PATH or its config
+ * directory exists. Config roots come from `herdr integration status`, which
+ * knows where each harness actually keeps its state.
+ */
+export function detect(harness, home = homedir()) {
+    const reasons = [];
+    const bin = isOnPath(harness.bins);
+    if (bin)
+        reasons.push(`binary ${path.basename(bin)}`);
+    const configPath = path.join(home, harness.configRoot);
+    if (existsSync(configPath))
+        reasons.push(`config ${harness.configRoot.startsWith(".") ? "~/" : ""}${harness.configRoot}`);
+    return { harness, installed: reasons.length > 0, reasons };
+}
+export function detectAll(home = homedir()) {
+    return HARNESSES.map((harness) => detect(harness, home));
+}

package/dist/doctor.js

@@ -0,0 +1,263 @@
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import path from "node:path";
+import { clauseFor, hasClause, BEGIN_MARKER } from "./convention.js";
+import { unverifiedEndpoints } from "./harnesses.js";
+import { ignoreEntries, isIgnoreMode, readIgnoreBlock } from "./ignore.js";
+import { inspect, plan, readState } from "./link.js";
+import { listHiddenSubdirectories, listSubdirectories } from "./scope.js";
+export function readSkills(paths) {
+    return listSubdirectories(paths.skills).map((name) => {
+        const dir = path.join(paths.skills, name);
+        const direct = path.join(dir, "SKILL.md");
+        const hasDirectSkillFile = existsSync(direct);
+        return {
+            name,
+            dir,
+            hasDirectSkillFile,
+            hasNestedSkillFile: !hasDirectSkillFile && findNestedSkillFile(dir, 1) !== undefined,
+            frontmatter: hasDirectSkillFile ? parseFrontmatter(readFileSync(direct, "utf8")) : {},
+        };
+    });
+}
+/** A SKILL.md in a subdirectory, which only some harnesses read. */
+export function findNestedSkillFile(dir, depth = 0) {
+    const direct = path.join(dir, "SKILL.md");
+    if (existsSync(direct))
+        return direct;
+    if (depth >= 2)
+        return undefined;
+    for (const child of listSubdirectories(dir)) {
+        const found = findNestedSkillFile(path.join(dir, child), depth + 1);
+        if (found)
+            return found;
+    }
+    return undefined;
+}
+export function parseFrontmatter(text) {
+    if (!text.startsWith("---"))
+        return {};
+    const end = text.indexOf("\n---", 3);
+    if (end === -1)
+        return {};
+    const block = text.slice(3, end);
+    const read = (key) => {
+        const match = block.match(new RegExp(`^${key}:\\s*(.+)$`, "m"));
+        if (!match?.[1])
+            return undefined;
+        return match[1].trim().replace(/^["']|["']$/g, "");
+    };
+    return { name: read("name"), description: read("description") };
+}
+/**
+ * Report the problems a user can act on.
+ *
+ * Missing or misdirected links for a selected harness are errors, not warnings:
+ * the whole promise of the tool is that the harness reads what you wrote, and a
+ * repository that fails that should not pass a CI check.
+ */
+export function diagnose({ paths, harnesses }) {
+    const findings = [];
+    // With nothing selected there are no links to check. Say so, rather than
+    // reporting a clean bill of health that was never actually earned: a CI
+    // runner has no harnesses installed, so this is reachable on every run.
+    if (harnesses.length === 0) {
+        findings.push({
+            severity: "warn",
+            message: "no harnesses are selected or installed, so only the convention was checked",
+            fix: "agentlink init, or pass --harnesses to check a specific set",
+        });
+    }
+    // --- the convention itself ------------------------------------------------
+    const instructionsExist = existsSync(paths.instructions);
+    if (!instructionsExist) {
+        findings.push({
+            severity: "error",
+            message: `${label(paths, paths.instructions)} is missing`,
+            fix: "agentlink init",
+        });
+    }
+    else {
+        const text = readFileSync(paths.instructions, "utf8");
+        if (!hasClause(text)) {
+            findings.push({
+                severity: "warn",
+                message: `${path.basename(paths.instructions)} does not explain the convention to agents`,
+                fix: "agentlink sync  (appends the agentlink clause)",
+            });
+        }
+        else if (!text.includes(clauseFor(paths.scope))) {
+            findings.push({
+                severity: "info",
+                message: `${path.basename(paths.instructions)} has an outdated agentlink clause, or an unterminated one`,
+                fix: "agentlink sync, then check the section by hand",
+            });
+        }
+    }
+    if (!existsSync(paths.skills)) {
+        findings.push({
+            severity: "warn",
+            message: `${short(paths, paths.skills)} does not exist`,
+            fix: "agentlink init",
+        });
+    }
+    // --- skills ---------------------------------------------------------------
+    for (const file of safeReadDir(paths.skills).filter((name) => name.endsWith(".md"))) {
+        findings.push({
+            severity: "warn",
+            message: `${short(paths, path.join(paths.skills, file))} sits at the root of .agents/skills`,
+            fix: "move it into .agents/skills/<skill-name>/SKILL.md — root Markdown is not a skill",
+        });
+    }
+    for (const hidden of listHiddenSubdirectories(paths.skills)) {
+        findings.push({
+            severity: "info",
+            message: `.agents/skills/${hidden} starts with a dot, so it is skipped`,
+            fix: "rename it without the dot to publish it as a skill",
+        });
+    }
+    for (const name of safeReadDir(paths.skills)) {
+        const entry = path.join(paths.skills, name);
+        if (name.startsWith(".") || name.endsWith(".md"))
+            continue;
+        const kind = inspect(entry).kind;
+        if (kind === "symlink") {
+            const target = inspect(entry).resolved;
+            if (!target || !existsSync(target)) {
+                findings.push({
+                    severity: "error",
+                    message: `.agents/skills/${name} is a broken symlink`,
+                    fix: "remove it or point it at a directory that exists",
+                });
+            }
+            continue;
+        }
+        if (kind === "error") {
+            findings.push({
+                severity: "error",
+                message: `.agents/skills/${name} cannot be read`,
+                fix: "check permissions on the path",
+            });
+        }
+    }
+    for (const skill of readSkills(paths)) {
+        if (!skill.hasDirectSkillFile) {
+            findings.push({
+                severity: "error",
+                message: skill.hasNestedSkillFile
+                    ? `.agents/skills/${skill.name} has no SKILL.md directly inside, only nested ones — most harnesses will not find it`
+                    : `.agents/skills/${skill.name} has no SKILL.md`,
+                fix: "put SKILL.md at .agents/skills/<skill-name>/SKILL.md",
+            });
+            continue;
+        }
+        const name = skill.frontmatter.name;
+        if (!name) {
+            findings.push({
+                severity: "error",
+                message: `.agents/skills/${skill.name}/SKILL.md has no \`name\` frontmatter`,
+                fix: "add `name:` matching the directory name",
+            });
+            continue;
+        }
+        if (name !== skill.name) {
+            findings.push({
+                severity: "warn",
+                message: `.agents/skills/${skill.name} declares name \`${name}\``,
+                fix: "keep the directory name and frontmatter name identical so every harness resolves it",
+            });
+        }
+        if (!/^[a-z0-9]+(-[a-z0-9]+)*$/.test(name) || name.length > 64) {
+            findings.push({
+                severity: "error",
+                message: `skill name \`${name}\` is not lowercase-hyphenated, 1-64 chars`,
+            });
+        }
+        if (!skill.frontmatter.description) {
+            findings.push({
+                severity: "error",
+                message: `.agents/skills/${skill.name}/SKILL.md has no \`description\``,
+                fix: "describe what the skill does and when to use it",
+            });
+        }
+    }
+    // --- links ----------------------------------------------------------------
+    const desired = plan(paths, harnesses);
+    for (const op of desired.ops) {
+        const existing = inspect(op.target);
+        if (existing.kind === "missing") {
+            findings.push({
+                severity: "error",
+                message: `${short(paths, op.target)} is not linked (${op.harnessIds.join(", ")})`,
+                fix: "agentlink sync",
+            });
+        }
+        else if (existing.kind === "symlink" && existing.resolved !== op.source) {
+            findings.push({
+                severity: "error",
+                message: `${short(paths, op.target)} points at ${short(paths, existing.resolved ?? "")}`,
+                fix: "agentlink sync",
+            });
+        }
+        else if (existing.kind === "file" || existing.kind === "dir") {
+            if (op.kind === "instructions") {
+                findings.push({
+                    severity: "error",
+                    message: `${short(paths, op.target)} is a real ${existing.kind}, not a symlink — two copies of your instructions`,
+                    fix: "agentlink adopt  (moves it to AGENTS.md and links back)",
+                });
+            }
+            else {
+                // Reported even when empty: an empty directory still blocks the link.
+                findings.push({
+                    severity: "error",
+                    message: `${short(paths, op.target)} is a real ${existing.kind} instead of a link to skill \`${op.skill}\``,
+                    fix: `agentlink fix  (the canonical copy is .agents/skills/${op.skill})`,
+                });
+            }
+        }
+    }
+    // --- honesty about the table ---------------------------------------------
+    for (const harness of harnesses) {
+        for (const { kind, endpoint } of unverifiedEndpoints(harness, paths.scope)) {
+            const where = endpoint.native ? "native path" : endpoint.alias;
+            findings.push({
+                severity: "info",
+                message: `${harness.label}: ${kind} ${where} is not confirmed by ${harness.source}`,
+            });
+        }
+    }
+    // --- gitignore ------------------------------------------------------------
+    const state = readState(paths);
+    const mode = isIgnoreMode(state.ignore) ? state.ignore : "skills";
+    if (paths.scope === "project" && existsSync(path.join(paths.root, ".git")) && mode !== "none") {
+        const expected = ignoreEntries(mode, {
+            skillDirs: [...new Set(desired.ops.filter((op) => op.kind === "skill").map((op) => path.posix.dirname(op.rel)))],
+            instructionFiles: [...new Set(desired.ops.filter((op) => op.kind === "instructions").map((op) => op.rel))],
+        });
+        const actual = readIgnoreBlock(paths);
+        const missing = expected.filter((entry) => !actual.includes(entry));
+        if (missing.length > 0) {
+            findings.push({
+                severity: "warn",
+                message: `${missing.length} linked path${missing.length === 1 ? "" : "s"} would show up as untracked: ${missing.slice(0, 3).join(", ")}${missing.length > 3 ? ", …" : ""}`,
+                fix: "agentlink sync",
+            });
+        }
+    }
+    return findings;
+}
+function safeReadDir(dir) {
+    try {
+        return readdirSync(dir);
+    }
+    catch {
+        return [];
+    }
+}
+function short(paths, absolute) {
+    return path.relative(paths.root, absolute) || ".";
+}
+function label(paths, absolute) {
+    return path.join(paths.scope === "global" ? "~" : ".", short(paths, absolute));
+}
+export { statSync, BEGIN_MARKER };

package/dist/fix.js

@@ -0,0 +1,183 @@
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, readdirSync, readlinkSync, realpathSync, renameSync, rmSync, } from "node:fs";
+import path from "node:path";
+import { inspect, isOwned, isInside, pruneEmptyParents } from "./link.js";
+import { listSubdirectories, relativeTo } from "./scope.js";
+/**
+ * Find real copies sitting where a symlink belongs.
+ *
+ * A copy is cheap to resolve when the canonical tree has nothing at that name
+ * (move it in) or has an identical directory (delete the copy). When the two
+ * differ, nothing is guessed: the caller reports both paths and stops, unless
+ * the user explicitly asks for the canonical copy to win.
+ */
+export function planFixes(paths, harnesses) {
+    const actions = [];
+    const seen = new Set();
+    for (const harness of harnesses) {
+        const skills = harness.skills[paths.scope];
+        if (!skills.native && skills.alias) {
+            const dir = path.join(paths.root, skills.alias);
+            // A harness directory that is itself a symlink into the canonical tree
+            // would make every entry look like an identical duplicate of itself.
+            // Acting on that would delete the canonical skills.
+            if (isInsideCanonical(paths, dir))
+                continue;
+            for (const name of listSubdirectories(dir)) {
+                const target = path.join(dir, name);
+                const rel = relativeTo(paths.root, target);
+                if (seen.has(rel))
+                    continue;
+                seen.add(rel);
+                // Only real directories are copies. Symlinks are already correct, and
+                // a symlinked directory is resolved through, never replaced.
+                if (inspect(target).kind !== "dir")
+                    continue;
+                if (isInsideCanonical(paths, target))
+                    continue;
+                const source = path.join(paths.skills, name);
+                const canonical = relativeTo(paths.root, source);
+                if (!existsSync(source)) {
+                    actions.push({ target: rel, canonical, kind: "move", skill: name });
+                }
+                else if (hashTree(target) === hashTree(source)) {
+                    actions.push({ target: rel, canonical, kind: "remove-identical", skill: name });
+                }
+                else {
+                    actions.push({ target: rel, canonical, kind: "conflict", skill: name, detail: "both copies differ" });
+                }
+            }
+        }
+        // Instructions: a real file or directory where a symlink belongs needs a human.
+        const instructions = harness.instructions[paths.scope];
+        if (!instructions.native && instructions.alias && existsSync(paths.instructions)) {
+            const target = path.join(paths.root, instructions.alias);
+            const rel = relativeTo(paths.root, target);
+            const kind = inspect(target).kind;
+            if (!seen.has(rel) && (kind === "file" || kind === "dir")) {
+                seen.add(rel);
+                actions.push({
+                    target: rel,
+                    canonical: relativeTo(paths.root, paths.instructions),
+                    kind: "conflict",
+                    detail: "two copies of your instructions",
+                });
+            }
+        }
+    }
+    return actions;
+}
+/** True when `candidate` is the canonical skills tree, or inside it. */
+function isInsideCanonical(paths, candidate) {
+    if (!existsSync(candidate))
+        return false;
+    let real;
+    try {
+        real = realpathSync(candidate);
+    }
+    catch {
+        return false;
+    }
+    let skillsReal;
+    try {
+        skillsReal = realpathSync(paths.skills);
+    }
+    catch {
+        return false;
+    }
+    if (isInside(skillsReal, real))
+        return true;
+    try {
+        // Resolving the parent catches a canonical entry that is itself a symlink
+        // into .agents, which realpath already collapsed above.
+        return isInside(realpathSync(paths.agentsDir), real);
+    }
+    catch {
+        return false;
+    }
+}
+export function applyFixes(paths, actions, options = {}) {
+    return actions.map((action) => {
+        if (action.kind === "conflict" && !options.force)
+            return { ...action, performed: false };
+        const target = path.join(paths.root, action.target);
+        const canonical = path.join(paths.root, action.canonical);
+        // Never touch anything that is not inside the scope root, and never touch
+        // the canonical tree itself.
+        if (!isInside(paths.root, target) || isOwned(paths, target)) {
+            return { ...action, performed: false, detail: "refused: outside the scope root" };
+        }
+        if (options.dryRun)
+            return { ...action, performed: false };
+        try {
+            if (action.kind === "move") {
+                mkdirSync(path.dirname(canonical), { recursive: true });
+                renameSync(target, canonical);
+            }
+            else {
+                rmSync(target, { recursive: true, force: true });
+            }
+            pruneEmptyParents(path.dirname(target), paths.root);
+            return { ...action, performed: true };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return { ...action, performed: false, detail: `failed: ${message}` };
+        }
+    });
+}
+/** Stable hash of a directory tree, tolerant of line-ending differences. */
+export function hashTree(dir) {
+    const hash = createHash("sha256");
+    walk(dir, "", hash);
+    return hash.digest("hex");
+}
+function walk(current, prefix, hash) {
+    let entries;
+    try {
+        entries = readdirSync(current, { withFileTypes: true });
+    }
+    catch (error) {
+        // An unreadable directory must not look like an empty one.
+        hash.update(`unreadable ${prefix} ${error?.code ?? "?"}\n`);
+        return;
+    }
+    for (const entry of [...entries].sort((a, b) => a.name.localeCompare(b.name))) {
+        const rel = prefix ? `${prefix}/${entry.name}` : entry.name;
+        const full = path.join(current, entry.name);
+        if (entry.isSymbolicLink()) {
+            hash.update(`link ${rel} ${safeReadlink(full)}\n`);
+        }
+        else if (entry.isDirectory()) {
+            hash.update(`dir ${rel}\n`);
+            walk(full, rel, hash);
+        }
+        else {
+            hash.update(`file ${rel} ${hashFile(full)}\n`);
+        }
+    }
+}
+function hashFile(file) {
+    try {
+        const buffer = readFileSync(file);
+        // Treat CRLF and LF files as equal so a Windows-authored copy is not
+        // reported as a conflict.
+        const isBinary = buffer.includes(0);
+        const content = isBinary ? buffer : Buffer.from(buffer.toString("utf8").replace(/\r\n/g, "\n"));
+        return createHash("sha256").update(content).digest("hex");
+    }
+    catch (error) {
+        // A constant sentinel would make two different unreadable files compare
+        // equal, which would pick "identical" and delete one of them.
+        const code = error?.code ?? "?";
+        return `unreadable:${code}:${Buffer.from(file).toString("base64")}`;
+    }
+}
+function safeReadlink(file) {
+    try {
+        return readlinkSync(file);
+    }
+    catch {
+        return "?";
+    }
+}