spfn 0.3.0-beta.3 → 0.3.0-beta.5

package/dist/templates/README.md

@@ -71,13 +71,28 @@ Next.js interceptor, `/login` starter UI, OAuth callback, and route map are alre
 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
+## Operations from the terminal
 
-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.
+Operating this app needs no admin dashboard. Ops routes live in
+`src/server/routes/ops.ts`, are written like any other route, and the `spfn ops`
+CLI discovers them from the running server:
+
+```bash
+# 1. Seed an administrator: uncomment SPFN_AUTH_ADMIN_ACCOUNTS in .env.server,
+#    then restart the server so the account is created.
+
+# 2. Issue a token for this machine (stored in the OS keychain on macOS)
+{{pmExec}} spfn ops token issue --name laptop --scopes 'example:read'
+
+# 3. Run the app's own operations
+{{pmExec}} spfn ops list --app http://localhost:8790
+{{pmExec}} spfn ops call countExamples --app http://localhost:8790
+{{pmExec}} spfn ops call listRecentExamples --describe   # usage from the route's schema
+```
+
+Tokens are scoped and revocable (`spfn ops token list` / `revoke`). Add your own
+commands by exporting more `opsRoute` handlers and passing them to
+`createOpsRouter` — no CLI change is needed, the manifest carries them.
 <!-- {{/auth}} -->
 
 ## Deployment

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

@@ -2,12 +2,12 @@
  * 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.
+ * `.skip(['auth'])`; the ops router owns its own ops-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 { opsRouter } from './routes/ops';
 import {
     listExamples,
     getExample,
@@ -24,7 +24,7 @@ export const appRouter = defineRouter({
     updateExample,
     deleteExample,
 })
-    .packages([authRouter, mcpRouter])
+    .packages([authRouter, opsRouter])
     .use([authenticate]);
 
 export type AppRouter = typeof appRouter;

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

@@ -0,0 +1,52 @@
+/**
+ * Ops routes — operate this application from the terminal.
+ *
+ * Operations are written exactly like features: `opsRoute` puts them under the
+ * `/_ops` namespace, and `createOpsRouter` injects `opsTokenAuth` into every one
+ * of them plus serves `GET /_ops/_manifest`, which the `spfn ops` CLI reads to
+ * discover the commands this app owns.
+ *
+ * First run, against a running server:
+ *
+ *   spfn ops token issue --name laptop --scopes 'example:read'
+ *   spfn ops list --app http://localhost:8790
+ *   spfn ops call countExamples --app http://localhost:8790
+ *
+ * Issuing a token signs in as an administrator, so seed one first with
+ * `SPFN_AUTH_ADMIN_ACCOUNTS` in `.env.server`.
+ */
+import { createOpsRouter, opsRoute } from '@spfn/core/ops';
+import { opsTokenAuth, requireOpsScope } from '@spfn/auth/server';
+import { Type } from '@sinclair/typebox';
+import { ExampleRepository } from '../repositories/example.repository';
+
+const exampleRepo = new ExampleRepository();
+
+/**
+ * GET /_ops/examples/count — how many examples exist
+ */
+const countExamples = opsRoute.get('/examples/count')
+    .use([requireOpsScope('example:read')])
+    .handler(async () => ({ count: await exampleRepo.countAll() }));
+
+/**
+ * GET /_ops/examples — recent examples, ops view
+ */
+const listRecentExamples = opsRoute.get('/examples')
+    .use([requireOpsScope('example:read')])
+    .input({
+        query: Type.Object({
+            limit: Type.Optional(Type.Number({ minimum: 1, maximum: 100 })),
+        }),
+    })
+    .handler(async (c) =>
+    {
+        const { query } = await c.data();
+
+        return { items: await exampleRepo.findAll(query.limit ?? 10, 0) };
+    });
+
+export const opsRouter = createOpsRouter({
+    countExamples,
+    listRecentExamples,
+}, { auth: opsTokenAuth });

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

@@ -10,6 +10,6 @@ export const getRoot = route.get('/')
             health: '/_core/health',
             examples: '/examples',
             auth: '/_auth',
-            mcp: '/mcp',
+            ops: '/_ops',
         },
     }));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spfn",
-  "version": "0.3.0-beta.3",
+  "version": "0.3.0-beta.5",
   "description": "Scaffold a full-stack TypeScript backend onto a Next.js app built with an AI coding agent: auth, database, typed routes and codegen, one fixed vertical slice per feature",
   "type": "module",
   "bin": {
@@ -92,6 +92,7 @@
     "@types/pg": "^8.10.9",
     "@types/prompts": "^2.4.9",
     "concurrently": "^9.2.1",
+    "hono": "^4.12.34",
     "tsx": "^4.20.6",
     "typescript": "^5.3.3",
     "vitest": "^4.0.6"

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

@@ -1,23 +0,0 @@
-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

@@ -1,75 +0,0 @@
-/**
- * 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);
-}