@withone/cli 1.24.0 → 1.26.0

package/dist/{chunk-AVOGNLC7.js → chunk-ZOIXA7MV.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-3DCROTPW.js");
   const { flow: subFlow, rootDir: subRootDir } = loadFlowWithMeta2(resolvedKey);
   const subContext = await executeFlow(
     subFlow,
@@ -1027,6 +1027,41 @@ async function executeBashStep(step, context, options) {
     response: { stdout: stdout.trim(), stderr: stderr.trim(), exitCode: 0 }
   };
 }
+function describe(value) {
+  if (value === null) return "null";
+  if (Array.isArray(value)) return `array (${JSON.stringify(value)})`;
+  if (typeof value === "object") return `object (${JSON.stringify(value)})`;
+  return `${typeof value} (${JSON.stringify(value)})`;
+}
+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 +1095,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 });
@@ -1188,18 +1224,68 @@ async function executeSteps(steps, context, api, permissions, allowedActionIds,
   return results;
 }
 async function executeFlow(flow, inputs, api, permissions, allowedActionIds, options = {}, resumeState, flowStack = []) {
-  for (const [name, decl] of Object.entries(flow.inputs)) {
-    if (decl.required !== false && inputs[name] === void 0 && decl.default === void 0) {
-      throw new Error(`Missing required input: "${name}" \u2014 ${decl.description || ""}`);
-    }
-  }
   const resolvedInputs = {};
   for (const [name, decl] of Object.entries(flow.inputs)) {
-    if (inputs[name] !== void 0) {
-      resolvedInputs[name] = inputs[name];
-    } else if (decl.default !== void 0) {
-      resolvedInputs[name] = decl.default;
+    const provided = inputs[name];
+    const isMissing2 = provided === void 0 || provided === null;
+    if (isMissing2) {
+      if (decl.required !== false && decl.default === void 0) {
+        throw new Error(`Missing required input: "${name}"${decl.description ? ` \u2014 ${decl.description}` : ""}`);
+      }
+      if (decl.default !== void 0) {
+        resolvedInputs[name] = decl.default;
+      }
+      continue;
+    }
+    let value = provided;
+    switch (decl.type) {
+      case "string":
+        if (typeof value !== "string") value = String(value);
+        break;
+      case "number":
+        if (typeof value === "string" && value.trim() !== "" && !Number.isNaN(Number(value))) {
+          value = Number(value);
+        }
+        if (typeof value !== "number" || Number.isNaN(value)) {
+          throw new Error(`Input "${name}" must be a number, got ${describe(provided)}`);
+        }
+        break;
+      case "boolean":
+        if (value === "true" || value === "1" || value === 1) value = true;
+        else if (value === "false" || value === "0" || value === 0) value = false;
+        if (typeof value !== "boolean") {
+          throw new Error(`Input "${name}" must be a boolean, got ${describe(provided)}`);
+        }
+        break;
+      case "array":
+        if (typeof value === "string") {
+          try {
+            value = JSON.parse(value);
+          } catch {
+          }
+        }
+        if (!Array.isArray(value)) {
+          throw new Error(`Input "${name}" must be an array, got ${describe(provided)}`);
+        }
+        break;
+      case "object":
+        if (typeof value === "string") {
+          try {
+            value = JSON.parse(value);
+          } catch {
+          }
+        }
+        if (!value || typeof value !== "object" || Array.isArray(value)) {
+          throw new Error(`Input "${name}" must be an object, got ${describe(provided)}`);
+        }
+        break;
+    }
+    if (Array.isArray(decl.enum) && decl.enum.length > 0) {
+      if (!decl.enum.some((allowed) => allowed === value)) {
+        throw new Error(`Input "${name}" must be one of ${JSON.stringify(decl.enum)}, got ${JSON.stringify(value)}`);
+      }
     }
+    resolvedInputs[name] = value;
   }
   const context = resumeState?.context || {
     input: resolvedInputs,
@@ -1207,6 +1293,7 @@ async function executeFlow(flow, inputs, api, permissions, allowedActionIds, opt
     steps: {},
     loop: {}
   };
+  context.input = resolvedInputs;
   const completedStepIds = resumeState ? new Set(resumeState.completedSteps) : void 0;
   if (options.dryRun && !options.mock) {
     options.onEvent?.({
@@ -1271,7 +1358,8 @@ var FLOW_SCHEMA = {
     required: { type: "boolean", required: false, description: "Whether this input must be provided" },
     default: { type: "unknown", required: false, description: "Default value if not provided" },
     description: { type: "string", required: false, description: "Human-readable description" },
-    connection: { type: "object", required: false, description: 'Connection metadata: { platform: "gmail" } \u2014 enables auto-resolution' }
+    connection: { type: "object", required: false, description: 'Connection metadata: { platform: "gmail" } \u2014 enables auto-resolution' },
+    enum: { type: "array", required: false, description: "Allowed values. Resolved input must equal one of these (post-coercion)." }
   },
   stepCommonFields: {
     id: { type: "string", required: true, description: "Unique step identifier (used in selectors)" },
@@ -1279,7 +1367,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-3DCROTPW.js}

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

package/dist/index.js

@@ -16,7 +16,7 @@ import {
   loadFlowWithMeta,
   resolveFlowPath,
   saveFlow
-} from "./chunk-AVOGNLC7.js";
+} from "./chunk-ZOIXA7MV.js";
 
 // src/index.ts
 import { createRequire as createRequire2 } from "module";
@@ -2281,6 +2281,11 @@ function validateFlowSchema(flow2) {
       if (!d.type || !FLOW_SCHEMA.validInputTypes.includes(d.type)) {
         errors.push({ path: `${prefix}.type`, message: `Input type must be one of: ${FLOW_SCHEMA.validInputTypes.join(", ")}` });
       }
+      if (d.enum !== void 0) {
+        if (!Array.isArray(d.enum) || d.enum.length === 0) {
+          errors.push({ path: `${prefix}.enum`, message: '"enum" must be a non-empty array of allowed values' });
+        }
+      }
       if (d.connection !== void 0) {
         if (!d.connection || typeof d.connection !== "object") {
           errors.push({ path: `${prefix}.connection`, message: "Connection metadata must be an object" });
@@ -2320,6 +2325,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 +2548,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.26.0",
   "description": "CLI for managing One",
   "type": "module",
   "files": [

package/skills/one/references/flows.md

@@ -186,9 +186,29 @@ one --agent flow execute <key> -i connectionKey=xxx -i param=value
 | `default` | Default value if not provided |
 | `description` | Human-readable description |
 | `connection` | `{ "platform": "gmail" }` — enables auto-resolution |
+| `enum` | Array of allowed values; rejected if input doesn't match (post-coercion) |
 
 Connection inputs with a `connection` field auto-resolve if the user has exactly one connection for that platform.
 
+**Validation, coercion, and enums.** At flow start the engine validates every declared input:
+
+1. **Required check** — `required: true` (the default) inputs without a value or `default` cause `Missing required input: "X"`.
+2. **Type coercion** — narrow, bidirectional fixes only:
+   - `number`: numeric strings (`"5"`) become `5`. Non-numeric strings throw.
+   - `boolean`: `"true"`/`"1"`/`1` → `true`; `"false"`/`"0"`/`0` → `false`. Anything else throws.
+   - `array` / `object`: JSON strings are parsed. Non-JSON throws.
+   - `string`: anything else is `String(value)`-coerced.
+3. **Enum check** — if `enum` is set, the (coerced) value must be `===` one of the allowed entries. Errors quote both the allowed list and the actual value.
+
+This eliminates the per-flow `if (!$.input.x) throw ...` boilerplate. Errors look like:
+
+```
+Input "tier" must be a number, got string ("lots")
+Input "stage" must be one of ["pre_seed","seed","series_a"], got "ipo"
+```
+
+The same checks run when a step calls a sub-flow, so type/enum guarantees hold across the call boundary.
+
 ## Selector Syntax
 
 | Pattern | Resolves To |
@@ -424,6 +444,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