terraui 0.1.0__tar.gz

terraui-0.1.0/.gitignore

@@ -0,0 +1,38 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+*.egg
+
+# Virtual envs
+.venv/
+venv/
+env/
+
+# Tooling / caches
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# Local runtime / scratch
+*.out
+pytest.out
+terraui.db
+*.sqlite
+*.sqlite3
+
+# Editors / OS
+.vscode/
+.idea/
+.DS_Store
+Thumbs.db
+
+# Secrets / env
+.env
+.env.*
+!.env.example

terraui-0.1.0/BACKEND_SPEC.md

@@ -0,0 +1,388 @@
+# TerraUi — Backend Build Prompt / Engineering Spec
+
+> Hand this document to an engineer (or to Claude Code) as the build brief for the
+> TerraUi backend. The frontend (`TerraUi.dc.html`) is the source of truth for the
+> product surface; this spec defines the engine that makes it real.
+
+---
+
+## 0. Mission
+
+TerraUi is a **local-first control plane for Terraform and Terragrunt**. An org points it at
+the directory that holds all their IaC repos; TerraUi discovers every unit (standalone
+Terraform *and* Terragrunt), and gives a single web UI to:
+
+- inventory every stack across clouds (AWS, GCP, Azure) and environments,
+- run `plan` / `apply` / `destroy` with a flag picker, streamed live,
+- detect and reconcile **drift**,
+- view **diffs** and full plan output,
+- see **who holds the state lock** and acquire/release it,
+- read **history / audit** (who changed what, from which PR/commit),
+- orchestrate **Terragrunt dependency-ordered** `run-all`,
+- generate plans from **GitHub & GitLab PRs**,
+- expose a **Cloud Shell** (real terminal) wired to the user's local shell + cloud SDKs,
+- answer questions via an **AI assistant**.
+
+Install path the user expects:
+
+```bash
+pip install terraui
+cd ~/acme/infra        # the folder that contains all IaC repos
+terraui start          # discovers everything, opens http://localhost:8787
+```
+
+**Core principle:** TerraUi runs commands on the *user's own machine*, using the *user's own
+shell* (PowerShell on Windows, zsh/bash on macOS & Linux) and the *user's existing cloud
+credentials*. It never stores secrets and never invents its own auth — it shells out exactly
+as the engineer would by hand.
+
+---
+
+## 1. Tech stack
+
+| Concern | Choice | Notes |
+|---|---|---|
+| Language | **Python 3.10+** | Matches `pip install` expectation. |
+| Web framework | **FastAPI** + **Uvicorn** | REST + WebSocket in one app. |
+| Async | `asyncio` + `anyio` | Subprocess streaming, concurrency. |
+| CLI | **Typer** (or Click) | `terraui start|server|agent|scan`. |
+| Terminal | **ptyprocess** / `pywinpty` (Windows) + **xterm.js** on the front | Real PTY. |
+| HCL parsing | **python-hcl2** + targeted regex fallbacks | Parse providers, backends, deps. |
+| Local store | **SQLite** (local mode) → **Postgres** (server mode) via SQLAlchemy | Runs, audit, drift snapshots. |
+| Realtime | WebSockets | Run output, terminal, drift events. |
+| Packaging | **pyproject.toml** (hatchling/poetry), console_scripts entry point | Ships the built frontend as package data. |
+
+The compiled frontend (a single self-contained HTML bundle of `TerraUi.dc.html`) is shipped
+inside the wheel and served at `/`. `terraui start` opens the browser to it.
+
+---
+
+## 2. CLI surface
+
+```
+terraui start [PATH]               # local mode: scan PATH (default cwd), serve UI + executor
+    --port 8787
+    --scan ./live ./modules        # extra roots / globs
+    --no-open                       # don't auto-open browser
+    --shell powershell|zsh|bash    # override detected shell
+    --drift-interval 30m            # background drift scan cadence (0 = off)
+
+terraui scan [PATH] --json         # print discovered units as JSON, no server (CI/debug)
+
+terraui server --config terraui.yaml   # team mode: central control plane (SSO, RBAC, Postgres)
+terraui agent --server URL --label prod-runner   # remote executor that registers with a server
+```
+
+Local mode = single binary, single user, zero infra. Server mode = shared deployment;
+**agents** hold the cloud creds and do the execution, the server never does (see §11).
+
+---
+
+## 3. Architecture
+
+```
+                 ┌──────────────────────────────────────────────┐
+   Browser  ──►  │  FastAPI app                                   │
+  (TerraUi UI)   │   ├─ REST  /api/...        (inventory, runs)   │
+       ▲   WS    │   ├─ WS    /ws/run/{id}    (live plan output)  │
+       └─────────┤   ├─ WS    /ws/term/{id}   (PTY terminal)      │
+                 │   ├─ Discovery service (HCL walk + parse)      │
+                 │   ├─ Execution engine (subprocess/PTY)         │
+                 │   ├─ Auth probe (aws/gcloud/az)                │
+                 │   ├─ State+lock inspector (per backend)        │
+                 │   ├─ Drift scheduler                           │
+                 │   ├─ VCS connectors (GitHub/GitLab)            │
+                 │   └─ AI service (LLM proxy + repo RAG)         │
+                 └──────────────────────────────────────────────┘
+                                  │ subprocess (user's shell)
+                                  ▼
+              terraform / terragrunt / aws / gcloud / az  on the local machine
+```
+
+---
+
+## 4. Discovery service
+
+On `start`, walk the scan roots and build the stack inventory.
+
+**Detection rules**
+- A directory with `*.tf` files → a **Terraform unit**.
+- A directory with `terragrunt.hcl` → a **Terragrunt unit** (takes precedence; the surrounding
+  `live/<env>/<stack>` convention defines env + stack name).
+- Read the `terraform { backend "<type>" { ... } }` block to find the **state location**
+  (s3/gcs/azurerm/local/remote) and any **lock table/lease**.
+- Parse `provider "<name>" { ... }` and `required_providers` to infer the **cloud**
+  (`aws`→AWS, `google`/`google-beta`→GCP, `azurerm`→Azure). A unit may be multi-cloud.
+- For Terragrunt, parse `dependency "<x>" { config_path = ... }` and `dependencies { paths = [...] }`
+  to build the **DAG** used for `run-all` ordering.
+- Derive **environment** from path (`live/prod/...`, `*-prod`, workspace) — make this
+  configurable via `terraui.yaml` overrides.
+
+**Output:** a normalized model the frontend consumes (one row per stack):
+
+```jsonc
+{
+  "id": "eks-prod",
+  "name": "eks-cluster",
+  "env": "prod",
+  "tool": "terragrunt",          // or "terraform"
+  "clouds": ["aws"],
+  "path": "live/prod/eks-cluster",
+  "vcs": { "host": "github", "repo": "acme/infra-live", "subdir": "live/prod/eks-cluster" },
+  "backend": { "type": "s3", "bucket": "acme-tfstate", "key": "prod/eks.tfstate",
+               "lock": { "type": "dynamodb", "table": "acme-tf-locks" } },
+  "deps": ["net-prod"],
+  "resourceCount": 88,
+  "status": "drift|healthy|running|error|plan_pending",
+  "drift": 3,
+  "lock": null
+}
+```
+
+Discovery must be **incremental & watchable** — re-scan on file change (watchdog) so the UI
+stays live as repos change. Cache parse results keyed by file mtime.
+
+---
+
+## 5. Execution engine
+
+The heart of the product. Runs `terraform`/`terragrunt` as a child process **in the unit's
+directory**, using the user's shell, streaming output to the browser.
+
+**Requirements**
+- Build the command from a structured request (see flag model below) — never string-concat
+  untrusted input; pass args as a list, validate the action against an allow-list
+  (`plan|apply|destroy|init|validate|output|state list|force-unlock`).
+- Spawn via the detected shell so the user's PATH, profile, and cloud CLI shims are present:
+  - Windows: `pwsh -NoLogo -Command <cmd>` (fallback `powershell.exe`).
+  - macOS/Linux: `$SHELL -lc <cmd>` (login shell to load creds/profile).
+- Stream **stdout+stderr** line-buffered over `WS /ws/run/{run_id}`. Emit structured events:
+  `{type:"line", stream:"stdout", text}`, `{type:"status", status}`, `{type:"summary", add, change, destroy}`.
+- Parse `terraform plan -json` / `-detailed-exitcode` to populate the **diff** and the
+  `+add ~change -destroy` summary the UI shows. Prefer `-json` for machine parsing; keep the
+  raw text for the log pane.
+- Persist every run: id, stack, action, full command, actor, trigger (manual/PR/merge/drift/schedule),
+  exit code, duration, summary, and the complete log. This is the **audit trail**.
+- Concurrency: serialize runs per stack (one lock per state); allow parallel across independent
+  stacks. For Terragrunt `run-all`, resolve the DAG and execute level-by-level honoring `--terragrunt-parallelism`.
+
+**Flag model** (mirrors the UI's run picker — `cmdVM` in the frontend):
+
+```jsonc
+{
+  "stackId": "rds-prod",
+  "action": "plan",                 // plan | apply | destroy
+  "runAll": false,                  // terragrunt run-all
+  "flags": {
+    "refresh": true,                // -refresh=false when false
+    "lock": true,                   // -lock=false when false
+    "autoApprove": false,           // -auto-approve (apply/destroy only)
+    "noColor": false,               // -no-color
+    "nonInteractive": true,         // --terragrunt-non-interactive
+    "parallelism": 10,              // -parallelism=N
+    "target": "",                   // -target=ADDR (repeatable)
+    "varFile": "env/prod.tfvars"    // -var-file=FILE (repeatable)
+  }
+}
+```
+
+`build_command()` must produce exactly what the UI previews, e.g.
+`terragrunt run-all plan -var-file=env/prod.tfvars --terragrunt-non-interactive`.
+
+---
+
+## 6. Cloud Shell (PTY terminal)
+
+A genuine interactive terminal, not a fake. `WS /ws/term/{session}` bridges xterm.js to a PTY
+running the user's shell in the IaC root. Supports `aws`, `gcloud`, `az`, `terraform`,
+`terragrunt`, `git`, etc. — anything on the user's PATH.
+
+- Use `ptyprocess` (POSIX) / `pywinpty` (Windows). Forward keystrokes, stream output, handle
+  resize (`SIGWINCH` / pty set-size) from the client's `cols/rows`.
+- The "Run on shell" button in the UI's flag modal sends a composed command into this session
+  (or a dedicated run session) so plan/apply output streams in the same place.
+- Reflect the active shell (PowerShell/zsh/bash) in the prompt; allow switching the executor shell.
+
+---
+
+## 7. Cloud SDK auth detection
+
+Probe each cloud's CLI and surface status in the top bar + Cloud Shell. Run these read-only
+checks (cache results ~60s, re-probe on demand and after a login):
+
+| Cloud | Probe command | Authenticated when |
+|---|---|---|
+| **AWS** | `aws sts get-caller-identity` | exit 0; show Account + Arn + region |
+| **GCP** | `gcloud auth application-default print-access-token` **and** `gcloud auth list` | ADC token prints **and** an active account exists |
+| **Azure** | `az account show` | exit 0; show subscription name/id |
+
+**GCP needs both logins** — document and surface this clearly:
+- `gcloud auth login` → user identity for the `gcloud` CLI.
+- `gcloud auth application-default login` → **ADC**, which the Terraform `google` provider uses.
+
+If a probe fails / token expired → mark the cloud **re-auth** (amber), gate affected stacks,
+and offer the exact remediation command (`az login`, `aws sso login --profile …`,
+`gcloud auth application-default login`) runnable straight from the Cloud Shell. Detect SDK
+presence + versions (`aws --version`, `gcloud --version`, `az version`) and warn if missing,
+with install links.
+
+---
+
+## 8. State & lock inspection
+
+Per backend type, without mutating state:
+
+- **Read state / resource list:** `terraform state list` + `terraform show -json` (run in unit dir).
+- **Locks:**
+  - S3 + **DynamoDB**: read the lock item from the lock table → who/when/lock-id.
+  - **GCS**: object generation/metadata lock.
+  - **azurerm**: blob **lease** state.
+- Surface lock holder, age, and lock-id in the UI. Support **acquire/release**:
+  release maps to `terraform force-unlock <LOCK_ID>` (guarded — require confirmation + RBAC in
+  server mode).
+- Optional **state versioning/history** (bucket versioning, or TerraUi-side snapshots) for the
+  "who changed what" timeline.
+
+---
+
+## 9. Drift detection
+
+- Scheduled background scan (default every 30m, `--drift-interval`): per stack run
+  `terraform plan -detailed-exitcode -refresh-only` (exit code 2 = drift) or parse a normal
+  `-json` plan for changes not originating from config.
+- Store drift snapshots: per-resource, attribute-level `state` vs `actual` (exactly what the
+  Drift tab renders). Emit a WS event so the sidebar badge and dashboard metric update live.
+- "Reconcile" action → opens the run picker pre-set to `plan` for that stack.
+
+---
+
+## 10. VCS integration (GitHub & GitLab)
+
+- OAuth/App install or PAT. Register **webhooks**: on PR/MR open & push, identify affected
+  stacks (changed paths ∩ discovered units) and run a **speculative plan**; post the
+  `+add ~change -destroy` summary + a link back to TerraUi as a PR/MR comment + status check.
+- On merge to the default branch → optionally trigger `apply` (policy-gated).
+- Record the PR/MR number, branch, commit SHA, and author on the run so the Runs/audit view can
+  show "GH #482 / GL !113 — title" with the engineer behind it (matches the frontend's run rows).
+- Abstract a `VCSProvider` interface; implement `GitHubProvider` and `GitLabProvider`.
+
+---
+
+## 11. Team mode & scaling (future-ready from day one)
+
+Design the local app so the same core promotes to a shared deployment without a rewrite:
+
+- **Server mode** (`terraui server`): central FastAPI + Postgres, serves the UI to many users.
+- **Agents** (`terraui agent`): remote executors that register with the server, hold the cloud
+  creds for their environment, pull run jobs from a queue, and stream output back. The server
+  **never** holds cloud secrets.
+- **Job queue / workers:** Redis or Postgres-backed (e.g. `arq`/Celery) for fan-out and
+  run-all orchestration across agents.
+- **AuthN/Z:** OIDC/SAML SSO; **RBAC** with per-environment apply approvals; optional policy
+  gate (**OPA / Sentinel**) evaluated on the plan before apply is allowed.
+- **Multi-tenant:** org → projects → stacks; row-level scoping in Postgres.
+- **Observability:** structured logs, Prometheus metrics, OpenTelemetry traces on runs.
+
+Keep all execution behind an `Executor` interface with `LocalExecutor` (subprocess/PTY) and
+`AgentExecutor` (remote) implementations — local and server modes differ only in which executor
+and store are wired in.
+
+---
+
+## 12. AI assistant
+
+- Endpoint `POST /api/ai/chat` proxying an LLM. **Never** put model keys in the browser; the
+  server holds them (env/secret store).
+- Ground answers in the user's repos: build a lightweight index (RAG) over discovered HCL,
+  backend configs, latest plan/drift snapshots, and run history, so questions like
+  "why is eks-cluster drifting?" use real context.
+- Allow the assistant to call **read-only** tools (state list, plan summary, auth status, dep
+  graph) but require explicit human approval before any mutating action — surface that guarantee
+  in the UI ("never applies without approval").
+- Stream tokens over SSE/WS for a responsive chat.
+
+---
+
+## 13. API surface (align with the frontend)
+
+REST (JSON):
+```
+GET    /api/stacks                      → inventory (see §4 model)
+GET    /api/stacks/{id}                 → detail + backend + deps + activity
+GET    /api/stacks/{id}/state           → resource list
+GET    /api/stacks/{id}/drift           → attribute-level drift snapshot
+POST   /api/stacks/{id}/lock            → acquire   |  DELETE → release (force-unlock)
+POST   /api/runs                        → start a run (flag model §5) → {runId}
+GET    /api/runs                        → history (filter: pr|manual|schedule|drift)
+GET    /api/runs/{id}                   → run detail + full log
+GET    /api/graph?env=prod              → Terragrunt DAG + run-all order
+GET    /api/clouds                      → auth status per cloud (§7)
+POST   /api/ai/chat                     → assistant
+GET    /api/health
+```
+WebSocket:
+```
+/ws/run/{runId}     → live run events (line/status/summary)
+/ws/term/{session}  → PTY terminal I/O + resize
+/ws/events          → inventory/drift/lock change push (UI live updates)
+```
+
+---
+
+## 14. Security
+
+- No secret storage. Use the cloud SDK credential chains already on the machine/agent.
+- Command allow-list + argument validation; never shell-interpolate user strings — pass argv.
+- Bind local mode to `127.0.0.1` by default; CSRF/Origin checks on WS upgrades.
+- Server mode: TLS, SSO, RBAC, signed agent registration, full audit log of every run & lock op.
+- Redact secrets from streamed logs (provider env vars, tokens) before persistence.
+
+---
+
+## 15. Packaging & layout
+
+```
+terraui/
+├─ pyproject.toml            # [project.scripts] terraui = "terraui.cli:app"
+├─ terraui/
+│  ├─ cli.py                 # Typer app: start/server/agent/scan
+│  ├─ server/app.py          # FastAPI factory, routers, WS
+│  ├─ discovery/             # walk + HCL parse + DAG
+│  ├─ exec/                  # Executor, LocalExecutor, AgentExecutor, PTY
+│  ├─ clouds/                # aws/gcp/azure auth probes
+│  ├─ state/                 # backend-specific state + lock inspectors
+│  ├─ drift/                 # scheduler + snapshots
+│  ├─ vcs/                   # github.py, gitlab.py
+│  ├─ ai/                    # chat + RAG
+│  ├─ store/                 # SQLAlchemy models, sqlite/postgres
+│  └─ web/                   # bundled frontend (TerraUi.html) as package data
+└─ tests/
+```
+
+> Implementation note: this repo uses a `src/terraui/` layout (PyPI best practice). The
+> `exec/` module is named `execution/` (avoids shadowing the Python builtin); the bundled
+> frontend lives at `src/terraui/web/index.html`.
+
+---
+
+## 16. Milestones
+
+1. **M1 — Inventory + UI shell:** discovery, `terraui start`, serve frontend, stacks list, state read.
+2. **M2 — Execution:** flag-model runs (plan/apply/destroy) streamed over WS; run history/audit; PTY Cloud Shell.
+3. **M3 — Drift + locks:** scheduled drift scans, attribute diffs, lock inspect/acquire/release.
+4. **M4 — Terragrunt orchestration:** DAG + dependency-ordered `run-all`.
+5. **M5 — VCS:** GitHub/GitLab webhooks, speculative PR plans, status checks, apply-on-merge.
+6. **M6 — AI assistant:** grounded chat with read-only tool access.
+7. **M7 — Server mode:** agents, SSO, RBAC, Postgres, policy gates — the scale story.
+
+---
+
+## 17. Acceptance (local mode MVP)
+
+```bash
+pip install terraui && cd ~/acme/infra && terraui start
+```
+…must: discover every Terraform & Terragrunt unit; show them grouped by env/cloud; report
+AWS/GCP/Azure auth status; let me open a stack, pick flags, run a streamed `plan`, see the diff,
+view drift, see who holds the lock, read run history with the triggering PR — and open a Cloud
+Shell that runs `az login` / `gcloud auth application-default login` against my real machine.

terraui-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Preet
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

terraui-0.1.0/PKG-INFO

@@ -0,0 +1,156 @@
+Metadata-Version: 2.4
+Name: terraui
+Version: 0.1.0
+Summary: Local-first control plane for Terraform & Terragrunt — inventory, plan/apply, drift, locks and a cloud shell, in one UI.
+Project-URL: Homepage, https://gitlab.com/terraui/terraui
+Project-URL: Repository, https://gitlab.com/terraui/terraui.git
+Project-URL: Issues, https://gitlab.com/terraui/terraui/-/issues
+Author: Preet
+License: MIT
+License-File: LICENSE
+Keywords: control-plane,devops,drift,iac,infrastructure,terraform,terragrunt
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Environment :: Web Environment
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: Topic :: System :: Systems Administration
+Requires-Python: >=3.10
+Requires-Dist: fastapi>=0.110
+Requires-Dist: httpx>=0.27
+Requires-Dist: python-hcl2>=4.3; python_version < '4'
+Requires-Dist: typer>=0.12
+Requires-Dist: uvicorn[standard]>=0.29
+Provides-Extra: ai
+Requires-Dist: anthropic>=0.40; extra == 'ai'
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: twine>=5; extra == 'dev'
+Provides-Extra: pty
+Requires-Dist: ptyprocess>=0.7; (sys_platform != 'win32') and extra == 'pty'
+Requires-Dist: pywinpty>=2.0; (sys_platform == 'win32') and extra == 'pty'
+Description-Content-Type: text/markdown
+
+# TerraUi
+
+A **local-first control plane for Terraform & Terragrunt**. Point it at the folder
+that holds all your IaC repos; it discovers every unit, and gives one web UI to
+inventory stacks, run `plan`/`apply`/`destroy` (streamed live), detect drift, read
+state and locks, browse the Terragrunt dependency graph, open a cloud shell, and
+ask an AI assistant.
+
+This repo implements the `TerraUi.dc.html` design (the product surface) plus the
+backend from `BACKEND_SPEC.md`. It ships as a Python package with the compiled
+frontend bundled and served at `/`.
+
+```bash
+pip install -e .            # from this repo (Python 3.10+)
+cd ~/acme/infra             # the folder containing your IaC repos
+terraui start               # discovers everything, opens http://localhost:8787
+```
+
+No IaC in the current folder? `terraui start` falls back to a fully-populated
+**demo dataset** (the one from the design) so you can explore the whole UI.
+
+## Cloud SDK setup (gcloud / aws / az)
+
+TerraUi shells out to your existing cloud CLIs — it never stores credentials. On
+first `terraui start` it runs a **read-only** check of the providers your stacks
+actually use and, if anything is missing, points you at `terraui setup`:
+
+```bash
+terraui setup            # per provider: detect → offer install → offer login
+```
+
+`setup` is **per-provider and skippable** — if you only use GCP, skip AWS and
+Azure and configure them later. It shows the exact install/login command before
+running it and asks for confirmation; nothing happens silently. GCP runs **both**
+required logins (`gcloud auth login` for the CLI and
+`gcloud auth application-default login` for the Terraform provider).
+
+## CLI
+
+```
+terraui start [PATH]        Local mode: scan PATH (default cwd), serve UI + executor
+    --port 8787             Port (default 8787)
+    --scan ./live ./mods    Extra roots to scan
+    --no-open               Don't auto-open the browser
+    --shell powershell|zsh|bash
+    --drift-interval 30m    Background drift cadence (0 = off)
+    --demo                  Force the bundled demo dataset
+    --check                 Run interactive cloud-SDK setup before serving
+    --skip-checks           Skip the cloud-SDK status check
+
+terraui setup [PATH]        Detect / install / authenticate cloud SDKs (per-provider, skippable)
+    --providers aws,gcp,azure   Limit to specific providers
+    --yes                       Non-interactive (install only; skip browser logins)
+
+terraui scan [PATH] --json  Print discovered units as JSON (CI / debug)
+terraui server  --config …  Team mode (scaffold — see BACKEND_SPEC §11)
+terraui agent   --server …  Remote executor (scaffold)
+```
+
+## What's implemented
+
+| Area | Status |
+|---|---|
+| Discovery (HCL walk, backend/provider/deps parse, Terragrunt DAG) | ✅ `discovery/` |
+| Execution engine (flag model → `build_command`, streamed over WS, persisted) | ✅ `execution/`, `store/` |
+| Cloud auth probes (AWS / GCP-with-ADC / Azure) | ✅ `clouds/` |
+| State & lock read (`terraform state list`, acquire/release) | ✅ `state/` |
+| Drift (per-stack snapshots; demo data, live scan scaffolded) | ◑ `drift` endpoint |
+| Cloud Shell PTY (pywinpty / ptyprocess, subprocess fallback) | ✅ `shell/` |
+| AI assistant (Claude `claude-haiku-4-5` proxy + offline fallback) | ✅ `ai/` |
+| Frontend bundle (all views, drawer, flag modal, toast) | ✅ `web/index.html` |
+| VCS webhooks, server/agent mode, RBAC, policy gates | ☐ scaffolded (§10–11) |
+
+The command the UI previews is exactly the command the executor runs —
+`buildCmdStr` (frontend) and `build_command` (backend) are kept identical and
+unit-tested against the spec example
+(`terragrunt run-all plan -var-file=env/prod.tfvars --terragrunt-non-interactive`).
+
+## Architecture
+
+```
+Browser (web/index.html)
+  REST  /api/*            inventory, runs, drift, locks, graph, clouds, ai
+  WS    /ws/run/{id}      live plan/apply output
+  WS    /ws/term/{sess}   PTY terminal
+        │
+FastAPI app (server/app.py)
+  discovery · execution · clouds · state · drift · ai · store
+        │ subprocess (user's shell)
+        ▼
+terraform / terragrunt / aws / gcloud / az  on the local machine
+```
+
+## Develop
+
+```bash
+pip install -e ".[dev,pty]"
+pytest                       # command builder, discovery, API smoke tests
+terraui start --demo         # run the UI against the demo dataset
+```
+
+The AI assistant proxies to Claude when `ANTHROPIC_API_KEY` is set (model
+`claude-haiku-4-5`); otherwise it returns grounded canned answers. The key never
+reaches the browser.
+
+## Security
+
+Local mode binds to `127.0.0.1`. No secrets are stored — TerraUi shells out using
+the cloud SDK credential chains already on your machine. Commands are built from a
+structured flag model and passed as argv (never shell-interpolated); the action is
+checked against an allow-list. Secrets are redacted from streamed logs before they
+are persisted. See `BACKEND_SPEC.md` §14 for the full model.