kibi-mcp 0.1.0

package/dist/tools/symbols.js

@@ -0,0 +1,219 @@
+/*
+ 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 { existsSync, readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { resolveWorkspaceRoot } from "../workspace.js";
+import { enrichSymbolCoordinates, } from "kibi-cli/extractors/symbols-coordinator";
+import { dump as dumpYAML, load as parseYAML } from "js-yaml";
+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 GENERATED_COORD_FIELDS = [
+    "sourceLine",
+    "sourceColumn",
+    "sourceEndLine",
+    "sourceEndColumn",
+    "coordinatesGeneratedAt",
+];
+const SOURCE_EXTENSIONS = new Set([
+    ".ts",
+    ".tsx",
+    ".js",
+    ".jsx",
+    ".mts",
+    ".cts",
+    ".mjs",
+    ".cjs",
+]);
+export async function handleKbSymbolsRefresh(args) {
+    const dryRun = args.dryRun === true;
+    const workspaceRoot = resolveWorkspaceRoot();
+    const manifestPath = resolveManifestPath(workspaceRoot);
+    const rawContent = readFileSync(manifestPath, "utf8");
+    const parsed = parseYAML(rawContent);
+    if (!isRecord(parsed) || !Array.isArray(parsed.symbols)) {
+        throw new Error(`Invalid symbols manifest at ${manifestPath}`);
+    }
+    const original = parsed.symbols.map((entry) => isRecord(entry)
+        ? { ...entry }
+        : {});
+    const entriesForEnrichment = original.map((entry) => ({
+        ...entry,
+        id: typeof entry.id === "string" ? entry.id : "",
+        title: typeof entry.title === "string" ? entry.title : "",
+    }));
+    const enriched = await enrichSymbolCoordinates(entriesForEnrichment, workspaceRoot);
+    parsed.symbols = enriched;
+    let refreshed = 0;
+    let failed = 0;
+    let unchanged = 0;
+    for (let i = 0; i < original.length; i++) {
+        const before = original[i] ?? {};
+        const after = enriched[i] ?? before;
+        const changed = GENERATED_COORD_FIELDS.some((field) => before[field] !== after[field]);
+        if (changed) {
+            refreshed++;
+            continue;
+        }
+        const source = typeof after.sourceFile === "string"
+            ? after.sourceFile
+            : typeof before.sourceFile === "string"
+                ? before.sourceFile
+                : undefined;
+        const eligible = isEligible(source, workspaceRoot);
+        if (eligible && !hasGeneratedCoordinates(after)) {
+            failed++;
+        }
+        else {
+            unchanged++;
+        }
+    }
+    const dumped = dumpYAML(parsed, {
+        lineWidth: -1,
+        noRefs: true,
+        sortKeys: false,
+    });
+    const nextContent = `${COMMENT_BLOCK}${dumped}`;
+    if (!dryRun && rawContent !== nextContent) {
+        writeFileSync(manifestPath, nextContent, "utf8");
+    }
+    return {
+        content: [
+            {
+                type: "text",
+                text: `kb_symbols_refresh ${dryRun ? "(dry run) " : ""}completed for ${path.relative(workspaceRoot, manifestPath)}: refreshed=${refreshed}, unchanged=${unchanged}, failed=${failed}`,
+            },
+        ],
+        structuredContent: {
+            refreshed,
+            failed,
+            unchanged,
+            dryRun,
+        },
+    };
+}
+export async function refreshCoordinatesForSymbolId(symbolId, workspaceRoot = resolveWorkspaceRoot()) {
+    const manifestPath = resolveManifestPath(workspaceRoot);
+    const rawContent = readFileSync(manifestPath, "utf8");
+    const parsed = parseYAML(rawContent);
+    if (!isRecord(parsed) || !Array.isArray(parsed.symbols)) {
+        return { refreshed: false, found: false };
+    }
+    const symbols = parsed.symbols.map((entry) => isRecord(entry)
+        ? { ...entry }
+        : {});
+    const index = symbols.findIndex((entry) => entry.id === symbolId);
+    if (index < 0) {
+        return { refreshed: false, found: false };
+    }
+    const original = symbols[index] ?? {};
+    const singleEntry = {
+        ...original,
+        id: typeof original.id === "string"
+            ? original.id
+            : "",
+        title: typeof original.title === "string"
+            ? original.title
+            : "",
+    };
+    const [enriched] = await enrichSymbolCoordinates([singleEntry], workspaceRoot);
+    symbols[index] = enriched ?? original;
+    parsed.symbols = symbols;
+    const refreshed = GENERATED_COORD_FIELDS.some((field) => original[field] !== symbols[index][field]);
+    const dumped = dumpYAML(parsed, {
+        lineWidth: -1,
+        noRefs: true,
+        sortKeys: false,
+    });
+    const nextContent = `${COMMENT_BLOCK}${dumped}`;
+    if (rawContent !== nextContent) {
+        writeFileSync(manifestPath, nextContent, "utf8");
+    }
+    return { refreshed, found: true };
+}
+function resolveManifestPath(workspaceRoot) {
+    const configPath = path.join(workspaceRoot, ".kb", "config.json");
+    if (existsSync(configPath)) {
+        try {
+            const config = JSON.parse(readFileSync(configPath, "utf8"));
+            if (config.symbolsManifest) {
+                return path.isAbsolute(config.symbolsManifest)
+                    ? config.symbolsManifest
+                    : path.resolve(workspaceRoot, config.symbolsManifest);
+            }
+        }
+        catch { }
+    }
+    const candidates = [
+        path.join(workspaceRoot, "symbols.yaml"),
+        path.join(workspaceRoot, "symbols.yml"),
+    ];
+    return candidates.find((candidate) => existsSync(candidate)) ?? candidates[0];
+}
+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);
+}
+function isEligible(sourceFile, workspaceRoot) {
+    if (!sourceFile)
+        return false;
+    const absolute = path.isAbsolute(sourceFile)
+        ? sourceFile
+        : path.resolve(workspaceRoot, sourceFile);
+    if (!existsSync(absolute))
+        return false;
+    return SOURCE_EXTENSIONS.has(path.extname(absolute).toLowerCase());
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/dist/tools/upsert.js

@@ -0,0 +1,228 @@
+/*
+ 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 entitySchema from "kibi-cli/schemas/entity";
+import relationshipSchema from "kibi-cli/schemas/relationship";
+import Ajv from "ajv";
+import { refreshCoordinatesForSymbolId } from "./symbols.js";
+const ajv = new Ajv({ strict: false });
+const validateEntity = ajv.compile(entitySchema);
+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.
+ */
+export async function handleKbUpsert(prolog, args) {
+    const { type, id, properties, relationships = [] } = args;
+    if (!type || !id) {
+        throw new Error("'type' and 'id' are required for upsert");
+    }
+    // Assemble full entity from flat args + properties
+    const entity = {
+        id,
+        type,
+        ...properties,
+    };
+    // Fill in defaults for optional required fields
+    if (!entity.created_at) {
+        entity.created_at = new Date().toISOString();
+    }
+    if (!entity.updated_at) {
+        entity.updated_at = new Date().toISOString();
+    }
+    if (!entity.source) {
+        entity.source = "mcp://kibi/upsert";
+    }
+    const entities = [entity];
+    // Validate all entities
+    for (let i = 0; i < entities.length; i++) {
+        const ent = entities[i];
+        if (!validateEntity(ent)) {
+            const errors = validateEntity.errors || [];
+            const errorMessages = errors
+                .map((e) => `${e.instancePath || "root"}: ${e.message}`)
+                .join("; ");
+            throw new Error(`Entity validation failed: ${errorMessages}`);
+        }
+    }
+    // Validate all relationships
+    for (let i = 0; i < relationships.length; i++) {
+        const rel = relationships[i];
+        if (!validateRelationship(rel)) {
+            const errors = validateRelationship.errors || [];
+            const errorMessages = errors
+                .map((e) => `${e.instancePath || "root"}: ${e.message}`)
+                .join("; ");
+            throw new Error(`Relationship validation failed at index ${i}: ${errorMessages}`);
+        }
+    }
+    let created = 0;
+    let updated = 0;
+    let relationshipsCreated = 0;
+    try {
+        // Process entities
+        for (const entity of entities) {
+            const id = entity.id;
+            const type = entity.type;
+            // Check if entity exists
+            const checkGoal = `kb_entity('${id}', _, _)`;
+            const checkResult = await prolog.query(checkGoal);
+            const isUpdate = checkResult.success;
+            // Build property list for Prolog
+            const props = buildPropertyList(entity);
+            // Assert entity (upsert)
+            if (isUpdate) {
+                // Delete old version, then insert new
+                const retractGoal = `kb_retract_entity('${id}')`;
+                await prolog.query(retractGoal);
+                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"}`);
+            }
+        }
+        // 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}, '${from}', '${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++;
+        }
+        // Save KB to disk
+        await prolog.query("kb_save");
+        if (type === "symbol") {
+            try {
+                await refreshCoordinatesForSymbolId(id);
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                if (process.env.KIBI_MCP_DEBUG) {
+                    console.warn(`[KIBI-MCP] Symbol coordinate auto-refresh failed for ${id}: ${message}`);
+                }
+            }
+        }
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Upserted ${id} (${created > 0 ? "created" : "updated"}) with ${relationshipsCreated} relationship(s).`,
+                },
+            ],
+            structuredContent: {
+                created,
+                updated,
+                relationships_created: relationshipsCreated,
+            },
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Upsert execution failed: ${message}`);
+    }
+}
+/**
+ * Build Prolog property list from entity object
+ * Returns simple Key=Value format without typed literals
+ * Example output: "[id='test-1', title=\"Test\", status=active]"
+ */
+function buildPropertyList(entity) {
+    const pairs = [];
+    // Defined internally to ensure thread safety and avoid initialization order issues.
+    // Using simple arrays instead of Sets is performant enough for small lists and avoids Set allocation overhead.
+    const ATOM_FIELDS = ["status", "owner", "priority", "severity"];
+    const STRING_FIELDS = [
+        "id",
+        "title",
+        "created_at",
+        "updated_at",
+        "source",
+        "text_ref",
+    ];
+    for (const [key, value] of Object.entries(entity)) {
+        if (key === "type")
+            continue;
+        let prologValue;
+        if (key === "id" && typeof value === "string") {
+            prologValue = `'${value}'`;
+        }
+        else if (Array.isArray(value)) {
+            prologValue = JSON.stringify(value);
+        }
+        else if (ATOM_FIELDS.includes(key) && typeof value === "string") {
+            prologValue = value;
+        }
+        else if (STRING_FIELDS.includes(key) && typeof value === "string") {
+            prologValue = `"${escapeQuotes(value)}"`;
+        }
+        else if (typeof value === "string") {
+            prologValue = `"${escapeQuotes(value)}"`;
+        }
+        else if (typeof value === "number") {
+            prologValue = String(value);
+        }
+        else if (typeof value === "boolean") {
+            prologValue = value ? "true" : "false";
+        }
+        else {
+            prologValue = `"${escapeQuotes(String(value))}"`;
+        }
+        pairs.push(`${key}=${prologValue}`);
+    }
+    return `[${pairs.join(", ")}]`;
+}
+/**
+ * Build Prolog metadata list for relationship
+ * Returns simple Key=Value format without typed literals
+ */
+function buildRelationshipMetadata(rel) {
+    const pairs = [];
+    for (const [key, value] of Object.entries(rel)) {
+        if (key === "type" || key === "from" || key === "to")
+            continue;
+        let prologValue;
+        if (typeof value === "string") {
+            prologValue = `"${escapeQuotes(value)}"`;
+        }
+        else if (typeof value === "number") {
+            prologValue = String(value);
+        }
+        else {
+            prologValue = `"${escapeQuotes(String(value))}"`;
+        }
+        pairs.push(`${key}=${prologValue}`);
+    }
+    return `[${pairs.join(", ")}]`;
+}
+/**
+ * Escape double quotes in strings for Prolog
+ */
+function escapeQuotes(str) {
+    return str.replace(/"/g, '\\"');
+}