@bluefly/openstandardagents 0.4.8 → 0.5.0

package/openapi/version-management.openapi.yaml

@@ -13,20 +13,17 @@ info:
     - Post-release: Replace `v0.4.2` → `{{VERSION}}`
     - CI/CD: Automate version substitution in pipelines
     - Multi-project: Apply consistent versioning across repositories
-
   contact:
     name: OSSA Community
     url: https://openstandardagents.org
   license:
     name: Apache 2.0
     url: https://www.apache.org/licenses/LICENSE-2.0.html
-
 servers:
   - url: http://localhost:3000/api/v1
     description: Local development
   - url: https://api.openstandardagents.org/v1
     description: Production
-
 tags:
   - name: version
     description: Version substitution and management operations
@@ -34,7 +31,6 @@ tags:
     description: Version detection from project sources
   - name: validation
     description: Version format validation
-
 paths:
   /version/substitute:
     post:
@@ -53,7 +49,6 @@ paths:
         **Example:**
         - Input: `apiVersion: ossa/v{{VERSION}}`
         - Output: `apiVersion: ossa/v0.4.2`
-
       tags:
         - version
       requestBody:
@@ -61,81 +56,84 @@ paths:
         content:
           application/json:
             schema:
-              $ref: '#/components/schemas/SubstituteRequest'
+              $ref: "#/components/schemas/SubstituteRequest"
             examples:
               basic:
                 summary: Basic substitution
                 value:
-                  version: "0.4.2"
+                  version: 0.4.2
               with_prefix:
                 summary: Version with 'v' prefix
                 value:
-                  version: "v0.4.2"
+                  version: v0.4.2
               custom_paths:
                 summary: Custom file patterns
                 value:
-                  version: "0.4.2"
+                  version: 0.4.2
                   paths:
-                    - "spec/**/*.json"
-                    - "docs/**/*.md"
+                    - spec/**/*.json
+                    - docs/**/*.md
                   exclude:
-                    - "node_modules/**"
-                    - ".git/**"
+                    - node_modules/**
+                    - .git/**
               dry_run:
                 summary: Preview changes without modifying files
                 value:
-                  version: "0.4.2"
+                  version: 0.4.2
                   dry_run: true
       responses:
-        '200':
+        "200":
           description: Substitution completed successfully
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/SubstituteResponse'
+                $ref: "#/components/schemas/SubstituteResponse"
               examples:
                 success:
                   summary: Successful substitution
                   value:
                     success: true
-                    version_used: "v0.4.2"
+                    version_used: v0.4.2
                     files_processed: 42
                     replacements_made: 156
                     files:
-                      - path: "spec/v0.4/agent.schema.json"
+                      - path: spec/v0.4/agent.schema.json
                         replacements: 8
-                      - path: "docs/roadmap/phase-1-specification.md"
+                      - path: docs/roadmap/phase-1-specification.md
                         replacements: 3
                 dry_run:
                   summary: Dry run result
                   value:
                     success: true
-                    version_used: "v0.4.2"
+                    version_used: v0.4.2
                     files_processed: 42
                     replacements_made: 156
                     dry_run: true
-                    message: "Dry run completed. No files were modified."
-        '400':
+                    message: Dry run completed. No files were modified.
+        "400":
           description: Invalid request
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/ErrorResponse'
+                $ref: "#/components/schemas/ErrorResponse"
               examples:
                 invalid_version:
                   summary: Invalid version format
                   value:
                     success: false
-                    error: "Invalid version format"
-                    message: "Version must be in semver format (e.g., '0.4.2' or 'v0.4.2')"
-                    code: "INVALID_VERSION_FORMAT"
-        '500':
+                    error: Invalid version format
+                    message: Version must be in semver format (e.g., '0.4.2' or 'v0.4.2')
+                    code: INVALID_VERSION_FORMAT
+        "500":
           description: Server error
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/ErrorResponse'
-
+                $ref: "#/components/schemas/ErrorResponse"
+      x-ossa-capability: version-substitute-version
+      x-ossa-autonomy:
+        level: supervised
+        approval_required: true
   /version/restore:
     post:
       operationId: restoreVersion
@@ -152,7 +150,6 @@ paths:
         1. Scan files for the specified version
         2. Replace version occurrences with `{{VERSION}}`
         3. Report restorations made
-
       tags:
         - version
       requestBody:
@@ -160,36 +157,39 @@ paths:
         content:
           application/json:
             schema:
-              $ref: '#/components/schemas/RestoreRequest'
+              $ref: "#/components/schemas/RestoreRequest"
             examples:
               basic:
                 summary: Basic restoration
                 value:
-                  version: "0.4.2"
+                  version: 0.4.2
               all_versions:
                 summary: Restore all versions to placeholder
                 value:
                   restore_all: true
       responses:
-        '200':
+        "200":
           description: Restoration completed successfully
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/RestoreResponse'
-        '400':
+                $ref: "#/components/schemas/RestoreResponse"
+        "400":
           description: Invalid request
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/ErrorResponse'
-        '500':
+                $ref: "#/components/schemas/ErrorResponse"
+        "500":
           description: Server error
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/ErrorResponse'
-
+                $ref: "#/components/schemas/ErrorResponse"
+      x-ossa-capability: version-restore-version
+      x-ossa-autonomy:
+        level: supervised
+        approval_required: true
   /version/detect:
     get:
       operationId: detectVersion
@@ -208,7 +208,6 @@ paths:
         - Detected version
         - Source where version was found
         - All available versions from all sources
-
       tags:
         - detection
       parameters:
@@ -218,53 +217,53 @@ paths:
           required: false
           schema:
             type: string
-            default: "."
+            default: .
       responses:
-        '200':
+        "200":
           description: Version detected successfully
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/DetectResponse'
+                $ref: "#/components/schemas/DetectResponse"
               examples:
                 from_git:
                   summary: Version detected from git tag
                   value:
                     success: true
-                    version: "v0.4.2"
-                    source: "git_tag"
+                    version: v0.4.2
+                    source: git_tag
                     all_sources:
-                      git_tag: "v0.4.2"
-                      package_json: "0.4.1"
+                      git_tag: v0.4.2
+                      package_json: 0.4.1
                 from_package:
                   summary: Version detected from package.json
                   value:
                     success: true
-                    version: "0.4.2"
-                    source: "package_json"
+                    version: 0.4.2
+                    source: package_json
                     all_sources:
-                      package_json: "0.4.2"
-        '404':
+                      package_json: 0.4.2
+        "404":
           description: No version found
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/ErrorResponse'
+                $ref: "#/components/schemas/ErrorResponse"
               examples:
                 not_found:
                   summary: No version detected
                   value:
                     success: false
-                    error: "Version not found"
-                    message: "Could not detect version from any source"
-                    code: "VERSION_NOT_FOUND"
-        '500':
+                    error: Version not found
+                    message: Could not detect version from any source
+                    code: VERSION_NOT_FOUND
+        "500":
           description: Server error
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/ErrorResponse'
-
+                $ref: "#/components/schemas/ErrorResponse"
+      x-ossa-capability: version-detect-version
   /version/validate:
     post:
       operationId: validateVersion
@@ -282,7 +281,6 @@ paths:
         - `0.4` (missing patch)
         - `v0.4.2.1` (too many segments)
         - `latest` (not semver)
-
       tags:
         - validation
       requestBody:
@@ -290,30 +288,30 @@ paths:
         content:
           application/json:
             schema:
-              $ref: '#/components/schemas/ValidateRequest'
+              $ref: "#/components/schemas/ValidateRequest"
             examples:
               valid:
                 summary: Valid version
                 value:
-                  version: "0.4.2"
+                  version: 0.4.2
               invalid:
                 summary: Invalid version
                 value:
                   version: "0.4"
       responses:
-        '200':
+        "200":
           description: Validation result
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/ValidateResponse'
+                $ref: "#/components/schemas/ValidateResponse"
               examples:
                 valid:
                   summary: Version is valid
                   value:
                     success: true
                     valid: true
-                    version: "0.4.2"
+                    version: 0.4.2
                     parsed:
                       major: 0
                       minor: 4
@@ -327,14 +325,17 @@ paths:
                     valid: false
                     version: "0.4"
                     errors:
-                      - "Missing patch version"
-        '400':
+                      - Missing patch version
+        "400":
           description: Invalid request
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/ErrorResponse'
-
+                $ref: "#/components/schemas/ErrorResponse"
+      x-ossa-capability: version-validate-version
+      x-ossa-autonomy:
+        level: supervised
+        approval_required: true
   /version/bump:
     post:
       operationId: bumpVersion
@@ -347,7 +348,6 @@ paths:
         - `minor`: 0.4.2 → 0.5.0
         - `patch`: 0.4.2 → 0.4.3
         - `prerelease`: 0.4.2 → 0.4.3-alpha.1
-
       tags:
         - version
       requestBody:
@@ -355,38 +355,41 @@ paths:
         content:
           application/json:
             schema:
-              $ref: '#/components/schemas/BumpRequest'
+              $ref: "#/components/schemas/BumpRequest"
             examples:
               patch:
                 summary: Bump patch version
                 value:
-                  version: "0.4.2"
-                  bump_type: "patch"
+                  version: 0.4.2
+                  bump_type: patch
               minor:
                 summary: Bump minor version
                 value:
-                  version: "0.4.2"
-                  bump_type: "minor"
+                  version: 0.4.2
+                  bump_type: minor
               prerelease:
                 summary: Bump to prerelease
                 value:
-                  version: "0.4.2"
-                  bump_type: "prerelease"
-                  prerelease_identifier: "alpha"
+                  version: 0.4.2
+                  bump_type: prerelease
+                  prerelease_identifier: alpha
       responses:
-        '200':
+        "200":
           description: Version bumped successfully
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/BumpResponse'
-        '400':
+                $ref: "#/components/schemas/BumpResponse"
+        "400":
           description: Invalid request
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/ErrorResponse'
-
+                $ref: "#/components/schemas/ErrorResponse"
+      x-ossa-capability: version-bump-version
+      x-ossa-autonomy:
+        level: supervised
+        approval_required: true
 components:
   schemas:
     SubstituteRequest:
@@ -396,9 +399,9 @@ components:
       properties:
         version:
           type: string
-          pattern: '^v?\d+\.\d+\.\d+(-[a-zA-Z0-9.]+)?(\+[a-zA-Z0-9.]+)?$'
+          pattern: ^v?\d+\.\d+\.\d+(-[a-zA-Z0-9.]+)?(\+[a-zA-Z0-9.]+)?$
           description: Semantic version to substitute (with or without 'v' prefix)
-          example: "0.4.2"
+          example: 0.4.2
         paths:
           type: array
           items:
@@ -410,22 +413,22 @@ components:
             - "**/*.yaml"
             - "**/*.yml"
           example:
-            - "spec/**/*.json"
-            - "docs/**/*.md"
+            - spec/**/*.json
+            - docs/**/*.md
         exclude:
           type: array
           items:
             type: string
           description: Glob patterns for files to exclude
           default:
-            - "node_modules/**"
-            - ".git/**"
-            - "vendor/**"
-            - "dist/**"
-            - "build/**"
+            - node_modules/**
+            - .git/**
+            - vendor/**
+            - dist/**
+            - build/**
           example:
-            - "node_modules/**"
-            - ".git/**"
+            - node_modules/**
+            - .git/**
         dry_run:
           type: boolean
           default: false
@@ -435,7 +438,6 @@ components:
           default: "{{VERSION}}"
           description: Custom placeholder pattern to replace
           example: "{{VERSION}}"
-
     SubstituteResponse:
       type: object
       required:
@@ -450,7 +452,7 @@ components:
         version_used:
           type: string
           description: The version that was substituted
-          example: "v0.4.2"
+          example: v0.4.2
         files_processed:
           type: integer
           description: Number of files scanned
@@ -465,7 +467,7 @@ components:
         message:
           type: string
           description: Human-readable result message
-          example: "Successfully replaced 156 occurrences in 42 files"
+          example: Successfully replaced 156 occurrences in 42 files
         files:
           type: array
           description: Details of each file processed
@@ -478,7 +480,7 @@ components:
               path:
                 type: string
                 description: Relative path to file
-                example: "spec/v0.4/agent.schema.json"
+                example: spec/v0.4/agent.schema.json
               replacements:
                 type: integer
                 description: Number of replacements in this file
@@ -495,15 +497,14 @@ components:
                       type: string
                     after:
                       type: string
-
     RestoreRequest:
       type: object
       properties:
         version:
           type: string
-          pattern: '^v?\d+\.\d+\.\d+(-[a-zA-Z0-9.]+)?(\+[a-zA-Z0-9.]+)?$'
+          pattern: ^v?\d+\.\d+\.\d+(-[a-zA-Z0-9.]+)?(\+[a-zA-Z0-9.]+)?$
           description: Specific version to restore to placeholder
-          example: "0.4.2"
+          example: 0.4.2
         restore_all:
           type: boolean
           default: false
@@ -523,9 +524,10 @@ components:
           default: "{{VERSION}}"
           description: Placeholder pattern to restore
       oneOf:
-        - required: [version]
-        - required: [restore_all]
-
+        - required:
+            - version
+        - required:
+            - restore_all
     RestoreResponse:
       type: object
       required:
@@ -538,7 +540,7 @@ components:
         version_restored:
           type: string
           description: The version that was restored to placeholder
-          example: "v0.4.2"
+          example: v0.4.2
         files_processed:
           type: integer
           example: 42
@@ -547,7 +549,7 @@ components:
           example: 156
         message:
           type: string
-          example: "Successfully restored 156 occurrences to {{VERSION}} in 42 files"
+          example: Successfully restored 156 occurrences to {{VERSION}} in 42 files
         files:
           type: array
           items:
@@ -557,15 +559,14 @@ components:
                 type: string
               replacements:
                 type: integer
-
     DetectRequest:
       type: object
       properties:
         directory:
           type: string
-          default: "."
+          default: .
           description: Directory to search for version sources
-          example: "/path/to/project"
+          example: /path/to/project
         sources:
           type: array
           items:
@@ -578,7 +579,6 @@ components:
               - pyproject_toml
               - cargo_toml
           description: Specific sources to check (checks all by default)
-
     DetectResponse:
       type: object
       required:
@@ -591,7 +591,7 @@ components:
         version:
           type: string
           description: Detected version
-          example: "v0.4.2"
+          example: v0.4.2
         source:
           type: string
           enum:
@@ -602,16 +602,15 @@ components:
             - pyproject_toml
             - cargo_toml
           description: Source where version was found
-          example: "git_tag"
+          example: git_tag
         all_sources:
           type: object
           description: All versions found from all sources
           additionalProperties:
             type: string
           example:
-            git_tag: "v0.4.2"
-            package_json: "0.4.1"
-
+            git_tag: v0.4.2
+            package_json: 0.4.1
     ValidateRequest:
       type: object
       required:
@@ -620,8 +619,7 @@ components:
         version:
           type: string
           description: Version string to validate
-          example: "0.4.2"
-
+          example: 0.4.2
     ValidateResponse:
       type: object
       required:
@@ -653,17 +651,16 @@ components:
             prerelease:
               type: string
               nullable: true
-              example: "alpha.1"
+              example: alpha.1
             build:
               type: string
               nullable: true
-              example: "build.123"
+              example: build.123
         errors:
           type: array
           items:
             type: string
           description: Validation errors (if invalid)
-
     BumpRequest:
       type: object
       required:
@@ -672,9 +669,9 @@ components:
       properties:
         version:
           type: string
-          pattern: '^v?\d+\.\d+\.\d+(-[a-zA-Z0-9.]+)?(\+[a-zA-Z0-9.]+)?$'
+          pattern: ^v?\d+\.\d+\.\d+(-[a-zA-Z0-9.]+)?(\+[a-zA-Z0-9.]+)?$
           description: Current version
-          example: "0.4.2"
+          example: 0.4.2
         bump_type:
           type: string
           enum:
@@ -683,12 +680,11 @@ components:
             - patch
             - prerelease
           description: Type of version bump
-          example: "patch"
+          example: patch
         prerelease_identifier:
           type: string
           description: Identifier for prerelease (e.g., 'alpha', 'beta', 'rc')
-          example: "alpha"
-
+          example: alpha
     BumpResponse:
       type: object
       required:
@@ -701,11 +697,11 @@ components:
         old_version:
           type: string
           description: Original version
-          example: "0.4.2"
+          example: 0.4.2
         new_version:
           type: string
           description: Bumped version
-          example: "0.4.3"
+          example: 0.4.3
         bump_type:
           type: string
           enum:
@@ -713,8 +709,7 @@ components:
             - minor
             - patch
             - prerelease
-          example: "patch"
-
+          example: patch
     ErrorResponse:
       type: object
       required:
@@ -724,31 +719,43 @@ components:
       properties:
         success:
           type: boolean
-          enum: [false]
+          enum:
+            - false
         error:
           type: string
           description: Error type
-          example: "Invalid version format"
+          example: Invalid version format
         message:
           type: string
           description: Human-readable error message
-          example: "Version must be in semver format (e.g., '0.4.2' or 'v0.4.2')"
+          example: Version must be in semver format (e.g., '0.4.2' or 'v0.4.2')
         code:
           type: string
           description: Machine-readable error code
-          example: "INVALID_VERSION_FORMAT"
+          example: INVALID_VERSION_FORMAT
         details:
           type: object
           description: Additional error details
           additionalProperties: true
-
   securitySchemes:
     apiKey:
       type: apiKey
       in: header
       name: X-API-Key
       description: API key for authentication (if required)
-
 security:
   - apiKey: []
-  - {}  # Allow unauthenticated access for local use
+  - {}
+x-ossa-metadata:
+  version: 1.0.0
+  compliance:
+    level: standard
+  observability:
+    tracing: true
+    metrics: true
+    logging: true
+x-ossa:
+  version: 0.5.0
+  agent:
+    id: version-management-api
+    type: worker