swallowkit 2.0.0-alpha.2 → 2.0.0-alpha.3

package/src/__tests__/react-dev.test.ts

@@ -0,0 +1,72 @@
+import ts from "typescript";
+import {
+  buildReactDevConfigSource,
+  buildReactDevWatchIgnoredSource,
+} from "../utils/react-dev";
+import { buildReactDevArgs } from "../cli/commands/dev";
+
+describe("React dev watch boundaries", () => {
+  it.each(["C:\\repo\\", "C:\\repo", "/repo/"])(
+    "ignores backend artifacts without excluding frontend or shared sources under %s",
+    root => {
+      const ignored: string[] = new Function("root", `return ${buildReactDevWatchIgnoredSource("root")}`)(root);
+      const normalized = root.replace(/\\/g, "/").replace(/\/$/, "");
+      expect(ignored).toEqual([
+        `${normalized}/functions/**`,
+        `${normalized}/bff/**`,
+        `${normalized}/.uv/**`,
+        `${normalized}/.swallowkit/**`,
+        `${normalized}/shared/dist/**`,
+      ]);
+      expect(ignored.some(value => value.includes("/src/") || value.includes("/shared/models/"))).toBe(false);
+    }
+  );
+
+  function loadWrapper(config: object) {
+    const loadConfigFromFile = jest.fn(async () => ({
+      config,
+      dependencies: ["/repo/vite.config.mts", "/repo/vite-settings.ts"],
+    }));
+    const mergeConfig = jest.fn((base: object, overrides: object) => ({ base, overrides }));
+    const result = { exports: {} as { default: (env: object) => Promise<unknown> } };
+    const source = ts.transpileModule(buildReactDevConfigSource(), {
+      compilerOptions: { module: ts.ModuleKind.CommonJS, target: ts.ScriptTarget.ES2022 },
+    }).outputText;
+    new Function("require", "exports", source)(
+      () => ({ defineConfig: (value: unknown) => value, loadConfigFromFile, mergeConfig }),
+      result.exports
+    );
+    return { load: result.exports.default, loadConfigFromFile, mergeConfig };
+  }
+
+  it("loads the user's Vite config and merges rather than replacing their watch options", async () => {
+    const config = { plugins: ["user-plugin"], server: { watch: { ignored: ["**/custom/**"], usePolling: true } } };
+    const wrapper = loadWrapper(config);
+    const env = { command: "serve", mode: "development" };
+    await wrapper.load(env);
+    expect(wrapper.loadConfigFromFile).toHaveBeenCalledWith(env, undefined, process.cwd());
+    expect(wrapper.mergeConfig).toHaveBeenCalledWith(config, {
+      plugins: [expect.objectContaining({ name: "swallowkit-dev-watch-boundaries" })],
+      server: { watch: { ignored: expect.arrayContaining([expect.stringContaining("/functions/**")]) } },
+    });
+    const plugin = wrapper.mergeConfig.mock.calls[0][1] as {
+      plugins: Array<{ configResolved: (config: { configFileDependencies: string[] }) => void }>;
+    };
+    const resolved = { configFileDependencies: ["/repo/wrapper.mjs"] };
+    plugin.plugins[0].configResolved(resolved);
+    expect(resolved.configFileDependencies).toContain("/repo/vite.config.mts");
+  });
+
+  it("respects an explicitly disabled watcher", async () => {
+    const config = { server: { watch: null } };
+    const wrapper = loadWrapper(config);
+    await expect(wrapper.load({})).resolves.toBe(config);
+    expect(wrapper.mergeConfig).not.toHaveBeenCalled();
+  });
+
+  it("passes the override config to existing projects without editing their Vite config", () => {
+    expect(buildReactDevArgs("pnpm", "3100", "127.0.0.1", ".swallowkit/config.mjs")).toEqual([
+      "exec", "vite", "--port", "3100", "--host", "127.0.0.1", "--strictPort", "--config", ".swallowkit/config.mjs",
+    ]);
+  });
+});

package/src/__tests__/react.test.ts

@@ -14,6 +14,7 @@ import {
   createReactBffProject,
   buildReactSwaConfig,
 } from "../core/project/react-project";
+import { buildHomePage } from "../core/project/home-page";
 import {
   generateManagedFunctionConfig,
   generateReactBffHelper,
@@ -505,6 +506,24 @@ describe("React project integration", () => {
     ).toBe(false);
   });
 
+  it("generates the shared home page with the selected package manager and Tailwind defaults", () => {
+    createReactProject(project, "sample", "npm");
+    expect(fs.readFileSync(path.join(project, "src", "Home.tsx"), "utf8"))
+      .toBe(buildHomePage("react", "npm"));
+
+    const css = fs.readFileSync(path.join(project, "src", "style.css"), "utf8");
+    expect(css).toContain('@import "tailwindcss"');
+    expect(css).toContain("@media (prefers-color-scheme: dark)");
+    expect(css).toContain("--background: #ffffff");
+    expect(css).toContain("--background: #0a0a0a");
+    expect(css).toContain("--color-background: var(--background)");
+    expect(css).toContain("font-family: Arial, Helvetica, sans-serif");
+    expect(fs.readFileSync(path.join(project, "index.html"), "utf8"))
+      .toContain('class="h-full antialiased"');
+    expect(fs.readFileSync(path.join(project, "vite.config.mts"), "utf8"))
+      .toContain("plugins: [react(), tailwindcss()]");
+  });
+
   it("plans and applies BFF bindings, React pages and metadata through the common path", async () => {
     const plan = await planScaffoldOperation({ model: "todo" });
     expect(plan.requiresApproval).toBe(false);

package/src/cli/commands/dev.ts

@@ -19,15 +19,15 @@ import {
 import { BackendLanguage } from '../../types';
 import { detectFromProject, getCommands } from '../../utils/package-manager';
 import {
-  buildProjectLocalUvEnv,
   buildProjectLocalUvInstallerEnv,
   buildUvPipInstallArgs,
-  buildUvVenvArgs,
+  ensureUvVirtualEnvironment,
   getProjectLocalUvInstallerCommand,
   getProjectLocalUvPaths,
   getPythonProjectRoot,
 } from '../../utils/python-uv';
 import { ConnectorMockServer } from '../../core/mock/connector-mock-server';
+import { buildReactDevConfigSource } from '../../utils/react-dev';
 
 export interface DevOptions {
   port?: string;
@@ -65,8 +65,8 @@ function normalizeParsedDevOptions(options: ParsedDevActionOptions): DevOptions
   };
 }
 
-export function buildFunctionsStartArgs(functionsPort: string): string[] {
-  return ['start', '--port', functionsPort];
+export function buildFunctionsStartArgs(functionsPort: string, backendLanguage: BackendLanguage = 'typescript'): string[] {
+  return [...(backendLanguage === 'csharp' ? [] : ['start']), '--port', functionsPort];
 }
 
 export function parseCoreToolsVersion(output: string): string | null {
@@ -105,15 +105,15 @@ export function buildFunctionsCoreToolsCommand(
 
     return {
       command: 'npm',
-      argsPrefix: ['exec', '--yes', NPM_CORE_TOOLS_PACKAGE, '--'],
-      label: `npm exec ${NPM_CORE_TOOLS_PACKAGE} (${reason})`,
+      argsPrefix: ['exec', '--yes', '--package', NPM_CORE_TOOLS_PACKAGE, '--', 'dotnet', 'run', '--no-launch-profile', '--'],
+      label: `dotnet run with npm ${NPM_CORE_TOOLS_PACKAGE} (${reason})`,
     };
   }
 
   return {
-    command: 'func',
-    argsPrefix: [],
-    label: installedVersion ? `func ${installedVersion}` : 'func',
+    command: backendLanguage === 'csharp' ? 'dotnet' : 'func',
+    argsPrefix: backendLanguage === 'csharp' ? ['run', '--no-launch-profile', '--'] : [],
+    label: backendLanguage === 'csharp' ? 'dotnet run' : installedVersion ? `func ${installedVersion}` : 'func',
   };
 }
 
@@ -138,8 +138,8 @@ export function buildSwaStartArgs(host: string | undefined, nextPort: string, sw
   ];
 }
 
-export function buildReactDevArgs(pm: string, port: string, host = 'localhost'): string[] {
-  const args = ['vite', '--port', port, '--host', host, '--strictPort'];
+export function buildReactDevArgs(pm: string, port: string, host = 'localhost', configPath?: string): string[] {
+  const args = ['vite', '--port', port, '--host', host, '--strictPort', ...(configPath ? ['--config', configPath] : [])];
   return pm === 'pnpm' ? ['exec', ...args] : args;
 }
 
@@ -270,7 +270,7 @@ async function checkCommand(
 }
 
 async function resolveProjectLocalUvCommand(projectRoot: string): Promise<{ command: string; env: NodeJS.ProcessEnv }> {
-  const uvEnv = buildProjectLocalUvEnv(process.env, projectRoot);
+  const uvEnv = { ...process.env };
   const { localUvExecutable } = getProjectLocalUvPaths(projectRoot);
 
   if (await checkCommand('uv', ['--version'], { shell: false })) {
@@ -471,22 +471,8 @@ async function bridgePythonCoreToolsForWindowsArm64(
 async function preparePythonFunctionsEnvironment(functionsDir: string): Promise<NodeJS.ProcessEnv> {
   const projectRoot = getPythonProjectRoot(functionsDir);
   const { command: uvCommand, env: uvEnv } = await resolveProjectLocalUvCommand(projectRoot);
-  const { venvDir, pythonExecutable } = getPythonVirtualEnvPaths(functionsDir);
-  const hasUsableVirtualEnv = fs.existsSync(pythonExecutable) && await checkCommand(pythonExecutable, ['--version'], {
-    cwd: functionsDir,
-    env: uvEnv,
-    shell: false,
-  });
-
-  if (!hasUsableVirtualEnv) {
-    const venvArgs = buildUvVenvArgs('.venv');
-    if (fs.existsSync(venvDir)) {
-      venvArgs.push('--clear');
-    }
-
-    console.log('📦 Creating Python virtual environment with uv...');
-    await runCommand(uvCommand, venvArgs, functionsDir, 'python virtual environment setup', uvEnv, false);
-  }
+  const { venvDir } = getPythonVirtualEnvPaths(functionsDir);
+  const pythonExecutable = await ensureUvVirtualEnvironment(uvCommand, venvDir, functionsDir, uvEnv);
 
   console.log('📦 Installing Python Azure Functions dependencies with uv...');
   await runCommand(
@@ -538,7 +524,7 @@ export async function assertDevPortAvailable(port: number, host: string): Promis
 }
 
 function stopDevProcesses(processes: ChildProcess[]): void {
-  const active = processes.filter(child => child.pid && !child.killed);
+  const active = processes.filter(child => child.pid && !child.killed && child.exitCode === null && child.signalCode === null);
   if (process.platform === 'win32' && active.length) {
     // Windows shell termination alone leaves Vite, Core Tools, and SWA running.
     const ids = active.map(child => child.pid).join(',');
@@ -721,6 +707,14 @@ async function startDevEnvironment(options: DevOptions) {
   const functionsBaseUrl = buildFunctionsBaseUrl(options.host, functionsPort);
   let functionsReadinessPromise: Promise<boolean> | null = null;
   let functionsReady = !!options.noFunctions;
+  let reactDevConfigDir: string | undefined;
+  const cleanupReactDevConfig = () => {
+    if (reactDevConfigDir) {
+      fs.rmSync(reactDevConfigDir, { recursive: true, force: true });
+      reactDevConfigDir = undefined;
+    }
+  };
+  process.once('exit', cleanupReactDevConfig);
 
   // Cleanup processes on Ctrl+C
   process.on('SIGINT', async () => {
@@ -939,7 +933,7 @@ async function startDevEnvironment(options: DevOptions) {
 
       // Azure Functions を起動
       const functionsCommand = functionsCoreToolsCommand ?? buildFunctionsCoreToolsCommand(backendLanguage, installedCoreToolsVersion);
-      const funcProcess = spawn(functionsCommand.command, [...functionsCommand.argsPrefix, ...buildFunctionsStartArgs(functionsPort)], {
+      const funcProcess = spawn(functionsCommand.command, [...functionsCommand.argsPrefix, ...buildFunctionsStartArgs(functionsPort, backendLanguage)], {
         cwd: functionsDir,
         shell: true,
         stdio: 'pipe', // Always pipe to capture output
@@ -987,6 +981,8 @@ async function startDevEnvironment(options: DevOptions) {
         console.error('⚠️  Azure Functions startup error:', error.message);
         console.log('💡 Please ensure Azure Functions Core Tools is installed');
         console.log(`   ${pmCmd.addGlobal} azure-functions-core-tools@4`);
+        stopDevProcesses(processes);
+        process.exit(1);
       });
 
       funcProcess.on('close', (code) => {
@@ -997,6 +993,8 @@ async function startDevEnvironment(options: DevOptions) {
             console.log('   Reinstall a matching Core Tools v4 package (Windows users should prefer the official x64/x86 MSI for their machine).');
             console.log('   SwallowKit local Python dev uses functions/.venv and requirements.txt, but Core Tools still needs its own bundled Python worker.');
           }
+          stopDevProcesses(processes);
+          process.exit(code || 1);
         }
       });
 
@@ -1083,7 +1081,17 @@ async function startDevEnvironment(options: DevOptions) {
     }
 
     // 5. Start Next.js development server
-    const nextArgs = react ? buildReactDevArgs(pm, port, options.host) : buildNextDevArgs(pm, port);
+    let reactDevConfigPath: string | undefined;
+    if (react) {
+      const stateDir = path.join(process.cwd(), '.swallowkit');
+      fs.mkdirSync(stateDir, { recursive: true });
+      reactDevConfigDir = fs.mkdtempSync(path.join(stateDir, 'vite-dev-'));
+      reactDevConfigPath = path.join(reactDevConfigDir, 'config.mjs');
+      fs.writeFileSync(reactDevConfigPath, buildReactDevConfigSource());
+    }
+    const nextArgs = react
+      ? buildReactDevArgs(pm, port, options.host, reactDevConfigPath && path.relative(process.cwd(), reactDevConfigPath))
+      : buildNextDevArgs(pm, port);
     
     // Ensure .env.local points to bffTargetPort so Next.js reads the correct backend URL.
     // When --mock-connectors is active, bffTargetPort = mock port (7072); otherwise = Functions port (7071).
@@ -1141,6 +1149,7 @@ async function startDevEnvironment(options: DevOptions) {
 
     nextProcess.on('error', (error) => {
       console.error(`❌ ${frontendLabel} startup error:`, error.message);
+      stopDevProcesses(processes);
       process.exit(1);
     });
 

package/src/cli/commands/init.ts

@@ -25,7 +25,8 @@ 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";
 
 interface InitOptions {
   name: string;
@@ -144,7 +145,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" };
 }
@@ -344,7 +345,7 @@ export async function initCommand(options: InitOptions) {
     const azureConfig = await promptAzureConfig(options);
 
     if (frontend === "react") {
-      createReactProject(projectDir, options.name);
+      createReactProject(projectDir, options.name, pm);
     } else {
       await createNextJsProject(options.name, pm);
       await upgradeNextJs(projectDir, options.nextVersion || 'latest', pm);
@@ -711,7 +712,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" />
@@ -778,13 +779,29 @@ 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 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'): string {
   const { name } = getSwallowKitPackageMetadata();
   return JSON.stringify(
@@ -831,7 +848,7 @@ async function addSwallowKitFiles(
   };
   packageJson.devDependencies = {
     ...packageJson.devDependencies,
-    ...buildGeneratedProjectDevDependencies(),
+    ...buildGeneratedProjectDevDependencies(frontend),
   };
 
   packageJson.scripts = {
@@ -865,6 +882,8 @@ 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 + (frontend === "react" ? "  esbuild: true\n" : ""));
@@ -1492,7 +1511,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
@@ -1632,117 +1650,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');
   
@@ -1796,9 +1705,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}
@@ -2949,7 +2857,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: |
@@ -3138,7 +3046,7 @@ variables:
 steps:
 ${commonSetup}  - task: UsePythonVersion@0
     inputs:
-      versionSpec: '3.11'
+      versionSpec: '${DEFAULT_AZURE_PYTHON_VERSION}'
     displayName: 'Install Python'
 
   - script: |

package/src/core/project/agent-instructions.ts

@@ -71,6 +71,9 @@ function getBackendRules(backendLanguage: BackendLanguage): string {
     "- All backend business logic and data access live in `functions/`.",
     `- SwallowKit derives OpenAPI and native ${BACKEND_LANGUAGE_LABELS[backendLanguage]} schema assets from the Zod source of truth.`,
     "- Keep custom business logic in ai-authored locations identified by the current boundary contract.",
+    backendLanguage === "python"
+      ? "- Use uv with the user's interpreter/version settings. Local Python is not pinned to the Azure deployment runtime. Preserve functions/.venv and functions/.codegen-venv; do not clear them or weaken OS application-control policy to fix interpreter errors."
+      : "- Start the isolated Functions backend with dotnet run, not func start from the source directory, so the SDK loads extensions from the build output.",
   ].join("\n");
 }
 
@@ -91,7 +94,7 @@ function interpolateTemplate(template: string, context: AgentInstructionContext)
       ? "├── src/                    # React SPA (Vite + React Router)\n│   └── pages/              # generated/custom UI and route registrations\n├── bff/                    # SWA managed HTTP-only Functions\n│   ├── src/                # BFF handlers and request-local helpers\n│   └── {function}/         # function.json registrations"
       : "├── app/                    # Next.js App Router\n│   ├── api/                # BFF routes\n│   └── {model}/            # generated/custom UI",
     devGuidance: react
-      ? "Use http://localhost:4280 for the app. `swallowkit dev` runs Vite (3000), the managed BFF (7073), standalone Functions (7071), and SWA CLI (4280). SWA forwards /api only to the managed BFF, never directly to standalone Functions. `--no-functions` leaves the BFF running; `--no-swa` removes same-origin routing/auth emulation. BFF local settings belong in bff/local.settings.json. Build bundles BFF dependencies and copies staticwebapp.config.json into dist/. Deploy dist/ + bff/ together, and functions/ separately."
+      ? "Use http://localhost:4280 for the app. `swallowkit dev` runs Vite (3000), the managed BFF (7073), standalone Functions (7071), and SWA CLI (4280). SWA forwards /api only to the managed BFF, never directly to standalone Functions. `--no-functions` leaves the BFF running; `--no-swa` removes same-origin routing/auth emulation. BFF local settings belong in bff/local.settings.json. Build bundles BFF dependencies and copies staticwebapp.config.json into dist/. Deploy dist/ + bff/ together, and functions/ separately. Generated home, CRUD, and login pages share the Next.js presentation templates. Preserve their Tailwind styles and the light/dark defaults in src/style.css when editing them."
       : "Use http://localhost:3000 for the app, or the SWA emulator port (4280) when testing SWA authentication. `swallowkit dev` runs Next.js and standalone Functions (7071). The BFF remains Next.js API routes.",
     pm: context.packageManager,
     runCmd,

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}`;
+}