avr-cli 0.1.6__tar.gz → 0.2.0__tar.gz

{avr_cli-0.1.6 → avr_cli-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: avr-cli
-Version: 0.1.6
+Version: 0.2.0
 Summary: Avrea command-line client
 Author-email: Avrea <support@avrea.com>
 License-Expression: Apache-2.0
@@ -157,6 +157,26 @@ avr job metrics <job-id> --watch       # CPU/memory/IO gauges, refreshed every f
 avr job metrics <job-id>               # static post-mortem after the job ended
 ```
 
+**Long-running dev VMs**
+
+Durable, org-scoped VMs reachable over SSH (plus RDP/VNC for a desktop), separate from job VMs. Create one with your key, then set it up in a single command:
+
+```sh
+avr vm create --name dev --os linux --size 2-vcpu \
+  --ssh-key @~/.ssh/id_ed25519.pub --ephemeral --wait      # boot, wait for SSH, print connect
+avr vm create --name ci --os linux --size 8-vcpu --ephemeral \
+  --repo org/project --disable-cache gha,packages          # attach a repo, narrow which caches it uses
+avr vm bootstrap <vm-id> --setup-github --install claude,codex \
+  --repo https://github.com/org/project --env AWS_REGION=eu-north-1
+avr vm ssh <vm-id>                                          # SSH session, host key pinned when published (or: -- <cmd>)
+avr vm ssh <vm-id> --login -- claude -p 'summarize the repo' # one-off command in a login shell (sees forwarded env)
+avr vm ssh <vm-id> --session dev                            # persistent tmux session, survives a dropped connection
+avr vm ssh-config <vm-id> --append                          # add `ssh <alias>` (scp/rsync, VS Code Remote-SSH) to ~/.ssh/config
+avr vm list ; avr vm stop <vm-id>                           # lifecycle
+```
+
+`bootstrap` runs each step over SSH and streams it live, feeding secrets (GitHub token, env values, agent credentials) on stdin rather than argv. `--forward-agent-creds` carries your local `ANTHROPIC_API_KEY` / `OPENAI_API_KEY`, or a Claude subscription token — if none is set it offers to run `claude setup-token` and forwards the pasted `CLAUDE_CODE_OAUTH_TOKEN`. Disks are ephemeral, so re-run it after every `avr vm start`. `avr vm ssh` pins the VM's host key when its endpoint publishes one; if it doesn't, `avr` warns and falls back to trust-on-first-use — pass `--session <name>` to attach to (or create) a persistent tmux session that survives a dropped connection. A one-off `avr vm ssh -- <cmd>` runs in a non-login shell that sources no startup files, so pass `--login` when the command needs bootstrap-forwarded env (e.g. `claude`'s subscription token). `avr vm ssh-config` emits a host-key-pinned SSH config block so plain `ssh`, scp/rsync, and VS Code / Cursor Remote-SSH reach the VM without wrapping each tool — `--append` writes it into `~/.ssh/config` for you (idempotent: re-run after a restart to refresh the endpoint in place). For a desktop, `avr vm rdp` / `avr vm vnc` tunnel over the same SSH endpoint, and `avr vm port-forward` is the generic primitive (repeat `--port` to forward several ports over one connection). A VM created with `--repo` inherits that repository's build/CI caches; `--disable-cache <name>` narrows them per VM (it can turn an inherited cache off, never on).
+
 **Cancel or rerun a run**
 
 ```sh

{avr_cli-0.1.6 → avr_cli-0.2.0}/README.md

@@ -126,6 +126,26 @@ avr job metrics <job-id> --watch       # CPU/memory/IO gauges, refreshed every f
 avr job metrics <job-id>               # static post-mortem after the job ended
 ```
 
+**Long-running dev VMs**
+
+Durable, org-scoped VMs reachable over SSH (plus RDP/VNC for a desktop), separate from job VMs. Create one with your key, then set it up in a single command:
+
+```sh
+avr vm create --name dev --os linux --size 2-vcpu \
+  --ssh-key @~/.ssh/id_ed25519.pub --ephemeral --wait      # boot, wait for SSH, print connect
+avr vm create --name ci --os linux --size 8-vcpu --ephemeral \
+  --repo org/project --disable-cache gha,packages          # attach a repo, narrow which caches it uses
+avr vm bootstrap <vm-id> --setup-github --install claude,codex \
+  --repo https://github.com/org/project --env AWS_REGION=eu-north-1
+avr vm ssh <vm-id>                                          # SSH session, host key pinned when published (or: -- <cmd>)
+avr vm ssh <vm-id> --login -- claude -p 'summarize the repo' # one-off command in a login shell (sees forwarded env)
+avr vm ssh <vm-id> --session dev                            # persistent tmux session, survives a dropped connection
+avr vm ssh-config <vm-id> --append                          # add `ssh <alias>` (scp/rsync, VS Code Remote-SSH) to ~/.ssh/config
+avr vm list ; avr vm stop <vm-id>                           # lifecycle
+```
+
+`bootstrap` runs each step over SSH and streams it live, feeding secrets (GitHub token, env values, agent credentials) on stdin rather than argv. `--forward-agent-creds` carries your local `ANTHROPIC_API_KEY` / `OPENAI_API_KEY`, or a Claude subscription token — if none is set it offers to run `claude setup-token` and forwards the pasted `CLAUDE_CODE_OAUTH_TOKEN`. Disks are ephemeral, so re-run it after every `avr vm start`. `avr vm ssh` pins the VM's host key when its endpoint publishes one; if it doesn't, `avr` warns and falls back to trust-on-first-use — pass `--session <name>` to attach to (or create) a persistent tmux session that survives a dropped connection. A one-off `avr vm ssh -- <cmd>` runs in a non-login shell that sources no startup files, so pass `--login` when the command needs bootstrap-forwarded env (e.g. `claude`'s subscription token). `avr vm ssh-config` emits a host-key-pinned SSH config block so plain `ssh`, scp/rsync, and VS Code / Cursor Remote-SSH reach the VM without wrapping each tool — `--append` writes it into `~/.ssh/config` for you (idempotent: re-run after a restart to refresh the endpoint in place). For a desktop, `avr vm rdp` / `avr vm vnc` tunnel over the same SSH endpoint, and `avr vm port-forward` is the generic primitive (repeat `--port` to forward several ports over one connection). A VM created with `--repo` inherits that repository's build/CI caches; `--disable-cache <name>` narrows them per VM (it can turn an inherited cache off, never on).
+
 **Cancel or rerun a run**
 
 ```sh

{avr_cli-0.1.6 → avr_cli-0.2.0}/avr_cli.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: avr-cli
-Version: 0.1.6
+Version: 0.2.0
 Summary: Avrea command-line client
 Author-email: Avrea <support@avrea.com>
 License-Expression: Apache-2.0
@@ -157,6 +157,26 @@ avr job metrics <job-id> --watch       # CPU/memory/IO gauges, refreshed every f
 avr job metrics <job-id>               # static post-mortem after the job ended
 ```
 
+**Long-running dev VMs**
+
+Durable, org-scoped VMs reachable over SSH (plus RDP/VNC for a desktop), separate from job VMs. Create one with your key, then set it up in a single command:
+
+```sh
+avr vm create --name dev --os linux --size 2-vcpu \
+  --ssh-key @~/.ssh/id_ed25519.pub --ephemeral --wait      # boot, wait for SSH, print connect
+avr vm create --name ci --os linux --size 8-vcpu --ephemeral \
+  --repo org/project --disable-cache gha,packages          # attach a repo, narrow which caches it uses
+avr vm bootstrap <vm-id> --setup-github --install claude,codex \
+  --repo https://github.com/org/project --env AWS_REGION=eu-north-1
+avr vm ssh <vm-id>                                          # SSH session, host key pinned when published (or: -- <cmd>)
+avr vm ssh <vm-id> --login -- claude -p 'summarize the repo' # one-off command in a login shell (sees forwarded env)
+avr vm ssh <vm-id> --session dev                            # persistent tmux session, survives a dropped connection
+avr vm ssh-config <vm-id> --append                          # add `ssh <alias>` (scp/rsync, VS Code Remote-SSH) to ~/.ssh/config
+avr vm list ; avr vm stop <vm-id>                           # lifecycle
+```
+
+`bootstrap` runs each step over SSH and streams it live, feeding secrets (GitHub token, env values, agent credentials) on stdin rather than argv. `--forward-agent-creds` carries your local `ANTHROPIC_API_KEY` / `OPENAI_API_KEY`, or a Claude subscription token — if none is set it offers to run `claude setup-token` and forwards the pasted `CLAUDE_CODE_OAUTH_TOKEN`. Disks are ephemeral, so re-run it after every `avr vm start`. `avr vm ssh` pins the VM's host key when its endpoint publishes one; if it doesn't, `avr` warns and falls back to trust-on-first-use — pass `--session <name>` to attach to (or create) a persistent tmux session that survives a dropped connection. A one-off `avr vm ssh -- <cmd>` runs in a non-login shell that sources no startup files, so pass `--login` when the command needs bootstrap-forwarded env (e.g. `claude`'s subscription token). `avr vm ssh-config` emits a host-key-pinned SSH config block so plain `ssh`, scp/rsync, and VS Code / Cursor Remote-SSH reach the VM without wrapping each tool — `--append` writes it into `~/.ssh/config` for you (idempotent: re-run after a restart to refresh the endpoint in place). For a desktop, `avr vm rdp` / `avr vm vnc` tunnel over the same SSH endpoint, and `avr vm port-forward` is the generic primitive (repeat `--port` to forward several ports over one connection). A VM created with `--repo` inherits that repository's build/CI caches; `--disable-cache <name>` narrows them per VM (it can turn an inherited cache off, never on).
+
 **Cancel or rerun a run**
 
 ```sh

{avr_cli-0.1.6 → avr_cli-0.2.0}/avr_cli.egg-info/SOURCES.txt

@@ -28,6 +28,7 @@ avrea_cli/paths.py
 avrea_cli/repo_context.py
 avrea_cli/transport.py
 avrea_cli/version.py
+avrea_cli/vm.py
 avrea_cli/assets/logo_mark.svg
 avrea_cli/commands/__init__.py
 avrea_cli/commands/auth_cmd.py
@@ -46,11 +47,14 @@ avrea_cli/commands/workflow.py
 tests/test_api_client.py
 tests/test_auth.py
 tests/test_auth_login.py
+tests/test_auth_sso.py
 tests/test_cache.py
 tests/test_config.py
 tests/test_config_cmd.py
 tests/test_display.py
+tests/test_docs_gen.py
 tests/test_env_conventions.py
+tests/test_firewall.py
 tests/test_global_flags.py
 tests/test_helpers.py
 tests/test_job_list.py
@@ -60,8 +64,11 @@ tests/test_json_output.py
 tests/test_lazy_registry.py
 tests/test_log_display.py
 tests/test_metrics_display.py
+tests/test_org_email_domain.py
+tests/test_org_saml.py
 tests/test_output.py
 tests/test_piped_output.py
+tests/test_public_mirrors.py
 tests/test_repo_context.py
 tests/test_run_attempts.py
 tests/test_run_list_flags.py
@@ -69,6 +76,7 @@ tests/test_run_logs.py
 tests/test_run_view.py
 tests/test_settings.py
 tests/test_transport.py
+tests/test_vm.py
 tests/test_web_flag.py
 tests/test_workflow_actions.py
 tests/test_workflow_run.py

{avr_cli-0.1.6 → avr_cli-0.2.0}/avrea_cli/_build_info.py

@@ -1,2 +1,2 @@
 # Auto-generated by .github/workflows/release.yml; do not edit.
-GIT_COMMIT = "d1c368547a8ca31fad2ec0513c6a2cfc33e3cb80"
+GIT_COMMIT = "0ee3d6ede53b90032c4a40561338c3e1b03d2c2b"

{avr_cli-0.1.6 → avr_cli-0.2.0}/avrea_cli/api_client.py

@@ -46,14 +46,45 @@ class ApiClient:
         response.raise_for_status()
         return response.json()
 
+    def public_get_text(self, path: str, params: dict[str, Any] | None = None) -> str:
+        """GET a non-JSON public API response, such as SAML SP metadata."""
+        url = f"{self.config.public_api_url}{path}"
+        try:
+            response = self._http.get(url, headers=self.config.get_api_headers(), timeout=self.timeout, params=params)
+        except httpx.HTTPError as exc:
+            self._log("GET", url, type(exc).__name__)
+            raise
+        self._log("GET", str(response.request.url), response.status_code)
+        response.raise_for_status()
+        return response.text
+
     def public_post(
-        self, path: str, json: dict[str, Any] | None = None, timeout: float | None = None
+        self,
+        path: str,
+        json: dict[str, Any] | None = None,
+        timeout: float | None = None,
+        *,
+        content: str | bytes | None = None,
+        params: dict[str, Any] | None = None,
+        content_type: str | None = None,
     ) -> dict[str, Any]:
         """POST request to public API."""
+        if json is not None and content is not None:
+            raise ValueError("public_post accepts either json or content, not both")
         url = f"{self.config.public_api_url}{path}"
         effective_timeout = timeout if timeout is not None else self.timeout
+        headers = self.config.get_api_headers()
+        if content_type is not None:
+            headers = {**headers, "Content-Type": content_type}
         try:
-            response = self._http.post(url, headers=self.config.get_api_headers(), timeout=effective_timeout, json=json)
+            response = self._http.post(
+                url,
+                headers=headers,
+                timeout=effective_timeout,
+                json=json,
+                content=content,
+                params=params,
+            )
         except httpx.HTTPError as exc:
             self._log("POST", url, type(exc).__name__)
             raise

{avr_cli-0.1.6 → avr_cli-0.2.0}/avrea_cli/auth.py

@@ -25,6 +25,7 @@ from pathlib import Path
 from typing import Any
 from typing import override
 from urllib.parse import parse_qs
+from urllib.parse import urlencode
 from urllib.parse import urlparse
 import click
 import html as html_module
@@ -191,6 +192,9 @@ class OAuthCallbackHandler(BaseHTTPRequestHandler):
 
     session_cookie = None
     csrf_token = None
+    # Set when the control plane bounces an OAuth sign-in because the email's
+    # domain enforces SAML. Carries the org slug and arrives without a session.
+    sso_required_slug: str | None = None
     # Set by login() before the server runs so the handler can call /users/me
     # with the just-issued session cookie and surface the email on the page.
     public_api_url: str | None = None
@@ -207,6 +211,8 @@ class OAuthCallbackHandler(BaseHTTPRequestHandler):
             OAuthCallbackHandler.session_cookie = query["session"][0]
         if "csrf_token" in query:
             OAuthCallbackHandler.csrf_token = query["csrf_token"][0]
+        if "sso_required" in query:
+            OAuthCallbackHandler.sso_required_slug = query["sso_required"][0]
         if not OAuthCallbackHandler.session_cookie:
             cookie_header = self.headers.get("Cookie", "")
             if "avrea_session=" in cookie_header:
@@ -354,9 +360,55 @@ code {{
 """
 
 
-def login(public_api_url: str, *, provider: str = "github") -> str:
+def discover_sso_login_path(public_api_url: str, email: str) -> str | None:
+    """The org's SAML login path when ``email``'s domain enforces SSO, else None.
+
+    Mirrors what the console does before offering OAuth buttons. The email goes
+    in the POST body, not the query, to keep it out of access logs.
     """
-    Perform browser OAuth login and return the API key.
+    try:
+        response = httpx.post(
+            f"{public_api_url}/sso/discover",
+            json={"email": email},
+            timeout=10.0,
+        )
+        response.raise_for_status()
+        body = response.json()
+    except httpx.HTTPError as e:
+        raise click.ClickException(f"Could not reach {public_api_url} to check for SSO: {e}") from None
+    except ValueError:
+        raise click.ClickException(f"Unexpected SSO discovery response from {public_api_url}") from None
+    # Valid JSON that isn't an object (a bare list, or null from a proxy) would
+    # otherwise blow up on .get with an AttributeError instead of this message.
+    if not isinstance(body, dict):
+        raise click.ClickException(f"Unexpected SSO discovery response from {public_api_url}")
+    if body.get("method") != "saml":
+        return None
+    path = body.get("saml_login_path")
+    if not path:
+        raise click.ClickException(f"{public_api_url} reported SSO for {email} but returned no login path")
+    return path
+
+
+def _auth_url(public_api_url: str, callback_uri: str, *, provider: str, saml_login_path: str | None) -> str:
+    """Where the browser starts the flow. Every branch lands back on
+    ``callback_uri`` with session/csrf_token in the query."""
+    if saml_login_path is not None:
+        return f"{public_api_url}{saml_login_path}?{urlencode({'next': callback_uri})}"
+    if provider == "google":
+        return f"{public_api_url}/oauth/google/login?final_redirect={callback_uri}"
+    if provider == "github":
+        return f"{public_api_url}/oauth/github/login?next={callback_uri}"
+    raise click.ClickException(f"Unsupported auth provider '{provider}'")
+
+
+def login(public_api_url: str, *, provider: str = "github", email: str | None = None) -> str:
+    """
+    Perform browser login and return the API key.
+
+    Routes through the org's SAML IdP when ``email`` is given and its domain
+    enforces SSO; otherwise through ``provider``'s OAuth flow. Both land on the
+    same local callback, so the handling below is shared.
     Raises click.Abort on failure.
     """
     # Control plane 302s here after the upstream OAuth callback completes;
@@ -371,8 +423,15 @@ def login(public_api_url: str, *, provider: str = "github") -> str:
     # otherwise leave stale session/csrf values behind.
     OAuthCallbackHandler.session_cookie = None
     OAuthCallbackHandler.csrf_token = None
+    OAuthCallbackHandler.sso_required_slug = None
     OAuthCallbackHandler.public_api_url = public_api_url
 
+    # Resolve the destination before binding the port: discovery is a network
+    # call and an unknown provider raises, so doing this first keeps either
+    # failure from leaving a stray listener on 8765.
+    saml_login_path = discover_sso_login_path(public_api_url, email) if email else None
+    auth_url = _auth_url(public_api_url, callback_uri, provider=provider, saml_login_path=saml_login_path)
+
     try:
         server = HTTPServer(("localhost", port), OAuthCallbackHandler)
     except OSError as e:
@@ -380,12 +439,6 @@ def login(public_api_url: str, *, provider: str = "github") -> str:
         click.echo("Ensure no other process is using this port and try again.")
         raise click.Abort() from None
 
-    if provider == "google":
-        auth_url = f"{public_api_url}/oauth/google/login?final_redirect={callback_uri}"
-    elif provider == "github":
-        auth_url = f"{public_api_url}/oauth/github/login?next={callback_uri}"
-    else:
-        raise click.ClickException(f"Unsupported auth provider '{provider}'")
     click.echo(f"Opening browser to: {auth_url}")
     click.echo("Waiting for authentication...")
 
@@ -418,6 +471,16 @@ def login(public_api_url: str, *, provider: str = "github") -> str:
         server.server_close()
 
     if not OAuthCallbackHandler.session_cookie:
+        if OAuthCallbackHandler.sso_required_slug:
+            # The control plane refuses OAuth for SSO-enforced domains and
+            # bounces back without a session. Only an email gets us the IdP.
+            click.echo(
+                f"Error: {OAuthCallbackHandler.sso_required_slug} requires single sign-on.",
+                err=True,
+            )
+            click.echo("Retry with your work email so the CLI can find your identity provider:", err=True)
+            click.echo("  avr auth login --email you@yourcompany.com", err=True)
+            raise click.Abort()
         click.echo("Error: Authentication failed - no session received", err=True)
         raise click.Abort()
 

{avr_cli-0.1.6 → avr_cli-0.2.0}/avrea_cli/commands/auth_cmd.py

@@ -67,10 +67,10 @@ def _maybe_auto_pin_default_org(api_url: str, api_key: str) -> tuple[str, str] |
     return slug, org_id
 
 
-def _do_login(ctx, provider):
+def _do_login(ctx, provider, email=None):
     config: CliConfig = ctx.obj["config"]
     try:
-        api_key = auth.login(config.public_api_url, provider=provider)
+        api_key = auth.login(config.public_api_url, provider=provider, email=email)
     except click.ClickException as exc:
         # Click's exception carries a useful `.message`; surface it under a
         # consistent "Login failed:" prefix and exit 1.
@@ -138,10 +138,15 @@ def auth_group(ctx):
     show_default=True,
     help="OAuth provider to use for CLI login.",
 )
+@click.option(
+    "--email",
+    default=None,
+    help="Work email. Routes through your company's SSO if its domain requires it, ignoring --provider.",
+)
 @click.pass_context
-def auth_login(ctx, provider: str):
+def auth_login(ctx, provider: str, email: str | None):
     """Authenticate via browser and store credentials."""
-    _do_login(ctx, provider)
+    _do_login(ctx, provider, email)
 
 
 @auth_group.command("logout")
@@ -283,10 +288,15 @@ def _format_token(token: str | None, show: bool) -> str:
     show_default=True,
     help="OAuth provider to use for CLI login.",
 )
+@click.option(
+    "--email",
+    default=None,
+    help="Work email. Routes through your company's SSO if its domain requires it, ignoring --provider.",
+)
 @click.pass_context
-def login_alias(ctx, provider: str):
+def login_alias(ctx, provider: str, email: str | None):
     """Authenticate via browser and store credentials."""
-    _do_login(ctx, provider)
+    _do_login(ctx, provider, email)
 
 
 @click.command("logout", hidden=True)