@gjermundgaraba/effect-actions 0.10.0 → 0.12.0

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,91 @@
+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.",
+});
+
+const Title = Schema.String.check(Schema.isMinLength(1)).annotate({
+  description: "A short name for the note, 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,
+  mcp: { destructiveHint: false },
+});
+
+export const DeleteNote = Action.make("deleteNote", {
+  description: "Delete a note for good.",
+  input: { id: Id },
+  error: NoteNotFound,
+  readOnly: false,
+  caller: CurrentUser,
+});
+
+export const Notes = [ListNotes, GetNote, CreateNote, UpdateNote, DeleteNote] as const;

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

@@ -0,0 +1,33 @@
+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 its services. `CurrentUser` is read per call. 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)),
+    };
+  }),
+  { authorize },
+);

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

@@ -0,0 +1,73 @@
+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>;
+    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 })),
+      // 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* () {
+    const port = yield* Config.Port("PORT").pipe(Config.withDefault(3000));
+
+    return HttpRouter.serve(routes).pipe(
+      // `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"))`.
+      Layer.provide(NodeHttpServer.layer(createServer, { host: "127.0.0.1", 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,
+);

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

@@ -0,0 +1,134 @@
+import { NodeServices } from "@effect/platform-node";
+import { describe, expect, it } from "@effect/vitest";
+import { 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 Testing from "@gjermundgaraba/effect-actions/Testing";
+import { commands, connection } from "../src/commands.js";
+import { 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),
+  );
+
+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("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)),
+  );
+});