@uipath/maestro-builder-sdk 6.3.0 → 6.5.0

package/dist/registry/archive/zip-reader.js

@@ -0,0 +1,256 @@
+/**
+ * A zip reader for exactly one archive: the connector library `registry pull`
+ * downloads.
+ *
+ * The SDK has no archive dependency and this keeps it that way. Node 22's
+ * `node:zlib` carries `inflateRawSync` and `crc32`, which is everything a
+ * reader needs for a zip that stores or deflates. The archive is self-produced
+ * by the pipeline (`zip -X` over a sorted file list): compression methods 0 and
+ * 8 only, no zip64, no data descriptors, no encryption, ASCII names. Everything
+ * outside that is refused rather than guessed at — this is a reader for the
+ * archive we make, not a general one.
+ *
+ * Layout, for the reader who has not seen a zip lately: every file's bytes sit
+ * behind a LOCAL FILE HEADER; after all of them comes the CENTRAL DIRECTORY,
+ * one header per entry pointing back at its local header; and the file ends
+ * with the END OF CENTRAL DIRECTORY record, which locates the directory and may
+ * be followed by an archive comment. Readers start at the end.
+ */
+import { crc32, inflateRawSync } from "node:zlib";
+/** The bytes are not a zip we can read: no end record, bad signatures, corrupt data. */
+export class NotAZip extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "NotAZip";
+    }
+}
+/** A well-formed zip that uses a feature this reader refuses (zip64, encryption, …). */
+export class UnsupportedArchive extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "UnsupportedArchive";
+    }
+}
+const SIG_LOCAL_HEADER = 0x04034b50;
+const SIG_CENTRAL_HEADER = 0x02014b50;
+const SIG_EOCD = 0x06054b50;
+const SIG_ZIP64_LOCATOR = 0x07064b50;
+const LOCAL_HEADER_SIZE = 30;
+const CENTRAL_HEADER_SIZE = 46;
+const EOCD_SIZE = 22;
+const ZIP64_LOCATOR_SIZE = 20;
+const MAX_COMMENT = 0xffff;
+const METHOD_STORED = 0;
+const METHOD_DEFLATE = 8;
+const FLAG_ENCRYPTED = 1 << 0;
+const FLAG_DATA_DESCRIPTOR = 1 << 3;
+const FLAG_UTF8_NAMES = 1 << 11;
+/** Bits 1–2 parameterise deflate and bit 11 names the encoding; nothing else is expected. */
+const FLAGS_UNDERSTOOD = (1 << 1) | (1 << 2) | FLAG_UTF8_NAMES;
+const ZIP64_EXTRA_ID = 0x0001;
+function view(buffer) {
+    return new DataView(buffer.buffer, buffer.byteOffset, buffer.byteLength);
+}
+/** Decode an entry name: UTF-8 when the archive says so, otherwise ASCII only. */
+function decodeName(bytes, flags) {
+    if (flags & FLAG_UTF8_NAMES) {
+        try {
+            return new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+        }
+        catch {
+            throw new NotAZip("entry name is not valid UTF-8");
+        }
+    }
+    // Without bit 11 the name is IBM437, which Node cannot decode and this archive
+    // never needs: its names are ASCII, where the two agree.
+    let name = "";
+    for (const byte of bytes) {
+        if (byte > 0x7f)
+            throw new UnsupportedArchive("non-ASCII entry name without the UTF-8 flag");
+        name += String.fromCharCode(byte);
+    }
+    return name;
+}
+/** Refuse the features this reader does not implement, before any byte is inflated. */
+function assertSupported(entry, extra) {
+    if (entry.flags & FLAG_ENCRYPTED) {
+        throw new UnsupportedArchive(`encrypted entry: ${entry.name}`);
+    }
+    // Python's zipfile tolerates bit 3 (sizes and CRC trail the data in a
+    // descriptor, the header carries zeros). This archive never sets it — the
+    // central directory always has the real values — so a set bit means a
+    // different producer, and refusing is the safer contract than trusting a
+    // header we would otherwise have to reconcile with the trailer.
+    if (entry.flags & FLAG_DATA_DESCRIPTOR) {
+        throw new UnsupportedArchive(`data descriptor entry: ${entry.name}`);
+    }
+    if (entry.flags & ~FLAGS_UNDERSTOOD & 0xffff) {
+        throw new UnsupportedArchive(`unrecognised general purpose flags 0x${entry.flags.toString(16)}: ${entry.name}`);
+    }
+    if (entry.method !== METHOD_STORED && entry.method !== METHOD_DEFLATE) {
+        throw new UnsupportedArchive(`compression method ${entry.method}: ${entry.name}`);
+    }
+    if (entry.compressedSize === 0xffffffff ||
+        entry.uncompressedSize === 0xffffffff ||
+        entry.localHeaderOffset === 0xffffffff) {
+        throw new UnsupportedArchive(`zip64 entry: ${entry.name}`);
+    }
+    // Extra fields are (id u16, size u16, data) records. Only the zip64 one matters.
+    const dv = view(extra);
+    let pos = 0;
+    while (pos + 4 <= extra.length) {
+        const id = dv.getUint16(pos, true);
+        const size = dv.getUint16(pos + 2, true);
+        if (id === ZIP64_EXTRA_ID)
+            throw new UnsupportedArchive(`zip64 entry: ${entry.name}`);
+        pos += 4 + size;
+    }
+    if (pos !== extra.length)
+        throw new NotAZip(`corrupt extra field: ${entry.name}`);
+}
+/**
+ * Find the End Of Central Directory record.
+ *
+ * It is the last 22 bytes when the archive has no comment; with one, it sits up
+ * to 65535 bytes earlier. We scan backwards for the signature and accept the
+ * first candidate whose comment length reaches exactly the end of the file, so
+ * a stray signature inside a comment cannot be mistaken for the record.
+ */
+function readEndRecord(buffer) {
+    const dv = view(buffer);
+    const floor = Math.max(0, buffer.length - EOCD_SIZE - MAX_COMMENT);
+    for (let pos = buffer.length - EOCD_SIZE; pos >= floor; pos -= 1) {
+        if (dv.getUint32(pos, true) !== SIG_EOCD)
+            continue;
+        const commentLength = dv.getUint16(pos + 20, true);
+        if (pos + EOCD_SIZE + commentLength !== buffer.length)
+            continue;
+        const thisDisk = dv.getUint16(pos + 4, true);
+        const directoryDisk = dv.getUint16(pos + 6, true);
+        const entriesOnDisk = dv.getUint16(pos + 8, true);
+        const totalEntries = dv.getUint16(pos + 10, true);
+        const directorySize = dv.getUint32(pos + 12, true);
+        const directoryOffset = dv.getUint32(pos + 16, true);
+        if (totalEntries === 0xffff ||
+            directorySize === 0xffffffff ||
+            directoryOffset === 0xffffffff ||
+            (pos >= ZIP64_LOCATOR_SIZE && dv.getUint32(pos - ZIP64_LOCATOR_SIZE, true) === SIG_ZIP64_LOCATOR)) {
+            throw new UnsupportedArchive("zip64 archive");
+        }
+        if (thisDisk !== 0 || directoryDisk !== 0 || entriesOnDisk !== totalEntries) {
+            throw new UnsupportedArchive("multi-disk archive");
+        }
+        if (directoryOffset + directorySize > pos) {
+            throw new NotAZip("central directory overruns the end record");
+        }
+        return { totalEntries, directorySize, directoryOffset };
+    }
+    throw new NotAZip("no end of central directory record found");
+}
+/**
+ * Every entry in the archive, in central-directory order, with the features we
+ * refuse already rejected. Throws {@link NotAZip} when the bytes are not a zip
+ * and {@link UnsupportedArchive} for one we decline to read.
+ */
+export function readZipEntries(buffer) {
+    const end = readEndRecord(buffer);
+    const dv = view(buffer);
+    const directoryEnd = end.directoryOffset + end.directorySize;
+    const entries = [];
+    let pos = end.directoryOffset;
+    for (let index = 0; index < end.totalEntries; index += 1) {
+        if (pos + CENTRAL_HEADER_SIZE > directoryEnd) {
+            throw new NotAZip(`central directory truncated at entry ${index}`);
+        }
+        if (dv.getUint32(pos, true) !== SIG_CENTRAL_HEADER) {
+            throw new NotAZip(`bad central directory signature at entry ${index}`);
+        }
+        const flags = dv.getUint16(pos + 8, true);
+        const method = dv.getUint16(pos + 10, true);
+        const crc = dv.getUint32(pos + 16, true);
+        const compressedSize = dv.getUint32(pos + 20, true);
+        const uncompressedSize = dv.getUint32(pos + 24, true);
+        const nameLength = dv.getUint16(pos + 28, true);
+        const extraLength = dv.getUint16(pos + 30, true);
+        const commentLength = dv.getUint16(pos + 32, true);
+        const externalAttr = dv.getUint32(pos + 38, true);
+        const localHeaderOffset = dv.getUint32(pos + 42, true);
+        const nameStart = pos + CENTRAL_HEADER_SIZE;
+        const extraStart = nameStart + nameLength;
+        const next = extraStart + extraLength + commentLength;
+        if (next > directoryEnd) {
+            throw new NotAZip(`central directory truncated at entry ${index}`);
+        }
+        const name = decodeName(buffer.subarray(nameStart, extraStart), flags);
+        const entry = {
+            name,
+            method,
+            flags,
+            crc32: crc,
+            compressedSize,
+            uncompressedSize,
+            localHeaderOffset,
+            externalAttr,
+            isDirectory: name.endsWith("/"),
+        };
+        assertSupported(entry, buffer.subarray(extraStart, extraStart + extraLength));
+        entries.push(entry);
+        pos = next;
+    }
+    return entries;
+}
+/**
+ * The uncompressed bytes of one entry, CRC-checked.
+ *
+ * The local header's name and extra lengths are read from the local header
+ * itself: a writer may store a different extra field there than in the central
+ * directory, so the directory's lengths cannot be used to find the data.
+ */
+export function entryData(buffer, entry) {
+    assertSupported(entry, new Uint8Array(0));
+    const dv = view(buffer);
+    const pos = entry.localHeaderOffset;
+    if (pos + LOCAL_HEADER_SIZE > buffer.length) {
+        throw new NotAZip(`local header out of range: ${entry.name}`);
+    }
+    if (dv.getUint32(pos, true) !== SIG_LOCAL_HEADER) {
+        throw new NotAZip(`bad local header signature: ${entry.name}`);
+    }
+    const nameLength = dv.getUint16(pos + 26, true);
+    const extraLength = dv.getUint16(pos + 28, true);
+    const nameStart = pos + LOCAL_HEADER_SIZE;
+    const dataStart = nameStart + nameLength + extraLength;
+    const dataEnd = dataStart + entry.compressedSize;
+    if (dataEnd > buffer.length) {
+        throw new NotAZip(`entry data out of range: ${entry.name}`);
+    }
+    // Python's zipfile makes this check too: the two names must agree, or the
+    // directory is pointing at somebody else's bytes.
+    const localName = decodeName(buffer.subarray(nameStart, nameStart + nameLength), entry.flags);
+    if (localName !== entry.name) {
+        throw new NotAZip(`file name in directory '${entry.name}' and header '${localName}' differ`);
+    }
+    const compressed = buffer.subarray(dataStart, dataEnd);
+    let data;
+    if (entry.method === METHOD_STORED) {
+        if (entry.compressedSize !== entry.uncompressedSize) {
+            throw new NotAZip(`stored entry sizes disagree: ${entry.name}`);
+        }
+        data = compressed;
+    }
+    else {
+        try {
+            data = inflateRawSync(compressed);
+        }
+        catch (error) {
+            throw new NotAZip(`bad deflate data for file '${entry.name}': ${error.message}`);
+        }
+    }
+    if (data.length !== entry.uncompressedSize) {
+        throw new NotAZip(`size mismatch for file '${entry.name}': expected ${entry.uncompressedSize}, got ${data.length}`);
+    }
+    if (crc32(data) !== entry.crc32) {
+        throw new NotAZip(`bad CRC-32 for file '${entry.name}'`);
+    }
+    return data;
+}

package/dist/registry/codecs/pyjson.d.ts

@@ -0,0 +1,62 @@
+/**
+ * A JSON writer with the exact output of Python's `json.dumps`.
+ *
+ * The connector library the Azure pipeline publishes, the overlay `prepare`
+ * writes into a project, and the string literals inside every generated
+ * descriptor module were all produced by `json.dumps`. Its defaults differ from
+ * `JSON.stringify` in ways that change bytes, and the library's sha256 is
+ * published precisely so an unchanged refresh is a no-op:
+ *
+ *   - `ensure_ascii=True` escapes every character outside `0x20..0x7e` as a
+ *     lowercase `\uXXXX`, astral characters as two surrogate escapes. 1,651 of
+ *     the 16,082 files in a current library carry such escapes.
+ *   - with `indent`, the item separator is `,` + newline and the key separator
+ *     is `: `; without, they are `, ` and `: ` — not `JSON.stringify`'s `,`/`:`.
+ *   - `sort_keys` orders by code point, not by UTF-16 code unit.
+ *   - a float prints as Python's `repr`: `1e-05`, `1e+16`, `2.5`, never `1e-5`.
+ *
+ * Everything the registry writes goes through this module, so the byte question
+ * is answered in one place and proven by one test: parse every library file,
+ * format it again, require the same bytes.
+ */
+export interface PyJsonOptions {
+    /** Spaces per level, as `json.dumps(indent=n)`. `undefined` means compact. */
+    indent?: number;
+    /** `json.dumps(sort_keys=True)`: keys ordered by code point at every level. */
+    sortKeys?: boolean;
+    /** `json.dumps(ensure_ascii=…)`; Python's default is `true`. */
+    ensureAscii?: boolean;
+    /**
+     * `json.dumps(separators=(item, key))`. Defaults follow Python: `(", ", ": ")`
+     * when compact, `(",", ": ")` when indented.
+     */
+    separators?: readonly [string, string];
+    /**
+     * Plain objects whose keys look like integers are refused, because
+     * `JSON.parse` and object literals both hoist such keys to the front in
+     * numeric order, so their insertion order is already lost. Pass a `Map` to
+     * carry an explicit order, or set this to accept the hoisted order knowingly.
+     */
+    allowIntegerKeys?: boolean;
+}
+/** Python `str` comparison: by Unicode code point, not UTF-16 code unit. */
+export declare function compareCodePoints(a: string, b: string): number;
+/** `repr(float)` for a JavaScript number that is not an integer. */
+export declare function pyFloatRepr(x: number): string;
+/** `json.dumps(str)`: the quoted, escaped form of one string. */
+export declare function pyJsonString(s: string, ensureAscii?: boolean): string;
+/**
+ * `json.dumps(value, **options)`.
+ *
+ * `undefined` values inside arrays become `null` (as `JSON.stringify` does);
+ * `undefined` object properties are omitted, matching the usual TypeScript
+ * habit of optional fields. Python has no `undefined`, so neither choice can
+ * disagree with it — but a `Map` may hold `undefined` deliberately and is
+ * written as `null` there, so prefer omitting keys over storing `undefined`.
+ */
+export declare function pyJsonStringify(value: unknown, options?: PyJsonOptions): string;
+/**
+ * `json.dump(value, file, indent=2)` followed by `file.write("\n")` — the
+ * shape every library entry, sidecar and index is written in.
+ */
+export declare function pyJsonDocument(value: unknown, options?: PyJsonOptions): string;

package/dist/registry/codecs/pyjson.js

@@ -0,0 +1,208 @@
+/**
+ * A JSON writer with the exact output of Python's `json.dumps`.
+ *
+ * The connector library the Azure pipeline publishes, the overlay `prepare`
+ * writes into a project, and the string literals inside every generated
+ * descriptor module were all produced by `json.dumps`. Its defaults differ from
+ * `JSON.stringify` in ways that change bytes, and the library's sha256 is
+ * published precisely so an unchanged refresh is a no-op:
+ *
+ *   - `ensure_ascii=True` escapes every character outside `0x20..0x7e` as a
+ *     lowercase `\uXXXX`, astral characters as two surrogate escapes. 1,651 of
+ *     the 16,082 files in a current library carry such escapes.
+ *   - with `indent`, the item separator is `,` + newline and the key separator
+ *     is `: `; without, they are `, ` and `: ` — not `JSON.stringify`'s `,`/`:`.
+ *   - `sort_keys` orders by code point, not by UTF-16 code unit.
+ *   - a float prints as Python's `repr`: `1e-05`, `1e+16`, `2.5`, never `1e-5`.
+ *
+ * Everything the registry writes goes through this module, so the byte question
+ * is answered in one place and proven by one test: parse every library file,
+ * format it again, require the same bytes.
+ */
+const INTEGER_LIKE = /^(?:0|[1-9][0-9]*)$/;
+/** Python `str` comparison: by Unicode code point, not UTF-16 code unit. */
+export function compareCodePoints(a, b) {
+    const ai = a[Symbol.iterator]();
+    const bi = b[Symbol.iterator]();
+    for (;;) {
+        const x = ai.next();
+        const y = bi.next();
+        if (x.done && y.done)
+            return 0;
+        if (x.done)
+            return -1;
+        if (y.done)
+            return 1;
+        const cx = x.value.codePointAt(0);
+        const cy = y.value.codePointAt(0);
+        if (cx !== cy)
+            return cx < cy ? -1 : 1;
+    }
+}
+/** `repr(float)` for a JavaScript number that is not an integer. */
+export function pyFloatRepr(x) {
+    if (Number.isNaN(x))
+        return "NaN";
+    if (x === Infinity)
+        return "Infinity";
+    if (x === -Infinity)
+        return "-Infinity";
+    if (x === 0)
+        return Object.is(x, -0) ? "-0.0" : "0.0";
+    const negative = x < 0;
+    // `toExponential()` with no argument yields the shortest digit string that
+    // round-trips, which is the same digit string Python's `repr` starts from.
+    const match = /^(\d)(?:\.(\d+))?e([+-]\d+)$/.exec(Math.abs(x).toExponential());
+    if (!match)
+        return String(x);
+    const digits = (match[1] + (match[2] ?? "")).replace(/0+$/, "") || "0";
+    const decimalPoint = parseInt(match[3], 10) + 1; // value = 0.<digits> × 10^decimalPoint
+    let body;
+    if (decimalPoint <= -4 || decimalPoint > 16) {
+        const mantissa = digits.length > 1 ? `${digits[0]}.${digits.slice(1)}` : digits;
+        const exponent = decimalPoint - 1;
+        body = `${mantissa}e${exponent < 0 ? "-" : "+"}${String(Math.abs(exponent)).padStart(2, "0")}`;
+    }
+    else if (decimalPoint <= 0) {
+        body = `0.${"0".repeat(-decimalPoint)}${digits}`;
+    }
+    else if (decimalPoint >= digits.length) {
+        body = `${digits}${"0".repeat(decimalPoint - digits.length)}.0`;
+    }
+    else {
+        body = `${digits.slice(0, decimalPoint)}.${digits.slice(decimalPoint)}`;
+    }
+    return negative ? `-${body}` : body;
+}
+function formatNumber(n) {
+    if (Number.isInteger(n) && !Object.is(n, -0)) {
+        // Python prints every digit of an int; JS switches to exponent form at 1e21.
+        return Math.abs(n) < 1e21 ? String(n) : BigInt(n).toString();
+    }
+    return pyFloatRepr(n);
+}
+const SHORT_ESCAPES = {
+    '"': '\\"',
+    "\\": "\\\\",
+    "\n": "\\n",
+    "\r": "\\r",
+    "\t": "\\t",
+    "\b": "\\b",
+    "\f": "\\f",
+};
+function hex4(unit) {
+    return `\\u${unit.toString(16).padStart(4, "0")}`;
+}
+/** `json.dumps(str)`: the quoted, escaped form of one string. */
+export function pyJsonString(s, ensureAscii = true) {
+    // Indexing a number or an object by position finds nothing and the loop
+    // below would answer `""` — an unquoted nothing in the middle of a generated
+    // module — where `json.dumps(5)` writes `5`. Callers with a non-string want
+    // `pyJsonStringify`; this one is for strings only, and says so.
+    if (typeof s !== "string") {
+        throw new TypeError(`pyJsonString: expected a string, got ${s === null ? "null" : typeof s}`);
+    }
+    let out = '"';
+    for (let i = 0; i < s.length; i++) {
+        const ch = s[i];
+        const short = SHORT_ESCAPES[ch];
+        if (short !== undefined) {
+            out += short;
+            continue;
+        }
+        const unit = s.charCodeAt(i);
+        if (unit < 0x20) {
+            out += hex4(unit);
+        }
+        else if (ensureAscii && unit > 0x7e) {
+            // Astral characters are two UTF-16 units and Python escapes them as the
+            // two surrogates, so escaping unit by unit is exactly right.
+            out += hex4(unit);
+        }
+        else {
+            out += ch;
+        }
+    }
+    return out + '"';
+}
+function entriesOf(value, options) {
+    let entries;
+    if (value instanceof Map) {
+        entries = [];
+        for (const [key, v] of value) {
+            if (typeof key !== "string") {
+                throw new TypeError(`pyjson: Map keys must be strings, got ${typeof key}`);
+            }
+            entries.push([key, v]);
+        }
+    }
+    else {
+        entries = Object.entries(value);
+        if (!options.allowIntegerKeys) {
+            const hoisted = entries.find(([key]) => INTEGER_LIKE.test(key));
+            if (hoisted) {
+                throw new TypeError(`pyjson: object key "${hoisted[0]}" looks like an integer, so JavaScript has ` +
+                    "already moved it to the front; carry the object as a Map to keep its order, " +
+                    "or pass allowIntegerKeys to accept the hoisted order.");
+            }
+        }
+    }
+    if (options.sortKeys) {
+        entries = [...entries].sort((a, b) => compareCodePoints(a[0], b[0]));
+    }
+    return entries;
+}
+/**
+ * `json.dumps(value, **options)`.
+ *
+ * `undefined` values inside arrays become `null` (as `JSON.stringify` does);
+ * `undefined` object properties are omitted, matching the usual TypeScript
+ * habit of optional fields. Python has no `undefined`, so neither choice can
+ * disagree with it — but a `Map` may hold `undefined` deliberately and is
+ * written as `null` there, so prefer omitting keys over storing `undefined`.
+ */
+export function pyJsonStringify(value, options = {}) {
+    const indent = options.indent;
+    const ensureAscii = options.ensureAscii ?? true;
+    const [itemSeparator, keySeparator] = options.separators ?? (indent === undefined ? [", ", ": "] : [",", ": "]);
+    const write = (v, depth) => {
+        if (v === null || v === undefined)
+            return "null";
+        switch (typeof v) {
+            case "string":
+                return pyJsonString(v, ensureAscii);
+            case "number":
+                return formatNumber(v);
+            case "boolean":
+                return v ? "true" : "false";
+            case "bigint":
+                return v.toString();
+            case "object":
+                break;
+            default:
+                throw new TypeError(`pyjson: cannot serialize a ${typeof v}`);
+        }
+        const inner = indent === undefined ? "" : `\n${" ".repeat(indent * (depth + 1))}`;
+        const closing = indent === undefined ? "" : `\n${" ".repeat(indent * depth)}`;
+        if (Array.isArray(v)) {
+            if (v.length === 0)
+                return "[]";
+            return `[${inner}${v.map((item) => write(item, depth + 1)).join(itemSeparator + inner)}${closing}]`;
+        }
+        const entries = entriesOf(v, options).filter(([, item]) => item !== undefined || v instanceof Map);
+        if (entries.length === 0)
+            return "{}";
+        const body = entries
+            .map(([key, item]) => `${pyJsonString(key, ensureAscii)}${keySeparator}${write(item, depth + 1)}`)
+            .join(itemSeparator + inner);
+        return `{${inner}${body}${closing}}`;
+    };
+    return write(value, 0);
+}
+/**
+ * `json.dump(value, file, indent=2)` followed by `file.write("\n")` — the
+ * shape every library entry, sidecar and index is written in.
+ */
+export function pyJsonDocument(value, options = {}) {
+    return `${pyJsonStringify(value, { indent: 2, ...options })}\n`;
+}

package/dist/registry/compat/compare.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Orderings that must match Python's `sorted()`.
+ *
+ * Python compares strings by code point and tuples element by element;
+ * `Array.prototype.sort` with no comparator compares UTF-16 code units of the
+ * stringified value. The two agree on ASCII and disagree above U+FFFF, which is
+ * why every sort that decides output bytes goes through one of these.
+ */
+export { compareCodePoints } from "../codecs/pyjson.js";
+/** A stable sort by one string key, code-point ordered. */
+export declare function sortedByCodePoint<T>(items: readonly T[], key: (item: T) => string): T[];
+/**
+ * `sorted(items, key=lambda x: (k1(x), k2(x), …))`: compare the first key, then
+ * the next, each by code point. Stable, like Python's.
+ */
+export declare function sortedByKeys<T>(items: readonly T[], ...keys: Array<(item: T) => string>): T[];
+/** `sorted(strings)`. */
+export declare function sortedStrings(items: Iterable<string>): string[];

package/dist/registry/compat/compare.js

@@ -0,0 +1,32 @@
+/**
+ * Orderings that must match Python's `sorted()`.
+ *
+ * Python compares strings by code point and tuples element by element;
+ * `Array.prototype.sort` with no comparator compares UTF-16 code units of the
+ * stringified value. The two agree on ASCII and disagree above U+FFFF, which is
+ * why every sort that decides output bytes goes through one of these.
+ */
+export { compareCodePoints } from "../codecs/pyjson.js";
+import { compareCodePoints } from "../codecs/pyjson.js";
+/** A stable sort by one string key, code-point ordered. */
+export function sortedByCodePoint(items, key) {
+    return [...items].sort((a, b) => compareCodePoints(key(a), key(b)));
+}
+/**
+ * `sorted(items, key=lambda x: (k1(x), k2(x), …))`: compare the first key, then
+ * the next, each by code point. Stable, like Python's.
+ */
+export function sortedByKeys(items, ...keys) {
+    return [...items].sort((a, b) => {
+        for (const key of keys) {
+            const c = compareCodePoints(key(a), key(b));
+            if (c !== 0)
+                return c;
+        }
+        return 0;
+    });
+}
+/** `sorted(strings)`. */
+export function sortedStrings(items) {
+    return [...items].sort(compareCodePoints);
+}

package/dist/registry/compat/paths.d.ts

@@ -0,0 +1,4 @@
+/** Replace the platform separator with `/`. */
+export declare function toPosix(p: string): string;
+/** `os.path.relpath(target, base)` spelled with `/`. */
+export declare function relativePosix(base: string, target: string): string;

package/dist/registry/compat/paths.js

@@ -0,0 +1,17 @@
+/**
+ * Path spelling for values that land inside files.
+ *
+ * `index.json` rows carry `path`, and the overlay index carries
+ * `descriptors/<key>/…`. Both are read as `/`-separated by every consumer, so
+ * they are forced to POSIX here regardless of the host, where Python's
+ * `os.path.relpath` would have used the OS separator.
+ */
+import { relative, sep } from "node:path";
+/** Replace the platform separator with `/`. */
+export function toPosix(p) {
+    return sep === "/" ? p : p.split(sep).join("/");
+}
+/** `os.path.relpath(target, base)` spelled with `/`. */
+export function relativePosix(base, target) {
+    return toPosix(relative(base, target));
+}

package/dist/registry/compat/pystr.d.ts

@@ -0,0 +1,50 @@
+/** `str.strip()` with no argument. */
+export declare function pyStrip(s: string): string;
+/** `str.rstrip()` with no argument. */
+export declare function pyRstrip(s: string): string;
+/** `str.strip(chars)`: strip any of the given characters from both ends. */
+export declare function pyStripChars(s: string, chars: string): string;
+/**
+ * `str(value)` for the JSON-shaped values the generators coerce: `True`,
+ * `None`, `1.0`, never `true`, `null`, `1`.
+ */
+export declare function pyStr(value: unknown): string;
+/**
+ * `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 declare function pyTitle(s: string): string;
+/** `s[:1].isupper()`: the first code point is an uppercase letter. */
+export declare function startsWithUpper(s: string): boolean;
+/** `s[:1].upper() + s[1:]`, slicing by code point. */
+export declare function upperFirst(s: string): string;
+/** `s[:1].lower() + s[1:]`, slicing by code point. */
+export declare function lowerFirst(s: string): string;
+/** `s.rsplit(sep, 1)[-1]`. */
+export declare function afterLast(s: string, sep: string): string;
+/** `s.rsplit(sep, 1)[0]` when `sep` occurs, else `s`. */
+export declare function beforeLast(s: string, sep: string): string;
+/** `s.split(sep, 1)` as a pair; the second element is `undefined` when absent. */
+export declare function splitOnce(s: string, sep: string): [string, string | undefined];
+/** `str.isdigit()` for ASCII digits, which is all the generators ever test. */
+export declare function isAsciiDigits(s: string): boolean;