swallowkit 1.1.2 → 2.0.0-alpha.10

package/dist/cli/commands/init.js

@@ -48,7 +48,11 @@ exports.buildCSharpFunctionsProjectSource = buildCSharpFunctionsProjectSource;
 exports.buildSwallowKitConfigSource = buildSwallowKitConfigSource;
 exports.buildGeneratedProjectDependencies = buildGeneratedProjectDependencies;
 exports.buildGeneratedProjectDevDependencies = buildGeneratedProjectDevDependencies;
+exports.ensureNextTailwindPostcssConfig = ensureNextTailwindPostcssConfig;
 exports.buildSwallowKitMcpProjectConfigSource = buildSwallowKitMcpProjectConfigSource;
+exports.selectInitialMcpVersion = selectInitialMcpVersion;
+exports.createSharedPackage = createSharedPackage;
+exports.createAzureFunctionsProject = createAzureFunctionsProject;
 exports.buildTypeScriptFunctionsPackageJson = buildTypeScriptFunctionsPackageJson;
 exports.buildFunctionsHostKeyBicepExpression = buildFunctionsHostKeyBicepExpression;
 exports.buildStaticWebAppConfigBicepSource = buildStaticWebAppConfigBicepSource;
@@ -62,6 +66,7 @@ const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const child_process_1 = require("child_process");
 const prompts_1 = __importDefault(require("prompts"));
+const react_project_1 = require("../../core/project/react-project");
 const package_manager_1 = require("../../utils/package-manager");
 const manifest_1 = require("../../core/project/manifest");
 const workflows_1 = require("../../core/project/workflows");
@@ -69,6 +74,8 @@ const agent_instructions_1 = require("../../core/project/agent-instructions");
 const migration_generator_1 = require("../../core/operations/migration-generator");
 const native_schema_generator_1 = require("../../core/scaffold/native-schema-generator");
 const python_uv_1 = require("../../utils/python-uv");
+const home_page_1 = require("../../core/project/home-page");
+const mcp_config_1 = require("../../core/project/mcp-config");
 function getStaticWebAppSku(plan) {
     return plan === 'free' ? 'Free' : 'Standard';
 }
@@ -156,7 +163,7 @@ function getFunctionsRuntimeConfig(backendLanguage) {
         return { name: "dotnet-isolated", version: "10.0" };
     }
     if (backendLanguage === "python") {
-        return { name: "python", version: "3.11" };
+        return { name: "python", version: python_uv_1.DEFAULT_AZURE_PYTHON_VERSION };
     }
     return { name: "node", version: "22" };
 }
@@ -260,6 +267,9 @@ const VALID_COSMOS_DB_MODE = ['freetier', 'serverless'];
 const VALID_VNET = ['none', 'outbound'];
 const VALID_SWA_PLAN = ['free', 'standard'];
 function validateInitFlags(options) {
+    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');
     }
@@ -320,24 +330,36 @@ async function initCommand(options) {
                 process.exit(1);
             }
         }
+        // Preserve existing non-interactive invocations while offering a frontend choice in the wizard.
+        const frontend = options.frontend ?? (interactive
+            ? (await (0, prompts_1.default)({
+                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 = options.cicd || await promptCiCd();
         const 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") {
+            (0, react_project_1.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);
         // Create infrastructure files (Bicep)
         await createInfrastructure(projectDir, options.name, azureConfig, backendLanguage);
         // 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 (0, manifest_1.syncProjectManifest)(projectDir);
         // Initialize Git repository and create initial commit
@@ -588,7 +610,11 @@ function parseIgnoredBuilds(output) {
     return Array.from(new Set(list));
 }
 function injectSwallowKitNextConfig(nextConfigContent, projectName) {
-    return nextConfigContent.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`);
+    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${cacheComponentsSetting}  agentRules: false, // SwallowKit owns the canonical root AGENTS.md contract\n  transpilePackages: ['@${projectName}/shared'],\n  serverExternalPackages: ['applicationinsights', 'diagnostic-channel-publishers'],$2`);
 }
 function buildCSharpFunctionsProgramSource() {
     return `using Microsoft.Azure.Functions.Worker;
@@ -623,7 +649,7 @@ function buildCSharpFunctionsProjectSource() {
     <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" />
@@ -635,8 +661,11 @@ function buildCSharpFunctionsProjectSource() {
 </Project>
 `;
 }
-function buildSwallowKitConfigSource(backendLanguage) {
+function buildSwallowKitConfigSource(backendLanguage, frontend = "nextjs") {
     return `module.exports = {
+  frontend: {
+    framework: '${frontend}',
+  },
   backend: {
     language: '${backendLanguage}',
   },
@@ -650,10 +679,9 @@ function buildSwallowKitConfigSource(backendLanguage) {
 }
 `;
 }
-function buildGeneratedProjectDependencies(projectName, pm = 'pnpm') {
+function buildGeneratedProjectDependencies(projectName, pm = 'pnpm', frontend = "nextjs") {
     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',
     };
@@ -675,13 +703,27 @@ function getSwallowKitPackageMetadata() {
         version: "latest",
     };
 }
-function buildGeneratedProjectDevDependencies() {
+function buildGeneratedProjectDevDependencies(frontend = "nextjs") {
     const { name, version } = getSwallowKitPackageMetadata();
     return {
         [name]: version,
+        ...(frontend === "nextjs" ? { "@tailwindcss/postcss": "^4.0.0" } : {}),
     };
 }
-function buildSwallowKitMcpProjectConfigSource(pm = 'pnpm') {
+function ensureNextTailwindPostcssConfig(projectDir) {
+    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": {},
+  },
+};
+`);
+}
+function buildSwallowKitMcpProjectConfigSource(pm = 'pnpm', mcpVersion = mcp_config_1.MCP_LATEST) {
     const { name } = getSwallowKitPackageMetadata();
     return JSON.stringify({
         mcpServers: {
@@ -692,31 +734,43 @@ function buildSwallowKitMcpProjectConfigSource(pm = 'pnpm') {
                     : ["--yes", "--package", `${name}@\${SWALLOWKIT_MCP_VERSION}`, "swallowkit-mcp"],
                 cwd: ".",
                 env: {
-                    SWALLOWKIT_MCP_VERSION: "latest",
+                    SWALLOWKIT_MCP_VERSION: mcpVersion,
                 },
             },
         },
     }, null, 2);
 }
+/** latest by default; pinned to this CLI version only when it is newer than published latest. */
+function selectInitialMcpVersion(lookupLatest = mcp_config_1.lookupPublishedLatestVersion) {
+    const { name, version } = getSwallowKitPackageMetadata();
+    if (version === mcp_config_1.MCP_LATEST)
+        return { version: mcp_config_1.MCP_LATEST, reason: "SwallowKit package metadata is unavailable." };
+    return (0, mcp_config_1.resolveMcpPinVersion)(version, lookupLatest(name));
+}
 async function addSwallowKitFiles(projectDir, options, cicdChoice, azureConfig, pm, backendLanguage) {
     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');
     const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf-8'));
     // 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': (0, package_manager_1.getBuildScript)(pm),
-        'start': 'next start',
+        'build': (0, package_manager_1.getBuildScript)(pm, frontend),
+        'start': frontend === "react" ? "vite preview" : 'next start',
+        ...(frontend === "react" ? {
+            typecheck: `tsc --noEmit && ${(0, package_manager_1.getCommands)(pm).exec} tsc --noEmit -p bff`,
+            "bff:start": `${(0, package_manager_1.getCommands)(pm).runFilter("bff")} start`,
+        } : {}),
         'functions:start': (0, package_manager_1.getFunctionsStartScript)(pm, backendLanguage),
     };
     packageJson.engines = {
@@ -728,16 +782,18 @@ async function addSwallowKitFiles(projectDir, options, cicdChoice, azureConfig,
     };
     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 = (0, package_manager_1.getWorkspaceConfig)(pm, workspacePackages);
     packageJson.workspaces = workspacePackages;
     if (wsConfig.type !== 'file') {
         packageJson.workspaces = wsConfig.value;
     }
     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
     // 2. Update next.config to add standalone output
@@ -770,17 +826,18 @@ async function addSwallowKitFiles(projectDir, options, cicdChoice, azureConfig,
         fs.writeFileSync(tsconfigPath, JSON.stringify(tsconfig, null, 2));
     }
     // 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);
-    // Create lib directory for Next.js-specific utilities
-    const libDir = path.join(projectDir, 'lib');
-    // Create lib/api directory for backend utilities
-    const apiLibDir = path.join(libDir, 'api');
-    fs.mkdirSync(apiLibDir, { recursive: true });
-    // Create backend utility for calling Azure Functions
-    const backendUtilContent = `// Get Functions base URL at runtime (not at build time)
+    if (frontend === "nextjs") {
+        // Create lib directory for Next.js-specific utilities
+        const libDir = path.join(projectDir, 'lib');
+        // Create lib/api directory for backend utilities
+        const apiLibDir = path.join(libDir, 'api');
+        fs.mkdirSync(apiLibDir, { recursive: true });
+        // Create backend utility for calling Azure Functions
+        const backendUtilContent = `// Get Functions base URL at runtime (not at build time)
 function getFunctionsBaseUrl(): string {
   return process.env.BACKEND_FUNCTIONS_BASE_URL || process.env.FUNCTIONS_BASE_URL || 'http://localhost:7071';
 }
@@ -890,7 +947,8 @@ export const api = {
   },
 };
 `;
-    fs.writeFileSync(path.join(apiLibDir, 'backend.ts'), backendUtilContent);
+        fs.writeFileSync(path.join(apiLibDir, 'backend.ts'), backendUtilContent);
+    }
     // 5. Create components directory
     const componentsDir = path.join(projectDir, 'components');
     fs.mkdirSync(componentsDir, { recursive: true });
@@ -976,7 +1034,8 @@ 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 = [
         '# Azure Functions Backend URL (Local)',
@@ -1005,21 +1064,30 @@ export async function register() {
             ".json": "application/json"
         }
     };
-    fs.writeFileSync(path.join(projectDir, 'staticwebapp.config.json'), JSON.stringify(swaConfig, null, 2));
+    fs.writeFileSync(path.join(projectDir, 'staticwebapp.config.json'), JSON.stringify(frontend === "react" ? (0, react_project_1.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") {
+        (0, react_project_1.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');
     await installDependencies(projectDir, pm);
     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"), (0, react_project_1.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, projectName) {
     console.log('📦 Creating shared workspace package for Zod models...\n');
@@ -1049,7 +1117,7 @@ async function createSharedPackage(projectDir, projectName) {
     // shared/tsconfig.json
     fs.writeFileSync(path.join(sharedDir, 'tsconfig.json'), JSON.stringify(buildSharedTsConfig(), null, 2));
     // 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`);
+    fs.writeFileSync(path.join(sharedDir, 'index.ts'), `// 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
     fs.writeFileSync(path.join(sharedDir, '.gitignore'), `node_modules\ndist\n`);
     console.log('✅ Shared package created\n');
@@ -1287,7 +1355,6 @@ public sealed class GreetFunction
 `);
 }
 function createPythonFunctionsProject(projectDir, functionsDir) {
-    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
 azure-cosmos>=4.9.0
@@ -1408,114 +1475,7 @@ export async function POST(request: NextRequest) {
 }
 async function createHomePage(projectDir, pm = 'pnpm') {
     console.log('📦 Creating home page...\n');
-    const pmCmd = (0, package_manager_1.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'), (0, home_page_1.buildHomePage)("nextjs", pm));
     console.log('✅ Home page created\n');
     // Create initial scaffold-config.ts
     const scaffoldConfigDir = path.join(projectDir, 'lib');
@@ -1556,9 +1516,8 @@ function createReadme(projectDir, projectName, cicdChoice, azureConfig, pm, back
     const backendScaffoldNote = backendLanguage === 'typescript'
         ? '- Azure Functions CRUD endpoints'
         : `- Azure Functions ${backendLanguageLabel} CRUD handlers\n- OpenAPI export + native-generated ${backendLanguageLabel} schema assets`;
-    const pythonUvPaths = (0, python_uv_1.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 (${python_uv_1.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}
 
@@ -1666,10 +1625,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)
@@ -1685,12 +1646,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
@@ -1712,8 +1673,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
 
@@ -1767,20 +1730,24 @@ This project was generated by SwallowKit. If you encounter any issues or have su
     fs.writeFileSync(path.join(projectDir, 'README.md'), readme);
     console.log('✅ README.md created\n');
 }
-function createAiAgentFiles(projectDir, projectName, backendLanguage, pm) {
+function createAiAgentFiles(projectDir, projectName, backendLanguage, pm, frontend = "nextjs") {
     console.log('🤖 Creating AI agent instruction files...\n');
     const runCmd = (0, package_manager_1.getCommands)(pm).exec;
     (0, agent_instructions_1.writeAgentInstructionFiles)(projectDir, {
         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)');
-    fs.writeFileSync(path.join(projectDir, '.mcp.json'), buildSwallowKitMcpProjectConfigSource(pm));
-    console.log('  ✅ .mcp.json (project-scoped MCP bootstrap)');
+    const mcpVersion = selectInitialMcpVersion();
+    fs.writeFileSync(path.join(projectDir, '.mcp.json'), buildSwallowKitMcpProjectConfigSource(pm, mcpVersion.version));
+    console.log(mcpVersion.version === mcp_config_1.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.)`);
     (0, workflows_1.writeWorkflowDocs)(projectDir, runCmd);
     console.log('  ✅ .swallowkit/workflows/ (agent-agnostic autonomous-loop runbooks)');
     const skillPaths = (0, workflows_1.writeAgentSkills)(projectDir, runCmd);
@@ -1858,6 +1825,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'
@@ -1911,7 +1886,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'
@@ -1921,7 +1896,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'
@@ -1945,7 +1920,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
@@ -2662,7 +2637,7 @@ jobs:
 ${commonSetup}      - name: Setup Python
         uses: actions/setup-python@v5
         with:
-          python-version: '3.11'
+          python-version: '${python_uv_1.DEFAULT_AZURE_PYTHON_VERSION}'
 
       - name: Install Functions dependencies
         run: |
@@ -2847,7 +2822,7 @@ variables:
 steps:
 ${commonSetup}  - task: UsePythonVersion@0
     inputs:
-      versionSpec: '3.11'
+      versionSpec: '${python_uv_1.DEFAULT_AZURE_PYTHON_VERSION}'
     displayName: 'Install Python'
 
   - script: |
@@ -2878,7 +2853,9 @@ ${commonSetup}  - task: UsePythonVersion@0
 function getSwaNodeVersionCommand() {
     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));"`;
 }
-function buildAzureSwaPipeline(pm, projectPm = pm) {
+function buildAzureSwaPipeline(pm, projectPm = pm, frontend = "nextjs") {
+    if (frontend === "react")
+        return (0, react_project_1.buildReactAzureSwaPipeline)(projectPm);
     // SWA/Oryx also invokes npm internally; normalize only the disposable CI checkout.
     pm = 'npm';
     const pmCmd = (0, package_manager_1.getCommands)(pm);
@@ -3056,19 +3033,21 @@ function getGitHubNpmWorkspaceNormalizationStep(pm, projectPm) {
           npm install --package-lock-only --ignore-scripts
 `;
 }
-async function createGitHubActionsWorkflows(projectDir, azureConfig, pm, backendLanguage) {
+async function createGitHubActionsWorkflows(projectDir, azureConfig, pm, backendLanguage, frontend = "nextjs") {
     console.log('📦 Creating GitHub Actions workflows...\n');
     const workflowsDir = path.join(projectDir, '.github', 'workflows');
     fs.mkdirSync(workflowsDir, { recursive: true });
     const actionsPm = pm;
-    const swaWorkflow = buildGitHubSwaWorkflow(actionsPm, pm);
+    const swaWorkflow = buildGitHubSwaWorkflow(actionsPm, pm, frontend);
     fs.writeFileSync(path.join(workflowsDir, 'deploy-swa.yml'), swaWorkflow);
     // deploy-functions.yml
     const functionsWorkflow = getGitHubFunctionsWorkflow(actionsPm, backendLanguage, pm);
     fs.writeFileSync(path.join(workflowsDir, 'deploy-functions.yml'), functionsWorkflow);
     console.log('✅ GitHub Actions workflows created\n');
 }
-function buildGitHubSwaWorkflow(pm, projectPm = pm) {
+function buildGitHubSwaWorkflow(pm, projectPm = pm, frontend = "nextjs") {
+    if (frontend === "react")
+        return (0, react_project_1.buildReactGitHubSwaWorkflow)(projectPm);
     // SWA/Oryx also invokes npm internally; normalize only the disposable CI checkout.
     pm = 'npm';
     const npmWorkspaceNormalizationStep = getGitHubNpmWorkspaceNormalizationStep(pm, projectPm);
@@ -3144,13 +3123,13 @@ ${npmWorkspaceNormalizationStep ? `\n${npmWorkspaceNormalizationStep}` : ''}
           NEXT_TURBOPACK_EXPERIMENTAL_USE_SYSTEM_TLS_CERTS: '1'
 `;
 }
-async function createAzurePipelines(projectDir, pm, backendLanguage) {
+async function createAzurePipelines(projectDir, pm, backendLanguage, frontend = "nextjs") {
     console.log('📦 Creating Azure Pipelines...\n');
     const pipelinesPm = pm;
     const pipelinesDir = path.join(projectDir, 'pipelines');
     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
     const functionsPipeline = getAzureFunctionsPipeline(pipelinesPm, backendLanguage, pm);