spfn 0.2.0-beta.9 → 0.3.0-beta.2

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,94 @@
+# {{projectName}}
+
+A full-stack app built with [SPFN](https://github.com/spfn/spfn) — a consistent
+architecture for taking an AI-built prototype to production. Scaffold mode: `{{mode}}`.
+
+## Getting started
+
+```bash
+# 1. Start PostgreSQL + Redis
+docker compose up -d
+
+# 2. The env files are generated for you:
+#    .env.local  — values loaded by Next.js, including auth session crypto (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 runtime 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
+{{pmExec}} spfn db generate     # create a migration from schema changes
+{{pmExec}} spfn db migrate      # apply pending migrations
+{{pmExec}} spfn env check       # check .env files against the schema
+{{pmExec}} spfn secret set DB_URL   # store a secret (keychain locally, SOPS for deploys)
+```
+
+## Environment & secrets
+
+`.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
+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
+generated env files, then run `{{pmExec}} spfn db migrate`. The lifecycle, router,
+Next.js interceptor, `/login` starter UI, OAuth callback, and route map are already wired.
+
+## Internationalization
+
+Edit `src/i18n/catalogs.ts` to add application-owned messages. Server components
+and handlers can import `getT` or `getClientMessages` from `@/i18n/server`.
+
+## Agent operations with MCP
+
+The SPFN API serves MCP at `http://localhost:8790/mcp`. Connect with the Bearer
+token stored as `SPFN_MCP_API_KEY` in `.env.server`, then replace the starter
+`app_status` tool in `src/server/mcp.ts` with operations from your domain layer.
+Before third-party access, replace the generated operator-key validator with your
+OAuth access-token validator and scope each tool to the resolved operator.
+<!-- {{/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

@@ -77,4 +77,4 @@ export const api = createApi<AppRouter>({
      * @default false
      */
     debug: process.env.NODE_ENV === 'development',
-});
+});

package/dist/templates/modes/full/src/app/auth/callback/page.tsx

@@ -0,0 +1 @@
+export { OAuthCallback as default } from '@spfn/auth/nextjs/client';

package/dist/templates/modes/full/src/app/login/page.tsx

@@ -0,0 +1,68 @@
+'use client';
+
+import { useState } from 'react';
+import { authApi } from '@spfn/auth';
+import { I18nProvider, useT } from '@spfn/i18n/client';
+import { catalogs } from '@/i18n/catalogs';
+
+const providers = ['google', 'github', 'kakao', 'naver'] as const;
+
+export default function LoginPage()
+{
+    return (
+        <I18nProvider locale="en" messages={catalogs.en ?? {}}>
+            <LoginContent />
+        </I18nProvider>
+    );
+}
+
+function LoginContent()
+{
+    const [error, setError] = useState<string>();
+    const [pending, setPending] = useState<string>();
+    const t = useT('common');
+
+    async function signIn(provider: typeof providers[number]): Promise<void>
+    {
+        setError(undefined);
+        setPending(provider);
+
+        try
+        {
+            const { authUrl } = provider === 'google'
+                ? await authApi.getGoogleOAuthUrl.call({ body: { returnUrl: '/' } })
+                : await authApi.getProviderOAuthUrl.call({
+                    params: { provider },
+                    body: { returnUrl: '/' },
+                });
+
+            window.location.assign(authUrl);
+        }
+        catch (cause)
+        {
+            setPending(undefined);
+            setError(cause instanceof Error ? cause.message : 'Could not start sign in');
+        }
+    }
+
+    return (
+        <main style={{ maxWidth: 420, margin: '10vh auto', padding: 24 }}>
+            <h1>{t('appName')} — Sign in</h1>
+            <p>Connect a provider key in <code>.env.server</code>, then continue.</p>
+            <div style={{ display: 'grid', gap: 12, marginTop: 24 }}>
+                {providers.map(provider => (
+                    <button
+                        key={provider}
+                        type="button"
+                        disabled={pending !== undefined}
+                        onClick={() => void signIn(provider)}
+                        style={{ padding: 12, textTransform: 'capitalize' }}
+                    >
+                        {pending === provider ? 'Connecting…' : `Continue with ${provider}`}
+                    </button>
+                ))}
+            </div>
+            {error ? <p role="alert">{error}</p> : null}
+        </main>
+    );
+}

package/dist/templates/modes/full/src/i18n/catalogs.ts

@@ -0,0 +1,16 @@
+import type { LocaleCatalogs } from '@spfn/i18n';
+
+export const catalogs: LocaleCatalogs = {
+    en: {
+        common: {
+            appName: 'My SPFN app',
+            welcome: 'Welcome, {name}',
+        },
+    },
+    ko: {
+        common: {
+            appName: '나의 SPFN 앱',
+            welcome: '환영합니다, {name}',
+        },
+    },
+};

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

@@ -0,0 +1,9 @@
+import { configureI18n } from '@spfn/i18n/server';
+import { catalogs } from './catalogs';
+
+configureI18n({
+    catalogs,
+    fallbackLocale: 'en',
+});
+
+export { getClientMessages, getT } from '@spfn/i18n/server';

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

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

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

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

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

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

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

@@ -0,0 +1,94 @@
+import { route } from '@spfn/core/route';
+import { Type } from '@sinclair/typebox';
+import { ExampleRepository } from '../repositories/example.repository';
+
+const exampleRepo = new ExampleRepository();
+
+export const listExamples = route.get('/examples')
+    .input({
+        query: Type.Object({
+            limit: Type.Optional(Type.Number({ minimum: 1, maximum: 100 })),
+            offset: Type.Optional(Type.Number({ minimum: 0 })),
+        }),
+    })
+    .skip(['auth'])
+    .handler(async (c) =>
+    {
+        const { query } = await c.data();
+        const limit = query.limit ?? 10;
+        const offset = query.offset ?? 0;
+
+        return {
+            examples: await exampleRepo.findAll(limit, offset),
+            total: await exampleRepo.countAll(),
+            limit,
+            offset,
+        };
+    });
+
+export const getExample = route.get('/examples/:id')
+    .input({
+        params: Type.Object({ id: Type.String() }),
+    })
+    .skip(['auth'])
+    .handler(async (c) =>
+    {
+        const { params } = await c.data();
+        const example = await exampleRepo.findById(params.id);
+        if (!example)
+        {
+            throw new Error('Example not found');
+        }
+
+        return example;
+    });
+
+export const createExample = route.post('/examples')
+    .input({
+        body: Type.Object({
+            name: Type.String(),
+            description: Type.String(),
+        }),
+    })
+    .handler(async (c) =>
+    {
+        const { body } = await c.data();
+
+        return exampleRepo.createExample(body);
+    });
+
+export const updateExample = route.put('/examples/:id')
+    .input({
+        params: Type.Object({ id: Type.String() }),
+        body: Type.Object({
+            name: Type.Optional(Type.String()),
+            description: Type.Optional(Type.String()),
+        }),
+    })
+    .handler(async (c) =>
+    {
+        const { params, body } = await c.data();
+        const example = await exampleRepo.updateExample(params.id, body);
+        if (!example)
+        {
+            throw new Error('Example not found');
+        }
+
+        return example;
+    });
+
+export const deleteExample = route.delete('/examples/:id')
+    .input({
+        params: Type.Object({ id: Type.String() }),
+    })
+    .handler(async (c) =>
+    {
+        const { params } = await c.data();
+        const example = await exampleRepo.deleteExample(params.id);
+        if (!example)
+        {
+            throw new Error('Example not found');
+        }
+
+        return { success: true, id: params.id };
+    });

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

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

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

@@ -0,0 +1,15 @@
+import { route } from '@spfn/core/route';
+
+export const getRoot = route.get('/')
+    .skip(['auth'])
+    .handler(async () => ({
+        name: 'SPFN API',
+        version: '1.0.0',
+        status: 'running',
+        endpoints: {
+            health: '/health',
+            examples: '/examples',
+            auth: '/_auth',
+            mcp: '/mcp',
+        },
+    }));

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

@@ -0,0 +1,14 @@
+/**
+ * Prototype-to-Production server configuration.
+ */
+import '@/i18n/server';
+import { createAuthLifecycle } from '@spfn/auth/server';
+import { defineServerConfig } from '@spfn/core/server';
+import { appRouter } from '@/server/router';
+
+export default defineServerConfig()
+    .port(8790)
+    .host('0.0.0.0')
+    .routes(appRouter)
+    .lifecycle(createAuthLifecycle())
+    .build();

package/dist/templates/server/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.',
         };
-    });
+    });