javi-forge 1.28.1 → 1.30.0

package/assets/claude-hooks/manifest.json

@@ -0,0 +1 @@
+{"schemaVersion":1,"asset":{"name":"javi-forge-skillguard-pre-tool-use.mjs","version":1,"policyVersion":1,"sha256":"78be7e6613c012280b7ad17886462ba166b63ebd031e34565d757b3a0796d7cc","historical":[]},"settingsEntries":{"current":{"version":1,"canonicalSha256":"038c59a91bf8967f6908afed74c465f1e7030254e11e4f8738975d6d708424d4"},"historical":[]},"installerHelpers":{"windowsSecureObject":null}}

package/dist/constants.d.ts

@@ -11,6 +11,8 @@ export declare const WORKFLOWS_DIR: string;
 export declare const CI_LOCAL_DIR: string;
 /** Git hook assets directory (installed by `javi-forge ci init`) */
 export declare const HOOK_ASSETS_DIR: string;
+/** Standalone Claude command-hook assets directory */
+export declare const CLAUDE_HOOK_ASSETS_DIR: string;
 /** Security hooks template directory */
 export declare const SECURITY_HOOKS_DIR: string;
 /** Local AI stack template directory */

package/dist/constants.js

@@ -13,6 +13,8 @@ export const WORKFLOWS_DIR = path.join(FORGE_ROOT, "workflows");
 export const CI_LOCAL_DIR = path.join(FORGE_ROOT, "ci-local");
 /** Git hook assets directory (installed by `javi-forge ci init`) */
 export const HOOK_ASSETS_DIR = path.join(FORGE_ROOT, "assets", "hooks");
+/** Standalone Claude command-hook assets directory */
+export const CLAUDE_HOOK_ASSETS_DIR = path.join(FORGE_ROOT, "assets", "claude-hooks");
 /** Security hooks template directory */
 export const SECURITY_HOOKS_DIR = path.join(TEMPLATES_DIR, "security-hooks");
 /** Local AI stack template directory */

package/dist/lib/__fixtures__/claude-hook-ownership.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Shared frozen ownership fixtures for the SkillGuard Claude PreToolUse guard.
+ *
+ * This module is the single source of truth for the byte/structure-exact
+ * identities the read-only recognition layer (Slice 2) classifies against:
+ *
+ * - the managed settings-entry handler group the Slice-3 writer installs;
+ * - the four v0 legacy cohort objects, copied verbatim from
+ *   `templates/security-hooks/claude-settings-security.json` (never normalized);
+ * - the marker/placeholder/hash constants.
+ *
+ * Everything here is data only (frozen literals plus a couple of pure
+ * builders) so it is deterministic, host-independent, and trivially testable.
+ * The production classifier imports the constants and the legacy cohort from
+ * here; the tests additionally use the one-byte-edited and duplicate variants.
+ */
+/** Exact managed marker prefix on the settings handler's `statusMessage`. */
+export declare const MANAGED_STATUS_PREFIX = "javi-forge-global-pretooluse:v1:sha256:";
+/** Placeholder the canonical hash normalizes the live asset SHA token to. */
+export declare const ASSET_SHA_PLACEHOLDER = "<ASSET_SHA256>";
+/** Whole-file SHA-256 of the retained v0 legacy scaffold template. */
+export declare const LEGACY_FILE_SHA256 = "b4638222ecddc2daac6ec3339596d853a626906bbd1233d789d80a319325c68d";
+/** Exact managed matcher — an exact-name alternative list, never a wildcard. */
+export declare const MANAGED_MATCHER = "Bash|PowerShell|Read|Write|Edit";
+/** Single project-local MJS argument, kept as a literal placeholder path. */
+export declare const MANAGED_ASSET_ARG = "${CLAUDE_PROJECT_DIR}/.claude/hooks/javi-forge-skillguard-pre-tool-use.mjs";
+/** Exact asset filename under `.claude/hooks/`. */
+export declare const ASSET_NAME = "javi-forge-skillguard-pre-tool-use.mjs";
+/** Exact first-line comment marking the managed asset. */
+export declare const ASSET_MANAGED_MARKER = "// javi-forge-managed: claude-pretooluse v1";
+/**
+ * A representative live asset SHA. Used only to build marker `statusMessage`
+ * values in fixtures; the canonical settings identity is invariant under this
+ * value (Decision ②), which the rotation-invariance test proves.
+ */
+export declare const SAMPLE_ASSET_SHA256 = "78be7e6613c012280b7ad17886462ba166b63ebd031e34565d757b3a0796d7cc";
+/** Build the exact marker `statusMessage` for a given live asset SHA. */
+export declare function managedStatusMessage(assetSha?: string): string;
+/** Build the exact managed command handler for a given live asset SHA. */
+export declare function managedHandler(assetSha?: string): {
+    type: string;
+    command: string;
+    args: string[];
+    timeout: number;
+    statusMessage: string;
+};
+/** Build the exact managed matcher group for a given live asset SHA. */
+export declare function managedGroup(assetSha?: string): {
+    matcher: string;
+    hooks: {
+        type: string;
+        command: string;
+        args: string[];
+        timeout: number;
+        statusMessage: string;
+    }[];
+};
+/** Build a valid settings container around the given hook sections. */
+export declare function settingsContainer(pre?: unknown[], post?: unknown[], extra?: Record<string, unknown>): Record<string, unknown>;
+export declare const L1_BASH_DANGEROUS: {
+    readonly matcher: "Bash";
+    readonly hook: "COMMAND=\"$CLAUDE_TOOL_INPUT\"\nBLOCKED_PATTERNS=(\n  'rm -rf /'\n  'rm -rf ~'\n  'chmod 777'\n  'curl.*|.*sh'\n  'wget.*|.*sh'\n  'eval.*\\$'\n  'base64.*-d.*|.*sh'\n  ':(){:|:&};:'\n)\nfor pattern in \"${BLOCKED_PATTERNS[@]}\"; do\n  if echo \"$COMMAND\" | grep -qE \"$pattern\"; then\n    echo \"BLOCKED: Dangerous command pattern detected: $pattern\"\n    exit 2\n  fi\ndone\nexit 0";
+    readonly description: "Block dangerous shell commands (rm -rf /, chmod 777, pipe-to-sh, fork bombs)";
+};
+export declare const L2_BASH_SENSITIVE_READ: {
+    readonly matcher: "Bash";
+    readonly hook: "COMMAND=\"$CLAUDE_TOOL_INPUT\"\nSENSITIVE_PATHS=(\n  '.env'\n  '.env.local'\n  '.env.production'\n  'credentials'\n  'secrets'\n  '.ssh'\n  '.gnupg'\n  '.aws/credentials'\n)\nfor path in \"${SENSITIVE_PATHS[@]}\"; do\n  if echo \"$COMMAND\" | grep -qE \"(cat|less|head|tail|bat|read).*$path\"; then\n    echo \"BLOCKED: Attempt to read sensitive file: $path\"\n    exit 2\n  fi\ndone\nexit 0";
+    readonly description: "Prevent reading sensitive files (.env, credentials, SSH keys)";
+};
+export declare const L3_WRITE_EDIT_PROTECTED: {
+    readonly matcher: "Write|Edit";
+    readonly hook: "INPUT=\"$CLAUDE_TOOL_INPUT\"\nPROTECTED_FILES=(\n  '.env'\n  '.env.production'\n  'credentials.json'\n  'serviceAccountKey.json'\n  '.ssh/'\n  '.gnupg/'\n)\nfor pf in \"${PROTECTED_FILES[@]}\"; do\n  if echo \"$INPUT\" | grep -q \"$pf\"; then\n    echo \"BLOCKED: Cannot modify protected file: $pf\"\n    exit 2\n  fi\ndone\nexit 0";
+    readonly description: "Prevent writing to credential and secret files";
+};
+export declare const L4_BASH_POST_SECRET_SCAN: {
+    readonly matcher: "Bash";
+    readonly hook: "OUTPUT=\"$CLAUDE_TOOL_OUTPUT\"\nLEAK_PATTERNS=(\n  'AKIA[0-9A-Z]{16}'\n  'ghp_[A-Za-z0-9]{36}'\n  'sk_live_[0-9a-zA-Z]{24,}'\n  'xox[baprs]-[0-9a-zA-Z-]+'\n  '-----BEGIN.*PRIVATE KEY-----'\n)\nfor pattern in \"${LEAK_PATTERNS[@]}\"; do\n  if echo \"$OUTPUT\" | grep -qE \"$pattern\"; then\n    echo \"WARNING: Command output may contain secrets. Review carefully.\"\n    exit 0\n  fi\ndone\nexit 0";
+    readonly description: "Warn if command output contains potential secrets";
+};
+/** The complete four-object v0 legacy cohort in committed order (L1–L3 Pre, L4 Post). */
+export declare const LEGACY_COHORT: {
+    readonly L1: {
+        readonly matcher: "Bash";
+        readonly hook: "COMMAND=\"$CLAUDE_TOOL_INPUT\"\nBLOCKED_PATTERNS=(\n  'rm -rf /'\n  'rm -rf ~'\n  'chmod 777'\n  'curl.*|.*sh'\n  'wget.*|.*sh'\n  'eval.*\\$'\n  'base64.*-d.*|.*sh'\n  ':(){:|:&};:'\n)\nfor pattern in \"${BLOCKED_PATTERNS[@]}\"; do\n  if echo \"$COMMAND\" | grep -qE \"$pattern\"; then\n    echo \"BLOCKED: Dangerous command pattern detected: $pattern\"\n    exit 2\n  fi\ndone\nexit 0";
+        readonly description: "Block dangerous shell commands (rm -rf /, chmod 777, pipe-to-sh, fork bombs)";
+    };
+    readonly L2: {
+        readonly matcher: "Bash";
+        readonly hook: "COMMAND=\"$CLAUDE_TOOL_INPUT\"\nSENSITIVE_PATHS=(\n  '.env'\n  '.env.local'\n  '.env.production'\n  'credentials'\n  'secrets'\n  '.ssh'\n  '.gnupg'\n  '.aws/credentials'\n)\nfor path in \"${SENSITIVE_PATHS[@]}\"; do\n  if echo \"$COMMAND\" | grep -qE \"(cat|less|head|tail|bat|read).*$path\"; then\n    echo \"BLOCKED: Attempt to read sensitive file: $path\"\n    exit 2\n  fi\ndone\nexit 0";
+        readonly description: "Prevent reading sensitive files (.env, credentials, SSH keys)";
+    };
+    readonly L3: {
+        readonly matcher: "Write|Edit";
+        readonly hook: "INPUT=\"$CLAUDE_TOOL_INPUT\"\nPROTECTED_FILES=(\n  '.env'\n  '.env.production'\n  'credentials.json'\n  'serviceAccountKey.json'\n  '.ssh/'\n  '.gnupg/'\n)\nfor pf in \"${PROTECTED_FILES[@]}\"; do\n  if echo \"$INPUT\" | grep -q \"$pf\"; then\n    echo \"BLOCKED: Cannot modify protected file: $pf\"\n    exit 2\n  fi\ndone\nexit 0";
+        readonly description: "Prevent writing to credential and secret files";
+    };
+    readonly L4: {
+        readonly matcher: "Bash";
+        readonly hook: "OUTPUT=\"$CLAUDE_TOOL_OUTPUT\"\nLEAK_PATTERNS=(\n  'AKIA[0-9A-Z]{16}'\n  'ghp_[A-Za-z0-9]{36}'\n  'sk_live_[0-9a-zA-Z]{24,}'\n  'xox[baprs]-[0-9a-zA-Z-]+'\n  '-----BEGIN.*PRIVATE KEY-----'\n)\nfor pattern in \"${LEAK_PATTERNS[@]}\"; do\n  if echo \"$OUTPUT\" | grep -qE \"$pattern\"; then\n    echo \"WARNING: Command output may contain secrets. Review carefully.\"\n    exit 0\n  fi\ndone\nexit 0";
+        readonly description: "Warn if command output contains potential secrets";
+    };
+};
+/**
+ * One-byte-edited L1: a single trailing character removed from the description.
+ * It must fail deep-structural equality against the exact cohort member.
+ */
+export declare const L1_ONE_BYTE_EDITED: {
+    readonly description: string;
+    readonly matcher: "Bash";
+    readonly hook: "COMMAND=\"$CLAUDE_TOOL_INPUT\"\nBLOCKED_PATTERNS=(\n  'rm -rf /'\n  'rm -rf ~'\n  'chmod 777'\n  'curl.*|.*sh'\n  'wget.*|.*sh'\n  'eval.*\\$'\n  'base64.*-d.*|.*sh'\n  ':(){:|:&};:'\n)\nfor pattern in \"${BLOCKED_PATTERNS[@]}\"; do\n  if echo \"$COMMAND\" | grep -qE \"$pattern\"; then\n    echo \"BLOCKED: Dangerous command pattern detected: $pattern\"\n    exit 2\n  fi\ndone\nexit 0";
+};
+//# sourceMappingURL=claude-hook-ownership.d.ts.map

package/dist/lib/__fixtures__/claude-hook-ownership.js

@@ -0,0 +1,96 @@
+// biome-ignore-all lint/suspicious/noTemplateCurlyInString: verbatim shell `${…}` and the literal Claude `${CLAUDE_PROJECT_DIR}` placeholder — never JS templates.
+/**
+ * Shared frozen ownership fixtures for the SkillGuard Claude PreToolUse guard.
+ *
+ * This module is the single source of truth for the byte/structure-exact
+ * identities the read-only recognition layer (Slice 2) classifies against:
+ *
+ * - the managed settings-entry handler group the Slice-3 writer installs;
+ * - the four v0 legacy cohort objects, copied verbatim from
+ *   `templates/security-hooks/claude-settings-security.json` (never normalized);
+ * - the marker/placeholder/hash constants.
+ *
+ * Everything here is data only (frozen literals plus a couple of pure
+ * builders) so it is deterministic, host-independent, and trivially testable.
+ * The production classifier imports the constants and the legacy cohort from
+ * here; the tests additionally use the one-byte-edited and duplicate variants.
+ */
+/** Exact managed marker prefix on the settings handler's `statusMessage`. */
+export const MANAGED_STATUS_PREFIX = "javi-forge-global-pretooluse:v1:sha256:";
+/** Placeholder the canonical hash normalizes the live asset SHA token to. */
+export const ASSET_SHA_PLACEHOLDER = "<ASSET_SHA256>";
+/** Whole-file SHA-256 of the retained v0 legacy scaffold template. */
+export const LEGACY_FILE_SHA256 = "b4638222ecddc2daac6ec3339596d853a626906bbd1233d789d80a319325c68d";
+/** Exact managed matcher — an exact-name alternative list, never a wildcard. */
+export const MANAGED_MATCHER = "Bash|PowerShell|Read|Write|Edit";
+/** Single project-local MJS argument, kept as a literal placeholder path. */
+export const MANAGED_ASSET_ARG = "${CLAUDE_PROJECT_DIR}/.claude/hooks/javi-forge-skillguard-pre-tool-use.mjs";
+/** Exact asset filename under `.claude/hooks/`. */
+export const ASSET_NAME = "javi-forge-skillguard-pre-tool-use.mjs";
+/** Exact first-line comment marking the managed asset. */
+export const ASSET_MANAGED_MARKER = "// javi-forge-managed: claude-pretooluse v1";
+/**
+ * A representative live asset SHA. Used only to build marker `statusMessage`
+ * values in fixtures; the canonical settings identity is invariant under this
+ * value (Decision ②), which the rotation-invariance test proves.
+ */
+export const SAMPLE_ASSET_SHA256 = "78be7e6613c012280b7ad17886462ba166b63ebd031e34565d757b3a0796d7cc";
+/** Build the exact marker `statusMessage` for a given live asset SHA. */
+export function managedStatusMessage(assetSha = SAMPLE_ASSET_SHA256) {
+    return `${MANAGED_STATUS_PREFIX}${assetSha}`;
+}
+/** Build the exact managed command handler for a given live asset SHA. */
+export function managedHandler(assetSha = SAMPLE_ASSET_SHA256) {
+    return {
+        type: "command",
+        command: "node",
+        args: [MANAGED_ASSET_ARG],
+        timeout: 30,
+        statusMessage: managedStatusMessage(assetSha),
+    };
+}
+/** Build the exact managed matcher group for a given live asset SHA. */
+export function managedGroup(assetSha = SAMPLE_ASSET_SHA256) {
+    return { matcher: MANAGED_MATCHER, hooks: [managedHandler(assetSha)] };
+}
+/** Build a valid settings container around the given hook sections. */
+export function settingsContainer(pre = [], post = [], extra = {}) {
+    return { ...extra, hooks: { PreToolUse: pre, PostToolUse: post } };
+}
+// --- v0 legacy cohort (verbatim from the retained template) ------------------
+export const L1_BASH_DANGEROUS = {
+    matcher: "Bash",
+    hook: "COMMAND=\"$CLAUDE_TOOL_INPUT\"\nBLOCKED_PATTERNS=(\n  'rm -rf /'\n  'rm -rf ~'\n  'chmod 777'\n  'curl.*|.*sh'\n  'wget.*|.*sh'\n  'eval.*\\$'\n  'base64.*-d.*|.*sh'\n  ':(){:|:&};:'\n)\nfor pattern in \"${BLOCKED_PATTERNS[@]}\"; do\n  if echo \"$COMMAND\" | grep -qE \"$pattern\"; then\n    echo \"BLOCKED: Dangerous command pattern detected: $pattern\"\n    exit 2\n  fi\ndone\nexit 0",
+    description: "Block dangerous shell commands (rm -rf /, chmod 777, pipe-to-sh, fork bombs)",
+};
+export const L2_BASH_SENSITIVE_READ = {
+    matcher: "Bash",
+    hook: "COMMAND=\"$CLAUDE_TOOL_INPUT\"\nSENSITIVE_PATHS=(\n  '.env'\n  '.env.local'\n  '.env.production'\n  'credentials'\n  'secrets'\n  '.ssh'\n  '.gnupg'\n  '.aws/credentials'\n)\nfor path in \"${SENSITIVE_PATHS[@]}\"; do\n  if echo \"$COMMAND\" | grep -qE \"(cat|less|head|tail|bat|read).*$path\"; then\n    echo \"BLOCKED: Attempt to read sensitive file: $path\"\n    exit 2\n  fi\ndone\nexit 0",
+    description: "Prevent reading sensitive files (.env, credentials, SSH keys)",
+};
+export const L3_WRITE_EDIT_PROTECTED = {
+    matcher: "Write|Edit",
+    hook: "INPUT=\"$CLAUDE_TOOL_INPUT\"\nPROTECTED_FILES=(\n  '.env'\n  '.env.production'\n  'credentials.json'\n  'serviceAccountKey.json'\n  '.ssh/'\n  '.gnupg/'\n)\nfor pf in \"${PROTECTED_FILES[@]}\"; do\n  if echo \"$INPUT\" | grep -q \"$pf\"; then\n    echo \"BLOCKED: Cannot modify protected file: $pf\"\n    exit 2\n  fi\ndone\nexit 0",
+    description: "Prevent writing to credential and secret files",
+};
+export const L4_BASH_POST_SECRET_SCAN = {
+    matcher: "Bash",
+    hook: "OUTPUT=\"$CLAUDE_TOOL_OUTPUT\"\nLEAK_PATTERNS=(\n  'AKIA[0-9A-Z]{16}'\n  'ghp_[A-Za-z0-9]{36}'\n  'sk_live_[0-9a-zA-Z]{24,}'\n  'xox[baprs]-[0-9a-zA-Z-]+'\n  '-----BEGIN.*PRIVATE KEY-----'\n)\nfor pattern in \"${LEAK_PATTERNS[@]}\"; do\n  if echo \"$OUTPUT\" | grep -qE \"$pattern\"; then\n    echo \"WARNING: Command output may contain secrets. Review carefully.\"\n    exit 0\n  fi\ndone\nexit 0",
+    description: "Warn if command output contains potential secrets",
+};
+/** The complete four-object v0 legacy cohort in committed order (L1–L3 Pre, L4 Post). */
+export const LEGACY_COHORT = {
+    L1: L1_BASH_DANGEROUS,
+    L2: L2_BASH_SENSITIVE_READ,
+    L3: L3_WRITE_EDIT_PROTECTED,
+    L4: L4_BASH_POST_SECRET_SCAN,
+};
+/**
+ * One-byte-edited L1: a single trailing character removed from the description.
+ * It must fail deep-structural equality against the exact cohort member.
+ */
+export const L1_ONE_BYTE_EDITED = {
+    ...L1_BASH_DANGEROUS,
+    description: "Block dangerous shell commands (rm -rf /, chmod 777, pipe-to-sh, fork bombs)".slice(0, -1),
+};
+//# sourceMappingURL=claude-hook-ownership.js.map

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

@@ -0,0 +1,102 @@
+/**
+ * Read-only Claude PreToolUse ownership manager (Slice 2). Its only filesystem
+ * surface is `safeReadFile` plus one isolated no-follow `lstat` helper — it never
+ * writes, creates directories, or makes backups. It owns asset byte
+ * classification (always recompute the full-file SHA), the settings read+parse
+ * wrapper (identity delegated to `claude-hook-settings`), the Node `>=22` check,
+ * 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 { 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;
+    version: number;
+    sha256: string;
+    historical: string[];
+}
+export interface Manifest {
+    asset: AssetManifestEntry;
+    settingsEntries: SettingsIdentityManifest;
+}
+export interface ClaudeHookAssetClassification {
+    state: ClaudeHookComponentState;
+    version?: number;
+    sha256?: string;
+    detail?: string;
+}
+export interface ClaudeHookDoctorReport {
+    healthy: boolean;
+    settings: {
+        state: ClaudeHookComponentState;
+        version?: number;
+        canonicalSha256?: string;
+        detail: string;
+    };
+    asset: {
+        state: ClaudeHookComponentState;
+        version?: number;
+        sha256?: string;
+        detail: string;
+    };
+    node: {
+        available: boolean;
+        version?: string;
+        satisfiesMinimum: boolean;
+    };
+    matcherExact: boolean;
+    commandShapeExact: boolean;
+    assetSettingsConsistent: boolean;
+    coverage: typeof COVERAGE;
+    hostResidual: string;
+    remediation: readonly string[];
+}
+/**
+ * Classify the asset into one of nine states from observed bytes only. Never
+ * trusts a claimed hash: the full-file SHA is always recomputed and compared to
+ * the manifest.
+ */
+export declare function classifyAssetState(assetPath: string, manifest: Manifest): Promise<ClaudeHookAssetClassification>;
+/** Read `.claude/settings.json` and classify it (lstat → bounded read → legacy SHA → pure classifier). */
+export declare function classifySettingsFile(settingsPath: string, currentAssetSha: string, identities: SettingsIdentityManifest): Promise<SettingsClassification>;
+/** Node availability + `>=22` check from a version string (no spawn). */
+export declare function detectNode(nodeVersion: string | undefined): {
+    available: boolean;
+    version?: string;
+    satisfiesMinimum: boolean;
+};
+/**
+ * Assemble the read-only component-level doctor report (no writes). `healthy` is
+ * exactly: both components `managed-current`, matcher and command shape exact,
+ * Node `>=22`. `assetSettingsConsistent` is a reported advisory, NOT part of it.
+ */
+export declare function doctorClaudePreToolUse(projectDir: string, options?: {
+    manifest?: Manifest;
+    nodeVersion?: string;
+}): Promise<ClaudeHookDoctorReport>;
+export interface ClaudeHookMutationResult {
+    ok: boolean;
+    changed: string[];
+    backups: string[];
+    report: ClaudeHookDoctorReport;
+    errors: string[];
+}
+/** 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 {};
+//# sourceMappingURL=claude-hook-manager.d.ts.map