@gjermundgaraba/effect-actions 0.11.0 → 0.13.0

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

@@ -0,0 +1,288 @@
+import { NodeServices } from "@effect/platform-node";
+import { describe, expect, it } from "@effect/vitest";
+import {
+  Arbitrary,
+  ConfigProvider,
+  Effect,
+  FileSystem,
+  Layer,
+  Schema,
+  Stdio,
+  Stream,
+} from "effect";
+import { CliError, Command } from "effect/cli";
+import { HttpClient, HttpClientRequest } from "effect/http";
+import { TestConsole } from "effect/testing";
+import * as ActionHttp from "@gjermundgaraba/effect-actions/ActionHttp";
+import * as Testing from "@gjermundgaraba/effect-actions/Testing";
+import { Http } from "../src/Api.js";
+import { commands, connection } from "../src/commands.js";
+import { ImportNotes, Note, NoteNotFound } from "../src/notes/Notes.js";
+import { NoteStore } from "../src/notes/store.js";
+import { routes } from "../src/routes.js";
+
+// What the commands add to the routes: their syntax and what they print. They call the real
+// routes in memory, as a client with a token does, where cli.ts connects them to a server.
+const served = Testing.layer(routes).pipe(Layer.provide(NoteStore.layerMemory));
+
+// Effect's own runner, given arguments instead of the process's. The console of `it.effect`
+// keeps every line printed, so a run returns the lines it added.
+const run = (token: string, args: ReadonlyArray<string>, stdin = "") =>
+  Effect.gen(function* () {
+    const before = (yield* TestConsole.logLines).length;
+
+    yield* Command.runWith(commands, { version: "0" })(args).pipe(
+      Effect.updateService(
+        HttpClient.HttpClient,
+        HttpClient.mapRequest(HttpClientRequest.bearerToken(token)),
+      ),
+      Effect.provide(Stdio.layerTest({ stdin: Stream.make(new TextEncoder().encode(stdin)) })),
+      Effect.provide(NodeServices.layer),
+    );
+
+    return (yield* TestConsole.logLines).slice(before);
+  });
+
+// The commands as cli.ts connects them, with what it reads from the environment given as a
+// Layer, so the test decides whether a token is configured, whatever the shell holds.
+const connected = (environment: Record<string, string>, args: ReadonlyArray<string>) =>
+  Command.runWith(commands.pipe(Command.provideEffect(HttpClient.HttpClient, connection)), {
+    version: "0",
+  })(args).pipe(
+    Effect.provide(ConfigProvider.layer(ConfigProvider.fromEnvRecord(environment))),
+    Effect.provide(NodeServices.layer),
+  );
+
+const fitsAFile = (text: string) =>
+  new TextDecoder().decode(new TextEncoder().encode(text)) === text;
+
+// Lines a random string almost never holds, each one the format has to keep apart from a title.
+const trickyLines = Arbitrary.array(
+  Arbitrary.schema(
+    Schema.Literals([
+      "",
+      "# A heading",
+      "\\# Escaped",
+      "\\\\# Twice",
+      "#tag",
+      "\r# After a carriage return",
+      "\u2028# After a line separator",
+    ]),
+  ),
+);
+
+const importable = Arbitrary.all([
+  Arbitrary.schema(ImportNotes.input),
+  Arbitrary.array(trickyLines),
+]).pipe(
+  Arbitrary.map(([{ notes }, extra]) =>
+    notes.map(({ title, body }, place) => ({
+      title,
+      body: [body, ...(extra[place] ?? [])].join("\n"),
+    })),
+  ),
+  Arbitrary.filter((notes) =>
+    notes.every(({ title, body }) => fitsAFile(title) && fitsAFile(body)),
+  ),
+);
+
+describe("the commands", () => {
+  it.effect("take an argument, a flag and stdin, and print what `render` returns", () =>
+    Effect.gen(function* () {
+      // A command without `render` prints its result as JSON.
+      const [created] = yield* run("ada", ["create-note", "--title", "Plan"], "First draft\n");
+      const { id } = yield* Schema.decodeUnknownEffect(Schema.fromJsonString(Note))(created);
+
+      expect(yield* run("ada", ["get-note", id])).toEqual(["# Plan\n\nFirst draft"]);
+
+      yield* run("ada", ["update-note", id, "--revision", "1"], "Second draft\n");
+
+      expect(yield* run("ada", ["get-note", id])).toEqual(["# Plan\n\nSecond draft"]);
+    }).pipe(Effect.provide(served)),
+  );
+
+  it.effect("describe a flag in `--help` as the contract describes its field", () =>
+    Effect.gen(function* () {
+      // Help is one printed text. The description is the `revision` field's, from Notes.ts.
+      expect(yield* run("ada", ["update-note", "--help"])).toEqual([
+        expect.stringContaining("The revision you read: 1 for a new note"),
+      ]);
+    }).pipe(Effect.provide(served)),
+  );
+
+  it.effect("run a command of their own beside the derived ones", () =>
+    Effect.gen(function* () {
+      yield* run("ada", ["create-note", "--title", "Plan"], "First draft\n");
+      yield* run("ada", ["create-note", "--title", "Budget"], "Too small\n");
+
+      // The command writes with the real file system, so the test gives it a real directory.
+      const files = yield* FileSystem.FileSystem;
+      const file = `${yield* files.makeTempDirectoryScoped()}/notes.md`;
+
+      expect(yield* run("ada", ["export", file])).toEqual([`Wrote 2 notes to ${file}`]);
+      expect(yield* files.readFileString(file)).toBe(
+        "# Plan\n\nFirst draft\n\n# Budget\n\nToo small",
+      );
+    }).pipe(Effect.provide(served), Effect.provide(NodeServices.layer)),
+  );
+
+  it.effect("import a file `export` wrote with one call, all its notes or none", () =>
+    Effect.gen(function* () {
+      const files = yield* FileSystem.FileSystem;
+      const directory = yield* files.makeTempDirectoryScoped();
+      const file = `${directory}/notes.md`;
+
+      yield* files.writeFileString(file, "# Plan\n\nFirst draft\n\n# Budget\n\nToo small");
+
+      expect(yield* run("ada", ["import", file])).toEqual(["Created 2 notes"]);
+      expect(yield* run("grace", ["import", file])).toEqual(["Created 2 notes"]);
+
+      yield* files.writeFileString(`${directory}/untitled.md`, "# Plan\n\nKept?\n\n# \n\nNo title");
+
+      const refused = yield* Effect.flip(run("ada", ["import", `${directory}/untitled.md`]));
+
+      expect(refused).toHaveProperty(
+        "userMessage",
+        expect.stringContaining("A note needs a title."),
+      );
+      const [listed = ""] = yield* run("ada", ["list-notes"]);
+
+      const { notes } = yield* Schema.decodeUnknownEffect(
+        Schema.fromJsonString(
+          Schema.Struct({ notes: Schema.Array(Schema.Struct({ title: Schema.String })) }),
+        ),
+      )(listed);
+
+      expect(notes.map(({ title }) => title)).toEqual(["Plan", "Budget"]);
+
+      // A missing file is a usage error: the command's help, and the file named on stderr.
+      yield* Effect.flip(run("ada", ["import", `${directory}/nowhere.md`]));
+
+      expect(yield* TestConsole.errorLines).toContainEqual(
+        expect.stringMatching(
+          /Invalid value for argument <file>: .*nowhere\.md.*File does not exist/su,
+        ),
+      );
+    }).pipe(Effect.provide(served), Effect.provide(NodeServices.layer)),
+  );
+
+  // Any notes the contract accepts, generated from its schema, with lines that start as a title
+  // would added to their bodies. A file holds Unicode text, so a string JSON carries but no file
+  // can, one with a lone surrogate, is left out.
+  it.effect.prop(
+    "import every note `export` wrote as it was, whatever its body holds",
+    [importable],
+    ([notes]) =>
+      Effect.gen(function* () {
+        const files = yield* FileSystem.FileSystem;
+        const file = `${yield* files.makeTempDirectoryScoped()}/notes.md`;
+
+        const as = (token: string) =>
+          ActionHttp.client(Http).pipe(
+            Effect.updateService(
+              HttpClient.HttpClient,
+              HttpClient.mapRequest(HttpClientRequest.bearerToken(token)),
+            ),
+          );
+
+        const [ada, grace] = [yield* as("ada"), yield* as("grace")];
+
+        yield* ada.importNotes({ notes });
+        yield* run("ada", ["export", file]);
+        yield* run("grace", ["import", file]);
+
+        const { notes: listed } = yield* grace.listNotes();
+        const read = yield* Effect.forEach(listed, ({ id }) => grace.getNote({ id }));
+
+        expect(read.map(({ title, body }) => ({ title, body }))).toEqual(notes);
+      }).pipe(Effect.provide(served), Effect.provide(NodeServices.layer)),
+    { arbitrary: { runs: 50 } },
+  );
+
+  it.effect(
+    "import an empty file as no notes, and refuse one `export` did not write or too long",
+    () =>
+      Effect.gen(function* () {
+        const files = yield* FileSystem.FileSystem;
+        const directory = yield* files.makeTempDirectoryScoped();
+
+        yield* files.writeFileString(`${directory}/empty.md`, "");
+
+        expect(yield* run("grace", ["import", `${directory}/empty.md`])).toEqual([
+          "Created 0 notes",
+        ]);
+
+        yield* files.writeFileString(`${directory}/preamble.md`, "My notes\n\n# Plan\n\nDraft");
+
+        expect(
+          yield* Effect.flip(run("grace", ["import", `${directory}/preamble.md`])),
+        ).toHaveProperty(
+          "userMessage",
+          "The file does not start with a `# ` title, as `notes export` writes one.",
+        );
+
+        const many = Array.from({ length: 101 }, (_, place) => `# Note ${place}\n\nBody`);
+
+        yield* files.writeFileString(`${directory}/many.md`, many.join("\n\n"));
+
+        expect(yield* Effect.flip(run("grace", ["import", `${directory}/many.md`]))).toHaveProperty(
+          "userMessage",
+          expect.stringContaining("An import holds at most 100 notes."),
+        );
+
+        expect(yield* run("grace", ["list-notes"])).toEqual([
+          JSON.stringify({ notes: [] }, null, 2),
+        ]);
+      }).pipe(Effect.provide(served), Effect.provide(NodeServices.layer)),
+  );
+
+  it.effect("fail as the server refuses, a command of their own included", () =>
+    Effect.gen(function* () {
+      const refused = yield* Effect.flip(run("mallory", ["export", "notes.md"]));
+
+      expect(refused).toBeInstanceOf(CliError.UserError);
+      expect(refused).toHaveProperty(
+        "userMessage",
+        '{"_tag":"Unauthenticated","message":"Unknown demo token."}',
+      );
+      // The command's own context is a line of its own on stderr, the JSON left as it is.
+      expect(yield* TestConsole.errorLines).toContain("The export to notes.md did not finish.");
+
+      // Not an action's error: the file system's, named in the message.
+      const unwritable = yield* Effect.flip(run("ada", ["export", "no-such-directory/notes.md"]));
+
+      expect(unwritable).toBeInstanceOf(CliError.UserError);
+      expect(unwritable).toHaveProperty("userMessage", expect.stringMatching(/^PlatformError: /));
+
+      const missing = yield* Effect.flip(run("ada", ["get-note", "9"]));
+
+      expect(missing).toHaveProperty("cause", new NoteNotFound({ id: "9" }));
+    }).pipe(Effect.provide(served)),
+  );
+
+  it.effect("call as the configured token names, and ask for one where none is configured", () =>
+    Effect.gen(function* () {
+      yield* connected({ NOTES_TOKEN: "reader" }, ["who-am-i"]);
+
+      expect(yield* TestConsole.logLines).toEqual([expect.stringContaining('"id": "reader"')]);
+
+      const refused = yield* Effect.flip(connected({}, ["list-notes"]));
+
+      expect(refused).toBeInstanceOf(CliError.UserError);
+      expect(refused).toHaveProperty(
+        "userMessage",
+        "NOTES_TOKEN is not set. Set it to your token: export NOTES_TOKEN=<your token>",
+      );
+
+      // What a person sees: that message, once, on stderr, and no report of a `ConfigError`.
+      expect(yield* TestConsole.errorLines).toEqual([
+        expect.stringContaining("NOTES_TOKEN is not set."),
+      ]);
+
+      // The token is read when a command runs, so its help needs none.
+      yield* connected({}, ["list-notes", "--help"]);
+
+      expect(yield* TestConsole.logLines).toHaveLength(2);
+    }).pipe(Effect.provide(served)),
+  );
+});

package/examples/notes-service/test/notes/notes.test.ts

@@ -0,0 +1,103 @@
+import { describe, expect, it } from "@effect/vitest";
+import { Array, Effect, Exit, References } from "effect";
+import * as Action from "@gjermundgaraba/effect-actions/Action";
+import { CurrentUser } from "../../src/identity/Identity.js";
+import { users } from "../../src/identity/users.js";
+import { notes } from "../../src/notes/handlers.js";
+import { NoteChanged, NoteNotFound } from "../../src/notes/Notes.js";
+import { NoteStore } from "../../src/notes/store.js";
+
+// What the implementation does, with no transport: `Action.client` runs the same decoding,
+// `authorize` and handler a server runs. Each call names its caller, as a request would.
+const as = (user: keyof typeof users) => Effect.provideService(CurrentUser, users[user]);
+
+describe("notes, in process", () => {
+  it.effect("keeps each user's notes their own", () =>
+    Effect.gen(function* () {
+      const client = yield* Action.client(notes);
+      const note = yield* client.createNote({ title: "Plan", body: "Draft" }).pipe(as("ada"));
+
+      expect(yield* client.listNotes().pipe(as("ada"))).toEqual({
+        notes: [{ id: note.id, title: "Plan" }],
+      });
+      expect(yield* client.listNotes().pipe(as("grace"))).toEqual({ notes: [] });
+
+      const missing = new NoteNotFound({ id: note.id });
+      const update = { id: note.id, body: "Mine now", revision: note.revision };
+
+      expect(yield* Effect.flip(client.getNote({ id: note.id }).pipe(as("grace")))).toEqual(
+        missing,
+      );
+      expect(yield* Effect.flip(client.updateNote(update).pipe(as("grace")))).toEqual(missing);
+      expect(yield* Effect.flip(client.deleteNote({ id: note.id }).pipe(as("grace")))).toEqual(
+        missing,
+      );
+      expect(yield* client.getNote({ id: note.id }).pipe(as("ada"))).toEqual(note);
+    }).pipe(Effect.provide(NoteStore.layerMemory)),
+  );
+
+  it.effect("deletes a note for its owner", () =>
+    Effect.gen(function* () {
+      const client = yield* Action.client(notes);
+      const note = yield* client.createNote({ title: "Plan", body: "Draft" }).pipe(as("ada"));
+
+      yield* client.deleteNote({ id: note.id }).pipe(as("ada"));
+
+      expect(yield* Effect.flip(client.getNote({ id: note.id }).pipe(as("ada")))).toEqual(
+        new NoteNotFound({ id: note.id }),
+      );
+    }).pipe(Effect.provide(NoteStore.layerMemory)),
+  );
+
+  it.effect("refuses an update of a revision that is no longer current", () =>
+    Effect.gen(function* () {
+      const client = yield* Action.client(notes);
+      const note = yield* client.createNote({ title: "Plan", body: "Draft" }).pipe(as("ada"));
+      const update = { id: note.id, body: "Final", revision: note.revision };
+
+      expect(yield* client.updateNote(update).pipe(as("ada"))).toMatchObject({ revision: 2 });
+      expect(yield* Effect.flip(client.updateNote(update).pipe(as("ada")))).toEqual(
+        new NoteChanged({ id: note.id, revision: 2 }),
+      );
+    }).pipe(Effect.provide(NoteStore.layerMemory)),
+  );
+
+  it.effect("lets one of two concurrent updates of the same revision through", () =>
+    Effect.gen(function* () {
+      const client = yield* Action.client(notes);
+
+      // A fiber is set aside after every `steps` steps, and two that run at once then take
+      // turns. Each count sets the first update aside at another point of its work; under
+      // three, the two do not finish.
+      const succeeded = yield* Effect.forEach(Array.range(3, 60), (steps) =>
+        Effect.gen(function* () {
+          const note = yield* client.createNote({ title: "Plan", body: "Draft" }).pipe(as("ada"));
+
+          const update = (body: string) =>
+            Effect.exit(client.updateNote({ id: note.id, body, revision: 1 }).pipe(as("ada")));
+
+          const exits = yield* Effect.all([update("One"), update("Two")], {
+            concurrency: "unbounded",
+          }).pipe(Effect.provideService(References.MaxOpsBeforeYield, steps));
+
+          return exits.filter(Exit.isSuccess).length;
+        }),
+      );
+
+      expect(succeeded).toEqual(Array.range(3, 60).map(() => 1));
+    }).pipe(Effect.provide(NoteStore.layerMemory)),
+  );
+
+  it.effect("refuses a write from a caller holding the read scope alone", () =>
+    Effect.gen(function* () {
+      const client = yield* Action.client(notes);
+      const create = client.createNote({ title: "Plan", body: "Draft" });
+      const refusal = yield* Effect.flip(create.pipe(as("reader")));
+
+      // `toEqual` on an error compares its fields and never its message, so the message is
+      // asserted on its own.
+      expect(refusal).toBeInstanceOf(Action.Forbidden);
+      expect(refusal.message).toBe("Requires notes:write.");
+    }).pipe(Effect.provide(NoteStore.layerMemory)),
+  );
+});

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

@@ -0,0 +1,84 @@
+import { describe, expect, it } from "@effect/vitest";
+import { Effect, Layer } from "effect";
+import { HttpClient, HttpClientRequest } from "effect/http";
+import * as Action from "@gjermundgaraba/effect-actions/Action";
+import * as ActionHttp from "@gjermundgaraba/effect-actions/ActionHttp";
+import * as Testing from "@gjermundgaraba/effect-actions/Testing";
+import { Http } from "../src/Api.js";
+import { Notes } from "../src/notes/Notes.js";
+import { NoteStore } from "../src/notes/store.js";
+import { routes } from "../src/routes.js";
+import { GetStatus } from "../src/status/Status.js";
+
+// What the wire adds: the real routes, behind their real authentication, answering in memory.
+// No port is opened. The caller is the token each client sends, as in production.
+const served = Testing.layer(routes).pipe(Layer.provide(NoteStore.layerMemory));
+
+const as = (token: string) => ({
+  transformClient: HttpClient.mapRequest(HttpClientRequest.bearerToken(token)),
+});
+
+describe("the service, over HTTP and MCP", () => {
+  it.effect("answers the public action without a token and refuses the rest", () =>
+    Effect.gen(function* () {
+      const anyone = yield* ActionHttp.client(Http);
+
+      expect(yield* anyone.getStatus()).toEqual({ service: "notes-service", notes: 0 });
+      expect(yield* Effect.flip(anyone.whoAmI())).toBeInstanceOf(Action.Unauthenticated);
+    }).pipe(Effect.provide(served)),
+  );
+
+  it.effect("refuses a token no user holds", () =>
+    Effect.gen(function* () {
+      const stranger = yield* ActionHttp.client(Http, as("mallory"));
+
+      const refusal = yield* Effect.flip(stranger.whoAmI());
+
+      expect(refusal).toBeInstanceOf(Action.Unauthenticated);
+      expect(refusal.message).toBe("Unknown demo token.");
+    }).pipe(Effect.provide(served)),
+  );
+
+  it.effect("serves the host's own routes beside the actions'", () =>
+    Effect.gen(function* () {
+      const health = yield* HttpClient.get("/healthz");
+      const openApi = yield* HttpClient.get("/api/openapi.json");
+
+      expect(yield* health.text).toBe("ok");
+      expect(yield* openApi.text).toContain('"/api/createNote"');
+    }).pipe(Effect.provide(served)),
+  );
+
+  it.effect("names the scope a caller lacks, so an OAuth client can ask for it", () =>
+    Effect.gen(function* () {
+      const reader = yield* ActionHttp.client(Http, as("reader"));
+
+      expect(yield* reader.whoAmI()).toEqual({ id: "reader", scopes: ["notes:read"] });
+
+      const refusal = yield* Effect.flip(reader.createNote({ title: "Plan", body: "" }));
+
+      expect(refusal).toBeInstanceOf(Action.Forbidden);
+      expect(refusal).toHaveProperty("scopes", ["notes:write"]);
+    }).pipe(Effect.provide(served)),
+  );
+
+  it.effect("serves one store to both surfaces: a note written over HTTP is read as a tool", () =>
+    Effect.gen(function* () {
+      const http = yield* ActionHttp.client(Http, as("ada"));
+      const mcp = yield* Testing.mcpClient([GetStatus, ...Notes], as("ada"));
+      const note = yield* http.createNote({ title: "Plan", body: "Draft" });
+
+      expect(yield* mcp.getNote({ id: note.id })).toEqual(note);
+      expect(yield* mcp.getStatus()).toEqual({ service: "notes-service", notes: 1 });
+    }).pipe(Effect.provide(served)),
+  );
+
+  it.effect("lists every tool to a signed-out MCP client, as one of them is public", () =>
+    Effect.gen(function* () {
+      const response = yield* HttpClient.execute(Testing.mcpRequest("tools/list"));
+
+      expect(response.status).toBe(200);
+      expect(yield* response.text).toContain('"name":"createNote"');
+    }).pipe(Effect.provide(served)),
+  );
+});

package/examples/quickstart/README.md

@@ -0,0 +1,31 @@
+# quickstart
+
+The smallest complete program: one action, served as a JSON route and as an MCP tool, called
+with its typed client. It is the skeleton of [notes-service](../notes-service/), which adds
+authentication, authorization, declared errors, a store, a CLI and a browser client to the same
+layout.
+
+## Run it
+
+From the repository root, after `vp install` (from an installed package, see
+[Run one](../README.md#run-one)):
+
+```sh
+node --import tsx examples/quickstart/src/server.ts     # 127.0.0.1:3000
+node --import tsx examples/quickstart/src/client.ts     # Hello, Ada!
+vp test examples/quickstart
+```
+
+## Layout
+
+```text
+src/
+├── greeting/
+│   ├── Greeting.ts    the contract
+│   └── handlers.ts    its implementation
+├── Api.ts             the HTTP binding, shared by server and client
+├── routes.ts          the surfaces: POST /api/greet and /mcp
+├── server.ts          entrypoint
+└── client.ts          entrypoint
+test/greeting/         the routes, called in memory
+```

package/examples/quickstart/src/Api.ts

@@ -0,0 +1,5 @@
+import * as ActionHttp from "@gjermundgaraba/effect-actions/ActionHttp";
+import { Greet } from "./greeting/Greeting.js";
+
+// The HTTP binding: `POST /api/greet`. The server serves it and the client calls it.
+export const Http = ActionHttp.make([Greet]);

package/examples/quickstart/src/client.ts

@@ -0,0 +1,13 @@
+import { NodeRuntime } from "@effect/platform-node";
+import { Console, Effect } from "effect";
+import { FetchHttpClient } from "effect/http";
+import * as ActionHttp from "@gjermundgaraba/effect-actions/ActionHttp";
+import { Http } from "./Api.js";
+
+// Entrypoint: `node --import tsx examples/quickstart/src/client.ts`, with the server running.
+// One typed method per action of the binding.
+Effect.gen(function* () {
+  const client = yield* ActionHttp.client(Http, { baseUrl: "http://127.0.0.1:3000" });
+
+  yield* Console.log(yield* client.greet({ name: "Ada" }));
+}).pipe(Effect.provide(FetchHttpClient.layer), NodeRuntime.runMain);

package/examples/quickstart/src/greeting/Greeting.ts

@@ -0,0 +1,12 @@
+import { Schema } from "effect";
+import * as Action from "@gjermundgaraba/effect-actions/Action";
+
+// A contract: what the action takes and answers, whether it changes anything, and who may
+// call it. It imports no server code, so any client can import it, a browser page included.
+export const Greet = Action.make("greet", {
+  description: "Greet someone by name.",
+  input: { name: Schema.String },
+  success: Schema.String,
+  readOnly: true,
+  caller: Action.Anyone,
+});

package/examples/quickstart/src/greeting/handlers.ts

@@ -0,0 +1,6 @@
+import { Effect } from "effect";
+import * as Action from "@gjermundgaraba/effect-actions/Action";
+import { Greet } from "./Greeting.js";
+
+// The implementation: the contract bound to its handler. Every surface takes this one value.
+export const greeting = Action.implement(Greet, ({ name }) => Effect.succeed(`Hello, ${name}!`));

package/examples/quickstart/src/routes.ts

@@ -0,0 +1,11 @@
+import { Layer } from "effect";
+import * as ActionHttp from "@gjermundgaraba/effect-actions/ActionHttp";
+import * as ActionMcp from "@gjermundgaraba/effect-actions/ActionMcp";
+import { Http } from "./Api.js";
+import { greeting } from "./greeting/handlers.js";
+
+// One implementation, two surfaces: a JSON route and an MCP tool at `/mcp`.
+export const routes = Layer.mergeAll(
+  ActionHttp.layer(Http, greeting),
+  ActionMcp.layerHttp(greeting, { name: "greetings", version: "1.0.0" }),
+);

package/examples/quickstart/src/server.ts

@@ -0,0 +1,16 @@
+import { createServer } from "node:http";
+import { NodeHttpServer, NodeRuntime } from "@effect/platform-node";
+import { Layer } from "effect";
+import { HttpRouter } from "effect/http";
+import { routes } from "./routes.js";
+
+// Entrypoint: `node --import tsx examples/quickstart/src/server.ts`.
+// A real server reads its port from config, `Config.Port("PORT")`, and limits request bodies:
+// `Layer.provide(Layer.succeed(HttpServerRequest.MaxBodySize, ByteSize.mebibytes(1)))`.
+// `127.0.0.1` serves this machine alone: a server others reach reads its host from config,
+// `Config.String("HOST").pipe(Config.withDefault("127.0.0.1"))`.
+HttpRouter.serve(routes).pipe(
+  Layer.provide(NodeHttpServer.layer(createServer, { host: "127.0.0.1", port: 3000 })),
+  Layer.launch,
+  NodeRuntime.runMain,
+);

package/examples/quickstart/test/greeting/greeting.test.ts

@@ -0,0 +1,18 @@
+import { expect, it } from "@effect/vitest";
+import { Effect } from "effect";
+import * as ActionHttp from "@gjermundgaraba/effect-actions/ActionHttp";
+import * as Testing from "@gjermundgaraba/effect-actions/Testing";
+import { Http } from "../../src/Api.js";
+import { Greet } from "../../src/greeting/Greeting.js";
+import { routes } from "../../src/routes.js";
+
+// The routes answer in memory: no port, and the same code the server runs.
+it.effect("greets over HTTP and as an MCP tool", () =>
+  Effect.gen(function* () {
+    const http = yield* ActionHttp.client(Http);
+    const mcp = yield* Testing.mcpClient([Greet]);
+
+    expect(yield* http.greet({ name: "Ada" })).toBe("Hello, Ada!");
+    expect(yield* mcp.greet({ name: "Ada" })).toBe("Hello, Ada!");
+  }).pipe(Effect.provide(Testing.layer(routes))),
+);