@gjermundgaraba/effect-actions 0.18.2 → 0.20.0

package/docs/ActionCli.md

@@ -4,102 +4,74 @@ Native Effect CLI commands for actions, with flags derived from each action's in
 `command` take implementations and run the handler in the command's own process, behind the same
 `authorize`: for a local tool, or an operator console that has the services itself. `remote` and
 `remoteCommand` take an HTTP binding and call a server, running nothing locally: for users of a
-service you already serve. `make` and `remote` derive a command for every action of the
-implementations or the binding, so a new action is a new command: list `actions` to leave some
-out.
-
-Read this page alone, in one tool call; if its output says it was truncated, read it again alone.
-When something fails, search [ActionCli-failures.md](ActionCli-failures.md). Reading order:
-[README.md](README.md).
-
-## API
-
-Import `@gjermundgaraba/effect-actions/ActionCli`.
-
-| API                                          | Purpose                                                                  |
-| -------------------------------------------- | ------------------------------------------------------------------------ |
-| `make(implementations, options)`             | Every implemented action as a subcommand of one command, run in process. |
-| `command(implementations, action, options?)` | One action, selected by its contract, as a native Effect `Command`.      |
-| `remote(binding, options)`                   | Every action of an HTTP binding as a subcommand, called over HTTP.       |
-| `remoteCommand(binding, action, options?)`   | One action of an HTTP binding, called over HTTP.                         |
-| `toUserError(binding)`                       | Piped onto a command of your own: it fails as a derived command does.    |
-| `logToStderr`                                | Applied last before `runMain`: stdout carries only results.              |
-
-| Option                                   | Meaning                                                                         |
-| ---------------------------------------- | ------------------------------------------------------------------------------- |
-| `command`, `remoteCommand`: `name`       | The command's name; default: the action's in kebab case.                        |
-| `command`, `remoteCommand`: `render`     | Decoded success to text for a person; adds `--json`.                            |
-| `command`, `remoteCommand`: `positional` | Input fields taken as positional arguments instead of flags, in this order.     |
-| `command`, `remoteCommand`: `aliases`    | A short flag per field: `{ limit: "n" }` takes `-n 5` beside `--limit 5`.       |
-| `command`, `remoteCommand`: `stdin`      | A required field read from stdin instead of a flag: `{ stdin: "value" }`.       |
-| `make`, `remote`: `name`                 | The aggregate's name, required.                                                 |
-| `make`, `remote`: `actions`              | The actions that are subcommands; default: every one.                           |
-| `make`, `remote`: `commands`             | Each subcommand's `command` options, by action name: `{ getNote: { render } }`. |
-| `make`, `remote`: `subcommands`          | Commands of your own beside the derived ones: `[exportNotes]`.                  |
-| `remoteCommand`, `remote`: `client`      | The client its commands call: `ActionHttp.client(Http, { baseUrl })`.           |
-
-Exported types: `Options<A>` of `make` and `remote`, `CommandOptions<A>` of `command` and
-`remoteCommand`, and `UserError<E>`, a type only: what a command fails with when its action fails with `E`.
+service you already serve. `make` and `remote` derive one command per action; which actions a
+surface serves is on `Action.make`.
 
-## Run actions as local commands
+A message the library throws says its fix; for a compiler diagnostic or Effect's own error, search [ActionCli-failures.md](ActionCli-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.
 
-Pass implementations to `make`, and provide the services and the caller on the command:
+## Run actions as local commands
 
-```ts
-const assistant = ActionCli.make([tasks, identity], { name: "assistant" }).pipe(
+Pass implementations to `make`; the host provides the services and the caller on the command,
+and runs it with Effect's own `Command.run`:
+
+```ts example=assistant/src/cli.ts
+import { userInfo } from "node:os";
+import { NodeRuntime, NodeServices } from "@effect/platform-node";
+import { Effect, Layer } from "effect";
+import { Command } from "effect/cli";
+import * as ActionCli from "@gjermundgaraba/effect-actions/ActionCli";
+import { commands } from "./commands.js";
+import { CurrentCaller, type Operator } from "./identity/Identity.js";
+import { Permissions } from "./identity/permissions.js";
+import { tasksFile } from "./platform/tasks-file.js";
+
+// Entrypoint: `node --import tsx examples/assistant/src/cli.ts list-tasks`.
+// The operator's own tool. No credential arrives at a terminal, so this host names the caller
+// itself: whoever runs the command, as the trusted operator. Being local earns nothing more:
+// `authorize` runs here as for a model's tool call, and admits the operator by its kind.
+const operator: Operator = { kind: "operator", id: userInfo().username };
+
+const assistant = commands.pipe(
   Command.provide(Layer.mergeAll(tasksFile, Permissions.layerMemory)),
   Command.provideSync(CurrentCaller, operator),
 );
+
+// A command's defect, such as a tasks file that does not decode, `runMain` reports on stdout.
+// `logToStderr`, applied last, moves that to stderr, so `assistant list-tasks --json | jq` reads
+// results alone.
+Command.run(assistant, { version: "1.0.0" }).pipe(
+  Effect.provide(NodeServices.layer),
+  ActionCli.logToStderr,
+  NodeRuntime.runMain,
+);
 ```
 
-Run it with Effect's own `Command.run`:
-[assistant/src/commands.ts](../examples/assistant/src/commands.ts) and
-[assistant/src/cli.ts](../examples/assistant/src/cli.ts) are the whole program, and
-[kitchen-sink/src/ops.ts](../examples/kitchen-sink/src/ops.ts) an operator console.
-
-- **Provide services on the command, not around the run.** `Command.provide(layer)` builds the
-  layer when an action runs. Provided around `Command.run`, it is built before parsing, so
-  `--help` and a mistyped flag open the database. The aggregate run with no subcommand still
-  builds what it is provided before showing its help.
-- **Each run builds its implementation.** A command runs its action's builder, and an authorizer
-  an Effect builds, then releases them after the call, even where the host already built them.
-  Implementations passed alongside are not built.
-- **For one action, or a tree of your own**, use `command(implementations, action, options?)`
-  under native `Command.withSubcommands`. For a command of your own beside every derived one:
-  [Add a command of your own](#add-a-command-of-your-own).
+The aggregate is [assistant/src/commands.ts](../examples/assistant/src/commands.ts), and
+[kitchen-sink/src/ops.ts](../examples/kitchen-sink/src/ops.ts) an operator console. For one
+action, or a tree of your own under native `Command.withSubcommands`, use
+`command(implementations, action, options?)`. Where services go, what each run builds and what a
+command prints on which stream are on `ActionCli.command`; what `runMain` reports, a command's
+defect included, on `ActionCli.logToStderr`; matching a failure after `Command.run`, on
+`ActionCli.UserError`.
+
 - **Test commands without a process** with `Command.runWith`, `TestConsole` and
-  `Stdio.layerTest`. Provide the services around the test so its commands share one store:
-  [assistant/test/commands.test.ts](../examples/assistant/test/commands.test.ts).
-  `TestConsole.logLines` holds every line of the test, each `unknown`, not of one run: take each
-  run's own and compare or decode them, as
-  [notes-service/test/commands.test.ts](../examples/notes-service/test/commands.test.ts) does.
-  A run also fails with Effect CLI's own errors, such as a flag that does not parse: only a
-  `UserError` has a `userMessage`, so match it (`Effect.catchTag("UserError", …)`) before reading one.
+  `Stdio.layerTest`: [assistant/test/commands.test.ts](../examples/assistant/test/commands.test.ts).
 
 ## Call a server from commands
 
-Pass the HTTP binding to `remote`. The program imports the binding alone, never a handler; each
-command calls its action through the binding's `ActionHttp.client` method
-([ActionHttp.md](ActionHttp.md#call-the-api-from-effect)) and fails as that method does. The host
-provides `HttpClient` (`NodeHttpClient.layerUndici`) in
-[notes-service/src/cli.ts](../examples/notes-service/src/cli.ts); the client says where the
-server is in [notes-service/src/commands.ts](../examples/notes-service/src/commands.ts).
-[kitchen-sink/src/cli.ts](../examples/kitchen-sink/src/cli.ts) adds a tenant header and uses
-every command option.
-
-- **The connection is the `client` option**, an Effect of the binding's client run each time a
-  command runs: `client: ActionHttp.client(Http, { baseUrl, transformClient })`. One reading
-  `Config` is an `Effect.gen` returning `yield* ActionHttp.client(…)`, so `--help` reads nothing.
-  Its failures and its methods' are the command's, printed as `Tag: message`, a
-  `CliError.UserError` as its `userMessage`; what they require, the host provides. Credentials go in `transformClient`
-  ([ActionHttp.md](ActionHttp.md#call-the-api-from-effect)).
-- **Never transform the `HttpClient` around the program**: it rewrites every request the program
-  makes, an absolute URL too, and sends each one the token.
-- **A token every command needs is required, its failure mapped to a tagged error whose `message`
-  says what to do**, or a missing one prints as `ConfigError: …`: `api` in
-  [notes-service/src/commands.ts](../examples/notes-service/src/commands.ts). Where a public
-  command must answer signed out, read it with `Config.option` and add the header when it is
-  there: [kitchen-sink/src/cli.ts](../examples/kitchen-sink/src/cli.ts).
+Pass the HTTP binding to `remote`. The program imports the binding alone, never a handler. The
+connection is the `client` option, an `ActionHttp.client`
+([ActionHttp.md](ActionHttp.md#call-the-api-from-effect)), its rules on `ActionCli.Calling`'s `client`,
+shared by `remote` and `remoteCommand`:
+[notes-service/src/commands.ts](../examples/notes-service/src/commands.ts) requires a token,
+mapping its absence to an error that says what to do, and
+[kitchen-sink/src/cli.ts](../examples/kitchen-sink/src/cli.ts) adds a tenant header, reads an
+optional token for a public command. The host provides
+`HttpClient` (`NodeHttpClient.layerUndici`) in
+[notes-service/src/cli.ts](../examples/notes-service/src/cli.ts).
+
+- **Split one binding into groups of commands**, one `remote` per group with its own `actions`;
+  what each group's `client` needs is on `ActionCli.Calling`'s `client`.
 - **Test a remote command the same way** as a local one, with `Testing.layer(routes)` provided
   as its `HttpClient` ([Testing.md](Testing.md#test-routes-in-memory)). Export the command from
   a module apart from the entrypoint that runs it
@@ -130,7 +102,8 @@ encoded JSON value decides the kind of flag:
   `Schema.FiniteFromString`.
 - A value flag reads its text as JSON when the field accepts that kind of JSON value
   (`--count 2`, `--owner '{"id":"x"}'`, `--points '[{"x":1}]'`), and keeps it as text otherwise
-  (`--limit auto`).
+  (`--limit auto`): quote a string that would read as JSON, `--id '"123"'` for a
+  `String | Number` field.
 - A repeated flag given no occurrence sends `[]` for a required `Schema.Array` field, and leaves
   an optional field out, where `--tags '[]'` alone sends an empty list.
 - An input that is not a struct of named fields (a union, a record, a scalar) gets one
@@ -138,88 +111,61 @@ encoded JSON value decides the kind of flag:
 
 ### Arguments, short flags and stdin
 
-In an aggregate, a command's options go under `commands`, keyed by the action's name
-(`completeTask`), not the command's:
-[assistant/src/commands.ts](../examples/assistant/src/commands.ts).
-
-- `positional`: list every required field before any optional one, and an array field last.
-- `stdin` suits a secret or a document. The value is all of stdin until it closes, without the
-  line endings that end it. A terminal is never read: pipe the value in.
+`description`, `render`, `positional`, `aliases` and `stdin` shape one command; in an aggregate
+they go under `commands`, keyed by the action's name. Each one's rules are on its own
+declaration:
+
+```ts example=assistant/src/commands.ts
+import * as ActionCli from "@gjermundgaraba/effect-actions/ActionCli";
+import { identity } from "./identity/handlers.js";
+import { tasks } from "./tasks/handlers.js";
+
+// The same implementations as local commands, `assistant <action>`: a command runs the handler
+// in this process, behind the same `authorize`. `add-task` and `who-am-i` are as derived; the
+// others each change their syntax or output.
+export const commands = ActionCli.make([tasks, identity], {
+  name: "assistant",
+  commands: {
+    // `assistant list-tasks -a ada`: a short flag beside `--assignee`. `render` prints a line
+    // per task for a person, and adds `--json` for the JSON a script reads. `description` is the
+    // command's help, saying what a line holds; the action's stays what a model reads.
+    listTasks: {
+      description: "Print one line per task: [x] when done, then its id, title and assignee.",
+      aliases: { assignee: "a" },
+      render: ({ tasks }) =>
+        tasks
+          .map((task) => `${task.done ? "[x]" : "[ ]"} ${task.id} ${task.title} (${task.assignee})`)
+          .join("\n"),
+    },
+    // `assistant complete-task 2`: an argument instead of `--id 2`.
+    completeTask: { positional: ["id"] },
+    // `assistant annotate-task --id 2 < notes.md`: the notes are piped in, not a flag.
+    annotateTask: { stdin: "notes" },
+  },
+});
+```
 
 ### Add a command of your own
 
 Work every surface should offer, a bulk import for one, is an action first: a command of your
-own then only reads the file and calls it. Its client checks the input as it encodes it, naming
-a bad entry by its path, so a decode of your own only repeats that check. `notes import <file>`
-reads `Argument.FileText` and calls `importNotes`. For a syntax the options cannot express, such
-as a flag named apart from its field, build the command with native `Command.make`, `Flag` and `Argument`, and pass it
-in `subcommands`: `notes export <file>` takes `Argument.String("file")`
-([notes-service/src/commands.ts](../examples/notes-service/src/commands.ts)):
-
-```ts
-const notes = ActionCli.remote(Http, { name: "notes", client: api, subcommands: [exportNotes] });
-```
-
-- **Never pipe `Command.withSubcommands` onto `make` or `remote`.** It replaces the derived
-  commands, which then answer with the usage text.
-- **Call the actions through a client**, in the command's own handler: `yield* api`, the Effect
-  the aggregate's `client` is, which needs no scope, or `Action.client`, acquired inside
-  `Effect.scoped` ([Action-in-process.md](Action-in-process.md#call-actions-in-process)).
-  `authorize` still runs.
-- **Its output is what it prints**, with `Console.log`: the output rules below are a derived
-  command's. **Pipe its whole Effect through `ActionCli.toUserError(Http)`**, the binding its
-  client is made from, HTTP or RPC, or `toUserError([GetNote])` over `Action.client`, to fail as a derived command does: a declared
-  error as its JSON on stderr, a transport failure named with its causes. A message of your own is `new CliError.UserError({ cause, userMessage })`, which
-  passes through. To add context to a failure, such as how far a batch got, print it inside the
-  pipe, `Effect.tapError(() => Console.error(…))`: wrapping the `UserError` in another puts its
-  JSON mid-sentence and hides the action's failure from `catchReason`. A failure left unmapped, one call's included, is reported as a crash,
-  `ERROR (#n)` with a stack trace.
-- **Write the list in the call**, or hold the options with `satisfies ActionCli.Options<…>`. The
-  aggregate's type then carries its commands' failures and services. A list in options
-  annotated `: ActionCli.Options<…>` adds none: the program compiles, then a command's service is not found.
-
-### Output and exit code
-
-- **A command writes only its result to stdout**: the success as JSON, indented by two spaces,
-  or the text `render` returns.
-- **Everything else a command runs writes to stderr**: its Effect logs and Effect `Console`
-  output. The global `console.log` and other direct writes bypass Effect and still reach stdout.
-- **A failure of the action is printed once on stderr, under Effect CLI's `ERROR` heading, as
-  the JSON HTTP sends for it** ([guarantees.md](guarantees.md#wire-behavior)), on the last line:
-  `{"_tag":"TaskNotFound","id":"9"}`. The process exits 1, or with the failure's
-  `Runtime.errorExitCode`. A failure no schema encodes, a builder's or the transport's, prints
-  as its tag or name and its message, never its other fields.
-- **Apply `logToStderr` last, before `runMain`, when scripts read stdout.** What happens outside
-  a command is `runMain`'s to report, on stdout: a defect, such as a handler's bug or a success
-  that does not encode, and a failure or a log of a layer the host provides. `logToStderr` moves
-  those reports and the default logger to stderr, keeping the exit code, but not those layers'
-  `Console` output or a logger writing through `Console.log`, such as `Logger.consoleJson`: log
-  JSON with `Logger.withConsoleError(Logger.formatJson)`.
-
-### Handle a failure after `Command.run`
-
-A command fails with `UserError<E>`, Effect CLI's `UserError` whose `cause`, and `reason`, is the
-action's failure. Match it by its tag:
-`Effect.catchReason("UserError", "TaskNotFound", (missing) => ...)`. `Command.run` has printed it
-by then, so a recovery decides what follows, such as the exit code, not the text. For text of
-your own, provide Effect's formatter,
-`CliOutput.layer(Object.assign({}, CliOutput.defaultFormatter(), { formatError }))`, or pass
-`renderErrors: false` to `Command.run` and print every failure yourself, the parser's too.
+own then only reads the file and calls it. For a syntax the options cannot express, such as a
+flag named apart from its field, build the command with native `Command.make`, `Flag` and
+`Argument`, and pass it in `subcommands`, whose rules are on `ActionCli.Options`; pipe its
+Effect through `toUserError` to fail as a derived command does.
+In [notes-service/src/commands.ts](../examples/notes-service/src/commands.ts),
+`notes import <file>` reads `Argument.FileText` and calls `importNotes`, and
+`notes export <file>` takes `Argument.String("file")` and calls two actions.
 
 ## Name the caller
 
-A local command of a protected action requires the identity service its contract declares
-([Action.md](Action.md#say-who-may-call-an-action)), whether or not a handler reads it. No
-credential arrives at a terminal, so the host names the caller, on the command:
-`Command.provideSync(CurrentCaller, operator)`, or `Command.provideEffect(CurrentCaller, load)`
-to read it when an action runs. See [assistant/src/cli.ts](../examples/assistant/src/cli.ts).
+`Command.provideSync(CurrentCaller, operator)` names the caller on the command in
+[assistant/src/cli.ts](../examples/assistant/src/cli.ts), or
+`Command.provideEffect(CurrentCaller, load)` reads it when an action runs
+([Action.md](Action.md#say-who-may-call-an-action)).
 
-- **A local command is no bypass.** The implementation's `authorize` runs as on every surface
-  ([Action.md](Action.md#authorize-calls)).
 - **A trusted operator is a type, not a flag.** Give the identity a variant only a host builds,
   kept out of every verifier's return type, and admit it in the shared `authorize`:
   [assistant/src/identity/Identity.ts](../examples/assistant/src/identity/Identity.ts) with
   [assistant/src/identity/authorize.ts](../examples/assistant/src/identity/authorize.ts), or
   [kitchen-sink/src/admin/Admin.ts](../examples/kitchen-sink/src/admin/Admin.ts) with
   [kitchen-sink/src/ops.ts](../examples/kitchen-sink/src/ops.ts).
-- **A remote command names no caller.** The server verifies the credentials its client sends.

package/docs/ActionHttp-failures.md

@@ -5,85 +5,23 @@ The tasks are in [ActionHttp.md](ActionHttp.md).
 
 ## Binding and serving
 
-- A route returns 404, which a client method reports as an `HttpClientError` with `DecodeError`
-  or `StatusCodeError`: the path lacks the prefix, no `layer` call serves the action, or the
-  binding does not hold that very action value, as when a test declares the contract again.
-- `No action of these implementations is in this HTTP binding: x`,
-  `Listed in actions, but the binding does not hold it: <names>` or
-  `but no implementation holds it`, thrown by `layer`: the binding, the implementations and
-  `actions` are matched by action value, never by name. `x (another contract)` is an action of a
-  bound name that is not the bound value, as a second copy of the contracts module makes.
-- `Duplicate served action: <name>` thrown by `layer`, or
-  `Method 'POST' already declared for route '<prefix>/<action>'` when the host builds: an action
-  is served once. One `layer` call got two implementations of it, or two calls serve it: give
-  each layer its own `actions`.
-- `Duplicate action: <name>` thrown by `make`: two actions share a name, or one is listed twice.
-  Rename one, or bind it under another prefix.
-- `ActionHttp binding: error _tag "Forbidden" is built in, and declared on every surface` thrown by
-  `make`: a binding error is a built-in error or reuses its tag. Drop it, or rename your own.
-- `Duplicate OpenAPI operationId: <name>` from `OpenApi.fromApi`, or a combined document or
-  native client lacking one binding's actions: bindings combined into one `HttpApi` need distinct
-  action names and distinct prefixes. Rename or re-prefix one, or document each binding alone.
-- `Service not found: effect-actions/Authentication/Security/…` when the host builds: a binding
-  holding a protected action is served with the native `HttpApiBuilder`. Serve it with `layer`.
-- Swagger shows no Authorize button: the binding holds no protected action.
+- A route returns 404, which a client method reports as an `HttpClientError` with `DecodeError` or `StatusCodeError`: the path lacks the prefix, no `ActionHttp.layer` call serves the action, or the binding does not hold that very action value, as when a test declares the contract again.
+- `Method 'POST' already declared for route '<prefix>/<action>'` when the host builds: two `ActionHttp.layer` calls serve one action; give each layer its own `actions`.
+- `Duplicate OpenAPI operationId: <name>` from `OpenApi.fromApi`: two bindings combined into one `HttpApi` share an action name; rename one, or document each binding alone.
+- `Type 'Handlers<…>' is not assignable to type '`Endpoint not handled: ${string}`'` at `HttpApiBuilder.group(binding.api, …)`, or `Service not found: effect-actions/Authentication/Security/…` when the host builds: a binding is served with the native `HttpApiBuilder`; serve it with `ActionHttp.layer`.
+- `Unsupported content-type: <type>` as a 415 body: Effect refuses a `Content-Type` other than `application/json`, after authentication and before the handler; send `application/json`.
 
 ## Types
 
-- `No overload matches this call` at `make`, naming
-  `"Protected actions take options naming their authentication"`, or a type error naming
-  `authentication`: give `{ authentication: Login }`. Do not silence it with
-  `caller: Action.Anyone`.
-- `Argument of type 'Options<…> | undefined' is not assignable` at `make`: a helper forwards
-  options that may be absent. Pass `options ?? {}`.
-- `Provider<…>` among the layer's requirements, or
-  `Type 'Provider<...>' is not assignable to type 'never'` where the server is launched: provide
-  the descriptor's provider ([Authentication-failures.md](Authentication-failures.md)).
-- `Authentication "<name>": the binding's descriptor is not its provider's`, a defect when `layer`
-  builds: build the binding and its provider from one descriptor.
-- `Type 'X' is not assignable to type 'never'` where the server is launched, or
-  `Request<"Requires", X>` in the layer's type: a handler, an authorizer or a layer middleware
-  reads a request service `X` that nothing around the layer provides, or router middleware
-  provides `X` and is not declared `HttpRouter.middleware<{ provides: X }>()`
-  ([Serve the routes](ActionHttp.md#serve-the-routes)). Where `X` is the identity, a public
-  handler reads it, or a layer whose middleware requires it serves public actions: make the
-  action protected, or serve the protected actions from a layer of their own.
-- Type error on `middleware` naming
-  `"Layer middleware fails only with the binding's errors and needs no client"`: add the error to
-  the binding's `error`, given inline so its type is certain, or move the check to the handlers
-  and declare the error on their actions.
-
-- `No overload matches this call` at `client`, naming `Options<unknown, unknown>`: options built
-  before the call hold the generic `HttpClient.mapRequestEffect(authorize)`, whose failures the
-  call cannot infer, or a helper types them as `Parameters<typeof ActionHttp.client>[1]`. Write
-  the transform as `(client) => HttpClient.mapRequestEffect(client, authorize)`, and type such
-  options as `ActionHttp.ClientOptions<E, R>`.
-
-## Requests
-
-- A route answers without credentials: its contract is `caller: Action.Anyone`.
-- A protected route answers 401 to a request with no content type or invalid input:
-  authentication runs before the body is read. Send the token.
-- 400 `InvalidInput` on a valid-looking request: its `message` names each field that did not
-  decode or the action does not declare, such as a misspelling. An action without input takes
-  only `{}`, and needs a body.
-- 415 `Unsupported content-type: <type>` (`none` without one): the request is not typed as JSON,
-  such as `fetch`'s default `text/plain` for a string body. Send `Content-Type: application/json`.
-- Empty 500: a defect, or a handler result not matching the success schema. The cause is in the
-  server's logs, written by its request logger, and under `Testing.layer` in the test's, as an error.
+- `Argument of type 'Options<…> | undefined' is not assignable` at `ActionHttp.make`: a helper forwards options that may be absent; pass `options ?? {}`.
+- `Type 'X' is not assignable to type 'never'` where the server is launched, or `Request<"Requires", X>` in the layer's type: nothing around the layer provides the request service `X`, or router middleware provides it undeclared; declare it `HttpRouter.middleware<{ provides: X }>()`; the rules are on `ActionHttp.layer`, and where `X` is the identity, on `ActionHttp.LayerOptions.middleware`.
+- Type error on `ActionHttp.LayerOptions.middleware` naming `"Layer middleware fails only with the binding's errors and needs no client"`: add the error to the binding's `error`, given inline so its type is certain, or move the check to the handlers and declare the error on their actions.
+- `No overload matches this call` at `ActionHttp.client`, naming `Options<unknown, unknown>`: options built before the call hold the generic `HttpClient.mapRequestEffect(authorize)`, or a helper types them as `Parameters<typeof ActionHttp.client>[1]`; write `(client) => HttpClient.mapRequestEffect(client, authorize)`, and type such options as `ActionHttp.ClientOptions<E, R>`.
 
 ## Client methods
 
-- `HttpClientError` whose `reason._tag` is `DecodeError`, printed `Decode error (<status> …)`,
-  for a status such as 429: no schema declares that status. For a 500, see the empty 500 above. Declare the error on the binding when middleware answers with it, or on
-  the action when its handler does.
-- `HttpClientError` whose `reason._tag` is `InvalidUrlError` outside a browser: relative routes
-  have no page to resolve against. Set `baseUrl`.
-- Type error listing `HttpClient` as an unsatisfied requirement: provide one, such as
-  `FetchHttpClient.layer`, or use `fetchClient`.
-- `Expected 1 arguments` at a client method: `{}` is not a valid input for the action, so pass
-  its input. Where the argument may be omitted, leave it out: `undefined` is a type error.
-- Type error passing `{ payload: ... }` to a client method: `payload` is the native client's
-  shape. Pass the input itself.
-- `InvalidInput` `Expected Filters` given a plain object: the input is a class, which encodes
-  only its instances. Pass `new Filters({ ... })`.
+- `HttpClientError` whose `reason._tag` is `DecodeError`, printed `Decode error (<status> …)`, for a status such as 429: no schema declares that status; declare the error on the binding when middleware answers with it, on the action when its handler does. For a 500, the cause is in the server's logs.
+- `HttpClientError` whose `reason._tag` is `InvalidUrlError` outside a browser: relative routes have no page to resolve against; set `baseUrl`.
+- Type error listing `HttpClient` as an unsatisfied requirement: provide one, such as `FetchHttpClient.layer`, or use `ActionHttp.fetchClient`.
+- `Expected 1 arguments` at a client method: `{}` is not a valid input for the action, so pass its input; where the argument may be omitted, leave it out, as `undefined` is a type error.
+- Type error passing `{ payload: ... }` to a client method: `payload` is the native client's shape; pass the input itself.