Skip to content

Self-improving AI Employees for everyone

fix(cli): bootstrap CLI runtime deps via uv venv (PEP 668 fix)

trohitgd2741e785288
diff --git a/.gitignore b/.gitignore
index 25056bc9..13c2b93c 100644
--- a/.gitignore
+++ b/.gitignore
@@ -102,6 +102,7 @@ build/
# =============================================================================
.venv/
venv/
+.cli-venv/
*.egg-info/
.eggs/
diff --git a/bin/cli.js b/bin/cli.js
index 820bb67c..a071b639 100755
--- a/bin/cli.js
+++ b/bin/cli.js
@@ -3,7 +3,7 @@
import { spawn, execSync } from 'child_process';
import { dirname, resolve } from 'path';
import { fileURLToPath } from 'url';
-import { readFileSync } from 'fs';
+import { readFileSync, existsSync } from 'fs';
const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
const PKG = JSON.parse(readFileSync(resolve(ROOT, 'package.json'), 'utf-8'));
@@ -126,7 +126,33 @@ function doctor() {
console.log('');
}
+// Resolve <ROOT>/.cli-venv Python if the postinstall step provisioned it.
+// Returns null on source checkouts (no venv -> fall back to ``npm run``).
+function venvPython() {
+ const py = process.platform === 'win32'
+ ? resolve(ROOT, '.cli-venv', 'Scripts', 'python.exe')
+ : resolve(ROOT, '.cli-venv', 'bin', 'python');
+ return existsSync(py) ? py : null;
+}
+
function run(script, extraArgs = []) {
+ // Global-install fast path: spawn the venv's Python directly with
+ // ``-m cli <cmd>``. Skips the ``npm run`` shim that previously re-
+ // resolved the system ``python`` (which on PEP 668 systems lacks
+ // the CLI runtime deps -- typer/rich/anyio/psutil). The npm-run
+ // path stays as the source-checkout fallback (``pnpm run start``
+ // uses package.json scripts directly).
+ const venvPy = venvPython();
+ if (venvPy) {
+ const child = spawn(venvPy, ['-m', 'cli', script, ...extraArgs], {
+ cwd: ROOT,
+ stdio: 'inherit',
+ });
+ child.on('error', (e) => { console.error(`Failed: ${e.message}`); process.exit(1); });
+ child.on('close', (code) => process.exit(code || 0));
+ return;
+ }
+
const npmArgs = ['run', script];
if (extraArgs.length) npmArgs.push('--', ...extraArgs);
const child = spawn(process.platform === 'win32' ? 'npm.cmd' : 'npm', npmArgs, {
diff --git a/cli/__main__.py b/cli/__main__.py
index 51005b2e..5945f2a8 100644
--- a/cli/__main__.py
+++ b/cli/__main__.py
@@ -1,38 +1,110 @@
"""Entry point for ``python -m cli``.
-pnpm scripts call ``python -m cli ...`` from the system Python,
-which only has ``uv`` -- not typer / rich / anyio / psutil. On first
-run we detect the missing imports, pip-install the declared runtime
-deps, and retry, so the user never has to ``pip install -e .`` by hand.
-
-The public CLI command is still ``machina`` (the user-facing name);
-``cli`` is just the Python import path after the
-``<repo>/machina/ → <repo>/cli/`` source-dir rename.
+The npm package ships the ``cli/`` source directory without its
+runtime dependencies (``typer`` / ``rich`` / ``anyio`` / ``psutil`` /
+``platformdirs`` / ``pywin32`` on Windows). The previous bootstrap
+``pip install``ed them against ``sys.executable``, which fails on any
+modern PEP 668 distro (Ubuntu 24.04+, Debian 12+, Homebrew Python,
+NixOS) with ``error: externally-managed-environment``.
+
+Fix: provision a private venv at ``<package_root>/.cli-venv`` via
+``uv`` (a hard install dependency verified by ``scripts/install.js``)
+and re-exec under that venv's Python. ``uv pip install`` operates
+inside the venv -- PEP 668 only governs the system interpreter, so
+this is the canonical workaround documented by
+https://peps.python.org/pep-0668/#guide-users-towards-virtual-environments.
+
+``scripts/install.js`` provisions the same venv at postinstall time,
+so end users never pay the first-run latency. This module is the
+fallback for the source-checkout / broken-install path.
"""
+from __future__ import annotations
+
+import os
+import shutil
import subprocess
import sys
+from pathlib import Path
+
+_ROOT = Path(__file__).resolve().parent.parent
+_VENV_DIR = _ROOT / ".cli-venv"
+
+
+def _venv_python() -> Path:
+ """Platform-specific path to the venv's Python interpreter."""
+ if sys.platform == "win32":
+ return _VENV_DIR / "Scripts" / "python.exe"
+ return _VENV_DIR / "bin" / "python"
-_RUNTIME_DEPS = (
- "typer>=0.12",
- "rich>=13",
- "anyio>=4",
- "psutil>=6",
-)
+def _running_under_venv() -> bool:
+ """True if ``sys.executable`` is already the CLI venv's Python.
-def _bootstrap_deps() -> None:
- print("machina: installing runtime dependencies (first run)...", file=sys.stderr)
- subprocess.check_call(
- [sys.executable, "-m", "pip", "install", "--quiet", *_RUNTIME_DEPS]
- )
+ Guards against infinite re-exec loops when the venv's interpreter
+ itself can't import the deps (would mean ``uv pip install`` was
+ silently no-op'd -- a real bug worth surfacing, not retrying).
+ """
+ try:
+ return Path(sys.executable).resolve() == _venv_python().resolve()
+ except (OSError, ValueError):
+ return False
+
+
+def _provision_venv() -> Path | None:
+ """Create ``<ROOT>/.cli-venv`` and install CLI deps via ``uv``.
+
+ Returns the venv's Python path on success, ``None`` if ``uv`` is
+ missing or the install fails. Output is inherited (not captured)
+ so the user sees ``uv``'s progress + any error context.
+ """
+ uv = shutil.which("uv")
+ if not uv:
+ return None
+ try:
+ if not _venv_python().exists():
+ print(
+ "machina: provisioning CLI runtime venv (first run)...",
+ file=sys.stderr,
+ )
+ subprocess.check_call([uv, "venv", "--quiet", str(_VENV_DIR)])
+ subprocess.check_call(
+ [
+ uv,
+ "pip",
+ "install",
+ "--quiet",
+ "--python",
+ str(_venv_python()),
+ "-e",
+ str(_ROOT),
+ ]
+ )
+ except subprocess.CalledProcessError:
+ return None
+ return _venv_python() if _venv_python().exists() else None
+
+
+def _reexec_in_venv() -> None:
+ """Provision the venv if needed, then re-exec ``python -m cli`` under it."""
+ venv_py = _venv_python() if _venv_python().exists() else _provision_venv()
+ if not venv_py:
+ sys.stderr.write(
+ "machina: runtime dependencies are missing and the CLI venv\n"
+ " could not be provisioned. Install uv\n"
+ " (https://docs.astral.sh/uv/getting-started/installation/)\n"
+ " and re-run, or run `machina build` to regenerate the venv.\n"
+ )
+ sys.exit(1)
+ os.execv(str(venv_py), [str(venv_py), "-m", "cli", *sys.argv[1:]])
try:
from cli.cli import app
except ImportError:
- _bootstrap_deps()
- from cli.cli import app
+ if _running_under_venv():
+ raise
+ _reexec_in_venv()
if __name__ == "__main__":
diff --git a/scripts/install.js b/scripts/install.js
index d141095b..37890e3e 100755
--- a/scripts/install.js
+++ b/scripts/install.js
@@ -148,7 +148,7 @@ try {
// Calculate total steps
let totalSteps = 1; // .env always
if (!clientDistExists) totalSteps += 2; // client deps + build
- totalSteps += 2; // Python deps + bytecode compile
+ totalSteps += 3; // Python deps + bytecode compile + CLI venv
let step = 0;
// Create .env if needed
@@ -202,6 +202,24 @@ try {
console.log(` Warning: bytecode compilation failed (non-fatal): ${err.message}`);
}
+ // Provision a private venv for the CLI runtime deps (typer, rich,
+ // anyio, psutil, platformdirs, pywin32-on-Windows). ``python -m cli``
+ // re-execs itself under this venv (see ``cli/__main__.py``), so the
+ // system Python never needs the deps -- avoids the PEP 668
+ // ``externally-managed-environment`` failure on Ubuntu 24.04+,
+ // Debian 12+, Homebrew Python, NixOS, etc.
+ // (https://peps.python.org/pep-0668/)
+ step++;
+ console.log(`[${step}/${totalSteps}] Provisioning CLI runtime venv...`);
+ const cliVenvDir = resolve(ROOT, '.cli-venv');
+ const cliVenvPython = process.platform === 'win32'
+ ? resolve(cliVenvDir, 'Scripts', 'python.exe')
+ : resolve(cliVenvDir, 'bin', 'python');
+ if (!existsSync(cliVenvPython)) {
+ run(`uv venv "${cliVenvDir}"`, ROOT);
+ }
+ run(`uv pip install --python "${cliVenvPython}" --quiet -e .`, ROOT);
+
// WhatsApp RPC is now an npm dependency - binary downloaded via postinstall
console.log('');
console.log('Done!');