swallowkit 1.0.0-beta.23 → 1.0.0-beta.25

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 {
@@ -100,6 +111,36 @@ export function buildNextDevArgs(pm: string, port: string): string[] {
   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;
@@ -157,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',
     });
 
@@ -174,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> {
@@ -256,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
@@ -331,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);
 }
 
@@ -556,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 () => {
@@ -712,19 +798,7 @@ async function startDevEnvironment(options: DevOptions) {
             await runCommand(pm, ['install'], functionsDir, `${pm} install`);
           }
         } else if (backendLanguage === 'csharp') {
-          let cleanedArtifacts = false;
-          for (const artifactPath of getCSharpFunctionsBuildArtifactPaths(functionsDir)) {
-            if (!fs.existsSync(artifactPath)) {
-              continue;
-            }
-
-            fs.rmSync(artifactPath, { recursive: true, force: true });
-            cleanedArtifacts = true;
-          }
-
-          if (cleanedArtifacts) {
-            console.log('🧹 Cleaned previous C# Functions build artifacts before func start.');
-          }
+          console.log('ℹ️  C# Azure Functions can take longer on cold start while the worker builds.');
         } else {
           functionsEnv = await preparePythonFunctionsEnvironment(functionsDir);
         }
@@ -839,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.');
@@ -935,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');
@@ -953,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, {
@@ -987,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)');
@@ -1024,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

@@ -19,6 +19,7 @@ import {
   buildCSharpCodegenToolManifestSource,
   buildPythonCodegenRequirementsSource,
 } from "../../core/scaffold/native-schema-generator";
+import { getProjectLocalUvPaths } from "../../utils/python-uv";
 
 interface InitOptions {
   name: string;
@@ -1128,6 +1129,7 @@ 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
@@ -1175,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');
   
@@ -1414,8 +1432,9 @@ 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 \`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. Scaffold uses a separate \`functions/.codegen-venv\` for Python schema generation.\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}

package/src/core/scaffold/native-schema-generator.ts

@@ -4,33 +4,45 @@ import { spawn, spawnSync } from "child_process";
 import { BackendLanguage } from "../../types";
 import { ModelInfo, toKebabCase } from "./model-parser";
 import { generateOpenApiDocument } from "./openapi-generator";
+import {
+  buildProjectLocalUvEnv,
+  buildProjectLocalUvInstallerEnv,
+  buildUvPipInstallArgs,
+  buildUvVenvArgs,
+  getProjectLocalUvInstallerCommand,
+  getProjectLocalUvPaths,
+  getPythonProjectRoot,
+} from "../../utils/python-uv";
 
 export const NSWAG_CONSOLECORE_VERSION = "14.7.1";
 export const PYTHON_SCHEMA_CODEGEN_REQUIREMENT = "datamodel-code-generator>=0.44.0,<1.0.0";
 const PYTHON_OUTPUT_MODEL_TYPE = "pydantic_v2.BaseModel";
 
-type PythonLauncher = {
-  command: string;
-  argsPrefix: string[];
-};
-
 function getMachineAwareStdio(): "inherit" | "pipe" {
   return process.env.SWALLOWKIT_MACHINE_OUTPUT === "1" ? "pipe" : "inherit";
 }
 
-function canRun(command: string, args: string[], cwd: string): boolean {
+function canRun(command: string, args: string[], cwd: string, env?: NodeJS.ProcessEnv): boolean {
   const result = spawnSync(command, args, {
     cwd,
+    env,
     stdio: "ignore",
   });
 
   return !result.error && result.status === 0;
 }
 
-async function runCommand(command: string, args: string[], cwd: string, errorMessage: string): Promise<void> {
+async function runCommand(
+  command: string,
+  args: string[],
+  cwd: string,
+  errorMessage: string,
+  env?: NodeJS.ProcessEnv
+): Promise<void> {
   await new Promise<void>((resolve, reject) => {
     const child = spawn(command, args, {
       cwd,
+      env,
       stdio: getMachineAwareStdio(),
     });
 
@@ -611,46 +623,63 @@ function getVirtualEnvPythonPath(venvDir: string): string {
     : path.join(venvDir, "bin", "python");
 }
 
-function detectSystemPythonLauncher(functionsRoot: string): PythonLauncher {
-  const candidates: PythonLauncher[] = [
-    { command: "python", argsPrefix: [] },
-    { command: "py", argsPrefix: ["-3"] },
-    { command: "python3", argsPrefix: [] },
-  ];
+async function ensureProjectLocalUvCommand(projectRoot: string): Promise<{ command: string; env: NodeJS.ProcessEnv }> {
+  const uvEnv = buildProjectLocalUvEnv(process.env, projectRoot);
+  const { localUvExecutable } = getProjectLocalUvPaths(projectRoot);
 
-  for (const candidate of candidates) {
-    if (canRun(candidate.command, [...candidate.argsPrefix, "--version"], functionsRoot)) {
-      return candidate;
-    }
+  if (canRun("uv", ["--version"], projectRoot)) {
+    return { command: "uv", env: uvEnv };
+  }
+
+  if (fs.existsSync(localUvExecutable) && canRun(localUvExecutable, ["--version"], projectRoot)) {
+    return { command: localUvExecutable, env: uvEnv };
   }
 
-  throw new Error(
-    "Python 3.11+ is required to generate backend schema assets.\n" +
-      "Install Python and retry, or create functions/.codegen-venv manually."
+  const installer = getProjectLocalUvInstallerCommand();
+  await runCommand(
+    installer.command,
+    installer.args,
+    projectRoot,
+    "Failed to install project-local uv.",
+    buildProjectLocalUvInstallerEnv(process.env, projectRoot)
   );
+
+  if (!(fs.existsSync(localUvExecutable) && canRun(localUvExecutable, ["--version"], projectRoot))) {
+    throw new Error("Failed to install project-local uv.");
+  }
+
+  return { command: localUvExecutable, env: uvEnv };
 }
 
 async function ensurePythonCodegenEnvironment(functionsRoot: string): Promise<string> {
   const requirementsPath = ensurePythonCodegenProjectFiles(functionsRoot);
+  const projectRoot = getPythonProjectRoot(functionsRoot);
+  const { command: uvCommand, env: uvEnv } = await ensureProjectLocalUvCommand(projectRoot);
   const venvDir = path.join(functionsRoot, ".codegen-venv");
   const venvPython = getVirtualEnvPythonPath(venvDir);
 
-  if (!fs.existsSync(venvPython)) {
-    const launcher = detectSystemPythonLauncher(functionsRoot);
+  if (!canRun(venvPython, ["--version"], functionsRoot, uvEnv)) {
+    const venvArgs = buildUvVenvArgs(venvDir);
+    if (fs.existsSync(venvDir)) {
+      venvArgs.push("--clear");
+    }
+
     await runCommand(
-      launcher.command,
-      [...launcher.argsPrefix, "-m", "venv", venvDir],
+      uvCommand,
+      venvArgs,
       functionsRoot,
-      "Failed to create the Python schema code generation virtual environment."
+      "Failed to create the Python schema code generation virtual environment.",
+      uvEnv
     );
   }
 
-  if (!canRun(venvPython, ["-c", "import datamodel_code_generator"], functionsRoot)) {
+  if (!canRun(venvPython, ["-c", "import datamodel_code_generator"], functionsRoot, uvEnv)) {
     await runCommand(
-      venvPython,
-      ["-m", "pip", "install", "--disable-pip-version-check", "-r", requirementsPath],
+      uvCommand,
+      buildUvPipInstallArgs(venvPython, requirementsPath),
       functionsRoot,
-      "Failed to install Python schema generation dependencies."
+      "Failed to install Python schema generation dependencies.",
+      uvEnv
     );
   }
 

package/src/utils/python-uv.ts

@@ -0,0 +1,96 @@
+import * as path from "path";
+
+export const SWALLOWKIT_PYTHON_VERSION = "3.11";
+
+export interface ProjectLocalUvPaths {
+  stateDir: string;
+  cacheDir: string;
+  pythonInstallDir: string;
+  toolDir: string;
+  toolBinDir: string;
+  localUvInstallDir: string;
+  localUvExecutable: string;
+}
+
+export function getPythonProjectRoot(functionsDir: string): string {
+  return path.dirname(functionsDir);
+}
+
+export function getProjectLocalUvPaths(projectRoot: string): ProjectLocalUvPaths {
+  const stateDir = path.join(projectRoot, ".uv");
+  const localUvInstallDir = path.join(stateDir, "bin");
+
+  return {
+    stateDir,
+    cacheDir: path.join(stateDir, "cache"),
+    pythonInstallDir: path.join(stateDir, "python"),
+    toolDir: path.join(stateDir, "tools"),
+    toolBinDir: path.join(stateDir, "tools", "bin"),
+    localUvInstallDir,
+    localUvExecutable: process.platform === "win32"
+      ? path.join(localUvInstallDir, "uv.exe")
+      : path.join(localUvInstallDir, "uv"),
+  };
+}
+
+export function buildProjectLocalUvEnv(
+  baseEnv: NodeJS.ProcessEnv,
+  projectRoot: string
+): NodeJS.ProcessEnv {
+  const uvPaths = getProjectLocalUvPaths(projectRoot);
+  const env: NodeJS.ProcessEnv = {
+    ...baseEnv,
+    UV_CACHE_DIR: uvPaths.cacheDir,
+    UV_PYTHON_INSTALL_DIR: uvPaths.pythonInstallDir,
+    UV_TOOL_DIR: uvPaths.toolDir,
+    UV_TOOL_BIN_DIR: uvPaths.toolBinDir,
+    UV_PYTHON_PREFERENCE: "only-managed",
+  };
+
+  if (process.platform === "win32") {
+    env.UV_PYTHON_NO_REGISTRY = "true";
+  }
+
+  return env;
+}
+
+export function buildProjectLocalUvInstallerEnv(
+  baseEnv: NodeJS.ProcessEnv,
+  projectRoot: string
+): NodeJS.ProcessEnv {
+  const uvPaths = getProjectLocalUvPaths(projectRoot);
+
+  return {
+    ...buildProjectLocalUvEnv(baseEnv, projectRoot),
+    UV_UNMANAGED_INSTALL: uvPaths.localUvInstallDir,
+    UV_NO_MODIFY_PATH: "1",
+  };
+}
+
+export function getProjectLocalUvInstallerCommand(): { command: string; args: string[] } {
+  if (process.platform === "win32") {
+    return {
+      command: "powershell",
+      args: [
+        "-NoProfile",
+        "-ExecutionPolicy",
+        "Bypass",
+        "-Command",
+        "$ProgressPreference = 'SilentlyContinue'; irm https://astral.sh/uv/install.ps1 | iex",
+      ],
+    };
+  }
+
+  return {
+    command: "sh",
+    args: ["-c", "curl -LsSf https://astral.sh/uv/install.sh | sh"],
+  };
+}
+
+export function buildUvVenvArgs(venvDir: string, pythonVersion = SWALLOWKIT_PYTHON_VERSION): string[] {
+  return ["venv", venvDir, "--python", pythonVersion];
+}
+
+export function buildUvPipInstallArgs(pythonExecutable: string, requirementsPath: string): string[] {
+  return ["pip", "install", "--python", pythonExecutable, "-r", requirementsPath];
+}