swallowkit 1.0.0-beta.22 → 1.0.0-beta.24

package/src/cli/commands/dev.ts

@@ -1,5 +1,7 @@
 import { Command } from 'commander';
 import { spawn, ChildProcess } from 'child_process';
+import * as http from 'http';
+import * as https from 'https';
 import * as path from 'path';
 import * as fs from 'fs';
 import * as os from 'os';
@@ -10,6 +12,15 @@ import { ModelInfo } from '../../core/scaffold/model-parser';
 import { applyDevSeedEnvironment, getContainerNameForModel, loadProjectModels } from './dev-seeds';
 import { BackendLanguage } from '../../types';
 import { detectFromProject, getCommands } from '../../utils/package-manager';
+import {
+  buildProjectLocalUvEnv,
+  buildProjectLocalUvInstallerEnv,
+  buildUvPipInstallArgs,
+  buildUvVenvArgs,
+  getProjectLocalUvInstallerCommand,
+  getProjectLocalUvPaths,
+  getPythonProjectRoot,
+} from '../../utils/python-uv';
 import { ConnectorMockServer } from '../../core/mock/connector-mock-server';
 
 export interface DevOptions {
@@ -27,6 +38,15 @@ type ParsedDevActionOptions = DevOptions & {
   functions?: boolean;
 };
 
+interface FunctionsCoreToolsCommand {
+  command: string;
+  argsPrefix: string[];
+  label: string;
+}
+
+const MINIMUM_CSHARP_CORE_TOOLS_VERSION = '4.6.0';
+const NPM_CORE_TOOLS_PACKAGE = 'azure-functions-core-tools@4';
+
 function normalizeParsedDevOptions(options: ParsedDevActionOptions): DevOptions {
   return {
     ...options,
@@ -38,11 +58,89 @@ export function buildFunctionsStartArgs(functionsPort: string): string[] {
   return ['start', '--port', functionsPort];
 }
 
+export function parseCoreToolsVersion(output: string): string | null {
+  const match = output.match(/\d+\.\d+\.\d+/);
+  return match ? match[0] : null;
+}
+
+export function compareVersionNumbers(left: string, right: string): number {
+  const leftParts = left.split('.').map((value) => Number.parseInt(value, 10));
+  const rightParts = right.split('.').map((value) => Number.parseInt(value, 10));
+  const length = Math.max(leftParts.length, rightParts.length);
+
+  for (let index = 0; index < length; index += 1) {
+    const leftPart = leftParts[index] ?? 0;
+    const rightPart = rightParts[index] ?? 0;
+
+    if (leftPart !== rightPart) {
+      return leftPart - rightPart;
+    }
+  }
+
+  return 0;
+}
+
+export function buildFunctionsCoreToolsCommand(
+  backendLanguage: BackendLanguage,
+  installedVersion: string | null
+): FunctionsCoreToolsCommand {
+  if (
+    backendLanguage === 'csharp' &&
+    (!installedVersion || compareVersionNumbers(installedVersion, MINIMUM_CSHARP_CORE_TOOLS_VERSION) < 0)
+  ) {
+    const reason = installedVersion
+      ? `installed func ${installedVersion} is too old for C# isolated`
+      : 'func is not installed';
+
+    return {
+      command: 'npm',
+      argsPrefix: ['exec', '--yes', NPM_CORE_TOOLS_PACKAGE, '--'],
+      label: `npm exec ${NPM_CORE_TOOLS_PACKAGE} (${reason})`,
+    };
+  }
+
+  return {
+    command: 'func',
+    argsPrefix: [],
+    label: installedVersion ? `func ${installedVersion}` : 'func',
+  };
+}
+
 export function buildNextDevArgs(pm: string, port: string): string[] {
   const baseArgs = ['next', 'dev', '--port', port, '--webpack'];
   return pm === 'pnpm' ? ['exec', ...baseArgs] : baseArgs;
 }
 
+export function buildFunctionsBaseUrl(host: string | undefined, functionsPort: string): string {
+  return `http://${host || 'localhost'}:${functionsPort}`;
+}
+
+export function getFunctionsReadinessTimeoutMs(backendLanguage: BackendLanguage): number {
+  return backendLanguage === 'csharp' ? 90_000 : 30_000;
+}
+
+export async function waitForHttpServerReady(
+  url: string,
+  timeoutMs = 30_000,
+  intervalMs = 500
+): Promise<boolean> {
+  const deadline = Date.now() + timeoutMs;
+
+  while (Date.now() <= deadline) {
+    if (await probeHttpServer(url)) {
+      return true;
+    }
+
+    if (Date.now() + intervalMs > deadline) {
+      break;
+    }
+
+    await new Promise((resolve) => setTimeout(resolve, intervalMs));
+  }
+
+  return probeHttpServer(url);
+}
+
 export function getPythonVirtualEnvPaths(functionsDir: string): {
   venvDir: string;
   binDir: string;
@@ -59,6 +157,13 @@ export function getPythonVirtualEnvPaths(functionsDir: string): {
   return { venvDir, binDir, pythonExecutable };
 }
 
+export function getCSharpFunctionsBuildArtifactPaths(functionsDir: string): string[] {
+  return [
+    path.join(functionsDir, 'bin'),
+    path.join(functionsDir, 'obj'),
+  ];
+}
+
 export function buildPythonFunctionsEnv(baseEnv: NodeJS.ProcessEnv, functionsDir: string): NodeJS.ProcessEnv {
   const { venvDir, binDir, pythonExecutable } = getPythonVirtualEnvPaths(functionsDir);
   const pathKey = getPathEnvKey(baseEnv);
@@ -93,10 +198,20 @@ async function checkCoreTools(): Promise<boolean> {
   return checkCommand('func', ['--version']);
 }
 
-async function checkCommand(command: string, args: string[] = ['--version']): Promise<boolean> {
+async function checkCommand(
+  command: string,
+  args: string[] = ['--version'],
+  options?: {
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+    shell?: boolean;
+  }
+): Promise<boolean> {
   return new Promise((resolve) => {
     const checkProcess = spawn(command, args, {
-      shell: true,
+      cwd: options?.cwd,
+      env: options?.env ?? process.env,
+      shell: options?.shell ?? true,
       stdio: 'pipe',
     });
 
@@ -110,26 +225,34 @@ async function checkCommand(command: string, args: string[] = ['--version']): Pr
   });
 }
 
-async function resolvePythonBootstrapCommand(): Promise<{ command: string; argsPrefix: string[]; label: string }> {
-  const candidates = process.platform === 'win32'
-    ? [
-        { command: 'py', argsPrefix: ['-3.11'], label: 'py -3.11' },
-        { command: 'python', argsPrefix: [], label: 'python' },
-      ]
-    : [
-        { command: 'python3', argsPrefix: [], label: 'python3' },
-        { command: 'python', argsPrefix: [], label: 'python' },
-      ];
-
-  for (const candidate of candidates) {
-    if (await checkCommand(candidate.command, [...candidate.argsPrefix, '--version'])) {
-      return candidate;
-    }
+async function resolveProjectLocalUvCommand(projectRoot: string): Promise<{ command: string; env: NodeJS.ProcessEnv }> {
+  const uvEnv = buildProjectLocalUvEnv(process.env, projectRoot);
+  const { localUvExecutable } = getProjectLocalUvPaths(projectRoot);
+
+  if (await checkCommand('uv', ['--version'], { shell: false })) {
+    return { command: 'uv', env: uvEnv };
+  }
+
+  if (fs.existsSync(localUvExecutable) && await checkCommand(localUvExecutable, ['--version'], { shell: false })) {
+    return { command: localUvExecutable, env: uvEnv };
   }
 
-  throw new Error(
-    'Python 3.11 was not found. Install Python 3.11 and make sure `python`, `python3`, or `py -3.11` is available.'
+  console.log('📦 Installing project-local uv...');
+  const installer = getProjectLocalUvInstallerCommand();
+  await runCommand(
+    installer.command,
+    installer.args,
+    projectRoot,
+    'uv installation',
+    buildProjectLocalUvInstallerEnv(process.env, projectRoot),
+    false
   );
+
+  if (!(fs.existsSync(localUvExecutable) && await checkCommand(localUvExecutable, ['--version'], { shell: false }))) {
+    throw new Error('Failed to install project-local uv.');
+  }
+
+  return { command: localUvExecutable, env: uvEnv };
 }
 
 async function getCommandPath(command: string): Promise<string | null> {
@@ -143,6 +266,18 @@ async function getCommandPath(command: string): Promise<string | null> {
   return firstLine || null;
 }
 
+async function resolveInstalledCoreToolsVersion(): Promise<string | null> {
+  if (!(await checkCoreTools())) {
+    return null;
+  }
+
+  try {
+    return parseCoreToolsVersion(await captureCommandOutput('func', ['--version']));
+  } catch {
+    return null;
+  }
+}
+
 async function captureCommandOutput(
   command: string,
   args: string[],
@@ -180,6 +315,41 @@ async function captureCommandOutput(
   });
 }
 
+async function probeHttpServer(url: string): Promise<boolean> {
+  return new Promise((resolve) => {
+    const target = new URL(url);
+    const requestFactory = target.protocol === 'https:' ? https.request : http.request;
+    let settled = false;
+    const finish = (value: boolean) => {
+      if (!settled) {
+        settled = true;
+        resolve(value);
+      }
+    };
+
+    const request = requestFactory(
+      {
+        hostname: target.hostname,
+        port: target.port,
+        path: target.pathname || '/',
+        method: 'GET',
+        timeout: 1000,
+      },
+      (response) => {
+        response.resume();
+        finish(true);
+      }
+    );
+
+    request.on('timeout', () => {
+      request.destroy();
+      finish(false);
+    });
+    request.on('error', () => finish(false));
+    request.end();
+  });
+}
+
 async function resolvePythonRuntimeDetails(
   functionsDir: string,
   env: NodeJS.ProcessEnv
@@ -255,47 +425,36 @@ async function bridgePythonCoreToolsForWindowsArm64(
 }
 
 async function preparePythonFunctionsEnvironment(functionsDir: string): Promise<NodeJS.ProcessEnv> {
-  const { pythonExecutable } = getPythonVirtualEnvPaths(functionsDir);
-  const hasUv = await checkCommand('uv', ['--version']);
-
-  if (!fs.existsSync(pythonExecutable)) {
-    if (hasUv) {
-      console.log('📦 Creating Python virtual environment with uv...');
-      await runCommand('uv', ['venv', '.venv', '--python', '3.11'], functionsDir, 'python virtual environment setup');
-    } else {
-      const bootstrap = await resolvePythonBootstrapCommand();
-      console.log(`📦 Creating Python virtual environment with ${bootstrap.label}...`);
-      await runCommand(
-        bootstrap.command,
-        [...bootstrap.argsPrefix, '-m', 'venv', '.venv'],
-        functionsDir,
-        'python virtual environment setup'
-      );
-    }
-  }
+  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,
+  });
 
-  const pythonEnv = buildPythonFunctionsEnv(process.env, functionsDir);
-  console.log(`📦 Installing Python Azure Functions dependencies${hasUv ? ' with uv' : ''}...`);
+  if (!hasUsableVirtualEnv) {
+    const venvArgs = buildUvVenvArgs('.venv');
+    if (fs.existsSync(venvDir)) {
+      venvArgs.push('--clear');
+    }
 
-  if (hasUv) {
-    await runCommand(
-      'uv',
-      ['pip', 'install', '--python', pythonExecutable, '-r', 'requirements.txt'],
-      functionsDir,
-      'python dependency installation',
-      pythonEnv
-    );
-  } else {
-    await runCommand('python', ['-m', 'pip', 'install', '--upgrade', 'pip'], functionsDir, 'python pip upgrade', pythonEnv);
-    await runCommand(
-      'python',
-      ['-m', 'pip', 'install', '-r', 'requirements.txt'],
-      functionsDir,
-      'python dependency installation',
-      pythonEnv
-    );
+    console.log('📦 Creating Python virtual environment with uv...');
+    await runCommand(uvCommand, venvArgs, functionsDir, 'python virtual environment setup', uvEnv, false);
   }
 
+  console.log('📦 Installing Python Azure Functions dependencies with uv...');
+  await runCommand(
+    uvCommand,
+    buildUvPipInstallArgs(pythonExecutable, 'requirements.txt'),
+    functionsDir,
+    'python dependency installation',
+    uvEnv,
+    false
+  );
+
+  const pythonEnv = buildPythonFunctionsEnv(uvEnv, functionsDir);
   return bridgePythonCoreToolsForWindowsArm64(functionsDir, pythonEnv);
 }
 
@@ -338,7 +497,7 @@ export function buildDevCommand(
     .option('--host <host>', 'Host name', 'localhost')
     .option('--open', 'Open browser automatically', false)
     .option('--verbose', 'Show verbose logs', false)
-    .option('--no-functions', 'Skip Azure Functions startup', false)
+    .option('--no-functions', 'Skip Azure Functions startup')
     .option('--seed-env <environment>', 'Replace Cosmos DB Emulator data from dev-seeds/<environment> before startup')
     .option('--mock-connectors', 'Start mock server for connector models (serves Zod-generated data)', false)
     .action(async (options: ParsedDevActionOptions) => {
@@ -480,6 +639,9 @@ async function startDevEnvironment(options: DevOptions) {
   let mockServer: ConnectorMockServer | null = null;
   let envLocalPath = '';
   let envLocalDefaultUrl = ''; // default Functions URL to restore on shutdown
+  const functionsBaseUrl = buildFunctionsBaseUrl(options.host, functionsPort);
+  let functionsReadinessPromise: Promise<boolean> | null = null;
+  let functionsReady = !!options.noFunctions;
 
   // Cleanup processes on Ctrl+C
   process.on('SIGINT', async () => {
@@ -532,11 +694,14 @@ async function startDevEnvironment(options: DevOptions) {
     const functionsDir = path.join(process.cwd(), 'functions');
     const hasFunctions = fs.existsSync(functionsDir) && hasFunctionsProject(functionsDir, backendLanguage);
 
+    let functionsCoreToolsCommand: FunctionsCoreToolsCommand | null = null;
+    let installedCoreToolsVersion: string | null = null;
+
     if (hasFunctions && !options.noFunctions) {
-      // Check if Azure Functions Core Tools is installed
-      const coreToolsInstalled = await checkCoreTools();
-      
-      if (!coreToolsInstalled) {
+      installedCoreToolsVersion = await resolveInstalledCoreToolsVersion();
+      functionsCoreToolsCommand = buildFunctionsCoreToolsCommand(backendLanguage, installedCoreToolsVersion);
+
+      if (functionsCoreToolsCommand.command === 'func' && !installedCoreToolsVersion) {
         console.log('');
         console.log('⚠️  Azure Functions Core Tools not found.');
         console.log('');
@@ -585,6 +750,8 @@ async function startDevEnvironment(options: DevOptions) {
           // Skip Azure Functions startup
           options.noFunctions = true;
         }
+      } else if (functionsCoreToolsCommand.command !== 'func') {
+        console.log(`ℹ️  Using ${functionsCoreToolsCommand.label}.`);
       }
       
       if (!options.noFunctions) {
@@ -631,8 +798,7 @@ async function startDevEnvironment(options: DevOptions) {
             await runCommand(pm, ['install'], functionsDir, `${pm} install`);
           }
         } else if (backendLanguage === 'csharp') {
-          console.log('📦 Building C# Azure Functions project...');
-          await runCommand('dotnet', ['build'], functionsDir, 'dotnet build');
+          console.log('ℹ️  C# Azure Functions can take longer on cold start while the worker builds.');
         } else {
           functionsEnv = await preparePythonFunctionsEnvironment(functionsDir);
         }
@@ -685,7 +851,8 @@ async function startDevEnvironment(options: DevOptions) {
       }
 
       // Azure Functions を起動
-      const funcProcess = spawn('func', buildFunctionsStartArgs(functionsPort), {
+      const functionsCommand = functionsCoreToolsCommand ?? buildFunctionsCoreToolsCommand(backendLanguage, installedCoreToolsVersion);
+      const funcProcess = spawn(functionsCommand.command, [...functionsCommand.argsPrefix, ...buildFunctionsStartArgs(functionsPort)], {
         cwd: functionsDir,
         shell: true,
         stdio: 'pipe', // Always pipe to capture output
@@ -746,7 +913,11 @@ async function startDevEnvironment(options: DevOptions) {
         }
       });
 
-      console.log(`✅ Azure Functions started (port: ${functionsPort})`);
+      console.log(`⏳ Waiting for Azure Functions to accept requests at ${functionsBaseUrl}...`);
+      functionsReadinessPromise = waitForHttpServerReady(
+        functionsBaseUrl,
+        getFunctionsReadinessTimeoutMs(backendLanguage)
+      );
     } else if (!hasFunctions) {
       console.log('');
       console.log('ℹ️  functions/ directory not found. Starting Next.js only.');
@@ -842,8 +1013,8 @@ async function startDevEnvironment(options: DevOptions) {
     // When --mock-connectors is active, bffTargetPort = mock port (7072); otherwise = Functions port (7071).
     // Next.js may load .env.local values that override spawn env vars, so we must keep them in sync.
     envLocalPath = path.join(process.cwd(), '.env.local');
-    envLocalDefaultUrl = `http://${options.host || 'localhost'}:${functionsPort}`;
-    const bffTargetUrl = `http://${options.host || 'localhost'}:${bffTargetPort}`;
+    envLocalDefaultUrl = functionsBaseUrl;
+    const bffTargetUrl = buildFunctionsBaseUrl(options.host, bffTargetPort);
     try {
       if (fs.existsSync(envLocalPath)) {
         const envContent = fs.readFileSync(envLocalPath, 'utf-8');
@@ -860,8 +1031,8 @@ async function startDevEnvironment(options: DevOptions) {
 
     const nextEnv: NodeJS.ProcessEnv = {
       ...process.env,
-      BACKEND_FUNCTIONS_BASE_URL: `http://${options.host || 'localhost'}:${bffTargetPort}`,
-      FUNCTIONS_BASE_URL: `http://${options.host || 'localhost'}:${bffTargetPort}`,
+      BACKEND_FUNCTIONS_BASE_URL: bffTargetUrl,
+      FUNCTIONS_BASE_URL: bffTargetUrl,
     };
 
     const nextProcess = spawn(pm === 'pnpm' ? 'pnpm' : 'npx', nextArgs, {
@@ -894,19 +1065,31 @@ async function startDevEnvironment(options: DevOptions) {
       process.exit(code || 0);
     });
 
+    if (functionsReadinessPromise) {
+      functionsReady = await functionsReadinessPromise;
+      console.log('');
+      if (functionsReady) {
+        console.log(`✅ Azure Functions ready (port: ${functionsPort})`);
+      } else {
+        console.log(`⚠️  Azure Functions is still starting: ${functionsBaseUrl}`);
+      }
+    }
+
     console.log('');
     console.log('✅ SwallowKit development environment is running!');
     console.log('');
     console.log(`📱 Next.js: http://${options.host || 'localhost'}:${port}`);
     if (hasFunctions && !options.noFunctions) {
-      console.log(`⚡ Azure Functions: http://${options.host || 'localhost'}:${functionsPort}`);
+      console.log(`${functionsReady ? '⚡ Azure Functions' : '⏳ Azure Functions (starting)'}: ${functionsBaseUrl}`);
     }
     if (mockServer) {
-      console.log(`🔌 Mock Proxy: http://${options.host || 'localhost'}:${bffTargetPort} (BFF → here)`);
+      console.log(`🔌 Mock Proxy: ${bffTargetUrl} (BFF → here)`);
     }
     console.log('');
-    if (hasFunctions && !options.noFunctions) {
+    if (hasFunctions && !options.noFunctions && functionsReady) {
       console.log('💡 Azure Functions and Next.js BFF are connected');
+    } else if (hasFunctions && !options.noFunctions) {
+      console.log('💡 Azure Functions is still warming up; BFF routes can fail until the backend responds.');
     }
     if (mockServer) {
       console.log('💡 Connector models served from mock server (Zod-generated data)');
@@ -931,12 +1114,13 @@ async function runCommand(
   args: string[],
   cwd: string,
   label: string,
-  env?: NodeJS.ProcessEnv
+  env?: NodeJS.ProcessEnv,
+  shell = true
 ): Promise<void> {
   await new Promise<void>((resolve, reject) => {
     const child = spawn(command, args, {
       cwd,
-      shell: true,
+      shell,
       stdio: 'inherit',
       env,
     });

package/src/cli/commands/init.ts

@@ -15,6 +15,11 @@ import {
   getFunctionsStartScript,
 } from "../../utils/package-manager";
 import { syncProjectManifest } from "../../core/project/manifest";
+import {
+  buildCSharpCodegenToolManifestSource,
+  buildPythonCodegenRequirementsSource,
+} from "../../core/scaffold/native-schema-generator";
+import { getProjectLocalUvPaths } from "../../utils/python-uv";
 
 interface InitOptions {
   name: string;
@@ -473,13 +478,6 @@ async function addSwallowKitFiles(
     ...buildGeneratedProjectDependencies(projectName),
   };
 
-  if (backendLanguage !== "typescript") {
-    packageJson.devDependencies = {
-      ...packageJson.devDependencies,
-      '@openapitools/openapi-generator-cli': '^2.21.0',
-    };
-  }
-  
   packageJson.scripts = {
     ...packageJson.scripts,
     'build': getBuildScript(pm),
@@ -955,8 +953,9 @@ tsconfig.json
 !dist/**/*.js
 `);
   } else if (backendLanguage === 'python') {
-    gitignoreLines.unshift('.venv', '__pycache__', '.python_packages');
+    gitignoreLines.unshift('.venv', '.codegen-venv', '__pycache__', '.python_packages');
     fs.writeFileSync(path.join(functionsDir, '.funcignore'), `.venv
+.codegen-venv
 __pycache__
 .pytest_cache
 .mypy_cache
@@ -1083,6 +1082,11 @@ function createCSharpFunctionsProject(projectDir: string, functionsDir: string):
   const csprojName = `${projectPascal}.Functions.csproj`;
 
   fs.writeFileSync(path.join(functionsDir, csprojName), buildCSharpFunctionsProjectSource());
+  fs.mkdirSync(path.join(functionsDir, '.config'), { recursive: true });
+  fs.writeFileSync(
+    path.join(functionsDir, '.config', 'dotnet-tools.json'),
+    buildCSharpCodegenToolManifestSource()
+  );
 
   fs.writeFileSync(path.join(functionsDir, 'Program.cs'), buildCSharpFunctionsProgramSource());
 
@@ -1125,11 +1129,16 @@ 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
 azure-cosmos>=4.9.0
 azure-identity>=1.19.0
 `);
+  fs.writeFileSync(
+    path.join(functionsDir, 'requirements.codegen.txt'),
+    buildPythonCodegenRequirementsSource()
+  );
 
   const blueprintsDir = path.join(functionsDir, 'blueprints');
   fs.mkdirSync(blueprintsDir, { recursive: true });
@@ -1168,6 +1177,22 @@ app.register_blueprint(greet_bp)
 `);
 }
 
+function ensureProjectGitignoreEntry(projectDir: string, entry: string): void {
+  const gitignorePath = path.join(projectDir, '.gitignore');
+  if (!fs.existsSync(gitignorePath)) {
+    return;
+  }
+
+  const current = fs.readFileSync(gitignorePath, 'utf8');
+  const lines = current.split(/\r?\n/);
+  if (lines.includes(entry)) {
+    return;
+  }
+
+  const normalized = current.endsWith('\n') ? current : `${current}\n`;
+  fs.writeFileSync(gitignorePath, `${normalized}${entry}\n`);
+}
+
 async function createBffApiRoute(projectDir: string) {
   console.log('📦 Creating BFF API route...\n');
   
@@ -1398,17 +1423,18 @@ function createReadme(
   const backendLanguageLabel = getBackendLanguageLabel(backendLanguage);
   const schemaBridgeDescription = backendLanguage === 'typescript'
     ? 'Zod (shared between frontend and backend)'
-    : `Zod + OpenAPI bridge (Zod in shared/, generated ${backendLanguageLabel} schemas in functions/generated/)`;
+    : `Zod + OpenAPI export (Zod in shared/, native-generated ${backendLanguageLabel} schemas in functions/generated/)`;
   const functionsTree = backendLanguage === 'typescript'
     ? `│   └── src/\n│       └── greet.ts      # Sample function`
     : backendLanguage === 'csharp'
-      ? `│   ├── Crud/\n│   │   └── GreetFunction.cs\n│   └── generated/       # OpenAPI-derived C# models`
-      : `│   ├── blueprints/\n│   │   └── greet.py\n│   └── generated/       # OpenAPI-derived Python models`;
+      ? `│   ├── Crud/\n│   │   └── GreetFunction.cs\n│   └── generated/       # Native-generated C# schema assets`
+      : `│   ├── blueprints/\n│   │   └── greet.py\n│   └── generated/       # Native-generated Python schema assets`;
   const backendScaffoldNote = backendLanguage === 'typescript'
     ? '- Azure Functions CRUD endpoints'
-    : `- Azure Functions ${backendLanguageLabel} CRUD handlers\n- OpenAPI spec + generated ${backendLanguageLabel} schema assets`;
+    : `- 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 \`functions/.venv\` for local Azure Functions development. If \`uv\` is installed, \`swallowkit dev\` uses it to create/manage that virtual environment; otherwise it falls back to the standard \`venv\` + \`pip\` workflow. Keep \`functions/requirements.txt\` as the dependency source of truth for Azure Functions compatibility.\n`
+    ? `\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`
     : '';
 
   const readme = `# ${projectName}
@@ -1626,14 +1652,14 @@ function createAiAgentFiles(projectDir: string, projectName: string, backendLang
   const functionsStructureLine = backendLanguage === 'typescript'
     ? `│   └── src/               # HTTP trigger handlers with Cosmos DB bindings`
     : backendLanguage === 'csharp'
-      ? `│   ├── Crud/              # C# HTTP trigger handlers\n│   └── generated/         # OpenAPI-derived C# schema assets`
-      : `│   ├── blueprints/        # Python HTTP trigger handlers\n│   └── generated/         # OpenAPI-derived Python schema assets`;
+      ? `│   ├── Crud/              # C# HTTP trigger handlers\n│   └── generated/         # Native-generated C# schema assets`
+      : `│   ├── blueprints/        # Python HTTP trigger handlers\n│   └── generated/         # Native-generated Python schema assets`;
   const backendSchemaNote = backendLanguage === 'typescript'
     ? `- The shared package (\`@${projectName}/shared\`) is consumed by both Next.js and Azure Functions as a workspace dependency.`
-    : `- The frontend/BFF source of truth stays in \`shared/models/\` as Zod schemas.\n- \`swallowkit scaffold\` exports OpenAPI into \`functions/openapi/\` and generates ${backendLanguageLabel} schema assets into \`functions/generated/\` for backend use.`;
+    : `- The frontend/BFF source of truth stays in \`shared/models/\` as Zod schemas.\n- \`swallowkit scaffold\` exports OpenAPI into \`functions/openapi/\` and generates ${backendLanguageLabel} schema assets into \`functions/generated/\` with native ${backendLanguageLabel} tooling.`;
   const backendRulesNote = backendLanguage === 'typescript'
     ? `- All CRUD operations and business logic live in \`functions/src/\`.\n- Use Azure Functions Cosmos DB **input/output bindings** (\`extraInputs\`/\`extraOutputs\`) for reads and writes.\n- Use the Cosmos DB SDK client directly **only** for delete operations (bindings do not support delete).\n- Validate all data against Zod schemas before writing to Cosmos DB.\n- The backend auto-generates \`id\` (UUID), \`createdAt\`, and \`updatedAt\` — never trust client-sent values for these fields.`
-    : `- All business logic lives in \`functions/\` and the generated handlers perform real Cosmos DB CRUD.\n- Keep Zod schemas in \`shared/models/\` as the source of truth.\n- Regenerate backend contracts with \`swallowkit scaffold shared/models/<name>.ts\` whenever a schema changes.\n- Use the generated OpenAPI-derived models in \`functions/generated/\` to keep backend contracts aligned.\n- The backend should still own \`id\`, \`createdAt\`, and \`updatedAt\`.`;
+    : `- All business logic lives in \`functions/\` and the generated handlers perform real Cosmos DB CRUD.\n- Keep Zod schemas in \`shared/models/\` as the source of truth.\n- Regenerate backend contracts with \`swallowkit scaffold shared/models/<name>.ts\` whenever a schema changes.\n- Use the native-generated schema assets in \`functions/generated/\` to keep backend contracts aligned.\n- The backend should still own \`id\`, \`createdAt\`, and \`updatedAt\`.`;
 
   // ── 1. AGENTS.md (Codex / generic agents) ──────────────────────────
 
@@ -1748,7 +1774,7 @@ Key rules:
 
 - ${backendRulesNote}
 
-${backendLanguage === 'typescript' ? 'Azure Functions handler pattern:' : `Generated ${backendLanguageLabel} handlers live under \`functions/\`. Re-run \`swallowkit scaffold shared/models/<name>.ts\` after schema changes to keep generated CRUD handlers and \`functions/generated/\` in sync.`}
+${backendLanguage === 'typescript' ? 'Azure Functions handler pattern:' : `Generated ${backendLanguageLabel} handlers live under \`functions/\`. Re-run \`swallowkit scaffold shared/models/<name>.ts\` after schema changes to keep generated CRUD handlers and the native schema assets under \`functions/generated/\` in sync.`}
 
 ${backendLanguage === 'typescript' ? `\`\`\`typescript
 // functions/src/{model}.ts
@@ -2018,7 +2044,7 @@ Files in \`functions/\` contain all business logic and data access for this appl
 
 - Keep backend contracts aligned with \`shared/models/\` by rerunning \`swallowkit scaffold\` after schema changes.
 - For TypeScript backends, use Cosmos DB **input/output bindings** (\`extraInputs\`/\`extraOutputs\`) for reads and writes.
-- For C#/Python backends, consume the generated OpenAPI-derived assets in \`functions/generated/\`.
+- For C#/Python backends, consume the native-generated assets in \`functions/generated/\`.
 - Auto-generate \`id\` (UUID), \`createdAt\`, and \`updatedAt\` on the backend. Never trust client-sent values.
 - Container names are PascalCase + 's' (e.g., \`Todos\`). Partition key defaults to \`/id\` but can be customized per model.