@bluefly/openstandardagents 0.2.9 → 0.3.0

package/scripts/generate-cli-docs.ts

@@ -1,410 +0,0 @@
-#!/usr/bin/env tsx
-/**
- * Generate CLI documentation from command source files
- * 
- * Usage: npm run docs:cli:generate
- */
-
-import { readFileSync, writeFileSync, mkdirSync, readdirSync } from 'fs';
-import { join, basename } from 'path';
-
-interface CommandInfo {
-  name: string;
-  description: string;
-  arguments: Array<{ name: string; description: string; required: boolean }>;
-  options: Array<{ flag: string; description: string; default?: string }>;
-  examples: string[];
-  apiEndpoint?: string;
-}
-
-const CLI_DIR = join(process.cwd(), 'src/cli/commands');
-const OUTPUT_DIR = join(process.cwd(), 'website/content/docs/cli-reference');
-
-// Command metadata (extracted from source or defined here)
-const COMMANDS: Record<string, CommandInfo> = {
-  validate: {
-    name: 'validate',
-    description: 'Validate OSSA agent manifests against the schema',
-    arguments: [
-      { name: 'path', description: 'Path to agent manifest file or directory', required: true }
-    ],
-    options: [
-      { flag: '--version <version>', description: 'Specify OSSA version', default: 'latest' },
-      { flag: '--strict', description: 'Enable strict validation mode' },
-      { flag: '--format <format>', description: 'Output format: json, yaml, table', default: 'table' },
-      { flag: '--verbose', description: 'Show detailed validation errors' }
-    ],
-    examples: [
-      'ossa validate agent.ossa.yaml',
-      'ossa validate ./agents/',
-      'ossa validate agent.ossa.yaml --strict',
-      'ossa validate agent.ossa.yaml --format json'
-    ],
-    apiEndpoint: 'POST /api/v1/validate'
-  },
-  generate: {
-    name: 'generate',
-    description: 'Generate OSSA agent manifests from templates',
-    arguments: [
-      { name: 'type', description: 'Agent type: worker, orchestrator, compliance, chat', required: true }
-    ],
-    options: [
-      { flag: '--name <name>', description: 'Agent name', default: 'My Agent' },
-      { flag: '--id <id>', description: 'Agent ID (DNS-1123 format)' },
-      { flag: '--output <path>', description: 'Output file path', default: 'agent.ossa.yaml' },
-      { flag: '--interactive', description: 'Interactive mode with prompts' }
-    ],
-    examples: [
-      'ossa generate worker --name "Data Processor"',
-      'ossa generate orchestrator --id my-orchestrator',
-      'ossa generate compliance --interactive',
-      'ossa generate chat --output chat-agent.yaml'
-    ],
-    apiEndpoint: 'POST /api/v1/agents/generate'
-  },
-  migrate: {
-    name: 'migrate',
-    description: 'Migrate agent manifests between OSSA versions',
-    arguments: [
-      { name: 'source', description: 'Source manifest file', required: true }
-    ],
-    options: [
-      { flag: '--from <version>', description: 'Source OSSA version' },
-      { flag: '--to <version>', description: 'Target OSSA version', default: 'latest' },
-      { flag: '--output <path>', description: 'Output file path' },
-      { flag: '--dry-run', description: 'Show changes without writing' }
-    ],
-    examples: [
-      'ossa migrate agent.yaml --from 0.2.4 --to 0.2.5',
-      'ossa migrate agent.yaml --dry-run',
-      'ossa migrate agent.yaml --output migrated-agent.yaml'
-    ],
-    apiEndpoint: 'POST /api/v1/migrate'
-  },
-  run: {
-    name: 'run',
-    description: 'Run an OSSA agent locally',
-    arguments: [
-      { name: 'manifest', description: 'Path to agent manifest', required: true }
-    ],
-    options: [
-      { flag: '--env <file>', description: 'Environment variables file' },
-      { flag: '--port <port>', description: 'Port to run on', default: '3000' },
-      { flag: '--watch', description: 'Watch for changes and reload' },
-      { flag: '--debug', description: 'Enable debug logging' }
-    ],
-    examples: [
-      'ossa run agent.ossa.yaml',
-      'ossa run agent.ossa.yaml --port 8080',
-      'ossa run agent.ossa.yaml --watch --debug',
-      'ossa run agent.ossa.yaml --env .env.local'
-    ],
-    apiEndpoint: 'POST /api/v1/agents/{id}/execute'
-  },
-  init: {
-    name: 'init',
-    description: 'Initialize a new OSSA project',
-    arguments: [],
-    options: [
-      { flag: '--name <name>', description: 'Project name' },
-      { flag: '--template <template>', description: 'Project template: minimal, full, enterprise' },
-      { flag: '--typescript', description: 'Use TypeScript' },
-      { flag: '--git', description: 'Initialize git repository' }
-    ],
-    examples: [
-      'ossa init',
-      'ossa init --name my-agent-project',
-      'ossa init --template enterprise --typescript',
-      'ossa init --git'
-    ]
-  },
-  setup: {
-    name: 'setup',
-    description: 'Set up OSSA development environment',
-    arguments: [],
-    options: [
-      { flag: '--gitlab', description: 'Configure GitLab integration' },
-      { flag: '--kubernetes', description: 'Configure Kubernetes deployment' },
-      { flag: '--registry <url>', description: 'Configure agent registry' },
-      { flag: '--interactive', description: 'Interactive setup wizard' }
-    ],
-    examples: [
-      'ossa setup --interactive',
-      'ossa setup --gitlab',
-      'ossa setup --kubernetes',
-      'ossa setup --registry https://registry.ossa.dev'
-    ]
-  },
-  export: {
-    name: 'export',
-    description: 'Export agent manifest to different formats',
-    arguments: [
-      { name: 'manifest', description: 'Path to agent manifest', required: true }
-    ],
-    options: [
-      { flag: '--format <format>', description: 'Export format: json, yaml, openapi, k8s', default: 'json' },
-      { flag: '--output <path>', description: 'Output file path' },
-      { flag: '--pretty', description: 'Pretty print output' }
-    ],
-    examples: [
-      'ossa export agent.ossa.yaml --format json',
-      'ossa export agent.ossa.yaml --format k8s --output deployment.yaml',
-      'ossa export agent.ossa.yaml --format openapi --pretty'
-    ]
-  },
-  import: {
-    name: 'import',
-    description: 'Import agents from other frameworks',
-    arguments: [
-      { name: 'source', description: 'Source file or URL', required: true }
-    ],
-    options: [
-      { flag: '--from <framework>', description: 'Source framework: langchain, crewai, openai, mcp' },
-      { flag: '--output <path>', description: 'Output file path', default: 'agent.ossa.yaml' },
-      { flag: '--validate', description: 'Validate after import' }
-    ],
-    examples: [
-      'ossa import langchain-agent.py --from langchain',
-      'ossa import crew.yaml --from crewai --validate',
-      'ossa import https://example.com/agent.json --from openai'
-    ]
-  },
-  schema: {
-    name: 'schema',
-    description: 'View and manage OSSA schemas',
-    arguments: [],
-    options: [
-      { flag: '--version <version>', description: 'Schema version', default: 'latest' },
-      { flag: '--format <format>', description: 'Output format: json, yaml', default: 'yaml' },
-      { flag: '--field <field>', description: 'Show specific field documentation' },
-      { flag: '--list', description: 'List available schema versions' }
-    ],
-    examples: [
-      'ossa schema',
-      'ossa schema --version 0.2.5',
-      'ossa schema --field agent.id',
-      'ossa schema --list'
-    ]
-  },
-  'gitlab-agent': {
-    name: 'gitlab-agent',
-    description: 'Manage GitLab agent integration',
-    arguments: [],
-    options: [
-      { flag: '--configure', description: 'Configure GitLab agent' },
-      { flag: '--deploy', description: 'Deploy agent to GitLab' },
-      { flag: '--status', description: 'Check agent status' },
-      { flag: '--logs', description: 'View agent logs' }
-    ],
-    examples: [
-      'ossa gitlab-agent --configure',
-      'ossa gitlab-agent --deploy',
-      'ossa gitlab-agent --status',
-      'ossa gitlab-agent --logs'
-    ]
-  },
-  agents: {
-    name: 'agents',
-    description: 'Manage OSSA agents',
-    arguments: [
-      { name: 'action', description: 'Action: list, get, create, update, delete', required: true }
-    ],
-    options: [
-      { flag: '--id <id>', description: 'Agent ID' },
-      { flag: '--role <role>', description: 'Filter by role' },
-      { flag: '--status <status>', description: 'Filter by status' },
-      { flag: '--format <format>', description: 'Output format: json, yaml, table', default: 'table' }
-    ],
-    examples: [
-      'ossa agents list',
-      'ossa agents list --role worker',
-      'ossa agents get --id my-agent',
-      'ossa agents create agent.ossa.yaml',
-      'ossa agents delete --id my-agent'
-    ],
-    apiEndpoint: 'GET /api/v1/agents'
-  }
-};
-
-function generateCommandDoc(cmd: CommandInfo): string {
-  let doc = `# ossa ${cmd.name}\n\n`;
-  doc += `**Purpose**: ${cmd.description}\n\n`;
-  
-  // Synopsis
-  doc += '## Synopsis\n\n';
-  doc += '```bash\n';
-  doc += `ossa ${cmd.name}`;
-  if (cmd.arguments.length > 0) {
-    for (const arg of cmd.arguments) {
-      doc += arg.required ? ` <${arg.name}>` : ` [${arg.name}]`;
-    }
-  }
-  doc += ' [options]\n';
-  doc += '```\n\n';
-  
-  // Description
-  doc += '## Description\n\n';
-  doc += `${cmd.description}\n\n`;
-  
-  // Arguments
-  if (cmd.arguments.length > 0) {
-    doc += '## Arguments\n\n';
-    for (const arg of cmd.arguments) {
-      const required = arg.required ? ' (required)' : ' (optional)';
-      doc += `- \`<${arg.name}>\`${required} - ${arg.description}\n`;
-    }
-    doc += '\n';
-  }
-  
-  // Options
-  if (cmd.options.length > 0) {
-    doc += '## Options\n\n';
-    for (const opt of cmd.options) {
-      doc += `- \`${opt.flag}\` - ${opt.description}`;
-      if (opt.default) {
-        doc += ` (default: ${opt.default})`;
-      }
-      doc += '\n';
-    }
-    doc += '\n';
-  }
-  
-  // Examples
-  if (cmd.examples.length > 0) {
-    doc += '## Examples\n\n';
-    for (const example of cmd.examples) {
-      doc += '```bash\n';
-      doc += example + '\n';
-      doc += '```\n\n';
-    }
-  }
-  
-  // API endpoint connection
-  if (cmd.apiEndpoint) {
-    doc += '## API Endpoint Connection\n\n';
-    doc += `This command uses the following API endpoint:\n`;
-    doc += `- \`${cmd.apiEndpoint}\` - [API Reference](../api-reference/index.md)\n\n`;
-  }
-  
-  // Exit codes
-  doc += '## Exit Codes\n\n';
-  doc += '- `0` - Success\n';
-  doc += '- `1` - General error\n';
-  doc += '- `2` - Invalid arguments\n';
-  doc += '- `3` - File not found\n\n';
-  
-  // Related commands
-  doc += '## Related Commands\n\n';
-  const relatedCommands = Object.keys(COMMANDS).filter(c => c !== cmd.name).slice(0, 3);
-  for (const related of relatedCommands) {
-    doc += `- [ossa ${related}](./ossa-${related}.md)\n`;
-  }
-  doc += '\n';
-  
-  // Related documentation
-  doc += '## Related Documentation\n\n';
-  doc += '- [API Reference](../api-reference/index.md)\n';
-  doc += '- [Schema Reference](../schema-reference/index.md)\n';
-  doc += '- [Getting Started](../getting-started/index.md)\n';
-  
-  return doc;
-}
-
-function main() {
-  console.log('🚀 Generating CLI documentation...\n');
-  
-  // Create output directory
-  mkdirSync(OUTPUT_DIR, { recursive: true });
-  
-  console.log(`📁 Processing ${Object.keys(COMMANDS).length} CLI commands...\n`);
-  
-  // Generate documentation for each command
-  for (const [name, cmd] of Object.entries(COMMANDS)) {
-    const docContent = generateCommandDoc(cmd);
-    const outputFile = join(OUTPUT_DIR, `ossa-${name}.md`);
-    
-    writeFileSync(outputFile, docContent);
-    console.log(`✅ Generated: ossa-${name}.md`);
-  }
-  
-  // Generate index
-  const indexContent = `# CLI Reference
-
-The OSSA CLI provides commands for managing AI agents throughout their lifecycle.
-
-## Installation
-
-\`\`\`bash
-npm install -g @bluefly/openstandardagents
-\`\`\`
-
-## Quick Start
-
-\`\`\`bash
-# Validate an agent manifest
-ossa validate agent.ossa.yaml
-
-# Generate a new agent
-ossa generate worker --name "My Agent"
-
-# Run an agent locally
-ossa run agent.ossa.yaml
-\`\`\`
-
-## Commands
-
-${Object.entries(COMMANDS).map(([name, cmd]) => {
-  return `### [ossa ${name}](./ossa-${name}.md)\n\n${cmd.description}\n`;
-}).join('\n')}
-
-## Global Options
-
-- \`--help\` - Show help for any command
-- \`--version\` - Show OSSA CLI version
-- \`--config <path>\` - Path to config file
-- \`--verbose\` - Enable verbose logging
-- \`--quiet\` - Suppress output
-
-## Configuration
-
-The OSSA CLI can be configured via:
-
-1. **Config file**: \`.ossarc.json\` or \`.ossarc.yaml\`
-2. **Environment variables**: \`OSSA_*\`
-3. **Command-line flags**
-
-Example \`.ossarc.json\`:
-
-\`\`\`json
-{
-  "registry": "https://registry.ossa.dev",
-  "defaultVersion": "0.2.5-RC",
-  "validation": {
-    "strict": true
-  }
-}
-\`\`\`
-
-## Environment Variables
-
-- \`OSSA_REGISTRY\` - Agent registry URL
-- \`OSSA_API_KEY\` - API authentication key
-- \`OSSA_VERSION\` - Default OSSA version
-- \`OSSA_DEBUG\` - Enable debug mode
-
-## Related Documentation
-
-- [API Reference](../api-reference/index.md)
-- [Schema Reference](../schema-reference/index.md)
-- [Getting Started](../getting-started/index.md)
-- [Guides](../guides/index.md)
-`;
-  
-  writeFileSync(join(OUTPUT_DIR, 'index.md'), indexContent);
-  console.log(`✅ Generated: index.md`);
-  
-  console.log(`\n✨ CLI documentation generated successfully!`);
-  console.log(`📂 Output: ${OUTPUT_DIR}`);
-}
-
-main();

package/scripts/generate-config-docs.ts

@@ -1,109 +0,0 @@
-#!/usr/bin/env tsx
-import { writeFileSync, mkdirSync } from 'fs';
-import { join } from 'path';
-
-const OUTPUT_FILE = join(process.cwd(), 'website/content/docs/configuration/index.md');
-
-const doc = `# Configuration Reference
-
-Configure OSSA CLI and runtime behavior.
-
-## Configuration File
-
-Create \`.ossarc.json\` or \`.ossarc.yaml\` in your project root:
-
-\`\`\`json
-{
-  "registry": "https://registry.ossa.dev",
-  "defaultVersion": "0.2.5-RC",
-  "validation": {
-    "strict": true,
-    "allowUnknownFields": false
-  },
-  "runtime": {
-    "timeout": 30000,
-    "retries": 3
-  }
-}
-\`\`\`
-
-## Configuration Options
-
-### registry
-- **Type**: \`string\`
-- **Default**: \`"https://registry.ossa.dev"\`
-- **Description**: Agent registry URL
-
-### defaultVersion
-- **Type**: \`string\`
-- **Default**: \`"latest"\`
-- **Description**: Default OSSA schema version
-
-### validation.strict
-- **Type**: \`boolean\`
-- **Default**: \`false\`
-- **Description**: Enable strict validation mode
-
-### validation.allowUnknownFields
-- **Type**: \`boolean\`
-- **Default**: \`true\`
-- **Description**: Allow unknown fields in manifests
-
-### runtime.timeout
-- **Type**: \`number\`
-- **Default**: \`30000\`
-- **Description**: Execution timeout in milliseconds
-
-### runtime.retries
-- **Type**: \`number\`
-- **Default**: \`3\`
-- **Description**: Number of retry attempts
-
-## Environment Variables
-
-Override configuration with environment variables:
-
-- \`OSSA_REGISTRY\` - Registry URL
-- \`OSSA_VERSION\` - Default version
-- \`OSSA_API_KEY\` - API authentication key
-- \`OSSA_DEBUG\` - Enable debug logging
-
-## Examples
-
-### Development Configuration
-
-\`\`\`json
-{
-  "registry": "http://localhost:3000",
-  "validation": {
-    "strict": false
-  }
-}
-\`\`\`
-
-### Production Configuration
-
-\`\`\`json
-{
-  "registry": "https://registry.ossa.dev",
-  "validation": {
-    "strict": true,
-    "allowUnknownFields": false
-  },
-  "runtime": {
-    "timeout": 60000,
-    "retries": 5
-  }
-}
-\`\`\`
-
-## Related
-
-- [CLI Reference](../cli-reference/)
-- [Environment Setup](../getting-started/installation)
-`;
-
-mkdirSync(join(process.cwd(), 'website/content/docs/configuration'), { recursive: true });
-writeFileSync(OUTPUT_FILE, doc);
-
-console.log(`✅ Generated configuration reference`);

package/scripts/generate-errors-docs.ts

@@ -1,76 +0,0 @@
-#!/usr/bin/env tsx
-import { readdirSync, readFileSync, writeFileSync, mkdirSync } from 'fs';
-import { join } from 'path';
-
-const SRC_DIR = join(process.cwd(), 'src');
-const OUTPUT_FILE = join(process.cwd(), 'website/content/docs/errors/index.md');
-
-interface ErrorInfo {
-  code: string;
-  message: string;
-  file: string;
-}
-
-function findErrors(dir: string, errors: ErrorInfo[] = []): ErrorInfo[] {
-  const entries = readdirSync(dir, { withFileTypes: true });
-  
-  for (const entry of entries) {
-    const fullPath = join(dir, entry.name);
-    
-    if (entry.isDirectory()) {
-      findErrors(fullPath, errors);
-    } else if (entry.name.endsWith('.ts')) {
-      const content = readFileSync(fullPath, 'utf-8');
-      
-      // Find throw new Error patterns
-      const matches = content.matchAll(/throw new (\w+Error)\(['"`]([^'"`]+)['"`]\)/g);
-      for (const match of matches) {
-        errors.push({
-          code: match[1],
-          message: match[2],
-          file: fullPath.replace(process.cwd(), '')
-        });
-      }
-    }
-  }
-  
-  return errors;
-}
-
-const errors = findErrors(SRC_DIR);
-const byCode = errors.reduce((acc, err) => {
-  if (!acc[err.code]) acc[err.code] = [];
-  acc[err.code].push(err);
-  return acc;
-}, {} as Record<string, ErrorInfo[]>);
-
-let doc = `# Error Reference
-
-Common errors and solutions.
-
-**Total Error Types**: ${Object.keys(byCode).length}
-
-`;
-
-for (const [code, instances] of Object.entries(byCode).sort()) {
-  doc += `## ${code}\n\n`;
-  
-  const uniqueMessages = [...new Set(instances.map(e => e.message))];
-  for (const msg of uniqueMessages) {
-    doc += `### "${msg}"\n\n`;
-    doc += `**Cause**: Check the error context for details\n\n`;
-    doc += `**Solution**: \n`;
-    doc += `\`\`\`bash\n# Enable debug mode\nDEBUG=* ossa <command>\n\`\`\`\n\n`;
-  }
-}
-
-doc += `## Getting Help
-
-- Check [Troubleshooting Guide](../troubleshooting/)
-- Open an issue on [GitLab](https://gitlab.com/blueflyio/openstandardagents/-/issues)
-`;
-
-mkdirSync(join(process.cwd(), 'website/content/docs/errors'), { recursive: true });
-writeFileSync(OUTPUT_FILE, doc);
-
-console.log(`✅ Generated error reference: ${Object.keys(byCode).length} error types`);

package/scripts/generate-examples-docs.ts

@@ -1,100 +0,0 @@
-#!/usr/bin/env tsx
-/**
- * Generate examples documentation from YAML files
- */
-
-import { readdirSync, readFileSync, writeFileSync, statSync, mkdirSync } from 'fs';
-import { join, relative, basename } from 'path';
-import yaml from 'js-yaml';
-
-const EXAMPLES_DIR = join(process.cwd(), 'examples');
-const OUTPUT_FILE = join(process.cwd(), 'website/content/docs/examples/catalog.md');
-
-interface Example {
-  path: string;
-  name: string;
-  role?: string;
-  description?: string;
-  category: string;
-}
-
-function findYamlFiles(dir: string, category: string = ''): Example[] {
-  const examples: Example[] = [];
-  const entries = readdirSync(dir);
-  
-  for (const entry of entries) {
-    const fullPath = join(dir, entry);
-    const stat = statSync(fullPath);
-    
-    if (stat.isDirectory()) {
-      examples.push(...findYamlFiles(fullPath, category || entry));
-    } else if (entry.match(/\.(yaml|yml)$/)) {
-      try {
-        const content = readFileSync(fullPath, 'utf-8');
-        // Use JSON_SCHEMA to prevent arbitrary code execution (CWE-502)
-        const data = yaml.load(content, { schema: yaml.JSON_SCHEMA }) as any;
-        
-        if (data?.agent) {
-          examples.push({
-            path: relative(EXAMPLES_DIR, fullPath),
-            name: data.agent.name || basename(entry, '.yaml'),
-            role: data.agent.role,
-            description: data.agent.description,
-            category: category || 'general'
-          });
-        }
-      } catch (error) {
-        // Skip invalid YAML
-      }
-    }
-  }
-  
-  return examples;
-}
-
-function generateDocs(examples: Example[]): string {
-  const byCategory = examples.reduce((acc, ex) => {
-    if (!acc[ex.category]) acc[ex.category] = [];
-    acc[ex.category].push(ex);
-    return acc;
-  }, {} as Record<string, Example[]>);
-  
-  let doc = `# Examples Catalog
-
-Auto-generated catalog of all OSSA agent examples.
-
-**Total Examples**: ${examples.length}
-
-`;
-
-  for (const [category, items] of Object.entries(byCategory).sort()) {
-    doc += `## ${category.charAt(0).toUpperCase() + category.slice(1)}\n\n`;
-    
-    for (const item of items.sort((a, b) => a.name.localeCompare(b.name))) {
-      doc += `### ${item.name}\n\n`;
-      if (item.role) doc += `**Role**: \`${item.role}\`\n\n`;
-      if (item.description) doc += `${item.description}\n\n`;
-      doc += `**File**: [\`${item.path}\`](https://github.com/blueflyio/openstandardagents/blob/main/examples/${item.path})\n\n`;
-      doc += `\`\`\`bash\nossa validate examples/${item.path}\n\`\`\`\n\n`;
-    }
-  }
-  
-  doc += `## Usage\n\n`;
-  doc += `\`\`\`bash\n# Validate any example\nossa validate examples/<path>\n\n`;
-  doc += `# Run an example\nossa run examples/<path>\n\`\`\`\n`;
-  
-  return doc;
-}
-
-console.log('🚀 Generating examples documentation...\n');
-
-const examples = findYamlFiles(EXAMPLES_DIR);
-console.log(`📁 Found ${examples.length} examples\n`);
-
-const doc = generateDocs(examples);
-
-mkdirSync(join(process.cwd(), 'website/content/docs/examples'), { recursive: true });
-writeFileSync(OUTPUT_FILE, doc);
-
-console.log(`✅ Generated: ${relative(process.cwd(), OUTPUT_FILE)}`);
-console.log(`\n✨ Examples documentation generated successfully!`);