kibi-mcp 0.3.0 → 0.3.2

package/dist/tools/upsert.js

@@ -27,6 +27,7 @@ const validateRelationship = ajv.compile(relationshipSchema);
  * Handle kb.upsert tool calls
  * Accepts { type, id, properties } — the flat format matching the tool schema.
  * Validates the assembled entity against JSON Schema before Prolog writes.
+ * implements REQ-002, REQ-011
  */
 export async function handleKbUpsert(prolog, args) {
     const { type, id, properties, relationships = [] } = args;
@@ -80,49 +81,56 @@ export async function handleKbUpsert(prolog, args) {
         for (const entity of entities) {
             const id = entity.id;
             const type = entity.type;
-            // Check if entity exists
+            // Check if entity exists before transaction (to determine created vs updated)
             const checkGoal = `once(kb_entity('${escapeAtom(id)}', _, _))`;
             const checkResult = await prolog.query(checkGoal);
             const isUpdate = checkResult.success;
             // Build property list for Prolog
             const props = buildPropertyList(entity);
-            // Assert entity (upsert)
+            // Build relationship goals
+            const relationshipGoals = [];
+            for (const rel of relationships) {
+                const relType = rel.type;
+                const from = rel.from;
+                const to = rel.to;
+                const metadata = buildRelationshipMetadata(rel);
+                relationshipGoals.push(`kb_assert_relationship(${relType}, '${escapeAtom(from)}', '${escapeAtom(to)}', ${metadata})`);
+            }
+            // Build atomic transaction goal wrapping entity + all relationships
+            // implements REQ-002, REQ-011
+            let transactionGoal;
+            if (relationshipGoals.length === 0) {
+                // Simple case: just entity
+                transactionGoal = `rdf_transaction((kb_assert_entity(${type}, ${props})))`;
+            }
+            else {
+                // Entity + relationships in one transaction
+                const goals = [
+                    `kb_assert_entity(${type}, ${props})`,
+                    ...relationshipGoals,
+                ].join(", ");
+                transactionGoal = `rdf_transaction((${goals}))`;
+            }
+            const txResult = await prolog.query(transactionGoal);
+            if (!txResult.success) {
+                throw new Error(`Failed to upsert entity ${id}: ${txResult.error || "Unknown error"} (goal: ${transactionGoal})`);
+            }
+            // Update counters
             if (isUpdate) {
-                // Update counter only. kb_assert_entity implements upsert semantics in Prolog.
                 updated++;
             }
             else {
                 created++;
             }
-            const assertGoal = `kb_assert_entity(${type}, ${props})`;
-            const assertResult = await prolog.query(assertGoal);
-            if (!assertResult.success) {
-                throw new Error(`Failed to assert entity ${id}: ${assertResult.error || "Unknown error"}`);
-            }
+            relationshipsCreated += relationships.length;
         }
-        // Process relationships
-        for (const rel of relationships) {
-            const relType = rel.type;
-            const from = rel.from;
-            const to = rel.to;
-            // Build metadata
-            const metadata = buildRelationshipMetadata(rel);
-            const relGoal = `kb_assert_relationship(${relType}, '${escapeAtom(from)}', '${escapeAtom(to)}', ${metadata})`;
-            const relResult = await prolog.query(relGoal);
-            if (!relResult.success) {
-                throw new Error(`Failed to assert relationship ${relType} from ${from} to ${to}: ${relResult.error || "Unknown error"}`);
-            }
-            relationshipsCreated++;
-        }
-        // Note: kb_save is intentionally NOT called here for performance.
-        // Callers that need durability across restarts should explicitly call kb_save.
-        // This allows batching multiple upserts before a single disk write.
-        prolog.invalidateCache();
-        // Save KB to disk to ensure durability across process restarts
-        await prolog.query("kb_save");
-        prolog.invalidateCache();
-        // multiple upserts and save once at the end for better performance.
+        // Save KB to disk after all entities/relationships are written to ensure
+        // durability across process restarts.
         prolog.invalidateCache();
+        const saveResult = await prolog.query("kb_save");
+        if (!saveResult.success) {
+            throw new Error(`Failed to save KB after upsert: ${saveResult.error || "Unknown error"}`);
+        }
         let contradictionPairsDetected;
         if (type === "req" && !args._skipContradictionCheck) {
             contradictionPairsDetected = await detectContradictionPairs(prolog, id);

package/dist/tools-config.js

@@ -16,6 +16,7 @@
  along with this program.  If not, see <https://www.gnu.org/licenses/>.
 */
 export const TOOLS = [
+    // implements REQ-002
     {
         name: "kb_query",
         description: "Read entities from the KB with filters. Use for discovery and lookup before edits. Do not use for writes. No mutation side effects. Tags filter by metadata tags only, not entity IDs.",
@@ -97,18 +98,7 @@ export const TOOLS = [
                         },
                         status: {
                             type: "string",
-                            enum: [
-                                "active",
-                                "draft",
-                                "archived",
-                                "deleted",
-                                "approved",
-                                "rejected",
-                                "pending",
-                                "in_progress",
-                                "superseded",
-                            ],
-                            description: "Required lifecycle state. Allowed values are fixed enum options. Example: 'active'.",
+                            description: "Required lifecycle state. Allowed values depend on entity type; backward-compatible legacy statuses are also accepted. Examples: 'open', 'passing', 'accepted', 'active'.",
                         },
                         source: {
                             type: "string",

package/dist/workspace.js

@@ -23,6 +23,7 @@ const WORKSPACE_ENV_KEYS = [
     "KIBI_ROOT",
 ];
 const KB_PATH_ENV_KEYS = ["KIBI_KB_PATH", "KB_PATH"];
+// implements REQ-002, REQ-012
 export function resolveWorkspaceRoot(startDir = process.cwd()) {
     const envRoot = readFirstEnv(WORKSPACE_ENV_KEYS);
     if (envRoot) {
@@ -38,21 +39,7 @@ export function resolveWorkspaceRoot(startDir = process.cwd()) {
     }
     return path.resolve(startDir);
 }
-export function resolveWorkspaceRootInfo(startDir = process.cwd()) {
-    const envRoot = readFirstEnv(WORKSPACE_ENV_KEYS);
-    if (envRoot) {
-        return { root: path.resolve(envRoot), reason: "env" };
-    }
-    const kbRoot = findUpwards(startDir, ".kb");
-    if (kbRoot) {
-        return { root: kbRoot, reason: "kb" };
-    }
-    const gitRoot = findUpwards(startDir, ".git");
-    if (gitRoot) {
-        return { root: gitRoot, reason: "git" };
-    }
-    return { root: path.resolve(startDir), reason: "cwd" };
-}
+// implements REQ-002, REQ-012
 export function resolveKbPath(workspaceRoot, branch) {
     const envPath = readFirstEnv(KB_PATH_ENV_KEYS);
     if (envPath) {
@@ -64,6 +51,7 @@ export function resolveKbPath(workspaceRoot, branch) {
     }
     return path.join(workspaceRoot, ".kb", "branches", branch);
 }
+// implements REQ-002
 export function resolveEnvFilePath(envFileName, workspaceRoot) {
     if (path.isAbsolute(envFileName)) {
         return envFileName;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kibi-mcp",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.26.0",
     "ajv": "^8.18.0",
@@ -9,8 +9,8 @@
     "fast-glob": "^3.2.12",
     "gray-matter": "^4.0.3",
     "js-yaml": "^4.1.0",
-    "kibi-cli": "^0.2.5",
-    "kibi-core": "^0.1.8",
+    "kibi-cli": "^0.2.7",
+    "kibi-core": "^0.1.10",
     "mcpcat": "^0.1.12",
     "ts-morph": "^23.0.0",
     "zod": "^4.3.6"

package/dist/tools/branch.js

@@ -1,181 +0,0 @@
-/*
- 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 { execSync } from "node:child_process";
-import * as fs from "node:fs";
-import * as path from "node:path";
-import { resolveKbPath, resolveWorkspaceRoot } from "../workspace.js";
-/**
- * Handle kb_branch_ensure tool calls - create branch KB if not exists
- */
-export async function handleKbBranchEnsure(_prolog, args) {
-    const { branch } = args;
-    if (!branch || branch.trim() === "") {
-        throw new Error("Branch name is required");
-    }
-    // Sanitize branch name (prevent path traversal)
-    const isSafe = (name) => {
-        // No empty or excessively long names
-        if (!name || name.length > 255)
-            return false;
-        // No path traversal or absolute paths
-        if (name.includes("..") || path.isAbsolute(name) || name.startsWith("/")) {
-            return false;
-        }
-        // Whitelist characters (alphanumeric, dot, underscore, hyphen, forward slash)
-        if (!/^[a-zA-Z0-9._\-/]+$/.test(name))
-            return false;
-        // No redundant slashes or trailing slash/dot
-        if (name.includes("//") ||
-            name.endsWith("/") ||
-            name.endsWith(".") ||
-            name.includes("\\")) {
-            return false;
-        }
-        return true;
-    };
-    if (!isSafe(branch)) {
-        throw new Error(`Invalid branch name: ${branch}`);
-    }
-    const safeBranch = branch;
-    try {
-        const workspaceRoot = resolveWorkspaceRoot();
-        const branchPath = resolveKbPath(workspaceRoot, safeBranch);
-        const developPath = resolveKbPath(workspaceRoot, "develop");
-        // Check if branch KB already exists
-        if (fs.existsSync(branchPath)) {
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: `Branch KB '${safeBranch}' already exists`,
-                    },
-                ],
-                structuredContent: {
-                    created: false,
-                    path: branchPath,
-                },
-            };
-        }
-        // Ensure develop branch exists
-        if (!fs.existsSync(developPath)) {
-            throw new Error("Develop branch KB does not exist. Run 'kb init' first.");
-        }
-        // Copy develop branch KB to new branch
-        fs.cpSync(developPath, branchPath, { recursive: true });
-        return {
-            content: [
-                {
-                    type: "text",
-                    text: `Created branch KB '${safeBranch}' from develop`,
-                },
-            ],
-            structuredContent: {
-                created: true,
-                path: branchPath,
-            },
-        };
-    }
-    catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
-        throw new Error(`Branch ensure failed: ${message}`);
-    }
-}
-/**
- * Handle kb_branch_gc tool calls - garbage collect stale branch KBs
- */
-export async function handleKbBranchGc(_prolog, args) {
-    const { dry_run = true } = args;
-    try {
-        const workspaceRoot = resolveWorkspaceRoot();
-        const kbRoot = path.dirname(resolveKbPath(workspaceRoot, "develop"));
-        // Check if .kb/branches exists
-        if (!fs.existsSync(kbRoot)) {
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: "No branch KBs found (.kb/branches does not exist)",
-                    },
-                ],
-                structuredContent: {
-                    stale: [],
-                    deleted: 0,
-                },
-            };
-        }
-        let gitBranches;
-        try {
-            execSync("git rev-parse --git-dir", {
-                encoding: "utf-8",
-                cwd: workspaceRoot,
-                stdio: ["pipe", "pipe", "pipe"],
-                env: process.env,
-            });
-            const output = execSync("git branch --format='%(refname:short)'", {
-                encoding: "utf-8",
-                cwd: workspaceRoot,
-                stdio: ["pipe", "pipe", "pipe"],
-                env: process.env,
-            });
-            gitBranches = new Set(output
-                .trim()
-                .split("\n")
-                .map((b) => b.trim().replace(/^'|'$/g, ""))
-                .filter((b) => b));
-        }
-        catch (error) {
-            const message = error instanceof Error ? error.message : String(error);
-            throw new Error(`Not in a git repository or git command failed: ${message}`);
-        }
-        // Get all KB branches
-        const kbBranches = fs
-            .readdirSync(kbRoot, { withFileTypes: true })
-            .filter((dirent) => dirent.isDirectory())
-            .map((dirent) => dirent.name);
-        // Find stale branches (KB exists but git branch doesn't, excluding develop)
-        const staleBranches = kbBranches.filter((kb) => kb !== "develop" && !gitBranches.has(kb));
-        // Delete stale branches if not dry run
-        let deletedCount = 0;
-        if (!dry_run && staleBranches.length > 0) {
-            for (const branch of staleBranches) {
-                const branchPath = path.join(kbRoot, branch);
-                fs.rmSync(branchPath, { recursive: true, force: true });
-                deletedCount++;
-            }
-        }
-        const summary = dry_run
-            ? `Found ${staleBranches.length} stale branch KB(s) (dry run - not deleted)`
-            : `Deleted ${deletedCount} stale branch KB(s)`;
-        return {
-            content: [
-                {
-                    type: "text",
-                    text: summary,
-                },
-            ],
-            structuredContent: {
-                stale: staleBranches,
-                deleted: deletedCount,
-            },
-        };
-    }
-    catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
-        throw new Error(`Branch GC failed: ${message}`);
-    }
-}

package/dist/tools/context.js

@@ -1,64 +0,0 @@
-import { parseEntityFromList, parseListOfLists, } from "kibi-cli/prolog/codec";
-export async function handleKbContext(prolog, args) {
-    const { sourceFile } = args;
-    try {
-        const safeSource = sourceFile.replace(/'/g, "\\'");
-        const entityGoal = `findall([Id,Type,Props], (kb_entities_by_source('${safeSource}', SourceIds), member(Id, SourceIds), kb_entity(Id, Type, Props)), Results)`;
-        const entityQueryResult = await prolog.query(entityGoal);
-        const entities = [];
-        const entityIds = [];
-        if (entityQueryResult.success && entityQueryResult.bindings.Results) {
-            const entitiesData = parseListOfLists(entityQueryResult.bindings.Results);
-            for (const data of entitiesData) {
-                const entity = parseEntityFromList(data);
-                entities.push({
-                    id: entity.id,
-                    type: entity.type,
-                    title: entity.title,
-                    status: entity.status,
-                    tags: entity.tags || [],
-                });
-                entityIds.push(entity.id);
-            }
-        }
-        const relationships = [];
-        for (const entityId of entityIds) {
-            const relGoal = `findall([RelType,FromId,ToId], (kb_relationship(RelType, FromId, ToId), (FromId = '${entityId}' ; ToId = '${entityId}')), RelResults)`;
-            const relQueryResult = await prolog.query(relGoal);
-            if (relQueryResult.success && relQueryResult.bindings.RelResults) {
-                const relData = parseListOfLists(relQueryResult.bindings.RelResults);
-                for (const rel of relData) {
-                    relationships.push({
-                        relType: rel[0],
-                        fromId: rel[1],
-                        toId: rel[2],
-                    });
-                }
-            }
-        }
-        const text = entities.length > 0
-            ? `Found ${entities.length} KB entities linked to source file "${sourceFile}": ${entities.map((e) => e.id).join(", ")}`
-            : `No KB entities found for source file "${sourceFile}"`;
-        return {
-            content: [
-                {
-                    type: "text",
-                    text,
-                },
-            ],
-            structuredContent: {
-                sourceFile,
-                entities,
-                relationships,
-                provenance: {
-                    predicate: "kb_entities_by_source",
-                    deterministic: true,
-                },
-            },
-        };
-    }
-    catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
-        throw new Error(`Context query failed: ${message}`);
-    }
-}

package/dist/tools/coverage-report.js

@@ -1,74 +0,0 @@
-import { parseAtomList, parsePairList } from "./prolog-list.js";
-export async function handleKbCoverageReport(prolog, args) {
-    const requested = args.type ?? "all";
-    if (args.type && args.type !== "req" && args.type !== "symbol") {
-        throw new Error("'type' must be one of: req, symbol");
-    }
-    const coverage = {};
-    const predicates = [];
-    if (requested === "all" || requested === "req") {
-        const reqIds = await queryAtoms(prolog, "setof(Req, kb_entity(Req, req, _), Reqs)", "Reqs");
-        const gapPairs = await queryPairs(prolog, "setof([Req,Reason], coverage_gap(Req, Reason), Rows)", "Rows");
-        const gaps = gapPairs.map(([req, reason]) => ({ req, reason }));
-        coverage.requirements = {
-            total: reqIds.length,
-            with_gaps: gaps.length,
-            healthy: Math.max(reqIds.length - gaps.length, 0),
-            gaps,
-        };
-        predicates.push("coverage_gap");
-    }
-    if (requested === "all" || requested === "symbol") {
-        const symbolIds = await queryAtoms(prolog, "setof(Symbol, kb_entity(Symbol, symbol, _), Symbols)", "Symbols");
-        const untestedResult = await prolog.query("untested_symbols(Symbols)");
-        const untestedSymbols = untestedResult.success && untestedResult.bindings.Symbols
-            ? parseAtomList(untestedResult.bindings.Symbols)
-            : [];
-        coverage.symbols = {
-            total: symbolIds.length,
-            untested: untestedSymbols.length,
-            tested: Math.max(symbolIds.length - untestedSymbols.length, 0),
-            untested_symbols: untestedSymbols,
-        };
-        predicates.push("untested_symbols");
-    }
-    const summaryParts = [];
-    if (coverage.requirements) {
-        summaryParts.push(`${coverage.requirements.healthy}/${coverage.requirements.total} requirements healthy`);
-    }
-    if (coverage.symbols) {
-        summaryParts.push(`${coverage.symbols.tested}/${coverage.symbols.total} symbols tested`);
-    }
-    return {
-        content: [
-            {
-                type: "text",
-                text: summaryParts.length > 0
-                    ? `Coverage report: ${summaryParts.join("; ")}.`
-                    : "Coverage report: no data.",
-            },
-        ],
-        structuredContent: {
-            requested_type: requested,
-            coverage,
-            provenance: {
-                deterministic: true,
-                predicates,
-            },
-        },
-    };
-}
-async function queryAtoms(prolog, goal, bindingName) {
-    const result = await prolog.query(goal);
-    if (!result.success || !result.bindings[bindingName]) {
-        return [];
-    }
-    return parseAtomList(result.bindings[bindingName]);
-}
-async function queryPairs(prolog, goal, bindingName) {
-    const result = await prolog.query(goal);
-    if (!result.success || !result.bindings[bindingName]) {
-        return [];
-    }
-    return parsePairList(result.bindings[bindingName]);
-}