@gjermundgaraba/effect-actions 0.11.0 → 0.13.0

package/examples/notes-service/src/commands.ts

@@ -0,0 +1,137 @@
+import { Config, Console, Effect, FileSystem, flow } from "effect";
+import { Argument, CliError, Command } from "effect/cli";
+import { HttpClient, HttpClientRequest } from "effect/http";
+import * as ActionCli from "@gjermundgaraba/effect-actions/ActionCli";
+import * as ActionHttp from "@gjermundgaraba/effect-actions/ActionHttp";
+import { Http } from "./Api.js";
+
+// The file's format: each note a `# ` title line, a blank line and its body, the notes apart by
+// a blank line. A body line that starts as a title would is written with a backslash before it,
+// as Markdown escapes one, and `import` takes it off, so every note reads back as it was.
+const escape = (body: string) => body.replaceAll(/^(?=\\*# )/gmu, "\\");
+
+const unescape = (body: string) => body.replaceAll(/^\\(?=\\*# )/gmu, "");
+
+// A command of your own, for what no single action does: this one calls two and writes a file.
+// It is a native Effect CLI command, so its syntax and its output are what you write: `notes
+// export notes.md` takes its argument from `Argument`, as a flag would come from `Flag`. It
+// calls the server through the binding's typed client, on the `HttpClient` the derived commands
+// use, and writes with the `FileSystem` every Effect CLI command has.
+const exportNotes = Command.make(
+  "export",
+  { file: Argument.String("file").pipe(Argument.withDescription("The Markdown file to write.")) },
+  ({ file }) =>
+    Effect.gen(function* () {
+      const client = yield* ActionHttp.client(Http);
+      const files = yield* FileSystem.FileSystem;
+      const { notes } = yield* client.listNotes();
+      const whole = yield* Effect.forEach(notes, ({ id }) => client.getNote({ id }));
+
+      yield* files.writeFileString(
+        file,
+        whole.map((note) => `# ${note.title}\n\n${escape(note.body)}`).join("\n\n"),
+      );
+
+      yield* Console.log(`Wrote ${whole.length} notes to ${file}`);
+    }).pipe(
+      // Context of your own for a failure goes to stderr before it, on a line of its own. A
+      // `UserError` wrapped around the failure instead would put its JSON mid-sentence. The
+      // line prints for every failure of the command, a file that cannot be written included,
+      // so it says only what is true of them all.
+      Effect.tapError(() => Console.error(`The export to ${file} did not finish.`)),
+      // Once, around the whole command: it then fails as a derived command does, an action's
+      // error printed as its JSON on stderr and any other, a file that cannot be written for
+      // one, named. A failure left as it is would be reported as a crash, with an `ERROR (#n)`
+      // line and a stack trace.
+      ActionCli.toUserError(Http),
+    ),
+).pipe(Command.withDescription("Write every note to a file, as Markdown."));
+
+// The other half of `export`: it reads such a file and creates its notes with one call of the
+// bulk action, so the server checks every note before it writes any, and a file of more than
+// the action's 100 is refused whole. The command reads the file and nothing more.
+// `Argument.FileText` reads it, and a missing file is a usage error naming it, where
+// `Argument.String` and `FileSystem` would print the platform's error. Text before the first
+// title is refused, not dropped: the file is not one `export` wrote. The derived `import-notes`
+// stays beside it, taking the notes as a JSON array in `--notes`.
+const importNotes = Command.make(
+  "import",
+  {
+    text: Argument.FileText("file").pipe(
+      Argument.withDescription("A Markdown file as `notes export` writes it."),
+    ),
+  },
+  ({ text }) =>
+    Effect.gen(function* () {
+      const client = yield* ActionHttp.client(Http);
+
+      if (text === "") return yield* Console.log("Created 0 notes");
+
+      if (!text.startsWith("# ")) {
+        return yield* new CliError.UserError({
+          cause: text.split("\n", 1)[0],
+          userMessage: "The file does not start with a `# ` title, as `notes export` writes one.",
+        });
+      }
+
+      const notes = text.split(/\n\n(?=# )/u).map((note) => {
+        const [title = "", ...body] = note.slice(2).split("\n\n");
+
+        return { title, body: unescape(body.join("\n\n")) };
+      });
+
+      const { notes: created } = yield* client.importNotes({ notes });
+
+      yield* Console.log(`Created ${created.length} notes`);
+    }).pipe(ActionCli.toUserError(Http)),
+).pipe(
+  Command.withDescription("Create the notes of a file `export` wrote, all or none, at most 100."),
+);
+
+// A command per action of the binding, a flag per input field, each calling the server over
+// HTTP. It imports the binding alone, never a handler. It is apart from cli.ts so a test runs
+// it: test/commands.test.ts.
+export const commands = ActionCli.remote(Http, {
+  name: "notes",
+  commands: {
+    // `notes create-note --title Draft < draft.md`: the body is piped in, not a flag.
+    createNote: { stdin: "body" },
+    getNote: { positional: ["id"], render: (note) => `# ${note.title}\n\n${note.body}` },
+    // `notes update-note <id> --revision 1 < draft.md`: an argument, a flag and stdin together.
+    updateNote: { positional: ["id"], stdin: "body" },
+  },
+  // `Command.withSubcommands` on the result would replace the derived commands, so your own
+  // go here.
+  subcommands: [exportNotes, importNotes],
+});
+
+// Where the server is and who is calling, read from config: the `HttpClient` every command
+// above calls with. It is an Effect, not a value, so that cli.ts provides it on the commands
+// and it runs when one of them does.
+export const connection = Effect.gen(function* () {
+  const url = yield* Config.String("NOTES_URL").pipe(Config.withDefault("http://127.0.0.1:3000"));
+
+  // Required, since every command but `get-status` is refused without one. A failure of what a
+  // command is provided is no action's error: left as it is, a missing token is reported as a
+  // crash, the log line `ERROR (#n): ConfigError: SchemaError(Expected string at
+  // ["NOTES_TOKEN"])`. Mapped to a `UserError`, it is printed as any failure of a command is:
+  // the message under an `ERROR` heading on stderr, and exit 1. `userMessage` is all that is
+  // printed, never `cause`: what the user needs from the cause goes into the message. A CLI
+  // whose public commands must answer signed out reads the token with `Config.option` instead
+  // and adds the header when it is there.
+  const token = yield* Config.Redacted("NOTES_TOKEN").pipe(
+    Effect.mapError(
+      (cause) =>
+        new CliError.UserError({
+          cause,
+          userMessage:
+            "NOTES_TOKEN is not set. Set it to your token: export NOTES_TOKEN=<your token>",
+        }),
+    ),
+  );
+
+  return HttpClient.mapRequest(
+    yield* HttpClient.HttpClient,
+    flow(HttpClientRequest.prependUrl(url), HttpClientRequest.bearerToken(token)),
+  );
+});

package/examples/notes-service/src/identity/Identity.ts

@@ -0,0 +1,31 @@
+import { Context, Schema } from "effect";
+import * as Action from "@gjermundgaraba/effect-actions/Action";
+import * as Authentication from "@gjermundgaraba/effect-actions/Authentication";
+
+export const scopes = { read: "notes:read", write: "notes:write" } as const;
+
+export const Scope = Schema.Literals([scopes.read, scopes.write]);
+
+export interface User {
+  readonly id: string;
+  readonly scopes: ReadonlyArray<typeof Scope.Type>;
+}
+
+/**
+ * Who is calling. A protected action declares it, `caller: CurrentUser`; authentication
+ * provides it per request, and a local host, such as the stdio server, provides it itself.
+ */
+export class CurrentUser extends Context.Service<CurrentUser, User>()(
+  "notes-service/CurrentUser",
+) {}
+
+// How a remote caller proves it is CurrentUser: a bearer token, the default scheme. Clients
+// import this descriptor with the binding; its verifier, in verifier.ts, stays on the server.
+export const Login = Authentication.make("notes-service.Login", CurrentUser);
+
+export const WhoAmI = Action.make("whoAmI", {
+  description: "Show who the credential identifies and which scopes it holds.",
+  success: { id: Schema.String, scopes: Schema.Array(Scope) },
+  readOnly: true,
+  caller: CurrentUser,
+});

package/examples/notes-service/src/identity/authorize.ts

@@ -0,0 +1,18 @@
+import { Effect } from "effect";
+import * as Action from "@gjermundgaraba/effect-actions/Action";
+import { CurrentUser, scopes } from "./Identity.js";
+
+// The one rule, read from each contract: a read needs the read scope, anything else the write
+// scope. Every implementation of protected actions states it, so HTTP, MCP and stdio all run it
+// before the handler. Naming the missing scope lets an OAuth client ask for it and retry: it is
+// answered a challenge, which only a server publishing discovery (verifier.ts) can follow up.
+// Where tokens are fixed, such as API keys, name no scope: the refusal is then a plain one.
+// So `scopes` below goes when `protectedResource` in verifier.ts does: copy both or neither.
+export const authorize = Effect.fn("authorize")(function* (action: Action.Any) {
+  const scope = action.readOnly ? scopes.read : scopes.write;
+  const user = yield* CurrentUser;
+
+  if (!user.scopes.includes(scope)) {
+    return yield* new Action.Forbidden({ message: `Requires ${scope}.`, scopes: [scope] });
+  }
+});

package/examples/notes-service/src/identity/handlers.ts

@@ -0,0 +1,10 @@
+import { Effect } from "effect";
+import * as Action from "@gjermundgaraba/effect-actions/Action";
+import { authorize } from "./authorize.js";
+import { CurrentUser, WhoAmI } from "./Identity.js";
+
+export const identity = Action.implement(
+  WhoAmI,
+  () => Effect.map(CurrentUser, ({ id, scopes }) => ({ id, scopes })),
+  { authorize },
+);

package/examples/notes-service/src/identity/users.ts

@@ -0,0 +1,9 @@
+import { scopes, type User } from "./Identity.js";
+
+// DEMO ONLY: the people who may sign in, each under a token that is their name. A real service
+// has no such table: its verifier reads the user from a signed token.
+export const users = {
+  ada: { id: "ada", scopes: [scopes.read, scopes.write] },
+  grace: { id: "grace", scopes: [scopes.read, scopes.write] },
+  reader: { id: "reader", scopes: [scopes.read] },
+} as const satisfies Readonly<Record<string, User>>;

package/examples/notes-service/src/identity/verifier.ts

@@ -0,0 +1,36 @@
+import { Config, Effect, Redacted } from "effect";
+import * as Action from "@gjermundgaraba/effect-actions/Action";
+import * as Authentication from "@gjermundgaraba/effect-actions/Authentication";
+import { Login, scopes } from "./Identity.js";
+import { users } from "./users.js";
+
+const isToken = (token: string): token is keyof typeof users => Object.hasOwn(users, token);
+
+// DEMO ONLY: a token is a user's name. A real verifier checks a signed token with your
+// authorization server's library, its audience included. An unknown token is the built-in
+// `Unauthenticated`: a 401 every client decodes.
+const verify = (token: Redacted.Redacted<string>) => {
+  const name = Redacted.value(token);
+
+  return isToken(name)
+    ? Effect.succeed(users[name])
+    : Effect.fail(new Action.Unauthenticated({ message: "Unknown demo token." }));
+};
+
+// Server only: `Login`'s provider. Every layer serving a protected action requires it and
+// authenticates before it decodes the input. As an OAuth protected resource it also publishes
+// discovery, so an MCP client that gets a 401 finds where to sign in, asking for read first.
+// The resource is the server's public URL, known only at startup, so it is read from config.
+export const authenticate = Authentication.layer(Login, verify, {
+  protectedResource: Effect.map(
+    Config.String("PUBLIC_URL").pipe(Config.withDefault("http://localhost:3000")),
+    (url) =>
+      ({
+        resource: `${url}/mcp`,
+        // DEMO ONLY: no server is there. Yours is your authorization server's issuer.
+        authorizationServers: ["https://auth.example.com"],
+        scopesSupported: [scopes.read, scopes.write],
+        scopesRequired: [scopes.read],
+      }) satisfies Authentication.ProtectedResource,
+  ),
+});

package/examples/notes-service/src/notes/Notes.ts

@@ -0,0 +1,119 @@
+import { Schema } from "effect";
+import * as Action from "@gjermundgaraba/effect-actions/Action";
+import { CurrentUser } from "../identity/Identity.js";
+
+export const Note = Schema.Struct({
+  id: Schema.String,
+  title: Schema.String,
+  body: Schema.String,
+  revision: Schema.Finite,
+});
+
+export type Note = typeof Note.Type;
+
+// A declared error is part of the contract: every client decodes it as this class, and its
+// status is what HTTP answers with.
+export class NoteNotFound extends Schema.TaggedError<NoteNotFound>()(
+  "NoteNotFound",
+  { id: Schema.String },
+  { httpApiStatus: 404 },
+) {}
+
+export class NoteChanged extends Schema.TaggedError<NoteChanged>()(
+  "NoteChanged",
+  { id: Schema.String, revision: Schema.Finite },
+  { httpApiStatus: 409 },
+) {}
+
+// A description on an input field is that field's help on every surface: beside its flag or
+// argument in a command's `--help`, and in the input schema a model reads from the MCP tool
+// listing and the OpenAPI document. A field without one has a flag with no help.
+const Id = Schema.String.annotate({
+  description: "The note's id, as the list of your notes shows it.",
+});
+
+// A check's `message` is what a caller reads when the value fails it, in place of the
+// generic "Expected a value with a length of at least 1". A model and a CLI user read it too.
+const Title = Schema.String.check(
+  Schema.isMinLength(1, { message: "A note needs a title." }),
+  Schema.isPattern(/^[^\r\n\u2028\u2029]*$/u, { message: "A title is one line." }),
+).annotate({
+  description: "A short name for the note: one line, at least one character.",
+});
+
+const Body = Schema.String.annotate({ description: "The note's whole text." });
+
+export const ListNotes = Action.make("listNotes", {
+  description: "List your notes, without their bodies.",
+  success: { notes: Schema.Array(Schema.Struct({ id: Schema.String, title: Schema.String })) },
+  readOnly: true,
+  caller: CurrentUser,
+});
+
+export const GetNote = Action.make("getNote", {
+  description: "Read one of your notes.",
+  input: { id: Id },
+  success: Note,
+  error: NoteNotFound,
+  readOnly: true,
+  caller: CurrentUser,
+});
+
+export const CreateNote = Action.make("createNote", {
+  description: "Create a note.",
+  input: { title: Title, body: Body },
+  success: Note,
+  readOnly: false,
+  caller: CurrentUser,
+  mcp: { destructiveHint: false },
+});
+
+export const UpdateNote = Action.make("updateNote", {
+  description:
+    "Replace a note's body. Pass the revision you read: the update is refused if the note changed since.",
+  input: {
+    id: Id,
+    body: Body.annotate({ description: "The text that replaces the note's body." }),
+    revision: Schema.Finite.annotate({
+      description: "The revision you read: 1 for a new note, one more after each update.",
+    }),
+  },
+  success: Note,
+  error: [NoteNotFound, NoteChanged],
+  readOnly: false,
+  caller: CurrentUser,
+  // No `destructiveHint`: an update replaces the body, so it is destructive, MCP's default for
+  // a write. `createNote` and `importNotes`, which only add, say `false`.
+});
+
+export const DeleteNote = Action.make("deleteNote", {
+  description: "Delete a note for good.",
+  input: { id: Id },
+  error: NoteNotFound,
+  readOnly: false,
+  caller: CurrentUser,
+});
+
+// Work every surface should offer is an action, a bulk import included: the HTTP API, the MCP
+// tools and the CLI then all have it, and the whole list is decoded, so checked, before the
+// handler writes any of it. A command of your own only reads the file and calls this once
+// (commands.ts). `importNotes` adds and removes nothing, so `destructiveHint` is `false`.
+export const ImportNotes = Action.make("importNotes", {
+  description:
+    "Create several notes at once, such as those `notes export` wrote. Every note is checked " +
+    "before any is written: an import holding one that is not valid writes none.",
+  input: {
+    notes: Schema.Array(Schema.Struct({ title: Title, body: Body }))
+      .check(
+        Schema.isMinLength(1, { message: "An import holds at least one note." }),
+        Schema.isMaxLength(100, { message: "An import holds at most 100 notes." }),
+      )
+      .annotate({ description: "The notes to create, in order: from 1 to 100." }),
+  },
+  success: { notes: Schema.Array(Note) },
+  readOnly: false,
+  caller: CurrentUser,
+  mcp: { destructiveHint: false },
+});
+
+export const Notes = [ListNotes, GetNote, CreateNote, UpdateNote, DeleteNote, ImportNotes] as const;

package/examples/notes-service/src/notes/handlers.ts

@@ -0,0 +1,39 @@
+import { Effect } from "effect";
+import * as Action from "@gjermundgaraba/effect-actions/Action";
+import { authorize } from "../identity/authorize.js";
+import { CurrentUser } from "../identity/Identity.js";
+import { Notes } from "./Notes.js";
+import { NoteStore } from "./store.js";
+
+// The builder runs once, at startup, however many surfaces serve these actions: it is where a
+// handler gets the services that last the process, never the caller. `CurrentUser` is read per
+// call, inside each handler. Each handler is a thin step from the contract to the store, and
+// none checks a scope: `authorize` has run before it.
+export const notes = Action.implement(
+  Notes,
+  Effect.gen(function* () {
+    const store = yield* NoteStore;
+
+    return {
+      listNotes: () =>
+        Effect.gen(function* () {
+          const user = yield* CurrentUser;
+          const owned = yield* store.list(user.id);
+
+          return { notes: owned.map(({ id, title }) => ({ id, title })) };
+        }),
+      getNote: ({ id }) => Effect.flatMap(CurrentUser, (user) => store.get(user.id, id)),
+      createNote: ({ title, body }) =>
+        Effect.flatMap(CurrentUser, (user) => store.create(user.id, title, body)),
+      updateNote: ({ id, body, revision }) =>
+        Effect.flatMap(CurrentUser, (user) => store.update(user.id, id, body, revision)),
+      deleteNote: ({ id }) => Effect.flatMap(CurrentUser, (user) => store.remove(user.id, id)),
+      importNotes: ({ notes }) =>
+        Effect.map(
+          Effect.flatMap(CurrentUser, (user) => store.createAll(user.id, notes)),
+          (created) => ({ notes: created }),
+        ),
+    };
+  }),
+  { authorize },
+);

package/examples/notes-service/src/notes/store.ts

@@ -0,0 +1,84 @@
+import { Context, Effect, Layer } from "effect";
+import { type Note, NoteChanged, NoteNotFound } from "./Notes.js";
+
+/**
+ * Where notes live, each owned by one user. Ownership is checked here, in the data access, so no
+ * surface and no handler can skip it.
+ */
+export class NoteStore extends Context.Service<
+  NoteStore,
+  {
+    readonly list: (owner: string) => Effect.Effect<ReadonlyArray<Note>>;
+    readonly get: (owner: string, id: string) => Effect.Effect<Note, NoteNotFound>;
+    readonly create: (owner: string, title: string, body: string) => Effect.Effect<Note>;
+    /** Every note or none: a database does this in one transaction. */
+    readonly createAll: (
+      owner: string,
+      notes: ReadonlyArray<{ readonly title: string; readonly body: string }>,
+    ) => Effect.Effect<ReadonlyArray<Note>>;
+    readonly update: (
+      owner: string,
+      id: string,
+      body: string,
+      revision: number,
+    ) => Effect.Effect<Note, NoteNotFound | NoteChanged>;
+    readonly remove: (owner: string, id: string) => Effect.Effect<void, NoteNotFound>;
+    readonly count: Effect.Effect<number>;
+  }
+>()("notes-service/NoteStore") {
+  // DEMO ONLY: memory, lost when the process stops. A real store is another Layer of this
+  // service, chosen by the entrypoint.
+  static readonly layerMemory = Layer.sync(NoteStore, () => {
+    // One map per owner: a note is only ever looked up among its owner's, whatever id is asked.
+    const notes = new Map<string, Map<string, Note>>();
+
+    const ownedBy = (owner: string) => notes.get(owner) ?? new Map<string, Note>();
+
+    const save = (owner: string, note: Note) => {
+      notes.set(owner, ownedBy(owner).set(note.id, note));
+
+      return note;
+    };
+
+    const get = Effect.fn("NoteStore.get")(function* (owner: string, id: string) {
+      const note = ownedBy(owner).get(id);
+
+      if (note === undefined) return yield* new NoteNotFound({ id });
+
+      return note;
+    });
+
+    return NoteStore.of({
+      list: (owner) => Effect.sync(() => Array.from(ownedBy(owner).values())),
+      get,
+      create: (owner, title, body) =>
+        Effect.sync(() => save(owner, { id: crypto.randomUUID(), title, body, revision: 1 })),
+      createAll: (owner, all) =>
+        Effect.sync(() =>
+          all.map(({ title, body }) =>
+            save(owner, { id: crypto.randomUUID(), title, body, revision: 1 }),
+          ),
+        ),
+      // No `yield*` between the read and the write: a fiber may be set aside at one, and two
+      // updates that each read revision 1 before either wrote would both succeed. A database
+      // does this with a conditional update or a transaction.
+      update: Effect.fn("NoteStore.update")(function* (owner, id, body, revision) {
+        const current = ownedBy(owner).get(id);
+
+        if (current === undefined) return yield* new NoteNotFound({ id });
+
+        if (current.revision !== revision) {
+          return yield* new NoteChanged({ id, revision: current.revision });
+        }
+
+        return save(owner, { ...current, body, revision: revision + 1 });
+      }),
+      remove: Effect.fn("NoteStore.remove")(function* (owner, id) {
+        if (!ownedBy(owner).delete(id)) return yield* new NoteNotFound({ id });
+      }),
+      count: Effect.sync(() =>
+        Array.from(notes.values()).reduce((total, owned) => total + owned.size, 0),
+      ),
+    });
+  });
+}

package/examples/notes-service/src/routes.ts

@@ -0,0 +1,45 @@
+import { Layer } from "effect";
+import { HttpRouter, HttpServerResponse } from "effect/http";
+import { OpenApi } from "effect/http-api";
+import * as ActionHttp from "@gjermundgaraba/effect-actions/ActionHttp";
+import * as ActionMcp from "@gjermundgaraba/effect-actions/ActionMcp";
+import { Http } from "./Api.js";
+import { identity } from "./identity/handlers.js";
+import { Login } from "./identity/Identity.js";
+import { authenticate } from "./identity/verifier.js";
+import { notes } from "./notes/handlers.js";
+import { status } from "./status/handlers.js";
+
+// Every domain's implementation, once. Each surface below takes the same list.
+const implementations = [status, notes, identity];
+
+// JSON routes at `/api/<action>`, the binding's. A protected route authenticates before it
+// reads its body; `getStatus` answers anyone.
+const api = ActionHttp.layer(Http, implementations);
+
+// The same actions as MCP tools at `/mcp`. Listing the tools and calling `getStatus` need no
+// token, because `getStatus` is public: an endpoint of protected tools alone asks a token for
+// the listing too. Any other call answers 401 with where to sign in, and so does a client of
+// an MCP revision with sessions when it opens one, since a session may call any tool.
+const mcp = ActionMcp.layerHttp(implementations, {
+  name: "notes-service",
+  version: "1.0.0",
+  instructions: "Notes belong to the signed-in user. Read a note before updating it.",
+  authentication: Login,
+});
+
+// The host's own routes sit beside the actions' on the same router.
+const health = HttpRouter.add("GET", "/healthz", HttpServerResponse.text("ok"));
+
+// Served to anyone, which is a choice: it tells a signed-out caller every action's name and
+// shape. To keep them, leave the route out, or provide `Authentication.protect(Login).layer`
+// to it.
+const openApi = HttpRouter.add(
+  "GET",
+  "/api/openapi.json",
+  HttpServerResponse.jsonUnsafe(OpenApi.fromApi(Http.api)),
+);
+
+// What the host serves. It still requires `NoteStore`: the entrypoint chooses which one, and a
+// test chooses its own.
+export const routes = Layer.mergeAll(api, mcp, health, openApi).pipe(Layer.provide(authenticate));

package/examples/notes-service/src/server.ts

@@ -0,0 +1,26 @@
+import { createServer } from "node:http";
+import { NodeHttpServer, NodeRuntime } from "@effect/platform-node";
+import { ByteSize, Config, Effect, Layer } from "effect";
+import { HttpRouter, HttpServerRequest } from "effect/http";
+import { NoteStore } from "./notes/store.js";
+import { routes } from "./routes.js";
+
+// Entrypoint: `node --import tsx examples/notes-service/src/server.ts`.
+// This is the composition root of the server. It chooses the store, reads the configuration
+// and starts Node's HTTP server; nothing below it knows which of those it got.
+const server = Layer.unwrap(
+  Effect.gen(function* () {
+    // The loopback default serves this machine alone; HOST=0.0.0.0 lets others reach it.
+    const host = yield* Config.String("HOST").pipe(Config.withDefault("127.0.0.1"));
+    const port = yield* Config.Port("PORT").pipe(Config.withDefault(3000));
+
+    return HttpRouter.serve(routes).pipe(
+      Layer.provide(NodeHttpServer.layer(createServer, { host, port })),
+      // Request bodies have no size limit unless the host sets one. This covers every route.
+      Layer.provide(Layer.succeed(HttpServerRequest.MaxBodySize, ByteSize.mebibytes(1))),
+      Layer.provide(NoteStore.layerMemory),
+    );
+  }),
+);
+
+Layer.launch(server).pipe(NodeRuntime.runMain);

package/examples/notes-service/src/status/Status.ts

@@ -0,0 +1,10 @@
+import { Schema } from "effect";
+import * as Action from "@gjermundgaraba/effect-actions/Action";
+
+// Public: `caller: Action.Anyone`. It answers before anyone has signed in, on every surface.
+export const GetStatus = Action.make("getStatus", {
+  description: "Report whether the service is up and how many notes it holds.",
+  success: { service: Schema.String, notes: Schema.Finite },
+  readOnly: true,
+  caller: Action.Anyone,
+});

package/examples/notes-service/src/status/handlers.ts

@@ -0,0 +1,14 @@
+import { Effect } from "effect";
+import * as Action from "@gjermundgaraba/effect-actions/Action";
+import { NoteStore } from "../notes/store.js";
+import { GetStatus } from "./Status.js";
+
+// A public action takes no `authorize`: nothing would run it.
+export const status = Action.implement(
+  GetStatus,
+  Effect.gen(function* () {
+    const store = yield* NoteStore;
+
+    return () => Effect.map(store.count, (notes) => ({ service: "notes-service", notes }));
+  }),
+);

package/examples/notes-service/src/stdio.ts

@@ -0,0 +1,25 @@
+import { NodeRuntime, NodeStdio } from "@effect/platform-node";
+import { Effect } from "effect";
+import * as ActionCli from "@gjermundgaraba/effect-actions/ActionCli";
+import * as ActionMcp from "@gjermundgaraba/effect-actions/ActionMcp";
+import { identity } from "./identity/handlers.js";
+import { CurrentUser } from "./identity/Identity.js";
+import { users } from "./identity/users.js";
+import { notes } from "./notes/handlers.js";
+import { NoteStore } from "./notes/store.js";
+import { status } from "./status/handlers.js";
+
+// Entrypoint: an MCP server a local agent starts as a subprocess, such as
+// `claude mcp add notes -- node --import tsx examples/notes-service/src/stdio.ts`.
+// The same implementations as the HTTP server, and the same `authorize`. No token arrives
+// over stdio, so this host names the caller itself. It is a process of its own with services
+// of its own: this in-memory store holds its notes, not the running server's. To share them,
+// both provide a store they both reach, such as a database.
+ActionMcp.runStdio([status, notes, identity], { name: "notes-service", version: "1.0.0" }).pipe(
+  // DEMO ONLY: a real host reads who started it, from its own login or configuration.
+  Effect.provideService(CurrentUser, users.ada),
+  Effect.provide([NodeStdio.layer, NoteStore.layerMemory]),
+  // stdout carries the protocol alone, so logs and failures go to stderr.
+  ActionCli.logToStderr,
+  NodeRuntime.runMain,
+);