@uipath/maestro-builder-sdk 6.4.0 → 6.5.0

package/dist/registry/prepare/retry.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Retry the other connections when a lookup exhausts one (flow-builder-sdk#744).
+ *
+ * Discovery lists the caller's own folder first and widens to the tenant only
+ * when that finds nothing — right for CHOOSING a connection, wrong for
+ * retrying one. When the own folder holds exactly one, the tenant's other
+ * connections are never looked at, so a `--resolve` that reads a collection to
+ * the end without a match reports a bad VALUE while the record sits in another
+ * folder's connection. Measured on two Jira connections where only the second
+ * carried project `TS`: the run failed on the first and never asked the second.
+ *
+ * Only an exhaustive miss demotes a connection. A transport or permission
+ * failure says nothing about whether the value exists; a scan stopped at the
+ * record cap did not reach the end; an unsearchable `by` is an authoring error
+ * that is the same on every connection. Those three pass through untouched.
+ *
+ * The "must not guess" rule is intact: {@link candidateConnections} lists and
+ * does not choose; what chooses is evidence. Exactly one candidate resolving
+ * everything wins. Two or more is a refusal listing them — the ids a lookup
+ * returns differ per connection, so "both work" is not a licence to pick. A
+ * connection the author pinned is never retried; the refusal names the
+ * alternatives instead.
+ *
+ * Ported from `_candidate_label`, `_probe_candidate` and `_retry_or_exit` in
+ * `prepare_connector.py`. The Python re-exec'd itself with `--connection-id
+ * <winner> --refresh-lookups`; here {@link retryOtherConnections} hands the
+ * winner back and `pipeline.ts` restores `bindings.json` and re-enters
+ * `prepareConnector` pinned to it — the same run, without a process boundary.
+ */
+import type { Reporter } from "../reporter.js";
+import type { UipClient } from "../uip/client.js";
+import { type ConnectionRow } from "./connections.js";
+import type { ResolutionPlan } from "./ledger.js";
+import { LookupExhausted, ResolutionRefusal } from "./resolve.js";
+/**
+ * Why a candidate did not resolve everything. The two kinds are kept apart all
+ * the way up, because only the first is evidence about the connection.
+ */
+export type ProbeOutcome = {
+    kind: "exhausted";
+    error: LookupExhausted;
+} | {
+    kind: "error";
+    error: ResolutionRefusal;
+};
+/**
+ * `_probe_candidate`: resolve every requested lookup against one connection.
+ *
+ * `undefined` when all of them resolve, else the FIRST reason they did not —
+ * the probe stops there, since a later lookup may depend on the one that just
+ * failed and every further call would be spent on a connection already known
+ * not to serve this run.
+ */
+export declare function probeCandidate(client: UipClient, connectorKey: string, plan: ResolutionPlan, connectionId: string): Promise<ProbeOutcome | undefined>;
+/** What the retry needs to know about the run that just exhausted a connection. */
+export interface RetryContext {
+    client: UipClient;
+    reporter: Reporter;
+    connectorKey: string;
+    /** The connection the exhausted lookup read. */
+    connectionId: string;
+    /** `--connection <name>`, passed on to the candidate listing as the Python did. */
+    connection?: string;
+    /**
+     * Whether the CALLER chose the connection (`--connection-id` / `--connection`).
+     * An explicit choice is never second-guessed: the retry is for a connection
+     * this command picked, not for one the author named.
+     */
+    pinned: boolean;
+}
+/**
+ * `_retry_or_exit`: the ONE other connection that resolves every requested
+ * lookup, or throw a {@link PrepareRefusal} explaining what was tried.
+ *
+ * Returns only on the path the Python re-exec'd on; every other path is a
+ * refusal carrying the Python's `sys.exit` text. The caller undoes the bindings
+ * this run wrote and re-runs pinned to the winner — re-running rather than
+ * switching in place is deliberate: the overlay and its lookup specs are
+ * described THROUGH a connection (`lookupSpecsFromOverlay`), so adopting a
+ * different connection after the describe would leave the overlay describing
+ * one connection while `bindings.json` names another.
+ */
+export declare function retryOtherConnections(ctx: RetryContext, plan: ResolutionPlan, first: LookupExhausted): Promise<ConnectionRow>;

package/dist/registry/prepare/retry.js

@@ -0,0 +1,109 @@
+import { ConnectionRefusal, candidateConnections, candidateListing } from "./connections.js";
+import { PrepareRefusal, candidateErrorLine, candidateExhaustedLine, candidateLabel, candidateListingFailedMessage, candidateResolvesAllLine, noConnectionResolvesMessage, onlyConnectionMessage, pinnedConnectionExhaustedMessage, severalConnectionsResolveMessage, tryingOtherConnectionsLine, } from "./messages.js";
+import { LookupExhausted, ResolutionRefusal, resolveOne } from "./resolve.js";
+import { pyGet, pyStrAny } from "./support.js";
+/**
+ * `_probe_candidate`: resolve every requested lookup against one connection.
+ *
+ * `undefined` when all of them resolve, else the FIRST reason they did not —
+ * the probe stops there, since a later lookup may depend on the one that just
+ * failed and every further call would be spent on a connection already known
+ * not to serve this run.
+ */
+export async function probeCandidate(client, connectorKey, plan, connectionId) {
+    const resolved = new Map();
+    for (const [field, by, value] of plan.ordered) {
+        try {
+            resolved.set(field, await resolveOne(client, connectorKey, plan.specs.get(field), field, by, value, connectionId, resolved));
+        }
+        catch (error) {
+            // `capped` is classified with the broken calls rather than with the
+            // exhaustive misses, for the same reason it does not demote the first
+            // connection: the scan stopped at the record cap without reaching the
+            // end, so "N record(s) scanned, no match" would state an absence
+            // nothing established. Reported as its own message instead, which says
+            // the cap stopped it and that the value may be further in.
+            if (error instanceof LookupExhausted && !error.capped)
+                return { kind: "exhausted", error };
+            if (error instanceof ResolutionRefusal)
+                return { kind: "error", error };
+            throw error;
+        }
+    }
+    return undefined;
+}
+/**
+ * `_retry_or_exit`: the ONE other connection that resolves every requested
+ * lookup, or throw a {@link PrepareRefusal} explaining what was tried.
+ *
+ * Returns only on the path the Python re-exec'd on; every other path is a
+ * refusal carrying the Python's `sys.exit` text. The caller undoes the bindings
+ * this run wrote and re-runs pinned to the winner — re-running rather than
+ * switching in place is deliberate: the overlay and its lookup specs are
+ * described THROUGH a connection (`lookupSpecsFromOverlay`), so adopting a
+ * different connection after the describe would leave the overlay describing
+ * one connection while `bindings.json` names another.
+ */
+export async function retryOtherConnections(ctx, plan, first) {
+    const sameId = (row) => pyStrAny(pyGet(row, "Id", null)) === pyStrAny(ctx.connectionId);
+    if (ctx.pinned) {
+        // The alternatives are still named, because the whole cost of this bug
+        // was not knowing they existed. INTENTIONAL DIVERGENCE: the Python did not
+        // guard this listing, so a listing failure here surfaced as a traceback
+        // that swallowed the lookup failure the author asked about; it is reported
+        // the way the unpinned branch reports it instead.
+        let others;
+        try {
+            others = (await candidateConnections(ctx.client, ctx.connectorKey)).filter((row) => !sameId(row));
+        }
+        catch (error) {
+            if (!(error instanceof ConnectionRefusal))
+                throw error;
+            throw new PrepareRefusal(candidateListingFailedMessage(first.message, error), "LOOKUP_EXHAUSTED_PINNED");
+        }
+        throw new PrepareRefusal(pinnedConnectionExhaustedMessage(first.message, ctx.connectorKey, others.length, candidateListing(others)), "LOOKUP_EXHAUSTED_PINNED");
+    }
+    let candidates;
+    try {
+        candidates = await candidateConnections(ctx.client, ctx.connectorKey, ctx.connection);
+    }
+    catch (error) {
+        if (!(error instanceof ConnectionRefusal))
+            throw error;
+        // The listing itself failed; report the original lookup failure, which is
+        // the thing the author asked about.
+        throw new PrepareRefusal(candidateListingFailedMessage(first.message, error), "LOOKUP_EXHAUSTED");
+    }
+    const others = candidates.filter((row) => !sameId(row));
+    if (others.length === 0) {
+        throw new PrepareRefusal(onlyConnectionMessage(first.message, ctx.connectorKey), "LOOKUP_EXHAUSTED_ONLY_CONNECTION");
+    }
+    ctx.reporter.info(tryingOtherConnectionsLine(first.field, others.length, ctx.connectorKey));
+    const winners = [];
+    const report = [];
+    for (const row of others) {
+        const outcome = await probeCandidate(ctx.client, ctx.connectorKey, plan, pyStrAny(pyGet(row, "Id", null)));
+        const label = candidateLabel(row);
+        if (outcome === undefined) {
+            winners.push(row);
+            report.push(candidateResolvesAllLine(label, plan.ordered.length));
+        }
+        else if (outcome.kind === "exhausted") {
+            report.push(candidateExhaustedLine(label, outcome.error.field, outcome.error.scanned));
+        }
+        else {
+            report.push(candidateErrorLine(label, outcome.error));
+        }
+    }
+    if (winners.length === 1)
+        return winners[0];
+    if (winners.length > 1) {
+        throw new PrepareRefusal(severalConnectionsResolveMessage(winners.length, ctx.connectorKey, candidateListing(winners)), "LOOKUP_EXHAUSTED_AMBIGUOUS");
+    }
+    // Nothing resolved anywhere. Report every candidate and what it held, the
+    // one connection first, so the reader can see the value really is absent
+    // rather than guess which connection was asked.
+    const original = candidates.find(sameId) ?? { Name: ctx.connectionId, Folder: "?" };
+    const lines = [candidateExhaustedLine(candidateLabel(original), first.field, first.scanned), ...report];
+    throw new PrepareRefusal(noConnectionResolvesMessage(ctx.connectorKey, first, lines, ctx.connectionId), "LOOKUP_EXHAUSTED_EVERYWHERE");
+}

package/dist/registry/prepare/source-import.d.ts

@@ -0,0 +1,54 @@
+/**
+ * `import … from "<specifier>"` — the specifier is group 3, quotes preserved.
+ * Anchored to a real import statement on purpose (see the module comment).
+ */
+export declare const IMPORT_PATTERN: RegExp;
+/** Where a `.flow.ts` will not be: generated output and installed packages. */
+export declare const SOURCE_SKIP_DIRS: ReadonlySet<string>;
+/**
+ * `Path(p).resolve()` with `strict=False`: absolute, `..` collapsed, and
+ * symlinks followed as far as the path exists. Both sides of every comparison
+ * go through this, so `/var/...` and `/private/var/...` name one file.
+ */
+export declare function canonicalPath(p: string): string;
+/**
+ * `_resolves_to`: does `specifier`, read from `source`, name the file `target`?
+ * A bare package specifier never does — it is not our overlay.
+ */
+export declare function resolvesTo(specifier: string, source: string, target: string): boolean;
+/**
+ * `_sources_importing`: every `*.flow.ts` under `root` whose import resolves
+ * to `baked`. Selection is by CONTENT rather than "the single flow in this
+ * directory": a workspace with three flows, one of which uses this connector,
+ * has one correct answer and this finds it.
+ */
+export declare function sourcesImporting(baked: string, root: string): string[];
+/**
+ * `_repoint_import`: point `source`'s import at the prepared descriptor and
+ * return the new specifier, or `undefined` when nothing changed.
+ *
+ * Only the quoted path changes. The rest of the statement — the named
+ * bindings, an `as` alias, the quote style — is carried through untouched,
+ * which is the whole difference between this and the find-and-replace it
+ * replaces.
+ */
+export declare function repointImport(source: string, baked: string, prepared: string): string | undefined;
+export interface RepointOptions {
+    /** The overlay directory (`--out`), relative to `cwd` or absolute. */
+    out: string;
+    connectorKey: string;
+    /** The project root the Python read as `Path.cwd()`. Defaults to the process's. */
+    cwd?: string;
+    /** `--source`: the one `.flow.ts` to repoint, settling any ambiguity. */
+    source?: string | null;
+    /** `--no-source-rewrite`: print the import line instead of editing the source. */
+    noSourceRewrite?: boolean;
+}
+/**
+ * `_repoint_source`: repoint the author's import, or say why it was left
+ * alone. The lines come back unprefixed; the caller prints each as
+ * `prepare-connector: <line>`. An empty list means nothing to report — no
+ * prepared module, no candidate, or a second run that finds no import left to
+ * change.
+ */
+export declare function repointSource(options: RepointOptions): string[];

package/dist/registry/prepare/source-import.js

@@ -0,0 +1,192 @@
+/**
+ * Repoint the author's `import … from './connectors/<key>.ts'` at the prepared
+ * descriptor, or explain why it was left alone.
+ *
+ * `prepare` already writes `bindings.json`, the overlay descriptor and
+ * `resolutions.json`; the one thing it did not do was update the import naming
+ * the descriptor it had just replaced. That left a mechanical edit — one
+ * specifier, one file, exactly one right answer — to the caller, who has
+ * strictly less information than this command does. Measured cost: an agent
+ * reaches for `sed 's|./connectors/|./connectors-local/|'`, which repoints
+ * connectors that were never prepared and breaks the flow with `Cannot find
+ * module` (#704).
+ *
+ * Imports are matched as RESOLVED PATHS, never as text, and only inside a real
+ * import STATEMENT — the same text in a comment, or in the import of a
+ * connector this run did not prepare, is left exactly as it was. Ambiguity
+ * keeps today's behaviour: zero candidates or several, and nothing is written.
+ *
+ * Ported from `_IMPORT_RE`, `_resolves_to`, `_sources_importing`,
+ * `_repoint_import` and `_repoint_source` in `prepare_connector.py`.
+ */
+import { readFileSync, readdirSync, realpathSync, statSync, writeFileSync } from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
+import { compareCodePoints } from "../compat/compare.js";
+import { relativePosix } from "../compat/paths.js";
+import { repointedLine, severalSourcesLine, sourceNotAFileLine } from "./messages.js";
+/**
+ * `import … from "<specifier>"` — the specifier is group 3, quotes preserved.
+ * Anchored to a real import statement on purpose (see the module comment).
+ */
+export const IMPORT_PATTERN = /(^\s*import\s[^;'"]*?\sfrom\s*)(['"])([^'"]+)(\2)/gm;
+/** Where a `.flow.ts` will not be: generated output and installed packages. */
+export const SOURCE_SKIP_DIRS = new Set(["node_modules", "connectors", "connectors-local", ".git"]);
+/**
+ * `Path(p).resolve()` with `strict=False`: absolute, `..` collapsed, and
+ * symlinks followed as far as the path exists. Both sides of every comparison
+ * go through this, so `/var/...` and `/private/var/...` name one file.
+ */
+export function canonicalPath(p) {
+    const absolute = resolve(p);
+    try {
+        return realpathSync.native(absolute);
+    }
+    catch {
+        const parent = dirname(absolute);
+        if (parent === absolute)
+            return absolute;
+        return join(canonicalPath(parent), basename(absolute));
+    }
+}
+/**
+ * `_resolves_to`: does `specifier`, read from `source`, name the file `target`?
+ * A bare package specifier never does — it is not our overlay.
+ */
+export function resolvesTo(specifier, source, target) {
+    if (!specifier.startsWith("."))
+        return false;
+    return canonicalPath(resolve(dirname(source), specifier)) === canonicalPath(target);
+}
+/** `sorted(Path…)`: paths compare part by part, each part by code point. */
+function comparePaths(a, b) {
+    for (let i = 0; i < Math.min(a.length, b.length); i++) {
+        const c = compareCodePoints(a[i], b[i]);
+        if (c !== 0)
+            return c;
+    }
+    return a.length - b.length;
+}
+/** Every `*.flow.ts` file under `root`, sorted, skipping the directories a source is never in. */
+function flowSources(root) {
+    const found = [];
+    const walk = (dir, parts) => {
+        let children;
+        try {
+            children = readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const child of children) {
+            if (child.isDirectory()) {
+                if (!SOURCE_SKIP_DIRS.has(child.name))
+                    walk(join(dir, child.name), [...parts, child.name]);
+            }
+            else if (child.isFile() && child.name.endsWith(".flow.ts")) {
+                found.push([...parts, child.name]);
+            }
+        }
+    };
+    walk(root, []);
+    found.sort(comparePaths);
+    return found.map((parts) => join(root, ...parts));
+}
+/**
+ * `_sources_importing`: every `*.flow.ts` under `root` whose import resolves
+ * to `baked`. Selection is by CONTENT rather than "the single flow in this
+ * directory": a workspace with three flows, one of which uses this connector,
+ * has one correct answer and this finds it.
+ */
+export function sourcesImporting(baked, root) {
+    const found = [];
+    for (const path of flowSources(root)) {
+        let text;
+        try {
+            text = readFileSync(path, "utf8");
+        }
+        catch {
+            continue;
+        }
+        for (const match of text.matchAll(IMPORT_PATTERN)) {
+            if (resolvesTo(match[3], path, baked)) {
+                found.push(path);
+                break;
+            }
+        }
+    }
+    return found;
+}
+/**
+ * `_repoint_import`: point `source`'s import at the prepared descriptor and
+ * return the new specifier, or `undefined` when nothing changed.
+ *
+ * Only the quoted path changes. The rest of the statement — the named
+ * bindings, an `as` alias, the quote style — is carried through untouched,
+ * which is the whole difference between this and the find-and-replace it
+ * replaces.
+ */
+export function repointImport(source, baked, prepared) {
+    let text;
+    try {
+        text = readFileSync(source, "utf8");
+    }
+    catch {
+        return undefined;
+    }
+    let specifier = relativePosix(dirname(source), prepared);
+    if (!specifier.startsWith("."))
+        specifier = `./${specifier}`;
+    let changed = false;
+    const rewritten = text.replace(IMPORT_PATTERN, (whole, head, quote, spec, tail) => {
+        if (!resolvesTo(spec, source, baked))
+            return whole;
+        changed = true;
+        return `${head}${quote}${specifier}${tail}`;
+    });
+    if (!changed || rewritten === text)
+        return undefined;
+    writeFileSync(source, rewritten, "utf8");
+    return specifier;
+}
+function isFile(path) {
+    try {
+        return statSync(path).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * `_repoint_source`: repoint the author's import, or say why it was left
+ * alone. The lines come back unprefixed; the caller prints each as
+ * `prepare-connector: <line>`. An empty list means nothing to report — no
+ * prepared module, no candidate, or a second run that finds no import left to
+ * change.
+ */
+export function repointSource(options) {
+    const cwd = options.cwd ?? process.cwd();
+    const prepared = canonicalPath(resolve(cwd, options.out, `${options.connectorKey}.ts`));
+    if (options.noSourceRewrite || !isFile(prepared))
+        return [];
+    const root = canonicalPath(cwd);
+    const baked = canonicalPath(join(root, "connectors", `${options.connectorKey}.ts`));
+    let candidates;
+    if (options.source) {
+        candidates = [canonicalPath(resolve(cwd, options.source))];
+        if (!isFile(candidates[0]))
+            return [sourceNotAFileLine(options.source)];
+    }
+    else {
+        candidates = sourcesImporting(baked, root);
+    }
+    if (candidates.length === 0)
+        return [];
+    if (candidates.length > 1) {
+        return [severalSourcesLine(candidates.map((c) => relativePosix(root, c)))];
+    }
+    const source = candidates[0];
+    const specifier = repointImport(source, baked, prepared);
+    if (specifier === undefined)
+        return [];
+    return [repointedLine(relativePosix(root, source), specifier)];
+}

package/dist/registry/prepare/support.d.ts

@@ -0,0 +1,41 @@
+export declare function isPlainObject(value: unknown): value is Record<string, unknown>;
+/** `bool(value)` for JSON-shaped values: `[]`, `{}`, `""`, `0`, `None` are false. */
+export declare function pyTruthy(value: unknown): boolean;
+/** `a or b`. */
+export declare function pyOr<A, B>(a: A, b: B): A | B;
+/** `mapping.get(key, default)`: the value when the key is PRESENT (even as `null`), else the default. */
+export declare function pyGet<D>(mapping: Record<string, unknown>, key: string, dflt: D): unknown | D;
+/** `type(value).__name__` for JSON-shaped values. */
+export declare function pyTypeName(value: unknown): string;
+/** `repr(str)`: single quotes unless the text has a `'` and no `"`; escapes as CPython does. */
+export declare function pyReprString(s: string): string;
+/** `repr(value)` for JSON-shaped values (`'x'`, `True`, `None`, `[1, 'a']`, `{'k': 1}`). */
+export declare function pyRepr(value: unknown): string;
+/** `str(value)` for any JSON-shaped value: `pyStr` for scalars, `repr` for containers, as Python does. */
+export declare function pyStrAny(value: unknown): string;
+/** `str.split()` with no argument: runs of whitespace, empties dropped. */
+export declare function pySplitWhitespace(s: string): string[];
+/**
+ * `os.path.join(a, b)` for a relative `b`: `a` + separator + `b`, with NO
+ * normalisation — `./connectors-local` stays `./connectors-local`.
+ *
+ * For the lines `prepare` prints, not for opening files. The Python printed
+ * every path as the author typed it (`args.out`, `args.bindings`), and
+ * `node:path`'s `join` would rewrite `./connectors-local/resolutions.json` as
+ * `connectors-local/resolutions.json`; the pipeline resolves a real path for
+ * the file system separately.
+ */
+export declare function pyPathJoin(a: string, b: string): string;
+/**
+ * `str(pathlib.Path(p))`: redundant separators and `.` components collapse,
+ * a trailing separator goes, `..` and a leading `/` stay, and an empty path
+ * is `.`. The descriptor generator printed its output directory this way.
+ */
+export declare function pyPathlibStr(p: string): string;
+/**
+ * Why `stdout` is not the JSON envelope a caller wanted — the text the Python
+ * put after "was not JSON:". Python printed `json.JSONDecodeError`'s message
+ * (`Expecting value: line 1 column 1 (char 0)`); this prints V8's, or names the
+ * type when the text parsed but is not an object.
+ */
+export declare function notJsonReason(stdout: string): string;

package/dist/registry/prepare/support.js

@@ -0,0 +1,178 @@
+/**
+ * Python value semantics the prepare helpers lean on, beyond `compat/pystr`.
+ *
+ * `_connections`, `_objects` and `_resolve` call `str()`, `repr()` and `bool()`
+ * on whatever a `uip` listing handed them and format the result into a refusal
+ * an agent reads. `pyStr` refuses containers on purpose (the generators never
+ * stringify one deliberately); here a container is a fact about the tenant's
+ * data and must render the way Python rendered it, not crash the refusal that
+ * was about to explain it. Everything in this module is private to `prepare/`.
+ */
+import { sep } from "node:path";
+import { pyStr } from "../compat/pystr.js";
+export function isPlainObject(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        !Array.isArray(value) &&
+        !(value instanceof Map) &&
+        !(value instanceof Set));
+}
+/** `bool(value)` for JSON-shaped values: `[]`, `{}`, `""`, `0`, `None` are false. */
+export function pyTruthy(value) {
+    if (value === null || value === undefined)
+        return false;
+    if (typeof value === "boolean")
+        return value;
+    if (typeof value === "number")
+        return value !== 0;
+    if (typeof value === "string")
+        return value.length > 0;
+    if (Array.isArray(value))
+        return value.length > 0;
+    if (value instanceof Map || value instanceof Set)
+        return value.size > 0;
+    if (typeof value === "object")
+        return Object.keys(value).length > 0;
+    return true;
+}
+/** `a or b`. */
+export function pyOr(a, b) {
+    return pyTruthy(a) ? a : b;
+}
+/** `mapping.get(key, default)`: the value when the key is PRESENT (even as `null`), else the default. */
+export function pyGet(mapping, key, dflt) {
+    return Object.prototype.hasOwnProperty.call(mapping, key) ? mapping[key] : dflt;
+}
+/** `type(value).__name__` for JSON-shaped values. */
+export function pyTypeName(value) {
+    if (value === null || value === undefined)
+        return "NoneType";
+    if (Array.isArray(value))
+        return "list";
+    switch (typeof value) {
+        case "string":
+            return "str";
+        case "boolean":
+            return "bool";
+        case "number":
+            return Number.isInteger(value) ? "int" : "float";
+        case "bigint":
+            return "int";
+        case "object":
+            return "dict";
+        default:
+            return typeof value;
+    }
+}
+/**
+ * `str.isprintable()` is false for these categories (and true for the ASCII
+ * space, which is in Zs). `repr` escapes exactly the non-printable ones.
+ */
+const NOT_PRINTABLE = /[\p{Cc}\p{Cf}\p{Cs}\p{Co}\p{Cn}\p{Zl}\p{Zp}\p{Zs}]/u;
+function hex(codePoint, width) {
+    return codePoint.toString(16).padStart(width, "0");
+}
+/** `repr(str)`: single quotes unless the text has a `'` and no `"`; escapes as CPython does. */
+export function pyReprString(s) {
+    const quote = s.includes("'") && !s.includes('"') ? '"' : "'";
+    let out = quote;
+    for (const ch of s) {
+        if (ch === quote || ch === "\\")
+            out += `\\${ch}`;
+        else if (ch === "\n")
+            out += "\\n";
+        else if (ch === "\r")
+            out += "\\r";
+        else if (ch === "\t")
+            out += "\\t";
+        else if (ch !== " " && NOT_PRINTABLE.test(ch)) {
+            const codePoint = ch.codePointAt(0);
+            out +=
+                codePoint < 0x100
+                    ? `\\x${hex(codePoint, 2)}`
+                    : codePoint < 0x10000
+                        ? `\\u${hex(codePoint, 4)}`
+                        : `\\U${hex(codePoint, 8)}`;
+        }
+        else
+            out += ch;
+    }
+    return out + quote;
+}
+/** `repr(value)` for JSON-shaped values (`'x'`, `True`, `None`, `[1, 'a']`, `{'k': 1}`). */
+export function pyRepr(value) {
+    if (typeof value === "string")
+        return pyReprString(value);
+    if (Array.isArray(value))
+        return `[${value.map(pyRepr).join(", ")}]`;
+    if (value instanceof Map) {
+        return `{${[...value.entries()].map(([k, v]) => `${pyRepr(k)}: ${pyRepr(v)}`).join(", ")}}`;
+    }
+    if (isPlainObject(value)) {
+        return `{${Object.entries(value)
+            .map(([k, v]) => `${pyReprString(k)}: ${pyRepr(v)}`)
+            .join(", ")}}`;
+    }
+    return pyStr(value);
+}
+/** `str(value)` for any JSON-shaped value: `pyStr` for scalars, `repr` for containers, as Python does. */
+export function pyStrAny(value) {
+    if (typeof value === "string")
+        return value;
+    if (Array.isArray(value) || value instanceof Map || isPlainObject(value))
+        return pyRepr(value);
+    return pyStr(value);
+}
+/**
+ * The characters `str.isspace()` is true for — the set `str.split()` splits
+ * on. Same table as `compat/pystr`'s `PY_SPACE`, which is not exported.
+ */
+const PY_WHITESPACE_RUN = /[\t\n\r\u000b\u000c\u001c\u001d\u001e\u001f \u0085\u00a0\u1680\u2000-\u200a\u2028\u2029\u202f\u205f\u3000]+/u;
+/** `str.split()` with no argument: runs of whitespace, empties dropped. */
+export function pySplitWhitespace(s) {
+    return s.split(PY_WHITESPACE_RUN).filter((token) => token !== "");
+}
+/**
+ * `os.path.join(a, b)` for a relative `b`: `a` + separator + `b`, with NO
+ * normalisation — `./connectors-local` stays `./connectors-local`.
+ *
+ * For the lines `prepare` prints, not for opening files. The Python printed
+ * every path as the author typed it (`args.out`, `args.bindings`), and
+ * `node:path`'s `join` would rewrite `./connectors-local/resolutions.json` as
+ * `connectors-local/resolutions.json`; the pipeline resolves a real path for
+ * the file system separately.
+ */
+export function pyPathJoin(a, b) {
+    if (a === "")
+        return b;
+    return a.endsWith("/") || a.endsWith(sep) ? `${a}${b}` : `${a}${sep}${b}`;
+}
+/**
+ * `str(pathlib.Path(p))`: redundant separators and `.` components collapse,
+ * a trailing separator goes, `..` and a leading `/` stay, and an empty path
+ * is `.`. The descriptor generator printed its output directory this way.
+ */
+export function pyPathlibStr(p) {
+    const absolute = p.startsWith("/");
+    const parts = p.split(/[\\/]+/).filter((part) => part !== "" && part !== ".");
+    const body = parts.join(sep);
+    if (absolute)
+        return `${sep}${body}`;
+    return body || ".";
+}
+/**
+ * Why `stdout` is not the JSON envelope a caller wanted — the text the Python
+ * put after "was not JSON:". Python printed `json.JSONDecodeError`'s message
+ * (`Expecting value: line 1 column 1 (char 0)`); this prints V8's, or names the
+ * type when the text parsed but is not an object.
+ */
+export function notJsonReason(stdout) {
+    let parsed;
+    try {
+        parsed = JSON.parse(stdout);
+    }
+    catch (error) {
+        return error instanceof Error ? error.message : String(error);
+    }
+    return `expected a JSON object, found ${pyTypeName(parsed)}`;
+}