@uipath/maestro-builder-sdk 5.2.0

package/dist/ref-resolve.d.ts

@@ -0,0 +1,77 @@
+/**
+ * `$ref` resolution for SPLIT `.flow` files (design §5, Phase 5E).
+ *
+ * The format lets a `.flow` be split across sibling files with JSON Reference
+ * (`{ "$ref": "./layout.json" }`) — used to sideline layout or definitions, or
+ * to extract a subflow out of an oversized file
+ * (`flow-schema/REF_RESOLUTION.md`, MST-8579). Decompile has to READ those, so
+ * this resolves them into ONE object model before anything else looks at the
+ * document.
+ *
+ * Compile keeps writing a single file, deliberately: nothing in the designer or
+ * the skills splits files today, so write-through splitting would be a merge
+ * concern with no producer to round-trip against.
+ *
+ * The semantics below are the platform resolver's, mirrored rather than
+ * reinvented (`flow-schema/src/ref-resolver/`), because a file the platform
+ * reads one way and the SDK another is worse than no support at all:
+ *
+ *  - **`$ref` replaces the whole object.** JSON Reference, not JSON Schema —
+ *    sibling properties beside a `$ref` are dropped, not merged.
+ *  - **Same-document fragments (`#/…`) are left ALONE.** They are legitimate
+ *    internal pointers — a connector tool's `outputSchema` carries them — and
+ *    they are not file references. Resolving them as filenames is the exact
+ *    regression the platform's own guard exists to prevent.
+ *  - **Relative paths only.** Absolute paths, Windows drive letters, protocol
+ *    URIs and traversal above the referencing file's root are REFUSED, because
+ *    a `.flow` is untrusted input and the alternative is a file-exfiltration
+ *    primitive (`$ref: '/etc/passwd'`, `$ref: 'https://…'`).
+ *  - **Any depth**, and resolved content is walked again for its own refs.
+ *
+ * Where this deliberately differs: an unresolvable ref is an ERROR here, not a
+ * warning. The platform's resolver collects non-fatal errors because a canvas
+ * can render a partial document and let a person fix it; decompile turns the
+ * document into SOURCE, and a silently-missing subtree becomes source that
+ * compiles to a different flow. Failing names the file that is missing.
+ */
+/** How this module reads a sibling file. Injected so it is testable and so the
+ * SDK core stays free of `node:fs`. */
+export type RefReader = (resolvedPath: string) => string;
+export interface ResolveRefsOptions {
+    /**
+     * The referencing document's own path — `$ref`s resolve against its
+     * DIRECTORY. May be project-relative (`project/main.flow`), POSIX absolute,
+     * or Windows absolute (backslashes are normalized).
+     */
+    baseUri: string;
+    /** Reads a sibling file's text, by resolved path. */
+    read: RefReader;
+    /** Recursion ceiling, mirroring the platform's own. Defaults to 10. */
+    maxDepth?: number;
+}
+/**
+ * Resolve one `$ref` value against the referencing file, refusing everything
+ * the platform refuses (see the module note for why each is refused).
+ */
+export declare function resolveRefPath(baseUri: string, refPath: string): string;
+/**
+ * Resolve every local-file `$ref` in `doc` into one object model.
+ *
+ * ```ts
+ * const raw = JSON.parse(readFileSync('Main.flow', 'utf8'));
+ * const flow = resolveFlowRefs(raw, {
+ *   baseUri: 'Main.flow',
+ *   read: (p) => readFileSync(p, 'utf8'),
+ * });
+ * ```
+ *
+ * @param doc - The parsed document, straight from the main file.
+ * @param options - The referencing path, the file reader, and the depth cap.
+ * @returns The same document with every resolvable `$ref` replaced in place
+ * (a new object; the input is not mutated).
+ * @throws If a `$ref` is unreadable, circular, over the depth cap, or names a
+ * path the format refuses.
+ */
+export declare function resolveFlowRefs(doc: unknown, options: ResolveRefsOptions): unknown;
+/** True if `doc` contains any local-file `$ref` — i.e. it is a SPLIT document. */
+export declare function hasFileRefs(doc: unknown): boolean;

package/dist/ref-resolve.js

@@ -0,0 +1,170 @@
+/**
+ * `$ref` resolution for SPLIT `.flow` files (design §5, Phase 5E).
+ *
+ * The format lets a `.flow` be split across sibling files with JSON Reference
+ * (`{ "$ref": "./layout.json" }`) — used to sideline layout or definitions, or
+ * to extract a subflow out of an oversized file
+ * (`flow-schema/REF_RESOLUTION.md`, MST-8579). Decompile has to READ those, so
+ * this resolves them into ONE object model before anything else looks at the
+ * document.
+ *
+ * Compile keeps writing a single file, deliberately: nothing in the designer or
+ * the skills splits files today, so write-through splitting would be a merge
+ * concern with no producer to round-trip against.
+ *
+ * The semantics below are the platform resolver's, mirrored rather than
+ * reinvented (`flow-schema/src/ref-resolver/`), because a file the platform
+ * reads one way and the SDK another is worse than no support at all:
+ *
+ *  - **`$ref` replaces the whole object.** JSON Reference, not JSON Schema —
+ *    sibling properties beside a `$ref` are dropped, not merged.
+ *  - **Same-document fragments (`#/…`) are left ALONE.** They are legitimate
+ *    internal pointers — a connector tool's `outputSchema` carries them — and
+ *    they are not file references. Resolving them as filenames is the exact
+ *    regression the platform's own guard exists to prevent.
+ *  - **Relative paths only.** Absolute paths, Windows drive letters, protocol
+ *    URIs and traversal above the referencing file's root are REFUSED, because
+ *    a `.flow` is untrusted input and the alternative is a file-exfiltration
+ *    primitive (`$ref: '/etc/passwd'`, `$ref: 'https://…'`).
+ *  - **Any depth**, and resolved content is walked again for its own refs.
+ *
+ * Where this deliberately differs: an unresolvable ref is an ERROR here, not a
+ * warning. The platform's resolver collects non-fatal errors because a canvas
+ * can render a partial document and let a person fix it; decompile turns the
+ * document into SOURCE, and a silently-missing subtree becomes source that
+ * compiles to a different flow. Failing names the file that is missing.
+ */
+/**
+ * Collapse `.` and `..` segments, preserving a leading `/` for POSIX absolute
+ * paths — the platform's `normalizePath`, same behavior.
+ */
+function normalizePath(path) {
+    const isAbsolute = path.startsWith('/');
+    const segments = path.split('/');
+    const result = [];
+    for (const segment of segments) {
+        if (segment === '' || segment === '.')
+            continue;
+        if (segment === '..' && result.length > 0 && result[result.length - 1] !== '..') {
+            result.pop();
+        }
+        else {
+            result.push(segment);
+        }
+    }
+    return (isAbsolute ? '/' : '') + result.join('/');
+}
+/**
+ * Resolve one `$ref` value against the referencing file, refusing everything
+ * the platform refuses (see the module note for why each is refused).
+ */
+export function resolveRefPath(baseUri, refPath) {
+    if (refPath.startsWith('#')) {
+        throw new Error(`$ref "${refPath}" is a same-document fragment, not a file — it must not be resolved as a path.`);
+    }
+    if (refPath.startsWith('/') || /^[a-zA-Z]:/.test(refPath)) {
+        throw new Error(`$ref "${refPath}" is an absolute path; only relative paths are allowed.`);
+    }
+    if (refPath.includes('://')) {
+        throw new Error(`$ref "${refPath}" is a protocol URI; only relative file paths are allowed.`);
+    }
+    const normalizedBase = baseUri.replace(/\\/g, '/');
+    const lastSlash = normalizedBase.lastIndexOf('/');
+    const baseDir = lastSlash >= 0 ? normalizedBase.slice(0, lastSlash + 1) : '';
+    const resolved = normalizePath(`${baseDir}${refPath}`);
+    const isAbsoluteBase = normalizedBase.startsWith('/') || /^[a-zA-Z]:\//.test(normalizedBase);
+    if (!isAbsoluteBase && resolved.startsWith('..')) {
+        throw new Error(`$ref "${refPath}" escapes the project root.`);
+    }
+    return resolved;
+}
+/** True for `{ $ref: '<string>' }` — the only shape JSON Reference defines. */
+function isRefObject(value) {
+    return (typeof value === 'object' && value !== null && !Array.isArray(value)
+        && typeof value.$ref === 'string');
+}
+/**
+ * Resolve every local-file `$ref` in `doc` into one object model.
+ *
+ * ```ts
+ * const raw = JSON.parse(readFileSync('Main.flow', 'utf8'));
+ * const flow = resolveFlowRefs(raw, {
+ *   baseUri: 'Main.flow',
+ *   read: (p) => readFileSync(p, 'utf8'),
+ * });
+ * ```
+ *
+ * @param doc - The parsed document, straight from the main file.
+ * @param options - The referencing path, the file reader, and the depth cap.
+ * @returns The same document with every resolvable `$ref` replaced in place
+ * (a new object; the input is not mutated).
+ * @throws If a `$ref` is unreadable, circular, over the depth cap, or names a
+ * path the format refuses.
+ */
+export function resolveFlowRefs(doc, options) {
+    const maxDepth = options.maxDepth ?? 10;
+    // The chain of files currently being resolved — a file that references
+    // itself, directly or through others, would otherwise recurse forever.
+    const visiting = new Set();
+    const walk = (node, baseUri, depth, where) => {
+        if (Array.isArray(node))
+            return node.map((v, i) => walk(v, baseUri, depth, `${where}/${i}`));
+        if (isRefObject(node)) {
+            // A same-document pointer is not ours to resolve — hand it back untouched
+            // for the JSON-Schema consumer downstream.
+            if (node.$ref.startsWith('#'))
+                return node;
+            if (depth >= maxDepth) {
+                throw new Error(`$ref resolution exceeded ${maxDepth} levels at ${where} ("${node.$ref}").`);
+            }
+            const path = resolveRefPath(baseUri, node.$ref);
+            if (visiting.has(path)) {
+                throw new Error(`Circular $ref at ${where}: "${node.$ref}" is already being resolved.`);
+            }
+            let text;
+            try {
+                text = options.read(path);
+            }
+            catch (err) {
+                const why = err instanceof Error ? err.message : String(err);
+                throw new Error(`$ref at ${where} points at "${node.$ref}", which could not be read (${why}).`);
+            }
+            let parsed;
+            try {
+                parsed = JSON.parse(text);
+            }
+            catch (err) {
+                const why = err instanceof Error ? err.message : String(err);
+                throw new Error(`$ref at ${where} points at "${node.$ref}", which is not valid JSON (${why}).`);
+            }
+            visiting.add(path);
+            try {
+                // The referenced file's OWN refs resolve against ITS location, not the
+                // referrer's — a sidecar may point at a sibling of its own.
+                return walk(parsed, path, depth + 1, where);
+            }
+            finally {
+                visiting.delete(path);
+            }
+        }
+        if (typeof node === 'object' && node !== null) {
+            const out = {};
+            for (const [k, v] of Object.entries(node)) {
+                out[k] = walk(v, baseUri, depth, `${where}/${k}`);
+            }
+            return out;
+        }
+        return node;
+    };
+    return walk(doc, options.baseUri, 0, '');
+}
+/** True if `doc` contains any local-file `$ref` — i.e. it is a SPLIT document. */
+export function hasFileRefs(doc) {
+    if (Array.isArray(doc))
+        return doc.some(hasFileRefs);
+    if (isRefObject(doc) && !doc.$ref.startsWith('#'))
+        return true;
+    if (typeof doc === 'object' && doc !== null)
+        return Object.values(doc).some(hasFileRefs);
+    return false;
+}

package/dist/registry/cache.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Where the connector library lives.
+ *
+ * One shared copy per machine, not one per project. The extracted `library-json`
+ * and the generated `library-md` are a pure function of the archive plus the
+ * SDK's curated corrections. Two projects pulling the same inputs produce
+ * byte-identical trees, so duplicating 159 MB into every project bought nothing.
+ * They are cached by a hash of both inputs, and `current` names the entry the
+ * next compile should use.
+ *
+ *     <root>/<archive-sha256>.zip              the downloaded archive
+ *     <root>/<library-sha256>/library-json/    extracted + curated
+ *     <root>/<library-sha256>/library-md/      generated
+ *     <root>/current -> <library-sha256>       moved by the last `registry pull`
+ *
+ * Only `connectors/` and `connectors-local/` stay in a project: the first
+ * because an author imports it by relative path, the second because a
+ * connection-resolved schema belongs to the tenant it came from, not the
+ * machine.
+ */
+export declare const LIBRARY_JSON_DIR = "library-json";
+export declare const LIBRARY_MARKDOWN_DIR = "library-md";
+export declare const CURRENT_LINK = "current";
+/**
+ * Root of the library cache. `UIP_FLOW_SDK_LIBRARY_CACHE` overrides it.
+ *
+ * An environment variable and no flag, on purpose. The writer and the readers
+ * are different processes: `registry pull` fills the cache, while this package's
+ * own compile and `uip maestro flow compile` (which carries its own copy of this
+ * resolution) read it. A flag can only reach the one process it was typed on, so
+ * `pull --cache /tmp/x` would leave `current` in a directory no reader ever
+ * looks at — the pull reports success and the next compile finds no library.
+ * There was such a flag; it is gone. Use this variable to relocate the cache,
+ * or `--library`/`--library-md` to bypass it entirely for one command.
+ */
+export declare function libraryCacheRoot(): string;
+export declare function cacheEntry(sha256: string, root?: string): string;
+/**
+ * The `library-json` the next compile should use, or undefined when nothing has
+ * been pulled yet. Resolved through `current` so a pull updates every project at
+ * once.
+ */
+export declare function resolveCachedLibrary(root?: string): string | undefined;
+/** The matching `library-md`, for an agent that wants to read rather than compile. */
+export declare function resolveCachedMarkdown(root?: string): string | undefined;
+/**
+ * The library a command should use: what the caller named, else the environment,
+ * else the cache. Every compile entry point resolves through this so `pull` and
+ * `compile` cannot disagree about where the library is — they did, and a library
+ * written by `pull` was invisible to the SDK's own compile.
+ */
+export declare function resolveLibraryDir(named?: string): string | undefined;
+/** What `current` points at, for reporting. */
+export declare function currentEntrySha(root?: string): string | undefined;
+export declare function referencedConnectorKeys(projectDir: string): string[];

package/dist/registry/cache.js

@@ -0,0 +1,134 @@
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+/**
+ * Where the connector library lives.
+ *
+ * One shared copy per machine, not one per project. The extracted `library-json`
+ * and the generated `library-md` are a pure function of the archive plus the
+ * SDK's curated corrections. Two projects pulling the same inputs produce
+ * byte-identical trees, so duplicating 159 MB into every project bought nothing.
+ * They are cached by a hash of both inputs, and `current` names the entry the
+ * next compile should use.
+ *
+ *     <root>/<archive-sha256>.zip              the downloaded archive
+ *     <root>/<library-sha256>/library-json/    extracted + curated
+ *     <root>/<library-sha256>/library-md/      generated
+ *     <root>/current -> <library-sha256>       moved by the last `registry pull`
+ *
+ * Only `connectors/` and `connectors-local/` stay in a project: the first
+ * because an author imports it by relative path, the second because a
+ * connection-resolved schema belongs to the tenant it came from, not the
+ * machine.
+ */
+export const LIBRARY_JSON_DIR = "library-json";
+export const LIBRARY_MARKDOWN_DIR = "library-md";
+export const CURRENT_LINK = "current";
+/**
+ * Root of the library cache. `UIP_FLOW_SDK_LIBRARY_CACHE` overrides it.
+ *
+ * An environment variable and no flag, on purpose. The writer and the readers
+ * are different processes: `registry pull` fills the cache, while this package's
+ * own compile and `uip maestro flow compile` (which carries its own copy of this
+ * resolution) read it. A flag can only reach the one process it was typed on, so
+ * `pull --cache /tmp/x` would leave `current` in a directory no reader ever
+ * looks at — the pull reports success and the next compile finds no library.
+ * There was such a flag; it is gone. Use this variable to relocate the cache,
+ * or `--library`/`--library-md` to bypass it entirely for one command.
+ */
+export function libraryCacheRoot() {
+    return (process.env.UIP_FLOW_SDK_LIBRARY_CACHE ||
+        join(homedir(), ".uipath", "cache", "flow-sdk", "library"));
+}
+export function cacheEntry(sha256, root = libraryCacheRoot()) {
+    return join(root, sha256);
+}
+/** A directory is a usable library only once its index has landed. */
+function hasIndex(dir) {
+    return existsSync(join(dir, "index.json"));
+}
+/**
+ * The `library-json` the next compile should use, or undefined when nothing has
+ * been pulled yet. Resolved through `current` so a pull updates every project at
+ * once.
+ */
+export function resolveCachedLibrary(root = libraryCacheRoot()) {
+    const dir = join(root, CURRENT_LINK, LIBRARY_JSON_DIR);
+    return hasIndex(dir) ? dir : undefined;
+}
+/** The matching `library-md`, for an agent that wants to read rather than compile. */
+export function resolveCachedMarkdown(root = libraryCacheRoot()) {
+    const dir = join(root, CURRENT_LINK, LIBRARY_MARKDOWN_DIR);
+    return hasIndex(dir) ? dir : undefined;
+}
+/**
+ * The library a command should use: what the caller named, else the environment,
+ * else the cache. Every compile entry point resolves through this so `pull` and
+ * `compile` cannot disagree about where the library is — they did, and a library
+ * written by `pull` was invisible to the SDK's own compile.
+ */
+export function resolveLibraryDir(named) {
+    return named ?? process.env.FLOW_SDK_LIBRARY_JSON ?? resolveCachedLibrary();
+}
+/** What `current` points at, for reporting. */
+export function currentEntrySha(root = libraryCacheRoot()) {
+    const link = join(root, CURRENT_LINK);
+    try {
+        if (!statSync(link).isDirectory())
+            return undefined;
+    }
+    catch {
+        return undefined;
+    }
+    const source = join(link, LIBRARY_JSON_DIR, ".registry-source.json");
+    if (!existsSync(source))
+        return undefined;
+    try {
+        const parsed = JSON.parse(readFileSync(source, "utf8"));
+        return typeof parsed.sha256 === "string" ? parsed.sha256 : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Connector keys a project actually authors against.
+ *
+ * Read so `pull` can generate only the descriptors that will be imported. The
+ * full set is 30 modules and 1.1 MB, of which a Slack project uses 32 KB; the
+ * rest is weight in someone's repository for operations they never call.
+ *
+ * Both authoring forms count: the typed import names the module by file, and the
+ * string form names the connector as the first argument.
+ */
+const IMPORT_FORM = /connectors(?:-local)?\/([a-z0-9][a-z0-9-]*)\.ts/g;
+const STRING_FORM = /\bconnector\(\s*['"]([a-z0-9][a-z0-9-]*)['"]/g;
+const AUTHORED = /\.(flow|case|bpmn)\.ts$/;
+export function referencedConnectorKeys(projectDir) {
+    const found = new Set();
+    let entries;
+    try {
+        entries = readdirSync(projectDir);
+    }
+    catch {
+        return [];
+    }
+    for (const entry of entries) {
+        if (!AUTHORED.test(entry))
+            continue;
+        let source;
+        try {
+            source = readFileSync(join(projectDir, entry), "utf8");
+        }
+        catch {
+            continue;
+        }
+        for (const pattern of [IMPORT_FORM, STRING_FORM]) {
+            pattern.lastIndex = 0;
+            for (let match = pattern.exec(source); match; match = pattern.exec(source)) {
+                found.add(match[1]);
+            }
+        }
+    }
+    return [...found].sort();
+}

package/dist/registry/curated-overlay.d.ts

@@ -0,0 +1,16 @@
+/** The corrections and definitions that the raw registry dump does not carry. */
+export declare function bundledOverlayPath(): string;
+/** Stable identity of the curated data, so a changed overlay gets a new cache entry. */
+export declare function curatedOverlayIdentity(overlayPath?: string): Promise<string>;
+/**
+ * Apply the SDK's curated corrections after extracting the raw registry dump.
+ *
+ * Files replace the dump's copy, while index rows are a union where the dump
+ * wins collisions. This is the same contract as the former unpack script: a
+ * correction changes the referenced file, and a definition absent from the
+ * dump (notably connector triggers) is made resolvable by its added index row.
+ */
+export declare function applyCuratedOverlay(libraryPath: string, overlayPath?: string): Promise<{
+    files: number;
+    entries: number;
+}>;

package/dist/registry/curated-overlay.js

@@ -0,0 +1,62 @@
+import { createHash } from "node:crypto";
+import { cp, mkdir, readdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join, relative } from "node:path";
+import { fileURLToPath } from "node:url";
+/** The corrections and definitions that the raw registry dump does not carry. */
+export function bundledOverlayPath() {
+    return fileURLToPath(new URL("../../lib/library-json.samples", import.meta.url));
+}
+async function jsonFiles(root, directory = root) {
+    const entries = await readdir(directory, { withFileTypes: true });
+    const files = await Promise.all(entries.map(async (entry) => {
+        const path = join(directory, entry.name);
+        if (entry.isDirectory())
+            return jsonFiles(root, path);
+        return entry.isFile() && entry.name.endsWith(".json") ? [path] : [];
+    }));
+    return files.flat().sort((left, right) => relative(root, left).localeCompare(relative(root, right)));
+}
+/** Stable identity of the curated data, so a changed overlay gets a new cache entry. */
+export async function curatedOverlayIdentity(overlayPath = bundledOverlayPath()) {
+    const hash = createHash("sha256");
+    for (const path of await jsonFiles(overlayPath)) {
+        hash.update(relative(overlayPath, path));
+        hash.update("\0");
+        hash.update(await readFile(path));
+        hash.update("\0");
+    }
+    return hash.digest("hex");
+}
+function entryIdentity(entry) {
+    return `${String(entry.nodeType)}\0${String(entry.version)}`;
+}
+/**
+ * Apply the SDK's curated corrections after extracting the raw registry dump.
+ *
+ * Files replace the dump's copy, while index rows are a union where the dump
+ * wins collisions. This is the same contract as the former unpack script: a
+ * correction changes the referenced file, and a definition absent from the
+ * dump (notably connector triggers) is made resolvable by its added index row.
+ */
+export async function applyCuratedOverlay(libraryPath, overlayPath = bundledOverlayPath()) {
+    const overlayFiles = await jsonFiles(overlayPath);
+    for (const source of overlayFiles) {
+        const rel = relative(overlayPath, source);
+        if (rel === "index.json")
+            continue;
+        const destination = join(libraryPath, rel);
+        await mkdir(dirname(destination), { recursive: true });
+        await cp(source, destination);
+    }
+    const indexPath = join(libraryPath, "index.json");
+    const destination = JSON.parse(await readFile(indexPath, "utf8"));
+    const overlay = JSON.parse(await readFile(join(overlayPath, "index.json"), "utf8"));
+    const entries = destination.entries ?? [];
+    const seen = new Set(entries.map(entryIdentity));
+    const additions = (overlay.entries ?? []).filter((entry) => !seen.has(entryIdentity(entry)));
+    if (additions.length > 0) {
+        destination.entries = [...entries, ...additions];
+        await writeFile(indexPath, `${JSON.stringify(destination, null, 2)}\n`);
+    }
+    return { files: overlayFiles.length - 1, entries: additions.length };
+}

package/dist/registry/extractor.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Unpack a downloaded connector-library archive.
+ *
+ * Python does the unpacking: `zipfile` is in its standard library, and this is
+ * the only step of the pull that needs an archive reader. Adding the SDK's first
+ * zip dependency to avoid one subprocess would be the worse trade, especially
+ * for code whose whole job is refusing hostile paths — `extract_library.py`
+ * carries that guard and its tests.
+ *
+ * Shaped like `materializer.ts` on purpose: same generator-path
+ * resolution, same `--python` override, same failure translation.
+ */
+export interface ExtractLibraryOptions {
+    archivePath: string;
+    destinationPath: string;
+    /** Only entries under this zip prefix are taken. */
+    root?: string;
+    pythonExecutable?: string;
+    /** Override used by tests and source checkouts. */
+    extractorPath?: string;
+}
+export declare function extractLibrary(options: ExtractLibraryOptions): Promise<void>;

package/dist/registry/extractor.js

@@ -0,0 +1,18 @@
+import { packagedGenerator, runGenerator } from "./python.js";
+export async function extractLibrary(options) {
+    const args = [
+        "--archive",
+        options.archivePath,
+        "--into",
+        options.destinationPath,
+    ];
+    if (options.root) {
+        args.push("--root", options.root);
+    }
+    await runGenerator({
+        script: options.extractorPath ?? packagedGenerator("extract_library.py"),
+        args,
+        pythonExecutable: options.pythonExecutable,
+        what: "Unpacking the connector library",
+    });
+}

package/dist/registry/materialize-bin.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/registry/materialize-bin.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+// The `flow-registry-materialize` bin. Kept as a separate entry file so
+// `materialize-cli.ts` can stay a plain `run(argv)` module that the
+// umbrella CLI mounts. Exit codes are identical to the pre-refactor script:
+// 2 for a usage error, 1 for a failed generation, 0 on success.
+import { run } from "./materialize-cli.js";
+process.exitCode = await run(process.argv.slice(2));

package/dist/registry/materialize-cli.d.ts

@@ -0,0 +1 @@
+export declare function run(argv: string[]): Promise<number>;

package/dist/registry/materialize-cli.js

@@ -0,0 +1,46 @@
+import { materializeRegistry } from "./materializer.js";
+/**
+ * Generate `library-md` and `connectors/` from an extracted `library-json`.
+ *
+ * Exposed as `run(argv)` rather than as a top-level script so the umbrella CLI
+ * can mount it the same way it mounts every other verb: `cli/common.ts` does
+ * `(await import(...)).run(argv)` and maps the returned code onto
+ * `process.exitCode`. A module that read `process.argv` and called
+ * `process.exit` at import time could not be mounted at all — which is why
+ * this verb used to be reachable only through its own bin, and why the product
+ * CLI had to resolve that bin out of the package's `bin` map instead of
+ * delegating to `dist/cli/index.js` like it does for compile and check.
+ *
+ * The bin still works: `materialize-bin.ts` is a two-line shim over
+ * this function, so both entry points share one implementation.
+ */
+const USAGE = "Usage: flow-sdk registry materialize --library-json <path> --library-md <path> --connectors <path> [--import <specifier>] [--triggers <path>] [--python <executable>] [--generator <path>]";
+function value(args, name) {
+    const index = args.indexOf(name);
+    return index >= 0 ? args[index + 1] : undefined;
+}
+export async function run(argv) {
+    const libraryJsonPath = value(argv, "--library-json");
+    const libraryMarkdownPath = value(argv, "--library-md");
+    const connectorsPath = value(argv, "--connectors");
+    if (!libraryJsonPath || !libraryMarkdownPath || !connectorsPath) {
+        console.error(USAGE);
+        return 2;
+    }
+    try {
+        await materializeRegistry({
+            libraryJsonPath,
+            libraryMarkdownPath,
+            connectorsPath,
+            connectorImport: value(argv, "--import"),
+            pythonExecutable: value(argv, "--python"),
+            triggersPath: value(argv, "--triggers"),
+            generatorPath: value(argv, "--generator"),
+        });
+        return 0;
+    }
+    catch (error) {
+        console.error(error instanceof Error ? error.message : String(error));
+        return 1;
+    }
+}

package/dist/registry/materializer.d.ts

@@ -0,0 +1,23 @@
+export interface MaterializeRegistryOptions {
+    libraryJsonPath: string;
+    /** Where the Markdown goes. Omit to skip it — see `connectorsPath`. */
+    libraryMarkdownPath?: string;
+    /**
+     * Where the typed descriptors go. Omit to generate none — every error the
+     * compiler reports comes from the library JSON, so the modules are for an
+     * editor's autocomplete rather than for validation, and a project that imports
+     * none does not need them.
+     */
+    connectorsPath?: string;
+    /**
+     * Connector keys to emit, instead of all of them. The full set is 30 modules
+     * and 1.1 MB; a project usually imports one.
+     */
+    connectorSubset?: string[];
+    connectorImport?: string;
+    pythonExecutable?: string;
+    triggersPath?: string;
+    /** Override used by tests and source checkouts. */
+    generatorPath?: string;
+}
+export declare function materializeRegistry(options: MaterializeRegistryOptions): Promise<void>;