kibi-cli 0.12.8 → 0.16.1

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

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

@@ -0,0 +1,40 @@
+import type {
+  UpsertInput,
+  UpsertPayload,
+} from "../../../operations/mutation/types.js";
+import { executeUpsert } from "../../../operations/mutation/upsert.js";
+import type { OperationSpec } from "../types.js";
+import {
+  ENTITY_PROPERTIES_SCHEMA,
+  ENTITY_TYPES,
+  RELATIONSHIPS_SCHEMA,
+} from "./mutation-schemas.js";
+
+export const upsertSpec = {
+  name: "kb_upsert",
+  cliName: "upsert",
+  description:
+    "Create or update one entity and optional relationships. Use for KB mutations after validating intent; prefer kb_validate_upsert first because it returns semantic advisor receipts for prose-heavy requirements. Use kb_model_requirement before hand-writing strict property facts from prose, and kb_suggest_predicates before hand-writing ontology predicate facts. Use the `relationships` array for batch creation of multiple links in a single call (e.g., linking a requirement to multiple tests or facts). Prefer modeling requirements as reusable fact links (`constrains`, `requires_property`, or `requires_predicate`) so consistency and contradiction checks remain queryable. Relationship endpoints must already exist in KB. For requirements, the write will be rejected if it contradicts existing current requirements that constrain the same subject with incompatible properties. To replace a conflicting requirement, include a `supersedes` relationship from the new requirement to the old one in the same request. Successful writes may return non-blocking semantic advisor warnings; inspect and repair those warnings before treating prose as contradiction-checkable. Do not use for read-only inspection. Side effects: writes KB, may refresh symbol coordinates.",
+  businessInputSchema: {
+    type: "object",
+    required: ["type", "id", "properties"],
+    properties: {
+      type: {
+        type: "string",
+        enum: ENTITY_TYPES,
+        description:
+          "Entity type to create/update. Allowed: req, scenario, test, adr, flag, event, symbol, fact. Example: 'req'.",
+      },
+      id: {
+        type: "string",
+        description:
+          "Unique entity ID (string). Example: 'REQ-123'. Existing ID updates the entity; new ID creates it.",
+      },
+      properties: ENTITY_PROPERTIES_SCHEMA,
+      relationships: RELATIONSHIPS_SCHEMA,
+    },
+  },
+  requiresProlog: true,
+  effects: ["kb-write", "workspace-write"],
+  execute: executeUpsert,
+} as const satisfies OperationSpec<UpsertInput, UpsertPayload>;

package/src/public/operations/types.ts

@@ -0,0 +1,57 @@
+import type { OperationContext } from "./runtime-types.js";
+export type { OperationContext };
+export type OperationName =
+  | "kb_query"
+  | "kb_search"
+  | "kb_status"
+  | "kb_skills_list"
+  | "kb_skills_load"
+  | "kb_skills_read"
+  | "kb_find_gaps"
+  | "kb_coverage"
+  | "kb_graph"
+  | "kb_sparql_remote"
+  | "kb_semantic_advisor"
+  | "kb_upsert"
+  | "kb_validate_upsert"
+  | "kb_delete"
+  | "kb_check"
+  | "kb_model_requirement"
+  | "kb_suggest_predicates"
+  | "kb_autopilot_generate";
+
+export type OperationEffect =
+  | "local-read"
+  | "kb-read"
+  | "workspace-read"
+  | "network-read"
+  | "kb-write"
+  | "workspace-write";
+
+export interface OperationContent {
+  readonly type: string;
+  readonly text?: string;
+}
+
+export interface OperationResult<O = unknown> {
+  readonly content: readonly OperationContent[];
+  readonly structuredContent?: O;
+}
+
+export interface OperationSpec<
+  I = Readonly<Record<string, unknown>>,
+  O = unknown,
+> {
+  readonly name: OperationName;
+  readonly cliName: string;
+  readonly description: string;
+  readonly businessInputSchema: Readonly<Record<string, unknown>>;
+  readonly requiresProlog: boolean;
+  readonly effects: readonly OperationEffect[];
+  readonly execute: {
+    bivarianceHack(
+      input: I,
+      context: OperationContext,
+    ): Promise<OperationResult<O>>;
+  }["bivarianceHack"];
+}

package/src/public/schemas/entity.ts

@@ -29,8 +29,19 @@ type FactKind =
 type Operator = "eq" | "neq" | "lt" | "lte" | "gt" | "gte";
 type ValueType = "string" | "int" | "number" | "bool";
 type Polarity = "require" | "forbid" | "assert" | "deny";
+type VerificationScope = "unit" | "integration" | "end_to_end";
+type VerificationPerspective = "internal" | "consumer";
 
 const factConditionals = JSON.parse(`[
+  {
+    "if": {
+      "anyOf": [
+        { "required": ["claim_key"] },
+        { "required": ["claim_text"] }
+      ]
+    },
+    "then": { "required": ["claim_key", "claim_text"] }
+  },
   {
     "if": {
       "properties": {
@@ -119,6 +130,12 @@ const entitySchema: Record<string, unknown> = {
     severity: { type: "string" },
     links: { type: "array", items: { type: "string" } },
     text_ref: { type: "string" },
+    logic_claims: {
+      type: "array",
+      minItems: 1,
+      uniqueItems: true,
+      items: { type: "string", pattern: "^CLAIM-[A-F0-9]{16}$" },
+    },
     sourceFile: { type: "string" },
     granularity_reason: {
       type: "string",
@@ -133,6 +150,14 @@ const entitySchema: Record<string, unknown> = {
       type: "string",
       enum: [...SYMBOL_ROLES] satisfies SymbolRole[],
     },
+    verification_scope: {
+      type: "string",
+      enum: ["unit", "integration", "end_to_end"] satisfies VerificationScope[],
+    },
+    verification_perspective: {
+      type: "string",
+      enum: ["internal", "consumer"] satisfies VerificationPerspective[],
+    },
     type: {
       type: "string",
       enum: [
@@ -176,6 +201,8 @@ const entitySchema: Record<string, unknown> = {
     valid_from: { type: "string" },
     valid_to: { type: "string" },
     canonical_key: { type: "string" },
+    claim_key: { type: "string", pattern: "^CLAIM-[A-F0-9]{16}$" },
+    claim_text: { type: "string" },
     predicate_name: { type: "string" },
     predicate_namespace: { type: "string" },
     predicate_arity: { type: "integer", minimum: 1 },
@@ -196,6 +223,14 @@ const entitySchema: Record<string, unknown> = {
     "type",
   ],
   allOf: [
+    {
+      if: {
+        properties: { type: { const: "req" } },
+      },
+      else: {
+        not: { required: ["logic_claims"] },
+      },
+    },
     // Forbid fact-only fields on non-fact entities
     {
       if: {
@@ -222,6 +257,8 @@ const entitySchema: Record<string, unknown> = {
             { required: ["valid_from"] },
             { required: ["valid_to"] },
             { required: ["canonical_key"] },
+            { required: ["claim_key"] },
+            { required: ["claim_text"] },
             { required: ["predicate_name"] },
             { required: ["predicate_namespace"] },
             { required: ["predicate_arity"] },
@@ -235,6 +272,19 @@ const entitySchema: Record<string, unknown> = {
         },
       },
     },
+    {
+      if: {
+        properties: { type: { const: "test" } },
+      },
+      else: {
+        not: {
+          anyOf: [
+            { required: ["verification_scope"] },
+            { required: ["verification_perspective"] },
+          ],
+        },
+      },
+    },
     ...factConditionals,
   ],
   additionalProperties: false,

package/src/public/skill-system/errors.ts

@@ -0,0 +1,38 @@
+export class SkillNotFoundError extends Error {
+  constructor(id: string) {
+    super(`Skill not found: ${id}`);
+    this.name = "SkillNotFoundError";
+  }
+}
+export class SkillResourceNotFoundError extends Error {
+  constructor(id: string, resourcePath: string) {
+    super(`Skill resource not found: ${id}/${resourcePath}`);
+    this.name = "SkillResourceNotFoundError";
+  }
+}
+export class SkillResourceOutOfBoundsError extends Error {
+  constructor(id: string, resourcePath: string) {
+    super(`Skill resource escapes bundle root: ${id}/${resourcePath}`);
+    this.name = "SkillResourceOutOfBoundsError";
+  }
+}
+export class SkillValidationError extends Error {
+  readonly field: string;
+  constructor(field: string, message: string) {
+    super(message);
+    this.name = "SkillValidationError";
+    this.field = field;
+  }
+}
+export class SkillOversizeError extends Error {
+  readonly maxBytes: number;
+  readonly actualBytes: number;
+  constructor(pathLike: string, maxBytes: number, actualBytes: number) {
+    super(
+      `Skill file exceeds ${maxBytes} bytes: ${pathLike} (${actualBytes} bytes)`,
+    );
+    this.name = "SkillOversizeError";
+    this.maxBytes = maxBytes;
+    this.actualBytes = actualBytes;
+  }
+}

package/src/public/skill-system/loader.ts

@@ -0,0 +1,108 @@
+import { existsSync, readFileSync, readdirSync, realpathSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+  SkillNotFoundError,
+  SkillResourceNotFoundError,
+  SkillResourceOutOfBoundsError,
+} from "./errors.js";
+import {
+  SKILL_FILE_NAME,
+  isPathOutOfBounds,
+  isWithinRoot,
+  normalizeResourcePath,
+} from "./paths.js";
+import type { SkillBundle, SkillManifest } from "./types.js";
+import {
+  RESOURCE_MAX_BYTES,
+  assertMaxBytes,
+  parseSkillBundle,
+} from "./validation.js";
+const defaultBundledSkillsDir = resolve(
+  dirname(fileURLToPath(import.meta.url)),
+  "../skills",
+);
+let bundledSkillsDir = defaultBundledSkillsDir;
+export function setBundledSkillsDir(dir: string): void {
+  bundledSkillsDir = dir;
+}
+export function resetBundledSkillsDir(): void {
+  bundledSkillsDir = defaultBundledSkillsDir;
+}
+export function listBundledSkills(): SkillManifest[] {
+  return listFrom(bundledSkillsDir);
+}
+export function loadBundledSkill(id: string): SkillBundle {
+  return loadBundledSkillFrom(bundledSkillsDir, id);
+}
+// implements REQ-reusable-skill-subsystem
+// covered_by TEST-skill-cli-load-validate
+export function loadBundledSkillFrom(
+  skillsDir: string,
+  id: string,
+): SkillBundle {
+  const root = findRoot(resolve(skillsDir), id);
+  if (!root) throw new SkillNotFoundError(id);
+  return parseSkillBundle(root);
+}
+export function readBundledSkillResource(
+  id: string,
+  resourcePath: string,
+): string {
+  return readBundle(loadBundledSkill(id), id, resourcePath);
+}
+// implements REQ-reusable-skill-subsystem
+// covered_by TEST-skill-cli-load-validate
+export function readBundledSkillResourceFrom(
+  skillsDir: string,
+  id: string,
+  resourcePath: string,
+): string {
+  return readBundle(loadBundledSkillFrom(skillsDir, id), id, resourcePath);
+}
+function listFrom(dir: string): SkillManifest[] {
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => join(dir, entry.name))
+    .filter((root) => existsSync(join(root, SKILL_FILE_NAME)))
+    .map((root) => parseSkillBundle(root).manifest)
+    .sort((a, b) => a.id.localeCompare(b.id));
+}
+function findRoot(dir: string, id: string): string | undefined {
+  return listRoots(dir).find(
+    (root) => parseSkillBundle(root).manifest.id === id,
+  );
+}
+function listRoots(dir: string): string[] {
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => join(dir, entry.name))
+    .filter((root) => existsSync(join(root, SKILL_FILE_NAME)));
+}
+function readBundle(
+  bundle: SkillBundle,
+  id: string,
+  resourcePath: string,
+): string {
+  const resource = normalizeResourcePath(resourcePath);
+  if (!resource || isPathOutOfBounds(resourcePath))
+    throw new SkillResourceOutOfBoundsError(id, resourcePath);
+  if (
+    !(bundle.manifest.resources ?? []).some(
+      (declared) => normalizeResourcePath(declared) === resource,
+    )
+  )
+    throw new SkillResourceNotFoundError(id, resourcePath);
+  const candidate = resolve(bundle.rootDir, resource);
+  try {
+    if (!isWithinRoot(realpathSync(bundle.rootDir), realpathSync(candidate)))
+      throw new SkillResourceOutOfBoundsError(id, resourcePath);
+  } catch (error) {
+    if (error instanceof SkillResourceOutOfBoundsError) throw error;
+    throw new SkillResourceNotFoundError(id, resourcePath);
+  }
+  assertMaxBytes(candidate, RESOURCE_MAX_BYTES);
+  return readFileSync(candidate, "utf8");
+}

package/src/public/skill-system/paths.ts

@@ -0,0 +1,27 @@
+import { existsSync, statSync } from "node:fs";
+import { isAbsolute, join, normalize, relative, resolve } from "node:path";
+export const SKILL_FILE_NAME = "SKILL.md";
+export function normalizeResourcePath(pathLike: string): string {
+  return normalize(pathLike).replaceAll("\\", "/");
+}
+export function isPathOutOfBounds(pathLike: string): boolean {
+  const normalized = normalizeResourcePath(pathLike);
+  return (
+    isAbsolute(pathLike) ||
+    normalized === ".." ||
+    normalized.startsWith("../") ||
+    normalized.includes("/../")
+  );
+}
+export function isWithinRoot(rootDir: string, candidatePath: string): boolean {
+  const rel = relative(rootDir, candidatePath);
+  return rel === "" || (!rel.startsWith("..") && !isAbsolute(rel));
+}
+export function resolveSkillFilePath(pathLike: string): string {
+  const resolved = resolve(pathLike);
+  if (existsSync(resolved) && statSync(resolved).isDirectory())
+    return join(resolved, SKILL_FILE_NAME);
+  return resolved.endsWith(SKILL_FILE_NAME)
+    ? resolved
+    : join(resolved, SKILL_FILE_NAME);
+}

package/src/public/skill-system/types.ts

@@ -0,0 +1,14 @@
+export interface SkillManifest {
+  id: string;
+  name: string;
+  description: string;
+  version: string;
+  kibiCompatibility: string;
+  tags?: string[];
+  resources?: string[];
+}
+export interface SkillBundle {
+  manifest: SkillManifest;
+  body: string;
+  rootDir: string;
+}