create-nwire 0.12.1 → 0.13.0

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
  *
- * 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();
 
-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.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",
-    "@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__/**/*"]
 }