@uipath/maestro-builder-sdk 6.51.3 → 6.52.0

package/dist/node-packages.d.ts

@@ -0,0 +1,68 @@
+/** The `package.json` key the trust list lives under. */
+export declare const NODE_PACKAGES_MANIFEST_KEY = "maestroBuilderSdk";
+export declare const NODE_PACKAGES_LIST_KEY = "nodePackages";
+export declare function isPackageName(spec: string): boolean;
+export interface TrustedPackages {
+    readonly names: ReadonlySet<string>;
+    /** Where each trusted name came from: the manifest path, or `--package`. */
+    readonly sources: ReadonlyMap<string, string>;
+    /** The `package.json` consulted, when one was found above the file. */
+    readonly manifest?: string;
+}
+/** The nearest `package.json` at or above `dir`, or undefined. */
+export declare function nearestPackageJson(dir: string): string | undefined;
+/**
+ * The packages this run may load: the project's `nodePackages` list plus the
+ * `--package` names. An entry that is not a bare package name is refused with
+ * the file it came from, so a manifest cannot smuggle a path or a URL in.
+ */
+export declare function trustedNodePackages(flowPath: string, flagged?: readonly string[]): TrustedPackages;
+/**
+ * The packages a flow's definitions name for node types the registry does not
+ * know yet, keyed by package, with the node types each one would explain.
+ */
+export declare function provenancePackages(flow: {
+    definitions?: unknown;
+}): Map<string, string[]>;
+/**
+ * Resolve `pkg` (and an optional `subpath`, `'./runtime'`) the way an ESM
+ * `import` from a file in `fromDir` would: walk up `node_modules` directories
+ * from there, and read the package's `exports` under import conditions — not
+ * `require.resolve`, whose CommonJS conditions refuse an import-only package and
+ * can pick a different entry of a dual one. Falls back to `main`, then
+ * `index.js`, for a package with no `exports`. Throws a sentence when nothing resolves.
+ */
+export declare function resolvePackageEntry(pkg: string, fromDir: string, subpath?: string): string;
+export interface LoadedNodePackages {
+    /** Packages imported, with where their trust came from. */
+    readonly loaded: ReadonlyArray<{
+        readonly package: string;
+        readonly trustedBy: string;
+        readonly resolved: string;
+    }>;
+    /** Packages the file names that the project does not trust; their nodes print as `rawNode`. */
+    readonly untrusted: ReadonlyArray<{
+        readonly package: string;
+        readonly nodeTypes: readonly string[];
+    }>;
+    /** Trusted packages that do not resolve from the file's directory. */
+    readonly missing: ReadonlyArray<{
+        readonly package: string;
+        readonly nodeTypes: readonly string[];
+        readonly error: string;
+    }>;
+    /** The warnings a tool prints, one sentence each. */
+    readonly warnings: readonly string[];
+}
+/** How to trust a package, as the warnings say it. */
+export declare function trustHint(pkg: string): string;
+/**
+ * Load every trusted package the flow needs (and every `--package`), resolved
+ * from the flow's directory. Importing a package registers its family through
+ * `/extend`; the registry adopts it at once, so a `decompile` that follows sees
+ * the types. Nothing is thrown for an untrusted or missing package: those are
+ * reported, and the caller's decompile falls back to `rawNode` for their nodes.
+ */
+export declare function loadNodePackages(flowPath: string, flow: {
+    definitions?: unknown;
+}, flagged?: readonly string[]): Promise<LoadedNodePackages>;

package/dist/node-packages.js

@@ -0,0 +1,279 @@
+/**
+ * Loading NODE-TYPE PACKAGES for a tool that has no author's module to import.
+ *
+ * `compile` needs none of this: the author's `.flow.ts` imports the package, the
+ * package registers its family (`@uipath/maestro-builder-sdk/extend`), and the
+ * build runs against a registry that knows the kinds. `decompile` and
+ * `merge --baseline-from` read a data-only `.flow`, so they have to learn which
+ * packages the file needs and load them — and loading a package runs its code.
+ *
+ * ## Provenance is discovery, not authorization
+ *
+ * A package type's definition in `definitions[]` carries `source.package`, the
+ * package that wrote it. That names what a node NEEDS; it never, on its own,
+ * causes an import. A package is loaded only when the project chose it:
+ *
+ *   - listed under `"maestroBuilderSdk": { "nodePackages": [...] }` in the nearest
+ *     `package.json` above the `.flow`, or
+ *   - named with `--package <name>` on the command line.
+ *
+ * The trust boundary is the one the project already has — `npm install` plus its
+ * own manifest — and nothing in a `.flow` can widen it. An untrusted package's
+ * nodes are printed as `rawNode(...)`, and the warning names the package and the
+ * two ways to trust it. Specifiers are validated as bare package names before
+ * anything is resolved: no paths, no URLs.
+ *
+ * ## Resolution is relative to the workflow, not the tool
+ *
+ * A globally installed SDK has its own `node_modules`, where the project's
+ * packages are not. Every package is resolved from the `.flow`'s own directory
+ * (`createRequire` anchored at the file) and the resolved URL is imported. The
+ * package's own `@uipath/maestro-builder-sdk/extend` import is redirected to the
+ * running SDK (`sdk-resolve-hook.ts`), so its family lands in this registry even
+ * when the project has a different copy of the SDK, or none.
+ *
+ * See docs/EXTENSIBLE_NODE_TYPES_DESIGN.md §3.5.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { FLOW_NODE_TYPES } from './flow-node-registry.js';
+import { useThisSdkForAuthoredSource } from './sdk-resolve.js';
+/** The `package.json` key the trust list lives under. */
+export const NODE_PACKAGES_MANIFEST_KEY = 'maestroBuilderSdk';
+export const NODE_PACKAGES_LIST_KEY = 'nodePackages';
+/** A bare npm package name: `name` or `@scope/name`; no path, no URL, no version. */
+const PACKAGE_NAME = /^(?:@[a-z0-9][a-z0-9._~-]*\/)?[a-z0-9][a-z0-9._~-]*$/;
+export function isPackageName(spec) {
+    return PACKAGE_NAME.test(spec) && spec.length <= 214;
+}
+/** The nearest `package.json` at or above `dir`, or undefined. */
+export function nearestPackageJson(dir) {
+    let current = resolve(dir);
+    for (;;) {
+        const candidate = join(current, 'package.json');
+        if (existsSync(candidate))
+            return candidate;
+        const parent = dirname(current);
+        if (parent === current)
+            return undefined;
+        current = parent;
+    }
+}
+/**
+ * The packages this run may load: the project's `nodePackages` list plus the
+ * `--package` names. An entry that is not a bare package name is refused with
+ * the file it came from, so a manifest cannot smuggle a path or a URL in.
+ */
+export function trustedNodePackages(flowPath, flagged = []) {
+    const names = new Set();
+    const sources = new Map();
+    for (const name of flagged) {
+        if (!isPackageName(name))
+            throw new Error(`--package ${JSON.stringify(name)} is not a bare npm package name (expected name or @scope/name).`);
+        names.add(name);
+        sources.set(name, '--package');
+    }
+    const manifest = nearestPackageJson(dirname(resolve(flowPath)));
+    if (manifest !== undefined) {
+        let parsed;
+        try {
+            parsed = JSON.parse(readFileSync(manifest, 'utf8'));
+        }
+        catch (error) {
+            throw new Error(`${manifest}: cannot read the nodePackages list: ${error.message}`);
+        }
+        const section = parsed?.[NODE_PACKAGES_MANIFEST_KEY];
+        const list = section?.[NODE_PACKAGES_LIST_KEY];
+        if (list !== undefined) {
+            if (!Array.isArray(list) || !list.every((entry) => typeof entry === 'string')) {
+                throw new Error(`${manifest}: "${NODE_PACKAGES_MANIFEST_KEY}"."${NODE_PACKAGES_LIST_KEY}" must be an array of package names.`);
+            }
+            for (const name of list) {
+                if (!isPackageName(name)) {
+                    throw new Error(`${manifest}: nodePackages entry ${JSON.stringify(name)} is not a bare npm package name (expected name or @scope/name).`);
+                }
+                if (!names.has(name)) {
+                    names.add(name);
+                    sources.set(name, manifest);
+                }
+            }
+        }
+    }
+    return { names, sources, manifest };
+}
+/**
+ * The packages a flow's definitions name for node types the registry does not
+ * know yet, keyed by package, with the node types each one would explain.
+ */
+export function provenancePackages(flow) {
+    const out = new Map();
+    const definitions = Array.isArray(flow.definitions) ? flow.definitions : [];
+    for (const def of definitions) {
+        const nodeType = typeof def?.nodeType === 'string' ? def.nodeType : undefined;
+        const source = def?.source;
+        const pkg = typeof source?.package === 'string' ? source.package : undefined;
+        if (nodeType === undefined || pkg === undefined)
+            continue;
+        if (FLOW_NODE_TYPES.byTypeName(nodeType) !== undefined)
+            continue;
+        const list = out.get(pkg) ?? [];
+        if (!list.includes(nodeType))
+            list.push(nodeType);
+        out.set(pkg, list);
+    }
+    return out;
+}
+/** The conditions an ESM `import` resolves `exports` with, in Node's order. */
+const IMPORT_CONDITIONS = ['node', 'import', 'default'];
+/** `exports` target for `subpath` under import conditions; undefined when the package does not export it. */
+function exportsTarget(exportsField, subpath) {
+    const pick = (value) => {
+        if (typeof value === 'string')
+            return value;
+        if (Array.isArray(value)) {
+            for (const v of value) {
+                const hit = pick(v);
+                if (hit !== undefined)
+                    return hit;
+            }
+            return undefined;
+        }
+        if (value !== null && typeof value === 'object') {
+            for (const [key, v] of Object.entries(value)) {
+                if (IMPORT_CONDITIONS.includes(key)) {
+                    const hit = pick(v);
+                    if (hit !== undefined)
+                        return hit;
+                }
+            }
+        }
+        return undefined;
+    };
+    if (typeof exportsField === 'string' || Array.isArray(exportsField))
+        return subpath === '.' ? pick(exportsField) : undefined;
+    if (exportsField === null || typeof exportsField !== 'object')
+        return undefined;
+    const map = exportsField;
+    // Either a subpath map ({ ".": …, "./runtime": … }) or bare conditions for ".".
+    if (!Object.keys(map).some((k) => k.startsWith('.')))
+        return subpath === '.' ? pick(map) : undefined;
+    if (Object.hasOwn(map, subpath))
+        return pick(map[subpath]);
+    // Subpath patterns, as Node resolves them: a key with one `*` matches when the
+    // subpath has its prefix and suffix; the longest prefix wins, and the matched
+    // part replaces every `*` in the target ("./*": "./dist/*.js" → ./dist/runtime.js).
+    let best;
+    for (const key of Object.keys(map)) {
+        const star = key.indexOf('*');
+        if (star < 0 || key.indexOf('*', star + 1) >= 0)
+            continue;
+        const prefix = key.slice(0, star);
+        const suffix = key.slice(star + 1);
+        if (!subpath.startsWith(prefix) || !subpath.endsWith(suffix) || subpath.length < prefix.length + suffix.length)
+            continue;
+        if (best === undefined || prefix.length > best.prefix.length)
+            best = { key, prefix, match: subpath.slice(prefix.length, subpath.length - suffix.length) };
+    }
+    if (best === undefined)
+        return undefined;
+    const target = pick(map[best.key]);
+    return target === undefined ? undefined : target.split('*').join(best.match);
+}
+/**
+ * Resolve `pkg` (and an optional `subpath`, `'./runtime'`) the way an ESM
+ * `import` from a file in `fromDir` would: walk up `node_modules` directories
+ * from there, and read the package's `exports` under import conditions — not
+ * `require.resolve`, whose CommonJS conditions refuse an import-only package and
+ * can pick a different entry of a dual one. Falls back to `main`, then
+ * `index.js`, for a package with no `exports`. Throws a sentence when nothing resolves.
+ */
+export function resolvePackageEntry(pkg, fromDir, subpath = '.') {
+    let current = resolve(fromDir);
+    for (;;) {
+        const root = join(current, 'node_modules', ...pkg.split('/'));
+        const manifestPath = join(root, 'package.json');
+        if (existsSync(manifestPath)) {
+            const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
+            let target;
+            if (manifest.exports !== undefined) {
+                target = exportsTarget(manifest.exports, subpath);
+                if (target === undefined)
+                    throw new Error(`${pkg} does not export "${subpath}" for import (${manifestPath}).`);
+            }
+            else if (subpath === '.') {
+                target = typeof manifest.main === 'string' ? manifest.main : 'index.js';
+            }
+            else {
+                target = subpath;
+            }
+            const file = resolve(root, target);
+            if (!existsSync(file))
+                throw new Error(`${pkg}'s entry ${target} is missing (${file}).`);
+            return file;
+        }
+        const parent = dirname(current);
+        if (parent === current)
+            throw new Error(`Cannot find package '${pkg}' in any node_modules above ${fromDir}.`);
+        current = parent;
+    }
+}
+/** How to trust a package, as the warnings say it. */
+export function trustHint(pkg) {
+    return `add it to package.json ("${NODE_PACKAGES_MANIFEST_KEY}": { "${NODE_PACKAGES_LIST_KEY}": [${JSON.stringify(pkg)}] }) or pass --package ${pkg}`;
+}
+/**
+ * Load every trusted package the flow needs (and every `--package`), resolved
+ * from the flow's directory. Importing a package registers its family through
+ * `/extend`; the registry adopts it at once, so a `decompile` that follows sees
+ * the types. Nothing is thrown for an untrusted or missing package: those are
+ * reported, and the caller's decompile falls back to `rawNode` for their nodes.
+ */
+export async function loadNodePackages(flowPath, flow, flagged = []) {
+    const trusted = trustedNodePackages(flowPath, flagged);
+    const needed = provenancePackages(flow);
+    // Every package the project trusts is a candidate, not only the ones provenance
+    // names: a hand-written or older .flow whose definition carries no
+    // `source.package` is served by listing the package (or passing --package).
+    for (const name of trusted.names)
+        if (!needed.has(name))
+            needed.set(name, []);
+    const loaded = [];
+    const untrusted = [];
+    const missing = [];
+    const warnings = [];
+    const fromDir = dirname(resolve(flowPath));
+    for (const [pkg, nodeTypes] of needed) {
+        if (!trusted.names.has(pkg)) {
+            untrusted.push({ package: pkg, nodeTypes });
+            warnings.push(`node type${nodeTypes.length === 1 ? '' : 's'} ${nodeTypes.map((t) => `"${t}"`).join(', ')} come${nodeTypes.length === 1 ? 's' : ''} from package ${pkg} `
+                + `(definitions[].source.package), which this project does not trust; ${trustHint(pkg)}. Its nodes are printed as rawNode(...).`);
+            continue;
+        }
+        if (!isPackageName(pkg)) {
+            // A trusted list never holds one of these (trustedNodePackages refuses), so this is provenance lying.
+            untrusted.push({ package: pkg, nodeTypes });
+            warnings.push(`definitions[].source.package ${JSON.stringify(pkg)} is not a bare npm package name; its nodes are printed as rawNode(...).`);
+            continue;
+        }
+        let resolved;
+        try {
+            resolved = resolvePackageEntry(pkg, fromDir);
+        }
+        catch (error) {
+            missing.push({ package: pkg, nodeTypes, error: error.message });
+            warnings.push(`package ${pkg} is trusted (${trusted.sources.get(pkg)}) but does not resolve from ${fromDir}: ${error.message} Install it beside the flow (npm install ${pkg}); its nodes are printed as rawNode(...).`);
+            continue;
+        }
+        // A package imports `@uipath/maestro-builder-sdk/extend`. Point that at THIS
+        // SDK, as compile does for authored source: a second copy (the project's own,
+        // under a globally installed tool) would register the family into a registry
+        // this run never reads. Installed only now, right before a real import, so a
+        // run that falls back to rawNode for every package never needs the hook —
+        // a bundled CLI has none (tests/cli-bundle.test.ts).
+        useThisSdkForAuthoredSource();
+        await import(pathToFileURL(resolved).href);
+        loaded.push({ package: pkg, trustedBy: trusted.sources.get(pkg), resolved });
+    }
+    return { loaded, untrusted, missing, warnings };
+}

package/dist/serialize.d.ts

@@ -30,7 +30,8 @@ export type DraftCode = BindingRefusalCode | typeof CONNECTOR_INPUT_MISSING | 'C
 export interface DraftFinding {
     /** The emitted node's id. */
     nodeId: string;
-    code: DraftCode;
+    /** A {@link DraftCode}, or a node-type package's own code reported through `ctx.draft`. */
+    code: DraftCode | string;
     /** The sentence the strict compile refuses with. */
     message: string;
 }

package/dist/serialize.js

@@ -2399,8 +2399,15 @@ export function serialize(built, opts = {}) {
             // makeNode, with the message every definition's mismatch gets.
             def = resolveContributionDefinition(contribution.definition, entry.type.versionedByDefinition ? undefined : version, where);
         }
-        else if (impl.definition === 'per-tenant' && resolved.carried === undefined) {
-            throw new Error(`internal SDK error: ${where}: per-tenant node type ${impl.typeName}@${version} returned no definition.`);
+        else if (impl.definition !== 'bundled' && resolved.carried === undefined) {
+            throw new Error(`internal SDK error: ${where}: ${impl.definition} node type ${impl.typeName}@${version} returned no definition.`);
+        }
+        // A package definition carries its provenance: which package wrote it, at
+        // which version. Decompile loads the package's authoring half from it, and
+        // the local engine the package's runtime half (docs/EXTENSIBLE_NODE_TYPES_DESIGN.md).
+        if (impl.definition === 'package' && def !== undefined) {
+            const origin = entry.family.package;
+            def = { ...def, source: { package: origin.name, ...(origin.version !== undefined ? { version: origin.version } : {}) } };
         }
         // A type that owns a family of names (`typeNamePrefix`) is placed under the
         // name its definition carries — `uipath.core.function.<key>`, not the prefix.
@@ -2413,7 +2420,7 @@ export function serialize(built, opts = {}) {
             throw new Error(`internal SDK error: ${where}: node type ${impl.typeName}@${version} supplied a definition for `
                 + `${JSON.stringify(nodeType)}, which is not a name it owns under "${prefix}".`);
         }
-        if (impl.definition === 'per-tenant') {
+        if (impl.definition !== 'bundled') {
             // At a version the flow carries, the carried definition answers: the
             // type's declaration speaks for the versions it registers, and an older
             // tenant definition (an inline agent at 1.1) may have no error handle.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uipath/maestro-builder-sdk",
-  "version": "6.51.3",
+  "version": "6.52.0",
   "description": "Build UiPath Flow, Case, and BPMN artifacts by writing TypeScript.",
   "license": "MIT",
   "homepage": "https://docs.uipath.com/maestro",
@@ -29,6 +29,10 @@
       "types": "./dist/bpmn/bpmn-sdk.d.ts",
       "import": "./dist/bpmn/bpmn-sdk.js"
     },
+    "./extend": {
+      "types": "./dist/extend.d.ts",
+      "import": "./dist/extend.js"
+    },
     "./cli": {
       "types": "./dist/cli/index.d.ts",
       "import": "./dist/cli/index.js"
@@ -92,5 +96,5 @@
     "@types/node": "^22.7.0",
     "esbuild": "^0.28.1"
   },
-  "gitref": "5e87eb230755d35a3c37ebb1921442ab5e196245"
+  "gitref": "4338e0cd3aa57c2329696080bee010a1e80d2e87"
 }