@pipelab/core-node 1.0.0-beta.12 → 1.0.0-beta.14

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pipelab/core-node",
-  "version": "1.0.0-beta.12",
+  "version": "1.0.0-beta.14",
   "private": false,
   "description": "The Pipelab automation engine for Node.js",
   "license": "FSL-1.1-MIT",
@@ -40,8 +40,8 @@
     "type-fest": "4.39.0",
     "ws": "8.18.3",
     "yauzl": "2.10.0",
-    "@pipelab/constants": "1.0.0-beta.10",
-    "@pipelab/shared": "1.0.0-beta.8"
+    "@pipelab/constants": "1.0.0-beta.12",
+    "@pipelab/shared": "1.0.0-beta.10"
   },
   "devDependencies": {
     "@types/adm-zip": "0.5.7",
@@ -52,13 +52,17 @@
     "@types/tar": "7.0.87",
     "@types/ws": "8.18.1",
     "@types/yauzl": "2.10.3",
+    "memfs": "4.57.6",
     "tsdown": "0.21.2",
     "typescript": "^5.0.0",
-    "@pipelab/tsconfig": "1.0.0-beta.8"
+    "vitest": "3.1.4",
+    "@pipelab/tsconfig": "1.0.0-beta.10"
   },
   "scripts": {
     "build": "tsdown",
     "format": "oxfmt .",
-    "lint": "oxlint ."
+    "lint": "oxlint .",
+    "typecheck": "tsc -b",
+    "test": "vitest run"
   }
 }

package/src/config.test.ts

@@ -0,0 +1,176 @@
+import { describe, test, expect, beforeEach, vi } from "vitest";
+import { setupConfigFile } from "./config";
+import { FileRepo } from "@pipelab/shared";
+import { PipelabContext } from "./context";
+import fs from "node:fs/promises";
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { vol } from "memfs";
+
+// Mock the node:fs and node:fs/promises modules to use memfs
+vi.mock("node:fs", async () => {
+  const memfs = await import("memfs");
+  return {
+    ...memfs.fs,
+    default: memfs.fs,
+  };
+});
+
+vi.mock("node:fs/promises", async () => {
+  const memfs = await import("memfs");
+  return {
+    ...memfs.fs.promises,
+    default: memfs.fs.promises,
+  };
+});
+
+describe("setupConfigFile & Backup Creation", () => {
+  let tempDir: string;
+  let context: PipelabContext;
+
+  beforeEach(() => {
+    vol.reset();
+    tempDir = "/tmp/pipelab-test-config";
+    context = new PipelabContext({ userDataPath: tempDir });
+  });
+
+  test("should migrate config and create backup files on disk", async () => {
+    // 1. Setup V1 configuration file in the context's config path
+    const configDir = context.getConfigPath();
+    await fs.mkdir(configDir, { recursive: true });
+    
+    const projectsFilePath = path.join(configDir, "projects.json");
+    
+    const v1Config = {
+      version: "1.0.0",
+      data: {
+        "pipeline-1": {
+          project: "main",
+          type: "internal",
+          configName: "pipeline-1",
+          lastModified: "2026-06-04",
+        }
+      }
+    };
+    
+    await fs.writeFile(projectsFilePath, JSON.stringify(v1Config));
+
+    // 2. Initialize setupConfigFile
+    const configInstance = await setupConfigFile<FileRepo>("projects", { context });
+
+    // Verify file exists
+    expect(existsSync(projectsFilePath)).toBe(true);
+
+    // 3. Retrieve config (this triggers the migration process and onStep callback)
+    const migratedConfig = await configInstance.getConfig();
+
+    // 4. Assert the main config is updated on disk to version 2.0.0
+    expect(migratedConfig.version).toBe("2.0.0");
+    
+    const updatedContent = JSON.parse(await fs.readFile(projectsFilePath, "utf8"));
+    expect(updatedContent.version).toBe("2.0.0");
+
+    // 5. Assert that the intermediate backup file was created on disk
+    const backupFilePath = path.join(configDir, "projects.v2.0.0.json");
+    expect(existsSync(backupFilePath)).toBe(true);
+
+    const backupContent = JSON.parse(await fs.readFile(backupFilePath, "utf8"));
+    expect(backupContent.version).toBe("2.0.0");
+    expect(backupContent.projects).toHaveLength(1);
+    expect(backupContent.pipelines).toHaveLength(1);
+  });
+
+  test("should create default config file if missing on setup", async () => {
+    const configDir = context.getConfigPath();
+    const projectsFilePath = path.join(configDir, "projects.json");
+
+    expect(existsSync(projectsFilePath)).toBe(false);
+
+    // Initialize setupConfigFile
+    await setupConfigFile<FileRepo>("projects", { context });
+
+    // Should create file with default value
+    expect(existsSync(projectsFilePath)).toBe(true);
+    const content = JSON.parse(await fs.readFile(projectsFilePath, "utf8"));
+    expect(content.version).toBe("2.0.0");
+    expect(content.projects).toHaveLength(1);
+    expect(content.pipelines).toEqual([]);
+  });
+
+  test("should fallback to default config and preserve corrupted file if parsing fails", async () => {
+    const configDir = context.getConfigPath();
+    await fs.mkdir(configDir, { recursive: true });
+    const projectsFilePath = path.join(configDir, "projects.json");
+
+    await fs.writeFile(projectsFilePath, "{ corrupted json... }");
+
+    const configInstance = await setupConfigFile<FileRepo>("projects", { context });
+    const config = await configInstance.getConfig();
+
+    expect(config.version).toBe("2.0.0");
+    expect(config.projects).toHaveLength(1);
+    expect(config.pipelines).toEqual([]);
+
+    // Verify a timestamped corrupted backup file exists
+    const files = await fs.readdir(configDir);
+    const corruptedFile = files.find(f => f.startsWith("projects.corrupted.") && f.endsWith(".json"));
+    expect(corruptedFile).toBeDefined();
+    const corruptedContent = await fs.readFile(path.join(configDir, corruptedFile!), "utf8");
+    expect(corruptedContent).toBe("{ corrupted json... }");
+  });
+
+  test("should fallback to default config and preserve file if migration throws", async () => {
+    const configDir = context.getConfigPath();
+    await fs.mkdir(configDir, { recursive: true });
+    const projectsFilePath = path.join(configDir, "projects.json");
+
+    const customMigrator = {
+      defaultValue: { version: "2.0.0", projects: [], pipelines: [] } as any,
+      migrate: async () => {
+        throw new Error("Migration failed!");
+      },
+    };
+
+    await fs.writeFile(projectsFilePath, JSON.stringify({ version: "1.0.0", invalidData: true }));
+
+    const configInstance = await setupConfigFile<any>("projects", {
+      context,
+      migrator: customMigrator,
+    });
+    const config = await configInstance.getConfig();
+
+    expect(config.version).toBe("2.0.0");
+
+    // Verify a timestamped corrupted backup file exists
+    const files = await fs.readdir(configDir);
+    const corruptedFile = files.find(f => f.startsWith("projects.corrupted.") && f.endsWith(".json"));
+    expect(corruptedFile).toBeDefined();
+    const corruptedContent = JSON.parse(await fs.readFile(path.join(configDir, corruptedFile!), "utf8"));
+    expect(corruptedContent.invalidData).toBe(true);
+  });
+
+  test("should save config to disk via setConfig", async () => {
+    const configInstance = await setupConfigFile<FileRepo>("projects", { context });
+    const initialConfig = await configInstance.getConfig();
+
+    const newConfig: FileRepo = {
+      ...initialConfig,
+      pipelines: [
+        {
+          id: "pipeline-new",
+          project: "main",
+          type: "internal",
+          configName: "pipeline-new",
+          lastModified: "2026-06-05",
+        },
+      ],
+    };
+
+    const success = await configInstance.setConfig(newConfig);
+    expect(success).toBe(true);
+
+    const savedContent = JSON.parse(await fs.readFile(path.join(context.getConfigPath(), "projects.json"), "utf8"));
+    expect(savedContent.pipelines).toHaveLength(1);
+    expect(savedContent.pipelines[0].id).toBe("pipeline-new");
+  });
+});

package/src/config.ts

@@ -6,15 +6,7 @@ import { useLogger } from "@pipelab/shared";
 import { configRegistry, Migrator, normalizePipelineConfig } from "@pipelab/shared";
 
 export const getMigrator = <T>(name: string) => {
-  if (configRegistry[name]) {
-    return configRegistry[name] as Migrator<T>;
-  }
-
-  if (name.startsWith("pipeline-") || path.isAbsolute(name) || name.endsWith(".json")) {
-    return configRegistry["pipeline"] as Migrator<T>;
-  }
-
-  return undefined;
+  return (configRegistry[name] || configRegistry["pipeline"]) as Migrator<T>;
 };
 
 export const setupConfigFile = async <T>(
@@ -63,22 +55,28 @@ export const setupConfigFile = async <T>(
       }
 
       let json: any = undefined;
+      let migrationFailed = false;
       try {
-        json = await migrator.migrate(originalJson, {
-          debug: false,
-          onStep: async (state: any, version: string) => {
-            const parsedPath = path.parse(filesPath);
-            const versionedPath = path.join(parsedPath.dir, `${parsedPath.name}.v${version}.json`);
-            try {
-              await fs.writeFile(versionedPath, JSON.stringify(state));
-              logger().info(`Intermediate backup created for ${name} at ${versionedPath}`);
-            } catch (e) {
-              logger().error(`Failed to create intermediate backup for ${name} at v${version}:`, e);
-            }
-          },
-        });
+        if (!parseFailed) {
+          json = await migrator.migrate(originalJson, {
+            debug: false,
+            onStep: async (state: any, version: string) => {
+              const parsedPath = path.parse(filesPath);
+              const versionedPath = path.join(parsedPath.dir, `${parsedPath.name}.v${version}.json`);
+              try {
+                await fs.writeFile(versionedPath, JSON.stringify(state));
+                logger().info(`Intermediate backup created for ${name} at ${versionedPath}`);
+              } catch (e) {
+                logger().error(`Failed to create intermediate backup for ${name} at v${version}:`, e);
+              }
+            },
+          });
+        } else {
+          json = migrator.defaultValue;
+        }
       } catch (e) {
         logger().error(`Error migrating config ${name}:`, e);
+        migrationFailed = true;
         json = migrator.defaultValue;
       }
 
@@ -95,8 +93,30 @@ export const setupConfigFile = async <T>(
       const originalVersion = originalJson?.version;
       const newVersion = json?.version;
 
-      // Save back migrated config if changed, if normalized, if it's a new file, or if parse failed
-      if (originalVersion !== newVersion || normalized || content === undefined || parseFailed) {
+      const shouldSaveBack =
+        originalVersion !== newVersion ||
+        normalized ||
+        content === undefined ||
+        parseFailed ||
+        migrationFailed;
+
+      if (shouldSaveBack) {
+        if (parseFailed || migrationFailed) {
+          try {
+            const parsedPath = path.parse(filesPath);
+            const timestamp = new Date().toISOString().replace(/[:.]/g, "-");
+            const corruptedPath = path.join(
+              parsedPath.dir,
+              `${parsedPath.name}.corrupted.${timestamp}.json`,
+            );
+            const backupContent = parseFailed ? (content || "") : JSON.stringify(originalJson, null, 2);
+            await fs.writeFile(corruptedPath, backupContent);
+            logger().info(`Corrupted config file preserved at ${corruptedPath}`);
+          } catch (e) {
+            logger().error(`Failed to backup corrupted config ${name}:`, e);
+          }
+        }
+
         try {
           await fs.writeFile(filesPath, JSON.stringify(json));
         } catch (e) {

package/src/context.ts

@@ -2,12 +2,17 @@ import { join, dirname, resolve } from "node:path";
 import { homedir, platform } from "node:os";
 import { fileURLToPath } from "node:url";
 import { existsSync } from "node:fs";
+import { mkdir, realpath, mkdtemp } from "node:fs/promises";
+import { SandboxFolder, DEFAULT_NODE_VERSION, DEFAULT_PNPM_VERSION } from "@pipelab/constants";
+
+// @ts-ignore import.meta is only allowed in ES Modules
+const metaUrl = typeof import.meta !== "undefined" ? import.meta.url : undefined;
 
 const _dirname =
   typeof __dirname !== "undefined"
     ? __dirname
-    : typeof import.meta !== "undefined" && import.meta.url
-      ? dirname(fileURLToPath(import.meta.url))
+    : metaUrl
+      ? dirname(fileURLToPath(metaUrl))
       : process.cwd();
 
 export const isDev = process.env.NODE_ENV === "development";
@@ -71,4 +76,48 @@ export class PipelabContext {
   getConfigPath(...subpaths: string[]) {
     return join(this.userDataPath, "config", ...subpaths);
   }
+
+  getTempPath(...subpaths: string[]) {
+    return join(this.userDataPath, "temp", ...subpaths);
+  }
+
+  async createTempFolder(prefix = "pipelab-") {
+    const baseDir = this.getTempPath();
+    await mkdir(baseDir, { recursive: true });
+    const realBaseDir = await realpath(baseDir);
+    return await mkdtemp(join(realBaseDir, prefix));
+  }
+
+  getCachePath(...subpaths: string[]) {
+    return join(this.userDataPath, "cache", ...subpaths);
+  }
+
+  getPnpmPath(...subpaths: string[]) {
+    return join(this.userDataPath, "pnpm", ...subpaths);
+  }
+
+  getNodePath(version = DEFAULT_NODE_VERSION) {
+    const isWindows = process.platform === "win32";
+    return this.getThirdPartyPath("node", version, isWindows ? "node.exe" : "bin/node");
+  }
+
+  getPnpmBinPath(version = DEFAULT_PNPM_VERSION) {
+    return this.getPackagesPath("pnpm", version, "bin", "pnpm.cjs");
+  }
+
+  getSandboxFolders(): Array<{ name: SandboxFolder; label: string; path: string }> {
+    const foldersRecord: Record<SandboxFolder, { label: string; path: string }> = {
+      [SandboxFolder.Packages]: { label: "Packages", path: this.getPackagesPath() },
+      [SandboxFolder.ThirdParty]: { label: "Third-Party Tools", path: this.getThirdPartyPath() },
+      [SandboxFolder.Config]: { label: "Configuration", path: this.getConfigPath() },
+      [SandboxFolder.Temp]: { label: "Temporary Files", path: this.getTempPath() },
+      [SandboxFolder.Cache]: { label: "Cache", path: this.getCachePath() },
+      [SandboxFolder.Pnpm]: { label: "PNPM Home", path: this.getPnpmPath() },
+    };
+
+    return (Object.keys(foldersRecord) as SandboxFolder[]).map((key) => ({
+      name: key,
+      ...foldersRecord[key],
+    }));
+  }
 }

package/src/handlers/build-history.ts

@@ -1,11 +1,11 @@
 import { PipelabContext } from "../context";
 import { join } from "node:path";
 import { writeFile, readFile, unlink, mkdir, stat, readdir } from "node:fs/promises";
-import { tmpdir } from "node:os";
 import { useLogger, BuildHistoryEntry, IBuildHistoryStorage, AppConfig } from "@pipelab/shared";
 import { setupConfigFile } from "../config";
 import checkDiskSpace from "check-disk-space";
 import { getFolderSize } from "../utils/fs-extras";
+import { SandboxFolder } from "@pipelab/constants";
 
 // Simplified storage - one file per pipeline containing array of build entries
 
@@ -294,6 +294,7 @@ export class BuildHistoryStorage implements IBuildHistoryStorage {
       total: number;
       free: number;
       pipelab: number;
+      folders: Array<{ name: SandboxFolder; label: string; size: number }>;
     };
   }> {
     try {
@@ -303,6 +304,16 @@ export class BuildHistoryStorage implements IBuildHistoryStorage {
       const diskSpace = await checkDiskSpace(this.context.userDataPath);
       const pipelabSize = await getFolderSize(this.context.userDataPath);
 
+      const folders = [];
+      for (const folder of this.context.getSandboxFolders()) {
+        const size = await getFolderSize(folder.path);
+        folders.push({
+          name: folder.name,
+          label: folder.label,
+          size,
+        });
+      }
+
       const settings = await setupConfigFile<AppConfig>("settings", { context: this.context });
       const config = await settings.getConfig();
       const policy = config?.buildHistory?.retentionPolicy || {
@@ -326,6 +337,7 @@ export class BuildHistoryStorage implements IBuildHistoryStorage {
             total: diskSpace.size,
             free: diskSpace.free,
             pipelab: pipelabSize,
+            folders,
           },
         };
       }
@@ -359,6 +371,7 @@ export class BuildHistoryStorage implements IBuildHistoryStorage {
           total: diskSpace.size,
           free: diskSpace.free,
           pipelab: pipelabSize,
+          folders,
         },
       };
     } catch (error) {

package/src/handlers/engine.ts

@@ -4,8 +4,7 @@ import { useLogger } from "@pipelab/shared";
 import { getFinalPlugins, executeGraphWithHistory } from "../utils";
 import { presets } from "../presets/list";
 import { handleActionExecute } from "../handler-func";
-import { generateTempFolder } from "../utils/fs-extras";
-import { tmpdir } from "node:os";
+import { join } from "node:path";
 import { setupConfigFile } from "../config";
 import { AppConfig } from "@pipelab/shared";
 
@@ -82,10 +81,10 @@ export const registerEngineHandlers = (context: PipelabContext) => {
     const settings = await setupConfigFile<AppConfig>("settings", { context });
     const config = await settings.getConfig();
 
-    const cachePath = config?.cacheFolder || tmpdir();
-    const cwd = await generateTempFolder(cachePath);
+    const cachePath = join(context.userDataPath, "cache", "actions", pluginId, nodeId);
+    const cwd = await context.createTempFolder("action-execute-");
 
-    const mainWindow = undefined;
+    const mainWindow: undefined = undefined;
     abortControllerGraph = new AbortController();
 
     const signalPromise = new Promise((resolve, reject) => {
@@ -145,9 +144,9 @@ export const registerEngineHandlers = (context: PipelabContext) => {
     const effectiveProjectName = projectName || "Unnamed Project";
     const effectiveProjectPath = projectPath || "";
     const effectivePipelineId = pipelineId || "unknown";
-    const effectiveCachePath = config?.cacheFolder || tmpdir();
+    const effectiveCachePath = join(context.userDataPath, "cache", effectivePipelineId);
 
-    const mainWindow = undefined;
+    const mainWindow: undefined = undefined;
     abortControllerGraph = new AbortController();
 
     try {

package/src/handlers/history.ts

@@ -304,7 +304,7 @@ export const registerHistoryHandlers = (context: PipelabContext) => {
         },
       };
 
-      await settings.saveConfig(newConfig);
+      await settings.setConfig(newConfig);
 
       send({
         type: "end",

package/src/handlers/plugins.ts

@@ -249,17 +249,12 @@ export const registerPluginsHandlers = (context: PipelabContext) => {
   // Ensures all required plugin IDs are loaded, JIT-installing any that are missing.
   // Called before opening a pipeline in the editor.
   handle("plugin:ensure-loaded", async (_, { send, value }) => {
-    const { pluginIds, plugins } = value;
+    const { plugins } = value;
     const { plugins: registeredPlugins, registerPlugins } = usePlugins();
     const loaded: string[] = [];
     const failed: string[] = [];
 
     const pluginsToEnsure = new Set<string>();
-    if (Array.isArray(pluginIds)) {
-      for (const id of pluginIds) {
-        if (id) pluginsToEnsure.add(id);
-      }
-    }
     if (plugins && typeof plugins === "object") {
       for (const id of Object.keys(plugins)) {
         if (id) pluginsToEnsure.add(id);

package/src/migrations.ts

@@ -1,12 +1,7 @@
 import { useAPI } from "./ipc-core";
 import { PipelabContext } from "./context";
-import { setupConfigFile } from "./config";
-import {
-  savedFileMigrator,
-  fileRepoMigrations,
-  appSettingsMigrator,
-  useLogger,
-} from "@pipelab/shared";
+import { setupConfigFile, getMigrator } from "./config";
+import { useLogger } from "@pipelab/shared";
 
 /**
  * Registers migration handlers for the CLI/Standalone server.
@@ -23,14 +18,7 @@ export function registerMigrationHandlers(context: PipelabContext) {
 
     try {
       // Determine which migrator to use
-      let migrator: any = null;
-      if (name === "projects") {
-        migrator = fileRepoMigrations;
-      } else if (name === "settings") {
-        migrator = appSettingsMigrator;
-      } else if (name.startsWith("pipeline-") || name.endsWith(".plb")) {
-        migrator = savedFileMigrator;
-      }
+      const migrator = getMigrator(name);
 
       if (!migrator) {
         throw new Error(

package/src/plugins-registry.ts

@@ -203,7 +203,7 @@ export async function findInstalledPlugins(
   return installed;
 }
 
-export const builtInPlugins = async (options: { context: PipelabContext }) => {
+export const builtInPlugins = async (options: { context: PipelabContext }): Promise<void> => {
   console.log("[Plugins] Starting background plugin loading...");
 
   // Pre-ensure Node.js and PNPM once in parallel so plugins don't have to wait for them
@@ -318,6 +318,4 @@ export const builtInPlugins = async (options: { context: PipelabContext }) => {
       webSocketServer.broadcast("startup:progress", { type: "ready" });
     }, 2000);
   })();
-
-  return [];
 };

package/src/runner.ts

@@ -3,7 +3,6 @@ import { setupConfigFile } from "./config";
 import { isDev, PipelabContext } from "./context";
 import { readFile, access, writeFile, mkdir } from "node:fs/promises";
 import { resolve, isAbsolute, join, dirname } from "node:path";
-import { tmpdir } from "node:os";
 import { savedFileMigrator } from "@pipelab/shared";
 import type { AppConfig } from "@pipelab/shared";
 import { registerMigrationHandlers } from "./migrations";

package/src/server.ts

@@ -11,6 +11,7 @@ import { existsSync } from "node:fs";
 import { readFile } from "node:fs/promises";
 import { join } from "node:path";
 import http from "http";
+// @ts-expect-error serve-handler has no type definitions
 import handler from "serve-handler";
 import { registerMigrationHandlers } from "./migrations";
 

package/src/types/runner.ts

@@ -35,6 +35,7 @@ export type ActionRunnerData<ACTION extends Action> = {
   setMeta: (callback: (data: ACTION["meta"]) => ACTION["meta"]) => void;
   meta: ACTION["meta"];
   cwd: string;
+  /** @deprecated Use `context` instead to resolve sandboxed folders and binary paths. */
   paths: {
     cache: string;
     pnpm: string;

package/src/utils/fs-extras.ts

@@ -1,17 +1,7 @@
-import { mkdir, createWriteStream, createReadStream } from "node:fs";
+import { createWriteStream } from "node:fs";
 import { execa, Options, Subprocess } from "execa";
-import {
-  mkdir as mkdirP,
-  access,
-  writeFile,
-  realpath,
-  mkdtemp,
-  chmod,
-  stat,
-  readdir,
-} from "node:fs/promises";
+import { mkdir as mkdirP, writeFile, stat, readdir } from "node:fs/promises";
 import { join, dirname } from "node:path";
-import { tmpdir } from "node:os";
 import tar from "tar";
 import yauzl from "yauzl";
 import archiver from "archiver";
@@ -32,17 +22,6 @@ export const ensure = async (filesPath: string, defaultContent = "{}") => {
   }
 };
 
-/**
- * Generates a unique temporary folder.
- */
-export const generateTempFolder = async (base?: string) => {
-  const targetBase = base || tmpdir();
-  await mkdirP(targetBase, { recursive: true });
-  const realPath = await realpath(targetBase);
-  const tempFolder = await mkdtemp(join(realPath, "pipelab-"));
-  return tempFolder;
-};
-
 /**
  * Extracts a .tar.gz archive.
  */