@gjermundgaraba/effect-actions 0.11.0 → 0.13.0

package/dist/Testing.d.mts

@@ -1,14 +1,15 @@
-import { BuiltIn } from "./internal/errors.mjs";
-import { Call } from "./internal/call.mjs";
+import { BuiltIn } from "./contract/errors.mjs";
+import { Call } from "./contract/call.mjs";
 import { Action_d_exports, Any } from "./Action.mjs";
-import { Params } from "./internal/mcp.mjs";
-import { Served } from "./internal/memory.mjs";
-import { Effect, Layer, Schema } from "effect";
+import { Params } from "./mcp/protocol.mjs";
+import { Served } from "./testing/memory.mjs";
+import { Cause, Effect, Layer, Schema } from "effect";
 import { Headers, HttpClient, HttpClientError, HttpClientRequest, HttpRouter } from "effect/http";
-//#region src/Testing.d.ts
+//#region src/testing/Testing.d.ts
 /**
- * The native `HttpClient`, answered by `handler` instead of the network: a web handler the
- * test serves, which other tests may share, such as
+ * For a web handler the test already owns; most tests want `layer(routes)`, below, with
+ * `ActionHttp.client` and `mcpClient`. The native `HttpClient`, answered by `handler` instead of
+ * the network: a web handler the test serves, which other tests may share, such as
  * `HttpRouter.toWebHandler(routes.pipe(Layer.provide(HttpServer.layerServices))).handler`,
  * the routes' platform services provided, as `layer(routes)` provides them itself. It is the
  * client `layer(routes)` gives, without building anything: the test owns the handler, and
@@ -18,7 +19,10 @@ export declare function layer(handler: (request: Request) => Promise<Response>):
 /**
  * The native `HttpClient`, answered in memory by `routes` instead of the network: provide
  * it to `ActionHttp.client` and to `mcpClient`. The routes are built with this layer and
- * released with its scope, without request logs. What they still require is this layer's, as
+ * released with its scope, without request logs: only the cause of a defect, of a result that
+ * does not encode or of a failure a route of your own leaves unhandled is logged, as an error,
+ * where a server's request logger would show it, on the process console even under `it.effect`
+ * and its `TestConsole`. What they still require is this layer's, as
  * under `HttpRouter.serve`: a builder's services, and a per-request service no middleware of
  * theirs provides, including one a global middleware reads. The routes keep their real
  * authentication: a client sends its caller's credential. Provided around it, the test
@@ -28,6 +32,8 @@ export declare function layer(handler: (request: Request) => Promise<Response>):
  * the rest, whose `FileSystem` is a no-op. A relative URL resolves against `http://localhost`.
  * The client is the layer's own: the program's other HTTP clients get none of its requests,
  * and it none of theirs.
+ * Guide: `docs/Testing.md` in this package; in an application: `examples/notes-service/test/`.
+ * A type error at `it.effect`, such as one naming `Scope`: `docs/Testing-failures.md`.
  */
 export declare function layer<A, E, R>(routes: Layer.Layer<A, E, R>): Layer.Layer<HttpClient.HttpClient, E, Exclude<HttpRouter.Request.Without<R> | HttpRouter.Request.Only<"Requires", R> | HttpRouter.Request.Only<"GlobalRequires", R>, Served>>;
 /** Where `mcpClient` sends, and through what client. */
@@ -37,7 +43,10 @@ export interface McpClientOptions {
    * the default `ActionMcp.layerHttp` path.
    */
   readonly url?: string;
-  /** Wraps the native `HttpClient`, as `ActionHttp.client` takes it: a bearer token, say. */
+  /**
+   * Wraps the native `HttpClient`, as `ActionHttp.client` takes it: a bearer token is
+   * `HttpClient.mapRequest(HttpClientRequest.bearerToken(token))`.
+   */
   readonly transformClient?: (client: HttpClient.HttpClient) => HttpClient.HttpClient;
 }
 /** Where an `mcpRequest` goes, and with what headers. */
@@ -52,19 +61,15 @@ export interface McpRequestOptions {
 }
 declare const McpCallError_base: Schema.Class<McpCallError, Schema.TaggedStruct<"McpCallError", {
   readonly message: Schema.String;
-}>, import("effect/Cause").YieldableError>;
+}>, Cause.YieldableError>;
 /**
- * An answer a client method cannot decode as the action's success or a declared error,
- * such as the native server's message for invalid arguments or an unknown tool. Its message
- * holds the answer.
+ * An answer a client method cannot read as the action's success or a declared error, such as
+ * the native server's message for invalid arguments or an unknown tool, or a result without
+ * its structured content. Its message holds the answer. Structured content that does not
+ * decode as the success is a `SchemaError` instead, and a request that fails an
+ * `HttpClientError`.
  */
 export declare class McpCallError extends McpCallError_base {}
-/**
- * What one call of `A` fails with: a declared error value (the action's own or a built-in one
- * from the tool, or a refusal from the endpoint's authentication), a `SchemaError` when the
- * input does not encode or the success does not decode, an `HttpClientError` when the
- * endpoint could not be reached, or an `McpCallError` for any other answer.
- */
 type CallError<A extends Any> = A["error"][number]["Type"] | BuiltIn | Schema.SchemaError | HttpClientError.HttpClientError | McpCallError;
 /** Every action of `Actions` as `client.<action>(input)`, calling its tool. */
 export type McpClient<Actions extends ReadonlyArray<Any>> = { readonly [A in Actions[number] as A["name"]]: Call<A, Effect.Effect<A["success"]["Type"], CallError<A>>>; };
@@ -75,13 +80,15 @@ export type McpClient<Actions extends ReadonlyArray<Any>> = { readonly [A in Act
  * media field from the blocks whose `_meta` names it, and a success that is media, or whose
  * every field is, from its blocks alone. A declared error the tool returns, the action's own
  * or a refusal, is its decoded value, and so is a refusal the endpoint's authentication
- * answers with. The argument may be omitted when `{}` is a valid input. Requires the native
- * `HttpClient`, such as the one `layer` provides.
+ * answers with: a test telling a 401 or 403 from a tool result asserts the status of a request
+ * `mcpRequest` builds. The argument may be omitted when `{}` is a valid input. Requires the
+ * native `HttpClient`, such as the one `layer` provides.
  */
 export declare function mcpClient<const Actions extends ReadonlyArray<Any>>(actions: Actions, options?: McpClientOptions): Effect.Effect<McpClient<Actions>, never, HttpClient.HttpClient>;
 /**
  * One stateless MCP request of `method` with `params`, as `ActionMcp.layerHttp` serves it,
- * as the native request value: the JSON-RPC envelope, the 2026-07-28 headers, `mcp-name` from
+ * as the native request value: the JSON-RPC envelope, the 2026-07-28 headers (`Accept`,
+ * `MCP-Protocol-Version`, `MCP-Method`), `mcp-name` from
  * `params.uri` for `resources/read` and `params.name` otherwise, and the client metadata in
  * `_meta` are filled in, under any `_meta` given, such as a `progressToken`; the protocol
  * version is always the request's own. The test sends it: `HttpClient.execute` answers the

package/dist/Testing.mjs

@@ -1,13 +1,13 @@
-import { Refusal } from "./internal/errors.mjs";
-import { assertOnce, projectedErrors } from "./internal/actions.mjs";
-import { inputOf } from "./internal/call.mjs";
-import { defaultPath, liftOf, statelessRequest } from "./internal/mcp.mjs";
-import { clientOf } from "./internal/memory.mjs";
-import { Context, Effect, FileSystem, Layer, Option, Path, Predicate, Schema, identity } from "effect";
-import { Etag, HttpClient, HttpClientRequest, HttpEffect, HttpPlatform, HttpRouter } from "effect/http";
+import { Refusal } from "./contract/errors.mjs";
+import { assertOnce, projectedErrors } from "./contract/rules.mjs";
+import { checked } from "./contract/call.mjs";
+import { defaultPath, liftOf, statelessRequest } from "./mcp/protocol.mjs";
+import { clientOf } from "./testing/memory.mjs";
+import { Cause, Console, Context, Effect, ErrorReporter, FileSystem, Layer, Option, Path, Predicate, Schema, identity } from "effect";
 import { McpSchema } from "effect/ai";
+import { Etag, HttpClient, HttpClientRequest, HttpEffect, HttpPlatform, HttpRouter } from "effect/http";
 import { Base64, Sse } from "effect/encoding";
-//#region src/Testing.ts
+//#region src/testing/Testing.ts
 function layer(routes) {
 	if (!Layer.isLayer(routes)) return clientOf(routes);
 	return Layer.unwrap(Effect.gen(function* () {
@@ -15,27 +15,24 @@ function layer(routes) {
 		const platform = yield* Layer.build(Layer.fresh(Layer.mergeAll(HttpPlatform.layer, Path.layer, Etag.layerWeak).pipe(Layer.provideMerge(Layer.succeed(FileSystem.FileSystem, fileSystem)))));
 		const context = Context.merge(platform, yield* Effect.context());
 		const app = yield* HttpRouter.toHttpEffect(routes).pipe(Effect.provideContext(context));
-		return clientOf(HttpEffect.toWebHandlerWith(context)(app));
+		return clientOf(HttpEffect.toWebHandlerWith(context)(Effect.tapCause(app, (cause) => isReported(cause) ? Effect.logError(cause).pipe(Effect.provideService(Console.Console, globalThis.console)) : Effect.void)));
 	}));
 }
+const isReported = (cause) => cause.reasons.some((reason) => Cause.isFailReason(reason) && !ErrorReporter.isIgnored(reason.error) || Cause.isDieReason(reason) && !ErrorReporter.isIgnored(reason.defect));
 /**
-* An answer a client method cannot decode as the action's success or a declared error,
-* such as the native server's message for invalid arguments or an unknown tool. Its message
-* holds the answer.
+* An answer a client method cannot read as the action's success or a declared error, such as
+* the native server's message for invalid arguments or an unknown tool, or a result without
+* its structured content. Its message holds the answer. Structured content that does not
+* decode as the success is a `SchemaError` instead, and a request that fails an
+* `HttpClientError`.
 */
 var McpCallError = class extends Schema.TaggedError()("McpCallError", { message: Schema.String }) {};
-/** The text of a block, none of a block of another kind. */
 const textOf = (block) => block?.type === "text" ? block.text : void 0;
-/** The JSON-RPC response to a `tools/call`: the native tool result, or a protocol error. */
-const ToolReply = Schema.Union([Schema.Struct({ result: McpSchema.CallToolResult }), Schema.Struct({ error: Schema.Struct({
+const ToolCallReply = Schema.Union([Schema.Struct({ result: McpSchema.CallToolResult }), Schema.Struct({ error: Schema.Struct({
 	code: Schema.Finite,
 	message: Schema.String
 }) })]);
-const decodeReply = Schema.decodeUnknownOption(Schema.fromJsonString(ToolReply));
-/**
-* The reply in a response: its body when it is one JSON message, or the last reply among an
-* event stream's events, which notifications may precede.
-*/
+const decodeReply = Schema.decodeUnknownOption(Schema.fromJsonString(ToolCallReply));
 const replyOf = (response, text) => {
 	if (!(response.headers["content-type"] ?? "").startsWith("text/event-stream")) return decodeReply(text);
 	const data = [];
@@ -44,40 +41,25 @@ const replyOf = (response, text) => {
 	}).feed(text);
 	return Option.fromNullishOr(data.flatMap((message) => Option.toArray(decodeReply(message))).at(-1));
 };
-/**
-* The JSON of the media `field` a tool result's blocks hold: those of its kind naming it, or
-* none, for the whole success, in order; an array, or else the one, if any. Surplus blocks for
-* one value stay an array, which its decoding refuses.
-*/
-const mediaOf = ({ name, kind, many }, result) => {
+const mediaFromBlocks = ({ name, kind, many }, result) => {
 	const values = result.content.flatMap((block) => block.type === kind && block._meta?.["effect-actions/field"] === name ? [{
 		data: Base64.encode(block.data),
 		mimeType: block.mimeType
 	}] : []);
 	return many || values.length > 1 ? values : values[0];
 };
-/**
-* The encoded success of a tool result lifting the media `lift` finds: the whole success's
-* blocks, or its structured content with each media field taken from its blocks alone, an
-* empty one when nothing else was left.
-*/
-const reassembled = (lift, result) => {
+const encodedSuccessOf = (lift, result) => {
 	const [whole] = lift.fields;
-	if (whole !== void 0 && whole.name === void 0) return mediaOf(whole, result);
+	if (whole !== void 0 && whole.name === void 0) return mediaFromBlocks(whole, result);
 	const { structuredContent = {} } = result;
 	if (!Predicate.isObject(structuredContent)) return structuredContent;
 	const lifted = new Set(lift.fields.map(({ name }) => name));
 	return Object.fromEntries([...Object.entries(structuredContent).filter(([key]) => !lifted.has(key)), ...lift.fields.flatMap((field) => {
-		const value = mediaOf(field, result);
+		const value = mediaFromBlocks(field, result);
 		return field.name === void 0 || value === void 0 ? [] : [[field.name, value]];
 	})]);
 };
-/** Fail with the value of one of `errors` that `text` holds, or else with `otherwise`. */
 const failWith = (errors, text, otherwise) => Schema.decodeUnknownEffect(Schema.fromJsonString(Schema.toCodecJson(Schema.Union(errors))))(text).pipe(Effect.mapError(() => otherwise), Effect.flatMap(Effect.fail));
-/**
-* The tool call of `action`, whose success its tool lifts as `lift` says, with `input` on
-* `client`, sending to `url`.
-*/
 const callTool = (client, url, action, lift, input) => {
 	const { name } = action;
 	const other = (answer) => new McpCallError({ message: `MCP tools/call "${name}" ${answer}` });
@@ -101,7 +83,7 @@ const callTool = (client, url, action, lift, input) => {
 			return yield* failWith(projectedErrors(action), error, other(`returned an error: ${error}`));
 		}
 		if (result.structuredContent === void 0 && lift.rest !== void 0) return yield* Effect.fail(other(`returned no structured content: ${text}`));
-		return yield* Schema.decodeUnknownEffect(Schema.toCodecJson(action.success))(reassembled(lift, result));
+		return yield* Schema.decodeUnknownEffect(Schema.toCodecJson(action.success))(encodedSuccessOf(lift, result));
 	});
 };
 function mcpClient(actions, { url = defaultPath, transformClient = identity } = {}) {
@@ -110,13 +92,14 @@ function mcpClient(actions, { url = defaultPath, transformClient = identity } =
 		const client = transformClient(native);
 		return Object.fromEntries(actions.map((action) => {
 			const lift = liftOf(action.success);
-			return [action.name, (...args) => Effect.flatMap(inputOf(action, args), (input) => callTool(client, url, action, lift, input))];
+			return [action.name, checked(action, (input) => callTool(client, url, action, lift, input))];
 		}));
 	});
 }
 /**
 * One stateless MCP request of `method` with `params`, as `ActionMcp.layerHttp` serves it,
-* as the native request value: the JSON-RPC envelope, the 2026-07-28 headers, `mcp-name` from
+* as the native request value: the JSON-RPC envelope, the 2026-07-28 headers (`Accept`,
+* `MCP-Protocol-Version`, `MCP-Method`), `mcp-name` from
 * `params.uri` for `resources/read` and `params.name` otherwise, and the client metadata in
 * `_meta` are filled in, under any `_meta` given, such as a `progressToken`; the protocol
 * version is always the request's own. The test sends it: `HttpClient.execute` answers the
@@ -126,8 +109,8 @@ function mcpClient(actions, { url = defaultPath, transformClient = identity } =
 * a call its types would not send.
 */
 const mcpRequest = (method, params = {}, { headers = {}, url = defaultPath } = {}) => {
-	const { headers: routing, body } = statelessRequest(method, params);
-	return HttpClientRequest.post(url).pipe(HttpClientRequest.setHeaders(headers), HttpClientRequest.setHeaders(routing), HttpClientRequest.bodyJsonUnsafe(body));
+	const { headers: routingHeaders, body } = statelessRequest(method, params);
+	return HttpClientRequest.post(url).pipe(HttpClientRequest.setHeaders(headers), HttpClientRequest.setHeaders(routingHeaders), HttpClientRequest.bodyJsonUnsafe(body));
 };
 //#endregion
 export { McpCallError, layer, mcpClient, mcpRequest };

package/dist/{internal/authentication.d.mts → authentication/provider.d.mts}

@@ -1,11 +1,11 @@
-import { Anyone } from "./actions.mjs";
-import { Refusal } from "./errors.mjs";
-import { Protected, ServedRequest, Serving } from "./implementation.mjs";
+import { Anyone } from "../contract/rules.mjs";
+import { Refusal } from "../contract/errors.mjs";
+import { BuildServices, Protected, ServedRequest, Serving } from "../contract/implementation.mjs";
 import { Action_d_exports, Any as Any$1, Errors } from "../Action.mjs";
 import { Context, Effect } from "effect";
 import { HttpRouter, HttpServerResponse } from "effect/http";
 import { HttpApiMiddleware, HttpApiSecurity } from "effect/http-api";
-//#region src/internal/authentication.d.ts
+//#region src/authentication/provider.d.ts
 /** One native security scheme: Bearer unless a descriptor names another. */
 export type Security = HttpApiSecurity.HttpApiSecurity;
 /** What a native scheme decodes: a `Redacted` token or key, or Basic credentials. */
@@ -34,6 +34,12 @@ type Response = Effect.Effect<HttpServerResponse.HttpServerResponse, unknown, un
 interface Runtime$1 {
   /** The descriptor the provider was built from, the one a binding naming it must hold. */
   readonly descriptor: unknown;
+  /**
+   * The verifier itself, for a surface answering refusals its own way, such as RPC: the
+   * credential to the identity, or a refusal, or an error the descriptor declares. An empty
+   * credential, as the native decoder gives an absent one, is refused without reaching it.
+   */
+  readonly authenticate: (credential: Credential) => Effect.Effect<unknown, unknown, unknown>;
   /** The native security middleware's implementation, keyed by its scheme. */
   readonly middleware: Readonly<Record<string, (route: Response, options: {
     readonly credential: Credential;
@@ -43,6 +49,11 @@ interface Runtime$1 {
    * answered with its challenge under Bearer; as it is under another scheme.
    */
   readonly stepUp: HttpApiMiddleware.HttpApiMiddleware<never, never, never>;
+  /**
+   * An MCP endpoint's request: decoded here, and a protected tool's call promotes what it
+   * verified. Where `optional`, a request presenting no credential, which the scheme decodes as
+   * empty, passes signed out.
+   */
   readonly http: <E, R>(route: Effect.Effect<HttpServerResponse.HttpServerResponse, E, R>, optional: boolean) => Effect.Effect<HttpServerResponse.HttpServerResponse, E, R | HttpRouter.Provided>;
   /**
    * A route of the host's own: the request is decoded here, the route gets the identity
@@ -61,7 +72,7 @@ export interface Descriptor<I, A, S extends Security, Name extends string = stri
   readonly security: S;
   /**
    * What its verifier may fail with besides a refusal, as a list: every protected endpoint
-   * declares it, and every remote surface sends it with its status.
+   * declares it, and every remote surface sends it, over HTTP with its status.
    */
   readonly error: E;
   readonly "~provider": Context.Key<Provider<I, Name>, Runtime$1>;
@@ -69,12 +80,12 @@ export interface Descriptor<I, A, S extends Security, Name extends string = stri
   /** An MCP request's verified identity, which a protected tool's call promotes. */
   readonly "~verified": Context.Key<never, unknown>;
 }
-export type Any = Descriptor<unknown, unknown, Security, string, Errors>;
-export type Identity<A extends Any$1> = [A] extends [never] ? never : A["caller"] extends Context.Key<infer I, unknown> ? I : never;
 /**
- * The identity a descriptor for `A` must authenticate: `unknown` for an erased action, whose
- * key is known only at run time, where `assertAuthentication` checks it.
+ * Any descriptor `make` returns, named so a package emitting declarations can export one, and a
+ * binding name one.
  */
+export type Any = Descriptor<unknown, unknown, Security, string, Errors>;
+export type Identity<A extends Any$1> = [A] extends [never] ? never : A["caller"] extends Context.Key<infer I, unknown> ? I : never;
 type Covered<A extends Any$1> = Exclude<A["caller"], typeof Anyone> extends Context.Key<infer I, unknown> ? I : never;
 export type Required<A extends Any$1> = [Protected<A>] extends [never] ? {
   readonly authentication?: Any;
@@ -82,6 +93,16 @@ export type Required<A extends Any$1> = [Protected<A>] extends [never] ? {
   readonly authentication: Descriptor<Covered<Protected<A>>, unknown, Security, string, Errors>;
 };
 export type ProviderOf<D> = D extends Descriptor<infer I, unknown, Security, infer Name, Errors> ? Provider<I, Name> : never;
+/** Actions a binding takes without options: public ones, as a protected one names its descriptor. */
+export type PublicOnly<Actions extends ReadonlyArray<Any$1>> = [Exclude<Actions[number], {
+  readonly caller: typeof Anyone;
+}>] extends [never] ? unknown : {
+  readonly "Protected actions take options naming their authentication": never;
+};
+/** The descriptor options `O` name, where they always name one. */
+export type DescriptorOf<O> = [O] extends [{
+  readonly authentication: infer D extends Any;
+}] ? D : undefined;
 /** All protected actions on a surface use the descriptor's single identity key. */
 export type Matching<A extends Any$1, D> = unknown extends Covered<Protected<A>> ? unknown : [Exclude<Covered<Protected<A>>, D extends Descriptor<infer I, unknown, Security, string, Errors> ? I : never>] extends [never] ? unknown : {
   readonly "Authentication descriptor does not cover every protected action": never;
@@ -90,6 +111,17 @@ export type Matching<A extends Any$1, D> = unknown extends Covered<Protected<A>>
 export type RemoteRequest<App, A extends Any$1> = ServedRequest<App, Extract<A, {
   readonly caller: typeof Anyone;
 }>> | Exclude<ServedRequest<App, Protected<A>>, Identity<Protected<A>>>;
+/**
+ * What a server of the actions `A` of the implementations `App` reads at startup, as
+ * `BuildServices` states it, with the caller a builder yields named as the mistake it is: a server
+ * has its caller per request.
+ */
+export type ServerBuildServices<App, A extends Any$1> = App extends unknown ? BuildServices<App, A> extends (infer R) ? R extends Identity<Protected<A>> ? {
+  readonly "A builder yields the caller, which a server has per request: yield it in a handler or an authorizer": {
+    readonly caller: R;
+    readonly builderOf: Serving<App, A>["name"];
+  };
+} : R : never : never;
 /**
  * What a call of `A` under the descriptor `D` may fail with from its verifier: the errors `D`
  * declares, for a protected action; none for a public one, which nothing verifies.

package/dist/authentication/provider.mjs

@@ -0,0 +1,12 @@
+import { Unauthenticated } from "../contract/errors.mjs";
+import { Anyone } from "../contract/rules.mjs";
+import { Effect, Option } from "effect";
+//#region src/authentication/provider.ts
+const withVerifierErrors = (action, errors, verifierErrors) => action.caller === Anyone || verifierErrors === void 0 ? errors : [...errors, ...verifierErrors];
+const assertAuthentication = (actions, auth) => {
+	for (const action of actions) if (action.caller !== Anyone && (auth === void 0 || action.caller.key !== auth.identity.key)) throw new Error(`Protected action '${action.name}' requires its matching authentication descriptor`);
+};
+const providerOf = (auth) => Effect.flatMap(Effect.service(auth["~provider"]), (provider) => provider.descriptor === auth ? Effect.succeed(provider) : Effect.die(/* @__PURE__ */ new Error(`Authentication "${auth.name}": the binding's descriptor is not its provider's; build both from one descriptor`)));
+const promote = (auth, run) => Effect.flatMap(Effect.serviceOption(auth["~verified"]), (actor) => Option.isSome(actor) ? Effect.provideService(run, auth.identity, actor.value) : Effect.fail(new Unauthenticated()));
+//#endregion
+export { assertAuthentication, promote, providerOf, withVerifierErrors };

package/dist/authentication/refusal.mjs

@@ -0,0 +1,36 @@
+import { Refusal, statuses } from "../contract/errors.mjs";
+import { Cause, Context, Effect, Exit, Option, Predicate, Ref, Schema } from "effect";
+import { HttpServerResponse } from "effect/http";
+//#region src/authentication/refusal.ts
+const rfc6750ErrorDescriptionCharacters = /^[\x20\x21\x23-\x5B\x5D-\x7E]+$/;
+const challenge = (scheme, parameters) => {
+	const given = parameters.flatMap(([name, value]) => value === void 0 ? [] : [`${name}="${value.replace(/["\\]/g, "\\$&")}"`]);
+	return given.length === 0 ? scheme : `${scheme} ${given.join(", ")}`;
+};
+const bearer = (parameters) => challenge("Bearer", parameters);
+const encode = Schema.encodeSync(Refusal);
+const isRefusal = Schema.is(Refusal);
+const insufficientScopeChallenge = (error, metadataUrl) => Predicate.isTagged(error, "Forbidden") && error.scopes !== void 0 ? bearer([
+	["error", "insufficient_scope"],
+	["scope", error.scopes.join(" ")],
+	["resource_metadata", metadataUrl],
+	["error_description", rfc6750ErrorDescriptionCharacters.test(error.message) ? error.message : void 0]
+]) : void 0;
+const plain = (error) => HttpServerResponse.jsonUnsafe(encode(error), { status: statuses[error._tag] });
+const answer = (error, metadataUrl) => {
+	const response = plain(error);
+	const scoped = insufficientScopeChallenge(error, metadataUrl);
+	return scoped === void 0 ? response : HttpServerResponse.setHeader(response, "www-authenticate", scoped);
+};
+var SteppedUpRefusal = class extends Context.Service()("effect-actions/SteppedUp") {};
+const isStepUp = (error) => isRefusal(error) && (!Predicate.isTagged(error, "Forbidden") || error.scopes !== void 0);
+const recordStepUp = (call) => Effect.tapError(call, (error) => isStepUp(error) ? Effect.flatMap(Effect.serviceOption(SteppedUpRefusal), (slot) => Option.isSome(slot) ? Ref.set(slot.value, Option.some(error)) : Effect.void) : Effect.void);
+const answerStepUp = (route, metadataUrl) => Effect.gen(function* () {
+	const slot = yield* Ref.make(Option.none());
+	const exit = yield* Effect.exit(Effect.provideService(route, SteppedUpRefusal, slot));
+	const refused = yield* Ref.get(slot);
+	const diedOrInterruptedAfterRefusal = Exit.isFailure(exit) && (Cause.hasDies(exit.cause) || Cause.hasInterrupts(exit.cause));
+	return Option.isSome(refused) && !diedOrInterruptedAfterRefusal ? answer(refused.value, metadataUrl) : yield* exit;
+});
+//#endregion
+export { answer, answerStepUp, bearer, challenge, isRefusal, isStepUp, plain, recordStepUp };

package/dist/{internal/cli.d.mts → cli/commands.d.mts}

@@ -1,14 +1,11 @@
-import "./errors.mjs";
+import "../contract/errors.mjs";
 import { Action_d_exports, Any } from "../Action.mjs";
 import { Effect, Runtime, Types } from "effect";
 import { CliError, Command } from "effect/cli";
-//#region src/internal/cli.d.ts
-/**
- * The fields of `A`'s input that may be positional: the named top-level fields of a struct
- * or class input, as encoded. None for any other input, a record or a union included.
- */
-export type Field<A extends Any> = A["input"]["Encoded"] extends (infer E) ? true extends Types.IsUnion<E> ? never : E extends ReadonlyArray<unknown> ? never : E extends object ? string extends keyof E ? never : Extract<keyof E, string> : never : never;
-/** How one command is named, takes its input and prints its result. */
+//#region src/cli/commands.d.ts
+type Field<A extends Any> = A["input"]["Encoded"] extends (infer E) ? true extends Types.IsUnion<E> ? never : E extends ReadonlyArray<unknown> ? never : E extends object ? string extends keyof E ? never : Extract<keyof E, string> : never : never;
+type StdinField<A extends Any> = A["input"]["Encoded"] extends (infer E) ? Exclude<Field<A>, { [K in keyof E]-?: {} extends Pick<E, K> ? K : never; }[keyof E]> : never;
+/** How one command of `A` is named, takes its input and prints its result. */
 export interface Options<A extends Any> {
   /** Override the command name. The action name, in kebab case, is used by default. */
   readonly name?: string;
@@ -24,12 +21,19 @@ export interface Options<A extends Any> {
    * `Param.withAlias` takes it.
    */
   readonly aliases?: { readonly [K in Field<A>]?: string; };
+  /**
+   * A required field read from stdin instead of a flag, such as a secret, which a flag would
+   * leave in the process list and the shell's history.
+   */
+  readonly stdin?: StdinField<A>;
 }
 /**
- * What a command fails with when its action fails: Effect CLI's own error for a handler's
- * failure, which `Command.run` prints on stderr and marks reported, so `runMain` does not
- * print it again. Its `cause` is the action's failure. The process exits with the cause's
- * `Runtime.errorExitCode`, 1 by default.
+ * What a command fails with when its action fails: Effect CLI's `UserError`, typed with the
+ * action's failure as its `cause` and `reason`, and whose message is its JSON, which `Command.run`
+ * prints on stderr and marks reported, so `runMain` does not print it again. The process exits with
+ * the cause's `Runtime.errorExitCode`, 1 by default. A type only: after `Command.run`, match the
+ * reason by its tag, `Effect.catchReason("UserError", "UserNotFound", f)`. A command of your own
+ * fails with one through `toUserError`; any other failure is reported as a crash, `ERROR (#n)`.
  */
 export declare class UserError<out E = unknown> extends CliError.UserError {
   readonly cause: E;