@uipath/maestro-builder-sdk 6.3.0 → 6.5.0

package/dist/api-index.md

@@ -19,7 +19,7 @@ compiler checks your source against, and it carries the `@remarks` and
 `@example` bodies the reference pages leave out. The span below is the whole
 declaration including its doc comment, so one read is the complete answer.
 
-Paths are relative to the installed package root:
+Paths are relative to the package root — the directory above this file:
 
 ```
 node_modules/@uipath/maestro-builder-sdk/dist/core/actions.d.ts    lines 539-610
@@ -29,11 +29,11 @@ Open the file at that line. No search, no `grep`, nothing shell-specific —
 which also means this works on Windows, where the command the reference pages
 used to suggest does not.
 
-The spans are generated by the same build that emits the `dist/` they point
-into, so they match the package they ship beside. They are NOT stable across
-versions — a line moves whenever the declaration above it changes — so an index
-and a `dist/` from different releases will not line up. If a span looks wrong,
-that is the thing to check first.
+This file is generated by the build that emits the `.d.ts` files beside it, so
+its spans are always true of THIS installed version. They are not stable across
+versions — a line moves whenever a declaration above it changes — which is why
+the index ships here and nowhere else: anywhere with its own release cadence
+could hand you spans for a version you do not have.
 
 ## `@uipath/maestro-builder-sdk`
 

package/dist/cli/commands/registry.js

@@ -27,10 +27,10 @@ export function registerRegistryCommands(program) {
         .option('--force', 're-download and regenerate even if the archive is cached')
         .option('--import <specifier>', 'module specifier for generated descriptors')
         .option('--triggers <path>', 'registry-triggers.json for trigger descriptors')
-        .option('--python <executable>', 'Python interpreter to run the generators with')
         .option('--root <prefix>', 'only extract archive entries under this prefix')
-        .option('--extractor <path>', 'extract_library.py to run instead of the packaged copy')
-        .option('--generator <path>', 'materialize_registry.py to run instead of the packaged copy')
+        .option('--python <executable>', '(deprecated, ignored) the generators run in-process')
+        .option('--extractor <path>', '(deprecated, ignored) the extractor is part of the package')
+        .option('--generator <path>', '(deprecated, ignored) the generators are part of the package')
         .action(async (options) => {
         const argv = [];
         addValue(argv, '--library', options.library);
@@ -54,12 +54,16 @@ export function registerRegistryCommands(program) {
     family.command('materialize')
         .description('Generate library-md and connectors/ from an extracted library-json.')
         .requiredOption('--library-json <dir>', 'extracted library-json directory')
-        .requiredOption('--library-md <dir>', 'markdown output directory')
-        .requiredOption('--connectors <dir>', 'TypeScript descriptor output directory')
+        .option('--library-md <dir>', 'markdown output directory (omit to skip the Markdown)')
+        .option('--connectors <dir>', 'TypeScript descriptor output directory (omit to skip descriptors)')
         .option('--import <specifier>', 'module specifier for generated descriptors')
         .option('--triggers <path>', 'registry-triggers.json for trigger descriptors')
-        .option('--python <executable>', 'Python interpreter to run the generators with')
-        .option('--generator <path>', 'materialize_registry.py to run instead of the packaged copy')
+        .option('--connector-subset <keys>', 'comma-separated connector keys to emit instead of all')
+        .option('--include-generic-expanded', 'also emit descriptors for GenericExpanded entries')
+        .option('--check-orphans', 'fail when an entry file has no index.json row (the image build asks for this)')
+        .option('--check-symbols', 'fail when a Markdown page cites a symbol the descriptors do not export')
+        .option('--python <executable>', '(deprecated, ignored) the generators run in-process')
+        .option('--generator <path>', '(deprecated, ignored) the generators are part of the package')
         .action(async (options) => {
         const argv = [];
         addValue(argv, '--library-json', options.libraryJson);
@@ -67,10 +71,56 @@ export function registerRegistryCommands(program) {
         addValue(argv, '--connectors', options.connectors);
         addValue(argv, '--import', options.import);
         addValue(argv, '--triggers', options.triggers);
+        addValue(argv, '--connector-subset', options.connectorSubset);
+        if (options.includeGenericExpanded)
+            argv.push('--include-generic-expanded');
+        if (options.checkSymbols)
+            argv.push('--check-symbols');
+        if (options.checkOrphans)
+            argv.push('--check-orphans');
         addValue(argv, '--python', options.python);
         addValue(argv, '--generator', options.generator);
         await invoke('registry materialize', () => loadTool(import.meta.url, '../../registry/materialize-cli.js'), argv);
     });
+    // The pipeline's generator, `generate_library_json.py`, flag for flag: the
+    // Azure YAML that calls it should only have to swap the executable.
+    family.command('build-library')
+        .description('Generate the canonical connector library from the UiPath Flow registry.')
+        .option('--output-dir <dir>', 'output directory (default: ./library)')
+        .option('--cache-dir <dir>', 'cache for `flow registry get` JSONs (default: ./.registry-cache)')
+        .option('--is-cache-dir <dir>', 'cache for `is resources describe` JSONs (default: ./.is-cache)')
+        .option('--connectors-cache-dir <dir>', 'cache for `is connectors metadata` JSONs (default: ./.is-connectors-cache)')
+        .option('--skip-enrichment', 'skip the `is resources describe` enrichment pass')
+        .option('--skip-connector-enrichment', 'skip the `is connectors metadata` connector-level pass')
+        .option('--skip-generic-expansion', 'keep Generic CRUD entries as templates instead of one entry per object/operation')
+        .option('--triggers-output <path>', 'trigger side-file path (default: <parent of --output-dir>/registry-triggers.json)')
+        .option('--keep-temp', 'keep the cache directories after the run')
+        .option('--offline', 'never run `uip`; treat an uncached call as a failed one (for replaying a build from kept caches)')
+        .option('--connectors <keys>', 'comma-separated connector keys to build as a curated subset (default: all)')
+        .option('--catalog-scope <scope>', "connector catalog scope: 'all', 'tier1' or 'tier2' (default: all)")
+        .option('--concurrency <n>', 'parallel remote CLI calls (default: 10)')
+        .action(async (options) => {
+        const argv = [];
+        addValue(argv, '--output-dir', options.outputDir);
+        addValue(argv, '--cache-dir', options.cacheDir);
+        addValue(argv, '--is-cache-dir', options.isCacheDir);
+        addValue(argv, '--connectors-cache-dir', options.connectorsCacheDir);
+        if (options.skipEnrichment)
+            argv.push('--skip-enrichment');
+        if (options.skipConnectorEnrichment)
+            argv.push('--skip-connector-enrichment');
+        if (options.skipGenericExpansion)
+            argv.push('--skip-generic-expansion');
+        addValue(argv, '--triggers-output', options.triggersOutput);
+        if (options.keepTemp)
+            argv.push('--keep-temp');
+        if (options.offline)
+            argv.push('--offline');
+        addValue(argv, '--connectors', options.connectors);
+        addValue(argv, '--catalog-scope', options.catalogScope);
+        addValue(argv, '--concurrency', options.concurrency);
+        await invoke('registry build-library', () => loadTool(import.meta.url, '../../registry/library-build/cli.js'), argv);
+    });
     family.command('prepare')
         .description("Resolve one operation's schema against a live connection into ./connectors-local.")
         .argument('<connector-key>', 'connector key, e.g. uipath-salesforce')
@@ -82,7 +132,11 @@ export function registerRegistryCommands(program) {
         .option('--bindings <file>', 'bindings file to update (default: ./bindings.json)')
         .option('--bind-connection <name>', 'symbolic connection name (default: the connector suffix)')
         .option('--bind-folder <name>', 'symbolic folder name (default: shared)')
-        .option('--no-bindings', 'discover the connection but leave bindings.json alone')
+        // A SEPARATE key, not commander's negation of `--bindings`: sharing one key
+        // made the result order-dependent, so `--no-bindings --bindings b.json` and
+        // the reverse disagreed. argparse had two independent options.
+        .option('--skip-bindings', 'discover the connection but leave bindings.json alone')
+        .option('--no-bindings', 'alias of --skip-bindings')
         .option('--object <name>', 'one connection-discovered object')
         .option('--all-objects', 'every connection-discovered object')
         .option('-f, --field <name=value>', 'parent field that selects the schema (repeatable)', collect, [])
@@ -92,8 +146,8 @@ export function registerRegistryCommands(program) {
         .option('--connector-version <version>', 'connector version to resolve against')
         .option('--import <specifier>', 'module specifier for generated descriptors')
         .option('--json-only', 'write the JSON overlay without generating TypeScript')
-        .option('--python <executable>', 'Python interpreter to run the generator with')
-        .option('--generator <path>', 'prepare_connector.py to run instead of the packaged copy')
+        .option('--python <executable>', '(deprecated, ignored once prepare runs in-process)')
+        .option('--generator <path>', '(deprecated, ignored: prepare runs in-process and no script is packaged)')
         // Commander declares the surface; the inner CLI only ever sees what is
         // forwarded below. Adding `--resolve` to prepare-cli.ts without adding it
         // HERE made the flag unreachable through the shipped command, while the
@@ -111,8 +165,10 @@ export function registerRegistryCommands(program) {
         addValue(argv, '--bindings', options.bindings);
         addValue(argv, '--bind-connection', options.bindConnection);
         addValue(argv, '--bind-folder', options.bindFolder);
-        // commander sets `bindings` false for `--no-bindings`.
-        if (options.bindings === false)
+        // commander sets `bindings` false for `--no-bindings`; `--skip-bindings`
+        // arrives under its own key, so neither spelling can be lost to the
+        // order the two flags appear in.
+        if (options.bindings === false || options.skipBindings)
             argv.push('--no-bindings');
         addValue(argv, '--object', options.object);
         if (options.allObjects)

package/dist/registry/archive/entry-policy.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Which archive entries the extractor is willing to write, and where.
+ *
+ * A zip carries whatever paths its author put in it, so entry names are
+ * validated rather than joined. This is `safe_relative_path` / `is_symlink`
+ * from `integrations/scripts/extract_library.py`, kept rule for rule so both
+ * extractors agree on what a hostile entry looks like:
+ *
+ *   * only entries under the root are considered, and the prefix is stripped,
+ *     so the tree flattens to the destination;
+ *   * a segment that is empty, `.` or `..` aborts the whole extraction. Not
+ *     skips it — aborts. An archive containing `../../etc/foo` is not an
+ *     archive with one bad file, it is an archive we should not be unpacking;
+ *   * absolute names and Windows drive letters are refused for the same reason;
+ *   * symlink entries are refused. Nothing in the library needs one, and a
+ *     symlink written during extraction turns a later write into a write
+ *     somewhere else.
+ */
+/** The archive asked for something outside the destination. */
+export declare class UnsafeArchive extends Error {
+    constructor(message: string);
+}
+/**
+ * The destination-relative path for `entryName`, or `undefined` to skip it.
+ *
+ * Throws {@link UnsafeArchive} when the name is one we refuse outright.
+ */
+export declare function safeRelativePath(entryName: string, root: string): string | undefined;
+/**
+ * Whether a central-directory `externalAttr` marks a symlink.
+ *
+ * The unix mode lives in the top 16 bits of the external attributes. Zips
+ * written on Windows leave it zero, which reads as "not a symlink" — correct,
+ * since those cannot carry one.
+ */
+export declare function isSymlinkEntry(externalAttr: number): boolean;

package/dist/registry/archive/entry-policy.js

@@ -0,0 +1,60 @@
+/**
+ * Which archive entries the extractor is willing to write, and where.
+ *
+ * A zip carries whatever paths its author put in it, so entry names are
+ * validated rather than joined. This is `safe_relative_path` / `is_symlink`
+ * from `integrations/scripts/extract_library.py`, kept rule for rule so both
+ * extractors agree on what a hostile entry looks like:
+ *
+ *   * only entries under the root are considered, and the prefix is stripped,
+ *     so the tree flattens to the destination;
+ *   * a segment that is empty, `.` or `..` aborts the whole extraction. Not
+ *     skips it — aborts. An archive containing `../../etc/foo` is not an
+ *     archive with one bad file, it is an archive we should not be unpacking;
+ *   * absolute names and Windows drive letters are refused for the same reason;
+ *   * symlink entries are refused. Nothing in the library needs one, and a
+ *     symlink written during extraction turns a later write into a write
+ *     somewhere else.
+ */
+/** The archive asked for something outside the destination. */
+export class UnsafeArchive extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "UnsafeArchive";
+    }
+}
+/**
+ * The destination-relative path for `entryName`, or `undefined` to skip it.
+ *
+ * Throws {@link UnsafeArchive} when the name is one we refuse outright.
+ */
+export function safeRelativePath(entryName, root) {
+    const normalized = entryName.replace(/\\/g, "/");
+    if (!normalized.startsWith(root))
+        return undefined;
+    const relative = normalized.slice(root.length);
+    if (relative === "" || relative.endsWith("/"))
+        return undefined; // the directory entry itself
+    const parts = relative.split("/");
+    if (relative.startsWith("/") || parts[0].includes(":")) {
+        throw new UnsafeArchive(`absolute or drive-qualified entry: ${entryName}`);
+    }
+    if (parts.some((part) => part === "" || part === "." || part === "..")) {
+        throw new UnsafeArchive(`unsafe entry: ${entryName}`);
+    }
+    return relative;
+}
+/** `S_IFMT` and `S_IFLNK` from `<sys/stat.h>`; `stat.S_ISLNK(mode)` is `(mode & S_IFMT) === S_IFLNK`. */
+const S_IFMT = 0o170000;
+const S_IFLNK = 0o120000;
+/**
+ * Whether a central-directory `externalAttr` marks a symlink.
+ *
+ * The unix mode lives in the top 16 bits of the external attributes. Zips
+ * written on Windows leave it zero, which reads as "not a symlink" — correct,
+ * since those cannot carry one.
+ */
+export function isSymlinkEntry(externalAttr) {
+    const mode = (externalAttr >>> 16) & 0xffff;
+    return (mode & S_IFMT) === S_IFLNK;
+}

package/dist/registry/archive/extract.d.ts

@@ -0,0 +1,31 @@
+export { UnsafeArchive } from "./entry-policy.js";
+export { NotAZip, UnsupportedArchive } from "./zip-reader.js";
+/** Only entries under this prefix are the library; the prefix is stripped on the way out. */
+export declare const DEFAULT_ROOT = "integrations/library-json/";
+export interface ExtractArchiveOptions {
+    /** The downloaded `.zip`. */
+    readonly archivePath: string;
+    /** Where the flattened `library-json/` tree lands; created if missing. */
+    readonly destination: string;
+    /** Only extract entries under this prefix (default {@link DEFAULT_ROOT}). */
+    readonly root?: string;
+}
+export interface ExtractArchiveResult {
+    /** Files written — directory entries and entries outside the root do not count. */
+    readonly written: number;
+}
+export type ExtractLibraryErrorCode = "NO_SUCH_ARCHIVE" | "UNSAFE_ARCHIVE" | "NOT_A_ZIP" | "UNSUPPORTED_ARCHIVE" | "NO_INDEX";
+/**
+ * Extraction stopped. `message` is exactly what the Python printed to stderr
+ * (`extract-library: …`), `code` says which way it failed, and `cause` carries
+ * the underlying {@link UnsafeArchive} / {@link NotAZip} /
+ * {@link UnsupportedArchive} when there is one.
+ */
+export declare class ExtractLibraryError extends Error {
+    readonly code: ExtractLibraryErrorCode;
+    readonly exitCode: 1;
+    constructor(message: string, code: ExtractLibraryErrorCode, options?: {
+        cause?: unknown;
+    });
+}
+export declare function extractArchive(options: ExtractArchiveOptions): ExtractArchiveResult;

package/dist/registry/archive/extract.js

@@ -0,0 +1,92 @@
+/**
+ * Extract the connector library out of a downloaded zip, safely.
+ *
+ * This is `integrations/scripts/extract_library.py` in TypeScript, so the SDK
+ * no longer needs Python for the one step where `zipfile` was the reason. The
+ * caller has already fetched the archive and checked its sha256; this only
+ * unpacks it, trusting nothing in it:
+ *
+ *   * entry names go through {@link safeRelativePath}, which flattens the tree
+ *     to the destination and aborts the WHOLE extraction on traversal — the
+ *     Python raised mid-loop and left what it had written, and so does this;
+ *   * symlink entries are refused;
+ *   * `index.json` has to land, or the archive was not the library and the
+ *     caller should hear about it rather than get an empty directory.
+ *
+ * Every failure is an {@link ExtractLibraryError} whose message is the line the
+ * Python printed to stderr; the caller prints it and exits 1.
+ */
+import { readFileSync } from "node:fs";
+import { join, resolve, sep } from "node:path";
+import { isFile, writeBytes, ensureDir } from "../files.js";
+import { UnsafeArchive, isSymlinkEntry, safeRelativePath } from "./entry-policy.js";
+import { NotAZip, UnsupportedArchive, entryData, readZipEntries } from "./zip-reader.js";
+export { UnsafeArchive } from "./entry-policy.js";
+export { NotAZip, UnsupportedArchive } from "./zip-reader.js";
+/** Only entries under this prefix are the library; the prefix is stripped on the way out. */
+export const DEFAULT_ROOT = "integrations/library-json/";
+/**
+ * Extraction stopped. `message` is exactly what the Python printed to stderr
+ * (`extract-library: …`), `code` says which way it failed, and `cause` carries
+ * the underlying {@link UnsafeArchive} / {@link NotAZip} /
+ * {@link UnsupportedArchive} when there is one.
+ */
+export class ExtractLibraryError extends Error {
+    code;
+    exitCode = 1;
+    constructor(message, code, options) {
+        super(message, options);
+        this.code = code;
+        this.name = "ExtractLibraryError";
+    }
+}
+/** `child` is `parent` or lives beneath it — both already `path.resolve`d. */
+function isWithin(parent, child) {
+    return child === parent || child.startsWith(parent.endsWith(sep) ? parent : parent + sep);
+}
+export function extractArchive(options) {
+    const { archivePath, destination } = options;
+    const root = options.root ?? DEFAULT_ROOT;
+    if (!isFile(archivePath)) {
+        throw new ExtractLibraryError(`extract-library: no such archive: ${archivePath}`, "NO_SUCH_ARCHIVE");
+    }
+    ensureDir(destination);
+    const destinationRoot = resolve(destination);
+    let written = 0;
+    try {
+        const buffer = readFileSync(archivePath);
+        for (const entry of readZipEntries(buffer)) {
+            const relative = safeRelativePath(entry.name, root);
+            if (relative === undefined)
+                continue;
+            if (isSymlinkEntry(entry.externalAttr)) {
+                throw new UnsafeArchive(`symlink entry: ${entry.name}`);
+            }
+            const target = resolve(destinationRoot, ...relative.split("/"));
+            // Defence in depth: the policy above already guarantees this, so it can
+            // never fire — but a second, independent check on the resolved path
+            // costs nothing and does not depend on the policy being right.
+            if (!isWithin(destinationRoot, target)) {
+                throw new UnsafeArchive(`entry escapes the destination: ${entry.name}`);
+            }
+            writeBytes(target, entryData(buffer, entry));
+            written += 1;
+        }
+    }
+    catch (error) {
+        if (error instanceof UnsafeArchive) {
+            throw new ExtractLibraryError(`extract-library: ${error.message}`, "UNSAFE_ARCHIVE", { cause: error });
+        }
+        if (error instanceof NotAZip) {
+            throw new ExtractLibraryError(`extract-library: ${archivePath} is not a zip: ${error.message}`, "NOT_A_ZIP", { cause: error });
+        }
+        if (error instanceof UnsupportedArchive) {
+            throw new ExtractLibraryError(`extract-library: ${archivePath} uses a zip feature this reader refuses: ${error.message}`, "UNSUPPORTED_ARCHIVE", { cause: error });
+        }
+        throw error;
+    }
+    if (written === 0 || !isFile(join(destination, "index.json"))) {
+        throw new ExtractLibraryError(`extract-library: ${archivePath} carries no ${root}index.json`, "NO_INDEX");
+    }
+    return { written };
+}

package/dist/registry/archive/zip-reader.d.ts

@@ -0,0 +1,38 @@
+/** The bytes are not a zip we can read: no end record, bad signatures, corrupt data. */
+export declare class NotAZip extends Error {
+    constructor(message: string);
+}
+/** A well-formed zip that uses a feature this reader refuses (zip64, encryption, …). */
+export declare class UnsupportedArchive extends Error {
+    constructor(message: string);
+}
+export interface ZipEntry {
+    /** The entry name as stored, `/`-separated by convention (not enforced here). */
+    readonly name: string;
+    /** 0 = stored, 8 = deflate. Anything else has already been refused. */
+    readonly method: number;
+    /** General purpose bit flags from the central directory. */
+    readonly flags: number;
+    readonly crc32: number;
+    readonly compressedSize: number;
+    readonly uncompressedSize: number;
+    readonly localHeaderOffset: number;
+    /** The high 16 bits carry the unix mode when the archive was made on unix. */
+    readonly externalAttr: number;
+    /** A directory entry: its name ends with `/`. */
+    readonly isDirectory: boolean;
+}
+/**
+ * Every entry in the archive, in central-directory order, with the features we
+ * refuse already rejected. Throws {@link NotAZip} when the bytes are not a zip
+ * and {@link UnsupportedArchive} for one we decline to read.
+ */
+export declare function readZipEntries(buffer: Uint8Array): ZipEntry[];
+/**
+ * The uncompressed bytes of one entry, CRC-checked.
+ *
+ * The local header's name and extra lengths are read from the local header
+ * itself: a writer may store a different extra field there than in the central
+ * directory, so the directory's lengths cannot be used to find the data.
+ */
+export declare function entryData(buffer: Uint8Array, entry: ZipEntry): Uint8Array;