bmad-plus 0.12.1 → 0.13.0

package/tools/cli/lib/python-provision.js

@@ -1,508 +1,508 @@
-/**
- * BMAD+ Unified Python Provisioning (Pillar 2 — kills split-brain / broken-on-arrival)
- *
- * Provisions the Python runtime a pack declares in the registry
- * (`runtime: [node, python]` → seo, memory). One code path for every pack:
- *   1. detect a Python >= 3.11 interpreter (or a uv that can fetch one)
- *   2. choose a provisioner: uv > pipx > venv+pip
- *   3. create an isolated env under a given dir (e.g. <project>/.bmad/venv)
- *   4. install the pack's requirements.txt into that env
- *   5. VERIFY the pack's entry modules import / entry script runs
- *
- * Design rules:
- *  - every external command goes through spawnSync with an ARG ARRAY (never a
- *    shell string) → no injection surface, no quoting bugs.
- *  - pure functions (version parsing, candidate lists, provisioner choice,
- *    command construction) are exported separately and unit-tested without
- *    spawning anything.
- *  - side-effecting functions take an injectable `runner` for testability.
- *  - NOTHING here throws for a missing interpreter/tool: callers always get a
- *    structured { ok, tool, messages[] } with actionable guidance.
- *
- * Author: Laurent Rochetta
- */
-
-const { spawnSync } = require('node:child_process');
-const path = require('node:path');
-const fs = require('node:fs');
-
-/** Minimum Python required by the registry (registry.yaml → runtimes.python). */
-const MIN_PYTHON = { major: 3, minor: 11 };
-
-/** Hard ceiling for any single provisioning step (pip installs can be slow). */
-const STEP_TIMEOUT_MS = 10 * 60 * 1000;
-
-// ─────────────────────────────────────────────────────────────────────────────
-// Runner — the ONLY place a real process is spawned.
-// ─────────────────────────────────────────────────────────────────────────────
-
-/**
- * Default command runner. Wraps spawnSync with safe defaults.
- * @param {string} cmd  Executable name (resolved via PATH).
- * @param {string[]} args  Argument array — NEVER a shell string.
- * @param {object} [opts]  Extra spawnSync options (cwd, timeout…).
- * @returns {{ status: number|null, stdout: string, stderr: string, error: string|null }}
- */
-function defaultRunner(cmd, args, opts = {}) {
-  const res = spawnSync(cmd, args, {
-    encoding: 'utf8',
-    shell: false,
-    windowsHide: true,
-    timeout: STEP_TIMEOUT_MS,
-    ...opts,
-  });
-  return {
-    status: typeof res.status === 'number' ? res.status : null,
-    stdout: res.stdout || '',
-    stderr: res.stderr || '',
-    error: res.error ? String(res.error.message || res.error) : null,
-  };
-}
-
-/** True when a runner result represents a successful invocation. */
-function ranOk(result) {
-  return Boolean(result) && result.error === null && result.status === 0;
-}
-
-// ─────────────────────────────────────────────────────────────────────────────
-// Pure logic — no I/O, fully unit-testable.
-// ─────────────────────────────────────────────────────────────────────────────
-
-/**
- * Parse a `python --version` / `py -3 --version` output line.
- * Accepts "Python 3.11.4", "Python 3.13.0rc1", output on stdout OR stderr.
- * @param {string} text
- * @returns {{ major: number, minor: number, patch: number, raw: string }|null}
- */
-function parsePythonVersion(text) {
-  if (typeof text !== 'string') return null;
-  const m = text.match(/Python\s+(\d+)\.(\d+)(?:\.(\d+))?/i);
-  if (!m) return null;
-  return {
-    major: Number(m[1]),
-    minor: Number(m[2]),
-    patch: m[3] !== undefined ? Number(m[3]) : 0,
-    raw: m[0],
-  };
-}
-
-/**
- * @param {{major:number, minor:number}|null} version
- * @param {{major:number, minor:number}} [min]
- * @returns {boolean}
- */
-function meetsMinVersion(version, min = MIN_PYTHON) {
-  if (!version) return false;
-  if (version.major !== min.major) return version.major > min.major;
-  return version.minor >= min.minor;
-}
-
-/**
- * Interpreter candidates to probe, in priority order, per platform.
- * `baseArgs` are prepended to every use of the command (the Windows `py`
- * launcher needs `-3` to pick a Python 3).
- * @param {string} [platform]  process.platform value ('win32', 'linux', 'darwin')
- * @returns {Array<{ cmd: string, baseArgs: string[] }>}
- */
-function pythonCandidates(platform = process.platform) {
-  if (platform === 'win32') {
-    return [
-      { cmd: 'py', baseArgs: ['-3'] },
-      { cmd: 'python', baseArgs: [] },
-      { cmd: 'python3', baseArgs: [] },
-    ];
-  }
-  return [
-    { cmd: 'python3', baseArgs: [] },
-    { cmd: 'python', baseArgs: [] },
-  ];
-}
-
-/**
- * Choose the provisioner from availability flags (registry.yaml:
- * `provisioner: uv, fallback: pipx`, then plain venv+pip as last resort).
- * @param {{ uv?: boolean, pipx?: boolean }} availability
- * @returns {'uv'|'pipx'|'venv'}
- */
-function chooseProvisioner({ uv = false, pipx = false } = {}) {
-  if (uv) return 'uv';
-  if (pipx) return 'pipx';
-  return 'venv';
-}
-
-/**
- * Path of the python executable inside a virtualenv.
- * @param {string} envDir
- * @param {string} [platform]
- * @returns {string}
- */
-function venvPython(envDir, platform = process.platform) {
-  return platform === 'win32'
-    ? path.join(envDir, 'Scripts', 'python.exe')
-    : path.join(envDir, 'bin', 'python');
-}
-
-/**
- * Build the exact command steps (arg arrays) to create the env and install
- * requirements with the chosen tool. Pure: constructs, never executes.
- *
- * @param {object} p
- * @param {'uv'|'pipx'|'venv'} p.tool       Chosen provisioner.
- * @param {{cmd:string, baseArgs:string[]}|null} p.python  Detected interpreter
- *        (may be null only for uv, which can fetch its own Python).
- * @param {string} p.envDir                 Target env dir (e.g. .bmad/venv).
- * @param {string|null} [p.requirementsPath] requirements.txt to install, or null.
- * @param {string} [p.platform]
- * @returns {{ create: Array<{cmd:string,args:string[],label:string}>,
- *             install: Array<{cmd:string,args:string[],label:string}> }}
- */
-function buildEnvCommands({ tool, python, envDir, requirementsPath = null, platform = process.platform }) {
-  const envPy = venvPython(envDir, platform);
-  const create = [];
-  const install = [];
-
-  if (tool === 'uv') {
-    create.push({
-      cmd: 'uv',
-      // `--python 3.11` lets uv pick (or download) a matching interpreter even
-      // when the system Python is absent or too old.
-      args: ['venv', envDir, '--python', `${MIN_PYTHON.major}.${MIN_PYTHON.minor}`],
-      label: 'uv venv',
-    });
-    if (requirementsPath) {
-      install.push({
-        cmd: 'uv',
-        args: ['pip', 'install', '-r', requirementsPath, '--python', envPy],
-        label: 'uv pip install',
-      });
-    }
-    return { create, install };
-  }
-
-  if (tool === 'pipx') {
-    // pipx ships `pipx run` which can execute the virtualenv app in isolation
-    // without polluting the system Python.
-    create.push({
-      cmd: 'pipx',
-      args: ['run', 'virtualenv', envDir],
-      label: 'pipx run virtualenv',
-    });
-    if (requirementsPath) {
-      install.push({
-        cmd: envPy,
-        args: ['-m', 'pip', 'install', '-r', requirementsPath],
-        label: 'pip install (pipx env)',
-      });
-    }
-    return { create, install };
-  }
-
-  // tool === 'venv' — stdlib venv + pip, requires a detected interpreter.
-  const py = python || { cmd: 'python', baseArgs: [] };
-  create.push({
-    cmd: py.cmd,
-    args: [...py.baseArgs, '-m', 'venv', envDir],
-    label: 'python -m venv',
-  });
-  if (requirementsPath) {
-    install.push({
-      cmd: envPy,
-      args: ['-m', 'pip', 'install', '-r', requirementsPath],
-      label: 'pip install (venv)',
-    });
-  }
-  return { create, install };
-}
-
-/**
- * Human guidance shown when no suitable Python is found.
- * @param {string} [platform]
- * @returns {string[]}
- */
-function missingPythonGuidance(platform = process.platform) {
-  const min = `${MIN_PYTHON.major}.${MIN_PYTHON.minor}`;
-  const lines = [`Python >= ${min} was not found on PATH.`];
-  if (platform === 'win32') {
-    lines.push(`Install it with: winget install Python.Python.3.12  (or from https://www.python.org/downloads/)`);
-  } else if (platform === 'darwin') {
-    lines.push(`Install it with: brew install python@3.12  (or from https://www.python.org/downloads/)`);
-  } else {
-    lines.push(`Install it with your package manager (e.g. apt install python3.12) or from https://www.python.org/downloads/`);
-  }
-  lines.push(`Alternatively install uv (https://docs.astral.sh/uv/) — BMAD+ will use it to fetch Python ${min} automatically.`);
-  return lines;
-}
-
-// ─────────────────────────────────────────────────────────────────────────────
-// Side-effecting steps — all take an injectable runner.
-// ─────────────────────────────────────────────────────────────────────────────
-
-/**
- * Probe PATH for a Python >= minVersion.
- * Never throws: a missing interpreter yields { ok:false } + guidance.
- *
- * @param {object} [opts]
- * @param {Function} [opts.runner]
- * @param {string} [opts.platform]
- * @param {{major:number,minor:number}} [opts.minVersion]
- * @returns {{ ok: boolean, tool: 'python'|null, command: {cmd:string,baseArgs:string[]}|null,
- *             version: object|null, messages: string[] }}
- */
-function detectPython({ runner = defaultRunner, platform = process.platform, minVersion = MIN_PYTHON } = {}) {
-  const messages = [];
-  let tooOld = null;
-
-  for (const candidate of pythonCandidates(platform)) {
-    const res = runner(candidate.cmd, [...candidate.baseArgs, '--version']);
-    if (!ranOk(res)) continue; // not installed / broken shim — try next
-    // Python 2 printed the version on stderr; be liberal in what we accept.
-    const version = parsePythonVersion(`${res.stdout}\n${res.stderr}`);
-    if (!version) continue;
-    if (meetsMinVersion(version, minVersion)) {
-      messages.push(`Found ${version.raw} via \`${[candidate.cmd, ...candidate.baseArgs].join(' ')}\`.`);
-      return { ok: true, tool: 'python', command: candidate, version, messages };
-    }
-    tooOld = { candidate, version };
-  }
-
-  if (tooOld) {
-    messages.push(
-      `Found ${tooOld.version.raw} via \`${tooOld.candidate.cmd}\`, but BMAD+ requires >= ${minVersion.major}.${minVersion.minor}.`
-    );
-  }
-  messages.push(...missingPythonGuidance(platform));
-  return { ok: false, tool: null, command: null, version: null, messages };
-}
-
-/**
- * Detect which provisioner is available (uv > pipx > venv fallback).
- * @param {object} [opts]
- * @param {Function} [opts.runner]
- * @returns {{ ok: true, tool: 'uv'|'pipx'|'venv', messages: string[] }}
- */
-function detectProvisioner({ runner = defaultRunner } = {}) {
-  const messages = [];
-  const uv = ranOk(runner('uv', ['--version']));
-  const pipx = uv ? false : ranOk(runner('pipx', ['--version']));
-  const tool = chooseProvisioner({ uv, pipx });
-  if (tool === 'venv') {
-    messages.push('Neither uv nor pipx found — falling back to stdlib venv + pip.');
-  } else {
-    messages.push(`Using ${tool} as Python provisioner.`);
-  }
-  return { ok: true, tool, messages };
-}
-
-/**
- * Create the isolated env with the chosen tool.
- * @returns {{ ok: boolean, tool: string, envDir: string, messages: string[] }}
- */
-function createEnv({ tool, python, envDir, runner = defaultRunner, platform = process.platform }) {
-  const messages = [];
-  const { create } = buildEnvCommands({ tool, python, envDir, platform });
-  for (const step of create) {
-    const res = runner(step.cmd, step.args);
-    if (!ranOk(res)) {
-      messages.push(`Failed to create env (${step.label}): ${firstErrorLine(res)}`);
-      return { ok: false, tool, envDir, messages };
-    }
-  }
-  messages.push(`Created isolated Python env at ${envDir} (${tool}).`);
-  return { ok: true, tool, envDir, messages };
-}
-
-/**
- * Install a requirements.txt into an existing env.
- * @returns {{ ok: boolean, tool: string, messages: string[] }}
- */
-function installRequirements({
-  tool,
-  python,
-  envDir,
-  requirementsPath,
-  runner = defaultRunner,
-  platform = process.platform,
-  fileExists = fs.existsSync,
-}) {
-  const messages = [];
-  if (!requirementsPath) {
-    return { ok: true, tool, messages: ['No requirements.txt declared — nothing to install.'] };
-  }
-  if (!fileExists(requirementsPath)) {
-    messages.push(`requirements file not found: ${requirementsPath}`);
-    return { ok: false, tool, messages };
-  }
-  const { install } = buildEnvCommands({ tool, python, envDir, requirementsPath, platform });
-  for (const step of install) {
-    const res = runner(step.cmd, step.args);
-    if (!ranOk(res)) {
-      messages.push(`Dependency install failed (${step.label}): ${firstErrorLine(res)}`);
-      messages.push(`You can retry manually: ${step.cmd} ${step.args.join(' ')}`);
-      return { ok: false, tool, messages };
-    }
-  }
-  messages.push(`Installed ${path.basename(requirementsPath)} into ${envDir}.`);
-  return { ok: true, tool, messages };
-}
-
-/**
- * Verify that the pack's entry modules import inside the env.
- * @param {object} p
- * @param {string[]} p.modules  e.g. ['requests', 'bs4'] — verified in ONE interpreter call.
- * @returns {{ ok: boolean, messages: string[] }}
- */
-function verifyImports({ envDir, modules, runner = defaultRunner, platform = process.platform }) {
-  if (!Array.isArray(modules) || modules.length === 0) {
-    return { ok: true, messages: [] };
-  }
-  const envPy = venvPython(envDir, platform);
-  const res = runner(envPy, ['-c', `import ${modules.join(', ')}`]);
-  if (!ranOk(res)) {
-    return {
-      ok: false,
-      messages: [`Import check failed for [${modules.join(', ')}]: ${firstErrorLine(res)}`],
-    };
-  }
-  return { ok: true, messages: [`Verified imports: ${modules.join(', ')}.`] };
-}
-
-/**
- * Verify that the pack's entry script runs inside the env (default: --help).
- * @returns {{ ok: boolean, messages: string[] }}
- */
-function verifyEntry({ envDir, entryPath, entryArgs = ['--help'], runner = defaultRunner, platform = process.platform }) {
-  if (!entryPath) return { ok: true, messages: [] };
-  const envPy = venvPython(envDir, platform);
-  const res = runner(envPy, [entryPath, ...entryArgs]);
-  if (!ranOk(res)) {
-    return {
-      ok: false,
-      messages: [`Entry check failed (${path.basename(entryPath)} ${entryArgs.join(' ')}): ${firstErrorLine(res)}`],
-    };
-  }
-  return { ok: true, messages: [`Verified entry: ${path.basename(entryPath)} runs.`] };
-}
-
-/**
- * Full pipeline: detect → choose provisioner → create env → install → verify.
- * This is the single call site the installer uses for ANY pack whose registry
- * runtime includes "python" (seo, memory, …).
- *
- * Never throws for environmental problems — always returns
- * { ok, tool, messages[] } so the installer can degrade gracefully and print
- * guidance instead of aborting the whole install.
- *
- * @param {object} p
- * @param {string} p.envDir                    e.g. path.join(projectDir, '.bmad', 'venv')
- * @param {string|null} [p.requirementsPath]   pack requirements.txt (absolute)
- * @param {string[]} [p.verifyModules]         modules that must import post-install
- * @param {string|null} [p.entryPath]          entry script to smoke-run
- * @param {string[]} [p.entryArgs]
- * @param {Function} [p.runner]                injectable for tests
- * @param {string} [p.platform]
- * @param {Function} [p.fileExists]
- * @param {{major:number,minor:number}} [p.minVersion]
- * @returns {{ ok: boolean, tool: string|null, envDir: string, python: object|null, messages: string[] }}
- */
-function provisionPack({
-  envDir,
-  requirementsPath = null,
-  verifyModules = [],
-  entryPath = null,
-  entryArgs = ['--help'],
-  runner = defaultRunner,
-  platform = process.platform,
-  fileExists = fs.existsSync,
-  minVersion = MIN_PYTHON,
-}) {
-  const messages = [];
-
-  if (!envDir) {
-    return { ok: false, tool: null, envDir: null, python: null, messages: ['provisionPack: envDir is required.'] };
-  }
-
-  // 1) provisioner first — uv can operate without a system Python.
-  const prov = detectProvisioner({ runner });
-  messages.push(...prov.messages);
-
-  // 2) interpreter
-  const py = detectPython({ runner, platform, minVersion });
-  messages.push(...py.messages);
-  if (!py.ok && prov.tool !== 'uv') {
-    return { ok: false, tool: prov.tool, envDir, python: null, messages };
-  }
-  if (!py.ok && prov.tool === 'uv') {
-    messages.push(`No system Python >= ${minVersion.major}.${minVersion.minor} — uv will download a managed interpreter.`);
-  }
-
-  // 3) create isolated env
-  const created = createEnv({ tool: prov.tool, python: py.command, envDir, runner, platform });
-  messages.push(...created.messages);
-  if (!created.ok) {
-    return { ok: false, tool: prov.tool, envDir, python: py.version, messages };
-  }
-
-  // 4) install requirements
-  const installed = installRequirements({
-    tool: prov.tool,
-    python: py.command,
-    envDir,
-    requirementsPath,
-    runner,
-    platform,
-    fileExists,
-  });
-  messages.push(...installed.messages);
-  if (!installed.ok) {
-    return { ok: false, tool: prov.tool, envDir, python: py.version, messages };
-  }
-
-  // 5) verify — a pack is only "installed" when its entry actually works.
-  const imports = verifyImports({ envDir, modules: verifyModules, runner, platform });
-  messages.push(...imports.messages);
-  if (!imports.ok) {
-    return { ok: false, tool: prov.tool, envDir, python: py.version, messages };
-  }
-
-  const entry = verifyEntry({ envDir, entryPath, entryArgs, runner, platform });
-  messages.push(...entry.messages);
-  if (!entry.ok) {
-    return { ok: false, tool: prov.tool, envDir, python: py.version, messages };
-  }
-
-  messages.push('Python runtime provisioned and verified.');
-  return { ok: true, tool: prov.tool, envDir, python: py.version, messages };
-}
-
-// ─────────────────────────────────────────────────────────────────────────────
-// Helpers
-// ─────────────────────────────────────────────────────────────────────────────
-
-/** First non-empty diagnostic line from a runner result, for compact messages. */
-function firstErrorLine(res) {
-  if (!res) return 'no result';
-  if (res.error) return res.error;
-  const text = `${res.stderr}\n${res.stdout}`.split(/\r?\n/).map((l) => l.trim()).filter(Boolean);
-  return text.length > 0 ? text[text.length - 1] : `exit code ${res.status}`;
-}
-
-module.exports = {
-  MIN_PYTHON,
-  // pure
-  parsePythonVersion,
-  meetsMinVersion,
-  pythonCandidates,
-  chooseProvisioner,
-  venvPython,
-  buildEnvCommands,
-  missingPythonGuidance,
-  // side-effecting (injectable runner)
-  defaultRunner,
-  detectPython,
-  detectProvisioner,
-  createEnv,
-  installRequirements,
-  verifyImports,
-  verifyEntry,
-  provisionPack,
-};
+/**
+ * BMAD+ Unified Python Provisioning (Pillar 2 — kills split-brain / broken-on-arrival)
+ *
+ * Provisions the Python runtime a pack declares in the registry
+ * (`runtime: [node, python]` → seo, memory). One code path for every pack:
+ *   1. detect a Python >= 3.11 interpreter (or a uv that can fetch one)
+ *   2. choose a provisioner: uv > pipx > venv+pip
+ *   3. create an isolated env under a given dir (e.g. <project>/.bmad/venv)
+ *   4. install the pack's requirements.txt into that env
+ *   5. VERIFY the pack's entry modules import / entry script runs
+ *
+ * Design rules:
+ *  - every external command goes through spawnSync with an ARG ARRAY (never a
+ *    shell string) → no injection surface, no quoting bugs.
+ *  - pure functions (version parsing, candidate lists, provisioner choice,
+ *    command construction) are exported separately and unit-tested without
+ *    spawning anything.
+ *  - side-effecting functions take an injectable `runner` for testability.
+ *  - NOTHING here throws for a missing interpreter/tool: callers always get a
+ *    structured { ok, tool, messages[] } with actionable guidance.
+ *
+ * Author: Laurent Rochetta
+ */
+
+const { spawnSync } = require('node:child_process');
+const path = require('node:path');
+const fs = require('node:fs');
+
+/** Minimum Python required by the registry (registry.yaml → runtimes.python). */
+const MIN_PYTHON = { major: 3, minor: 11 };
+
+/** Hard ceiling for any single provisioning step (pip installs can be slow). */
+const STEP_TIMEOUT_MS = 10 * 60 * 1000;
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Runner — the ONLY place a real process is spawned.
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Default command runner. Wraps spawnSync with safe defaults.
+ * @param {string} cmd  Executable name (resolved via PATH).
+ * @param {string[]} args  Argument array — NEVER a shell string.
+ * @param {object} [opts]  Extra spawnSync options (cwd, timeout…).
+ * @returns {{ status: number|null, stdout: string, stderr: string, error: string|null }}
+ */
+function defaultRunner(cmd, args, opts = {}) {
+  const res = spawnSync(cmd, args, {
+    encoding: 'utf8',
+    shell: false,
+    windowsHide: true,
+    timeout: STEP_TIMEOUT_MS,
+    ...opts,
+  });
+  return {
+    status: typeof res.status === 'number' ? res.status : null,
+    stdout: res.stdout || '',
+    stderr: res.stderr || '',
+    error: res.error ? String(res.error.message || res.error) : null,
+  };
+}
+
+/** True when a runner result represents a successful invocation. */
+function ranOk(result) {
+  return Boolean(result) && result.error === null && result.status === 0;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Pure logic — no I/O, fully unit-testable.
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Parse a `python --version` / `py -3 --version` output line.
+ * Accepts "Python 3.11.4", "Python 3.13.0rc1", output on stdout OR stderr.
+ * @param {string} text
+ * @returns {{ major: number, minor: number, patch: number, raw: string }|null}
+ */
+function parsePythonVersion(text) {
+  if (typeof text !== 'string') return null;
+  const m = text.match(/Python\s+(\d+)\.(\d+)(?:\.(\d+))?/i);
+  if (!m) return null;
+  return {
+    major: Number(m[1]),
+    minor: Number(m[2]),
+    patch: m[3] !== undefined ? Number(m[3]) : 0,
+    raw: m[0],
+  };
+}
+
+/**
+ * @param {{major:number, minor:number}|null} version
+ * @param {{major:number, minor:number}} [min]
+ * @returns {boolean}
+ */
+function meetsMinVersion(version, min = MIN_PYTHON) {
+  if (!version) return false;
+  if (version.major !== min.major) return version.major > min.major;
+  return version.minor >= min.minor;
+}
+
+/**
+ * Interpreter candidates to probe, in priority order, per platform.
+ * `baseArgs` are prepended to every use of the command (the Windows `py`
+ * launcher needs `-3` to pick a Python 3).
+ * @param {string} [platform]  process.platform value ('win32', 'linux', 'darwin')
+ * @returns {Array<{ cmd: string, baseArgs: string[] }>}
+ */
+function pythonCandidates(platform = process.platform) {
+  if (platform === 'win32') {
+    return [
+      { cmd: 'py', baseArgs: ['-3'] },
+      { cmd: 'python', baseArgs: [] },
+      { cmd: 'python3', baseArgs: [] },
+    ];
+  }
+  return [
+    { cmd: 'python3', baseArgs: [] },
+    { cmd: 'python', baseArgs: [] },
+  ];
+}
+
+/**
+ * Choose the provisioner from availability flags (registry.yaml:
+ * `provisioner: uv, fallback: pipx`, then plain venv+pip as last resort).
+ * @param {{ uv?: boolean, pipx?: boolean }} availability
+ * @returns {'uv'|'pipx'|'venv'}
+ */
+function chooseProvisioner({ uv = false, pipx = false } = {}) {
+  if (uv) return 'uv';
+  if (pipx) return 'pipx';
+  return 'venv';
+}
+
+/**
+ * Path of the python executable inside a virtualenv.
+ * @param {string} envDir
+ * @param {string} [platform]
+ * @returns {string}
+ */
+function venvPython(envDir, platform = process.platform) {
+  return platform === 'win32'
+    ? path.join(envDir, 'Scripts', 'python.exe')
+    : path.join(envDir, 'bin', 'python');
+}
+
+/**
+ * Build the exact command steps (arg arrays) to create the env and install
+ * requirements with the chosen tool. Pure: constructs, never executes.
+ *
+ * @param {object} p
+ * @param {'uv'|'pipx'|'venv'} p.tool       Chosen provisioner.
+ * @param {{cmd:string, baseArgs:string[]}|null} p.python  Detected interpreter
+ *        (may be null only for uv, which can fetch its own Python).
+ * @param {string} p.envDir                 Target env dir (e.g. .bmad/venv).
+ * @param {string|null} [p.requirementsPath] requirements.txt to install, or null.
+ * @param {string} [p.platform]
+ * @returns {{ create: Array<{cmd:string,args:string[],label:string}>,
+ *             install: Array<{cmd:string,args:string[],label:string}> }}
+ */
+function buildEnvCommands({ tool, python, envDir, requirementsPath = null, platform = process.platform }) {
+  const envPy = venvPython(envDir, platform);
+  const create = [];
+  const install = [];
+
+  if (tool === 'uv') {
+    create.push({
+      cmd: 'uv',
+      // `--python 3.11` lets uv pick (or download) a matching interpreter even
+      // when the system Python is absent or too old.
+      args: ['venv', envDir, '--python', `${MIN_PYTHON.major}.${MIN_PYTHON.minor}`],
+      label: 'uv venv',
+    });
+    if (requirementsPath) {
+      install.push({
+        cmd: 'uv',
+        args: ['pip', 'install', '-r', requirementsPath, '--python', envPy],
+        label: 'uv pip install',
+      });
+    }
+    return { create, install };
+  }
+
+  if (tool === 'pipx') {
+    // pipx ships `pipx run` which can execute the virtualenv app in isolation
+    // without polluting the system Python.
+    create.push({
+      cmd: 'pipx',
+      args: ['run', 'virtualenv', envDir],
+      label: 'pipx run virtualenv',
+    });
+    if (requirementsPath) {
+      install.push({
+        cmd: envPy,
+        args: ['-m', 'pip', 'install', '-r', requirementsPath],
+        label: 'pip install (pipx env)',
+      });
+    }
+    return { create, install };
+  }
+
+  // tool === 'venv' — stdlib venv + pip, requires a detected interpreter.
+  const py = python || { cmd: 'python', baseArgs: [] };
+  create.push({
+    cmd: py.cmd,
+    args: [...py.baseArgs, '-m', 'venv', envDir],
+    label: 'python -m venv',
+  });
+  if (requirementsPath) {
+    install.push({
+      cmd: envPy,
+      args: ['-m', 'pip', 'install', '-r', requirementsPath],
+      label: 'pip install (venv)',
+    });
+  }
+  return { create, install };
+}
+
+/**
+ * Human guidance shown when no suitable Python is found.
+ * @param {string} [platform]
+ * @returns {string[]}
+ */
+function missingPythonGuidance(platform = process.platform) {
+  const min = `${MIN_PYTHON.major}.${MIN_PYTHON.minor}`;
+  const lines = [`Python >= ${min} was not found on PATH.`];
+  if (platform === 'win32') {
+    lines.push(`Install it with: winget install Python.Python.3.12  (or from https://www.python.org/downloads/)`);
+  } else if (platform === 'darwin') {
+    lines.push(`Install it with: brew install python@3.12  (or from https://www.python.org/downloads/)`);
+  } else {
+    lines.push(`Install it with your package manager (e.g. apt install python3.12) or from https://www.python.org/downloads/`);
+  }
+  lines.push(`Alternatively install uv (https://docs.astral.sh/uv/) — BMAD+ will use it to fetch Python ${min} automatically.`);
+  return lines;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Side-effecting steps — all take an injectable runner.
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Probe PATH for a Python >= minVersion.
+ * Never throws: a missing interpreter yields { ok:false } + guidance.
+ *
+ * @param {object} [opts]
+ * @param {Function} [opts.runner]
+ * @param {string} [opts.platform]
+ * @param {{major:number,minor:number}} [opts.minVersion]
+ * @returns {{ ok: boolean, tool: 'python'|null, command: {cmd:string,baseArgs:string[]}|null,
+ *             version: object|null, messages: string[] }}
+ */
+function detectPython({ runner = defaultRunner, platform = process.platform, minVersion = MIN_PYTHON } = {}) {
+  const messages = [];
+  let tooOld = null;
+
+  for (const candidate of pythonCandidates(platform)) {
+    const res = runner(candidate.cmd, [...candidate.baseArgs, '--version']);
+    if (!ranOk(res)) continue; // not installed / broken shim — try next
+    // Python 2 printed the version on stderr; be liberal in what we accept.
+    const version = parsePythonVersion(`${res.stdout}\n${res.stderr}`);
+    if (!version) continue;
+    if (meetsMinVersion(version, minVersion)) {
+      messages.push(`Found ${version.raw} via \`${[candidate.cmd, ...candidate.baseArgs].join(' ')}\`.`);
+      return { ok: true, tool: 'python', command: candidate, version, messages };
+    }
+    tooOld = { candidate, version };
+  }
+
+  if (tooOld) {
+    messages.push(
+      `Found ${tooOld.version.raw} via \`${tooOld.candidate.cmd}\`, but BMAD+ requires >= ${minVersion.major}.${minVersion.minor}.`
+    );
+  }
+  messages.push(...missingPythonGuidance(platform));
+  return { ok: false, tool: null, command: null, version: null, messages };
+}
+
+/**
+ * Detect which provisioner is available (uv > pipx > venv fallback).
+ * @param {object} [opts]
+ * @param {Function} [opts.runner]
+ * @returns {{ ok: true, tool: 'uv'|'pipx'|'venv', messages: string[] }}
+ */
+function detectProvisioner({ runner = defaultRunner } = {}) {
+  const messages = [];
+  const uv = ranOk(runner('uv', ['--version']));
+  const pipx = uv ? false : ranOk(runner('pipx', ['--version']));
+  const tool = chooseProvisioner({ uv, pipx });
+  if (tool === 'venv') {
+    messages.push('Neither uv nor pipx found — falling back to stdlib venv + pip.');
+  } else {
+    messages.push(`Using ${tool} as Python provisioner.`);
+  }
+  return { ok: true, tool, messages };
+}
+
+/**
+ * Create the isolated env with the chosen tool.
+ * @returns {{ ok: boolean, tool: string, envDir: string, messages: string[] }}
+ */
+function createEnv({ tool, python, envDir, runner = defaultRunner, platform = process.platform }) {
+  const messages = [];
+  const { create } = buildEnvCommands({ tool, python, envDir, platform });
+  for (const step of create) {
+    const res = runner(step.cmd, step.args);
+    if (!ranOk(res)) {
+      messages.push(`Failed to create env (${step.label}): ${firstErrorLine(res)}`);
+      return { ok: false, tool, envDir, messages };
+    }
+  }
+  messages.push(`Created isolated Python env at ${envDir} (${tool}).`);
+  return { ok: true, tool, envDir, messages };
+}
+
+/**
+ * Install a requirements.txt into an existing env.
+ * @returns {{ ok: boolean, tool: string, messages: string[] }}
+ */
+function installRequirements({
+  tool,
+  python,
+  envDir,
+  requirementsPath,
+  runner = defaultRunner,
+  platform = process.platform,
+  fileExists = fs.existsSync,
+}) {
+  const messages = [];
+  if (!requirementsPath) {
+    return { ok: true, tool, messages: ['No requirements.txt declared — nothing to install.'] };
+  }
+  if (!fileExists(requirementsPath)) {
+    messages.push(`requirements file not found: ${requirementsPath}`);
+    return { ok: false, tool, messages };
+  }
+  const { install } = buildEnvCommands({ tool, python, envDir, requirementsPath, platform });
+  for (const step of install) {
+    const res = runner(step.cmd, step.args);
+    if (!ranOk(res)) {
+      messages.push(`Dependency install failed (${step.label}): ${firstErrorLine(res)}`);
+      messages.push(`You can retry manually: ${step.cmd} ${step.args.join(' ')}`);
+      return { ok: false, tool, messages };
+    }
+  }
+  messages.push(`Installed ${path.basename(requirementsPath)} into ${envDir}.`);
+  return { ok: true, tool, messages };
+}
+
+/**
+ * Verify that the pack's entry modules import inside the env.
+ * @param {object} p
+ * @param {string[]} p.modules  e.g. ['requests', 'bs4'] — verified in ONE interpreter call.
+ * @returns {{ ok: boolean, messages: string[] }}
+ */
+function verifyImports({ envDir, modules, runner = defaultRunner, platform = process.platform }) {
+  if (!Array.isArray(modules) || modules.length === 0) {
+    return { ok: true, messages: [] };
+  }
+  const envPy = venvPython(envDir, platform);
+  const res = runner(envPy, ['-c', `import ${modules.join(', ')}`]);
+  if (!ranOk(res)) {
+    return {
+      ok: false,
+      messages: [`Import check failed for [${modules.join(', ')}]: ${firstErrorLine(res)}`],
+    };
+  }
+  return { ok: true, messages: [`Verified imports: ${modules.join(', ')}.`] };
+}
+
+/**
+ * Verify that the pack's entry script runs inside the env (default: --help).
+ * @returns {{ ok: boolean, messages: string[] }}
+ */
+function verifyEntry({ envDir, entryPath, entryArgs = ['--help'], runner = defaultRunner, platform = process.platform }) {
+  if (!entryPath) return { ok: true, messages: [] };
+  const envPy = venvPython(envDir, platform);
+  const res = runner(envPy, [entryPath, ...entryArgs]);
+  if (!ranOk(res)) {
+    return {
+      ok: false,
+      messages: [`Entry check failed (${path.basename(entryPath)} ${entryArgs.join(' ')}): ${firstErrorLine(res)}`],
+    };
+  }
+  return { ok: true, messages: [`Verified entry: ${path.basename(entryPath)} runs.`] };
+}
+
+/**
+ * Full pipeline: detect → choose provisioner → create env → install → verify.
+ * This is the single call site the installer uses for ANY pack whose registry
+ * runtime includes "python" (seo, memory, …).
+ *
+ * Never throws for environmental problems — always returns
+ * { ok, tool, messages[] } so the installer can degrade gracefully and print
+ * guidance instead of aborting the whole install.
+ *
+ * @param {object} p
+ * @param {string} p.envDir                    e.g. path.join(projectDir, '.bmad', 'venv')
+ * @param {string|null} [p.requirementsPath]   pack requirements.txt (absolute)
+ * @param {string[]} [p.verifyModules]         modules that must import post-install
+ * @param {string|null} [p.entryPath]          entry script to smoke-run
+ * @param {string[]} [p.entryArgs]
+ * @param {Function} [p.runner]                injectable for tests
+ * @param {string} [p.platform]
+ * @param {Function} [p.fileExists]
+ * @param {{major:number,minor:number}} [p.minVersion]
+ * @returns {{ ok: boolean, tool: string|null, envDir: string, python: object|null, messages: string[] }}
+ */
+function provisionPack({
+  envDir,
+  requirementsPath = null,
+  verifyModules = [],
+  entryPath = null,
+  entryArgs = ['--help'],
+  runner = defaultRunner,
+  platform = process.platform,
+  fileExists = fs.existsSync,
+  minVersion = MIN_PYTHON,
+}) {
+  const messages = [];
+
+  if (!envDir) {
+    return { ok: false, tool: null, envDir: null, python: null, messages: ['provisionPack: envDir is required.'] };
+  }
+
+  // 1) provisioner first — uv can operate without a system Python.
+  const prov = detectProvisioner({ runner });
+  messages.push(...prov.messages);
+
+  // 2) interpreter
+  const py = detectPython({ runner, platform, minVersion });
+  messages.push(...py.messages);
+  if (!py.ok && prov.tool !== 'uv') {
+    return { ok: false, tool: prov.tool, envDir, python: null, messages };
+  }
+  if (!py.ok && prov.tool === 'uv') {
+    messages.push(`No system Python >= ${minVersion.major}.${minVersion.minor} — uv will download a managed interpreter.`);
+  }
+
+  // 3) create isolated env
+  const created = createEnv({ tool: prov.tool, python: py.command, envDir, runner, platform });
+  messages.push(...created.messages);
+  if (!created.ok) {
+    return { ok: false, tool: prov.tool, envDir, python: py.version, messages };
+  }
+
+  // 4) install requirements
+  const installed = installRequirements({
+    tool: prov.tool,
+    python: py.command,
+    envDir,
+    requirementsPath,
+    runner,
+    platform,
+    fileExists,
+  });
+  messages.push(...installed.messages);
+  if (!installed.ok) {
+    return { ok: false, tool: prov.tool, envDir, python: py.version, messages };
+  }
+
+  // 5) verify — a pack is only "installed" when its entry actually works.
+  const imports = verifyImports({ envDir, modules: verifyModules, runner, platform });
+  messages.push(...imports.messages);
+  if (!imports.ok) {
+    return { ok: false, tool: prov.tool, envDir, python: py.version, messages };
+  }
+
+  const entry = verifyEntry({ envDir, entryPath, entryArgs, runner, platform });
+  messages.push(...entry.messages);
+  if (!entry.ok) {
+    return { ok: false, tool: prov.tool, envDir, python: py.version, messages };
+  }
+
+  messages.push('Python runtime provisioned and verified.');
+  return { ok: true, tool: prov.tool, envDir, python: py.version, messages };
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Helpers
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** First non-empty diagnostic line from a runner result, for compact messages. */
+function firstErrorLine(res) {
+  if (!res) return 'no result';
+  if (res.error) return res.error;
+  const text = `${res.stderr}\n${res.stdout}`.split(/\r?\n/).map((l) => l.trim()).filter(Boolean);
+  return text.length > 0 ? text[text.length - 1] : `exit code ${res.status}`;
+}
+
+module.exports = {
+  MIN_PYTHON,
+  // pure
+  parsePythonVersion,
+  meetsMinVersion,
+  pythonCandidates,
+  chooseProvisioner,
+  venvPython,
+  buildEnvCommands,
+  missingPythonGuidance,
+  // side-effecting (injectable runner)
+  defaultRunner,
+  detectPython,
+  detectProvisioner,
+  createEnv,
+  installRequirements,
+  verifyImports,
+  verifyEntry,
+  provisionPack,
+};