machinaos 0.0.87 → 0.0.89

package/.env.template

@@ -86,6 +86,26 @@ TEMPORAL_GRACEFUL_SHUTDOWN_SECONDS=30
 # didn't pre-cache it.
 TEMPORAL_SERVER_READY_TIMEOUT_SECONDS=120
 
+# --- Startup resilience (server-ready-before-workers) ---
+# After the gRPC port binds, the client polls the WorkflowService gRPC
+# health check until it reports SERVING before starting the worker /
+# visibility sweep (the documented readiness probe; see
+# https://docs.temporal.io/troubleshooting/deadline-exceeded-error).
+# Bounded — the unbounded layer is main.py's 3s reconnect loop.
+TEMPORAL_HEALTH_CHECK_ATTEMPTS=5
+TEMPORAL_HEALTH_CHECK_DELAY_SECONDS=0.5
+TEMPORAL_HEALTH_CHECK_TIMEOUT_SECONDS=2.0
+# The boot-time terminate-running sweep issues a Visibility query that
+# races shard acquisition ("shard status unknown"). Retry it a few times
+# (linear backoff = attempt x base) before giving up for that boot.
+TEMPORAL_SWEEP_ATTEMPTS=4
+TEMPORAL_SWEEP_BACKOFF_SECONDS=0.5
+# The embedded worker self-restarts on a transient crash (the Temporal
+# worker shuts down on a poll failure rather than auto-retrying). Backoff
+# doubles from base up to max between restarts.
+TEMPORAL_WORKER_RESTART_BACKOFF_SECONDS=1.0
+TEMPORAL_WORKER_RESTART_BACKOFF_MAX_SECONDS=30.0
+
 # Wave 12 event framework. ``true`` (default) routes trigger events
 # through TriggerListenerWorkflow + Temporal Signal fan-out for the
 # 8 canary-registered trigger types (webhook, chat, task, telegram,
@@ -98,6 +118,25 @@ EVENT_FRAMEWORK_ENABLED=true
 # context-window threshold. Per-session overrides via the UI.
 COMPACTION_ENABLED=true
 
+# Compaction trigger threshold as a fraction of the model's context
+# window (0.05 - 0.99). 0.8 = compact when cumulative tokens hit 80%.
+# Per-user overrides via the UserSettings row (Settings tab).
+COMPACTION_RATIO=0.8
+
+# Agent loop hard step cap. AI Agent + Chat Agent stop the LLM/tool
+# iteration loop after this many rounds and return a truncation note.
+# Per-user overrides via the UserSettings row (Settings tab).
+AGENT_RECURSION_LIMIT=200
+
+# Browser automation (agent-browser CLI). Each distinct browser
+# session maps to one Chrome instance. BROWSER_MAX_INSTANCES caps
+# concurrent instances — when a new session would exceed it, the
+# least-recently-used session is closed first. BROWSER_IDLE_TIMEOUT_MS
+# makes the agent-browser daemon close its browser after that many
+# milliseconds without commands (0 disables).
+BROWSER_MAX_INSTANCES=3
+BROWSER_IDLE_TIMEOUT_MS=600000
+
 # Dead-letter queue for failed workflow executions. Off by default.
 DLQ_ENABLED=false
 

package/.machina/workflows/AI Assistant_example_workflow-1779017037684-e2e5da7a.json

@@ -603,7 +603,7 @@
     "aiAgent-177920047601512-ce3047": {
       "prompt": "{{chattrigger.message}} {{telegramreceive.text}}",
       "provider": "gemini",
-      "model": "gemini-flash-latest",
+      "model": "gemini-3.5-flash",
       "system_message": "You are a helpful assistant",
       "label": "AI Agent"
     },

package/.machina/workflows/AI Employee_example_workflow-1779102911870-cbc76c82.json

@@ -2160,7 +2160,7 @@
     },
     "chatAgent-177920047617122-dbe3b7": {
       "provider": "gemini",
-      "model": "gemini-flash-latest",
+      "model": "gemini-3.5-flash",
       "prompt": "{{chattrigger.message}} {{telegramreceive.text}}",
       "system_message": "",
       "label": "Zeenie"
@@ -2233,35 +2233,35 @@
     "coding_agent-177920047617125-dbe3b7": {
       "prompt": "",
       "provider": "gemini",
-      "model": "gemini-flash-latest",
+      "model": "gemini-3.5-flash",
       "system_message": "You are a helpful assistant",
       "label": "Coding Agent"
     },
     "productivity_agent-177920047617126-dbe3b7": {
       "prompt": "",
       "provider": "gemini",
-      "model": "gemini-flash-latest",
+      "model": "gemini-3.5-flash",
       "system_message": "You are a helpful assistant",
       "label": "Productivity Agent"
     },
     "travel_agent-177920047617127-dbe3b7": {
       "prompt": "",
       "provider": "gemini",
-      "model": "gemini-flash-latest",
+      "model": "gemini-3.5-flash",
       "system_message": "You are a helpful assistant",
       "label": "Travel Agent"
     },
     "web_agent-177920047617128-dbe3b7": {
       "prompt": "",
       "provider": "gemini",
-      "model": "gemini-flash-latest",
+      "model": "gemini-3.5-flash",
       "system_message": "You are a helpful assistant",
       "label": "Web Agent"
     },
     "social_agent-177920047617129-dbe3b7": {
       "prompt": "",
       "provider": "gemini",
-      "model": "gemini-flash-latest",
+      "model": "gemini-3.5-flash",
       "system_message": "You are a helpful assistant",
       "label": "Social Agent"
     },

package/README.md

@@ -104,13 +104,13 @@ RAG pipeline out of the box: parse PDFs and HTML, chunk into searchable pieces,
 | Provider     | Notes                                                                    |
 |--------------|--------------------------------------------------------------------------|
 | OpenAI       | GPT-5 family, GPT-4.1, o-series reasoning models, GPT-4o                 |
-| Anthropic    | Claude Opus 4.x, Sonnet 4.x, Haiku 4.5 — with extended thinking          |
+| Anthropic    | Claude Fable 5, Opus 4.x, Sonnet 4.6, Haiku 4.5 — with extended thinking |
 | Google       | Gemini 3 Pro/Flash, 2.5 Pro/Flash — with reasoning budgets               |
-| DeepSeek     | DeepSeek V3, DeepSeek Reasoner                                           |
-| Kimi         | Kimi K2.5, Kimi K2 Thinking                                              |
-| Mistral      | Mistral Large/Small, Codestral                                           |
-| Groq         | Llama 3/4, Qwen3, GPT-OSS (ultra-fast inference)                         |
-| Cerebras     | Llama 3.1, Qwen-3-235b (custom AI hardware)                              |
+| DeepSeek     | DeepSeek V4 (Flash/Pro); chat/reasoner legacy aliases                    |
+| Kimi         | Kimi K2.6, K2.5, K2.7-Code                                               |
+| Mistral      | Mistral Large/Medium/Small, Codestral                                   |
+| Groq         | Llama 3.x, Qwen3, GPT-OSS (ultra-fast inference)                         |
+| Cerebras     | GPT-OSS-120b, Qwen-3-235b, GLM-4.7 (custom AI hardware)                  |
 | OpenRouter   | 200+ models via one unified API                                          |
 | **Ollama**   | Run any local model on your machine — free, private, offline             |
 | **LM Studio**| Run any local model with a desktop app — free, private, offline          |

package/bin/cli.js

@@ -11,6 +11,8 @@ const PKG = JSON.parse(readFileSync(resolve(ROOT, 'package.json'), 'utf-8'));
 const COMMANDS = {
   start: 'Start in production mode',
   dev: 'Start development server (hot-reload)',
+  serve: 'Serve on a single public port (API + WS + SPA; used by deploy)',
+  deploy: 'Provision a cloud VM running MachinaOs (Terraform)',
   stop: 'Stop all running services',
   build: 'Build the project for production',
   clean: 'Clean build artifacts',
@@ -175,9 +177,12 @@ if (cmd === 'help' || cmd === '--help' || cmd === '-h') {
   console.log(`machina v${PKG.version}`);
 } else if (cmd === 'doctor') {
   doctor();
-} else if (cmd === 'start' || cmd === 'dev' || cmd === 'build') {
+} else if (cmd === 'start' || cmd === 'dev' || cmd === 'build' || cmd === 'serve') {
   checkDeps();
   run(cmd, process.argv.slice(3));
+} else if (cmd === 'deploy') {
+  // Needs sub-verb + flags forwarded (up/status/destroy --provider ...).
+  run(cmd, process.argv.slice(3));
 } else if (COMMANDS[cmd]) {
   run(cmd);
 } else {

package/cli/cli.py

@@ -90,6 +90,22 @@ def _build() -> None:
     build_command()
 
 
+@app.command(
+    "serve",
+    help="Run on a single public port (API + WebSocket + built SPA + sidecar). Used by `machina deploy`.",
+)
+def _serve(
+    port: int | None = typer.Option(
+        None,
+        "--port",
+        help="Public port (default: $PORT, else PYTHON_BACKEND_PORT).",
+    ),
+) -> None:
+    from cli.commands.serve import serve_command
+
+    serve_command(port=port)
+
+
 # --------------------------------------------------------------- daemon group
 
 daemon_app = typer.Typer(
@@ -143,6 +159,77 @@ def _daemon_restart() -> None:
 app.add_typer(daemon_app, name="daemon")
 
 
+# --------------------------------------------------------------- deploy group
+
+deploy_app = typer.Typer(
+    name="deploy",
+    help="Provision a fresh cloud VM running MachinaOs (via Terraform).",
+    no_args_is_help=True,
+    add_completion=False,
+)
+
+
+@deploy_app.command(
+    "up",
+    help="Create the 'machinaos' VM, install MachinaOs behind the login gate, and run it.",
+)
+def _deploy_up(
+    provider: str = typer.Option("gcp", "--provider", help="Cloud provider: gcp (aws is a follow-on)."),
+    owner_email: str = typer.Option(..., "--owner-email", help="Login email for the owner account."),
+    owner_password: str | None = typer.Option(
+        None, "--owner-password", help="Login password (>=8 chars). Generated + printed once if omitted."
+    ),
+    source: str = typer.Option("local", "--source", help="Install source: local (npm pack) or release (npm registry)."),
+    version: str = typer.Option("latest", "--version", help="machinaos version when --source release."),
+    machine_type: str = typer.Option("e2-standard-2", "--machine-type", help="VM size."),
+    port: int = typer.Option(8080, "--port", help="Public port the app binds + the firewall opens."),
+    allow_cidr: str = typer.Option("0.0.0.0/0", "--allow-cidr", help="Firewall source range (restrict to your IP/32)."),
+    region: str | None = typer.Option(None, "--region", help="Cloud region (provider default if omitted)."),
+    zone: str | None = typer.Option(None, "--zone", help="Cloud zone (provider default if omitted)."),
+    project: str | None = typer.Option(None, "--project", help="GCP project (defaults to gcloud config)."),
+) -> None:
+    from cli.commands.deploy.up import up_command
+
+    up_command(
+        provider=provider,
+        region=region,
+        zone=zone,
+        machine_type=machine_type,
+        port=port,
+        owner_email=owner_email,
+        owner_password=owner_password,
+        source=source,
+        version=version,
+        allow_cidr=allow_cidr,
+        project=project,
+    )
+
+
+@deploy_app.command(
+    "status",
+    help="Show the 'machinaos' deployment's URL + health.",
+)
+def _deploy_status() -> None:
+    from cli.commands.deploy.status import status_command
+
+    status_command()
+
+
+@deploy_app.command(
+    "destroy",
+    help="Terraform-destroy the 'machinaos' deployment and remove its local state.",
+)
+def _deploy_destroy(
+    keep_state: bool = typer.Option(False, "--keep-state", help="Keep the local Terraform state dir."),
+) -> None:
+    from cli.commands.deploy.destroy import destroy_command
+
+    destroy_command(keep_state=keep_state)
+
+
+app.add_typer(deploy_app, name="deploy")
+
+
 # ----------------------------------------------------------------- docs group
 
 docs_app = typer.Typer(

package/cli/commands/build.py

@@ -1,8 +1,17 @@
 """``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.
+Checks toolchain (node, npm, python, uv), then runs the 6-step
+build: ``.env`` bootstrap -> ``pnpm install`` -> client build ->
+Node.js sidecar bundle -> ``uv sync`` -> compile Python bytecode
+-> pooch-fetch Temporal binary.
+
+Layers ``.env.dev`` (when present in the checkout) BEFORE running
+those steps so the build's ``DATA_DIR`` matches the runtime's
+expected location. Without that, ``machina build`` would pooch
+Temporal under ``~/.machina/`` and ``machina dev`` would re-fetch
+it into ``<repo>/.machina/`` — a redundant download on every fresh
+clone. Production (global-install) operators never have
+``.env.dev`` in their checkout, so the layering is a no-op there.
 
 The ``MACHINAOS_BUILDING`` env var is set so ``scripts/postinstall.js``
 skips its own ``install.js`` invocation when build is the orchestrator.
@@ -97,6 +106,27 @@ def _ensure_uv(python_cmd: str) -> str:
 def build_command() -> None:
     root = project_root()
 
+    # Layer ``.env.dev`` (if present) BEFORE the install steps so the
+    # build's ``DATA_DIR`` matches what the runtime (``machina dev``)
+    # will see. Without this, ``machina build`` reads
+    # ``DATA_DIR=~/.machina`` from ``.env.template`` and lands the
+    # Temporal CLI under user home, but ``machina dev`` then reads
+    # ``DATA_DIR=.machina`` from ``.env.dev`` and re-downloads into
+    # ``<repo>/.machina/`` — a cache-miss the operator pays on every
+    # fresh checkout.
+    #
+    # Safe for global installs: ``.env.dev`` is committed to git for
+    # repo-clone contributors but is NOT in the npm ``files`` list, so
+    # ``npm install -g machinaos`` doesn't ship it. Without
+    # ``.env.dev`` on disk, :func:`load_dev_overrides` is a no-op and
+    # the build falls through to ``.env.template`` defaults
+    # (``DATA_DIR=~/.machina``) — identical to today's behaviour and
+    # matching what ``machina start`` / ``machina daemon`` use at
+    # runtime.
+    from cli.config import load_dev_overrides
+
+    load_dev_overrides(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"

package/cli/commands/clean.py

@@ -44,10 +44,19 @@ _TARGETS = [
 # ``.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"})
+# it would force the operator to re-clone to recover. ``deploy/``
+# holds ``machina deploy``'s Terraform working dirs + state files:
+# deleting state for LIVE cloud resources orphans the VM/firewall
+# (``machina deploy destroy`` could no longer find them) -- only
+# ``deploy destroy`` removes that tree. ``packages/`` holds the
+# MachinaOs-managed binaries (Temporal CLI ~114 MB, Stripe CLI, the
+# shared npm tree with claude/agent-browser/edgymeow): all of it is
+# re-fetchable but expensive -- wiping it forced a full Temporal
+# re-download on every clean+build cycle, which hard-fails ``machina
+# build`` on slow links. Anything else under ``.machina/`` (claude
+# state, workspaces, credentials.db, ...) is transient runtime state
+# and is fair game.
+_MACHINA_KEEP = frozenset({"workflows", "deploy", "packages"})
 
 
 def _rmtree_with_retry(path: Path, *, attempts: int = 3, delay: float = 0.1) -> bool:

package/cli/commands/deploy/__init__.py

@@ -0,0 +1,13 @@
+"""``machina deploy`` -- provision a fresh cloud VM running MachinaOs.
+
+A thin wrapper over **Terraform**: the command generates secrets + a tfvars
+file and drives ``terraform init/apply/destroy``. Terraform owns every cloud
+resource (VM, firewall, optional artifact bucket) declaratively, with its own
+state. Per-provider root modules live under ``cli/terraform/<provider>/`` and
+share one variable interface, so a new provider is one new module + no CLI
+change.
+
+The Typer group is assembled in ``cli/cli.py`` (lazy-wrapped leaves), mirroring
+the ``daemon`` group; this package just holds the verb implementations + shared
+helpers (``_config`` / ``_secrets`` / ``_state`` / ``_terraform``).
+"""

package/cli/commands/deploy/_secrets.py

@@ -0,0 +1,65 @@
+"""Secret + environment generation for ``machina deploy``.
+
+Generates the cryptographic keys + owner password the login gate needs, and
+assembles the full env-var map (``app_env``) that Terraform renders into the
+VM's ``/etc/machinaos/machina.env`` (a systemd ``EnvironmentFile``). The map
+carries only the deployment overrides + secrets; the VM's ``.env`` (copied
+from ``.env.template`` by the package build) supplies the rest of the required
+settings, and OS env (the EnvironmentFile) wins over ``.env`` in
+pydantic-settings.
+"""
+
+from __future__ import annotations
+
+import secrets
+import string
+
+_PW_ALPHABET = string.ascii_letters + string.digits
+
+
+def new_key() -> str:
+    """48-char hex secret (>= the 32-char minimum the app enforces)."""
+    return secrets.token_hex(24)
+
+
+def new_password(length: int = 20) -> str:
+    """Strong alphanumeric password (avoids shell/systemd-quoting pitfalls)."""
+    return "".join(secrets.choice(_PW_ALPHABET) for _ in range(length))
+
+
+def build_app_env(
+    *,
+    owner_email: str,
+    owner_password: str,
+    port: int,
+    data_dir: str = "/var/lib/machinaos",
+) -> dict[str, str]:
+    """The systemd EnvironmentFile map: gate overrides + freshly minted secrets.
+
+    JWT/SECRET/ENCRYPTION keys are generated per deploy. ``JWT_COOKIE_SECURE``
+    is ``false`` because the VM is reached over plain HTTP on its IP; flip to
+    true once a domain + TLS terminator is in front. Temporal/Redis/event
+    framework are off (local execution).
+    """
+    return {
+        "HOST": "0.0.0.0",
+        "PORT": str(port),
+        "DATA_DIR": data_dir,
+        "WORKSPACE_BASE_DIR": "workspaces",
+        "SERVE_STATIC_CLIENT": "true",
+        "VITE_AUTH_ENABLED": "true",
+        "AUTH_MODE": "single",
+        "JWT_COOKIE_SECURE": "false",
+        "JWT_COOKIE_SAMESITE": "lax",
+        "TEMPORAL_ENABLED": "false",
+        "EVENT_FRAMEWORK_ENABLED": "false",
+        "REDIS_ENABLED": "false",
+        "NODEJS_EXECUTOR_PORT": "3020",
+        "LOG_FORMAT": "text",
+        "JWT_SECRET_KEY": new_key(),
+        "SECRET_KEY": new_key(),
+        "API_KEY_ENCRYPTION_KEY": new_key(),
+        "MACHINA_OWNER_EMAIL": owner_email,
+        "MACHINA_OWNER_NAME": "Owner",
+        "MACHINA_OWNER_PASSWORD": owner_password,
+    }

package/cli/commands/deploy/_state.py

@@ -0,0 +1,56 @@
+"""Working dir + metadata for the (single) ``machina deploy`` deployment.
+
+The VM instance is always named ``machinaos`` (one deployment per project), so
+the working dir is fixed at ``<user-data>/deploy/machinaos/``. That directory
+is BOTH the Terraform working dir (rendered module + ``terraform.tfvars.json``
++ local state) and the home of a small ``deploy-meta.json`` (provider + port +
+owner email) used by ``status`` / ``destroy``.
+
+No module-level side effects -- ``user_data_dir`` (platformdirs) is only
+resolved when a function is called.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from cli.platform_ import user_data_dir
+
+#: The fixed instance / deployment name.
+NAME = "machinaos"
+
+_META_FILENAME = "deploy-meta.json"
+
+
+def deploy_root() -> Path:
+    return user_data_dir() / "deploy"
+
+
+def workdir() -> Path:
+    """Terraform working dir + state location for the deployment."""
+    return deploy_root() / NAME
+
+
+def meta_file() -> Path:
+    return workdir() / _META_FILENAME
+
+
+def write_meta(meta: dict) -> None:
+    wd = workdir()
+    wd.mkdir(parents=True, exist_ok=True)
+    meta_file().write_text(json.dumps(meta, indent=2), encoding="utf-8")
+
+
+def read_meta() -> dict | None:
+    mf = meta_file()
+    if not mf.exists():
+        return None
+    try:
+        return json.loads(mf.read_text(encoding="utf-8"))
+    except (ValueError, OSError):
+        return None
+
+
+def exists() -> bool:
+    return meta_file().exists()

package/cli/commands/deploy/_terraform.py

@@ -0,0 +1,68 @@
+"""Terraform driver for ``machina deploy``.
+
+Thin helpers over the ``terraform`` CLI (via ``cli.run``): preflight that it
+exists, copy the chosen provider module into the deployment working dir, write
+``terraform.tfvars.json``, and run init/apply/output/destroy. The CLI never
+talks to a cloud API directly -- Terraform's providers do, using the same
+credentials the cloud CLIs use (gcloud ADC / AWS default chain).
+"""
+
+from __future__ import annotations
+
+import json
+import shutil
+from pathlib import Path
+
+import typer
+
+from cli._common import error_block
+from cli.platform_ import project_root
+from cli.run import capture, run
+
+
+def ensure_terraform() -> None:
+    """Abort with guidance if the ``terraform`` binary is not on PATH."""
+    if capture(["terraform", "version"]) is None:
+        error_block(
+            "Terraform is required but was not found on PATH.",
+            [
+                "Install it: https://developer.hashicorp.com/terraform/install",
+                "Then re-run `machina deploy up`.",
+            ],
+        )
+        raise typer.Exit(code=1)
+
+
+def module_src(provider: str) -> Path:
+    """Path to the shipped HCL module for ``provider``."""
+    return project_root() / "cli" / "terraform" / provider
+
+
+def prepare_workdir(workdir: Path, provider: str) -> None:
+    """Copy the provider module's files into ``workdir`` (preserving state)."""
+    src = module_src(provider)
+    if not src.is_dir():
+        error_block(
+            f"No Terraform module for provider {provider!r}.",
+            [f"Expected at {src}", "Supported today: gcp (aws is a follow-on)."],
+        )
+        raise typer.Exit(code=1)
+    workdir.mkdir(parents=True, exist_ok=True)
+    # Copy module sources (*.tf, *.tftpl). Never touch tfstate / tfvars / meta.
+    for f in src.iterdir():
+        if f.is_file() and f.suffix in (".tf", ".tftpl"):
+            shutil.copy2(f, workdir / f.name)
+
+
+def write_tfvars(workdir: Path, variables: dict) -> None:
+    (workdir / "terraform.tfvars.json").write_text(
+        json.dumps(variables, indent=2), encoding="utf-8"
+    )
+
+
+def tf(workdir: Path, *args: str, check: bool = True) -> int:
+    return run(["terraform", *args], cwd=workdir, check=check)
+
+
+def tf_output(workdir: Path, name: str) -> str | None:
+    return capture(["terraform", "output", "-raw", name], cwd=workdir)

package/cli/commands/deploy/destroy.py

@@ -0,0 +1,34 @@
+"""``machina deploy destroy`` -- tear down the deployment's cloud resources."""
+
+from __future__ import annotations
+
+import shutil
+
+import typer
+
+from cli._common import preflight
+from cli.colors import console
+
+from . import _state, _terraform
+
+
+def destroy_command(*, keep_state: bool = False) -> None:
+    # Establish the same DATA_DIR context as `deploy up` so workdir() matches.
+    preflight()
+    meta = _state.read_meta()
+    if meta is None:
+        console.print("[yellow]No 'machinaos' deployment found.[/]")
+        raise typer.Exit(code=1)
+
+    _terraform.ensure_terraform()
+    wd = _state.workdir()
+
+    console.log("terraform destroy (machinaos)...")
+    _terraform.tf(wd, "destroy", "-auto-approve", "-input=false")
+
+    if keep_state:
+        console.print(f"  Destroyed. State kept at {wd}")
+        return
+
+    shutil.rmtree(wd, ignore_errors=True)
+    console.print("  [green]Destroyed[/] and removed local state for 'machinaos'.")

package/cli/commands/deploy/providers/__init__.py

@@ -0,0 +1,34 @@
+"""Provider CLI adapters -- Stage 1 of ``machina deploy``.
+
+Each adapter wraps the operator's already-installed cloud CLI (gcloud / aws)
+to verify it is present + authenticated, resolve the project/region/zone,
+ensure Terraform can authenticate with the same credentials, and enable the
+required cloud APIs. Adapters create NO cloud resources -- Terraform (Stage 2)
+does that, inheriting the CLI's credentials.
+"""
+
+from __future__ import annotations
+
+import typer
+
+from ._base import ProviderCli
+
+
+def get_provider(name: str) -> ProviderCli:
+    """Resolve the CLI adapter for ``name`` (lazy-imports the impl)."""
+    if name == "gcp":
+        from .gcp import GcpCli
+
+        return GcpCli()
+    if name == "aws":
+        from .aws import AwsCli
+
+        return AwsCli()
+
+    from cli._common import error_block
+
+    error_block(f"Unknown provider {name!r}.", ["Supported: gcp (aws is a follow-on)."])
+    raise typer.Exit(code=1)
+
+
+__all__ = ["ProviderCli", "get_provider"]

package/cli/commands/deploy/providers/_base.py

@@ -0,0 +1,46 @@
+"""The provider-CLI adapter contract (Stage 1 of ``machina deploy``)."""
+
+from __future__ import annotations
+
+from typing import Protocol
+
+
+class ProviderCli(Protocol):
+    """Auth + context + API-enablement over a cloud provider's own CLI.
+
+    All methods shell out via ``cli.run``; failures abort with ``typer.Exit``
+    and ``error_block`` remediation. None of these create cloud resources --
+    Terraform (Stage 2) owns that, using the credentials these methods verify.
+    """
+
+    name: str
+
+    def check(self) -> None:
+        """Abort unless the provider CLI binary is on PATH."""
+        ...
+
+    def authed_account(self) -> str | None:
+        """Return the logged-in identity, or ``None`` if not authenticated."""
+        ...
+
+    def resolve_context(
+        self, *, region: str | None, zone: str | None, project: str | None
+    ) -> dict:
+        """Resolve + validate ``{project, region, zone, ...}`` from CLI config + flags.
+
+        Aborts (with guidance) if the CLI is not logged in or required context
+        (e.g. a GCP project) is missing.
+        """
+        ...
+
+    def ensure_terraform_auth(self) -> None:
+        """Ensure Terraform's provider can authenticate (e.g. gcloud ADC)."""
+        ...
+
+    def enable_apis(self, ctx: dict) -> None:
+        """Enable the cloud APIs Terraform will need."""
+        ...
+
+    def tfvars_extra(self, ctx: dict) -> dict:
+        """Provider-specific tfvars keys merged into the deployment's tfvars."""
+        ...