@pipelab/plugin-core 1.0.1-beta.2

package/dist/module-6F3E5H7Y-BVGmvvK_.cjs

@@ -0,0 +1,6 @@
+const require_chunk_JTKJZQYV = require("./chunk-JTKJZQYV-DwALyGe5.cjs");
+require("./index.cjs");
+exports.QuickJSModuleCallbacks = require_chunk_JTKJZQYV.QuickJSModuleCallbacks;
+exports.QuickJSWASMModule = require_chunk_JTKJZQYV.QuickJSWASMModule;
+exports.applyBaseRuntimeOptions = require_chunk_JTKJZQYV.applyBaseRuntimeOptions;
+exports.applyModuleEvalRuntimeOptions = require_chunk_JTKJZQYV.applyModuleEvalRuntimeOptions;

package/dist/module-6F3E5H7Y-DHjYta_R.mjs

@@ -0,0 +1,2 @@
+import { a as applyModuleEvalRuntimeOptions, i as applyBaseRuntimeOptions, n as QuickJSModuleCallbacks, r as QuickJSWASMModule } from "./chunk-JTKJZQYV-CRyylFtW.mjs";
+export { QuickJSModuleCallbacks, QuickJSWASMModule, applyBaseRuntimeOptions, applyModuleEvalRuntimeOptions };

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@pipelab/plugin-core",
+  "version": "1.0.1-beta.2",
+  "description": "Core library for building Pipelab plugins",
+  "license": "FSL-1.1-MIT",
+  "author": "CynToolkit",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/CynToolkit/pipelab.git",
+    "directory": "packages/plugin-core"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "browser": "./src/index.ts",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs",
+      "default": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@types/node": "^24.12.2",
+    "archiver": "7.0.1",
+    "electron": "32.1.2",
+    "execa": "9.4.1",
+    "pacote": "21.5.0",
+    "tar": "6.2.1",
+    "type-fest": "4.26.1",
+    "yauzl": "2.10.0",
+    "zod": "4.3.6"
+  },
+  "devDependencies": {
+    "@types/archiver": "7.0.0",
+    "@types/pacote": "11.1.8",
+    "@types/tar": "7.0.87",
+    "@types/yauzl": "2.10.3",
+    "tsdown": "0.21.2",
+    "typescript": "5.9.3",
+    "@pipelab/constants": "1.0.1-beta.3",
+    "@pipelab/shared": "2.0.1-beta.4",
+    "@pipelab/tsconfig": "1.0.1-beta.3"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "format": "oxfmt .",
+    "lint": "oxlint ."
+  },
+  "module": "./dist/index.js"
+}

package/src/archive-utils.ts

@@ -0,0 +1,137 @@
+import { mkdir, createReadStream, createWriteStream } from "node:fs";
+import { mkdir as mkdirP } from "node:fs/promises";
+import { join, dirname } from "node:path";
+import zlib from "zlib";
+import tar from "tar";
+import yauzl from "yauzl";
+import archiver from "archiver";
+
+/**
+ * Extracts a .tar.gz archive.
+ * @param archivePath The full path to the .tar.gz file.
+ * @param destinationDir The directory to extract contents into.
+ * @returns A Promise that resolves when extraction is complete.
+ */
+export async function extractTarGz(archivePath: string, destinationDir: string): Promise<void> {
+  console.log(`Extracting ${archivePath} to ${destinationDir}...`);
+
+  // Ensure the destination directory exists
+  await mkdirP(destinationDir, { recursive: true });
+
+  return new Promise((resolve, reject) => {
+    const readStream = createReadStream(archivePath);
+    const gunzipStream = zlib.createGunzip();
+    const extractStream = tar.extract({ cwd: destinationDir });
+
+    readStream.on("error", reject);
+    gunzipStream.on("error", reject);
+    extractStream.on("error", reject);
+
+    extractStream.on("close", () => {
+      console.log("Extraction finished.");
+      resolve();
+    });
+
+    readStream.pipe(gunzipStream).pipe(extractStream);
+  });
+}
+
+/**
+ * Extracts a .zip archive.
+ * @param archivePath The full path to the .zip file.
+ * @param destinationDir The directory to extract contents into.
+ * @returns A Promise that resolves when extraction is complete.
+ */
+export async function extractZip(archivePath: string, destinationDir: string): Promise<void> {
+  console.log(`Extracting ${archivePath} to ${destinationDir}...`);
+
+  // Ensure the destination directory exists
+  await mkdirP(destinationDir, { recursive: true });
+
+  return new Promise((resolve, reject) => {
+    yauzl.open(archivePath, { lazyEntries: true }, (err, zipfile) => {
+      if (err || !zipfile) {
+        return reject(err || new Error("Could not open zip file"));
+      }
+
+      zipfile.on("error", reject);
+
+      zipfile.readEntry(); // Start reading entries
+
+      zipfile.on("entry", (entry) => {
+        const entryPath = join(destinationDir, entry.fileName);
+
+        if (/\/$/.test(entry.fileName)) {
+          // It's a directory
+          mkdirP(entryPath, { recursive: true })
+            .then(() => zipfile.readEntry())
+            .catch(reject);
+        } else {
+          // It's a file
+          // Ensure parent directory exists (just in case)
+          mkdirP(dirname(entryPath), { recursive: true })
+            .then(() => {
+              zipfile.openReadStream(entry, (err, readStream) => {
+                if (err || !readStream) {
+                  return reject(err || new Error("Could not open read stream"));
+                }
+
+                readStream.on("error", reject);
+                const writeStream = createWriteStream(entryPath);
+                writeStream.on("error", reject);
+                writeStream.on("close", () => {
+                  zipfile.readEntry();
+                });
+                readStream.pipe(writeStream);
+              });
+            })
+            .catch(reject);
+        }
+      });
+
+      zipfile.on("end", () => {
+        console.log("Zip extraction finished.");
+        resolve();
+      });
+    });
+  });
+}
+
+export const zipFolder = async (from: string, to: string, log: typeof console.log) => {
+  const output = createWriteStream(to);
+
+  const archive = archiver("zip", {
+    zlib: { level: 9 }, // Sets the compression level.
+  });
+
+  // eslint-disable-next-line no-async-promise-executor
+  return new Promise<string>(async (resolve, reject) => {
+    // listen for all archive data to be written
+    // 'close' event is fired only when a file descriptor is involved
+    output.on("close", function () {
+      log(archive.pointer() + " total bytes");
+      log("archiver has been finalized and the output file descriptor has closed.");
+      resolve(to);
+    });
+
+    // This event is fired when the data source is drained no matter what was the data source.
+    // It is not part of this library but part of NodeJS.
+    output.on("end", function () {
+      log("Data has been drained");
+    });
+
+    // good practice to catch this error and expose it to the user
+    archive.on("error", function (err) {
+      reject(err);
+    });
+
+    // pipe archive data to the file
+    archive.pipe(output);
+
+    archive.directory(from, false);
+
+    // finalize the archive (ie we are done appending files but streams have to finish yet)
+    // 'close', 'end' or 'finish' may be fired right after calling this method so register to them beforehand
+    await archive.finalize();
+  });
+};

package/src/create-plugin.ts

@@ -0,0 +1,8 @@
+export type Plugin = {
+  nodes: Record<string, any>;
+  runtime: () => Promise<void>;
+};
+
+export const createPlugin = (plugin: Plugin) => {
+  return plugin;
+};

package/src/custom-errors.ts

@@ -0,0 +1,11 @@
+export class ExternalCommandError extends Error {
+  code: number;
+
+  constructor(message: string, code: number) {
+    super(message);
+
+    this.code = code;
+
+    Object.setPrototypeOf(this, ExternalCommandError.prototype);
+  }
+}

package/src/fs-utils.ts

@@ -0,0 +1,31 @@
+import { access, mkdir, realpath, writeFile, mkdtemp } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { tmpdir } from "node:os";
+import { readdirSync, copyFileSync, statSync } from "node:fs";
+
+export const ensure = async (filesPath: string, defaultContent = "{}") => {
+  // create parent folder
+  await mkdir(dirname(filesPath), {
+    recursive: true,
+  });
+
+  // ensure file exist
+  try {
+    await access(filesPath);
+  } catch {
+    // File doesn't exist, create it
+    await writeFile(filesPath, defaultContent); // json
+  }
+};
+
+export const generateTempFolder = async (base?: string) => {
+  const targetBase = base || tmpdir();
+  await mkdir(targetBase, {
+    recursive: true,
+  });
+  const realPath = await realpath(targetBase);
+  console.log("join", join(realPath, "pipelab-"));
+  const tempFolder = await mkdtemp(join(realPath, "pipelab-"));
+
+  return tempFolder;
+};

package/src/index.ts

@@ -0,0 +1,10 @@
+export * from "./pipelab";
+export * from "./create-plugin";
+export * from "./utils";
+export * from "./fs-utils";
+export * from "./archive-utils";
+export * from "./custom-errors";
+export * from "./node-utils";
+
+export { z as schema } from "zod";
+export type NoData = { [index in string]?: unknown };

package/src/node-utils.ts

@@ -0,0 +1,52 @@
+import { access } from "node:fs/promises";
+import { join } from "node:path";
+
+export type OutputRuntimes = "construct" | "godot";
+
+const fileExists = async (path: string): Promise<boolean> => {
+  try {
+    await access(path);
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+/**
+ * Detects the runtime of an app folder by checking for specific files.
+ * This function depends on Node.js APIs and should only be used in Node environments.
+ */
+export const detectRuntime = async (
+  appFolder: string | undefined,
+): Promise<OutputRuntimes | undefined> => {
+  if (!appFolder) {
+    return undefined;
+  }
+
+  const indexExist = await fileExists(join(appFolder, "index.html"));
+  const swExist = await fileExists(join(appFolder, "sw.js"));
+  const offlineJSON = await fileExists(join(appFolder, "offline.json"));
+  const dataJSON = await fileExists(join(appFolder, "data.json"));
+  const scriptsFolder = await fileExists(join(appFolder, "scripts"));
+  const workermainJs = await fileExists(join(appFolder, "workermain.js"));
+
+  if (!indexExist) {
+    throw new Error("The input folder does not contain an index.html file");
+  }
+
+  let detectedRuntime: OutputRuntimes | undefined = undefined;
+
+  if (swExist || dataJSON || workermainJs || scriptsFolder) {
+    detectedRuntime = "construct";
+  }
+
+  console.log("Detected runtime", detectedRuntime);
+
+  if (detectedRuntime === "construct" && offlineJSON && swExist) {
+    throw new Error(
+      "Construct runtime detected, please disable offline capabilties when using HTML5 export. Offline is already supported by default.",
+    );
+  }
+
+  return detectedRuntime;
+};

package/src/pipelab.ts

@@ -0,0 +1,103 @@
+import type { BrowserWindow } from "electron";
+import type {
+  Action,
+  Condition,
+  Loop,
+  Expression,
+  Event,
+  SetOutputActionFn,
+  SetOutputLoopFn,
+  SetOutputExpressionFn,
+  ExtractInputsFromAction,
+  ExtractInputsFromCondition,
+  ExtractInputsFromLoop,
+  ExtractInputsFromEvent,
+  ExtractInputsFromExpression,
+} from "@pipelab/shared";
+
+export * from "@pipelab/shared";
+
+export type RunnerCallbackFnArgument = {
+  done: () => void;
+  id: string;
+  log: (...args: Parameters<(typeof console)["log"]>) => void;
+};
+
+export type ActionRunnerData<ACTION extends Action> = {
+  log: typeof console.log;
+  setOutput: SetOutputActionFn<ACTION>;
+  inputs: ExtractInputsFromAction<ACTION>;
+  setMeta: (callback: (data: ACTION["meta"]) => ACTION["meta"]) => void;
+  meta: ACTION["meta"];
+  cwd: string;
+  paths: {
+    assets: string;
+    cache: string;
+    pnpm: string;
+    node: string;
+    userData: string;
+    modules: string;
+    thirdparty: string;
+  };
+  api: {
+    fetchAsset: (packageName: string, version?: string) => Promise<string>;
+    [key: string]: any;
+  };
+  browserWindow: BrowserWindow;
+  abortSignal: AbortSignal;
+};
+
+export type ActionRunner<ACTION extends Action> = (data: ActionRunnerData<ACTION>) => Promise<void>;
+export const createActionRunner = <ACTION extends Action>(runner: ActionRunner<ACTION>) => runner;
+
+// ---
+
+export type ConditionRunner<CONDITION extends Condition> = (data: {
+  log: typeof console.log;
+  inputs: ExtractInputsFromCondition<CONDITION>;
+  setMeta: (callback: (data: CONDITION["meta"]) => CONDITION["meta"]) => void;
+  meta: CONDITION["meta"];
+  cwd: string;
+}) => Promise<boolean>;
+export const createConditionRunner = <CONDITION extends Condition>(
+  runner: ConditionRunner<CONDITION>,
+) => runner;
+
+// ---
+
+export type LoopRunner<LOOP extends Loop> = (data: {
+  log: typeof console.log;
+  setOutput: SetOutputLoopFn<LOOP>;
+  inputs: ExtractInputsFromLoop<LOOP>;
+  setMeta: (callback: (data: LOOP["meta"]) => LOOP["meta"]) => void;
+  meta: LOOP["meta"];
+  cwd: string;
+}) => Promise<"step" | "exit">;
+export const createLoopRunner = <LOOP extends Loop>(runner: LoopRunner<LOOP>) => runner;
+
+export type ExpressionRunner<EXPRESSION extends Expression> = (data: {
+  log: typeof console.log;
+  setOutput: SetOutputExpressionFn<EXPRESSION>;
+  inputs: ExtractInputsFromExpression<EXPRESSION>;
+  setMeta: (callback: (data: EXPRESSION["meta"]) => EXPRESSION["meta"]) => void;
+  meta: EXPRESSION["meta"];
+  cwd: string;
+}) => Promise<string>;
+export const createExpressionRunner = <EXPRESSION extends Expression>(
+  runner: ExpressionRunner<EXPRESSION>,
+) => runner;
+
+export type EventRunner<EVENT extends Event> = (data: {
+  log: typeof console.log;
+  inputs: ExtractInputsFromEvent<EVENT>;
+  setMeta: (callback: (data: EVENT["meta"]) => EVENT["meta"]) => void;
+  meta: EVENT["meta"];
+  cwd: string;
+}) => Promise<void>;
+export const createEventRunner = <EVENT extends Event>(runner: EventRunner<EVENT>) => runner;
+
+export type Runner = ActionRunner<any> | LoopRunner<any> | EventRunner<any> | ConditionRunner<any>;
+
+export const sleep = (duration: number) => {
+  return new Promise((resolve) => setTimeout(resolve, duration));
+};

package/src/utils.ts

@@ -0,0 +1,251 @@
+import { execa, Options, Subprocess } from "execa";
+import { ExternalCommandError } from "./custom-errors.js";
+import { join } from "node:path";
+import { access, mkdir, writeFile, rm } from "node:fs/promises";
+import { createWriteStream } from "node:fs";
+import { pipeline } from "node:stream/promises";
+import pacote from "pacote";
+
+export const fileExists = async (path: string): Promise<boolean> => {
+  try {
+    await access(path);
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+export const runWithLiveLogs = async (
+  command: string,
+  args: string[],
+  execaOptions: Options,
+  log: typeof console.log,
+  hooks?: {
+    onStdout?: (data: string, subprocess: Subprocess) => void;
+    onStderr?: (data: string, subprocess: Subprocess) => void;
+    onExit?: (code: number) => void;
+  },
+): Promise<void> => {
+  return new Promise((resolve, reject) => {
+    console.log("command: ", command, args.join(" "));
+
+    const subprocess = execa(command, args, {
+      ...execaOptions,
+      stdout: "pipe",
+      stderr: "pipe",
+      stdin: "pipe",
+    });
+
+    subprocess.stdout.on("data", (data: Buffer) => {
+      hooks?.onStdout?.(data.toString(), subprocess);
+    });
+
+    subprocess.stderr?.on("data", (data: Buffer) => {
+      hooks?.onStderr?.(data.toString(), subprocess);
+    });
+
+    subprocess.on("error", (error: Error) => {
+      console.log("error", error);
+      return reject(error);
+    });
+
+    subprocess.on("close", (code: number) => {
+      console.log("close", code);
+      hooks?.onExit?.(code);
+
+      if (code === 0) {
+        return resolve();
+      } else {
+        return reject(new Error(`Command exited with non-zero code: ${code}`));
+      }
+    });
+
+    subprocess.on("disconnect", () => {
+      console.log("disconnect");
+      hooks?.onExit?.(0);
+      return resolve();
+    });
+
+    subprocess.on("exit", (code: number) => {
+      console.log("exit", code);
+      hooks?.onExit?.(code);
+
+      if (code === 0) {
+        return resolve();
+      } else {
+        return reject(new Error(`Command exited with non-zero code: ${code}`));
+      }
+    });
+  });
+};
+
+export const runWithLiveLogsPTY = async (
+  command: string,
+  args: string[],
+  execaOptions: Options,
+  log: typeof console.log,
+  hooks?: {
+    onStdout?: (data: string, subprocess: Subprocess) => void;
+    onStderr?: (data: string, subprocess: Subprocess) => void;
+    onExit?: (code: number) => void;
+    onCreated?: (subprocess: Subprocess) => void;
+  },
+  abortSignal?: AbortSignal,
+): Promise<void> => {
+  return new Promise((resolve, reject) => {
+    console.log("command (execa-pty-fallback): ", command, args.join(" "));
+
+    const subprocess = execa(command, args, {
+      ...execaOptions,
+      stdout: "pipe",
+      stderr: "pipe",
+      stdin: "pipe",
+      env: {
+        ...process.env,
+        ...execaOptions.env,
+        TERM: "xterm-256color",
+        FORCE_STDERR_LOGGING: "1",
+      },
+      cancelSignal: abortSignal,
+    });
+
+    hooks?.onCreated?.(subprocess);
+
+    subprocess.stdout?.on("data", (data: Buffer) => {
+      hooks?.onStdout?.(data.toString(), subprocess);
+    });
+
+    subprocess.stderr?.on("data", (data: Buffer) => {
+      hooks?.onStderr?.(data.toString(), subprocess);
+    });
+
+    subprocess.on("error", (error: Error) => {
+      console.log("error", error);
+      return reject(error);
+    });
+
+    subprocess.on("exit", (code: number) => {
+      console.log("exit", code);
+      hooks?.onExit?.(code || 0);
+
+      if (code === 0) {
+        return resolve();
+      } else {
+        return reject(
+          new ExternalCommandError(`Command exited with non-zero code: ${code}`, code || 1),
+        );
+      }
+    });
+  });
+};
+
+export interface Hooks {
+  onProgress?: (data: { progress: number; downloadedSize: number }) => void;
+}
+
+/**
+ * Downloads a file from a given URL to a specified local path with progress tracking.
+ *
+ * @param url - The URL of the file to download.
+ * @param localPath - The local file path to save the downloaded file.
+ * @returns A promise that resolves when the file is downloaded.
+ */
+export const downloadFile = async (
+  url: string,
+  localPath: string,
+  hooks?: Hooks,
+  abortSignal?: AbortSignal,
+): Promise<void> => {
+  // Fetch the resource
+  const response = await fetch(url, {
+    signal: abortSignal,
+  });
+
+  // Check if the fetch was successful
+  if (!response.ok) {
+    throw new Error(`Failed to fetch file: ${response.statusText}`);
+  }
+
+  // Get the total size of the file
+  const contentLength = response.headers.get("content-length");
+  if (!contentLength) {
+    throw new Error("Content-Length header is missing");
+  }
+  const totalSize = parseInt(contentLength, 10);
+
+  // Track progress
+  let downloadedSize = 0;
+  const fileStream = createWriteStream(localPath);
+
+  // Create a readable stream to monitor progress
+  const progressStream = new TransformStream({
+    transform(chunk, controller) {
+      downloadedSize += chunk.length;
+      const progress = (downloadedSize / totalSize) * 100;
+      if (hooks?.onProgress) {
+        hooks.onProgress({
+          progress,
+          downloadedSize,
+        });
+      }
+      controller.enqueue(chunk);
+    },
+  });
+
+  // Pipe the response through the progress tracker and into the file
+  const readable = response.body?.pipeThrough(progressStream);
+  if (!readable) {
+    throw new Error("Failed to create a readable stream");
+  }
+
+  await pipeline(readable, fileStream);
+};
+
+/**
+ * Installs an NPM package from the npm registry as a tarball if not already present.
+ * @param thirdpartyDir The directory where third-party tools are stored.
+ * @param name The name of the package (e.g., 'pnpm' or '@poki/cli').
+ * @param version The version of the package.
+ * @param options (Optional) configuration for dependency installation.
+ * @returns A Promise that resolves to the path of the extracted package (the 'package' subfolder).
+ */
+export const ensureNPMPackage = async (
+  thirdpartyDir: string,
+  name: string,
+  version: string,
+  options?: {
+    nodePath?: string;
+    pnpmPath?: string;
+    installDeps?: boolean;
+  },
+) => {
+  const packageDir = join(thirdpartyDir, name, version);
+  const finalPath = join(packageDir, "package");
+
+  // 1. Check if already installed
+  if (await fileExists(finalPath)) {
+    return finalPath;
+  }
+  console.log(`NPM package ${name}@${version} not found at ${finalPath}, installing...`);
+
+  // 2. Extract using pacote
+  console.log(`Extracting ${name}@${version} to ${finalPath}...`);
+  await mkdir(packageDir, { recursive: true });
+  await pacote.extract(`${name}@${version}`, finalPath);
+
+  // 3. Install dependencies if requested
+  if (options?.installDeps && options.pnpmPath) {
+    console.log(
+      `Installing dependencies for ${name}@${version} using pnpm at ${options.pnpmPath}...`,
+    );
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    // We use the pnpm .cjs bundle directly with node
+    const node = options.nodePath || process.execPath;
+    await execa(node, [options.pnpmPath, "install", "--prod"], {
+      cwd: finalPath,
+      stdio: "inherit",
+    });
+  }
+
+  return finalPath;
+};

package/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "@pipelab/tsconfig/vue.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src",
+    "types": ["node"]
+  },
+  "include": ["src"]
+}

package/tsdown.config.ts

@@ -0,0 +1,8 @@
+import { defineConfig } from "tsdown";
+
+export default defineConfig({
+  entry: ["src/index.ts"],
+  format: ["esm", "cjs"],
+  dts: true,
+  clean: true,
+});