agentgov-cli 0.1.0__tar.gz

agentgov_cli-0.1.0/.gitignore

@@ -0,0 +1,81 @@
+# ============================================================================
+# AgentGov top-level .gitignore
+# Per-subsystem gitignores live inside control-tower/, gateway/, cli/ if needed.
+# ============================================================================
+
+# ---- Secrets & environment ----
+.env
+.env.local
+.env.*.local
+.env.production
+!.env.example
+!.env.act.example
+*.pem
+*.key
+!signing_keys.example/*.pub
+# PyPI publish token (project-local so twine finds it via `twine upload --config-file`)
+.pypirc
+
+# ---- Python ----
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+.venv/
+venv/
+env/
+ENV/
+build/
+dist/
+*.egg-info/
+.eggs/
+*.egg
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+.coverage.*
+htmlcov/
+coverage.xml
+*.cover
+.tox/
+
+# ---- Node / Next.js ----
+node_modules/
+.next/
+out/
+.vercel/
+.turbo/
+*.tsbuildinfo
+next-env.d.ts
+.pnpm-debug.log*
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+.pnpm-store/
+
+# ---- Supabase ----
+supabase/.branches/
+supabase/.temp/
+supabase/functions/*/deno.lock
+
+# ---- Gateway runtime state ----
+# The gateway keeps SQLite caches + disk-backed event queues in these paths.
+# They are ephemeral by design and must never be committed.
+gateway/.runtime/
+gateway/policy_cache.sqlite*
+gateway/event_queue/
+~/.agentgov/
+
+# ---- IDE / OS ----
+.vscode/
+.idea/
+*.swp
+*.swo
+.DS_Store
+Thumbs.db
+
+# ---- Local overrides ----
+*.local
+CLAUDE.local.md

agentgov_cli-0.1.0/PKG-INFO

@@ -0,0 +1,81 @@
+Metadata-Version: 2.5
+Name: agentgov-cli
+Version: 0.1.0
+Summary: AgentGov CLI — wrap Claude Code, bind work items, check gateway health.
+Author: AgentGov Contributors
+License: Apache-2.0
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27.2
+Requires-Dist: pydantic>=2.9.0
+Requires-Dist: pynacl>=1.5.0
+Requires-Dist: rich>=13.9.0
+Requires-Dist: typer>=0.12.5
+Requires-Dist: uuid7>=0.1.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.11.2; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
+Requires-Dist: pytest>=8.3.0; extra == 'dev'
+Requires-Dist: ruff>=0.6.9; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# agentgov
+
+The developer-laptop CLI for AgentGov.
+
+Wraps Claude Code to bind sessions to work items and enforce governance from a signed policy snapshot. Runs alongside `agentgov-gateway` (the local proxy) — this CLI handles login, device registration, session wrapping, work-item binding, and diagnostics.
+
+Part of the AgentGov project — see [github.com/deepakahu/agentGov](https://github.com/deepakahu/agentGov) for the full monorepo.
+
+## Install
+
+```bash
+pip install agentgov agentgov-gateway
+```
+
+## First-time setup
+
+```bash
+# Attach this machine to your AgentGov control tower
+agentgov login --tower https://your-agentgov.vercel.app
+
+# Register this device (generates an X25519 keypair, gets a gtw_ token)
+agentgov register-device --name "$(hostname)"
+
+# Drop Claude Code hooks + statusline + slash command into ~/.claude/
+agentgov install
+
+# Start the gateway (background)
+agentgov-gateway &
+```
+
+## Every day
+
+```bash
+# Run Claude Code through the governed gateway
+agentgov wrap claude
+
+# Bind the current session to a work item
+# (or use the /workitem slash command inside Claude Code)
+agentgov workitem PROJ-1234
+```
+
+## Diagnose
+
+```bash
+agentgov status    # what's my current binding, tokens, quota
+agentgov doctor    # is everything wired correctly
+```
+
+## Commands
+
+- `agentgov login` — attach this machine to a user in the control tower
+- `agentgov register-device` — generate device keypair + register with tower
+- `agentgov install` — drop client assets into `~/.claude/`
+- `agentgov wrap <cmd>` — wrap `claude` (or another command) in a governed session
+- `agentgov workitem <ref>` — bind the current session to a work item
+- `agentgov status` — show current binding + totals
+- `agentgov doctor` — diagnose the installation
+
+## License
+
+Apache-2.0

agentgov_cli-0.1.0/README.md

@@ -0,0 +1,61 @@
+# agentgov
+
+The developer-laptop CLI for AgentGov.
+
+Wraps Claude Code to bind sessions to work items and enforce governance from a signed policy snapshot. Runs alongside `agentgov-gateway` (the local proxy) — this CLI handles login, device registration, session wrapping, work-item binding, and diagnostics.
+
+Part of the AgentGov project — see [github.com/deepakahu/agentGov](https://github.com/deepakahu/agentGov) for the full monorepo.
+
+## Install
+
+```bash
+pip install agentgov agentgov-gateway
+```
+
+## First-time setup
+
+```bash
+# Attach this machine to your AgentGov control tower
+agentgov login --tower https://your-agentgov.vercel.app
+
+# Register this device (generates an X25519 keypair, gets a gtw_ token)
+agentgov register-device --name "$(hostname)"
+
+# Drop Claude Code hooks + statusline + slash command into ~/.claude/
+agentgov install
+
+# Start the gateway (background)
+agentgov-gateway &
+```
+
+## Every day
+
+```bash
+# Run Claude Code through the governed gateway
+agentgov wrap claude
+
+# Bind the current session to a work item
+# (or use the /workitem slash command inside Claude Code)
+agentgov workitem PROJ-1234
+```
+
+## Diagnose
+
+```bash
+agentgov status    # what's my current binding, tokens, quota
+agentgov doctor    # is everything wired correctly
+```
+
+## Commands
+
+- `agentgov login` — attach this machine to a user in the control tower
+- `agentgov register-device` — generate device keypair + register with tower
+- `agentgov install` — drop client assets into `~/.claude/`
+- `agentgov wrap <cmd>` — wrap `claude` (or another command) in a governed session
+- `agentgov workitem <ref>` — bind the current session to a work item
+- `agentgov status` — show current binding + totals
+- `agentgov doctor` — diagnose the installation
+
+## License
+
+Apache-2.0

agentgov_cli-0.1.0/agentgov_cli/__init__.py

@@ -0,0 +1,3 @@
+"""AgentGov CLI. Developer-laptop tool: wrap · workitem · status · doctor."""
+
+__version__ = "0.1.0"

agentgov_cli-0.1.0/agentgov_cli/commands/doctor.py

@@ -0,0 +1,168 @@
+"""`agentgov doctor` — diagnose the installation (CLAUDE.md §13, §14).
+
+The old §12.1 blanket rule ("gateway must NEVER run on a governed developer's
+machine") has been REPLACED by the §14.4 CONDITIONAL rule:
+
+  The gateway MAY run locally provided
+    (a) upstream_mode = oauth_passthrough  (no vault to steal)
+    OR
+    (b) every credential is user-scoped + spending-capped + device-encrypted.
+
+So this doctor:
+  - Confirms local gateway is reachable (green: it IS local).
+  - Reports the machine fingerprint + the upstream_mode the gateway is
+    running in.
+  - Flags a WARNING (not an error) only if apikey_vault is on AND we couldn't
+    confirm device-encrypted delivery (i.e. an env-provided key overrides the
+    sealed cred — legacy §12 path on a dev machine, which we discourage).
+"""
+
+from __future__ import annotations
+
+import hashlib
+import platform
+import socket
+import uuid
+from pathlib import Path
+
+import httpx
+import typer
+from rich.console import Console
+from rich.table import Table
+
+console = Console()
+
+
+def run(
+    gateway_url: str = typer.Option(None, "--gateway", envvar="AGENTGOV_GATEWAY_URL"),
+) -> None:
+    ok = 0
+    warn = 0
+    fail = 0
+    table = Table("check", "result", "detail", show_lines=False)
+
+    # 1. Managed settings present (Linux only; on macOS/Windows we just show the path)
+    settings_path = _managed_settings_path()
+    if settings_path.exists():
+        table.add_row("managed-settings.json", "[green]OK[/]", str(settings_path))
+        ok += 1
+    else:
+        table.add_row("managed-settings.json", "[yellow]MISSING[/]", str(settings_path))
+        warn += 1
+
+    # 2. Hooks executable
+    hooks_dir = Path.home() / ".claude" / "agentgov-hooks"
+    if not hooks_dir.exists():
+        table.add_row("hooks installed", "[red]MISSING[/]", str(hooks_dir))
+        fail += 1
+    else:
+        problems = [str(h) for h in hooks_dir.glob("*.py") if not h.stat().st_mode & 0o100]
+        if problems:
+            table.add_row("hooks executable", "[red]FAIL[/]", ", ".join(problems))
+            fail += 1
+        else:
+            table.add_row("hooks executable", "[green]OK[/]", str(hooks_dir))
+            ok += 1
+
+    # 3. Statusline installed
+    sl = Path.home() / ".claude" / "agentgov-statusline" / "agentgov_statusline.sh"
+    if sl.exists():
+        table.add_row("statusline installed", "[green]OK[/]", str(sl))
+        ok += 1
+    else:
+        table.add_row("statusline installed", "[yellow]MISSING[/]", str(sl))
+        warn += 1
+
+    # 4. Identity + device registration (§13/§14)
+    identity = Path.home() / ".agentgov" / "identity.json"
+    creds = Path.home() / ".agentgov" / "gateway_creds.json"
+    if identity.exists():
+        table.add_row("identity", "[green]OK[/]", str(identity))
+        ok += 1
+    else:
+        table.add_row("identity", "[yellow]MISSING[/]", "run `agentgov login`")
+        warn += 1
+    if creds.exists():
+        table.add_row("device registered", "[green]OK[/]", str(creds))
+        ok += 1
+    else:
+        table.add_row(
+            "device registered", "[yellow]MISSING[/]", "run `agentgov register-device --name ...`"
+        )
+        warn += 1
+
+    # 5. Gateway reachable
+    url = gateway_url or "http://localhost:8000"
+    upstream_mode = None
+    try:
+        r = httpx.get(f"{url}/health", timeout=3.0)
+        if r.status_code == 200:
+            table.add_row("gateway reachable", "[green]OK[/]", url)
+            ok += 1
+            # Try to read the mode from the /admin endpoint or fall back to
+            # env — for now we just show what env says.
+            import os as _os
+
+            upstream_mode = _os.environ.get("UPSTREAM_MODE", "oauth_passthrough")
+        else:
+            table.add_row("gateway reachable", "[red]FAIL[/]", f"{url} → HTTP {r.status_code}")
+            fail += 1
+    except Exception as e:
+        table.add_row("gateway reachable", "[red]FAIL[/]", f"{url}: {e}")
+        fail += 1
+
+    # 6. §14.4 CONDITIONAL rule check
+    fp = _machine_fingerprint()
+    if upstream_mode == "oauth_passthrough":
+        table.add_row(
+            "§14.4 rule",
+            "[green]OK[/]",
+            f"oauth_passthrough — no vault  ·  fingerprint={fp[:16]}…",
+        )
+        ok += 1
+    elif upstream_mode == "apikey_vault":
+        # We can't introspect the running gateway's config remotely (yet).
+        # This is a soft warning until we add /admin/mode endpoint.
+        import os as _os
+
+        legacy_env_key = bool(_os.environ.get("ANTHROPIC_API_KEY", ""))
+        if legacy_env_key:
+            table.add_row(
+                "§14.4 rule",
+                "[yellow]WARN[/]",
+                (
+                    "apikey_vault WITH env-provided ANTHROPIC_API_KEY — legacy §12 path. "
+                    "Prefer per-device sealed credentials."
+                ),
+            )
+            warn += 1
+        else:
+            table.add_row(
+                "§14.4 rule",
+                "[green]OK[/]",
+                "apikey_vault via per-device sealed credential (recommended)",
+            )
+            ok += 1
+
+    console.print(table)
+    console.print(f"\n[bold]{ok} OK  ·  {warn} WARN  ·  {fail} FAIL[/]")
+    if fail:
+        raise typer.Exit(2)
+    if warn:
+        raise typer.Exit(1)
+
+
+def _managed_settings_path() -> Path:
+    sysname = platform.system()
+    if sysname == "Darwin":
+        return Path("/Library/Application Support/ClaudeCode/managed-settings.json")
+    if sysname == "Windows":
+        return Path(r"C:\ProgramData\ClaudeCode\managed-settings.json")
+    return Path("/etc/claude-code/managed-settings.json")
+
+
+def _machine_fingerprint() -> str:
+    """SHA-256 of hostname + a stable MAC — same recipe as the gateway."""
+    hostname = socket.gethostname()
+    mac = uuid.getnode()
+    return hashlib.sha256(f"{hostname}:{mac:012x}".encode()).hexdigest()

agentgov_cli-0.1.0/agentgov_cli/commands/install.py

@@ -0,0 +1,122 @@
+"""`agentgov install` — copies client assets to ~/.claude/, prints managed-settings.json.
+
+The managed-settings.json is printed to stdout (with the admin-visible path per OS)
+so an administrator can drop it into the OS-managed path. That path is ROOT-owned;
+we do NOT try to write it — the CLI runs as the developer.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import platform
+import shutil
+import sys
+from pathlib import Path
+
+from rich.console import Console
+
+console = Console()
+
+# Asset source is discovered relative to the installed package (client_assets is
+# a sibling directory of the cli/). In wheel installs we ship it via
+# package data; in local dev we look up-tree.
+ASSET_ROOTS = [
+    Path(__file__).resolve().parent.parent.parent.parent / "client_assets",
+    Path(sys.prefix) / "share" / "agentgov" / "client_assets",
+]
+
+
+def run(
+    gateway_url: str = "http://localhost:8000",
+    force: bool = False,
+) -> None:
+    """Install hooks + statusline + slash commands into ~/.claude/."""
+    src = _find_assets()
+    dest = Path.home() / ".claude"
+    dest.mkdir(exist_ok=True)
+
+    hooks_src = src / "hooks"
+    hooks_dest = dest / "agentgov-hooks"
+    if hooks_dest.exists() and not force:
+        console.print(f"[yellow]Skipping[/] hooks — {hooks_dest} exists (use --force)")
+    else:
+        shutil.copytree(hooks_src, hooks_dest, dirs_exist_ok=True)
+        for h in hooks_dest.glob("*.py"):
+            h.chmod(0o755)
+        console.print(f"[green]Copied[/] hooks → {hooks_dest}")
+
+    statusline_src = src / "statusline"
+    statusline_dest = dest / "agentgov-statusline"
+    if statusline_dest.exists() and not force:
+        console.print(f"[yellow]Skipping[/] statusline — {statusline_dest} exists")
+    else:
+        shutil.copytree(statusline_src, statusline_dest, dirs_exist_ok=True)
+        for h in statusline_dest.glob("*.sh"):
+            h.chmod(0o755)
+        console.print(f"[green]Copied[/] statusline → {statusline_dest}")
+
+    commands_dest = dest / "commands"
+    commands_dest.mkdir(exist_ok=True)
+    shutil.copy2(src / "commands" / "workitem.md", commands_dest / "workitem.md")
+    console.print(f"[green]Copied[/] /workitem slash command → {commands_dest / 'workitem.md'}")
+
+    settings = _build_managed_settings(gateway_url, hooks_dest, statusline_dest)
+    console.rule("[bold]managed-settings.json[/]")
+    console.print(f"Ask your admin to save this file at:\n  {_managed_settings_path()}\n")
+    console.print(json.dumps(settings, indent=2))
+
+
+def _find_assets() -> Path:
+    for root in ASSET_ROOTS:
+        if root.exists():
+            return root
+    raise FileNotFoundError(f"client_assets/ not found in any of: {ASSET_ROOTS}")
+
+
+def _build_managed_settings(
+    gateway_url: str, hooks_dest: Path, statusline_dest: Path
+) -> dict[str, object]:
+    return {
+        "env": {
+            "ANTHROPIC_BASE_URL": gateway_url,
+            "AGENTGOV_LOOPBACK_PORT": os.environ.get("AGENTGOV_LOOPBACK_PORT", "8788"),
+        },
+        # apiKeyHelper disabled — Claude Code must use the agk_ key from the wrapper env.
+        "apiKeyHelper": "",
+        "hooks": {
+            "PreToolUse": [
+                {
+                    "matcher": "Read|Write|Edit|Glob|Grep|Bash|NotebookEdit",
+                    "hooks": [
+                        {"type": "command", "command": str(hooks_dest / "pretooluse_pathguard.py")}
+                    ],
+                }
+            ],
+            "SessionStart": [
+                {
+                    "hooks": [
+                        {"type": "command", "command": str(hooks_dest / "sessionstart_register.py")}
+                    ]
+                }
+            ],
+        },
+        "statusLine": {
+            "type": "command",
+            "command": str(statusline_dest / "agentgov_statusline.sh"),
+        },
+        # Permissions baseline: developers may NOT override the base URL or hooks.
+        "permissions": {
+            "allow": [],
+            "deny": [],
+        },
+    }
+
+
+def _managed_settings_path() -> str:
+    sysname = platform.system()
+    if sysname == "Darwin":
+        return "/Library/Application Support/ClaudeCode/managed-settings.json"
+    if sysname == "Windows":
+        return r"C:\ProgramData\ClaudeCode\managed-settings.json"
+    return "/etc/claude-code/managed-settings.json"

agentgov_cli-0.1.0/agentgov_cli/commands/login.py

@@ -0,0 +1,74 @@
+"""`agentgov login` — obtain an AgentGov session token (CLAUDE.md §13.5).
+
+v1 implements a DEV-ONLY stub: the CLI accepts a bearer token you paste
+(from the dashboard) and stores it in ~/.agentgov/identity.json (0600).
+The real OAuth device-code flow lands with Auth0 in Phase 5; the file
+layout + tower endpoint are already device-code-shaped so the swap is
+transparent to `wrap`.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+
+import httpx
+import typer
+from rich.console import Console
+
+console = Console()
+
+
+def run(
+    tower_url: str = typer.Option(
+        None, "--tower", envvar="CONTROL_TOWER_URL", help="Control tower URL"
+    ),
+    token: str = typer.Option(
+        None,
+        "--token",
+        help="Paste your dev-admin token (development mode only). Prompts if omitted.",
+        prompt=False,
+    ),
+) -> None:
+    """Attach this machine to a user in the AgentGov control tower."""
+    tower = tower_url or os.environ.get("CONTROL_TOWER_URL") or "http://localhost:3000"
+
+    if not token:
+        console.print(
+            "[bold]Dev-mode login[/] — paste a dev-admin token from the dashboard, or "
+            "the literal string 'agentgov-dev-admin' to use the seeded ADMIN.",
+        )
+        token = typer.prompt("token", hide_input=True).strip()
+    else:
+        token = token.strip()
+
+    # Verify the token can list /api/devices (a low-risk authenticated call).
+    try:
+        r = httpx.get(
+            f"{tower.rstrip('/')}/api/devices",
+            headers={"Authorization": f"Bearer {token}"},
+            timeout=10.0,
+        )
+    except Exception as e:
+        console.print(f"[red]Cannot reach control tower at {tower}: {e}[/]")
+        raise typer.Exit(2) from e
+    if r.status_code == 401:
+        console.print("[red]Token rejected by control tower.[/]")
+        raise typer.Exit(2)
+    if r.status_code >= 400:
+        console.print(f"[red]Unexpected response from control tower: {r.status_code} {r.text}[/]")
+        raise typer.Exit(2)
+
+    # Persist.
+    identity_path = Path.home() / ".agentgov" / "identity.json"
+    identity_path.parent.mkdir(parents=True, exist_ok=True)
+    payload = {
+        "tower_url": tower,
+        "auth0_token": token,
+        # user_id + tenant_id populated on register-device response.
+    }
+    identity_path.write_text(json.dumps(payload, indent=2))
+    identity_path.chmod(0o600)
+    console.print(f"[green]✅ Logged in.[/] Identity saved to {identity_path}")
+    console.print("Next: [bold]agentgov register-device --name 'my-laptop'[/]")