minitest-cli 0.34.0__tar.gz → 0.35.0__tar.gz

{minitest_cli-0.34.0 → minitest_cli-0.35.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: minitest-cli
-Version: 0.34.0
+Version: 0.35.0
 Summary: Minitest CLI – command-line interface for the Minitest testing platform
 Project-URL: Homepage, https://minitap.ai/
 Project-URL: Source, https://github.com/minitap-ai/minitest-cli
@@ -166,7 +166,7 @@ app defaults.
 | Command          | Description               |
 | ---------------- | ------------------------- |
 | `minitest auth`  | Authentication management |
-| `minitest apps`  | List, inspect, and create apps |
+| `minitest apps`  | List, inspect, and create apps; residential proxy and private network settings |
 | `minitest scenario` | Create, update, list and delete scenarios |
 | `minitest scenario-binding` | Bind test accounts, test files or app skills to scenarios |
 | `minitest draft` | Drafts — branches of the test suite |
@@ -198,6 +198,34 @@ stderr and leave `--json` stdout unchanged. Switch to the new names.
 | `run cancel --srp`, `run recording --srp` | `--target-id` |
 | `--type` on `scenario create/update/list` | `--tag` |
 
+## App network settings
+
+Two per-app settings decide how test devices reach the network. Anyone on the
+app can read them; only workspace **owners and admins** can change them (other
+roles get `Only workspace owners and admins can change this setting`, exit 2).
+`set` reads the current settings first and changes only what you pass.
+Domains are an exact host (`api.stg.example.com`) or `*.example.com`, which
+matches subdomains only, not `example.com` itself.
+
+```bash
+# Residential proxy: reach the listed domains from a residential IP in one country
+minitest --app <app-id> apps residential-proxy show
+minitest --app <app-id> apps residential-proxy set [--enable|--disable] [--country tr] \
+  [--domain ipinfo.io ...] [--remove-domain <d> ...] [--clear-domains]
+
+# Private network: reach internal domains through a connector running in your network
+minitest --app <app-id> apps private-network show
+minitest --app <app-id> apps private-network connectors
+minitest --app <app-id> apps private-network set [--enable|--disable] [--connector <name-or-id>] \
+  [--domain api.stg.corp.internal ...] [--remove-domain <d> ...] [--clear-domains] [--port 443 ...]
+```
+
+`--clear-domains --domain a --domain b` replaces the list; `--port` replaces the
+ports (default 443). Turning the private network on needs a connector and at
+least one domain. Connectors cannot be created from the CLI: a workspace owner
+or admin creates them in the webapp, under **Workspace settings → Private
+network**.
+
 ## CLI-only maintenance
 
 `minitest maintenance` lets a coding agent keep Minitest scenarios in sync

{minitest_cli-0.34.0 → minitest_cli-0.35.0}/README.md

@@ -133,7 +133,7 @@ app defaults.
 | Command          | Description               |
 | ---------------- | ------------------------- |
 | `minitest auth`  | Authentication management |
-| `minitest apps`  | List, inspect, and create apps |
+| `minitest apps`  | List, inspect, and create apps; residential proxy and private network settings |
 | `minitest scenario` | Create, update, list and delete scenarios |
 | `minitest scenario-binding` | Bind test accounts, test files or app skills to scenarios |
 | `minitest draft` | Drafts — branches of the test suite |
@@ -165,6 +165,34 @@ stderr and leave `--json` stdout unchanged. Switch to the new names.
 | `run cancel --srp`, `run recording --srp` | `--target-id` |
 | `--type` on `scenario create/update/list` | `--tag` |
 
+## App network settings
+
+Two per-app settings decide how test devices reach the network. Anyone on the
+app can read them; only workspace **owners and admins** can change them (other
+roles get `Only workspace owners and admins can change this setting`, exit 2).
+`set` reads the current settings first and changes only what you pass.
+Domains are an exact host (`api.stg.example.com`) or `*.example.com`, which
+matches subdomains only, not `example.com` itself.
+
+```bash
+# Residential proxy: reach the listed domains from a residential IP in one country
+minitest --app <app-id> apps residential-proxy show
+minitest --app <app-id> apps residential-proxy set [--enable|--disable] [--country tr] \
+  [--domain ipinfo.io ...] [--remove-domain <d> ...] [--clear-domains]
+
+# Private network: reach internal domains through a connector running in your network
+minitest --app <app-id> apps private-network show
+minitest --app <app-id> apps private-network connectors
+minitest --app <app-id> apps private-network set [--enable|--disable] [--connector <name-or-id>] \
+  [--domain api.stg.corp.internal ...] [--remove-domain <d> ...] [--clear-domains] [--port 443 ...]
+```
+
+`--clear-domains --domain a --domain b` replaces the list; `--port` replaces the
+ports (default 443). Turning the private network on needs a connector and at
+least one domain. Connectors cannot be created from the CLI: a workspace owner
+or admin creates them in the webapp, under **Workspace settings → Private
+network**.
+
 ## CLI-only maintenance
 
 `minitest maintenance` lets a coding agent keep Minitest scenarios in sync

{minitest_cli-0.34.0 → minitest_cli-0.35.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "minitest-cli"
-version = "0.34.0"
+version = "0.35.0"
 description = "Minitest CLI – command-line interface for the Minitest testing platform"
 readme = "README.md"
 license = "MIT"

minitest_cli-0.35.0/src/minitest_cli/commands/app_network_helpers.py

@@ -0,0 +1,114 @@
+"""Shared plumbing for the per-app network settings (residential proxy, private network)."""
+
+import asyncio
+import re
+from typing import Any
+
+import httpx
+import typer
+
+from minitest_cli.api.client import ApiClient
+from minitest_cli.api.errors import format_network_error
+from minitest_cli.commands._response_errors import extract_detail
+from minitest_cli.core.app_context import resolve_app_id
+from minitest_cli.core.auth import require_auth
+from minitest_cli.core.config import Settings
+from minitest_cli.utils.output import print_error
+
+EXIT_GENERAL_ERROR = 1
+EXIT_AUTH_ERROR = 2
+EXIT_NETWORK_ERROR = 3
+EXIT_NOT_FOUND = 4
+
+ADMIN_ONLY_MESSAGE = "Only workspace owners and admins can change this setting."
+
+
+def is_json_mode() -> bool:
+    return typer.Context.json_mode  # type: ignore[attr-defined]
+
+
+def resolve_target() -> tuple[Settings, str]:
+    settings: Settings = typer.Context.settings  # type: ignore[attr-defined]
+    require_auth(settings)
+    return settings, resolve_app_id(settings, typer.Context.app_flag)  # type: ignore[attr-defined]
+
+
+def fail(message: str, code: int = EXIT_GENERAL_ERROR) -> typer.Exit:
+    print_error(message)
+    return typer.Exit(code=code)
+
+
+def _raise_for_status(resp: httpx.Response) -> None:
+    if resp.status_code < 400:
+        return
+    detail = extract_detail(resp)
+    if resp.status_code == 403:
+        raise fail(f"{ADMIN_ONLY_MESSAGE} ({detail})", EXIT_AUTH_ERROR)
+    if resp.status_code == 401:
+        raise fail(f"Authentication failed: {detail}", EXIT_AUTH_ERROR)
+    if resp.status_code == 404:
+        raise fail(f"Not found: {detail}", EXIT_NOT_FOUND)
+    if resp.status_code in (400, 409, 422):
+        raise fail(f"Rejected by the server ({resp.status_code}): {detail}")
+    raise fail(f"API error ({resp.status_code}): {detail}", EXIT_NETWORK_ERROR)
+
+
+def call_api(
+    settings: Settings, method: str, path: str, body: dict[str, Any] | None = None
+) -> dict[str, Any]:
+    async def _run() -> dict[str, Any]:
+        async with ApiClient(settings) as client:
+            resp = await client.request(method, path, json=body)
+        _raise_for_status(resp)
+        try:
+            return resp.json()
+        except ValueError as exc:
+            raise fail(
+                f"Unexpected non-JSON response ({resp.status_code}): {resp.text[:200]}",
+                EXIT_NETWORK_ERROR,
+            ) from exc
+
+    try:
+        return asyncio.run(_run())
+    except httpx.HTTPError as exc:
+        raise fail(format_network_error(exc), EXIT_NETWORK_ERROR) from exc
+
+
+def merge_domains(
+    current: list[str],
+    *,
+    add: list[str] | None,
+    remove: list[str] | None,
+    clear: bool,
+    pattern: str,
+    max_domains: int,
+) -> list[str]:
+    """Apply ``--clear-domains``, ``--remove-domain`` then ``--domain`` and validate the result."""
+    added = [_normalize(d) for d in add or []]
+    invalid = [d for d in added if not re.fullmatch(pattern, d)]
+    if invalid:
+        raise fail(
+            f"Invalid domain(s): {', '.join(invalid)}. Use a lowercase host like api.example.com, "
+            "or *.example.com to match its subdomains (not example.com itself)."
+        )
+    removed = {_normalize(d) for d in remove or []}
+    unknown = sorted(removed - set(current))
+    if unknown:
+        raise fail(f"Not in the current domain list: {', '.join(unknown)}.")
+    base = [] if clear else [d for d in current if d not in removed]
+    merged = list(dict.fromkeys([*base, *added]))
+    if len(merged) > max_domains:
+        raise fail(f"Too many domains: {len(merged)} (max {max_domains}).")
+    return merged
+
+
+def _normalize(domain: str) -> str:
+    return domain.strip().lower().rstrip(".")
+
+
+def on_off(value: bool) -> str:
+    return "on" if value else "off"
+
+
+def domain_list(domains: list[str]) -> str:
+    return ", ".join(domains) if domains else "-"

{minitest_cli-0.34.0 → minitest_cli-0.35.0}/src/minitest_cli/commands/apps.py

@@ -1,4 +1,4 @@
-"""App management commands: list, get, create, dependencies."""
+"""App management commands: list, get, create, dependencies, network settings."""
 
 import asyncio
 from pathlib import Path
@@ -10,7 +10,12 @@ import typer
 from minitest_cli.api.apps_manager_client import AppsManagerClient  # noqa: F401  re-exported for tests
 from minitest_cli.api.client import ApiClient
 from minitest_cli.api.errors import format_network_error
-from minitest_cli.commands import apps_dependencies, apps_get
+from minitest_cli.commands import (
+    apps_dependencies,
+    apps_get,
+    private_network,
+    residential_proxy,
+)
 from minitest_cli.commands.apps_helpers import create_app_request
 from minitest_cli.commands.apps_table import APP_TABLE_HEADERS, app_row
 from minitest_cli.core.auth import require_auth
@@ -30,6 +35,8 @@ EXIT_NETWORK_ERROR = 3
 app = typer.Typer(name="apps", help="App management.")
 app.command(name="dependencies")(apps_dependencies.dependencies)
 app.command(name="get")(apps_get.get_app)
+app.add_typer(residential_proxy.app)
+app.add_typer(private_network.app)
 
 
 @app.callback()

minitest_cli-0.35.0/src/minitest_cli/commands/private_network.py

@@ -0,0 +1,143 @@
+"""'apps private-network': reach a customer's internal domains through a connector."""
+
+from typing import Annotated, Any
+
+import typer
+
+from minitest_cli.commands.app_network_helpers import (
+    call_api,
+    fail,
+    is_json_mode,
+    merge_domains,
+    resolve_target,
+)
+from minitest_cli.commands.private_network_helpers import (
+    CREATE_IN_WEBAPP_HINT,
+    UNAVAILABLE_MESSAGE,
+    render_config,
+    render_connectors,
+    resolve_connector,
+)
+from minitest_cli.core.config import Settings
+from minitest_cli.utils.output import print_success
+
+app = typer.Typer(
+    name="private-network",
+    help=(
+        "Private network of the app (--app): devices reach internal domains through a "
+        "connector running in your network. Changing it needs the OWNER or ADMIN role. "
+        f"{CREATE_IN_WEBAPP_HINT}"
+    ),
+    no_args_is_help=True,
+)
+
+
+def _path(app_id: str) -> str:
+    return f"/api/v1/apps/{app_id}/private-network"
+
+
+@app.command(name="show")
+def show() -> None:
+    """Show the app's private network settings."""
+    settings, app_id = resolve_target()
+    config = call_api(settings, "GET", _path(app_id))
+    render_config(config)
+
+
+@app.command(name="connectors")
+def connectors() -> None:
+    """List the workspace connectors the app can route through (read-only)."""
+    settings, app_id = resolve_target()
+    listing = call_api(settings, "GET", f"{_path(app_id)}/connectors")
+    render_connectors(listing)
+
+
+@app.command(name="set")
+def set_config(
+    enable: Annotated[
+        bool | None,
+        typer.Option(
+            "--enable/--disable",
+            help="Switch it on or off. On needs a connector and at least one domain.",
+        ),
+    ] = None,
+    connector: Annotated[
+        str | None,
+        typer.Option("--connector", help="Connector name or id (see 'connectors')."),
+    ] = None,
+    domain: Annotated[
+        list[str] | None,
+        typer.Option(
+            "--domain",
+            help="Internal domain to reach (repeatable): host, or *.host for its subdomains only.",
+        ),
+    ] = None,
+    remove_domain: Annotated[
+        list[str] | None,
+        typer.Option("--remove-domain", help="Domain to stop reaching (repeatable)."),
+    ] = None,
+    clear_domains: Annotated[
+        bool,
+        typer.Option("--clear-domains", help="Drop every current domain before adding --domain."),
+    ] = False,
+    port: Annotated[
+        list[int] | None,
+        typer.Option(
+            "--port",
+            min=1,
+            max=65535,
+            help="Port devices may reach (repeatable). Replaces the current ports; default 443.",
+        ),
+    ] = None,
+) -> None:
+    """Change the app's private network settings; options not passed stay as they are."""
+    if not any([enable is not None, connector, domain, remove_domain, clear_domains, port]):
+        raise fail(
+            "Nothing to change: pass --enable/--disable, --connector, a domain option or --port."
+        )
+    settings, app_id = resolve_target()
+    current = call_api(settings, "GET", _path(app_id))
+    body = _build_body(settings, app_id, current, enable, connector, port)
+    body["domains"] = merge_domains(
+        current["domains"],
+        add=domain,
+        remove=remove_domain,
+        clear=clear_domains,
+        pattern=current["domainPattern"],
+        max_domains=current["maxDomains"],
+    )
+    if body["enabled"]:
+        if not current["available"]:
+            raise fail(UNAVAILABLE_MESSAGE)
+        if not body["connectorId"]:
+            raise fail(
+                "Turning it on needs a connector: pass --connector <name-or-id> "
+                f"(see 'minitest apps private-network connectors'). {CREATE_IN_WEBAPP_HINT}"
+            )
+        if not body["domains"]:
+            raise fail("Turning it on needs at least one --domain.")
+
+    updated = call_api(settings, "PUT", _path(app_id), body)
+    if not is_json_mode():
+        print_success("Private network updated.")
+    render_config(updated)
+
+
+def _build_body(
+    settings: Settings,
+    app_id: str,
+    current: dict[str, Any],
+    enable: bool | None,
+    connector: str | None,
+    port: list[int] | None,
+) -> dict[str, Any]:
+    if connector:
+        listing = call_api(settings, "GET", f"{_path(app_id)}/connectors")
+        connector_id = resolve_connector(listing["connectors"], connector)["id"]
+    else:
+        connector_id = current["connector"]["id"] if current["connector"] else None
+    return {
+        "enabled": current["enabled"] if enable is None else enable,
+        "connectorId": connector_id,
+        "ports": list(dict.fromkeys(port)) if port else current["ports"] or [443],
+    }

minitest_cli-0.35.0/src/minitest_cli/commands/private_network_helpers.py

@@ -0,0 +1,93 @@
+"""Rendering and connector lookup for 'apps private-network'."""
+
+from typing import Any
+
+from minitest_cli.commands.app_network_helpers import domain_list, fail, is_json_mode, on_off
+from minitest_cli.utils.output import print_info, print_json, print_table, print_warning
+
+UNAVAILABLE_MESSAGE = "This workspace cannot use private network. Contact Minitap to enable it."
+CREATE_IN_WEBAPP_HINT = (
+    "Connectors can only be created by a workspace owner or admin in the webapp: "
+    "Workspace settings → Private network."
+)
+
+
+def resolve_connector(connectors: list[dict[str, Any]], ref: str) -> dict[str, Any]:
+    """Find a connector by id, or by name (case-insensitive)."""
+    if not connectors:
+        raise fail(f"This workspace has no connector. {CREATE_IN_WEBAPP_HINT}")
+    by_id = [c for c in connectors if c["id"] == ref]
+    matches = by_id or [c for c in connectors if c["name"].casefold() == ref.casefold()]
+    if len(matches) == 1:
+        return matches[0]
+    if matches:
+        ids = ", ".join(c["id"] for c in matches)
+        raise fail(f"Several connectors are named '{ref}': pass one of these ids instead: {ids}.")
+    names = ", ".join(f"{c['name']} ({c['status']})" for c in connectors)
+    raise fail(f"No connector named '{ref}'. Available: {names}. {CREATE_IN_WEBAPP_HINT}")
+
+
+def without_token_prefix(config: dict[str, Any]) -> dict[str, Any]:
+    connector = config.get("connector")
+    if not connector:
+        return config
+    return {**config, "connector": {k: v for k, v in connector.items() if k != "tokenPrefix"}}
+
+
+def render_config(config: dict[str, Any]) -> None:
+    config = without_token_prefix(config)
+    if not config["available"]:
+        print_warning(UNAVAILABLE_MESSAGE)
+    if is_json_mode():
+        print_json(config)
+        warn_connector_state(config)
+        return
+    connector = config["connector"]
+    print(f"Enabled: {on_off(config['enabled'])}")  # noqa: T201
+    if connector:
+        print(f"Connector: {connector['name']} ({connector['status']}) {connector['id']}")  # noqa: T201
+    else:
+        print("Connector: -")  # noqa: T201
+    print(f"Domains: {domain_list(config['domains'])}")  # noqa: T201
+    print(f"Ports: {', '.join(str(p) for p in config['ports']) or '-'}")  # noqa: T201
+    warn_connector_state(config)
+
+
+def warn_connector_state(config: dict[str, Any]) -> None:
+    connector = config["connector"]
+    if config["enabled"] and connector and connector["status"] != "online":
+        print_warning(
+            f"Connector '{connector['name']}' is {connector['status']}: runs cannot reach "
+            "the internal domains until it is connected."
+        )
+    refused = config["domainsRefusedByConnector"]
+    if refused:
+        print_warning(
+            f"The connector's own allowlist refuses: {', '.join(refused)}. Add them on the "
+            "connector machine, or the devices will not reach them."
+        )
+
+
+def render_connectors(listing: dict[str, Any]) -> None:
+    if not listing["available"]:
+        print_warning(UNAVAILABLE_MESSAGE)
+    connectors = listing["connectors"]
+    if not connectors:
+        print_info(f"No connector yet. {CREATE_IN_WEBAPP_HINT}")
+    if is_json_mode():
+        print_json(listing)
+        return
+    if not connectors:
+        return
+    rows = [
+        [
+            c["name"],
+            c["status"],
+            domain_list(c["domains"]),
+            ", ".join(str(p) for p in c["ports"]) or "-",
+            c.get("lastSeenAt") or "-",
+            c["id"],
+        ]
+        for c in connectors
+    ]
+    print_table(["Name", "Status", "Domains", "Ports", "Last seen", "ID"], rows, title="Connectors")

minitest_cli-0.35.0/src/minitest_cli/commands/residential_proxy.py

@@ -0,0 +1,121 @@
+"""'apps residential-proxy': route some of an app's device traffic through residential IPs."""
+
+from typing import Annotated, Any
+
+import typer
+
+from minitest_cli.commands.app_network_helpers import (
+    call_api,
+    domain_list,
+    fail,
+    is_json_mode,
+    merge_domains,
+    on_off,
+    resolve_target,
+)
+from minitest_cli.utils.output import print_json, print_success, print_warning
+
+app = typer.Typer(
+    name="residential-proxy",
+    help=(
+        "Residential proxy of the app (--app): devices reach the listed domains from a "
+        "residential IP in the chosen country. Changing it needs the OWNER or ADMIN role."
+    ),
+    no_args_is_help=True,
+)
+
+UNAVAILABLE_MESSAGE = (
+    "This workspace cannot use the residential proxy. Contact Minitap to enable it."
+)
+
+
+def _path(app_id: str) -> str:
+    return f"/api/v1/apps/{app_id}/residential-proxy"
+
+
+def _render(config: dict[str, Any]) -> None:
+    if not config["available"]:
+        print_warning(UNAVAILABLE_MESSAGE)
+    if is_json_mode():
+        print_json(config)
+        return
+    print(f"Enabled: {on_off(config['enabled'])}")  # noqa: T201
+    print(f"Country: {config['country']}")  # noqa: T201
+    print(f"Domains: {domain_list(config['allowedDomains'])}")  # noqa: T201
+    print(f"Countries available: {', '.join(config['availableCountries'])}")  # noqa: T201
+    print(f"Price: {config['usdPerGb']} USD per GB")  # noqa: T201
+
+
+@app.command(name="show")
+def show() -> None:
+    """Show the app's residential proxy settings."""
+    settings, app_id = resolve_target()
+    config = call_api(settings, "GET", _path(app_id))
+    _render(config)
+
+
+@app.command(name="set")
+def set_config(
+    enable: Annotated[
+        bool | None,
+        typer.Option("--enable/--disable", help="Switch the proxy on or off."),
+    ] = None,
+    country: Annotated[
+        str | None,
+        typer.Option("--country", help="Exit country code, e.g. tr (see 'show')."),
+    ] = None,
+    domain: Annotated[
+        list[str] | None,
+        typer.Option(
+            "--domain",
+            help="Domain to route through the proxy (repeatable): host or *.host for subdomains.",
+        ),
+    ] = None,
+    remove_domain: Annotated[
+        list[str] | None,
+        typer.Option("--remove-domain", help="Domain to stop routing (repeatable)."),
+    ] = None,
+    clear_domains: Annotated[
+        bool,
+        typer.Option("--clear-domains", help="Drop every current domain before adding --domain."),
+    ] = False,
+) -> None:
+    """Change the app's residential proxy settings; options not passed stay as they are."""
+    if (
+        enable is None
+        and country is None
+        and not domain
+        and not remove_domain
+        and not clear_domains
+    ):
+        raise fail("Nothing to change: pass --enable/--disable, --country or a domain option.")
+    settings, app_id = resolve_target()
+    current = call_api(settings, "GET", _path(app_id))
+    if not current["available"]:
+        raise fail(UNAVAILABLE_MESSAGE)
+
+    chosen_country = country.strip().lower() if country else current["country"]
+    if chosen_country not in current["availableCountries"]:
+        raise fail(
+            f"Unknown country '{chosen_country}'. Pick one of: "
+            f"{', '.join(current['availableCountries'])}."
+        )
+    body = {
+        "enabled": current["enabled"] if enable is None else enable,
+        "country": chosen_country,
+        "allowedDomains": merge_domains(
+            current["allowedDomains"],
+            add=domain,
+            remove=remove_domain,
+            clear=clear_domains,
+            pattern=current["domainPattern"],
+            max_domains=current["maxDomains"],
+        ),
+    }
+    if body["enabled"] and not body["allowedDomains"]:
+        print_warning("The proxy is on but no domain is listed, so no traffic goes through it.")
+
+    updated = call_api(settings, "PUT", _path(app_id), body)
+    if not is_json_mode():
+        print_success("Residential proxy updated.")
+    _render(updated)