create-nwire 0.12.1 → 0.13.0

package/templates/enterprise/modules/posts/routes/approve-post.ts

@@ -7,7 +7,7 @@
  */
 
 import { post } from "@nwire/wires/http";
-import type { ForgeDispatcher } from "@nwire/forge";
+import { FORGE_ACTION_RUNNER_BINDING, type ActionRunner } from "@nwire/forge";
 import { z } from "zod";
 import { approvePost } from "../actions/approve-post";
 
@@ -21,8 +21,8 @@ export const approvePostHandler = async (
   input: Input,
   ctx: { resolve: <T>(name: string) => T },
 ) => {
-  const dispatcher = ctx.resolve<ForgeDispatcher>("forge.dispatcher");
-  await dispatcher.dispatch(approvePost, {
+  const actions = ctx.resolve<ActionRunner>(FORGE_ACTION_RUNNER_BINDING);
+  await actions.dispatch(approvePost, {
     postId: input.postId,
     approvedBy: input.moderatorId,
   });

package/templates/enterprise/modules/posts/routes/get-post.ts

@@ -6,7 +6,7 @@
  */
 
 import { get } from "@nwire/wires/http";
-import type { ForgeDispatcher } from "@nwire/forge";
+import { FORGE_QUERY_RUNNER_BINDING, type QueryRunner } from "@nwire/forge";
 import { z } from "zod";
 
 const Params = z.object({ postId: z.string() });
@@ -17,8 +17,8 @@ export const getPostHandler = async (
   input: z.infer<typeof Params>,
   ctx: { resolve: <T>(name: string) => T },
 ) => {
-  const dispatcher = ctx.resolve<ForgeDispatcher>("forge.dispatcher");
-  const post = await dispatcher.query("posts.get-post", input);
+  const queries = ctx.resolve<QueryRunner>(FORGE_QUERY_RUNNER_BINDING);
+  const post = await queries.run("posts.get-post", input);
   if (!post) return { $status: 404, body: { error: { code: "POST_NOT_FOUND" } } };
   return post;
 };

package/templates/enterprise/modules/posts/routes/list-queue.ts

@@ -7,7 +7,7 @@
  */
 
 import { get } from "@nwire/wires/http";
-import type { ForgeDispatcher } from "@nwire/forge";
+import { FORGE_QUERY_RUNNER_BINDING, type QueryRunner } from "@nwire/forge";
 import { z } from "zod";
 
 const Query = z.object({
@@ -20,9 +20,9 @@ export const listQueueHandler = async (
   input: z.infer<typeof Query>,
   ctx: { resolve: <T>(name: string) => T },
 ) => {
-  const dispatcher = ctx.resolve<ForgeDispatcher>("forge.dispatcher");
+  const queries = ctx.resolve<QueryRunner>(FORGE_QUERY_RUNNER_BINDING);
   return {
-    items: await dispatcher.query("posts.list-pending", input),
-    totals: await dispatcher.query("posts.queue-totals", {}),
+    items: await queries.run("posts.list-pending", input),
+    totals: await queries.run("posts.queue-totals", {}),
   };
 };

package/templates/enterprise/modules/posts/routes/posts-by-author.ts

@@ -0,0 +1,28 @@
+/**
+ * GET /api/posts/by-author — all posts an author has submitted, across statuses.
+ *
+ * Demonstrates the handler-form query: `postsByAuthor` has no projection
+ * backing — it reads directly from a DB (or a mock) via `QueryContext`.
+ * Swap the mock in `queries/posts-by-author.ts` for a real DB call when
+ * you connect a store.
+ */
+
+import { get } from "@nwire/wires/http";
+import { FORGE_QUERY_RUNNER_BINDING, type QueryRunner } from "@nwire/forge";
+import { z } from "zod";
+
+const Query = z.object({
+  authorId: z.string(),
+  limit: z.coerce.number().int().min(1).max(100).default(20),
+});
+
+export const postsByAuthorRoute = get("/posts/by-author", { query: Query });
+
+export const postsByAuthorHandler = async (
+  input: z.infer<typeof Query>,
+  ctx: { resolve: <T>(name: string) => T },
+) => {
+  const queries = ctx.resolve<QueryRunner>(FORGE_QUERY_RUNNER_BINDING);
+  const posts = await queries.run("posts.by-author", input);
+  return { items: posts, total: (posts as unknown[]).length };
+};

package/templates/enterprise/modules/posts/routes/reject-post.ts

@@ -6,7 +6,7 @@
  */
 
 import { post } from "@nwire/wires/http";
-import type { ForgeDispatcher } from "@nwire/forge";
+import { FORGE_ACTION_RUNNER_BINDING, type ActionRunner } from "@nwire/forge";
 import { z } from "zod";
 import { rejectPost } from "../actions/reject-post";
 
@@ -20,8 +20,8 @@ type Input = z.infer<typeof Params> & z.infer<typeof Body>;
 export const rejectPostRoute = post("/posts/:postId/reject", { params: Params, body: Body });
 
 export const rejectPostHandler = async (input: Input, ctx: { resolve: <T>(name: string) => T }) => {
-  const dispatcher = ctx.resolve<ForgeDispatcher>("forge.dispatcher");
-  await dispatcher.dispatch(rejectPost, {
+  const actions = ctx.resolve<ActionRunner>(FORGE_ACTION_RUNNER_BINDING);
+  await actions.dispatch(rejectPost, {
     postId: input.postId,
     rejectedBy: input.moderatorId,
     reason: input.reason,

package/templates/enterprise/modules/posts/routes/submit-post.ts

@@ -7,7 +7,7 @@
  */
 
 import { post } from "@nwire/wires/http";
-import type { ForgeDispatcher } from "@nwire/forge";
+import { FORGE_ACTION_RUNNER_BINDING, type ActionRunner } from "@nwire/forge";
 import { z } from "zod";
 import { submitPost } from "../actions/submit-post";
 
@@ -22,7 +22,7 @@ export const submitPostHandler = async (
   input: z.infer<typeof Body>,
   ctx: { resolve: <T>(name: string) => T },
 ) => {
-  const dispatcher = ctx.resolve<ForgeDispatcher>("forge.dispatcher");
-  await dispatcher.dispatch(submitPost, input);
+  const actions = ctx.resolve<ActionRunner>(FORGE_ACTION_RUNNER_BINDING);
+  await actions.dispatch(submitPost, input);
   return { $status: 202, body: { accepted: true } };
 };

package/templates/enterprise/modules/posts/workflows/auto-moderate.ts

@@ -3,7 +3,7 @@
  * submitted post and decides whether to bypass the human queue.
  *
  * Pattern: workflows are subscribers — they react to events with the
- * same `on(Event, handler)` shape projections use. The difference is
+ * same `when(Event, handler)` shape projections use. The difference is
  * what they DO with the event:
  *
  *   - Workflows produce SIDE EFFECTS — dispatch more actions, send
@@ -47,8 +47,8 @@ function autoCheck(body: string): "approve" | { reject: string } | "human" {
   return "approve";
 }
 
-export const autoModerate = defineWorkflow("auto-moderate", ({ on, send }) => {
-  on(PostWasSubmitted, async (event) => {
+export const autoModerate = defineWorkflow("auto-moderate", ({ when, send }) => {
+  when(PostWasSubmitted, async (event) => {
     const decision = autoCheck(event.body);
 
     if (decision === "approve") {

package/templates/enterprise/package.json

@@ -4,27 +4,26 @@
   "private": true,
   "type": "module",
   "scripts": {
-    "dev": "vite-node app/main.ts",
+    "dev": "nwire dev",
     "test": "vitest run",
     "doctor": "nwire doctor",
     "studio": "nwire studio",
     "cache": "nwire cache"
   },
   "dependencies": {
-    "@nwire/app": "^0.12.1",
-    "@nwire/endpoint": "^0.12.1",
-    "@nwire/forge": "^0.12.1",
-    "@nwire/koa": "^0.12.1",
-    "@nwire/messages": "^0.12.1",
-    "@nwire/wires": "^0.12.1",
+    "@nwire/app": "^0.13.0",
+    "@nwire/endpoint": "^0.13.0",
+    "@nwire/forge": "^0.13.0",
+    "@nwire/koa": "^0.13.0",
+    "@nwire/messages": "^0.13.0",
+    "@nwire/wires": "^0.13.0",
     "zod": "^4.0.0"
   },
   "devDependencies": {
-    "@nwire/test-kit": "^0.12.1",
+    "@nwire/cli": "^0.13.0",
+    "@nwire/test-kit": "^0.13.0",
     "@types/node": "^22.19.9",
     "typescript": "^5.9.0",
-    "vite-node": "^3.2.4",
-    "vitest": "^4.0.18",
-    "@nwire/cli": "^0.12.1"
+    "vitest": "^4.0.18"
   }
 }

package/templates/enterprise/tsconfig.json

@@ -11,5 +11,5 @@
     "noEmit": true,
     "types": ["node"]
   },
-  "include": ["app/**/*", "modules/**/*", "__tests__/**/*"]
+  "include": ["app/**/*", "config/**/*", "modules/**/*", "__tests__/**/*"]
 }

package/templates/mcp/AGENTS.md

@@ -0,0 +1,73 @@
+# AGENTS.md — working in this nwire MCP server
+
+This is a **nwire** backend wired as an MCP (Model Context Protocol) server.
+AI clients (Claude, Cursor, IDE plugins) connect over stdio and call the
+tools you define here. The server speaks JSON-RPC 2.0.
+
+## The shape
+
+```ts
+import { tool } from "@nwire/wires/mcp";
+import { z } from "zod";
+
+// A binding declares the tool name + input schema.
+const myTool = tool("my-tool", {
+  description: "What this tool does in plain language.",
+  input: z.object({ value: z.string() }),
+});
+
+// A handler is a plain async function.
+const myHandler = async (input: { value: string }) => ({ result: input.value });
+
+// Wire them in app/tools.ts and app.ts picks them up.
+```
+
+`app/main.ts` boots the server (stdio loop + nwire endpoint).
+Tools live in `app/tools/`, the store in `app/store/`.
+
+## stdout is the JSON-RPC channel
+
+**Never write to stdout from tool handlers or any module they import.**
+Any non-JSON byte on stdout corrupts the MCP framing and breaks the client.
+
+- Log with: `console.error(...)` or `process.stderr.write(...)`
+- Never use: `console.log(...)` inside tools
+
+## Import map — DO NOT GUESS THESE
+
+| Primitive                                        | Package            |
+| ------------------------------------------------ | ------------------ |
+| `createApp`, `definePlugin`                      | `@nwire/app`       |
+| `endpoint`                                       | `@nwire/endpoint`  |
+| `tool`                                           | `@nwire/wires/mcp` |
+| `mcpAdapter`                                     | `@nwire/mcp`       |
+| `defineHandler`, `defineResource`, `defineError` | `@nwire/handler`   |
+
+## Adding a tool
+
+1. Create `app/tools/<verb>-<noun>.ts` — export a `{name}Tool` binding and
+   `{name}Handler` function.
+2. Add it to `app/tools.ts`.
+3. Wire it in `app/app.ts` (already done via the `tools` array).
+
+## Commands
+
+- `pnpm start` — run the MCP server on stdio.
+- `pnpm dev` — same, with file-watching restart.
+- `pnpm test` — run the test suite (in-process + stdio integration).
+- `pnpm typecheck` — TypeScript check.
+
+## Connecting to Claude Desktop
+
+Add this to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "{{PROJECT_NAME}}": {
+      "command": "node",
+      "args": ["--import", "tsx/esm", "/absolute/path/to/app/main.ts"]
+    }
+  }
+}
+```

package/templates/mcp/__tests__/mcp-server.test.ts

@@ -0,0 +1,205 @@
+/**
+ * MCP server stdio test — drives the server the same way Claude / Cursor
+ * will: spawn the entry process, feed newline-framed JSON-RPC over stdin,
+ * assert responses on stdout.
+ *
+ * Protocol order:
+ *   initialize → (no response to notifications/initialized) → tools/list
+ *   → tools/call
+ *
+ * The test also exercises the adapter in-process (without spawning) to keep
+ * the unit path fast and to make assertion failures easy to debug.
+ */
+
+import { describe, it, expect, beforeAll, afterAll } from "vitest";
+import { spawn, type ChildProcess } from "node:child_process";
+import { endpoint } from "@nwire/endpoint";
+import { mcpAdapter } from "@nwire/mcp";
+import { app } from "../app/app";
+
+// ─── In-process adapter tests ────────────────────────────────────────
+
+let running: Awaited<ReturnType<ReturnType<typeof endpoint>["run"]>>;
+let mcp: ReturnType<typeof mcpAdapter>;
+
+beforeAll(async () => {
+  mcp = mcpAdapter();
+  running = await endpoint("{{PROJECT_NAME}}-test", {
+    exitOnShutdown: false,
+    banner: false,
+    probes: { enabled: false },
+  })
+    .use(mcp)
+    .mount(app)
+    .run();
+});
+
+afterAll(async () => {
+  await running.shutdown("test");
+  await app.stop();
+});
+
+describe("MCP adapter — in-process", () => {
+  it("lists the three registered tools", () => {
+    const names = mcp
+      .list()
+      .map((t) => t.name)
+      .sort();
+    expect(names).toEqual(["add-fact", "list-facts", "lookup-fact"]);
+  });
+
+  it("list-facts returns the seed entries", async () => {
+    const result = (await mcp.call("list-facts", {})) as { count: number; facts: unknown[] };
+    expect(result.count).toBeGreaterThanOrEqual(2);
+  });
+
+  it("add-fact stores a new entry", async () => {
+    const result = (await mcp.call("add-fact", {
+      topic: "test-topic",
+      body: "written by the test suite",
+    })) as { stored: { topic: string }; total: number };
+    expect(result.stored.topic).toBe("test-topic");
+    expect(result.total).toBeGreaterThan(2);
+  });
+
+  it("lookup-fact finds stored entries by keyword", async () => {
+    const result = (await mcp.call("lookup-fact", { query: "nwire" })) as {
+      count: number;
+      results: unknown[];
+    };
+    expect(result.count).toBeGreaterThanOrEqual(1);
+  });
+
+  it("lookup-fact returns empty results for an unknown term", async () => {
+    const result = (await mcp.call("lookup-fact", { query: "xyzzy-not-a-thing" })) as {
+      count: number;
+    };
+    expect(result.count).toBe(0);
+  });
+});
+
+// ─── Stdio integration — spawn the real entry ────────────────────────
+
+/**
+ * A minimal client harness that speaks newline-delimited JSON-RPC over
+ * a spawned child process's stdio. Mirrors the shape used in
+ * `packages/nwire-mcp/src/__tests__/mcp-io.test.ts`.
+ */
+class StdioClient {
+  private readonly child: ChildProcess;
+  private buffer = "";
+  private pending = new Map<number, (value: unknown) => void>();
+  private id = 0;
+
+  constructor(entryPath: string) {
+    this.child = spawn("node", ["--import", "tsx/esm", entryPath], {
+      stdio: ["pipe", "pipe", "pipe"],
+      env: { ...process.env, NODE_ENV: "test" },
+    });
+
+    this.child.stdout!.setEncoding("utf8");
+    this.child.stdout!.on("data", (chunk: string) => {
+      this.buffer += chunk;
+      const lines = this.buffer.split("\n");
+      this.buffer = lines.pop() ?? "";
+      for (const line of lines) {
+        if (!line.trim()) continue;
+        try {
+          const msg = JSON.parse(line) as { id?: number };
+          if (msg.id != null && this.pending.has(msg.id)) {
+            this.pending.get(msg.id)!(msg);
+            this.pending.delete(msg.id);
+          }
+        } catch {
+          // Non-JSON on stdout is a bug — surface it for debugging.
+          process.stderr.write(`[test] non-JSON on stdout: ${line}\n`);
+        }
+      }
+    });
+  }
+
+  request(method: string, params?: Record<string, unknown>): Promise<unknown> {
+    const id = ++this.id;
+    const promise = new Promise<unknown>((resolve) => {
+      this.pending.set(id, resolve);
+    });
+    this.child.stdin!.write(JSON.stringify({ jsonrpc: "2.0", id, method, params }) + "\n");
+    return promise;
+  }
+
+  notify(method: string, params?: Record<string, unknown>): void {
+    this.child.stdin!.write(JSON.stringify({ jsonrpc: "2.0", method, params }) + "\n");
+  }
+
+  close(): void {
+    this.child.stdin!.end();
+  }
+}
+
+describe("MCP server — stdio JSON-RPC", () => {
+  let client: StdioClient;
+
+  beforeAll(() => {
+    // Resolve relative to this test file at runtime.
+    const entry = new URL("../app/main.ts", import.meta.url).pathname;
+    client = new StdioClient(entry);
+  });
+
+  afterAll(() => {
+    client.close();
+  });
+
+  it("initialize returns the protocol version and server info", async () => {
+    const res = (await client.request("initialize", {
+      protocolVersion: "2024-11-05",
+      capabilities: {},
+    })) as { result: { protocolVersion: string; serverInfo: { name: string } } };
+    expect(res.result.protocolVersion).toBe("2024-11-05");
+    expect(res.result.serverInfo.name).toBe("{{PROJECT_NAME}}");
+    // Confirm: the MCP lifecycle notification must not block future requests.
+    client.notify("notifications/initialized");
+  });
+
+  it("tools/list returns all registered tools", async () => {
+    const res = (await client.request("tools/list")) as {
+      result: { tools: Array<{ name: string }> };
+    };
+    const names = res.result.tools.map((t) => t.name).sort();
+    expect(names).toContain("lookup-fact");
+    expect(names).toContain("add-fact");
+    expect(names).toContain("list-facts");
+  });
+
+  it("tools/call list-facts returns the seeded knowledge base", async () => {
+    const res = (await client.request("tools/call", {
+      name: "list-facts",
+      arguments: {},
+    })) as { result: { content: Array<{ type: string; text: string }>; isError: boolean } };
+    expect(res.result.isError).toBe(false);
+    const body = JSON.parse(res.result.content[0].text) as { count: number };
+    expect(body.count).toBeGreaterThanOrEqual(2);
+  });
+
+  it("tools/call lookup-fact finds a seeded entry", async () => {
+    const res = (await client.request("tools/call", {
+      name: "lookup-fact",
+      arguments: { query: "mcp" },
+    })) as { result: { content: Array<{ type: string; text: string }>; isError: boolean } };
+    expect(res.result.isError).toBe(false);
+    const body = JSON.parse(res.result.content[0].text) as { count: number };
+    expect(body.count).toBeGreaterThanOrEqual(1);
+  });
+
+  it("tools/call for an unknown tool responds with isError", async () => {
+    const res = (await client.request("tools/call", {
+      name: "nonexistent-tool",
+      arguments: {},
+    })) as {
+      result?: { isError: boolean; content: Array<{ text: string }> };
+      error?: { code: number };
+    };
+    // The server surfaces unknown-tool as an isError content response (not a JSON-RPC error).
+    const isErrorResult = res.result?.isError === true || res.error != null;
+    expect(isErrorResult).toBe(true);
+  });
+});

package/templates/mcp/_gitignore

@@ -0,0 +1,5 @@
+node_modules/
+dist/
+.nwire/
+*.log
+.DS_Store

package/templates/mcp/_npmrc

@@ -0,0 +1,4 @@
+# nwire dev runs via vite-node (esbuild). pnpm 11 defers esbuild's build
+# script and then fails the pre-run deps check; skip that check so
+# `pnpm dev` runs clean right after install.
+verify-deps-before-run=false

package/templates/mcp/_pnpm-workspace.yaml

@@ -0,0 +1,6 @@
+# pnpm 11 reads build-allow + run settings here (not the package.json
+# "pnpm" field). esbuild backs vite-node; allow its build, and skip the
+# pre-run deps check so `pnpm dev` runs clean right after install.
+onlyBuiltDependencies:
+  - esbuild
+verifyDepsBeforeRun: false

package/templates/mcp/app/app.ts

@@ -0,0 +1,24 @@
+/**
+ * App — the composition root.
+ *
+ * `createApp` constructs the container and wires all MCP tools in this
+ * module body. The exported `app` is COMPLETE on import — no caller needs
+ * to wire or start it. No ports are bound here; that is `main.ts`'s job.
+ *
+ * Tests import `{ app }` from this file and drive it with `mcpAdapter()`
+ * directly — never import `main.ts` from tests, it owns the stdio loop
+ * and will hang the runner.
+ *
+ * Graduate: add `@nwire/mongo` or `@nwire/drizzle` as a plugin here when
+ * the in-memory store outgrows its welcome. The tool handlers keep calling
+ * `ctx.resolve("db")`; nothing else changes.
+ */
+
+import { createApp } from "@nwire/app";
+import { tools } from "./tools";
+
+export const app = createApp({ appName: "{{PROJECT_NAME}}" });
+
+for (const { binding, handler } of tools) {
+  app.wire(binding, handler);
+}