machinaos 0.0.78 → 0.0.80

package/cli/commands/clean.py

@@ -0,0 +1,141 @@
+"""``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
+
+import shutil
+import time
+from pathlib import Path
+
+from cli._common import free_all_ports, preflight
+
+
+# Removed each run -- order doesn't matter, ``shutil.rmtree`` is recursive.
+# Only project-local artefacts. Home-rooted state (``~/.machina/``,
+# ``~/.claude/``, etc.) is the user's; we never touch it from
+# ``machina clean``.
+_TARGETS = [
+    "node_modules",
+    "client/node_modules",
+    "client/dist",
+    "client/.vite",
+    # 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",
+]
+
+
+# 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.
+_MACHINA_KEEP = frozenset({"workflows"})
+
+
+def _rmtree_with_retry(path: Path, *, attempts: int = 3, delay: float = 0.1) -> bool:
+    """``shutil.rmtree`` with Windows-friendly retry on file-lock errors."""
+    for attempt in range(attempts):
+        try:
+            shutil.rmtree(path, ignore_errors=False)
+            return True
+        except OSError as exc:
+            if attempt == attempts - 1:
+                print(f"  warning: could not remove {path.name}: {exc}")
+                return False
+            time.sleep(delay)
+    return False
+
+
+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
+
+    killed_ports = 0
+    for port, result in zip(cfg.all_ports, results):
+        if result.killed_pids:
+            print(f"  port {port}: killed {len(result.killed_pids)} process(es)")
+            killed_ports += len(result.killed_pids)
+
+    orphaned = kill_orphaned_machina_processes(str(root), exclude_substring="-m cli")
+    if orphaned:
+        print(f"  orphaned: killed {len(orphaned)} process(es)")
+
+    return bool(killed_ports or orphaned)
+
+
+def clean_command() -> None:
+    cfg, root = preflight()
+
+    print("Cleaning MachinaOS...")
+
+    # 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:
+        print("  no running processes found.")
+
+    # Step 3: remove top-level artefact directories
+    print()
+    print("Removing directories...")
+    for target in _TARGETS:
+        path = root / target
+        if path.exists():
+            print(f"  removing: {target}")
+            _rmtree_with_retry(path)
+
+    # Step 4: selectively clean ``<repo>/.machina/`` -- preserve
+    # ``workflows/`` (shipped example seeds, see ``_MACHINA_KEEP``);
+    # 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():
+        for child in machina_dir.iterdir():
+            if child.name in _MACHINA_KEEP:
+                continue
+            rel = f".machina/{child.name}"
+            print(f"  removing: {rel}")
+            if child.is_dir():
+                _rmtree_with_retry(child)
+            else:
+                try:
+                    child.unlink()
+                except OSError as exc:
+                    print(f"  warning: could not remove {rel}: {exc}")
+
+    print()
+    print("Done.")

package/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"]

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

package/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
+
+
+@app.command("restart")
+def restart_command() -> None:
+    """Stop the backend then start it again; convenience wrapper."""
+    stop_command()
+    start_command()

package/cli/commands/daemon/start.py

@@ -0,0 +1,49 @@
+"""``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
+
+
+@app.command("start")
+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})")

package/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
+
+
+@app.command("status")
+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}[/]")

package/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
+
+
+@app.command("stop")
+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}[/]")

package/{machina → cli}/commands/dev.py

@@ -19,19 +19,23 @@ from pathlib import Path
 
 import typer
 
-from machina.colors import console
-from machina.config import load_config
-from machina.platform_ import platform_name, project_root
-from machina.buildenv import validate_build
-from machina.ports import kill_port
-from machina.supervisor import Manager, ServiceSpec
+from cli._common import build_backend_spec, free_all_ports, preflight
+from cli.colors import console
+from cli.config import load_dev_overrides
+from cli.platform_ import (
+    node_modules_dir,
+    platform_name,
+    static_client_script,
+)
+from cli.buildenv import validate_build
+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()
-        or (root / "client" / "node_modules" / "vite").exists()
-    )
+    return (node_modules_dir(root) / "vite").exists() or (
+        root / "client" / "node_modules" / "vite"
+    ).exists()
 
 
 def _clear_vite_cache(root: Path) -> None:
@@ -46,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",
@@ -60,55 +61,44 @@ 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,
-    )
-
-    return [
-        client_spec,
-        server_spec,
-        ServiceSpec(
-            name="temporal",
-            argv=["temporal", "api"],
-            cwd=root,
-            ready_port=cfg.temporal_port,
-        ),
-    ]
+    server_spec = build_backend_spec(cfg, host=backend_host, root=root)
+    return [client_spec, server_spec, *temporal_specs(root, cfg)]
 
 
 def dev_command(
     daemon: bool = typer.Option(
-        False, "--daemon", help="Bind backend to 0.0.0.0 instead of 127.0.0.1.",
+        False,
+        "--daemon",
+        help="Bind backend to 0.0.0.0 instead of 127.0.0.1.",
     ),
 ) -> None:
-    root = project_root()
-    cfg = load_config()
+    # Layer ``.env.dev`` (committed) on top of ``.env.template`` + ``.env``
+    # so dev state lands at ``<repo>/.machina/`` (per-checkout) instead
+    # of ``~/.machina/`` (user home). Called BEFORE ``preflight()`` so
+    # ``load_config``'s ``setdefault`` pass sees the dev values already
+    # in ``os.environ``. ``machina start`` / ``machina daemon`` skip
+    # this hook, falling through to the ``.env.template`` defaults.
+    load_dev_overrides()
+    cfg, root = preflight()
     os.environ.setdefault("PYTHONUTF8", "1")
 
     validate_build(root)
 
     console.print("\n[bold]=== MachinaOS Starting ===[/]\n")
     console.print(f"Platform: {platform_name()}")
-    console.print(f"Mode:     {'Daemon (uvicorn)' if daemon else 'Development (uvicorn)'}")
+    console.print(
+        f"Mode:     {'Daemon (uvicorn)' if daemon else 'Development (uvicorn)'}"
+    )
     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)

package/{machina → cli}/commands/docs.py

@@ -15,8 +15,8 @@ from pathlib import Path
 
 import typer
 
-from machina.colors import console
-from machina.platform_ import project_root
+from cli.colors import console
+from cli.platform_ import project_root, server_dir
 
 
 app = typer.Typer(
@@ -52,8 +52,7 @@ def _list_categories(docs_dir: Path) -> list[str]:
     if not docs_dir.exists():
         return []
     return sorted(
-        d.name for d in docs_dir.iterdir()
-        if d.is_dir() and not d.name.startswith("_")
+        d.name for d in docs_dir.iterdir() if d.is_dir() and not d.name.startswith("_")
     )
 
 
@@ -65,11 +64,13 @@ def _list_docs(docs_dir: Path, category: str) -> list[dict]:
             continue
         if path.name.startswith("_") or path.name == "README.md":
             continue
-        out.append({
-            "rel_path": f"{category}/{path.name}",
-            "title": _read_h1(path),
-            "node_key": path.stem,
-        })
+        out.append(
+            {
+                "rel_path": f"{category}/{path.name}",
+                "title": _read_h1(path),
+                "node_key": path.stem,
+            }
+        )
     return out
 
 
@@ -125,7 +126,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(
@@ -141,7 +142,8 @@ def _check_completeness(root: Path) -> int:
 @app.command("nodes", help="Rebuild (or --check) the per-node documentation index.")
 def nodes(
     check: bool = typer.Option(
-        False, "--check",
+        False,
+        "--check",
         help="Instead of rewriting, exit 1 if any registered node lacks a doc.",
     ),
 ) -> None: