@bluefly/openstandardagents 0.4.4 → 0.4.6

package/dist/adapters/warp/adapter.js

@@ -0,0 +1,386 @@
+/**
+ * Warp Terminal Agent Platform Adapter
+ * Exports OSSA agent manifests to Warp agent format
+ *
+ * Warp agents are command-line agents that run in Warp Terminal
+ * https://docs.warp.dev/agent-platform/getting-started/agents-in-warp
+ *
+ * SOLID: Single Responsibility - Warp agent generation only
+ * DRY: Reuses BaseAdapter validation and helpers
+ */
+import { BaseAdapter } from '../base/adapter.interface.js';
+export class WarpAdapter extends BaseAdapter {
+    platform = 'warp';
+    displayName = 'Warp Terminal';
+    description = 'Warp terminal agent with command-line interface and triggers';
+    status = 'beta';
+    supportedVersions = ['v{{VERSION}}'];
+    /**
+     * Export OSSA manifest to Warp agent format
+     */
+    async export(manifest, options) {
+        const startTime = Date.now();
+        try {
+            // Validate manifest
+            if (options?.validate !== false) {
+                const validation = await this.validate(manifest);
+                if (!validation.valid) {
+                    return this.createResult(false, [], `Validation failed: ${validation.errors?.map((e) => e.message).join(', ')}`, {
+                        duration: Date.now() - startTime,
+                        warnings: validation.warnings?.map((w) => w.message),
+                    });
+                }
+            }
+            const agentName = manifest.metadata?.name || 'warp-agent';
+            const files = [];
+            // Generate warp-agent.yaml - Warp agent configuration
+            const warpAgent = this.convertToWarpAgent(manifest);
+            const config = {
+                version: '1.0',
+                agent: warpAgent,
+            };
+            files.push(this.createFile(`warp/${agentName}/warp-agent.yaml`, this.generateWarpConfig(config), 'config', 'yaml'));
+            // Generate handlers for each command
+            warpAgent.commands.forEach((cmd) => {
+                files.push(this.createFile(`warp/${agentName}/handlers/${cmd.name}.sh`, this.generateCommandHandler(cmd, manifest), 'code', 'bash'));
+            });
+            // Generate README.md
+            files.push(this.createFile(`warp/${agentName}/README.md`, this.generateReadme(manifest, warpAgent), 'documentation'));
+            // Include source OSSA manifest for provenance
+            files.push(this.createManifestFile(manifest));
+            // Perfect Agent files
+            files.push(...(await this.generatePerfectAgentFiles(manifest, options)));
+            return this.createResult(true, files, undefined, {
+                duration: Date.now() - startTime,
+                version: '1.0.0',
+            });
+        }
+        catch (error) {
+            return this.createResult(false, [], error instanceof Error ? error.message : String(error), { duration: Date.now() - startTime });
+        }
+    }
+    /**
+     * Validate manifest for Warp compatibility
+     */
+    async validate(manifest) {
+        const errors = [];
+        const warnings = [];
+        // Base validation
+        const baseValidation = await super.validate(manifest);
+        if (baseValidation.errors)
+            errors.push(...baseValidation.errors);
+        if (baseValidation.warnings)
+            warnings.push(...baseValidation.warnings);
+        // Warp-specific validation
+        const spec = manifest.spec;
+        // Check capabilities or tools (Warp uses these as commands)
+        if ((!spec?.capabilities || !Array.isArray(spec.capabilities)) &&
+            (!spec?.tools || !Array.isArray(spec.tools))) {
+            warnings.push({
+                message: 'No capabilities or tools defined, agent will have no commands',
+                path: 'spec.capabilities',
+                suggestion: 'Add spec.capabilities or spec.tools array',
+            });
+        }
+        return {
+            valid: errors.length === 0,
+            errors: errors.length > 0 ? errors : undefined,
+            warnings: warnings.length > 0 ? warnings : undefined,
+        };
+    }
+    /**
+     * Get example Warp-optimized manifest
+     */
+    getExample() {
+        return {
+            apiVersion: 'ossa/v{{VERSION}}',
+            kind: 'Agent',
+            metadata: {
+                name: 'warp-dev-agent',
+                version: '1.0.0',
+                description: 'Development workflow agent for Warp Terminal',
+            },
+            spec: {
+                role: 'Assists with common development tasks in the terminal',
+                capabilities: [
+                    'git-commit',
+                    'run-tests',
+                    'deploy',
+                    'code-review',
+                ],
+                tools: [
+                    {
+                        type: 'command',
+                        name: 'git_commit',
+                        description: 'Create a git commit with conventional commit format',
+                    },
+                    {
+                        type: 'command',
+                        name: 'run_tests',
+                        description: 'Run project tests and display results',
+                    },
+                ],
+            },
+        };
+    }
+    /**
+     * Convert OSSA manifest to Warp agent
+     */
+    convertToWarpAgent(manifest) {
+        const name = manifest.metadata?.name || 'warp-agent';
+        const description = manifest.spec?.role || manifest.metadata?.description || 'Warp agent';
+        // Convert tools/capabilities to Warp commands
+        const tools = (manifest.spec?.tools || []);
+        const capabilities = (manifest.spec?.capabilities || []).map((c) => (typeof c === 'string' ? c : c.name || ''));
+        const commands = [];
+        // Convert tools to commands
+        tools.forEach((tool) => {
+            const cmdName = tool.name?.replace(/_/g, '-') || 'unknown';
+            const cmd = {
+                name: cmdName,
+                description: tool.description || `Execute ${cmdName}`,
+                handler: `./handlers/${cmdName}.sh`,
+            };
+            // Extract parameters from tool schema
+            if (tool.inputSchema || tool.schema) {
+                const schema = tool.inputSchema || tool.schema;
+                if (schema.properties) {
+                    cmd.parameters = this.convertSchemaToParameters(schema);
+                }
+            }
+            commands.push(cmd);
+        });
+        // Add capability-based commands if no tools
+        if (commands.length === 0 && capabilities.length > 0) {
+            capabilities.forEach((cap) => {
+                const cmdName = cap.replace(/_/g, '-');
+                commands.push({
+                    name: cmdName,
+                    description: `Execute ${cap} capability`,
+                    handler: `./handlers/${cmdName}.sh`,
+                });
+            });
+        }
+        return {
+            name,
+            description,
+            commands,
+            metadata: {
+                version: manifest.metadata?.version,
+                author: manifest.metadata?.author,
+                tags: manifest.metadata?.tags,
+            },
+        };
+    }
+    /**
+     * Convert JSON Schema to Warp parameters
+     */
+    convertSchemaToParameters(schema) {
+        const params = {};
+        if (!schema.properties)
+            return params;
+        for (const [key, value] of Object.entries(schema.properties)) {
+            const prop = value;
+            params[key] = {
+                type: prop.type || 'string',
+                description: prop.description || `Parameter: ${key}`,
+                required: schema.required?.includes(key),
+                default: prop.default,
+                enum: prop.enum,
+            };
+        }
+        return params;
+    }
+    /**
+     * Generate warp-agent.yaml configuration
+     */
+    generateWarpConfig(config) {
+        // Manual YAML generation for better control
+        let yaml = `version: "${config.version}"\n\n`;
+        yaml += `agent:\n`;
+        yaml += `  name: "${config.agent.name}"\n`;
+        yaml += `  description: "${config.agent.description}"\n\n`;
+        if (config.agent.metadata) {
+            yaml += `  metadata:\n`;
+            if (config.agent.metadata.version) {
+                yaml += `    version: "${config.agent.metadata.version}"\n`;
+            }
+            if (config.agent.metadata.author) {
+                yaml += `    author: "${config.agent.metadata.author}"\n`;
+            }
+            if (config.agent.metadata.tags) {
+                yaml += `    tags:\n`;
+                config.agent.metadata.tags.forEach((tag) => {
+                    yaml += `      - "${tag}"\n`;
+                });
+            }
+            yaml += '\n';
+        }
+        yaml += `  commands:\n`;
+        config.agent.commands.forEach((cmd) => {
+            yaml += `    - name: "${cmd.name}"\n`;
+            yaml += `      description: "${cmd.description}"\n`;
+            yaml += `      handler: "${cmd.handler}"\n`;
+            if (cmd.parameters && Object.keys(cmd.parameters).length > 0) {
+                yaml += `      parameters:\n`;
+                Object.entries(cmd.parameters).forEach(([name, param]) => {
+                    yaml += `        ${name}:\n`;
+                    yaml += `          type: "${param.type}"\n`;
+                    yaml += `          description: "${param.description}"\n`;
+                    if (param.required)
+                        yaml += `          required: true\n`;
+                    if (param.default !== undefined)
+                        yaml += `          default: ${JSON.stringify(param.default)}\n`;
+                });
+            }
+            yaml += '\n';
+        });
+        return yaml;
+    }
+    /**
+     * Generate command handler script
+     */
+    generateCommandHandler(cmd, manifest) {
+        const params = cmd.parameters || {};
+        const paramList = Object.keys(params)
+            .map((p) => `$${p.toUpperCase()}`)
+            .join(' ');
+        return `#!/usr/bin/env bash
+# Warp Command Handler: ${cmd.name}
+# ${cmd.description}
+# Generated from OSSA manifest
+
+set -euo pipefail
+
+# Command: ${cmd.name}
+# Description: ${cmd.description}
+
+${Object.keys(params).length > 0
+            ? `# Parameters:\n${Object.entries(params)
+                .map(([name, param]) => `# - ${name.toUpperCase()}: ${param.description}${param.required ? ' (required)' : ''}`)
+                .join('\n')}`
+            : '# No parameters'}
+
+# Parse arguments
+${Object.entries(params)
+            .map(([name]) => `${name.toUpperCase()}=""`)
+            .join('\n')}
+
+while [[ $# -gt 0 ]]; do
+  case $1 in
+${Object.keys(params)
+            .map((name) => `    --${name})
+      ${name.toUpperCase()}="$2"
+      shift 2
+      ;;`)
+            .join('\n')}
+    *)
+      echo "Unknown parameter: $1"
+      exit 1
+      ;;
+  esac
+done
+
+# Validate required parameters
+${Object.entries(params)
+            .filter(([, param]) => param.required)
+            .map(([name]) => `if [[ -z "$${name.toUpperCase()}" ]]; then
+  echo "Error: --${name} is required"
+  exit 1
+fi`)
+            .join('\n')}
+
+# Delegate to OSSA CLI when available (set OSSA_MANIFEST to manifest path)
+if command -v ossa >/dev/null 2>&1 && [[ -n "\${OSSA_MANIFEST:-}" ]]; then
+  ossa run "\${OSSA_MANIFEST}" --tool ${cmd.name} -- "\$@"
+  exit \$?
+fi
+
+# Fallback: output structured result for callers
+echo "{\"tool\": \"${cmd.name}\", \"params\": {${Object.keys(params)
+            .map((k) => `\"${k}\": \"\$${k.toUpperCase()}\"`)
+            .join(', ')}}}"
+exit 0
+`;
+    }
+    /**
+     * Generate README.md
+     */
+    generateReadme(manifest, agent) {
+        const agentName = manifest.metadata?.name || 'warp-agent';
+        const description = manifest.spec?.role || manifest.metadata?.description || 'Warp agent';
+        return `# ${agentName}
+
+${description}
+
+## Warp Terminal Agent
+
+This agent is designed for use with [Warp Terminal](https://www.warp.dev/), providing command-line tools and workflows.
+
+## Installation
+
+1. **Copy to Warp agents directory:**
+
+\`\`\`bash
+mkdir -p ~/.warp/agents
+cp -r warp/${agentName} ~/.warp/agents/
+\`\`\`
+
+2. **Make handlers executable:**
+
+\`\`\`bash
+chmod +x ~/.warp/agents/${agentName}/handlers/*.sh
+\`\`\`
+
+3. **Restart Warp Terminal**
+
+## Available Commands
+
+${agent.commands
+            .map((cmd) => `### /${cmd.name}
+
+${cmd.description}
+
+${cmd.parameters && Object.keys(cmd.parameters).length > 0
+            ? `**Parameters:**
+
+${Object.entries(cmd.parameters)
+                .map(([name, param]) => `- \`--${name}\`: ${param.description}${param.required ? ' (required)' : ''}`)
+                .join('\n')}`
+            : '**No parameters**'}
+
+**Usage:**
+
+\`\`\`bash
+/${cmd.name}${cmd.parameters
+            ? ` ${Object.keys(cmd.parameters)
+                .map((p) => `--${p} <value>`)
+                .join(' ')}`
+            : ''}
+\`\`\`
+`)
+            .join('\n')}
+
+## Development
+
+Command handlers are located in \`handlers/\` directory. Each handler is a bash script that implements the command logic.
+
+To add or modify commands:
+
+1. Edit \`warp-agent.yaml\` to add/update command definitions
+2. Create/modify the corresponding handler script in \`handlers/\`
+3. Make the handler executable: \`chmod +x handlers/<command>.sh\`
+
+## Generated from OSSA
+
+This agent was generated from an OSSA v${manifest.apiVersion?.split('/')[1] || '{{VERSION}}'} manifest.
+
+Original manifest: \`agent.ossa.yaml\`
+
+## License
+
+${manifest.metadata?.license || 'MIT'}
+`;
+    }
+}
+//# sourceMappingURL=adapter.js.map

package/dist/adapters/warp/types.d.ts

@@ -0,0 +1,140 @@
+/**
+ * Warp Terminal Agent Type Definitions
+ * https://docs.warp.dev/agent-platform/getting-started/agents-in-warp
+ */
+/**
+ * Warp Agent Definition
+ */
+export interface WarpAgent {
+    /**
+     * Unique agent identifier
+     */
+    name: string;
+    /**
+     * Human-readable description
+     */
+    description: string;
+    /**
+     * Agent commands
+     */
+    commands: WarpCommand[];
+    /**
+     * Command triggers (optional)
+     */
+    triggers?: WarpTrigger[];
+    /**
+     * Agent permissions
+     */
+    permissions?: WarpPermission[];
+    /**
+     * Agent metadata
+     */
+    metadata?: {
+        version?: string;
+        author?: string;
+        tags?: string[];
+        [key: string]: unknown;
+    };
+}
+/**
+ * Warp Command Definition
+ */
+export interface WarpCommand {
+    /**
+     * Command name (invoked as /name in Warp)
+     */
+    name: string;
+    /**
+     * Command description
+     */
+    description: string;
+    /**
+     * Command parameters
+     */
+    parameters?: Record<string, WarpParameter>;
+    /**
+     * Shell command or script path to execute
+     */
+    handler: string;
+    /**
+     * Command aliases
+     */
+    aliases?: string[];
+    /**
+     * Command examples
+     */
+    examples?: string[];
+}
+/**
+ * Warp Parameter Definition
+ */
+export interface WarpParameter {
+    /**
+     * Parameter type
+     */
+    type: 'string' | 'number' | 'boolean' | 'array' | 'object';
+    /**
+     * Parameter description
+     */
+    description: string;
+    /**
+     * Whether parameter is required
+     */
+    required?: boolean;
+    /**
+     * Default value
+     */
+    default?: unknown;
+    /**
+     * Allowed values
+     */
+    enum?: unknown[];
+}
+/**
+ * Warp Trigger Definition
+ */
+export interface WarpTrigger {
+    /**
+     * Trigger type
+     */
+    type: 'keyword' | 'pattern' | 'event';
+    /**
+     * Trigger value (keyword, regex pattern, or event name)
+     */
+    value: string;
+    /**
+     * Command to execute when triggered
+     */
+    command: string;
+}
+/**
+ * Warp Permission Definition
+ */
+export interface WarpPermission {
+    /**
+     * Permission type
+     */
+    type: 'filesystem' | 'network' | 'environment' | 'process' | 'clipboard' | 'system';
+    /**
+     * Permission scope (e.g., read, write, execute)
+     */
+    scope: string[];
+    /**
+     * Permission description
+     */
+    description?: string;
+}
+/**
+ * Warp Agent Configuration File
+ */
+export interface WarpAgentConfig {
+    /**
+     * Config file version
+     */
+    version: '1.0';
+    /**
+     * Agent definition
+     */
+    agent: WarpAgent;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/adapters/warp/types.js

@@ -0,0 +1,6 @@
+/**
+ * Warp Terminal Agent Type Definitions
+ * https://docs.warp.dev/agent-platform/getting-started/agents-in-warp
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/api/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * OSSA REST API — Express app factory
+ *
+ * Three consumers, one service layer:
+ *   CLI (inquirer) → Service Layer ← REST API (Express) ← MCP Server (stdio)
+ */
+import express from 'express';
+import 'reflect-metadata';
+export interface CreateAppOptions {
+    corsOrigin?: string;
+}
+export declare function createApp(opts?: CreateAppOptions): express.Application;
+//# sourceMappingURL=index.d.ts.map

package/dist/api/index.js

@@ -0,0 +1,44 @@
+/**
+ * OSSA REST API — Express app factory
+ *
+ * Three consumers, one service layer:
+ *   CLI (inquirer) → Service Layer ← REST API (Express) ← MCP Server (stdio)
+ */
+import express from 'express';
+import 'reflect-metadata';
+import { corsMiddleware } from './middleware/cors.js';
+import { errorHandler } from './middleware/error-handler.js';
+import { requestId } from './middleware/request-id.js';
+import { convertRouter } from './routes/convert.router.js';
+import { exportRouter } from './routes/export.router.js';
+import { healthRouter } from './routes/health.router.js';
+import { manifestsRouter } from './routes/manifests.router.js';
+import { mcpRouter } from './routes/mcp.router.js';
+import { skillsRouter } from './routes/skills.router.js';
+import { validateRouter } from './routes/validate.router.js';
+import { versionRouter } from './routes/version.router.js';
+import { wizardRouter } from './routes/wizard.router.js';
+import { workspaceRouter } from './routes/workspace.router.js';
+export function createApp(opts) {
+    const app = express();
+    // Body parsing
+    app.use(express.json({ limit: '10mb' }));
+    // Middleware
+    app.use(requestId());
+    app.use(corsMiddleware(opts?.corsOrigin));
+    // Routes
+    app.use('/', healthRouter());
+    app.use('/api/v1/manifests', manifestsRouter());
+    app.use('/api/v1/wizard', wizardRouter());
+    app.use('/api/v1/export', exportRouter());
+    app.use('/api/v1/convert', convertRouter());
+    app.use('/api/v1/skills', skillsRouter());
+    app.use('/api/v1/workspace', workspaceRouter());
+    app.use('/api/v1/mcp', mcpRouter());
+    app.use('/api/v1/version', versionRouter());
+    app.use('/api/v1/validate', validateRouter());
+    // Error handler (must be last)
+    app.use(errorHandler());
+    return app;
+}
+//# sourceMappingURL=index.js.map

package/dist/api/middleware/cors.d.ts

@@ -0,0 +1,6 @@
+/**
+ * CORS middleware for ossa-ui and other consumers
+ */
+import type { Request, Response, NextFunction } from 'express';
+export declare function corsMiddleware(origin?: string): (_req: Request, res: Response, next: NextFunction) => void;
+//# sourceMappingURL=cors.d.ts.map

package/dist/api/middleware/cors.js

@@ -0,0 +1,17 @@
+/**
+ * CORS middleware for ossa-ui and other consumers
+ */
+export function corsMiddleware(origin) {
+    return (_req, res, next) => {
+        res.setHeader('Access-Control-Allow-Origin', origin || '*');
+        res.setHeader('Access-Control-Allow-Methods', 'GET, POST, PUT, DELETE, OPTIONS');
+        res.setHeader('Access-Control-Allow-Headers', 'Content-Type, Authorization, X-Request-Id');
+        res.setHeader('Access-Control-Max-Age', '86400');
+        if (_req.method === 'OPTIONS') {
+            res.status(204).end();
+            return;
+        }
+        next();
+    };
+}
+//# sourceMappingURL=cors.js.map

package/dist/api/middleware/error-handler.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Global error handler middleware
+ */
+import type { Request, Response, NextFunction } from 'express';
+export declare function errorHandler(): (err: Error, _req: Request, res: Response, _next: NextFunction) => void;
+//# sourceMappingURL=error-handler.d.ts.map

package/dist/api/middleware/error-handler.js

@@ -0,0 +1,32 @@
+/**
+ * Global error handler middleware
+ */
+import { ZodError } from 'zod';
+export function errorHandler() {
+    return (err, _req, res, _next) => {
+        if (err instanceof ZodError) {
+            res.status(400).json({
+                error: 'Validation error',
+                details: err.issues.map((i) => ({
+                    path: i.path.join('.'),
+                    message: i.message,
+                })),
+            });
+            return;
+        }
+        // Known OSSA errors
+        if (err.message?.includes('not found') ||
+            err.message?.includes('No such file')) {
+            res.status(404).json({ error: err.message });
+            return;
+        }
+        if (err.message?.includes('already exists')) {
+            res.status(409).json({ error: err.message });
+            return;
+        }
+        // Unknown errors
+        console.error('Unhandled error:', err);
+        res.status(500).json({ error: 'Internal server error' });
+    };
+}
+//# sourceMappingURL=error-handler.js.map

package/dist/api/middleware/request-id.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Request ID middleware — adds X-Request-Id header
+ */
+import type { Request, Response, NextFunction } from 'express';
+export declare function requestId(): (req: Request, res: Response, next: NextFunction) => void;
+//# sourceMappingURL=request-id.d.ts.map

package/dist/api/middleware/request-id.js

@@ -0,0 +1,12 @@
+/**
+ * Request ID middleware — adds X-Request-Id header
+ */
+import { v4 as uuidv4 } from 'uuid';
+export function requestId() {
+    return (req, res, next) => {
+        const id = req.headers['x-request-id'] || uuidv4();
+        res.setHeader('X-Request-Id', id);
+        next();
+    };
+}
+//# sourceMappingURL=request-id.js.map

package/dist/api/middleware/validate.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Zod validation middleware for Express request body/query
+ */
+import type { Request, Response, NextFunction } from 'express';
+import { z } from 'zod';
+export declare function validateBody(schema: z.ZodSchema): (req: Request, res: Response, next: NextFunction) => void;
+export declare function validateQuery(schema: z.ZodSchema): (req: Request, res: Response, next: NextFunction) => void;
+//# sourceMappingURL=validate.d.ts.map