kibi-cli 0.14.0 → 0.17.0

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

@@ -0,0 +1,249 @@
+import {
+  runOperationJsonQuery,
+  toPrologAtom,
+  toPrologList,
+} from "../prolog-json.js";
+import type { OperationContext } from "../runtime-types.js";
+import type { OperationResult, OperationSpec } from "../types.js";
+
+const ENTITY_TYPES = [
+  "req",
+  "scenario",
+  "test",
+  "adr",
+  "flag",
+  "event",
+  "symbol",
+  "fact",
+] as const;
+const ENTITY_TYPE_SET: ReadonlySet<string> = new Set(ENTITY_TYPES);
+
+export type FindGapsInput = {
+  readonly type?: string;
+  readonly missingRelationships?: readonly string[];
+  readonly presentRelationships?: readonly string[];
+  readonly tags?: readonly string[];
+  readonly sourceFile?: string;
+  readonly limit?: number;
+  readonly offset?: number;
+};
+
+export type FindGapsPayload = {
+  readonly rows: readonly Readonly<Record<string, unknown>>[];
+  readonly count: number;
+  readonly meta?: Readonly<Record<string, unknown>>;
+};
+
+export type CoverageInput = {
+  readonly by?: "req" | "symbol" | "type";
+  readonly tags?: readonly string[];
+  readonly includePassing?: boolean;
+  readonly includeTransitive?: boolean;
+  readonly limit?: number;
+  readonly offset?: number;
+};
+
+export type CoveragePayload = {
+  readonly summary: Readonly<Record<string, number>>;
+  readonly rows: readonly Readonly<Record<string, unknown>>[];
+  readonly meta?: Readonly<Record<string, unknown>>;
+};
+
+export type GraphInput = {
+  readonly seedIds: readonly string[];
+  readonly relationships?: readonly string[];
+  readonly direction?: "outgoing" | "incoming" | "both";
+  readonly depth?: number;
+  readonly entityTypes?: readonly string[];
+  readonly maxNodes?: number;
+  readonly maxEdges?: number;
+};
+
+export type GraphPayload = {
+  readonly nodes: readonly Readonly<Record<string, unknown>>[];
+  readonly edges: readonly Readonly<Record<string, unknown>>[];
+  readonly truncated: boolean;
+  readonly meta?: Readonly<Record<string, unknown>>;
+};
+
+function requireProlog(context: OperationContext) {
+  if (context.prolog === undefined) {
+    throw new Error("Reporting operation requires a Prolog runtime");
+  }
+  return context.prolog;
+}
+
+function validateEntityType(type?: string): void {
+  if (type !== undefined && !ENTITY_TYPE_SET.has(type)) {
+    throw new Error(
+      `Invalid type '${type}'. Valid types: ${ENTITY_TYPES.join(", ")}. Use a single type value, or omit this parameter to query all entities.`,
+    );
+  }
+}
+
+export async function executeFindGaps(
+  input: FindGapsInput,
+  context: OperationContext,
+): Promise<OperationResult<FindGapsPayload>> {
+  validateEntityType(input.type);
+  try {
+    const payload = await runOperationJsonQuery<FindGapsPayload>(
+      requireProlog(context),
+      "discovery.pl",
+      `discovery:find_gaps_json(${toPrologAtom(input.type)}, ${toPrologList(input.missingRelationships)}, ${toPrologList(input.presentRelationships)}, ${toPrologList(input.tags)}, ${toPrologAtom(input.sourceFile)}, ${input.limit ?? 100}, ${input.offset ?? 0}, JsonString)`,
+      "Find-gaps execution",
+    );
+    const rows = payload.rows ?? [];
+    return {
+      content: [
+        {
+          type: "text",
+          text:
+            rows.length === 0
+              ? "No matching gaps found."
+              : `Found ${payload.count ?? rows.length} gap rows. Showing ${rows.length}: ${rows.map((row) => row.id).join(", ")}`,
+        },
+      ],
+      structuredContent: payload,
+    };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(`Find-gaps execution failed: ${message}`);
+  }
+}
+
+export const findGapsSpec = {
+  name: "kb_find_gaps",
+  cliName: "find-gaps",
+  description:
+    "Run bulk missing/present relationship analysis over KB entities. Use for questions like which requirements lack scenarios or tests. No mutation side effects.",
+  businessInputSchema: {
+    type: "object",
+    properties: {
+      type: {
+        type: "string",
+        enum: ENTITY_TYPES,
+      },
+      missingRelationships: { type: "array", items: { type: "string" } },
+      presentRelationships: { type: "array", items: { type: "string" } },
+      tags: { type: "array", items: { type: "string" } },
+      sourceFile: { type: "string" },
+      limit: { type: "integer", default: 100 },
+      offset: { type: "integer", default: 0 },
+    },
+  },
+  requiresProlog: true,
+  effects: ["kb-read"],
+  execute: executeFindGaps,
+} as const satisfies OperationSpec<FindGapsInput, FindGapsPayload>;
+
+export async function executeCoverage(
+  input: CoverageInput,
+  context: OperationContext,
+): Promise<OperationResult<CoveragePayload>> {
+  try {
+    const payload = await runOperationJsonQuery<CoveragePayload>(
+      requireProlog(context),
+      "discovery.pl",
+      `discovery:coverage_report_json('${input.by ?? "req"}', ${toPrologList(input.tags)}, ${input.includePassing ?? false}, ${input.includeTransitive ?? true}, ${input.limit ?? 100}, ${input.offset ?? 0}, JsonString)`,
+      "Coverage execution",
+    );
+    const fullyCovered = Number(payload.summary?.fullyCovered ?? 0);
+    const total = Number(payload.summary?.total ?? 0);
+    return {
+      content: [
+        {
+          type: "text",
+          text: `Coverage summary: ${fullyCovered} fully covered out of ${total}.`,
+        },
+      ],
+      structuredContent: payload,
+    };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(`Coverage execution failed: ${message}`);
+  }
+}
+
+export const coverageSpec = {
+  name: "kb_coverage",
+  cliName: "coverage",
+  description:
+    "Generate curated coverage reports for requirements, symbols, or grouped types. Read-only reporting with no mutation side effects.",
+  businessInputSchema: {
+    type: "object",
+    properties: {
+      by: { type: "string", enum: ["req", "symbol", "type"], default: "req" },
+      tags: { type: "array", items: { type: "string" } },
+      includePassing: { type: "boolean", default: false },
+      includeTransitive: { type: "boolean", default: true },
+      limit: { type: "integer", default: 100 },
+      offset: { type: "integer", default: 0 },
+    },
+  },
+  requiresProlog: true,
+  effects: ["kb-read"],
+  execute: executeCoverage,
+} as const satisfies OperationSpec<CoverageInput, CoveragePayload>;
+
+export async function executeGraph(
+  input: GraphInput,
+  context: OperationContext,
+): Promise<OperationResult<GraphPayload>> {
+  const depth = input.depth ?? 1;
+  if (depth < 1 || depth > 5) {
+    throw new RangeError("Graph depth must be between 1 and 5");
+  }
+  try {
+    const payload = await runOperationJsonQuery<GraphPayload>(
+      requireProlog(context),
+      "discovery.pl",
+      `discovery:graph_expand_json(${toPrologList(input.seedIds)}, ${toPrologList(input.relationships)}, '${input.direction ?? "outgoing"}', ${depth}, ${toPrologList(input.entityTypes)}, ${input.maxNodes ?? 200}, ${input.maxEdges ?? 500}, JsonString)`,
+      "Graph execution",
+    );
+    const nodes = payload.nodes ?? [];
+    const edges = payload.edges ?? [];
+    return {
+      content: [
+        {
+          type: "text",
+          text:
+            nodes.length === 0
+              ? "Graph traversal returned no nodes."
+              : `Graph traversal returned ${nodes.length} nodes and ${edges.length} edges from ${input.seedIds.join(", ")}.`,
+        },
+      ],
+      structuredContent: payload,
+    };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(`Graph execution failed: ${message}`);
+  }
+}
+
+export const graphSpec = {
+  name: "kb_graph",
+  cliName: "graph",
+  description:
+    "Run bounded graph traversal from one or more seed IDs across curated relationship types. No mutation side effects.",
+  businessInputSchema: {
+    type: "object",
+    required: ["seedIds"],
+    properties: {
+      seedIds: { type: "array", items: { type: "string" } },
+      relationships: { type: "array", items: { type: "string" } },
+      direction: {
+        type: "string",
+        enum: ["outgoing", "incoming", "both"],
+        default: "outgoing",
+      },
+      depth: { type: "integer", default: 1, minimum: 1, maximum: 5 },
+      entityTypes: { type: "array", items: { type: "string" } },
+      maxNodes: { type: "integer", default: 200 },
+      maxEdges: { type: "integer", default: 500 },
+    },
+  },
+  requiresProlog: true,
+  effects: ["kb-read"],
+  execute: executeGraph,
+} as const satisfies OperationSpec<GraphInput, GraphPayload>;

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

@@ -0,0 +1,174 @@
+import { InputError } from "../../../cli-errors.js";
+import { analyzeSemanticAdvisorInput } from "../../../operations/semantic-advisor/analyze-prose.js";
+import type {
+  SemanticAdvisorArgs,
+  SemanticAdvisorOperationResult,
+} from "../../../operations/semantic-advisor/types.js";
+import type { OperationContext } from "../runtime-types.js";
+import type { OperationSpec } from "../types.js";
+
+function requiredText(value: unknown): string {
+  const text = typeof value === "string" ? value.trim() : "";
+  if (!text) {
+    throw new InputError(
+      "VALIDATION_FAILED",
+      "Semantic advisor failed: text must be a non-empty string",
+    );
+  }
+  return text;
+}
+
+function optionalString(value: unknown): string | undefined {
+  const text = typeof value === "string" ? value.trim() : "";
+  return text || undefined;
+}
+
+export async function executeSemanticAdvisor(
+  args: SemanticAdvisorArgs,
+  _context?: OperationContext,
+): Promise<SemanticAdvisorOperationResult> {
+  const text = requiredText(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,
+      },
+    },
+    ...(args.clauses !== undefined ? { clauses: args.clauses } : {}),
+    ...(args.interpretations !== undefined
+      ? { interpretations: args.interpretations }
+      : {}),
+  });
+  return {
+    content: [
+      {
+        type: "text",
+        text: `kb_semantic_advisor: ${result.receipt.summary} Suggestions: ${result.receipt.suggestions.map(({ kind }) => kind).join(", ") || "none"}.`,
+      },
+    ],
+    structuredContent: { receipt: result.receipt, warnings: result.warnings },
+  };
+}
+
+async function executeSemanticAdvisorInput(
+  input: Readonly<Record<string, unknown>>,
+  context: OperationContext,
+): Promise<SemanticAdvisorOperationResult> {
+  const type = optionalString(input.type);
+  const id = optionalString(input.id);
+  const title = optionalString(input.title);
+  const source = optionalString(input.source);
+  const status = optionalString(input.status);
+  const clauses = Array.isArray(input.clauses)
+    ? input.clauses.filter(
+        (value): value is string => typeof value === "string",
+      )
+    : undefined;
+  const interpretations = Array.isArray(input.interpretations)
+    ? input.interpretations.filter(
+        (
+          value,
+        ): value is NonNullable<
+          SemanticAdvisorArgs["interpretations"]
+        >[number] => typeof value === "object" && value !== null,
+      )
+    : undefined;
+  return executeSemanticAdvisor(
+    {
+      text: requiredText(input.text),
+      ...(type ? { type } : {}),
+      ...(id ? { id } : {}),
+      ...(title ? { title } : {}),
+      ...(source ? { source } : {}),
+      ...(status ? { status } : {}),
+      ...(clauses !== undefined ? { clauses } : {}),
+      ...(interpretations !== undefined ? { interpretations } : {}),
+    },
+    context,
+  );
+}
+
+export const semanticAdvisorSpec = {
+  name: "kb_semantic_advisor",
+  cliName: "semantic-advisor",
+  description:
+    "Analyze requirement prose without mutating the KB and return semantic advisor receipts with modeling suggestions. Use before constructing kb_upsert payloads when prose may contain machine-checkable logic. Suggestions can include strict-property facts, predicate facts, ambiguity observations, or ontology-gap observations; all suggestions are advisory and reviewable.",
+  businessInputSchema: {
+    type: "object",
+    required: ["text"],
+    properties: {
+      text: {
+        type: "string",
+        description:
+          "Requirement prose to inspect for machine-checkable modeling suggestions.",
+      },
+      clauses: {
+        type: "array",
+        items: { type: "string" },
+        description:
+          "Optional complete list of atomic requirement clauses supplied by the caller. Use this for compound prose so every normative clause receives a stable claim key and independent grounding review.",
+      },
+      interpretations: {
+        type: "array",
+        maxItems: 3,
+        description:
+          "Optional host-LLM typed kibi.logic.v1 interpretations. Kibi validates and canonicalizes them; raw Prolog is not accepted.",
+        items: {
+          type: "object",
+          required: ["claim_key", "claim_text", "ir"],
+          properties: {
+            claim_key: { type: "string" },
+            claim_text: { type: "string" },
+            confidence: { type: "number", minimum: 0, maximum: 1 },
+            span: { type: "object" },
+            ir: { type: "object" },
+          },
+        },
+      },
+      type: {
+        type: "string",
+        enum: [
+          "req",
+          "scenario",
+          "test",
+          "adr",
+          "flag",
+          "event",
+          "symbol",
+          "fact",
+        ],
+        default: "req",
+        description:
+          "Entity type context for analysis. Requirement, domain-fact, and supporting prose all receive a proposition ledger; only requirements receive deterministic modeling suggestions.",
+      },
+      id: {
+        type: "string",
+        description:
+          "Optional requirement ID used for deterministic draft relationship guidance.",
+      },
+      title: {
+        type: "string",
+        description: "Optional requirement title for draft apply plans.",
+      },
+      source: {
+        type: "string",
+        description: "Optional provenance for draft suggestions.",
+      },
+      status: {
+        type: "string",
+        description: "Optional requirement status for draft suggestions.",
+      },
+    },
+  },
+  requiresProlog: false,
+  effects: ["local-read"],
+  execute: executeSemanticAdvisorInput,
+} as const satisfies OperationSpec;

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

@@ -0,0 +1,142 @@
+import { createHash } from "node:crypto";
+import {
+  type SkillManifest,
+  listBundledSkills,
+  loadBundledSkill,
+  readBundledSkillResource,
+} from "../../skills.js";
+import type { OperationContext } from "../runtime-types.js";
+import type { OperationResult, OperationSpec } from "../types.js";
+
+function assertNonEmptyString(value: string, field: string): void {
+  if (typeof value !== "string" || value.trim() === "") {
+    throw new Error(`${field} must be a non-empty string`);
+  }
+}
+
+async function executeSkillsList(
+  _input: Readonly<Record<string, unknown>>,
+  _context: OperationContext,
+): Promise<OperationResult<{ readonly skills: readonly SkillManifest[] }>> {
+  const skills = listBundledSkills();
+  const ids = skills.map((skill) => skill.id).join(", ") || "none";
+  return {
+    content: [
+      { type: "text", text: `Found ${skills.length} bundled skills: ${ids}` },
+    ],
+    structuredContent: { skills },
+  };
+}
+
+async function executeSkillsLoad(
+  input: Readonly<Record<string, unknown>>,
+  _context: OperationContext,
+): Promise<
+  OperationResult<{
+    readonly metadata: SkillManifest;
+    readonly body: string;
+    readonly resources: readonly string[];
+    readonly contentHash: string;
+    readonly sourceType: "bundled";
+  }>
+> {
+  const id = typeof input.id === "string" ? input.id : "";
+  assertNonEmptyString(id, "id");
+  const bundle = loadBundledSkill(id);
+  const resources = bundle.manifest.resources ?? [];
+  const contentHash = createHash("sha256")
+    .update(bundle.body, "utf8")
+    .digest("hex");
+  const resourceList = resources.length === 0 ? "none" : resources.join(", ");
+  return {
+    content: [
+      {
+        type: "text",
+        text: `Loaded bundled skill ${bundle.manifest.id} with ${resources.length} resources: ${resourceList}`,
+      },
+    ],
+    structuredContent: {
+      metadata: bundle.manifest,
+      body: bundle.body,
+      resources,
+      contentHash,
+      sourceType: "bundled",
+    },
+  };
+}
+
+async function executeSkillsRead(
+  input: Readonly<Record<string, unknown>>,
+  _context: OperationContext,
+): Promise<OperationResult<{ readonly content: string }>> {
+  const id = typeof input.id === "string" ? input.id : "";
+  const resource = typeof input.resource === "string" ? input.resource : "";
+  assertNonEmptyString(id, "id");
+  assertNonEmptyString(resource, "resource");
+  const resourceContent = readBundledSkillResource(id, resource);
+  return {
+    content: [
+      {
+        type: "text",
+        text: `Read bundled skill resource ${id}/${resource}`,
+      },
+    ],
+    structuredContent: { content: resourceContent },
+  };
+}
+
+export const skillsListSpec = {
+  name: "kb_skills_list",
+  cliName: "skills list",
+  description:
+    "List bundled Kibi agent skills available for progressive disclosure. Read-only; does not mutate the KB or require Prolog.",
+  businessInputSchema: { type: "object", properties: {} },
+  requiresProlog: false,
+  effects: ["local-read"],
+  execute: executeSkillsList,
+} as const satisfies OperationSpec;
+
+export const skillsLoadSpec = {
+  name: "kb_skills_load",
+  cliName: "skills load",
+  description:
+    "Load a bundled Kibi agent skill by ID, returning its manifest metadata, Markdown body, declared resources, content hash, and source type. Read-only; does not execute scripts or require Prolog.",
+  businessInputSchema: {
+    type: "object",
+    required: ["id"],
+    properties: {
+      id: {
+        type: "string",
+        description: "Bundled skill ID to load. Example: 'kibi-usage'.",
+      },
+    },
+  },
+  requiresProlog: false,
+  effects: ["local-read"],
+  execute: executeSkillsLoad,
+} as const satisfies OperationSpec;
+
+export const skillsReadSpec = {
+  name: "kb_skills_read",
+  cliName: "skills read",
+  description:
+    "Read a declared resource from a bundled Kibi agent skill. Resource paths are restricted to the skill manifest; arbitrary file paths are not exposed. Read-only; does not require Prolog.",
+  businessInputSchema: {
+    type: "object",
+    required: ["id", "resource"],
+    properties: {
+      id: {
+        type: "string",
+        description: "Bundled skill ID. Example: 'kibi-usage'.",
+      },
+      resource: {
+        type: "string",
+        description:
+          "Manifest-declared resource path to read. Example: 'resources/workflows.md'.",
+      },
+    },
+  },
+  requiresProlog: false,
+  effects: ["local-read"],
+  execute: executeSkillsRead,
+} as const satisfies OperationSpec;