docsgov 0.1.0

package/dist/repo/repo.js

@@ -0,0 +1,353 @@
+// Package repo is the OS boundary for docgov. It is the only package that
+// touches the real filesystem directly and owns OS path handling. Everything
+// else works with slash paths and the FS interface.
+//
+// Responsibilities:
+//   - Walk CWD up to the nearest ancestor containing a .docgov/ directory.
+//   - Fall back to the supplied directory when no .docgov/ exists (gen/add
+//     bootstrapping mode).
+//   - Return a Repo that exposes an FS and the OS root path.
+//   - CRLF -> LF normalisation on every file read.
+import * as nodefs from "node:fs/promises";
+import * as path from "node:path";
+import { isNotExist, RealFS } from "./fs.js";
+import { OverlayFS } from "./overlay.js";
+// sentinel is the directory name that marks a docgov repository root.
+const sentinel = ".docgov";
+/**
+ * Holds the resolved repository root. It is the sole owner of the OS path; all
+ * callers work through the {@link FS} interface or the slash-path readFile
+ * helper.
+ */
+export class Repo {
+    rootPath;
+    fsys;
+    /** @internal Use {@link find} or {@link Repo.withOverlay}. */
+    constructor(rootPath, fsys) {
+        this.rootPath = rootPath;
+        this.fsys = fsys;
+    }
+    /** The absolute OS path of the repository root. */
+    root() {
+        return this.rootPath;
+    }
+    /**
+     * The {@link FS} rooted at the repository root. All names passed to its
+     * methods must use forward slashes (the io/fs convention).
+     */
+    fs() {
+        return this.fsys;
+    }
+    /**
+     * Reads the named file (slash path, relative to repo root) and returns its
+     * contents with CRLF sequences normalised to LF. Throws on I/O failure.
+     */
+    async readFile(name) {
+        const data = await this.fsys.readFile(name);
+        return normalizeCRLF(data);
+    }
+    /**
+     * Reports whether a regular file exists at `repoRel` (a slash path relative
+     * to the repo root) with exact case for every path segment. Returns false for
+     * directories — the docs guard checks file references, not directories.
+     *
+     * Exact-case check: a host filesystem stat case-folds on macOS and Windows,
+     * so it would wrongly accept "Docs/ADR/0001.md" when the real path is
+     * "docs/adr/0001.md". This walks each directory's entries and matches each
+     * segment by exact string equality, so a case mismatch at any segment returns
+     * false regardless of host behaviour.
+     *
+     * I/O errors: a genuinely missing path returns false. Any other directory
+     * read error is propagated (Rule 12 — fail loud) so callers can distinguish
+     * "absent" from "broken repo".
+     */
+    async exists(repoRel) {
+        // Normalise: strip leading slash, then clean using slash semantics so the
+        // logical slash path is never contaminated by OS-specific separators.
+        let rel = repoRel.startsWith("/") ? repoRel.slice(1) : repoRel;
+        rel = path.posix.normalize(rel);
+        if (rel === "." || rel === "") {
+            return false;
+        }
+        const segments = rel.split("/");
+        let current = this.fsys;
+        for (let i = 0; i < segments.length; i++) {
+            const seg = segments[i];
+            let entries;
+            try {
+                entries = await current.readDir(".");
+            }
+            catch (err) {
+                if (isNotExist(err)) {
+                    return false;
+                }
+                throw err;
+            }
+            // Find an entry matching this segment with exact case.
+            const found = entries.find((e) => e.name() === seg);
+            if (!found) {
+                // No exact-case match at this segment.
+                return false;
+            }
+            const isLast = i === segments.length - 1;
+            if (isLast) {
+                // The final segment must be a regular file (not a directory).
+                return !found.isDir();
+            }
+            // Not the final segment: descend into the subdirectory.
+            if (!found.isDir()) {
+                // Expected a directory but found a file — path not valid.
+                return false;
+            }
+            current = current.sub(seg);
+        }
+        return false;
+    }
+    /**
+     * Reports whether a regular file exists at `slashPath` (slash path relative
+     * to the repo root). Returns false for directories and for any path that
+     * cannot be resolved — I/O errors are treated as "not present" so the caller
+     * falls through to the subsequent write, which surfaces the error with richer
+     * context. This intentionally differs from {@link exists}, which propagates
+     * I/O errors so the docs guard can distinguish "absent" from "broken repo".
+     */
+    async fileExists(slashPath) {
+        let abs;
+        try {
+            abs = this.toAbs(slashPath);
+        }
+        catch {
+            return false;
+        }
+        try {
+            const info = await nodefs.stat(abs);
+            return info.isFile();
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Returns a new Repo identical to this one except that reads of `slashPath`
+     * (via {@link fs} or {@link readFile}) return `content` instead of the
+     * on-disk bytes. All other paths delegate to the base FS. The base Repo is
+     * not modified.
+     */
+    withOverlay(slashPath, content) {
+        const ov = new OverlayFS(this.fsys, slashPath, content);
+        return new Repo(this.rootPath, ov);
+    }
+    // --- write capability (the sole owner of all OS writes) ---
+    /**
+     * Writes `data` to the file at `slashPath` (slash-relative to the repo root),
+     * creating all parent directories as needed. Throws if `slashPath` would
+     * escape the repo root via ".." traversal.
+     */
+    async writeFile(slashPath, data) {
+        const abs = this.toAbs(slashPath);
+        try {
+            await nodefs.mkdir(path.dirname(abs), { recursive: true });
+        }
+        catch (err) {
+            throw new Error(`repo.writeFile: mkdir parents for ${JSON.stringify(slashPath)}: ${errMsg(err)}`);
+        }
+        try {
+            await nodefs.writeFile(abs, data);
+        }
+        catch (err) {
+            throw new Error(`repo.writeFile: write ${JSON.stringify(slashPath)}: ${errMsg(err)}`);
+        }
+    }
+    /**
+     * Renames the directory at `oldSlashPath` to `newSlashPath` (both
+     * slash-relative to the repo root). The parent of `newSlashPath` must already
+     * exist (os.Rename semantics).
+     */
+    async renameDir(oldSlashPath, newSlashPath) {
+        const oldAbs = this.toAbs(oldSlashPath);
+        const newAbs = this.toAbs(newSlashPath);
+        try {
+            await nodefs.rename(oldAbs, newAbs);
+        }
+        catch (err) {
+            throw new Error(`repo.renameDir: rename ${JSON.stringify(oldSlashPath)} -> ${JSON.stringify(newSlashPath)}: ${errMsg(err)}`);
+        }
+    }
+    /**
+     * Removes the directory tree rooted at `slashPath` (slash-relative to the
+     * repo root). A no-op when the path does not exist, matching the
+     * write-with-backup stale-.bak cleanup use-case.
+     */
+    async removeAll(slashPath) {
+        const abs = this.toAbs(slashPath);
+        try {
+            await nodefs.rm(abs, { recursive: true, force: true });
+        }
+        catch (err) {
+            throw new Error(`repo.removeAll: remove ${JSON.stringify(slashPath)}: ${errMsg(err)}`);
+        }
+    }
+    /**
+     * Reports whether a directory exists at `slashPath` (slash-relative to the
+     * repo root). Returns false for any stat error (including not-found).
+     */
+    async dirExists(slashPath) {
+        let abs;
+        try {
+            abs = this.toAbs(slashPath);
+        }
+        catch {
+            return false;
+        }
+        try {
+            const info = await nodefs.stat(abs);
+            return info.isDirectory();
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Writes `content` to a temp file that is a sibling of the file at
+     * `slashPath` (same directory, ".docgov-flip.tmp" suffix), then returns a
+     * {@link PendingWrite}. The caller calls commit to either rename the temp
+     * into place (ok=true) or remove it (ok=false). The temp file is always in
+     * the same directory as the target so the rename stays atomic on a single
+     * filesystem.
+     */
+    async atomicWriteFile(slashPath, content) {
+        const abs = this.toAbs(slashPath);
+        try {
+            await nodefs.mkdir(path.dirname(abs), { recursive: true });
+        }
+        catch (err) {
+            throw new Error(`repo.atomicWriteFile: mkdir parents for ${JSON.stringify(slashPath)}: ${errMsg(err)}`);
+        }
+        const tmpAbs = abs + ".docgov-flip.tmp";
+        try {
+            await nodefs.writeFile(tmpAbs, content);
+        }
+        catch (err) {
+            throw new Error(`repo.atomicWriteFile: write temp for ${JSON.stringify(slashPath)}: ${errMsg(err)}`);
+        }
+        return new PendingWrite(tmpAbs, abs);
+    }
+    /**
+     * Converts a slash-relative path to an absolute OS path under the repo root.
+     * Throws if the result would escape the repo root (".." traversal).
+     */
+    toAbs(slashPath) {
+        // Convert slash path to OS-native segments, then join under root.
+        const abs = path.join(this.rootPath, ...slashPath.split("/"));
+        // Verify the result is still within the repo root. path.join collapses ".."
+        // elements, so checking the prefix is sufficient.
+        let rootWithSep = this.rootPath;
+        if (!rootWithSep.endsWith(path.sep)) {
+            rootWithSep += path.sep;
+        }
+        if (abs !== this.rootPath && !abs.startsWith(rootWithSep)) {
+            throw new Error(`repo: path ${JSON.stringify(slashPath)} escapes repository root ${JSON.stringify(this.rootPath)}`);
+        }
+        return abs;
+    }
+}
+/**
+ * Holds the paths needed to complete or roll back an atomic write started by
+ * {@link Repo.atomicWriteFile}. Call commit(true) to rename the temp file into
+ * place, or commit(false) to remove the temp file and leave the original
+ * untouched.
+ */
+export class PendingWrite {
+    tmpAbs;
+    finalAbs;
+    /** @internal */
+    constructor(tmpAbs, finalAbs) {
+        this.tmpAbs = tmpAbs;
+        this.finalAbs = finalAbs;
+    }
+    /**
+     * Finalises (ok=true: atomic rename into place) or rolls back (ok=false:
+     * remove the temp, leave the original untouched) the pending write.
+     */
+    async commit(ok) {
+        if (!ok) {
+            try {
+                await nodefs.rm(this.tmpAbs);
+            }
+            catch (err) {
+                if (!isNotExist(err)) {
+                    throw new Error(`repo.PendingWrite.commit(rollback): remove temp ${JSON.stringify(this.tmpAbs)}: ${errMsg(err)}`);
+                }
+            }
+            return;
+        }
+        try {
+            await nodefs.rename(this.tmpAbs, this.finalAbs);
+        }
+        catch (err) {
+            throw new Error(`repo.PendingWrite.commit(commit): rename ${JSON.stringify(this.tmpAbs)} -> ${JSON.stringify(this.finalAbs)}: ${errMsg(err)}`);
+        }
+    }
+    /**
+     * Exposes the temp path so tests can assert the atomicity invariant — that
+     * the temp file is a sibling of the target, not in the OS temp dir. Mirrors
+     * Go's TmpAbsForTest export-test helper.
+     */
+    tmpAbsForTest() {
+        return this.tmpAbs;
+    }
+}
+/**
+ * Walks up from `dir` to locate the nearest ancestor containing a .docgov/
+ * directory. If none is found it falls back to `dir` itself (so gen and add can
+ * bootstrap a repo that has no .docgov/ yet). `dir` is resolved to an absolute
+ * OS path first.
+ */
+export async function find(dir) {
+    const abs = path.resolve(dir);
+    let current = abs;
+    for (;;) {
+        const candidate = path.join(current, sentinel);
+        let isDir = false;
+        try {
+            const info = await nodefs.stat(candidate);
+            isDir = info.isDirectory();
+        }
+        catch {
+            isDir = false;
+        }
+        if (isDir) {
+            // Found the sentinel directory.
+            return new Repo(current, new RealFS(current));
+        }
+        const parent = path.dirname(current);
+        if (parent === current) {
+            // Reached the filesystem root without finding .docgov/. Fall back to the
+            // original dir (bootstrapping mode).
+            return new Repo(abs, new RealFS(abs));
+        }
+        current = parent;
+    }
+}
+// normalizeCRLF replaces every CRLF (0x0d 0x0a) byte sequence with a single LF,
+// matching Go's bytes.ReplaceAll(data, "\r\n", "\n"). Operates on raw bytes so
+// no text decoding is involved.
+function normalizeCRLF(data) {
+    // Fast path: no CR present.
+    if (!data.includes(0x0d)) {
+        return data;
+    }
+    const out = [];
+    for (let i = 0; i < data.length; i++) {
+        if (data[i] === 0x0d && i + 1 < data.length && data[i + 1] === 0x0a) {
+            out.push(0x0a);
+            i++; // skip the LF; the CRLF pair becomes a single LF
+            continue;
+        }
+        out.push(data[i]);
+    }
+    return Uint8Array.from(out);
+}
+function errMsg(err) {
+    return err instanceof Error ? err.message : String(err);
+}

package/dist/repo/repo.test.js

@@ -0,0 +1,255 @@
+import * as nodefs from "node:fs/promises";
+import * as path from "node:path";
+import { describe, expect, test } from "vitest";
+import { find } from "./repo.js";
+import { makeDir } from "./testutil.js";
+const dec = new TextDecoder();
+describe("find: repo-root discovery", () => {
+    // WHY: when a .docgov/ exists in the ancestor chain, that ancestor is the
+    // repo root — governance config lives relative to it.
+    test("returns the ancestor that owns .docgov/ when CWD is the root", async () => {
+        const root = await makeDir(".docgov");
+        const r = await find(root);
+        expect(r.root()).toBe(root);
+        // The FS must be usable — list the sentinel dir through it.
+        const entries = await r.fs().readDir(".");
+        expect(entries.map((e) => e.name())).toContain(".docgov");
+    });
+    // WHY: gen/add must be able to bootstrap a repo that has no .docgov/ yet;
+    // falling back to the supplied dir is what makes that possible.
+    test("falls back to the supplied dir when no .docgov/ exists (bootstrapping)", async () => {
+        const root = await makeDir(); // no .docgov
+        const r = await find(root);
+        expect(r.root()).toBe(root);
+    });
+    // WHY: a check run from a nested working directory must resolve the same repo
+    // root as a run from the top — the walk-up is what guarantees that.
+    test("walks up from a nested directory to the .docgov/ owner", async () => {
+        const root = await makeDir(".docgov", "a/b/c");
+        const nested = path.join(root, "a", "b", "c");
+        const r = await find(nested);
+        expect(r.root()).toBe(root);
+    });
+});
+// WHY: callers must never see carriage returns; normalisation at the read
+// boundary keeps every downstream parser CRLF-agnostic and reports
+// byte-identical across platforms.
+test("readFile normalises CRLF to LF so callers never see CR", async () => {
+    const root = await makeDir(".docgov");
+    await nodefs.writeFile(path.join(root, "test.txt"), "line one\r\nline two\r\n");
+    const r = await find(root);
+    const got = dec.decode(await r.readFile("test.txt"));
+    expect(got).not.toContain("\r");
+    expect(got).toBe("line one\nline two\n");
+});
+const enc = new TextEncoder();
+describe("exists: exact-case file presence for the docs guard", () => {
+    // WHY: the docs guard validates file references; a real regular file at the
+    // exact path must report present so a valid reference is not flagged broken.
+    test("returns true for an existing regular file (exact case)", async () => {
+        const root = await makeDir(".docgov", "docs/adr");
+        const r = await find(root);
+        await r.writeFile("docs/adr/0001.md", enc.encode("x\n"));
+        expect(await r.exists("docs/adr/0001.md")).toBe(true);
+    });
+    // WHY: host filesystems case-fold on macOS/Windows; exists() must NOT, or a
+    // wrong-case reference ("Docs/...") would be wrongly accepted and ship broken.
+    test("returns false when a path segment differs only in case", async () => {
+        const root = await makeDir(".docgov", "docs/adr");
+        const r = await find(root);
+        await r.writeFile("docs/adr/0001.md", enc.encode("x\n"));
+        expect(await r.exists("Docs/adr/0001.md")).toBe(false);
+        expect(await r.exists("docs/adr/0001.MD")).toBe(false);
+    });
+    // WHY: the guard checks file references, not directory references; a reference
+    // that resolves to a directory must be rejected as not-a-file.
+    test("returns false when the final segment is a directory", async () => {
+        const root = await makeDir(".docgov", "docs/adr");
+        const r = await find(root);
+        expect(await r.exists("docs/adr")).toBe(false);
+    });
+    // WHY: a reference whose interior segment is a file (not a dir) cannot be
+    // descended into; treating it as present would mask a malformed reference.
+    test("returns false when an interior segment is a file, not a directory", async () => {
+        const root = await makeDir(".docgov", "docs");
+        const r = await find(root);
+        await r.writeFile("docs/a.md", enc.encode("x\n"));
+        // a.md is a file, so "a.md/inner.md" cannot descend.
+        expect(await r.exists("docs/a.md/inner.md")).toBe(false);
+    });
+    // WHY: a missing leaf in an existing directory is the common "broken
+    // reference" case the guard must catch — it must report absent, not error.
+    test("returns false for a missing final segment", async () => {
+        const root = await makeDir(".docgov", "docs");
+        const r = await find(root);
+        expect(await r.exists("docs/missing.md")).toBe(false);
+    });
+    // WHY: an empty or root-only path is never a file reference; returning false
+    // keeps the guard from treating "." as a present file.
+    test("returns false for the root / empty path", async () => {
+        const root = await makeDir(".docgov");
+        const r = await find(root);
+        expect(await r.exists("/")).toBe(false);
+        expect(await r.exists("")).toBe(false);
+    });
+    // WHY: a leading slash is a slash-relative reference, not an absolute OS path;
+    // it must be stripped so the lookup still resolves under the repo root.
+    test("strips a leading slash before resolving", async () => {
+        const root = await makeDir(".docgov", "docs");
+        const r = await find(root);
+        await r.writeFile("docs/a.md", enc.encode("x\n"));
+        expect(await r.exists("/docs/a.md")).toBe(true);
+    });
+});
+describe("fileExists / dirExists: write-with-backup precondition checks", () => {
+    // WHY: the write-with-backup layer asks "is there already a file here?"; a
+    // genuine file must report true so it backs up instead of clobbering.
+    test("fileExists is true for a file and false for a directory or missing path", async () => {
+        const root = await makeDir(".docgov", "docs");
+        const r = await find(root);
+        await r.writeFile("docs/a.md", enc.encode("x\n"));
+        expect(await r.fileExists("docs/a.md")).toBe(true);
+        expect(await r.fileExists("docs")).toBe(false); // a directory
+        expect(await r.fileExists("docs/missing.md")).toBe(false);
+    });
+    // WHY: fileExists swallows resolution faults as "not present" (unlike exists)
+    // so the caller falls through to the write that surfaces a richer error; an
+    // escaping path must therefore be reported absent, not throw here.
+    test("fileExists returns false for a path that escapes the repo root", async () => {
+        const root = await makeDir(".docgov");
+        const r = await find(root);
+        expect(await r.fileExists("../outside.md")).toBe(false);
+    });
+    // WHY: dirExists gates directory operations (rename targets, group dirs); a
+    // real directory must report true and a file or missing path false.
+    test("dirExists is true for a directory and false for a file or missing path", async () => {
+        const root = await makeDir(".docgov", "docs");
+        const r = await find(root);
+        await r.writeFile("docs/a.md", enc.encode("x\n"));
+        expect(await r.dirExists("docs")).toBe(true);
+        expect(await r.dirExists("docs/a.md")).toBe(false); // a file
+        expect(await r.dirExists("docs/missing")).toBe(false);
+    });
+    // WHY: same swallow-faults contract — an escaping directory path must be
+    // reported absent rather than throwing, so callers branch on a boolean.
+    test("dirExists returns false for a path that escapes the repo root", async () => {
+        const root = await makeDir(".docgov");
+        const r = await find(root);
+        expect(await r.dirExists("../outside")).toBe(false);
+    });
+});
+describe("writeFile: the sole owner of OS writes", () => {
+    // WHY: docgov generates files into nested doc dirs that may not exist yet;
+    // writeFile must create parents so generation does not fail on a fresh repo.
+    test("creates missing parent directories", async () => {
+        const root = await makeDir(".docgov");
+        const r = await find(root);
+        await r.writeFile("docs/deep/nested/a.md", enc.encode("hello\n"));
+        expect(dec.decode(await r.readFile("docs/deep/nested/a.md"))).toBe("hello\n");
+    });
+    // WHY: writeFile is the single guarded write boundary; a path escaping the
+    // root must be refused (via toAbs) so generation can never scribble outside
+    // the repo. The error names the offending path for diagnosis.
+    test("refuses a path that escapes the repo root", async () => {
+        const root = await makeDir(".docgov");
+        const r = await find(root);
+        await expect(r.writeFile("../escape.md", enc.encode("x"))).rejects.toThrow(/escapes repository root/);
+    });
+});
+describe("renameDir / removeAll: directory lifecycle", () => {
+    // WHY: rename is used to move a generated group dir into place; it must move
+    // the tree atomically so a half-renamed dir never appears.
+    test("renameDir moves a directory tree to a new name", async () => {
+        const root = await makeDir(".docgov", "old");
+        const r = await find(root);
+        await r.writeFile("old/a.md", enc.encode("x\n"));
+        await r.renameDir("old", "new");
+        expect(await r.dirExists("old")).toBe(false);
+        expect(await r.fileExists("new/a.md")).toBe(true);
+    });
+    // WHY: a failed rename (e.g. missing source) must throw with context naming
+    // both paths so the operator can see which move broke — Rule 12 fail loud.
+    test("renameDir throws with both paths when the source is missing", async () => {
+        const root = await makeDir(".docgov");
+        const r = await find(root);
+        await expect(r.renameDir("missing", "dest")).rejects.toThrow(/repo\.renameDir/);
+    });
+    // WHY: removeAll backs the stale-.bak cleanup; it must delete an existing tree
+    // so a leftover backup dir does not block the next write.
+    test("removeAll deletes an existing directory tree", async () => {
+        const root = await makeDir(".docgov", "junk");
+        const r = await find(root);
+        await r.writeFile("junk/a.md", enc.encode("x\n"));
+        await r.removeAll("junk");
+        expect(await r.dirExists("junk")).toBe(false);
+    });
+    // WHY: the cleanup use-case calls removeAll even when nothing is there; it
+    // must be a no-op (force:true), never throw, so cleanup is idempotent.
+    test("removeAll is a no-op for a missing path", async () => {
+        const root = await makeDir(".docgov");
+        const r = await find(root);
+        await expect(r.removeAll("nope")).resolves.toBeUndefined();
+    });
+});
+describe("atomicWriteFile + PendingWrite: crash-safe flips", () => {
+    // WHY: the flip writes to a SIBLING temp so the rename stays on one filesystem
+    // and is atomic; if the temp landed in the OS temp dir the rename could cross
+    // devices and silently degrade to a non-atomic copy.
+    test("writes a sibling temp file, not one in the OS temp dir", async () => {
+        const root = await makeDir(".docgov", "docs");
+        const r = await find(root);
+        const pending = await r.atomicWriteFile("docs/a.md", enc.encode("new\n"));
+        const tmp = pending.tmpAbsForTest();
+        expect(tmp).toBe(path.join(root, "docs", "a.md.docgov-flip.tmp"));
+        // The target itself is not yet written before commit.
+        expect(await r.fileExists("docs/a.md")).toBe(false);
+        await pending.commit(true);
+    });
+    // WHY: commit(true) is what makes the new content visible; after it the target
+    // holds the new bytes and the temp is gone (renamed into place).
+    test("commit(true) renames the temp into place", async () => {
+        const root = await makeDir(".docgov", "docs");
+        const r = await find(root);
+        const pending = await r.atomicWriteFile("docs/a.md", enc.encode("committed\n"));
+        await pending.commit(true);
+        expect(dec.decode(await r.readFile("docs/a.md"))).toBe("committed\n");
+        expect(await r.fileExists(pending.tmpAbsForTest())).toBe(false);
+    });
+    // WHY: commit(false) is the rollback path; it must remove the temp and leave
+    // any original untouched, so an aborted flip changes nothing on disk.
+    test("commit(false) removes the temp and leaves the original untouched", async () => {
+        const root = await makeDir(".docgov", "docs");
+        const r = await find(root);
+        await r.writeFile("docs/a.md", enc.encode("original\n"));
+        const pending = await r.atomicWriteFile("docs/a.md", enc.encode("new\n"));
+        await pending.commit(false);
+        expect(dec.decode(await r.readFile("docs/a.md"))).toBe("original\n");
+        expect(await nodefs.stat(pending.tmpAbsForTest()).then(() => true).catch(() => false)).toBe(false);
+    });
+    // WHY: rollback must be idempotent — if the temp is already gone, commit(false)
+    // must swallow the ENOENT (not re-throw), so a double-rollback never crashes
+    // the cleanup path.
+    test("commit(false) is a no-op when the temp is already removed", async () => {
+        const root = await makeDir(".docgov", "docs");
+        const r = await find(root);
+        const pending = await r.atomicWriteFile("docs/a.md", enc.encode("x\n"));
+        await nodefs.rm(pending.tmpAbsForTest()); // remove it out from under commit
+        await expect(pending.commit(false)).resolves.toBeUndefined();
+    });
+    // WHY: atomicWriteFile must create the target's parent dirs, mirroring
+    // writeFile, so a flip into a not-yet-existing doc dir succeeds.
+    test("creates missing parent directories for the temp", async () => {
+        const root = await makeDir(".docgov");
+        const r = await find(root);
+        const pending = await r.atomicWriteFile("docs/new/a.md", enc.encode("y\n"));
+        await pending.commit(true);
+        expect(dec.decode(await r.readFile("docs/new/a.md"))).toBe("y\n");
+    });
+    // WHY: atomicWriteFile is also a guarded write; an escaping path must be
+    // refused before any temp is created.
+    test("refuses a path that escapes the repo root", async () => {
+        const root = await makeDir(".docgov");
+        const r = await find(root);
+        await expect(r.atomicWriteFile("../escape.md", enc.encode("x"))).rejects.toThrow(/escapes repository root/);
+    });
+});

package/dist/repo/testutil.js

@@ -0,0 +1,27 @@
+import * as nodefs from "node:fs/promises";
+import * as os from "node:os";
+import * as path from "node:path";
+import { afterEach } from "vitest";
+// makeDir is the TS analogue of the Go test helper of the same name: it creates
+// a fresh temp directory and any requested subdirectories (slash-separated,
+// relative to the root) and returns the root OS path. Created roots are removed
+// after each test.
+const createdRoots = [];
+afterEach(async () => {
+    for (const root of createdRoots.splice(0)) {
+        await nodefs.rm(root, { recursive: true, force: true });
+    }
+});
+export async function makeDir(...dirs) {
+    const root = await nodefs.mkdtemp(path.join(os.tmpdir(), "docgov-repo-"));
+    // Resolve symlinks (macOS /var -> /private/var) so toAbs prefix checks and
+    // root equality assertions compare canonical paths.
+    const realRoot = await nodefs.realpath(root);
+    createdRoots.push(realRoot);
+    for (const d of dirs) {
+        await nodefs.mkdir(path.join(realRoot, ...d.split("/")), {
+            recursive: true,
+        });
+    }
+    return realRoot;
+}