Skip to content

Self-improving AI Employees for everyone

refactor(cli): make machina clean recovery-resilient + extract _common helpers

trohitg18e0522456a9
diff --git a/cli/_common.py b/cli/_common.py
new file mode 100644
index 00000000..789986fb
--- /dev/null
+++ b/cli/_common.py
@@ -0,0 +1,115 @@
+"""Cross-verb helpers shared by ``machina`` commands.
+
+Centralises the four patterns that previously appeared inlined in
+``start.py`` / ``dev.py`` / ``stop.py`` / ``clean.py`` / ``build.py``:
+
+ - :func:`preflight` -- ``load_config()`` + ``project_root()``
+ preamble every verb opens with.
+ - :func:`free_all_ports` -- ``for port in cfg.all_ports: kill_port``
+ loop; lazy-imports ``cli.ports`` so a
+ broken ``psutil`` install doesn't take
+ down the recovery verb.
+ - :func:`build_backend_spec` -- the shared ``uv_run("uvicorn", ...)``
+ ServiceSpec used by both ``start``
+ and ``dev``.
+ - :func:`error_block` -- multi-line ``[red]Error: ...[/]``
+ formatter; lazy-imports ``cli.colors``.
+
+No third-party packages are imported at module load time. Importing
+this module from ``cli/commands/clean.py`` is safe even when
+``rich`` / ``psutil`` / ``platformdirs`` are missing -- only the
+helper that actually needs the dep pulls it in.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from cli.config import Config, load_config
+from cli.platform_ import project_root, server_dir
+
+if TYPE_CHECKING:
+ from cli.ports import KillResult
+ from cli.supervisor import ServiceSpec
+
+# ``cli.run`` (and ``cli.supervisor`` via ``cli.colors``) transitively
+# pull in ``rich``. They're only needed by ``build_backend_spec`` /
+# ``error_block`` which themselves lazy-import. Keeping them out of the
+# top-level import list means ``machina clean`` (which calls only
+# ``preflight`` and ``free_all_ports``) loads even when ``rich`` /
+# ``psutil`` / ``platformdirs`` are unavailable.
+
+
+def preflight(cfg: Config | None = None) -> tuple[Config, Path]:
+ """Standard verb preamble: ``(load_config(), project_root())``.
+
+ Pass an explicit ``cfg`` to avoid the lookup (e.g. when the caller
+ already has one). ``load_config`` is ``@lru_cache``d, so repeated
+ calls inside the same process are free regardless.
+ """
+ return cfg or load_config(), project_root()
+
+
+def free_all_ports(cfg: Config) -> list[KillResult]:
+ """Kill anything listening on ``cfg.all_ports``; return per-port
+ results.
+
+ Returns a list (not a count) so callers can render per-port status
+ -- ``machina stop`` shows ``[OK]`` / ``[!!]`` markers and the killed
+ PIDs, ``machina start`` and ``clean`` just want them gone. The
+ helper centralises the iteration, callers pick the rendering.
+
+ ``cli.ports`` is imported lazily so this module loads even when
+ ``psutil`` (a transitive dep) is missing -- important for the
+ recovery verb ``machina clean``.
+ """
+ from cli.ports import kill_port
+ return [kill_port(port) for port in cfg.all_ports]
+
+
+def build_backend_spec(
+ cfg: Config,
+ *,
+ host: str,
+ root: Path | None = None,
+) -> "ServiceSpec":
+ """The Python backend ``ServiceSpec`` shared by ``start`` and ``dev``.
+
+ Routes through :func:`cli.run.uv_run` so the standardised
+ ``uv run --no-sync`` flags stay in one place. ``host`` is the only
+ differentiator (``start`` picks ``127.0.0.1`` on Windows/WSL vs
+ ``0.0.0.0`` elsewhere; ``dev`` honours its ``--daemon`` flag).
+
+ ``cli.run`` and ``cli.supervisor`` are lazy-imported so this module
+ stays importable when their transitive ``rich`` dep is missing --
+ ``machina clean`` doesn't call this and shouldn't pay for it.
+ """
+ from cli.run import uv_run
+ from cli.supervisor import ServiceSpec
+ return ServiceSpec(
+ name="server",
+ argv=uv_run(
+ "uvicorn", "main:app",
+ "--host", host,
+ "--port", str(cfg.backend_port),
+ "--log-level", "warning",
+ ),
+ cwd=server_dir(root),
+ ready_port=cfg.backend_port,
+ )
+
+
+def error_block(title: str, lines: list[str]) -> None:
+ """Print a multi-line ``[red]Error: ...[/]`` block, indented body.
+
+ ``cli.colors`` is imported lazily so this module remains
+ importable without ``rich``. Anything heavier (e.g., remediation
+ URLs, code snippets) goes in ``lines`` -- it's rendered as plain
+ ``console.print`` calls so rich BBCode in callers' strings still
+ interprets.
+ """
+ from cli.colors import console
+ console.print(f"[red]Error: {title}[/]")
+ for line in lines:
+ console.print(f" {line}")
diff --git a/cli/buildenv.py b/cli/buildenv.py
index 52bf1e71..900182ac 100644
--- a/cli/buildenv.py
+++ b/cli/buildenv.py
@@ -1,8 +1,14 @@
"""Build-environment helpers shared by ``start`` / ``dev`` / ``daemon``.
-Three commands had near-duplicate copies of "find the venv python" and
-"the build artifacts must exist or refuse to start". Lifted here so a
-new launcher gets both for free.
+``validate_build`` refuses to launch when ``machina build`` hasn't been
+run. Layout knowledge lives in :mod:`cli.platform_` -- this file only
+composes the documented prefixes (workspace venv, node_modules, client
+dist) into a boolean check.
+
+Subprocess callers (start / dev / daemon / temporal specs) build their
+argv via :func:`cli.run.uv_run`, which runs the command inside the uv
+workspace ``.venv`` per https://docs.astral.sh/uv/reference/cli/#uv-run.
+There is no path-to-interpreter logic on the CLI side -- uv owns that.
"""
from __future__ import annotations
@@ -12,21 +18,11 @@ from pathlib import Path
import typer
from cli.colors import console
-
-
-def venv_python(root: Path) -> Path | None:
- """Return the project's venv python path, or ``None`` if absent.
-
- Tries the Windows layout first (``Scripts/python.exe``) then POSIX
- (``bin/python``); the first existing path wins.
- """
- for candidate in (
- root / "server" / ".venv" / "Scripts" / "python.exe",
- root / "server" / ".venv" / "bin" / "python",
- ):
- if candidate.exists():
- return candidate
- return None
+from cli.platform_ import (
+ client_dist_entry,
+ node_modules_dir,
+ server_venv,
+)
def validate_build(root: Path, *, require_client_dist: bool = False) -> None:
@@ -36,9 +32,9 @@ def validate_build(root: Path, *, require_client_dist: bool = False) -> None:
missing ``client/dist`` (Vite serves the source); ``start`` opts in
via ``require_client_dist=True``.
"""
- if not (root / "node_modules").exists() or not (root / "server" / ".venv").exists():
+ if not node_modules_dir(root).exists() or not server_venv(root).exists():
console.print('[red]Error: Project not built. Run "machina build" first.[/]')
raise typer.Exit(code=1)
- if require_client_dist and not (root / "client" / "dist" / "index.html").exists():
+ if require_client_dist and not client_dist_entry(root).exists():
console.print('[red]Error: Client not built. Run "machina build" first.[/]')
raise typer.Exit(code=1)
diff --git a/cli/commands/_temporal_specs.py b/cli/commands/_temporal_specs.py
index 1d4ca0a6..37bb6f54 100644
--- a/cli/commands/_temporal_specs.py
+++ b/cli/commands/_temporal_specs.py
@@ -8,7 +8,8 @@ Returns the right Temporal ``ServiceSpec`` set based on
- ``postgres`` (default) — two specs running the supervised runtimes:
``temporal-postgres`` (pgserver) then ``temporal-server`` (Temporal
binary with YAML config). Both wrap ``BaseSupervisor`` singletons
- via ``cli.commands._supervised_runtime``. Data lands under
+ via ``services.temporal._supervised_runtime`` (a thin shim that
+ lives next to the runtime factories it imports). Data lands under
``DATA_DIR/postgres/``; binaries come from a pooch-managed cache
(no system install required).
@@ -32,6 +33,8 @@ from __future__ import annotations
import os
from pathlib import Path
+from cli.platform_ import server_dir
+from cli.run import uv_run
from cli.supervisor import RestartPolicy, ServiceSpec
# Backend names — must match ``core.config.Settings.temporal_backend``
@@ -65,12 +68,18 @@ _GRACE_SECONDS = float(
def _runtime_argv(factory_path: str) -> list[str]:
"""Build the argv for one BaseSupervisor singleton, invoked via the
generic supervised-runtime shim. ``factory_path`` is the dotted
- ``module:attr`` accessor."""
- return [
- "uv", "run", "python", "-m",
- "cli.commands._supervised_runtime",
+ ``module:attr`` accessor.
+
+ Composes the uv invocation through :func:`cli.run.uv_run` so every
+ ``uv run --no-sync`` callsite in the CLI shares the same flag set.
+ The shim itself lives at ``services.temporal._supervised_runtime``
+ (next to the runtime factories), so the spawned python only needs
+ to resolve modules out of the workspace ``.venv``.
+ """
+ return uv_run(
+ "python", "-m", "services.temporal._supervised_runtime",
factory_path,
- ]
+ )
def temporal_specs(root: Path, cfg) -> list[ServiceSpec]:
@@ -81,14 +90,14 @@ def temporal_specs(root: Path, cfg) -> list[ServiceSpec]:
readiness probe (same port for both ``sqlite`` and ``postgres``).
"""
backend = cfg.temporal_backend.strip().lower()
- server_dir = root / "server"
+ server_cwd = server_dir(root)
if backend == _BACKEND_POSTGRES:
return [
ServiceSpec(
name="postgres",
argv=_runtime_argv("services.temporal._runtime:get_postgres_runtime"),
- cwd=server_dir,
+ cwd=server_cwd,
# pgserver picks a dynamic port; skip the TCP probe here
# and rely on the temporal spec to gate readiness via
# gRPC (it can't connect until Postgres accepts).
@@ -102,7 +111,7 @@ def temporal_specs(root: Path, cfg) -> list[ServiceSpec]:
argv=_runtime_argv(
"services.temporal._runtime:get_temporal_server_runtime",
),
- cwd=server_dir,
+ cwd=server_cwd,
ready_port=cfg.temporal_port,
ready_timeout=_SERVER_READY_TIMEOUT_SECONDS,
restart=RestartPolicy.ON_CRASH,
@@ -122,7 +131,7 @@ def temporal_specs(root: Path, cfg) -> list[ServiceSpec]:
argv=_runtime_argv(
"services.temporal._runtime:get_temporal_server_runtime",
),
- cwd=server_dir,
+ cwd=server_cwd,
ready_port=cfg.temporal_port,
ready_timeout=_SERVER_READY_TIMEOUT_SECONDS,
restart=RestartPolicy.ON_CRASH,
diff --git a/cli/commands/clean.py b/cli/commands/clean.py
index c9c25cad..086cbb4f 100644
--- a/cli/commands/clean.py
+++ b/cli/commands/clean.py
@@ -1,8 +1,16 @@
-"""``machina clean`` — reset the repo to a fresh-checkout state.
-
-Stops every process listening on the configured ports + orphaned project
-processes, waits for file locks to release, then removes build artefacts
-and venvs.
+"""``machina clean`` -- reset the repo to a fresh-checkout state.
+
+Recovery verb: must work even when the env is partially broken
+(missing ``rich`` / ``psutil`` / ``platformdirs`` wheels, half-wiped
+``server/.venv``, etc.). Everything at module load is stdlib + first-party
+helpers (``cli._common`` / ``cli.config`` / ``cli.platform_``). The
+process-killing step (which needs ``psutil`` via :mod:`cli.ports`) is
+lazy-imported inside :func:`clean_command` and degrades to a warning
+if the wheel is missing -- file removal continues regardless.
+
+Stops every process listening on the configured ports + orphaned
+project processes, waits for file locks to release, then removes build
+artefacts and venvs.
"""
from __future__ import annotations
@@ -11,10 +19,7 @@ import shutil
import time
from pathlib import Path
-from cli.colors import console
-from cli.config import load_config
-from cli.platform_ import project_root
-from cli.ports import kill_orphaned_machina_processes, kill_port
+from cli._common import free_all_ports, preflight
# Removed each run -- order doesn't matter, ``shutil.rmtree`` is recursive.
@@ -26,19 +31,22 @@ _TARGETS = [
"client/node_modules",
"client/dist",
"client/.vite",
- # Python venvs
+ # Python venvs. ``server/.venv`` is uv's default location for the
+ # server's standalone project. ``.venv`` at the repo root is a
+ # leftover from the brief workspace-layout experiment -- harmless
+ # to wipe alongside if present.
"server/.venv",
- ".venv", # stale root venv (should not exist)
+ ".venv",
]
# Children of ``<repo>/.machina/`` to wipe selectively. The bare
# ``.machina`` entry can't go in ``_TARGETS`` anymore because the
# ``workflows/`` subtree holds shipped example seeds (git-tracked,
-# imported on first launch by ``services.example_loader``) — wiping it
-# would force the operator to re-clone to recover. Anything else under
-# ``.machina/`` (claude state, workspaces, credentials.db, …) is
-# transient runtime state and is fair game.
+# imported on first launch by ``services.example_loader``) -- wiping
+# it would force the operator to re-clone to recover. Anything else
+# under ``.machina/`` (claude state, workspaces, credentials.db, ...)
+# is transient runtime state and is fair game.
_MACHINA_KEEP = frozenset({"workflows"})
@@ -50,52 +58,69 @@ def _rmtree_with_retry(path: Path, *, attempts: int = 3, delay: float = 0.1) ->
return True
except OSError as exc:
if attempt == attempts - 1:
- console.print(f" [yellow]Warning: Could not remove {path.name}: {exc}[/]")
+ print(f" warning: could not remove {path.name}: {exc}")
return False
time.sleep(delay)
return False
-def clean_command() -> None:
- cfg = load_config()
- root = project_root()
-
- console.print("[bold]Cleaning MachinaOS...[/]\n")
+def _kill_running_processes(cfg, root: Path) -> bool:
+ """Best-effort: kill anything on configured ports + orphaned project
+ processes. Returns True if anything was killed (so the caller knows
+ to wait for file locks to release before deleting directories).
+
+ The process-killing path needs ``psutil`` (via :mod:`cli.ports`). If
+ it isn't importable -- partially broken env -- we print a warning
+ and skip; the directory-removal step still runs.
+ """
+ try:
+ results = free_all_ports(cfg)
+ # ``free_all_ports`` itself lazy-imports ``cli.ports`` -- the
+ # outer try/except catches the ImportError if psutil is gone.
+ from cli.ports import kill_orphaned_machina_processes
+ except ImportError as exc:
+ print(f" warning: psutil unavailable ({exc.name}); skipping process cleanup")
+ return False
- # Step 1: kill anything on configured ports
- console.print("Stopping running processes...")
killed_ports = 0
- for port in cfg.all_ports:
- result = kill_port(port)
+ for port, result in zip(cfg.all_ports, results):
if result.killed_pids:
- console.print(f" Port {port}: Killed {len(result.killed_pids)} process(es)")
+ print(f" port {port}: killed {len(result.killed_pids)} process(es)")
killed_ports += len(result.killed_pids)
- # Step 2: kill orphaned project processes (may hold .venv file locks).
- # ``exclude_substring="-m cli"`` skips the supervisor running this
- # very ``clean`` command — its cmdline contains the entry-point
- # token ``-m cli``.
orphaned = kill_orphaned_machina_processes(str(root), exclude_substring="-m cli")
if orphaned:
- console.print(f" Orphaned: Killed {len(orphaned)} process(es)")
+ print(f" orphaned: killed {len(orphaned)} process(es)")
+
+ return bool(killed_ports or orphaned)
+
+
+def clean_command() -> None:
+ cfg, root = preflight()
+
+ print("Cleaning MachinaOS...")
- if killed_ports or orphaned:
- console.print(" Waiting for processes to release file locks...")
+ # Step 1+2: kill running processes (best-effort, may degrade)
+ print("Stopping running processes...")
+ killed_any = _kill_running_processes(cfg, root)
+ if killed_any:
+ print(" waiting for processes to release file locks...")
time.sleep(1.0)
else:
- console.print(" No running processes found.")
+ print(" no running processes found.")
- # Step 3: remove directories
- console.print("\nRemoving directories...")
+ # Step 3: remove top-level artefact directories
+ print()
+ print("Removing directories...")
for target in _TARGETS:
path = root / target
if path.exists():
- console.print(f" Removing: {target}")
+ print(f" removing: {target}")
_rmtree_with_retry(path)
- # Step 4: selectively clean ``<repo>/.machina/`` — preserve
+ # Step 4: selectively clean ``<repo>/.machina/`` -- preserve
# ``workflows/`` (shipped example seeds, see ``_MACHINA_KEEP``);
- # wipe everything else (claude/, workspaces/, *.db, …) so the
+ # wipe everything else (claude/, workspaces/, *.db, ...) so the
# repo-local DATA_DIR opt-out gets the same fresh-state treatment.
machina_dir = root / ".machina"
if machina_dir.is_dir():
@@ -103,13 +128,14 @@ def clean_command() -> None:
if child.name in _MACHINA_KEEP:
continue
rel = f".machina/{child.name}"
- console.print(f" Removing: {rel}")
+ print(f" removing: {rel}")
if child.is_dir():
_rmtree_with_retry(child)
else:
try:
child.unlink()
except OSError as exc:
- console.print(f" [yellow]Warning: Could not remove {rel}: {exc}[/]")
+ print(f" warning: could not remove {rel}: {exc}")
- console.print("\n[green]Done.[/]")
+ print()
+ print("Done.")
diff --git a/cli/commands/daemon.py b/cli/commands/daemon.py
deleted file mode 100644
index 610d0017..00000000
--- a/cli/commands/daemon.py
+++ /dev/null
@@ -1,147 +0,0 @@
-"""``machina daemon`` -- run the backend as a detached process.
-
-Pure-Python, all-platforms. No NSSM / systemd / launchd integration.
-Spawns ``uvicorn main:app`` in a new session (POSIX) or detached
-process group (Windows), writes the PID under ``~/.machina/`` so the
-other verbs can find it, and uses ``psutil`` for tree-kill on stop.
-
-For boot-time auto-start, configure your OS service manager
-separately (`systemctl`, `launchctl`, Task Scheduler) -- this CLI does
-not register itself with the system.
-"""
-
-from __future__ import annotations
-
-import subprocess
-from pathlib import Path
-
-import psutil
-import typer
-
-from cli.buildenv import venv_python
-from cli.colors import console
-from cli.platform_ import IS_WINDOWS, project_root
-
-app = typer.Typer(
- name="daemon",
- help="Run the MachinaOs backend as a detached process.",
- no_args_is_help=True,
- add_completion=False,
-)
-
-
-# ---------------------------------------------------------------- helpers
-
-_PID_DIR = Path.home() / ".machina"
-_PID_FILE = _PID_DIR / "machina-backend.pid"
-
-
-def _detached_kwargs() -> dict:
- """Cross-platform "spawn detached, survive parent exit" kwargs."""
- if IS_WINDOWS:
- # CREATE_NEW_PROCESS_GROUP lets us send CTRL_BREAK_EVENT later;
- # DETACHED_PROCESS releases the console handle.
- return {
- "creationflags": (
- subprocess.DETACHED_PROCESS | subprocess.CREATE_NEW_PROCESS_GROUP
- ),
- }
- # POSIX: setsid puts the child in its own process group / session,
- # so killing the parent (this CLI) doesn't take the daemon down.
- return {"start_new_session": True}
-
-
-def _read_pid() -> int | None:
- if not _PID_FILE.exists():
- return None
- try:
- pid = int(_PID_FILE.read_text().strip())
- except (ValueError, OSError):
- return None
- return pid if psutil.pid_exists(pid) else None
-
-
-def _kill_tree(pid: int) -> None:
- try:
- proc = psutil.Process(pid)
- except psutil.NoSuchProcess:
- return
- for child in proc.children(recursive=True):
- try:
- child.kill()
- except psutil.NoSuchProcess:
- pass
- try:
- proc.terminate()
- proc.wait(timeout=5)
- except psutil.NoSuchProcess:
- return
- except psutil.TimeoutExpired:
- try:
- proc.kill()
- except psutil.NoSuchProcess:
- pass
-
-
-# ---------------------------------------------------------------- verbs
-
-
-def start_command() -> None:
- """Start the backend in the background; write PID to ~/.machina/."""
- if (existing := _read_pid()) is not None:
- console.print(f"[yellow]Already running (pid={existing}).[/]")
- return
-
- root = project_root()
- server = root / "server"
- py = venv_python(root)
- if py is None:
- console.print(f'[red]Python venv not found at {py}.[/] Run "machina build" first.')
- raise typer.Exit(code=1)
-
- _PID_DIR.mkdir(parents=True, exist_ok=True)
- log_file = _PID_DIR / "backend.log"
- log = log_file.open("ab")
-
- proc = subprocess.Popen(
- [str(py), "-m", "uvicorn", "main:app",
- "--host", "0.0.0.0", "--port", "3010", "--log-level", "warning"],
- cwd=str(server),
- stdin=subprocess.DEVNULL,
- stdout=log,
- stderr=log,
- **_detached_kwargs(),
- )
- _PID_FILE.write_text(str(proc.pid))
- console.print(f"[green]Started pid={proc.pid}[/] (logs: {log_file})")
-
-
-def stop_command() -> None:
- """Stop the backend if running; clear PID file."""
- pid = _read_pid()
- if pid is None:
- console.print("Not running.")
- _PID_FILE.unlink(missing_ok=True)
- return
- _kill_tree(pid)
- _PID_FILE.unlink(missing_ok=True)
- console.print(f"[green]Stopped pid={pid}[/]")
-
-
-def status_command() -> None:
- """Report whether the backend is running."""
- pid = _read_pid()
- if pid is None:
- console.print("Not running.")
- raise typer.Exit(code=1)
- console.print(f"[green]Running pid={pid}[/]")
-
-
-def restart_command() -> None:
- """Stop then start; convenience wrapper."""
- stop_command()
- start_command()
diff --git a/cli/commands/daemon/__init__.py b/cli/commands/daemon/__init__.py
new file mode 100644
index 00000000..ee295c49
--- /dev/null
+++ b/cli/commands/daemon/__init__.py
@@ -0,0 +1,47 @@
+"""``machina daemon`` -- run the backend as a detached process.
+
+Pure-Python, all-platforms. No NSSM / systemd / launchd integration.
+Spawns ``uvicorn main:app`` in a new session (POSIX) or detached
+process group (Windows), writes the PID under the project's
+user-data dir (see :func:`cli.platform_.user_data_dir`), and uses
+``psutil`` for tree-kill on stop.
+
+Package layout (verb-per-file, following pdm's ``commands/venv/`` and
+hatch's per-verb-folder convention):
+
+ - :mod:`._state` -- ``pid_dir`` / ``pid_file`` / ``read_pid`` /
+ ``kill_tree`` / ``detached_kwargs`` (lazy --
+ no module-level side effects)
+ - :mod:`.start` -- ``daemon start`` verb
+ - :mod:`.stop` -- ``daemon stop`` verb
+ - :mod:`.status` -- ``daemon status`` verb
+ - :mod:`.restart` -- ``daemon restart`` verb
+
+For boot-time auto-start, configure your OS service manager separately
+(``systemctl``, ``launchctl``, Task Scheduler) -- this CLI does not
+register itself with the system.
+"""
+
+from __future__ import annotations
+
+import typer
+
+# The ``app`` Typer instance is declared FIRST so the verb modules can
+# import it via ``from . import app`` and register themselves via
+# ``@app.command``. The verb-module imports BELOW are what trigger that
+# registration -- without them, ``machina daemon`` would be empty.
+app = typer.Typer(
+ name="daemon",
+ help="Run the MachinaOs backend as a detached process.",
+ no_args_is_help=True,
+ add_completion=False,
+)
+
+# Import order matters only for ``restart`` (which imports ``start_command``
+# + ``stop_command``); list those two first for clarity, then the rest.
+from . import start # noqa: E402,F401
+from . import stop # noqa: E402,F401
+from . import status # noqa: E402,F401
+from . import restart # noqa: E402,F401
+
+__all__ = ["app"]
diff --git a/cli/commands/daemon/_state.py b/cli/commands/daemon/_state.py
new file mode 100644
index 00000000..6aaa306a
--- /dev/null
+++ b/cli/commands/daemon/_state.py
@@ -0,0 +1,97 @@
+"""Shared state for the ``machina daemon`` verbs.
+
+PID-file location, detached-spawn kwargs, and the ``psutil``-backed
+tree-kill helper that ``start`` / ``stop`` / ``status`` / ``restart``
+all need. Lives in its own module so each verb file imports only what
+it uses -- no module-level side effects (the PID-dir resolution
+happens inside :func:`pid_dir`, not at import time, so importing this
+module is cheap and doesn't depend on ``platformdirs`` being available
+until the verb actually runs).
+"""
+
+from __future__ import annotations
+
+import subprocess
+from pathlib import Path
+
+import psutil
+
+from cli.platform_ import IS_WINDOWS, user_data_dir
+
+
+_PID_FILENAME = "machina-backend.pid"
+_LOG_FILENAME = "backend.log"
+
+
+def pid_dir() -> Path:
+ """Project's user-data directory -- created on demand by callers."""
+ return user_data_dir()
+
+
+def pid_file() -> Path:
+ """Path to the daemon's PID file."""
+ return pid_dir() / _PID_FILENAME
+
+
+def log_file() -> Path:
+ """Path to the daemon's stdout/stderr log file."""
+ return pid_dir() / _LOG_FILENAME
+
+
+def detached_kwargs() -> dict:
+ """Cross-platform "spawn detached, survive parent exit" kwargs.
+
+ Windows: ``CREATE_NEW_PROCESS_GROUP`` enables later ``CTRL_BREAK_EVENT``;
+ ``DETACHED_PROCESS`` releases the console handle.
+ POSIX: ``start_new_session`` puts the child in its own session, so
+ killing the parent (this CLI) doesn't take the daemon down.
+ """
+ if IS_WINDOWS:
+ return {
+ "creationflags": (
+ subprocess.DETACHED_PROCESS | subprocess.CREATE_NEW_PROCESS_GROUP
+ ),
+ }
+ return {"start_new_session": True}
+
+
+def read_pid() -> int | None:
+ """Return the live PID from the PID file, or ``None`` if absent /
+ corrupt / process no longer exists."""
+ pf = pid_file()
+ if not pf.exists():
+ return None
+ try:
+ pid = int(pf.read_text().strip())
+ except (ValueError, OSError):
+ return None
+ return pid if psutil.pid_exists(pid) else None
+
+
+def kill_tree(pid: int) -> None:
+ """Terminate ``pid`` and all of its descendants. Best-effort.
+
+ Children are killed first, then the parent is terminated with a
+ 5-second grace period; falls back to SIGKILL if the parent doesn't
+ exit in time. Matches the supervisor's two-phase shutdown
+ semantics.
+ """
+ try:
+ proc = psutil.Process(pid)
+ except psutil.NoSuchProcess:
+ return
+ for child in proc.children(recursive=True):
+ try:
+ child.kill()
+ except psutil.NoSuchProcess:
+ pass
+ try:
+ proc.terminate()
+ proc.wait(timeout=5)
+ except psutil.NoSuchProcess:
+ return
+ except psutil.TimeoutExpired:
+ try:
+ proc.kill()
+ except psutil.NoSuchProcess:
+ pass
diff --git a/cli/commands/daemon/restart.py b/cli/commands/daemon/restart.py
new file mode 100644
index 00000000..252ecd4e
--- /dev/null
+++ b/cli/commands/daemon/restart.py
@@ -0,0 +1,14 @@
+"""``machina daemon restart`` -- stop then start."""
+
+from __future__ import annotations
+
+from . import app
+from .start import start_command
+from .stop import stop_command
+
+
+def restart_command() -> None:
+ """Stop the backend then start it again; convenience wrapper."""
+ stop_command()
+ start_command()
diff --git a/cli/commands/daemon/start.py b/cli/commands/daemon/start.py
new file mode 100644
index 00000000..12ed76dd
--- /dev/null
+++ b/cli/commands/daemon/start.py
@@ -0,0 +1,45 @@
+"""``machina daemon start`` -- spawn the backend as a detached process."""
+
+from __future__ import annotations
+
+import subprocess
+
+from cli._common import preflight
+from cli.colors import console
+from cli.platform_ import server_dir
+from cli.run import uv_run
+
+from . import app
+from ._state import detached_kwargs, log_file, pid_dir, pid_file, read_pid
+
+
+def start_command() -> None:
+ """Start the backend in the background; write PID to the project's
+ user-data directory."""
+ if (existing := read_pid()) is not None:
+ console.print(f"[yellow]Already running (pid={existing}).[/]")
+ return
+
+ cfg, root = preflight()
+ backend_port = cfg.backend_port
+
+ pid_dir().mkdir(parents=True, exist_ok=True)
+ log_path = log_file()
+ log = log_path.open("ab")
+
+ proc = subprocess.Popen(
+ uv_run(
+ "uvicorn", "main:app",
+ "--host", "0.0.0.0",
+ "--port", str(backend_port),
+ "--log-level", "warning",
+ ),
+ cwd=str(server_dir(root)),
+ stdin=subprocess.DEVNULL,
+ stdout=log,
+ stderr=log,
+ **detached_kwargs(),
+ )
+ pid_file().write_text(str(proc.pid))
+ console.print(f"[green]Started pid={proc.pid}[/] (logs: {log_path})")
diff --git a/cli/commands/daemon/status.py b/cli/commands/daemon/status.py
new file mode 100644
index 00000000..ccbe17e3
--- /dev/null
+++ b/cli/commands/daemon/status.py
@@ -0,0 +1,20 @@
+"""``machina daemon status`` -- report whether the backend is running."""
+
+from __future__ import annotations
+
+import typer
+
+from cli.colors import console
+
+from . import app
+from ._state import read_pid
+
+
+def status_command() -> None:
+ """Exit 0 if running (and print PID); exit 1 otherwise."""
+ pid = read_pid()
+ if pid is None:
+ console.print("Not running.")
+ raise typer.Exit(code=1)
+ console.print(f"[green]Running pid={pid}[/]")
diff --git a/cli/commands/daemon/stop.py b/cli/commands/daemon/stop.py
new file mode 100644
index 00000000..0eb69ff5
--- /dev/null
+++ b/cli/commands/daemon/stop.py
@@ -0,0 +1,22 @@
+"""``machina daemon stop`` -- terminate the detached backend."""
+
+from __future__ import annotations
+
+from cli.colors import console
+
+from . import app
+from ._state import kill_tree, pid_file, read_pid
+
+
+def stop_command() -> None:
+ """Stop the backend if running; clear PID file either way."""
+ pid = read_pid()
+ pf = pid_file()
+ if pid is None:
+ console.print("Not running.")
+ pf.unlink(missing_ok=True)
+ return
+ kill_tree(pid)
+ pf.unlink(missing_ok=True)
+ console.print(f"[green]Stopped pid={pid}[/]")
diff --git a/cli/commands/dev.py b/cli/commands/dev.py
index 255cc763..24d64152 100644
--- a/cli/commands/dev.py
+++ b/cli/commands/dev.py
@@ -19,18 +19,21 @@ from pathlib import Path
import typer
+from cli._common import build_backend_spec, free_all_ports, preflight
from cli.colors import console
-from cli.config import load_config
-from cli.platform_ import platform_name, project_root
+from cli.platform_ import (
+ node_modules_dir,
+ platform_name,
+ static_client_script,
+)
from cli.buildenv import validate_build
-from cli.ports import kill_port
from cli.supervisor import Manager, ServiceSpec
from cli.commands._temporal_specs import temporal_specs
def _has_vite(root: Path) -> bool:
return (
- (root / "node_modules" / "vite").exists()
+ (node_modules_dir(root) / "vite").exists()
or (root / "client" / "node_modules" / "vite").exists()
)
@@ -47,9 +50,6 @@ def _clear_vite_cache(root: Path) -> None:
def _build_specs(root: Path, cfg, *, daemon: bool, use_vite: bool) -> list[ServiceSpec]:
- static_client = root / "scripts" / "serve-client.js"
- server_dir = root / "server"
-
if use_vite:
client_spec = ServiceSpec(
name="client",
@@ -61,24 +61,13 @@ def _build_specs(root: Path, cfg, *, daemon: bool, use_vite: bool) -> list[Servi
else:
client_spec = ServiceSpec(
name="client",
- argv=["node", str(static_client)],
+ argv=["node", str(static_client_script(root))],
cwd=root,
ready_port=cfg.client_port,
)
backend_host = "0.0.0.0" if daemon else "127.0.0.1"
- server_spec = ServiceSpec(
- name="server",
- argv=[
- "uv", "run", "uvicorn", "main:app",
- "--host", backend_host,
- "--port", str(cfg.backend_port),
- "--log-level", "warning",
- ],
- cwd=server_dir,
- ready_port=cfg.backend_port,
- )
-
+ server_spec = build_backend_spec(cfg, host=backend_host, root=root)
return [client_spec, server_spec, *temporal_specs(root, cfg)]
@@ -87,8 +76,7 @@ def dev_command(
False, "--daemon", help="Bind backend to 0.0.0.0 instead of 127.0.0.1.",
),
) -> None:
- root = project_root()
- cfg = load_config()
+ cfg, root = preflight()
os.environ.setdefault("PYTHONUTF8", "1")
validate_build(root)
@@ -99,8 +87,7 @@ def dev_command(
console.print(f"Ports: {', '.join(str(p) for p in cfg.all_ports)}")
console.log("Freeing ports...")
- for port in cfg.all_ports:
- kill_port(port)
+ free_all_ports(cfg)
console.log("Ports ready")
_clear_vite_cache(root)
diff --git a/cli/commands/docs.py b/cli/commands/docs.py
index 6749a782..cc160749 100644
--- a/cli/commands/docs.py
+++ b/cli/commands/docs.py
@@ -16,7 +16,7 @@ from pathlib import Path
import typer
from cli.colors import console
-from cli.platform_ import project_root
+from cli.platform_ import project_root, server_dir
app = typer.Typer(
@@ -125,7 +125,7 @@ def _rewrite_index(root: Path) -> None:
def _check_completeness(root: Path) -> int:
documented = _collect_documented_keys(_docs_dir(root))
- registered = _collect_registry_keys(root / "server" / "nodes")
+ registered = _collect_registry_keys(server_dir(root) / "nodes")
missing = sorted(k for k in registered if k not in documented)
if not missing:
console.print(
diff --git a/cli/commands/start.py b/cli/commands/start.py
index e2e5c23e..e6b3df97 100644
--- a/cli/commands/start.py
+++ b/cli/commands/start.py
@@ -20,11 +20,17 @@ from pathlib import Path
import typer
+from cli._common import build_backend_spec, error_block, free_all_ports, preflight
from cli.colors import console
-from cli.config import load_config
-from cli.platform_ import IS_WINDOWS, IS_WSL, platform_name, project_root
-from cli.buildenv import validate_build, venv_python
-from cli.ports import kill_port
+from cli.platform_ import (
+ IS_WINDOWS,
+ IS_WSL,
+ platform_name,
+ server_venv,
+ static_client_script,
+)
+from cli.buildenv import validate_build
+from cli.run import uv_run
from cli.supervisor import Manager, ServiceSpec
from cli.commands._temporal_specs import temporal_specs
@@ -37,28 +43,34 @@ def _sqlalchemy_preflight(root: Path) -> None:
calls even after exclusions are added. Catching it here gives a
clear remediation message instead of letting uvicorn hang silently.
See ``docs-internal/errors.md`` #1 / #1a.
+
+ Runs the probe inside the workspace ``.venv`` through ``uv run``
+ (via :func:`cli.run.uv_run`) -- same environment the supervised
+ services will use, no path-to-interpreter logic on this side.
"""
- py = venv_python(root)
- if py is None:
- return
started = time.monotonic()
try:
subprocess.run(
- [str(py), "-c", "import sqlalchemy"],
+ uv_run("python", "-c", "import sqlalchemy"),
+ cwd=str(root),
timeout=15,
check=True,
capture_output=True,
)
except (subprocess.TimeoutExpired, subprocess.CalledProcessError):
elapsed = time.monotonic() - started
- console.print(f"[red]Error: Python venv health check failed ({elapsed:.1f}s).[/]")
- console.print(" sqlalchemy import hung or crashed.")
- console.print(" Likely cause: Windows Defender scan cache or stale kernel state.")
- console.print(" Fix options:")
- console.print(" 1. Restart-Service WinDefend (admin PowerShell)")
- console.print(" 2. Reboot the machine")
- console.print(f" 3. Add {root / 'server' / '.venv'} to Defender exclusions")
- console.print(" See docs-internal/errors.md #1 / #1a for details.")
+ error_block(
+ f"Python venv health check failed ({elapsed:.1f}s).",
+ [
+ "sqlalchemy import hung or crashed.",
+ "Likely cause: Windows Defender scan cache or stale kernel state.",
+ "Fix options:",
+ " 1. Restart-Service WinDefend (admin PowerShell)",
+ " 2. Reboot the machine",
+ f" 3. Add {server_venv(root)} to Defender exclusions",
+ "See docs-internal/errors.md #1 / #1a for details.",
+ ],
+ )
raise typer.Exit(code=1)
elapsed = time.monotonic() - started
if elapsed > 5.0:
@@ -87,33 +99,19 @@ def _read_version(root: Path) -> str:
def _build_specs(root: Path, cfg, *, temporal_running: bool) -> list[ServiceSpec]:
- static_client = root / "scripts" / "serve-client.js"
- server_dir = root / "server"
-
# Match the existing behaviour: production uses python:start
# (bind 127.0.0.1) on Windows/WSL, python:daemon (bind 0.0.0.0)
# on POSIX.
backend_host = "127.0.0.1" if (IS_WINDOWS or IS_WSL) else "0.0.0.0"
- backend_argv = [
- "uv", "run", "uvicorn", "main:app",
- "--host", backend_host,
- "--port", str(cfg.backend_port),
- "--log-level", "warning",
- ]
specs: list[ServiceSpec] = [
ServiceSpec(
name="client",
- argv=["node", str(static_client)],
+ argv=["node", str(static_client_script(root))],
cwd=root,
ready_port=cfg.client_port,
),
- ServiceSpec(
- name="server",
- argv=backend_argv,
- cwd=server_dir,
- ready_port=cfg.backend_port,
- ),
+ build_backend_spec(cfg, host=backend_host, root=root),
]
if not temporal_running:
specs.extend(temporal_specs(root, cfg))
@@ -121,8 +119,7 @@ def _build_specs(root: Path, cfg, *, temporal_running: bool) -> list[ServiceSpec
def start_command() -> None:
- root = project_root()
- cfg = load_config()
+ cfg, root = preflight()
os.environ.setdefault("PYTHONUTF8", "1")
validate_build(root, require_client_dist=True)
@@ -133,8 +130,7 @@ def start_command() -> None:
console.print("[dim]Temporal already running, skipping[/]")
console.log("Freeing ports...")
- for port in cfg.all_ports:
- kill_port(port)
+ free_all_ports(cfg)
console.log("Ports ready")
version = _read_version(root)
diff --git a/cli/commands/stop.py b/cli/commands/stop.py
index 8664b921..c4ce18f0 100644
--- a/cli/commands/stop.py
+++ b/cli/commands/stop.py
@@ -11,19 +11,17 @@ import time
import typer
+from cli._common import free_all_ports, preflight
from cli.colors import console
-from cli.config import load_config
-from cli.platform_ import platform_name, project_root
+from cli.platform_ import platform_name
from cli.ports import (
kill_by_pattern,
kill_orphaned_machina_processes,
- kill_port,
)
def stop_command() -> None:
- cfg = load_config()
- root = project_root()
+ cfg, root = preflight()
console.print()
console.print("[bold]Stopping MachinaOS services...[/]")
@@ -33,8 +31,7 @@ def stop_command() -> None:
console.print()
all_stopped = True
- for port in cfg.all_ports:
- result = kill_port(port)
+ for port, result in zip(cfg.all_ports, free_all_ports(cfg)):
status = "[green]\\[OK][/]" if result.port_free else "[red]\\[!!][/]"
if result.port_free:
if result.killed_pids:
diff --git a/cli/platform_.py b/cli/platform_.py
index e7e6199e..99c265dd 100644
--- a/cli/platform_.py
+++ b/cli/platform_.py
@@ -1,4 +1,29 @@
-"""Platform / shell / venv detection helpers."""
+"""Platform / shell / venv detection + canonical path-prefix helpers.
+
+All on-disk locations the CLI needs (server tree, the server's uv venv,
+client static script, build-output index, OS-native user dirs) are
+derived from one prefix -- :func:`project_root` -- via the helpers
+below. No callsite composes ``root / "server"`` / ``root / ".venv"``
+inline; every consumer imports the named helper. This keeps layout
+knowledge centralised so a future repo rename / directory relocation
+is a single-file edit.
+
+The CLI is **independent of the server's uv environment**: ``machina``
+is installable via pipx / system Python without involving uv, and
+shells out to ``uv run --no-sync ...`` (via :func:`cli.run.uv_run`)
+for any server-side command. :func:`server_venv` exists so build /
+clean / preflight code can check or report that venv's location
+without composing it inline.
+
+``server_venv`` respects uv's documented ``UV_PROJECT_ENVIRONMENT``
+override (https://docs.astral.sh/uv/concepts/projects/config/) so
+power users with non-default venv locations still work.
+
+OS-native user dirs (data, cache, config, log) are derived through
+``platformdirs`` (https://pypi.org/project/platformdirs/) -- the same
+library the server uses for its pooch binary cache -- so the two halves
+of the project agree on per-OS conventions.
+"""
from __future__ import annotations
@@ -30,8 +55,110 @@ def platform_name() -> str:
def project_root() -> Path:
- """Resolve the project root from a module under ``machina/``.
+ """Resolve the project root from a module under ``cli/``.
- Layout: ``<project_root>/machina/<this_file>`` -> parents[1].
+ Layout: ``<project_root>/cli/<this_file>`` -> parents[1].
"""
return Path(__file__).resolve().parents[1]
+
+
+# ---------------------------------------------------------------------------
+# Path-prefix helpers -- canonical layout derived from ``project_root``.
+# ---------------------------------------------------------------------------
+
+def _root(root: Path | None) -> Path:
+ return root if root is not None else project_root()
+
+
+def server_dir(root: Path | None = None) -> Path:
+ """The ``server/`` directory -- the Python backend + plugin tree.
+ ``server/`` is its own standalone uv project (its ``pyproject.toml``
+ declares the dependency closure ``uv sync`` resolves)."""
+ return _root(root) / "server"
+
+
+def server_venv(root: Path | None = None) -> Path:
+ """The server's uv-managed project environment directory.
+
+ ``server/`` is a standalone uv project, so uv places its venv at
+ ``server/.venv`` by default per https://docs.astral.sh/uv/concepts/
+ projects/layout/. The ``UV_PROJECT_ENVIRONMENT`` env var overrides
+ this -- relative overrides resolve against ``server/`` (matching
+ uv's own behaviour), absolute paths are used verbatim.
+
+ The CLI itself does NOT live in this venv; ``machina`` is
+ independently installable (pipx / system python). This helper
+ exists so build / clean / preflight code can check or report the
+ server venv's location without anyone composing the path inline.
+ """
+ base = server_dir(root)
+ override = os.environ.get("UV_PROJECT_ENVIRONMENT")
+ if override:
+ path = Path(override)
+ return path if path.is_absolute() else base / path
+ return base / ".venv"
+
+
+def node_modules_dir(root: Path | None = None) -> Path:
+ """The pnpm/npm-installed dependency tree at the workspace root."""
+ return _root(root) / "node_modules"
+
+
+def client_dist_entry(root: Path | None = None) -> Path:
+ """The Vite-built client entrypoint -- proof that the client side
+ of ``machina build`` completed."""
+ return _root(root) / "client" / "dist" / "index.html"
+
+
+def static_client_script(root: Path | None = None) -> Path:
+ """The Node.js static-server script that serves the built client
+ (used by ``machina start``)."""
+ return _root(root) / "scripts" / "serve-client.js"
+
+
+# ---------------------------------------------------------------------------
+# OS-native user directories via ``platformdirs``
+# (https://pypi.org/project/platformdirs/). ``platformdirs`` is imported
+# inside each helper, NOT at module level, so the rest of
+# ``cli.platform_`` (path-prefix helpers, project_root, the platform
+# booleans) keeps loading even when the wheel hasn't been installed
+# yet -- the recovery-verb scenario (``machina clean`` against a
+# half-broken env). Callers that actually need a user dir trigger the
+# import on first call; if missing, the natural ``ModuleNotFoundError``
+# surfaces at that callsite, not at every CLI import.
+# ---------------------------------------------------------------------------
+
+_APP_NAME = "MachinaOs"
+
+
+def user_data_dir() -> Path:
+ """User data directory.
+
+ Honours the project's ``DATA_DIR`` env override (see
+ ``.env.template``) -- the convention shared with the server's
+ ``core.paths.machina_root``. Otherwise delegates to platformdirs.
+ """
+ override = os.environ.get("DATA_DIR")
+ if override:
+ return Path(override).expanduser()
+ import platformdirs
+ return platformdirs.user_data_path(_APP_NAME, appauthor=_APP_NAME)
+
+
+def user_cache_dir() -> Path:
+ """User cache directory (downloaded binaries / pooch caches).
+ Matches ``server/core/paths.py::packages_dir``."""
+ import platformdirs
+ return platformdirs.user_cache_path(_APP_NAME, appauthor=_APP_NAME)
+
+
+def user_config_dir() -> Path:
+ """User config directory."""
+ import platformdirs
+ return platformdirs.user_config_path(_APP_NAME, appauthor=_APP_NAME)
+
+
+def user_log_dir() -> Path:
+ """User log directory."""
+ import platformdirs
+ return platformdirs.user_log_path(_APP_NAME, appauthor=_APP_NAME)
diff --git a/cli/pyproject.toml b/cli/pyproject.toml
deleted file mode 100644
index 1da3f4ed..00000000
--- a/cli/pyproject.toml
+++ /dev/null
@@ -1,32 +0,0 @@
-[project]
-name = "machina"
-version = "0.1.0"
-description = "MachinaOS project supervisor CLI"
-requires-python = ">=3.11"
-dependencies = [
- "typer>=0.12",
- "rich>=13",
- "psutil>=6",
- "anyio>=4",
- # 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 = ["setuptools>=68"]
-build-backend = "setuptools.build_meta"
-
-[tool.setuptools.packages.find]
-where = ["."]
-include = ["cli*"]
-exclude = ["tests*"]
-
-[tool.pytest.ini_options]
-testpaths = ["tests"]
-asyncio_mode = "auto"
diff --git a/cli/run.py b/cli/run.py
index f918429e..7ba89feb 100644
--- a/cli/run.py
+++ b/cli/run.py
@@ -40,6 +40,33 @@ def which_argv(argv: list[str]) -> list[str]:
return [shutil.which(argv[0]) or argv[0], *argv[1:]]
+def uv_run(*args: str) -> list[str]:
+ """Standardized argv for executing a command inside the workspace
+ ``.venv`` via ``uv run``.
+
+ ``uv run`` is the documented subcommand for executing commands
+ against a uv project / workspace environment
+ (https://docs.astral.sh/uv/reference/cli/#uv-run). With the workspace
+ declared in the repo-root ``pyproject.toml``, ``uv sync`` materialises
+ one shared ``.venv`` at the workspace root and installs every member
+ (currently ``server/``) editable into it -- so ``python -m
+ services.*`` resolves out of that single environment
+ (https://docs.astral.sh/uv/concepts/projects/sync/).
+
+ ``--no-sync`` skips the per-invocation lockfile re-check that ``uv
+ run`` does by default. ``machina build`` is the single place that
+ actually re-syncs; every other entry point (start, dev, daemon,
+ supervised runtimes, preflight) trusts the lockfile and just
+ activates the env. This is the documented optimisation for hot
+ spawn paths (https://docs.astral.sh/uv/reference/cli/#uv-run).
+
+ All ``uv run ...`` invocations in this CLI MUST go through this
+ helper -- never inline ``["uv", "run", ...]`` argv lists -- so the
+ flags + semantics stay uniform.
+ """
+ return ["uv", "run", "--no-sync", *args]
+
+
def run(
argv: list[str],
*,
diff --git a/cli/tests/test_daemon.py b/cli/tests/test_daemon.py
index b20a5027..71fdd979 100644
--- a/cli/tests/test_daemon.py
+++ b/cli/tests/test_daemon.py
@@ -1,4 +1,17 @@
-"""Smoke tests for ``cli.commands.daemon``."""
+"""Smoke tests for ``cli.commands.daemon`` (verb-per-file package).
+
+Post-refactor, the shared helpers live in :mod:`cli.commands.daemon._state`:
+
+ - ``detached_kwargs()`` -- POSIX vs Windows spawn flags
+ - ``pid_file()`` / ``pid_dir()`` / ``log_file()`` -- lazy path lookups
+ - ``read_pid()`` -- PID-file → live-pid lookup
+ - ``kill_tree(pid)`` -- psutil-backed recursive terminate
+
+The verb entry points live in sibling modules (``start.py`` / ``stop.py``
+/ ``status.py`` / ``restart.py``). Patches target whichever module
+actually owns the attribute under test -- mirrors how pdm tests its
+``commands/venv/`` sub-package.
+"""
from __future__ import annotations
@@ -9,72 +22,72 @@ from unittest.mock import MagicMock, patch
import psutil
import pytest
-from cli.commands import daemon
+from cli.commands.daemon import _state, status, stop
-# venv-python discovery is now centralised in cli.buildenv; covered
-# by tests/test_start.py (test_venv_python_finds_*).
-
+# ---------------------------------------------------------------- helpers
def test_detached_kwargs_windows_uses_creationflags():
# subprocess.DETACHED_PROCESS and CREATE_NEW_PROCESS_GROUP are only
- # defined on Windows. Patching them in with `create=True` lets the
- # test cover the Windows branch of `_detached_kwargs` on every CI
- # runner (POSIX or Windows) without resorting to a skipif that would
- # leave the branch entirely uncovered on the Linux-only CI matrix.
+ # defined on Windows. Patching them in with ``create=True`` lets the
+ # test cover the Windows branch of ``detached_kwargs`` on every CI
+ # runner (POSIX or Windows) without a skipif that would leave the
+ # branch entirely uncovered on the Linux-only CI matrix.
# Real values from windows.h: DETACHED_PROCESS=0x08, GROUP=0x200.
fake_detached = 0x00000008
fake_new_group = 0x00000200
- with patch.object(daemon, "IS_WINDOWS", True), \
+ with patch.object(_state, "IS_WINDOWS", True), \
patch.object(subprocess, "DETACHED_PROCESS", fake_detached, create=True), \
patch.object(subprocess, "CREATE_NEW_PROCESS_GROUP", fake_new_group, create=True):
- kw = daemon._detached_kwargs()
+ kw = _state.detached_kwargs()
assert "creationflags" in kw
assert kw["creationflags"] == fake_detached | fake_new_group
assert "start_new_session" not in kw
def test_detached_kwargs_posix_uses_setsid():
- with patch.object(daemon, "IS_WINDOWS", False):
- kw = daemon._detached_kwargs()
+ with patch.object(_state, "IS_WINDOWS", False):
+ kw = _state.detached_kwargs()
assert kw == {"start_new_session": True}
def test_read_pid_returns_none_when_file_missing(tmp_path: Path):
- with patch.object(daemon, "_PID_FILE", tmp_path / "missing.pid"):
- assert daemon._read_pid() is None
+ with patch.object(_state, "pid_file", return_value=tmp_path / "missing.pid"):
+ assert _state.read_pid() is None
def test_read_pid_returns_none_for_corrupt_pid_file(tmp_path: Path):
- pid_file = tmp_path / "cli.pid"
- pid_file.write_text("not-a-number")
- with patch.object(daemon, "_PID_FILE", pid_file):
- assert daemon._read_pid() is None
+ pid_path = tmp_path / "cli.pid"
+ pid_path.write_text("not-a-number")
+ with patch.object(_state, "pid_file", return_value=pid_path):
+ assert _state.read_pid() is None
def test_read_pid_returns_none_when_process_no_longer_exists(tmp_path: Path):
- pid_file = tmp_path / "cli.pid"
- pid_file.write_text("999999")
- with patch.object(daemon, "_PID_FILE", pid_file), \
- patch.object(daemon.psutil, "pid_exists", return_value=False):
- assert daemon._read_pid() is None
+ pid_path = tmp_path / "cli.pid"
+ pid_path.write_text("999999")
+ with patch.object(_state, "pid_file", return_value=pid_path), \
+ patch.object(_state.psutil, "pid_exists", return_value=False):
+ assert _state.read_pid() is None
def test_read_pid_returns_pid_when_alive(tmp_path: Path):
- pid_file = tmp_path / "cli.pid"
- pid_file.write_text("1234\n")
- with patch.object(daemon, "_PID_FILE", pid_file), \
- patch.object(daemon.psutil, "pid_exists", return_value=True):
- assert daemon._read_pid() == 1234
+ pid_path = tmp_path / "cli.pid"
+ pid_path.write_text("1234\n")
+ with patch.object(_state, "pid_file", return_value=pid_path), \
+ patch.object(_state.psutil, "pid_exists", return_value=True):
+ assert _state.read_pid() == 1234
+
+# ---------------------------------------------------------------- kill_tree
def test_kill_tree_terminates_children_and_parent():
parent = MagicMock()
child1 = MagicMock()
child2 = MagicMock()
parent.children.return_value = [child1, child2]
- with patch.object(daemon.psutil, "Process", return_value=parent):
- daemon._kill_tree(123)
+ with patch.object(_state.psutil, "Process", return_value=parent):
+ _state.kill_tree(123)
child1.kill.assert_called_once()
child2.kill.assert_called_once()
parent.terminate.assert_called_once()
@@ -85,29 +98,36 @@ def test_kill_tree_force_kills_on_timeout():
parent = MagicMock()
parent.children.return_value = []
parent.wait.side_effect = psutil.TimeoutExpired(seconds=5)
- with patch.object(daemon.psutil, "Process", return_value=parent):
- daemon._kill_tree(123)
+ with patch.object(_state.psutil, "Process", return_value=parent):
+ _state.kill_tree(123)
parent.terminate.assert_called_once()
parent.kill.assert_called_once()
def test_kill_tree_no_such_process_is_noop():
- with patch.object(daemon.psutil, "Process", side_effect=psutil.NoSuchProcess(123)):
- daemon._kill_tree(123)
+ with patch.object(_state.psutil, "Process", side_effect=psutil.NoSuchProcess(123)):
+ _state.kill_tree(123)
+
+# ---------------------------------------------------------------- verbs
def test_stop_command_clears_pid_file_when_not_running(tmp_path: Path):
- pid_file = tmp_path / "cli.pid"
- pid_file.write_text("999999")
- with patch.object(daemon, "_PID_FILE", pid_file), \
- patch.object(daemon, "_read_pid", return_value=None):
- daemon.stop_command()
- assert not pid_file.exists()
+ # ``stop`` module imports ``pid_file`` / ``read_pid`` by name from
+ # ``_state``, so the patches must target the consumer's namespace
+ # (``stop.pid_file``), not the source module (``_state.pid_file``).
+ # Classic "where to patch" gotcha -- see
+ # https://docs.python.org/3/library/unittest.mock.html#where-to-patch.
+ pid_path = tmp_path / "cli.pid"
+ pid_path.write_text("999999")
+ with patch.object(stop, "pid_file", return_value=pid_path), \
+ patch.object(stop, "read_pid", return_value=None):
+ stop.stop_command()
+ assert not pid_path.exists()
def test_status_command_exits_1_when_not_running():
import typer
- with patch.object(daemon, "_read_pid", return_value=None), \
+ with patch.object(status, "read_pid", return_value=None), \
pytest.raises(typer.Exit) as exc:
- daemon.status_command()
+ status.status_command()
assert exc.value.exit_code == 1
diff --git a/cli/tests/test_start.py b/cli/tests/test_start.py
index 746d2232..373bb3e0 100644
--- a/cli/tests/test_start.py
+++ b/cli/tests/test_start.py
@@ -5,7 +5,6 @@ from __future__ import annotations
from pathlib import Path
from unittest.mock import patch
-from cli import buildenv
from cli.commands import start
from cli.config import Config, load_config
@@ -18,22 +17,12 @@ def _cfg() -> Config:
return load_config()
-def test_venv_python_returns_none_when_missing(tmp_path: Path):
- assert buildenv.venv_python(tmp_path) is None
-
-
-def test_venv_python_finds_windows_layout(tmp_path: Path):
- win_py = tmp_path / "server" / ".venv" / "Scripts" / "python.exe"
- win_py.parent.mkdir(parents=True)
- win_py.write_text("")
- assert buildenv.venv_python(tmp_path) == win_py
-
-
-def test_venv_python_finds_posix_layout(tmp_path: Path):
- posix_py = tmp_path / "server" / ".venv" / "bin" / "python"
- posix_py.parent.mkdir(parents=True)
- posix_py.write_text("")
- assert buildenv.venv_python(tmp_path) == posix_py
+# The previous ``test_venv_python_*`` cases verified a custom helper
+# that walked ``server/.venv/{Scripts,bin}`` paths. That helper has been
+# retired: subprocess launchers now build their argv via
+# :func:`cli.run.uv_run`, which delegates interpreter selection to
+# ``uv run`` (https://docs.astral.sh/uv/reference/cli/#uv-run). Nothing
+# platform-specific to assert from the CLI side anymore.
def test_temporal_running_false_when_port_closed():
diff --git a/pyproject.toml b/pyproject.toml
index e05c0bea..5d20a98d 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -8,6 +8,13 @@ dependencies = [
"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
@@ -25,3 +32,17 @@ build-backend = "hatchling.build"
[tool.hatch.build.targets.wheel]
packages = ["cli"]
+
+[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.
diff --git a/cli/commands/_supervised_runtime.py b/server/services/temporal/_supervised_runtime.py
similarity index 73%
rename from cli/commands/_supervised_runtime.py
rename to server/services/temporal/_supervised_runtime.py
index d5316f2c..b660da41 100644
--- a/cli/commands/_supervised_runtime.py
+++ b/server/services/temporal/_supervised_runtime.py
@@ -1,9 +1,9 @@
"""Generic bridge: run any ``BaseSupervisor`` singleton from a CLI.
-The Manager supervisor in ``machina/supervisor.py`` schedules
+The CLI's ``Manager`` supervisor (``cli/supervisor.py``) schedules
``ServiceSpec`` entries by spawning a subprocess and supervising it.
``BaseSupervisor``-managed runtimes (pgserver, Temporal binary) don't
-ship a CLI of their own — they're Python singletons started via
+ship a CLI of their own -- they're Python singletons started via
``await runtime.start()``.
This shim bridges the two: import a runtime factory by dotted path,
@@ -11,12 +11,19 @@ call it, ``await singleton.start()``, then block on a shutdown signal.
``Manager`` sends SIGTERM during graceful shutdown; we catch it,
``await singleton.stop()``, then exit cleanly.
-Usage (inside ``ServiceSpec.argv``):
+Module location: this lives inside the ``server`` package because the
+factory targets it resolves (``services.temporal._runtime:get_postgres
+_runtime`` etc.) are server-side singletons. Hosting the shim here
+keeps the CLI free of server-side imports and lets a single ``uv run
+python -m services.temporal._supervised_runtime <factory>`` invocation
+work against the workspace ``.venv`` -- no PYTHONPATH composition, no
+cross-venv plumbing.
- [
- "python", "-m", "cli.commands._supervised_runtime",
- "services.temporal._runtime:get_postgres_runtime",
- ]
+Invocation (inside ``ServiceSpec.argv``, built via ``cli.run.uv_run``):
+
+ uv_run("python", "-m",
+ "services.temporal._supervised_runtime",
+ "services.temporal._runtime:get_postgres_runtime")
Equivalent to (Python idiom):
@@ -62,7 +69,7 @@ async def _run(factory_dotted: str) -> int:
except NotImplementedError:
# Windows: add_signal_handler raises for SIGTERM. The
# Manager supervisor's tree-kill semantics (psutil-based)
- # work regardless — we just lose the graceful path on Win.
+ # work regardless -- we just lose the graceful path on Win.
pass
print(f"[supervised_runtime] starting {factory_dotted}", flush=True)
@@ -79,7 +86,7 @@ async def _run(factory_dotted: str) -> int:
def main() -> int:
if len(sys.argv) != 2:
print(
- "usage: python -m cli.commands._supervised_runtime "
+ "usage: python -m services.temporal._supervised_runtime "
"<module.path:factory>",
file=sys.stderr,
)