@synergenius/flow-weaver 0.33.1 → 0.44.0

package/dist/cli/flow-weaver-chunk-J7EPZW2I.mjs

@@ -0,0 +1,33 @@
+import { createRequire as __createRequire } from "module";
+const require = __createRequire(import.meta.url);
+import {
+  registerPackDocTopics
+} from "./flow-weaver-chunk-XG2WKXYZ.mjs";
+import {
+  discoverDocTopics
+} from "./flow-weaver-chunk-4DVY73ML.mjs";
+
+// src/docs/pack-topics.ts
+import * as fs from "fs";
+async function loadPackDocTopics(projectDir = process.cwd()) {
+  let topics;
+  try {
+    topics = await discoverDocTopics(projectDir);
+  } catch {
+    return 0;
+  }
+  const present = topics.filter((topic) => {
+    if (fs.existsSync(topic.absoluteFile)) return true;
+    process.stderr.write(
+      `[docs] ${topic.packageName} declares topic "${topic.slug}" but ${topic.absoluteFile} does not exist
+`
+    );
+    return false;
+  });
+  registerPackDocTopics(present);
+  return present.length;
+}
+
+export {
+  loadPackDocTopics
+};

package/dist/cli/flow-weaver-chunk-KOEMJHLG.mjs

@@ -0,0 +1,83 @@
+import { createRequire as __createRequire } from "module";
+const require = __createRequire(import.meta.url);
+
+// src/mcp/response-utils.ts
+function makeToolResult(data) {
+  return {
+    content: [{ type: "text", text: JSON.stringify({ success: true, data }, null, 2) }]
+  };
+}
+function makeErrorResult(code, message) {
+  return {
+    content: [
+      {
+        type: "text",
+        text: JSON.stringify({ success: false, error: { code, message } }, null, 2)
+      }
+    ],
+    isError: true
+  };
+}
+var ERROR_HINTS = {
+  UNKNOWN_NODE_TYPE: 'Run fw_query(query="node-types") to see available types',
+  UNKNOWN_SOURCE_NODE: 'Run fw_query(query="nodes") to see all node instances',
+  UNKNOWN_TARGET_NODE: 'Run fw_query(query="nodes") to see all node instances',
+  UNKNOWN_SOURCE_PORT: 'Run fw_describe(node="<nodeId>") to see available ports. Use fw_modify(operation="addConnection") to safely wire ports.',
+  UNKNOWN_TARGET_PORT: 'Run fw_describe(node="<nodeId>") to see available ports. Use fw_modify(operation="addConnection") to safely wire ports.',
+  MISSING_REQUIRED_INPUT: "Add a @connect to this port, or make it optional with @input portName [optional]",
+  CYCLE_DETECTED: 'Use a scoped forEach node instead of graph loops. See fw_docs "advanced-annotations"',
+  STEP_PORT_TYPE_MISMATCH: "STEP ports (execute, onSuccess, onFailure) can only connect to other STEP ports",
+  MULTIPLE_CONNECTIONS_TO_INPUT: "A data input takes one connection unless the port declares how to combine several: `@input name [mergeStrategy:FIRST|LAST|COLLECT|MERGE|CONCAT]` on the node type. Otherwise use separate ports",
+  UNUSED_NODE: 'Connect this node or remove it with fw_modify(operation="removeNode")',
+  EXPRESSION_SYNTAX: `An [expr:] value is JavaScript. Text needs quotes inside the attribute (timeout="'24h'"). An upstream port is read as node.port (agentId="prep.agentId"). See advanced-annotations`,
+  NO_START_CONNECTIONS: 'Add @connect Start.portName -> node.port, or use fw_modify(operation="addConnection") to wire it.',
+  NO_EXIT_CONNECTIONS: 'Add @connect node.port -> Exit.portName, or use fw_modify(operation="addConnection") to wire it.',
+  UNREACHABLE_EXIT_PORT: 'Use fw_modify(operation="addConnection") to connect a node output to this Exit port.',
+  RESERVED_NODE_NAME: 'Rename the node type. "Start" and "Exit" are reserved',
+  RESERVED_INSTANCE_ID: 'Rename the instance. "Start" and "Exit" are reserved IDs',
+  MULTIPLE_WORKFLOWS_FOUND: "Specify workflowName parameter to select which workflow to use",
+  DUPLICATE_NODE_NAME: "Rename one of the duplicate node type functions to be unique",
+  INVALID_EXIT_PORT_TYPE: "Ensure Exit onSuccess/onFailure ports are STEP type (auto-generated)",
+  // Agent-specific rules
+  AGENT_LLM_MISSING_ERROR_HANDLER: 'Use fw_modify(operation="addConnection", params={from:"<nodeId>.onFailure", to:"Exit.onFailure"}) or add a retry/fallback node',
+  AGENT_UNGUARDED_TOOL_EXECUTOR: 'Add a human-approval node before the tool executor. Use fw_scaffold(template="human-approval") to create one',
+  AGENT_MISSING_MEMORY_IN_LOOP: 'Add a conversation-memory node inside the loop scope. Use fw_scaffold(template="conversation-memory") to create one',
+  AGENT_LLM_NO_FALLBACK: "Add a retry or fallback node between the LLM onFailure and Exit. Consider a second LLM provider as fallback",
+  AGENT_TOOL_NO_OUTPUT_HANDLING: 'Use fw_modify(operation="addConnection") to wire tool output ports to downstream nodes',
+  // Design quality rules
+  DESIGN_ASYNC_NO_ERROR_PATH: 'Normal-mode node: fw_modify(operation="addConnection", params={from:"<nodeId>.onFailure", to:"Exit.onFailure"}) or add a retry/error handler. @expression node: a throw aborts the run and wiring onFailure changes nothing; rewrite the node in normal mode returning onFailure to route the failure, or add [suppress: "DESIGN_ASYNC_NO_ERROR_PATH"] if aborting is intended',
+  DESIGN_SCOPE_NO_FAILURE_EXIT: 'Use fw_modify(operation="addConnection", params={from:"<nodeId>.onFailure", to:"Exit.onFailure"}) to surface scope failures',
+  DESIGN_UNBOUNDED_RETRY: "Add a maxAttempts or retries input port to the retry node type to bound the loop",
+  DESIGN_FANOUT_NO_FANIN: "Add a merge node downstream where parallel branches converge before Exit",
+  DESIGN_EXIT_DATA_UNREACHABLE: 'Use fw_modify(operation="addConnection") to connect a node output to this Exit port, or add a pull-execution node',
+  DESIGN_PULL_CANDIDATE: "Add [pullExecution: execute] to the @node annotation so the node runs on demand",
+  DESIGN_PULL_UNUSED: "Connect a data output from this node to a downstream consumer, or remove pullExecution"
+};
+function addHintsToItems(items, friendlyErrorFn) {
+  return items.map((item) => {
+    if (!item.code) return item;
+    const result = { ...item };
+    let hint = ERROR_HINTS[item.code];
+    if (hint) {
+      if (item.nodeId && hint.includes("<nodeId>")) {
+        hint = hint.replace(/<nodeId>/g, item.nodeId);
+      }
+      result.hint = hint;
+      return result;
+    }
+    if (friendlyErrorFn) {
+      const friendly = friendlyErrorFn({ code: item.code, message: item.message, node: item.nodeId });
+      if (friendly?.fix) {
+        result.fix = friendly.fix;
+      }
+    }
+    return result;
+  });
+}
+
+export {
+  makeToolResult,
+  makeErrorResult,
+  ERROR_HINTS,
+  addHintsToItems
+};

package/dist/cli/flow-weaver-chunk-M6CBWQKJ.mjs

@@ -0,0 +1,271 @@
+import { createRequire as __createRequire } from "module";
+const require = __createRequire(import.meta.url);
+import {
+  getFriendlyError
+} from "./flow-weaver-chunk-S63Q3JIU.mjs";
+import {
+  generateCode
+} from "./flow-weaver-chunk-V6DHWFQG.mjs";
+import {
+  detectProjectModuleFormat
+} from "./flow-weaver-chunk-U3EO3X4B.mjs";
+import {
+  validateWorkflow
+} from "./flow-weaver-chunk-ZQALO25T.mjs";
+import {
+  safeAppendFile,
+  safeWriteFile
+} from "./flow-weaver-chunk-NYZDQYFU.mjs";
+import {
+  generateInPlace
+} from "./flow-weaver-chunk-A6M5K3W7.mjs";
+import {
+  isMultipleWorkflows,
+  parseWorkflow,
+  parseWorkflowSourceAtPath
+} from "./flow-weaver-chunk-W3YNK26P.mjs";
+import {
+  logger
+} from "./flow-weaver-chunk-RIWE7YTR.mjs";
+import {
+  getErrorMessage
+} from "./flow-weaver-chunk-OMVWSNHJ.mjs";
+import {
+  Ze
+} from "./flow-weaver-chunk-GAQXZHNO.mjs";
+
+// src/cli/commands/compile.ts
+import * as fs from "fs";
+import * as path from "path";
+function reportValidation(label, validation, verbose) {
+  if (validation.errors.length > 0) {
+    logger.error(`  ${label}`);
+    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}`);
+        }
+      }
+    });
+    return false;
+  }
+  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}`);
+      }
+    });
+  }
+  return true;
+}
+function displayPath(filePath) {
+  const rel = path.relative(process.cwd(), filePath);
+  if (rel && !rel.startsWith("..") && rel.length < filePath.length) {
+    return rel;
+  }
+  return filePath;
+}
+function resolveModuleFormat(format, cwd) {
+  if (format === "esm" || format === "cjs") {
+    return format;
+  }
+  const detection = detectProjectModuleFormat(cwd);
+  return detection.format;
+}
+async function compileCommand(input, options = {}) {
+  const { production = false, sourceMap = false, strict = false, verbose = false, workflowName, dryRun = false, format, clean = false, output } = options;
+  const cwd = process.cwd();
+  const moduleFormat = resolveModuleFormat(format, cwd);
+  let pattern = input;
+  try {
+    if (fs.existsSync(input) && fs.statSync(input).isDirectory()) {
+      pattern = path.join(input, "**/*.ts");
+    }
+  } catch {
+  }
+  const allFiles = await Ze(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}`);
+  }
+  let outputDir;
+  let outputFile;
+  if (output) {
+    const isOutputDir = output.endsWith("/") || output.endsWith(path.sep) || fs.existsSync(output) && fs.statSync(output).isDirectory();
+    if (isOutputDir) {
+      outputDir = output.endsWith("/") || output.endsWith(path.sep) ? output.slice(0, -1) : output;
+      if (!fs.existsSync(outputDir)) {
+        fs.mkdirSync(outputDir, { recursive: true });
+      }
+    } else if (files.length > 1) {
+      throw new Error(
+        `Cannot use --output with a file path when compiling multiple files. Use a directory path instead (e.g. --output ${output}/)`
+      );
+    } else {
+      outputFile = path.resolve(output);
+    }
+  }
+  const totalTimer = logger.timer();
+  logger.section("Compiling Workflows");
+  if (verbose) {
+    logger.info(`Found ${files.length} file(s)`);
+    logger.info(`Module format: ${moduleFormat.toUpperCase()}`);
+    if (sourceMap) {
+      logger.info("Source maps: enabled");
+    }
+    files.forEach((file) => logger.info(`  ${displayPath(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);
+    const fileTimer = logger.timer();
+    try {
+      const rawSource = fs.readFileSync(file, "utf8");
+      if (!rawSource.includes("@flowWeaver")) {
+        if (verbose) {
+          logger.info(`  ${logger.dim("skip")} ${fileName} ${logger.dim("(no @flowWeaver annotations)")}`);
+        }
+        continue;
+      }
+      const parseResult = await parseWorkflow(file, { workflowName, projectDir: cwd });
+      if (!workflowName && isMultipleWorkflows(parseResult.errors) && parseResult.availableWorkflows.length > 1) {
+        let code = rawSource;
+        let failed = false;
+        for (const name of parseResult.availableWorkflows) {
+          const label = `${fileName} (${name})`;
+          const one = await parseWorkflowSourceAtPath(file, code, { workflowName: name, projectDir: cwd });
+          if (one.errors.length > 0) {
+            logger.error(`  ${label}`);
+            one.errors.forEach((err) => logger.error(`    ${err}`));
+            failed = true;
+            break;
+          }
+          if (!reportValidation(label, validateWorkflow(one.ast, strict ? { mode: "strict" } : void 0), verbose)) {
+            failed = true;
+            break;
+          }
+          code = generateInPlace(code, one.ast, { production, moduleFormat, sourceFile: file, skipParamReturns: clean }).code;
+        }
+        if (failed) {
+          errorCount++;
+          continue;
+        }
+        const writePath2 = outputFile ? outputFile : outputDir ? path.join(outputDir, path.basename(file)) : file;
+        const changed = code !== rawSource;
+        if (!dryRun && changed) safeWriteFile(writePath2, code);
+        if (sourceMap) logger.warn(`  ${fileName}: source maps are only written for files with one workflow`);
+        const names = logger.dim(`(${parseResult.availableWorkflows.join(", ")})`);
+        if (changed) logger.success(`${displayPath(file)} ${names} ${logger.dim(fileTimer.elapsed())}${dryRun ? ` ${logger.dim("(dry run)")}` : ""}`);
+        else if (verbose || dryRun) logger.log(`  ${displayPath(file)} ${names} ${logger.dim(dryRun ? "(no changes, dry run)" : "no changes")}`);
+        successCount++;
+        continue;
+      }
+      if (parseResult.warnings.length > 0 && verbose) {
+        logger.warn(`Parse warnings in ${fileName}:`);
+        parseResult.warnings.forEach((w) => logger.warn(`  ${w}`));
+      }
+      if (parseResult.errors.length > 0) {
+        const isNonWorkflowFile = parseResult.errors.length === 1 && typeof parseResult.errors[0] === "string" && parseResult.errors[0].startsWith("No workflows found");
+        if (isNonWorkflowFile) {
+          if (verbose) {
+            logger.info(`  ${logger.dim("skip")} ${fileName} ${logger.dim("(no workflow)")}`);
+          }
+          continue;
+        }
+        logger.error(`  ${fileName}`);
+        parseResult.errors.forEach((err) => logger.error(`    ${err}`));
+        errorCount++;
+        continue;
+      }
+      if (!reportValidation(fileName, validateWorkflow(parseResult.ast, strict ? { mode: "strict" } : void 0), verbose)) {
+        errorCount++;
+        continue;
+      }
+      const result = generateInPlace(rawSource, parseResult.ast, { production, moduleFormat, sourceFile: file, skipParamReturns: clean });
+      const writePath = outputFile ? outputFile : outputDir ? path.join(outputDir, path.basename(file)) : file;
+      if (!dryRun) {
+        safeWriteFile(writePath, result.code);
+        if (sourceMap) {
+          const mapResult = generateCode(parseResult.ast, {
+            production,
+            sourceMap: true,
+            moduleFormat
+          });
+          if (mapResult.sourceMap) {
+            const mapPath = writePath + ".map";
+            safeWriteFile(mapPath, mapResult.sourceMap);
+            const sourceMappingComment = `
+//# sourceMappingURL=${path.basename(mapPath)}
+`;
+            if (!result.code.includes("//# sourceMappingURL=")) {
+              safeAppendFile(writePath, sourceMappingComment);
+            }
+            if (verbose) {
+              logger.info(`    source map: ${displayPath(mapPath)}`);
+            }
+          }
+        }
+      }
+      const timing = logger.dim(fileTimer.elapsed());
+      const filePrint = displayPath(file);
+      if (dryRun) {
+        if (result.hasChanges) {
+          logger.success(`${filePrint} ${timing} ${logger.dim("(dry run)")}`);
+        } else {
+          logger.log(`  ${filePrint} ${logger.dim("(no changes, dry run)")}`);
+        }
+      } else if (result.hasChanges) {
+        logger.success(`${filePrint} ${timing}`);
+      } else if (verbose) {
+        logger.info(`  ${filePrint} ${logger.dim("no changes")}`);
+      }
+      successCount++;
+    } catch (error) {
+      logger.error(`  ${fileName}: ${getErrorMessage(error)}`);
+      errorCount++;
+    }
+  }
+  const elapsed = totalTimer.elapsed();
+  const formatNote = verbose ? "" : ` (${moduleFormat.toUpperCase()})`;
+  const dryRunNote = dryRun ? " (dry run)" : "";
+  logger.newline();
+  if (errorCount > 0) {
+    logger.log(`  ${successCount} compiled, ${errorCount} failed${formatNote} in ${elapsed}${dryRunNote}`);
+    throw new Error(`${errorCount} file(s) failed to compile`);
+  } else {
+    logger.log(`  ${successCount} file${successCount !== 1 ? "s" : ""} compiled${formatNote} in ${elapsed}${dryRunNote}`);
+  }
+}
+
+export {
+  compileCommand
+};