@emseepea/create-progress-streaming-server 0.0.12 → 0.0.14

package/README.md

@@ -7,7 +7,7 @@ This directory is both the maintained example and its public npm initializer.
 Use this template for a tool that reports bounded progress while its HTTP call
 remains open. Choose the [tool server](../tool-server/README.md) when the result
 can return promptly. This template does not add replay, reconnectable sessions,
-or subscriptions. [Compare all eight templates](https://emseepea.github.io/emseepea/examples/).
+or subscriptions. [Compare all templates](https://emseepea.github.io/emseepea/examples/).
 
 ## Create a Project
 
@@ -17,6 +17,30 @@ npm init @emseepea/progress-streaming-server -- my-server
 
 <!-- generated-project-readme -->
 
+## Choose Open or Protected Access
+
+Start open when the catalogue and operations are public.
+
+To protect this template, pass both options to the app factory:
+
+- `access: { access: "protected", requiredScopes: ["peas:read"] }`
+- an `authentication` adapter
+
+Keep `authentication.discovery` as `"public"` unless capability names or
+schemas are sensitive. Use `"protected"` only when each principal should see a
+permission-filtered catalogue. OAuth metadata remains public in both modes.
+
+## Add Observability
+
+The same factory accepts `observability`.
+
+- Use `structuredLogging` for safe structured events.
+- Use `openTelemetry` for traces and metrics.
+
+Adapters receive only redacted framework events. They never receive request
+bodies, arguments, results, tokens, provider claims, or raw errors. See the
+[server API](https://github.com/emseepea/emseepea/tree/main/packages/framework#authentication-and-observability) for the complete configuration.
+
 ## Streaming Progress Example
 
 Choose this example when a tool takes long enough that people benefit from

package/initializer-dist/template/README.md

@@ -1,4 +1,28 @@
-# Streaming Progress Example
+# Choose Open or Protected Access
+
+Start open when the catalogue and operations are public.
+
+To protect this template, pass both options to the app factory:
+
+- `access: { access: "protected", requiredScopes: ["peas:read"] }`
+- an `authentication` adapter
+
+Keep `authentication.discovery` as `"public"` unless capability names or
+schemas are sensitive. Use `"protected"` only when each principal should see a
+permission-filtered catalogue. OAuth metadata remains public in both modes.
+
+## Add Observability
+
+The same factory accepts `observability`.
+
+- Use `structuredLogging` for safe structured events.
+- Use `openTelemetry` for traces and metrics.
+
+Adapters receive only redacted framework events. They never receive request
+bodies, arguments, results, tokens, provider claims, or raw errors. See the
+[server API](https://github.com/emseepea/emseepea/tree/main/packages/framework#authentication-and-observability) for the complete configuration.
+
+## Streaming Progress Example
 
 Choose this example when a tool takes long enough that people benefit from
 seeing progress before the final answer.

package/initializer-dist/template/package.json

@@ -14,7 +14,7 @@
     "lint": "oxlint src test eval"
   },
   "devDependencies": {
-    "@emseepea/testing": "0.5.2",
+    "@emseepea/testing": "0.6.1",
     "@types/node": "24.13.3",
     "typescript": "6.0.3",
     "oxlint": "1.80.0"
@@ -24,7 +24,7 @@
   },
   "private": true,
   "dependencies": {
-    "@emseepea/server": "0.3.3",
+    "@emseepea/server": "0.4.0",
     "zod": "4.4.3"
   }
 }

package/initializer-dist/template/src/app.ts

@@ -0,0 +1,21 @@
+import {
+  createEmseepea,
+  discoverCapabilities,
+  type AccessPolicy,
+  type EmseepeaExtensions,
+} from "@emseepea/server";
+
+export interface ProgressStreamingServerOptions extends EmseepeaExtensions {
+  readonly access?: AccessPolicy;
+}
+
+export async function createProgressStreamingServer(options: ProgressStreamingServerOptions = {}) {
+  const { access = { access: "public" }, ...extensions } = options;
+  return createEmseepea({
+    name: "emseepea-progress-streaming-server",
+    version: "0.0.0",
+    instructions: "Use run-germination-trial for the sample pea germination trial.",
+    ...await discoverCapabilities(new URL("./capabilities/", import.meta.url), access),
+    ...extensions,
+  });
+}

package/initializer-dist/template/src/capabilities/tool.run-germination-trial.ts

@@ -1,10 +1,15 @@
 import { setTimeout as delay } from "node:timers/promises";
-import { defineStreamingTool, type CapabilityModuleFactory } from "@emseepea/server";
+import {
+  defineStreamingTool,
+  type AccessPolicy,
+  type CapabilityModuleFactory,
+  type StreamingToolContext,
+} from "@emseepea/server";
 import { z } from "zod";
 
-export default (() => defineStreamingTool({
+export default ((access) => defineStreamingTool({
   name: "run-germination-trial",
-  access: "public",
+  ...access,
   description: "Run a sample pea germination trial with bounded progress.",
   inputSchema: z.object({
     tray: z.literal("sample-tray").describe("Sample germination tray to test."),
@@ -17,7 +22,7 @@ export default (() => defineStreamingTool({
     stages: z.tuple([z.literal("soak"), z.literal("sow"), z.literal("sprout")])
       .describe("Trial stages completed in order."),
   }),
-  async handler({ tray }, { reportProgress, signal }) {
+  async handler({ tray }, { reportProgress, signal }: StreamingToolContext) {
     const stages: ["soak", "sow", "sprout"] = ["soak", "sow", "sprout"];
     for (const [index, stage] of stages.entries()) {
       await reportProgress({ progress: index + 1, total: stages.length, message: stage });
@@ -26,4 +31,4 @@ export default (() => defineStreamingTool({
     const data = { tray, status: "complete" as const, germinatedSeeds: 8 as const, totalSeeds: 10 as const, stages };
     return { data };
   },
-})) satisfies CapabilityModuleFactory;
+})) satisfies CapabilityModuleFactory<AccessPolicy>;

package/initializer-dist/template/src/server.ts

@@ -1,11 +1,9 @@
-import { createEmseepea, discoverCapabilities, serveEmseepea } from "@emseepea/server";
+import { serveEmseepea } from "@emseepea/server";
+import { createProgressStreamingServer } from "./app.js";
 
-const running = await serveEmseepea(createEmseepea({
-  name: "emseepea-progress-streaming-server",
-  version: "0.0.0",
-  instructions: "Use run-germination-trial for the sample pea germination trial.",
-  ...await discoverCapabilities(new URL("./capabilities/", import.meta.url)),
-}), { port: Number.parseInt(process.env.PORT ?? "3000", 10) });
+const running = await serveEmseepea(await createProgressStreamingServer(), {
+  port: Number.parseInt(process.env.PORT ?? "3000", 10),
+});
 
 console.log(`Em See Pea progress-streaming-server example listening at ${running.url}`);
 

package/initializer-dist/template/test/server.test.mjs

@@ -1,7 +1,12 @@
 import assert from "node:assert/strict";
 import test from "node:test";
 
-import { startMcpServer } from "@emseepea/testing";
+import {
+  insecureTestAuthentication,
+  startEmseepea,
+  startMcpServer,
+} from "@emseepea/testing";
+import { createProgressStreamingServer } from "../dist/app.js";
 
 test("reports bounded progress before returning the final germination result", async (t) => {
   const running = await startMcpServer(t, new URL("../dist/server.js", import.meta.url));
@@ -29,3 +34,20 @@ test("reports bounded progress before returning the final germination result", a
   });
   assert.equal(result.content[0].text, JSON.stringify(result.structuredContent));
 });
+
+test("the same template composes protected access and observability", async (t) => {
+  const events = [];
+  const permissions = ["trials:run"];
+  const running = await startEmseepea(t, await createProgressStreamingServer({
+    access: { access: "protected", requiredScopes: permissions },
+    authentication: insecureTestAuthentication(permissions),
+    observability: [{ id: "test-log", emit: (event) => events.push(event) }],
+  }));
+  const client = await running.connect("test-token");
+  const result = await client.callTool({
+    name: "run-germination-trial",
+    arguments: { tray: "sample-tray" },
+  });
+  assert.equal(result.structuredContent.status, "complete");
+  assert.ok(events.some(({ capability }) => capability === "run-germination-trial"));
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@emseepea/create-progress-streaming-server",
-  "version": "0.0.12",
+  "version": "0.0.14",
   "description": "Create an Em See Pea server that streams tool progress.",
   "license": "MIT",
   "type": "module",
@@ -18,9 +18,9 @@
     "prepack": "npm run build:initializer"
   },
   "devDependencies": {
-    "@emseepea/server": "0.3.3",
+    "@emseepea/server": "0.4.0",
     "zod": "4.4.3",
-    "@emseepea/testing": "0.5.2",
+    "@emseepea/testing": "0.6.1",
     "@types/node": "24.13.3",
     "typescript": "6.0.3",
     "oxlint": "1.80.0"