kizlo 0.28.0 → 0.29.0

package/dist/cli/commands/_setup.js

@@ -1,11 +1,11 @@
 import { DEFAULT_WORDPRESS_TAG, LOCAL_DIR_REL } from "../wp/constants.js";
 import { composeStop, createStack, dockerHint, dockerStatus } from "../wp/docker.js";
 import { DEFAULT_ENV_KEYS, availablePackageManagers, detectInvokingPackageManager, ensureGitignored, envGroups, envKeysPresent, mergeEnv, pickStackPort, writeFileIfAbsent } from "../utils.js";
+import { removeProjectContainers } from "../wp/session.js";
 import { DEFAULT_DEV_DB_PORT, DEFAULT_DEV_PORT, DEFAULT_MCP_PORT, resolveStackName, stackProject } from "../daemon/config.js";
 import { promptFragment, resolvePromptDefault } from "../presets/template.js";
 import { createAdminAppPassword } from "../wp/bootstrap.js";
 import { bootstrapDev } from "../wp/dev.js";
-import { removeProjectContainers } from "../wp/session.js";
 import { syncSiteSettings } from "../wp/settings.js";
 import { devStack } from "../wp/stack.js";
 import { isPluginVersionSupported, pluginUpdateMessage } from "@kizlo/shared";

package/dist/cli/commands/dev.js

@@ -2,9 +2,11 @@ import { createStack, dockerHint, dockerStatus, stackStatus } from "../wp/docker
 import { findConfigDir } from "../wp/utils.js";
 import { log } from "../daemon/logger.js";
 import { DEFAULT_ENV_KEYS, ensureGitignored, envGroups, groupDefault, mergeEnv, pickStackPort, withSpinner } from "../utils.js";
+import { ownerStatus } from "../process-owner.js";
+import { operationLock, withOperation } from "../daemon/lock.js";
+import { projectSession, reapOrphans, registerSession, removeProjectContainers, spawnWatchdog, unregisterSession } from "../wp/session.js";
 import { resolveDevConfig, resolveMcpConfig, usesLocalWordPress } from "../daemon/config.js";
 import { bootstrapDev } from "../wp/dev.js";
-import { reapOrphans, registerSession, removeProjectContainers, spawnWatchdog, unregisterSession } from "../wp/session.js";
 import { syncSiteSettings } from "../wp/settings.js";
 import { devStack } from "../wp/stack.js";
 import { palette } from "../banner.js";
@@ -12,6 +14,7 @@ import { watchReload } from "../daemon/reload.js";
 import { startWatcher } from "../daemon/watch.js";
 import { createMcpState } from "../mcp/state.js";
 import { resolveMcpPort, startMcp } from "../mcp/index.js";
+import { exportDev } from "../wp/export.js";
 import { join } from "node:path";
 import { existsSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { defineCommand } from "citty";
@@ -147,8 +150,9 @@ function syncLocalUrl(configDir, url) {
 * an `npm`/`pnpm` wrapper silently swallows — leaving us orphaned but alive otherwise).
 */
 async function armForegroundTeardown(cfg) {
-	const owner = await registerSession(cfg.project);
-	spawnWatchdog(cfg.project, owner);
+	const file = operationLock(cfg.configDir);
+	const owner = await registerSession(cfg.project, file);
+	spawnWatchdog(cfg.project, owner, file);
 	let exiting = false;
 	const shutdown = (line) => {
 		if (exiting) return;
@@ -295,35 +299,51 @@ async function rebootStack(cwd, label, mcpPort) {
 */
 async function startForeground(cfg) {
 	const cwd = process.cwd();
-	let ready = await prepareStack(cfg);
-	const shutdown = await armForegroundTeardown(ready);
-	const { creds, start } = await bootAndSync(ready);
-	const stack = {
-		status: () => stackStatus(ready.project),
-		onStopped: () => shutdown()
-	};
-	const mcp = createMcpState();
-	const mcpPort = ready.mcpPort;
-	let stopContract = await startWatcher(ready.configDir, {
-		stack,
-		mcp
+	let ready = cfg;
+	const session = await withOperation(cfg.configDir, async () => {
+		const existing = projectSession(cfg.project);
+		if (existing && await ownerStatus(existing) !== "dead") throw new Error("Local WordPress already has an active dev session. Stop it before starting another.");
+		ready = await prepareStack(cfg);
+		const shutdown = await armForegroundTeardown(ready);
+		const { creds, start } = await bootAndSync(ready);
+		const stack$1 = {
+			status: () => stackStatus(ready.project),
+			onStopped: () => shutdown()
+		};
+		const mcp$1 = createMcpState();
+		const mcpPort$1 = ready.mcpPort;
+		const stopContract$1 = await startWatcher(ready.configDir, {
+			stack: stack$1,
+			mcp: mcp$1
+		});
+		const mcpServer$1 = stopContract$1 && mcpPort$1 !== void 0 ? await startMcp(mcp$1, mcpPort$1) : void 0;
+		if (!stopContract$1) log.info("Another `kizlo dev` is serving MCP for this project.");
+		printReady(creds, false, start, mcpServer$1?.url);
+		return {
+			stack: stack$1,
+			mcp: mcp$1,
+			mcpPort: mcpPort$1,
+			stopContract: stopContract$1,
+			mcpServer: mcpServer$1
+		};
 	});
-	const mcpServer = stopContract && mcpPort !== void 0 ? await startMcp(mcp, mcpPort) : void 0;
-	if (!stopContract) log.info("Another `kizlo dev` is serving MCP for this project.");
-	printReady(creds, false, start, mcpServer?.url);
+	let { stopContract } = session;
+	const { stack, mcp, mcpPort, mcpServer } = session;
 	let reloading = false;
 	const reload = async (changed) => {
 		if (reloading) return;
 		reloading = true;
 		try {
-			stopContract?.();
-			const rebooted = await rebootStack(cwd, `${changed} changed — restarting the session`, mcpPort);
-			ready = rebooted.ready;
-			stopContract = await startWatcher(ready.configDir, {
-				stack,
-				mcp
+			await withOperation(ready.configDir, async () => {
+				stopContract?.();
+				const rebooted = await rebootStack(cwd, `${changed} changed — restarting the session`, mcpPort);
+				ready = rebooted.ready;
+				stopContract = await startWatcher(ready.configDir, {
+					stack,
+					mcp
+				});
+				printReady(rebooted.creds, true, rebooted.start, mcpServer?.url);
 			});
-			printReady(rebooted.creds, true, rebooted.start, mcpServer?.url);
 		} catch (error) {
 			log.error("Failed to reload the dev session:", error);
 		} finally {
@@ -416,10 +436,17 @@ const subCommands = {
 			name: "stop",
 			description: "Stop local WordPress, keeping the database volume"
 		},
-		async run() {
+		args: { export: {
+			type: "boolean",
+			description: "Export the existing local site"
+		} },
+		async run({ args }) {
+			if (args.export) throw new Error("--export cannot be combined with stop or reset. Run `kizlo dev --export`.");
 			if (!await requireLocalWordPress(process.cwd())) return;
-			const { stack } = await resolve$1(process.cwd());
-			await withSpinner("Stopping local WordPress", () => stack.composeStop(), "Local WordPress stopped (volumes kept)");
+			await withOperation((await resolveDevConfig(process.cwd())).configDir, async () => {
+				const { stack } = await resolve$1(process.cwd());
+				await withSpinner("Stopping local WordPress", () => stack.composeStop(), "Local WordPress stopped (volumes kept)");
+			});
 		}
 	}),
 	reset: defineCommand({
@@ -427,25 +454,43 @@ const subCommands = {
 			name: "reset",
 			description: "Wipe the database and the install folder so the next `kizlo dev` rebuilds fresh"
 		},
-		async run() {
+		args: { export: {
+			type: "boolean",
+			description: "Export the existing local site"
+		} },
+		async run({ args }) {
+			if (args.export) throw new Error("--export cannot be combined with stop or reset. Run `kizlo dev --export`.");
 			if (!await requireLocalWordPress(process.cwd())) return;
-			const { cfg, stack } = await resolve$1(process.cwd());
-			await withSpinner("Wiping local WordPress", () => stack.composeDown({ volumes: true }), "Local WordPress reset successfully");
-			rmSync(cfg.wordpressDir, {
-				recursive: true,
-				force: true
+			const cfg = await resolveDevConfig(process.cwd());
+			await withOperation(cfg.configDir, async () => {
+				const { stack } = await resolve$1(process.cwd());
+				await withSpinner("Wiping local WordPress", () => stack.composeDown({ volumes: true }), "Local WordPress reset successfully");
+				rmSync(cfg.wordpressDir, {
+					recursive: true,
+					force: true
+				});
+				note("Run `kizlo dev` to rebuild fresh.");
 			});
-			note("Run `kizlo dev` to rebuild fresh.");
 		}
 	})
 };
 const dev = defineCommand({
 	meta: {
 		name: "dev",
-		description: "Run local WordPress and the contract watcher (stop | reset)"
+		description: "Run local WordPress and the contract watcher (stop | reset | --export)"
 	},
+	args: { export: {
+		type: "boolean",
+		description: "Export site content and SQL to a ZIP and stop dev"
+	} },
 	subCommands,
-	run: groupDefault(Object.keys(subCommands), bringUp)
+	setup({ args, rawArgs }) {
+		if (args.export && rawArgs.some((arg) => arg === "stop" || arg === "reset")) throw new Error("--export cannot be combined with stop or reset. Run `kizlo dev --export`.");
+	},
+	run: groupDefault(Object.keys(subCommands), async ({ args }) => {
+		if (args.export) note(`Exported ${await exportDev(process.cwd())}\n   Local WordPress and its dev session are stopped.`);
+		else await bringUp();
+	})
 });
 
 //#endregion

package/dist/cli/daemon/lock.js

@@ -1,53 +1,96 @@
-import { currentProcessOwner, ownerAlive } from "../process-owner.js";
+import { currentProcessOwner, ownerStatus } from "../process-owner.js";
 import path from "node:path";
 import fs from "node:fs";
+import { randomUUID } from "node:crypto";
 
 //#region src/cli/daemon/lock.ts
 function lockPath(cwd) {
 	return path.join(cwd, "node_modules/.cache/kizlo/dev.lock");
 }
-/** True when a live daemon still owns the process identity recorded by the lock. */
-async function isLocked(file) {
-	if (!fs.existsSync(file)) return false;
-	const contents = fs.readFileSync(file, "utf8").trim();
+function readLock(file) {
+	try {
+		return fs.readFileSync(file, "utf8");
+	} catch (error) {
+		if (error.code === "ENOENT") return void 0;
+		throw error;
+	}
+}
+async function held(contents) {
 	let owner;
 	try {
-		owner = contents.startsWith("{") ? JSON.parse(contents) : { pid: Number(contents) };
+		owner = contents.trim().startsWith("{") ? JSON.parse(contents) : { pid: Number(contents) };
 	} catch {
 		return false;
 	}
-	return ownerAlive(owner);
+	return await ownerStatus(owner) !== "dead";
 }
 /** Claim the file for this process, or report that it was already there. */
 function claim(file, owner) {
+	const pending = `${file}.${randomUUID()}.tmp`;
 	try {
-		fs.writeFileSync(file, JSON.stringify(owner), { flag: "wx" });
+		fs.writeFileSync(pending, JSON.stringify(owner), {
+			flag: "wx",
+			mode: 384
+		});
+		fs.linkSync(pending, file);
 		return true;
 	} catch (error) {
 		if (error.code !== "EEXIST") throw error;
 		return false;
+	} finally {
+		fs.rmSync(pending, { force: true });
 	}
 }
-/**
-* Take the lock for this process, answering false when a live daemon already holds it. The file is
-* created with `wx`, so two `kizlo dev` starting together cannot both come away believing they won.
-* A lock whose owner has died or whose PID belongs to another process is removed and taken over.
-* Losing the second claim means another process reached the same stale lock first, so this one
-* stands down rather than trying again.
-*/
+/** Publish one complete owner record, serializing and rechecking any stale-owner replacement. */
 async function acquire(file) {
 	fs.mkdirSync(path.dirname(file), { recursive: true });
 	const owner = await currentProcessOwner();
 	if (claim(file, owner)) return true;
-	if (await isLocked(file)) return false;
-	fs.rmSync(file, { force: true });
-	return claim(file, owner);
+	const contents = readLock(file);
+	if (contents === void 0) return claim(file, owner);
+	if (await held(contents)) return false;
+	const recovery = `${file}.reclaim`;
+	try {
+		fs.mkdirSync(recovery);
+	} catch (error) {
+		if (error.code !== "EEXIST") throw error;
+		throw new Error(`Lock recovery is concurrent or was interrupted. Retry; if this persists, stop this project's dev commands and remove ${recovery}.`);
+	}
+	try {
+		if (readLock(file) !== contents) return false;
+		fs.rmSync(file, { force: true });
+		return claim(file, owner);
+	} finally {
+		fs.rmdirSync(recovery);
+	}
 }
 function release(file) {
 	try {
 		fs.rmSync(file, { force: true });
 	} catch {}
 }
+/** Lifecycle operations share one lock, separate from the long-lived contract watcher. */
+function operationLock(configDir) {
+	return path.join(configDir, ".kizlo/dev-operation.lock");
+}
+async function releaseOwned(file) {
+	const owner = await currentProcessOwner();
+	try {
+		const recorded = JSON.parse(fs.readFileSync(file, "utf8"));
+		if (recorded.pid === owner.pid && recorded.token === owner.token) release(file);
+	} catch (error) {
+		if (error.code !== "ENOENT") throw error;
+	}
+}
+async function withOperation(configDir, run) {
+	const file = operationLock(configDir);
+	if (!await acquire(file)) throw new Error("Another dev start, reload, stop, reset or export is active. Wait for it to finish and retry.");
+	try {
+		return await run();
+	} finally {
+		await releaseOwned(file);
+	}
+}
 
 //#endregion
-export { acquire, lockPath, release };
+export { acquire, lockPath, operationLock, release, releaseOwned, withOperation };

package/dist/cli/daemon/watch.js

@@ -1,8 +1,8 @@
 import { log } from "./logger.js";
+import { acquire, lockPath, release } from "./lock.js";
 import { resolveConfig, resolveWatchCredentials } from "./config.js";
 import { IntrospectionFetchError } from "../../wordpress/fetch-introspection.js";
 import { generateIntrospectionOnce, generateOnce, reportGenerationError } from "./generate.js";
-import { acquire, lockPath, release } from "./lock.js";
 import path from "node:path";
 import { FSWatcher } from "chokidar";
 

package/dist/cli/process-owner.js

@@ -3,12 +3,7 @@ import { randomUUID } from "node:crypto";
 
 //#region src/cli/process-owner.ts
 const HOST = "127.0.0.1";
-/**
-* How long to wait for an owner to answer its liveness probe. A dead owner refuses the connection
-* at once and never reaches this, so the timeout only decides how long a *live* owner may be too
-* busy to answer before it is read as gone. The dev session answers on the same event loop it
-* typechecks the generated client on, which blocks it for the better part of a second.
-*/
+/** A busy dev session can miss this deadline; timeout means unknown, never confirmed exit. */
 const PROBE_TIMEOUT_MS = 1e3;
 let ownerPromise;
 const ownerServers = /* @__PURE__ */ new Set();
@@ -21,7 +16,10 @@ function currentProcessOwner() {
 	if (ownerPromise) return ownerPromise;
 	ownerPromise = new Promise((resolve, reject) => {
 		const token = randomUUID();
-		const server = createServer((socket) => socket.end(token));
+		const server = createServer((socket) => {
+			socket.on("error", () => {});
+			socket.end(token);
+		});
 		server.unref();
 		const failed = (error) => {
 			ownerPromise = void 0;
@@ -49,24 +47,24 @@ function currentProcessOwner() {
 	});
 	return ownerPromise;
 }
-function pidAlive(pid) {
-	if (!Number.isSafeInteger(pid) || pid <= 0) return false;
+function pidStatus(pid) {
+	if (!Number.isSafeInteger(pid) || pid <= 0) return "dead";
 	try {
 		process.kill(pid, 0);
-		return true;
-	} catch {
-		return false;
+		return "alive";
+	} catch (error) {
+		return error.code === "ESRCH" ? "dead" : "unknown";
 	}
 }
 function hasDiscriminator(owner) {
 	return "port" in owner || "token" in owner;
 }
-/** True only when the recorded PID and its random liveness token still match. */
-async function ownerAlive(owner) {
-	if (typeof owner !== "object" || owner === null || !("pid" in owner)) return false;
-	if (!pidAlive(owner.pid)) return false;
-	if (!hasDiscriminator(owner)) return true;
-	if (!Number.isSafeInteger(owner.port) || owner.port <= 0 || owner.port > 65535 || typeof owner.token !== "string" || !owner.token) return false;
+/** A missed probe cannot distinguish a busy owner from a stale record. */
+async function ownerStatus(owner) {
+	if (typeof owner !== "object" || owner === null || !("pid" in owner)) return "dead";
+	const pid = pidStatus(owner.pid);
+	if (pid !== "alive" || !hasDiscriminator(owner)) return pid;
+	if (!Number.isSafeInteger(owner.port) || owner.port <= 0 || owner.port > 65535 || typeof owner.token !== "string" || !owner.token) return "dead";
 	return new Promise((resolve) => {
 		let response = "";
 		let settled = false;
@@ -76,21 +74,25 @@ async function ownerAlive(owner) {
 		});
 		socket.setEncoding("utf8");
 		socket.setTimeout(PROBE_TIMEOUT_MS);
-		const finish = (alive) => {
+		const finish = (status) => {
 			if (settled) return;
 			settled = true;
 			socket.destroy();
-			resolve(alive);
+			resolve(status);
 		};
 		socket.on("data", (chunk) => {
 			response += chunk;
-			if (response.length > owner.token.length) finish(false);
+			if (response.length > owner.token.length) finish("dead");
+		});
+		const missed = () => finish(pidStatus(owner.pid) === "dead" ? "dead" : "unknown");
+		socket.on("end", () => {
+			if (response) finish(response === owner.token ? "alive" : "dead");
+			else missed();
 		});
-		socket.on("end", () => finish(response === owner.token));
-		socket.on("error", () => finish(false));
-		socket.on("timeout", () => finish(false));
+		socket.on("error", missed);
+		socket.on("timeout", missed);
 	});
 }
 
 //#endregion
-export { currentProcessOwner, ownerAlive };
+export { currentProcessOwner, ownerStatus };

package/dist/cli/wp/compose/export.php

@@ -0,0 +1,82 @@
+<?php
+// Run in the existing wp-cli image; only read the effective mounted content tree.
+set_error_handler(static function ($severity, $message, $file, $line) {
+    throw new ErrorException($message, 0, $severity, $file, $line);
+});
+
+try {
+    [$script, $workspace, $content] = $argv;
+    if (!class_exists('PharData') || !Phar::canCompress(Phar::GZ)) {
+        throw new RuntimeException('The PHP image needs PharData ZIP and zlib support.');
+    }
+    $sql = "$workspace/database.sql";
+    if (!is_file($sql) || filesize($sql) === 0) {
+        throw new RuntimeException('The database dump is empty or missing.');
+    }
+    $root = realpath($content);
+    if ($root === false || !is_dir($root) || is_link($content)) {
+        throw new RuntimeException('The wp-content directory is missing or is a link outside the install.');
+    }
+    $directories = ['wp-content'];
+    $total = filesize($sql);
+    $entryCount = 3;
+    $files = function ($directory, $entry, $ancestors = []) use (&$files, &$directories, &$total, &$entryCount, $root): Generator {
+        $real = realpath($directory);
+        if ($real === false || ($real !== $root && !str_starts_with($real, "$root/"))) {
+            throw new RuntimeException("Content link escapes wp-content: $entry");
+        }
+        if (isset($ancestors[$real])) {
+            throw new RuntimeException("Content contains a directory link cycle: $entry");
+        }
+        $ancestors[$real] = true;
+        foreach (new DirectoryIterator($directory) as $file) {
+            if ($file->isDot()) continue;
+            if (++$entryCount > 65535) throw new RuntimeException('Export exceeds the PHP ZIP entry limit (65535).');
+            $name = $file->getFilename();
+            if (str_contains($name, '\\') || str_contains($name, ':')) {
+                throw new RuntimeException("Content filename is unsafe in a portable ZIP: $entry/$name");
+            }
+            $path = $file->getPathname();
+            $target = realpath($path);
+            if ($target === false || ($target !== $root && !str_starts_with($target, "$root/"))) {
+                throw new RuntimeException("Content link is broken or escapes wp-content: $entry/$name");
+            }
+            $key = "$entry/$name";
+            if ($file->isDir()) {
+                $directories[] = $key;
+                yield from $files($path, $key, $ancestors);
+            } elseif ($file->isFile() && is_readable($path)) {
+                $total += filesize($path);
+                // Phar ZIP has no ZIP64 support. Fail instead of publishing a truncated archive.
+                if ($total > 0xffffffff) throw new RuntimeException('Export exceeds the PHP ZIP size limit (4 GiB).');
+                yield $key => $path;
+            } else {
+                throw new RuntimeException("Content is unreadable or not a regular file: $key");
+            }
+        }
+    };
+    if ($total > 0xffffffff) throw new RuntimeException('SQL exceeds the PHP ZIP size limit (4 GiB).');
+    $inner = new PharData("$workspace/database.sql.zip");
+    $inner->buildFromIterator(new ArrayIterator(['database.sql' => $sql]));
+    $inner->compressFiles(Phar::GZ);
+    unset($inner);
+
+    $entries = function () use ($workspace, $root, $files): Generator {
+        yield 'database.sql.zip' => "$workspace/database.sql.zip";
+        yield 'README.txt' => "$workspace/README.txt";
+        yield from $files($root, 'wp-content');
+    };
+    $outer = new PharData("$workspace/site.zip");
+    $outer->startBuffering();
+    $outer->buildFromIterator($entries());
+    foreach ($directories as $directory) $outer->addEmptyDir($directory);
+    $outer->compressFiles(Phar::GZ);
+    $outer->stopBuffering();
+    unset($outer);
+    if (!is_file("$workspace/site.zip") || filesize("$workspace/site.zip") === 0 || filesize("$workspace/site.zip") > 0xffffffff) {
+        throw new RuntimeException('PHP did not produce an export ZIP.');
+    }
+} catch (Throwable $error) {
+    fwrite(STDERR, 'Export ZIP failed: ' . $error->getMessage() . PHP_EOL);
+    exit(1);
+}

package/dist/cli/wp/docker.d.ts

@@ -9,6 +9,8 @@ type RunInput = {
   input?: string;
   inputFile?: string;
   detached?: boolean;
+  signal?: AbortSignal;
+  timeout?: number;
 };
 /** A docker-compose stack: project id (`-p`), published port, image tag, and compose files (`-f`). */
 interface Stack {
@@ -42,6 +44,8 @@ interface RunResult {
   stdout: string;
   stderr: string;
 }
+/** File transfers use Docker's copy support, keeping archive/SQL bytes out of stdout. */
+declare function docker(args: string[], opts?: RunInput): Promise<RunResult>;
 /**
  * Docker's readiness in three states, so callers can tell "not installed" from "installed but not
  * running" and say the right thing:
@@ -65,7 +69,7 @@ declare function dockerAvailable(): Promise<boolean>;
  * this works from any directory and without the project's compose files. Throws when docker itself
  * could not answer, which the callers tell apart from an empty answer.
  */
-declare function runningProjectContainers(project: string): Promise<string[]>;
+declare function runningProjectContainers(project: string, opts?: RunInput): Promise<string[]>;
 /**
  * Stop every running container for a compose project, targeted by label so this needs neither the
  * project's compose files nor its directory. Both are out of reach for a stack whose owning session
@@ -103,4 +107,4 @@ declare const wpCli: (args: string[]) => Promise<string>;
 /** Run PHP inside the active stack's loaded WordPress. */
 declare const wpEval: (php: string) => Promise<string>;
 //#endregion
-export { DockerStack, DockerStatus, RunResult, Stack, StackStatus, compose, composeDown, composePull, composeStop, composeUp, createStack, dockerAvailable, dockerHint, dockerStatus, runningProjectContainers, stackStatus, stopProjectContainers, wpCli, wpEval };
+export { DockerStack, DockerStatus, RunResult, Stack, StackStatus, compose, composeDown, composePull, composeStop, composeUp, createStack, docker, dockerAvailable, dockerHint, dockerStatus, runningProjectContainers, stackStatus, stopProjectContainers, wpCli, wpEval };

package/dist/cli/wp/docker.js

@@ -11,7 +11,9 @@ function run(cmd, args, env, opts) {
 				"pipe"
 			],
 			env,
-			detached: opts?.detached
+			detached: opts?.detached,
+			signal: opts?.signal,
+			timeout: opts?.timeout
 		});
 		let stdout = "";
 		let stderr = "";
@@ -23,15 +25,20 @@ function run(cmd, args, env, opts) {
 		});
 		child.on("error", reject);
 		child.on("close", (code) => resolvePromise({
-			code: code ?? 0,
+			code: code ?? 1,
 			stdout,
 			stderr
 		}));
+		child.stdin.on("error", reject);
 		if (opts?.inputFile !== void 0) createReadStream(opts.inputFile).on("error", reject).pipe(child.stdin);
 		else if (opts?.input !== void 0) child.stdin.end(opts.input);
 		else child.stdin.end();
 	});
 }
+/** File transfers use Docker's copy support, keeping archive/SQL bytes out of stdout. */
+function docker(args, opts) {
+	return run("docker", args, process.env, opts);
+}
 /**
 * Probe Docker in two steps: `docker --version` only touches the client (is it installed?), then
 * `docker version` contacts the server (is the daemon up?). Used before any command that needs local
@@ -62,13 +69,13 @@ async function dockerAvailable() {
 * this works from any directory and without the project's compose files. Throws when docker itself
 * could not answer, which the callers tell apart from an empty answer.
 */
-async function runningProjectContainers(project) {
+async function runningProjectContainers(project, opts) {
 	const res = await run("docker", [
 		"ps",
 		"-q",
 		"--filter",
 		`label=com.docker.compose.project=${project}`
-	], process.env);
+	], process.env, opts);
 	if (res.code !== 0) throw new Error(`docker ps failed:\n${res.stderr || res.stdout}`);
 	return res.stdout.split("\n").filter(Boolean);
 }
@@ -279,4 +286,4 @@ const wpCli = (args) => activeStack().wpCli(args);
 const wpEval = (php) => wpCli(["eval", php]);
 
 //#endregion
-export { compose, composeDown, composePull, composeStop, composeUp, createStack, dockerAvailable, dockerHint, dockerStatus, runningProjectContainers, stackStatus, stopProjectContainers, wpCli, wpEval };
+export { compose, composeDown, composePull, composeStop, composeUp, createStack, docker, dockerAvailable, dockerHint, dockerStatus, runningProjectContainers, stackStatus, stopProjectContainers, wpCli, wpEval };