create-nwire 0.12.1 → 0.13.1

package/templates/service/AGENTS.md

@@ -14,7 +14,9 @@ import { post } from "@nwire/wires/http";
 import { httpKoa } from "@nwire/koa";
 
 const app = createApp({ appName: "svc" });
-app.wire(post("/things", { body: z.object({ name: z.string() }) }), async (input) => ({ ok: input.name }));
+app.wire(post("/things", { body: z.object({ name: z.string() }) }), async (input) => ({
+  ok: input.name,
+}));
 await endpoint("svc", { port: 3000 }).use(httpKoa()).mount(app).run();
 ```
 
@@ -26,15 +28,15 @@ their request shapes in `app/resources/`, errors in `app/errors/`.
 The single most common mistake is importing a primitive from the wrong
 package. Use exactly:
 
-| Primitive | Package |
-|---|---|
-| `createApp`, `appCompose`, `definePlugin` | `@nwire/app` |
-| `endpoint` | `@nwire/endpoint` |
-| `get` `post` `put` `patch` `del` | `@nwire/wires/http` |
-| `httpKoa` | `@nwire/koa` |
-| `defineHandler`, `defineResource`, `defineError`, `Unauthorized`/`Forbidden`/`NotFound`/`Conflict`/`BadRequest` | `@nwire/handler` |
-| `defineEvent` | `@nwire/messages` |
-| `defineAction`, `defineActor`, `defineProjection`, `defineQuery`, `defineWorkflow`, `createForgePlugin` | `@nwire/forge` |
+| Primitive                                                                                                       | Package             |
+| --------------------------------------------------------------------------------------------------------------- | ------------------- |
+| `createApp`, `appCompose`, `definePlugin`                                                                       | `@nwire/app`        |
+| `endpoint`                                                                                                      | `@nwire/endpoint`   |
+| `get` `post` `put` `patch` `del`                                                                                | `@nwire/wires/http` |
+| `httpKoa`                                                                                                       | `@nwire/koa`        |
+| `defineHandler`, `defineResource`, `defineError`, `Unauthorized`/`Forbidden`/`NotFound`/`Conflict`/`BadRequest` | `@nwire/handler`    |
+| `defineEvent`                                                                                                   | `@nwire/messages`   |
+| `defineAction`, `defineActor`, `defineProjection`, `defineQuery`, `defineWorkflow`, `forgePlugins`              | `@nwire/forge`      |
 
 `defineResource` and `defineError` are in **`@nwire/handler`**, not
 `@nwire/forge`. This service template does not depend on `@nwire/forge` —
@@ -56,7 +58,7 @@ listener file (not `on` — `on` is for lifecycle hooks).
 
 ## Commands
 
-- `pnpm dev` — run the app (HTTP on :3000).
+- `pnpm dev` — wire + Studio on http://localhost:4000.
 - `pnpm test` — run the test suite.
 - `pnpm doctor` — health-check the project setup.
 - `pnpm studio` — open the live trace/inspect console.

package/templates/service/README.md

@@ -16,18 +16,20 @@ pnpm dev
 
 ## Try
 
+`pnpm dev` serves the wire + Studio on http://localhost:4000.
+
 ```bash
 # create a todo
-curl -X POST http://localhost:3000/api/todos \
+curl -X POST http://localhost:4000/api/todos \
   -H "content-type: application/json" \
   -H "x-user-id: alice" \
   -d '{"text":"buy milk"}'
 
 # list this user's todos
-curl -H "x-user-id: alice" http://localhost:3000/api/todos
+curl -H "x-user-id: alice" http://localhost:4000/api/todos
 
 # complete one
-curl -X POST http://localhost:3000/api/todos/<id>/complete \
+curl -X POST http://localhost:4000/api/todos/<id>/complete \
   -H "x-user-id: alice"
 ```
 

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/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/main.ts

@@ -1,42 +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   # wire + Studio on http://localhost:4000
  *
- * 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:4000/api/todos \
+ *        -H "content-type: application/json" \
+ *        -H "x-user-id: alice" \
+ *        -d '{"text":"buy milk"}'
+ *   curl -H "x-user-id: alice" http://localhost:4000/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();
 
-const app = buildApp();
-await endpoint("{{PROJECT_NAME}}", { port: 3000 })
-  .use(httpKoa({ prefix: "/api", middleware: [requireUser] }))
+await endpoint(cfg.name, { port: cfg.port, banner: cfg.banner })
+  .use(httpKoa({ prefix: http.prefix, middleware: [requireUser] }))
   .mount(app)
   .run();

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

@@ -99,32 +99,16 @@ export class TodoStore {
 // ─── 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.
- *
- * this template's main.ts uses the simpler `container.register(...)` path because we
- * don't have a forge app yet. The plugin is exported so forge 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,27 +4,26 @@
   "private": true,
   "type": "module",
   "scripts": {
-    "dev": "vite-node app/main.ts",
+    "dev": "nwire dev",
     "test": "vitest run",
     "doctor": "nwire doctor",
     "studio": "nwire studio",
     "cache": "nwire cache"
   },
   "dependencies": {
-    "@nwire/app": "^0.12.1",
-    "@nwire/endpoint": "^0.12.1",
-    "@nwire/handler": "^0.12.1",
-    "@nwire/koa": "^0.12.1",
-    "@nwire/wires": "^0.12.1",
+    "@nwire/app": "^0.13.1",
+    "@nwire/endpoint": "^0.13.1",
+    "@nwire/handler": "^0.13.1",
+    "@nwire/koa": "^0.13.1",
+    "@nwire/wires": "^0.13.1",
     "koa": "^2.16.1",
     "zod": "^4.0.0"
   },
   "devDependencies": {
+    "@nwire/cli": "^0.13.1",
     "@types/koa": "^2.15.0",
     "@types/node": "^22.19.9",
     "typescript": "^5.9.0",
-    "vite-node": "^3.2.4",
-    "vitest": "^4.0.18",
-    "@nwire/cli": "^0.12.1"
+    "vitest": "^4.0.18"
   }
 }

package/templates/service/tsconfig.json

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