create-nwire 0.11.1 → 0.12.1

package/dist/index.js

@@ -67,6 +67,9 @@ export function scaffold(opts) {
 const UNDERSCORE_TO_DOT = {
     _gitignore: ".gitignore",
     _npmrc: ".npmrc",
+    // Underscore-prefixed in the template so it doesn't make the nwire
+    // monorepo treat the template dir as a nested pnpm workspace.
+    "_pnpm-workspace.yaml": "pnpm-workspace.yaml",
     _eslintrc: ".eslintrc",
     _eslintignore: ".eslintignore",
     _prettierrc: ".prettierrc",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-nwire",
-  "version": "0.11.1",
+  "version": "0.12.1",
   "description": "Scaffolder for new Nwire projects. Run `pnpm create nwire <name>` or `npm create nwire <name>` to bootstrap.",
   "keywords": [
     "nwire",

package/templates/enterprise/AGENTS.md

@@ -0,0 +1,43 @@
+# AGENTS.md — working in this nwire app
+
+This is an **nwire** backend (enterprise tier: the full forge battery is
+installed). The one idea: you write logic once as a **handler** (a plain
+typed function) and wire it to a **transport** (HTTP route, queue, cron,
+MCP tool). The handler never knows which transport called it. When logic
+gets real, forge adds events, actors, projections, and workflows.
+
+## Import map — DO NOT GUESS THESE
+
+The most common mistake is importing a primitive from the wrong package:
+
+| 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`, `defineSchema`, `defineProjection`, `defineQuery`, `defineWorkflow`, `createForgePlugin` | `@nwire/forge` |
+
+`defineResource` and `defineError` are in **`@nwire/handler`**, not
+`@nwire/forge` — even though forge re-exports some of them, import from
+`@nwire/handler` directly.
+
+## Concepts
+
+- **Handler** — `(input, ctx) => result`; `ctx` carries `input`,
+  `resolve`, `execute`, `emit`, `envelope`, `logger`.
+- **Event** — a past-tense fact (`defineEvent`). Emit with `ctx.emit`;
+  react to it with `when(Event, fn)` in a listener file (`on` is for
+  lifecycle hooks only).
+- **Action** — a named command (`defineAction`) a handler fulfils and may
+  emit events from. Register via `createForgePlugin({ handlers: [act.handler] })`.
+- **Actor** — a thing with identity that guards a rule. **Projection** — a
+  read model folded from events. **Workflow** — a process that reacts over
+  time.
+
+## Commands
+
+- `pnpm dev` — run the app. `pnpm test` — tests. `pnpm doctor` — health
+  check. `pnpm studio` — live trace/inspect console.

package/templates/enterprise/_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/enterprise/_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/enterprise/app/main.ts

@@ -52,6 +52,4 @@ export async function bootstrap(opts: number | BootstrapOptions = 3000) {
   return { app, running, koa };
 }
 
-if (import.meta.url === `file://${process.argv[1]}`) {
-  await bootstrap();
-}
+await bootstrap();

package/templates/enterprise/package.json

@@ -5,22 +5,26 @@
   "type": "module",
   "scripts": {
     "dev": "vite-node app/main.ts",
-    "test": "vitest run"
+    "test": "vitest run",
+    "doctor": "nwire doctor",
+    "studio": "nwire studio",
+    "cache": "nwire cache"
   },
   "dependencies": {
-    "@nwire/app": "^0.11.1",
-    "@nwire/endpoint": "^0.11.1",
-    "@nwire/forge": "^0.11.1",
-    "@nwire/koa": "^0.11.1",
-    "@nwire/messages": "^0.11.1",
-    "@nwire/wires": "^0.11.1",
+    "@nwire/app": "^0.12.1",
+    "@nwire/endpoint": "^0.12.1",
+    "@nwire/forge": "^0.12.1",
+    "@nwire/koa": "^0.12.1",
+    "@nwire/messages": "^0.12.1",
+    "@nwire/wires": "^0.12.1",
     "zod": "^4.0.0"
   },
   "devDependencies": {
-    "@nwire/test-kit": "^0.11.1",
+    "@nwire/test-kit": "^0.12.1",
     "@types/node": "^22.19.9",
     "typescript": "^5.9.0",
     "vite-node": "^3.2.4",
-    "vitest": "^4.0.18"
+    "vitest": "^4.0.18",
+    "@nwire/cli": "^0.12.1"
   }
 }

package/templates/enterprise/tsconfig.json

@@ -9,7 +9,7 @@
     "skipLibCheck": true,
     "forceConsistentCasingInFileNames": true,
     "noEmit": true,
-    "types": ["node", "vite/client"]
+    "types": ["node"]
   },
   "include": ["app/**/*", "modules/**/*", "__tests__/**/*"]
 }

package/templates/minimal/AGENTS.md

@@ -0,0 +1,37 @@
+# AGENTS.md — working in this nwire app
+
+This is a **minimal nwire** backend. You write logic once as a **handler**
+(a plain typed function) and wire it to a **transport** (here, HTTP). The
+handler never knows which transport called it.
+
+## The shape (`app/main.ts`)
+
+```ts
+import { createApp } from "@nwire/app";
+import { endpoint } from "@nwire/endpoint";
+import { get } from "@nwire/wires/http";
+import { httpKoa } from "@nwire/koa";
+
+const app = createApp({ appName: "app" });
+app.wire(get("/hello"), async () => ({ message: "hello" }));
+await endpoint("app", { port: 3000 }).use(httpKoa()).mount(app).run();
+```
+
+## What's installed (don't import beyond these)
+
+| Primitive | Package |
+|---|---|
+| `createApp`, `definePlugin` | `@nwire/app` |
+| `endpoint` | `@nwire/endpoint` |
+| `get` `post` `put` `patch` `del` | `@nwire/wires/http` |
+| `httpKoa` | `@nwire/koa` |
+
+This tier is HTTP-only. Add capabilities by installing the package first:
+`@nwire/handler` for `defineResource`/`defineError`, `@nwire/messages` for
+`defineEvent`, `@nwire/forge` for actions/actors/projections/workflows.
+**Don't import a primitive from a package that isn't in `package.json`.**
+
+## Commands
+
+- `pnpm dev` — run the app (HTTP on :3000). `pnpm test` — tests.
+- `pnpm doctor` — health-check the setup. `pnpm studio` — trace console.

package/templates/minimal/_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/minimal/_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/minimal/app/main.ts

@@ -29,7 +29,5 @@ export function buildApp() {
   return app;
 }
 
-if (import.meta.url === `file://${process.argv[1]}`) {
-  const app = buildApp();
-  await endpoint("{{PROJECT_NAME}}", { port: 3000 }).use(httpKoa()).mount(app).run();
-}
+const app = buildApp();
+await endpoint("{{PROJECT_NAME}}", { port: 3000 }).use(httpKoa()).mount(app).run();

package/templates/minimal/package.json

@@ -5,19 +5,23 @@
   "type": "module",
   "scripts": {
     "dev": "vite-node app/main.ts",
-    "test": "vitest run"
+    "test": "vitest run",
+    "doctor": "nwire doctor",
+    "studio": "nwire studio",
+    "cache": "nwire cache"
   },
   "dependencies": {
-    "@nwire/app": "^0.11.1",
-    "@nwire/endpoint": "^0.11.1",
-    "@nwire/koa": "^0.11.1",
-    "@nwire/wires": "^0.11.1",
+    "@nwire/app": "^0.12.1",
+    "@nwire/endpoint": "^0.12.1",
+    "@nwire/koa": "^0.12.1",
+    "@nwire/wires": "^0.12.1",
     "zod": "^4.0.0"
   },
   "devDependencies": {
     "@types/node": "^22.19.9",
     "typescript": "^5.9.0",
     "vite-node": "^3.2.4",
-    "vitest": "^4.0.18"
+    "vitest": "^4.0.18",
+    "@nwire/cli": "^0.12.1"
   }
 }

package/templates/minimal/tsconfig.json

@@ -9,7 +9,7 @@
     "skipLibCheck": true,
     "forceConsistentCasingInFileNames": true,
     "noEmit": true,
-    "types": ["node", "vite/client"]
+    "types": ["node"]
   },
   "include": ["app/**/*", "__tests__/**/*"]
 }

package/templates/service/AGENTS.md

@@ -0,0 +1,62 @@
+# AGENTS.md — working in this nwire app
+
+This is an **nwire** backend. The one idea: you write logic once as a
+**handler** (a plain typed function) and wire it to a **transport** (an
+HTTP route, a queue, cron, an MCP tool). The handler never knows which
+transport called it.
+
+## The shape
+
+```ts
+import { createApp } from "@nwire/app";
+import { endpoint } from "@nwire/endpoint";
+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 }));
+await endpoint("svc", { port: 3000 }).use(httpKoa()).mount(app).run();
+```
+
+`app/main.ts` builds and runs the app. Routes live in `app/routes/`,
+their request shapes in `app/resources/`, errors in `app/errors/`.
+
+## Import map — DO NOT GUESS THESE
+
+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` |
+
+`defineResource` and `defineError` are in **`@nwire/handler`**, not
+`@nwire/forge`. This service template does not depend on `@nwire/forge` —
+don't import from it unless you add it to `package.json` first.
+
+## Adding a route
+
+1. A binding + handler: `app/routes/<verb>-<noun>.ts` exports a route
+   (`post("/path", { body })`) and a handler `(input, ctx) => result`.
+2. Register it in `app/api.ts`'s wire list (or `app.wire(route, handler)`).
+3. Throw a typed `defineError` for failures; return a plain object or a
+   `defineResource` projection for success.
+
+## Verbs
+
+`.wire(binding, handler)` binds a transport. `.use(adapter)` mounts a
+transport on the endpoint. To react to events, use `when(Event, fn)` in a
+listener file (not `on` — `on` is for lifecycle hooks).
+
+## Commands
+
+- `pnpm dev` — run the app (HTTP on :3000).
+- `pnpm test` — run the test suite.
+- `pnpm doctor` — health-check the project setup.
+- `pnpm studio` — open the live trace/inspect console.

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/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

@@ -35,10 +35,8 @@ export function buildApp() {
   return app;
 }
 
-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();
-}
+const app = buildApp();
+await endpoint("{{PROJECT_NAME}}", { port: 3000 })
+  .use(httpKoa({ prefix: "/api", 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,7 +96,7 @@ 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 })`.
@@ -109,8 +109,8 @@ export class TodoStore {
  * (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
+ * 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 }) => {

package/templates/service/package.json

@@ -5,14 +5,17 @@
   "type": "module",
   "scripts": {
     "dev": "vite-node app/main.ts",
-    "test": "vitest run"
+    "test": "vitest run",
+    "doctor": "nwire doctor",
+    "studio": "nwire studio",
+    "cache": "nwire cache"
   },
   "dependencies": {
-    "@nwire/app": "^0.11.1",
-    "@nwire/endpoint": "^0.11.1",
-    "@nwire/handler": "^0.11.1",
-    "@nwire/koa": "^0.11.1",
-    "@nwire/wires": "^0.11.1",
+    "@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",
     "koa": "^2.16.1",
     "zod": "^4.0.0"
   },
@@ -21,6 +24,7 @@
     "@types/node": "^22.19.9",
     "typescript": "^5.9.0",
     "vite-node": "^3.2.4",
-    "vitest": "^4.0.18"
+    "vitest": "^4.0.18",
+    "@nwire/cli": "^0.12.1"
   }
 }

package/templates/service/tsconfig.json

@@ -9,7 +9,7 @@
     "skipLibCheck": true,
     "forceConsistentCasingInFileNames": true,
     "noEmit": true,
-    "types": ["node", "vite/client"]
+    "types": ["node"]
   },
   "include": ["app/**/*", "__tests__/**/*"]
 }