create-nwire 0.12.1 → 0.13.1

package/dist/index.d.ts

@@ -8,7 +8,7 @@
  * Usage:
  *   pnpm create nwire <target-dir> [--template minimal|service|enterprise]
  */
-export type TemplateName = "minimal" | "service" | "enterprise";
+export type TemplateName = "minimal" | "service" | "enterprise" | "mcp";
 interface ScaffoldOptions {
     target: string;
     template: TemplateName;

package/dist/index.js

@@ -37,6 +37,10 @@ const TEMPLATES = {
         title: "Enterprise",
         blurb: "modules/<bc>/{events,actions,workflows,projections,routes}. Full forge shape.",
     },
+    mcp: {
+        title: "MCP",
+        blurb: "Model Context Protocol server over stdio. AI clients call tool() wires.",
+    },
 };
 function templatesRoot() {
     const candidate = resolve(__dirname, "..", "templates");
@@ -142,7 +146,7 @@ const main = defineCommand({
         },
         template: {
             type: "string",
-            description: "Template: minimal | service | enterprise",
+            description: "Template: minimal | service | enterprise | mcp",
             default: "service",
         },
         name: {
@@ -164,7 +168,7 @@ const main = defineCommand({
         }
         const template = resolveTemplateName(String(ctx.args.template));
         if (!template) {
-            console.error(pc.red(`unknown template "${ctx.args.template}". Use minimal, service, or enterprise.`));
+            console.error(pc.red(`unknown template "${ctx.args.template}". Use minimal, service, enterprise, or mcp.`));
             process.exit(1);
         }
         const target = resolve(process.cwd(), targetArg);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-nwire",
-  "version": "0.12.1",
+  "version": "0.13.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

@@ -10,15 +10,15 @@ gets real, forge adds events, actors, projections, and workflows.
 
 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` |
+| 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`, `forgePlugins` | `@nwire/forge`      |
 
 `defineResource` and `defineError` are in **`@nwire/handler`**, not
 `@nwire/forge` — even though forge re-exports some of them, import from
@@ -31,8 +31,8 @@ The most common mistake is importing a primitive from the wrong package:
 - **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] })`.
+- **Action** — a named command (`defineAction`) that is itself the handler
+  and may emit events from. Register via `createApp({ handlers: [act] })`.
 - **Actor** — a thing with identity that guards a rule. **Projection** — a
   read model folded from events. **Workflow** — a process that reacts over
   time.

package/templates/enterprise/README.md

@@ -16,19 +16,24 @@ pnpm dev
 
 ## Try
 
+`pnpm dev` serves the wire + Studio on http://localhost:4000.
+
 ```bash
 # submit a post (becomes pending, auto-moderation triggers)
-curl -X POST http://localhost:3000/api/posts \
+curl -X POST http://localhost:4000/api/posts \
   -H "content-type: application/json" \
   -d '{"authorId":"alice","body":"Hello, world!"}'
 
-# read the dashboard projection
-curl http://localhost:3000/api/queue
+# read the dashboard projection — copy a pending postId from here
+curl http://localhost:4000/api/queue
 
-# decide a borderline one manually
-curl -X POST http://localhost:3000/api/posts/<id>/approve \
+# decide one manually (paste the postId from /api/queue above)
+curl -X POST http://localhost:4000/api/posts/<postId>/approve \
   -H "content-type: application/json" \
   -d '{"moderatorId":"miri"}'
+
+# all posts by an author, across statuses
+curl "http://localhost:4000/api/posts/by-author?authorId=alice"
 ```
 
 ## Test
@@ -42,8 +47,8 @@ pnpm test
 ```
 {{PROJECT_NAME}}/
 ├── app/
-│   ├── main.ts                              ← endpoint + app.start + run
-│   ├── api.ts                               ← httpInterface — wires every route
+│   ├── main.ts                              ← endpoint().use(httpKoa()).mount(app).run()
+│   ├── api.ts                               ← wires[] — every route + handler pair
 │   └── app.ts                               ← createApp({ modules: [...] })
 ├── modules/
 │   └── posts/                               ← bounded context: posts moderation
@@ -90,11 +95,11 @@ actor (`defineActor`) versus a direct DB write inside a handler.
 
 ## Studio
 
-`api.inspect(app)` mounts the `/_nwire/*` introspection surface. Point
-Studio at this app:
+`pnpm dev` already serves Studio alongside the wire on http://localhost:4000.
+For the standalone Studio process (multi-project shell, process manager):
 
 ```bash
-npx -p @nwire/cli nwire studio
+pnpm studio
 ```
 
 You'll get live traces, action / event / workflow browsers, projection

package/templates/enterprise/__tests__/auto-moderate.test.ts

@@ -7,22 +7,38 @@
  * The workflow runs in-process (same runtime the route dispatches into),
  * so `await idle()` between submit + dashboard read is enough to observe
  * the post-decision state.
+ *
+ * Boots the app from `app.ts` (the pure value) on 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 { bootstrap } from "../app/main";
+import { endpoint } from "@nwire/endpoint";
+import { httpKoa } from "@nwire/koa";
+import { app } from "../app/app";
 
-let running: Awaited<ReturnType<typeof bootstrap>>;
+let running: Awaited<ReturnType<ReturnType<typeof endpoint>["run"]>>;
+let koa: ReturnType<typeof httpKoa>;
 let url: string;
 
 beforeAll(async () => {
-  running = await bootstrap({ port: 0, test: true });
-  url = `http://127.0.0.1:${running.koa.port()}`;
+  koa = httpKoa({ port: 0, prefix: "/api" });
+  running = await endpoint("auto-moderate-test", {
+    exitOnShutdown: false,
+    banner: false,
+    probes: { enabled: false },
+  })
+    .use(koa)
+    .mount(app)
+    .run();
+  url = `http://127.0.0.1:${koa.port()}`;
 });
 
 afterAll(async () => {
-  await running.running.shutdown("test");
-  await running.app.stop();
+  await running.shutdown("test");
+  await app.stop();
 });
 
 const idle = () => new Promise<void>((resolve) => setImmediate(resolve));

package/templates/enterprise/__tests__/submit-flow.test.ts

@@ -1,22 +1,38 @@
 /**
  * Happy path — submit a post via HTTP, verify the action runs, the
  * workflow + projection update the dashboard.
+ *
+ * Boots the app from `app.ts` (the pure value) on 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 { bootstrap } from "../app/main";
+import { endpoint } from "@nwire/endpoint";
+import { httpKoa } from "@nwire/koa";
+import { app } from "../app/app";
 
-let running: Awaited<ReturnType<typeof bootstrap>>;
+let running: Awaited<ReturnType<ReturnType<typeof endpoint>["run"]>>;
+let koa: ReturnType<typeof httpKoa>;
 let url: string;
 
 beforeAll(async () => {
-  running = await bootstrap({ port: 0, test: true });
-  url = `http://127.0.0.1:${running.koa.port()}`;
+  koa = httpKoa({ port: 0, prefix: "/api" });
+  running = await endpoint("submit-flow-test", {
+    exitOnShutdown: false,
+    banner: false,
+    probes: { enabled: false },
+  })
+    .use(koa)
+    .mount(app)
+    .run();
+  url = `http://127.0.0.1:${koa.port()}`;
 });
 
 afterAll(async () => {
-  await running.running.shutdown("test");
-  await running.app.stop();
+  await running.shutdown("test");
+  await app.stop();
 });
 
 const idle = () => new Promise<void>((resolve) => setImmediate(resolve));

package/templates/enterprise/app/api.ts

@@ -3,7 +3,7 @@
  *
  * Every route file under `../modules/posts/routes/` exports a
  * `{name}Route` (binding) + `{name}Handler` (function). The `wires`
- * array is what main.ts feeds into `app.wire(...)`.
+ * array feeds into `app.wire(...)` in `app.ts`.
  */
 
 import { submitPostRoute, submitPostHandler } from "../modules/posts/routes/submit-post";
@@ -11,11 +11,15 @@ import { approvePostRoute, approvePostHandler } from "../modules/posts/routes/ap
 import { rejectPostRoute, rejectPostHandler } from "../modules/posts/routes/reject-post";
 import { listQueueRoute, listQueueHandler } from "../modules/posts/routes/list-queue";
 import { getPostRoute, getPostHandler } from "../modules/posts/routes/get-post";
+import { postsByAuthorRoute, postsByAuthorHandler } from "../modules/posts/routes/posts-by-author";
 
 export const wires = [
   { binding: submitPostRoute, handler: submitPostHandler },
   { binding: approvePostRoute, handler: approvePostHandler },
   { binding: rejectPostRoute, handler: rejectPostHandler },
   { binding: listQueueRoute, handler: listQueueHandler },
+  // Literal `/posts/by-author` must be wired before the `/posts/:postId`
+  // param route — otherwise `:postId` captures "by-author" and shadows it.
+  { binding: postsByAuthorRoute, handler: postsByAuthorHandler },
   { binding: getPostRoute, handler: getPostHandler },
 ] as const;

package/templates/enterprise/app/app.ts

@@ -1,18 +1,23 @@
 /**
- * `buildApp` composes the posts bounded context into a runnable App.
+ * App — the posts bounded context as a pure value.
  *
- * Each piece (events, actions, workflows, projections, queries) is
- * imported directly; `.with(createForgePlugin(...))` installs forge with
- * the handlers, workflows, projections, and queries the BC needs.
+ * `createApp` installs the forge plugin set (workflows + projections) and
+ * wires all HTTP 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.
  *
- * For multi-BC apps, build each as its own App and compose:
+ * Tests import `{ app }` from this file and build an isolated endpoint per
+ * suite. Never import `main.ts` from tests: it starts the server and hangs
+ * the runner.
+ *
+ * Multi-BC: build each as its own App and compose at the endpoint:
  *
  *   const monolith = appCompose(postsApp, ordersApp);
- *   await endpoint("monolith", { port: 3000 }).use(httpKoa()).mount(monolith).run();
+ *   await endpoint("monolith", { port }).use(httpKoa()).mount(monolith).run();
  */
 
 import { createApp } from "@nwire/app";
-import { createForgePlugin } from "@nwire/forge";
+import { forgePlugins } from "@nwire/forge";
 
 import { submitPost } from "../modules/posts/actions/submit-post";
 import { approvePost } from "../modules/posts/actions/approve-post";
@@ -25,16 +30,19 @@ import {
   getPost,
 } from "../modules/posts/projections/queue-dashboard";
 import { postsByAuthor } from "../modules/posts/queries/posts-by-author";
+import { wires } from "./api";
 
-export function buildApp() {
-  return createApp({ appName: "{{PROJECT_NAME}}" }).with(
-    createForgePlugin({
-      handlers: [submitPost.handler!, approvePost.handler!, rejectPost.handler!],
+export const app = createApp({
+  appName: "{{PROJECT_NAME}}",
+  handlers: [submitPost, approvePost, rejectPost, listPending, queueTotals, getPost, postsByAuthor],
+  plugins: [
+    ...forgePlugins({
       workflows: [autoModerate],
       projections: [queueDashboard],
-      queries: [listPending, queueTotals, getPost, postsByAuthor],
     }),
-  );
-}
+  ],
+});
 
-export const app = buildApp();
+for (const { binding, handler } of wires) {
+  app.wire(binding, handler);
+}

package/templates/enterprise/app/main.ts

@@ -1,55 +1,30 @@
 /**
- * Entry — boot the app under HTTP.
+ * Entry — the only file that boots a real HTTP server.
  *
- *   1. buildApp composes the App with forge (handlers, workflows,
- *      projections, queries) via `.with(createForgePlugin(...))`.
- *   2. app.wire(...) pairs every route binding with its handler.
- *   3. endpoint().use(httpKoa({prefix:"/api"})).mount(app).run() starts
- *      the HTTP listener + graceful drain + K8s probes.
+ *   pnpm dev   # wire + Studio on http://localhost:4000
  *
- * Once running:
- *   - HTTP POST /api/posts → submitPost action → PostWasSubmitted event
- *   - autoModerate workflow picks up the event, runs auto-check, dispatches
- *     approve/reject if obvious
- *   - queueDashboard projection folds all three events into state
- *   - HTTP GET /api/queue reads from the projection
+ *   curl -X POST http://localhost:4000/api/posts \
+ *        -H "content-type: application/json" \
+ *        -d '{"authorId":"alice","body":"Hello, world!"}'
+ *   curl http://localhost:4000/api/queue
  *
- * Run:    pnpm dev
- * Try:    curl -X POST http://localhost:3000/api/posts \
- *               -H "content-type: application/json" \
- *               -d '{"authorId":"alice","body":"Hello, world!"}'
- *         curl http://localhost:3000/api/queue
+ * `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 { endpoint } from "@nwire/endpoint";
 import { httpKoa } from "@nwire/koa";
-import { buildApp } from "./app";
-import { wires } from "./api";
+import { appConfig } from "../config/app";
+import { httpConfig } from "../config/http";
+import { app } from "./app";
 
-export interface BootstrapOptions {
-  readonly port?: number;
-  readonly test?: boolean;
-}
+const cfg = appConfig();
+const http = httpConfig();
 
-export async function bootstrap(opts: number | BootstrapOptions = 3000) {
-  const { port = 3000, test = false } =
-    typeof opts === "number" ? { port: opts, test: false } : opts;
-
-  const app = buildApp();
-  for (const { binding, handler } of wires) {
-    app.wire(binding, handler);
-  }
-  await app.start();
-  const koa = httpKoa({ port, prefix: "/api" });
-  const running = await endpoint("{{PROJECT_NAME}}", {
-    exitOnShutdown: !test,
-    banner: !test,
-    probes: { enabled: !test },
-  })
-    .use(koa)
-    .mount(app)
-    .run();
-  return { app, running, koa };
-}
-
-await bootstrap();
+await endpoint(cfg.name, { port: cfg.port, banner: cfg.banner })
+  .use(httpKoa({ prefix: http.prefix }))
+  .mount(app)
+  .run();

package/templates/enterprise/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/enterprise/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/enterprise/config/http.ts

@@ -0,0 +1,15 @@
+/**
+ * HTTP transport settings — prefix 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/posts`. */
+  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/enterprise/modules/posts/actions/approve-post.ts

@@ -13,13 +13,14 @@ import { PostWasApproved } from "../events/post-was-approved";
 
 export const approvePost = defineAction({
   name: "posts.approve-post",
-  description: "Approve a post — either by a human moderator or the auto-moderation workflow.",
-  schema: z.object({
+  description:
+    "Miri reviews the post and approves it — or the auto-check clears it so Alice doesn't have to wait.",
+  input: z.object({
     postId: z.string(),
     approvedBy: z.string(),
   }),
   emits: [PostWasApproved],
-  handler: async (input) =>
+  handler: async ({ input }) =>
     PostWasApproved({
       postId: input.postId,
       approvedBy: input.approvedBy,

package/templates/enterprise/modules/posts/actions/reject-post.ts

@@ -12,14 +12,14 @@ import { PostWasRejected } from "../events/post-was-rejected";
 
 export const rejectPost = defineAction({
   name: "posts.reject-post",
-  description: "Reject a post with a stated reason.",
-  schema: z.object({
+  description: "Miri (or the auto-check) rejects the post with a reason Alice can see and act on.",
+  input: z.object({
     postId: z.string(),
     rejectedBy: z.string(),
     reason: z.string().min(1).max(500),
   }),
   emits: [PostWasRejected],
-  handler: async (input) =>
+  handler: async ({ input }) =>
     PostWasRejected({
       postId: input.postId,
       rejectedBy: input.rejectedBy,

package/templates/enterprise/modules/posts/actions/submit-post.ts

@@ -25,13 +25,14 @@ import { PostWasSubmitted } from "../events/post-was-submitted";
 
 export const submitPost = defineAction({
   name: "posts.submit-post",
-  description: "Author submits a draft to the moderation queue.",
-  schema: z.object({
+  description:
+    "Alice drafts a post and submits it for moderation — she's waiting to see if it gets through.",
+  input: z.object({
     authorId: z.string(),
     body: z.string().min(1).max(2000),
   }),
   emits: [PostWasSubmitted],
-  handler: async (input) =>
+  handler: async ({ input }) =>
     PostWasSubmitted({
       postId: randomUUID(),
       authorId: input.authorId,

package/templates/enterprise/modules/posts/events/post-was-approved.ts

@@ -11,7 +11,7 @@ import { defineEvent } from "@nwire/messages";
 
 export const PostWasApproved = defineEvent({
   name: "posts.post-was-approved",
-  description: "A moderator (or the auto-moderation workflow) approves a post.",
+  description: "The post cleared moderation — Alice's words are now visible to readers.",
   outcome: "success",
   audience: ["product", "ops"],
   schema: z.object({

package/templates/enterprise/modules/posts/events/post-was-rejected.ts

@@ -8,7 +8,8 @@ import { defineEvent } from "@nwire/messages";
 
 export const PostWasRejected = defineEvent({
   name: "posts.post-was-rejected",
-  description: "A moderator (or the auto-moderation workflow) rejects a post.",
+  description:
+    "The post was turned away — Miri or the auto-check flagged it, and Alice sees the reason.",
   outcome: "failure",
   audience: ["product", "ops"],
   schema: z.object({

package/templates/enterprise/modules/posts/events/post-was-submitted.ts

@@ -15,7 +15,8 @@ import { defineEvent } from "@nwire/messages";
 
 export const PostWasSubmitted = defineEvent({
   name: "posts.post-was-submitted",
-  description: "An author drafts a post and submits it for moderation.",
+  description:
+    "Alice drafts a post and submits it for moderation — she's waiting to see if it gets through.",
   outcome: "milestone",
   audience: ["product", "ops"],
   schema: z.object({