@gjermundgaraba/effect-actions 0.1.0-rc.1 → 0.1.0

package/README.md

@@ -1,31 +1,13 @@
-# @gjermundgaraba/effect-actions
+# effect-actions
 
-Define an Effect action once, implement it once, expose it over **HTTP and MCP**.
+Define an Effect action once. Serve it over HTTP and MCP, hand it to a model as a native
+Toolkit, run it from a CLI, and publish its contract as JSON. Same schemas, same handler,
+Effect's own servers and clients underneath.
 
-**Snapshot-dependent preview.** This release requires Effect snapshot
-[`9ad9891`](https://pkg.pr.new/Effect-TS/effect/effect@9ad9891). The published npm
-version `effect@4.0.0-rc.115` is not compatible: it lacks APIs required by the MCP
-adapter. Install both packages explicitly:
-
-```sh
-pnpm add @gjermundgaraba/effect-actions@rc \
-  'effect@https://pkg.pr.new/Effect-TS/effect/effect@9ad9891'
-```
-
-The snapshot reports version `4.0.0-rc.115`, so the package retains that nominal
-peer declaration. A semver peer cannot distinguish the snapshot from the npm
-build; satisfying the peer declaration alone does **not** ensure compatibility.
-Installation requires access to `pkg.pr.new`, not just the npm registry.
-
-For Node server wiring, use the matching platform snapshot too:
-
-```sh
-pnpm add '@effect/platform-node@https://pkg.pr.new/Effect-TS/effect/@effect/platform-node@9ad9891'
-```
-
-## Quickstart
+## Looks like this
 
 ```ts
+import { McpProtocol } from "effect/unstable/ai";
 import { Effect, Layer, Schema } from "effect";
 import * as Action from "@gjermundgaraba/effect-actions/Action";
 import * as ActionGroup from "@gjermundgaraba/effect-actions/ActionGroup";
@@ -49,227 +31,76 @@ const app = Actions.implement({
 
 export const routes = Layer.mergeAll(
   Http.layer(app),
-  ActionMcp.layer({ name: "greetings", version: "1.0.0", path: "/mcp" }, app),
+  ActionMcp.layerHttp(
+    { protocols: [McpProtocol.v2026_07_28], name: "greetings", version: "1.0.0", path: "/mcp" },
+    app,
+  ),
 );
 ```
 
-Serve `routes` with Effect's `HttpRouter`. This creates `POST /api/actions/greet` and an
-MCP endpoint at `/mcp`. The HTTP response is `"Hello, Ada!"`; MCP returns
-`structuredContent: { value: "Hello, Ada!" }`.
-See [examples/server.ts](examples/server.ts) for Node server wiring and the
-[authenticated demo](examples/README.md) for a runnable application.
-
-### Contracts
-
-- Omit `input` for an action without arguments.
-- `errors` is a list of failure schemas, defaulting to none. Each schema retains
-  its own `httpApiStatus` annotation.
-- A group's `errors` are added to every one of its actions, so a shared set, such as
-  authorization failures, is declared once. Its `schemaError` policy decides how both
-  transports answer failed decoding or encoding; see
-  [schema-error policies](docs/behavior.md#schema-error-policies).
-- Actions default to both transports; use `http: false` or `mcp: false` to opt out.
-  An action exposed on neither is rejected.
-- MCP input must have an object-root JSON Schema; declared errors must encode to
-  objects. The MCP adapter checks this at Layer construction. HTTP allows scalars.
-- `mcp.name` overrides the tool name. `destructive` defaults to `!readOnly`.
-- Schemas must be service-free. Handlers may require services.
-- The group name is the OpenAPI tag and operation-ID prefix (`greetings.greet`).
-
-## HTTP client
-
-Save the quickstart above as `quickstart.ts`. Once its routes are served:
+Serve `routes` with Effect's `HttpRouter` and you have `POST /api/actions/greetings/greet`
+and an MCP tool named `greet` at `/mcp`. The same `app` is also:
 
 ```ts
-import { Effect } from "effect";
-import { FetchHttpClient } from "effect/unstable/http";
-import { Http } from "./quickstart.js";
-
-export const greeting = Effect.gen(function* () {
-  const client = yield* Http.client({ baseUrl: "http://127.0.0.1:3000" });
-
-  return yield* client.greet({ name: "Ada" });
-}).pipe(Effect.provide(FetchHttpClient.layer));
+const { toolkit, layer } = ActionToolkit.make(app); // native Effect AI Toolkit and its handler layer
+const cli = ActionCli.group(app); // greetings greet --input '{"name":"Ada"}'
+const remote = ActionCliClient.command(Http, "greetings", "greet"); // same command, over HTTP
+const catalog = ActionCatalog.make(Actions); // offline JSON contract, no handlers acquired
 ```
 
-Run `greeting` with `Effect.runPromise`. Methods take decoded inputs and return
-decoded results; MCP-only actions are excluded. `ActionHttp.make` binds the mount path the
-server and its clients must agree on, so `client` accepts only connection options. Authentication headers can be added with
-`transformClient`. See [client details](docs/behavior.md#http-client-details)
-for error types, optional inputs, and native grouped clients.
-
-## Multiple groups
-
-An application can split its contracts and handlers into groups without splitting its
-endpoints. Configuration comes first, then the groups or implementations:
+And the client is Effect's own, typed from the same contract:
 
 ```ts
-const Http = ActionHttp.make({ apiPath: "/api/actions" }, PublicActions, UserActions);
-
-const routes = Layer.mergeAll(
-  Http.layer(PublicApp),
-  Http.layer(UserApp).pipe(Layer.provide(authentication.layer)),
-  ActionMcp.layer({ name: "my-app", version: "1.0.0", path: "/mcp" }, UserApp, AuditApp),
-);
-```
-
-- **One layer per group.** `Http.layer(app)` registers the routes of one group, and router
-  middleware provided to a layer applies to that layer alone: above, only the user group
-  requires authentication. A group that is never mounted has no routes.
-- **Each adapter reads only what it serves.** A group without HTTP actions registers nothing
-  and is not built by `Http.layer`, nor one without tools by `ActionMcp.layer`.
-- **Names.** Routes and client methods are flat (`POST /api/actions/<action>`,
-  `client.<action>()`), so group names and HTTP action names must be unique within one
-  `ActionHttp.make`, and tool names within one `ActionMcp.layer`. Duplicates throw at
-  construction; neither adapter looks at the other's names.
-- **MCP middleware is per endpoint.** An MCP endpoint is one route, so middleware provided
-  to `ActionMcp.layer`, authentication included, covers all of its tools. Handlers can still
-  authorize each tool differently. Only tools that need different middleware, such as none
-  at all, need their own endpoint: one `ActionMcp.layer` per `path`.
-
-Each group is its own native `HttpApiGroup`, so a host can also combine separately made
-`Http.api` values with `HttpApi.addHttpApi`. See [examples/app.ts](examples/app.ts).
-
-## Serving the document
-
-`Http.api` is a native `HttpApi`, carrying every route, description, declared error and
-policy error. Documents and documentation UIs are therefore Effect's own:
-
-```ts
-import { HttpRouter, HttpServerResponse } from "effect/unstable/http";
-import { HttpApiScalar, HttpApiSwagger, OpenApi } from "effect/unstable/httpapi";
+const greeting = Effect.gen(function* () {
+  const client = yield* HttpApiClient.make(Http.api, { baseUrl });
 
-const documentation = Layer.mergeAll(
-  HttpRouter.add("GET", "/openapi.json", HttpServerResponse.jsonUnsafe(OpenApi.fromApi(Http.api))),
-  HttpApiSwagger.layer(Http.api, { path: "/docs" }),
-  HttpApiScalar.layer(Http.api, { path: "/reference" }),
-);
+  return yield* client.greetings.greet({ payload: { name: "Ada" } });
+});
 ```
 
-Each is an ordinary route layer, so it takes whatever middleware it is provided. The same
-value gives Effect's grouped client: `HttpApiClient.make(Http.api)`.
-
-## Adapter options
-
-| API                                   | Options                                                                  |
-| ------------------------------------- | ------------------------------------------------------------------------ |
-| `ActionGroup.make(options, …actions)` | `name`, `errors`, `schemaError`                                          |
-| `ActionHttp.make(options, …groups)`   | `apiPath`                                                                |
-| `Http.layer(app)`                     | None                                                                     |
-| `Http.client(options?)`               | `baseUrl`, `transformClient`, `transformResponse`                        |
-| `ActionMcp.layer(options, …apps)`     | `name`, `version`, `path`, `protocols`, `allowedOrigins`, `instructions` |
+## Why
 
-`apiPath` and MCP `path` have no defaults. `Http` has three members: `api`, `layer` and
-`client`.
+- Input, success, and errors are declared once. Routes, tools, commands, clients, OpenAPI, and the catalog are derived from that declaration, so they cannot disagree.
+- A handler may fail only with the errors its action declares. Shared failures such as `Forbidden` are declared once on the group.
+- The pieces are Effect's own. `Http.api` is a native `HttpApi`, so `OpenApi.fromApi`, Swagger, Scalar, and `HttpApiClient` work on it unchanged. MCP is Effect's native `McpServer`, one `Tool` per action, with no SDK runtime dependency.
+- Build-time services and per-request services are tracked separately in the types. Middleware is per group, so a public group and an authenticated group can share one mount path.
+- Tests run in memory. Call the routes through a web handler with the same typed client, or drive the official MCP client, without opening a port.
 
-See [adapter behavior](docs/behavior.md) for shared schema-error policies,
-dependency lifetimes, wire formats, and MCP protocol support.
-
-## Scope
-
-HTTP means JSON POST endpoints, not Effect's RPC wire protocol. Both adapters use
-Effect's servers; there is no MCP SDK runtime dependency. Actions are unary:
-no streaming, uploads, prompts, resources, or retries.
-
-Authentication and authorization belong to the application. Tool discovery is
-not filtered by actor. The example's bearer tokens are **demo-only**; production
-needs real token validation, MCP authorization discovery, request limits, and
-error reporting.
-
-## Development and packaging
-
-Requires a supported Node.js version (24 LTS recommended) and [Vite+](https://viteplus.dev).
+## Install
 
 ```sh
-vp install
-vp check
-vp test
-vp run test:package
-vp run example
+pnpm add @gjermundgaraba/effect-actions effect@4.0.0-rc.116
 ```
 
-`vp run dev` watches the library build. `vp check` also verifies the compile-time
-assertions in `tests/types.spec.ts`. Tests cover both transports, official MCP clients,
-context isolation, schema-error policies, and cancellation.
-
-`vp run build` emits ESM and declarations into `dist/`. The entry points are one subpath per
-module: `/Action`, `/ActionGroup`, `/ActionHttp`, `/ActionMcp`, `/Authentication`, `/Testing`,
-and `/TestingClient`. There is no package root, so a contracts-only or browser bundle never
-loads the MCP server or the optional client peer.
-`vp run test:package` builds and checks a tarball in an isolated consumer using the pinned
-Effect snapshot; it does not establish compatibility with the published peer.
+Add `@effect/platform-node@4.0.0-rc.116` to serve from Node. Every module is a subpath import
+(`.../Action`, `.../ActionHttp`, ...); there is no package root, so a contracts-only bundle
+never loads a server.
 
-## Authentication and OAuth discovery
+## Docs
 
-`Authentication.middleware(CurrentActor, { authenticate, errors, headers })` provides
-an application-defined context service for each request. `authenticate` is an Effect;
-`errors` lists its error schemas in precedence order. The first matching schema owns
-both serialization and `httpApiStatus` (500 when unannotated). If its encoder fails,
-the request fails as a server error; another schema is not tried. `headers(error)`
-can add a Bearer challenge.
-Responses use `Cache-Control: no-store`, including failures handled by enclosing middleware. Provide the returned middleware's `.layer` to
-HTTP and MCP route layers. See [examples/app.ts](examples/app.ts).
+The reference in [docs/](docs/README.md) is written for coding agents: one card per module
+with the API, a canonical snippet, the rules, and the failure modes.
 
-Authentication dependencies are request requirements, as with native `HttpRouter.middleware`.
-Use `.combine(...)` with middleware that provides them. Acquired resources stay alive
-until the request scope closes. Downstream action errors are handled by their transport,
-not serialized as authentication failures.
+- [docs/README.md](docs/README.md): start here, includes the adapter decision list.
+- [docs/guarantees.md](docs/guarantees.md): cross-cutting rules for lifetimes, wire formats, and scope.
+- [docs/CONTEXT.md](docs/CONTEXT.md): the vocabulary the docs and the code use.
+- [examples/](examples/README.md): a runnable authenticated application with three groups, two MCP endpoints, OpenAPI, and every other projection.
 
-`Authentication.protectedResource({ resource, authorizationServers, scopesSupported })`
-returns `{ layer, metadataUrl, challenge }`. Mount its public `layer` separately from
-protected routes. It publishes [RFC 9728 metadata](https://www.rfc-editor.org/rfc/rfc9728.html)
-at `/.well-known/oauth-protected-resource` followed by the resource path and query. Discovery
-matches that literal path and query for GET and HEAD; other requests reach the host router.
-Caching policy belongs to the host. `challenge()`
-returns the `WWW-Authenticate` value; pass `{ error: "invalid_token" }` or
-`{ error: "insufficient_scope", scope: "admin" }` where appropriate. Supported scopes
-are advertised in metadata; the challenge names only scopes needed for that request.
-The helper supports HTTPS URLs and loopback HTTP for development, with no credentials
-or fragment. Resource identifiers may include a query; authorization-server issuers may not.
-Your application owns login, consent, and token verification.
+## For agents
 
-```ts
-const discovery = Authentication.protectedResource({
-  resource: "https://api.example.com/mcp",
-  authorizationServers: ["https://auth.example.com"],
-});
-
-const authentication = Authentication.middleware(CurrentActor, {
-  authenticate,
-  errors: [Unauthenticated],
-  headers: () => ({ "www-authenticate": discovery.challenge({ error: "invalid_token" }) }),
-});
-
-const routes = Layer.mergeAll(
-  discovery.layer,
-  protectedRoutes.pipe(Layer.provide(authentication.layer)),
-);
+```sh
+npx skills add gjermundgaraba/effect-actions --skill effect-actions
 ```
 
-## Testing
-
-Import from `@gjermundgaraba/effect-actions/Testing`; it requires no MCP client dependency.
-`withMcpClient` lives in `@gjermundgaraba/effect-actions/TestingClient` and needs the optional
-peer `@modelcontextprotocol/client@^2.0.0`. Only that entry point loads the peer.
+The skill is generated from `docs/`, so pointing an agent at `docs/` (in this repository or
+in `node_modules/@gjermundgaraba/effect-actions/docs`) gives the same content.
 
-```ts
-const web = HttpRouter.toWebHandler(routes.pipe(Layer.provide(HttpServer.layerServices)));
+## Status
 
-const greeting = Effect.gen(function* () {
-  const client = yield* httpClient(Http, web.handler);
+The `effect` peer is pinned to an exact Effect 4 release candidate and moves with it; expect a
+release of this package for each Effect release candidate it adopts. Actions are unary JSON over HTTP and MCP: no streaming, uploads, prompts, or resources.
+Authentication and authorization belong to the application. See [docs/setup.md](docs/setup.md).
 
-  return yield* client.greet({ name: "Ada" });
-});
-```
+## Contributing
 
-- `httpClient(Http, handler, options?)` is the typed HTTP client calling a web handler in
-  memory. `options` are the client's connection options; `baseUrl` defaults to `http://localhost`.
-- `mcpRequest({ url, method, params?, headers? })` builds a stateless 2026-07-28 request.
-  `params` takes whatever `JSON.stringify` accepts, `undefined` fields included, so tests can
-  send malformed arguments.
-  Caller `params._meta` fields override the default client capabilities
-  and information; application metadata is preserved. The protocol version stays pinned to
-  2026-07-28 in both the request header and metadata. Metadata is merged shallowly.
-- `withMcpClient({ fetch, path, mode?, baseUrl?, headers? }, async client => ...)`
-  connects the official client and closes it in a `finally` block.
-  `mode` defaults to `"modern"` (2026-07-28); use `"legacy"` to exercise session negotiation.
+See [CONTRIBUTING.md](CONTRIBUTING.md). MIT licensed.

package/dist/Action.d.mts

@@ -1,2 +1,62 @@
-import { a as Handler, c as SchemaErrorPolicy, i as Codec, l as SchemaFailure, o as McpOptions, r as Any, s as Options, t as Action, u as make } from "./Action-CXsfTEhx.mjs";
-export { Action, Any, Codec, Handler, McpOptions, Options, SchemaErrorPolicy, SchemaFailure, make };
+import { Effect, Schema } from "effect";
+declare namespace Action_d_exports {
+  export { Action, Any, Codec, Handler, McpOptions, Options, make };
+}
+/** Any service-free schema. Only handlers may require services. */
+export type Codec = Schema.Codec<unknown, unknown, never, never>;
+/** MCP tool metadata; every field has a default derived from the action. */
+export interface McpOptions {
+  /** Tool name; defaults to the action name. Must match `^[A-Za-z0-9_-]{1,128}$`. */
+  readonly name?: string;
+  /** `readOnlyHint`; defaults to `false`. */
+  readonly readOnly?: boolean;
+  /** `destructiveHint`; defaults to `!readOnly`, as the MCP spec only defines it for writes. */
+  readonly destructive?: boolean;
+  /** `idempotentHint`; defaults to `false`. */
+  readonly idempotent?: boolean;
+  /** `openWorldHint`; defaults to `true`. */
+  readonly openWorld?: boolean;
+}
+type ResolvedMcp<Name extends string, Mcp extends false | McpOptions | undefined> = Mcp extends false ? false : {
+  readonly name: Mcp extends McpOptions ? "name" extends keyof Mcp ? Extract<Mcp["name"], string> extends never ? Name : Extract<Mcp["name"], string> | (undefined extends Mcp["name"] ? Name : never) : Name : Name;
+  readonly readOnly: boolean;
+  readonly destructive: boolean;
+  readonly idempotent: boolean;
+  readonly openWorld: boolean;
+};
+/** What `make` needs to define an action. */
+export interface Options<Input extends Codec, Output extends Codec, Errors extends ReadonlyArray<Codec>, Http extends boolean = boolean, Mcp extends false | McpOptions | undefined = McpOptions | undefined> {
+  readonly description: string;
+  /** Omit for an action without arguments. */
+  readonly input?: Input;
+  readonly success: Output;
+  /** One schema per declared failure; each keeps its own HTTP status annotation. Defaults to none. */
+  readonly errors?: Errors;
+  /** `false` hides the action from HTTP routes and clients. */
+  readonly http?: Http;
+  /** `false` hides the action from MCP; otherwise tool metadata. */
+  readonly mcp?: Mcp;
+}
+/** A pure contract: schemas and transport metadata. Implementations are bound by `ActionGroup.implement`. */
+export interface Action<Name extends string, Input extends Codec, Output extends Codec, Errors extends ReadonlyArray<Codec>, Http extends boolean = boolean, Mcp extends false | McpOptions | undefined = McpOptions | undefined> {
+  readonly name: Name;
+  readonly description: string;
+  readonly input: Input;
+  readonly success: Output;
+  readonly errors: Errors;
+  readonly http: Http;
+  readonly mcp: ResolvedMcp<Name, Mcp>;
+}
+/** Any action, with its schemas erased. */
+export type Any = Action<string, Codec, Codec, ReadonlyArray<Codec>, boolean, false> | Action<string, Codec, Codec, ReadonlyArray<Codec>, boolean, McpOptions> | Action<string, Codec, Codec, ReadonlyArray<Codec>, boolean, undefined>;
+/** Receives decoded input; may fail only with the declared errors. */
+export type Handler<A extends Any, R = never> = (input: A["input"]["Type"]) => Effect.Effect<A["success"]["Type"], A["errors"][number]["Type"], R>;
+/** An empty object schema that also produces the object root MCP requires. */
+declare const NoInput: Schema.$Record<Schema.String, Schema.Never>;
+/**
+ * Define an action contract. Names are `[A-Za-z0-9_-]+`, other than `then`.
+ * Actions can be local-only by setting both transports to `false`.
+ */
+export declare function make<const Name extends string, Input extends Codec = typeof NoInput, Output extends Codec = never, const Errors extends ReadonlyArray<Codec> = [], const Http extends boolean = true, const Mcp extends false | McpOptions | undefined = undefined>(name: Name, options: Options<Input, Output, Errors, Http, Mcp>): Action<Name, Input, Output, Errors, Http, Mcp>;
+//#endregion
+export { Action_d_exports };

package/dist/Action.mjs

@@ -1,17 +1,20 @@
+import { assertName } from "./internal/actions.mjs";
 import { Schema } from "effect";
 //#region src/Action.ts
 /** An empty object schema that also produces the object root MCP requires. */
 const NoInput = Schema.Record(Schema.String, Schema.Never);
 function make(name, options) {
-	if (!/^[A-Za-z][A-Za-z0-9_-]*$/.test(name)) throw new Error(`Invalid action name: ${name}`);
-	if (options.http === false && options.mcp === false) throw new Error(`Action ${name} is exposed on no transport`);
+	assertName("action name", name);
 	const readOnly = options.mcp === false ? false : options.mcp?.readOnly ?? false;
 	const mcp = options.mcp === false ? false : {
 		name: options.mcp?.name ?? name,
 		readOnly,
-		destructive: options.mcp?.destructive ?? !readOnly
+		destructive: options.mcp?.destructive ?? !readOnly,
+		idempotent: options.mcp?.idempotent ?? false,
+		openWorld: options.mcp?.openWorld ?? true
 	};
-	if (mcp !== false && !/^[A-Za-z0-9_-]{1,128}$/.test(mcp.name)) throw new Error(`Invalid MCP name: ${mcp.name}`);
+	if (mcp !== false && mcp.name.length > 128) throw new Error(`Invalid MCP name: ${mcp.name}`);
+	if (mcp !== false) assertName("MCP name", mcp.name);
 	return {
 		name,
 		description: options.description,

package/dist/ActionCatalog.d.mts

@@ -0,0 +1,31 @@
+import { Action_d_exports, Any } from "./Action.mjs";
+import { ActionGroup_d_exports, Any as Any$1 } from "./ActionGroup.mjs";
+import { JsonSchema } from "effect";
+//#region src/ActionCatalog.d.ts
+/** One contract, with independently rooted JSON schemas for its encoded values. */
+export interface Entry {
+  readonly id: string;
+  readonly group: string;
+  readonly name: string;
+  readonly description: string;
+  readonly http: boolean;
+  readonly mcp: Any["mcp"];
+  readonly input: JsonSchema.JsonSchema;
+  readonly success: JsonSchema.JsonSchema;
+  /** Includes the errors inherited from the group; not HTTP schema-policy errors. */
+  readonly errors: ReadonlyArray<JsonSchema.JsonSchema>;
+  /** HTTP-only decoding/encoding policy errors, separate from handler failures. */
+  readonly httpSchemaErrors: ReadonlyArray<JsonSchema.JsonSchema>;
+}
+/** An offline contract document, not an authorization decision or a mounted endpoint. */
+export interface Catalog {
+  readonly version: "1";
+  readonly actions: ReadonlyArray<Entry>;
+}
+/**
+ * Describe the supplied groups without acquiring implementations. Schemas describe
+ * encoded action values, not MCP's `{ value }` envelope or deployment-specific URLs.
+ * Local-only actions are included; the host chooses what, if anything, to publish.
+ */
+export declare const make: (...groups: ReadonlyArray<Any$1>) => Catalog;
+//#endregion

package/dist/ActionCatalog.mjs

@@ -0,0 +1,36 @@
+import { assertDistinct } from "./internal/actions.mjs";
+import { JsonSchema, Schema } from "effect";
+//#region src/ActionCatalog.ts
+const jsonSchema = (codec) => {
+	const document = Schema.toJsonSchemaDocument(codec);
+	return {
+		$schema: JsonSchema.META_SCHEMA_URI_DRAFT_2020_12,
+		...document.schema,
+		...Object.keys(document.definitions).length === 0 ? {} : { $defs: document.definitions }
+	};
+};
+/**
+* Describe the supplied groups without acquiring implementations. Schemas describe
+* encoded action values, not MCP's `{ value }` envelope or deployment-specific URLs.
+* Local-only actions are included; the host chooses what, if anything, to publish.
+*/
+const make = (...groups) => {
+	assertDistinct("catalog group", groups.map((group) => group.name));
+	return {
+		version: "1",
+		actions: groups.flatMap((group) => group.actions.map((action) => ({
+			id: `${group.name}.${action.name}`,
+			group: group.name,
+			name: action.name,
+			description: action.description,
+			http: action.http,
+			mcp: action.mcp,
+			input: jsonSchema(action.input),
+			success: jsonSchema(action.success),
+			errors: action.errors.map(jsonSchema),
+			httpSchemaErrors: action.http ? group.schemaError?.errors.map(jsonSchema) ?? [] : []
+		})))
+	};
+};
+//#endregion
+export { make };

package/dist/ActionCli.d.mts

@@ -0,0 +1,27 @@
+import { Action_d_exports, Any, Handler } from "./Action.mjs";
+import { Actions } from "./internal/actions.mjs";
+import { HandlerContext, Handlers, HandlersContext, Implementation } from "./internal/implementation.mjs";
+import { Options } from "./internal/cli.mjs";
+import { Scope } from "effect";
+import { Command } from "effect/unstable/cli";
+//#region src/ActionCli.d.ts
+/** Configuration for an aggregate group command. */
+export interface GroupOptions {
+  /** Override the group command name. */
+  readonly name?: string;
+}
+type Selected<G extends Actions, Name extends G["actions"][number]["name"]> = Extract<G["actions"][number], {
+  readonly name: Name;
+}>;
+type BoundHandler<Name extends string, A extends Any, R> = Readonly<Record<Name, Handler<A, R>>>;
+/**
+ * Project one explicitly selected local action into a native Effect CLI command.
+ * The action name resolves against the bound group; no HTTP fallback exists.
+ */
+export declare const command: <G extends Actions, Name extends G["actions"][number]["name"], H extends BoundHandler<Name, Selected<G, Name>, HandlerContext<H, Name>>, EX, RX, Parameters extends Command.Command.Config = never>(app: Implementation<G, H, EX, RX>, name: Name, options?: Options<Selected<G, Name>["success"]["Type"], Parameters>) => Command.Command<string, never, {}, EX | import("effect/Schema").SchemaError | Extract<G["actions"][number], {
+  readonly name: Name;
+}>["errors"][number]["Type"], Exclude<RX, Scope.Scope> | Exclude<HandlerContext<H, Name>, Scope.Scope>>;
+/** Project every local action below its group namespace with default CLI options. */
+export declare const group: <G extends Actions, H extends Handlers<HandlersContext<H>>, EX, RX>(app: Implementation<G, H, EX, RX>, options?: GroupOptions) => Command.Command<string, {}, {}, EX | import("effect/Schema").SchemaError | G["actions"][number]["errors"][number]["Type"], Exclude<Exclude<RX, Scope.Scope>, Command.CommandContext<string>> | Exclude<Exclude<HandlersContext<H>, Scope.Scope>, Command.CommandContext<string>>>;
+//#endregion
+export type { Options };

package/dist/ActionCli.mjs

@@ -0,0 +1,26 @@
+import { dispatch } from "./internal/implementation.mjs";
+import { command as command$1 } from "./internal/cli.mjs";
+import { Effect } from "effect";
+import { Command } from "effect/unstable/cli";
+//#region src/ActionCli.ts
+const select = (group, name) => {
+	const action = group.actions.find((candidate) => candidate.name === name);
+	if (action === void 0) throw new Error(`Unknown action "${group.name}.${name}"`);
+	return action;
+};
+const local = (app, action, input) => Effect.scoped(Effect.flatMap(app.build, (handlers) => dispatch(app.group, action, handlers)(input)));
+/**
+* Project one explicitly selected local action into a native Effect CLI command.
+* The action name resolves against the bound group; no HTTP fallback exists.
+*/
+const command = (app, name, options) => {
+	const action = select(app.group, name);
+	return command$1(action, (input) => local(app, action, input), options);
+};
+/** Project every local action below its group namespace with default CLI options. */
+const group = (app, options) => {
+	const commands = app.group.actions.map((action) => command$1(action, (input) => Effect.scoped(Effect.flatMap(app.build, (handlers) => dispatch(app.group, action, handlers)(input)))));
+	return Command.make(options?.name ?? app.group.name).pipe(Command.withSubcommands(commands));
+};
+//#endregion
+export { command, group };

package/dist/ActionCliClient.d.mts

@@ -0,0 +1,45 @@
+import { Actions } from "./internal/actions.mjs";
+import { Options as Options$1 } from "./internal/cli.mjs";
+import { ActionHttp_d_exports, Api, Http } from "./ActionHttp.mjs";
+import { Effect } from "effect";
+import { HttpApi, HttpApiClient, HttpApiEndpoint, HttpApiGroup } from "effect/unstable/httpapi";
+import { Command } from "effect/unstable/cli";
+import { HttpClient } from "effect/unstable/http";
+//#region src/ActionCliClient.d.ts
+/** Parsing, rendering and native HTTP-endpoint configuration for one remote action. */
+export type Options<Output, ParsedParameters extends Command.Command.Config = never> = Options$1<Output, ParsedParameters> & {
+  /** Passed directly to Effect's native `HttpApiClient.endpoint`. */
+  readonly connection?: NonNullable<globalThis.Parameters<typeof HttpApiClient.make>[1]>;
+};
+/** Configuration for a remote aggregate group command. */
+export interface GroupOptions {
+  /** Override the group command name. */
+  readonly name?: string;
+  /** Shared native HTTP-endpoint configuration for every remote action. */
+  readonly connection?: NonNullable<globalThis.Parameters<typeof HttpApiClient.make>[1]>;
+}
+type Group<Groups extends ReadonlyArray<Actions>, Name extends Groups[number]["name"]> = Extract<Groups[number], {
+  readonly name: Name;
+}>;
+type Selected<G extends Actions, Name extends G["actions"][number]["name"]> = Extract<G["actions"][number], {
+  readonly name: Name;
+}>;
+type HttpNames<G extends Actions> = Extract<G["actions"][number], {
+  readonly http: true;
+}>["name"];
+type ApiGroups<Groups extends ReadonlyArray<Actions>> = Api<Groups[number]> extends HttpApi.HttpApi<"actions", infer ApiGroups> ? ApiGroups : never;
+type Endpoint<Groups extends ReadonlyArray<Actions>, GroupName extends Groups[number]["name"], ActionName extends HttpNames<Group<Groups, GroupName>>> = Extract<HttpApiGroup.EndpointsWithIdentifier<ApiGroups<Groups>, Extract<GroupName, HttpApiGroup.Identifier<ApiGroups<Groups>>>>, {
+  readonly identifier: ActionName;
+}>;
+type NativeMethod<Groups extends ReadonlyArray<Actions>, GroupName extends Groups[number]["name"], ActionName extends HttpNames<Group<Groups, GroupName>>> = HttpApiClient.Client.Method<Extract<Endpoint<Groups, GroupName, ActionName>, HttpApiEndpoint.ConstraintRequest>, never, never>;
+type RemoteCommand<Groups extends ReadonlyArray<Actions>, GroupName extends Groups[number]["name"], ActionName extends HttpNames<Group<Groups, GroupName>>> = Command.Command<string, never, {}, Effect.Error<ReturnType<NativeMethod<Groups, GroupName, ActionName>>>, HttpClient.HttpClient | Effect.Services<ReturnType<NativeMethod<Groups, GroupName, ActionName>>>>;
+type RemoteGroupCommand<Groups extends ReadonlyArray<Actions>, GroupName extends Groups[number]["name"]> = Command.Command<string, {}, {}, Effect.Error<ReturnType<NativeMethod<Groups, GroupName, HttpNames<Group<Groups, GroupName>>>>>, HttpClient.HttpClient | Effect.Services<ReturnType<NativeMethod<Groups, GroupName, HttpNames<Group<Groups, GroupName>>>>>>;
+/**
+ * Project one HTTP action retained by the binding into a native Effect CLI command.
+ * Group and action selectors resolve exclusively from `http.groups`; runtime guards
+ * keep dynamically supplied selector strings from reaching the native client.
+ */
+export declare const command: <const Groups extends ReadonlyArray<Actions>, const GroupName extends Groups[number]["name"], const ActionName extends HttpNames<Group<Groups, GroupName>>, ParsedParameters extends Command.Command.Config = never>(http: Http<Groups>, groupName: GroupName, actionName: ActionName, options?: Options<Selected<Group<Groups, GroupName>, ActionName>["success"]["Type"], ParsedParameters>) => RemoteCommand<Groups, GroupName, ActionName>;
+/** Project all HTTP-enabled actions retained by one group below its group namespace. */
+export declare const group: <const Groups extends ReadonlyArray<Actions>, const GroupName extends Groups[number]["name"]>(http: Http<Groups>, groupName: GroupName, options?: GroupOptions) => RemoteGroupCommand<Groups, GroupName>;
+//#endregion

package/dist/ActionCliClient.mjs

@@ -0,0 +1,52 @@
+import { command as command$1 } from "./internal/cli.mjs";
+import { Effect } from "effect";
+import { HttpApiClient } from "effect/unstable/httpapi";
+import { Command } from "effect/unstable/cli";
+import { HttpClient } from "effect/unstable/http";
+//#region src/ActionCliClient.ts
+/**
+* The native endpoint builder needs string selectors for a runtime-selected route.
+* `http.groups` is checked before this widening, and `NativeMethod` restores the
+* corresponding precise endpoint type at that one dynamic client boundary.
+*/
+const erasedApi = (api) => {
+	return api;
+};
+const selectGroup = (groups, name) => {
+	const group = groups.find((candidate) => candidate.name === name);
+	if (group === void 0) throw new Error(`Unknown HTTP group "${name}"`);
+	return group;
+};
+const selectAction = (group, name) => {
+	const action = group.actions.find((candidate) => candidate.name === name);
+	if (action === void 0 || !action.http) throw new Error(`Unknown HTTP action "${group.name}.${name}"`);
+	return action;
+};
+/**
+* Project one HTTP action retained by the binding into a native Effect CLI command.
+* Group and action selectors resolve exclusively from `http.groups`; runtime guards
+* keep dynamically supplied selector strings from reaching the native client.
+*/
+const command = (http, groupName, actionName, options) => {
+	const group = selectGroup(http.groups, groupName);
+	const action = selectAction(group, actionName);
+	return command$1(action, (input) => Effect.flatMap(HttpClient.HttpClient, (httpClient) => {
+		const endpoint = HttpApiClient.endpoint(erasedApi(http.api), {
+			group: groupName,
+			endpoint: actionName,
+			httpClient,
+			...options?.connection
+		});
+		return Effect.flatMap(endpoint, (method) => {
+			return method({ payload: input });
+		});
+	}), options);
+};
+/** Project all HTTP-enabled actions retained by one group below its group namespace. */
+const group = (http, groupName, options) => {
+	const actions = selectGroup(http.groups, groupName);
+	const commands = actions.actions.flatMap((action) => action.http ? [options?.connection === void 0 ? command(http, groupName, action.name) : command(http, groupName, action.name, { connection: options.connection })] : []);
+	return Command.make(options?.name ?? actions.name).pipe(Command.withSubcommands(commands));
+};
+//#endregion
+export { command, group };