kibi-mcp 0.1.0

package/dist/tools/query-relationships.js

@@ -0,0 +1,176 @@
+/*
+ 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/>.
+*/
+const VALID_REL_TYPES = [
+    "depends_on",
+    "specified_by",
+    "verified_by",
+    "validates",
+    "implements",
+    "covered_by",
+    "constrained_by",
+    "constrains",
+    "requires_property",
+    "guards",
+    "publishes",
+    "consumes",
+    "supersedes",
+    "relates_to",
+];
+/**
+ * Handle kb_query_relationships tool calls.
+ * Queries the kb_relationship/3 predicate which has arity (Type, From, To).
+ *
+ * Note: kb_relationship/3 requires RelType to be bound (atom_concat/3 in Prolog
+ * does not work with an unbound first argument). When no type filter is given,
+ * we iterate over all known type values.
+ */
+export async function handleKbQueryRelationships(prolog, args) {
+    const { from, to, type } = args;
+    if (type && !VALID_REL_TYPES.includes(type)) {
+        throw new Error(`Invalid relationship type '${type}'. Valid types: ${VALID_REL_TYPES.join(", ")}`);
+    }
+    // When type is specified we run one query; otherwise iterate all known types
+    // (kb_relationship/3 requires the type to be bound due to atom_concat/3 in Prolog).
+    const typesToQuery = type ? [type] : VALID_REL_TYPES;
+    const allRelationships = [];
+    for (const relType of typesToQuery) {
+        // We collect what we actually need based on which args are bound.
+        // When both from and to are specified, we just need to check existence.
+        // Otherwise collect the unbound sides.
+        let goal;
+        if (from && to) {
+            // Check if the specific triple exists
+            goal = `(kb_relationship('${relType}', '${from}', '${to}') -> Results = [['${from}','${to}']] ; Results = [])`;
+        }
+        else if (from) {
+            goal = `findall(To, kb_relationship('${relType}', '${from}', To), Results)`;
+        }
+        else if (to) {
+            goal = `findall(From, kb_relationship('${relType}', From, '${to}'), Results)`;
+        }
+        else {
+            goal = `findall([From,To], kb_relationship('${relType}', From, To), Results)`;
+        }
+        const queryResult = await prolog.query(goal);
+        if (!queryResult.success) {
+            throw new Error(queryResult.error || "Relationship query failed");
+        }
+        if (queryResult.bindings.Results) {
+            const raw = queryResult.bindings.Results;
+            if (from && to) {
+                // Results is either [[from,to]] or []
+                const pairs = parsePairResults(raw);
+                for (const [pairFrom, pairTo] of pairs) {
+                    allRelationships.push({ relType, from: pairFrom, to: pairTo });
+                }
+            }
+            else if (from) {
+                // Results is [To, To, ...]
+                const ids = parseIdList(raw);
+                for (const toId of ids) {
+                    allRelationships.push({ relType, from, to: toId });
+                }
+            }
+            else if (to) {
+                // Results is [From, From, ...]
+                const ids = parseIdList(raw);
+                for (const fromId of ids) {
+                    allRelationships.push({ relType, from: fromId, to });
+                }
+            }
+            else {
+                // Results is [[From,To], ...]
+                const pairs = parsePairResults(raw);
+                for (const [pairFrom, pairTo] of pairs) {
+                    allRelationships.push({ relType, from: pairFrom, to: pairTo });
+                }
+            }
+        }
+    }
+    const text = allRelationships.length === 0
+        ? "No relationships found."
+        : `Found ${allRelationships.length} relationship(s): ${allRelationships
+            .map((r) => `${r.from} -[${r.relType}]-> ${r.to}`)
+            .join(", ")}`;
+    return {
+        content: [{ type: "text", text }],
+        structuredContent: {
+            relationships: allRelationships,
+            count: allRelationships.length,
+        },
+    };
+}
+/**
+ * Parse a flat Prolog list of atoms "[A,B,C]" into a string array.
+ */
+function parseIdList(raw) {
+    const cleaned = raw.trim();
+    if (cleaned === "[]" || cleaned === "")
+        return [];
+    const inner = cleaned.replace(/^\[/, "").replace(/\]$/, "");
+    return inner
+        .split(",")
+        .map((s) => s.trim().replace(/^'|'$/g, "").replace(/^"|"$/g, ""))
+        .filter(Boolean);
+}
+/**
+ * Parse Prolog findall result "[[From,To],...]" into [from, to] pairs.
+ */
+function parsePairResults(raw) {
+    const cleaned = raw.trim();
+    if (cleaned === "[]" || cleaned === "")
+        return [];
+    const inner = cleaned.replace(/^\[/, "").replace(/\]$/, "");
+    const pairs = [];
+    let depth = 0;
+    let current = "";
+    for (let i = 0; i < inner.length; i++) {
+        const ch = inner[i];
+        if (ch === "[") {
+            depth++;
+            current += ch;
+        }
+        else if (ch === "]") {
+            depth--;
+            current += ch;
+            if (depth === 0) {
+                const pair = parsePair(current.trim());
+                if (pair)
+                    pairs.push(pair);
+                current = "";
+            }
+        }
+        else if (ch === "," && depth === 0) {
+            // top-level separator between pairs — skip
+        }
+        else {
+            current += ch;
+        }
+    }
+    return pairs;
+}
+function parsePair(pairStr) {
+    // expect "[From,To]"
+    const inner = pairStr.replace(/^\[/, "").replace(/\]$/, "").trim();
+    const parts = inner
+        .split(",")
+        .map((s) => s.trim().replace(/^'|'$/g, "").replace(/^"|"$/g, ""));
+    if (parts.length < 2)
+        return null;
+    return [parts[0], parts[1]];
+}

package/dist/tools/query.js

@@ -0,0 +1,364 @@
+/*
+ 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/>.
+*/
+export const VALID_ENTITY_TYPES = [
+    "req",
+    "scenario",
+    "test",
+    "adr",
+    "flag",
+    "event",
+    "symbol",
+    "fact",
+];
+/**
+ * Handle kb.query tool calls
+ * Reuses query logic from CLI command
+ */
+export async function handleKbQuery(prolog, args) {
+    const { type, id, tags, sourceFile, limit = 100, offset = 0 } = args;
+    try {
+        let results = [];
+        // Validate type if provided
+        if (type) {
+            if (!VALID_ENTITY_TYPES.includes(type)) {
+                throw new Error(`Invalid type '${type}'. Valid types: ${VALID_ENTITY_TYPES.join(", ")}. Use a single type value, or omit this parameter to query all entities.`);
+            }
+        }
+        // Build Prolog query
+        let goal;
+        if (sourceFile) {
+            const safeSource = sourceFile.replace(/'/g, "\\'");
+            if (type) {
+                goal = `findall([Id,'${type}',Props], (kb_entities_by_source('${safeSource}', SourceIds), member(Id, SourceIds), kb_entity(Id, '${type}', Props)), Results)`;
+            }
+            else {
+                goal = `findall([Id,Type,Props], (kb_entities_by_source('${safeSource}', SourceIds), member(Id, SourceIds), kb_entity(Id, Type, Props)), Results)`;
+            }
+        }
+        else if (id && type) {
+            goal = `kb_entity('${id}', '${type}', Props), Id = '${id}', Type = '${type}', Result = [Id, Type, Props]`;
+        }
+        else if (id) {
+            goal = `findall(['${id}',Type,Props], kb_entity('${id}', Type, Props), Results)`;
+        }
+        else if (tags && tags.length > 0) {
+            const tagList = `[${tags.map((t) => `'${t}'`).join(",")}]`;
+            if (type) {
+                goal = `findall([Id,'${type}',Props], (kb_entity(Id, '${type}', Props), memberchk(tags=Tags, Props), member(Tag, Tags), member(Tag, ${tagList})), Results)`;
+            }
+            else {
+                goal = `findall([Id,Type,Props], (kb_entity(Id, Type, Props), memberchk(tags=Tags, Props), member(Tag, Tags), member(Tag, ${tagList})), Results)`;
+            }
+        }
+        else if (type) {
+            goal = `findall([Id,'${type}',Props], kb_entity(Id, '${type}', Props), Results)`;
+        }
+        else {
+            goal = "findall([Id,Type,Props], kb_entity(Id, Type, Props), Results)";
+        }
+        const queryResult = await prolog.query(goal);
+        if (queryResult.success) {
+            if (id && type) {
+                // Single entity query
+                if (queryResult.bindings.Result) {
+                    const entity = parseEntityFromBinding(queryResult.bindings.Result);
+                    results = [entity];
+                }
+            }
+            else {
+                // Multiple entities query
+                if (queryResult.bindings.Results) {
+                    const entitiesData = parseListOfLists(queryResult.bindings.Results);
+                    for (const data of entitiesData) {
+                        const entity = parseEntityFromList(data);
+                        results.push(entity);
+                    }
+                }
+            }
+        }
+        else {
+            throw new Error(queryResult.error || "Query failed with unknown error");
+        }
+        // Apply pagination
+        const paginated = results.slice(offset, offset + limit);
+        // Build human-readable text with entity IDs and titles
+        let text;
+        if (results.length === 0) {
+            text = `No entities found${type ? ` of type '${type}'` : ""}.`;
+        }
+        else {
+            const details = paginated
+                .map((e) => {
+                const id = e.id.replace(/^file:\/\/.*\//, "");
+                const title = e.title;
+                const status = e.status;
+                return `${id} (${title}, status=${status})`;
+            })
+                .join(", ");
+            text = `Found ${results.length} entities${type ? ` of type '${type}'` : ""}. Showing ${paginated.length} (offset ${offset}, limit ${limit}): ${details}`;
+        }
+        // Return MCP structured response
+        return {
+            content: [
+                {
+                    type: "text",
+                    text,
+                },
+            ],
+            structuredContent: {
+                entities: paginated,
+                count: results.length,
+            },
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Query execution failed: ${message}`);
+    }
+}
+/**
+ * Parse a Prolog list of lists into a JavaScript array.
+ * Input: "[[a,b,c],[d,e,f]]"
+ * Output: [["a", "b", "c"], ["d", "e", "f"]]
+ */
+export function parseListOfLists(listStr) {
+    const cleaned = listStr.trim().replace(/^\[/, "").replace(/\]$/, "");
+    if (cleaned === "") {
+        return [];
+    }
+    const results = [];
+    let depth = 0;
+    let current = "";
+    let currentList = [];
+    for (let i = 0; i < cleaned.length; i++) {
+        const char = cleaned[i];
+        if (char === "[") {
+            depth++;
+            if (depth > 1)
+                current += char;
+        }
+        else if (char === "]") {
+            depth--;
+            if (depth === 0) {
+                if (current) {
+                    currentList.push(current.trim());
+                    current = "";
+                }
+                if (currentList.length > 0) {
+                    results.push(currentList);
+                    currentList = [];
+                }
+            }
+            else {
+                current += char;
+            }
+        }
+        else if (char === "," && depth === 1) {
+            if (current) {
+                currentList.push(current.trim());
+                current = "";
+            }
+        }
+        else if (char === "," && depth === 0) {
+            // Skip comma between lists
+        }
+        else {
+            current += char;
+        }
+    }
+    return results;
+}
+/**
+ * Parse a single entity from Prolog binding format.
+ * Input: "[abc123, req, [id=abc123, title=\"Test\", ...]]"
+ */
+export function parseEntityFromBinding(bindingStr) {
+    const cleaned = bindingStr.trim().replace(/^\[/, "").replace(/\]$/, "");
+    const parts = splitTopLevel(cleaned, ",");
+    if (parts.length < 3) {
+        return {};
+    }
+    const id = parts[0].trim();
+    const type = parts[1].trim();
+    const propsStr = parts.slice(2).join(",").trim();
+    const props = parsePropertyList(propsStr);
+    return { ...props, id: normalizeEntityId(stripOuterQuotes(id)), type };
+}
+/**
+ * Parse entity from array returned by parseListOfLists.
+ * Input: ["abc123", "req", "[id=abc123, title=\"Test\", ...]"]
+ */
+export function parseEntityFromList(data) {
+    if (data.length < 3) {
+        return {};
+    }
+    const id = data[0].trim();
+    const type = data[1].trim();
+    const propsStr = data[2].trim();
+    const props = parsePropertyList(propsStr);
+    return { ...props, id: normalizeEntityId(stripOuterQuotes(id)), type };
+}
+/**
+ * Parse Prolog property list into JavaScript object.
+ */
+export function parsePropertyList(propsStr) {
+    const props = {};
+    let cleaned = propsStr.trim();
+    if (cleaned.startsWith("[")) {
+        cleaned = cleaned.substring(1);
+    }
+    if (cleaned.endsWith("]")) {
+        cleaned = cleaned.substring(0, cleaned.length - 1);
+    }
+    const pairs = splitTopLevel(cleaned, ",");
+    for (const pair of pairs) {
+        const eqIndex = pair.indexOf("=");
+        if (eqIndex === -1)
+            continue;
+        const key = pair.substring(0, eqIndex).trim();
+        const value = pair.substring(eqIndex + 1).trim();
+        if (key === "..." || value === "..." || value === "...|...") {
+            continue;
+        }
+        const parsed = parsePrologValue(value);
+        props[key] = parsed;
+    }
+    return props;
+}
+/**
+ * Parse a single Prolog value, handling typed literals and URIs.
+ */
+export function parsePrologValue(valueInput) {
+    const value = valueInput.trim();
+    // Handle typed literal: ^^("value", type)
+    if (value.startsWith("^^(")) {
+        const innerStart = value.indexOf("(") + 1;
+        let depth = 1;
+        let innerEnd = innerStart;
+        for (let i = innerStart; i < value.length; i++) {
+            if (value[i] === "(")
+                depth++;
+            if (value[i] === ")") {
+                depth--;
+                if (depth === 0) {
+                    innerEnd = i;
+                    break;
+                }
+            }
+        }
+        const innerContent = value.substring(innerStart, innerEnd);
+        const parts = splitTopLevel(innerContent, ",");
+        if (parts.length >= 2) {
+            let literalValue = parts[0].trim();
+            if (literalValue.startsWith('"') && literalValue.endsWith('"')) {
+                literalValue = literalValue.substring(1, literalValue.length - 1);
+            }
+            // Handle array notation
+            if (literalValue.startsWith("[") && literalValue.endsWith("]")) {
+                const listContent = literalValue.substring(1, literalValue.length - 1);
+                if (listContent === "") {
+                    return [];
+                }
+                return splitTopLevel(listContent, ",").map((item) => item.trim());
+            }
+            return literalValue;
+        }
+    }
+    // Handle URI
+    if (value.startsWith("file:///")) {
+        const lastSlash = value.lastIndexOf("/");
+        if (lastSlash !== -1) {
+            return value.substring(lastSlash + 1);
+        }
+        return value;
+    }
+    // Handle quoted string
+    if (value.startsWith('"') && value.endsWith('"')) {
+        return value.substring(1, value.length - 1);
+    }
+    // Handle quoted atom
+    if (value.startsWith("'") && value.endsWith("'")) {
+        return value.substring(1, value.length - 1);
+    }
+    // Handle list
+    if (value.startsWith("[") && value.endsWith("]")) {
+        const listContent = value.substring(1, value.length - 1);
+        if (listContent === "") {
+            return [];
+        }
+        const items = splitTopLevel(listContent, ",").map((item) => {
+            return parsePrologValue(item.trim());
+        });
+        return items;
+    }
+    return value;
+}
+/**
+ * Split a string by delimiter at the top level (not inside brackets or quotes).
+ */
+export function splitTopLevel(str, delimiter) {
+    const results = [];
+    let current = "";
+    let depth = 0;
+    let inQuotes = false;
+    for (let i = 0; i < str.length; i++) {
+        const char = str[i];
+        const prevChar = i > 0 ? str[i - 1] : "";
+        if (char === '"' && prevChar !== "\\") {
+            inQuotes = !inQuotes;
+            current += char;
+        }
+        else if (!inQuotes && (char === "[" || char === "(")) {
+            depth++;
+            current += char;
+        }
+        else if (!inQuotes && (char === "]" || char === ")")) {
+            depth--;
+            current += char;
+        }
+        else if (!inQuotes && depth === 0 && char === delimiter) {
+            if (current) {
+                results.push(current);
+                current = "";
+            }
+        }
+        else {
+            current += char;
+        }
+    }
+    if (current) {
+        results.push(current);
+    }
+    return results;
+}
+function stripOuterQuotes(value) {
+    if (value.startsWith("'") && value.endsWith("'")) {
+        return value.slice(1, -1);
+    }
+    if (value.startsWith('"') && value.endsWith('"')) {
+        return value.slice(1, -1);
+    }
+    return value;
+}
+function normalizeEntityId(value) {
+    if (!value.startsWith("file:///")) {
+        return value;
+    }
+    const idx = value.lastIndexOf("/");
+    return idx === -1 ? value : value.slice(idx + 1);
+}

package/dist/tools/suggest-shared-facts.js

@@ -0,0 +1,138 @@
+/*
+ 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 { parseAtomList } from "./prolog-list.js";
+/**
+ * Handle analyze_shared_facts tool calls
+ * Analyzes requirements to suggest shared domain facts for extraction
+ */
+export async function handleSuggestSharedFacts(prolog, args) {
+    const minFreq = args.min_frequency ?? 2;
+    try {
+        // Query all requirements with their text properties
+        const reqsResult = await prolog.query("findall([Id,Title], (kb_entity(Id, req, Props), memberchk(title=Title, Props)), Reqs)");
+        if (!reqsResult.success || !reqsResult.bindings.Reqs) {
+            return {
+                content: [{ type: "text", text: "No requirements found in KB" }],
+                structuredContent: { suggestions: [], count: 0 },
+            };
+        }
+        const reqsList = parseAtomList(reqsResult.bindings.Reqs);
+        const requirements = [];
+        // Parse the list-of-lists format from Prolog
+        const reqMatch = reqsList.join("").matchAll(/\[([^,]+),([^\]]+)\]/g);
+        if (reqMatch) {
+            for (const match of reqMatch) {
+                const id = match[1].trim().replace(/^'|'$/g, "");
+                const title = match[2].trim().replace(/^'|'$/g, "");
+                requirements.push({ id, title, description: title });
+            }
+        }
+        // Query all existing facts for context
+        const factsResult = await prolog.query("findall([Id,Title], (kb_entity(Id, fact, Props), memberchk(title=Title, Props)), Facts)");
+        if (!factsResult.success || !factsResult.bindings.Facts) {
+            return {
+                content: [{ type: "text", text: "No facts found in KB" }],
+                structuredContent: { suggestions: [], count: 0 },
+            };
+        }
+        const factsList = parseAtomList(factsResult.bindings.Facts);
+        const existingFacts = new Set();
+        const factMatch = factsList.join("").matchAll(/\[([^,]+),([^\]]+)\]/g);
+        if (factMatch) {
+            for (const match of factMatch) {
+                const title = match[2].trim().replace(/^'|'$/g, "");
+                existingFacts.add(title.toLowerCase());
+            }
+        }
+        // Extract and analyze domain concepts from requirements
+        const suggestions = analyzeSharedConcepts(requirements, existingFacts, minFreq);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Found ${suggestions.length} potential shared fact(s) to consider creating.`,
+                },
+            ],
+            structuredContent: {
+                suggestions,
+                count: suggestions.length,
+            },
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Shared facts analysis failed: ${message}`);
+    }
+}
+/**
+ * Lightweight heuristic to identify shared domain concepts
+ * Focuses on:
+ * - Capitalized terms (possible domain concepts)
+ * - Repeated phrases across multiple requirements
+ * - Excludes existing facts
+ */
+function analyzeSharedConcepts(requirements, existingFacts, minFreq) {
+    const conceptCounts = new Map();
+    for (const req of requirements) {
+        const originalText = `${req.title} ${req.description || ""}`;
+        const text = originalText.toLowerCase();
+        // Extract capitalized terms (potential domain concepts)
+        // Pattern: words starting with capital letters that aren't at sentence start
+        const capitalizedTerms = originalText.matchAll(/\b([A-Z][a-z]+)\b/g);
+        // Extract repeated phrases (2+ words)
+        // Extract repeated phrases (2+ words)
+        const words = text.split(/\s+/).filter(w => w.length > 3);
+        for (let i = 0; i < words.length - 1; i++) {
+            const phrase = `${words[i]} ${words[i + 1]}`;
+            if (!conceptCounts.has(phrase)) {
+                conceptCounts.set(phrase, new Set());
+            }
+            conceptCounts.get(phrase).add(req.id);
+        }
+        // Also track individual capitalized terms
+        for (const match of capitalizedTerms) {
+            const lowerTerm = match[1].toLowerCase(); // Get the captured group
+            if (!conceptCounts.has(lowerTerm)) {
+                conceptCounts.set(lowerTerm, new Set());
+            }
+            conceptCounts.get(lowerTerm).add(req.id);
+        }
+    }
+    // Generate suggestions
+    const suggestions = [];
+    for (const [concept, reqIds] of conceptCounts) {
+        if (reqIds.size >= minFreq) {
+            // Skip if this concept already exists as a fact
+            if (!existingFacts.has(concept)) {
+                suggestions.push({
+                    concept: capitalizeConcept(concept),
+                    mentions: reqIds.size,
+                    requirements: Array.from(reqIds),
+                });
+            }
+        }
+    }
+    // Sort by frequency (most mentioned first)
+    return suggestions.sort((a, b) => b.mentions - a.mentions);
+}
+function capitalizeConcept(concept) {
+    return concept
+        .split(/\s+/)
+        .map(word => word.charAt(0).toUpperCase() + word.slice(1))
+        .join(" ");
+}