spfn 0.3.0-beta.1 → 0.3.0-beta.3

package/README.md

@@ -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`
@@ -411,8 +418,14 @@ listSignups  GET /_ops/signups
 Add `--json` for the raw JSON Schema. The server still validates every call — `--describe`
 reports what it will accept, and the app's answer decides.
 
-The app URL comes from `--app` or `SPFN_OPS_APP`. The ops token resolves `--token` →
-`SPFN_OPS_TOKEN` → macOS keychain, and its lifecycle is managed with:
+The app URL comes from `--app` or `SPFN_OPS_APP`, and it must be **https** — every one of
+these commands carries a secret, and `token issue` carries an administrator's password.
+`http` is accepted only against `localhost`, `127.0.0.1` and `::1`, where there is no
+network to listen on. A URL with a base path (`https://example.com/api`) is kept whole:
+both the ops calls and the administrator sign-in go through it.
+
+The ops token resolves `--token` → `SPFN_OPS_TOKEN` → macOS keychain, and its lifecycle is
+managed with:
 
 ```bash
 spfn ops token issue --name laptop --scopes 'waitlist:read' --app <url>
@@ -442,6 +455,10 @@ point, which that release added. The CLI does not depend on the package in any f
 loads it from the app at run time, and tells a missing package apart from one too old to
 carry the entry point, so the message names the thing to do.
 
+Because the package is the app's, it is resolved **from the directory the command runs in**.
+Run `spfn ops token` from the app's root; running it elsewhere reports the package as
+missing, and the message names the directory it looked in.
+
 ---
 
 ## Scaffold structure
@@ -570,7 +587,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:
 
@@ -585,7 +602,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`.

package/dist/index.js

@@ -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.1";
+  return "0.3.0-beta.3";
 }
 function getTagFromVersion(version) {
   const match = version.match(/-([a-z]+)\./i);
@@ -982,7 +1004,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";
@@ -1483,7 +1505,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 +2144,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 +2168,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 +2229,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 +2302,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 +2418,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 +2524,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 +2610,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 +2635,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 +2699,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 +2729,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 +2751,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 +2765,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 +2778,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,
@@ -5380,7 +5408,39 @@ async function fetchOpsManifest(appUrl, token) {
   if (manifest?.manifestVersion !== 1 || !Array.isArray(manifest.commands)) {
     throw new Error("The manifest answer has an unknown shape.");
   }
-  return manifest;
+  return { manifestVersion: 1, commands: usableCommands(manifest.commands) };
+}
+var OPS_METHODS = /* @__PURE__ */ new Set(["GET", "POST", "PUT", "PATCH", "DELETE"]);
+var OPS_PATH_PREFIX = "/_ops/";
+function unusableBecause(command) {
+  if (typeof command?.name !== "string" || command.name.length === 0) {
+    return "it has no name";
+  }
+  if (typeof command.method !== "string" || !OPS_METHODS.has(command.method)) {
+    return `its method is ${JSON.stringify(command.method)}`;
+  }
+  if (typeof command.path !== "string" || !command.path.startsWith(OPS_PATH_PREFIX)) {
+    return `its path ${JSON.stringify(command.path)} is outside ${OPS_PATH_PREFIX}`;
+  }
+  if (command.path.split("/").includes("..")) {
+    return `its path ${JSON.stringify(command.path)} climbs out of the ops namespace`;
+  }
+  return null;
+}
+function usableCommands(commands) {
+  const usable = [];
+  for (const command of commands) {
+    const reason = unusableBecause(command);
+    if (reason !== null) {
+      console.error(`\u26A0\uFE0F  Ignoring an ops command the manifest announced: ${reason}.`);
+      continue;
+    }
+    usable.push({ ...command, input: isPlainObject(command.input) ? command.input : {} });
+  }
+  return usable;
+}
+function isPlainObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
 }
 function buildCommandPath(command, params, query) {
   const path5 = command.path.replace(/:([A-Za-z0-9_]+)/g, (_match, name) => {
@@ -5407,6 +5467,10 @@ var SECTIONS = [
 function isSchema(value) {
   return value !== null && typeof value === "object" && !Array.isArray(value);
 }
+var MAX_SCHEMA_DEPTH = 12;
+function plain(value) {
+  return value.replace(/[\u0000-\u001f\u007f-\u009f]/g, "?");
+}
 function typeName(schema) {
   if (Array.isArray(schema.enum)) {
     return schema.enum.every((v) => typeof v === "string") ? "string" : "value";
@@ -5453,7 +5517,7 @@ function constraintNotes(schema) {
   }
   return notes;
 }
-function collectFields(schema, prefix = "") {
+function collectFields(schema, prefix = "", depth = 0) {
   const properties = isSchema(schema.properties) ? schema.properties : {};
   const required = Array.isArray(schema.required) ? schema.required : [];
   const rows = [];
@@ -5461,17 +5525,17 @@ function collectFields(schema, prefix = "") {
     if (!isSchema(raw)) {
       continue;
     }
-    const path5 = prefix ? `${prefix}.${name}` : name;
-    const nested = isSchema(raw.properties) ? collectFields(raw, path5) : [];
+    const path5 = prefix ? `${prefix}.${plain(name)}` : plain(name);
+    const nested = isSchema(raw.properties) && depth < MAX_SCHEMA_DEPTH ? collectFields(raw, path5, depth + 1) : [];
     if (nested.length > 0) {
       rows.push(...nested);
       continue;
     }
     rows.push({
       name: path5,
-      type: typeName(raw),
+      type: plain(typeName(raw)),
       requirement: required.includes(name) ? "required" : "optional",
-      notes: constraintNotes(raw).join(", ")
+      notes: plain(constraintNotes(raw).join(", "))
     });
   }
   return rows;
@@ -5490,7 +5554,7 @@ function renderSection(label, flag, rows) {
   return lines;
 }
 function renderCommandUsage(command) {
-  const lines = [`${command.name}  ${command.method} ${command.path}`, ""];
+  const lines = [`${plain(command.name)}  ${command.method} ${plain(command.path)}`, ""];
   let described = false;
   for (const section of SECTIONS) {
     const schema = command.input[section.key];
@@ -5507,7 +5571,7 @@ function renderCommandUsage(command) {
   if (!described) {
     lines.push("  Takes no input.", "");
   }
-  lines.push(`  Invoke: spfn ops call ${command.name}${exampleFlags(command)}`);
+  lines.push(`  Invoke: spfn ops call ${plain(command.name)}${exampleFlags(command)}`);
   return lines.join("\n");
 }
 function exampleFlags(command) {
@@ -5598,18 +5662,37 @@ function deleteOpsToken(account) {
 }
 
 // src/commands/ops/resolve.ts
+function isLoopback(hostname) {
+  return hostname === "localhost" || hostname === "127.0.0.1" || hostname === "[::1]" || hostname.endsWith(".localhost");
+}
+function assertTransportSafe(parsed, appUrl) {
+  if (parsed.protocol === "https:" || parsed.protocol === "http:" && isLoopback(parsed.hostname)) {
+    return;
+  }
+  if (parsed.protocol === "http:") {
+    console.error(chalk33.red(`\u274C Refusing to talk to ${appUrl} over http.`));
+    console.error(chalk33.gray("   An administrator password and an ops token cross this connection, and http sends both in the clear."));
+    console.error(chalk33.gray("   Use https. http is allowed only against localhost."));
+    process.exit(1);
+  }
+  console.error(chalk33.red(`\u274C App URL must be https, got "${parsed.protocol}//".`));
+  console.error(chalk33.gray("   The ops surface is reached over HTTP(S) \u2014 http is allowed only against localhost."));
+  process.exit(1);
+}
 function resolveAppUrl(options) {
   const appUrl = options.app ?? process.env.SPFN_OPS_APP;
   if (!appUrl) {
     console.error(chalk33.red("\u274C No app URL. Pass --app <url> or set SPFN_OPS_APP."));
     process.exit(1);
   }
+  let parsed;
   try {
-    new URL(appUrl);
+    parsed = new URL(appUrl);
   } catch {
     console.error(chalk33.red(`\u274C Invalid app URL: ${appUrl}`));
     process.exit(1);
   }
+  assertTransportSafe(parsed, appUrl);
   return appUrl;
 }
 function appAccount(appUrl) {
@@ -5623,7 +5706,13 @@ async function resolveToken(options, appUrl) {
     return process.env.SPFN_OPS_TOKEN;
   }
   if (keychainSupported()) {
-    const stored = await loadOpsToken(appAccount(appUrl));
+    const stored = await loadOpsToken(appAccount(appUrl)).catch((err) => {
+      console.error(chalk33.yellow(
+        `\u26A0\uFE0F  Could not read the keychain (${err instanceof Error ? err.message : String(err)}).`
+      ));
+      console.error(chalk33.gray("   Unlock it, or pass --token / set SPFN_OPS_TOKEN for this run."));
+      return null;
+    });
     if (stored) {
       return stored;
     }
@@ -5654,16 +5743,26 @@ import prompts9 from "prompts";
 import chalk34 from "chalk";
 
 // src/utils/ops/auth-crypto.ts
+import { createRequire } from "module";
+import { join as join25 } from "path";
+import { pathToFileURL as pathToFileURL3 } from "url";
 var CRYPTO_ENTRY_SINCE = "0.3.0-beta.2";
 var CRYPTO_ENTRY = "@spfn/auth/crypto";
+async function importFromApp(specifier) {
+  const requireFromApp = createRequire(join25(process.cwd(), "noop.js"));
+  return await import(pathToFileURL3(requireFromApp.resolve(specifier)).href);
+}
 async function loadAuthCrypto() {
   try {
-    return await import(CRYPTO_ENTRY);
+    return await importFromApp(CRYPTO_ENTRY);
   } catch (err) {
     const code = err.code;
     if (code === "ERR_MODULE_NOT_FOUND" || code === "MODULE_NOT_FOUND") {
       throw new Error(
-        "This project does not have @spfn/auth installed, and ops tokens live in its schema \u2014 so this app has none to issue, list or revoke.\n   An app that uses the ops surface installs @spfn/auth for opsTokenAuth; add it there.\n   Invoking commands with a token you already hold (spfn ops list / call) does not need it."
+        `No @spfn/auth is installed in ${process.cwd()}, and ops tokens live in its schema \u2014 so this app has none to issue, list or revoke.
+   An app that uses the ops surface installs @spfn/auth for opsTokenAuth; add it there.
+   Run this from the app directory \u2014 the package is resolved from where the command runs.
+   Invoking commands with a token you already hold (spfn ops list / call) does not need it.`
       );
     }
     if (code === "ERR_PACKAGE_PATH_NOT_EXPORTED") {
@@ -5677,8 +5776,18 @@ async function loadAuthCrypto() {
 }
 
 // src/utils/ops/admin-session.ts
+function parseJsonAnswer(text, status, statusText) {
+  if (!text) {
+    return {};
+  }
+  try {
+    return JSON.parse(text);
+  } catch {
+    throw new Error(`The app answered ${status} ${statusText} with something that is not JSON.`);
+  }
+}
 async function postJson(appUrl, path5, body, authorization) {
-  const response = await fetch(new URL(path5, appUrl), {
+  const response = await fetch(joinUrl(appUrl, path5), {
     method: "POST",
     headers: {
       "Content-Type": "application/json",
@@ -5687,7 +5796,7 @@ async function postJson(appUrl, path5, body, authorization) {
     body: JSON.stringify(body)
   });
   const text = await response.text();
-  const parsed = text ? JSON.parse(text) : {};
+  const parsed = parseJsonAnswer(text, response.status, response.statusText);
   if (!response.ok) {
     throw new Error(parsed.message ?? parsed.error ?? `${response.status} ${response.statusText}`);
   }
@@ -5752,7 +5861,7 @@ async function withAdminSession(appUrl, run2) {
   return result;
 }
 async function adminRequest(appUrl, method, path5, session, body) {
-  const response = await fetch(new URL(path5, appUrl), {
+  const response = await fetch(joinUrl(appUrl, path5), {
     method,
     headers: {
       Authorization: session.authorization,
@@ -5761,7 +5870,7 @@ async function adminRequest(appUrl, method, path5, session, body) {
     ...body === void 0 ? {} : { body: JSON.stringify(body) }
   });
   const text = await response.text();
-  const parsed = text ? JSON.parse(text) : {};
+  const parsed = parseJsonAnswer(text, response.status, response.statusText);
   if (!response.ok) {
     throw new Error(parsed.message ?? parsed.error ?? `${response.status} ${response.statusText}`);
   }
@@ -5920,7 +6029,7 @@ async function listCommands(options) {
   console.log(chalk36.bold(`Ops commands at ${appUrl}:
 `));
   for (const command of manifest.commands) {
-    console.log(`  ${chalk36.cyan(command.name)}  ${chalk36.gray(`${command.method} ${command.path}`)}  input: ${inputSummary(command)}`);
+    console.log(`  ${chalk36.cyan(plain(command.name))}  ${chalk36.gray(`${command.method} ${plain(command.path)}`)}  input: ${inputSummary(command)}`);
   }
   console.log(chalk36.gray(`
 \u{1F4A1} Invoke: spfn ops call <name> [--param k=v] [--query k=v] [--data '{"..."}']`));
@@ -5932,8 +6041,8 @@ async function callCommand(name, options) {
   const manifest = await fetchOpsManifest(appUrl, token);
   const command = manifest.commands.find((c) => c.name === name);
   if (!command) {
-    console.error(chalk36.red(`\u274C Unknown ops command "${name}".`));
-    console.error(chalk36.gray(`   Known: ${manifest.commands.map((c) => c.name).join(", ") || "(none)"}`));
+    console.error(chalk36.red(`\u274C Unknown ops command "${plain(name)}".`));
+    console.error(chalk36.gray(`   Known: ${manifest.commands.map((c) => plain(c.name)).join(", ") || "(none)"}`));
     process.exit(1);
   }
   if (options.describe) {
@@ -5943,7 +6052,7 @@ async function callCommand(name, options) {
   let body;
   if (options.data !== void 0) {
     if (command.method === "GET") {
-      console.error(chalk36.red(`\u274C "${name}" is a ${command.method} command and takes no request body.`));
+      console.error(chalk36.red(`\u274C "${plain(name)}" is a ${command.method} command and takes no request body.`));
       console.error(chalk36.gray("   Pass its input with --query k=v (or --param k=v for path segments)."));
       process.exit(1);
     }
@@ -5964,7 +6073,7 @@ async function callCommand(name, options) {
     console.log(rendered);
     return;
   }
-  console.error(chalk36.red(`\u274C ${command.method} ${command.path} answered ${response.status}`));
+  console.error(chalk36.red(`\u274C ${command.method} ${plain(command.path)} answered ${response.status}`));
   console.error(rendered);
   process.exit(1);
 }
@@ -5994,7 +6103,7 @@ function resolveEnv(env9) {
 
 // src/commands/secret/store-value.ts
 init_logger();
-import { join as join26 } from "path";
+import { join as join27 } from "path";
 init_env_file();
 
 // src/utils/sops.ts
@@ -6043,19 +6152,19 @@ async function sopsUpdateKeys(absFile) {
 
 // src/utils/secret-config.ts
 import { existsSync as existsSync28, readdirSync as readdirSync2 } from "fs";
-import { join as join25 } from "path";
+import { join as join26 } from "path";
 var SECRETS_DIR = "secrets";
 function getSopsFile(cwd, env9) {
   const relFile = `${SECRETS_DIR}/${env9}.enc.json`;
-  return { absFile: join25(cwd, relFile), relFile };
+  return { absFile: join26(cwd, relFile), relFile };
 }
 function findUp(cwd, filename, maxDepth = 6) {
   let dir = cwd;
   for (let depth = 0; depth < maxDepth; depth++) {
-    if (existsSync28(join25(dir, filename))) {
+    if (existsSync28(join26(dir, filename))) {
       return dir;
     }
-    const parent = join25(dir, "..");
+    const parent = join26(dir, "..");
     if (parent === dir) {
       break;
     }
@@ -6065,17 +6174,17 @@ function findUp(cwd, filename, maxDepth = 6) {
 }
 function findSopsConfig(cwd) {
   const dir = findUp(cwd, ".sops.yaml");
-  return dir ? join25(dir, ".sops.yaml") : null;
+  return dir ? join26(dir, ".sops.yaml") : null;
 }
 function hasSopsConfig(cwd) {
   return findSopsConfig(cwd) !== null;
 }
 function listSopsFiles(cwd) {
-  const dir = join25(cwd, SECRETS_DIR);
+  const dir = join26(cwd, SECRETS_DIR);
   if (!existsSync28(dir)) {
     return [];
   }
-  return readdirSync2(dir).filter((name) => name.endsWith(".enc.json")).map((name) => join25(dir, name));
+  return readdirSync2(dir).filter((name) => name.endsWith(".enc.json")).map((name) => join26(dir, name));
 }
 
 // src/commands/secret/store-value.ts
@@ -6104,7 +6213,7 @@ async function storeSecret(cwd, env9, key, value) {
       );
     }
     await store.set(keychainName(key), value);
-    const serverEnvPath = join26(cwd, ".env.server");
+    const serverEnvPath = join27(cwd, ".env.server");
     const result = upsertEnvVar(serverEnvPath, key, keychainRef(key));
     restrictEnvFilePerms(serverEnvPath);
     ensureGitignored(cwd, [{ pattern: ".env.server", comment: "spfn server env (secrets)" }]);
@@ -6344,10 +6453,10 @@ init_logger();
 import { execa as execa12 } from "execa";
 import { existsSync as existsSync29, mkdirSync as mkdirSync6 } from "fs";
 import { homedir } from "os";
-import { dirname as dirname5, join as join27 } from "path";
+import { dirname as dirname5, join as join28 } from "path";
 import chalk41 from "chalk";
 function ageKeyFile() {
-  return process.env.SOPS_AGE_KEY_FILE ?? join27(homedir(), ".config", "sops", "age", "keys.txt");
+  return process.env.SOPS_AGE_KEY_FILE ?? join28(homedir(), ".config", "sops", "age", "keys.txt");
 }
 async function ensureAgeInstalled() {
   try {
@@ -6395,7 +6504,7 @@ function printPublicKeys(keys) {
 // src/commands/secret/recipients.ts
 init_logger();
 import { existsSync as existsSync30, readFileSync as readFileSync12, writeFileSync as writeFileSync19 } from "fs";
-import { join as join28 } from "path";
+import { join as join29 } from "path";
 import { parse as parse3, stringify } from "yaml";
 import chalk42 from "chalk";
 var SOPS_CONFIG = ".sops.yaml";
@@ -6403,7 +6512,7 @@ var DEFAULT_PATH_REGEX = "secrets/.*\\.enc\\.json$";
 var AGE_RECIPIENT = /^age1[0-9a-z]+$/;
 async function secretRecipients(action, key, _options) {
   const cwd = process.cwd();
-  const configPath = join28(cwd, SOPS_CONFIG);
+  const configPath = join29(cwd, SOPS_CONFIG);
   if (action === "list") {
     listRecipients(configPath);
     return;
@@ -6488,7 +6597,7 @@ async function reencrypt(cwd) {
 
 // src/commands/secret/check.ts
 init_logger();
-import { join as join29 } from "path";
+import { join as join30 } from "path";
 import chalk43 from "chalk";
 init_env_file();
 var COMMITTED_FILES = [".env", ".env.example"];
@@ -6507,14 +6616,14 @@ async function secretCheck(options) {
   const issues = [];
   const warnings = [];
   for (const file of COMMITTED_FILES) {
-    const parsed = parseEnvFile(join29(cwd, file));
+    const parsed = parseEnvFile(join30(cwd, file));
     for (const [key, value] of Object.entries(parsed)) {
       if (secretKeys.has(key) && value.length > 0 && !PLACEHOLDER.test(value)) {
         issues.push(`${chalk43.cyan(key)} has a real value in committed ${chalk43.yellow(file)} \u2014 move it to the keychain/SOPS.`);
       }
     }
   }
-  const serverEnv = parseEnvFile(join29(cwd, ".env.server"));
+  const serverEnv = parseEnvFile(join30(cwd, ".env.server"));
   for (const key of secretKeys) {
     const value = serverEnv[key];
     if (value && !value.startsWith(KEYCHAIN_REF_PREFIX)) {

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
 

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

@@ -8,7 +8,6 @@ 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 {
     listExamples,
     getExample,
@@ -19,7 +18,6 @@ import {
 
 export const appRouter = defineRouter({
     getRoot,
-    getHealth,
     listExamples,
     getExample,
     createExample,

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

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

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.1",
+  "version": "0.3.0-beta.3",
   "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/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(),
-        };
-    });