kibi-mcp 0.13.0 → 0.14.0

package/dist/tools/delete.js

@@ -1,4 +1,5 @@
 import { escapeAtom, parseEntityFromList, parseListOfLists } from "kibi-cli/prolog/codec";
+import { writeBriefPendingMarker } from "../utils/brief-marker.js";
 /**
  * Handle kb.delete tool calls
  * Prevents deletion of entities with dependents (referential integrity)
@@ -12,6 +13,8 @@ prolog, args) {
     let deleted = 0;
     let skipped = 0;
     const errors = [];
+    const pendingEntityIds = [];
+    const pendingRelationships = [];
     try {
         for (const id of ids) {
             const safeId = escapeAtom(id);
@@ -42,6 +45,7 @@ prolog, args) {
             }
             // No dependents, safe to delete
             const entityMetadata = await loadEntityMetadataForDelete(prolog, id, safeId);
+            const relationships = await loadOutgoingRelationshipsForDelete(prolog, safeId);
             const deleteGoal = buildDeleteGoal(safeId, entityMetadata);
             const deleteResult = await prolog.query(deleteGoal);
             if (!deleteResult.success) {
@@ -50,6 +54,8 @@ prolog, args) {
             }
             else {
                 deleted++;
+                pendingEntityIds.push(id);
+                pendingRelationships.push(...relationships);
             }
         }
         // Save KB to disk
@@ -57,6 +63,14 @@ prolog, args) {
         if (!saveResult.success) {
             throw new Error(`Failed to save KB after delete: ${saveResult.error || "Unknown error"}`);
         }
+        if (pendingEntityIds.length > 0 || pendingRelationships.length > 0) {
+            writeBriefPendingMarker({
+                ...(args._requestId ? { sessionId: args._requestId } : {}),
+                operation: "delete",
+                entityIds: pendingEntityIds,
+                relationships: pendingRelationships,
+            });
+        }
         prolog.invalidateCache();
         return {
             content: [
@@ -91,6 +105,38 @@ async function loadEntityMetadataForDelete(prolog, id, safeId) {
     const { id: _entityId, type: _entityType, ...props } = entity;
     return { type, props };
 }
+async function loadOutgoingRelationshipsForDelete(prolog, safeId) {
+    const result = await prolog.query(`findall([Type,'${safeId}',To], (member(Type, [depends_on, verified_by, validates, specified_by, relates_to, guards, publishes, consumes, implements, covered_by, executable_for, constrains, requires_property, supersedes, constrained_by]), kb_relationship(Type, '${safeId}', To)), Relationships)`);
+    if (!result.success) {
+        throw new Error(`Failed to load outgoing relationships for entity ${safeId}: ${result.error || "Unknown error"}`);
+    }
+    const rows = result.bindings.Relationships
+        ? parseListOfLists(result.bindings.Relationships)
+        : [];
+    return rows.flatMap((row) => {
+        const type = row[0];
+        const from = row[1];
+        const to = row[2];
+        if (type === undefined || from === undefined || to === undefined) {
+            return [];
+        }
+        return [
+            {
+                type: normalizeDeleteRelationshipValue(type),
+                from: normalizeDeleteRelationshipValue(from),
+                to: normalizeDeleteRelationshipValue(to),
+            },
+        ];
+    });
+}
+function normalizeDeleteRelationshipValue(value) {
+    const normalized = String(value);
+    if ((normalized.startsWith("'") && normalized.endsWith("'")) ||
+        (normalized.startsWith('"') && normalized.endsWith('"'))) {
+        return normalized.slice(1, -1);
+    }
+    return normalized;
+}
 function buildDeleteGoal(safeId, metadata) {
     const auditProps = [`id='${safeId}'`, ...serializeDeleteProps(metadata.props)];
     return `kb_retract_entity('${safeId}', ${metadata.type}, [${auditProps.join(", ")}])`;

package/dist/tools/symbols.js

@@ -20,19 +20,16 @@ import path from "node:path";
 import { dump as dumpYAML, load as parseYAML } from "js-yaml";
 import { enrichSymbolCoordinates, } from "kibi-cli/extractors/symbols-coordinator";
 import { resolveWorkspaceRoot } from "../workspace.js";
-const COMMENT_BLOCK = `# symbols.yaml
-# AUTHORED fields (edit freely):
-#   id, title, sourceFile, links, status, tags, owner, priority
-# GENERATED fields (never edit manually — overwritten by kibi sync and kb_symbols_refresh):
-#   sourceLine, sourceColumn, sourceEndLine, sourceEndColumn, coordinatesGeneratedAt
-# Run \`kibi sync\` or call the \`kb_symbols_refresh\` MCP tool to refresh coordinates.
+const SYMBOL_COORDINATES_COMMENT_BLOCK = `# symbol-coordinates.yaml
+# GENERATED coordinate artifact — do not edit manually.
+# Run \`kibi sync --refresh-symbol-coordinates\` to refresh.
 `;
+const DEFAULT_COORDINATE_ARTIFACT_NAME = "symbol-coordinates.yaml";
 const GENERATED_COORD_FIELDS = [
     "sourceLine",
     "sourceColumn",
     "sourceEndLine",
     "sourceEndColumn",
-    "coordinatesGeneratedAt",
 ];
 const SOURCE_EXTENSIONS = new Set([
     ".ts",
@@ -48,7 +45,7 @@ export async function handleKbSymbolsRefresh(args) {
     // implements REQ-vscode-traceability
     const dryRun = args.dryRun === true;
     const workspaceRoot = args.workspaceRoot ?? resolveWorkspaceRoot();
-    const manifestPath = await resolveManifestPath(workspaceRoot);
+    const { coordinatesPath, manifestPath } = await resolveManifestPaths(workspaceRoot);
     const rawContent = await readFile(manifestPath, "utf8");
     const parsed = parseYAML(rawContent);
     if (!isRecord(parsed) || !Array.isArray(parsed.symbols)) {
@@ -89,20 +86,16 @@ export async function handleKbSymbolsRefresh(args) {
             unchanged++;
         }
     }
-    const dumped = dumpYAML(parsed, {
-        lineWidth: -1,
-        noRefs: true,
-        sortKeys: false,
-    });
-    const nextContent = `${COMMENT_BLOCK}${dumped}`;
-    if (!dryRun && rawContent !== nextContent) {
-        await writeFile(manifestPath, nextContent, "utf8");
+    const nextCoordinates = writeCoordinateArtifact(buildCoordinatesMap(finalized));
+    const currentCoordinates = await readOptionalTextFile(coordinatesPath);
+    if (!dryRun && currentCoordinates !== nextCoordinates) {
+        await writeFile(coordinatesPath, nextCoordinates, "utf8");
     }
     return {
         content: [
             {
                 type: "text",
-                text: `kb_symbols_refresh ${dryRun ? "(dry run) " : ""}completed for ${path.relative(workspaceRoot, manifestPath)}: refreshed=${refreshed}, unchanged=${unchanged}, failed=${failed}`,
+                text: `kb_symbols_refresh ${dryRun ? "(dry run) " : ""}completed for ${path.relative(workspaceRoot, coordinatesPath)}: refreshed=${refreshed}, unchanged=${unchanged}, failed=${failed}`,
             },
         ],
         structuredContent: {
@@ -115,7 +108,7 @@ export async function handleKbSymbolsRefresh(args) {
 }
 export async function refreshCoordinatesForSymbolId(symbolId, workspaceRoot = resolveWorkspaceRoot()) {
     // implements REQ-vscode-traceability
-    const manifestPath = await resolveManifestPath(workspaceRoot);
+    const { coordinatesPath, manifestPath } = await resolveManifestPaths(workspaceRoot);
     const rawContent = await readFile(manifestPath, "utf8");
     const parsed = parseYAML(rawContent);
     if (!isRecord(parsed) || !Array.isArray(parsed.symbols)) {
@@ -143,17 +136,30 @@ export async function refreshCoordinatesForSymbolId(symbolId, workspaceRoot = re
     symbols[index] = finalized;
     parsed.symbols = symbols;
     const refreshed = GENERATED_COORD_FIELDS.some((field) => original[field] !== finalized[field]);
-    const dumped = dumpYAML(parsed, {
-        lineWidth: -1,
-        noRefs: true,
-        sortKeys: false,
-    });
-    const nextContent = `${COMMENT_BLOCK}${dumped}`;
-    if (rawContent !== nextContent) {
-        await writeFile(manifestPath, nextContent, "utf8");
+    const artifact = await readCoordinateArtifactFromPath(coordinatesPath);
+    const nextCoordinates = {
+        ...artifact.coordinates,
+    };
+    const coordinatesRecord = toCoordinateRecord(finalized);
+    if (coordinatesRecord) {
+        nextCoordinates[symbolId] = coordinatesRecord;
+    }
+    if (coordinatesRecord || Object.keys(nextCoordinates).length > 0) {
+        const nextContent = writeCoordinateArtifact(nextCoordinates);
+        const currentContent = await readOptionalTextFile(coordinatesPath);
+        if (currentContent !== nextContent) {
+            await writeFile(coordinatesPath, nextContent, "utf8");
+        }
     }
     return { refreshed, found: true };
 }
+async function resolveManifestPaths(workspaceRoot) {
+    const manifestPath = await resolveManifestPath(workspaceRoot);
+    return {
+        manifestPath,
+        coordinatesPath: path.join(path.dirname(manifestPath), DEFAULT_COORDINATE_ARTIFACT_NAME),
+    };
+}
 export async function resolveManifestPath(workspaceRoot) {
     // implements REQ-002, REQ-013
     const configPath = path.join(workspaceRoot, ".kb", "config.json");
@@ -190,9 +196,7 @@ function hasGeneratedCoordinates(entry) {
     return (typeof entry.sourceLine === "number" &&
         typeof entry.sourceColumn === "number" &&
         typeof entry.sourceEndLine === "number" &&
-        typeof entry.sourceEndColumn === "number" &&
-        typeof entry.coordinatesGeneratedAt === "string" &&
-        entry.coordinatesGeneratedAt.length > 0);
+        typeof entry.sourceEndColumn === "number");
 }
 async function isEligible(sourceFile, workspaceRoot) {
     if (!sourceFile)
@@ -251,7 +255,6 @@ async function fillMissingCoordinates(before, after, workspaceRoot) {
                 sourceColumn: match.index,
                 sourceEndLine: index + 1,
                 sourceEndColumn: match.index + title.length,
-                coordinatesGeneratedAt: new Date().toISOString(),
             };
         }
     }
@@ -263,3 +266,86 @@ async function fillMissingCoordinates(before, after, workspaceRoot) {
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
+function normalizeCoordinateRecord(value) {
+    if (!isRecord(value)) {
+        return null;
+    }
+    const { sourceColumn, sourceEndColumn, sourceEndLine, sourceFile, sourceLine } = value;
+    if (typeof sourceFile !== "string" ||
+        typeof sourceLine !== "number" ||
+        typeof sourceColumn !== "number" ||
+        typeof sourceEndLine !== "number" ||
+        typeof sourceEndColumn !== "number") {
+        return null;
+    }
+    return {
+        sourceFile,
+        sourceLine,
+        sourceColumn,
+        sourceEndLine,
+        sourceEndColumn,
+    };
+}
+function sortCoordinates(coordinates) {
+    const sortedCoordinates = {};
+    for (const symbolId of Object.keys(coordinates).sort((left, right) => left.localeCompare(right))) {
+        const record = normalizeCoordinateRecord(coordinates[symbolId]);
+        if (!record) {
+            continue;
+        }
+        sortedCoordinates[symbolId] = record;
+    }
+    return sortedCoordinates;
+}
+function readCoordinateArtifact(content) {
+    const parsed = parseYAML(content);
+    if (!isRecord(parsed) || !isRecord(parsed.coordinates)) {
+        return { coordinates: {} };
+    }
+    const coordinates = {};
+    for (const [symbolId, record] of Object.entries(parsed.coordinates)) {
+        const normalizedRecord = normalizeCoordinateRecord(record);
+        if (!normalizedRecord) {
+            continue;
+        }
+        coordinates[symbolId] = normalizedRecord;
+    }
+    return { coordinates };
+}
+function writeCoordinateArtifact(coordinates) {
+    return `${SYMBOL_COORDINATES_COMMENT_BLOCK}${dumpYAML({ coordinates: sortCoordinates(coordinates) }, {
+        lineWidth: -1,
+        noRefs: true,
+        sortKeys: true,
+    })}`;
+}
+function toCoordinateRecord(entry) {
+    return normalizeCoordinateRecord(entry);
+}
+function buildCoordinatesMap(entries) {
+    const coordinates = {};
+    for (const entry of entries) {
+        const id = typeof entry.id === "string" ? entry.id : undefined;
+        const record = toCoordinateRecord(entry);
+        if (!id || !record) {
+            continue;
+        }
+        coordinates[id] = record;
+    }
+    return coordinates;
+}
+async function readCoordinateArtifactFromPath(coordinatesPath) {
+    const content = await readOptionalTextFile(coordinatesPath);
+    if (content === null) {
+        return { coordinates: {} };
+    }
+    return readCoordinateArtifact(content);
+}
+async function readOptionalTextFile(filePath) {
+    try {
+        return await readFile(filePath, "utf8");
+    }
+    catch {
+        return null;
+    }
+}

package/dist/tools/upsert.js

@@ -20,6 +20,7 @@ import { escapeAtom, toPrologAtom, toPrologString, } from "kibi-cli/prolog/codec
 import entitySchema from "kibi-cli/schemas/entity";
 import relationshipSchema from "kibi-cli/schemas/relationship";
 import { isMcpDebugEnabled } from "../env.js";
+import { writeBriefPendingMarker } from "../utils/brief-marker.js";
 import { refreshCoordinatesForSymbolId } from "./symbols.js";
 let refreshCoordinatesForSymbolIdImpl = refreshCoordinatesForSymbolId;
 const ajv = new Ajv({ strict: false });
@@ -155,6 +156,16 @@ export async function handleKbUpsert(prolog, args) {
         if (!saveResult.success) {
             throw new Error(`Failed to save KB after upsert: ${saveResult.error || "Unknown error"}`);
         }
+        writeBriefPendingMarker({
+            ...(args._requestId ? { sessionId: args._requestId } : {}),
+            operation: "upsert",
+            entityIds: [id],
+            relationships: relationships.map((rel) => ({
+                from: String(rel.from),
+                to: String(rel.to),
+                type: String(rel.type),
+            })),
+        });
         if (type === "symbol") {
             try {
                 await refreshCoordinatesForSymbolIdImpl(id);

package/dist/utils/brief-marker.js

@@ -0,0 +1,107 @@
+/*
+ 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 fs from "node:fs";
+import path from "node:path";
+import { resolveWorkspaceRoot } from "../workspace.js";
+// implements REQ-opencode-kibi-briefing-v2
+export function writeBriefPendingMarker(args) {
+    const workspaceRoot = resolveWorkspaceRoot();
+    const pendingDir = path.join(workspaceRoot, ".kb", "briefs", "pending");
+    fs.mkdirSync(pendingDir, { recursive: true });
+    const sessionId = normalizeSessionId(args.sessionId);
+    const existing = loadExistingMarker(pendingDir, sessionId);
+    const timestamp = existing?.payload.timestamp ?? Date.now();
+    const payload = {
+        sessionId,
+        timestamp,
+        branch: resolveMarkerBranch(workspaceRoot),
+        operation: args.operation,
+        entityIds: mergeUniqueStrings(existing?.payload.entityIds ?? [], args.entityIds),
+        relationships: mergeRelationships(existing?.payload.relationships ?? [], args.relationships ?? []),
+    };
+    const filePath = existing?.filePath ??
+        path.join(pendingDir, `${sanitizeSessionId(sessionId)}-${timestamp}.json`);
+    fs.writeFileSync(filePath, `${JSON.stringify(payload, null, 2)}\n`, "utf8");
+    return payload;
+}
+function loadExistingMarker(pendingDir, sessionId) {
+    const prefix = `${sanitizeSessionId(sessionId)}-`;
+    const matches = fs
+        .readdirSync(pendingDir, { withFileTypes: true })
+        .filter((entry) => entry.isFile())
+        .map((entry) => entry.name)
+        .filter((name) => name.startsWith(prefix) && name.endsWith(".json"))
+        .sort();
+    const latest = matches.at(-1);
+    if (!latest) {
+        return null;
+    }
+    const filePath = path.join(pendingDir, latest);
+    const raw = fs.readFileSync(filePath, "utf8");
+    return {
+        filePath,
+        payload: JSON.parse(raw),
+    };
+}
+function normalizeSessionId(sessionId) {
+    const normalized = sessionId?.trim();
+    return normalized && normalized.length > 0 ? normalized : "unknown";
+}
+function sanitizeSessionId(sessionId) {
+    return sessionId.replace(/[\\/:*?"<>|]+/g, "_");
+}
+function resolveMarkerBranch(workspaceRoot) {
+    const envBranch = process.env.KIBI_BRANCH?.trim();
+    if (envBranch) {
+        return envBranch;
+    }
+    const branchesDir = path.join(workspaceRoot, ".kb", "branches");
+    if (!fs.existsSync(branchesDir)) {
+        return "unknown";
+    }
+    const branches = fs
+        .readdirSync(branchesDir, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory())
+        .map((entry) => entry.name)
+        .sort();
+    return branches.length === 1 ? (branches[0] ?? "unknown") : "unknown";
+}
+function mergeUniqueStrings(existing, incoming) {
+    const merged = new Set();
+    for (const value of existing) {
+        if (value) {
+            merged.add(value);
+        }
+    }
+    for (const value of incoming) {
+        if (value) {
+            merged.add(value);
+        }
+    }
+    return [...merged];
+}
+function mergeRelationships(existing, incoming) {
+    const merged = new Map();
+    for (const relationship of [...existing, ...incoming]) {
+        if (!relationship.from || !relationship.to || !relationship.type) {
+            continue;
+        }
+        merged.set(`${relationship.type}\u0000${relationship.from}\u0000${relationship.to}`, relationship);
+    }
+    return [...merged.values()];
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kibi-mcp",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.26.0",
     "ajv": "^8.18.0",
@@ -9,7 +9,7 @@
     "fast-glob": "^3.2.12",
     "gray-matter": "^4.0.3",
     "js-yaml": "^4.1.0",
-    "kibi-cli": "^0.10.0",
+    "kibi-cli": "^0.11.0",
     "kibi-core": "^0.5.3",
     "mcpcat": "^0.1.12",
     "ts-morph": "^23.0.0",