kibi-cli 0.14.0 → 0.16.1

package/src/public/operations/check-format-shared.ts

@@ -0,0 +1,178 @@
+import type { Violation } from "../check-types.js";
+/*
+ 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 type { ChangedFileImpactResult } from "../impact-diagnostics.js";
+import type { QualityDiagnostic } from "../impact-diagnostics.js";
+
+// implements REQ-mcp-tool-check
+export interface CheckDiagnostic {
+  readonly category: string;
+  readonly severity: "error" | "warning";
+  readonly message: string;
+  readonly file?: string;
+  readonly suggestion?: string;
+}
+
+// implements REQ-mcp-tool-check
+export interface CheckStructuredContent {
+  readonly violations: readonly Violation[];
+  readonly count: number;
+  readonly diagnostics: readonly CheckDiagnostic[];
+  readonly qualityDiagnostics?: readonly QualityDiagnostic[];
+  readonly impactDiagnostics?: ChangedFileImpactResult["impactDiagnostics"];
+  readonly sourceFiles?: ChangedFileImpactResult["sourceFiles"];
+  readonly extractedSymbols?: ChangedFileImpactResult["extractedSymbols"];
+  readonly linkedEntities?: ChangedFileImpactResult["linkedEntities"];
+  readonly nextActions?: ChangedFileImpactResult["nextActions"];
+}
+
+function formatDiagnostics(diagnostics: readonly CheckDiagnostic[]) {
+  return diagnostics.map((d) => ({
+    category: d.category,
+    severity: d.severity,
+    message: d.message,
+    ...(d.file !== undefined ? { file: d.file } : {}),
+    ...(d.suggestion !== undefined ? { suggestion: d.suggestion } : {}),
+  }));
+}
+
+// implements REQ-mcp-tool-check
+export function formatImpactText(
+  impactResult: ChangedFileImpactResult,
+): string {
+  if (impactResult.impactDiagnostics.length === 0) {
+    return "No impact diagnostics found";
+  }
+
+  const details = impactResult.impactDiagnostics.map((diagnostic) => {
+    const files =
+      diagnostic.files.length > 0
+        ? diagnostic.files.join(", ")
+        : "unknown-source";
+    return `- ${diagnostic.id} | ${diagnostic.severity} | ${files} | ${diagnostic.message} Suggestion: ${diagnostic.suggestion}`;
+  });
+  return `${impactResult.impactDiagnostics.length} impact diagnostics found\n${details.join("\n")}`;
+}
+
+function formatOptionalList(
+  label: string,
+  values: readonly string[] | undefined,
+) {
+  if (values === undefined || values.length === 0) {
+    return [];
+  }
+  return [`${label}: ${values.join(", ")}`];
+}
+
+// implements REQ-mcp-tool-check
+export function formatQualityDiagnosticsText(
+  diagnostics: readonly QualityDiagnostic[],
+): string {
+  if (diagnostics.length === 0) {
+    return "No quality diagnostics found";
+  }
+
+  const details = diagnostics.map((diagnostic) => {
+    const parts = [
+      diagnostic.id,
+      diagnostic.severity,
+      diagnostic.category,
+      diagnostic.message,
+    ];
+    const metadata = [
+      `Blocking: ${diagnostic.blocking ? "yes" : "no"}`,
+      ...formatOptionalList("Files", diagnostic.files),
+      ...formatOptionalList("Docs", diagnostic.docs),
+      ...(diagnostic.entityId !== undefined
+        ? [`Entity: ${diagnostic.entityId}`]
+        : []),
+      ...(diagnostic.source !== undefined
+        ? [`Source: ${diagnostic.source}`]
+        : []),
+      `Suggestion: ${diagnostic.suggestion}`,
+    ];
+    return `- ${parts.join(" | ")}\n  ${metadata.join("\n  ")}`;
+  });
+
+  return `${diagnostics.length} quality diagnostic${diagnostics.length === 1 ? "" : "s"} found\n${details.join("\n")}`;
+}
+
+// implements REQ-mcp-tool-check
+export function formatViolationText(violations: readonly Violation[]): string {
+  if (violations.length === 0) {
+    return "No violations found";
+  }
+
+  const details = violations.map((violation) => {
+    const parts = [
+      violation.rule,
+      violation.entityId,
+      violation.source ?? "unknown-source",
+      violation.description,
+    ];
+    if (violation.suggestion) {
+      parts.push(`Suggestion: ${violation.suggestion}`);
+    }
+    return `- ${parts.join(" | ")}`;
+  });
+
+  return `${violations.length} violations found\n${details.join("\n")}`;
+}
+
+// implements REQ-mcp-tool-check
+export function buildStructuredContent(input: {
+  violations: readonly Violation[];
+  diagnostics: readonly CheckDiagnostic[];
+  qualityDiagnostics?: readonly QualityDiagnostic[];
+  impactResult: ChangedFileImpactResult | undefined;
+}): CheckStructuredContent {
+  const qualityDiagnostics = input.qualityDiagnostics ?? [];
+  return {
+    violations: [...input.violations],
+    count: input.violations.length,
+    diagnostics: formatDiagnostics(input.diagnostics),
+    ...(qualityDiagnostics.length > 0
+      ? { qualityDiagnostics: [...qualityDiagnostics] }
+      : {}),
+    ...(input.impactResult
+      ? {
+          impactDiagnostics: input.impactResult.impactDiagnostics,
+          sourceFiles: input.impactResult.sourceFiles,
+          extractedSymbols: input.impactResult.extractedSymbols,
+          linkedEntities: input.impactResult.linkedEntities,
+          nextActions: input.impactResult.nextActions,
+        }
+      : {}),
+  };
+}
+
+// implements REQ-mcp-tool-check
+export function buildSummary(input: {
+  readonly violations: readonly Violation[];
+  readonly impactResult: ChangedFileImpactResult | undefined;
+  readonly qualityDiagnostics: readonly QualityDiagnostic[];
+}): string {
+  const sections = [formatViolationText(input.violations)];
+  if (input.impactResult !== undefined) {
+    sections.push(formatImpactText(input.impactResult));
+  }
+  if (input.qualityDiagnostics.length > 0) {
+    sections.push(formatQualityDiagnosticsText(input.qualityDiagnostics));
+  }
+  return sections.join("\n");
+}

package/src/public/operations/check-helpers.ts

@@ -0,0 +1,141 @@
+import { readFileSync } from "node:fs";
+/*
+ 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 { readFile } from "node:fs/promises";
+import path from "node:path";
+import { getKbPlPathOverride } from "../../env.js";
+import { resolveKbPlPath } from "../../prolog.js";
+import { analyzePrologQueryPlanSafety } from "../../utils/prolog-query-plan-safety.js";
+import {
+  type ChecksConfig,
+  DEFAULT_CHECKS_CONFIG,
+  RULE_NAMES,
+  type Violation,
+  getEffectiveRules,
+} from "../../utils/rule-registry.js";
+import {
+  type ChangedFileImpactResult,
+  type QualityDiagnostic,
+  analyzeChangedFileImpact,
+} from "../impact-diagnostics.js";
+import type { CheckInput } from "./check-executor.js";
+
+export { RULE_NAMES, getEffectiveRules };
+
+function resolveChecksPlPath(): string {
+  const override = getKbPlPathOverride();
+  return path.join(path.dirname(override ?? resolveKbPlPath()), "checks.pl");
+}
+
+// implements REQ-mcp-tool-check
+export function collectQueryPlanSafetyViolations(): Violation[] {
+  const checksPlPath = resolveChecksPlPath();
+  const source = readFileSync(checksPlPath, "utf8");
+  return analyzePrologQueryPlanSafety(source).map((v) => ({
+    rule: "query-plan-safety",
+    entityId: v.predicate,
+    description: v.description,
+    suggestion: v.suggestion,
+    source: `${checksPlPath}:${v.line}`,
+  }));
+}
+
+// implements REQ-mcp-tool-check
+export async function loadChecksConfig(
+  workspaceRoot: string,
+): Promise<ChecksConfig> {
+  const configPath = path.join(workspaceRoot, ".kb", "config.json");
+  try {
+    const content = await readFile(configPath, "utf8");
+    const parsed = JSON.parse(content) as {
+      checks?: Partial<ChecksConfig>;
+    };
+
+    const parsedRules = parsed.checks?.rules;
+    const normalizedRules: Record<string, boolean> = {
+      ...DEFAULT_CHECKS_CONFIG.rules,
+    };
+    if (parsedRules && typeof parsedRules === "object") {
+      for (const [key, value] of Object.entries(parsedRules)) {
+        if (typeof value === "boolean") {
+          normalizedRules[key] = value;
+        }
+      }
+    }
+
+    const parsedSt = parsed.checks?.symbolTraceability;
+    const normalizedSt = { ...DEFAULT_CHECKS_CONFIG.symbolTraceability };
+    if (
+      parsedSt &&
+      typeof parsedSt === "object" &&
+      typeof parsedSt.requireAdr === "boolean"
+    ) {
+      normalizedSt.requireAdr = parsedSt.requireAdr;
+    }
+
+    return { rules: normalizedRules, symbolTraceability: normalizedSt };
+  } catch {
+    return DEFAULT_CHECKS_CONFIG;
+  }
+}
+
+// implements REQ-mcp-tool-check
+export function hasImpactOptions(args: CheckInput): boolean {
+  return Boolean(
+    args.includeImpactDiagnostics ||
+      args.staged ||
+      args.includeWorkingTreeDiff ||
+      (args.sourceFiles !== undefined && args.sourceFiles.length > 0),
+  );
+}
+
+// implements REQ-mcp-tool-check
+export function analyzeKbCheckImpact(
+  workspaceRoot: string,
+  args: CheckInput,
+): ChangedFileImpactResult | undefined {
+  if (!hasImpactOptions(args)) {
+    return undefined;
+  }
+  return analyzeChangedFileImpact({
+    workspaceRoot,
+    ...(args.sourceFiles !== undefined
+      ? { sourceFiles: args.sourceFiles }
+      : {}),
+    ...(args.staged !== undefined ? { staged: args.staged } : {}),
+    ...(args.includeWorkingTreeDiff !== undefined
+      ? { includeWorkingTreeDiff: args.includeWorkingTreeDiff }
+      : {}),
+    ...(args.includeImpactDiagnostics !== undefined
+      ? { includeImpactDiagnostics: args.includeImpactDiagnostics }
+      : {}),
+    ...(args.maxDiagnostics !== undefined
+      ? { maxDiagnostics: args.maxDiagnostics }
+      : {}),
+  });
+}
+
+// implements REQ-mcp-tool-check
+export function qualityDiagnosticsFromImpact(
+  impactResult: ChangedFileImpactResult | undefined,
+): readonly QualityDiagnostic[] {
+  if (impactResult === undefined) return [];
+  return impactResult.impactDiagnostics.filter(
+    (d) => !d.blocking && d.severity !== "error",
+  );
+}

package/src/public/operations/discovery-entities.ts

@@ -0,0 +1,122 @@
+import {
+  escapeAtomContent,
+  parseEntityFromBinding,
+  parseEntityFromList,
+  parseListOfLists,
+} from "../../prolog/codec.js";
+import type { PrologPort } from "./runtime-types.js";
+
+export type EntityQueryInput = {
+  readonly type?: string;
+  readonly id?: string;
+  readonly tags?: readonly string[];
+  readonly sourceFile?: string;
+};
+
+export const VALID_ENTITY_TYPES = [
+  "req",
+  "scenario",
+  "test",
+  "adr",
+  "flag",
+  "event",
+  "symbol",
+  "fact",
+] as const;
+
+// implements REQ-002, REQ-013
+export function validateEntityType(type?: string): void {
+  if (type && !VALID_ENTITY_TYPES.some((candidate) => candidate === 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.`,
+    );
+  }
+}
+
+// implements REQ-002, REQ-013
+export function buildEntityGoal(input: EntityQueryInput): string {
+  const { type, id, tags, sourceFile } = input;
+  if (sourceFile) {
+    const safeSource = escapeAtomContent(sourceFile);
+    if (type) {
+      const safeType = escapeAtomContent(type);
+      return `findall([Id,'${safeType}',Props], (kb_entities_by_source('${safeSource}', SourceIds), member(Id, SourceIds), kb_entity(Id, '${safeType}', Props)), Results)`;
+    }
+    return `findall([Id,Type,Props], (kb_entities_by_source('${safeSource}', SourceIds), member(Id, SourceIds), kb_entity(Id, Type, Props)), Results)`;
+  }
+  if (id && type) {
+    const safeId = escapeAtomContent(id);
+    const safeType = escapeAtomContent(type);
+    return `findall(['${safeId}','${safeType}',Props], kb_entity('${safeId}', '${safeType}', Props), Results)`;
+  }
+  if (id) {
+    const safeId = escapeAtomContent(id);
+    return `findall(['${safeId}',Type,Props], kb_entity('${safeId}', Type, Props), Results)`;
+  }
+  if (tags && tags.length > 0) {
+    if (type) {
+      const safeType = escapeAtomContent(type);
+      return `findall([Id,'${safeType}',Props], kb_entity(Id, '${safeType}', Props), Results)`;
+    }
+    return "findall([Id,Type,Props], kb_entity(Id, Type, Props), Results)";
+  }
+  if (type) {
+    const safeType = escapeAtomContent(type);
+    return `findall([Id,'${safeType}',Props], kb_entity(Id, '${safeType}', Props), Results)`;
+  }
+  return "findall([Id,Type,Props], kb_entity(Id, Type, Props), Results)";
+}
+
+// implements REQ-002, REQ-013
+export async function loadEntities(
+  prolog: Pick<PrologPort, "query">,
+  input: EntityQueryInput,
+): Promise<Record<string, unknown>[]> {
+  validateEntityType(input.type);
+  const queryResult = await prolog.query(buildEntityGoal(input));
+  if (!queryResult.success) {
+    throw new Error(queryResult.error || "Query failed with unknown error");
+  }
+
+  let entities: Record<string, unknown>[] = [];
+  const resultsBinding = queryResult.bindings.Results;
+  const resultBinding = queryResult.bindings.Result;
+  if (resultsBinding) {
+    entities = parseListOfLists(resultsBinding).map(parseEntityFromList);
+  } else if (resultBinding) {
+    entities = [parseEntityFromBinding(resultBinding)];
+  }
+  if (input.tags && input.tags.length > 0) {
+    const requested = new Set(input.tags.map((tag) => tag.trim()));
+    entities = entities.filter((entity) => {
+      const tags = entity.tags;
+      return (
+        Array.isArray(tags) &&
+        tags.some((tag) => requested.has(String(tag).trim()))
+      );
+    });
+  }
+  return dedupeEntities(entities);
+}
+
+// implements REQ-002
+export function paginateResults<T>(
+  results: readonly T[],
+  limit = 100,
+  offset = 0,
+): T[] {
+  return results.slice(offset, offset + limit);
+}
+
+// implements REQ-002
+export function dedupeEntities(
+  entities: readonly Record<string, unknown>[],
+): Record<string, unknown>[] {
+  const seen = new Set<string>();
+  return entities.filter((entity) => {
+    const key = `${String(entity.type ?? "")}::${String(entity.id ?? "")}`;
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+}

package/src/public/operations/discovery-executors.ts

@@ -0,0 +1,176 @@
+import { rankEntities } from "../../search-ranking.js";
+import type { SearchMatch } from "../../search-ranking.js";
+import {
+  loadEntities,
+  paginateResults,
+  validateEntityType,
+} from "./discovery-entities.js";
+import { runOperationJsonQuery } from "./prolog-json.js";
+import type { OperationContext, PrologPort } from "./runtime-types.js";
+import type { OperationResult } from "./types.js";
+
+export type QueryInput = {
+  readonly type?: string;
+  readonly id?: string;
+  readonly tags?: readonly string[];
+  readonly sourceFile?: string;
+  readonly limit?: number;
+  readonly offset?: number;
+};
+
+export type QueryPayload = {
+  readonly entities: readonly Record<string, unknown>[];
+  readonly count: number;
+};
+
+export type SearchInput = {
+  readonly query: string;
+  readonly type?: string;
+  readonly limit?: number;
+  readonly offset?: number;
+};
+
+export type SearchPayload = {
+  readonly results: readonly SearchMatch[];
+  readonly count: number;
+};
+
+export type StatusInput = Readonly<Record<string, never>>;
+
+export type StatusPayload = {
+  readonly branch: string;
+  readonly snapshotId: string;
+  readonly syncedAt: string | null;
+  readonly dirty: boolean;
+  readonly syncState: string;
+  readonly kbPath?: string;
+  readonly lastSyncSource?: string;
+};
+
+function requireProlog(context: OperationContext): PrologPort {
+  if (!context.prolog) {
+    throw new Error("Discovery operation requires a Prolog context");
+  }
+  return context.prolog;
+}
+
+function isStatusPayload(value: unknown): value is StatusPayload {
+  if (value === null || typeof value !== "object") return false;
+  const record = Object.fromEntries(Object.entries(value));
+  return (
+    typeof record.branch === "string" &&
+    typeof record.snapshotId === "string" &&
+    (typeof record.syncedAt === "string" || record.syncedAt === null) &&
+    typeof record.dirty === "boolean" &&
+    typeof record.syncState === "string"
+  );
+}
+
+export async function executeQuery(
+  input: QueryInput,
+  context: OperationContext,
+): Promise<OperationResult<QueryPayload>> {
+  // implements REQ-kibi-operation-interface-parity
+  const { type, id, tags, sourceFile, limit = 100, offset = 0 } = input;
+  try {
+    const entities = await loadEntities(requireProlog(context), {
+      ...(type !== undefined ? { type } : {}),
+      ...(id !== undefined ? { id } : {}),
+      ...(tags !== undefined ? { tags } : {}),
+      ...(sourceFile !== undefined ? { sourceFile } : {}),
+    });
+    const paginated = paginateResults(entities, limit, offset);
+    const text =
+      entities.length === 0
+        ? `No entities found${type ? ` of type '${type}'` : ""}.`
+        : `Found ${entities.length} entities${type ? ` of type '${type}'` : ""}. Showing ${paginated.length} (offset ${offset}, limit ${limit}): ${paginated
+            .map((entity) => {
+              const entityId = String(entity.id ?? "").replace(
+                /^file:\/\/.*\//,
+                "",
+              );
+              return `${entityId} (${String(entity.title ?? "")}, status=${String(entity.status ?? "")})`;
+            })
+            .join(", ")}`;
+    return {
+      content: [{ type: "text", text }],
+      structuredContent: { entities: paginated, count: entities.length },
+    };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(`Query execution failed: ${message}`);
+  }
+}
+
+export async function executeSearch(
+  input: SearchInput,
+  context: OperationContext,
+): Promise<OperationResult<SearchPayload>> {
+  // implements REQ-kibi-operation-interface-parity, REQ-mcp-search-discovery
+  const { query, type, limit = 20, offset = 0 } = input;
+  const trimmedQuery = query.trim();
+  if (!trimmedQuery) {
+    throw new Error(
+      "Search execution failed: query must be a non-empty string",
+    );
+  }
+  validateEntityType(type);
+  try {
+    const entities = await loadEntities(requireProlog(context), {
+      ...(type !== undefined ? { type } : {}),
+    });
+    const matches = await rankEntities(
+      entities,
+      trimmedQuery,
+      context.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) =>
+                `${String(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}`);
+  }
+}
+
+export async function executeStatus(
+  _input: StatusInput,
+  context: OperationContext,
+): Promise<OperationResult<StatusPayload>> {
+  // implements REQ-kibi-operation-interface-parity, REQ-cli-status-pre-first-sync
+  try {
+    const payload = await runOperationJsonQuery<StatusPayload>(
+      requireProlog(context),
+      "status.pl",
+      "status:kb_status_json(JsonString)",
+      "Status execution",
+    );
+    if (!isStatusPayload(payload)) {
+      throw new Error("Status execution query returned an invalid payload");
+    }
+    return {
+      content: [
+        {
+          type: "text",
+          text: `Branch ${payload.branch} is ${payload.syncState} (snapshot ${payload.snapshotId}, dirty=${payload.dirty})`,
+        },
+      ],
+      structuredContent: payload,
+    };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(`Status execution failed: ${message}`);
+  }
+}

package/src/public/operations/index.ts

@@ -0,0 +1,19 @@
+export * from "./catalog.js";
+export * from "./check-executor.js";
+export * from "./discovery-entities.js";
+export * from "./discovery-executors.js";
+export * from "./runtime-types.js";
+export * from "./node-ports.js";
+export * from "./specs/autopilot.js";
+export * from "./specs/check.js";
+export * from "./specs/discovery.js";
+export * from "./specs/modeling.js";
+export * from "./specs/mutation.js";
+export * from "./specs/reporting.js";
+export * from "./specs/semantic.js";
+export * from "./specs/skills.js";
+export * from "./specs/sparql.js";
+export * from "./types.js";
+export * from "../../operations/autopilot/generate.js";
+export * from "../../operations/autopilot/presentation.js";
+export type * from "../../operations/autopilot/types.js";