kibi-cli 0.5.0 → 0.6.0

package/dist/commands/aggregated-checks.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"aggregated-checks.d.ts","sourceRoot":"","sources":["../../src/commands/aggregated-checks.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,aAAa,EAAmB,MAAM,cAAc,CAAC;AAEnE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAU5C;;;;;;;GAOG;AACH,wBAAsB,mBAAmB,CACvC,MAAM,EAAE,aAAa,EACrB,cAAc,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,IAAI,EAClC,UAAU,UAAQ,GACjB,OAAO,CAAC,SAAS,EAAE,CAAC,CA2DtB"}
+{"version":3,"file":"aggregated-checks.d.ts","sourceRoot":"","sources":["../../src/commands/aggregated-checks.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,aAAa,EAAmB,MAAM,cAAc,CAAC;AAEnE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAU5C;;;;;;;GAOG;AACH,wBAAsB,mBAAmB,CACvC,MAAM,EAAE,aAAa,EACrB,cAAc,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,IAAI,EAClC,UAAU,UAAQ,GACjB,OAAO,CAAC,SAAS,EAAE,CAAC,CA4DtB"}

package/dist/commands/aggregated-checks.js

@@ -10,6 +10,7 @@ import { escapeAtom } from "../prolog/codec.js";
  * @param requireAdr - Whether to require ADR constraints for symbol-traceability
  */
 export async function runAggregatedChecks(prolog, rulesAllowlist, requireAdr = false) {
+    // implements REQ-003
     const violations = [];
     const checksPlPath = path.join(path.dirname(resolveKbPlPath()), "checks.pl");
     const checksPlPathEscaped = escapeAtom(checksPlPath);
@@ -48,8 +49,8 @@ export async function runAggregatedChecks(prolog, rulesAllowlist, requireAdr = f
                         rule: v.rule,
                         entityId: v.entityId,
                         description: v.description,
-                        suggestion: v.suggestion || undefined,
-                        source: v.source || undefined,
+                        ...(v.suggestion ? { suggestion: v.suggestion } : {}),
+                        ...(v.source ? { source: v.source } : {}),
                     });
                 }
             }

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

@@ -1 +1 @@
-{"version":3,"file":"check.d.ts","sourceRoot":"","sources":["../../src/commands/check.ts"],"names":[],"mappings":"AAkDA,OAAO,EAGL,KAAK,SAAS,EAEf,MAAM,2BAA2B,CAAC;AAEnC,YAAY,EAAE,SAAS,EAAE,CAAC;AAI1B,MAAM,WAAW,YAAY;IAC3B,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAC3B,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AA4DD,wBAAsB,YAAY,CAChC,OAAO,EAAE,YAAY,GACpB,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CAgR/B"}
+{"version":3,"file":"check.d.ts","sourceRoot":"","sources":["../../src/commands/check.ts"],"names":[],"mappings":"AAuDA,OAAO,EAGL,KAAK,SAAS,EAEf,MAAM,2BAA2B,CAAC;AAEnC,YAAY,EAAE,SAAS,EAAE,CAAC;AAI1B,MAAM,WAAW,YAAY;IAC3B,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAC3B,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AA+GD,wBAAsB,YAAY,CAChC,OAAO,EAAE,YAAY,GACpB,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CAgR/B"}

package/dist/commands/check.js

@@ -15,8 +15,10 @@
  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 { existsSync } from "node:fs";
 import * as path from "node:path";
-import { extractFromManifestString } from "../extractors/manifest.js";
+import { getBranchOverride, isCliTraceOrDebugEnabled } from "../env.js";
+import { extractFromManifest, extractFromManifestString, } from "../extractors/manifest.js";
 import { extractFromMarkdownString, } from "../extractors/markdown.js";
 import { PrologProcess } from "../prolog.js";
 import { escapeAtom, parseTriples, parseViolationRows, } from "../prolog/codec.js";
@@ -30,9 +32,48 @@ import { safeCleanupProlog } from "../utils/prolog-cleanup.js";
 import { RULES, getEffectiveRules, } from "../utils/rule-registry.js";
 import { runAggregatedChecks } from "./aggregated-checks.js";
 import { getCurrentBranch } from "./init-helpers.js";
+function getMatchGroup(match, index = 1) {
+    const value = match?.[index];
+    return typeof value === "string" ? value : null;
+}
 function buildManifestLookup(stagedFiles) {
     const manifestLookup = new Map();
     const manifestResults = [];
+    // Pre-populate lookup from working-tree manifests so that code-only changes
+    // (where symbols.yaml is not staged) still resolve to the correct symbol IDs
+    // and relationships already defined on disk.
+    const config = loadConfig(process.cwd());
+    const symbolsRelPath = config.paths.symbols;
+    if (symbolsRelPath) {
+        const absSymbolsPath = path.resolve(process.cwd(), symbolsRelPath);
+        if (existsSync(absSymbolsPath)) {
+            try {
+                const entries = extractFromManifest(absSymbolsPath);
+                for (const entry of entries) {
+                    const sourceFile = entry.sourceFile || entry.entity.source || absSymbolsPath;
+                    const key = `${sourceFile}:${entry.entity.title}`;
+                    manifestLookup.set(key, {
+                        id: entry.entity.id,
+                        relationships: entry.relationships
+                            .filter((relationship) => relationship.type === "implements" ||
+                            relationship.type === "covered_by" ||
+                            relationship.type === "executable_for")
+                            .map((relationship) => ({
+                            type: relationship.type,
+                            to: relationship.to,
+                        })),
+                    });
+                }
+            }
+            catch (e) {
+                // Ignore working-tree manifest parsing errors; staged-only fallback still applies
+                if (isCliTraceOrDebugEnabled()) {
+                    const msg = e instanceof Error ? e.message : String(e);
+                    console.debug(`[kibi] skipping working-tree manifest ${absSymbolsPath}: ${msg}`);
+                }
+            }
+        }
+    }
     const stagedManifestFiles = stagedFiles.filter((file) => file.content !== undefined &&
         (file.path.endsWith("/symbols.yaml") ||
             file.path.endsWith("/symbols.yml") ||
@@ -56,7 +97,8 @@ function buildManifestLookup(stagedFiles) {
                     id: entry.entity.id,
                     relationships: entry.relationships
                         .filter((relationship) => relationship.type === "implements" ||
-                        relationship.type === "covered_by")
+                        relationship.type === "covered_by" ||
+                        relationship.type === "executable_for")
                         .map((relationship) => ({
                         type: relationship.type,
                         to: relationship.to,
@@ -80,7 +122,7 @@ export async function checkCommand(options) {
             resolvedKbPath = options.kbPath;
         }
         else {
-            const envBranch = process.env.KIBI_BRANCH;
+            const envBranch = getBranchOverride();
             let branch = envBranch || undefined;
             if (!branch) {
                 try {
@@ -294,8 +336,9 @@ async function checkMustPriorityCoverage(prolog) {
         if (entityResult.success && entityResult.bindings.Props) {
             const propsStr = entityResult.bindings.Props;
             const sourceMatch = propsStr.match(/source\s*=\s*\^\^?\("([^"]+)"/);
-            if (sourceMatch) {
-                source = sourceMatch[1];
+            const sourceValue = getMatchGroup(sourceMatch);
+            if (sourceValue) {
+                source = sourceValue;
             }
         }
         const scenarioResult = await prolog.query(`kb_relationship(specified_by, '${reqId}', ScenarioId)`);
@@ -331,10 +374,7 @@ async function findMustPriorityReqs(prolog) {
     }
     const idsStr = result.bindings.Ids;
     const match = idsStr.match(/\[(.*)\]/);
-    if (!match) {
-        return [];
-    }
-    const content = match[1].trim();
+    const content = getMatchGroup(match)?.trim();
     if (!content) {
         return [];
     }
@@ -349,10 +389,7 @@ async function getAllEntityIds(prolog, type) {
     }
     const idsStr = result.bindings.Ids;
     const match = idsStr.match(/\[(.*)\]/);
-    if (!match) {
-        return [];
-    }
-    const content = match[1].trim();
+    const content = getMatchGroup(match)?.trim();
     if (!content) {
         return [];
     }
@@ -377,15 +414,17 @@ async function checkNoDanglingRefs(prolog) {
         if (relsResult.success && relsResult.bindings.Rels) {
             const relsStr = relsResult.bindings.Rels;
             const match = relsStr.match(/\[(.*)\]/);
-            if (match) {
-                const content = match[1].trim();
-                if (content) {
-                    const relMatches = content.matchAll(/\[([^,]+),([^\]]+)\]/g);
-                    for (const relMatch of relMatches) {
-                        const fromId = relMatch[1].trim().replace(/^'|'$/g, "");
-                        const toId = relMatch[2].trim().replace(/^'|'$/g, "");
-                        allRels.push({ from: fromId, to: toId });
-                    }
+            const content = getMatchGroup(match)?.trim();
+            if (content) {
+                const relMatches = content.matchAll(/\[([^,]+),([^\]]+)\]/g);
+                for (const relMatch of relMatches) {
+                    const fromValue = getMatchGroup(relMatch);
+                    const toValue = getMatchGroup(relMatch, 2);
+                    if (!fromValue || !toValue)
+                        continue;
+                    const fromId = fromValue.trim().replace(/^'|'$/g, "");
+                    const toId = toValue.trim().replace(/^'|'$/g, "");
+                    allRels.push({ from: fromId, to: toId });
                 }
             }
         }
@@ -419,18 +458,19 @@ async function checkNoCycles(prolog) {
     }
     const depsStr = depsResult.bindings.Deps;
     const match = depsStr.match(/\[(.*)\]/);
-    if (!match) {
-        return violations;
-    }
-    const content = match[1].trim();
+    const content = getMatchGroup(match)?.trim();
     if (!content) {
         return violations;
     }
     const graph = new Map();
     const depMatches = content.matchAll(/\[([^,]+),([^\]]+)\]/g);
     for (const depMatch of depMatches) {
-        const from = depMatch[1].trim().replace(/^'|'$/g, "");
-        const to = depMatch[2].trim().replace(/^'|'$/g, "");
+        const fromValue = getMatchGroup(depMatch);
+        const toValue = getMatchGroup(depMatch, 2);
+        if (!fromValue || !toValue)
+            continue;
+        const from = fromValue.trim().replace(/^'|'$/g, "");
+        const to = toValue.trim().replace(/^'|'$/g, "");
         if (!graph.has(from)) {
             graph.set(from, []);
         }
@@ -464,6 +504,10 @@ async function checkNoCycles(prolog) {
         if (!visited.has(node)) {
             const cyclePath = hasCycleDFS(node, []);
             if (cyclePath) {
+                const cycleEntityId = cyclePath[0];
+                if (!cycleEntityId) {
+                    continue;
+                }
                 const cycleWithSources = [];
                 for (const entityId of cyclePath) {
                     const entityResult = await prolog.query(`kb_entity('${entityId}', _, Props)`);
@@ -471,15 +515,16 @@ async function checkNoCycles(prolog) {
                     if (entityResult.success && entityResult.bindings.Props) {
                         const propsStr = entityResult.bindings.Props;
                         const sourceMatch = propsStr.match(/source\s*=\s*\^\^?\("([^"]+)"/);
-                        if (sourceMatch) {
-                            sourceName = path.basename(sourceMatch[1], ".md");
+                        const sourceValue = getMatchGroup(sourceMatch);
+                        if (sourceValue) {
+                            sourceName = path.basename(sourceValue, ".md");
                         }
                     }
                     cycleWithSources.push(sourceName);
                 }
                 violations.push({
                     rule: "no-cycles",
-                    entityId: cyclePath[0],
+                    entityId: cycleEntityId,
                     description: `Circular dependency detected: ${cycleWithSources.join(" → ")}`,
                     suggestion: "Break cycle by removing one of the depends_on relationships",
                 });
@@ -506,7 +551,10 @@ async function checkRequiredFields(prolog, allEntityIds) {
             const propKeys = new Set();
             const keyMatches = propsStr.matchAll(/(\w+)\s*=/g);
             for (const match of keyMatches) {
-                propKeys.add(match[1]);
+                const key = getMatchGroup(match);
+                if (key) {
+                    propKeys.add(key);
+                }
             }
             for (const field of required) {
                 if (!propKeys.has(field)) {
@@ -531,10 +579,7 @@ async function checkDeprecatedAdrs(prolog) {
     }
     const idsStr = result.bindings.Ids;
     const match = idsStr.match(/\[(.*)\]/);
-    if (!match) {
-        return violations;
-    }
-    const content = match[1].trim();
+    const content = getMatchGroup(match)?.trim();
     if (!content) {
         return violations;
     }
@@ -547,8 +592,9 @@ async function checkDeprecatedAdrs(prolog) {
         if (entityResult.success && entityResult.bindings.Props) {
             const propsStr = entityResult.bindings.Props;
             const sourceMatch = propsStr.match(/source\s*=\s*\^\^?\("([^"]+)"/);
-            if (sourceMatch) {
-                source = sourceMatch[1];
+            const sourceValue = getMatchGroup(sourceMatch);
+            if (sourceValue) {
+                source = sourceValue;
             }
         }
         violations.push({
@@ -600,19 +646,19 @@ async function checkSymbolCoverage(prolog) {
     if (uncoveredResult.success && uncoveredResult.bindings.Symbols) {
         const symbolsStr = uncoveredResult.bindings.Symbols;
         const match = symbolsStr.match(/\[(.*)\]/);
-        if (match) {
-            const content = match[1].trim();
-            if (content) {
-                const symbolMatches = content.matchAll(/'([^']+)'/g);
-                for (const symbolMatch of symbolMatches) {
-                    const symbolId = symbolMatch[1];
-                    violations.push({
-                        rule: "symbol-coverage",
-                        entityId: symbolId,
-                        description: "Code symbol is not traceable to any functional requirement.",
-                        suggestion: "Update symbols.yaml to link this symbol to a related requirement.",
-                    });
-                }
+        const content = getMatchGroup(match)?.trim();
+        if (content) {
+            const symbolMatches = content.matchAll(/'([^']+)'/g);
+            for (const symbolMatch of symbolMatches) {
+                const symbolId = getMatchGroup(symbolMatch);
+                if (!symbolId)
+                    continue;
+                violations.push({
+                    rule: "symbol-coverage",
+                    entityId: symbolId,
+                    description: "Code symbol is not traceable to any functional requirement.",
+                    suggestion: "Update symbols.yaml to link this symbol to a related requirement.",
+                });
             }
         }
     }

package/dist/commands/discovery-shared.d.ts

@@ -1,11 +1,18 @@
-import { PrologProcess } from "../prolog.js";
+import { PrologProcess, resolveKbPlPath } from "../prolog.js";
 export interface DiscoveryCommandOptions {
     format?: "json" | "table";
 }
-export declare function withAttachedBranchProlog<T>(callback: (prolog: PrologProcess) => Promise<T>): Promise<T>;
-export declare function withPrologProcess<T>(callback: (prolog: PrologProcess) => Promise<T>): Promise<T>;
+/** Dependencies that can be injected for testing. */
+export interface DiscoveryDeps {
+    createProlog: (opts: {
+        timeout: number;
+    }) => PrologProcess;
+    resolveKbPl: typeof resolveKbPlPath;
+}
+export declare function withAttachedBranchProlog<T>(callback: (prolog: PrologProcess) => Promise<T>, deps?: Partial<DiscoveryDeps>): Promise<T>;
+export declare function withPrologProcess<T>(callback: (prolog: PrologProcess) => Promise<T>, deps?: Partial<DiscoveryDeps>): Promise<T>;
 export declare function resolveCurrentKbPath(): Promise<string>;
-export declare function resolveCoreModulePath(fileName: string): string;
-export declare function runJsonModuleQuery<T>(prolog: PrologProcess, fileName: string, goal: string, errorLabel: string, kbPath?: string): Promise<T>;
+export declare function resolveCoreModulePath(fileName: string, deps?: Partial<DiscoveryDeps>): string;
+export declare function runJsonModuleQuery<T>(prolog: PrologProcess, fileName: string, goal: string, errorLabel: string, kbPath?: string, deps?: Partial<DiscoveryDeps>): Promise<T>;
 export declare function printDiscoveryResult(format: "json" | "table" | undefined, structured: unknown, fallbackText: string): void;
 //# sourceMappingURL=discovery-shared.d.ts.map

package/dist/commands/discovery-shared.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"discovery-shared.d.ts","sourceRoot":"","sources":["../../src/commands/discovery-shared.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,aAAa,EAAmB,MAAM,cAAc,CAAC;AAK9D,MAAM,WAAW,uBAAuB;IACtC,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CAC3B;AAGD,wBAAsB,wBAAwB,CAAC,CAAC,EAC9C,QAAQ,EAAE,CAAC,MAAM,EAAE,aAAa,KAAK,OAAO,CAAC,CAAC,CAAC,GAC9C,OAAO,CAAC,CAAC,CAAC,CAkCZ;AAGD,wBAAsB,iBAAiB,CAAC,CAAC,EACvC,QAAQ,EAAE,CAAC,MAAM,EAAE,aAAa,KAAK,OAAO,CAAC,CAAC,CAAC,GAC9C,OAAO,CAAC,CAAC,CAAC,CAYZ;AAGD,wBAAsB,oBAAoB,IAAI,OAAO,CAAC,MAAM,CAAC,CAS5D;AAGD,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAE9D;AAGD,wBAAsB,kBAAkB,CAAC,CAAC,EACxC,MAAM,EAAE,aAAa,EACrB,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,MAAM,EAClB,MAAM,CAAC,EAAE,MAAM,GACd,OAAO,CAAC,CAAC,CAAC,CAwBZ;AAGD,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS,EACpC,UAAU,EAAE,OAAO,EACnB,YAAY,EAAE,MAAM,GACnB,IAAI,CAQN"}
+{"version":3,"file":"discovery-shared.d.ts","sourceRoot":"","sources":["../../src/commands/discovery-shared.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAK9D,MAAM,WAAW,uBAAuB;IACtC,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CAC3B;AAED,qDAAqD;AACrD,MAAM,WAAW,aAAa;IAC5B,YAAY,EAAE,CAAC,IAAI,EAAE;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,KAAK,aAAa,CAAC;IAC3D,WAAW,EAAE,OAAO,eAAe,CAAC;CACrC;AAGD,wBAAsB,wBAAwB,CAAC,CAAC,EAC9C,QAAQ,EAAE,CAAC,MAAM,EAAE,aAAa,KAAK,OAAO,CAAC,CAAC,CAAC,EAC/C,IAAI,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,GAC5B,OAAO,CAAC,CAAC,CAAC,CAmCZ;AAGD,wBAAsB,iBAAiB,CAAC,CAAC,EACvC,QAAQ,EAAE,CAAC,MAAM,EAAE,aAAa,KAAK,OAAO,CAAC,CAAC,CAAC,EAC/C,IAAI,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,GAC5B,OAAO,CAAC,CAAC,CAAC,CAmBZ;AAGD,wBAAsB,oBAAoB,IAAI,OAAO,CAAC,MAAM,CAAC,CAS5D;AAGD,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,MAAM,EAChB,IAAI,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,GAC5B,MAAM,CAGR;AAGD,wBAAsB,kBAAkB,CAAC,CAAC,EACxC,MAAM,EAAE,aAAa,EACrB,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,MAAM,EAClB,MAAM,CAAC,EAAE,MAAM,EACf,IAAI,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,GAC5B,OAAO,CAAC,CAAC,CAAC,CAwBZ;AAGD,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS,EACpC,UAAU,EAAE,OAAO,EACnB,YAAY,EAAE,MAAM,GACnB,IAAI,CAQN"}

package/dist/commands/discovery-shared.js

@@ -1,24 +1,25 @@
 import path from "node:path";
 import Table from "cli-table3";
+import { getBranchOverride } from "../env.js";
 import { PrologProcess, resolveKbPlPath } from "../prolog.js";
 import { escapeAtom } from "../prolog/codec.js";
 import { safeCleanupProlog } from "../utils/prolog-cleanup.js";
 import { getCurrentBranch } from "./init-helpers.js";
 // implements REQ-003
-export async function withAttachedBranchProlog(callback) {
+export async function withAttachedBranchProlog(callback, deps) {
+    const createProlog = deps?.createProlog ?? ((opts) => new PrologProcess(opts));
     let prolog = null;
     let attached = false;
     try {
-        prolog = new PrologProcess({ timeout: 120000 });
+        prolog = createProlog({ timeout: 120000 });
         await prolog.start();
         await prolog.query("set_prolog_flag(answer_write_options, [max_depth(0), spacing(next_argument)])");
         let branch;
         try {
-            branch =
-                process.env.KIBI_BRANCH || (await getCurrentBranch(process.cwd()));
+            branch = getBranchOverride() || (await getCurrentBranch(process.cwd()));
         }
         catch {
-            branch = process.env.KIBI_BRANCH || "main";
+            branch = getBranchOverride() || "main";
         }
         const kbPath = path.join(process.cwd(), ".kb/branches", branch);
         const attachResult = await prolog.query(`kb_attach('${escapeAtom(kbPath)}')`);
@@ -33,10 +34,16 @@ export async function withAttachedBranchProlog(callback) {
     }
 }
 // implements REQ-003
-export async function withPrologProcess(callback) {
-    const prolog = new PrologProcess({ timeout: 120000 });
+export async function withPrologProcess(callback, deps) {
+    const createProlog = deps?.createProlog ?? ((opts) => new PrologProcess(opts));
+    const prolog = createProlog({ timeout: 120000 });
     try {
         await prolog.start();
+        // NOTE: useOneShotMode is an internal optimization flag on PrologProcess that
+        // forces single-query mode (start → query → terminate per call) instead of the
+        // default interactive session. It is not exposed in the public PrologProcess
+        // type because callers should not set it directly — only internal discovery
+        // helpers use it for lightweight one-shot queries that don't need session state.
         prolog.useOneShotMode = true;
         await prolog.query("set_prolog_flag(answer_write_options, [max_depth(0), spacing(next_argument)])");
         return await callback(prolog);
@@ -49,20 +56,21 @@ export async function withPrologProcess(callback) {
 export async function resolveCurrentKbPath() {
     let branch;
     try {
-        branch = process.env.KIBI_BRANCH || (await getCurrentBranch(process.cwd()));
+        branch = getBranchOverride() || (await getCurrentBranch(process.cwd()));
     }
     catch {
-        branch = process.env.KIBI_BRANCH || "main";
+        branch = getBranchOverride() || "main";
     }
     return path.join(process.cwd(), ".kb/branches", branch);
 }
 // implements REQ-003
-export function resolveCoreModulePath(fileName) {
-    return path.join(path.dirname(resolveKbPlPath()), fileName);
+export function resolveCoreModulePath(fileName, deps) {
+    const resolve = deps?.resolveKbPl ?? resolveKbPlPath;
+    return path.join(path.dirname(resolve()), fileName);
 }
 // implements REQ-003
-export async function runJsonModuleQuery(prolog, fileName, goal, errorLabel, kbPath) {
-    const modulePath = escapeAtom(resolveCoreModulePath(fileName).replace(/\\/g, "/"));
+export async function runJsonModuleQuery(prolog, fileName, goal, errorLabel, kbPath, deps) {
+    const modulePath = escapeAtom(resolveCoreModulePath(fileName, deps).replace(/\\/g, "/"));
     const wrappedGoal = kbPath
         ? `(use_module('${modulePath}'), kb_attach('${escapeAtom(kbPath)}'), ${goal}, kb_detach)`
         : `(use_module('${modulePath}'), ${goal})`;

package/dist/commands/doctor.js

@@ -82,7 +82,15 @@ function checkSWIProlog() {
                 remediation: "Reinstall SWI-Prolog from https://www.swi-prolog.org/",
             };
         }
-        const major = Number.parseInt(versionMatch[1], 10);
+        const majorText = versionMatch[1];
+        if (!majorText) {
+            return {
+                passed: false,
+                message: "Unable to parse major version",
+                remediation: "Reinstall SWI-Prolog from https://www.swi-prolog.org/",
+            };
+        }
+        const major = Number.parseInt(majorText, 10);
         if (major < 9) {
             return {
                 passed: false,

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":"AAuFA,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,CAQN;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAMpD;AAED,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAajD;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,CAmCnE;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":"AAuFA,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,CAQN;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAMpD;AAED,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAajD;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"}

package/dist/commands/init-helpers.js

@@ -121,6 +121,7 @@ function escapeRegex(s) {
     return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
 export function installHook(hookPath, content) {
+    // implements REQ-008
     const kibiSection = `${KIBI_HOOK_BEGIN}\n${content}\n${KIBI_HOOK_END}`;
     if (existsSync(hookPath)) {
         const existing = readFileSync(hookPath, "utf8");
@@ -130,12 +131,10 @@ export function installHook(hookPath, content) {
             const updated = existing.replace(new RegExp(`${escapeRegex(KIBI_HOOK_BEGIN)}[\\s\\S]*?${escapeRegex(KIBI_HOOK_END)}`), kibiSection);
             writeFileSync(hookPath, updated, { mode: 0o755 });
         }
-        else if (existing.includes("kibi branch ensure")) {
-            // Legacy format: already has the complete kibi logic, skip
+        else if (existing.trim().length > 0) {
             return;
         }
         else {
-            // Hook exists with user content (no kibi section) - append kibi section
             const shebang = existing.startsWith("#!/") ? "" : "#!/bin/sh\n";
             writeFileSync(hookPath, `${shebang}${existing.trimEnd()}\n${kibiSection}\n`, { mode: 0o755 });
         }

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

@@ -1 +1 @@
-{"version":3,"file":"query.d.ts","sourceRoot":"","sources":["../../src/commands/query.ts"],"names":[],"mappings":"AA4CA,UAAU,YAAY;IACpB,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IAC1B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAGD,wBAAsB,YAAY,CAChC,IAAI,EAAE,MAAM,GAAG,SAAS,EACxB,OAAO,EAAE,YAAY,GACpB,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CA+J/B"}
+{"version":3,"file":"query.d.ts","sourceRoot":"","sources":["../../src/commands/query.ts"],"names":[],"mappings":"AA4CA,UAAU,YAAY;IACpB,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IAC1B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAGD,wBAAsB,YAAY,CAChC,IAAI,EAAE,MAAM,GAAG,SAAS,EACxB,OAAO,EAAE,YAAY,GACpB,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CA4K/B"}

package/dist/commands/query.js

@@ -71,11 +71,21 @@ export async function queryCommand(type, options) {
                 const rows = parseListOfLists(queryResult.bindings.Results);
                 const parsed = rows
                     .filter((r) => r.length >= 3)
-                    .map((r) => ({
-                    type: parsePrologValue(r[0]),
-                    from: parsePrologValue(r[1]),
-                    to: parsePrologValue(r[2]),
-                }));
+                    .flatMap((r) => {
+                    const [typeValue, fromValue, toValue] = r;
+                    if (typeValue === undefined ||
+                        fromValue === undefined ||
+                        toValue === undefined) {
+                        return [];
+                    }
+                    return [
+                        {
+                            type: parsePrologValue(typeValue),
+                            from: parsePrologValue(fromValue),
+                            to: parsePrologValue(toValue),
+                        },
+                    ];
+                });
                 results = parsed.filter((rel) => rel &&
                     typeof rel.type === "string" &&
                     typeof rel.from === "string" &&

package/dist/commands/search.js

@@ -22,7 +22,7 @@ export async function searchCommand(query, options) {
 }
 async function executeSearch(prolog, query, type, limit, offset) {
     const entitiesResult = await queryEntities(prolog, {
-        type,
+        ...(type !== undefined ? { type } : {}),
         limit: 100000,
         offset: 0,
     });

package/dist/commands/sync/cache.d.ts

@@ -1,3 +1,12 @@
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+interface SyncCacheDeps {
+    createHash: typeof createHash;
+    existsSync: typeof existsSync;
+    mkdirSync: typeof mkdirSync;
+    readFileSync: typeof readFileSync;
+    writeFileSync: typeof writeFileSync;
+}
 export type SyncCache = {
     version: number;
     hashes: Record<string, string>;
@@ -6,8 +15,9 @@ export type SyncCache = {
 export declare const SYNC_CACHE_VERSION = 1;
 export declare const SYNC_CACHE_TTL_MS: number;
 export declare function toCacheKey(filePath: string): string;
-export declare function hashFile(filePath: string): string;
-export declare function readSyncCache(cachePath: string): SyncCache;
-export declare function writeSyncCache(cachePath: string, cache: SyncCache): void;
-export declare function copySyncCache(livePath: string, stagingPath: string): void;
+export declare function hashFile(filePath: string, deps?: Partial<SyncCacheDeps>): string;
+export declare function readSyncCache(cachePath: string, deps?: Partial<SyncCacheDeps>): SyncCache;
+export declare function writeSyncCache(cachePath: string, cache: SyncCache, deps?: Partial<SyncCacheDeps>): void;
+export declare function copySyncCache(livePath: string, stagingPath: string, deps?: Partial<SyncCacheDeps>): void;
+export {};
 //# sourceMappingURL=cache.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../../../src/commands/sync/cache.ts"],"names":[],"mappings":"AAsBA,MAAM,MAAM,SAAS,GAAG;IACtB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAChC,CAAC;AAEF,eAAO,MAAM,kBAAkB,IAAI,CAAC;AACpC,eAAO,MAAM,iBAAiB,QAA2B,CAAC;AAE1D,wBAAgB,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAEnD;AAED,wBAAgB,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAGjD;AAED,wBAAgB,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,CAiC1D;AAED,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,GAAG,IAAI,CAYxE;AAED,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,IAAI,CAQzE"}
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../../../src/commands/sync/cache.ts"],"names":[],"mappings":"AAkBA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAG7E,UAAU,aAAa;IACrB,UAAU,EAAE,OAAO,UAAU,CAAC;IAC9B,UAAU,EAAE,OAAO,UAAU,CAAC;IAC9B,SAAS,EAAE,OAAO,SAAS,CAAC;IAC5B,YAAY,EAAE,OAAO,YAAY,CAAC;IAClC,aAAa,EAAE,OAAO,aAAa,CAAC;CACrC;AAaD,MAAM,MAAM,SAAS,GAAG;IACtB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAChC,CAAC;AAEF,eAAO,MAAM,kBAAkB,IAAI,CAAC;AACpC,eAAO,MAAM,iBAAiB,QAA2B,CAAC;AAE1D,wBAAgB,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAEnD;AAED,wBAAgB,QAAQ,CAEtB,QAAQ,EAAE,MAAM,EAChB,IAAI,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,GAC5B,MAAM,CAIR;AAED,wBAAgB,aAAa,CAE3B,SAAS,EAAE,MAAM,EACjB,IAAI,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,GAC5B,SAAS,CAkCX;AAED,wBAAgB,cAAc,CAE5B,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,SAAS,EAChB,IAAI,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,GAC5B,IAAI,CAaN;AAED,wBAAgB,aAAa,CAE3B,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,MAAM,EACnB,IAAI,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,GAC5B,IAAI,CASN"}

package/dist/commands/sync/cache.js

@@ -18,17 +18,33 @@
 import { createHash } from "node:crypto";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import * as path from "node:path";
+function resolveDeps(overrides) {
+    return {
+        createHash,
+        existsSync,
+        mkdirSync,
+        readFileSync,
+        writeFileSync,
+        ...overrides,
+    };
+}
 export const SYNC_CACHE_VERSION = 1;
 export const SYNC_CACHE_TTL_MS = 30 * 24 * 60 * 60 * 1000;
 export function toCacheKey(filePath) {
     return path.relative(process.cwd(), filePath).split(path.sep).join("/");
 }
-export function hashFile(filePath) {
-    const content = readFileSync(filePath);
-    return createHash("sha256").update(content).digest("hex");
+export function hashFile(
+// implements REQ-003
+filePath, deps) {
+    const resolved = resolveDeps(deps);
+    const content = resolved.readFileSync(filePath);
+    return resolved.createHash("sha256").update(content).digest("hex");
 }
-export function readSyncCache(cachePath) {
-    if (!existsSync(cachePath)) {
+export function readSyncCache(
+// implements REQ-003
+cachePath, deps) {
+    const resolved = resolveDeps(deps);
+    if (!resolved.existsSync(cachePath)) {
         return {
             version: SYNC_CACHE_VERSION,
             hashes: {},
@@ -36,7 +52,7 @@ export function readSyncCache(cachePath) {
         };
     }
     try {
-        const parsed = JSON.parse(readFileSync(cachePath, "utf8"));
+        const parsed = JSON.parse(resolved.readFileSync(cachePath, "utf8"));
         if (parsed.version !== SYNC_CACHE_VERSION) {
             return {
                 version: SYNC_CACHE_VERSION,
@@ -58,19 +74,25 @@ export function readSyncCache(cachePath) {
         };
     }
 }
-export function writeSyncCache(cachePath, cache) {
+export function writeSyncCache(
+// implements REQ-003
+cachePath, cache, deps) {
+    const resolved = resolveDeps(deps);
     const cacheDir = path.dirname(cachePath);
-    if (!existsSync(cacheDir)) {
-        mkdirSync(cacheDir, { recursive: true });
+    if (!resolved.existsSync(cacheDir)) {
+        resolved.mkdirSync(cacheDir, { recursive: true });
     }
-    writeFileSync(cachePath, `${JSON.stringify(cache, null, 2)}
+    resolved.writeFileSync(cachePath, `${JSON.stringify(cache, null, 2)}
 `, "utf8");
 }
-export function copySyncCache(livePath, stagingPath) {
+export function copySyncCache(
+// implements REQ-003
+livePath, stagingPath, deps) {
+    const resolved = resolveDeps(deps);
     const liveCachePath = path.join(livePath, "sync-cache.json");
     const stagingCachePath = path.join(stagingPath, "sync-cache.json");
-    if (existsSync(liveCachePath)) {
-        const cacheContent = readFileSync(liveCachePath, "utf8");
-        writeFileSync(stagingCachePath, cacheContent, "utf8");
+    if (resolved.existsSync(liveCachePath)) {
+        const cacheContent = resolved.readFileSync(liveCachePath, "utf8");
+        resolved.writeFileSync(stagingCachePath, cacheContent, "utf8");
     }
 }

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

@@ -1 +1 @@
-{"version":3,"file":"extraction.d.ts","sourceRoot":"","sources":["../../../src/commands/sync/extraction.ts"],"names":[],"mappings":"AAmBA,OAAO,EACL,KAAK,gBAAgB,EAGtB,MAAM,8BAA8B,CAAC;AAGtC,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,gBAAgB,EAAE,CAAC;IAC5B,eAAe,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAC7B,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CAC7C;AAED,wBAAsB,kBAAkB,CACtC,oBAAoB,EAAE,MAAM,EAAE,EAC9B,oBAAoB,EAAE,MAAM,EAAE,EAC9B,YAAY,EAAE,OAAO,GACpB,OAAO,CAAC,gBAAgB,CAAC,CAoD3B"}
+{"version":3,"file":"extraction.d.ts","sourceRoot":"","sources":["../../../src/commands/sync/extraction.ts"],"names":[],"mappings":"AAmBA,OAAO,EACL,KAAK,gBAAgB,EAGtB,MAAM,8BAA8B,CAAC;AAGtC,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,gBAAgB,EAAE,CAAC;IAC5B,eAAe,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAC7B,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CAC7C;AAED,wBAAsB,kBAAkB,CAEtC,oBAAoB,EAAE,MAAM,EAAE,EAC9B,oBAAoB,EAAE,MAAM,EAAE,EAC9B,YAAY,EAAE,OAAO,GACpB,OAAO,CAAC,gBAAgB,CAAC,CA4C3B"}