@revenexx/studio-integrations 0.7.0 → 1.1.0

package/dist/runtime/data/loopBody.d.ts

@@ -0,0 +1,129 @@
+import type { NodeManifest, WorkflowEdge, WorkflowNode } from '../types/integrations.js';
+/**
+ * Which nodes repeat, and which edges are walked once per element (PO-277).
+ *
+ * The iterator draws its two outputs like any other pair of ports, so nothing
+ * on the canvas said that everything hanging off `item` runs once per element
+ * while everything off `done` runs once, afterwards. This module computes the
+ * repeating part; the canvases mark it (`specs/editor-loop-body.md`).
+ *
+ * **The set is the engine's, not a tidier one.** `getLoopBodyNodes`
+ * (`worker/src/dagUtils.ts`) walks forward from the `item` port and follows
+ * EVERY outgoing edge it meets — an error route, a nested iterator's `done`,
+ * an edge the author meant as "and afterwards, do this". There is no stop
+ * condition, because the loop body has no end anywhere in the workflow. The
+ * walk below is that walk, deliberately: a UI that computed the body the
+ * author *meant* would draw nothing on the node that surprises them, which is
+ * the one case this is for.
+ *
+ * **Nesting needs no special case.** The engine narrows an inner iterator's
+ * body to its outer one (`getLoopBodyNodes(inner, edges, loopBodyIds)`), but a
+ * body is closed under reachability and the inner iterator is in the outer
+ * body — so everything reachable from the inner `item` is already in the outer
+ * one, and the narrowing never removes anything. A node inside two loops is
+ * therefore simply a member of both bodies, which is what `depth` counts.
+ */
+/** The iterator's repeating output — the port the body hangs off. */
+export declare const ITEM_PORT = "item";
+/** The iterator's post-loop output — everything off it runs once, at the end. */
+export declare const DONE_PORT = "done";
+/**
+ * Nodes known to iterate while no manifest says so.
+ *
+ * The worker learns which nodes iterate at bundle-build time by duck-typing the
+ * implementation (`builder/src/generateEntry.ts` → `MANIFEST.iterationNodeIds`),
+ * and nothing of that reaches the studio: `GET /nodes` publishes the manifest,
+ * and no field in it says "this node repeats what is wired to it". Until one
+ * does — {@link NodeManifest.iteration}, read first by {@link manifestIterates}
+ * — the editor has to know the published iterator by name. One slug, in one
+ * place, rather than the same string spelled out at every call site.
+ */
+export declare const ITERATOR_SLUGS: readonly string[];
+/**
+ * Whether a manifest describes a node that runs its `item` side per element.
+ *
+ * A manifest that carries the field at all is believed either way — `false`
+ * defeats the slug fallback. Otherwise the day the service starts publishing it,
+ * a published `iteration: false` on the very slug below would be overruled by
+ * this file, which is the one answer the field exists to give.
+ */
+export declare function manifestIterates(manifest: NodeManifest | null | undefined): boolean;
+/** The blob's iterator nodes, in blob order. */
+export declare function iteratorNodeIds(nodes: readonly WorkflowNode[]): string[];
+/** One iterator's body: what repeats, and where it overlaps the `done` side. */
+export interface LoopBody {
+    /** The iterator whose `item` port this body hangs off. */
+    iteratorId: string;
+    /** Every node the engine would run once per element. */
+    nodeIds: Set<string>;
+    /**
+     * Body nodes that are ALSO reachable from `done` — the author wired the body
+     * into the part meant to run after the loop, and the engine repeats it.
+     *
+     * Only the join case is provable. Where `done` is wired nowhere, a node
+     * appended to the body is indistinguishable from a node meant to be in it, so
+     * nothing here reports it (`specs/editor-loop-body.md` § Gaps). The mark on
+     * the card is what covers that case: it says "this repeats" wherever it is
+     * true, whether or not anything can tell it was a mistake.
+     */
+    joinedWithDone: Set<string>;
+}
+/**
+ * One body per iterator id, in the order given.
+ *
+ * Pure on purpose — the catalogue lookup that decides what an iterator IS lives
+ * in {@link iteratorNodeIds}, so the walk can be tested against a graph alone.
+ */
+export declare function computeLoopBodies(iteratorIds: readonly string[], edges: readonly WorkflowEdge[]): LoopBody[];
+/** What one node card has to say about repeating. */
+export interface LoopBodyMark {
+    /**
+     * How many bodies this node is in — 1 for a plain loop, 2 inside a nested
+     * one. The card shows the number from 2 up: "repeats" is the news at depth 1,
+     * "repeats per element of both" is the news above it.
+     */
+    depth: number;
+    /** The iterators, outermost first (a larger body encloses a smaller one). */
+    iteratorIds: string[];
+}
+/**
+ * Marks for a whole canvas: which nodes repeat, and the bodies behind them.
+ *
+ * **Nodes only, deliberately — the connections carry nothing.** Tinting the
+ * body's edges was the obvious other half, and it is the one thing this could
+ * not do: `specs/editor-output-paths.md` AC-2 promises that the lines carry no
+ * meaning and stay neutral, and colour and dashing on an edge are both reserved
+ * for a run that actually happened (`docs/editor-path-colors.md`). A body drawn
+ * in a colour of its own would take that promise back for every workflow with a
+ * loop in it.
+ */
+export interface LoopBodyMarks {
+    byNode: Map<string, LoopBodyMark>;
+    bodies: LoopBody[];
+}
+/**
+ * The whole computation for one blob, ready to hand to a canvas.
+ *
+ * Called by all three canvases (editor, run replay, history preview) on every
+ * sync: the marks depend on the edges, so anything less would let a rewired
+ * body keep an old mark. The cost is one pass over the edges to build the
+ * adjacency map, then two breadth-first walks per iterator over it — and a
+ * workflow with no iterator in it costs one filter over the nodes.
+ */
+export declare function loopBodyMarks(nodes: readonly WorkflowNode[], edges: readonly WorkflowEdge[]): LoopBodyMarks;
+/** What one canvas hands a node card about repetition. */
+export interface NodeLoopData {
+    /** The iterators whose body this node is in, outermost first, by label. */
+    inside?: string[];
+    /** Set on an iterator itself: how many nodes hang off its `item` port. */
+    bodySize?: number;
+}
+/**
+ * One call per canvas sync: node id → what its card says about repeating.
+ *
+ * Names rather than ids, because the card shows the sentence — and the same
+ * three steps a banner uses to name a node ({@link nodeDisplayLabel}), so a
+ * loop the user renamed is named that everywhere. Absent from the map means
+ * nothing to say, which is the common case and costs the card nothing.
+ */
+export declare function nodeLoopData(nodes: readonly WorkflowNode[], edges: readonly WorkflowEdge[]): Map<string, NodeLoopData>;

package/dist/runtime/data/loopBody.js

@@ -0,0 +1,76 @@
+import { nodeDisplayLabel } from "../utils/validationFindings.js";
+import { findManifest } from "./integrationNodeCatalog.js";
+export const ITEM_PORT = "item";
+export const DONE_PORT = "done";
+export const ITERATOR_SLUGS = ["revenexx:iterator"];
+export function manifestIterates(manifest) {
+  if (!manifest) return false;
+  if (manifest.iteration !== void 0) return manifest.iteration;
+  return ITERATOR_SLUGS.includes(manifest.slug);
+}
+export function iteratorNodeIds(nodes) {
+  return nodes.filter((n) => manifestIterates(findManifest(n.nodeSlug, n.nodeVersion))).map((n) => n.id);
+}
+function successors(edges) {
+  const out = /* @__PURE__ */ new Map();
+  for (const edge of edges) {
+    const list = out.get(edge.from.nodeId);
+    if (list) list.push(edge.to.nodeId);
+    else out.set(edge.from.nodeId, [edge.to.nodeId]);
+  }
+  return out;
+}
+function reachableFromPort(fromNodeId, output, edges, next = successors(edges)) {
+  const visited = /* @__PURE__ */ new Set();
+  const queue = [];
+  for (const edge of edges) {
+    if (edge.from.nodeId === fromNodeId && edge.from.output === output) queue.push(edge.to.nodeId);
+  }
+  for (let head = 0; head < queue.length; head++) {
+    const nodeId = queue[head];
+    if (visited.has(nodeId)) continue;
+    visited.add(nodeId);
+    for (const target of next.get(nodeId) ?? []) {
+      if (!visited.has(target)) queue.push(target);
+    }
+  }
+  return visited;
+}
+export function computeLoopBodies(iteratorIds, edges) {
+  const next = successors(edges);
+  return iteratorIds.map((iteratorId) => {
+    const nodeIds = reachableFromPort(iteratorId, ITEM_PORT, edges, next);
+    const afterLoop = reachableFromPort(iteratorId, DONE_PORT, edges, next);
+    const joinedWithDone = new Set([...nodeIds].filter((id) => afterLoop.has(id)));
+    return { iteratorId, nodeIds, joinedWithDone };
+  });
+}
+export function loopBodyMarks(nodes, edges) {
+  const bodies = computeLoopBodies(iteratorNodeIds(nodes), edges);
+  const byNode = /* @__PURE__ */ new Map();
+  const outermostFirst = [...bodies].sort((a, b) => b.nodeIds.size - a.nodeIds.size);
+  for (const body of outermostFirst) {
+    for (const nodeId of body.nodeIds) {
+      const mark = byNode.get(nodeId) ?? { depth: 0, iteratorIds: [] };
+      mark.depth += 1;
+      mark.iteratorIds.push(body.iteratorId);
+      byNode.set(nodeId, mark);
+    }
+  }
+  return { byNode, bodies };
+}
+export function nodeLoopData(nodes, edges) {
+  const marks = loopBodyMarks(nodes, edges);
+  if (!marks.bodies.length) return /* @__PURE__ */ new Map();
+  const labelOf = new Map(nodes.map((n) => [n.id, nodeDisplayLabel(n)]));
+  const out = /* @__PURE__ */ new Map();
+  for (const [nodeId, mark] of marks.byNode) {
+    out.set(nodeId, { inside: mark.iteratorIds.map((id) => labelOf.get(id) ?? id) });
+  }
+  for (const body of marks.bodies) {
+    const entry = out.get(body.iteratorId) ?? {};
+    entry.bodySize = body.nodeIds.size;
+    out.set(body.iteratorId, entry);
+  }
+  return out;
+}

package/dist/runtime/data/nodeInputData.d.ts

@@ -1,4 +1,4 @@
-import type { NodeManifest, NodeManifestOutput, OutputKind, WorkflowEdge, WorkflowNode } from '../types/integrations.js';
+import type { LocalizedString, NodeManifest, NodeManifestOutput, OutputKind, WorkflowEdge, WorkflowNode } from '../types/integrations.js';
 /** `${{ nodes.<id>.outputs.<port> }}`, optionally narrowed to one field. */
 export declare function nodeOutputExpr(nodeId: string, port: string, field?: string): string;
 /** `${{ trigger.payload }}`, optionally narrowed to a path inside it. */
@@ -20,13 +20,70 @@ export interface FieldEntry {
     name: string;
     /** Declared data type (`string`, `number`, `boolean`, …) when the manifest carries one. */
     dataType: string | null;
+    /**
+     * What the publisher says this field holds, unresolved. Kept in the shape the
+     * manifest sent it so the language is chosen where it is drawn — see the note
+     * on {@link PortEntry.description}.
+     */
+    description?: LocalizedString;
 }
 export interface PortEntry {
     name: string;
     kind: OutputKind;
     /** Declared payload fields of this port (schema; may be empty). */
     fields: FieldEntry[];
+    /**
+     * What the publisher says flows through this port, **unresolved** — the
+     * localised map as the manifest sent it, not a string.
+     *
+     * Resolving here would pick the language at the moment the ports are derived,
+     * and these helpers are pure by design: their tests would then depend on the
+     * studio's locale, and a language switched afterwards would not reach a port
+     * list already computed. So the raw value travels and whoever draws it calls
+     * the resolver, which is how every other manifest string in the studio is
+     * read. Absent rather than null when the publisher wrote none: most do not,
+     * and an optional key keeps the derivation's shape honest about that.
+     */
+    description?: LocalizedString;
 }
+export interface InputPortEntry {
+    name: string;
+    /** Declared data type of what the node accepts here. */
+    dataType: string | null;
+    /**
+     * Whether an upstream connection is mandatory.
+     *
+     * Most manifests leave the key out, so the default decides what nearly every
+     * node claims. It is **the service's**, not ours: the node-manifest schema
+     * documents `required` as *"Whether an upstream connection is mandatory.
+     * Defaults to true."*, so an absent key is read as required and the chip says
+     * so. Reading it the other way would have the studio call a mandatory input
+     * optional on the strength of a key nobody wrote.
+     *
+     * It is a statement about what the type **declares**, not a rule anything
+     * enforces — nothing in the studio blocks a save over it, and the service's own
+     * blob validation checks that a named port exists rather than that it is fed.
+     */
+    required: boolean;
+    /** What the publisher says the node expects, unresolved — see {@link PortEntry.description}. */
+    description?: LocalizedString;
+}
+/**
+ * What a node accepts, read from the manifest's `inputs` map.
+ *
+ * **Two wire shapes, one of them a trap.** A node with named ports arrives as an
+ * object; a node that accepts nothing arrives as `[]`, because the service
+ * encodes an empty PHP array as a JSON array rather than an object. So the empty
+ * case has a different JSON *type* from the populated one, and reading it with
+ * `Object.entries` alone would work by luck rather than by intent. Both land here
+ * as an empty list.
+ *
+ * The studio read this under a singular `input` key until PO-216 — a shape the
+ * service has never sent and its schema forbids, so every input a node declared
+ * was invisible: the sentence, the data type, and whether a connection was
+ * mandatory at all.
+ */
+export declare function inputPortsForManifest(manifest: NodeManifest | null | undefined): InputPortEntry[];
 /**
  * A manifest declaring zero output ports describes a TERMINAL node (PO-201):
  * the run ends there, so it gets no output handle and no edge may leave it.

package/dist/runtime/data/nodeInputData.js

@@ -37,13 +37,38 @@ export function collectUpstreamNodes(selectedId, nodes, edges) {
 function fieldEntries(raw) {
   if (Array.isArray(raw)) return raw.map((v) => ({ name: String(v), dataType: null }));
   if (raw && typeof raw === "object") {
-    return Object.entries(raw).map(([name, spec]) => ({
-      name,
-      dataType: spec && typeof spec === "object" && typeof spec.dataType === "string" ? spec.dataType : null
-    }));
+    return Object.entries(raw).map(([name, spec]) => {
+      const s = spec && typeof spec === "object" ? spec : null;
+      return {
+        name,
+        dataType: typeof s?.dataType === "string" ? s.dataType : null,
+        ...describedBy(s?.description)
+      };
+    });
   }
   return [];
 }
+function describedBy(raw) {
+  if (typeof raw === "string") return raw.trim() ? { description: raw.trim() } : {};
+  if (raw && typeof raw === "object" && !Array.isArray(raw)) {
+    const entries = Object.entries(raw).filter((e) => typeof e[1] === "string" && e[1].trim() !== "").map(([k, v]) => [k, v.trim()]);
+    return entries.length ? { description: Object.fromEntries(entries) } : {};
+  }
+  return {};
+}
+export function inputPortsForManifest(manifest) {
+  const raw = manifest?.inputs;
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return [];
+  return Object.entries(raw).map(([name, spec]) => {
+    const s = spec && typeof spec === "object" ? spec : null;
+    return {
+      name,
+      dataType: typeof s?.dataType === "string" ? s.dataType : null,
+      required: s?.required !== false,
+      ...describedBy(s?.description)
+    };
+  });
+}
 export function isTerminalManifest(manifest) {
   return !!manifest && Array.isArray(manifest.outputs) && !manifest.outputs.length;
 }
@@ -53,7 +78,7 @@ export function portsForNode(node, manifest, resolvedOutputs) {
   const ports = [];
   for (const o of list) {
     if (o.name) {
-      ports.push({ name: o.name, kind: o.kind, fields: fieldEntries(o.fields) });
+      ports.push({ name: o.name, kind: o.kind, fields: fieldEntries(o.fields), ...describedBy(o.description) });
     } else if (o.sourceFromConfig) {
       const raw = node.config?.[o.sourceFromConfig];
       const values = Array.isArray(raw) ? raw : [];

package/dist/runtime/data/triggerGlyphs.d.ts

@@ -0,0 +1,47 @@
+import type { Component } from 'vue';
+import type { TriggerType } from '../types/integrations.js';
+/**
+ * Trigger type → glyph, for every surface that draws one.
+ *
+ * Eight files drew a trigger's glyph, and they did it two ways. Five spelled the
+ * mapping out — the canvas card and the run replay panel as ternaries, the node
+ * inspector's header, the template card and the template detail page as records —
+ * and three did not carry a mapping at all: they resolved a glyph from Lucide by
+ * *name*, so no import mentioned one, in the node palette's trigger tiles (through
+ * `nodeIcon`), the create dialog's trigger select and the template flow preview
+ * (each through a local `iconFor`).
+ *
+ * They did not agree: a webhook was a globe on the templates page, a link on the
+ * canvas and Lucide's pretzel in the palette, so the same trigger changed shape
+ * three times on the way from picking it to seeing it. The replay panel's ternary
+ * had no `event` branch at all, so an event-triggered run drew the manual play
+ * button — wrong information, not a mismatch (PO-329).
+ *
+ * One map instead, and the reason it can be Solar's: `TRIGGER_TEMPLATES` is
+ * this repository's own catalogue, not a node manifest, so its `icon` strings
+ * ('Play', 'Clock', 'Webhook', 'Zap') were Lucide names by habit rather than by
+ * contract. The node-type icon map (`nodeIcons.ts`) is a different thing and
+ * stays Lucide deliberately — see `docs/icons.md`.
+ */
+export declare const TRIGGER_GLYPHS: Record<TriggerType, Component>;
+/**
+ * The glyph for a trigger type.
+ *
+ * The parameter is deliberately wider than `TriggerType`: some callers read the
+ * type out of a template blob or a run record, where the service may name a kind
+ * the studio has no word for yet — `templates/[slug].vue` is built for exactly
+ * that case and says so.
+ *
+ * Such a kind falls back to the **bolt**, not to the manual play button, which is
+ * what the templates surfaces did before this map existed. A play button asserts
+ * "you start this yourself", and for an unknown kind that is a claim rather than a
+ * gap; the bolt says only that something fires it.
+ *
+ * `Object.hasOwn`, not `?? Bolt` on its own: a plain object inherits
+ * `Object.prototype`, so a service that named a trigger kind `constructor` or
+ * `toString` would resolve to a function, the `??` would never fire, and the card
+ * would try to render `<component :is="Object">`. The `Lucide[name]` lookups this
+ * map replaced could not do that — a module namespace object has a null prototype
+ * — so the guard is what keeps the docstring above true rather than nearly true.
+ */
+export declare function triggerGlyph(type?: string | null): Component;

package/dist/runtime/data/triggerGlyphs.js

@@ -0,0 +1,11 @@
+import { Bolt, ClockCircle, LinkRound, Play } from "#solar-icons";
+export const TRIGGER_GLYPHS = {
+  manual: Play,
+  schedule: ClockCircle,
+  webhook: LinkRound,
+  event: Bolt
+};
+export function triggerGlyph(type) {
+  const key = String(type);
+  return Object.hasOwn(TRIGGER_GLYPHS, key) ? TRIGGER_GLYPHS[key] : Bolt;
+}