Metadata-Version: 2.4
Name: terraui
Version: 0.1.6
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.
