kibi-cli 0.12.8 → 0.16.1

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";

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"]
+>;