@bluefly/openstandardagents 0.3.5 → 0.3.6

package/openapi/ossa-cli-enhancements.openapi.yaml

@@ -0,0 +1,148 @@
+openapi: 3.1.0
+info:
+  title: OSSA CLI Enhancements API
+  version: 1.0.0
+  description: |
+    OpenAPI specification for OSSA CLI enhancement commands:
+    - Knowledge base generation
+    - Agent enhancement
+    - Context enrichment
+    - Learning & feedback loops
+    - Real example generation
+    
+    FOLLOWS DRY PRINCIPLE: Single source of truth for all CLI command schemas.
+  contact:
+    name: OSSA Standards Team
+    email: ossa@bluefly.io
+  license:
+    name: Apache-2.0
+    url: https://www.apache.org/licenses/LICENSE-2.0.html
+
+servers:
+  - url: http://localhost:4000/api/v1
+    description: Local development server
+  - url: https://api.blueflyagents.com/api/v1
+    description: Production API server
+
+tags:
+  - name: knowledge
+    description: Knowledge base generation and management
+  - name: enhancement
+    description: Agent enhancement operations
+  - name: examples
+    description: Real example generation
+
+paths:
+  /knowledge/generate:
+    post:
+      operationId: generateKnowledgeBase
+      summary: Generate knowledge base from codebase
+      tags:
+        - knowledge
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+                - agentName
+                - sourcePath
+              properties:
+                agentName:
+                  type: string
+                  example: code-quality-reviewer
+                sourcePath:
+                  type: string
+                  example: ~/Sites/blueflyio/compliance-engine
+                patterns:
+                  type: array
+                  items:
+                    type: string
+                  example: ["typescript", "react", "drupal"]
+                outputPath:
+                  type: string
+                syncBrain:
+                  type: boolean
+                  default: false
+      responses:
+        '200':
+          description: Knowledge base generated successfully
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  success:
+                    type: boolean
+                  knowledgeBase:
+                    type: object
+                    properties:
+                      patterns:
+                        type: array
+                        items:
+                          type: string
+                      examples:
+                        type: integer
+                      contextFiles:
+                        type: integer
+                  outputPath:
+                    type: string
+
+  /enhance/agent:
+    post:
+      operationId: enhanceAgent
+      summary: Enhance existing agent
+      tags:
+        - enhancement
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+                - agentName
+              properties:
+                agentName:
+                  type: string
+                capabilities:
+                  type: array
+                  items:
+                    type: string
+                promptsFromCodebase:
+                  type: boolean
+                tools:
+                  type: array
+                  items:
+                    type: string
+      responses:
+        '200':
+          description: Agent enhanced successfully
+
+  /examples/generate:
+    post:
+      operationId: generateExamples
+      summary: Generate real examples from codebase
+      tags:
+        - examples
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+                - agentName
+              properties:
+                agentName:
+                  type: string
+                sourcePath:
+                  type: string
+                gitlabIssues:
+                  type: boolean
+                gitlabMRs:
+                  type: boolean
+      responses:
+        '200':
+          description: Examples generated successfully

package/openapi/release-automation.openapi.yaml

@@ -0,0 +1,144 @@
+openapi: 3.1.0
+info:
+  title: Release Automation API
+  version: 1.0.0
+  description: |
+    OpenAPI specification for agent-based release automation.
+    Integrates semantic-release, Keep a Changelog format, and agent orchestration.
+    
+    FOLLOWS DRY PRINCIPLE: Single source of truth for release automation schemas.
+  contact:
+    name: OSSA Release Team
+    email: release@bluefly.io
+  license:
+    name: Apache-2.0
+    url: https://www.apache.org/licenses/LICENSE-2.0.html
+
+servers:
+  - url: http://localhost:4000/api/v1
+    description: Local development server
+  - url: https://api.blueflyagents.com/api/v1
+    description: Production API server
+
+tags:
+  - name: release
+    description: Release orchestration and automation
+  - name: changelog
+    description: Changelog generation and management
+  - name: version
+    description: Version management and validation
+
+paths:
+  /release/analyze:
+    post:
+      operationId: analyzeRelease
+      summary: Analyze commits and determine release type
+      tags:
+        - release
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+                - branch
+              properties:
+                branch:
+                  type: string
+                  example: release/v0.3.x
+                fromTag:
+                  type: string
+                  example: v0.3.6
+                toCommit:
+                  type: string
+                  example: HEAD
+                dryRun:
+                  type: boolean
+                  default: false
+      responses:
+        '200':
+          description: Release analysis complete
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  releaseNeeded:
+                    type: boolean
+                  releaseType:
+                    type: string
+                    enum: [major, minor, patch, prerelease]
+                  currentVersion:
+                    type: string
+                  nextVersion:
+                    type: string
+
+  /release/execute:
+    post:
+      operationId: executeRelease
+      summary: Execute full release workflow via agent orchestration
+      tags:
+        - release
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+                - branch
+              properties:
+                branch:
+                  type: string
+                dryRun:
+                  type: boolean
+                  default: false
+      responses:
+        '200':
+          description: Release executed successfully
+
+  /changelog/generate:
+    post:
+      operationId: generateChangelog
+      summary: Generate changelog following Keep a Changelog format
+      tags:
+        - changelog
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+                - version
+              properties:
+                version:
+                  type: string
+                format:
+                  type: string
+                  enum: [keepachangelog, markdown, json]
+                  default: keepachangelog
+      responses:
+        '200':
+          description: Changelog generated successfully
+
+  /changelog/validate:
+    post:
+      operationId: validateChangelog
+      summary: Validate changelog follows Keep a Changelog format
+      tags:
+        - changelog
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                changelogPath:
+                  type: string
+                  default: CHANGELOG.md
+      responses:
+        '200':
+          description: Changelog validation result

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bluefly/openstandardagents",
-  "version": "0.3.5",
+  "version": "0.3.6",
   "exports": {
     "./schema": "./spec/v{{VERSION}}/ossa-{{VERSION}}.schema.json",
     "./schema/v0.3.3": "./spec/v{{VERSION}}/ossa-{{VERSION}}.schema.json",
@@ -53,6 +53,11 @@
       "types": "./dist/mesh/index.d.ts",
       "import": "./dist/mesh/index.js",
       "require": "./dist/mesh/index.js"
+    },
+    "./audit": {
+      "types": "./dist/services/audit.d.ts",
+      "import": "./dist/services/audit.js",
+      "require": "./dist/services/audit.js"
     }
   },
   "description": "OSSA - Open Standard for Software Agents. The OpenAPI for agents. A specification standard (not a framework) that defines contracts/metadata for production agent systems.",
@@ -76,6 +81,7 @@
     "README.md",
     "LICENSE",
     "CHANGELOG.md",
+    ".version.json",
     ".env.local",
     ".devfile.yaml",
     ".wiki-config.json",
@@ -85,12 +91,12 @@
     "llms-ctx.txt"
   ],
   "publishConfig": {
-    "access": "public",
-    "registry": "https://registry.npmjs.org/"
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/blueflyio/openstandardagents/"
+    "url": "https://gitlab.com/blueflyio/ossa/openstandardagents.git"
   },
   "bugs": {
     "url": "https://github.com/blueflyio/openstandardagents/issues"
@@ -100,7 +106,7 @@
     "// ─────────────────────────────────────────────────────────────────────────────": "",
     "// BUILD & DEVELOPMENT": "",
     "prebuild": "npm run docs:process",
-    "build": "tsc && npm run build:assets",
+    "build": "tsc && tsx src/tools/fix-esm-imports.ts && npm run build:assets",
     "build:assets": "cp -r spec dist/",
     "build:clean": "npm run clean && npm run build",
     "dev": "tsc --watch",
@@ -135,9 +141,9 @@
     "validate:sdks": "npm run validate:sdk:typescript && npm run validate:sdk:python",
     "validate:sdk:typescript": "cd src/sdks/typescript && npm install && npm run build && npm run typecheck",
     "validate:sdk:python": "cd src/sdks/python && python -m pip install --quiet -e . && python -m pytest tests/ -v || true",
-    "validate:schema": "npx ajv-cli compile -s $(node -p \"require('./.version.json').spec_path\")/$(node -p \"require('./.version.json').schema_file\") -r $(node -p \"require('./.version.json').spec_path\")/extensions/kagent/kagent.schema.json -r $(node -p \"require('./.version.json').spec_path\")/extensions/mcp/mcp.schema.json -r $(node -p \"require('./.version.json').spec_path\")/extensions/a2a/a2a.schema.json -r $(node -p \"require('./.version.json').spec_path\")/extensions/langchain/langchain.schema.json -r $(node -p \"require('./.version.json').spec_path\")/extensions/langgraph/langgraph.schema.json -r $(node -p \"require('./.version.json').spec_path\")/extensions/ag2/ag2.schema.json -r $(node -p \"require('./.version.json').spec_path\")/extensions/crewai/crewai.schema.json --strict=false --allow-union-types",
-    "validate:manifest": "npx ajv-cli validate -s $(node -p \"require('./.version.json').spec_path\")/$(node -p \"require('./.version.json').schema_file\") --strict=false --allow-union-types -d",
-    "validate:examples": "find examples -name '*.ossa.yaml' -o -name '*.ossa.yml' | head -20 | xargs -I {} npm run validate:manifest -- {}",
+    "validate:schema": "npx ajv-cli compile -s $(node -p \"require('./.version.json').spec_path\")/$(node -p \"require('./.version.json').schema_file\") -r $(node -p \"require('./.version.json').spec_path\")/extensions/kagent/kagent.schema.json -r $(node -p \"require('./.version.json').spec_path\")/extensions/mcp/mcp.schema.json -r $(node -p \"require('./.version.json').spec_path\")/extensions/a2a/a2a.schema.json -r $(node -p \"require('./.version.json').spec_path\")/extensions/langchain/langchain.schema.json -r $(node -p \"require('./.version.json').spec_path\")/extensions/langgraph/langgraph.schema.json -r $(node -p \"require('./.version.json').spec_path\")/extensions/ag2/ag2.schema.json -r $(node -p \"require('./.version.json').spec_path\")/extensions/crewai/crewai.schema.json --strict=false --allow-union-types -c ajv-formats",
+    "validate:manifest": "npx ajv-cli validate -s $(node -p \"require('./.version.json').spec_path\")/$(node -p \"require('./.version.json').schema_file\") --strict=false --allow-union-types -c ajv-formats -d",
+    "validate:examples": "find examples -name '*.ossa.yaml' -o -name '*.ossa.yml' | grep -v 'swarm-to-ossa' | head -20 | xargs -I {} npm run validate:manifest -- {}",
     "validate:power": "tsx src/tools/validation/validate-ossa.ts",
     "validate:openapi": "tsx src/tools/validation/validate-openapi-extensions.ts",
     "validate:current": "tsx src/tools/validation/validate-v$(node -p \"require('./.version.json').current\")-features.ts",
@@ -179,7 +185,7 @@
     "postinstall": "node bin/postinstall || true",
     "// RELEASE & PUBLISH": "",
     "prerelease": "npm run quality && npm run test && npm run validate",
-    "prepublishOnly": "npm run build:clean && npm run test && npm run lint",
+    "prepublishOnly": "npm run build:clean && npm run test:unit && npm run test:smoke",
     "release:check": "npm run prerelease && echo '✅ Ready for release'",
     "release:verify": "tsx src/dev-cli/src/index.ts release verify",
     "release:prep": "tsx src/dev-cli/src/index.ts release prep v$(node -p \"require('./.version.json').latest_stable\")"
@@ -215,13 +221,15 @@
     "@qdrant/js-client-rest": "^1.9.0",
     "@types/tar": "^6.1.13",
     "ajv": "^8.12.0",
-    "ajv-formats": "^3.0.1",
     "axios": "^1.12.2",
+    "boxen": "^7.1.1",
     "chalk": "^5.6.2",
     "commander": "^11.1.0",
     "glob": "^11.0.3",
+    "inquirer": "^9.2.12",
     "inversify": "^7.10.4",
     "openai": "^6.9.1",
+    "ora": "^8.0.1",
     "readline": "^1.3.0",
     "reflect-metadata": "^0.2.2",
     "semver": "^7.7.3",
@@ -238,6 +246,7 @@
     "@semantic-release/git": "^10.0.1",
     "@semantic-release/github": "^12.0.0",
     "@semantic-release/gitlab": "^13.2.9",
+    "@types/inquirer": "^9.0.9",
     "@types/jest": "^29.5.14",
     "@types/js-yaml": "^4.0.9",
     "@types/node": "^20.19.19",
@@ -247,6 +256,8 @@
     "@typescript-eslint/eslint-plugin": "^8.48.0",
     "@typescript-eslint/parser": "^8.48.0",
     "ajv-cli": "^5.0.0",
+    "ajv-formats": "^3.0.1",
+    "esbuild": "^0.27.2",
     "eslint": "^8.57.1",
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-prettier": "^5.5.4",
@@ -263,8 +274,20 @@
     "tsx": "^4.21.0",
     "typescript": "^5.9.3"
   },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "workspaces": [
+    "packages/*"
+  ],
+  "lint-staged": {
+    "src/**/*.{ts,tsx}": [
+      "eslint --fix",
+      "prettier --write"
+    ]
+  },
   "volta": {
-    "node": "18.20.8",
-    "npm": "10.9.4"
+    "node": "20.11.0",
+    "npm": "10.2.4"
   }
 }

package/schemas/capability-contract.v0.json

@@ -0,0 +1,116 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "OSSA Capability Contract v0",
+  "description": "Defines an enforceable contract for an agent capability.",
+  "type": "object",
+  "properties": {
+    "id": {
+      "type": "string",
+      "description": "Unique identifier for the capability (e.g., 'search', 'summarize-text'). Must be URL-friendly."
+    },
+    "version": {
+      "type": "string",
+      "description": "Version of this capability contract (e.g., '0.1.0').",
+      "pattern": "^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?(?:\+[0-9A-Za-z-]+)?$"
+    },
+    "description": {
+      "type": "string",
+      "description": "Human-readable description of what the capability does and when to use it.",
+      "maxLength": 1024
+    },
+    "inputSchema": {
+      "description": "JSON Schema defining the expected input for the capability.",
+      "oneOf": [
+        {" $ref": "https://json-schema.org/draft/2020-12/schema"},
+        {"type": "string"} 
+      ]
+    },
+    "outputSchema": {
+      "description": "JSON Schema defining the expected output from the capability.",
+      "oneOf": [
+        {" $ref": "https://json-schema.org/draft/2020-12/schema"},
+        {"type": "string"} 
+      ]
+    },
+    "authRequirements": {
+      "type": "object",
+      "description": "Specifies authentication schemes and scopes required for this capability.",
+      "properties": {
+        "schemes": {
+          "type": "array",
+          "items": {"type": "string"},
+          "description": "List of OpenAPI security scheme names (e.g., 'oauth2', 'apiKey')."
+        },
+        "scopes": {
+          "type": "array",
+          "items": {"type": "string"},
+          "description": "Provider-specific scopes or permissions required."
+        }
+      },
+      "required": ["schemes"]
+    },
+    "semantics": {
+      "type": "object",
+      "properties": {
+        "idempotency": {
+          "type": "string",
+          "enum": ["idempotent", "non-idempotent"],
+          "description": "Indicates if the operation is idempotent."
+        },
+        "sideEffects": {
+          "type": "string",
+          "enum": ["none", "stateful", "external"],
+          "description": "Indicates if the capability has side effects."
+        }
+      },
+      "required": ["idempotency", "sideEffects"]
+    },
+    "slo": {
+      "type": "object",
+      "description": "Service Level Objectives for the capability.",
+      "properties": {
+        "maxLatencyMs": {
+          "type": "integer",
+          "description": "Maximum acceptable latency in milliseconds (e.g., for p95)."
+        },
+        "maxErrorRate": {
+          "type": "number",
+          "format": "float",
+          "description": "Maximum acceptable error rate (e.g., 0.01 for 1%)."
+        }
+      },
+      "required": ["maxLatencyMs", "maxErrorRate"]
+    },
+    "telemetryRequirements": {
+      "type": "object",
+      "description": "Specifies required telemetry emissions for this capability.",
+      "properties": {
+        "requiredMetrics": {
+          "type": "array",
+          "items": {"type": "string"},
+          "description": "List of standard metric names that must be emitted (e.g., 'ossa.capability.invocations', 'ossa.tokens.prompt')."
+        },
+        "logs": {
+          "type": "array",
+          "items": {"type": "string"},
+          "description": "List of standard log types that must be emitted (e.g., 'request_details', 'error_context')."
+        },
+        "trace": {
+          "type": "boolean",
+          "description": "Indicates whether tracing should be enabled for this capability."
+        }
+      },
+      "required": ["requiredMetrics", "logs", "trace"]
+    }
+  },
+  "required": [
+    "id",
+    "version",
+    "description",
+    "inputSchema",
+    "outputSchema",
+    "semantics",
+    "slo",
+    "telemetryRequirements"
+  ]
+}

package/schemas/identity.lock.schema.json

@@ -0,0 +1,59 @@
+{
+  "title": "Identity Lock Schema",
+  "description": "Schema for capturing resolved provider mappings and hashes for reproducibility and drift detection.",
+  "type": "object",
+  "properties": {
+    "agentName": {
+      "type": "string",
+      "description": "The name of the agent."
+    },
+    "resolvedIdentity": {
+      "type": "object",
+      "properties": {
+        "principal": {
+          "type": "object",
+          "properties": {
+            "category": {"type": "string"},
+            "mode": {"type": "string"},
+            "provider": {"type": "string"},
+            "region": {"type": "string"},
+            "roleName": {"type": "string"},
+            "scopes": {"type": "array", "items": {"type": "string"}},
+            "oidc": {
+              "type": "object",
+              "properties": {
+                "issuerUrl": {"type": "string"},
+                "audience": {"type": "string"}
+              },
+              "required": ["issuerUrl", "audience"]
+            }
+          },
+          "required": ["category", "mode", "provider", "roleName"]
+        },
+        "credentialSource": {
+          "type": "object",
+          "properties": {
+            "type": {"type": "string"},
+            "ref": {"type": "string"}
+          },
+          "required": ["type", "ref"]
+        },
+        "provisionedResourceId": {
+          "type": "string",
+          "description": "The unique identifier of the provisioned resource (e.g., ARN, GitLab SA ID)."
+        },
+        "hash": {
+          "type": "string",
+          "description": "A hash of the resolved configuration for drift detection."
+        }
+      },
+      "required": ["principal", "credentialSource", "provisionedResourceId", "hash"]
+    },
+    "timestamp": {
+      "type": "string",
+      "format": "date-time",
+      "description": "Timestamp when this lock file was generated."
+    }
+  },
+  "required": ["agentName", "resolvedIdentity", "timestamp"]
+}