@uipath/solutionpackager-sdk 1.0.10

package/README.md

@@ -0,0 +1,308 @@
+# Solution Packager
+
+A Module Federation Enterprise (MFE) orchestrator for UiPath solution packaging. This tool provides a framework for registering and executing project-specific packaging tools with cross-platform filesystem support.
+
+## Overview
+
+The Solution Packager is a dummy tool framework designed to:
+
+- Register project-type-specific packaging tools
+- Orchestrate execution across multiple projects in a solution
+- Provide unified filesystem access (Node.js and Browser environments)
+- Track execution time and results for each tool
+
+## Installation
+
+```bash
+npm install
+```
+
+### WorkflowCompiler Prerequisite
+
+The Node.js implementation of the WorkflowCompiler tool (used for Process, Library, WebApp, and Tests projects) requires the UiPath WorkflowCompiler to be installed locally. From the packager root directory, run:
+
+```bash
+# Windows (default)
+npm run download:workflowcompiler
+
+# Linux
+npm run download:workflowcompiler:core
+
+# macOS
+npm run download:workflowcompiler:macos
+```
+
+**Requirements:** Azure CLI must be installed and authenticated (`az login`) with access to the UiPath Azure DevOps organization. The tool will be installed to `packager/tools/workflowcompiler/`. The browser implementation does not require local installation as it delegates to a remote agent.
+
+## Usage
+
+### Registering a Tool
+
+```typescript
+import { registerTool } from "solutionpackager";
+
+registerTool({
+  name: "MyTool",
+  projectType: "myproject",
+  execute: async (path, params, fs) => {
+    // Use the filesystem abstraction
+    await fs.writeFile("/output.txt", "Hello World");
+
+    return {
+      success: true,
+      logs: ["Tool executed successfully"],
+    };
+  },
+});
+```
+
+### Running a Solution
+
+```typescript
+import { runSolution } from "solutionpackager";
+
+// Node.js environment (no lazy loading)
+const results = await runSolution("path/to/solution.sln", { param: "value" });
+
+// Browser environment (with lazy loading support)
+const results = await runSolution(
+  "path/to/solution.sln",
+  { param: "value" },
+  {
+    lazyLoad: async (path: string) => {
+      // Fetch file content from remote server
+      const response = await fetch(`/api/files${path}`);
+      return new Uint8Array(await response.arrayBuffer());
+    },
+  }
+);
+```
+
+## Development
+
+### Build
+
+```bash
+npm run build
+```
+
+Builds the project using `rslib` and generates:
+
+- ES module output in `dist/`
+- TypeScript declarations
+- Module Federation remote entry point
+
+### Testing
+
+```bash
+# Run all tests (Node.js environment)
+npm test
+
+# Run browser tests
+npm run test:browser
+
+# Run with coverage
+npm run test:coverage
+```
+
+#### End-to-End Testing
+
+The e2e tests pack a complete UiPath solution and verify the output structure:
+
+```bash
+# Run e2e tests
+npm test solution-packager-e2e
+
+# Run e2e tests in watch mode
+npx vitest solution-packager-e2e
+```
+
+**What the e2e test does:**
+
+1. Loads the test solution from `tests/test-data/Blueprints/SupportedProjectsSolution.uis`
+2. Extracts and packs the solution using the solution packager
+3. Creates a packaged archive (`.zip`) in a temporary directory
+4. Verifies the output structure contains:
+   - A `files/` directory with project outputs
+   - `.nupkg` files for each project in the solution
+
+**Inspecting the output:**
+
+The test creates output in a temporary directory (OS temp folder). To keep the output for inspection, modify the test to use a known directory or add a breakpoint after packing completes. The output archive structure looks like:
+
+```text
+SupportedProjectsSolution_<version>.zip
+└── files/
+    ├── <project-id-1>/
+    │   └── <project-name>.nupkg
+    ├── <project-id-2>/
+    │   └── <project-name>.nupkg
+    └── ...
+```
+
+Each `.nupkg` file contains the packaged RPA project with all dependencies and metadata.
+
+#### Test Coverage
+
+- **Node.js Tests**: Validates platform detection and ensures lazy loading is rejected in Node.js environment
+- **Browser Tests**: Tests tool registration, execution, filesystem operations, and lazy loading functionality
+- **E2E Tests**: Complete solution packing workflow with real UiPath projects
+
+## Architecture
+
+### Core Components
+
+- **`registry.ts`**: Tool registration and lookup system
+- **`orchestrator.ts`**: Solution parsing and tool execution coordinator
+- **`types.ts`**: TypeScript interfaces for tools, projects, and solutions
+
+### Dependencies
+
+- **`uipath-solutionpackager-tool-core`**: Cross-platform filesystem abstraction
+
+## Tool Package Requirements
+
+Tool packages consumed by the SDK must follow these conventions to ensure correct bundling and compatibility.
+
+### package.json
+
+- **`type`**: Must be `"module"` (ESM)
+- **`exports`**: Must include both `source` and `default` conditions:
+  ```json
+  "exports": {
+    ".": {
+      "source": "./src/index.ts",
+      "default": "./dist/index.js"
+    }
+  }
+  ```
+  The `source` condition allows the SDK bundler to resolve directly from TypeScript source (via `conditionNames: ["source", "import", "default"]`), enabling better tree-shaking and avoiding double-bundling.
+- **`files`**: Must include both `dist` and `src`:
+  ```json
+  "files": ["dist", "src"]
+  ```
+- **`types`**: Must point to `"./dist/index.d.ts"`
+- **`peerDependencies`**: `@uipath/solutionpackager-tool-core` should be a peer dependency (not a regular dependency)
+
+### rslib.config.ts
+
+```typescript
+import { defineConfig } from '@rslib/core';
+
+export default defineConfig({
+  source: {
+    entry: {
+      index: './src/index.ts',
+    },
+  },
+  lib: [
+    {
+      bundle: true,
+      format: 'esm',
+      syntax: 'es2021',
+      dts: true,
+      autoExternal: true,
+    },
+  ],
+  output: {
+    target: 'web',
+  },
+  tools: {
+    rspack: {
+      devtool: 'source-map',
+      output: {
+        devtoolModuleFilenameTemplate: 'webpack://<tool-name>/[resource-path]',
+      },
+      resolve: {
+        fallback: {
+          'fs/promises': false,
+          fs: false,
+          path: false,
+        },
+      },
+    },
+  },
+});
+```
+
+Key settings:
+- **`autoExternal: true`**: Keeps dependencies external. The SDK (`autoExternal: false`, `all-in-one`) handles bundling everything into a standalone output.
+- **`target: "web"`**: Tools must work in both browser and Node.js. This ensures no Node.js built-ins leak into the bundle.
+- **`fallback`**: Silences bundler errors for Node.js module imports from `solutionpackager-tool-core` or transitive dependencies.
+- **`devtool: "source-map"`**: Enables debugging with properly namespaced source maps.
+
+## Platform Support
+
+- **Node.js**: Uses native `fs` module, lazy loading not supported
+- **Browser**: Uses ZenFS with IndexedDB backend, supports lazy loading for on-demand file fetching
+
+## Current Status
+
+The framework is **fully functional** for:
+
+- **Module Federation**: Dynamic loading of external tool packages (`apiworkflow`, `connector`) at runtime.
+- **Cross-Platform Filesystem**: Seamless file operations in both Node.js and Browser (via ZenFS).
+- **Tool Orchestration**: Registration and execution flow is complete.
+
+For a live demonstration of the browser capabilities, see the [Test Browser](../test-browser/README.md) project.
+
+
+
+### Console Interception with LogInterceptor
+
+The `solutionpackager` package provides a `logInterceptor` singleton that intercepts console methods and allows you to register callbacks to process log messages. This is useful for capturing logs during execution and forwarding them to external logging services, displaying them in UI, or storing them for analysis.
+
+#### Complete Example: Intercepting Build Logs
+
+```typescript
+import { logInterceptor, LogLevel, LogMessage } from 'solutionpackager';
+
+// Storage for captured logs
+const capturedLogs: LogMessage[] = [];
+
+// Define callback to capture logs
+const captureCallback = (logMessage: LogMessage) => {
+  capturedLogs.push(logMessage);
+
+  // Forward errors to monitoring service
+  if (logMessage.logLevel === LogLevel.Error) {
+    notifyErrorMonitoring(logMessage);
+  }
+};
+
+// Start interception
+logInterceptor.registerCallback(captureCallback);
+logInterceptor.startIntercepting(LogLevel.Info);
+
+try {
+  // Execute your functionality - all console logs will be captured
+  await buildSolution('path/to/solution.sln');
+
+  // Can also log structured messages
+  console.log(new LogMessage('Build completed successfully', LogLevel.Info, {
+    source: 'build',
+    progress: 100,
+  }));
+
+} finally {
+  // Clean up
+  logInterceptor.unregisterCallback(captureCallback);
+  logInterceptor.stopIntercepting();
+
+  // Process captured logs
+  console.log(`Captured ${capturedLogs.length} log messages`);
+  const errors = capturedLogs.filter(log => log.logLevel === LogLevel.Error);
+  console.log(`Found ${errors.length} errors`);
+}```
+
+#### Important Notes
+
+- Callbacks are invoked **synchronously** for each log message
+- Logs from within callbacks are **not** re-intercepted (recursion prevention)
+- All intercepted logs are still written to the original console
+- LogMessage instances passed to console methods are automatically detected and formatted
+- Regular console arguments are converted to LogMessage instances with the appropriate level
+
+## License
+
+Internal UiPath project

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+import "@uipath/tool-connector";
+import "@uipath/tool-workflowcompiler";
+import "@uipath/tool-apiworkflow";
+import "@uipath/tool-bpmn";
+import "@uipath/tool-flow";
+import "@uipath/tool-case";
+import "@uipath/tool-agent";
+import "@uipath/tool-webapp";
+import "@uipath/resource-builder-tool";
+export * from "@uipath/solution-packager";