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

package/docs/CONTEXT.md

@@ -0,0 +1,36 @@
+# Context
+
+Vocabulary and seams for `@gjermundgaraba/effect-actions`. The docs, the code, and the tests
+use these words with these meanings.
+
+## Terms
+
+- **Action**: one contract. A name, a description, an input schema, a success schema, declared error schemas, and transport metadata (`http`, `mcp`). Holds no behavior. Made by `Action.make`.
+- **Group**: a named, ordered set of actions plus group-level errors and an optional schema-error policy. Adapters serve groups, clients are organized by group, and the group name is the OpenAPI tag. Made by `ActionGroup.make`.
+- **Contract**: an action or a group. Pure data; safe to import anywhere, including browsers.
+- **Handler**: a function from decoded input to an Effect of decoded success, failing only with the action's declared errors, possibly requiring services.
+- **Implementation**: a nominal binding of a complete handler record to a group, made by `group.implement`. Carries build-time error and requirement channels. Adapters accept implementations; `ActionCatalog` accepts contracts.
+- **Builder**: the record or Effect passed to `implement`. Runs once per adapter layer that serves the implementation.
+- **Build-time requirement**: a service yielded in the builder. Resolved when an adapter layer is built.
+- **Request-time requirement**: a service yielded inside a handler. Supplied per invocation: by router middleware for HTTP-hosted adapters, by the host for Toolkit, CLI, and stdio.
+- **Adapter** (also **projection**): a module that maps implementations or contracts onto one surface: `ActionHttp`, `ActionMcp`, `ActionToolkit`, `ActionCli`, `ActionCliClient`, `ActionCatalog`. Each adapter reads only what it serves and validates only its own namespace.
+- **Binding**: the value an adapter returns before anything runs. `ActionHttp.make` returns the HTTP binding (`groups`, `api`, `layer`); `ActionToolkit.make` returns the Toolkit binding (`toolkit`, `layer`).
+- **Declared error**: an error schema listed on an action or inherited from its group. Handlers may fail with it. Encoded on every transport with its `httpApiStatus`.
+- **Schema-error policy**: a group option mapping Effect's `HttpApiSchemaError` (decode or encode failure) to a declared policy error with a status. HTTP only.
+- **Policy error**: an error a schema-error policy may answer with. Part of the transport contract, never returnable by a handler.
+- **Local-only action**: `http: false` and `mcp: false`. Reachable through `ActionCli` and listed in the catalog.
+- **Tool**: the MCP or Toolkit projection of an MCP-enabled action, named by `mcp.name` and carrying its hints.
+- **Endpoint**: one `ActionMcp.layerHttp` mount. One route, one middleware set, one tool registry.
+- **Document**: the OpenAPI output of `Http.api`, produced by Effect (`OpenApi.fromApi`).
+- **Catalog**: the offline JSON description of groups produced by `ActionCatalog.make`. Descriptive only.
+- **Identity**: the per-request principal, provided by `Authentication.middleware` under an application-owned tag. Never provided at startup.
+
+## Seams
+
+- `src/Action.ts` and `src/ActionGroup.ts` are contracts. They import nothing transport-specific and know nothing about HTTP, MCP, or the CLI.
+- `src/internal/actions.ts` and `src/internal/implementation.ts` hold the shared shapes adapters consume: the contract half of a group, the schema-error policy, and the nominal `Implementation` class. Everything under `src/internal` is not public API; the public modules re-export the types consumers need.
+- Each adapter owns its own mapping from contracts to its surface and never reaches into another adapter. HTTP does not know about tool names; MCP does not know about routes.
+- Adapters build on Effect's own servers and clients: `HttpApi` for HTTP, `McpServer` for MCP, `Toolkit` for the AI toolkit, `Command` for the CLI. The library adds no protocol runtime and defines no application error types.
+- Authentication is router middleware plus discovery metadata. Verification, login, and consent stay in the application.
+- `Testing` depends only on `effect`. `TestingClient` is the single module that loads the optional MCP client peer.
+- Docs: `README.md` is the pitch for humans. `docs/` is the reference for agents, one card per module. `skills/effect-actions` is a copy of `docs/`, with this vocabulary included. `CONTRIBUTING.md` and `AGENTS.md` are for maintainers.

package/docs/README.md

@@ -0,0 +1,85 @@
+# effect-actions reference
+
+Reference for `@gjermundgaraba/effect-actions`, written for coding agents. Every page is a
+card with the same sections: **API** (signatures), **Canonical** (the one right way to write
+it), **Rules** (must and never), **Failure modes** (what you see when it is wrong, and the fix).
+Read the card for a module before writing code that uses it. Vocabulary is defined in
+[CONTEXT.md](CONTEXT.md); the pages use those terms exactly.
+
+Package facts that apply everywhere:
+
+- Every module is a subpath import: `import * as Action from "@gjermundgaraba/effect-actions/Action"`. There is no package root.
+- The `effect` peer is pinned to an exact release candidate (`4.0.0-rc.116`). Install the same version.
+- Contracts are pure values. Nothing runs, binds, or acquires services until an adapter layer is built.
+
+## Pages
+
+| Read                                     | When you need to                                                                       |
+| ---------------------------------------- | -------------------------------------------------------------------------------------- |
+| [setup.md](setup.md)                     | install, pin versions, pick entry points, know what the package does not do            |
+| [Action.md](Action.md)                   | define one contract: input, success, errors, HTTP and MCP flags, tool hints            |
+| [ActionGroup.md](ActionGroup.md)         | group contracts, declare shared errors, set a schema-error policy, bind handlers       |
+| [ActionHttp.md](ActionHttp.md)           | serve JSON POST routes, publish OpenAPI, call the API with `HttpApiClient`             |
+| [ActionMcp.md](ActionMcp.md)             | serve MCP tools over Streamable HTTP or stdio                                          |
+| [ActionToolkit.md](ActionToolkit.md)     | use actions as a native Effect AI `Toolkit` without a server                           |
+| [ActionCli.md](ActionCli.md)             | run handlers in-process from a terminal command                                        |
+| [ActionCliClient.md](ActionCliClient.md) | call the HTTP API from a terminal command                                              |
+| [ActionCatalog.md](ActionCatalog.md)     | export contracts as an offline JSON document                                           |
+| [Authentication.md](Authentication.md)   | provide a per-request identity, publish RFC 9728 discovery, build bearer challenges    |
+| [Testing.md](Testing.md)                 | call routes in memory, build MCP requests, drive the official MCP client               |
+| [guarantees.md](guarantees.md)           | cross-cutting rules: dependency lifetimes, wire formats, spans, request context, scope |
+
+## Choose an adapter
+
+- Callers speak JSON over HTTP: `ActionHttp`. Clients use Effect's `HttpApiClient` on `Http.api`.
+- Callers are MCP clients: `ActionMcp.layerHttp` for a hosted endpoint, `ActionMcp.layerStdio` for a subprocess.
+- Callers are an Effect AI program in the same process: `ActionToolkit`.
+- Callers are humans or scripts in a terminal, handlers run locally: `ActionCli`.
+- Callers are humans or scripts in a terminal, handlers run on a server: `ActionCliClient`.
+- Nothing runs, only the contract is published: `ActionCatalog`.
+
+One implementation (`group.implement(...)`) feeds every adapter.
+
+## Minimal program
+
+```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";
+import * as ActionHttp from "@gjermundgaraba/effect-actions/ActionHttp";
+import * as ActionMcp from "@gjermundgaraba/effect-actions/ActionMcp";
+
+const Greet = Action.make("greet", {
+  description: "Greet someone by name.",
+  input: Schema.Struct({ name: Schema.String }),
+  success: Schema.String,
+  mcp: { readOnly: true },
+});
+
+export const Actions = ActionGroup.make({ name: "greetings" }, Greet);
+
+export const Http = ActionHttp.make({ apiPath: "/api/actions" }, Actions);
+
+const app = Actions.implement({
+  greet: ({ name }) => Effect.succeed(`Hello, ${name}!`),
+});
+
+export const routes = Layer.mergeAll(
+  Http.layer(app),
+  ActionMcp.layerHttp(
+    { protocols: [McpProtocol.v2026_07_28], name: "greetings", version: "1.0.0", path: "/mcp" },
+    app,
+  ),
+);
+```
+
+Serve `routes` with `HttpRouter.serve` and a platform server layer. Result: `POST /api/actions/greetings/greet` and an MCP tool `greet` at `/mcp`.
+
+## Runnable examples
+
+Repository directory `examples/` ([on GitHub](https://github.com/gjermundgaraba/effect-actions/tree/main/examples)):
+
+- `quickstart.ts`, `quickstart-client.ts`: the minimal program and its typed client.
+- `contracts.ts`, `handlers.ts`, `app.ts`, `server.ts`: an authenticated application with three groups, per-group middleware, two MCP endpoints, OpenAPI and Swagger.
+- `toolkit.ts`, `catalog.ts`, `cli.ts`, `cli-client.ts`, `mcp-stdio.ts`: one file per other projection.

package/docs/Testing.md

@@ -0,0 +1,91 @@
+# Testing
+
+In-memory calls against served layers. `Testing` needs no extra dependency. `TestingClient`
+loads the optional `@modelcontextprotocol/client` peer and nothing else does.
+
+## API
+
+```ts
+import * as Testing from "@gjermundgaraba/effect-actions/Testing";
+import * as TestingClient from "@gjermundgaraba/effect-actions/TestingClient";
+
+type Handler = (request: Request) => Promise<Response>; // HttpRouter.toWebHandler(routes).handler
+
+/** Native grouped HttpApiClient calling `handler` in memory. baseUrl defaults to http://localhost. */
+const httpClient: <Api extends HttpApi.HttpApi<any, any>>(
+  api: Api,
+  handler: Handler,
+  options?: Parameters<typeof HttpApiClient.make>[1],
+) => Effect.Effect<HttpApiClient.Client<Api>>;
+
+/** One stateless 2026-07-28 JSON-RPC request with client metadata defaulted. */
+const mcpRequest: (options: McpRequestOptions) => Request;
+
+interface McpRequestOptions {
+  readonly url: string | URL;
+  readonly method: string; // "tools/list", "tools/call", ...
+  readonly params?: McpRequestParams; // anything JSON.stringify accepts, undefined fields included
+  readonly headers?: HeadersInit;
+}
+
+/** Connect the official client, run the callback, always close the transport. */
+const withMcpClient: <A>(
+  options: McpClientOptions,
+  run: (client: Client) => Promise<A>,
+) => Promise<A>;
+
+interface McpClientOptions {
+  readonly fetch: (request: Request) => Promise<Response>; // the web handler
+  readonly path: string;
+  readonly versionNegotiation?: ClientOptions["versionNegotiation"]; // official client default is legacy
+  readonly baseUrl?: string | URL; // http://localhost
+  readonly headers?: HeadersInit;
+}
+```
+
+## Canonical
+
+```ts
+import { Effect, Layer } from "effect";
+import { HttpRouter, HttpServer } from "effect/unstable/http";
+import * as Testing from "@gjermundgaraba/effect-actions/Testing";
+import * as TestingClient from "@gjermundgaraba/effect-actions/TestingClient";
+import { Http, routes } from "./quickstart.js";
+
+const web = HttpRouter.toWebHandler(routes.pipe(Layer.provide(HttpServer.layerServices)));
+// call web.dispose() when the test finishes
+
+// HTTP, typed, in memory.
+const greeting = Effect.gen(function* () {
+  const client = yield* Testing.httpClient(Http.api, web.handler);
+
+  return yield* client.greetings.greet({ payload: { name: "Ada" } });
+});
+
+// MCP, raw request, no handshake (2026-07-28 is stateless).
+const listed = await web.handler(
+  Testing.mcpRequest({ url: "http://localhost/mcp", method: "tools/list" }),
+);
+
+// MCP, official client.
+const result = await TestingClient.withMcpClient(
+  { fetch: web.handler, path: "/mcp", versionNegotiation: { mode: { pin: "2026-07-28" } } },
+  (client) => client.callTool({ name: "greet", arguments: { name: "Ada" } }),
+);
+```
+
+## Rules
+
+- `httpClient` is the same `HttpApiClient` consumers use, with its transport replaced by `handler`. Same `{ payload }` calls, same error channel.
+- `mcpRequest` pins protocol version 2026-07-28 in both the header and `_meta`. Caller `params._meta` fields override the defaulted client capabilities and info; the merge is shallow. Application metadata is preserved.
+- `params` accepts what `JSON.stringify` accepts, so tests can send malformed arguments on purpose. `undefined` fields are dropped.
+- `withMcpClient` closes the transport in a `finally` block. `versionNegotiation` is passed to the official client unchanged; for a stateless endpoint pin `2026-07-28`.
+- Add `Authorization` through `headers` in both MCP helpers, or through `transformClient` in `httpClient` options.
+- Direct handler tests can use `app.build` under `Effect.scoped`, but they bypass decoding, encoding, and middleware. Keep at least one adapter-level test per transport.
+
+## Failure modes
+
+- `@modelcontextprotocol/client` not found: only `TestingClient` needs it. Install the peer in devDependencies, or use `Testing.mcpRequest` instead.
+- Official client fails negotiation against a stateless endpoint: set `versionNegotiation: { mode: { pin: "2026-07-28" } }`.
+- Handler leaks between tests: `web.dispose()` was not called. Register it with the test runner's cleanup hook.
+- 404 from `httpClient`: `routes` did not include `Http.layer(app)`, or `HttpServer.layerServices` was not provided to `toWebHandler`.

package/docs/guarantees.md

@@ -0,0 +1,55 @@
+# Guarantees
+
+Rules that hold across every adapter. Module pages link here rather than repeating them.
+
+## Dependency lifetimes
+
+- Handlers receive decoded input, return decoded results, and may fail only with declared errors. Anything else is a defect.
+- Build-time services are those yielded in the `implement` builder Effect. They resolve once per adapter layer, in that layer's scope. An implementation served by two adapters is built twice. Share state through a Layer provided to the adapters, never through the builder.
+- Request-time services are those yielded inside a handler. For HTTP-hosted adapters (`ActionHttp`, `ActionMcp.layerHttp`) they appear as `HttpRouter.Request.From<"Requires", R>` and are supplied by router middleware, `HttpRouter.provideRequest`, or request context. For `ActionToolkit`, `ActionCli`, and `ActionMcp.layerStdio` the host supplies them at invocation.
+- Use distinct tags for build-time capabilities and request-scoped identity. Never provide an identity or tenant tag in a startup layer or root context. The adapters use native Effect context capture and merging: a startup value under a tag can shadow a request value or satisfy a missing one. Types verify presence, not provenance.
+- Authentication must establish identity on every protected request. Types cannot verify that a handler performed authorization.
+- `ActionCli` acquires the implementation per invocation and releases it after the call. `ActionToolkit.layer` acquires it once for the layer's lifetime.
+
+## Wire behavior
+
+Defaults without a schema-error policy. HTTP is a native `HttpApi`; MCP is a native `McpServer` with one `Tool` per action. The library defines no error types of its own.
+
+| Case                        | HTTP                                                                                                  | MCP                                                                                                    |
+| --------------------------- | ----------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
+| Input                       | decoded with the schema's JSON codec; failure is an empty **400**                                     | decoded with the schema's JSON codec; failure is `InvalidParams`, presented as an `isError` result     |
+| Success                     | the success codec's encoding as the body: `{"id":"1","name":"Ada"}`, `42`                             | `structuredContent: { value: <encoded> }`                                                              |
+| Declared error              | encoded by its schema with its `httpApiStatus` (unannotated: 500): `{"_tag":"UserNotFound","id":"x"}` | `isError: true`; text content is the same JSON; no `structuredContent`                                 |
+| Invalid output encoding     | empty **400** (`HttpApiSchemaError`)                                                                  | `isError: true`, text `Tool execution failed due to an internal server error.`; cause logged, not sent |
+| Defect                      | empty **500**                                                                                         | same generic `isError` result; cause logged, not sent                                                  |
+| Unknown path or method      | 404                                                                                                   | n/a                                                                                                    |
+| Invalid JSON / content type | 400 / 415                                                                                             | n/a                                                                                                    |
+
+- A group `schemaError` policy replaces the empty 400s on HTTP with a declared error and status. It never affects MCP. Details in [ActionGroup.md](ActionGroup.md).
+- Routes are `POST <apiPath>/<group>/<action>`. Operation IDs are `<group>.<action>`. Effect generates OpenAPI component names and references.
+- Object schemas strip excess fields unless configured to reject them.
+
+## Namespaces
+
+- Group names are unique within one `ActionHttp.make`. Action names are unique within a group. MCP tool names are unique within a group and within each Toolkit or MCP projection that serves it.
+- Adapters validate only the namespace they serve. HTTP does not check tool names; MCP does not check route names.
+- Each adapter builds only what it serves. A group with no HTTP actions is not built by `Http.layer`; a group with no tools is not built by MCP or Toolkit.
+
+## Observability
+
+- Each handler runs in a span named `<group>.<action>`, a child of the transport's request span. Decoding and encoding happen outside the handler span.
+- MCP defects and encoding failures are logged with their cause and answered generically.
+
+## MCP transport
+
+- `protocols` is required. Effect owns negotiation, revision rejection, and session lifecycle; the adapter forwards the selection unchanged. `[McpProtocol.v2026_07_28]` is a stateless endpoint.
+- `layerHttp` is single-endpoint Streamable HTTP, never two-endpoint HTTP+SSE, whatever revision is selected.
+- Cancellation is Effect's native RPC interruption.
+- Each endpoint or subprocess owns a fresh native tool registry. That isolates names, not application context.
+
+## Scope
+
+- HTTP is JSON `POST` on `HttpApi`, not Effect RPC. MCP is native `McpServer`, no SDK runtime dependency.
+- Actions are unary: no streaming, uploads, prompts, resources, retries, or code-execution sandbox.
+- Authentication and authorization are the application's. Tool discovery is not filtered by actor. Production needs real token validation, MCP authorization discovery, request limits, and error reporting; the package supplies shapes for the first two only.
+- The catalog is descriptive. Presence in it grants nothing.

package/docs/setup.md

@@ -0,0 +1,63 @@
+# Setup
+
+Install, version pins, entry points, and the boundaries of the package.
+
+## Install
+
+```sh
+pnpm add @gjermundgaraba/effect-actions effect@4.0.0-rc.116
+```
+
+| Need                           | Add                                                   |
+| ------------------------------ | ----------------------------------------------------- |
+| Node HTTP server or stdio host | `@effect/platform-node@4.0.0-rc.116`                  |
+| `TestingClient.withMcpClient`  | `@modelcontextprotocol/client@^2.0.0` (optional peer) |
+
+Node `^22.12.0 || ^24.0.0 || >=26.0.0`. ESM only.
+
+## Entry points
+
+There is no package root. Import one module per subpath, as a namespace:
+
+```ts
+import * as Action from "@gjermundgaraba/effect-actions/Action";
+import * as ActionGroup from "@gjermundgaraba/effect-actions/ActionGroup";
+import * as ActionHttp from "@gjermundgaraba/effect-actions/ActionHttp";
+import * as ActionMcp from "@gjermundgaraba/effect-actions/ActionMcp";
+import * as ActionToolkit from "@gjermundgaraba/effect-actions/ActionToolkit";
+import * as ActionCatalog from "@gjermundgaraba/effect-actions/ActionCatalog";
+import * as ActionCli from "@gjermundgaraba/effect-actions/ActionCli";
+import * as ActionCliClient from "@gjermundgaraba/effect-actions/ActionCliClient";
+import * as Authentication from "@gjermundgaraba/effect-actions/Authentication";
+import * as Testing from "@gjermundgaraba/effect-actions/Testing";
+import * as TestingClient from "@gjermundgaraba/effect-actions/TestingClient";
+```
+
+Every module imports from the `effect` package only, with two exceptions worth knowing when
+bundling: `ActionMcp` and `ActionToolkit` are the only modules that import `effect/unstable/ai`,
+and `TestingClient` is the only module that imports the optional `@modelcontextprotocol/client`
+peer. Because there is no package root, importing a contract module never pulls in an MCP
+server or the peer.
+
+Companion Effect modules you will import alongside: `effect/unstable/httpapi` (`HttpApiClient`, `OpenApi`, `HttpApiSwagger`, `HttpApiScalar`), `effect/unstable/http` (`HttpRouter`, `HttpServerResponse`, `FetchHttpClient`), `effect/unstable/ai` (`McpProtocol`), `effect/unstable/cli` (`Command`, `Flag`, `Argument`).
+
+## Rules
+
+- Pin `effect` to the exact release candidate the package declares as peer. Mixed rc versions fail at the type level in ways that look like library bugs.
+- Never import from `dist/` paths or from a package root. Only the subpaths above are public.
+- Schemas passed to `Action.make` must be service-free (`Schema.Codec<_, _, never, never>`). Handlers may require services.
+
+## Scope
+
+What the package does, and nothing else:
+
+- HTTP means JSON `POST` endpoints built on Effect's `HttpApi`. It is not Effect RPC.
+- MCP means one native `McpServer` `Tool` per action. There is no MCP SDK runtime dependency.
+- Actions are unary: one decoded input, one decoded success or one declared error. No streaming, uploads, prompts, resources, retries, or code-execution sandbox.
+- Authentication and authorization are the application's. The library provides a middleware shape and discovery metadata, not a token verifier. Tool discovery is never filtered by actor.
+
+## Failure modes
+
+- `Cannot find module '@gjermundgaraba/effect-actions'`: there is no root export. Import a subpath.
+- Type errors inside `effect/unstable/*` after install: `effect` version drift. Align to the peer pin.
+- `@modelcontextprotocol/client` resolution errors in a server build: something imported `TestingClient`. Only tests should.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gjermundgaraba/effect-actions",
-  "version": "0.1.0-rc.2",
+  "version": "0.1.0",
   "description": "Define Effect action contracts once and project them onto HTTP, MCP, native Toolkits, catalogs, and CLIs.",
   "homepage": "https://github.com/gjermundgaraba/effect-actions#readme",
   "bugs": {
@@ -12,7 +12,8 @@
     "url": "git+https://github.com/gjermundgaraba/effect-actions.git"
   },
   "files": [
-    "dist"
+    "dist",
+    "docs"
   ],
   "type": "module",
   "exports": {
@@ -30,18 +31,17 @@
     "./package.json": "./package.json"
   },
   "publishConfig": {
-    "access": "public",
-    "tag": "rc"
+    "access": "public"
   },
   "devDependencies": {
     "@effect/platform-node": "4.0.0-rc.116",
     "@modelcontextprotocol/client": "2.0.0",
-    "@types/node": "26.5.1",
+    "@types/node": "26.6.2",
     "effect": "4.0.0-rc.116",
-    "tsx": "4.23.13",
+    "tsx": "4.23.15",
     "typescript": "7.0.2",
-    "vite": "npm:@voidzero-dev/vite-plus-core@0.3.2",
-    "vite-plus": "0.3.2"
+    "vite": "npm:@voidzero-dev/vite-plus-core@0.3.3",
+    "vite-plus": "0.3.3"
   },
   "peerDependencies": {
     "@modelcontextprotocol/client": "^2.0.0",
@@ -55,7 +55,7 @@
   "devEngines": {
     "packageManager": {
       "name": "pnpm",
-      "version": "12.4.1",
+      "version": "12.5.1",
       "onFail": "download"
     }
   },
@@ -68,6 +68,7 @@
     "test": "vp test",
     "check": "vp check",
     "example": "node --import tsx examples/server.ts",
-    "test:package": "vp run build && node scripts/test-package.mjs"
+    "test:package": "vp run build && node scripts/test-package.mjs",
+    "docs:sync": "node --import tsx scripts/sync-skill.ts"
   }
 }