@uipath/maestro-builder-sdk 5.2.0

package/dist/compile-cli.js

@@ -0,0 +1,160 @@
+#!/usr/bin/env node
+/**
+ * compile-cli — flow.ts → <Name>.flow
+ *
+ * Usage:
+ *   node --experimental-strip-types compile-cli.js <flow.ts | BaseName> \
+ *        [-o out.flow] [--library <library-json dir>] [--bindings <bindings.json>] \
+ *        [--no-check]
+ *
+ * --library defaults to $FLOW_SDK_LIBRARY_JSON; --bindings defaults to
+ * ./bindings.json when present. Connector actions require a library.
+ *
+ * `--no-check` skips the SDK's static `check()` pass and emits whatever
+ * `.build()` produced. It exists for loops whose verification is somewhere else
+ * entirely — e.g. authoring against the product CLI (`uip maestro flow
+ * validate` / `debug`), where a pre-emit static pass would answer questions the
+ * product's own gates are supposed to answer. `.build()` still throws on
+ * structural problems; only the diagnostic pass is skipped.
+ */
+import { writeFileSync, existsSync, mkdirSync } from 'node:fs';
+import { basename, dirname, join, resolve } from 'node:path';
+import { resolveFlowFile, loadBuiltFlow } from './load.js';
+import { serializeWithSidecars, connectorInputErrors } from './serialize.js';
+import { check } from './check.js';
+import { Library } from './library.js';
+import { resolveLibraryDir } from './registry/cache.js';
+import { Bindings } from './bindings.js';
+import { runWhenInvokedDirectly } from './cli-run.js';
+import { connectionResources, mergeBindingsV2, readBindingsV2 } from './bindings-v2.js';
+import { ensureTypeScriptRuntime } from './node-runtime.js';
+function opt(argv, name) {
+    const i = argv.indexOf(name);
+    return i >= 0 ? argv[i + 1] : undefined;
+}
+export async function run(argv) {
+    if (argv.length === 0 || argv[0] === '-h' || argv[0] === '--help') {
+        console.error('usage: compile <flow.ts | BaseName> [-o out.flow] [--library <dir>] [--bindings <file>]');
+        return 2;
+    }
+    const flags = new Set(['-o', '--library', '--bindings', '--connectors-local']);
+    const noCheck = argv.includes('--no-check');
+    const pos = argv.find((a, i) => !flags.has(a) && !flags.has(argv[i - 1]));
+    if (!pos) {
+        console.error('compile: missing <flow.ts | BaseName>');
+        return 2;
+    }
+    const file = resolveFlowFile(pos);
+    ensureTypeScriptRuntime();
+    const built = await loadBuiltFlow(file);
+    // --library, else $FLOW_SDK_LIBRARY_JSON, else the shared cache `registry pull`
+    // filled. Resolving through one helper is what stops `pull` and `compile`
+    // disagreeing about where the library is — they did, and a pulled library was
+    // invisible to this command.
+    const libDir = resolveLibraryDir(opt(argv, '--library'));
+    const bindFile = opt(argv, '--bindings') ?? (existsSync('bindings.json') ? 'bindings.json' : undefined);
+    // A `prepare-connector`/`prepare-trigger` overlay: auto-detected next to the
+    // flow (like bindings.json), it shadows the baked library with full,
+    // connection-resolved field schemas. See core/library.ts (LibraryOpts.overlayDir).
+    const overlayDir = opt(argv, '--connectors-local')
+        ?? (existsSync(join('connectors-local', 'index.json')) ? 'connectors-local' : undefined);
+    // Only load the library when it's actually present; flows without connectors
+    // (e.g. HTTP-only) then compile fine even if the connector cache isn't built.
+    // A connector action with no library resolves to a clear error in serialize().
+    //
+    // Loaded BEFORE check() on purpose: one of check's rules (whether a connector
+    // event operation declares any event parameters) can only be answered from the
+    // library, and answering it from an assumption instead is what made
+    // EVENT_NO_SCOPE an error for HTTP Webhook, whose only correct `where` is empty.
+    const library = libDir && existsSync(join(libDir, 'index.json')) ? new Library(libDir, { overlayDir }) : undefined;
+    const bindings = new Bindings(bindFile);
+    if (!noCheck) {
+        const diags = check(built, library
+            ? {
+                eventParams: (connector, event) => {
+                    try {
+                        return library.eventParameterFields(connector, event);
+                    }
+                    catch {
+                        return undefined; // unresolvable: serialize() reports it properly
+                    }
+                },
+                lookups: (connector, action, version, object) => library.lookupSpecs(connector, action, version, object),
+                resolutions: library.lookupResolutions,
+                // Same validator serialize() runs below, so the check pass names the
+                // refusal (and stops) instead of printing `0 error(s)` first.
+                connectorInputs: (spec, inputs) => {
+                    try {
+                        const rc = library.resolve(spec.key, spec.action, spec.version, spec.object);
+                        return connectorInputErrors(rc, inputs, library.lookupResolutions ?? {}, library.lookupSpecs(spec.key, spec.action, spec.version, spec.object) ?? {});
+                    }
+                    catch {
+                        return undefined;
+                    }
+                },
+                bindings,
+            }
+            : { bindings });
+        const errors = diags.filter((d) => d.level === 'error');
+        for (const d of diags)
+            console.error(`  ${d.level === 'error' ? '✗' : '⚠'} [${d.code}] ${d.message}${d.suggestion ? ` (did you mean "${d.suggestion}"?)` : ''}`);
+        if (errors.length) {
+            console.error(`compile: ${errors.length} error(s); not emitting.`);
+            return 1;
+        }
+    }
+    // The serializer's own observations — a connection or folder value that can
+    // never be a tenant resource key — printed in the same `⚠ [CODE]` shape as
+    // check()'s, and never fatal: the .flow is still written, exit stays 0.
+    const warnings = [];
+    const { flow: flowJson, sidecars } = serializeWithSidecars(built, {
+        library, bindings, warn: (w) => warnings.push(w),
+    });
+    for (const w of warnings)
+        console.error(`  ⚠ [${w.code}] ${w.message}`);
+    const out = opt(argv, '-o') ?? `${built.name || basename(file).replace(/\.flow\.ts$|\.ts$/, '')}.flow`;
+    writeFileSync(out, JSON.stringify(flowJson, null, 2) + '\n');
+    console.log(`compile: wrote ${out} (${flowJson.nodes.length} nodes, ${flowJson.edges.length} edges)`);
+    // An inline agent is TWO artifacts: the node, and the agent's own configuration
+    // at `<source>/agent.json` — which is where flow-v1's serializer points the
+    // runtime (`entryPoint: "<source>/agent.json"`, resolved relative to the
+    // project). Writing only the `.flow` would emit a node referencing a definition
+    // that is not on disk, which validates locally and has nothing to run deployed.
+    // Sidecar paths are relative to the emitted flow, and are confined to its
+    // directory: a `..` or absolute path in one would be a bug here, not author
+    // input, but it is cheap to refuse rather than write outside the project.
+    const outDir = dirname(resolve(out));
+    for (const s of sidecars) {
+        const target = resolve(outDir, s.path);
+        if (target !== outDir && !target.startsWith(outDir + '/')) {
+            console.error(`compile: refusing to write a sidecar outside the flow's directory: ${s.path}`);
+            return 1;
+        }
+        mkdirSync(dirname(target), { recursive: true });
+        writeFileSync(target, JSON.stringify(s.json, null, 2) + '\n');
+        console.log(`compile: wrote ${s.path}`);
+    }
+    // `bindings_v2.json` — the solution-resource sidecar `uip solution resources
+    // refresh` reads. Without it the connection is never declared, so the canvas
+    // and the VS Code extension flag the Flow's connection as invalid
+    // (flow-builder-sdk#689). Written only inside a scaffolded Flow project:
+    // `project.uiproj` is what makes the output directory a project rather than
+    // somewhere a `.flow` was merely dropped, and littering a scratch directory
+    // with a resource declaration nothing reads would be worse than not writing it.
+    if (existsSync(join(outDir, 'project.uiproj'))) {
+        const sidecarPath = join(outDir, 'bindings_v2.json');
+        const connections = connectionResources(flowJson);
+        const existing = readBindingsV2(sidecarPath);
+        // Nothing to declare and nothing already declared — do not create an empty
+        // file for a flow that has no resources at all.
+        if (connections.length > 0 || existing !== undefined) {
+            const merged = mergeBindingsV2(existing, connections);
+            writeFileSync(sidecarPath, JSON.stringify(merged, null, 2) + '\n');
+            const kept = merged.resources.length - connections.length;
+            console.log(`compile: wrote bindings_v2.json (${connections.length} connection resource(s)`
+                + `${kept > 0 ? `, ${kept} other resource(s) preserved` : ''})`);
+        }
+    }
+    return 0;
+}
+runWhenInvokedDirectly(import.meta.url, 'compile', run);

package/dist/config.d.ts

@@ -0,0 +1,47 @@
+/**
+ * config — build a connector node's `inputs.detail.configuration` envelope.
+ *
+ * `uip maestro flow validate` requires connector configuration to be a
+ * `=jsonString:`-wrapped `{ essentialConfiguration, optionalConfiguration }`
+ * envelope. This mirrors the platform's own rehydrateConfiguration (Tier-A defaults
+ * + library-derived per-connector statics), minus the fieldsContainer sidecar.
+ */
+/**
+ * Convert an Integration Service operation discriminator into an HTTP transport
+ * verb. `GETBYID` identifies a curated Retrieve operation in the connector
+ * library, but the runtime's transport fields accept real HTTP methods only.
+ * Keep the discriminator in `instanceParameters`; normalize only fields that
+ * drive the request transport.
+ */
+export declare function transportHttpMethod(method: string): string;
+/**
+ * Compose the `=jsonString:`-wrapped configuration for a connector library entry.
+ *
+ * ## Two things here are measured, not chosen
+ *
+ * Census over **every** connector node in the deployed corpus — 4,026 `.flow`
+ * artifacts from the v1 nightlies, 1,421 nodes carrying an `instanceParameters`:
+ *
+ * | activityType | n | `instanceParameters` keys | `essentialConfiguration.operation` |
+ * |---|--:|---|---|
+ * | `Curated` | 1,104 | activityType · connectorKey · **httpMethod** · objectName · **subType** · supportsStreaming · version | the VERB: create 452 · list 332 · retrieve 319 · update 1 |
+ * | `Generic` | 84 | activityType · connectorKey · objectName · **operation** · supportsStreaming · version | the VERB: list 72 · retrieve 12 |
+ * | `CuratedTrigger`/`WaitFor` | 233 | + eventOperation · eventMode | absent |
+ *
+ * 1. **`operation` is the operation's VERB.** It was hard-wired to the Tier-A
+ *    default `'create'` here, so a List node shipped `operation: "create"` —
+ *    wrong on 736 of the 1,188 platform nodes that declare it (62%), silently,
+ *    since nothing local reads it. It is `lowercase(entry.operation.name)`; the
+ *    library's names (`List` 2,149 · `Create` 1,969 · `Retrieve` 1,180 · `Delete`
+ *    742 · `Update` 573 · `Replace` 390 · …) lower-case exactly onto the
+ *    platform's values.
+ * 2. **`instanceParameters` branches on activityType.** `operation` appears there
+ *    on exactly **84** nodes and `activityType: "Generic"` on exactly **84** —
+ *    the same 84 — while `httpMethod` and `subType` appear on **none** of them.
+ *    So a Generic instance names its verb there and drops the two curated fields.
+ *
+ * Neither is cosmetic for a generic node: v1's own `check_generic_dynamic_node.py`
+ * identifies the activity semantically, by `activityType == 'generic'` **and
+ * `operation == 'list'`**, read from these very keys.
+ */
+export declare function buildConfiguration(entry: any, version: string, inputValues?: Record<string, unknown>, seed?: string): string;

package/dist/config.js

@@ -0,0 +1,201 @@
+/**
+ * config — build a connector node's `inputs.detail.configuration` envelope.
+ *
+ * `uip maestro flow validate` requires connector configuration to be a
+ * `=jsonString:`-wrapped `{ essentialConfiguration, optionalConfiguration }`
+ * envelope. This mirrors the platform's own rehydrateConfiguration (Tier-A defaults
+ * + library-derived per-connector statics), minus the fieldsContainer sidecar.
+ */
+import { parseCeql } from './core/ceql.js';
+const TIER_A_DEFAULTS = {
+    additionalHeaders: null,
+    baseObject: null,
+    cachedBrowserItems: [],
+    cachedLookupValues: [],
+    cachedPropertyMappings: [],
+    customFieldsRequestDetails: null,
+    eventMode: null,
+    eventOperation: null,
+    executionType: null,
+    hasBreakingChanges: false,
+    isAutopilotInvalidConfig: false,
+    jobArguments: null,
+    language: 'en-US',
+    maxPageSize: 1000,
+    objectActions: [],
+    operation: 'create',
+    packageVersion: '1.0.0',
+    primaryKeys: [],
+};
+/**
+ * Which of an operation's parameters carries a CEQL filter.
+ *
+ * The authoritative signal is live IS metadata (`design.component ===
+ * "FilterBuilder"`), which the offline connector library does not carry. The
+ * description does: measured over the shipped library's 7,036 entries, **738 of
+ * the 769 parameters named `where` say "CEQL" in their description**, and the
+ * marker correctly EXCLUDES the 102 parameters named `filter` and 9 named
+ * `$filter` — those are OData, a different language whose strings would be
+ * mangled by a CEQL parser.
+ *
+ * So the description is the discriminator and the name is not. The ~31 `where`
+ * parameters with a terse description ("Where clause") are left alone rather
+ * than guessed at: emitting a tree that disagrees with the query is worse than
+ * emitting none.
+ */
+function ceqlParameterNames(op) {
+    const parameters = Array.isArray(op.parameters) ? op.parameters : [];
+    return parameters
+        .filter((p) => typeof p?.name === 'string' && /ceql/i.test(String(p?.description ?? '')))
+        .map((p) => p.name);
+}
+/**
+ * The design-time filter trees for an operation's CEQL parameters, keyed by
+ * parameter name — `null` when it has none, matching what the platform's own
+ * artifacts carry.
+ *
+ * Only a LITERAL string is parsed. A filter built from a runtime expression
+ * renders as `=js:…` here, and the v1 authoring path turns that into a
+ * `{var_…}` placeholder plus `inputs.detail.filterVariables`; nothing offline
+ * can reproduce that pairing, and a tree that disagrees with the query string is
+ * the one outcome worse than no tree. Those keep their runtime half and get no
+ * tree — unchanged from before, rather than wrong.
+ */
+function savedFilterTrees(op, inputValues, seed) {
+    if (!inputValues)
+        return null;
+    const trees = {};
+    for (const name of ceqlParameterNames(op)) {
+        const raw = inputValues[name];
+        if (typeof raw !== 'string' || raw.trim() === '' || raw.startsWith('=js:'))
+            continue;
+        trees[name] = parseCeql(raw, `${seed}:${name}`);
+    }
+    return Object.keys(trees).length > 0 ? trees : null;
+}
+const ESSENTIAL_KEYS = new Set([
+    'connectorVersion',
+    'savedFilterTrees',
+    'customFieldsRequestDetails',
+    'executionType',
+    'httpMethod',
+    'instanceParameters',
+    'objectName',
+    'operation',
+    'packageVersion',
+    'path',
+    'unifiedTypesCompatible',
+]);
+/**
+ * Convert an Integration Service operation discriminator into an HTTP transport
+ * verb. `GETBYID` identifies a curated Retrieve operation in the connector
+ * library, but the runtime's transport fields accept real HTTP methods only.
+ * Keep the discriminator in `instanceParameters`; normalize only fields that
+ * drive the request transport.
+ */
+export function transportHttpMethod(method) {
+    return method === 'GETBYID' ? 'GET' : method;
+}
+function schemaReplayDetails(operation, inputValues) {
+    if (operation.customFieldsRequestDetails)
+        return operation.customFieldsRequestDetails;
+    const action = operation.schemaAction;
+    const parents = Array.isArray(action?.parents) ? action.parents : [];
+    if (!inputValues || typeof action?.name !== 'string' || parents.length === 0)
+        return null;
+    const parameterValues = [];
+    for (const parent of parents) {
+        const value = inputValues[parent];
+        if (!['string', 'number', 'boolean'].includes(typeof value)
+            || (typeof value === 'string' && value.startsWith('=js:'))) {
+            return null;
+        }
+        parameterValues.push([parent.replaceAll('.', '_sub_'), String(value)]);
+    }
+    return { objectActionName: action.name, parameterValues };
+}
+function envelope(flat) {
+    const essential = {};
+    const optional = {};
+    for (const [k, v] of Object.entries(flat)) {
+        if (ESSENTIAL_KEYS.has(k))
+            essential[k] = v;
+        else
+            optional[k] = v;
+    }
+    return { essentialConfiguration: essential, optionalConfiguration: optional };
+}
+/**
+ * Compose the `=jsonString:`-wrapped configuration for a connector library entry.
+ *
+ * ## Two things here are measured, not chosen
+ *
+ * Census over **every** connector node in the deployed corpus — 4,026 `.flow`
+ * artifacts from the v1 nightlies, 1,421 nodes carrying an `instanceParameters`:
+ *
+ * | activityType | n | `instanceParameters` keys | `essentialConfiguration.operation` |
+ * |---|--:|---|---|
+ * | `Curated` | 1,104 | activityType · connectorKey · **httpMethod** · objectName · **subType** · supportsStreaming · version | the VERB: create 452 · list 332 · retrieve 319 · update 1 |
+ * | `Generic` | 84 | activityType · connectorKey · objectName · **operation** · supportsStreaming · version | the VERB: list 72 · retrieve 12 |
+ * | `CuratedTrigger`/`WaitFor` | 233 | + eventOperation · eventMode | absent |
+ *
+ * 1. **`operation` is the operation's VERB.** It was hard-wired to the Tier-A
+ *    default `'create'` here, so a List node shipped `operation: "create"` —
+ *    wrong on 736 of the 1,188 platform nodes that declare it (62%), silently,
+ *    since nothing local reads it. It is `lowercase(entry.operation.name)`; the
+ *    library's names (`List` 2,149 · `Create` 1,969 · `Retrieve` 1,180 · `Delete`
+ *    742 · `Update` 573 · `Replace` 390 · …) lower-case exactly onto the
+ *    platform's values.
+ * 2. **`instanceParameters` branches on activityType.** `operation` appears there
+ *    on exactly **84** nodes and `activityType: "Generic"` on exactly **84** —
+ *    the same 84 — while `httpMethod` and `subType` appear on **none** of them.
+ *    So a Generic instance names its verb there and drops the two curated fields.
+ *
+ * Neither is cosmetic for a generic node: v1's own `check_generic_dynamic_node.py`
+ * identifies the activity semantically, by `activityType == 'generic'` **and
+ * `operation == 'list'`**, read from these very keys.
+ */
+export function buildConfiguration(entry, version, inputValues, seed = 'node') {
+    const op = entry.operation ?? {};
+    const conn = entry.connector ?? {};
+    const at = op.activityType;
+    const isGeneric = at === 'Generic' || at === 'GenericExpanded';
+    const v1ActivityType = isGeneric ? 'Generic' : 'Curated';
+    // `operation.name` is the verb (`List`, `Create`, …); the platform stores it
+    // lower-cased. Falls back to the Tier-A default for an entry that declares no
+    // name, which keeps such an entry's emission exactly as it was.
+    const verb = typeof op.name === 'string' && op.name
+        ? op.name.toLowerCase()
+        : TIER_A_DEFAULTS.operation;
+    const composed = {
+        ...TIER_A_DEFAULTS,
+        operation: verb,
+        customFieldsRequestDetails: schemaReplayDetails(op, inputValues),
+        savedFilterTrees: savedFilterTrees(op, inputValues, seed),
+        connectorKey: conn.key,
+        objectName: op.objectName,
+        httpMethod: transportHttpMethod(op.httpMethod),
+        instanceParameters: isGeneric
+            ? {
+                connectorKey: conn.key,
+                objectName: op.objectName,
+                activityType: v1ActivityType,
+                version,
+                operation: verb,
+                supportsStreaming: op.supportsStreaming,
+            }
+            : {
+                connectorKey: conn.key,
+                objectName: op.objectName,
+                httpMethod: op.httpMethod,
+                activityType: v1ActivityType,
+                version,
+                supportsStreaming: op.supportsStreaming,
+                subType: op.subType,
+            },
+        ...(conn.name ? { connectorName: conn.name } : {}),
+        ...(op.objectDisplayName ? { objectDisplayName: op.objectDisplayName } : {}),
+        ...(op.pathTemplate || op.path ? { path: op.pathTemplate || op.path } : {}),
+    };
+    return '=jsonString:' + JSON.stringify(envelope(composed));
+}