arga-cli 0.1.0__py3-none-any.whl

arga_cli/mcp.py

@@ -0,0 +1,125 @@
+from __future__ import annotations
+
+import json
+from collections.abc import Callable
+from dataclasses import dataclass
+from pathlib import Path
+
+SERVER_NAME = "arga-context"
+
+
+@dataclass(frozen=True)
+class McpTarget:
+    key: str
+    label: str
+    config_path: Path
+
+
+def get_targets(home: Path | None = None) -> list[McpTarget]:
+    home = home or Path.home()
+    return [
+        McpTarget("cursor", "Cursor", home / ".cursor" / "mcp.json"),
+        McpTarget("claude", "Claude Code", home / ".claude" / "mcp.json"),
+        McpTarget("codex", "Codex CLI", home / ".config" / "codex" / "mcp.json"),
+    ]
+
+
+def build_mcp_config(api_url: str, api_key: str) -> dict[str, object]:
+    return {
+        "mcpServers": {
+            SERVER_NAME: {
+                "url": f"{api_url.rstrip('/')}/mcp",
+                "headers": {
+                    "Authorization": f"Bearer {api_key}",
+                },
+            }
+        }
+    }
+
+
+def detect_installed_targets(home: Path | None = None) -> list[McpTarget]:
+    detected: list[McpTarget] = []
+    for target in get_targets(home):
+        if target.config_path.exists() or target.config_path.parent.exists():
+            detected.append(target)
+    return detected
+
+
+def load_existing_config(config_path: Path) -> dict[str, object]:
+    if not config_path.exists():
+        return {}
+
+    try:
+        data = json.loads(config_path.read_text())
+    except json.JSONDecodeError as exc:
+        raise ValueError(f"Invalid JSON in {config_path}") from exc
+
+    if not isinstance(data, dict):
+        raise ValueError(f"Expected top-level object in {config_path}")
+    return data
+
+
+def merge_mcp_config(existing: dict[str, object], mcp_config: dict[str, object]) -> dict[str, object]:
+    merged = dict(existing)
+    existing_servers = merged.get("mcpServers")
+    if existing_servers is None:
+        merged_servers: dict[str, object] = {}
+    elif isinstance(existing_servers, dict):
+        merged_servers = dict(existing_servers)
+    else:
+        raise ValueError("Expected `mcpServers` to be an object")
+
+    new_servers = mcp_config.get("mcpServers")
+    if not isinstance(new_servers, dict):
+        raise ValueError("Generated MCP config is invalid")
+
+    merged_servers.update(new_servers)
+    merged["mcpServers"] = merged_servers
+    return merged
+
+
+def write_mcp_config(config_path: Path, config: dict[str, object]) -> None:
+    config_path.parent.mkdir(parents=True, exist_ok=True)
+    payload = json.dumps(config, indent=2) + "\n"
+    temp_path = config_path.with_suffix(f"{config_path.suffix}.tmp")
+    temp_path.write_text(payload)
+    temp_path.replace(config_path)
+
+
+def install_mcp_configuration(
+    *,
+    api_url: str,
+    api_key: str,
+    home: Path | None = None,
+    echo: Callable[[str], None] = print,
+) -> tuple[int, int]:
+    detected = detect_installed_targets(home)
+
+    echo("Detected:")
+    if not detected:
+        echo("No supported IDE agents detected.")
+        return 0, 0
+
+    for target in detected:
+        echo(f"✓ {target.label}")
+
+    echo("")
+    echo("Installing MCP configuration...")
+    echo("")
+
+    installed = 0
+    failures = 0
+    generated_config = build_mcp_config(api_url, api_key)
+
+    for target in detected:
+        try:
+            existing = load_existing_config(target.config_path)
+            merged = merge_mcp_config(existing, generated_config)
+            write_mcp_config(target.config_path, merged)
+            echo(f"✓ {target.label} configured")
+            installed += 1
+        except ValueError as exc:
+            echo(f"✗ {target.label} not configured: {exc}")
+            failures += 1
+
+    return installed, failures

arga_cli-0.1.0.dist-info/METADATA

@@ -0,0 +1,298 @@
+Metadata-Version: 2.4
+Name: arga-cli
+Version: 0.1.0
+Summary: Command-line interface for Arga authentication, MCP installation, and browser validation
+Author: Arga Labs
+Project-URL: Homepage, https://github.com/ArgaLabs/arga-cli
+Project-URL: Repository, https://github.com/ArgaLabs/arga-cli
+Project-URL: Issues, https://github.com/ArgaLabs/arga-cli/issues
+Keywords: arga,cli,mcp,developer-tools,validation
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.27.0
+
+# Arga CLI
+
+`arga` is the command-line interface for authenticating with Arga, installing MCP configuration into supported coding agents, and starting validation runs against deployed apps or pull requests.
+
+## What It Does
+
+- Authenticates your machine with Arga using the device login flow.
+- Stores a device-scoped API key locally so each terminal/device can be revoked independently.
+- Shows the currently authenticated user and workspace.
+- Installs MCP configuration into supported local agents.
+- Starts URL validation runs from the terminal.
+- Starts pull request validation runs from the terminal.
+- Wraps `git commit` and `git push` with Arga skip-validation helpers.
+- Starts and inspects Arga app scans.
+
+## Installation 
+
+Once published to PyPI:
+
+```bash
+uv tool install arga-cli
+```
+
+You can also install it with `pipx` or `pip`:
+
+```bash
+pipx install arga-cli
+pip install arga-cli
+```
+
+After installation, the executable is:
+
+```bash
+arga --help
+```
+
+## Quick Start
+
+Authenticate:
+
+```bash
+arga login
+arga whoami
+```
+
+Remove the saved device credential:
+
+```bash
+arga logout
+```
+
+Install MCP configuration for detected agents:
+
+```bash
+arga mcp install
+```
+
+Start a browser validation run:
+
+```bash
+arga test url --url https://demo-app.com --prompt "test the login flow"
+```
+
+Start a pull request validation run:
+
+```bash
+arga validate pr --repo arga-labs/validation-server --pr 182
+```
+
+Create a commit that skips Arga validation:
+
+```bash
+arga commit -m "docs: update examples" --skip
+arga push --skip
+```
+
+Inspect or update automatic validation settings:
+
+```bash
+arga validate install arga-labs/validation-server
+arga validate config arga-labs/validation-server
+arga validate config set arga-labs/validation-server --trigger branch --branch main --comments on
+```
+
+Start an app scan and inspect it later:
+
+```bash
+arga scan https://demo-app.com --budget 200
+arga scan status <run_id>
+arga scan report <run_id>
+```
+
+List and inspect recent validation runs:
+
+```bash
+arga runs list --repo arga-labs/validation-server --limit 20
+arga runs status <run_id>
+arga runs cancel <run_id>
+```
+
+`arga validate url` is also available and currently behaves the same as `arga test url`:
+
+```bash
+arga validate url --url https://demo-app.com --prompt "test checkout"
+```
+
+## Command Reference
+
+### Authentication
+
+```bash
+arga login
+arga whoami
+arga logout
+```
+
+- `arga login` opens the browser to complete Arga's device authorization flow.
+- `arga whoami` verifies the saved API key and prints the GitHub login plus workspace.
+- `arga logout` removes the local credential and attempts to revoke the current device on the server.
+
+### Validation
+
+```bash
+arga test url --url https://demo-app.com --prompt "test login flow"
+arga validate url --url https://demo-app.com --prompt "test checkout"
+arga validate pr --repo arga-labs/validation-server --pr 182
+arga validate install arga-labs/validation-server
+arga validate config arga-labs/validation-server
+arga validate config set arga-labs/validation-server --trigger branch --branch main --comments on
+```
+
+- `arga test url` starts a one-off validation against a deployed URL.
+- `arga validate url` is an equivalent URL-validation entry point under the `validate` namespace.
+- `arga validate pr` starts GitHub-backed PR validation for a repository and pull request number.
+- `arga validate install <repo>` installs the GitHub webhook for automatic validation on a repository.
+- `arga validate config <repo>` shows the current automatic validation settings, including install state, trigger mode, selected branch, and PR comment behavior.
+- `arga validate config set <repo>` updates the automatic validation settings. Any omitted options keep their current value.
+
+For URL validation, you can optionally provide credentials:
+
+```bash
+arga test url \
+  --url https://demo-app.com \
+  --prompt "log in and create an order" \
+  --email test@company.com \
+  --password supersecret
+```
+
+Both `--email` and `--password` must be supplied together.
+
+### App Scans
+
+```bash
+arga scan https://demo-app.com --budget 200
+arga scan status <run_id>
+arga scan report <run_id>
+```
+
+- `arga scan <url>` starts an app scan, waits for the generated scan plan to be ready, and auto-approves it so execution can begin.
+- `--budget` controls the red-team action budget and defaults to `200`.
+- `arga scan status <run_id>` prints the current run status and anomaly count.
+- `arga scan report <run_id>` prints the final JSON report once the scan has completed.
+
+### Validation Runs
+
+```bash
+arga runs list --repo arga-labs/validation-server --status running --limit 20
+arga runs status <run_id>
+arga runs cancel <run_id>
+```
+
+- `arga runs list` shows recent PR and branch validation runs in table form.
+- `--repo` narrows the list to a single repository.
+- `--status` accepts `completed`, `failed`, or `running`. The `running` filter includes non-terminal states such as `queued`.
+- `arga runs status <run_id>` prints a detailed summary for a specific run.
+- `arga runs cancel <run_id>` cancels the run through the validation API.
+
+### Git Wrappers
+
+```bash
+arga commit -m "docs: update examples" --skip
+arga push --skip
+```
+
+- `arga commit` delegates to `git commit`.
+- `arga commit --skip` appends a final `[skip arga]` paragraph to the commit message so Arga skips validation for that head commit.
+- `arga push` delegates to `git push`.
+- `arga push --skip` verifies the current `HEAD` commit already contains `[skip arga]` before pushing. This is safest when the commit was created with `arga commit --skip`.
+
+## Supported MCP Targets
+
+`arga mcp install` writes or updates MCP configuration for supported agents when they are detected locally:
+
+- `~/.cursor/mcp.json`
+- `~/.claude/mcp.json`
+- `~/.config/codex/mcp.json`
+
+The installed server is named `arga-context` and points to:
+
+```text
+<api-url>/mcp
+```
+
+using an `Authorization: Bearer <api_key>` header generated from your saved CLI login.
+
+## MCP Installation
+
+Install or update MCP config after you have logged in:
+
+```bash
+arga login
+arga mcp install
+```
+
+The installer:
+
+- Detects supported local agent config directories.
+- Preserves existing `mcpServers` entries.
+- Merges in the generated `arga-context` server definition.
+- Returns a non-zero exit code if no supported targets are detected or if any target cannot be updated.
+
+If you need to add the server manually, the generated config looks like:
+
+```json
+{
+  "mcpServers": {
+    "arga-context": {
+      "url": "https://api.argalabs.com/mcp",
+      "headers": {
+        "Authorization": "Bearer <your-api-key>"
+      }
+    }
+  }
+}
+```
+
+## Using A Custom API URL
+
+By default, the CLI targets `https://api.argalabs.com`.
+
+To point it at another environment, pass `--api-url` or set `ARGA_API_URL`:
+
+```bash
+arga login --api-url http://localhost:8000
+arga mcp install --api-url http://localhost:8000
+arga test url --api-url http://localhost:8000 --url https://demo-app.com --prompt "test checkout"
+arga validate url --api-url http://localhost:8000 --url https://demo-app.com --prompt "test checkout"
+arga validate pr --api-url http://localhost:8000 --repo arga-labs/validation-server --pr 182
+```
+
+```bash
+export ARGA_API_URL=http://localhost:8000
+arga login
+```
+
+## Local Development
+
+```bash
+uv sync
+uv run pytest
+uv run arga --help
+```
+
+To install the current checkout as a shell command:
+
+```bash
+uv tool install -e .
+```
+
+## Config Storage
+
+The CLI stores its local auth state in:
+
+```bash
+~/.config/arga/config.json
+```
+
+That file contains the saved API key plus device metadata returned during `arga login`.

arga_cli-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+arga_cli/__init__.py,sha256=LAW9JWDNyNyHSyGOE1kdkqHVEKIH96pyAId4nXElvEY,24
+arga_cli/main.py,sha256=SkdAcx7n6-2L84FP_GTaVL3YjuJVhk6LthgdcfAIT60,39472
+arga_cli/mcp.py,sha256=W9OZbI_SjQARJR2bd2vz-0V0vzjTfqsKD1tZc0myR6s,3653
+arga_cli-0.1.0.dist-info/METADATA,sha256=P6DZ2JbUOEAc7AaENBy-zrbUAXKF5aXYz_y36iQQ1is,8386
+arga_cli-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+arga_cli-0.1.0.dist-info/entry_points.txt,sha256=oBp8vAj2Cot6llfpaf0ovJJ12jdNLpjaiZYxUnVvb4c,44
+arga_cli-0.1.0.dist-info/top_level.txt,sha256=ud5gQ95maAJ777TDrNnf4lMiYaikKV3xCsNEgbU5pjU,9
+arga_cli-0.1.0.dist-info/RECORD,,

arga_cli-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

arga_cli-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+arga = arga_cli.main:main

arga_cli-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+arga_cli