create-nwire 0.7.0

package/templates/L4/app/api.ts

@@ -0,0 +1,118 @@
+/**
+ * The HTTP interface — six routes covering submit + decide + dashboard.
+ *
+ * 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 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.
+ */
+
+import { httpInterface, get, post } from "@nwire/http";
+import { z } from "zod";
+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;
+
+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;
+    },
+  );

package/templates/L4/app/app.ts

@@ -0,0 +1,28 @@
+/**
+ * `createApp` composes the moderation module into a runnable app.
+ *
+ * Why createApp at Level 2 (when todo-app skipped it):
+ *
+ *   - We have a workflow that subscribes to events on the bus. The
+ *     workflow needs the runtime to register its subscription and
+ *     fire it on PostWasSubmitted. That's what `createApp` orchestrates.
+ *
+ *   - We have a projection that folds events into state. Same story —
+ *     the runtime registers the projection's reducers and calls them
+ *     on every matching event.
+ *
+ *   - We have actions that emit events. The runtime persists those
+ *     events through the implicit bus and routes them to all subscribers.
+ *
+ * One module, no plugins yet — but the moment we add a Postgres-backed
+ * projection store, a Redis cache, OTel tracing, an audit log plugin,
+ * they all attach here via `.use(plugin)`. The same `createApp` API
+ * scales from one module to dozens.
+ */
+
+import { createApp } from "@nwire/forge";
+import { moderationModule } from "./moderation.module";
+
+export const app = createApp({
+  modules: [moderationModule],
+});

package/templates/L4/app/auto-moderate.workflow.ts

@@ -0,0 +1,78 @@
+/**
+ * `autoModerate` — workflow that runs cheap auto-moderation on every
+ * 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
+ * what they DO with the event:
+ *
+ *   - Workflows produce SIDE EFFECTS — dispatch more actions, send
+ *     external messages, schedule timers, fire integrations.
+ *   - Projections produce READ STATE — fold events into a denormalized
+ *     model that queries read from.
+ *
+ * Same subscription primitive; different intent. The symmetry is real —
+ * if you have one, you have the shape to add the other.
+ *
+ * ## Why a workflow here vs. doing it inline in the resolver
+ *
+ * The HTTP resolver for "submit post" should return quickly — the user
+ * is waiting on a response. Running auto-moderation (which might call
+ * an LLM, scan a profanity list, lookup author reputation) takes time
+ * we can't afford in the request path.
+ *
+ * The workflow decouples the two: the action returns immediately after
+ * recording PostWasSubmitted; the workflow picks up the event async and
+ * does the heavy lifting. From the user's perspective: "Submitted!"
+ * From the system's perspective: the moderation flow runs to completion
+ * with retries, DLQ, and replay if the worker process restarts.
+ */
+
+import { defineWorkflow } from "@nwire/forge";
+import { PostWasSubmitted } from "./events";
+import { approvePost, rejectPost } from "./actions";
+
+/**
+ * Trivial moderation check — in a real app this would call an LLM,
+ * check against a banned-words list, look up author reputation, etc.
+ * Returns "approve" for clean content, "reject" with a reason for
+ * obvious violations, "human" when the content is ambiguous and needs
+ * a moderator's eye.
+ */
+function autoCheck(body: string): "approve" | { reject: string } | "human" {
+  if (body.toLowerCase().includes("spam-marker")) return { reject: "Auto-detected spam" };
+  if (body.length < 5) return "human";
+  return "approve";
+}
+
+export const autoModerate = defineWorkflow("auto-moderate", ({ on, send }) => {
+  on(PostWasSubmitted, async (event) => {
+    /**
+     * Three possible outcomes from the auto-check. Each maps to either
+     * dispatching the matching action (approve/reject) or doing nothing
+     * and letting a human moderator handle it via the HTTP endpoints.
+     *
+     * `send(action, input)` is the workflow's way to dispatch — it
+     * runs the action through the same pipeline as an HTTP-triggered
+     * dispatch, including retry/DLQ/idempotency.
+     */
+    const decision = autoCheck(event.body);
+
+    if (decision === "approve") {
+      await send(approvePost, { postId: event.postId, approvedBy: "auto" });
+      return;
+    }
+
+    if (typeof decision === "object") {
+      await send(rejectPost, {
+        postId: event.postId,
+        rejectedBy: "auto",
+        reason: decision.reject,
+      });
+      return;
+    }
+
+    // "human" — do nothing; the post stays in the pending queue,
+    // visible to moderators via GET /queue.
+  });
+});

package/templates/L4/app/events.ts

@@ -0,0 +1,53 @@
+/**
+ * Domain events for the moderation queue.
+ *
+ * Each event is past-tense — it represents a fact that happened, not a
+ * command to do something. `WasSubmitted`, `WasApproved`, `WasRejected`.
+ * The tense is the whole grammar: events name the past, actions name the
+ * 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: "moderation.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(),
+  }),
+});
+
+export const PostWasApproved = defineEvent({
+  name: "moderation.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(),
+  }),
+});
+
+export const PostWasRejected = defineEvent({
+  name: "moderation.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/app/main.ts

@@ -0,0 +1,39 @@
+/**
+ * Entry — boot the createApp and run the http interface under endpoint().
+ *
+ * The order matters:
+ *
+ *   1. `app` is a configured-but-unbooted forge app — modules registered,
+ *      workflow subscribers wired, projection reducers attached, but
+ *      nothing's actually 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.
+ *
+ * Once running:
+ *   - HTTP `POST /api/posts` → submitPost action → PostWasSubmitted event
+ *   - autoModerate workflow picks up the event, runs auto-check, dispatches
+ *     approve/reject if obvious
+ *   - queueDashboard projection picks up ALL three events, updates state
+ *   - HTTP `GET /api/queue` reads from the projection
+ *
+ * Run:    pnpm dev
+ * Try:    curl -X POST http://localhost:3000/api/posts \
+ *               -H "content-type: application/json" \
+ *               -d '{"authorId":"alice","body":"Hello, world!"}'
+ *         curl http://localhost:3000/api/queue
+ */
+
+import { endpoint } from "@nwire/endpoint";
+import { app } from "./app";
+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.
+api.inspect(app);
+
+await endpoint("{{PROJECT_NAME}}", { port: 3000 }).serve(api).run();

package/templates/L4/app/moderation.module.ts

@@ -0,0 +1,28 @@
+/**
+ * The moderation module — collects all the domain pieces for this
+ * bounded context. `defineModule` is purely organizational: it groups
+ * actions / events / workflows / projections / queries that belong
+ * to one part of the business, marks which ones are public (callable
+ * from other modules / apps), and gives the runtime a single value
+ * to register.
+ *
+ * `.public()` controls cross-module visibility — see
+ * `architecture-primitives.html` for the full rules. Here every action
+ * and query is public because we have one module; in a multi-module
+ * app you'd be more selective.
+ */
+
+import { defineModule } from "@nwire/forge";
+import { PostWasSubmitted, PostWasApproved, PostWasRejected } from "./events";
+import { submitPost, approvePost, rejectPost } from "./actions";
+import { autoModerate } from "./auto-moderate.workflow";
+import { queueDashboard, listPending, queueTotals, getPost } from "./queue.projection";
+
+export const moderationModule = defineModule("moderation", {
+  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

@@ -0,0 +1,162 @@
+/**
+ * `queueDashboard` projection — the read model for the moderation queue.
+ *
+ * NOTICE 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.
+ *
+ *   - This PROJECTION subscribes to events via the same `on` map shape.
+ *     Its job is to fold events into a denormalized state that queries
+ *     read from. No side effects; pure state derivation.
+ *
+ * Same subscription primitive. Same `on(Event)` ergonomics. Different
+ * 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.
+ */
+
+import { defineProjection, defineQuery } from "@nwire/forge";
+import { z } from "zod";
+import { PostWasSubmitted, PostWasApproved, PostWasRejected } from "./events";
+
+// ─── The projection state shape ────────────────────────────────
+
+interface QueueItem {
+  postId: string;
+  authorId: string;
+  body: string;
+  status: "pending" | "approved" | "rejected";
+  submittedAt: string;
+  decidedAt?: string;
+  decidedBy?: string;
+  reason?: string;
+}
+
+interface QueueState {
+  byId: Record<string, QueueItem>;
+  pendingIds: string[]; // ordered, oldest first
+  totals: { pending: number; approved: number; rejected: number };
+}
+
+// ─── The projection — note the `on` map matches the workflow's ───
+
+export const queueDashboard = defineProjection<QueueState>("queue-dashboard", {
+  description: "The moderation dashboard read model — pending queue + decision totals.",
+  listens: [PostWasSubmitted, PostWasApproved, PostWasRejected],
+  initial: () => ({
+    byId: {},
+    pendingIds: [],
+    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,
+        [event.postId]: {
+          postId: event.postId,
+          authorId: event.authorId,
+          body: event.body,
+          status: "pending",
+          submittedAt: event.submittedAt,
+        },
+      },
+      pendingIds: [...state.pendingIds, event.postId],
+      totals: { ...state.totals, pending: state.totals.pending + 1 },
+    }),
+
+    [PostWasApproved.name]: (state, event) => {
+      const item = state.byId[event.postId];
+      if (!item) return state;
+      return {
+        byId: {
+          ...state.byId,
+          [event.postId]: {
+            ...item,
+            status: "approved",
+            decidedAt: event.approvedAt,
+            decidedBy: event.approvedBy,
+          },
+        },
+        pendingIds: state.pendingIds.filter((id) => id !== event.postId),
+        totals: {
+          ...state.totals,
+          pending: state.totals.pending - 1,
+          approved: state.totals.approved + 1,
+        },
+      };
+    },
+
+    [PostWasRejected.name]: (state, event) => {
+      const item = state.byId[event.postId];
+      if (!item) return state;
+      return {
+        byId: {
+          ...state.byId,
+          [event.postId]: {
+            ...item,
+            status: "rejected",
+            decidedAt: event.rejectedAt,
+            decidedBy: event.rejectedBy,
+            reason: event.reason,
+          },
+        },
+        pendingIds: state.pendingIds.filter((id) => id !== event.postId),
+        totals: {
+          ...state.totals,
+          pending: state.totals.pending - 1,
+          rejected: state.totals.rejected + 1,
+        },
+      };
+    },
+  },
+});
+
+// ─── Queries — read the projection's state ─────────────────────
+
+export const listPending = defineQuery(queueDashboard, {
+  name: "moderation.list-pending",
+  schema: z.object({ limit: z.coerce.number().int().min(1).max(100).default(20) }),
+  execute: (state, { limit }) =>
+    state.pendingIds
+      .slice(0, limit)
+      .map((id) => state.byId[id])
+      .filter((x): x is QueueItem => x !== undefined),
+});
+
+export const queueTotals = defineQuery(queueDashboard, {
+  name: "moderation.queue-totals",
+  schema: z.object({}),
+  execute: (state) => state.totals,
+});
+
+export const getPost = defineQuery(queueDashboard, {
+  name: "moderation.get-post",
+  schema: z.object({ postId: z.string() }),
+  execute: (state, { postId }) => state.byId[postId] ?? null,
+});

package/templates/L4/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "{{PROJECT_NAME}}",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vite-node app/main.ts",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@nwire/app": "^0.7.0",
+    "@nwire/endpoint": "^0.7.0",
+    "@nwire/forge": "^0.7.0",
+    "@nwire/http": "^0.7.0",
+    "@nwire/messages": "^0.7.0",
+    "zod": "^4.0.0"
+  },
+  "devDependencies": {
+    "@nwire/test-kit": "^0.7.0",
+    "@types/node": "^22.19.9",
+    "typescript": "^5.9.0",
+    "vite-node": "^3.2.4",
+    "vitest": "^4.0.18"
+  }
+}

package/templates/L4/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "lib": ["ES2022"],
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "noEmit": true,
+    "types": ["node", "vite/client"]
+  },
+  "include": ["app/**/*"]
+}