@uipath/maestro-builder-sdk 6.3.0 → 6.5.0

package/dist/registry/library-build/cli.js

@@ -0,0 +1,182 @@
+/**
+ * `registry build-library`: the Azure pipeline's library generator as a verb.
+ *
+ * This is `generate_library_json.py`'s `parse_args()` plus the part of `main()`
+ * that {@link buildLibrary} deliberately leaves out — the two banner lines, the
+ * cache lifecycle, and the exit code. The flag surface is the Python's one for
+ * one, because the pipeline that calls it is a YAML file nobody wants to edit
+ * twice; a flag argparse would have rejected is rejected here with exit 2.
+ *
+ * Exposed as `run(argv)` so the umbrella CLI can mount it the way it mounts
+ * every other registry verb. The optional `deps` argument exists for tests: a
+ * replay client and a recording reporter make the whole verb run without a
+ * tenant, which is the only way its exit codes can be pinned.
+ */
+import { rmSync } from "node:fs";
+import { UsageError, exitCodeOf, messageOf } from "../errors.js";
+import { consoleReporter } from "../reporter.js";
+import { OfflineUipClient, defaultUipClient } from "../uip/client.js";
+import { FsResponseCache } from "../uip/response-cache.js";
+import { buildLibrary, parseConnectorsFlag } from "./build.js";
+/** argparse's defaults, verbatim. */
+export const DEFAULTS = {
+    outputDir: "./library",
+    cacheDir: "./.registry-cache",
+    isCacheDir: "./.is-cache",
+    connectorsCacheDir: "./.is-connectors-cache",
+    catalogScope: "all",
+    concurrency: 10,
+};
+const CATALOG_SCOPES = ["all", "tier1", "tier2"];
+const USAGE = [
+    "Usage: flow-sdk registry build-library [--output-dir <dir>] [--cache-dir <dir>] [--is-cache-dir <dir>]",
+    "                                      [--connectors-cache-dir <dir>] [--triggers-output <path>]",
+    "                                      [--connectors a,b] [--catalog-scope all|tier1|tier2] [--concurrency <n>]",
+    "                                      [--skip-enrichment] [--skip-connector-enrichment]",
+    "                                      [--skip-generic-expansion] [--keep-temp] [--offline]",
+].join("\n");
+const VALUED = new Set([
+    "--output-dir",
+    "--cache-dir",
+    "--is-cache-dir",
+    "--connectors-cache-dir",
+    "--triggers-output",
+    "--connectors",
+    "--catalog-scope",
+    "--concurrency",
+]);
+const SWITCHES = new Set(["--skip-enrichment", "--skip-connector-enrichment", "--skip-generic-expansion", "--keep-temp", "--offline"]);
+/**
+ * `int(text)`, narrowed on purpose: an optionally signed run of ASCII digits,
+ * ASCII whitespace allowed around it. Python's `int()` also takes `_`
+ * separators (`1_0`) and non-ASCII decimal digits (`١٠`); a pipeline YAML
+ * never spells a worker count that way, and accepting it would only make a
+ * typo parse. What IS mirrored is the refusal of zero and negatives, below.
+ *
+ * The sign is only reachable as `--concurrency=-3`: the loop below reads any
+ * `-…` as the next flag, so `--concurrency -3` is "expected one argument"
+ * where argparse's negative-number special case gave `int("-3")`. Both are a
+ * usage error and exit 2 before the build starts, and the alternative is to
+ * change how every valued flag reads its value for a number that is then
+ * refused anyway.
+ */
+const PY_INT = /^\s*[+-]?\d+\s*$/;
+/**
+ * The options for this argv, or a {@link UsageError} carrying argparse's
+ * wording. Both `--flag value` and `--flag=value` are accepted, as argparse
+ * accepts them; anything that is neither a known flag nor a flag's value is an
+ * unrecognized argument, because the generator takes no positionals.
+ */
+export function parseArgs(argv) {
+    const values = new Map();
+    const switches = new Set();
+    const unrecognized = [];
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        const eq = arg.startsWith("--") ? arg.indexOf("=") : -1;
+        const name = eq >= 0 ? arg.slice(0, eq) : arg;
+        if (VALUED.has(name)) {
+            if (eq >= 0) {
+                values.set(name, arg.slice(eq + 1));
+                continue;
+            }
+            const next = argv[i + 1];
+            // argparse refuses to read another flag as a value.
+            if (next === undefined || (next.startsWith("-") && next !== "-")) {
+                throw new UsageError(`argument ${name}: expected one argument`);
+            }
+            values.set(name, next);
+            i += 1;
+        }
+        else if (SWITCHES.has(name) && eq < 0) {
+            switches.add(name);
+        }
+        else {
+            unrecognized.push(arg);
+        }
+    }
+    if (unrecognized.length > 0)
+        throw new UsageError(`unrecognized arguments: ${unrecognized.join(" ")}`);
+    const catalogScope = values.get("--catalog-scope") ?? DEFAULTS.catalogScope;
+    if (!CATALOG_SCOPES.includes(catalogScope)) {
+        throw new UsageError(`argument --catalog-scope: invalid choice: '${catalogScope}' (choose from ${CATALOG_SCOPES.map((s) => `'${s}'`).join(", ")})`);
+    }
+    const concurrencyText = values.get("--concurrency");
+    let concurrency = DEFAULTS.concurrency;
+    if (concurrencyText !== undefined) {
+        if (!PY_INT.test(concurrencyText))
+            throw new UsageError(`argument --concurrency: invalid int value: '${concurrencyText}'`);
+        concurrency = parseInt(concurrencyText, 10);
+        // argparse accepted `0` and `-3`; the first `ThreadPoolExecutor(max_workers=…)`
+        // then raised `ValueError: max_workers must be greater than 0` — a traceback
+        // and exit 1, minutes into the build. The refusal is kept, moved to where
+        // the flag is read: a usage error (exit 2) before anything runs.
+        if (concurrency < 1)
+            throw new UsageError(`argument --concurrency: must be greater than 0, got ${concurrency}`);
+    }
+    // `if args.connectors:` tested the RAW string, so `--connectors ""` is a
+    // full build while `--connectors ,` is a curated subset of nothing. The
+    // split-and-strip happens only once the string has passed that gate.
+    const connectorsText = values.get("--connectors");
+    const connectors = connectorsText ? parseConnectorsFlag(connectorsText) : undefined;
+    return {
+        outputDir: values.get("--output-dir") ?? DEFAULTS.outputDir,
+        cacheDir: values.get("--cache-dir") ?? DEFAULTS.cacheDir,
+        isCacheDir: values.get("--is-cache-dir") ?? DEFAULTS.isCacheDir,
+        connectorsCacheDir: values.get("--connectors-cache-dir") ?? DEFAULTS.connectorsCacheDir,
+        ...(values.has("--triggers-output") ? { triggersOutput: values.get("--triggers-output") } : {}),
+        ...(connectors !== undefined ? { connectors } : {}),
+        catalogScope: catalogScope,
+        concurrency,
+        skipEnrichment: switches.has("--skip-enrichment"),
+        skipConnectorEnrichment: switches.has("--skip-connector-enrichment"),
+        skipGenericExpansion: switches.has("--skip-generic-expansion"),
+        keepTemp: switches.has("--keep-temp"),
+        offline: switches.has("--offline"),
+    };
+}
+export async function run(argv, deps = {}) {
+    if (argv.includes("--help") || argv.includes("-h")) {
+        console.log(USAGE);
+        return 0;
+    }
+    let options;
+    try {
+        options = parseArgs(argv);
+    }
+    catch (error) {
+        console.error(messageOf(error));
+        console.error(USAGE);
+        return 2;
+    }
+    const reporter = deps.reporter ?? consoleReporter;
+    reporter.info(`Cache directory: ${options.cacheDir}`);
+    reporter.info(`Output directory: ${options.outputDir}`);
+    try {
+        await buildLibrary(options, {
+            client: deps.client ?? (options.offline ? new OfflineUipClient() : defaultUipClient()),
+            caches: {
+                registry: new FsResponseCache(options.cacheDir),
+                is: new FsResponseCache(options.isCacheDir),
+                connectors: new FsResponseCache(options.connectorsCacheDir),
+            },
+            reporter,
+            concurrency: options.concurrency,
+        });
+        // The caches are a re-run aid, not a product: a build that got this far
+        // has no use for them unless asked to keep them. A build that failed above
+        // keeps them regardless, as the Python did, so the retry is cheap.
+        if (!options.keepTemp) {
+            reporter.info("Cleaning up caches...");
+            for (const dir of [options.cacheDir, options.isCacheDir, options.connectorsCacheDir]) {
+                rmSync(dir, { recursive: true, force: true });
+            }
+        }
+        reporter.info("Done!");
+        return 0;
+    }
+    catch (error) {
+        console.error(messageOf(error));
+        return exitCodeOf(error);
+    }
+}

package/dist/registry/library-build/context.d.ts

@@ -0,0 +1,107 @@
+import type { Reporter } from "../reporter.js";
+import type { UipClient } from "../uip/client.js";
+import { type ResponseCache } from "../uip/response-cache.js";
+export interface BuildCaches {
+    /** `--cache-dir`: raw `flow registry get` stdout plus `_search_results.json`. */
+    registry: ResponseCache;
+    /** `--is-cache-dir`: `is resources describe/list` and `is triggers` payloads. */
+    is: ResponseCache;
+    /** `--connectors-cache-dir`: `is connectors metadata` payloads. */
+    connectors: ResponseCache;
+}
+export interface BuildPorts {
+    client: UipClient;
+    caches: BuildCaches;
+    reporter: Reporter;
+    /** Parallel remote calls, as `--concurrency`. */
+    concurrency: number;
+    /** Kill a `uip` call after this long. Unset means no limit, as the Python had none. */
+    timeoutMs?: number;
+}
+/** One describe that failed while parent fields were set: `(connector, object, operation, message)`. */
+export type FailedFieldDescribe = readonly [
+    connectorKey: string,
+    objectName: string,
+    operation: string,
+    message: string
+];
+/**
+ * What the Python kept in module globals, plus the ports.
+ *
+ * `connectionId` routes every registry get / describe / list through
+ * `--connection-id`; `parentFields` are forwarded as `-f name=value` on
+ * describes and discriminate their cache key; `failedFieldDescribes` collects
+ * the CLI's own rejection message for each describe that failed under `-f`,
+ * because the pipeline otherwise swallows it (see `isDescribeOperation`).
+ */
+export interface BuildContext extends BuildPorts {
+    connectionId?: string;
+    /** Insertion order is the `-f` order on the command line. */
+    parentFields: Map<string, string>;
+    failedFieldDescribes: FailedFieldDescribe[];
+}
+export interface BuildScope {
+    connectionId?: string;
+    parentFields?: ReadonlyMap<string, string> | Readonly<Record<string, string>>;
+}
+export declare function createBuildContext(ports: BuildPorts, scope?: BuildScope): BuildContext;
+/** `_schema_cache_scope()`: static and per-connection responses never share a cache. */
+export declare function schemaCacheScope(ctx: BuildContext): string;
+/**
+ * `_field_scope()`: `f-` + the first 12 hex digits of the sha256 over
+ * `name=value` pairs sorted by name and joined with NUL; empty when no parent
+ * field is set. The describe answer is a function of these values, so a cache
+ * keyed only on (connection, object, operation) would serve the first variant
+ * for every later one.
+ */
+export declare function fieldScope(parentFields: ReadonlyMap<string, string>): string;
+/** Cache file for one `flow registry get`: the node type with `.` → `_`. */
+export declare function registryCacheName(nodeType: string): string;
+export declare const SEARCH_RESULTS_NAME = "_search_results.json";
+/** `json.dump(payload, f)`: cache bytes shaped as Python wrote them. */
+export declare function writeCache(cache: ResponseCache, name: string, payload: unknown): void;
+/**
+ * `registry_get`: cached `uip maestro flow registry get <nodeType>`.
+ *
+ * Returns the cache name the raw stdout lives under, or `undefined` when the
+ * call failed. `quiet` suppresses the failure WARN — for a caller probing which
+ * of several node-type namespaces an action lives in, where a miss is an
+ * expected answer rather than a problem to report.
+ */
+export declare function registryGet(ctx: BuildContext, nodeType: string, quiet?: boolean): Promise<string | undefined>;
+/**
+ * `is_describe_operation`: cached `uip is resources describe <connector>
+ * <object> --operation <op>` (plus `--connection-id` and `-f` when set).
+ *
+ * Returns the payload's `Data` on success, or `undefined` on any failure. A
+ * failure is cached too, with a sentinel that keeps the CLI's `Message`: an
+ * incomplete parent set is rejected with a helpful message the pipeline would
+ * otherwise swallow, so it is recorded on the context while parent fields are
+ * set — from a fresh call and from a cached failure alike.
+ */
+export declare function isDescribeOperation(ctx: BuildContext, connectorKey: string, objectName: string, operation: string): Promise<unknown>;
+/**
+ * `is_describe_object`: cached `uip is resources describe <connector> <object>`
+ * with no `--operation`. Its `Data` carries `AvailableOperations`.
+ */
+export declare function isDescribeObject(ctx: BuildContext, connectorKey: string, objectName: string): Promise<unknown>;
+/**
+ * `is_resources_list`: cached `uip is resources list <connector>` — the object
+ * catalog, each row `Name`/`DisplayName`/`Path`/`Type`/`SubType`. The list on
+ * success (possibly empty), `undefined` on failure.
+ *
+ * `refresh` bypasses BOTH caches — this one and the CLI's own, which never
+ * invalidates itself: measured on uipath-salesforce-sfdc, 18 objects stale and
+ * 864 with `--refresh`.
+ */
+export declare function isResourcesList(ctx: BuildContext, connectorKey: string, options?: {
+    operation?: string | null;
+    refresh?: boolean;
+}): Promise<unknown[] | undefined>;
+/**
+ * `is_connector_get`: cached `uip is connectors metadata <key>`, answering the
+ * first element of `Data` or `undefined`. The legacy `connectors get` cache
+ * files are deliberately not reused: that output omitted the discovery
+ * capabilities and would silently mark every connector static.
+ */
+export declare function isConnectorGet(ctx: BuildContext, connectorKey: string): Promise<unknown>;

package/dist/registry/library-build/context.js

@@ -0,0 +1,267 @@
+/**
+ * The build's connection to the tenant: one `uip` client, three response caches,
+ * and the scope every call is made under.
+ *
+ * The Python generator kept `_CONNECTION_ID`, `_PARENT_FIELDS` and
+ * `_FAILED_FIELD_DESCRIBES` as module globals that `prepare_connector` set before
+ * calling in. Here they ride on a {@link BuildContext} that every remote call
+ * takes as its first argument, so two builds in one process cannot see each
+ * other's connection, and a test can hand in a context that never reaches the
+ * network.
+ *
+ * Cache file names and the `Result: Failure` sentinels are the Python's exactly:
+ * a `--keep-temp` cache the Python wrote drives this code to the same bytes,
+ * which is how the port is proven.
+ */
+import { createHash } from "node:crypto";
+import { pyJsonStringify } from "../codecs/pyjson.js";
+import { sortedByKeys } from "../compat/compare.js";
+import { isConnectorsMetadata, isResourcesDescribeObject, isResourcesDescribeOperation, isResourcesList as isResourcesListArgv, registryGet as registryGetArgv, } from "../uip/commands.js";
+import { CACHED_FAILURE, isCachedFailure, safeCacheName } from "../uip/response-cache.js";
+import { pyStrip } from "../compat/pystr.js";
+import { get, isRecord, pyOr, truthy } from "./py.js";
+export function createBuildContext(ports, scope = {}) {
+    const parentFields = scope.parentFields instanceof Map
+        ? new Map(scope.parentFields)
+        : new Map(Object.entries(scope.parentFields ?? {}));
+    return {
+        ...ports,
+        ...(scope.connectionId ? { connectionId: scope.connectionId } : {}),
+        parentFields,
+        failedFieldDescribes: [],
+    };
+}
+/** `_schema_cache_scope()`: static and per-connection responses never share a cache. */
+export function schemaCacheScope(ctx) {
+    return ctx.connectionId || "_static";
+}
+/**
+ * `_field_scope()`: `f-` + the first 12 hex digits of the sha256 over
+ * `name=value` pairs sorted by name and joined with NUL; empty when no parent
+ * field is set. The describe answer is a function of these values, so a cache
+ * keyed only on (connection, object, operation) would serve the first variant
+ * for every later one.
+ */
+export function fieldScope(parentFields) {
+    if (parentFields.size === 0)
+        return "";
+    const pairs = sortedByKeys([...parentFields.entries()], ([k]) => k, ([, v]) => v);
+    const flat = pairs.map(([k, v]) => `${k}=${v}`).join("\0");
+    return `f-${createHash("sha256").update(flat, "utf8").digest("hex").slice(0, 12)}`;
+}
+/** Cache file for one `flow registry get`: the node type with `.` → `_`. */
+export function registryCacheName(nodeType) {
+    return `${nodeType.replaceAll(".", "_")}.json`;
+}
+export const SEARCH_RESULTS_NAME = "_search_results.json";
+function runUip(ctx, argv) {
+    return ctx.client.run(argv, ctx.timeoutMs === undefined ? undefined : { timeoutMs: ctx.timeoutMs });
+}
+/**
+ * `json.loads(result.stdout)`: the whole of stdout as one document, or
+ * `undefined` when it is not one. Deliberately not the lenient banner-skipping
+ * parser — the Python parsed the full stream and treated anything else as a
+ * failed call, and a call that fails there must fail here.
+ */
+function parseStdout(stdout) {
+    try {
+        return JSON.parse(stdout);
+    }
+    catch {
+        return undefined;
+    }
+}
+/** `json.dump(payload, f)`: cache bytes shaped as Python wrote them. */
+export function writeCache(cache, name, payload) {
+    cache.write(name, payload, pyJsonStringify(payload));
+}
+/**
+ * True when the call never ran, so nothing about it may be written down.
+ *
+ * Each fetcher below remembers a FAILURE as a `Result: Failure` sentinel, and
+ * a failure is only ever the tenant's answer — the Python had no offline mode,
+ * so every failure it cached was one. Under `--offline` the client refuses
+ * instead, and caching that as a failure would make the next ONLINE build over
+ * the same `--keep-temp` caches read the refusal as "this object has no
+ * schema" and carry on, silently.
+ *
+ * This is checked EXPLICITLY, before the parse, rather than resting on the
+ * parse failing: the four writes below are gated on `parseStdout` succeeding,
+ * and they stay safe only because `OfflineUipClient` happens to emit empty
+ * output. That accident is exactly what the offline work set out to remove, and
+ * `events.ts` already refuses to rest on it for the two trigger caches.
+ */
+function refused(result) {
+    return result.refused === true;
+}
+/**
+ * `"__".join(parts)` raises `TypeError` on a non-str part, and the Python
+ * generator relied on that: an entry whose `objectName` is `null` never
+ * reached the CLI (its enrichment failed and was reported). `Array.join`
+ * would coerce `null` to `""` and issue a describe the Python never made.
+ */
+function cacheNameOf(...parts) {
+    parts.forEach((part, i) => {
+        if (typeof part !== "string") {
+            const kind = part === null || part === undefined ? "NoneType" : typeof part === "number" ? "int" : typeof part;
+            throw new TypeError(`sequence item ${i}: expected str instance, ${kind} found`);
+        }
+    });
+    return `${safeCacheName(...parts)}.json`;
+}
+/** `payload.get("Result")` on something that is not a dict raises in Python. */
+function envelope(payload) {
+    if (!isRecord(payload))
+        throw new TypeError(`'${Array.isArray(payload) ? "list" : typeof payload}' object has no attribute 'get'`);
+    return payload;
+}
+/**
+ * `registry_get`: cached `uip maestro flow registry get <nodeType>`.
+ *
+ * Returns the cache name the raw stdout lives under, or `undefined` when the
+ * call failed. `quiet` suppresses the failure WARN — for a caller probing which
+ * of several node-type namespaces an action lives in, where a miss is an
+ * expected answer rather than a problem to report.
+ */
+export async function registryGet(ctx, nodeType, quiet = false) {
+    const name = registryCacheName(nodeType);
+    if (ctx.caches.registry.has(name))
+        return name;
+    const result = await runUip(ctx, registryGetArgv(nodeType, ctx.connectionId));
+    if (result.code !== 0) {
+        if (!quiet)
+            ctx.reporter.warn(`  WARN: registry get failed for ${nodeType}: ${pyStrip(result.stderr)}`);
+        return undefined;
+    }
+    ctx.caches.registry.write(name, undefined, result.stdout);
+    return name;
+}
+function noteFailedFieldDescribe(ctx, connectorKey, objectName, operation, message) {
+    if (ctx.parentFields.size > 0) {
+        ctx.failedFieldDescribes.push([connectorKey, objectName, operation, typeof message === "string" && message ? message : ""]);
+    }
+}
+/**
+ * `is_describe_operation`: cached `uip is resources describe <connector>
+ * <object> --operation <op>` (plus `--connection-id` and `-f` when set).
+ *
+ * Returns the payload's `Data` on success, or `undefined` on any failure. A
+ * failure is cached too, with a sentinel that keeps the CLI's `Message`: an
+ * incomplete parent set is rejected with a helpful message the pipeline would
+ * otherwise swallow, so it is recorded on the context while parent fields are
+ * set — from a fresh call and from a cached failure alike.
+ */
+export async function isDescribeOperation(ctx, connectorKey, objectName, operation) {
+    const parts = [schemaCacheScope(ctx), connectorKey, objectName, operation];
+    const scope = fieldScope(ctx.parentFields);
+    if (scope)
+        parts.push(scope);
+    const name = cacheNameOf(...parts);
+    if (ctx.caches.is.has(name)) {
+        const cached = ctx.caches.is.read(name);
+        if (isCachedFailure(cached))
+            noteFailedFieldDescribe(ctx, connectorKey, objectName, operation, get(cached, "Message"));
+        return isRecord(cached) && cached.Data !== undefined ? cached.Data : undefined;
+    }
+    const result = await runUip(ctx, isResourcesDescribeOperation(connectorKey, objectName, operation, ctx.connectionId, ctx.parentFields));
+    if (refused(result))
+        return undefined;
+    const parsed = parseStdout(result.stdout);
+    if (parsed === undefined)
+        return undefined;
+    const payload = envelope(parsed);
+    if (get(payload, "Result") !== "Success") {
+        noteFailedFieldDescribe(ctx, connectorKey, objectName, operation, get(payload, "Message"));
+        writeCache(ctx.caches.is, name, { Result: "Failure", [CACHED_FAILURE]: true, Message: get(payload, "Message") });
+        return undefined;
+    }
+    writeCache(ctx.caches.is, name, payload);
+    return payload.Data;
+}
+/**
+ * `is_describe_object`: cached `uip is resources describe <connector> <object>`
+ * with no `--operation`. Its `Data` carries `AvailableOperations`.
+ */
+export async function isDescribeObject(ctx, connectorKey, objectName) {
+    const name = cacheNameOf(schemaCacheScope(ctx), connectorKey, objectName, "_operations");
+    if (ctx.caches.is.has(name)) {
+        const cached = ctx.caches.is.read(name);
+        return isRecord(cached) && cached.Data !== undefined ? cached.Data : undefined;
+    }
+    const result = await runUip(ctx, isResourcesDescribeObject(connectorKey, objectName, ctx.connectionId));
+    if (refused(result))
+        return undefined;
+    const parsed = parseStdout(result.stdout);
+    if (parsed === undefined)
+        return undefined;
+    const payload = envelope(parsed);
+    if (get(payload, "Result") !== "Success") {
+        writeCache(ctx.caches.is, name, { Result: "Failure", [CACHED_FAILURE]: true });
+        return undefined;
+    }
+    writeCache(ctx.caches.is, name, payload);
+    return payload.Data;
+}
+/**
+ * `is_resources_list`: cached `uip is resources list <connector>` — the object
+ * catalog, each row `Name`/`DisplayName`/`Path`/`Type`/`SubType`. The list on
+ * success (possibly empty), `undefined` on failure.
+ *
+ * `refresh` bypasses BOTH caches — this one and the CLI's own, which never
+ * invalidates itself: measured on uipath-salesforce-sfdc, 18 objects stale and
+ * 864 with `--refresh`.
+ */
+export async function isResourcesList(ctx, connectorKey, options = {}) {
+    const operation = options.operation ?? undefined;
+    const name = `${safeCacheName(schemaCacheScope(ctx), connectorKey, pyOr(operation, "_all_operations"), "_resources_list")}.json`;
+    if (!options.refresh && ctx.caches.is.has(name)) {
+        const cached = ctx.caches.is.read(name);
+        const data = get(cached, "Data");
+        return Array.isArray(data) ? data : undefined;
+    }
+    const result = await runUip(ctx, isResourcesListArgv(connectorKey, {
+        ...(truthy(operation) ? { operation } : {}),
+        ...(options.refresh ? { refresh: true } : {}),
+        connectionId: ctx.connectionId,
+    }));
+    if (refused(result))
+        return undefined;
+    const parsed = parseStdout(result.stdout);
+    if (parsed === undefined)
+        return undefined;
+    const payload = envelope(parsed);
+    if (get(payload, "Result") !== "Success") {
+        writeCache(ctx.caches.is, name, { Result: "Failure", [CACHED_FAILURE]: true });
+        return undefined;
+    }
+    writeCache(ctx.caches.is, name, payload);
+    return Array.isArray(payload.Data) ? payload.Data : undefined;
+}
+/**
+ * `is_connector_get`: cached `uip is connectors metadata <key>`, answering the
+ * first element of `Data` or `undefined`. The legacy `connectors get` cache
+ * files are deliberately not reused: that output omitted the discovery
+ * capabilities and would silently mark every connector static.
+ */
+export async function isConnectorGet(ctx, connectorKey) {
+    const name = `${safeCacheName(connectorKey, "_connector_metadata")}.json`;
+    const firstRow = (payload) => {
+        const data = pyOr(get(payload, "Data"), []);
+        return Array.isArray(data) && data.length > 0 ? data[0] : undefined;
+    };
+    if (ctx.caches.connectors.has(name))
+        return firstRow(ctx.caches.connectors.read(name));
+    const result = await runUip(ctx, isConnectorsMetadata(connectorKey));
+    if (refused(result))
+        return undefined;
+    const parsed = parseStdout(result.stdout);
+    if (parsed === undefined)
+        return undefined;
+    const payload = envelope(parsed);
+    if (get(payload, "Result") !== "Success") {
+        writeCache(ctx.caches.connectors, name, { Result: "Failure", [CACHED_FAILURE]: true });
+        return undefined;
+    }
+    writeCache(ctx.caches.connectors, name, payload);
+    return firstRow(payload);
+}

package/dist/registry/library-build/enrich.d.ts

@@ -0,0 +1,36 @@
+import type { LibraryEntry } from "../model/library.js";
+import { type BuildContext } from "./context.js";
+/**
+ * Registry `httpMethod` (e.g. `GETBYID`) → a guess at the `is resources`
+ * operation name, for an entry whose canonical `operation.name` is empty.
+ */
+export declare const HTTP_METHOD_TO_OPERATION: ReadonlyMap<string, string>;
+/**
+ * `discover_operation_name`: the `is resources` operation whose HTTP method
+ * matches the entry's, from the object's `AvailableOperations`; `null` when
+ * the object cannot be described or nothing matches.
+ */
+export declare function discoverOperationName(ctx: BuildContext, entry: LibraryEntry): Promise<unknown>;
+/**
+ * The pure half of `enrich_entry`: merge one describe `Data` payload into the
+ * entry, in place. `operation.name` is filled only when the registry left it
+ * empty; `pathTemplate`, `parameters` and the two schemas come from the
+ * payload; `objectDisplayName` and `display.operationLabel` fill gaps only.
+ */
+export declare function applyDescribe(entry: LibraryEntry, data: unknown): LibraryEntry;
+/**
+ * `enrich_entry`: augment a canonical entry with `is resources describe` data.
+ * On any failure the entry is returned as it was, so the pipeline degrades
+ * gracefully.
+ *
+ * The registry's verb and the IS CLI's can DISAGREE for the same operation
+ * (Data Service `QueryEntityRecordsCurated`: registry `List`, CLI `Create`).
+ * When the registry's name does not resolve, the OBJECT is asked which
+ * operations it has and the one whose HTTP method matches is retried.
+ * `operation.name` deliberately keeps the REGISTRY's verb even then — it maps
+ * to a CRUD verb the offline fixtures are synthesised from; the discovered
+ * name is only for reaching the schema.
+ */
+export declare function enrichEntry(ctx: BuildContext, entry: LibraryEntry): Promise<LibraryEntry>;
+/** `enrich_all`: `enrichEntry` over every entry, results in input order. */
+export declare function enrichAll(ctx: BuildContext, entries: readonly LibraryEntry[]): Promise<LibraryEntry[]>;