create-nwire 0.7.0

package/templates/L2/app/api.ts

@@ -0,0 +1,125 @@
+/**
+ * The HTTP interface — four routes + their inline handlers.
+ *
+ * Each route binding carries its own schemas (params + body + query);
+ * the framework validates the request against them before the handler
+ * runs. The handler receives a typed `input` (merged from all three)
+ * plus the resolved request context.
+ *
+ * What the handler reads from ctx:
+ *
+ *   - `input`            parsed + validated route input
+ *   - `resolve<T>(name)` container binding (e.g. the todo store)
+ *   - `_raw`             Koa context (for state.userId set by requireUser)
+ *
+ * The middleware chain `requireUser` runs before EVERY route — adding it
+ * once at the interface level instead of repeating per-route. Per-route
+ * middleware would go on individual `.wire(...)` calls if needed.
+ *
+ * Response shapes use `Todo.project(record)` so the public field list
+ * defined on the model controls what ships. No hand-mapping; no risk
+ * of an internal field leaking.
+ */
+
+import { httpInterface, get, post, del } from "@nwire/http";
+import { z } from "zod";
+import { Todo, type TodoRecord } from "./model";
+import { TodoStore } from "./store";
+import { TodoNotFound, TodoAlreadyCompleted } from "./errors";
+import { requireUser } from "./middleware";
+
+// ─── The interface ────────────────────────────────────────────────
+
+export const api = httpInterface({ prefix: "/api" })
+  .use(requireUser)
+
+  // POST /api/todos — add
+  .wire(
+    post("/todos", {
+      body: z.object({ text: z.string().min(1).max(500) }),
+    }),
+    async ({ input, resolve, _raw }) => {
+      const { text } = input as { text: string };
+      const store = resolve<TodoStore>("todos");
+      const userId = _raw.state.userId as string;
+      const todo = store.add({ userId, text });
+      return { $status: 201, body: project(todo) };
+    },
+  )
+
+  // GET /api/todos?status=open|completed — list
+  .wire(
+    get("/todos", {
+      query: z.object({
+        status: z.enum(["open", "completed"]).optional(),
+      }),
+    }),
+    async ({ input, resolve, _raw }) => {
+      const { status } = input as { status?: "open" | "completed" };
+      const store = resolve<TodoStore>("todos");
+      const userId = _raw.state.userId as string;
+      const list = store.listByUser(userId, status);
+      return { items: list.map(project), total: list.length };
+    },
+  )
+
+  // POST /api/todos/:id/complete — mark complete
+  .wire(
+    post("/todos/:id/complete", {
+      params: z.object({ id: z.string() }),
+    }),
+    async ({ input, resolve, _raw }) => {
+      const { id } = input as { id: string };
+      const store = resolve<TodoStore>("todos");
+      const userId = _raw.state.userId as string;
+
+      const existing = store.get(id);
+      if (!existing || existing.userId !== userId) throw TodoNotFound;
+      if (existing.status === "completed") throw TodoAlreadyCompleted;
+
+      const updated = store.complete(id);
+      return project(updated!);
+    },
+  )
+
+  // DELETE /api/todos/:id — remove
+  .wire(
+    del("/todos/:id", {
+      params: z.object({ id: z.string() }),
+    }),
+    async ({ input, resolve, _raw }) => {
+      const { id } = input as { id: string };
+      const store = resolve<TodoStore>("todos");
+      const userId = _raw.state.userId as string;
+
+      const existing = store.get(id);
+      if (!existing || existing.userId !== userId) throw TodoNotFound;
+
+      store.remove(id);
+      return null; // → 204 No Content
+    },
+  );
+
+// ─── Helpers ──────────────────────────────────────────────────────
+
+/**
+ * `project()` shapes the internal record onto the public Todo model.
+ * In a richer setup with `response.list(Todo)` this happens automatically.
+ * Here we call it explicitly so the example reads top-to-bottom.
+ */
+function project(t: TodoRecord) {
+  return {
+    id: t.id,
+    userId: t.userId,
+    text: t.text,
+    status: t.status,
+    addedAt: t.addedAt,
+    completedAt: t.completedAt,
+  };
+}
+
+// Reference Todo so the import isn't tree-shaken — the model is the
+// canonical declaration of the public field set, even when we project
+// by hand. Future: switch to response.list(Todo) once the new builder
+// has the project() helper wired.
+void Todo;

package/templates/L2/app/errors.ts

@@ -0,0 +1,48 @@
+/**
+ * Typed errors — throwable values, rendered per transport.
+ *
+ * `defineError` returns an Error subclass with `code` + `status` baked
+ * in. In a resolver handler you just `throw TodoNotFound` and the HTTP
+ * transport renders it as JSON `{ error: { code: "TODO_NOT_FOUND" } }`
+ * with status 404. GraphQL would render it as a GQL error with the same
+ * extensions. CLI would print + exit with the right code. One error
+ * declaration, every transport does the right thing.
+ *
+ * Bonus: clients can switch on `error.code` to render UI per-case
+ * (toast "Already done!" vs full 404 page). The shape is part of the
+ * contract, not invented per call site.
+ */
+
+import { defineError } from "@nwire/forge";
+
+/** A user looked up a todo by id and we don't have it. */
+export const TodoNotFound = defineError({
+  code: "TODO_NOT_FOUND",
+  status: 404,
+  summary: "Todo not found in this user's list",
+});
+
+/**
+ * The user tried to complete a todo that's already in the `completed`
+ * state. Distinct from "already removed" — this is a soft conflict the
+ * UI can recognize and ignore silently if it wants.
+ */
+export const TodoAlreadyCompleted = defineError({
+  code: "TODO_ALREADY_COMPLETED",
+  status: 409,
+  summary: "Todo has already been marked complete",
+});
+
+/**
+ * Caller didn't send an `x-user-id` header. Our auth middleware is
+ * intentionally trivial for this example — a real app would use
+ * `@nwire/auth` + `@nwire/auth-logto` or similar.
+ */
+export const NoUserId = defineError({
+  code: "MISSING_USER_ID",
+  status: 401,
+  summary: "Caller must provide x-user-id header",
+});
+
+// Re-export common framework errors so resolvers import from one place.
+export { Unauthorized, Forbidden, NotFound, Gone } from "@nwire/forge";

package/templates/L2/app/main.ts

@@ -0,0 +1,35 @@
+/**
+ * Entry point — wire the store into the http interface, then run.
+ *
+ * The shape for Level 1:
+ *
+ *   1. Build an in-memory container, register the store on it.
+ *   2. Hand it to the http interface via `.provide()` — the resolvers'
+ *      `resolve("todos")` reads from there.
+ *   3. Wrap in `endpoint()` for graceful shutdown + K8s probes.
+ *
+ * No `createApp` here. With ONE binding and zero plugin lifecycle work,
+ * createApp adds ceremony without value. The station-management example
+ * shows the full createApp + plugin shape with many bindings and
+ * framework events; Level 1 doesn't need it.
+ *
+ * Run:    pnpm dev
+ * Try:    curl -X POST http://localhost:3000/api/todos \
+ *               -H "content-type: application/json" \
+ *               -H "x-user-id: alice" \
+ *               -d '{"text":"buy milk"}'
+ *
+ *         curl -H "x-user-id: alice" http://localhost:3000/api/todos
+ */
+
+import { endpoint } from "@nwire/endpoint";
+import { InMemoryContainer } from "@nwire/container";
+import { TodoStore } from "./store";
+import { api } from "./api";
+
+const container = new InMemoryContainer();
+container.register("todos", new TodoStore());
+
+api.provide(container);
+
+await endpoint("{{PROJECT_NAME}}", { port: 3000 }).serve(api).run();

package/templates/L2/app/middleware.ts

@@ -0,0 +1,32 @@
+/**
+ * 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/L2/app/model.ts

@@ -0,0 +1,60 @@
+/**
+ * Todo — the public API shape.
+ *
+ * `defineResource` ties a Zod schema to an explicit `public` field list so
+ * the HTTP response automatically strips anything internal. Without this,
+ * an internal field added later (an audit timestamp, a soft-delete flag)
+ * silently leaks into clients on the next response. With it, that's
+ * a compile-time error: a field appears in the schema but not in `public`,
+ * the strip is explicit, and reviewers can see what the API exposes by
+ * scanning one array.
+ *
+ * The same `Todo` model is used by every resolver that returns todos —
+ * single, list, paginated. `response.list(Todo)` and `response.ok(Todo)`
+ * both call `Todo.project()` on each record so the public field rules
+ * apply once, declared in one place.
+ */
+
+import { z } from "zod";
+import { defineResource } from "@nwire/forge";
+
+export const Todo = defineResource("Todo", {
+  summary: "A single todo item in a user's list",
+
+  schema: z.object({
+    id: z.string().describe("Unique todo identifier"),
+    userId: z.string().describe("Owner of the todo"),
+    text: z.string().describe("What the user wants to remember"),
+    status: z.enum(["open", "completed"]).describe("Lifecycle state"),
+    addedAt: z.string().datetime().describe("ISO 8601 creation timestamp"),
+    completedAt: z
+      .string()
+      .datetime()
+      .nullable()
+      .describe("Set when status=completed; null otherwise"),
+  }),
+
+  public: ["id", "userId", "text", "status", "addedAt", "completedAt"],
+
+  examples: {
+    open: {
+      id: "01HK7Z3YV4MPNG2BAYBA8XQZ4F",
+      userId: "alice",
+      text: "buy milk",
+      status: "open",
+      addedAt: "2026-05-21T10:00:00.000Z",
+      completedAt: null,
+    },
+    done: {
+      id: "01HK7Z4AVV4MPNG2BAYBA8XQZ4F",
+      userId: "alice",
+      text: "ship v1.0",
+      status: "completed",
+      addedAt: "2026-05-20T09:00:00.000Z",
+      completedAt: "2026-05-21T11:30:00.000Z",
+    },
+  },
+});
+
+/** Inferred TS type — what handlers work with internally. */
+export type TodoRecord = z.infer<typeof Todo.schema>;

package/templates/L2/app/store.ts

@@ -0,0 +1,122 @@
+/**
+ * In-memory todo store.
+ *
+ * Two parts:
+ *
+ *   1. `TodoStore` — the actual data + operations (kept dead simple so
+ *      readers see the framework, not the persistence layer).
+ *   2. `todoStorePlugin` — a `@nwire/app` plugin that registers the
+ *      store on the container under the name "todos" and tears it down
+ *      on graceful shutdown.
+ *
+ * In a real app you'd swap the store for `@nwire/data-drizzle` against
+ * Postgres or `@nwire/store-mongo` against Mongo. The PLUGIN shape stays
+ * the same — `provide("todos", { boot, shutdown })`. Resolvers always do
+ * `ctx.resolve("todos")` and get whatever the plugin booted.
+ */
+
+import { randomUUID } from "node:crypto";
+import { definePlugin } from "@nwire/app";
+import type { TodoRecord } from "./model";
+
+// ─── The store itself ────────────────────────────────────────────
+
+export class TodoStore {
+  private readonly byId = new Map<string, TodoRecord>();
+  private readonly byUser = new Map<string, Set<string>>();
+
+  add(input: { userId: string; text: string }): TodoRecord {
+    const todo: TodoRecord = {
+      id: randomUUID(),
+      userId: input.userId,
+      text: input.text,
+      status: "open",
+      addedAt: new Date().toISOString(),
+      completedAt: null,
+    };
+    this.byId.set(todo.id, todo);
+    const owned = this.byUser.get(input.userId) ?? new Set<string>();
+    owned.add(todo.id);
+    this.byUser.set(input.userId, owned);
+    return todo;
+  }
+
+  get(id: string): TodoRecord | undefined {
+    return this.byId.get(id);
+  }
+
+  complete(id: string): TodoRecord | undefined {
+    const existing = this.byId.get(id);
+    if (!existing) return undefined;
+    /**
+     * Returning the SAME object would break callers that compare the
+     * old + new value (e.g., for change detection). Always allocate.
+     */
+    const updated: TodoRecord = {
+      ...existing,
+      status: "completed",
+      completedAt: new Date().toISOString(),
+    };
+    this.byId.set(id, updated);
+    return updated;
+  }
+
+  remove(id: string): boolean {
+    const existing = this.byId.get(id);
+    if (!existing) return false;
+    this.byId.delete(id);
+    this.byUser.get(existing.userId)?.delete(id);
+    return true;
+  }
+
+  listByUser(userId: string, status?: "open" | "completed"): TodoRecord[] {
+    const ids = this.byUser.get(userId) ?? new Set<string>();
+    const out: TodoRecord[] = [];
+    for (const id of ids) {
+      const t = this.byId.get(id);
+      if (!t) continue;
+      if (status && t.status !== status) continue;
+      out.push(t);
+    }
+    // Open todos first (recently-added on top); completed at the bottom.
+    out.sort((a, b) => {
+      if (a.status !== b.status) return a.status === "open" ? -1 : 1;
+      return a.addedAt < b.addedAt ? 1 : -1;
+    });
+    return out;
+  }
+
+  /** Diagnostic — number of todos held. */
+  size(): number {
+    return this.byId.size;
+  }
+}
+
+// ─── The plugin ──────────────────────────────────────────────────
+
+/**
+ * Plugin shape: `provide("todos", { boot, shutdown })`.
+ *
+ * The framework calls `boot()` during app start, registers the result
+ * on the container under the name we chose, and calls `shutdown(store)`
+ * during graceful drain. From any resolver's ctx: `ctx.resolve("todos")`.
+ *
+ * This same shape works whether the store is in-memory (here), a Pool
+ * (Postgres via Drizzle), or a MongoClient. The plugin wrapper handles
+ * the lifecycle; the store implementation handles its own concerns.
+ */
+export const todoStorePlugin = definePlugin("todos", ({ provide }) => {
+  provide("todos", {
+    boot: () => new TodoStore(),
+    shutdown: (store) => {
+      // For an in-memory store there's nothing to close. A real adapter
+      // would call `pool.end()` / `client.close()` here.
+      void store;
+    },
+    healthCheck: (store) => {
+      // Trivial — proves the store is alive. A real adapter would
+      // SELECT 1 against the DB. Lightship calls this on every /readyz.
+      if (store.size() < 0) throw new Error("store corrupt");
+    },
+  });
+});

package/templates/L2/package.json

@@ -0,0 +1,24 @@
+{
+  "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/container": "^0.7.0",
+    "@nwire/endpoint": "^0.7.0",
+    "@nwire/forge": "^0.7.0",
+    "@nwire/http": "^0.7.0",
+    "zod": "^4.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.19.9",
+    "typescript": "^5.9.0",
+    "vite-node": "^3.2.4",
+    "vitest": "^4.0.18"
+  }
+}

package/templates/L2/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/**/*"]
+}

package/templates/L4/README.md

@@ -0,0 +1,52 @@
+# {{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.
+
+Built around a moderation-queue example so you can see the moving
+parts before swapping in your own domain.
+
+## Run
+
+```bash
+pnpm install
+pnpm dev
+```
+
+## Try
+
+```bash
+# submit a post (becomes pending, auto-moderation triggers)
+curl -X POST http://localhost:3000/api/posts \
+  -H "content-type: application/json" \
+  -d '{"authorId":"alice","body":"Hello, world!"}'
+
+# read the dashboard projection
+curl http://localhost:3000/api/queue
+```
+
+## Source map
+
+| 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  |
+
+## Studio
+
+`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.

package/templates/L4/_gitignore

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

package/templates/L4/app/actions.ts

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