@gjermundgaraba/effect-actions 0.10.0 → 0.12.0

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 };

package/dist/{internal → contract}/call.d.mts

@@ -1,12 +1,12 @@
 import "./implementation.mjs";
 import { Action_d_exports, Any } from "../Action.mjs";
 import { Effect, Schema } from "effect";
-//#region src/internal/call.d.ts
+//#region src/contract/call.d.ts
 /**
  * A call of `A` answering `R`. It may leave its input out when `{}` is a valid encoded input,
  * such as for an action declared without `input` or one whose every field has a decoding
  * default, and then sends the input `{}` decodes to. Every client shares this rule:
- * `ActionHttp.client`, `Testing.mcpClient` and `Action.client`.
+ * `ActionHttp.client`, `ActionRpc.client`, `Testing.mcpClient` and `Action.client`.
  */
 export type Call<A extends Any, R> = {} extends A["input"]["Encoded"] ? (...input: [] | [input: A["input"]["Type"]]) => R : (input: A["input"]["Type"]) => R;
 //#endregion

package/dist/contract/call.mjs

@@ -0,0 +1,10 @@
+import { InvalidInput } from "./errors.mjs";
+import { Effect, Schema } from "effect";
+//#region src/contract/call.ts
+const inputOf = (action, args) => args.length === 0 ? Schema.decodeUnknownEffect(Schema.toCodecJson(action.input))({}) : Effect.succeed(args[0]);
+const checked = (action, send) => {
+	const encode = Schema.encodeUnknownEffect(Schema.toCodecJson(action.input), { errors: "all" });
+	return (...args) => inputOf(action, args).pipe(Effect.tap(encode), Effect.mapError(InvalidInput.fromSchemaError), Effect.flatMap(send));
+};
+//#endregion
+export { checked, inputOf };

package/dist/{internal → contract}/errors.d.mts

@@ -1,14 +1,14 @@
 import { Schema } from "effect";
-//#region src/internal/errors.d.ts
-/**
- * One thing wrong with an input: where, as the keys and indexes leading to it from the input's
- * root, none for the input itself, and what the schema expects there.
- */
+//#region src/contract/errors.d.ts
 declare const Issue: Schema.Struct<{
   readonly path: Schema.$Array<Schema.Union<readonly [Schema.String, Schema.Finite]>>;
   readonly message: Schema.String;
 }>;
-/** One thing wrong with an input, as `InvalidInput.issues` lists it. */
+/**
+ * One thing wrong with an input, as `InvalidInput.issues` lists it: where, as the keys and
+ * indexes leading to it from the input's root, none for the input itself, and what the schema
+ * expects there.
+ */
 type Issue = (typeof Issue)["Type"];
 declare const InvalidInput_base: Schema.Class<InvalidInput, Schema.TaggedStruct<"InvalidInput", {
   readonly message: Schema.withConstructorDefault<Schema.String>;
@@ -24,7 +24,7 @@ declare const InvalidInput_base: Schema.Class<InvalidInput, Schema.TaggedStruct<
  * failing with it for input that decodes but cannot be served may name its own.
  */
 export declare class InvalidInput extends InvalidInput_base {
-  private readonly "~builtIn";
+  private readonly "~declared in the action's error, or built in";
   /**
    * The `InvalidInput` for input that did not decode, as every surface answers it: the
    * schema's message, and each of its issues by path, for code that decodes input of its own,
@@ -40,7 +40,7 @@ declare const Unauthenticated_base: Schema.Class<Unauthenticated, Schema.TaggedS
 }>, import("effect/Cause").YieldableError>;
 /** The caller is not authenticated: authentication or an implementation's `authorize` refuses. */
 export declare class Unauthenticated extends Unauthenticated_base {
-  private readonly "~builtIn";
+  private readonly "~declared in the action's error, or built in";
 }
 declare const Forbidden_base: Schema.Class<Forbidden, Schema.TaggedStruct<"Forbidden", {
   readonly message: Schema.withConstructorDefault<Schema.String>;
@@ -49,10 +49,13 @@ declare const Forbidden_base: Schema.Class<Forbidden, Schema.TaggedStruct<"Forbi
 /**
  * The caller may not run this action: an implementation's `authorize` refuses. `scopes`,
  * when given, are every OAuth scope the call needs: a refusal naming them is answered with
- * the `insufficient_scope` challenge an OAuth client re-authorizes on.
+ * the `insufficient_scope` challenge an OAuth client re-authorizes on, so name them only where
+ * re-authorizing can grant them. Over HTTP it is a 403 either way. Over MCP, from an authorizer
+ * or a handler, it is a 403 only when it names scopes on an endpoint under Bearer, and
+ * otherwise a tool result with `isError: true`, in a 200 response.
  */
 export declare class Forbidden extends Forbidden_base {
-  private readonly "~builtIn";
+  private readonly "~declared in the action's error, or built in";
 }
 /**
  * What authentication or an implementation's `authorize` refuses a caller with, instead of

package/dist/{internal → contract}/errors.mjs

@@ -1,17 +1,11 @@
 import { Effect, Predicate, Schema, SchemaIssue } from "effect";
-//#region src/internal/errors.ts
-/** A message field that defaults, so `new Forbidden()` needs no argument. */
-const message = (fallback) => Schema.String.pipe(Schema.withConstructorDefault(Effect.succeed(fallback)));
-/** Each built-in error's HTTP status, by tag: its annotation, and what a refusal answers. */
+//#region src/contract/errors.ts
+const defaultedMessage = (fallback) => Schema.String.pipe(Schema.withConstructorDefault(Effect.succeed(fallback)));
 const statuses = {
 	InvalidInput: 400,
 	Unauthenticated: 401,
 	Forbidden: 403
 };
-/**
-* One thing wrong with an input: where, as the keys and indexes leading to it from the input's
-* root, none for the input itself, and what the schema expects there.
-*/
 const Issue = Schema.Struct({
 	path: Schema.Array(Schema.Union([Schema.String, Schema.Finite])),
 	message: Schema.String
@@ -24,7 +18,7 @@ const standardIssues = SchemaIssue.makeFormatterStandardSchemaV1();
 * failing with it for input that decodes but cannot be served may name its own.
 */
 var InvalidInput = class InvalidInput extends Schema.TaggedError()("InvalidInput", {
-	message: message("The input does not match the action's input."),
+	message: defaultedMessage("The input does not match the action's input."),
 	issues: Schema.Array(Issue).pipe(Schema.withConstructorDefault(Effect.succeed([])))
 }, { httpApiStatus: statuses.InvalidInput }) {
 	/**
@@ -47,20 +41,21 @@ var InvalidInput = class InvalidInput extends Schema.TaggedError()("InvalidInput
 	});
 };
 /** The caller is not authenticated: authentication or an implementation's `authorize` refuses. */
-var Unauthenticated = class extends Schema.TaggedError()("Unauthenticated", { message: message("Authentication is required.") }, { httpApiStatus: statuses.Unauthenticated }) {};
-/** An OAuth scope token (RFC 6749 §3.3): printable ASCII but space, `"` and `\`. */
+var Unauthenticated = class extends Schema.TaggedError()("Unauthenticated", { message: defaultedMessage("Authentication is required.") }, { httpApiStatus: statuses.Unauthenticated }) {};
 const scopeToken = /^[\x21\x23-\x5B\x5D-\x7E]+$/;
 const ScopeToken = Schema.String.check(Schema.isPattern(scopeToken));
 /**
 * The caller may not run this action: an implementation's `authorize` refuses. `scopes`,
 * when given, are every OAuth scope the call needs: a refusal naming them is answered with
-* the `insufficient_scope` challenge an OAuth client re-authorizes on.
+* the `insufficient_scope` challenge an OAuth client re-authorizes on, so name them only where
+* re-authorizing can grant them. Over HTTP it is a 403 either way. Over MCP, from an authorizer
+* or a handler, it is a 403 only when it names scopes on an endpoint under Bearer, and
+* otherwise a tool result with `isError: true`, in a 200 response.
 */
 var Forbidden = class extends Schema.TaggedError()("Forbidden", {
-	message: message("Not allowed."),
+	message: defaultedMessage("Not allowed."),
 	scopes: Schema.optionalKey(Schema.NonEmptyArray(ScopeToken))
 }, { httpApiStatus: statuses.Forbidden }) {};
-/** The refusals, as schemas. */
 const refusals = [Unauthenticated, Forbidden];
 /**
 * What authentication or an implementation's `authorize` refuses a caller with, instead of