create-nwire 0.7.1 → 0.8.0

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

@@ -0,0 +1,29 @@
+/**
+ * POST /api/posts/:postId/reject — human moderator rejects with a reason.
+ *
+ * The reason is mandatory and becomes part of the audit trail via the
+ * PostWasRejected event.
+ */
+
+import { post, type HttpHandler } from "@nwire/http";
+import { z } from "zod";
+import { app } from "../../../app/app";
+import { rejectPost } from "../actions/reject-post";
+
+const Params = z.object({ postId: z.string() });
+const Body = z.object({
+  moderatorId: z.string(),
+  reason: z.string().min(1).max(500),
+});
+type Input = z.infer<typeof Params> & z.infer<typeof Body>;
+
+export const rejectPostRoute = post("/posts/:postId/reject", { params: Params, body: Body });
+
+export const rejectPostHandler: HttpHandler<Input> = async ({ input }) => {
+  await app.runtime.dispatch(rejectPost, {
+    postId: input.postId,
+    rejectedBy: input.moderatorId,
+    reason: input.reason,
+  });
+  return { $status: 202, body: { accepted: true } };
+};

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

@@ -0,0 +1,28 @@
+/**
+ * POST /api/posts — author submits a draft for moderation.
+ *
+ * Returns 202 (Accepted) — the action recorded PostWasSubmitted; the
+ * auto-moderate workflow + dashboard projection run downstream. By the
+ * time the client polls GET /api/queue the post may already be auto-decided.
+ *
+ * The route handler is a thin shim: translate request → action input,
+ * dispatch, return the tagged response. All orchestration happens
+ * downstream of the event the action emits — never inside the handler.
+ */
+
+import { post, type HttpHandler } from "@nwire/http";
+import { z } from "zod";
+import { app } from "../../../app/app";
+import { submitPost } from "../actions/submit-post";
+
+const Body = z.object({
+  authorId: z.string(),
+  body: z.string().min(1).max(2000),
+});
+
+export const submitPostRoute = post("/posts", { body: Body });
+
+export const submitPostHandler: HttpHandler<z.infer<typeof Body>> = async ({ input }) => {
+  await app.runtime.dispatch(submitPost, input);
+  return { $status: 202, body: { accepted: true } };
+};

package/templates/L4/{app/auto-moderate.workflow.ts → modules/posts/workflows/auto-moderate.ts}

@@ -1,5 +1,5 @@
 /**
- * `autoModerate` — workflow that runs cheap auto-moderation on every
+ * 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
@@ -14,12 +14,12 @@
  * 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
+ * ## Why a workflow here vs. doing it inline in the route handler
  *
- * 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 HTTP `POST /posts` route 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
@@ -29,15 +29,17 @@
  */
 
 import { defineWorkflow } from "@nwire/forge";
-import { PostWasSubmitted } from "./events";
-import { approvePost, rejectPost } from "./actions";
+import { PostWasSubmitted } from "../events/post-was-submitted";
+import { approvePost } from "../actions/approve-post";
+import { rejectPost } from "../actions/reject-post";
 
 /**
  * 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.
+ *
+ *   - "approve" for clean content
+ *   - `{ reject: reason }` for obvious violations
+ *   - "human" when content is ambiguous and a moderator should decide
  */
 function autoCheck(body: string): "approve" | { reject: string } | "human" {
   if (body.toLowerCase().includes("spam-marker")) return { reject: "Auto-detected spam" };
@@ -47,15 +49,6 @@ function autoCheck(body: string): "approve" | { reject: string } | "human" {
 
 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") {

package/templates/L4/tsconfig.json

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

package/templates/L2/app/middleware.ts

@@ -1,32 +0,0 @@
-/**
- * Tiny `requireUser` middleware — proves the chain pattern.
- *
- * A real app would use `@nwire/auth` + an IdP adapter (Logto,
- * better-auth, etc.) to extract `user` from a JWT in the Authorization
- * header. For this example we trust the `x-user-id` header so the test
- * suite stays focused on the framework shape, not on JWT handling.
- *
- * The middleware does two things:
- *
- *   1. Throws `NoUserId` if the header is absent — surfaces as 401 JSON.
- *   2. Attaches the user id to the request-scoped container so resolvers
- *      can `ctx.resolve<string>("userId")` without re-reading the header.
- *
- * Resolvers chain it with `.use(requireUser)`; auth lives at the
- * interface seam, not inside business logic.
- */
-
-import type { HttpMiddleware } from "@nwire/http";
-import { NoUserId } from "./errors";
-
-export const requireUser: HttpMiddleware = async (ctx, next) => {
-  const userId = ctx.request.headers["x-user-id"];
-  if (typeof userId !== "string" || userId.length === 0) {
-    throw NoUserId;
-  }
-  // Stash on Koa state so resolvers can read it via _raw.state.userId,
-  // OR they can read the header directly via _raw.request.headers. We
-  // attach to state so the handler's signature is clean.
-  ctx.state.userId = userId;
-  await next();
-};

package/templates/L4/app/actions.ts

@@ -1,81 +0,0 @@
-/**
- * Domain actions — the use cases the moderation system exposes.
- *
- * Each action is a named function with input validation, executable from:
- *
- *   - A resolver (HTTP handler dispatches via `execute(action, input)`)
- *   - A workflow (the auto-moderation workflow dispatches via `send(action, ...)`)
- *   - Tests (via the harness — exercises the action without booting HTTP)
- *
- * That reuse across callers is exactly why actions are extracted from
- * resolvers. In the todo-app example we didn't extract — each CRUD
- * resolver did its own DB write. Here `approvePost` is called both from
- * the HTTP `POST /posts/:id/approve` endpoint AND from the workflow's
- * auto-approve branch. Extracting it keeps the logic in one place.
- *
- * The actions emit events, the framework records them, and the implicit
- * bus delivers them to subscribed workflows + projections.
- */
-
-import { randomUUID } from "node:crypto";
-import { z } from "zod";
-import { defineAction } from "@nwire/forge";
-import { PostWasSubmitted, PostWasApproved, PostWasRejected } from "./events";
-
-export const submitPost = defineAction({
-  name: "moderation.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) => {
-    /**
-     * The action's job is to validate the input and return the event(s)
-     * that describe what happened. The framework persists the events,
-     * notifies workflow subscribers, and folds them into projections.
-     * Notice: the action doesn't know who's listening. That's the bus.
-     */
-    return PostWasSubmitted({
-      postId: randomUUID(),
-      authorId: input.authorId,
-      body: input.body,
-      submittedAt: new Date().toISOString(),
-    });
-  },
-});
-
-export const approvePost = defineAction({
-  name: "moderation.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(),
-    }),
-});
-
-export const rejectPost = defineAction({
-  name: "moderation.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/app/events.ts

@@ -1,53 +0,0 @@
-/**
- * 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/moderation.module.ts

@@ -1,28 +0,0 @@
-/**
- * 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()],
-});