@uipath/maestro-builder-sdk 5.2.0

package/dist/decompile-cli.d.ts

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

package/dist/decompile-cli.js

@@ -0,0 +1,131 @@
+#!/usr/bin/env node
+/**
+ * decompile-cli — <original>.flow → <Name>.flow.ts (bin `flow-decompile`)
+ *
+ * Usage:
+ *   flow-decompile <original.flow> [-o Name.flow.ts] [--import <specifier>] [--strict]
+ *
+ * The reverse of compile-cli: reads a `.flow` JSON and emits Flow SDK builder
+ * source whose default export re-serializes to the same graph (same node ids,
+ * same logical edges). `--import` sets the module specifier of the emitted
+ * `import { flow, … }` line (default the published package) so the file resolves
+ * wherever you place it. `--strict` turns off best-effort mode, so an
+ * unsupported construct is a hard error instead of a `// TODO` marker.
+ *
+ * Besides the `.flow.ts`, this also emits a per-flow pipeline wrapper
+ * (`<Name>.pipeline.mjs`) that chains decompile → [edit] → compile → merge, so an
+ * agent can run one script for the whole brownfield write-back loop. Pass
+ * `--no-pipeline` to skip it.
+ */
+import { readFileSync, writeFileSync } from 'node:fs';
+import { basename, resolve } from 'node:path';
+import { decompile } from './decompile.js';
+import { resolveFlowRefs } from './ref-resolve.js';
+import { runWhenInvokedDirectly } from './cli-run.js';
+import { PACKAGE_NAME } from './package-name.js';
+function opt(argv, name) {
+    const i = argv.indexOf(name);
+    return i >= 0 ? argv[i + 1] : undefined;
+}
+/** Derive a PascalCase base name from the flow name/id for the default output file. */
+function baseName(flow) {
+    const src = flow.name ?? flow.id ?? 'Flow';
+    const pascal = src
+        .split(/[^A-Za-z0-9]+/)
+        .filter(Boolean)
+        .map((w) => w[0].toUpperCase() + w.slice(1))
+        .join('');
+    return pascal || 'Flow';
+}
+export function run(argv) {
+    if (argv.length === 0 || argv[0] === '-h' || argv[0] === '--help') {
+        console.error('usage: flow-decompile <original.flow> [-o Name.flow.ts] [--import <specifier>] [--strict]');
+        return 2;
+    }
+    const flags = new Set(['-o', '--import']);
+    const pos = argv.find((a, i) => !flags.has(a) && !flags.has(argv[i - 1]) && !a.startsWith('--'));
+    if (!pos) {
+        console.error('flow-decompile: missing <original.flow>');
+        return 2;
+    }
+    // A `.flow` may be SPLIT across sibling files with JSON Reference — resolve
+    // those into one object model before decompiling (design §5; the format's own
+    // read path does the same). A single-file flow walks through untouched.
+    const flow = resolveFlowRefs(JSON.parse(readFileSync(pos, 'utf8')), {
+        baseUri: pos,
+        read: (path) => readFileSync(path, 'utf8'),
+    });
+    const ts = decompile(flow, {
+        importSpecifier: opt(argv, '--import') ?? PACKAGE_NAME,
+        bestEffort: !argv.includes('--strict'),
+        // Findings the source cannot carry on its own (a node no trigger reaches, a
+        // pinned core version this SDK lacks, a file-format version outside the
+        // writable band) go to stderr, where the agent running the brownfield loop
+        // reads them before compile refuses.
+        warn: (message) => console.error(`flow-decompile: warning: ${message}`),
+    });
+    const out = opt(argv, '-o') ?? `${baseName(flow)}.flow.ts`;
+    writeFileSync(out, ts);
+    console.log(`flow-decompile: wrote ${basename(out)}`);
+    if (!argv.includes('--no-pipeline')) {
+        const pipelinePath = out.replace(/\.flow\.ts$|\.ts$/, '') + '.pipeline.mjs';
+        writeFileSync(pipelinePath, pipelineScript(resolve(pos), resolve(out)));
+        console.log(`flow-decompile: wrote ${basename(pipelinePath)}`);
+    }
+    return 0;
+}
+/**
+ * A per-flow wrapper that runs the whole brownfield write-back loop with one
+ * command. First run: decompile the original into `<Name>.flow.ts` and capture a
+ * baseline. You then EDIT `<Name>.flow.ts`. Re-run: it compiles your edits and
+ * merges them back into the original, producing `<Name>.merged.flow`. It shells
+ * out through the public `uip maestro flow` authoring commands. Until a UiPath
+ * CLI carrying those preview commands is installed, it falls back to the SDK's
+ * retained `flow-sdk` bin from this workspace.
+ */
+function pipelineScript(originalPath, tsPath) {
+    const base = tsPath.replace(/\.flow\.ts$|\.ts$/, '');
+    return `#!/usr/bin/env node
+// Generated by flow-decompile — the brownfield read/modify/write pipeline for
+// ${basename(originalPath)}. Run it, edit ${basename(tsPath)}, run it again.
+import { execFileSync, spawnSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+
+const ORIGINAL = ${JSON.stringify(originalPath)};
+const TS       = ${JSON.stringify(tsPath)};
+const BASELINE = ${JSON.stringify(base + '.baseline.flow')};
+const EDITED   = ${JSON.stringify(base + '.edited.flow')};
+const MERGED   = ${JSON.stringify(base + '.merged.flow')};
+
+const uipProbe = spawnSync('uip', ['maestro', 'flow', 'compile', '--help'], { stdio: 'ignore' });
+const frontDoor = !uipProbe.error && uipProbe.status === 0
+  ? { file: 'uip', prefix: ['maestro', 'flow'] }
+  : { file: 'npx', prefix: ['--no-install', 'flow-sdk', 'flow'] };
+const run = (verb, args) =>
+  execFileSync(frontDoor.file, [...frontDoor.prefix, verb, ...args], { stdio: 'inherit' });
+
+// Ensure the decompiled source exists (a fresh clone may have only the .flow).
+if (!existsSync(TS)) run('decompile', [ORIGINAL, '-o', TS, '--no-pipeline']);
+
+if (!existsSync(BASELINE)) {
+  // ── Step 1: capture the baseline = compile of the PRISTINE decompiled code,
+  //    BEFORE any edit. Run this once right after decompiling, then edit. ──
+  run('compile', [TS, '-o', BASELINE, '--no-check']);
+  console.log('\\n>>> Baseline captured. Now EDIT ' + ${JSON.stringify(basename(tsPath))} + ', then re-run this script to compile + merge.');
+} else {
+  // ── Step 2: compile your edits, then merge them back into the original. ──
+  run('compile', [TS, '-o', EDITED, '--no-check']);
+
+  // ── DIFF GATE (seam) ──────────────────────────────────────────────────────
+  // A future step can diff ORIGINAL vs the about-to-be-written MERGED here and
+  // ask for confirmation before the write. Left as a no-op for now.
+  // ---------------------------------------------------------------------------
+
+  const args = [ORIGINAL, EDITED, '-o', MERGED];
+  if (existsSync(BASELINE)) args.push('--baseline', BASELINE);
+  run('merge', args);
+  console.log('\\n>>> Wrote ' + ${JSON.stringify(base + '.merged.flow')});
+}
+`;
+}
+runWhenInvokedDirectly(import.meta.url, 'flow-decompile', run);

package/dist/decompile.d.ts

@@ -0,0 +1,138 @@
+/**
+ * decompile — the reverse of `serialize.ts`: turn a real UiPath `.flow` JSON
+ * back into Flow SDK builder source (`.flow.ts`) that, when re-compiled,
+ * serializes to the **same** graph (same node ids, same logical edges).
+ *
+ * Unlike the case decompiler (`case/decompile.ts`), a flow is a directed GRAPH
+ * (`nodes[]` + `edges[]` with `sourcePort`/`targetPort`), not a hierarchy, and
+ * the builder is structured (`.branch()` / `.switch()` / `.loop()` /
+ * `.parallel()` / `.onError()` / `.return()`). Decompiling therefore means
+ * reconstructing structured control flow from the graph — the inverse of
+ * serialize's `emit()` walker. This module is built in layers:
+ *
+ *   - Phase 1 (here): the linear core — header, variables, trigger, and a
+ *     straight-line chain of action steps ending in `.return()` / `.terminate()`.
+ *   - Phase 2: the full node reverse-map (http / transform / connectors / hitl /
+ *     agents / queue / …) and connector reverse-lookup.
+ *   - Phase 3: control-flow reconstruction (branch / switch / loop / parallel /
+ *     onError / stepToRef / subflow) via graph analysis.
+ *
+ * The linchpin is **node-id stability**: serialize derives each node id from the
+ * author's step NAME (`claimId`: `[^A-Za-z0-9_]→_`, then de-dup `base`/`base2`/…),
+ * so if we name every step with its original node id, serialize reproduces
+ * byte-identical ids. A happy consequence: serialize's `renameRefs`
+ * (`$vars.<stepName>`→`$vars.<nodeId>`) becomes the identity, so expression
+ * references need no un-renaming.
+ *
+ * The round-trip is **semantically** lossless, not byte-for-byte: layout,
+ * display labels on plain steps, and formatting are not preserved (layout is
+ * re-attached by `flow-merge`; see `docs/FLOW_PARITY.md`).
+ */
+import { type FlowGlobalDeclaration } from './flow-variables.js';
+/** An expression envelope as written by `migrate.ts` (`{type,expression,fieldType}`). */
+interface WrappedSource {
+    type: string;
+    expression: string;
+    fieldType?: string;
+}
+/** A node output descriptor (`node.outputs[name]`). */
+interface OutputDesc {
+    type?: string;
+    description?: string;
+    source?: string | WrappedSource;
+    var?: string;
+}
+/** A canvas point, as persisted in an edge route. */
+interface UiPoint {
+    x: number;
+    y: number;
+    id?: string;
+}
+/** One node's designer layout, as persisted on `node.ui` or in `layout.nodes`. */
+interface NodeUi {
+    position?: {
+        x: number;
+        y: number;
+    };
+    size?: {
+        width: number;
+        height: number;
+    };
+    collapsed?: boolean;
+}
+/** One edge's route, as persisted on `edge.ui` or in `layout.edges`. */
+interface EdgeUi {
+    waypoints?: UiPoint[];
+    routedWaypoints?: UiPoint[];
+}
+interface FlowNode {
+    id: string;
+    type: string;
+    typeVersion?: string;
+    parentId?: string;
+    inputs?: Record<string, unknown>;
+    outputs?: Record<string, OutputDesc>;
+    display?: {
+        label?: string;
+        icon?: string;
+    };
+    model?: unknown;
+    ui?: NodeUi;
+}
+interface FlowEdge {
+    id?: string;
+    sourceNodeId: string;
+    sourcePort: string;
+    targetNodeId: string;
+    targetPort: string;
+    ui?: EdgeUi;
+}
+type Global = FlowGlobalDeclaration;
+interface VariableUpdate {
+    variableId: string;
+    expression: string | WrappedSource;
+}
+interface FlowVariables {
+    globals?: Global[];
+    nodes?: unknown[];
+    variableUpdates?: Record<string, VariableUpdate[]>;
+    [name: string]: unknown;
+}
+interface FlowFile {
+    id?: string;
+    name?: string;
+    version?: string;
+    definitions?: Array<{
+        nodeType?: string;
+        version?: string;
+    }>;
+    nodes?: FlowNode[];
+    edges?: FlowEdge[];
+    variables?: FlowVariables;
+    subflows?: Record<string, FlowFile>;
+    layout?: {
+        nodes?: Record<string, NodeUi>;
+        edges?: Record<string, EdgeUi>;
+    };
+}
+export interface DecompileOptions {
+    /** Module specifier for the `import { flow, … } from …` line. Default `./flow-sdk.js`. */
+    importSpecifier?: string;
+    /**
+     * When true (the default), a node type the reverse-map does not yet handle is
+     * emitted as a `mock()` placeholder carrying a `// TODO` marker rather than
+     * throwing — so a validating flow always produces usable code. Set false to
+     * make an unsupported construct a hard error instead.
+     */
+    bestEffort?: boolean;
+    /**
+     * Receives each non-fatal finding about the file, one message per finding:
+     * a node no trigger reaches (the builder cannot express a detached node, so
+     * the source omits it — strict mode throws instead), and a core
+     * `(type, typeVersion)` pair this SDK does not bundle (the source keeps it;
+     * `compile` will refuse it). The CLI prints these on stderr.
+     */
+    warn?: (message: string) => void;
+}
+export declare function decompile(flow: FlowFile, options?: DecompileOptions): string;
+export {};