@uipath/maestro-builder-sdk 5.2.0

package/dist/registry/materializer.js

@@ -0,0 +1,34 @@
+import { packagedGenerator, runGenerator } from "./python.js";
+import { applyCuratedOverlay } from "./curated-overlay.js";
+import { PACKAGE_NAME } from "../package-name.js";
+export async function materializeRegistry(options) {
+    // The product CLI downloads the raw registry archive and delegates directly
+    // to this API. Apply the SDK's curated corrections here so every caller gets
+    // the same resolvable library as the standalone flow-sdk pull command,
+    // including connector start-trigger definitions absent from the raw dump.
+    await applyCuratedOverlay(options.libraryJsonPath);
+    const args = [
+        "--library-json",
+        options.libraryJsonPath,
+        "--import",
+        options.connectorImport ?? PACKAGE_NAME,
+    ];
+    if (options.libraryMarkdownPath) {
+        args.push("--library-md", options.libraryMarkdownPath);
+    }
+    if (options.connectorsPath) {
+        args.push("--connectors", options.connectorsPath);
+    }
+    if (options.connectorSubset && options.connectorSubset.length > 0) {
+        args.push("--connector-subset", options.connectorSubset.join(","));
+    }
+    if (options.triggersPath) {
+        args.push("--triggers", options.triggersPath);
+    }
+    await runGenerator({
+        script: options.generatorPath ?? packagedGenerator("materialize_registry.py"),
+        args,
+        pythonExecutable: options.pythonExecutable,
+        what: "Registry materialization",
+    });
+}

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

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

package/dist/registry/path-cli.js

@@ -0,0 +1,56 @@
+import { join } from "node:path";
+import { CURRENT_LINK, currentEntrySha, libraryCacheRoot, resolveCachedLibrary, resolveCachedMarkdown, } from "./cache.js";
+/**
+ * Say where the connector library is.
+ *
+ * The library moved out of the project into a shared cache, which means a script
+ * or an agent can no longer assume `./library`. Something has to answer "where is
+ * it", and printing a bare path is what makes that usable from a shell:
+ *
+ *     FLOW_SDK_LIBRARY_MD="$(npx flow-sdk registry path --library-md)"
+ *
+ * `uip maestro registry path` reported the same thing before it was removed;
+ * this is its replacement, on the CLI that now owns the library.
+ */
+const USAGE = [
+    "Usage: flow-sdk registry path [--library-json | --library-md | --root | --sha]",
+    "",
+    "  With no flag, prints all of them as JSON. With one, prints just that value,",
+    "  unquoted, for use in a shell.",
+].join("\n");
+export async function run(argv) {
+    if (argv.includes("--help") || argv.includes("-h")) {
+        console.log(USAGE);
+        return 0;
+    }
+    const root = libraryCacheRoot();
+    const libraryJson = resolveCachedLibrary();
+    const libraryMarkdown = resolveCachedMarkdown();
+    const sha256 = currentEntrySha();
+    const single = (value) => {
+        if (!value) {
+            console.error("No connector library in the cache yet. Run `flow-sdk registry pull`.");
+            return 1;
+        }
+        console.log(value);
+        return 0;
+    };
+    if (argv.includes("--library-json"))
+        return single(libraryJson);
+    if (argv.includes("--library-md"))
+        return single(libraryMarkdown);
+    if (argv.includes("--root"))
+        return single(root);
+    if (argv.includes("--sha"))
+        return single(sha256);
+    console.log(JSON.stringify({
+        root,
+        current: join(root, CURRENT_LINK),
+        sha256: sha256 ?? null,
+        libraryJson: libraryJson ?? null,
+        libraryMarkdown: libraryMarkdown ?? null,
+    }, null, 2));
+    // Not an error: a caller asking for the whole picture is entitled to be told
+    // the cache is empty, rather than getting a non-zero exit for a plain report.
+    return 0;
+}

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

@@ -0,0 +1,62 @@
+/**
+ * Fetch one operation's connection-resolved schema into a local overlay.
+ *
+ * The published library is tenant-agnostic, which is what lets it ship — and
+ * also what it cannot know: a Salesforce custom object, the fields a Jira
+ * project and issue type select, a ServiceNow table that exists on one tenant.
+ * Those need a connection, so they cannot be in the archive `pull` downloads.
+ *
+ * This writes what the archive is missing into `./connectors-local/`, which the
+ * compilers pick up on their own and union over the library — it can add fields,
+ * never remove ones that already worked. Without it a connector whose schema
+ * depends on a connection cannot be compiled at all: the fields discovered from
+ * a live `describe` have nowhere to go, and `compile` rejects them as unknown.
+ *
+ * Needs the `uip` CLI on PATH and logged in. The tenant calls go through it —
+ * `uip maestro flow registry get`, `uip is resources list/describe` — because
+ * `uip` is the tenant client and this only orchestrates it.
+ */
+export interface PrepareConnectorOptions {
+    connectorKey: string;
+    action: string;
+    /** Omit to discover it from `uip is connections list`. */
+    connectionId?: string;
+    /** Pick the connection by name when several match. */
+    connection?: string;
+    /** bindings file to add the discovered connection to. */
+    bindings?: string;
+    bindConnection?: string;
+    bindFolder?: string;
+    noBindings?: boolean;
+    /** One connection-discovered object, for a Generic action. */
+    objectName?: string;
+    /** Every connection-discovered object. Mutually exclusive with objectName. */
+    allObjects?: boolean;
+    /** Parent-field values that select the schema, as `name=value`. */
+    fields?: string[];
+    /** Lookup resolutions, as `field:by=value`. Repeatable. */
+    resolve?: string[];
+    /** Re-resolve lookups already recorded, instead of leaving them alone. */
+    refreshLookups?: boolean;
+    outPath?: string;
+    version?: string;
+    connectorImport?: string;
+    jsonOnly?: boolean;
+    /** The `.flow.ts` whose import should be repointed at the prepared descriptor. */
+    source?: string;
+    /** Print the import line instead of editing the source. */
+    noSourceRewrite?: boolean;
+    pythonExecutable?: string;
+    /** Override used by tests and source checkouts. */
+    generatorPath?: string;
+}
+/** The generator's argv for these options. Exported to be tested directly. */
+export declare function generatorArgs(options: PrepareConnectorOptions): string[];
+export declare function prepareConnector(options: PrepareConnectorOptions): Promise<void>;
+/**
+ * Options for this argv, or null when it does not name a connector, an action
+ * and a connection. Split out from `run` so the parsing can be tested without
+ * an interpreter.
+ */
+export declare function parseArgs(argv: string[]): PrepareConnectorOptions | null;
+export declare function run(argv: string[]): Promise<number>;

package/dist/registry/prepare-cli.js

@@ -0,0 +1,185 @@
+import { packagedGenerator, runGenerator } from "./python.js";
+import { PACKAGE_NAME } from "../package-name.js";
+// This mirrors the generator's own flags one for one, so a `--version` here is
+// the connector's version, not the package's. The umbrella CLI spells that
+// `--connector-version`, because commander's program-level version option
+// shadows a subcommand's; it translates before calling `run`.
+/** What a generated descriptor imports from. The generator's own default is a
+ * relative path that only resolves inside a source checkout. */
+const DEFAULT_CONNECTOR_IMPORT = PACKAGE_NAME;
+const USAGE = [
+    "Usage: flow-sdk registry prepare <connector-key> <action> [--connection-id <id>]",
+    "                                [--connection <name>] [--bindings <file>] [--no-bindings]",
+    "                                [--object <name> | --all-objects] [-f NAME=VALUE ...]",
+    "                                [--resolve FIELD:BY=VALUE ...] [--refresh-lookups]",
+    "                                [--out <dir>] [--version <v>] [--import <specifier>]",
+    "                                [--json-only] [--source <flow.ts>] [--no-source-rewrite]",
+    "                                [--python <exe>]",
+].join("\n");
+/** The generator's argv for these options. Exported to be tested directly. */
+export function generatorArgs(options) {
+    const args = [options.connectorKey, options.action];
+    if (options.connectionId)
+        args.push("--connection-id", options.connectionId);
+    if (options.connection)
+        args.push("--connection", options.connection);
+    if (options.bindings)
+        args.push("--bindings", options.bindings);
+    if (options.bindConnection)
+        args.push("--bind-connection", options.bindConnection);
+    if (options.bindFolder)
+        args.push("--bind-folder", options.bindFolder);
+    if (options.noBindings)
+        args.push("--no-bindings");
+    if (options.objectName)
+        args.push("--object", options.objectName);
+    if (options.allObjects)
+        args.push("--all-objects");
+    for (const field of options.fields ?? [])
+        args.push("-f", field);
+    for (const one of options.resolve ?? [])
+        args.push("--resolve", one);
+    if (options.refreshLookups)
+        args.push("--refresh-lookups");
+    if (options.outPath)
+        args.push("--out", options.outPath);
+    if (options.version)
+        args.push("--version", options.version);
+    // Always sent, because the generator's own default is `../sdk/flow-sdk.js` —
+    // a relative path that resolves in the eval image's checkout and nowhere else.
+    // The legacy `prepare-connector` shim hard-coded this; nothing else does, so
+    // omitting it emits a descriptor whose import line resolves to nothing.
+    // Matches materializer.ts, which defaults the same specifier.
+    args.push("--import", options.connectorImport ?? DEFAULT_CONNECTOR_IMPORT);
+    if (options.jsonOnly)
+        args.push("--json-only");
+    if (options.source)
+        args.push("--source", options.source);
+    if (options.noSourceRewrite)
+        args.push("--no-source-rewrite");
+    return args;
+}
+export async function prepareConnector(options) {
+    const args = generatorArgs(options);
+    await runGenerator({
+        script: options.generatorPath ?? packagedGenerator("prepare_connector.py"),
+        args,
+        pythonExecutable: options.pythonExecutable,
+        what: "Preparing the connector",
+    });
+}
+function value(args, name) {
+    const index = args.indexOf(name);
+    return index >= 0 ? args[index + 1] : undefined;
+}
+/** Every value given for a repeatable flag, in order. */
+function repeated(args, name) {
+    const collected = [];
+    args.forEach((arg, index) => {
+        if (arg === name) {
+            const next = args[index + 1];
+            if (next !== undefined)
+                collected.push(next);
+        }
+    });
+    return collected;
+}
+/** Every `-f`/`--field` value, in the order given — the flag repeats. */
+function fields(args) {
+    const collected = [];
+    args.forEach((arg, index) => {
+        if (arg === "-f" || arg === "--field") {
+            const next = args[index + 1];
+            if (next !== undefined)
+                collected.push(next);
+        }
+    });
+    return collected;
+}
+/**
+ * Options for this argv, or null when it does not name a connector, an action
+ * and a connection. Split out from `run` so the parsing can be tested without
+ * an interpreter.
+ */
+export function parseArgs(argv) {
+    // The two positionals are whatever is left once flags and their values are
+    // accounted for, so they can appear before or after the flags.
+    const consumed = new Set();
+    for (const name of [
+        "--connection-id",
+        "--connection",
+        "--bindings",
+        "--bind-connection",
+        "--bind-folder",
+        "--object",
+        "--out",
+        "--version",
+        "--import",
+        "--source",
+        "--python",
+        "--generator",
+        "-f",
+        "--field",
+        "--resolve",
+    ]) {
+        argv.forEach((arg, index) => {
+            if (arg === name) {
+                consumed.add(index);
+                consumed.add(index + 1);
+            }
+        });
+    }
+    ["--all-objects", "--json-only", "--refresh-lookups", "--no-bindings",
+        "--no-source-rewrite"].forEach((flag) => {
+        const index = argv.indexOf(flag);
+        if (index >= 0)
+            consumed.add(index);
+    });
+    const positionals = argv.filter((_, index) => !consumed.has(index));
+    // `--connection-id` is no longer required: without one the generator
+    // discovers the connection itself and writes bindings.json.
+    if (positionals.length !== 2)
+        return null;
+    return {
+        connectorKey: positionals[0],
+        action: positionals[1],
+        connectionId: value(argv, "--connection-id"),
+        connection: value(argv, "--connection"),
+        bindings: value(argv, "--bindings"),
+        bindConnection: value(argv, "--bind-connection"),
+        bindFolder: value(argv, "--bind-folder"),
+        noBindings: argv.includes("--no-bindings"),
+        objectName: value(argv, "--object"),
+        allObjects: argv.includes("--all-objects"),
+        fields: fields(argv),
+        resolve: repeated(argv, "--resolve"),
+        refreshLookups: argv.includes("--refresh-lookups"),
+        outPath: value(argv, "--out"),
+        version: value(argv, "--version"),
+        connectorImport: value(argv, "--import"),
+        jsonOnly: argv.includes("--json-only"),
+        source: value(argv, "--source"),
+        noSourceRewrite: argv.includes("--no-source-rewrite"),
+        pythonExecutable: value(argv, "--python"),
+        generatorPath: value(argv, "--generator"),
+    };
+}
+export async function run(argv) {
+    if (argv.includes("--help") || argv.includes("-h")) {
+        console.log(USAGE);
+        return 0;
+    }
+    const options = parseArgs(argv);
+    if (!options) {
+        console.error(USAGE);
+        return 2;
+    }
+    try {
+        await prepareConnector(options);
+        return 0;
+    }
+    catch (error) {
+        console.error(error instanceof Error ? error.message : String(error));
+        return 1;
+    }
+}

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

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

package/dist/registry/pull-cli.js

@@ -0,0 +1,274 @@
+import { createHash } from "node:crypto";
+import { mkdir, readFile, rename, rm, stat, symlink, writeFile, } from "node:fs/promises";
+import { join } from "node:path";
+import { CURRENT_LINK, LIBRARY_JSON_DIR, LIBRARY_MARKDOWN_DIR, cacheEntry, libraryCacheRoot, referencedConnectorKeys, } from "./cache.js";
+import { extractLibrary } from "./extractor.js";
+import { materializeRegistry } from "./materializer.js";
+import { curatedOverlayIdentity } from "./curated-overlay.js";
+/**
+ * Fetch the published connector library into the shared cache, and generate the
+ * typed descriptors a project imports.
+ *
+ * The library and its markdown go to `~/.uipath/cache/flow-sdk/library/<sha256>/`
+ * and `current` is pointed at them, because both trees are a pure function of the
+ * archive plus this SDK version's curated corrections: two projects that pull
+ * the same inputs produce byte-identical output, so a copy per project cost
+ * 159 MB for nothing. A pull refreshes the one copy and every project sees it.
+ *
+ * The project gets only `connectors/`, and only for the connectors it actually
+ * references — an author imports those by relative path, so they cannot live in
+ * the cache, but the other 29 modules were never going to be imported either.
+ *
+ * `--library` and `--library-md` still name destinations, for a caller that wants
+ * the trees somewhere specific instead of in the cache.
+ */
+const DEFAULT_URL = "https://download.uipath.com/maestro/registry/library-json.zip";
+/** Provenance for a cache entry, written inside its library-json. */
+const SOURCE_FILE = ".registry-source.json";
+const USAGE = [
+    "Usage: flow-sdk registry pull [--connectors <dir>] [--connector <key>]...",
+    "                             [--library <dir>] [--library-md <dir>]",
+    "                             [--url <url>] [--archive <zip>] [--force]",
+    "                             [--import <specifier>] [--triggers <path>] [--python <exe>]",
+    "                             [--root <prefix>] [--extractor <path>] [--generator <path>]",
+].join("\n");
+function value(args, name) {
+    const index = args.indexOf(name);
+    return index >= 0 ? args[index + 1] : undefined;
+}
+function has(args, name) {
+    return args.includes(name);
+}
+/** Every `--connector` value; the flag repeats. */
+function repeated(args, name) {
+    const values = [];
+    args.forEach((arg, index) => {
+        if (arg === name && args[index + 1] !== undefined) {
+            values.push(args[index + 1]);
+        }
+    });
+    return values;
+}
+/** The sha256 a `.sha256` sidecar declares, rejecting anything that is not one. */
+function expectedChecksum(body) {
+    const hash = body.trim().split(/\s+/, 1)[0]?.toLowerCase();
+    if (!hash || !/^[a-f0-9]{64}$/.test(hash)) {
+        // A proxy or portal serving an HTML error page reaches here. Failing on the
+        // shape means that shows up as a bad checksum response rather than as a
+        // mismatch against a "hash" that was really a login page.
+        throw new Error("The connector library checksum response is not a sha256.");
+    }
+    return hash;
+}
+async function isFile(path) {
+    try {
+        return (await stat(path)).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+async function isDirectory(path) {
+    try {
+        return (await stat(path)).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+async function download(url) {
+    const response = await fetch(url);
+    if (!response.ok) {
+        throw new Error(`Could not download ${url}: HTTP ${response.status} ${response.statusText}`);
+    }
+    return new Uint8Array(await response.arrayBuffer());
+}
+/**
+ * Node's built-in fetch ignores HTTP(S)_PROXY unless told otherwise, and it
+ * fails in a way that looks like the server is down. Say so up front, and name
+ * both ways out, rather than let a proxied user debug a timeout.
+ */
+function warnAboutProxy() {
+    const proxy = process.env.HTTPS_PROXY ??
+        process.env.https_proxy ??
+        process.env.HTTP_PROXY ??
+        process.env.http_proxy;
+    if (!proxy)
+        return;
+    console.error(`registry pull: a proxy is set (${proxy}) and Node's fetch does not use it by default.\n` +
+        "  If the download fails, either run with NODE_USE_ENV_PROXY=1 (Node 24+),\n" +
+        "  or fetch the zip yourself and pass --archive <path>.");
+}
+async function resolveArchive(argv, cacheDir, force) {
+    const local = value(argv, "--archive");
+    if (local) {
+        // The caller's own file: no sidecar to check it against, and demanding one
+        // would defeat the escape hatch this exists to be. It is hashed anyway, so
+        // it still gets a cache entry of its own.
+        if (!(await isFile(local))) {
+            throw new Error(`No such archive: ${local}`);
+        }
+        return { path: local };
+    }
+    const url = value(argv, "--url") ?? DEFAULT_URL;
+    warnAboutProxy();
+    const checksumResponse = await fetch(`${url}.sha256`);
+    if (!checksumResponse.ok) {
+        throw new Error(`Could not download ${url}.sha256: HTTP ${checksumResponse.status} ${checksumResponse.statusText}`);
+    }
+    const expected = expectedChecksum(await checksumResponse.text());
+    await mkdir(cacheDir, { recursive: true });
+    const cached = join(cacheDir, `${expected}.zip`);
+    if (!force && (await isFile(cached))) {
+        console.error(`registry pull: reusing cached ${expected.slice(0, 12)}…`);
+        return { path: cached, checksum: expected, url };
+    }
+    const archive = await download(url);
+    const actual = createHash("sha256").update(archive).digest("hex");
+    if (actual !== expected) {
+        throw new Error(`Connector library checksum mismatch: expected ${expected}, received ${actual}.`);
+    }
+    // Write through a temp name so a killed run cannot leave a half file under a
+    // hash that claims to describe it.
+    const temporary = `${cached}.tmp-${process.pid}`;
+    await writeFile(temporary, archive);
+    await rename(temporary, cached);
+    return { path: cached, checksum: expected, url };
+}
+/** A `--archive` has no sidecar, so its identity is the bytes themselves. */
+async function archiveIdentity(archive) {
+    if (archive.checksum)
+        return archive.checksum;
+    return createHash("sha256").update(await readFile(archive.path)).digest("hex");
+}
+/** The extracted library is a function of both the dump and SDK corrections. */
+function libraryIdentity(archiveSha256, overlaySha256) {
+    return createHash("sha256")
+        .update(archiveSha256)
+        .update("\0")
+        .update(overlaySha256)
+        .digest("hex");
+}
+async function isCurrentLibrary(libraryPath, sha256) {
+    if (!(await isFile(join(libraryPath, "index.json"))))
+        return false;
+    try {
+        const source = JSON.parse(await readFile(join(libraryPath, SOURCE_FILE), "utf8"));
+        return source.sha256 === sha256;
+    }
+    catch {
+        return false;
+    }
+}
+async function writeSource(libraryPath, archive, sha256, archiveSha256, overlaySha256) {
+    await writeFile(join(libraryPath, SOURCE_FILE), `${JSON.stringify({
+        sha256,
+        archiveSha256,
+        overlaySha256,
+        url: archive.url ?? null,
+        archive: archive.checksum ? undefined : archive.path,
+        pulledAt: new Date().toISOString(),
+    }, null, 2)}\n`);
+}
+/**
+ * Point `current` at an entry, replacing whatever it named.
+ *
+ * Written to a temp name and renamed, so a reader never sees the link missing —
+ * `rename` over an existing symlink is atomic, while unlink-then-create leaves a
+ * window where a concurrent compile finds nothing.
+ */
+async function pointCurrentAt(root, sha256) {
+    const link = join(root, CURRENT_LINK);
+    const temporary = `${link}.tmp-${process.pid}`;
+    await rm(temporary, { recursive: true, force: true });
+    await symlink(sha256, temporary, "junction");
+    await rename(temporary, link);
+}
+export async function run(argv) {
+    if (has(argv, "--help") || has(argv, "-h")) {
+        console.log(USAGE);
+        return 0;
+    }
+    const cacheDir = libraryCacheRoot();
+    const force = has(argv, "--force");
+    const pythonExecutable = value(argv, "--python");
+    const connectorsPath = value(argv, "--connectors") ?? "connectors";
+    try {
+        const archive = await resolveArchive(argv, cacheDir, force);
+        const archiveSha256 = await archiveIdentity(archive);
+        const overlaySha256 = await curatedOverlayIdentity();
+        const sha256 = libraryIdentity(archiveSha256, overlaySha256);
+        const entry = cacheEntry(sha256, cacheDir);
+        // Destination overrides: a caller can still put the trees somewhere of their
+        // own choosing instead of in the cache.
+        const libraryPath = value(argv, "--library") ?? join(entry, LIBRARY_JSON_DIR);
+        const markdownPath = value(argv, "--library-md") ?? join(entry, LIBRARY_MARKDOWN_DIR);
+        const haveLibrary = !force && (await isCurrentLibrary(libraryPath, sha256));
+        if (haveLibrary) {
+            console.error(`registry pull: library ${sha256.slice(0, 12)}… already extracted`);
+        }
+        else {
+            // Unpack beside the target and swap, so a failure leaves whatever was
+            // already there rather than half of a new one.
+            const staging = `${libraryPath}.tmp-${process.pid}`;
+            await rm(staging, { recursive: true, force: true });
+            await extractLibrary({
+                archivePath: archive.path,
+                destinationPath: staging,
+                root: value(argv, "--root"),
+                pythonExecutable,
+                extractorPath: value(argv, "--extractor"),
+            });
+            await rm(libraryPath, { recursive: true, force: true });
+            await mkdir(join(libraryPath, ".."), { recursive: true });
+            await rename(staging, libraryPath);
+            await writeSource(libraryPath, archive, sha256, archiveSha256, overlaySha256);
+        }
+        // Which descriptors this project will actually import. Generating all 30
+        // costs 1.1 MB in someone's repository for operations they never call.
+        const named = repeated(argv, "--connector");
+        const referenced = named.length > 0 ? named : referencedConnectorKeys(".");
+        // Generate only what is missing. The Markdown is 2,472 pages and a pure
+        // function of the library JSON, so regenerating it to add one descriptor is
+        // pure waste — and it is what the first run of this design did.
+        const haveMarkdown = !force && haveLibrary && (await isFile(join(markdownPath, "index.json")));
+        if (haveMarkdown) {
+            console.error(`registry pull: markdown ${sha256.slice(0, 12)}… already generated`);
+        }
+        const wantMarkdown = !haveMarkdown;
+        const wantConnectors = referenced.length > 0;
+        if (wantMarkdown || wantConnectors) {
+            await materializeRegistry({
+                libraryJsonPath: libraryPath,
+                libraryMarkdownPath: wantMarkdown ? markdownPath : undefined,
+                connectorsPath: wantConnectors ? connectorsPath : undefined,
+                connectorSubset: referenced,
+                connectorImport: value(argv, "--import"),
+                pythonExecutable,
+                triggersPath: value(argv, "--triggers"),
+                generatorPath: value(argv, "--generator"),
+            });
+        }
+        if (!(await isFile(join(markdownPath, "index.json")))) {
+            throw new Error(`Registry materialization did not produce ${join(markdownPath, "index.json")}.`);
+        }
+        if (!value(argv, "--library")) {
+            await pointCurrentAt(cacheDir, sha256);
+        }
+        console.error(`registry pull: ${sha256.slice(0, 12)}… ready in ${cacheDir}` +
+            (value(argv, "--library") ? "" : ` (current -> ${sha256.slice(0, 12)}…)`));
+        if (referenced.length > 0) {
+            console.error(`registry pull: generated ${connectorsPath}/ for ${referenced.join(", ")}`);
+        }
+        else {
+            console.error("registry pull: no connector referenced by this project yet, so no " +
+                "descriptors were generated. Name one with `--connector <key>`, or " +
+                "author the step and pull again.");
+        }
+        return 0;
+    }
+    catch (error) {
+        console.error(error instanceof Error ? error.message : String(error));
+        return 1;
+    }
+}

package/dist/registry/python.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Running the packaged Python generators.
+ *
+ * Three verbs shell out to Python — materialize, extract and prepare — and all
+ * three need the same three things: the script's path inside the installed
+ * package, an interpreter, and a failure translated into a message worth
+ * reading. Keeping that here means a fix (a new platform's interpreter name,
+ * a clearer error) lands once.
+ *
+ * The generators are copied to `dist/generators/` at build time and these
+ * modules live in `dist/registry/`, so the path is one level up. Resolving it
+ * from `import.meta.url` rather than `process.cwd()` is what lets the verbs run
+ * from anywhere.
+ */
+/** A generator shipped in `dist/generators/`. */
+export declare function packagedGenerator(fileName: string): string;
+export declare function defaultPythonExecutable(): string;
+export interface RunGeneratorOptions {
+    /** Script path — usually `packagedGenerator(...)`, overridable for checkouts. */
+    script: string;
+    args: string[];
+    pythonExecutable?: string;
+    /** Names the step in failure messages, e.g. "Registry materialization". */
+    what: string;
+}
+export declare function runGenerator(options: RunGeneratorOptions): Promise<void>;