@uipath/maestro-builder-sdk 6.4.0 → 6.5.1

package/dist/registry/compat/pystr.js

@@ -0,0 +1,221 @@
+/**
+ * The few string operations that must behave like Python's, because their
+ * result reaches a file the Python generators used to write.
+ *
+ * Everything else in the registry is ordinary TypeScript. This module exists
+ * so the places where JavaScript and Python disagree — `strip()`'s whitespace
+ * set, `str()` of a bool, `title()` after a digit, slicing by code point — are
+ * spelled once and tested against a table Python itself produced
+ * (`typescript/tests/fixtures/registry/pycompat.json`).
+ */
+import { pyFloatRepr } from "../codecs/pyjson.js";
+/**
+ * Characters `str.isspace()` is true for. Not the same set as JavaScript's
+ * `\s`: Python includes the C1 separators `\x1c`–`\x1f` and `\x85`, and
+ * excludes the BOM ``.
+ */
+const PY_SPACE = "\t\n\u000b\u000c\r\u001c\u001d\u001e\u001f \u0085\u00a0\u1680" +
+    "\u2000\u2001\u2002\u2003\u2004\u2005\u2006\u2007\u2008\u2009\u200a" +
+    "\u2028\u2029\u202f\u205f\u3000";
+function isPySpace(ch) {
+    return PY_SPACE.includes(ch);
+}
+/** `str.strip()` with no argument. */
+export function pyStrip(s) {
+    let start = 0;
+    let end = s.length;
+    while (start < end && isPySpace(s[start]))
+        start++;
+    while (end > start && isPySpace(s[end - 1]))
+        end--;
+    return s.slice(start, end);
+}
+/** `str.rstrip()` with no argument. */
+export function pyRstrip(s) {
+    let end = s.length;
+    while (end > 0 && isPySpace(s[end - 1]))
+        end--;
+    return s.slice(0, end);
+}
+/** `str.strip(chars)`: strip any of the given characters from both ends. */
+export function pyStripChars(s, chars) {
+    let start = 0;
+    let end = s.length;
+    while (start < end && chars.includes(s[start]))
+        start++;
+    while (end > start && chars.includes(s[end - 1]))
+        end--;
+    return s.slice(start, end);
+}
+/**
+ * `str(value)` for the JSON-shaped values the generators coerce: `True`,
+ * `None`, `1.0`, never `true`, `null`, `1`.
+ */
+export function pyStr(value) {
+    if (value === null || value === undefined)
+        return "None";
+    if (typeof value === "boolean")
+        return value ? "True" : "False";
+    if (typeof value === "number") {
+        return Number.isInteger(value) && !Object.is(value, -0) ? String(value) : pyFloatRepr(value);
+    }
+    if (typeof value === "string")
+        return value;
+    if (typeof value === "bigint")
+        return value.toString();
+    // Python would print a repr of a dict or list here; the generators never do
+    // that on purpose, so make it loud rather than plausible.
+    throw new TypeError(`pyStr: refusing to stringify a ${Array.isArray(value) ? "list" : typeof value}`);
+}
+const UPPER = /\p{Lu}/u;
+/**
+ * `str.title()`'s word-boundary test is the Unicode `Cased` property, not "a
+ * letter with a case category": a modifier letter such as `ʰ`, a circled `Ⓐ`
+ * or a Roman numeral `ⅷ` is cased and continues a word, while the apostrophe
+ * `ʼ` in `ʼn`'s titlecase is not and starts one.
+ */
+const CASED = /\p{Cased}/u;
+/** `Case_Ignorable`: what the final-sigma rule looks past on either side. */
+const CASE_IGNORABLE = /\p{Case_Ignorable}/u;
+const TITLECASE_LETTER = /\p{Lt}/u;
+/**
+ * Code points whose titlecase is neither themselves nor their `toUpperCase()`,
+ * from Unicode 15.1 (CPython 3.13). `ß` and the ligatures titlecase to a
+ * capital followed by lowercase, the digraphs to their dedicated titlecase
+ * code point, and the Greek forms with iota subscript to the base capital plus
+ * COMBINING GREEK YPOGEGRAMMENI (U+0345), where uppercasing gives a full
+ * capital iota instead. (`ʼn` → `ʼN` and `ǰ` → `J̌` are NOT here: there the
+ * titlecase equals the uppercase, which `toUpperCase()` already spells.)
+ */
+const TITLECASE_SPECIAL = new Map([
+    ["ß", "Ss"],
+    ["DŽ", "Dž"], ["dž", "Dž"], ["LJ", "Lj"], ["lj", "Lj"], ["NJ", "Nj"], ["nj", "Nj"], ["DZ", "Dz"], ["dz", "Dz"],
+    ["և", "Եւ"],
+    ["ᾲ", "Ὰͅ"], ["ᾳ", "ᾼ"], ["ᾴ", "Άͅ"], ["ᾷ", "ᾼ͂"],
+    ["ῂ", "Ὴͅ"], ["ῃ", "ῌ"], ["ῄ", "Ήͅ"], ["ῇ", "ῌ͂"],
+    ["ῲ", "Ὼͅ"], ["ῳ", "ῼ"], ["ῴ", "Ώͅ"], ["ῷ", "ῼ͂"],
+    ["ff", "Ff"], ["fi", "Fi"], ["fl", "Fl"], ["ffi", "Ffi"], ["ffl", "Ffl"], ["ſt", "St"], ["st", "St"],
+    ["ﬓ", "Մն"], ["ﬔ", "Մե"], ["ﬕ", "Մի"], ["ﬖ", "Վն"], ["ﬗ", "Մխ"],
+]);
+/**
+ * `_PyUnicode_ToTitleFull`: Python's titlecase of one code point, which
+ * JavaScript lacks. UnicodeData gives most code points no titlecase of their
+ * own, in which case it is their uppercase — and `toUpperCase()` already
+ * applies SpecialCasing there — so only the exceptions need spelling: a
+ * titlecase letter is its own titlecase; Georgian Mkhedruli titlecases to
+ * itself although it uppercases to Mtavruli; the Greek small letters with
+ * iota subscript (`ᾀ`…`ᾧ`) titlecase to the titlecase letter eight code points
+ * up; and the table above.
+ */
+function titlecaseChar(ch) {
+    const special = TITLECASE_SPECIAL.get(ch);
+    if (special !== undefined)
+        return special;
+    if (TITLECASE_LETTER.test(ch))
+        return ch;
+    const cp = ch.codePointAt(0);
+    if (cp >= 0x10d0 && cp <= 0x10ff)
+        return ch;
+    if ((cp >= 0x1f80 && cp <= 0x1f87) || (cp >= 0x1f90 && cp <= 0x1f97) || (cp >= 0x1fa0 && cp <= 0x1fa7)) {
+        return String.fromCodePoint(cp + 8);
+    }
+    return ch.toUpperCase();
+}
+/**
+ * Whether the `Σ` at `chars[i]` is in Final_Sigma context: preceded, past any
+ * case-ignorables, by a cased character, and not followed, past any
+ * case-ignorables, by one. CPython applies this inside `title()` and `lower()`;
+ * `toLowerCase()` applies it only when given the whole string, which lowering
+ * one character at a time forfeits.
+ */
+function isFinalSigma(chars, i) {
+    let j = i - 1;
+    while (j >= 0 && CASE_IGNORABLE.test(chars[j]))
+        j--;
+    if (j < 0 || !CASED.test(chars[j]))
+        return false;
+    j = i + 1;
+    while (j < chars.length && CASE_IGNORABLE.test(chars[j]))
+        j++;
+    return j === chars.length || !CASED.test(chars[j]);
+}
+/**
+ * `str.title()`: each character after a non-cased one (or at the start) is
+ * titlecased, every other one lowercased — so digits and apostrophes start a
+ * new word (`"a1b"` → `"A1B"`, `"o'brien"` → `"O'Brien"`), unlike a
+ * split-on-space capitaliser, and a capital sigma ending a word becomes `ς`
+ * (`"ΟΔΟΣ"` → `"Οδος"`).
+ *
+ * Checked against CPython 3.13 (Unicode 15.1) over all 1,112,064 code points,
+ * each as `chr(cp)` — which exercises the titlecase branch — and again as
+ * `"A" + chr(cp)`, `"AΣ" + chr(cp)` and `chr(cp) + "Σ"`, which exercise the
+ * lowercase branch and the final-sigma rule in both directions. Every
+ * disagreement was a code point Node's ICU 16 cases and Unicode 15.1 does not:
+ * U+019B, U+0264, U+1C89, U+1C8A, U+A7CB–A7CD, U+A7DA–A7DC and the Garay block
+ * (U+10D50–10D65, U+10D70–10D85) — 54 code points in total. So this matches
+ * `str.title()` exactly on the repertoire the two share, and an engine newer
+ * than the Python it is compared with will case a handful of letters Python
+ * leaves alone.
+ *
+ * None of the 54 appears in the committed library's slugs, labels or field
+ * names, which is where it matters — but that is an observation about how the
+ * registry names things today, not a rule anything enforces, so a future
+ * connector could in principle carry one. The curated cases that guard the
+ * behaviour are in `registry-compat.test.ts`, via the fixture Python wrote.
+ */
+export function pyTitle(s) {
+    const chars = [...s];
+    let out = "";
+    let previousCased = false;
+    for (let i = 0; i < chars.length; i++) {
+        const ch = chars[i];
+        if (!previousCased)
+            out += titlecaseChar(ch);
+        else if (ch === "Σ")
+            out += isFinalSigma(chars, i) ? "ς" : "σ";
+        else
+            out += ch.toLowerCase();
+        previousCased = CASED.test(ch);
+    }
+    return out;
+}
+/** `s[:1].isupper()`: the first code point is an uppercase letter. */
+export function startsWithUpper(s) {
+    const first = s.codePointAt(0);
+    return first !== undefined && UPPER.test(String.fromCodePoint(first));
+}
+/** `s[:1].upper() + s[1:]`, slicing by code point. */
+export function upperFirst(s) {
+    const first = s.codePointAt(0);
+    if (first === undefined)
+        return s;
+    const head = String.fromCodePoint(first);
+    return head.toUpperCase() + s.slice(head.length);
+}
+/** `s[:1].lower() + s[1:]`, slicing by code point. */
+export function lowerFirst(s) {
+    const first = s.codePointAt(0);
+    if (first === undefined)
+        return s;
+    const head = String.fromCodePoint(first);
+    return head.toLowerCase() + s.slice(head.length);
+}
+/** `s.rsplit(sep, 1)[-1]`. */
+export function afterLast(s, sep) {
+    const at = s.lastIndexOf(sep);
+    return at < 0 ? s : s.slice(at + sep.length);
+}
+/** `s.rsplit(sep, 1)[0]` when `sep` occurs, else `s`. */
+export function beforeLast(s, sep) {
+    const at = s.lastIndexOf(sep);
+    return at < 0 ? s : s.slice(0, at);
+}
+/** `s.split(sep, 1)` as a pair; the second element is `undefined` when absent. */
+export function splitOnce(s, sep) {
+    const at = s.indexOf(sep);
+    return at < 0 ? [s, undefined] : [s.slice(0, at), s.slice(at + sep.length)];
+}
+/** `str.isdigit()` for ASCII digits, which is all the generators ever test. */
+export function isAsciiDigits(s) {
+    return /^[0-9]+$/.test(s);
+}

package/dist/registry/concurrency.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Bounded parallelism with results in input order.
+ *
+ * The library builder used seven thread pools; four of them appended results as
+ * they completed, so the order of expanded entries — and, on a tie, which of two
+ * colliding entries won — depended on scheduling. This helper runs at most
+ * `limit` tasks at once and always returns `results[i]` for `items[i]`, so the
+ * output of a build is a function of its inputs alone.
+ */
+export declare function mapConcurrent<T, R>(items: readonly T[], limit: number, fn: (item: T, index: number) => Promise<R>): Promise<R[]>;

package/dist/registry/concurrency.js

@@ -0,0 +1,34 @@
+/**
+ * Bounded parallelism with results in input order.
+ *
+ * The library builder used seven thread pools; four of them appended results as
+ * they completed, so the order of expanded entries — and, on a tie, which of two
+ * colliding entries won — depended on scheduling. This helper runs at most
+ * `limit` tasks at once and always returns `results[i]` for `items[i]`, so the
+ * output of a build is a function of its inputs alone.
+ */
+export async function mapConcurrent(items, limit, fn) {
+    // `ThreadPoolExecutor(max_workers=0)` raised `ValueError: max_workers must
+    // be greater than 0`, and so does this, even for no work: a limit that is
+    // not a positive number is a caller's mistake, and clamping it to one
+    // worker would turn a pipeline typo into a build that runs serially for
+    // hours instead of failing at once.
+    if (!(Number.isFinite(limit) && limit >= 1)) {
+        throw new RangeError(`mapConcurrent: limit must be a positive number, got ${limit}`);
+    }
+    const results = new Array(items.length);
+    if (items.length === 0)
+        return results;
+    const workers = Math.min(Math.floor(limit), items.length);
+    let next = 0;
+    const run = async () => {
+        for (;;) {
+            const index = next++;
+            if (index >= items.length)
+                return;
+            results[index] = await fn(items[index], index);
+        }
+    };
+    await Promise.all(Array.from({ length: workers }, run));
+    return results;
+}

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;