kibi-mcp 0.17.5 → 0.19.2

package/dist/tools/model-requirement.js

@@ -1,351 +1,12 @@
-import { readFile } from "node:fs/promises";
-import path from "node:path";
-import { buildStrictWriteSet, } from "kibi-cli/public/check-types";
-import { getSchemaVersionStatus } from "kibi-cli/schema-version";
+import { modelRequirementSpec, } from "kibi-cli/operations";
+import { estimateNormativeSignalConfidence, extractRequirementClaim, getWorkspaceMigrationWarning, strictWriteSetToApplyPlan, writeSetPrimaryEntityId, } from "kibi-cli/operations/modeling/model-requirement";
 import { resolveWorkspaceRoot } from "../workspace.js";
-const STRICT_FALLBACK_CONFIDENCE = 0.69;
-const NORMATIVE_SECTION_PATTERN = /\b(requirements?|polic(?:y|ies)|rules?)\b/i;
-function normalizeText(text) {
-    const normalized = String(text ?? "").trim();
-    if (!normalized) {
-        throw new Error("Requirement modeling failed: text must be a non-empty string");
-    }
-    return normalized;
-}
-function normalizeOptionalString(value) {
-    const normalized = String(value ?? "").trim();
-    return normalized.length > 0 ? normalized : undefined;
-}
-function normalizeSourceFiles(sourceFiles) {
-    const seen = new Set();
-    const normalized = [];
-    for (const sourceFile of sourceFiles ?? []) {
-        const trimmed = String(sourceFile ?? "").trim();
-        if (!trimmed || seen.has(trimmed))
-            continue;
-        seen.add(trimmed);
-        normalized.push(trimmed);
-    }
-    return normalized;
-}
-function clampConfidence(confidence) {
-    const numeric = typeof confidence === "number" && Number.isFinite(confidence)
-        ? confidence
-        : 0.8;
-    return Math.round(Math.min(1, Math.max(0, numeric)) * 100) / 100;
-}
-function normalizeClaimValue(value) {
-    if (typeof value === "string" ||
-        typeof value === "number" ||
-        typeof value === "boolean") {
-        if (typeof value === "number" && !Number.isFinite(value)) {
-            throw new Error("Requirement modeling failed: value must be a finite number");
-        }
-        return value;
-    }
-    throw new Error("Requirement modeling failed: value must be a string, number, or boolean");
-}
-function stripListPrefix(value) {
-    return value
-        .replace(/^\s*[-*+]\s+/, "")
-        .replace(/^\s*\d+[.)]\s+/, "")
-        .trim();
-}
-function trimSentenceTail(value) {
-    return value.replace(/[\s.?!:;]+$/g, "").trim();
-}
-function cleanSubject(value) {
-    const cleaned = trimSentenceTail(stripListPrefix(value));
-    return cleaned.replace(/^(?:the|a|an)\s+/i, "").trim() || cleaned;
-}
-function cleanPredicate(value) {
-    return trimSentenceTail(stripListPrefix(value)) || "statement";
-}
-function fallbackSubjectFromSource(source) {
-    const basename = path
-        .basename(source, path.extname(source))
-        .replace(/[-_]+/g, " ")
-        .trim();
-    return basename || "Requirement";
-}
-function hasExplicitClaimFields(args) {
-    return (args.subjectKey !== undefined ||
-        args.propertyKey !== undefined ||
-        args.operator !== undefined ||
-        args.value !== undefined);
-}
-function buildFallbackClaim(statement, source, confidence, provenance) {
-    return {
-        claim: {
-            source,
-            subjectKey: fallbackSubjectFromSource(source),
-            propertyKey: "statement",
-            operator: "eq",
-            value: statement,
-            confidence: Math.min(confidence, STRICT_FALLBACK_CONFIDENCE),
-            ...(provenance ? { provenance } : {}),
-        },
-        extractionMode: "fallback",
-        extractionWarnings: [
-            "Deterministic claim extraction could not infer a strict semantic claim; emitted a review artifact instead.",
-        ],
-    };
-}
-function extractHeuristicClaim(statement, source, confidence, provenance) {
-    const normalized = stripListPrefix(statement);
-    const retentionMatch = normalized.match(/^(?<subject>.+?)\s+(?:must|shall|should)\s+be\s+retained\s+for\s+(?<value>\d+)\s+(?<unit>day|days|month|months|year|years)\.?$/i);
-    if (retentionMatch?.groups) {
-        const { unit, subject, value } = retentionMatch.groups;
-        if (!unit || !subject || !value)
-            return null;
-        const normalizedUnit = unit.toLowerCase().startsWith("day")
-            ? "Days"
-            : unit.toLowerCase().startsWith("month")
-                ? "Months"
-                : "Years";
-        return {
-            claim: {
-                source,
-                subjectKey: cleanSubject(subject),
-                propertyKey: `Retention ${normalizedUnit}`,
-                operator: "eq",
-                value: Number(value),
-                confidence,
-                ...(provenance ? { provenance } : {}),
-            },
-            extractionMode: "heuristic",
-            extractionWarnings: [],
-        };
-    }
-    const enabledMatch = normalized.match(/^(?<subject>.+?)\s+(?:must|shall|should)\s+be\s+(?<state>enabled|disabled)\.?$/i);
-    if (enabledMatch?.groups) {
-        const { subject, state } = enabledMatch.groups;
-        if (!subject || !state)
-            return null;
-        return {
-            claim: {
-                source,
-                subjectKey: cleanSubject(subject),
-                propertyKey: "enabled",
-                operator: "bool",
-                value: state.toLowerCase() === "enabled",
-                confidence,
-                ...(provenance ? { provenance } : {}),
-            },
-            extractionMode: "heuristic",
-            extractionWarnings: [],
-        };
-    }
-    const forbiddenMatch = normalized.match(/^(?<subject>.+?)\s+(?:must|shall|should)\s+not\s+(?<predicate>.+?)\.?$/i);
-    if (forbiddenMatch?.groups) {
-        const { subject, predicate } = forbiddenMatch.groups;
-        if (!subject || !predicate)
-            return null;
-        return {
-            claim: {
-                source,
-                subjectKey: cleanSubject(subject),
-                propertyKey: cleanPredicate(predicate),
-                operator: "polarity",
-                value: "forbid",
-                confidence,
-                ...(provenance ? { provenance } : {}),
-            },
-            extractionMode: "heuristic",
-            extractionWarnings: [],
-        };
-    }
-    const requiredMatch = normalized.match(/^(?<subject>.+?)\s+(?:must|shall|should)\s+(?<predicate>.+?)\.?$/i);
-    if (requiredMatch?.groups) {
-        const { subject, predicate } = requiredMatch.groups;
-        if (!subject || !predicate)
-            return null;
-        return {
-            claim: {
-                source,
-                subjectKey: cleanSubject(subject),
-                propertyKey: cleanPredicate(predicate),
-                operator: "polarity",
-                value: "require",
-                confidence,
-                ...(provenance ? { provenance } : {}),
-            },
-            extractionMode: "heuristic",
-            extractionWarnings: [],
-        };
-    }
-    return null;
-}
-export function estimateNormativeSignalConfidence(statement, heading) {
-    const normalizedStatement = stripListPrefix(statement).toLowerCase();
-    if (!/\b(must|shall|should)\b/.test(normalizedStatement)) {
-        return 0;
-    }
-    let confidence = normalizedStatement.includes(" shall ")
-        ? 0.86
-        : normalizedStatement.includes(" must ")
-            ? 0.84
-            : 0.78;
-    if (heading && NORMATIVE_SECTION_PATTERN.test(heading)) {
-        confidence += 0.08;
-    }
-    return Math.round(Math.min(0.95, confidence) * 100) / 100;
-}
-export function extractRequirementClaim(args) {
-    const statement = normalizeText(args.text);
-    const sourceFiles = normalizeSourceFiles(args.sourceFiles);
-    const source = normalizeOptionalString(args.source) ?? sourceFiles[0];
-    if (!source) {
-        throw new Error("Requirement modeling failed: provide source or at least one sourceFiles entry");
-    }
-    const provenance = normalizeOptionalString(args.provenance);
-    const confidence = clampConfidence(args.confidence);
-    if (hasExplicitClaimFields(args)) {
-        if (!normalizeOptionalString(args.subjectKey) ||
-            !normalizeOptionalString(args.propertyKey) ||
-            args.operator === undefined ||
-            args.value === undefined) {
-            throw new Error("Requirement modeling failed: subjectKey, propertyKey, operator, and value must all be provided when any extracted claim field is supplied");
-        }
-        return {
-            statement,
-            source,
-            sourceFiles,
-            claim: {
-                source,
-                subjectKey: normalizeOptionalString(args.subjectKey),
-                propertyKey: normalizeOptionalString(args.propertyKey),
-                operator: args.operator,
-                value: normalizeClaimValue(args.value),
-                confidence,
-                ...(provenance ? { provenance } : {}),
-            },
-            extractionMode: "provided",
-            extractionWarnings: [],
-        };
-    }
-    const heuristic = extractHeuristicClaim(statement, source, confidence, provenance);
-    if (heuristic) {
-        return {
-            statement,
-            source,
-            sourceFiles,
-            ...heuristic,
-        };
-    }
-    return {
-        statement,
-        source,
-        sourceFiles,
-        ...buildFallbackClaim(statement, source, confidence, provenance),
-    };
-}
-function toRelationshipPlanRows(relationships) {
-    return relationships.map((relationship) => ({
-        type: relationship.type,
-        from: relationship.from,
-        to: relationship.to,
-    }));
-}
-export function strictWriteSetToApplyPlan(writeSet) {
-    if (!writeSet.isStrict) {
-        return [
-            {
-                type: writeSet.observationFact.type,
-                id: writeSet.observationFact.id,
-                properties: writeSet.observationFact.properties,
-                relationships: [],
-            },
-        ];
-    }
-    return [
-        {
-            type: writeSet.subjectFact.type,
-            id: writeSet.subjectFact.id,
-            properties: writeSet.subjectFact.properties,
-            relationships: [],
-        },
-        {
-            type: writeSet.propertyFact.type,
-            id: writeSet.propertyFact.id,
-            properties: writeSet.propertyFact.properties,
-            relationships: [],
-        },
-        {
-            type: writeSet.req.type,
-            id: writeSet.req.id,
-            properties: writeSet.req.properties,
-            relationships: toRelationshipPlanRows(writeSet.relationships),
-        },
-    ];
-}
-export function writeSetPrimaryEntityId(writeSet) {
-    return writeSet.isStrict ? writeSet.req.id : writeSet.observationFact.id;
-}
-export async function getWorkspaceMigrationWarning(workspaceRoot = resolveWorkspaceRoot()) {
-    const configPath = path.join(workspaceRoot, ".kb", "config.json");
-    let rawConfig;
-    try {
-        rawConfig = await readFile(configPath, "utf8");
-    }
-    catch {
-        return null;
-    }
-    try {
-        const parsed = JSON.parse(rawConfig);
-        const status = getSchemaVersionStatus(parsed ?? undefined);
-        return status.warning;
-    }
-    catch {
-        return "KB config schemaVersion could not be read and should be checked before applying automated modeling.";
-    }
-}
+export { estimateNormativeSignalConfidence, extractRequirementClaim, getWorkspaceMigrationWarning, strictWriteSetToApplyPlan, writeSetPrimaryEntityId, };
 export async function handleKbModelRequirement(_prolog, args) {
-    const extracted = extractRequirementClaim(args);
-    const writeSet = buildStrictWriteSet({
-        claim: extracted.claim,
-        statement: extracted.statement,
-    });
-    const applyPlan = strictWriteSetToApplyPlan(writeSet);
-    const migrationWarning = await getWorkspaceMigrationWarning();
-    const warnings = writeSet.isStrict
-        ? []
-        : [
-            {
-                kind: "low_confidence_observation_downgrade",
-                message: `Claim confidence ${writeSet.confidence.toFixed(2)} is below the strict threshold 0.70, so Kibi emitted an observation fact instead of strict subject/property facts.`,
-                nextAction: "If this is normative, provide subjectKey, propertyKey, operator, and value explicitly, then apply the returned strict write-set sequentially.",
-            },
-        ];
-    const strictSummary = writeSet.isStrict
-        ? `Modeled strict requirement into ${applyPlan.length} sequential applyPlan step(s).`
-        : "Modeled a non-blocking observation review artifact; deterministic claim extraction stayed below the strict threshold.";
-    const structuredContent = {
-        statement: extracted.statement,
-        source: extracted.source,
-        sourceFiles: extracted.sourceFiles,
-        claim: extracted.claim,
-        writeSet,
-        applyPlan,
-        isStrict: writeSet.isStrict,
-        confidence: writeSet.confidence,
-        extractionMode: extracted.extractionMode,
-        extractionWarnings: extracted.extractionWarnings,
-        warnings,
-        migrationWarning,
-    };
-    return {
-        content: [
-            {
-                type: "text",
-                text: migrationWarning
-                    ? `${strictSummary} Migration warning included.`
-                    : strictSummary,
-            },
-        ],
-        structuredContent,
-        applyPlan,
-        writeSet,
-        migrationWarning,
+    const context = {
+        workspaceRoot: resolveWorkspaceRoot(),
+        signal: new AbortController().signal,
+        clock: () => new Date(),
     };
+    return modelRequirementSpec.execute(args, context);
 }

package/dist/tools/mutation-context.js

@@ -0,0 +1,28 @@
+import * as fs from "node:fs/promises";
+import { resolveWorkspaceRoot } from "../workspace.js";
+const filesystem = {
+    readFile: (filePath) => fs.readFile(filePath, "utf8"),
+    writeFile: (filePath, data) => fs.writeFile(filePath, data, "utf8"),
+    mkdir: async (directoryPath) => {
+        await fs.mkdir(directoryPath, { recursive: true });
+    },
+    stat: (filePath) => fs.stat(filePath),
+};
+// implements REQ-kibi-operation-interface-parity
+export function createMutationContext(prolog) {
+    const port = prolog === undefined
+        ? undefined
+        : {
+            query: (goal) => prolog.query(goal),
+            nextSolution: async () => null,
+            invalidateCache: () => prolog.invalidateCache(),
+            save: () => prolog.query("kb_save"),
+        };
+    return {
+        workspaceRoot: resolveWorkspaceRoot(),
+        signal: new AbortController().signal,
+        clock: () => new Date(),
+        fs: filesystem,
+        ...(port === undefined ? {} : { prolog: port }),
+    };
+}

package/dist/tools/query-plan-safety.js

@@ -0,0 +1,58 @@
+import fs from "node:fs";
+const GENERATOR_PATTERN = /\b(?:kb_entity|kb_relationship|member|memberchk|findall|setof|bagof)\s*\(/;
+const NEGATION_PATTERN = /\\\+\s*/;
+export function collectQueryPlanSafetyViolations(checksPlPath) {
+    const source = fs.readFileSync(checksPlPath, "utf8");
+    return analyzeSource(source).map((violation) => ({
+        rule: "query-plan-safety",
+        entityId: violation.predicate,
+        description: violation.description,
+        suggestion: violation.suggestion,
+        source: `${checksPlPath}:${violation.line}`,
+    }));
+}
+function analyzeSource(source) {
+    const lines = source.split(/\r?\n/);
+    const violations = [];
+    let clauseStart = 0;
+    let predicate = "unknown";
+    let clauseLines = [];
+    for (let index = 0; index < lines.length; index += 1) {
+        const line = lines[index] ?? "";
+        if (clauseLines.length === 0 && line.trim().length === 0) {
+            continue;
+        }
+        if (clauseLines.length === 0) {
+            clauseStart = index + 1;
+            predicate = predicateNameFrom(line) ?? "unknown";
+        }
+        clauseLines.push(line);
+        if (line.trim().endsWith(".")) {
+            const violation = analyzeClause(predicate, clauseStart, clauseLines);
+            if (violation)
+                violations.push(violation);
+            clauseLines = [];
+        }
+    }
+    return violations;
+}
+function predicateNameFrom(line) {
+    const match = line.match(/^\s*([a-z][a-zA-Z0-9_]*)\s*\(/);
+    return match?.[1] ?? null;
+}
+function analyzeClause(predicate, startLine, lines) {
+    const negationIndex = lines.findIndex((line) => NEGATION_PATTERN.test(line));
+    if (negationIndex < 0)
+        return null;
+    const hasLaterGenerator = lines
+        .slice(negationIndex + 1)
+        .some((line) => GENERATOR_PATTERN.test(line));
+    if (!hasLaterGenerator)
+        return null;
+    return {
+        predicate,
+        line: startLine + negationIndex,
+        description: "Negation appears before later generator calls in the same clause.",
+        suggestion: "Move kb_entity/kb_relationship/member/findall generators before \\+/1 so variables are bound before negation.",
+    };
+}

package/dist/tools/query.js

@@ -1,52 +1,7 @@
-import { loadEntities, paginateResults, } from "./entity-query.js";
-export { VALID_ENTITY_TYPES } from "./entity-query.js";
-/**
- * Handle kb.query tool calls
- * Reuses query logic from CLI command
- */
+import { VALID_ENTITY_TYPES, querySpec } from "kibi-cli/operations";
+import { createDiscoveryContext } from "./discovery-adapter.js";
+export { VALID_ENTITY_TYPES };
 export async function handleKbQuery(prolog, args) {
-    const { type, id, tags, sourceFile, limit = 100, offset = 0 } = args;
-    try {
-        const queryArgs = {
-            ...(type !== undefined ? { type } : {}),
-            ...(id !== undefined ? { id } : {}),
-            ...(tags !== undefined ? { tags } : {}),
-            ...(sourceFile !== undefined ? { sourceFile } : {}),
-        };
-        const results = await loadEntities(prolog, queryArgs);
-        const paginated = paginateResults(results, limit, offset);
-        // 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}`);
-    }
+    // implements REQ-kibi-operation-interface-parity
+    return querySpec.execute(args, createDiscoveryContext(prolog));
 }

package/dist/tools/relationship-validation.js

@@ -0,0 +1,11 @@
+import { formatInvalidRelationshipError, formatInvalidRelationshipTuple, formatRelationshipSourceMismatch, validateLiveRelationshipTargets as validateSharedTargets, } from "kibi-cli/operations/mutation/relationships";
+export { formatInvalidRelationshipError, formatInvalidRelationshipTuple, formatRelationshipSourceMismatch, };
+export async function validateLiveRelationshipTargets(prolog, entity, relationships) {
+    const port = {
+        query: (goal) => prolog.query(goal),
+        nextSolution: async () => null,
+        invalidateCache: () => prolog.invalidateCache(),
+        save: () => prolog.query("kb_save"),
+    };
+    await validateSharedTargets(port, entity, relationships);
+}

package/dist/tools/search.js

@@ -1,39 +1,6 @@
-import { rankEntities } from "kibi-cli/search-ranking";
-import { resolveWorkspaceRoot } from "../workspace.js";
-import { loadEntities, paginateResults, validateEntityType, } from "./entity-query.js";
-// implements REQ-mcp-search-discovery, REQ-002
+import { searchSpec } from "kibi-cli/operations";
+import { createDiscoveryContext } from "./discovery-adapter.js";
 export async function handleKbSearch(prolog, args) {
-    const { query, type, limit = 20, offset = 0 } = args;
-    const trimmedQuery = query.trim();
-    if (!trimmedQuery) {
-        throw new Error("Search execution failed: query must be a non-empty string");
-    }
-    validateEntityType(type);
-    try {
-        const workspaceRoot = resolveWorkspaceRoot();
-        const entities = await loadEntities(prolog, {
-            ...(type !== undefined ? { type } : {}),
-        });
-        const matches = await rankEntities(entities, trimmedQuery, workspaceRoot);
-        const paginated = paginateResults(matches, limit, offset);
-        const text = matches.length === 0
-            ? `No search results for '${trimmedQuery}'.`
-            : `Found ${matches.length} search results for '${trimmedQuery}'. Showing ${paginated.length} (offset ${offset}, limit ${limit}): ${paginated
-                .map((match) => `${match.entity.id} [${match.reasons.join(", ")}]`)
-                .join(", ")}`;
-        return {
-            content: [{ type: "text", text }],
-            structuredContent: {
-                results: paginated,
-                count: matches.length,
-            },
-        };
-    }
-    catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
-        if (message.startsWith("Search execution failed:")) {
-            throw error;
-        }
-        throw new Error(`Search execution failed: ${message}`);
-    }
+    // implements REQ-kibi-operation-interface-parity, REQ-mcp-search-discovery
+    return searchSpec.execute(args, createDiscoveryContext(prolog));
 }

package/dist/tools/semantic-advisor.js

@@ -1,42 +1,4 @@
-import { analyzeSemanticAdvisorInput } from "../semantic-advisor/analyze-prose.js";
-function normalizeText(value) {
-    const text = typeof value === "string" ? value.trim() : "";
-    if (!text) {
-        throw new Error("Semantic advisor failed: text must be a non-empty string");
-    }
-    return text;
-}
-function optionalString(value) {
-    const text = typeof value === "string" ? value.trim() : "";
-    return text.length > 0 ? text : undefined;
-}
+import { executeSemanticAdvisor } from "kibi-cli/operations";
 export async function handleKbSemanticAdvisor(args) {
-    const text = normalizeText(args.text);
-    const id = optionalString(args.id) ?? "REQ-SEMANTIC-ADVISOR-PREVIEW";
-    const title = optionalString(args.title) ?? text.split(/[.!?]/, 1)[0] ?? text;
-    const source = optionalString(args.source) ?? "mcp://kibi/semantic-advisor";
-    const result = analyzeSemanticAdvisorInput({
-        payload: {
-            type: optionalString(args.type) ?? "req",
-            id,
-            properties: {
-                title,
-                status: optionalString(args.status) ?? "open",
-                source,
-                text_ref: text,
-            },
-        },
-    });
-    return {
-        content: [
-            {
-                type: "text",
-                text: `kb_semantic_advisor: ${result.receipt.summary} Suggestions: ${result.receipt.suggestions.map((suggestion) => suggestion.kind).join(", ") || "none"}.`,
-            },
-        ],
-        structuredContent: {
-            receipt: result.receipt,
-            warnings: result.warnings,
-        },
-    };
+    return executeSemanticAdvisor(args);
 }