diff --git a/README.md b/README.md index 1f4a499..9e531d2 100644 --- a/README.md +++ b/README.md @@ -52,6 +52,28 @@ modules, which is verified in this repo's own tests. Pass `--region` to put both the resources and the state bucket somewhere other than `us-east-1`. +## What it is trying to be + +**The first ninety minutes of a new infrastructure repository, without the +mistakes that take six months to surface.** + +Not a platform. Not a control plane. A generator that writes a first draft you +own outright, in plain Terraform, with no runtime dependency on this tool. You +should be able to delete `stackmason` afterwards and lose nothing. + +- **The defaults are the product**, and they are not negotiable silently. +- **There will never be a flag that turns a refusal into a warning.** It is the + most common request a scaffolding tool gets and the answer is permanently no: + an escape hatch on a security default is the same as not having the default, + because the hatch is what ends up in the example someone copies. +- **It never emits a credential**, in any form, for any reason. +- **Every choice is explicable six months later**, via `DECISIONS.md`. + +Full detail, plus what is deliberately **not** planned, in the +[roadmap](ROADMAP.md). Work in flight is tracked in the +[0.2](https://github.com/ehtishammubarik/stackmason/milestone/1) and +[0.3](https://github.com/ehtishammubarik/stackmason/milestone/2) milestones. + ## Why not just copy a blog post Because the defaults are the product. @@ -193,7 +215,8 @@ MIT. --- If `stackmason` saved you the first ninety minutes of an infrastructure repo, a -star helps the next person find it. Contributions welcome: +star helps the next person find it. Contributions welcome, and the +[roadmap](ROADMAP.md) says which issues are load-bearing: [`good first issue`](https://github.com/ehtishammubarik/stackmason/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) is pre-scoped, and [CONTRIBUTING.md](CONTRIBUTING.md) says how to claim one so two people do not build it twice. Read the `terraform validate` section first if diff --git a/ROADMAP.md b/ROADMAP.md new file mode 100644 index 0000000..f8159fa --- /dev/null +++ b/ROADMAP.md @@ -0,0 +1,148 @@ +# Roadmap + +Honest about status: `stackmason` is alpha. **Three of the nine advertised +stacks are configured.** The other six emit a module reference and a name, and +say so loudly, but they do not apply. Treat version numbers accordingly. + +Each section maps to a GitHub milestone, so this file and the issue tracker +cannot drift apart without one of them being visibly wrong. + +- [**0.2 — every advertised stack actually applies**](https://github.com/ehtishammubarik/stackmason/milestone/1) +- [**0.3 — beyond one region, one cloud, one run**](https://github.com/ehtishammubarik/stackmason/milestone/2) + +## Vision + +**The first ninety minutes of a new infrastructure repository, without the +mistakes that take six months to surface.** + +Not a platform. Not a control plane. A generator that writes a first draft you +own outright and can delete this tool afterwards. + +Four commitments follow, and the first is the one everything else serves. + +**The defaults are the product, and they are not negotiable silently.** A +scaffolding tool multiplies whatever it emits. One insecure default becomes a +hundred insecure deployments, run by people who reasonably assumed the generator +knew better. So `stackmason` **refuses** to emit a data port open to +`0.0.0.0/0`, a publicly accessible database, a bastion with no source +restriction, or `skip_final_snapshot` in production. + +**There will be no flag that turns a refusal into a warning.** This is the most +common request a scaffolding tool gets and the answer is permanently no. An +escape hatch on a security default is the same as not having the default, +because the hatch is what ends up in the example someone copies. If a refusal is +wrong, the argument to make is that it is wrong, on the issue, and then it stops +being a refusal for everyone. + +**It never emits a credential.** Not a placeholder, not a generated one, not +base64. Secrets are `sensitive` variables with no default, because a default is +what gets committed. + +**Every choice is explicable six months later.** Sizing questions accept +`suggest` and return a recommendation with its reasoning attached, written to +`DECISIONS.md`. The alternative is a user picking at random and blaming the +tool. + +**Where it stops.** This writes the first draft. Reading the plan is still your +job, and the generated README says so. It is not a compliance guarantee, not a +secret manager, and not a drift detector. If you want a full platform, use +Terragrunt, Atmos, or Cluster.dev. Growing into one would mean giving up the +property that makes this worth having: the output is a plain Terraform +repository with no runtime dependency on the thing that generated it. + +## Now (0.1.x) + +Shipped, tested, and on PyPI. + +| Capability | | +| :--- | :--- | +| Interview-driven generation | one directory and one state file per environment | +| **Three stacks fully configured** | `vpc`, `eks`, `rds` — these plan and apply | +| Six stacks emit a marked stub | `[stub]` in the CLI, `GEN001` warning, `INCOMPLETE` in the file ([#19]) | +| Guardrails that **refuse to generate** | open data port, public database, unrestricted bastion, `skip_final_snapshot` in prod | +| Cost warnings | NAT-per-AZ and control planes costed before you commit | +| `suggest` on every sizing question | reasoning written to `DECISIONS.md` | +| **Explicit provider region and `default_tags`** | region is never inherited from the ambient shell ([#15]) | +| Generated repo is `terraform fmt` clean | so it passes the CI it ships with on its first commit | +| A real `plan` verified | `eks` + `rds` plans 64 resources, 0 changes, 0 destroys | + +## Next (0.2) + +[Milestone](https://github.com/ehtishammubarik/stackmason/milestone/1). +**Six of nine advertised stacks do not apply. Until that closes, nothing else +matters more.** Each is self-contained and independently mergeable. + +| Item | Note | +| :--- | :--- | +| [Configure `s3`](https://github.com/ehtishammubarik/stackmason/issues/21) | Best first one: no VPC dependency, and the secure defaults are the interesting part | +| [Configure `alb`](https://github.com/ehtishammubarik/stackmason/issues/22) | A load balancer with no listeners applies, costs money, and routes nothing | +| [Configure `elasticache`](https://github.com/ehtishammubarik/stackmason/issues/23) | Watch the security group; this is where #11 went wrong for RDS | +| [Configure `msk`](https://github.com/ehtishammubarik/stackmason/issues/24) | Answers are already collected and then discarded | +| [Configure `redshift`](https://github.com/ehtishammubarik/stackmason/issues/25) | The most expensive stub to discover at apply time | +| [Configure `observability`](https://github.com/ehtishammubarik/stackmason/issues/26) | Largest. Helm releases, not a module reference; needs providers no generated repo configures yet | +| [Stub tracking issue](https://github.com/ehtishammubarik/stackmason/issues/10) | Closes when all six are done | +| [Generated environments have no outputs](https://github.com/ehtishammubarik/stackmason/issues/9) | Nothing downstream can consume the repo | +| [Plan summary before writing](https://github.com/ehtishammubarik/stackmason/issues/1) | Cost and blast radius visible before a file is created | +| [The interview never asks for a region](https://github.com/ehtishammubarik/stackmason/issues/14) | Needs a notion of questions belonging to no stack | + +## Later (0.3+) + +[Milestone](https://github.com/ehtishammubarik/stackmason/milestone/2). None of +it blocks 0.2. + +| Item | Note | +| :--- | :--- | +| [More than one region per environment](https://github.com/ehtishammubarik/stackmason/issues/2) | Needs the global-question mechanism from #14 first | +| [Regenerate without clobbering local edits](https://github.com/ehtishammubarik/stackmason/issues/4) | The output is your repository; a second run should respect that | +| [Azure and GCP stacks](https://github.com/ehtishammubarik/stackmason/issues/3) | The registry is structured for it. Nothing is implemented, and the README says so | + +## Not planned + +Saying no is part of a roadmap, and here it is most of the product. + +- **A flag that downgrades a refusal to a warning.** Permanent. See Vision. +- **Emitting any credential**, in any form, for any reason. +- **Vendoring `terraform-aws-modules`.** Copying them here would mean inheriting + their maintenance burden, freezing their security fixes, and taking on their + licensing. A pinned reference gets upstream fixes for free. +- **Drift detection, a control plane, or a state backend of our own.** That is + Terragrunt, Atmos, and Cluster.dev, and they are good at it. +- **A runtime dependency of generated repos on `stackmason`.** The output is + plain Terraform. You should be able to delete this tool and lose nothing. +- **Dependencies in the core.** CI enforces it. + +## How this file stays true + +`websieve`'s roadmap went stale: two shipped features sat under **Next** for +weeks, including the one labelled "the biggest correctness gap" +([websieve#34](https://github.com/ehtishammubarik/websieve/issues/34)). Someone +evaluating it read a solved problem as a live limitation. + +So: **a PR that closes a roadmap item moves its row into Now, in the same PR.** +Not afterwards. The row names the PR that delivered it, which is what makes the +claim checkable rather than assertable. Reviewers, this is fair game to block +on. + +The stack count in the opening paragraph is the number most likely to rot. It is +asserted against generated output by the test suite, so it cannot be wrong here +and right in the code without CI failing. + +## Influencing this list + +The order is a guess, and a real use case beats a guess. + +- **Open an issue** describing what you were building and where this got in the + way. Concrete beats abstract: which stacks, which environments, what broke. +- **Email** [contact@eprecisio.com](mailto:contact@eprecisio.com) if an issue is + not the right shape. +- **LinkedIn:** [Ehtisham Mubarik](https://www.linkedin.com/in/ehtisham-mubarik) + or [Eprecisio Technologies](https://www.linkedin.com/company/eprecisio/) + +Issues labelled [`good first issue`](https://github.com/ehtishammubarik/stackmason/labels/good%20first%20issue) +are scoped so a first contribution does not require reading the whole codebase. +[`CONTRIBUTING.md`](CONTRIBUTING.md) says how to claim one so two people do not +build it twice, and has the `terraform validate` section you should read before +touching what gets emitted. + +[#15]: https://github.com/ehtishammubarik/stackmason/pull/15 +[#19]: https://github.com/ehtishammubarik/stackmason/pull/19 diff --git a/tests/test_stackmason.py b/tests/test_stackmason.py index 2ac535b..6f5d312 100644 --- a/tests/test_stackmason.py +++ b/tests/test_stackmason.py @@ -805,3 +805,64 @@ def test_generated_output_still_formats_cleanly_with_a_stub_present(): through the same alignment path as real arguments.""" body = _module_body("s3") assert align_hcl(body) == body + + +# -------------------------------------------------------------------------- +# Documentation that cannot go stale (issue #27) +# +# websieve's roadmap sat for weeks promising two features that had already +# shipped, one of them labelled "the biggest correctness gap". The fix there +# was a convention; a convention is only as good as the next person's memory. +# The one number here most likely to rot is the configured-stack count, so it +# is asserted rather than trusted. +# -------------------------------------------------------------------------- + +REPO_ROOT = Path(__file__).resolve().parent.parent + + +def test_roadmap_stack_count_matches_the_registry(): + """`ROADMAP.md` opens with how many stacks actually apply. + + Configuring a stack without updating that sentence fails here, which is + the whole point: the number is load-bearing for anyone deciding whether + this tool is usable, and it is exactly the kind of figure nobody + remembers to update. + """ + configured = sum(1 for s in ALL_STACKS if s.configured) + total = len(ALL_STACKS) + # Collapse whitespace: the sentence is line-wrapped in the file, and a + # reflow is a formatting change, not a factual one. + roadmap = " ".join((REPO_ROOT / "ROADMAP.md").read_text().split()) + + spelled = { + 1: "One", + 2: "Two", + 3: "Three", + 4: "Four", + 5: "Five", + 6: "Six", + 7: "Seven", + 8: "Eight", + 9: "Nine", + } + claim = ( + f"{spelled[configured]} of the {spelled[total].lower()} advertised stacks are configured" + ) + assert claim in roadmap, ( + f"ROADMAP.md must say {claim!r}. The registry has {configured} configured " + f"of {total}; update the roadmap in the same PR that changes the code." + ) + + +def test_roadmap_links_every_open_stub_stack(): + """Every unconfigured stack needs a row someone can act on. + + A stub with no issue behind it is a dead end for a contributor who just + read that it does not work. + """ + roadmap = (REPO_ROOT / "ROADMAP.md").read_text() + for stack in ALL_STACKS: + if not stack.configured: + assert f"Configure `{stack.id}`" in roadmap, ( + f"{stack.id} is a stub with no roadmap row pointing at its issue" + )