@withone/cli 1.22.0 → 1.24.0

package/dist/{chunk-KZOFPEHD.js → chunk-AVOGNLC7.js}

@@ -447,6 +447,38 @@ var execAsync = promisify(exec);
 function sleep2(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
+var StepTimeoutError = class extends Error {
+  errorCode = "TIMEOUT";
+  constructor(stepId, timeoutMs) {
+    super(`Step "${stepId}" exceeded timeout of ${timeoutMs}ms`);
+    this.name = "StepTimeoutError";
+  }
+};
+function withTimeout(promise, timeoutMs, stepId) {
+  let timer;
+  const timeoutPromise = new Promise((_, reject) => {
+    timer = setTimeout(() => reject(new StepTimeoutError(stepId, timeoutMs)), timeoutMs);
+  });
+  return Promise.race([promise, timeoutPromise]).finally(() => {
+    if (timer) clearTimeout(timer);
+  });
+}
+function computeRetryDelay(onError, attempt) {
+  const base = onError.retryDelayMs ?? 1e3;
+  const max = onError.maxDelayMs ?? 3e4;
+  const backoff = onError.backoff ?? "fixed";
+  const retryIndex = attempt - 2;
+  let delay;
+  if (backoff === "exponential" || backoff === "exponential-jitter") {
+    delay = Math.min(base * Math.pow(2, retryIndex), max);
+    if (backoff === "exponential-jitter") {
+      delay = delay * (0.5 + Math.random() * 0.5);
+    }
+  } else {
+    delay = base;
+  }
+  return Math.round(delay);
+}
 function resolveSelector(selectorPath, context) {
   if (!selectorPath.startsWith("$.")) return selectorPath;
   const parts = selectorPath.slice(2).split(/\.|\[/).map((p) => p.replace(/\]$/, ""));
@@ -474,12 +506,22 @@ function resolveSelector(selectorPath, context) {
   }
   return current;
 }
+function shellQuote(value) {
+  return `'${value.replace(/'/g, `'\\''`)}'`;
+}
 function interpolateString(str, context) {
-  return str.replace(/\{\{(\$\.[^}]+)\}\}/g, (_match, selector) => {
+  return str.replace(/\{\{\s*(q\s+)?(\$\.[^}\s]+)\s*\}\}/g, (_match, qFlag, selector) => {
     const value = resolveSelector(selector, context);
-    if (value === void 0 || value === null) return "";
-    if (typeof value === "object") return JSON.stringify(value);
-    return String(value);
+    if (value === void 0 || value === null) return qFlag ? `''` : "";
+    if (typeof value === "object") {
+      console.warn(
+        `[flow] WARNING: Handlebars expression "{{${qFlag ? "q " : ""}${selector}}}" resolved to ${Array.isArray(value) ? "an array" : "an object"} and was stringified as JSON. To pass objects/arrays as native values, use a direct selector without {{ }}: "${selector}"`
+      );
+      const json = JSON.stringify(value);
+      return qFlag ? shellQuote(json) : json;
+    }
+    const str2 = String(value);
+    return qFlag ? shellQuote(str2) : str2;
   });
 }
 function resolveValue(value, context) {
@@ -487,7 +529,7 @@ function resolveValue(value, context) {
     if (value.startsWith("$.") && !value.includes("{{")) {
       return resolveSelector(value, context);
     }
-    if (value.includes("{{$.")) {
+    if (value.includes("{{$.") || /\{\{\s*q\s+\$\./.test(value)) {
       return interpolateString(value, context);
     }
     return value;
@@ -609,8 +651,8 @@ function executeTransformStep(step, context) {
 async function executeCodeStep(step, context, options) {
   const config = step.code;
   if (config.module) {
-    const output2 = await executeCodeModule(step.id, config.module, context, options);
-    return { status: "success", output: output2, response: output2 };
+    const output = await executeCodeModule(step.id, config.module, context, options);
+    return { status: "success", output, response: output };
   }
   if (typeof config.source !== "string") {
     throw new Error(`Code step "${step.id}" must define either "source" or "module"`);
@@ -618,9 +660,41 @@ async function executeCodeStep(step, context, options) {
   const AsyncFunction = Object.getPrototypeOf(async function() {
   }).constructor;
   const sandboxedRequire = createSandboxedRequire();
-  const fn = new AsyncFunction("$", "require", config.source);
-  const output = await fn(context, sandboxedRequire);
-  return { status: "success", output, response: output };
+  const sourceURL = `code:${step.id}`;
+  const taggedSource = `${config.source}
+//# sourceURL=${sourceURL}`;
+  const fn = new AsyncFunction("$", "require", taggedSource);
+  try {
+    const output = await fn(context, sandboxedRequire);
+    return { status: "success", output, response: output };
+  } catch (err) {
+    throw rewriteCodeStepError(err, step.id, config.source, sourceURL);
+  }
+}
+function rewriteCodeStepError(err, stepId, source, sourceURL) {
+  if (!(err instanceof Error)) return new Error(String(err));
+  const WRAPPER_LINE_OFFSET = 2;
+  const sourceLines = source.split("\n");
+  const stack = err.stack || "";
+  const re = new RegExp(`${sourceURL.replace(/[.*+?^${}()|[\\]\\\\]/g, "\\$&")}:(\\d+):(\\d+)`);
+  const match = stack.match(re);
+  if (!match) {
+    err.message = `Code step "${stepId}" failed: ${err.message}`;
+    return err;
+  }
+  const wrappedLine = parseInt(match[1], 10);
+  const col = parseInt(match[2], 10);
+  const userLine = wrappedLine - WRAPPER_LINE_OFFSET;
+  const lineContent = sourceLines[userLine - 1] ?? "";
+  const trimmed = lineContent.trim();
+  err.message = `Code step "${stepId}" failed at line ${userLine}:${col}
+  ${trimmed}
+  ${err.message}`;
+  err.stack = stack.replace(
+    new RegExp(`(${sourceURL.replace(/[.*+?^${}()|[\\]\\\\]/g, "\\$&")}:)(\\d+)`, "g"),
+    (_m, prefix, l) => `${prefix}${parseInt(l, 10) - WRAPPER_LINE_OFFSET}`
+  );
+  return err;
 }
 async function executeCodeModule(stepId, modulePath, context, options) {
   const rootDir = options.rootDir;
@@ -840,7 +914,7 @@ async function executeSubflowStep(step, context, api, permissions, allowedAction
   if (flowStack.includes(resolvedKey)) {
     throw new Error(`Circular flow detected: ${[...flowStack, resolvedKey].join(" \u2192 ")}`);
   }
-  const { loadFlowWithMeta: loadFlowWithMeta2 } = await import("./flow-runner-CXZ6AWXT.js");
+  const { loadFlowWithMeta: loadFlowWithMeta2 } = await import("./flow-runner-LCDHSLUT.js");
   const { flow: subFlow, rootDir: subRootDir } = loadFlowWithMeta2(resolvedKey);
   const subContext = await executeFlow(
     subFlow,
@@ -852,10 +926,35 @@ async function executeSubflowStep(step, context, api, permissions, allowedAction
     void 0,
     [...flowStack, resolvedKey]
   );
+  const finalStep = subFlow.steps[subFlow.steps.length - 1];
+  const finalOutput = finalStep ? subContext.steps[finalStep.id]?.output : void 0;
+  let flattenedOutput;
+  if (finalOutput && typeof finalOutput === "object" && !Array.isArray(finalOutput)) {
+    const collisions = Object.keys(finalOutput).filter(
+      (k) => k in subContext.steps
+    );
+    if (collisions.length > 0) {
+      options.onEvent?.({
+        event: "flow:warning",
+        message: `Sub-flow "${resolvedKey}" final step output fields [${collisions.join(", ")}] collide with sub-step ids \u2014 flattened fields take precedence.`
+      });
+    }
+    flattenedOutput = {
+      ...subContext.steps,
+      ...finalOutput,
+      _steps: subContext.steps
+    };
+  } else {
+    flattenedOutput = {
+      ...subContext.steps,
+      _steps: subContext.steps,
+      ...finalOutput !== void 0 ? { _finalOutput: finalOutput } : {}
+    };
+  }
   return {
     status: "success",
-    output: subContext.steps,
-    response: subContext
+    output: flattenedOutput,
+    response: flattenedOutput
   };
 }
 async function executePaginateStep(step, context, api, permissions, allowedActionIds, options) {
@@ -951,13 +1050,14 @@ async function executeSingleStep(step, context, api, permissions, allowedActionI
   for (let attempt = 1; attempt <= maxAttempts; attempt++) {
     try {
       if (attempt > 1) {
+        const delay = computeRetryDelay(step.onError, attempt);
         options.onEvent?.({
           event: "step:retry",
           stepId: step.id,
           attempt,
-          maxRetries: step.onError.retries
+          maxRetries: step.onError.retries,
+          delayMs: delay
         });
-        const delay = step.onError?.retryDelayMs || 1e3;
         await sleep2(delay);
       }
       if (options.mock && (step.type === "action" || step.type === "paginate" || step.type === "bash")) {
@@ -972,49 +1072,46 @@ async function executeSingleStep(step, context, api, permissions, allowedActionI
         context.steps[step.id] = result2;
         return result2;
       }
-      let result;
-      switch (step.type) {
-        case "action":
-          result = await executeActionStep(step, context, api, permissions, allowedActionIds);
-          break;
-        case "transform":
-          result = executeTransformStep(step, context);
-          break;
-        case "code":
-          result = await executeCodeStep(step, context, options);
-          break;
-        case "condition":
-          result = await executeConditionStep(step, context, api, permissions, allowedActionIds, options, flowStack);
-          break;
-        case "loop":
-          result = await executeLoopStep(step, context, api, permissions, allowedActionIds, options, flowStack);
-          break;
-        case "parallel":
-          result = await executeParallelStep(step, context, api, permissions, allowedActionIds, options, flowStack);
-          break;
-        case "file-read":
-          result = executeFileReadStep(step, context);
-          break;
-        case "file-write":
-          result = executeFileWriteStep(step, context);
-          break;
-        case "while":
-          result = await executeWhileStep(step, context, api, permissions, allowedActionIds, options, flowStack);
-          break;
-        case "flow":
-          result = await executeSubflowStep(step, context, api, permissions, allowedActionIds, options, flowStack);
-          break;
-        case "paginate":
-          result = await executePaginateStep(step, context, api, permissions, allowedActionIds, options);
-          break;
-        case "bash":
-          result = await executeBashStep(step, context, options);
-          break;
-        default:
-          throw new Error(`Unknown step type: ${step.type}`);
-      }
+      const dispatch = async () => {
+        switch (step.type) {
+          case "action":
+            return await executeActionStep(step, context, api, permissions, allowedActionIds);
+          case "transform":
+            return executeTransformStep(step, context);
+          case "code":
+            return await executeCodeStep(step, context, options);
+          case "condition":
+            return await executeConditionStep(step, context, api, permissions, allowedActionIds, options, flowStack);
+          case "loop":
+            return await executeLoopStep(step, context, api, permissions, allowedActionIds, options, flowStack);
+          case "parallel":
+            return await executeParallelStep(step, context, api, permissions, allowedActionIds, options, flowStack);
+          case "file-read":
+            return executeFileReadStep(step, context);
+          case "file-write":
+            return executeFileWriteStep(step, context);
+          case "while":
+            return await executeWhileStep(step, context, api, permissions, allowedActionIds, options, flowStack);
+          case "flow":
+            return await executeSubflowStep(step, context, api, permissions, allowedActionIds, options, flowStack);
+          case "paginate":
+            return await executePaginateStep(step, context, api, permissions, allowedActionIds, options);
+          case "bash":
+            return await executeBashStep(step, context, options);
+          default:
+            throw new Error(`Unknown step type: ${step.type}`);
+        }
+      };
+      const result = step.timeoutMs ? await withTimeout(dispatch(), step.timeoutMs, step.id) : await dispatch();
       result.durationMs = Date.now() - startTime;
-      if (attempt > 1) result.retries = attempt - 1;
+      if (attempt > 1) {
+        result.retries = attempt - 1;
+        options.onEvent?.({
+          event: "step:retry-success",
+          stepId: step.id,
+          retries: attempt - 1
+        });
+      }
       context.steps[step.id] = result;
       return result;
     } catch (err) {
@@ -1026,20 +1123,27 @@ async function executeSingleStep(step, context, api, permissions, allowedActionI
   }
   const errorMessage = lastError?.message || "Unknown error";
   const strategy = step.onError?.strategy || "fail";
+  const retriesUsed = Math.max(0, maxAttempts - 1);
+  const isTimeout = lastError instanceof StepTimeoutError;
+  const errorCode = lastError?.errorCode;
   if (strategy === "continue") {
     const result = {
-      status: "failed",
+      status: isTimeout ? "timeout" : "failed",
       error: errorMessage,
-      durationMs: Date.now() - startTime
+      ...errorCode ? { errorCode } : {},
+      durationMs: Date.now() - startTime,
+      retries: retriesUsed
     };
     context.steps[step.id] = result;
     return result;
   }
   if (strategy === "fallback" && step.onError?.fallbackStepId) {
     const result = {
-      status: "failed",
+      status: isTimeout ? "timeout" : "failed",
       error: errorMessage,
-      durationMs: Date.now() - startTime
+      ...errorCode ? { errorCode } : {},
+      durationMs: Date.now() - startTime,
+      retries: retriesUsed
     };
     context.steps[step.id] = result;
     return result;
@@ -1174,7 +1278,8 @@ var FLOW_SCHEMA = {
     name: { type: "string", required: true, description: "Human-readable step label" },
     type: { type: "string", required: true, description: "Step type (determines which config object is required)" },
     if: { type: "string", required: false, description: "JS expression \u2014 skip step if falsy" },
-    unless: { type: "string", required: false, description: "JS expression \u2014 skip step if truthy" }
+    unless: { type: "string", required: false, description: "JS expression \u2014 skip step if truthy" },
+    timeoutMs: { type: "number", required: false, description: 'Wall-clock timeout (ms). On expiry the step fails with errorCode:"TIMEOUT"; with onError:continue the result gets status:"timeout".' }
   },
   stepTypes: [
     {
@@ -1614,7 +1719,7 @@ Every step MUST have \`id\`, \`name\`, and \`type\`. The \`type\` determines whi
   for (const [name, fd] of Object.entries(FLOW_SCHEMA.stepCommonFields)) {
     sections.push(`| \`${name}\` | ${fd.type} | ${fd.required ? "yes" : "no"} | ${fd.description} |`);
   }
-  sections.push(`| \`onError\` | object | no | Error handling: \`{ "strategy": "${FLOW_SCHEMA.errorStrategies.join(" | ")}", "retries": 3, "retryDelayMs": 1000 }\` |`);
+  sections.push(`| \`onError\` | object | no | Error handling: \`{ "strategy": "${FLOW_SCHEMA.errorStrategies.join(" | ")}", "retries": 3, "retryDelayMs": 1000, "backoff": "fixed \\| exponential \\| exponential-jitter", "maxDelayMs": 30000 }\` |`);
   sections.push(`
 ## Step Types
 
@@ -1682,6 +1787,39 @@ Every completed step produces both \`output\` and \`response\`:
 - **Code/transform steps**: \`output\` is the return value. \`response\` is an alias for \`output\`.
 - **In practice**: Use \`$.steps.stepId.response\` for action steps (API data) and \`$.steps.stepId.output\` for code/transform steps (computed data). Both work interchangeably, but using the semantically correct one makes flows easier to read.
 
+### Step result metadata (\`status\`, \`error\`, \`errorCode\`)
+
+Every step result also exposes execution metadata that downstream steps can inspect:
+
+| Field | Values | When set |
+|-------|--------|----------|
+| \`$.steps.X.status\` | \`"success"\` \\| \`"skipped"\` \\| \`"failed"\` \\| \`"timeout"\` | Always |
+| \`$.steps.X.error\` | error message string | When status is \`failed\` or \`timeout\` |
+| \`$.steps.X.errorCode\` | machine-readable code (e.g. \`"TIMEOUT"\`) | When the error has a code |
+| \`$.steps.X.durationMs\` | number | Always |
+| \`$.steps.X.retries\` | number | When the step was retried |
+
+This lets downstream steps distinguish \`skipped\` (\`if\` condition false) from \`failed\` (error, \`onError:continue\`) from \`timeout\` (exceeded \`timeoutMs\`) \u2014 e.g. \`"if": "$.steps.enrichment.status === 'timeout'"\` to retry with a longer window.
+
+### Sub-flow output (flattened)
+
+When a step has \`type: "flow"\`, the sub-flow's final step output is flattened onto the parent step's \`output\`:
+
+\`\`\`jsonc
+// Sub-flow "sub-consts" has a final step "load" that returns { CHART_URL, API_KEY }
+
+// Preferred (flattened):
+"{{$.steps.loadConfig.output.CHART_URL}}"
+
+// Legacy nested path (still works for backward compatibility):
+"{{$.steps.loadConfig.output.load.output.CHART_URL}}"
+
+// Escape hatch for programmatic access to the full sub-flow steps map:
+"{{$.steps.loadConfig.output._steps.load.output.CHART_URL}}"
+\`\`\`
+
+If a sub-step id collides with a flattened field name, the flattened field wins and the engine emits a \`flow:warning\` event.
+
 ## Error Handling
 
 \`\`\`json

package/dist/{flow-runner-CXZ6AWXT.js → flow-runner-LCDHSLUT.js}

@@ -11,7 +11,7 @@ import {
   saveFlow,
   summarizeFlowInputs,
   walkSteps
-} from "./chunk-KZOFPEHD.js";
+} from "./chunk-AVOGNLC7.js";
 export {
   FlowRunner,
   collectStepTypes,

package/dist/index.js

@@ -16,7 +16,7 @@ import {
   loadFlowWithMeta,
   resolveFlowPath,
   saveFlow
-} from "./chunk-KZOFPEHD.js";
+} from "./chunk-AVOGNLC7.js";
 
 // src/index.ts
 import { createRequire as createRequire2 } from "module";
@@ -2243,6 +2243,9 @@ function colorMethod(method) {
 import pc7 from "picocolors";
 
 // src/lib/flow-validator.ts
+import fs6 from "fs";
+import path6 from "path";
+import { spawnSync } from "child_process";
 function validateFlowSchema(flow2) {
   const errors = [];
   if (!flow2 || typeof flow2 !== "object") {
@@ -2301,26 +2304,26 @@ function validateStepsArray(steps, pathPrefix, errors) {
   const validTypes = FLOW_SCHEMA.stepTypes.map((st) => st.type);
   for (let i = 0; i < steps.length; i++) {
     const step = steps[i];
-    const path6 = `${pathPrefix}[${i}]`;
+    const path8 = `${pathPrefix}[${i}]`;
     if (!step || typeof step !== "object" || Array.isArray(step)) {
-      errors.push({ path: path6, message: "Step must be an object" });
+      errors.push({ path: path8, message: "Step must be an object" });
       continue;
     }
     const s = step;
     if (!s.id || typeof s.id !== "string") {
-      errors.push({ path: `${path6}.id`, message: 'Step must have a string "id"' });
+      errors.push({ path: `${path8}.id`, message: 'Step must have a string "id"' });
     }
     if (!s.name || typeof s.name !== "string") {
-      errors.push({ path: `${path6}.name`, message: 'Step must have a string "name"' });
+      errors.push({ path: `${path8}.name`, message: 'Step must have a string "name"' });
     }
     if (!s.type || !validTypes.includes(s.type)) {
-      errors.push({ path: `${path6}.type`, message: `Step type must be one of: ${validTypes.join(", ")}` });
+      errors.push({ path: `${path8}.type`, message: `Step type must be one of: ${validTypes.join(", ")}` });
       continue;
     }
     if (s.onError && typeof s.onError === "object") {
       const oe = s.onError;
       if (!FLOW_SCHEMA.errorStrategies.includes(oe.strategy)) {
-        errors.push({ path: `${path6}.onError.strategy`, message: `Error strategy must be one of: ${FLOW_SCHEMA.errorStrategies.join(", ")}` });
+        errors.push({ path: `${path8}.onError.strategy`, message: `Error strategy must be one of: ${FLOW_SCHEMA.errorStrategies.join(", ")}` });
       }
     }
     const descriptor = getStepTypeDescriptor(s.type);
@@ -2330,14 +2333,14 @@ function validateStepsArray(steps, pathPrefix, errors) {
     if (!configObj || typeof configObj !== "object") {
       const hint = detectFlatConfigHint(s, descriptor);
       errors.push({
-        path: `${path6}.${configKey}`,
+        path: `${path8}.${configKey}`,
         message: `${capitalize(descriptor.type)} step must have a "${configKey}" config object${hint}`
       });
       continue;
     }
     const config2 = configObj;
     for (const [fieldName, fd] of Object.entries(descriptor.fields)) {
-      const fieldPath = `${path6}.${configKey}.${fieldName}`;
+      const fieldPath = `${path8}.${configKey}.${fieldName}`;
       const value = config2[fieldName];
       if (fd.required && (value === void 0 || value === null || value === "")) {
         errors.push({ path: fieldPath, message: `${capitalize(descriptor.type)} must have ${fd.type === "string" ? "a string" : fd.type === "array" ? "a" : "a"} "${fieldName}"` });
@@ -2373,18 +2376,24 @@ function validateStepsArray(steps, pathPrefix, errors) {
       const hasSource = typeof config2.source === "string" && config2.source.length > 0;
       const hasModule = typeof config2.module === "string" && config2.module.length > 0;
       if (!hasSource && !hasModule) {
-        errors.push({ path: `${path6}.${configKey}`, message: 'Code step must define either "source" (inline JS) or "module" (path to .mjs file)' });
+        errors.push({ path: `${path8}.${configKey}`, message: 'Code step must define either "source" (inline JS) or "module" (path to .mjs file)' });
       } else if (hasSource && hasModule) {
-        errors.push({ path: `${path6}.${configKey}`, message: 'Code step cannot define both "source" and "module" \u2014 pick one' });
+        errors.push({ path: `${path8}.${configKey}`, message: 'Code step cannot define both "source" and "module" \u2014 pick one' });
       }
       if (hasModule) {
         const m = config2.module;
         if (m.startsWith("/") || /^[a-zA-Z]:[\\/]/.test(m)) {
-          errors.push({ path: `${path6}.${configKey}.module`, message: "Code module path must be relative to the flow folder (no absolute paths)" });
+          errors.push({ path: `${path8}.${configKey}.module`, message: "Code module path must be relative to the flow folder (no absolute paths)" });
         } else if (m.split(/[\\/]/).includes("..")) {
-          errors.push({ path: `${path6}.${configKey}.module`, message: 'Code module path must not escape the flow folder ("..")' });
+          errors.push({ path: `${path8}.${configKey}.module`, message: 'Code module path must not escape the flow folder ("..")' });
         } else if (!m.endsWith(".mjs")) {
-          errors.push({ path: `${path6}.${configKey}.module`, message: "Code module must be a .mjs file" });
+          errors.push({ path: `${path8}.${configKey}.module`, message: "Code module must be a .mjs file" });
+        }
+      }
+      if (hasSource) {
+        const syntaxError = checkCodeSourceSyntax(config2.source);
+        if (syntaxError) {
+          errors.push({ path: `${path8}.${configKey}.source`, message: `Syntax error in code step: ${syntaxError}` });
         }
       }
     }
@@ -2401,6 +2410,17 @@ function detectFlatConfigHint(step, descriptor) {
 function capitalize(s) {
   return s.charAt(0).toUpperCase() + s.slice(1);
 }
+var AsyncFunctionCtor = Object.getPrototypeOf(async function() {
+}).constructor;
+function checkCodeSourceSyntax(source) {
+  try {
+    new AsyncFunctionCtor("$", "require", source);
+    return null;
+  } catch (err) {
+    if (err instanceof SyntaxError) return err.message;
+    return err.message;
+  }
+}
 function validateStepIds(flow2) {
   const errors = [];
   const seen = /* @__PURE__ */ new Set();
@@ -2408,16 +2428,16 @@ function validateStepIds(flow2) {
   function collectIds(steps, pathPrefix) {
     for (let i = 0; i < steps.length; i++) {
       const step = steps[i];
-      const path6 = `${pathPrefix}[${i}]`;
+      const path8 = `${pathPrefix}[${i}]`;
       if (seen.has(step.id)) {
-        errors.push({ path: `${path6}.id`, message: `Duplicate step ID: "${step.id}"` });
+        errors.push({ path: `${path8}.id`, message: `Duplicate step ID: "${step.id}"` });
       } else {
         seen.add(step.id);
       }
       for (const { configKey, fieldName } of nestedKeys) {
         const config2 = step[configKey];
         if (config2 && Array.isArray(config2[fieldName])) {
-          collectIds(config2[fieldName], `${path6}.${configKey}.${fieldName}`);
+          collectIds(config2[fieldName], `${path8}.${configKey}.${fieldName}`);
         }
       }
     }
@@ -2465,7 +2485,7 @@ function validateSelectorReferences(flow2) {
     }
     return selectors;
   }
-  function checkSelectors(selectors, path6) {
+  function checkSelectors(selectors, path8, precedingStepIds) {
     for (const selector of selectors) {
       const parts = selector.split(".");
       if (parts.length < 3) continue;
@@ -2473,37 +2493,42 @@ function validateSelectorReferences(flow2) {
       if (root === "input") {
         const inputName = parts[2];
         if (!inputNames.has(inputName)) {
-          errors.push({ path: path6, message: `Selector "${selector}" references undefined input "${inputName}"` });
+          errors.push({ path: path8, message: `Selector "${selector}" references undefined input "${inputName}"` });
         }
       } else if (root === "steps") {
-        const stepId = parts[2];
+        const stepId = parts[2].replace(/[\[\]]/g, "").split(/[\[\]]/)[0];
         if (!allStepIds.has(stepId)) {
-          errors.push({ path: path6, message: `Selector "${selector}" references undefined step "${stepId}"` });
+          errors.push({ path: path8, message: `Selector "${selector}" references undefined step "${stepId}"` });
+        } else if (precedingStepIds && !precedingStepIds.has(stepId)) {
+          errors.push({
+            path: path8,
+            message: `Selector "${selector}" references step "${stepId}" which is declared after the current step. Steps execute in declaration order, so this will always resolve to undefined at runtime \u2014 move the dependency earlier in the steps array.`
+          });
         }
       }
     }
   }
   const EXPRESSION_FIELDS = /* @__PURE__ */ new Set(["condition.expression", "while.condition"]);
-  function checkOperatorsInSelectorField(value, path6) {
+  function checkOperatorsInSelectorField(value, path8) {
     if (typeof value === "string" && value.startsWith("$.")) {
       if (value.includes("||")) {
-        errors.push({ path: path6, message: `Selector "${value}" contains unsupported operator "||". Selectors in data fields use dot-path resolution, not JS evaluation. Use the "default" field on the input definition instead, or use a "code" step for complex expressions.` });
+        errors.push({ path: path8, message: `Selector "${value}" contains unsupported operator "||". Selectors in data fields use dot-path resolution, not JS evaluation. Use the "default" field on the input definition instead, or use a "code" step for complex expressions.` });
       } else if (value.includes("&&")) {
-        errors.push({ path: path6, message: `Selector "${value}" contains unsupported operator "&&". Selectors in data fields use dot-path resolution, not JS evaluation. Use a "condition" step or "code" step for complex expressions.` });
+        errors.push({ path: path8, message: `Selector "${value}" contains unsupported operator "&&". Selectors in data fields use dot-path resolution, not JS evaluation. Use a "condition" step or "code" step for complex expressions.` });
       }
     } else if (value && typeof value === "object" && !Array.isArray(value)) {
       for (const [k, v] of Object.entries(value)) {
-        checkOperatorsInSelectorField(v, `${path6}.${k}`);
+        checkOperatorsInSelectorField(v, `${path8}.${k}`);
       }
     } else if (Array.isArray(value)) {
       for (let i = 0; i < value.length; i++) {
-        checkOperatorsInSelectorField(value[i], `${path6}[${i}]`);
+        checkOperatorsInSelectorField(value[i], `${path8}[${i}]`);
       }
     }
   }
-  function checkStep(step, pathPrefix) {
-    if (step.if) checkSelectors(extractSelectors(step.if), `${pathPrefix}.if`);
-    if (step.unless) checkSelectors(extractSelectors(step.unless), `${pathPrefix}.unless`);
+  function checkStep(step, pathPrefix, preceding2) {
+    if (step.if) checkSelectors(extractSelectors(step.if), `${pathPrefix}.if`, preceding2);
+    if (step.unless) checkSelectors(extractSelectors(step.unless), `${pathPrefix}.unless`, preceding2);
     const descriptor = getStepTypeDescriptor(step.type);
     if (descriptor) {
       const config2 = step[descriptor.configKey];
@@ -2515,41 +2540,95 @@ function validateSelectorReferences(flow2) {
             if (value !== void 0) {
               const fieldKey = `${descriptor.configKey}.${fieldName}`;
               const fieldPath = `${pathPrefix}.${fieldKey}`;
-              checkSelectors(extractSelectors(value), fieldPath);
+              checkSelectors(extractSelectors(value), fieldPath, preceding2);
               if (!EXPRESSION_FIELDS.has(fieldKey)) {
                 checkOperatorsInSelectorField(value, fieldPath);
               }
             }
           }
+        } else {
+          const c = config2;
+          const codeSource = step.type === "code" ? c.source : void 0;
+          const transformExpr = step.type === "transform" ? c.expression : void 0;
+          const text4 = codeSource ?? transformExpr;
+          if (typeof text4 === "string") {
+            const fieldName = step.type === "code" ? "source" : "expression";
+            checkSelectors(extractSelectors(text4), `${pathPrefix}.${descriptor.configKey}.${fieldName}`, preceding2);
+          }
         }
       }
       for (const { configKey, fieldName } of nestedKeys) {
         if (configKey === descriptor.configKey) {
           const c = step[configKey];
           if (c && Array.isArray(c[fieldName])) {
-            c[fieldName].forEach(
-              (s, i) => checkStep(s, `${pathPrefix}.${configKey}.${fieldName}[${i}]`)
-            );
+            const childPreceding = new Set(preceding2);
+            c[fieldName].forEach((s, i) => {
+              checkStep(s, `${pathPrefix}.${configKey}.${fieldName}[${i}]`, childPreceding);
+              childPreceding.add(s.id);
+            });
           }
         }
       }
     }
   }
-  flow2.steps.forEach((step, i) => checkStep(step, `steps[${i}]`));
+  const preceding = /* @__PURE__ */ new Set();
+  flow2.steps.forEach((step, i) => {
+    checkStep(step, `steps[${i}]`, preceding);
+    preceding.add(step.id);
+  });
   return errors;
 }
-function validateFlow(flow2) {
+function validateFlow(flow2, rootDir) {
   const schemaErrors = validateFlowSchema(flow2);
   if (schemaErrors.length > 0) return schemaErrors;
   const f = flow2;
   return [
     ...validateStepIds(f),
-    ...validateSelectorReferences(f)
+    ...validateSelectorReferences(f),
+    ...rootDir ? validateCodeModules(f, rootDir) : []
   ];
 }
+function validateCodeModules(flow2, rootDir) {
+  const errors = [];
+  const nestedKeys = getNestedStepsKeys();
+  function walk(steps, pathPrefix) {
+    for (let i = 0; i < steps.length; i++) {
+      const step = steps[i];
+      const stepPath = `${pathPrefix}[${i}]`;
+      if (step.type === "code" && step.code?.module) {
+        const m = step.code.module;
+        const abs = path6.resolve(rootDir, m);
+        if (!fs6.existsSync(abs)) {
+          errors.push({
+            path: `${stepPath}.code.module`,
+            message: `Code module "${m}" not found at ${abs}`
+          });
+        } else {
+          const res = spawnSync(process.execPath, ["--check", abs], { encoding: "utf-8" });
+          if (res.status !== 0) {
+            const msg = (res.stderr || "").split("\n").find((l) => l.includes("SyntaxError") || l.includes("Error")) || res.stderr || "Syntax check failed";
+            errors.push({
+              path: `${stepPath}.code.module`,
+              message: `Syntax error in code module "${m}": ${msg.trim()}`
+            });
+          }
+        }
+      }
+      for (const { configKey, fieldName } of nestedKeys) {
+        const config2 = step[configKey];
+        if (config2 && Array.isArray(config2[fieldName])) {
+          walk(config2[fieldName], `${stepPath}.${configKey}.${fieldName}`);
+        }
+      }
+    }
+  }
+  walk(flow2.steps, "steps");
+  return errors;
+}
 
 // src/commands/flow.ts
-import fs6 from "fs";
+import fs7 from "fs";
+import path7 from "path";
 function getConfig2() {
   const apiKey = getApiKey();
   if (!apiKey) {
@@ -2607,7 +2686,7 @@ async function flowCreateCommand(key, options) {
     if (raw.startsWith("@")) {
       const filePath = raw.slice(1);
       try {
-        raw = fs6.readFileSync(filePath, "utf-8");
+        raw = fs7.readFileSync(filePath, "utf-8");
       } catch (err) {
         error(`Cannot read file "${filePath}": ${err.message}`);
       }
@@ -2672,6 +2751,15 @@ async function flowExecuteCommand(keyOrPath, options) {
     return;
   }
   spinner5.stop(`Workflow: ${flow2.name} (${flow2.steps.length} steps)`);
+  const preflightErrors = validateFlow(flow2, rootDir);
+  if (preflightErrors.length > 0) {
+    if (isAgentMode()) {
+      json({ error: "Validation failed", errors: preflightErrors });
+      process.exit(1);
+    }
+    error(`Validation failed:
+${preflightErrors.map((e) => `  ${e.path}: ${e.message}`).join("\n")}`);
+  }
   if (flowFilePath.endsWith(".flow.json")) {
     const msg = `Workflow "${flow2.key}" uses the deprecated single-file layout. Migrate to .one/flows/${flow2.key}/flow.json (see: one guide flows).`;
     if (isAgentMode()) {
@@ -2812,15 +2900,23 @@ async function flowValidateCommand(keyOrPath) {
   const spinner5 = createSpinner();
   spinner5.start(`Validating "${keyOrPath}"...`);
   let flowData;
+  let rootDir;
   try {
-    const flowPath = resolveFlowPath(keyOrPath);
-    const content = fs6.readFileSync(flowPath, "utf-8");
-    flowData = JSON.parse(content);
+    try {
+      const loaded = loadFlowWithMeta(keyOrPath);
+      flowData = loaded.flow;
+      rootDir = loaded.rootDir;
+    } catch {
+      const flowPath = resolveFlowPath(keyOrPath);
+      const content = fs7.readFileSync(flowPath, "utf-8");
+      flowData = JSON.parse(content);
+      rootDir = path7.dirname(flowPath);
+    }
   } catch (err) {
     spinner5.stop("Validation failed");
     error(`Could not read workflow: ${err instanceof Error ? err.message : String(err)}`);
   }
-  const errors = validateFlow(flowData);
+  const errors = validateFlow(flowData, rootDir);
   if (errors.length > 0) {
     spinner5.stop("Validation failed");
     if (isAgentMode()) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@withone/cli",
-  "version": "1.22.0",
+  "version": "1.24.0",
   "description": "CLI for managing One",
   "type": "module",
   "files": [

package/skills/one/references/flows.md

@@ -95,6 +95,21 @@ process.stdout.write(JSON.stringify(items.filter(i => i.active)));
 
 The module runs as a child `node` process: the flow context `$` is piped to stdin as JSON, and stdout is parsed as JSON and used as the step's output. Modules have full Node APIs available (unlike inline `code.source`, which is sandboxed). Use `code.module` for anything non-trivial; keep `code.source` for one-liners.
 
+#### Inline `code.source` sandbox
+
+Inline `code.source` runs inside an async function with a restricted `require`. Only the following Node built-ins are importable:
+
+- `node:buffer`
+- `node:crypto`
+- `node:url`
+- `node:path`
+
+Everything else — `fs`, `http`, `https`, `net`, `child_process`, `process`, `os`, `cluster`, `dgram`, `tls`, `vm`, `worker_threads` — is **blocked** and will throw `Module "<name>" is blocked in code steps`. The runtime also does not expose `process`, `__dirname`, `__filename`, `setTimeout`, or `fetch`.
+
+If you need any of those (filesystem reads, network calls, timers, etc.), use a `code.module` step instead — modules run as a real child `node` process and have the full Node API surface.
+
+When an inline `code.source` step throws at runtime, the error message reports the user-relative line and column plus the offending line of source — e.g. `Code step "blowup" failed at line 3:34\n  const c = $.steps.mk.output.data.score;\n  Cannot read properties of null (reading 'score')`. No need to bisect the step manually.
+
 Whatever JSON a module writes to stdout becomes both `$.steps.<id>.output` and `$.steps.<id>.response` (aliases). Downstream steps can reference either.
 
 ### Migrating a legacy single-file flow
@@ -130,6 +145,8 @@ Two rules: (1) prepend the stdin-read line, (2) replace `return X` with `process
 one --agent flow validate <key>
 ```
 
+`flow validate` parses every inline `code.source` and runs `node --check` on every `code.module` file, so syntax errors (brace/paren mismatches, duplicate `let`, etc.) surface here instead of after upstream steps have already run. It also extracts `$.steps.X` and `$.input.X` references from inside `code.source` and `transform.expression` and reports any reference to an undefined step/input or to a step declared **after** the current one (forward references resolve to `undefined` at runtime — silent data loss). The same checks run automatically at the start of `flow execute` so a broken step in position 15 fails the run immediately rather than 15 minutes in.
+
 ### Step 6: Execute
 
 ```bash
@@ -187,6 +204,16 @@ Connection inputs with a `connection` field auto-resolve if the user has exactly
 
 A pure `$.xxx` value resolves to the raw type. A string containing `{{$.xxx}}` does string interpolation.
 
+**Passing objects and arrays:** `{{ }}` interpolation always produces a string — if the resolved value is an object or array it will be JSON-stringified and the engine will log a warning. To pass an object/array as a native value to the next step, use a **direct selector without `{{ }}`**:
+
+```json
+// ✗ Wrong — becomes a JSON string, triggers a runtime warning
+"files": "{{$.steps.extract.output.allFiles}}"
+
+// ✓ Right — passes the array as an array
+"files": "$.steps.extract.output.allFiles"
+```
+
 ### Selectors vs expressions
 
 Selectors in data fields (`data`, `queryParams`, `pathVars`, `connectionKey`) are **dot-path lookups only** — they do not support JavaScript operators like `||` or `&&`. For default values, use the `default` field on the input definition:
@@ -343,6 +370,14 @@ After a parallel step, access each substep's output by its `id`: `$.steps.fetchE
 }
 ```
 
+A sub-flow step exposes the sub-flow's **step results map** at both `.output` and `.response` (they are aliases — pick whichever reads better). Access a specific sub-step's data with:
+
+```
+$.steps.<parent>.output.<subStepId>.output.<field>
+```
+
+e.g. if sub-flow `enrich-customer` has a step `load` that returns `{ TEAM: "acme" }`, the caller reads it as `$.steps.enrich.output.load.output.TEAM`. There is no longer any `.response.<subStepId>` vs `.output.<subStepId>` ambiguity.
+
 ### `paginate` — Auto-collect paginated results
 
 ```json
@@ -369,6 +404,26 @@ After a parallel step, access each substep's output by its `id`: `$.steps.fetchE
 }
 ```
 
+**Safe interpolation.** Plain `{{$.input.x}}` does string substitution and is **unsafe** for bash — values containing quotes, `$`, backticks, `&`, etc. will break the command (or worse). Use the `q` helper to POSIX-shell-quote the value:
+
+```json
+{ "command": "echo {{q $.input.companyName}} | tr '[:upper:]' '[:lower:]'" }
+```
+
+`{{q $.input.companyName}}` resolves `O'Reilly Media & Co` to `'O'\''Reilly Media & Co'` — a single argv token bash will parse cleanly. Use `{{q ...}}` for **every** interpolation of user-controlled data into a bash command.
+
+Alternatively, pass values as environment variables (also shell-safe) and reference them with `$VAR`:
+
+```json
+{
+  "type": "bash",
+  "bash": {
+    "env": { "COMPANY": "$.input.companyName" },
+    "command": "echo \"$COMPANY\" | tr '[:upper:]' '[:lower:]'"
+  }
+}
+```
+
 ## Error Handling
 
 ```json
@@ -377,6 +432,30 @@ After a parallel step, access each substep's output by its `id`: `$.steps.fetchE
 
 Strategies: `fail` (default), `continue`, `retry`, `fallback`.
 
+**Retry backoff.** By default each retry waits exactly `retryDelayMs`. For rate-limited APIs add `"backoff": "exponential"` (or `"exponential-jitter"`) and an optional `"maxDelayMs"` cap (defaults to 30000):
+
+```json
+{
+  "onError": {
+    "strategy": "retry",
+    "retries": 4,
+    "retryDelayMs": 1000,
+    "backoff": "exponential-jitter",
+    "maxDelayMs": 10000
+  }
+}
+```
+
+`exponential` waits `retryDelayMs * 2^(retryIndex)` (1s, 2s, 4s, 8s…) capped at `maxDelayMs`. `exponential-jitter` multiplies each wait by a random factor in [0.5, 1.0) so concurrent retries spread out.
+
+**Inspecting retry outcomes.** Every retried step exposes how it ended on its `StepResult`:
+
+- `$.steps.<id>.status` — `"success"` or `"failed"`
+- `$.steps.<id>.retries` — number of retries actually performed (0 if first attempt succeeded)
+- `$.steps.<id>.error` — last error message (only set when `status === "failed"` under `continue`/`fallback` strategies)
+
+A successful-after-retry step also emits a `step:retry-success` event with the retry count, so you can distinguish a clean first-attempt success from a recovered one in logs.
+
 Conditional execution: `"if": "$.steps.find.response.data.length > 0"`
 
 ## AI-Augmented Patterns