@crewhaus/tool-lifecycle 0.7.0

package/dist/lib/retire.d.ts

@@ -0,0 +1,92 @@
+import type { RetirementSteps, StepOutcome } from "@crewhaus/harness-lifecycle";
+import type { Tree } from "./tree";
+/** Where a harness keeps its durable state, by convention. */
+export declare const STATE_RELDIR = ".crewhaus";
+/**
+ * Where `@crewhaus/harness-lifecycle` moves the live state dir inside the
+ * archive. The package does not export this name, so it is mirrored here —
+ * and asserted at run time rather than trusted: if the archived tree is not
+ * found at this path the tool reports that it could not verify the archive,
+ * never that it verified one. `index.test.ts` pins the coupling so a rename
+ * upstream fails a test here instead of silently skipping verification.
+ */
+export declare const ARCHIVED_STATE_DIRNAME = "crewhaus-state";
+/** The manifest this tool writes into the archive before anything moves. */
+export declare const STATE_MANIFEST_FILENAME = "state-manifest.json";
+/** Default registry root, matching `@crewhaus/spec-registry`'s file backend. */
+export declare const DEFAULT_REGISTRY_RELDIR = ".crewhaus/specs";
+export declare const AUDIT_VERIFY_UNAVAILABLE: string;
+export declare const COMPLIANCE_EVIDENCE_UNAVAILABLE: string;
+/**
+ * What is known about a spec's registry entry.
+ *
+ * `unknown` exists because the alternative is unthinkable: a manifest that
+ * could not be parsed, reported as "no pins", retires a harness that an
+ * environment is still pointing at. An unreadable manifest and an absent one
+ * are different answers and are kept different all the way to the result.
+ */
+export type PinState = {
+    readonly state: "absent";
+} | {
+    readonly state: "known";
+    readonly pins: Record<string, string>;
+    readonly versions: ReadonlyArray<string>;
+} | {
+    readonly state: "unknown";
+    readonly reason: string;
+};
+/** A spec name is a directory component: never a path, never a traversal. */
+export declare function specNameIsSafe(name: string): boolean;
+/**
+ * Read `<registryDir>/<spec>/manifest.json` — the file-backed
+ * `@crewhaus/spec-registry` layout (`{ versions: [...], pins: { env: version } }`).
+ *
+ * Only the FILE is read here; the rule that active pins block a retirement
+ * belongs to `buildRetirementPlan` in `@crewhaus/harness-lifecycle` and is
+ * not restated. Anything that is not a well-formed manifest resolves to
+ * `unknown`, never to an empty pin set.
+ */
+export declare function readRegistryPins(registryDirAbs: string, spec: string): PinState;
+export type StateManifest = {
+    readonly writtenAt: string;
+    readonly harnessDir: string;
+    readonly fileCount: number;
+    readonly totalBytes: number;
+    readonly complete: boolean;
+    readonly unreadable: Tree["unreadable"];
+    readonly entries: Tree["entries"];
+};
+export type BuildStepsOptions = {
+    /** The fingerprint of `.crewhaus` taken BEFORE anything moves. */
+    readonly stateTree: Tree | undefined;
+    readonly harnessDir: string;
+    readonly pinState: PinState;
+    readonly now: () => Date;
+};
+/**
+ * The `RetirementSteps` this build can honestly supply.
+ *
+ * `backupState` does not make a second copy of the state: the package's own
+ * archive step MOVES the live directory into the archive, so a copy beside it
+ * would double the bytes and prove nothing. What it writes instead is the
+ * per-file sha256 manifest taken before the move, which is what makes the
+ * move checkable afterwards — and it refuses (ok: false, which aborts before
+ * anything is destroyed) when that fingerprint is incomplete.
+ */
+export declare function buildRetireSteps(opts: BuildStepsOptions): RetirementSteps;
+/**
+ * Wrap a step set so every outcome is kept.
+ *
+ * `runRetirement` THROWS on the step that fails, and the retirement log it
+ * writes into the archive only exists for the abort paths that get that far —
+ * so a caller of the tool would otherwise be told "the tombstone failed" with
+ * no record of the three steps that succeeded before it. Recording here means
+ * a refused retirement reports the same per-step outcomes a completed one
+ * does, which is what makes it possible to tell how far it got.
+ */
+export declare function recordSteps(steps: RetirementSteps): {
+    readonly steps: RetirementSteps;
+    readonly recorded: StepOutcome[];
+};
+/** Read back a state manifest written by `backupState`. */
+export declare function readStateManifest(archiveDir: string): StateManifest | undefined;

package/dist/lib/retire.js

@@ -0,0 +1,269 @@
+/**
+ * `HarnessRetire`'s half of the retirement: the facts the tool must establish
+ * before `@crewhaus/harness-lifecycle` is allowed to move anything, and the
+ * `RetirementSteps` seam the package asks its host to supply.
+ *
+ * The package owns the orchestration — the order of the steps, the refusal on
+ * an active deployment pin, the abort-before-destruction gate, and the
+ * `retirement.json` written into the archive. None of that is re-decided
+ * here. What lives here is what a HOST has to answer: where are the pins,
+ * what can this build actually do, and did the bytes arrive.
+ *
+ * WHAT THIS BUILD CANNOT DO, AND SAYS SO. Three of the five steps the CLI
+ * wires need packages `@crewhaus/tool-lifecycle` does not depend on. Rather
+ * than reporting them as successes (a step that returns `ok: true` for work
+ * nobody did is the exact "could not determine reported as fine" failure this
+ * repository keeps paying for), they return `ok: false` with the reason. The
+ * package then aborts before the destructive move, which is the correct
+ * outcome: the audit chain has not been verified, so nothing should be moved
+ * on the strength of it.
+ */
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import * as path from "node:path";
+import { renderPath } from "./result";
+/** Where a harness keeps its durable state, by convention. */
+export const STATE_RELDIR = ".crewhaus";
+/**
+ * Where `@crewhaus/harness-lifecycle` moves the live state dir inside the
+ * archive. The package does not export this name, so it is mirrored here —
+ * and asserted at run time rather than trusted: if the archived tree is not
+ * found at this path the tool reports that it could not verify the archive,
+ * never that it verified one. `index.test.ts` pins the coupling so a rename
+ * upstream fails a test here instead of silently skipping verification.
+ */
+export const ARCHIVED_STATE_DIRNAME = "crewhaus-state";
+/** The manifest this tool writes into the archive before anything moves. */
+export const STATE_MANIFEST_FILENAME = "state-manifest.json";
+/** Default registry root, matching `@crewhaus/spec-registry`'s file backend. */
+export const DEFAULT_REGISTRY_RELDIR = ".crewhaus/specs";
+export const AUDIT_VERIFY_UNAVAILABLE = "not performed — @crewhaus/audit-log is not a dependency of @crewhaus/tool-lifecycle, so this " +
+    "tool cannot verify the harness's audit chain. Run the AuditVerify tool (@crewhaus/tool-crewhaus) " +
+    "against the same directory first; it walks the real chain.";
+export const COMPLIANCE_EVIDENCE_UNAVAILABLE = "not performed — @crewhaus/compliance-controls is not a dependency of @crewhaus/tool-lifecycle, " +
+    "so no final compliance-evidence bundle was collected. Collect it with the CLI " +
+    "(`crewhaus compliance evidence`) before retiring if your framework requires one.";
+/** A spec name is a directory component: never a path, never a traversal. */
+export function specNameIsSafe(name) {
+    return (name.length > 0 &&
+        !name.includes("/") &&
+        !name.includes("\\") &&
+        !name.includes("\u0000") &&
+        name !== "." &&
+        name !== ".." &&
+        !name.split(/[/\\]/).includes(".."));
+}
+/**
+ * Read `<registryDir>/<spec>/manifest.json` — the file-backed
+ * `@crewhaus/spec-registry` layout (`{ versions: [...], pins: { env: version } }`).
+ *
+ * Only the FILE is read here; the rule that active pins block a retirement
+ * belongs to `buildRetirementPlan` in `@crewhaus/harness-lifecycle` and is
+ * not restated. Anything that is not a well-formed manifest resolves to
+ * `unknown`, never to an empty pin set.
+ */
+export function readRegistryPins(registryDirAbs, spec) {
+    const manifestPath = path.join(registryDirAbs, spec, "manifest.json");
+    let raw;
+    try {
+        raw = readFileSync(manifestPath, "utf8");
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "ENOENT")
+            return { state: "absent" };
+        return {
+            state: "unknown",
+            reason: `the registry manifest for "${renderPath(spec)}" could not be read (${code ?? "unknown error"})`,
+        };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        return {
+            state: "unknown",
+            reason: `the registry manifest for "${renderPath(spec)}" is not valid JSON (${err.message})`,
+        };
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        return {
+            state: "unknown",
+            reason: `the registry manifest for "${renderPath(spec)}" is not a JSON object`,
+        };
+    }
+    const record = parsed;
+    const rawPins = record["pins"];
+    const rawVersions = record["versions"];
+    const pins = {};
+    if (rawPins !== undefined) {
+        if (typeof rawPins !== "object" || rawPins === null || Array.isArray(rawPins)) {
+            return {
+                state: "unknown",
+                reason: `the registry manifest for "${renderPath(spec)}" has a "pins" field that is not an object`,
+            };
+        }
+        for (const [env, version] of Object.entries(rawPins)) {
+            if (typeof version !== "string") {
+                return {
+                    state: "unknown",
+                    reason: `the registry manifest for "${renderPath(spec)}" pins "${renderPath(env)}" to something that is not a version string`,
+                };
+            }
+            pins[env] = version;
+        }
+    }
+    let versions = [];
+    if (rawVersions !== undefined) {
+        if (!Array.isArray(rawVersions) || rawVersions.some((v) => typeof v !== "string")) {
+            return {
+                state: "unknown",
+                reason: `the registry manifest for "${renderPath(spec)}" has a "versions" field that is not an array of strings`,
+            };
+        }
+        versions = [...rawVersions].sort();
+    }
+    return { state: "known", pins, versions };
+}
+/**
+ * The `RetirementSteps` this build can honestly supply.
+ *
+ * `backupState` does not make a second copy of the state: the package's own
+ * archive step MOVES the live directory into the archive, so a copy beside it
+ * would double the bytes and prove nothing. What it writes instead is the
+ * per-file sha256 manifest taken before the move, which is what makes the
+ * move checkable afterwards — and it refuses (ok: false, which aborts before
+ * anything is destroyed) when that fingerprint is incomplete.
+ */
+export function buildRetireSteps(opts) {
+    return {
+        async backupState(archiveDir) {
+            const tree = opts.stateTree;
+            if (tree === undefined) {
+                return {
+                    step: "backupState",
+                    ok: true,
+                    detail: `no ${STATE_RELDIR} directory under ${renderPath(opts.harnessDir)} — nothing to fingerprint`,
+                };
+            }
+            if (!tree.complete) {
+                return {
+                    step: "backupState",
+                    ok: false,
+                    detail: `${tree.unreadable.length} entry(ies) under ${STATE_RELDIR} could not be read, so the archive could not be fingerprinted: ${tree.unreadable
+                        .slice(0, 3)
+                        .map((u) => `${u.rel} (${u.reason})`)
+                        .join("; ")}`,
+                };
+            }
+            const manifest = {
+                writtenAt: opts.now().toISOString(),
+                harnessDir: opts.harnessDir,
+                fileCount: tree.fileCount,
+                totalBytes: tree.totalBytes,
+                complete: tree.complete,
+                unreadable: tree.unreadable,
+                entries: tree.entries,
+            };
+            const manifestPath = path.join(archiveDir, STATE_MANIFEST_FILENAME);
+            try {
+                writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`, { mode: 0o600 });
+            }
+            catch (err) {
+                return {
+                    step: "backupState",
+                    ok: false,
+                    detail: `the state manifest could not be written to the archive: ${err.message}`,
+                };
+            }
+            return {
+                step: "backupState",
+                ok: true,
+                detail: `fingerprinted ${tree.fileCount} file(s), ${tree.totalBytes} byte(s) → ${STATE_MANIFEST_FILENAME}`,
+                tarball: manifestPath,
+            };
+        },
+        async complianceEvidence() {
+            return { step: "complianceEvidence", ok: false, detail: COMPLIANCE_EVIDENCE_UNAVAILABLE };
+        },
+        async auditVerify() {
+            return { step: "auditVerify", ok: false, detail: AUDIT_VERIFY_UNAVAILABLE };
+        },
+        async pushKnowledge() {
+            // Never planned by this tool: knowledge sharing is the KnowledgeSync
+            // tool's job, and doing it here would push a harness's memories on the
+            // way out of a call whose subject is deletion.
+            return {
+                step: "pushKnowledge",
+                ok: true,
+                detail: "skipped — run the KnowledgeSync tool before retiring if the lessons should outlive the harness",
+            };
+        },
+        async tombstoneRegistry() {
+            const pin = opts.pinState;
+            if (pin.state === "absent") {
+                // True, and the only case this build can honestly report as done:
+                // there is no registry entry, so there is nothing to tombstone.
+                return {
+                    step: "tombstoneRegistry",
+                    ok: true,
+                    detail: "no registry entry for this spec — nothing to tombstone",
+                };
+            }
+            if (pin.state === "unknown") {
+                return { step: "tombstoneRegistry", ok: false, detail: pin.reason };
+            }
+            if (pin.versions.length === 0 && Object.keys(pin.pins).length === 0) {
+                return {
+                    step: "tombstoneRegistry",
+                    ok: true,
+                    detail: "the registry entry holds no versions and no pins — nothing to tombstone",
+                };
+            }
+            return {
+                step: "tombstoneRegistry",
+                ok: false,
+                detail: `${pin.versions.length} registered version(s) and ${Object.keys(pin.pins).length} pin(s) remain, and @crewhaus/spec-registry is not a dependency of @crewhaus/tool-lifecycle, so this tool cannot delete them. Remove them first (crewhaus registry delete), then retire — retiring now would leave a registry entry pointing at state that no longer exists.`,
+            };
+        },
+    };
+}
+/**
+ * Wrap a step set so every outcome is kept.
+ *
+ * `runRetirement` THROWS on the step that fails, and the retirement log it
+ * writes into the archive only exists for the abort paths that get that far —
+ * so a caller of the tool would otherwise be told "the tombstone failed" with
+ * no record of the three steps that succeeded before it. Recording here means
+ * a refused retirement reports the same per-step outcomes a completed one
+ * does, which is what makes it possible to tell how far it got.
+ */
+export function recordSteps(steps) {
+    const recorded = [];
+    const keep = (outcome) => {
+        recorded.push({ step: outcome.step, ok: outcome.ok, detail: outcome.detail });
+        return outcome;
+    };
+    return {
+        recorded,
+        steps: {
+            backupState: async (archiveDir) => keep(await steps.backupState(archiveDir)),
+            complianceEvidence: async (archiveDir) => keep(await steps.complianceEvidence(archiveDir)),
+            auditVerify: async () => keep(await steps.auditVerify()),
+            pushKnowledge: async (archiveDir) => keep(await steps.pushKnowledge(archiveDir)),
+            tombstoneRegistry: async () => keep(await steps.tombstoneRegistry()),
+        },
+    };
+}
+/** Read back a state manifest written by `backupState`. */
+export function readStateManifest(archiveDir) {
+    const p = path.join(archiveDir, STATE_MANIFEST_FILENAME);
+    if (!existsSync(p))
+        return undefined;
+    try {
+        return JSON.parse(readFileSync(p, "utf8"));
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/lib/tree.d.ts

@@ -0,0 +1,74 @@
+import { type Loaded } from "./result";
+export type TreeEntry = {
+    /** Path relative to the walk root, with `/` separators on every OS. */
+    readonly rel: string;
+    readonly kind: "file" | "symlink" | "other";
+    readonly bytes: number;
+    /** sha256 of the file's bytes. Absent for a symlink or an unhashed entry. */
+    readonly sha256?: string;
+    /** A symlink's target, verbatim. */
+    readonly target?: string;
+};
+export type TreeUnreadable = {
+    readonly rel: string;
+    readonly reason: string;
+};
+export type Tree = {
+    readonly root: string;
+    readonly entries: ReadonlyArray<TreeEntry>;
+    readonly fileCount: number;
+    readonly totalBytes: number;
+    /** Oldest / newest mtime seen, epoch ms. Absent for an empty tree. */
+    readonly oldestMtimeMs?: number;
+    readonly newestMtimeMs?: number;
+    /** Entries that could not be read, with the reason each one failed. */
+    readonly unreadable: ReadonlyArray<TreeUnreadable>;
+    /**
+     * True only when every entry under the root was visited AND (when hashing
+     * was requested) hashed. False the moment anything was skipped, refused or
+     * truncated — the caller must not treat such a tree as a verified one.
+     */
+    readonly complete: boolean;
+};
+export type WalkOptions = {
+    readonly maxFiles: number;
+    readonly maxBytes: number;
+    /** Compute sha256 per file. Off for a cheap inventory. */
+    readonly hash: boolean;
+};
+/**
+ * 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 declare function walkTree(root: string, opts: WalkOptions): Loaded<Tree>;
+export type VerifyMismatch = {
+    readonly rel: string;
+    readonly problem: "missing" | "size" | "sha256" | "unreadable" | "kind";
+    readonly detail: string;
+};
+export type VerifyResult = {
+    readonly checked: number;
+    readonly verified: number;
+    readonly mismatched: ReadonlyArray<VerifyMismatch>;
+    /**
+     * True only when every entry of the manifest was found and matched. A
+     * manifest that was itself incomplete can never verify, because the
+     * entries it is missing are exactly the ones nothing is being checked
+     * against.
+     */
+    readonly ok: boolean;
+};
+/**
+ * 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 declare function verifyAgainst(destRoot: string, manifest: ReadonlyArray<TreeEntry>, manifestComplete?: boolean): VerifyResult;
+/** sha256 of one file, or the reason it could not be hashed. */
+export declare function hashFile(abs: string): Loaded<string>;