@uipath/maestro-builder-sdk 6.51.3 → 6.52.1

package/dist/core/nodes/package-definition.js

@@ -0,0 +1,162 @@
+/**
+ * The node definition a node-type package writes into a compiled `.flow`.
+ *
+ * A package type has no platform definition — neither the SDK's bundled snapshot
+ * nor the tenant has one — so the file has to carry everything a reader needs:
+ * the designer's display and handles, the input and output schemas, and the
+ * `model.expansion` template the `.flow` → BPMN converter expands.
+ *
+ * ## Why one-node expansion
+ *
+ * The product's converter (vendored in `local-engine`) resolves a node's
+ * definition as `manifestDef ?? fileDef` and reads a node's per-instance input
+ * VALUES only through a definition's `model.expansion`: a `context` entry's
+ * `source: 'node.data.inputs.<name>'` is read off each placed node while the
+ * template is expanded. So every package definition expands to exactly one
+ * `bpmn:ServiceTask` that REPLACES the node under its own id, carries
+ * `<uipath:type value="<serviceType>">`, its inputs as context, and its
+ * `=response` / `=Error` output rows — the element shape a runtime's dispatch
+ * lane reads for a connector. Expansion drops the node's original edges, so the
+ * template re-creates the `success` edge and, when the author wired `.onError`,
+ * an error boundary with the `error` edge.
+ *
+ * The input NAMES are the contract with the runtime half of the package: a
+ * handler reads them off `TaskContext.inputs`. A `string` context entry is
+ * emitted as `value` and a `json` one as a JSON `body`; the converter turns a
+ * falsy `string` into `""` and a falsy `json` into `{}`, so a package encodes
+ * booleans and numbers as `=js:` expressions rather than relying on either.
+ */
+export const DEFAULT_PACKAGE_DEFINITION_VERSION = '1.0';
+const ERROR_SCHEMA = {
+    $schema: 'http://json-schema.org/draft-07/schema#',
+    type: 'object',
+    required: ['code', 'message', 'detail', 'category', 'status'],
+    properties: {
+        code: { type: 'string', description: 'Error code as a string' },
+        message: { type: 'string', description: 'High-level error message' },
+        detail: { type: 'string', description: 'Detailed error description' },
+        category: { type: 'string', description: 'Error category' },
+        status: { type: 'integer', description: 'HTTP status code' },
+    },
+    additionalProperties: false,
+};
+/** The context entry type the converter emits for a field: structured values ride as a JSON body. */
+function contextType(field) {
+    return field.type === 'array' || field.type === 'object' ? 'json' : 'string';
+}
+/**
+ * Build a package node's definition from its shape: the complete manifest a
+ * compiled flow carries as a `snapshot` reference, with the one-node expansion
+ * described above. Provenance (`source.package`) is stamped at serialize time
+ * from the family's `package`, not here, so a shape stays free of the package's
+ * own name.
+ */
+export function defineNodeDefinition(shape) {
+    const version = shape.version ?? DEFAULT_PACKAGE_DEFINITION_VERSION;
+    const context = Object.entries(shape.inputs).map(([name, field]) => ({
+        name,
+        type: contextType(field),
+        source: `node.data.inputs.${name}`,
+    }));
+    const properties = Object.fromEntries(Object.entries(shape.inputs).map(([name, field]) => [name, {
+            type: field.type,
+            description: field.description,
+            ...(field.enum ? { enum: [...field.enum] } : {}),
+        }]));
+    const required = Object.entries(shape.inputs).filter(([, f]) => f.required).map(([name]) => name);
+    const inputDefaults = Object.fromEntries(Object.entries(shape.inputs).filter(([, f]) => f.default !== undefined).map(([name, f]) => [name, f.default]));
+    return {
+        nodeType: shape.nodeType,
+        version,
+        category: shape.category ?? 'package',
+        description: shape.description,
+        tags: shape.tags ? [...shape.tags] : ['package', ...shape.nodeType.split('.').slice(1)],
+        sortOrder: 90,
+        supportsErrorHandling: true,
+        display: { label: shape.label, icon: shape.icon },
+        handleConfiguration: [
+            { position: 'left', handles: [{ id: 'input', type: 'target', handleType: 'input' }] },
+            {
+                position: 'right',
+                handles: [
+                    { id: 'success', type: 'source', handleType: 'output' },
+                    {
+                        id: 'error', label: 'Error', type: 'source', handleType: 'output',
+                        visible: '{inputs.errorHandlingEnabled}', constraints: { maxConnections: 1 },
+                    },
+                ],
+            },
+        ],
+        debug: { runtime: 'bpmnEngine' },
+        model: {
+            type: 'bpmn:ServiceTask',
+            serviceType: shape.serviceType,
+            version: 'v1',
+            expansion: {
+                nodes: [
+                    {
+                        id: '{nodeId}',
+                        type: 'bpmn:ServiceTask',
+                        replaceOriginal: true,
+                        position: { x: 0, y: 0 },
+                        data: {
+                            label: '{node.data.label}',
+                            model: {
+                                serviceType: shape.serviceType,
+                                version: 'v1',
+                                context,
+                                outputs: [
+                                    { name: 'output', type: 'object', source: '=response', var: 'output' },
+                                    { name: 'error', type: 'object', source: '=Error', var: 'error' },
+                                ],
+                            },
+                        },
+                    },
+                    {
+                        condition: "hasEdgeFromHandle('error')",
+                        id: '_Implicit_BoundaryError_{nodeId}',
+                        type: 'bpmn:BoundaryEvent',
+                        parentId: null,
+                        position: { x: 0, y: 0 },
+                        data: {
+                            label: 'Error',
+                            attachedToId: '{nodeId}',
+                            eventDefinition: { type: 'bpmn:ErrorEventDefinition', id: '_Implicit_BoundaryError_{nodeId}_Error' },
+                            // The `=Error` envelope is written by the BOUNDARY's output row when it
+                            // fires, not by the failed task's own row — without this, `.onError`
+                            // handlers read `<step>.error` as undefined. `custom: true` keeps the var
+                            // as written: the converter would otherwise prefix it with the boundary's id.
+                            model: { outputs: [{ name: 'error', type: 'object', source: '=Error', var: '{nodeId}.error', custom: true }] },
+                        },
+                    },
+                ],
+                edges: [
+                    { matchOriginalEdgeByHandle: 'success', preserveEdgeId: true, source: '{nodeId}', type: 'bpmn:SequenceFlow' },
+                    {
+                        condition: "hasEdgeFromHandle('error')",
+                        matchOriginalEdgeByHandle: 'error',
+                        preserveEdgeId: true,
+                        source: '_Implicit_BoundaryError_{nodeId}',
+                        type: 'bpmn:SequenceFlow',
+                    },
+                ],
+            },
+        },
+        inputDefinition: { type: 'object', properties, required },
+        inputDefaults,
+        outputDefinition: {
+            output: {
+                type: 'object',
+                description: `What ${shape.label} produced`,
+                source: '=response',
+                var: 'output',
+                schema: {
+                    $schema: 'http://json-schema.org/draft-07/schema#',
+                    type: 'object',
+                    properties: Object.fromEntries(Object.entries(shape.outputs).map(([k, v]) => [k, { type: v.type, description: v.description }])),
+                },
+            },
+            error: { type: 'object', description: 'Error information if the step fails', source: '=Error', var: 'error', schema: ERROR_SCHEMA },
+        },
+    };
+}

package/dist/core/nodes/registry.d.ts

@@ -35,13 +35,25 @@ export interface NodeTypeRegistryOptions {
 export declare class NodeTypeRegistry<Ctx extends ArtifactContexts> {
     #private;
     readonly artifact: string;
-    readonly families: readonly NodeFamily<Ctx>[];
     /**
      * @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: string, families: readonly NodeFamily<Ctx>[], options: NodeTypeRegistryOptions);
+    /** Every family the registry knows: the built-in ones, then the registered packages' in registration order. */
+    get families(): readonly NodeFamily<Ctx>[];
+    /**
+     * 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: NodeFamily<Ctx>): void;
     /**
      * The node type for a spec, by its kind, or undefined when the kind is not
      * registered. When several types share the kind, the one whose `matches(spec)`

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;