@uipath/solutionpackager-tool-core 0.0.26

package/README.md

@@ -0,0 +1,308 @@
+# UiPath Solution Packager Tool Core
+
+Core contracts and interfaces for building UiPath Solution Packager tools. This package provides the type definitions and base classes for creating tools that restore, validate, build, and pack UiPath projects and solutions.
+
+## Installation
+
+### From GitHub Packages
+
+#### Prerequisites
+
+Create a GitHub Personal Access Token with `read:packages` permission:
+
+1. Go to GitHub → Settings → Developer settings → Personal access tokens → Tokens (classic)
+2. Generate new token with `read:packages` scope
+3. Set as environment variable:
+
+**Windows (PowerShell):**
+
+```powershell
+$env:GH_NPM_REGISTRY_TOKEN = "your-token-here"
+```
+
+**Linux/macOS:**
+
+```bash
+export GH_NPM_REGISTRY_TOKEN="your-token-here"
+```
+
+#### Install
+
+Create `.npmrc` in your project root:
+
+```text
+@uipath:registry=https://npm.pkg.github.com/
+//npm.pkg.github.com/:_authToken=${GH_NPM_REGISTRY_TOKEN}
+```
+
+Then install:
+
+```bash
+npm install @uipath/solutionpackager-tool-core
+```
+
+## Quick Start
+
+### 1. Implement a Project Tool
+
+Extend `ProjectTool` and override the operations you need:
+
+```typescript
+import {
+  ProjectTool,
+  type IProjectBuildOptions,
+  type IProjectRestoreOptions,
+  ToolResult,
+  type IToolLogger,
+  type IFileSystem,
+  Path,
+} from "@uipath/solutionpackager-tool-core";
+
+export class ApiWorkflowsTool extends ProjectTool {
+  constructor(fileSystem: IFileSystem, logger: IToolLogger) {
+    super(fileSystem, logger);
+  }
+
+  override async restoreAsync(
+    options: IProjectRestoreOptions,
+    cancellationToken?: AbortSignal
+  ): Promise<ToolResult> {
+    this.logger.info("Restoring dependencies...");
+    return ToolResult.success();
+  }
+
+  override async buildAsync(
+    options: IProjectBuildOptions,
+    cancellationToken?: AbortSignal
+  ): Promise<ToolResult> {
+    this.logger.info("Building project...");
+    const outputFolder = Path.join(options.outputPath, "output");
+
+    await this.fileSystem.mkdir(outputFolder);
+    await this.fileSystem.writeFile(
+      Path.join(outputFolder, "artifact.txt"),
+      "Build Artifact"
+    );
+
+    return new ToolResult(ToolErrorCodes.Success, "Build completed", [outputFolder]);
+  }
+
+  override async dispose(): Promise<void> {
+    // Cleanup resources
+  }
+}
+```
+
+### 2. Create a Tool Factory
+
+Implement `IProjectToolFactory`:
+
+```typescript
+import {
+  type IProjectToolFactory,
+  type ProjectTool,
+  ProjectTypes,
+  type ProjectType,
+  type IToolLogger,
+  type IFileSystem,
+} from "@uipath/solutionpackager-tool-core";
+
+export class ApiWorkflowToolFactory implements IProjectToolFactory {
+  readonly supportedTypes: readonly ProjectType[] = [ProjectTypes.Api];
+
+  constructor(private readonly fileSystem: IFileSystem) {}
+
+  async createAsync(logger: IToolLogger): Promise<ProjectTool> {
+    return new ApiWorkflowsTool(this.fileSystem, logger);
+  }
+}
+```
+
+### 3. Register Your Tool
+
+Register with the SolutionPackager instance:
+
+```typescript
+import type { IToolsFactoryRepositoryConfigurator } from "@uipath/solutionpackager-tool-core";
+
+export function registerProjectToolFactory(
+  configurator: IToolsFactoryRepositoryConfigurator,
+  fileSystem: IFileSystem
+): void {
+  configurator.registerProjectToolFactory(
+    new ApiWorkflowToolFactory(fileSystem)
+  );
+}
+
+// Usage:
+// const solutionPackager = await createBrowserSolutionPackager();
+// registerApiWorkflowTool(solutionPackager, solutionPackager.fileSystem);
+```
+
+## Core Concepts
+
+### Tool Base Classes
+
+**ProjectTool** - Override operations your tool supports:
+
+- `restoreAsync()` - Restore dependencies
+- `validateAsync()` - Validate project
+- `buildAsync()` - Build/compile
+- `packAsync()` - Package project
+- `dispose()` - Cleanup
+
+**SolutionTool** - Similar to ProjectTool but operates at solution level.
+
+### Logging
+
+Access logger via `this.logger`:
+
+```typescript
+this.logger.info("Starting build");
+this.logger.progress("Building", 50);
+this.logger.warn("Deprecated API");
+this.logger.error("Build failed", { code: "BUILD_001" });
+```
+
+### File System
+
+Access via `this.fileSystem` with consistent API across Node.js and Browser:
+
+```typescript
+// Read file
+const content = await this.fileSystem.readFile("path/to/file.json");
+
+// Write file
+await this.fileSystem.writeFile("output/config.xml", "<config></config>");
+
+// Create directory (recursive)
+await this.fileSystem.mkdir("dist/assets/images");
+
+// Check existence
+if (await this.fileSystem.exists("entrypoints.json")) { }
+
+// List directory
+const files = await this.fileSystem.readdir("src/components");
+
+// Delete (recursive for directories)
+await this.fileSystem.rm("temp_build");
+```
+
+### Tool Results
+
+```typescript
+// Success
+return ToolResult.success();
+
+// Error with code and message
+return ToolResult.error(ToolErrorCodes.InternalError, "Syntax error");
+
+// With package paths
+return new ToolResult(ToolErrorCodes.Success, "done", [packagePath]);
+```
+
+## Built-in Types
+
+### Project Types
+
+- `ProjectTypes.Agent`
+- `ProjectTypes.Api`
+- `ProjectTypes.Connector`
+- `ProjectTypes.Process`
+- `ProjectTypes.Library`
+- `ProjectTypes.WebApp`
+- `ProjectTypes.Tests`
+
+### Error Codes
+
+- `ToolErrorCodes.Success`
+- `ToolErrorCodes.InternalError`
+
+Extend with custom codes:
+
+```typescript
+type MyToolErrorCode = ToolErrorCode | "COMPILATION_FAILED" | "VALIDATION_ERROR";
+```
+
+## Utilities
+
+### Path Utilities
+
+```typescript
+import { Path } from "@uipath/solutionpackager-tool-core";
+const fullPath = Path.join(basePath, "subfolder", "file.json");
+```
+
+### NuGet Constants
+
+```typescript
+import { NugetConstants } from "@uipath/solutionpackager-tool-core";
+
+NugetConstants.OutputFolderName;           // "bundle"
+NugetConstants.ContentFolderName;          // "content"
+NugetConstants.OperateFileName;            // "operate.json"
+NugetConstants.EntryPointsFileName;        // "entrypoints.json"
+NugetConstants.PackageDescriptorFileName;  // "package-descriptor.json"
+```
+
+## Architecture
+
+```text
+┌─────────────────────────────────────────────────────────────┐
+│              tool.core (contracts)                          │
+│  IToolLogger  IFileSystem  ProjectTool  SolutionTool        │
+└─────────────────────────────────────────────────────────────┘
+                          ▲
+          implements/uses │
+┌─────────────────────────┼───────────────────────────────────┐
+│              solutionpackager                               │
+│  ToolLogger  FileSystem  ToolsFactory            │
+└─────────────────────────────────────────────────────────────┘
+```
+
+1. `tool.core` provides interfaces and base classes
+2. Tools implement interfaces and register factories
+3. SolutionPackager discovers and creates tool instances
+4. Tools execute operations with injected logger and file system
+
+## Development
+
+```bash
+# Build
+npm run build
+
+# Run tests
+npm test
+
+# Pack
+npm pack
+
+# Publish
+npm publish
+```
+
+## Troubleshooting
+
+### Installation Issues
+
+**404 Not Found:**
+
+- Verify package exists at <https://github.com/orgs/UiPath/packages>
+- Check `GH_NPM_REGISTRY_TOKEN` environment variable is set
+- Ensure token has `read:packages` permission
+
+**401 Unauthorized:**
+
+- Verify token hasn't expired
+- Check environment variable: `echo $env:GH_NPM_REGISTRY_TOKEN` (Windows) or `echo $GH_NPM_REGISTRY_TOKEN` (Linux/macOS)
+
+## Examples
+
+See `@uipath/tool-apiworkflow` for a complete reference implementation.
+
+## Package Information
+
+- **Registry:** GitHub Packages (npm)
+- **Organization:** UiPath
+- **Package:** `@uipath/solutionpackager-tool-core`
+- **Repository:** <https://github.com/UiPath/Studio.Common>

package/dist/filesystem/file-system.d.ts

@@ -0,0 +1 @@
+export type { FileSystemStats, IFileSystem } from "@uipath/filesystem";

package/dist/filesystem/index.d.ts

@@ -0,0 +1,5 @@
+export type { FileSystemStats, IFileSystem } from "./file-system.js";
+export type { FileEntry } from "./path.js";
+export { Path } from "./path.js";
+export { type ITemporaryStorageService, TemporaryStorageService, } from "./temporary-storage-service.js";
+export { type IZipService, ZipService } from "./zip-service.js";

package/dist/filesystem/index.js

@@ -0,0 +1,3 @@
+export { Path } from "./path.js";
+export { TemporaryStorageService } from "./temporary-storage-service.js";
+export { ZipService } from "./zip-service.js";

package/dist/filesystem/path.d.ts

@@ -0,0 +1,53 @@
+import type { IFileSystem } from "./file-system.js";
+/**
+ * Represents a file entry with relative and absolute paths
+ */
+export interface FileEntry {
+    /**
+     * Path relative to the root directory
+     */
+    relativePath: string;
+    /**
+     * Absolute path in the filesystem
+     */
+    absolutePath: string;
+}
+/**
+ * Platform-independent path utilities
+ */
+export declare class Path {
+    /**
+     * Normalize path separators to forward slashes (ZIP standard)
+     */
+    static normalize(path: string): string;
+    /**
+     * Join path segments with forward slashes
+     */
+    static join(...segments: string[]): string;
+    /**
+     * Get the directory name of a path (platform-independent)
+     * @param path - The file path
+     * @returns The directory path, or '.' if no directory
+     */
+    static dirname(path: string): string;
+    /**
+     * Get the base name (filename) of a path (platform-independent)
+     * @param path - The file path
+     * @returns The filename portion of the path
+     */
+    static basename(path: string): string;
+    /**
+     * Get the extension of a path (platform-independent)
+     * @param path - The file path
+     * @returns The extension including the dot (e.g., '.txt'), or empty string if no extension
+     */
+    static extname(path: string): string;
+    /**
+     * Recursively walk a directory and return all files
+     * @param fs - FileSystem implementation
+     * @param rootPath - Root directory to walk
+     * @param currentRelativePath - Current relative path (used internally for recursion)
+     * @returns Array of file entries with relative and absolute paths
+     */
+    static walkDirectory(fs: IFileSystem, rootPath: string, currentRelativePath?: string): Promise<FileEntry[]>;
+}

package/dist/filesystem/path.js

@@ -0,0 +1,47 @@
+class Path {
+    static normalize(path) {
+        return path.replace(/\\/g, "/").replace(/\/+/g, "/");
+    }
+    static join(...segments) {
+        return Path.normalize(segments.filter((s)=>s.length > 0).join("/"));
+    }
+    static dirname(path) {
+        const normalized = Path.normalize(path).replace(/\/$/, "");
+        if ("" === normalized) return ".";
+        const lastSlash = normalized.lastIndexOf("/");
+        if (-1 === lastSlash) return ".";
+        if (0 === lastSlash) return "/";
+        return normalized.substring(0, lastSlash);
+    }
+    static basename(path) {
+        const normalized = Path.normalize(path).replace(/\/$/, "");
+        if ("" === normalized) return "";
+        const lastSlash = normalized.lastIndexOf("/");
+        return lastSlash >= 0 ? normalized.substring(lastSlash + 1) : normalized;
+    }
+    static extname(path) {
+        const base = Path.basename(path);
+        const lastDot = base.lastIndexOf(".");
+        if (-1 === lastDot || 0 === lastDot || lastDot === base.length - 1) return "";
+        return base.substring(lastDot);
+    }
+    static async walkDirectory(fs, rootPath, currentRelativePath = "") {
+        const entries = [];
+        const absolutePath = currentRelativePath ? Path.join(rootPath, currentRelativePath) : rootPath;
+        const items = await fs.readdir(absolutePath);
+        for (const item of items){
+            const itemRelativePath = currentRelativePath ? Path.join(currentRelativePath, item) : item;
+            const itemAbsolutePath = Path.join(rootPath, itemRelativePath);
+            const stat = await fs.stat(itemAbsolutePath);
+            if (stat?.isDirectory()) {
+                const subEntries = await Path.walkDirectory(fs, rootPath, itemRelativePath);
+                entries.push(...subEntries);
+            } else if (stat?.isFile()) entries.push({
+                relativePath: Path.normalize(itemRelativePath),
+                absolutePath: Path.normalize(itemAbsolutePath)
+            });
+        }
+        return entries;
+    }
+}
+export { Path };

package/dist/filesystem/temporary-storage-service.d.ts

@@ -0,0 +1,31 @@
+import type { IFileSystem } from "./file-system.js";
+/**
+ * Service for managing temporary storage.
+ */
+export interface ITemporaryStorageService {
+    /**
+     * Ensure temp folder is initialized and get its path.
+     */
+    getTempFolderPath(): Promise<string>;
+    /**
+     * Ensure subfolder in temp folder is initialized and get its path.
+     */
+    getTempSubfolderPathAsync(subfolder: string): Promise<string>;
+    /**
+     * Delete the temporary directory
+     */
+    cleanup(): Promise<void>;
+}
+export declare class TemporaryStorageService implements ITemporaryStorageService {
+    private readonly fileSystem;
+    private _tempFolderPath;
+    constructor(fileSystem: IFileSystem);
+    getTempFolderPath(): Promise<string>;
+    /**
+     * Generate a unique folder name using timestamp and random string
+     * Format: tool-temp-{timestamp}-{random}
+     */
+    private generateUniqueFolderName;
+    getTempSubfolderPathAsync(subfolder: string): Promise<string>;
+    cleanup(): Promise<void>;
+}

package/dist/filesystem/temporary-storage-service.js

@@ -0,0 +1,46 @@
+import { Path } from "./path.js";
+class TemporaryStorageService {
+    fileSystem;
+    _tempFolderPath = null;
+    constructor(fileSystem){
+        this.fileSystem = fileSystem;
+    }
+    async getTempFolderPath() {
+        if (!this._tempFolderPath) {
+            const systemTempDir = await this.fileSystem.getTempDir();
+            const uniqueFolderName = this.generateUniqueFolderName();
+            this._tempFolderPath = Path.join(systemTempDir, uniqueFolderName);
+            await this.fileSystem.mkdir(this._tempFolderPath);
+        }
+        return this._tempFolderPath;
+    }
+    generateUniqueFolderName() {
+        const timestamp = Date.now();
+        const random = Math.random().toString(36).substring(2, 10);
+        return `tool-temp-${timestamp}-${random}`;
+    }
+    async getTempSubfolderPathAsync(subfolder) {
+        const tempFolderPath = await this.getTempFolderPath();
+        const inputPath = Path.join(tempFolderPath, subfolder);
+        await this.fileSystem.mkdir(inputPath);
+        return inputPath;
+    }
+    async cleanup() {
+        try {
+            if (!this._tempFolderPath) return;
+            try {
+                const stats = await this.fileSystem.stat(this._tempFolderPath);
+                if (!stats) return;
+            } catch  {
+                return;
+            }
+            const pathToCleanup = this._tempFolderPath;
+            await this.fileSystem.rm(this._tempFolderPath);
+            this._tempFolderPath = null;
+            console.info(`Cleaned up temp folder: ${pathToCleanup}`);
+        } catch (error) {
+            console.error("Error during cleanup:", error);
+        }
+    }
+}
+export { TemporaryStorageService };

package/dist/filesystem/zip-service.d.ts

@@ -0,0 +1,25 @@
+import type { IFileSystem } from "./file-system.js";
+/**
+ * Interface for zip compression and extraction operations
+ */
+export interface IZipService {
+    /**
+     * Extract a zip archive to a directory
+     * @param zipData The raw zip archive data
+     * @param targetPath The directory path to extract files to
+     * @returns List of extracted file paths
+     */
+    extractAsync(zipData: Uint8Array, targetPath: string): Promise<string[]>;
+    /**
+     * Create a zip archive from a directory
+     * @param sourcePath The directory path to compress
+     * @returns The compressed zip data
+     */
+    compressAsync(sourcePath: string): Promise<Uint8Array>;
+}
+export declare class ZipService implements IZipService {
+    private readonly fileSystem;
+    constructor(fileSystem: IFileSystem);
+    extractAsync(zipData: Uint8Array, targetPath: string): Promise<string[]>;
+    compressAsync(sourcePath: string): Promise<Uint8Array>;
+}

package/dist/filesystem/zip-service.js

@@ -0,0 +1,41 @@
+import { unzipSync, zipSync } from "fflate";
+import { Path } from "./path.js";
+class ZipService {
+    fileSystem;
+    constructor(fileSystem){
+        this.fileSystem = fileSystem;
+    }
+    async extractAsync(zipData, targetPath) {
+        const normalizedTarget = targetPath.replace(/\/$/, "");
+        await this.fileSystem.mkdir(normalizedTarget);
+        const files = unzipSync(zipData);
+        const extractedPaths = [];
+        for (const [relativePath, data] of Object.entries(files)){
+            if (relativePath.endsWith("/") || 0 === data.length) {
+                const dirPath = `${normalizedTarget}/${relativePath.replace(/\/$/, "")}`;
+                await this.fileSystem.mkdir(dirPath);
+                continue;
+            }
+            const fullPath = `${normalizedTarget}/${relativePath}`;
+            const parentDir = fullPath.split("/").slice(0, -1).join("/");
+            if (parentDir) await this.fileSystem.mkdir(parentDir);
+            await this.fileSystem.writeFile(fullPath, data);
+            extractedPaths.push(fullPath);
+        }
+        return extractedPaths;
+    }
+    async compressAsync(sourcePath) {
+        const normalizedSource = sourcePath.replace(/\/$/, "");
+        const entries = await Path.walkDirectory(this.fileSystem, normalizedSource);
+        const zippable = {};
+        for (const entry of entries){
+            const fileData = await this.fileSystem.readFile(entry.absolutePath);
+            if (fileData) zippable[entry.relativePath] = fileData;
+        }
+        const zipData = zipSync(zippable, {
+            level: 6
+        });
+        return zipData;
+    }
+}
+export { ZipService };