@bluefly/openstandardagents 0.2.5-RC → 0.2.7

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/lowercase-docs.ts

@@ -0,0 +1,43 @@
+#!/usr/bin/env tsx
+/**
+ * Convert all documentation filenames to lowercase
+ */
+
+import { readdirSync, renameSync, statSync } from 'fs';
+import { join, basename, dirname } from 'path';
+
+const DOCS_DIR = join(process.cwd(), 'website/content/docs');
+
+function lowercaseFiles(dir: string) {
+  const entries = readdirSync(dir);
+  
+  for (const entry of entries) {
+    const fullPath = join(dir, entry);
+    const stat = statSync(fullPath);
+    
+    if (stat.isDirectory()) {
+      // Recursively process subdirectories
+      lowercaseFiles(fullPath);
+      
+      // Rename directory if needed
+      const lowerEntry = entry.toLowerCase();
+      if (entry !== lowerEntry) {
+        const newPath = join(dirname(fullPath), lowerEntry);
+        console.log(`📁 Renaming: ${entry} → ${lowerEntry}`);
+        renameSync(fullPath, newPath);
+      }
+    } else if (entry.endsWith('.md')) {
+      // Rename file if needed
+      const lowerEntry = entry.toLowerCase();
+      if (entry !== lowerEntry) {
+        const newPath = join(dirname(fullPath), lowerEntry);
+        console.log(`📄 Renaming: ${entry} → ${lowerEntry}`);
+        renameSync(fullPath, newPath);
+      }
+    }
+  }
+}
+
+console.log('🔄 Converting documentation filenames to lowercase...\n');
+lowercaseFiles(DOCS_DIR);
+console.log('\n✅ Done!');

package/scripts/manage-milestone-mrs.ts

@@ -0,0 +1,279 @@
+#!/usr/bin/env tsx
+/**
+ * Manage Merge Requests for a specific milestone
+ * Helps clean up and organize MRs for controlled releases
+ */
+
+import { Gitlab } from '@gitbeaker/node';
+import { Command } from 'commander';
+
+const gitlab = new Gitlab({
+  token: process.env.GITLAB_TOKEN || process.env.GITLAB_ACCESS_TOKEN,
+  host: 'https://gitlab.com',
+});
+
+const PROJECT_ID = '76265294'; // blueflyio/openstandardagents
+
+interface MRInfo {
+  iid: number;
+  title: string;
+  state: string;
+  target_branch: string;
+  source_branch: string;
+  milestone?: { title: string };
+  has_conflicts: boolean;
+  merge_status: string;
+  web_url: string;
+}
+
+async function listMRsInMilestone(milestone: string) {
+  console.log(`\n📋 Listing MRs in milestone: ${milestone}\n`);
+
+  const mrs = await gitlab.MergeRequests.all({
+    projectId: PROJECT_ID,
+    state: 'opened',
+    milestone,
+  });
+
+  if (mrs.length === 0) {
+    console.log('No open MRs found in this milestone.');
+    return;
+  }
+
+  console.log(`Found ${mrs.length} open MRs:\n`);
+
+  for (const mr of mrs) {
+    const status = mr.has_conflicts ? '❌ CONFLICTS' : '✅ Clean';
+    const target = mr.target_branch === 'development' ? '✅ dev' : `⚠️  ${mr.target_branch}`;
+    
+    console.log(`!${mr.iid}: ${mr.title}`);
+    console.log(`   Target: ${target} | Status: ${status}`);
+    console.log(`   ${mr.web_url}\n`);
+  }
+}
+
+async function listMRsNotInMilestone(milestone: string) {
+  console.log(`\n📋 Listing open MRs NOT in milestone: ${milestone}\n`);
+
+  const allMRs = await gitlab.MergeRequests.all({
+    projectId: PROJECT_ID,
+    state: 'opened',
+  });
+
+  const outsideMRs = allMRs.filter(
+    (mr: any) => !mr.milestone || mr.milestone.title !== milestone
+  );
+
+  if (outsideMRs.length === 0) {
+    console.log('All open MRs are in the milestone.');
+    return;
+  }
+
+  console.log(`Found ${outsideMRs.length} MRs outside milestone:\n`);
+
+  for (const mr of outsideMRs) {
+    const milestoneText = mr.milestone ? mr.milestone.title : 'No milestone';
+    console.log(`!${mr.iid}: ${mr.title}`);
+    console.log(`   Milestone: ${milestoneText}`);
+    console.log(`   Target: ${mr.target_branch}`);
+    console.log(`   ${mr.web_url}\n`);
+  }
+}
+
+async function retargetMR(mrId: number, targetBranch: string) {
+  console.log(`\n🎯 Retargeting MR !${mrId} to ${targetBranch}...\n`);
+
+  try {
+    await gitlab.MergeRequests.edit(PROJECT_ID, mrId, {
+      target_branch: targetBranch,
+    });
+
+    console.log(`✅ Successfully retargeted MR !${mrId} to ${targetBranch}`);
+  } catch (error: any) {
+    console.error(`❌ Failed to retarget MR: ${error.message}`);
+    process.exit(1);
+  }
+}
+
+async function closeMR(mrId: number, reason: string) {
+  console.log(`\n🚫 Closing MR !${mrId}...\n`);
+
+  try {
+    // Add comment explaining closure
+    await gitlab.MergeRequestNotes.create(PROJECT_ID, mrId, {
+      body: `Closing this MR: ${reason}\n\nIf this work is still needed, please rebase and assign to the appropriate milestone.`,
+    });
+
+    // Close the MR
+    await gitlab.MergeRequests.edit(PROJECT_ID, mrId, {
+      state_event: 'close',
+    });
+
+    console.log(`✅ Successfully closed MR !${mrId}`);
+  } catch (error: any) {
+    console.error(`❌ Failed to close MR: ${error.message}`);
+    process.exit(1);
+  }
+}
+
+async function rebaseMR(mrId: number) {
+  console.log(`\n🔄 Rebasing MR !${mrId}...\n`);
+
+  try {
+    await gitlab.MergeRequests.rebase(PROJECT_ID, mrId);
+    console.log(`✅ Rebase initiated for MR !${mrId}`);
+    console.log('   Check the MR page for rebase status.');
+  } catch (error: any) {
+    console.error(`❌ Failed to rebase MR: ${error.message}`);
+    process.exit(1);
+  }
+}
+
+async function assignMilestone(mrId: number, milestone: string) {
+  console.log(`\n🏷️  Assigning MR !${mrId} to milestone ${milestone}...\n`);
+
+  try {
+    // Get milestone ID
+    const milestones = await gitlab.ProjectMilestones.all(PROJECT_ID);
+    const targetMilestone = milestones.find((m: any) => m.title === milestone);
+
+    if (!targetMilestone) {
+      throw new Error(`Milestone "${milestone}" not found`);
+    }
+
+    await gitlab.MergeRequests.edit(PROJECT_ID, mrId, {
+      milestone_id: targetMilestone.id,
+    });
+
+    console.log(`✅ Successfully assigned MR !${mrId} to milestone ${milestone}`);
+  } catch (error: any) {
+    console.error(`❌ Failed to assign milestone: ${error.message}`);
+    process.exit(1);
+  }
+}
+
+async function bulkRetarget(milestone: string, targetBranch: string) {
+  console.log(`\n🎯 Bulk retargeting all MRs in ${milestone} to ${targetBranch}...\n`);
+
+  const mrs = await gitlab.MergeRequests.all({
+    projectId: PROJECT_ID,
+    state: 'opened',
+    milestone,
+  });
+
+  console.log(`Found ${mrs.length} MRs to retarget\n`);
+
+  for (const mr of mrs) {
+    if (mr.target_branch !== targetBranch) {
+      console.log(`Retargeting !${mr.iid}: ${mr.title}`);
+      await retargetMR(mr.iid, targetBranch);
+    } else {
+      console.log(`Skipping !${mr.iid}: already targets ${targetBranch}`);
+    }
+  }
+
+  console.log(`\n✅ Bulk retarget complete`);
+}
+
+async function bulkRebase(milestone: string) {
+  console.log(`\n🔄 Bulk rebasing all MRs in ${milestone}...\n`);
+
+  const mrs = await gitlab.MergeRequests.all({
+    projectId: PROJECT_ID,
+    state: 'opened',
+    milestone,
+  });
+
+  console.log(`Found ${mrs.length} MRs to rebase\n`);
+
+  for (const mr of mrs) {
+    if (mr.has_conflicts) {
+      console.log(`Rebasing !${mr.iid}: ${mr.title} (has conflicts)`);
+      await rebaseMR(mr.iid);
+      // Wait a bit between rebases
+      await new Promise((resolve) => setTimeout(resolve, 2000));
+    } else {
+      console.log(`Skipping !${mr.iid}: no conflicts`);
+    }
+  }
+
+  console.log(`\n✅ Bulk rebase complete`);
+}
+
+// CLI
+const program = new Command();
+
+program
+  .name('manage-milestone-mrs')
+  .description('Manage merge requests for milestone-based releases')
+  .version('1.0.0');
+
+program
+  .command('list')
+  .description('List all MRs in a milestone')
+  .requiredOption('-m, --milestone <milestone>', 'Milestone name (e.g., v0.2.6)')
+  .action(async (options) => {
+    await listMRsInMilestone(options.milestone);
+  });
+
+program
+  .command('list-outside')
+  .description('List all MRs NOT in a milestone')
+  .requiredOption('-m, --milestone <milestone>', 'Milestone name (e.g., v0.2.6)')
+  .action(async (options) => {
+    await listMRsNotInMilestone(options.milestone);
+  });
+
+program
+  .command('retarget')
+  .description('Retarget an MR to a different branch')
+  .requiredOption('-i, --id <id>', 'MR ID (e.g., 123)')
+  .requiredOption('-t, --target <branch>', 'Target branch (e.g., development)')
+  .action(async (options) => {
+    await retargetMR(parseInt(options.id), options.target);
+  });
+
+program
+  .command('close')
+  .description('Close an MR with a reason')
+  .requiredOption('-i, --id <id>', 'MR ID (e.g., 123)')
+  .requiredOption('-r, --reason <reason>', 'Reason for closing')
+  .action(async (options) => {
+    await closeMR(parseInt(options.id), options.reason);
+  });
+
+program
+  .command('rebase')
+  .description('Rebase an MR')
+  .requiredOption('-i, --id <id>', 'MR ID (e.g., 123)')
+  .action(async (options) => {
+    await rebaseMR(parseInt(options.id));
+  });
+
+program
+  .command('assign')
+  .description('Assign an MR to a milestone')
+  .requiredOption('-i, --id <id>', 'MR ID (e.g., 123)')
+  .requiredOption('-m, --milestone <milestone>', 'Milestone name (e.g., v0.2.6)')
+  .action(async (options) => {
+    await assignMilestone(parseInt(options.id), options.milestone);
+  });
+
+program
+  .command('bulk-retarget')
+  .description('Retarget all MRs in a milestone to a branch')
+  .requiredOption('-m, --milestone <milestone>', 'Milestone name (e.g., v0.2.6)')
+  .requiredOption('-t, --target <branch>', 'Target branch (e.g., development)')
+  .action(async (options) => {
+    await bulkRetarget(options.milestone, options.target);
+  });
+
+program
+  .command('bulk-rebase')
+  .description('Rebase all MRs with conflicts in a milestone')
+  .requiredOption('-m, --milestone <milestone>', 'Milestone name (e.g., v0.2.6)')
+  .action(async (options) => {
+    await bulkRebase(options.milestone);
+  });
+
+program.parse();