@uipath/packager-tool-webapp 1.0.4

package/src/strategies/variant-strategy.ts

@@ -0,0 +1,67 @@
+import type {
+    IFileSystem,
+    NugetPackageInfo,
+} from "@uipath/solutionpackager-tool-core";
+import type { WebAppManifest } from "../models/webapp-manifest.js";
+
+/**
+ * Arguments for packaging operation
+ */
+export interface PackageArgs {
+    /**
+     * File system instance
+     */
+    fileSystem: IFileSystem;
+
+    /**
+     * Project root path
+     */
+    projectPath: string;
+
+    /**
+     * Parsed webApp manifest
+     */
+    manifest: WebAppManifest;
+
+    /**
+     * Output directory path
+     */
+    outputPath: string;
+
+    /**
+     * NuGet package information
+     */
+    packageInfo: NugetPackageInfo;
+
+    /**
+     * Logger instance (optional, for strategy-specific logging)
+     */
+    logger?: {
+        info: (message: string) => void;
+        error: (message: string) => void;
+        progress: (message: string) => void;
+        warn?: (message: string) => void;
+    };
+}
+
+/**
+ * Strategy interface for different WebApp variant packaging
+ */
+export interface VariantStrategy {
+    /**
+     * Package the WebApp according to variant-specific logic
+     * @param args - Packaging arguments
+     * @returns Path to the created .nupkg file
+     */
+    packageAsync(args: PackageArgs): Promise<string>;
+    /**
+     * Optional variant-specific validation step invoked during tool validation.
+     * Implementations may warn or throw on invalid configuration.
+     */
+    validateAsync?(args: {
+        fileSystem: PackageArgs["fileSystem"];
+        projectPath: string;
+        manifest: PackageArgs["manifest"];
+        logger?: PackageArgs["logger"];
+    }): Promise<void>;
+}

package/src/utils/fs-helpers.ts

@@ -0,0 +1,58 @@
+import type { IFileSystem } from "@uipath/solutionpackager-tool-core";
+import { Path } from "@uipath/solutionpackager-tool-core";
+
+/**
+ * Copy directory recursively from source to destination
+ */
+export async function copyDirectoryAsync(
+    fileSystem: IFileSystem,
+    sourcePath: string,
+    destinationPath: string,
+): Promise<void> {
+    await fileSystem.mkdir(destinationPath);
+
+    const entries = await fileSystem.readdir(sourcePath);
+
+    for (const entry of entries) {
+        const sourceEntry = Path.join(sourcePath, entry);
+        const destEntry = Path.join(destinationPath, entry);
+
+        const stat = await fileSystem.stat(sourceEntry);
+        if (stat?.isDirectory()) {
+            await copyDirectoryAsync(fileSystem, sourceEntry, destEntry);
+        } else if (stat?.isFile()) {
+            const content = await fileSystem.readFile(sourceEntry);
+            if (content) {
+                await fileSystem.writeFile(destEntry, content);
+            }
+        }
+    }
+}
+
+/**
+ * Find .nupkg file in a directory
+ */
+export async function findNupkgInFolder(
+    fileSystem: IFileSystem,
+    directoryPath: string,
+): Promise<string | null> {
+    const entries = await fileSystem.readdir(directoryPath);
+
+    for (const entry of entries) {
+        const entryPath = Path.join(directoryPath, entry);
+        const stat = await fileSystem.stat(entryPath);
+
+        if (stat?.isFile() && entry.endsWith(".nupkg")) {
+            return entryPath;
+        }
+
+        if (stat?.isDirectory()) {
+            const found = await findNupkgInFolder(fileSystem, entryPath);
+            if (found) {
+                return found;
+            }
+        }
+    }
+
+    return null;
+}

package/src/utils/manifest-loader.ts

@@ -0,0 +1,34 @@
+import type { IFileSystem } from "@uipath/solutionpackager-tool-core";
+import { Path } from "@uipath/solutionpackager-tool-core";
+import type { WebAppManifest } from "../models/webapp-manifest.js";
+import { WEBAPP_MANIFEST_FILE_NAME } from "../models/webapp-manifest.js";
+
+/**
+ * Load and parse webAppManifest.json from project path
+ */
+export async function loadWebAppManifest(
+    fileSystem: IFileSystem,
+    projectPath: string,
+): Promise<WebAppManifest | null> {
+    const manifestPath = Path.join(projectPath, WEBAPP_MANIFEST_FILE_NAME);
+
+    const exists = await fileSystem.exists(manifestPath);
+    if (!exists) {
+        return null;
+    }
+
+    const content = await fileSystem.readFile(manifestPath);
+    if (!content) {
+        return null;
+    }
+
+    try {
+        const text = new TextDecoder().decode(content);
+        const manifest: WebAppManifest = JSON.parse(text);
+        return manifest;
+    } catch (error) {
+        throw new Error(
+            `Failed to parse ${WEBAPP_MANIFEST_FILE_NAME}: ${error instanceof Error ? error.message : String(error)}`,
+        );
+    }
+}

package/src/webapp-tool-factory.ts

@@ -0,0 +1,23 @@
+import {
+    type IFileSystem,
+    type IProjectToolFactory,
+    type IToolLogger,
+    type ProjectTool,
+    type ProjectType,
+    ProjectTypes,
+} from "@uipath/solutionpackager-tool-core";
+import { WebAppTool } from "./webapp-tool.js";
+
+/**
+ * Factory for creating WebApp project tools
+ */
+export class WebAppToolFactory implements IProjectToolFactory {
+    readonly supportedTypes: readonly ProjectType[] = [ProjectTypes.AppV2];
+
+    async createAsync(
+        logger: IToolLogger,
+        fileSystem: IFileSystem,
+    ): Promise<ProjectTool> {
+        return new WebAppTool(fileSystem, logger);
+    }
+}

package/src/webapp-tool.ts

@@ -0,0 +1,269 @@
+import {
+    type IFileSystem,
+    type IProjectBuildOptions,
+    type IProjectPackOptions,
+    type IProjectRestoreOptions,
+    type IProjectValidateOptions,
+    type IToolLogger,
+    Path,
+    ProjectTool,
+    TemporaryStorageService,
+    ToolErrorCodes,
+    ToolResult,
+} from "@uipath/solutionpackager-tool-core";
+import { ERROR_MESSAGES, PROJECT_JSON_FILE } from "./constants.js";
+import type { WebAppManifest } from "./models/webapp-manifest.js";
+import { WEBAPP_MANIFEST_FILE_NAME } from "./models/webapp-manifest.js";
+import type { VariantStrategy } from "./strategies/variant-strategy.js";
+import { VariantStrategyFactory } from "./strategies/variant-strategy-factory.js";
+import { loadWebAppManifest } from "./utils/manifest-loader.js";
+
+/**
+ * WebApp project tool implementation
+ * Packages WebApp-type projects into .nupkg artifacts
+ */
+export class WebAppTool extends ProjectTool {
+    private readonly _temporaryStorage: TemporaryStorageService;
+    private _tempBuildFolder: string | null = null;
+
+    constructor(fileSystem: IFileSystem, logger: IToolLogger) {
+        super(fileSystem, logger);
+        this._temporaryStorage = new TemporaryStorageService(fileSystem);
+    }
+
+    override async restoreAsync(
+        _options: IProjectRestoreOptions,
+        _cancellationToken?: AbortSignal,
+    ): Promise<ToolResult> {
+        this.logger.info(
+            "Restore operation is not required for WebApp projects",
+        );
+        return ToolResult.success();
+    }
+
+    override async validateAsync(
+        options: IProjectValidateOptions,
+        _cancellationToken?: AbortSignal,
+    ): Promise<ToolResult> {
+        // Input validation
+        if (!options.projectPath) {
+            return this.handleError(
+                new Error(ERROR_MESSAGES.PROJECT_PATH_REQUIRED),
+                "Validation",
+            );
+        }
+
+        try {
+            this.logger.info("Validating WebApp project...");
+
+            // Prepare manifest and strategy (common logic factored out)
+            let manifest: WebAppManifest | undefined;
+            let strategy: VariantStrategy;
+            try {
+                const prepared = await this.getManifestAndStrategy(
+                    options.projectPath,
+                );
+                manifest = prepared.manifest;
+                strategy = prepared.strategy;
+            } catch (error) {
+                return this.handleError(error, "Validation");
+            }
+
+            // Delegate variant-specific validation (may warn or throw)
+            try {
+                if (strategy.validateAsync) {
+                    await strategy.validateAsync({
+                        fileSystem: this.fileSystem,
+                        projectPath: options.projectPath,
+                        manifest,
+                        logger: this.createStrategyLogger(),
+                    });
+                }
+            } catch (error) {
+                return this.handleError(error, "Validation");
+            }
+
+            this.logger.info("WebApp project validation completed");
+            return ToolResult.success();
+        } catch (error) {
+            return this.handleError(error, "Validation");
+        }
+    }
+
+    override async buildAsync(
+        _options: IProjectBuildOptions,
+        _cancellationToken?: AbortSignal,
+    ): Promise<ToolResult> {
+        // For v1, build is lightweight - just prepare metadata structure
+        // Actual build happens via isCompiled=false (future) or external build
+        this.logger.info(
+            "Build operation for WebApp is lightweight (metadata preparation only)",
+        );
+        return ToolResult.success();
+    }
+
+    override async packAsync(
+        options: IProjectPackOptions,
+        _cancellationToken?: AbortSignal,
+    ): Promise<ToolResult> {
+        // Input validation
+        if (!options.projectPath) {
+            return this.handleError(
+                new Error(ERROR_MESSAGES.PROJECT_PATH_REQUIRED),
+                "Packing",
+            );
+        }
+        if (!options.outputPath) {
+            return this.handleError(
+                new Error(ERROR_MESSAGES.OUTPUT_PATH_REQUIRED),
+                "Packing",
+            );
+        }
+        if (!options.package?.id) {
+            return this.handleError(
+                new Error(ERROR_MESSAGES.PACKAGE_NAME_REQUIRED),
+                "Packing",
+            );
+        }
+        if (!options.package?.version) {
+            return this.handleError(
+                new Error(ERROR_MESSAGES.PACKAGE_VERSION_REQUIRED),
+                "Packing",
+            );
+        }
+
+        try {
+            this.logger.info(
+                `Packing WebApp project: ${options.package.id}@${options.package.version}`,
+            );
+
+            // Prepare manifest and strategy (common logic factored out)
+            let manifest: WebAppManifest | undefined;
+            let strategy: VariantStrategy;
+            try {
+                const prepared = await this.getManifestAndStrategy(
+                    options.projectPath,
+                );
+                manifest = prepared.manifest;
+                strategy = prepared.strategy;
+            } catch (error) {
+                return this.handleError(
+                    error,
+                    `Packing WebApp project '${options.package.id}'`,
+                );
+            }
+
+            // Package using strategy
+            const nupkgPath = await strategy.packageAsync({
+                fileSystem: this.fileSystem,
+                projectPath: options.projectPath,
+                manifest,
+                outputPath: options.outputPath,
+                packageInfo: options.package,
+                logger: this.createStrategyLogger(),
+            });
+
+            this.logger.info(
+                `WebApp package created successfully: ${nupkgPath}`,
+            );
+            return new ToolResult(ToolErrorCodes.Success, "done", [nupkgPath]);
+        } catch (error) {
+            return this.handleError(
+                error,
+                `Packing WebApp project '${options.package.id}'`,
+            );
+        }
+    }
+
+    override async dispose(): Promise<void> {
+        this.logger.info("Disposing WebApp Tool");
+        try {
+            if (this._tempBuildFolder) {
+                await this.fileSystem.rm(this._tempBuildFolder);
+                this._tempBuildFolder = null;
+            }
+            await this._temporaryStorage.cleanup();
+        } catch {
+            // Ignore errors during cleanup
+        }
+    }
+
+    /**
+     * 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 async getManifestAndStrategy(
+        projectPath: string,
+    ): Promise<{ manifest: WebAppManifest; strategy: VariantStrategy }> {
+        // Check manifest existence
+        const manifestPath = Path.join(projectPath, WEBAPP_MANIFEST_FILE_NAME);
+        const manifestExists = await this.fileSystem.exists(manifestPath);
+
+        if (!manifestExists) {
+            throw new Error(
+                ERROR_MESSAGES.MANIFEST_NOT_FOUND(WEBAPP_MANIFEST_FILE_NAME),
+            );
+        }
+
+        // Ensure this is a WebApp project: project.json must NOT exist
+        const projectJsonPath = Path.join(projectPath, PROJECT_JSON_FILE);
+        if (await this.fileSystem.exists(projectJsonPath)) {
+            throw new Error(ERROR_MESSAGES.PROJECT_JSON_FOUND);
+        }
+
+        // Load manifest and ensure it's valid
+        const manifest = await loadWebAppManifest(this.fileSystem, projectPath);
+        if (!manifest) {
+            throw new Error(
+                ERROR_MESSAGES.MANIFEST_LOAD_FAILED(WEBAPP_MANIFEST_FILE_NAME),
+            );
+        }
+
+        // Create strategy (will throw if unsupported)
+        const strategy = VariantStrategyFactory.createStrategy(
+            manifest,
+            this.fileSystem,
+        );
+
+        return { manifest, strategy };
+    }
+
+    /**
+     * Standardized error handling helper
+     */
+    private handleError(error: unknown, context: string): ToolResult {
+        const errorMessage =
+            error instanceof Error ? error.message : String(error);
+        this.logger.error(`${context}: ${errorMessage}`);
+
+        // Use appropriate error message based on context
+        let userMessage: string;
+        if (context === "Validation") {
+            userMessage = ERROR_MESSAGES.VALIDATION_FAILED(errorMessage);
+        } else if (context.startsWith("Packing")) {
+            userMessage = ERROR_MESSAGES.PACKING_FAILED(errorMessage);
+        } else {
+            userMessage = errorMessage;
+        }
+
+        return ToolResult.error(ToolErrorCodes.InternalError, userMessage);
+    }
+
+    /**
+     * Create a logger wrapper for strategy methods
+     */
+    private createStrategyLogger(): {
+        info: (message: string) => void;
+        error: (message: string) => void;
+        progress: (message: string) => void;
+        warn: (message: string) => void;
+    } {
+        return {
+            info: (msg: string) => this.logger.info(msg),
+            error: (msg: string) => this.logger.error(msg),
+            progress: (msg: string) => this.logger.progress(msg),
+            warn: (msg: string) => this.logger.warn(msg),
+        };
+    }
+}