@uipath/packager-tool-flow 1.200.0-preview.109 → 1.201.0-preview.115

package/dist/flow-io.d.ts

@@ -1,23 +1,58 @@
 import { type IFileSystem } from "@uipath/filesystem";
-import { type Workflow } from "@uipath/flow-schema";
+import { type RefMap, type ResolveRefCallback, 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.
+ * Migrate a freshly-parsed raw workflow document to the fleet write floor
+ * (`MINIMUM_SUPPORTED_SCHEMA_VERSION`), in memory. `inMemoryWorkflowToFileFormat`
+ * refuses to serialize a workflow whose `version` differs from the floor (the
+ * flow-schema write-floor contract), so every read that can reach a serialize
+ * path — debug, format, pack, node/edge edits — must project to the floor
+ * first, the same way the canvas does on open. Older documents migrate up to
+ * the floor; newer reversible documents (up to `runtimeVersion`) project back
+ * down to it. 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.
+ * The document must have its `$ref` chunks resolved BEFORE this runs — the
+ * floor projection validates the full document shape (e.g. `layout.nodes`),
+ * which an unresolved `$ref` placeholder would fail. Use
+ * {@link resolveAndMigrateWorkflow} (or `resolveWorkflowRefs` + this) rather
+ * than calling this on raw file content.
+ *
+ * Fail-soft: a missing `version`, an unknown version with no migration chain,
+ * or a failing chain step all return the document unchanged — the serializer
+ * guard remains the backstop.
  */
 export declare function migrateRawWorkflow(raw: unknown, logger?: FlowIoLogger): unknown;
+/**
+ * Build the standard `$ref` resolver for `.flow` chunk files: resolves the
+ * ref path against the referencing file's directory and reads it as UTF-8
+ * JSON. A missing target logs a warning (fail-soft) and resolves to `null`;
+ * the resulting workflow may be partial.
+ */
+export declare function createFlowRefResolver(fs: IFileSystem, logger?: FlowIoLogger): ResolveRefCallback;
+/**
+ * Resolve all `$ref` chunk references in a parsed `.flow` document. Throws
+ * when resolution itself errors (cycles, resolver throws); a missing target
+ * is handled fail-soft by the resolver, not here.
+ */
+export declare function resolveWorkflowRefs(parsed: unknown, resolver: ResolveRefCallback, baseUri: string): Promise<{
+    resolved: unknown;
+    refMap: RefMap;
+}>;
+/**
+ * The full read pipeline for a parsed `.flow` document: resolve `$ref`
+ * chunks, project to the fleet write floor, convert to the in-memory
+ * Workflow. Refs are resolved BEFORE migrating because the floor projection
+ * validates the full document shape (e.g. `layout.nodes`), which an
+ * unresolved `$ref` placeholder would fail.
+ */
+export declare function resolveAndMigrateWorkflow(parsed: unknown, resolver: ResolveRefCallback, baseUri: string, logger?: FlowIoLogger): Promise<{
+    workflow: Workflow;
+    refMap: RefMap;
+}>;
 export interface ReadFlowWorkflowOptions {
     /** Filesystem to read from. Defaults to `getFileSystem()`. */
     fs?: IFileSystem;

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 export { buildInlineAgentContract, type InlineAgentContract, } from "./agents.js";
 export { replaceExporterVersion } from "./exporter-version.js";
-export { type FlowIoLogger, migrateRawWorkflow, readFlowWorkflow, } from "./flow-io.js";
+export { createFlowRefResolver, type FlowIoLogger, migrateRawWorkflow, readFlowWorkflow, resolveAndMigrateWorkflow, resolveWorkflowRefs, } 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

@@ -32,7 +32,7 @@ import {
 // package.json
 var package_default = {
   name: "@uipath/packager-tool-flow",
-  version: "1.200.0-preview.109",
+  version: "1.201.0-preview.115",
   description: "UiPath Flow tool implementation",
   type: "module",
   exports: {
@@ -75,17 +75,17 @@ var package_default = {
   license: "ISC",
   peerDependencies: {
     "@uipath/filesystem": "workspace:*",
-    "@uipath/flow-converter": "0.25.0",
-    "@uipath/flow-core": "^0.34.1",
-    "@uipath/flow-migrations": "^0.15.1",
-    "@uipath/flow-schema": "^0.22.1",
+    "@uipath/flow-converter": "^0.25.4",
+    "@uipath/flow-core": "^0.34.3",
+    "@uipath/flow-migrations": "^0.15.4",
+    "@uipath/flow-schema": "^0.22.4",
     "@uipath/solutionpackager-tool-core": "workspace:*",
     "@uipath/tool-agent": "^2.0.0"
   },
   devDependencies: {
     "@types/node": "^25.5.2",
     "@uipath/filesystem": "workspace:*",
-    "@uipath/flow-core": "^0.34.1",
+    "@uipath/flow-core": "^0.34.3",
     "@uipath/solutionpackager-tool-core": "workspace:*",
     "@uipath/tool-agent": "^2.0.0",
     "@vitest/browser": "^4.1.6",
@@ -350,21 +350,27 @@ var replaceExporterVersion = (bpmnXml, version) => bpmnXml.replace(/exporterVers
 // src/flow-io.ts
 import { getFileSystem } from "@uipath/filesystem";
 import {
-  currentVersion,
-  migrateWorkflow,
-  migrations
+  migrateWorkflowToFloor,
+  minimumSupportedVersion,
+  runtimeMigrations,
+  runtimeVersion
 } from "@uipath/flow-migrations";
-import { resolveAndConvertWorkflow } from "@uipath/flow-schema";
+import {
+  fileFormatToInMemoryWorkflow,
+  resolveRefs
+} from "@uipath/flow-schema";
 function migrateRawWorkflow(raw, logger) {
   const doc = raw;
-  if (!doc?.version || doc.version === currentVersion) {
+  if (!doc?.version) {
     return raw;
   }
   try {
-    const result = migrateWorkflow(migrations, doc, currentVersion);
+    const result = migrateWorkflowToFloor(runtimeMigrations, doc, runtimeVersion, minimumSupportedVersion);
+    if (result.error) {
+      logger?.warn(`migrateRawWorkflow: migration ${result.fromVersion} -> ${result.toVersion} did not apply: [${result.error.step}] ${result.error.message}`);
+      return raw;
+    }
     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}`);
@@ -374,11 +380,8 @@ function migrateRawWorkflow(raw, logger) {
     return raw;
   }
 }
-async function readFlowWorkflow(filePath, options = {}) {
-  const fs = options.fs ?? getFileSystem();
-  const logger = options.logger;
-  const raw = migrateRawWorkflow(JSON.parse(await readUtf8(fs, filePath)), logger);
-  const resolver = async (refPath, baseUri) => {
+function createFlowRefResolver(fs, logger) {
+  return async (refPath, baseUri) => {
     const resolvedPath = fs.path.resolve(fs.path.dirname(baseUri), refPath);
     const refContent = await readUtf8OrNull(fs, resolvedPath);
     if (refContent === null) {
@@ -387,9 +390,30 @@ async function readFlowWorkflow(filePath, options = {}) {
     }
     return JSON.parse(refContent);
   };
-  const { workflow } = await resolveAndConvertWorkflow(raw, resolver, {
-    baseUri: filePath
+}
+async function resolveWorkflowRefs(parsed, resolver, baseUri) {
+  const { resolved, refMap, errors } = await resolveRefs(parsed, resolver, {
+    baseUri
   });
+  if (errors.length > 0) {
+    const messages = errors.map((e) => `${e.pointer}: ${e.message}`).join("; ");
+    throw new Error(`Failed to resolve $ref(s): ${messages}`);
+  }
+  return { resolved, refMap };
+}
+async function resolveAndMigrateWorkflow(parsed, resolver, baseUri, logger) {
+  const { resolved, refMap } = await resolveWorkflowRefs(parsed, resolver, baseUri);
+  const migrated = migrateRawWorkflow(resolved, logger);
+  return {
+    workflow: fileFormatToInMemoryWorkflow(migrated),
+    refMap
+  };
+}
+async function readFlowWorkflow(filePath, options = {}) {
+  const fs = options.fs ?? getFileSystem();
+  const logger = options.logger;
+  const parsed = JSON.parse(await readUtf8(fs, filePath));
+  const { workflow } = await resolveAndMigrateWorkflow(parsed, createFlowRefResolver(fs, logger), filePath, logger);
   return workflow;
 }
 async function readUtf8(fs, filePath) {
@@ -712,12 +736,15 @@ class FlowToolFactory {
 toolsFactoryRepository.registerProjectToolFactory(new FlowToolFactory);
 export {
   setPublishIntentOnInlineAgents,
+  resolveWorkflowRefs,
+  resolveAndMigrateWorkflow,
   replaceExporterVersion,
   readFlowWorkflow,
   migrateRawWorkflow,
+  createFlowRefResolver,
   buildInlineAgentContract,
   FlowToolFactory,
   FlowTool
 };
 
-//# debugId=C70BAE8CC057EB2764756E2164756E21
+//# debugId=A24A63C9F661398464756E2164756E21

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uipath/packager-tool-flow",
-  "version": "1.200.0-preview.109",
+  "version": "1.201.0-preview.115",
   "description": "UiPath Flow tool implementation",
   "type": "module",
   "exports": {
@@ -25,13 +25,13 @@
   "author": "",
   "license": "ISC",
   "peerDependencies": {
-    "@uipath/filesystem": "1.200.0",
-    "@uipath/flow-converter": "0.25.0",
-    "@uipath/flow-core": "^0.34.1",
-    "@uipath/flow-migrations": "^0.15.1",
-    "@uipath/flow-schema": "^0.22.1",
-    "@uipath/solutionpackager-tool-core": "1.200.0",
+    "@uipath/filesystem": "1.201.0",
+    "@uipath/flow-converter": "^0.25.4",
+    "@uipath/flow-core": "^0.34.3",
+    "@uipath/flow-migrations": "^0.15.4",
+    "@uipath/flow-schema": "^0.22.4",
+    "@uipath/solutionpackager-tool-core": "1.201.0",
     "@uipath/tool-agent": "^2.0.0"
   },
-  "gitHead": "fcc01cdae81bbd0c25d3d4fc287537a9d19d99f4"
+  "gitHead": "f1086b73654d7728cb71f280588b3e0c77d535fc"
 }

package/src/flow-io.ts

@@ -1,11 +1,19 @@
 import { getFileSystem, type IFileSystem } from "@uipath/filesystem";
 import {
-    currentVersion,
     type MigrationWorkflow,
-    migrateWorkflow,
-    migrations,
+    migrateWorkflowToFloor,
+    minimumSupportedVersion,
+    runtimeMigrations,
+    runtimeVersion,
 } from "@uipath/flow-migrations";
-import { resolveAndConvertWorkflow, type Workflow } from "@uipath/flow-schema";
+import {
+    fileFormatToInMemoryWorkflow,
+    type RefMap,
+    type ResolveRefCallback,
+    resolveRefs,
+    type Workflow,
+    type WorkflowFile,
+} from "@uipath/flow-schema";
 
 export type FlowIoLogger = {
     warn: (message: string) => void;
@@ -13,37 +21,51 @@ export type FlowIoLogger = {
 };
 
 /**
- * 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.
+ * Migrate a freshly-parsed raw workflow document to the fleet write floor
+ * (`MINIMUM_SUPPORTED_SCHEMA_VERSION`), in memory. `inMemoryWorkflowToFileFormat`
+ * refuses to serialize a workflow whose `version` differs from the floor (the
+ * flow-schema write-floor contract), so every read that can reach a serialize
+ * path — debug, format, pack, node/edge edits — must project to the floor
+ * first, the same way the canvas does on open. Older documents migrate up to
+ * the floor; newer reversible documents (up to `runtimeVersion`) project back
+ * down to it. The source file is never touched; the migrated version is
+ * persisted only when a caller explicitly writes back.
+ *
+ * The document must have its `$ref` chunks resolved BEFORE this runs — the
+ * floor projection validates the full document shape (e.g. `layout.nodes`),
+ * which an unresolved `$ref` placeholder would fail. Use
+ * {@link resolveAndMigrateWorkflow} (or `resolveWorkflowRefs` + this) rather
+ * than calling this on raw file content.
  *
- * 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.
+ * Fail-soft: a missing `version`, an unknown version with no migration chain,
+ * or a failing chain step all return the document unchanged — the serializer
+ * guard remains the backstop.
  */
 export function migrateRawWorkflow(
     raw: unknown,
     logger?: FlowIoLogger,
 ): unknown {
     const doc = raw as MigrationWorkflow | null;
-    if (!doc?.version || doc.version === currentVersion) {
+    if (!doc?.version) {
         return raw;
     }
     try {
-        const result = migrateWorkflow(migrations, doc, currentVersion);
-        if (!result.migrated) {
-            const detail = result.error
-                ? `: [${result.error.step}] ${result.error.message}`
-                : "";
+        const result = migrateWorkflowToFloor(
+            runtimeMigrations,
+            doc,
+            runtimeVersion,
+            minimumSupportedVersion,
+        );
+        if (result.error) {
             logger?.warn(
-                `migrateRawWorkflow: migration ${result.fromVersion} -> ${result.toVersion} did not apply${detail}`,
+                `migrateRawWorkflow: migration ${result.fromVersion} -> ${result.toVersion} did not apply: [${result.error.step}] ${result.error.message}`,
             );
             return raw;
         }
+        if (!result.migrated) {
+            // Already at the floor with no repair to retain — nothing to change.
+            return raw;
+        }
         logger?.debug?.(
             `migrateRawWorkflow: migrated workflow ${result.fromVersion} -> ${result.toVersion}`,
         );
@@ -58,6 +80,76 @@ export function migrateRawWorkflow(
     }
 }
 
+/**
+ * Build the standard `$ref` resolver for `.flow` chunk files: resolves the
+ * ref path against the referencing file's directory and reads it as UTF-8
+ * JSON. A missing target logs a warning (fail-soft) and resolves to `null`;
+ * the resulting workflow may be partial.
+ */
+export function createFlowRefResolver(
+    fs: IFileSystem,
+    logger?: FlowIoLogger,
+): ResolveRefCallback {
+    return async (refPath: string, baseUri: string) => {
+        const resolvedPath = fs.path.resolve(fs.path.dirname(baseUri), refPath);
+        const refContent = await readUtf8OrNull(fs, resolvedPath);
+        if (refContent === null) {
+            logger?.warn(
+                `Failed to resolve $ref "${refPath}": file not found at ${resolvedPath}`,
+            );
+            return null;
+        }
+        return JSON.parse(refContent);
+    };
+}
+
+/**
+ * Resolve all `$ref` chunk references in a parsed `.flow` document. Throws
+ * when resolution itself errors (cycles, resolver throws); a missing target
+ * is handled fail-soft by the resolver, not here.
+ */
+export async function resolveWorkflowRefs(
+    parsed: unknown,
+    resolver: ResolveRefCallback,
+    baseUri: string,
+): Promise<{ resolved: unknown; refMap: RefMap }> {
+    const { resolved, refMap, errors } = await resolveRefs(parsed, resolver, {
+        baseUri,
+    });
+    if (errors.length > 0) {
+        const messages = errors
+            .map((e) => `${e.pointer}: ${e.message}`)
+            .join("; ");
+        throw new Error(`Failed to resolve $ref(s): ${messages}`);
+    }
+    return { resolved, refMap };
+}
+
+/**
+ * The full read pipeline for a parsed `.flow` document: resolve `$ref`
+ * chunks, project to the fleet write floor, convert to the in-memory
+ * Workflow. Refs are resolved BEFORE migrating because the floor projection
+ * validates the full document shape (e.g. `layout.nodes`), which an
+ * unresolved `$ref` placeholder would fail.
+ */
+export async function resolveAndMigrateWorkflow(
+    parsed: unknown,
+    resolver: ResolveRefCallback,
+    baseUri: string,
+    logger?: FlowIoLogger,
+): Promise<{ workflow: Workflow; refMap: RefMap }> {
+    const { resolved, refMap } = await resolveWorkflowRefs(
+        parsed,
+        resolver,
+        baseUri,
+    );
+    const migrated = migrateRawWorkflow(resolved, logger);
+    return {
+        workflow: fileFormatToInMemoryWorkflow(migrated as WorkflowFile),
+        refMap,
+    };
+}
+
 export interface ReadFlowWorkflowOptions {
     /** Filesystem to read from. Defaults to `getFileSystem()`. */
     fs?: IFileSystem;
@@ -86,26 +178,13 @@ export async function readFlowWorkflow(
 ): Promise<Workflow> {
     const fs = options.fs ?? getFileSystem();
     const logger = options.logger;
-    const raw = migrateRawWorkflow(
-        JSON.parse(await readUtf8(fs, filePath)),
+    const parsed: unknown = JSON.parse(await readUtf8(fs, filePath));
+    const { workflow } = await resolveAndMigrateWorkflow(
+        parsed,
+        createFlowRefResolver(fs, logger),
+        filePath,
         logger,
     );
-
-    const resolver = async (refPath: string, baseUri: string) => {
-        const resolvedPath = fs.path.resolve(fs.path.dirname(baseUri), refPath);
-        const refContent = await readUtf8OrNull(fs, resolvedPath);
-        if (refContent === null) {
-            logger?.warn(
-                `Failed to resolve $ref "${refPath}": file not found at ${resolvedPath}`,
-            );
-            return null;
-        }
-        return JSON.parse(refContent);
-    };
-
-    const { workflow } = await resolveAndConvertWorkflow(raw, resolver, {
-        baseUri: filePath,
-    });
     return workflow;
 }
 

package/src/index.ts

@@ -14,9 +14,12 @@ export {
 } from "./agents.js";
 export { replaceExporterVersion } from "./exporter-version.js";
 export {
+    createFlowRefResolver,
     type FlowIoLogger,
     migrateRawWorkflow,
     readFlowWorkflow,
+    resolveAndMigrateWorkflow,
+    resolveWorkflowRefs,
 } from "./flow-io.js";
 export { FlowTool } from "./flow-tool.js";
 export { FlowToolFactory } from "./flow-tool-factory.js";