kibi-cli 2.36.0 → 2.39.0

package/dist/commands/hook-managers.d.ts

@@ -0,0 +1,43 @@
+import { type ManagedHookName } from "./init-helpers.js";
+/** Git hook managers whose configuration Kibi can print and read. */
+export declare const HOOK_MANAGER_NAMES: readonly ["lefthook", "husky", "pre-commit"];
+export type HookManagerName = (typeof HOOK_MANAGER_NAMES)[number];
+/** Formats `kibi init --print-hook` can emit. */
+export declare const HOOK_SNIPPET_FORMATS: readonly ["shell", "lefthook", "husky", "pre-commit"];
+export type HookSnippetFormat = (typeof HOOK_SNIPPET_FORMATS)[number];
+export interface DetectedHookManager {
+    name: HookManagerName;
+    /** Repository-relative file or directory that holds the hook definitions. */
+    configPath: string;
+}
+/**
+ * The hook manager that owns this repository's Git hooks, if any. Installed
+ * hook files are the strongest evidence (they show what Git runs today), then
+ * a core.hooksPath pointing into `.husky`, then a manager configuration file
+ * that has not been installed yet.
+ */
+export declare function detectHookManager(worktreeRoot: string, effectiveHooksDir: string, hooksPathConfig?: string | null): DetectedHookManager | null;
+/**
+ * The commands a hook manager runs for one Git hook, read from its
+ * configuration, or null when the manager does not define that hook (or its
+ * configuration cannot be read).
+ */
+export declare function hookManagerCommands(manager: HookManagerName, worktreeRoot: string, hook: ManagedHookName): string[] | null;
+/** Labels of the Kibi commands a hook definition never visibly runs. */
+export declare function missingKibiHookCommands(hook: ManagedHookName, scripts: readonly string[]): string[];
+/**
+ * Configuration that wires the given hooks to the commands Kibi's managed
+ * templates run, in a hook manager's own format. `shell` and `husky` print
+ * the hook-script snippets of `kibi init --print-hook`.
+ */
+export declare function hookManagerSnippet(format: HookSnippetFormat, hooks: readonly ManagedHookName[]): string;
+export interface HookManagerCoverage {
+    hook: ManagedHookName;
+    /** Kibi commands the manager's definition of this hook does not visibly run. */
+    missing: string[];
+    /** Whether the manager defines the hook at all. */
+    configured: boolean;
+}
+/** What each Kibi-managed hook looks like in the manager's configuration. */
+export declare function hookManagerCoverage(manager: HookManagerName, worktreeRoot: string): HookManagerCoverage[];
+//# sourceMappingURL=hook-managers.d.ts.map

package/dist/commands/hook-managers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hook-managers.d.ts","sourceRoot":"","sources":["../../src/commands/hook-managers.ts"],"names":[],"mappings":"AAqBA,OAAO,EAEL,KAAK,eAAe,EAErB,MAAM,mBAAmB,CAAC;AAE3B,qEAAqE;AACrE,eAAO,MAAM,kBAAkB,8CAA+C,CAAC;AAE/E,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,kBAAkB,CAAC,CAAC,MAAM,CAAC,CAAC;AAElE,iDAAiD;AACjD,eAAO,MAAM,oBAAoB,uDAA4C,CAAC;AAE9E,MAAM,MAAM,iBAAiB,GAAG,CAAC,OAAO,oBAAoB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEtE,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,eAAe,CAAC;IACtB,6EAA6E;IAC7E,UAAU,EAAE,MAAM,CAAC;CACpB;AAqGD;;;;;GAKG;AAEH,wBAAgB,iBAAiB,CAC/B,YAAY,EAAE,MAAM,EACpB,iBAAiB,EAAE,MAAM,EACzB,eAAe,GAAE,MAAM,GAAG,IAAW,GACpC,mBAAmB,GAAG,IAAI,CAwB5B;AAmID;;;;GAIG;AAEH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,eAAe,EACxB,YAAY,EAAE,MAAM,EACpB,IAAI,EAAE,eAAe,GACpB,MAAM,EAAE,GAAG,IAAI,CAWjB;AAkED,wEAAwE;AAExE,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,eAAe,EACrB,OAAO,EAAE,SAAS,MAAM,EAAE,GACzB,MAAM,EAAE,CAKV;AAsFD;;;;GAIG;AAEH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,iBAAiB,EACzB,KAAK,EAAE,SAAS,eAAe,EAAE,GAChC,MAAM,CAiBR;AAED,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,eAAe,CAAC;IACtB,gFAAgF;IAChF,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,mDAAmD;IACnD,UAAU,EAAE,OAAO,CAAC;CACrB;AAED,6EAA6E;AAE7E,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,eAAe,EACxB,YAAY,EAAE,MAAM,GACnB,mBAAmB,EAAE,CASvB"}

package/dist/commands/hook-managers.js

@@ -0,0 +1,426 @@
+/*
+ Kibi — repo-local, per-branch, queryable long-term memory for software projects
+ Copyright (C) 2026 Piotr Franczyk
+
+ This program is free software: you can redistribute it and/or modify
+ it under the terms of the GNU Affero General Public License as published by
+ the Free Software Foundation, either version 3 of the License, or
+ (at your option) any later version.
+
+ This program is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ GNU Affero General Public License for more details.
+
+ 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 { readFileSync, statSync } from "node:fs";
+import * as path from "node:path";
+import { parse as parseYaml } from "yaml";
+import { MANAGED_HOOK_NAMES, hookDelegationSnippet, } from "./init-helpers.js";
+/** Git hook managers whose configuration Kibi can print and read. */
+export const HOOK_MANAGER_NAMES = ["lefthook", "husky", "pre-commit"];
+/** Formats `kibi init --print-hook` can emit. */
+export const HOOK_SNIPPET_FORMATS = ["shell", ...HOOK_MANAGER_NAMES];
+// lefthook reads the first of these it finds; the -local variants are merged
+// on top of the main file.
+const LEFTHOOK_CONFIG_FILES = [
+    "lefthook.yml",
+    ".lefthook.yml",
+    "lefthook.yaml",
+    ".lefthook.yaml",
+    "lefthook.json",
+    ".lefthook.json",
+    "lefthook.jsonc",
+    ".lefthook.jsonc",
+    "lefthook.toml",
+    ".lefthook.toml",
+    ".config/lefthook.yml",
+    ".config/lefthook.yaml",
+];
+const LEFTHOOK_LOCAL_CONFIG_FILES = [
+    "lefthook-local.yml",
+    ".lefthook-local.yml",
+    "lefthook-local.yaml",
+    ".lefthook-local.yaml",
+    "lefthook-local.json",
+    ".lefthook-local.json",
+];
+const PRE_COMMIT_CONFIG_FILE = ".pre-commit-config.yaml";
+const HUSKY_DIR = ".husky";
+/** Hooks in the order a reader expects them: the commit gate first. */
+const PRINT_ORDER = [
+    "pre-commit",
+    "post-checkout",
+    "post-merge",
+    "post-rewrite",
+];
+// The local runner every Node.js install ships with. `--no-install` never
+// downloads a kibi outside the project lockfile.
+const KIBI_COMMAND = "npx --no-install kibi";
+function isFile(filePath) {
+    try {
+        return statSync(filePath).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+function isDirectory(filePath) {
+    try {
+        return statSync(filePath).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+function readText(filePath) {
+    try {
+        return readFileSync(filePath, "utf8");
+    }
+    catch {
+        return null;
+    }
+}
+function firstExisting(root, candidates) {
+    return candidates.find((file) => isFile(path.join(root, file))) ?? null;
+}
+/**
+ * Which manager generated a hook file, from the marker text each one emits.
+ * husky is recognized by core.hooksPath instead: its hook files are the
+ * project's own scripts, which may mention husky without being generated.
+ */
+function hookFileManager(content) {
+    if (content.includes("File generated by pre-commit"))
+        return "pre-commit";
+    if (/\blefthook\b/.test(content))
+        return "lefthook";
+    return null;
+}
+function managerConfigPath(worktreeRoot, name) {
+    switch (name) {
+        case "lefthook":
+            return (firstExisting(worktreeRoot, LEFTHOOK_CONFIG_FILES) ?? "lefthook.yml");
+        case "husky":
+            return HUSKY_DIR;
+        case "pre-commit":
+            return PRE_COMMIT_CONFIG_FILE;
+    }
+}
+/**
+ * The hook manager that owns this repository's Git hooks, if any. Installed
+ * hook files are the strongest evidence (they show what Git runs today), then
+ * a core.hooksPath pointing into `.husky`, then a manager configuration file
+ * that has not been installed yet.
+ */
+// implements REQ-git-hook-manager-integration
+export function detectHookManager(worktreeRoot, effectiveHooksDir, hooksPathConfig = null) {
+    const found = (name) => ({
+        name,
+        configPath: managerConfigPath(worktreeRoot, name),
+    });
+    for (const hook of MANAGED_HOOK_NAMES) {
+        const content = readText(path.join(effectiveHooksDir, hook));
+        const manager = content === null ? null : hookFileManager(content);
+        if (manager)
+            return found(manager);
+    }
+    if (hooksPathConfig !== null &&
+        /(?:^|[\\/])\.husky(?:[\\/]_)?[\\/]?$/.test(hooksPathConfig.trim())) {
+        return found("husky");
+    }
+    if (firstExisting(worktreeRoot, LEFTHOOK_CONFIG_FILES)) {
+        return found("lefthook");
+    }
+    if (isDirectory(path.join(worktreeRoot, HUSKY_DIR)))
+        return found("husky");
+    if (isFile(path.join(worktreeRoot, PRE_COMMIT_CONFIG_FILE))) {
+        return found("pre-commit");
+    }
+    return null;
+}
+function parseConfig(filePath) {
+    const text = readText(filePath);
+    if (text === null)
+        return undefined;
+    try {
+        return parseYaml(text);
+    }
+    catch {
+        return undefined;
+    }
+}
+function asRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : null;
+}
+/**
+ * Every shell command lefthook runs for one hook: `run` strings of commands
+ * and jobs (including nested groups), plus the contents of the scripts it
+ * executes from `.lefthook/<hook>/`.
+ */
+function lefthookRuns(node, scriptDir, commands) {
+    if (Array.isArray(node)) {
+        for (const item of node)
+            lefthookRuns(item, scriptDir, commands);
+        return;
+    }
+    const record = asRecord(node);
+    if (!record)
+        return;
+    for (const [key, value] of Object.entries(record)) {
+        if (key === "run" && typeof value === "string") {
+            commands.push(value);
+        }
+        else if (key === "script" && typeof value === "string") {
+            const script = readText(path.join(scriptDir, value));
+            if (script !== null)
+                commands.push(script);
+        }
+        else if (key === "scripts" && asRecord(value)) {
+            for (const name of Object.keys(value)) {
+                const script = readText(path.join(scriptDir, name));
+                if (script !== null)
+                    commands.push(script);
+            }
+        }
+        else {
+            lefthookRuns(value, scriptDir, commands);
+        }
+    }
+}
+function lefthookCommands(worktreeRoot, hook) {
+    const main = firstExisting(worktreeRoot, LEFTHOOK_CONFIG_FILES);
+    const files = [
+        ...(main ? [main] : []),
+        ...LEFTHOOK_LOCAL_CONFIG_FILES.filter((file) => isFile(path.join(worktreeRoot, file))),
+    ];
+    let configured = false;
+    const commands = [];
+    for (const file of files) {
+        // TOML configs are not read; their hooks count as not visible.
+        const hookNode = asRecord(parseConfig(path.join(worktreeRoot, file)))?.[hook];
+        if (hookNode === undefined || hookNode === null)
+            continue;
+        configured = true;
+        lefthookRuns(hookNode, path.join(worktreeRoot, ".lefthook", hook), commands);
+    }
+    return configured ? commands : null;
+}
+// pre-commit stage names before 3.2 dropped the `pre-` prefix.
+const LEGACY_PRE_COMMIT_STAGES = {
+    commit: "pre-commit",
+    push: "pre-push",
+    "merge-commit": "pre-merge-commit",
+};
+function preCommitFrameworkCommands(worktreeRoot, hook) {
+    const config = asRecord(parseConfig(path.join(worktreeRoot, PRE_COMMIT_CONFIG_FILE)));
+    if (!config || !Array.isArray(config.repos))
+        return null;
+    const defaultStages = Array.isArray(config.default_stages)
+        ? config.default_stages
+        : null;
+    let configured = false;
+    const commands = [];
+    for (const repo of config.repos) {
+        const hooks = asRecord(repo)?.hooks;
+        if (!Array.isArray(hooks))
+            continue;
+        for (const entry of hooks) {
+            const definition = asRecord(entry);
+            if (!definition)
+                continue;
+            const stages = Array.isArray(definition.stages)
+                ? definition.stages
+                : defaultStages;
+            const runsHere = stages === null
+                ? hook === "pre-commit"
+                : stages.some((stage) => typeof stage === "string" &&
+                    (LEGACY_PRE_COMMIT_STAGES[stage] ?? stage) === hook);
+            if (!runsHere)
+                continue;
+            configured = true;
+            // Only local hooks carry a shell entry; remote hooks are opaque here.
+            if (typeof definition.entry === "string") {
+                const args = Array.isArray(definition.args)
+                    ? definition.args.filter((arg) => typeof arg === "string")
+                    : [];
+                commands.push([definition.entry, ...args].join(" "));
+            }
+        }
+    }
+    return configured ? commands : null;
+}
+/**
+ * The commands a hook manager runs for one Git hook, read from its
+ * configuration, or null when the manager does not define that hook (or its
+ * configuration cannot be read).
+ */
+// implements REQ-git-hook-manager-integration
+export function hookManagerCommands(manager, worktreeRoot, hook) {
+    switch (manager) {
+        case "lefthook":
+            return lefthookCommands(worktreeRoot, hook);
+        case "husky": {
+            const script = readText(path.join(worktreeRoot, HUSKY_DIR, hook));
+            return script === null ? null : [script];
+        }
+        case "pre-commit":
+            return preCommitFrameworkCommands(worktreeRoot, hook);
+    }
+}
+/**
+ * Individual shell commands of a hook script, ignoring comments. Lines are
+ * split on command separators so `a && b` counts as two commands.
+ */
+function splitShellCommands(content) {
+    return content
+        .split("\n")
+        .filter((line) => !line.trimStart().startsWith("#"))
+        .flatMap((line) => line.split(/&&|\|\||;|\|/))
+        .map((command) => command.trim())
+        .filter((command) => command.length > 0);
+}
+// Matches `kibi <sub>`, `npx kibi <sub>`, `node_modules/.bin/kibi <sub>` and
+// the template's `"$KIBI_BIN" <sub>`.
+function invokesKibi(command, subcommand) {
+    return new RegExp(`(?:\\bkibi|\\bKIBI_BIN)["'}]*\\s+${subcommand}(?=[\\s"']|$)`).test(command);
+}
+// A flag ends at whitespace, a closing quote (`sh -c '... --staged'`) or the
+// end of the command.
+function hasFlag(command, flag) {
+    return new RegExp(`\\s${flag}(?=[\\s"']|$)`).test(command);
+}
+/** The commands each Kibi-managed hook template runs. */
+const KIBI_HOOK_DELEGATIONS = (() => {
+    const sync = [
+        {
+            label: "kibi sync",
+            matches: (command) => invokesKibi(command, "sync"),
+        },
+    ];
+    return {
+        "pre-commit": [
+            {
+                label: "kibi check-generated --staged --changed-only",
+                matches: (command) => invokesKibi(command, "check-generated") &&
+                    hasFlag(command, "--staged") &&
+                    hasFlag(command, "--changed-only"),
+            },
+            {
+                label: "kibi check --staged",
+                matches: (command) => invokesKibi(command, "check") && hasFlag(command, "--staged"),
+            },
+        ],
+        "post-checkout": sync,
+        "post-merge": sync,
+        "post-rewrite": sync,
+    };
+})();
+/** Labels of the Kibi commands a hook definition never visibly runs. */
+// implements REQ-git-hook-manager-integration
+export function missingKibiHookCommands(hook, scripts) {
+    const commands = scripts.flatMap(splitShellCommands);
+    return KIBI_HOOK_DELEGATIONS[hook]
+        .filter((delegation) => !commands.some(delegation.matches))
+        .map((delegation) => delegation.label);
+}
+function ordered(hooks) {
+    return PRINT_ORDER.filter((hook) => hooks.includes(hook));
+}
+// Runs in lefthook's shell, where {N} is the Nth Git hook argument.
+const LEFTHOOK_RUNS = {
+    "pre-commit": `${KIBI_COMMAND} check-generated --staged --changed-only && ${KIBI_COMMAND} check --staged`,
+    "post-checkout": `if [ "{3}" = "1" ]; then ${KIBI_COMMAND} sync; fi`,
+    "post-merge": `${KIBI_COMMAND} sync`,
+    "post-rewrite": `if [ "{1}" = "rebase" ]; then ${KIBI_COMMAND} sync; fi`,
+};
+function lefthookSnippet(hooks) {
+    const lines = [
+        "# Kibi git hook commands for lefthook. Merge these entries into your",
+        "# lefthook.yml (keep your existing commands), then run 'lefthook install'.",
+    ];
+    for (const hook of hooks) {
+        lines.push(`${hook}:`, "  commands:");
+        if (hook === "post-checkout") {
+            lines.push("    # {3} is 1 for a branch checkout, 0 for a file checkout.");
+        }
+        lines.push(`    ${hook === "pre-commit" ? "kibi-check" : "kibi-sync"}:`, `      run: ${LEFTHOOK_RUNS[hook]}`);
+    }
+    return `${lines.join("\n")}\n`;
+}
+// pre-commit exposes post-checkout and post-rewrite arguments as variables.
+const PRE_COMMIT_FRAMEWORK_HOOKS = {
+    "pre-commit": {
+        id: "kibi-check",
+        name: "kibi check --staged",
+        entry: `sh -c '${KIBI_COMMAND} check-generated --staged --changed-only && ${KIBI_COMMAND} check --staged'`,
+    },
+    "post-checkout": {
+        id: "kibi-sync-checkout",
+        name: "kibi sync (branch checkout)",
+        entry: `sh -c 'if [ "$PRE_COMMIT_CHECKOUT_TYPE" = "1" ]; then ${KIBI_COMMAND} sync; fi'`,
+    },
+    "post-merge": {
+        id: "kibi-sync-merge",
+        name: "kibi sync (merge)",
+        entry: `${KIBI_COMMAND} sync`,
+    },
+    "post-rewrite": {
+        id: "kibi-sync-rebase",
+        name: "kibi sync (rebase)",
+        entry: `sh -c 'if [ "$PRE_COMMIT_REWRITE_COMMAND" = "rebase" ]; then ${KIBI_COMMAND} sync; fi'`,
+    },
+};
+function preCommitFrameworkSnippet(hooks) {
+    const lines = [
+        "# Kibi git hooks for the pre-commit framework. Merge into your",
+        "# .pre-commit-config.yaml (add the hook types to any existing",
+        "# default_install_hook_types and the hooks to a local repo), then run",
+        `# 'pre-commit install'.`,
+        `default_install_hook_types: [${hooks.join(", ")}]`,
+        "repos:",
+        "  - repo: local",
+        "    hooks:",
+    ];
+    for (const hook of hooks) {
+        const definition = PRE_COMMIT_FRAMEWORK_HOOKS[hook];
+        lines.push(`      - id: ${definition.id}`, `        name: ${definition.name}`, `        entry: ${definition.entry}`, "        language: system", "        pass_filenames: false", "        always_run: true", `        stages: [${hook}]`);
+    }
+    return `${lines.join("\n")}\n`;
+}
+/**
+ * Configuration that wires the given hooks to the commands Kibi's managed
+ * templates run, in a hook manager's own format. `shell` and `husky` print
+ * the hook-script snippets of `kibi init --print-hook`.
+ */
+// implements REQ-git-hook-manager-integration
+export function hookManagerSnippet(format, hooks) {
+    const selected = ordered(hooks);
+    switch (format) {
+        case "shell":
+            return selected.map(hookDelegationSnippet).join("\n");
+        case "husky":
+            return selected
+                .map((hook) => `# --- ${HUSKY_DIR}/${hook} ---\n${hookDelegationSnippet(hook)}`)
+                .join("\n");
+        case "lefthook":
+            return lefthookSnippet(selected);
+        case "pre-commit":
+            return preCommitFrameworkSnippet(selected);
+    }
+}
+/** What each Kibi-managed hook looks like in the manager's configuration. */
+// implements REQ-git-hook-manager-integration
+export function hookManagerCoverage(manager, worktreeRoot) {
+    return ordered(MANAGED_HOOK_NAMES).map((hook) => {
+        const commands = hookManagerCommands(manager, worktreeRoot, hook);
+        return {
+            hook,
+            configured: commands !== null,
+            missing: missingKibiHookCommands(hook, commands ?? []),
+        };
+    });
+}

package/dist/commands/init.d.ts

@@ -3,6 +3,7 @@ interface InitOptions {
     github?: boolean;
     badgeOnly?: boolean;
     printHook?: string;
+    format?: string;
 }
 export declare function initCommand(options: InitOptions): Promise<{
     exitCode: number;

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

@@ -1 +1 @@
-{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../src/commands/init.ts"],"names":[],"mappings":"AAuGA,UAAU,WAAW;IACnB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAoDD,wBAAsB,WAAW,CAC/B,OAAO,EAAE,WAAW,GACnB,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CAgK/B"}
+{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../src/commands/init.ts"],"names":[],"mappings":"AA8GA,UAAU,WAAW;IACnB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAkFD,wBAAsB,WAAW,CAC/B,OAAO,EAAE,WAAW,GACnB,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CA0L/B"}

package/dist/commands/init.js

@@ -24,7 +24,8 @@ import { resolveBranchAttachment } from "../utils/branch-resolver.js";
 import { readLegacyKbConfig } from "../utils/config.js";
 import { resolveGitRepository, } from "../utils/git-repository-context.js";
 import { scaffoldGitHubIntegration } from "./github-init.js";
-import { MANAGED_HOOK_NAMES, copySchemaFiles, createKbDirectoryStructure, createManifestFile, ensureSymbolsManifestFile, hookDelegationSnippet, installGitHooks, isManagedHookName, updateGitIgnore, } from "./init-helpers.js";
+import { HOOK_SNIPPET_FORMATS, detectHookManager, hookManagerCoverage, hookManagerSnippet, } from "./hook-managers.js";
+import { MANAGED_HOOK_NAMES, copySchemaFiles, createKbDirectoryStructure, createManifestFile, ensureSymbolsManifestFile, installGitHooks, isManagedHookName, updateGitIgnore, } from "./init-helpers.js";
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 /**
@@ -83,6 +84,24 @@ function isRepositoryManagedHooksDir(context) {
     // directory, which can sit outside the current worktree root.
     return isWithin(hooksDir, commonGitDir) || isWithin(hooksDir, worktreeRoot);
 }
+/**
+ * Hooks owned by a hook manager are left to it: Kibi installs nothing into
+ * the hooks directory and prints the manager configuration that runs Kibi's
+ * commands for every hook the manager does not visibly cover yet.
+ */
+// implements REQ-git-hook-manager-integration
+function reportHookManager(manager, worktreeRoot) {
+    const gaps = hookManagerCoverage(manager.name, worktreeRoot).filter((entry) => entry.missing.length > 0);
+    const owner = `Git hooks are managed by ${manager.name} (${manager.configPath})`;
+    if (gaps.length === 0) {
+        console.log(`✓ ${owner}, which already runs Kibi's hook commands; Kibi installed no hooks of its own.`);
+        return;
+    }
+    const hooks = gaps.map((entry) => entry.hook);
+    console.log(`! ${owner}; Kibi installed no hooks of its own. ${manager.configPath} does not visibly run Kibi's commands for: ${hooks.join(", ")}. Add this (running the same commands through a task runner or script works too), or Kibi enforcement stays OFF for those hooks:\n`);
+    console.log(hookManagerSnippet(manager.name, hooks));
+    console.log(`  Print it again with: kibi init --print-hook ${hooks.length === 1 ? hooks[0] : "all"} --format ${manager.name}`);
+}
 async function initNextAction(projectRoot) {
     const sourceFiles = await nodeFilesystem.glob([
         ".kb/requirements/**/*.md",
@@ -121,15 +140,25 @@ async function initNextAction(projectRoot) {
 // implements REQ-cli-init
 // implements REQ-kibi-github-report-integration
 export async function initCommand(options) {
+    if (options.format !== undefined && options.printHook === undefined) {
+        console.error("Error: --format applies only to --print-hook.");
+        return { exitCode: 1 };
+    }
     if (options.printHook !== undefined) {
         // Print-only mode: emit a delegation snippet for a hook Kibi does not
         // own and touch nothing, not even the repository context.
-        // implements REQ-git-hook-effective-install
-        if (!isManagedHookName(options.printHook)) {
-            console.error(`Error: unknown hook '${options.printHook}' for --print-hook. Expected one of: ${MANAGED_HOOK_NAMES.join(", ")}.`);
+        // implements REQ-git-hook-effective-install, REQ-git-hook-manager-integration
+        const printHook = options.printHook;
+        if (printHook !== "all" && !isManagedHookName(printHook)) {
+            console.error(`Error: unknown hook '${printHook}' for --print-hook. Expected one of: ${MANAGED_HOOK_NAMES.join(", ")}, all.`);
+            return { exitCode: 1 };
+        }
+        const format = options.format ?? "shell";
+        if (!HOOK_SNIPPET_FORMATS.includes(format)) {
+            console.error(`Error: unknown --format '${format}' for --print-hook. Expected one of: ${HOOK_SNIPPET_FORMATS.join(", ")}.`);
             return { exitCode: 1 };
         }
-        process.stdout.write(hookDelegationSnippet(options.printHook));
+        process.stdout.write(hookManagerSnippet(format, printHook === "all" ? MANAGED_HOOK_NAMES : [printHook]));
         return { exitCode: 0 };
     }
     if (options.badgeOnly === true && options.github !== true) {
@@ -202,9 +231,15 @@ export async function initCommand(options) {
             ensureSymbolsManifestFile(projectRoot);
         }
         if (options.hooks) {
+            const manager = repoContext
+                ? detectHookManager(repoContext.worktreeRoot, repoContext.effectiveHooksDir, repoContext.hooksPathConfig)
+                : null;
             if (!repoContext) {
                 console.error("Warning: No git repository found, skipping hooks");
             }
+            else if (manager) {
+                reportHookManager(manager, repoContext.worktreeRoot);
+            }
             else if (!isRepositoryManagedHooksDir(repoContext)) {
                 // core.hooksPath is only the culprit when it is configured; the
                 // default hooks directory can also escape the repository through a

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

@@ -1 +1 @@
-{"version":3,"file":"migrate.d.ts","sourceRoot":"","sources":["../../src/commands/migrate.ts"],"names":[],"mappings":"AAmEA,OAAO,KAAK,EACV,eAAe,EAGhB,MAAM,wCAAwC,CAAC;AAwBhD,UAAU,cAAc;IACtB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IAC1B,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,iBAAiB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC7B,uFAAuF;IACvF,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,6EAA6E;IAC7E,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,qFAAqF;IACrF,uBAAuB,CAAC,EAAE,OAAO,CAAC;CACnC;AAED,MAAM,WAAW,oBAAoB;IACnC,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB,uBAAuB,EAAE,SAAS,GAAG,WAAW,GAAG,gBAAgB,GAAG,IAAI,CAAC;IAC3E,MAAM,EAAE,SAAS,CAAC;IAClB,4BAA4B,EAAE,MAAM,CAAC;IACrC,8EAA8E;IAC9E,oBAAoB,EAAE,MAAM,CAAC;IAC7B,8DAA8D;IAC9D,4BAA4B,EAAE,MAAM,CAAC;IACrC,sEAAsE;IACtE,oBAAoB,EAAE,MAAM,CAAC;IAC7B,4FAA4F;IAC5F,kBAAkB,EAAE,MAAM,CAAC;IAC3B,wHAAwH;IACxH,oBAAoB,EAAE,MAAM,CAAC;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,oEAAoE;IACpE,mBAAmB,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;CAC1B;AAED,iFAAiF;AACjF,MAAM,WAAW,mBAAmB;IAClC,kEAAkE;IAClE,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,oBAAoB,CAAC;IAC5B,0EAA0E;IAC1E,gBAAgB,EAAE,OAAO,CAAC;CAC3B;AAqLD,wBAAgB,mBAAmB,CACjC,gBAAgB,EAAE,OAAO,EACzB,UAAU,EAAE,MAAM,GAAG,IAAI,GACxB,MAAM,CAUR;AAwXD,wBAAgB,+BAA+B,IAAI;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,CAKtE;AAGD,wBAAsB,cAAc,CAClC,OAAO,GAAE,cAAmB,GAC3B,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,mBAAmB,CAAA;CAAE,CAAC,CAgkB9D;AAED;;;;GAIG;AAEH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,mBAAmB,GAAG,MAAM,CAGzE;AA8YD;;;;;GAKG;AAEH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,IAAI,CAAC,eAAe,EAAE,MAAM,CAAC,GACpC,OAAO,CAOT"}
+{"version":3,"file":"migrate.d.ts","sourceRoot":"","sources":["../../src/commands/migrate.ts"],"names":[],"mappings":"AAmEA,OAAO,KAAK,EACV,eAAe,EAGhB,MAAM,wCAAwC,CAAC;AAyBhD,UAAU,cAAc;IACtB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IAC1B,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,iBAAiB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC7B,uFAAuF;IACvF,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,6EAA6E;IAC7E,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,qFAAqF;IACrF,uBAAuB,CAAC,EAAE,OAAO,CAAC;CACnC;AAED,MAAM,WAAW,oBAAoB;IACnC,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB,uBAAuB,EAAE,SAAS,GAAG,WAAW,GAAG,gBAAgB,GAAG,IAAI,CAAC;IAC3E,MAAM,EAAE,SAAS,CAAC;IAClB,4BAA4B,EAAE,MAAM,CAAC;IACrC,8EAA8E;IAC9E,oBAAoB,EAAE,MAAM,CAAC;IAC7B,8DAA8D;IAC9D,4BAA4B,EAAE,MAAM,CAAC;IACrC,sEAAsE;IACtE,oBAAoB,EAAE,MAAM,CAAC;IAC7B,4FAA4F;IAC5F,kBAAkB,EAAE,MAAM,CAAC;IAC3B,wHAAwH;IACxH,oBAAoB,EAAE,MAAM,CAAC;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,oEAAoE;IACpE,mBAAmB,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;CAC1B;AAED,iFAAiF;AACjF,MAAM,WAAW,mBAAmB;IAClC,kEAAkE;IAClE,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,oBAAoB,CAAC;IAC5B,0EAA0E;IAC1E,gBAAgB,EAAE,OAAO,CAAC;CAC3B;AAqLD,wBAAgB,mBAAmB,CACjC,gBAAgB,EAAE,OAAO,EACzB,UAAU,EAAE,MAAM,GAAG,IAAI,GACxB,MAAM,CAUR;AAwXD,wBAAgB,+BAA+B,IAAI;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,CAKtE;AAGD,wBAAsB,cAAc,CAClC,OAAO,GAAE,cAAmB,GAC3B,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,mBAAmB,CAAA;CAAE,CAAC,CAgkB9D;AAED;;;;GAIG;AAEH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,mBAAmB,GAAG,MAAM,CAGzE;AAoZD;;;;;GAKG;AAEH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,IAAI,CAAC,eAAe,EAAE,MAAM,CAAC,GACpC,OAAO,CAOT"}

package/dist/commands/migrate.js

@@ -27,6 +27,7 @@ import { applySourcePathRepairs, findSourceRepairs, } from "../operations/migrat
 import { applySupersededClosures, planSupersededClosures, } from "../operations/migration/superseded-closure.js";
 import { coordinateRefreshFailureMessage, readGeneratedManifestBytes, refreshCoordinatesAfterMigration, } from "../operations/migration/symbol-coordinates-refresh.js";
 import { applySymbolLegacyLinks, planSymbolLegacyLinks, } from "../operations/migration/symbol-legacy-links.js";
+import { noteCliErrorCategory } from "../usage-telemetry.js";
 import { resolveBranchAttachment } from "../utils/branch-resolver.js";
 import { defaultKbManifest, readKbManifest, readKbManifestStatus, writeKbManifest, } from "../utils/kb-manifest.js";
 import { CANONICAL_ENTITY_PATHS, KB_PATHS } from "../utils/kb-paths.js";
@@ -1067,11 +1068,13 @@ async function migratePlanCommand(options) {
             ? plan.planHash
             : options.approvedPlanHash;
         if (!approvedPlanHash) {
-            console.error("--apply-safe requires --approved-plan-hash <sha256>.");
+            noteCliErrorCategory("migrate:approved_plan_hash_missing");
+            console.error(`--apply-safe requires --approved-plan-hash <sha256>. Review the plan with 'kibi migrate', then approve its current hash: kibi migrate --apply-safe --approved-plan-hash ${plan.planHash}`);
             return { exitCode: 2 };
         }
         if (approvedPlanHash !== plan.planHash) {
-            console.error("Migration plan changed; regenerate the plan and approve its current hash.");
+            noteCliErrorCategory("migrate:plan_hash_changed");
+            console.error(`Migration plan changed; regenerate the plan and approve its current hash: kibi migrate --apply-safe --approved-plan-hash ${plan.planHash}`);
             return { exitCode: 2 };
         }
         const explicitActionIds = approveWholePlan
@@ -1109,8 +1112,11 @@ async function migratePlanCommand(options) {
             console.log(result.content[0]?.text ?? "Migration applied.");
             printApplySummary(result.structuredContent);
         }
+        const outcome = result.structuredContent?.outcome;
+        if (outcome !== "applied")
+            noteCliErrorCategory(`migrate:${outcome}`);
         return {
-            exitCode: result.structuredContent?.outcome === "applied" ? 0 : 1,
+            exitCode: outcome === "applied" ? 0 : 1,
         };
     }
     if (options.format === "json") {

package/dist/commands/sync/persistence.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"persistence.d.ts","sourceRoot":"","sources":["../../../src/commands/sync/persistence.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EAEV,qBAAqB,EACrB,gBAAgB,EACjB,MAAM,8BAA8B,CAAC;AACtC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AA4HrD,MAAM,WAAW,iBAAiB;IAChC,WAAW,EAAE,MAAM,CAAC;IACpB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,UAAU,EAAE,OAAO,CAAC;CACrB;AAuFD,iFAAiF;AACjF,wBAAsB,yBAAyB,CAC7C,MAAM,EAAE,aAAa,EACrB,WAAW,EAAE,SAAS,MAAM,EAAE,GAC7B,OAAO,CAAC,MAAM,CAAC,CA+BjB;AAED,0EAA0E;AAC1E,wBAAsB,mBAAmB,CACvC,MAAM,EAAE,aAAa,EACrB,SAAS,EAAE,SAAS,MAAM,EAAE,GAC3B,OAAO,CAAC,MAAM,CAAC,CAmBjB;AAED,8EAA8E;AAC9E,wBAAsB,8BAA8B,CAClD,MAAM,EAAE,aAAa,EACrB,SAAS,EAAE,SAAS,MAAM,EAAE,GAC3B,OAAO,CAAC,IAAI,CAAC,CAoBf;AAED,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,aAAa,EACrB,aAAa,EAAE,SAAS,qBAAqB,EAAE,GAC9C,OAAO,CAAC,MAAM,CAAC,CAuBjB;AAmCD,6EAA6E;AAE7E,MAAM,MAAM,WAAW,GAAG,QAAQ,CAAC;IACjC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,aAAa,EAAE,MAAM,CAAC;CACvB,CAAC,CAAC;AAEH;;;GAGG;AAEH,wBAAsB,gBAAgB,CACpC,MAAM,EAAE,IAAI,CAAC,aAAa,EAAE,OAAO,CAAC,GACnC,OAAO,CAAC,WAAW,GAAG,SAAS,CAAC,CAmBlC;AAED,wBAAsB,eAAe,CAEnC,MAAM,EAAE,aAAa,EACrB,OAAO,EAAE,gBAAgB,EAAE,EAC3B,SAAS,EAAE,GAAG,CAAC,MAAM,CAAC,EACtB,OAAO,GAAE;IAAE,qBAAqB,CAAC,EAAE,OAAO,CAAA;CAAO,GAChD,OAAO,CAAC;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,OAAO,CAAA;CAAE,CAAC,CAyRvD;AA4BD,wBAAgB,0BAA0B,CACxC,WAAW,EAAE,MAAM,GAAG,SAAS,EAC/B,UAAU,EAAE,MAAM,GAAG,SAAS,GAC7B,MAAM,CAER;AAGD,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,aAAa,EACrB,OAAO,EAAE,gBAAgB,EAAE,EAC3B,kBAAkB,EAAE,qBAAqB,EAAE,EAC3C,OAAO,GAAE;IAAE,aAAa,CAAC,EAAE,MAAM,CAAA;CAAO,GACvC,OAAO,CAAC;IAAE,iBAAiB,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,OAAO,CAAA;CAAE,CAAC,CA0O7D"}
+{"version":3,"file":"persistence.d.ts","sourceRoot":"","sources":["../../../src/commands/sync/persistence.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EAEV,qBAAqB,EACrB,gBAAgB,EACjB,MAAM,8BAA8B,CAAC;AACtC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAgIrD,MAAM,WAAW,iBAAiB;IAChC,WAAW,EAAE,MAAM,CAAC;IACpB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,UAAU,EAAE,OAAO,CAAC;CACrB;AA0HD,iFAAiF;AACjF,wBAAsB,yBAAyB,CAC7C,MAAM,EAAE,aAAa,EACrB,WAAW,EAAE,SAAS,MAAM,EAAE,GAC7B,OAAO,CAAC,MAAM,CAAC,CA+BjB;AAED,0EAA0E;AAC1E,wBAAsB,mBAAmB,CACvC,MAAM,EAAE,aAAa,EACrB,SAAS,EAAE,SAAS,MAAM,EAAE,GAC3B,OAAO,CAAC,MAAM,CAAC,CAmBjB;AAED,8EAA8E;AAC9E,wBAAsB,8BAA8B,CAClD,MAAM,EAAE,aAAa,EACrB,SAAS,EAAE,SAAS,MAAM,EAAE,GAC3B,OAAO,CAAC,IAAI,CAAC,CAoBf;AAED,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,aAAa,EACrB,aAAa,EAAE,SAAS,qBAAqB,EAAE,GAC9C,OAAO,CAAC,MAAM,CAAC,CAuBjB;AAmCD,6EAA6E;AAE7E,MAAM,MAAM,WAAW,GAAG,QAAQ,CAAC;IACjC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,aAAa,EAAE,MAAM,CAAC;CACvB,CAAC,CAAC;AAEH;;;GAGG;AAEH,wBAAsB,gBAAgB,CACpC,MAAM,EAAE,IAAI,CAAC,aAAa,EAAE,OAAO,CAAC,GACnC,OAAO,CAAC,WAAW,GAAG,SAAS,CAAC,CAmBlC;AAED,wBAAsB,eAAe,CAEnC,MAAM,EAAE,aAAa,EACrB,OAAO,EAAE,gBAAgB,EAAE,EAC3B,SAAS,EAAE,GAAG,CAAC,MAAM,CAAC,EACtB,OAAO,GAAE;IAAE,qBAAqB,CAAC,EAAE,OAAO,CAAA;CAAO,GAChD,OAAO,CAAC;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,OAAO,CAAA;CAAE,CAAC,CA2RvD;AA4BD,wBAAgB,0BAA0B,CACxC,WAAW,EAAE,MAAM,GAAG,SAAS,EAC/B,UAAU,EAAE,MAAM,GAAG,SAAS,GAC7B,MAAM,CAER;AAGD,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,aAAa,EACrB,OAAO,EAAE,gBAAgB,EAAE,EAC3B,kBAAkB,EAAE,qBAAqB,EAAE,EAC3C,OAAO,GAAE;IAAE,aAAa,CAAC,EAAE,MAAM,CAAA;CAAO,GACvC,OAAO,CAAC;IAAE,iBAAiB,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,OAAO,CAAA;CAAE,CAAC,CA4P7D"}