@uipath/maestro-builder-sdk 6.51.3 → 6.52.0

package/dist/core/nodes/registry.js

@@ -6,19 +6,57 @@ function owns(p, typeName) {
 }
 export class NodeTypeRegistry {
     artifact;
-    families;
-    #byKind = new Map();
-    #byTypeName = new Map();
-    /** The types that own a family of names (`typeNamePrefix`); no two prefixes overlap. */
-    #byPrefix = [];
+    #builtIn;
+    #extensions = [];
+    #index;
+    #options;
     /**
      * @param artifact - The artifact's name, for messages (`'flow'`).
-     * @param families - Every family this artifact supports, in no significant order.
+     * @param families - Every built-in family this artifact supports, in no significant order.
      * @param options - What the artifact knows that the contract does not.
      */
     constructor(artifact, families, options) {
         this.artifact = artifact;
-        this.families = families;
+        this.#builtIn = families;
+        this.#options = options;
+        const { index, problems } = this.#build(families);
+        if (problems.length > 0) {
+            throw new Error(`internal SDK error: the ${artifact} node-type registry is inconsistent:\n`
+                + problems.map((p) => `  - ${p}`).join('\n'));
+        }
+        this.#index = index;
+    }
+    /** Every family the registry knows: the built-in ones, then the registered packages' in registration order. */
+    get families() {
+        return [...this.#builtIn, ...this.#extensions];
+    }
+    /**
+     * Register a node-type package's family (`@uipath/maestro-builder-sdk/extend`).
+     *
+     * The whole registry is re-indexed with the new family last, under the same
+     * rules construction applies, so a package cannot take a kind, a type name, a
+     * prefix or a diagnostic code a built-in family owns, nor one another package
+     * registered first. A refusal names the package and leaves the live index as
+     * it was. Registering the same family object twice is a no-op: an ESM module
+     * runs once per process, but a test may import a package through two paths.
+     */
+    register(family) {
+        if (this.#extensions.includes(family))
+            return;
+        if (family.package === undefined) {
+            throw new Error(`cannot register node family "${family.id}": a family registered at run time must name its package (NodeFamily.package).`);
+        }
+        const { index, problems } = this.#build([...this.#builtIn, ...this.#extensions, family]);
+        if (problems.length > 0) {
+            throw new Error(`cannot register node family "${family.id}" from ${family.package.name}:\n`
+                + problems.map((p) => `  - ${p}`).join('\n'));
+        }
+        this.#extensions = [...this.#extensions, family];
+        this.#index = index;
+    }
+    #build(families) {
+        const index = { byKind: new Map(), byTypeName: new Map(), byPrefix: [] };
+        const options = this.#options;
         const problems = [];
         const familyIds = new Set();
         const codeOwner = new Map();
@@ -36,7 +74,7 @@ export class NodeTypeRegistry {
             for (const listed of family.types) {
                 const type = asVersioned(listed);
                 const where = `${family.id}/${type.kind}`;
-                const sharing = this.#byKind.get(type.kind);
+                const sharing = index.byKind.get(type.kind);
                 if (sharing && (!type.matches || sharing.some((other) => !other.type.matches))) {
                     problems.push(`kind "${type.kind}" is registered twice (${[...sharing, { family, type }].map((e) => `${e.family.id}/${e.type.typeName}`).join(' and ')}); node types that share a kind must each declare matches(spec)`);
                 }
@@ -45,22 +83,22 @@ export class NodeTypeRegistry {
                     if (type.typeName !== `${prefix}*`) {
                         problems.push(`${where}: a type that owns the names under "${prefix}" is named "${prefix}*", not "${type.typeName}"`);
                     }
-                    const overlap = this.#byPrefix.find((p) => p.prefix.startsWith(prefix) || prefix.startsWith(p.prefix));
+                    const overlap = index.byPrefix.find((p) => p.prefix.startsWith(prefix) || prefix.startsWith(p.prefix));
                     if (overlap)
                         problems.push(`${where}: prefix "${prefix}" overlaps "${overlap.prefix}" (${placeOf(overlap.entry)})`);
-                    const shadowed = [...this.#byTypeName.keys()].find((n) => n.startsWith(prefix) && (type.typeNameMatches?.(n) ?? true));
+                    const shadowed = [...index.byTypeName.keys()].find((n) => n.startsWith(prefix) && (type.typeNameMatches?.(n) ?? true));
                     if (shadowed)
                         problems.push(`${where}: prefix "${prefix}" would also own the registered type "${shadowed}"`);
                 }
                 else {
-                    const owner = this.#byPrefix.find((p) => owns(p, type.typeName));
+                    const owner = index.byPrefix.find((p) => owns(p, type.typeName));
                     if (owner)
                         problems.push(`${where}: type name "${type.typeName}" falls under the prefix "${owner.prefix}" (${placeOf(owner.entry)})`);
                 }
                 if (type.typeNameMatches !== undefined && type.typeNamePrefix === undefined) {
                     problems.push(`${where}: typeNameMatches narrows a typeNamePrefix, and the type declares none`);
                 }
-                const typeOwner = this.#byTypeName.get(type.typeName);
+                const typeOwner = index.byTypeName.get(type.typeName);
                 if (typeOwner) {
                     problems.push(`type name "${type.typeName}" is registered twice (${placeOf(typeOwner)} and ${where}); one VersionedNodeType owns every version of a type`);
                 }
@@ -72,19 +110,24 @@ export class NodeTypeRegistry {
                 }
                 for (const [key, impl] of Object.entries(type.versions)) {
                     problems.push(...implementationProblems(where, key, impl, type, options));
+                    // A package's definition is the package's: the platform does not run it, so
+                    // a built-in family may not declare one, and a package family declares nothing else.
+                    if (impl.definition === 'package' && family.package === undefined) {
+                        problems.push(`${where}@${key}: is a package definition, so it must come from a node-type package (NodeFamily.package), not a built-in family`);
+                    }
+                    if (impl.definition !== 'package' && family.package !== undefined) {
+                        problems.push(`${where}@${key}: comes from package ${family.package.name}, so it must declare definition: 'package' (found '${impl.definition}')`);
+                    }
                 }
                 const entry = { family, type };
-                this.#byKind.set(type.kind, [...(sharing ?? []), entry]);
-                this.#byTypeName.set(type.typeName, entry);
+                index.byKind.set(type.kind, [...(sharing ?? []), entry]);
+                index.byTypeName.set(type.typeName, entry);
                 if (type.typeNamePrefix !== undefined) {
-                    this.#byPrefix.push({ prefix: type.typeNamePrefix, matches: type.typeNameMatches?.bind(type), entry });
+                    index.byPrefix.push({ prefix: type.typeNamePrefix, matches: type.typeNameMatches?.bind(type), entry });
                 }
             }
         }
-        if (problems.length > 0) {
-            throw new Error(`internal SDK error: the ${artifact} node-type registry is inconsistent:\n`
-                + problems.map((p) => `  - ${p}`).join('\n'));
-        }
+        return { index, problems };
     }
     /**
      * The node type for a spec, by its kind, or undefined when the kind is not
@@ -92,7 +135,7 @@ export class NodeTypeRegistry {
      * holds — undefined when none does; two matching is an SDK bug and throws.
      */
     byKind(kind, spec) {
-        const all = this.#byKind.get(kind);
+        const all = this.#index.byKind.get(kind);
         if (!all)
             return undefined;
         if (all.length === 1)
@@ -105,7 +148,7 @@ export class NodeTypeRegistry {
     }
     /** Every node type registered for a kind (several when they share it), in registration order. */
     typesOfKind(kind) {
-        return this.#byKind.get(kind) ?? [];
+        return this.#index.byKind.get(kind) ?? [];
     }
     /**
      * The node type for a type name in the file — the exact name, else the type
@@ -115,14 +158,14 @@ export class NodeTypeRegistry {
      * read it as its factory, so it still does.
      */
     byTypeName(typeName) {
-        const exact = this.#byTypeName.get(typeName);
+        const exact = this.#index.byTypeName.get(typeName);
         if (exact)
             return exact;
-        return this.#byPrefix.find((p) => owns(p, typeName))?.entry;
+        return this.#index.byPrefix.find((p) => owns(p, typeName))?.entry;
     }
     /** Every registered kind, sorted. */
     kinds() {
-        return [...this.#byKind.keys()].sort();
+        return [...this.#index.byKind.keys()].sort();
     }
 }
 /** Where a registered type lives, as the registry's messages name it: `<family>/<kind>`. */
@@ -154,7 +197,7 @@ function implementationProblems(where, key, impl, type, options) {
         }
     }
     else if (impl.errorPort === undefined) {
-        out.push(`${at}: is per-tenant, so it must declare errorPort — there is no definition to ask`);
+        out.push(`${at}: is ${impl.definition}, so it must declare errorPort — there is no bundled definition to ask`);
     }
     return out;
 }

package/dist/decompile-cli.d.ts

@@ -1,3 +1,3 @@
 #!/usr/bin/env node
 import { type CliExitCode } from './cli-run.js';
-export declare function run(argv: string[]): CliExitCode;
+export declare function run(argv: string[]): Promise<CliExitCode>;

package/dist/decompile-cli.js

@@ -23,9 +23,10 @@ import { basename, dirname, join, resolve } from 'node:path';
 import { defaultSourceOut, workDirBeside, writeSource } from './workdir.js';
 import { decompile } from './decompile.js';
 import { resolveFlowRefs } from './ref-resolve.js';
-import { flagValue, runWhenInvokedDirectly } from './cli-run.js';
+import { flagValue, flagValues, runWhenInvokedDirectly } from './cli-run.js';
 import { PACKAGE_NAME } from './package-name.js';
 import { commentText } from './core/comment-text.js';
+import { loadNodePackages } from './node-packages.js';
 import { pipelineFrontDoor } from './registry/uip/pipeline-front-door.js';
 /** Derive a PascalCase base name from the flow name/id for the default output file. */
 function baseName(flow) {
@@ -37,12 +38,12 @@ function baseName(flow) {
         .join('');
     return pascal || 'Flow';
 }
-export function run(argv) {
+export async function run(argv) {
     if (argv.length === 0 || argv[0] === '-h' || argv[0] === '--help') {
-        console.error('usage: flow-decompile <original.flow> [-o Name.flow.ts] [--import <specifier>] [--strict]');
+        console.error('usage: flow-decompile <original.flow> [-o Name.flow.ts] [--import <specifier>] [--package <name>]... [--strict]');
         return 2;
     }
-    const flags = new Set(['-o', '--import']);
+    const flags = new Set(['-o', '--import', '--package']);
     const pos = argv.find((a, i) => !flags.has(a) && !flags.has(argv[i - 1]) && !a.startsWith('--'));
     if (!pos) {
         console.error('flow-decompile: missing <original.flow>');
@@ -55,6 +56,15 @@ export function run(argv) {
         baseUri: pos,
         read: (path) => readFileSync(path, 'utf8'),
     });
+    // Node-type packages the file needs: loaded only when the project trusts them
+    // (package.json nodePackages, or --package), resolved from the .flow's own
+    // directory (node-packages.ts). An untrusted or missing package is a warning,
+    // and its nodes print as rawNode(...).
+    const packages = await loadNodePackages(pos, flow, flagValues(argv, '--package'));
+    for (const message of packages.warnings)
+        console.error(`flow-decompile: warning: ${message}`);
+    if (packages.loaded.length > 0)
+        reportResult({ packages: packages.loaded.map((p) => p.package) });
     const ts = decompile(flow, {
         importSpecifier: flagValue(argv, '--import') ?? PACKAGE_NAME,
         bestEffort: !argv.includes('--strict'),

package/dist/decompile.d.ts

@@ -152,5 +152,19 @@ export interface DecompileOptions {
      */
     readSidecar?: (relativePath: string) => string | undefined;
 }
+/**
+ * Tracks which identifiers the emitted source uses, per module, so each import
+ * is exact. A built-in factory lands in the SDK's import; a node-type package's
+ * factory (`FactoryCall.module`, the family's `package.name`) lands in that
+ * package's own import line, so the emitted source compiles against the same
+ * packages the original was written with (docs/EXTENSIBLE_NODE_TYPES_DESIGN.md §3.5).
+ */
+/**
+ * The SDK names the decompiler itself may import (its helpers), beside every
+ * built-in family's factory. A package factory with one of these names is
+ * aliased, whichever is requested first, so the SDK's own name is always bare.
+ * `decompile-imports.test.ts` checks this list against the `imp.use('…')` sites.
+ */
+export declare const SDK_HELPER_NAMES: readonly string[];
 export declare function decompile(flow: FlowFile, options?: DecompileOptions): string;
 export {};

package/dist/decompile.js

@@ -308,16 +308,76 @@ class Emit {
         return this.lines.join('\n');
     }
 }
-/** Tracks which SDK identifiers the emitted source uses, so the import is exact. */
+/**
+ * Tracks which identifiers the emitted source uses, per module, so each import
+ * is exact. A built-in factory lands in the SDK's import; a node-type package's
+ * factory (`FactoryCall.module`, the family's `package.name`) lands in that
+ * package's own import line, so the emitted source compiles against the same
+ * packages the original was written with (docs/EXTENSIBLE_NODE_TYPES_DESIGN.md §3.5).
+ */
+/**
+ * The SDK names the decompiler itself may import (its helpers), beside every
+ * built-in family's factory. A package factory with one of these names is
+ * aliased, whichever is requested first, so the SDK's own name is always bare.
+ * `decompile-imports.test.ts` checks this list against the `imp.use('…')` sites.
+ */
+export const SDK_HELPER_NAMES = [
+    'connector', 'conversationTrigger', 'err', 'flow', 'formTrigger', 'input', 'ixpExtract', 'js', 'lit', 'manual',
+    'mock', 'onEvent', 'out', 'ran', 'rawNode', 'scheduled', 'subflow', 'types', 'v', 'voiceTrigger', 'waitForEvent',
+];
+/** `@acme/flow-nodes` → `acme_flow_nodes`: the alias suffix for a package's colliding factory. */
+function moduleSlug(module) {
+    return module.replace(/^@/, '').replace(/[^A-Za-z0-9]+/g, '_').replace(/^_+|_+$/g, '');
+}
 class Imports {
-    used = new Set(['flow']);
-    use(name) {
-        this.used.add(name);
-        return name;
+    /** `undefined` is the SDK itself; the specifier is only known when the lines are printed. */
+    used = new Map([[undefined, new Map([['flow', 'flow']])]]);
+    /** Every local identifier handed out, so no two modules bind the same name. */
+    locals = new Set(['flow']);
+    /** Names a package may not take bare: the SDK's helpers and every built-in factory. */
+    reserved;
+    constructor() {
+        this.reserved = new Set([
+            ...SDK_HELPER_NAMES,
+            ...FLOW_NODE_TYPES.families.filter((f) => f.package === undefined).flatMap((f) => f.types.map((t) => t.factory)),
+        ]);
+    }
+    /**
+     * The local identifier to print for `name` imported from `module` (`undefined`
+     * for the SDK). An SDK name is always its own; a package factory keeps its name
+     * unless the SDK owns it or another module already binds it, and is then
+     * imported `as <name>_<package slug>` — deterministic, so the emitted source is
+     * stable and `import { post as post_acme_flow_nodes }` reads as what it is.
+     */
+    use(name, module) {
+        let names = this.used.get(module);
+        if (names === undefined) {
+            names = new Map();
+            this.used.set(module, names);
+        }
+        const existing = names.get(name);
+        if (existing !== undefined)
+            return existing;
+        let local = name;
+        if (module !== undefined && (this.reserved.has(name) || this.locals.has(name))) {
+            local = `${name}_${moduleSlug(module)}`;
+            for (let n = 2; this.locals.has(local); n++)
+                local = `${name}_${moduleSlug(module)}_${n}`;
+        }
+        names.set(name, local);
+        this.locals.add(local);
+        return local;
     }
+    /** One import per module: the SDK first, then the packages by name. */
     line(specifier) {
-        const names = [...this.used].sort();
-        return `import { ${names.join(', ')} } from ${tsLiteral(specifier)};`;
+        const lines = [];
+        for (const [module, names] of [...this.used].sort(([a], [b]) => (a === undefined ? -1 : b === undefined ? 1 : a.localeCompare(b)))) {
+            if (names.size === 0)
+                continue;
+            const bindings = [...names].sort(([a], [b]) => a.localeCompare(b)).map(([name, local]) => (local === name ? name : `${name} as ${local}`));
+            lines.push(`import { ${bindings.join(', ')} } from ${tsLiteral(module ?? specifier)};`);
+        }
+        return lines.join('\n');
     }
 }
 // ─── Expression inversion ─────────────────────────────────────────────────────
@@ -774,7 +834,9 @@ function emitRegisteredSpec(node, imp, inputNames, graph) {
     };
     const options = opts((call.options ?? []).map(([k, v]) => [k, v]));
     const args = [...(call.positional ?? []), ...(options ? [options] : [])];
-    return `${imp.use(call.factory)}(${args.join(', ')})`
+    // A package type's factory is imported from its package, not from the SDK.
+    const origin = FLOW_NODE_TYPES.byTypeName(node.type)?.family.package;
+    return `${imp.use(call.factory, call.module ?? origin?.name)}(${args.join(', ')})`
         + (call.comment !== undefined ? ` /* ${commentText(call.comment)} */` : '');
 }
 /**
@@ -937,12 +999,18 @@ function unsupportedSpec(node, imp, o) {
         }
         const inputs = node.inputs ?? {};
         const inputsSrc = Object.keys(inputs).length > 0 ? JSON.stringify(inputs, null, 2) : undefined;
+        // A definition a node-type package wrote names the package; the node prints
+        // as rawNode because the project does not trust (or has not installed) it.
+        const origin = def.source?.package;
+        const hint = typeof origin === 'string'
+            ? ` /* from node-type package ${commentText(origin)}: load it with --package or package.json nodePackages to get its factory */`
+            : '';
         return `${imp.use('rawNode')}(${opts([
             ['nodeType', tsLiteral(node.type)],
             ['version', tsText(node.typeVersion)],
             ['manifest', constName],
             ['inputs', inputsSrc],
-        ])})`;
+        ])})${hint}`;
     }
     if (o.bestEffort === false) {
         throw new Error(`decompile: unsupported node type "${node.type}" (node "${node.id}") and the file carries no `

package/dist/extend.d.ts

@@ -0,0 +1,81 @@
+/**
+ * The extension surface of the Flow SDK: what a NODE-TYPE PACKAGE imports.
+ *
+ * A node-type package carries a family of node types the SDK does not ship —
+ * the Local family (`@uipath/flow-local-nodes`) is the first — and makes them
+ * available to a `.flow.ts` through a normal import:
+ *
+ * ```ts
+ * import { flow, manual } from '@uipath/maestro-builder-sdk';
+ * import { runCommand } from '@uipath/flow-local-nodes';
+ * ```
+ *
+ * The package registers its family as a side effect of being imported
+ * (`defineFlowNodeFamily`), so `compile`, `check` and `merge` need no
+ * configuration: `loadBuiltFlow` imports the author's module, the module imports
+ * the package, the package registers, and `build()` runs against a registry that
+ * knows the new kinds. Every type of a package family declares
+ * `definition: 'package'`, and the registry refuses a package type anywhere else —
+ * that is the rule that keeps the public SDK free of node types the UiPath
+ * platform cannot run.
+ *
+ * Everything else in `core/` is private. A package needs only what is exported
+ * here; see docs/EXTENSIBLE_NODE_TYPES_DESIGN.md.
+ */
+import type { NodeFamily, DiagnosticCatalog, PackageOrigin } from './core/nodes/family.js';
+import type { FlowAction } from './core/node-classes.js';
+import type { FlowContexts, FlowNodeFamily } from './flow-node-type.js';
+export type { NodeType, FactoryCall, OutputContract, ExprSite, DefinitionSource, ArtifactContexts, FieldsRead, OutputRead, OutputPathRead, } from './core/nodes/node-type.js';
+export type { VersionedNodeType } from './core/nodes/versioned.js';
+export type { NodeFamily, Placement, DiagnosticCatalog, PackageOrigin } from './core/nodes/family.js';
+export type { DefinitionReference } from './core/node-classes.js';
+export type { FlowContexts, FlowNodeType, FlowVersionedNodeType, FlowNodeFamily, FlowSerializeContext, FlowDeserializeContext, FlowPrintContext, FlowCheckContext, FlowFamilyCheckContext, FlowNodeContribution, FlowRawNodeAdvice, } from './flow-node-type.js';
+export type { FlowAction } from './core/node-classes.js';
+export { defineNodeDefinition, DEFAULT_PACKAGE_DEFINITION_VERSION, } from './core/nodes/package-definition.js';
+export type { PackageNodeShape, PackageInputField, PackageOutputField, PackageNodeDefinition } from './core/nodes/package-definition.js';
+/**
+ * Wrap a package factory's spec literal as the `FlowAction` instance `.step()`
+ * accepts, keeping the literal's own type. A built-in factory extends the SDK's
+ * `FlowActionSpec` union by augmenting an internal interface; a package has no
+ * such access, and does not need it: `.step(name, spec)` takes any `FlowAction`,
+ * and this is the one way to make one. The returned value IS the spec (the
+ * serializer reads `kind` and `inputs` off it) and is `instanceof FlowAction`.
+ *
+ * @param spec - The spec literal the factory built, `{ kind, inputs }`.
+ * @returns The same spec, typed as itself and as a `FlowAction`.
+ */
+export declare function packageActionSpec<S extends {
+    kind: string;
+}>(spec: S): S & FlowAction;
+/**
+ * The version of this extension contract. A package pins the version it was
+ * written against in `defineFlowNodeFamily({ contract })`; a mismatch is refused
+ * at import time, before any flow is built, with both numbers in the sentence.
+ * It moves only when a hook's signature changes.
+ */
+export declare const EXTENSION_CONTRACT_VERSION = 1;
+/** What a package passes to `defineFlowNodeFamily`. */
+export interface FlowNodeFamilyDefinition {
+    /** Stable id, e.g. `'local'`. Unique across the registry. */
+    readonly id: string;
+    readonly title: string;
+    /** The family's node types: single-version (`FlowNodeType`) or versioned (`FlowVersionedNodeType`), as a built-in family lists them. */
+    readonly types: FlowNodeFamily['types'];
+    readonly diagnostics: DiagnosticCatalog;
+    /** Rules over every placement of this family's types, after the per-node checks. */
+    readonly check?: NodeFamily<FlowContexts>['check'];
+    /** The package the family comes from; written as provenance into every definition. */
+    readonly package: PackageOrigin;
+    /** The `EXTENSION_CONTRACT_VERSION` the package was written against. */
+    readonly contract: number;
+}
+/**
+ * Define and register a node-type package's family with the Flow registry.
+ *
+ * Returns the family. Refuses, by throwing at import time, a contract version
+ * other than this SDK's and a family with no package name. The registry refuses,
+ * when it adopts the family (at compile time, before any node is serialized), a
+ * kind, type name, prefix or diagnostic code a built-in family or an earlier
+ * package owns, and a type that does not declare `definition: 'package'`.
+ */
+export declare function defineFlowNodeFamily(definition: FlowNodeFamilyDefinition): FlowNodeFamily;

package/dist/extend.js

@@ -0,0 +1,56 @@
+import { contributeFamily } from './core/nodes/extensions.js';
+import { builtinActionSpec } from './core/actions.js';
+export { defineNodeDefinition, DEFAULT_PACKAGE_DEFINITION_VERSION, } from './core/nodes/package-definition.js';
+/**
+ * Wrap a package factory's spec literal as the `FlowAction` instance `.step()`
+ * accepts, keeping the literal's own type. A built-in factory extends the SDK's
+ * `FlowActionSpec` union by augmenting an internal interface; a package has no
+ * such access, and does not need it: `.step(name, spec)` takes any `FlowAction`,
+ * and this is the one way to make one. The returned value IS the spec (the
+ * serializer reads `kind` and `inputs` off it) and is `instanceof FlowAction`.
+ *
+ * @param spec - The spec literal the factory built, `{ kind, inputs }`.
+ * @returns The same spec, typed as itself and as a `FlowAction`.
+ */
+export function packageActionSpec(spec) {
+    return builtinActionSpec(spec);
+}
+/**
+ * The version of this extension contract. A package pins the version it was
+ * written against in `defineFlowNodeFamily({ contract })`; a mismatch is refused
+ * at import time, before any flow is built, with both numbers in the sentence.
+ * It moves only when a hook's signature changes.
+ */
+export const EXTENSION_CONTRACT_VERSION = 1;
+/**
+ * Define and register a node-type package's family with the Flow registry.
+ *
+ * Returns the family. Refuses, by throwing at import time, a contract version
+ * other than this SDK's and a family with no package name. The registry refuses,
+ * when it adopts the family (at compile time, before any node is serialized), a
+ * kind, type name, prefix or diagnostic code a built-in family or an earlier
+ * package owns, and a type that does not declare `definition: 'package'`.
+ */
+export function defineFlowNodeFamily(definition) {
+    if (definition.contract !== EXTENSION_CONTRACT_VERSION) {
+        throw new Error(`node-type package ${definition.package?.name ?? definition.id} was written against extension contract `
+            + `${String(definition.contract)}, but this @uipath/maestro-builder-sdk provides ${EXTENSION_CONTRACT_VERSION}. `
+            + 'Update the package (or the SDK) so the two agree.');
+    }
+    if (typeof definition.package?.name !== 'string' || definition.package.name === '') {
+        throw new Error(`node-type family "${definition.id}" names no package; defineFlowNodeFamily needs package.name.`);
+    }
+    const family = {
+        id: definition.id,
+        title: definition.title,
+        types: definition.types,
+        diagnostics: definition.diagnostics,
+        package: { name: definition.package.name, ...(definition.package.version !== undefined ? { version: definition.package.version } : {}) },
+        ...(definition.check !== undefined ? { check: definition.check } : {}),
+    };
+    // Contributed, not registered: this entry stays light at import (FB009), so it
+    // never loads the Flow registry; the registry adopts the family when it loads
+    // (`core/nodes/extensions.ts`), and registers it at once if it already has.
+    contributeFamily(family);
+    return family;
+}

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

@@ -11,3 +11,10 @@ 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>;
+/**
+ * Register a node-type package's family with the Flow registry
+ * (`@uipath/maestro-builder-sdk/extend`'s `defineFlowNodeFamily` calls this).
+ * Refused, with the package named, when the family collides with a built-in
+ * family or with a package registered earlier.
+ */
+export declare function registerFlowNodeFamily(family: FlowNodeFamily): FlowNodeFamily;

package/dist/flow-node-registry.js

@@ -7,6 +7,7 @@
  * is left to port.
  */
 import { NodeTypeRegistry } from './core/nodes/registry.js';
+import { adoptContributedFamilies } from './core/nodes/extensions.js';
 import { hasBundledDefinition } from './flow-definitions.js';
 import { agentFlowFamily } from './nodes/agent/flow/family.js';
 import { aiPatternsFlowFamily } from './nodes/ai-patterns/flow/family.js';
@@ -25,3 +26,16 @@ 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 = [agentFlowFamily, aiPatternsFlowFamily, connectorFlowFamily, conversationFlowFamily, dataFabricFlowFamily, delayFlowFamily, documentFlowFamily, hitlFlowFamily, httpFlowFamily, mockFlowFamily, processFlowFamily, queueFlowFamily, scriptFlowFamily, transformFlowFamily];
 export const FLOW_NODE_TYPES = new NodeTypeRegistry('flow', FLOW_NODE_FAMILIES, { hasBundledDefinition });
+// Node-type packages contribute their families through the light `/extend` entry;
+// adopt the ones already contributed and register every later one as it arrives.
+adoptContributedFamilies((family) => FLOW_NODE_TYPES.register(family));
+/**
+ * Register a node-type package's family with the Flow registry
+ * (`@uipath/maestro-builder-sdk/extend`'s `defineFlowNodeFamily` calls this).
+ * Refused, with the package named, when the family collides with a built-in
+ * family or with a package registered earlier.
+ */
+export function registerFlowNodeFamily(family) {
+    FLOW_NODE_TYPES.register(family);
+    return family;
+}

package/dist/merge-cli.js

@@ -49,11 +49,12 @@ import { MergeRefusedError, mergeFlowWithSidecars } from './merge.js';
 import { sidecarSetFromList } from './merge-sidecars.js';
 import { isWithin } from './path-within.js';
 import { resourceSourcesOfOtherFlows } from './project-resource-users.js';
-import { flagValue, runWhenInvokedDirectly } from './cli-run.js';
+import { flagValue, flagValues, runWhenInvokedDirectly } from './cli-run.js';
 import { ensureTypeScriptRuntime } from './node-runtime.js';
 import { flowCheckOpts, openCliLibrary } from './cli-library.js';
 import { Bindings } from './bindings.js';
 import { defaultBindingsFile } from './workdir.js';
+import { loadNodePackages } from './node-packages.js';
 import { baselineFromOriginal, checkEdited, classifyDrafts, compileSourceDraftTolerant, findingCounts, splitUnplaced } from './merge-compile.js';
 const USAGE = 'usage: flow-merge <original.flow> <edited.flow | Edited.flow.ts> [-o merged.flow] '
     + '[--baseline <baseline.flow> | --baseline-from <original.flow>] [--library <dir>] [--bindings <file>] [--strict]';
@@ -159,7 +160,7 @@ export async function run(argv) {
         console.error(USAGE);
         return 2;
     }
-    const flags = new Set(['-o', '--baseline', '--baseline-from', '--library', '--bindings', '--connectors-local']);
+    const flags = new Set(['-o', '--baseline', '--baseline-from', '--library', '--bindings', '--connectors-local', '--package']);
     const positionals = argv.filter((a, i) => !flags.has(a) && !flags.has(argv[i - 1]) && !a.startsWith('-'));
     const [originalPath, editedPath] = positionals;
     if (!originalPath || !editedPath) {
@@ -200,6 +201,15 @@ export async function run(argv) {
     else {
         edited = JSON.parse(readFileSync(editedPath, 'utf8'));
     }
+    if (baselineFrom) {
+        // The baseline is a decompile of the original: load the node-type packages
+        // its definitions name, under the project's trust (package.json nodePackages
+        // or --package), so the decompiled source imports them rather than printing
+        // rawNode(...) — which would differ from the edit and refuse a clean merge.
+        const packages = await loadNodePackages(baselineFrom, JSON.parse(readFileSync(baselineFrom, 'utf8')), flagValues(argv, '--package'));
+        for (const message of packages.warnings)
+            console.error(`flow-merge: warning: ${message}`);
+    }
     const baselineCompile = baselineFrom
         ? await baselineFromOriginal(baselineFrom, compileOpts, (m) => console.error(`flow-merge: decompile warning: ${m}`))
         : undefined;

package/dist/merge-compile.js

@@ -49,7 +49,12 @@ export async function baselineFromOriginal(originalPath, opts = {}, warn) {
             }
         },
     });
-    const dir = mkdtempSync(join(tmpdir(), 'flow-merge-baseline-'));
+    // Beside the original, not in the system temp dir: the decompiled source imports
+    // the SDK, which `useThisSdkForAuthoredSource` resolves from anywhere, and any
+    // NODE-TYPE PACKAGE the original was written with, which Node resolves only by
+    // walking up from the file to a `node_modules` — the author's project's. A
+    // directory that cannot be written to (a read-only mount) falls back to tmp.
+    const dir = baselineDirectory(originalPath);
     try {
         writeFileSync(join(dir, 'package.json'), '{"type":"module"}\n');
         const file = join(dir, 'Baseline.flow.ts');
@@ -60,6 +65,14 @@ export async function baselineFromOriginal(originalPath, opts = {}, warn) {
         rmSync(dir, { recursive: true, force: true });
     }
 }
+function baselineDirectory(originalPath) {
+    try {
+        return mkdtempSync(join(dirname(resolve(originalPath)), '.flow-merge-baseline-'));
+    }
+    catch {
+        return mkdtempSync(join(tmpdir(), 'flow-merge-baseline-'));
+    }
+}
 /**
  * Sort each finding by what merge does with its node: `refused` when the node
  * comes from the edited flow (reason `edited`: the author changed or added it;