docs(terraform): document the verbs the way the recipes actually parse them #878

Merged

coilysiren merged 1 commit from fix/terraform-docs-action-arg into main

2026-08-19 20:46:18 +00:00

coilyco-ops commented

2026-08-19 20:44:27 +00:00

Member

Closes #874.

Every terraform stack README documented just terraform-<stack> action=plan. The recipes take the action positionally, so the documented form never worked.

Why it never worked

_lib.terraform_run reads sys.argv[1] verbatim and splices it into the command, comparing against the literal string "init" for its special case. So action=init did not even reach the init branch, and every form produced terraform -chdir=... action=<verb>, which terraform rejects as an unknown subcommand.

Verified, not assumed

Ran each form against a mock terraform on PATH that echoes its arguments:

just terraform-aws-iam plan         ->  terraform -chdir=terraform/aws-iam plan
just terraform-aws-iam action=plan  ->  terraform -chdir=terraform/aws-iam action=plan
just terraform-aws-iam init         ->  terraform -chdir=terraform/aws-iam init

I also confirmed all five verbs route through terraform_run before rewriting anything — admin-kms and tailscale have no local argv handling of their own, so it would have been easy to assume they differed. They do not.

Scope

22 occurrences across 5 files. Prose references were included, not just the fenced blocks: aws-inventory/README.md and aws-public-assets/README.md both described "action=output" inline.

The aws-public-assets README was new in #873 and inherited this by copying the sibling convention, which is the failure the convention exists to prevent. That one is mine.

Not addressed here

Nothing validates a documented just invocation against the recipe that serves it, which is how this drifted across four stacks and then propagated into a fifth. #874 notes it; a checker that merely asserts the verb exists would not catch this class, since the verb was real and the argument shape was wrong. Left as a separate concern rather than bundled in.

pre-commit run --all-files green.

Closes #874. Every terraform stack README documented `just terraform-<stack> action=plan`. The recipes take the action **positionally**, so the documented form never worked. ## Why it never worked `_lib.terraform_run` reads `sys.argv[1]` verbatim and splices it into the command, comparing against the literal string `"init"` for its special case. So `action=init` did not even reach the init branch, and every form produced `terraform -chdir=... action=<verb>`, which terraform rejects as an unknown subcommand. ## Verified, not assumed Ran each form against a mock `terraform` on `PATH` that echoes its arguments: ``` just terraform-aws-iam plan -> terraform -chdir=terraform/aws-iam plan just terraform-aws-iam action=plan -> terraform -chdir=terraform/aws-iam action=plan just terraform-aws-iam init -> terraform -chdir=terraform/aws-iam init ``` I also confirmed all five verbs route through `terraform_run` before rewriting anything — `admin-kms` and `tailscale` have no local argv handling of their own, so it would have been easy to assume they differed. They do not. ## Scope 22 occurrences across 5 files. Prose references were included, not just the fenced blocks: `aws-inventory/README.md` and `aws-public-assets/README.md` both described "`action=output`" inline. The `aws-public-assets` README was new in #873 and inherited this by copying the sibling convention, which is the failure the convention exists to prevent. That one is mine. ## Not addressed here Nothing validates a documented `just` invocation against the recipe that serves it, which is how this drifted across four stacks and then propagated into a fifth. #874 notes it; a checker that merely asserts the verb exists would not catch this class, since the verb was real and the argument shape was wrong. Left as a separate concern rather than bundled in. `pre-commit run --all-files` green.

coilyco-ops added 1 commit

2026-08-19 20:44:28 +00:00

docs(terraform): document the verbs the way the recipes actually parse them

TruffleHog / Scan for secrets (pull_request) Successful in 5s

Details

CI / lint (pull_request) Successful in 40s

Details

383ff2ea8a

Every terraform stack README documented `just terraform-<stack> action=plan`.
The recipes take the action positionally, so the documented form never worked.

_lib.terraform_run reads sys.argv[1] verbatim and splices it into the command,
comparing against the literal string "init" for its special case. So
`action=init` did not even reach the init branch, and every form produced
`terraform -chdir=terraform/<stack> action=<verb>`, which terraform rejects as
an unknown subcommand.

Verified against a mock terraform on PATH rather than by reading:

  just terraform-aws-iam plan         -> terraform -chdir=... plan
  just terraform-aws-iam action=plan  -> terraform -chdir=... action=plan
  just terraform-aws-iam init         -> terraform -chdir=... init

All five verbs route through terraform_run, admin-kms and tailscale included,
so the same correction applies to each. 22 occurrences across 5 files, prose
references to `action=output` included rather than only the fenced blocks.

The aws-public-assets README was new in #873 and inherited this by copying the
sibling convention, which is the failure the convention exists to prevent.

Closes #874

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Co-authored-by: Kai Siren <coilysiren@gmail.com>
Co-authored-by: Claude <noreply@anthropic.com>

coilyco-ops requested review from coilysiren

2026-08-19 20:44:28 +00:00