@withone/cli 1.24.0 → 1.25.0

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

@@ -914,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-LCDHSLUT.js");
+  const { loadFlowWithMeta: loadFlowWithMeta2 } = await import("./flow-runner-MXRNWG4Y.js");
   const { flow: subFlow, rootDir: subRootDir } = loadFlowWithMeta2(resolvedKey);
   const subContext = await executeFlow(
     subFlow,
@@ -1027,6 +1027,35 @@ async function executeBashStep(step, context, options) {
     response: { stdout: stdout.trim(), stderr: stderr.trim(), exitCode: 0 }
   };
 }
+function isMissing(value) {
+  if (value === void 0 || value === null) return true;
+  if (typeof value === "string" && value.length === 0) return true;
+  if (Array.isArray(value) && value.length === 0) return true;
+  return false;
+}
+function explainMissing(selector, context) {
+  const parts = selector.slice(2).split(".");
+  if (parts[0] !== "steps" || parts.length < 2) return "";
+  const stepId = parts[1].replace(/\[.*$/, "");
+  const upstream = context.steps[stepId];
+  if (!upstream) return ` (upstream step "${stepId}" has not run)`;
+  if (upstream.status === "skipped") return ` (upstream step "${stepId}" was skipped)`;
+  if (upstream.status === "failed") return ` (upstream step "${stepId}" failed: ${upstream.error ?? "unknown error"})`;
+  if (upstream.status === "timeout") return ` (upstream step "${stepId}" timed out)`;
+  return "";
+}
+function checkRequires(step, context) {
+  if (!step.requires || step.requires.length === 0) return;
+  for (const selector of step.requires) {
+    const value = resolveSelector(selector, context);
+    if (isMissing(value)) {
+      const why = explainMissing(selector, context);
+      throw new Error(
+        `Step "${step.id}" requires ${selector} but it resolved to ${value === void 0 ? "undefined" : value === null ? "null" : Array.isArray(value) ? "an empty array" : "an empty string"}${why}`
+      );
+    }
+  }
+}
 async function executeSingleStep(step, context, api, permissions, allowedActionIds, options, flowStack = []) {
   if (step.if) {
     const condResult = evaluateExpression(step.if, context);
@@ -1060,6 +1089,7 @@ async function executeSingleStep(step, context, api, permissions, allowedActionI
         });
         await sleep2(delay);
       }
+      checkRequires(step, context);
       if (options.mock && (step.type === "action" || step.type === "paginate" || step.type === "bash")) {
         const resolvedConfig = step[step.type] ? resolveValue(step[step.type], context) : {};
         options.onEvent?.({ event: "step:mock", stepId: step.id, type: step.type, config: resolvedConfig });
@@ -1279,7 +1309,8 @@ var FLOW_SCHEMA = {
     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" },
-    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".' }
+    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".' },
+    requires: { type: "array", required: false, description: "Presence preconditions: array of $.input.X or $.steps.X.output... selectors that must resolve to a non-empty value before the step runs. Failures honor onError." }
   },
   stepTypes: [
     {

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

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

package/dist/index.js

@@ -16,7 +16,7 @@ import {
   loadFlowWithMeta,
   resolveFlowPath,
   saveFlow
-} from "./chunk-AVOGNLC7.js";
+} from "./chunk-ONGJ2QKB.js";
 
 // src/index.ts
 import { createRequire as createRequire2 } from "module";
@@ -2320,6 +2320,20 @@ function validateStepsArray(steps, pathPrefix, errors) {
       errors.push({ path: `${path8}.type`, message: `Step type must be one of: ${validTypes.join(", ")}` });
       continue;
     }
+    if (s.requires !== void 0) {
+      if (!Array.isArray(s.requires)) {
+        errors.push({ path: `${path8}.requires`, message: '"requires" must be an array of selector strings (e.g. ["$.steps.foo.output.bar"])' });
+      } else {
+        for (let r = 0; r < s.requires.length; r++) {
+          const sel = s.requires[r];
+          if (typeof sel !== "string") {
+            errors.push({ path: `${path8}.requires[${r}]`, message: '"requires" entry must be a selector string' });
+          } else if (!sel.startsWith("$.")) {
+            errors.push({ path: `${path8}.requires[${r}]`, message: `"requires" entry "${sel}" must be a selector starting with "$." (e.g. "$.steps.foo.output.bar")` });
+          }
+        }
+      }
+    }
     if (s.onError && typeof s.onError === "object") {
       const oe = s.onError;
       if (!FLOW_SCHEMA.errorStrategies.includes(oe.strategy)) {
@@ -2529,6 +2543,14 @@ function validateSelectorReferences(flow2) {
   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);
+    if (Array.isArray(step.requires)) {
+      const reqs = step.requires;
+      reqs.forEach((sel, i) => {
+        if (typeof sel === "string" && sel.startsWith("$.")) {
+          checkSelectors([sel], `${pathPrefix}.requires[${i}]`, preceding2);
+        }
+      });
+    }
     const descriptor = getStepTypeDescriptor(step.type);
     if (descriptor) {
       const config2 = step[descriptor.configKey];

package/package.json

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

package/skills/one/references/flows.md

@@ -424,6 +424,35 @@ Alternatively, pass values as environment variables (also shell-safe) and refere
 }
 ```
 
+## Step Input Contracts (`requires`)
+
+Declare the data a step depends on so the engine fails fast — with a useful error — when an upstream value is missing. Without `requires`, a skipped or failed upstream step silently leaves `undefined` in the context and the consumer either crashes deep in user code or burns an LLM call on empty input.
+
+```json
+{
+  "id": "summarizeFounder",
+  "type": "code",
+  "requires": [
+    "$.steps.fetchProfile.output.bio",
+    "$.input.founderName"
+  ],
+  "code": { "module": "lib/summarize.mjs" }
+}
+```
+
+Each entry is a `$.input.X` or `$.steps.X.output...` selector. A selector is considered missing when it resolves to `undefined`, `null`, `""`, or `[]` (empty objects are allowed). On a miss, the engine throws **before** the step runs:
+
+```
+Step "summarizeFounder" requires $.steps.fetchProfile.output.bio but it
+resolved to undefined (upstream step "fetchProfile" was skipped)
+```
+
+The "because…" suffix tells you exactly why — skipped, failed, or timed out — so you can fix the upstream wiring instead of guessing.
+
+`requires` failures honor the step's `onError` strategy: pair `requires` with `onError: { strategy: "continue" }` to skip optional consumers gracefully, or leave the default `fail` to halt the flow on contract violations.
+
+Forward references are caught at flow load time: if `requires` points at a step declared after the current step, validation rejects the flow.
+
 ## Error Handling
 
 ```json