@powerlines/engine 0.15.0 → 0.15.2

package/dist/index.mjs

@@ -1,568 +1,8 @@
-import { t as PowerlinesEngineContext } from "./engine-context-BuD9AGfd.mjs";
-import { POWERLINES_API_FUNCTIONS } from "@powerlines/core/constants";
-import { resolvePackage } from "@stryke/fs/resolve";
-import { joinPaths } from "@stryke/path/join";
-import { LogLevelLabel } from "@storm-software/config-tools/types";
-import { isSet } from "@stryke/type-checks/is-set";
-import { isString } from "@stryke/type-checks/is-string";
-import { Worker } from "jest-worker";
-import { Transform } from "node:stream";
-import { parseArgs } from "node:util";
+import { PowerlinesEngineContext } from "./context/engine-context.mjs";
+import { PowerlinesEngine, createContext, createEngine } from "./engine.mjs";
+import { createRpcClient } from "./helpers/rpc.mjs";
+import { createExecutionHost } from "./helpers/create-execution-host.mjs";
+import "./context/index.mjs";
+import { finalize } from "./helpers/finalize.mjs";
 
-//#region src/_internal/helpers/worker.ts
-const RESTARTED = Symbol("powerlines-worker:restarted");
-/**
-* Formats the debug address into a string.
-*/
-const formatDebugAddress = ({ host, port }) => {
-	if (host) return `${host}:${port}`;
-	return `${port}`;
-};
-/**
-* Node.js CLI flags that are not allowed in NODE_OPTIONS and must be
-* passed as direct CLI arguments via execArgv.
-* This set is the difference between all Node.js CLI flags and the ones **not**
-* allowed in NODE_OPTIONS, as listed in the Node.js documentation:
-* https://nodejs.org/api/cli.html#node_optionsoptions
-*
-* It is not exhaustive since not all options make sense for Powerlines (e.g. --test)
-*/
-const EXEC_ARGV_ONLY_OPTIONS = new Set([
-	"experimental-network-inspection",
-	"experimental-storage-inspection",
-	"experimental-worker-inspection",
-	"experimental-inspector-network-resource"
-]);
-function formatArg(key, value) {
-	if (value === true) return `--${key}`;
-	if (value) return `--${key}=${value.includes(" ") && !value.startsWith("\"") ? JSON.stringify(value) : value}`;
-	return null;
-}
-/**
-* Tokenizes the arguments string into an array of strings, supporting quoted
-* values and escaped characters.
-* Converted from: https://github.com/nodejs/node/blob/c29d53c5cfc63c5a876084e788d70c9e87bed880/src/node_options.cc#L1401
-*
-* @param input - The arguments string to be tokenized.
-* @returns An array of strings with the tokenized arguments.
-*/
-const tokenizeArgs = (input) => {
-	const args = [];
-	let isInString = false;
-	let willStartNewArg = true;
-	for (let i = 0; i < input.length; i++) {
-		let char = input[i];
-		if (char) {
-			if (char === "\\" && isInString) {
-				if (input.length === i + 1) throw new Error("Invalid escape character at the end.");
-				char = input[++i];
-				if (!char) continue;
-			} else if (char === " " && !isInString) {
-				willStartNewArg = true;
-				continue;
-			} else if (char === "\"") {
-				isInString = !isInString;
-				continue;
-			}
-			if (willStartNewArg) {
-				args.push(char);
-				willStartNewArg = false;
-			} else args[args.length - 1] += char;
-		}
-	}
-	if (isInString) throw new Error("Unterminated string");
-	return args;
-};
-/**
-* Get the node options from the environment variable `NODE_OPTIONS` and returns
-* them as an array of strings.
-*
-* @returns An array of strings with the node options.
-*/
-const getNodeOptionsArgs = () => {
-	if (!process.env.NODE_OPTIONS) return [];
-	return tokenizeArgs(process.env.NODE_OPTIONS);
-};
-/**
-* Stringify the arguments to be used in a command line. It will ignore any
-* argument that has a value of `undefined`. Options that are not allowed in
-* NODE_OPTIONS are returned separately as execArgv.
-*
-* @param args - The arguments to be stringified.
-* @returns An object with `nodeOptions` string and `execArgv` array.
-*/
-function formatNodeOptions(args) {
-	const nodeOptionsParts = [];
-	const execArgv = [];
-	for (const [key, value] of Object.entries(args)) {
-		const formatted = formatArg(key, value);
-		if (formatted === null) continue;
-		if (EXEC_ARGV_ONLY_OPTIONS.has(key)) execArgv.push(formatted);
-		else nodeOptionsParts.push(formatted);
-	}
-	return {
-		nodeOptions: nodeOptionsParts.join(" "),
-		execArgv
-	};
-}
-const parseNodeArgs = (args) => {
-	const { values, tokens } = parseArgs({
-		args,
-		strict: false,
-		tokens: true
-	});
-	let orphan = null;
-	for (let i = 0; i < tokens.length; i++) {
-		const token = tokens[i];
-		if (!token) continue;
-		if (token.kind === "option-terminator") break;
-		if (token.kind === "option") {
-			orphan = !isSet(token.value) ? token : null;
-			continue;
-		}
-		if (token.kind !== "positional") {
-			orphan = null;
-			continue;
-		}
-		if (!orphan) continue;
-		if (orphan.name in values && isString(values[orphan.name])) values[orphan.name] += ` ${token.value}`;
-		else values[orphan.name] = token.value;
-	}
-	return values;
-};
-function getParsedNodeOptions() {
-	const args = [...process.execArgv, ...getNodeOptionsArgs()];
-	if (args.length === 0) return {};
-	return parseNodeArgs(args);
-}
-/**
-* Get's the debug address from the `NODE_OPTIONS` environment variable. If the
-* address is not found, it returns the default host (`undefined`) and port
-* (`9229`).
-*
-* @returns An object with the host and port of the debug address.
-*/
-const getParsedDebugAddress = (address) => {
-	if (!address || !isString(address)) return {
-		host: void 0,
-		port: 9229
-	};
-	if (address.includes(":")) {
-		const [host, port] = address.split(":");
-		if (!host || !port) throw new Error(`Invalid debug address: ${address}`);
-		return {
-			host,
-			port: Number.parseInt(port, 10)
-		};
-	}
-	return {
-		host: void 0,
-		port: Number.parseInt(address, 10)
-	};
-};
-/**
-* Get the debug type from the `NODE_OPTIONS` environment variable.
-*/
-function getNodeDebugType(nodeOptions) {
-	if (nodeOptions.inspect) return "inspect";
-	if (nodeOptions["inspect-brk"] || nodeOptions.inspect_brk) return "inspect-brk";
-}
-const cleanupWorkers = (worker) => {
-	for (const curWorker of worker._workerPool?._workers || []) curWorker._child?.kill("SIGINT");
-};
-var Worker$1 = class {
-	#worker;
-	/**
-	* Create a new worker instance.
-	*
-	* @param workerPath - The path to the worker file.
-	* @param options - The options for the worker, including exposed methods, timeout, and hooks for activity and restart.
-	*/
-	constructor(workerPath, options) {
-		this.workerPath = workerPath;
-		this.options = options;
-		const { timeout, onRestart, debuggerPortOffset = -1, enableSourceMaps = false, isolatedMemory = false, logger, ...rest } = this.options;
-		let restartPromise;
-		let resolveRestartPromise;
-		let activeTasks = 0;
-		this.#worker = void 0;
-		process.on("exit", () => {
-			this.close();
-		});
-		const nodeOptions = getParsedNodeOptions();
-		const originalOptions = { ...nodeOptions };
-		delete nodeOptions.inspect;
-		delete nodeOptions["inspect-brk"];
-		delete nodeOptions.inspect_brk;
-		if (debuggerPortOffset !== -1) {
-			const nodeDebugType = getNodeDebugType(originalOptions);
-			if (nodeDebugType) {
-				const debuggerAddress = getParsedDebugAddress(originalOptions[nodeDebugType]);
-				nodeOptions[nodeDebugType] = formatDebugAddress({
-					host: debuggerAddress.host,
-					port: debuggerAddress.port === 0 ? 0 : debuggerAddress.port + 1 + debuggerPortOffset
-				});
-			}
-		}
-		if (enableSourceMaps) nodeOptions["enable-source-maps"] = true;
-		if (isolatedMemory) {
-			delete nodeOptions["max-old-space-size"];
-			delete nodeOptions.max_old_space_size;
-		}
-		const { nodeOptions: formattedNodeOptions, execArgv } = formatNodeOptions(nodeOptions);
-		const createWorker = () => {
-			const workerEnv = {
-				...process.env,
-				...rest.forkOptions?.env ?? {},
-				POWERLINES_WORKER: "true",
-				NODE_OPTIONS: formattedNodeOptions
-			};
-			if (workerEnv.FORCE_COLOR === void 0) {
-				if (!workerEnv.NO_COLOR && !workerEnv.CI && workerEnv.TERM !== "dumb" && (process.stdout.isTTY || process.stderr?.isTTY)) workerEnv.FORCE_COLOR = "1";
-			}
-			this.#worker = new Worker(workerPath, {
-				...rest,
-				forkOptions: {
-					...rest.forkOptions,
-					execArgv: [...execArgv, ...rest.forkOptions?.execArgv ?? []],
-					env: workerEnv
-				},
-				maxRetries: 0
-			});
-			restartPromise = new Promise((resolve) => {
-				resolveRestartPromise = resolve;
-			});
-			/**
-			* Jest Worker has two worker types, ChildProcessWorker (uses child_process) and NodeThreadWorker (uses worker_threads)
-			* Powerlines uses ChildProcessWorker by default, but it can be switched to NodeThreadWorker with an experimental flag
-			*
-			* We only want to handle ChildProcessWorker's orphan process issue, so we access the private property "_child":
-			* https://github.com/facebook/jest/blob/b38d7d345a81d97d1dc3b68b8458b1837fbf19be/packages/jest-worker/src/workers/ChildProcessWorker.ts
-			*
-			* But this property is not available in NodeThreadWorker, so we need to check if we are using ChildProcessWorker
-			*/
-			if (!rest.enableWorkerThreads) for (const worker of this.#worker._workerPool?._workers || []) {
-				worker._child?.on("exit", (code, signal) => {
-					if ((code || signal && signal !== "SIGINT") && this.#worker) {
-						logger(LogLevelLabel.ERROR, `Worker exited with code: ${code} and signal: ${signal}`);
-						process.exit(code ?? 1);
-					}
-				});
-				worker._child?.on("message", ([, data]) => {
-					if (data && typeof data === "object" && "type" in data && data.type === "activity") onActivity();
-				});
-			}
-			let aborted = false;
-			const onActivityAbort = () => {
-				if (!aborted) {
-					this.options.onActivityAbort?.();
-					aborted = true;
-				}
-			};
-			const abortActivityStreamOnLog = new Transform({ transform(_chunk, _encoding, callback) {
-				onActivityAbort();
-				callback();
-			} });
-			this.#worker.getStdout().pipe(abortActivityStreamOnLog);
-			this.#worker.getStderr().pipe(abortActivityStreamOnLog);
-			this.#worker.getStdout().pipe(process.stdout);
-			this.#worker.getStderr().pipe(process.stderr);
-		};
-		createWorker();
-		const onHanging = () => {
-			const worker = this.#worker;
-			if (!worker) return;
-			const resolve = resolveRestartPromise;
-			createWorker();
-			logger(LogLevelLabel.WARN, `Sending SIGTERM signal to static worker due to timeout${timeout ? ` of ${timeout / 1e3} seconds` : ""}. Subsequent errors may be a result of the worker exiting.`);
-			worker.end().then(() => {
-				resolve(RESTARTED);
-			});
-		};
-		let hangingTimer = false;
-		const onActivity = () => {
-			if (hangingTimer) clearTimeout(hangingTimer);
-			if (this.options.onActivity) this.options.onActivity();
-			hangingTimer = activeTasks > 0 && setTimeout(onHanging, timeout);
-		};
-		for (const method of rest.exposedMethods) {
-			if (method.startsWith("_")) continue;
-			this[method] = timeout ? async (...args) => {
-				activeTasks++;
-				try {
-					let attempts = 0;
-					for (;;) {
-						onActivity();
-						const result = await Promise.race([this.#worker[method](args.length > 0 && args[0] ? args[0] : {}), restartPromise]);
-						if (result !== RESTARTED) return result;
-						if (onRestart) onRestart(method, args, ++attempts);
-					}
-				} finally {
-					activeTasks--;
-					onActivity();
-				}
-			} : this.#worker[method].bind(this.#worker);
-		}
-	}
-	async end() {
-		const worker = this.#worker;
-		if (!worker) throw new Error("Farm is ended, no more calls can be done to it");
-		cleanupWorkers(worker);
-		this.#worker = void 0;
-		return worker.end();
-	}
-	/**
-	* Quietly end the worker if it exists
-	*/
-	close() {
-		if (this.#worker) {
-			cleanupWorkers(this.#worker);
-			this.#worker.end();
-		}
-	}
-};
-
-//#endregion
-//#region src/index.ts
-/**
-* The Powerlines Engine class
-*
-* @remarks
-* This class is responsible for managing the Powerlines project lifecycle, including initialization, building, and finalization.
-*
-* @public
-*/
-var PowerlinesEngine = class PowerlinesEngine {
-	/**
-	* The Powerlines context
-	*/
-	#context;
-	/**
-	* The worker pool for managing child threads
-	*/
-	#worker;
-	/**
-	* Create a new Powerlines Engine instance
-	*
-	* @param options - The options to initialize the context with
-	* @returns A new instance of the Powerlines Engine
-	*/
-	static async fromOptions(options) {
-		const api = new PowerlinesEngine(await PowerlinesEngineContext.fromOptions(options));
-		const packagePath = await resolvePackage("@powerlines/engine");
-		if (!packagePath) throw new Error("Could not resolve `@powerlines/engine` package location.");
-		api.#worker = new Worker$1(joinPaths(packagePath, "./_internal/worker.mjs"), {
-			exposedMethods: POWERLINES_API_FUNCTIONS,
-			logger: api.context.createLog(null)
-		});
-		return api;
-	}
-	/**
-	* The Powerlines context
-	*/
-	get context() {
-		return this.#context;
-	}
-	/**
-	* Create a new Powerlines Engine instance
-	*
-	* @param context - The Powerlines context
-	*/
-	constructor(context) {
-		this.#context = context;
-	}
-	/**
-	* Generate the Powerlines typescript declaration file
-	*
-	* @remarks
-	* This method will only generate the typescript declaration file for the Powerlines project. It is generally recommended to run the full `prepare` command, which will run this method as part of its process.
-	*
-	* @param inlineConfig - The inline configuration for the types command
-	*/
-	async types(inlineConfig = { command: "types" }) {
-		const timer = this.context.timer("Types");
-		this.context.info(" 🏗️  Generating typescript declarations for the Powerlines project");
-		this.context.debug(" Aggregating configuration options for the Powerlines project");
-		inlineConfig.command ??= "types";
-		await Promise.all(this.#context.executions.map(async (options) => this.#worker.types({
-			options,
-			config: inlineConfig
-		})));
-		this.context.debug("✔ Powerlines types generation has completed successfully");
-		timer();
-	}
-	/**
-	* Prepare the Powerlines API
-	*
-	* @remarks
-	* This method will prepare the Powerlines API for use, initializing any necessary resources.
-	*
-	* @param inlineConfig - The inline configuration for the prepare command
-	*/
-	async prepare(inlineConfig = { command: "prepare" }) {
-		const timer = this.context.timer("Prepare");
-		this.context.info(" 🏗️  Preparing the Powerlines project");
-		this.context.debug("Aggregating configuration options for the Powerlines project");
-		inlineConfig.command ??= "prepare";
-		await Promise.all(this.#context.executions.map(async (options) => this.#worker.prepare({
-			options,
-			config: inlineConfig
-		})));
-		this.context.debug("✔ Powerlines preparation has completed successfully");
-		timer();
-	}
-	/**
-	* Create a new Powerlines project
-	*
-	* @remarks
-	* This method will create a new Powerlines project in the current directory.
-	*
-	* @param inlineConfig - The inline configuration for the new command
-	* @returns A promise that resolves when the project has been created
-	*/
-	async new(inlineConfig) {
-		const timer = this.context.timer("New");
-		this.context.info(" 🆕 Creating a new Powerlines project");
-		inlineConfig.command ??= "new";
-		await Promise.all(this.#context.executions.map(async (options) => this.#worker.new({
-			options,
-			config: inlineConfig
-		})));
-		this.context.debug("✔ Powerlines new command completed successfully");
-		timer();
-	}
-	/**
-	* Clean any previously prepared artifacts
-	*
-	* @remarks
-	* This method will remove the previous Powerlines artifacts from the project.
-	*
-	* @param inlineConfig - The inline configuration for the clean command
-	* @returns A promise that resolves when the clean command has completed
-	*/
-	async clean(inlineConfig = { command: "clean" }) {
-		const timer = this.context.timer("Clean");
-		this.context.info(" 🧹 Cleaning the previous Powerlines artifacts");
-		inlineConfig.command ??= "clean";
-		await Promise.all(this.#context.executions.map(async (options) => this.#worker.clean({
-			options,
-			config: inlineConfig
-		})));
-		this.context.debug("✔ Powerlines cleaning completed successfully");
-		timer();
-	}
-	/**
-	* Lint the project
-	*
-	* @param inlineConfig - The inline configuration for the lint command
-	* @returns A promise that resolves when the lint command has completed
-	*/
-	async lint(inlineConfig = { command: "lint" }) {
-		const timer = this.context.timer("Lint");
-		this.context.info(" 📝 Linting the Powerlines project");
-		inlineConfig.command ??= "lint";
-		await Promise.all(this.#context.executions.map(async (options) => this.#worker.lint({
-			options,
-			config: inlineConfig
-		})));
-		this.context.debug("✔ Powerlines linting completed successfully");
-		timer();
-	}
-	/**
-	* Test the project
-	*
-	* @remarks
-	* This method will run the tests for the Powerlines project.
-	*
-	* @param inlineConfig - The inline configuration for the test command
-	* @returns A promise that resolves when the test command has completed
-	*/
-	async test(inlineConfig = { command: "test" }) {
-		const timer = this.context.timer("Test");
-		this.context.info(" 🧪 Running tests for the Powerlines project");
-		inlineConfig.command ??= "test";
-		await Promise.all(this.#context.executions.map(async (options) => this.#worker.test({
-			options,
-			config: inlineConfig
-		})));
-		this.context.debug("✔ Powerlines testing completed successfully");
-		timer();
-	}
-	/**
-	* Build the project
-	*
-	* @remarks
-	* This method will build the Powerlines project, generating the necessary artifacts.
-	*
-	* @param inlineConfig - The inline configuration for the build command
-	* @returns A promise that resolves when the build command has completed
-	*/
-	async build(inlineConfig = { command: "build" }) {
-		const timer = this.context.timer("Build");
-		this.context.info(" 📦 Building the Powerlines project");
-		await Promise.all(this.#context.executions.map(async (options) => this.#worker.build({
-			options,
-			config: inlineConfig
-		})));
-		this.context.debug("✔ Powerlines build completed successfully");
-		timer();
-	}
-	/**
-	* Prepare the documentation for the project
-	*
-	* @param inlineConfig - The inline configuration for the docs command
-	* @returns A promise that resolves when the documentation generation has completed
-	*/
-	async docs(inlineConfig = { command: "docs" }) {
-		const timer = this.context.timer("Docs");
-		this.context.info(" 📓 Generating documentation for the Powerlines project");
-		inlineConfig.command ??= "docs";
-		await Promise.all(this.#context.executions.map(async (options) => this.#worker.docs({
-			options,
-			config: inlineConfig
-		})));
-		this.context.debug("✔ Powerlines documentation generation completed successfully");
-		timer();
-	}
-	/**
-	* Deploy the project source code
-	*
-	* @remarks
-	* This method will prepare and build the Powerlines project, generating the necessary artifacts for the deployment.
-	*
-	* @param inlineConfig - The inline configuration for the deploy command
-	*/
-	async deploy(inlineConfig = { command: "deploy" }) {
-		const timer = this.context.timer("Deploy");
-		this.context.info(" 🚀 Deploying the Powerlines project");
-		inlineConfig.command ??= "deploy";
-		await Promise.all(this.#context.executions.map(async (options) => this.#worker.deploy({
-			options,
-			config: inlineConfig
-		})));
-		this.context.debug("✔ Powerlines deploy completed successfully");
-		timer();
-	}
-	/**
-	* Finalization/cleanup processing for the Powerlines API
-	*
-	* @remarks
-	* This step includes any final processes or clean up required by Powerlines. It will be run after each Powerlines command.
-	*
-	* @returns A promise that resolves when the finalization process has completed
-	*/
-	async finalize() {
-		const timer = this.context.timer("Finalization");
-		this.context.info(" 🏁 Powerlines finalization processes started");
-		this.#worker.close();
-		this.context.debug("✔ Powerlines finalization completed successfully");
-		timer();
-	}
-	async [Symbol.asyncDispose]() {
-		return this.finalize();
-	}
-};
-
-//#endregion
-export { PowerlinesEngine };
-//# sourceMappingURL=index.mjs.map
+export { PowerlinesEngine, PowerlinesEngineContext, createContext, createEngine, createExecutionHost, createRpcClient, finalize };