kibi-cli 2.0.0 → 2.2.0

package/dist/commands/doctor.js

@@ -20,11 +20,30 @@ import { existsSync, readFileSync, statSync } from "node:fs";
 import { createRequire } from "node:module";
 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 { 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.
+ * Generic third-party plugins report package/capability/mode/declared only.
+ */
+// implements REQ-kibi-env-bootstrap, REQ-capability-plugin-configuration-v1
+const FIRST_PARTY_PLUGIN_SECRETS = {
+    "kibi-plugin-jev": ["TYPESAFE_API_KEY"],
+};
+/** Static Jev defaults — must stay aligned with kibi-plugin-jev (no import). */
+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",
@@ -58,8 +77,19 @@ export async function doctorCommand(options = {}) {
             name: "post-rewrite hook",
             check: checkPostRewriteHook,
         },
+        {
+            name: "Kibi-managed hook sections",
+            check: checkManagedHookSections,
+        },
+        {
+            name: "Capability plugins",
+            check: checkCapabilityPlugins,
+        },
     ];
-    const results = checks.map(({ name, check }) => ({ name, ...check() }));
+    const results = [];
+    for (const { name, check } of checks) {
+        results.push({ name, ...(await check()) });
+    }
     const allPassed = results.every((result) => result.passed);
     const runtime = await runtimeProvenance();
     const packageActions = await packageMigrationActions(runtime);
@@ -329,6 +359,107 @@ function checkSWIProlog() {
         };
     }
 }
+/**
+ * Read-only view of package.json plugin activation.
+ * Does not import or execute plugin packages (no loadPluginPackage / dynamic import).
+ */
+// implements REQ-capability-plugin-configuration-v1, REQ-kibi-env-bootstrap
+function checkCapabilityPlugins() {
+    try {
+        const bootstrap = bootstrapKibiEnvironment();
+        const workspaceRoot = bootstrap.workspaceRoot;
+        const rows = describeConfiguredCapabilityPlugins(workspaceRoot);
+        if (rows.length === 0) {
+            return {
+                passed: true,
+                message: "None configured; builtin providers only",
+            };
+        }
+        const parts = rows.map((row) => `${row.package} ${row.capability} ${row.mode} declared=${row.declared ? "yes" : "no"}`);
+        if (rows.some((row) => !row.declared)) {
+            return {
+                passed: false,
+                message: parts.join("; "),
+                remediation: "Add the configured plugin package to dependencies, devDependencies, or optionalDependencies, or remove the kibi.plugins activation entry.",
+            };
+        }
+        const config = readProjectKibiConfig(workspaceRoot);
+        const packages = [
+            ...new Set((config.plugins ?? []).map((plugin) => plugin.package)),
+        ];
+        const missingSecrets = [];
+        const legacySecrets = [];
+        for (const packageName of packages) {
+            const secrets = FIRST_PARTY_PLUGIN_SECRETS[packageName] ?? [];
+            for (const secret of secrets) {
+                const source = formatSecretSourcePart(secret, bootstrap);
+                parts.push(`${secret}=${source}`);
+                if (source === "missing")
+                    missingSecrets.push(secret);
+                if (source === "legacy_env")
+                    legacySecrets.push(secret);
+            }
+            if (packageName === "kibi-plugin-jev") {
+                parts.push(...formatJevStaticConfigParts());
+            }
+        }
+        const message = parts.join("; ");
+        if (missingSecrets.length > 0) {
+            const jevMissing = missingSecrets.includes("TYPESAFE_API_KEY");
+            return {
+                passed: false,
+                message,
+                remediation: jevMissing
+                    ? "Set `TYPESAFE_API_KEY` in `~/.config/kibi/env` (user-wide) or `<workspace>/.env.kibi` (project override), then restart long-running Kibi MCP/host processes."
+                    : `Set missing plugin secret(s) (${missingSecrets.join(", ")}) in ~/.config/kibi/env or <workspace>/.env.kibi, then restart long-running Kibi MCP/host processes.`,
+            };
+        }
+        if (legacySecrets.length > 0) {
+            return {
+                passed: true,
+                message,
+                remediation: `Migrate ${legacySecrets.join(", ")} from legacy \`.env\` to \`~/.config/kibi/env\` or \`<workspace>/.env.kibi\`, then restart long-running Kibi MCP/host processes.`,
+            };
+        }
+        return {
+            passed: true,
+            message,
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+            passed: false,
+            message,
+            remediation: "Fix package.json kibi.plugins, then restart long-running Kibi MCP or client processes.",
+        };
+    }
+}
+function formatSecretSourcePart(secret, bootstrap) {
+    return secretSourceFromBootstrap(secret, bootstrap);
+}
+/**
+ * Static first-party Jev diagnostics — mirrors plugin resolve helpers without importing.
+ */
+// implements REQ-kibi-env-bootstrap, REQ-capability-plugin-configuration-v1
+function formatJevStaticConfigParts(env = process.env) {
+    const model = env.KIBI_JEV_MODEL?.trim() || JEV_DEFAULT_MODEL;
+    const raw = env.KIBI_JEV_TIMEOUT_MS;
+    if (raw === undefined || raw.trim() === "") {
+        return [`jev.model=${model}`, "jev.timeoutMs=default"];
+    }
+    const trimmed = raw.trim();
+    if (!/^[1-9]\d*$/.test(trimmed)) {
+        return [`jev.model=${model}`, "jev.timeoutMs=invalid"];
+    }
+    const timeoutMs = Number(trimmed);
+    if (!Number.isSafeInteger(timeoutMs) ||
+        timeoutMs < 1 ||
+        timeoutMs > JEV_MAX_TIMEOUT_MS) {
+        return [`jev.model=${model}`, "jev.timeoutMs=invalid"];
+    }
+    return [`jev.model=${model}`, `jev.timeoutMs=${String(timeoutMs)}`];
+}
 function checkKbDirectory() {
     const kbDir = path.join(process.cwd(), ".kb");
     if (!existsSync(kbDir)) {
@@ -404,15 +535,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) {
@@ -424,13 +626,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) {
@@ -442,20 +644,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);
@@ -499,7 +701,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
@@ -511,8 +713,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) {
@@ -524,15 +726,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);
@@ -568,13 +770,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/engine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../src/commands/engine.ts"],"names":[],"mappings":"AAkCA,wBAAsB,mBAAmB,IAAI,OAAO,CAAC,IAAI,CAAC,CA4BzD;AAED,wBAAsB,iBAAiB,IAAI,OAAO,CAAC,IAAI,CAAC,CAWvD;AAED,wBAAsB,oBAAoB,IAAI,OAAO,CAAC,IAAI,CAAC,CAE1D;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,GAAG,CAAC,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;GAKG;AAEH,wBAAsB,oBAAoB,CACxC,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,IAAI,CAAC,CAyCf;AAED,wBAAsB,qBAAqB,IAAI,OAAO,CAAC,IAAI,CAAC,CAkB3D;AAED,wBAAsB,oBAAoB,CAAC,OAAO,EAAE;IAClD,MAAM,EAAE,MAAM,CAAC;CAChB,GAAG,OAAO,CAAC,IAAI,CAAC,CAWhB"}
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../src/commands/engine.ts"],"names":[],"mappings":"AAkCA,wBAAsB,mBAAmB,IAAI,OAAO,CAAC,IAAI,CAAC,CA4BzD;AAED,wBAAsB,iBAAiB,IAAI,OAAO,CAAC,IAAI,CAAC,CAWvD;AAED,wBAAsB,oBAAoB,IAAI,OAAO,CAAC,IAAI,CAAC,CAE1D;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,GAAG,CAAC,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;GAKG;AAEH,wBAAsB,oBAAoB,CACxC,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,IAAI,CAAC,CA2Cf;AAED,wBAAsB,qBAAqB,IAAI,OAAO,CAAC,IAAI,CAAC,CAkB3D;AAED,wBAAsB,oBAAoB,CAAC,OAAO,EAAE;IAClD,MAAM,EAAE,MAAM,CAAC;CAChB,GAAG,OAAO,CAAC,IAAI,CAAC,CAWhB"}

package/dist/commands/engine.js

@@ -96,7 +96,9 @@ export async function engineJanitorCommand(options) {
         return;
     }
     for (const finding of findings) {
-        const holder = "pid" in finding && finding.pid !== undefined ? ` pid=${finding.pid}` : "";
+        const holder = "pid" in finding && finding.pid !== undefined
+            ? ` pid=${finding.pid}`
+            : "";
         const workspace = finding.kind === "store-lock" && finding.workspaceRoot !== undefined
             ? ` workspace=${finding.workspaceRoot}`
             : "";

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

@@ -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"];

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":"AAkIA,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;AAiDD,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";
@@ -61,13 +61,17 @@ old_ref=$1
 new_ref=$2
 branch_flag=$3
 
+# File checkouts never refresh the KB; skip binary resolution so sandboxed
+# test workspaces without an installed kibi CLI can restore tracked files.
+if [ "$branch_flag" != "1" ]; then
+  exit 0
+fi
+
 ${KIBI_BIN_RESOLVER}
 
-if [ "$branch_flag" = "1" ]; then
-  # Branch stores are derived from the checked-out tracked sources. Never copy
-  # the old branch's compiled store during checkout.
-  "$KIBI_BIN" sync
-fi
+# Branch stores are derived from the checked-out tracked sources. Never copy
+# the old branch's compiled store during checkout.
+"$KIBI_BIN" sync
 `;
 const POST_MERGE_HOOK = `#!/bin/sh
 # post-merge hook for kibi
@@ -102,13 +106,14 @@ const PRE_COMMIT_HOOK = `#!/bin/sh
 # Behavior-changing source edits require staged Kibi impact evidence
 # (KB entity docs under .kb/, authored symbols metadata, or refreshed
 # symbol coordinates). Test-only and docs-only edits are exempt.
-# Refresh with:
-#   kibi sync --refresh-symbol-coordinates && git add .kb/symbol-coordinates.yaml .kb/symbols.yaml
+# Generated manifests are checked against the exact staged snapshot before
+# traceability validation. The check never stages files on the user's behalf.
 
 set -e
 
 ${KIBI_BIN_RESOLVER}
 
+"$KIBI_BIN" check-generated --staged --changed-only
 "$KIBI_BIN" check --staged
 `;
 export async function getCurrentBranch(cwd = process.cwd()) {
@@ -168,6 +173,7 @@ const CANONICAL_DERIVED_GITIGNORE_ENTRIES = [
     ".kb/briefs/",
     ".kb/migrations/",
     ".kb/usage.log",
+    ".env.kibi",
 ];
 /**
  * Pre-canonical Kibi init wrote a blanket `.kb/` fence and then
@@ -230,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;
 }