@withone/cli 1.22.0 → 1.23.0

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

@@ -447,6 +447,22 @@ var execAsync = promisify(exec);
 function sleep2(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
+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 +490,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 +513,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 +635,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 +644,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 +898,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-DFUFU2LM.js");
   const { flow: subFlow, rootDir: subRootDir } = loadFlowWithMeta2(resolvedKey);
   const subContext = await executeFlow(
     subFlow,
@@ -855,7 +913,7 @@ async function executeSubflowStep(step, context, api, permissions, allowedAction
   return {
     status: "success",
     output: subContext.steps,
-    response: subContext
+    response: subContext.steps
   };
 }
 async function executePaginateStep(step, context, api, permissions, allowedActionIds, options) {
@@ -951,13 +1009,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")) {
@@ -1014,7 +1073,14 @@ async function executeSingleStep(step, context, api, permissions, allowedActionI
           throw new Error(`Unknown step type: ${step.type}`);
       }
       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,11 +1092,13 @@ 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);
   if (strategy === "continue") {
     const result = {
       status: "failed",
       error: errorMessage,
-      durationMs: Date.now() - startTime
+      durationMs: Date.now() - startTime,
+      retries: retriesUsed
     };
     context.steps[step.id] = result;
     return result;
@@ -1039,7 +1107,8 @@ async function executeSingleStep(step, context, api, permissions, allowedActionI
     const result = {
       status: "failed",
       error: errorMessage,
-      durationMs: Date.now() - startTime
+      durationMs: Date.now() - startTime,
+      retries: retriesUsed
     };
     context.steps[step.id] = result;
     return result;
@@ -1614,7 +1683,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
 

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

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

package/dist/index.js

@@ -16,7 +16,7 @@ import {
   loadFlowWithMeta,
   resolveFlowPath,
   saveFlow
-} from "./chunk-KZOFPEHD.js";
+} from "./chunk-Z45IBT5P.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.23.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