kibi-mcp 0.1.0

package/dist/tools/branch.js

@@ -0,0 +1,208 @@
+/*
+ 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/>.
+*/
+/*
+ How to apply this header to source files (examples)
+
+ 1) Prepend header to a single file (POSIX shells):
+
+    cat LICENSE_HEADER.txt "$FILE" > "$FILE".with-header && mv "$FILE".with-header "$FILE"
+
+ 2) Apply to multiple files (example: the project's main entry files):
+
+    for f in packages/cli/bin/kibi packages/mcp/bin/kibi-mcp packages/cli/src/*.ts packages/mcp/src/*.ts; do
+      if [ -f "$f" ]; then
+        cp "$f" "$f".bak
+        (cat LICENSE_HEADER.txt; echo; cat "$f" ) > "$f".new && mv "$f".new "$f"
+      fi
+    done
+
+ 3) Avoid duplicating the header: run a quick guard to only add if missing
+
+    for f in packages/cli/bin/kibi packages/mcp/bin/kibi-mcp; do
+      if [ -f "$f" ]; then
+        if ! head -n 5 "$f" | grep -q "Copyright (C) 2026 Piotr Franczyk"; then
+          cp "$f" "$f".bak
+          (cat LICENSE_HEADER.txt; echo; cat "$f" ) > "$f".new && mv "$f".new "$f"
+        fi
+      fi
+    done
+*/
+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/check.js

@@ -0,0 +1,349 @@
+/*
+ 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/>.
+*/
+/*
+ How to apply this header to source files (examples)
+
+ 1) Prepend header to a single file (POSIX shells):
+
+    cat LICENSE_HEADER.txt "$FILE" > "$FILE".with-header && mv "$FILE".with-header "$FILE"
+
+ 2) Apply to multiple files (example: the project's main entry files):
+
+    for f in packages/cli/bin/kibi packages/mcp/bin/kibi-mcp packages/cli/src/*.ts packages/mcp/src/*.ts; do
+      if [ -f "$f" ]; then
+        cp "$f" "$f".bak
+        (cat LICENSE_HEADER.txt; echo; cat "$f" ) > "$f".new && mv "$f".new "$f"
+      fi
+    done
+
+ 3) Avoid duplicating the header: run a quick guard to only add if missing
+
+    for f in packages/cli/bin/kibi packages/mcp/bin/kibi-mcp; do
+      if [ -f "$f" ]; then
+        if ! head -n 5 "$f" | grep -q "Copyright (C) 2026 Piotr Franczyk"; then
+          cp "$f" "$f".bak
+          (cat LICENSE_HEADER.txt; echo; cat "$f" ) > "$f".new && mv "$f".new "$f"
+        fi
+      fi
+    done
+*/
+import * as path from "node:path";
+import { parsePairList } from "./prolog-list.js";
+/**
+ * Handle kb_check tool calls - run validation rules on the KB
+ * Reuses validation logic from CLI check command
+ */
+export async function handleKbCheck(prolog, args) {
+    const { rules } = args;
+    try {
+        const violations = [];
+        const allEntityIds = await getAllEntityIds(prolog);
+        // Run all validation rules (or specific rules if provided)
+        const allRules = [
+            "must-priority-coverage",
+            "no-dangling-refs",
+            "no-cycles",
+            "required-fields",
+            "symbol-coverage",
+        ];
+        const rulesToRun = rules && rules.length > 0 ? rules : allRules;
+        if (rulesToRun.includes("must-priority-coverage")) {
+            violations.push(...(await checkMustPriorityCoverage(prolog)));
+        }
+        if (rulesToRun.includes("no-dangling-refs")) {
+            violations.push(...(await checkNoDanglingRefs(prolog)));
+        }
+        if (rulesToRun.includes("no-cycles")) {
+            violations.push(...(await checkNoCycles(prolog)));
+        }
+        if (rulesToRun.includes("required-fields")) {
+            violations.push(...(await checkRequiredFields(prolog, allEntityIds)));
+        }
+        if (rulesToRun.includes("symbol-coverage")) {
+            violations.push(...(await checkSymbolCoverage(prolog)));
+        }
+        // Return MCP structured response
+        const summary = violations.length === 0
+            ? "No violations found"
+            : `${violations.length} violations found`;
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: summary,
+                },
+            ],
+            structuredContent: {
+                violations,
+                count: violations.length,
+            },
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Check execution failed: ${message}`);
+    }
+}
+async function checkMustPriorityCoverage(prolog) {
+    const violations = [];
+    const gapsResult = await prolog.query("setof([Req,Reason], coverage_gap(Req, Reason), Rows)");
+    if (!gapsResult.success || !gapsResult.bindings.Rows) {
+        return violations;
+    }
+    const gaps = parsePairList(gapsResult.bindings.Rows);
+    for (const [reqId, reason] of gaps) {
+        const entityResult = await prolog.query(`kb_entity('${reqId}', req, Props)`);
+        let source = "";
+        if (entityResult.success && entityResult.bindings.Props) {
+            const propsStr = entityResult.bindings.Props;
+            const sourceMatch = propsStr.match(/source\s*=\s*\^\^?\("([^"]+)"/);
+            if (sourceMatch) {
+                source = sourceMatch[1];
+            }
+        }
+        const missing = [];
+        if (reason.includes("scenario")) {
+            missing.push("scenario");
+        }
+        if (reason.includes("test")) {
+            missing.push("test");
+        }
+        violations.push({
+            rule: "must-priority-coverage",
+            entityId: reqId,
+            description: `Must-priority requirement lacks ${missing.join(" and ")} coverage`,
+            source,
+            suggestion: missing
+                .map((m) => `Create ${m} that covers this requirement`)
+                .join("; "),
+        });
+    }
+    return violations;
+}
+async function getAllEntityIds(prolog, type) {
+    const typeFilter = type ? `, Type = ${type}` : "";
+    const query = `findall(Id, (kb_entity(Id, Type, _)${typeFilter}), Ids)`;
+    const result = await prolog.query(query);
+    if (!result.success || !result.bindings.Ids) {
+        return [];
+    }
+    const idsStr = result.bindings.Ids;
+    const match = idsStr.match(/\[(.*)\]/);
+    if (!match) {
+        return [];
+    }
+    const content = match[1].trim();
+    if (!content) {
+        return [];
+    }
+    return content.split(",").map((id) => id.trim().replace(/^'|'$/g, ""));
+}
+async function checkNoDanglingRefs(prolog) {
+    const violations = [];
+    // Get all entity IDs once
+    const allEntityIds = new Set(await getAllEntityIds(prolog));
+    // Get all relationships by querying all known relationship types
+    const relTypes = [
+        "depends_on",
+        "verified_by",
+        "validates",
+        "specified_by",
+        "relates_to",
+    ];
+    const allRels = [];
+    for (const relType of relTypes) {
+        const relsResult = await prolog.query(`findall([From,To], kb_relationship(${relType}, From, To), Rels)`);
+        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 });
+                    }
+                }
+            }
+        }
+    }
+    // Check all collected relationships for dangling refs
+    for (const rel of allRels) {
+        if (!allEntityIds.has(rel.from)) {
+            violations.push({
+                rule: "no-dangling-refs",
+                entityId: rel.from,
+                description: `Relationship references non-existent entity: ${rel.from}`,
+                suggestion: "Remove relationship or create missing entity",
+            });
+        }
+        if (!allEntityIds.has(rel.to)) {
+            violations.push({
+                rule: "no-dangling-refs",
+                entityId: rel.to,
+                description: `Relationship references non-existent entity: ${rel.to}`,
+                suggestion: "Remove relationship or create missing entity",
+            });
+        }
+    }
+    return violations;
+}
+async function checkNoCycles(prolog) {
+    const violations = [];
+    // Get all depends_on relationships
+    const depsResult = await prolog.query("findall([From,To], kb_relationship(depends_on, From, To), Deps)");
+    if (!depsResult.success || !depsResult.bindings.Deps) {
+        return violations;
+    }
+    const depsStr = depsResult.bindings.Deps;
+    const match = depsStr.match(/\[(.*)\]/);
+    if (!match) {
+        return violations;
+    }
+    const content = match[1].trim();
+    if (!content) {
+        return violations;
+    }
+    // Build adjacency map
+    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, "");
+        if (!graph.has(from)) {
+            graph.set(from, []);
+        }
+        const fromList = graph.get(from);
+        if (fromList) {
+            fromList.push(to);
+        }
+    }
+    // DFS to detect cycles
+    const visited = new Set();
+    const recStack = new Set();
+    function hasCycleDFS(node, path) {
+        visited.add(node);
+        recStack.add(node);
+        path.push(node);
+        const neighbors = graph.get(node) || [];
+        for (const neighbor of neighbors) {
+            if (!visited.has(neighbor)) {
+                const cyclePath = hasCycleDFS(neighbor, [...path]);
+                if (cyclePath)
+                    return cyclePath;
+            }
+            else if (recStack.has(neighbor)) {
+                // Cycle detected
+                return [...path, neighbor];
+            }
+        }
+        recStack.delete(node);
+        return null;
+    }
+    // Check each node for cycles
+    for (const node of graph.keys()) {
+        if (!visited.has(node)) {
+            const cyclePath = hasCycleDFS(node, []);
+            if (cyclePath) {
+                const cycleWithSources = [];
+                for (const entityId of cyclePath) {
+                    const entityResult = await prolog.query(`kb_entity('${entityId}', _, Props)`);
+                    let sourceName = entityId;
+                    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");
+                        }
+                    }
+                    cycleWithSources.push(sourceName);
+                }
+                violations.push({
+                    rule: "no-cycles",
+                    entityId: cyclePath[0],
+                    description: `Circular dependency detected: ${cycleWithSources.join(" → ")}`,
+                    suggestion: "Break the cycle by removing one of the depends_on relationships",
+                });
+                break; // Report only first cycle found
+            }
+        }
+    }
+    return violations;
+}
+async function checkRequiredFields(prolog, allEntityIds) {
+    const violations = [];
+    const required = [
+        "id",
+        "title",
+        "status",
+        "created_at",
+        "updated_at",
+        "source",
+    ];
+    for (const entityId of allEntityIds) {
+        const result = await prolog.query(`kb_entity('${entityId}', Type, Props)`);
+        if (result.success && result.bindings.Props) {
+            // Parse properties list: [key1=value1, key2=value2, ...]
+            const propsStr = result.bindings.Props;
+            const propKeys = new Set();
+            // Extract keys from Props
+            const keyMatches = propsStr.matchAll(/(\w+)\s*=/g);
+            for (const match of keyMatches) {
+                propKeys.add(match[1]);
+            }
+            // Check for missing required fields
+            for (const field of required) {
+                if (!propKeys.has(field)) {
+                    violations.push({
+                        rule: "required-fields",
+                        entityId: entityId,
+                        description: `Missing required field: ${field}`,
+                        suggestion: `Add ${field} to entity definition`,
+                    });
+                }
+            }
+        }
+    }
+    return violations;
+}
+async function checkSymbolCoverage(prolog) {
+    const violations = [];
+    const uncoveredResult = await prolog.query("setof(Symbol, (kb_entity(Symbol, symbol, _), \\+ transitively_implements(Symbol, _)), Symbols)");
+    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.",
+                    });
+                }
+            }
+        }
+    }
+    return violations;
+}