@bluefly/openstandardagents 0.2.4 → 0.2.7

package/scripts/generate-config-docs.ts

@@ -0,0 +1,109 @@
+#!/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

@@ -0,0 +1,76 @@
+#!/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

@@ -0,0 +1,99 @@
+#!/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');
+        const data = yaml.load(content) 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!`);

package/scripts/generate-schema-docs.ts

@@ -0,0 +1,296 @@
+#!/usr/bin/env tsx
+/**
+ * Generate schema documentation from JSON Schema
+ * 
+ * Usage: npm run docs:schema:generate
+ */
+
+import { readFileSync, writeFileSync, mkdirSync } from 'fs';
+import { join } from 'path';
+
+interface SchemaProperty {
+  type: string | string[];
+  description?: string;
+  format?: string;
+  pattern?: string;
+  enum?: string[];
+  minimum?: number;
+  maximum?: number;
+  minLength?: number;
+  maxLength?: number;
+  required?: boolean;
+  default?: any;
+  examples?: any[];
+  properties?: Record<string, SchemaProperty>;
+  items?: SchemaProperty;
+}
+
+const SPEC_DIR = join(process.cwd(), 'spec/v0.2.5-RC');
+const OUTPUT_DIR = join(process.cwd(), 'website/content/docs/schema-reference');
+
+// Field documentation metadata
+const FIELD_DOCS: Record<string, {
+  why: string;
+  how: string;
+  where: string;
+  examples: string[];
+  relatedFields: string[];
+  relatedDocs: string[];
+}> = {
+  'agent.id': {
+    why: 'Unique identifier for agent registration, API routing, and inter-agent communication',
+    how: 'Use DNS-1123 subdomain format: lowercase alphanumeric with hyphens, max 63 chars',
+    where: 'Used in API endpoints (/agents/{id}), Kubernetes resources, and registry URLs',
+    examples: [
+      'my-agent',
+      'data-processor-v2',
+      'compliance-checker-prod'
+    ],
+    relatedFields: ['agent.name', 'agent.version', 'agent.role'],
+    relatedDocs: ['../cli-reference/ossa-validate.md', '../api-reference/core-api.md']
+  },
+  'agent.name': {
+    why: 'Human-readable name for display in UIs and documentation',
+    how: 'Use descriptive names that clearly indicate the agent\'s purpose',
+    where: 'Displayed in agent lists, dashboards, and documentation',
+    examples: [
+      'Data Processing Agent',
+      'Compliance Checker',
+      'Customer Support Bot'
+    ],
+    relatedFields: ['agent.id', 'agent.description'],
+    relatedDocs: ['../guides/creating-agents.md']
+  },
+  'agent.version': {
+    why: 'Track agent versions for compatibility, rollback, and change management',
+    how: 'Use semantic versioning (MAJOR.MINOR.PATCH)',
+    where: 'Used in registry, deployment manifests, and API responses',
+    examples: [
+      '1.0.0',
+      '2.1.3',
+      '0.1.0-beta'
+    ],
+    relatedFields: ['agent.id', 'ossaVersion'],
+    relatedDocs: ['../guides/versioning.md']
+  },
+  'agent.role': {
+    why: 'Classify agents by their function in the system for routing and orchestration',
+    how: 'Choose from predefined roles or use custom roles',
+    where: 'Used for agent discovery, filtering, and orchestration patterns',
+    examples: [
+      'worker',
+      'orchestrator',
+      'compliance',
+      'monitor'
+    ],
+    relatedFields: ['agent.capabilities', 'agent.taxonomy'],
+    relatedDocs: ['../architecture/multi-agent-systems.md']
+  },
+  'agent.capabilities': {
+    why: 'Define what the agent can do, enabling capability-based routing and discovery',
+    how: 'List all capabilities with input/output schemas and descriptions',
+    where: 'Used by orchestrators to route tasks and by registry for discovery',
+    examples: [
+      'process_data',
+      'validate_compliance',
+      'generate_report'
+    ],
+    relatedFields: ['agent.tools', 'agent.role'],
+    relatedDocs: ['../guides/defining-capabilities.md']
+  }
+};
+
+function generateFieldDoc(fieldPath: string, property: SchemaProperty): string {
+  const metadata = FIELD_DOCS[fieldPath] || {
+    why: 'No documentation available',
+    how: 'No documentation available',
+    where: 'No documentation available',
+    examples: [],
+    relatedFields: [],
+    relatedDocs: []
+  };
+  
+  let doc = `# ${fieldPath}\n\n`;
+  
+  // Type and requirements
+  const typeStr = Array.isArray(property.type) ? property.type.join(' | ') : property.type;
+  doc += `**Type**: \`${typeStr}\`\n`;
+  doc += `**Required**: ${property.required ? 'Yes' : 'No'}\n`;
+  if (property.format) {
+    doc += `**Format**: ${property.format}\n`;
+  }
+  doc += '\n';
+  
+  // Description
+  if (property.description) {
+    doc += `## Description\n\n${property.description}\n\n`;
+  }
+  
+  // Why
+  doc += `## Why This Field Exists\n\n${metadata.why}\n\n`;
+  
+  // How
+  doc += `## How to Use\n\n${metadata.how}\n\n`;
+  
+  // Where
+  doc += `## Where It's Used\n\n${metadata.where}\n\n`;
+  
+  // Format requirements
+  if (property.pattern) {
+    doc += `## Format Requirements\n\n`;
+    doc += `Must match pattern: \`${property.pattern}\`\n\n`;
+  }
+  
+  if (property.enum) {
+    doc += `## Allowed Values\n\n`;
+    for (const value of property.enum) {
+      doc += `- \`${value}\`\n`;
+    }
+    doc += '\n';
+  }
+  
+  if (property.minimum !== undefined || property.maximum !== undefined) {
+    doc += `## Constraints\n\n`;
+    if (property.minimum !== undefined) {
+      doc += `- Minimum: ${property.minimum}\n`;
+    }
+    if (property.maximum !== undefined) {
+      doc += `- Maximum: ${property.maximum}\n`;
+    }
+    doc += '\n';
+  }
+  
+  if (property.minLength !== undefined || property.maxLength !== undefined) {
+    doc += `## Length Constraints\n\n`;
+    if (property.minLength !== undefined) {
+      doc += `- Minimum length: ${property.minLength}\n`;
+    }
+    if (property.maxLength !== undefined) {
+      doc += `- Maximum length: ${property.maxLength}\n`;
+    }
+    doc += '\n';
+  }
+  
+  // Examples
+  if (metadata.examples.length > 0) {
+    doc += `## Examples\n\n`;
+    for (const example of metadata.examples) {
+      doc += `\`\`\`yaml\n${fieldPath}: ${example}\n\`\`\`\n\n`;
+    }
+  }
+  
+  // Validation
+  doc += `## Validation\n\n`;
+  doc += `\`\`\`bash\nossa validate agent.ossa.yaml\n\`\`\`\n\n`;
+  
+  // Related fields
+  if (metadata.relatedFields.length > 0) {
+    doc += `## Related Fields\n\n`;
+    for (const field of metadata.relatedFields) {
+      const filename = field.replace(/\./g, '-') + '.md';
+      doc += `- [${field}](./${filename})\n`;
+    }
+    doc += '\n';
+  }
+  
+  // Related documentation
+  if (metadata.relatedDocs.length > 0) {
+    doc += `## Related Documentation\n\n`;
+    for (const docLink of metadata.relatedDocs) {
+      doc += `- [${docLink.split('/').pop()?.replace('.md', '')}](${docLink})\n`;
+    }
+    doc += '\n';
+  }
+  
+  return doc;
+}
+
+function main() {
+  console.log('🚀 Generating schema documentation...\n');
+  
+  // Create output directory
+  mkdirSync(OUTPUT_DIR, { recursive: true });
+  
+  // Read schema
+  const schemaPath = join(SPEC_DIR, 'ossa-0.2.5-RC.schema.json');
+  const schemaContent = readFileSync(schemaPath, 'utf-8');
+  const schema = JSON.parse(schemaContent);
+  
+  console.log(`📁 Processing schema fields...\n`);
+  
+  // Generate documentation for documented fields
+  let count = 0;
+  for (const [fieldPath, metadata] of Object.entries(FIELD_DOCS)) {
+    // Create a mock property for now (in real implementation, extract from schema)
+    const property: SchemaProperty = {
+      type: 'string',
+      description: `The ${fieldPath} field`,
+      required: true
+    };
+    
+    const docContent = generateFieldDoc(fieldPath, property);
+    const filename = fieldPath.replace(/\./g, '-') + '.md';
+    const outputFile = join(OUTPUT_DIR, filename);
+    
+    writeFileSync(outputFile, docContent);
+    console.log(`✅ Generated: ${filename}`);
+    count++;
+  }
+  
+  // Generate index
+  const indexContent = `# Schema Reference
+
+Complete reference for the OSSA agent manifest schema.
+
+## Overview
+
+The OSSA schema defines the structure of agent manifests. Every field serves a specific purpose in the agent lifecycle.
+
+## Core Fields
+
+### Agent Identification
+- [agent.id](./agent-id.md) - Unique agent identifier
+- [agent.name](./agent-name.md) - Human-readable name
+- [agent.version](./agent-version.md) - Semantic version
+- [agent.role](./agent-role.md) - Agent role classification
+
+### Agent Capabilities
+- [agent.capabilities](./agent-capabilities.md) - What the agent can do
+
+## Schema Versions
+
+- **Current**: v0.2.5-RC
+- **Stable**: v0.2.4
+- **Previous**: v0.2.3, v0.2.2
+
+See [Versioning Guide](../guides/versioning.md) for migration information.
+
+## Validation
+
+Validate your agent manifests:
+
+\`\`\`bash
+ossa validate agent.ossa.yaml
+\`\`\`
+
+## Complete Schema
+
+View the complete JSON Schema:
+- [v0.2.5-RC Schema](https://github.com/blueflyio/openstandardagents/blob/main/spec/v0.2.5-RC/ossa-0.2.5-RC.schema.json)
+
+## Related Documentation
+
+- [CLI Reference](../cli-reference/index.md)
+- [API Reference](../api-reference/index.md)
+- [Creating Agents Guide](../guides/creating-agents.md)
+`;
+  
+  writeFileSync(join(OUTPUT_DIR, 'index.md'), indexContent);
+  console.log(`✅ Generated: index.md`);
+  
+  console.log(`\n✨ Schema documentation generated successfully!`);
+  console.log(`📂 Output: ${OUTPUT_DIR}`);
+  console.log(`📊 Fields documented: ${count}`);
+}
+
+main();

package/scripts/generate-types-docs.ts

@@ -0,0 +1,48 @@
+#!/usr/bin/env tsx
+import { readFileSync, writeFileSync, mkdirSync } from 'fs';
+import { join } from 'path';
+
+const TYPES_FILE = join(process.cwd(), 'src/types/index.ts');
+const OUTPUT_FILE = join(process.cwd(), 'website/content/docs/types-reference/index.md');
+
+const content = readFileSync(TYPES_FILE, 'utf-8');
+
+// Extract interfaces and types
+const interfaces = content.match(/export interface \w+[^}]+}/gs) || [];
+const types = content.match(/export type \w+ = [^;]+;/gs) || [];
+
+let doc = `# TypeScript Types Reference
+
+Auto-generated from \`src/types/index.ts\`
+
+## Interfaces
+
+`;
+
+for (const iface of interfaces) {
+  const name = iface.match(/interface (\w+)/)?.[1];
+  if (name) {
+    doc += `### ${name}\n\n\`\`\`typescript\n${iface}\n\`\`\`\n\n`;
+  }
+}
+
+doc += `## Type Aliases\n\n`;
+
+for (const type of types) {
+  const name = type.match(/type (\w+)/)?.[1];
+  if (name) {
+    doc += `### ${name}\n\n\`\`\`typescript\n${type}\n\`\`\`\n\n`;
+  }
+}
+
+doc += `## Usage
+
+\`\`\`typescript
+import { OSSAManifest, AgentSpec } from '@bluefly/openstandardagents';
+\`\`\`
+`;
+
+mkdirSync(join(process.cwd(), 'website/content/docs/types-reference'), { recursive: true });
+writeFileSync(OUTPUT_FILE, doc);
+
+console.log(`✅ Generated types reference: ${interfaces.length} interfaces, ${types.length} types`);

package/scripts/lib/exec.ts

@@ -0,0 +1,37 @@
+/**
+ * Execution Utilities
+ * 
+ * DRY: Reusable command execution with proper error handling
+ * Type-safe: Validates commands and handles errors
+ */
+
+import { execSync } from 'child_process';
+import { z } from 'zod';
+
+const CommandSchema = z.string().min(1);
+
+interface ExecOptions {
+  encoding?: BufferEncoding;
+  stdio?: 'inherit' | 'pipe';
+}
+
+/**
+ * Execute command with validation and error handling
+ */
+export function execCommand(
+  command: string,
+  options: ExecOptions = {}
+): string {
+  const validatedCommand = CommandSchema.parse(command);
+  
+  try {
+    const result = execSync(validatedCommand, {
+      encoding: options.encoding || 'utf8',
+      stdio: options.stdio || 'pipe',
+    });
+    return result as string;
+  } catch (error: any) {
+    const message = error?.message || 'Command execution failed';
+    throw new Error(`Command failed: ${validatedCommand}\n${message}`);
+  }
+}