@uipath/maestro-builder-sdk 6.18.10 → 6.20.0

package/dist/flow-definitions.d.ts

@@ -0,0 +1,10 @@
+/**
+ * The bundled definitions, keyed `<nodeType>@<version>`. Deep-frozen: every reader
+ * shares this one copy, so a write meant for one node must clone first, and one
+ * that does not throws at its own site instead of leaking into another reader.
+ */
+export declare const BUNDLED_DEFINITIONS: Readonly<Record<string, any>>;
+/** Whether the SDK bundles `<typeName>@<version>`. */
+export declare function hasBundledDefinition(typeName: string, version: string): boolean;
+/** The versions of `typeName` the SDK bundles, in bundle order. */
+export declare function bundledVersions(typeName: string): string[];

package/dist/flow-definitions.js

@@ -0,0 +1,35 @@
+/**
+ * The node definitions this SDK bundles for Flow (`core-definitions.json`, keyed
+ * `<nodeType>@<version>`): the one parse of the bundle, shared by `serialize`,
+ * `decompile` and the node-type registry's validation.
+ *
+ * Kept apart from `serialize.ts` so the registry can depend on the bundle without
+ * importing the serializer that depends on the registry.
+ */
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+/**
+ * The bundled definitions, keyed `<nodeType>@<version>`. Deep-frozen: every reader
+ * shares this one copy, so a write meant for one node must clone first, and one
+ * that does not throws at its own site instead of leaking into another reader.
+ */
+export const BUNDLED_DEFINITIONS = deepFreeze(JSON.parse(readFileSync(join(dirname(fileURLToPath(import.meta.url)), 'core-definitions.json'), 'utf8')));
+function deepFreeze(value) {
+    if (value !== null && typeof value === 'object' && !Object.isFrozen(value)) {
+        Object.freeze(value);
+        for (const child of Object.values(value))
+            deepFreeze(child);
+    }
+    return value;
+}
+const BUNDLED_KEYS = new Set(Object.keys(BUNDLED_DEFINITIONS));
+/** Whether the SDK bundles `<typeName>@<version>`. */
+export function hasBundledDefinition(typeName, version) {
+    return BUNDLED_KEYS.has(`${typeName}@${version}`);
+}
+/** The versions of `typeName` the SDK bundles, in bundle order. */
+export function bundledVersions(typeName) {
+    const prefix = `${typeName}@`;
+    return [...BUNDLED_KEYS].filter((k) => k.startsWith(prefix)).map((k) => k.slice(prefix.length));
+}

package/dist/flow-expr-check.js

@@ -75,7 +75,7 @@ function addStepNames(steps, roots) {
     for (const s of steps) {
         // `return` carries a synthetic name; the port-edge kinds carry none at all —
         // they are edges, not nodes, so there is nothing to reference them by.
-        if (s.kind !== 'return' && s.kind !== 'stepToRef' && s.kind !== 'stepToList' && s.kind !== 'break')
+        if (s.kind !== 'return' && s.kind !== 'stepToRef' && s.kind !== 'stepToList' && s.kind !== 'break' && s.kind !== 'continue')
             roots.add(s.name);
         switch (s.kind) {
             case 'stepToList':

package/dist/flow-node-registry.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Flow's node-type registry: every Flow node family, listed explicitly
+ * (docs/NODE_TYPE_ARCHITECTURE_DESIGN.md §4.5).
+ *
+ * While a kind is not listed here, `serialize`, `check` and `decompile` handle it
+ * with their existing branches — the FB014 pins in `tests/lint/pins.txt` are what
+ * is left to port.
+ */
+import { NodeTypeRegistry } from './core/nodes/registry.js';
+import type { FlowContexts, FlowNodeFamily } from './flow-node-type.js';
+/** The families, in no significant order. Adding one is the whole of registering it. */
+export declare const FLOW_NODE_FAMILIES: readonly FlowNodeFamily[];
+export declare const FLOW_NODE_TYPES: NodeTypeRegistry<FlowContexts>;

package/dist/flow-node-registry.js

@@ -0,0 +1,19 @@
+/**
+ * Flow's node-type registry: every Flow node family, listed explicitly
+ * (docs/NODE_TYPE_ARCHITECTURE_DESIGN.md §4.5).
+ *
+ * While a kind is not listed here, `serialize`, `check` and `decompile` handle it
+ * with their existing branches — the FB014 pins in `tests/lint/pins.txt` are what
+ * is left to port.
+ */
+import { NodeTypeRegistry } from './core/nodes/registry.js';
+import { hasBundledDefinition } from './flow-definitions.js';
+import { dataFabricFlowFamily } from './nodes/data-fabric/flow/family.js';
+import { delayFlowFamily } from './nodes/delay/flow/family.js';
+import { documentFlowFamily } from './nodes/document/flow/family.js';
+import { mockFlowFamily } from './nodes/mock/flow/family.js';
+import { scriptFlowFamily } from './nodes/script/flow/family.js';
+import { transformFlowFamily } from './nodes/transform/flow/family.js';
+/** The families, in no significant order. Adding one is the whole of registering it. */
+export const FLOW_NODE_FAMILIES = [dataFabricFlowFamily, delayFlowFamily, documentFlowFamily, mockFlowFamily, scriptFlowFamily, transformFlowFamily];
+export const FLOW_NODE_TYPES = new NodeTypeRegistry('flow', FLOW_NODE_FAMILIES, { hasBundledDefinition });

package/dist/flow-node-type.d.ts

@@ -0,0 +1,192 @@
+/**
+ * The Flow specialization of the node-type contract (`core/nodes/`), and the
+ * contexts Flow lends a node type for each job. docs/NODE_TYPE_ARCHITECTURE_DESIGN.md
+ * §4.1–§4.3.
+ *
+ * A Flow node type serializes to a {@link FlowNodeContribution} — the same contract
+ * a custom `FlowAction.contribute()` returns, plus the two things built-in node
+ * types need and custom ones never had (`model`, `port`). The serializer still
+ * owns the node's id, label, `typeVersion`, layout, edges and definition dedupe;
+ * each context below is the whole of what a node type can see.
+ */
+import type { ArtifactContexts, NodeType } from './core/nodes/node-type.js';
+import type { VersionedNodeType } from './core/nodes/versioned.js';
+import type { NodeFamily, Placement } from './core/nodes/family.js';
+import type { DefinitionReference, NodeContribution } from './core/node-classes.js';
+import type { CheckOpts } from './check.js';
+/**
+ * What a Flow node type's `serialize` returns: the node's type-owned fields.
+ *
+ * The `inputs`, `outputs` and `bindings` are a {@link NodeContribution}'s; only
+ * `definition` differs (optional here), and `model` and `port` are Flow's own.
+ *
+ * A node type owns its bindings: together with what it hoists through
+ * `ctx.bind`, they must close every `<bindings.NAME>` its definition references.
+ * `serialize` enforces that (#942); `check` does not verify it, because the
+ * bindings exist only once the type serializes and no author input can open the
+ * gap, so the type's own tests are what pin it.
+ */
+export interface FlowNodeContribution extends Omit<NodeContribution, 'definition'> {
+    /**
+     * The definition to compile against. A `bundled` type must omit it: the
+     * serializer resolves `<typeName>@<version>` from the bundle, and refuses one
+     * returned. A `per-tenant` type must supply the definition it built (a
+     * `snapshot` reference).
+     */
+    definition?: DefinitionReference;
+    /**
+     * Whether the node carries the definition's `model` (`'definition'`, the default)
+     * or none (`'omit'`) — Data Fabric nodes never carry one (see `makeNode`).
+     */
+    model?: 'definition' | 'omit';
+    /** The forward port the next step's edge leaves from. Default: the definition's default source handle. */
+    port?: string;
+}
+/** What `serialize` may ask of the serializer, for one placement. */
+export interface FlowSerializeContext {
+    /** The step name the author gave this node. */
+    readonly step: string;
+    /**
+     * The version being emitted, always set: the author's `{ version }` when the step
+     * names one, else what `select()` or the default chose. It does not say whether
+     * the author pinned it.
+     */
+    readonly version: string;
+    /** Render one value (an `Expr`, or a literal) as the file stores it, with this scope's rename map. */
+    render(value: unknown): unknown;
+    /**
+     * Apply this scope's rename map to raw JavaScript that is not an `Expr` — a
+     * script body reads `$vars.<step>` like any expression, so a reused child's
+     * body must follow its copy's node ids too.
+     */
+    renameRefs(js: string): string;
+    /** The node id another step of this scope was emitted under — rename-aware, for subflow copies. */
+    stepNodeId(step: string): string;
+    /** A deterministic id for `seed`, unique to this flow and node. */
+    mint(seed: string): string;
+    /**
+     * Hoist a binding entry into the flow's `bindings`, deduplicated by `id`. With
+     * the contribution's own `bindings`, these must close every `<bindings.NAME>`
+     * the node's definition references: serialize refuses a name left open
+     * (`CONTRIBUTION_BINDING_UNRESOLVED`), and `check` does not see bindings.
+     */
+    bind(entry: {
+        readonly id: string;
+    } & Readonly<Record<string, unknown>>): void;
+    /** The bundled definition `<typeName>@<version>`, or undefined when the SDK does not ship it. */
+    definition(typeName: string, version: string): unknown;
+}
+/** What `deserialize` may ask of the decompiler, for one serialized node. */
+export interface FlowDeserializeContext {
+    /** The serialized node's id. */
+    readonly nodeId: string;
+    /** A serialized value back as the spec holds it: `=js:` text becomes an `Expr`; a literal stays itself. */
+    expr(raw: unknown): unknown;
+    /**
+     * A serialized value's TEXT, unwrapped from an expression envelope: a string
+     * as is, a `{ type: 'jsExpression', expression }` envelope as `=js:<expression>`,
+     * any other envelope as its expression; undefined for anything else.
+     */
+    sourceText(raw: unknown): string | undefined;
+    /** A plain value, unwrapped from a `{ type: 'literal', expression: '<json>' }` envelope when it is one. */
+    plainValue(raw: unknown): unknown;
+    /** The step name a node id was emitted for. */
+    stepName(nodeId: string): string;
+    /** The file's own `definitions[]` entry for this node, if it carries one. */
+    definition(): unknown;
+    /** Report something the lift could not keep. Decompile prints it once. */
+    warn(message: string): void;
+}
+/** What `print` may ask of the decompiler. Every method returns source text. */
+export interface FlowPrintContext {
+    /**
+     * Any spec value as source: an `Expr` as the helper an author writes (`input('x')`, `js\`…\``), an array or
+     * plain object recursively (`[a, b]`, `{ k: v }`), anything else as a literal.
+     */
+    value(value: unknown): string;
+    /** A string literal. */
+    string(text: string): string;
+    /** Any JSON value as a literal, verbatim (`{"a":1}`), where the source writes the value as data. */
+    json(value: unknown): string;
+    /** An object key: a bare identifier when legal, otherwise a quoted string. */
+    key(name: string): string;
+    /** An authoring helper (`lit`, `input`, …) by name: imported into the printed source, and its identifier. */
+    helper(name: string): string;
+}
+/** What a node-local `check` may ask of the checker. */
+export interface FlowCheckContext {
+    /** The step being checked. */
+    readonly step: string;
+    /** The version the node will be emitted at. */
+    readonly version: string;
+    /** Report a diagnostic on this step. Its severity is the family catalog's for `code`. */
+    report(code: string, message: string, suggestion?: string): void;
+    /**
+     * The flow input or variable a bare reference (`$vars.x`, or an input's
+     * `$vars.<trigger>.output.x`) names, with its declared type when it has one;
+     * undefined for anything else — a step output's type is not known offline.
+     */
+    declaredRef(js: string): {
+        name: string;
+        type: string | undefined;
+    } | undefined;
+    /** The options `check` was called with (the connector-library views among them). */
+    readonly options: CheckOpts;
+}
+/** What a family-level `check` may ask of the checker. */
+export interface FlowFamilyCheckContext {
+    /** Report a diagnostic on `step`. Its severity is the family catalog's for `code`. */
+    report(step: string, code: string, message: string, suggestion?: string): void;
+    /** Whether the flow has a step of that name, in any scope the family's placements can see. */
+    hasStep(step: string): boolean;
+    /** Where a step of that name is placed, when it is one of this registry's node types. */
+    placementOf(step: string): Placement | undefined;
+    /**
+     * Whether that step is one of this registry's node types whose `{ version }` did
+     * not resolve. It has no placement, and `NODE_VERSION_UNREGISTERED` already
+     * reports it, so a rule about it should stay silent rather than say it is missing.
+     */
+    versionUnresolved(step: string): boolean;
+}
+export interface FlowContexts extends ArtifactContexts {
+    serialize: FlowSerializeContext;
+    deserialize: FlowDeserializeContext;
+    print: FlowPrintContext;
+    check: FlowCheckContext;
+    familyCheck: FlowFamilyCheckContext;
+}
+/**
+ * What `rawNode` reports for a raw node of a registered type: the typed spelling
+ * to prefer (RAW_NODE_TYPED_FAMILY), and the inputs the product never reads
+ * (RAW_NODE_UNKNOWN_INPUT). Both apply to every version, registered or not —
+ * a raw node is often how an author reaches a version the SDK does not bundle.
+ */
+export interface FlowRawNodeAdvice {
+    /** The typed spelling the warning names, e.g. `dataFabricRead({ entity, … })`. */
+    readonly factory: string;
+    /** Appended to the warning: what the factory writes, and what still needs a raw node. */
+    readonly hint?: string;
+    /**
+     * A raw node's inputs carry a key the product never reads: an `error` at a version
+     * the SDK bundles (`bundled`), where the key set is known, else a `warning`.
+     */
+    inputProblem?(inputs: unknown, version: string, bundled: boolean): {
+        severity: 'error' | 'warning';
+        message: string;
+    } | undefined;
+}
+/** One Flow node type at one version. */
+export interface FlowNodeType<Spec> extends NodeType<Spec, FlowNodeContribution, FlowContexts> {
+    /**
+     * The node-level `model` every node of this type carries, whichever path emits
+     * it — this type's `serialize`, or a `rawNode` of its definition. `'omit'`: none
+     * (Data Fabric). Default `'definition'`; a contribution's own `model` wins.
+     */
+    readonly nodeModel?: 'definition' | 'omit';
+    /** What `rawNode` reports for a raw node of this type. */
+    readonly rawNode?: FlowRawNodeAdvice;
+}
+/** A Flow node type with several versions. */
+export type FlowVersionedNodeType<Spec> = VersionedNodeType<Spec, FlowNodeContribution, FlowContexts, FlowNodeType<Spec>>;
+/** A Flow node family. */
+export type FlowNodeFamily = NodeFamily<FlowContexts>;

package/dist/flow-node-type.js

@@ -0,0 +1 @@
+export {};

package/dist/flow-sdk.d.ts

@@ -18,11 +18,18 @@
  */
 export * from './core/expr.js';
 export * from './core/actions.js';
+export * from './nodes/data-fabric/flow/index.js';
+export * from './nodes/delay/flow/index.js';
+export * from './nodes/document/flow/index.js';
+export * from './nodes/mock/flow/index.js';
+export * from './nodes/script/flow/index.js';
+export * from './nodes/transform/flow/index.js';
 export { resolveFlowRefs, resolveRefPath, hasFileRefs } from './ref-resolve.js';
 export type { RefReader, ResolveRefsOptions } from './ref-resolve.js';
 export * from './core/connectors.js';
 export * from './core/lookups.js';
 export * from './core/node-classes.js';
+export * from './raw-node.js';
 import { Expr } from './core/expr.js';
 import type { ErrorEnvelopeField, TypeDesc } from './core/expr.js';
 import type { ActionSpec, EventSubscription, TriggerOptions } from './core/actions.js';
@@ -330,6 +337,13 @@ export type CaseValue = string | number | boolean;
 export interface SwitchArm {
     value: CaseValue;
     label?: string;
+    /**
+     * The case's wire id — `inputs.cases[].id`, and the `case-<id>` port its arm
+     * leaves from. Omitted, it is positional (`case_1`, `case_2`, …). Set it only
+     * to keep an id a flow already has (decompile does, for a designer-drawn
+     * switch whose ids are `default-1`, …).
+     */
+    id?: string;
     body: Step[];
 }
 /**
@@ -513,6 +527,14 @@ export type Step = {
  | {
     kind: 'break';
 }
+/**
+ * Go on to the enclosing loop/do-while's next iteration through its continue
+ * handle — the edge a body's last step gets. Terminal on its path. Only valid
+ * inside a container body.
+ */
+ | {
+    kind: 'continue';
+}
 /**
  * A fan-out and its join. `arms` is one step list per arm — an ARRAY, because
  * arms are positional and carry no author-supplied keys — and `name` names the
@@ -951,7 +973,8 @@ declare class StepList {
      * @param name - The switch node's id.
      * @param on - The value to compare each case against.
      * @param cases - One entry per arm, evaluated top to bottom; the first strict
-     * match wins. `label` names the arm's outgoing edge.
+     * match wins. `label` names the arm's outgoing edge. `id` keeps a case's wire
+     * id (`inputs.cases[].id`, port `case-<id>`); omitted, it is `case_<n>`.
      * @param defaultFn - Receives a sub-builder for the arm taken when nothing
      * matches. Omit it and an unmatched value simply continues.
      * @param options - Node options; `version` selects the exact definition
@@ -962,6 +985,7 @@ declare class StepList {
         value: CaseValue;
         body: (b: ArmBuilder) => void;
         label?: string;
+        id?: string;
     }[], defaultFn?: (b: StepList) => void, options?: NodeOptions): this;
     /**
      * Run two or more arms **in parallel** from this point and join them back
@@ -1046,6 +1070,21 @@ declare class StepList {
      * @returns This builder. Nothing after this call on the same path can run.
      */
     break(): this;
+    /**
+     * Go on to the **next iteration** of the enclosing `.loop()` / `.doWhile()`
+     * through its continue handle — the edge the body's last step gets anyway.
+     * Use it where a path would otherwise end the run: an `.onError()` handler or
+     * an HTTP-branch / outcome list inside the body ends on an End node of its own
+     * unless it says where to go, so "log the failure and skip this item" is
+     * `.onError((h) => h.step('log', …).continue())`. Terminal on its path, like
+     * `.break()`. Compilation fails when there is no enclosing container.
+     *
+     * Not `.stepToRef('<loop>')`: that names the loop as a step and enters it from
+     * its outer input — it restarts the loop, it does not go on to the next item.
+     *
+     * @returns This builder. Nothing after this call on the same path can run.
+     */
+    continue(): this;
     /**
      * Stop the **whole run**, here and now — not just this path.
      *

package/dist/flow-sdk.js

@@ -21,12 +21,20 @@
 // single import an author needs.
 export * from './core/expr.js';
 export * from './core/actions.js';
+// Node families' public surfaces (docs/NODE_TYPE_ARCHITECTURE_DESIGN.md §8).
+export * from './nodes/data-fabric/flow/index.js';
+export * from './nodes/delay/flow/index.js';
+export * from './nodes/document/flow/index.js';
+export * from './nodes/mock/flow/index.js';
+export * from './nodes/script/flow/index.js';
+export * from './nodes/transform/flow/index.js';
 // `$ref`-split ingestion (design §5): decompile resolves local-file refs into
 // one object model. Exported so a host doing its own file reading can too.
 export { resolveFlowRefs, resolveRefPath, hasFileRefs } from './ref-resolve.js';
 export * from './core/connectors.js';
 export * from './core/lookups.js';
 export * from './core/node-classes.js';
+export * from './raw-node.js';
 import { err as errRef, toExpr, types } from './core/expr.js';
 import { builtinActionSpec, builtinTriggerSpec, subscriptionFrom } from './core/actions.js';
 import { checkFlowExpressions, FlowBuildError } from './flow-expr-check.js';
@@ -609,7 +617,8 @@ class StepList {
      * @param name - The switch node's id.
      * @param on - The value to compare each case against.
      * @param cases - One entry per arm, evaluated top to bottom; the first strict
-     * match wins. `label` names the arm's outgoing edge.
+     * match wins. `label` names the arm's outgoing edge. `id` keeps a case's wire
+     * id (`inputs.cases[].id`, port `case-<id>`); omitted, it is `case_<n>`.
      * @param defaultFn - Receives a sub-builder for the arm taken when nothing
      * matches. Omit it and an unmatched value simply continues.
      * @param options - Node options; `version` selects the exact definition
@@ -627,7 +636,7 @@ class StepList {
             // An arm's own `.label(...)` wins over the case config's `label`; either
             // overrides the serializer's derived `Case "<value>"`.
             const label = arm.armLabel ?? c.label;
-            return { value: c.value, ...(label !== undefined ? { label } : {}), body: arm.steps };
+            return { value: c.value, ...(label !== undefined ? { label } : {}), ...(c.id !== undefined ? { id: c.id } : {}), body: arm.steps };
         });
         let dflt;
         if (defaultFn) {
@@ -757,6 +766,24 @@ class StepList {
         this.steps.push({ kind: 'break' });
         return this;
     }
+    /**
+     * Go on to the **next iteration** of the enclosing `.loop()` / `.doWhile()`
+     * through its continue handle — the edge the body's last step gets anyway.
+     * Use it where a path would otherwise end the run: an `.onError()` handler or
+     * an HTTP-branch / outcome list inside the body ends on an End node of its own
+     * unless it says where to go, so "log the failure and skip this item" is
+     * `.onError((h) => h.step('log', …).continue())`. Terminal on its path, like
+     * `.break()`. Compilation fails when there is no enclosing container.
+     *
+     * Not `.stepToRef('<loop>')`: that names the loop as a step and enters it from
+     * its outer input — it restarts the loop, it does not go on to the next item.
+     *
+     * @returns This builder. Nothing after this call on the same path can run.
+     */
+    continue() {
+        this.steps.push({ kind: 'continue' });
+        return this;
+    }
     /**
      * Stop the **whole run**, here and now — not just this path.
      *

package/dist/flow-step-tree.js

@@ -9,7 +9,7 @@ export function stopsAtEnd(steps) {
         || (st.kind === 'branch' && (has(st.then, kinds) || has(st.otherwise, kinds)))
         || ((st.kind === 'switch' || st.kind === 'stepSwitch') && st.cases.some((c) => has(c.body, kinds)))
         || (st.kind === 'switch' && st.default !== undefined && has(st.default, kinds)));
-    return has(steps, new Set(['return'])) && !has(steps, new Set(['terminate', 'break']));
+    return has(steps, new Set(['return'])) && !has(steps, new Set(['terminate', 'break', 'continue']));
 }
 /**
  * The step lists nested DIRECTLY inside `step` — the bodies a walk over this
@@ -37,6 +37,7 @@ export function childStepLists(step) {
             return step.arms;
         case 'action':
         case 'break':
+        case 'continue':
         case 'terminate':
         case 'stepToRef':
         case 'return':

package/dist/index.d.ts

@@ -14,7 +14,8 @@ export type { EmitFlowOpts } from './emit.js';
 export { decompile as decompileFlow } from './decompile.js';
 export type { DecompileOptions as FlowDecompileOptions } from './decompile.js';
 export { mergeFlow } from './merge.js';
-export type { MergeOptions as FlowMergeOptions } from './merge.js';
+export type { MergeOptions as FlowMergeOptions, MergeFinding as FlowMergeFinding } from './merge.js';
+export { MergeRefusedError as FlowMergeRefusedError } from './merge.js';
 export { Library } from './library.js';
 export { Bindings } from './bindings.js';
 export { check } from './check.js';

package/dist/index.js

@@ -18,6 +18,7 @@ export { serialize } from './serialize.js';
 export { emitFlow } from './emit.js';
 export { decompile as decompileFlow } from './decompile.js';
 export { mergeFlow } from './merge.js';
+export { MergeRefusedError as FlowMergeRefusedError } from './merge.js';
 export { Library } from './library.js';
 export { Bindings } from './bindings.js';
 export { check } from './check.js';

package/dist/merge-cli.js

@@ -3,23 +3,25 @@
  * merge-cli — merge an edited flow back into the original `.flow` (bin `flow-merge`)
  *
  * Usage:
- *   flow-merge <original.flow> <edited.flow> [-o merged.flow] [--baseline <baseline.flow>]
+ *   flow-merge <original.flow> <edited.flow> [-o merged.flow] [--baseline <baseline.flow>] [--strict]
  *
  * `edited.flow` is compile(decompile(original) after your edits). `--baseline`
  * is compile(decompile(original)) BEFORE any edit — supplying it enables the
  * delta merge (untouched nodes keep their original content, placeholder-safe);
  * omit it for a two-way merge (take the edited graph, re-attach original layout).
- * See merge.ts.
+ * With `--baseline`, every wire-identity difference between the baseline and
+ * the original (what the no-edit round trip changed) is printed as a warning;
+ * `--strict` refuses instead (exit 1, nothing written). See merge.ts.
  */
 import { reportResult } from './cli-result.js';
 import { writeJsonFile } from './core/json-file.js';
 import { readFileSync } from 'node:fs';
 import { basename, resolve } from 'node:path';
-import { mergeFlow } from './merge.js';
+import { MergeRefusedError, mergeFlow } from './merge.js';
 import { flagValue, runWhenInvokedDirectly } from './cli-run.js';
 export function run(argv) {
     if (argv.length === 0 || argv[0] === '-h' || argv[0] === '--help') {
-        console.error('usage: flow-merge <original.flow> <edited.flow> [-o merged.flow] [--baseline <baseline.flow>]');
+        console.error('usage: flow-merge <original.flow> <edited.flow> [-o merged.flow] [--baseline <baseline.flow>] [--strict]');
         return 2;
     }
     const flags = new Set(['-o', '--baseline']);
@@ -33,10 +35,25 @@ export function run(argv) {
     const edited = JSON.parse(readFileSync(editedPath, 'utf8'));
     const baselinePath = flagValue(argv, '--baseline');
     const baseline = baselinePath ? JSON.parse(readFileSync(baselinePath, 'utf8')) : undefined;
-    const merged = mergeFlow(original, edited, {
-        baseline,
-        warn: (m) => console.error(`flow-merge: warning: ${m}`),
-    });
+    const strict = argv.includes('--strict');
+    if (strict && !baseline) {
+        console.error('flow-merge: --strict compares the no-edit round trip with the original; pass --baseline <baseline.flow>');
+        return 2;
+    }
+    let merged;
+    try {
+        merged = mergeFlow(original, edited, {
+            baseline,
+            strict,
+            warn: (m) => console.error(`flow-merge: warning: ${m}`),
+        });
+    }
+    catch (error) {
+        if (!(error instanceof MergeRefusedError))
+            throw error;
+        console.error(`flow-merge: ${error.message}`);
+        return 1;
+    }
     const out = flagValue(argv, '-o') ?? 'merged.flow';
     writeJsonFile(out, merged);
     console.log(`flow-merge: wrote ${basename(out)} (${(merged.nodes ?? []).length} nodes, ${(merged.edges ?? []).length} edges)`);

package/dist/merge-roundtrip.d.ts

@@ -0,0 +1,81 @@
+/** A node as merge sees it: only the fields these checks read. */
+interface RtNode {
+    id: string;
+    type: string;
+    typeVersion?: string;
+    inputs?: Record<string, unknown>;
+    [k: string]: unknown;
+}
+/** An edge as merge sees it. */
+interface RtEdge {
+    id?: string;
+    sourceNodeId: string;
+    sourcePort: string;
+    targetNodeId: string;
+    targetPort: string;
+    [k: string]: unknown;
+}
+/** A `.flow` file as merge sees it. */
+interface RtFlow {
+    nodes?: RtNode[];
+    edges?: RtEdge[];
+    definitions?: Array<{
+        nodeType?: string;
+        [k: string]: unknown;
+    }>;
+    subflows?: Record<string, unknown>;
+    bindings?: Array<{
+        id?: string;
+        [k: string]: unknown;
+    }>;
+    [k: string]: unknown;
+}
+/** One difference, or one inconsistency in the merged file. */
+export interface MergeFinding {
+    /** Which comparison found it. */
+    kind: 'node-removed' | 'node-added' | 'node-type' | 'implicit-end' | 'edge-handle-renamed' | 'edge-rewired' | 'edge-removed' | 'edge-added' | 'handle-ids' | 'binding-removed' | 'binding-added' | 'undeclared-handle' | 'duplicate-binding';
+    /** The finding, phrased for the author, naming the node, edge or row. */
+    message: string;
+    /**
+     * Whether `strict` refuses the merge over it. False for `implicit-end` and
+     * `binding-removed`, which leave the merged file doing what the original does.
+     */
+    refuses: boolean;
+}
+/**
+ * Every wire-identity difference between the original and its no-edit round
+ * trip that the merged file still carries, phrased as what the merge writes.
+ *
+ * A difference the author's edit undid is not reported: an edge the round trip
+ * dropped that the merged file has again, an edge or node the round trip added
+ * that the merged file lacks, a node whose type or handles the round trip
+ * changed that the merged file no longer has (or has with the original's).
+ *
+ * @param original - The file being merged into.
+ * @param baseline - compile(decompile(original)) before any edit.
+ * @param merged - The merged file, before it is written.
+ * @returns One finding per difference, in a stable order.
+ */
+export declare function roundTripFindings(original: RtFlow, baseline: RtFlow, merged: RtFlow): MergeFinding[];
+/**
+ * Inconsistencies in the merged file that come from mixing its sources: a root
+ * edge leaving a handle its source node does not declare, and two binding rows
+ * binding the same resource property.
+ *
+ * A node with no definition in `merged.definitions` (a sticky note, a type
+ * neither input carried) is not judged. Neither is anything the original
+ * already had — an edge it carries verbatim, or as many same-identity binding
+ * rows as it already holds — because the merge did not cause it.
+ *
+ * @param merged - The merged file.
+ * @param original - The file merged into.
+ * @returns One finding per inconsistency.
+ */
+export declare function mergedFileFindings(merged: RtFlow, original?: RtFlow): MergeFinding[];
+/** Thrown by `mergeFlow` under `strict` when a finding refuses the merge. */
+export declare class MergeRefusedError extends Error {
+    /** Every refusing finding, in report order. */
+    readonly findings: readonly MergeFinding[];
+    constructor(findings: readonly MergeFinding[]);
+}
+export {};