swallowkit 1.1.2 → 2.0.0-alpha.10

package/src/core/project/capabilities.ts

@@ -27,6 +27,13 @@ export interface CapabilityAuthProvider {
 export interface CapabilitiesContract {
   contractVersion: number;
   swallowkitVersion: string;
+  frontends: {
+    supported: string[];
+    default: string;
+    configuration: string;
+    reactArchitecture: string;
+    development: string;
+  };
   modelDeclarations: CapabilityModelDeclaration[];
   authentication: {
     correctWorkflow: string[];
@@ -46,6 +53,7 @@ export interface CapabilitiesContract {
   sharedModels: {
     idFieldRule: string;
     buildNote: string;
+    nativeSchemaMapping: string[];
   };
   seeding: {
     createTemplates: string;
@@ -53,10 +61,19 @@ export interface CapabilitiesContract {
     notes: string[];
   };
   machineCommands: string[];
+  provisioning: {
+    execution: string;
+    completion: string;
+    tracking: string;
+    recovery: string;
+    diagnostics: string;
+    approval: string;
+  };
   verifyChecks: {
     defaultChecks: string[];
     optInChecks: string[];
     customChecks: string;
+    backendBuild: string;
   };
 }
 
@@ -64,6 +81,13 @@ export function inspectCapabilities(): CapabilitiesContract {
   return {
     contractVersion: 1,
     swallowkitVersion: getSwallowKitVersion(),
+    frontends: {
+      supported: ["nextjs", "react"],
+      default: "nextjs",
+      configuration: "init --frontend nextjs|react; stored as frontend.framework in swallowkit.config.js. Missing settings preserve Next.js.",
+      reactArchitecture: "React/Vite SPA on SWA -> HTTP-only SWA managed Functions BFF (bff/) -> standalone Functions (functions/). Never link standalone Functions to SWA. Backend keys stay server-side.",
+      development: "React dev runs Vite:3000, BFF:7073, Functions:7071 and SWA CLI:4280; use the SWA port for same-origin APIs and authentication. Build/verify include BFF typechecking.",
+    },
     modelDeclarations: [
       {
         name: "schema",
@@ -94,6 +118,19 @@ export function inspectCapabilities(): CapabilitiesContract {
           "Role-based access control metadata applied to the generated CRUD Functions. `roles` guards all operations; `read`/`write` guard per-operation; `policy` references a named authorization policy from swallowkit.config auth.authorization.policies.",
         format:
           "export const authPolicy = { roles: ['admin'] };\n// or per-operation:\nexport const authPolicy = { read: ['user'], write: ['admin'] };\n// or a named policy:\nexport const authPolicy = { policy: 'adminOnly' };",
+        notes: [
+          "An explicit authPolicy without configured authentication blocks plan/apply/generate scaffold with auth-policy-without-auth before any artifacts are written. Run plan auth, apply auth, then re-plan scaffold. An empty {} declaration keeps the existing behavior: no explicit policy.",
+          "With named auth.schemes, define auth.authorization.policies selecting schemes and roles, then reference them via policy or read/write names. A role-only declaration cannot select a named scheme and blocks with auth-policy-requires-named-policy; it is supported by legacy single-provider authentication.",
+          "Conversely, single-provider authentication (auth.provider) supports role lists only. Referencing a named policy (authPolicy.policy, read/write names, or a named auth.authorization.defaultPolicy) blocks with auth-named-policy-requires-named-scheme; add a named scheme first.",
+        ],
+      },
+      {
+        name: "references",
+        required: false,
+        description:
+          "Explicit foreign keys used by generated UI lookups. Without it, a string field named <model>Id is treated as a foreign key only when shared/models contains that model (userId -> User only if user.ts exists). Map a field to false to disable inference. References to missing models are ignored with a reference-model-not-found warning.",
+        format: "export const references = { authorId: 'User', legacyId: false };",
+        notes: ["Only single string id fields can reference a model.", "No lookup UI, fetch, or OpenAPI reference is generated for fields that do not reference an existing model."],
       },
       {
         name: "connectorConfig",
@@ -160,15 +197,24 @@ export function inspectCapabilities(): CapabilitiesContract {
       ],
       notGuaranteed: [
         "Owner scoping: generated CRUD does NOT restrict rows to the authenticated principal. Any authenticated caller passing the policy can read/write any document.",
+        "Without authentication, plan scaffold reports user-scoped-data-without-auth when the partition key or an owner-like field (userId, learnerId, ownerId, ...) suggests per-user data.",
       ],
       guidance: [
-        "For multi-user data where users may only touch their own records, add ai-authored custom endpoints that derive the scoping key (e.g. learnerId) from the verified principal — never from the request body — and restrict generated write endpoints to admin roles or disable them.",
+        "Configure authentication via plan/apply auth before declaring authPolicy. For multi-user data where users may only touch their own records, add ai-authored custom endpoints that derive the scoping key (e.g. learnerId) from the verified principal — never from the request body — and restrict generated write endpoints to admin roles or disable them.",
       ],
     },
     sharedModels: {
       idFieldRule: "id: z.string() (required). createdAt/updatedAt: z.string().optional(). The backend owns their values.",
+      nativeSchemaMapping: [
+        "C#/Python schema assets derive types from Zod, never from field names: z.string() -> string/str (including createdAt/updatedAt).",
+        "Date types only when declared: z.iso.datetime() -> DateTime/datetime, z.iso.date() -> DateOnly/date, z.date() -> DateTime/datetime.",
+        "z.number() -> double / float|int; z.number().int() or z.int() -> long / int.",
+        "Inline z.object({...}) fields become named classes <Model><Field> (e.g. ProbeItemNested); imported model schemas keep their own class.",
+        "min/max/length/nonempty/regex/int/gt/gte/lt/lte/positive/nonnegative and array min/max are enforced by C# IValidatableObject.Validate and Python Field bounds/validators. Regexes use search semantics like Zod.",
+        "String formats (email/uuid/url), refinements, and transforms are not re-implemented natively; the BFF Zod schemas remain the authoritative validation.",
+      ],
       buildNote:
-        "verify typecheck resolves the shared package from its built dist/. SwallowKit rebuilds shared automatically during verify; when typechecking manually, build the shared package first (errors like \"no exported member\" usually mean a stale dist).",
+        "create-model and plan/apply scaffold append missing model exports to shared/index.ts, including manually authored models. Manual exports are allowed (no markers); existing content is preserved. verify typecheck resolves the shared package from its built dist/. SwallowKit rebuilds shared automatically during verify; when typechecking manually, build shared first.",
     },
     seeding: {
       createTemplates: "swallowkit create-dev-seeds <environment> — writes dev-seeds/<environment>/<model>.json templates.",
@@ -176,18 +222,29 @@ export function inspectCapabilities(): CapabilitiesContract {
       notes: ["Editing dev-seeds/*.json alone does nothing; seeds are only applied via dev --seed-env."],
     },
     machineCommands: [
-      "inspect project | entities | routes | artifacts | boundaries | infra | drift | capabilities",
+      "inspect project | entities | routes | artifacts | boundaries | infra | drift | capabilities; inspect provision --plan <runId> [--wait-seconds <0-3600>]",
       "validate project",
       "generate model <names...> | generate scaffold <model>",
-      "plan scaffold <models...> | plan auth --provider <p> [--scheme <name>] [--allowed-providers <csv>] | plan provision -g <rg> --location <loc> --swa-location <loc> [--adopt-existing --baseline 0 --what-if] [--reconcile --what-if]",
-      "apply scaffold [models...] --plan <id> [--approve] | apply auth --plan <id> [--approve] | apply provision --plan <id> --approve",
+      "plan scaffold <models...> [--api-only] [--skip-infra] | plan auth --provider <p> [--scheme <name>] [--allowed-providers <csv>] | plan provision -g <rg> --location <loc> --swa-location <loc> [--adopt-existing --baseline 0 --what-if] [--reconcile --what-if] [--resume-deployment <name>]",
+      "apply scaffold [models...] --plan <id> [--approve] [--skip-infra] | apply auth --plan <id> [--approve] | apply provision --plan <id> --approve [--wait-seconds <0-3600>] (also resumes the same execution checkpoint)",
       "verify project [--checks <ids>] [--compact]",
       "explain failure [--check <id>]",
+      "(regular CLI) migrations add-model <model> [--dry-run] — generate only the container migration after scaffold --skip-infra",
+      "(regular CLI) configure-mcp [--version auto|latest|<semver>] — re-select the MCP launcher version in .mcp.json",
     ],
+    provisioning: {
+      execution: "Submit Bicep once with az deployment group create --no-wait, then bounded state polling (default 300 seconds, configurable 0-3600) for machine/MCP; the human `swallowkit provision` command waits until Azure reaches a terminal state. Azure CLI invocations are bounded separately. Warning-only stderr with exit 0 is not a failure; output capture limits do not terminate az.",
+      completion: "status complete/outcome succeeded requires Azure Succeeded plus verified migration tags and local ledger completion. Running/Accepted -> in-progress; unreadable/not-found state -> blocked/outcome unknown; bookkeeping interruption after Azure Succeeded -> blocked/outcome partial; Failed/Canceled -> failed with Azure causes.",
+      tracking: "Approved runs persist before Azure writes under .swallowkit/state/provision/. runId equals the original planId and preserves the subscription, RG, deployment ID/correlation, fingerprints and migration state. inspect provision is read-only; apply provision --plan resumes without re-submitting attempted deployments. Ctrl+C/termination may leave Azure running; never cancel/delete without explicit consent.",
+      recovery: "For an older untracked baseline, plan provision --resume-deployment <name> compares the existing ARM template and non-secure parameters to the local Bicep/parameters. It observes that deployment and only tags/records it after Succeeded. Mismatches, unreadable evidence, secure parameters or non-baseline migrations block; do not use reconcile just to repair bookkeeping.",
+      diagnostics: "Machine/MCP results include bounded/redacted stdout/stderr, omitted-output flags, exit code, signal, failure kind, elapsed time and deployment identity, but no deployment outputs. Normal CLI shows named resource information and CI/CD setup guidance after success. Never print --debug output, keys, tokens or connection strings.",
+      approval: "Machine/MCP initial apply and every resume require explicit human approval. A human invoking normal provision or provision --resume explicitly requests execution without another confirmation prompt. Agents must not switch to normal CLI to bypass approval. A passing local command or an ok envelope is not proof of completed Azure provisioning; inspect status, outcome and nextActions.",
+    },
     verifyChecks: {
-      defaultChecks: ["structure", "drift", "typecheck"],
+      defaultChecks: ["structure", "drift", "typecheck", "backend-build"],
       optInChecks: ["build", "lint", "test"],
       customChecks: "swallowkit.config verify.checks: [{ id, command, title?, timeoutMs? }]",
+      backendBuild: "Runs dotnet build in functions/ (C#), the project tsc --noEmit (TypeScript), or Python 3 compileall (syntax only, using functions/.venv before PATH). Missing toolchains are skip with a reason, not proof of validation. Root build scripts do not replace backend-build; use --checks \"structure,drift,typecheck,backend-build,build\" for both.",
     },
   };
 }

package/src/core/project/home-page.ts

@@ -0,0 +1,114 @@
+import { FrontendFramework } from "../../types";
+import { PackageManager, getCommands } from "../../utils/package-manager";
+import { adaptReactPage } from "../scaffold/react-ui-generator";
+
+export function buildHomePage(
+  frontend: FrontendFramework,
+  pm: PackageManager
+): string {
+  const framework = frontend === "react" ? "React" : "Next.js";
+  const page = `import { useState } from 'react';
+import Link from 'next/link';
+import { scaffoldConfig } from '@/lib/scaffold-config';
+
+export default function Home() {
+  const [greetingStatus, setGreetingStatus] = useState<'idle' | 'loading' | 'success' | 'error'>('idle');
+  const [message, setMessage] = useState('');
+
+  const testConnection = async () => {
+    setGreetingStatus('loading');
+    try {
+      const response = await fetch('/api/greet?name=SwallowKit');
+      const data = await response.json();
+      if (!response.ok) {
+        throw new Error(data.error || \`Server error: \${response.status}\`);
+      }
+      setMessage(data.message);
+      setGreetingStatus('success');
+    } catch (error) {
+      setMessage(error instanceof Error ? error.message : 'Failed to connect to Azure Functions');
+      setGreetingStatus('error');
+    }
+  };
+
+  return (
+    <div className="min-h-screen bg-gradient-to-br from-blue-50 to-indigo-50 dark:from-gray-900 dark:to-gray-800">
+      <div className="container mx-auto px-4 py-12">
+        <header className="text-center mb-16">
+          <h1 className="text-5xl font-bold text-gray-800 dark:text-white mb-4">
+            Welcome to SwallowKit
+          </h1>
+          <p className="text-xl text-gray-600 dark:text-gray-400">
+            ${framework} on Azure Static Web Apps + Functions + Cosmos DB — Zod schema sharing
+          </p>
+        </header>
+
+        <section className="max-w-2xl mx-auto mb-12">
+          <div className="bg-white dark:bg-gray-800 rounded-xl p-8 border border-gray-200 dark:border-gray-700">
+            <h2 className="text-2xl font-semibold mb-4 text-gray-900 dark:text-gray-100">
+              Test BFF → Functions Connection
+            </h2>
+            <button
+              onClick={testConnection}
+              disabled={greetingStatus === 'loading'}
+              className="px-6 py-3 bg-blue-600 hover:bg-blue-700 disabled:bg-gray-400 text-white rounded-lg font-medium transition-colors"
+            >
+              {greetingStatus === 'loading' ? 'Testing...' : 'Test Connection'}
+            </button>
+            {greetingStatus === 'success' && (
+              <div role="status" className="mt-4 p-4 bg-green-50 dark:bg-green-900/20 border border-green-200 dark:border-green-800 rounded-lg">
+                <p className="text-green-800 dark:text-green-200 font-medium">✅ Connection successful!</p>
+                <p className="text-green-700 dark:text-green-300 text-sm mt-1">{message}</p>
+              </div>
+            )}
+            {greetingStatus === 'error' && (
+              <div role="alert" className="mt-4 p-4 bg-red-50 dark:bg-red-900/20 border border-red-200 dark:border-red-800 rounded-lg">
+                <p className="text-red-800 dark:text-red-200 font-medium">❌ Connection failed</p>
+                <p className="text-red-700 dark:text-red-300 text-sm mt-1">{message}</p>
+              </div>
+            )}
+          </div>
+        </section>
+
+        {scaffoldConfig.models.length > 0 ? (
+          <section className="max-w-6xl mx-auto">
+            <h2 className="text-3xl font-bold mb-8 text-gray-900 dark:text-gray-100">Your Models</h2>
+            <div className="grid gap-6 grid-cols-1 md:grid-cols-2 lg:grid-cols-3">
+              {scaffoldConfig.models.map((model) => (
+                <Link
+                  key={model.name}
+                  href={model.path}
+                  className="block p-8 bg-white dark:bg-gray-800 border border-gray-200 dark:border-gray-700 rounded-xl hover:shadow-lg hover:border-blue-400 dark:hover:border-blue-600 transition-all"
+                >
+                  <h3 className="text-2xl font-semibold mb-2 text-gray-900 dark:text-gray-100">{model.label}</h3>
+                  <p className="text-gray-600 dark:text-gray-400">Manage {model.label.toLowerCase()}</p>
+                </Link>
+              ))}
+            </div>
+          </section>
+        ) : (
+          <section className="max-w-2xl mx-auto text-center">
+            <div className="bg-white dark:bg-gray-800 rounded-xl p-12 border border-gray-200 dark:border-gray-700">
+              <h2 className="text-2xl font-semibold mb-4 text-gray-900 dark:text-gray-100">Get Started</h2>
+              <p className="text-gray-600 dark:text-gray-400 mb-6">
+                Create your first model with Zod and generate CRUD operations automatically.
+              </p>
+              <code className="block bg-gray-100 dark:bg-gray-900 p-4 rounded text-left text-sm">
+                ${getCommands(pm).exec} swallowkit scaffold shared/models/your-model.ts
+              </code>
+            </div>
+          </section>
+        )}
+
+        <footer className="mt-16 text-center text-gray-600 dark:text-gray-400 text-sm">
+          <p>Built with SwallowKit</p>
+        </footer>
+      </div>
+    </div>
+  );
+}
+`;
+  return frontend === "react"
+    ? adaptReactPage(page)
+    : `'use client'\n\nexport const dynamic = 'force-dynamic';\n\n${page}`;
+}

package/src/core/project/manifest.ts

@@ -1,8 +1,8 @@
 import * as fs from "fs";
 import * as path from "path";
-import { getBackendLanguage, getFullConfig, normalizeAuthConfig, validateConfig } from "../config";
+import { getBackendLanguage, getFrontendFramework, getFullConfig, normalizeAuthConfig, validateConfig } from "../config";
 import { getAllModels, toCamelCase, toKebabCase } from "../scaffold/model-parser";
-import { AuthConfig, BackendLanguage, ConnectorDefinition, ModelAuthPolicy, ModelConnectorConfig } from "../../types";
+import { AuthConfig, BackendLanguage, FrontendFramework, ConnectorDefinition, ModelAuthPolicy, ModelConnectorConfig } from "../../types";
 import { captureConsoleMessages, withWorkingDirectory } from "../operations/runtime";
 
 const CONFIG_CANDIDATES = [
@@ -69,6 +69,7 @@ export interface ProjectManifestArtifacts {
 
 export interface ProjectManifestArchitecture {
   pattern: string;
+  frontendFramework?: FrontendFramework;
   backendLanguage: BackendLanguage;
   layerBoundaries: string[];
   hasSharedWorkspace: boolean;
@@ -81,6 +82,7 @@ export interface ProjectManifest {
   generatedAt: string;
   configPath: string | null;
   backendLanguage: BackendLanguage;
+  frontendFramework?: FrontendFramework;
   configValidation: {
     valid: boolean;
     errors: string[];
@@ -115,7 +117,10 @@ function relativeProjectPath(projectRoot: string, targetPath: string): string {
   return path.relative(projectRoot, targetPath).replace(/\\/g, "/");
 }
 
-function buildModules(projectRoot: string): ProjectManifestModule[] {
+function buildModules(projectRoot: string, frontend: FrontendFramework): ProjectManifestModule[] {
+  const bffRoot = frontend === "react" ? "bff" : "app/api";
+  const uiRoot = frontend === "react" ? "src" : "app";
+  const authRoot = frontend === "react" ? "bff/src/auth" : "app/api/auth";
   const candidates: ProjectManifestModule[] = [
     {
       name: "shared-models",
@@ -126,8 +131,8 @@ function buildModules(projectRoot: string): ProjectManifestModule[] {
     {
       name: "bff",
       kind: "bff",
-      rootPath: "app/api",
-      exists: fs.existsSync(path.join(projectRoot, "app", "api")),
+      rootPath: bffRoot,
+      exists: fs.existsSync(path.join(projectRoot, bffRoot)),
     },
     {
       name: "functions",
@@ -138,8 +143,8 @@ function buildModules(projectRoot: string): ProjectManifestModule[] {
     {
       name: "ui",
       kind: "ui",
-      rootPath: "app",
-      exists: fs.existsSync(path.join(projectRoot, "app")),
+      rootPath: uiRoot,
+      exists: fs.existsSync(path.join(projectRoot, uiRoot)),
     },
     {
       name: "infrastructure",
@@ -150,21 +155,21 @@ function buildModules(projectRoot: string): ProjectManifestModule[] {
     {
       name: "auth",
       kind: "auth",
-      rootPath: "app/api/auth",
-      exists: fs.existsSync(path.join(projectRoot, "app", "api", "auth")),
+      rootPath: authRoot,
+      exists: fs.existsSync(path.join(projectRoot, authRoot)),
     },
   ];
 
   return candidates;
 }
 
-function buildArtifacts(projectRoot: string): ProjectManifestArtifacts {
+function buildArtifacts(projectRoot: string, frontend: FrontendFramework): ProjectManifestArtifacts {
   const openApiDir = path.join(projectRoot, "functions", "openapi");
   const generatedDir = path.join(projectRoot, "functions", "generated");
 
   return {
-    callFunctionHelperPath: "lib/api/call-function.ts",
-    callFunctionHelperExists: fs.existsSync(path.join(projectRoot, "lib", "api", "call-function.ts")),
+    callFunctionHelperPath: frontend === "react" ? "bff/src/lib/call-function.ts" : "lib/api/call-function.ts",
+    callFunctionHelperExists: fs.existsSync(path.join(projectRoot, ...(frontend === "react" ? ["bff", "src", "lib", "call-function.ts"] : ["lib", "api", "call-function.ts"]))),
     openApiSpecs: fs.existsSync(openApiDir)
       ? fs.readdirSync(openApiDir)
           .filter((entry) => entry.endsWith(".json"))
@@ -178,8 +183,8 @@ function buildArtifacts(projectRoot: string): ProjectManifestArtifacts {
       : [],
     proxyPath: "proxy.ts",
     proxyExists: fs.existsSync(path.join(projectRoot, "proxy.ts")),
-    loginPagePath: "app/login/page.tsx",
-    loginPageExists: fs.existsSync(path.join(projectRoot, "app", "login", "page.tsx")),
+    loginPagePath: frontend === "react" ? "src/pages/login.tsx" : "app/login/page.tsx",
+    loginPageExists: fs.existsSync(path.join(projectRoot, ...(frontend === "react" ? ["src", "pages", "login.tsx"] : ["app", "login", "page.tsx"]))),
     authContextPath: "lib/auth/auth-context.tsx",
     authContextExists: fs.existsSync(path.join(projectRoot, "lib", "auth", "auth-context.tsx")),
   };
@@ -188,7 +193,8 @@ function buildArtifacts(projectRoot: string): ProjectManifestArtifacts {
 function buildEntityRoutes(
   projectRoot: string,
   backendLanguage: BackendLanguage,
-  entity: ProjectManifestEntity
+  entity: ProjectManifestEntity,
+  frontend: FrontendFramework
 ): ProjectManifestRoute[] {
   const modelCamel = toCamelCase(entity.name);
   const modelKebab = toKebabCase(entity.name);
@@ -229,8 +235,10 @@ function buildEntityRoutes(
       entityName: entity.name,
       methods: listMethods,
       publicPath: `/api/${modelCamel}`,
-      filePath: `app/api/${modelCamel}/route.ts`,
-      exists: fs.existsSync(path.join(projectRoot, "app", "api", modelCamel, "route.ts")),
+      filePath: frontend === "react" ? `bff/src/${modelCamel}/index.ts` : `app/api/${modelCamel}/route.ts`,
+      exists: frontend === "react"
+        ? fs.existsSync(path.join(projectRoot, "bff", "src", modelCamel, "index.ts")) && fs.existsSync(path.join(projectRoot, "bff", modelCamel, "function.json"))
+        : fs.existsSync(path.join(projectRoot, "app", "api", modelCamel, "route.ts")),
     },
     {
       name: `${entity.name}-bff-detail`,
@@ -239,8 +247,10 @@ function buildEntityRoutes(
       entityName: entity.name,
       methods: detailMethods,
       publicPath: `/api/${modelCamel}/{id}`,
-      filePath: `app/api/${modelCamel}/[id]/route.ts`,
-      exists: fs.existsSync(path.join(projectRoot, "app", "api", modelCamel, "[id]", "route.ts")),
+      filePath: frontend === "react" ? `bff/src/${modelCamel}/index.ts` : `app/api/${modelCamel}/[id]/route.ts`,
+      exists: frontend === "react"
+        ? fs.existsSync(path.join(projectRoot, "bff", "src", modelCamel, "index.ts")) && fs.existsSync(path.join(projectRoot, "bff", modelCamel, "function.json"))
+        : fs.existsSync(path.join(projectRoot, "app", "api", modelCamel, "[id]", "route.ts")),
     },
     {
       name: `${entity.name}-functions`,
@@ -255,7 +265,18 @@ function buildEntityRoutes(
   ];
 }
 
-function buildSystemRoutes(projectRoot: string): ProjectManifestRoute[] {
+function buildSystemRoutes(projectRoot: string, frontend: FrontendFramework, auth?: AuthConfig): ProjectManifestRoute[] {
+  if (frontend === "react") {
+    const providers = Object.values(normalizeAuthConfig(auth)?.schemes ?? {}).map(scheme => scheme.provider);
+    return ["login", "logout", "me"].map(action => ({
+      name: `auth-${action}`, kind: "system", surface: "bff",
+      methods: [action === "me" ? "GET" : "POST"], publicPath: `/api/auth/${action}`,
+      filePath: "bff/src/auth/index.ts",
+      exists: (providers.includes("custom-jwt") || (action === "me" && providers.includes("external-token"))) &&
+        fs.existsSync(path.join(projectRoot, "bff", "src", "auth", "index.ts")) &&
+        fs.existsSync(path.join(projectRoot, "bff", "auth", "function.json")),
+    }));
+  }
   return [
     {
       name: "auth-login",
@@ -296,6 +317,7 @@ export async function buildProjectManifest(projectRoot: string = process.cwd()):
   return withWorkingDirectory(projectRoot, async () => {
     const configPath = resolveConfigPath(projectRoot);
     const backendLanguage = getBackendLanguage(configPath || undefined);
+    const frontendFramework = getFrontendFramework(configPath || undefined);
     const config = getFullConfig(configPath || undefined);
     const configValidation = validateConfig(config);
     const { result: entities, messages } = await captureConsoleMessages(async () => {
@@ -327,8 +349,8 @@ export async function buildProjectManifest(projectRoot: string = process.cwd()):
     );
 
     const routes = [
-      ...entities.flatMap((entity) => buildEntityRoutes(projectRoot, backendLanguage, entity)),
-      ...buildSystemRoutes(projectRoot),
+      ...entities.flatMap((entity) => buildEntityRoutes(projectRoot, backendLanguage, entity, frontendFramework)),
+      ...buildSystemRoutes(projectRoot, frontendFramework, config.auth),
     ].sort((left, right) => left.name.localeCompare(right.name));
 
     const manifest: ProjectManifest = {
@@ -336,6 +358,7 @@ export async function buildProjectManifest(projectRoot: string = process.cwd()):
       generatedAt: new Date().toISOString(),
       configPath,
       backendLanguage,
+      frontendFramework,
       configValidation,
       connectors: Object.entries(config.connectors || {})
         .map(([name, definition]) => ({ name, definition }))
@@ -343,16 +366,18 @@ export async function buildProjectManifest(projectRoot: string = process.cwd()):
       auth: normalizeAuthConfig(config.auth) || null,
       entities: entities.sort((left, right) => left.name.localeCompare(right.name)),
       routes,
-      modules: buildModules(projectRoot),
-      artifacts: buildArtifacts(projectRoot),
+      modules: buildModules(projectRoot, frontendFramework),
+      artifacts: buildArtifacts(projectRoot, frontendFramework),
       architecture: {
-        pattern: "Next.js BFF + Azure Functions + shared Zod models",
+        pattern: frontendFramework === "react" ? "React SPA + SWA managed Functions BFF + standalone Azure Functions + shared Zod models" : "Next.js BFF + Azure Functions + shared Zod models",
+        frontendFramework,
         backendLanguage,
         layerBoundaries: [
           "shared/models -> schema source of truth",
-          "app/api -> BFF layer only",
+          `${frontendFramework === "react" ? "bff" : "app/api"} -> BFF layer only`,
           "functions -> backend logic and data access",
-          "app -> UI and pages",
+          `${frontendFramework === "react" ? "src" : "app"} -> UI and pages`,
+          "SWA and standalone Functions are not linked; backend credentials stay in the BFF",
         ],
         hasSharedWorkspace: fs.existsSync(path.join(projectRoot, "shared", "package.json")),
         hasConnectors: Object.keys(config.connectors || {}).length > 0,

package/src/core/project/mcp-config.ts

@@ -0,0 +1,84 @@
+/**
+ * Project-scoped MCP launcher version management.
+ *
+ * `.mcp.json` intentionally resolves `swallowkit@latest` so that projects created
+ * with older releases still get the current stable tools. A prerelease project can
+ * be newer than `latest`; in that case the launcher is pinned to the project
+ * version until a stable release that understands project-aware delegation catches up.
+ */
+
+import { spawnSync } from "child_process";
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+import { compareSemver, isPrerelease, parseSemver } from "../../utils/semver";
+
+export const MCP_CONFIG_PATH = ".mcp.json";
+export const MCP_VERSION_ENV = "SWALLOWKIT_MCP_VERSION";
+export const MCP_LATEST = "latest";
+
+export interface McpPinDecision {
+  version: string;
+  reason: string;
+}
+
+/**
+ * Decide the SWALLOWKIT_MCP_VERSION value for a project that uses `projectVersion`.
+ * Uses `latest` unless the project version is newer than the published `latest`.
+ * When the registry could not be reached, prereleases are pinned conservatively.
+ */
+export function resolveMcpPinVersion(projectVersion: string, publishedLatest: string | null): McpPinDecision {
+  if (!parseSemver(projectVersion)) {
+    return { version: MCP_LATEST, reason: `Project version ${projectVersion} is not a valid semantic version.` };
+  }
+  if (publishedLatest && parseSemver(publishedLatest)) {
+    const comparison = compareSemver(projectVersion, publishedLatest)!;
+    return comparison > 0
+      ? { version: projectVersion, reason: `Project version ${projectVersion} is newer than published latest ${publishedLatest}.` }
+      : { version: MCP_LATEST, reason: `Published latest ${publishedLatest} is the same as or newer than project version ${projectVersion}.` };
+  }
+  return isPrerelease(projectVersion)
+    ? { version: projectVersion, reason: `Published latest is unknown; prerelease ${projectVersion} is pinned so MCP matches the project.` }
+    : { version: MCP_LATEST, reason: "Published latest is unknown; stable projects keep latest." };
+}
+
+export function lookupPublishedLatestVersion(packageName: string, timeoutMs = 15000): string | null {
+  // Run outside the project so its devEngines/packageManager policy does not reject npm.
+  const result = spawnSync("npm", ["view", `${packageName}@latest`, "version"], {
+    cwd: os.tmpdir(),
+    encoding: "utf8",
+    timeout: timeoutMs,
+    shell: process.platform === "win32",
+    stdio: ["ignore", "pipe", "ignore"],
+  });
+  if (result.error || result.status !== 0) return null;
+  const version = String(result.stdout).trim().split(/\s+/).pop() ?? "";
+  return parseSemver(version) ? version : null;
+}
+
+export function readMcpConfigVersion(projectDir: string): string | null {
+  const configPath = path.join(projectDir, MCP_CONFIG_PATH);
+  if (!fs.existsSync(configPath)) return null;
+  try {
+    const config = JSON.parse(fs.readFileSync(configPath, "utf8"));
+    const value = config?.mcpServers?.swallowkit?.env?.[MCP_VERSION_ENV];
+    return typeof value === "string" ? value : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Update only the SwallowKit MCP version in .mcp.json, preserving all other content. */
+export function writeMcpConfigVersion(projectDir: string, version: string): void {
+  const configPath = path.join(projectDir, MCP_CONFIG_PATH);
+  if (!fs.existsSync(configPath)) {
+    throw new Error(`${MCP_CONFIG_PATH} was not found. Run this command from a SwallowKit project root.`);
+  }
+  const config = JSON.parse(fs.readFileSync(configPath, "utf8"));
+  const server = config?.mcpServers?.swallowkit;
+  if (!server || typeof server !== "object") {
+    throw new Error(`${MCP_CONFIG_PATH} does not define mcpServers.swallowkit.`);
+  }
+  server.env = { ...(server.env ?? {}), [MCP_VERSION_ENV]: version };
+  fs.writeFileSync(configPath, `${JSON.stringify(config, null, 2)}\n`);
+}