@uipath/maestro-builder-sdk 5.2.0 → 5.3.0

package/dist/case/decompile.d.ts

@@ -182,6 +182,50 @@ export interface CaseDecompileResult {
     source: string;
     diagnostics: CaseDecompileDiagnostic[];
 }
+type Preservation = {
+    topLevel?: Record<string, unknown>;
+    metadata?: Record<string, unknown>;
+    caseAppConfigFields?: {
+        fields?: Record<string, unknown>;
+        sections?: Array<{
+            id: string;
+            fields: Record<string, unknown>;
+        }>;
+    };
+    nodes?: Array<{
+        index: number;
+        node: Record<string, unknown>;
+    }>;
+    nodeOrder?: string[];
+    edges?: unknown[];
+    layout?: unknown;
+    omitLayout?: boolean;
+    variableFields?: Partial<Record<'inputs' | 'outputs' | 'inputOutputs', Record<string, Record<string, unknown>>>>;
+    legacyVariableDefaults?: Partial<Record<'inputs' | 'outputs' | 'inputOutputs', Record<string, unknown>>>;
+    variableOrder?: Partial<Record<'inputs' | 'outputs' | 'inputOutputs', string[]>>;
+    taskFields?: Array<{
+        stage: string;
+        lane: number;
+        task: string;
+        fields: Record<string, unknown>;
+    }>;
+    triggerDataFields?: Array<Record<string, unknown>>;
+    omitStagePositions?: string[];
+    omitTaskElementIds?: Array<{
+        stage: string;
+        lane: number;
+        task: string;
+    }>;
+    identities?: unknown;
+};
+/**
+ * Everything the ORIGINAL document owns and the typed builder does not model —
+ * ids, layout, platform metadata, annotation nodes, node order, designer
+ * variable columns. Exported because `mergeCase` needs the same extraction that
+ * `decompile` embeds in a `preserveCaseJson(...)` payload, only read from the
+ * original file at merge time instead.
+ */
+export declare function collectPreservation(plan: CasePlan): Preservation | undefined;
 export declare function decompileWithDiagnostics(plan: CasePlan, options?: DecompileOptions): CaseDecompileResult;
 export declare function decompile(plan: CasePlan, options?: DecompileOptions): string;
 export {};

package/dist/case/decompile.js

@@ -899,6 +899,45 @@ function slaIdentity(sla) {
         escalations: (sla.escalationRule ?? []).map((entry) => ({ ...(entry.id ? { id: entry.id } : {}) })),
     };
 }
+/**
+ * Drop preservation entries the serializer reproduces on its own, so a payload
+ * that says nothing is not emitted at all.
+ *
+ * Only PROVABLE redundancies, each one a fact about the serializer rather than a
+ * guess about the document:
+ *
+ *  - `identities.id` — but ONLY when `slugId` writes that exact id inline as
+ *    `casePlan("…")`. It does so for a canonical `case-[A-Za-z0-9]{10}`; anything
+ *    else it SLUGIFIES, and then the identity entry is the only thing restoring
+ *    the document's real id. `probe--wait-rule` (`case-WaitRuleMigrationProbe`)
+ *    is exactly that, and it is why this is a comparison rather than a delete.
+ *  - `identities.triggers` when it is exactly `[{ id: "trigger_1" }]` — the
+ *    serializer hardcodes `i === 0 ? 'trigger_1'`, so the first trigger already
+ *    has that id.
+ *  - empty collections — there is nothing to align.
+ *  - `nodeOrder` with fewer than two ids — ordering one node is identity.
+ *
+ * Everything else stays. A designer document orders stages before its trigger,
+ * carries ids no label seeding reproduces, and needs every one of them.
+ */
+function prunePreservation(preservation, plan) {
+    const identities = preservation.identities;
+    if (identities) {
+        if (identities.id === slugId(plan))
+            delete identities.id;
+        if (identities.triggers?.length === 1 && identities.triggers[0]?.id === 'trigger_1')
+            delete identities.triggers;
+        for (const key of ['triggers', 'stages', 'caseExitRules', 'slaRules'])
+            if (Array.isArray(identities[key]) && identities[key].length === 0)
+                delete identities[key];
+        if (identities.variables && Object.values(identities.variables).every((rows) => !Array.isArray(rows) || rows.length === 0))
+            delete identities.variables;
+        if (Object.keys(identities).length === 0)
+            delete preservation.identities;
+    }
+    if ((preservation.nodeOrder?.length ?? 0) < 2)
+        delete preservation.nodeOrder;
+}
 function identityPreservation(plan) {
     return {
         ...(plan.id ? { id: plan.id } : {}),
@@ -925,7 +964,14 @@ function identityPreservation(plan) {
         ])),
     };
 }
-function collectPreservation(plan) {
+/**
+ * Everything the ORIGINAL document owns and the typed builder does not model —
+ * ids, layout, platform metadata, annotation nodes, node order, designer
+ * variable columns. Exported because `mergeCase` needs the same extraction that
+ * `decompile` embeds in a `preserveCaseJson(...)` payload, only read from the
+ * original file at merge time instead.
+ */
+export function collectPreservation(plan) {
     const preservation = { identities: identityPreservation(plan) };
     const topKnown = new Set(['id', 'name', 'description', 'version', 'bindings', 'variables', 'metadata', 'nodes', 'edges', 'layout']);
     const topLevel = Object.fromEntries(Object.entries(plan).filter(([name]) => !topKnown.has(name)));
@@ -1078,6 +1124,7 @@ function collectPreservation(plan) {
         preservation.legacyVariableDefaults = legacyVariableDefaults;
     if (Object.keys(variableOrder).length)
         preservation.variableOrder = variableOrder;
+    prunePreservation(preservation, plan);
     return Object.keys(preservation).length ? preservation : undefined;
 }
 function slugId(plan) {

package/dist/case/format-profile.js

@@ -60,6 +60,17 @@ export const CASE_SCHEMA_VERSIONS = {
     latestKnown: CASE_FORMAT_PROFILE.validationCeiling.formatVersion,
     migration: 'Case documents migrate FORWARD on read, through the platform\'s feature-flag-gated chain; there is no '
         + '`uip maestro case migrate`, and no path that writes an older grammar.',
+    // Case has no `merge`, so it cannot repeat Flow's advice. What it can say is
+    // which direction the rewrite moves and whether that is a problem, rather than
+    // sending the reader after a command that does not exist — which is what the
+    // shared wording did, and what an eval agent then worked around by copying the
+    // recompiled file over the original.
+    preserveAdvice: (_declared, writes, direction) => direction === 'newer'
+        ? `Keep the original file: this build's ceiling is ${writes}, so recompiling over it is the one `
+            + 'direction the platform will not undo for you.'
+        : `Recompiling rewrites the whole file at ${writes}. That is the direction the platform's on-read `
+            + 'chain takes it anyway, and the round-trip is asserted converter-equivalent over the migration '
+            + 'corpus, so the rewrite is normally safe to keep.',
     writable: [
         {
             version: CASE_FORMAT_PROFILE.writeVersion,

package/dist/case/merge-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/case/merge-cli.js

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+/**
+ * case/merge-cli — merge an edited case back into the original `caseplan.json`
+ * (bin `case-merge`, surfaced as `uip maestro case merge`).
+ *
+ * Usage:
+ *   case-merge <original.json> <edited.json> [-o merged.json]
+ *
+ * `edited.json` is compile(decompile(original)) after your edits. See merge.ts
+ * for what each side decides and why the join is by label rather than by id.
+ */
+import { readFileSync, writeFileSync } from 'node:fs';
+import { basename } from 'node:path';
+import { mergeCase } from './merge.js';
+import { runWhenInvokedDirectly } from '../cli-run.js';
+function opt(argv, name) {
+    const i = argv.indexOf(name);
+    return i >= 0 ? argv[i + 1] : undefined;
+}
+export function run(argv) {
+    if (argv.length === 0 || argv[0] === '-h' || argv[0] === '--help') {
+        console.error('usage: case-merge <original.json> <edited.json> [-o merged.json]');
+        return 2;
+    }
+    const flags = new Set(['-o']);
+    const positionals = argv.filter((a, i) => !flags.has(a) && !flags.has(argv[i - 1]) && !a.startsWith('-'));
+    const [originalPath, editedPath] = positionals;
+    if (!originalPath || !editedPath) {
+        console.error('case-merge: need <original.json> and <edited.json>');
+        return 2;
+    }
+    const original = JSON.parse(readFileSync(originalPath, 'utf8'));
+    const edited = JSON.parse(readFileSync(editedPath, 'utf8'));
+    const merged = mergeCase(original, edited, {
+        warn: (message) => console.error(`case-merge: warning: ${message}`),
+    });
+    const out = opt(argv, '-o') ?? 'merged.caseplan.json';
+    writeFileSync(out, JSON.stringify(merged, null, 2) + '\n');
+    const stages = (merged.nodes ?? [])
+        .filter((node) => String(node.type ?? '').endsWith('Stage')).length;
+    console.log(`case-merge: wrote ${basename(out)} (${stages} stage(s))`);
+    return 0;
+}
+runWhenInvokedDirectly(import.meta.url, 'case-merge', run);

package/dist/case/merge.d.ts

@@ -0,0 +1,18 @@
+/** A caseplan-shaped document. Deliberately loose: merge moves fields, it does not type them. */
+export type CaseDocument = Record<string, unknown>;
+export interface CaseMergeOptions {
+    /**
+     * Called once per finding. Today the only finding is a construct the original
+     * carried an identity for that the edited document no longer has — a rename or
+     * a delete, which are indistinguishable here and which silently drop the
+     * original's ids for that construct.
+     */
+    warn?: (message: string) => void;
+}
+/**
+ * Merge an edited case plan onto its original.
+ *
+ * The edited document supplies the graph; the original supplies identity and
+ * everything the typed builder does not model. Neither input is mutated.
+ */
+export declare function mergeCase(original: CaseDocument, edited: CaseDocument, options?: CaseMergeOptions): CaseDocument;

package/dist/case/merge.js

@@ -0,0 +1,112 @@
+/**
+ * merge — write a decompiled-then-edited case back into the ORIGINAL
+ * `caseplan.json`, keeping everything the original owns and the author does not.
+ *
+ * The brownfield pipeline mirrors Flow's:
+ *
+ *   original.json --decompile--> Case.case.ts --(edit)--> --compile--> edited.json
+ *   mergeCase(original, edited) --> merged.json
+ *
+ * ## Why Case cannot merge the way Flow does
+ *
+ * `mergeFlow` re-attaches by NODE ID, and says so: "node ids are stable by
+ * construction (decompile names every step by its node id), which is what lets
+ * every re-attach key on id." Flow ids ARE the authored step names, so a
+ * round-trip reproduces them for free.
+ *
+ * Case ids are not. `case/ids.ts` derives `Stage_` + base62(fnv1a64('stage:<label>'))
+ * because the schema demands an opaque `prefixedId`, and a document written by
+ * the designer carries ids from some other producer entirely — `Stage_Kp3mRx`
+ * is not derivable from "Review" by anyone but its author. So an edited case
+ * compiled on its own carries GENERATED ids, and id is exactly the key this
+ * merge cannot use.
+ *
+ * What it uses instead is what the preservation channel already uses: stage
+ * LABEL, task displayName, lane and position. That is not a second mechanism —
+ * it is the same one, read from the original file at merge time rather than
+ * from a `preserveCaseJson(...)` payload baked into the source.
+ *
+ * ## What each side decides
+ *
+ *   edited    the graph: stages, tasks, conditions, rules, variables, bindings
+ *   original  identity and chrome: every id, layout, platform-owned metadata,
+ *             annotation nodes, node order, opaque edges, designer variable columns
+ *
+ * A construct the edit ADDED has no counterpart in the original, so it keeps the
+ * ids the serializer generated. A construct the edit DELETED simply has nothing
+ * to receive its preserved identity, and is dropped with it.
+ *
+ * ## Why this exists next to `preserveCaseJson`
+ *
+ * Both answer the same question. The payload answers it at compile time from a
+ * literal embedded in the authored file; this answers it at merge time from the
+ * original document. The payload's failure mode is that it can go stale or be
+ * hand-edited — flow-builder-sdk#719 was a reference left pointing at an id the
+ * payload had renamed away, and the eval agent that met it reached for
+ * `perl -0pi -e` against a minified blob. Identity read fresh from the original
+ * cannot drift from it.
+ */
+import { collectPreservation } from './decompile.js';
+import { applyPreservation } from './serialize.js';
+function clone(value) {
+    return JSON.parse(JSON.stringify(value));
+}
+/** Stage labels in a document, in order. */
+function stageLabels(document) {
+    return (document.nodes ?? [])
+        .filter((node) => String(node.type ?? '').endsWith('Stage'))
+        .map((node) => String(node.data?.label ?? ''));
+}
+/** Task display names in a document, by stage label. */
+function taskNames(document) {
+    const out = new Map();
+    for (const node of (document.nodes ?? [])) {
+        if (!String(node.type ?? '').endsWith('Stage'))
+            continue;
+        const names = new Set();
+        for (const lane of (node.data?.tasks ?? []))
+            for (const task of lane)
+                names.add(String(task.displayName ?? ''));
+        out.set(String(node.data?.label ?? ''), names);
+    }
+    return out;
+}
+/**
+ * Report identities the merge could not place, so a rename does not silently
+ * mint a new id for a construct the original already had one for.
+ */
+function warnOrphanedIdentities(preservation, edited, warn) {
+    const labels = new Set(stageLabels(edited));
+    const tasks = taskNames(edited);
+    for (const stage of preservation.identities?.stages ?? []) {
+        if (!labels.has(stage.label)) {
+            warn(`stage "${stage.label}" is in the original but not in the edited case, so its ids are dropped. `
+                + `If this was a RENAME rather than a delete, the renamed stage gets a new id and every reference `
+                + `to the old one goes with it — rename in the original first, or keep the label.`);
+            continue;
+        }
+        const present = tasks.get(stage.label) ?? new Set();
+        for (const lane of stage.tasks ?? [])
+            for (const task of lane)
+                if (!present.has(task.name))
+                    warn(`task "${task.name}" in stage "${stage.label}" is in the original but not in the edited case, `
+                        + `so its ids are dropped. A rename reads the same as a delete here.`);
+    }
+}
+/**
+ * Merge an edited case plan onto its original.
+ *
+ * The edited document supplies the graph; the original supplies identity and
+ * everything the typed builder does not model. Neither input is mutated.
+ */
+export function mergeCase(original, edited, options = {}) {
+    const preservation = collectPreservation(original);
+    if (!preservation)
+        return clone(edited);
+    if (options.warn)
+        warnOrphanedIdentities(preservation, edited, options.warn);
+    // `applyPreservation` is what `compile` runs with the payload a source
+    // carries. Handing it the ORIGINAL's payload and the EDITED graph is the whole
+    // merge: same operation, different provenance.
+    return applyPreservation(clone(edited), preservation, { overwrite: true });
+}

package/dist/case/serialize.d.ts

@@ -1,5 +1,6 @@
 import { Library } from '../core/library.js';
 import { Bindings } from '../core/bindings.js';
+import { type CaseJsonPreservation } from './preserve.js';
 import type { BuiltCase } from './case-sdk.js';
 /** Optional wiring for connector tasks — the library that resolves a connector
  * op, and the bindings that map its symbolic connection/folder to resources. */
@@ -8,3 +9,25 @@ export interface CaseSerializeOpts {
     bindings?: Bindings;
 }
 export declare function serialize(built: BuiltCase, opts?: CaseSerializeOpts): Record<string, unknown>;
+/** How `applyPreservation` treats a field the target already has. */
+export interface ApplyPreservationOptions {
+    /**
+     * Let a preserved field overwrite one already present on the target.
+     *
+     * `compile` leaves this off: it applies the payload to a document the
+     * serializer just built, so a field already there means the channel is
+     * claiming something the typed builder owns — a contract violation worth
+     * refusing loudly.
+     *
+     * `mergeCase` turns it on, because its target has ALREADY been compiled. The
+     * designer-owned fields are present by construction there, and the whole point
+     * of the merge is that the original wins on exactly those.
+     */
+    overwrite?: boolean;
+}
+/**
+ * Stamp a preservation payload onto a caseplan-shaped document. Exported for
+ * `mergeCase`, which applies the ORIGINAL's payload to the EDITED graph — the
+ * same operation compile performs with the payload the source carries.
+ */
+export declare function applyPreservation(result: Record<string, unknown>, preservation: CaseJsonPreservation | undefined, options?: ApplyPreservationOptions): Record<string, unknown>;

package/dist/case/serialize.js

@@ -294,7 +294,12 @@ function applyAuthorLayout(result, authored) {
         result.layout = layout;
     return result;
 }
-function applyPreservation(result, preservation) {
+/**
+ * Stamp a preservation payload onto a caseplan-shaped document. Exported for
+ * `mergeCase`, which applies the ORIGINAL's payload to the EDITED graph — the
+ * same operation compile performs with the payload the source carries.
+ */
+export function applyPreservation(result, preservation, options = {}) {
     if (!preservation)
         return result;
     const errors = caseJsonPreservationErrors(preservation);
@@ -306,7 +311,7 @@ function applyPreservation(result, preservation) {
     const caseAppConfig = result.metadata.caseAppConfig;
     if (caseAppConfig && preservation.caseAppConfigFields) {
         for (const [field, value] of Object.entries(preservation.caseAppConfigFields.fields ?? {})) {
-            if (Object.prototype.hasOwnProperty.call(caseAppConfig, field))
+            if (!options.overwrite && Object.prototype.hasOwnProperty.call(caseAppConfig, field))
                 throw new Error(`preserved caseAppConfig field "${field}" collides with serializer-owned output.`);
             caseAppConfig[field] = value;
         }
@@ -315,7 +320,7 @@ function applyPreservation(result, preservation) {
             if (!section)
                 continue;
             for (const [field, value] of Object.entries(entry.fields)) {
-                if (Object.prototype.hasOwnProperty.call(section, field))
+                if (!options.overwrite && Object.prototype.hasOwnProperty.call(section, field))
                     throw new Error(`preserved Case App section "${entry.id}" field "${field}" collides with serializer-owned output.`);
                 section[field] = value;
             }
@@ -333,10 +338,12 @@ function applyPreservation(result, preservation) {
         const rows = variables[lane] ?? [];
         for (const [name, fields] of Object.entries(byName ?? {})) {
             const row = rows.find((candidate) => candidate.name === name);
+            if (!row && options.overwrite)
+                continue;
             if (!row)
                 throw new Error(`preserved variable "${name}" was not regenerated in variables.${lane}.`);
             for (const [field, value] of Object.entries(fields)) {
-                if (Object.prototype.hasOwnProperty.call(row, field))
+                if (!options.overwrite && Object.prototype.hasOwnProperty.call(row, field))
                     throw new Error(`preserved variable "${name}" field "${field}" collides with serializer-owned output.`);
                 row[field] = value;
             }
@@ -346,11 +353,22 @@ function applyPreservation(result, preservation) {
         const rows = variables[lane] ?? [];
         for (const [name, value] of Object.entries(byName ?? {})) {
             const row = rows.find((candidate) => candidate.name === name);
+            if (!row && options.overwrite)
+                continue;
             if (!row)
                 throw new Error(`legacy variable default "${name}" was not regenerated in variables.${lane}.`);
             const encoded = JSON.stringify(value);
-            if (row.default !== encoded)
+            // The legacy row exists to carry the NON-STRING spelling of a value the
+            // serializer now writes as a string, so it is only applicable while the two
+            // still agree. Under merge a disagreement means the author edited the
+            // default, which makes the preserved spelling stale: keep what the author
+            // wrote and drop the legacy row. Under compile it means the payload
+            // contradicts the source, which is worth refusing.
+            if (row.default !== encoded) {
+                if (options.overwrite)
+                    continue;
                 throw new Error(`legacy variable default "${name}" does not match the serializer-owned default.`);
+            }
             row.default = value;
         }
     }
@@ -376,7 +394,8 @@ function applyPreservation(result, preservation) {
                 // channel quietly overwrite typed output.
                 if (task[field] === value)
                     continue;
-                throw new Error(`preserved task "${entry.stage}/${entry.task}" field "${field}" collides with serializer-owned output.`);
+                if (!options.overwrite)
+                    throw new Error(`preserved task "${entry.stage}/${entry.task}" field "${field}" collides with serializer-owned output.`);
             }
             task[field] = value;
         }
@@ -397,6 +416,8 @@ function applyPreservation(result, preservation) {
         .filter((node) => node.type === 'case-management:Trigger' || node.type === 'uipath.case.trigger');
     for (const [index, fields] of (preservation.triggerDataFields ?? []).entries()) {
         const trigger = triggerNodes[index];
+        if (!trigger && options.overwrite)
+            continue;
         if (!trigger)
             throw new Error(`trigger ${index + 1} was not regenerated for preserved data fields.`);
         Object.assign(trigger.data, fields);
@@ -485,9 +506,21 @@ function applyPreservedIdentities(result, preservation) {
             replaced = replaced.replaceAll(current, wanted);
         return replaced;
     };
+    // Every field that carries an id GENERATED by this serialize pass has to be
+    // rewritten when preservation renames the node that id belongs to. Missing one
+    // leaves a reference pointing at an id nothing has any more.
+    //
+    // `exitToStageId` was missing, and it only bites when the preserved id DIFFERS
+    // from the generated one — i.e. on a document this SDK did not write. Round-trip
+    // an SDK-authored case and the two agree, so the rename is a no-op and nothing
+    // shows. Take a DESIGNER document, whose stage ids are not label-seeded, insert
+    // a stage and recompile — the brownfield loop the skill documents — and
+    // `exitToStage: "Decision"` resolves to the generated id, the Decision node is
+    // then renamed to its designer id, and the exit points at nothing. Silently:
+    // `case check` says OK and `uip maestro case validate` reports nothing about it.
     const referenceFields = new Set([
-        'elementId', 'selectedStageId', 'selectedStageIds', 'selectedTasksIds', 'slaId', 'escalationId',
-        'originalVar', 'var', 'source', 'target',
+        'elementId', 'exitToStageId', 'selectedStageId', 'selectedStageIds', 'selectedTasksIds',
+        'slaId', 'escalationId', 'originalVar', 'var', 'source', 'target',
     ]);
     const preservedOutputSources = [];
     for (const node of nodes) {

package/dist/check.js

@@ -193,6 +193,36 @@ function checkFlow(built, ancestors, opts = {}) {
                     });
                 }
             }
+            // The mirror of HITL_OUTCOME_PORTS_OFF below: `completed` on a human task
+            // that HAS opted into per-outcome exits.
+            //
+            // Turning on `outcomePorts` (or `exposeError`, which implies it) moves the
+            // step to the node's 1.1/1.2 definition, and those declare ONE source
+            // handle — `outcome-{item.id}`, repeated over `inputs.schema.outcomes`.
+            // There is no `completed` handle to leave from, so this edge is refused by
+            // the product: `flow validate` answers "Edge references undeclared source
+            // handle \"completed\" on node \"<step>\"" (measured). Without this rule
+            // `check` was silent, `compile` emitted it, and the author found out from
+            // validate — or from a consumer that inspects ports.
+            if ((s.kind === 'stepToList' || s.kind === 'stepToRef') && s.port === 'completed') {
+                const prevSpec = prevAction?.spec;
+                const isHitl = !!prevSpec && 'kind' in prevSpec && prevSpec.kind === 'hitl';
+                const routed = isHitl
+                    && (prevSpec.inputs?.outcomePorts === true || prevSpec.inputs?.exposeError === true);
+                if (routed) {
+                    const first = prevSpec.inputs.outcomes?.[0];
+                    const firstId = outcomeSlug(typeof first === 'string' ? first : first?.name, 0);
+                    diags.push({
+                        level: 'error', code: 'HITL_COMPLETED_PORT_GONE', step: prevAction?.name,
+                        message: `Port "completed" does not exist on human task "${prevAction?.name}". `
+                            + `${prevSpec.inputs?.exposeError === true ? 'exposeError' : 'outcomePorts'} selects the node's `
+                            + `${prevSpec.inputs?.exposeError === true ? '1.2' : '1.1'} definition, whose only source handle is `
+                            + `"outcome-<id>" repeated over the outcomes — the 1.0 definition's single 'completed' exit is not `
+                            + `part of it. The FIRST outcome ("outcome-${firstId}") is what continues the main path.`,
+                        suggestion: `route the outcomes (.stepToList('outcome-${firstId}', …)), or drop outcomePorts to keep the 'completed' exit`,
+                    });
+                }
+            }
             if ((s.kind === 'stepToList' || s.kind === 'stepToRef') && s.port.startsWith('outcome-')) {
                 const want = s.port.slice('outcome-'.length);
                 const prevSpec = prevAction?.spec;

package/dist/cli/commands/case.js

@@ -1,6 +1,6 @@
 import { addValue, inferCheckMode, invoke, loadTool } from '../common.js';
 export function registerCaseCommands(program) {
-    const family = program.command('case').description('Build and check Case artifacts.');
+    const family = program.command('case').description('Build, check, and merge Case artifacts.');
     family.command('compile')
         .description('Compile authored TypeScript to caseplan.json.')
         .argument('<source>', 'a .case.ts path or bare name')
@@ -57,4 +57,14 @@ export function registerCaseCommands(program) {
             argv.push('--no-pipeline');
         await invoke('case decompile', () => loadTool(import.meta.url, '../../case/decompile-cli.js'), argv);
     });
+    family.command('merge')
+        .description('Merge an edited case plan with its original caseplan.json.')
+        .argument('<original>', 'original caseplan.json path')
+        .argument('<edited>', 'edited caseplan.json path')
+        .option('-o, --output <file>', 'merged output path')
+        .action(async (original, edited, options) => {
+        const argv = [original, edited];
+        addValue(argv, '-o', options.output);
+        await invoke('case merge', () => loadTool(import.meta.url, '../../case/merge-cli.js'), argv);
+    });
 }

package/dist/format-profile.js

@@ -55,6 +55,8 @@ export const FLOW_SCHEMA_VERSIONS = {
     latestKnown: '1.10',
     migration: 'Moving a document between versions is `uip maestro flow migrate`\'s job — it owns the hops, '
         + 'including data repairs this SDK cannot reproduce from the source alone.',
+    preserveAdvice: () => 'Until then, merge the recompiled graph back into the ORIGINAL file with `uip maestro flow merge`, '
+        + 'which keeps its own declared version.',
     writable: [
         {
             version: '1.6',

package/dist/schema-version.d.ts

@@ -91,6 +91,16 @@ export interface SchemaVersionPolicy {
      * refusal that names the wrong mechanism is worse than one that names none.
      */
     migration: string;
+    /**
+     * What to do when a document declares a version this build cannot write, for
+     * the `// TODO:` decompile leaves behind. Family-specific for the same reason
+     * {@link migration} is: the honest answer names a command the reader actually
+     * has. Flow can be told to merge the recompiled graph back into the original,
+     * because `uip maestro flow merge` exists; Case cannot, because it has no
+     * merge. Omitted, no instruction is offered at all, which beats naming one
+     * that does not exist.
+     */
+    preserveAdvice?: (declared: string, writes: string, direction: 'older' | 'newer') => string;
     /**
      * The builder method that declares it, WITHOUT parentheses (`.schemaVersion`)
      * — every message appends its own argument list, so a value carrying `()`

package/dist/schema-version.js

@@ -138,11 +138,21 @@ export function preserveSchemaVersion(policy, declared) {
     if (isWritableSchemaVersion(policy, version)) {
         return { call: `${policy.method}(${JSON.stringify(version)})` };
     }
-    const writes = policy.default ?? writableSchemaVersions(policy)[0] ?? 'nothing';
+    const writes = String(policy.default ?? writableSchemaVersions(policy)[0] ?? 'nothing');
+    // Which way the rewrite moves matters, and the message used to flatten it. A
+    // document OLDER than the write version is being carried forward, which the
+    // platform would do on read anyway; one NEWER is being pushed BACK below what
+    // the platform handed you, and that is where a construct this build does not
+    // know can be dropped.
+    const direction = isSchemaVersionSyntax(version) && isSchemaVersionSyntax(writes)
+        && compareSchemaVersions(version, writes) > 0 ? 'newer' : 'older';
+    const advice = policy.preserveAdvice?.(version, writes, direction);
     return {
         problem: `the file declares ${policy.family} schema version ${JSON.stringify(version)}, which this SDK build cannot write, `
-            + `so this source does not re-declare it and recompiling writes ${JSON.stringify(String(writes))} instead. `
-            + `${policy.migration} Until then, merge the recompiled graph back into the ORIGINAL file, which keeps its own `
-            + `declared version.`,
+            + `so this source does not re-declare it and recompiling writes ${JSON.stringify(writes)} instead — `
+            + `${direction === 'newer'
+                ? 'a DOWNGRADE below the version the platform gave you, which can drop constructs this build does not know'
+                : 'carrying the document forward'}. `
+            + `${policy.migration}${advice ? ` ${advice}` : ''}`,
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uipath/maestro-builder-sdk",
-  "version": "5.2.0",
+  "version": "5.3.0",
   "description": "Build UiPath Flow, Case, and BPMN artifacts by writing TypeScript.",
   "license": "MIT",
   "homepage": "https://docs.uipath.com/maestro",
@@ -12,11 +12,6 @@
     "orchestration",
     "case-management"
   ],
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/UiPath/flow-builder-sdk.git",
-    "directory": "typescript/sdk"
-  },
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -53,6 +48,7 @@
     "case-compile": "./dist/case/compile-cli.js",
     "case-check": "./dist/case/check-cli.js",
     "case-decompile": "./dist/case/decompile-cli.js",
+    "case-merge": "./dist/case/merge-cli.js",
     "bpmn-compile": "./dist/bpmn/compile-cli.js",
     "bpmn-check": "./dist/bpmn/check-cli.js",
     "bpmn-decompile": "./dist/bpmn/decompile-cli.js",
@@ -67,6 +63,20 @@
   "engines": {
     "node": ">=22.6"
   },
+  "scripts": {
+    "build": "tsc && tsc -p cli/tsconfig.json && cp src/core-definitions.json dist/core-definitions.json && cp src/ixp-definition.json dist/ixp-definition.json && cp src/bpmn/uipath-moddle.v1.json dist/bpmn/uipath-moddle.v1.json && cp src/bpmn/registry-types.json dist/bpmn/registry-types.json && node scripts/copy-registry-generators.mjs && node scripts/extract-api-model.mjs --check && node scripts/gen-api-reference.mjs --check && node scripts/api-doc-coverage.mjs --check && node scripts/check-api-docs.mjs",
+    "check:package": "node scripts/check-package-contents.mjs",
+    "generate:api": "node scripts/extract-api-model.mjs && node scripts/gen-api-reference.mjs",
+    "docs:check": "node scripts/check-api-docs.mjs",
+    "coverage:flow": "node scripts/audit-flow-coverage.mjs",
+    "coverage:case": "node scripts/audit-case-coverage.mjs",
+    "docs:coverage": "node scripts/api-doc-coverage.mjs",
+    "docs:coverage:accept": "node scripts/api-doc-coverage.mjs --write",
+    "prepack": "npm run build",
+    "check:md-examples": "node scripts/check-md-examples.mjs",
+    "sync:definitions": "node scripts/sync-core-definitions.mjs",
+    "check:definitions": "node scripts/sync-core-definitions.mjs --check"
+  },
   "dependencies": {
     "bpmn-auto-layout": "^1.3.0",
     "bpmn-moddle": "^9.0.4",
@@ -77,9 +87,5 @@
     "@types/node": "^22.7.0",
     "esbuild": "^0.28.1"
   },
-  "gitref": "fe867a0e0080d40c98359688494c808eebed1c8b",
-  "gitHead": "fe867a0e0080d40c98359688494c808eebed1c8b",
-  "publishConfig": {
-    "registry": "https://registry.npmjs.org/"
-  }
+  "gitref": "776d66e5ed1bfa43a703c7ff5684e9c5c8c26152"
 }