machinaos 0.0.74 → 0.0.76

package/client/package.json

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

package/machina/README.md

@@ -0,0 +1,47 @@
+# machina
+
+Project supervisor CLI for the MachinaOS stack. Replaces `scripts/*.js`
+gradually; backwards-compatible with `pnpm run start`/`dev`/`stop`/etc.
+
+## Install
+
+Done automatically in `scripts/postinstall.js` after `pnpm install`. To
+install manually:
+
+```sh
+python -m pip install -e ./machina
+```
+
+## Use
+
+```sh
+python -m machina --help        # list commands
+python -m machina stop          # kill ports + orphans + temporal
+```
+
+Or via the npm scripts (which now invoke the same Python CLI):
+
+```sh
+pnpm run stop
+```
+
+## Cross-platform notes
+
+- **Windows**: `python` resolves correctly out of the box.
+- **macOS / Linux**: requires `python` to point to Python 3.11+. Most
+  modern distros provide this via `python-is-python3` or a symlink. If
+  your distro only ships `python3`, run `python3 -m machina <cmd>` or
+  add an alias.
+
+## Architecture
+
+Built on battle-tested primitives — minimal custom code:
+
+| Layer | Library |
+|---|---|
+| CLI | `typer` |
+| Subprocess | `anyio.open_process` |
+| Tree-kill | `psutil` + `pywin32` (Job Objects on Windows) |
+| Restart backoff | stdlib (deque + monotonic time + jittered exponential, ~20 LOC) |
+| Output | `rich.Console` |
+| Env | `python-dotenv` |

package/machina/__init__.py

@@ -0,0 +1,3 @@
+"""MachinaOS project supervisor CLI."""
+
+__version__ = "0.1.0"

package/machina/__main__.py

@@ -0,0 +1,35 @@
+"""Entry point for ``python -m machina``.
+
+pnpm scripts call ``python -m machina ...`` from the system Python,
+which only has ``uv`` -- not typer / rich / anyio / psutil. On first
+run we detect the missing imports, pip-install the declared runtime
+deps, and retry, so the user never has to ``pip install -e .`` by hand.
+"""
+
+import subprocess
+import sys
+
+_RUNTIME_DEPS = (
+    "typer>=0.12",
+    "rich>=13.0",
+    "anyio>=4.0",
+    "psutil>=6.0",
+)
+
+
+def _bootstrap_deps() -> None:
+    print("machina: installing runtime dependencies (first run)...", file=sys.stderr)
+    subprocess.check_call(
+        [sys.executable, "-m", "pip", "install", "--quiet", *_RUNTIME_DEPS]
+    )
+
+
+try:
+    from machina.cli import app
+except ImportError:
+    _bootstrap_deps()
+    from machina.cli import app
+
+
+if __name__ == "__main__":
+    app()

package/machina/buildenv.py

@@ -0,0 +1,44 @@
+"""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.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import typer
+
+from machina.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
+
+
+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 (root / "node_modules").exists() or not (root / "server" / ".venv").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():
+        console.print('[red]Error: Client not built. Run "machina build" first.[/]')
+        raise typer.Exit(code=1)

package/machina/cli.py

@@ -0,0 +1,55 @@
+"""Typer CLI for ``machina``.
+
+Each subcommand lives under ``machina.commands``; this module just
+mounts them and exposes ``app`` as the entry point.
+"""
+
+from __future__ import annotations
+
+import typer
+
+from machina.commands.build import build_command
+from machina.commands.clean import clean_command
+from machina.commands.daemon import app as daemon_app
+from machina.commands.dev import dev_command
+from machina.commands.docs import app as docs_app
+from machina.commands.start import start_command
+from machina.commands.stop import stop_command
+from machina.commands.version import app as version_app
+
+
+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."""
+
+
+app.command("start", help="Start all services in production mode (static client + uvicorn + temporal).")(
+    start_command
+)
+app.command("dev", help="Start all services in dev mode (Vite HMR + uvicorn + temporal).")(
+    dev_command
+)
+app.command("stop", help="Stop all MachinaOS services and free configured ports.")(
+    stop_command
+)
+app.command("clean", help="Stop services then remove build artefacts and venvs.")(
+    clean_command
+)
+app.command("build", help="Install toolchain + build client + sync Python + verify deps.")(
+    build_command
+)
+app.add_typer(version_app, name="version")
+app.add_typer(docs_app, name="docs")
+app.add_typer(daemon_app, name="daemon")
+
+
+if __name__ == "__main__":
+    app()

package/machina/colors.py

@@ -0,0 +1,47 @@
+"""Rich console + per-service color rotation (Honcho-style).
+
+Latency-analysis hook: ``emit`` routes through ``Console.log`` instead of
+``Console.print``, which prepends a built-in timestamp column. The console
+is configured with ``log_time_format=[%H:%M:%S.%f]`` for ms precision and
+``log_path=False`` to drop the file:line caller info that rich adds by
+default. ``console.print`` callers (banner / step headers) remain timestamp-
+less so the launch banner stays readable.
+"""
+
+from __future__ import annotations
+
+from itertools import cycle
+from rich.console import Console
+
+
+# Single shared console — single-writer aggregator avoids interleaving
+# concurrent stream output (VS Code's pty host pattern). ``log_*`` settings
+# only affect ``console.log`` calls; ``console.print`` is unaffected.
+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",
+]
+_color_cycle = cycle(_PALETTE)
+
+
+def next_color() -> str:
+    return next(_color_cycle)
+
+
+def emit(name: str, color: str, line: str, *, stream: str = "stdout") -> None:
+    """Print one line tagged with the service name + color, timestamped.
+
+    Renders as ``[14:23:45.123] cyan         | <message>``. The timestamp
+    column is added by ``console.log``; prefix width stays uniform so
+    side-by-side latency comparison across services lines up visually.
+    """
+    width = 12
+    prefix = f"[{color}]{name:<{width}}[/{color}]"
+    style = "" if stream == "stdout" else "[dim]"
+    suffix = "" if stream == "stdout" else "[/dim]"
+    console.log(f"{prefix}{style} | {line}{suffix}", highlight=False)

package/machina/commands/__init__.py

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

package/machina/commands/build.py

@@ -0,0 +1,170 @@
+"""``machina build`` -- replaces ``scripts/build.js``.
+
+Checks toolchain (node, npm, python, uv, temporal-server), then runs
+the 4-step build: ``.env`` bootstrap -> ``pnpm install`` -> client
+build -> ``uv sync`` -> verify edgymeow binary.
+
+The ``MACHINAOS_BUILDING`` env var is set so ``scripts/postinstall.js``
+skips its own ``install.js`` invocation when build is the orchestrator.
+"""
+
+from __future__ import annotations
+
+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
+
+
+# ---------------------------------------------------------------- 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"):
+        if shutil.which(cmd):
+            return cmd
+    return None
+
+
+def _check_python(cmd: str) -> bool:
+    out = capture([cmd, "--version"])
+    if not out:
+        return False
+    match = re.search(r"Python (\d+)\.(\d+)", out)
+    if not match:
+        return False
+    major, minor = int(match.group(1)), int(match.group(2))
+    if major >= 3 and minor >= 12:
+        console.print(f"  {out}")
+        return True
+    console.print(f"  {out} [red](too old, need 3.12+)[/]")
+    return False
+
+
+def _ensure_pip(python_cmd: str) -> None:
+    if not capture([python_cmd, "-m", "pip", "--version"]):
+        console.print("  Installing pip via ensurepip...")
+        run([python_cmd, "-m", "ensurepip", "--upgrade"])
+
+
+def _ensure_uv(python_cmd: str) -> str:
+    """Install ``uv`` via pip if missing; return the resolved version string."""
+    version = capture(["uv", "--version"])
+    if version:
+        console.print(f"  uv: {version}")
+        return version
+    _ensure_pip(python_cmd)
+    console.print("  Installing uv via pip...")
+    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/[/]")
+        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()
+
+    # Prevent the postinstall orchestrator from re-running install.js when
+    # we're orchestrating ourselves (matches the existing JS contract).
+    os.environ["MACHINAOS_BUILDING"] = "true"
+    os.environ.setdefault("PYTHONUTF8", "1")
+
+    is_postinstall = os.environ.get("npm_lifecycle_event") == "postinstall"
+    is_ci = os.environ.get("CI") == "true" or os.environ.get("GITHUB_ACTIONS") == "true"
+    if is_ci and is_postinstall:
+        console.print("CI environment detected, skipping postinstall build.")
+        return
+
+    # ---- toolchain ---------------------------------------------------
+    console.print("[bold]Checking dependencies...[/]\n")
+    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.[/]")
+        raise typer.Exit(code=1)
+
+    npm_version = capture(["npm", "--version"])
+    console.print(f"  npm: {npm_version or '[red]not found[/]'}")
+
+    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/"
+        )
+        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"
+    env_path = root / ".env"
+    template_path = root / ".env.template"
+
+    # Step markers go through ``console.log`` so each [N/5] line is
+    # timestamped — diff between consecutive timestamps is the wall-clock
+    # cost of that step, no manual instrumentation needed.
+    if not env_path.exists() and template_path.exists():
+        shutil.copy2(template_path, env_path)
+        console.log("[0/5] Created .env from template")
+
+    if not is_postinstall:
+        console.log("[1/5] Installing dependencies...")
+        run(["pnpm", "install"], cwd=root)
+    else:
+        console.log("[1/5] Dependencies already installed by package manager")
+
+    console.log("[2/5] Building client...")
+    run(["pnpm", "--filter", "react-flow-client", "run", "build"], cwd=root)
+
+    console.log("[3/4] Installing Python dependencies...")
+    if not (server_dir / ".venv").exists():
+        run(["uv", "venv"], cwd=server_dir)
+    run(["uv", "sync"], cwd=server_dir)
+
+    console.log("[4/4] 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.[/]"
+        )
+
+    console.log("[green]Build complete.[/]")

package/machina/commands/clean.py

@@ -0,0 +1,80 @@
+"""``machina clean`` -- replaces ``scripts/clean.js``.
+
+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 machina.colors import console
+from machina.config import load_config
+from machina.platform_ import project_root
+from machina.ports import kill_orphaned_machina_processes, kill_port
+
+
+# Removed each run -- order doesn't matter, ``shutil.rmtree`` is recursive.
+_TARGETS = [
+    "node_modules",
+    "client/node_modules",
+    "client/dist",
+    "client/.vite",
+    "server/data",       # workflow.db, credentials.db, workspaces/
+    "server/.venv",
+    ".venv",             # stale root venv (should not exist)
+]
+
+
+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:
+                console.print(f"  [yellow]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")
+
+    # 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)
+        if result.killed_pids:
+            console.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)
+    orphaned = kill_orphaned_machina_processes(str(root), exclude_substring="machina")
+    if orphaned:
+        console.print(f"  Orphaned: Killed {len(orphaned)} process(es)")
+
+    if killed_ports or orphaned:
+        console.print("  Waiting for processes to release file locks...")
+        time.sleep(1.0)
+    else:
+        console.print("  No running processes found.")
+
+    # Step 3: remove directories
+    console.print("\nRemoving directories...")
+    for target in _TARGETS:
+        path = root / target
+        if path.exists():
+            console.print(f"  Removing: {target}")
+            _rmtree_with_retry(path)
+
+    console.print("\n[green]Done.[/]")

package/machina/commands/daemon.py

@@ -0,0 +1,150 @@
+"""``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 os
+import signal
+import subprocess
+import sys
+from pathlib import Path
+
+import psutil
+import typer
+
+from machina.buildenv import venv_python
+from machina.colors import console
+from machina.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
+
+
+@app.command("start")
+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})")
+
+
+@app.command("stop")
+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}[/]")
+
+
+@app.command("status")
+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}[/]")
+
+
+@app.command("restart")
+def restart_command() -> None:
+    """Stop then start; convenience wrapper."""
+    stop_command()
+    start_command()