@synergenius/flow-weaver 0.2.0

package/dist/cli/commands/compile.js

@@ -0,0 +1,278 @@
+/**
+ * Compile command - compiles workflow files to TypeScript
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { glob } from 'glob';
+import { parseWorkflow } from '../../api/index.js';
+import { generateInPlace } from '../../api/generate-in-place.js';
+import { generateCode } from '../../api/generate.js';
+import { validator } from '../../validator.js';
+import { logger } from '../utils/logger.js';
+import { getErrorMessage } from '../../utils/error-utils.js';
+import { getFriendlyError } from '../../friendly-errors.js';
+import { detectProjectModuleFormat } from './doctor.js';
+import { generateInngestFunction } from '../../generator/inngest.js';
+import { AnnotationParser } from '../../parser.js';
+/**
+ * Resolve the module format to use for compilation.
+ * If 'auto' or not specified, detect from the project's package.json.
+ */
+function resolveModuleFormat(format, cwd) {
+    if (format === 'esm' || format === 'cjs') {
+        return format;
+    }
+    // Auto-detect from project
+    const detection = detectProjectModuleFormat(cwd);
+    return detection.format;
+}
+export async function compileCommand(input, options = {}) {
+    const { production = false, sourceMap = false, strict = false, verbose = false, workflowName, dryRun = false, format, inlineRuntime = false, clean = false, target } = options;
+    // Handle Inngest target compilation
+    if (target === 'inngest') {
+        return compileInngestTarget(input, { production, verbose, workflowName, dryRun });
+    }
+    // Resolve module format (auto-detect if not specified)
+    const cwd = process.cwd();
+    const moduleFormat = resolveModuleFormat(format, cwd);
+    try {
+        // If input is a directory, expand to all .ts files recursively
+        let pattern = input;
+        try {
+            if (fs.existsSync(input) && fs.statSync(input).isDirectory()) {
+                pattern = path.join(input, '**/*.ts');
+            }
+        }
+        catch {
+            // Not a valid path, use as glob pattern
+        }
+        // Find files matching the pattern, filter to actual files only
+        const allFiles = await glob(pattern, { absolute: true });
+        const files = allFiles.filter((f) => {
+            try {
+                return fs.statSync(f).isFile();
+            }
+            catch {
+                return false;
+            }
+        });
+        if (files.length === 0) {
+            throw new Error(`No files found matching pattern: ${input}`);
+        }
+        logger.section('Compiling Workflows');
+        logger.info(`Found ${files.length} file(s)`);
+        logger.info(`Module format: ${moduleFormat.toUpperCase()}`);
+        if (sourceMap) {
+            logger.info('Source maps: enabled');
+        }
+        if (verbose) {
+            files.forEach((file) => logger.info(`  - ${file}`));
+        }
+        logger.newline();
+        let successCount = 0;
+        let errorCount = 0;
+        for (let i = 0; i < files.length; i++) {
+            const file = files[i];
+            const fileName = path.basename(file);
+            logger.progress(i + 1, files.length, fileName);
+            try {
+                // Skip files without @flowWeaver annotations before parsing
+                const rawSource = fs.readFileSync(file, 'utf8');
+                if (!rawSource.includes('@flowWeaver')) {
+                    if (verbose) {
+                        logger.info(`  Skipped ${fileName} (no @flowWeaver annotations)`);
+                    }
+                    continue;
+                }
+                // Parse the workflow
+                const parseResult = await parseWorkflow(file, { workflowName });
+                if (parseResult.warnings.length > 0) {
+                    parseResult.warnings.forEach((w) => logger.warn(`  ${w}`));
+                }
+                if (parseResult.errors.length > 0) {
+                    // Skip non-workflow files silently (only error is "No workflows found")
+                    const isNonWorkflowFile = parseResult.errors.length === 1 &&
+                        typeof parseResult.errors[0] === 'string' &&
+                        parseResult.errors[0].startsWith('No workflows found');
+                    if (isNonWorkflowFile) {
+                        if (verbose) {
+                            logger.info(`  Skipped ${fileName} (no workflow)`);
+                        }
+                        continue;
+                    }
+                    logger.error(`Failed to parse ${fileName}:`);
+                    parseResult.errors.forEach((err) => logger.error(`  ${err}`));
+                    errorCount++;
+                    continue;
+                }
+                // Validate the AST (especially for --strict mode)
+                if (strict) {
+                    const validation = validator.validate(parseResult.ast, { strictMode: true });
+                    if (validation.errors.length > 0) {
+                        logger.error(`Validation errors in ${fileName}:`);
+                        validation.errors.forEach((err) => {
+                            const friendly = getFriendlyError(err);
+                            if (friendly) {
+                                const loc = err.location ? `[line ${err.location.line}] ` : '';
+                                logger.error(`  ${loc}${friendly.title}: ${friendly.explanation}`);
+                                logger.info(`    How to fix: ${friendly.fix}`);
+                            }
+                            else {
+                                let msg = `  - ${err.message}`;
+                                if (err.node) {
+                                    msg += ` (node: ${err.node})`;
+                                }
+                                logger.error(msg);
+                            }
+                        });
+                        errorCount++;
+                        continue;
+                    }
+                    if (validation.warnings.length > 0 && verbose) {
+                        validation.warnings.forEach((warn) => {
+                            const friendly = getFriendlyError(warn);
+                            if (friendly) {
+                                const loc = warn.location ? `[line ${warn.location.line}] ` : '';
+                                logger.warn(`  ${loc}${friendly.title}: ${friendly.explanation}`);
+                                logger.info(`    How to fix: ${friendly.fix}`);
+                            }
+                            else {
+                                logger.warn(`  ${warn.message}`);
+                            }
+                        });
+                    }
+                }
+                // Read original source
+                const sourceCode = fs.readFileSync(file, 'utf8');
+                // Generate code in-place (preserves types, interfaces, etc.)
+                const result = generateInPlace(sourceCode, parseResult.ast, { production, moduleFormat, inlineRuntime, sourceFile: file, skipParamReturns: clean });
+                // Write back to original file (skip in dry-run mode)
+                if (!dryRun) {
+                    fs.writeFileSync(file, result.code, 'utf8');
+                    // Generate source map if requested
+                    if (sourceMap) {
+                        const mapResult = generateCode(parseResult.ast, {
+                            production,
+                            sourceMap: true,
+                            moduleFormat,
+                        });
+                        if (mapResult.sourceMap) {
+                            const mapPath = file + '.map';
+                            fs.writeFileSync(mapPath, mapResult.sourceMap, 'utf8');
+                            // Append sourceMappingURL comment to the compiled file
+                            const sourceMappingComment = `\n//# sourceMappingURL=${path.basename(mapPath)}\n`;
+                            if (!result.code.includes('//# sourceMappingURL=')) {
+                                fs.appendFileSync(file, sourceMappingComment, 'utf8');
+                            }
+                            if (verbose) {
+                                logger.info(`  Source map: ${mapPath}`);
+                            }
+                        }
+                    }
+                }
+                if (dryRun) {
+                    if (result.hasChanges) {
+                        logger.success(`  Would compile: ${file}`);
+                    }
+                    else if (verbose) {
+                        logger.info(`  No changes: ${file}`);
+                    }
+                }
+                else if (result.hasChanges) {
+                    logger.success(`  Compiled: ${file}`);
+                }
+                else if (verbose) {
+                    logger.info(`  No changes: ${file}`);
+                }
+                successCount++;
+            }
+            catch (error) {
+                logger.error(`Failed to compile ${fileName}: ${getErrorMessage(error)}`);
+                errorCount++;
+            }
+        }
+        // Summary
+        logger.newline();
+        logger.section('Summary');
+        logger.success(`${successCount} file(s) compiled successfully`);
+        if (errorCount > 0) {
+            throw new Error(`${errorCount} file(s) failed to compile`);
+        }
+    }
+    catch (error) {
+        if (error instanceof Error && error.message.includes('file(s) failed')) {
+            throw error;
+        }
+        throw new Error(`Compilation failed: ${getErrorMessage(error)}`);
+    }
+}
+/**
+ * Compile a workflow file to Inngest function code with per-node step.run().
+ */
+export async function compileInngestTarget(input, options) {
+    const filePath = path.resolve(input);
+    if (!fs.existsSync(filePath)) {
+        throw new Error(`File not found: ${filePath}`);
+    }
+    logger.section('Compiling to Inngest');
+    logger.info(`Input: ${filePath}`);
+    logger.info(`Target: Inngest (per-node step.run)`);
+    logger.newline();
+    const parser = new AnnotationParser();
+    const parseResult = parser.parse(filePath);
+    if (parseResult.errors.length > 0) {
+        const msgs = parseResult.errors.map((e) => `  ${e}`).join('\n');
+        throw new Error(`Parse errors:\n${msgs}`);
+    }
+    if (parseResult.workflows.length === 0) {
+        throw new Error('No workflows found in file');
+    }
+    const workflow = options.workflowName
+        ? parseResult.workflows.find((w) => w.name === options.workflowName || w.functionName === options.workflowName)
+        : parseResult.workflows[0];
+    if (!workflow) {
+        const available = parseResult.workflows.map((w) => w.name).join(', ');
+        throw new Error(`Workflow "${options.workflowName}" not found. Available: ${available}`);
+    }
+    const allNodeTypes = [...(workflow.nodeTypes || [])];
+    // CLI overrides for workflow options
+    if (options.cron) {
+        workflow.options = workflow.options || {};
+        workflow.options.trigger = { ...workflow.options.trigger, cron: options.cron };
+    }
+    if (options.retries !== undefined) {
+        workflow.options = workflow.options || {};
+        workflow.options.retries = options.retries;
+    }
+    if (options.timeout) {
+        workflow.options = workflow.options || {};
+        workflow.options.timeout = options.timeout;
+    }
+    const code = generateInngestFunction(workflow, allNodeTypes, {
+        production: options.production,
+        typedEvents: options.typedEvents,
+        serveHandler: options.serve,
+        framework: options.framework,
+    });
+    const outputPath = filePath.replace(/\.ts$/, '.inngest.ts');
+    if (options.dryRun) {
+        logger.success(`Would generate: ${outputPath}`);
+        logger.newline();
+        logger.section('Preview');
+        const lines = code.split('\n');
+        const preview = lines.slice(0, 50).join('\n');
+        logger.log(preview);
+        if (lines.length > 50) {
+            logger.info(`... (${lines.length - 50} more lines)`);
+        }
+    }
+    else {
+        fs.writeFileSync(outputPath, code, 'utf8');
+        logger.success(`Compiled: ${outputPath}`);
+    }
+    logger.newline();
+    logger.section('Summary');
+    logger.success(`Workflow "${workflow.name}" compiled to Inngest function`);
+    logger.info('Each node is wrapped in step.run() for per-node durability');
+}
+//# sourceMappingURL=compile.js.map

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

@@ -0,0 +1,33 @@
+/**
+ * Create command - scaffolds workflows and nodes from templates
+ */
+export interface CreateWorkflowOptions {
+    line?: number;
+    async?: boolean;
+    preview?: boolean;
+    provider?: string;
+    model?: string;
+    config?: string;
+    name?: string;
+    nodes?: string;
+    input?: string;
+    output?: string;
+}
+export interface CreateNodeOptions {
+    line?: number;
+    preview?: boolean;
+    config?: string;
+    strategy?: string;
+}
+/**
+ * Create a workflow from a template
+ */
+export declare function createWorkflowCommand(template: string, file: string, options?: CreateWorkflowOptions): Promise<void>;
+/**
+ * Create a node type from a template
+ * Uses processor template by default
+ */
+export declare function createNodeCommand(name: string, file: string, options?: CreateNodeOptions & {
+    template?: string;
+}): Promise<void>;
+//# sourceMappingURL=create.d.ts.map

package/dist/cli/commands/create.js

@@ -0,0 +1,147 @@
+/* eslint-disable no-console */
+/**
+ * Create command - scaffolds workflows and nodes from templates
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { getWorkflowTemplate, getNodeTemplate, toCamelCase } from '../templates/index.js';
+import { logger } from '../utils/logger.js';
+import { getErrorMessage } from '../../utils/error-utils.js';
+/**
+ * Insert content at a specific line or append to end of file
+ */
+function insertIntoFile(filePath, content, line) {
+    // Create file if it doesn't exist
+    if (!fs.existsSync(filePath)) {
+        const dir = path.dirname(filePath);
+        if (!fs.existsSync(dir)) {
+            fs.mkdirSync(dir, { recursive: true });
+        }
+        fs.writeFileSync(filePath, content + '\n');
+        return;
+    }
+    const existingContent = fs.readFileSync(filePath, 'utf8');
+    const lines = existingContent.split('\n');
+    if (line !== undefined && line > 0) {
+        // Insert AFTER specific line (1-indexed)
+        // Line 3 means insert after line 3, so at index 3
+        const insertIndex = Math.min(line, lines.length);
+        lines.splice(insertIndex, 0, content);
+    }
+    else {
+        // Append to end
+        lines.push('', content);
+    }
+    fs.writeFileSync(filePath, lines.join('\n'));
+}
+/**
+ * Create a workflow from a template
+ */
+export async function createWorkflowCommand(template, file, options = {}) {
+    const { line, async: isAsync = false, preview = false, provider, model, config: configJson, } = options;
+    const templateDef = getWorkflowTemplate(template);
+    if (!templateDef) {
+        logger.error(`Unknown workflow template: ${template}`);
+        logger.info("Run 'flow-weaver templates' to see available templates");
+        process.exit(1);
+    }
+    // Resolve to absolute path
+    const filePath = path.resolve(file);
+    // Derive workflow name from filename (or use --name override)
+    const baseName = path.basename(filePath, path.extname(filePath));
+    const workflowName = options.name || toCamelCase(baseName);
+    // Build config object from options
+    const config = {};
+    if (provider)
+        config.provider = provider;
+    if (model)
+        config.model = model;
+    if (options.nodes)
+        config.nodes = options.nodes.split(',').map((n) => n.trim());
+    if (options.input)
+        config.input = options.input;
+    if (options.output)
+        config.output = options.output;
+    if (configJson) {
+        try {
+            Object.assign(config, JSON.parse(configJson));
+        }
+        catch {
+            logger.error('Invalid --config JSON');
+            process.exit(1);
+        }
+    }
+    // Generate the template code
+    const code = templateDef.generate({
+        workflowName,
+        async: isAsync,
+        config: Object.keys(config).length > 0 ? config : undefined,
+    });
+    // Preview mode: just output the code
+    if (preview) {
+        console.log(code);
+        return;
+    }
+    try {
+        insertIntoFile(filePath, code, line);
+        logger.success(`Created ${templateDef.name} workflow in ${file}`);
+        if (line) {
+            logger.info(`  Inserted at line ${line}`);
+        }
+        logger.info(`  Workflow function: ${workflowName}`);
+    }
+    catch (error) {
+        logger.error(`Failed to create workflow: ${getErrorMessage(error)}`);
+        process.exit(1);
+    }
+}
+/**
+ * Create a node type from a template
+ * Uses processor template by default
+ */
+export async function createNodeCommand(name, file, options = {}) {
+    const { line, template = 'processor', preview = false, strategy, config: configJson } = options;
+    const templateDef = getNodeTemplate(template);
+    if (!templateDef) {
+        logger.error(`Unknown node template: ${template}`);
+        logger.info("Run 'flow-weaver templates' to see available templates");
+        process.exit(1);
+    }
+    // Resolve to absolute path
+    const filePath = path.resolve(file);
+    // Build config object from options
+    const config = {};
+    if (strategy)
+        config.strategy = strategy;
+    if (configJson) {
+        try {
+            Object.assign(config, JSON.parse(configJson));
+        }
+        catch {
+            logger.error('Invalid --config JSON');
+            process.exit(1);
+        }
+    }
+    // Generate the template code with provided name and optional config
+    const nodeName = toCamelCase(name);
+    const nodeConfig = Object.keys(config).length > 0 ? config : undefined;
+    const code = templateDef.generate(nodeName, nodeConfig);
+    // Preview mode: just output the code
+    if (preview) {
+        console.log(code);
+        return;
+    }
+    try {
+        insertIntoFile(filePath, code, line);
+        logger.success(`Created ${templateDef.name} node in ${file}`);
+        if (line) {
+            logger.info(`  Inserted at line ${line}`);
+        }
+        logger.info(`  Node function: ${nodeName}`);
+    }
+    catch (error) {
+        logger.error(`Failed to create node: ${getErrorMessage(error)}`);
+        process.exit(1);
+    }
+}
+//# sourceMappingURL=create.js.map

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

@@ -0,0 +1,68 @@
+/**
+ * Describe command - outputs workflow structure in LLM-friendly formats
+ */
+import type { TWorkflowAST, TNodeInstanceAST, TNodeTypeAST } from '../../ast/types.js';
+export interface DescribeOptions {
+    format?: 'json' | 'text' | 'mermaid' | 'paths';
+    node?: string;
+    workflowName?: string;
+    compile?: boolean;
+}
+export interface NodeInfo {
+    id: string;
+    type: string;
+    inputs: string[];
+    outputs: string[];
+}
+export interface ConnectionInfo {
+    from: string;
+    to: string;
+}
+export interface DescribeOutput {
+    name: string;
+    description: string | null;
+    nodes: NodeInfo[];
+    connections: ConnectionInfo[];
+    graph: string;
+    validation: {
+        valid: boolean;
+        errors: string[];
+        warnings: string[];
+    };
+}
+export interface FocusedNodeOutput {
+    focusNode: string;
+    node: NodeInfo;
+    incoming: ConnectionInfo[];
+    outgoing: ConnectionInfo[];
+    validation: {
+        valid: boolean;
+        errors: string[];
+        warnings: string[];
+    };
+}
+export declare function buildNodeInfo(instance: TNodeInstanceAST, nodeType: TNodeTypeAST | undefined): NodeInfo;
+/**
+ * Enumerate all Start-to-Exit paths via DFS.
+ * Returns an array of path arrays (each path is string[] including Start and Exit).
+ */
+export declare function enumeratePaths(ast: TWorkflowAST): string[][];
+export declare function buildGraph(ast: TWorkflowAST): string;
+export declare function formatPaths(ast: TWorkflowAST): string;
+export declare function generateMermaid(ast: TWorkflowAST): string;
+/**
+ * Pure function to describe a workflow - no I/O, returns data
+ */
+export declare function describeWorkflow(ast: TWorkflowAST, options?: {
+    node?: string;
+}): DescribeOutput | FocusedNodeOutput;
+/**
+ * Generate structured human-readable text output
+ */
+export declare function formatTextOutput(ast: TWorkflowAST, output: DescribeOutput | FocusedNodeOutput): string;
+/**
+ * Format the describe output based on format option
+ */
+export declare function formatDescribeOutput(ast: TWorkflowAST, output: DescribeOutput | FocusedNodeOutput, format: 'json' | 'text' | 'mermaid' | 'paths'): string;
+export declare function describeCommand(input: string, options?: DescribeOptions): Promise<void>;
+//# sourceMappingURL=describe.d.ts.map