create-nwire 0.12.0 → 0.13.0

package/templates/service/__tests__/todo-api.test.ts

@@ -1,22 +1,22 @@
 /**
  * Smoke test — the four CRUD operations + the requireUser middleware.
  *
- * Boots the app under httpKoa against an ephemeral port and dispatches
- * fetch requests exactly the way clients will.
+ * Boots the app from `app.ts` (the pure value) against an ephemeral port.
+ * `app` is complete on import — routes are wired in the module body of
+ * `app.ts`. Never imports `main.ts` — that file runs a real server and
+ * hangs the test runner.
  */
 
 import { describe, it, expect, beforeAll, afterAll } from "vitest";
 import { endpoint } from "@nwire/endpoint";
 import { httpKoa } from "@nwire/koa";
-import { buildApp } from "../app/main";
+import { app } from "../app/app";
 import { requireUser } from "../app/middleware/require-user";
 
 let running: Awaited<ReturnType<ReturnType<typeof endpoint>["run"]>>;
-let app: ReturnType<typeof buildApp>;
 let url: string;
 
 beforeAll(async () => {
-  app = buildApp();
   const koa = httpKoa({ port: 0, prefix: "/api", middleware: [requireUser] });
   running = await endpoint("todo-test", {
     exitOnShutdown: false,

package/templates/service/_npmrc

@@ -0,0 +1,4 @@
+# nwire dev runs via vite-node (esbuild). pnpm 11 defers esbuild's build
+# script and then fails the pre-run deps check; skip that check so
+# `pnpm dev` runs clean right after install.
+verify-deps-before-run=false

package/templates/service/_pnpm-workspace.yaml

@@ -0,0 +1,6 @@
+# pnpm 11 reads build-allow + run settings here (not the package.json
+# "pnpm" field). esbuild backs vite-node; allow its build, and skip the
+# pre-run deps check so `pnpm dev` runs clean right after install.
+onlyBuiltDependencies:
+  - esbuild
+verifyDepsBeforeRun: false

package/templates/service/app/app.ts

@@ -0,0 +1,25 @@
+/**
+ * App — the bounded context value.
+ *
+ * `createApp` installs plugins and wires all routes in this module body.
+ * The exported `app` is COMPLETE on import — no caller needs to wire or
+ * start it. No ports are bound here; that is `main.ts`'s job.
+ *
+ * Tests import `{ app }` from this file and build an isolated endpoint.
+ * Never import `main.ts` from tests: it boots a real server and hangs
+ * the runner.
+ *
+ * Graduate: swap `TodoStore` for `@nwire/drizzle` or `@nwire/mongo`.
+ * The plugin shape (`provide("todos", { boot, shutdown, healthCheck })`)
+ * stays the same; handlers keep calling `resolve("todos")`.
+ */
+
+import { createApp } from "@nwire/app";
+import { todoStorePlugin } from "./store/todo-store";
+import { wires } from "./api";
+
+export const app = createApp({ appName: "{{PROJECT_NAME}}" }).with(todoStorePlugin);
+
+for (const { binding, handler } of wires) {
+  app.wire(binding, handler);
+}

package/templates/service/app/errors/todo-errors.ts

@@ -13,7 +13,7 @@
  * contract, not invented per call site.
  */
 
-import { defineError } from "@nwire/forge";
+import { defineError } from "@nwire/handler";
 
 /** A user looked up a todo by id and we don't have it. */
 export const TodoNotFound = defineError({
@@ -45,4 +45,4 @@ export const NoUserId = defineError({
 });
 
 // Re-export common framework errors so handlers import from one place.
-export { Unauthorized, Forbidden, NotFound, Gone } from "@nwire/forge";
+export { Unauthorized, Forbidden, NotFound, Gone } from "@nwire/handler";

package/templates/service/app/main.ts

@@ -1,44 +1,32 @@
 /**
- * Entry — boot the app under HTTP.
+ * Entry — the only file that boots a real HTTP server.
  *
- *   1. createApp constructs the bounded context; `.with(plugin)` installs
- *      the TodoStore on the container.
- *   2. app.wire(...) pairs every route binding with its handler.
- *   3. endpoint().use(httpKoa({ middleware: [requireUser] })).mount(app).run()
- *      runs the HTTP adapter under graceful drain + K8s probes.
+ *   pnpm dev
  *
- * 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
+ *   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
+ *
+ * `app` is a pure value — routes are wired in `./app` on import.
+ * This file adds the one side effect: binding a port and serving traffic.
+ * Tests import `{ app }` from `./app` and build their own ephemeral
+ * endpoint — never import this file from tests or it boots a server and
+ * hangs the runner.
  */
 
-import { createApp, definePlugin } from "@nwire/app";
 import { endpoint } from "@nwire/endpoint";
 import { httpKoa } from "@nwire/koa";
-
-import { wires } from "./api";
+import { appConfig } from "../config/app";
+import { httpConfig } from "../config/http";
 import { requireUser } from "./middleware/require-user";
-import { TodoStore } from "./store/todo-store";
-
-const todoStorePlugin = definePlugin("todo-store", ({ bind }) => {
-  bind("todos", new TodoStore());
-});
+import { app } from "./app";
 
-export function buildApp() {
-  const app = createApp({ appName: "{{PROJECT_NAME}}" }).with(todoStorePlugin);
-  for (const { binding, handler } of wires) {
-    app.wire(binding, handler);
-  }
-  return app;
-}
+const cfg = appConfig();
+const http = httpConfig();
 
-if (import.meta.url === `file://${process.argv[1]}`) {
-  const app = buildApp();
-  await endpoint("{{PROJECT_NAME}}", { port: 3000 })
-    .use(httpKoa({ prefix: "/api", middleware: [requireUser] }))
-    .mount(app)
-    .run();
-}
+await endpoint(cfg.name, { port: cfg.port, banner: cfg.banner })
+  .use(httpKoa({ prefix: http.prefix, middleware: [requireUser] }))
+  .mount(app)
+  .run();

package/templates/service/app/resources/todo.ts

@@ -16,7 +16,7 @@
  */
 
 import { z } from "zod";
-import { defineResource } from "@nwire/forge";
+import { defineResource } from "@nwire/handler";
 
 export const Todo = defineResource("Todo", {
   summary: "A single todo item in a user's list",

package/templates/service/app/store/todo-store.ts

@@ -14,9 +14,9 @@
  * the same — `provide("todos", { boot, shutdown })`. Handlers always do
  * `resolve("todos")` and get whatever the plugin booted.
  *
- * The L2 template uses the simpler container-register-then-provide path
+ * This template uses the simpler container-register-then-provide path
  * from `main.ts` (no createApp). The plugin form is exported so it's
- * one rename away once you graduate to L4.
+ * one rename away once you add the forge battery.
  */
 
 import { randomUUID } from "node:crypto";
@@ -96,35 +96,19 @@ export class TodoStore {
   }
 }
 
-// ─── The plugin (optional — used when you graduate to L4) ────────
+// ─── The plugin (optional — used when you add the forge battery) ────────
 
 /**
- * Plugin shape: `provide("todos", { boot, shutdown })`.
+ * Plugin shape: `bind("todos", store)`.
  *
- * 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 handler: `resolve("todos")`.
+ * `bind` registers the store on the container under the name we chose.
+ * From any handler: `resolve("todos")`. For lifecycle teardown, use
+ * `dispose(() => ...)` — called on graceful shutdown.
  *
  * 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.
- *
- * L2 main.ts uses the simpler `container.register(...)` path because we
- * don't have a forge app yet. The plugin is exported so L4 graduation
- * is `import { todoStorePlugin } from "./store/todo-store"`.
  */
-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 /ready.
-      if (store.size() < 0) throw new Error("store corrupt");
-    },
-  });
+export const todoStorePlugin = definePlugin("todos", ({ bind }) => {
+  bind("todos", new TodoStore());
 });

package/templates/service/config/app.ts

@@ -0,0 +1,18 @@
+/**
+ * App-level settings — the process identity and lifecycle budgets the
+ * endpoint owns. A function of the typed `env`, so the same config file
+ * reads differently per environment without an `if` in sight.
+ */
+
+import { env, type Env } from "./env";
+
+export const appConfig = (e: Env = env) => ({
+  /** Endpoint + app name — shows in the banner, logs, and telemetry. */
+  name: "{{PROJECT_NAME}}",
+  /** Port the HTTP transport binds. */
+  port: e.PORT,
+  /** Print the boot banner outside of tests. */
+  banner: e.NODE_ENV !== "test",
+});
+
+export type AppConfig = ReturnType<typeof appConfig>;

package/templates/service/config/env.ts

@@ -0,0 +1,32 @@
+/**
+ * Typed environment — read `process.env` once, through a schema, and never
+ * touch it again from app code. Missing or malformed values fail loudly at
+ * boot with a readable message, not three layers deep at first request.
+ *
+ * `config/*.ts` files take this typed `env` and shape it into the settings
+ * each concern needs.
+ */
+
+import { z } from "zod";
+
+const EnvSchema = z.object({
+  NODE_ENV: z.enum(["development", "test", "production"]).default("development"),
+  PORT: z.coerce.number().int().min(0).max(65_535).default(3000),
+  HTTP_PREFIX: z.string().default("/api"),
+});
+
+export type Env = z.output<typeof EnvSchema>;
+
+export function loadEnv(source: NodeJS.ProcessEnv = process.env): Env {
+  const parsed = EnvSchema.safeParse(source);
+  if (!parsed.success) {
+    const summary = parsed.error.issues
+      .map((i) => `  ${i.path.join(".") || "(root)"}: ${i.message}`)
+      .join("\n");
+    throw new Error(`Invalid environment:\n${summary}`);
+  }
+  return parsed.data;
+}
+
+/** The validated environment, loaded once. */
+export const env: Env = loadEnv();

package/templates/service/config/http.ts

@@ -0,0 +1,15 @@
+/**
+ * HTTP transport settings — prefix, OpenAPI, and the dev inspect surface
+ * Studio reads. A function of the typed `env`, like every config file here.
+ */
+
+import { env, type Env } from "./env";
+
+export const httpConfig = (e: Env = env) => ({
+  /** Mounted under this prefix — e.g. `POST /api/todos`. */
+  prefix: e.HTTP_PREFIX,
+  /** Expose detailed errors in dev; redact in production. */
+  exposeErrors: e.NODE_ENV !== "production",
+});
+
+export type HttpConfig = ReturnType<typeof httpConfig>;

package/templates/service/package.json

@@ -4,23 +4,26 @@
   "private": true,
   "type": "module",
   "scripts": {
-    "dev": "vite-node app/main.ts",
-    "test": "vitest run"
+    "dev": "nwire dev",
+    "test": "vitest run",
+    "doctor": "nwire doctor",
+    "studio": "nwire studio",
+    "cache": "nwire cache"
   },
   "dependencies": {
-    "@nwire/app": "^0.12.0",
-    "@nwire/endpoint": "^0.12.0",
-    "@nwire/handler": "^0.12.0",
-    "@nwire/koa": "^0.12.0",
-    "@nwire/wires": "^0.12.0",
+    "@nwire/app": "^0.13.0",
+    "@nwire/endpoint": "^0.13.0",
+    "@nwire/handler": "^0.13.0",
+    "@nwire/koa": "^0.13.0",
+    "@nwire/wires": "^0.13.0",
     "koa": "^2.16.1",
     "zod": "^4.0.0"
   },
   "devDependencies": {
+    "@nwire/cli": "^0.13.0",
     "@types/koa": "^2.15.0",
     "@types/node": "^22.19.9",
     "typescript": "^5.9.0",
-    "vite-node": "^3.2.4",
     "vitest": "^4.0.18"
   }
 }

package/templates/service/tsconfig.json

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