Metadata-Version: 2.4
Name: tf2okf
Version: 0.4.0
Summary: Generate Open Knowledge Format (OKF) v0.2 bundles from Terraform-family repositories
Author: tf2okf contributors
License-Expression: Apache-2.0
Keywords: terraform,terragrunt,tfscaffold,okf,open-knowledge-format,copilot,iac
Classifier: Development Status :: 4 - Beta
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 :: Documentation
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: PyYAML<7,>=6.0.2
Requires-Dist: typer<1,>=0.12.5
Provides-Extra: hcl
Requires-Dist: python-hcl2<8,>=7.0; extra == "hcl"
Provides-Extra: dev
Requires-Dist: pytest<9,>=8.3; extra == "dev"
Requires-Dist: pytest-cov<7,>=5; extra == "dev"
Requires-Dist: ruff<1,>=0.9; extra == "dev"
Requires-Dist: mypy<2,>=1.13; extra == "dev"
Requires-Dist: bandit<2,>=1.8; extra == "dev"
Requires-Dist: pip-audit<3,>=2.7; extra == "dev"
Requires-Dist: build<2,>=1.2; extra == "dev"
Requires-Dist: twine<7,>=6; extra == "dev"
Requires-Dist: types-PyYAML<7,>=6.0; extra == "dev"
Dynamic: license-file

# tf2okf

`tf2okf` generates deterministic Open Knowledge Format v0.2 Markdown from Terraform-family repositories.

## Install and run

Requires Python 3.10 or newer.

### Install from this repository (local source)

```bash
python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install -r requirements.txt
python3 -m pip install .
tf2okf --help
```

### Install for use in other repositories

Install once, then run `tf2okf` from any Terraform/Terragrunt project.

If published on PyPI:

```bash
python3 -m pip install tf2okf
```

If not published on PyPI, install directly from Git:

```bash
python3 -m pip install "git+https://github.com/<owner>/tf2okf.git"
```

For isolated global CLI usage across projects (`pipx`):

```bash
pipx install "git+https://github.com/<owner>/tf2okf.git"
```

Common commands:

```bash
tf2okf frameworks
tf2okf discover .
tf2okf init .
tf2okf generate .
tf2okf check .
tf2okf diff .
```

## Framework selection

```bash
tf2okf frameworks
tf2okf discover .
tf2okf init . --framework auto
tf2okf init . --framework tfscaffold
tf2okf init . --framework terragrunt
tf2okf init . --framework plain-terraform
```

Configuration:

```yaml
version: '2'
framework:
  type: auto
```

`auto` detects known framework signatures. Explicit selection always wins.

### tfscaffold adapter

Discovers independent `components/`, reusable `modules/`, and `etc/*.tfvars` environment metadata.

### Terragrunt adapter

Discovers each `terragrunt.hcl` unit, static `terraform.source`, `include`, `dependency.config_path`, shared HCL and `terragrunt.stack.hcl` files. `.terragrunt-cache` and generated `.terragrunt-stack` content are ignored.

### Plain Terraform adapter

Parses Terraform source directly from the configured root.

## Commands

- `init` — create configuration, detect/select framework, create initial OKF and Copilot instructions
- `discover` — show detected framework and reasons without changing files
- `generate` — regenerate machine-owned OKF
- `check` — fail when committed generated OKF has drifted
- `diff` — show generated knowledge diff
- `frameworks` — list supported adapters

No LLM is needed for generation.

## Security defaults

`tf2okf` is intentionally source-only: it does not read Terraform state, plans, cloud credentials, or execute Terraform. Repository-relative configuration paths are containment-checked; symlinked Terraform files are ignored; source files over 2 MiB are skipped; likely secret-bearing attributes are redacted; and optional `terraform-docs` execution has a timeout and captured-output limit. See `SECURITY.md` for the threat model.

## Open-source release checklist

Before publishing: enable GitHub private vulnerability reporting, branch protection/rulesets, required CI/CodeQL/dependency review checks, Dependabot security updates, secret scanning/push protection where available, and PyPI trusted publishing for the `pypi` environment. Run `python -m build && python -m twine check dist/*` locally or in CI.
