ai-developer-skill-os 8.1.10 → 8.2.0

package/tooling/build-registry.js

@@ -0,0 +1,186 @@
+/**
+ * build-registry.js
+ * V8.2 Governed Capability Metadata & Eval Platform
+ * Generates registry/index.yaml (lightweight lookup) and registry/graph.json (O(1) graph & cycle check)
+ * 
+ * Usage: node tooling/build-registry.js
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import yaml from 'js-yaml';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+const SKILLS_DIR = path.join(__dirname, '../.agents/skills');
+const REGISTRY_DIR = path.join(__dirname, '../.agents/registry');
+const INDEX_YAML = path.join(REGISTRY_DIR, 'index.yaml');
+const GRAPH_JSON = path.join(REGISTRY_DIR, 'graph.json');
+
+function parseYamlFile(filePath) {
+  try {
+    const content = fs.readFileSync(filePath, 'utf8');
+    const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+    if (match) {
+      return yaml.load(match[1]);
+    }
+    return yaml.load(content);
+  } catch (e) {
+    console.error(`[WARN] Failed to parse YAML from ${filePath}: ${e.message}`);
+    return null;
+  }
+}
+
+function buildRegistry() {
+  console.log('🔄 Building V8.2 Governed Capability Registry & O(1) Runtime Graph...');
+
+  if (!fs.existsSync(SKILLS_DIR)) {
+    console.error('❌ Skills directory not found:', SKILLS_DIR);
+    process.exit(1);
+  }
+
+  fs.mkdirSync(REGISTRY_DIR, { recursive: true });
+
+  const dirs = fs.readdirSync(SKILLS_DIR).filter(d => 
+    !d.startsWith('_') && fs.statSync(path.join(SKILLS_DIR, d)).isDirectory()
+  );
+
+  const capabilities = {};
+  const adjacency = {};
+  const reverseAdjacency = {};
+
+  for (const dir of dirs) {
+    const capYamlPath = path.join(SKILLS_DIR, dir, 'capability.yaml');
+    const skillMdPath = path.join(SKILLS_DIR, dir, 'SKILL.md');
+    
+    let meta = null;
+    let fromCapabilityYaml = false;
+
+    if (fs.existsSync(capYamlPath)) {
+      meta = parseYamlFile(capYamlPath);
+      fromCapabilityYaml = true;
+    } else if (fs.existsSync(skillMdPath)) {
+      meta = parseYamlFile(skillMdPath);
+    }
+
+    if (!meta) continue;
+
+    const id = meta.id || meta.name || dir;
+    const version = meta.version || '8.2.0';
+    const description = meta.description || '';
+    
+    // Normalize tags
+    let tags = meta.tags || meta.keywords || [];
+    if (!Array.isArray(tags) || tags.length === 0) {
+      // Derive simple tags from dir words
+      tags = dir.replace(/^qk-/, '').split('-');
+    }
+
+    // Normalize dependencies
+    let dependencies = meta.dependencies || [];
+    if (!fromCapabilityYaml) {
+      // Derive from V8.1 skill frontmatter decision_boundary / workflow
+      const deps = new Set();
+      if (meta.workflow && typeof meta.workflow === 'string') deps.add(meta.workflow);
+      if (meta.decision_boundary?.delegates_to) {
+        meta.decision_boundary.delegates_to.forEach(d => deps.add(d));
+      }
+      dependencies = Array.from(deps);
+    }
+
+    capabilities[id] = {
+      path: `.agents/skills/${dir}`,
+      version,
+      tags,
+      dependencies
+    };
+
+    adjacency[id] = dependencies;
+    if (!reverseAdjacency[id]) reverseAdjacency[id] = [];
+  }
+
+  // Populate reverse adjacency for orphan detection
+  for (const [id, deps] of Object.entries(adjacency)) {
+    for (const dep of deps) {
+      if (!reverseAdjacency[dep]) reverseAdjacency[dep] = [];
+      reverseAdjacency[dep].push(id);
+    }
+  }
+
+  // Detect cycles using DFS
+  let hasCycles = false;
+  const visited = {};
+  const recursionStack = {};
+
+  function detectCycle(node) {
+    visited[node] = true;
+    recursionStack[node] = true;
+
+    const deps = adjacency[node] || [];
+    for (const dep of deps) {
+      if (!visited[dep]) {
+        if (detectCycle(dep)) return true;
+      } else if (recursionStack[dep]) {
+        return true;
+      }
+    }
+
+    recursionStack[node] = false;
+    return false;
+  }
+
+  for (const node of Object.keys(adjacency)) {
+    if (!visited[node]) {
+      if (detectCycle(node)) {
+        hasCycles = true;
+        break;
+      }
+    }
+  }
+
+  // Build Graph JSON (O(1) Runtime lookups)
+  const graphNodes = {};
+  for (const [id, data] of Object.entries(capabilities)) {
+    const dependents = reverseAdjacency[id] || [];
+    const isOrphan = data.dependencies.length === 0 && dependents.length === 0 && id !== 'qk-orchestrator' && id !== 'qk-help';
+
+    graphNodes[id] = {
+      path: data.path,
+      version: data.version,
+      tags: data.tags,
+      dependencies: data.dependencies,
+      dependents,
+      is_orphan: isOrphan
+    };
+  }
+
+  const graphJsonData = {
+    schema_version: 1,
+    manifest_version: '8.2',
+    generated_at: new Date().toISOString(),
+    nodes: graphNodes,
+    adjacency,
+    stats: {
+      total_capabilities: Object.keys(capabilities).length,
+      has_cycles: hasCycles
+    }
+  };
+
+  // Build Registry Index YAML (Lightweight lookup)
+  const indexYamlContent = `# AUTO-GENERATED BY registry-builder (tooling/build-registry.js)\n# DO NOT EDIT MANUALLY. THIS IS A GENERATED RUNTIME ARTIFACT.\n` +
+    yaml.dump({
+      schema_version: 1,
+      manifest_version: '8.2',
+      generated_at: new Date().toISOString(),
+      capabilities
+    }, { indent: 2 });
+
+  fs.writeFileSync(INDEX_YAML, indexYamlContent, 'utf8');
+  fs.writeFileSync(GRAPH_JSON, JSON.stringify(graphJsonData, null, 2), 'utf8');
+
+  console.log(`✅ Generated lightweight registry index at .agents/registry/index.yaml (${Object.keys(capabilities).length} capabilities)`);
+  console.log(`✅ Generated O(1) adjacency graph at .agents/registry/graph.json (has_cycles: ${hasCycles})`);
+}
+
+buildRegistry();