@uipath/maestro-builder-sdk 5.2.0

package/dist/check-cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { type CliExitCode } from './cli-run.js';
+export declare function run(argv: string[]): Promise<CliExitCode>;

package/dist/check-cli.js

@@ -0,0 +1,118 @@
+#!/usr/bin/env node
+/**
+ * check-cli — static-validate an authored flow without emitting.
+ *
+ * Usage: node --experimental-strip-types check-cli.js <flow.ts | BaseName>
+ * Prints diagnostics; exits non-zero if any errors.
+ */
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { resolveFlowFile, loadBuiltFlow } from './load.js';
+import { check } from './check.js';
+import { Library } from './library.js';
+import { Bindings } from './bindings.js';
+import { connectorInputErrors } from './serialize.js';
+import { runWhenInvokedDirectly } from './cli-run.js';
+import { ensureTypeScriptRuntime } from './node-runtime.js';
+import { resolveLibraryDir } from './registry/cache.js';
+/**
+ * Library lookups for the checks whose facts live in the connector corpus:
+ * event parameters and measured list envelopes.
+ *
+ * Deliberately optional. `check` is the fast inner-loop rung and stays a pure
+ * function of the built flow — with no library it simply cannot know whether an
+ * empty `where` is correct, so it fails open (a warning, not an error). Given a
+ * library, `compile` and `check` make the same call with the facts in hand.
+ * `--library` mirrors compile-cli's flag and default.
+ */
+function checkOpts(argv) {
+    const flag = argv.indexOf('--library');
+    const libDir = resolveLibraryDir(flag >= 0 ? argv[flag + 1] : undefined);
+    // bindings.json beside the source, exactly as compile-cli finds it — so the
+    // own-name refusal compile would raise is reported here first.
+    const bindFlag = argv.indexOf('--bindings');
+    const bindFile = bindFlag >= 0 ? argv[bindFlag + 1] : (existsSync('bindings.json') ? 'bindings.json' : undefined);
+    const bindings = bindFile ? new Bindings(bindFile) : undefined;
+    if (!libDir || !existsSync(join(libDir, 'index.json')))
+        return bindings ? { bindings } : {};
+    // The overlay matters here as much as it does for compile: `resolutions.json`
+    // lives in it, and without it every already-resolved lookup would be reported
+    // as still owed — telling the author to re-run a `prepare` they already ran.
+    const overlayDir = existsSync(join('connectors-local', 'index.json'))
+        ? 'connectors-local'
+        : undefined;
+    const library = new Library(libDir, { overlayDir });
+    return {
+        eventParams: (connector, event, object) => {
+            try {
+                return library.eventParameterFields(connector, event, object);
+            }
+            catch {
+                // An unresolvable operation is EVENT_UNKNOWN's business (compile reports
+                // it against the real library); here it just means "unknown".
+                return undefined;
+            }
+        },
+        eventFilterFields: (connector, event, object) => {
+            try {
+                return library.eventFilterFields(connector, event, object);
+            }
+            catch {
+                return undefined; // unknown fails open, same as every callback here
+            }
+        },
+        lookups: (connector, action, version, object) => library.lookupSpecs(connector, action, version, object),
+        resolutions: library.lookupResolutions,
+        schemaReadiness: (connector, action, version, object) => {
+            try {
+                return library.schemaReadiness(connector, action, version, object);
+            }
+            catch {
+                // An unreadable entry means "unknown", and unknown fails open — the
+                // same rule as every other callback here.
+                return undefined;
+            }
+        },
+        listEnvelope: (connector, operation, version, object) => {
+            try {
+                return library.resolve(connector, operation, version, object).listEnvelope;
+            }
+            catch {
+                return undefined;
+            }
+        },
+        // The field contract compile enforces, from the same validator: an operation
+        // the library cannot resolve is compile's business (it names the entry).
+        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 } : {}),
+    };
+}
+export async function run(argv) {
+    const arg = argv.find((a) => !a.startsWith('--')) ?? argv[0];
+    if (!arg || arg === '-h' || arg === '--help') {
+        console.error('usage: check [--library <dir>] [--bindings <file>] <flow.ts | BaseName>');
+        return 2;
+    }
+    const file = resolveFlowFile(arg);
+    ensureTypeScriptRuntime();
+    const built = await loadBuiltFlow(file);
+    const diags = check(built, checkOpts(argv));
+    if (diags.length === 0) {
+        console.log('✓ no issues');
+        return 0;
+    }
+    for (const d of diags)
+        console.log(`${d.level === 'error' ? '✗' : '⚠'} [${d.code}] ${d.message}${d.suggestion ? ` (did you mean "${d.suggestion}"?)` : ''}`);
+    const errors = diags.filter((d) => d.level === 'error').length;
+    console.log(`\n${errors} error(s), ${diags.length - errors} warning(s)`);
+    return errors ? 1 : 0;
+}
+runWhenInvokedDirectly(import.meta.url, 'check', run);

package/dist/check.d.ts

@@ -0,0 +1,146 @@
+import { type LookupResolutions, type LookupSpec } from './core/lookups.js';
+import type { SchemaReadiness } from './core/library.js';
+import type { BuiltFlow } from './flow-sdk.js';
+export interface Diagnostic {
+    level: 'error' | 'warning';
+    code: string;
+    message: string;
+    step?: string;
+    suggestion?: string;
+}
+/**
+ * What a connector operation declares as its EVENT PARAMETERS — the `where` half
+ * of a subscription. `known: false` means "no library was supplied", which is a
+ * different answer from `known: true, names: []` ("this operation takes none").
+ * Conflating the two is what made `EVENT_NO_SCOPE` an error for the HTTP Webhook
+ * connector, whose only correct `where` is empty.
+ */
+export interface EventParamFields {
+    known: boolean;
+    names: string[];
+    /**
+     * The operation is a GENERIC event (`activityType: GenericTrigger`): its node type
+     * covers every object of the connection, so the subscription must name one with
+     * `object`. Unknown (no library) reads as `false`, which fails open.
+     */
+    generic?: boolean;
+    /** The entry's own object — `''` for a generic event, the built-in one for a curated event. */
+    object?: string;
+    /**
+     * Required parameters that SELECT the schema rather than scope the
+     * subscription (Jira's `project` / `issuetype`). Their values decide which
+     * filter and output fields exist, and no CLI surface accepts them — so when
+     * this is non-empty the known filter vocabulary is a BASELINE, and a leaf
+     * outside it may still be legal.
+     */
+    selectors?: string[];
+    /**
+     * The named object has no prepared variant on a connector whose objects come
+     * from the connection — the generic template answered instead.
+     */
+    objectUnprepared?: boolean;
+    /**
+     * The connector discovers custom fields per connection and nothing has
+     * prepared this event, so the known vocabulary is a strict subset of the
+     * tenant's BY DESIGN.
+     */
+    customFieldsUnprepared?: boolean;
+    /**
+     * The filter vocabulary is a subset that NO prepare can complete.
+     *
+     * An activity closes this gap: `resources describe` takes `-f name=value`
+     * and `--action`, so supplying the parent values runs the connector's
+     * ObjectAction (Jira `GenerateSchema`, Salesforce `GenerateQuerySchema`) and
+     * the custom fields come back. `uip is triggers describe` has neither flag,
+     * so for an EVENT on a custom-field-discovering connector there is no call
+     * that reaches the parent-scoped fields — the designer grows Jira's filter
+     * list once a project and issue type are picked, and nothing in this CLI
+     * can. Distinct from `customFieldsUnprepared`, which preparing DOES fix.
+     */
+    filtersPartial?: boolean;
+}
+export interface ListEnvelopeFields {
+    envelope: string | null;
+    source: string;
+    tier: string;
+}
+export interface CheckOpts {
+    /**
+     * Resolve a connector event's declared event parameters, by connector key and
+     * event name. Supplied by `check-cli` when `$FLOW_SDK_LIBRARY_JSON` points at a
+     * library; omitted (and so unknown) otherwise.
+     *
+     * A function rather than a `Library`, on purpose: `check` stays a pure function
+     * of the built flow plus this one lookup, so it needs no library at all to run
+     * and cannot be slowed down by one.
+     */
+    eventParams?: (connector: string, event: string, object?: string) => EventParamFields | undefined;
+    /**
+     * Resolve a connector event's FILTERABLE field names — the vocabulary a
+     * `filters` leaf may name — sourced the same way as `eventParams`. A GENERIC
+     * event's vocabulary is per object, so the subscription's `object` rides
+     * along. `undefined` means unknown and fails open; a known-EMPTY list also
+     * fails open, because connectors that declare no filter fields exist and
+     * refusing every leaf on their events would turn a coverage gap into a
+     * false error.
+     */
+    eventFilterFields?: (connector: string, event: string, object?: string) => string[] | undefined;
+    /**
+     * Resolve one connector operation's generated lookup table, keyed by field.
+     *
+     * Supplied by the CLIs when a library is on hand, omitted otherwise — so a
+     * `check` with no library simply does not fire the lookup rules rather than
+     * guessing at them.
+     */
+    lookups?: (connector: string, action: string, version?: string, object?: string) => Readonly<Record<string, LookupSpec>> | undefined;
+    /** Everything `registry prepare --resolve` has recorded in the local overlay. */
+    resolutions?: LookupResolutions;
+    /**
+     * Whether a connector step's schema is materialized locally — the fact behind
+     * the OBJECT_UNPREPARED and CUSTOM_FIELDS_UNPREPARED warnings. Supplied by the
+     * CLIs when a library is on hand, omitted otherwise, same as `lookups`: with
+     * no library, `check` cannot know what is owed and says nothing.
+     */
+    schemaReadiness?: (connector: string, action: string, version?: string, object?: string) => SchemaReadiness | undefined;
+    /** Resolve the measured collection envelope for one connector operation. */
+    listEnvelope?: (connector: string, operation: string, version?: string, object?: string) => ListEnvelopeFields | undefined;
+    /**
+     * What `compile` would refuse one connector step's inputs with — a missing
+     * required field, an unknown or mistyped input, a container part given a value —
+     * or `undefined` when it would accept them. Supplied by the CLIs from the same
+     * library-backed validator `serialize` runs (`connectorInputErrors`), so the
+     * inner loop and the emit rung cannot disagree; omitted (no library) → not checked.
+     * Before this hook, `check` printed `0 error(s)` for a source `compile` then
+     * refused twice in a row (teams-decision, 2026-09-01, turns 22–25).
+     */
+    connectorInputs?: (spec: {
+        key: string;
+        action: string;
+        version?: string;
+        object?: string;
+    }, inputs: Record<string, unknown>) => string | undefined;
+    /**
+     * The project's `bindings.json`, when there is one — enough of it to detect an
+     * entry that answers with its own name, which `compile` refuses (BINDING_SELF_NAME).
+     */
+    bindings?: {
+        resolve(name?: string): string | undefined;
+    };
+}
+export declare function check(built: BuiltFlow, opts?: CheckOpts): Diagnostic[];
+/**
+ * The ISO-8601 repeating-interval pattern, copied VERBATIM from the
+ * `core.trigger.scheduled@1.1` definition (`inputDefinition.then.properties.
+ * timerValue.pattern`). `core-definitions.test.ts` pins the two as equal, so if
+ * the definition's pattern ever changes this constant fails a test instead of
+ * silently drifting.
+ */
+export declare const SCHEDULE_PATTERN: string;
+/**
+ * The Quartz-cron alternative of the scheduled trigger's **1.2** definition
+ * pattern (`core-definitions.json`, `core.trigger.scheduled@1.2` — transcribed
+ * from `registry get` 2026-08-18; `core-definitions.test.ts` pins the two as
+ * consistent): 6–7 whitespace-separated fields of digits/ranges/steps, month
+ * and day names, and the Quartz specials `L W LW ? * #`.
+ */
+export declare const SCHEDULE_CRON_PATTERN: string;