@lunnoa/client 2.3.0 → 2.4.0

package/README.md

@@ -264,7 +264,7 @@ npx @lunnoa/client agents deploy ./agents/triage.ts \
   --url https://lunnoa.example --api-key lna_...
 ```
 
-`defineAction` binds catalogue actions only; toolkit `createAction` is for in-platform apps. `defineWorkflow` takes an optional `defineTrigger`. Omit it for Manually Run with no input fields. `runs.start` ignores the trigger and runs the steps only. See Lunnoa Docs under `guides/develop/client/define`, `runs`, and `cli-deploy`.
+`defineAction` binds catalogue actions only; toolkit `createAction` is for in-platform apps. `defineWorkflow` takes an optional `defineTrigger`. Omit it for Manually Run with no input fields. `runs.start` ignores the trigger and runs the steps only. Pass data into step settings with `ref.trigger('caseId')` or `ref.step('load', 'rows', 0)` (give the source step a `key`); the server resolves them on deploy and the builder shows them as mapped fields. See Lunnoa Docs under `guides/develop/client/define`, `runs`, and `cli-deploy`.
 
 ### CLI discovery
 

package/dist/cli.js

@@ -1810,7 +1810,9 @@ function stepFromDefinition(step) {
     ...use.input ?? {},
     ...step.input ?? {}
   };
+  const key = step.key;
   return {
+    ...key ? { key } : {},
     appId: resolveActionAppId(use),
     actionId: resolveActionId(use),
     ...use.connection?.id ? { connectionId: use.connection.id } : {},
@@ -2026,6 +2028,7 @@ function triggerToUpsertInput(trigger) {
 function stepToUpsertInput(step) {
   const use = step.use;
   return {
+    ...step.key ? { key: step.key } : {},
     appId: resolveActionAppId(use),
     actionId: resolveActionId(use),
     connectionId: use.connection?.id,

package/dist/index.cjs

@@ -563,7 +563,7 @@ function assertTriggerConfig(config) {
       throw new Error("defineTrigger inputs require id");
     }
   }
-  if (config.inputs?.length && config.id.trim() !== "flow-control_trigger_manual") {
+  if (config.inputs?.length && config.id.trim() !== MANUAL_TRIGGER_ID) {
     throw new Error(
       "defineTrigger inputs are only valid on flow-control_trigger_manual"
     );
@@ -573,6 +573,73 @@ function defineTrigger(config) {
   assertTriggerConfig(config);
   return { kind: DEFINE_KINDS.trigger, ...config };
 }
+var MANUAL_TRIGGER_ID = "flow-control_trigger_manual";
+var TRIGGER_KEY = "trigger";
+var STEP_KEY_PATTERN = /^[A-Za-z][A-Za-z0-9_-]*$/;
+var STEP_REF_PATTERN = /={{step:([^}]*)}}/g;
+function refString(key, path) {
+  const parts = [key, ...path.map(String)];
+  for (const part of parts) {
+    if (!part || /[,{}]/.test(part)) {
+      throw new Error(`ref path parts must be non-empty and contain no , { or }: "${part}"`);
+    }
+  }
+  return `={{step:${parts.join(",")}}}`;
+}
+var ref = {
+  /** A trigger output field, e.g. a Manually Run input id. */
+  trigger: (field, ...path) => refString(TRIGGER_KEY, [field, ...path]),
+  /** An earlier step's output, by its `key`. Array indexes are numbers. */
+  step: (key, ...path) => refString(key, path)
+};
+function collectRefs(value, out) {
+  if (typeof value === "string") {
+    for (const match of value.matchAll(STEP_REF_PATTERN)) {
+      out.push(match[1].split(",").map((part) => part.trim()));
+    }
+  } else if (Array.isArray(value)) {
+    value.forEach((item) => collectRefs(item, out));
+  } else if (value && typeof value === "object") {
+    Object.values(value).forEach((item) => collectRefs(item, out));
+  }
+}
+function assertStepRefs(config) {
+  const triggerId = config.trigger?.id.trim() ?? MANUAL_TRIGGER_ID;
+  const triggerFields = triggerId === MANUAL_TRIGGER_ID ? new Set((config.trigger?.inputs ?? []).map((f) => f.id.trim())) : void 0;
+  const allKeys = /* @__PURE__ */ new Set();
+  for (const step of config.steps) {
+    if (step.key === void 0) continue;
+    if (!STEP_KEY_PATTERN.test(step.key) || step.key === TRIGGER_KEY) {
+      throw new Error(
+        `Step key "${step.key}" must start with a letter, use letters, digits, - or _, and not be "${TRIGGER_KEY}".`
+      );
+    }
+    if (allKeys.has(step.key)) {
+      throw new Error(`Step key "${step.key}" is used twice.`);
+    }
+    allKeys.add(step.key);
+  }
+  const earlier = /* @__PURE__ */ new Set([TRIGGER_KEY]);
+  config.steps.forEach((step, index) => {
+    const refs = [];
+    collectRefs([step.use?.input, step.input], refs);
+    const where = `Step "${step.key ?? step.name ?? index + 1}"`;
+    for (const [key = "", ...path] of refs) {
+      const shown = `={{step:${[key, ...path].join(",")}}}`;
+      if (!earlier.has(key)) {
+        throw new Error(
+          allKeys.has(key) ? `${where}: ${shown} refers to itself or a later step. Use the trigger or an earlier step.` : `${where}: ${shown} names unknown key "${key}". Use "trigger" or an earlier step's key.`
+        );
+      }
+      if (key === TRIGGER_KEY && triggerFields && !triggerFields.has(path[0] ?? "")) {
+        throw new Error(
+          `${where}: ${shown} uses trigger field "${path[0] ?? ""}", which is not declared in trigger inputs.`
+        );
+      }
+    }
+    if (step.key) earlier.add(step.key);
+  });
+}
 function defineWorkflow(config) {
   if (!config.slug?.trim()) {
     throw new Error("defineWorkflow requires slug");
@@ -583,6 +650,7 @@ function defineWorkflow(config) {
   if (config.trigger) {
     assertTriggerConfig(config.trigger);
   }
+  assertStepRefs(config);
   return { kind: DEFINE_KINDS.workflow, ...config };
 }
 function defineAgent(config) {
@@ -1874,7 +1942,9 @@ function stepFromDefinition(step) {
     ...use.input ?? {},
     ...step.input ?? {}
   };
+  const key = step.key;
   return {
+    ...key ? { key } : {},
     appId: resolveActionAppId(use),
     actionId: resolveActionId(use),
     ...use.connection?.id ? { connectionId: use.connection.id } : {},
@@ -2090,6 +2160,7 @@ function triggerToUpsertInput(trigger) {
 function stepToUpsertInput(step) {
   const use = step.use;
   return {
+    ...step.key ? { key: step.key } : {},
     appId: resolveActionAppId(use),
     actionId: resolveActionId(use),
     connectionId: use.connection?.id,
@@ -2355,6 +2426,7 @@ exports.iterateOffset = iterateOffset;
 exports.iteratePages = iteratePages;
 exports.parseSseEvents = parseSseEvents;
 exports.parseSseStream = parseSseStream;
+exports.ref = ref;
 exports.resolveActionAppId = resolveActionAppId;
 exports.resolveActionId = resolveActionId;
 exports.resolveTriggerAppId = resolveTriggerAppId;