@bluefly/openstandardagents 0.3.2 → 0.3.3

package/openapi/dev-cli.openapi.yml

@@ -0,0 +1,867 @@
+openapi: 3.1.0
+info:
+  title: OSSA Developer CLI API
+  version: 1.0.0
+  description: |
+    Developer CLI for OSSA version management and spec generation.
+    **Separate from npm package** - Only for developers working on OSSA itself.
+    
+    Architecture:
+    - OpenAPI-First: This spec drives all CLI commands
+    - Zod Validation: All inputs/outputs validated with Zod schemas
+    - DRY: Single source of truth (.version.json)
+    - SOLID: Each command is a separate service
+
+servers:
+  - url: cli://ossa-dev
+    description: OSSA Developer CLI
+
+paths:
+  /version/release:
+    post:
+      operationId: versionRelease
+      summary: Release a new version (one command to release)
+      description: |
+        Bumps version, syncs all files, validates, and prepares for release.
+        This is the ONE command you need to release.
+      tags:
+        - Version Management
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/VersionReleaseRequest'
+      responses:
+        '200':
+          description: Release prepared successfully
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/VersionReleaseResponse'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '500':
+          $ref: '#/components/responses/InternalError'
+
+  /version/validate:
+    get:
+      operationId: versionValidate
+      summary: Validate version consistency
+      description: |
+        Validates that all version references are consistent.
+        Checks .version.json, package.json, and all files with {{VERSION}}.
+      tags:
+        - Version Management
+      responses:
+        '200':
+          description: Validation results
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/VersionValidateResponse'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+
+  /version/audit:
+    get:
+      operationId: versionAudit
+      summary: Audit for hardcoded versions
+      description: |
+        Finds all hardcoded versions (not using {{VERSION}} placeholder).
+        Returns list of files that need to be updated.
+      tags:
+        - Version Management
+      parameters:
+        - name: fix
+          in: query
+          schema:
+            type: boolean
+            default: false
+          description: Automatically replace hardcoded versions with {{VERSION}}
+      responses:
+        '200':
+          description: Audit results
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/VersionAuditResponse'
+
+  /version/sync:
+    post:
+      operationId: versionSync
+      summary: Sync {{VERSION}} placeholders
+      description: |
+        Replaces {{VERSION}} placeholders with actual version from .version.json.
+        Used during build/CI.
+      tags:
+        - Version Management
+      requestBody:
+        required: false
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/VersionSyncRequest'
+      responses:
+        '200':
+          description: Sync complete
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/VersionSyncResponse'
+
+  /spec/generate:
+    post:
+      operationId: specGenerate
+      summary: Generate spec from source (for CI)
+      description: |
+        Generates OSSA spec from source files.
+        **This prevents local AI bots from breaking the spec.**
+        CI always generates spec from source, never uses local files.
+      tags:
+        - Spec Generation
+      requestBody:
+        required: false
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/SpecGenerateRequest'
+      responses:
+        '200':
+          description: Spec generated successfully
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/SpecGenerateResponse'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '500':
+          $ref: '#/components/responses/InternalError'
+
+  /spec/validate:
+    post:
+      operationId: specValidate
+      summary: Validate generated spec
+      description: |
+        Validates generated spec against OpenAPI schema.
+        Ensures spec is valid before committing.
+      tags:
+        - Spec Generation
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/SpecValidateRequest'
+      responses:
+        '200':
+          description: Validation results
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/SpecValidateResponse'
+
+  /workflow/release:
+    get:
+      operationId: workflowRelease
+      summary: Show release workflow
+      description: |
+        Displays step-by-step release workflow guide.
+      tags:
+        - Workflow Help
+      responses:
+        '200':
+          description: Workflow guide
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/WorkflowResponse'
+
+  /workflow/validate:
+    get:
+      operationId: workflowValidate
+      summary: Show validation workflow
+      description: |
+        Displays step-by-step validation workflow guide.
+      tags:
+        - Workflow Help
+      responses:
+        '200':
+          description: Workflow guide
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/WorkflowResponse'
+
+  /release/verify:
+    post:
+      operationId: releaseVerify
+      summary: Verify release readiness
+      description: |
+        Validates repository state, versions, tags, and CI configuration
+        before any release operations. This is a CRUD Read operation - it
+        validates state but does not modify anything.
+      tags:
+        - Release Management
+      requestBody:
+        required: false
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/ReleaseVerifyRequest'
+      responses:
+        '200':
+          description: Verification results
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ReleaseVerifyResponse'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '500':
+          $ref: '#/components/responses/InternalError'
+
+  /release/prep:
+    post:
+      operationId: releasePrep
+      summary: Prepare release - comprehensive validation
+      description: |
+        Comprehensive pre-release validation for GitLab, GitHub, and npmjs.
+        Validates all platforms before release. This is a CRUD Read operation.
+      tags:
+        - Release Management
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/ReleasePrepRequest'
+      responses:
+        '200':
+          description: Preparation results
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ReleasePrepResponse'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '500':
+          $ref: '#/components/responses/InternalError'
+
+components:
+  schemas:
+    VersionReleaseRequest:
+      type: object
+      required:
+        - bumpType
+      properties:
+        bumpType:
+          type: string
+          enum: [patch, minor, major]
+          description: Version bump type
+        dryRun:
+          type: boolean
+          default: false
+          description: Dry run mode (don't actually change files)
+        skipValidation:
+          type: boolean
+          default: false
+          description: Skip validation after bump
+
+    VersionReleaseResponse:
+      type: object
+      required:
+        - success
+        - oldVersion
+        - newVersion
+        - changes
+      properties:
+        success:
+          type: boolean
+        oldVersion:
+          type: string
+        newVersion:
+          type: string
+        changes:
+          type: array
+          items:
+            type: string
+          description: List of files changed
+        nextSteps:
+          type: array
+          items:
+            type: string
+          description: Next steps for release
+
+    VersionValidateResponse:
+      type: object
+      required:
+        - valid
+        - errors
+        - warnings
+      properties:
+        valid:
+          type: boolean
+        errors:
+          type: array
+          items:
+            type: string
+        warnings:
+          type: array
+          items:
+            type: string
+        details:
+          type: object
+          additionalProperties:
+            type: string
+
+    VersionAuditResponse:
+      type: object
+      required:
+        - files
+        - total
+      properties:
+        files:
+          type: array
+          items:
+            $ref: '#/components/schemas/HardcodedVersionFile'
+        total:
+          type: integer
+        fixed:
+          type: integer
+          description: Number of files fixed (if fix=true)
+
+    HardcodedVersionFile:
+      type: object
+      required:
+        - path
+        - line
+        - content
+        - suggested
+      properties:
+        path:
+          type: string
+        line:
+          type: integer
+        content:
+          type: string
+          description: Line with hardcoded version
+        suggested:
+          type: string
+          description: Suggested replacement with {{VERSION}}
+
+    VersionSyncRequest:
+      type: object
+      properties:
+        version:
+          type: string
+          description: Version to use (defaults to .version.json)
+        files:
+          type: array
+          items:
+            type: string
+          description: Specific files to sync (defaults to all)
+
+    VersionSyncResponse:
+      type: object
+      required:
+        - success
+        - filesUpdated
+      properties:
+        success:
+          type: boolean
+        filesUpdated:
+          type: integer
+        files:
+          type: array
+          items:
+            type: string
+
+    SpecGenerateRequest:
+      type: object
+      properties:
+        outputDir:
+          type: string
+          default: spec/
+          description: Output directory for generated spec
+        validate:
+          type: boolean
+          default: true
+          description: Validate generated spec
+
+    SpecGenerateResponse:
+      type: object
+      required:
+        - success
+        - outputPath
+      properties:
+        success:
+          type: boolean
+        outputPath:
+          type: string
+        filesGenerated:
+          type: array
+          items:
+            type: string
+        validation:
+          $ref: '#/components/schemas/SpecValidationResult'
+
+    SpecValidateRequest:
+      type: object
+      required:
+        - specPath
+      properties:
+        specPath:
+          type: string
+          description: Path to spec file to validate
+
+    SpecValidateResponse:
+      type: object
+      required:
+        - valid
+        - errors
+      properties:
+        valid:
+          type: boolean
+        errors:
+          type: array
+          items:
+            type: string
+        warnings:
+          type: array
+          items:
+            type: string
+
+    SpecValidationResult:
+      type: object
+      required:
+        - valid
+        - errors
+      properties:
+        valid:
+          type: boolean
+        errors:
+          type: array
+          items:
+            type: string
+
+    WorkflowResponse:
+      type: object
+      required:
+        - steps
+      properties:
+        steps:
+          type: array
+          items:
+            type: object
+            required:
+              - number
+              - description
+              - command
+            properties:
+              number:
+                type: integer
+              description:
+                type: string
+              command:
+                type: string
+              optional:
+                type: boolean
+                default: false
+
+    ReleaseVerifyRequest:
+      type: object
+      properties:
+        version:
+          type: string
+          description: Version to verify (defaults to current version)
+        skipBuildTests:
+          type: boolean
+          default: false
+          description: Skip build and test validation
+        skipCIConfig:
+          type: boolean
+          default: false
+          description: Skip CI configuration validation
+
+    ReleaseVerifyResponse:
+      type: object
+      required:
+        - ready
+        - version
+        - versionTag
+        - repository
+        - versionState
+        - tagState
+        - errors
+        - warnings
+        - nextSteps
+      properties:
+        ready:
+          type: boolean
+          description: Whether repository is ready for release
+        version:
+          type: string
+          description: Current version from .version.json
+        versionTag:
+          type: string
+          description: Version tag (e.g., v0.3.3)
+        repository:
+          $ref: '#/components/schemas/RepositoryState'
+        versionState:
+          $ref: '#/components/schemas/VersionState'
+        tagState:
+          $ref: '#/components/schemas/TagState'
+        ciConfig:
+          $ref: '#/components/schemas/CIConfigState'
+          description: CI configuration state (optional if skipCIConfig=true)
+        errors:
+          type: array
+          items:
+            type: string
+          description: List of errors preventing release
+        warnings:
+          type: array
+          items:
+            type: string
+          description: List of warnings (non-blocking)
+        nextSteps:
+          type: array
+          items:
+            type: string
+          description: Next steps to complete release
+
+    RepositoryState:
+      type: object
+      required:
+        - remoteUrl
+        - currentBranch
+        - isClean
+        - checks
+      properties:
+        remoteUrl:
+          type: string
+        currentBranch:
+          type: string
+        isClean:
+          type: boolean
+        checks:
+          type: array
+          items:
+            $ref: '#/components/schemas/RepositoryCheck'
+
+    RepositoryCheck:
+      type: object
+      required:
+        - name
+        - passed
+        - message
+      properties:
+        name:
+          type: string
+        passed:
+          type: boolean
+        message:
+          type: string
+
+    VersionState:
+      type: object
+      required:
+        - versionFromJson
+        - packageVersion
+        - versionTag
+        - isSynced
+        - checks
+      properties:
+        versionFromJson:
+          type: string
+        packageVersion:
+          type: string
+        versionTag:
+          type: string
+        isSynced:
+          type: boolean
+        checks:
+          type: array
+          items:
+            $ref: '#/components/schemas/RepositoryCheck'
+
+    TagState:
+      type: object
+      required:
+        - versionTag
+        - stableTagExists
+        - rcTags
+        - devTags
+        - checks
+      properties:
+        versionTag:
+          type: string
+        stableTagExists:
+          type: boolean
+        rcTags:
+          type: array
+          items:
+            type: string
+        devTags:
+          type: array
+          items:
+            type: string
+        checks:
+          type: array
+          items:
+            $ref: '#/components/schemas/RepositoryCheck'
+
+    CIConfigState:
+      type: object
+      required:
+        - files
+        - checks
+      properties:
+        files:
+          type: array
+          items:
+            $ref: '#/components/schemas/CIConfigCheck'
+        checks:
+          type: array
+          items:
+            $ref: '#/components/schemas/RepositoryCheck'
+
+    CIConfigCheck:
+      type: object
+      required:
+        - filePath
+        - exists
+      properties:
+        filePath:
+          type: string
+        exists:
+          type: boolean
+        hasFastGate:
+          type: boolean
+        hasFullGate:
+          type: boolean
+        checks:
+          type: array
+          items:
+            $ref: '#/components/schemas/RepositoryCheck'
+
+    ReleasePrepRequest:
+      type: object
+      required:
+        - version
+      properties:
+        version:
+          type: string
+          description: Version to prepare (e.g., 0.3.3)
+        dryRun:
+          type: boolean
+          default: false
+          description: Dry run mode (validate only, no changes)
+        skipGitHub:
+          type: boolean
+          default: false
+          description: Skip GitHub validation
+        skipNPM:
+          type: boolean
+          default: false
+          description: Skip NPM validation
+
+    ReleasePrepResponse:
+      type: object
+      required:
+        - ready
+        - version
+        - versionTag
+        - gitlab
+        - allErrors
+        - allWarnings
+        - checklist
+        - nextSteps
+        - rollbackPlan
+      properties:
+        ready:
+          type: boolean
+          description: Whether release is ready
+        version:
+          type: string
+        versionTag:
+          type: string
+        gitlab:
+          $ref: '#/components/schemas/GitLabValidation'
+        github:
+          $ref: '#/components/schemas/GitHubValidation'
+        npm:
+          $ref: '#/components/schemas/NPMValidation'
+        allErrors:
+          type: array
+          items:
+            type: string
+        allWarnings:
+          type: array
+          items:
+            type: string
+        checklist:
+          type: array
+          items:
+            $ref: '#/components/schemas/ChecklistItem'
+        nextSteps:
+          type: array
+          items:
+            type: string
+        rollbackPlan:
+          type: array
+          items:
+            type: string
+
+    GitLabValidation:
+      type: object
+      required:
+        - ready
+        - remoteUrl
+        - branch
+        - tagExists
+        - tagCanBeCreated
+        - releaseCanBeCreated
+        - protectedTagRules
+        - ciTokenConfigured
+        - errors
+        - warnings
+      properties:
+        ready:
+          type: boolean
+        remoteUrl:
+          type: string
+        branch:
+          type: string
+        tagExists:
+          type: boolean
+        tagCanBeCreated:
+          type: boolean
+        releaseCanBeCreated:
+          type: boolean
+        protectedTagRules:
+          type: object
+          properties:
+            pattern:
+              type: string
+            allowed:
+              type: boolean
+        ciTokenConfigured:
+          type: boolean
+        errors:
+          type: array
+          items:
+            type: string
+        warnings:
+          type: array
+          items:
+            type: string
+
+    GitHubValidation:
+      type: object
+      required:
+        - ready
+        - remoteConfigured
+        - mirrorEnabled
+        - tokenConfigured
+        - releaseCanBeCreated
+        - errors
+        - warnings
+      properties:
+        ready:
+          type: boolean
+        remoteConfigured:
+          type: boolean
+        mirrorEnabled:
+          type: boolean
+        tokenConfigured:
+          type: boolean
+        releaseCanBeCreated:
+          type: boolean
+        errors:
+          type: array
+          items:
+            type: string
+        warnings:
+          type: array
+          items:
+            type: string
+
+    NPMValidation:
+      type: object
+      required:
+        - ready
+        - versionExists
+        - canPublish
+        - tokenConfigured
+        - registryAccessible
+        - packageName
+        - errors
+        - warnings
+      properties:
+        ready:
+          type: boolean
+        versionExists:
+          type: boolean
+        canPublish:
+          type: boolean
+        tokenConfigured:
+          type: boolean
+        registryAccessible:
+          type: boolean
+        packageName:
+          type: string
+        currentPublishedVersion:
+          type: string
+        errors:
+          type: array
+          items:
+            type: string
+        warnings:
+          type: array
+          items:
+            type: string
+
+    ChecklistItem:
+      type: object
+      required:
+        - category
+        - item
+        - status
+        - message
+      properties:
+        category:
+          type: string
+        item:
+          type: string
+        status:
+          type: string
+          enum: [pass, fail, warning, skip]
+        message:
+          type: string
+
+  responses:
+    BadRequest:
+      description: Bad request
+      content:
+        application/json:
+          schema:
+            type: object
+            properties:
+              error:
+                type: string
+              details:
+                type: object
+
+    InternalError:
+      description: Internal server error
+      content:
+        application/json:
+          schema:
+            type: object
+            properties:
+              error:
+                type: string
+              details:
+                type: object