javi-forge 1.24.0 → 1.25.0

package/dist/cli/dispatch/ci.js

@@ -70,9 +70,14 @@ export async function handleCi(cli, ctx) {
     // Sub-command: javi-forge ci init → install git hooks
     if (cli.input[1] === "init") {
         const { installCIHooks } = await import("../../commands/ci.js");
-        const { installed, upgraded, backups, errors, states } = await installCIHooks(process.cwd(), {
+        const { installed, upgraded, backups, errors, states, notes } = await installCIHooks(process.cwd(), {
             force: cli.flags.force === true,
         });
+        // Migration notes (e.g. "legacy javi-forge hooksPath removed") come first:
+        // they explain a config change the operator did not explicitly ask for.
+        for (const note of notes) {
+            console.log(`ℹ ${note}`);
+        }
         for (const backup of backups) {
             console.log(`⚠ Backed up the previous hook → ${backup}`);
         }

package/dist/commands/ci.d.ts

@@ -212,6 +212,12 @@ export interface InstallHooksResult {
     backups: string[];
     errors: string[];
     states: HookStateReport[];
+    /**
+     * Informational messages from the hooksPath guard (D6) — e.g. the "legacy
+     * javi-forge hooksPath removed" note emitted when the migration path unsets
+     * a `ci-local/hooks` local value. NOT errors; surfaced to the operator.
+     */
+    notes: string[];
 }
 /**
  * Pure classification of hook CONTENT (D6 steps 1-5).

package/dist/commands/ci.js

@@ -1548,9 +1548,227 @@ async function repairHookMode(hookPath) {
 async function readHookBody(hookName) {
     return await fs.readFile(path.join(HOOK_ASSETS_DIR, hookName), "utf8");
 }
+/** The exact — and ONLY — value javi-forge itself ever wrote (git.ts:83). */
+const LEGACY_HOOKSPATH = "ci-local/hooks";
+/**
+ * Read a higher-scope `core.hooksPath` with `git config <scope> --get`.
+ *
+ * `--global`/`--system` reads return each scope's OWN value regardless of the
+ * local value, so a shadowing higher-scope hooksPath is visible with ZERO
+ * mutation. git exits 1 (no section / no config file) or 5 (key unset) for "no
+ * value" → `{ value: "" }`. ANY other failure is surfaced as `failed` so the
+ * guard can fail CLOSED: a blind spot on a possible shadow must never let the
+ * migration unset the local value and half-migrate the repo.
+ */
+async function readScopedHooksPath(projectDir, scope) {
+    try {
+        const { stdout } = await execFileAsync("git", ["config", scope, "--get", "core.hooksPath"], { cwd: projectDir });
+        return { value: stdout.trim() };
+    }
+    catch (e) {
+        const code = e.code;
+        if (code === 1 || code === 5) {
+            return { value: "" };
+        }
+        return { value: "", failed: e instanceof Error ? e.message : String(e) };
+    }
+}
+/**
+ * Read the LOCAL `core.hooksPath` with the SAME fail-closed discipline as
+ * {@link readScopedHooksPath} (JDA-001).
+ *
+ * git exits 1 (no section / no config file) or 5 (key unset) for a genuine "no
+ * value" → `{ value: "" }`, the safe fresh-install path. ANY OTHER failure
+ * (config lock, I/O error, a corrupt `.git/config`, a git fault) is surfaced as
+ * `failed` so the guard can REFUSE. Swallowing such a failure to `""` would be a
+ * FAIL-OPEN: a local value genuinely = `ci-local/hooks` that transiently fails
+ * to read would look like a fresh repo, so step 5 would never unset it and the
+ * shims would be installed into `.git/hooks` while the still-present local value
+ * keeps SHADOWING them — `installCIHooks` would report installed/upgraded while
+ * git runs the OLD ci-local bodies. An unknown-state local read must never be
+ * treated as a fresh install.
+ */
+async function readLocalHooksPath(projectDir) {
+    try {
+        const { stdout } = await execFileAsync("git", ["config", "--local", "--get", "core.hooksPath"], { cwd: projectDir });
+        return { value: stdout.trim() };
+    }
+    catch (e) {
+        const code = e.code;
+        if (code === 1 || code === 5) {
+            return { value: "" };
+        }
+        return { value: "", failed: e instanceof Error ? e.message : String(e) };
+    }
+}
+/**
+ * Read a WORKTREE-scoped `core.hooksPath` (JDA-002), which — with
+ * `extensions.worktreeConfig` enabled — ALSO shadows `.git/hooks`.
+ *
+ * The extension is checked FIRST for a load-bearing reason: when it is OFF, `git
+ * config --worktree` silently behaves like `--local` (verified), so reading it
+ * here would double-count the LOCAL value and refuse a valid legacy migration.
+ * It is a DISTINCT scope only when the extension is enabled, and only then does
+ * `--worktree --get` read from `$GIT_DIR/config.worktree` WITHOUT falling back to
+ * local. Gating on the extension also handles the multiple-worktree + extension-off
+ * case where `--worktree` errors out ("not enabled"): we never issue that read, so
+ * that specific error can never surface as a spurious refuse.
+ *
+ * Same fail-closed discipline as the scoped reads: exit 1/5 → genuine no value;
+ * any OTHER failure → `failed` so the guard REFUSES rather than fail open.
+ */
+async function readWorktreeHooksPath(projectDir) {
+    // Determine whether the worktree config extension is enabled.
+    let enabled = false;
+    try {
+        const { stdout } = await execFileAsync("git", ["config", "--bool", "--get", "extensions.worktreeConfig"], { cwd: projectDir });
+        enabled = stdout.trim() === "true";
+    }
+    catch (e) {
+        const code = e.code;
+        if (code === 1 || code === 5) {
+            // Extension unset/disabled → no DISTINCT worktree scope exists; the local
+            // read (step 3) already covers the --worktree==--local fallback. Treat as
+            // no worktree value, never a refuse.
+            return { value: "" };
+        }
+        // Cannot determine the extension state → fail CLOSED.
+        return { value: "", failed: e instanceof Error ? e.message : String(e) };
+    }
+    if (!enabled) {
+        return { value: "" };
+    }
+    try {
+        const { stdout } = await execFileAsync("git", ["config", "--worktree", "--get", "core.hooksPath"], { cwd: projectDir });
+        return { value: stdout.trim() };
+    }
+    catch (e) {
+        const code = e.code;
+        if (code === 1 || code === 5) {
+            return { value: "" };
+        }
+        return { value: "", failed: e instanceof Error ? e.message : String(e) };
+    }
+}
+/**
+ * The ATOMIC `core.hooksPath` guard (design D6). Runs BEFORE the install loop
+ * mutates anything.
+ *
+ * DETECT-BEFORE-MUTATE — steps 1-4 are pure reads; only step 5 writes (unset
+ * the legacy local value). EVERY refuse path returns `{ refuse }` having mutated
+ * NOTHING, so the repo is left in its EXACT prior state and can never land
+ * half-migrated (JDA-001 / JDA-008). The single write (`--local --unset`) and
+ * the subsequent shim install happen ONLY on the fully-validated success/force
+ * path.
+ */
+async function guardHooksPath(projectDir, hooksDir, manifest, force) {
+    // ── Step 1: classify the managed slots (pure read), exactly as the install
+    //   loop will. A manifest problem is NOT classified here — it surfaces
+    //   per-hook in the loop; an unclassifiable slot is treated as ABSENT (never
+    //   fabricate a foreign refusal from a manifest error).
+    const foreignSlots = [];
+    for (const name of HOOK_NAMES) {
+        const entry = manifest[name];
+        try {
+            assertHookManifestEntry(entry, name);
+        }
+        catch {
+            continue;
+        }
+        const state = await classifyHookPath(path.join(hooksDir, name), name, entry);
+        if (state === HOOK_STATE.FOREIGN) {
+            foreignSlots.push(name);
+        }
+    }
+    // ── Step 2: DETECT a shadowing higher-scope hooksPath via SCOPED reads (ZERO
+    //   mutation). A global/system value shadows .git/hooks the moment git
+    //   consults hooksPath, so installing there would be INERT — refuse rather
+    //   than fail open. Detected WITHOUT unsetting local, so a
+    //   `local-unset + global-present` half-migration is impossible.
+    for (const scope of ["--system", "--global"]) {
+        const probe = await readScopedHooksPath(projectDir, scope);
+        if (probe.failed !== undefined) {
+            return {
+                refuse: `could not read ${scope} git config core.hooksPath (${probe.failed}). Refusing to install: a higher-scope hooksPath could silently shadow .git/hooks and the hooks would not run. Resolve the git error and re-run.`,
+            };
+        }
+        if (probe.value !== "") {
+            const label = scope === "--global" ? "global" : "system";
+            return {
+                refuse: `a ${label} core.hooksPath='${probe.value}' would redirect git away from .git/hooks — the installed hooks would NOT run. Resolve it first (git config ${scope} --unset core.hooksPath) and re-run.`,
+            };
+        }
+    }
+    // ── Step 2b (JDA-002): a WORKTREE-scoped hooksPath (with
+    //   extensions.worktreeConfig enabled) ALSO shadows .git/hooks. Same
+    //   fail-closed handling: a non-1/5 read failure REFUSES rather than fail open.
+    const worktree = await readWorktreeHooksPath(projectDir);
+    if (worktree.failed !== undefined) {
+        return {
+            refuse: `could not read --worktree git config core.hooksPath (${worktree.failed}). Refusing to install: a worktree-scoped hooksPath could silently shadow .git/hooks and the hooks would not run. Resolve the git error and re-run.`,
+        };
+    }
+    if (worktree.value !== "") {
+        return {
+            refuse: `a worktree core.hooksPath='${worktree.value}' would redirect git away from .git/hooks — the installed hooks would NOT run. Resolve it first (git config --worktree --unset core.hooksPath) and re-run.`,
+        };
+    }
+    // Shadow reads now cover --global, --system and --worktree. The includeIf
+    // residual edge remains: a hooksPath injected only through a
+    // [includeIf "gitdir:…"] conditional include is NOT returned by
+    // --global/--system/--worktree --get and would surface only in an effective
+    // read — a documented residual edge, not covered by these scoped reads.
+    // ── Step 3: the LOCAL value. A foreign local manager (husky/lefthook/custom)
+    //   owns this repo's hooks; never hijack it. --force does NOT override (force
+    //   is consent to lose a file, not to seize another manager's config). The read
+    //   fails CLOSED (JDA-001): a non-1/5 failure REFUSES rather than mistake an
+    //   unreadable local value for a fresh repo and install over a shadowing value.
+    const localProbe = await readLocalHooksPath(projectDir);
+    if (localProbe.failed !== undefined) {
+        return {
+            refuse: `could not read --local git config core.hooksPath (${localProbe.failed}). Refusing to install: a local hooksPath could silently shadow .git/hooks and the installed hooks would not run. Resolve the git error and re-run.`,
+        };
+    }
+    const local = localProbe.value;
+    if (local !== "" && local !== LEGACY_HOOKSPATH) {
+        return {
+            refuse: `core.hooksPath is set to '${local}' — another hook manager owns this repo's hooks. javi-forge refuses to install or change it. Unset it yourself (git config --local --unset core.hooksPath) if you want javi-forge hooks.`,
+        };
+    }
+    const legacy = local === LEGACY_HOOKSPATH;
+    // ── Step 4: installability, ONLY on the migration path. Unsetting the legacy
+    //   value ACTIVATES whatever sits in .git/hooks; if a slot is FOREIGN without
+    //   --force, migrating now would activate a dormant foreign hook → ATOMIC
+    //   REFUSE, leave core.hooksPath SET, install NOTHING. When there is no legacy
+    //   value to unset, foreign slots are handled per-hook by the install loop as
+    //   before — nothing is being activated.
+    if (legacy && !force && foreignSlots.length > 0) {
+        const slot = foreignSlots[0];
+        return {
+            refuse: `core.hooksPath=${LEGACY_HOOKSPATH} would be removed, but .git/hooks/${slot} holds a foreign hook (a prior 'tdd init' or hand-written hook). Migrating now would activate it. Resolve it (delete/back it up) or re-run with --force.`,
+        };
+    }
+    // ── Step 5: ONLY NOW mutate. Every check passed (or --force). Unset the
+    //   legacy local value — the ONLY value javi-forge ever wrote, and only the
+    //   --local scope is ever touched — then let the caller install. The install
+    //   NEVER runs before steps 2 and 4.
+    if (legacy) {
+        await execFileAsync("git", ["config", "--local", "--unset", "core.hooksPath"], { cwd: projectDir });
+        return {
+            note: "legacy javi-forge hooksPath removed; hooks now live in .git/hooks",
+        };
+    }
+    return {};
+}
 export async function installCIHooks(projectDir, options = {}) {
     const force = options.force === true;
-    const empty = { installed: [], upgraded: [], backups: [], states: [] };
+    const empty = {
+        installed: [],
+        upgraded: [],
+        backups: [],
+        states: [],
+        notes: [],
+    };
     const gitDir = path.join(projectDir, ".git");
     if (!(await fs.pathExists(gitDir))) {
         return {
@@ -1587,6 +1805,19 @@ export async function installCIHooks(projectDir, options = {}) {
     const backups = [];
     const errors = [];
     const states = [];
+    const notes = [];
+    // The ATOMIC core.hooksPath guard (D6) is the SINGLE choke point shared by
+    // `ci init` and `init`. It runs DETECT-BEFORE-MUTATE: on refuse it has
+    // mutated nothing and we return without installing; on the success/force
+    // path it has already unset any legacy `ci-local/hooks` value and we
+    // proceed to install the shims.
+    const guard = await guardHooksPath(projectDir, hooksDir, manifest, force);
+    if ("refuse" in guard) {
+        return { ...empty, errors: [guard.refuse] };
+    }
+    if (guard.note !== undefined) {
+        notes.push(guard.note);
+    }
     for (const name of HOOK_NAMES) {
         const hookPath = path.join(hooksDir, name);
         const entry = manifest[name];
@@ -1631,6 +1862,6 @@ export async function installCIHooks(projectDir, options = {}) {
             errors.push(`${name}: ${e instanceof Error ? e.message : String(e)}`);
         }
     }
-    return { installed, upgraded, backups, errors, states };
+    return { installed, upgraded, backups, errors, states, notes };
 }
 //# sourceMappingURL=ci.js.map

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

@@ -11,15 +11,17 @@ import type { StepFn } from "../types.js";
  */
 export declare const stepGitInit: StepFn;
 /**
- * Step 2: Configure git hooks path.
+ * Step 2: Install managed git hooks (D7 reconciliation).
  *
- * - Copies templates/ci-local/ → <project>/ci-local/ (no overwrite).
- * - chmod 0755 on hook files.
- * - Sets git config core.hooksPath to ci-local/hooks.
- * - Skips entirely when CI_LOCAL_DIR template is missing.
- * - Errors are swallowed and reported as status:"error" — never thrown.
+ * Init no longer copies `ci-local/` hook bodies into the project nor flips
+ * `core.hooksPath` — both were the pre-consolidation mechanism. It now delegates
+ * to `installCIHooks`, the SINGLE writer of `.git/hooks` and the choke point for
+ * the ATOMIC `core.hooksPath` guard (D6). A foreign/global hooksPath, or a
+ * dormant foreign slot, is REFUSED there with zero mutation and surfaced as an
+ * error here — init never overrides the user's hook manager.
  *
- * Extracted VERBATIM from src/commands/init.ts (PR 1 of 6).
+ * - dry-run: reports "would install managed hooks", calls nothing.
+ * - Errors are swallowed and reported as status:"error" — never thrown.
  */
 export declare const stepGitHooks: StepFn;
 //# sourceMappingURL=git.d.ts.map

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

@@ -1,6 +1,5 @@
 import path from "node:path";
 import fs from "fs-extra";
-import { CI_LOCAL_DIR } from "../../../constants.js";
 import { execFileAsync } from "../../../lib/exec.js";
 import { report } from "../report.js";
 /**
@@ -34,48 +33,46 @@ export const stepGitInit = async (ctx) => {
     }
 };
 /**
- * Step 2: Configure git hooks path.
+ * Step 2: Install managed git hooks (D7 reconciliation).
  *
- * - Copies templates/ci-local/ → <project>/ci-local/ (no overwrite).
- * - chmod 0755 on hook files.
- * - Sets git config core.hooksPath to ci-local/hooks.
- * - Skips entirely when CI_LOCAL_DIR template is missing.
- * - Errors are swallowed and reported as status:"error" — never thrown.
+ * Init no longer copies `ci-local/` hook bodies into the project nor flips
+ * `core.hooksPath` — both were the pre-consolidation mechanism. It now delegates
+ * to `installCIHooks`, the SINGLE writer of `.git/hooks` and the choke point for
+ * the ATOMIC `core.hooksPath` guard (D6). A foreign/global hooksPath, or a
+ * dormant foreign slot, is REFUSED there with zero mutation and surfaced as an
+ * error here — init never overrides the user's hook manager.
  *
- * Extracted VERBATIM from src/commands/init.ts (PR 1 of 6).
+ * - dry-run: reports "would install managed hooks", calls nothing.
+ * - Errors are swallowed and reported as status:"error" — never thrown.
  */
 export const stepGitHooks = async (ctx) => {
     const { projectDir, dryRun, onStep } = ctx;
     const stepId = "git-hooks";
-    report(onStep, stepId, "Configure git hooks path", "running");
+    const label = "Install git hooks";
+    report(onStep, stepId, label, "running");
+    if (dryRun) {
+        report(onStep, stepId, label, "done", "would install managed hooks");
+        return;
+    }
     try {
-        const ciLocalSrc = CI_LOCAL_DIR;
-        const ciLocalDest = path.join(projectDir, "ci-local");
-        if (await fs.pathExists(ciLocalSrc)) {
-            if (!dryRun) {
-                await fs.copy(ciLocalSrc, ciLocalDest, {
-                    overwrite: false,
-                    errorOnExist: false,
-                });
-                // Set core.hooksPath to ci-local/hooks
-                const hooksDir = path.join(ciLocalDest, "hooks");
-                if (await fs.pathExists(hooksDir)) {
-                    // Ensure hooks are executable
-                    const hookFiles = await fs.readdir(hooksDir);
-                    for (const hook of hookFiles) {
-                        await fs.chmod(path.join(hooksDir, hook), 0o755);
-                    }
-                    await execFileAsync("git", ["config", "core.hooksPath", "ci-local/hooks"], { cwd: projectDir });
-                }
-            }
-            report(onStep, stepId, "Configure git hooks path", "done", "ci-local/hooks");
-        }
-        else {
-            report(onStep, stepId, "Configure git hooks path", "skipped", "no ci-local dir");
+        // Lazy import: installCIHooks pulls in the CI command surface; keep it off
+        // the init cold-start path, exactly like the `ci init` dispatch branch.
+        const { installCIHooks } = await import("../../ci.js");
+        const { installed, upgraded, backups, errors, notes } = await installCIHooks(projectDir);
+        if (errors.length > 0) {
+            report(onStep, stepId, label, "error", errors.join("; "));
+            return;
         }
+        const detail = [
+            ...installed.map((h) => `installed ${h}`),
+            ...upgraded.map((h) => `upgraded ${h}`),
+            ...notes,
+            ...backups.map((b) => `backup ${b}`),
+        ].join("; ") || "managed hooks installed";
+        report(onStep, stepId, label, "done", detail);
     }
     catch (e) {
-        report(onStep, stepId, "Configure git hooks path", "error", String(e));
+        report(onStep, stepId, label, "error", String(e));
     }
 };
 //# sourceMappingURL=git.js.map

package/package.json

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