@uipath/packager-tool-webapp 1.0.4

package/dist/webapp-tool.d.ts

@@ -0,0 +1,29 @@
+import { type IFileSystem, type IProjectBuildOptions, type IProjectPackOptions, type IProjectRestoreOptions, type IProjectValidateOptions, type IToolLogger, ProjectTool, ToolResult } from "@uipath/solutionpackager-tool-core";
+/**
+ * WebApp project tool implementation
+ * Packages WebApp-type projects into .nupkg artifacts
+ */
+export declare class WebAppTool extends ProjectTool {
+    private readonly _temporaryStorage;
+    private _tempBuildFolder;
+    constructor(fileSystem: IFileSystem, logger: IToolLogger);
+    restoreAsync(_options: IProjectRestoreOptions, _cancellationToken?: AbortSignal): Promise<ToolResult>;
+    validateAsync(options: IProjectValidateOptions, _cancellationToken?: AbortSignal): Promise<ToolResult>;
+    buildAsync(_options: IProjectBuildOptions, _cancellationToken?: AbortSignal): Promise<ToolResult>;
+    packAsync(options: IProjectPackOptions, _cancellationToken?: AbortSignal): Promise<ToolResult>;
+    dispose(): Promise<void>;
+    /**
+     * Common helper that validates manifest file presence, loads manifest
+     * and instantiates a variant strategy. Throws Error with user-friendly
+     * message when any step fails.
+     */
+    private getManifestAndStrategy;
+    /**
+     * Standardized error handling helper
+     */
+    private handleError;
+    /**
+     * Create a logger wrapper for strategy methods
+     */
+    private createStrategyLogger;
+}

package/package.json

@@ -0,0 +1,58 @@
+{
+    "name": "@uipath/packager-tool-webapp",
+    "version": "1.0.4",
+    "description": "UiPath WebApp 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-webapp"
+    },
+    "publishConfig": {
+        "registry": "https://registry.npmjs.org/"
+    },
+    "types": "./dist/index.d.ts",
+    "scripts": {
+        "build": "bun build ./src/index.ts --outdir dist --format esm --target browser --external @uipath/solutionpackager-tool-core && tsc --emitDeclarationOnly --outDir dist",
+        "dev": "bun build ./src/index.ts --outdir dist --format esm --target browser --external @uipath/solutionpackager-tool-core --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/solutionpackager-tool-core": "0.0.31"
+    },
+    "devDependencies": {
+        "@types/node": "^25.5.0",
+        "@uipath/solutionpackager-tool-core": "0.0.31",
+        "@vitest/browser": "^4.0.14",
+        "@vitest/browser-playwright": "^4.0.14",
+        "@vitest/coverage-v8": "^4.0.14",
+        "playwright": "^1.57.0",
+        "typescript": "^5.9.3",
+        "vitest": "^4.0.14"
+    }
+}

package/src/constants.ts

@@ -0,0 +1,60 @@
+/**
+ * Constants used throughout the WebApp tool implementation
+ */
+
+/**
+ * File names
+ */
+export const PROJECT_JSON_FILE = "project.json";
+
+/**
+ * Default bundle path if not specified in manifest
+ */
+export const DEFAULT_BUNDLE_PATH = "source/dist";
+
+/**
+ * Target runtime for operate.json
+ */
+export const TARGET_RUNTIME = "Coded";
+
+/**
+ * Default entry point type
+ */
+export const DEFAULT_ENTRY_POINT_TYPE = "api";
+
+/**
+ * Error messages
+ */
+export const ERROR_MESSAGES = {
+    MANIFEST_NOT_FOUND: (file: string): string =>
+        `WebApp manifest not found: ${file}. This file is required for WebApp projects.`,
+
+    PROJECT_JSON_FOUND:
+        "project.json found in WebApp project. The WebApp tool only supports Coded web apps without project.json.",
+
+    MANIFEST_LOAD_FAILED: (file: string): string =>
+        `Failed to load or parse ${file}`,
+
+    BUNDLE_NOT_FOUND: (path: string): string =>
+        `Compiled bundle not found at ${path}. Ensure the project is built before packing.`,
+
+    BUNDLE_NOT_DIRECTORY: (path: string): string =>
+        `Bundle path ${path} exists but is not a directory.`,
+
+    BUILD_NOT_SUPPORTED:
+        "Build execution (isCompiled=false) is not yet supported. Please build the project manually and set isCompiled=true.",
+
+    VALIDATION_FAILED: (context: string): string =>
+        `Validation failed: ${context}`,
+
+    PACKING_FAILED: (context: string): string =>
+        `An error occurred while packing WebApp project: ${context}`,
+
+    PACKAGE_NAME_REQUIRED: "Package name is required",
+
+    PACKAGE_VERSION_REQUIRED: "Package version is required",
+
+    PROJECT_PATH_REQUIRED: "Project path is required",
+
+    OUTPUT_PATH_REQUIRED: "Output path is required",
+} as const;

package/src/index.ts

@@ -0,0 +1,7 @@
+import { toolsFactoryRepository } from "@uipath/solutionpackager-tool-core";
+import { WebAppToolFactory } from "./webapp-tool-factory.js";
+
+export { WebAppTool } from "./webapp-tool.js";
+export { WebAppToolFactory } from "./webapp-tool-factory.js";
+
+toolsFactoryRepository.registerProjectToolFactory(new WebAppToolFactory());

package/src/models/webapp-manifest.ts

@@ -0,0 +1,45 @@
+export enum WebAppVariantType {
+    Coded = "Coded",
+    JS = "JS",
+}
+
+/** @public */
+export enum AppSubType {
+    /** Coded app subtype that is registered with Solutions */
+    Coded = "Coded",
+    /** CodedAction app subtype that is registered with Solutions */
+    CodedAction = "CodedAction",
+}
+
+/**
+ * Variant-specific configurations
+ */
+export interface CodedAppConfig {
+    /** If true: pack only; If false: build → pack (future) */
+    isCompiled?: boolean;
+    /** Compiled bundle folder location (default: dist/) */
+    bundlePath?: string;
+    /** Optional build command for future scenarios */
+    buildCommand?: string;
+    isActionApp?: boolean;
+}
+
+export interface JsConfig {
+    // Placeholder for future properties specific to JS variant
+    [key: string]: unknown;
+}
+
+/** Map each variant to its specific config type */
+type ManifestConfigMap = {
+    [WebAppVariantType.Coded]: CodedAppConfig;
+    [WebAppVariantType.JS]: JsConfig;
+};
+
+/** WebApp manifest type parameterized by variant */
+export type WebAppManifest<T extends WebAppVariantType = WebAppVariantType> = {
+    type: T;
+    solutionResourceSubType: string;
+    config?: ManifestConfigMap[T];
+};
+
+export const WEBAPP_MANIFEST_FILE_NAME = "webAppManifest.json";

package/src/strategies/coded-app-strategy.ts

@@ -0,0 +1,413 @@
+import type {
+    IFileSystem,
+    OperateFileModel,
+    PackageDescriptorFileModel,
+} from "@uipath/solutionpackager-tool-core";
+import {
+    NugetConstants,
+    NugetPackager,
+    Path,
+    ProjectTypes,
+    TargetFramework,
+} from "@uipath/solutionpackager-tool-core";
+import {
+    DEFAULT_BUNDLE_PATH,
+    DEFAULT_ENTRY_POINT_TYPE,
+    ERROR_MESSAGES,
+    TARGET_RUNTIME,
+} from "../constants.js";
+import type { WebAppManifest } from "../models/webapp-manifest.js";
+import {
+    WEBAPP_MANIFEST_FILE_NAME,
+    type WebAppVariantType,
+} from "../models/webapp-manifest.js";
+import { copyDirectoryAsync } from "../utils/fs-helpers.js";
+import type { PackageArgs, VariantStrategy } from "./variant-strategy.js";
+
+/**
+ * Coded app strategy for Coded variant
+ * Supports isCompiled=true (v1) and isCompiled=false (future)
+ */
+export class CodedAppStrategy implements VariantStrategy {
+    constructor(private readonly fileSystem: IFileSystem) {}
+
+    /**
+     * Variant-specific validation: warn if compiled bundle is expected but missing
+     */
+    async validateAsync(args: {
+        fileSystem: IFileSystem;
+        projectPath: string;
+        manifest: WebAppManifest;
+        logger?: {
+            info: (message: string) => void;
+            error: (message: string) => void;
+            progress: (message: string) => void;
+        };
+    }): Promise<void> {
+        const { projectPath, manifest, logger } = args;
+
+        // Narrow manifest to Coded to read typed config safely
+        const typed = manifest as WebAppManifest<WebAppVariantType.Coded>;
+        let bundlePath = typed.config?.bundlePath;
+        if (typeof bundlePath !== "string" || bundlePath.length === 0) {
+            bundlePath = DEFAULT_BUNDLE_PATH;
+        }
+        const isCompiled = typed.config?.isCompiled ?? true;
+
+        if (isCompiled) {
+            const fullBundlePath = Path.join(projectPath, bundlePath);
+            const exists = await this.fileSystem.exists(fullBundlePath);
+            if (!exists) {
+                const message = ERROR_MESSAGES.BUNDLE_NOT_FOUND(fullBundlePath);
+
+                // Prefer `warn` if available on the provided logger, otherwise fall back to `info`.
+                if ((logger as any)?.warn) {
+                    (logger as any).warn(message);
+                } else {
+                    logger?.info(`Warning: ${message}`);
+                }
+            }
+        }
+    }
+
+    async packageAsync(args: PackageArgs): Promise<string> {
+        const { projectPath, manifest, outputPath, packageInfo, logger } = args;
+
+        logger?.info(
+            `Packaging Coded variant: ${packageInfo.id}@${packageInfo.version}`,
+        );
+
+        // Get bundle path from manifest or use default
+        let bundlePath = (manifest as WebAppManifest<WebAppVariantType.Coded>)
+            .config?.bundlePath;
+        if (typeof bundlePath !== "string" || bundlePath.length === 0) {
+            bundlePath = DEFAULT_BUNDLE_PATH;
+        }
+        const isCompiled =
+            (manifest as WebAppManifest<WebAppVariantType.Coded>).config
+                ?.isCompiled ?? true;
+
+        const fullBundlePath = Path.join(projectPath, bundlePath);
+
+        // Validate compiled bundle exists (for v1, isCompiled=true)
+        if (isCompiled) {
+            logger?.progress("Validating compiled bundle...");
+            const bundleExists = await this.fileSystem.exists(fullBundlePath);
+            if (!bundleExists) {
+                throw new Error(
+                    ERROR_MESSAGES.BUNDLE_NOT_FOUND(fullBundlePath),
+                );
+            }
+
+            const bundleStat = await this.fileSystem.stat(fullBundlePath);
+            if (!bundleStat?.isDirectory()) {
+                throw new Error(
+                    ERROR_MESSAGES.BUNDLE_NOT_DIRECTORY(fullBundlePath),
+                );
+            }
+        } else {
+            // Future: Run build command
+            logger?.info(
+                "Build mode (isCompiled=false) is not yet implemented in v1.",
+            );
+            throw new Error(ERROR_MESSAGES.BUILD_NOT_SUPPORTED);
+        }
+
+        // Create bundle directory structure (similar to api-workflow)
+        const localBuildFolder = Path.join(
+            outputPath,
+            NugetConstants.OutputFolderName,
+        );
+        const contentFolder = Path.join(
+            localBuildFolder,
+            NugetConstants.ContentFolderName,
+        );
+        await this.fileSystem.mkdir(contentFolder);
+
+        try {
+            // Copy bundle to content folder
+            logger?.progress("Copying bundle to content folder...");
+            await copyDirectoryAsync(
+                this.fileSystem,
+                fullBundlePath,
+                contentFolder,
+            );
+
+            // Prepare metadata files
+            logger?.progress("Preparing metadata files...");
+            await this.prepareMetadataFiles(
+                localBuildFolder,
+                contentFolder,
+                packageInfo,
+                manifest,
+                projectPath,
+            );
+
+            // Create the NuGet package using native packager
+            logger?.progress("Creating NuGet package...");
+            const nupkgFileName = `${packageInfo.id}.${packageInfo.version}.nupkg`;
+            const nupkgPath = Path.join(outputPath, nupkgFileName);
+
+            const packager = new NugetPackager(this.fileSystem);
+            const result = await packager.packAsync(
+                localBuildFolder,
+                packageInfo,
+                nupkgPath,
+            );
+
+            logger?.info(`Package created successfully: ${result.outputPath}`);
+            return result.outputPath;
+        } finally {
+            // Always cleanup the temporary build folder
+            try {
+                await this.fileSystem.rm(localBuildFolder);
+            } catch (cleanupError) {
+                logger?.error(
+                    `Failed to cleanup build folder: ${
+                        cleanupError instanceof Error
+                            ? cleanupError.message
+                            : String(cleanupError)
+                    }`,
+                );
+            }
+        }
+    }
+
+    /**
+     * Prepare metadata files (operate.json, package-descriptor.json, bindings.json, bindings_v2.json, entry-points.json)
+     */
+    private async prepareMetadataFiles(
+        _localBuildFolder: string,
+        contentFolder: string,
+        packageInfo: {
+            id: string;
+            version: string;
+            author?: string;
+            description?: string;
+        },
+        _manifest: any,
+        projectPath: string,
+    ): Promise<void> {
+        // Determine main file - check for index.html or use default
+        let mainFile = "index.html";
+        const indexHtmlPath = Path.join(contentFolder, "index.html");
+        const indexHtmlExists = await this.fileSystem.exists(indexHtmlPath);
+        if (!indexHtmlExists) {
+            // Check for other common entry points
+            const possibleEntries = ["index.html", "main.html", "app.html"];
+            for (const entry of possibleEntries) {
+                const entryPath = Path.join(contentFolder, entry);
+                if (await this.fileSystem.exists(entryPath)) {
+                    mainFile = entry;
+                    break;
+                }
+            }
+        }
+
+        // Create operate.json in content folder
+        const operatePath = Path.join(
+            contentFolder,
+            NugetConstants.OperateFileName,
+        );
+        const operateModel: OperateFileModel & { targetRuntime: string } = {
+            projectId: packageInfo.id,
+            main: mainFile,
+            contentType: ProjectTypes.WebApp,
+            targetFramework: TargetFramework.Portable,
+            targetRuntime: TARGET_RUNTIME,
+            runtimeOptions: {
+                requiresUserInteraction: false,
+                isAttended: false,
+            },
+        };
+
+        const operateJson = JSON.stringify(operateModel, null, 2);
+        await this.fileSystem.writeFile(operatePath, operateJson);
+
+        // Copy webAppManifest.json from project root into content (as-is)
+        const manifestSourcePath = Path.join(
+            projectPath,
+            WEBAPP_MANIFEST_FILE_NAME,
+        );
+        const manifestDestPath = Path.join(
+            contentFolder,
+            WEBAPP_MANIFEST_FILE_NAME,
+        );
+        const manifestExists = await this.fileSystem.exists(manifestSourcePath);
+        if (manifestExists) {
+            const manifestContent =
+                await this.fileSystem.readFile(manifestSourcePath);
+            if (manifestContent) {
+                await this.fileSystem.writeFile(
+                    manifestDestPath,
+                    manifestContent,
+                );
+            }
+        }
+
+        // Copy uipath.json from project root into content (if it exists)
+        const uipathJsonSourcePath = Path.join(projectPath, "uipath.json");
+        const uipathJsonDestPath = Path.join(contentFolder, "uipath.json");
+        const uipathJsonExists =
+            await this.fileSystem.exists(uipathJsonSourcePath);
+        if (uipathJsonExists) {
+            const uipathJsonContent =
+                await this.fileSystem.readFile(uipathJsonSourcePath);
+            if (uipathJsonContent) {
+                await this.fileSystem.writeFile(
+                    uipathJsonDestPath,
+                    uipathJsonContent,
+                );
+            }
+        }
+
+        // Create or copy bindings.json (version 1.0)
+        const bindingsPath = Path.join(contentFolder, "bindings.json");
+        const bindingsExists = await this.fileSystem.exists(bindingsPath);
+
+        if (!bindingsExists) {
+            const bindingsJson = JSON.stringify(
+                {
+                    version: "1.0",
+                    resources: [],
+                },
+                null,
+                2,
+            );
+            await this.fileSystem.writeFile(bindingsPath, bindingsJson);
+        }
+
+        // Create or copy bindings_v2.json (version 2.0)
+        const bindingsV2Path = Path.join(contentFolder, "bindings_v2.json");
+        const bindingsV2Exists = await this.fileSystem.exists(bindingsV2Path);
+
+        if (!bindingsV2Exists) {
+            const bindingsV2Json = JSON.stringify(
+                {
+                    version: "2.0",
+                    resources: [],
+                },
+                null,
+                2,
+            );
+            await this.fileSystem.writeFile(bindingsV2Path, bindingsV2Json);
+        }
+
+        // Create or copy entry-points.json
+        const entryPointsPath = Path.join(contentFolder, "entry-points.json");
+        const projectEntryPointsPath = Path.join(
+            projectPath,
+            "entry-points.json",
+        );
+
+        let entryPointsContent: string;
+        const projectEntryPointsExists = await this.fileSystem.exists(
+            projectEntryPointsPath,
+        );
+
+        if (projectEntryPointsExists) {
+            const entryPointsData = await this.fileSystem.readFile(
+                projectEntryPointsPath,
+            );
+            if (entryPointsData) {
+                entryPointsContent = new TextDecoder().decode(entryPointsData);
+            } else {
+                entryPointsContent = this.createDefaultEntryPoints(mainFile);
+            }
+        } else {
+            entryPointsContent = this.createDefaultEntryPoints(mainFile);
+        }
+
+        await this.fileSystem.writeFile(entryPointsPath, entryPointsContent);
+
+        // Create package-descriptor.json in content folder
+        const packageDescriptorPath = Path.join(
+            contentFolder,
+            NugetConstants.PackageDescriptorFileName,
+        );
+        const packageDescriptor: PackageDescriptorFileModel = {
+            files: {
+                [NugetConstants.OperateFileName]: Path.join(
+                    NugetConstants.ContentFolderName,
+                    NugetConstants.OperateFileName,
+                ),
+                "entry-points.json": Path.join(
+                    NugetConstants.ContentFolderName,
+                    "entry-points.json",
+                ),
+                "bindings.json": Path.join(
+                    NugetConstants.ContentFolderName,
+                    "bindings_v2.json",
+                ),
+            },
+        };
+
+        const packageDescriptorJson = JSON.stringify(
+            packageDescriptor,
+            null,
+            2,
+        );
+        await this.fileSystem.writeFile(
+            packageDescriptorPath,
+            packageDescriptorJson,
+        );
+    }
+
+    /**
+     * Create default entry-points.json structure
+     */
+    private createDefaultEntryPoints(mainFile: string): string {
+        const uniqueId = this.generateUniqueId();
+
+        const entryPoints = {
+            $schema: "https://cloud.uipath.com/draft/2024-12/entry-point",
+            $id: "entry-points-doc-001",
+            entryPoints: [
+                {
+                    filePath: mainFile,
+                    uniqueId: uniqueId,
+                    type: DEFAULT_ENTRY_POINT_TYPE,
+                    input: {
+                        amount: { type: "integer" },
+                        id: { type: "string" },
+                    },
+                    output: {
+                        status: { type: "string" },
+                    },
+                },
+            ],
+        };
+
+        return JSON.stringify(entryPoints, null, 2);
+    }
+
+    /**
+     * Generate a cryptographically secure unique ID (UUID v4-like format)
+     */
+    private generateUniqueId(): string {
+        const randomBytes = new Uint8Array(16);
+
+        if (typeof crypto !== "undefined" && crypto.getRandomValues) {
+            crypto.getRandomValues(randomBytes);
+        } else {
+            throw new Error("crypto.getRandomValues is not available");
+        }
+
+        // Set version (4) and variant bits according to UUID v4 spec
+        randomBytes[6] = (randomBytes[6] & 0x0f) | 0x40; // Version 4
+        randomBytes[8] = (randomBytes[8] & 0x3f) | 0x80; // Variant 10
+
+        // Convert to UUID string format: xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx
+        const hex = Array.from(randomBytes)
+            .map((b) => b.toString(16).padStart(2, "0"))
+            .join("");
+
+        return [
+            hex.substring(0, 8),
+            hex.substring(8, 12),
+            hex.substring(12, 16),
+            hex.substring(16, 20),
+            hex.substring(20, 32),
+        ].join("-");
+    }
+}

package/src/strategies/variant-strategy-factory.ts

@@ -0,0 +1,39 @@
+import type { IFileSystem } from "@uipath/solutionpackager-tool-core";
+import type { WebAppManifest } from "../models/webapp-manifest.js";
+import { WebAppVariantType } from "../models/webapp-manifest.js";
+import { CodedAppStrategy } from "./coded-app-strategy.js";
+import type { VariantStrategy } from "./variant-strategy.js";
+
+/**
+ * Factory for creating variant-specific packaging strategies
+ */
+export class VariantStrategyFactory {
+    /**
+     * Create a strategy instance based on manifest type
+     * @param manifest - WebApp manifest
+     * @param fileSystem - File system instance
+     * @returns Strategy instance
+     * @throws Error if variant is not supported
+     */
+    static createStrategy(
+        manifest: WebAppManifest,
+        fileSystem: IFileSystem,
+    ): VariantStrategy {
+        const variant = manifest.type;
+
+        switch (variant) {
+            case WebAppVariantType.Coded:
+                return new CodedAppStrategy(fileSystem);
+
+            case WebAppVariantType.JS:
+                throw new Error(
+                    "JS variant is not yet implemented. Only Coded is supported in v1.",
+                );
+
+            default:
+                throw new Error(
+                    `Unknown WebApp variant: ${manifest.type}. Supported variants: ${Object.values(WebAppVariantType).join(", ")}`,
+                );
+        }
+    }
+}