@uipath/maestro-builder-sdk 6.4.0 → 6.5.0

package/dist/registry/library-reader.d.ts

@@ -0,0 +1,20 @@
+import type { IndexRow, LibraryEntry, LibraryIndex, V1Definition } from "./model/library.js";
+export interface LoadedLibrary {
+    /** The `library-json` directory. */
+    readonly dir: string;
+    readonly index: LibraryIndex;
+    /** `objectName`s the curated ledger declares connector-invariant. */
+    readonly invariant: ReadonlySet<string>;
+    entryPath(row: IndexRow): string;
+    v1defPath(row: IndexRow): string;
+    /** The canonical entry, or `undefined` when the file the index names is missing. */
+    readEntry(row: IndexRow): LibraryEntry | undefined;
+    /** The sidecar, unwrapped from a one-element list, or `undefined` when absent. */
+    readV1Def(row: IndexRow): V1Definition | undefined;
+}
+/** `<path minus .json>.v1def.json`, the sidecar beside an entry. */
+export declare function sidecarPath(entryRelativePath: string): string;
+export declare function readJsonFile(path: string): unknown;
+/** A sidecar may be `[definition]` in some snapshots; the definition is what callers want. */
+export declare function unwrapV1Def(raw: unknown): V1Definition | undefined;
+export declare function loadLibrary(dir: string): LoadedLibrary;

package/dist/registry/library-reader.js

@@ -0,0 +1,50 @@
+/**
+ * Reading an extracted `library-json/` tree.
+ *
+ * Every generator walks the same index and opens the same two files per
+ * operation. This is that walk, once, with the path rules the Python spelled in
+ * three places: the entry is `index.json`'s `path`, the sidecar is the same path
+ * with `.json` swapped for `.v1def.json`, and a sidecar that is a one-element
+ * list is unwrapped.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { loadInvariantCollections } from "./lookup-specs.js";
+/** `<path minus .json>.v1def.json`, the sidecar beside an entry. */
+export function sidecarPath(entryRelativePath) {
+    return `${entryRelativePath.slice(0, -".json".length)}.v1def.json`;
+}
+export function readJsonFile(path) {
+    return JSON.parse(readFileSync(path, "utf8"));
+}
+/** A sidecar may be `[definition]` in some snapshots; the definition is what callers want. */
+export function unwrapV1Def(raw) {
+    if (Array.isArray(raw))
+        return (raw[0] ?? undefined);
+    if (raw && typeof raw === "object")
+        return raw;
+    return undefined;
+}
+export function loadLibrary(dir) {
+    const indexPath = join(dir, "index.json");
+    if (!existsSync(indexPath)) {
+        throw new Error(`library missing index.json: ${indexPath}`);
+    }
+    const index = readJsonFile(indexPath);
+    const invariant = loadInvariantCollections(dir);
+    return {
+        dir,
+        index,
+        invariant,
+        entryPath: (row) => join(dir, row.path),
+        v1defPath: (row) => join(dir, sidecarPath(row.path)),
+        readEntry(row) {
+            const path = join(dir, row.path);
+            return existsSync(path) ? readJsonFile(path) : undefined;
+        },
+        readV1Def(row) {
+            const path = join(dir, sidecarPath(row.path));
+            return existsSync(path) ? unwrapV1Def(readJsonFile(path)) : undefined;
+        },
+    };
+}

package/dist/registry/lookup-specs.d.ts

@@ -0,0 +1,55 @@
+import type { FieldReference, LibraryField } from "./model/library.js";
+export declare const LEDGER_FILENAME = "invariant-collections.json";
+/**
+ * The ledger's `objectName` set, or an empty set. An absent or malformed
+ * ledger reads as empty rather than raising: the permissive path is the
+ * pre-ledger behaviour, so a bad edit loses exactness, never a build.
+ */
+export declare function loadInvariantCollections(libraryDir: string | undefined): Set<string>;
+/** The field's `reference` block when it declares a resolvable value. */
+export declare function referenceOf(field: {
+    reference?: unknown;
+}): FieldReference | undefined;
+/** True when resolving would return the value it was given. */
+export declare function isIdentityLookup(reference: FieldReference): boolean;
+export type LookupClass = "none" | "identity" | "invariant" | "lookup";
+/** Only `'lookup'` earns a helper and a `--resolve`. */
+export declare function classify(field: {
+    reference?: unknown;
+}, invariant: ReadonlySet<string>): LookupClass;
+/** The subset of `fields` that earns a `.by*` helper, in declaration order. */
+export declare function resolvableLookupFields<F extends {
+    reference?: unknown;
+}>(fields: readonly F[], invariant: ReadonlySet<string>): F[];
+export type LookupStrategy = "dependent" | "filter" | "tree" | "scan";
+/**
+ * Which retrieval strategy `prepare` uses. `dependsOn` wins outright because it
+ * is a prerequisite, not an optimisation; then a server-side filter beats a
+ * tree walk beats a full scan.
+ */
+export declare function lookupStrategy(reference: FieldReference): LookupStrategy;
+/** One lookup field's retrieval contract, as the generated descriptor carries it. */
+export interface LookupSpecData {
+    path: string;
+    by: string[];
+    value: string;
+    /** Insertion-ordered: the order of `lookupNames`. */
+    aliases: Map<string, string>;
+    strategy: LookupStrategy;
+    objectName?: string;
+    dependsOn?: string[];
+}
+/**
+ * `{ fieldName → spec }` for the lookup-bearing fields of any field list.
+ *
+ * `catalogReferences` supplies a `reference` for a field whose authoring
+ * vocabulary lacks one: the two declarations disagree about which fields they
+ * carry, and a lookup declared only in the catalog is still a lookup.
+ */
+export declare function specsFromFields(fields: readonly LibraryField[], invariant: ReadonlySet<string>, catalogReferences?: ReadonlyMap<string, FieldReference>): Map<string, LookupSpecData>;
+/** The `reference` blocks the catalog's `inputSchema.fields` declare, by name. */
+export declare function catalogReferences(entry: {
+    inputSchema?: {
+        fields?: LibraryField[];
+    } | null;
+}): Map<string, FieldReference>;

package/dist/registry/lookup-specs.js

@@ -0,0 +1,140 @@
+/**
+ * Which connector input fields earn a `.by*` helper, and what the helper needs.
+ *
+ * A `reference` with a `lookupValue` says a field's value is an opaque id to be
+ * resolved against a live connection. Two classes are excluded: IDENTITY
+ * lookups, where `lookupValue` is the only `lookupNames` entry so resolving
+ * returns what it was given, and INVARIANT collections, whose ids are a property
+ * of the connector's API rather than of a connection (a country list), read from
+ * the curated `invariant-collections.json` ledger. Everything else is a lookup;
+ * the fallback direction is the safe one.
+ *
+ * Ported from `integrations/scripts/_lookups.py` and the `lookup_specs` half of
+ * `generate_connectors_ts.py`. `core/lookups.ts` keeps `check` and `compile`
+ * agreeing with this by importing it.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { pyTruthy } from "./generators/type-tree.js";
+import { byAliases } from "./naming.js";
+export const LEDGER_FILENAME = "invariant-collections.json";
+/**
+ * The ledger's `objectName` set, or an empty set. An absent or malformed
+ * ledger reads as empty rather than raising: the permissive path is the
+ * pre-ledger behaviour, so a bad edit loses exactness, never a build.
+ */
+export function loadInvariantCollections(libraryDir) {
+    if (!libraryDir)
+        return new Set();
+    const path = join(libraryDir, LEDGER_FILENAME);
+    if (!existsSync(path))
+        return new Set();
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch {
+        return new Set();
+    }
+    const rows = parsed?.collections;
+    if (!Array.isArray(rows))
+        return new Set();
+    const out = new Set();
+    for (const row of rows) {
+        if (row && typeof row === "object" && typeof row.objectName === "string") {
+            out.add(row.objectName);
+        }
+    }
+    return out;
+}
+/** The field's `reference` block when it declares a resolvable value. */
+export function referenceOf(field) {
+    const reference = field.reference;
+    if (!reference || typeof reference !== "object" || Array.isArray(reference))
+        return undefined;
+    // `not reference.get("lookupValue")`: an empty list or dict is "no value"
+    // in Python and would be "a value" to a bare JavaScript test.
+    if (!pyTruthy(reference.lookupValue))
+        return undefined;
+    return reference;
+}
+/** True when resolving would return the value it was given. */
+export function isIdentityLookup(reference) {
+    const names = reference.lookupNames ?? [];
+    return names.length === 1 && reference.lookupValue !== undefined && names.includes(reference.lookupValue);
+}
+/** Only `'lookup'` earns a helper and a `--resolve`. */
+export function classify(field, invariant) {
+    const reference = referenceOf(field);
+    if (!reference)
+        return "none";
+    if (isIdentityLookup(reference))
+        return "identity";
+    if (reference.objectName !== undefined && invariant.has(reference.objectName))
+        return "invariant";
+    return "lookup";
+}
+/** The subset of `fields` that earns a `.by*` helper, in declaration order. */
+export function resolvableLookupFields(fields, invariant) {
+    return fields.filter((f) => classify(f, invariant) === "lookup");
+}
+/**
+ * Which retrieval strategy `prepare` uses. `dependsOn` wins outright because it
+ * is a prerequisite, not an optimisation; then a server-side filter beats a
+ * tree walk beats a full scan.
+ */
+export function lookupStrategy(reference) {
+    if (reference.dependsOn && reference.dependsOn.length > 0)
+        return "dependent";
+    if (reference.filterPattern)
+        return "filter";
+    if (reference.childPath)
+        return "tree";
+    return "scan";
+}
+/**
+ * `{ fieldName → spec }` for the lookup-bearing fields of any field list.
+ *
+ * `catalogReferences` supplies a `reference` for a field whose authoring
+ * vocabulary lacks one: the two declarations disagree about which fields they
+ * carry, and a lookup declared only in the catalog is still a lookup.
+ */
+export function specsFromFields(fields, invariant, catalogReferences) {
+    const specs = new Map();
+    for (const field of fields) {
+        const name = field.name;
+        if (!name)
+            continue;
+        let merged = field;
+        if (!(field.reference && typeof field.reference === "object") && catalogReferences?.has(name)) {
+            merged = { ...field, reference: catalogReferences.get(name) };
+        }
+        if (classify(merged, invariant) !== "lookup")
+            continue;
+        const reference = referenceOf(merged);
+        const names = (reference.lookupNames ?? []).map((n) => String(n));
+        const spec = {
+            path: reference.path || "",
+            by: names,
+            value: String(reference.lookupValue),
+            aliases: byAliases(names),
+            strategy: lookupStrategy(reference),
+        };
+        if (reference.objectName)
+            spec.objectName = String(reference.objectName);
+        if (reference.dependsOn && reference.dependsOn.length > 0)
+            spec.dependsOn = reference.dependsOn.map((d) => String(d));
+        specs.set(name, spec);
+    }
+    return specs;
+}
+/** The `reference` blocks the catalog's `inputSchema.fields` declare, by name. */
+export function catalogReferences(entry) {
+    const out = new Map();
+    for (const field of entry.inputSchema?.fields ?? []) {
+        if (field.reference && typeof field.reference === "object" && field.name !== undefined) {
+            out.set(field.name, field.reference);
+        }
+    }
+    return out;
+}

package/dist/registry/materialize-cli.js

@@ -1,46 +1,60 @@
+import { exitCodeOf, messageOf } from "./errors.js";
 import { materializeRegistry } from "./materializer.js";
 /**
- * Generate `library-md` and `connectors/` from an extracted `library-json`.
+ * Generate `library-md` and/or `connectors/` from an extracted `library-json`.
  *
  * Exposed as `run(argv)` rather than as a top-level script so the umbrella CLI
  * can mount it the same way it mounts every other verb: `cli/common.ts` does
  * `(await import(...)).run(argv)` and maps the returned code onto
- * `process.exitCode`. A module that read `process.argv` and called
- * `process.exit` at import time could not be mounted at all — which is why
- * this verb used to be reachable only through its own bin, and why the product
- * CLI had to resolve that bin out of the package's `bin` map instead of
- * delegating to `dist/cli/index.js` like it does for compile and check.
+ * `process.exitCode`. The `flow-registry-materialize` bin is a two-line shim
+ * over this function.
  *
- * The bin still works: `materialize-bin.ts` is a two-line shim over
- * this function, so both entry points share one implementation.
+ * Either output may be omitted, but not both: an image build that already
+ * pulled the Markdown asks only for the descriptors, and a project that needs
+ * no descriptors asks only for the pages. `--python` and `--generator` are
+ * accepted for one release and ignored — nothing is spawned any more.
  */
-const USAGE = "Usage: flow-sdk registry materialize --library-json <path> --library-md <path> --connectors <path> [--import <specifier>] [--triggers <path>] [--python <executable>] [--generator <path>]";
+const USAGE = "Usage: flow-sdk registry materialize --library-json <path> [--library-md <path>] [--connectors <path>]\n" +
+    "                                     [--import <specifier>] [--triggers <path>] [--connector-subset a,b]\n" +
+    "                                     [--include-generic-expanded] [--check-symbols] [--check-orphans]";
+const IGNORED = ["--python", "--generator"];
 function value(args, name) {
     const index = args.indexOf(name);
     return index >= 0 ? args[index + 1] : undefined;
 }
 export async function run(argv) {
+    if (argv.includes("--help") || argv.includes("-h")) {
+        console.log(USAGE);
+        return 0;
+    }
     const libraryJsonPath = value(argv, "--library-json");
     const libraryMarkdownPath = value(argv, "--library-md");
     const connectorsPath = value(argv, "--connectors");
-    if (!libraryJsonPath || !libraryMarkdownPath || !connectorsPath) {
+    if (!libraryJsonPath || (!libraryMarkdownPath && !connectorsPath)) {
         console.error(USAGE);
         return 2;
     }
+    for (const flag of IGNORED) {
+        if (argv.includes(flag)) {
+            console.error(`registry materialize: ${flag} is ignored — the generators run in-process now and the flag will be removed.`);
+        }
+    }
     try {
         await materializeRegistry({
             libraryJsonPath,
             libraryMarkdownPath,
             connectorsPath,
             connectorImport: value(argv, "--import"),
-            pythonExecutable: value(argv, "--python"),
             triggersPath: value(argv, "--triggers"),
-            generatorPath: value(argv, "--generator"),
+            connectorSubset: value(argv, "--connector-subset")?.split(",").filter((c) => c.length > 0),
+            includeGenericExpanded: argv.includes("--include-generic-expanded"),
+            checkSymbols: argv.includes("--check-symbols"),
+            checkOrphans: argv.includes("--check-orphans"),
         });
         return 0;
     }
     catch (error) {
-        console.error(error instanceof Error ? error.message : String(error));
-        return 1;
+        console.error(messageOf(error));
+        return exitCodeOf(error);
     }
 }

package/dist/registry/materializer.d.ts

@@ -1,3 +1,5 @@
+import { type MaterializeResult } from "./generators/materialize.js";
+import { type Reporter } from "./reporter.js";
 export interface MaterializeRegistryOptions {
     libraryJsonPath: string;
     /** Where the Markdown goes. Omit to skip it — see `connectorsPath`. */
@@ -15,9 +17,29 @@ export interface MaterializeRegistryOptions {
      */
     connectorSubset?: string[];
     connectorImport?: string;
-    pythonExecutable?: string;
     triggersPath?: string;
-    /** Override used by tests and source checkouts. */
+    /** Also emit descriptors for GenericExpanded entries. */
+    includeGenericExpanded?: boolean;
+    /** Fail when a Markdown page cites a symbol the descriptors do not export. */
+    checkSymbols?: boolean;
+    /**
+     * Fail when an entry file has no `index.json` row, which makes it
+     * unresolvable. The image build asks for this; `registry pull` does not, and
+     * must not — see the call site for the live-library case that proves why.
+     */
+    checkOrphans?: boolean;
+    reporter?: Reporter;
+    /** @deprecated No interpreter is involved any more; accepted and ignored. */
+    pythonExecutable?: string;
+    /** @deprecated The generators are part of the package; accepted and ignored. */
     generatorPath?: string;
 }
-export declare function materializeRegistry(options: MaterializeRegistryOptions): Promise<void>;
+/**
+ * Apply the SDK's curated corrections to an extracted library, then generate
+ * its Markdown and TypeScript views in-process.
+ *
+ * The product CLI downloads the raw registry archive and delegates directly to
+ * this API, so the corrections are applied here for every caller — including
+ * the connector start-trigger definitions absent from the raw dump.
+ */
+export declare function materializeRegistry(options: MaterializeRegistryOptions): Promise<MaterializeResult>;

package/dist/registry/materializer.js

@@ -1,34 +1,50 @@
-import { packagedGenerator, runGenerator } from "./python.js";
 import { applyCuratedOverlay } from "./curated-overlay.js";
+import { assertNoOrphans } from "./orphans.js";
 import { PACKAGE_NAME } from "../package-name.js";
+import { materialize } from "./generators/materialize.js";
+import { consoleReporter } from "./reporter.js";
+/**
+ * Apply the SDK's curated corrections to an extracted library, then generate
+ * its Markdown and TypeScript views in-process.
+ *
+ * The product CLI downloads the raw registry archive and delegates directly to
+ * this API, so the corrections are applied here for every caller — including
+ * the connector start-trigger definitions absent from the raw dump.
+ */
 export async function materializeRegistry(options) {
-    // The product CLI downloads the raw registry archive and delegates directly
-    // to this API. Apply the SDK's curated corrections here so every caller gets
-    // the same resolvable library as the standalone flow-sdk pull command,
-    // including connector start-trigger definitions absent from the raw dump.
-    await applyCuratedOverlay(options.libraryJsonPath);
-    const args = [
-        "--library-json",
-        options.libraryJsonPath,
-        "--import",
-        options.connectorImport ?? PACKAGE_NAME,
-    ];
-    if (options.libraryMarkdownPath) {
-        args.push("--library-md", options.libraryMarkdownPath);
-    }
-    if (options.connectorsPath) {
-        args.push("--connectors", options.connectorsPath);
-    }
-    if (options.connectorSubset && options.connectorSubset.length > 0) {
-        args.push("--connector-subset", options.connectorSubset.join(","));
-    }
-    if (options.triggersPath) {
-        args.push("--triggers", options.triggersPath);
-    }
-    await runGenerator({
-        script: options.generatorPath ?? packagedGenerator("materialize_registry.py"),
-        args,
-        pythonExecutable: options.pythonExecutable,
-        what: "Registry materialization",
+    // The caller's reporter, forwarded: the overlay warns when it declines a
+    // correction the library resolves elsewhere, and a caller that asked for
+    // silence should not get that on stderr anyway.
+    await applyCuratedOverlay(options.libraryJsonPath, undefined, options.reporter ?? consoleReporter);
+    // OPT-IN, because this is the public API and `registry pull` comes through it.
+    //
+    // The check belongs to the image build, which is the only place the Python
+    // ever ran it (`unpack-library.sh`, never materialize_registry.py). Running it
+    // for every caller looked like a free upgrade and was not: the overlay used to
+    // copy four `event-*@1.0.0.json` files whose (nodeType, version) identity a
+    // LIVE library already carries at a different path, so no index row was added
+    // and the copy was an orphan by this definition. Against the committed zip
+    // those rows are missing and do get added, which is why the tests and the
+    // image stayed green while `registry pull` against a real registry threw.
+    //
+    // The overlay now declines that copy and warns, so this is no longer a trap —
+    // but it stays opt-in, because whether an unreachable entry file should fail
+    // the run is the image build's question rather than every caller's.
+    //
+    // It runs after the overlay, as the shell did: the overlay's job is to ADD the
+    // rows the raw dump lacks, so checking first would report orphans it is about
+    // to adopt.
+    if (options.checkOrphans)
+        assertNoOrphans(options.libraryJsonPath);
+    return materialize({
+        libraryJsonPath: options.libraryJsonPath,
+        libraryMarkdownPath: options.libraryMarkdownPath,
+        connectorsPath: options.connectorsPath,
+        connectorSubset: options.connectorSubset,
+        connectorImport: options.connectorImport ?? PACKAGE_NAME,
+        triggersPath: options.triggersPath,
+        includeGenericExpanded: options.includeGenericExpanded,
+        checkSymbols: options.checkSymbols,
+        reporter: options.reporter ?? consoleReporter,
     });
 }