@bluefly/openstandardagents 0.3.5 → 0.3.6

package/examples/validation/error-codes-demo.ts

@@ -0,0 +1,254 @@
+/**
+ * OSSA Error Code Catalog - Demo
+ *
+ * Demonstrates how to use error codes for validation and debugging
+ */
+
+import {
+  EnhancedOSSAValidator,
+  OSSAErrorCode,
+  getErrorDetails,
+  searchErrorsByTag,
+  searchErrorsBySeverity,
+} from '../../src/validation';
+import { writeFileSync } from 'fs';
+import { join } from 'path';
+
+// Example 1: Validate with error codes
+function validateWithErrorCodes() {
+  console.log('=== Example 1: Validate with Error Codes ===\n');
+
+  const invalidManifest = {
+    kind: 'Agent', // Missing apiVersion (OSSA-001)
+    metadata: {
+      name: 'My_Agent', // Invalid DNS format (OSSA-800)
+      decentralized_identity: {
+        did: 'did:key:abc123', // Wrong DID method (OSSA-100)
+      },
+    },
+    // Missing spec (OSSA-005)
+  };
+
+  const validator = new EnhancedOSSAValidator();
+  const result = validator.validate(invalidManifest);
+
+  console.log('Valid:', result.valid);
+  console.log('Total Issues:', result.report.summary.total);
+  console.log('Errors:', result.report.summary.errorCount);
+  console.log('\nFormatted Output:\n');
+  console.log(result.formatted.text);
+  console.log('\n');
+}
+
+// Example 2: Handle specific error codes
+function handleSpecificErrors() {
+  console.log('=== Example 2: Handle Specific Errors ===\n');
+
+  const manifest = {
+    apiVersion: 'ossa/v0.3.6',
+    kind: 'Agent',
+    metadata: {
+      name: 'security-scanner',
+      decentralized_identity: {
+        did: 'did:ossa:INVALID_UPPERCASE', // Invalid (uppercase)
+      },
+      genetics: {
+        generation: 1,
+        // Missing parent_dids (OSSA-201)
+      },
+    },
+    spec: {
+      type: 'analyzer',
+    },
+  };
+
+  const validator = new EnhancedOSSAValidator();
+  const result = validator.validate(manifest);
+
+  if (!result.valid) {
+    result.report.errors.forEach((error) => {
+      console.log(`Error Code: ${error.code}`);
+      console.log(`Path: ${error.path}`);
+      console.log(`Message: ${error.message}`);
+
+      // Handle specific errors
+      switch (error.code) {
+        case OSSAErrorCode.OSSA_100:
+          console.log('🔧 Fix: Use lowercase in DID');
+          console.log('   did: "did:ossa:invalid_uppercase" → did: "did:ossa:invaliduppercase"');
+          break;
+        case OSSAErrorCode.OSSA_201:
+          console.log('🔧 Fix: Add parent DIDs for generation 1');
+          console.log('   Add: "parent_dids": ["did:ossa:parent1", "did:ossa:parent2"]');
+          break;
+        default:
+          console.log(`🔧 Fix: ${error.remediation}`);
+      }
+
+      console.log(`📚 Docs: ${error.docsUrl}`);
+      console.log('---\n');
+    });
+  }
+}
+
+// Example 3: Search and filter errors
+function searchAndFilter() {
+  console.log('=== Example 3: Search and Filter Errors ===\n');
+
+  // Find all DID-related errors
+  const didErrors = searchErrorsByTag('did');
+  console.log(`DID-related errors: ${didErrors.length}`);
+  didErrors.forEach((error) => {
+    console.log(`  - ${error.code}: ${error.message}`);
+  });
+  console.log('');
+
+  // Find all critical errors
+  const criticalErrors = searchErrorsBySeverity('error');
+  console.log(`Critical errors in catalog: ${criticalErrors.length}`);
+  console.log('');
+
+  // Find genetics errors
+  const geneticsErrors = searchErrorsByTag('genetics');
+  console.log(`Genetics errors: ${geneticsErrors.length}`);
+  geneticsErrors.slice(0, 5).forEach((error) => {
+    console.log(`  - ${error.code}: ${error.message}`);
+  });
+  console.log('');
+}
+
+// Example 4: Get error details
+function getErrorInfo() {
+  console.log('=== Example 4: Get Error Details ===\n');
+
+  const details = getErrorDetails(OSSAErrorCode.OSSA_001);
+
+  console.log(`Code: ${details!.code}`);
+  console.log(`Severity: ${details!.severity}`);
+  console.log(`Message: ${details!.message}`);
+  console.log(`Remediation: ${details!.remediation}`);
+  console.log(`Docs: ${details!.docsUrl}`);
+  console.log(`Tags: ${details!.tags?.join(', ')}`);
+
+  if (details!.examples && details!.examples.length > 0) {
+    console.log('\nExamples:');
+    details!.examples.forEach((example, i) => {
+      console.log(`\n  Example ${i + 1}: ${example.title}`);
+      console.log(`  Invalid: ${example.invalid}`);
+      console.log(`  Valid: ${example.valid}`);
+      console.log(`  Why: ${example.explanation}`);
+    });
+  }
+  console.log('');
+}
+
+// Example 5: Export multiple formats
+function exportFormats() {
+  console.log('=== Example 5: Export Multiple Formats ===\n');
+
+  const manifest = {
+    apiVersion: 'ossa/v0.3.6',
+    kind: 'Agent',
+    metadata: {
+      name: 'test-agent',
+    },
+    // Missing spec
+  };
+
+  const validator = new EnhancedOSSAValidator();
+  const result = validator.validate(manifest);
+
+  // Export JSON
+  const jsonPath = join(__dirname, 'validation-report.json');
+  writeFileSync(jsonPath, result.formatted.json);
+  console.log(`✅ Exported JSON: ${jsonPath}`);
+
+  // Export Markdown
+  const mdPath = join(__dirname, 'validation-report.md');
+  writeFileSync(mdPath, result.formatted.markdown);
+  console.log(`✅ Exported Markdown: ${mdPath}`);
+
+  // Export HTML
+  const htmlPath = join(__dirname, 'validation-report.html');
+  writeFileSync(htmlPath, result.formatted.html);
+  console.log(`✅ Exported HTML: ${htmlPath}`);
+
+  console.log('\n');
+}
+
+// Example 6: Validate file
+function validateFile() {
+  console.log('=== Example 6: Validate File ===\n');
+
+  const validator = new EnhancedOSSAValidator();
+
+  try {
+    // Create test manifest
+    const testManifest = {
+      apiVersion: 'ossa/v0.3.6',
+      kind: 'Agent',
+      metadata: {
+        name: 'file-test-agent',
+        taxonomy: {
+          domain: 'security',
+          subdomain: 'auth',
+        },
+        access_tier: {
+          tier: 'tier_1_read',
+          permissions: ['read_code', 'read_configs'],
+        },
+      },
+      spec: {
+        type: 'analyzer',
+        model: {
+          provider: 'anthropic',
+          name: 'claude-3-5-sonnet-20241022',
+        },
+      },
+    };
+
+    const testPath = join(__dirname, 'test-manifest.json');
+    writeFileSync(testPath, JSON.stringify(testManifest, null, 2));
+
+    // Validate
+    const result = validator.validateFile(testPath);
+
+    console.log(`File: ${testPath}`);
+    console.log(`Valid: ${result.valid}`);
+    console.log(`Issues: ${result.report.summary.total}`);
+
+    if (result.valid) {
+      console.log('✅ Manifest is valid!');
+    } else {
+      console.log('\nIssues found:');
+      console.log(result.formatted.text);
+    }
+  } catch (error) {
+    console.error('Error:', error);
+  }
+
+  console.log('');
+}
+
+// Run all examples
+async function main() {
+  console.clear();
+  console.log('╔═══════════════════════════════════════════════╗');
+  console.log('║  OSSA Error Code Catalog - Demo              ║');
+  console.log('║  Production-Quality Error Handling           ║');
+  console.log('╚═══════════════════════════════════════════════╝\n');
+
+  validateWithErrorCodes();
+  handleSpecificErrors();
+  searchAndFilter();
+  getErrorInfo();
+  exportFormats();
+  validateFile();
+
+  console.log('╔═══════════════════════════════════════════════╗');
+  console.log('║  Demo Complete                                ║');
+  console.log('║  Check generated files in examples/validation ║');
+  console.log('╚═══════════════════════════════════════════════╝');
+}
+
+main().catch(console.error);

package/examples/workflows/batch-email-campaign.yaml

@@ -1,6 +1,6 @@
 # Example: Batch Email Campaign Workflow
 # Demonstrates loops, parallel execution, and batch processing
-apiVersion: ossa/v0.3.5
+apiVersion: ossa/v0.3.6
 kind: Workflow
 metadata:
   name: batch-email-campaign

package/examples/workflows/content-review-publish.yaml

@@ -1,6 +1,6 @@
 # Example: Content Review and Publish Workflow
 # Demonstrates mixed Task + Agent composition
-apiVersion: ossa/v0.3.5
+apiVersion: ossa/v0.3.6
 kind: Workflow
 metadata:
   name: content-review-publish

package/examples/workflows/simple-etl.yaml

@@ -1,6 +1,6 @@
 # Example: Simple ETL Workflow
 # Demonstrates sequential Tasks with data transformation
-apiVersion: ossa/v0.3.5
+apiVersion: ossa/v0.3.6
 kind: Workflow
 metadata:
   name: simple-etl

package/openapi/agents-md-service.yaml

@@ -0,0 +1,338 @@
+openapi: 3.1.0
+info:
+  title: OSSA AGENTS.md Generation Service
+  description: Service for generating and managing agents.md documentation files for repositories.
+  version: 1.0.0
+
+servers:
+  - url: /api/v1/agents-md
+    description: v1 API root
+
+paths:
+  /generate:
+    post:
+      summary: Generate AGENTS.md for a repository
+      operationId: generateAgentsMd
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+                - repo_path
+              properties:
+                repo_path:
+                  type: string
+                  description: Path to the repository (bare or worktree)
+                branch:
+                  type: string
+                  default: main
+                template_overrides:
+                  type: object
+                  additionalProperties: true
+                auto_commit:
+                  type: boolean
+                  default: false
+                auto_push:
+                  type: boolean
+                  default: false
+      responses:
+        '200':
+          description: Successfully generated AGENTS.md
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/GenerationResult'
+        '400':
+          description: Invalid request
+        '500':
+          description: Internal server error
+
+  /batch:
+    post:
+      summary: Batch generate AGENTS.md for multiple repositories
+      operationId: batchGenerateAgentsMd
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+                - repos
+              properties:
+                repos:
+                  type: array
+                  items:
+                    $ref: '#/components/schemas/RepoConfig'
+                parallel:
+                  type: boolean
+                  default: true
+      responses:
+        '200':
+          description: Batch generation completed
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  results:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/GenerationResult'
+                  summary:
+                    type: object
+                    properties:
+                      total:
+                        type: integer
+                      success:
+                        type: integer
+                      failed:
+                        type: integer
+
+  /:
+    get:
+      summary: List all repositories with AGENTS.md status
+      operationId: listReposStatus
+      parameters:
+        - name: filter
+          in: query
+          schema:
+            type: string
+            enum: [has_agents_md, missing_agents_md, all]
+            default: all
+      responses:
+        '200':
+          description: List of repository statuses
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  repos:
+                    type: array
+                    items:
+                      type: object
+                      properties:
+                        repo_id:
+                          type: string
+                        exists:
+                          type: boolean
+                        last_updated:
+                          type: string
+                          format: date-time
+                        validates:
+                          type: boolean
+
+  /{repoId}:
+    parameters:
+      - name: repoId
+        in: path
+        required: true
+        schema:
+          type: string
+    get:
+      summary: Get AGENTS.md status for a repository
+      operationId: getRepoStatus
+      responses:
+        '200':
+          description: Repository AGENTS.md status
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  exists:
+                    type: boolean
+                  content:
+                    type: string
+                  last_updated:
+                    type: string
+                    format: date-time
+                  validates:
+                    type: boolean
+        '404':
+          description: Repository not found
+    put:
+      summary: Regenerate or update AGENTS.md for a repository
+      operationId: updateAgentsMd
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                template_overrides:
+                  type: object
+                auto_commit:
+                  type: boolean
+                  default: false
+      responses:
+        '200':
+          description: Successfully updated AGENTS.md
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  content:
+                    type: string
+                  diff:
+                    type: string
+                  commit_sha:
+                    type: string
+    delete:
+      summary: Remove AGENTS.md from a repository
+      operationId: deleteAgentsMd
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                auto_commit:
+                  type: boolean
+                  default: false
+      responses:
+        '200':
+          description: Successfully deleted AGENTS.md
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  status:
+                    type: string
+                    enum: [success, failure]
+                  commit_sha:
+                    type: string
+
+  /template:
+    get:
+      summary: Get current AGENTS.md template
+      operationId: getTemplate
+      responses:
+        '200':
+          description: Current template content and variables
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  template:
+                    type: string
+                  variables:
+                    type: array
+                    items:
+                      type: string
+    put:
+      summary: Update AGENTS.md template
+      operationId: updateTemplate
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+                - template
+              properties:
+                template:
+                  type: string
+      responses:
+        '200':
+          description: Template updated successfully
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  status:
+                    type: string
+                    enum: [success, failure]
+                  validation:
+                    $ref: '#/components/schemas/ValidationResult'
+
+components:
+  schemas:
+    RepoConfig:
+      type: object
+      required:
+        - repo_path
+      properties:
+        repo_path:
+          type: string
+          example: /Volumes/AgentPlatform/repos/bare/blueflyio/agent-protocol.git
+        branch:
+          type: string
+          example: main
+        project_name:
+          type: string
+        project_type:
+          type: string
+        description:
+          type: string
+        gitlab_url:
+          type: string
+        wiki_url:
+          type: string
+
+    GenerationResult:
+      type: object
+      required:
+        - repo_path
+        - status
+        - content
+        - validation
+      properties:
+        repo_path:
+          type: string
+        status:
+          type: string
+          enum: [success, failed]
+        content:
+          type: string
+        commit_sha:
+          type: string
+        validation:
+          $ref: '#/components/schemas/ValidationResult'
+        error:
+          type: string
+
+    ValidationResult:
+      type: object
+      required:
+        - valid
+        - follows_standard
+      properties:
+        valid:
+          type: boolean
+        follows_standard:
+          type: boolean
+        errors:
+          type: array
+          items:
+            type: string
+        warnings:
+          type: array
+          items:
+            type: string
+
+    TemplateVariables:
+      type: object
+      properties:
+        PROJECT_NAME:
+          type: string
+        PROJECT_DESCRIPTION:
+          type: string
+        REPO_URL:
+          type: string
+        REPO_PATH:
+          type: string
+        PROJECT_TYPE:
+          type: string
+        PROJECT_STATUS:
+          type: string
+        WIKI_URL:
+          type: string

package/openapi/cli-commands.openapi.yaml

@@ -1407,31 +1407,3 @@ x-ossa-metadata:
     approved: true
     approvedBy: OSSA Standards Team
     approvalDate: 2026-01-09
-  cli_mapping:
-    validate: POST /cli/validate
-    lint: POST /cli/lint
-    diff: POST /cli/diff
-    export: POST /cli/export
-    import: POST /cli/import
-    init: POST /cli/init
-    generate: POST /cli/generate
-    migrate: POST /cli/migrate
-    agents_list: GET /cli/agents
-    agents_create: POST /cli/agents
-    agents_get: GET /cli/agents/{name}
-    agents_update: PUT /cli/agents/{name}
-    agents_delete: DELETE /cli/agents/{name}
-    publish: POST /cli/registry/publish
-    search: GET /cli/registry/search
-    install: POST /cli/registry/install
-    info: GET /cli/registry/info/{name}
-    schema: GET /cli/schema
-    test: POST /cli/test
-    deploy: POST /cli/deploy
-    run: POST /cli/run
-    status: GET /cli/status
-    stop: POST /cli/stop
-    rollback: POST /cli/rollback
-    llms_txt_generate: POST /cli/llms-txt/generate
-    llms_txt_validate: POST /cli/llms-txt/validate
-    llms_txt_sync: POST /cli/llms-txt/sync