spfn 0.2.0-beta.6 → 0.2.0-beta.60

package/dist/templates/.dockerignore

@@ -14,6 +14,7 @@ dist
 .env
 .env.local
 .env*.local
+.env.server
 
 # Git
 .git

package/dist/templates/Dockerfile

@@ -1,5 +1,5 @@
 # Production Dockerfile for SPFN
-FROM node:20-alpine
+FROM node:22-alpine
 
 WORKDIR /app
 

package/dist/templates/README.md

@@ -0,0 +1,81 @@
+# {{projectName}}
+
+A full-stack app built with [SPFN](https://github.com/spfn/spfn) — a typed SPFN
+backend running alongside Next.js.
+
+## Getting started
+
+```bash
+# 1. Start PostgreSQL + Redis
+docker compose up -d
+
+# 2. The env files are generated for you:
+#    .env.local  — Next.js-facing values (gitignored)
+#    .env.server — server secrets: DB, cache (gitignored, never loaded by Next.js)
+#    Review them and adjust as needed.
+
+# 3. Start the dev server (Next.js :3790 + SPFN API :8790)
+{{pmRun}} spfn:dev
+```
+
+Then open:
+
+- Next.js — http://localhost:3790
+- API health — http://localhost:8790/health
+
+## Project structure
+
+```
+src/
+  app/                 Next.js App Router
+  server/              SPFN backend (entities, repositories, routes, router)
+  generated/           codegen output (route map) — do not edit by hand
+.env.local             Next.js-facing env (gitignored)
+.env.server            server secrets (gitignored)
+.env.example           committed reference — keys only, placeholder values
+.spfnrc.ts             codegen configuration
+spfn.config.js         deployment config
+```
+
+A feature is a vertical slice: `Entity` (Drizzle table) → `Repository` →
+`Route` (TypeBox validation) → `Router` → `{{pmRun}} codegen` → typed client.
+
+## Common commands
+
+```bash
+{{pmRun}} spfn:dev          # dev: Next.js + SPFN API (add --watch to restart on changes)
+{{pmRun}} spfn:build        # production build
+{{pmRun}} spfn:start        # run the production build
+{{pm}} spfn db generate     # create a migration from schema changes
+{{pm}} spfn db migrate      # apply pending migrations
+{{pm}} spfn env check       # check .env files against the schema
+{{pm}} spfn secret set DB_URL   # store a secret (keychain locally, SOPS for deploys)
+```
+
+## Environment & secrets
+
+`.env.server` holds server-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
+in encrypted SOPS files. See the [SPFN CLI docs](https://github.com/spfn/spfn).
+
+<!-- {{#auth}} -->
+## Authentication
+
+This project includes `@spfn/auth`. Configure providers and session settings in your
+server setup, and read `@spfn/auth`'s README for the full Entity → Repository →
+Service → Route flow and the typed `authApi` client.
+<!-- {{/auth}} -->
+
+## Deployment
+
+```bash
+# Build + run locally
+{{pmRun}} spfn:build && {{pmRun}} spfn:start
+
+# Or with Docker
+docker compose -f docker-compose.production.yml up --build -d
+```
+
+Never commit real secrets. `.env.server` is gitignored; inject secrets in your
+CI/CD pipeline or via `spfn secret` + your GitOps decryption step.

package/dist/templates/lib/api-client.ts

@@ -1,47 +1,80 @@
 /**
  * API Client Configuration
  *
- * Type-safe client for accessing server routes
- */
-
-import { createApi } from '@spfn/core/nextjs';
-import { errorRegistry } from "@spfn/core/errors";
-
-import type { AppRouter } from '@/server/router';
-
-/**
- * Pre-configured type-safe API client
- *
+ * Type-safe client for accessing server routes.
  * Core HTTP errors are automatically registered.
- * Add custom application errors via the errors field if needed.
  *
  * @example
  * ```typescript
  * import { api } from '@/lib/api-client';
  *
  * // Basic call
- * const user = await api.getUser
- *     .call({ id: '123' });
+ * const user = await api.getUser.call({ params: { id: '123' } });
  *
- * // Error handling with instanceof
- * try {
- *     await api.someRoute.call();
- * } catch (error) {
- *     if (error instanceof NotFoundError) {
- *         console.log('Resource not found');
- *     } else if (error instanceof ValidationError) {
- *         console.log('Validation failed:', error.fields);
- *     }
- * }
+ * // With options
+ * const data = await api.getData
+ *     .headers({ 'X-Custom': 'value' })
+ *     .fetchOptions({ next: { revalidate: 60 } })
+ *     .call({ query: { page: 1 } });
  * ```
- *
- * Works in:
- * - Server Components (no router import needed)
- * - Client Components (proxied through /api/actions)
- * - Server Actions
- * - Route Handlers
  */
+
+import { createApi } from '@spfn/core/nextjs';
+import type { AppRouter } from '@/server/router';
+
 export const api = createApi<AppRouter>({
-    errorRegistry: errorRegistry,
-    debug: true
-});
+    /**
+     * Base URL for RPC endpoint
+     * @default '/api/rpc'
+     */
+    // baseUrl: '/api/rpc',
+
+    /**
+     * Default headers for all requests
+     */
+    // headers: { 'X-Client': 'web' },
+
+    /**
+     * Request timeout in milliseconds
+     * @default 30000
+     */
+    // timeout: 30000,
+
+    /**
+     * Custom error registry for deserialization
+     * Core HTTP errors are automatically included.
+     *
+     * @example
+     * import { authErrorRegistry } from '@myapp/auth/errors';
+     * errorRegistry: [authErrorRegistry, MyCustomError]
+     */
+    // errorRegistry: [],
+
+    /**
+     * Global request interceptor
+     *
+     * @example
+     * onRequest: async (url, init) => {
+     *     init.headers = { ...init.headers, 'X-Request-Id': crypto.randomUUID() };
+     *     return init;
+     * }
+     */
+    // onRequest: async (url, init) => init,
+
+    /**
+     * Global response interceptor
+     *
+     * @example
+     * onResponse: async (response, body) => {
+     *     if (response.status === 401) redirect('/login');
+     *     return { response, body };
+     * }
+     */
+    // onResponse: async (response, body) => ({ response, body }),
+
+    /**
+     * Enable debug logging
+     * @default false
+     */
+    debug: process.env.NODE_ENV === 'development',
+});

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

@@ -36,88 +36,23 @@ export const envSchema = defineEnvSchema({
 });
 
 /**
- * Type-safe Environment Registry
+ * Type-safe Environment Variables
  *
- * Use this registry to access environment variables throughout your application.
- * It provides type-safe access and automatic validation.
+ * Variables are lazily validated on access — if a required variable is
+ * missing or invalid, an error is thrown at the first access point.
+ * This is timing-safe with dotenv loading.
  *
  * @example
  * ```typescript
  * import env from '@/server/config/env.config';
  *
- * // Get required variable (throws if missing)
- * const dbUrl = env.require('DATABASE_URL');
- *
- * // Get optional variable (returns undefined if missing)
- * const redisUrl = env.get('REDIS_URL');
- *
- * // Get with default value
- * const port = env.get('PORT') ?? 8790;
+ * const dbUrl = env.DATABASE_URL;   // throws if required and missing
+ * const port = env.PORT ?? 8790;    // optional with fallback
  * ```
- */
-export const env = createEnvRegistry(envSchema);
-
-/**
- * Validate Environment Variables
  *
- * This validation runs automatically when this module is imported.
- * It will fail fast on startup if any required variables are missing
- * or if there are configuration errors.
+ * For explicit upfront validation (e.g. in a CLI script), call
+ * `createEnvRegistry(envSchema).validateAll()` to get `{ errors, warnings }`.
  */
-if (typeof process !== 'undefined' && process.env.NODE_ENV !== 'test')
-{
-    const validation = env.validate();
-
-    // Critical errors (missing required variables)
-    if (!validation.valid)
-    {
-        console.error('\n❌ Environment Validation Failed\n');
-        console.error('The following required environment variables are missing or invalid:\n');
-
-        validation.errors.forEach((error) =>
-        {
-            console.error(`  • ${error.key}`);
-            console.error(`    ${error.message}`);
-
-            if (error.suggestion)
-            {
-                console.error(`    💡 ${error.suggestion}`);
-            }
-
-            console.error('');
-        });
-
-        console.error('Please check your .env files and ensure all required variables are set.');
-        console.error('See .env.example for reference.\n');
-
-        process.exit(1);
-    }
+export const env = createEnvRegistry(envSchema).validate();
 
-    // Non-critical warnings
-    if (validation.warnings.length > 0)
-    {
-        console.warn('\n⚠️  Environment Warnings:\n');
-
-        validation.warnings.forEach((warning) =>
-        {
-            console.warn(`  • ${warning.key}: ${warning.message}`);
-
-            if (warning.suggestion)
-            {
-                console.warn(`    💡 ${warning.suggestion}`);
-            }
-        });
-
-        console.warn('');
-    }
-}
-
-/**
- * Export the registry as default
- *
- * Import this in your application to access environment variables:
- * ```typescript
- * import env from '@/server/config/env.config';
- * ```
- */
-export default env;
+export default env;

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

@@ -1 +1 @@
-export { examples } from './example.entity';
+export { examples } from './example.entity';

package/dist/templates/server/entities/example.entity.ts

@@ -9,4 +9,4 @@ export const examples = pgTable('examples', {
 });
 
 export type Example = typeof examples.$inferSelect;
-export type NewExample = typeof examples.$inferInsert;
+export type NewExample = typeof examples.$inferInsert;

package/dist/templates/server/repositories/example.repository.ts

@@ -37,4 +37,4 @@ export class ExampleRepository extends BaseRepository
     {
         return await this._count(examples);
     }
-}
+}

package/dist/templates/server/router.ts

@@ -1,4 +1,3 @@
-
 /**
  * Application Router
  *
@@ -20,10 +19,10 @@ export const appRouter = defineRouter({
     getExample,
     createExample,
     updateExample,
-    deleteExample
+    deleteExample,
 });
 
 /**
  * Router type for client usage
  */
-export type AppRouter = typeof appRouter;
+export type AppRouter = typeof appRouter;

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

@@ -39,26 +39,16 @@ export const listExamples = route.get('/examples')
 
 /**
  * GET /examples/:id - Get single example
- *
- * This route requires authorization header for testing header validation
  */
 export const getExample = route.get('/examples/:id')
     .input({
-        headers: Type.Object({
-            test: Type.String({
-                description: 'Bearer token for authentication'
-            })
-        }),
         params: Type.Object({
             id: Type.String(),
         }),
     })
     .handler(async (c) =>
     {
-        const { params, headers } = await c.data();
-
-        // Log authorization header for testing
-        console.log('Authorization:', headers.test);
+        const { params } = await c.data();
 
         const example = await exampleRepo.findById(params.id);
 
@@ -137,4 +127,4 @@ export const deleteExample = route.delete('/examples/:id')
             success: true,
             id: params.id,
         };
-    });
+    });

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

@@ -15,4 +15,4 @@ export const getHealth = route.get('/health')
             timestamp: Date.now(),
             uptime: process.uptime(),
         };
-    });
+    });

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

@@ -16,8 +16,7 @@ export const getRoot = route.get('/')
             endpoints: {
                 health: '/health',
                 examples: '/examples',
-                teams: '/teams',
             },
             message: 'Welcome to SPFN! Visit /examples for usage examples.',
         };
-    });
+    });

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

@@ -2,10 +2,10 @@
  * Server Configuration
  */
 import { defineServerConfig } from '@spfn/core/server';
-import { appRouter } from "@/server/router";
+import { appRouter } from '@/server/router';
 
 export default defineServerConfig()
     .port(8790)
     .host('0.0.0.0')
     .routes(appRouter)
-    .build();
+    .build();

package/package.json

@@ -1,16 +1,26 @@
 {
   "name": "spfn",
-  "version": "0.2.0-beta.6",
+  "version": "0.2.0-beta.60",
   "description": "Superfunction CLI - Add SPFN to your Next.js project",
   "type": "module",
   "bin": {
-    "spfn": "./bin/spfn.js"
+    "spfn": "bin/spfn.js"
   },
   "types": "./dist/index.d.ts",
   "files": [
     "dist",
     "bin"
   ],
+  "scripts": {
+    "build": "tsup && node scripts/copy-templates.js",
+    "test": "vitest run",
+    "prepack": "node -e \"require('fs').copyFileSync('../../LICENSE','LICENSE')\"",
+    "dev": "tsup --watch",
+    "type-check": "tsc --noEmit",
+    "publish:alpha": "npm publish --access public --tag alpha",
+    "publish:beta": "npm publish --access public --tag beta",
+    "publish:latest": "npm publish --access public"
+  },
   "keywords": [
     "spfn",
     "cli",
@@ -27,26 +37,26 @@
     "typescript",
     "type-safe"
   ],
-  "author": "Ray Im <rayim@inflike.com>",
+  "author": "Ray Im <rayim@fxy.global>",
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/spfn/spfn.git",
+    "url": "git+https://github.com/fxylabs/spfn.git",
     "directory": "packages/cli"
   },
   "publishConfig": {
     "access": "public",
-    "tag": "alpha",
-    "registry": "https://registry.npmjs.org"
+    "tag": "beta"
   },
   "bugs": {
-    "url": "https://github.com/spfn/spfn/issues"
+    "url": "https://github.com/fxylabs/spfn/issues"
   },
-  "homepage": "https://github.com/spfn/spfn/tree/main/packages/cli#readme",
+  "homepage": "https://github.com/fxylabs/spfn/tree/main/packages/cli#readme",
   "engines": {
     "node": ">=18.18.0"
   },
   "peerDependencies": {
+    "@spfn/core": ">=0.2.0-beta.54",
     "typescript": "^5.3.0"
   },
   "peerDependenciesMeta": {
@@ -59,7 +69,8 @@
     "chokidar": "^4.0.3",
     "commander": "^11.1.0",
     "dotenv": "^17.2.3",
-    "drizzle-orm": "^0.45.0",
+    "drizzle-kit": "1.0.0-rc.4",
+    "drizzle-orm": "1.0.0-rc.4",
     "execa": "^8.0.1",
     "fs-extra": "^11.2.0",
     "ora": "^7.0.1",
@@ -67,21 +78,21 @@
     "postgres": "^3.4.0",
     "prompts": "^2.4.2",
     "tsup": "^8.5.0",
-    "@spfn/core": "0.2.0-beta.8"
+    "yaml": "^2.5.0"
+  },
+  "optionalDependencies": {
+    "@napi-rs/keyring": "^1.1.0"
   },
   "devDependencies": {
+    "@electric-sql/pglite": "^0.5.4",
+    "@spfn/core": "workspace:*",
     "@types/fs-extra": "^11.0.4",
     "@types/node": "^20.11.0",
     "@types/pg": "^8.10.9",
     "@types/prompts": "^2.4.9",
     "concurrently": "^9.2.1",
-    "drizzle-kit": "^0.31.6",
     "tsx": "^4.20.6",
-    "typescript": "^5.3.3"
-  },
-  "scripts": {
-    "build": "tsup && node scripts/copy-templates.js",
-    "dev": "tsup --watch",
-    "type-check": "tsc --noEmit"
+    "typescript": "^5.3.3",
+    "vitest": "^4.0.6"
   }
-}
+}

package/dist/commands/generate/templates/contract.template

@@ -1,58 +0,0 @@
-/**
- * {{PASCAL_NAME}} Contracts
- *
- * Auto-generated by SPFN CLI
- */
-
-import { Type } from '@sinclair/typebox';
-import { createContract } from '@spfn/core/route';
-
-/**
- * GET /{{ENTITY_NAME}}
- * List {{PASCAL_NAME}} items
- */
-export const list{{PASCAL_NAME}}Contract = createContract({
-    method: 'GET',
-    path: '/{{ENTITY_NAME}}',
-    query: Type.Object({
-        limit: Type.Optional(Type.Number({ minimum: 1, maximum: 100 })),
-        offset: Type.Optional(Type.Number({ minimum: 0 })),
-    }),
-    responses: {
-        200: Type.Object({
-            items: Type.Array(
-                Type.Object({
-                    id: Type.Number(),
-                    name: Type.String(),
-                    description: Type.Union([Type.String(), Type.Null()]),
-                    createdAt: Type.String(),
-                    updatedAt: Type.String(),
-                })
-            ),
-            limit: Type.Number(),
-            offset: Type.Number(),
-        }),
-    },
-});
-
-/**
- * POST /{{ENTITY_NAME}}
- * Create new {{PASCAL_NAME}}
- */
-export const create{{PASCAL_NAME}}Contract = createContract({
-    method: 'POST',
-    path: '/{{ENTITY_NAME}}',
-    body: Type.Object({
-        name: Type.String({ minLength: 1 }),
-        description: Type.Optional(Type.String()),
-    }),
-    responses: {
-        201: Type.Object({
-            id: Type.Number(),
-            name: Type.String(),
-            description: Type.Union([Type.String(), Type.Null()]),
-            createdAt: Type.String(),
-            updatedAt: Type.String(),
-        }),
-    },
-});

package/dist/commands/generate/templates/entity.template

@@ -1,28 +0,0 @@
-/**
- * {{PASCAL_NAME}} Entity
- *
- * Auto-generated by SPFN CLI
- */
-
-import { index, serial, text, timestamp } from 'drizzle-orm/pg-core';
-import { {{SCHEMA_VAR_NAME}} } from './{{SCHEMA_FILE_NAME}}';
-
-export const {{ENTITY_NAME}} = {{SCHEMA_VAR_NAME}}.table('{{TABLE_NAME}}', {
-    // Primary Key
-    id: serial('id').primaryKey(),
-
-    // Fields
-    name: text('name').notNull(),
-    description: text('description'),
-
-    // Timestamps
-    createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
-    updatedAt: timestamp('updated_at', { withTimezone: true }).notNull().defaultNow(),
-}, (table) => [
-    // Indexes
-    index('{{SCHEMA_NAME}}_{{TABLE_NAME}}_name_idx').on(table.name),
-]);
-
-// Type inference
-export type {{PASCAL_NAME}} = typeof {{ENTITY_NAME}}.$inferSelect;
-export type New{{PASCAL_NAME}} = typeof {{ENTITY_NAME}}.$inferInsert;

package/dist/commands/generate/templates/init-migration.template

@@ -1,3 +0,0 @@
--- Initial migration for @spfn/{{FN_NAME}}
--- Create schema for {{PASCAL_NAME}} package
-CREATE SCHEMA IF NOT EXISTS spfn_{{FN_NAME}};

package/dist/commands/generate/templates/repository.template

@@ -1,56 +0,0 @@
-/**
- * {{PASCAL_NAME}} Repository
- *
- * Auto-generated by SPFN CLI
- */
-
-import { findOne, findMany, create, update, deleteById } from '@spfn/core/db';
-import { eq } from 'drizzle-orm';
-import { {{ENTITY_NAME}} } from '@/entities';
-import type { {{PASCAL_NAME}}, New{{PASCAL_NAME}} } from '@/entities';
-
-export const {{REPO_NAME}} = {
-    /**
-     * Find {{PASCAL_NAME}} by ID
-     */
-    findById: async (id: number): Promise<{{PASCAL_NAME}} | null> =>
-    {
-        return findOne({{ENTITY_NAME}}, eq({{ENTITY_NAME}}.id, id));
-    },
-
-    /**
-     * Find all {{PASCAL_NAME}} items
-     */
-    findMany: async (options?: { limit?: number; offset?: number }): Promise<{{PASCAL_NAME}}[]> =>
-    {
-        const { limit = 20, offset = 0 } = options || {};
-        return findMany({{ENTITY_NAME}}, {
-            limit,
-            offset,
-        });
-    },
-
-    /**
-     * Create new {{PASCAL_NAME}}
-     */
-    create: async (data: New{{PASCAL_NAME}}): Promise<{{PASCAL_NAME}}> =>
-    {
-        return create({{ENTITY_NAME}}, data);
-    },
-
-    /**
-     * Update {{PASCAL_NAME}} by ID
-     */
-    updateById: async (id: number, data: Partial<New{{PASCAL_NAME}}>): Promise<{{PASCAL_NAME}} | null> =>
-    {
-        return update({{ENTITY_NAME}}, eq({{ENTITY_NAME}}.id, id), data);
-    },
-
-    /**
-     * Delete {{PASCAL_NAME}} by ID
-     */
-    deleteById: async (id: number): Promise<void> =>
-    {
-        await deleteById({{ENTITY_NAME}}, id);
-    },
-};