@gjermundgaraba/effect-actions 0.18.2 → 0.19.0

package/dist/ActionCli.d.mts

@@ -14,14 +14,17 @@ interface AnyBinding extends Declaring {
 }
 /**
  * Make a command of your own fail as a derived command does. Give it what the command calls, the
- * binding of `ActionHttp.client` or `ActionRpc.client`, or the actions of `Action.client`, and pipe the command's
- * whole Effect through it: a failure that is a declared error, the binding's and its
- * authentication's included, or a built-in one becomes a `UserError` whose message is its JSON, and any other, a transport
- * failure for one, a `UserError` naming it and the causes beneath it. An Effect CLI error, your
- * own `new CliError.UserError({ cause, userMessage })` included, passes through as it is. To
- * add context, such as how far a batch got, print it before this in the pipe, with
- * `Effect.tapError(() => Console.error(…))`: a `UserError` wrapped around the result would
- * replace its JSON.
+ * binding of `ActionHttp.client` or `ActionRpc.client`, or the actions of `Action.client`, and
+ * pipe the command's whole Effect through it: a failure that is a declared error, the binding's
+ * and its authentication's included, or a built-in one becomes a `UserError` whose message is its
+ * JSON, and any other, a transport failure for one, a `UserError` naming it and the causes
+ * beneath it. An Effect CLI error, your own `new CliError.UserError({ cause, userMessage })`
+ * included, passes through as it is.
+ *
+ * **Gotchas**
+ *
+ * - A failure left unmapped, one call's included, is reported as a crash, `ERROR (#n)` with a stack trace: pipe the whole Effect through it, once.
+ * - To add context, such as how far a batch got, print it before this in the pipe, `Effect.tapError(() => Console.error(…))`: a `UserError` wrapped around the result puts its JSON mid-sentence and hides the action's failure from `catchReason`.
  */
 export declare const toUserError: (calls: AnyBinding | ReadonlyArray<Any>) => <A, E, R>(self: Effect.Effect<A, E, R>) => Effect.Effect<A, UserError<Exclude<E, CliError.CliError>> | Exclude<E, Exclude<E, CliError.CliError>>, R>;
 /**
@@ -43,11 +46,16 @@ interface Options$1<A extends Any = Any> {
   readonly commands?: { readonly [K in A as K["name"]]?: Options<K>; };
   /**
    * Commands of your own beside the derived ones, as `Command.withSubcommands` takes them:
-   * `[importLinks]`, each made with Effect CLI's `Command.make`. One fails as you make it fail:
-   * with a `CliError.UserError` for `Command.run` to print its `userMessage` on stderr. Written
-   * in the call, or in options held with `satisfies` this type, the list adds its commands'
-   * failures and services to the aggregate's type; in options annotated with this type, it adds
-   * none.
+   * `[importLinks]`, each made with Effect CLI's `Command.make` and printing its output itself,
+   * with `Console.log`. One calls actions through a client in its own handler: `yield*` the
+   * Effect `remote` takes as `client`, which needs no scope, or `Action.client`, acquired inside
+   * `Effect.scoped`. It fails as you make it fail: through `toUserError` as a derived command
+   * does, or with a `CliError.UserError` for `Command.run` to print its `userMessage` on stderr.
+   *
+   * **Gotchas**
+   *
+   * - Write the list in the call, or hold the options with `satisfies ActionCli.Options<…>`: in options annotated `: ActionCli.Options<…>` it adds none of its commands' failures and services to the aggregate's type, so the program compiles, then a command's service is not found.
+   * - Never pipe `Command.withSubcommands` onto the aggregate instead: it replaces the derived commands, which then answer with the usage text.
    */
   readonly subcommands?: Subcommands | undefined;
 }
@@ -64,25 +72,48 @@ type Local<App, A extends Any> = Effect.Effect<A["success"]["Type"], A["error"][
 /**
  * Project one implemented action into a native Effect CLI command that runs its handler in
  * process, behind its implementation's authorization. It is named after the action in kebab
- * case with one flag per field of its input (`--user-id`), or `--input` taking the whole input
- * as JSON when it is not a struct. The flag of an array of strings or numbers is repeated for each value, a boolean
- * field is a switch, `--no-<name>` sending `false` as a required one left out does, and a field's `description` is its flag's help. It needs what the authorization, its handler and its builder
- * need; the host provides the identity. It prints the result on stdout; a failure is a
- * `UserError`, or an Effect CLI error as it is, such as a builder's `CliError.UserError`, which
- * `Command.run` prints on stderr. `remoteCommand` calls a server instead.
+ * case, with one flag per top-level field of its input (`--user-id`), or `--input` taking the
+ * whole input as JSON when it is not a struct of named fields. The host provides the caller on
+ * the command, `Command.provideSync`, beside what the authorization, the handler and the builder
+ * need. `remoteCommand` calls a server instead.
+ *
+ * **Gotchas**
+ *
+ * - A success is its JSON on stdout, indented by two spaces, or `render`'s text; nothing for an action without `success`. Its Effect logs and `Console` output go to stderr; other writes as `logToStderr` says.
+ * - A declared error is its JSON on stderr, under Effect CLI's `ERROR` heading, the command failing with a `UserError` whose `cause` is the error, exit 1 or its `Runtime.errorExitCode`; a refusal as `Action.Unauthenticated` and `Action.Forbidden` say; input that does not decode, in `--input` or a flag's JSON value, is `InvalidInput`'s JSON there, while a missing flag or a rejected choice is Effect CLI's own parse error.
+ * - A failure no schema encodes, a builder's or an accepted error that does not encode, is a `UserError` printed as its tag or name and its message, then its causes, never its other fields; a defect, an undeclared failure, or a success that does not encode is the command's defect, which `runMain` reports as `logToStderr` says.
+ * - Provide services with `Command.provide` on the command, built when an action runs: provided around `Command.run`, they are built before parsing, so `--help` and a mistyped flag open the database.
+ * - Each run builds the action's implementation, its builder and an authorizer an Effect builds, and releases them after the call, even where the host already built them; implementations passed beside it are not built.
+ * - A field named like a global flag (`help`, `version`, `log-level`) is no clash: its flag shadows the global one on this command.
  */
 export declare function command<const Apps extends Served, A extends ActionOf<Member<Apps>>, const O = {}>(implementations: Apps, action: A, options?: O & NoInfer<Options<A>> & NoInfer<Known<O, Options<Any>>>): Command.Command<string, never, {}, Failing<Effect.Error<Local<Owning<Member<Apps>, A>, A>>>, Effect.Services<Local<Owning<Member<Apps>, A>, A>>>;
 /**
  * Project one action of an HTTP binding into a native Effect CLI command, derived as `command`
  * derives it, that calls the action through `client`'s method and fails as the method does, or
- * as the Effect building the client does. `client` is an Effect of the binding's client, such as
- * `ActionHttp.client(Http, { baseUrl })`, run each time the command runs; omitted, it is
- * `ActionHttp.client(binding)` on the host's `HttpClient`. It runs nothing locally.
+ * as the Effect building the client does. It runs nothing locally and names no caller: the
+ * server verifies the credentials its client sends.
  */
-export declare function remoteCommand<const H extends AnyHttp, A extends H["actions"][number], const O = {}, C extends ClientOf<H> | undefined = undefined>(binding: H, action: A, options?: O & NoInfer<Options<A>> & NoInfer<Known<O, RemoteKeys<Options<Any>>>> & {
+export declare function remoteCommand<const H extends AnyHttp, A extends H["actions"][number], const O = {}, C extends ClientOf<H, A> | undefined = undefined>(binding: H, action: A, options?: O & NoInfer<Options<A>> & NoInfer<Known<O, RemoteKeys<Options<Any>>>> & Calling<C>): Command.Command<string, never, {}, Failing<CallFailure<H, C, A>>, CallServices<C, A>>;
+export interface Calling<C> {
+  /**
+   * The connection: an Effect of the binding's client, such as
+   * `ActionHttp.client(Http, { baseUrl, transformClient })`, run each time a command runs, so one
+   * reading `Config` is an `Effect.gen` returning `yield* ActionHttp.client(…)` and `--help`
+   * reads nothing. What it requires, the host provides. Omitted, it is
+   * `ActionHttp.client(binding)` on the host's `HttpClient`, with no `baseUrl`. It needs only the
+   * methods of the actions it derives commands for: those `remote`'s `actions` lists, or
+   * `remoteCommand`'s one.
+   *
+   * **Gotchas**
+   *
+   * - A token read with `Config` and not set fails every command, a public one's too, as `ConfigError: …`, which names no fix: map it to a tagged error whose `message` says what to do, or read an optional one with `Config.option`.
+   * - Credentials go in `transformClient`: a command adds no headers of its own, so without them a protected action answers `Unauthenticated`.
+   * - Never transform the `HttpClient` around the program instead: it rewrites every request the program makes, an absolute URL too, and sends each one the token.
+   */
   readonly client?: C;
-}): Command.Command<string, never, {}, Failing<CallFailure<H, C, A>>, CallServices<C, A>>;
-type ClientOf<H extends AnyHttp> = Effect.Effect<Client<H, unknown, unknown>, unknown, unknown>;
+}
+type ClientOf<H extends AnyHttp, A extends Any> = Effect.Effect<Pick<Client<H, unknown, unknown>, A["name"]>, unknown, unknown>;
+type Needed<O, L extends ReadonlyArray<Any>, All extends Any> = "actions" extends (O extends unknown ? keyof O : never) ? Selected<O, All> : L[number];
 type RemoteKeys<Keys> = Keys & {
   readonly client?: unknown;
 };
@@ -91,35 +122,43 @@ type Called<M, A extends Any> = A extends unknown ? A["name"] extends keyof M ?
 type CallFailure<H extends AnyHttp, C, A extends Any> = C extends Effect.Effect<infer M, infer CE, unknown> ? CE | Effect.Error<Called<M, A>> : Effect.Error<Called<Client<H>, A>>;
 type CallServices<C, A extends Any> = C extends Effect.Effect<infer M, unknown, infer CR> ? CR | Effect.Services<Called<M, A>> : HttpClient.HttpClient;
 /**
- * Project every implemented action as a subcommand of one aggregate command, each named after
- * its action in kebab case and run in process. `commands` gives a subcommand the options
- * `command` takes, by action name; `subcommands` adds commands of your own, which
- * `Command.withSubcommands` on the result would put in the derived ones' place. `remote` calls a
- * server instead. A test runs it in memory, with no process:
- * `Command.runWith(command, { version })(args)`.
+ * Project the implemented actions, every one or those `actions` selects, as subcommands of one
+ * aggregate command, each derived as `command` derives it and run in process. `commands` gives a
+ * subcommand the options `command` takes, by action name; `subcommands` adds commands of your
+ * own. `remote` calls a server instead. A test runs it in memory, with no process: `Command.runWith(command, { version })(args)`.
  * Guide: `docs/ActionCli.md` in this package; in an application: `examples/assistant/src/commands.ts`.
+ *
+ * **Gotchas**
+ *
+ * - Services provided on it with `Command.provide` are also built when it runs with no subcommand, before it shows its help.
  */
 export declare function make<const Apps extends Served, const O extends Selection<ActionOf<Member<Apps>>> = {}, const Own extends Subcommands = []>(implementations: Apps, options: O & NoInfer<Options$1<ActionOf<Member<Apps>>>> & NoInfer<KnownOptions<O, Options$1, ActionOf<Member<Apps>>>> & {
   readonly subcommands?: Own | undefined;
 }): Command.Command<string, {}, {}, Failing<Effect.Error<Local<Holding<Member<Apps>, SelectedOf<O, Apps>>, SelectedOf<O, Apps>>>> | Command.Error<OwnCommand<Own>>, Effect.Services<Local<Holding<Member<Apps>, SelectedOf<O, Apps>>, SelectedOf<O, Apps>>> | Command.Services<OwnCommand<Own>>>;
 /**
- * Project every action of an HTTP binding as a subcommand of one aggregate command, derived as
- * `make` derives it, each calling its action through `client`'s method, as `remoteCommand`
- * does. `commands` gives one the options `command` takes; `subcommands` adds commands of your
- * own, which call through the same client by yielding the Effect given as `client`.
+ * Project the actions of an HTTP binding, every one or those `actions` selects, as subcommands of
+ * one aggregate command, derived as `make` derives them, each calling its action through
+ * `client`'s method, as `remoteCommand` does. `commands` gives one the options `command` takes;
+ * `subcommands` adds commands of your own, which call through the same client by yielding the
+ * Effect given as `client`.
+ * In an application: `examples/notes-service/src/commands.ts`.
  */
-export declare function remote<const H extends AnyHttp, const O extends Selection<H["actions"][number]> = {}, const Own extends Subcommands = [], C extends ClientOf<H> | undefined = undefined>(binding: H, options: O & NoInfer<Options$1<H["actions"][number]>> & NoInfer<KnownOptions<O, RemoteKeys<Options$1<Any>>, H["actions"][number]>> & {
-  readonly client?: C;
+export declare function remote<const H extends AnyHttp, const O extends Selection<H["actions"][number]> = {}, const Own extends Subcommands = [], const L extends ReadonlyArray<H["actions"][number]> = H["actions"], C extends ClientOf<H, Needed<O, L, H["actions"][number]>> | undefined = undefined>(binding: H, options: O & NoInfer<Options$1<H["actions"][number]>> & NoInfer<KnownOptions<O, RemoteKeys<Options$1<Any>>, H["actions"][number]>> & Calling<C> & {
+  readonly actions?: L | undefined;
   readonly subcommands?: Own | undefined;
 }): Command.Command<string, {}, {}, Failing<CallFailure<H, C, Selected<O, H["actions"][number]>>> | Command.Error<OwnCommand<Own>>, CallServices<C, Selected<O, H["actions"][number]>> | Command.Services<OwnCommand<Own>>>;
 /**
  * A program whose stdout carries only its results, such as a CLI feeding scripts or an MCP
  * subprocess, applied last, before `NodeRuntime.runMain`: the default logger of every layer
- * provided within writes to stderr, and a failure `runMain` would report, such as a defect or
- * a failure of a layer the host provides, is reported on stderr instead, once. A command's
- * own failure, which `Command.run` has printed, is not reported again. The exit code is the
- * one `runMain` gives: the failure's `Runtime.errorExitCode`, 1 by default, or 130 for an
- * interruption.
+ * provided within writes to stderr, and a failure `runMain` would report on stdout, such as a
+ * defect, a success that does not encode or a failure of a layer the host provides, is reported
+ * on stderr instead, once. A command's own failure, which `Command.run` has printed, is not
+ * reported again. The exit code is the one `runMain` gives: the failure's
+ * `Runtime.errorExitCode`, 1 by default, or 130 for an interruption.
+ *
+ * **Gotchas**
+ *
+ * - It moves the default logger only: a host layer's `Console` output, the global `console.log`, and a logger writing through `Console.log` such as `Logger.consoleJson`, still reach stdout; log JSON with `Logger.withConsoleError(Logger.formatJson)`.
  */
 export declare const logToStderr: <A, E, R>(self: Effect.Effect<A, E, R>) => Effect.Effect<A, never, R>;
 //#endregion

package/dist/ActionCli.mjs

@@ -1,6 +1,6 @@
 import { assertDistinct, assertKnown } from "./contract/names.mjs";
 import { bindingErrors, projectedErrors } from "./contract/declared.mjs";
-import { Implementation, acquire, assertHeld, select, toList } from "./contract/implementation.mjs";
+import { Implementation, acquire, assertHeld, notHeld, select, toList } from "./contract/implementation.mjs";
 import { client } from "./ActionHttp.mjs";
 import { command as command$1, failingAsDerived } from "./cli/commands.mjs";
 import { Cause, Effect, Logger, Runtime } from "effect";
@@ -8,14 +8,17 @@ import { Command } from "effect/cli";
 //#region src/cli/ActionCli.ts
 /**
 * Make a command of your own fail as a derived command does. Give it what the command calls, the
-* binding of `ActionHttp.client` or `ActionRpc.client`, or the actions of `Action.client`, and pipe the command's
-* whole Effect through it: a failure that is a declared error, the binding's and its
-* authentication's included, or a built-in one becomes a `UserError` whose message is its JSON, and any other, a transport
-* failure for one, a `UserError` naming it and the causes beneath it. An Effect CLI error, your
-* own `new CliError.UserError({ cause, userMessage })` included, passes through as it is. To
-* add context, such as how far a batch got, print it before this in the pipe, with
-* `Effect.tapError(() => Console.error(…))`: a `UserError` wrapped around the result would
-* replace its JSON.
+* binding of `ActionHttp.client` or `ActionRpc.client`, or the actions of `Action.client`, and
+* pipe the command's whole Effect through it: a failure that is a declared error, the binding's
+* and its authentication's included, or a built-in one becomes a `UserError` whose message is its
+* JSON, and any other, a transport failure for one, a `UserError` naming it and the causes
+* beneath it. An Effect CLI error, your own `new CliError.UserError({ cause, userMessage })`
+* included, passes through as it is.
+*
+* **Gotchas**
+*
+* - A failure left unmapped, one call's included, is reported as a crash, `ERROR (#n)` with a stack trace: pipe the whole Effect through it, once.
+* - To add context, such as how far a batch got, print it before this in the pipe, `Effect.tapError(() => Console.error(…))`: a `UserError` wrapped around the result puts its JSON mid-sentence and hides the action's failure from `catchReason`.
 */
 const toUserError = (calls) => "actions" in calls ? failingAsDerived(calls.actions.flatMap((action) => bindingErrors(action, calls))) : failingAsDerived(calls.flatMap((action) => projectedErrors(action)));
 const runWithBuildOfItsOwn = (app, action, input) => {
@@ -27,8 +30,8 @@ const runWithBuildOfItsOwn = (app, action, input) => {
 };
 const theImplementationOf = (apps, action) => {
 	const [app, ...others] = apps.filter((candidate) => candidate.actions.includes(action));
-	if (app === void 0) throw new Error(`Action "${action.name}" has no implementation here`);
-	if (others.length > 0) throw new Error(`Action "${action.name}" is implemented twice here`);
+	if (app === void 0) throw new Error(`Action "${action.name}" has no implementation here (pass its implementation, and select with the contract value it implements: an equal-looking action does not match)`);
+	if (others.length > 0) throw new Error(`Action "${action.name}" is implemented twice here (pass one of them)`);
 	return app;
 };
 const inProcess = (apps, action, options) => {
@@ -36,10 +39,10 @@ const inProcess = (apps, action, options) => {
 	return command$1(action, (input) => runWithBuildOfItsOwn(app, action, input), options, projectedErrors(action));
 };
 const overHttp = (binding, action, options, client$1) => {
-	if (!binding.actions.includes(action)) throw new Error(`Action "${action.name}" is not in this HTTP binding`);
+	if (!binding.actions.includes(action)) throw new Error(`Action "${action.name}" is not in this HTTP binding (pass it to the binding's ActionHttp.make, and select with the contract value it received)`);
 	return command$1(action, (input) => Effect.flatMap(client$1 ?? client(binding), (methods) => {
 		const method = methods[action.name];
-		if (method === void 0) throw new Error(`No client method for ${action.name}`);
+		if (method === void 0) throw new Error(`No client method for ${action.name} (give \`client\` a method for this action)`);
 		return method(input);
 	}), options, bindingErrors(action, binding));
 };
@@ -54,23 +57,33 @@ const aggregateCommand = (name, actions, commands, own, project) => {
 	})), ...own.flatMap((entry) => Command.isCommand(entry) ? [entry] : entry.commands).map((command) => ({
 		claimant: "subcommands",
 		name: command.name
-	}))], ({ name: claimed }) => claimed, ({ claimant }) => claimant);
+	}))], ({ name: claimed }) => claimed, {
+		claimantOf: ({ claimant }) => claimant,
+		fix: "rename one of your subcommands, or give an action's command another name in commands"
+	});
 	return Command.make(name).pipe(Command.withSubcommands([...derived.map(({ command }) => command), ...own]));
 };
 const checkedCommandsOf = (commands, actions) => {
 	const given = commands ?? {};
-	assertKnown("commands", Object.keys(given), actions.map((action) => action.name));
+	assertKnown("commands", Object.keys(given), actions.map((action) => action.name), "key it by the action's own name, not its command's");
 	return given;
 };
 /**
 * Project one implemented action into a native Effect CLI command that runs its handler in
 * process, behind its implementation's authorization. It is named after the action in kebab
-* case with one flag per field of its input (`--user-id`), or `--input` taking the whole input
-* as JSON when it is not a struct. The flag of an array of strings or numbers is repeated for each value, a boolean
-* field is a switch, `--no-<name>` sending `false` as a required one left out does, and a field's `description` is its flag's help. It needs what the authorization, its handler and its builder
-* need; the host provides the identity. It prints the result on stdout; a failure is a
-* `UserError`, or an Effect CLI error as it is, such as a builder's `CliError.UserError`, which
-* `Command.run` prints on stderr. `remoteCommand` calls a server instead.
+* case, with one flag per top-level field of its input (`--user-id`), or `--input` taking the
+* whole input as JSON when it is not a struct of named fields. The host provides the caller on
+* the command, `Command.provideSync`, beside what the authorization, the handler and the builder
+* need. `remoteCommand` calls a server instead.
+*
+* **Gotchas**
+*
+* - A success is its JSON on stdout, indented by two spaces, or `render`'s text; nothing for an action without `success`. Its Effect logs and `Console` output go to stderr; other writes as `logToStderr` says.
+* - A declared error is its JSON on stderr, under Effect CLI's `ERROR` heading, the command failing with a `UserError` whose `cause` is the error, exit 1 or its `Runtime.errorExitCode`; a refusal as `Action.Unauthenticated` and `Action.Forbidden` say; input that does not decode, in `--input` or a flag's JSON value, is `InvalidInput`'s JSON there, while a missing flag or a rejected choice is Effect CLI's own parse error.
+* - A failure no schema encodes, a builder's or an accepted error that does not encode, is a `UserError` printed as its tag or name and its message, then its causes, never its other fields; a defect, an undeclared failure, or a success that does not encode is the command's defect, which `runMain` reports as `logToStderr` says.
+* - Provide services with `Command.provide` on the command, built when an action runs: provided around `Command.run`, they are built before parsing, so `--help` and a mistyped flag open the database.
+* - Each run builds the action's implementation, its builder and an authorizer an Effect builds, and releases them after the call, even where the host already built them; implementations passed beside it are not built.
+* - A field named like a global flag (`help`, `version`, `log-level`) is no clash: its flag shadows the global one on this command.
 */
 function command(implementations, action, options) {
 	return inProcess(toList(implementations), action, options);
@@ -80,13 +93,15 @@ function remoteCommand(binding, action, options) {
 	return overHttp(binding, action, options === void 0 ? void 0 : syntax, client);
 }
 /**
-* Project every implemented action as a subcommand of one aggregate command, each named after
-* its action in kebab case and run in process. `commands` gives a subcommand the options
-* `command` takes, by action name; `subcommands` adds commands of your own, which
-* `Command.withSubcommands` on the result would put in the derived ones' place. `remote` calls a
-* server instead. A test runs it in memory, with no process:
-* `Command.runWith(command, { version })(args)`.
+* Project the implemented actions, every one or those `actions` selects, as subcommands of one
+* aggregate command, each derived as `command` derives it and run in process. `commands` gives a
+* subcommand the options `command` takes, by action name; `subcommands` adds commands of your
+* own. `remote` calls a server instead. A test runs it in memory, with no process: `Command.runWith(command, { version })(args)`.
 * Guide: `docs/ActionCli.md` in this package; in an application: `examples/assistant/src/commands.ts`.
+*
+* **Gotchas**
+*
+* - Services provided on it with `Command.provide` are also built when it runs with no subcommand, before it shows its help.
 */
 function make(implementations, options) {
 	const apps = toList(implementations);
@@ -96,18 +111,22 @@ function make(implementations, options) {
 }
 function remote(binding, options) {
 	const listed = options.actions;
-	if (listed !== void 0) assertHeld("the binding does not hold it", listed, binding.actions);
+	if (listed !== void 0) assertHeld(notHeld.byBinding, listed, binding.actions);
 	const commands = checkedCommandsOf(options.commands, binding.actions);
 	return aggregateCommand(options.name, binding.actions.filter((action) => listed?.includes(action) ?? true), commands, options.subcommands ?? [], (action, syntax) => overHttp(binding, action, syntax, options.client));
 }
 /**
 * A program whose stdout carries only its results, such as a CLI feeding scripts or an MCP
 * subprocess, applied last, before `NodeRuntime.runMain`: the default logger of every layer
-* provided within writes to stderr, and a failure `runMain` would report, such as a defect or
-* a failure of a layer the host provides, is reported on stderr instead, once. A command's
-* own failure, which `Command.run` has printed, is not reported again. The exit code is the
-* one `runMain` gives: the failure's `Runtime.errorExitCode`, 1 by default, or 130 for an
-* interruption.
+* provided within writes to stderr, and a failure `runMain` would report on stdout, such as a
+* defect, a success that does not encode or a failure of a layer the host provides, is reported
+* on stderr instead, once. A command's own failure, which `Command.run` has printed, is not
+* reported again. The exit code is the one `runMain` gives: the failure's
+* `Runtime.errorExitCode`, 1 by default, or 130 for an interruption.
+*
+* **Gotchas**
+*
+* - It moves the default logger only: a host layer's `Console` output, the global `console.log`, and a logger writing through `Console.log` such as `Logger.consoleJson`, still reach stdout; log JSON with `Logger.withConsoleError(Logger.formatJson)`.
 */
 const logToStderr = (self) => self.pipe(Effect.catchCause((cause) => {
 	if (Cause.hasInterruptsOnly(cause)) return Effect.interrupt;

package/dist/ActionHttp.d.mts

@@ -14,6 +14,11 @@ export interface FetchClientOptions<E = HttpClientError.HttpClientError, R = nev
   /**
    * What each call sends with. Omitted: the global `fetch`, looked up on every call, so one
    * installed after the client is built, such as a test's stub, is used.
+   *
+   * **Gotchas**
+   *
+   * - A page on the API's own origin sends its cookies already; from another origin pass `(input, init) => fetch(input, { ...init, credentials: "include" })`, and the server's CORS must allow credentials, `HttpRouter.cors({ allowedOrigins, credentials: true })`.
+   * - A `fetch` of your own passes `init.signal` on, or interrupting a call no longer aborts its request: a deadline is `Effect.timeout` on the call.
    */
   readonly fetch?: typeof globalThis.fetch | undefined;
 }
@@ -30,14 +35,16 @@ type HttpLayer<H extends AnyHttp, Apps extends Served, M extends Middleware, A e
 export interface LayerOptions<M extends Middleware = [], A extends Any = never> {
   /**
    * The actions it serves, among the binding's actions the implementations hold: `[GetUser]`.
-   * Defaults to every one of them. A layer whose middleware requires the identity lists
-   * protected actions only.
+   * Defaults to every one of them.
    */
   readonly actions?: ReadonlyArray<A> | undefined;
   /**
    * Native endpoint middleware every served route runs, the first innermost: inside the
-   * authentication of a protected route, outside its decoding. A middleware requiring the
-   * identity needs a layer serving only protected actions.
+   * authentication of a protected route, outside its decoding, so it also sees invalid input.
+   *
+   * **Gotchas**
+   *
+   * - A middleware requiring the identity needs a layer serving only protected actions: serve the public ones from a second layer without it.
    */
   readonly middleware?: M;
 }
@@ -46,9 +53,31 @@ type LayerRequest<App, A extends Any, M extends Middleware> = Exclude<Through<M,
 }>] extends [never] ? Identity<Protected<Serving<App, A>>> : never)>;
 /** Contract-level configuration shared by servers and clients. */
 interface Options$1<E extends Errors = Errors> {
+  /**
+   * The mount path of every route: `/api` by default, `/` at the root. Split a large API, or
+   * actions sharing a name, into one binding per area, each with its own `prefix` and client;
+   * one host serves them all.
+   */
   readonly prefix?: `/${string}`;
-  /** Router middleware's errors, which every endpoint declares: one schema, or a list. */
+  /**
+   * What router middleware around the routes, or the layer's `middleware`, answers with, such as
+   * a quota's 429, which every endpoint declares: one schema, or a list.
+   *
+   * **Gotchas**
+   *
+   * - An error a handler fails with goes in its action's `error`, not here.
+   * - Router middleware answering with one encodes and sends it itself, `HttpServerResponse.schemaJson(QuotaExceeded)(error, { status: 429 })`, at the status `Action.Options.error` gives it: at any other a client fails with an `HttpClientError`.
+   */
   readonly error?: E | E[number];
+  /**
+   * The descriptor of the binding's protected actions, `Authentication.make(...)`: required
+   * when it holds one, and it documents and enforces their credentials as native endpoint
+   * security middleware on each of them.
+   *
+   * **Gotchas**
+   *
+   * - One descriptor per binding: actions of a second identity take a second binding with its own `prefix`, and a public action may be in both.
+   */
   readonly authentication?: Any$1;
 }
 type Endpoint<A extends Any, E extends Errors, D> = A extends Any ? HttpApiEndpoint.HttpApiEndpoint<A["name"], "POST", `/${string}`, never, never, Schema.toCodecJson<A["input"]>, never, Schema.toCodecJson<A["success"]>, Schema.toCodecJson<A["error"][number] | E[number] | VerifierError<A, D> | BuiltIns>, never> : never;
@@ -59,6 +88,7 @@ type Api<Actions extends ReadonlyArray<Any>, E extends Errors, D> = HttpApi.Http
  * serves the same; `layer` serves it and `client` calls it.
  */
 export interface Binding<Actions extends ReadonlyArray<Any>, E extends Errors = [], D extends Any$1 | undefined = undefined> {
+  /** Its protected actions' authentication descriptor, or `undefined` without one. */
   readonly authentication: D;
   /** The exact actions bound to this binding. */
   readonly actions: Actions;
@@ -66,16 +96,26 @@ export interface Binding<Actions extends ReadonlyArray<Any>, E extends Errors =
   readonly error: E;
   /** Where its routes mount: `/api` by default, `/` at the root, without a trailing slash. */
   readonly prefix: `/${string}`;
+  /**
+   * The native `HttpApi`, for `OpenApi.fromApi`, `HttpApiSwagger.layer`, `HttpApiScalar.layer`
+   * and Effect's own tools: it lists every action of the binding, served or not.
+   *
+   * **Gotchas**
+   *
+   * - Serve it with `layer`, never the native `HttpApiBuilder`: its group name is typed `string`, so `HttpApiBuilder.group(api, "api", …)` is refused as `Endpoint not handled: ${string}`, and given a `string`-typed name a protected action makes the host fail to build with `Service not found: effect-actions/Authentication/Security/…`.
+   * - A header that middleware reads is not in its document, whose operations list no `parameters`: rewrite it, `OpenApi.fromApi(Http.api.annotate(OpenApi.Transform, (document) => …))`, or make the value an input.
+   * - An OAuth protected resource is documented as a bearer scheme: Effect has no OAuth scheme.
+   * - Combined into one document, `HttpApi.make("app").addHttpApi(A.api).addHttpApi(B.api)`, a shared action name makes `OpenApi.fromApi` throw `Duplicate OpenAPI operationId`, and a shared prefix silently drops one binding's actions from the document and a native client: otherwise document each alone.
+   * - A binding holding no protected action documents no security scheme, so Swagger shows no Authorize button.
+   */
   readonly api: Api<Actions, E, D>;
 }
 /**
- * Bind actions once, for servers and clients alike, each at `POST <prefix>/<action>`.
- * Every endpoint declares its action's errors, the binding's `error`, and the built-in
- * `InvalidInput`, `Unauthenticated` and `Forbidden`, so clients decode each as a typed
- * failure. A union's own `httpApiStatus` applies to every member; otherwise, each member
- * uses its own status, or 422 without one. Protected contracts receive native endpoint
- * security middleware: the same descriptor documents their credentials and enforces them.
- * Guide: `docs/ActionHttp.md` in this package; in an application: `examples/notes-service/src/routes.ts`.
+ * Bind actions once, for servers and clients alike, each at `POST <prefix>/<action>`, a
+ * `readOnly` one too. Every endpoint declares its action's errors, the binding's `error`, and
+ * the built-in `InvalidInput`, `Unauthenticated` and `Forbidden`, so clients decode each as a
+ * typed failure; a protected one also declares what its descriptor's verifier fails with.
+ * Guide: `docs/ActionHttp.md` in this package; in an application: `examples/notes-service/src/Api.ts`.
  */
 export declare function make<const Actions extends ReadonlyArray<Any & {
   readonly caller: typeof Anyone;
@@ -84,41 +124,45 @@ export declare function make<const Actions extends ReadonlyArray<Any>, const O e
 export declare function make<const Actions extends ReadonlyArray<Any>>(actions: Actions & PublicOnly<Actions>): Binding<Actions, [], undefined>;
 /**
  * Serve the binding's actions among `implementations` in one layer, or those its `actions` lists,
- * authenticating a protected action's request before decoding it, then running its implementation's
- * `authorize` before each handler. The binding decides what may be served:
- * an implementation's actions the binding leaves out have no route here, and one holding none of
- * those served is not built; implementations holding none of the binding's actions at all are
- * refused when `layer` is called. It mounts only the routes of the actions it serves, so one
- * binding may be served by several layers, each with its own `actions` and `middleware`, which
- * covers its routes only. Each implementation's builder runs once per layer graph however many
- * layers serve it.
+ * authenticating a protected action's request before decoding it, then running its
+ * implementation's `authorize` before each handler. An implementation's actions the binding
+ * leaves out have no route here, one holding none of those served is not built, and a non-empty
+ * list holding none of the binding's actions is refused when `layer` is called. Several layers
+ * may serve one binding, each with its own `actions` and `middleware` covering its routes only.
+ * The layer fails as the builders do, needs at startup what they need, and per request what the
+ * authorization and handlers of the actions it serves need, until its `middleware` or middleware
+ * around it provides them, the identity of a protected action excepted, which its authentication
+ * provides; what is provided per request wins over what the layer was built with. A declared
+ * error answers with its JSON at the status `Action.Options.error` gives it, input that does not
+ * decode a 400 `InvalidInput`, and a refusal as `Action.Unauthenticated` and `Action.Forbidden`
+ * say.
+ *
+ * **Gotchas**
  *
- * The layer fails as the builders do, needs at startup what they need, and per request what
- * each implementation's authorization and the handlers of the actions it serves
- * need, until its `middleware` or middleware provided around it provides them, the identity
- * of a protected action excepted, which its authentication provides; the router provides
- * its own, such as the request, to every route. Its routes take only requests typed as JSON,
- * and what middleware provides per request wins over what the layer was built with. A request
- * body is read whole, however large, unless the host limits it where the routes are served:
- * `Layer.provide(Layer.succeed(HttpServerRequest.MaxBodySize, ByteSize.mebibytes(1)))`.
+ * - A success is its JSON as the body; an action without `success` answers an empty 200, no body and no content type, so a hand-written client must not parse it. One without `input` still takes the body `{}` typed as JSON: no body is a 400.
+ * - A body that is not JSON is a 400 `InvalidInput`; a request with no `Content-Type` a 415 `Unsupported content-type: none`, one with another type Effect's own 415; each after authentication on a protected route.
+ * - A defect, an undeclared failure, or a success or an error that does not encode answers an empty 500: the cause goes to the log and to the call's `ErrorReporter`s, never to the body.
+ * - A path no layer serves, or a method other than `POST` on a route, is a 404.
+ * - The 415 keeps from every handler what another site's page can send without a CORS preflight, such as a form post carrying the user's cookie; the server's CORS policy decides the rest.
+ * - Router middleware providing a request service `X` is declared `HttpRouter.middleware<{ provides: X }>()`: without the type argument it runs and the layer still owes `X`.
+ * - `HttpRouter.provideRequest(layer)` builds its layer once, at startup, so it never provides an identity or a tenant.
+ * - A request body is read whole, however large, unless the host provides `HttpServerRequest.MaxBodySize` to `HttpRouter.serve`, limiting every route that reads its body whole, MCP endpoints included; a body a route reads as a stream is not limited. On Node a request over it gets no response, its connection closed, never a 413; `HttpRouter.toWebHandler` ignores it, so limit bodies in the platform serving the handler.
+ * - An `ErrorReporter` the server runs with is given, as `Info`, a handler's declared failure and an input that does not decode, never a refusal or a refused credential: give an error class `override readonly [ErrorReporter.ignore] = true` to keep it out, and drop `Info` for a built-in error, which takes no mark.
  */
 export declare function layer<const H extends AnyHttp, const Apps extends Served>(binding: H, implementations: Apps): HttpLayer<H, Apps, []>;
 export declare function layer<const H extends AnyHttp, const Apps extends Served, const O extends LayerOptions<Middleware, H["actions"][number]>>(binding: H, implementations: Apps, options: O & ServerOnly<MiddlewareOf<O, Middleware>, H["error"]> & NoInfer<Known<O, LayerOptions<Middleware>>>): HttpLayer<H, Apps, MiddlewareOf<O, Middleware>, Selected<O, H["actions"][number]>>;
 /**
  * Effect's native `HttpApiClient` for a binding, one method per action taking the
- * action's input directly: `client.greet({ name })`. The argument may be omitted when `{}`
- * is a valid input. Requires the native `HttpClient`, as `HttpApiClient.make` does.
- * The options are the native ones, `baseUrl` and `transformClient`, a bearer token being
- * `transformClient: HttpClient.mapRequest(HttpClientRequest.bearerToken(token))`. The native
- * client itself stays available: `HttpApiClient.make(Http.api)`.
+ * action's input directly: `client.greet({ name })`, the argument omitted when `{}` is a valid
+ * input. Requires the native `HttpClient`, as `HttpApiClient.make` does; the native client
+ * itself stays available: `HttpApiClient.make(Http.api)`. Each call fails with its
+ * `MethodError`, an undeclared answer such as a 502 from a proxy or a defect's empty 500 as an
+ * `HttpClientError`, and with what `transformClient` adds.
  *
- * A call fails with a declared error value (the action's own, the binding's, a built-in
- * `InvalidInput`, `Unauthenticated` or `Forbidden`, or on a protected action its descriptor's),
- * a native `HttpClientError` when the server could not be reached or answered with a status or
- * body the contract does not declare, or a `SchemaError` when the success does not decode. An
- * input that does not encode fails with `InvalidInput`, and nothing is sent. A call also fails
- * with what the client `transformClient` returns fails with, as it is, and requires what that
- * client requires.
+ * **Gotchas**
+ *
+ * - An input that does not encode fails with `InvalidInput`, and nothing is sent; undeclared input fields, which TypeScript lets through on a wider value, are dropped as it encodes, since the server would refuse them.
+ * - It interprets no status and retries nothing: a failed write may have happened, and only a declared error says what the server did.
  */
 export declare function client<const H extends AnyHttp>(binding: H, options?: Options): Effect.Effect<Client<H>, never, HttpClient.HttpClient>;
 export declare function client<const H extends AnyHttp, E, R>(binding: H, options: Options<E, R>): Effect.Effect<Client<H, E, R>, never, HttpClient.HttpClient>;
@@ -127,9 +171,6 @@ export declare function client<const H extends AnyHttp, E, R>(binding: H, option
  * a browser app: its methods are the same Effects, which require only what `transformClient`
  * requires, so a call without one runs alone, as `Effect.runPromise(api.greet({ name }))`. The
  * options are `client`'s, and `fetch`.
- *
- * Each call sends with `options.fetch`, or with the global `fetch` as it is when the call
- * runs.
  */
 export declare function fetchClient<const H extends AnyHttp>(binding: H, options?: FetchClientOptions): Client<H>;
 export declare function fetchClient<const H extends AnyHttp, E, R>(binding: H, options: FetchClientOptions<E, R>): Client<H, E, R>;

package/dist/ActionHttp.mjs

@@ -1,9 +1,9 @@
 import { Anyone } from "./contract/caller.mjs";
+import { declared } from "./contract/status.mjs";
 import { bindingErrors, bindingOf, projectedErrors } from "./contract/declared.mjs";
 import { acquire, provideHandlers, servingOf } from "./contract/implementation.mjs";
 import { providerOf } from "./authentication/provider.mjs";
 import { inputParseOptions } from "./contract/call.mjs";
-import { declared } from "./contract/status.mjs";
 import { methods } from "./http/client.mjs";
 import { SchemaErrors, schemaErrors } from "./http/schema-errors.mjs";
 import { Context, Effect, Layer, Scope } from "effect";
@@ -21,7 +21,7 @@ const apiOf = (group, endpoints) => {
 const endpointOf = (action, path, errors) => HttpApiEndpoint.post(action.name, path, {
 	payload: action.input.pipe(HttpApiSchema.asJson()),
 	success: action.success,
-	error: errors.flatMap(declared)
+	error: errors.map(declared)
 });
 const withinLayerMiddleware = (endpoint, middleware = []) => middleware.reduce((inner, key) => inner.middleware(key), endpoint);
 function make(actions, options = {}) {