@bluefly/openstandardagents 0.2.5-RC → 0.2.8

package/scripts/fix-schema-formats.js

@@ -0,0 +1,82 @@
+#!/usr/bin/env node
+
+/**
+ * Fix unsupported format constraints in JSON schemas
+ * Removes format constraints that aren't supported by ajv-cli
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const UNSUPPORTED_FORMATS = ['uri'];
+const SPEC_DIR = path.join(__dirname, '..', 'spec');
+
+function fixSchema(schemaPath) {
+  const content = fs.readFileSync(schemaPath, 'utf8');
+  const schema = JSON.parse(content);
+  
+  let fixed = false;
+  
+  function walk(obj) {
+    if (typeof obj !== 'object' || obj === null) return;
+    
+    if (obj.format && UNSUPPORTED_FORMATS.includes(obj.format)) {
+      delete obj.format;
+      fixed = true;
+    }
+    
+    for (const key in obj) {
+      walk(obj[key]);
+    }
+  }
+  
+  walk(schema);
+  
+  if (fixed) {
+    fs.writeFileSync(schemaPath, JSON.stringify(schema, null, 2) + '\n');
+    return true;
+  }
+  
+  return false;
+}
+
+function findSchemas(dir) {
+  const schemas = [];
+  
+  function scan(currentDir) {
+    const entries = fs.readdirSync(currentDir, { withFileTypes: true });
+    
+    for (const entry of entries) {
+      const fullPath = path.join(currentDir, entry.name);
+      
+      if (entry.isDirectory()) {
+        scan(fullPath);
+      } else if (entry.name.endsWith('.schema.json')) {
+        schemas.push(fullPath);
+      }
+    }
+  }
+  
+  scan(dir);
+  return schemas;
+}
+
+console.log('🔧 Fixing schema format constraints...\n');
+
+const schemas = findSchemas(SPEC_DIR);
+let fixedCount = 0;
+
+for (const schemaPath of schemas) {
+  const relative = path.relative(process.cwd(), schemaPath);
+  
+  try {
+    if (fixSchema(schemaPath)) {
+      console.log(`✓ Fixed: ${relative}`);
+      fixedCount++;
+    }
+  } catch (err) {
+    console.error(`✗ Error in ${relative}: ${err.message}`);
+  }
+}
+
+console.log(`\n${fixedCount} schema(s) fixed`);

package/scripts/generate-agents-catalog.ts

@@ -0,0 +1,77 @@
+#!/usr/bin/env tsx
+import { readdirSync, readFileSync, writeFileSync, statSync, mkdirSync } from 'fs';
+import { join, relative } from 'path';
+import yaml from 'js-yaml';
+
+const AGENTS_DIR = join(process.cwd(), '.gitlab/agents');
+const OUTPUT_FILE = join(process.cwd(), 'website/content/docs/agents/catalog.md');
+
+interface Agent {
+  id: string;
+  name: string;
+  role: string;
+  description?: string;
+  capabilities: Array<{ name: string; description: string }>;
+  path: string;
+}
+
+function findAgents(): Agent[] {
+  const agents: Agent[] = [];
+  const entries = readdirSync(AGENTS_DIR);
+  
+  for (const entry of entries) {
+    const manifestPath = join(AGENTS_DIR, entry, 'manifest.ossa.yaml');
+    try {
+      const content = readFileSync(manifestPath, 'utf-8');
+      const data = yaml.load(content) as any;
+      
+      if (data?.agent) {
+        agents.push({
+          id: data.agent.id,
+          name: data.agent.name,
+          role: data.agent.role,
+          description: data.agent.description,
+          capabilities: data.agent.capabilities || [],
+          path: relative(process.cwd(), manifestPath)
+        });
+      }
+    } catch (error) {
+      // Skip if no manifest
+    }
+  }
+  
+  return agents;
+}
+
+const agents = findAgents();
+
+let doc = `# GitLab Agents Catalog
+
+OSSA-compliant agents for GitLab CI/CD automation.
+
+**Total Agents**: ${agents.length}
+
+`;
+
+for (const agent of agents.sort((a, b) => a.name.localeCompare(b.name))) {
+  doc += `## ${agent.name}\n\n`;
+  doc += `**ID**: \`${agent.id}\`  \n`;
+  doc += `**Role**: \`${agent.role}\`\n\n`;
+  if (agent.description) doc += `${agent.description}\n\n`;
+  
+  if (agent.capabilities.length > 0) {
+    doc += `### Capabilities\n\n`;
+    for (const cap of agent.capabilities) {
+      doc += `- **${cap.name}**: ${cap.description}\n`;
+    }
+    doc += '\n';
+  }
+  
+  doc += `**Manifest**: [\`${agent.path}\`](https://github.com/blueflyio/openstandardagents/blob/main/${agent.path})\n\n`;
+  doc += `\`\`\`bash\n# Deploy agent\nkubectl apply -f ${agent.path}\n\`\`\`\n\n`;
+}
+
+mkdirSync(join(process.cwd(), 'website/content/docs/agents'), { recursive: true });
+writeFileSync(OUTPUT_FILE, doc);
+
+console.log(`✅ Generated agents catalog: ${agents.length} agents`);

package/scripts/generate-api-docs.ts

@@ -0,0 +1,218 @@
+#!/usr/bin/env tsx
+/**
+ * Generate API documentation from OpenAPI specifications
+ * 
+ * Usage: npm run docs:api:generate
+ */
+
+import { readFileSync, writeFileSync, mkdirSync, readdirSync } from 'fs';
+import { join, basename } from 'path';
+import yaml from 'js-yaml';
+
+interface OpenAPISpec {
+  openapi: string;
+  info: {
+    title: string;
+    version: string;
+    description?: string;
+  };
+  servers?: Array<{ url: string; description?: string }>;
+  paths: Record<string, Record<string, any>>;
+  components?: {
+    schemas?: Record<string, any>;
+    securitySchemes?: Record<string, any>;
+  };
+}
+
+const OPENAPI_DIR = join(process.cwd(), 'openapi');
+const OUTPUT_DIR = join(process.cwd(), 'website/content/docs/api-reference');
+
+function generateEndpointDoc(path: string, method: string, operation: any): string {
+  const methodUpper = method.toUpperCase();
+  let doc = `### ${operation.summary || `${methodUpper} ${path}`}\n\n`;
+  
+  doc += '```http\n';
+  doc += `${methodUpper} ${path}\n`;
+  doc += '```\n\n';
+  
+  if (operation.description) {
+    doc += `**Description**: ${operation.description}\n\n`;
+  }
+  
+  // Parameters
+  if (operation.parameters && operation.parameters.length > 0) {
+    doc += '**Parameters**:\n\n';
+    for (const param of operation.parameters) {
+      const required = param.required ? ', required' : '';
+      doc += `- \`${param.name}\` (${param.in}${required}) - ${param.description || 'No description'}\n`;
+    }
+    doc += '\n';
+  }
+  
+  // Request body
+  if (operation.requestBody) {
+    doc += '**Request Body**:\n\n';
+    const content = operation.requestBody.content;
+    if (content && content['application/json']) {
+      doc += '```json\n';
+      doc += JSON.stringify(content['application/json'].example || {}, null, 2);
+      doc += '\n```\n\n';
+    }
+  }
+  
+  // Responses
+  if (operation.responses) {
+    doc += '**Responses**:\n\n';
+    for (const [code, response] of Object.entries(operation.responses)) {
+      doc += `**${code}**: ${(response as any).description}\n\n`;
+      const content = (response as any).content;
+      if (content && content['application/json']) {
+        doc += '```json\n';
+        doc += JSON.stringify(content['application/json'].example || {}, null, 2);
+        doc += '\n```\n\n';
+      }
+    }
+  }
+  
+  // Example
+  doc += '**Example**:\n\n';
+  doc += '```bash\n';
+  doc += `curl -X ${methodUpper} "https://api.ossa.dev${path}" \\\n`;
+  doc += '  -H "Authorization: Bearer YOUR_TOKEN"';
+  if (operation.requestBody) {
+    doc += ' \\\n  -H "Content-Type: application/json" \\\n  -d @request.json';
+  }
+  doc += '\n```\n\n';
+  
+  return doc;
+}
+
+function generateAPIDoc(spec: OpenAPISpec, filename: string): string {
+  const apiName = spec.info.title;
+  const apiVersion = spec.info.version;
+  
+  let doc = `# ${apiName}\n\n`;
+  doc += `**Version**: ${apiVersion}\n\n`;
+  
+  if (spec.info.description) {
+    doc += `${spec.info.description}\n\n`;
+  }
+  
+  doc += '## Base URL\n\n';
+  if (spec.servers && spec.servers.length > 0) {
+    for (const server of spec.servers) {
+      doc += `- \`${server.url}\``;
+      if (server.description) {
+        doc += ` - ${server.description}`;
+      }
+      doc += '\n';
+    }
+  } else {
+    doc += '`https://api.ossa.dev`\n';
+  }
+  doc += '\n';
+  
+  // Authentication
+  if (spec.components?.securitySchemes) {
+    doc += '## Authentication\n\n';
+    doc += 'This API requires authentication. See [Authentication Guide](../authentication.md) for details.\n\n';
+  }
+  
+  // Endpoints
+  doc += '## Endpoints\n\n';
+  
+  for (const [path, methods] of Object.entries(spec.paths)) {
+    for (const [method, operation] of Object.entries(methods)) {
+      if (['get', 'post', 'put', 'patch', 'delete'].includes(method)) {
+        doc += generateEndpointDoc(path, method, operation);
+      }
+    }
+  }
+  
+  // Related documentation
+  doc += '## Related Documentation\n\n';
+  doc += '- [CLI Reference](../cli-reference/index.md)\n';
+  doc += '- [Schema Reference](../schema-reference/index.md)\n';
+  doc += '- [Authentication Guide](../authentication.md)\n';
+  
+  return doc;
+}
+
+function main() {
+  console.log('🚀 Generating API documentation...\n');
+  
+  // Create output directory
+  mkdirSync(OUTPUT_DIR, { recursive: true });
+  
+  // Process core APIs
+  const coreDir = join(OPENAPI_DIR, 'core');
+  const coreFiles = readdirSync(coreDir).filter(f => f.endsWith('.yaml'));
+  
+  console.log(`📁 Processing ${coreFiles.length} core API specs...\n`);
+  
+  for (const file of coreFiles) {
+    try {
+      const specPath = join(coreDir, file);
+      const specContent = readFileSync(specPath, 'utf-8');
+      const spec = yaml.load(specContent) as OpenAPISpec;
+      
+      const docContent = generateAPIDoc(spec, file);
+      const outputFile = join(OUTPUT_DIR, file.replace('.openapi.yaml', '.md'));
+      
+      writeFileSync(outputFile, docContent);
+      console.log(`✅ Generated: ${basename(outputFile)}`);
+    } catch (error) {
+      console.log(`⚠️  Skipped: ${file} (${(error as Error).message})`);
+    }
+  }
+  
+  // Generate index
+  const indexContent = `# API Reference
+
+Welcome to the OSSA API Reference documentation.
+
+## Core APIs
+
+${coreFiles.map(f => {
+  const name = f.replace('.openapi.yaml', '').replace(/-/g, ' ').replace(/\b\w/g, l => l.toUpperCase());
+  const link = f.replace('.openapi.yaml', '.md');
+  return `- [${name}](${link})`;
+}).join('\n')}
+
+## Authentication
+
+All API endpoints require authentication. See the [Authentication Guide](./authentication.md) for details.
+
+## Rate Limiting
+
+- 100 requests per minute per API key
+- 1000 requests per hour per API key
+
+## Error Responses
+
+All APIs use standard HTTP status codes and return errors in the following format:
+
+\`\`\`json
+{
+  "error": "error_code",
+  "message": "Human-readable error message",
+  "details": []
+}
+\`\`\`
+
+## Support
+
+For API support, please:
+- Check the [Troubleshooting Guide](../guides/troubleshooting.md)
+- Open an issue on [GitLab](https://gitlab.com/blueflyio/openstandardagents/-/issues)
+- Join our [Discord community](https://discord.gg/ossa)
+`;
+  
+  writeFileSync(join(OUTPUT_DIR, 'index.md'), indexContent);
+  console.log(`✅ Generated: index.md`);
+  
+  console.log(`\n✨ API documentation generated successfully!`);
+  console.log(`📂 Output: ${OUTPUT_DIR}`);
+}
+
+main();