terraform stack READMEs document 'action=plan', but the recipes take the action positionally #874

New issue

Closed

opened 2026-08-19 16:22:17 +00:00 by coilyco-ops · 0 comments

coilyco-ops commented

2026-08-19 16:22:17 +00:00

Member

Every terraform stack README documents the verbs as just terraform-<stack> action=plan. The recipes take the action as a positional argument, so the documented form does not work.

What actually happens

_lib.terraform_run reads sys.argv[1] verbatim and splices it into the command:

action = sys.argv[1] if len(sys.argv) > 1 else "plan"
base = f"terraform -chdir=terraform/{chdir}"
if action == "init":
    run(f"{base} init", env=env)
    return
flags = " -auto-approve" if auto_approve and action in ("apply", "destroy") else ""
run(f"{base} {action}{flags}", env=env)

So the two forms produce:

'action=init'  ->  terraform -chdir=terraform/aws-public-assets action=init
'init'         ->  terraform -chdir=terraform/aws-public-assets init
'action=plan'  ->  terraform -chdir=terraform/aws-public-assets action=plan
'plan'         ->  terraform -chdir=terraform/aws-public-assets plan

action=init does not even reach the init branch, since the comparison is against the literal string. Terraform then rejects action=init as an unknown subcommand.

The correct form is positional:

just terraform-aws-public-assets init
just terraform-aws-public-assets plan
just terraform-aws-public-assets apply
just terraform-aws-public-assets output

Where it appears

Five files, 19 lines:

terraform/aws-public-assets/README.md - lines 72-75, 83
terraform/aws-inventory/README.md - lines 56-59, 65, 74-76
terraform/aws-iam/README.md - lines 28-30
terraform/admin-kms/README.md - lines 19-21
docs/tailscale.md - line 33

The prose references need the same treatment, not just the fenced blocks: aws-inventory/README.md:65 and aws-public-assets/README.md:83 both describe "action=output" inline.

How it got here

Pre-existing across the four older stacks. terraform/aws-public-assets/README.md is new in #873 and inherited it by copying the sibling convention, which is the failure mode the convention was supposed to prevent. Worth fixing all five together rather than only the new one.

Worth considering alongside

Nothing validates a documented just invocation against the recipe that serves it, so this drifted silently across four stacks and then propagated into a fifth. A check that extracts just <verb> <args> from fenced blocks and asserts the verb exists would not have caught this one (the verb is real, the argument shape is wrong), but a per-script argument contract might. Filing as a note rather than a requirement.

Every terraform stack README documents the verbs as `just terraform-<stack> action=plan`. The recipes take the action as a **positional argument**, so the documented form does not work. ## What actually happens `_lib.terraform_run` reads `sys.argv[1]` verbatim and splices it into the command: ```python action = sys.argv[1] if len(sys.argv) > 1 else "plan" base = f"terraform -chdir=terraform/{chdir}" if action == "init": run(f"{base} init", env=env) return flags = " -auto-approve" if auto_approve and action in ("apply", "destroy") else "" run(f"{base} {action}{flags}", env=env) ``` So the two forms produce: ``` 'action=init' -> terraform -chdir=terraform/aws-public-assets action=init 'init' -> terraform -chdir=terraform/aws-public-assets init 'action=plan' -> terraform -chdir=terraform/aws-public-assets action=plan 'plan' -> terraform -chdir=terraform/aws-public-assets plan ``` `action=init` does not even reach the `init` branch, since the comparison is against the literal string. Terraform then rejects `action=init` as an unknown subcommand. The correct form is positional: ``` just terraform-aws-public-assets init just terraform-aws-public-assets plan just terraform-aws-public-assets apply just terraform-aws-public-assets output ``` ## Where it appears Five files, 19 lines: - `terraform/aws-public-assets/README.md` - lines 72-75, 83 - `terraform/aws-inventory/README.md` - lines 56-59, 65, 74-76 - `terraform/aws-iam/README.md` - lines 28-30 - `terraform/admin-kms/README.md` - lines 19-21 - `docs/tailscale.md` - line 33 The prose references need the same treatment, not just the fenced blocks: `aws-inventory/README.md:65` and `aws-public-assets/README.md:83` both describe "`action=output`" inline. ## How it got here Pre-existing across the four older stacks. `terraform/aws-public-assets/README.md` is new in #873 and inherited it by copying the sibling convention, which is the failure mode the convention was supposed to prevent. Worth fixing all five together rather than only the new one. ## Worth considering alongside Nothing validates a documented `just` invocation against the recipe that serves it, so this drifted silently across four stacks and then propagated into a fifth. A check that extracts `just <verb> <args>` from fenced blocks and asserts the verb exists would not have caught this one (the verb is real, the argument shape is wrong), but a per-script argument contract might. Filing as a note rather than a requirement.

coilyco-ops referenced this issue from a commit

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

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

coilyco-ops referenced this issue from a pull request that will close it,

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

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