From e915db8f5e66181444aff9eacb4d25afdc5d4036 Mon Sep 17 00:00:00 2001 From: ehtishammubarik <40181801+ehtishammubarik@users.noreply.github.com> Date: Tue, 18 Aug 2026 09:59:25 +0000 Subject: [PATCH] docs: add a roadmap and a vision, and make the stack count CI-enforced 13 open issues, two milestones, and nothing saying which mattered or where this is going. A contributor picked by title and hoped. The vision section matters more here than in most repos because this tool writes infrastructure other people apply to real accounts, and its value is entirely in what it refuses to emit. Writing down that there will never be a flag downgrading a refusal to a warning gives a reviewer something to point at when the next PR adds --allow-public-database with a reasonable justification attached. That is the most common request a scaffolding tool receives. Now/Next/Later are tables of real linked issues mapped to the two milestones. All 13 issue references and both PR references were verified against the tracker rather than written from memory. The roadmap claims its stack count is enforced, so it is: two tests assert ROADMAP.md against the registry. Configuring a stack without updating the sentence fails with a message naming the new number. Verified by flipping s3 to configured and watching it fail: AssertionError: ROADMAP.md must say 'Four of the nine advertised stacks are configured'. The registry has 4 configured of 9; update the roadmap in the same PR that changes the code. That is the difference from websieve's roadmap, which went stale within weeks under a convention alone (websieve#34). A convention is only as good as the next person's memory. Closes #27 Co-Authored-By: Claude Opus 5 --- README.md | 25 ++++++- ROADMAP.md | 148 +++++++++++++++++++++++++++++++++++++++ tests/test_stackmason.py | 61 ++++++++++++++++ 3 files changed, 233 insertions(+), 1 deletion(-) create mode 100644 ROADMAP.md 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" + )