@gjermundgaraba/effect-actions 0.18.2 → 0.20.0

package/docs/Testing.md

@@ -4,207 +4,174 @@ Two ways to test, and neither opens a port. `Action.client` calls an implementat
 what its handlers and its `authorize` do. `Testing.layer` answers the real routes in memory,
 through Effect's own `HttpClient`: what a surface adds, such as authentication, statuses,
 challenges and tool results as sent. The examples put a domain's tests in `test/<domain>/` and
-tests of the surfaces beside them, in `it.effect` from `@effect/vitest`, which supplies the
-`Scope` that `Action.client` and `ActionRpc.client` require, a `TestClock` and a `TestConsole`
-(both imported from `effect/testing`).
+tests of the surfaces beside them, in `it.effect` from `@effect/vitest`, which supplies a
+`Scope`, a `TestClock` and a `TestConsole` (both imported from `effect/testing`).
 
-Read this page alone, in one tool call; if its output says it was truncated, read it again alone.
-When something fails, search [Testing-failures.md](Testing-failures.md). Reading order:
-[README.md](README.md).
-
-## API
-
-Import `@gjermundgaraba/effect-actions/Testing`.
-
-| API              | Purpose                                                                      |
-| ---------------- | ---------------------------------------------------------------------------- |
-| `layer(routes)`  | A `Layer<HttpClient>` answering requests with `routes` in memory.            |
-| `layer(handler)` | A `Layer<HttpClient>` answering requests with a web handler the test serves. |
-
-MCP tools are tested with `ActionMcp.client` and `ActionMcp.request`
-([Test MCP tools](#test-mcp-tools)).
+A message the library throws says its fix; for a compiler diagnostic or Effect's own error, search [Testing-failures.md](Testing-failures.md). For one symbol, `grep -rn <symbol> node_modules/@gjermundgaraba/effect-actions/dist/`: each declaration's JSDoc carries its rules and gotchas, and this page only what an example cannot show.
 
 ## Test an implementation in process
 
 Acquire `Action.client(implementation)` and call its methods
-([Action-in-process.md](Action-in-process.md#call-actions-in-process)). A call runs the decoding,
-the `authorize` and the handler a server runs, but no authentication and no middleware. Provide
-the startup services around the test, as an entrypoint does, and what a request would carry, its
-caller first, around each call:
-
-```ts
+([Action.md](Action.md#call-actions-in-process)), as
+[notes-service/test/notes/in-process.test.ts](../examples/notes-service/test/notes/in-process.test.ts)
+does. The rules are on `Action.client`.
+
+```ts example=notes-service/test/notes/in-process.test.ts
+import { describe, expect, it } from "@effect/vitest";
+import { Effect } from "effect";
+import * as Action from "@gjermundgaraba/effect-actions/Action";
+import { CurrentUser } from "../../src/identity/Identity.js";
+import { users } from "../../src/identity/users.js";
+import { notes } from "../../src/notes/handlers.js";
+import { NoteNotFound } from "../../src/notes/Notes.js";
+import { NoteStore } from "../../src/notes/store.js";
+
+// What the implementation does, with no transport: `Action.client` runs the same decoding,
+// `authorize` and handler a server runs. The caller is provided around each call, as a server
+// provides it per request.
 const as = (user: keyof typeof users) => Effect.provideService(CurrentUser, users[user]);
 
-it.effect("keeps each user's notes their own", () =>
-  Effect.gen(function* () {
-    const client = yield* Action.client(notes);
-    const note = yield* client.createNote({ title: "Plan", body: "Draft" }).pipe(as("ada"));
-
-    expect(yield* client.listNotes().pipe(as("grace"))).toEqual({ notes: [] });
-  }).pipe(Effect.provide(NoteStore.layerMemory)),
-);
+describe("notes, in process", () => {
+  it.effect("keeps each user's notes their own", () =>
+    Effect.gen(function* () {
+      const client = yield* Action.client(notes);
+      const note = yield* client.createNote({ title: "Plan", body: "Draft" }).pipe(as("ada"));
+
+      expect(yield* client.listNotes().pipe(as("ada"))).toEqual({
+        notes: [{ id: note.id, title: "Plan" }],
+      });
+      expect(yield* client.listNotes().pipe(as("grace"))).toEqual({ notes: [] });
+
+      const missing = new NoteNotFound({ id: note.id });
+      const update = { id: note.id, body: "Mine now", revision: note.revision };
+
+      expect(yield* Effect.flip(client.getNote({ id: note.id }).pipe(as("grace")))).toEqual(
+        missing,
+      );
+      expect(yield* Effect.flip(client.updateNote(update).pipe(as("grace")))).toEqual(missing);
+      expect(yield* Effect.flip(client.deleteNote({ id: note.id }).pipe(as("grace")))).toEqual(
+        missing,
+      );
+      expect(yield* client.getNote({ id: note.id }).pipe(as("ada"))).toEqual(note);
+    }).pipe(Effect.provide(NoteStore.layerMemory)),
+  );
+
+  it.effect("refuses a write from a caller holding the read scope alone", () =>
+    Effect.gen(function* () {
+      const client = yield* Action.client(notes);
+      const create = client.createNote({ title: "Plan", body: "Draft" });
+      const refusal = yield* Effect.flip(create.pipe(as("reader")));
+
+      expect(refusal).toBeInstanceOf(Action.Forbidden);
+      expect(refusal.message).toBe("Requires notes:write.");
+    }).pipe(Effect.provide(NoteStore.layerMemory)),
+  );
+});
 ```
 
-See [notes-service/test/notes/notes.test.ts](../examples/notes-service/test/notes/notes.test.ts).
-
 - Replace the edge, not the service under test:
   [mcp-tools/test/printers/printers.test.ts](../examples/mcp-tools/test/printers/printers.test.ts)
   runs the real upstream service over a fake `HttpClient` Layer.
 - `it.effect` runs on a test clock: fork a call that waits, `TestClock.adjust`, then join it.
 - A stdio server runs the same implementations: test them here. A subprocess test adds only what
   the process adds, stdout carrying nothing but the protocol.
-- A Toolkit and a CLI need no `Testing` export: call `toolkit.handle` or script a
+- A Toolkit and a CLI need no `Testing` export: call `handle` on `yield* toolkit`, or script a
   `LanguageModel` ([assistant/test/toolkit.test.ts](../examples/assistant/test/toolkit.test.ts)),
-  and run commands with `Command.runWith`
-  ([assistant/test/commands.test.ts](../examples/assistant/test/commands.test.ts)).
+  and run commands without a process
+  ([ActionCli.md](ActionCli.md#run-actions-as-local-commands)).
 
 ## Test routes in memory
 
-Export the routes still requiring what an entrypoint chooses, give the test its own, and provide
-the layer to each test:
+Export the routes still requiring what an entrypoint chooses, give the test its own services, and
+provide `Testing.layer(routes)` to each test. What it serves, the requests it reaches, a remote
+`ActionCli` command's included, and what it cannot do are on `Testing.layer`.
 
-```ts
-const served = Testing.layer(routes).pipe(Layer.provide(NoteStore.layerMemory));
-```
+The smallest test:
 
-Under it, `ActionHttp.client(Http)` needs no `baseUrl`, and `HttpClient.get("/healthz")` reaches
-the host's own routes. Each test builds the routes anew, so each starts from an empty store. See
-[notes-service/test/routes.test.ts](../examples/notes-service/test/routes.test.ts); the smallest
-test is
-[quickstart/test/greeting/greeting.test.ts](../examples/quickstart/test/greeting/greeting.test.ts).
-
-- A service the test reads too goes around `layer` with `Layer.provideMerge`, so handlers and
-  test share one instance
-  ([kitchen-sink/test/identity/session.test.ts](../examples/kitchen-sink/test/identity/session.test.ts)).
-- Two `layer`s are two servers: a second one runs every builder again, and they share only what
-  is provided around both. For two ports, that is `Action.layer(implementations)` and the
-  services ([kitchen-sink/test/routes.test.ts](../examples/kitchen-sink/test/routes.test.ts),
-  [Action-in-process.md](Action-in-process.md#share-one-build-across-servers)).
-- The client is `layer`'s own. A fake upstream is another `HttpClient`: provide it to the service
-  that calls out ([mcp-tools/test/routes.test.ts](../examples/mcp-tools/test/routes.test.ts)).
-- Every request on `layer`'s client reaches the routes, whatever its host: a client given a
-  `baseUrl`, a remote `ActionCli` command's included, runs in memory unchanged.
-- Requests run in the test's context: a `ConfigProvider` or the test clock around the test
-  reaches middleware and handlers.
-- To send raw web `Request`s too, build one `HttpRouter.toWebHandler` and dispose it yourself;
-  `Testing.layer(web.handler)` gives the typed clients the same handler
-  ([kitchen-sink/test/request-policy.test.ts](../examples/kitchen-sink/test/request-policy.test.ts)).
+```ts example=quickstart/test/routes.test.ts
+import { expect, it } from "@effect/vitest";
+import { Effect } from "effect";
+import * as ActionHttp from "@gjermundgaraba/effect-actions/ActionHttp";
+import * as ActionMcp from "@gjermundgaraba/effect-actions/ActionMcp";
+import * as Testing from "@gjermundgaraba/effect-actions/Testing";
+import { Http } from "../src/Api.js";
+import { Greet } from "../src/greeting/Greeting.js";
+import { routes } from "../src/routes.js";
 
-## Test as a signed-in caller
-
-The routes keep their real authentication. Serve them behind their provider
-([Authentication.md](Authentication.md#verify-credentials)), and give each client its caller's
-credential:
+// The routes answer in memory: no port, and the same code the server runs.
+it.effect("greets over HTTP and as an MCP tool", () =>
+  Effect.gen(function* () {
+    const http = yield* ActionHttp.client(Http);
+    const mcp = yield* ActionMcp.client([Greet]);
 
-```ts
-const as = (token: string) => ({
-  transformClient: HttpClient.mapRequest(HttpClientRequest.bearerToken(token)),
-});
+    expect(yield* http.greet({ name: "Ada" })).toBe("Hello, Ada!");
+    expect(yield* mcp.greet({ name: "Ada" })).toBe("Hello, Ada!");
+  }).pipe(Effect.provide(Testing.layer(routes))),
+);
 ```
 
-Both clients take it: `ActionHttp.client(Http, as("reader"))` and
-`ActionMcp.client([GetStatus, ...Notes], as("ada"))`.
+[notes-service/test/routes.test.ts](../examples/notes-service/test/routes.test.ts) provides a
+store a builder yields, calls the host's own routes with `HttpClient.get("/healthz")` and signs
+callers in.
 
-- Never provide the identity to `layer`, around it or to the routes. It is a type error: only a
-  provider of their own descriptor satisfies them.
-- To change what a credential verifies as, replace the service the verifier reads (`servedWith`
-  in
-  [kitchen-sink/test/identity/identity.test.ts](../examples/kitchen-sink/test/identity/identity.test.ts)),
-  or provide a test verifier: another `Authentication.layer` of the same descriptor.
+- A service the test reads too:
+  [kitchen-sink/test/identity/session.test.ts](../examples/kitchen-sink/test/identity/session.test.ts).
+- Several `layer`s sharing one build:
+  [kitchen-sink/test/routes.test.ts](../examples/kitchen-sink/test/routes.test.ts)
+  ([Action.md](Action.md#share-one-build-across-servers)).
+- A fake upstream: [mcp-tools/test/routes.test.ts](../examples/mcp-tools/test/routes.test.ts).
+- Raw web `Request`s beside the typed clients, through one web handler the test disposes of,
+  given to `Testing.layer(handler)`:
+  [kitchen-sink/test/request-policy.test.ts](../examples/kitchen-sink/test/request-policy.test.ts).
 
-A typed client decodes a refusal to its error. To assert on the answer as sent, build the request
-(`HttpClientRequest.post`, `bearerToken`, `bodyJsonUnsafe`) and send it with `HttpClient.execute`,
-which succeeds whatever the status. Read `response.status` and
-`response.headers["www-authenticate"]`, the challenge, as that file does. The status and body of
-each case are the table in [guarantees.md](guarantees.md#wire-behavior).
+## Test as a signed-in caller
 
-## Test MCP tools
+Serve the routes behind their provider
+([Authentication.md](Authentication.md#verify-credentials)), and give each client its caller's
+credential in `transformClient`, as `as` in
+[notes-service/test/routes.test.ts](../examples/notes-service/test/routes.test.ts) does for
+`ActionHttp.client` and `ActionMcp.client` alike.
 
-`ActionMcp.client(actions, options?)` gives one method per action, calling its tool and decoding
-the result as `ActionHttp.client` decodes a route's, an image included. Pass the contract values
-the endpoint serves, such as `implementation.actions`. Its failures:
-[ActionMcp-failures.md](ActionMcp-failures.md).
-
-A method fails with the action's declared errors and the built-in ones as decoded values, and with
-`McpCallError` for any other answer: its `reason` says which, `StatusError`, `ProtocolError`,
-`NoReply`, `UndeclaredError` or `NoStructuredContent`, with what the endpoint sent, so a test
-asserts on `reason` and `Effect.catchReason("McpCallError", "StatusError", ...)` recovers one;
-structured content that does not decode as the success is a `SchemaError`, and a request that
-fails Effect's `HttpClientError`. Only a tool's result carries the action's own errors: an HTTP
-answer other than 200 decodes as a refusal, or, given the endpoint's `authentication`, as an error
-its verifier declares for a protected tool, as `ActionHttp.client` types it; otherwise it is an
-`McpCallError`
-([kitchen-sink/test/identity/identity.test.ts](../examples/kitchen-sink/test/identity/identity.test.ts)).
-
-A method decodes a refusal alike whether the endpoint answered a 401 or a 403 or returned a tool
-result in a 200 ([guarantees.md](guarantees.md#wire-behavior)): to assert which, send the call
-yourself and read its status.
-
-For that, and for what the client's types will not send or its decoding hides (`tools/list`, an
-`Origin` header, a refusal's challenge, a malformed call), build the request with
-`ActionMcp.request`. It returns a native `HttpClientRequest`:
-`yield* HttpClient.execute(ActionMcp.request("tools/call", { name: "whoAmI", arguments: {} }))`
-succeeds with the response whatever its status, to read `response.status`, `response.headers`
-and `yield* response.json`
-([kitchen-sink/test/identity/identity.test.ts](../examples/kitchen-sink/test/identity/identity.test.ts)
-asserts a 401 so, and
-[mcp-tools/test/routes.test.ts](../examples/mcp-tools/test/routes.test.ts) reads `tools/list`).
-For a web handler or `fetch`, pass an absolute `url`: `HttpClientRequest.toWebResult(request)` is
-then a `Result` holding the web `Request`, taken with `Result.getOrThrow`.
+To change what a credential verifies as, replace the service the verifier reads (`servedWith` in
+[kitchen-sink/test/identity/identity.test.ts](../examples/kitchen-sink/test/identity/identity.test.ts)),
+or provide a test verifier: another `Authentication.layer` of the same descriptor.
 
-## Test rpcs
+A typed client decodes a refusal to its error. To assert on the answer as sent, its status and
+its `www-authenticate` challenge, send the request with `HttpClient.execute`, as that file does;
+a tool call's request is built with `ActionMcp.request` ([Test MCP tools](#test-mcp-tools)).
+The status and body of each case are on `ActionHttp.layer` and on each built-in error.
 
-`Testing.layer` answers HTTP requests and cannot upgrade a WebSocket. Export the rpc layer without
-its protocol ([ActionRpc.md](ActionRpc.md#serve-the-rpcs)), and give it Effect's HTTP protocol in
-the test, on both sides:
+## Test MCP tools
 
-```ts
-const server = rpc.pipe(
-  Layer.provide(RpcServer.layerProtocolHttp({ path: "/rpc" })),
-  Layer.provide(RpcSerialization.layerJson),
-);
+`ActionMcp.client(actions, options?)` gives one method per action, calling its tool. What it
+decodes and how it fails are on `ActionMcp.client` and `McpCallError`
+([ActionMcp-failures.md](ActionMcp-failures.md)).
 
-const served = RpcClient.layerProtocolHttp({ url: "/rpc" }).pipe(
-  Layer.provide(RpcSerialization.layerJson),
-  Layer.provide(Testing.layer(server)),
-  Layer.provide(MessageStore.layerMemory),
-);
+For what the client's types will not send or its decoding hides, build the request with
+`ActionMcp.request`, which says how to send it:
+[kitchen-sink/test/identity/identity.test.ts](../examples/kitchen-sink/test/identity/identity.test.ts)
+asserts a 401, and
+[mcp-tools/test/routes.test.ts](../examples/mcp-tools/test/routes.test.ts) reads `tools/list`.
 
-const as = (token: string) => RpcClient.withHeaders({ authorization: `Bearer ${token}` });
-```
+## Test rpcs
 
-Authentication is per message, so each call carries its credential and one client serves every
-caller: `client.postMessage({ text }).pipe(as("ada"))`. See
-[live-rpc/test/routes.test.ts](../examples/live-rpc/test/routes.test.ts);
+Export the rpc layer without its protocol ([ActionRpc.md](ActionRpc.md#serve-the-rpcs)) and
+serve it under `Testing.layer`, as
+[live-rpc/test/routes.test.ts](../examples/live-rpc/test/routes.test.ts) does; the protocol each
+side takes is on `Testing.layer`.
 [live-rpc/test/browser.test.ts](../examples/live-rpc/test/browser.test.ts) tests a page's client
-the same way. To call JSON routes in the same test, merge both route layers into the one
-`Testing.layer` and give it to the protocol with `Layer.provideMerge`, which keeps its `HttpClient`
-for the test
-([kitchen-sink/test/identity/session.test.ts](../examples/kitchen-sink/test/identity/session.test.ts)).
-Effect's `RpcTest.makeClient` is no substitute: it asks for handlers of the
-binding's group, which `ActionRpc.layer` does not provide (`Handler<"…">` stays required).
+the same way, and
+[kitchen-sink/test/identity/session.test.ts](../examples/kitchen-sink/test/identity/session.test.ts)
+serves JSON routes and rpcs in one `Testing.layer`.
 
 ## Assert on errors
 
 Take the failure with `Effect.flip(call)`, which alone asserts only that the call failed, then
-assert its class and its `message` separately:
-
-```ts
-expect(refusal).toBeInstanceOf(Action.Forbidden);
-expect(refusal.message).toBe("Requires notes:write.");
-```
+assert its class and its `message` separately, as the last test of
+[notes-service/test/notes/in-process.test.ts](../examples/notes-service/test/notes/in-process.test.ts) does.
 
 `toEqual` never compares a tagged error's `message`, which is not an enumerable property:
 `expect(error).toEqual(new Action.Forbidden({ message: "anything" }))` passes for every message,
 and so does `toStrictEqual`. Other fields are compared, so `toEqual(new NoteNotFound({ id }))`
 asserts the `id`, and `toEqual(new Action.Forbidden({ scopes: ["issues:write"] }))` still needs the
-message asserted beside it. The message is all a model reads of a tool's failure.
-
-`toBeInstanceOf` narrows nothing: the flipped failure stays the union of the action's declared
-and built-in errors, so reading a field only one of them has, such as `retryAfterSeconds`, does
-not compile. Compare with `toEqual(new RateLimited({ retryAfterSeconds: 10 }))`, or narrow with
-`instanceof` first.
-
-A Toolkit raises neither a refusal nor a declared error: each is a result the model reads, so
-assert `isFailure` and `result.message`
-([assistant/test/toolkit.test.ts](../examples/assistant/test/toolkit.test.ts)).
+message asserted beside it.

package/docs/setup-failures.md

@@ -3,35 +3,11 @@
 What you see when something is wrong, and the fix. Search for a fragment of the message.
 The tasks are in [setup.md](setup.md).
 
-- `TS1149: File name '…/assistant.ts' differs from already included file name '…/Assistant.ts' only in casing`:
-  a lowercase file is named for its domain beside the domain's contract. Name lowercase files for
-  their role, such as `handlers.ts` or `turns.ts`: on a disk that ignores case the two are one file.
-- `Cannot find module '@gjermundgaraba/effect-actions'`: there is no root export. Import a
-  subpath from [Entry points](setup.md#entry-points), never the root or a `dist/` path.
-- A browser build fails with `Could not resolve "node:…"`, or warns
-  `Module "node:…" has been externalized for browser compatibility`: the page imports a file that
-  also holds server code, such as a contract beside its `Action.implement`, or an authentication
-  descriptor beside its `Authentication.layer`. Move contracts, identities, descriptors and
-  bindings to files that import no server code.
-- A page that loads Effect from an import map still bundles a second copy of Effect or of some
-  of its modules, or fails to resolve `effect/Schema` in the browser when its bundler
-  externalizes subpaths, as esbuild's `--external:effect` does: a module of the page imports an
-  Effect specifier the map does not serve. Serve the specifiers
-  [Bundle for a browser](setup.md#bundle-for-a-browser) lists, and import Effect through them in
-  the page's own modules too.
-- A page loading Effect from an import map fails with
-  `Failed to resolve module specifier "effect/Cause"` in Chromium: the map points at Effect's
-  published files and lacks a specifier Effect imports itself. Map `effect/Cause`,
-  `effect/Effect`, `effect/Exit` and `effect/Function` to the same files, or serve Effect from a
-  build that resolves its own imports.
-- A page fails at load with `does not provide an export named …`: it serves only the names it
-  uses of an Effect specifier, from a vendored module or a trimmed bundle, and the package
-  imports another. Serve each specifier whole.
-- Type errors inside `effect/*` modules after install, an unmet peer warning for `effect`,
-  such as `found 4.1.0`, or a start failing with `Cannot find module '…/effect/dist/…'` under an
-  `@effect/*` package: more than one Effect release is installed, or one outside the peer
-  range. Install the `effect` range [Install](setup.md#install) names, with every `@effect/*`
-  package at the version `effect` resolved to, such as `@effect/platform-node@4.0.4` beside
-  `effect@4.0.4`.
-- `Cannot find module 'effect/unstable/http'` (or `…/httpapi`, `…/cli`, `…/ai`): these modules
-  are now `effect/http`, `effect/http-api`, `effect/cli` and `effect/ai`.
+- `TS1149: File name '…/assistant.ts' differs from already included file name '…/Assistant.ts' only in casing`: a lowercase file is named for its domain beside the domain's contract. Name lowercase files for their role, such as `handlers.ts` or `turns.ts`: on a disk that ignores case the two are one file.
+- `Cannot find module '@gjermundgaraba/effect-actions'`: there is no root export. Import a subpath from [Entry points](setup.md#entry-points), never the root or a `dist/` path.
+- A browser build fails with `Could not resolve "node:…"`, or warns `Module "node:…" has been externalized for browser compatibility`: the page imports a file that also holds server code, such as a contract beside its `Action.implement`, or an authentication descriptor beside its `Authentication.layer`. Move contracts, identities, descriptors and bindings to files that import no server code.
+- A page that loads Effect from an import map still bundles a second copy of Effect or of some of its modules, or fails to resolve `effect/Schema` in the browser when its bundler externalizes subpaths, as esbuild's `--external:effect` does: a module of the page imports an Effect specifier the map does not serve. Serve the specifiers [Bundle for a browser](setup.md#bundle-for-a-browser) lists, and import Effect through them in the page's own modules too.
+- A page loading Effect from an import map fails with `Failed to resolve module specifier "effect/Cause"` in Chromium: the map points at Effect's published files and lacks a specifier Effect imports itself. Map `effect/Cause`, `effect/Effect`, `effect/Exit` and `effect/Function` to the same files, or serve Effect from a build that resolves its own imports.
+- A page fails at load with `does not provide an export named …`: it serves only the names it uses of an Effect specifier, from a vendored module or a trimmed bundle, and the package imports another. Serve each specifier whole.
+- Type errors inside `effect/*` modules after install, an unmet peer warning for `effect`, such as `found 4.1.0`, or a start failing with `Cannot find module '…/effect/dist/…'` under an `@effect/*` package: more than one Effect release is installed, or one outside the peer range. Install the `effect` range [Install](setup.md#install) names, with every `@effect/*` package at the version `effect` resolved to, such as `@effect/platform-node@4.0.4` beside `effect@4.0.4`.
+- `Cannot find module 'effect/unstable/http'` (or `…/httpapi`, `…/cli`, `…/ai`): these modules are now `effect/http`, `effect/http-api`, `effect/cli` and `effect/ai`.

package/docs/setup.md

@@ -3,9 +3,7 @@
 Install the package, import its modules, write the smallest program, lay out an application and
 bundle a browser client.
 
-Read this page alone, in one tool call; if its output says it was truncated, read it again alone.
-When something fails, search [setup-failures.md](setup-failures.md). Reading order:
-[README.md](README.md).
+A message the library throws says its fix; for a compiler diagnostic or Effect's own error, search [setup-failures.md](setup-failures.md).
 
 ## Install
 
@@ -18,6 +16,7 @@ pnpm add @gjermundgaraba/effect-actions effect@~4.0.4
 | Node HTTP server, stdio host or CLI | `@effect/platform-node@~4.0.4`                                  |
 | Tests                               | `vitest@^5` and `@effect/vitest@~4.0.4`, as dev dependencies    |
 | Type checking                       | `typescript@^7.0.2`, as a dev dependency                        |
+| Node's types, for `node:` imports   | `@types/node`, as a dev dependency                              |
 | Running a TypeScript entrypoint     | `tsx`, as a dev dependency: `node --import tsx <entrypoint>.ts` |
 
 The `effect` peer admits the 4.0.x patches from the oldest whose APIs the package uses, and no
@@ -26,9 +25,8 @@ minor release: a minor release may change the unstable Effect modules the surfac
 Keep the tilde in `package.json`: `^4.0.4`, which npm writes for `effect@4.0.4`, admits a minor
 release outside the peer range. `npm install effect@~4.0.4` keeps it.
 
-Node `^22.12.0 || ^24.0.0 || >=26.0.0`: the package's `engines`, where its `devEngines` is
-what developing the library itself takes. TypeScript 7 or newer. ESM only. No example ships a
-`tsconfig.json`; this one checks them. The package's modules resolve only through its
+Node `>=26`: the package's `engines`, the Node the library is developed and tested on. TypeScript 7 or newer. ESM only. The repository checks the
+examples with a stricter `tsconfig.json`; this is the minimum a project needs. The package's modules resolve only through its
 `exports`, which `"module": "nodenext"` reads, as a bundler project's
 `"moduleResolution": "bundler"` does. `"strict": true` is required, by Effect:
 
@@ -40,7 +38,8 @@ what developing the library itself takes. TypeScript 7 or newer. ESM only. No ex
     "strict": true,
     "exactOptionalPropertyTypes": true,
     "noEmit": true,
-    "skipLibCheck": true
+    "skipLibCheck": true,
+    "types": ["node"]
   },
   "include": ["src", "test"]
 }
@@ -48,18 +47,10 @@ what developing the library itself takes. TypeScript 7 or newer. ESM only. No ex
 
 ## Entry points
 
-There is no package root. Import one module per subpath, as a namespace:
-
-```ts
-import * as Action from "@gjermundgaraba/effect-actions/Action";
-import * as ActionHttp from "@gjermundgaraba/effect-actions/ActionHttp";
-import * as ActionMcp from "@gjermundgaraba/effect-actions/ActionMcp";
-import * as ActionRpc from "@gjermundgaraba/effect-actions/ActionRpc";
-import * as ActionToolkit from "@gjermundgaraba/effect-actions/ActionToolkit";
-import * as ActionCli from "@gjermundgaraba/effect-actions/ActionCli";
-import * as Authentication from "@gjermundgaraba/effect-actions/Authentication";
-import * as Testing from "@gjermundgaraba/effect-actions/Testing";
-```
+There is no package root. Import one module per subpath, as a namespace,
+`import * as Action from "@gjermundgaraba/effect-actions/Action"`.
+The modules: `Action`, `ActionHttp`, `ActionMcp`, `ActionRpc`, `ActionToolkit`, `ActionCli`,
+`Authentication`, `Testing`.
 
 Effect's own modules are subpaths of `effect` too: `effect/http` (`HttpRouter`, `HttpClient`,
 `FetchHttpClient`), `effect/http-api` (`OpenApi`, `HttpApiMiddleware`), `effect/rpc`
@@ -71,8 +62,12 @@ Effect's own modules are subpaths of `effect` too: `effect/http` (`HttpRouter`,
 One action, served as a JSON route and as an MCP tool: four declarations, each in a file of
 [quickstart/src/](../examples/quickstart/src/).
 
-```ts
-// greeting/Greeting.ts: the contract. It imports no server code.
+```ts example=quickstart/src/greeting/Greeting.ts
+import { Schema } from "effect";
+import * as Action from "@gjermundgaraba/effect-actions/Action";
+
+// A contract: what the action takes and answers, whether it changes anything, and who may
+// call it. It imports no server code, so any client can import it, a browser page included.
 export const Greet = Action.make("greet", {
   description: "Greet someone by name.",
   input: { name: Schema.String },
@@ -80,14 +75,33 @@ export const Greet = Action.make("greet", {
   readOnly: true,
   caller: Action.Anyone,
 });
+```
+
+```ts example=quickstart/src/greeting/handlers.ts
+import { Effect } from "effect";
+import * as Action from "@gjermundgaraba/effect-actions/Action";
+import { Greet } from "./Greeting.js";
 
-// greeting/handlers.ts: the implementation. Every surface takes this one value.
+// The implementation: the contract bound to its handler. Every surface takes this one value.
 export const greeting = Action.implement(Greet, ({ name }) => Effect.succeed(`Hello, ${name}!`));
+```
 
-// Api.ts: the HTTP binding, which the server serves and the client calls.
+```ts example=quickstart/src/Api.ts
+import * as ActionHttp from "@gjermundgaraba/effect-actions/ActionHttp";
+import { Greet } from "./greeting/Greeting.js";
+
+// The HTTP binding: `POST /api/greet`. The server serves it and the client calls it.
 export const Http = ActionHttp.make([Greet]);
+```
 
-// routes.ts: the surfaces as one Layer.
+```ts example=quickstart/src/routes.ts
+import { Layer } from "effect";
+import * as ActionHttp from "@gjermundgaraba/effect-actions/ActionHttp";
+import * as ActionMcp from "@gjermundgaraba/effect-actions/ActionMcp";
+import { Http } from "./Api.js";
+import { greeting } from "./greeting/handlers.js";
+
+// One implementation, two surfaces: a JSON route and an MCP tool at `/mcp`.
 export const routes = Layer.mergeAll(
   ActionHttp.layer(Http, greeting),
   ActionMcp.layerHttp(greeting, { name: "greetings", version: "1.0.0" }),
@@ -95,22 +109,15 @@ export const routes = Layer.mergeAll(
 ```
 
 Serve `routes` with `HttpRouter.serve` and a platform server layer
-([quickstart/src/server.ts](../examples/quickstart/src/server.ts)) and you have `POST /api/greet`
-and an MCP tool `greet` at `/mcp`. Call the route with the binding's typed client
-([quickstart/src/client.ts](../examples/quickstart/src/client.ts)), and test both in memory
-([quickstart/test/greeting/greeting.test.ts](../examples/quickstart/test/greeting/greeting.test.ts)).
-
-A request body has no size limit unless the host sets one
-([ActionHttp.md](ActionHttp.md#serve-the-routes)).
+([quickstart/src/server.ts](../examples/quickstart/src/server.ts)), call the route with the
+binding's typed client ([quickstart/src/client.ts](../examples/quickstart/src/client.ts)), and
+test both in memory ([quickstart/test/routes.test.ts](../examples/quickstart/test/routes.test.ts)).
 [notes-service](../examples/notes-service/) is this program grown into a service, in the same
 layout.
 
 ## Lay out an application
 
-Folders are domains; the PascalCase file in each is its contract file, which imports no server
-code; `routes.ts` holds the surfaces; each entrypoint chooses the services. An entrypoint of a
-remote surface never provides an identity: authentication supplies it per request
-([Action.md](Action.md#say-who-may-call-an-action)). The tree:
+Copy the examples' layout:
 [examples/README.md](../examples/README.md#how-they-are-laid-out).
 
 ## Bundle for a browser
@@ -126,6 +133,3 @@ promises, [live-rpc/src/browser.ts](../examples/live-rpc/src/browser.ts) over a
 - Those four modules import Effect through `effect`, `effect/http` and `effect/http-api` alone,
   and `ActionRpc` through `effect/rpc` too. A page loading Effect from an import map serves
   those, and `effect/socket` for a WebSocket client.
-- A page on another origin needs CORS on the host, answered before authentication:
-  `HttpRouter.cors`, as in
-  [kitchen-sink/src/request-policy.ts](../examples/kitchen-sink/src/request-policy.ts).

package/examples/README.md

@@ -5,14 +5,9 @@ run, with its own tests and a README that says what it shows and where. They are
 linted and tested with the library, and they ship in the package, at
 `node_modules/@gjermundgaraba/effect-actions/examples`.
 
-| Example                         | What it is                                                                                                       | Start from it when                                                      |
-| ------------------------------- | ---------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
-| [quickstart](quickstart/)       | One action, served as a JSON route and an MCP tool, called with its typed client.                                | You want the smallest thing that runs.                                  |
-| [notes-service](notes-service/) | A service with bearer authentication: a JSON API and MCP tools from one implementation, a CLI, a browser client. | You are building a service others call. Most applications are this.     |
-| [mcp-tools](mcp-tools/)         | An MCP server whose tools wrap an upstream HTTP API, over stdio and over HTTP, with an image result.             | You are putting an existing API in front of a model.                    |
-| [assistant](assistant/)         | No server: the same implementations as a model's tools, with approval of writes, and as local commands.          | A model calls your code in process, or you are building a local CLI.    |
-| [live-rpc](live-rpc/)           | Effect RPC over a WebSocket with a browser-shaped client, each message carrying its own token.                   | A client keeps a connection open, or the application speaks Effect RPC. |
-| [kitchen-sink](kitchen-sink/)   | The reference: a multi-tenant issue tracker using every module and nearly every option, with an index.           | You need a working use of one specific feature.                         |
+[quickstart](quickstart/), [notes-service](notes-service/), [mcp-tools](mcp-tools/),
+[assistant](assistant/), [live-rpc](live-rpc/) and [kitchen-sink](kitchen-sink/): which to start
+from, by what you are building, is the table in [docs/README.md](../docs/README.md#examples).
 
 ## Run one
 
@@ -25,8 +20,9 @@ vp test examples/notes-service
 ```
 
 In a project that installs the package, copy an example's directory out of `node_modules` and
-run it the same way: the examples import the package by its name. They need `tsx` and
-`@effect/platform-node` beside `effect`, and `vitest` with `@effect/vitest` for their tests.
+run it the same way: the examples import the package by its name. They need `tsx`,
+`@effect/platform-node` and `@types/node` beside `effect`, and `vitest` with `@effect/vitest` for
+their tests.
 
 ## How they are laid out