kibi-cli 0.14.0 → 0.16.1

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,135 @@
+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 } : {}),
+  });
+  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;
+  return executeSemanticAdvisor(
+    {
+      text: requiredText(input.text),
+      ...(type ? { type } : {}),
+      ...(id ? { id } : {}),
+      ...(title ? { title } : {}),
+      ...(source ? { source } : {}),
+      ...(status ? { status } : {}),
+      ...(clauses !== undefined ? { clauses } : {}),
+    },
+    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.",
+      },
+      type: {
+        type: "string",
+        enum: ["req"],
+        default: "req",
+        description:
+          "Entity type context for analysis. Currently requirement prose is supported.",
+      },
+      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;

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

@@ -0,0 +1,149 @@
+import type { OperationContext } from "../runtime-types.js";
+import type { OperationResult, OperationSpec } from "../types.js";
+
+// implements REQ-kibi-operation-interface-parity
+export type SparqlRemoteInput = {
+  readonly endpoint: string;
+  readonly query: string;
+  readonly timeoutMs?: number;
+};
+
+// implements REQ-kibi-operation-interface-parity
+export type SparqlRemoteOutput = {
+  readonly rows: readonly Readonly<Record<string, unknown>>[];
+};
+
+function validateInput(input: SparqlRemoteInput): URL {
+  if (typeof input.endpoint !== "string" || input.endpoint.trim() === "") {
+    throw new Error("SPARQL endpoint is required");
+  }
+  if (typeof input.query !== "string" || input.query.trim() === "") {
+    throw new Error("SPARQL query is required");
+  }
+  let endpoint: URL;
+  try {
+    endpoint = new URL(input.endpoint);
+  } catch {
+    throw new Error("SPARQL endpoint must be an http:// or https:// URL");
+  }
+  if (endpoint.protocol !== "http:" && endpoint.protocol !== "https:") {
+    throw new Error("SPARQL endpoint must be an http:// or https:// URL");
+  }
+  if (!/^\s*select\b/i.test(input.query)) {
+    throw new Error("SPARQL query must be a SELECT query");
+  }
+  if (
+    input.timeoutMs !== undefined &&
+    (!Number.isFinite(input.timeoutMs) || input.timeoutMs <= 0)
+  ) {
+    throw new Error("SPARQL timeoutMs must be a positive number when provided");
+  }
+  return endpoint;
+}
+
+function isRecord(value: unknown): value is Readonly<Record<string, unknown>> {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function decodeRows(payload: unknown): SparqlRemoteOutput {
+  if (!isRecord(payload) || !isRecord(payload.results)) {
+    throw new Error("SPARQL endpoint returned an invalid result document");
+  }
+  const bindings = payload.results.bindings;
+  if (!Array.isArray(bindings)) {
+    throw new Error("SPARQL endpoint returned an invalid bindings array");
+  }
+  const rows = bindings.map((binding) => {
+    if (!isRecord(binding)) {
+      throw new Error("SPARQL endpoint returned an invalid binding");
+    }
+    const row: Record<string, unknown> = {};
+    for (const [variable, term] of Object.entries(binding)) {
+      if (!isRecord(term) || typeof term.value !== "string") {
+        throw new Error(`SPARQL endpoint returned an invalid ${variable} term`);
+      }
+      row[variable] = term.value;
+    }
+    return row;
+  });
+  return { rows };
+}
+
+// implements REQ-kibi-operation-interface-parity, REQ-002, REQ-013
+async function executeSparqlRemote(
+  input: SparqlRemoteInput,
+  context: OperationContext,
+): Promise<OperationResult<SparqlRemoteOutput>> {
+  const endpoint = validateInput(input);
+  if (context.net === undefined) {
+    throw new Error("SPARQL remote query requires a network port");
+  }
+  const signal =
+    input.timeoutMs === undefined
+      ? context.signal
+      : AbortSignal.any([
+          context.signal,
+          AbortSignal.timeout(
+            Math.max(1, Math.ceil(input.timeoutMs / 1_000)) * 1_000,
+          ),
+        ]);
+  try {
+    const response = await context.net.fetch(endpoint, {
+      method: "POST",
+      headers: {
+        accept: "application/sparql-results+json",
+        "content-type": "application/x-www-form-urlencoded;charset=UTF-8",
+      },
+      body: new URLSearchParams({ query: input.query }),
+      signal,
+    });
+    if (!response.ok) {
+      throw new Error(`SPARQL endpoint returned HTTP ${response.status}`);
+    }
+    const payload: unknown = await response.json();
+    const structuredContent = decodeRows(payload);
+    const rowCount = structuredContent.rows.length;
+    return {
+      content: [
+        {
+          type: "text",
+          text: `Remote SPARQL query returned ${rowCount} row${rowCount === 1 ? "" : "s"}.`,
+        },
+      ],
+      structuredContent,
+    };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(`SPARQL remote query failed: ${message}`);
+  }
+}
+
+export const sparqlRemoteSpec = {
+  name: "kb_sparql_remote",
+  cliName: "sparql-remote",
+  description:
+    "Opt-in remote SPARQL query tool for external HTTP(S) RDF endpoints. This does not query Kibi's local RDF store directly, stores no credentials, and depends on network availability.",
+  businessInputSchema: {
+    type: "object",
+    required: ["endpoint", "query"],
+    properties: {
+      endpoint: {
+        type: "string",
+        description:
+          "Remote SPARQL endpoint URL. Must start with http:// or https://.",
+      },
+      query: {
+        type: "string",
+        description: "SPARQL SELECT query to send to the remote endpoint.",
+      },
+      timeoutMs: {
+        type: "number",
+        description:
+          "Optional positive timeout in milliseconds for the remote query.",
+      },
+    },
+  },
+  requiresProlog: false,
+  effects: ["network-read"],
+  execute: executeSparqlRemote,
+} as const satisfies OperationSpec<SparqlRemoteInput, SparqlRemoteOutput>;