spfn 0.3.0-beta.2 → 0.3.0-beta.4

package/README.md

@@ -2,7 +2,7 @@
 
 `spfn` takes a Next.js idea from prototype to production with a consistent full-stack
 architecture. It can scaffold either a core-only backend or a production baseline with
-authentication, internationalization, and an agent-facing MCP endpoint, then runs the
+authentication, internationalization, and a terminal operations surface, then runs the
 dev/build/start lifecycle, database tooling, RPC codegen, and environment validation.
 
 Consistent is the point rather than a nicety: what it scaffolds is one fixed shape per
@@ -31,7 +31,7 @@ is not supported — see [the root README](../../README.md#what-do-i-need-instal
 ## Usage
 
 ```bash
-# Prototype-to-Production baseline: core + auth + i18n + MCP
+# Prototype-to-Production baseline: core + auth + i18n + ops
 npx spfn@beta create my-app --mode full
 cd my-app
 docker compose up -d            # Postgres + Redis
@@ -71,7 +71,7 @@ pass `--mode full`.
 |--------|-------------|
 | `--pm <manager>` | Force package manager: `npm` \| `pnpm` \| `yarn` \| `bun` |
 | `--shadcn` | Also run `shadcn init` |
-| `--mode <mode>` | `bare` (core only) \| `full` (core, auth, i18n, MCP) |
+| `--mode <mode>` | `bare` (core only) \| `full` (core, auth, i18n, ops) |
 | `--skip-install` | Skip dependency install |
 | `--skip-git` | Skip `git init` |
 | `-y, --yes` | Skip prompts, use defaults |
@@ -86,7 +86,7 @@ already exists). See [Scaffold structure](#scaffold-structure) for what lands on
 
 | Option | Description |
 |--------|-------------|
-| `--mode <mode>` | `bare` (core only) \| `full` (core, auth, i18n, MCP) |
+| `--mode <mode>` | `bare` (core only) \| `full` (core, auth, i18n, ops) |
 | `-y, --yes` | Skip prompts, use defaults |
 
 Generated projects pin `drizzle-orm` and `drizzle-kit` to `1.0.0-rc.4`, matching
@@ -134,9 +134,8 @@ no pre-build needed.
 |--------|-------------|---------|
 | `--server-only` | Run only the SPFN/Hono server (also auto-selected if Next.js isn't a dependency) | off |
 | `--watch` | Restart the server on `src/server` changes (chokidar) | off |
-| `-p, --port <port>` | Server port | from `server.config.ts` / env (`4000` in server-only fallback) |
-| `-H, --host <host>` | Server host | `localhost` |
-| `--routes <path>` | Routes directory path | server default |
+| `-p, --port <port>` | SPFN server port (sets `SPFN_PORT`) | `spfn.config.js` `ports.server`, then `8790` |
+| `-H, --host <host>` | SPFN server host (sets `SPFN_HOST`) | `spfn.config.js` `host`, then `localhost` |
 | `--allow-pending-migrations` | Start even when migrations are pending (they are listed as a warning) | off |
 
 Note: hot reload is **off by default** — pass `--watch` to restart on file changes.
@@ -165,11 +164,19 @@ if `.spfn/server`, `.spfn/prod-server.mjs`, or `.next` are missing.
 |--------|-------------|---------|
 | `--server-only` | Run only the SPFN server | off |
 | `--next-only` | Run only Next.js | off |
-| `-p, --port <port>` | SPFN server port (sets `SPFN_PORT`) | `8790` |
-| `-h, --host <host>` | SPFN server host (sets `SPFN_HOST`) | `0.0.0.0` |
+| `-p, --port <port>` | SPFN server port (sets `SPFN_PORT`) | `spfn.config.js` `ports.server`, then `8790` |
+| `-h, --host <host>` | SPFN server host (sets `SPFN_HOST`) | `spfn.config.js` `host`, then `localhost` |
 | `--allow-pending-migrations` | Start even when migrations are pending (they are listed as a warning) | off |
 
-Next.js is started on `0.0.0.0:3790`. Both run together via `concurrently --kill-others`.
+Both run together via `concurrently --kill-others`.
+
+Neither flag has a default value, deliberately. A default is indistinguishable
+from a value the operator typed, and it was forwarded as `SPFN_PORT` either way —
+which overrode the app's own configuration. Pass nothing and `spfn.config.js`
+decides; pass a flag and it wins.
+
+Next.js is started on the port `spfn.config.js` gives as `ports.next` (`3790` by
+default), overridable with `NEXT_PORT`.
 
 Pending migrations stop the boot unless `--allow-pending-migrations` or
 `SPFN_ALLOW_PENDING_MIGRATIONS=true` is set — see [Database](#spfn-db). `--next-only`
@@ -491,24 +498,30 @@ src/
   app/auth/callback/page.tsx         # OAuth session handoff
   i18n/catalogs.ts                   # application-owned en/ko starter messages
   i18n/server.ts                     # configured server-side i18n registry
-  server/mcp.ts                      # authenticated /mcp endpoint + starter app_status tool
-  server/router.ts                   # authRouter + mcpRouter + global authenticate
+  server/routes/ops.ts               # ops routes under /_ops + the manifest `spfn ops` reads
+  server/router.ts                   # authRouter + opsRouter + global authenticate
   server/server.config.ts            # createAuthLifecycle + i18n startup
 next.config.ts                       # /_auth/* callback rewrite
 .env.local                           # generated auth session secret (gitignored)
-.env.server                          # auth keyring + MCP operator key (gitignored)
+.env.server                          # auth keyring (gitignored)
 ```
 
 The full RPC proxy imports the auth interceptor and merges `authRouteMap`. Internal auth
-and MCP keys are generated with cryptographic randomness in ignored local env files;
+keys are generated with cryptographic randomness in ignored local env files;
 `.env.example` contains placeholders only. Add only the provider keys you use, then run
-`pnpm spfn db migrate`. The starter MCP endpoint accepts `SPFN_MCP_API_KEY` as a Bearer
-token for first-party operation; replace that validator with OAuth before third-party access.
+`pnpm spfn db migrate`.
+
+Operating the app is [`spfn ops`](#spfn-ops), not a dashboard: the starter
+`src/server/routes/ops.ts` exposes two read commands, and `spfn ops` discovers them from
+the running server's manifest. Issuing the first token signs in as an administrator, so
+uncomment `SPFN_AUTH_ADMIN_ACCOUNTS` in `.env.server` and restart before
+`spfn ops token issue`. The ops surface adds no dependency — the router comes from
+`@spfn/core/ops` and the tokens from `@spfn/auth`.
 
 `init` also patches `package.json` (scripts: `spfn:dev`, `spfn:server`, `spfn:next`,
 `spfn:build`, `spfn:start`, `codegen`; deps: `@spfn/core`, `spfn`, `drizzle-orm`,
 `@sinclair/typebox`, `concurrently`, etc.; full also adds `@spfn/auth`, `@spfn/i18n`,
-`@spfn/mcp`, auth's `@spfn/notification` peer, and a Node `>=20.0.0` engine when the
+auth's `@spfn/notification` peer, and a Node `>=20.0.0` engine when the
 existing range still permits older Node versions), excludes `src/server` from the root
 `tsconfig.json` (Vercel compat), and adds `.spfn/`, `.env.local`, `.env.server` to
 `.gitignore`.
@@ -580,7 +593,7 @@ docker compose -f docker-compose.production.yml up --build -d
 
 The Dockerfile (`node:22-alpine`) installs with `pnpm --frozen-lockfile`, runs
 `pnpm run spfn:build`, prunes dev deps, exposes `3790`/`8790`, health-checks
-`http://localhost:8790/health`, and starts via `pnpm run spfn:start`.
+`http://localhost:8790/_core/health`, and starts via `pnpm run spfn:start`.
 
 Run migrations against the target DB before/with deploy:
 
@@ -595,7 +608,7 @@ the gate is one that never served the 500s. If a rollout has to proceed anyway,
 logged as a warning instead.
 
 A readiness probe can catch the same drift on a cluster the local gate never sees. When
-detailed health is on, `GET /health` carries a `migrations` object with per-package
+detailed health is on, `GET /_core/health` carries a `migrations` object with per-package
 applied/pending counts — assert `migrations.pending === 0` in the probe to hold a
 drifted pod out of rotation. Reporting drift does not, by itself, change the overall
 health `status`.
@@ -614,8 +627,8 @@ type ships from `spfn` (`@type {import('spfn').SpfnConfig}`).
 something with an AI coding agent and now want a real backend under it, `init` is the one.
 
 **`bare` or `full`?**
-`full` is the recommended baseline: core, auth, i18n and MCP wired together, so you get a
-working authenticated app on day one. `bare` is core only — the architecture with nothing
+`full` is the recommended baseline: core, auth, i18n and the ops surface wired together, so
+you get a working authenticated app on day one, operable from the terminal. `bare` is core only — the architecture with nothing
 else decided. Automation should always pass `--mode` explicitly, because a `--yes` run
 without one still produces `bare` for backward compatibility.
 
@@ -630,7 +643,7 @@ pointing at your own PostgreSQL works too. PostgreSQL itself is not optional.
 
 **Which Node version do I need?**
 20 or later, in both modes. `@spfn/core` runs on `@hono/node-server` 2, which declares
-that floor, and full mode's MCP server needs the same.
+that floor, and full mode's `@spfn/auth` needs the same.
 
 **When do I have to run codegen by hand?**
 Whenever routes change outside `spfn dev`, which runs a codegen watcher for you. A stale or
@@ -678,5 +691,6 @@ committed.
 
 - [`@spfn/core`](../core/README.md) — server, route DSL, codegen, db, client runtime.
 - [`@spfn/auth`](../auth/README.md) — what `--mode full` wires in for accounts and roles.
-- [`@spfn/mcp`](../mcp/README.md) — what `--mode full` wires in for operating the app.
+- [`@spfn/mcp`](../mcp/README.md) — an agent-facing MCP endpoint, added on demand with
+  `spfn add @spfn/mcp`.
 - Project root README — framework overview and getting started.

package/dist/index.js

@@ -103,7 +103,7 @@ async function selectScaffoldMode(options) {
     choices: [
       {
         title: "full (recommended)",
-        description: "Core, auth, i18n, and MCP \u2014 ready for Prototype to Production",
+        description: "Core, auth, i18n, and ops CLI \u2014 ready for Prototype to Production",
         value: "full"
       },
       {
@@ -808,11 +808,33 @@ async function setupDeploymentConfig(cwd, packageJson, packageManager) {
       const configContent = `/**
  * SPFN Configuration
  *
- * This file configures your SPFN application deployment settings.
+ * This file describes how your app is served and deployed. It is committed, so
+ * keep secrets out of it.
  *
  * @type {import('spfn').SpfnConfig}
  */
 export default {
+  /**
+   * Ports the two processes bind.
+   *
+   * This is the only place either number is written. The Dockerfile, the
+   * compose file and \`spfn dev\` / \`spfn start\` all read it, so changing a
+   * port here changes it everywhere.
+   *
+   * Overridable per environment with NEXT_PORT and SPFN_PORT \u2014 a container
+   * setting one of those wins over what is written here.
+   */
+  ports: {
+    next: 3790,
+    server: 8790,
+  },
+
+  /**
+   * Host the SPFN API server binds. A container sets SPFN_HOST=0.0.0.0; a
+   * developer machine has no reason to publish its dev server to the network.
+   */
+  host: 'localhost',
+
   /**
    * Package manager to use for dependency installation
    * Options: 'npm' | 'yarn' | 'pnpm' | 'bun'
@@ -922,7 +944,7 @@ var init_deployment_config = __esm({
 
 // src/utils/version.ts
 function getCliVersion() {
-  return "0.3.0-beta.2";
+  return "0.3.0-beta.4";
 }
 function getTagFromVersion(version) {
   const match = version.match(/-([a-z]+)\./i);
@@ -966,7 +988,6 @@ async function setupPackageJson(cwd, packageJsonPath, packageJson, packageManage
   if (mode === "full") {
     packageJson.dependencies["@spfn/auth"] = spfnTag;
     packageJson.dependencies["@spfn/i18n"] = spfnTag;
-    packageJson.dependencies["@spfn/mcp"] = spfnTag;
     packageJson.dependencies["@spfn/notification"] = spfnTag;
   }
   packageJson.devDependencies["@types/node"] = "^20.11.0";
@@ -982,7 +1003,7 @@ async function setupPackageJson(cwd, packageJsonPath, packageJson, packageManage
   }
   packageJson.scripts["spfn:dev"] = "spfn dev";
   packageJson.scripts["spfn:server"] = "spfn dev --server-only";
-  packageJson.scripts["spfn:next"] = "next dev --turbo --port 3790";
+  packageJson.scripts["spfn:next"] = "next dev --turbo";
   packageJson.scripts["spfn:start"] = "spfn start";
   packageJson.scripts["spfn:build"] = "spfn build";
   packageJson.scripts["codegen"] = "spfn codegen run";
@@ -1165,9 +1186,12 @@ SPFN_AUTH_TOKEN_ENCRYPTION_KEYS=v1:${randomSecret("base64")}
 # SPFN_AUTH_NAVER_CLIENT_ID=your-naver-client-id
 # SPFN_AUTH_NAVER_CLIENT_SECRET=your-naver-client-secret
 
-# Full scaffold: MCP operator endpoint
-SPFN_MCP_URL=http://localhost:8790
-SPFN_MCP_API_KEY=${randomSecret("base64url")}
+# Full scaffold: ops CLI (spfn ops)
+# Ops commands need no variable of their own \u2014 they authenticate with a token
+# issued by \`spfn ops token issue\`, and issuing one signs in as an administrator.
+# Uncomment to seed that administrator on the next server start, then remove the
+# password once the account exists.
+# SPFN_AUTH_ADMIN_ACCOUNTS=[{"email":"admin@example.com","password":"replace-with-a-strong-password","role":"admin"}]
 `;
 }
 function randomSecret(encoding) {
@@ -1397,9 +1421,12 @@ SPFN_AUTH_TOKEN_ENCRYPTION_KEYS=v1:replace-with-a-base64-encoded-32-byte-key
 # SPFN_AUTH_NAVER_CLIENT_ID=your-naver-client-id
 # SPFN_AUTH_NAVER_CLIENT_SECRET=your-naver-client-secret
 
-# Full scaffold: MCP operator endpoint
-SPFN_MCP_URL=http://localhost:8790
-SPFN_MCP_API_KEY=replace-with-a-random-operator-key
+# Full scaffold: ops CLI (spfn ops)
+# Ops commands need no variable of their own \u2014 they authenticate with a token
+# issued by \`spfn ops token issue\`, and issuing one signs in as an administrator.
+# Uncomment to seed that administrator on the next server start, then remove the
+# password once the account exists.
+# SPFN_AUTH_ADMIN_ACCOUNTS=[{"email":"admin@example.com","password":"replace-with-a-strong-password","role":"admin"}]
 `;
   }
 });
@@ -1483,7 +1510,7 @@ async function initializeSpfn(options = {}) {
   console.log(`  ${mode === "full" ? "4" : "3"}. Run: ` + chalk4.cyan(`${getRunCommand(pm)} spfn:dev`));
   console.log(`  ${mode === "full" ? "5" : "4"}. Visit:`);
   console.log("     - Next.js: " + chalk4.cyan("http://localhost:3790"));
-  console.log("     - API:     " + chalk4.cyan("http://localhost:8790/health"));
+  console.log("     - API:     " + chalk4.cyan("http://localhost:8790/_core/health"));
   if (mode === "full") {
     console.log("     - MCP:     " + chalk4.cyan("http://localhost:8790/mcp"));
   }
@@ -2122,6 +2149,7 @@ async function resolveKeychainEnv(cwd) {
 }
 
 // src/commands/dev.ts
+import { loadAppConfig, resolvePorts, resolveHost } from "@spfn/core/app-config";
 function ignoreDotfilesUnder(root) {
   return (watchedPath) => relative(root, watchedPath).split(sep2).some((segment) => segment.startsWith(".") && segment !== "." && segment !== "..");
 }
@@ -2145,13 +2173,22 @@ function waitForReadyFile(filePath, timeoutMs = 3e4) {
     });
   });
 }
-var devCommand = new Command4("dev").description("Start SPFN development server (detects and runs Next.js + Hono)").option("-p, --port <port>", "Server port").option("-H, --host <host>", "Server host").option("--routes <path>", "Routes directory path").option("--server-only", "Run only Hono server (skip Next.js)").option("--watch", "Enable hot reload (watch mode)").option("--allow-pending-migrations", "Start even when migrations are pending (they are listed as a warning)").action(async (options) => {
+var devCommand = new Command4("dev").description("Start SPFN development server (detects and runs Next.js + Hono)").option("-p, --port <port>", "Server port").option("-H, --host <host>", "Server host").option("--server-only", "Run only Hono server (skip Next.js)").option("--watch", "Enable hot reload (watch mode)").option("--allow-pending-migrations", "Start even when migrations are pending (they are listed as a warning)").action(async (options) => {
   process.setMaxListeners(20);
   if (!process.env.NODE_ENV) {
     process.env.NODE_ENV = "development";
   }
   const cwd = process.cwd();
   const serverDir = join15(cwd, "src", "server");
+  if (options.port) {
+    process.env.SPFN_PORT = String(options.port);
+  }
+  if (options.host) {
+    process.env.SPFN_HOST = String(options.host);
+  }
+  const appConfig = await loadAppConfig(cwd);
+  const { next: nextPort, server: serverPort } = resolvePorts(appConfig);
+  const serverHost = resolveHost(appConfig);
   if (!existsSync14(serverDir)) {
     logger.error("src/server directory not found.");
     logger.info('Run "spfn init" first to initialize SPFN in your project.');
@@ -2197,11 +2234,7 @@ var devCommand = new Command4("dev").description("Start SPFN development server
   if (existsSync14(readySignal)) {
     unlinkSync(readySignal);
   }
-  const configParts = [];
-  if (options.port) configParts.push(`port: ${options.port}`);
-  if (options.host) configParts.push(`host: '${options.host}'`);
-  if (options.routes) configParts.push(`routesPath: '${options.routes}'`);
-  configParts.push("debug: true");
+  const configParts = ["debug: true"];
   const readyFile = join15(tempDir, "server-ready");
   writeFileSync10(serverEntry, `
 import { writeFileSync } from 'fs';
@@ -2274,9 +2307,7 @@ catch (error)
   const pm = detectPackageManager(cwd);
   if (options.serverOnly || !hasNext) {
     const watchMode2 = options.watch === true;
-    const host = options.host ?? process.env.HOST ?? "localhost";
-    const port = options.port ?? process.env.PORT ?? "4000";
-    logger.info(`Starting SPFN Server on http://${host}:${port}${watchMode2 ? " (watch mode)" : ""}
+    logger.info(`Starting SPFN Server on http://${serverHost}:${serverPort}${watchMode2 ? " (watch mode)" : ""}
 `);
     let serverProcess2 = null;
     let watcherProcess2 = null;
@@ -2392,7 +2423,7 @@ catch (error)
   };
   const startNext = () => {
     const nextCmd = pm === "npm" ? "npm" : pm;
-    const nextArgs = pm === "npm" ? ["run", "spfn:next"] : ["run", "spfn:next"];
+    const nextArgs = ["run", "spfn:next", "--", "--port", String(nextPort)];
     nextProcess = execa6(nextCmd, nextArgs, {
       cwd,
       stdio: "inherit",
@@ -2498,6 +2529,19 @@ import { execa as execa7 } from "execa";
 import ora5 from "ora";
 import chalk7 from "chalk";
 import { build } from "tsup";
+function renderProdServerEntry() {
+  return `// Load environment variables FIRST (before any imports that depend on them)
+// Use centralized environment loader for standard dotenv priority
+await import('@spfn/core/config');
+
+// Now import server (logger singleton will be created with correct NODE_ENV)
+const { startServer } = await import('@spfn/core/server');
+
+// No address here on purpose: SPFN_PORT / SPFN_HOST and spfn.config.js decide,
+// and startServer reads both.
+await startServer({ debug: false });
+`;
+}
 async function buildProject(options) {
   if (!process.env.NODE_ENV) {
     process.env.NODE_ENV = "production";
@@ -2571,6 +2615,12 @@ async function buildProject(options) {
         entry: ["src/server/**/*.ts"],
         format: ["esm"],
         outDir: ".spfn/server",
+        // Pin the extension. Left to tsup it follows the app's
+        // package.json — `.mjs` normally, `.js` under
+        // `"type": "module"` — and @spfn/core looks the compiled
+        // server.config up by name, so an app that declared that field
+        // shipped a production server running on defaults.
+        outExtension: () => ({ js: ".mjs" }),
         clean: true,
         splitting: false,
         tsconfig: "src/server/tsconfig.json",
@@ -2590,29 +2640,7 @@ async function buildProject(options) {
         }
       });
       const prodServerPath = join16(cwd, ".spfn", "prod-server.mjs");
-      const prodServerContent = `// Load environment variables FIRST (before any imports that depend on them)
-// Use centralized environment loader for standard dotenv priority
-const { env } = await import('@spfn/core/config');
-
-// Now import server (logger singleton will be created with correct NODE_ENV)
-const { startServer } = await import('@spfn/core/server');
-import { join } from 'path';
-import { fileURLToPath } from 'url';
-import { dirname } from 'path';
-
-const __dirname = dirname(fileURLToPath(import.meta.url));
-
-// Environment variables: from .env files OR injected by container/kubernetes
-const port = env.SPFN_PORT || '8790';
-const host = env.SPFN_HOST || '0.0.0.0';
-
-await startServer({
-    port: Number(port),
-    host,
-    routesPath: join(__dirname, 'server', 'routes'),
-    debug: false
-});
-`;
+      const prodServerContent = renderProdServerEntry();
       writeFileSync11(prodServerPath, prodServerContent);
       spinner.succeed(`SPFN server build completed \u2192 .spfn/server`);
       const routesDir = join16(cwd, ".spfn", "server", "routes");
@@ -2676,7 +2704,8 @@ import { existsSync as existsSync16, readFileSync as readFileSync8 } from "fs";
 import { join as join17 } from "path";
 import { execa as execa8 } from "execa";
 import chalk8 from "chalk";
-var startCommand = new Command6("start").description("Start SPFN production server (Next.js + Hono)").option("--server-only", "Run only SPFN server (skip Next.js)").option("--next-only", "Run only Next.js (skip SPFN server)").option("-p, --port <port>", "Server port", "8790").option("-h, --host <host>", "Server host", "0.0.0.0").option("--allow-pending-migrations", "Start even when migrations are pending (they are listed as a warning)").action(async (options) => {
+import { loadAppConfig as loadAppConfig2, resolvePorts as resolvePorts2 } from "@spfn/core/app-config";
+var startCommand = new Command6("start").description("Start SPFN production server (Next.js + Hono)").option("--server-only", "Run only SPFN server (skip Next.js)").option("--next-only", "Run only Next.js (skip SPFN server)").option("-p, --port <port>", "SPFN server port (default: spfn.config.js ports.server, then 8790)").option("-h, --host <host>", "SPFN server host (default: spfn.config.js host, then localhost)").option("--allow-pending-migrations", "Start even when migrations are pending (they are listed as a warning)").action(async (options) => {
   if (!process.env.NODE_ENV) {
     process.env.NODE_ENV = "production";
   }
@@ -2705,8 +2734,13 @@ var startCommand = new Command6("start").description("Start SPFN production serv
     logger.error('.spfn/prod-server.mjs not found. Please run "spfn build" first.');
     process.exit(1);
   }
-  process.env.SPFN_PORT = options.port;
-  process.env.SPFN_HOST = options.host;
+  if (options.port) {
+    process.env.SPFN_PORT = options.port;
+  }
+  if (options.host) {
+    process.env.SPFN_HOST = options.host;
+  }
+  const nextPort = resolvePorts2(await loadAppConfig2(cwd)).next;
   if (!options.nextOnly) {
     const { checkPendingMigrationsBeforeStart: checkPendingMigrationsBeforeStart2 } = await Promise.resolve().then(() => (init_migration_status(), migration_status_exports));
     const migrationCheck = await checkPendingMigrationsBeforeStart2(
@@ -2722,8 +2756,7 @@ var startCommand = new Command6("start").description("Start SPFN production serv
     }
   }
   if (options.serverOnly || !hasNext) {
-    logger.info(`Starting SPFN Server (production) on http://${options.host}:${options.port}
-`);
+    logger.info("Starting SPFN Server (production)\n");
     try {
       await execa8("node", [serverEntry], {
         stdio: "inherit",
@@ -2737,9 +2770,10 @@ var startCommand = new Command6("start").description("Start SPFN production serv
     return;
   }
   if (options.nextOnly) {
-    logger.info("Starting Next.js (production) on http://0.0.0.0:3790\n");
+    logger.info(`Starting Next.js (production) on http://0.0.0.0:${nextPort}
+`);
     try {
-      await execa8("npx", ["next", "start", "-H", "0.0.0.0", "-p", "3790"], {
+      await execa8("npx", ["next", "start", "-H", "0.0.0.0", "-p", String(nextPort)], {
         stdio: "inherit",
         cwd
       });
@@ -2749,12 +2783,11 @@ var startCommand = new Command6("start").description("Start SPFN production serv
     }
     return;
   }
-  const nextCmd = "next start -H 0.0.0.0 -p 3790";
+  const nextCmd = `next start -H 0.0.0.0 -p ${nextPort}`;
   const serverCmd = `node "${serverEntry}"`;
   console.log(chalk8.blue.bold("\n\u{1F680} Starting SPFN production server...\n"));
-  logger.info("Next.js: http://0.0.0.0:3790");
-  logger.info(`SPFN API: http://${options.host}:${options.port}
-`);
+  logger.info(`Next.js: http://0.0.0.0:${nextPort}`);
+  logger.info("SPFN API: announced by the server below\n");
   try {
     await execa8(
       pm === "npm" ? "npx" : pm,

package/dist/templates/Dockerfile

@@ -24,12 +24,15 @@ RUN pnpm prune --prod
 # Environment
 ENV NODE_ENV=production
 
-# Expose ports
+# Expose ports. Docker cannot read spfn.config.js, so these two numbers are the
+# one place they are repeated — keep them in step with `ports` in that file, or
+# set NEXT_PORT / SPFN_PORT here and in the compose file instead.
 EXPOSE 3790 8790
 
-# Health check
+# Health check. Falls back to the same default the framework uses, so setting
+# SPFN_PORT alone moves both the server and its probe.
 HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
-  CMD node -e "require('http').get('http://localhost:8790/health', (r) => {process.exit(r.statusCode === 200 ? 0 : 1)})"
+  CMD node -e "require('http').get('http://localhost:'+(process.env.SPFN_PORT||8790)+'/_core/health', (r) => {process.exit(r.statusCode === 200 ? 0 : 1)})"
 
 # Start application
 CMD ["pnpm", "run", "spfn:start"]

package/dist/templates/README.md

@@ -21,7 +21,7 @@ docker compose up -d
 Then open:
 
 - Next.js — http://localhost:3790
-- API health — http://localhost:8790/health
+- API health — http://localhost:8790/_core/health
 
 ## Project structure
 
@@ -71,13 +71,28 @@ Next.js interceptor, `/login` starter UI, OAuth callback, and route map are alre
 Edit `src/i18n/catalogs.ts` to add application-owned messages. Server components
 and handlers can import `getT` or `getClientMessages` from `@/i18n/server`.
 
-## Agent operations with MCP
+## Operations from the terminal
 
-The SPFN API serves MCP at `http://localhost:8790/mcp`. Connect with the Bearer
-token stored as `SPFN_MCP_API_KEY` in `.env.server`, then replace the starter
-`app_status` tool in `src/server/mcp.ts` with operations from your domain layer.
-Before third-party access, replace the generated operator-key validator with your
-OAuth access-token validator and scope each tool to the resolved operator.
+Operating this app needs no admin dashboard. Ops routes live in
+`src/server/routes/ops.ts`, are written like any other route, and the `spfn ops`
+CLI discovers them from the running server:
+
+```bash
+# 1. Seed an administrator: uncomment SPFN_AUTH_ADMIN_ACCOUNTS in .env.server,
+#    then restart the server so the account is created.
+
+# 2. Issue a token for this machine (stored in the OS keychain on macOS)
+{{pmExec}} spfn ops token issue --name laptop --scopes 'example:read'
+
+# 3. Run the app's own operations
+{{pmExec}} spfn ops list --app http://localhost:8790
+{{pmExec}} spfn ops call countExamples --app http://localhost:8790
+{{pmExec}} spfn ops call listRecentExamples --describe   # usage from the route's schema
+```
+
+Tokens are scoped and revocable (`spfn ops token list` / `revoke`). Add your own
+commands by exporting more `opsRoute` handlers and passing them to
+`createOpsRouter` — no CLI change is needed, the manifest carries them.
 <!-- {{/auth}} -->
 
 ## Deployment

package/dist/templates/docker-compose.production.yml

@@ -22,13 +22,20 @@ services:
       context: .
       dockerfile: Dockerfile
     ports:
-      - "3790:3790"  # Next.js
-      - "8790:8790"  # SPFN API
+      - "${NEXT_PORT:-3790}:${NEXT_PORT:-3790}"  # Next.js
+      - "${SPFN_PORT:-8790}:${SPFN_PORT:-8790}"  # SPFN API
     environment:
       # Required: Set these via .env file or environment
       - DATABASE_URL=${DATABASE_URL}
       - REDIS_URL=${REDIS_URL:-redis://redis:6379}
       - NODE_ENV=production
+      # Ports: leave unset and spfn.config.js decides. Set either one to
+      # override it for this deployment — the mapping above follows.
+      - NEXT_PORT=${NEXT_PORT:-}
+      - SPFN_PORT=${SPFN_PORT:-}
+      # A container has to bind every interface; a developer machine does not,
+      # which is why localhost is the default and this line is here.
+      - SPFN_HOST=0.0.0.0
       # Optional: Frontend API URL
       - NEXT_PUBLIC_API_URL=${NEXT_PUBLIC_API_URL:-http://localhost:8790}
     restart: unless-stopped

package/dist/templates/modes/full/src/server/router.ts

@@ -2,13 +2,12 @@
  * Prototype-to-Production application router.
  *
  * Auth protects application routes by default. Public routes opt out with
- * `.skip(['auth'])`; the MCP router owns its Bearer-token boundary.
+ * `.skip(['auth'])`; the ops router owns its own ops-token boundary.
  */
 import { authRouter, authenticate } from '@spfn/auth/server';
 import { defineRouter } from '@spfn/core/route';
-import { mcpRouter } from './mcp';
 import { getRoot } from './routes/root';
-import { getHealth } from './routes/health';
+import { opsRouter } from './routes/ops';
 import {
     listExamples,
     getExample,
@@ -19,14 +18,13 @@ import {
 
 export const appRouter = defineRouter({
     getRoot,
-    getHealth,
     listExamples,
     getExample,
     createExample,
     updateExample,
     deleteExample,
 })
-    .packages([authRouter, mcpRouter])
+    .packages([authRouter, opsRouter])
     .use([authenticate]);
 
 export type AppRouter = typeof appRouter;

package/dist/templates/modes/full/src/server/routes/ops.ts

@@ -0,0 +1,52 @@
+/**
+ * Ops routes — operate this application from the terminal.
+ *
+ * Operations are written exactly like features: `opsRoute` puts them under the
+ * `/_ops` namespace, and `createOpsRouter` injects `opsTokenAuth` into every one
+ * of them plus serves `GET /_ops/_manifest`, which the `spfn ops` CLI reads to
+ * discover the commands this app owns.
+ *
+ * First run, against a running server:
+ *
+ *   spfn ops token issue --name laptop --scopes 'example:read'
+ *   spfn ops list --app http://localhost:8790
+ *   spfn ops call countExamples --app http://localhost:8790
+ *
+ * Issuing a token signs in as an administrator, so seed one first with
+ * `SPFN_AUTH_ADMIN_ACCOUNTS` in `.env.server`.
+ */
+import { createOpsRouter, opsRoute } from '@spfn/core/ops';
+import { opsTokenAuth, requireOpsScope } from '@spfn/auth/server';
+import { Type } from '@sinclair/typebox';
+import { ExampleRepository } from '../repositories/example.repository';
+
+const exampleRepo = new ExampleRepository();
+
+/**
+ * GET /_ops/examples/count — how many examples exist
+ */
+const countExamples = opsRoute.get('/examples/count')
+    .use([requireOpsScope('example:read')])
+    .handler(async () => ({ count: await exampleRepo.countAll() }));
+
+/**
+ * GET /_ops/examples — recent examples, ops view
+ */
+const listRecentExamples = opsRoute.get('/examples')
+    .use([requireOpsScope('example:read')])
+    .input({
+        query: Type.Object({
+            limit: Type.Optional(Type.Number({ minimum: 1, maximum: 100 })),
+        }),
+    })
+    .handler(async (c) =>
+    {
+        const { query } = await c.data();
+
+        return { items: await exampleRepo.findAll(query.limit ?? 10, 0) };
+    });
+
+export const opsRouter = createOpsRouter({
+    countExamples,
+    listRecentExamples,
+}, { auth: opsTokenAuth });

package/dist/templates/modes/full/src/server/routes/root.ts

@@ -7,9 +7,9 @@ export const getRoot = route.get('/')
         version: '1.0.0',
         status: 'running',
         endpoints: {
-            health: '/health',
+            health: '/_core/health',
             examples: '/examples',
             auth: '/_auth',
-            mcp: '/mcp',
+            ops: '/_ops',
         },
     }));

package/dist/templates/modes/full/src/server/server.config.ts

@@ -7,8 +7,6 @@ import { defineServerConfig } from '@spfn/core/server';
 import { appRouter } from '@/server/router';
 
 export default defineServerConfig()
-    .port(8790)
-    .host('0.0.0.0')
     .routes(appRouter)
     .lifecycle(createAuthLifecycle())
     .build();

package/dist/templates/server/router.ts

@@ -6,7 +6,6 @@
 
 import { defineRouter } from '@spfn/core/route';
 import { getRoot } from './routes/root';
-import { getHealth } from './routes/health';
 import { listExamples, getExample, createExample, updateExample, deleteExample } from './routes/examples';
 
 /**
@@ -14,7 +13,6 @@ import { listExamples, getExample, createExample, updateExample, deleteExample }
  */
 export const appRouter = defineRouter({
     getRoot,
-    getHealth,
     listExamples,
     getExample,
     createExample,

package/dist/templates/server/routes/root.ts

@@ -14,7 +14,7 @@ export const getRoot = route.get('/')
             version: '1.0.0',
             status: 'running',
             endpoints: {
-                health: '/health',
+                health: '/_core/health',
                 examples: '/examples',
             },
             message: 'Welcome to SPFN! Visit /examples for usage examples.',

package/dist/templates/server/server.config.ts

@@ -5,7 +5,5 @@ import { defineServerConfig } from '@spfn/core/server';
 import { appRouter } from '@/server/router';
 
 export default defineServerConfig()
-    .port(8790)
-    .host('0.0.0.0')
     .routes(appRouter)
     .build();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spfn",
-  "version": "0.3.0-beta.2",
+  "version": "0.3.0-beta.4",
   "description": "Scaffold a full-stack TypeScript backend onto a Next.js app built with an AI coding agent: auth, database, typed routes and codegen, one fixed vertical slice per feature",
   "type": "module",
   "bin": {
@@ -57,7 +57,7 @@
     "node": ">=20.0.0"
   },
   "peerDependencies": {
-    "@spfn/core": ">=0.3.0-beta.1 <0.4.0",
+    "@spfn/core": ">=0.3.0-beta.3 <0.4.0",
     "typescript": "^5.3.0"
   },
   "peerDependenciesMeta": {

package/dist/templates/modes/full/src/server/config/env.config.ts

@@ -1,23 +0,0 @@
-import {
-    createEnvRegistry,
-    defineEnvSchema,
-    envSecret,
-    envUrl,
-} from '@spfn/core/env';
-
-export const envSchema = defineEnvSchema({
-    SPFN_MCP_URL: envUrl({
-        description: 'Public base URL of the SPFN server that exposes /mcp',
-        default: 'http://localhost:8790',
-        required: false,
-    }),
-    SPFN_MCP_API_KEY: envSecret({
-        description: 'First-party Bearer token for the generated MCP operator endpoint',
-        required: true,
-        generate: 'base64url32',
-    }),
-});
-
-export const env = createEnvRegistry(envSchema).validate();
-
-export default env;

package/dist/templates/modes/full/src/server/mcp.ts

@@ -1,75 +0,0 @@
-/**
- * Remote MCP endpoint for operating this application with an agent.
- *
- * The generated operator key makes the endpoint usable immediately. Replace
- * `validateToken` with your OAuth access-token validator before granting access
- * to third-party clients, and expose only tools the resolved operator may use.
- */
-import { timingSafeEqual } from 'node:crypto';
-import type { McpAuth, McpTool } from '@spfn/mcp';
-import { createMcpRoute } from '@spfn/mcp/server';
-import env from './config/env.config';
-
-type OperatorAuth = McpAuth & {
-    operatorId: string;
-};
-
-type OperatorContext = {
-    operatorId: string;
-};
-
-const tools: McpTool<OperatorContext>[] = [
-    {
-        name: 'app_status',
-        title: 'Application status',
-        description: 'Check that the deployed application MCP endpoint is available.',
-        inputSchema: {
-            type: 'object',
-            properties: {},
-        },
-        annotations: {
-            readOnlyHint: true,
-            destructiveHint: false,
-        },
-        handler: async (_args, context) => ({
-            status: 'ok',
-            operatorId: context.operatorId,
-        }),
-    },
-];
-
-export const mcpRouter = createMcpRoute<OperatorAuth, OperatorContext>({
-    appUrl: env.SPFN_MCP_URL,
-    serverInfo: {
-        name: 'spfn-app',
-        version: '1.0.0',
-        description: 'Operate this SPFN application with an agent.',
-    },
-    validateToken: async (token) =>
-    {
-        // The registry validates this required secret at startup. Its public
-        // proxy type remains optional so schemas can also describe values that
-        // are not required in every environment.
-        if (!secretsMatch(token, env.SPFN_MCP_API_KEY!))
-        {
-            throw new Error('Invalid MCP access token');
-        }
-
-        return {
-            clientId: 'operator-agent',
-            operatorId: 'operator',
-            scopes: ['operate'],
-        };
-    },
-    resolveContext: async auth => ({ operatorId: auth.operatorId }),
-    listTools: () => tools,
-});
-
-function secretsMatch(actual: string, expected: string): boolean
-{
-    const actualBytes = Buffer.from(actual);
-    const expectedBytes = Buffer.from(expected);
-
-    return actualBytes.length === expectedBytes.length
-        && timingSafeEqual(actualBytes, expectedBytes);
-}

package/dist/templates/modes/full/src/server/routes/health.ts

@@ -1,9 +0,0 @@
-import { route } from '@spfn/core/route';
-
-export const getHealth = route.get('/health')
-    .skip(['auth'])
-    .handler(async () => ({
-        status: 'ok',
-        timestamp: Date.now(),
-        uptime: process.uptime(),
-    }));

package/dist/templates/server/routes/health.ts

@@ -1,18 +0,0 @@
-/**
- * Health Check Route
- *
- * Minimal endpoint for monitoring systems, load balancers, and orchestrators.
- * Used by Kubernetes probes, uptime monitors, etc.
- */
-
-import { route } from '@spfn/core/route';
-
-export const getHealth = route.get('/health')
-    .handler(async () =>
-    {
-        return {
-            status: 'ok',
-            timestamp: Date.now(),
-            uptime: process.uptime(),
-        };
-    });