gisool 0.0.0-stage → 0.1.0

package/dist/catalog/index.js

@@ -0,0 +1,133 @@
+import { readFile } from "node:fs/promises";
+import { applyFamilies } from "./fields.js";
+import { assertRegularSkillPath, CatalogError, scanRoot, sha256 } from "./scanner.js";
+import { parseSkillUri, skillUri } from "./uri.js";
+import { watchRoots } from "./watcher.js";
+export { CatalogError } from "./scanner.js";
+export { parseSkillUri, skillUri } from "./uri.js";
+function deltaIsEmpty(d) {
+    return d.added.length === 0 && d.changed.length === 0 && d.removed.length === 0;
+}
+/** Indexes the configured skill roots in place. Nothing is scanned until refresh(); nothing is ever written. */
+export function createCatalog(config) {
+    const roots = config.roots.map((r) => ({ id: r.id, path: r.path }));
+    const log = config.log ?? console.error;
+    let entries = new Map();
+    let resourceIndex = new Map();
+    let families = [];
+    let rootStatus = roots.map((r) => ({ id: r.id, path: r.path, readable: false, count: 0 }));
+    const listeners = new Set();
+    let chain = Promise.resolve();
+    async function scan() {
+        const next = [];
+        const explicit = new Map();
+        const status = [];
+        const seen = new Set();
+        for (const root of roots) {
+            const { readable, skills } = await scanRoot(root, log);
+            let count = 0;
+            for (const { entry, explicitGroup } of skills) {
+                if (seen.has(entry.uri))
+                    continue;
+                seen.add(entry.uri);
+                next.push(entry);
+                explicit.set(entry.uri, explicitGroup);
+                count += 1;
+            }
+            status.push({ id: root.id, path: root.path, readable, count });
+        }
+        next.sort((a, b) => (a.uri < b.uri ? -1 : a.uri > b.uri ? 1 : 0));
+        const nextFamilies = applyFamilies(next, explicit);
+        const delta = { added: [], changed: [], removed: [] };
+        const nextMap = new Map(next.map((e) => [e.uri, e]));
+        for (const entry of next) {
+            const prev = entries.get(entry.uri);
+            if (!prev)
+                delta.added.push(entry);
+            else if (prev.manifestDigest !== entry.manifestDigest || JSON.stringify(prev.group) !== JSON.stringify(entry.group))
+                delta.changed.push(entry);
+        }
+        for (const uri of entries.keys())
+            if (!nextMap.has(uri))
+                delta.removed.push(uri);
+        const nextResources = new Map();
+        for (const entry of next)
+            for (const r of entry.resources)
+                nextResources.set(r.uri, { entry, digest: r.digest, size: r.size });
+        entries = nextMap;
+        resourceIndex = nextResources;
+        families = nextFamilies;
+        rootStatus = status;
+        if (!deltaIsEmpty(delta)) {
+            for (const cb of listeners) {
+                try {
+                    cb(delta);
+                }
+                catch (error) {
+                    log(`catalog onDelta listener failed: ${error.message}`);
+                }
+            }
+        }
+        return delta;
+    }
+    function refresh() {
+        const run = chain.then(scan, scan);
+        chain = run.catch(() => undefined);
+        return run;
+    }
+    const watcher = config.watch
+        ? watchRoots(roots, () => {
+            refresh().catch((error) => log(`catalog refresh failed: ${error.message}`));
+        }, { debounceMs: config.watchDebounceMs, log })
+        : undefined;
+    return {
+        list: () => [...entries.values()],
+        get: (uri) => entries.get(uri),
+        async readResource(uri) {
+            const parsed = parseSkillUri(uri);
+            if (!parsed)
+                throw new CatalogError("invalid_uri", "not a valid skill://local URI");
+            const root = roots.find((r) => r.id === parsed.rootId);
+            if (!root)
+                throw new CatalogError("unknown_root", `unknown skill root: ${parsed.rootId}`);
+            const canonical = skillUri(parsed.rootId, ...parsed.segments);
+            const filePath = await assertRegularSkillPath(root.path, parsed.segments);
+            const known = resourceIndex.get(canonical);
+            if (!known)
+                throw new CatalogError("unknown_resource", "resource is not in any skill manifest");
+            const bytes = await readFile(filePath);
+            const digest = sha256(bytes);
+            if (digest !== known.digest)
+                throw new CatalogError("digest_mismatch", "resource changed since the last catalog refresh");
+            return { text: bytes.toString("utf8"), digest, size: bytes.byteLength };
+        },
+        refresh,
+        onDelta(cb) {
+            listeners.add(cb);
+            return () => listeners.delete(cb);
+        },
+        report() {
+            const byName = new Map();
+            for (const entry of entries.values()) {
+                if (!byName.has(entry.name))
+                    byName.set(entry.name, { roots: new Set(), uris: [] });
+                const slot = byName.get(entry.name);
+                slot.roots.add(entry.rootId);
+                slot.uris.push(entry.uri);
+            }
+            const duplicates = [...byName.entries()]
+                .filter(([, v]) => v.roots.size > 1)
+                .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+                .map(([name, v]) => ({ name, uris: v.uris.sort() }));
+            return {
+                duplicates,
+                families: families.map((f) => ({ id: f.id, uris: [...f.uris] })),
+                roots: rootStatus.map((r) => ({ ...r })),
+            };
+        },
+        close() {
+            watcher?.close();
+            listeners.clear();
+        },
+    };
+}

package/dist/catalog/scanner.js

@@ -0,0 +1,185 @@
+// Ported from server/src/index.ts @48e7955
+import { createHash } from "node:crypto";
+import { lstat, readdir, readFile, stat } from "node:fs/promises";
+import path from "node:path";
+import { extractFields, splitSkillMarkdown } from "./fields.js";
+import { skillUri } from "./uri.js";
+/** SEP-2640 limits per skill. */
+export const MAX_SKILL_RESOURCE_COUNT = 512;
+export const MAX_SKILL_TOTAL_BYTES = 16 * 1024 * 1024;
+export class CatalogError extends Error {
+    code;
+    constructor(code, message) {
+        super(`${code}: ${message}`);
+        this.name = "CatalogError";
+        this.code = code;
+    }
+}
+export function sha256(bytes) {
+    return `sha256:${createHash("sha256").update(bytes).digest("hex")}`;
+}
+export function manifestDigest(resources) {
+    const sorted = resources.map(({ uri, digest, size }) => ({ uri, digest, size })).sort((a, b) => (a.uri < b.uri ? -1 : a.uri > b.uri ? 1 : 0));
+    return sha256(JSON.stringify(sorted));
+}
+/** Regular files under baseDir (relative posix paths), skipping dotfiles, node_modules and symlinks. */
+export async function collectSkillRelativeFiles(baseDir) {
+    const output = [];
+    async function walk(dir, prefix) {
+        const entries = await readdir(dir, { withFileTypes: true });
+        for (const entry of entries) {
+            if (entry.name.startsWith(".") || entry.name === "node_modules")
+                continue;
+            const relative = prefix ? `${prefix}/${entry.name}` : entry.name;
+            if (entry.isDirectory()) {
+                await walk(path.join(dir, entry.name), relative);
+            }
+            else if (entry.isFile()) {
+                const info = await lstat(path.join(dir, entry.name));
+                if (info.isFile())
+                    output.push({ relative, size: info.size });
+            }
+        }
+    }
+    await walk(baseDir, "");
+    return output.sort((a, b) => (a.relative < b.relative ? -1 : a.relative > b.relative ? 1 : 0));
+}
+/** Directories (relative to rootDir, never through symlinked dirs) that contain a SKILL.md. */
+export async function listSkillEntryDirs(rootDir) {
+    const output = [];
+    async function walk(dir, prefix) {
+        const entries = await readdir(dir, { withFileTypes: true });
+        for (const entry of entries) {
+            if (!entry.isDirectory() || entry.name.startsWith(".") || entry.name === "node_modules")
+                continue;
+            const relative = prefix ? `${prefix}/${entry.name}` : entry.name;
+            try {
+                const info = await stat(path.join(dir, entry.name, "SKILL.md"));
+                if (info.isFile())
+                    output.push(relative);
+            }
+            catch {
+                // not a skill directory; descendants may still contain one
+            }
+            await walk(path.join(dir, entry.name), relative);
+        }
+    }
+    await walk(rootDir, "");
+    return output.sort();
+}
+/** Builds one entry; returns null (with a stderr note) for anything that must not be served. Reads but never writes. */
+export async function buildSkillEntry(rootId, rootDir, dir, log = console.error) {
+    const skillDir = path.join(rootDir, dir);
+    const skillPath = path.join(skillDir, "SKILL.md");
+    let mtimeMs;
+    try {
+        const info = await lstat(skillPath);
+        if (!info.isFile() || info.isSymbolicLink()) {
+            log(`Skipping skill ${rootId}/${dir}: SKILL.md must be a regular file`);
+            return null;
+        }
+        mtimeMs = info.mtimeMs;
+    }
+    catch {
+        return null;
+    }
+    const files = await collectSkillRelativeFiles(skillDir);
+    const declaredBytes = files.reduce((sum, f) => sum + f.size, 0);
+    if (files.length > MAX_SKILL_RESOURCE_COUNT || declaredBytes > MAX_SKILL_TOTAL_BYTES) {
+        log(`Skipping skill ${rootId}/${dir}: exceeds SEP-2640 limits (${files.length} resources, ${declaredBytes} bytes)`);
+        return null;
+    }
+    let fields = null;
+    let skillDigest;
+    const resources = [];
+    let totalBytes = 0;
+    for (const { relative } of files) {
+        const bytes = await readFile(path.join(skillDir, relative));
+        totalBytes += bytes.byteLength;
+        const digest = sha256(bytes);
+        resources.push({ uri: skillUri(rootId, dir, relative), digest, size: bytes.byteLength });
+        if (relative === "SKILL.md") {
+            skillDigest = digest;
+            const { frontmatter, body } = splitSkillMarkdown(bytes.toString("utf8"));
+            fields = frontmatter ? extractFields(frontmatter, body) : null;
+        }
+    }
+    if (resources.length > MAX_SKILL_RESOURCE_COUNT || totalBytes > MAX_SKILL_TOTAL_BYTES) {
+        log(`Skipping skill ${rootId}/${dir}: exceeds SEP-2640 limits (${resources.length} resources, ${totalBytes} bytes)`);
+        return null;
+    }
+    if (!skillDigest)
+        return null;
+    if (!fields) {
+        log(`Skipping skill ${rootId}/${dir}: SKILL.md frontmatter requires name and description`);
+        return null;
+    }
+    if (fields.name !== dir.split("/").pop()) {
+        log(`Skipping skill ${rootId}/${dir}: frontmatter name "${fields.name}" does not match directory name`);
+        return null;
+    }
+    const { group, ...rest } = fields;
+    const entry = {
+        uri: skillUri(rootId, dir, "SKILL.md"),
+        rootId,
+        dir,
+        ...rest,
+        digest: skillDigest,
+        manifestDigest: manifestDigest(resources),
+        resources,
+        mtimeMs,
+    };
+    return group ? { entry, explicitGroup: group } : { entry };
+}
+/** Scans one root; a missing or unreadable root is reported as readable: false, not thrown. */
+export async function scanRoot(root, log = console.error) {
+    let dirs;
+    try {
+        const info = await stat(root.path);
+        if (!info.isDirectory())
+            return { readable: false, skills: [] };
+        dirs = await listSkillEntryDirs(root.path);
+    }
+    catch {
+        return { readable: false, skills: [] };
+    }
+    const skills = [];
+    for (const dir of dirs) {
+        try {
+            const skill = await buildSkillEntry(root.id, root.path, dir, log);
+            if (skill)
+                skills.push(skill);
+        }
+        catch (error) {
+            log(`Failed to build skill entry for ${root.id}/${dir}: ${error.message}`);
+        }
+    }
+    return { readable: true, skills };
+}
+/** Resolves segments under rootDir, refusing traversal outside the root and any symlink along the way. */
+export async function assertRegularSkillPath(rootDir, segments) {
+    const relativePath = path.posix.normalize(segments.join("/"));
+    const filePath = path.resolve(rootDir, relativePath);
+    const relativeToRoot = path.relative(rootDir, filePath);
+    if (!relativeToRoot || relativeToRoot.startsWith("..") || path.isAbsolute(relativeToRoot)) {
+        throw new CatalogError("path_outside_root", "resource path escapes its skill root");
+    }
+    let current = rootDir;
+    const parts = relativeToRoot.split(path.sep);
+    for (const [index, segment] of parts.entries()) {
+        current = path.join(current, segment);
+        let info;
+        try {
+            info = await lstat(current);
+        }
+        catch {
+            throw new CatalogError("unknown_resource", "unknown or inaccessible skill resource");
+        }
+        if (info.isSymbolicLink())
+            throw new CatalogError("symlink_refused", "symbolic links inside skill roots are not served");
+        if (index === parts.length - 1 ? !info.isFile() : !info.isDirectory()) {
+            throw new CatalogError("unknown_resource", "skill resources require regular files and directories");
+        }
+    }
+    return current;
+}

package/dist/catalog/uri.js

@@ -0,0 +1,41 @@
+export const SKILL_URI_AUTHORITY = "local";
+/** skill://local/<rootId>/<dir...>/<relative...>, each path segment URI-encoded. */
+export function skillUri(...segments) {
+    const parts = segments.flatMap((segment) => segment.split("/")).filter(Boolean);
+    return `skill://${SKILL_URI_AUTHORITY}/${parts.map((part) => encodeURIComponent(part)).join("/")}`;
+}
+/** Parses a skill URI into its root id and path segments; returns null for anything malformed or traversing. */
+export function parseSkillUri(uri) {
+    if (typeof uri !== "string" || /%2e/i.test(uri) || /%2f/i.test(uri) || uri.includes("\\"))
+        return null;
+    const authorityIndex = uri.indexOf("://");
+    const rawPath = authorityIndex === -1 ? uri : uri.slice(authorityIndex + 3);
+    if (rawPath.split("/").some((segment) => segment === ".." || segment === "."))
+        return null;
+    let parsed;
+    try {
+        parsed = new URL(uri);
+    }
+    catch {
+        return null;
+    }
+    if (parsed.protocol !== "skill:" || parsed.host !== SKILL_URI_AUTHORITY || parsed.username || parsed.password || parsed.search || parsed.hash || !parsed.pathname || parsed.pathname === "/")
+        return null;
+    let segments;
+    try {
+        segments = parsed.pathname.split("/").filter(Boolean).map(decodeURIComponent);
+    }
+    catch {
+        return null;
+    }
+    if (segments.length < 2)
+        return null;
+    const rootId = segments[0];
+    if (!/^[A-Za-z0-9._-]+$/.test(rootId))
+        return null;
+    for (const segment of segments.slice(1)) {
+        if (segment === ".." || segment === "." || segment.includes("/") || segment.includes("\0"))
+            return null;
+    }
+    return { rootId, segments: segments.slice(1) };
+}

package/dist/catalog/watcher.js

@@ -0,0 +1,59 @@
+import { watch } from "node:fs";
+export const WATCH_DEBOUNCE_MS = 500;
+const WATCH_FALLBACK_MS = 2000;
+/**
+ * Watches each root recursively and calls onChange once per quiet period of debounceMs.
+ * Roots that do not exist (or cannot be watched) are skipped with one log line; the next refresh still reports them unreadable.
+ * A watcher that errors later (EMFILE, EACCES) is logged once and closed; the periodic refresh keeps detecting changes.
+ */
+export function watchRoots(roots, onChange, opts) {
+    const debounceMs = opts.debounceMs ?? WATCH_DEBOUNCE_MS;
+    const watchers = [];
+    let timer;
+    let closed = false;
+    const schedule = () => {
+        if (closed)
+            return;
+        if (timer)
+            clearTimeout(timer);
+        timer = setTimeout(() => {
+            timer = undefined;
+            if (!closed)
+                onChange();
+        }, debounceMs);
+    };
+    for (const root of roots) {
+        try {
+            const watcher = watch(root.path, { recursive: true, persistent: false }, schedule);
+            let failed = false;
+            watcher.on("error", (error) => {
+                if (failed)
+                    return;
+                failed = true;
+                opts.log(`catalog watcher for root ${root.id} (${root.path}) failed: ${error.message}`);
+                watcher.close();
+            });
+            watchers.push(watcher);
+        }
+        catch (error) {
+            opts.log(`catalog watcher cannot watch root ${root.id} (${root.path}): ${error.message}`);
+        }
+    }
+    // fs.watch can drop events under load; a periodic refresh (no-op when nothing changed) bounds detection latency.
+    let poll;
+    if (watchers.length > 0) {
+        poll = setInterval(schedule, WATCH_FALLBACK_MS);
+        poll.unref();
+    }
+    return {
+        close() {
+            closed = true;
+            if (poll)
+                clearInterval(poll);
+            if (timer)
+                clearTimeout(timer);
+            for (const watcher of watchers)
+                watcher.close();
+        },
+    };
+}

package/dist/cli/config-writer.js

@@ -0,0 +1,255 @@
+import { createHash, randomUUID } from "node:crypto";
+import { chmodSync, existsSync, lstatSync, mkdirSync, readFileSync, renameSync, rmSync, rmdirSync, statSync, writeFileSync } from "node:fs";
+import { dirname, isAbsolute, join, relative } from "node:path";
+export class WriterError extends Error {
+    code;
+    paths;
+    constructor(code, message, paths = []) {
+        super(`${code}: ${message}`);
+        this.name = "WriterError";
+        this.code = code;
+        this.paths = paths;
+    }
+}
+export const sha256 = (text) => createHash("sha256").update(text).digest("hex");
+export function readTarget(path) {
+    let st;
+    try {
+        st = lstatSync(path);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return null;
+        throw error;
+    }
+    if (!st.isFile())
+        throw new WriterError("not_a_regular_file", `expected a regular file: ${path}`, [path]);
+    return readFileSync(path, "utf8");
+}
+export const changedFiles = (files) => files.filter((f) => f.before !== f.after);
+export function maskSecrets(text, secrets) {
+    let out = text;
+    for (const s of secrets)
+        if (s.length >= 8)
+            out = out.replaceAll(s, "<gisool-token>");
+    return out;
+}
+function splitLines(text) {
+    if (text === null || text === "")
+        return [];
+    const lines = text.split("\n");
+    if (lines[lines.length - 1] === "")
+        lines.pop();
+    return lines;
+}
+function diffOps(a, b) {
+    const n = a.length;
+    const m = b.length;
+    if (n * m > 25_000_000)
+        return [...a.map((line) => ({ tag: "-", line })), ...b.map((line) => ({ tag: "+", line }))];
+    // LCS table over suffixes; lcs[i][j] = LCS length of a[i..] and b[j..].
+    const w = m + 1;
+    const lcs = new Uint32Array((n + 1) * w);
+    for (let i = n - 1; i >= 0; i--) {
+        for (let j = m - 1; j >= 0; j--) {
+            lcs[i * w + j] = a[i] === b[j] ? lcs[(i + 1) * w + j + 1] + 1 : Math.max(lcs[(i + 1) * w + j], lcs[i * w + j + 1]);
+        }
+    }
+    const ops = [];
+    let i = 0;
+    let j = 0;
+    while (i < n && j < m) {
+        if (a[i] === b[j]) {
+            ops.push({ tag: " ", line: a[i] });
+            i++;
+            j++;
+        }
+        else if (lcs[(i + 1) * w + j] >= lcs[i * w + j + 1])
+            ops.push({ tag: "-", line: a[i++] });
+        else
+            ops.push({ tag: "+", line: b[j++] });
+    }
+    while (i < n)
+        ops.push({ tag: "-", line: a[i++] });
+    while (j < m)
+        ops.push({ tag: "+", line: b[j++] });
+    return ops;
+}
+export function unifiedDiff(path, before, after, context = 3) {
+    if (before === after)
+        return "";
+    const ops = diffOps(splitLines(before), splitLines(after));
+    const header = [`--- ${before === null ? "/dev/null" : `a${path}`}`, `+++ ${after === null ? "/dev/null" : `b${path}`}`];
+    const changes = ops.map((op, idx) => (op.tag === " " ? -1 : idx)).filter((idx) => idx >= 0);
+    if (changes.length === 0)
+        return [...header, "@@ whitespace or trailing newline only @@"].join("\n") + "\n";
+    const hunks = [];
+    for (const idx of changes) {
+        const start = Math.max(0, idx - context);
+        const end = Math.min(ops.length, idx + context + 1);
+        const last = hunks[hunks.length - 1];
+        if (last && start <= last[1])
+            last[1] = Math.max(last[1], end);
+        else
+            hunks.push([start, end]);
+    }
+    const out = [...header];
+    for (const [start, end] of hunks) {
+        let aLine = 1;
+        let bLine = 1;
+        for (let k = 0; k < start; k++) {
+            if (ops[k].tag !== "+")
+                aLine++;
+            if (ops[k].tag !== "-")
+                bLine++;
+        }
+        const slice = ops.slice(start, end);
+        const aLen = slice.filter((o) => o.tag !== "+").length;
+        const bLen = slice.filter((o) => o.tag !== "-").length;
+        out.push(`@@ -${aLen === 0 ? aLine - 1 : aLine},${aLen} +${bLen === 0 ? bLine - 1 : bLine},${bLen} @@`);
+        for (const o of slice)
+            out.push(`${o.tag}${o.line}`);
+    }
+    return out.join("\n") + "\n";
+}
+/** Unparseable targets are refused: only JSON is checked structurally (TOML and other formats are validated by their pack). */
+export function unparseable(file) {
+    if (!file.path.endsWith(".json") || file.before === null || file.before.trim() === "")
+        return undefined;
+    try {
+        JSON.parse(file.before);
+        return undefined;
+    }
+    catch (error) {
+        return error.message;
+    }
+}
+export function backupPathFor(backupDir, home, path) {
+    const rel = relative(home, path);
+    return rel && !rel.startsWith("..") && !isAbsolute(rel) ? join(backupDir, "files", rel) : join(backupDir, "files", "_root", path);
+}
+function snapshot(path) {
+    const text = readTarget(path);
+    return { exists: text !== null, mtimeMs: text === null ? 0 : statSync(path).mtimeMs, digest: text === null ? null : sha256(text) };
+}
+function mkdirTracked(dir, created) {
+    const missing = [];
+    let cur = dir;
+    while (!existsSync(cur)) {
+        missing.unshift(cur);
+        const parent = dirname(cur);
+        if (parent === cur)
+            break;
+        cur = parent;
+    }
+    for (const d of missing) {
+        mkdirSync(d, { mode: 0o700 });
+        created.push(d);
+    }
+}
+function atomicWrite(path, content, mode, expected) {
+    const tmp = `${path}.gisool-${randomUUID()}.tmp`;
+    try {
+        writeFileSync(tmp, content, { flag: "wx", mode });
+        chmodSync(tmp, mode);
+        if (expected) {
+            // Re-read mtime + digest immediately before the rename so a concurrent editor's change is never clobbered.
+            const now = snapshot(path);
+            if (now.exists !== expected.exists || now.digest !== expected.digest || now.mtimeMs !== expected.mtimeMs) {
+                throw new WriterError("concurrent_modification", `file changed during apply: ${path}`, [path]);
+            }
+        }
+        renameSync(tmp, path);
+    }
+    finally {
+        rmSync(tmp, { force: true });
+    }
+}
+/**
+ * Applies planned files atomically. Validates the whole plan first (unparseable or changed-since-plan files abort before
+ * any write), backs up originals under backupDir mirroring their path relative to home (0600), writes via temp + rename
+ * preserving an existing file's mode, and on any failure restores every file already written.
+ */
+export function applyFiles(files, opts) {
+    const todo = changedFiles(files);
+    const bad = todo.filter((f) => unparseable(f) !== undefined);
+    if (bad.length)
+        throw new WriterError("unparseable_config", `refusing to edit unparseable file(s): ${bad.map((f) => f.path).join(", ")}`, bad.map((f) => f.path));
+    const moved = todo.filter((f) => readTarget(f.path) !== f.before);
+    if (moved.length)
+        throw new WriterError("modified_since_plan", `file(s) changed after the plan was made: ${moved.map((f) => f.path).join(", ")}`, moved.map((f) => f.path));
+    const applied = [];
+    const createdDirs = [];
+    const written = [];
+    try {
+        for (const f of todo) {
+            const expected = snapshot(f.path);
+            if (expected.digest !== (f.before === null ? null : sha256(f.before))) {
+                throw new WriterError("modified_since_plan", `file changed after the plan was made: ${f.path}`, [f.path]);
+            }
+            let backup = null;
+            if (f.before !== null) {
+                backup = backupPathFor(opts.backupDir, opts.home, f.path);
+                mkdirSync(dirname(backup), { recursive: true, mode: 0o700 });
+                writeFileSync(backup, f.before, { flag: "wx", mode: 0o600 });
+                chmodSync(backup, 0o600);
+            }
+            const mode = f.before !== null ? statSync(f.path).mode & 0o777 : f.mode;
+            mkdirTracked(dirname(f.path), createdDirs);
+            atomicWrite(f.path, f.after, mode, expected);
+            written.push(f);
+            applied.push({ path: f.path, backup: backup === null ? null : relative(opts.backupDir, backup), existed: f.before !== null,
+                beforeDigest: f.before === null ? null : sha256(f.before), afterDigest: sha256(f.after), mode });
+        }
+    }
+    catch (error) {
+        restoreWritten(written);
+        removeEmptyDirs(createdDirs);
+        throw error;
+    }
+    return { files: applied, createdDirs };
+}
+function restoreWritten(written) {
+    for (const f of [...written].reverse()) {
+        if (readTarget(f.path) !== f.after)
+            continue;
+        if (f.before === null)
+            rmSync(f.path, { force: true });
+        else
+            atomicWrite(f.path, f.before, statSync(f.path).mode & 0o777, null);
+    }
+}
+export function removeEmptyDirs(dirs) {
+    for (const d of [...dirs].reverse()) {
+        try {
+            rmdirSync(d);
+        }
+        catch {
+            // Non-empty (someone else wrote there) or already gone: keep it.
+        }
+    }
+}
+/** Restores files recorded by applyFiles from backupDir; files edited since gisool wrote them are left alone. */
+export function restoreFiles(files, backupDir) {
+    const out = [];
+    for (const f of [...files].reverse()) {
+        const current = readTarget(f.path);
+        if (current === null && !f.existed) {
+            out.push({ path: f.path, action: "unchanged" });
+            continue;
+        }
+        if (current === null || sha256(current) !== f.afterDigest) {
+            out.push({ path: f.path, action: "skipped_modified" });
+            continue;
+        }
+        if (!f.existed || f.backup === null) {
+            rmSync(f.path, { force: true });
+            out.push({ path: f.path, action: "removed" });
+            continue;
+        }
+        const original = readFileSync(join(backupDir, f.backup), "utf8");
+        atomicWrite(f.path, original, f.mode, null);
+        out.push({ path: f.path, action: "restored" });
+    }
+    return out;
+}