@uipath/packager-tool-flow 1.195.0 → 1.196.0

package/dist/exporter-version.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Replace the BPMN `exporterVersion="development"` placeholder produced by
+ * `@uipath/flow-converter` with a real version string.
+ *
+ * Why: Studio Web treats `exporterVersion="development"` as dev-build content
+ * and locks the file read-only ("cannot save"). Published CLI bundles must
+ * emit a real version so Studio Web accepts the uploaded BPMN for editing.
+ */
+export declare const replaceExporterVersion: (bpmnXml: string, version: string) => string;

package/dist/flow-io.d.ts

@@ -2,7 +2,22 @@ import { type IFileSystem } from "@uipath/filesystem";
 import { type Workflow } from "@uipath/flow-schema";
 export type FlowIoLogger = {
     warn: (message: string) => void;
+    debug?: (message: string) => void;
 };
+/**
+ * Migrate a freshly-parsed raw workflow document to the current schema
+ * version, in memory. `inMemoryWorkflowToFileFormat` refuses to serialize a
+ * workflow whose `version` predates the current one (the flow-schema
+ * migration contract), so every read that can reach a serialize path —
+ * debug, format, pack, node/edge edits — must migrate first, the same way
+ * the canvas migrates on open. The source file is never touched; the
+ * migrated version is persisted only when a caller explicitly writes back.
+ *
+ * Fail-soft: a missing/current `version`, an unknown version with no
+ * migration chain, or a failing chain step all return the document
+ * unchanged — the serializer guard remains the backstop, exactly as before.
+ */
+export declare function migrateRawWorkflow(raw: unknown, logger?: FlowIoLogger): unknown;
 export interface ReadFlowWorkflowOptions {
     /** Filesystem to read from. Defaults to `getFileSystem()`. */
     fs?: IFileSystem;

package/dist/index.d.ts

@@ -1,4 +1,5 @@
-export { type FlowIoLogger, readFlowWorkflow } from "./flow-io.js";
+export { replaceExporterVersion } from "./exporter-version.js";
+export { type FlowIoLogger, migrateRawWorkflow, readFlowWorkflow, } from "./flow-io.js";
 export { FlowTool } from "./flow-tool.js";
 export { FlowToolFactory } from "./flow-tool-factory.js";
 export { setPublishIntentOnInlineAgents } from "./inline-agent-utils.js";

package/dist/index.js

@@ -27,6 +27,74 @@ import {
   ToolErrorCodes,
   ToolResult
 } from "@uipath/solutionpackager-tool-core";
+// package.json
+var package_default = {
+  name: "@uipath/packager-tool-flow",
+  version: "1.196.0",
+  description: "UiPath Flow tool implementation",
+  type: "module",
+  exports: {
+    ".": {
+      source: "./src/index.ts",
+      default: "./dist/index.js"
+    }
+  },
+  repository: {
+    type: "git",
+    url: "https://github.com/UiPath/cli.git",
+    directory: "packages/packager/packager-tool-flow"
+  },
+  publishConfig: {
+    registry: "https://npm.pkg.github.com/"
+  },
+  types: "./dist/index.d.ts",
+  scripts: {
+    build: "bun build ./src/index.ts --outdir dist --format esm --target browser --external @uipath/filesystem --external @uipath/solutionpackager-tool-core --external @uipath/tool-agent --external @uipath/flow-core --external @uipath/flow-converter --external @uipath/flow-migrations --external @uipath/flow-schema && tsc --emitDeclarationOnly --outDir dist",
+    dev: "bun build ./src/index.ts --outdir dist --format esm --target browser --external @uipath/filesystem --external @uipath/solutionpackager-tool-core --external @uipath/tool-agent --external @uipath/flow-core --external @uipath/flow-converter --external @uipath/flow-migrations --external @uipath/flow-schema --watch",
+    test: "vitest run",
+    "test:browser": "vitest run --config=vitest.browser.config.ts",
+    "test:coverage": "vitest run --coverage",
+    "test:browser:coverage": "vitest run --config=vitest.browser.config.ts --coverage",
+    "test:all": "bun run test && bun run test:browser",
+    "test:all:coverage": "bun run test:coverage && bun run test:browser:coverage",
+    prepack: "bun run build",
+    "publish:dry": "bun publish --dry-run",
+    "publish:gh": "bun publish",
+    "version:patch": "bun version patch --no-git-tag-version",
+    "version:minor": "bun version minor --no-git-tag-version",
+    "version:major": "bun version major --no-git-tag-version",
+    lint: "biome check ."
+  },
+  files: [
+    "dist",
+    "!dist/**/*.map",
+    "src"
+  ],
+  author: "",
+  license: "ISC",
+  peerDependencies: {
+    "@uipath/filesystem": "workspace:*",
+    "@uipath/flow-converter": "^0.1.312",
+    "@uipath/flow-core": "^0.2.415",
+    "@uipath/flow-migrations": "^0.1.214",
+    "@uipath/flow-schema": "^0.2.534",
+    "@uipath/solutionpackager-tool-core": "workspace:*",
+    "@uipath/tool-agent": "^1.2.6"
+  },
+  devDependencies: {
+    "@types/node": "^25.5.2",
+    "@uipath/filesystem": "workspace:*",
+    "@uipath/flow-core": "^0.2.415",
+    "@uipath/solutionpackager-tool-core": "workspace:*",
+    "@uipath/tool-agent": "^1.2.6",
+    "@vitest/browser": "^4.1.6",
+    "@vitest/browser-playwright": "^4.1.6",
+    "@vitest/coverage-v8": "^4.1.6",
+    playwright: "^1.57.0",
+    typescript: "^6.0.2",
+    vitest: "^4.1.6"
+  }
+};
 
 // src/agents.ts
 import { Path as Path2 } from "@uipath/solutionpackager-tool-core";
@@ -197,13 +265,40 @@ function ensureProcessBindings(workflow, logger) {
   return bindingsCreated;
 }
 
+// src/exporter-version.ts
+var replaceExporterVersion = (bpmnXml, version) => bpmnXml.replace(/exporterVersion="development"/g, () => `exporterVersion="${version}"`);
+
 // src/flow-io.ts
 import { getFileSystem } from "@uipath/filesystem";
+import {
+  currentVersion,
+  migrateWorkflow,
+  migrations
+} from "@uipath/flow-migrations";
 import { resolveAndConvertWorkflow } from "@uipath/flow-schema";
+function migrateRawWorkflow(raw, logger) {
+  const doc = raw;
+  if (!doc?.version || doc.version === currentVersion) {
+    return raw;
+  }
+  try {
+    const result = migrateWorkflow(migrations, doc, currentVersion);
+    if (!result.migrated) {
+      const detail = result.error ? `: [${result.error.step}] ${result.error.message}` : "";
+      logger?.warn(`migrateRawWorkflow: migration ${result.fromVersion} -> ${result.toVersion} did not apply${detail}`);
+      return raw;
+    }
+    logger?.debug?.(`migrateRawWorkflow: migrated workflow ${result.fromVersion} -> ${result.toVersion}`);
+    return result.workflow;
+  } catch (err) {
+    logger?.warn(`migrateRawWorkflow: failed to migrate v${String(doc.version)} workflow: ${err instanceof Error ? err.message : String(err)}`);
+    return raw;
+  }
+}
 async function readFlowWorkflow(filePath, options = {}) {
   const fs = options.fs ?? getFileSystem();
   const logger = options.logger;
-  const raw = JSON.parse(await readUtf8(fs, filePath));
+  const raw = migrateRawWorkflow(JSON.parse(await readUtf8(fs, filePath)), logger);
   const resolver = async (refPath, baseUri) => {
     const resolvedPath = fs.path.resolve(fs.path.dirname(baseUri), refPath);
     const refContent = await readUtf8OrNull(fs, resolvedPath);
@@ -368,7 +463,8 @@ class FlowTool extends ProjectTool {
     const fileFormat = inMemoryWorkflowToFileFormat(workflow);
     setPublishIntentOnInlineAgents(fileFormat);
     const resolvedFlowJson = JSON.stringify(fileFormat);
-    const { bpmn } = await convertFlowToBpmn(resolvedFlowJson);
+    const { bpmn: rawBpmn } = await convertFlowToBpmn(resolvedFlowJson);
+    const bpmn = replaceExporterVersion(rawBpmn, package_default.version);
     await this.fileSystem.writeFile(bpmnPath, bpmn);
     const packagingNodes = (workflow.nodes ?? []).map((node) => ({
       id: node.id,
@@ -564,7 +660,9 @@ class FlowToolFactory {
 toolsFactoryRepository.registerProjectToolFactory(new FlowToolFactory);
 export {
   setPublishIntentOnInlineAgents,
+  replaceExporterVersion,
   readFlowWorkflow,
+  migrateRawWorkflow,
   FlowToolFactory,
   FlowTool
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uipath/packager-tool-flow",
-  "version": "1.195.0",
+  "version": "1.196.0",
   "description": "UiPath Flow tool implementation",
   "type": "module",
   "exports": {
@@ -26,12 +26,13 @@
   "author": "",
   "license": "ISC",
   "peerDependencies": {
-    "@uipath/filesystem": "1.195.0",
-    "@uipath/flow-converter": "^0.1.273",
-    "@uipath/flow-core": "^0.2.376",
-    "@uipath/flow-schema": "^0.2.495",
-    "@uipath/solutionpackager-tool-core": "1.195.0",
-    "@uipath/tool-agent": "^1.2.4"
+    "@uipath/filesystem": "1.196.0",
+    "@uipath/flow-converter": "^0.1.312",
+    "@uipath/flow-core": "^0.2.415",
+    "@uipath/flow-migrations": "^0.1.214",
+    "@uipath/flow-schema": "^0.2.534",
+    "@uipath/solutionpackager-tool-core": "1.196.0",
+    "@uipath/tool-agent": "^1.2.6"
   },
-  "gitHead": "eecf5713cd579b15783c770d1923e44e730271ea"
+  "gitHead": "94d71f9c52214980a1f0ae62b3f5372095788553"
 }

package/src/exporter-version.ts

@@ -0,0 +1,18 @@
+/**
+ * Replace the BPMN `exporterVersion="development"` placeholder produced by
+ * `@uipath/flow-converter` with a real version string.
+ *
+ * Why: Studio Web treats `exporterVersion="development"` as dev-build content
+ * and locks the file read-only ("cannot save"). Published CLI bundles must
+ * emit a real version so Studio Web accepts the uploaded BPMN for editing.
+ */
+export const replaceExporterVersion = (
+    bpmnXml: string,
+    version: string,
+): string =>
+    // Use a replacer function so any `$` sequences in `version` (e.g. `$&`,
+    // `$1`) are not interpreted by String.prototype.replace.
+    bpmnXml.replace(
+        /exporterVersion="development"/g,
+        () => `exporterVersion="${version}"`,
+    );

package/src/flow-io.ts

@@ -1,10 +1,63 @@
 import { getFileSystem, type IFileSystem } from "@uipath/filesystem";
+import {
+    currentVersion,
+    type MigrationWorkflow,
+    migrateWorkflow,
+    migrations,
+} from "@uipath/flow-migrations";
 import { resolveAndConvertWorkflow, type Workflow } from "@uipath/flow-schema";
 
 export type FlowIoLogger = {
     warn: (message: string) => void;
+    debug?: (message: string) => void;
 };
 
+/**
+ * Migrate a freshly-parsed raw workflow document to the current schema
+ * version, in memory. `inMemoryWorkflowToFileFormat` refuses to serialize a
+ * workflow whose `version` predates the current one (the flow-schema
+ * migration contract), so every read that can reach a serialize path —
+ * debug, format, pack, node/edge edits — must migrate first, the same way
+ * the canvas migrates on open. The source file is never touched; the
+ * migrated version is persisted only when a caller explicitly writes back.
+ *
+ * Fail-soft: a missing/current `version`, an unknown version with no
+ * migration chain, or a failing chain step all return the document
+ * unchanged — the serializer guard remains the backstop, exactly as before.
+ */
+export function migrateRawWorkflow(
+    raw: unknown,
+    logger?: FlowIoLogger,
+): unknown {
+    const doc = raw as MigrationWorkflow | null;
+    if (!doc?.version || doc.version === currentVersion) {
+        return raw;
+    }
+    try {
+        const result = migrateWorkflow(migrations, doc, currentVersion);
+        if (!result.migrated) {
+            const detail = result.error
+                ? `: [${result.error.step}] ${result.error.message}`
+                : "";
+            logger?.warn(
+                `migrateRawWorkflow: migration ${result.fromVersion} -> ${result.toVersion} did not apply${detail}`,
+            );
+            return raw;
+        }
+        logger?.debug?.(
+            `migrateRawWorkflow: migrated workflow ${result.fromVersion} -> ${result.toVersion}`,
+        );
+        return result.workflow;
+    } catch (err) {
+        logger?.warn(
+            `migrateRawWorkflow: failed to migrate v${String(doc.version)} workflow: ${
+                err instanceof Error ? err.message : String(err)
+            }`,
+        );
+        return raw;
+    }
+}
+
 export interface ReadFlowWorkflowOptions {
     /** Filesystem to read from. Defaults to `getFileSystem()`. */
     fs?: IFileSystem;
@@ -33,7 +86,10 @@ export async function readFlowWorkflow(
 ): Promise<Workflow> {
     const fs = options.fs ?? getFileSystem();
     const logger = options.logger;
-    const raw = JSON.parse(await readUtf8(fs, filePath));
+    const raw = migrateRawWorkflow(
+        JSON.parse(await readUtf8(fs, filePath)),
+        logger,
+    );
 
     const resolver = async (refPath: string, baseUri: string) => {
         const resolvedPath = fs.path.resolve(fs.path.dirname(baseUri), refPath);

package/src/flow-tool.ts

@@ -33,8 +33,10 @@ import {
     ToolErrorCodes,
     ToolResult,
 } from "@uipath/solutionpackager-tool-core";
+import pkg from "../package.json" with { type: "json" };
 import { processAgents } from "./agents.js";
 import { ensureProcessBindings } from "./ensure-process-bindings.js";
+import { replaceExporterVersion } from "./exporter-version.js";
 import { readFlowWorkflow } from "./flow-io.js";
 import { setPublishIntentOnInlineAgents } from "./inline-agent-utils.js";
 
@@ -262,7 +264,8 @@ export class FlowTool extends ProjectTool {
         const fileFormat = inMemoryWorkflowToFileFormat(workflow);
         setPublishIntentOnInlineAgents(fileFormat);
         const resolvedFlowJson = JSON.stringify(fileFormat);
-        const { bpmn } = await convertFlowToBpmn(resolvedFlowJson);
+        const { bpmn: rawBpmn } = await convertFlowToBpmn(resolvedFlowJson);
+        const bpmn = replaceExporterVersion(rawBpmn, pkg.version);
         await this.fileSystem.writeFile(bpmnPath, bpmn);
 
         // Map file-format nodes to flat PackagingNode shape so

package/src/index.ts

@@ -2,7 +2,12 @@
 import { toolsFactoryRepository } from "@uipath/solutionpackager-tool-core";
 import { FlowToolFactory } from "./flow-tool-factory.js";
 
-export { type FlowIoLogger, readFlowWorkflow } from "./flow-io.js";
+export { replaceExporterVersion } from "./exporter-version.js";
+export {
+    type FlowIoLogger,
+    migrateRawWorkflow,
+    readFlowWorkflow,
+} from "./flow-io.js";
 export { FlowTool } from "./flow-tool.js";
 export { FlowToolFactory } from "./flow-tool-factory.js";
 export { setPublishIntentOnInlineAgents } from "./inline-agent-utils.js";