spfn 0.3.0-beta.7 → 0.3.0-beta.9

package/README.md

@@ -703,11 +703,25 @@ docker-compose.yml                   # Postgres + Redis (dev)
 docker-compose.production.yml
 Dockerfile, .dockerignore
 next.config.ts                       # patched when auth is enabled: /_auth/:path* rewrite → SPFN API
-.env.example                         # committed reference — every key, placeholder values
+.env.local.example                   # committed reference — Next.js keys, placeholder values
+.env.server.example                  # committed reference — backend keys, placeholder values
 .env.local                           # generated, gitignored (values loaded by Next.js)
 .env.server                          # generated, gitignored (server secrets: DB, cache)
 ```
 
+The reference is split by consumer, never combined, and a key's file follows who
+reads it rather than whether it is secret:
+
+- `.env.local` / `.env.local.example` — the Next.js process (server routes, proxy,
+  SSR) and, through `NEXT_PUBLIC_*`, the browser: `SPFN_API_URL`, `SPFN_APP_URL`,
+  `SPFN_AUTH_SESSION_SECRET`, `SPFN_AUTH_SESSION_TTL`, `SPFN_AUTH_CSRF`.
+- `.env.server` / `.env.server.example` — the SPFN backend only, never loaded by
+  Next.js: `NODE_ENV`, `SPFN_LOG_LEVEL`, `DATABASE_URL`, `CACHE_URL`, `DB_POOL_*`,
+  and every OAuth, token, and admin secret.
+
+So the session secret is secret and still lives in `.env.local` — the Next.js proxy
+verifies cookies with it — while `DATABASE_URL` never appears there at all.
+
 Full mode overlays the Prototype-to-Production baseline:
 
 ```
@@ -726,7 +740,7 @@ next.config.ts                       # /_auth/* callback rewrite
 
 The full RPC proxy imports the auth interceptor and merges `authRouteMap`. Internal auth
 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
+`.env.local.example` and `.env.server.example` contain placeholders only. Add only the provider keys you use, then run
 `pnpm spfn db migrate`.
 
 Operating the app is [`spfn ops`](#spfn-ops), not a dashboard: the starter

package/dist/index.js

@@ -72,6 +72,9 @@ function detectPackageManager(cwd) {
 function getRunCommand(pm) {
   return pm === "npm" ? "npm run" : `${pm} run`;
 }
+function getRunScriptArgs(pm, script, args) {
+  return pm === "npm" ? ["run", script, "--", ...args] : ["run", script, ...args];
+}
 var init_package_manager = __esm({
   "src/utils/package-manager.ts"() {
     "use strict";
@@ -948,7 +951,7 @@ import { dirname as dirname2, join as join10 } from "path";
 import { fileURLToPath as fileURLToPath2 } from "url";
 function getCliVersion() {
   if (true) {
-    return "0.3.0-beta.7";
+    return "0.3.0-beta.9";
   }
   return fromPackageJson ?? (fromPackageJson = readPackageVersion());
 }
@@ -1169,14 +1172,6 @@ import { randomBytes } from "crypto";
 import { spawnSync } from "child_process";
 import { join as join12 } from "path";
 import fse8 from "fs-extra";
-function envExampleTemplate(mode) {
-  return withPlaceholderCreds(`# Example environment \u2014 committed reference for the variables SPFN uses.
-# Real values live in .env.local (Next.js) and .env.server (backend secrets),
-# both gitignored. This file documents the keys; it is not loaded by anything.
-
-${ENV_LOCAL_TEMPLATE}${mode === "full" ? FULL_ENV_LOCAL_EXAMPLE : ""}
-${ENV_SERVER_TEMPLATE}${mode === "full" ? FULL_ENV_SERVER_EXAMPLE : ""}`);
-}
 function envServerExampleTemplate(mode) {
   return withPlaceholderCreds(
     `${ENV_SERVER_TEMPLATE}${mode === "full" ? FULL_ENV_SERVER_EXAMPLE : ""}`
@@ -1195,7 +1190,9 @@ NEXT_PUBLIC_SPFN_APP_URL=http://localhost:3790
 `;
 }
 function envLocalExampleTemplate(mode) {
-  return `${ENV_LOCAL_TEMPLATE}${mode === "full" ? FULL_ENV_LOCAL_EXAMPLE : ""}`;
+  return withPlaceholderCreds(
+    `${ENV_LOCAL_TEMPLATE}${mode === "full" ? FULL_ENV_LOCAL_EXAMPLE : ""}`
+  );
 }
 function envServerTemplate(mode) {
   if (mode === "bare") {
@@ -1261,20 +1258,16 @@ export default defineConfig({
   updateTsconfig(cwd);
 }
 function generateEnvFiles(cwd, mode) {
-  writeLocalEnv(cwd, envLocalTemplate(mode), envLocalExampleTemplate(mode));
-  writeServerEnv(cwd, envServerTemplate(mode), envServerExampleTemplate(mode));
-  writeExampleEnv(cwd, envExampleTemplate(mode));
+  writeReferenceEnv(cwd, ".env.local.example", envLocalExampleTemplate(mode));
+  writeReferenceEnv(cwd, ".env.server.example", envServerExampleTemplate(mode));
+  writeLocalEnv(cwd, envLocalTemplate(mode));
+  writeServerEnv(cwd, envServerTemplate(mode));
 }
-function writeLocalEnv(cwd, template, exampleTemplate) {
+function writeLocalEnv(cwd, template) {
   const filename = ".env.local";
   const filePath = join12(cwd, filename);
   if (isGitTracked(cwd, filename)) {
-    const referenceName = ".env.local.spfn.example";
-    const referencePath = join12(cwd, referenceName);
-    if (!existsSync12(referencePath)) {
-      writeFileSync8(referencePath, exampleTemplate);
-    }
-    logger.warn(`${filename} is tracked by Git \u2014 left it untouched; wrote ${referenceName}. Untrack ${filename}, then add the missing keys with freshly generated values`);
+    logger.warn(`${filename} is tracked by Git \u2014 left it untouched; its keys are listed in .env.local.example. Untrack ${filename}, then add the missing keys with freshly generated values`);
     return;
   }
   writeEnvFile(cwd, filename, template);
@@ -1287,7 +1280,7 @@ function isGitTracked(cwd, filename) {
   });
   return result.status === 0;
 }
-function writeServerEnv(cwd, template, exampleTemplate) {
+function writeServerEnv(cwd, template) {
   const filePath = join12(cwd, ".env.server");
   if (!existsSync12(filePath)) {
     writeFileSync8(filePath, template);
@@ -1295,16 +1288,15 @@ function writeServerEnv(cwd, template, exampleTemplate) {
     logger.success("Created .env.server");
     return;
   }
-  writeFileSync8(join12(cwd, ".env.server.example"), exampleTemplate);
-  logger.warn(".env.server already exists \u2014 left it untouched; wrote SPFN's reference to .env.server.example, add any missing keys manually");
+  logger.warn(".env.server already exists \u2014 left it untouched; SPFN's reference is in .env.server.example, add any missing keys manually");
 }
-function writeExampleEnv(cwd, content) {
-  const filePath = join12(cwd, ".env.example");
+function writeReferenceEnv(cwd, filename, content) {
+  const filePath = join12(cwd, filename);
   if (existsSync12(filePath)) {
     return;
   }
   writeFileSync8(filePath, content);
-  logger.success("Created .env.example (committed reference)");
+  logger.success(`Created ${filename} (committed reference)`);
 }
 function writeEnvFile(cwd, filename, content) {
   const filePath = join12(cwd, filename);
@@ -1362,8 +1354,11 @@ function pendingIgnoreRules(content) {
   if (!gitignoreCovers(lines, ".env.server")) {
     rules.push("\n# spfn server env (secrets)\n.env.server\n");
   }
-  if (!lines.some((line) => line.trim() === "!.env.example")) {
-    rules.push("\n# spfn env reference (committed)\n!.env.example\n");
+  if (!lines.some((line) => line.trim() === "!.env.local.example")) {
+    rules.push("\n# spfn env reference, Next.js keys (committed)\n!.env.local.example\n");
+  }
+  if (!lines.some((line) => line.trim() === "!.env.server.example")) {
+    rules.push("\n# spfn env reference, backend keys (committed)\n!.env.server.example\n");
   }
   return rules;
 }
@@ -2658,7 +2653,7 @@ catch (error)
   };
   const startNext = () => {
     const nextCmd = pm === "npm" ? "npm" : pm;
-    const nextArgs = ["run", "spfn:next", "--", "--port", String(nextPort)];
+    const nextArgs = getRunScriptArgs(pm, "spfn:next", ["--port", String(nextPort)]);
     nextProcess = execa6(nextCmd, nextArgs, {
       cwd,
       stdio: "inherit",
@@ -7148,7 +7143,7 @@ init_logger();
 import { join as join32 } from "path";
 import chalk43 from "chalk";
 init_env_file();
-var COMMITTED_FILES = [".env", ".env.example"];
+var COMMITTED_FILES = [".env", ".env.example", ".env.local.example", ".env.server.example"];
 var PLACEHOLDER = /(your-|changeme|placeholder|example|<.*>)/i;
 async function secretCheck(options) {
   const cwd = process.cwd();

package/dist/templates/README.md

@@ -32,7 +32,8 @@ src/
   generated/           codegen output (route map) — do not edit by hand
 .env.local             Next.js runtime env (gitignored)
 .env.server            server secrets (gitignored)
-.env.example           committed reference — keys only, placeholder values
+.env.local.example     committed reference — the Next.js keys, placeholder values
+.env.server.example    committed reference — the backend keys, placeholder values
 .spfnrc.ts             codegen configuration
 spfn.config.js         deployment config
 ```
@@ -54,6 +55,12 @@ A feature is a vertical slice: `Entity` (Drizzle table) → `Repository` →
 
 ## Environment & secrets
 
+The env reference is split by consumer: `.env.local.example` lists what the Next.js
+process reads (`SPFN_API_URL`, `NEXT_PUBLIC_*`, the auth session secret), and
+`.env.server.example` lists what only the backend reads (`DATABASE_URL`, `CACHE_URL`,
+OAuth secrets). Which file a key belongs in follows who consumes it, not whether it
+is secret.
+
 `.env.server` holds backend-only secrets and is gitignored — Next.js never loads it.
 For a managed workflow use `spfn secret`: local values go to the OS keychain (only a
 `secret:keychain:` reference lands in `.env.server`), and deployed secrets are stored

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spfn",
-  "version": "0.3.0-beta.7",
+  "version": "0.3.0-beta.9",
   "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": {