@gjermundgaraba/effect-actions 0.11.0 → 0.12.0

package/examples/mcp-tools/test/printers/printers.test.ts

@@ -0,0 +1,189 @@
+import { describe, expect, it } from "@effect/vitest";
+import { ConfigProvider, Effect, Fiber, Layer } from "effect";
+import {
+  HttpClient,
+  HttpClientError,
+  type HttpClientRequest,
+  HttpClientResponse,
+} from "effect/http";
+import { TestClock } from "effect/testing";
+import * as Action from "@gjermundgaraba/effect-actions/Action";
+import { fakeFarm } from "../../src/printers/fake.js";
+import { PrintFarm } from "../../src/printers/farm.js";
+import { printers } from "../../src/printers/handlers.js";
+import { PrintFarmError } from "../../src/printers/Printers.js";
+
+// What the tools do, with no transport: `Action.client` runs the same decoding and the same
+// handlers a server runs. A public action has no caller, so a call needs none provided.
+
+// The real `PrintFarm` over an upstream of the test's: its requests, its sign-in and its error
+// mapping all run, and only the network is replaced. Its settings come from a Layer too.
+const farmOver = (upstream: Layer.Layer<HttpClient.HttpClient>) =>
+  PrintFarm.layer.pipe(
+    Layer.provide(upstream),
+    Layer.provide(
+      ConfigProvider.layer(
+        ConfigProvider.fromEnvRecord({
+          FARM_URL: "https://farm.example.test",
+          FARM_USER: "agent",
+          FARM_PASSWORD: "secret",
+        }),
+      ),
+    ),
+  );
+
+// The fake farm, noting each request the service sends it. A request is noted as the service
+// wrote it, before its client prepends FARM_URL, so the paths are relative.
+const noting = (sent: Array<string>) =>
+  Layer.effect(
+    HttpClient.HttpClient,
+    Effect.map(
+      HttpClient.HttpClient,
+      HttpClient.tapRequest((request) =>
+        Effect.sync(() => sent.push(`${request.method} ${request.url}`)),
+      ),
+    ),
+  ).pipe(Layer.provide(fakeFarm));
+
+// A farm that lets the service sign in, then answers every other request with `answer`.
+const farmThat = (
+  answer: (
+    request: HttpClientRequest.HttpClientRequest,
+  ) => Effect.Effect<HttpClientResponse.HttpClientResponse, HttpClientError.HttpClientError>,
+) =>
+  Layer.succeed(
+    HttpClient.HttpClient,
+    HttpClient.make((request, url) =>
+      url.pathname === "/api/login"
+        ? Effect.succeed(HttpClientResponse.fromWeb(request, Response.json({ token: "session" })))
+        : answer(request),
+    ),
+  );
+
+const door = { id: "mk4-1", name: "MK4 by the door" };
+
+describe("printers, in process", () => {
+  it.effect("pauses, resumes and cancels a job, each call safe to repeat", () =>
+    Effect.gen(function* () {
+      const client = yield* Action.client(printers);
+      const pause = client.set_paused({ printer_id: "mk4-1", paused: true });
+      const cancel = client.cancel_print({ printer_id: "mk4-1" });
+      const job = { file: "bracket.gcode", progress: 62 };
+
+      expect(yield* pause).toEqual({ ...door, state: "paused", job });
+      expect(yield* pause).toEqual({ ...door, state: "paused", job });
+      expect(yield* client.set_paused({ printer_id: "mk4-1", paused: false })).toEqual({
+        ...door,
+        state: "printing",
+        job,
+      });
+      expect(yield* cancel).toEqual({ ...door, state: "idle", job: null });
+      expect(yield* cancel).toEqual({ ...door, state: "idle", job: null });
+    }).pipe(Effect.provide(farmOver(fakeFarm))),
+  );
+
+  it.effect("signs in once at startup, however many tools are called", () => {
+    const sent: Array<string> = [];
+
+    return Effect.gen(function* () {
+      const client = yield* Action.client(printers);
+
+      yield* client.list_printers();
+      yield* client.set_paused({ printer_id: "mk4-1", paused: true });
+
+      expect(sent).toEqual([
+        "POST /api/login",
+        "GET /api/printers",
+        "POST /api/printers/mk4-1/pause",
+      ]);
+    }).pipe(Effect.provide(farmOver(noting(sent))));
+  });
+
+  it.effect("refuses an id that could leave its place in the farm's URL, sending nothing", () => {
+    const sent: Array<string> = [];
+
+    return Effect.gen(function* () {
+      const client = yield* Action.client(printers);
+
+      for (const printer_id of ["..", "mk4-1/../..", "mk4-1?force=true", ""]) {
+        const refused = yield* Effect.flip(client.cancel_print({ printer_id }));
+
+        expect(refused).toBeInstanceOf(Action.InvalidInput);
+      }
+
+      expect(sent).toEqual(["POST /api/login"]);
+    }).pipe(Effect.provide(farmOver(noting(sent))));
+  });
+
+  // The message is all a model gets of a failure, so each test asserts it. `toEqual` with an
+  // expected error would not: an error's `message` is not among the properties it compares.
+  it.effect("fails with the declared error, carrying the farm's own reason", () =>
+    Effect.gen(function* () {
+      const client = yield* Action.client(printers);
+      const busy = yield* Effect.flip(client.start_print({ printer_id: "mk4-1", file: "a.gcode" }));
+      const unknown = yield* Effect.flip(client.get_camera_snapshot({ printer_id: "mk9" }));
+
+      expect(busy).toBeInstanceOf(PrintFarmError);
+      expect(busy.message).toBe(
+        "The print farm refused: MK4 by the door is busy with bracket.gcode.",
+      );
+      expect(unknown).toBeInstanceOf(PrintFarmError);
+      expect(unknown.message).toBe("The print farm refused: No printer has the id mk9.");
+    }).pipe(Effect.provide(farmOver(fakeFarm))),
+  );
+
+  it.effect("says so when the farm cannot be reached", () =>
+    Effect.gen(function* () {
+      const client = yield* Action.client(printers);
+      const error = yield* Effect.flip(client.list_printers());
+
+      expect(error).toBeInstanceOf(PrintFarmError);
+      expect(error.message).toBe("The print farm could not be reached.");
+    }).pipe(
+      Effect.provide(
+        farmOver(
+          farmThat((request) =>
+            Effect.fail(
+              new HttpClientError.HttpClientError({
+                reason: new HttpClientError.TransportError({ request }),
+              }),
+            ),
+          ),
+        ),
+      ),
+    ),
+  );
+
+  it.effect("says so when the farm answers in a shape the service does not know", () =>
+    Effect.gen(function* () {
+      const client = yield* Action.client(printers);
+      const error = yield* Effect.flip(client.list_printers());
+
+      expect(error).toBeInstanceOf(PrintFarmError);
+      expect(error.message).toBe("The print farm sent an answer this server could not read.");
+    }).pipe(
+      Effect.provide(
+        farmOver(
+          farmThat((request) =>
+            Effect.succeed(HttpClientResponse.fromWeb(request, Response.json({ rows: [] }))),
+          ),
+        ),
+      ),
+    ),
+  );
+
+  // `it.effect` runs on a test clock, so the thirty seconds pass when the test says so.
+  it.effect("gives up on a farm that does not answer", () =>
+    Effect.gen(function* () {
+      const client = yield* Action.client(printers);
+      const call = yield* Effect.forkChild(Effect.flip(client.list_printers()));
+
+      yield* TestClock.adjust("30 seconds");
+
+      const error = yield* Fiber.join(call);
+
+      expect(error).toBeInstanceOf(PrintFarmError);
+      expect(error.message).toBe("The print farm did not answer in time.");
+    }).pipe(Effect.provide(farmOver(farmThat(() => Effect.never)))),
+  );
+});

package/examples/mcp-tools/test/routes.test.ts

@@ -0,0 +1,202 @@
+import { describe, expect, it } from "@effect/vitest";
+import { ConfigProvider, Effect, Layer, Schema } from "effect";
+import { HttpClient, HttpClientRequest, HttpClientResponse } from "effect/http";
+import * as Testing from "@gjermundgaraba/effect-actions/Testing";
+import { fakeFarm, picture } from "../src/printers/fake.js";
+import { PrintFarm } from "../src/printers/farm.js";
+import { PrintFarmError, Printers } from "../src/printers/Printers.js";
+import { routes } from "../src/routes.js";
+
+// What the MCP surface adds: the tools as listed, their results as sent, the origin check.
+// The real routes answer in memory, and no port is opened.
+
+// What the entrypoint reads from the environment, given to the test as a Layer.
+const farm = { FARM_URL: "https://farm.example.test", FARM_USER: "agent", FARM_PASSWORD: "secret" };
+
+// `Testing.layer` gives the test an `HttpClient` of its own, which reaches the routes. The
+// fake farm is another `HttpClient`, provided to `PrintFarm.layer` alone.
+const servedWith = (environment: Record<string, string>) =>
+  Testing.layer(routes).pipe(
+    Layer.provide(PrintFarm.layer.pipe(Layer.provide(fakeFarm))),
+    Layer.provide(ConfigProvider.layer(ConfigProvider.fromEnvRecord(environment))),
+  );
+
+const served = servedWith({
+  ...farm,
+  ALLOWED_ORIGINS: "https://console.example.test,https://wall.example.test",
+});
+
+// A browser's preflight: what it asks before a cross-origin `POST` with an MCP client's headers.
+const preflight = (origin: string) =>
+  HttpClient.execute(
+    HttpClientRequest.make("OPTIONS")("/mcp", {
+      headers: {
+        origin,
+        "access-control-request-method": "POST",
+        "access-control-request-headers": "content-type, mcp-protocol-version",
+      },
+    }),
+  );
+
+// One tool of a `tools/list` answer, as far as this test reads it.
+const Listed = Schema.Struct({
+  result: Schema.Struct({
+    tools: Schema.Array(
+      Schema.Struct({
+        name: Schema.String,
+        annotations: Schema.Struct({
+          title: Schema.String,
+          readOnlyHint: Schema.Boolean,
+          destructiveHint: Schema.Boolean,
+          idempotentHint: Schema.Boolean,
+        }),
+      }),
+    ),
+  }),
+});
+
+describe("the tools, over MCP", () => {
+  it.effect("lists every tool with the hints its contract states", () =>
+    Effect.gen(function* () {
+      // A raw request, for what no typed client shows: here, the listing itself.
+      const response = yield* HttpClient.execute(Testing.mcpRequest("tools/list"));
+      const { result } = yield* HttpClientResponse.schemaBodyJson(Listed)(response);
+
+      const hints = (readOnlyHint: boolean, destructiveHint: boolean, idempotentHint: boolean) => ({
+        readOnlyHint,
+        destructiveHint,
+        idempotentHint,
+      });
+
+      expect(result.tools).toEqual([
+        {
+          name: "list_printers",
+          annotations: { title: "List printers", ...hints(true, false, false) },
+        },
+        {
+          name: "get_camera_snapshot",
+          annotations: { title: "Camera snapshot", ...hints(true, false, false) },
+        },
+        {
+          name: "start_print",
+          annotations: { title: "Start a print", ...hints(false, false, false) },
+        },
+        {
+          name: "set_paused",
+          annotations: { title: "Pause or resume a print", ...hints(false, false, true) },
+        },
+        {
+          name: "cancel_print",
+          annotations: { title: "Cancel a print", ...hints(false, true, true) },
+        },
+      ]);
+    }).pipe(Effect.provide(served)),
+  );
+
+  it.effect("answers a camera's picture as an image beside the printer", () =>
+    Effect.gen(function* () {
+      // A client method per tool: it sends `tools/call` and decodes the result, the image
+      // from its image block, as the handler returned it.
+      const mcp = yield* Testing.mcpClient(Printers);
+
+      expect(yield* mcp.get_camera_snapshot({ printer_id: "mk4-1" })).toEqual({
+        printer: {
+          id: "mk4-1",
+          name: "MK4 by the door",
+          state: "printing",
+          job: { file: "bracket.gcode", progress: 62 },
+        },
+        image: { data: picture, mimeType: "image/png" },
+      });
+    }).pipe(Effect.provide(served)),
+  );
+
+  it.effect("answers the farm's refusal as the tool's declared error, message and all", () =>
+    Effect.gen(function* () {
+      const mcp = yield* Testing.mcpClient(Printers);
+      const error = yield* Effect.flip(mcp.get_camera_snapshot({ printer_id: "mini-1" }));
+
+      expect(error).toBeInstanceOf(PrintFarmError);
+      expect(error.message).toBe("The print farm refused: Mini on the shelf is offline.");
+    }).pipe(Effect.provide(served)),
+  );
+
+  it.effect("accepts the browser origins the configuration lists, and no other", () =>
+    Effect.gen(function* () {
+      const from = (origin: string) =>
+        HttpClient.execute(Testing.mcpRequest("tools/list", {}, { headers: { origin } }));
+
+      expect((yield* from("https://console.example.test")).status).toBe(200);
+      expect((yield* from("https://wall.example.test")).status).toBe(200);
+      expect((yield* from("https://elsewhere.example.test")).status).toBe(403);
+    }).pipe(Effect.provide(served)),
+  );
+
+  it.effect("answers a listed origin's CORS preflight, and its headers on a tool's answer", () =>
+    Effect.gen(function* () {
+      const asked = yield* preflight("https://console.example.test");
+
+      expect(asked.status).toBe(204);
+      expect(asked.headers["access-control-allow-origin"]).toBe("https://console.example.test");
+      expect(asked.headers["access-control-allow-methods"]).toBe("POST, DELETE");
+      expect(asked.headers["access-control-allow-headers"]).toContain("MCP-Protocol-Version");
+
+      const listed = yield* HttpClient.execute(
+        Testing.mcpRequest(
+          "tools/list",
+          {},
+          { headers: { origin: "https://console.example.test" } },
+        ),
+      );
+
+      expect(listed.headers["access-control-allow-origin"]).toBe("https://console.example.test");
+      expect(listed.headers["access-control-expose-headers"]).toContain("Mcp-Session-Id");
+
+      // Two origins are configured, so each request's own is compared with the list.
+      expect((yield* preflight("https://elsewhere.example.test")).headers).not.toHaveProperty(
+        "access-control-allow-origin",
+      );
+    }).pipe(Effect.provide(served)),
+  );
+
+  it.effect("names its one configured origin to every preflight, and still refuses any other", () =>
+    Effect.gen(function* () {
+      // With exactly one origin, Effect's CORS compares nothing: the header is that origin
+      // whoever asks. A page elsewhere is still refused, twice: its browser reads an origin
+      // that is not its own, and the endpoint answers its request 403.
+      const asked = yield* preflight("https://elsewhere.example.test");
+
+      expect(asked.status).toBe(204);
+      expect(asked.headers["access-control-allow-origin"]).toBe("https://console.example.test");
+
+      const called = yield* HttpClient.execute(
+        Testing.mcpRequest(
+          "tools/list",
+          {},
+          { headers: { origin: "https://elsewhere.example.test" } },
+        ),
+      );
+
+      expect(called.status).toBe(403);
+      expect(called.headers["access-control-allow-origin"]).toBe("https://console.example.test");
+    }).pipe(
+      Effect.provide(servedWith({ ...farm, ALLOWED_ORIGINS: "https://console.example.test" })),
+    ),
+  );
+
+  it.effect("allows no origin where none is configured", () =>
+    Effect.gen(function* () {
+      const asked = yield* preflight("https://console.example.test");
+
+      expect(asked.headers).not.toHaveProperty("access-control-allow-origin");
+    }).pipe(Effect.provide(servedWith(farm))),
+  );
+
+  it.effect("serves the host's own route beside the tools", () =>
+    Effect.gen(function* () {
+      const health = yield* HttpClient.get("/healthz");
+
+      expect(yield* health.text).toBe("ok");
+    }).pipe(Effect.provide(served)),
+  );
+});

package/examples/notes-service/README.md

@@ -0,0 +1,108 @@
+# notes-service
+
+A small service as most applications of this library are built: one set of contracts, one
+implementation, served as a JSON API and as MCP tools, with a CLI and a browser client on the
+same binding. Notes belong to the signed-in user; reading needs the `notes:read` scope and
+writing `notes:write`.
+
+Start here if you are building a service. The other examples follow the same layout. Then read
+[Action.md](../../docs/Action.md) and the page of each surface you serve, which
+[docs/README.md](../../docs/README.md) routes, one page per tool call. An error's message is
+quoted in a `docs/*-failures.md`.
+
+## Run it
+
+From the repository root, after `vp install` (from an installed package, see
+[Run one](../README.md#run-one)):
+
+```sh
+node --import tsx examples/notes-service/src/server.ts          # 127.0.0.1:3000
+
+export NOTES_TOKEN=ada                                          # a demo token: ada, grace or reader
+node --import tsx examples/notes-service/src/cli.ts --help
+echo "First draft" | node --import tsx examples/notes-service/src/cli.ts create-note --title Plan
+node --import tsx examples/notes-service/src/cli.ts list-notes
+node --import tsx examples/notes-service/src/cli.ts export notes.md   # a command written by hand
+
+vp test examples/notes-service
+```
+
+An agent host connects to the running server, and so to the notes the API holds:
+
+```sh
+claude mcp add --transport http notes http://127.0.0.1:3000/mcp --header "Authorization: Bearer ada"
+codex mcp add notes --url http://127.0.0.1:3000/mcp --bearer-token-env-var NOTES_TOKEN
+```
+
+`src/stdio.ts` is the other way in: a subprocess the host starts, with a store of its own.
+
+The server reads `PORT` (default 3000) and `PUBLIC_URL`, the address it tells OAuth clients it
+is at; the CLI reads `NOTES_URL` and `NOTES_TOKEN`. Change the port and set all three to match.
+Every command asks for `NOTES_TOKEN`, the public `get-status` included: without it a command
+prints one message on stderr saying to set it, and exits 1. `--help` needs none.
+
+The tokens are fixed names and the store is memory: replace both before deploying anything.
+
+## Layout
+
+```text
+src/
+├── notes/
+│   ├── Notes.ts       contract: schemas, errors, actions
+│   ├── store.ts       NoteStore, the service the handlers call, and its Layer
+│   └── handlers.ts    Action.implement: contract to store
+├── identity/
+│   ├── Identity.ts    contract: CurrentUser, scopes, the Login descriptor, whoAmI
+│   ├── authorize.ts   the one authorization rule
+│   ├── users.ts       the demo users
+│   ├── verifier.ts    Authentication.layer: tokens to users, server only
+│   └── handlers.ts
+├── status/
+│   ├── Status.ts      contract: a public action
+│   └── handlers.ts
+├── Api.ts             the HTTP binding of every domain's actions
+├── routes.ts          every surface of the host: /api, /mcp, /healthz, the OpenAPI document
+├── server.ts          entrypoint: the HTTP server
+├── stdio.ts           entrypoint: MCP for a local agent
+├── commands.ts        the commands calling the server, one written by hand, and their connection
+├── cli.ts             entrypoint: the commands, given that connection
+└── browser.ts         client module: promises for a web page
+test/
+├── notes/             in process, with Action.client
+├── routes.test.ts     over HTTP and MCP in memory, with Testing.layer
+└── commands.test.ts   the commands and their connection, against the same routes in memory
+```
+
+- **A folder per domain, not per mechanism.** Everything about notes is in `notes/`; there is no
+  `contracts/` or `handlers/` folder.
+- **The PascalCase file is the contract.** `Notes.ts`, `Identity.ts`, `Status.ts` and `Api.ts`
+  import no server code, so a browser or a CLI imports them. The lowercase files beside them run
+  on the server.
+- **One entrypoint per way of running it.** Each chooses its own implementations: `server.ts`
+  picks the store and the HTTP server, `stdio.ts` names the local user, a test provides its own
+  store. Nothing below an entrypoint knows which it got.
+- **In a monorepo** the contract files and `Api.ts` are the package the server, the CLI and the
+  website all depend on; the lowercase files and `routes.ts` are the server.
+
+## Where to look
+
+| To see                                                        | Read                             |
+| ------------------------------------------------------------- | -------------------------------- |
+| A contract with declared errors and their statuses            | `src/notes/Notes.ts`             |
+| Input fields described, for `--help` and a tool's schema      | `src/notes/Notes.ts`             |
+| Handlers getting a service once and the caller per call       | `src/notes/handlers.ts`          |
+| A public action beside protected ones                         | `src/status/`                    |
+| Authorization from `readOnly`, refusing with a scope          | `src/identity/authorize.ts`      |
+| A token verifier and OAuth discovery read from config         | `src/identity/verifier.ts`       |
+| One implementation served over HTTP and MCP                   | `src/routes.ts`                  |
+| Config, a body limit and the host's own routes                | `src/server.ts`, `src/routes.ts` |
+| The same actions over stdio, the host naming the caller       | `src/stdio.ts`                   |
+| A CLI derived from the binding: an argument, a field on stdin | `src/commands.ts`                |
+| A command written by hand beside the derived ones             | `src/commands.ts`                |
+| The CLI's connection, read from config when a command runs    | `src/commands.ts`, `src/cli.ts`  |
+| A missing token as one message, not a `ConfigError` report    | `src/commands.ts`                |
+| A promise client handling each declared error by its tag      | `src/browser.ts`                 |
+| Testing handlers and authorization with no transport          | `test/notes/notes.test.ts`       |
+| Testing routes, tools and refusals in memory                  | `test/routes.test.ts`            |
+| Testing commands against the routes in memory                 | `test/commands.test.ts`          |
+| Testing `--help` and the connection with config as a Layer    | `test/commands.test.ts`          |

package/examples/notes-service/src/Api.ts

@@ -0,0 +1,13 @@
+import * as ActionHttp from "@gjermundgaraba/effect-actions/ActionHttp";
+import { Login, WhoAmI } from "./identity/Identity.js";
+import { Notes } from "./notes/Notes.js";
+import { GetStatus } from "./status/Status.js";
+
+// The HTTP binding: every action at `POST /api/<name>`, the protected ones requiring `Login`.
+// It is plain data and imports no server code, so the server, the CLI and a browser page all
+// import this one value, and each gets its routes or its typed methods from it. An action
+// added here is also a `notes` command: commands.ts derives one per action of this binding.
+export const Http = ActionHttp.make([GetStatus, ...Notes, WhoAmI], {
+  prefix: "/api",
+  authentication: Login,
+});

package/examples/notes-service/src/browser.ts

@@ -0,0 +1,41 @@
+import { Effect } from "effect";
+import { HttpClient, HttpClientRequest } from "effect/http";
+import * as ActionHttp from "@gjermundgaraba/effect-actions/ActionHttp";
+import { Http } from "./Api.js";
+import type { Note } from "./notes/Notes.js";
+
+// Client module: what a web page imports. It holds the binding and nothing of the server, so a
+// bundler gets the contracts and Effect's fetch client, and no handler.
+//
+// Without `baseUrl` the routes are called on the page's own origin. A page served elsewhere
+// passes the API's URL, and the server must then allow its origin (CORS).
+export const connect = (token: string, baseUrl?: string) => {
+  // Built once, outside any Effect. Every method is typed from its action.
+  const api = ActionHttp.fetchClient(Http, {
+    transformClient: HttpClient.mapRequest(HttpClientRequest.bearerToken(token)),
+    ...(baseUrl === undefined ? {} : { baseUrl }),
+  });
+
+  // Each method returns a promise. A failure rejects it with the decoded error, so in a `catch`
+  // `error instanceof Action.Unauthenticated` tells an expired sign-in from anything else.
+  return {
+    notes: () => Effect.runPromise(api.listNotes()),
+
+    // A declared error can also be handled by its tag before the promise: a missing note is
+    // `undefined` here, and every other failure still rejects.
+    note: (id: string): Promise<Note | undefined> =>
+      api.getNote({ id }).pipe(
+        Effect.catchTag("NoteNotFound", () => Effect.succeed(undefined)),
+        Effect.runPromise,
+      ),
+
+    // A stale revision is refused, never overwritten: the error carries the current one.
+    save: (note: Note, body: string) =>
+      api.updateNote({ id: note.id, body, revision: note.revision }).pipe(
+        Effect.catchTag("NoteChanged", ({ revision }) =>
+          Effect.fail(new Error(`Someone else saved revision ${revision}. Reload the note.`)),
+        ),
+        Effect.runPromise,
+      ),
+  };
+};

package/examples/notes-service/src/cli.ts

@@ -0,0 +1,22 @@
+import { NodeHttpClient, NodeRuntime, NodeServices } from "@effect/platform-node";
+import { Effect } from "effect";
+import { Command } from "effect/cli";
+import { HttpClient } from "effect/http";
+import * as ActionCli from "@gjermundgaraba/effect-actions/ActionCli";
+import { commands, connection } from "./commands.js";
+
+// Entrypoint: `node --import tsx examples/notes-service/src/cli.ts list-notes`.
+// The commands of commands.ts, connected to a server.
+const notes = commands.pipe(
+  // Provided on the command, never around `Command.run`: the URL and the token are then read
+  // when a command runs, so `--help` and a mistyped flag need neither.
+  Command.provideEffect(HttpClient.HttpClient, connection),
+);
+
+// A result is printed on stdout. A failure goes to stderr, under an `ERROR` heading, as the JSON
+// HTTP sends, such as `{"_tag":"NoteNotFound","id":"9"}`, and the command exits 1.
+Command.run(notes, { version: "1.0.0" }).pipe(
+  Effect.provide([NodeHttpClient.layerUndici, NodeServices.layer]),
+  ActionCli.logToStderr,
+  NodeRuntime.runMain,
+);

package/examples/notes-service/src/commands.ts

@@ -0,0 +1,89 @@
+import { Config, Console, Effect, FileSystem, flow } from "effect";
+import { Argument, CliError, Command } from "effect/cli";
+import { HttpClient, HttpClientRequest } from "effect/http";
+import * as ActionCli from "@gjermundgaraba/effect-actions/ActionCli";
+import * as ActionHttp from "@gjermundgaraba/effect-actions/ActionHttp";
+import { Http } from "./Api.js";
+
+// A command of your own, for what no single action does: this one calls two and writes a file.
+// It is a native Effect CLI command, so its syntax and its output are what you write: `notes
+// export notes.md` takes its argument from `Argument`, as a flag would come from `Flag`. It
+// calls the server through the binding's typed client, on the `HttpClient` the derived commands
+// use, and writes with the `FileSystem` every Effect CLI command has.
+const exportNotes = Command.make(
+  "export",
+  { file: Argument.String("file").pipe(Argument.withDescription("The Markdown file to write.")) },
+  ({ file }) =>
+    Effect.gen(function* () {
+      const client = yield* ActionHttp.client(Http);
+      const files = yield* FileSystem.FileSystem;
+      const { notes } = yield* client.listNotes();
+      const whole = yield* Effect.forEach(notes, ({ id }) => client.getNote({ id }));
+
+      yield* files.writeFileString(
+        file,
+        whole.map((note) => `# ${note.title}\n\n${note.body}`).join("\n\n"),
+      );
+
+      yield* Console.log(`Wrote ${whole.length} notes to ${file}`);
+    }).pipe(
+      // Context of your own for a failure goes to stderr before it, on a line of its own. A
+      // `UserError` wrapped around the failure instead would put its JSON mid-sentence. The
+      // line prints for every failure of the command, a file that cannot be written included,
+      // so it says only what is true of them all.
+      Effect.tapError(() => Console.error(`The export to ${file} did not finish.`)),
+      // Once, around the whole command: it then fails as a derived command does, an action's
+      // error printed as its JSON on stderr and any other, a file that cannot be written for
+      // one, named. A failure left as it is would be reported as a crash, with an `ERROR (#n)`
+      // line and a stack trace.
+      ActionCli.toUserError(Http),
+    ),
+).pipe(Command.withDescription("Write every note to a file, as Markdown."));
+
+// A command per action of the binding, a flag per input field, each calling the server over
+// HTTP. It imports the binding alone, never a handler. It is apart from cli.ts so a test runs
+// it: test/commands.test.ts.
+export const commands = ActionCli.remote(Http, {
+  name: "notes",
+  commands: {
+    // `notes create-note --title Draft < draft.md`: the body is piped in, not a flag.
+    createNote: { stdin: "body" },
+    getNote: { positional: ["id"], render: (note) => `# ${note.title}\n\n${note.body}` },
+    // `notes update-note <id> --revision 1 < draft.md`: an argument, a flag and stdin together.
+    updateNote: { positional: ["id"], stdin: "body" },
+  },
+  // `Command.withSubcommands` on the result would replace the derived commands, so your own
+  // go here.
+  subcommands: [exportNotes],
+});
+
+// Where the server is and who is calling, read from config: the `HttpClient` every command
+// above calls with. It is an Effect, not a value, so that cli.ts provides it on the commands
+// and it runs when one of them does.
+export const connection = Effect.gen(function* () {
+  const url = yield* Config.String("NOTES_URL").pipe(Config.withDefault("http://127.0.0.1:3000"));
+
+  // Required, since every command but `get-status` is refused without one. A failure of what a
+  // command is provided is no action's error: left as it is, a missing token is reported as a
+  // crash, the log line `ERROR (#n): ConfigError: SchemaError(Expected string at
+  // ["NOTES_TOKEN"])`. Mapped to a `UserError`, it is printed as any failure of a command is:
+  // the message under an `ERROR` heading on stderr, and exit 1. `userMessage` is all that is
+  // printed, never `cause`: what the user needs from the cause goes into the message. A CLI
+  // whose public commands must answer signed out reads the token with `Config.option` instead
+  // and adds the header when it is there.
+  const token = yield* Config.Redacted("NOTES_TOKEN").pipe(
+    Effect.mapError(
+      (cause) =>
+        new CliError.UserError({
+          cause,
+          userMessage:
+            "NOTES_TOKEN is not set. Set it to your token: export NOTES_TOKEN=<your token>",
+        }),
+    ),
+  );
+
+  return HttpClient.mapRequest(
+    yield* HttpClient.HttpClient,
+    flow(HttpClientRequest.prependUrl(url), HttpClientRequest.bearerToken(token)),
+  );
+});