spfn 0.2.0-beta.60 → 0.2.0-beta.63

package/dist/templates/README.md

@@ -1,7 +1,7 @@
 # {{projectName}}
 
-A full-stack app built with [SPFN](https://github.com/spfn/spfn) — a typed SPFN
-backend running alongside Next.js.
+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
 
@@ -10,7 +10,7 @@ backend running alongside Next.js.
 docker compose up -d
 
 # 2. The env files are generated for you:
-#    .env.local  — Next.js-facing values (gitignored)
+#    .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.
 
@@ -30,7 +30,7 @@ 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.local             Next.js runtime env (gitignored)
 .env.server            server secrets (gitignored)
 .env.example           committed reference — keys only, placeholder values
 .spfnrc.ts             codegen configuration
@@ -46,15 +46,15 @@ A feature is a vertical slice: `Entity` (Drizzle table) → `Repository` →
 {{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)
+{{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 server-only secrets and is gitignored — Next.js never loads it.
+`.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).
@@ -63,8 +63,21 @@ in encrypted SOPS files. See the [SPFN CLI docs](https://github.com/spfn/spfn).
 ## 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.
+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

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spfn",
-  "version": "0.2.0-beta.60",
+  "version": "0.2.0-beta.63",
   "description": "Superfunction CLI - Add SPFN to your Next.js project",
   "type": "module",
   "bin": {