kibi-cli 0.14.0 → 0.17.0

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,20 @@
+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";
+export * from "../../logic/ir.js";

package/src/public/operations/node-ports.ts

@@ -0,0 +1,78 @@
+import { execFile } from "node:child_process";
+import * as fs from "node:fs/promises";
+import { promisify } from "node:util";
+import fg from "fast-glob";
+
+import { createRepoIgnorePolicy } from "../ignore-policy.js";
+import type { FilesystemPort, GitPort, NetworkPort } from "./runtime-types.js";
+
+type NodeFilesystemPort = FilesystemPort & {
+  readonly glob: (
+    patterns: readonly string[],
+    options: { readonly cwd: string; readonly includeIgnored?: boolean },
+  ) => Promise<readonly string[]>;
+};
+
+type NodeGitPort = GitPort & {
+  readonly ignoredPaths: (
+    workspaceRoot: string,
+    paths: readonly string[],
+  ) => Promise<readonly string[]>;
+};
+
+const execFileAsync = promisify(execFile);
+const ALWAYS_IGNORED_GLOBS = [
+  "**/.git/**",
+  "**/.kb/**",
+  "**/node_modules/**",
+  "**/vendor/**",
+  "**/vendors/**",
+  "**/third_party/**",
+  "**/third-party/**",
+  "**/dist/**",
+  "**/build/**",
+  "**/coverage/**",
+  "**/target/**",
+] as const;
+
+export const nodeFilesystem: NodeFilesystemPort = {
+  readFile: (filePath) => fs.readFile(filePath, "utf8"),
+  writeFile: async (filePath, data) => {
+    await fs.writeFile(filePath, data, "utf8");
+  },
+  mkdir: async (directoryPath) => {
+    await fs.mkdir(directoryPath, { recursive: true });
+  },
+  stat: (filePath) => fs.stat(filePath),
+  glob: (patterns, options) =>
+    fg([...patterns], {
+      cwd: options.cwd,
+      onlyFiles: true,
+      unique: true,
+      dot: true,
+      suppressErrors: true,
+      ignore: [...ALWAYS_IGNORED_GLOBS],
+    }),
+};
+
+export const nodeGit: NodeGitPort = {
+  revParse: async (...args) => {
+    const { stdout } = await execFileAsync("git", ["rev-parse", ...args]);
+    return stdout.trim();
+  },
+  showToplevel: async () => {
+    const { stdout } = await execFileAsync("git", [
+      "rev-parse",
+      "--show-toplevel",
+    ]);
+    return stdout.trim();
+  },
+  ignoredPaths: async (workspaceRoot, paths) => {
+    const policy = createRepoIgnorePolicy(workspaceRoot);
+    return paths.filter((candidate) => policy.isIgnored(candidate));
+  },
+};
+
+export const nodeNetwork: NetworkPort = {
+  fetch: (input, init) => globalThis.fetch(input, init),
+};

package/src/public/operations/prolog-json.ts

@@ -0,0 +1,71 @@
+import path from "node:path";
+
+import { getKbPlPathOverride } from "../../env.js";
+import { resolveKbPlPath } from "../../prolog.js";
+import { escapeAtom } from "../../prolog/codec.js";
+import type { PrologPort } from "./runtime-types.js";
+
+function resolveCoreModulePath(fileName: string): string {
+  const genericOverride = getKbPlPathOverride();
+  return path.join(
+    path.dirname(genericOverride ?? resolveKbPlPath()),
+    fileName,
+  );
+}
+
+export async function runOperationJsonQuery<T>(
+  prolog: PrologPort,
+  fileName: string,
+  goal: string,
+  errorLabel: string,
+): Promise<T> {
+  const modulePath = escapeAtom(
+    resolveCoreModulePath(fileName).replaceAll("\\", "/"),
+  );
+  const oneShotMode =
+    typeof (globalThis as { Bun?: unknown }).Bun !== "undefined";
+  const result = oneShotMode
+    ? await prolog.query(`(use_module('${modulePath}'), ${goal})`)
+    : await runInteractiveModuleQuery(prolog, modulePath, goal, errorLabel);
+  if (!result.success) {
+    throw new Error(
+      `${errorLabel} query failed: ${result.error ?? "Unknown error"}`,
+    );
+  }
+  const rawJson = result.bindings.JsonString;
+  if (rawJson === undefined) {
+    throw new Error(`${errorLabel} query returned no JsonString binding`);
+  }
+  let parsed: unknown = JSON.parse(rawJson);
+  if (typeof parsed === "string") {
+    parsed = JSON.parse(parsed);
+  }
+  return parsed as T;
+}
+
+async function runInteractiveModuleQuery(
+  prolog: PrologPort,
+  modulePath: string,
+  goal: string,
+  errorLabel: string,
+) {
+  const loadResult = await prolog.query(`use_module('${modulePath}')`);
+  if (!loadResult.success) {
+    throw new Error(
+      `${errorLabel} module load failed: ${loadResult.error ?? "Unknown error"}`,
+    );
+  }
+  return prolog.query(goal);
+}
+
+export function toPrologAtom(value?: string): string {
+  return value === undefined || value === ""
+    ? "none"
+    : `'${escapeAtom(value)}'`;
+}
+
+export function toPrologList(values?: readonly string[]): string {
+  return values === undefined || values.length === 0
+    ? "[]"
+    : `[${values.map((value) => `'${escapeAtom(value)}'`).join(",")}]`;
+}

package/src/public/operations/runtime-types.ts

@@ -0,0 +1,106 @@
+import type { OperationEffect } from "./types.js";
+
+export type { OperationEffect } from "./types.js";
+
+export type PrologQueryResult = {
+  readonly success: boolean;
+  readonly bindings: Readonly<Record<string, string>>;
+  readonly error?: string;
+};
+
+// implements REQ-kibi-operation-interface-parity
+export interface PrologPort {
+  query(goal: string): Promise<PrologQueryResult>;
+  nextSolution(): Promise<PrologQueryResult | null>;
+  invalidateCache?(): void;
+  save(): Promise<PrologQueryResult>;
+}
+
+export type FilesystemStat = {
+  readonly isFile: () => boolean;
+  readonly isDirectory: () => boolean;
+};
+
+export interface FilesystemPort {
+  readFile(path: string): Promise<string>;
+  writeFile(path: string, data: string): Promise<void>;
+  mkdir(path: string): Promise<void>;
+  stat(path: string): Promise<FilesystemStat>;
+}
+
+export interface GitPort {
+  revParse(...args: readonly string[]): Promise<string>;
+  showToplevel(): Promise<string>;
+}
+
+export interface NetworkPort {
+  fetch(input: string | URL, init?: RequestInit): Promise<Response>;
+}
+
+export type Clock = () => Date;
+
+export type RuntimeOptions = {
+  readonly workspaceRoot?: string;
+  readonly signal?: AbortSignal;
+  readonly clock?: Clock;
+  readonly prolog?: PrologPort;
+  readonly fs?: FilesystemPort;
+  readonly git?: GitPort;
+  readonly net?: NetworkPort;
+};
+
+export type OperationContext = {
+  readonly workspaceRoot: string;
+  readonly signal: AbortSignal;
+  readonly clock: Clock;
+  readonly prolog?: PrologPort;
+  readonly fs?: FilesystemPort;
+  readonly git?: GitPort;
+  readonly net?: NetworkPort;
+};
+
+export interface RuntimeOperationSpec<TInput = unknown, TResult = unknown> {
+  readonly name: string;
+  readonly effects: readonly OperationEffect[];
+  readonly requiresProlog: boolean;
+  execute(input: TInput, context: OperationContext): Promise<TResult>;
+}
+
+export type OperationOutcome =
+  | { readonly status: "success"; readonly result: unknown }
+  | { readonly status: "error"; readonly error: unknown };
+
+// implements REQ-kibi-operation-interface-parity
+export interface OperationRuntime {
+  open(
+    spec: RuntimeOperationSpec<unknown, unknown>,
+    opts?: RuntimeOptions,
+  ): Promise<OperationContext>;
+  afterSuccess(
+    spec: RuntimeOperationSpec<unknown, unknown>,
+    context: OperationContext,
+  ): Promise<void>;
+  close(context: OperationContext, outcome: OperationOutcome): Promise<void>;
+}
+
+// implements REQ-kibi-operation-interface-parity
+export async function executeOperation<TInput, TResult>(
+  runtime: OperationRuntime,
+  spec: RuntimeOperationSpec<TInput, TResult>,
+  input: TInput,
+  opts?: RuntimeOptions,
+): Promise<TResult> {
+  const context = await runtime.open(spec, opts);
+  let result: TResult;
+  try {
+    result = await spec.execute(input, context);
+    if (spec.effects.includes("kb-write")) {
+      await runtime.afterSuccess(spec, context);
+    }
+  } catch (error) {
+    await runtime.close(context, { status: "error", error });
+    throw error;
+  }
+  await runtime.close(context, { status: "success", result });
+  return result;
+}

package/src/public/operations/specs/autopilot.ts

@@ -0,0 +1,98 @@
+import { executeAutopilotGenerate } from "../../../operations/autopilot/generate.js";
+import type {
+  AutopilotGenerateArgs,
+  AutopilotGenerateResult,
+} from "../../../operations/autopilot/types.js";
+import type { OperationSpec } from "../types.js";
+
+export type {
+  AutopilotBootstrapContext,
+  AutopilotGenerateArgs,
+  AutopilotGenerateResult,
+} from "../../../operations/autopilot/types.js";
+export { executeAutopilotGenerate } from "../../../operations/autopilot/generate.js";
+
+export const autopilotGenerateSpec = {
+  name: "kb_autopilot_generate",
+  cliName: "autopilot-generate",
+  description:
+    "Generate agent-centric bootstrap output for KB population. Read-only analysis that returns activation state, bootstrap guidance, candidate entities with evidence, payoff summary, and exact applyPlan payloads for later kb_upsert calls. No mutation side effects.",
+  businessInputSchema: {
+    type: "object",
+    properties: {
+      includeGenericMarkdown: {
+        type: "boolean",
+        default: true,
+        description:
+          "Whether to include generic markdown file content as candidate facts. Default: true.",
+      },
+      minConfidence: {
+        type: "number",
+        default: 0.8,
+        minimum: 0.6,
+        maximum: 0.95,
+        description:
+          "Minimum confidence threshold for candidates. Clamped to [0.60, 0.95]. Default: 0.80.",
+      },
+      maxCandidates: {
+        type: "integer",
+        default: 50,
+        minimum: 1,
+        maximum: 200,
+        description:
+          "Maximum number of candidates to return. Clamped to [1, 200]. Default: 50.",
+      },
+      entityTypes: {
+        type: "array",
+        items: {
+          type: "string",
+          enum: ["req", "scenario", "test", "adr", "fact", "symbol"],
+        },
+        description:
+          "Optional filter to limit candidate generation to specific entity types.",
+      },
+      bootstrapContext: {
+        type: "object",
+        description:
+          "Optional declared bootstrap context supplied by the agent to ground the read-only synthesis output.",
+        properties: {
+          projectSummary: {
+            type: "string",
+            description:
+              "Optional short summary of the project or bootstrap goal.",
+          },
+          sourceOfTruthPaths: {
+            type: "array",
+            items: { type: "string" },
+            description:
+              "Optional repo-relative paths that should be treated as declared sources of truth.",
+          },
+          sourceOfTruthNotes: {
+            type: "array",
+            items: { type: "string" },
+            description:
+              "Optional notes about how to interpret the declared sources of truth.",
+          },
+          priorityRoots: {
+            type: "array",
+            items: { type: "string" },
+            description:
+              "Optional repo roots the bootstrap flow should prioritize when authoring entities.",
+          },
+          verificationAnchors: {
+            type: "array",
+            items: { type: "string" },
+            description:
+              "Optional verification commands, documents, or checkpoints to reference in the output.",
+          },
+        },
+      },
+    },
+  },
+  requiresProlog: false,
+  effects: ["workspace-read"],
+  execute: executeAutopilotGenerate,
+} as const satisfies OperationSpec<
+  AutopilotGenerateArgs,
+  AutopilotGenerateResult["structuredContent"]
+>;

package/src/public/operations/specs/check.ts

@@ -0,0 +1,75 @@
+import { executeCheck } from "../check-executor.js";
+import type { OperationSpec } from "../types.js";
+
+export const checkSpec = {
+  name: "kb_check",
+  cliName: "check",
+  description:
+    "Run KB validation rules and return violations. Use before or after mutations, and after meaningful source edits with impact options to surface symbol granularity and semantic-review diagnostics. Do not use for point lookups. No write side effects. Prefer explicit rules for faster iteration; omit rules for final full validation plus full-KB qualityDiagnostics review.",
+  businessInputSchema: {
+    type: "object",
+    properties: {
+      rules: {
+        type: "array",
+        items: {
+          type: "string",
+          enum: [
+            "must-priority-coverage",
+            "symbol-coverage",
+            "symbol-traceability",
+            "no-dangling-refs",
+            "no-cycles",
+            "required-fields",
+            "deprecated-adr-no-successor",
+            "domain-contradictions",
+            "strict-fact-shape",
+            "strict-req-fact-pairing",
+            "predicate-verifiability",
+            "logic-coverage",
+            "rule-safety",
+            "rule-verifiability",
+            "semantic-completeness",
+            "query-plan-safety",
+          ],
+        },
+        description:
+          "Optional rule subset. Allowed: must-priority-coverage, symbol-coverage, symbol-traceability, no-dangling-refs, no-cycles, required-fields, deprecated-adr-no-successor, domain-contradictions, strict-fact-shape, strict-req-fact-pairing, predicate-verifiability, logic-coverage, rule-safety, rule-verifiability, semantic-completeness, query-plan-safety. If omitted, server runs all rules plus the full-KB qualityDiagnostics audit scan; if supplied, server preserves scoped validation and skips the full-KB advisory scan.",
+      },
+      sourceFiles: {
+        type: "array",
+        items: { type: "string" },
+        description:
+          "Optional repo-relative source files to inspect for early impact diagnostics. Use with includeImpactDiagnostics after meaningful source edits.",
+      },
+      staged: {
+        type: "boolean",
+        description:
+          "When true, inspect staged source changes for impact diagnostics using the shared CLI impact analyzer without shelling out to kibi check.",
+      },
+      includeWorkingTreeDiff: {
+        type: "boolean",
+        description:
+          "When true, inspect current unstaged working-tree diffs for impact diagnostics. Pair with sourceFiles to scope the analysis.",
+      },
+      includeImpactDiagnostics: {
+        type: "boolean",
+        description:
+          "When true, include changed-file impact diagnostics such as symbol_granularity_violation and symbol_semantic_review_needed in structured output.",
+      },
+      maxDiagnostics: {
+        type: "integer",
+        minimum: 0,
+        description:
+          "Optional maximum number of impact diagnostics to return. Graph validation violations are not capped by this value.",
+      },
+      workspaceRoot: {
+        type: "string",
+        description:
+          "Optional workspace root for impact diagnostics and .kb/config.json lookup. Defaults to the MCP server workspace.",
+      },
+    },
+  },
+  requiresProlog: true,
+  effects: ["kb-read", "workspace-read"],
+  execute: executeCheck,
+} as const satisfies OperationSpec;