@pipelab/test-utils 1.0.1-beta.14

package/.turbo/turbo-build.log

@@ -0,0 +1,14 @@
+
+
+> @pipelab/test-utils@1.0.1-beta.12 build /run/media/armaldio/SSD/Projects/Pipelab/pipelab/packages/test-utils
+> tsdown
+
+ℹ tsdown v0.21.2 powered by rolldown v1.0.0-rc.9
+ℹ entry: src/index.ts
+ℹ tsconfig: ../../tsconfig.json
+ℹ Build start
+ℹ Cleaning 2 files
+ℹ dist/index.mjs    4.87 kB │ gzip: 1.91 kB
+ℹ dist/index.d.mts  1.80 kB │ gzip: 0.80 kB
+ℹ 2 files, total: 6.67 kB
+✔ Build complete in 2173ms

package/CHANGELOG.md

@@ -0,0 +1,120 @@
+# @pipelab/test-utils
+
+## 1.0.1-beta.14
+
+### Patch Changes
+
+- azs
+- Updated dependencies
+  - @pipelab/plugin-core@1.0.1-beta.19
+
+## 1.0.1-beta.13
+
+### Patch Changes
+
+- sqqd
+- Updated dependencies
+  - @pipelab/plugin-core@1.0.1-beta.18
+
+## 1.0.1-beta.12
+
+### Patch Changes
+
+- sd
+- Updated dependencies
+  - @pipelab/plugin-core@1.0.1-beta.17
+
+## 1.0.1-beta.11
+
+### Patch Changes
+
+- sd
+- Updated dependencies
+  - @pipelab/plugin-core@1.0.1-beta.16
+
+## 1.0.1-beta.10
+
+### Patch Changes
+
+- wdf
+- Updated dependencies
+  - @pipelab/plugin-core@1.0.1-beta.15
+
+## 1.0.1-beta.9
+
+### Patch Changes
+
+- sdf
+- Updated dependencies
+  - @pipelab/plugin-core@1.0.1-beta.14
+
+## 1.0.1-beta.8
+
+### Patch Changes
+
+- Updated dependencies
+  - @pipelab/plugin-core@1.0.1-beta.13
+
+## 1.0.1-beta.7
+
+### Patch Changes
+
+- sd
+- Updated dependencies
+  - @pipelab/plugin-core@1.0.1-beta.12
+
+## 1.0.1-beta.6
+
+### Patch Changes
+
+- rfg
+- Updated dependencies
+  - @pipelab/plugin-core@1.0.1-beta.11
+
+## 1.0.1-beta.5
+
+### Patch Changes
+
+- szd
+- Updated dependencies
+  - @pipelab/plugin-core@1.0.1-beta.10
+
+## 1.0.1-beta.4
+
+### Patch Changes
+
+- sd
+- Updated dependencies
+  - @pipelab/plugin-core@1.0.1-beta.9
+
+## 1.0.1-beta.3
+
+### Patch Changes
+
+- sd
+- Updated dependencies
+  - @pipelab/plugin-core@1.0.1-beta.8
+
+## 1.0.1-beta.2
+
+### Patch Changes
+
+- sd
+- Updated dependencies
+  - @pipelab/plugin-core@1.0.1-beta.7
+
+## 1.0.1-beta.1
+
+### Patch Changes
+
+- sd
+- Updated dependencies
+  - @pipelab/plugin-core@1.0.1-beta.6
+
+## 1.0.1-beta.0
+
+### Patch Changes
+
+- test
+- Updated dependencies
+  - @pipelab/plugin-core@1.0.1-beta.5

package/LICENSE

@@ -0,0 +1,110 @@
+# Functional Source License, Version 1.1, MIT Future License
+
+## Abbreviation
+
+FSL-1.1-MIT
+
+## Notice
+
+Copyright 2026 CynToolkit
+
+## Terms and Conditions
+
+### Licensor ("We")
+
+The party offering the Software under these Terms and Conditions.
+
+### The Software
+
+The "Software" is each version of the software that we make available under
+these Terms and Conditions, as indicated by our inclusion of these Terms and
+Conditions with the Software.
+
+### License Grant
+
+Subject to your compliance with this License Grant and the Patents,
+Redistribution and Trademark clauses below, we hereby grant you the right to
+use, copy, modify, create derivative works, publicly perform, publicly display
+and redistribute the Software for any Permitted Purpose identified below.
+
+### Permitted Purpose
+
+A Permitted Purpose is any purpose other than a Competing Use. A Competing Use
+means making the Software available to others in a commercial product or
+service that:
+
+1. substitutes for the Software;
+
+2. substitutes for any other product or service we offer using the Software
+   that exists as of the date we make the Software available; or
+
+3. offers the same or substantially similar functionality as the Software.
+
+Permitted Purposes specifically include using the Software:
+
+1. for your internal use and access;
+
+2. for non-commercial education;
+
+3. for non-commercial research; and
+
+4. in connection with professional services that you provide to a licensee
+   using the Software in accordance with these Terms and Conditions.
+
+### Patents
+
+To the extent your use for a Permitted Purpose would necessarily infringe our
+patents, the license grant above includes a license under our patents. If you
+make a claim against any party that the Software infringes or contributes to
+the infringement of any patent, then your patent license to the Software ends
+immediately.
+
+### Redistribution
+
+The Terms and Conditions apply to all copies, modifications and derivatives of
+the Software.
+
+If you redistribute any copies, modifications or derivatives of the Software,
+you must include a copy of or a link to these Terms and Conditions and not
+remove any copyright notices provided in or with the Software.
+
+### Disclaimer
+
+THE SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTIES OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING WITHOUT LIMITATION WARRANTIES OF FITNESS FOR A PARTICULAR
+PURPOSE, MERCHANTABILITY, TITLE OR NON-INFRINGEMENT.
+
+IN NO EVENT WILL WE HAVE ANY LIABILITY TO YOU ARISING OUT OF OR RELATED TO THE
+SOFTWARE, INCLUDING INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES,
+EVEN IF WE HAVE BEEN INFORMED OF THEIR POSSIBILITY IN ADVANCE.
+
+### Trademarks
+
+Except for displaying the License Details and identifying us as the origin of
+the Software, you have no right under these Terms and Conditions to use our
+trademarks, trade names, service marks or product names.
+
+## Grant of Future License
+
+We hereby irrevocably grant you an additional license to use the Software under
+the MIT license that is effective on the second anniversary of the date we make
+the Software available. On or after that date, you may use the Software under
+the MIT license, in which case the following will apply:
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/LICENSE.md

@@ -0,0 +1,110 @@
+# Functional Source License, Version 1.1, MIT Future License
+
+## Abbreviation
+
+FSL-1.1-MIT
+
+## Notice
+
+Copyright 2024-present Quentin Goinaud - Armaldio
+
+## Terms and Conditions
+
+### Licensor ("We")
+
+The party offering the Software under these Terms and Conditions.
+
+### The Software
+
+The "Software" is each version of the software that we make available under
+these Terms and Conditions, as indicated by our inclusion of these Terms and
+Conditions with the Software.
+
+### License Grant
+
+Subject to your compliance with this License Grant and the Patents,
+Redistribution and Trademark clauses below, we hereby grant you the right to
+use, copy, modify, create derivative works, publicly perform, publicly display
+and redistribute the Software for any Permitted Purpose identified below.
+
+### Permitted Purpose
+
+A Permitted Purpose is any purpose other than a Competing Use. A Competing Use
+means making the Software available to others in a commercial product or
+service that:
+
+1. substitutes for the Software;
+
+2. substitutes for any other product or service we offer using the Software
+   that exists as of the date we make the Software available; or
+
+3. offers the same or substantially similar functionality as the Software.
+
+Permitted Purposes specifically include using the Software:
+
+1. for your internal use and access;
+
+2. for non-commercial education;
+
+3. for non-commercial research; and
+
+4. in connection with professional services that you provide to a licensee
+   using the Software in accordance with these Terms and Conditions.
+
+### Patents
+
+To the extent your use for a Permitted Purpose would necessarily infringe our
+patents, the license grant above includes a license under our patents. If you
+make a claim against any party that the Software infringes or contributes to
+the infringement of any patent, then your patent license to the Software ends
+immediately.
+
+### Redistribution
+
+The Terms and Conditions apply to all copies, modifications and derivatives of
+the Software.
+
+If you redistribute any copies, modifications or derivatives of the Software,
+you must include a copy of or a link to these Terms and Conditions and not
+remove any copyright notices provided in or with the Software.
+
+### Disclaimer
+
+THE SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTIES OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING WITHOUT LIMITATION WARRANTIES OF FITNESS FOR A PARTICULAR
+PURPOSE, MERCHANTABILITY, TITLE OR NON-INFRINGEMENT.
+
+IN NO EVENT WILL WE HAVE ANY LIABILITY TO YOU ARISING OUT OF OR RELATED TO THE
+SOFTWARE, INCLUDING INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES,
+EVEN IF WE HAVE BEEN INFORMED OF THEIR POSSIBILITY IN ADVANCE.
+
+### Trademarks
+
+Except for displaying the License Details and identifying us as the origin of
+the Software, you have no right under these Terms and Conditions to use our
+trademarks, trade names, service marks or product names.
+
+## Grant of Future License
+
+We hereby irrevocably grant you an additional license to use the Software under
+the MIT license that is effective on the second anniversary of the date we make
+the Software available. On or after that date, you may use the Software under
+the MIT license, in which case the following will apply:
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.mts

@@ -0,0 +1,65 @@
+import * as execa$1 from "execa";
+import { Action, ActionRunner, ActionRunnerData } from "@pipelab/plugin-core";
+
+//#region src/index.d.ts
+/**
+ * Finds the monorepo root by looking for pnpm-workspace.yaml.
+ */
+declare function findProjectRoot(startDir: string): string;
+declare const isWindows: boolean;
+declare const isMac: boolean;
+declare const isLinux: boolean;
+/**
+ * Creates a unique sandbox directory and returns a bundle containing its path
+ * and a pre-filled remove utility.
+ */
+declare const createSandbox: (prefix: string) => Promise<{
+  path: string;
+  paths: {
+    input: string;
+    output: string;
+    userData: string;
+    project: string;
+    thirdparty: string;
+  };
+  /**
+   * Creates a mock binary/script in the sandbox.
+   */
+  mockBinary: (relativePath: string, content?: string, options?: {
+    extension?: string | false;
+  }) => Promise<string>;
+  remove: () => Promise<void>;
+}>;
+/**
+ * Runs the Pipelab CLI out-of-process.
+ */
+declare const runCLI: (args: string[], options?: {
+  cwd?: string;
+  env?: Record<string, string>;
+}) => Promise<execa$1.Result<{
+  cwd: string;
+  env: {
+    PIPELAB_DISABLE_HISTORY: string;
+  };
+}>>;
+/**
+ * Runs a Pipelab action runner directly in-process for focused testing.
+ */
+declare const runAction: <A extends Action>(runner: ActionRunner<A>, options: {
+  inputs: ActionRunnerData<A>["inputs"];
+  sandboxPath: string;
+  extraEnv?: Record<string, string>;
+}) => Promise<{
+  outputs: Record<string, unknown>;
+}>;
+/**
+ * Runs the packaged electron app (smoke test)
+ */
+declare const runElectronApp: (app_path: string, options?: {
+  timeoutMs?: number;
+}) => Promise<execa$1.Result<{
+  cleanup: true;
+  timeout: number;
+}>>;
+//#endregion
+export { createSandbox, findProjectRoot, isLinux, isMac, isWindows, runAction, runCLI, runElectronApp };

package/dist/index.mjs

@@ -0,0 +1,140 @@
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { chmod, mkdir, rm, writeFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { execa } from "execa";
+//#region src/index.ts
+const __dirname = dirname(fileURLToPath(import.meta.url));
+/**
+* Finds the monorepo root by looking for pnpm-workspace.yaml.
+*/
+function findProjectRoot(startDir) {
+	let curr = startDir;
+	while (curr !== dirname(curr)) {
+		if (existsSync(join(curr, "pnpm-workspace.yaml"))) return curr;
+		curr = dirname(curr);
+	}
+	throw new Error("Could not find project root (pnpm-workspace.yaml)");
+}
+const isWindows = process.platform === "win32";
+const isMac = process.platform === "darwin";
+const isLinux = process.platform === "linux";
+/**
+* Creates a unique sandbox directory and returns a bundle containing its path
+* and a pre-filled remove utility.
+*/
+const createSandbox = async (prefix) => {
+	const sandboxPath = join(tmpdir(), `${prefix}-${Math.random().toString(36).substring(7)}`);
+	const paths = {
+		input: join(sandboxPath, "input"),
+		output: join(sandboxPath, "output"),
+		userData: join(sandboxPath, "user-data"),
+		project: join(sandboxPath, "project"),
+		thirdparty: join(sandboxPath, "thirdparty")
+	};
+	await mkdir(sandboxPath, { recursive: true });
+	await Promise.all([
+		mkdir(paths.input, { recursive: true }),
+		mkdir(paths.output, { recursive: true }),
+		mkdir(paths.userData, { recursive: true })
+	]);
+	return {
+		path: sandboxPath,
+		paths,
+		mockBinary: async (relativePath, content, options = {}) => {
+			const fullPath = join(sandboxPath, relativePath);
+			let platformPath = fullPath;
+			if (options.extension === false) {} else if (options.extension) platformPath = `${fullPath}.${options.extension}`;
+			else platformPath = /\.[a-z0-9]+$/i.test(relativePath) ? fullPath : isWindows ? `${fullPath}.cmd` : `${fullPath}.sh`;
+			const defaultContent = isWindows ? `@echo off\necho Mock Binary Execution: %*\nexit /b 0` : `#!/bin/bash\necho "Mock Binary Execution: $@"\nexit 0`;
+			await mkdir(dirname(platformPath), { recursive: true });
+			await writeFile(platformPath, content || defaultContent);
+			if (!isWindows) await chmod(platformPath, 493);
+			return platformPath;
+		},
+		remove: async () => {
+			await rm(sandboxPath, {
+				recursive: true,
+				force: true,
+				maxRetries: 20,
+				retryDelay: 500
+			});
+		}
+	};
+};
+/**
+* Runs the Pipelab CLI out-of-process.
+*/
+const runCLI = async (args, options = {}) => {
+	const projectRoot = findProjectRoot(__dirname);
+	return execa("tsx", [resolve(projectRoot, "apps/cli/src/index.ts"), ...args], {
+		cwd: options.cwd || projectRoot,
+		env: {
+			...process.env,
+			PIPELAB_DISABLE_HISTORY: "true",
+			...options.env
+		}
+	});
+};
+/**
+* Runs a Pipelab action runner directly in-process for focused testing.
+*/
+const runAction = async (runner, options) => {
+	const outputs = {};
+	const pnpmShimPath = join(options.sandboxPath, "pnpm-shim.cjs");
+	await writeFile(pnpmShimPath, `const { spawnSync } = require('child_process');
+spawnSync('pnpm', process.argv.slice(2), { stdio: 'inherit', shell: true });`);
+	const context = {
+		inputs: options.inputs,
+		log: (...args) => {
+			console.log("[Runner Log]", ...args);
+		},
+		setOutput: (key, value) => {
+			console.log(`[Runner Output] ${key} = ${value}`);
+			outputs[key] = value;
+		},
+		cwd: options.sandboxPath,
+		paths: {
+			assets: join(options.sandboxPath, "assets"),
+			cache: join(options.sandboxPath, "cache"),
+			pnpm: pnpmShimPath,
+			node: process.execPath,
+			userData: join(options.sandboxPath, "user-data"),
+			modules: join(options.sandboxPath, "modules"),
+			thirdparty: join(options.sandboxPath, "thirdparty")
+		},
+		api: { fetchAsset: async (packageName) => {
+			const sandboxAssetPath = join(options.sandboxPath, "assets", packageName);
+			if (existsSync(sandboxAssetPath)) return sandboxAssetPath;
+			const folderName = packageName.startsWith("@pipelab/") ? packageName.replace("@pipelab/", "") : packageName;
+			return join(findProjectRoot(__dirname), "assets", folderName);
+		} },
+		browserWindow: void 0,
+		abortSignal: new AbortController().signal,
+		setMeta: () => {},
+		meta: {}
+	};
+	const originalEnv = { ...process.env };
+	if (options.extraEnv) Object.assign(process.env, options.extraEnv);
+	try {
+		await runner(context);
+	} finally {
+		if (options.extraEnv) {
+			for (const key in options.extraEnv) if (!(key in originalEnv)) delete process.env[key];
+			Object.assign(process.env, originalEnv);
+		}
+	}
+	return { outputs };
+};
+/**
+* Runs the packaged electron app (smoke test)
+*/
+const runElectronApp = async (app_path, options = {}) => {
+	return execa(app_path, [], {
+		cleanup: true,
+		timeout: options.timeoutMs || 12e4
+	});
+};
+//#endregion
+export { createSandbox, findProjectRoot, isLinux, isMac, isWindows, runAction, runCLI, runElectronApp };

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@pipelab/test-utils",
+  "version": "1.0.1-beta.14",
+  "private": false,
+  "description": "Testing utilities for Pipelab plugins and monorepo",
+  "license": "FSL-1.1-MIT",
+  "author": "CynToolkit",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/CynToolkit/pipelab.git",
+    "directory": "packages/test-utils"
+  },
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs",
+      "default": "./dist/index.mjs"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "execa": "9.5.1",
+    "@pipelab/plugin-core": "1.0.1-beta.19"
+  },
+  "devDependencies": {
+    "@types/node": "24.12.2",
+    "tsdown": "0.21.2",
+    "typescript": "^5.0.0",
+    "@pipelab/tsconfig": "1.0.1-beta.19"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "format": "oxfmt .",
+    "lint": "oxlint ."
+  }
+}

package/src/index.ts

@@ -0,0 +1,223 @@
+import { resolve, dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { mkdir, writeFile, chmod, rm } from "node:fs/promises";
+import { existsSync as existsSyncSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { type ActionRunner, type ActionRunnerData, type Action, PipelabContext } from "@pipelab/plugin-core";
+import { execa } from "execa";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+/**
+ * Finds the monorepo root by looking for pnpm-workspace.yaml.
+ */
+export function findProjectRoot(startDir: string): string {
+  let curr = startDir;
+  while (curr !== dirname(curr)) {
+    if (existsSyncSync(join(curr, "pnpm-workspace.yaml"))) {
+      return curr;
+    }
+    curr = dirname(curr);
+  }
+  throw new Error("Could not find project root (pnpm-workspace.yaml)");
+}
+
+export const isWindows = process.platform === "win32";
+export const isMac = process.platform === "darwin";
+export const isLinux = process.platform === "linux";
+
+/**
+ * Creates a unique sandbox directory and returns a bundle containing its path
+ * and a pre-filled remove utility.
+ */
+export const createSandbox = async (prefix: string) => {
+  const sandboxPath = join(tmpdir(), `${prefix}-${Math.random().toString(36).substring(7)}`);
+
+  const paths = {
+    input: join(sandboxPath, "input"),
+    output: join(sandboxPath, "output"),
+    userData: join(sandboxPath, "user-data"),
+    project: join(sandboxPath, "project"),
+    thirdparty: join(sandboxPath, "thirdparty"),
+  };
+
+  await mkdir(sandboxPath, { recursive: true });
+  await Promise.all([
+    mkdir(paths.input, { recursive: true }),
+    mkdir(paths.output, { recursive: true }),
+    mkdir(paths.userData, { recursive: true }),
+  ]);
+
+  return {
+    path: sandboxPath,
+    paths,
+    /**
+     * Creates a mock binary/script in the sandbox.
+     */
+    mockBinary: async (
+      relativePath: string,
+      content?: string,
+      options: { extension?: string | false } = {},
+    ) => {
+      const fullPath = join(sandboxPath, relativePath);
+      let platformPath = fullPath;
+
+      if (options.extension === false) {
+        // Use exactly the path provided
+      } else if (options.extension) {
+        platformPath = `${fullPath}.${options.extension}`;
+      } else {
+        const hasExtension = /\.[a-z0-9]+$/i.test(relativePath);
+        platformPath = hasExtension ? fullPath : isWindows ? `${fullPath}.cmd` : `${fullPath}.sh`;
+      }
+
+      const defaultContent = isWindows
+        ? `@echo off\necho Mock Binary Execution: %*\nexit /b 0`
+        : `#!/bin/bash\necho "Mock Binary Execution: $@"\nexit 0`;
+
+      await mkdir(dirname(platformPath), { recursive: true });
+      await writeFile(platformPath, content || defaultContent);
+
+      if (!isWindows) {
+        await chmod(platformPath, 0o755);
+      }
+
+      return platformPath;
+    },
+    remove: async () => {
+      await rm(sandboxPath, {
+        recursive: true,
+        force: true,
+        maxRetries: 20,
+        retryDelay: 500,
+      });
+    },
+  };
+};
+
+/**
+ * Runs the Pipelab CLI out-of-process.
+ */
+export const runCLI = async (
+  args: string[],
+  options: {
+    cwd?: string;
+    env?: Record<string, string>;
+  } = {},
+) => {
+  const projectRoot = findProjectRoot(__dirname);
+  const cliPath = resolve(projectRoot, "apps/cli/src/index.ts");
+
+  return execa("tsx", [cliPath, ...args], {
+    cwd: options.cwd || projectRoot,
+    env: {
+      ...process.env,
+      PIPELAB_DISABLE_HISTORY: "true",
+      ...options.env,
+    },
+  });
+};
+
+/**
+ * Runs a Pipelab action runner directly in-process for focused testing.
+ */
+export const runAction = async <A extends Action>(
+  runner: ActionRunner<A>,
+  options: {
+    inputs: ActionRunnerData<A>["inputs"];
+    sandboxPath: string;
+    extraEnv?: Record<string, string>;
+  },
+): Promise<{ outputs: Record<string, unknown> }> => {
+  const outputs: Record<string, unknown> = {};
+
+  // Create a pnpm shim because ensureNPMPackage expects a JS file runnable by node
+  const pnpmShimPath = join(options.sandboxPath, "pnpm-shim.cjs");
+  await writeFile(
+    pnpmShimPath,
+    `const { spawnSync } = require('child_process');
+spawnSync('pnpm', process.argv.slice(2), { stdio: 'inherit', shell: true });`,
+  );
+
+  const context: ActionRunnerData<A> = {
+    inputs: options.inputs,
+    log: (...args: any[]) => {
+      console.log("[Runner Log]", ...args);
+    },
+    setOutput: (key: any, value: any) => {
+      console.log(`[Runner Output] ${key} = ${value}`);
+      outputs[key] = value;
+    },
+    cwd: options.sandboxPath,
+    paths: {
+      assets: join(options.sandboxPath, "assets"),
+      cache: join(options.sandboxPath, "cache"),
+      pnpm: pnpmShimPath,
+      node: process.execPath,
+      userData: join(options.sandboxPath, "user-data"),
+      modules: join(options.sandboxPath, "modules"),
+      thirdparty: join(options.sandboxPath, "thirdparty"),
+    },
+    api: {
+      fetchAsset: async (packageName: string) => {
+        const sandboxAssetPath = join(options.sandboxPath, "assets", packageName);
+        if (existsSyncSync(sandboxAssetPath)) {
+          return sandboxAssetPath;
+        }
+        // Fallback to real monorepo assets
+        // Normalize: remove @pipelab/ prefix if present
+        const folderName = packageName.startsWith("@pipelab/")
+          ? packageName.replace("@pipelab/", "")
+          : packageName;
+
+        const projectRoot = findProjectRoot(__dirname);
+        return join(projectRoot, "assets", folderName);
+      },
+    },
+    // @ts-ignore - Mocking BrowserWindow
+    browserWindow: undefined,
+    abortSignal: new AbortController().signal,
+    context: new PipelabContext({
+      userDataPath: join(options.sandboxPath, "user-data"),
+    }),
+    // @ts-ignore - Mocking setMeta
+    setMeta: () => {},
+    meta: {} as any,
+  };
+
+  // Set environment variables for the test if provided
+  const originalEnv = { ...process.env };
+  if (options.extraEnv) {
+    Object.assign(process.env, options.extraEnv);
+  }
+
+  try {
+    await runner(context);
+  } finally {
+    // Restore original environment
+    if (options.extraEnv) {
+      // Remove keys that were added
+      for (const key in options.extraEnv) {
+        if (!(key in originalEnv)) {
+          delete process.env[key];
+        }
+      }
+      // Restore original values
+      Object.assign(process.env, originalEnv);
+    }
+  }
+
+  return { outputs };
+};
+
+/**
+ * Runs the packaged electron app (smoke test)
+ */
+export const runElectronApp = async (app_path: string, options: { timeoutMs?: number } = {}) => {
+  const child = execa(app_path, [], {
+    cleanup: true,
+    timeout: options.timeoutMs || 120000,
+  });
+  return child;
+};