@crewhaus/tool-lifecycle 0.7.0

package/dist/lib/tree.js

@@ -0,0 +1,284 @@
+/**
+ * Walking and fingerprinting a directory tree.
+ *
+ * Two tools need to say "this is exactly what moved, and it is still the same
+ * bytes afterwards": `HarnessRetire` (which archives a harness's `.crewhaus`
+ * and cannot get it back) and `StoreMigrate` (which must be able to report a
+ * half-finished migration rather than a boolean). Both answers come from
+ * here.
+ *
+ * Three properties the callers depend on:
+ *
+ *   1. A walk that hit anything it could not read comes back `complete:
+ *      false` with the reason. A manifest with a hole in it must never be
+ *      presented as a verified one — that is the failure this package exists
+ *      to avoid, at the exact moment the original is about to be destroyed.
+ *   2. Symlinks are recorded, never followed. Following them would walk out
+ *      of the tree (and could loop), and the archive move preserves the link
+ *      itself, so the link's TARGET is not what is being fingerprinted.
+ *   3. The budgets are checked while walking, not after. A tree that blows
+ *      the file or byte budget stops the walk and says so, rather than
+ *      hashing a hundred gigabytes because nobody looked first.
+ */
+import { createHash } from "node:crypto";
+import { lstatSync, readFileSync, readdirSync, readlinkSync } from "node:fs";
+import * as path from "node:path";
+import { fail } from "./result";
+const toPosix = (p) => (path.sep === "/" ? p : p.split(path.sep).join("/"));
+/**
+ * Walk `root` depth-first in sorted order.
+ *
+ * Sorted because a result that depends on `readdir` order is a result that
+ * differs between two machines looking at the same directory, and because the
+ * manifest this produces is compared byte-for-byte against a later walk.
+ */
+export function walkTree(root, opts) {
+    const entries = [];
+    const unreadable = [];
+    let fileCount = 0;
+    let totalBytes = 0;
+    let oldestMtimeMs;
+    let newestMtimeMs;
+    let budgetExceeded;
+    const visit = (abs, rel) => {
+        if (budgetExceeded !== undefined)
+            return;
+        let names;
+        try {
+            names = readdirSync(abs).sort();
+        }
+        catch (err) {
+            unreadable.push({
+                rel: rel === "" ? "." : rel,
+                reason: `directory could not be listed (${err.code ?? "unknown error"})`,
+            });
+            return;
+        }
+        for (const name of names) {
+            if (budgetExceeded !== undefined)
+                return;
+            const childAbs = path.join(abs, name);
+            const childRel = toPosix(rel === "" ? name : `${rel}/${name}`);
+            let stat;
+            try {
+                // lstat, not stat: a symlink is recorded as itself. `stat` would
+                // report its target's size and could be made to point anywhere.
+                stat = lstatSync(childAbs);
+            }
+            catch (err) {
+                unreadable.push({
+                    rel: childRel,
+                    reason: `could not be stat'd (${err.code ?? "unknown error"})`,
+                });
+                continue;
+            }
+            if (stat.isDirectory()) {
+                visit(childAbs, childRel);
+                continue;
+            }
+            if (stat.isSymbolicLink()) {
+                let target;
+                try {
+                    target = readlinkSync(childAbs);
+                }
+                catch (err) {
+                    unreadable.push({
+                        rel: childRel,
+                        reason: `symlink could not be read (${err.code ?? "unknown error"})`,
+                    });
+                    continue;
+                }
+                entries.push({ rel: childRel, kind: "symlink", bytes: 0, target });
+                continue;
+            }
+            if (!stat.isFile()) {
+                // A socket or a fifo is not data and cannot be hashed; it is recorded
+                // so the caller knows the archive will not be a faithful copy.
+                entries.push({ rel: childRel, kind: "other", bytes: 0 });
+                unreadable.push({ rel: childRel, reason: "not a regular file (not hashed)" });
+                continue;
+            }
+            fileCount += 1;
+            totalBytes += stat.size;
+            oldestMtimeMs =
+                oldestMtimeMs === undefined ? stat.mtimeMs : Math.min(oldestMtimeMs, stat.mtimeMs);
+            newestMtimeMs =
+                newestMtimeMs === undefined ? stat.mtimeMs : Math.max(newestMtimeMs, stat.mtimeMs);
+            if (fileCount > opts.maxFiles) {
+                budgetExceeded = `the tree holds more than ${opts.maxFiles} files`;
+                return;
+            }
+            if (totalBytes > opts.maxBytes) {
+                budgetExceeded = `the tree holds more than ${opts.maxBytes} bytes`;
+                return;
+            }
+            if (!opts.hash) {
+                entries.push({ rel: childRel, kind: "file", bytes: stat.size });
+                continue;
+            }
+            try {
+                entries.push({
+                    rel: childRel,
+                    kind: "file",
+                    bytes: stat.size,
+                    sha256: createHash("sha256").update(readFileSync(childAbs)).digest("hex"),
+                });
+            }
+            catch (err) {
+                unreadable.push({
+                    rel: childRel,
+                    reason: `could not be read for hashing (${err.code ?? "unknown error"})`,
+                });
+                entries.push({ rel: childRel, kind: "file", bytes: stat.size });
+            }
+        }
+    };
+    try {
+        visit(root, "");
+    }
+    catch (err) {
+        return fail("unreadable", `"${root}" could not be walked: ${err.message}`);
+    }
+    if (budgetExceeded !== undefined) {
+        return fail("too-large", `${budgetExceeded} — raise the budget explicitly if that is really what you meant to touch`);
+    }
+    return {
+        ok: true,
+        value: {
+            root,
+            entries,
+            fileCount,
+            totalBytes,
+            ...(oldestMtimeMs !== undefined ? { oldestMtimeMs } : {}),
+            ...(newestMtimeMs !== undefined ? { newestMtimeMs } : {}),
+            unreadable,
+            complete: unreadable.length === 0,
+        },
+    };
+}
+/**
+ * Check a tree against a manifest taken earlier.
+ *
+ * Used twice: after `HarnessRetire` moves `.crewhaus` into the archive (did
+ * every byte arrive?), and after `StoreMigrate` copies a store (is the
+ * destination really the source?). An entry the manifest never hashed is
+ * reported as unverifiable rather than counted as verified.
+ */
+export function verifyAgainst(destRoot, manifest, manifestComplete = true) {
+    const mismatched = [];
+    let verified = 0;
+    for (const entry of manifest) {
+        const abs = path.join(destRoot, ...entry.rel.split("/"));
+        let stat;
+        try {
+            stat = lstatSync(abs);
+        }
+        catch (err) {
+            mismatched.push({
+                rel: entry.rel,
+                problem: "missing",
+                detail: `not present at the destination (${err.code ?? "unknown error"})`,
+            });
+            continue;
+        }
+        if (entry.kind === "symlink") {
+            if (!stat.isSymbolicLink()) {
+                mismatched.push({ rel: entry.rel, problem: "kind", detail: "was a symlink, is not now" });
+                continue;
+            }
+            // The link's TARGET is the only content a symlink has, so verifying
+            // that a symlink is still a symlink verifies nothing about it. A
+            // repointed link would otherwise have counted towards `verified` at the
+            // moment the original was being destroyed.
+            let target;
+            try {
+                target = readlinkSync(abs);
+            }
+            catch (err) {
+                mismatched.push({
+                    rel: entry.rel,
+                    problem: "unreadable",
+                    detail: `symlink could not be read at the destination (${err.code ?? "unknown error"})`,
+                });
+                continue;
+            }
+            if (entry.target === undefined) {
+                mismatched.push({
+                    rel: entry.rel,
+                    problem: "unreadable",
+                    detail: "no target was recorded for this symlink, so it cannot be verified",
+                });
+                continue;
+            }
+            if (target !== entry.target) {
+                mismatched.push({
+                    rel: entry.rel,
+                    problem: "sha256",
+                    detail: `pointed at "${entry.target}" before, "${target}" now`,
+                });
+                continue;
+            }
+            verified += 1;
+            continue;
+        }
+        if (entry.kind !== "file") {
+            mismatched.push({
+                rel: entry.rel,
+                problem: "unreadable",
+                detail: "not a regular file — nothing was hashed, so nothing can be verified",
+            });
+            continue;
+        }
+        if (stat.size !== entry.bytes) {
+            mismatched.push({
+                rel: entry.rel,
+                problem: "size",
+                detail: `${entry.bytes} bytes before, ${stat.size} now`,
+            });
+            continue;
+        }
+        if (entry.sha256 === undefined) {
+            mismatched.push({
+                rel: entry.rel,
+                problem: "unreadable",
+                detail: "no hash was recorded for this file, so its contents cannot be verified",
+            });
+            continue;
+        }
+        let digest;
+        try {
+            digest = createHash("sha256").update(readFileSync(abs)).digest("hex");
+        }
+        catch (err) {
+            mismatched.push({
+                rel: entry.rel,
+                problem: "unreadable",
+                detail: `could not be read at the destination (${err.code ?? "unknown error"})`,
+            });
+            continue;
+        }
+        if (digest !== entry.sha256) {
+            mismatched.push({ rel: entry.rel, problem: "sha256", detail: "contents differ" });
+            continue;
+        }
+        verified += 1;
+    }
+    return {
+        checked: manifest.length,
+        verified,
+        mismatched,
+        ok: manifestComplete && mismatched.length === 0,
+    };
+}
+/** sha256 of one file, or the reason it could not be hashed. */
+export function hashFile(abs) {
+    try {
+        return { ok: true, value: createHash("sha256").update(readFileSync(abs)).digest("hex") };
+    }
+    catch (err) {
+        const code = err.code;
+        return code === "ENOENT"
+            ? fail("missing", "file does not exist")
+            : fail("unreadable", `file could not be read (${code ?? "unknown error"})`);
+    }
+}

package/dist/paths.d.ts

@@ -0,0 +1,42 @@
+import { CrewhausError } from "@crewhaus/errors";
+/** Raised when a caller-supplied path resolves outside the workspace root. */
+export declare class ToolPermissionError extends CrewhausError {
+    readonly name = "ToolPermissionError";
+    readonly toolName: string;
+    readonly path: string;
+    constructor(toolName: string, attemptedPath: string);
+}
+/**
+ * A validated path, in both forms the tools need.
+ *
+ * `real` has every in-workspace symlink already resolved and is what I/O
+ * should use — operating on it closes most of the check-to-use window.
+ * `abs` is the lexical resolution, which is what a tool must use when the
+ * question is about the link ITSELF (`Stat` reporting a symlink target,
+ * `RemovePath` deleting a link rather than its destination).
+ */
+export type SafePath = {
+    readonly abs: string;
+    readonly real: string;
+    /** The path as the caller wrote it, for echoing back in results. */
+    readonly given: string;
+    /** Slash-separated path relative to the workspace root. */
+    readonly rel: string;
+};
+/** The workspace root, resolved. Every path is contained within it. */
+export declare function workspaceRoot(): string;
+export declare function resolveSafe(toolName: string, rel: string, root?: string): SafePath;
+/** A path relative to the workspace root, with `/` separators on every OS. */
+export declare function toPosix(p: string): string;
+/**
+ * True when `candidate` is `parent` or lives underneath it. Both must already
+ * be absolute. Used to keep an archive entry, or a symlink inside an
+ * extracted tree, from reaching outside its destination.
+ */
+export declare function isInside(parent: string, candidate: string): boolean;
+/**
+ * Reject an archive member name that would escape its destination: an
+ * absolute path, a Windows drive prefix, or any `..` segment. Checked on the
+ * NAME, before extraction, because after extraction the damage is done.
+ */
+export declare function archiveEntryEscapes(name: string): boolean;

package/dist/paths.js

@@ -0,0 +1,158 @@
+/**
+ * Path containment — the gate every caller-supplied path in this package
+ * passes through before any syscall touches it.
+ *
+ * The approach is the one `@crewhaus/tool-fs` uses, and for the same reasons:
+ * a lexical check alone is fooled by a symlink that lives inside the
+ * workspace and points outside it (CWE-59), so the real path is checked too.
+ * The workspace root is `process.cwd()`, matching tool-fs, so a harness that
+ * trusts one tool's boundary gets the same boundary here.
+ */
+import { lstatSync, readlinkSync, realpathSync } from "node:fs";
+import * as path from "node:path";
+import { CrewhausError } from "@crewhaus/errors";
+/** Raised when a caller-supplied path resolves outside the workspace root. */
+export class ToolPermissionError extends CrewhausError {
+    name = "ToolPermissionError";
+    toolName;
+    path;
+    constructor(toolName, attemptedPath) {
+        super("tool", `tool "${toolName}" rejected path "${attemptedPath}": resolved location escapes the workspace root`);
+        this.toolName = toolName;
+        this.path = attemptedPath;
+    }
+}
+/** The workspace root, resolved. Every path is contained within it. */
+export function workspaceRoot() {
+    return path.resolve(process.cwd());
+}
+/**
+ * Resolve `rel` inside the workspace, or throw `ToolPermissionError`.
+ *
+ * The leaf is allowed not to exist — every tool here that creates something
+ * needs to validate a destination before it is made — so the deepest
+ * EXISTING ancestor is realpath'd and the missing tail re-appended. Any
+ * failure other than that walk fails closed.
+ */
+/**
+ * True when the NAME exists, whether or not it leads anywhere.
+ *
+ * `existsSync` FOLLOWS symlinks, so it answers false for a link whose target
+ * is missing — and that is exactly the case that matters: a dangling link is
+ * still a door, because `open(…, "w")` through `evil -> /outside/x` CREATES
+ * `/outside/x`. Probing with `lstat` keeps the link's name in the part of the
+ * path that gets resolved, rather than in the "does not exist yet" tail that
+ * is re-appended to the root verbatim and so passes the containment check.
+ */
+function nameExists(p) {
+    try {
+        lstatSync(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Where `target` would actually land, with every symlink on the way already
+ * followed — including one whose own target does not exist yet.
+ *
+ * `realpathSync` gives up with ENOENT on a dangling link, which would leave
+ * that link unresolved and let it stand in for a plain missing file. So the
+ * deepest ancestor that exists as a NAME is resolved, a dangling one is
+ * followed a hop by hand, and the components that do not exist are appended.
+ * The result is the path an `open` would create, which is the only path worth
+ * checking containment against.
+ */
+function resolveLocation(target, depth = 0) {
+    if (depth > 40)
+        throw new Error(`symlink chain at "${target}" is too long to resolve`);
+    let probe = target;
+    const tail = [];
+    while (!nameExists(probe)) {
+        tail.unshift(path.basename(probe));
+        const parent = path.dirname(probe);
+        if (parent === probe)
+            break; // reached the filesystem root
+        probe = parent;
+    }
+    let probeReal;
+    try {
+        probeReal = realpathSync(probe);
+    }
+    catch (err) {
+        if (err.code !== "ENOENT")
+            throw err;
+        // The name is there but `realpath` cannot finish it: a symlink with a
+        // missing target. `readlinkSync` throws EINVAL on anything else, which
+        // fails closed.
+        const link = readlinkSync(probe);
+        // A RELATIVE target resolves against the directory that actually CONTAINS
+        // the link, which is not the link's lexical parent when that parent is
+        // itself reached through a symlink. `<root>/dirlink/x -> ../y` with
+        // `dirlink` pointing out of the root really lands at `<elsewhere>/y`, but
+        // measured from the lexical parent it reads as `<root>/y` — an in-root
+        // path the caller's path does not lead to. So the parent is made real
+        // first. An absolute target ignores the base.
+        const base = realpathSync(path.dirname(probe));
+        probeReal = resolveLocation(path.resolve(base, link), depth + 1);
+    }
+    return tail.length > 0 ? path.join(probeReal, ...tail) : probeReal;
+}
+export function resolveSafe(toolName, rel, root = workspaceRoot()) {
+    const rootResolved = path.resolve(root);
+    const abs = path.resolve(rootResolved, rel);
+    // 1) Lexical containment — rejects `..` and absolute escapes. The trailing
+    //    separator avoids the `/root` vs `/root-sibling` prefix pitfall.
+    if (abs !== rootResolved && !abs.startsWith(`${rootResolved}${path.sep}`)) {
+        throw new ToolPermissionError(toolName, rel);
+    }
+    let real;
+    try {
+        const rootReal = realpathSync(rootResolved);
+        real = resolveLocation(abs);
+        // 2) Symlink-aware containment. The real path must land inside the real
+        //    root, so an in-workspace symlink pointing at /etc is refused here.
+        if (real !== rootReal && !real.startsWith(`${rootReal}${path.sep}`)) {
+            throw new ToolPermissionError(toolName, rel);
+        }
+    }
+    catch (err) {
+        if (err instanceof ToolPermissionError)
+            throw err;
+        throw new ToolPermissionError(toolName, rel);
+    }
+    return {
+        abs,
+        real,
+        given: rel,
+        rel: toPosix(path.relative(rootResolved, abs)),
+    };
+}
+/** A path relative to the workspace root, with `/` separators on every OS. */
+export function toPosix(p) {
+    return path.sep === "/" ? p : p.split(path.sep).join("/");
+}
+/**
+ * True when `candidate` is `parent` or lives underneath it. Both must already
+ * be absolute. Used to keep an archive entry, or a symlink inside an
+ * extracted tree, from reaching outside its destination.
+ */
+export function isInside(parent, candidate) {
+    const p = path.resolve(parent);
+    const c = path.resolve(candidate);
+    return c === p || c.startsWith(`${p}${path.sep}`);
+}
+/**
+ * Reject an archive member name that would escape its destination: an
+ * absolute path, a Windows drive prefix, or any `..` segment. Checked on the
+ * NAME, before extraction, because after extraction the damage is done.
+ */
+export function archiveEntryEscapes(name) {
+    const normalized = name.replace(/\\/g, "/");
+    if (normalized.startsWith("/"))
+        return true;
+    if (/^[A-Za-z]:/.test(normalized))
+        return true;
+    return normalized.split("/").some((segment) => segment === "..");
+}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@crewhaus/tool-lifecycle",
+  "version": "0.7.0",
+  "type": "module",
+  "description": "Deterministic harness lifecycle: retirement, store migration, retention enforcement and knowledge sync",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "test": "bun test src"
+  },
+  "dependencies": {
+    "@crewhaus/errors": "0.7.0",
+    "@crewhaus/harness-lifecycle": "0.7.0",
+    "@crewhaus/tool-builder": "0.7.0",
+    "@crewhaus/tool-catalog": "0.7.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@crewhaus/tool-executor": "workspace:*"
+  },
+  "license": "Apache-2.0",
+  "author": {
+    "name": "Max Meier",
+    "email": "max@crewhaus.ai",
+    "url": "https://crewhaus.ai"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/crewhaus/factory.git",
+    "directory": "packages/tool-lifecycle"
+  },
+  "homepage": "https://github.com/crewhaus/factory/tree/main/packages/tool-lifecycle#readme",
+  "bugs": {
+    "url": "https://github.com/crewhaus/factory/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": ["dist", "README.md", "LICENSE", "NOTICE"]
+}