@effected/kit 0.0.0-stage → 0.13.0

package/Distribution.js

@@ -0,0 +1,90 @@
+import { Context, Effect, Option, Schema } from "effect";
+
+// src/Distribution.ts
+/**
+* The carrier package a tool's bins were installed through.
+*
+* @remarks
+* A carrier (`@scope/plugin`) re-exposes its front ends' bins and passes its
+* own identity down to each front end's `main`. A plain struct rather than a
+* `Schema.Class`, because it travels in JSON envelopes as a plain object and
+* is compared structurally.
+*
+* @public
+*/
+const Distribution = Schema.Struct({
+	name: Schema.String,
+	version: Schema.String
+});
+/**
+* The `distribution` field of a machine-readable envelope: `null` when the
+* front end was installed directly rather than through a carrier.
+*
+* @public
+*/
+const DistributionField = Schema.NullOr(Distribution);
+/**
+* The carrier this run was installed through, read anywhere without
+* appearing in `R`.
+*
+* @remarks
+* A `Context.Reference`, not a `Context.Service`: it carries its own default
+* (`Option.none()`), so a direct install needs no provision at all. A front
+* end's `main` provides it once, at the top of the program, with
+* `Effect.provideService(CurrentDistribution, Option.fromNullishOr(options.distribution))`.
+*
+* @public
+*/
+const CurrentDistribution = Context.Reference("@effected/kit/CurrentDistribution", { defaultValue: () => Option.none() });
+/**
+* The `via <name> <version>` suffix (prefixed with a space) a `--version`
+* line or a startup log line appends, or `""` for a direct install.
+*
+* @public
+*/
+const distributionSuffix = (distribution) => Option.match(distribution, {
+	onNone: () => "",
+	onSome: ({ name, version }) => ` via ${name} ${version}`
+});
+/**
+* Decorates a `--version` line formatter so its line ends with
+* {@link distributionSuffix}: `formatVersion(name, version)` followed by
+* a space and `via <carrier> <version>` when installed through a carrier,
+* unchanged for a direct install.
+*
+* @remarks
+* Shaped around `effect/cli`'s `CliOutput.Formatter["formatVersion"]`: it
+* wraps whatever formatter is in effect (a coloured default or a custom one)
+* rather than replacing it. The suffix is computed once, when the decorator is
+* applied, because the distribution is known at `main`. Data-last, for `pipe`.
+*
+* @example
+* ```ts
+* import { withDistributionVersion } from "@effected/kit";
+* import { Option } from "effect";
+*
+* const formatVersion = withDistributionVersion(Option.some({ name: "@scope/plugin", version: "2.0.0" }))(
+* 	(name, version) => `${name} ${version}`,
+* );
+* formatVersion("tool", "1.0.0"); // "tool 1.0.0 via @scope/plugin 2.0.0"
+* ```
+*
+* @public
+*/
+const withDistributionVersion = (distribution) => {
+	const suffix = distributionSuffix(distribution);
+	return (formatVersion) => (name, version) => `${formatVersion(name, version)}${suffix}`;
+};
+/**
+* Provides {@link CurrentDistribution} to `self`: `Option.some` of a carrier,
+* `Option.none()` for `null` or `undefined` (a direct install).
+*
+* @remarks
+* The one-line form of what a front end's `main` does once at the top of its
+* program. Data-last, for `pipe`.
+*
+* @public
+*/
+const withDistribution = (distribution) => (self) => Effect.provideService(self, CurrentDistribution, Option.fromNullishOr(distribution));
+
+export { CurrentDistribution, Distribution, DistributionField, distributionSuffix, withDistribution, withDistributionVersion };

package/ErrorText.js

@@ -0,0 +1,98 @@
+import { causeMessage } from "./internal/causeMessage.js";
+import { Predicate } from "effect";
+
+// src/ErrorText.ts
+const describe = (value) => {
+	if (Predicate.isString(value)) return value;
+	if (value === void 0 || value === null) return String(value);
+	if (typeof value !== "object" && typeof value !== "function") return String(value);
+	try {
+		if (Predicate.hasProperty(value, "message") && Predicate.isString(value.message)) return value.message;
+	} catch {}
+	try {
+		const json = JSON.stringify(value);
+		if (json !== void 0) return json;
+	} catch {}
+	try {
+		return String(value);
+	} catch {
+		return "[unprintable value]";
+	}
+};
+/**
+* Any value as error text, without ever throwing: the one implementation every front end of a tool uses, so a CLI and
+* an MCP server describe the same failure with the same words.
+*
+* @remarks
+* Every member is pure and total. None sanitises its result: text read from a value you do not control may carry
+* escape sequences, so sanitise it before printing it to a terminal. `@effected/cli-kit` publishes the same functions as
+* `Fmt.describe`, `Fmt.causeMessage` and `Fmt.errorText`, which delegate here.
+*
+* The anti-pattern this replaces is the per-site fallback `error instanceof Error ? error.message : String(error)`:
+* it misses an error from another realm and a plain `{ message }` object, reads nothing along the `cause` chain, and
+* throws on a value whose `toString` throws or which has no prototype.
+*
+* @example
+* ```ts
+* import { ErrorText } from "@effected/kit"
+*
+* const failure = new Error("Failed to execute statement", { cause: new Error("SQLITE_BUSY: database is locked") })
+* console.log(ErrorText.of(failure))
+* // => "Failed to execute statement: SQLITE_BUSY: database is locked"
+* console.log(ErrorText.of({ code: 7 }))
+* // => "{\"code\":7}"
+* ```
+*
+* @public
+*/
+var ErrorText = class {
+	constructor() {}
+	/**
+	* Any value as text, without ever throwing.
+	*
+	* @remarks
+	* A string is itself; a number, boolean, bigint or symbol is `String(value)`; `undefined` and `null` are
+	* `"undefined"` and `"null"`. A value with a string `message` (an `Error`, one from another realm, a plain
+	* `{ message }`) is that message, even an empty one. Anything else is its JSON, or `String(value)` when it has none
+	* (a cycle, a function), or `"[unprintable value]"` when that throws too. A getter that throws is a value with no
+	* message.
+	*
+	* For the messages along an error's `cause` chain, use {@link ErrorText.causeMessage}; for the two combined, use
+	* {@link ErrorText.of}.
+	*
+	* @param value - the value
+	*/
+	static describe = describe;
+	/**
+	* Every distinct non-empty message along a value's `cause` chain, nearest first and joined with `: `, or
+	* `undefined` when nothing along it has one.
+	*
+	* @remarks
+	* The kit's one guarded cause-message read, the one its own errors render a preserved cause with. A node's message
+	* is a thrown string or a non-empty string `message` property, read without `instanceof Error`, so an error from
+	* another realm or a plain `{ message }` object counts. A deeper message the joined text already contains is not
+	* repeated, and one that contains the joined text replaces it, so a `SqlError` wrapping SQLite's own text reads
+	* `Failed to execute statement: SQLITE_BUSY: database is locked`. It is the whole chain, not the innermost message
+	* alone. The walk stops after eight nodes, so a cyclic chain terminates.
+	*
+	* Never throws: a `message` getter that throws leaves that node without text, and a `cause` getter that throws ends
+	* the walk with the text found so far, `undefined` when there is none.
+	*
+	* @param value - the error, or whatever was thrown
+	*/
+	static causeMessage = causeMessage;
+	/**
+	* The text of an unknown failure: {@link ErrorText.causeMessage} when the chain carries a message, otherwise
+	* {@link ErrorText.describe}.
+	*
+	* @remarks
+	* Exactly `ErrorText.causeMessage(value) ?? ErrorText.describe(value)`, the fallback every I/O site would otherwise
+	* spell out by hand. An error whose message is empty and whose chain carries none is `""`, as `describe` reads it.
+	* Never throws.
+	*
+	* @param value - the error, or whatever was thrown
+	*/
+	static of = (value) => causeMessage(value) ?? describe(value);
+};
+
+export { ErrorText };

package/Exclusive.js

@@ -0,0 +1,141 @@
+import { Duration, Effect, Schema, Semaphore } from "effect";
+
+// src/Exclusive.ts
+/**
+* The body of an {@link Exclusive.run} call ran past its timeout and was
+* interrupted. Its finalizers had run, and the permit was released, by the
+* time the caller sees this.
+*
+* @remarks
+* Audience: calling code, which usually folds it into its own outcome (a tool
+* result's `{ kind: "timeout" }`). `timeout` is the formatted duration.
+*
+* @public
+*/
+var ExclusiveTimeout = class extends Schema.TaggedError()("ExclusiveTimeout", {
+	timeout: Schema.String,
+	message: Schema.String
+}) {};
+/**
+* A one-permit lane for work that mutates process-global state (the working
+* directory, the environment, a patched stream), so two requests never
+* interleave it and the state is restored before the next one starts.
+*
+* @remarks
+* Ordering, on every exit path:
+*
+* 1. Waiting for the permit is interruptible: a request cancelled while it is
+*    queued leaves the queue and never runs.
+* 2. Once the permit is held, the caller's interruption is masked until the
+*    body ends. A transport that maps a client cancel to an interrupt (an MCP
+*    server does) only drops the response; the next request still waits for
+*    the real work to finish.
+* 3. The required timeout interrupts the body, and only the body.
+* 4. The body runs in its own `Scope`: its finalizers (restoring the working
+*    directory or the environment with {@link ProcessScope}, removing a temp
+*    directory) run, then the permit is released, then the caller sees the
+*    result, an {@link ExclusiveTimeout}, or its own deferred interruption.
+*
+* A body that ignores interruption delays its timeout and the permit release
+* until it settles, as an uninterruptible region does. That is
+* deliberate, because releasing the permit while process state is still being
+* changed is the bug this lane exists to prevent. Run promise work through
+* {@link Exclusive.promise}, whose interruption aborts the signal and then
+* waits for the promise to settle; `Effect.promise` would abandon it. A
+* promise that ignores its signal and never settles therefore hangs the
+* timeout and the permit forever: give it `abandon: true`.
+*
+* **Not reentrant.** A `run` on the same lane from inside a body waits for the
+* permit its own caller holds. It never gets it: the nested call waits until
+* the outer timeout fires, which interrupts the body (and the nested wait with
+* it), so the outer `run` fails with {@link ExclusiveTimeout}. Call the inner
+* work directly instead of through the lane again.
+*
+* @example
+* ```ts
+* import { Exclusive, ProcessScope } from "@effected/kit"
+* import { Effect } from "effect"
+*
+* const lane = yield* Exclusive.make
+* const result = yield* lane.run(
+* 	Effect.gen(function* () {
+* 		yield* ProcessScope.chdir(process, root)
+* 		return yield* Exclusive.promise({ try: (signal) => runTool(signal), catch: (cause) => new ToolFailed({ cause }) })
+* 	}),
+* 	{ timeout: "2 minutes" },
+* )
+* ```
+*
+* @public
+*/
+var Exclusive = class Exclusive {
+	semaphore;
+	constructor(semaphore) {
+		this.semaphore = semaphore;
+	}
+	/** A new lane with one permit. Bind it once (a module-level or layer-built value); every call shares it. */
+	static make = Effect.map(Semaphore.make(1), (semaphore) => new Exclusive(semaphore));
+	/**
+	* A promise whose interruption aborts `signal` and then waits for the
+	* promise to settle, rather than abandoning it as `Effect.promise` and
+	* `Effect.tryPromise` do. A rejection, or a synchronous throw from `try`,
+	* fails through `catch`; a `catch` that itself throws dies with what it
+	* threw.
+	*
+	* @remarks
+	* **The default hangs on a promise that ignores its signal.** Waiting is
+	* the point: the interrupt (a lane timeout, a cancel) returns only once the
+	* promise has settled, so no work is still changing process state when the
+	* permit is released. But a promise that never observes `signal` and never
+	* settles (a test runner's `start`, a third-party call with no
+	* cancellation) holds the interrupt, the lane's timeout and the permit
+	* forever.
+	*
+	* Pass `abandon: true` for such a promise. Interruption still aborts
+	* `signal`, then resumes at once without waiting; the promise keeps running
+	* unobserved and its eventual result is dropped. Inside {@link Exclusive.run}
+	* the body's scope still closes, and its finalizers still run, before the
+	* permit is released. What abandoning gives up is the guarantee that the
+	* promise itself has stopped: choose it only when the promise cannot be
+	* stopped, and restore any state it touches in a finalizer.
+	*/
+	static promise = (options) => Effect.callback((resume, signal) => {
+		const failure = (cause) => {
+			try {
+				return Effect.fail(options.catch(cause));
+			} catch (error) {
+				return Effect.die(error);
+			}
+		};
+		let settled;
+		try {
+			settled = Promise.resolve(options.try(signal));
+		} catch (cause) {
+			resume(failure(cause));
+			return;
+		}
+		settled.then((value) => resume(Effect.succeed(value)), (cause) => resume(failure(cause)));
+		if (options.abandon === true) return;
+		return Effect.promise(() => settled.then(() => void 0, () => void 0));
+	});
+	/**
+	* Runs `body` holding this lane's permit, under the ordering in the class
+	* remarks. `body` gets its own `Scope`, closed before the permit is released.
+	*/
+	run = (body, options) => {
+		const timeout = Duration.fromInputUnsafe(options.timeout);
+		const lane = Effect.interruptible(Effect.scoped(body)).pipe(Effect.timeoutOrElse({
+			duration: timeout,
+			orElse: () => {
+				const formatted = Duration.format(timeout);
+				return Effect.fail(new ExclusiveTimeout({
+					timeout: formatted,
+					message: `Timed out after ${formatted}.`
+				}));
+			}
+		}));
+		return this.semaphore.withPermit(Effect.uninterruptible(lane)).pipe(Effect.withSpan("Exclusive.run"));
+	};
+};
+
+export { Exclusive, ExclusiveTimeout };

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 C. Spencer Beggs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/LaunchContext.js

@@ -0,0 +1,90 @@
+import { Option } from "effect";
+
+// src/LaunchContext.ts
+/**
+* Resolves where a tool launched by an agent host should treat as its project.
+*
+* @example
+* ```ts
+* import { LaunchContext } from "@effected/kit"
+*
+* const dir = LaunchContext.projectDir({
+* 	argv: [],
+* 	env: { CLAUDE_PROJECT_DIR: "/work/app" },
+* 	keys: ["MYTOOL_PROJECT_DIR", "CLAUDE_PROJECT_DIR"],
+* 	cwd: "/home/me",
+* })
+* // => "/work/app"
+* ```
+*
+* @public
+*/
+var LaunchContext = class LaunchContext {
+	constructor() {}
+	/**
+	* Whether a value still carries a literal `${VAR}` placeholder.
+	*
+	* @remarks
+	* An agent host can pass `${CLAUDE_PROJECT_DIR}` through unsubstituted in
+	* some launch paths; a path containing a placeholder is never what was meant.
+	*/
+	static isUnsubstituted = (value) => {
+		const open = value.indexOf("${");
+		return open !== -1 && value.indexOf("}", open + 2) !== -1;
+	};
+	/**
+	* `value` trimmed, when it names something: `Option.none()` for `undefined`,
+	* an empty or whitespace-only string, or a string still carrying a literal
+	* `${VAR}` placeholder ({@link LaunchContext.isUnsubstituted}).
+	*
+	* @remarks
+	* The guard every resolver here applies; use it directly for one positional
+	* argument, as in `LaunchContext.usable(argv[2])`. `??` would accept an empty
+	* string or a literal `${VAR}`, neither of which names a directory or an id.
+	*/
+	static usable = (value) => {
+		if (value === void 0) return Option.none();
+		const trimmed = value.trim();
+		return trimmed === "" || LaunchContext.isUnsubstituted(trimmed) ? Option.none() : Option.some(trimmed);
+	};
+	/**
+	* The first {@link LaunchContext.usable} `argv` value, then the first usable
+	* `env` value in `keys` order; `Option.none()` when none is usable.
+	*
+	* @remarks
+	* The resolver under {@link LaunchContext.projectDir}, without its `cwd`
+	* fallback, for any launch-supplied location: a host's plugin data
+	* directory, then an app override, with the caller's own fallback after
+	* it. Values are trimmed, so a value with surrounding whitespace resolves to
+	* the trimmed path.
+	*
+	* @example
+	* ```ts
+	* import { LaunchContext } from "@effected/kit"
+	* import { Option } from "effect"
+	*
+	* const dataDir = LaunchContext.resolve({ env, keys: ["CLAUDE_PLUGIN_DATA", "MYTOOL_DATA_DIR"] }).pipe(
+	* 	Option.getOrElse(() => `${home}/.mytool`),
+	* )
+	* ```
+	*/
+	static resolve = (input) => {
+		for (const value of input.argv ?? []) {
+			const found = LaunchContext.usable(value);
+			if (Option.isSome(found)) return found;
+		}
+		for (const key of input.keys) {
+			const found = LaunchContext.usable(input.env[key]);
+			if (Option.isSome(found)) return found;
+		}
+		return Option.none();
+	};
+	/**
+	* The first usable argv value, then the first usable env value in `keys`
+	* order, then `cwd`: {@link LaunchContext.resolve} with `cwd` as the
+	* fallback.
+	*/
+	static projectDir = (input) => Option.getOrElse(LaunchContext.resolve(input), () => input.cwd);
+};
+
+export { LaunchContext };

package/PathContainment.js

@@ -0,0 +1,90 @@
+import { Effect, FileSystem, Path } from "effect";
+
+// src/PathContainment.ts
+/** Link hops followed before a candidate is judged outside (a loop never settles). */
+const MAX_LINK_HOPS = 40;
+/** Whether a platform failure means "nothing is there", the only failure read as absent. */
+const isNotFound = (error) => error.reason?._tag === "NotFound";
+/**
+* Decides whether a caller-supplied path stays inside a root.
+*
+* @remarks
+* Audience: a handler that must refuse a path outside its workspace before
+* reading or writing it. Neither form fails: "outside" is the answer `false`,
+* and the filesystem is required in `R` from core, never owned here. A
+* relative `candidate` is resolved against `root`, never the process working
+* directory.
+*
+* {@link PathContainment.isWithinLexical} is pure and compares spellings, so a
+* link inside the root that points out is invisible to it. Use
+* {@link PathContainment.isWithin} for anything that will touch the disk.
+*
+* @public
+*/
+var PathContainment = class PathContainment {
+	constructor() {}
+	/**
+	* Whether `candidate` is `root` or lies under it, comparing resolved
+	* spellings only (`..` segments and trailing separators are normalised;
+	* links are not followed). A sibling sharing a prefix (`/repo-other` against
+	* `/repo`) is outside. A relative `candidate` is resolved against `root`.
+	*/
+	static isWithinLexical(path, root, candidate) {
+		const base = path.resolve(root);
+		const target = path.resolve(base, candidate);
+		if (target === base) return true;
+		const relative = path.relative(base, target);
+		return relative !== "" && relative !== ".." && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative);
+	}
+	/**
+	* Whether `candidate` is `root` or lies under it once links are resolved.
+	*
+	* @remarks
+	* The candidate need not exist: its nearest existing ancestor is resolved
+	* with `realPath` and the missing tail appended, so a path about to be
+	* created is judged by where its parent really is. A component that is a
+	* dangling link is followed to where it points (a link out of the root is
+	* outside even when its target is absent), up to a fixed number of hops;
+	* a loop is outside.
+	*
+	* Fails closed: only a `NotFound` counts as absent. Any other failure on a
+	* candidate component (permission denied, a link loop, a non-directory
+	* parent) answers `false`. The lexical answer stands in only when the root's
+	* own real path is `NotFound`; any other failure reading it is `false`.
+	*
+	* A point-in-time check: the filesystem can change between this answer and
+	* the read or write it guards.
+	*/
+	static isWithin = (root, candidate) => Effect.gen(function* () {
+		const fs = yield* FileSystem.FileSystem;
+		const path = yield* Path.Path;
+		const base = path.resolve(root);
+		const realRoot = yield* Effect.result(fs.realPath(base));
+		if (realRoot._tag === "Failure") return isNotFound(realRoot.failure) && PathContainment.isWithinLexical(path, root, candidate);
+		let existing = path.resolve(base, candidate);
+		let tail = [];
+		let hops = 0;
+		for (;;) {
+			const real = yield* Effect.result(fs.realPath(existing));
+			if (real._tag === "Success") return PathContainment.isWithinLexical(path, realRoot.success, path.join(real.success, ...tail));
+			if (!isNotFound(real.failure)) return false;
+			const link = yield* Effect.result(fs.readLink(existing));
+			if (link._tag === "Success") {
+				hops += 1;
+				if (hops > MAX_LINK_HOPS) return false;
+				const parent = yield* Effect.result(fs.realPath(path.dirname(existing)));
+				if (parent._tag === "Failure") return false;
+				existing = path.resolve(parent.success, link.success, ...tail);
+				tail = [];
+				continue;
+			}
+			if (!isNotFound(link.failure)) return false;
+			const parent = path.dirname(existing);
+			if (parent === existing) return false;
+			tail = [path.basename(existing), ...tail];
+			existing = parent;
+		}
+	});
+};
+
+export { PathContainment };

package/ProcessGuard.js

@@ -0,0 +1,144 @@
+// src/ProcessGuard.ts
+const isInjectedKind = (kind) => kind === "uncaughtException" || kind === "unhandledRejection";
+const INJECT_AT = ["load", "connected"];
+const INJECT_KIND = ["uncaughtException", "unhandledRejection"];
+/** Emit one injected crash through the host, to the listeners the guard installed there. */
+const emitInjected = (host, kind) => {
+	const error = /* @__PURE__ */ new Error(`[injected] ${kind}`);
+	if (kind === "uncaughtException") {
+		host.emit("uncaughtException", error, "uncaughtException");
+		return;
+	}
+	const promise = Promise.reject(error);
+	promise.catch(() => void 0);
+	host.emit("unhandledRejection", error, promise);
+};
+const fallbackFormat = (error) => error instanceof Error ? error.stack ?? error.message : String(error);
+/**
+* Transport-neutral crash guards for a server process, installed before the
+* server's module graph loads. Imported from `@effected/kit/guard`.
+*
+* @remarks
+* {@link ProcessGuard.run} registers `uncaughtException` and
+* `unhandledRejection` listeners on `host`, then awaits `load`. It launches
+* nothing itself: `load` starts the server, over whatever transport, and
+* calls `markConnected` once it is serving. `@effected/mcp-kit/guard`'s
+* `McpGuard.run` is this guard with an MCP stdio launch in its `load`.
+*
+* - This entrypoint has no runtime import at all, so a throw while the
+*   server graph evaluates is still reported on stderr.
+* - A `load` that rejects is reported as `startup failed` and exits 1
+*   whatever the policy. Left to a log-only rejection listener, it would let
+*   the event loop drain and exit 0 with no server.
+* - Installing an `unhandledRejection` listener switches off Node's default
+*   of throwing on one, so `"log"` really does keep the process running.
+* - An exit from a guard skips every finalizer the server registered.
+* - Every report is one line: `<label>: uncaughtException (<origin>): …`,
+*   `<label>: unhandledRejection: …` or `<label>: startup failed: …`.
+*
+* @example
+* ```ts
+* import { ProcessGuard } from "@effected/kit/guard";
+*
+* await ProcessGuard.run({
+*   label: "my-lsp",
+*   host: process,
+*   policy: { onUncaught: "exitBeforeConnect", onRejection: "log" },
+*   load: async (guard) => {
+*     const { startServer } = await import("./server.js");
+*     await startServer();
+*     guard.markConnected();
+*   },
+* });
+* ```
+*
+* @public
+*/
+var ProcessGuard = class {
+	constructor() {}
+	/**
+	* Parse a test-only crash-injection setting into {@link ProcessGuardOptions.injectCrash}: `<at>:<kind>`, where `at`
+	* is `"load"` or `"connected"` and `kind` is `"uncaughtException"` or `"unhandledRejection"`. Anything else, or no
+	* value, is `undefined` (no injection), so a launcher can pass an environment variable straight through and every
+	* launcher shares one grammar.
+	*
+	* @example
+	* ```ts
+	* ProcessGuard.parseInjectCrash("connected:unhandledRejection"); // => { at: "connected", kind: "unhandledRejection" }
+	* ProcessGuard.parseInjectCrash("later:boom"); // => undefined
+	* ```
+	*/
+	static parseInjectCrash = (value) => {
+		if (value === void 0) return void 0;
+		const [at, kind, ...rest] = value.split(":");
+		if (rest.length > 0) return void 0;
+		const validAt = INJECT_AT.find((candidate) => candidate === at);
+		const validKind = INJECT_KIND.find((candidate) => candidate === kind);
+		return validAt === void 0 || validKind === void 0 ? void 0 : {
+			at: validAt,
+			kind: validKind
+		};
+	};
+	/** Install the guards, then run `load`. Resolves once `load` has resolved. */
+	static run = async (options) => {
+		const { host, label } = options;
+		const onUncaught = options.policy?.onUncaught ?? "exit";
+		const onRejection = options.policy?.onRejection ?? "exit";
+		let connected = false;
+		let format = fallbackFormat;
+		const describe = (error) => {
+			try {
+				return format(error);
+			} catch {
+				try {
+					return fallbackFormat(error);
+				} catch {
+					return "<unformattable error value>";
+				}
+			}
+		};
+		const exits = (mode) => mode === "exit" || mode === "exitBeforeConnect" && !connected;
+		host.on("uncaughtException", (error, origin) => {
+			host.stderr.write(`${label}: uncaughtException (${origin}): ${describe(error)}\n`);
+			if (exits(onUncaught)) host.exit(1);
+		});
+		host.on("unhandledRejection", (reason) => {
+			host.stderr.write(`${label}: unhandledRejection: ${describe(reason)}\n`);
+			if (exits(onRejection)) host.exit(1);
+		});
+		const inject = options.injectCrash;
+		const injectKind = isInjectedKind(inject?.kind) ? inject.kind : void 0;
+		if (inject?.at === "load" && injectKind !== void 0) await new Promise((resolve, reject) => {
+			setTimeout(() => {
+				try {
+					emitInjected(host, injectKind);
+					resolve();
+				} catch (error) {
+					reject(error);
+				}
+			}, 0);
+		});
+		const control = {
+			markConnected: () => {
+				if (connected) return;
+				connected = true;
+				if (inject?.at === "connected" && injectKind !== void 0) setTimeout(() => {
+					try {
+						emitInjected(host, injectKind);
+					} catch {}
+				}, 0);
+			},
+			useFormat: (next) => {
+				format = next;
+			}
+		};
+		try {
+			await options.load(control);
+		} catch (error) {
+			host.stderr.write(`${label}: startup failed: ${describe(error)}\n`);
+			host.exit(1);
+		}
+	};
+};
+
+export { ProcessGuard };