spfn 0.2.0-beta.2 → 0.2.0-beta.20

package/dist/index.js

@@ -521,35 +521,47 @@ import { existsSync as existsSync6 } from "fs";
 import { join as join6 } from "path";
 import fse3 from "fs-extra";
 async function setupApiProxy(cwd, includeAuth) {
-  const appDir = existsSync6(join6(cwd, "src", "app")) ? join6(cwd, "src", "app") : join6(cwd, "app");
+  const srcAppDir = join6(cwd, "src", "app");
+  const rootAppDir = join6(cwd, "app");
+  let appDir;
+  if (existsSync6(srcAppDir)) {
+    appDir = srcAppDir;
+  } else if (existsSync6(rootAppDir)) {
+    appDir = rootAppDir;
+  } else {
+    logger.error("Next.js app directory not found. Expected src/app or app directory.");
+    process.exit(1);
+  }
   const rpcDir = join6(appDir, "api", "rpc", "[routeName]");
   const rpcRoutePath = join6(rpcDir, "route.ts");
-  if (!existsSync6(rpcRoutePath)) {
-    ensureDirSync3(rpcDir);
-    const authImport = includeAuth ? `import '@spfn/auth/nextjs/api';
+  if (existsSync6(rpcRoutePath)) {
+    logger.error(`RPC proxy route already exists: ${rpcRoutePath.replace(cwd + "/", "")}`);
+    process.exit(1);
+  }
+  ensureDirSync3(rpcDir);
+  const authImport = includeAuth ? `import '@spfn/auth/nextjs/api';
 ` : "";
-    const routeContent = `/**
+  const routeContent = `/**
  * SPFN RPC Proxy
  *
- * Resolves routeName to actual HTTP method and path from router,
+ * Resolves routeName to actual HTTP method and path from routeMap,
  * then forwards requests to SPFN API server with automatic:
  * - Cookie forwarding
  * - Interceptor execution
  * - Header manipulation
  *
- * Note: Imports from '@spfn/core/nextjs/server' (server-only)
- * Uses next/headers internally - do not import in Client Components
+ * Note: Uses generated route-map to avoid loading server code in Next.js process.
+ * Run \`spfn codegen run\` if route-map.ts is missing.
  */
 
-${authImport}import { appRouter } from '@/server/router';
+${authImport}import { routeMap } from '@/generated/route-map';
 import { createRpcProxy } from '@spfn/core/nextjs/server';
 
-export const { GET, POST } = createRpcProxy({ router: appRouter });
+export const { GET, POST } = createRpcProxy({ routeMap });
 `;
-    writeFileSync2(rpcRoutePath, routeContent);
-    const relativePath = rpcRoutePath.replace(cwd + "/", "");
-    logger.success(`Created ${relativePath} (RPC proxy)`);
-  }
+  writeFileSync2(rpcRoutePath, routeContent);
+  const relativePath = rpcRoutePath.replace(cwd + "/", "");
+  logger.success(`Created ${relativePath} (RPC proxy)`);
 }
 var ensureDirSync3, writeFileSync2;
 var init_api_proxy = __esm({
@@ -741,6 +753,23 @@ var init_deployment_config = __esm({
   }
 });
 
+// src/utils/version.ts
+function getCliVersion() {
+  return "0.2.0-beta.20";
+}
+function getTagFromVersion(version) {
+  const match = version.match(/-([a-z]+)\./i);
+  return match ? match[1] : "latest";
+}
+function getSpfnTag() {
+  return getTagFromVersion(getCliVersion());
+}
+var init_version = __esm({
+  "src/utils/version.ts"() {
+    "use strict";
+  }
+});
+
 // src/commands/init/steps/package.ts
 import ora3 from "ora";
 import { execa as execa2 } from "execa";
@@ -750,13 +779,15 @@ async function setupPackageJson(cwd, packageJsonPath, packageJson, packageManage
   packageJson.dependencies = packageJson.dependencies || {};
   packageJson.devDependencies = packageJson.devDependencies || {};
   packageJson.scripts = packageJson.scripts || {};
-  packageJson.dependencies["@spfn/core"] = "alpha";
+  const spfnTag = getSpfnTag();
+  packageJson.dependencies["@spfn/core"] = spfnTag;
   packageJson.dependencies["@sinclair/typebox"] = "^0.34.0";
+  packageJson.dependencies["drizzle-orm"] = "^0.45.0";
   packageJson.dependencies["drizzle-typebox"] = "^0.1.0";
-  packageJson.dependencies["spfn"] = "alpha";
+  packageJson.dependencies["spfn"] = spfnTag;
   packageJson.dependencies["concurrently"] = "^9.2.1";
   if (includeAuth) {
-    packageJson.dependencies["@spfn/auth"] = "alpha";
+    packageJson.dependencies["@spfn/auth"] = spfnTag;
   }
   packageJson.devDependencies["@types/node"] = "^20.11.0";
   packageJson.devDependencies["tsx"] = "^4.20.6";
@@ -793,6 +824,7 @@ var init_package = __esm({
   "src/commands/init/steps/package.ts"() {
     "use strict";
     init_logger();
+    init_version();
     ({ writeFileSync: writeFileSync4 } = fse6);
   }
 });
@@ -802,26 +834,7 @@ import { existsSync as existsSync9, readFileSync as readFileSync2 } from "fs";
 import { join as join9 } from "path";
 import fse7 from "fs-extra";
 async function setupConfigFiles(cwd) {
-  const envExamplePath = join9(cwd, ".env.local.example");
-  if (!existsSync9(envExamplePath)) {
-    const envExampleContent = `# Environment
-NODE_ENV=local
-
-# Logging
-SPFN_LOG_LEVEL=info
-
-# Database (matches docker-compose.yml)
-DATABASE_URL=postgresql://spfn:spfn@localhost:5432/spfn_dev
-
-# Cache - Redis/Valkey (optional)
-CACHE_URL=redis://localhost:6379
-
-# SPFN API Server URL (for API Route Proxy and SSR)
-SPFN_API_URL=http://localhost:8790
-`;
-    writeFileSync5(envExamplePath, envExampleContent);
-    logger.success("Created .env.local.example");
-  }
+  generateEnvExamples(cwd);
   const spfnrcPath = join9(cwd, ".spfnrc.ts");
   if (!existsSync9(spfnrcPath)) {
     const spfnrcContent = `import { defineConfig, defineGenerator } from '@spfn/core/codegen';
@@ -830,64 +843,135 @@ SPFN_API_URL=http://localhost:8790
  * SPFN Codegen Configuration
  *
  * Configure code generators here. Generators run during \`spfn dev\` and \`spfn codegen run\`.
- *
- * Example: Custom generator
- * @example
- * const myGenerator = defineGenerator({
- *     name: 'my-package:generator',
- *     enabled: true,
- *     // ... generator-specific options
- * });
- *
- * Example: File-based generator
- * @example
- * const customGen = defineGenerator({
- *     path: './src/generators/my-generator.ts',
- * });
  */
 
 export default defineConfig({
     generators: [
-        // Add your generators here
-        // myGenerator,
+        // Route map generator - generates routeName \u2192 {method, path} mappings
+        // Used by RPC proxy to resolve routes without importing server code
+        defineGenerator({
+            name: '@spfn/core:route-map',
+            routerPath: './src/server/router.ts',
+            outputPath: './src/generated/route-map.ts',
+        }),
     ]
 });
 `;
     writeFileSync5(spfnrcPath, spfnrcContent);
     logger.success("Created .spfnrc.ts (codegen configuration)");
   }
+  updateGitignore(cwd);
+  updateTsconfig(cwd);
+}
+function generateEnvExamples(cwd) {
+  writeEnvExample(cwd, ".env.example", `# Shared defaults (committed)
+# These values are shared across all environments.
+
+# Environment
+NODE_ENV=local
+
+# Logging
+SPFN_LOG_LEVEL=info
+
+# Server
+PORT=4000
+
+# SPFN API Server URL (for API Route Proxy and SSR)
+SPFN_API_URL=http://localhost:8790
+NEXT_PUBLIC_SPFN_API_URL=http://localhost:8790
+`);
+  writeEnvExample(cwd, ".env.local.example", `# Local overrides (gitignored)
+# Developer-specific values that should NOT be committed.
+
+# Database (matches docker-compose.yml)
+DATABASE_URL=postgresql://spfn:spfn@localhost:5432/spfn_dev
+
+# Cache - Redis/Valkey (optional)
+CACHE_URL=redis://localhost:6379
+
+# SPFN App URL (optional, for CORS and redirects)
+# SPFN_APP_URL=http://localhost:3790
+`);
+  writeEnvExample(cwd, ".env.server.example", `# Server-only defaults (committed)
+# These values are only loaded by the SPFN server, not by Next.js.
+
+# Database pool
+DB_POOL_MAX=10
+DB_POOL_IDLE_TIMEOUT=30
+
+# Server timeouts
+SERVER_TIMEOUT=120000
+SHUTDOWN_TIMEOUT=30000
+`);
+  writeEnvExample(cwd, ".env.server.local.example", `# Server secrets (gitignored)
+# Server-only sensitive values. Never commit this file.
+
+# Database write/read URLs (master-replica pattern, optional)
+# DATABASE_WRITE_URL=postgresql://user:password@master:5432/dbname
+# DATABASE_READ_URL=postgresql://user:password@replica:5432/dbname
+
+# Cache password (optional)
+# CACHE_PASSWORD=your-redis-password
+`);
+}
+function writeEnvExample(cwd, filename, content) {
+  const filePath = join9(cwd, filename);
+  if (existsSync9(filePath)) {
+    return;
+  }
+  writeFileSync5(filePath, content);
+  logger.success(`Created ${filename}`);
+}
+function updateGitignore(cwd) {
   const gitignorePath = join9(cwd, ".gitignore");
-  if (existsSync9(gitignorePath)) {
-    try {
-      const gitignoreContent = readFileSync2(gitignorePath, "utf-8");
-      if (!gitignoreContent.includes(".spfn")) {
-        const updatedContent = gitignoreContent.replace(
-          /# production\n\/build/,
-          "# production\n/build\n\n# spfn\n/.spfn/"
-        );
-        writeFileSync5(gitignorePath, updatedContent);
-        logger.success("Updated .gitignore with .spfn directory");
-      }
-    } catch (error) {
-      logger.warn("Could not update .gitignore (you can add .spfn manually)");
+  if (!existsSync9(gitignorePath)) {
+    return;
+  }
+  try {
+    const content = readFileSync2(gitignorePath, "utf-8");
+    let updated = content;
+    let changed = false;
+    if (!content.includes(".spfn")) {
+      updated = updated.replace(
+        /# production\n\/build/,
+        "# production\n/build\n\n# spfn\n/.spfn/"
+      );
+      changed = true;
     }
+    if (!content.includes(".env.local") && !content.includes(".env.*.local")) {
+      updated += `
+# environment secrets (local overrides)
+.env.local
+.env.*.local
+`;
+      changed = true;
+    }
+    if (changed) {
+      writeFileSync5(gitignorePath, updated);
+      logger.success("Updated .gitignore with .spfn directory and env patterns");
+    }
+  } catch (error) {
+    logger.warn("Could not update .gitignore (you can add patterns manually)");
   }
+}
+function updateTsconfig(cwd) {
   const tsconfigPath = join9(cwd, "tsconfig.json");
-  if (existsSync9(tsconfigPath)) {
-    try {
-      const tsconfigContent = readFileSync2(tsconfigPath, "utf-8");
-      const tsconfig = JSON.parse(tsconfigContent);
-      if (!tsconfig.exclude) {
-        tsconfig.exclude = [];
-      }
-      if (!tsconfig.exclude.includes("src/server")) {
-        tsconfig.exclude.push("src/server");
-        writeFileSync5(tsconfigPath, JSON.stringify(tsconfig, null, 2) + "\n");
-        logger.success("Updated tsconfig.json (excluded src/server for Vercel compatibility)");
-      }
-    } catch (error) {
-      logger.warn('Could not update tsconfig.json (you can add "src/server" to exclude manually)');
+  if (!existsSync9(tsconfigPath)) {
+    return;
+  }
+  try {
+    const tsconfigContent = readFileSync2(tsconfigPath, "utf-8");
+    const tsconfig = JSON.parse(tsconfigContent);
+    if (!tsconfig.exclude) {
+      tsconfig.exclude = [];
+    }
+    if (!tsconfig.exclude.includes("src/server")) {
+      tsconfig.exclude.push("src/server");
+      writeFileSync5(tsconfigPath, JSON.stringify(tsconfig, null, 2) + "\n");
+      logger.success("Updated tsconfig.json (excluded src/server for Vercel compatibility)");
     }
+  } catch (error) {
+    logger.warn('Could not update tsconfig.json (you can add "src/server" to exclude manually)');
   }
 }
 var writeFileSync5;
@@ -961,7 +1045,7 @@ __export(function_migrations_exports, {
 import chalk11 from "chalk";
 import { join as join15 } from "path";
 import { env as env2 } from "@spfn/core/config";
-import { loadEnvFiles as loadEnvFiles2 } from "@spfn/core/server";
+import { loadEnv as loadEnv2 } from "@spfn/core/server";
 import { existsSync as existsSync16, readdirSync as readdirSync2, readFileSync as readFileSync5 } from "fs";
 function discoverFunctionMigrations(cwd = process.cwd()) {
   const nodeModulesPath = join15(cwd, "node_modules");
@@ -1009,7 +1093,7 @@ async function executeFunctionMigrations(functionMigrations) {
   const { drizzle } = await import("drizzle-orm/postgres-js");
   const { migrate } = await import("drizzle-orm/postgres-js/migrator");
   const postgres = await import("postgres");
-  loadEnvFiles2();
+  loadEnv2();
   if (!env2.DATABASE_URL) {
     throw new Error("DATABASE_URL not found in environment");
   }
@@ -1019,7 +1103,10 @@ async function executeFunctionMigrations(functionMigrations) {
     for (const func of functionMigrations) {
       console.log(chalk11.blue(`
   \u{1F4E6} Running ${func.packageName} migrations...`));
-      await migrate(db, { migrationsFolder: func.migrationsDir });
+      await migrate(db, {
+        migrationsFolder: func.migrationsDir,
+        migrationsTable: "__spfn_fn_migrations"
+      });
       console.log(chalk11.green(`  \u2713 ${func.packageName} migrations applied`));
       executedCount++;
     }
@@ -1179,10 +1266,30 @@ init_init();
 init_logger();
 init_package_manager();
 import { Command as Command4 } from "commander";
-import { existsSync as existsSync11, readFileSync as readFileSync3, writeFileSync as writeFileSync6, mkdirSync } from "fs";
+import { existsSync as existsSync11, readFileSync as readFileSync3, writeFileSync as writeFileSync6, mkdirSync, unlinkSync, watch } from "fs";
 import { join as join11 } from "path";
 import { execa as execa4 } from "execa";
 import chokidar from "chokidar";
+function waitForReadyFile(filePath, timeoutMs = 3e4) {
+  return new Promise((resolve2, reject) => {
+    if (existsSync11(filePath)) {
+      unlinkSync(filePath);
+    }
+    const timer = setTimeout(() => {
+      watcher.close();
+      reject(new Error(`Server did not become ready within ${timeoutMs / 1e3}s`));
+    }, timeoutMs);
+    const dir = join11(filePath, "..");
+    const fileName = filePath.split("/").pop();
+    const watcher = watch(dir, (event, name) => {
+      if (name === fileName && existsSync11(filePath)) {
+        watcher.close();
+        clearTimeout(timer);
+        resolve2(readFileSync3(filePath, "utf-8").trim());
+      }
+    });
+  });
+}
 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)").action(async (options) => {
   process.setMaxListeners(20);
   if (!process.env.NODE_ENV) {
@@ -1210,17 +1317,22 @@ var devCommand = new Command4("dev").description("Start SPFN development server
   if (options.host) configParts.push(`host: '${options.host}'`);
   if (options.routes) configParts.push(`routesPath: '${options.routes}'`);
   configParts.push("debug: true");
+  const readyFile = join11(tempDir, "server-ready");
   writeFileSync6(serverEntry, `
+import { writeFileSync } from 'fs';
+
 // Load environment variables FIRST (before any imports that depend on them)
-// Use centralized environment loader for standard dotenv priority
 await import('@spfn/core/config');
 
 // Import and start server
 const { startServer } = await import('@spfn/core/server');
 
-await startServer({
+const instance = await startServer({
     ${configParts.join(",\n    ")}
 });
+
+// Signal ready with actual port
+writeFileSync(${JSON.stringify(readyFile)}, String(instance.config.port));
 `);
   writeFileSync6(watcherEntry, `
 // Load environment variables
@@ -1277,7 +1389,9 @@ catch (error)
   const pm = detectPackageManager(cwd);
   if (options.serverOnly || !hasNext) {
     const watchMode2 = options.watch === true;
-    logger.info(`Starting SPFN Server on http://${options.host}:${options.port}${watchMode2 ? " (watch mode)" : ""}
+    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)" : ""}
 `);
     let serverProcess2 = null;
     let watcherProcess2 = null;
@@ -1471,7 +1585,13 @@ catch (error)
   process.on("SIGTERM", cleanup);
   startWatcher();
   startServer();
-  await new Promise((resolve2) => setTimeout(resolve2, 2e3));
+  try {
+    const port = await waitForReadyFile(readyFile);
+    logger.info(`[SPFN] Server ready on port ${port}, starting Next.js...
+`);
+  } catch (error) {
+    logger.warn(`[SPFN] Server readiness check timed out, starting Next.js anyway...`);
+  }
   startNext();
   await new Promise((resolve2) => {
     const keepAlive = setInterval(() => {
@@ -1522,7 +1642,7 @@ async function buildProject(options) {
       const orchestrator = new CodegenOrchestrator({
         generators,
         cwd,
-        debug: false
+        debug: true
       });
       await orchestrator.generateAll();
       spinner.succeed("API client generated");
@@ -1832,7 +1952,7 @@ async function runGenerators() {
   const orchestrator = new CodegenOrchestrator({
     generators,
     cwd,
-    debug: false
+    debug: true
   });
   await orchestrator.generateAll();
   console.log("\n" + chalk7.green.bold("\u2713 Code generation completed"));
@@ -1991,14 +2111,14 @@ import { Command as Command9 } from "commander";
 import chalk10 from "chalk";
 
 // src/commands/db/utils/drizzle.ts
-import { existsSync as existsSync15, writeFileSync as writeFileSync9, unlinkSync } from "fs";
+import { existsSync as existsSync15, writeFileSync as writeFileSync9, unlinkSync as unlinkSync2 } from "fs";
 import { spawn } from "child_process";
 import chalk9 from "chalk";
 import ora6 from "ora";
 import { env } from "@spfn/core/config";
-import { loadEnvFiles } from "@spfn/core/server";
+import { loadEnv } from "@spfn/core/server";
 function validateDatabasePrerequisites() {
-  loadEnvFiles();
+  loadEnv();
   if (!env.DATABASE_URL) {
     console.error(chalk9.red("\u274C DATABASE_URL not found in environment"));
     console.log(chalk9.yellow("\n\u{1F4A1} Tip: Add DATABASE_URL to your .env file"));
@@ -2010,7 +2130,7 @@ async function runDrizzleCommand(command) {
   const tempConfigPath = `./drizzle.config.${process.pid}.${Date.now()}.temp.ts`;
   const configPath = hasUserConfig ? "./drizzle.config.ts" : tempConfigPath;
   if (!hasUserConfig) {
-    loadEnvFiles();
+    loadEnv();
     if (!env.DATABASE_URL) {
       console.error(chalk9.red("\u274C DATABASE_URL not found in environment"));
       console.log(chalk9.yellow("\n\u{1F4A1} Tip: Add DATABASE_URL to your .env file"));
@@ -2020,7 +2140,10 @@ async function runDrizzleCommand(command) {
     const configContent = generateDrizzleConfigFile({
       cwd: process.cwd(),
       // Exclude package schemas to avoid .ts/.js mixing (packages use migrations instead)
-      disablePackageDiscovery: true
+      disablePackageDiscovery: true,
+      // Expand globs and auto-detect PostgreSQL schemas for push/generate compatibility
+      expandGlobs: true,
+      autoDetectSchemas: true
     });
     writeFileSync9(tempConfigPath, configContent);
     console.log(chalk9.dim("Using auto-generated Drizzle config\n"));
@@ -2031,11 +2154,12 @@ async function runDrizzleCommand(command) {
     const drizzleProcess = spawn("drizzle-kit", args, {
       stdio: "inherit",
       // Allow interactive input
-      shell: true
+      shell: true,
+      env: { ...process.env, NODE_TLS_REJECT_UNAUTHORIZED: "0" }
     });
     const cleanup = () => {
       if (!hasUserConfig && existsSync15(tempConfigPath)) {
-        unlinkSync(tempConfigPath);
+        unlinkSync2(tempConfigPath);
       }
     };
     drizzleProcess.on("close", (code) => {
@@ -2107,6 +2231,8 @@ async function dbPush() {
 
 // src/commands/db/migrate.ts
 import chalk16 from "chalk";
+import { join as join16 } from "path";
+import { existsSync as existsSync18 } from "fs";
 
 // src/commands/db/backup.ts
 import { promises as fs3 } from "fs";
@@ -2341,8 +2467,10 @@ async function listBackupFiles() {
 
 // src/commands/db/backup.ts
 import { env as env3 } from "@spfn/core/config";
+import { loadEnv as loadEnv3 } from "@spfn/core/server";
 async function dbBackup(options) {
   console.log(chalk15.blue("\u{1F4BE} Creating database backup...\n"));
+  loadEnv3();
   const dbUrl = env3.DATABASE_URL;
   if (!dbUrl) {
     console.error(chalk15.red("\u274C DATABASE_URL not found in environment"));
@@ -2457,7 +2585,10 @@ async function dbBackup(options) {
 }
 
 // src/commands/db/migrate.ts
-import "@spfn/core/config";
+import { env as env4 } from "@spfn/core/config";
+import { loadEnv as loadEnv4 } from "@spfn/core/server";
+var FUNCTION_MIGRATIONS_TABLE = "__spfn_fn_migrations";
+var PROJECT_MIGRATIONS_TABLE = "__drizzle_migrations";
 async function dbMigrate(options = {}) {
   try {
     validateDatabasePrerequisites();
@@ -2473,35 +2604,62 @@ async function dbMigrate(options = {}) {
     });
     console.log("");
   }
-  const { discoverFunctionMigrations: discoverFunctionMigrations2, executeFunctionMigrations: executeFunctionMigrations2 } = await Promise.resolve().then(() => (init_function_migrations(), function_migrations_exports));
+  const { drizzle } = await import("drizzle-orm/postgres-js");
+  const { migrate } = await import("drizzle-orm/postgres-js/migrator");
+  const postgres = await import("postgres");
+  loadEnv4();
+  if (!env4.DATABASE_URL) {
+    console.error(chalk16.red("\u274C DATABASE_URL not found in environment"));
+    process.exit(1);
+  }
+  const { discoverFunctionMigrations: discoverFunctionMigrations2 } = await Promise.resolve().then(() => (init_function_migrations(), function_migrations_exports));
   const functions = discoverFunctionMigrations2(process.cwd());
   if (functions.length > 0) {
-    console.log(chalk16.blue("\u{1F4E6} Applying function package migrations:"));
-    functions.forEach((func) => {
-      console.log(chalk16.dim(`  - ${func.packageName}`));
-    });
+    const fnConn = postgres.default(env4.DATABASE_URL, { max: 1 });
+    const fnDb = drizzle(fnConn);
     try {
-      await executeFunctionMigrations2(functions);
+      console.log(chalk16.blue("\u{1F4E6} Applying function package migrations:"));
+      functions.forEach((func) => {
+        console.log(chalk16.dim(`  - ${func.packageName}`));
+      });
+      for (const func of functions) {
+        console.log(chalk16.blue(`
+  \u{1F4E6} Running ${func.packageName} migrations...`));
+        await migrate(fnDb, {
+          migrationsFolder: func.migrationsDir,
+          migrationsTable: FUNCTION_MIGRATIONS_TABLE
+        });
+        console.log(chalk16.green(`  \u2713 ${func.packageName} migrations applied`));
+      }
       console.log(chalk16.green("\u2705 Function migrations applied\n"));
-    } catch (error) {
-      console.error(chalk16.red("\n\u274C Failed to apply function migrations"));
-      console.error(chalk16.red(error instanceof Error ? error.message : "Unknown error"));
-      process.exit(1);
+    } finally {
+      await fnConn.end();
     }
   }
-  await runWithSpinner(
-    "Running project migrations...",
-    "migrate",
-    "Project migrations applied successfully",
-    "Failed to run project migrations"
-  );
+  const projectMigrationsDir = join16(process.cwd(), "src/server/drizzle");
+  if (existsSync18(projectMigrationsDir)) {
+    const projConn = postgres.default(env4.DATABASE_URL, { max: 1 });
+    const projDb = drizzle(projConn);
+    try {
+      console.log(chalk16.blue("\u{1F4E6} Running project migrations..."));
+      await migrate(projDb, {
+        migrationsFolder: projectMigrationsDir,
+        migrationsTable: PROJECT_MIGRATIONS_TABLE
+      });
+      console.log(chalk16.green("\u2705 Project migrations applied successfully"));
+    } finally {
+      await projConn.end();
+    }
+  } else {
+    console.log(chalk16.dim("No project migrations found (src/server/drizzle)"));
+  }
 }
 
 // src/commands/db/studio.ts
 import chalk17 from "chalk";
-import { existsSync as existsSync18, writeFileSync as writeFileSync10, unlinkSync as unlinkSync2 } from "fs";
+import { existsSync as existsSync19, writeFileSync as writeFileSync10, unlinkSync as unlinkSync3 } from "fs";
 import { spawn as spawn3 } from "child_process";
-import { env as env4 } from "@spfn/core/config";
+import { env as env5 } from "@spfn/core/config";
 import "@spfn/core/config";
 async function dbStudio(requestedPort) {
   console.log(chalk17.blue("\u{1F3A8} Opening Drizzle Studio...\n"));
@@ -2518,12 +2676,12 @@ async function dbStudio(requestedPort) {
     console.error(chalk17.red(error instanceof Error ? error.message : "Failed to find available port"));
     process.exit(1);
   }
-  const hasUserConfig = existsSync18("./drizzle.config.ts");
+  const hasUserConfig = existsSync19("./drizzle.config.ts");
   const tempConfigPath = `./drizzle.config.${process.pid}.${Date.now()}.temp.ts`;
   try {
     const configPath = hasUserConfig ? "./drizzle.config.ts" : tempConfigPath;
     if (!hasUserConfig) {
-      if (!env4.DATABASE_URL) {
+      if (!env5.DATABASE_URL) {
         console.error(chalk17.red("\u274C DATABASE_URL not found in environment"));
         console.log(chalk17.yellow("\n\u{1F4A1} Tip: Add DATABASE_URL to your .env file"));
         process.exit(1);
@@ -2540,11 +2698,12 @@ async function dbStudio(requestedPort) {
     }
     const studioProcess = spawn3("drizzle-kit", ["studio", `--port=${port}`, `--config=${configPath}`], {
       stdio: "inherit",
-      shell: true
+      shell: true,
+      env: { ...process.env, NODE_TLS_REJECT_UNAUTHORIZED: "0" }
     });
     const cleanup = () => {
-      if (!hasUserConfig && existsSync18(tempConfigPath)) {
-        unlinkSync2(tempConfigPath);
+      if (!hasUserConfig && existsSync19(tempConfigPath)) {
+        unlinkSync3(tempConfigPath);
       }
     };
     studioProcess.on("exit", (code) => {
@@ -2573,8 +2732,8 @@ async function dbStudio(requestedPort) {
       process.exit(0);
     });
   } catch (error) {
-    if (!hasUserConfig && existsSync18(tempConfigPath)) {
-      unlinkSync2(tempConfigPath);
+    if (!hasUserConfig && existsSync19(tempConfigPath)) {
+      unlinkSync3(tempConfigPath);
     }
     console.error(chalk17.red("\u274C Failed to start Drizzle Studio"));
     console.error(chalk17.red(error instanceof Error ? error.message : "Unknown error"));
@@ -2626,10 +2785,12 @@ import { spawn as spawn4 } from "child_process";
 import chalk20 from "chalk";
 import ora9 from "ora";
 import prompts4 from "prompts";
-import { env as env5 } from "@spfn/core/config";
+import { env as env6 } from "@spfn/core/config";
+import { loadEnv as loadEnv5 } from "@spfn/core/server";
 async function dbRestore(backupFile, options = {}) {
   console.log(chalk20.blue("\u267B\uFE0F  Restoring database from backup...\n"));
-  const dbUrl = env5.DATABASE_URL;
+  loadEnv5();
+  const dbUrl = env6.DATABASE_URL;
   if (!dbUrl) {
     console.error(chalk20.red("\u274C DATABASE_URL not found in environment"));
     console.log(chalk20.yellow("\n\u{1F4A1} Tip: Add DATABASE_URL to your .env file"));
@@ -2678,29 +2839,29 @@ async function dbRestore(backupFile, options = {}) {
     if (metadata.backup.schemaOnly) {
       console.log(chalk20.yellow("  \u26A0\uFE0F  Schema-only backup (no data)"));
     }
-    const warnings = [];
+    const warnings2 = [];
     const [currentGitInfo, currentMigrationInfo] = await Promise.all([
       collectGitInfo(),
       collectMigrationInfo(dbUrl)
     ]);
     if (metadata.git && currentGitInfo) {
       if (metadata.git.commit !== currentGitInfo.commit) {
-        warnings.push(`Git commit mismatch: backup from ${metadata.git.commit.substring(0, 7)}, current is ${currentGitInfo.commit.substring(0, 7)}`);
+        warnings2.push(`Git commit mismatch: backup from ${metadata.git.commit.substring(0, 7)}, current is ${currentGitInfo.commit.substring(0, 7)}`);
       }
       if (metadata.git.branch !== currentGitInfo.branch) {
-        warnings.push(`Git branch mismatch: backup from '${metadata.git.branch}', current is '${currentGitInfo.branch}'`);
+        warnings2.push(`Git branch mismatch: backup from '${metadata.git.branch}', current is '${currentGitInfo.branch}'`);
       }
     }
     if (metadata.migrations && currentMigrationInfo) {
       if (metadata.migrations.hash !== currentMigrationInfo.hash) {
-        warnings.push(`Migration version mismatch: backup has ${metadata.migrations.count} migrations, current has ${currentMigrationInfo.count}`);
-        warnings.push(`  Last migration in backup: ${metadata.migrations.hash}`);
-        warnings.push(`  Current last migration: ${currentMigrationInfo.hash}`);
+        warnings2.push(`Migration version mismatch: backup has ${metadata.migrations.count} migrations, current has ${currentMigrationInfo.count}`);
+        warnings2.push(`  Last migration in backup: ${metadata.migrations.hash}`);
+        warnings2.push(`  Current last migration: ${currentMigrationInfo.hash}`);
       }
     }
-    if (warnings.length > 0) {
+    if (warnings2.length > 0) {
       console.log(chalk20.yellow("\n\u26A0\uFE0F  Version Warnings:\n"));
-      warnings.forEach((warning) => console.log(chalk20.yellow(`  - ${warning}`)));
+      warnings2.forEach((warning) => console.log(chalk20.yellow(`  - ${warning}`)));
       console.log("");
     }
   }
@@ -2728,6 +2889,7 @@ async function dbRestore(backupFile, options = {}) {
     args.push("-p", dbInfo.port);
     args.push("-U", dbInfo.user);
     args.push("-d", dbInfo.database);
+    args.push("--verbose");
     if (options.drop) {
       args.push("--clean");
     }
@@ -2750,8 +2912,10 @@ async function dbRestore(backupFile, options = {}) {
     args.push("-p", dbInfo.port);
     args.push("-U", dbInfo.user);
     args.push("-d", dbInfo.database);
+    args.push("-v", "ON_ERROR_STOP=1");
     args.push("-f", file);
   }
+  const verbose = options.verbose ?? false;
   const spinner = ora9("Restoring backup...").start();
   const restoreProcess = spawn4(command, args, {
     stdio: ["ignore", "pipe", "pipe"],
@@ -2760,19 +2924,81 @@ async function dbRestore(backupFile, options = {}) {
       PGPASSWORD: dbInfo.password
     }
   });
-  let errorOutput = "";
+  const warnings = [];
+  const errors = [];
+  let objectCount = 0;
+  let lastObject = "";
   restoreProcess.stderr?.on("data", (data) => {
-    errorOutput += data.toString();
+    const lines = data.toString().split("\n").filter((l) => l.trim());
+    for (const line of lines) {
+      if (/^pg_restore:.*warning:/i.test(line) || /^WARNING:/i.test(line)) {
+        warnings.push(line.trim());
+      } else if (/^pg_restore:.*error:/i.test(line) || /^ERROR:/i.test(line) || /^psql:.*ERROR/i.test(line)) {
+        errors.push(line.trim());
+      }
+      const objectMatch = line.match(/processing item (\d+)\/(\d+)/);
+      if (objectMatch) {
+        objectCount = Number(objectMatch[2]);
+        const current = Number(objectMatch[1]);
+        const desc = line.replace(/^pg_restore:\s*/, "").trim();
+        lastObject = desc;
+        spinner.text = `Restoring backup... [${current}/${objectCount}] ${desc}`;
+      } else if (isCustomFormat) {
+        const desc = line.replace(/^pg_restore:\s*/, "").trim();
+        if (desc && !/warning:|error:/i.test(desc)) {
+          lastObject = desc;
+          spinner.text = `Restoring backup... ${desc}`;
+        }
+      }
+      if (verbose) {
+        spinner.stop();
+        console.log(chalk20.dim(`  ${line.trim()}`));
+        spinner.start();
+      }
+    }
+  });
+  restoreProcess.stdout?.on("data", (data) => {
+    if (verbose) {
+      spinner.stop();
+      console.log(chalk20.dim(`  ${data.toString().trim()}`));
+      spinner.start();
+    }
   });
   await new Promise((resolve2, reject) => {
     restoreProcess.on("close", (code) => {
       if (code === 0) {
-        spinner.succeed("Restore completed");
+        const summary = objectCount > 0 ? ` (${objectCount} objects)` : "";
+        spinner.succeed(`Restore completed${summary}`);
+        if (warnings.length > 0) {
+          console.log(chalk20.yellow(`
+\u26A0\uFE0F  Warnings during restore (${warnings.length}):
+`));
+          for (const w of warnings) {
+            console.log(chalk20.yellow(`  - ${w}`));
+          }
+        }
         console.log(chalk20.green("\n\u2705 Database restored successfully"));
         resolve2();
       } else {
         spinner.fail("Restore failed");
-        reject(new Error(errorOutput || "Restore failed"));
+        if (errors.length > 0) {
+          console.error(chalk20.red(`
+\u274C Errors (${errors.length}):
+`));
+          for (const e of errors) {
+            console.error(chalk20.red(`  - ${e}`));
+          }
+        }
+        if (warnings.length > 0) {
+          console.log(chalk20.yellow(`
+\u26A0\uFE0F  Warnings (${warnings.length}):
+`));
+          for (const w of warnings) {
+            console.log(chalk20.yellow(`  - ${w}`));
+          }
+        }
+        const fallback = errors.length === 0 && warnings.length === 0 ? "Restore failed with no output" : "";
+        reject(new Error(fallback));
       }
     });
     restoreProcess.on("error", (error) => {
@@ -2780,8 +3006,11 @@ async function dbRestore(backupFile, options = {}) {
       reject(error);
     });
   }).catch((error) => {
-    console.error(chalk20.red("\n\u274C Failed to restore database"));
-    console.error(chalk20.red(error instanceof Error ? error.message : "Unknown error"));
+    const msg = error instanceof Error ? error.message : "Unknown error";
+    if (msg) {
+      console.error(chalk20.red(`
+\u274C ${msg}`));
+    }
     process.exit(1);
   });
 }
@@ -2881,14 +3110,14 @@ dbCommand.command("studio").description("Open Drizzle Studio (database GUI)").op
 dbCommand.command("drop").description("Drop all database tables (\u26A0\uFE0F  dangerous!)").action(dbDrop);
 dbCommand.command("check").description("Check database connection").action(dbCheck);
 dbCommand.command("backup").description("Create a database backup").option("-f, --format <format>", "Backup format (sql or custom)", "sql").option("-o, --output <path>", "Custom output path").option("-s, --schema <name>", "Backup specific schema only").option("--data-only", "Backup data only (no schema)").option("--schema-only", "Backup schema only (no data)").option("--tag <tags>", "Comma-separated tags for this backup").option("--env <environment>", "Environment label (e.g., production, staging)").action((options) => dbBackup(options));
-dbCommand.command("restore [file]").description("Restore database from backup").option("--drop", "Drop existing tables before restore").option("-s, --schema <name>", "Restore specific schema only").option("--data-only", "Restore data only (requires custom format .dump file)").option("--schema-only", "Restore schema only (requires custom format .dump file)").action((file, options) => dbRestore(file, options));
+dbCommand.command("restore [file]").description("Restore database from backup").option("--drop", "Drop existing tables before restore").option("-s, --schema <name>", "Restore specific schema only").option("--data-only", "Restore data only (requires custom format .dump file)").option("--schema-only", "Restore schema only (requires custom format .dump file)").option("-v, --verbose", "Show detailed restore progress").action((file, options) => dbRestore(file, options));
 dbCommand.command("backup:list").description("List all database backups").action(dbBackupList);
 dbCommand.command("backup:clean").description("Clean old database backups").option("-k, --keep <number>", "Keep N most recent backups", parseInt).option("-o, --older-than <days>", "Delete backups older than N days", parseInt).action((options) => dbBackupClean(options));
 
 // src/commands/add.ts
 import { Command as Command10 } from "commander";
-import { existsSync as existsSync19, readFileSync as readFileSync6 } from "fs";
-import { join as join16 } from "path";
+import { existsSync as existsSync20, readFileSync as readFileSync6 } from "fs";
+import { join as join17 } from "path";
 import { exec as exec2 } from "child_process";
 import { promisify as promisify2 } from "util";
 import chalk23 from "chalk";
@@ -2906,9 +3135,9 @@ async function addPackage(packageName) {
 \u{1F4E6} Setting up ${packageName}...
 `));
   try {
-    const pkgPath = join16(process.cwd(), "node_modules", ...packageName.split("/"));
-    const pkgJsonPath = join16(pkgPath, "package.json");
-    if (!existsSync19(pkgJsonPath)) {
+    const pkgPath = join17(process.cwd(), "node_modules", ...packageName.split("/"));
+    const pkgJsonPath = join17(pkgPath, "package.json");
+    if (!existsSync20(pkgJsonPath)) {
       const installSpinner = ora11("Installing package...").start();
       try {
         await execAsync2(`pnpm add ${packageName}`);
@@ -2920,7 +3149,7 @@ async function addPackage(packageName) {
     } else {
       console.log(chalk23.gray("\u2713 Package already installed (using local version)\n"));
     }
-    if (!existsSync19(pkgJsonPath)) {
+    if (!existsSync20(pkgJsonPath)) {
       throw new Error(`Package ${packageName} not found after installation`);
     }
     const pkgJson = JSON.parse(readFileSync6(pkgJsonPath, "utf-8"));
@@ -2928,8 +3157,8 @@ async function addPackage(packageName) {
       console.log(chalk23.blue(`
 \u{1F5C4}\uFE0F  Setting up database for ${packageName}...
 `));
-      const { env: env6 } = await import("@spfn/core/config");
-      if (!env6.DATABASE_URL) {
+      const { env: env7 } = await import("@spfn/core/config");
+      if (!env7.DATABASE_URL) {
         console.log(chalk23.yellow("\u26A0\uFE0F  DATABASE_URL not found"));
         console.log(chalk23.gray("Skipping database setup. Run migrations manually when ready:\n"));
         console.log(chalk23.gray(`  pnpm spfn db push
@@ -2976,8 +3205,8 @@ var addCommand = new Command10("add").description("Install and set up SPFN ecosy
 init_logger();
 import { Command as Command11 } from "commander";
 import ora12 from "ora";
-import { join as join25 } from "path";
-import { existsSync as existsSync22 } from "fs";
+import { join as join26 } from "path";
+import { existsSync as existsSync23 } from "fs";
 import chalk25 from "chalk";
 
 // src/commands/generate/prompts.ts
@@ -3070,11 +3299,11 @@ async function confirmConfiguration(config) {
 }
 
 // src/commands/generate/generators/structure.ts
-import { join as join24 } from "path";
+import { join as join25 } from "path";
 import { mkdirSync as mkdirSync5, writeFileSync as writeFileSync17 } from "fs";
 
 // src/commands/generate/generators/config.ts
-import { join as join18 } from "path";
+import { join as join19 } from "path";
 import { writeFileSync as writeFileSync11, mkdirSync as mkdirSync3 } from "fs";
 
 // src/commands/generate/string-utils.ts
@@ -3104,29 +3333,29 @@ function toSafeSchemaName(str) {
 }
 
 // src/commands/generate/template-loader.ts
-import { readFileSync as readFileSync7, existsSync as existsSync20 } from "fs";
-import { join as join17, dirname as dirname2 } from "path";
+import { readFileSync as readFileSync7, existsSync as existsSync21 } from "fs";
+import { join as join18, dirname as dirname2 } from "path";
 import { fileURLToPath as fileURLToPath2 } from "url";
 function findTemplatesPath2() {
   const __filename = fileURLToPath2(import.meta.url);
   const __dirname2 = dirname2(__filename);
-  const distPath = join17(__dirname2, "commands", "generate", "templates");
-  if (existsSync20(distPath)) {
+  const distPath = join18(__dirname2, "commands", "generate", "templates");
+  if (existsSync21(distPath)) {
     return distPath;
   }
-  const sameDirPath = join17(__dirname2, "templates");
-  if (existsSync20(sameDirPath)) {
+  const sameDirPath = join18(__dirname2, "templates");
+  if (existsSync21(sameDirPath)) {
     return sameDirPath;
   }
-  const srcPath = join17(__dirname2, "..", "..", "src", "commands", "generate", "templates");
-  if (existsSync20(srcPath)) {
+  const srcPath = join18(__dirname2, "..", "..", "src", "commands", "generate", "templates");
+  if (existsSync21(srcPath)) {
     return srcPath;
   }
   throw new Error(`Templates directory not found. Tried: ${distPath}, ${sameDirPath}, ${srcPath}`);
 }
 function loadTemplate(templateName, variables) {
   const templatesDir = findTemplatesPath2();
-  const templatePath = join17(templatesDir, `${templateName}.template`);
+  const templatePath = join18(templatesDir, `${templateName}.template`);
   let content = readFileSync7(templatePath, "utf-8");
   for (const [key, value] of Object.entries(variables)) {
     const regex = new RegExp(`\\{\\{${key}\\}\\}`, "g");
@@ -3230,7 +3459,7 @@ function generatePackageJson(fnDir, scope, fnName, description) {
     }
   };
   writeFileSync11(
-    join18(fnDir, "package.json"),
+    join19(fnDir, "package.json"),
     JSON.stringify(content, null, 4) + "\n"
   );
 }
@@ -3264,7 +3493,7 @@ function generateTsConfig(fnDir) {
     exclude: ["node_modules", "dist", "**/*.test.ts", "**/__tests__/**"]
   };
   writeFileSync11(
-    join18(fnDir, "tsconfig.json"),
+    join19(fnDir, "tsconfig.json"),
     JSON.stringify(content, null, 4) + "\n"
   );
 }
@@ -3340,7 +3569,7 @@ export default defineConfig({
     ],
 });
 `;
-  writeFileSync11(join18(fnDir, "tsup.config.ts"), content);
+  writeFileSync11(join19(fnDir, "tsup.config.ts"), content);
 }
 function generateDrizzleConfig(fnDir, scope, fnName) {
   const schemaName = `spfn_${toSnakeCase(fnName)}`;
@@ -3360,7 +3589,7 @@ export default defineConfig({
     schemaFilter: ['${schemaName}'], // Only generate for ${fnName} schema
 });
 `;
-  writeFileSync11(join18(fnDir, "drizzle.config.ts"), content);
+  writeFileSync11(join19(fnDir, "drizzle.config.ts"), content);
 }
 function generateExampleGenerator(fnDir, scope, fnName) {
   const pascalName = toPascalCase(fnName);
@@ -3429,10 +3658,10 @@ export const moduleName = '${fnName}';
     };
 }
 `;
-  const generatorsDir = join18(fnDir, "src/server/generators");
+  const generatorsDir = join19(fnDir, "src/server/generators");
   mkdirSync3(generatorsDir, { recursive: true });
   writeFileSync11(
-    join18(generatorsDir, "example-generator.ts"),
+    join19(generatorsDir, "example-generator.ts"),
     content
   );
   const indexContent = `/**
@@ -3447,7 +3676,7 @@ export const moduleName = '${fnName}';
 export { create${pascalName}ExampleGenerator } from './example-generator.js';
 `;
   writeFileSync11(
-    join18(generatorsDir, "index.ts"),
+    join19(generatorsDir, "index.ts"),
     indexContent
   );
 }
@@ -3936,15 +4165,15 @@ Contributions are welcome! Please follow the development workflow above.
 
 MIT
 `;
-  writeFileSync11(join18(fnDir, "README.md"), content);
+  writeFileSync11(join19(fnDir, "README.md"), content);
 }
 
 // src/commands/generate/generators/entity.ts
-import { join as join19 } from "path";
-import { writeFileSync as writeFileSync12, existsSync as existsSync21 } from "fs";
+import { join as join20 } from "path";
+import { writeFileSync as writeFileSync12, existsSync as existsSync22 } from "fs";
 function generateSchema(fnDir, scope, fnName) {
-  const schemaFilePath = join19(fnDir, "src/server/entities/schema.ts");
-  if (existsSync21(schemaFilePath)) {
+  const schemaFilePath = join20(fnDir, "src/server/entities/schema.ts");
+  if (existsSync22(schemaFilePath)) {
     return;
   }
   const packageName = `${scope}/${fnName}`;
@@ -3975,7 +4204,7 @@ function generateEntity(fnDir, scope, fnName, entityName) {
     SCHEMA_FILE_NAME: schemaFileName
   });
   writeFileSync12(
-    join19(fnDir, `src/server/entities/${toKebabCase(entityName)}.ts`),
+    join20(fnDir, `src/server/entities/${toKebabCase(entityName)}.ts`),
     content
   );
 }
@@ -3983,11 +4212,11 @@ function generateEntitiesIndex(fnDir, entities) {
   const schemaExport = `export * from './schema';`;
   const entityExports = entities.map((entity) => `export * from './${toKebabCase(entity)}';`).join("\n");
   const content = [schemaExport, entityExports].filter(Boolean).join("\n");
-  writeFileSync12(join19(fnDir, "src/server/entities/index.ts"), content + "\n");
+  writeFileSync12(join20(fnDir, "src/server/entities/index.ts"), content + "\n");
 }
 
 // src/commands/generate/generators/repository.ts
-import { join as join20 } from "path";
+import { join as join21 } from "path";
 import { writeFileSync as writeFileSync13 } from "fs";
 function generateRepository(fnDir, entityName) {
   const pascalName = toPascalCase(entityName);
@@ -3998,17 +4227,17 @@ function generateRepository(fnDir, entityName) {
     REPO_NAME: repoName
   });
   writeFileSync13(
-    join20(fnDir, `src/server/repositories/${toKebabCase(entityName)}.repository.ts`),
+    join21(fnDir, `src/server/repositories/${toKebabCase(entityName)}.repository.ts`),
     content
   );
 }
 function generateRepositoriesIndex(fnDir, entities) {
   const exports = entities.map((entity) => `export * from './${toKebabCase(entity)}.repository';`).join("\n");
-  writeFileSync13(join20(fnDir, "src/server/repositories/index.ts"), exports + "\n");
+  writeFileSync13(join21(fnDir, "src/server/repositories/index.ts"), exports + "\n");
 }
 
 // src/commands/generate/generators/route.ts
-import { join as join21 } from "path";
+import { join as join22 } from "path";
 import { mkdirSync as mkdirSync4, writeFileSync as writeFileSync14 } from "fs";
 function generateRoute(fnDir, entityName) {
   const pascalName = toPascalCase(entityName);
@@ -4020,13 +4249,13 @@ function generateRoute(fnDir, entityName) {
     REPO_NAME: repoName,
     KEBAB_NAME: kebabName
   });
-  const routeDir = join21(fnDir, `src/server/routes/${kebabName}`);
+  const routeDir = join22(fnDir, `src/server/routes/${kebabName}`);
   mkdirSync4(routeDir, { recursive: true });
-  writeFileSync14(join21(routeDir, "index.ts"), content);
+  writeFileSync14(join22(routeDir, "index.ts"), content);
 }
 
 // src/commands/generate/generators/contract.ts
-import { join as join22 } from "path";
+import { join as join23 } from "path";
 import { writeFileSync as writeFileSync15 } from "fs";
 function generateContract(fnDir, entityName) {
   const pascalName = toPascalCase(entityName);
@@ -4035,13 +4264,13 @@ function generateContract(fnDir, entityName) {
     ENTITY_NAME: entityName
   });
   writeFileSync15(
-    join22(fnDir, `src/lib/contracts/${toKebabCase(entityName)}.ts`),
+    join23(fnDir, `src/lib/contracts/${toKebabCase(entityName)}.ts`),
     content
   );
 }
 
 // src/commands/generate/generators/index-files.ts
-import { join as join23 } from "path";
+import { join as join24 } from "path";
 import { writeFileSync as writeFileSync16 } from "fs";
 function generateMainIndex(fnDir, fnName) {
   const content = `/**
@@ -4068,7 +4297,7 @@ export * from '@/lib/types/index';
 
 export * from '@/server/entities/index';
 `;
-  writeFileSync16(join23(fnDir, "src/index.ts"), content);
+  writeFileSync16(join24(fnDir, "src/index.ts"), content);
 }
 function generateServerIndex(fnDir) {
   const content = `/**
@@ -4103,7 +4332,7 @@ export * from '@/server/repositories/index';
 
 // TODO: Export helpers here
 `;
-  writeFileSync16(join23(fnDir, "src/server.ts"), content);
+  writeFileSync16(join24(fnDir, "src/server.ts"), content);
 }
 function generateClientIndex(fnDir) {
   const content = `/**
@@ -4136,7 +4365,7 @@ export * from './client/store';
 
 export * from './client/components';
 `;
-  writeFileSync16(join23(fnDir, "src/client.ts"), content);
+  writeFileSync16(join24(fnDir, "src/client.ts"), content);
 }
 function generateTypesFile(fnDir, fnName) {
   const content = `/**
@@ -4148,7 +4377,7 @@ function generateTypesFile(fnDir, fnName) {
 
 export * from '@/lib/types/index';
 `;
-  writeFileSync16(join23(fnDir, "src/types.ts"), content);
+  writeFileSync16(join24(fnDir, "src/types.ts"), content);
 }
 
 // src/commands/generate/generators/structure.ts
@@ -4170,7 +4399,7 @@ async function generateFunctionStructure(options) {
     "src/client/store",
     "src/client/components"
   ];
-  dirs.forEach((dir) => mkdirSync5(join24(fnDir, dir), { recursive: true }));
+  dirs.forEach((dir) => mkdirSync5(join25(fnDir, dir), { recursive: true }));
   generatePackageJson(fnDir, scope, fnName, description);
   generateTsConfig(fnDir);
   generateTsupConfig(fnDir);
@@ -4190,15 +4419,15 @@ async function generateFunctionStructure(options) {
     generateEntitiesIndex(fnDir, entities);
     generateRepositoriesIndex(fnDir, entities);
   } else {
-    writeFileSync17(join24(fnDir, "src/server/entities/index.ts"), "// Export your entities here\nexport {}\n");
-    writeFileSync17(join24(fnDir, "src/server/repositories/index.ts"), "// Export your repositories here\nexport {}\n");
-  }
-  writeFileSync17(join24(fnDir, "src/client/hooks/index.ts"), "/**\n * Client Hooks\n */\n\n// TODO: Add hooks (e.g., useAuth, useData, etc.)\nexport {}\n");
-  writeFileSync17(join24(fnDir, "src/client/store/index.ts"), "/**\n * Client Store\n */\n\n// TODO: Add Zustand store if needed\nexport {}\n");
-  writeFileSync17(join24(fnDir, "src/client/components/index.ts"), "/**\n * Client Components\n */\n\n// TODO: Add React components\nexport {}\n");
-  writeFileSync17(join24(fnDir, "src/client/index.ts"), "/**\n * Client Module Entry\n */\n\nexport * from './hooks';\nexport * from './store';\nexport * from './components';\n");
-  writeFileSync17(join24(fnDir, "src/lib/types/index.ts"), "/**\n * Shared Type Definitions\n */\n\n// Add your shared types here\nexport {}\n");
-  writeFileSync17(join24(fnDir, "src/lib/contracts/index.ts"), "/**\n * API Contracts\n */\n\n// Export your contracts here\nexport {}\n");
+    writeFileSync17(join25(fnDir, "src/server/entities/index.ts"), "// Export your entities here\nexport {}\n");
+    writeFileSync17(join25(fnDir, "src/server/repositories/index.ts"), "// Export your repositories here\nexport {}\n");
+  }
+  writeFileSync17(join25(fnDir, "src/client/hooks/index.ts"), "/**\n * Client Hooks\n */\n\n// TODO: Add hooks (e.g., useAuth, useData, etc.)\nexport {}\n");
+  writeFileSync17(join25(fnDir, "src/client/store/index.ts"), "/**\n * Client Store\n */\n\n// TODO: Add Zustand store if needed\nexport {}\n");
+  writeFileSync17(join25(fnDir, "src/client/components/index.ts"), "/**\n * Client Components\n */\n\n// TODO: Add React components\nexport {}\n");
+  writeFileSync17(join25(fnDir, "src/client/index.ts"), "/**\n * Client Module Entry\n */\n\nexport * from './hooks';\nexport * from './store';\nexport * from './components';\n");
+  writeFileSync17(join25(fnDir, "src/lib/types/index.ts"), "/**\n * Shared Type Definitions\n */\n\n// Add your shared types here\nexport {}\n");
+  writeFileSync17(join25(fnDir, "src/lib/contracts/index.ts"), "/**\n * API Contracts\n */\n\n// Export your contracts here\nexport {}\n");
   generateMainIndex(fnDir, fnName);
   generateServerIndex(fnDir);
   generateClientIndex(fnDir);
@@ -4222,8 +4451,8 @@ async function generateFunction(name, options) {
     logger.error("Function name is required");
     process.exit(1);
   }
-  const fnDir = join25(cwd, fnName);
-  if (existsSync22(fnDir)) {
+  const fnDir = join26(cwd, fnName);
+  if (existsSync23(fnDir)) {
     logger.error(`Directory ${fnName} already exists at ${fnDir}`);
     process.exit(1);
   }
@@ -4288,13 +4517,29 @@ generateCommand.command("fn").description("Generate a new SPFN function module")
 // src/commands/env.ts
 import { Command as Command12 } from "commander";
 import chalk26 from "chalk";
-import { existsSync as existsSync23, readFileSync as readFileSync8, writeFileSync as writeFileSync18 } from "fs";
+import { existsSync as existsSync24, readFileSync as readFileSync8, writeFileSync as writeFileSync18 } from "fs";
 import { resolve } from "path";
 import { parse } from "dotenv";
-var ENV_FILES = {
+var VALID_ENVS = ["local", "development", "staging", "production", "test"];
+var BASE_ENV_FILES = {
   nextjs: [".env", ".env.local"],
   server: [".env.server", ".env.server.local"]
 };
+function getEnvFilesForEnvironment(nodeEnv) {
+  const files = [".env"];
+  if (nodeEnv) {
+    files.push(`.env.${nodeEnv}`);
+  }
+  if (nodeEnv !== "test") {
+    files.push(".env.local");
+  }
+  if (nodeEnv) {
+    files.push(`.env.${nodeEnv}.local`);
+  }
+  files.push(".env.server");
+  files.push(".env.server.local");
+  return files;
+}
 function getTargetFile(schema) {
   const isNextjs = schema.nextjs ?? schema.key?.startsWith("NEXT_PUBLIC_");
   if (isNextjs) {
@@ -4327,8 +4572,7 @@ function formatType(type) {
     enum: chalk26.magenta,
     json: chalk26.red
   };
-  const colorFn = typeColors[type] || chalk26.white;
-  return colorFn(type);
+  return (typeColors[type] || chalk26.white)(type);
 }
 function formatDefault(value, type) {
   if (value === void 0) {
@@ -4489,8 +4733,19 @@ var envCommand = new Command12("env").description("Manage environment variables"
 envCommand.command("list").description("List all environment variables from schema").option("-p, --package <package>", "Package name to read env schema from", "@spfn/core").option("-g, --group", "Group variables by target file").action(listEnvVars);
 envCommand.command("stats").description("Show environment variable statistics").option("-p, --package <package>", "Package name to read env schema from", "@spfn/core").action(showEnvStats);
 envCommand.command("search").description("Search environment variables").argument("<query>", "Search query (matches key or description)").option("-p, --package <package>", "Package name to read env schema from", "@spfn/core").action(searchEnvVars);
+function validateEnvOption(envValue) {
+  if (!VALID_ENVS.includes(envValue)) {
+    console.error(chalk26.red(`
+\u274C Invalid environment: "${envValue}"`));
+    console.log(chalk26.dim(`   Valid values: ${VALID_ENVS.join(", ")}
+`));
+    process.exit(1);
+  }
+  return envValue;
+}
 async function initEnvFiles(options) {
   const packageName = options.package || "@spfn/core";
+  const targetEnv = options.env ? validateEnvOption(options.env) : void 0;
   const cwd = process.cwd();
   try {
     const envSchema = await loadEnvSchema(packageName);
@@ -4502,24 +4757,41 @@ async function initEnvFiles(options) {
       acc[exampleFile].push([key, schema]);
       return acc;
     }, {});
-    console.log(chalk26.blue.bold(`
+    if (targetEnv) {
+      console.log(chalk26.blue.bold(`
+\u{1F680} Generating .env template files for ${chalk26.cyan(targetEnv)} environment
+`));
+      const envSpecificFiles = {};
+      const committedVars = allVars.filter(([_, schema]) => !schema.sensitive);
+      if (committedVars.length > 0) {
+        envSpecificFiles[`.env.${targetEnv}.example`] = committedVars;
+      }
+      const sensitiveVars = allVars.filter(([_, schema]) => schema.sensitive);
+      if (sensitiveVars.length > 0) {
+        envSpecificFiles[`.env.${targetEnv}.local.example`] = sensitiveVars;
+      }
+      const allGrouped = { ...grouped, ...envSpecificFiles };
+      for (const [file, vars] of Object.entries(allGrouped)) {
+        writeEnvTemplate(cwd, file, vars, options.force ?? false);
+      }
+    } else {
+      console.log(chalk26.blue.bold(`
 \u{1F680} Generating .env template files
 `));
-    for (const [file, vars] of Object.entries(grouped)) {
-      const filePath = resolve(cwd, file);
-      if (existsSync23(filePath) && !options.force) {
-        console.log(chalk26.yellow(`  \u23ED\uFE0F  ${file} already exists (use --force to overwrite)`));
-        continue;
+      for (const [file, vars] of Object.entries(grouped)) {
+        writeEnvTemplate(cwd, file, vars, options.force ?? false);
       }
-      const content = generateEnvFileContent(vars);
-      writeFileSync18(filePath, content, "utf-8");
-      console.log(chalk26.green(`  \u2705 ${file} (${vars.length} variables)`));
     }
     console.log(chalk26.dim("\n\u{1F4A1} Copy .example files to create your actual .env files:"));
     console.log(chalk26.dim("   cp .env.example .env"));
     console.log(chalk26.dim("   cp .env.local.example .env.local"));
     console.log(chalk26.dim("   cp .env.server.example .env.server"));
-    console.log(chalk26.dim("   cp .env.server.local.example .env.server.local\n"));
+    console.log(chalk26.dim("   cp .env.server.local.example .env.server.local"));
+    if (targetEnv) {
+      console.log(chalk26.dim(`   cp .env.${targetEnv}.example .env.${targetEnv}`));
+      console.log(chalk26.dim(`   cp .env.${targetEnv}.local.example .env.${targetEnv}.local`));
+    }
+    console.log("");
   } catch (error) {
     console.error(chalk26.red(`
 \u274C ${error instanceof Error ? error.message : "Unknown error"}
@@ -4527,6 +4799,15 @@ async function initEnvFiles(options) {
     process.exit(1);
   }
 }
+function writeEnvTemplate(cwd, file, vars, force) {
+  const filePath = resolve(cwd, file);
+  if (existsSync24(filePath) && !force) {
+    console.log(chalk26.yellow(`  \u23ED\uFE0F  ${file} already exists (use --force to overwrite)`));
+    return;
+  }
+  writeFileSync18(filePath, generateEnvFileContent(vars), "utf-8");
+  console.log(chalk26.green(`  \u2705 ${file} (${vars.length} variables)`));
+}
 function generateEnvFileContent(vars) {
   const lines = [
     "# Auto-generated by spfn env init",
@@ -4554,20 +4835,22 @@ function generateEnvFileContent(vars) {
 }
 async function checkEnvFiles(options) {
   const packageName = options.package || "@spfn/core";
+  const targetEnv = options.env ? validateEnvOption(options.env) : void 0;
   const cwd = process.cwd();
   try {
     const envSchema = await loadEnvSchema(packageName);
     const allVars = Object.entries(envSchema);
+    const envLabel = targetEnv ? ` (${targetEnv})` : "";
     console.log(chalk26.blue.bold(`
-\u{1F50D} Checking .env files against schema
+\u{1F50D} Checking .env files against schema${envLabel}
 `));
-    const allFiles = [...ENV_FILES.nextjs, ...ENV_FILES.server];
+    const filesToCheck = targetEnv ? getEnvFilesForEnvironment(targetEnv) : [...BASE_ENV_FILES.nextjs, ...BASE_ENV_FILES.server];
     const loadedEnv = {};
     const issues = [];
     const warnings = [];
-    for (const file of allFiles) {
+    for (const file of filesToCheck) {
       const filePath = resolve(cwd, file);
-      if (!existsSync23(filePath)) {
+      if (!existsSync24(filePath)) {
         continue;
       }
       const content = readFileSync8(filePath, "utf-8");
@@ -4587,8 +4870,8 @@ async function checkEnvFiles(options) {
         }
         continue;
       }
-      const isNextjsFile = ENV_FILES.nextjs.includes(found.file);
-      const isServerFile = ENV_FILES.server.includes(found.file);
+      const isNextjsFile = BASE_ENV_FILES.nextjs.includes(found.file);
+      const isServerFile = BASE_ENV_FILES.server.includes(found.file);
       const shouldBeNextjs = schema.nextjs ?? key.startsWith("NEXT_PUBLIC_");
       if (!shouldBeNextjs && isNextjsFile && !isServerFile) {
         if (schema.sensitive) {
@@ -4638,12 +4921,91 @@ async function checkEnvFiles(options) {
     process.exit(1);
   }
 }
-envCommand.command("init").description("Generate .env template files from schema").option("-p, --package <package>", "Package name to read env schema from", "@spfn/core").option("-f, --force", "Overwrite existing files").action(initEnvFiles);
-envCommand.command("check").description("Check .env files against schema").option("-p, --package <package>", "Package name to read env schema from", "@spfn/core").action(checkEnvFiles);
+envCommand.command("init").description("Generate .env template files from schema").option("-p, --package <package>", "Package name to read env schema from", "@spfn/core").option("-e, --env <environment>", "Generate environment-specific templates (e.g. production, staging)").option("-f, --force", "Overwrite existing files").action(initEnvFiles);
+envCommand.command("check").description("Check .env files against schema").option("-p, --package <package>", "Package name to read env schema from", "@spfn/core").option("-e, --env <environment>", "Check files for a specific environment (e.g. production)").action(checkEnvFiles);
+async function validateEnvVars(options) {
+  const packages = options.packages || ["@spfn/core"];
+  const targetEnv = options.env ? validateEnvOption(options.env) : void 0;
+  if (targetEnv) {
+    const { loadEnv: loadEnv6 } = await import("@spfn/core/env/loader");
+    const result = loadEnv6({ nodeEnv: targetEnv });
+    console.log(chalk26.blue.bold(`
+\u{1F50D} Validating environment variables for ${chalk26.cyan(targetEnv)}
+`));
+    if (result.loadedFiles.length > 0) {
+      console.log(chalk26.dim(`  Loaded: ${result.loadedFiles.join(", ")}`));
+    }
+    console.log("");
+  } else {
+    console.log(chalk26.blue.bold(`
+\u{1F50D} Validating environment variables
+`));
+  }
+  const allErrors = [];
+  const allWarnings = [];
+  for (const packageName of packages) {
+    try {
+      console.log(chalk26.dim(`  \u{1F4E6} ${packageName}`));
+      const envSchema = await loadEnvSchema(packageName);
+      const { createEnvRegistry } = await import("@spfn/core/env");
+      const registry = createEnvRegistry(envSchema);
+      const result = registry.validateAll();
+      for (const error of result.errors) {
+        allErrors.push({ ...error, package: packageName });
+      }
+      for (const warning of result.warnings) {
+        allWarnings.push({ ...warning, package: packageName });
+      }
+    } catch (error) {
+      if (error instanceof Error && error.message.includes("does not export envSchema")) {
+        console.log(chalk26.dim(`    \u23ED\uFE0F  No envSchema exported, skipping`));
+        continue;
+      }
+      console.error(chalk26.red(`    \u274C Failed to load: ${error instanceof Error ? error.message : String(error)}`));
+      if (options.strict) {
+        process.exit(1);
+      }
+    }
+  }
+  console.log("");
+  if (allErrors.length > 0) {
+    console.log(chalk26.red.bold(`\u274C Validation Errors (${allErrors.length}):
+`));
+    for (const error of allErrors) {
+      console.log(`  ${chalk26.red("\u2717")} ${chalk26.cyan(error.key)}`);
+      console.log(`    ${chalk26.dim(error.message)}`);
+      console.log(`    ${chalk26.dim(`from ${error.package}`)}`);
+      console.log("");
+    }
+  }
+  if (allWarnings.length > 0) {
+    console.log(chalk26.yellow.bold(`\u26A0\uFE0F  Warnings (${allWarnings.length}):
+`));
+    for (const warning of allWarnings) {
+      console.log(`  ${chalk26.yellow("\u26A0")} ${chalk26.cyan(warning.key)}`);
+      console.log(`    ${chalk26.dim(warning.message)}`);
+      console.log("");
+    }
+  }
+  if (allErrors.length === 0 && allWarnings.length === 0) {
+    console.log(chalk26.green.bold("\u2705 All environment variables are valid!\n"));
+  } else if (allErrors.length === 0) {
+    console.log(chalk26.green("\u2705 No errors found."));
+    console.log(chalk26.yellow(`\u26A0\uFE0F  ${allWarnings.length} warning(s) found.
+`));
+  } else {
+    console.log(chalk26.red(`
+\u274C Validation failed with ${allErrors.length} error(s)
+`));
+    process.exit(1);
+  }
+}
+envCommand.command("validate").description("Validate environment variables against schema (for CI/CD)").option("-p, --packages <packages...>", "Packages to validate", ["@spfn/core"]).option("-e, --env <environment>", "Load env files for specific environment before validating").option("-s, --strict", "Exit on any error (including load failures)").action(validateEnvVars);
 
 // src/index.ts
+init_version();
 var program = new Command13();
-program.name("spfn").description("SPFN CLI - The Missing Backend for Next.js").version("0.1.0");
+program.name("spfn").description("SPFN CLI - The Missing Backend for Next.js").version(getCliVersion());
 program.addCommand(createCommand);
 program.addCommand(initCommand);
 program.addCommand(addCommand);