@gjermundgaraba/effect-actions 0.11.0 → 0.12.0

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, 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) : 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;

package/dist/cli/commands.mjs

@@ -0,0 +1,302 @@
+import { InvalidInput } from "../contract/errors.mjs";
+import { assertDistinct, literalValues, members, projectedErrors, unsuspended } from "../contract/rules.mjs";
+import { withStderrConsole } from "../stdio/console.mjs";
+import { Console, Effect, Option, Predicate, Record, Runtime, Schema, SchemaAST, Stdio, Stream, flow } from "effect";
+import { CliError, Command, Flag, Param } from "effect/cli";
+//#region src/cli/commands.ts
+const kebab = (name) => {
+	const kebabbed = name.replace(/([A-Z]+)([A-Z][a-z])/g, "$1-$2").replace(/([a-z0-9])([A-Z])/g, "$1-$2").replace(/_/g, "-").replace(/^-+|-+$/g, "").toLowerCase();
+	return kebabbed === "" ? name : kebabbed;
+};
+const renderedCommandJsonFlag = Flag.Boolean("json").pipe(Flag.withDefault(false), Flag.withDescription("Print machine-readable JSON"));
+const jsonKinds = [
+	"null",
+	"boolean",
+	"number",
+	"string",
+	"array",
+	"object"
+];
+const jsonKindOf = (value) => value === null ? "null" : Predicate.isBoolean(value) ? "boolean" : Predicate.isNumber(value) ? "number" : Predicate.isString(value) ? "string" : Array.isArray(value) ? "array" : "object";
+const acceptedJsonKindsOf = (ast) => members(ast).flatMap((member) => {
+	if (SchemaAST.isLiteral(member)) return [jsonKindOf(member.literal)];
+	if (SchemaAST.isEnum(member)) return member.enums.map(([, value]) => jsonKindOf(value));
+	if (SchemaAST.isNull(member)) return ["null"];
+	if (SchemaAST.isBoolean(member)) return ["boolean"];
+	if (SchemaAST.isNumber(member)) return ["number"];
+	if (SchemaAST.isString(member) || SchemaAST.isTemplateLiteral(member)) return ["string"];
+	if (SchemaAST.isArrays(member)) return ["array"];
+	if (SchemaAST.isObjects(member)) return ["object"];
+	return jsonKinds;
+});
+const jsonOfAcceptedKindOrText = (encoded) => {
+	const accepted = new Set(acceptedJsonKindsOf(encoded));
+	return Schema.Union([Schema.fromJsonString(Schema.Json).check(Schema.makeFilter((json) => accepted.has(jsonKindOf(json)))), Schema.String]);
+};
+const stringChoicesOf = (ast) => {
+	const accepted = members(ast).flatMap(literalValues);
+	return accepted.every(Predicate.isString) ? accepted : void 0;
+};
+const takesTextAsIs = (encoded) => stringChoicesOf(encoded) !== void 0 || SchemaAST.isString(encoded) || SchemaAST.isTemplateLiteral(encoded);
+const valueParam = (kind, name, field) => {
+	const encoded = unsuspended(field);
+	if (takesTextAsIs(encoded)) {
+		const literals = stringChoicesOf(encoded);
+		return literals === void 0 ? Param.String(kind, name) : Param.Literals(kind, name, literals);
+	}
+	if (SchemaAST.isBoolean(encoded)) return Param.Boolean(kind, name);
+	return Param.String(kind, name).pipe(Param.withSchema(jsonOfAcceptedKindOrText(encoded)), Param.withMetavar("value"));
+};
+const withoutOptionalAbsence = (ast) => {
+	const members = SchemaAST.isUnion(ast) ? ast.types.filter((member) => !SchemaAST.isNull(member) && !SchemaAST.isUndefined(member)) : [];
+	return members.length === 1 && members[0] !== void 0 ? members[0] : ast;
+};
+const optionalAddedNull = (plain) => {
+	const types = members(plain);
+	return types.some(SchemaAST.isUndefined) && !types.some(SchemaAST.isNull);
+};
+const repeatedElementOf = (ast) => {
+	const encoded = unsuspended(ast);
+	if (!SchemaAST.isArrays(encoded)) return void 0;
+	const [element, ...after] = encoded.rest;
+	if (element === void 0 || after.length > 0 || !encoded.elements.every((first) => first === element) || !acceptedJsonKindsOf(element).every((kind) => kind === "string" || kind === "number")) return;
+	return {
+		element,
+		min: encoded.elements.length
+	};
+};
+const noElementOccurrence = "[]";
+const jsonHintOf = (encoded) => {
+	const value = unsuspended(encoded);
+	const kinds = new Set(acceptedJsonKindsOf(value));
+	if (kinds.size !== 1) return void 0;
+	if (kinds.has("object")) return "A JSON object.";
+	if (!kinds.has("array")) return void 0;
+	const fields = elementFieldsOf(value);
+	return fields === void 0 ? "A JSON array." : `A JSON array of {${fields.join(", ")}}.`;
+};
+const elementFieldsOf = (array) => {
+	if (!SchemaAST.isArrays(array)) return void 0;
+	const [element, ...others] = [...array.elements, ...array.rest];
+	if (element === void 0 || others.some((other) => other !== element)) return void 0;
+	const fields = namedFieldsOf(unsuspended(element));
+	return fields.size === 0 ? void 0 : Array.from(fields, ([name, field]) => SchemaAST.isOptional(field) ? `${String(name)}?` : String(name));
+};
+const withHint = (description, hint) => {
+	if (hint === void 0 || description === void 0) return description ?? hint;
+	const stated = description.trimEnd();
+	return /[.!?:]$/.test(stated) ? `${stated} ${hint}` : `${stated}. ${hint}`;
+};
+const fieldParam = (kind, name, encoded, plain) => {
+	const optional = SchemaAST.isOptional(encoded);
+	const value = optional && plain !== void 0 && optionalAddedNull(plain) ? withoutOptionalAbsence(encoded) : encoded;
+	const repeats = repeatedElementOf(value);
+	if (repeats !== void 0) {
+		const literals = stringChoicesOf(unsuspended(repeats.element));
+		const elements = literals === void 0 ? valueParam(kind, name, repeats.element) : Param.Literals(kind, name, [...literals, noElementOccurrence]);
+		const listed = (values) => Option.some(values.filter((value) => value !== noElementOccurrence));
+		return {
+			param: optional ? Param.variadic(elements).pipe(Param.map((values) => values.length === 0 ? Option.none() : listed(values))) : Param.variadic(elements, { min: repeats.min }).pipe(Param.map(listed)),
+			repeats: true,
+			hint: kind === Param.flagKind ? "Repeat for each value." : void 0
+		};
+	}
+	if (optional) return {
+		param: Param.optional(valueParam(kind, name, value)),
+		repeats: false,
+		hint: kind === Param.flagKind && SchemaAST.isBoolean(unsuspended(value)) ? `--no-${name} sends false.` : jsonHintOf(value)
+	};
+	const isSwitch = kind === Param.flagKind && SchemaAST.isBoolean(unsuspended(encoded));
+	return {
+		param: isSwitch ? Flag.Boolean(name).pipe(Flag.withDefault(false), Flag.map(Option.some)) : valueParam(kind, name, encoded).pipe(Param.map(Option.some)),
+		repeats: false,
+		hint: isSwitch ? "Left out, it sends false." : jsonHintOf(encoded)
+	};
+};
+const namedFieldsOf = (ast) => {
+	const fields = SchemaAST.isDeclaration(ast) ? ast.typeParameters[0] : ast;
+	return new Map(fields !== void 0 && SchemaAST.isObjects(fields) ? fields.propertySignatures.map((property) => [property.name, property.type]) : []);
+};
+const isTransformedAsWhole = (ast) => (SchemaAST.isDeclaration(ast) ? ast.typeParameters[0] : ast)?.encoding !== void 0;
+const ownOrSuspendedDescriptionOf = (ast) => ast.context?.annotations?.description ?? SchemaAST.resolveDescription(ast) ?? describedBeforeLastCheck(ast) ?? (SchemaAST.isSuspend(ast) ? ownOrSuspendedDescriptionOf(ast.thunk()) : void 0);
+const describedBeforeLastCheck = (ast) => [ast.annotations, ...(ast.checks ?? []).map((check) => check.annotations)].map((annotations) => annotations?.["description"]).findLast(Predicate.isString);
+const describedThroughAbsence = (ast) => ownOrSuspendedDescriptionOf(ast) ?? ownOrSuspendedDescriptionOf(withoutOptionalAbsence(ast));
+const describedByElement = (ast) => {
+	const array = unsuspended(withoutOptionalAbsence(ast));
+	const element = SchemaAST.isArrays(array) ? array.rest[0] : void 0;
+	return element === void 0 ? void 0 : describedThroughAbsence(element);
+};
+const fieldParams = (encoded, input, positional, aliases) => {
+	const plainEncodedFields = namedFieldsOf(SchemaAST.toEncoded(input));
+	const declaredFieldsUnlessRenamed = namedFieldsOf(isTransformedAsWhole(input) ? encoded : SchemaAST.toType(input));
+	return encoded.propertySignatures.map((property) => {
+		const field = String(property.name);
+		const declaredField = declaredFieldsUnlessRenamed.get(property.name);
+		const kind = positional.includes(field) ? Param.argumentKind : Param.flagKind;
+		const { param, repeats, hint } = fieldParam(kind, kebab(field), property.type, plainEncodedFields.get(property.name));
+		const alias = kind === Param.flagKind ? aliases[field] : void 0;
+		const aliased = alias === void 0 ? param : Param.withAlias(param, alias);
+		const documented = declaredField ?? property.type;
+		const description = describedThroughAbsence(documented) ?? describedThroughAbsence(property.type) ?? (repeats ? describedByElement(documented) ?? describedByElement(property.type) : void 0);
+		const help = withHint(description, hint);
+		return {
+			field,
+			param: help === void 0 ? aliased : Param.withDescription(aliased, help),
+			optional: SchemaAST.isOptional(property.type),
+			repeats,
+			hint,
+			description
+		};
+	});
+};
+const positionalOrder = (params, positional) => {
+	assertDistinct("positional argument", positional, (field) => field);
+	const ordered = positional.map((field) => {
+		const found = params.find((param) => param.field === field);
+		if (found === void 0) throw new Error(`Not an input field: ${field}`);
+		return found;
+	});
+	const firstOptional = ordered.findIndex((param) => param.optional);
+	const misplaced = ordered.slice(firstOptional === -1 ? ordered.length : firstOptional).find((param) => !param.optional);
+	if (misplaced !== void 0) throw new Error(`Required positional argument after an optional one: ${misplaced.field}`);
+	const repeatedBeforeLast = ordered.slice(0, -1).find((param) => param.repeats);
+	if (repeatedBeforeLast !== void 0) throw new Error(`Repeated positional argument before another one: ${repeatedBeforeLast.field}`);
+	return ordered;
+};
+const wholeInputFlag = (encoded) => Flag.String("input").pipe(Flag.withSchema(jsonOfAcceptedKindOrText(encoded)), Flag.withDescription("Whole action input as JSON; omitted, {}"), Flag.optional);
+const printedOutput = (action, value, render) => Effect.map(Effect.orDie(Schema.encodeEffect(Schema.toCodecJson(action.success))(value)), (encoded) => render === void 0 && SchemaAST.isVoid(action.success.ast) ? Option.none() : Option.some(render === void 0 ? JSON.stringify(encoded, null, 2) : render(value)));
+/**
+* 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)`.
+*/
+var UserError = class extends CliError.UserError {
+	/**
+	* The action's failure, as Effect names an error's nested one, so the native
+	* `Effect.catchReason("UserError", "UserNotFound", f)` and `catchReasons` match it by tag.
+	*/
+	get reason() {
+		return this.cause;
+	}
+	get [Runtime.errorExitCode]() {
+		return Runtime.getErrorExitCode(this.cause);
+	}
+};
+const ownStringProperty = (error, key) => {
+	if (!Predicate.hasProperty(error, key)) return void 0;
+	const value = error[key];
+	return Predicate.isString(value) ? value : void 0;
+};
+const describedWithoutFields = (error, seen = /* @__PURE__ */ new Set()) => {
+	const name = ownStringProperty(error, "_tag") ?? (error instanceof Error ? error.name : "Error");
+	const message = Predicate.isString(error) ? error : ownStringProperty(error, "message") ?? "";
+	const named = message === "" ? name : `${name}: ${message}`;
+	seen.add(error);
+	return Predicate.hasProperty(error, "cause") && error.cause !== void 0 && !seen.has(error.cause) ? `${named}: ${describedWithoutFields(error.cause, seen)}` : named;
+};
+const userErrorOf = (errors) => {
+	const encode = Schema.encodeUnknownEffect(Schema.fromJsonString(Schema.toCodecJson(Schema.Union(errors))));
+	return (error) => encode(error, { onExcessProperty: "error" }).pipe(Effect.catch(() => encode(error)), Effect.orElseSucceed(() => describedWithoutFields(error)), Effect.flatMap((userMessage) => Effect.fail(new UserError({
+		cause: error,
+		userMessage
+	}))));
+};
+const failingAsDerived = (actions, surfaceErrorsOf) => {
+	const failure = userErrorOf([...new Set(actions.flatMap((action) => projectedErrors(action, surfaceErrorsOf(action))))]);
+	return (self) => Effect.catchIf(self, (error) => !CliError.isCliError(error), failure);
+};
+const unreadableStdinField = (field, message) => new InvalidInput({
+	message,
+	issues: [{
+		path: [field],
+		message
+	}]
+});
+const fieldValueFromText = (field) => {
+	const encoded = unsuspended(field);
+	return takesTextAsIs(encoded) ? (text) => text : Schema.decodeSync(jsonOfAcceptedKindOrText(encoded));
+};
+const stdinTextOf = (field) => Effect.gen(function* () {
+	const stdio = yield* Effect.serviceOption(Stdio.Stdio);
+	if (Option.isNone(stdio)) return yield* Effect.die(/* @__PURE__ */ new Error("Stdio is not provided"));
+	if (yield* stdio.value.stdinIsTerminal) return yield* unreadableStdinField(field, `${field} is read from stdin, which is a terminal: pipe it in`);
+	return (yield* stdio.value.stdin.pipe(Stream.decodeText(), Stream.mkString, Effect.mapError((error) => unreadableStdinField(field, `stdin cannot be read: ${error.message}`)))).replace(/[\r\n]+$/, "");
+});
+const inputConfig = (action, positional, aliases, stdin) => {
+	const codec = Schema.toCodecJson(action.input);
+	const encoded = unsuspended(SchemaAST.toEncoded(codec.ast));
+	const decodeRefusingUndeclared = Schema.decodeUnknownEffect(codec, { onExcessProperty: "error" });
+	const decode = flow(decodeRefusingUndeclared, Effect.mapError(InvalidInput.fromSchemaError));
+	if (SchemaAST.isObjects(encoded) && encoded.indexSignatures.every((signature) => SchemaAST.isNever(signature.type))) {
+		const params = fieldParams(encoded, unsuspended(action.input.ast), positional, aliases);
+		const fromStdin = Option.map(Option.fromUndefinedOr(stdin), (field) => {
+			const property = encoded.propertySignatures.find(({ name }) => name === field);
+			if (property === void 0 || SchemaAST.isOptional(property.type)) throw new Error(`Not a required input field: ${field}`);
+			if (positional.includes(field)) throw new Error(`Both positional and stdin: ${field}`);
+			const description = params.find((param) => param.field === field)?.description;
+			return {
+				field,
+				value: fieldValueFromText(property.type),
+				help: `Reads ${kebab(field)} from stdin${description === void 0 ? "." : `: ${description}`}`
+			};
+		});
+		const flagged = new Set(params.map(({ field }) => field).filter((field) => !positional.includes(field) && field !== stdin));
+		const stray = Object.keys(aliases).find((field) => !flagged.has(field));
+		if (stray !== void 0) throw new Error(`Not a flag's input field: ${stray}`);
+		return {
+			flags: Object.fromEntries(params.flatMap(({ field, param }) => flagged.has(field) ? [[field, param]] : [])),
+			positional: positionalOrder(params, positional),
+			decode: (parsed) => Option.match(fromStdin, {
+				onNone: () => decode(Record.getSomes(parsed)),
+				onSome: ({ field, value }) => Effect.flatMap(stdinTextOf(field), (text) => decode({
+					...Record.getSomes(parsed),
+					[field]: value(text)
+				}))
+			}),
+			stdinHelp: Option.getOrUndefined(Option.map(fromStdin, ({ help }) => help))
+		};
+	}
+	if (positional.length > 0) throw new Error(`Positional arguments need named input fields: ${positional.join(", ")}`);
+	if (Object.keys(aliases).length > 0) throw new Error(`Aliases need named input fields: ${Object.keys(aliases).join(", ")}`);
+	if (stdin !== void 0) throw new Error(`Stdin needs named input fields: ${stdin}`);
+	return {
+		flags: { input: wholeInputFlag(encoded) },
+		positional: [],
+		decode: (parsed) => decode(Option.getOrElse(parsed["input"] ?? Option.none(), () => ({}))),
+		stdinHelp: void 0
+	};
+};
+const command = (action, execute, options, errors = []) => {
+	const name = options?.name ?? kebab(action.name);
+	const render = options?.render;
+	const { flags, positional, decode, stdinHelp } = inputConfig(action, options?.positional ?? [], options?.aliases ?? {}, options?.stdin);
+	const failure = userErrorOf(projectedErrors(action, errors));
+	assertDistinct("flag", [
+		...Object.keys(flags).map((field) => [`--${kebab(field)}`, `field ${field}`]),
+		...render === void 0 ? [] : [["--json", "render's --json"]],
+		...Object.entries(options?.aliases ?? {}).flatMap(([field, alias]) => Predicate.isString(alias) ? [[`--${alias.replace(/^-+/, "")}`, `alias of field ${field}`]] : [])
+	], ([flag]) => flag, ([, claimant]) => claimant);
+	const args = positional.map(({ param }) => param);
+	const parsedFields = (input, values) => ({
+		...input,
+		...Object.fromEntries(positional.map(({ field }, index) => [field, values[index] ?? Option.none()]))
+	});
+	const run = (parsed, rendered) => decode(parsed).pipe(Effect.flatMap(execute), Effect.catch(failure), Effect.flatMap((value) => printedOutput(action, value, rendered)), withStderrConsole, Effect.flatMap(Option.match({
+		onNone: () => Effect.void,
+		onSome: Console.log
+	})));
+	const command = render === void 0 ? Command.make(name, {
+		input: flags,
+		args
+	}, ({ input, args: values }) => run(parsedFields(input, values), void 0)) : Command.make(name, {
+		input: flags,
+		args,
+		json: renderedCommandJsonFlag
+	}, ({ input, args: values, json }) => run(parsedFields(input, values), json ? void 0 : render));
+	return stdinHelp === void 0 ? Command.withDescription(command, action.description) : command.pipe(Command.withDescription(`${action.description}\n\n${stdinHelp}`), Command.withShortDescription(action.description));
+};
+//#endregion
+export { UserError, command, failingAsDerived, kebab };