kibi-cli 2.1.0 → 2.3.0

package/dist/commands/doctor.js

@@ -22,8 +22,11 @@ import * as path from "node:path";
 import { fileURLToPath } from "node:url";
 import { bootstrapKibiEnvironment, secretSourceFromBootstrap, } from "../env/bootstrap.js";
 import { describeConfiguredCapabilityPlugins, readProjectKibiConfig, } from "../plugins/project-config.js";
+import { SwiplResolutionError, inspectSwiplBundle, probeRequiredLibraries, resolveSwipl, } from "../prolog/swipl-resolver.js";
 import { buildMigrationPlan, migrationAction, } from "../public/operations/migration-plan.js";
+import { resolveGitRepository, } from "../utils/git-repository-context.js";
 import { readKbManifestStatus } from "../utils/kb-manifest.js";
+import { hasManagedHooks, outdatedManagedHooks } from "./init-helpers.js";
 import { planLegacyStorageMigration } from "./legacy-storage-migration.js";
 /**
  * First-party plugin diagnostics known without importing the package.
@@ -38,6 +41,10 @@ const JEV_DEFAULT_MODEL = "jev-latest";
 const JEV_MAX_TIMEOUT_MS = 120_000;
 // implements REQ-003
 export async function doctorCommand(options = {}) {
+    // The repository context is per-diagnostic-run state: clearing here keeps
+    // repeated in-process invocations honest when core.hooksPath changes
+    // between runs, without introducing another ambient cache.
+    cachedRepositoryContext = undefined;
     const checks = [
         {
             name: "SWI-Prolog",
@@ -71,6 +78,10 @@ export async function doctorCommand(options = {}) {
             name: "post-rewrite hook",
             check: checkPostRewriteHook,
         },
+        {
+            name: "Kibi-managed hook sections",
+            check: checkManagedHookSections,
+        },
         {
             name: "Capability plugins",
             check: checkCapabilityPlugins,
@@ -309,45 +320,78 @@ function resolveInstalledPackageInfo(name) {
         dependencies: undefined,
     };
 }
+const SWIPL_SOURCE_LABELS = {
+    env: "KIBI_SWIPL",
+    bundled: "the bundled build",
+    path: "PATH",
+};
+// implements REQ-prolog-doctor-runtime-report
 function checkSWIProlog() {
+    let resolved;
     try {
-        const output = execSync("swipl --version", { encoding: "utf-8" });
-        const versionMatch = output.match(/version\s+(\d+)\.(\d+)/i);
-        if (!versionMatch) {
-            return {
-                passed: false,
-                message: "Unable to parse version",
-                remediation: "Reinstall SWI-Prolog from https://www.swi-prolog.org/",
-            };
-        }
-        const majorText = versionMatch[1];
-        if (!majorText) {
-            return {
-                passed: false,
-                message: "Unable to parse major version",
-                remediation: "Reinstall SWI-Prolog from https://www.swi-prolog.org/",
-            };
-        }
-        const major = Number.parseInt(majorText, 10);
-        if (major < 9) {
+        resolved = resolveSwipl();
+    }
+    catch (error) {
+        if (!(error instanceof SwiplResolutionError))
+            throw error;
+        const [headline = error.message, ...guidance] = error.message.split("\n");
+        return {
+            passed: false,
+            message: headline,
+            ...(guidance.length === 0 ? {} : { remediation: guidance.join("\n   ") }),
+            details: {
+                code: error.code,
+                platform: error.platform,
+                ...(error.packageName === undefined
+                    ? {}
+                    : { bundledPackage: error.packageName }),
+            },
+        };
+    }
+    const details = {
+        source: resolved.source,
+        path: resolved.bin,
+        version: resolved.version,
+        ...(resolved.home === undefined ? {} : { home: resolved.home }),
+    };
+    const summary = `Version ${resolved.version} from ${SWIPL_SOURCE_LABELS[resolved.source]} at ${resolved.bin}`;
+    const probe = probeRequiredLibraries(resolved);
+    if (probe.kind !== "ok") {
+        const remediation = resolved.source === "bundled"
+            ? "Reinstall the bundled SWI-Prolog package, or set KIBI_SWIPL=system to use swipl from PATH."
+            : "Install a full SWI-Prolog 9.0+ distribution that provides these libraries (for example swi-prolog rather than swi-prolog-nox or a minimal build), or point KIBI_SWIPL at one.";
+        if (probe.kind === "missing") {
             return {
                 passed: false,
-                message: `Version ${major}.x found (requires ≥9.0)`,
-                remediation: "Upgrade SWI-Prolog to version 9.0 or higher from https://www.swi-prolog.org/",
+                message: `${summary}; cannot load required libraries: ${probe.libraries.join(", ")}`,
+                remediation,
+                details: { ...details, missingLibraries: probe.libraries },
             };
         }
-        return {
-            passed: true,
-            message: `Version ${versionMatch[0]} installed`,
-        };
-    }
-    catch (error) {
         return {
             passed: false,
-            message: "Not installed or not in PATH",
-            remediation: "Install SWI-Prolog from https://www.swi-prolog.org/ and add to PATH",
+            message: `${summary}; the required-library load check could not run (${probe.detail})`,
+            remediation,
+            details,
         };
     }
+    let bundleNote = "";
+    if (resolved.source === "path") {
+        try {
+            const bundle = inspectSwiplBundle();
+            if (bundle.state === "missing") {
+                bundleNote = `; bundled ${bundle.packageName} is not installed (npm install --save-dev ${bundle.packageName})`;
+            }
+        }
+        catch {
+            // The bundle note is advisory; never let it fail the check.
+        }
+    }
+    return {
+        passed: true,
+        message: `${summary}; required libraries load${bundleNote}`,
+        details,
+    };
 }
 /**
  * Read-only view of package.json plugin activation.
@@ -525,15 +569,86 @@ function checkGitRepository() {
         };
     }
 }
+// Hook health must be diagnosed against the hooks directory Git actually
+// executes (resolved via git rev-parse --git-path hooks, honoring
+// core.hooksPath and linked worktrees), not against <cwd>/.git/hooks.
+// implements REQ-git-hook-effective-install
+let cachedRepositoryContext;
+function doctorRepositoryContext() {
+    const cwd = process.cwd();
+    if (cachedRepositoryContext?.cwd !== cwd) {
+        const resolution = resolveGitRepository(cwd);
+        cachedRepositoryContext = {
+            cwd,
+            context: resolution.status === "ok" ? resolution.context : null,
+        };
+    }
+    return cachedRepositoryContext.context;
+}
+function effectiveHooksDir() {
+    const context = doctorRepositoryContext();
+    return (context?.effectiveHooksDir ?? path.join(process.cwd(), ".git", "hooks"));
+}
+function shellQuote(value) {
+    return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+function remediationHookPaths(...hooks) {
+    const dir = effectiveHooksDir();
+    return `Run: chmod +x ${hooks.map((hook) => shellQuote(path.join(dir, hook))).join(" ")}`;
+}
+function hooksPathSuffix() {
+    const context = doctorRepositoryContext();
+    if (!context?.hooksPathConfig)
+        return "";
+    const origin = context.hooksPathOrigin
+        ? ` from ${context.hooksPathOrigin}`
+        : "";
+    return ` (core.hooksPath=${context.hooksPathConfig}${origin})`;
+}
+/**
+ * Kibi-managed hook sections must match what this CLI installs. A section
+ * written by an older CLI keeps running while silently lacking newer gates
+ * (the pre-commit `check-generated` step, for example), and the other hook
+ * checks only confirm that kibi is invoked at all.
+ */
+// implements REQ-cli-doctor
+function checkManagedHookSections() {
+    const hooksDir = effectiveHooksDir();
+    let outdated;
+    try {
+        if (!hasManagedHooks(hooksDir)) {
+            return { passed: true, message: "Not installed (optional)" };
+        }
+        outdated = outdatedManagedHooks(hooksDir);
+    }
+    catch {
+        return {
+            passed: false,
+            message: "Unable to read hook content",
+            remediation: "Run: kibi init",
+        };
+    }
+    if (outdated.length > 0) {
+        return {
+            passed: false,
+            message: `Outdated for this Kibi CLI: ${outdated.join(", ")} (installed by a different version; newer gates may be missing)${hooksPathSuffix()}`,
+            remediation: "Run: kibi init to refresh the kibi-managed hook sections",
+        };
+    }
+    return { passed: true, message: "Current for this Kibi CLI" };
+}
 function checkGitHooks() {
-    const postCheckoutPath = path.join(process.cwd(), ".git/hooks/post-checkout");
-    const postMergePath = path.join(process.cwd(), ".git/hooks/post-merge");
+    const postCheckoutPath = path.join(effectiveHooksDir(), "post-checkout");
+    const postMergePath = path.join(effectiveHooksDir(), "post-merge");
+    const preCommitPath = path.join(effectiveHooksDir(), "pre-commit");
     const postCheckoutExists = existsSync(postCheckoutPath);
     const postMergeExists = existsSync(postMergePath);
-    if (!postCheckoutExists && !postMergeExists) {
+    // An existing pre-commit is hard enforcement; the companions being absent
+    // must not downgrade the summary to "optional".
+    if (!postCheckoutExists && !postMergeExists && !existsSync(preCommitPath)) {
         return {
             passed: true,
-            message: "Not installed (optional)",
+            message: `Not installed (optional)${hooksPathSuffix()}`,
         };
     }
     if (postCheckoutExists && postMergeExists) {
@@ -545,13 +660,13 @@ function checkGitHooks() {
             if (checkoutExecutable && mergeExecutable) {
                 return {
                     passed: true,
-                    message: "Installed and executable",
+                    message: `Installed and executable${hooksPathSuffix()}`,
                 };
             }
             return {
                 passed: false,
-                message: "Installed but not executable",
-                remediation: "Run: chmod +x .git/hooks/post-checkout .git/hooks/post-merge",
+                message: `Installed but not executable${hooksPathSuffix()}`,
+                remediation: remediationHookPaths("post-checkout", "post-merge"),
             };
         }
         catch (error) {
@@ -563,20 +678,20 @@ function checkGitHooks() {
     }
     return {
         passed: false,
-        message: "Partially installed",
+        message: `Partially installed${hooksPathSuffix()}`,
         remediation: "Run: kibi init",
     };
 }
 function checkPreCommitHook() {
-    const postCheckoutPath = path.join(process.cwd(), ".git/hooks/post-checkout");
-    const postMergePath = path.join(process.cwd(), ".git/hooks/post-merge");
-    const preCommitPath = path.join(process.cwd(), ".git/hooks/pre-commit");
+    const postCheckoutPath = path.join(effectiveHooksDir(), "post-checkout");
+    const postMergePath = path.join(effectiveHooksDir(), "post-merge");
+    const preCommitPath = path.join(effectiveHooksDir(), "pre-commit");
     const postCheckoutExists = existsSync(postCheckoutPath);
     const postMergeExists = existsSync(postMergePath);
-    if (!postCheckoutExists && !postMergeExists) {
+    if (!postCheckoutExists && !postMergeExists && !existsSync(preCommitPath)) {
         return {
             passed: true,
-            message: "Not installed (optional)",
+            message: `Not installed (optional)${hooksPathSuffix()}`,
         };
     }
     const preCommitExists = existsSync(preCommitPath);
@@ -620,7 +735,7 @@ function checkPreCommitHook() {
                 }
                 return {
                     passed: true,
-                    message: "Installed and executable (resolves kibi CLI; uses 'kibi check --staged')",
+                    message: `Installed and executable (resolves kibi CLI; uses 'kibi check --staged')${hooksPathSuffix()}`,
                 };
             }
             // Warn but pass if using legacy kibi check without --staged
@@ -632,8 +747,8 @@ function checkPreCommitHook() {
         }
         return {
             passed: false,
-            message: "Installed but not executable",
-            remediation: "Run: chmod +x .git/hooks/pre-commit",
+            message: `Installed but not executable${hooksPathSuffix()}`,
+            remediation: remediationHookPaths("pre-commit"),
         };
     }
     catch (error) {
@@ -645,15 +760,15 @@ function checkPreCommitHook() {
     }
 }
 function checkPostRewriteHook() {
-    const postCheckoutPath = path.join(process.cwd(), ".git/hooks/post-checkout");
-    const postMergePath = path.join(process.cwd(), ".git/hooks/post-merge");
-    const postRewritePath = path.join(process.cwd(), ".git/hooks/post-rewrite");
+    const postCheckoutPath = path.join(effectiveHooksDir(), "post-checkout");
+    const postMergePath = path.join(effectiveHooksDir(), "post-merge");
+    const postRewritePath = path.join(effectiveHooksDir(), "post-rewrite");
     const postCheckoutExists = existsSync(postCheckoutPath);
     const postMergeExists = existsSync(postMergePath);
-    if (!postCheckoutExists && !postMergeExists) {
+    if (!postCheckoutExists && !postMergeExists && !existsSync(postRewritePath)) {
         return {
             passed: true,
-            message: "Not installed (optional)",
+            message: `Not installed (optional)${hooksPathSuffix()}`,
         };
     }
     const postRewriteExists = existsSync(postRewritePath);
@@ -689,13 +804,13 @@ function checkPostRewriteHook() {
             }
             return {
                 passed: true,
-                message: "Installed and executable",
+                message: `Installed and executable${hooksPathSuffix()}`,
             };
         }
         return {
             passed: false,
-            message: "Installed but not executable",
-            remediation: "Run: chmod +x .git/hooks/post-rewrite",
+            message: `Installed but not executable${hooksPathSuffix()}`,
+            remediation: remediationHookPaths("post-rewrite"),
         };
     }
     catch (error) {

package/dist/commands/github-init.d.ts

@@ -2,7 +2,7 @@ export declare const GITHUB_REPORT_WORKFLOW_RELPATH = ".github/workflows/kibi-re
 export declare const GITHUB_BADGE_WORKFLOW_RELPATH = ".github/workflows/kibi-badge.yml";
 export declare const GITHUB_PAGES_NAMESPACE = "kibi-report";
 export declare const KIBI_BADGE_ALT = "Kibi requirement health";
-export declare const KIBI_METRIC_DOCS_URL = "https://github.com/Looted/kibi/blob/develop/docs/github-integration.md#what-the-badge-means";
+export declare const KIBI_METRIC_DOCS_URL = "https://looted.github.io/kibi/guide/github-integration.html#what-the-badge-means";
 export declare const PLACEHOLDER_OWNER = "OWNER";
 export declare const PLACEHOLDER_REPO = "REPOSITORY";
 export type GitHubRepo = Readonly<{

package/dist/commands/github-init.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"github-init.d.ts","sourceRoot":"","sources":["../../src/commands/github-init.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"github-init.d.ts","sourceRoot":"","sources":["../../src/commands/github-init.ts"],"names":[],"mappings":"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"}

package/dist/commands/github-init.js

@@ -16,7 +16,7 @@
  along with this program.  If not, see <https://www.gnu.org/licenses/>.
 */
 import { execFileSync } from "node:child_process";
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync, } from "node:fs";
 import * as path from "node:path";
 import { fileURLToPath } from "node:url";
 const __filename = fileURLToPath(import.meta.url);
@@ -25,7 +25,7 @@ export const GITHUB_REPORT_WORKFLOW_RELPATH = ".github/workflows/kibi-report.yml
 export const GITHUB_BADGE_WORKFLOW_RELPATH = ".github/workflows/kibi-badge.yml";
 export const GITHUB_PAGES_NAMESPACE = "kibi-report";
 export const KIBI_BADGE_ALT = "Kibi requirement health";
-export const KIBI_METRIC_DOCS_URL = "https://github.com/Looted/kibi/blob/develop/docs/github-integration.md#what-the-badge-means";
+export const KIBI_METRIC_DOCS_URL = "https://looted.github.io/kibi/guide/github-integration.html#what-the-badge-means";
 export const PLACEHOLDER_OWNER = "OWNER";
 export const PLACEHOLDER_REPO = "REPOSITORY";
 const README_CANDIDATES = ["README.md", "readme.md", "Readme.md"];
@@ -101,9 +101,16 @@ export function hasKibiBadge(content) {
     return /\[!\[Kibi requirement health\]/i.test(content);
 }
 export function detectReadmePath(cwd) {
+    let entries;
+    try {
+        entries = new Set(readdirSync(cwd));
+    }
+    catch {
+        return undefined;
+    }
     for (const name of README_CANDIDATES) {
         const candidate = path.join(cwd, name);
-        if (existsSync(candidate)) {
+        if (entries.has(name) && existsSync(candidate)) {
             return candidate;
         }
     }

package/dist/commands/init-helpers.d.ts

@@ -4,6 +4,21 @@ export declare function createManifestFile(kbDir: string): void;
 export declare function updateGitIgnore(cwd: string): void;
 export declare function ensureSymbolsManifestFile(cwd: string): void;
 export declare function copySchemaFiles(kbDir: string, schemaSourceDir: string): Promise<void>;
-export declare function installHook(hookPath: string, content: string): void;
-export declare function installGitHooks(gitDir: string): void;
+export type InstallHookResult = "installed" | "updated" | "skipped-foreign" | "skipped-symlink" | "skipped-unsupported";
+export declare function installHook(hookPath: string, content: string): InstallHookResult;
+export interface GitHookInstallResult {
+    hook: "pre-commit" | "post-checkout" | "post-merge" | "post-rewrite";
+    result: InstallHookResult;
+}
+/**
+ * Installed kibi-managed hooks whose managed section differs from what this
+ * CLI installs, such as a pre-commit gate written before `check-generated`
+ * joined it. User-authored hooks without kibi markers are not reported.
+ */
+export declare function outdatedManagedHooks(hooksDir: string): string[];
+/** Whether any hook in the directory carries a kibi-managed section. */
+export declare function hasManagedHooks(hooksDir: string): boolean;
+export declare function installGitHooks(hooksDir: string, options?: {
+    hooksPathOrigin?: string | null;
+}): GitHookInstallResult[];
 //# sourceMappingURL=init-helpers.d.ts.map

package/dist/commands/init-helpers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"init-helpers.d.ts","sourceRoot":"","sources":["../../src/commands/init-helpers.ts"],"names":[],"mappings":"AAuIA,wBAAsB,gBAAgB,CACpC,GAAG,GAAE,MAAsB,GAC1B,OAAO,CAAC,MAAM,CAAC,CASjB;AAED,wBAAgB,0BAA0B,CACxC,KAAK,EAAE,MAAM,EACb,aAAa,EAAE,MAAM,GACpB,IAAI,CAUN;AAED,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAGtD;AAED,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CA6BjD;AAkDD,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAU3D;AAED,wBAAsB,eAAe,CACnC,KAAK,EAAE,MAAM,EACb,eAAe,EAAE,MAAM,GACtB,OAAO,CAAC,IAAI,CAAC,CAYf;AASD,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAkCnE;AAED,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAiBpD"}
+{"version":3,"file":"init-helpers.d.ts","sourceRoot":"","sources":["../../src/commands/init-helpers.ts"],"names":[],"mappings":"AAyIA,wBAAsB,gBAAgB,CACpC,GAAG,GAAE,MAAsB,GAC1B,OAAO,CAAC,MAAM,CAAC,CASjB;AAED,wBAAgB,0BAA0B,CACxC,KAAK,EAAE,MAAM,EACb,aAAa,EAAE,MAAM,GACpB,IAAI,CAUN;AAED,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAGtD;AAED,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CA6BjD;AAkDD,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAU3D;AAED,wBAAsB,eAAe,CACnC,KAAK,EAAE,MAAM,EACb,eAAe,EAAE,MAAM,GACtB,OAAO,CAAC,IAAI,CAAC,CAYf;AASD,MAAM,MAAM,iBAAiB,GACzB,WAAW,GACX,SAAS,GACT,iBAAiB,GACjB,iBAAiB,GACjB,qBAAqB,CAAC;AAoB1B,wBAAgB,WAAW,CACzB,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,GACd,iBAAiB,CAyEnB;AAED,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,YAAY,GAAG,eAAe,GAAG,YAAY,GAAG,cAAc,CAAC;IACrE,MAAM,EAAE,iBAAiB,CAAC;CAC3B;AAiBD;;;;GAIG;AAEH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE,CAU/D;AAED,wEAAwE;AAExE,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAQzD;AAED,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE;IAAE,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CAAO,GAChD,oBAAoB,EAAE,CA8CxB"}

package/dist/commands/init-helpers.js

@@ -15,7 +15,7 @@
  You should have received a copy of the GNU Affero General Public License
  along with this program.  If not, see <https://www.gnu.org/licenses/>.
 */
-import { chmodSync, copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync, } from "node:fs";
+import { chmodSync, copyFileSync, existsSync, lstatSync, mkdirSync, readFileSync, writeFileSync, } from "node:fs";
 import * as path from "node:path";
 import fg from "fast-glob";
 import { getBranchDiagnostic, resolveActiveBranch, } from "../utils/branch-resolver.js";
@@ -236,41 +236,141 @@ const KIBI_HOOK_END = "# END kibi-managed";
 function escapeRegex(s) {
     return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
+function hookIntegrationRecipe(hook) {
+    // Recipes must reproduce the exact checks the Kibi template runs for that
+    // hook, with failure propagation, or the delegation is weaker than the
+    // template it replaces.
+    switch (hook) {
+        case "pre-commit":
+            return "delegate from that hook with 'kibi check-generated --staged --changed-only && kibi check --staged' (both commands must succeed; '&&' propagates the first failure)";
+        case "post-checkout":
+            return "delegate from that hook to 'kibi sync' on branch checkouts (the template skips file checkouts)";
+        case "post-merge":
+            return "delegate from that hook to 'kibi sync'";
+        case "post-rewrite":
+            return "delegate from that hook to 'kibi sync' after rebase/amend rewrites";
+        default:
+            return "delegate to the matching Kibi template command";
+    }
+}
 export function installHook(hookPath, content) {
     // implements REQ-008
+    // implements REQ-git-hook-effective-install
     const kibiSection = `${KIBI_HOOK_BEGIN}\n${content}\n${KIBI_HOOK_END}`;
-    if (existsSync(hookPath)) {
+    let hookStats;
+    try {
+        hookStats = lstatSync(hookPath);
+    }
+    catch (error) {
+        if (error.code === "ENOENT" ||
+            error.code === "ENOTDIR") {
+            // Missing hook: create it through the parent directory. Refuse when an
+            // ancestor is itself a symlink whose target leaves the resolved path
+            // (realpath is checked by the caller's hooks-dir guard).
+            writeFileSync(hookPath, `#!/bin/sh\n${kibiSection}\n`, { mode: 0o755 });
+            chmodSync(hookPath, 0o755);
+            return "installed";
+        }
+        console.error(`! Unable to inspect ${hookPath}: ${error.message}; leaving it untouched.`);
+        return "skipped-unsupported";
+    }
+    if (hookStats.isSymbolicLink()) {
+        // Never follow a symlinked hook: read/write/chmod would modify an
+        // arbitrary target outside our guard. Dangling symlinks are treated the
+        // same (the intended target must not be auto-created either).
+        return "skipped-symlink";
+    }
+    if (!hookStats.isFile()) {
+        return "skipped-unsupported";
+    }
+    try {
         const existing = readFileSync(hookPath, "utf8");
         if (existing.includes(KIBI_HOOK_BEGIN) &&
             existing.includes(KIBI_HOOK_END)) {
             // Replace only the kibi-managed section, preserving any user-authored content
             const updated = existing.replace(new RegExp(`${escapeRegex(KIBI_HOOK_BEGIN)}[\\s\\S]*?${escapeRegex(KIBI_HOOK_END)}`), kibiSection);
             writeFileSync(hookPath, updated, { mode: 0o755 });
+            chmodSync(hookPath, 0o755);
+            return "updated";
         }
-        else if (existing.trim().length > 0) {
-            return;
-        }
-        else {
-            const shebang = existing.startsWith("#!/") ? "" : "#!/bin/sh\n";
-            writeFileSync(hookPath, `${shebang}${existing.trimEnd()}\n${kibiSection}\n`, { mode: 0o755 });
+        if (existing.trim().length > 0) {
+            // A hook we did not write: never overwrite foreign enforcement.
+            return "skipped-foreign";
         }
+        const shebang = existing.startsWith("#!/") ? "" : "#!/bin/sh\n";
+        writeFileSync(hookPath, `${shebang}${existing.trimEnd()}\n${kibiSection}\n`, { mode: 0o755 });
+        chmodSync(hookPath, 0o755);
+        return "installed";
     }
-    else {
-        writeFileSync(hookPath, `#!/bin/sh\n${kibiSection}\n`, { mode: 0o755 });
+    catch (error) {
+        console.error(`! Unable to read ${hookPath}: ${error.message}; leaving it untouched.`);
+        return "skipped-unsupported";
     }
-    // Explicitly ensure hook is executable
-    chmodSync(hookPath, 0o755);
 }
-export function installGitHooks(gitDir) {
-    const hooksDir = path.join(gitDir, "hooks");
+/** Kibi-managed hooks in install order, with the template each one installs. */
+const MANAGED_HOOK_TEMPLATES = [
+    ["post-checkout", POST_CHECKOUT_HOOK],
+    ["post-merge", POST_MERGE_HOOK],
+    ["post-rewrite", POST_REWRITE_HOOK],
+    ["pre-commit", PRE_COMMIT_HOOK],
+];
+function managedHookBody(template) {
+    return template.replace("#!/bin/sh\n", "");
+}
+/**
+ * Installed kibi-managed hooks whose managed section differs from what this
+ * CLI installs, such as a pre-commit gate written before `check-generated`
+ * joined it. User-authored hooks without kibi markers are not reported.
+ */
+// implements REQ-cli-doctor
+export function outdatedManagedHooks(hooksDir) {
+    const managed = new RegExp(`${escapeRegex(KIBI_HOOK_BEGIN)}\\n([\\s\\S]*?)\\n${escapeRegex(KIBI_HOOK_END)}`);
+    return MANAGED_HOOK_TEMPLATES.filter(([hook, template]) => {
+        const hookPath = path.join(hooksDir, hook);
+        if (!existsSync(hookPath))
+            return false;
+        const section = managed.exec(readFileSync(hookPath, "utf8"));
+        return section !== null && section[1] !== managedHookBody(template);
+    }).map(([hook]) => hook);
+}
+/** Whether any hook in the directory carries a kibi-managed section. */
+// implements REQ-cli-doctor
+export function hasManagedHooks(hooksDir) {
+    return MANAGED_HOOK_TEMPLATES.some(([hook]) => {
+        const hookPath = path.join(hooksDir, hook);
+        return (existsSync(hookPath) &&
+            readFileSync(hookPath, "utf8").includes(KIBI_HOOK_BEGIN));
+    });
+}
+export function installGitHooks(hooksDir, options = {}) {
+    // implements REQ-git-hook-effective-install
     mkdirSync(hooksDir, { recursive: true });
-    const postCheckoutPath = path.join(hooksDir, "post-checkout");
-    const postMergePath = path.join(hooksDir, "post-merge");
-    const postRewritePath = path.join(hooksDir, "post-rewrite");
-    const preCommitPath = path.join(hooksDir, "pre-commit");
-    installHook(postCheckoutPath, POST_CHECKOUT_HOOK.replace("#!/bin/sh\n", ""));
-    installHook(postMergePath, POST_MERGE_HOOK.replace("#!/bin/sh\n", ""));
-    installHook(postRewritePath, POST_REWRITE_HOOK.replace("#!/bin/sh\n", ""));
-    installHook(preCommitPath, PRE_COMMIT_HOOK.replace("#!/bin/sh\n", ""));
-    console.log("✓ Installed git hooks (pre-commit, post-checkout, post-merge, post-rewrite)");
+    const results = MANAGED_HOOK_TEMPLATES.map(([hook, template]) => ({
+        hook,
+        result: installHook(path.join(hooksDir, hook), managedHookBody(template)),
+    }));
+    for (const { hook, result } of results) {
+        if (result === "skipped-foreign") {
+            console.log(`! ${hook}: existing non-Kibi hook left untouched; Kibi enforcement is NOT installed for this hook. To integrate: ${hookIntegrationRecipe(hook)}.`);
+        }
+        else if (result === "skipped-symlink") {
+            console.log(`! ${hook}: hook is a symlink; Kibi never edits symlink targets. Manage the target manually (${hookIntegrationRecipe(hook)}).`);
+        }
+        else if (result === "skipped-unsupported") {
+            console.log(`! ${hook}: hook path is not a regular file; left untouched.`);
+        }
+    }
+    const installedOrUpdated = results.filter((entry) => entry.result === "installed" || entry.result === "updated");
+    if (installedOrUpdated.length > 0) {
+        console.log(`✓ Installed/updated Kibi git hooks at ${hooksDir} (${installedOrUpdated.map((entry) => entry.hook).join(", ")})`);
+    }
+    else {
+        console.log(`! No Kibi git hooks installed at ${hooksDir} (all hooks were skipped).`);
+    }
+    if (options.hooksPathOrigin) {
+        // Configuration/location reporting stays neutral about what happened:
+        // the per-hook lines and the aggregate above carry the install verdict.
+        console.log(`! core.hooksPath is configured (${options.hooksPathOrigin}); the effective hooks directory for THIS checkout is ${hooksDir}. Git resolves a relative hooks path separately under every worktree, so coverage of other worktrees is INCOMPLETE/UNVERIFIED: commit a versioned launcher that delegates to kibi, or run 'kibi init' in each checkout. Kibi will not change core.hooksPath.`);
+    }
+    return results;
 }

package/dist/commands/init.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../src/commands/init.ts"],"names":[],"mappings":"AAqCA,UAAU,WAAW;IACnB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAoDD,wBAAsB,WAAW,CAC/B,OAAO,EAAE,WAAW,GACnB,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CA2F/B"}
+{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../src/commands/init.ts"],"names":[],"mappings":"AAmGA,UAAU,WAAW;IACnB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAoDD,wBAAsB,WAAW,CAC/B,OAAO,EAAE,WAAW,GACnB,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CAwI/B"}