javi-forge 1.28.1 → 1.29.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/claude-hook-manager.d.ts

@@ -0,0 +1,88 @@
+/**
+ * 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";
+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[];
+    errors: string[];
+}
+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

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

@@ -0,0 +1,276 @@
+/**
+ * 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 { createHash } from "node:crypto";
+import { lstat } 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 { safeReadFile } from "./safe-read.js";
+/** 1 MiB read budget, shared with the runtime's stdin envelope. */
+const ASSET_MAX_BYTES = 1024 * 1024;
+const NODE_MINIMUM_MAJOR = 22;
+const READ_OPTS = {
+    maxBytes: ASSET_MAX_BYTES,
+    hardRejectOverBytes: ASSET_MAX_BYTES,
+    maxLineLength: Number.POSITIVE_INFINITY,
+};
+const COVERAGE = ["Bash", "PowerShell", "Read", "Write", "Edit"];
+const HOST_RESIDUAL = "spawn/start/timeout failures continue through Claude permission flow";
+const ASSET_SHA_TOKEN = /^[0-9a-f]{64}$/;
+async function lstatNoFollow(target) {
+    try {
+        const stats = await lstat(target);
+        if (stats.isSymbolicLink())
+            return { kind: "symlink" };
+        if (!stats.isFile())
+            return { kind: "non-regular" };
+        return { kind: "file" };
+    }
+    catch (error) {
+        const code = error.code;
+        if (code === "ENOENT" || code === "ENOTDIR")
+            return { kind: "enoent" };
+        return { kind: "error", detail: code ?? String(error) };
+    }
+}
+/** Hash the observed bytes as UTF-8, matching the manifest's raw-file hash for the managed asset. */
+function sha256Of(content) {
+    return createHash("sha256")
+        .update(Buffer.from(content, "utf8"))
+        .digest("hex");
+}
+/**
+ * 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 async function classifyAssetState(assetPath, manifest) {
+    const stat = await lstatNoFollow(assetPath);
+    if (stat.kind === "enoent")
+        return { state: "absent" };
+    if (stat.kind === "symlink")
+        return { state: "symlink" };
+    if (stat.kind === "non-regular")
+        return { state: "non-regular" };
+    if (stat.kind === "error")
+        return { state: "non-regular", detail: stat.detail };
+    const read = await safeReadFile(assetPath, READ_OPTS);
+    if (!read.ok) {
+        if (read.reason === "not-found")
+            return { state: "absent" };
+        if (read.reason === "binary")
+            return { state: "foreign", detail: "binary" };
+        if (read.reason === "too-large") {
+            return { state: "foreign", detail: "exceeds asset budget" };
+        }
+        return { state: "non-regular", detail: read.reason };
+    }
+    if (!read.content.startsWith(`${ASSET_MANAGED_MARKER}\n`)) {
+        return { state: "foreign" };
+    }
+    const sha256 = sha256Of(read.content);
+    if (sha256 === manifest.asset.sha256) {
+        return {
+            state: "managed-current",
+            version: manifest.asset.version,
+            sha256,
+        };
+    }
+    if (manifest.asset.historical.includes(sha256)) {
+        return {
+            state: "released-outdated",
+            version: manifest.asset.version,
+            sha256,
+        };
+    }
+    return { state: "edited-managed", sha256 };
+}
+/** Read `.claude/settings.json` and classify it (lstat → bounded read → legacy SHA → pure classifier). */
+export async function classifySettingsFile(settingsPath, currentAssetSha, identities) {
+    const parsed = await readSettings(settingsPath);
+    if ("state" in parsed)
+        return parsed.classification;
+    return classifySettingsEntry(parsed.value, currentAssetSha, identities);
+}
+const done = (classification) => ({
+    state: true,
+    classification,
+});
+async function readSettings(settingsPath) {
+    const stat = await lstatNoFollow(settingsPath);
+    if (stat.kind === "enoent")
+        return done({ state: "absent" });
+    if (stat.kind === "symlink")
+        return done({ state: "symlink" });
+    if (stat.kind === "non-regular")
+        return done({ state: "non-regular" });
+    if (stat.kind === "error") {
+        return done({ state: "non-regular", detail: stat.detail });
+    }
+    const read = await safeReadFile(settingsPath, READ_OPTS);
+    if (!read.ok) {
+        if (read.reason === "not-found")
+            return done({ state: "absent" });
+        if (read.reason === "binary" || read.reason === "too-large") {
+            return done({ state: "malformed", detail: read.reason });
+        }
+        return done({ state: "non-regular", detail: read.reason });
+    }
+    if (sha256Of(read.content) === LEGACY_FILE_SHA256) {
+        return done({ state: "exact-legacy", detail: "whole-file" });
+    }
+    try {
+        return { value: JSON.parse(read.content) };
+    }
+    catch {
+        return done({ state: "malformed", detail: "invalid-json" });
+    }
+}
+/** Node availability + `>=22` check from a version string (no spawn). */
+export function detectNode(nodeVersion) {
+    if (!nodeVersion)
+        return { available: false, satisfiesMinimum: false };
+    const major = Number.parseInt(nodeVersion.split(".")[0] ?? "", 10);
+    return {
+        available: true,
+        version: nodeVersion,
+        satisfiesMinimum: Number.isFinite(major) && major >= NODE_MINIMUM_MAJOR,
+    };
+}
+const NO_SIGNALS = {
+    matcherExact: false,
+    commandShapeExact: false,
+    assetSettingsConsistent: false,
+};
+/** Derive matcher/command/consistency signals from the marked handler, if any. */
+function settingsSignals(value, classification, currentAssetSha) {
+    if (classification.groupIndex === undefined || !isPlainObject(value)) {
+        return NO_SIGNALS;
+    }
+    const hooks = value.hooks;
+    const groups = isPlainObject(hooks) && Array.isArray(hooks.PreToolUse)
+        ? hooks.PreToolUse
+        : [];
+    const group = groups[classification.groupIndex];
+    if (!isPlainObject(group) || !Array.isArray(group.hooks))
+        return NO_SIGNALS;
+    const handler = group.hooks[classification.handlerIndex ?? -1];
+    if (!isPlainObject(handler))
+        return NO_SIGNALS;
+    const args = handler.args;
+    const commandShapeExact = handler.type === "command" &&
+        handler.command === "node" &&
+        Array.isArray(args) &&
+        args.length === 1 &&
+        args[0] === MANAGED_ASSET_ARG &&
+        handler.timeout === 30;
+    let assetSettingsConsistent = false;
+    if (typeof handler.statusMessage === "string" &&
+        handler.statusMessage.startsWith(MANAGED_STATUS_PREFIX)) {
+        const token = handler.statusMessage.slice(MANAGED_STATUS_PREFIX.length);
+        assetSettingsConsistent =
+            ASSET_SHA_TOKEN.test(token) && token === currentAssetSha;
+    }
+    return {
+        matcherExact: group.matcher === MANAGED_MATCHER,
+        commandShapeExact,
+        assetSettingsConsistent,
+    };
+}
+const REMEDIATION = {
+    absent: "install the managed $ (Slice 3)",
+    "released-outdated": "upgrade the managed $ (Slice 3)",
+    "exact-legacy": "migrate the legacy $ (Slice 3)",
+    "edited-managed": "repair the managed $ with --force (Slice 3)",
+    foreign: "manually review the $",
+    symlink: "manually review the $",
+    "non-regular": "manually review the $",
+    malformed: "manually review the $",
+};
+function remediationFor(state, component) {
+    return REMEDIATION[state]?.replace("$", component);
+}
+/**
+ * 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 async function doctorClaudePreToolUse(projectDir, options) {
+    const manifest = options?.manifest ?? (await readManifest());
+    const currentAssetSha = manifest.asset.sha256;
+    const asset = await classifyAssetState(path.join(projectDir, ".claude", "hooks", ASSET_NAME), manifest);
+    const settingsRead = await readSettings(path.join(projectDir, ".claude", "settings.json"));
+    const settings = "state" in settingsRead
+        ? settingsRead.classification
+        : classifySettingsEntry(settingsRead.value, currentAssetSha, manifest.settingsEntries);
+    const signals = "value" in settingsRead
+        ? settingsSignals(settingsRead.value, settings, currentAssetSha)
+        : NO_SIGNALS;
+    const node = detectNode(options?.nodeVersion ?? process.versions.node);
+    const remediation = new Set();
+    if (asset.state !== "managed-current") {
+        const line = remediationFor(asset.state, "asset");
+        if (line)
+            remediation.add(line);
+    }
+    if (settings.state !== "managed-current") {
+        const line = remediationFor(settings.state, "settings");
+        if (line)
+            remediation.add(line);
+    }
+    if (!node.satisfiesMinimum)
+        remediation.add("install Node 22 or newer");
+    if (!signals.matcherExact)
+        remediation.add("restore the exact managed matcher");
+    if (!signals.commandShapeExact) {
+        remediation.add("restore the exact managed command shape");
+    }
+    const healthy = settings.state === "managed-current" &&
+        asset.state === "managed-current" &&
+        signals.matcherExact &&
+        signals.commandShapeExact &&
+        node.satisfiesMinimum;
+    return {
+        healthy,
+        settings: {
+            state: settings.state,
+            version: settings.version,
+            canonicalSha256: settings.canonicalSha256,
+            detail: settings.detail ?? settings.state,
+        },
+        asset: {
+            state: asset.state,
+            version: asset.version,
+            sha256: asset.sha256,
+            detail: asset.detail ?? asset.state,
+        },
+        node,
+        matcherExact: signals.matcherExact,
+        commandShapeExact: signals.commandShapeExact,
+        assetSettingsConsistent: signals.assetSettingsConsistent,
+        coverage: COVERAGE,
+        hostResidual: HOST_RESIDUAL,
+        remediation: [...remediation].sort(),
+    };
+}
+async function readManifest() {
+    const read = await safeReadFile(path.join(CLAUDE_HOOK_ASSETS_DIR, "manifest.json"), READ_OPTS);
+    if (!read.ok)
+        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");
+}
+export function repairClaudePreToolUse(_projectDir, _options) {
+    throw new Error("unimplemented: Slice 3 transaction");
+}
+//# sourceMappingURL=claude-hook-manager.js.map