@particle-academy/fancy-flow 0.15.0 → 0.16.0

package/dist/engine.cjs

@@ -222,6 +222,8 @@ function pauseForHuman(ctx, awaiting, detail) {
 var NODE_MANIFEST_SCHEMA_VERSION = 1;
 var FIRST_PARTY_SCOPE = "@particle-academy/";
 var NAMESPACED_KIND = /^@[a-z0-9][a-z0-9._-]*\/[a-z0-9][a-z0-9._-]*$/i;
+var SIDE_EFFECTS = ["none", "idempotent", "unsafe-to-replay"];
+var REQUIREMENTS = ["required", "optional"];
 function err(field, message) {
   return { level: "error", field, message };
 }
@@ -252,72 +254,200 @@ function validateNodeManifest(input) {
   if (typeof m.name !== "string" || m.name.trim() === "") {
     problems.push(err("name", "Required \u2014 the package name as installed."));
   }
-  if (typeof m.kind !== "string" || m.kind.trim() === "") {
+  validateKind(m.kind, problems);
+  validateAliases(m.aliases, problems);
+  if (m.configVersion !== void 0 && (typeof m.configVersion !== "number" || !Number.isInteger(m.configVersion))) {
+    problems.push(err("configVersion", "Must be an integer."));
+  }
+  if (m.fancyFlow !== void 0) {
+    problems.push(
+      err(
+        "fancyFlow",
+        'A single engine range cannot express the split \u2014 it cannot say "needs ts >=0.15 AND php >=0.7". Move the range into each entry of `runtimes` as `engine`.'
+      )
+    );
+  }
+  validateRuntimes(m.runtimes, problems);
+  if (typeof m.fixtures !== "string" || m.fixtures.trim() === "") {
+    problems.push(
+      err("fixtures", "Required \u2014 path to the node's golden fixtures. Every claimed runtime runs them, which is what makes cross-runtime parity verified rather than claimed.")
+    );
+  }
+  validateCapabilities(m.capabilities, problems);
+  if (m.sideEffects !== void 0 && !SIDE_EFFECTS.includes(m.sideEffects)) {
+    problems.push(err("sideEffects", `Must be one of: ${SIDE_EFFECTS.join(", ")}.`));
+  }
+  if (m.verified !== void 0) {
+    problems.push(
+      err("verified", "Assigned by the registry, not the package. Remove it \u2014 a package cannot vouch for itself.")
+    );
+  }
+  const ok = !problems.some((p) => p.level === "error");
+  return ok ? { ok, manifest: m, problems } : { ok, problems };
+}
+function validateKind(kind, problems) {
+  if (typeof kind !== "string" || kind.trim() === "") {
     problems.push(err("kind", "Required \u2014 the canonical kind id this package provides."));
-  } else if (!NAMESPACED_KIND.test(m.kind)) {
+    return;
+  }
+  if (!NAMESPACED_KIND.test(kind)) {
     problems.push(
-      err("kind", `"${m.kind}" must be namespaced as @scope/name \u2014 a bare id makes stored graphs ambiguous, and that is unfixable once documents carry it.`)
+      err("kind", `"${kind}" must be namespaced as @scope/name \u2014 a bare id makes stored graphs ambiguous, and that is unfixable once documents carry it.`)
     );
-  } else if (m.kind.startsWith(FIRST_PARTY_SCOPE)) {
+    return;
+  }
+  if (kind.startsWith(FIRST_PARTY_SCOPE)) {
     problems.push(
       warn("kind", `${FIRST_PARTY_SCOPE}* is reserved for first-party nodes; the registry will reject this unless the package is first-party.`)
     );
   }
-  if (typeof m.fancyFlow !== "string" || m.fancyFlow.trim() === "") {
-    problems.push(err("fancyFlow", "Required \u2014 the semver range of fancy-flow this node targets."));
+}
+function validateAliases(aliases2, problems) {
+  if (aliases2 === void 0) return;
+  if (!Array.isArray(aliases2) || aliases2.some((a) => typeof a !== "string" || a.trim() === "")) {
+    problems.push(err("aliases", "Must be an array of non-empty id strings."));
+  }
+}
+function validateRuntimes(runtimes, problems) {
+  if (typeof runtimes !== "object" || runtimes === null || Array.isArray(runtimes)) {
+    problems.push(err("runtimes", "Required \u2014 an object of runtime id to { entry | package, engine }."));
+    return;
   }
-  if (typeof m.runtimes !== "object" || m.runtimes === null || Array.isArray(m.runtimes)) {
-    problems.push(err("runtimes", "Required \u2014 an object of runtime id to entrypoint."));
-  } else {
-    const entries = Object.entries(m.runtimes);
-    if (entries.length === 0) {
-      problems.push(err("runtimes", "A node that implements no runtime cannot execute anywhere."));
+  const entries = Object.entries(runtimes);
+  if (entries.length === 0) {
+    problems.push(err("runtimes", "A node that implements no runtime cannot execute anywhere."));
+    return;
+  }
+  for (const [runtime, spec] of entries) {
+    if (typeof spec !== "object" || spec === null || Array.isArray(spec)) {
+      problems.push(err(`runtimes.${runtime}`, "Must be an object of { entry | package, engine }."));
+      continue;
     }
-    for (const [runtime, entry] of entries) {
-      if (typeof entry !== "string" || entry.trim() === "") {
-        problems.push(err(`runtimes.${runtime}`, "Entrypoint must be a non-empty string."));
-      }
+    const s = spec;
+    const hasEntry = typeof s.entry === "string" && s.entry.trim() !== "";
+    const hasPackage = typeof s.package === "string" && s.package.trim() !== "";
+    if (!hasEntry && !hasPackage) {
+      problems.push(err(`runtimes.${runtime}`, "Needs `entry` (a module path) or `package` (a dependency requirement)."));
+    }
+    if (hasEntry && hasPackage) {
+      problems.push(err(`runtimes.${runtime}`, "Declare `entry` or `package`, not both \u2014 which one is authoritative is otherwise ambiguous."));
+    }
+    if (typeof s.engine !== "string" || s.engine.trim() === "") {
+      problems.push(
+        err(`runtimes.${runtime}.engine`, `Required \u2014 the semver range of the ${runtime} engine. Without it, this node installs against a ${runtime} engine too old to run it.`)
+      );
     }
   }
-  if (typeof m.fixtures !== "string" || m.fixtures.trim() === "") {
+}
+function validateCapabilities(capabilities, problems) {
+  if (capabilities === void 0) return;
+  if (typeof capabilities !== "object" || capabilities === null || Array.isArray(capabilities)) {
     problems.push(
-      err("fixtures", "Required \u2014 path to the node's golden fixtures. Every claimed runtime runs them, which is what makes cross-runtime parity verified rather than claimed.")
+      err("capabilities", 'Must be an object of capability id to "required" | "optional" \u2014 a bare list cannot say whether the node works without one.')
     );
+    return;
   }
-  if (m.capabilities !== void 0) {
-    if (!Array.isArray(m.capabilities) || m.capabilities.some((c) => typeof c !== "string")) {
-      problems.push(err("capabilities", "Must be an array of capability id strings."));
+  for (const [id, requirement] of Object.entries(capabilities)) {
+    if (!REQUIREMENTS.includes(requirement)) {
+      problems.push(err(`capabilities.${id}`, `Must be "required" or "optional".`));
     }
   }
-  if (m.verified !== void 0) {
+}
+function checkRuntimeSupport(manifest, hostRuntimes, engineVersions) {
+  const runtimes = manifest.runtimes ?? {};
+  const provided = Object.keys(runtimes);
+  const problems = [];
+  const missing = hostRuntimes.filter((r) => !provided.includes(r));
+  if (missing.length > 0) {
     problems.push(
-      err("verified", "Assigned by the registry, not the package. Remove it \u2014 a package cannot vouch for itself.")
+      err(
+        "runtimes",
+        `${manifest.kind} implements ${provided.join(", ") || "no runtime"} but this project executes on ${missing.join(", ")}. The node would install, appear in the palette, and then fail to run.`
+      )
     );
   }
-  const ok = !problems.some((p) => p.level === "error");
-  return ok ? { ok, manifest: m, problems } : { ok, problems };
+  for (const runtime of hostRuntimes) {
+    const spec = runtimes[runtime];
+    if (!spec) continue;
+    const hostVersion = engineVersions?.[runtime];
+    if (hostVersion === void 0) {
+      problems.push(
+        warn(`runtimes.${runtime}.engine`, `${manifest.kind} needs ${runtime} engine ${spec.engine}; this host did not report its ${runtime} version, so the range was not checked.`)
+      );
+      continue;
+    }
+    if (!satisfiesRange(hostVersion, spec.engine)) {
+      problems.push(
+        err(`runtimes.${runtime}.engine`, `${manifest.kind} needs ${runtime} engine ${spec.engine}, but this host runs ${hostVersion}.`)
+      );
+    }
+  }
+  return problems;
 }
-function checkRuntimeSupport(manifest, hostRuntimes) {
-  const provided = Object.keys(manifest.runtimes ?? {});
-  const missing = hostRuntimes.filter((r) => !provided.includes(r));
-  if (missing.length === 0) return [];
-  return [
-    err(
-      "runtimes",
-      `${manifest.kind} implements ${provided.join(", ") || "no runtime"} but this project executes on ${missing.join(", ")}. The node would install, appear in the palette, and then fail to run.`
-    )
-  ];
+function satisfiesRange(version, range) {
+  const trimmed = range.trim();
+  if (trimmed === "*" || trimmed === "") return true;
+  const v = parseVersion(version);
+  if (!v) return false;
+  for (const clause of trimmed.split("||").map((c) => c.trim())) {
+    if (satisfiesClause(v, clause)) return true;
+  }
+  return false;
+}
+function satisfiesClause(v, clause) {
+  const m = /^(\^|~|>=|>|<=|<|=)?\s*v?(\d+)(?:\.(\d+))?(?:\.(\d+))?/.exec(clause);
+  if (!m) return false;
+  const op = m[1] ?? "=";
+  const target = [Number(m[2]), Number(m[3] ?? 0), Number(m[4] ?? 0)];
+  const cmp = compare(v, target);
+  switch (op) {
+    case ">=":
+      return cmp >= 0;
+    case ">":
+      return cmp > 0;
+    case "<=":
+      return cmp <= 0;
+    case "<":
+      return cmp < 0;
+    case "=":
+      return cmp === 0;
+    case "~":
+      return cmp >= 0 && v[0] === target[0] && v[1] === target[1];
+    case "^":
+      if (target[0] === 0) return cmp >= 0 && v[0] === 0 && v[1] === target[1];
+      return cmp >= 0 && v[0] === target[0];
+    default:
+      return false;
+  }
+}
+function parseVersion(version) {
+  const m = /^v?(\d+)\.(\d+)(?:\.(\d+))?/.exec(version.trim());
+  return m ? [Number(m[1]), Number(m[2]), Number(m[3] ?? 0)] : null;
+}
+function compare(a, b) {
+  for (let i = 0; i < 3; i++) {
+    if (a[i] !== b[i]) return a[i] < b[i] ? -1 : 1;
+  }
+  return 0;
 }
 function checkCapabilities(manifest, available) {
-  const needed = manifest.capabilities ?? [];
-  const missing = needed.filter((c) => available[c] !== true);
-  if (missing.length === 0) return [];
-  return [
-    warn(
-      "capabilities",
-      `${manifest.kind} needs ${missing.join(", ")} wired on the host. Until then the node will fail at run time rather than at install.`
-    )
-  ];
+  const needed = manifest.capabilities ?? {};
+  const problems = [];
+  for (const [id, requirement] of Object.entries(needed)) {
+    if (available[id] === true) continue;
+    problems.push(
+      requirement === "required" ? err("capabilities", `${manifest.kind} requires the ${id} capability, which this host has not registered. The node cannot run here.`) : warn("capabilities", `${manifest.kind} can use the ${id} capability, which this host has not registered. The node runs with reduced behaviour.`)
+    );
+  }
+  return problems;
+}
+function registerLlmClient(client) {
+  return () => {
+  };
+}
+function registerWorkflowResolver(resolver) {
+  return () => {
+  };
 }
 
 // src/marketplace/fixtures.ts
@@ -332,7 +462,7 @@ function buildGraph(kindId, testCase) {
     data: { kind: kindId, config: testCase.config ?? {} }
   };
   const kind = getNodeKind(kindId) ?? void 0;
-  const ports = (resolveNodePorts(subject, kind).outputs ?? []).map((p) => p.id);
+  const ports = testCase.ports ?? (resolveNodePorts(subject, kind).outputs ?? []).map((p) => p.id);
   const effective = ports.length ? ports : ["out"];
   const nodes = [
     { id: TRIGGER, type: "manual_trigger", position: { x: 0, y: 0 }, data: {} },
@@ -360,17 +490,67 @@ function buildGraph(kindId, testCase) {
 function deepEqual(a, b) {
   return JSON.stringify(a) === JSON.stringify(b);
 }
+function installStubs(stubs) {
+  if (!stubs) return () => {
+  };
+  const teardown = [];
+  if (stubs.llm_client) {
+    stubs.llm_client.chooseRoute;
+    teardown.push(registerLlmClient());
+  }
+  if (stubs.workflow_resolver) {
+    stubs.workflow_resolver;
+    teardown.push(registerWorkflowResolver());
+  }
+  return () => teardown.forEach((fn) => fn());
+}
+function matchesEvent(event, want) {
+  if (event.type !== want.type) return false;
+  const e = event;
+  if (want.nodeId !== void 0 && e.nodeId !== want.nodeId) return false;
+  if (want.level !== void 0 && e.level !== want.level) return false;
+  if (want.messageContains !== void 0 && !String(e.message ?? "").includes(want.messageContains)) return false;
+  return true;
+}
+async function resume(kindId, testCase, executor, pausedNodeId, submit) {
+  const { graph } = buildGraph(kindId, testCase);
+  const fired = [];
+  let carried;
+  const executors = {
+    manual_trigger: () => testCase.inputs ?? {},
+    "@particle-academy/manual_trigger": () => testCase.inputs ?? {},
+    [kindId]: executor
+  };
+  executors[pausedNodeId] = ((c) => executor({ ...c, inputs: { ...c.inputs, values: submit } }));
+  for (const node of graph.nodes) {
+    if (!node.id.startsWith("probe:")) continue;
+    const port = node.id.slice("probe:".length);
+    executors[node.id] = ((c) => {
+      fired.push(port);
+      carried = c.inputs?.in ?? c.inputs;
+      return void 0;
+    });
+  }
+  const releaseStubs = installStubs(testCase.stubs);
+  const result = await runFlow(graph, executors, () => {
+  });
+  releaseStubs();
+  return { ok: result.ok, error: result.error, fired, carried };
+}
 async function runFixtures(file, executor) {
   const failures = [];
   let passed = 0;
   for (const testCase of file.cases) {
-    const { graph } = buildGraph(file.kind, testCase);
+    const kindId = testCase.legacyKind ?? file.kind;
+    const { graph } = buildGraph(kindId, testCase);
     const fired = [];
+    const events = [];
     let carried;
+    const releaseStubs = installStubs(testCase.stubs);
     const executors = {
       manual_trigger: () => testCase.inputs ?? {},
       "@particle-academy/manual_trigger": () => testCase.inputs ?? {},
-      [file.kind]: executor
+      [kindId]: executor
     };
     for (const node of graph.nodes) {
       if (!node.id.startsWith("probe:")) continue;
@@ -381,8 +561,8 @@ async function runFixtures(file, executor) {
         return void 0;
       });
     }
-    const result = await runFlow(graph, executors, () => {
-    });
+    const result = await runFlow(graph, executors, (e) => events.push(e));
+    releaseStubs();
     const fail = (message) => failures.push({ case: testCase.name, message });
     const expected = testCase.expect;
     let caseOk = true;
@@ -425,6 +605,40 @@ async function runFixtures(file, executor) {
         fail(`expected the value carried downstream to be ${JSON.stringify(expected.value)}, got ${JSON.stringify(carried)}`);
       }
     }
+    for (const want of expected.events ?? []) {
+      if (!events.some((e) => matchesEvent(e, want))) {
+        caseOk = false;
+        fail(`expected an emitted event matching ${JSON.stringify(want)}, but none of the ${events.length} emitted events did`);
+      }
+    }
+    if (expected.afterResume) {
+      const paused = decodePause(result.error);
+      if (!paused) {
+        caseOk = false;
+        fail("expected the run to pause before resuming, but it never paused");
+      } else {
+        const resumed = await resume(kindId, testCase, executor, paused.nodeId, expected.afterResume.submit);
+        const want = expected.afterResume;
+        if (want.error !== void 0) {
+          if (resumed.ok || !String(resumed.error ?? "").includes(want.error)) {
+            caseOk = false;
+            fail(`after resume: expected an error containing "${want.error}", got ${resumed.ok ? "success" : `"${resumed.error}"`}`);
+          }
+        }
+        if (want.ports !== void 0) {
+          const got = [...resumed.fired].sort();
+          const wanted = [...want.ports].sort();
+          if (!deepEqual(got, wanted)) {
+            caseOk = false;
+            fail(`after resume: expected ports [${wanted.join(", ")}] to reach a downstream node, but [${got.join(", ")}] did`);
+          }
+        }
+        if ("value" in want && !deepEqual(resumed.carried, want.value)) {
+          caseOk = false;
+          fail(`after resume: expected the value carried downstream to be ${JSON.stringify(want.value)}, got ${JSON.stringify(resumed.carried)}`);
+        }
+      }
+    }
     if (caseOk) passed += 1;
   }
   return { ok: failures.length === 0, passed, failures };
@@ -444,6 +658,15 @@ function validateFixtureFile(input, expectedKind) {
     problems.push("`cases` must contain at least one case \u2014 an empty fixture file proves nothing.");
     return problems;
   }
+  const coversFailure = f.cases.some((c) => {
+    const expect = c?.expect;
+    return Boolean(expect && ("error" in expect || "pause" in expect));
+  });
+  if (!coversFailure) {
+    problems.push(
+      "At least one case must assert a failure (`expect.error`) or a pause (`expect.pause`). Every case here covers a success path, and the divergence this format exists to catch reported success while doing nothing."
+    );
+  }
   f.cases.forEach((c, i) => {
     const label = `cases[${i}]`;
     if (typeof c !== "object" || c === null) {
@@ -480,6 +703,7 @@ exports.isPause = isPause;
 exports.pauseForHuman = pauseForHuman;
 exports.runFixtures = runFixtures;
 exports.runFlow = runFlow;
+exports.satisfiesRange = satisfiesRange;
 exports.validateFixtureFile = validateFixtureFile;
 exports.validateNodeManifest = validateNodeManifest;
 //# sourceMappingURL=engine.cjs.map