@gjermundgaraba/effect-actions 0.20.0 → 0.21.0

package/examples/mcp-tools/src/platform/print-farm.ts

@@ -2,10 +2,11 @@ import { Config, Effect, Layer, Redacted, Schema } from "effect";
 import {
   HttpBody,
   HttpClient,
-  type HttpClientError,
   HttpClientRequest,
   HttpClientResponse,
 } from "effect/http";
+import type { HttpClientError } from "effect/http";
+
 import { PrintFarm } from "../printers/farm.js";
 import { Printer, PrintFarmError } from "../printers/Printers.js";
 
@@ -13,16 +14,24 @@ const fail = (message: string) => Effect.fail(new PrintFarmError({ message }));
 
 const unreadable = "The print farm sent an answer this server could not read.";
 
+// An id is written into the path as it is: the contract admits only letters, digits,
+// `_` and `-`, so it is always one segment. Encoding would not make other text safe:
+// `encodeURIComponent` leaves `..` alone, and a URL parser then walks up the path.
+const at = (id: string, rest = "") => `/api/printers/${id}${rest}`;
+
 // The farm answers a request it refuses with a status that is not 2xx and `{ "error": "..." }`.
 // Its reason is passed on to the model, which can act on "The printer is busy with a job".
 const refuseUnlessOk = HttpClientResponse.matchStatus({
   "2xx": (response) => Effect.succeed(response),
   orElse: (response) =>
-    HttpClientResponse.schemaBodyJson(Schema.Struct({ error: Schema.String }))(response).pipe(
+    HttpClientResponse.schemaBodyJson(Schema.Struct({ error: Schema.String }))(
+      response
+    ).pipe(
       Effect.matchEffect({
-        onFailure: () => fail(`The print farm refused the request (HTTP ${response.status}).`),
+        onFailure: () =>
+          fail(`The print farm refused the request (HTTP ${response.status}).`),
         onSuccess: ({ error }) => fail(`The print farm refused: ${error}`),
-      }),
+      })
     ),
 });
 
@@ -30,24 +39,34 @@ const refuseUnlessOk = HttpClientResponse.matchStatus({
 // answer of another shape than expected, or none in time. Nothing of the HTTP client's own
 // errors leaves this file, so no tool can fail with something its contract does not declare.
 const asPrintFarmError = <A>(
-  effect: Effect.Effect<A, PrintFarmError | HttpClientError.HttpClientError | Schema.SchemaError>,
+  effect: Effect.Effect<
+    A,
+    PrintFarmError | HttpClientError.HttpClientError | Schema.SchemaError
+  >
 ) =>
   effect.pipe(
-    Effect.catchTag("HttpClientError", ({ response }) =>
-      fail(response === undefined ? "The print farm could not be reached." : unreadable),
-    ),
-    Effect.catchTag("SchemaError", () => fail(unreadable)),
+    Effect.catchTags({
+      HttpClientError: ({ response }) =>
+        fail(
+          response === undefined
+            ? "The print farm could not be reached."
+            : unreadable
+        ),
+      SchemaError: () => fail(unreadable),
+    }),
     Effect.timeoutOrElse({
       duration: "30 seconds",
       orElse: () => fail("The print farm did not answer in time."),
-    }),
+    })
   );
 
 const asImage = (response: HttpClientResponse.HttpClientResponse) =>
   Effect.gen(function* () {
     const mimeType = response.headers["content-type"];
 
-    if (mimeType === undefined || !mimeType.startsWith("image/")) return yield* fail(unreadable);
+    if (mimeType === undefined || !mimeType.startsWith("image/")) {
+      return yield* fail(unreadable);
+    }
 
     return { data: new Uint8Array(yield* response.arrayBuffer), mimeType };
   });
@@ -67,7 +86,7 @@ export const printFarm = Layer.effect(
 
     const http = (yield* HttpClient.HttpClient).pipe(
       HttpClient.mapRequest(HttpClientRequest.prependUrl(url.href)),
-      HttpClient.transformResponse(Effect.flatMap(refuseUnlessOk)),
+      HttpClient.transformResponse(Effect.flatMap(refuseUnlessOk))
     );
 
     // Signs in once, here, and every call below reuses the token, kept `Redacted` so no log
@@ -81,38 +100,49 @@ export const printFarm = Layer.effect(
       .pipe(
         Effect.flatMap(
           HttpClientResponse.schemaBodyJson(
-            Schema.Struct({ token: Schema.RedactedFromValue(Schema.String) }),
-          ),
+            Schema.Struct({ token: Schema.RedactedFromValue(Schema.String) })
+          )
         ),
-        asPrintFarmError,
+        asPrintFarmError
       );
 
-    yield* Effect.logInfo(`Signed in to the print farm at ${url.host} as ${user}.`);
-
-    const api = HttpClient.mapRequest(http, HttpClientRequest.bearerToken(session.token));
+    yield* Effect.logInfo(
+      `Signed in to the print farm at ${url.host} as ${user}.`
+    );
 
-    // An id is written into the path as it is: the contract admits only letters, digits,
-    // `_` and `-`, so it is always one segment. Encoding would not make other text safe:
-    // `encodeURIComponent` leaves `..` alone, and a URL parser then walks up the path.
-    const at = (id: string, rest = "") => `/api/printers/${id}${rest}`;
+    const api = HttpClient.mapRequest(
+      http,
+      HttpClientRequest.bearerToken(session.token)
+    );
 
     const printer = (answer: ReturnType<typeof api.get>) =>
-      answer.pipe(Effect.flatMap(HttpClientResponse.schemaBodyJson(Printer)), asPrintFarmError);
+      answer.pipe(
+        Effect.flatMap(HttpClientResponse.schemaBodyJson(Printer)),
+        asPrintFarmError
+      );
 
     return PrintFarm.of({
       printers: api.get("/api/printers").pipe(
         Effect.flatMap(
-          HttpClientResponse.schemaBodyJson(Schema.Struct({ printers: Schema.Array(Printer) })),
+          HttpClientResponse.schemaBodyJson(
+            Schema.Struct({ printers: Schema.Array(Printer) })
+          )
         ),
         Effect.map(({ printers }) => printers),
-        asPrintFarmError,
+        asPrintFarmError
       ),
       printer: (id) => printer(api.get(at(id))),
-      snapshot: (id) => api.get(at(id, "/camera")).pipe(Effect.flatMap(asImage), asPrintFarmError),
+      snapshot: (id) =>
+        api
+          .get(at(id, "/camera"))
+          .pipe(Effect.flatMap(asImage), asPrintFarmError),
       start: (id, file) =>
-        printer(api.post(at(id, "/job"), { body: HttpBody.jsonUnsafe({ file }) })),
-      setPaused: (id, paused) => printer(api.post(at(id, paused ? "/pause" : "/resume"))),
+        printer(
+          api.post(at(id, "/job"), { body: HttpBody.jsonUnsafe({ file }) })
+        ),
+      setPaused: (id, paused) =>
+        printer(api.post(at(id, paused ? "/pause" : "/resume"))),
       cancel: (id) => printer(api.del(at(id, "/job"))),
     });
-  }),
+  })
 );

package/examples/mcp-tools/src/printers/Printers.ts

@@ -1,5 +1,5 @@
-import { Schema } from "effect";
 import * as Action from "@gjermundgaraba/effect-actions/Action";
+import { Schema } from "effect";
 
 export const Printer = Schema.Struct({
   id: Schema.String,
@@ -8,8 +8,10 @@ export const Printer = Schema.Struct({
   job: Schema.NullOr(
     Schema.Struct({
       file: Schema.String,
-      progress: Schema.Finite.annotate({ description: "Percent done, 0 to 100." }),
-    }),
+      progress: Schema.Finite.annotate({
+        description: "Percent done, 0 to 100.",
+      }),
+    })
   ),
 });
 
@@ -18,7 +20,10 @@ export type Printer = typeof Printer.Type;
 // The one error every tool declares: the farm could not do what was asked. A model reads its
 // `message` and decides what to do next, so the message says what went wrong in plain words.
 // A handler failing with an error its action does not declare does not compile.
-export class PrintFarmError extends Schema.TaggedError<PrintFarmError>()("PrintFarmError", {
+export class PrintFarmError extends Schema.TaggedError<
+  PrintFarmError,
+  { readonly brand: unique symbol }
+>()("PrintFarmError", {
   message: Schema.String,
 }) {}
 
@@ -27,7 +32,9 @@ export class PrintFarmError extends Schema.TaggedError<PrintFarmError>()("PrintF
 // from a model. An id that does not match is refused as invalid input, on every surface,
 // before a handler runs, so `..` or `a/b` never reaches the farm. The `u` flag is what puts the
 // pattern in the tool's schema, where the model reads it.
-const PrinterId = Schema.String.check(Schema.isPattern(/^[A-Za-z0-9_-]+$/u)).annotate({
+const PrinterId = Schema.String.check(
+  Schema.isPattern(/^[A-Za-z0-9_-]+$/u)
+).annotate({
   description: "A printer's id, as list_printers gives it, such as mk4-1.",
 });
 
@@ -74,7 +81,9 @@ export const StartPrint = Action.make("start_print", {
     "named as the farm stores it. Refused when the printer is not idle.",
   input: {
     printer_id: PrinterId,
-    file: Schema.String.annotate({ description: "A G-code file's name, such as bracket.gcode." }),
+    file: Schema.String.annotate({
+      description: "A G-code file's name, such as bracket.gcode.",
+    }),
   },
   success: Printer,
   readOnly: false,
@@ -89,7 +98,9 @@ export const SetPaused = Action.make("set_paused", {
     "pausing is the safe move while deciding what to do with a print that looks wrong.",
   input: {
     printer_id: PrinterId,
-    paused: Schema.Boolean.annotate({ description: "true to pause the job, false to resume it." }),
+    paused: Schema.Boolean.annotate({
+      description: "true to pause the job, false to resume it.",
+    }),
   },
   success: Printer,
   readOnly: false,

package/examples/mcp-tools/src/printers/farm.ts

@@ -1,5 +1,7 @@
-import { Context, type Effect } from "effect";
 import type * as Action from "@gjermundgaraba/effect-actions/Action";
+import { Context } from "effect";
+import type { Effect } from "effect";
+
 import type { Printer, PrintFarmError } from "./Printers.js";
 
 /**
@@ -10,11 +12,19 @@ import type { Printer, PrintFarmError } from "./Printers.js";
 export class PrintFarm extends Context.Service<
   PrintFarm,
   {
-    readonly printers: Effect.Effect<ReadonlyArray<Printer>, PrintFarmError>;
+    readonly printers: Effect.Effect<readonly Printer[], PrintFarmError>;
     readonly printer: (id: string) => Effect.Effect<Printer, PrintFarmError>;
-    readonly snapshot: (id: string) => Effect.Effect<typeof Action.Image.Type, PrintFarmError>;
-    readonly start: (id: string, file: string) => Effect.Effect<Printer, PrintFarmError>;
-    readonly setPaused: (id: string, paused: boolean) => Effect.Effect<Printer, PrintFarmError>;
+    readonly snapshot: (
+      id: string
+    ) => Effect.Effect<typeof Action.Image.Type, PrintFarmError>;
+    readonly start: (
+      id: string,
+      file: string
+    ) => Effect.Effect<Printer, PrintFarmError>;
+    readonly setPaused: (
+      id: string,
+      paused: boolean
+    ) => Effect.Effect<Printer, PrintFarmError>;
     readonly cancel: (id: string) => Effect.Effect<Printer, PrintFarmError>;
   }
 >()("mcp-tools/PrintFarm") {}

package/examples/mcp-tools/src/printers/handlers.ts

@@ -1,5 +1,6 @@
-import { Effect } from "effect";
 import * as Action from "@gjermundgaraba/effect-actions/Action";
+import { Effect } from "effect";
+
 import { PrintFarm } from "./farm.js";
 import { Printers } from "./Printers.js";
 
@@ -14,16 +15,21 @@ export const printers = Action.implement(
     const farm = yield* PrintFarm;
 
     return {
-      list_printers: () => Effect.map(farm.printers, (all) => ({ printers: all })),
+      list_printers: () =>
+        Effect.map(farm.printers, (all) => ({ printers: all })),
       // Returned as `{ data, mimeType }` like any other field: the MCP surface makes the block.
       get_camera_snapshot: ({ printer_id }) =>
         Effect.all(
-          { printer: farm.printer(printer_id), image: farm.snapshot(printer_id) },
-          { concurrency: "unbounded" },
+          {
+            printer: farm.printer(printer_id),
+            image: farm.snapshot(printer_id),
+          },
+          { concurrency: "unbounded" }
         ),
       start_print: ({ printer_id, file }) => farm.start(printer_id, file),
-      set_paused: ({ printer_id, paused }) => farm.setPaused(printer_id, paused),
+      set_paused: ({ printer_id, paused }) =>
+        farm.setPaused(printer_id, paused),
       cancel_print: ({ printer_id }) => farm.cancel(printer_id),
     };
-  }),
+  })
 );

package/examples/mcp-tools/src/routes.ts

@@ -1,6 +1,7 @@
+import * as ActionMcp from "@gjermundgaraba/effect-actions/ActionMcp";
 import { Config, Effect, Layer, Schema } from "effect";
 import { HttpRouter, HttpServerResponse } from "effect/http";
-import * as ActionMcp from "@gjermundgaraba/effect-actions/ActionMcp";
+
 import { serverInfo } from "./instructions.js";
 import { printers } from "./printers/handlers.js";
 
@@ -11,9 +12,10 @@ export const routes = Layer.unwrap(
     // A browser sends its page's `Origin`, and the endpoint refuses every origin not listed
     // here, so a web page a user happens to visit cannot call the tools. Other MCP clients
     // send none and pass. `ALLOWED_ORIGINS=https://a.example,https://b.example`; none by default.
-    const allowedOrigins = yield* Config.Array(Schema.String, "ALLOWED_ORIGINS").pipe(
-      Config.withDefault([]),
-    );
+    const allowedOrigins = yield* Config.Array(
+      Schema.String,
+      "ALLOWED_ORIGINS"
+    ).pipe(Config.withDefault([]));
 
     // The Origin check only refuses. A browser also needs CORS: an answer to its preflight, and
     // headers on the endpoint's answers. `HttpRouter.cors` is global to the router and, given
@@ -39,7 +41,7 @@ export const routes = Layer.unwrap(
     return Layer.mergeAll(
       // No `authentication`: every tool is public, so the endpoint authenticates nothing.
       ActionMcp.layerHttp(printers, { ...serverInfo, allowedOrigins }),
-      HttpRouter.add("GET", "/healthz", HttpServerResponse.text("ok")),
+      HttpRouter.add("GET", "/healthz", HttpServerResponse.text("ok"))
     ).pipe(Layer.provide(cors));
-  }),
+  })
 );

package/examples/mcp-tools/src/server.ts

@@ -1,7 +1,9 @@
 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 { fakeFarm } from "./platform/fake-farm.js";
 import { printFarm } from "./platform/print-farm.js";
 import { routes } from "./routes.js";
@@ -13,19 +15,24 @@ import { routes } from "./routes.js";
 // that need a caller are protected as docs/ActionMcp.md's "Protect tools" shows.
 const server = Layer.unwrap(
   Effect.gen(function* () {
-    const host = yield* Config.String("HOST").pipe(Config.withDefault("127.0.0.1"));
+    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. A tool call is a few
       // short fields, so anything larger is not one.
-      Layer.provide(Layer.succeed(HttpServerRequest.MaxBodySize, ByteSize.kibibytes(64))),
+      Layer.provide(
+        Layer.succeed(HttpServerRequest.MaxBodySize, ByteSize.kibibytes(64))
+      ),
       // DEMO ONLY: `fakeFarm` answers the farm's API in memory. A real server provides
       // `FetchHttpClient.layer` in its place, and `printFarm` calls the farm at FARM_URL.
-      Layer.provide(printFarm.pipe(Layer.provide(fakeFarm))),
+      Layer.provide(printFarm.pipe(Layer.provide(fakeFarm)))
     );
-  }),
+  })
 );
 
-Layer.launch(server).pipe(NodeRuntime.runMain);
+Layer.launch(server).pipe(NodeRuntime.runMain());

package/examples/mcp-tools/src/stdio.ts

@@ -1,7 +1,8 @@
 import { NodeRuntime, NodeStdio } from "@effect/platform-node";
-import { Effect, Layer } from "effect";
 import * as ActionCli from "@gjermundgaraba/effect-actions/ActionCli";
 import * as ActionMcp from "@gjermundgaraba/effect-actions/ActionMcp";
+import { Effect, Layer } from "effect";
+
 import { serverInfo } from "./instructions.js";
 import { fakeFarm } from "./platform/fake-farm.js";
 import { printFarm } from "./platform/print-farm.js";
@@ -22,5 +23,5 @@ ActionMcp.runStdio(printers, serverInfo).pipe(
   // stdout carries the protocol alone. Applied last, this sends every log to stderr, the
   // sign-in line `printFarm` logs included, and a startup failure too.
   ActionCli.logToStderr,
-  NodeRuntime.runMain,
+  NodeRuntime.runMain()
 );