kibi-cli 2.35.1 → 2.38.0

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/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;AA4HrD,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,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,CA4P7D"}

package/dist/commands/sync/persistence.js

@@ -151,6 +151,30 @@ function parsePrologList(value) {
     }
     return values;
 }
+/**
+ * Assert a batch of relationships, keeping each one that succeeds, and return
+ * the 1-based positions of those that failed. Null when the store could not
+ * run the batch at all, so the caller retries every relationship.
+ */
+async function assertRelationshipsReporting(prolog, chunk) {
+    try {
+        const rels = chunk.map(({ rel, fromId, toId }) => `rel(${toPrologAtom(rel.type)}, ${toPrologAtom(fromId)}, ${toPrologAtom(toId)})`);
+        const result = await prolog.query(`kb_assert_relationships_reporting([${rels.join(", ")}], Failed)`);
+        // rationale: a non-string answer fails to parse below and the catch
+        // returns null too; the type test only narrows for the parser.
+        // Stryker disable next-line ConditionalExpression
+        if (!result.success || typeof result.bindings.Failed !== "string") {
+            return null;
+        }
+        const failed = parsePrologList(result.bindings.Failed).map(Number);
+        if (failed.some((position) => !Number.isInteger(position)))
+            return null;
+        return new Set(failed);
+    }
+    catch {
+        return null;
+    }
+}
 function sourceLookupCandidates(sourceFile) {
     return [
         ...new Set([
@@ -618,7 +642,25 @@ export async function persistRelationships(prolog, results, shardRelationships,
             kbModified = true;
             continue;
         }
-        for (const item of chunk) {
+        // One failing relationship (a dangling link is enough) rolls the whole
+        // batch back. Keep the ones that do assert in one more round trip and
+        // retry only the failures one by one for their exact errors, instead of
+        // one round trip per relationship of the batch.
+        const failedPositions = relationshipBatchRunner
+            ? await assertRelationshipsReporting(prolog, chunk)
+            : null;
+        const retried = failedPositions === null
+            ? chunk
+            : chunk.filter((_, index) => failedPositions.has(index + 1));
+        if (failedPositions !== null) {
+            chunk.forEach((item, index) => {
+                if (failedPositions.has(index + 1))
+                    return;
+                countEdge(item.rel.type, item.fromId, item.toId);
+                kbModified = true;
+            });
+        }
+        for (const item of retried) {
             try {
                 const single = await prolog.query(item.goal);
                 if (single.success) {

package/dist/commands/telemetry.d.ts

@@ -0,0 +1,7 @@
+import type { CommandResult } from "../cli-command.js";
+export type TelemetryAction = "status" | "enable" | "disable";
+/** `kibi telemetry [status|enable|disable]`: show or persist the choice. */
+export declare function telemetryCommand(action: string | undefined, options?: {
+    format?: "json" | "text";
+}, env?: NodeJS.ProcessEnv): Promise<CommandResult>;
+//# sourceMappingURL=telemetry.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"telemetry.d.ts","sourceRoot":"","sources":["../../src/commands/telemetry.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAEvD,MAAM,MAAM,eAAe,GAAG,QAAQ,GAAG,QAAQ,GAAG,SAAS,CAAC;AAG9D,4EAA4E;AAC5E,wBAAsB,gBAAgB,CACpC,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,OAAO,GAAE;IAAE,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAAA;CAAO,EAC1C,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,OAAO,CAAC,aAAa,CAAC,CAsBxB"}

package/dist/commands/telemetry.js

@@ -0,0 +1,23 @@
+// implements REQ-kibi-anonymous-usage-telemetry
+import { TELEMETRY_DOCS_URL, setTelemetryPreference, telemetryStatus, } from "kibi-agent-core/usage-telemetry";
+// implements REQ-kibi-anonymous-usage-telemetry
+/** `kibi telemetry [status|enable|disable]`: show or persist the choice. */
+export async function telemetryCommand(action, options = {}, env = process.env) {
+    const chosen = action ?? "status";
+    if (chosen !== "status" && chosen !== "enable" && chosen !== "disable") {
+        console.error(`Error: unknown telemetry action "${chosen}"; use status, enable or disable`);
+        return { exitCode: 1 };
+    }
+    if (chosen !== "status") {
+        setTelemetryPreference(chosen === "enable" ? "enabled" : "disabled", env);
+    }
+    const status = telemetryStatus(env);
+    if (options.format === "json") {
+        console.log(JSON.stringify({ ...status, docs: TELEMETRY_DOCS_URL }));
+        return { exitCode: 0 };
+    }
+    console.log(`Anonymous usage telemetry is ${status.enabled ? "on" : "off"} (${status.reason}).`);
+    console.log(`Settings and queue: ${status.directory}`);
+    console.log(`What is collected: ${TELEMETRY_DOCS_URL}`);
+    return { exitCode: 0 };
+}

package/dist/decision-firmness.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"decision-firmness.d.ts","sourceRoot":"","sources":["../src/decision-firmness.ts"],"names":[],"mappings":"AA4BA,sCAAsC;AAEtC,eAAO,MAAM,eAAe,6CAA8C,CAAC;AAG3E,MAAM,MAAM,QAAQ,GAAG,CAAC,OAAO,eAAe,CAAC,CAAC,MAAM,CAAC,CAAC;AAExD,yEAAyE;AAEzE,eAAO,MAAM,gBAAgB,EAAE,QAAoB,CAAC;AAEpD,wCAAwC;AAExC,eAAO,MAAM,cAAc,yBAA0B,CAAC;AAEtD,0EAA0E;AAE1E,eAAO,MAAM,wBAAwB,qBAAqB,CAAC;AAE3D,+DAA+D;AAE/D,eAAO,MAAM,qBAAqB,KAAK,CAAC;AAIxC;;;;GAIG;AAEH,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,CAEzE;AAGD,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,QAAQ,CAK5D;AAGD,wBAAgB,eAAe,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAKtD;AAED;;;;;;;GAOG;AAEH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,OAAO,EACb,KAAK,EAAE,OAAO,EACd,MAAM,CAAC,EAAE,OAAO,GACf,QAAQ,GAAG,SAAS,CAItB;AAED;;;;GAIG;AAEH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAEzE;AAED,uEAAuE;AAEvE,wBAAgB,UAAU,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAI9D;AAED;;;GAGG;AAEH,wBAAgB,WAAW,CAAC,MAAM,EAAE;IAClC,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB,GAAG,MAAM,GAAG,SAAS,CAcrB;AAMD;;;GAGG;AAEH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAkBxD"}
+{"version":3,"file":"decision-firmness.d.ts","sourceRoot":"","sources":["../src/decision-firmness.ts"],"names":[],"mappings":"AA4BA,sCAAsC;AAEtC,eAAO,MAAM,eAAe,6CAA8C,CAAC;AAG3E,MAAM,MAAM,QAAQ,GAAG,CAAC,OAAO,eAAe,CAAC,CAAC,MAAM,CAAC,CAAC;AAExD,yEAAyE;AAEzE,eAAO,MAAM,gBAAgB,EAAE,QAAoB,CAAC;AAEpD,wCAAwC;AAExC,eAAO,MAAM,cAAc,yBAA0B,CAAC;AAEtD,0EAA0E;AAE1E,eAAO,MAAM,wBAAwB,qBAAqB,CAAC;AAE3D,+DAA+D;AAE/D,eAAO,MAAM,qBAAqB,KAAK,CAAC;AAIxC;;;;GAIG;AAEH,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,CAEzE;AAGD,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,QAAQ,CAE5D;AAGD,wBAAgB,eAAe,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAEtD;AAED;;;;;;;GAOG;AAEH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,OAAO,EACb,KAAK,EAAE,OAAO,EACd,MAAM,CAAC,EAAE,OAAO,GACf,QAAQ,GAAG,SAAS,CAItB;AAED;;;;GAIG;AAEH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAEzE;AAED,uEAAuE;AAEvE,wBAAgB,UAAU,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAI9D;AAED;;;GAGG;AAEH,wBAAgB,WAAW,CAAC,MAAM,EAAE;IAClC,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB,GAAG,MAAM,GAAG,SAAS,CAcrB;AAMD;;;GAGG;AAEH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAgBxD"}