kibi-cli 0.5.1 → 0.6.0

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

@@ -1,5 +1,16 @@
-import { type ManifestSymbolEntry } from "../../extractors/symbols-coordinator.js";
-export declare function refreshManifestCoordinates(manifestPath: string, workspaceRoot: string): Promise<void>;
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { dump as dumpYAML, load as parseYAML } from "js-yaml";
+import { type ManifestSymbolEntry, enrichSymbolCoordinates } from "../../extractors/symbols-coordinator.js";
+interface ManifestDeps {
+    dumpYAML: typeof dumpYAML;
+    enrichSymbolCoordinates: typeof enrichSymbolCoordinates;
+    existsSync: typeof existsSync;
+    parseYAML: typeof parseYAML;
+    readFileSync: typeof readFileSync;
+    writeFileSync: typeof writeFileSync;
+}
+export declare function refreshManifestCoordinates(manifestPath: string, workspaceRoot: string, deps?: Partial<ManifestDeps>): Promise<void>;
 export declare function hasAllGeneratedCoordinates(entry: ManifestSymbolEntry): boolean;
-export declare function isEligibleForCoordinateRefresh(sourceFile: string | undefined, workspaceRoot: string): boolean;
+export declare function isEligibleForCoordinateRefresh(sourceFile: string | undefined, workspaceRoot: string, deps?: Partial<ManifestDeps>): boolean;
+export {};
 //# sourceMappingURL=manifest.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../../../src/commands/sync/manifest.ts"],"names":[],"mappings":"AAqBA,OAAO,EACL,KAAK,mBAAmB,EAEzB,MAAM,yCAAyC,CAAC;AA6BjD,wBAAsB,0BAA0B,CAC9C,YAAY,EAAE,MAAM,EACpB,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC,IAAI,CAAC,CAyEf;AAED,wBAAgB,0BAA0B,CACxC,KAAK,EAAE,mBAAmB,GACzB,OAAO,CAST;AAED,wBAAgB,8BAA8B,CAC5C,UAAU,EAAE,MAAM,GAAG,SAAS,EAC9B,aAAa,EAAE,MAAM,GACpB,OAAO,CAST"}
+{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../../../src/commands/sync/manifest.ts"],"names":[],"mappings":"AAkBA,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAElE,OAAO,EAAE,IAAI,IAAI,QAAQ,EAAE,IAAI,IAAI,SAAS,EAAE,MAAM,SAAS,CAAC;AAC9D,OAAO,EACL,KAAK,mBAAmB,EACxB,uBAAuB,EACxB,MAAM,yCAAyC,CAAC;AAEjD,UAAU,YAAY;IACpB,QAAQ,EAAE,OAAO,QAAQ,CAAC;IAC1B,uBAAuB,EAAE,OAAO,uBAAuB,CAAC;IACxD,UAAU,EAAE,OAAO,UAAU,CAAC;IAC9B,SAAS,EAAE,OAAO,SAAS,CAAC;IAC5B,YAAY,EAAE,OAAO,YAAY,CAAC;IAClC,aAAa,EAAE,OAAO,aAAa,CAAC;CACrC;AAyCD,wBAAsB,0BAA0B,CAE9C,YAAY,EAAE,MAAM,EACpB,aAAa,EAAE,MAAM,EACrB,IAAI,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,GAC3B,OAAO,CAAC,IAAI,CAAC,CA8Ef;AAED,wBAAgB,0BAA0B,CAExC,KAAK,EAAE,mBAAmB,GACzB,OAAO,CAST;AAED,wBAAgB,8BAA8B,CAE5C,UAAU,EAAE,MAAM,GAAG,SAAS,EAC9B,aAAa,EAAE,MAAM,EACrB,IAAI,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,GAC3B,OAAO,CAUT"}

package/dist/commands/sync/manifest.js

@@ -19,6 +19,17 @@ import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import * as path from "node:path";
 import { dump as dumpYAML, load as parseYAML } from "js-yaml";
 import { enrichSymbolCoordinates, } from "../../extractors/symbols-coordinator.js";
+function resolveDeps(overrides) {
+    return {
+        dumpYAML,
+        enrichSymbolCoordinates,
+        existsSync,
+        parseYAML,
+        readFileSync,
+        writeFileSync,
+        ...overrides,
+    };
+}
 const SYMBOLS_MANIFEST_COMMENT_BLOCK = `# symbols.yaml
 # AUTHORED fields (edit freely):
 #   id, title, sourceFile, links, status, tags, owner, priority
@@ -43,9 +54,12 @@ const GENERATED_COORD_FIELDS = [
     "sourceEndColumn",
     "coordinatesGeneratedAt",
 ];
-export async function refreshManifestCoordinates(manifestPath, workspaceRoot) {
-    const rawContent = readFileSync(manifestPath, "utf8");
-    const parsed = parseYAML(rawContent);
+export async function refreshManifestCoordinates(
+// implements REQ-003
+manifestPath, workspaceRoot, deps) {
+    const resolved = resolveDeps(deps);
+    const rawContent = resolved.readFileSync(manifestPath, "utf8");
+    const parsed = resolved.parseYAML(rawContent);
     if (!isRecord(parsed)) {
         console.warn(`Warning: symbols manifest ${manifestPath} is not a YAML object; skipping coordinate refresh`);
         return;
@@ -58,7 +72,7 @@ export async function refreshManifestCoordinates(manifestPath, workspaceRoot) {
     const before = rawSymbols.map((entry) => isRecord(entry)
         ? { ...entry }
         : {});
-    const enriched = await enrichSymbolCoordinates(before, workspaceRoot);
+    const enriched = await resolved.enrichSymbolCoordinates(before, workspaceRoot);
     parsed.symbols = enriched;
     let refreshed = 0;
     let failed = 0;
@@ -75,7 +89,7 @@ export async function refreshManifestCoordinates(manifestPath, workspaceRoot) {
             ? current.sourceFile
             : typeof previous.sourceFile === "string"
                 ? previous.sourceFile
-                : undefined, workspaceRoot);
+                : undefined, workspaceRoot, resolved);
         if (eligible && !hasAllGeneratedCoordinates(current)) {
             failed++;
         }
@@ -83,18 +97,20 @@ export async function refreshManifestCoordinates(manifestPath, workspaceRoot) {
             unchanged++;
         }
     }
-    const dumped = dumpYAML(parsed, {
+    const dumped = resolved.dumpYAML(parsed, {
         lineWidth: -1,
         noRefs: true,
         sortKeys: false,
     });
     const nextContent = `${SYMBOLS_MANIFEST_COMMENT_BLOCK}${dumped}`;
     if (rawContent !== nextContent) {
-        writeFileSync(manifestPath, nextContent, "utf8");
+        resolved.writeFileSync(manifestPath, nextContent, "utf8");
     }
     console.log(`✓ Refreshed symbol coordinates in ${path.relative(workspaceRoot, manifestPath)} (refreshed=${refreshed}, unchanged=${unchanged}, failed=${failed})`);
 }
-export function hasAllGeneratedCoordinates(entry) {
+export function hasAllGeneratedCoordinates(
+// implements REQ-003
+entry) {
     return (typeof entry.sourceLine === "number" &&
         typeof entry.sourceColumn === "number" &&
         typeof entry.sourceEndLine === "number" &&
@@ -102,13 +118,16 @@ export function hasAllGeneratedCoordinates(entry) {
         typeof entry.coordinatesGeneratedAt === "string" &&
         entry.coordinatesGeneratedAt.length > 0);
 }
-export function isEligibleForCoordinateRefresh(sourceFile, workspaceRoot) {
+export function isEligibleForCoordinateRefresh(
+// implements REQ-003
+sourceFile, workspaceRoot, deps) {
+    const resolved = resolveDeps(deps);
     if (!sourceFile)
         return false;
     const absolute = path.isAbsolute(sourceFile)
         ? sourceFile
         : path.resolve(workspaceRoot, sourceFile);
-    if (!existsSync(absolute))
+    if (!resolved.existsSync(absolute))
         return false;
     const ext = path.extname(absolute).toLowerCase();
     return SYMBOL_COORD_EXTENSIONS.has(ext);

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;AAqErD,MAAM,WAAW,iBAAiB;IAChC,WAAW,EAAE,MAAM,CAAC;IACpB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,UAAU,EAAE,OAAO,CAAC;CACrB;AAED,wBAAsB,eAAe,CAEnC,MAAM,EAAE,aAAa,EACrB,OAAO,EAAE,gBAAgB,EAAE,EAC3B,SAAS,EAAE,GAAG,CAAC,MAAM,CAAC,GACrB,OAAO,CAAC;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,OAAO,CAAA;CAAE,CAAC,CAoEvD;AAED,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,aAAa,EACrB,OAAO,EAAE,gBAAgB,EAAE,EAC3B,kBAAkB,EAAE,qBAAqB,EAAE,GAC1C,OAAO,CAAC;IAAE,iBAAiB,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,OAAO,CAAA;CAAE,CAAC,CAiI7D"}
+{"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;AA0ErD,MAAM,WAAW,iBAAiB;IAChC,WAAW,EAAE,MAAM,CAAC;IACpB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,UAAU,EAAE,OAAO,CAAC;CACrB;AAED,wBAAsB,eAAe,CAEnC,MAAM,EAAE,aAAa,EACrB,OAAO,EAAE,gBAAgB,EAAE,EAC3B,SAAS,EAAE,GAAG,CAAC,MAAM,CAAC,GACrB,OAAO,CAAC;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,OAAO,CAAA;CAAE,CAAC,CAoEvD;AAED,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,aAAa,EACrB,OAAO,EAAE,gBAAgB,EAAE,EAC3B,kBAAkB,EAAE,qBAAqB,EAAE,GAC1C,OAAO,CAAC;IAAE,iBAAiB,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,OAAO,CAAA;CAAE,CAAC,CAiI7D"}

package/dist/commands/sync/persistence.js

@@ -39,27 +39,31 @@ const STRING_FIELDS = new Set([
 ]);
 const NUMBER_FIELDS = new Set(["value_int", "value_number"]);
 const BOOLEAN_FIELDS = new Set(["value_bool", "closed_world"]);
+function getEntityField(entity, field) {
+    // ExtractedEntity declares all fact fields as optional properties, so indexing
+    // via keyof is safe. The cast is confined to this single helper.
+    return entity[field];
+}
 // Serialize typed fact fields from entity
 function serializeTypedFactFields(entity) {
     const fields = [];
-    const entityRecord = entity;
     // String fields (safely escaped double-quoted Prolog strings)
     for (const field of STRING_FIELDS) {
-        const value = entityRecord[field];
+        const value = getEntityField(entity, field);
         if (value !== undefined && value !== null) {
             fields.push(`${field}=${toPrologString(String(value))}`);
         }
     }
     // Atom fields (possibly unquoted if simple)
     for (const field of ATOM_FIELDS) {
-        const value = entityRecord[field];
+        const value = getEntityField(entity, field);
         if (value !== undefined && value !== null) {
             fields.push(`${field}=${toPrologAtom(String(value))}`);
         }
     }
     // Number fields (unquoted); value_int must be a true integer
     for (const field of NUMBER_FIELDS) {
-        const value = entityRecord[field];
+        const value = getEntityField(entity, field);
         if (value !== undefined && value !== null && typeof value === "number") {
             if (field === "value_int" && !Number.isInteger(value)) {
                 continue; // silently drop non-integer value_int
@@ -69,7 +73,7 @@ function serializeTypedFactFields(entity) {
     }
     // Boolean fields (true/false atoms)
     for (const field of BOOLEAN_FIELDS) {
-        const value = entityRecord[field];
+        const value = getEntityField(entity, field);
         if (value !== undefined && value !== null && typeof value === "boolean") {
             fields.push(`${field}=${value}`);
         }

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

@@ -1,4 +1,20 @@
-export declare function prepareStagingEnvironment(stagingPath: string, livePath: string, rebuild: boolean): Promise<void>;
-export declare function atomicPublish(stagingPath: string, livePath: string): void;
-export declare function cleanupStaging(stagingPath: string): void;
+import { existsSync, mkdirSync, renameSync, rmSync } from "node:fs";
+import { copyFileSync } from "node:fs";
+import fg from "fast-glob";
+import { copyCleanSnapshot } from "../../utils/branch-resolver.js";
+interface StagingDeps {
+    copyCleanSnapshot: typeof copyCleanSnapshot;
+    copyFileSync: typeof copyFileSync;
+    cwd: () => string;
+    existsSync: typeof existsSync;
+    fg: typeof fg;
+    mkdirSync: typeof mkdirSync;
+    moduleDir: string;
+    renameSync: typeof renameSync;
+    rmSync: typeof rmSync;
+}
+export declare function prepareStagingEnvironment(stagingPath: string, livePath: string, rebuild: boolean, deps?: Partial<StagingDeps>): Promise<void>;
+export declare function atomicPublish(stagingPath: string, livePath: string, deps?: Partial<StagingDeps>): void;
+export declare function cleanupStaging(stagingPath: string, deps?: Partial<StagingDeps>): void;
+export {};
 //# sourceMappingURL=staging.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"staging.d.ts","sourceRoot":"","sources":["../../../src/commands/sync/staging.ts"],"names":[],"mappings":"AAwBA,wBAAsB,yBAAyB,CAC7C,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,OAAO,GACf,OAAO,CAAC,IAAI,CAAC,CAYf;AAuCD,wBAAgB,aAAa,CAAC,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAczE;AAED,wBAAgB,cAAc,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAIxD"}
+{"version":3,"file":"staging.d.ts","sourceRoot":"","sources":["../../../src/commands/sync/staging.ts"],"names":[],"mappings":"AAkBA,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AACpE,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAEvC,OAAO,EAAE,MAAM,WAAW,CAAC;AAC3B,OAAO,EAAE,iBAAiB,EAAE,MAAM,gCAAgC,CAAC;AAEnE,UAAU,WAAW;IACnB,iBAAiB,EAAE,OAAO,iBAAiB,CAAC;IAC5C,YAAY,EAAE,OAAO,YAAY,CAAC;IAClC,GAAG,EAAE,MAAM,MAAM,CAAC;IAClB,UAAU,EAAE,OAAO,UAAU,CAAC;IAC9B,EAAE,EAAE,OAAO,EAAE,CAAC;IACd,SAAS,EAAE,OAAO,SAAS,CAAC;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,OAAO,UAAU,CAAC;IAC9B,MAAM,EAAE,OAAO,MAAM,CAAC;CACvB;AAiBD,wBAAsB,yBAAyB,CAE7C,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,OAAO,EAChB,IAAI,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,GAC1B,OAAO,CAAC,IAAI,CAAC,CAaf;AA0CD,wBAAgB,aAAa,CAE3B,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,EAChB,IAAI,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,GAC1B,IAAI,CAeN;AAED,wBAAgB,cAAc,CAE5B,WAAW,EAAE,MAAM,EACnB,IAAI,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,GAC1B,IAAI,CAKN"}

package/dist/commands/sync/staging.js

@@ -20,29 +20,46 @@ import { copyFileSync } from "node:fs";
 import * as path from "node:path";
 import fg from "fast-glob";
 import { copyCleanSnapshot } from "../../utils/branch-resolver.js";
-export async function prepareStagingEnvironment(stagingPath, livePath, rebuild) {
+function resolveDeps(overrides) {
+    return {
+        copyCleanSnapshot,
+        copyFileSync,
+        cwd: () => process.cwd(),
+        existsSync,
+        fg,
+        mkdirSync,
+        moduleDir: import.meta.dirname,
+        renameSync,
+        rmSync,
+        ...overrides,
+    };
+}
+export async function prepareStagingEnvironment(
+// implements REQ-003
+stagingPath, livePath, rebuild, deps) {
+    const resolved = resolveDeps(deps);
     // Cleanup any existing staging directory
-    cleanupStaging(stagingPath);
-    mkdirSync(stagingPath, { recursive: true });
-    if (!rebuild && existsSync(livePath)) {
+    cleanupStaging(stagingPath, resolved);
+    resolved.mkdirSync(stagingPath, { recursive: true });
+    if (!rebuild && resolved.existsSync(livePath)) {
         // Use existing live path if available
-        copyCleanSnapshot(livePath, stagingPath);
+        resolved.copyCleanSnapshot(livePath, stagingPath);
     }
     else {
         // Start fresh with schema only
-        await copySchemaToStaging(stagingPath);
+        await copySchemaToStaging(stagingPath, resolved);
     }
 }
-async function copySchemaToStaging(stagingPath) {
+async function copySchemaToStaging(stagingPath, deps) {
     const possibleSchemaPaths = [
-        path.resolve(process.cwd(), "node_modules", "kibi-cli", "schema"),
-        path.resolve(process.cwd(), "..", "..", "schema"),
-        path.resolve(import.meta.dirname || __dirname, "..", "..", "schema"),
-        path.resolve(process.cwd(), "packages", "cli", "schema"),
+        path.resolve(deps.cwd(), "node_modules", "kibi-cli", "schema"),
+        path.resolve(deps.cwd(), "..", "..", "schema"),
+        path.resolve(deps.moduleDir, "..", "..", "schema"),
+        path.resolve(deps.cwd(), "packages", "cli", "schema"),
     ];
     let schemaSourceDir = null;
     for (const p of possibleSchemaPaths) {
-        if (existsSync(p)) {
+        if (deps.existsSync(p)) {
             schemaSourceDir = p;
             break;
         }
@@ -50,37 +67,43 @@ async function copySchemaToStaging(stagingPath) {
     if (!schemaSourceDir) {
         return;
     }
-    const schemaFiles = await fg("*.pl", {
+    const schemaFiles = await deps.fg("*.pl", {
         cwd: schemaSourceDir,
         absolute: false,
     });
     const schemaDestDir = path.join(stagingPath, "schema");
-    if (!existsSync(schemaDestDir)) {
-        mkdirSync(schemaDestDir, { recursive: true });
+    if (!deps.existsSync(schemaDestDir)) {
+        deps.mkdirSync(schemaDestDir, { recursive: true });
     }
     for (const file of schemaFiles) {
         const sourcePath = path.join(schemaSourceDir, file);
         const destPath = path.join(schemaDestDir, file);
-        copyFileSync(sourcePath, destPath);
+        deps.copyFileSync(sourcePath, destPath);
     }
 }
-export function atomicPublish(stagingPath, livePath) {
+export function atomicPublish(
+// implements REQ-003
+stagingPath, livePath, deps) {
+    const resolved = resolveDeps(deps);
     const liveParent = path.dirname(livePath);
-    if (!existsSync(liveParent)) {
-        mkdirSync(liveParent, { recursive: true });
+    if (!resolved.existsSync(liveParent)) {
+        resolved.mkdirSync(liveParent, { recursive: true });
     }
-    if (existsSync(livePath)) {
+    if (resolved.existsSync(livePath)) {
         const tempPath = `${livePath}.old.${Date.now()}`;
-        renameSync(livePath, tempPath);
-        renameSync(stagingPath, livePath);
-        rmSync(tempPath, { recursive: true, force: true });
+        resolved.renameSync(livePath, tempPath);
+        resolved.renameSync(stagingPath, livePath);
+        resolved.rmSync(tempPath, { recursive: true, force: true });
     }
     else {
-        renameSync(stagingPath, livePath);
+        resolved.renameSync(stagingPath, livePath);
     }
 }
-export function cleanupStaging(stagingPath) {
-    if (existsSync(stagingPath)) {
-        rmSync(stagingPath, { recursive: true, force: true });
+export function cleanupStaging(
+// implements REQ-003
+stagingPath, deps) {
+    const resolved = resolveDeps(deps);
+    if (resolved.existsSync(stagingPath)) {
+        resolved.rmSync(stagingPath, { recursive: true, force: true });
     }
 }

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

@@ -1 +1 @@
-{"version":3,"file":"sync.d.ts","sourceRoot":"","sources":["../../src/commands/sync.ts"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EAAc,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAyCjE,qBAAa,SAAU,SAAQ,KAAK;gBACtB,OAAO,EAAE,MAAM;CAI5B;AAGD,MAAM,WAAW,UAAW,SAAQ,WAAW;IAC7C,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAGD,wBAAsB,WAAW,CAC/B,OAAO,GAAE;IACP,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,OAAO,CAAC,EAAE,OAAO,CAAC;CACd,GACL,OAAO,CAAC,UAAU,CAAC,CAmZrB;AAED,OAAO,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC"}
+{"version":3,"file":"sync.d.ts","sourceRoot":"","sources":["../../src/commands/sync.ts"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EAAc,WAAW,EAAE,MAAM,mBAAmB,CAAC;AA0CjE,qBAAa,SAAU,SAAQ,KAAK;gBACtB,OAAO,EAAE,MAAM;CAI5B;AAGD,MAAM,WAAW,UAAW,SAAQ,WAAW;IAC7C,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAGD,wBAAsB,WAAW,CAC/B,OAAO,GAAE;IAAE,YAAY,CAAC,EAAE,OAAO,CAAC;IAAC,OAAO,CAAC,EAAE,OAAO,CAAA;CAAO,GAC1D,OAAO,CAAC,UAAU,CAAC,CAqarB;AAED,OAAO,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/commands/sync.js

@@ -19,6 +19,7 @@ import { execSync } from "node:child_process";
 import { existsSync } from "node:fs";
 import * as path from "node:path";
 import { branchErrorToDiagnostic, createDocsNotIndexedDiagnostic, createInvalidAuthoringDiagnostic, createKbMissingDiagnostic, formatSyncSummary, } from "../diagnostics.js";
+import { isCliDebugEnabled } from "../env.js";
 import { extractFromRelationshipShards, flattenRelationships, validateRelationships, } from "../extractors/relationships.js";
 import { PrologProcess } from "../prolog.js";
 import { resolveActiveBranch, } from "../utils/branch-resolver.js";
@@ -57,6 +58,7 @@ export async function syncCommand(options = {}) {
             return undefined;
         }
     };
+    const withOptionalCommit = (value, commit) => commit !== undefined ? { ...value, commit } : value;
     try {
         // Branch resolution
         const branchResult = resolveActiveBranch(process.cwd());
@@ -67,14 +69,14 @@ export async function syncCommand(options = {}) {
             throw new SyncError(`Failed to resolve active branch: ${branchResult.error}`);
         }
         currentBranch = branchResult.branch;
-        if (process.env.KIBI_DEBUG) {
+        if (isCliDebugEnabled()) {
             // eslint-disable-next-line no-console
             console.log("[kibi-debug] currentBranch:", currentBranch);
         }
         const config = loadSyncConfig(process.cwd());
         const paths = config.paths;
         const { markdownFiles, manifestFiles, relationshipsDir } = await discoverSourceFiles(process.cwd(), paths);
-        if (process.env.KIBI_DEBUG) {
+        if (isCliDebugEnabled()) {
             // eslint-disable-next-line no-console
             console.log("[kibi-debug] markdownFiles:", markdownFiles.length);
             // eslint-disable-next-line no-console
@@ -152,9 +154,8 @@ export async function syncCommand(options = {}) {
                 console.error(`${err.file}: ${err.message}`);
             }
             console.error(`FAILED: ${errors.length} errors found`);
-            return {
+            return withOptionalCommit({
                 branch: currentBranch,
-                commit: getCurrentCommit(),
                 timestamp: new Date().toISOString(),
                 entityCounts,
                 relationshipCount: 0,
@@ -163,7 +164,7 @@ export async function syncCommand(options = {}) {
                 failures: diagnostics,
                 durationMs: Date.now() - startTime,
                 exitCode: 1,
-            };
+            }, getCurrentCommit());
         }
         if (results.length === 0 && allRelationships.length === 0 && !rebuild) {
             const evictedHashes = {};
@@ -181,9 +182,8 @@ export async function syncCommand(options = {}) {
                 seenAt: evictedSeenAt,
             });
             console.log("✓ Imported 0 entities, 0 relationships (no changes)");
-            return {
+            return withOptionalCommit({
                 branch: currentBranch,
-                commit: getCurrentCommit(),
                 timestamp: new Date().toISOString(),
                 entityCounts,
                 relationshipCount: 0,
@@ -192,7 +192,7 @@ export async function syncCommand(options = {}) {
                 failures: diagnostics,
                 durationMs: Date.now() - startTime,
                 exitCode: 0,
-            };
+            }, getCurrentCommit());
         }
         const livePath = path.join(process.cwd(), `.kb/branches/${currentBranch}`);
         const kbExists = existsSync(livePath);
@@ -235,9 +235,8 @@ export async function syncCommand(options = {}) {
                         console.error(`${err.file}: ${err.message}`);
                     }
                     console.error(`FAILED: ${errors.length} errors found`);
-                    return {
+                    return withOptionalCommit({
                         branch: currentBranch,
-                        commit: getCurrentCommit(),
                         timestamp: new Date().toISOString(),
                         entityCounts,
                         relationshipCount: 0,
@@ -246,12 +245,11 @@ export async function syncCommand(options = {}) {
                         failures: diagnostics,
                         durationMs: Date.now() - startTime,
                         exitCode: 1,
-                    };
+                    }, getCurrentCommit());
                 }
                 console.log(`OK: Validation passed (${entityCount} entities)`);
-                return {
+                return withOptionalCommit({
                     branch: currentBranch,
-                    commit: getCurrentCommit(),
                     timestamp: new Date().toISOString(),
                     entityCounts,
                     relationshipCount: 0,
@@ -260,7 +258,7 @@ export async function syncCommand(options = {}) {
                     failures: diagnostics,
                     durationMs: Date.now() - startTime,
                     exitCode: 0,
-                };
+                }, getCurrentCommit());
             }
             if (kbModified) {
                 prolog.invalidateCache();
@@ -295,9 +293,8 @@ export async function syncCommand(options = {}) {
             }
             console.log(`✓ Imported ${entityCount} entities, ${relationshipCount} relationships`);
             const commit = getCurrentCommit();
-            const summary = {
+            const summary = withOptionalCommit({
                 branch: currentBranch,
-                commit,
                 timestamp: new Date().toISOString(),
                 entityCounts,
                 relationshipCount,
@@ -305,7 +302,7 @@ export async function syncCommand(options = {}) {
                 published,
                 failures: diagnostics,
                 durationMs: Date.now() - startTime,
-            };
+            }, commit);
             console.log(formatSyncSummary(summary));
             return { ...summary, exitCode: 0 };
         }
@@ -318,9 +315,8 @@ export async function syncCommand(options = {}) {
         const errorMessage = error instanceof Error ? error.message : String(error);
         console.error(`Error: ${errorMessage}`);
         const commit = getCurrentCommit();
-        const summary = {
+        const summary = withOptionalCommit({
             branch: currentBranch || "unknown",
-            commit,
             timestamp: new Date().toISOString(),
             entityCounts,
             relationshipCount: 0,
@@ -328,7 +324,7 @@ export async function syncCommand(options = {}) {
             published: false,
             failures: diagnostics,
             durationMs: Date.now() - startTime,
-        };
+        }, commit);
         if (diagnostics.length > 0) {
             console.log("\nDiagnostics:");
             for (const d of diagnostics) {

package/dist/diagnostics.d.ts

@@ -28,21 +28,12 @@ export interface SyncSummary {
  * Branch resolution error codes mapping to diagnostic categories
  */
 export type BranchErrorCode = "DETACHED_HEAD" | "UNBORN_BRANCH" | "GIT_NOT_AVAILABLE" | "NOT_A_GIT_REPO" | "ENV_OVERRIDE" | "UNKNOWN_ERROR";
-/**
- * Convert branch error code to diagnostic category
- */
-export declare function branchErrorToDiagnostic(code: BranchErrorCode, message: string, branch?: string): Diagnostic;
+export declare function branchErrorToDiagnostic(_code: BranchErrorCode, message: string, branch?: string): Diagnostic;
 /**
  * Create KB_MISSING diagnostic
  */
 export declare function createKbMissingDiagnostic(branch: string, path: string): Diagnostic;
-/**
- * Create DOCS_NOT_INDEXED diagnostic
- */
 export declare function createDocsNotIndexedDiagnostic(docCount: number, entityCount: number): Diagnostic;
-/**
- * Create INVALID_AUTHORING diagnostic for embedded entities
- */
 export declare function createInvalidAuthoringDiagnostic(filePath: string, embeddedTypes: string[]): Diagnostic;
 /**
  * Format sync summary for CLI output

package/dist/diagnostics.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"diagnostics.d.ts","sourceRoot":"","sources":["../src/diagnostics.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,MAAM,kBAAkB,GAC1B,2BAA2B,GAC3B,YAAY,GACZ,kBAAkB,GAClB,mBAAmB,GACnB,YAAY,GACZ,kBAAkB,GAClB,oBAAoB,CAAC;AAEzB,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,kBAAkB,CAAC;IAC7B,QAAQ,EAAE,OAAO,GAAG,SAAS,CAAC;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACrC,iBAAiB,EAAE,MAAM,CAAC;IAC1B,OAAO,EAAE,OAAO,CAAC;IACjB,SAAS,EAAE,OAAO,CAAC;IACnB,QAAQ,EAAE,UAAU,EAAE,CAAC;IACvB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,MAAM,eAAe,GACvB,eAAe,GACf,eAAe,GACf,mBAAmB,GACnB,gBAAgB,GAChB,cAAc,GACd,eAAe,CAAC;AAEpB;;GAEG;AACH,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,eAAe,EACrB,OAAO,EAAE,MAAM,EACf,MAAM,CAAC,EAAE,MAAM,GACd,UAAU,CASZ;AAED;;GAEG;AACH,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,GACX,UAAU,CAOZ;AAED;;GAEG;AACH,wBAAgB,8BAA8B,CAC5C,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,MAAM,GAClB,UAAU,CAQZ;AAED;;GAEG;AACH,wBAAgB,gCAAgC,CAC9C,QAAQ,EAAE,MAAM,EAChB,aAAa,EAAE,MAAM,EAAE,GACtB,UAAU,CAQZ;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,WAAW,GAAG,MAAM,CAiD9D;AAED;;GAEG;AACH,wBAAgB,uBAAuB,CAAC,WAAW,EAAE,UAAU,EAAE,GAAG,KAAK,CAAC;IACxE,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,CAAC,CAQD"}
+{"version":3,"file":"diagnostics.d.ts","sourceRoot":"","sources":["../src/diagnostics.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,MAAM,kBAAkB,GAC1B,2BAA2B,GAC3B,YAAY,GACZ,kBAAkB,GAClB,mBAAmB,GACnB,YAAY,GACZ,kBAAkB,GAClB,oBAAoB,CAAC;AAEzB,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,kBAAkB,CAAC;IAC7B,QAAQ,EAAE,OAAO,GAAG,SAAS,CAAC;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACrC,iBAAiB,EAAE,MAAM,CAAC;IAC1B,OAAO,EAAE,OAAO,CAAC;IACjB,SAAS,EAAE,OAAO,CAAC;IACnB,QAAQ,EAAE,UAAU,EAAE,CAAC;IACvB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,MAAM,eAAe,GACvB,eAAe,GACf,eAAe,GACf,mBAAmB,GACnB,gBAAgB,GAChB,cAAc,GACd,eAAe,CAAC;AAEpB,wBAAgB,uBAAuB,CAErC,KAAK,EAAE,eAAe,EACtB,OAAO,EAAE,MAAM,EACf,MAAM,CAAC,EAAE,MAAM,GACd,UAAU,CASZ;AAED;;GAEG;AACH,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,GACX,UAAU,CAOZ;AAED,wBAAgB,8BAA8B,CAC5C,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,MAAM,GAClB,UAAU,CAQZ;AAED,wBAAgB,gCAAgC,CAC9C,QAAQ,EAAE,MAAM,EAChB,aAAa,EAAE,MAAM,EAAE,GACtB,UAAU,CAQZ;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,WAAW,GAAG,MAAM,CAiD9D;AAED;;GAEG;AACH,wBAAgB,uBAAuB,CAAC,WAAW,EAAE,UAAU,EAAE,GAAG,KAAK,CAAC;IACxE,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,CAAC,CASD"}

package/dist/diagnostics.js

@@ -5,10 +5,9 @@
  * making it easier for both CLI users and MCP consumers to understand
  * and respond to issues programmatically.
  */
-/**
- * Convert branch error code to diagnostic category
- */
-export function branchErrorToDiagnostic(code, message, branch) {
+export function branchErrorToDiagnostic(
+// implements REQ-008
+_code, message, branch) {
     return {
         category: "BRANCH_RESOLUTION_FAILURE",
         severity: "error",
@@ -29,9 +28,6 @@ export function createKbMissingDiagnostic(branch, path) {
         suggestion: `Run 'kibi sync' to create the KB at ${path}`,
     };
 }
-/**
- * Create DOCS_NOT_INDEXED diagnostic
- */
 export function createDocsNotIndexedDiagnostic(docCount, entityCount) {
     return {
         category: "DOCS_NOT_INDEXED",
@@ -40,9 +36,6 @@ export function createDocsNotIndexedDiagnostic(docCount, entityCount) {
         suggestion: "Some documents may have extraction errors. Run 'kibi sync --validate-only' to check.",
     };
 }
-/**
- * Create INVALID_AUTHORING diagnostic for embedded entities
- */
 export function createInvalidAuthoringDiagnostic(filePath, embeddedTypes) {
     return {
         category: "INVALID_AUTHORING",
@@ -102,11 +95,12 @@ export function formatSyncSummary(summary) {
  * Format diagnostics for MCP structured response
  */
 export function formatDiagnosticsForMcp(diagnostics) {
+    // implements REQ-003
     return diagnostics.map((d) => ({
         category: d.category,
         severity: d.severity,
         message: d.message,
-        file: d.file,
-        suggestion: d.suggestion,
+        ...(d.file !== undefined ? { file: d.file } : {}),
+        ...(d.suggestion !== undefined ? { suggestion: d.suggestion } : {}),
     }));
 }

package/dist/env.d.ts

@@ -0,0 +1,7 @@
+export declare function getBranchOverride(): string | undefined;
+export declare function getKbPlPathOverride(): string | undefined;
+export declare function isCliDebugEnabled(): boolean;
+export declare function isCliTraceEnabled(): boolean;
+export declare function isCliTraceOrDebugEnabled(): boolean;
+export declare function isPrologDebugEnabled(): boolean;
+//# sourceMappingURL=env.d.ts.map

package/dist/env.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.d.ts","sourceRoot":"","sources":["../src/env.ts"],"names":[],"mappings":"AAoBA,wBAAgB,iBAAiB,IAAI,MAAM,GAAG,SAAS,CAGtD;AAED,wBAAgB,mBAAmB,IAAI,MAAM,GAAG,SAAS,CAGxD;AAED,wBAAgB,iBAAiB,IAAI,OAAO,CAG3C;AAED,wBAAgB,iBAAiB,IAAI,OAAO,CAG3C;AAED,wBAAgB,wBAAwB,IAAI,OAAO,CAGlD;AAED,wBAAgB,oBAAoB,IAAI,OAAO,CAG9C"}

package/dist/env.js

@@ -0,0 +1,41 @@
+/*
+ * 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.
+ */
+function getEnvValue(key) {
+    const value = process.env[key];
+    return typeof value === "string" ? value : undefined;
+}
+function getTrimmedEnvValue(key) {
+    const value = getEnvValue(key)?.trim();
+    return value ? value : undefined;
+}
+export function getBranchOverride() {
+    // implements REQ-003
+    return getTrimmedEnvValue("KIBI_BRANCH");
+}
+export function getKbPlPathOverride() {
+    // implements REQ-003
+    return getEnvValue("KIBI_KB_PL_PATH");
+}
+export function isCliDebugEnabled() {
+    // implements REQ-003
+    return Boolean(getEnvValue("KIBI_DEBUG"));
+}
+export function isCliTraceEnabled() {
+    // implements REQ-003
+    return Boolean(getEnvValue("KIBI_TRACE"));
+}
+export function isCliTraceOrDebugEnabled() {
+    // implements REQ-003
+    return isCliTraceEnabled() || isCliDebugEnabled();
+}
+export function isPrologDebugEnabled() {
+    // implements REQ-003
+    return Boolean(getEnvValue("KIBI_PROLOG_DEBUG"));
+}

package/dist/extractors/manifest.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../../src/extractors/manifest.ts"],"names":[],"mappings":"AAsBA,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;CACZ;AAED,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,eAAe,CAAC;IACxB,aAAa,EAAE,qBAAqB,EAAE,CAAC;IACvC,6EAA6E;IAC7E,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,qBAAa,aAAc,SAAQ,KAAK;IAG7B,QAAQ,EAAE,MAAM;gBADvB,OAAO,EAAE,MAAM,EACR,QAAQ,EAAE,MAAM;CAK1B;AA6GD,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,GACf,gBAAgB,EAAE,CAmBpB;AAED,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,gBAAgB,EAAE,CAGxE"}
+{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../../src/extractors/manifest.ts"],"names":[],"mappings":"AAsBA,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;CACZ;AAED,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,eAAe,CAAC;IACxB,aAAa,EAAE,qBAAqB,EAAE,CAAC;IACvC,6EAA6E;IAC7E,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,qBAAa,aAAc,SAAQ,KAAK;IAG7B,QAAQ,EAAE,MAAM;gBADvB,OAAO,EAAE,MAAM,EACR,QAAQ,EAAE,MAAM;CAK1B;AA+GD,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,GACf,gBAAgB,EAAE,CAmBpB;AAED,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,gBAAgB,EAAE,CAGxE"}