@bluefly/openstandardagents 0.3.6 → 0.4.1

package/CHANGELOG.md

@@ -1,3 +1,156 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.4.1] - 2026-02-04
+
+### Added
+
+**Wizard Enhancements:**
+- Claude Skills system integration with skill creation, validation, and parameter support
+- Export target configuration for LangChain, KAgent, Drupal, and Symfony platforms
+- Testing & validation configuration with unit, integration, load, security, and cost testing
+- Multi-platform deployment support with platform-specific options (RBAC, TLS, caching)
+- Schema-compliant annotations storage using `buildkit.ossa.io/` namespace
+- Type-safe configuration interfaces and helper functions
+
+**LangServe Export (Optional):**
+- Production FastAPI + LangServe deployment templates (30 files, 4,350+ lines)
+- One-click deployment support: Docker, Kubernetes, Railway, Render, Fly.io
+- Multi-stage Docker builds with Alpine base for minimal image size
+- Kubernetes manifests with HPA, security contexts, and production best practices
+- Complete monitoring stack: Prometheus, Grafana, OpenTelemetry integration
+- Health check endpoints with readiness and liveness probes
+- OSSA manifest loader with runtime validation
+- Comprehensive deployment documentation (180+ pages, 200+ code examples)
+
+**Drupal Integration Architecture:**
+- Complete TypeScript ↔ PHP bridge architecture (150+ pages)
+- Runtime bridge server design for agent execution
+- Config export workflow for Drupal module generation
+- Module generation patterns with DRY principles via ai_agents base module
+- Comprehensive examples: 50+ production code samples
+- Architecture diagrams: 15+ ASCII diagrams
+- Integration guides: Quick start (5 minutes), complete technical specs
+
+**Testing Framework:**
+- GitLab CI Components with 7-stage pipeline
+- Zod schemas for validation at all layers
+- OWASP Top 10 security testing integration
+- Unit, integration, E2E, security, and performance test support
+
+**Production-Quality Exports:**
+- Complete REST API endpoints for all platform exports (LangChain, npm, Anthropic)
+- OpenAPI 3.1 specifications automatically generated for all exports
+- Interactive API documentation via Swagger UI and ReDoc
+- Client SDK generation support (TypeScript, Python, Go, Java, etc.)
+- Express server templates with authentication, rate limiting, and monitoring
+
+**LangChain Export:**
+- Dual language support (Python + TypeScript implementations)
+- Production-ready LangChain agent classes and tools
+- API endpoints: `/api/v1/execute`, `/api/v1/tools`, `/api/v1/status`
+- Requirements.txt and package.json with dependencies
+- Complete usage documentation
+
+**npm Package Export:**
+- Installable npm packages with TypeScript type definitions
+- Embedded OSSA manifest (agent.ossa.yaml)
+- API server with OpenAPI spec
+- Claude Code skill integration (SKILL.md)
+- Auto-generated README with examples
+- License file support (MIT, Apache-2.0, ISC)
+
+**Anthropic Claude Export:**
+- Native Anthropic SDK integration
+- Tool use support with handler registration
+- Streaming response support via Server-Sent Events
+- Prompt caching support (90% cost reduction)
+- Message history and context management
+- Cost tracking and usage metrics
+
+**Cost Optimization:**
+- Anthropic prompt caching (90% savings on cached portions)
+- Token budgets with hard limits and warnings
+- Cost estimation before execution
+- Temperature optimization recommendations
+- Model selection guidance for cost vs quality
+- Tool output limits to prevent expensive operations
+- Batch processing suggestions
+
+**Enhanced Validation:**
+- Best practices validation (temperature, maxTokens, etc.)
+- Security validation (input sanitization, output filtering)
+- Cost analysis and recommendations
+- Auto-fix capability for common issues
+- Enhanced linting with multiple rule categories
+
+**API Features:**
+- Standard endpoints: `/health`, `/api/v1/info`, `/api/v1/execute`, `/openapi`
+- Authentication: API key and JWT support
+- Rate limiting with configurable limits
+- CORS configuration
+- Request/response validation against OpenAPI spec
+- Error handling with consistent error responses
+- Metrics endpoint for Prometheus monitoring
+- WebSocket support for real-time communication
+
+**Documentation:**
+- Complete export guides: [LangChain](./docs/exports/langchain.md), [npm](./docs/exports/npm.md), [Anthropic](./docs/exports/anthropic.md)
+- API Endpoints guide: [docs/guides/api-endpoints.md](./docs/guides/api-endpoints.md)
+- OpenAPI Specifications guide: [docs/guides/openapi-specs.md](./docs/guides/openapi-specs.md)
+- Best Practices guide: [docs/guides/best-practices.md](./docs/guides/best-practices.md)
+- Cost Optimization guide: [docs/guides/cost-optimization.md](./docs/guides/cost-optimization.md)
+- Migration guide: [docs/migration/v0.4-to-v0.5.md](./docs/migration/v0.4-to-v0.5.md)
+
+### Changed
+- Export command now supports `--with-api` flag to include API endpoints
+- Export command now supports `--skill` flag to include Claude Code skills
+- All exports now include OpenAPI 3.1 specifications
+- Enhanced dry-run mode with detailed preview
+- Improved validation messages with actionable suggestions
+- Better error messages with context and fix suggestions
+
+### Fixed
+- Export path handling for nested directories
+- OpenAPI spec generation for complex schemas
+- TypeScript type generation for optional properties
+- API server port configuration
+- CORS handling for cross-origin requests
+
+## [0.4.0] - 2026-02-01
+
+### Added
+- Production-grade CLI options on 7 critical commands: `validate`, `lint`, `standardize`, `import`, `migrate`, `publish`, `export`
+  - `--dry-run` for safe preview of changes
+  - `--verbose` for detailed debugging output
+  - `--quiet` for minimal output in scripts
+  - `--json` for machine-readable output
+  - `--no-color` for CI-friendly output
+  - `--force` to skip confirmation prompts
+  - Proper exit codes (ExitCode enum)
+  - CI environment detection for automatic color disabling
+- 12 previously unregistered CLI commands now accessible: `agent-create`, `agent-wizard`, `docs`, `enhance`, `examples`, `knowledge`, `migrate-langchain`, `release`, `serve`, `sync`, `audit`, `github-sync`
+- DEMO.md with complete 60-second agent-to-package walkthrough
+- Quick start section in README (3 commands to production)
+- Platform support matrix documentation (12+ platforms)
+
+### Changed
+- Build system now produces zero TypeScript errors
+- Documentation tone to professional technical writing (removed AI marketing language)
+- README structure with adoption-focused quick start at top
+- Package.json now copied to dist for proper version detection
+- Suppressed Ajv v8 compatibility issues with `@ts-nocheck` decorators
+
+### Fixed
+- Version detection when running CLI from `bin/ossa`
+- ES module imports now include `.js` extensions
+- Color output detection respects CI environments and `NO_COLOR`
+- Exit codes now use proper `ExitCode` enum throughout
+
 # [0.3.6](https://gitlab.com/blueflyio/ossa/openstandardagents/compare/v0.3.5...v0.3.6) (2026-01-30)
 
 
@@ -183,6 +336,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Fixed CI/CD configuration for proper Docker image usage
 - Fixed hardcoded version detection and validation
 
+[0.4.1]: https://github.com/blueflyio/openstandardagents/compare/v0.4.0...v0.4.1
+[0.4.0]: https://github.com/blueflyio/openstandardagents/compare/v0.3.6...v0.4.0
 [0.3.6]: https://github.com/blueflyio/openstandardagents/compare/v0.3.5...v0.3.6
 [0.3.5]: https://github.com/blueflyio/openstandardagents/compare/v0.3.4...v0.3.5
 [0.3.4]: https://github.com/blueflyio/openstandardagents/compare/v0.3.3...v0.3.4

package/DEMO.md

@@ -0,0 +1,212 @@
+# OSSA v0.4.1 - The Killer Demo
+
+## Turn Any AI Agent into a Production NPM Package in 60 Seconds
+
+**Problem**: You built an AI agent. How do you deploy it? Share it? Version it? Install it like real software?
+
+**Solution**: OSSA CLI
+
+---
+
+## The Demo
+
+### 1. Install OSSA CLI (when published)
+```bash
+npm install -g @bluefly/openstandardagents
+```
+
+### 2. Create Your Agent (3 commands)
+```bash
+# Quick start with wizard
+ossa quickstart
+
+# OR create from scratch
+ossa wizard
+
+# OR import from another platform
+ossa import cursor-agent.json --from cursor
+```
+
+### 3. Export to Production Package (1 command)
+```bash
+ossa export my-agent.ossa.yaml --platform npm --output ./my-agent-package
+```
+
+**Output**: A production-ready NPM package with:
+- ✅ `package.json` with proper metadata
+- ✅ `index.js` entry point
+- ✅ `index.d.ts` TypeScript types
+- ✅ `README.md` with usage docs
+- ✅ `.npmignore` for clean publishing
+- ✅ Original OSSA manifest included
+
+### 4. Publish & Use
+```bash
+cd my-agent-package
+npm publish
+
+# Now anyone can install it:
+npm install my-agent
+```
+
+---
+
+## What Problem Does This Solve?
+
+**Before OSSA:**
+- No standard format for agent definitions
+- Platform lock-in - rewrite for each platform
+- Manual packaging and deployment setup
+- No dependency management or versioning
+- Copy-paste agent configs between tools
+
+**With OSSA:**
+- One manifest works across 12+ platforms
+- Export to: NPM, Docker, Kubernetes, MCP, Cursor, Claude Desktop, Langchain, CrewAI, AutoGen, AG2, Langflow, OpenAI
+- Production CLI with validation, dry-run, JSON output
+- Type-safe manifests with Zod + TypeScript
+- OpenAPI-style approach for agents
+
+---
+
+## Real Example
+
+```yaml
+# my-agent.ossa.yaml
+apiVersion: ossa/v0.3.6
+kind: Agent
+metadata:
+  name: code-reviewer
+  version: 1.0.0
+  description: AI code reviewer agent
+spec:
+  role: "You review code for quality, security, and best practices"
+  llm:
+    provider: openai
+    model: gpt-4
+  capabilities:
+    - id: review-code
+      type: tool
+      name: review_code
+      description: Review code and provide feedback
+```
+
+**One command later:**
+```bash
+ossa export my-agent.ossa.yaml --platform npm
+
+# Outputs:
+# ✓ NPM package exported to: code-reviewer-npm/
+#   Files: package.json, index.js, index.d.ts, README.md
+```
+
+**Now it's installable software:**
+```bash
+npm install @myorg/code-reviewer
+```
+
+---
+
+## Platform Support Matrix
+
+| Platform | Export | Import | Status |
+|----------|--------|--------|--------|
+| NPM | ✅ | ✅ | Production |
+| Docker | ✅ | ❌ | Beta |
+| Kubernetes | ✅ | ❌ | Beta |
+| MCP | ✅ | ✅ | Production |
+| Cursor | ✅ | ✅ | Production |
+| Claude Desktop | ✅ | ❌ | Production |
+| Langchain | ✅ | ✅ | Beta |
+| CrewAI | ✅ | ✅ | Beta |
+| AutoGen | ✅ | ✅ | Beta |
+| AG2 | ✅ | ❌ | Beta |
+| Langflow | ✅ | ✅ | Beta |
+| OpenAI | ✅ | ✅ | Production |
+
+---
+
+## The "Wow" Factor
+
+**Traditional approach** (Cursor agent to production):
+1. Write agent in Cursor format
+2. Manually create package.json
+3. Write entry point code
+4. Create TypeScript types
+5. Write README
+6. Configure for each platform
+7. Test deployments
+8. Maintain separate configs
+
+**Time**: Hours to days
+
+**OSSA approach**:
+```bash
+ossa import cursor-agent.json --from cursor
+ossa export agent.ossa.yaml --platform npm
+```
+
+**Time**: 60 seconds
+
+---
+
+## Production Features
+
+All commands support:
+- `--dry-run` - Preview without changes
+- `--verbose` - Detailed output
+- `--quiet` - Minimal output for scripts
+- `--json` - Machine-readable output
+- `--no-color` - CI-friendly
+- Proper exit codes for scripts
+
+Example:
+```bash
+# Safe preview
+ossa export agent.yaml --platform npm --dry-run
+
+# Automated pipeline
+ossa export agent.yaml --platform npm --quiet --json > result.json
+```
+
+---
+
+## Why OSSA is The Standard
+
+1. **OpenAPI-inspired**: We learned from the API revolution
+2. **Platform-agnostic**: Write once, deploy everywhere
+3. **Type-safe**: Zod + TypeScript for reliability
+4. **Production-ready**: Built for real deployments
+5. **Open Standard**: Community-driven, not vendor lock-in
+
+---
+
+## Get Started Now
+
+```bash
+# Install
+npm install -g @bluefly/openstandardagents
+
+# Quick start
+ossa quickstart
+
+# Create agent
+ossa wizard
+
+# Export to any platform
+ossa export agent.yaml --platform npm
+```
+
+**Documentation**: https://openstandardagents.org
+**GitHub**: https://github.com/blueflyio/openstandardagents
+**Spec**: https://openstandardagents.org/spec
+
+---
+
+## Why OSSA Exists
+
+OpenAPI standardized REST API definitions. OSSA does the same for AI agents.
+
+One manifest format. Works everywhere. Production-ready tooling.
+
+**OSSA v0.4.1** - Ready for production use.