@synergenius/flow-weaver 0.29.1 → 0.30.1

package/README.md

@@ -18,15 +18,27 @@ Flow Weaver is a TypeScript workflow compiler. Define workflows with JSDoc annot
 
 Build AI agent workflows, data pipelines, or automation scripts through natural language using MCP tools in Claude Code, Cursor, Windsurf, VS Code, JetBrains, Codex, or any MCP-compatible editor. Or write them by hand with annotations the same way you write JSDoc today.
 
-## Project Status
+## About me & my vision
+
+Hey, I am [Ricardo Morais](https://linkedin.com/in/moraispgsi), the project's founder and owner. 
+
+I have always wondered why Visual Programming never took off. After understanding why I tried to address most of the concerns from the development community:
+  - No lock-in: code is compiled and yours, not dependent on this library. You can remove the annotation after compiling and the file is standalone.
+  - The code is the source of truth, visual part runs on top, this allows you to create your workflows visually in the Studio, at the end of the day it is just plain Typescript code that you or any LLM can understand and iterate.
+  - It being just code opens a lot of doors for you, like using Git for version control, doing all sort of stuff you already do with code like testing, linting, automating, everything.
+  - In the era of LLMs and agents, being able to have that control is crucial, it is not a black box, you can see everything and so can your assistant.
 
-Flow Weaver is in **active alpha**. The compiler, validator, CLI, and MCP tools are stable and thoroughly tested. The test suite covers thousands of cases across parsing, compilation, validation, diffing, and deployment. CI runs on every commit.
+As of now this is a solo project and I am building it in the open. There is a lot to do and rough edges to smooth out. If you run into issues or have questions, the [Discord](https://discord.gg/6Byh3ur2bk) is the best place to reach out. Every issue and question gets a response. I genuinely want to hear from you.
+
+If this resonates with what you have been looking for, give it a try and let me know how it goes. Stars, feedback, and honest criticism all help equally.
+
+## Project Status
 
-This started as a curiosity by [Ricardo Morais](https://linkedin.com/in/moraispgsi) into why visual programming never took off and whether code-first and visual editing could actually coexist. It has grown into something real. It is actively maintained, with releases shipping regularly. If you run into issues or have questions, the [Discord](https://discord.gg/6Byh3ur2bk) is the best place to reach out. Every issue and question gets a response, usually within a day.
+Flow Weaver is in **beta**. The compiler, validator, CLI, and MCP tools are stable and thoroughly tested. The test suite covers thousands of cases across parsing, compilation, validation, diffing, and deployment. CI runs on every commit.
 
 **Flow Weaver Studio**, the browser-based visual IDE, is the next major milestone and is being actively built. Core editing (canvas, terminal, diagnostics) is live today. The visual debugger, AI chat assistant, version history, and deployment dashboard are in progress. You can follow development on Discord or in the [GitHub releases](https://github.com/synergenius-fw/flow-weaver/releases).
 
-Breaking changes may occur between minor versions during alpha. Pin your version in `package.json` if stability matters for your project.
+Breaking changes may still occur between minor versions during beta. Pin your version in `package.json` if stability matters for your project.
 
 ## Capabilities
 
@@ -224,11 +236,11 @@ export async function supportAgent(
 
 Run `fw --help` or `fw <command> --help` for full options.
 
-## Flow Weaver Studio (Early Beta)
+## Flow Weaver Studio (Beta)
 
 A browser-based visual IDE for building workflows. Canvas editor, integrated terminal, real-time diagnostics, and the full CLI available in the cloud.
 
-Studio is in early beta. Core editing is live. The visual debugger, AI chat assistant, version history, and deployment dashboard are being actively developed and will ship incrementally. The cloud platform is not yet production-ready, and paid plans are not available yet. Use it to explore and experiment, but expect rough edges.
+Studio is in beta. Core editing is live. The visual debugger, AI chat assistant, version history, and deployment dashboard are being actively developed and will ship incrementally. The cloud platform is not yet production-ready, and paid plans are not available yet. Use it to explore and experiment, but expect rough edges.
 
 [Open Studio](https://flowweaver.ai/studio) · [Learn more](https://flowweaver.ai/features)
 

package/dist/cli/commands/compile.js

@@ -137,48 +137,50 @@ export async function compileCommand(input, options = {}) {
                 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(`  ${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.warn(`    How to fix: ${friendly.fix}`);
-                            if (err.docUrl) {
-                                logger.warn(`    See: ${err.docUrl}`);
-                            }
+            // Validate the AST
+            const validation = validator.validate(parseResult.ast, { strictMode: strict });
+            // In strict mode, validation errors block compilation
+            if (strict && validation.errors.length > 0) {
+                logger.error(`  ${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.warn(`    How to fix: ${friendly.fix}`);
+                        if (err.docUrl) {
+                            logger.warn(`    See: ${err.docUrl}`);
                         }
-                        else {
-                            let msg = `    ${err.message}`;
-                            if (err.node) {
-                                msg += ` (node: ${err.node})`;
-                            }
-                            logger.error(msg);
-                            if (err.docUrl) {
-                                logger.warn(`    See: ${err.docUrl}`);
-                            }
+                    }
+                    else {
+                        let msg = `    ${err.message}`;
+                        if (err.node) {
+                            msg += ` (node: ${err.node})`;
                         }
-                    });
-                    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.warn(`    How to fix: ${friendly.fix}`);
+                        logger.error(msg);
+                        if (err.docUrl) {
+                            logger.warn(`    See: ${err.docUrl}`);
                         }
-                        else {
-                            logger.warn(`  ${warn.message}`);
+                    }
+                });
+                errorCount++;
+                continue;
+            }
+            // Always show validation warnings (not just in verbose mode)
+            if (validation.warnings.length > 0) {
+                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}`);
+                        if (verbose) {
+                            logger.warn(`    How to fix: ${friendly.fix}`);
                         }
-                    });
-                }
+                    }
+                    else {
+                        logger.warn(`  ${warn.message}`);
+                    }
+                });
             }
             // Read original source
             const sourceCode = fs.readFileSync(file, 'utf8');

package/dist/cli/commands/describe.js

@@ -349,7 +349,7 @@ export async function describeCommand(input, options = {}) {
     }
     try {
         // Parse the workflow
-        const parseResult = await parseWorkflow(filePath, { workflowName });
+        const parseResult = await parseWorkflow(filePath, { workflowName, projectDir: path.dirname(filePath) });
         if (parseResult.errors.length > 0) {
             throw new Error(`Parse errors:\n${parseResult.errors.map((err) => `  ${err}`).join('\n')}`);
         }

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

@@ -13,6 +13,10 @@ export interface DevOptions extends DevModeOptions {
     clean?: boolean;
     /** Compilation target (default: typescript in-place) */
     target?: string;
+    /** Mock config for built-in nodes as JSON string */
+    mocks?: string;
+    /** Path to JSON file with mock config */
+    mocksFile?: string;
 }
 /**
  * Dev command: watch + compile + run in a single loop.

package/dist/cli/commands/dev.js

@@ -52,11 +52,38 @@ function parseParams(options) {
     }
     return {};
 }
+/**
+ * Parse mock config from --mocks or --mocks-file.
+ */
+function parseMocks(options) {
+    if (options.mocks) {
+        try {
+            return JSON.parse(options.mocks);
+        }
+        catch {
+            throw new Error(`Invalid JSON in --mocks: ${options.mocks}`);
+        }
+    }
+    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');
+            return JSON.parse(content);
+        }
+        catch {
+            throw new Error(`Failed to parse mocks file: ${options.mocksFile}`);
+        }
+    }
+    return undefined;
+}
 /**
  * Run a single compile + execute cycle.
  * Returns true if both compile and run succeeded.
  */
-async function compileAndRun(filePath, params, options) {
+async function compileAndRun(filePath, params, mocks, options) {
     // Step 1: Compile
     const compileOpts = {
         format: options.format,
@@ -96,6 +123,7 @@ async function compileAndRun(filePath, params, options) {
             workflowName: options.workflow,
             production: options.production ?? false,
             includeTrace: !options.production,
+            mocks,
         });
         if (options.json) {
             process.stdout.write(JSON.stringify({
@@ -143,16 +171,20 @@ export async function devCommand(input, options = {}) {
         throw new Error(`Unknown dev target "${options.target}". ${available.length ? `Available: ${available.join(', ')}` : 'No dev mode providers registered. Install a pack that provides one.'}`);
     }
     const params = parseParams(options);
+    const mocks = parseMocks(options);
     if (!options.json) {
         logger.section('Dev Mode');
         logger.info(`File: ${path.basename(filePath)}`);
         if (Object.keys(params).length > 0) {
             logger.info(`Params: ${JSON.stringify(params)}`);
         }
+        if (mocks) {
+            logger.info(`Mocks: ${JSON.stringify(mocks)}`);
+        }
         logger.newline();
     }
     // Initial compile + run
-    await compileAndRun(filePath, params, options);
+    await compileAndRun(filePath, params, mocks, options);
     // If --once, exit after first cycle
     if (options.once) {
         return;
@@ -173,7 +205,7 @@ export async function devCommand(input, options = {}) {
         if (!options.json) {
             cycleSeparator(file);
         }
-        await compileAndRun(filePath, params, options);
+        await compileAndRun(filePath, params, mocks, options);
     });
     // Handle process termination
     const cleanup = () => {

package/dist/cli/commands/diagram.js

@@ -5,6 +5,7 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import { fileToSVG, fileToHTML, fileToASCII } from '../../diagram/index.js';
+import { parser } from '../../parser.js';
 import { logger } from '../utils/logger.js';
 import { safeWriteFile } from '../utils/safe-write.js';
 const ASCII_FORMATS = new Set(['ascii', 'ascii-compact', 'text']);
@@ -14,6 +15,8 @@ export async function diagramCommand(input, options = {}) {
     if (!fs.existsSync(filePath)) {
         throw new Error(`File not found: ${filePath}`);
     }
+    // Load marketplace pack tag handlers before parsing
+    await parser.loadPackHandlers(path.dirname(filePath));
     let result;
     if (ASCII_FORMATS.has(format)) {
         result = fileToASCII(filePath, { ...diagramOptions, format });

package/dist/cli/commands/diff.js

@@ -21,8 +21,8 @@ export async function diffCommand(file1, file2, options = {}) {
     try {
         // Parse both workflows
         const [result1, result2] = await Promise.all([
-            parseWorkflow(filePath1, { workflowName }),
-            parseWorkflow(filePath2, { workflowName }),
+            parseWorkflow(filePath1, { workflowName, projectDir: path.dirname(filePath1) }),
+            parseWorkflow(filePath2, { workflowName, projectDir: path.dirname(filePath2) }),
         ]);
         if (result1.errors.length > 0) {
             throw new Error(`Parse errors in ${file1}:\n${result1.errors.map((err) => `  ${err}`).join('\n')}`);

package/dist/cli/commands/run.js

@@ -184,7 +184,7 @@ async function runCommandInner(input, options) {
             let executionOrder = resumeExecutionOrder;
             if (!executionOrder) {
                 const source = fs.readFileSync(filePath, 'utf8');
-                const parsed = await parseWorkflow(source, { workflowName: options.workflow });
+                const parsed = await parseWorkflow(source, { workflowName: options.workflow, projectDir: path.dirname(filePath) });
                 if (parsed.errors.length === 0) {
                     executionOrder = getTopologicalOrder(parsed.ast);
                 }
@@ -427,7 +427,7 @@ export async function validateMockConfig(mocks, filePath, workflowName) {
     }
     // Quick-parse the workflow to check which built-in node types are used
     try {
-        const result = await parseWorkflow(filePath, { workflowName });
+        const result = await parseWorkflow(filePath, { workflowName, projectDir: path.dirname(filePath) });
         if (result.errors.length > 0 || !result.ast?.instances)
             return;
         const usedNodeTypes = new Set(result.ast.instances.map((i) => i.nodeType));

package/dist/cli/commands/serve.js

@@ -30,6 +30,17 @@ import { logger } from '../utils/logger.js';
  * ```
  */
 export async function serveCommand(dir, options) {
+    // Check fastify is installed before proceeding
+    try {
+        await import('fastify');
+    }
+    catch {
+        logger.error('The serve command requires fastify. Install it with:');
+        logger.newline();
+        logger.log('  npm install fastify');
+        logger.newline();
+        process.exit(1);
+    }
     const workflowDir = path.resolve(dir || '.');
     // Validate directory exists
     if (!fs.existsSync(workflowDir)) {

package/dist/cli/commands/validate.js

@@ -62,7 +62,7 @@ export async function validateCommand(input, options = {}) {
             }
             try {
                 // Parse the workflow
-                const parseResult = await parseWorkflow(file, { workflowName, projectDir: process.cwd() });
+                const parseResult = await parseWorkflow(file, { workflowName, projectDir: path.dirname(path.resolve(file)) });
                 if (parseResult.warnings.length > 0) {
                     if (!json && !quiet) {
                         logger.warn(`Parse warnings in ${fileName}:`);