@uipath/maestro-builder-sdk 6.4.0 → 6.5.1

package/dist/registry/generators/markdown/sections/lookups.js

@@ -0,0 +1,150 @@
+/**
+ * `## Resolving lookups`: helpers first, enumeration commands only where owed.
+ *
+ * A field holding an id is resolved late through `lookup(...)` and one
+ * `prepare`; the `resources run list` command survives only for IDENTITY
+ * lookups, which have no helper and no offline vocabulary. Ported from
+ * `lookup_lines`, `enumeration_command` and `reference_strategy`.
+ */
+import { pyJsonString } from "../../../codecs/pyjson.js";
+import { sortedStrings } from "../../../compat/compare.js";
+import { pyStr, splitOnce } from "../../../compat/pystr.js";
+import { classify, referenceOf } from "../../../lookup-specs.js";
+import { byAliases } from "../../../naming.js";
+import { authoringField, referenceCollection, referenceQuery } from "../common.js";
+import { firstValue, IDENT, pyOr, pyTruthy, strList } from "../pyvalue.js";
+/** The `resources run list` call that shows what an identity-lookup field accepts. */
+export function enumerationCommand(connectorKey, f) {
+    const collection = referenceCollection(f);
+    const query = referenceQuery(f);
+    let command = `uip is resources run list ${connectorKey} ${collection} --connection-id <id>`;
+    if (query)
+        command += ` --query "${query}"`;
+    return command;
+}
+/** Prose for how `prepare` will retrieve this collection. */
+export function referenceStrategy(reference) {
+    if (pyTruthy(reference.dependsOn)) {
+        const depends = strList(reference.dependsOn)
+            .map((d) => `\`${d}\``)
+            .join(", ");
+        return `dependent — resolve ${depends} first`;
+    }
+    if (pyTruthy(reference.filterPattern))
+        return "one request (server-side filter)";
+    if (pyTruthy(reference.childPath))
+        return "hierarchical walk";
+    return "paged scan (no server-side filter declared)";
+}
+/**
+ * The section body, or `[]` when no field is a lookup. `symbol` is the
+ * generated descriptor's exported name, or `undefined` when the operation has
+ * no descriptor (a Generic CRUD expansion), in which case the string form of
+ * `lookup()` carries the real key and action.
+ */
+export function lookupLines(connectorKey, action, fields, symbol, invariant) {
+    const resolvable = [];
+    const identity = [];
+    for (const f of fields) {
+        const kind = classify(f, invariant);
+        if (kind === "lookup")
+            resolvable.push([f, referenceOf(f)]);
+        else if (kind === "identity")
+            identity.push(f);
+    }
+    if (!resolvable.length && !identity.length)
+        return [];
+    const out = [];
+    if (resolvable.length) {
+        const [firstField, firstReference] = resolvable[0];
+        // Keyed by the WIRE name (`users[*]`), the string `--resolve` and
+        // buildConnectorInputs match on; the table's `field` column keeps the
+        // authoring name the reader writes as an object key.
+        const firstName = pyStr(pyOr(firstField.name, authoringField(firstField)[0]));
+        const firstNames = strList(firstReference.lookupNames);
+        const firstAliases = byAliases(firstNames);
+        const holder = symbol || `'${connectorKey}', '${action}'`;
+        const call = `lookup(${holder}, '${firstName}')`;
+        const sample = firstAliases.size
+            ? `.${firstValue(firstAliases)}('…')`
+            : firstNames.length
+                ? `.by('${firstNames[0]}', '…')`
+                : ".by('id', '…')";
+        // The MECHANISM — resolve, never hand-write the wire value — is true of
+        // every lookup. The old JUSTIFICATION was not: it asserted the value is an
+        // opaque, connection-specific id, which is false for 320 of the library's
+        // 2,563 rows and, on `uipath-salesforce-slack` `send-message-to-user`, for
+        // a row printed three lines below the claim (`send_as` sends the word
+        // `bot`) — #706. Nothing in the metadata says which case a field is in, so
+        // the id claim is stated as the CONDITION it always was, and the `sends`
+        // column — already printed below — answers which case this page is.
+        out.push("These fields send a value the connector defines, not the label you " +
+            "know it by — the `sends` column says which. Do not write that value " +
+            "by hand: where it is an opaque id it is also connection-specific, so " +
+            "a pasted one resolves to nobody (or to somebody else) against a " +
+            "different connection. Resolve it late:");
+        out.push("");
+        out.push("```ts");
+        // A dotted wire name is a legal object key only when quoted.
+        const key = IDENT.test(firstName) ? firstName : pyJsonString(firstName);
+        out.push(`${key}: ${call}${sample}`);
+        out.push("```");
+        out.push("");
+        out.push("| field | helpers | matches on | sends |");
+        out.push("| --- | --- | --- | --- |");
+        for (const [f, reference] of resolvable) {
+            const [name] = authoringField(f);
+            const names = strList(reference.lookupNames);
+            const aliases = byAliases(names);
+            const helperCell = aliases.size
+                ? [...aliases.values()].map((a) => `\`.${a}(v)\``).join(" ")
+                : "_(generic form only)_";
+            // `objectName` can carry a query string; show the collection.
+            const target = pyOr(splitOnce(pyStr(pyOr(reference.objectName, "")), "?")[0], referenceCollection(f));
+            out.push(`| \`${name}\` | ${helperCell} | ` +
+                names.map((n) => `\`${n}\``).join(" ") +
+                ` | \`${target}.${pyStr(reference.lookupValue)}\` |`);
+        }
+        out.push("");
+        out.push("Any field also takes the generic form: `.by('<name>', value)`.");
+        out.push("");
+        // ORDERING, not just the command: author the token, let check name the command, run it once.
+        out.push("Author the `lookup()` call and finish the flow — `check` reports " +
+            "each token still unresolved with exactly this command; run it " +
+            "once before compiling (`compile` refuses an unresolved lookup):");
+        out.push("");
+        // ONE command carrying every --resolve, and no `--connection-id`.
+        out.push("```bash");
+        out.push(`npx flow-sdk registry prepare ${connectorKey} ${action} \\`);
+        const resolves = resolvable.map(([f, reference]) => {
+            const [name] = authoringField(f);
+            const names = pyOr(strList(reference.lookupNames), ["id"]);
+            return `  --resolve ${name}:${names[0]}=<value>`;
+        });
+        for (const line of resolves.slice(0, -1))
+            out.push(`${line} \\`);
+        out.push(resolves[resolves.length - 1]);
+        out.push("```");
+        out.push("");
+        const strategies = new Set(resolvable.map(([, r]) => referenceStrategy(r)));
+        out.push(`Strategy: ${sortedStrings(strategies).join("; ")}.`);
+        out.push("");
+    }
+    if (identity.length) {
+        out.push("**These fields take a plain string.** Their `reference` enumerates " +
+            "the legal values rather than mapping a name to an id — what you " +
+            "send back is what you searched for — so there is no helper and " +
+            "nothing to resolve. The values exist only behind the connection, " +
+            "so this is how to see what is accepted:");
+        out.push("");
+        out.push("```bash");
+        for (const f of identity) {
+            const [name] = authoringField(f);
+            out.push(`# ${name}`);
+            out.push(enumerationCommand(connectorKey, f));
+        }
+        out.push("```");
+        out.push("");
+    }
+    return out;
+}

package/dist/registry/generators/markdown/sections/outputs.d.ts

@@ -0,0 +1,3 @@
+/** `## Outputs`: the entry's `outputSchema.fields`, one bullet each. The sidecar carries no output fields. */
+import { type Dict } from "../pyvalue.js";
+export declare function outputsLines(j: Dict): string[];

package/dist/registry/generators/markdown/sections/outputs.js

@@ -0,0 +1,9 @@
+/** `## Outputs`: the entry's `outputSchema.fields`, one bullet each. The sidecar carries no output fields. */
+import { dictOf, listOf, pyOr } from "../pyvalue.js";
+import { fieldLine } from "./inputs.js";
+export function outputsLines(j) {
+    const outFields = listOf(pyOr(dictOf(j.outputSchema).fields, []));
+    if (!outFields.length)
+        return [];
+    return ["## Outputs", "", ...outFields.map((f) => fieldLine(dictOf(f))), ""];
+}

package/dist/registry/generators/markdown/sections/resolving-fields.d.ts

@@ -0,0 +1,2 @@
+import { type Dict } from "../pyvalue.js";
+export declare function schemaActionLines(connectorKey: string, objectName: string, verb: string, action: Dict, fields: readonly Dict[]): string[];

package/dist/registry/generators/markdown/sections/resolving-fields.js

@@ -0,0 +1,139 @@
+/**
+ * `## Resolving the field set`: how to get an operation's real field set when
+ * parent VALUES select it (Jira `create-issue` describes to 2 fields with
+ * nothing supplied and 32 once a project and an issue type are given).
+ * Ported from `schema_action_lines`.
+ */
+import { pyStr, splitOnce } from "../../../compat/pystr.js";
+import { referenceCollection, referenceQuery } from "../common.js";
+import { dictOf, listOf, pyOr, pyTruthy } from "../pyvalue.js";
+export function schemaActionLines(connectorKey, objectName, verb, action, fields) {
+    const parents = listOf(pyOr(action.parents, []));
+    if (!parents.length)
+        return [];
+    const byName = new Map();
+    for (const f of fields)
+        byName.set(f.name, f);
+    const trigger = action.trigger;
+    const replaces = action.replaces;
+    const obj = pyOr(objectName, "<object>");
+    const out = ["## Resolving the field set", ""];
+    out.push("The inputs listed below are only the ones that SELECT the field set. " +
+        "The real set depends on the values of " +
+        parents.map((p) => `\`${pyStr(p)}\``).join(", ") +
+        " — a different value gives a different set, so there is no single " +
+        "field list for this operation.");
+    out.push("");
+    if (pyTruthy(trigger)) {
+        out.push(`It is not automatic: \`${pyStr(trigger)}\` is a trigger rather than data, ` +
+            "so the schema has to be requested once the values are in place.");
+        out.push("");
+    }
+    out.push("Resolve the parents in this order, then describe again:");
+    out.push("");
+    parents.forEach((parentRaw, i) => {
+        const position = i + 1;
+        const parent = pyStr(parentRaw);
+        const field = dictOf(byName.get(parentRaw));
+        const reference = dictOf(pyOr(field.reference, {}));
+        const collection = referenceCollection(field);
+        if (!collection) {
+            out.push(`${position}. \`${parent}\` — supply the value; it is not chosen from a list.`);
+            out.push("");
+            return;
+        }
+        const query = referenceQuery(field);
+        const pattern = pyStr(pyOr(reference.filterPattern, ""));
+        const names = listOf(pyOr(reference.lookupNames, []));
+        const send = pyStr(pyOr(reference.lookupValue, "id"));
+        out.push(`${position}. \`${parent}\` — from \`${collection}\`` +
+            (names.length ? `, match on ${names.map((n) => `\`${pyStr(n)}\``).join(" or ")}` : "") +
+            `, send \`${send}\`.`);
+        // A placeholder means an earlier parent's value goes here.
+        if (collection.includes("{")) {
+            out.push("   Substitute the value resolved above for the `{…}` part of the collection.");
+        }
+        out.push("");
+        out.push("   ```bash");
+        out.push(`   uip is resources run list ${connectorKey} ${collection} --connection-id <id> \\`);
+        if (pattern) {
+            // The connector declares its own search; substituting the term narrows server-side.
+            out.push(`     --query "${pattern.replaceAll("{filter}", "<search-term>")}" \\`);
+        }
+        else if (query) {
+            out.push(`     --query "${query}" \\`);
+        }
+        const projection = pyOr(names.slice(0, 2), ["name"])
+            .map((n) => `${splitOnce(pyStr(n), "[")[0]}:${pyStr(n)}`)
+            .join(",");
+        out.push(`     --output-filter "{items: items[*].{${projection},` +
+            `send:${send}}, page: Pagination.{h:HasMore,t:NextPageToken}}" \\`);
+        out.push("     --output json");
+        out.push("   ```");
+        out.push("");
+        if (pattern) {
+            out.push("   The connector declares its own search, so narrow with " +
+                "the term the user gave rather than reading pages: one " +
+                "call usually returns a handful, and `page` comes back " +
+                "either absent or with `h` as `\"false\"`. Page only if " +
+                "the term matches nothing.");
+        }
+        else {
+            out.push("   Page it: `page.h` is the `elements-has-more` response " +
+                "header verbatim, so it is the string `\"true\"` rather " +
+                "than a boolean, and `page` is absent altogether when the " +
+                "connector sends no pagination headers. While it reads " +
+                "`\"true\"` and the value has not appeared, pass `page.t` " +
+                "back as `--query \"nextPage=<token>\"` and read the next " +
+                "page. Stop on the match. The projection keeps each page " +
+                "small but does not reduce the call count.");
+            out.push("");
+            out.push("   Before paging, check this field's `Reference` in the " +
+                "`describe` output for a `FilterPattern`: it is " +
+                "connection-scoped, so it is not in this catalog, but when " +
+                "present it is the connector's own search and removes the " +
+                "paging — Jira's project lookup declares `query={filter}`, " +
+                "which turns 420-plus rows across pages into two in one call. " +
+                "Substitute the wanted term into whatever pattern this field " +
+                "declares; the shape is:");
+            out.push("");
+            out.push("   ```bash");
+            out.push(`   uip is resources run list ${connectorKey} ${collection} --connection-id <id> \\`);
+            out.push('     --query "<filter-pattern with the term substituted>" --output json');
+            out.push("   ```");
+        }
+        out.push("");
+    });
+    const supplied = parents.map((p) => `-f ${pyStr(p)}=<value>`).join(" ");
+    out.push(`${parents.length + 1}. Describe again with the resolved values:`);
+    out.push("");
+    out.push("   ```bash");
+    out.push(`   uip is resources describe ${connectorKey} ${pyStr(obj)} --operation ${verb} \\`);
+    out.push(`     --connection-id <id> ${supplied} --output json`);
+    out.push("   ```");
+    out.push("");
+    if (replaces === "output") {
+        out.push("   This replaces the **response** fields — it tells you the shape " +
+            "of what comes back, not what to send.");
+    }
+    else if (replaces === "both") {
+        out.push("   This replaces the **request** fields AND the **response** " +
+            "fields — both halves of this operation change with the values " +
+            "above, so read the response shape from the same call.");
+    }
+    else {
+        out.push("   This replaces the **request** fields.");
+    }
+    out.push("");
+    // Only meaningful where the action rewrites the INPUT (matches the CLI's `isParentOnlyResult` gate).
+    if (replaces === "input" || replaces === "both") {
+        out.push("If the result contains only the parents again, one of the values " +
+            "does not exist on this connection. The call reports `Success` " +
+            "either way, so the count alone cannot tell that apart from having " +
+            "supplied nothing — check whether anything beyond the parents came " +
+            "back. Too FEW parents fails loudly instead, with " +
+            "`No api-type ObjectAction matched`.");
+        out.push("");
+    }
+    return out;
+}

package/dist/registry/generators/markdown/sections/schema-dynamic.d.ts

@@ -0,0 +1,2 @@
+import { type Dict } from "../pyvalue.js";
+export declare function schemaDynamicLines(j: Dict, nodeType: string): string[];

package/dist/registry/generators/markdown/sections/schema-dynamic.js

@@ -0,0 +1,86 @@
+/**
+ * The blockquote on an operation whose real inputs arrive from a live
+ * connection (`runtime.requiresConnectionForSchema`). It points the agent at
+ * `registry prepare` without claiming every marked operation is incomplete; a
+ * discovery entry (`objectFromDiscovery`) is missing its OBJECT rather than
+ * field values, so its prose and its `--object` flag differ.
+ */
+import { afterLast, pyStr } from "../../../compat/pystr.js";
+import { dictOf, listOf, pyOr, pyTruthy } from "../pyvalue.js";
+export function schemaDynamicLines(j, nodeType) {
+    if (!pyTruthy(dictOf(j.runtime).requiresConnectionForSchema))
+        return [];
+    const conn = dictOf(j.connector);
+    const op = dictOf(j.operation);
+    const key = pyStr(pyOr(conn.key, "<key>"));
+    const prefix = `uipath.connector.${key}.`;
+    const action = nodeType.startsWith(prefix) ? nodeType.slice(prefix.length) : afterLast(nodeType, ".");
+    const parents = listOf(pyOr(dictOf(op.schemaAction).parents, []));
+    const discovery = pyTruthy(op.objectFromDiscovery);
+    const out = [];
+    let supply;
+    if (discovery) {
+        out.push("> ⚠️ **The object is not in this catalog.** This node works on " +
+            "any object in the connection, including custom ones, so it " +
+            "carries no inputs here — what has to be resolved is the " +
+            "OBJECT, not a field value. Author first, then one command " +
+            "resolves it; **Choosing the object** below has the rules.");
+        supply = "--object <name-as-the-task-said-it>";
+    }
+    else {
+        out.push("> ⚠️ **This operation resolves its real inputs from a live " +
+            "connection.** The inputs listed below are only what the " +
+            "tenant-agnostic snapshot carries. Do NOT hand-guess the " +
+            "missing names.");
+        out.push(">");
+        if (parents.length) {
+            out.push("> Its parents are named outright, with the call that " +
+                "resolves each one, under **Resolving the field set** " +
+                "below. Read that first.");
+        }
+        else {
+            out.push("> Any input whose reference path carries a `{placeholder}` " +
+                "is a parent: resolve a value for EVERY parent first, then " +
+                "prepare the operation with all of them. Too few parents is " +
+                "refused; a wrong VALUE is not — it resolves right back to " +
+                "the parent fields.");
+        }
+        // The `-f` stays visible even when the catalog cannot name the parents.
+        supply = parents.length
+            ? parents.map((name) => `-f ${pyStr(name)}=<value>`).join(" ")
+            : "-f <parent-field>=<value> ...";
+    }
+    out.push(">");
+    out.push("> ```bash");
+    // ONE spelling on every page, the one `check` prints; no `--connection-id`.
+    if (discovery) {
+        out.push(`> npx flow-sdk registry prepare ${key} ${action} ${supply}`);
+    }
+    else if (supply) {
+        out.push(`> npx flow-sdk registry prepare ${key} ${action} \\`);
+        out.push(`>   ${supply}`);
+    }
+    else {
+        out.push(`> npx flow-sdk registry prepare ${key} ${action}`);
+    }
+    out.push("> ```");
+    out.push(">");
+    let overlay = "> It writes a `./connectors-local/` overlay the compiler " +
+        "auto-detects (its fields are unioned onto this entry).";
+    if (!discovery) {
+        overlay +=
+            " The full loop — how to find the parents and resolve their " +
+                "values — is in the connector guide " +
+                "(`references/connector-params.md`) under \"Schema-dynamic " +
+                "operations: the parent-field loop\".";
+    }
+    out.push(overlay);
+    out.push("> This requires a working live connection. For an explicitly " +
+        "offline/validate-only flow that needs no connection-specific fields, " +
+        "use the published static inputs below instead; a placeholder " +
+        "connection cannot materialize a live schema. If that input list is " +
+        "empty, pass `{}`: offline evidence proves operation identity and " +
+        "control routing, not the provider payload or dispatch.");
+    out.push("");
+    return out;
+}

package/dist/registry/generators/materialize.d.ts

@@ -0,0 +1,30 @@
+import { type Reporter } from "../reporter.js";
+export interface MaterializeOptions {
+    /** The extracted library; must hold an `index.json`. */
+    libraryJsonPath: string;
+    /** Where the Markdown goes. Omit to skip it. */
+    libraryMarkdownPath?: string;
+    /** Where the descriptor modules go. Omit to generate none. */
+    connectorsPath?: string;
+    /** Connector keys to emit descriptors for, instead of all of them. */
+    connectorSubset?: readonly string[];
+    /** Module specifier the generated TypeScript imports the SDK from. */
+    connectorImport?: string;
+    /** `registry-triggers.json`, for `<key>.triggers.ts` modules beside the descriptors. */
+    triggersPath?: string;
+    /** Also emit descriptors for GenericExpanded entries (the overlay's case). */
+    includeGenericExpanded?: boolean;
+    /** Fail when a page cites a symbol the modules do not export. */
+    checkSymbols?: boolean;
+    reporter?: Reporter;
+}
+export interface MaterializeResult {
+    markdownFiles: number;
+    typescriptModules: number;
+    /** `nodeType → exported const`, for callers that print a handoff. */
+    symbols: Map<string, string>;
+    warnings: string[];
+}
+export declare function materialize(options: MaterializeOptions): MaterializeResult;
+/** Remove a staging directory left by an interrupted run, if any. */
+export declare function cleanStaging(target: string): void;

package/dist/registry/generators/materialize.js

@@ -0,0 +1,132 @@
+/**
+ * Turn an extracted `library-json/` into the two derived views: Markdown pages
+ * an agent reads and TypeScript descriptor modules an author imports.
+ *
+ * This is `materialize_registry.py` without the subprocesses: the three
+ * generators it used to spawn are function calls. What it keeps is every
+ * observable rule of the Python — the connectors directory is wiped first, the
+ * Markdown is staged beside its target and swapped in, a missing trigger
+ * catalogue is an error, the trigger subset is deliberately NOT narrowed to the
+ * connector subset (the Python never forwarded it; file counts depend on that),
+ * and a required-input gap fails the run after the descriptor modules are
+ * written but before the trigger modules are, the way the descriptor
+ * generator's `sys.exit` did.
+ *
+ * New, behind a flag: `checkSymbols` runs the cross-check that used to be a
+ * separate script in `unpack-library.sh`, so a page can never cite a symbol
+ * the descriptors do not export.
+ */
+import { PACKAGE_NAME } from "../../package-name.js";
+import { existsSync, readdirSync, readFileSync, rmSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { pyJsonDocument } from "../codecs/pyjson.js";
+import { Refusal } from "../errors.js";
+import { listFiles, resetDir, stageAndSwap, writeText } from "../files.js";
+import { loadLibrary } from "../library-reader.js";
+import { silentReporter } from "../reporter.js";
+import { formatRequiredInputGaps, renderDescriptorModules } from "./descriptors.js";
+import { renderMarkdownLibrary } from "./markdown/index.js";
+import { citedSymbolMismatches, formatMismatches } from "./md-symbols.js";
+import { renderTriggerModules } from "./triggers.js";
+const DEFAULT_IMPORT = PACKAGE_NAME;
+function countFiles(dir, suffix, recursive) {
+    if (!dir || !existsSync(dir))
+        return 0;
+    if (recursive)
+        return listFiles(dir, (rel) => rel.endsWith(suffix)).length;
+    return readdirSync(dir, { withFileTypes: true }).filter((e) => e.isFile() && e.name.endsWith(suffix)).length;
+}
+/** The pages on disk under a Markdown tree, keyed like `renderMarkdownLibrary` keys them. */
+function readPages(markdownDir) {
+    const pages = new Map();
+    for (const rel of listFiles(markdownDir, (r) => r.endsWith(".md"))) {
+        pages.set(rel, readFileSync(join(markdownDir, rel), "utf8"));
+    }
+    return pages;
+}
+export function materialize(options) {
+    const reporter = options.reporter ?? silentReporter;
+    const libraryJson = resolve(options.libraryJsonPath);
+    const libraryMd = options.libraryMarkdownPath ? resolve(options.libraryMarkdownPath) : undefined;
+    const connectors = options.connectorsPath ? resolve(options.connectorsPath) : undefined;
+    if (!existsSync(join(libraryJson, "index.json"))) {
+        throw new Refusal(`materialize-registry: missing ${join(libraryJson, "index.json")}`, "LIBRARY_MISSING");
+    }
+    const outputs = [libraryMd, connectors].filter((p) => p !== undefined);
+    if (outputs.includes(libraryJson) || new Set(outputs).size !== outputs.length) {
+        throw new Refusal("materialize-registry: input and output directories must be distinct", "OUTPUTS_NOT_DISTINCT");
+    }
+    const warnings = [];
+    const library = loadLibrary(libraryJson);
+    if (connectors !== undefined)
+        resetDir(connectors);
+    let pages;
+    if (libraryMd !== undefined) {
+        // Generate beside the target and swap, exactly as pull-cli does for
+        // library-json: two `registry pull`s racing on the shared final path (a
+        // coding agent issues tool calls in parallel) once left one of them with
+        // "Directory not empty" mid-write.
+        const rendered = renderMarkdownLibrary(library);
+        for (const warning of rendered.warnings)
+            reporter.warn(warning);
+        warnings.push(...rendered.warnings);
+        stageAndSwap(libraryMd, (staging) => {
+            for (const [rel, text] of rendered.pages)
+                writeText(join(staging, rel), text);
+            writeText(join(staging, "index.json"), pyJsonDocument(rendered.index));
+        });
+        pages = rendered.pages;
+    }
+    let modules = new Map();
+    let symbols = new Map();
+    if (connectors !== undefined) {
+        const output = renderDescriptorModules(library, {
+            importSpecifier: options.connectorImport ?? DEFAULT_IMPORT,
+            connectors: options.connectorSubset?.filter((c) => c.length > 0),
+            includeGenericExpanded: options.includeGenericExpanded,
+        });
+        modules = output.modules;
+        symbols = output.symbols;
+        for (const [name, text] of modules)
+            writeText(join(connectors, name), text);
+        // The descriptor generator wrote every module and then exited 1 on a gap,
+        // and `materialize_registry.py` ran it with `check=True`, so the trigger
+        // generator that came next never ran. Same here: the descriptor modules
+        // are on disk, the failure is as loud, and no `.triggers.ts` is written
+        // beside them.
+        if (output.requiredInputGaps.length > 0) {
+            throw new Refusal(formatRequiredInputGaps(output.requiredInputGaps), "REQUIRED_INPUT_GAP");
+        }
+        if (options.triggersPath) {
+            const triggersPath = resolve(options.triggersPath);
+            if (!existsSync(triggersPath)) {
+                throw new Refusal(`materialize-registry: missing trigger catalog ${triggersPath}`, "TRIGGERS_MISSING");
+            }
+            const catalogue = JSON.parse(readFileSync(triggersPath, "utf8"));
+            // The connector subset is not forwarded here, as the Python never did.
+            for (const [name, text] of renderTriggerModules(catalogue, { importSpecifier: options.connectorImport ?? DEFAULT_IMPORT })) {
+                writeText(join(connectors, name), text);
+            }
+        }
+    }
+    if (options.checkSymbols && connectors !== undefined) {
+        const checked = pages ?? (libraryMd && existsSync(libraryMd) ? readPages(libraryMd) : undefined);
+        if (checked) {
+            const bad = citedSymbolMismatches(checked, modules);
+            if (bad.length > 0)
+                throw new Refusal(formatMismatches(bad), "MD_SYMBOL_MISMATCH");
+        }
+    }
+    const result = {
+        markdownFiles: countFiles(libraryMd, ".md", true),
+        typescriptModules: countFiles(connectors, ".ts", false),
+        symbols,
+        warnings,
+    };
+    reporter.info(`materialize-registry: generated ${result.markdownFiles} markdown file(s) and ${result.typescriptModules} TypeScript module(s)`);
+    return result;
+}
+/** Remove a staging directory left by an interrupted run, if any. */
+export function cleanStaging(target) {
+    rmSync(`${target}.tmp-${process.pid}`, { recursive: true, force: true });
+}

package/dist/registry/generators/md-symbols.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Every descriptor symbol the Markdown cites must exist in the emitted TypeScript.
+ *
+ * The `## Example` on each page names an exported const —
+ * `connector(SendMessageToUser, …)` — and imports it from
+ * `./connectors/<key>.ts`. Neither the const name nor the `.by*` aliases are in
+ * the JSON library: both are derived by `naming.symbolIndex`, which the
+ * Markdown and descriptor generators share precisely so they cannot disagree.
+ * This is the check that proves the sharing is real rather than intended.
+ * Ported from `check_md_symbols.py`.
+ */
+/** `{ connectorKey → exported const names }` from `<key>.ts` module texts, `.triggers.ts` excluded. */
+export declare function exportedSymbols(modules: ReadonlyMap<string, string>): Map<string, Set<string>>;
+/**
+ * One line per page that cites a symbol its module does not export, as
+ * `<page> cites <key>.<Symbol>`, in page order.
+ */
+export declare function citedSymbolMismatches(pages: ReadonlyMap<string, string>, modules: ReadonlyMap<string, string>): string[];
+/** How many mismatches to print before truncating. */
+export declare const MAX_REPORTED = 20;
+/** The stderr text `check_md_symbols.py` printed, for the same mismatches. */
+export declare function formatMismatches(bad: readonly string[]): string;

package/dist/registry/generators/md-symbols.js

@@ -0,0 +1,58 @@
+/**
+ * Every descriptor symbol the Markdown cites must exist in the emitted TypeScript.
+ *
+ * The `## Example` on each page names an exported const —
+ * `connector(SendMessageToUser, …)` — and imports it from
+ * `./connectors/<key>.ts`. Neither the const name nor the `.by*` aliases are in
+ * the JSON library: both are derived by `naming.symbolIndex`, which the
+ * Markdown and descriptor generators share precisely so they cannot disagree.
+ * This is the check that proves the sharing is real rather than intended.
+ * Ported from `check_md_symbols.py`.
+ */
+/** `export const X =` at a line start; `\w` as Python spells it, Unicode-aware. */
+const EXPORTED = /^export const ([\p{L}\p{N}_]+) =/gmu;
+/** `import { X } from './connectors/<key>.ts'` or `./connectors-local/…`. */
+const CITED = /import \{ ([\p{L}\p{N}_]+) \} from '\.\/connectors(?:-local)?\/([^']+)\.ts'/gu;
+/** `{ connectorKey → exported const names }` from `<key>.ts` module texts, `.triggers.ts` excluded. */
+export function exportedSymbols(modules) {
+    const out = new Map();
+    for (const [fileName, text] of modules) {
+        // `<key>.triggers.ts` is the connector-EVENT surface, a different catalogue
+        // with its own identity-only descriptors. Pages never import from it.
+        if (!fileName.endsWith(".ts") || fileName.endsWith(".triggers.ts"))
+            continue;
+        const names = new Set();
+        for (const match of text.matchAll(EXPORTED))
+            names.add(match[1]);
+        out.set(fileName.slice(0, -3), names);
+    }
+    return out;
+}
+/**
+ * One line per page that cites a symbol its module does not export, as
+ * `<page> cites <key>.<Symbol>`, in page order.
+ */
+export function citedSymbolMismatches(pages, modules) {
+    const exported = exportedSymbols(modules);
+    const bad = [];
+    for (const [page, text] of pages) {
+        for (const match of text.matchAll(CITED)) {
+            const [, symbol, key] = match;
+            if (!exported.get(key)?.has(symbol))
+                bad.push(`${page} cites ${key}.${symbol}`);
+        }
+    }
+    return bad;
+}
+/** How many mismatches to print before truncating. */
+export const MAX_REPORTED = 20;
+/** The stderr text `check_md_symbols.py` printed, for the same mismatches. */
+export function formatMismatches(bad) {
+    const lines = [`error: ${bad.length} markdown page(s) cite a descriptor symbol that was never emitted:`];
+    for (const line of bad.slice(0, MAX_REPORTED))
+        lines.push(`  ${line}`);
+    if (bad.length > MAX_REPORTED)
+        lines.push(`  … and ${bad.length - MAX_REPORTED} more`);
+    lines.push("       Both generators derive symbol names through registry/naming.ts (symbolIndex).", "       A mismatch means one of them stopped using it. See docs/CONNECTOR_LOOKUP_DESIGN.md §6.4.");
+    return lines.join("\n");
+}