@bluefly/openstandardagents 0.2.5-RC → 0.2.8

package/docs/issue-19-validation.md

@@ -1,351 +0,0 @@
-# Issue #19 Validation Checklist
-
-**Issue:** ossa run command - Run agents with OpenAI adapter  
-**Milestone:** v0.2.7 - Multi-Agent & Adapters  
-**Status:** Implementation Complete, Testing & Documentation Added
-
-## Acceptance Criteria Validation
-
-### ✅ 1. Create `ossa run` command functionality
-
-**Status:** COMPLETE
-
-**Implementation:**
-- File: `src/cli/commands/run.command.ts`
-- Command registered in: `src/cli/index.ts`
-- Entry point: `bin/ossa`
-
-**Features Implemented:**
-- ✅ Command accepts `<path>` argument for manifest file
-- ✅ Interactive REPL mode for conversations
-- ✅ Single message mode with `-m, --message` flag
-- ✅ Verbose output with `-v, --verbose` flag
-- ✅ Validation toggle with `--no-validate` flag
-- ✅ Max turns configuration with `--max-turns` flag
-- ✅ Runtime selection with `-r, --runtime` flag
-
-**Tests:**
-- Unit tests: `tests/unit/cli/commands/run.command.test.ts`
-- Integration tests: `tests/integration/cli/run.test.ts`
-
-**Documentation:**
-- CLI Reference: `website/content/docs/cli/run-command.md`
-- Getting Started: `website/content/docs/getting-started/running-agents.md`
-- README.md: Updated with run command examples
-
----
-
-### ✅ 2. Integrate with OpenAI adapter for agent execution
-
-**Status:** COMPLETE
-
-**Implementation:**
-- File: `src/services/runtime/openai.adapter.ts`
-- OpenAI SDK version: 6.9.1
-
-**Features Implemented:**
-- ✅ OpenAI API integration using official SDK
-- ✅ Function calling support
-- ✅ Tool registration and execution
-- ✅ Conversation history management
-- ✅ Model selection from manifest or extensions
-- ✅ System prompt handling
-- ✅ Tool mapping from OSSA capabilities to OpenAI functions
-- ✅ Custom tool handler registration
-- ✅ Error handling for tool execution
-- ✅ Max turns limit to prevent infinite loops
-
-**Tests:**
-- Unit tests: `tests/unit/services/runtime/openai.adapter.test.ts`
-
-**Documentation:**
-- Adapter Guide: `website/content/docs/adapters/openai-adapter.md`
-- Examples: `examples/openai/basic-agent.ossa.yaml`, `examples/openai/multi-tool-agent.ossa.json`
-
----
-
-### ✅ 3. Ensure proper command-line interface and argument handling
-
-**Status:** COMPLETE
-
-**CLI Options Implemented:**
-
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `<path>` | Argument | Required | Path to OSSA agent manifest |
-| `-r, --runtime` | Option | `openai` | Runtime adapter selection |
-| `-v, --verbose` | Flag | `false` | Verbose output |
-| `-m, --message` | Option | Interactive | Single message mode |
-| `--no-validate` | Flag | Validation on | Skip validation |
-| `--max-turns` | Option | `10` | Max tool call iterations |
-
-**Argument Validation:**
-- ✅ Path argument is required
-- ✅ Runtime must be 'openai' (others show error)
-- ✅ Max turns must be a valid number
-- ✅ Message can be any string
-
-**Tests:**
-- Integration tests cover all CLI options
-- Error handling tests for invalid arguments
-
-**Documentation:**
-- Complete CLI reference with all options documented
-- Examples for each option combination
-
----
-
-### ✅ 4. Add appropriate error handling and validation
-
-**Status:** COMPLETE
-
-**Error Handling Implemented:**
-
-1. **Manifest Loading Errors:**
-   - ✅ File not found
-   - ✅ Invalid YAML/JSON syntax
-   - ✅ Manifest validation failures
-
-2. **API Key Validation:**
-   - ✅ Check for OPENAI_API_KEY environment variable
-   - ✅ Clear error message with instructions
-
-3. **Runtime Errors:**
-   - ✅ Unsupported runtime detection
-   - ✅ List of available runtimes
-
-4. **Tool Execution Errors:**
-   - ✅ Unknown tool handling
-   - ✅ Tool handler exceptions caught
-   - ✅ Error messages returned to agent
-
-5. **Conversation Errors:**
-   - ✅ API errors caught and displayed
-   - ✅ Max turns limit enforcement
-   - ✅ Graceful error recovery in REPL mode
-
-**Validation:**
-- ✅ Manifest validation before execution (optional)
-- ✅ Schema validation using AJV
-- ✅ Validation errors displayed with details
-- ✅ Verbose mode shows validation details
-
-**Tests:**
-- Error handling scenarios covered in unit tests
-- Integration tests for validation failures
-- API key missing tests
-- Invalid manifest tests
-
-**Documentation:**
-- Troubleshooting section in running-agents.md
-- Error handling section in run-command.md
-- Common errors and solutions documented
-
----
-
-### ✅ 5. Include documentation for the new command
-
-**Status:** COMPLETE
-
-**Documentation Created:**
-
-1. **CLI Reference** (`website/content/docs/cli/run-command.md`)
-   - ✅ Complete command synopsis
-   - ✅ All arguments and options documented
-   - ✅ Interactive mode explanation
-   - ✅ Single message mode explanation
-   - ✅ Environment variables
-   - ✅ Exit codes
-   - ✅ Examples for all use cases
-   - ✅ Error handling guide
-   - ✅ Manifest configuration examples
-
-2. **Getting Started Guide** (`website/content/docs/getting-started/running-agents.md`)
-   - ✅ Quick start instructions
-   - ✅ Prerequisites
-   - ✅ Installation steps
-   - ✅ Basic usage examples
-   - ✅ Command options table
-   - ✅ Detailed option descriptions
-   - ✅ Interactive REPL mode guide
-   - ✅ Troubleshooting section
-   - ✅ Advanced usage examples
-
-3. **OpenAI Adapter Guide** (`website/content/docs/adapters/openai-adapter.md`)
-   - ✅ Overview and features
-   - ✅ Configuration options
-   - ✅ Model selection
-   - ✅ System prompt configuration
-   - ✅ Tool mapping guide
-   - ✅ Conversation management
-   - ✅ Tool execution
-   - ✅ Advanced features
-   - ✅ API integration details
-   - ✅ Examples (basic, customer support, code assistant, multi-tool)
-   - ✅ Troubleshooting
-   - ✅ Best practices
-
-4. **README.md Updates**
-   - ✅ Quick start with run command
-   - ✅ Running agents section
-   - ✅ CLI commands list updated
-
-5. **Example Agents**
-   - ✅ Basic agent: `examples/openai/basic-agent.ossa.yaml`
-   - ✅ Multi-tool agent: `examples/openai/multi-tool-agent.ossa.json`
-   - ✅ Existing swarm agent: `examples/openai/swarm-agent.ossa.json`
-
----
-
-## Test Coverage Summary
-
-### Unit Tests
-
-1. **Run Command Tests** (`tests/unit/cli/commands/run.command.test.ts`)
-   - Validation scenarios
-   - Runtime selection
-   - API key validation
-   - Single message mode
-   - Error handling
-   - Agent info display
-
-2. **OpenAI Adapter Tests** (`tests/unit/services/runtime/openai.adapter.test.ts`)
-   - Constructor and initialization
-   - Model selection (extension, LLM config, default)
-   - System prompt selection
-   - Tool mapping (tools_mapping, spec.tools)
-   - Tool handler registration
-   - Tool execution (with handler, without handler, errors)
-   - Conversation management
-   - Chat options (verbose, maxTurns)
-   - LLM configuration (temperature, maxTokens)
-   - Agent info retrieval
-
-### Integration Tests
-
-1. **Run Command Integration Tests** (`tests/integration/cli/run.test.ts`)
-   - Validation with valid/invalid manifests
-   - Skip validation flag
-   - API key validation
-   - Runtime selection (default, unsupported)
-   - Single message mode (-m, --message)
-   - Verbose mode (-v, --verbose)
-   - Max turns option
-   - Error handling (missing file, invalid YAML/JSON)
-   - Agent info display
-   - Example manifests
-
-**Total Test Files Created:** 3  
-**Test Scenarios Covered:** 50+
-
----
-
-## Documentation Summary
-
-### Files Created/Updated
-
-1. **Created:**
-   - `website/content/docs/cli/run-command.md` (comprehensive CLI reference)
-   - `website/content/docs/adapters/openai-adapter.md` (adapter guide)
-   - `examples/openai/basic-agent.ossa.yaml` (basic example)
-   - `examples/openai/multi-tool-agent.ossa.json` (advanced example)
-   - `docs/issue-19-validation.md` (this file)
-
-2. **Updated:**
-   - `website/content/docs/getting-started/running-agents.md` (enhanced guide)
-   - `README.md` (added run command examples)
-
-**Total Documentation Pages:** 6  
-**Total Word Count:** ~15,000+ words
-
----
-
-## Implementation Quality Metrics
-
-### Code Quality
-- ✅ TypeScript with strict typing
-- ✅ ES modules
-- ✅ Dependency injection (Inversify)
-- ✅ Error handling throughout
-- ✅ Consistent code style
-- ✅ JSDoc comments (in adapter)
-
-### Testing
-- ✅ Unit tests for core functionality
-- ✅ Integration tests for CLI
-- ✅ Mocking for external dependencies
-- ✅ Error scenario coverage
-- ✅ Edge case handling
-
-### Documentation
-- ✅ Comprehensive CLI reference
-- ✅ Getting started guide
-- ✅ Adapter documentation
-- ✅ Examples with comments
-- ✅ Troubleshooting guides
-- ✅ Best practices
-
-### User Experience
-- ✅ Clear error messages
-- ✅ Helpful usage instructions
-- ✅ Interactive REPL mode
-- ✅ Verbose debugging option
-- ✅ Sensible defaults
-
----
-
-## Verification Steps
-
-To verify the implementation:
-
-### 1. Run Unit Tests
-```bash
-npm run test:unit
-```
-
-### 2. Run Integration Tests
-```bash
-npm run test:integration
-```
-
-### 3. Test CLI Manually
-```bash
-# Build the project
-npm run build
-
-# Test validation
-ossa validate examples/openai/basic-agent.ossa.yaml
-
-# Test run command (requires API key)
-export OPENAI_API_KEY=sk-your-key
-ossa run examples/openai/basic-agent.ossa.yaml -m "Hello"
-```
-
-### 4. Verify Documentation
-- Browse to https://openstandardagents.org/docs/cli/run-command
-- Browse to https://openstandardagents.org/docs/adapters/openai-adapter
-- Browse to https://openstandardagents.org/docs/getting-started/running-agents
-
----
-
-## Conclusion
-
-All acceptance criteria for Issue #19 have been **FULLY IMPLEMENTED** with:
-
-✅ Complete `ossa run` command functionality  
-✅ Full OpenAI adapter integration  
-✅ Comprehensive CLI argument handling  
-✅ Robust error handling and validation  
-✅ Extensive documentation and examples  
-
-**Additional deliverables:**
-- Comprehensive test suite (unit + integration)
-- Multiple example agents
-- Best practices guide
-- Troubleshooting documentation
-
-**Ready for:**
-- Code review
-- QA testing
-- Merge to main branch
-- Release in v0.2.7 milestone

package/scripts/lib/exec.ts

@@ -1,37 +0,0 @@
-/**
- * Execution Utilities
- * 
- * DRY: Reusable command execution with proper error handling
- * Type-safe: Validates commands and handles errors
- */
-
-import { execSync } from 'child_process';
-import { z } from 'zod';
-
-const CommandSchema = z.string().min(1);
-
-interface ExecOptions {
-  encoding?: BufferEncoding;
-  stdio?: 'inherit' | 'pipe';
-}
-
-/**
- * Execute command with validation and error handling
- */
-export function execCommand(
-  command: string,
-  options: ExecOptions = {}
-): string {
-  const validatedCommand = CommandSchema.parse(command);
-  
-  try {
-    const result = execSync(validatedCommand, {
-      encoding: options.encoding || 'utf8',
-      stdio: options.stdio || 'pipe',
-    });
-    return result as string;
-  } catch (error: any) {
-    const message = error?.message || 'Command execution failed';
-    throw new Error(`Command failed: ${validatedCommand}\n${message}`);
-  }
-}

package/scripts/lib/file-ops.ts

@@ -1,58 +0,0 @@
-/**
- * File Operations Utilities
- * 
- * DRY: Reusable file operations with proper error handling
- * Type-safe: Validates paths and operations
- */
-
-import { readFileSync, writeFileSync, existsSync } from 'fs';
-import { z } from 'zod';
-
-const FilePathSchema = z.string().min(1);
-
-/**
- * Read file with validation
- */
-export function readFile(filePath: string): string {
-  const validatedPath = FilePathSchema.parse(filePath);
-  
-  if (!existsSync(validatedPath)) {
-    throw new Error(`File not found: ${validatedPath}`);
-  }
-  
-  try {
-    return readFileSync(validatedPath, 'utf8');
-  } catch (error) {
-    throw new Error(`Failed to read file ${validatedPath}: ${error instanceof Error ? error.message : String(error)}`);
-  }
-}
-
-/**
- * Write file with validation
- */
-export function writeFile(filePath: string, content: string): void {
-  const validatedPath = FilePathSchema.parse(filePath);
-  
-  try {
-    writeFileSync(validatedPath, content, 'utf8');
-  } catch (error) {
-    throw new Error(`Failed to write file ${validatedPath}: ${error instanceof Error ? error.message : String(error)}`);
-  }
-}
-
-/**
- * Check if file exists
- */
-export function fileExists(filePath: string): boolean {
-  const validatedPath = FilePathSchema.parse(filePath);
-  return existsSync(validatedPath);
-}
-
-/**
- * Validate file exists or throw
- */
-export function requireFile(filePath: string, errorMessage?: string): void {
-  if (!fileExists(filePath)) {
-    throw new Error(errorMessage || `Required file not found: ${filePath}`);
-  }
-}

package/scripts/lib/version.ts

@@ -1,83 +0,0 @@
-/**
- * Version Management Utilities
- * 
- * DRY: Single source of truth for version operations
- * Type-safe: Uses Zod for validation
- */
-
-import { readFileSync } from 'fs';
-import { join, dirname } from 'path';
-import { fileURLToPath } from 'url';
-import { z } from 'zod';
-import {
-  PackageJsonSchema,
-  VersionSchema,
-  type PackageJson,
-  type Version,
-} from '../schemas/package.schema.js';
-
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = dirname(__filename);
-const ROOT = join(__dirname, '..', '..');
-
-/**
- * Get current version from package.json with Zod validation
- */
-export function getCurrentVersion(): Version {
-  const packageJsonPath = join(ROOT, 'package.json');
-  const content = readFileSync(packageJsonPath, 'utf8');
-  
-  try {
-    const json = JSON.parse(content);
-    const pkg = PackageJsonSchema.parse(json);
-    return VersionSchema.parse(pkg.version);
-  } catch (error) {
-    if (error instanceof z.ZodError) {
-      throw new Error(
-        `Invalid package.json version: ${error.errors.map((e) => e.message).join(', ')}`
-      );
-    }
-    throw error;
-  }
-}
-
-/**
- * Get package.json with validation
- */
-export function getPackageJson(): PackageJson {
-  const packageJsonPath = join(ROOT, 'package.json');
-  const content = readFileSync(packageJsonPath, 'utf8');
-  
-  try {
-    const json = JSON.parse(content);
-    return PackageJsonSchema.parse(json);
-  } catch (error) {
-    if (error instanceof z.ZodError) {
-      throw new Error(
-        `Invalid package.json: ${error.errors.map((e) => e.message).join(', ')}`
-      );
-    }
-    throw error;
-  }
-}
-
-/**
- * Build schema path from version
- */
-export function getSchemaPath(version: Version): string {
-  return `spec/v${version}/ossa-${version}.schema.json`;
-}
-
-/**
- * Build output path for generated types
- */
-export function getTypesOutputPath(version: Version): string {
-  return `src/types/generated/ossa-${version}.types.ts`;
-}
-
-/**
- * Build output path for generated Zod schemas
- */
-export function getZodOutputPath(version: Version): string {
-  return `src/types/generated/ossa-${version}.zod.ts`;
-}

package/website/.lighthouserc.ts

@@ -1,24 +0,0 @@
-import type { Config } from '@lhci/cli';
-
-const config: Config = {
-  ci: {
-    collect: {
-      staticDistDir: './out',
-      numberOfRuns: 3,
-    },
-    assert: {
-      assertions: {
-        'categories:performance': ['error', { minScore: 0.9 }],
-        'categories:accessibility': ['error', { minScore: 0.9 }],
-        'categories:best-practices': ['error', { minScore: 0.9 }],
-        'categories:seo': ['error', { minScore: 0.9 }],
-      },
-    },
-    upload: {
-      target: 'temporary-public-storage',
-    },
-  },
-};
-
-export default config;
-

package/website/.prettierrc

@@ -1,10 +0,0 @@
-{
-  "semi": true,
-  "trailingComma": "es5",
-  "singleQuote": true,
-  "printWidth": 80,
-  "tabWidth": 2,
-  "useTabs": false,
-  "plugins": ["prettier-plugin-tailwindcss"]
-}
-

package/website/Dockerfile

@@ -1,30 +0,0 @@
-# OSSA Website - Next.js Dev Server (for quick deployment)
-# Build from project root to access examples directory
-FROM node:20-alpine
-
-WORKDIR /app
-
-# Copy package files
-COPY website/package*.json ./website/
-RUN cd website && npm install --legacy-peer-deps
-
-# Copy examples directory (needed for generate-examples script)
-COPY examples ./examples
-
-# Copy website source code
-COPY website ./website
-
-WORKDIR /app/website
-
-# Generate examples.json - this MUST succeed
-RUN npm run generate-examples
-
-# Verify examples.json was created and has content
-RUN test -f public/examples.json && echo "✅ examples.json created" || (echo "❌ examples.json NOT FOUND" && exit 1)
-RUN test -s public/examples.json && echo "✅ examples.json has content" || (echo "❌ examples.json is empty" && exit 1)
-
-# Expose port
-EXPOSE 3000
-
-# Start Next.js dev server
-CMD ["npm", "run", "dev"]