javi-forge 1.29.0 → 1.30.1

package/dist/lib/__fixtures__/fake-secure-fs.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Synchronous in-memory `PlatformSecureFs` fake for the transaction engine's
+ * fault matrix. Host-independent, no root, no real filesystem: directories,
+ * files, modes, and dev+ino identities live in Maps, and every failure branch
+ * (identity drift, ACL refusal, exclusive-create EEXIST, write/fsync fault,
+ * rename fault, ownership loss, capture refusal, post-commit hash drift) is a
+ * declarative toggle. Used only by tests.
+ */
+import type { PlatformSecureFs } from "../secure-fs-transaction.js";
+interface FakeFile {
+    bytes: Buffer;
+    mode: number;
+}
+/** Per-call fault predicates; every one defaults to "no fault". */
+export interface FakeFaults {
+    /** Refuse revalidateIdentity for a path on its Nth (1-based) call. */
+    revalidateRefuse?: (target: string, callIndex: number) => boolean;
+    /** Refuse proveOwnershipAndMode for a path on its Nth call. */
+    ownershipRefuse?: (dirPath: string, callIndex: number) => boolean;
+    /** Refuse proveNoExtendedAcl for a path on its Nth call. */
+    aclRefuse?: (target: string, callIndex: number) => boolean;
+    /** Refuse captureFile for a path (simulate open/read failure). */
+    captureRefuse?: (target: string) => boolean;
+    /** Override the sha of a captured file (simulate post-commit drift). */
+    captureShaOverride?: (target: string) => string | undefined;
+    /** Refuse writeExclusive for a base name on its Nth call (EEXIST / fsync fault). */
+    writeRefuse?: (name: string, callIndex: number) => boolean;
+    /** Refuse renameInDir when the destination base name matches. */
+    renameRefuse?: (to: string) => boolean;
+}
+export interface FakeSecureFs extends PlatformSecureFs {
+    readonly dirs: Set<string>;
+    readonly files: Map<string, FakeFile>;
+    readonly dirModes: Map<string, number>;
+    faults: FakeFaults;
+    seedDir(dirPath: string): void;
+    seedFile(filePath: string, bytes: Buffer, mode?: number): void;
+    fileText(filePath: string): string | undefined;
+    hasBackup(dirPath: string): boolean;
+}
+export declare function makeFakeSecureFs(): FakeSecureFs;
+export {};
+//# sourceMappingURL=fake-secure-fs.d.ts.map

package/dist/lib/__fixtures__/fake-secure-fs.js

@@ -0,0 +1,183 @@
+/**
+ * Synchronous in-memory `PlatformSecureFs` fake for the transaction engine's
+ * fault matrix. Host-independent, no root, no real filesystem: directories,
+ * files, modes, and dev+ino identities live in Maps, and every failure branch
+ * (identity drift, ACL refusal, exclusive-create EEXIST, write/fsync fault,
+ * rename fault, ownership loss, capture refusal, post-commit hash drift) is a
+ * declarative toggle. Used only by tests.
+ */
+import { createHash } from "node:crypto";
+import path from "node:path";
+const ok = () => ({ ok: true });
+const okValue = (value) => ({ ok: true, value });
+const unsafe = (detail) => ({
+    ok: false,
+    refusal: "unsafe-parent-chain",
+    detail,
+});
+export function makeFakeSecureFs() {
+    const dirs = new Set();
+    const files = new Map();
+    const dirModes = new Map();
+    const inos = new Map();
+    let inoSeq = 100;
+    const revalidateCounts = new Map();
+    const ownershipCounts = new Map();
+    const aclCounts = new Map();
+    const writeCounts = new Map();
+    const inoFor = (p) => {
+        let ino = inos.get(p);
+        if (ino === undefined) {
+            ino = inoSeq++;
+            inos.set(p, ino);
+        }
+        return ino;
+    };
+    const bump = (m, key) => {
+        const next = (m.get(key) ?? 0) + 1;
+        m.set(key, next);
+        return next;
+    };
+    const handleFor = (p) => ({
+        path: p,
+        identity: { dev: 1, ino: inoFor(p) },
+        close: async () => { },
+    });
+    const isEmptyDir = (p) => {
+        const prefix = `${p}/`;
+        for (const f of files.keys())
+            if (f.startsWith(prefix))
+                return false;
+        for (const d of dirs)
+            if (d !== p && d.startsWith(prefix))
+                return false;
+        return true;
+    };
+    const fake = {
+        dirs,
+        files,
+        dirModes,
+        faults: {},
+        seedDir(dirPath) {
+            dirs.add(dirPath);
+        },
+        seedFile(filePath, bytes, mode = 0o644) {
+            files.set(filePath, { bytes, mode });
+        },
+        fileText(filePath) {
+            return files.get(filePath)?.bytes.toString("utf8");
+        },
+        hasBackup(dirPath) {
+            const prefix = `${dirPath}/`;
+            for (const f of files.keys()) {
+                if (f.startsWith(prefix) && f.includes(".javi-forge.bak."))
+                    return true;
+            }
+            return false;
+        },
+        async openDirNoFollow(dirPath) {
+            if (!dirs.has(dirPath))
+                return unsafe(`openDir enoent ${dirPath}`);
+            return okValue(handleFor(dirPath));
+        },
+        async revalidateIdentity(target, held) {
+            const idx = bump(revalidateCounts, target);
+            if (fake.faults.revalidateRefuse?.(target, idx)) {
+                return unsafe(`identity drift ${target}`);
+            }
+            if (!dirs.has(target) && !files.has(target)) {
+                return unsafe(`identity missing ${target}`);
+            }
+            return inoFor(target) === held.ino
+                ? ok()
+                : unsafe(`identity drift ${target}`);
+        },
+        async proveOwnershipAndMode(dirPath) {
+            const idx = bump(ownershipCounts, dirPath);
+            if (fake.faults.ownershipRefuse?.(dirPath, idx)) {
+                return unsafe(`ownership ${dirPath}`);
+            }
+            return ok();
+        },
+        async proveNoExtendedAcl(target) {
+            const idx = bump(aclCounts, target);
+            if (fake.faults.aclRefuse?.(target, idx)) {
+                return { ok: false, refusal: "unsupported-posix-acl", detail: target };
+            }
+            return ok();
+        },
+        async createDirExclusive(parent, name, mode) {
+            const full = path.join(parent.path, name);
+            if (dirs.has(full) || files.has(full))
+                return unsafe(`EEXIST ${full}`);
+            dirs.add(full);
+            dirModes.set(full, mode);
+            return okValue(handleFor(full));
+        },
+        async captureFile(target) {
+            if (fake.faults.captureRefuse?.(target))
+                return unsafe(`capture ${target}`);
+            const file = files.get(target);
+            if (!file)
+                return unsafe(`capture enoent ${target}`);
+            const realSha = createHash("sha256").update(file.bytes).digest("hex");
+            const sha256 = fake.faults.captureShaOverride?.(target) ?? realSha;
+            return okValue({
+                bytes: file.bytes,
+                mode: file.mode,
+                identity: { dev: 1, ino: inoFor(target) },
+                sha256,
+            });
+        },
+        async writeExclusive(dir, name, bytes, mode) {
+            const idx = bump(writeCounts, name);
+            if (fake.faults.writeRefuse?.(name, idx))
+                return unsafe(`write ${name}`);
+            const full = path.join(dir.path, name);
+            if (files.has(full))
+                return unsafe(`EEXIST ${full}`);
+            files.set(full, { bytes, mode });
+            return ok();
+        },
+        async applyExactMode(target, mode) {
+            const file = files.get(target);
+            if (!file)
+                return unsafe(`applyMode enoent ${target}`);
+            file.mode = mode;
+            return ok();
+        },
+        async renameInDir(dir, from, to) {
+            if (fake.faults.renameRefuse?.(to))
+                return unsafe(`rename ${to}`);
+            const fromP = path.join(dir.path, from);
+            const toP = path.join(dir.path, to);
+            const file = files.get(fromP);
+            if (!file)
+                return unsafe(`rename enoent ${fromP}`);
+            files.set(toP, file);
+            files.delete(fromP);
+            inos.delete(toP); // fresh identity for the renamed-in target
+            return ok();
+        },
+        async unlinkIfIdentity(dir, name, _held) {
+            const full = path.join(dir.path, name);
+            if (!files.has(full))
+                return unsafe(`unlink enoent ${full}`);
+            files.delete(full);
+            return ok();
+        },
+        async rmdirIfIdentityEmpty(handle) {
+            if (!dirs.has(handle.path))
+                return unsafe(`rmdir enoent ${handle.path}`);
+            if (inoFor(handle.path) !== handle.identity.ino) {
+                return unsafe(`rmdir identity ${handle.path}`);
+            }
+            if (!isEmptyDir(handle.path))
+                return unsafe(`rmdir not-empty ${handle.path}`);
+            dirs.delete(handle.path);
+            return ok();
+        },
+    };
+    return fake;
+}
+//# sourceMappingURL=fake-secure-fs.js.map

package/dist/lib/claude-hook-manager.d.ts

@@ -8,6 +8,7 @@
  * Slice-3 seams — Slice 3 GROWS this file, it does not relocate this code.
  */
 import { type ClaudeHookComponentState, type SettingsClassification, type SettingsIdentityManifest } from "./claude-hook-settings.js";
+import { type PlatformSecureFs } from "./secure-fs-transaction.js";
 declare const COVERAGE: readonly ["Bash", "PowerShell", "Read", "Write", "Edit"];
 export interface AssetManifestEntry {
     name: string;
@@ -78,10 +79,23 @@ export interface ClaudeHookMutationResult {
     ok: boolean;
     changed: string[];
     backups: string[];
+    report: ClaudeHookDoctorReport;
     errors: string[];
 }
-export declare function installClaudePreToolUse(_projectDir: string): Promise<ClaudeHookMutationResult>;
-export declare function repairClaudePreToolUse(_projectDir: string, _options?: {
+/** Injectable deps so tests drive `_run` with a fake `PlatformSecureFs`. */
+export interface ClaudeHookRunDeps {
+    secureFs?: PlatformSecureFs | null;
+    clock?: () => Date;
+    nonce?: () => string;
+    manifest?: Manifest;
+    platform?: NodeJS.Platform;
+}
+/** Internal deps-taking entry; tests drive it with a fake `PlatformSecureFs`. */
+export declare function _run(projectDir: string, mode: "install" | "repair", options: {
+    force?: boolean;
+}, deps: ClaudeHookRunDeps): Promise<ClaudeHookMutationResult>;
+export declare function installClaudePreToolUse(projectDir: string): Promise<ClaudeHookMutationResult>;
+export declare function repairClaudePreToolUse(projectDir: string, options?: {
     force?: boolean;
 }): Promise<ClaudeHookMutationResult>;
 export {};

package/dist/lib/claude-hook-manager.js

@@ -7,13 +7,15 @@
  * and the component-level doctor. Install/repair are declared but unimplemented
  * Slice-3 seams — Slice 3 GROWS this file, it does not relocate this code.
  */
-import { createHash } from "node:crypto";
-import { lstat } from "node:fs/promises";
+import { createHash, randomBytes } from "node:crypto";
+import { lstat, readFile } from "node:fs/promises";
 import path from "node:path";
 import { CLAUDE_HOOK_ASSETS_DIR } from "../constants.js";
 import { ASSET_MANAGED_MARKER, ASSET_NAME, } from "./__fixtures__/claude-hook-ownership.js";
-import { classifySettingsEntry, isPlainObject, LEGACY_FILE_SHA256, MANAGED_ASSET_ARG, MANAGED_MATCHER, MANAGED_STATUS_PREFIX, } from "./claude-hook-settings.js";
+import { buildManagedContainer, classifySettingsEntry, isPlainObject, LEGACY_FILE_SHA256, MANAGED_ASSET_ARG, MANAGED_MATCHER, MANAGED_STATUS_PREFIX, planForceReplace, planLegacyCohortExcision, planManagedClaudeHookMerge, } from "./claude-hook-settings.js";
 import { safeReadFile } from "./safe-read.js";
+import { selectSecureFs } from "./secure-fs-posix.js";
+import { runTransaction, } from "./secure-fs-transaction.js";
 /** 1 MiB read budget, shared with the runtime's stdin envelope. */
 const ASSET_MAX_BYTES = 1024 * 1024;
 const NODE_MINIMUM_MAJOR = 22;
@@ -267,10 +269,222 @@ async function readManifest() {
         throw new Error(`unreadable claude-hooks manifest: ${read.reason}`);
     return JSON.parse(read.content);
 }
-export function installClaudePreToolUse(_projectDir) {
-    throw new Error("unimplemented: Slice 3 transaction");
+function refuseMessage(component, state) {
+    const remedy = remediationFor(state, component);
+    return `refuse ${component} in state ${state}${remedy ? ` — ${remedy}` : ""}`;
 }
-export function repairClaudePreToolUse(_projectDir, _options) {
-    throw new Error("unimplemented: Slice 3 transaction");
+function resolveAssetPlan(state, forced) {
+    switch (state) {
+        case "absent":
+        case "released-outdated":
+            return { kind: "write" };
+        case "managed-current":
+            return { kind: "noop" };
+        case "edited-managed":
+            return forced
+                ? { kind: "write" }
+                : { kind: "refuse", reason: refuseMessage("asset", state) };
+        default:
+            return { kind: "refuse", reason: refuseMessage("asset", state) };
+    }
+}
+function resolveSettingsPlan(settingsRead, currentAssetSha, forced, identities) {
+    if ("state" in settingsRead) {
+        const state = settingsRead.classification.state;
+        if (state === "absent" || state === "exact-legacy") {
+            return {
+                kind: "container",
+                container: buildManagedContainer(currentAssetSha),
+            };
+        }
+        return { kind: "refuse", reason: refuseMessage("settings", state) };
+    }
+    const value = settingsRead.value;
+    const merge = planManagedClaudeHookMerge(value, currentAssetSha, identities);
+    if (!merge.refused) {
+        if (merge.action === "install")
+            return { kind: "install" };
+        if (merge.action === "noop")
+            return { kind: "noop" };
+        if (merge.action === "replace") {
+            return {
+                kind: "replace",
+                groupIndex: merge.groupIndex,
+                handlerIndex: merge.handlerIndex,
+            };
+        }
+    }
+    const cls = classifySettingsEntry(value, currentAssetSha, identities);
+    if (cls.state === "exact-legacy") {
+        const plan = planLegacyCohortExcision(value);
+        return plan.refused
+            ? {
+                kind: "refuse",
+                reason: plan.reason ?? refuseMessage("settings", cls.state),
+            }
+            : { kind: "excise", plan };
+    }
+    if (cls.state === "edited-managed") {
+        if (!forced)
+            return { kind: "refuse", reason: refuseMessage("settings", cls.state) };
+        const force = planForceReplace(value, currentAssetSha);
+        if (force.refused) {
+            return {
+                kind: "refuse",
+                reason: force.reason ?? refuseMessage("settings", cls.state),
+            };
+        }
+        return {
+            kind: "replace",
+            groupIndex: force.groupIndex,
+            handlerIndex: force.handlerIndex,
+        };
+    }
+    return { kind: "refuse", reason: refuseMessage("settings", cls.state) };
+}
+function freshManagedGroup(currentAssetSha) {
+    return buildManagedContainer(currentAssetSha).hooks
+        .PreToolUse[0];
+}
+function ensureHooks(container) {
+    if (!isPlainObject(container.hooks))
+        container.hooks = {};
+    const hooks = container.hooks;
+    if (!Array.isArray(hooks.PreToolUse))
+        hooks.PreToolUse = [];
+    return hooks;
+}
+/** Build the desired settings container, preserving unrelated content. */
+function applySettingsPlan(value, plan, currentAssetSha) {
+    if (plan.kind === "container")
+        return plan.container;
+    const container = structuredClone(value);
+    const group = freshManagedGroup(currentAssetSha);
+    const hooks = ensureHooks(container);
+    const pre = hooks.PreToolUse;
+    if (plan.kind === "install") {
+        pre.push(group);
+        return container;
+    }
+    if (plan.kind === "replace") {
+        const g = pre[plan.groupIndex];
+        g.matcher = MANAGED_MATCHER;
+        g.hooks[plan.handlerIndex] = group.hooks[0];
+        return container;
+    }
+    if (plan.kind !== "excise")
+        return container;
+    // excise: remove the proven cohort by descending index, then insert the group.
+    const { removePreIndices, removePostIndices, insertPreAt } = plan.plan;
+    for (const index of [...removePreIndices].sort((a, b) => b - a)) {
+        pre.splice(index, 1);
+    }
+    const post = Array.isArray(hooks.PostToolUse) ? hooks.PostToolUse : [];
+    for (const index of [...removePostIndices].sort((a, b) => b - a)) {
+        post.splice(index, 1);
+    }
+    pre.splice(insertPreAt, 0, group);
+    return container;
+}
+function serializeSettings(container) {
+    return Buffer.from(`${JSON.stringify(container, null, 2)}\n`, "utf8");
+}
+/** Internal deps-taking entry; tests drive it with a fake `PlatformSecureFs`. */
+export async function _run(projectDir, mode, options, deps) {
+    const manifest = deps.manifest ?? (await readManifest());
+    const platform = deps.platform ?? process.platform;
+    const secureFs = deps.secureFs !== undefined ? deps.secureFs : selectSecureFs(platform);
+    const clock = deps.clock ?? (() => new Date());
+    const nonce = deps.nonce ?? (() => randomBytes(4).toString("hex"));
+    const currentAssetSha = manifest.asset.sha256;
+    const assetDestPath = path.join(projectDir, ".claude", "hooks", ASSET_NAME);
+    const settingsPath = path.join(projectDir, ".claude", "settings.json");
+    const assetSrcPath = path.join(CLAUDE_HOOK_ASSETS_DIR, ASSET_NAME);
+    const doctor = () => doctorClaudePreToolUse(projectDir, { manifest });
+    // Windows (or any platform without an adapter) refuses with zero mutation.
+    if (!secureFs) {
+        return {
+            ok: false,
+            changed: [],
+            backups: [],
+            errors: ["windows-secure-object-unavailable"],
+            report: await doctor(),
+        };
+    }
+    // Classify both components with the Slice-2 read layer.
+    const assetCls = await classifyAssetState(assetDestPath, manifest);
+    const settingsRead = await readSettings(settingsPath);
+    const settingsState = ("state" in settingsRead
+        ? settingsRead.classification
+        : classifySettingsEntry(settingsRead.value, currentAssetSha, manifest.settingsEntries)).state;
+    const forced = mode === "repair" && options.force === true;
+    const assetPlan = resolveAssetPlan(assetCls.state, forced);
+    const settingsPlan = resolveSettingsPlan(settingsRead, currentAssetSha, forced, manifest.settingsEntries);
+    // A refusal on either component refuses the whole operation, zero mutation.
+    if (assetPlan.kind === "refuse" || settingsPlan.kind === "refuse") {
+        const reason = assetPlan.kind === "refuse"
+            ? assetPlan.reason
+            : settingsPlan.reason;
+        return {
+            ok: false,
+            changed: [],
+            backups: [],
+            errors: [reason],
+            report: await doctor(),
+        };
+    }
+    // Zero-write idempotent no-op: both components already current.
+    if (assetPlan.kind === "noop" && settingsPlan.kind === "noop") {
+        return {
+            ok: true,
+            changed: [],
+            backups: [],
+            errors: [],
+            report: await doctor(),
+        };
+    }
+    const assetWasAbsent = assetCls.state === "absent";
+    const settingsWasAbsent = "state" in settingsRead && settingsRead.classification.state === "absent";
+    const assetForced = forced && assetCls.state === "edited-managed";
+    const settingsForced = forced && settingsState === "edited-managed";
+    const desiredAsset = assetPlan.kind === "write" ? await readFile(assetSrcPath) : null;
+    const desiredSettings = settingsPlan.kind === "noop"
+        ? null
+        : serializeSettings(applySettingsPlan("value" in settingsRead ? settingsRead.value : undefined, settingsPlan, currentAssetSha));
+    const asset = {
+        path: assetDestPath,
+        desired: desiredAsset,
+        capturePrior: assetPlan.kind === "write" && !assetWasAbsent,
+        forceBackup: assetForced,
+        wasAbsent: assetWasAbsent,
+    };
+    const settings = {
+        path: settingsPath,
+        desired: desiredSettings,
+        capturePrior: settingsPlan.kind !== "noop" && !settingsWasAbsent,
+        forceBackup: settingsForced,
+        wasAbsent: settingsWasAbsent,
+    };
+    const tx = await runTransaction({
+        secureFs,
+        clock,
+        nonce,
+        projectDir,
+        asset,
+        settings,
+    });
+    return {
+        ok: tx.ok,
+        changed: tx.committed,
+        backups: tx.backups,
+        errors: tx.errors,
+        report: await doctor(),
+    };
+}
+export function installClaudePreToolUse(projectDir) {
+    return _run(projectDir, "install", {}, {});
+}
+export function repairClaudePreToolUse(projectDir, options) {
+    return _run(projectDir, "repair", options ?? {}, {});
 }
 //# sourceMappingURL=claude-hook-manager.js.map

package/dist/lib/claude-hook-settings.d.ts

@@ -113,4 +113,76 @@ export interface ManagedMergePlan {
  * preserved), and every other state refuses (edited/force is a Slice-3 concern).
  */
 export declare function planManagedClaudeHookMerge(parsed: unknown, currentAssetSha: string, identities: SettingsIdentityManifest): ManagedMergePlan;
+/** The exact managed handler shape the writer installs. */
+export interface ManagedHandler {
+    type: "command";
+    command: "node";
+    args: [string];
+    timeout: number;
+    statusMessage: string;
+}
+/** The exact managed matcher group the writer installs. */
+export interface ManagedMatcherGroup {
+    matcher: string;
+    hooks: [ManagedHandler];
+}
+/** Cohort-excision plan for embedded exact-legacy. */
+export interface LegacyCohortExcisionPlan {
+    refused: boolean;
+    reason?: string;
+    /** Indices to remove from hooks.PreToolUse (L1..L3 matches), ascending. */
+    removePreIndices: number[];
+    /** Indices to remove from hooks.PostToolUse (L4 match), ascending. */
+    removePostIndices: number[];
+    /** Append position for the freshly built managed PreToolUse group. */
+    insertPreAt: number;
+}
+/**
+ * Plan excision of the proven four-object legacy cohort from an embedded
+ * container. Reuses `LEGACY_COHORT` + `deepStructuralEqual` (the same primitives
+ * `classifyLegacy` uses) and never re-derives the classifier. Returns the exact
+ * ascending object indices to remove per event plus the append position for the
+ * freshly built managed group; every non-cohort sibling is preserved by index.
+ * Only an exact-legacy cohort is eligible — a partial/edited cohort refuses
+ * (the classifier already routes those to `foreign`).
+ */
+export declare function planLegacyCohortExcision(parsed: unknown): LegacyCohortExcisionPlan;
+/**
+ * Force-replace plan for edited-managed. Eligibility keys on MATCHER EXACTNESS
+ * (§324), not unconditionally on sibling count. Exposes matcherExact +
+ * siblingHandlers so the manager can enforce the exact §324 rule.
+ */
+export interface ForceReplacePlan {
+    refused: boolean;
+    /** Set only when matcher edited AND siblingHandlers > 0. */
+    reason?: string;
+    state: ClaudeHookComponentState;
+    groupIndex?: number;
+    handlerIndex?: number;
+    /** True => group matcher === MANAGED_MATCHER. */
+    matcherExact?: boolean;
+    /** Count of unrelated handlers in the group. */
+    siblingHandlers?: number;
+}
+/**
+ * Plan an in-place force replacement of the single marker-proven managed
+ * handler for an `edited-managed` component. Eligibility (§324 / JD-A-001):
+ * - matcherExact === true  → eligible regardless of siblingHandlers.
+ * - matcherExact === false && siblingHandlers === 0 → eligible.
+ * - matcherExact === false && siblingHandlers  >  0 → refused even under force.
+ * A container without exactly one marker-proven handler in a valid matcher
+ * group also refuses.
+ */
+export declare function planForceReplace(parsed: unknown, currentAssetSha: string): ForceReplacePlan;
+/**
+ * Synthesize a fresh managed-only container for the two terminal states with no
+ * parsed value: fresh install (`absent`) and whole-file `exact-legacy`. Takes
+ * only the current asset SHA — not the whole Manifest — so this module never
+ * imports the manager's manifest reader at runtime (JD-A-002).
+ */
+export declare function buildManagedContainer(currentAssetSha: string): {
+    hooks: {
+        PreToolUse: [ManagedMatcherGroup];
+    };
+};
 //# sourceMappingURL=claude-hook-settings.d.ts.map