machinaos 0.0.80 → 0.0.82

package/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, {

package/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__":

package/cli/supervisor.py

@@ -59,9 +59,19 @@ class ServiceSpec:
 
 
 def _full_env(spec_env: dict[str, str]) -> dict[str, str]:
-    """Inherit parent env + force-color so child output stays readable."""
+    """Inherit parent env + force-color so child output stays readable.
+
+    ``VIRTUAL_ENV`` is stripped: ``uv run`` resolves the project venv
+    via the workspace ``pyproject.toml`` and warns when an inherited
+    ``VIRTUAL_ENV`` points elsewhere (which it does whenever the user
+    has the root ``.venv`` activated in their shell and the spec runs
+    with ``cwd=server/``). The warning has no operational effect --
+    uv ignores ``VIRTUAL_ENV`` unless ``--active`` is passed -- so we
+    drop it at the source rather than teach every reader to ignore it.
+    """
+    inherited = {k: v for k, v in os.environ.items() if k != "VIRTUAL_ENV"}
     return {
-        **os.environ,
+        **inherited,
         "FORCE_COLOR": "1",
         "PYTHONUNBUFFERED": "1",
         **spec_env,

package/client/package.json

@@ -1,7 +1,7 @@
 {
   "name": "react-flow-client",
   "private": true,
-  "version": "0.0.80",
+  "version": "0.0.82",
   "type": "module",
   "scripts": {
     "start": "vite --host 0.0.0.0",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "machinaos",
-  "version": "0.0.80",
+  "version": "0.0.82",
   "description": "Open source workflow automation platform with AI agents, React Flow, and n8n-inspired architecture",
   "type": "module",
   "keywords": [
@@ -53,6 +53,7 @@
     "!**/node_modules/",
     "!**/.vite/",
     ".env.template",
+    "pyproject.toml",
     "README.md",
     "install.sh",
     "install.ps1"

package/pyproject.toml

@@ -0,0 +1,57 @@
+[project]
+name = "machinaos-cli"
+version = "0.1.0"
+description = "MachinaOS project supervisor CLI (machina)."
+requires-python = ">=3.12"
+dependencies = [
+    "typer>=0.12",
+    "rich>=13",
+    "anyio>=4",
+    "psutil>=6",
+    # OS-native user data / cache / config / log dirs. Soft dependency
+    # in the CLI (``cli/platform_.py`` imports it inside a try/except
+    # and falls back to a stdlib implementation if the wheel isn't
+    # available) so ``machina clean`` / ``machina build`` still work
+    # immediately after a wipe, before ``pip install`` has had a
+    # chance to materialise it.
+    "platformdirs>=4.0",
+    # Required on Windows for the supervisor's Job Object (cli/tree.py).
+    # Without it, child processes survive abnormal supervisor exit
+    # (SIGKILL, BSOD, console close) and accumulate as orphans across
+    # dev restarts. Floor 308 is the first release shipping prebuilt
+    # wheels for Python 3.13.
+    "pywin32>=308; platform_system == 'Windows'",
+]
+
+[project.scripts]
+machina = "cli.cli:app"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["cli"]
+
+# The CLI runs under the user's global / pipx-managed Python — it is
+# NOT a uv-managed project. ``managed = false`` tells ``uv`` to leave
+# this project alone: ``uv sync`` at the repo root is a no-op, no
+# ``<repo>/.venv/`` is created, ``python`` on PATH resolves to the
+# user's global interpreter instead of being shadowed by a workspace
+# venv. The server is the only uv-managed project (``server/.venv``).
+[tool.uv]
+managed = false
+
+[dependency-groups]
+dev = []
+
+# ``machinaos-cli`` is a standalone Python CLI package -- installable
+# via ``pipx install .`` / ``pip install .`` against any Python >=3.12
+# without involving uv. It depends on nothing from ``server/``. The
+# server has its own uv-managed venv at ``server/.venv``; the CLI
+# invokes server-side commands by shelling out via ``cli.run.uv_run``
+# (which runs ``uv run --no-sync ...`` with ``cwd=server/`` so uv
+# discovers ``server/pyproject.toml`` and activates ``server/.venv``).
+# Keeping the CLI independent of the uv workspace means contributors
+# can install / run / debug ``machina`` on whatever interpreter is on
+# PATH -- no per-checkout venv activation required.

package/scripts/install.js

@@ -23,12 +23,20 @@ const ROOT = resolve(__dirname, '..');
 process.env.PYTHONUTF8 = '1';
 
 function run(cmd, cwd = ROOT, timeoutMs = 300000) {
+  // Strip VIRTUAL_ENV from the spawned env. When the user runs
+  // ``npm install -g machinaos`` from a shell that has activated a
+  // venv (very common during dev), uv emits a noisy ``VIRTUAL_ENV
+  // ... does not match the project environment path`` warning per
+  // invocation. uv only honours VIRTUAL_ENV with ``--active``, which
+  // we never pass, so dropping it at the source is the documented
+  // workaround. Same fix applied to cli/supervisor.py's _full_env.
+  const { VIRTUAL_ENV, ...cleanEnv } = process.env;
   execSync(cmd, {
     cwd,
     stdio: 'inherit',
     shell: true,
     timeout: timeoutMs,
-    env: { ...process.env, MACHINAOS_INSTALLING: 'true' }
+    env: { ...cleanEnv, MACHINAOS_INSTALLING: 'true' }
   });
 }
 
@@ -148,7 +156,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 +210,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!');