machinaos 0.0.78 → 0.0.80

package/cli/_common.py

@@ -0,0 +1,122 @@
+"""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}")

package/cli/buildenv.py

@@ -0,0 +1,40 @@
+"""Build-environment helpers shared by ``start`` / ``dev`` / ``daemon``.
+
+``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
+
+from pathlib import Path
+
+import typer
+
+from cli.colors import console
+from cli.platform_ import (
+    client_dist_entry,
+    node_modules_dir,
+    server_venv,
+)
+
+
+def validate_build(root: Path, *, require_client_dist: bool = False) -> None:
+    """Refuse to launch if ``machina build`` hasn't been run.
+
+    Raises ``typer.Exit(1)`` with a remediation hint. ``dev`` allows a
+    missing ``client/dist`` (Vite serves the source); ``start`` opts in
+    via ``require_client_dist=True``.
+    """
+    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 client_dist_entry(root).exists():
+        console.print('[red]Error: Client not built. Run "machina build" first.[/]')
+        raise typer.Exit(code=1)

package/cli/cli.py

@@ -0,0 +1,204 @@
+"""Typer CLI for ``machina``.
+
+Every verb is registered here as a thin stub that lazy-imports its
+implementation on dispatch. Running ``machina clean`` (the recovery
+verb) only triggers the import of ``cli.commands.clean`` -- not
+``dev`` / ``start`` / temporal specs / daemon verbs / docs / version.
+
+Pattern lifted from gemini-cli's ``gemini.tsx`` + vercel's ``vc.js``
+(fast-path ``--version`` and ``--help`` before any heavy import) and
+next.js's ``bin/next.ts`` (per-verb ``import('../cli/<verb>.js')``).
+Typer's ``add_typer`` requires a concrete sub-app at registration
+time, so for grouped verbs (``daemon`` / ``docs`` / ``version``) we
+build fresh Typer instances HERE and lazy-wrap each leaf -- avoids
+importing ``cli.commands.daemon`` etc. at boot.
+"""
+
+from __future__ import annotations
+
+import typer
+
+app = typer.Typer(
+    name="machina",
+    help="MachinaOS project supervisor CLI.",
+    no_args_is_help=True,
+    add_completion=False,
+)
+
+
+@app.callback()
+def _root() -> None:
+    """Marks the Typer app as a multi-command group."""
+
+
+# ----------------------------------------------------------- top-level verbs
+
+
+@app.command(
+    "start",
+    help="Start all services in production mode (static client + uvicorn + temporal).",
+)
+def _start() -> None:
+    from cli.commands.start import start_command
+
+    start_command()
+
+
+@app.command(
+    "dev",
+    help="Start all services in dev mode (Vite HMR + uvicorn + temporal).",
+)
+def _dev(
+    daemon: bool = typer.Option(
+        False,
+        "--daemon",
+        help="Bind backend to 0.0.0.0 instead of 127.0.0.1.",
+    ),
+) -> None:
+    from cli.commands.dev import dev_command
+
+    dev_command(daemon=daemon)
+
+
+@app.command(
+    "stop",
+    help="Stop all MachinaOS services and free configured ports.",
+)
+def _stop() -> None:
+    from cli.commands.stop import stop_command
+
+    stop_command()
+
+
+@app.command(
+    "clean",
+    help="Stop services then remove build artefacts and venvs.",
+)
+def _clean() -> None:
+    from cli.commands.clean import clean_command
+
+    clean_command()
+
+
+@app.command(
+    "build",
+    help="Install toolchain + build client + sync Python + verify deps.",
+)
+def _build() -> None:
+    from cli.commands.build import build_command
+
+    build_command()
+
+
+# --------------------------------------------------------------- daemon group
+
+daemon_app = typer.Typer(
+    name="daemon",
+    help="Run the MachinaOs backend as a detached process.",
+    no_args_is_help=True,
+    add_completion=False,
+)
+
+
+@daemon_app.command(
+    "start",
+    help="Start the backend in the background; write PID file to user-data dir.",
+)
+def _daemon_start() -> None:
+    from cli.commands.daemon.start import start_command
+
+    start_command()
+
+
+@daemon_app.command(
+    "stop",
+    help="Stop the backend if running; clear PID file either way.",
+)
+def _daemon_stop() -> None:
+    from cli.commands.daemon.stop import stop_command
+
+    stop_command()
+
+
+@daemon_app.command(
+    "status",
+    help="Exit 0 if running (and print PID); exit 1 otherwise.",
+)
+def _daemon_status() -> None:
+    from cli.commands.daemon.status import status_command
+
+    status_command()
+
+
+@daemon_app.command(
+    "restart",
+    help="Stop the backend then start it again; convenience wrapper.",
+)
+def _daemon_restart() -> None:
+    from cli.commands.daemon.restart import restart_command
+
+    restart_command()
+
+
+app.add_typer(daemon_app, name="daemon")
+
+
+# ----------------------------------------------------------------- docs group
+
+docs_app = typer.Typer(
+    name="docs",
+    help="Documentation tooling (rebuild indices, completeness checks).",
+    no_args_is_help=True,
+    add_completion=False,
+)
+
+
+@docs_app.command(
+    "nodes",
+    help="Rebuild (or --check) the per-node documentation index.",
+)
+def _docs_nodes(
+    check: bool = typer.Option(
+        False,
+        "--check",
+        help="Instead of rewriting, exit 1 if any registered node lacks a doc.",
+    ),
+) -> None:
+    from cli.commands.docs import nodes
+
+    nodes(check=check)
+
+
+app.add_typer(docs_app, name="docs")
+
+
+# -------------------------------------------------------------- version group
+
+version_app = typer.Typer(
+    name="version",
+    help="Version-sync tooling.",
+    no_args_is_help=True,
+    add_completion=False,
+)
+
+
+@version_app.command(
+    "sync",
+    help="Sync package.json versions from latest git tag.",
+)
+def _version_sync(
+    tag: str | None = typer.Argument(
+        None,
+        help="Git tag to use (defaults to latest).",
+    ),
+) -> None:
+    from cli.commands.version import sync
+
+    sync(tag=tag)
+
+
+app.add_typer(version_app, name="version")
+
+
+if __name__ == "__main__":
+    app()

package/{machina → cli}/colors.py

@@ -23,8 +23,16 @@ console = Console(log_time_format="[%H:%M:%S.%f]", log_path=False)
 # Honcho's rotation, lifted: skip very-dark (black) and very-bright (white)
 # so prefixes remain readable on both light and dark terminals.
 _PALETTE = [
-    "cyan", "green", "yellow", "blue", "magenta",
-    "bright_cyan", "bright_green", "bright_yellow", "bright_blue", "bright_magenta",
+    "cyan",
+    "green",
+    "yellow",
+    "blue",
+    "magenta",
+    "bright_cyan",
+    "bright_green",
+    "bright_yellow",
+    "bright_blue",
+    "bright_magenta",
 ]
 _color_cycle = cycle(_PALETTE)
 

package/cli/commands/__init__.py

@@ -0,0 +1 @@
+"""``machina`` subcommand modules. Imported by ``cli.cli``."""

package/cli/commands/_temporal_specs.py

@@ -0,0 +1,59 @@
+"""ServiceSpec for the Temporal stack — shared by ``start`` and ``dev``.
+
+One ServiceSpec running the supervised :class:`TemporalServerRuntime`
+singleton via :mod:`services.temporal._supervised_runtime` (a thin
+shim that lives next to the runtime factory it imports). The runtime
+spawns the official ``temporal`` CLI (downloaded by pooch from
+https://temporal.download/cli/archive/latest) with the ``server
+start-dev`` subcommand against a SQLite db at
+``settings.temporal_sqlite_path``.
+
+Matches the local-dev install method documented at
+https://docs.temporal.io/develop/python/set-up-your-local-python.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+from cli.config import Config
+from cli.platform_ import server_dir
+from cli.run import uv_run
+from cli.supervisor import RestartPolicy, ServiceSpec
+
+
+def temporal_specs(root: Path, cfg: Config) -> list[ServiceSpec]:
+    """Return the Temporal ServiceSpec list.
+
+    ``cfg`` is :class:`cli.config.Config`; ``cfg.temporal_port`` drives
+    the gRPC readiness probe.
+
+    Readiness-probe + graceful-shutdown windows are read at call time
+    from ``os.environ`` (pushed there by :func:`cli.config.load_config`
+    from ``.env.template``); ``KeyError`` if missing — broken install.
+    Doing the reads here, not at module import, keeps the module safe
+    to import before ``load_config()`` runs (tests, REPL, reverse
+    import order).
+    """
+    return [
+        ServiceSpec(
+            name="temporal",
+            argv=uv_run(
+                "python",
+                "-m",
+                "services.temporal._supervised_runtime",
+                "services.temporal._runtime:get_temporal_server_runtime",
+            ),
+            cwd=server_dir(root),
+            ready_port=cfg.temporal_port,
+            ready_timeout=float(os.environ["TEMPORAL_SERVER_READY_TIMEOUT_SECONDS"]),
+            restart=RestartPolicy.ON_CRASH,
+            terminate_grace_seconds=float(
+                os.environ["TEMPORAL_GRACEFUL_SHUTDOWN_SECONDS"]
+            ),
+        ),
+    ]
+
+
+__all__ = ["temporal_specs"]

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

@@ -14,13 +14,13 @@ import os
 import re
 import shutil
 import sys
-from pathlib import Path
 
 import typer
 
-from machina.run import capture, run
-from machina.colors import console
-from machina.platform_ import project_root
+from cli._common import error_block
+from cli.run import capture, run, uv_run
+from cli.colors import console
+from cli.platform_ import node_modules_dir, project_root, server_dir
 
 
 # Source dirs / entry-point modules under ``server/`` that ``machina build``
@@ -44,6 +44,7 @@ COMPILEALL_SOURCE_DIRS: tuple[str, ...] = (
 
 # ---------------------------------------------------------------- helpers
 
+
 def _which_python() -> str | None:
     """Prefer ``python3`` so we don't pick up Python 2.x on POSIX distros."""
     for cmd in ("python3", "python"):
@@ -84,33 +85,15 @@ def _ensure_uv(python_cmd: str) -> str:
     run([python_cmd, "-m", "pip", "install", "uv"])
     version = capture(["uv", "--version"])
     if not version:
-        console.print("[red]Error: failed to install uv. See https://docs.astral.sh/uv/[/]")
+        error_block("failed to install uv.", ["See https://docs.astral.sh/uv/"])
         raise typer.Exit(code=1)
     console.print(f"  uv: {version}")
     return version
 
 
-def _ensure_temporal() -> None:
-    """Ensure the ``temporal`` CLI (from npm package ``temporal-server``) is on PATH."""
-    version = capture(["temporal", "--version"])
-    if version:
-        console.print(f"  temporal: {version}")
-        return
-    console.print("  temporal: not found, installing globally...")
-    rc = run(["npm", "install", "-g", "temporal-server"], check=False)
-    if rc != 0:
-        console.print(
-            "  [yellow]Warning: temporal install failed. "
-            "Distributed execution unavailable.[/]"
-        )
-        return
-    version = capture(["temporal", "--version"])
-    if version:
-        console.print(f"  temporal: {version}")
-
-
 # ---------------------------------------------------------------- build
 
+
 def build_command() -> None:
     root = project_root()
 
@@ -130,7 +113,7 @@ def build_command() -> None:
     node_version = capture(["node", "--version"])
     console.print(f"  Node.js: {node_version or '[red]not found[/]'}")
     if not node_version:
-        console.print("[red]Error: Node.js is required.[/]")
+        error_block("Node.js is required.", [])
         raise typer.Exit(code=1)
 
     npm_version = capture(["npm", "--version"])
@@ -138,19 +121,18 @@ def build_command() -> None:
 
     python_cmd = _which_python()
     if not python_cmd or not _check_python(python_cmd):
-        console.print(
-            "[red]Error: Python 3.12+ is required.[/] "
-            "Install from https://python.org/downloads/"
+        error_block(
+            "Python 3.12+ is required.",
+            ["Install from https://python.org/downloads/"],
         )
         raise typer.Exit(code=1)
 
     _ensure_uv(python_cmd)
-    _ensure_temporal()
 
     console.print("\n[green]All dependencies ready.[/]\n")
 
     # ---- build steps -------------------------------------------------
-    server_dir = root / "server"
+    server_cwd = server_dir(root)
     env_path = root / ".env"
     template_path = root / ".env.template"
 
@@ -179,9 +161,13 @@ def build_command() -> None:
     run(["pnpm", "--filter", "machinaos-nodejs-executor", "run", "build"], cwd=root)
 
     console.log("[4/6] Installing Python dependencies...")
-    if not (server_dir / ".venv").exists():
-        run(["uv", "venv"], cwd=server_dir)
-    run(["uv", "sync"], cwd=server_dir)
+    # ``server/`` is its own standalone uv project; ``uv sync`` at that
+    # directory resolves ``server/pyproject.toml`` and materialises
+    # ``server/.venv``. The CLI lives in a separate venv (or system
+    # python via pipx) and never shares this environment -- see
+    # ``cli/platform_.py`` docstring for the rationale. ``uv sync``
+    # is idempotent and creates the venv on first run.
+    run(["uv", "sync"], cwd=server_cwd)
 
     # Pre-compile our Python sources to optimised bytecode (.opt-1.pyc).
     # `-O` strips `assert` statements + `__debug__` branches; `-q`
@@ -195,20 +181,24 @@ def build_command() -> None:
     # template files inside packages like crawlee that aren't real Python.
     console.log("[5/6] Compiling Python bytecode...")
     run(
-        ["uv", "run", "python", "-O", "-m", "compileall", "-q", "-j", "0", *COMPILEALL_SOURCE_DIRS],
-        cwd=server_dir,
+        uv_run(
+            "python", "-O", "-m", "compileall", "-q", "-j", "0", *COMPILEALL_SOURCE_DIRS
+        ),
+        cwd=server_cwd,
         check=False,  # missing pyc is non-fatal — runtime regenerates as needed
     )
 
-    console.log("[6/6] Verifying edgymeow binary...")
-    bin_name = "edgymeow-server.exe" if sys.platform == "win32" else "edgymeow-server"
-    edgymeow_bin = root / "node_modules" / "edgymeow" / "bin" / bin_name
-    if edgymeow_bin.exists():
-        console.print(f"  Binary present: {edgymeow_bin}")
-    else:
-        console.print(
-            "  [yellow]Warning: edgymeow binary not found. "
-            "Set WHATSAPP_RUNTIME_ENABLED=false to disable.[/]"
-        )
+    # Temporal is a required runtime dep: fetch + verify the binaries
+    # now so first ``machina start`` is instant instead of paying the
+    # ~90 MB pooch download cost inside ``_pre_spawn``. The ``-m
+    # services.temporal._install`` entry runs ``ensure_temporal_binaries``
+    # then asserts every extracted path exists; non-zero exit aborts
+    # the build via ``run(check=True)``. Idempotent on re-build (pooch
+    # cache hit) so this step is sub-second once the tarball is on disk.
+    console.log("[6/6] Installing Temporal binaries...")
+    run(
+        uv_run("python", "-m", "services.temporal._install"),
+        cwd=server_cwd,
+    )
 
     console.log("[green]Build complete.[/]")