@bluefly/openstandardagents 0.3.5 → 0.4.0

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 → cli/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

package/openapi/{dev-cli.openapi.yml → dev-cli/openapi.yaml}

@@ -50,7 +50,7 @@ paths:
       summary: Validate version consistency
       description: |
         Validates that all version references are consistent.
-        Checks .version.json, package.json, and all files with {{VERSION}}.
+        Checks .version.json, package.json, and all files with 0.3.6.
       tags:
         - Version Management
       responses:
@@ -68,7 +68,7 @@ paths:
       operationId: versionAudit
       summary: Audit for hardcoded versions
       description: |
-        Finds all hardcoded versions (not using {{VERSION}} placeholder).
+        Finds all hardcoded versions (not using 0.3.6 placeholder).
         Returns list of files that need to be updated.
       tags:
         - Version Management
@@ -78,7 +78,7 @@ paths:
           schema:
             type: boolean
             default: false
-          description: Automatically replace hardcoded versions with {{VERSION}}
+          description: Automatically replace hardcoded versions with 0.3.6
       responses:
         '200':
           description: Audit results
@@ -87,12 +87,50 @@ paths:
               schema:
                 $ref: '#/components/schemas/VersionAuditResponse'
 
+  /version/status:
+    get:
+      operationId: versionStatus
+      summary: Get version status and health
+      description: |
+        Shows comprehensive version status including:
+        - Current version from .version.json
+        - Git tag status
+        - Package.json version
+        - Schema files status
+        - Placeholder usage statistics
+      tags:
+        - Version Management
+      responses:
+        '200':
+          description: Version status
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/VersionStatusResponse'
+
+  /version/check:
+    get:
+      operationId: versionCheck
+      summary: Quick version consistency check
+      description: |
+        Fast check for version consistency across critical files.
+        Returns OK/WARN/ERROR status.
+      tags:
+        - Version Management
+      responses:
+        '200':
+          description: Check results
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/VersionCheckResponse'
+
   /version/sync:
     post:
       operationId: versionSync
-      summary: Sync {{VERSION}} placeholders
+      summary: Sync 0.3.6 placeholders
       description: |
-        Replaces {{VERSION}} placeholders with actual version from .version.json.
+        Replaces 0.3.6 placeholders with actual version from .version.json.
         Used during build/CI.
       tags:
         - Version Management
@@ -348,7 +386,70 @@ components:
           description: Line with hardcoded version
         suggested:
           type: string
-          description: Suggested replacement with {{VERSION}}
+          description: Suggested replacement with 0.3.6
+
+    VersionStatusResponse:
+      type: object
+      required:
+        - current
+        - packageJson
+        - gitTag
+        - schemaExists
+        - placeholderStats
+      properties:
+        current:
+          type: string
+          description: Current version from .version.json
+        packageJson:
+          type: string
+          description: Version from package.json
+        gitTag:
+          type: string
+          description: Latest git tag
+        schemaExists:
+          type: boolean
+          description: Whether schema files exist for current version
+        specPath:
+          type: string
+          description: Path to spec directory
+        schemaFile:
+          type: string
+          description: Schema filename
+        placeholderStats:
+          type: object
+          properties:
+            total:
+              type: integer
+              description: Total files with placeholders
+            hardcoded:
+              type: integer
+              description: Files with hardcoded versions
+        health:
+          type: string
+          enum: [healthy, warning, error]
+          description: Overall version health status
+
+    VersionCheckResponse:
+      type: object
+      required:
+        - status
+        - consistent
+      properties:
+        status:
+          type: string
+          enum: [OK, WARN, ERROR]
+          description: Check status
+        consistent:
+          type: boolean
+          description: Whether versions are consistent
+        issues:
+          type: array
+          items:
+            type: string
+          description: List of consistency issues
+        message:
+          type: string
+          description: Human-readable status message
 
     VersionSyncRequest:
       type: object