Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 24 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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
Expand Down
148 changes: 148 additions & 0 deletions ROADMAP.md
Original file line number Diff line number Diff line change
@@ -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
61 changes: 61 additions & 0 deletions tests/test_stackmason.py
Original file line number Diff line number Diff line change
Expand Up @@ -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"
)
Loading