kizlo 0.1.0 → 0.2.0

package/dist/cli/wp/docker.js

@@ -1,14 +1,18 @@
-import { COMPOSE } from "./constants.js";
 import { spawn } from "node:child_process";
+import { createReadStream } from "node:fs";
 
 //#region src/cli/wp/docker.ts
-function run(cmd, args, opts) {
+function run(cmd, args, env, opts) {
 	return new Promise((resolvePromise, reject) => {
-		const child = spawn(cmd, args, { stdio: [
-			"pipe",
-			"pipe",
-			"pipe"
-		] });
+		const child = spawn(cmd, args, {
+			stdio: [
+				"pipe",
+				"pipe",
+				"pipe"
+			],
+			env,
+			detached: opts?.detached
+		});
 		let stdout = "";
 		let stderr = "";
 		child.stdout.on("data", (d) => {
@@ -23,47 +27,104 @@ function run(cmd, args, opts) {
 			stdout,
 			stderr
 		}));
-		if (opts?.input !== void 0) child.stdin.end(opts.input);
+		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();
 	});
 }
-/** `docker compose <args>` against the harness compose file. */
-async function compose(args, opts) {
-	return run("docker", [...COMPOSE, ...args], opts);
-}
-/** Bring services up detached and wait for health checks. */
-async function composeUp() {
-	const res = await compose([
-		"up",
-		"-d",
-		"--wait"
-	]);
-	if (res.code !== 0) throw new Error(`docker compose up failed:\n${res.stderr}`);
-}
-/** Tear everything down, optionally removing volumes. */
-async function composeDown(opts) {
-	const args = ["down"];
-	if (opts?.volumes) args.push("-v");
-	await compose(args);
+/**
+* Whether the Docker daemon is reachable. `docker version` contacts the server (not just
+* the client), so a non-zero exit means the daemon is down or Docker isn't installed —
+* the early check before a command that needs a stack (e.g. `init`'s local setup).
+*/
+async function dockerAvailable() {
+	try {
+		return (await run("docker", ["version"], process.env)).code === 0;
+	} catch {
+		return false;
+	}
 }
-/** `docker compose stop` — halt containers but keep volumes (DB intact). */
-async function composeStop() {
-	await compose(["stop"]);
+function bind(stack) {
+	const base = [
+		"compose",
+		"-p",
+		stack.project,
+		...stack.composeFiles.flatMap((file) => ["-f", file])
+	];
+	const env = {
+		...process.env,
+		WP_PORT: String(stack.port)
+	};
+	const compose$1 = (args, opts) => run("docker", [...base, ...args], env, opts);
+	const composeUp$1 = async () => {
+		const res = await compose$1([
+			"up",
+			"-d",
+			"--wait"
+		]);
+		if (res.code !== 0) throw new Error(`docker compose up failed:\n${res.stderr}`);
+	};
+	const composeDown$1 = async (opts) => {
+		const args = ["down"];
+		if (opts?.volumes) args.push("-v");
+		await compose$1(args);
+	};
+	const composeStop$1 = async (opts) => {
+		await compose$1(["stop"], opts);
+	};
+	const publishedPort = async () => {
+		const match = (await compose$1([
+			"port",
+			"wordpress",
+			"80"
+		])).stdout.match(/:(\d+)\s*$/);
+		return match ? Number(match[1]) : void 0;
+	};
+	const wpCli$1 = async (args) => {
+		const res = await compose$1([
+			"exec",
+			"-T",
+			"wp-cli",
+			"wp",
+			...args
+		]);
+		if (res.code !== 0) throw new Error(`wp ${args.join(" ")} failed:\n${res.stderr || res.stdout}`);
+		return res.stdout.replace(/\r/g, "").trim();
+	};
+	return {
+		compose: compose$1,
+		composeUp: composeUp$1,
+		composeStop: composeStop$1,
+		composeDown: composeDown$1,
+		publishedPort,
+		wpCli: wpCli$1
+	};
 }
 /**
-* Run a wp-cli command against the warm `wp-cli` container and return trimmed stdout.
+* The stack the module-level helpers target. `createStack` sets it so fixtures —
+* which call the public `wpCli`/`compose` with no stack — hit whatever stack the
+* running command activated (the test stack during seeding).
 */
-async function wpCli(args) {
-	const res = await compose([
-		"exec",
-		"-T",
-		"wp-cli",
-		"wp",
-		...args
-	]);
-	if (res.code !== 0) throw new Error(`wp ${args.join(" ")} failed:\n${res.stderr || res.stdout}`);
-	return res.stdout.replace(/\r/g, "").trim();
+let active = null;
+/** Build a stack-bound docker helper and mark it active for the bare helpers below. */
+function createStack(stack) {
+	active = stack;
+	return bind(stack);
+}
+function activeStack() {
+	if (!active) throw new Error("No active kizlo stack — createStack() must run first.");
+	return bind(active);
 }
+/** `docker compose <args>` against the active stack. */
+const compose = (args, opts) => activeStack().compose(args, opts);
+/** Bring the active stack's services up detached and wait for health checks. */
+const composeUp = () => activeStack().composeUp();
+/** Tear the active stack down, optionally removing volumes. */
+const composeDown = (opts) => activeStack().composeDown(opts);
+/** `docker compose stop` — halt the active stack's containers but keep volumes. */
+const composeStop = (opts) => activeStack().composeStop(opts);
+/** Run a wp-cli command against the active stack's warm `wp-cli` container. */
+const wpCli = (args) => activeStack().wpCli(args);
 
 //#endregion
-export { compose, composeDown, composeStop, composeUp, wpCli };
+export { compose, composeDown, composeStop, composeUp, createStack, dockerAvailable, wpCli };

package/dist/cli/wp/ports.js

@@ -0,0 +1,72 @@
+import { createServer } from "node:net";
+
+//#region src/cli/wp/ports.ts
+/** Thrown when an explicitly-configured port is already taken — a collision the user owns. */
+var PortInUseError = class extends Error {
+	port;
+	host;
+	constructor(port, host) {
+		super(`Port ${host}:${port} is already in use`);
+		this.name = "PortInUseError";
+		this.port = port;
+		this.host = host;
+	}
+};
+/** True if `host:port` can be bound right now (i.e. nothing else is listening on it). */
+function isFree(port, host = "0.0.0.0") {
+	return new Promise((resolvePromise) => {
+		const server = createServer();
+		server.once("error", () => resolvePromise(false));
+		server.listen({
+			port,
+			host
+		}, () => server.close(() => resolvePromise(true)));
+	});
+}
+/** An OS-assigned ephemeral port on `host` — the fallback when the whole scan range is taken. */
+function ephemeralPort(host) {
+	return new Promise((resolvePromise, reject) => {
+		const server = createServer();
+		server.once("error", reject);
+		server.listen({
+			port: 0,
+			host
+		}, () => {
+			const address = server.address();
+			const port = typeof address === "object" && address ? address.port : 0;
+			server.close(() => resolvePromise(port));
+		});
+	});
+}
+/**
+* Resolve `preferred` to a host port that's actually free, scanning upward from it.
+* The configured/default value is only a *starting point*: if it (or the next few) are
+* already taken — by a stray container, another stack, or any unrelated server — we step
+* to the next free port instead of letting `docker compose up` fail with a port clash.
+* Falls back to an OS-assigned ephemeral port if the whole scan range is busy.
+*
+* `host` must match how the port is published: `0.0.0.0` for the all-interfaces WP port,
+* `127.0.0.1` for the loopback-only MySQL port — a port can be free on one and not the other.
+*/
+async function findFreePort(preferred, host = "0.0.0.0") {
+	for (let port = preferred; port < preferred + 100; port++) if (await isFree(port, host)) return port;
+	return ephemeralPort(host);
+}
+/**
+* Resolve a host port, branching on whether the value was *chosen by the user*:
+*
+* - A **default** port (`fixed: false`) is only a starting point — if it's taken (by another
+*   project's stack or any unrelated server) we step to the next free one via {@link findFreePort},
+*   so the stack comes up instead of failing on a clash.
+* - An **explicit** port (`fixed: true`, set in `kizlo.config`) is the user taking control: a
+*   collision there is theirs to resolve, so we throw {@link PortInUseError} rather than silently
+*   serving somewhere they didn't ask for.
+*/
+async function resolveHostPort(preferred, { fixed, host = "0.0.0.0" }) {
+	if (!fixed) return findFreePort(preferred, host);
+	if (await isFree(preferred, host)) return preferred;
+	throw new PortInUseError(preferred, host);
+}
+
+//#endregion
+export { PortInUseError, isFree, resolveHostPort };

package/dist/cli/wp/session.js

@@ -0,0 +1,150 @@
+import { execFile, spawn } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { promisify } from "node:util";
+import { homedir } from "node:os";
+
+//#region src/cli/wp/session.ts
+const exec = promisify(execFile);
+/**
+* Where foreground `kizlo dev` sessions are recorded, keyed by compose project.
+* Global (not per-repo) on purpose: the whole point is to reap a *different*
+* project's stack that was orphaned by a crashed session you never came back to.
+*/
+function registryPath() {
+	return join(homedir(), ".cache", "kizlo", "dev-sessions.json");
+}
+function readRegistry() {
+	const file = registryPath();
+	if (!existsSync(file)) return {};
+	try {
+		return JSON.parse(readFileSync(file, "utf8"));
+	} catch {
+		return {};
+	}
+}
+function writeRegistry(registry) {
+	const file = registryPath();
+	mkdirSync(dirname(file), { recursive: true });
+	writeFileSync(file, JSON.stringify(registry, null, 2));
+}
+/** True when a process with this PID is still alive (signal 0 probes without killing). */
+function pidAlive(pid) {
+	try {
+		process.kill(pid, 0);
+		return true;
+	} catch {
+		return false;
+	}
+}
+/**
+* Stop a compose project's containers by label, without needing its compose files.
+* Used for orphans owned by a dead PID — we can't assume we're in that project's
+* directory, so we target the running containers directly rather than via compose.
+*/
+async function stopByProject(project) {
+	const { stdout } = await exec("docker", [
+		"ps",
+		"-q",
+		"--filter",
+		`label=com.docker.compose.project=${project}`
+	]);
+	const ids = stdout.split("\n").filter(Boolean);
+	if (ids.length) await exec("docker", ["stop", ...ids]);
+}
+/**
+* Stop and remove *every* container for `project` — running or stopped — keeping its
+* volumes (the DB and bind-mounted install survive). Run right before bringing a dev
+* stack up so `compose up` creates brand-new containers instead of reconciling a stale
+* one left by a crashed session or a second invocation: reconciling an existing — often
+* unhealthy — mysql in place is what intermittently fails the dependency wait with
+* "exited (137)". Returns true if it removed anything. Best effort: a docker-down error
+* surfaces later on `up`, where the message is actionable.
+*/
+async function removeProjectContainers(project) {
+	try {
+		const { stdout } = await exec("docker", [
+			"ps",
+			"-aq",
+			"--filter",
+			`label=com.docker.compose.project=${project}`
+		]);
+		const ids = stdout.split("\n").filter(Boolean);
+		if (!ids.length) return false;
+		await exec("docker", ["stop", ...ids]).catch(() => {});
+		await exec("docker", [
+			"rm",
+			"-f",
+			...ids
+		]);
+		return true;
+	} catch {
+		return false;
+	}
+}
+/**
+* Spawn the detached watchdog that stops `project`'s stack when this process dies by
+* any means the in-process handlers can't catch (terminal closed, SIGKILL, crash).
+* Returns its PID so the graceful teardown path can kill it (the stack is already
+* being stopped, so the watchdog would have nothing to do). Best effort: a failure
+* here just means we fall back to signal handlers + the startup reaper.
+*/
+function spawnWatchdog(project) {
+	try {
+		const watchdog = fileURLToPath(new URL("./watchdog.js", import.meta.url));
+		const child = spawn(process.execPath, [
+			watchdog,
+			String(process.pid),
+			project
+		], {
+			detached: true,
+			stdio: "ignore"
+		});
+		child.unref();
+		return child.pid;
+	} catch {
+		return;
+	}
+}
+/** Record this process as the owner of `project`'s foreground stack. */
+function registerSession(project) {
+	const registry = readRegistry();
+	registry[project] = { pid: process.pid };
+	writeRegistry(registry);
+}
+/** Drop `project` from the registry (graceful teardown). Best effort. */
+function unregisterSession(project) {
+	try {
+		const registry = readRegistry();
+		if (registry[project]) {
+			delete registry[project];
+			writeRegistry(registry);
+		}
+	} catch {}
+}
+/**
+* Stop any foreground stacks whose owning session has died (SIGKILL, crash, power
+* loss) — the cases a signal handler can never catch. Runs at the start of every
+* `kizlo dev`, so leaked stacks from *any* project self-heal the next time you
+* bring one up. Returns the projects that were reaped, for logging.
+*/
+async function reapOrphans() {
+	const registry = readRegistry();
+	const reaped = [];
+	let changed = false;
+	for (const [project, session] of Object.entries(registry)) {
+		if (pidAlive(session.pid)) continue;
+		try {
+			await stopByProject(project);
+			reaped.push(project);
+		} catch {}
+		delete registry[project];
+		changed = true;
+	}
+	if (changed) writeRegistry(registry);
+	return reaped;
+}
+
+//#endregion
+export { reapOrphans, registerSession, removeProjectContainers, spawnWatchdog, unregisterSession };

package/dist/cli/wp/settings.js

@@ -0,0 +1,73 @@
+import { WP_KIZLO_BASE } from "../../wordpress/constants.js";
+import { WordPressService } from "../../wordpress/service.js";
+
+//#region src/cli/wp/settings.ts
+/** Loopback hosts that, from inside the dev Docker stack, must be rewritten to reach the host. */
+const LOOPBACK_HOSTS = new Set([
+	"localhost",
+	"127.0.0.1",
+	"0.0.0.0",
+	"::1"
+]);
+/** The origin of a URL (scheme + host + port), or undefined when it can't be parsed. */
+function originOf(url) {
+	try {
+		return new URL(url).origin;
+	} catch {
+		return;
+	}
+}
+/**
+* Rewrite a loopback host to `host.docker.internal` so the dockerized WordPress dev stack can reach a
+* Kizlo server on the host (the container's own `localhost` is not the host). Non-loopback hosts (real
+* deployments) and unparseable URLs are returned unchanged.
+*/
+function toContainerHostUrl(url) {
+	try {
+		const parsed = new URL(url);
+		if (!LOOPBACK_HOSTS.has(parsed.hostname)) return url;
+		parsed.hostname = "host.docker.internal";
+		return parsed.toString();
+	} catch {
+		return url;
+	}
+}
+/**
+* Push site-level settings into the WordPress plugin's `kizlo_settings_site` option: the shared
+* `secret` (so webhook signing/verification share a key) plus the `url`/`backend_url` the plugin
+* needs to reach the Kizlo server when delivering events. `backend_url` is the backend URL verbatim;
+* `url` is an explicit `siteUrl` when given (split deployments), otherwise the backend's origin (the
+* single-origin default used by dev + local provision). `PUT /kizlo/v1/settings/site` merges, so
+* sending only the keys we have is a safe partial update that leaves other site settings intact;
+* empty fields are omitted. Best-effort: the plugin may not be active yet (remote `init`), so
+* failures are returned, never thrown.
+*/
+async function syncSiteSettings(credentials, settings) {
+	const body = {};
+	if (settings.secret) body.secret = settings.secret;
+	const url = settings.siteUrl ?? (settings.backendUrl ? originOf(settings.backendUrl) : void 0);
+	if (settings.backendUrl) body.backend_url = settings.containerized ? toContainerHostUrl(settings.backendUrl) : settings.backendUrl;
+	if (url) body.url = url;
+	const response = await new WordPressService({ credentials }).put("settings/site", {
+		base: WP_KIZLO_BASE,
+		body
+	});
+	if (response.error) return {
+		ok: false,
+		error: describeError(response.status, response.error)
+	};
+	return { ok: true };
+}
+/**
+* A short, log-friendly summary of a failed request. A transport failure has no HTTP status (`0`), so
+* its message (e.g. `fetch failed`) is the only signal; otherwise the status code is shown — the raw
+* `error.message` can be a full HTML page (when the URL serves the frontend instead of WordPress) and
+* would flood the warning.
+*/
+function describeError(status, error) {
+	if (status === 0) return error.message;
+	return `HTTP ${status}`;
+}
+
+//#endregion
+export { syncSiteSettings };

package/dist/cli/wp/setup.js

@@ -1,8 +1,8 @@
 import { WordPressService } from "../../wordpress/service.js";
 import { credentialsPath } from "./utils.js";
 import { bootstrapWp } from "./bootstrap.js";
-import { dirname } from "node:path";
 import { mkdirSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
 
 //#region src/cli/wp/setup.ts
 /**

package/dist/cli/wp/stack.js

@@ -0,0 +1,58 @@
+import { isLocalPlugin } from "./types.js";
+import { COMPOSE_FILE } from "./constants.js";
+import { writeDevOverride, writeTestOverride } from "./compose/override.js";
+
+//#region src/cli/wp/stack.ts
+/** The local-plugin dirs to bind-mount, gathered from every fixture's `plugins`. */
+function localMounts(fixtures) {
+	return fixtures.flatMap((fixture) => fixture.plugins ?? []).filter(isLocalPlugin).map((plugin) => plugin.path);
+}
+/**
+* The test stack: the base compose file under a `<name>-test` project, plus a generated
+* mount override when any fixture carries a local (`{ path }`) plugin — so the same
+* fixtures bind-mount their live plugin source here exactly as in the dev stack.
+*/
+function testStack(cfg) {
+	const mounts = localMounts(cfg.fixtures);
+	const composeFiles = mounts.length ? [COMPOSE_FILE, writeTestOverride(cfg.configDir, mounts)] : [COMPOSE_FILE];
+	return {
+		project: cfg.project,
+		port: cfg.port,
+		composeFiles
+	};
+}
+/**
+* The host user to run the dev container as, so bind-mounted files come out owned
+* by you. Only on native Linux, where Docker doesn't remap ownership; `undefined`
+* (a no-op) on macOS/Windows, and when running as root (no benefit).
+*/
+function detectHostUser() {
+	if (process.platform !== "linux" || typeof process.getuid !== "function") return void 0;
+	const uid = process.getuid();
+	if (uid === 0) return void 0;
+	return {
+		uid,
+		gid: typeof process.getgid === "function" ? process.getgid() : uid
+	};
+}
+/**
+* The dev stack: the base compose file plus the generated mount override, under a
+* `<name>-dev` project. Building the stack (re)writes the override so it always
+* matches the current `dev.path` and the `dev.fixtures` local plugins.
+*/
+function devStack(cfg) {
+	const override = writeDevOverride(cfg.configDir, {
+		wordpressDir: cfg.wordpressDir,
+		mounts: localMounts(cfg.fixtures),
+		hostUser: detectHostUser(),
+		dbPort: cfg.dbPort
+	});
+	return {
+		project: cfg.project,
+		port: cfg.port,
+		composeFiles: [COMPOSE_FILE, override]
+	};
+}
+
+//#endregion
+export { devStack, testStack };

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

@@ -55,18 +55,39 @@ type PluginSource = string | {
   name: string;
   source: string;
 };
+/**
+ * A local plugin directory to bind-mount into the dev stack (`kizlo dev`) instead
+ * of installing it. The container gets the live files at
+ * `wp-content/plugins/<basename(path)>`, so edits show up without a reinstall, and
+ * the plugin is activated by that basename. `path` is relative to the config dir.
+ */
+type LocalPlugin = {
+  path: string;
+};
+/** A `kizlo dev` plugin entry: an installable {@link PluginSource} or a {@link LocalPlugin} to mount. */
+type DevPluginSource = PluginSource | LocalPlugin;
+/** True when a dev plugin entry is a local directory to bind-mount, not something to install. */
+declare function isLocalPlugin(plugin: DevPluginSource): plugin is LocalPlugin;
+type FixtureSeedFn = (ctx: SeedContext) => Promise<Record<string, JsonValue>>;
+type FixtureCleanupFn = (ctx: SeedContext) => Promise<void>;
 /** The serializable test layer an extension ships alongside its live extension. */
 interface Fixture {
   /** Namespace key under `TestCredentials.fixtures`. */
   name: string;
-  /** Plugins to install + activate via wp-cli during bootstrap, in order (deps first). */
-  plugins?: PluginSource[];
+  /**
+   * Plugins this fixture needs active, in order (deps first). Each entry is either
+   * an installable {@link PluginSource} (wp.org slug / zip source) or a
+   * {@link LocalPlugin} (`{ path }`) bind-mounted live from your repo — the same
+   * shape `kizlo dev` mounts, so a fixture can carry your plugin's local source
+   * and it behaves identically in the dev and test stacks (no build/zip step).
+   */
+  plugins?: DevPluginSource[];
   /** Build this extension's world once during seeding; return created handles. */
-  seed?: (ctx: SeedContext) => Promise<Record<string, JsonValue>>;
+  seed?: FixtureSeedFn;
   /** Revert per-test mutations (teardown); does NOT uninstall plugins or seeded data. */
-  cleanup?: (ctx: SeedContext) => Promise<void>;
+  cleanup?: FixtureCleanupFn;
 }
 /** Identity helper for authoring a `Fixture` with full inference and autocomplete. */
 declare function defineFixture(fixture: Fixture): Fixture;
 //#endregion
-export { Fixture, JsonValue, PluginSource, SeedContext, TestAdminUser, TestCredentials, TestUser, defineFixture };
+export { DevPluginSource, Fixture, FixtureCleanupFn, FixtureSeedFn, JsonValue, LocalPlugin, PluginSource, SeedContext, TestAdminUser, TestCredentials, TestUser, defineFixture, isLocalPlugin };

package/dist/cli/wp/types.js

@@ -1,8 +1,12 @@
 //#region src/cli/wp/types.ts
+/** True when a dev plugin entry is a local directory to bind-mount, not something to install. */
+function isLocalPlugin(plugin) {
+	return typeof plugin === "object" && "path" in plugin;
+}
 /** Identity helper for authoring a `Fixture` with full inference and autocomplete. */
 function defineFixture(fixture) {
 	return fixture;
 }
 
 //#endregion
-export { defineFixture };
+export { defineFixture, isLocalPlugin };

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

@@ -1,4 +1,4 @@
-import { PluginSource, TestCredentials } from "./types.js";
+import { DevPluginSource, PluginSource, TestCredentials } from "./types.js";
 
 //#region src/cli/wp/utils.d.ts
 
@@ -16,6 +16,12 @@ import { PluginSource, TestCredentials } from "./types.js";
 declare function isSeeded(): Promise<boolean>;
 /** Build a GitHub release-zip URL for `PluginSource.source` (asset named `<tag>.zip`). */
 declare function githubRelease(repo: string, tag: string): string;
+/**
+ * Download URL for a Kizlo plugin's latest release, served by kizlo.io (it 302s to
+ * the current GitHub release asset). Always tracks the newest published version —
+ * use {@link githubRelease} instead to pin a specific tag.
+ */
+declare function kizloRelease(slug: string): string;
 /** Resolve a `PluginSource` to the `(name, source)` pair `ensurePlugin` needs. */
 declare function resolvePluginSource(plugin: PluginSource): [name: string, source: string];
 /**
@@ -25,6 +31,21 @@ declare function resolvePluginSource(plugin: PluginSource): [name: string, sourc
  * are absent (i.e. after `wp reset` wipes the volume).
  */
 declare function ensurePlugin(name: string, source: string): Promise<void>;
+/**
+ * Activate a bind-mounted local plugin by its directory basename (the slug the
+ * mount lands at under `wp-content/plugins`). Idempotent: the files arrive via the
+ * compose bind, so there's nothing to install — just activate if it isn't already.
+ */
+declare function activateLocalPlugin(pluginPath: string): Promise<void>;
+/**
+ * Ensure every plugin is active. Installable sources go first so a bind-mounted
+ * local plugin that depends on one (e.g. a WooCommerce extension) finds it already
+ * present; then each {@link LocalPlugin} is activated by basename. A local plugin
+ * whose slug matches an installable (e.g. mounting `kizlo` over the released
+ * `kizlo`) is seen as already installed, so `ensurePlugin` activates the live
+ * files instead of downloading over them.
+ */
+declare function ensurePlugins(plugins: DevPluginSource[]): Promise<void>;
 /**
  * The directory holding `kizlo.config.*`, found by walking up from `cwd` (falling
  * back to `cwd` when none is found). Anchoring the credentials artifact here —
@@ -35,5 +56,11 @@ declare function findConfigDir(cwd?: string): string;
 /** Fixed credentials artifact path, anchored to the config root. */
 declare function credentialsPath(cwd?: string): string;
 declare function getTestCredentials(): TestCredentials;
+/**
+ * The host port the credentials artifact advertises, if it exists — the port a warm test
+ * stack is pinned to. Tests connect via this URL, so a reused stack must come back up on
+ * the same port; `undefined` means no stack has ever been seeded here (a cold boot).
+ */
+declare function recordedPort(): number | undefined;
 //#endregion
-export { credentialsPath, ensurePlugin, findConfigDir, getTestCredentials, githubRelease, isSeeded, resolvePluginSource };
+export { activateLocalPlugin, credentialsPath, ensurePlugin, ensurePlugins, findConfigDir, getTestCredentials, githubRelease, isSeeded, kizloRelease, recordedPort, resolvePluginSource };