create-nwire 0.7.1 → 0.8.0

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(),
+  }),
+});

package/templates/L4/modules/posts/posts.module.ts

@@ -0,0 +1,35 @@
+/**
+ * The posts module — collects every domain piece for this bounded
+ * context. `defineModule` is purely organizational: it groups events,
+ * actions, workflows, projections, and queries that belong to one part
+ * of the business, marks which are public (callable from other modules /
+ * apps), and gives the runtime a single value to register.
+ *
+ * `.public()` controls cross-module visibility. Here every action +
+ * query is public because we have one module; in a multi-module app
+ * you'd be more selective — only what's part of the BC's contract
+ * stays public.
+ */
+
+import { defineModule } from "@nwire/forge";
+
+import { PostWasSubmitted } from "./events/post-was-submitted";
+import { PostWasApproved } from "./events/post-was-approved";
+import { PostWasRejected } from "./events/post-was-rejected";
+
+import { submitPost } from "./actions/submit-post";
+import { approvePost } from "./actions/approve-post";
+import { rejectPost } from "./actions/reject-post";
+
+import { autoModerate } from "./workflows/auto-moderate";
+
+import { queueDashboard, listPending, queueTotals, getPost } from "./projections/queue-dashboard";
+
+export const postsModule = defineModule("posts", {
+  description: "Post moderation queue — submit, auto-check, decide, dashboard.",
+  events: [PostWasSubmitted, PostWasApproved, PostWasRejected],
+  actions: [submitPost.public(), approvePost.public(), rejectPost.public()],
+  workflows: [autoModerate],
+  projections: [queueDashboard],
+  queries: [listPending.public(), queueTotals.public(), getPost.public()],
+});

package/templates/L4/{app/queue.projection.ts → modules/posts/projections/queue-dashboard.ts}

@@ -1,11 +1,11 @@
 /**
- * `queueDashboard` projection — the read model for the moderation queue.
+ * queueDashboard — the read model for the moderation queue.
  *
- * NOTICE THE SYMMETRY:
+ * NOTE THE SYMMETRY:
  *
- *   - The autoModerate WORKFLOW (./auto-moderate.workflow.ts) subscribes
- *     to events via `on(PostWasSubmitted, (event) => ...)`. Its job is
- *     to produce SIDE EFFECTS — dispatch more actions.
+ *   - The autoModerate WORKFLOW subscribes to events via
+ *     `on(PostWasSubmitted, (event) => ...)`. Its job is to produce SIDE
+ *     EFFECTS — dispatch more actions.
  *
  *   - This PROJECTION subscribes to events via the same `on` map shape.
  *     Its job is to fold events into a denormalized state that queries
@@ -15,32 +15,25 @@
  * intent. If you understand workflows, you understand projections —
  * just write to state instead of dispatching.
  *
- * ## Why a projection vs. computing on every read
- *
- * The HTTP `GET /queue?status=pending` could query the event log + fold
- * matching events on every request. That works for low traffic. For a
- * busy moderation dashboard with thousands of moderators each polling
- * every 5 seconds, that's wasted CPU.
- *
- * The projection folds incrementally: every time an event fires, it
- * updates the state. Queries read the materialized state directly.
- * Trade-off: more memory, less CPU; eventually-consistent (the
- * projection lags the event by milliseconds at worst). For dashboards
- * that's the right trade.
- *
  * ## When this lives in a database
  *
  * The in-memory state here is for example clarity. In production the
  * projection's `on` reducers would write to Postgres / Mongo / Redis,
  * and the query would read from there. The PRIMITIVE is the same —
  * `on(Event) → mutate state`. Where state lives is a deployment choice.
+ *
+ * Queries (`listPending`, `queueTotals`, `getPost`) live in this file
+ * too because they're tightly coupled to the projection's state shape.
+ * Split them out if/when queries grow beyond the projection's surface.
  */
 
 import { defineProjection, defineQuery } from "@nwire/forge";
 import { z } from "zod";
-import { PostWasSubmitted, PostWasApproved, PostWasRejected } from "./events";
+import { PostWasSubmitted } from "../events/post-was-submitted";
+import { PostWasApproved } from "../events/post-was-approved";
+import { PostWasRejected } from "../events/post-was-rejected";
 
-// ─── The projection state shape ────────────────────────────────
+// ─── State shape ─────────────────────────────────────────────────
 
 interface QueueItem {
   postId: string;
@@ -59,7 +52,7 @@ interface QueueState {
   totals: { pending: number; approved: number; rejected: number };
 }
 
-// ─── The projection — note the `on` map matches the workflow's ───
+// ─── Projection — `on` map matches the workflow's shape ─────────
 
 export const queueDashboard = defineProjection<QueueState>("queue-dashboard", {
   description: "The moderation dashboard read model — pending queue + decision totals.",
@@ -70,11 +63,6 @@ export const queueDashboard = defineProjection<QueueState>("queue-dashboard", {
     totals: { pending: 0, approved: 0, rejected: 0 },
   }),
   on: {
-    /**
-     * Same shape as a workflow's `on(PostWasSubmitted, ...)`. The
-     * difference: this returns state, the workflow returns void
-     * (and produces side effects).
-     */
     [PostWasSubmitted.name]: (state, event) => ({
       byId: {
         ...state.byId,
@@ -137,10 +125,10 @@ export const queueDashboard = defineProjection<QueueState>("queue-dashboard", {
   },
 });
 
-// ─── Queries — read the projection's state ─────────────────────
+// ─── Queries — read the projection's state ──────────────────────
 
 export const listPending = defineQuery(queueDashboard, {
-  name: "moderation.list-pending",
+  name: "posts.list-pending",
   schema: z.object({ limit: z.coerce.number().int().min(1).max(100).default(20) }),
   execute: (state, { limit }) =>
     state.pendingIds
@@ -150,13 +138,13 @@ export const listPending = defineQuery(queueDashboard, {
 });
 
 export const queueTotals = defineQuery(queueDashboard, {
-  name: "moderation.queue-totals",
+  name: "posts.queue-totals",
   schema: z.object({}),
   execute: (state) => state.totals,
 });
 
 export const getPost = defineQuery(queueDashboard, {
-  name: "moderation.get-post",
+  name: "posts.get-post",
   schema: z.object({ postId: z.string() }),
   execute: (state, { postId }) => state.byId[postId] ?? null,
 });

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

@@ -0,0 +1,26 @@
+/**
+ * POST /api/posts/:postId/approve — human moderator approves a post.
+ *
+ * Dispatches the SAME action that the auto-moderate workflow dispatches
+ * — that reuse is exactly why approvePost lives in `actions/` and not
+ * inline in the route handler.
+ */
+
+import { post, type HttpHandler } from "@nwire/http";
+import { z } from "zod";
+import { app } from "../../../app/app";
+import { approvePost } from "../actions/approve-post";
+
+const Params = z.object({ postId: z.string() });
+const Body = z.object({ moderatorId: z.string() });
+type Input = z.infer<typeof Params> & z.infer<typeof Body>;
+
+export const approvePostRoute = post("/posts/:postId/approve", { params: Params, body: Body });
+
+export const approvePostHandler: HttpHandler<Input> = async ({ input }) => {
+  await app.runtime.dispatch(approvePost, {
+    postId: input.postId,
+    approvedBy: input.moderatorId,
+  });
+  return { $status: 202, body: { accepted: true } };
+};

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

@@ -0,0 +1,20 @@
+/**
+ * GET /api/posts/:postId — single-post lookup.
+ *
+ * Returns the projection's record. 404 when the post isn't in the
+ * dashboard (never submitted, or projection state was reset).
+ */
+
+import { get, type HttpHandler } from "@nwire/http";
+import { z } from "zod";
+import { app } from "../../../app/app";
+
+const Params = z.object({ postId: z.string() });
+
+export const getPostRoute = get("/posts/:postId", { params: Params });
+
+export const getPostHandler: HttpHandler<z.infer<typeof Params>> = async ({ input }) => {
+  const post = await app.runtime.query("posts.get-post", input);
+  if (!post) return { $status: 404, body: { error: { code: "POST_NOT_FOUND" } } };
+  return post;
+};

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

@@ -0,0 +1,22 @@
+/**
+ * GET /api/queue — dashboard view (pending list + totals).
+ *
+ * Reads from the queueDashboard projection via two queries. The
+ * projection has been folding events in the background — this is a
+ * straight state read, no recomputation.
+ */
+
+import { get, type HttpHandler } from "@nwire/http";
+import { z } from "zod";
+import { app } from "../../../app/app";
+
+const Query = z.object({
+  limit: z.coerce.number().int().min(1).max(100).default(20),
+});
+
+export const listQueueRoute = get("/queue", { query: Query });
+
+export const listQueueHandler: HttpHandler<z.infer<typeof Query>> = async ({ input }) => ({
+  items: await app.runtime.query("posts.list-pending", input),
+  totals: await app.runtime.query("posts.queue-totals", {}),
+});