swallowkit 1.1.2 → 2.0.0-alpha.10

package/src/cli/commands/init.ts

@@ -1,8 +1,9 @@
-import * as fs from "fs";
+import * as fs from "fs";
 import * as path from "path";
 import { spawn, execSync } from "child_process";
 import prompts from "prompts";
-import { BackendLanguage } from "../../types";
+import { BackendLanguage, FrontendFramework } from "../../types";
+import { buildReactReadme, buildReactSwaConfig, createReactBffProject, createReactProject, buildReactGitHubSwaWorkflow, buildReactAzureSwaPipeline } from "../../core/project/react-project";
 import {
   type PackageManager,
   detectFromUserAgent,
@@ -24,11 +25,14 @@ import {
   buildCSharpCodegenToolManifestSource,
   buildPythonCodegenRequirementsSource,
 } from "../../core/scaffold/native-schema-generator";
-import { getProjectLocalUvPaths } from "../../utils/python-uv";
+import { DEFAULT_AZURE_PYTHON_VERSION } from "../../utils/python-uv";
+import { buildHomePage } from "../../core/project/home-page";
+import { MCP_LATEST, McpPinDecision, lookupPublishedLatestVersion, resolveMcpPinVersion } from "../../core/project/mcp-config";
 
 interface InitOptions {
   name: string;
   template: string;
+  frontend?: FrontendFramework;
   nextVersion?: string;
   cicd?: CiCdProvider;
   backendLanguage?: BackendLanguage;
@@ -142,7 +146,7 @@ function getFunctionsRuntimeConfig(backendLanguage: BackendLanguage): { name: st
     return { name: "dotnet-isolated", version: "10.0" };
   }
   if (backendLanguage === "python") {
-    return { name: "python", version: "3.11" };
+    return { name: "python", version: DEFAULT_AZURE_PYTHON_VERSION };
   }
   return { name: "node", version: "22" };
 }
@@ -257,6 +261,9 @@ const VALID_VNET: VNetOption[] = ['none', 'outbound'];
 const VALID_SWA_PLAN: StaticWebAppPlan[] = ['free', 'standard'];
 
 function validateInitFlags(options: InitOptions): void {
+  if (options.frontend && !["nextjs", "react"].includes(options.frontend)) {
+    throw new Error("Invalid --frontend: expected nextjs or react");
+  }
   if (options.packageManager && !['npm', 'pnpm'].includes(options.packageManager)) {
     throw new Error('Invalid --package-manager: expected npm or pnpm');
   }
@@ -322,17 +329,28 @@ export async function initCommand(options: InitOptions) {
       }
     }
 
+    // Preserve existing non-interactive invocations while offering a frontend choice in the wizard.
+    const frontend: FrontendFramework = options.frontend ?? (interactive
+      ? (await prompts({
+          type: "select", name: "frontend", message: "Frontend framework:",
+          choices: [{ title: "Next.js (App Router)", value: "nextjs" }, { title: "React (Vite SPA + SWA managed Functions BFF)", value: "react" }],
+          initial: 0,
+        })).frontend || "nextjs"
+      : "nextjs");
+    options = { ...options, frontend };
+
     // Use flag values if provided, otherwise prompt interactively
     const cicdProvider: CiCdProvider = options.cicd || await promptCiCd();
     const backendLanguage: BackendLanguage = options.backendLanguage || await promptBackendLanguage();
 
     const azureConfig = await promptAzureConfig(options);
 
-    // Create Next.js project with create-next-app
-    await createNextJsProject(options.name, pm);
-
-    // Upgrade Next.js to specified version (or latest) to avoid cached old versions
-    await upgradeNextJs(projectDir, options.nextVersion || 'latest', pm);
+    if (frontend === "react") {
+      createReactProject(projectDir, options.name, pm);
+    } else {
+      await createNextJsProject(options.name, pm);
+      await upgradeNextJs(projectDir, options.nextVersion || 'latest', pm);
+    }
 
     // Add SwallowKit specific files
     await addSwallowKitFiles(projectDir, options, cicdProvider, azureConfig, pm, backendLanguage);
@@ -342,9 +360,9 @@ export async function initCommand(options: InitOptions) {
     
     // Create CI/CD files based on choice
     if (cicdProvider === 'github') {
-      await createGitHubActionsWorkflows(projectDir, azureConfig, pm, backendLanguage);
+      await createGitHubActionsWorkflows(projectDir, azureConfig, pm, backendLanguage, frontend);
     } else if (cicdProvider === 'azure') {
-      await createAzurePipelines(projectDir, pm, backendLanguage);
+      await createAzurePipelines(projectDir, pm, backendLanguage, frontend);
     }
 
     await syncProjectManifest(projectDir);
@@ -651,9 +669,13 @@ export function parseIgnoredBuilds(output: string): string[] {
 }
 
 export function injectSwallowKitNextConfig(nextConfigContent: string, projectName: string): string {
-  return nextConfigContent.replace(
+  const compatibleConfig = nextConfigContent.replace(/(\b(?:cacheComponents|partialPrefetching)\s*:\s*)true\b/g, '$1false');
+  const cacheComponentsSetting = /\bcacheComponents\s*:/.test(compatibleConfig)
+    ? ''
+    : '  cacheComponents: false,\n';
+  return compatibleConfig.replace(
     /(const\s+nextConfig[:\s]*(?::\s*NextConfig\s*)?=\s*\{)(\s*\/\*[^*]*\*\/)?/,
-    `$1\n  output: 'standalone',\n  agentRules: false, // SwallowKit owns the canonical root AGENTS.md contract\n  transpilePackages: ['@${projectName}/shared'],\n  serverExternalPackages: ['applicationinsights', 'diagnostic-channel-publishers'],$2`
+    `$1\n  output: 'standalone',\n${cacheComponentsSetting}  agentRules: false, // SwallowKit owns the canonical root AGENTS.md contract\n  transpilePackages: ['@${projectName}/shared'],\n  serverExternalPackages: ['applicationinsights', 'diagnostic-channel-publishers'],$2`
   );
 }
 
@@ -691,7 +713,7 @@ export function buildCSharpFunctionsProjectSource(): string {
     <None Remove="generated\\**\\bin\\**;generated\\**\\obj\\**" />
   </ItemGroup>
   <ItemGroup>
-    <PackageReference Include="Microsoft.Azure.Cosmos" Version="3.47.0" />
+    <PackageReference Include="Microsoft.Azure.Cosmos" Version="3.63.2" />
     <PackageReference Include="Newtonsoft.Json" Version="13.0.3" />
     <PackageReference Include="Azure.Identity" Version="1.17.0" />
     <PackageReference Include="Microsoft.Azure.Functions.Worker" Version="2.52.0" />
@@ -704,8 +726,11 @@ export function buildCSharpFunctionsProjectSource(): string {
 `;
 }
 
-export function buildSwallowKitConfigSource(backendLanguage: BackendLanguage): string {
+export function buildSwallowKitConfigSource(backendLanguage: BackendLanguage, frontend: FrontendFramework = "nextjs"): string {
   return `module.exports = {
+  frontend: {
+    framework: '${frontend}',
+  },
   backend: {
     language: '${backendLanguage}',
   },
@@ -723,10 +748,10 @@ export function buildSwallowKitConfigSource(backendLanguage: BackendLanguage): s
 export function buildGeneratedProjectDependencies(
   projectName: string,
   pm: PackageManager = 'pnpm',
+  frontend: FrontendFramework = "nextjs",
 ): Record<string, string> {
   return {
-    '@azure/cosmos': '^4.0.0',
-    'applicationinsights': '^3.3.0',
+    ...(frontend === "nextjs" ? { '@azure/cosmos': '^4.0.0', 'applicationinsights': '^3.3.0' } : {}),
     'zod': '^4.0.0',
     [`@${projectName}/shared`]: pm === 'pnpm' ? 'workspace:*' : 'file:shared',
   };
@@ -755,14 +780,30 @@ function getSwallowKitPackageMetadata(): { name: string; version: string } {
   };
 }
 
-export function buildGeneratedProjectDevDependencies(): Record<string, string> {
+export function buildGeneratedProjectDevDependencies(frontend: FrontendFramework = "nextjs"): Record<string, string> {
   const { name, version } = getSwallowKitPackageMetadata();
   return {
     [name]: version,
+    ...(frontend === "nextjs" ? { "@tailwindcss/postcss": "^4.0.0" } : {}),
   };
 }
 
-export function buildSwallowKitMcpProjectConfigSource(pm: PackageManager = 'pnpm'): string {
+export function ensureNextTailwindPostcssConfig(projectDir: string): void {
+  if (["postcss.config.mjs", "postcss.config.js", "postcss.config.cjs", "postcss.config.json"]
+    .some(file => fs.existsSync(path.join(projectDir, file)))) {
+    return;
+  }
+
+  // New create-next-app templates can configure Tailwind for Turbopack only.
+  fs.writeFileSync(path.join(projectDir, "postcss.config.mjs"), `export default {
+  plugins: {
+    "@tailwindcss/postcss": {},
+  },
+};
+`);
+}
+
+export function buildSwallowKitMcpProjectConfigSource(pm: PackageManager = 'pnpm', mcpVersion: string = MCP_LATEST): string {
   const { name } = getSwallowKitPackageMetadata();
   return JSON.stringify(
     {
@@ -774,7 +815,7 @@ export function buildSwallowKitMcpProjectConfigSource(pm: PackageManager = 'pnpm
             : ["--yes", "--package", `${name}@\${SWALLOWKIT_MCP_VERSION}`, "swallowkit-mcp"],
           cwd: ".",
           env: {
-            SWALLOWKIT_MCP_VERSION: "latest",
+            SWALLOWKIT_MCP_VERSION: mcpVersion,
           },
         },
       },
@@ -784,6 +825,15 @@ export function buildSwallowKitMcpProjectConfigSource(pm: PackageManager = 'pnpm
   );
 }
 
+/** latest by default; pinned to this CLI version only when it is newer than published latest. */
+export function selectInitialMcpVersion(
+  lookupLatest: (packageName: string) => string | null = lookupPublishedLatestVersion
+): McpPinDecision {
+  const { name, version } = getSwallowKitPackageMetadata();
+  if (version === MCP_LATEST) return { version: MCP_LATEST, reason: "SwallowKit package metadata is unavailable." };
+  return resolveMcpPinVersion(version, lookupLatest(name));
+}
+
 async function addSwallowKitFiles(
   projectDir: string,
   options: InitOptions,
@@ -795,6 +845,7 @@ async function addSwallowKitFiles(
   console.log('📦 Adding SwallowKit files...\n');
   
   const projectName = options.name;
+  const frontend = options.frontend ?? "nextjs";
 
   // 1. Update package.json to add runtime dependencies for generated projects
   const packageJsonPath = path.join(projectDir, 'package.json');
@@ -803,17 +854,21 @@ async function addSwallowKitFiles(
   // Root BFF/auth code imports Zod directly; declare it as well as the shared package.
   packageJson.dependencies = {
     ...packageJson.dependencies,
-    ...buildGeneratedProjectDependencies(projectName, pm),
+    ...buildGeneratedProjectDependencies(projectName, pm, frontend),
   };
   packageJson.devDependencies = {
     ...packageJson.devDependencies,
-    ...buildGeneratedProjectDevDependencies(),
+    ...buildGeneratedProjectDevDependencies(frontend),
   };
 
   packageJson.scripts = {
     ...packageJson.scripts,
-    'build': getBuildScript(pm),
-    'start': 'next start',
+    'build': getBuildScript(pm, frontend),
+    'start': frontend === "react" ? "vite preview" : 'next start',
+    ...(frontend === "react" ? {
+      typecheck: `tsc --noEmit && ${getCommands(pm).exec} tsc --noEmit -p bff`,
+      "bff:start": `${getCommands(pm).runFilter("bff")} start`,
+    } : {}),
     'functions:start': getFunctionsStartScript(pm, backendLanguage),
   };
 
@@ -827,7 +882,7 @@ async function addSwallowKitFiles(
   delete packageJson.packageManager;
 
   // Keep package.json workspaces for npm-based CI/CD even when local development uses pnpm.
-  const workspacePackages = usesNodeFunctionsProject(backendLanguage) ? ['shared', 'functions'] : ['shared'];
+  const workspacePackages = [...(usesNodeFunctionsProject(backendLanguage) ? ['shared', 'functions'] : ['shared']), ...(frontend === "react" ? ["bff"] : [])];
   const wsConfig = getWorkspaceConfig(pm, workspacePackages);
   packageJson.workspaces = workspacePackages;
 
@@ -837,9 +892,11 @@ async function addSwallowKitFiles(
   
   fs.writeFileSync(packageJsonPath, JSON.stringify(packageJson, null, 2));
 
+  if (frontend === "nextjs") ensureNextTailwindPostcssConfig(projectDir);
+
   // Create pnpm-workspace.yaml for local pnpm development when needed.
   if (wsConfig.type === 'file') {
-    fs.writeFileSync(path.join(projectDir, wsConfig.filename), wsConfig.content);
+    fs.writeFileSync(path.join(projectDir, wsConfig.filename), wsConfig.content + (frontend === "react" ? "  esbuild: true\n" : ""));
   }
 
   // Don't install yet — wait until all workspace packages (shared, functions) are created
@@ -878,12 +935,13 @@ async function addSwallowKitFiles(
   }
 
   // 3. Create SwallowKit config
-  const swallowkitConfig = buildSwallowKitConfigSource(backendLanguage);
+  const swallowkitConfig = buildSwallowKitConfigSource(backendLanguage, frontend);
   fs.writeFileSync(path.join(projectDir, 'swallowkit.config.js'), swallowkitConfig);
 
   // 4. Create shared workspace package for Zod models (Single Source of Truth)
   await createSharedPackage(projectDir, projectName);
 
+  if (frontend === "nextjs") {
   // Create lib directory for Next.js-specific utilities
   const libDir = path.join(projectDir, 'lib');
 
@@ -1003,6 +1061,7 @@ export const api = {
 };
 `;
   fs.writeFileSync(path.join(apiLibDir, 'backend.ts'), backendUtilContent);
+  }
 
   // 5. Create components directory
   const componentsDir = path.join(projectDir, 'components');
@@ -1091,7 +1150,7 @@ export async function register() {
   }
 }
 `;
-  fs.writeFileSync(path.join(projectDir, 'instrumentation.ts'), instrumentationContent);
+  if (frontend === "nextjs") fs.writeFileSync(path.join(projectDir, 'instrumentation.ts'), instrumentationContent);
 
   // 8. Create .env.local for local development
   const envLocalContent = [
@@ -1124,17 +1183,19 @@ export async function register() {
   };
   fs.writeFileSync(
     path.join(projectDir, 'staticwebapp.config.json'),
-    JSON.stringify(swaConfig, null, 2)
+    JSON.stringify(frontend === "react" ? buildReactSwaConfig() : swaConfig, null, 2)
   );
 
   // 14. Create Azure Functions project
   await createAzureFunctionsProject(projectDir, pm, backendLanguage);
 
   // 15. Create BFF API route to call Azure Functions
-  await createBffApiRoute(projectDir);
-
-  // 16. Create home page
-  await createHomePage(projectDir, pm);
+  if (frontend === "react") {
+    createReactBffProject(projectDir, projectName, pm);
+  } else {
+    await createBffApiRoute(projectDir);
+    await createHomePage(projectDir, pm);
+  }
 
   // 17. Install all workspace dependencies (root + shared + functions)
   console.log('📦 Installing workspace dependencies...\n');
@@ -1143,13 +1204,17 @@ export async function register() {
   console.log('✅ Project structure created\n');
 
   // 18. Create README.md
-  createReadme(projectDir, projectName, cicdChoice, azureConfig, pm, backendLanguage);
+  if (frontend === "react") {
+    fs.writeFileSync(path.join(projectDir, "README.md"), buildReactReadme(projectName, pm, backendLanguage));
+  } else {
+    createReadme(projectDir, projectName, cicdChoice, azureConfig, pm, backendLanguage);
+  }
 
   // 19. Create AI agent instruction files (AGENTS.md, CLAUDE.md, .github/copilot-instructions.md, etc.)
-  createAiAgentFiles(projectDir, projectName, backendLanguage, pm);
+  createAiAgentFiles(projectDir, projectName, backendLanguage, pm, frontend);
 }
 
-async function createSharedPackage(projectDir: string, projectName: string) {
+export async function createSharedPackage(projectDir: string, projectName: string) {
   console.log('📦 Creating shared workspace package for Zod models...\n');
 
   const sharedDir = path.join(projectDir, 'shared');
@@ -1189,7 +1254,7 @@ async function createSharedPackage(projectDir: string, projectName: string) {
   // shared/index.ts (empty re-export file, scaffold will add entries)
   fs.writeFileSync(
     path.join(sharedDir, 'index.ts'),
-    `// Shared Zod models — auto-managed by SwallowKit scaffold command\n// Do not edit the export list below manually\n`
+    `// Shared Zod models. SwallowKit create-model/scaffold append missing model exports.\n// You may add exports manually; existing exports and comments are preserved. No managed markers.\n`
   );
 
   // shared/.gitignore
@@ -1201,7 +1266,7 @@ async function createSharedPackage(projectDir: string, projectName: string) {
   console.log('✅ Shared package created\n');
 }
 
-async function createAzureFunctionsProject(
+export async function createAzureFunctionsProject(
   projectDir: string,
   pm: PackageManager = 'pnpm',
   backendLanguage: BackendLanguage = 'typescript'
@@ -1456,7 +1521,6 @@ public sealed class GreetFunction
 }
 
 function createPythonFunctionsProject(projectDir: string, functionsDir: string): void {
-  fs.writeFileSync(path.join(projectDir, '.python-version'), '3.11\n');
   ensureProjectGitignoreEntry(projectDir, '.uv');
 
   fs.writeFileSync(path.join(functionsDir, 'requirements.txt'), `azure-functions>=1.20.0
@@ -1596,117 +1660,8 @@ export async function POST(request: NextRequest) {
 
 async function createHomePage(projectDir: string, pm: PackageManager = 'pnpm') {
   console.log('📦 Creating home page...\n');
-  
-  const pmCmd = getCommands(pm);
-  
-  const pageContent = `'use client'
-
-export const dynamic = 'force-dynamic';
-
-import { useState } from 'react';
-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">
-            Next.js on Azure Static Web Apps + Functions + Cosmos DB — Zod schema sharing
-          </p>
-        </header>
-
-        {/* Connection Test */}
-        <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 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 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>
-
-        {/* Scaffolded Models Menu */}
-        {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) => (
-                <a
-                  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>
-                </a>
-              ))}
-            </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">
-                ${pmCmd.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>
-  );
-}
-`;
-  
-  fs.writeFileSync(path.join(projectDir, 'app', 'page.tsx'), pageContent);
+  fs.writeFileSync(path.join(projectDir, 'app', 'page.tsx'), buildHomePage("nextjs", pm));
 
   console.log('✅ Home page created\n');
   
@@ -1760,9 +1715,8 @@ function createReadme(
   const backendScaffoldNote = backendLanguage === 'typescript'
     ? '- Azure Functions CRUD endpoints'
     : `- Azure Functions ${backendLanguageLabel} CRUD handlers\n- OpenAPI export + native-generated ${backendLanguageLabel} schema assets`;
-  const pythonUvPaths = getProjectLocalUvPaths(projectDir);
   const pythonLocalDevNote = backendLanguage === 'python'
-    ? `\n**Python local dev note**: SwallowKit uses \`uv\` for Python backends and keeps the managed Python runtime under \`${path.relative(projectDir, pythonUvPaths.pythonInstallDir)}\`. Local Azure Functions runs from \`functions/.venv\`, schema generation uses \`functions/.codegen-venv\`, and \`swallowkit dev\` bootstraps a project-local \`uv\` binary automatically when needed. Keep \`functions/requirements.txt\` and \`functions/requirements.codegen.txt\` as the dependency sources of truth.\n`
+    ? `\n**Python local dev note**: SwallowKit uses normal \`uv\` interpreter discovery and settings, including installed Python, \`.python-version\`, and \`UV_PYTHON\`. It does not pin local Python to the Azure deployment version (${DEFAULT_AZURE_PYTHON_VERSION}). Local Functions uses \`functions/.venv\` and schema generation uses \`functions/.codegen-venv\`. Existing environments are preserved; explicitly recreate them with uv when switching interpreters. A missing uv binary is bootstrapped under \`.uv/bin\` without changing PATH. Keep \`functions/requirements.txt\` and \`functions/requirements.codegen.txt\` as the dependency sources of truth.\n`
     : '';
 
   const readme = `# ${projectName}
@@ -1871,10 +1825,12 @@ ${pmCmd.exec} swallowkit provision --resource-group <rg-name>
 
 This creates:
 - Static Web App (\`swa-${projectName}\`)
-- Azure Functions (\`func-${projectName}\`)
-- Cosmos DB (\`cosmos-${projectName}\`)
+- Azure Functions (\`func-${projectName}-<suffix>\`)
+- Cosmos DB (\`cosmos-${projectName}-<suffix>\`)
 - Storage Account
 
+Cosmos DB and Function App names must be globally unique, so they include a short suffix derived from the resource group. When provisioning completes, the command prints the actual resource names and the CI/CD settings to use.
+
 You will be prompted to select Azure regions:
 1. **Primary location**: For Functions and Cosmos DB (default: Japan East)
 2. **Static Web App location**: Limited availability (default: East Asia)
@@ -1890,12 +1846,12 @@ ${cicdChoice === 'github' ? `#### GitHub Actions
 
 2. Get Function App publish profile:
    \`\`\`bash
-   az webapp deployment list-publishing-profiles --name func-${projectName} --resource-group <rg-name> --xml
+   az webapp deployment list-publishing-profiles --name <functions-app-name> --resource-group <rg-name> --xml
    \`\`\`
 
 3. Add secrets to GitHub repository:
    - \`AZURE_STATIC_WEB_APPS_API_TOKEN\`: SWA deployment token (from step 1)
-   - \`AZURE_FUNCTIONAPP_NAME\`: \`func-${projectName}\`
+   - \`AZURE_FUNCTIONAPP_NAME\`: Functions app name printed by \`swallowkit provision\` (\`func-${projectName}-<suffix>\`)
    - \`AZURE_FUNCTIONAPP_PUBLISH_PROFILE\`: Functions publish profile (from step 2)
 
 4. Push to \`main\` branch to trigger deployment (or use **Actions** → **Run workflow** for manual deployment)` : cicdChoice === 'azure' ? `#### Azure Pipelines
@@ -1917,8 +1873,10 @@ az staticwebapp deploy --name swa-${projectName} --resource-group <rg-name> --ap
 \`\`\`bash
 cd functions
 ${pmCmd.run} build
-func azure functionapp publish func-${projectName}
-\`\`\``}
+func azure functionapp publish <functions-app-name>
+\`\`\`
+
+Use the Functions app name printed by \`swallowkit provision\`.`}
 
 ## 🔧 Available Commands
 
@@ -1978,7 +1936,8 @@ function createAiAgentFiles(
   projectDir: string,
   projectName: string,
   backendLanguage: BackendLanguage,
-  pm: PackageManager
+  pm: PackageManager,
+  frontend: FrontendFramework = "nextjs"
 ) {
   console.log('🤖 Creating AI agent instruction files...\n');
   const runCmd = getCommands(pm).exec;
@@ -1987,17 +1946,23 @@ function createAiAgentFiles(
     projectName,
     backendLanguage,
     packageManager: pm,
+    frontend,
   });
   console.log('  ✅ AGENTS.md (canonical project contract)');
   console.log('  ✅ CLAUDE.md (Claude Code adapter)');
   console.log('  ✅ .github/copilot-instructions.md (GitHub Copilot adapter)');
   console.log('  ✅ .github/instructions/ (path-specific instructions)');
 
+  const mcpVersion = selectInitialMcpVersion();
   fs.writeFileSync(
     path.join(projectDir, '.mcp.json'),
-    buildSwallowKitMcpProjectConfigSource(pm)
+    buildSwallowKitMcpProjectConfigSource(pm, mcpVersion.version)
+  );
+  console.log(
+    mcpVersion.version === MCP_LATEST
+      ? '  ✅ .mcp.json (project-scoped MCP bootstrap, resolves latest)'
+      : `  ✅ .mcp.json (project-scoped MCP bootstrap, pinned to ${mcpVersion.version}: ${mcpVersion.reason} Run "${runCmd} swallowkit configure-mcp" to re-select later.)`
   );
-  console.log('  ✅ .mcp.json (project-scoped MCP bootstrap)');
 
   writeWorkflowDocs(projectDir, runCmd);
   console.log('  ✅ .swallowkit/workflows/ (agent-agnostic autonomous-loop runbooks)');
@@ -2088,6 +2053,14 @@ param cosmosDbMode string = '${azureConfig.cosmosDbMode}'
 @description('Enable VNet integration')
 param enableVNet bool = ${enableVNet}
 
+// Cosmos DB account and Function App names are globally unique across Azure.
+// A suffix derived from the resource group keeps names stable for redeployments
+// to the same resource group while avoiding collisions with other environments
+// and with names Azure still reserves after a previous resource group is deleted.
+var resourceSuffix = take(uniqueString(resourceGroup().id, projectName), 6)
+var cosmosAccountName = 'cosmos-\${take(toLower(projectName), 30)}-\${resourceSuffix}'
+var functionsAppName = 'func-\${take(projectName, 40)}-\${resourceSuffix}'
+
 // Shared Log Analytics Workspace (in Functions region for data residency)
 module logAnalytics 'modules/loganalytics.bicep' = {
   name: 'logAnalytics'
@@ -2141,7 +2114,7 @@ module vnet 'modules/vnet.bicep' = if (enableVNet) {
 module cosmosDbFreeTier 'modules/cosmosdb-freetier.bicep' = if (cosmosDbMode == 'freetier') {
   name: 'cosmosDb'
   params: {
-    accountName: 'cosmos-\${projectName}'
+    accountName: cosmosAccountName
     databaseName: '\${projectName}Database'
     location: location
     publicNetworkAccess: enableVNet ? 'Disabled' : 'Enabled'
@@ -2151,7 +2124,7 @@ module cosmosDbFreeTier 'modules/cosmosdb-freetier.bicep' = if (cosmosDbMode ==
 module cosmosDbServerless 'modules/cosmosdb-serverless.bicep' = if (cosmosDbMode == 'serverless') {
   name: 'cosmosDb'
   params: {
-    accountName: 'cosmos-\${projectName}'
+    accountName: cosmosAccountName
     databaseName: '\${projectName}Database'
     location: location
     publicNetworkAccess: enableVNet ? 'Disabled' : 'Enabled'
@@ -2175,7 +2148,7 @@ module cosmosPrivateEndpoint 'modules/private-endpoint-cosmos.bicep' = if (enabl
 module functionsFlex 'modules/functions-flex.bicep' = {
   name: 'functionsApp'
     params: {
-      name: 'func-\${projectName}'
+      name: functionsAppName
       location: location
       storageAccountName: 'stg\${uniqueString(resourceGroup().id, projectName)}'
       appInsightsConnectionString: appInsightsFunctions.outputs.connectionString
@@ -2911,7 +2884,7 @@ jobs:
 ${commonSetup}      - name: Setup Python
         uses: actions/setup-python@v5
         with:
-          python-version: '3.11'
+          python-version: '${DEFAULT_AZURE_PYTHON_VERSION}'
 
       - name: Install Functions dependencies
         run: |
@@ -3100,7 +3073,7 @@ variables:
 steps:
 ${commonSetup}  - task: UsePythonVersion@0
     inputs:
-      versionSpec: '3.11'
+      versionSpec: '${DEFAULT_AZURE_PYTHON_VERSION}'
     displayName: 'Install Python'
 
   - script: |
@@ -3133,7 +3106,8 @@ export function getSwaNodeVersionCommand(): string {
   return `node -e "const fs=require('fs');const p=JSON.parse(fs.readFileSync('package.json','utf8'));p.engines={...p.engines,node:'>=22.14.0 <23'};fs.writeFileSync('package.json',JSON.stringify(p,null,2)+String.fromCharCode(10));"`;
 }
 
-export function buildAzureSwaPipeline(pm: PackageManager, projectPm: PackageManager = pm): string {
+export function buildAzureSwaPipeline(pm: PackageManager, projectPm: PackageManager = pm, frontend: FrontendFramework = "nextjs"): string {
+  if (frontend === "react") return buildReactAzureSwaPipeline(projectPm);
   // SWA/Oryx also invokes npm internally; normalize only the disposable CI checkout.
   pm = 'npm';
   const pmCmd = getCommands(pm);
@@ -3321,7 +3295,8 @@ async function createGitHubActionsWorkflows(
   projectDir: string,
   azureConfig: AzureConfig,
   pm: PackageManager,
-  backendLanguage: BackendLanguage
+  backendLanguage: BackendLanguage,
+  frontend: FrontendFramework = "nextjs"
 ) {
   console.log('📦 Creating GitHub Actions workflows...\n');
   const workflowsDir = path.join(projectDir, '.github', 'workflows');
@@ -3329,7 +3304,7 @@ async function createGitHubActionsWorkflows(
 
   const actionsPm: PackageManager = pm;
 
-  const swaWorkflow = buildGitHubSwaWorkflow(actionsPm, pm);
+  const swaWorkflow = buildGitHubSwaWorkflow(actionsPm, pm, frontend);
   fs.writeFileSync(path.join(workflowsDir, 'deploy-swa.yml'), swaWorkflow);
 
   // deploy-functions.yml
@@ -3339,7 +3314,8 @@ async function createGitHubActionsWorkflows(
   console.log('✅ GitHub Actions workflows created\n');
 }
 
-export function buildGitHubSwaWorkflow(pm: PackageManager, projectPm: PackageManager = pm): string {
+export function buildGitHubSwaWorkflow(pm: PackageManager, projectPm: PackageManager = pm, frontend: FrontendFramework = "nextjs"): string {
+  if (frontend === "react") return buildReactGitHubSwaWorkflow(projectPm);
   // SWA/Oryx also invokes npm internally; normalize only the disposable CI checkout.
   pm = 'npm';
   const npmWorkspaceNormalizationStep = getGitHubNpmWorkspaceNormalizationStep(pm, projectPm);
@@ -3417,7 +3393,7 @@ ${npmWorkspaceNormalizationStep ? `\n${npmWorkspaceNormalizationStep}` : ''}
 `;
 }
 
-async function createAzurePipelines(projectDir: string, pm: PackageManager, backendLanguage: BackendLanguage) {
+async function createAzurePipelines(projectDir: string, pm: PackageManager, backendLanguage: BackendLanguage, frontend: FrontendFramework = "nextjs") {
   console.log('📦 Creating Azure Pipelines...\n');
 
   const pipelinesPm: PackageManager = pm;
@@ -3425,7 +3401,7 @@ async function createAzurePipelines(projectDir: string, pm: PackageManager, back
   fs.mkdirSync(pipelinesDir, { recursive: true });
 
   // swa.yml
-  const swaPipeline = buildAzureSwaPipeline(pipelinesPm, pm);
+  const swaPipeline = buildAzureSwaPipeline(pipelinesPm, pm, frontend);
   fs.writeFileSync(path.join(pipelinesDir, 'swa.yml'), swaPipeline);
   
   // functions.yml
@@ -3434,4 +3410,3 @@ async function createAzurePipelines(projectDir: string, pm: PackageManager, back
 
   console.log('✅ Azure Pipelines created\n');
 }
-