swallowkit 1.1.2 → 2.0.0-alpha.10

package/src/utils/azure-cli.ts

@@ -0,0 +1,315 @@
+/**
+ * Azure CLI invocation that works without a shell on every platform.
+ *
+ * On Windows `az` is a batch wrapper (az.cmd). Node cannot spawn it with `shell: false`
+ * (ENOENT for "az", EINVAL for "az.cmd"), so the wrapper is resolved explicitly:
+ * the MSI layout runs its bundled Python exactly like az.cmd does, and other wrappers
+ * run through cmd.exe with every argument quoted.
+ */
+
+import { spawn, spawnSync, SpawnSyncOptions } from "child_process";
+import * as fs from "fs";
+import * as path from "path";
+
+export interface AzCliInvocation {
+  command: string;
+  prefixArgs: string[];
+  env?: NodeJS.ProcessEnv;
+  /** Batch wrapper that must be started through cmd.exe. */
+  batchScript?: string;
+  /** Resolved executable or wrapper, for diagnostics. */
+  source: string;
+}
+
+export interface AzCliResult {
+  status: number | null;
+  stdout: string;
+  stderr: string;
+  error?: Error;
+  signal: NodeJS.Signals | null;
+  elapsedMs: number;
+  failureKind?: "timeout" | "buffer" | "cancelled" | "spawn" | "signal" | "communication" | "exit";
+  errorCode?: string;
+  stdoutTruncated: boolean;
+  stderrTruncated: boolean;
+}
+
+export interface AzCliRunOptions {
+  timeout?: number;
+  invocation?: AzCliInvocation | null;
+  signal?: AbortSignal;
+  /** Capture is bounded independently of the child's output volume. */
+  captureBytes?: number;
+}
+
+export type AzCliAvailability =
+  | { available: true; invocation: AzCliInvocation }
+  | { available: false; reason: "not-found" | "not-runnable"; detail: string };
+
+function findOnWindowsPath(name: string, env: NodeJS.ProcessEnv): string | null {
+  const pathValue = env.PATH ?? env.Path ?? "";
+  const extensions = (env.PATHEXT ?? ".COM;.EXE;.BAT;.CMD").split(";").filter(Boolean).map((ext) => ext.toLowerCase());
+  for (const directory of pathValue.split(";").filter(Boolean)) {
+    for (const extension of extensions) {
+      const candidate = path.join(directory.replace(/^"|"$/g, ""), `${name}${extension}`);
+      try {
+        if (fs.statSync(candidate).isFile()) return candidate;
+      } catch {
+        // Keep searching PATH.
+      }
+    }
+  }
+  return null;
+}
+
+export function resolveAzCliInvocation(
+  env: NodeJS.ProcessEnv = process.env,
+  platform: NodeJS.Platform = process.platform
+): AzCliInvocation | null {
+  if (platform !== "win32") return { command: "az", prefixArgs: [], source: "az" };
+
+  const resolved = findOnWindowsPath("az", env);
+  if (!resolved) return null;
+  const extension = path.extname(resolved).toLowerCase();
+  if (extension === ".exe" || extension === ".com") {
+    return { command: resolved, prefixArgs: [], source: resolved };
+  }
+
+  // MSI install: wbin\az.cmd runs "..\python.exe -IBm azure.cli %*" with AZ_INSTALLER=MSI.
+  const bundledPython = path.join(path.dirname(resolved), "..", "python.exe");
+  if (path.basename(path.dirname(resolved)).toLowerCase() === "wbin" && fs.existsSync(bundledPython)) {
+    return {
+      command: path.resolve(bundledPython),
+      prefixArgs: ["-IBm", "azure.cli"],
+      env: { AZ_INSTALLER: "MSI" },
+      source: resolved,
+    };
+  }
+
+  return { command: env.ComSpec ?? "cmd.exe", prefixArgs: [], batchScript: resolved, source: resolved };
+}
+
+/** Builds the cmd.exe /s /c payload. Rejects characters cmd.exe would reinterpret even inside quotes. */
+export function buildBatchCommandLine(script: string, args: string[]): string {
+  for (const value of [script, ...args]) {
+    if (/["%\r\n]/.test(value)) {
+      throw new Error(`Azure CLI argument cannot be passed safely through ${path.basename(script)} (quotes, percent signs, or newlines).`);
+    }
+  }
+  return `"${[script, ...args].map((value) => `"${value.replace(/(\\+)$/, "$1$1")}"`).join(" ")}"`;
+}
+
+let cachedInvocation: AzCliInvocation | null | undefined;
+
+export function getAzCliInvocation(): AzCliInvocation | null {
+  if (cachedInvocation === undefined) cachedInvocation = resolveAzCliInvocation();
+  return cachedInvocation;
+}
+
+export function resetAzCliInvocationCache(): void {
+  cachedInvocation = undefined;
+}
+
+/** Test hook: pin the resolved invocation (null = not found). */
+export function setAzCliInvocationForTesting(invocation: AzCliInvocation | null | undefined): void {
+  cachedInvocation = invocation;
+}
+
+export function runAzCli(
+  args: string[],
+  options: AzCliRunOptions = {}
+): AzCliResult {
+  const startedAt = Date.now();
+  const invocation = options.invocation === undefined ? getAzCliInvocation() : options.invocation;
+  if (!invocation) {
+    return missingCliResult();
+  }
+  const spawnOptions: SpawnSyncOptions = {
+    shell: false,
+    encoding: "utf-8",
+    timeout: options.timeout ?? 300_000,
+    maxBuffer: options.captureBytes ?? 1_048_576,
+    env: invocation.env ? { ...process.env, ...invocation.env } : process.env,
+  };
+  let result;
+  try {
+    result = invocation.batchScript
+      ? spawnSync(invocation.command, ["/d", "/s", "/v:off", "/c", buildBatchCommandLine(invocation.batchScript, args)], {
+        ...spawnOptions,
+        windowsVerbatimArguments: true,
+      })
+      : spawnSync(invocation.command, [...invocation.prefixArgs, ...args], spawnOptions);
+  } catch (error) {
+    return {
+      ...missingCliResult(),
+      error: error instanceof Error ? error : new Error(String(error)),
+      errorCode: (error as NodeJS.ErrnoException)?.code,
+      elapsedMs: Date.now() - startedAt,
+    };
+  }
+  const errorCode = (result.error as NodeJS.ErrnoException | undefined)?.code;
+  return {
+    status: result.status,
+    stdout: String(result.stdout ?? ""),
+    stderr: String(result.stderr ?? ""),
+    signal: result.signal ?? null,
+    elapsedMs: Date.now() - startedAt,
+    stdoutTruncated: errorCode === "ENOBUFS",
+    stderrTruncated: errorCode === "ENOBUFS",
+    ...(errorCode ? { errorCode } : {}),
+    ...(errorCode === "ETIMEDOUT" ? { failureKind: "timeout" as const }
+      : errorCode === "ENOBUFS" ? { failureKind: "buffer" as const }
+        : result.error ? { failureKind: "spawn" as const }
+          : result.signal ? { failureKind: "signal" as const }
+            : result.status !== 0 ? { failureKind: "exit" as const } : {}),
+    ...(result.error ? { error: result.error } : {}),
+  };
+}
+
+function missingCliResult(): AzCliResult {
+  return {
+    status: null, stdout: "", stderr: "", signal: null, elapsedMs: 0,
+    stdoutTruncated: false, stderrTruncated: false,
+    error: Object.assign(new Error("az was not found on PATH"), { code: "ENOENT" }),
+    errorCode: "ENOENT", failureKind: "spawn",
+  };
+}
+
+/** Unlike spawnSync/maxBuffer, discarding excess output never kills the Azure CLI. */
+export async function runAzCliAsync(args: string[], options: AzCliRunOptions = {}): Promise<AzCliResult> {
+  const invocation = options.invocation === undefined ? getAzCliInvocation() : options.invocation;
+  if (!invocation) return missingCliResult();
+  const timeout = options.timeout ?? 60_000;
+  const captureBytes = options.captureBytes ?? 65_536;
+  if (!Number.isFinite(timeout) || timeout <= 0 || !Number.isInteger(captureBytes) || captureBytes < 1) {
+    throw new Error("Azure CLI timeout and captureBytes must be finite positive values.");
+  }
+  const startedAt = Date.now();
+  const result: AzCliResult = {
+    status: null, stdout: "", stderr: "", signal: null, elapsedMs: 0,
+    stdoutTruncated: false, stderrTruncated: false,
+  };
+  if (options.signal?.aborted) return { ...result, failureKind: "cancelled" };
+  let commandArgs: string[];
+  try {
+    commandArgs = invocation.batchScript
+      ? ["/d", "/s", "/v:off", "/c", buildBatchCommandLine(invocation.batchScript, args)]
+      : [...invocation.prefixArgs, ...args];
+  } catch (error) {
+    return { ...result, error: error instanceof Error ? error : new Error(String(error)), failureKind: "spawn" };
+  }
+  return new Promise<AzCliResult>((resolve) => {
+    let stdout = Buffer.alloc(0);
+    let stderr = Buffer.alloc(0);
+    let finished = false;
+    let drainTimer: NodeJS.Timeout | undefined;
+    let child: ReturnType<typeof spawn>;
+    const finish = () => {
+      if (finished) return;
+      finished = true;
+      clearTimeout(timer);
+      if (drainTimer) clearTimeout(drainTimer);
+      options.signal?.removeEventListener("abort", abort);
+      result.stdout = stdout.toString("utf-8");
+      result.stderr = stderr.toString("utf-8");
+      result.elapsedMs = Date.now() - startedAt;
+      if (!result.failureKind && result.status !== 0) {
+        result.failureKind = result.signal ? "signal"
+          : /ConnectionReset|ConnectionError|connection.*(?:closed|reset|aborted)|ReadTimeout|RemoteDisconnected|ETIMEDOUT|ECONNRESET/i.test(result.stderr)
+            ? "communication" : "exit";
+      }
+      resolve(result);
+    };
+    const stop = (kind: "timeout" | "cancelled") => {
+      if (finished || result.failureKind === "timeout" || result.failureKind === "cancelled") return;
+      result.failureKind = kind;
+      if (kind === "timeout") result.errorCode = "ETIMEDOUT";
+      child?.kill("SIGTERM");
+      // Descendants can inherit pipes; do not wait indefinitely for their close events.
+      drainTimer = setTimeout(() => {
+        child?.kill("SIGKILL");
+        child?.stdout?.destroy();
+        child?.stderr?.destroy();
+        result.stdoutTruncated = true;
+        result.stderrTruncated = true;
+        finish();
+      }, 1_000);
+    };
+    const abort = () => stop("cancelled");
+    const timer = setTimeout(() => stop("timeout"), timeout);
+    try {
+      child = spawn(invocation.command, commandArgs, {
+        shell: false,
+        windowsHide: true,
+        ...(invocation.batchScript ? { windowsVerbatimArguments: true } : {}),
+        env: invocation.env ? { ...process.env, ...invocation.env } : process.env,
+        stdio: ["ignore", "pipe", "pipe"],
+      });
+    } catch (error) {
+      result.error = error instanceof Error ? error : new Error(String(error));
+      result.errorCode = (error as NodeJS.ErrnoException)?.code;
+      result.failureKind = "spawn";
+      finish();
+      return;
+    }
+    const capture = (stream: "stdout" | "stderr", chunk: Buffer) => {
+      const buffer = stream === "stdout" ? stdout : stderr;
+      const remaining = captureBytes - buffer.length;
+      if (chunk.length > remaining) result[`${stream}Truncated`] = true;
+      if (remaining <= 0) return;
+      const combined = Buffer.concat([buffer, chunk.subarray(0, Math.max(remaining, 0))]);
+      if (stream === "stdout") stdout = combined;
+      else stderr = combined;
+    };
+    child.stdout?.on("data", (chunk: Buffer) => capture("stdout", chunk));
+    child.stderr?.on("data", (chunk: Buffer) => capture("stderr", chunk));
+    child.on("error", (error: NodeJS.ErrnoException) => {
+      if (finished) return;
+      result.error = error;
+      result.errorCode = error.code;
+      result.failureKind ??= "spawn";
+      finish();
+    });
+    child.on("exit", (code, signal) => {
+      if (finished) return;
+      result.status = code;
+      result.signal = signal;
+      if (!drainTimer) {
+        drainTimer = setTimeout(() => {
+          child.stdout?.destroy();
+          child.stderr?.destroy();
+          result.stdoutTruncated = true;
+          result.stderrTruncated = true;
+          finish();
+        }, 1_000);
+      }
+    });
+    child.on("close", (code, signal) => {
+      if (finished) return;
+      result.status = code;
+      result.signal = signal;
+      finish();
+    });
+    options.signal?.addEventListener("abort", abort, { once: true });
+    if (options.signal?.aborted) abort();
+  });
+}
+
+export function checkAzCliAvailability(): AzCliAvailability {
+  const invocation = getAzCliInvocation();
+  if (!invocation) {
+    return { available: false, reason: "not-found", detail: "az was not found on PATH." };
+  }
+  const result = runAzCli(["--version"], { timeout: 60_000, invocation });
+  if (result.status === 0) return { available: true, invocation };
+  const errorCode = (result.error as NodeJS.ErrnoException | undefined)?.code;
+  if (errorCode === "ENOENT") {
+    return { available: false, reason: "not-found", detail: "az was not found on PATH." };
+  }
+  const output = `${result.stderr || result.stdout}`.trim().split(/\r?\n/).slice(-3).join(" ");
+  return {
+    available: false,
+    reason: "not-runnable",
+    detail: `${invocation.source} could not run "az --version" (${result.error?.message ?? `exit ${result.status}`})${output ? `: ${output}` : ""}`,
+  };
+}

package/src/utils/azure-diagnostics.ts

@@ -0,0 +1,75 @@
+import type { AzCliResult } from "./azure-cli";
+
+const SENSITIVE_KEY = /outputs|parameters|password|secret|token|authorization|connection.?string|accountkey|api.?key|functions?.?key|client.?secret|access.?key|primary.?key|secondary.?key/i;
+
+export function redactAzureText(text: string, secretValues: readonly string[] = []): string {
+  const redactValues = (value: string) => {
+    for (const secret of secretValues) {
+      if (secret) value = value.split(secret).join("[REDACTED]").split(JSON.stringify(secret).slice(1, -1)).join("[REDACTED]");
+    }
+    return value;
+  };
+  text = redactValues(text);
+  let value = text;
+  try {
+    const redact = (entry: unknown): unknown => {
+      if (typeof entry === "string") return redactPlainText(redactValues(entry));
+      if (Array.isArray(entry)) return entry.map(redact);
+      if (entry && typeof entry === "object") {
+        return Object.fromEntries(Object.entries(entry).map(([key, item]) => [key, SENSITIVE_KEY.test(key) ? "[REDACTED]" : redact(item)]));
+      }
+      return entry;
+    };
+    value = JSON.stringify(redact(JSON.parse(text)));
+  } catch {
+    // An incomplete deployment payload cannot be safely projected/redacted.
+    if (/"(?:outputs|parameters)"\s*:/i.test(text)) return "[Azure payload omitted: may contain secrets]";
+    value = redactPlainText(text);
+  }
+  return value;
+}
+
+function redactPlainText(text: string): string {
+  return text
+    .replace(/\bBearer\s+[^\s"',;]+/gi, "Bearer [REDACTED]")
+    .replace(/\beyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\b/g, "[REDACTED]")
+    .replace(/(?:AccountEndpoint|DefaultEndpointsProtocol)=[^\r\n"']+/gi, "[connection string REDACTED]")
+    .replace(/((?:api[-_ ]?key|functions?[-_ ]?key|accountkey|password|client[-_ ]?secret|secret|token|access[-_ ]?key|primary[-_ ]?key|secondary[-_ ]?key|authorization)\s*["']?\s*[:=]\s*)(?:"[^"]*"|'[^']*'|[^\s,;}\]]+)/gi, "$1[REDACTED]")
+    .replace(/([?&](?:code|sig|token|key|secret|password)=)[^&\s"'<>]+/gi, "$1[REDACTED]");
+}
+
+export interface AzureCliDiagnostic {
+  phase: string;
+  exitCode: number | null;
+  signal: NodeJS.Signals | null;
+  elapsedMs: number;
+  failureKind?: AzCliResult["failureKind"];
+  errorCode?: string;
+  stdout: string;
+  stderr: string;
+  outputTruncated: boolean;
+}
+
+export function azureCliDiagnostic(result: AzCliResult, phase: string, secretValues: readonly string[] = []): AzureCliDiagnostic {
+  const stdout = result.stdoutTruncated ? "[stdout omitted: capture limit reached]" : redactAzureText(result.stdout, secretValues);
+  const stderr = result.stderrTruncated ? "[stderr omitted: capture limit reached]" : redactAzureText(result.stderr, secretValues);
+  return {
+    phase,
+    exitCode: result.status,
+    signal: result.signal ?? null,
+    elapsedMs: result.elapsedMs,
+    ...(result.failureKind ? { failureKind: result.failureKind } : {}),
+    ...(result.errorCode ? { errorCode: result.errorCode } : {}),
+    stdout: stdout.slice(0, 4_000),
+    stderr: stderr.slice(0, 4_000),
+    outputTruncated: result.stdoutTruncated || result.stderrTruncated || stdout.length > 4_000 || stderr.length > 4_000,
+  };
+}
+
+export function formatAzureDiagnostic(diagnostic: AzureCliDiagnostic): string {
+  return [
+    `az ${diagnostic.phase}: exit=${diagnostic.exitCode ?? "unknown"}, signal=${diagnostic.signal ?? "none"}, kind=${diagnostic.failureKind ?? "none"}, elapsed=${diagnostic.elapsedMs}ms${diagnostic.errorCode ? `, error=${diagnostic.errorCode}` : ""}${diagnostic.outputTruncated ? ", output omitted/truncated" : ""}`,
+    ...(diagnostic.stdout ? [`stdout: ${diagnostic.stdout}`] : []),
+    ...(diagnostic.stderr ? [`stderr: ${diagnostic.stderr}`] : []),
+  ].join("\n");
+}

package/src/utils/package-manager.ts

@@ -1,7 +1,7 @@
 import * as fs from "fs";
 import * as path from "path";
 import { execSync } from "child_process";
-import { BackendLanguage } from "../types";
+import { BackendLanguage, FrontendFramework } from "../types";
 
 /**
  * Supported package managers
@@ -156,7 +156,7 @@ export function getWorkspaceConfig(pm: PackageManager, workspaces: string[]) {
       /** pnpm uses pnpm-workspace.yaml */
       type: "file" as const,
       filename: "pnpm-workspace.yaml",
-      content: `packages:\n${workspaces.map((w) => `  - ${w}`).join("\n")}\nallowBuilds:\n  protobufjs: false\n  unrs-resolver: false\n`,
+      content: `packages:\n${workspaces.map((w) => `  - ${w}`).join("\n")}\nallowBuilds:\n  keytar: false\n  protobufjs: false\n  unrs-resolver: false\n`,
     };
   }
 
@@ -214,7 +214,10 @@ export function getAzurePipelinesSetup(pm: PackageManager): string {
 /**
  * Build script for generated package.json (depends on workspace command syntax)
  */
-export function getBuildScript(pm: PackageManager): string {
+export function getBuildScript(pm: PackageManager, frontend: FrontendFramework = "nextjs"): string {
+  if (frontend === "react") {
+    return `${getCommands(pm).runFilter("shared")} build && tsc --noEmit && vite build && node -e "require('fs').copyFileSync('staticwebapp.config.json','dist/staticwebapp.config.json')" && ${getCommands(pm).runFilter("bff")} build`;
+  }
   const copyStandaloneAssets = `node -e "const fs=require('fs');fs.mkdirSync('.next/standalone/.next',{recursive:true});if(fs.existsSync('.next/static'))fs.cpSync('.next/static','.next/standalone/.next/static',{recursive:true});if(fs.existsSync('public'))fs.cpSync('public','.next/standalone/public',{recursive:true});"`;
 
   if (pm === "pnpm") {
@@ -247,5 +250,5 @@ export function getFunctionsStartScript(
     return "cd functions && npm start";
   }
 
-  return "cd functions && func start";
+  return backendLanguage === "csharp" ? "cd functions && dotnet run" : "cd functions && func start";
 }

package/src/utils/python-uv.ts

@@ -1,13 +1,13 @@
 import * as path from "path";
+import * as fs from "fs";
+import { execFile } from "child_process";
+import { promisify } from "util";
 
-export const SWALLOWKIT_PYTHON_VERSION = "3.11";
+const execFileAsync = promisify(execFile);
+export const DEFAULT_AZURE_PYTHON_VERSION = "3.14";
 
 export interface ProjectLocalUvPaths {
   stateDir: string;
-  cacheDir: string;
-  pythonInstallDir: string;
-  toolDir: string;
-  toolBinDir: string;
   localUvInstallDir: string;
   localUvExecutable: string;
 }
@@ -22,10 +22,6 @@ export function getProjectLocalUvPaths(projectRoot: string): ProjectLocalUvPaths
 
   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")
@@ -33,40 +29,26 @@ export function getProjectLocalUvPaths(projectRoot: string): ProjectLocalUvPaths
   };
 }
 
-export function buildProjectLocalUvEnv(
+export function buildProjectLocalUvInstallerEnv(
   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",
+    UV_UNMANAGED_INSTALL: uvPaths.localUvInstallDir,
+    UV_NO_MODIFY_PATH: "1",
   };
-
+  // Windows PowerShell must discover its own modules, not inherit PowerShell 7's.
   if (process.platform === "win32") {
-    env.UV_PYTHON_NO_REGISTRY = "true";
+    for (const key of Object.keys(env)) {
+      if (key.toLowerCase() === "psmodulepath") delete env[key];
+    }
   }
-
   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 {
@@ -87,10 +69,48 @@ export function getProjectLocalUvInstallerCommand(): { command: string; args: st
   };
 }
 
-export function buildUvVenvArgs(venvDir: string, pythonVersion = SWALLOWKIT_PYTHON_VERSION): string[] {
-  return ["venv", venvDir, "--python", pythonVersion];
+export function buildUvVenvArgs(venvDir: string): string[] {
+  return ["venv", venvDir];
+}
+
+export function getVirtualEnvPythonPath(venvDir: string): string {
+  return process.platform === "win32"
+    ? path.join(venvDir, "Scripts", "python.exe")
+    : path.join(venvDir, "bin", "python");
+}
+
+export async function ensureUvVirtualEnvironment(
+  uvCommand: string,
+  venvDir: string,
+  cwd: string,
+  env: NodeJS.ProcessEnv
+): Promise<string> {
+  const pythonExecutable = getVirtualEnvPythonPath(venvDir);
+  if (!fs.existsSync(venvDir)) {
+    const { stdout, stderr } = await execFileAsync(uvCommand, buildUvVenvArgs(venvDir), { cwd, env });
+    if (env.SWALLOWKIT_MACHINE_OUTPUT !== "1") {
+      if (stdout) process.stdout.write(stdout);
+      if (stderr) process.stderr.write(stderr);
+    }
+  }
+  try {
+    await execFileAsync(pythonExecutable, ["--version"], { cwd, env });
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : String(error);
+    throw new Error(
+      `Cannot execute Python at ${pythonExecutable}: ${reason}\n` +
+      "The virtual environment was preserved. Check the interpreter and OS application-control policy. " +
+      "To switch Python, explicitly recreate this environment with uv and a trusted interpreter; SwallowKit will not clear it automatically."
+    );
+  }
+  return pythonExecutable;
 }
 
 export function buildUvPipInstallArgs(pythonExecutable: string, requirementsPath: string): string[] {
   return ["pip", "install", "--python", pythonExecutable, "-r", requirementsPath];
 }
+
+export function buildPythonCodegenInstallEnv(env: NodeJS.ProcessEnv): NodeJS.ProcessEnv {
+  // Codegen reads JSON; PyYAML's optional accelerator must not require a C compiler.
+  return { ...env, PYYAML_FORCE_LIBYAML: env.PYYAML_FORCE_LIBYAML ?? "0" };
+}

package/src/utils/react-dev.ts

@@ -0,0 +1,31 @@
+export const REACT_DEV_WATCH_DIRECTORIES = [
+  "functions",
+  "bff",
+  ".uv",
+  ".swallowkit",
+  "shared/dist",
+];
+
+export function buildReactDevWatchIgnoredSource(rootExpression: string): string {
+  return `${JSON.stringify(REACT_DEV_WATCH_DIRECTORIES)}.map(directory => \`\${${rootExpression}.replace(/\\\\/g, '/').replace(/\\/$/, '')}/\${directory}/**\`)`;
+}
+
+export function buildReactDevConfigSource(): string {
+  return `import { defineConfig, loadConfigFromFile, mergeConfig } from 'vite';
+
+export default defineConfig(async env => {
+  const loaded = await loadConfigFromFile(env, undefined, process.cwd());
+  const config = loaded?.config ?? {};
+  if (config.server?.watch === null) return config;
+  return mergeConfig(config, {
+    plugins: [{
+      name: 'swallowkit-dev-watch-boundaries',
+      configResolved(resolved) {
+        resolved.configFileDependencies.push(...(loaded?.dependencies ?? []));
+      },
+    }],
+    server: { watch: { ignored: ${buildReactDevWatchIgnoredSource("process.cwd()")} } },
+  });
+});
+`;
+}

package/src/utils/semver.ts

@@ -0,0 +1,59 @@
+export interface ParsedSemver {
+  major: number;
+  minor: number;
+  patch: number;
+  prerelease: Array<string | number>;
+}
+
+const SEMVER_PATTERN =
+  /^v?(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[A-Za-z-][0-9A-Za-z-]*)(?:\.(?:0|[1-9]\d*|\d*[A-Za-z-][0-9A-Za-z-]*))*))?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/;
+
+export function parseSemver(value: string | null | undefined): ParsedSemver | null {
+  const match = typeof value === "string" ? SEMVER_PATTERN.exec(value.trim()) : null;
+  if (!match) return null;
+  return {
+    major: Number(match[1]),
+    minor: Number(match[2]),
+    patch: Number(match[3]),
+    prerelease: match[4]
+      ? match[4].split(".").map((identifier) => (/^\d+$/.test(identifier) ? Number(identifier) : identifier))
+      : [],
+  };
+}
+
+export function isPrerelease(value: string): boolean {
+  return (parseSemver(value)?.prerelease.length ?? 0) > 0;
+}
+
+/**
+ * Compares versions by SemVer 2.0 precedence. Build metadata is ignored.
+ * Returns null when either value is not a valid version.
+ */
+export function compareSemver(left: string, right: string): number | null {
+  const a = parseSemver(left);
+  const b = parseSemver(right);
+  if (!a || !b) return null;
+
+  for (const key of ["major", "minor", "patch"] as const) {
+    if (a[key] !== b[key]) return a[key] < b[key] ? -1 : 1;
+  }
+
+  if (a.prerelease.length === 0 || b.prerelease.length === 0) {
+    if (a.prerelease.length === b.prerelease.length) return 0;
+    return a.prerelease.length === 0 ? 1 : -1;
+  }
+
+  const length = Math.max(a.prerelease.length, b.prerelease.length);
+  for (let index = 0; index < length; index++) {
+    const leftId = a.prerelease[index];
+    const rightId = b.prerelease[index];
+    if (leftId === undefined) return -1;
+    if (rightId === undefined) return 1;
+    if (leftId === rightId) continue;
+    if (typeof leftId === "number" && typeof rightId === "number") return leftId < rightId ? -1 : 1;
+    if (typeof leftId === "number") return -1;
+    if (typeof rightId === "number") return 1;
+    return leftId < rightId ? -1 : 1;
+  }
+  return 0;
+}