@uipath/flow-tool 1.0.4 → 1.1.0

package/dist/services/connector-binding-validator.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Connector-binding shape validator (MST-9810, upstream UiPath/cli#2027).
+ *
+ * `uip maestro flow validate` historically only checked that `node.type`
+ * existed in the definitions[] list. A flow whose nodes are generic Managed
+ * HTTP placeholders (`core.action.http.v2`) labelled like connector activities
+ * — e.g. `name: "Send Slack Message"`, `display.label: "Create Jira Issue"` —
+ * with no `inputs.detail` binding therefore passed validation cleanly, then
+ * 404'd at runtime against the unconfigured HTTP endpoint.
+ *
+ * This module looks at every Managed-HTTP node, derives whether the label is
+ * "connector-shaped" (mentions a connector keyword from the cached IS catalog
+ * or a static fallback list), and verifies that the node carries either a
+ * connector-mode or manual-mode binding. Misses surface as a `warning` by
+ * default and as `error` under `--strict-bindings`.
+ *
+ * Catalog lookup is best-effort: when the registry cache is missing
+ * (offline / first-run), a small static keyword list keeps the check active
+ * for the most common connectors (Slack, Gmail, Jira, Salesforce, …) rather
+ * than going silent — these are the same connectors most likely to be
+ * referenced by hallucinating agents.
+ */
+import type { ValidationIssue } from "./node-validators/types.js";
+/** Generic Managed HTTP node type — the type that historically slipped through. */
+export declare const MANAGED_HTTP_NODE_TYPE = "core.action.http.v2";
+/**
+ * Structural shape of a flow node the binding validator needs. Kept loose so
+ * `ParsedWorkflow` nodes satisfy it without a cast — fields beyond this set
+ * are ignored.
+ */
+export interface ConnectorBindingNode {
+    id: string;
+    type: string;
+    name?: unknown;
+    display?: {
+        label?: unknown;
+    } & Record<string, unknown>;
+    inputs?: Record<string, unknown>;
+}
+/** Structural shape of the workflow envelope the validator walks. */
+export interface ConnectorBindingWorkflow {
+    nodes: ConnectorBindingNode[];
+    subflows?: Record<string, {
+        nodes?: ConnectorBindingNode[];
+    }>;
+}
+export interface ConnectorBindingValidationOptions {
+    /**
+     * Promote each emitted issue from `warning` to `error`. Wired to the
+     * `--strict-bindings` CLI flag. Useful for CI gates that want a
+     * mislabeled HTTP node to fail the build rather than passively warn.
+     */
+    strict?: boolean;
+    /**
+     * Test-time injection. When provided, this overrides whatever
+     * `loadRegistry()` would return. Lets specs assert behavior against a
+     * known catalog without touching the user's real cache.
+     */
+    catalogOverride?: ConnectorCatalog;
+}
+/**
+ * Compact view of the IS catalog the validator actually needs — connector
+ * keywords (`key`, `name`) and a flat list of activity display tokens.
+ * Built once per `validateFile` from the cached `MaestroRegistry`.
+ */
+export interface ConnectorCatalog {
+    /**
+     * Connector keyword tokens (e.g. "slack" derived from `uipath-uipath-slack`
+     * → strip "uipath-" prefix → split by "-"). Lower-cased.
+     */
+    keywords: Set<string>;
+    /**
+     * Activity displayName token bags — each entry is the set of lowercase
+     * tokens from one activity's displayName. A label whose tokens match
+     * any entry (subset or superset) is considered connector-shaped.
+     */
+    activityTokenBags: Array<{
+        connectorKey: string;
+        connectorName: string;
+        tokens: Set<string>;
+    }>;
+}
+/**
+ * Build a `ConnectorCatalog` from the cached registry. Returns a catalog with
+ * empty `activityTokenBags` (but populated with static keywords) when no
+ * cache exists — so the check still fires for offline users.
+ */
+export declare function loadConnectorCatalog(): Promise<ConnectorCatalog>;
+/**
+ * Walk every node in the flow + every subflow and emit one issue per
+ * unbound, connector-shaped Managed HTTP node. Scope mirrors
+ * `validateResourceBindings` so the new check stays consistent with the
+ * §A4 binding-integrity pass already in `FlowValidateService`.
+ */
+export declare function validateConnectorBindings(workflow: ConnectorBindingWorkflow, catalog: ConnectorCatalog, options?: Pick<ConnectorBindingValidationOptions, "strict">): ValidationIssue[];

package/dist/services/flow-validate-service.d.ts

@@ -1,4 +1,5 @@
 import type { NodeManifest } from "@uipath/flow-core";
+import { type ConnectorCatalog } from "./connector-binding-validator.js";
 import { type FlowNodeValidator, type ValidationIssue } from "./node-validators/index.js";
 import type { WorkflowGovernanceEnforcements, WorkflowValidationRule } from "./node-validators/workflow-rule-types.js";
 interface FlowValidateResult {
@@ -51,6 +52,18 @@ export interface FlowValidateOptions {
      * enables current-manifest validation.
      */
     currentManifests?: ManifestForCurrentValidation[];
+    /**
+     * Promote connector-binding shape warnings (MST-9810) to errors. By
+     * default, an unbound Managed HTTP node carrying a connector-shaped label
+     * emits a warning so existing flows keep validating green; CI gates
+     * opt in via `--strict-bindings` to fail the build instead.
+     */
+    strictBindings?: boolean;
+    /**
+     * Test/host override for the connector catalog used by the binding-shape
+     * validator. Supplying this skips the `loadRegistry()` cache lookup.
+     */
+    connectorCatalog?: ConnectorCatalog;
 }
 export declare class FlowValidateService {
     private readonly fs;
@@ -60,7 +73,10 @@ export declare class FlowValidateService {
     private readonly availableModelNames?;
     private readonly validateCurrentManifests;
     private readonly currentManifestOverrides?;
+    private readonly strictBindings;
+    private readonly connectorCatalogOverride?;
     private currentManifestCache?;
+    private connectorCatalogCache?;
     constructor(options?: FlowValidateOptions);
     execute(flowFilePath: string): Promise<number>;
     private loadCurrentManifestMap;
@@ -100,6 +116,83 @@ export declare class FlowValidateService {
     private validateUniqueIds;
     /** Uniqueness check for `variables.globals` IDs; called once per scope (root + each subflow). */
     private validateGlobalVariableUniqueness;
+    /**
+     * Resource-node bindings integrity (residual roadmap §A4, [MST-9712]).
+     *
+     * Every process-typed node (RPA workflow, agent, API workflow, agent-tool
+     * process — see PROCESS_NODE_PREFIXES) referenced anywhere in the flow
+     * — top-level `nodes[]` AND every subflow's `nodes[]` — must have a
+     * corresponding `workflow.bindings` entry whose `resourceKey` covers the
+     * node's needs. Without it, the workflow passes `flow validate` today but
+     * fails opaquely at runtime as "Failure in the Orchestrator Job".
+     *
+     * Uses `collectNodeBindingResourceKeys` from `node-service.ts` (the same
+     * helper `ensureProcessBindings` uses on the write path) to compute each
+     * process node's needed resource keys, then checks each against the
+     * declared `bindings[].resourceKey` set.
+     */
+    private validateResourceBindings;
+    /**
+     * Cross-node connection ID reuse (residual roadmap §A6, [MST-9714]).
+     *
+     * Two distinct nodes referencing the same `inputs.detail.connectionResourceId`
+     * share runtime connection state. Often that's a bug (a node was duplicated
+     * without re-pointing the connection); sometimes it's intentional (two
+     * connectors on the same SaaS account, sharing rate-limit headroom).
+     *
+     * Severity: `warning` — legitimate sharing exists, so don't block validate.
+     * Users can investigate or ignore as appropriate.
+     *
+     * Scope: top-level `workflow.nodes` + every `workflow.subflows[].nodes`
+     * (matches A4's iteration shape for consistency).
+     */
+    private validateConnectionIdReuse;
+    /**
+     * Connector-binding shape check (MST-9810, upstream UiPath/cli#2027).
+     *
+     * Lazy-loads the IS connector catalog (cached registry from
+     * `~/.uipath/maestro/registry.json`, falling back to a static keyword
+     * list when no cache exists) and delegates to
+     * `validateConnectorBindings`. Promotes warnings to errors when
+     * constructed with `strictBindings: true` (wired to `--strict-bindings`).
+     *
+     * Catalog loading is best-effort and never throws: when the cache is
+     * missing or unreadable, the validator still runs against the static
+     * fallback keyword list. That keeps the check active for offline users
+     * who would otherwise be the most likely to hit this bug, while
+     * letting tests inject deterministic catalogs via
+     * `FlowValidateOptions.connectorCatalog`.
+     */
+    private validateConnectorBindingShapes;
+    private loadConnectorCatalogCached;
+    /**
+     * Project↔solution registration + canonical-path layout (residual roadmap
+     * §A3, [MST-9711]). Walks up from the .flow's parent looking for a
+     * `.uipx` solution file. When one is found, asserts both:
+     *
+     *  (a) the .flow's project directory is registered in the solution's
+     *      projects[] list (matched by ProjectRelativePath's directory name),
+     *      and
+     *  (b) the canonical layout: <solution>/<projectName>/<projectName>.flow
+     *      — i.e. the .flow file basename equals its parent directory name.
+     *
+     * Standalone authoring (no .uipx in any parent) is allowed — the rule
+     * stays silent in that case so single-flow workflows aren't penalised.
+     *
+     * Severity: warning. Both issues are recoverable (`uip solution project add`
+     * fixes registration; renaming the file or directory fixes the layout).
+     */
+    private validateSolutionRegistrationAndLayout;
+    /**
+     * Best-effort path canonicalization for the registration-comparison
+     * call site. Returns `fs.realpath(p)` when the call succeeds, and
+     * the original `p` when it fails (e.g., the path doesn't exist).
+     * Falling back to the literal path is deliberate: a missing path is
+     * exactly the failure mode that the surrounding validator already
+     * surfaces via other issues, and canonicalization is an optimization
+     * for symlink/case-folding correctness, not a precondition.
+     */
+    private canonicalizePath;
     /**
      * Catch stale embedded OOTB definitions. Studio Web renders against the
      * current node manifest, while .flow files carry a serialized copy of the

package/dist/services/node-service.d.ts

@@ -0,0 +1,94 @@
+import type { NodeInstance, Workflow } from "@uipath/flow-core";
+import { type ConnectorInfo } from "@uipath/maestro-sdk";
+/**
+ * Thrown when a node type is genuinely absent from the SDK bundle and the
+ * tenant manifest — i.e. a typo or a removed node.
+ */
+export declare class NodeTypeNotFoundError extends Error {
+    readonly code = "NodeTypeNotFound";
+    readonly instructions: string;
+    constructor(message: string, instructions: string);
+}
+/**
+ * Thrown when a node type IS in the SDK bundle (so it exists as a feature on
+ * the platform) but is missing from the loaded tenant manifest — almost always
+ * a feature-flag / entitlement gate.
+ */
+export declare class NodeTypeNotEnabledError extends Error {
+    readonly code = "NodeTypeNotEnabled";
+    readonly instructions: string;
+    constructor(message: string, instructions: string);
+}
+export interface NodeSummary {
+    id: string;
+    type: string;
+    label: string;
+    position: {
+        x: number;
+        y: number;
+    };
+}
+export interface ListNodesResult {
+    nodes: NodeSummary[];
+    count: number;
+}
+export declare const listNodesInFlow: (filePath: string) => Promise<ListNodesResult>;
+export interface AddNodeOptions {
+    position?: {
+        x: number;
+        y: number;
+    };
+    label?: string;
+    inputs?: Record<string, unknown>;
+    source?: string;
+}
+export interface AddNodeResult {
+    node: NodeInstance;
+    definitionAdded: boolean;
+    bindingsCreated: number;
+    variableCount: number;
+    connectorInfo?: ConnectorInfo;
+}
+export interface DeleteNodeResult {
+    deletedNode: NodeSummary;
+    edgesRemoved: number;
+    bindingsRemoved: number;
+    definitionsRemoved: number;
+    variablesRemoved: number;
+    variableUpdatesRemoved: number;
+}
+/**
+ * Node type prefixes that use process-style bindings (GUID as resourceKey).
+ * Covers RPA workflows, agent process tools, and agent nodes.
+ */
+export declare const PROCESS_NODE_PREFIXES: string[];
+export declare function isProcessNode(manifest: {
+    nodeType: string;
+}): boolean;
+/**
+ * Safety net: ensure every process/agent node in the workflow has corresponding
+ * entries in the workflow `bindings` array and that `<bindings.*>` placeholders
+ * in node model.context are resolved to `=bindings.<id>` references.
+ *
+ * This handles flows authored outside the CLI (e.g. direct file edits or
+ * skill-generated files) where `addNodeToFlow` was never called, so the
+ * binding creation / resolution step was skipped.
+ *
+ * Mutates the workflow in place. Safe to call multiple times — already-resolved
+ * nodes are skipped.
+ */
+export declare function ensureProcessBindings(workflow: Workflow): number;
+/**
+ * Collect all binding resourceKeys associated with a node.
+ * Handles three binding ownership patterns:
+ * 1. Process nodes — resourceKey from the definition's model.bindings.resourceKey,
+ *    falling back to the process GUID extracted from the node type
+ * 2. Connector nodes — resourceKey is the connectionId stored in inputs.detail
+ * 3. Input refs — "=bindings.<id>" patterns resolved to resourceKeys
+ */
+export declare function collectNodeBindingResourceKeys(node: NodeInstance, bindings: Array<{
+    id: string;
+    resourceKey: string;
+}>, definitions?: Array<Record<string, unknown>>): Set<string>;
+export declare const addNodeToFlow: (filePath: string, nodeType: string, options?: AddNodeOptions) => Promise<AddNodeResult>;
+export declare const deleteNodeFromFlow: (filePath: string, nodeId: string) => Promise<DeleteNodeResult>;

package/dist/services/node-validators/index.d.ts

@@ -1,6 +1,7 @@
 import type { FlowNodeValidator } from "./types.js";
 export { connectorNodeValidator } from "./connector-validator.js";
 export { expressionPrefixValidator } from "./expression-prefix-validator.js";
+export { ixpNodeValidator } from "./ixp-node-validator.js";
 export { modelSourceValidator } from "./model-source-validator.js";
 export type { FlowNodeValidator, FlowValidatorContext, FlowValidatorNode, ValidationIssue, ValidationIssueSeverity, } from "./types.js";
 /**

package/dist/services/node-validators/ixp-node-validator.d.ts

@@ -0,0 +1,2 @@
+import type { FlowNodeValidator } from "./types.js";
+export declare const ixpNodeValidator: FlowNodeValidator;

package/dist/services/packaging-utils.d.ts

@@ -0,0 +1,107 @@
+import type { IFileSystem } from "@uipath/filesystem";
+import { type EntryPoint, type PackagingBinding, type PackagingNode, type PackagingNodeManifest, type PackagingWorkflowVariables } from "@uipath/flow-schema";
+interface FlowFileNode {
+    id: string;
+    type: string;
+    typeVersion?: string;
+    display?: Record<string, unknown>;
+    inputs?: Record<string, unknown>;
+    outputs?: Record<string, unknown>;
+    model?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+/**
+ * Resolve the inline-agent's projectId UUID from a flow node.
+ *
+ * flow-core 0.2.50 moved the per-instance source UUID from
+ * `node.model.source` to `node.inputs.source`. Older `.flow` files (and
+ * any saved before the migration ran) still carry the legacy
+ * `model.source` shape — `model-source-validator.ts` accepts both, so
+ * the packagers must too. Falls back through the same key set
+ * flow-workbench's `extractInlineAgents` uses.
+ *
+ * Note: `packager/packager-tool-flow/src/flow-tool.ts` keeps an inline
+ * copy of this rule (`readSource` in `generateFlowPackagingArtifacts`).
+ * `flow-tool` already imports `@uipath/packager-tool-flow`, so the
+ * reverse import would create a cycle. If the priority list ever
+ * changes, update both copies — or lift the helper into
+ * `@uipath/flow-schema` (currently an external dep) and delete both.
+ */
+export declare function readInlineAgentSource(node: {
+    inputs?: Record<string, unknown>;
+    model?: Record<string, unknown>;
+}): string | undefined;
+/** Returns true when the node's type is a known inline-agent node type. */
+export declare function isInlineAgentNodeType(type: string | undefined): boolean;
+/** Returns true when the node's type is the conversational agent type. */
+export declare function isConversationalAgentNodeType(type: string | undefined): boolean;
+/**
+ * Convert file-format nodes (flat `inputs`/`display`/`outputs`) to the
+ * `PackagingNode` shape expected by flow-schema packaging helpers — also
+ * flat: `display`, `inputs`, `outputs`, and `model` sit at the top of the
+ * node, matching `inputsMatchBinding` and `getConnectionMetadata` in
+ * `getBindingResources`. We default `typeVersion` here for legacy file-format
+ * nodes that omit it; `toPackagingNodes` from flow-schema is an identity cast
+ * and does NOT remap fields, so we do that here.
+ */
+export declare function fileNodesToPackagingNodes(nodes: FlowFileNode[]): PackagingNode[];
+/** Packaged inline agent with entry point and file metadata. */
+export interface InlineAgentPackage {
+    /** The agent's projectId UUID (directory name). */
+    source: string;
+    /** Entry point for entry-points.json. */
+    entryPoint: EntryPoint;
+    /** The raw agent.json content (for .agent-builder/agent.json). */
+    agentJson: Record<string, unknown>;
+}
+/**
+ * Scan workflow nodes for inline agents, read their agent.json,
+ * and build entry points + metadata for packaging.
+ *
+ * The source UUID may live at `inputs.source` (canonical) or `model.source`
+ * (legacy, pre-flow-core 0.2.50). We honour both — see
+ * {@link readInlineAgentSource}.
+ */
+export declare function packageInlineAgents(fs: IFileSystem, projectDir: string, nodes: Array<{
+    type: string;
+    inputs?: Record<string, unknown>;
+    model?: Record<string, unknown>;
+}>): Promise<InlineAgentPackage[]>;
+/**
+ * Build inline-agent descriptors for a debug session's FpsProperties
+ * injection. Mirrors flow-workbench's `extractInlineAgents` shape:
+ * one entry per agent node with a resolvable source UUID.
+ *
+ * The runtime resolves each entry by `executorInfo.projectId`, so this
+ * walks every agent node — even the ones whose `agent.json` may not be
+ * on disk yet — and returns the descriptor list.
+ *
+ * `entryPointPath` is `<projectId>/agent.json` (no `content/` prefix —
+ * runtime resolves against the deployed package root).
+ */
+export declare function buildInlineAgentDescriptors(nodes: Array<{
+    type: string;
+    display?: Record<string, unknown>;
+    inputs?: Record<string, unknown>;
+    model?: Record<string, unknown>;
+}>): Array<{
+    name: string;
+    agentProjectId: string;
+    isConversational: boolean;
+    entryPointPath: string;
+}>;
+/**
+ * Write all packaging artifacts (operate.json, entry-points.json, bindings_v2.json,
+ * package-descriptor.json) into a directory using @uipath/flow-schema.
+ *
+ * Returns the computed entry points so callers can derive PIMS entry point paths
+ * without calling getEntryPoints again.
+ */
+export declare function writePackagingArtifacts(fs: IFileSystem, projectDir: string, projectId: string, packagingNodes: PackagingNode[], bindings: PackagingBinding[], variables: PackagingWorkflowVariables, bpmnFileName: string, startEventId: string, flowFileName?: string, definitions?: PackagingNodeManifest[]): Promise<EntryPoint[]>;
+/**
+ * Re-read a .flow file and regenerate bindings_v2.json in the same project directory.
+ * Called after `node add` (process nodes), `node delete`, and `node configure` to
+ * keep bindings in sync with the .flow file.
+ */
+export declare function regenerateBindingsFile(fs: IFileSystem, flowFilePath: string): Promise<void>;
+export {};