@synergenius/flow-weaver 0.2.0

package/dist/cli/commands/pattern.js

@@ -0,0 +1,185 @@
+/* eslint-disable no-console */
+/**
+ * CLI pattern commands
+ * - list: Find patterns in files/directories
+ * - apply: Merge pattern into workflow
+ * - extract: Create pattern from workflow nodes
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { glob } from 'glob';
+import { AnnotationParser } from '../../parser.js';
+import { logger } from '../utils/logger.js';
+import { listPatterns, applyPattern, extractPattern } from '../../api/patterns.js';
+const parser = new AnnotationParser();
+/**
+ * Find patterns in a file or directory
+ */
+export async function patternListCommand(inputPath, options) {
+    if (!fs.existsSync(inputPath)) {
+        throw new Error(`Path not found: ${inputPath}`);
+    }
+    const stat = fs.statSync(inputPath);
+    let files;
+    if (stat.isDirectory()) {
+        files = await glob('**/*.ts', { cwd: inputPath, absolute: true });
+    }
+    else {
+        files = [inputPath];
+    }
+    const allPatterns = [];
+    for (const file of files) {
+        try {
+            const patterns = listPatterns(file);
+            if (patterns.length > 0) {
+                allPatterns.push({ file, patterns });
+            }
+        }
+        catch {
+            // Skip files that fail to parse
+        }
+    }
+    const flat = allPatterns.flatMap(({ file, patterns }) => patterns.map((p) => ({ file, ...p })));
+    if (flat.length === 0) {
+        if (options.json) {
+            console.log(JSON.stringify([]));
+        }
+        else {
+            logger.info('No patterns found');
+        }
+        return;
+    }
+    if (options.json) {
+        console.log(JSON.stringify(flat, null, 2));
+        return;
+    }
+    // Human-readable output
+    for (const { file, name, description, inputPorts, outputPorts, nodes } of flat) {
+        logger.section(name);
+        if (description) {
+            logger.info(description);
+        }
+        logger.info(`File: ${path.relative(process.cwd(), file)}`);
+        if (inputPorts.length > 0) {
+            logger.info('Input ports:');
+            for (const port of inputPorts) {
+                logger.log(`  ${port.name}${port.description ? ` - ${port.description}` : ''}`);
+            }
+        }
+        if (outputPorts.length > 0) {
+            logger.info('Output ports:');
+            for (const port of outputPorts) {
+                logger.log(`  ${port.name}${port.description ? ` - ${port.description}` : ''}`);
+            }
+        }
+        if (nodes.length > 0) {
+            logger.info(`Nodes: ${nodes.join(', ')}`);
+        }
+        logger.newline();
+    }
+}
+/**
+ * Apply a pattern to a workflow file
+ */
+export async function patternApplyCommand(patternFile, targetFile, options) {
+    // Parse pattern file
+    const patternResult = parser.parse(patternFile);
+    if (patternResult.patterns.length === 0) {
+        throw new Error(`No patterns found in ${patternFile}`);
+    }
+    // Select pattern (by name if specified, otherwise first)
+    let pattern;
+    if (options.name) {
+        const found = patternResult.patterns.find((p) => p.name === options.name);
+        if (!found) {
+            throw new Error(`Pattern "${options.name}" not found in ${patternFile}`);
+        }
+        pattern = found;
+    }
+    else {
+        pattern = patternResult.patterns[0];
+    }
+    // Parse target to detect existing node types
+    const targetContent = fs.readFileSync(targetFile, 'utf8');
+    const targetResult = parser.parse(targetFile);
+    const existingNodeTypes = new Set(targetResult.nodeTypes.map((nt) => nt.name));
+    // Apply pattern via API
+    const result = applyPattern({
+        patternAST: pattern,
+        targetContent,
+        targetNodeTypes: existingNodeTypes,
+        prefix: options.prefix,
+    });
+    if (result.conflicts.length > 0) {
+        console.log(`\u26A0\uFE0F  Node type conflict detected: ${result.conflicts.join(', ')}`);
+        console.log('   Existing node types will be preserved. Consider using --prefix to avoid conflicts.');
+    }
+    if (options.preview) {
+        console.log(result.modifiedContent);
+        logger.newline();
+        logger.section('Manual wiring required');
+        for (const instruction of result.wiringInstructions) {
+            logger.log(`  ${instruction}`);
+        }
+        logger.info('Input ports:');
+        for (const name of Object.keys(pattern.inputPorts)) {
+            logger.log(`  IN.${name}`);
+        }
+        logger.info('Output ports:');
+        for (const name of Object.keys(pattern.outputPorts)) {
+            logger.log(`  OUT.${name}`);
+        }
+        return;
+    }
+    // Write modified content
+    fs.writeFileSync(targetFile, result.modifiedContent);
+    logger.success(`Applied pattern "${pattern.name}" to ${targetFile}`);
+    if (result.nodeTypesAdded.length > 0) {
+        logger.info(`Added node types: ${result.nodeTypesAdded.join(', ')}`);
+    }
+    const nodePrefix = options.prefix ? `${options.prefix}_` : '';
+    logger.info(`Added nodes: ${pattern.instances.map((i) => `${nodePrefix}${i.id}`).join(', ')}`);
+    logger.newline();
+    logger.section('Wire these ports manually');
+    for (const instruction of result.wiringInstructions) {
+        logger.log(`  ${instruction}`);
+    }
+    logger.info('Input ports:');
+    for (const name of Object.keys(pattern.inputPorts)) {
+        logger.log(`  IN.${name}`);
+    }
+    logger.info('Output ports:');
+    for (const name of Object.keys(pattern.outputPorts)) {
+        logger.log(`  OUT.${name}`);
+    }
+}
+/**
+ * Extract a pattern from workflow nodes
+ */
+export async function patternExtractCommand(sourceFile, options) {
+    // Parse source file
+    const parseResult = parser.parse(sourceFile);
+    if (parseResult.workflows.length === 0) {
+        throw new Error(`No workflows found in ${sourceFile}`);
+    }
+    const workflow = parseResult.workflows[0];
+    const nodeIds = options.nodes.split(',').map((s) => s.trim());
+    // Extract pattern via API
+    const result = extractPattern({
+        workflowAST: workflow,
+        nodeTypes: parseResult.nodeTypes,
+        nodeIds,
+        name: options.name,
+    });
+    if (options.preview) {
+        console.log(result.patternCode);
+        return;
+    }
+    // Write to output file
+    fs.writeFileSync(options.output, result.patternCode);
+    logger.success(`Extracted pattern "${result.patternName}" to ${options.output}`);
+    logger.info(`Included nodes: ${result.nodes.join(', ')}`);
+    logger.info(`Input ports: ${result.inputPorts.join(', ') || 'none'}`);
+    logger.info(`Output ports: ${result.outputPorts.join(', ') || 'none'}`);
+}
+//# sourceMappingURL=pattern.js.map

package/dist/cli/commands/plugin.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Plugin command — scaffolds a new external plugin directory
+ */
+export interface PluginInitOptions {
+    area?: string;
+    system?: boolean;
+    preview?: boolean;
+    force?: boolean;
+}
+export declare function validatePluginName(name: string): string | true;
+export declare function generatePluginFiles(pluginName: string, options: {
+    area: string;
+    system: boolean;
+}): Record<string, string>;
+export declare function pluginInitCommand(name: string, options: PluginInitOptions): Promise<void>;
+//# sourceMappingURL=plugin.d.ts.map

package/dist/cli/commands/plugin.js

@@ -0,0 +1,176 @@
+/* eslint-disable no-console */
+/**
+ * Plugin command — scaffolds a new external plugin directory
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { logger } from '../utils/logger.js';
+// ── Validation ───────────────────────────────────────────────────────────────
+const PLUGIN_NAME_RE = /^[a-zA-Z0-9][-a-zA-Z0-9_.]*$/;
+const VALID_AREAS = ['sidebar', 'main', 'toolbar', 'modal', 'panel'];
+export function validatePluginName(name) {
+    if (!name)
+        return 'Plugin name cannot be empty';
+    if (name.length > 100)
+        return 'Plugin name must be at most 100 characters';
+    if (!PLUGIN_NAME_RE.test(name)) {
+        return 'Plugin name must start with a letter or digit and contain only letters, digits, hyphens, dots, and underscores';
+    }
+    return true;
+}
+// ── File generation ──────────────────────────────────────────────────────────
+function toPascalCase(name) {
+    return name
+        .split(/[-_.]/)
+        .map((s) => s.charAt(0).toUpperCase() + s.slice(1))
+        .join('');
+}
+export function generatePluginFiles(pluginName, options) {
+    const componentName = toPascalCase(pluginName) + 'Panel';
+    const pluginArtifact = [
+        `name: ${pluginName}`,
+        'version: 1.0.0',
+        `description: ${pluginName} plugin`,
+        'entry:',
+        '  client: ./client/index.tsx',
+        ...(options.system ? ['  system: ./system/index.ts'] : []),
+        'capabilities: {}',
+        '',
+    ].join('\n');
+    const clientIndex = [
+        "import { PluginPanel, createPlugin } from '@synergenius/flow-weaver/plugin';",
+        "import type { TPluginComponentProps, TPluginComponentApi } from '@synergenius/flow-weaver/plugin';",
+        "import React from 'react';",
+        '',
+        `const PLUGIN_NAME = '${pluginName}';`,
+        '',
+        ...(options.system
+            ? [
+                `const fetchData = async (api: TPluginComponentApi) =>`,
+                `  api.call(PLUGIN_NAME, 'getData', undefined);`,
+                '',
+            ]
+            : []),
+        `const ${componentName} = (props: TPluginComponentProps) => {`,
+        '  return (',
+        '    <PluginPanel {...props}>',
+        `      <div style={{ padding: 16 }}>`,
+        `        <h3>${pluginName}</h3>`,
+        ...(options.system
+            ? [
+                '        <button',
+                '          onClick={async () => {',
+                '            const result = await fetchData(props.api);',
+                '            console.log(result);',
+                '          }}',
+                '        >',
+                '          Fetch Data',
+                '        </button>',
+            ]
+            : ['        <p>Plugin loaded.</p>']),
+        '      </div>',
+        '    </PluginPanel>',
+        '  );',
+        '};',
+        '',
+        'export default createPlugin(() => ({',
+        '  async initialize() {},',
+        '  ui: {',
+        '    components: {',
+        `      ${componentName},`,
+        '    },',
+        '    config: {',
+        `      ${componentName}: {`,
+        `        name: '${componentName}',`,
+        `        displayName: '${pluginName}',`,
+        `        area: '${options.area}',`,
+        `        description: '${pluginName} plugin panel',`,
+        '      },',
+        '    },',
+        '  },',
+        '}));',
+        '',
+    ].join('\n');
+    const files = {
+        'plugin-artifact.yaml': pluginArtifact,
+        'client/index.tsx': clientIndex,
+    };
+    if (options.system) {
+        const systemIndex = [
+            "import type { TPluginSystemModule } from '@synergenius/flow-weaver/plugin';",
+            '',
+            'const plugin: TPluginSystemModule = {',
+            '  async initialize() {',
+            '    // Plugin system module initialized',
+            '  },',
+            '  methods: {',
+            '    async getData() {',
+            `      return { message: 'Hello from ${pluginName}!' };`,
+            '    },',
+            '  },',
+            '  async cleanup() {',
+            '    // Plugin cleanup',
+            '  },',
+            '};',
+            '',
+            'export default plugin;',
+            '',
+        ].join('\n');
+        files['system/index.ts'] = systemIndex;
+    }
+    return files;
+}
+// ── CLI entrypoint ───────────────────────────────────────────────────────────
+export async function pluginInitCommand(name, options) {
+    const area = options.area ?? 'panel';
+    const includeSystem = options.system !== false;
+    const preview = options.preview ?? false;
+    const force = options.force ?? false;
+    // Validate plugin name
+    const valid = validatePluginName(name);
+    if (valid !== true) {
+        throw new Error(valid);
+    }
+    // Validate area
+    if (!VALID_AREAS.includes(area)) {
+        throw new Error(`Invalid area "${area}". Available: ${VALID_AREAS.join(', ')}`);
+    }
+    const files = generatePluginFiles(name, { area, system: includeSystem });
+    if (preview) {
+        logger.section('Preview');
+        for (const [relativePath, content] of Object.entries(files)) {
+            logger.log(`\n── ${relativePath} ──`);
+            logger.log(content);
+        }
+        return;
+    }
+    // Write files under plugins/<name>/
+    const targetDir = path.resolve('plugins', name);
+    const filesCreated = [];
+    const filesSkipped = [];
+    for (const [relativePath, content] of Object.entries(files)) {
+        const absPath = path.join(targetDir, relativePath);
+        const dir = path.dirname(absPath);
+        fs.mkdirSync(dir, { recursive: true });
+        if (fs.existsSync(absPath) && !force) {
+            filesSkipped.push(relativePath);
+            continue;
+        }
+        fs.writeFileSync(absPath, content, 'utf8');
+        filesCreated.push(relativePath);
+    }
+    // Output
+    logger.section('Plugin scaffolded');
+    for (const file of filesCreated) {
+        logger.success(`Created plugins/${name}/${file}`);
+    }
+    for (const file of filesSkipped) {
+        logger.warn(`Skipped plugins/${name}/${file} (already exists)`);
+    }
+    logger.newline();
+    logger.section('Next steps');
+    logger.log(`  Ensure your .flowweaver/config.yaml has: pluginsDir: plugins`);
+    logger.log(`  Then restart the editor to load the plugin.`);
+    logger.newline();
+}
+//# sourceMappingURL=plugin.js.map

package/dist/cli/commands/run.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Run command - execute a workflow file directly from the CLI
+ */
+export interface RunOptions {
+    /** Specific workflow name to run (if file contains multiple workflows) */
+    workflow?: string;
+    /** Input parameters as JSON string */
+    params?: string;
+    /** Path to JSON file containing input parameters */
+    paramsFile?: string;
+    /** Run in production mode (no trace events) */
+    production?: boolean;
+    /** Include execution trace events */
+    trace?: boolean;
+    /** Output result as JSON (for scripting) */
+    json?: boolean;
+    /** Execution timeout in milliseconds */
+    timeout?: number;
+    /** Mock config for built-in nodes as inline JSON string */
+    mocks?: string;
+    /** Path to JSON file containing mock config for built-in nodes */
+    mocksFile?: string;
+}
+/**
+ * Execute a workflow file and output the result.
+ *
+ * @param input - Path to the workflow file
+ * @param options - Execution options
+ *
+ * @example
+ * ```bash
+ * # Basic execution
+ * flow-weaver run workflow.ts
+ *
+ * # With parameters
+ * flow-weaver run workflow.ts --params '{"a": 5, "b": 3}'
+ *
+ * # From params file
+ * flow-weaver run workflow.ts --params-file params.json
+ *
+ * # Specific workflow in multi-workflow file
+ * flow-weaver run workflow.ts --workflow calculate
+ *
+ * # JSON output for scripting
+ * flow-weaver run workflow.ts --json | jq '.result'
+ * ```
+ */
+export declare function runCommand(input: string, options: RunOptions): Promise<void>;
+//# sourceMappingURL=run.d.ts.map

package/dist/cli/commands/run.js

@@ -0,0 +1,191 @@
+/**
+ * Run command - execute a workflow file directly from the CLI
+ */
+import * as path from 'path';
+import * as fs from 'fs';
+import { executeWorkflowFromFile } from '../../mcp/workflow-executor.js';
+import { logger } from '../utils/logger.js';
+import { getFriendlyError } from '../../friendly-errors.js';
+import { getErrorMessage } from '../../utils/error-utils.js';
+/**
+ * Execute a workflow file and output the result.
+ *
+ * @param input - Path to the workflow file
+ * @param options - Execution options
+ *
+ * @example
+ * ```bash
+ * # Basic execution
+ * flow-weaver run workflow.ts
+ *
+ * # With parameters
+ * flow-weaver run workflow.ts --params '{"a": 5, "b": 3}'
+ *
+ * # From params file
+ * flow-weaver run workflow.ts --params-file params.json
+ *
+ * # Specific workflow in multi-workflow file
+ * flow-weaver run workflow.ts --workflow calculate
+ *
+ * # JSON output for scripting
+ * flow-weaver run workflow.ts --json | jq '.result'
+ * ```
+ */
+export async function runCommand(input, options) {
+    const filePath = path.resolve(input);
+    // Validate file exists
+    if (!fs.existsSync(filePath)) {
+        throw new Error(`File not found: ${filePath}`);
+    }
+    // Parse params from --params or --params-file
+    let params = {};
+    if (options.params) {
+        try {
+            params = JSON.parse(options.params);
+        }
+        catch {
+            throw new Error(`Invalid JSON in --params: ${options.params}`);
+        }
+    }
+    else if (options.paramsFile) {
+        const paramsFilePath = path.resolve(options.paramsFile);
+        if (!fs.existsSync(paramsFilePath)) {
+            throw new Error(`Params file not found: ${paramsFilePath}`);
+        }
+        try {
+            const content = fs.readFileSync(paramsFilePath, 'utf8');
+            params = JSON.parse(content);
+        }
+        catch {
+            throw new Error(`Failed to parse params file: ${options.paramsFile}`);
+        }
+    }
+    // Parse mocks from --mocks or --mocks-file
+    let mocks;
+    if (options.mocks) {
+        try {
+            mocks = JSON.parse(options.mocks);
+        }
+        catch {
+            throw new Error(`Invalid JSON in --mocks: ${options.mocks}`);
+        }
+    }
+    else if (options.mocksFile) {
+        const mocksFilePath = path.resolve(options.mocksFile);
+        if (!fs.existsSync(mocksFilePath)) {
+            throw new Error(`Mocks file not found: ${mocksFilePath}`);
+        }
+        try {
+            const content = fs.readFileSync(mocksFilePath, 'utf8');
+            mocks = JSON.parse(content);
+        }
+        catch {
+            throw new Error(`Failed to parse mocks file: ${options.mocksFile}`);
+        }
+    }
+    // Set up timeout if specified
+    let timeoutId;
+    let timedOut = false;
+    if (options.timeout) {
+        timeoutId = setTimeout(() => {
+            timedOut = true;
+            if (!options.json) {
+                logger.error(`Execution timed out after ${options.timeout}ms`);
+            }
+            process.exit(1);
+        }, options.timeout);
+    }
+    try {
+        // Determine trace inclusion:
+        // - If --production is set, no trace (unless --trace explicitly set)
+        // - If --trace is set, include trace
+        // - Default: include trace in dev mode
+        const includeTrace = options.trace ?? !options.production;
+        if (!options.json && mocks) {
+            logger.info('Running with mock data');
+        }
+        const result = await executeWorkflowFromFile(filePath, params, {
+            workflowName: options.workflow,
+            production: options.production ?? false,
+            includeTrace,
+            mocks,
+        });
+        if (timedOut)
+            return; // Don't output if already timed out
+        if (options.json) {
+            // JSON output for scripting
+            process.stdout.write(JSON.stringify({
+                success: true,
+                workflow: result.functionName,
+                executionTime: result.executionTime,
+                result: result.result,
+                ...(includeTrace && result.trace && { traceCount: result.trace.length }),
+            }, null, 2) + '\n');
+        }
+        else {
+            // Human-readable output
+            logger.success(`Workflow "${result.functionName}" completed in ${result.executionTime}ms`);
+            logger.newline();
+            logger.section('Result');
+            logger.log(JSON.stringify(result.result, null, 2));
+            if (result.trace && result.trace.length > 0) {
+                logger.newline();
+                logger.section('Trace');
+                logger.log(`${result.trace.length} events captured`);
+                // Show first few trace events as summary
+                const preview = result.trace.slice(0, 5);
+                for (const event of preview) {
+                    logger.log(`  [${event.type}] ${event.data?.nodeId || ''}`);
+                }
+                if (result.trace.length > 5) {
+                    logger.log(`  ... and ${result.trace.length - 5} more events`);
+                }
+            }
+        }
+    }
+    catch (error) {
+        const errorMsg = getErrorMessage(error);
+        // Try to extract validator error code from the error message for friendly formatting
+        // Common pattern: "Validation error [CODE]: message" or errors with a .code property
+        const errorObj = error;
+        if (errorObj.errors && Array.isArray(errorObj.errors)) {
+            // Structured validation errors (from compileWorkflow)
+            logger.error(`Workflow execution failed:`);
+            for (const err of errorObj.errors) {
+                const friendly = getFriendlyError(err);
+                if (friendly) {
+                    logger.error(`  ${friendly.title}: ${friendly.explanation}`);
+                    logger.info(`    How to fix: ${friendly.fix}`);
+                }
+                else {
+                    logger.error(`  - ${err.message}`);
+                }
+            }
+        }
+        else if (errorObj.code) {
+            const friendly = getFriendlyError({ code: errorObj.code, message: errorMsg });
+            if (friendly) {
+                logger.error(`${friendly.title}: ${friendly.explanation}`);
+                logger.info(`  How to fix: ${friendly.fix}`);
+            }
+            else {
+                logger.error(`Workflow execution failed: ${errorMsg}`);
+            }
+        }
+        else {
+            logger.error(`Workflow execution failed: ${errorMsg}`);
+        }
+        if (!options.json) {
+            throw error;
+        }
+        else {
+            process.stdout.write(JSON.stringify({ success: false, error: errorMsg }, null, 2) + '\n');
+        }
+    }
+    finally {
+        if (timeoutId) {
+            clearTimeout(timeoutId);
+        }
+    }
+}
+//# sourceMappingURL=run.js.map

package/dist/cli/commands/serve.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Serve command - start HTTP server exposing workflows as endpoints
+ */
+export interface ServeOptions {
+    /** Server port */
+    port?: number;
+    /** Server host */
+    host?: string;
+    /** Enable file watching for hot reload */
+    watch?: boolean;
+    /** Production mode (no trace events) */
+    production?: boolean;
+    /** Precompile all workflows on startup */
+    precompile?: boolean;
+    /** CORS origin */
+    cors?: string;
+    /** Enable Swagger UI at /docs */
+    swagger?: boolean;
+}
+/**
+ * Start a webhook server exposing workflows as HTTP endpoints.
+ *
+ * @param dir - Directory containing workflow files (defaults to current directory)
+ * @param options - Server options
+ *
+ * @example
+ * ```bash
+ * # Start server with current directory
+ * flow-weaver serve
+ *
+ * # Specify workflow directory
+ * flow-weaver serve ./workflows
+ *
+ * # Custom port
+ * flow-weaver serve --port 8080
+ *
+ * # Production mode
+ * flow-weaver serve --production --precompile
+ *
+ * # Disable hot reload
+ * flow-weaver serve --no-watch
+ * ```
+ */
+export declare function serveCommand(dir: string | undefined, options: ServeOptions): Promise<void>;
+//# sourceMappingURL=serve.d.ts.map