@effected/kit 0.0.0-stage → 0.12.0

package/README.md

@@ -1,3 +1,99 @@
-# Temporary Holding Version
+# @effected/kit
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![npm](https://img.shields.io/npm/v/@effected%2Fengine?label=npm&color=cb3837)](https://www.npmjs.com/package/@effected/kit)
+[![License: MIT](https://img.shields.io/badge/License-MIT-4caf50.svg)](https://opensource.org/licenses/MIT)
+[![Node.js %3E%3D24.11.0](https://img.shields.io/badge/Node.js-%3E%3D24.11.0-5fa04e.svg)](https://nodejs.org/)
+[![TypeScript 7.0](https://img.shields.io/badge/TypeScript-7.0-3178c6.svg)](https://www.typescriptlang.org/)
+
+Platform-free primitives shared by every front end of an Effect v4 tool. A carrier-pattern tool (a CLI, an MCP server, an LSP server) ships more than one bin behind one meta-package, and every one of those front ends needs to answer the same handful of questions the same way: which carrier was I installed through, and what version line does that make me. This package holds those primitives once, so a consumer's own `engine` package can depend on them without also depending on `@effected/cli-kit` or any other front end.
+
+> **Pre-`1.0.0`.** This package is part of the `@effected/*` kit, built on stable
+> Effect v4 (`effect` `~4.1.0`) and still in `0.x` development. Stable Effect
+> makes a kit `1.0.0` possible, not automatic. To keep your `effect` and
+> `@effect/*` versions on the line the kit is built and tested against, install
+> [`@effected/pnpm-plugin-effected`](https://www.npmjs.com/package/@effected/pnpm-plugin-effected).
+>
+> **Stability: unstable.** This package's API surface is not yet considered
+> complete and may change across `0.x` releases. Pin an exact version — even a
+> package marked *stable* before `1.0.0` can introduce a breaking change by
+> accident, and an exact pin turns that into a type-check error rather than a
+> runtime surprise. Full policy: [release strategy](https://github.com/spencerbeggs/effected#release-strategy).
+
+## Install
+
+```bash
+npm install @effected/kit effect
+```
+
+```bash
+pnpm add @effected/kit effect
+```
+
+Requires Node.js >=24.11.0.
+
+All `@effected/*` packages are ESM-only: the exports maps publish only `import` conditions, so `require()` — including tools that resolve in CJS mode — fails with Node's `ERR_PACKAGE_PATH_NOT_EXPORTED` rather than loading a CJS build that does not exist. Import from an ES module.
+
+`effect` v4 is the only peer dependency, and it is the only dependency of any kind — no parser, no polyfill, no platform package rides in behind it. There is no IO here: every export is a schema, a reference with a default, or a pure function.
+
+## Distribution
+
+`Distribution` is the carrier package a tool's bins were installed through — its `name` and `version`. A plain `Schema.Struct` rather than a `Schema.Class`, because it travels as a plain object inside a machine-readable envelope and is compared structurally, never constructed on its own.
+
+```ts
+import { Distribution } from "@effected/kit";
+import { Schema } from "effect";
+
+const decoded = Schema.decodeUnknownSync(Distribution)({ name: "@okfit/plugin", version: "0.5.1" });
+console.log(decoded);
+// => { name: "@okfit/plugin", version: "0.5.1" }
+```
+
+`DistributionField` is the `distribution` field of an envelope: `Schema.NullOr(Distribution)`, where `null` means the front end was installed directly rather than through a carrier — not "not yet known."
+
+## CurrentDistribution
+
+`CurrentDistribution` is a `Context.Reference<Option<Distribution>>`, not a `Context.Service`: it carries its own default (`Option.none()`), so reading it never appears in an effect's `R` and a direct install needs no provision at all. A front end's `main` provides it once, at the top of the program, once it has resolved what installed it.
+
+```ts
+import { CurrentDistribution } from "@effected/kit";
+import { Effect, Option } from "effect";
+
+const program = Effect.gen(function* () {
+  const current = yield* CurrentDistribution;
+  return Option.isSome(current) ? current.value.name : "direct install";
+});
+
+console.log(Effect.runSync(program));
+// => "direct install"
+```
+
+Providing a value scopes it to the sub-effect, the same way any `Context.Reference` scopes:
+
+```ts
+program.pipe(
+  Effect.provideService(CurrentDistribution, Option.some({ name: "@okfit/plugin", version: "0.5.1" })),
+);
+```
+
+## distributionSuffix
+
+`distributionSuffix` turns a `CurrentDistribution` read into the trailing text a `--version` line or a startup log line appends — `""` for a direct install, `" via <name> <version>"` for a carrier. A free function, not a static on `Distribution`, because a `Schema.Struct` value carries no statics to hang it from.
+
+```ts
+import { distributionSuffix } from "@effected/kit";
+import { Option } from "effect";
+
+distributionSuffix(Option.none());
+// => ""
+
+distributionSuffix(Option.some({ name: "@okfit/plugin", version: "0.5.1" }));
+// => " via @okfit/plugin 0.5.1"
+```
+
+## Tier
+
+Pure tier: `effect` is the only peer, no `process`, no `node:` import, no platform package. Nothing in the kit depends on `@effected/kit` except `@effected/mcp-kit`; `@effected/cli-kit` never does — the two sit at the same layer, both consumed by a front end, never by each other.
+
+## License
+
+[MIT](LICENSE)

package/Remediation.js

@@ -0,0 +1,33 @@
+import { Schema } from "effect";
+
+// src/Remediation.ts
+/**
+* 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
+*/
+const Remediation = Schema.Struct({
+	hint: Schema.String,
+	suggestedTool: Schema.optionalKey(Schema.String),
+	suggestedArgs: Schema.optionalKey(Schema.Record(Schema.String, Schema.Unknown))
+});
+
+export { Remediation };

package/guard.d.ts

@@ -0,0 +1,205 @@
+/**
+ * The slice of the host process {@link ProcessGuard.run} uses. Node's
+ * `process` satisfies it.
+ *
+ * @remarks
+ * Structural on purpose: the guard never reads a global, so a test passes a
+ * double and a front end passes `process` from its own `main`.
+ *
+ * @public
+ */
+interface ProcessGuardHost {
+  /** Register the `uncaughtException` listener. */
+  on(event: "uncaughtException", listener: (error: Error, origin: string) => void): unknown;
+  /** Register the `unhandledRejection` listener. */
+  on(event: "unhandledRejection", listener: (reason: unknown) => void): unknown;
+  /** Raise an `uncaughtException` to the registered listeners. Used only by {@link ProcessGuardOptions.injectCrash}. */
+  emit(event: "uncaughtException", error: Error, origin: "uncaughtException" | "unhandledRejection"): unknown;
+  /** Raise an `unhandledRejection` to the registered listeners. Used only by {@link ProcessGuardOptions.injectCrash}. */
+  emit(event: "unhandledRejection", reason: unknown, promise: Promise<unknown>): unknown;
+  /** Where every guard report is written. For a stdio server, never stdout: that is the protocol wire. */
+  readonly stderr: {
+    write(chunk: string): unknown;
+  };
+  /** End the process at once. */
+  exit(code?: number): never;
+}
+/**
+ * When a stray exception or rejection ends the process.
+ *
+ * @remarks
+ * `"exit"` exits 1 whenever it happens. `"exitBeforeConnect"` exits 1 until
+ * the caller reports the server connected with
+ * {@link ProcessGuardControl.markConnected}, then logs and keeps serving: a
+ * server that dies mid-session drops every client attached to it. `"log"`
+ * never exits.
+ *
+ * @public
+ */
+interface ProcessGuardPolicy {
+  /** For `uncaughtException`. */
+  readonly onUncaught: "exit" | "exitBeforeConnect";
+  /** For `unhandledRejection`. Defaults to `"exit"`. */
+  readonly onRejection?: "exit" | "exitBeforeConnect" | "log" | undefined;
+}
+/**
+ * One crash {@link ProcessGuardOptions.injectCrash} raises: which event, and
+ * when.
+ *
+ * @public
+ */
+interface ProcessGuardInjection {
+  /** `"load"`: before `load` is called. `"connected"`: after the first {@link ProcessGuardControl.markConnected}. */
+  readonly at: "load" | "connected";
+  /** Which event to raise. */
+  readonly kind: "uncaughtException" | "unhandledRejection";
+}
+/**
+ * What {@link ProcessGuardOptions.load} is handed: the two moments only the
+ * caller can see.
+ *
+ * @remarks
+ * Plain callbacks, so a caller with no Effect runtime (a
+ * `vscode-languageserver` server, a hand-written socket loop) uses them the
+ * same way an Effect launcher does: an MCP launcher passes `markConnected`
+ * to `McpStdio.launch`'s `onReady`; an LSP calls it once its connection is
+ * listening.
+ *
+ * @public
+ */
+interface ProcessGuardControl {
+  /**
+   * Report the server connected: from here on `"exitBeforeConnect"` logs and
+   * keeps going. Call it once the server is serving. Later calls do nothing.
+   * Safe to call after `load` has resolved, which is the usual case.
+   *
+   * @remarks
+   * For a server framed over stdio (MCP, LSP), "serving" is the moment its
+   * transport is built and reading stdin, before the first request arrives:
+   * from then on a client is attached, and a stray error should be logged,
+   * not end the session.
+   */
+  readonly markConnected: () => void;
+  /**
+   * Format every report from here on with `format`, in place of the guard's
+   * own dependency-free formatter. A `format` that throws falls back to the
+   * guard's own, so a broken formatter never hides a crash.
+   */
+  readonly useFormat: (format: (error: unknown) => string) => void;
+}
+/**
+ * Options for {@link ProcessGuard.run}.
+ *
+ * @public
+ */
+interface ProcessGuardOptions {
+  /** Prefixes every report the guard writes, as in `my-server: uncaughtException (…): …`. */
+  readonly label: string;
+  /** The process: pass `process`. */
+  readonly host: ProcessGuardHost;
+  /** Defaults to `{ onUncaught: "exit", onRejection: "exit" }`. */
+  readonly policy?: ProcessGuardPolicy | undefined;
+  /**
+   * Import, assemble and start the server. Everything that can throw while
+   * loading belongs here, behind a dynamic `import()`, so the guards are
+   * already listening when it runs. A rejection is reported as
+   * `startup failed` and exits 1, whatever the policy.
+   */
+  readonly load: (guard: ProcessGuardControl) => Promise<unknown>;
+  /**
+   * For a test of the guards themselves: raise one stray `kind` at `at`, so
+   * both halves of a policy can be driven end to end in a real process.
+   *
+   * @remarks
+   * - `"load"` raises it once both listeners are installed and before
+   *   `load` is called, then waits for the guard to handle it: `load` is
+   *   not called until the listener has run. If a test double's `exit`
+   *   throws instead of ending the process, `run` rejects with what it
+   *   threw and never calls `load`. The pre-connect half of the policy
+   *   applies, so `"exitBeforeConnect"` exits 1 here, and only an
+   *   `onRejection` of `"log"` lets the process go on to load and serve.
+   *   The report uses the guard's own formatter, since no `useFormat` has
+   *   run yet.
+   * - `"connected"` raises it after the first `markConnected`, where
+   *   `"exitBeforeConnect"` logs and keeps serving. It is never raised if
+   *   `markConnected` is never called. A throw from a test double's `exit`
+   *   there is dropped.
+   *
+   * **The `"connected"` report is asynchronous.** It is raised on a later
+   * tick, a `setTimeout(0)` after `markConnected`, so it can land after the
+   * first responses the server sends: a test that reads stderr once, right
+   * after its first response, can see nothing. Wait for the report (with
+   * `McpProcess.stderrUntil` from `@effected/mcp-kit/testing`, for an MCP
+   * server) rather than reading it once.
+   *
+   * Either is raised only through `host.emit`, on a `setTimeout(0)` tick,
+   * never as a real throw or rejection, so the guard's listeners handle it
+   * the same way under the real `process` and under a test double. Under
+   * `process`, every listener registered for the event sees it, not only
+   * the guard's. It carries an `[injected]` message; a rejection is emitted
+   * with an already-handled rejected promise. `undefined`, or an `at` or
+   * `kind` outside these values, does nothing at all. Wire it to an
+   * environment variable only a test sets.
+   */
+  readonly injectCrash?: ProcessGuardInjection | undefined;
+}
+/**
+ * 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
+ */
+export declare class ProcessGuard {
+  private 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 readonly parseInjectCrash: (value: string | undefined) => ProcessGuardInjection | undefined;
+  /** Install the guards, then run `load`. Resolves once `load` has resolved. */
+  static readonly run: (options: ProcessGuardOptions) => Promise<void>;
+}
+export type { ProcessGuardControl, ProcessGuardHost, ProcessGuardInjection, ProcessGuardOptions, ProcessGuardPolicy };
+//# sourceMappingURL=guard.d.ts.map

package/guard.js

@@ -0,0 +1,3 @@
+import { ProcessGuard } from "./ProcessGuard.js";
+
+export { ProcessGuard };