@uipath/maestro-builder-sdk 6.13.0 → 6.14.0

package/README.md

@@ -8,12 +8,18 @@ Data flows through named variables and expressions — you never write native `i
 
 ## Quick start
 
-Install the SDK:
+Install the SDK globally:
 
 ```bash
-npm install @uipath/maestro-builder-sdk
+npm install -g @uipath/maestro-builder-sdk
 ```
 
+A global install is enough: the workspace needs no `package.json` or
+`node_modules`. When the SDK loads an authored file, every
+`import … from '@uipath/maestro-builder-sdk'` (and `/case`, `/bpmn`) resolves
+to the copy that is running, wherever it is installed. A project-local install
+(`npm install --save-dev`) still works, for a project that pins a version.
+
 ### Author
 
 A whole flow is one file. `HelloWorld.flow.ts`:

package/dist/bpmn/load.js

@@ -2,6 +2,7 @@
 import { pathToFileURL } from 'node:url';
 import { resolve } from 'node:path';
 import { existsSync } from 'node:fs';
+import { useThisSdkForAuthoredSource } from '../sdk-resolve.js';
 /** Resolve a user argument (a `.ts` path or a BaseName) to a bpmn source file. */
 export function resolveBpmnFile(arg) {
     const candidates = [arg, `${arg}.bpmn.ts`, `${arg}.ts`];
@@ -11,6 +12,7 @@ export function resolveBpmnFile(arg) {
     throw new Error(`bpmn source not found: tried ${candidates.join(', ')}`);
 }
 export async function loadBuiltBpmn(file) {
+    useThisSdkForAuthoredSource();
     const mod = await import(pathToFileURL(file).href);
     const exp = mod.default ?? mod.bpmn;
     if (!exp)

package/dist/case/load.js

@@ -2,6 +2,7 @@
 import { pathToFileURL } from 'node:url';
 import { resolve } from 'node:path';
 import { existsSync, statSync } from 'node:fs';
+import { useThisSdkForAuthoredSource } from '../sdk-resolve.js';
 /**
  * Resolve a user argument (a `.ts` path or a BaseName) to a case source file.
  *
@@ -21,6 +22,7 @@ export function resolveCaseFile(arg) {
     throw new Error(`case source not found: tried ${candidates.join(', ')}`);
 }
 export async function loadBuiltCase(file) {
+    useThisSdkForAuthoredSource();
     const mod = await import(pathToFileURL(file).href);
     const exp = mod.default ?? mod.casePlan ?? mod.case;
     if (!exp)

package/dist/load.js

@@ -2,6 +2,7 @@
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { basename, dirname, join, resolve } from 'node:path';
 import { statSync } from 'node:fs';
+import { useThisSdkForAuthoredSource } from './sdk-resolve.js';
 /** Resolve a user argument (a `.ts` path or a BaseName) to a flow source file. */
 export function resolveFlowFile(arg) {
     const candidates = [arg, `${arg}.flow.ts`, `${arg}.ts`];
@@ -19,6 +20,7 @@ export function resolveFlowFile(arg) {
     throw new Error(`flow source not found: tried ${candidates.join(', ')}`);
 }
 export async function loadBuiltFlow(file) {
+    useThisSdkForAuthoredSource();
     let mod;
     try {
         mod = await import(pathToFileURL(file).href);

package/dist/sdk-resolve-hook.d.ts

@@ -0,0 +1,9 @@
+interface ResolveContext {
+    parentURL?: string;
+    [key: string]: unknown;
+}
+type NextResolve = (specifier: string, context?: ResolveContext) => unknown;
+/** True for the package name and its subpath exports (`/case`, `/bpmn`, …). */
+export declare function isSdkSpecifier(specifier: string): boolean;
+export declare function resolve(specifier: string, context: ResolveContext, nextResolve: NextResolve): Promise<unknown>;
+export {};

package/dist/sdk-resolve-hook.js

@@ -0,0 +1,29 @@
+/**
+ * Node resolve hook: authored source always imports THIS copy of the SDK.
+ *
+ * Authored `.flow.ts` / `.case.ts` / `.bpmn.ts` files, and the `connectors/*.ts`
+ * modules the registry generates, import the package by name. Node resolves a
+ * bare specifier by walking `node_modules` up from the importing file, so the
+ * name only resolved when the workspace had its own install. A global install
+ * (`npm install -g`) is never on that path, and ESM ignores `NODE_PATH`.
+ *
+ * The hook re-resolves those specifiers from inside this package instead.
+ * Node's package self-reference (a package may import its own name when it
+ * declares `exports`) then maps them to the files beside this one. The same
+ * mapping also guarantees one copy: the serializer checks builders with
+ * `instanceof`, and a second copy of the package in the workspace would fail
+ * those checks with errors that do not name the cause.
+ *
+ * Registered by `sdk-resolve.ts` before any authored module is imported.
+ */
+import { PACKAGE_NAME } from './package-name.js';
+/** True for the package name and its subpath exports (`/case`, `/bpmn`, …). */
+export function isSdkSpecifier(specifier) {
+    return specifier === PACKAGE_NAME || specifier.startsWith(`${PACKAGE_NAME}/`);
+}
+export async function resolve(specifier, context, nextResolve) {
+    if (isSdkSpecifier(specifier)) {
+        return nextResolve(specifier, { ...context, parentURL: import.meta.url });
+    }
+    return nextResolve(specifier, context);
+}

package/dist/sdk-resolve.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Make `import … from '@uipath/maestro-builder-sdk'` in authored source resolve
+ * to the running package, installed locally or globally. See
+ * `sdk-resolve-hook.ts` for why. Idempotent; call it before importing authored
+ * source.
+ *
+ * Does nothing when the compiled hook is absent, which is the case only when
+ * the SDK runs from its TypeScript source under the test runner. The runner
+ * resolves imports itself, so no hook is needed there.
+ */
+export declare function useThisSdkForAuthoredSource(): void;

package/dist/sdk-resolve.js

@@ -0,0 +1,24 @@
+/** Register the resolve hook that points authored source at this SDK copy. */
+import { existsSync } from 'node:fs';
+import { register } from 'node:module';
+import { fileURLToPath } from 'node:url';
+let registered = false;
+/**
+ * Make `import … from '@uipath/maestro-builder-sdk'` in authored source resolve
+ * to the running package, installed locally or globally. See
+ * `sdk-resolve-hook.ts` for why. Idempotent; call it before importing authored
+ * source.
+ *
+ * Does nothing when the compiled hook is absent, which is the case only when
+ * the SDK runs from its TypeScript source under the test runner. The runner
+ * resolves imports itself, so no hook is needed there.
+ */
+export function useThisSdkForAuthoredSource() {
+    if (registered)
+        return;
+    registered = true;
+    const hook = new URL('./sdk-resolve-hook.js', import.meta.url);
+    if (!existsSync(fileURLToPath(hook)))
+        return;
+    register(hook);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uipath/maestro-builder-sdk",
-  "version": "6.13.0",
+  "version": "6.14.0",
   "description": "Build UiPath Flow, Case, and BPMN artifacts by writing TypeScript.",
   "license": "MIT",
   "homepage": "https://docs.uipath.com/maestro",
@@ -92,5 +92,5 @@
     "@types/node": "^22.7.0",
     "esbuild": "^0.28.1"
   },
-  "gitref": "bf85d17e1d820f584329913c9ac836a2fbc23dec"
+  "gitref": "84bd49a28ffaae311bcb7b3207a311dfeaf1c08f"
 }