@effected/kit 0.0.0-stage → 0.13.0

package/index.d.ts

@@ -0,0 +1,555 @@
+import { Context, Duration, Effect, FileSystem, Option, Path, Schema, Scope } from "effect";
+/**
+ * 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
+ */
+export declare const Distribution: Schema.Struct<{
+  readonly name: Schema.String;
+  readonly version: Schema.String;
+}>;
+/**
+ * A decoded {@link (Distribution:variable)}.
+ *
+ * @public
+ */
+export type Distribution = typeof Distribution.Type;
+/**
+ * The `distribution` field of a machine-readable envelope: `null` when the
+ * front end was installed directly rather than through a carrier.
+ *
+ * @public
+ */
+export declare const DistributionField: Schema.NullOr<Schema.Struct<{
+  readonly name: Schema.String;
+  readonly version: Schema.String;
+}>>;
+/**
+ * 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
+ */
+export declare const CurrentDistribution: Context.Reference<Option.Option<Distribution>>;
+/**
+ * The `via <name> <version>` suffix (prefixed with a space) a `--version`
+ * line or a startup log line appends, or `""` for a direct install.
+ *
+ * @public
+ */
+export declare const distributionSuffix: (distribution: Option.Option<Distribution>) => string;
+/**
+ * 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
+ */
+export declare const withDistributionVersion: (distribution: Option.Option<Distribution>) => ((formatVersion: (name: string, version: string) => string) => (name: string, version: string) => string);
+/**
+ * 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
+ */
+export declare const withDistribution: (distribution: Distribution | null | undefined) => <A, E, R>(self: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>;
+/**
+ * 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
+ */
+export declare class ErrorText {
+  private 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 readonly describe: (value: unknown) => string;
+  /**
+   * 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 readonly causeMessage: (value: unknown) => string | undefined;
+  /**
+   * 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 readonly of: (value: unknown) => string;
+}
+/**
+ * {@link Exclusive.run}'s required options.
+ *
+ * @public
+ */
+interface ExclusiveRunOptions {
+  /**
+   * How long the body may run once it holds the permit. Required: a lane
+   * that mutates process-global state must not be held forever by a body
+   * that never settles. The timeout interrupts the body; it never releases
+   * the permit before the body's finalizers have run.
+   */
+  readonly timeout: Duration.Input;
+}
+/**
+ * {@link Exclusive.promise}'s options.
+ *
+ * @public
+ */
+interface ExclusivePromiseOptions<A, E> {
+  /** Starts the promise. `signal` aborts when the effect is interrupted. */
+  readonly try: (signal: AbortSignal) => PromiseLike<A>;
+  /** Maps a rejection, or a synchronous throw from `try`, to the typed failure. */
+  readonly catch: (cause: unknown) => E;
+  /**
+   * On interruption, abort `signal` and resume at once instead of waiting for
+   * the promise to settle. Default `false` (abort, then wait). Set it for a
+   * promise that ignores its signal, which would otherwise hold the interrupt
+   * forever; see {@link Exclusive.promise}.
+   */
+  readonly abandon?: boolean;
+}
+declare const ExclusiveTimeout_base: Schema.Class<ExclusiveTimeout, Schema.TaggedStruct<"ExclusiveTimeout", {
+  readonly timeout: Schema.String;
+  readonly message: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * 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
+ */
+export declare class ExclusiveTimeout extends ExclusiveTimeout_base {}
+/**
+ * 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
+ */
+export declare class Exclusive {
+  private readonly semaphore;
+  private constructor();
+  /** A new lane with one permit. Bind it once (a module-level or layer-built value); every call shares it. */
+  static readonly make: Effect.Effect<Exclusive>;
+  /**
+   * 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 readonly promise: <A, E>(options: ExclusivePromiseOptions<A, E>) => Effect.Effect<A, E>;
+  /**
+   * 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.
+   */
+  readonly run: <A, E, R>(body: Effect.Effect<A, E, R>, options: ExclusiveRunOptions) => Effect.Effect<A, E | ExclusiveTimeout, Exclude<R, Scope.Scope>>;
+}
+/**
+ * The parameter shape {@link LaunchContext.resolve} takes: the process-derived
+ * facts a front end resolves once, passed in as values.
+ *
+ * @remarks
+ * Nothing here reads `process`: `argv` and `env` come from the front end's own
+ * `main.ts`. That keeps the resolution rule shared and testable while the
+ * process read stays at the one place allowed to make it.
+ *
+ * @public
+ */
+interface ResolveInput {
+  /**
+   * Positional candidates, checked in order. Pass positional arguments only —
+   * the parsed positionals of your command, never raw `process.argv.slice(2)`:
+   * every non-empty value counts as a candidate, so a `--flag` would become the
+   * project directory.
+   */
+  readonly argv?: ReadonlyArray<string> | undefined;
+  /** The environment, usually `process.env`. */
+  readonly env: Readonly<Record<string, string | undefined>>;
+  /** Env keys to try in order, for example `["OKFIT_PROJECT_DIR", "CLAUDE_PROJECT_DIR"]`. */
+  readonly keys: ReadonlyArray<string>;
+}
+/**
+ * The parameter shape {@link LaunchContext.projectDir} takes: {@link ResolveInput}
+ * plus the `cwd` fallback.
+ *
+ * @public
+ */
+interface ProjectDirInput extends ResolveInput {
+  /** The fallback, usually `process.cwd()`. */
+  readonly cwd: string;
+}
+/**
+ * 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
+ */
+export declare class LaunchContext {
+  private 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 readonly isUnsubstituted: (value: string) => boolean;
+  /**
+   * `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 readonly usable: (value: string | undefined) => Option.Option<string>;
+  /**
+   * 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 readonly resolve: (input: ResolveInput) => Option.Option<string>;
+  /**
+   * 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 readonly projectDir: (input: ProjectDirInput) => string;
+}
+/**
+ * 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
+ */
+export declare class PathContainment {
+  private 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: Path.Path, root: string, candidate: string): boolean;
+  /**
+   * 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 readonly isWithin: (root: string, candidate: string) => Effect.Effect<boolean, never, FileSystem.FileSystem | Path.Path>;
+}
+/**
+ * The working-directory half of a process, structurally. Node's `process`
+ * satisfies it; pass it in, so nothing here reads `process` itself.
+ *
+ * @public
+ */
+interface ProcessCwdHost {
+  /** The current working directory. May throw when it was deleted (`ENOENT`). */
+  cwd(): string;
+  /** Changes the working directory. Throws when `directory` cannot be entered. */
+  chdir(directory: string): void;
+}
+declare const ProcessScopeError_base: Schema.Class<ProcessScopeError, Schema.TaggedStruct<"ProcessScopeError", {
+  readonly reason: Schema.Literal<"ChdirFailed">;
+  readonly path: Schema.String;
+  readonly message: Schema.String;
+  readonly cause: Schema.Defect;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * A {@link ProcessScope} change could not be made.
+ *
+ * @remarks
+ * Audience: calling code (`reason`, `path`) and an end user (`message`).
+ * `"ChdirFailed"` means `chdir` threw for `path`; the original throw is
+ * `cause`. Nothing was changed, so nothing is restored.
+ *
+ * @public
+ */
+export declare class ProcessScopeError extends ProcessScopeError_base {}
+/**
+ * Scoped changes to process-global state, each restored when the enclosing
+ * `Scope` closes, on every exit path.
+ *
+ * @remarks
+ * Pair them with {@link Exclusive}: a scoped restore protects the next request
+ * only if no other request can run while the change is live.
+ *
+ * Both take the state they change as an argument (a {@link ProcessCwdHost},
+ * an environment record), so they read no `process` and test against plain
+ * doubles. For a temporary directory, use core's
+ * `FileSystem.makeTempDirectory` in an `Effect.acquireRelease` whose release
+ * ignores a failed removal; `makeTempDirectoryScoped`'s release dies on one,
+ * which turns a successful body into a defect.
+ *
+ * @public
+ */
+export declare class ProcessScope {
+  private constructor();
+  /**
+   * Enters `directory` and returns to the previous working directory when the
+   * scope closes.
+   *
+   * @remarks
+   * When the previous directory cannot be read (it was deleted, so `cwd()`
+   * throws), the change still happens and nothing is restored: there is no
+   * valid directory to go back to. A restore that throws is ignored for the
+   * same reason.
+   */
+  static readonly chdir: (host: ProcessCwdHost, directory: string) => Effect.Effect<void, ProcessScopeError, Scope.Scope>;
+  /**
+   * Applies `patch` to `env` and restores every patched key when the scope
+   * closes.
+   *
+   * @remarks
+   * An `undefined` value in `patch` deletes the key, and a key that was absent
+   * before is deleted again on restore. Assigning `undefined` to Node's
+   * `process.env` would store the string `"undefined"`, so neither direction
+   * ever assigns it.
+   */
+  static readonly env: (env: Record<string, string | undefined>, patch: Readonly<Record<string, string | undefined>>) => Effect.Effect<void, never, Scope.Scope>;
+}
+/**
+ * What a caller — usually an agent — should do after a failure.
+ *
+ * @remarks
+ * `hint` is the human-readable instruction. `suggestedTool` and `suggestedArgs`
+ * optionally name the tool to call next and the arguments to call it with, so
+ * an agent can act without parsing the hint. The optional keys are
+ * `optionalKey`: omit them rather than passing an explicit `undefined`, which
+ * is rejected instead of silently encoded.
+ *
+ * @example
+ * ```ts
+ * import { Remediation } from "@effected/kit"
+ *
+ * const remediation: Remediation = {
+ * 	hint: "Run the validator on the whole bundle first.",
+ * 	suggestedTool: "validate_bundle",
+ * 	suggestedArgs: { strict: true },
+ * }
+ * ```
+ *
+ * @public
+ */
+export declare const Remediation: Schema.Struct<{
+  readonly hint: Schema.String;
+  readonly suggestedTool: Schema.optionalKey<Schema.String>;
+  readonly suggestedArgs: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Unknown>>;
+}>;
+/**
+ * A decoded {@link (Remediation:variable)}.
+ *
+ * @public
+ */
+export type Remediation = typeof Remediation.Type;
+export type { ExclusivePromiseOptions, ExclusiveRunOptions, ProcessCwdHost, ProjectDirInput, ResolveInput };
+//# sourceMappingURL=index.d.ts.map

package/index.js

@@ -0,0 +1,9 @@
+import { CurrentDistribution, Distribution, DistributionField, distributionSuffix, withDistribution, withDistributionVersion } from "./Distribution.js";
+import { ErrorText } from "./ErrorText.js";
+import { Exclusive, ExclusiveTimeout } from "./Exclusive.js";
+import { LaunchContext } from "./LaunchContext.js";
+import { PathContainment } from "./PathContainment.js";
+import { ProcessScope, ProcessScopeError } from "./ProcessScope.js";
+import { Remediation } from "./Remediation.js";
+
+export { CurrentDistribution, Distribution, DistributionField, ErrorText, Exclusive, ExclusiveTimeout, LaunchContext, PathContainment, ProcessScope, ProcessScopeError, Remediation, distributionSuffix, withDistribution, withDistributionVersion };

package/internal/causeMessage.js

@@ -0,0 +1,57 @@
+import { Predicate } from "effect";
+
+// src/internal/causeMessage.ts
+/** How many nodes of a cause chain the walk reads before stopping, so a cyclic chain cannot spin. */
+const CAUSE_DEPTH = 8;
+/**
+* The message a single node carries: a thrown string, or a non-empty string `message` property. A getter or
+* proxy trap that throws is a node with no message.
+*/
+const messageAt = (node) => {
+	try {
+		const text = Predicate.isString(node) ? node : Predicate.hasProperty(node, "message") && Predicate.isString(node.message) ? node.message : void 0;
+		return text === void 0 || text.trim() === "" ? void 0 : text;
+	} catch {
+		return;
+	}
+};
+/** The next link of the chain: a node's `cause`, or `undefined` when it has none or reading it throws. */
+const causeAt = (node) => {
+	try {
+		return Predicate.hasProperty(node, "cause") ? node.cause : void 0;
+	} catch {
+		return;
+	}
+};
+/**
+* Every distinct non-empty message a preserved cause chain carries, nearest
+* first and joined with `: `, or `undefined` when nothing along it has one.
+*
+* A `Schema.Defect()` field holds whatever was thrown, so the read is guarded
+* rather than assumed: `Predicate.hasProperty` + `Predicate.isString` accepts
+* an `Error`, a cross-realm `Error` that fails `instanceof`, a plain
+* `{ message }` object and a thrown string alike. An empty or whitespace-only
+* message counts as none. The walk follows `cause` links because a wrapper's
+* text is often the generic summary and the driver's text underneath is the
+* actionable detail, yet a wrapper that composes its own context must not
+* lose it either; so nothing is dropped, and a deeper text the nearer one
+* already contains is not repeated. The walk is bounded, so a cycle terminates.
+*
+* It never throws: every property read is guarded, so a `message` getter that throws leaves that link
+* without text, and a `cause` getter that throws ends the walk with what was found so far.
+*/
+const causeMessage = (cause) => {
+	let message;
+	let node = cause;
+	for (let depth = 0; depth < CAUSE_DEPTH && node !== void 0 && node !== null; depth++) {
+		const text = messageAt(node);
+		if (text !== void 0) {
+			if (message === void 0 || text.includes(message)) message = text;
+			else if (!message.includes(text)) message = `${message}: ${text}`;
+		}
+		node = causeAt(node);
+	}
+	return message;
+};
+
+export { causeMessage };

package/package.json

@@ -1,6 +1,50 @@
 {
-  "name": "@effected/kit",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+	"name": "@effected/kit",
+	"version": "0.13.0",
+	"private": false,
+	"description": "Platform-free primitives shared by every front end of an Effect v4 tool: distribution identity, remediation, launch context, and transport-neutral process crash guards",
+	"keywords": [
+		"effect",
+		"cli",
+		"mcp",
+		"carrier",
+		"distribution",
+		"effected"
+	],
+	"homepage": "https://github.com/spencerbeggs/effected/tree/main/packages/kit#readme",
+	"bugs": {
+		"url": "https://github.com/spencerbeggs/effected/issues"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/spencerbeggs/effected.git",
+		"directory": "packages/kit"
+	},
+	"license": "MIT",
+	"author": {
+		"name": "C. Spencer Beggs",
+		"email": "spencer@beggs.codes",
+		"url": "https://spencerbeg.gs"
+	},
+	"sideEffects": false,
+	"type": "module",
+	"exports": {
+		".": {
+			"types": "./index.d.ts",
+			"import": "./index.js",
+			"default": "./index.js"
+		},
+		"./guard": {
+			"types": "./guard.d.ts",
+			"import": "./guard.js",
+			"default": "./guard.js"
+		},
+		"./package.json": "./package.json"
+	},
+	"peerDependencies": {
+		"effect": "~4.1.0"
+	},
+	"engines": {
+		"node": ">=24.11.0"
+	}
+}

package/tsdoc-metadata.json

@@ -0,0 +1,11 @@
+// This file is read by tools that parse documentation comments conforming to the TSDoc standard.
+// It should be published with your NPM package.  It should not be tracked by Git.
+{
+  "tsdocVersion": "0.12",
+  "toolPackages": [
+    {
+      "packageName": "@microsoft/api-extractor",
+      "packageVersion": "7.60.1"
+    }
+  ]
+}