Metadata-Version: 2.4
Name: tofu-assist
Version: 0.2.7
Summary: Natural language → validated, secured, cost-estimated OpenTofu config
Author: tofu-assist
License-Expression: MIT
Project-URL: Homepage, https://github.com/tofu-assist/tofu-assist
Project-URL: Repository, https://github.com/tofu-assist/tofu-assist.git
Project-URL: Issues, https://github.com/tofu-assist/tofu-assist/issues
Keywords: opentofu,terraform,infrastructure-as-code,iac,devops,nlp,hcl,cloud,aws,gcp,azure
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: System :: Systems Administration
Classifier: Topic :: Software Development :: Code Generators
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: rich>=13.0
Dynamic: license-file

# tofu-assist

<p align="center">
  <img src="https://raw.githubusercontent.com/tofu-assist/tofu-assist/main/assets/tofuassist-logo.png" alt="tofu-assist" width="480">
</p>

<p align="center">
  <a href="https://github.com/tofu-assist/tofu-assist/actions"><img src="https://img.shields.io/badge/tests-56%20passed-brightgreen" alt="Tests"></a>
  <a href="https://pypi.org/project/tofu-assist/"><img src="https://img.shields.io/badge/python-3.10%2B-blue" alt="Python"></a>
  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green" alt="License"></a>

</p>

**Writing Terraform is slow. Reading `terraform plan` output is unreadable. `tofu-assist` fixes both.**

Describe your infrastructure in plain English. Get validated, security-scanned, cost-estimated OpenTofu config — with a single approve step before anything touches your cloud.

![tofu-assist demo](https://raw.githubusercontent.com/tofu-assist/tofu-assist/main/demo.gif)

```
$ tofu-assist "I need a k8s cluster with postgres in eu-west-1"

Provider: aws (eu-west-1)
Generating configuration...

   ✓ main.tf (47 lines)
   ✓ variables.tf (11 lines)
   ✓ outputs.tf (8 lines)

Security scan: ✓ no issues found

Running tofu plan...

SUMMARY
  9 resources: 9 will be created.
  Estimated cost: $187/month

ATTENTION REQUIRED
  (none)

WHAT WILL BE BUILT
  + main (VPC)
  + 2x public (subnet)
  + 2x private (subnet)
  + main (EKS cluster)
  + main (EKS node group)
  + main (RDS instance)
  ...

Apply this? [y/N]
```

## Install

### Prerequisites

- **OpenTofu** ([install guide](https://opentofu.org/docs/intro/install/)) — the open-source Terraform fork
- **Python 3.10+**
- An API key for any OpenAI-compatible LLM (DeepSeek, OpenAI, Anthropic, OpenCode, etc.)

### Quickstart

```bash
pip install tofu-assist
export TOFU_ASSIST_API_KEY=your_api_key
tofu-assist "I need a load balancer with two EC2 instances"
```

### Optional dependencies

| Tool | Purpose | Install |
|------|---------|---------|
| [Infracost](https://www.infracost.io/docs/) | Cost estimation before apply | `curl -fsSL https://raw.githubusercontent.com/infracost/infracost/master/scripts/install.sh \| sh` |
| [Checkov](https://www.checkov.io/) | Static security scanning | `pip install checkov` |

The pipeline degrades gracefully — missing tools are skipped with a note, never an error.

## What it does

**Three layers. One pipeline.**

| Layer | What you get |
|-------|-------------|
| **Generate** | Plain English → production-quality HCL. Security defaults baked in: encryption at rest, blocked public S3, no wildcard IAM, no 0.0.0.0/0 on sensitive ports. One retry if validation fails. |
| **Verify** | Static security scan (Checkov) catches bad defaults before `plan`. Plan explainer turns 500-line JSON into a 3-section summary. Cost estimate (Infracost) tells you the monthly bill before you approve. |
| **Approve** | Hard-stop on production resource destruction. Tag-only changes are silent. `y/N` gate with everything visible. |

## Subcommands

### `tofu-assist explain` — understand any codebase instantly

Point at any directory with `.tf` files and get a plain-English summary.

```bash
$ tofu-assist explain ./infra

Analyzing /home/user/infra...

──────────────────────────────────────────────────────────
CODEBASE EXPLANATION
──────────────────────────────────────────────────────────

OVERVIEW
A production EKS cluster with RDS Postgres in a custom VPC
across 3 AZs. Public-facing via ALB with WAF.

RESOURCES (12)
  • main_vpc (aws_vpc)
    VPC with 10.0.0.0/16 CIDR for all resources
  • public_subnet_a (aws_subnet)
    Public subnet in us-east-1a for load balancer
  • ...

ARCHITECTURE
Internet → WAF → ALB → EKS (private subnets) → RDS (private subnets)

SECURITY NOTES
  ⚠ RDS is publicly accessible — consider restricting
  ⚠ Security group allows 0.0.0.0/0 on port 5432

COST IMPLICATIONS
  💰 EKS cluster: ~$73/month base
  💰 RDS db.r5.large (multi-AZ): ~$400/month

SUGGESTIONS
  → Add encryption at rest for RDS
  → Add lifecycle policies for S3 buckets
  → Tag all resources with Environment and Team
```

Options:
- `--detailed` — deeper security and cost analysis
- `--json` — machine-readable JSON output

### `tofu-assist edit` — modify existing config via natural language

Don't rewrite configs. Tell them what to change.

```bash
$ tofu-assist edit "add a read replica to the RDS instance"

Editing /home/user/infra...
Instruction: add a read replica to the RDS instance

Changes:
--- a/main.tf
+++ b/main.tf
@@ -45,6 +45,14 @@
   skip_final_snapshot = true
 }

+resource "aws_db_instance" "read_replica" {
+  replicate_source_db = aws_db_instance.main.identifier
+  instance_class      = "db.r5.large"
+}
+

Apply these changes? [y/N] y
✓ Modified 1 file(s): main.tf
  Backup saved to: ~/.tofu-assist/backups/

Next steps:
  cd /home/user/infra && tofu plan    # review the plan
  tofu apply                 # apply changes
```

Options:
- `--dir` — specify target directory
- `--dry-run` — preview changes without applying
- `--yes` / `-y` — skip approval prompt

## How it works

```
You: "I need a k8s cluster with postgres"
         │
         ▼
   ┌─────────────────┐
   │  LLM generation  │  System prompt enforces security defaults.
   │  (DeepSeek/any)  │  JSON envelope, no markdown parsing.
   └────────┬────────┘
            │  main.tf, variables.tf, outputs.tf
            ▼
   ┌─────────────────┐
   │  Checkov scan    │  Static analysis. CRITICAL findings surfaced.
   │  (optional)      │  Encryption, public access, wildcard IAM.
   └────────┬────────┘
            │
            ▼
   ┌─────────────────┐
   │  tofu plan       │  OpenTofu validates and produces plan JSON.
   └────────┬────────┘
            │
            ▼
   ┌─────────────────┐
   │  explain layer   │  SUMMARY + ATTENTION REQUIRED + WHAT WILL BE BUILT.
   │  + Infracost     │  Estimated cost injected inline.
   └────────┬────────┘
            │
            ▼
   ┌─────────────────┐
   │  Approve? [y/N]  │  Hard-stop on production resource destruction.
   └─────────────────┘
```

### Edit flow

```
You: "add a read replica to the RDS"
         │
         ▼
   ┌─────────────────┐
   │  Read existing    │  All .tf files from target directory.
   │  config files     │  Hidden files and plan.json skipped.
   └────────┬────────┘
            │
            ▼
   ┌─────────────────┐
   │  LLM edit         │  System prompt preserves all unchanged
   │  (DeepSeek/any)   │  resources. Only modifies what the
   └────────┬────────┘  instruction targets.
            │
            ▼
   ┌─────────────────┐
   │  Show diff        │  Unified diff of changes across all files.
   │  + tofu validate  │  Validation with auto-retry on failure.
   └────────┬────────┘
            │
            ▼
   ┌─────────────────┐
   │  Approve? [y/N]   │  Backs up originals to ~/.tofu-assist/backups/.
   │                   │  Overwrites on approval. Dry-run available.
   └─────────────────┘
```

## Safety features

- **Security defaults in the system prompt** — encryption at rest, blocked public S3, no wildcard IAM, restricted security groups. The LLM generates secure config by default.
- **Checkov static scan** — catches bad defaults before `plan` runs. CRITICAL findings are always surfaced. Noise is swallowed.
- **Production risk detection** — destroying `aws_db_instance.production` is a hard stop. Destroying `aws_subnet.main` is a warning. The classification weighs resource type AND naming patterns.
- **Alarming plan detection** — 15+ deletions or high destroy ratio refuses auto-summary. Single production database destroy triggers hard stop.
- **Tag-only filtering** — tag changes are silent. The ATTENTION REQUIRED section stays trustworthy.
- **Never blocks on tool failures** — Infracost not installed? Shows "cost estimate unavailable." Checkov not installed? Skips scan. The pipeline degrades gracefully.

## Files

```
~/.tofu-assist/
├── pending/                    ← Generation lands here
│   └── 2024-01-15-143022/
│       ├── main.tf
│       ├── variables.tf
│       ├── outputs.tf
│       └── plan.json
└── applied/                    ← Successful applies archived here
    └── 2024-01-15-143045/
        └── ...
```

## Configuration

| Variable | Default | Purpose |
|----------|---------|---------|
| `TOFU_ASSIST_API_KEY` | `$DEEPSEEK_API_KEY` | LLM API key (required) |
| `TOFU_ASSIST_API_BASE` | `https://api.deepseek.com/v1` | OpenAI-compatible API endpoint |
| `TOFU_ASSIST_MODEL` | `deepseek-chat` | Model name |

### Provider examples

```bash
# DeepSeek (default)
export TOFU_ASSIST_API_KEY=sk-...

# OpenAI
export TOFU_ASSIST_API_KEY=sk-...
export TOFU_ASSIST_API_BASE=https://api.openai.com/v1
export TOFU_ASSIST_MODEL=gpt-4o

# Anthropic (via compatible proxy)
export TOFU_ASSIST_API_KEY=sk-ant-...
export TOFU_ASSIST_API_BASE=https://api.anthropic.com/v1
export TOFU_ASSIST_MODEL=claude-sonnet-4-20250514

# OpenCode Go
export TOFU_ASSIST_API_KEY=oc-...
export TOFU_ASSIST_API_BASE=https://api.opencode.ai/zen/go/v1
export TOFU_ASSIST_MODEL=deepseek-v4-flash
```

### File structure

```
~/.tofu-assist/
├── pending/                    ← Generated configs land here before approval
│   ├── 2024-01-15-143022/      ← Fresh generation
│   └── edit-2024-01-15-150000/ ← Edit preview
│       ├── main.tf
│       ├── variables.tf
│       ├── outputs.tf
│       └── plan.json
├── applied/                    ← Successfully applied configs archived here
│   └── 2024-01-15-143045/
└── backups/                    ← Originals backed up before edit overwrites
    └── 2024-01-15-150000/
```

## Why?

Coding agents can generate Terraform. But they can't validate it, scan it for security issues, estimate what it'll cost, or stop you from destroying production. tofu-assist does all of that, plus lets you edit existing configs and explain any codebase — not just generate from scratch.

> *"Try generating a production EKS cluster with RDS in Claude Code. Now check: is the DB encrypted? Are the security groups locked down? Do you know what it'll cost? What happens if you run apply? Exactly."*

## Why OpenTofu

OpenTofu is the community fork of Terraform (Apache 2.0), created after HashiCorp's license change to BUSL. `tofu-assist` bets on OpenTofu — the ecosystem that's growing, not the one that changed the rules.

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, testing, and PR guidelines.

```bash
git clone https://github.com/tofu-assist/tofu-assist.git
cd tofu-assist
pip install -e ".[dev]"
python -m pytest -v
```

## License

MIT
