@bluefly/openstandardagents 0.2.5-RC → 0.2.7

package/scripts/create-issue-helper.ts

@@ -0,0 +1,238 @@
+#!/usr/bin/env tsx
+
+/**
+ * GitLab Issue Creation Helper (Zod Edition)
+ * 
+ * Creates GitLab issues via API with proper validation and error handling.
+ * Uses Zod for runtime validation and type safety.
+ * 
+ * Usage:
+ *   npx tsx scripts/create-issue-helper.ts <title> <milestone-id> <labels> [description-file]
+ * 
+ * Example:
+ *   npx tsx scripts/create-issue-helper.ts "Enhance bin" 3 "enhancement,cli,bin" .gitlab/ISSUE-BIN-ENHANCEMENT.md
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { z } from 'zod';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+// ============================================================================
+// Zod Schemas
+// ============================================================================
+
+const ConfigSchema = z.object({
+  gitlabApiUrl: z.string().url(),
+  gitlabToken: z.string().min(1, 'GitLab token is required'),
+  projectId: z.string().min(1, 'Project ID is required'),
+  title: z.string().min(1, 'Title is required'),
+  milestoneId: z.number().int().positive('Milestone ID must be a positive integer'),
+  labels: z.array(z.string().min(1)).min(1, 'At least one label is required'),
+  description: z.string().optional(),
+});
+
+const GitLabIssueResponseSchema = z.object({
+  iid: z.number(),
+  web_url: z.string().url(),
+  title: z.string(),
+  state: z.string(),
+});
+
+const GitLabErrorResponseSchema = z.object({
+  message: z.string().optional(),
+  error: z.string().optional(),
+});
+
+type Config = z.infer<typeof ConfigSchema>;
+type GitLabIssueResponse = z.infer<typeof GitLabIssueResponseSchema>;
+type GitLabErrorResponse = z.infer<typeof GitLabErrorResponseSchema>;
+
+// ============================================================================
+// Configuration
+// ============================================================================
+
+function getConfig(): Config {
+  const args = process.argv.slice(2);
+  
+  if (args.length < 3) {
+    console.error('❌ Usage: tsx scripts/create-issue-helper.ts <title> <milestone-id> <labels> [description-file]');
+    console.error('   Example: tsx scripts/create-issue-helper.ts "Enhance bin" 3 "enhancement,cli,bin" .gitlab/ISSUE-BIN-ENHANCEMENT.md');
+    process.exit(1);
+  }
+
+  const [title, milestoneIdStr, labelsStr, descFile] = args;
+  
+  // Parse milestone ID
+  const milestoneId = parseInt(milestoneIdStr, 10);
+  if (isNaN(milestoneId) || milestoneId <= 0) {
+    console.error(`❌ Invalid milestone ID: ${milestoneIdStr}`);
+    process.exit(1);
+  }
+
+  // Parse labels
+  const labels = labelsStr.split(',').map(l => l.trim()).filter(l => l.length > 0);
+  if (labels.length === 0) {
+    console.error(`❌ No valid labels provided: ${labelsStr}`);
+    process.exit(1);
+  }
+
+  // Read description file if provided
+  let description: string | undefined;
+  if (descFile) {
+    const descPath = path.isAbsolute(descFile) ? descFile : path.join(process.cwd(), descFile);
+    if (!fs.existsSync(descPath)) {
+      console.error(`❌ Description file not found: ${descPath}`);
+      process.exit(1);
+    }
+    description = fs.readFileSync(descPath, 'utf-8');
+  }
+
+  // Get GitLab token (try multiple sources)
+  const gitlabToken = process.env.SERVICE_ACCOUNT_OSSA_TOKEN ||
+                      process.env.SERVICE_ACCOUNT_VERSION_MANAGER_TOKEN ||
+                      process.env.GITLAB_TOKEN ||
+                      process.env.GITLAB_PUSH_TOKEN ||
+                      '';
+
+  if (!gitlabToken) {
+    console.error('❌ No GitLab token found. Please set one of:');
+    console.error('   - SERVICE_ACCOUNT_OSSA_TOKEN');
+    console.error('   - SERVICE_ACCOUNT_VERSION_MANAGER_TOKEN');
+    console.error('   - GITLAB_TOKEN');
+    console.error('   - GITLAB_PUSH_TOKEN');
+    process.exit(1);
+  }
+
+  // Get project ID
+  const projectId = process.env.CI_PROJECT_ID || 
+                    process.env.GITLAB_PROJECT_ID ||
+                    'blueflyio/openstandardagents';
+
+  // Get API URL
+  const gitlabApiUrl = process.env.CI_API_V4_URL ||
+                       process.env.GITLAB_API_URL ||
+                       'https://gitlab.com/api/v4';
+
+  try {
+    return ConfigSchema.parse({
+      gitlabApiUrl,
+      gitlabToken,
+      projectId,
+      title,
+      milestoneId,
+      labels,
+      description,
+    });
+  } catch (error) {
+    if (error instanceof z.ZodError) {
+      console.error('❌ Configuration validation failed:');
+      error.issues.forEach((issue) => {
+        console.error(`   • ${issue.path.join('.')}: ${issue.message}`);
+      });
+    } else {
+      console.error('❌ Configuration error:', error instanceof Error ? error.message : String(error));
+    }
+    process.exit(1);
+  }
+}
+
+// ============================================================================
+// GitLab API
+// ============================================================================
+
+async function createIssue(config: Config): Promise<GitLabIssueResponse> {
+  const projectPath = encodeURIComponent(config.projectId);
+  const url = `${config.gitlabApiUrl}/projects/${projectPath}/issues`;
+
+  const payload = {
+    title: config.title,
+    description: config.description || '',
+    milestone_id: config.milestoneId,
+    labels: config.labels.join(','),
+  };
+
+  try {
+    const response = await fetch(url, {
+      method: 'POST',
+      headers: {
+        'PRIVATE-TOKEN': config.gitlabToken,
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify(payload),
+    });
+
+    const responseText = await response.text();
+    let responseData: unknown;
+
+    try {
+      responseData = JSON.parse(responseText);
+    } catch {
+      responseData = responseText;
+    }
+
+    if (!response.ok) {
+      // Try to parse as error response
+      const errorData = GitLabErrorResponseSchema.safeParse(responseData);
+      if (errorData.success) {
+        const error = errorData.data;
+        throw new Error(`GitLab API error: ${error.message || error.error || responseText}`);
+      }
+      throw new Error(`GitLab API error (HTTP ${response.status}): ${responseText}`);
+    }
+
+    // Validate response
+    const issue = GitLabIssueResponseSchema.parse(responseData);
+    return issue;
+  } catch (error) {
+    if (error instanceof z.ZodError) {
+      console.error('❌ Invalid response from GitLab API:');
+      error.issues.forEach((issue) => {
+        console.error(`   • ${issue.path.join('.')}: ${issue.message}`);
+      });
+      throw new Error('Failed to parse GitLab API response');
+    }
+    throw error;
+  }
+}
+
+// ============================================================================
+// Main
+// ============================================================================
+
+async function main(): Promise<void> {
+  console.log('🔧 GitLab Issue Creation Helper (Zod Edition)');
+  console.log('==============================================\n');
+
+  const config = getConfig();
+  
+  console.log(`📋 Configuration:`);
+  console.log(`   Project: ${config.projectId}`);
+  console.log(`   Title: ${config.title}`);
+  console.log(`   Milestone: #${config.milestoneId}`);
+  console.log(`   Labels: ${config.labels.join(', ')}`);
+  console.log(`   Description: ${config.description ? `${config.description.length} chars` : 'none'}`);
+  console.log('');
+
+  try {
+    const issue = await createIssue(config);
+    
+    console.log('✅ Issue created successfully!');
+    console.log(`   Issue: !${issue.iid}`);
+    console.log(`   URL: ${issue.web_url}`);
+    console.log(`   State: ${issue.state}`);
+  } catch (error) {
+    console.error('❌ Failed to create issue:', error instanceof Error ? error.message : String(error));
+    process.exit(1);
+  }
+}
+
+// Run
+main().catch((error) => {
+  console.error('❌ Fatal error:', error instanceof Error ? error.message : String(error));
+  process.exit(1);
+});
+

package/scripts/create-milestone-issue.ts

@@ -0,0 +1,73 @@
+#!/usr/bin/env tsx
+
+/**
+ * Create GitLab Issue for Milestone
+ * Quick script to create issues via GitLab API
+ */
+
+import { readFileSync } from 'fs';
+
+const GITLAB_API_URL = process.env.CI_API_V4_URL || 'https://gitlab.com/api/v4';
+const GITLAB_TOKEN = process.env.SERVICE_ACCOUNT_OSSA_TOKEN || 
+                      process.env.GITLAB_TOKEN || 
+                      process.env.GITLAB_PUSH_TOKEN || '';
+const PROJECT_ID = process.env.CI_PROJECT_ID || 'blueflyio/openstandardagents';
+
+async function createIssue(
+  title: string,
+  description: string,
+  milestoneId: number,
+  labels: string[] = []
+) {
+  if (!GITLAB_TOKEN) {
+    console.error('❌ GITLAB_TOKEN or SERVICE_ACCOUNT_OSSA_TOKEN required');
+    process.exit(1);
+  }
+
+  const projectPath = encodeURIComponent(PROJECT_ID);
+  const url = `${GITLAB_API_URL}/projects/${projectPath}/issues`;
+
+  try {
+    const response = await fetch(url, {
+      method: 'POST',
+      headers: {
+        'PRIVATE-TOKEN': GITLAB_TOKEN,
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify({
+        title,
+        description,
+        milestone_id: milestoneId,
+        labels: labels.join(','),
+      }),
+    });
+
+    if (!response.ok) {
+      const error = await response.text();
+      throw new Error(`Failed to create issue: ${error}`);
+    }
+
+    const issue = await response.json();
+    console.log(`✅ Issue created: !${issue.iid}`);
+    console.log(`   URL: ${issue.web_url}`);
+    return issue.iid;
+  } catch (error) {
+    console.error('❌ Error creating issue:', error);
+    process.exit(1);
+  }
+}
+
+// Main
+const args = process.argv.slice(2);
+if (args.length < 3) {
+  console.log('Usage: tsx scripts/create-milestone-issue.ts <title> <milestone-id> <labels> [description-file]');
+  console.log('Example: tsx scripts/create-milestone-issue.ts "Enhance bin" 3 "enhancement,cli"');
+  process.exit(1);
+}
+
+const [title, milestoneId, labelsStr, descFile] = args;
+const labels = labelsStr.split(',').map(l => l.trim());
+const description = descFile && readFileSync(descFile, 'utf-8') || '';
+
+createIssue(title, description, parseInt(milestoneId), labels);
+

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