@synergenius/flow-weaver 0.2.0

package/dist/deployment/openapi/generator.js

@@ -0,0 +1,347 @@
+/**
+ * OpenAPI specification generator
+ *
+ * Generates OpenAPI 3.0 specifications from workflow endpoints.
+ */
+import { SchemaConverter } from './schema-converter.js';
+/**
+ * OpenAPI specification generator
+ */
+export class OpenAPIGenerator {
+    schemaConverter;
+    constructor() {
+        this.schemaConverter = new SchemaConverter();
+    }
+    /**
+     * Generate OpenAPI specification from workflow endpoints
+     */
+    generate(endpoints, options) {
+        const doc = {
+            openapi: '3.0.3',
+            info: {
+                title: options.title,
+                version: options.version,
+                description: options.description,
+                contact: options.contact,
+                license: options.license,
+            },
+            servers: options.servers,
+            paths: {},
+            components: {
+                schemas: this.generateComponentSchemas(),
+                responses: this.generateStandardResponses(),
+            },
+            tags: [
+                {
+                    name: 'workflows',
+                    description: 'Workflow execution endpoints',
+                },
+                {
+                    name: 'system',
+                    description: 'System and health check endpoints',
+                },
+            ],
+        };
+        // Add standard system endpoints
+        doc.paths['/health'] = this.generateHealthEndpoint();
+        doc.paths['/workflows'] = this.generateListEndpoint();
+        // Add workflow endpoints
+        for (const endpoint of endpoints) {
+            const path = options.basePath ? `${options.basePath}${endpoint.path}` : endpoint.path;
+            doc.paths[path] = this.generateWorkflowEndpoint(endpoint);
+        }
+        return doc;
+    }
+    /**
+     * Generate path item for a workflow endpoint
+     */
+    generateWorkflowEndpoint(endpoint) {
+        const operation = {
+            operationId: `execute_${endpoint.name}`,
+            summary: `Execute ${endpoint.name} workflow`,
+            description: endpoint.description || `Execute the ${endpoint.name} workflow`,
+            tags: ['workflows'],
+            parameters: [
+                {
+                    name: 'trace',
+                    in: 'query',
+                    description: 'Include execution trace events in response',
+                    required: false,
+                    schema: { type: 'boolean', default: false },
+                },
+            ],
+            requestBody: {
+                description: 'Workflow input parameters',
+                required: true,
+                content: {
+                    'application/json': {
+                        schema: endpoint.inputSchema
+                            ? this.schemaConverter.toOpenAPISchema(endpoint.inputSchema)
+                            : { type: 'object' },
+                    },
+                },
+            },
+            responses: {
+                '200': {
+                    description: 'Successful workflow execution',
+                    content: {
+                        'application/json': {
+                            schema: this.schemaConverter.createSuccessSchema(endpoint.outputSchema
+                                ? this.schemaConverter.toOpenAPISchema(endpoint.outputSchema)
+                                : undefined),
+                        },
+                    },
+                    headers: {
+                        'X-Request-Id': {
+                            schema: { type: 'string' },
+                            description: 'Unique request identifier',
+                        },
+                        'X-Execution-Time': {
+                            schema: { type: 'string' },
+                            description: 'Execution time in milliseconds',
+                        },
+                    },
+                },
+                '400': {
+                    description: 'Validation error',
+                    content: {
+                        'application/json': {
+                            schema: { $ref: '#/components/schemas/Error' },
+                        },
+                    },
+                },
+                '404': {
+                    description: 'Workflow not found',
+                    content: {
+                        'application/json': {
+                            schema: { $ref: '#/components/schemas/Error' },
+                        },
+                    },
+                },
+                '500': {
+                    description: 'Execution error',
+                    content: {
+                        'application/json': {
+                            schema: { $ref: '#/components/schemas/Error' },
+                        },
+                    },
+                },
+                '504': {
+                    description: 'Execution timeout',
+                    content: {
+                        'application/json': {
+                            schema: { $ref: '#/components/schemas/Error' },
+                        },
+                    },
+                },
+            },
+        };
+        return {
+            [endpoint.method.toLowerCase()]: operation,
+        };
+    }
+    /**
+     * Generate health endpoint
+     */
+    generateHealthEndpoint() {
+        return {
+            get: {
+                operationId: 'health_check',
+                summary: 'Health check',
+                description: 'Check server health and get basic status information',
+                tags: ['system'],
+                responses: {
+                    '200': {
+                        description: 'Server is healthy',
+                        content: {
+                            'application/json': {
+                                schema: {
+                                    type: 'object',
+                                    properties: {
+                                        status: {
+                                            type: 'string',
+                                            enum: ['ok', 'error'],
+                                        },
+                                        timestamp: {
+                                            type: 'string',
+                                            format: 'date-time',
+                                        },
+                                        workflows: {
+                                            type: 'integer',
+                                            description: 'Number of registered workflows',
+                                        },
+                                        uptime: {
+                                            type: 'integer',
+                                            description: 'Server uptime in seconds',
+                                        },
+                                    },
+                                    required: ['status', 'timestamp', 'workflows'],
+                                },
+                            },
+                        },
+                    },
+                },
+            },
+        };
+    }
+    /**
+     * Generate workflow list endpoint
+     */
+    generateListEndpoint() {
+        return {
+            get: {
+                operationId: 'list_workflows',
+                summary: 'List all workflows',
+                description: 'Get a list of all registered workflows with their metadata',
+                tags: ['system'],
+                responses: {
+                    '200': {
+                        description: 'List of workflows',
+                        content: {
+                            'application/json': {
+                                schema: {
+                                    type: 'object',
+                                    properties: {
+                                        count: {
+                                            type: 'integer',
+                                            description: 'Total number of workflows',
+                                        },
+                                        workflows: {
+                                            type: 'array',
+                                            items: {
+                                                type: 'object',
+                                                properties: {
+                                                    name: { type: 'string' },
+                                                    path: { type: 'string' },
+                                                    method: { type: 'string' },
+                                                    description: { type: 'string' },
+                                                    inputSchema: { type: 'object' },
+                                                    outputSchema: { type: 'object' },
+                                                },
+                                                required: ['name', 'path', 'method'],
+                                            },
+                                        },
+                                    },
+                                    required: ['count', 'workflows'],
+                                },
+                            },
+                        },
+                    },
+                },
+            },
+        };
+    }
+    /**
+     * Generate component schemas
+     */
+    generateComponentSchemas() {
+        return {
+            Error: this.schemaConverter.createErrorSchema(),
+            TraceEvent: {
+                type: 'object',
+                properties: {
+                    type: { type: 'string', description: 'Event type' },
+                    timestamp: { type: 'number', description: 'Unix timestamp' },
+                    data: { type: 'object', description: 'Event data' },
+                },
+                required: ['type', 'timestamp'],
+            },
+        };
+    }
+    /**
+     * Generate standard responses
+     */
+    generateStandardResponses() {
+        return {
+            BadRequest: {
+                description: 'Bad request - validation failed',
+                content: {
+                    'application/json': {
+                        schema: { $ref: '#/components/schemas/Error' },
+                    },
+                },
+            },
+            NotFound: {
+                description: 'Resource not found',
+                content: {
+                    'application/json': {
+                        schema: { $ref: '#/components/schemas/Error' },
+                    },
+                },
+            },
+            InternalError: {
+                description: 'Internal server error',
+                content: {
+                    'application/json': {
+                        schema: { $ref: '#/components/schemas/Error' },
+                    },
+                },
+            },
+        };
+    }
+}
+/**
+ * Generate OpenAPI specification as JSON string
+ */
+export function generateOpenAPIJson(endpoints, options) {
+    const generator = new OpenAPIGenerator();
+    const doc = generator.generate(endpoints, options);
+    return JSON.stringify(doc, null, 2);
+}
+/**
+ * Generate OpenAPI specification as YAML string
+ */
+export function generateOpenAPIYaml(endpoints, options) {
+    const generator = new OpenAPIGenerator();
+    const doc = generator.generate(endpoints, options);
+    // Simple JSON to YAML conversion (for basic cases)
+    // For production, use a proper YAML library
+    return jsonToYaml(doc);
+}
+/**
+ * Simple JSON to YAML converter
+ */
+function jsonToYaml(obj, indent = 0) {
+    const spaces = '  '.repeat(indent);
+    if (obj === null || obj === undefined) {
+        return 'null';
+    }
+    if (typeof obj === 'string') {
+        // Quote strings that need it
+        if (obj.includes('\n') ||
+            obj.includes(':') ||
+            obj.includes('#') ||
+            obj.startsWith(' ') ||
+            obj.endsWith(' ')) {
+            return `"${obj.replace(/"/g, '\\"').replace(/\n/g, '\\n')}"`;
+        }
+        return obj;
+    }
+    if (typeof obj === 'number' || typeof obj === 'boolean') {
+        return String(obj);
+    }
+    if (Array.isArray(obj)) {
+        if (obj.length === 0)
+            return '[]';
+        return obj.map((item) => `${spaces}- ${jsonToYaml(item, indent + 1).trimStart()}`).join('\n');
+    }
+    if (typeof obj === 'object') {
+        const entries = Object.entries(obj);
+        if (entries.length === 0)
+            return '{}';
+        return entries
+            .map(([key, value]) => {
+            const valueStr = jsonToYaml(value, indent + 1);
+            if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+                return `${spaces}${key}:\n${valueStr}`;
+            }
+            if (Array.isArray(value)) {
+                return `${spaces}${key}:\n${valueStr}`;
+            }
+            return `${spaces}${key}: ${valueStr}`;
+        })
+            .join('\n');
+    }
+    return String(obj);
+}
+//# sourceMappingURL=generator.js.map

package/dist/deployment/openapi/schema-converter.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Schema converter for transforming Flow Weaver schemas to OpenAPI format
+ */
+import type { TDataType } from '../../ast/types.js';
+/**
+ * OpenAPI 3.0 Schema Object (simplified)
+ */
+export interface OpenAPISchema {
+    type?: string;
+    format?: string;
+    description?: string;
+    properties?: Record<string, OpenAPISchema>;
+    items?: OpenAPISchema;
+    required?: string[];
+    enum?: unknown[];
+    default?: unknown;
+    nullable?: boolean;
+    oneOf?: OpenAPISchema[];
+    anyOf?: OpenAPISchema[];
+    allOf?: OpenAPISchema[];
+    $ref?: string;
+    additionalProperties?: boolean | OpenAPISchema;
+}
+/**
+ * Schema converter class
+ */
+export declare class SchemaConverter {
+    /**
+     * Convert a Flow Weaver data type to OpenAPI schema
+     */
+    toOpenAPIType(dataType: TDataType): OpenAPISchema;
+    /**
+     * Convert a Flow Weaver JSON Schema to OpenAPI Schema
+     */
+    toOpenAPISchema(schema: Record<string, unknown>): OpenAPISchema;
+    /**
+     * Create a schema for workflow error responses
+     */
+    createErrorSchema(): OpenAPISchema;
+    /**
+     * Create a schema for successful workflow responses
+     */
+    createSuccessSchema(outputSchema?: OpenAPISchema): OpenAPISchema;
+}
+/**
+ * Singleton instance for convenience
+ */
+export declare const schemaConverter: SchemaConverter;
+//# sourceMappingURL=schema-converter.d.ts.map

package/dist/deployment/openapi/schema-converter.js

@@ -0,0 +1,192 @@
+/**
+ * Schema converter for transforming Flow Weaver schemas to OpenAPI format
+ */
+/**
+ * Flow Weaver data type to OpenAPI type mapping
+ */
+const DATA_TYPE_MAP = {
+    STRING: { type: 'string' },
+    NUMBER: { type: 'number' },
+    BOOLEAN: { type: 'boolean' },
+    OBJECT: { type: 'object' },
+    ARRAY: { type: 'array' },
+    FUNCTION: { type: 'object', format: 'function' },
+    ANY: { type: 'object', format: 'any' },
+    STEP: { type: 'boolean', format: 'step' },
+};
+/**
+ * Schema converter class
+ */
+export class SchemaConverter {
+    /**
+     * Convert a Flow Weaver data type to OpenAPI schema
+     */
+    toOpenAPIType(dataType) {
+        const mapping = DATA_TYPE_MAP[dataType];
+        if (!mapping) {
+            return { type: 'object' };
+        }
+        const schema = { type: mapping.type };
+        if (mapping.format) {
+            schema.format = mapping.format;
+        }
+        return schema;
+    }
+    /**
+     * Convert a Flow Weaver JSON Schema to OpenAPI Schema
+     */
+    toOpenAPISchema(schema) {
+        if (!schema || typeof schema !== 'object') {
+            return { type: 'object' };
+        }
+        const result = {};
+        // Copy basic properties
+        if (schema.type) {
+            result.type = schema.type;
+        }
+        if (schema.description) {
+            result.description = schema.description;
+        }
+        if (schema.format) {
+            result.format = schema.format;
+        }
+        if (schema.default !== undefined) {
+            result.default = schema.default;
+        }
+        if (schema.enum) {
+            result.enum = schema.enum;
+        }
+        // Convert properties recursively
+        if (schema.properties) {
+            result.properties = {};
+            const props = schema.properties;
+            for (const [key, value] of Object.entries(props)) {
+                result.properties[key] = this.toOpenAPISchema(value);
+            }
+        }
+        // Handle required fields
+        if (schema.required) {
+            result.required = schema.required;
+        }
+        // Handle array items
+        if (schema.items) {
+            result.items = this.toOpenAPISchema(schema.items);
+        }
+        // Handle additional properties
+        if (schema.additionalProperties !== undefined) {
+            if (typeof schema.additionalProperties === 'boolean') {
+                result.additionalProperties = schema.additionalProperties;
+            }
+            else {
+                result.additionalProperties = this.toOpenAPISchema(schema.additionalProperties);
+            }
+        }
+        // Handle composition keywords
+        if (schema.oneOf) {
+            result.oneOf = schema.oneOf.map((s) => this.toOpenAPISchema(s));
+        }
+        if (schema.anyOf) {
+            result.anyOf = schema.anyOf.map((s) => this.toOpenAPISchema(s));
+        }
+        if (schema.allOf) {
+            result.allOf = schema.allOf.map((s) => this.toOpenAPISchema(s));
+        }
+        return result;
+    }
+    /**
+     * Create a schema for workflow error responses
+     */
+    createErrorSchema() {
+        return {
+            type: 'object',
+            properties: {
+                success: {
+                    type: 'boolean',
+                    description: 'Always false for error responses',
+                    default: false,
+                },
+                error: {
+                    type: 'object',
+                    properties: {
+                        code: {
+                            type: 'string',
+                            description: 'Error code',
+                            enum: [
+                                'WORKFLOW_NOT_FOUND',
+                                'VALIDATION_ERROR',
+                                'EXECUTION_ERROR',
+                                'TIMEOUT',
+                                'CANCELLED',
+                                'INTERNAL_ERROR',
+                            ],
+                        },
+                        message: {
+                            type: 'string',
+                            description: 'Human-readable error message',
+                        },
+                        stack: {
+                            type: 'string',
+                            description: 'Stack trace (development only)',
+                        },
+                    },
+                    required: ['code', 'message'],
+                },
+                executionTime: {
+                    type: 'number',
+                    description: 'Execution time in milliseconds',
+                },
+                requestId: {
+                    type: 'string',
+                    description: 'Unique request identifier',
+                },
+            },
+            required: ['success', 'error'],
+        };
+    }
+    /**
+     * Create a schema for successful workflow responses
+     */
+    createSuccessSchema(outputSchema) {
+        return {
+            type: 'object',
+            properties: {
+                success: {
+                    type: 'boolean',
+                    description: 'Always true for successful responses',
+                    default: true,
+                },
+                workflow: {
+                    type: 'string',
+                    description: 'Name of the executed workflow',
+                },
+                result: outputSchema || { type: 'object', description: 'Workflow result' },
+                executionTime: {
+                    type: 'number',
+                    description: 'Execution time in milliseconds',
+                },
+                trace: {
+                    type: 'array',
+                    description: 'Execution trace events (if requested)',
+                    items: {
+                        type: 'object',
+                        properties: {
+                            type: { type: 'string' },
+                            timestamp: { type: 'number' },
+                            data: { type: 'object' },
+                        },
+                    },
+                },
+                requestId: {
+                    type: 'string',
+                    description: 'Unique request identifier',
+                },
+            },
+            required: ['success', 'workflow', 'executionTime', 'requestId'],
+        };
+    }
+}
+/**
+ * Singleton instance for convenience
+ */
+export const schemaConverter = new SchemaConverter();
+//# sourceMappingURL=schema-converter.js.map