create-nwire 0.7.0 → 0.8.0

package/templates/L4/README.md

@@ -1,8 +1,8 @@
 # {{PROJECT_NAME}}
 
 A Level 4 Nwire app — the full enterprise shape: bounded modules,
-actor-based domain, events, a stateful workflow (saga), a projection
-for read-side queries, and resolvers for the HTTP surface.
+events, actions that emit them, a stateful workflow (saga), a projection
+for read-side queries, and HTTP routes that bind them.
 
 Built around a moderation-queue example so you can see the moving
 parts before swapping in your own domain.
@@ -24,29 +24,79 @@ curl -X POST http://localhost:3000/api/posts \
 
 # read the dashboard projection
 curl http://localhost:3000/api/queue
+
+# decide a borderline one manually
+curl -X POST http://localhost:3000/api/posts/<id>/approve \
+  -H "content-type: application/json" \
+  -d '{"moderatorId":"miri"}'
+```
+
+## Test
+
+```bash
+pnpm test
 ```
 
-## Source map
+## Folder shape
 
-| File                        | What it does                                       |
-| --------------------------- | -------------------------------------------------- |
-| `main.ts`                   | Boots app + endpoint + Studio inspect              |
-| `app.ts`                    | `createApp({ modules })` — the configured runtime  |
-| `api.ts`                    | `httpInterface` + resolvers                        |
-| `events.ts`                 | `defineEvent(...)` — domain event contracts        |
-| `actions.ts`                | `defineAction(...)` — intent → event handlers      |
-| `moderation.module.ts`      | `defineModule(...)` — bounded context wiring       |
-| `auto-moderate.workflow.ts` | `defineWorkflow(...)` — saga that reacts to events |
-| `queue.projection.ts`       | `defineProjection(...)` — denormalized read model  |
+```
+{{PROJECT_NAME}}/
+├── app/
+│   ├── main.ts                              ← endpoint + app.start + run
+│   ├── api.ts                               ← httpInterface — wires every route
+│   └── app.ts                               ← createApp({ modules: [...] })
+├── modules/
+│   └── posts/                               ← bounded context: posts moderation
+│       ├── posts.module.ts                  ← defineModule — collects + exposes the BC
+│       ├── events/
+│       │   ├── post-was-submitted.ts
+│       │   ├── post-was-approved.ts
+│       │   └── post-was-rejected.ts
+│       ├── actions/
+│       │   ├── submit-post.ts
+│       │   ├── approve-post.ts
+│       │   └── reject-post.ts
+│       ├── workflows/
+│       │   └── auto-moderate.ts             ← defineWorkflow — saga shape
+│       ├── projections/
+│       │   └── queue-dashboard.ts           ← defineProjection + queries
+│       └── routes/
+│           ├── submit-post.ts               ← POST /api/posts
+│           ├── approve-post.ts              ← POST /api/posts/:postId/approve
+│           ├── reject-post.ts               ← POST /api/posts/:postId/reject
+│           ├── list-queue.ts                ← GET  /api/queue
+│           └── get-post.ts                  ← GET  /api/posts/:postId
+└── __tests__/
+    ├── submit-flow.test.ts
+    └── auto-moderate.test.ts
+```
+
+## Where to add a …
+
+| You want to add … | Where it goes                                                                       |
+| ----------------- | ----------------------------------------------------------------------------------- |
+| A new event       | `modules/<bc>/events/<noun-was-verbed>.ts` — `defineEvent`; register in module      |
+| A new action      | `modules/<bc>/actions/<verb-noun>.ts` — `defineAction({ emits, handler })`          |
+| A new workflow    | `modules/<bc>/workflows/<name>.ts` — `defineWorkflow(({ on, send }) => ...)`        |
+| A new projection  | `modules/<bc>/projections/<name>.ts` — `defineProjection` + co-located `defineQuery`|
+| A new route       | `modules/<bc>/routes/<verb-noun>.ts` exports `{name}Route + {name}Handler`; `.wire()` from `app/api.ts` |
+| A new bounded ctx | `modules/<new-bc>/` mirroring `posts/`; add to `createApp({ modules: [...] })` in `app/app.ts` |
 
 ## Studio
 
-`api.inspect(app)` mounts the `/_nwire/*` introspection surface.
-Point Studio at this app:
+`api.inspect(app)` mounts the `/_nwire/*` introspection surface. Point
+Studio at this app:
 
 ```bash
 npx -p @nwire/cli nwire studio
 ```
 
-You'll get live traces, an actor browser, projection viewer, DLQ list,
-and manual dispatch — all reading from this app.
+You'll get live traces, action / event / workflow browsers, projection
+viewer, DLQ list, and manual dispatch — all reading from this app.
+
+## Grow up
+
+When you need multi-app deployments, cross-service buses, persistent
+projection stores, durable timers, queue workers — keep this same shape
+and add the matching `@nwire/*` adapter package. Nothing in this template
+changes; the boot wires in the new adapter.

package/templates/L4/__tests__/auto-moderate.test.ts

@@ -0,0 +1,96 @@
+/**
+ * Auto-moderate workflow — exercises both decision branches:
+ *
+ *   - Clean content → auto-approved (totals.approved increments)
+ *   - Spam marker  → auto-rejected (totals.rejected increments)
+ *
+ * The workflow runs in-process (same runtime the route dispatches into),
+ * so `await idle()` between submit + dashboard read is enough to observe
+ * the post-decision state.
+ */
+
+import { describe, it, expect, beforeAll, afterAll } from "vitest";
+import http from "node:http";
+import type { Server } from "node:http";
+import { app } from "../app/app";
+import { api } from "../app/api";
+
+let server: Server;
+let url: string;
+
+beforeAll(async () => {
+  await app.start();
+  server = http.createServer(api.compile());
+  await new Promise<void>((resolve) => server.listen(0, "127.0.0.1", resolve));
+  const addr = server.address() as { port: number };
+  url = `http://127.0.0.1:${addr.port}`;
+});
+
+afterAll(async () => {
+  await new Promise<void>((resolve, reject) =>
+    server.close((err) => (err ? reject(err) : resolve())),
+  );
+  await app.stop();
+});
+
+const idle = () => new Promise<void>((resolve) => setImmediate(resolve));
+
+async function req(
+  path: string,
+  init: RequestInit = {},
+): Promise<{ status: number; body: unknown }> {
+  const res = await fetch(`${url}${path}`, {
+    ...init,
+    headers: {
+      "content-type": "application/json",
+      ...((init.headers as Record<string, string>) ?? {}),
+    },
+  });
+  const text = await res.text();
+  let body: unknown = text;
+  try {
+    body = JSON.parse(text);
+  } catch {
+    /* keep as text */
+  }
+  return { status: res.status, body };
+}
+
+async function totals(): Promise<{ pending: number; approved: number; rejected: number }> {
+  const res = await req("/api/queue");
+  return (res.body as { totals: { pending: number; approved: number; rejected: number } }).totals;
+}
+
+describe("auto-moderate workflow", () => {
+  it("auto-approves clean content end-to-end", async () => {
+    const before = await totals();
+    await req("/api/posts", {
+      method: "POST",
+      body: JSON.stringify({
+        authorId: "alice",
+        body: "Hello, this is a perfectly clean post.",
+      }),
+    });
+    await idle();
+    await idle();
+    await idle();
+    const after = await totals();
+    expect(after.approved).toBe(before.approved + 1);
+  });
+
+  it("auto-rejects content with the spam marker", async () => {
+    const before = await totals();
+    await req("/api/posts", {
+      method: "POST",
+      body: JSON.stringify({
+        authorId: "bob",
+        body: "Buy now! spam-marker free stuff!",
+      }),
+    });
+    await idle();
+    await idle();
+    await idle();
+    const after = await totals();
+    expect(after.rejected).toBe(before.rejected + 1);
+  });
+});

package/templates/L4/__tests__/submit-flow.test.ts

@@ -0,0 +1,80 @@
+/**
+ * Happy path — submit a post via HTTP, verify the action runs, the
+ * workflow + projection update the dashboard.
+ */
+
+import { describe, it, expect, beforeAll, afterAll } from "vitest";
+import http from "node:http";
+import type { Server } from "node:http";
+import { app } from "../app/app";
+import { api } from "../app/api";
+
+let server: Server;
+let url: string;
+
+beforeAll(async () => {
+  await app.start();
+  server = http.createServer(api.compile());
+  await new Promise<void>((resolve) => server.listen(0, "127.0.0.1", resolve));
+  const addr = server.address() as { port: number };
+  url = `http://127.0.0.1:${addr.port}`;
+});
+
+afterAll(async () => {
+  await new Promise<void>((resolve, reject) =>
+    server.close((err) => (err ? reject(err) : resolve())),
+  );
+  await app.stop();
+});
+
+const idle = () => new Promise<void>((resolve) => setImmediate(resolve));
+
+async function req(
+  path: string,
+  init: RequestInit = {},
+): Promise<{ status: number; body: unknown }> {
+  const res = await fetch(`${url}${path}`, {
+    ...init,
+    headers: {
+      "content-type": "application/json",
+      ...((init.headers as Record<string, string>) ?? {}),
+    },
+  });
+  const text = await res.text();
+  let body: unknown = text;
+  try {
+    body = JSON.parse(text);
+  } catch {
+    /* keep as text */
+  }
+  return { status: res.status, body };
+}
+
+describe("submit flow", () => {
+  it("accepts a submission and the dashboard reflects it", async () => {
+    const submit = await req("/api/posts", {
+      method: "POST",
+      body: JSON.stringify({ authorId: "alice", body: "hi" }), // length<5 → "human"
+    });
+    expect(submit.status).toBe(202);
+
+    await idle();
+    await idle();
+
+    const queue = await req("/api/queue");
+    const items = (queue.body as { items: Array<{ authorId: string; status: string }> }).items;
+    const alice = items.find((i) => i.authorId === "alice");
+    expect(alice).toBeDefined();
+    expect(alice?.status).toBe("pending");
+  });
+
+  it("400s on empty body (structured validation error)", async () => {
+    const res = await req("/api/posts", {
+      method: "POST",
+      body: JSON.stringify({ authorId: "alice", body: "" }),
+    });
+    expect(res.status).toBe(400);
+    const body = res.body as { error: { code: string } };
+    expect(body.error.code).toBe("validation_failed");
+  });
+});

package/templates/L4/app/api.ts

@@ -1,118 +1,28 @@
 /**
- * The HTTP interface — six routes covering submit + decide + dashboard.
+ * HTTP interface — one `.wire(Route, Handler)` per operation.
  *
- * Resolvers call into actions and queries via the forge runtime. The
- * runtime is the implicit bus — `dispatch(action, input)` runs an
- * action through the full pipeline (validation, retry, DLQ, event
- * recording, workflow notification, projection folding). `query(name,
- * input)` reads the projection's materialized state.
+ * The route + handler pairs all live in `modules/posts/routes/`. The
+ * interface stays a 1-line-per-route reducer.
  *
- * The HTTP shape is intentionally thin: translate request → action
- * input, dispatch, return a tagged response. All the orchestration
- * (auto-moderate workflow, projection updates) happens downstream of
- * the event the action emits — never inside the resolver.
- *
- * Once `createApp` is also extracted to `@nwire/app` (v1.1), these
- * resolvers will use `ctx.execute(action, input)` + `ctx.query(...)`
- * directly. For v1.0 we route through the runtime explicitly.
+ * `.provide(app.runtime.getContainer())` hands the forge runtime's
+ * container to the http layer so handlers can `resolve()` from any
+ * binding the runtime registered (e.g. dispatch, query, the runtime
+ * itself for ad-hoc reads).
  */
 
-import { httpInterface, get, post } from "@nwire/http";
-import { z } from "zod";
+import { httpInterface } from "@nwire/http";
 import { app } from "./app";
-import { submitPost, approvePost, rejectPost } from "./actions";
 
-/**
- * Tiny adapter — the resolver layer needs the runtime to dispatch
- * actions and read projections. We hand it the unwrapped runtime
- * instance from the forge app. v1.1's createApp extraction will
- * expose this through `ctx.execute()` / `ctx.query()` directly.
- */
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-const runtime = (app as any).runtime;
+import { submitPostRoute, submitPostHandler } from "../modules/posts/routes/submit-post";
+import { approvePostRoute, approvePostHandler } from "../modules/posts/routes/approve-post";
+import { rejectPostRoute, rejectPostHandler } from "../modules/posts/routes/reject-post";
+import { listQueueRoute, listQueueHandler } from "../modules/posts/routes/list-queue";
+import { getPostRoute, getPostHandler } from "../modules/posts/routes/get-post";
 
 export const api = httpInterface({ prefix: "/api" })
-  // POST /api/posts — author submits a draft for moderation
-  .wire(
-    post("/posts", {
-      body: z.object({
-        authorId: z.string(),
-        body: z.string().min(1).max(2000),
-      }),
-    }),
-    async ({ input }) => {
-      await runtime.dispatch(submitPost, input);
-      /**
-       * Return 202 — accepted, not done. The submitPost action
-       * recorded PostWasSubmitted; the auto-moderate workflow + the
-       * dashboard projection will run downstream of that. By the time
-       * the client polls GET /queue the post may already be auto-decided.
-       */
-      return { $status: 202, body: { accepted: true } };
-    },
-  )
-
-  // POST /api/posts/:postId/approve — human moderator approves
-  .wire(
-    post("/posts/:postId/approve", {
-      params: z.object({ postId: z.string() }),
-      body: z.object({ moderatorId: z.string() }),
-    }),
-    async ({ input }) => {
-      const { postId, moderatorId } = input as { postId: string; moderatorId: string };
-      await runtime.dispatch(approvePost, {
-        postId,
-        approvedBy: moderatorId,
-      });
-      return { $status: 202, body: { accepted: true } };
-    },
-  )
-
-  // POST /api/posts/:postId/reject — human moderator rejects with reason
-  .wire(
-    post("/posts/:postId/reject", {
-      params: z.object({ postId: z.string() }),
-      body: z.object({
-        moderatorId: z.string(),
-        reason: z.string().min(1).max(500),
-      }),
-    }),
-    async ({ input }) => {
-      const { postId, moderatorId, reason } = input as {
-        postId: string;
-        moderatorId: string;
-        reason: string;
-      };
-      await runtime.dispatch(rejectPost, {
-        postId,
-        rejectedBy: moderatorId,
-        reason,
-      });
-      return { $status: 202, body: { accepted: true } };
-    },
-  )
-
-  // GET /api/queue — dashboard view
-  .wire(
-    get("/queue", {
-      query: z.object({
-        limit: z.coerce.number().int().min(1).max(100).default(20),
-      }),
-    }),
-    async ({ input }) => ({
-      items: await runtime.query("moderation.list-pending", input),
-      totals: await runtime.query("moderation.queue-totals", {}),
-    }),
-  )
-
-  // GET /api/posts/:postId — single post lookup
-  .wire(
-    get("/posts/:postId", {
-      params: z.object({ postId: z.string() }),
-    }),
-    async ({ input }) => {
-      const post = await runtime.query("moderation.get-post", input);
-      if (!post) return { $status: 404, body: { error: { code: "POST_NOT_FOUND" } } };
-      return post;
-    },
-  );
+  .provide(app.runtime.getContainer())
+  .wire(submitPostRoute, submitPostHandler)
+  .wire(approvePostRoute, approvePostHandler)
+  .wire(rejectPostRoute, rejectPostHandler)
+  .wire(listQueueRoute, listQueueHandler)
+  .wire(getPostRoute, getPostHandler);

package/templates/L4/app/app.ts

@@ -1,7 +1,7 @@
 /**
- * `createApp` composes the moderation module into a runnable app.
+ * `createApp` composes the posts module into a runnable app.
  *
- * Why createApp at Level 2 (when todo-app skipped it):
+ * Why createApp at L4 (when L2 skipped it):
  *
  *   - We have a workflow that subscribes to events on the bus. The
  *     workflow needs the runtime to register its subscription and
@@ -21,8 +21,8 @@
  */
 
 import { createApp } from "@nwire/forge";
-import { moderationModule } from "./moderation.module";
+import { postsModule } from "../modules/posts/posts.module";
 
 export const app = createApp({
-  modules: [moderationModule],
+  modules: [postsModule],
 });

package/templates/L4/app/main.ts

@@ -1,20 +1,22 @@
 /**
- * Entry — boot the createApp and run the http interface under endpoint().
+ * Entry — boot the forge app and run the http interface under endpoint().
  *
- * The order matters:
+ * The lifecycle:
  *
- *   1. `app` is a configured-but-unbooted forge app — modules registered,
- *      workflow subscribers wired, projection reducers attached, but
- *      nothing's actually running yet.
+ *   1. `app` (./app.ts) is a configured-but-unbooted forge app — modules
+ *      registered, workflow subscribers wired, projection reducers
+ *      attached, but nothing's running yet.
  *   2. `app.start()` boots the runtime — workflows subscribe to the bus,
  *      projection state initializes, framework events fire.
- *   3. `endpoint().serve(api).run()` starts the HTTP listener + K8s probes.
+ *   3. `api.inspect(app)` mounts the `/_nwire/*` introspection surface
+ *      that Studio's Live + Trace pages consume.
+ *   4. `endpoint().serve(api).run()` starts the HTTP listener + K8s probes.
  *
  * Once running:
  *   - HTTP `POST /api/posts` → submitPost action → PostWasSubmitted event
- *   - autoModerate workflow picks up the event, runs auto-check, dispatches
+ *   - `autoModerate` workflow picks up the event, runs auto-check, dispatches
  *     approve/reject if obvious
- *   - queueDashboard projection picks up ALL three events, updates state
+ *   - `queueDashboard` projection picks up ALL three events, updates state
  *   - HTTP `GET /api/queue` reads from the projection
  *
  * Run:    pnpm dev
@@ -30,10 +32,7 @@ import { api } from "./api";
 
 await app.start();
 
-// `.inspect(app)` mounts the `/_nwire/*` introspection surface that
-// Studio's Live + Trace pages consume — live telemetry SSE stream,
-// actor browser, projection viewer, DLQ list, manual dispatch.
-// Off-by-default; opt in to demonstrate the dev-mode introspection.
+// Off-by-default in production; opt in here so Studio's Live page works.
 api.inspect(app);
 
 await endpoint("{{PROJECT_NAME}}", { port: 3000 }).serve(api).run();

package/templates/L4/modules/posts/actions/approve-post.ts

@@ -0,0 +1,28 @@
+/**
+ * approvePost — approve a post.
+ *
+ * Called from BOTH a human moderator route (POST /posts/:id/approve) AND
+ * from the auto-moderation workflow when the auto-check decides "clean".
+ * That reuse across callers is exactly why actions are extracted from
+ * route handlers in the first place.
+ */
+
+import { z } from "zod";
+import { defineAction } from "@nwire/forge";
+import { PostWasApproved } from "../events/post-was-approved";
+
+export const approvePost = defineAction({
+  name: "posts.approve-post",
+  description: "Approve a post — either by a human moderator or the auto-moderation workflow.",
+  schema: z.object({
+    postId: z.string(),
+    approvedBy: z.string(),
+  }),
+  emits: [PostWasApproved],
+  handler: async (input) =>
+    PostWasApproved({
+      postId: input.postId,
+      approvedBy: input.approvedBy,
+      approvedAt: new Date().toISOString(),
+    }),
+});

package/templates/L4/modules/posts/actions/reject-post.ts

@@ -0,0 +1,29 @@
+/**
+ * rejectPost — reject a post with a stated reason.
+ *
+ * Called from BOTH a human moderator route (POST /posts/:id/reject) AND
+ * from the auto-moderation workflow when the auto-check matches a known
+ * spam pattern.
+ */
+
+import { z } from "zod";
+import { defineAction } from "@nwire/forge";
+import { PostWasRejected } from "../events/post-was-rejected";
+
+export const rejectPost = defineAction({
+  name: "posts.reject-post",
+  description: "Reject a post with a stated reason.",
+  schema: z.object({
+    postId: z.string(),
+    rejectedBy: z.string(),
+    reason: z.string().min(1).max(500),
+  }),
+  emits: [PostWasRejected],
+  handler: async (input) =>
+    PostWasRejected({
+      postId: input.postId,
+      rejectedBy: input.rejectedBy,
+      reason: input.reason,
+      rejectedAt: new Date().toISOString(),
+    }),
+});

package/templates/L4/modules/posts/actions/submit-post.ts

@@ -0,0 +1,36 @@
+/**
+ * submitPost — author submits a draft to the moderation queue.
+ *
+ * Actions are the use cases the BC exposes. Each is callable from:
+ *
+ *   - A route handler (HTTP dispatch via `runtime.dispatch(action, input)`)
+ *   - A workflow (the auto-moderation workflow dispatches via `send(...)`)
+ *   - Tests (via the harness — exercises the action without booting HTTP)
+ *
+ * The action's job is to validate input and return the event(s) that
+ * describe what happened. The framework persists the events, notifies
+ * subscribed workflows, and folds them into projections. Actions don't
+ * know who's listening — that's the bus's job.
+ */
+
+import { randomUUID } from "node:crypto";
+import { z } from "zod";
+import { defineAction } from "@nwire/forge";
+import { PostWasSubmitted } from "../events/post-was-submitted";
+
+export const submitPost = defineAction({
+  name: "posts.submit-post",
+  description: "Author submits a draft to the moderation queue.",
+  schema: z.object({
+    authorId: z.string(),
+    body: z.string().min(1).max(2000),
+  }),
+  emits: [PostWasSubmitted],
+  handler: async (input) =>
+    PostWasSubmitted({
+      postId: randomUUID(),
+      authorId: input.authorId,
+      body: input.body,
+      submittedAt: new Date().toISOString(),
+    }),
+});

package/templates/L4/modules/posts/events/post-was-approved.ts

@@ -0,0 +1,22 @@
+/**
+ * PostWasApproved — a moderator (or the auto-moderation workflow) approves a post.
+ *
+ * `approvedBy` carries either a human moderator id or the literal "auto"
+ * for workflow-driven approvals — the dashboard renders the badge
+ * differently in the two cases.
+ */
+
+import { z } from "zod";
+import { defineEvent } from "@nwire/messages";
+
+export const PostWasApproved = defineEvent({
+  name: "posts.post-was-approved",
+  description: "A moderator (or the auto-moderation workflow) approves a post.",
+  outcome: "success",
+  audience: ["product", "ops"],
+  schema: z.object({
+    postId: z.string(),
+    approvedBy: z.string().describe("Moderator id, or 'auto' for workflow-driven approval"),
+    approvedAt: z.string().datetime(),
+  }),
+});

package/templates/L4/modules/posts/events/post-was-rejected.ts

@@ -0,0 +1,20 @@
+/**
+ * PostWasRejected — a moderator (or the auto-moderation workflow) rejects
+ * a post with a stated reason. The reason becomes part of the audit trail.
+ */
+
+import { z } from "zod";
+import { defineEvent } from "@nwire/messages";
+
+export const PostWasRejected = defineEvent({
+  name: "posts.post-was-rejected",
+  description: "A moderator (or the auto-moderation workflow) rejects a post.",
+  outcome: "failure",
+  audience: ["product", "ops"],
+  schema: z.object({
+    postId: z.string(),
+    rejectedBy: z.string(),
+    reason: z.string(),
+    rejectedAt: z.string().datetime(),
+  }),
+});

package/templates/L4/modules/posts/events/post-was-submitted.ts

@@ -0,0 +1,27 @@
+/**
+ * PostWasSubmitted — an author drafts a post and submits it for moderation.
+ *
+ * Past-tense by convention: events name FACTS that happened, not commands
+ * to do something. The grammar is the whole semantic: events = past,
+ * actions = present-imperative.
+ *
+ * `outcome` and `audience` are Studio-aware metadata — the scanner picks
+ * them up so the dashboard can render the event with the right semantics
+ * ("milestone", "success", "failure") and route to the right subscribers.
+ */
+
+import { z } from "zod";
+import { defineEvent } from "@nwire/messages";
+
+export const PostWasSubmitted = defineEvent({
+  name: "posts.post-was-submitted",
+  description: "An author drafts a post and submits it for moderation.",
+  outcome: "milestone",
+  audience: ["product", "ops"],
+  schema: z.object({
+    postId: z.string(),
+    authorId: z.string(),
+    body: z.string(),
+    submittedAt: z.string().datetime(),
+  }),
+});