javi-forge 1.31.0 → 1.32.0

package/dist/cli/dispatch/hooks.d.ts

@@ -4,8 +4,11 @@
  * (`./commands/hooks.js`) is lazy-imported inside the handler to keep cold-start
  * minimal, because hooks are on the commit/push hot path.
  *
- * Only subcommand: `hooks run <pre-commit|pre-push>` → dispatches to runHook and
- * exits with its code. Any other subcommand or a missing name → usage + exit 1.
+ * Subcommands:
+ *   - `hooks run <pre-commit|pre-push>` → runHook, exits with its code.
+ *   - `hooks <install|doctor|repair> claude [--force]` → runClaudeHookCommand,
+ *     exits with its code (wrong/missing target → usage + exit 1).
+ * Any other subcommand or a missing name → usage + exit 1.
  */
 import type { CLI } from "./types.js";
 export declare function handleHooks(cli: CLI): Promise<void>;

package/dist/cli/dispatch/hooks.js

@@ -4,8 +4,11 @@
  * (`./commands/hooks.js`) is lazy-imported inside the handler to keep cold-start
  * minimal, because hooks are on the commit/push hot path.
  *
- * Only subcommand: `hooks run <pre-commit|pre-push>` → dispatches to runHook and
- * exits with its code. Any other subcommand or a missing name → usage + exit 1.
+ * Subcommands:
+ *   - `hooks run <pre-commit|pre-push>` → runHook, exits with its code.
+ *   - `hooks <install|doctor|repair> claude [--force]` → runClaudeHookCommand,
+ *     exits with its code (wrong/missing target → usage + exit 1).
+ * Any other subcommand or a missing name → usage + exit 1.
  */
 import { HOOKS_HELP_TEXT } from "../help.js";
 export async function handleHooks(cli) {
@@ -23,6 +26,17 @@ export async function handleHooks(cli) {
         const code = await runHook(name, process.cwd());
         process.exit(code);
     }
+    const sub = cli.input[1];
+    if (sub === "install" || sub === "doctor" || sub === "repair") {
+        if (cli.input[2] !== "claude") {
+            console.error(`Usage: javi-forge hooks ${sub} claude`);
+            process.exit(1);
+        }
+        const { runClaudeHookCommand } = await import("../../commands/claude-hooks.js");
+        process.exit(await runClaudeHookCommand(sub, process.cwd(), {
+            force: cli.flags.force === true,
+        }));
+    }
     // No subcommand → show usage (exit 0). An unknown subcommand is a typo →
     // show usage but exit 1 rather than run nothing silently.
     console.log(HOOKS_HELP_TEXT);

package/dist/cli/help.d.ts

@@ -19,7 +19,7 @@ export declare const CI_HELP_TEXT = "\n  Usage\n    $ javi-forge ci [subcommand]
  * Per-command help for `hooks`, shown by `javi-forge hooks --help` (or when
  * `hooks` is given an unknown subcommand). Whitespace is significant.
  */
-export declare const HOOKS_HELP_TEXT = "\n  Usage\n    $ javi-forge hooks run <pre-commit|pre-push>\n\n    Run the sections enabled under hooks: in .javi-forge/ci.yaml, in a fixed\n    cheap\u2192expensive order, fail-fast. With no hooks: config the default is the\n    quick native CI gate (setup + lint + compile + gates \u2014 no tests, no coverage).\n\n  Subcommands\n    run pre-commit  Run the composed pre-commit sections\n    run pre-push    Run the composed pre-push sections\n\n  Notes\n    A blocking section failure exits non-zero and blocks the commit/push.\n    A broken .javi-forge/ci.yaml exits 1 (fail-closed \u2014 never skips a gate).\n    To skip: git commit --no-verify   (pre-push: git push --no-verify)\n\n  Examples\n    $ javi-forge hooks run pre-commit\n    $ javi-forge hooks run pre-push\n";
+export declare const HOOKS_HELP_TEXT = "\n  Usage\n    $ javi-forge hooks run <pre-commit|pre-push>\n    $ javi-forge hooks <install|doctor|repair> claude [--force]\n\n    Run the sections enabled under hooks: in .javi-forge/ci.yaml, in a fixed\n    cheap\u2192expensive order, fail-fast. With no hooks: config the default is the\n    quick native CI gate (setup + lint + compile + gates \u2014 no tests, no coverage).\n\n  Subcommands\n    run pre-commit    Run the composed pre-commit sections\n    run pre-push      Run the composed pre-push sections\n    install claude    Install the managed Claude PreToolUse guard (.claude/)\n    doctor claude     Report Claude PreToolUse guard health (informational)\n    repair claude     Repair the managed guard; --force overwrites edited assets\n\n  Notes\n    A blocking section failure exits non-zero and blocks the commit/push.\n    A broken .javi-forge/ci.yaml exits 1 (fail-closed \u2014 never skips a gate).\n    To skip: git commit --no-verify   (pre-push: git push --no-verify)\n    doctor claude is informational (always exits 0); install/repair exit 0 on\n    success, non-zero on refusal/failure. Use repair claude --force to overwrite\n    a locally edited managed asset.\n\n  Examples\n    $ javi-forge hooks run pre-commit\n    $ javi-forge hooks run pre-push\n    $ javi-forge hooks install claude\n    $ javi-forge hooks doctor claude\n    $ javi-forge hooks repair claude --force\n";
 export declare const FLAGS_SCHEMA: {
     readonly help: {
         readonly type: "boolean";

package/dist/cli/help.js

@@ -166,23 +166,33 @@ export const CI_HELP_TEXT = `
 export const HOOKS_HELP_TEXT = `
   Usage
     $ javi-forge hooks run <pre-commit|pre-push>
+    $ javi-forge hooks <install|doctor|repair> claude [--force]
 
     Run the sections enabled under hooks: in .javi-forge/ci.yaml, in a fixed
     cheap→expensive order, fail-fast. With no hooks: config the default is the
     quick native CI gate (setup + lint + compile + gates — no tests, no coverage).
 
   Subcommands
-    run pre-commit  Run the composed pre-commit sections
-    run pre-push    Run the composed pre-push sections
+    run pre-commit    Run the composed pre-commit sections
+    run pre-push      Run the composed pre-push sections
+    install claude    Install the managed Claude PreToolUse guard (.claude/)
+    doctor claude     Report Claude PreToolUse guard health (informational)
+    repair claude     Repair the managed guard; --force overwrites edited assets
 
   Notes
     A blocking section failure exits non-zero and blocks the commit/push.
     A broken .javi-forge/ci.yaml exits 1 (fail-closed — never skips a gate).
     To skip: git commit --no-verify   (pre-push: git push --no-verify)
+    doctor claude is informational (always exits 0); install/repair exit 0 on
+    success, non-zero on refusal/failure. Use repair claude --force to overwrite
+    a locally edited managed asset.
 
   Examples
     $ javi-forge hooks run pre-commit
     $ javi-forge hooks run pre-push
+    $ javi-forge hooks install claude
+    $ javi-forge hooks doctor claude
+    $ javi-forge hooks repair claude --force
 `;
 export const FLAGS_SCHEMA = {
     // `--help` is handled manually (autoHelp is disabled at the entrypoint so

package/dist/commands/claude-hooks.d.ts

@@ -0,0 +1,32 @@
+/**
+ * `javi-forge hooks <install|doctor|repair> claude` — console-only renderer for
+ * the already-tested Claude PreToolUse guard library (Slice 4a). It wires the
+ * three lib fns to human output + exit codes; it adds NO new security logic and
+ * never touches `runTransaction`/secure-fs directly.
+ *
+ * Honest-execution constraint (spec Requirement "…never fabricates execution
+ * status"): the doctor renderer reports effective execution as `inconclusive`
+ * only. It MUST NOT print, imply, or default to `RUNNABLE` — real host-probing
+ * is Slice 4b. Exit 2 (INCONCLUSIVE gate semantics) is likewise reserved for 4b
+ * and never emitted here.
+ */
+import { doctorClaudePreToolUse, installClaudePreToolUse, repairClaudePreToolUse } from "../lib/claude-hook-manager.js";
+export type ClaudeHookSub = "install" | "doctor" | "repair";
+/** Injectable seams for tests; each defaults to the real implementation. */
+export interface ClaudeHookCmdDeps {
+    install?: typeof installClaudePreToolUse;
+    doctor?: typeof doctorClaudePreToolUse;
+    repair?: typeof repairClaudePreToolUse;
+    log?: (msg: string) => void;
+    logError?: (msg: string) => void;
+}
+/**
+ * Run one Claude-hook subcommand against `projectDir`. Returns the process exit
+ * code (the dispatcher calls `process.exit`, not this fn):
+ *   - install/repair: 0 when `ok`, 1 on refusal/failure.
+ *   - doctor: always 0 (informational).
+ */
+export declare function runClaudeHookCommand(sub: ClaudeHookSub, projectDir: string, opts: {
+    force?: boolean;
+}, deps?: ClaudeHookCmdDeps): Promise<number>;
+//# sourceMappingURL=claude-hooks.d.ts.map

package/dist/commands/claude-hooks.js

@@ -0,0 +1,75 @@
+/**
+ * `javi-forge hooks <install|doctor|repair> claude` — console-only renderer for
+ * the already-tested Claude PreToolUse guard library (Slice 4a). It wires the
+ * three lib fns to human output + exit codes; it adds NO new security logic and
+ * never touches `runTransaction`/secure-fs directly.
+ *
+ * Honest-execution constraint (spec Requirement "…never fabricates execution
+ * status"): the doctor renderer reports effective execution as `inconclusive`
+ * only. It MUST NOT print, imply, or default to `RUNNABLE` — real host-probing
+ * is Slice 4b. Exit 2 (INCONCLUSIVE gate semantics) is likewise reserved for 4b
+ * and never emitted here.
+ */
+import { doctorClaudePreToolUse, installClaudePreToolUse, repairClaudePreToolUse, } from "../lib/claude-hook-manager.js";
+function renderMutation(verb, result, log, logError) {
+    if (result.ok) {
+        log(`${verb} claude: ok`);
+        if (result.changed.length > 0) {
+            log("changed:");
+            for (const p of result.changed)
+                log(`  ${p}`);
+        }
+        else {
+            log("changed: nothing (already up to date)");
+        }
+        if (result.backups.length > 0) {
+            log("backups:");
+            for (const p of result.backups)
+                log(`  ${p}`);
+        }
+        return 0;
+    }
+    logError(`${verb} claude: refused`);
+    for (const e of result.errors)
+        logError(`  ${e}`);
+    return 1;
+}
+function renderDoctor(report, log) {
+    log(`doctor claude: ${report.healthy ? "healthy" : "unhealthy"}`);
+    log(`  settings: ${report.settings.state} — ${report.settings.detail}`);
+    log(`  asset:    ${report.asset.state} — ${report.asset.detail}`);
+    log(`  node:     ${report.node.version ?? "unavailable"} (min-satisfied: ${report.node.satisfiesMinimum})`);
+    // Honest stub: 4a cannot confirm the guard is live. Never RUNNABLE.
+    log("  execution: inconclusive (effective-execution probe deferred to 4b)");
+    log(`  host-residual: ${report.hostResidual}`);
+    if (report.remediation.length > 0) {
+        log("  remediation:");
+        for (const r of report.remediation)
+            log(`    - ${r}`);
+    }
+    // Doctor is informational, not a gate — always exit 0 (spec Scenario
+    // "Doctor reports component health").
+    return 0;
+}
+/**
+ * Run one Claude-hook subcommand against `projectDir`. Returns the process exit
+ * code (the dispatcher calls `process.exit`, not this fn):
+ *   - install/repair: 0 when `ok`, 1 on refusal/failure.
+ *   - doctor: always 0 (informational).
+ */
+export async function runClaudeHookCommand(sub, projectDir, opts, deps = {}) {
+    const log = deps.log ?? ((m) => console.log(m));
+    const logError = deps.logError ?? ((m) => console.error(m));
+    const install = deps.install ?? installClaudePreToolUse;
+    const doctor = deps.doctor ?? doctorClaudePreToolUse;
+    const repair = deps.repair ?? repairClaudePreToolUse;
+    if (sub === "install") {
+        return renderMutation("install", await install(projectDir), log, logError);
+    }
+    if (sub === "repair") {
+        const result = await repair(projectDir, { force: opts.force === true });
+        return renderMutation("repair", result, log, logError);
+    }
+    return renderDoctor(await doctor(projectDir), log);
+}
+//# sourceMappingURL=claude-hooks.js.map

package/dist/commands/init/steps/security.d.ts

@@ -1,11 +1,15 @@
 import type { StepFn } from "../types.js";
 /**
- * Step 14: Scaffold security hooks (hook-consolidation S4 fold).
+ * Step 14: Scaffold security hooks (hook-consolidation S4 fold + SkillGuard 4a).
  *
  * - When options.securityHooks is false, reports "skipped".
  * - Otherwise:
- *   1. Copies the kiteguard-style runtime settings to `.claude/settings.json`
- *      when absent (KEPT — this is a real feature).
+ *   1. When `claudePreToolUseGuard` is set, installs the managed Claude
+ *      PreToolUse guard via the transactional `installClaudePreToolUse`
+ *      (SkillGuard Slice 4a). The legacy copy-if-absent
+ *      `claude-settings-security.json` scaffold is RETIRED — the managed
+ *      installer owns `.claude/settings.json` + the hook asset with proper
+ *      ownership markers.
  *   2. Merges the `hooks:` security sections for the selected reliability
  *      profile into `.javi-forge/ci.yaml` via `setHookFeature` (creating a
  *      minimal `version: 2` config when absent). The dispatcher composes these

package/dist/commands/init/steps/security.js

@@ -1,8 +1,5 @@
-import path from "node:path";
-import fs from "fs-extra";
-import { SECURITY_HOOKS_DIR } from "../../../constants.js";
 import { setHookFeature } from "../../../lib/ci-config.js";
-import { ensureDirExists } from "../../../lib/common.js";
+import { installClaudePreToolUse } from "../../../lib/claude-hook-manager.js";
 import { report } from "../report.js";
 /**
  * Hook-feature preset per reliability profile (hook-consolidation S4).
@@ -21,12 +18,16 @@ const PROFILE_PRESET = {
     strict: { preCommit: ["secrets", "permissions"], prePush: ["deps"] },
 };
 /**
- * Step 14: Scaffold security hooks (hook-consolidation S4 fold).
+ * Step 14: Scaffold security hooks (hook-consolidation S4 fold + SkillGuard 4a).
  *
  * - When options.securityHooks is false, reports "skipped".
  * - Otherwise:
- *   1. Copies the kiteguard-style runtime settings to `.claude/settings.json`
- *      when absent (KEPT — this is a real feature).
+ *   1. When `claudePreToolUseGuard` is set, installs the managed Claude
+ *      PreToolUse guard via the transactional `installClaudePreToolUse`
+ *      (SkillGuard Slice 4a). The legacy copy-if-absent
+ *      `claude-settings-security.json` scaffold is RETIRED — the managed
+ *      installer owns `.claude/settings.json` + the hook asset with proper
+ *      ownership markers.
  *   2. Merges the `hooks:` security sections for the selected reliability
  *      profile into `.javi-forge/ci.yaml` via `setHookFeature` (creating a
  *      minimal `version: 2` config when absent). The dispatcher composes these
@@ -37,7 +38,7 @@ const PROFILE_PRESET = {
  */
 export const stepSecurityHooks = async (ctx) => {
     const { projectDir, dryRun, onStep, options } = ctx;
-    const { securityHooks, hookProfile } = options;
+    const { securityHooks, hookProfile, claudePreToolUseGuard } = options;
     const stepId = "security-hooks";
     report(onStep, stepId, "Scaffold security hooks", "running");
     try {
@@ -48,18 +49,22 @@ export const stepSecurityHooks = async (ctx) => {
         const profile = hookProfile ?? "standard";
         const preset = PROFILE_PRESET[profile];
         if (dryRun) {
-            report(onStep, stepId, "Scaffold security hooks", "done", `dry-run: would merge ${profile} hooks preset + copy .claude/settings.json`);
+            const guardNote = claudePreToolUseGuard
+                ? " + install Claude PreToolUse guard"
+                : "";
+            report(onStep, stepId, "Scaffold security hooks", "done", `dry-run: would merge ${profile} hooks preset${guardNote}`);
             return;
         }
-        // 1. Copy the kiteguard-style runtime security settings to .claude/.
-        const settingsSrc = path.join(SECURITY_HOOKS_DIR, "claude-settings-security.json");
-        if (await fs.pathExists(settingsSrc)) {
-            const claudeDir = path.join(projectDir, ".claude");
-            await ensureDirExists(claudeDir);
-            const settingsDest = path.join(claudeDir, "settings.json");
-            if (!(await fs.pathExists(settingsDest))) {
-                await fs.copy(settingsSrc, settingsDest);
+        // 1. Install the managed Claude PreToolUse guard (transactional; owns
+        //    .claude/settings.json + the hook asset). Retires the legacy copy.
+        let guardNote = "";
+        if (claudePreToolUseGuard) {
+            const result = await installClaudePreToolUse(projectDir);
+            if (!result.ok) {
+                report(onStep, stepId, "Scaffold security hooks", "error", `Claude guard install refused: ${result.errors.join("; ")}`);
+                return;
             }
+            guardNote = "; Claude guard installed";
         }
         // 2. Merge the profile's security sections into .javi-forge/ci.yaml.
         for (const feature of preset.preCommit) {
@@ -72,9 +77,10 @@ export const stepSecurityHooks = async (ctx) => {
             ...preset.preCommit.map((f) => `pre-commit.${f}`),
             ...preset.prePush.map((f) => `pre-push.${f}`),
         ];
-        report(onStep, stepId, "Scaffold security hooks", "done", merged.length > 0
+        const presetNote = merged.length > 0
             ? `${profile} preset: ${merged.join(", ")}`
-            : `${profile} preset: CI gate only (no security sections)`);
+            : `${profile} preset: CI gate only (no security sections)`;
+        report(onStep, stepId, "Scaffold security hooks", "done", `${presetNote}${guardNote}`);
     }
     catch (e) {
         report(onStep, stepId, "Scaffold security hooks", "error", String(e));

package/dist/types/index.d.ts

@@ -16,6 +16,11 @@ export interface InitOptions {
     claudeMd: boolean;
     securityHooks: boolean;
     hookProfile: HookProfile;
+    /**
+     * Install the managed Claude PreToolUse guard during init. Derived from
+     * `securityHooks` at the single App.tsx call site (all profiles incl. Minimal).
+     */
+    claudePreToolUseGuard: boolean;
     codeGraph: boolean;
     dockerDeploy: boolean;
     /** Service name for docker rollout (default: 'app') */

package/dist/ui/App.js

@@ -93,6 +93,9 @@ export default function App({ dryRun = false, presetStack, presetCI, presetMemor
             claudeMd: opts.claudeMd,
             securityHooks: opts.securityHooks,
             hookProfile: opts.hookProfile,
+            // Derived from securityHooks alone — ALL profiles incl. Minimal
+            // install the managed guard when security hooks are enabled.
+            claudePreToolUseGuard: opts.securityHooks,
             codeGraph: opts.codeGraph,
             localAi: opts.localAi,
             dockerDeploy: false,

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "javi-forge",
-	"version": "1.31.0",
+	"version": "1.32.0",
 	"description": "Project scaffolding and AI-ready CI bootstrap",
 	"type": "module",
 	"bin": {