@uipath/maestro-builder-sdk 6.4.0 → 6.5.0

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

@@ -1,7 +1,20 @@
+import { type Reporter } from "./reporter.js";
 /** 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>;
+export interface CuratedOverlayResult {
+    /** Overlay files copied into the library. */
+    files: number;
+    /** Index rows added for identities the library did not already carry. */
+    entries: number;
+    /**
+     * Overlay entry files NOT copied, because the library resolves their
+     * identity to a different path. POSIX-relative to the overlay, sorted. Each
+     * one is also reported through the reporter — see {@link applyCuratedOverlay}.
+     */
+    skipped: string[];
+}
 /**
  * Apply the SDK's curated corrections after extracting the raw registry dump.
  *
@@ -9,8 +22,27 @@ export declare function curatedOverlayIdentity(overlayPath?: string): Promise<st
  * 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.
+ *
+ * WHEN THE LIBRARY ALREADY RESOLVES THE IDENTITY ELSEWHERE, the file is not
+ * copied at all and the skip is reported. That case is not hypothetical: four
+ * of the bundled `event-*@1.0.0.json` files carry a (nodeType, version) the
+ * raw dump lacks TODAY but a refreshed catalog serves at its own path — the
+ * per-object event variants land under `<connector>/events/<object>/`, keeping
+ * the template's nodeType. Since the union keeps the library's row, copying
+ * anyway left a file no index row pointed at, which `--check-orphans` (the
+ * image build passes it) rejects. The three ways out are not equal:
+ *
+ *   - copying and teaching the orphan check to tolerate the file would keep
+ *     the build green and hide the real loss, which is that the hand-verified
+ *     CORRECTION never takes effect once the index points somewhere else;
+ *   - redirecting the correction onto the indexed path cannot be done safely
+ *     here, because ONE event identity maps to MANY per-object paths in a
+ *     refreshed library, and stamping the flat curated definition over each
+ *     per-object variant would destroy the per-object schema the library just
+ *     served — a worse regression than the one being fixed;
+ *   - so the copy is skipped and said out loud. The library keeps the
+ *     definition it resolves, the tree gains no unreachable file, and the
+ *     operator is told which overlay row has been overtaken and needs
+ *     re-verifying. The image build is then green before AND after a refresh.
  */
-export declare function applyCuratedOverlay(libraryPath: string, overlayPath?: string): Promise<{
-    files: number;
-    entries: number;
-}>;
+export declare function applyCuratedOverlay(libraryPath: string, overlayPath?: string, reporter?: Reporter): Promise<CuratedOverlayResult>;

package/dist/registry/curated-overlay.js

@@ -1,7 +1,9 @@
 import { createHash } from "node:crypto";
 import { cp, mkdir, readdir, readFile, writeFile } from "node:fs/promises";
-import { dirname, join, relative } from "node:path";
+import { dirname, join, relative, sep } from "node:path";
 import { fileURLToPath } from "node:url";
+import { sortedStrings } from "./compat/compare.js";
+import { consoleReporter } from "./reporter.js";
 /** 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));
@@ -30,6 +32,10 @@ export async function curatedOverlayIdentity(overlayPath = bundledOverlayPath())
 function entryIdentity(entry) {
     return `${String(entry.nodeType)}\0${String(entry.version)}`;
 }
+/** The sidecar that travels with an entry file, and has no index row of its own. */
+function sidecarOf(rel) {
+    return `${rel.slice(0, -".json".length)}.v1def.json`;
+}
 /**
  * Apply the SDK's curated corrections after extracting the raw registry dump.
  *
@@ -37,26 +43,93 @@ function entryIdentity(entry) {
  * 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.
+ *
+ * WHEN THE LIBRARY ALREADY RESOLVES THE IDENTITY ELSEWHERE, the file is not
+ * copied at all and the skip is reported. That case is not hypothetical: four
+ * of the bundled `event-*@1.0.0.json` files carry a (nodeType, version) the
+ * raw dump lacks TODAY but a refreshed catalog serves at its own path — the
+ * per-object event variants land under `<connector>/events/<object>/`, keeping
+ * the template's nodeType. Since the union keeps the library's row, copying
+ * anyway left a file no index row pointed at, which `--check-orphans` (the
+ * image build passes it) rejects. The three ways out are not equal:
+ *
+ *   - copying and teaching the orphan check to tolerate the file would keep
+ *     the build green and hide the real loss, which is that the hand-verified
+ *     CORRECTION never takes effect once the index points somewhere else;
+ *   - redirecting the correction onto the indexed path cannot be done safely
+ *     here, because ONE event identity maps to MANY per-object paths in a
+ *     refreshed library, and stamping the flat curated definition over each
+ *     per-object variant would destroy the per-object schema the library just
+ *     served — a worse regression than the one being fixed;
+ *   - so the copy is skipped and said out loud. The library keeps the
+ *     definition it resolves, the tree gains no unreachable file, and the
+ *     operator is told which overlay row has been overtaken and needs
+ *     re-verifying. The image build is then green before AND after a refresh.
  */
-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);
-    }
+export async function applyCuratedOverlay(libraryPath, overlayPath = bundledOverlayPath(), 
+// The public materializer API does not forward one, and a warning nobody
+// sees would defeat the point, so the default is the real terminal.
+reporter = consoleReporter) {
     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)));
+    // Every path the library resolves each identity to. A `GenericExpanded` or
+    // per-object entry shares its nodeType with its siblings, so an identity
+    // legitimately has more than one.
+    const resolvedPaths = new Map();
+    for (const entry of entries) {
+        if (typeof entry.path !== "string")
+            continue;
+        const identity = entryIdentity(entry);
+        const known = resolvedPaths.get(identity);
+        if (known === undefined)
+            resolvedPaths.set(identity, [entry.path]);
+        else
+            known.push(entry.path);
+    }
+    const additions = [];
+    const skipped = new Set();
+    for (const row of overlay.entries ?? []) {
+        const identity = entryIdentity(row);
+        if (!resolvedPaths.has(identity)) {
+            additions.push(row);
+            continue;
+        }
+        const paths = resolvedPaths.get(identity);
+        if (typeof row.path !== "string" || paths.includes(row.path))
+            continue;
+        skipped.add(row.path);
+        reporter.warn([
+            `  WARN: curated overlay SKIPPED ${row.path}`,
+            `        ${String(row.nodeType)}@${String(row.version)} is already in the library's index, at`,
+            ...paths.map((path) => `          ${path}`),
+            "        so the copied file would resolve for nobody. The library's own definition stands and",
+            "        this correction does NOT take effect. Re-verify it against the current library and drop",
+            "        its row from typescript/sdk/lib/library-json.samples/index.json once the library carries it.",
+        ].join("\n"));
+    }
+    // A skipped entry's sidecar goes with it: it is only ever read beside the
+    // entry file, so leaving it behind would state a correction nothing reads.
+    const notCopied = new Set(["index.json"]);
+    for (const rel of skipped) {
+        notCopied.add(rel);
+        notCopied.add(sidecarOf(rel));
+    }
+    const overlayFiles = await jsonFiles(overlayPath);
+    let copied = 0;
+    for (const source of overlayFiles) {
+        const rel = relative(overlayPath, source).split(sep).join("/");
+        if (notCopied.has(rel))
+            continue;
+        const target = join(libraryPath, rel);
+        await mkdir(dirname(target), { recursive: true });
+        await cp(source, target);
+        copied += 1;
+    }
     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 };
+    return { files: copied, entries: additions.length, skipped: sortedStrings([...skipped]) };
 }

package/dist/registry/errors.d.ts

@@ -0,0 +1,26 @@
+/**
+ * The two ways a registry verb ends badly, and what each means for the exit code.
+ *
+ * A {@link Refusal} is the tool declining to proceed for a reason the author
+ * can act on — no connection matched, the object is ambiguous, a parent field
+ * was rejected. The message is the product: agents read it and follow it, so it
+ * is written for a reader and kept verbatim from the Python it replaces. It
+ * exits 1. A {@link UsageError} is a malformed invocation and exits 2, as
+ * argparse did. Anything else is a bug and propagates as itself.
+ */
+export declare class Refusal extends Error {
+    /** A stable, grep-able name for the refusal, e.g. `CONNECTION_AMBIGUOUS`. */
+    readonly code: string;
+    readonly exitCode: 1;
+    constructor(message: string, 
+    /** A stable, grep-able name for the refusal, e.g. `CONNECTION_AMBIGUOUS`. */
+    code?: string);
+}
+export declare class UsageError extends Error {
+    readonly exitCode: 2;
+    constructor(message: string);
+}
+/** The exit code a CLI verb should return for a thrown value. */
+export declare function exitCodeOf(error: unknown): number;
+/** The text a CLI verb should print to stderr for a thrown value. */
+export declare function messageOf(error: unknown): string;

package/dist/registry/errors.js

@@ -0,0 +1,38 @@
+/**
+ * The two ways a registry verb ends badly, and what each means for the exit code.
+ *
+ * A {@link Refusal} is the tool declining to proceed for a reason the author
+ * can act on — no connection matched, the object is ambiguous, a parent field
+ * was rejected. The message is the product: agents read it and follow it, so it
+ * is written for a reader and kept verbatim from the Python it replaces. It
+ * exits 1. A {@link UsageError} is a malformed invocation and exits 2, as
+ * argparse did. Anything else is a bug and propagates as itself.
+ */
+export class Refusal extends Error {
+    code;
+    exitCode = 1;
+    constructor(message, 
+    /** A stable, grep-able name for the refusal, e.g. `CONNECTION_AMBIGUOUS`. */
+    code = "REFUSED") {
+        super(message);
+        this.code = code;
+        this.name = "Refusal";
+    }
+}
+export class UsageError extends Error {
+    exitCode = 2;
+    constructor(message) {
+        super(message);
+        this.name = "UsageError";
+    }
+}
+/** The exit code a CLI verb should return for a thrown value. */
+export function exitCodeOf(error) {
+    if (error instanceof Refusal || error instanceof UsageError)
+        return error.exitCode;
+    return 1;
+}
+/** The text a CLI verb should print to stderr for a thrown value. */
+export function messageOf(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/registry/extractor.d.ts

@@ -1,22 +1,21 @@
 /**
  * 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.
+ * In-process since the TypeScript port: `archive/` reads the zip with
+ * `node:zlib` and refuses anything hostile (path traversal, symlinks, features
+ * the self-produced archive never uses). The Python `extract_library.py` this
+ * replaced carried the same rules; its tests are ported beside the reader.
  */
 export interface ExtractLibraryOptions {
     archivePath: string;
     destinationPath: string;
     /** Only entries under this zip prefix are taken. */
     root?: string;
+    /** @deprecated No interpreter is involved any more; accepted and ignored. */
     pythonExecutable?: string;
-    /** Override used by tests and source checkouts. */
+    /** @deprecated The extractor is part of the package; accepted and ignored. */
     extractorPath?: string;
 }
-export declare function extractLibrary(options: ExtractLibraryOptions): Promise<void>;
+export declare function extractLibrary(options: ExtractLibraryOptions): Promise<{
+    written: number;
+}>;

package/dist/registry/extractor.js

@@ -1,18 +1,8 @@
-import { packagedGenerator, runGenerator } from "./python.js";
+import { extractArchive } from "./archive/extract.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",
+    return extractArchive({
+        archivePath: options.archivePath,
+        destination: options.destinationPath,
+        root: options.root,
     });
 }

package/dist/registry/files.d.ts

@@ -0,0 +1,26 @@
+export declare function ensureDir(path: string): void;
+export declare function writeText(path: string, text: string): void;
+export declare function writeBytes(path: string, bytes: Uint8Array): void;
+export declare function readText(path: string): string;
+export declare function readJson(path: string): unknown;
+export declare function isFile(path: string): boolean;
+export declare function isDirectory(path: string): boolean;
+/** Every file under `root`, as paths relative to it with `/` separators, sorted. */
+export declare function listFiles(root: string, filter?: (relative: string) => boolean): string[];
+/**
+ * Build a directory beside its final name, then swap it into place.
+ *
+ * `fill` writes into `<target>.tmp-<pid>`. When it returns, any existing
+ * `target` is renamed to `<target>.old-<pid>`, the staging directory takes the
+ * final name, and the old tree is removed. A failure inside `fill` leaves the
+ * previous `target` untouched and cleans up the staging directory; a failure
+ * of the final rename puts the parked tree back, so the previous output
+ * survives as it did when Python's `Path.rename` raised.
+ *
+ * On overlayfs — every Docker RUN after the first — a directory written by an
+ * earlier layer cannot be renamed, so the parking step falls back to deleting
+ * it. See the comment on that branch for what the fallback gives up.
+ */
+export declare function stageAndSwap(target: string, fill: (staging: string) => void): void;
+/** Remove a directory tree if it exists, then create it empty. */
+export declare function resetDir(path: string): void;

package/dist/registry/files.js

@@ -0,0 +1,160 @@
+/**
+ * The filesystem moves the registry makes, in one place.
+ *
+ * Generators return strings and maps; these helpers put them on disk. The
+ * stage-and-swap dance exists because two `registry pull`s can race on the
+ * shared cache when a coding agent issues tool calls in parallel, and a
+ * converter that wipes and rewrites its output directory in place left one of
+ * them mid-write.
+ */
+import { mkdirSync, renameSync, rmSync, writeFileSync, existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { messageOf } from "./errors.js";
+export function ensureDir(path) {
+    mkdirSync(path, { recursive: true });
+}
+export function writeText(path, text) {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, text, "utf8");
+}
+export function writeBytes(path, bytes) {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, bytes);
+}
+export function readText(path) {
+    return readFileSync(path, "utf8");
+}
+export function readJson(path) {
+    return JSON.parse(readFileSync(path, "utf8"));
+}
+export function isFile(path) {
+    try {
+        return statSync(path).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+export function isDirectory(path) {
+    try {
+        return statSync(path).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/** Every file under `root`, as paths relative to it with `/` separators, sorted. */
+export function listFiles(root, filter) {
+    const out = [];
+    const walk = (dir, prefix) => {
+        for (const entry of readdirSync(dir, { withFileTypes: true })) {
+            const rel = prefix ? `${prefix}/${entry.name}` : entry.name;
+            if (entry.isDirectory())
+                walk(join(dir, entry.name), rel);
+            else if (entry.isFile() && (!filter || filter(rel)))
+                out.push(rel);
+        }
+    };
+    if (existsSync(root))
+        walk(root, "");
+    return out.sort();
+}
+/**
+ * Build a directory beside its final name, then swap it into place.
+ *
+ * `fill` writes into `<target>.tmp-<pid>`. When it returns, any existing
+ * `target` is renamed to `<target>.old-<pid>`, the staging directory takes the
+ * final name, and the old tree is removed. A failure inside `fill` leaves the
+ * previous `target` untouched and cleans up the staging directory; a failure
+ * of the final rename puts the parked tree back, so the previous output
+ * survives as it did when Python's `Path.rename` raised.
+ *
+ * On overlayfs — every Docker RUN after the first — a directory written by an
+ * earlier layer cannot be renamed, so the parking step falls back to deleting
+ * it. See the comment on that branch for what the fallback gives up.
+ */
+export function stageAndSwap(target, fill) {
+    const staging = `${target}.tmp-${process.pid}`;
+    const previous = `${target}.old-${process.pid}`;
+    rmSync(staging, { recursive: true, force: true });
+    mkdirSync(staging, { recursive: true });
+    try {
+        fill(staging);
+    }
+    catch (error) {
+        rmSync(staging, { recursive: true, force: true });
+        throw error;
+    }
+    mkdirSync(dirname(target), { recursive: true });
+    // Which of the three states the target is in when the final rename runs, so
+    // a failure there can say honestly what is and is not still on disk.
+    let parked = "nothing-was-there";
+    if (existsSync(target)) {
+        try {
+            renameSync(target, previous);
+            parked = "parked";
+        }
+        catch (error) {
+            // EXDEV on a rename INSIDE one directory looks impossible, and on
+            // overlayfs it is routine: a directory that came from a lower layer
+            // cannot be renamed at all, because the kernel would have to copy the
+            // whole tree up first, so it answers "cross-device link not permitted".
+            // The e2e image hits this exactly — `registry pull` writes library-md in
+            // one RUN and `registry materialize` swaps it in the next.
+            //
+            // So: delete instead of parking. Be clear about what that costs. From
+            // here until the rename below succeeds, `target` does not exist, and if
+            // that rename fails there is no parked copy to put back — the PREVIOUS
+            // tree is gone for good. The NEW tree is not: it is complete in
+            // `staging`, which is left in place on that failure and named in the
+            // error, so an operator can finish the move by hand. The alternative
+            // that keeps the old tree, copying it aside first, costs a second pass
+            // over 7,000 files inside a Docker build where nothing races the swap;
+            // the window is accepted there and only there. The atomic path stays the
+            // default everywhere a rename works.
+            if (error?.code !== "EXDEV")
+                throw error;
+            rmSync(target, { recursive: true, force: true });
+            parked = "deleted";
+        }
+    }
+    try {
+        renameSync(staging, target);
+    }
+    catch (error) {
+        // The new tree is deliberately NOT cleaned up here: it is the only copy
+        // when the overlayfs branch ran, and finishing the move by hand is the
+        // recovery. It is not ALWAYS there, though — the rename can fail because
+        // the staging tree itself went missing, which is what a second run sharing
+        // this output with the same pid does, the race the `.tmp-<pid>` naming
+        // already admits. Sending an operator after a directory that is not there
+        // costs them the time it takes to distrust the message.
+        let outcome;
+        if (parked === "parked") {
+            try {
+                renameSync(previous, target);
+                outcome = `the previous tree was put back at ${target}`;
+            }
+            catch {
+                outcome = `the previous tree could not be put back and is still parked at ${previous}`;
+            }
+        }
+        else if (parked === "deleted") {
+            outcome = "the previous tree was already deleted by the overlayfs fallback and is gone";
+        }
+        else {
+            outcome = "there was no previous tree";
+        }
+        const remains = existsSync(staging)
+            ? `the complete new tree is at ${staging}`
+            : `the new tree is NOT at ${staging} either, so this output has to be built again`;
+        throw new Error(`stageAndSwap: could not move ${staging} to ${target}: ${messageOf(error)}; ${outcome}, and ${remains}`, { cause: error });
+    }
+    if (parked === "parked")
+        rmSync(previous, { recursive: true, force: true });
+}
+/** Remove a directory tree if it exists, then create it empty. */
+export function resetDir(path) {
+    rmSync(path, { recursive: true, force: true });
+    mkdirSync(path, { recursive: true });
+}

package/dist/registry/generators/descriptors.d.ts

@@ -0,0 +1,81 @@
+import type { LoadedLibrary } from "../library-reader.js";
+import { type LookupSpecData, type LookupStrategy } from "../lookup-specs.js";
+import { type LibraryEntry, type LibraryField, type V1Definition } from "../model/library.js";
+import { NamedTypeRegistry } from "./type-registry.js";
+import { type TreeField, type TypeNode, type TypeTree } from "./type-tree.js";
+/** A field name is a valid identifier only if it has no dots, brackets, etc.; otherwise it is quoted. */
+export declare function keyLiteral(name: string): string;
+/** One sentence for a lookup field's own doc comment: what it sends, how to get one. */
+export declare function lookupFieldNote(declared: TreeField): string;
+/**
+ * One property line.
+ *
+ * An INPUT property is wrapped so it also accepts an expression, and a
+ * resolvable lookup additionally accepts an unresolved token. The wrapper goes
+ * here rather than on the leaf type so that `tags: input('tags')` — the whole
+ * collection as one expression — is legal alongside `tags: ['a', out(…)]`.
+ * An OUTPUT property is never wrapped: it came back from the connector.
+ */
+export declare function emitNestedProperty(name: string, node: TypeNode, indent: string, namedTypes: NamedTypeRegistry, allOptional: boolean, isInput?: boolean): string[];
+/** `export interface <name> { … }` over the roots of one tree. */
+export declare function emitInterface(name: string, allOptional: boolean, namedTypes: NamedTypeRegistry, fieldTree: TypeTree, isInput?: boolean): string[];
+export declare const STRATEGY_PROSE: Readonly<Record<LookupStrategy, string>>;
+/**
+ * The grep-able header: the lookups stated in prose beside the data, for agents
+ * that read source with Grep and have no language server. Bare ` * ` body
+ * lines, to be spliced inside a `/** … *\/` block.
+ */
+export declare function emitLookupComment(specs: ReadonlyMap<string, LookupSpecData>, symbol?: string): string[];
+/**
+ * The descriptor's `lookups:` literal — a RUNTIME value, not a type. `lookup()`
+ * reads `aliases` from it to build the `.byName()` family.
+ */
+export declare function emitLookupsBlock(specs: ReadonlyMap<string, LookupSpecData>): string[];
+/**
+ * A connector EVENT as a `triggerDescriptor()`, the shape `onEvent()` takes.
+ *
+ * The payload type comes from `outputSchema`, and `where` from the entry's
+ * event parameters. An entry that declares none keeps a loose
+ * `Record<string, string>`: that is either an event which genuinely takes no
+ * parameters (HTTP Webhook) or one nothing has described yet, and an empty
+ * interface would refuse every key in both cases.
+ */
+export declare function emitEvent(entry: LibraryEntry, inFields: readonly LibraryField[], inputTree: TypeTree, outputTree: TypeTree, name: string, inputTypes: NamedTypeRegistry, outputTypes: NamedTypeRegistry, invariant?: ReadonlySet<string>): string[];
+/** One operation: its `Inputs`/`Outputs` interfaces, doc comment and `descriptor()` const. */
+export declare function emitOp(entry: LibraryEntry, v1def: V1Definition, inputTree: TypeTree, outputTree: TypeTree, name: string, inputTypes: NamedTypeRegistry, outputTypes: NamedTypeRegistry, invariant?: ReadonlySet<string>): string[];
+/**
+ * The catalog names required inputs but the generated `Inputs` interface is
+ * empty: the descriptor would type-check a call the platform rejects. One line
+ * naming the operation and the fields, or `undefined` when there is no gap.
+ */
+export declare function requiredInputGap(entry: LibraryEntry, inputTree: TypeTree): string | undefined;
+export interface DescriptorOptions {
+    /** Module specifier for `import { descriptor }`; {@link PACKAGE_NAME} by default. */
+    importSpecifier?: string;
+    /** Connector keys to emit; every connector when omitted or empty. */
+    connectors?: readonly string[];
+    /**
+     * Emit typed descriptors for `GenericExpanded` entries (and every per-object
+     * variant of a generic event). Off for the bulk library; on for the small
+     * connection-resolved overlays `prepare` writes.
+     */
+    includeGenericExpanded?: boolean;
+}
+export interface DescriptorOutput {
+    /** `"<connector-key>.ts"` → module text, in emit order (connector keys sorted by code point). */
+    modules: Map<string, string>;
+    /** nodeType → exported const name, from `naming.symbolIndex`, for the whole index. */
+    symbols: Map<string, string>;
+    /** One line per operation whose catalog requires inputs its interface cannot carry. */
+    requiredInputGaps: string[];
+}
+/**
+ * Render every connector module of the library.
+ *
+ * The Python `main()` wrote every module and only then exited 1 on
+ * {@link DescriptorOutput.requiredInputGaps}; this returns both and the caller
+ * decides. A missing entry or sidecar throws, as the Python did.
+ */
+export declare function renderDescriptorModules(library: LoadedLibrary, options?: DescriptorOptions): DescriptorOutput;
+/** The text the Python printed before exiting 1 on gaps; call only with a non-empty list. */
+export declare function formatRequiredInputGaps(gaps: readonly string[]): string;