@bluefly/openstandardagents 0.2.8 → 0.3.0

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,99 +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');
-        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-llms-ctx.sh

@@ -1,17 +0,0 @@
-#!/bin/bash
-# Generate llms-ctx.txt files from llms.txt
-
-set -e
-
-echo "Installing llms-txt..."
-pip install llms-txt --quiet
-
-echo "Generating llms-ctx.txt (without Optional)..."
-llms_txt2ctx llms.txt -o llms-ctx.txt
-
-echo "Generating llms-ctx-full.txt (with Optional)..."
-llms_txt2ctx llms.txt -o llms-ctx-full.txt --include-optional
-
-echo "✅ Generated:"
-echo "  - llms-ctx.txt ($(wc -l < llms-ctx.txt) lines)"
-echo "  - llms-ctx-full.txt ($(wc -l < llms-ctx-full.txt) lines)"

package/scripts/generate-schema-docs.ts

@@ -1,317 +0,0 @@
-#!/usr/bin/env tsx
-/**
- * Generate schema documentation from JSON Schema
- * 
- * Usage: npm run docs:schema:generate
- */
-
-import { readFileSync, writeFileSync, mkdirSync, readdirSync } from 'fs';
-import { join, resolve } from 'path';
-
-// Dynamic version detection - find latest spec directory
-function getLatestSchemaVersion(): { dir: string; file: string } {
-  const specDir = join(process.cwd(), 'spec');
-  const dirs = readdirSync(specDir, { withFileTypes: true })
-    .filter(d => d.isDirectory() && d.name.startsWith('v'))
-    .map(d => d.name)
-    .sort((a, b) => b.localeCompare(a, undefined, { numeric: true }));
-
-  if (dirs.length === 0) {
-    throw new Error('No schema version directories found in spec/');
-  }
-
-  const latestDir = dirs[0];
-  const version = latestDir.slice(1); // Remove 'v' prefix
-  return {
-    dir: latestDir,
-    file: `ossa-${version}.schema.json`
-  };
-}
-
-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;
-}
-
-// Dynamic paths based on detected version
-const schemaVersion = getLatestSchemaVersion();
-const SPEC_DIR = join(process.cwd(), 'spec', schemaVersion.dir);
-const OUTPUT_DIR = join(process.cwd(), '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 dynamically
-  const schemaPath = join(SPEC_DIR, schemaVersion.file);
-  console.log(`📜 Using schema: ${schemaVersion.dir}/${schemaVersion.file}`);
-  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**: ${schemaVersion.dir}
-
-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:
-- [${schemaVersion.dir} Schema](https://github.com/blueflyio/openstandardagents/blob/main/spec/${schemaVersion.dir}/${schemaVersion.file})
-
-## 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

@@ -1,48 +0,0 @@
-#!/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`);