kibi-cli 0.10.1 → 0.11.1

package/src/public/skills/kibi-usage/resources/relationship-directions.md

@@ -0,0 +1,89 @@
+# Relationship Directions
+
+## Direction Table
+
+| Relationship | Source -> Target | Semantic Meaning |
+|-------------|------------------|------------------|
+| `implements` | symbol -> req | Production code symbol owns or implements requirement behavior |
+| `specified_by` | req -> scenario | Requirement is specified by a BDD scenario |
+| `verified_by` | req/scenario -> test | Requirement or scenario is verified by a test case |
+| `validates` | test -> req/scenario | Test validates a requirement or scenario (inverse of verified_by) |
+| `executable_for` | symbol -> test | Test symbol (code) is executable code for a test entity |
+| `constrains` | req -> fact(subject) | Requirement constrains a strict-lane domain fact |
+| `requires_property` | req -> fact(property_value) | Requirement requires a specific property value fact |
+| `supersedes` | old-req -> new-req | Old requirement is formally replaced by a new requirement |
+| `covered_by` | symbol -> test | Production symbol has test coverage evidence |
+
+## Valid Payload Examples
+
+### implements
+```yaml
+relationships:
+  - type: implements
+    from: SYM-001
+    to: REQ-001
+```
+
+### specified_by
+```yaml
+relationships:
+  - type: specified_by
+    from: REQ-001
+    to: SCEN-001
+```
+
+### verified_by
+```yaml
+relationships:
+  - type: verified_by
+    from: REQ-001
+    to: TEST-001
+```
+
+### validates
+```yaml
+relationships:
+  - type: validates
+    from: TEST-001
+    to: SCEN-001
+```
+
+### executable_for
+```yaml
+relationships:
+  - type: executable_for
+    from: SYM-test-login
+    to: TEST-001
+```
+
+### constrains
+```yaml
+relationships:
+  - type: constrains
+    from: REQ-019
+    to: FACT-USER-ROLE
+```
+
+### requires_property
+```yaml
+relationships:
+  - type: requires_property
+    from: REQ-019
+    to: FACT-LIMIT-3
+```
+
+### supersedes
+```yaml
+relationships:
+  - type: supersedes
+    from: REQ-001
+    to: REQ-001-v2
+```
+
+### covered_by
+```yaml
+relationships:
+  - type: covered_by
+    from: SYM-handler
+    to: TEST-005
+```

package/src/public/skills/kibi-usage/resources/workflows.md

@@ -0,0 +1,35 @@
+# Workflows
+
+## Discovery to Validation Sequence
+
+The canonical workflow for any KB operation follows this pattern:
+
+1. **Discover**: `kb_search` with focused probes
+2. **Confirm**: `kb_query` for exact IDs and state
+3. **Inspect**: `kb_status` when freshness matters
+4. **Create endpoints**: `kb_upsert` for new entities (sequential)
+5. **Link**: `kb_upsert` with relationship rows (sequential)
+6. **Validate**: `kb_check` with targeted rules during work, full check at completion
+
+## Creating a New Feature
+```
+1. kb_search to discover existing requirements and related knowledge
+2. kb_query to confirm exact IDs and source-linked context
+3. kb_upsert for new or updated requirements (include relationship rows)
+4. kb_check with targeted rules
+```
+
+## Fixing a Traceability Gap
+```
+1. kb_query --sourceFile <code-file> to find linked entities
+2. kb_find_gaps --type req --missing-rel specified_by to find orphan requirements
+3. kb_upsert to add missing relationship rows (sequential)
+4. kb_check with rules: ["no-dangling-refs", "symbol-traceability"]
+```
+
+## Before Risky Work
+```
+1. /brief-kibi or kb_briefing_generate for citation-backed briefing
+2. Inspect briefingState; proceed only if ready
+3. Use constraints, regressionRisks, and cited entities from the briefing
+```

package/src/public/skills.ts

@@ -0,0 +1,359 @@
+import {
+  existsSync,
+  readFileSync,
+  readdirSync,
+  realpathSync,
+  statSync,
+} from "node:fs";
+import {
+  dirname,
+  isAbsolute,
+  join,
+  normalize,
+  relative,
+  resolve,
+} from "node:path";
+import { fileURLToPath } from "node:url";
+import matter from "gray-matter";
+
+const SKILL_MARKDOWN_MAX_BYTES = 256 * 1024;
+const RESOURCE_MAX_BYTES = 128 * 1024;
+const SKILL_FILE_NAME = "SKILL.md";
+
+const moduleDir = dirname(fileURLToPath(import.meta.url));
+let bundledSkillsDir = resolve(moduleDir, "skills");
+const defaultBundledSkillsDir = bundledSkillsDir;
+
+export function setBundledSkillsDir(dir: string): void {
+  bundledSkillsDir = dir;
+}
+
+export function resetBundledSkillsDir(): void {
+  bundledSkillsDir = defaultBundledSkillsDir;
+}
+
+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;
+}
+
+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;
+  }
+}
+
+export function listBundledSkills(): SkillManifest[] { // implements REQ-001
+  if (!existsSync(bundledSkillsDir)) {
+    return [];
+  }
+
+  return readdirSync(bundledSkillsDir, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => join(bundledSkillsDir, entry.name))
+    .filter((rootDir) => existsSync(join(rootDir, SKILL_FILE_NAME)))
+    .map((rootDir) => parseSkillBundle(rootDir).manifest)
+    .sort((left, right) => left.id.localeCompare(right.id));
+}
+
+export function loadBundledSkill(id: string): SkillBundle { // implements REQ-001
+  const rootDir = findBundledSkillRoot(id);
+  if (!rootDir) {
+    throw new SkillNotFoundError(id);
+  }
+
+  return parseSkillBundle(rootDir);
+}
+
+export function readBundledSkillResource(
+  id: string,
+  resourcePath: string,
+): string { // implements REQ-001
+  const bundle = loadBundledSkill(id);
+  const declaredResource = normalizeResourcePath(resourcePath);
+
+  if (!declaredResource || isPathOutOfBounds(resourcePath)) {
+    throw new SkillResourceOutOfBoundsError(id, resourcePath);
+  }
+
+  if (!isDeclaredResource(bundle.manifest, declaredResource)) {
+    throw new SkillResourceNotFoundError(id, resourcePath);
+  }
+
+  const candidatePath = resolve(bundle.rootDir, declaredResource);
+  let realResourcePath: string;
+  let realRootDir: string;
+  try {
+    realResourcePath = realpathSync(candidatePath);
+    realRootDir = realpathSync(bundle.rootDir);
+  } catch {
+    throw new SkillResourceNotFoundError(id, resourcePath);
+  }
+
+  if (!isWithinRoot(realRootDir, realResourcePath)) {
+    throw new SkillResourceOutOfBoundsError(id, resourcePath);
+  }
+
+  assertMaxBytes(candidatePath, RESOURCE_MAX_BYTES);
+  return readFileSync(candidatePath, "utf8");
+}
+
+export function validateSkillBundle(
+  pathLike: string,
+): { valid: boolean; errors: SkillValidationError[] } { // implements REQ-001
+  const skillFilePath = resolveSkillFilePath(pathLike);
+  const errors: SkillValidationError[] = [];
+
+  if (!existsSync(skillFilePath)) {
+    errors.push(new SkillValidationError("SKILL.md", `Missing ${SKILL_FILE_NAME}`));
+    return { valid: false, errors };
+  }
+
+  const parsed = matter(readFileSync(skillFilePath, "utf8"));
+  errors.push(...validateManifestData(parsed.data));
+
+  if (errors.length === 0) {
+    validateBundleContents(skillFilePath, coerceManifest(parsed.data), errors);
+  }
+
+  return { valid: errors.length === 0, errors };
+}
+
+function validateBundleContents(
+  skillFilePath: string,
+  manifest: SkillManifest,
+  errors: SkillValidationError[],
+): void {
+  try {
+    assertMaxBytes(skillFilePath, SKILL_MARKDOWN_MAX_BYTES);
+  } catch (error) {
+    errors.push(new SkillValidationError("SKILL.md", error instanceof Error ? error.message : String(error)));
+  }
+
+  const rootDir = dirname(skillFilePath);
+  let realRootDir: string;
+  try {
+    realRootDir = realpathSync(rootDir);
+  } catch (error) {
+    errors.push(new SkillValidationError("SKILL.md", error instanceof Error ? error.message : String(error)));
+    return;
+  }
+
+  for (const resource of manifest.resources ?? []) {
+    const resourcePath = resolve(rootDir, resource);
+    try {
+      if (!existsSync(resourcePath)) {
+        errors.push(new SkillValidationError("resources", `Missing skill resource: ${resource}`));
+        continue;
+      }
+
+      const realResourcePath = realpathSync(resourcePath);
+      if (!isWithinRoot(realRootDir, realResourcePath)) {
+        errors.push(new SkillValidationError("resources", `Skill resource escapes bundle root: ${resource}`));
+        continue;
+      }
+
+      assertMaxBytes(resourcePath, RESOURCE_MAX_BYTES);
+    } catch (error) {
+      errors.push(new SkillValidationError("resources", error instanceof Error ? error.message : String(error)));
+    }
+  }
+}
+
+function findBundledSkillRoot(id: string): string | undefined {
+  if (!existsSync(bundledSkillsDir)) {
+    return undefined;
+  }
+
+  for (const entry of readdirSync(bundledSkillsDir, { withFileTypes: true })) {
+    if (!entry.isDirectory()) {
+      continue;
+    }
+
+    const rootDir = join(bundledSkillsDir, entry.name);
+    const skillFilePath = join(rootDir, SKILL_FILE_NAME);
+    if (!existsSync(skillFilePath)) {
+      continue;
+    }
+
+    const manifest = parseSkillBundle(rootDir).manifest;
+    if (manifest.id === id) {
+      return rootDir;
+    }
+  }
+
+  return undefined;
+}
+
+function parseSkillBundle(rootDir: string): SkillBundle {
+  const skillFilePath = join(rootDir, SKILL_FILE_NAME);
+  assertMaxBytes(skillFilePath, SKILL_MARKDOWN_MAX_BYTES);
+
+  const parsed = matter(readFileSync(skillFilePath, "utf8"));
+  const errors = validateManifestData(parsed.data);
+  if (errors.length > 0) {
+    throw errors[0] as SkillValidationError;
+  }
+
+  return {
+    manifest: coerceManifest(parsed.data),
+    body: parsed.content,
+    rootDir: resolve(rootDir),
+  };
+}
+
+function validateManifestData(data: Record<string, unknown>): SkillValidationError[] {
+  const errors: SkillValidationError[] = [];
+  const requiredFields = [
+    "id",
+    "name",
+    "description",
+    "version",
+    "kibiCompatibility",
+  ] as const;
+
+  for (const field of requiredFields) {
+    if (typeof data[field] !== "string" || data[field].trim() === "") {
+      errors.push(new SkillValidationError(field, `Missing required skill field: ${field}`));
+    }
+  }
+
+  if (typeof data.version === "string" && !/^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/.test(data.version)) {
+    errors.push(new SkillValidationError("version", `Invalid skill version: ${data.version}`));
+  }
+
+  if (data.tags !== undefined && !isStringArray(data.tags)) {
+    errors.push(new SkillValidationError("tags", "Skill tags must be strings"));
+  }
+
+  if (data.resources !== undefined) {
+    if (!isStringArray(data.resources)) {
+      errors.push(new SkillValidationError("resources", "Skill resources must be strings"));
+    } else {
+      for (const resource of data.resources) {
+        const normalized = normalizeResourcePath(resource);
+        if (!normalized || isPathOutOfBounds(resource)) {
+          errors.push(
+            new SkillValidationError("resources", `Invalid skill resource: ${resource}`),
+          );
+        }
+      }
+    }
+  }
+
+  return errors;
+}
+
+function coerceManifest(data: Record<string, unknown>): SkillManifest {
+  const manifest: SkillManifest = {
+    id: String(data.id),
+    name: String(data.name),
+    description: String(data.description),
+    version: String(data.version),
+    kibiCompatibility: String(data.kibiCompatibility),
+  };
+
+  if (isStringArray(data.tags)) {
+    manifest.tags = data.tags;
+  }
+
+  if (isStringArray(data.resources)) {
+    manifest.resources = data.resources.map((resource) => normalizeResourcePath(resource));
+  }
+
+  return manifest;
+}
+
+function isStringArray(value: unknown): value is string[] {
+  return Array.isArray(value) && value.every((item) => typeof item === "string");
+}
+
+function normalizeResourcePath(pathLike: string): string {
+  return normalize(pathLike).replaceAll("\\", "/");
+}
+
+function isPathOutOfBounds(pathLike: string): boolean {
+  const normalized = normalizeResourcePath(pathLike);
+  return (
+    isAbsolute(pathLike) ||
+    normalized === ".." ||
+    normalized.startsWith("../") ||
+    normalized.includes("/../")
+  );
+}
+
+function isDeclaredResource(manifest: SkillManifest, resourcePath: string): boolean {
+  return (manifest.resources ?? []).some(
+    (declared) => normalizeResourcePath(declared) === resourcePath,
+  );
+}
+
+function isWithinRoot(rootDir: string, candidatePath: string): boolean {
+  const relativePath = relative(rootDir, candidatePath);
+  return relativePath === "" || (!relativePath.startsWith("..") && !isAbsolute(relativePath));
+}
+
+function assertMaxBytes(pathLike: string, maxBytes: number): void {
+  const size = statSync(pathLike).size;
+  if (size > maxBytes) {
+    throw new SkillOversizeError(pathLike, maxBytes, size);
+  }
+}
+
+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);
+}
+