126 lines
3.4 KiB
Markdown
126 lines
3.4 KiB
Markdown
# The Three Types of Commands
|
||
|
||
This framework deliberately separates *how* you interact with the system into three distinct command types. The split is not cosmetic; it encodes safety, intent, and operational assumptions directly into the tooling so that mistakes are harder to make under stress.
|
||
|
||
The guiding idea: **production should feel boring and safe; exploration should feel powerful and a little dangerous; the application itself should not care how it is being operated.**
|
||
|
||
---
|
||
|
||
## 1. Application Commands (`app`)
|
||
|
||
**What they are**
|
||
Commands defined *by the application itself*, for its own domain needs. They are not part of the framework, even though they are built on top of it.
|
||
|
||
The framework provides structure and affordances; the application supplies meaning.
|
||
|
||
**Core properties**
|
||
|
||
* Express domain behavior, not infrastructure concerns
|
||
* Safe by definition
|
||
* Deterministic and repeatable
|
||
* No environment‑dependent semantics
|
||
* Identical behavior in dev, staging, and production
|
||
|
||
**Examples**
|
||
|
||
* Handling HTTP requests
|
||
* Rendering templates
|
||
* Running background jobs / queues
|
||
* Sending emails triggered by application logic
|
||
|
||
**Non‑goals**
|
||
|
||
* No schema changes
|
||
* No data backfills
|
||
* No destructive behavior
|
||
* No operational or lifecycle management
|
||
|
||
**Rule of thumb**
|
||
If removing the framework would require rewriting *how* it runs but not *what* it does, the command belongs here.
|
||
|
||
---
|
||
|
||
## 2. Management Commands (`mgmt`)
|
||
|
||
**What they are**
|
||
Operational, *production‑safe* commands used to evolve and maintain a live system.
|
||
|
||
These commands assume real data exists and must not be casually destroyed.
|
||
|
||
**Core properties**
|
||
|
||
* Forward‑only
|
||
* Idempotent or safely repeatable
|
||
* Designed to run in production
|
||
* Explicit, auditable intent
|
||
|
||
**Examples**
|
||
|
||
* Applying migrations
|
||
* Running seeders that assert invariant data
|
||
* Reindexing or rebuilding derived data
|
||
* Rotating keys, recalculating counters
|
||
|
||
**Design constraints**
|
||
|
||
* No implicit rollbacks
|
||
* No hidden destructive actions
|
||
* Fail fast if assumptions are violated
|
||
|
||
**Rule of thumb**
|
||
If you would run it at 3am while tired and worried, it must live here.
|
||
|
||
---
|
||
|
||
## 3. Development Commands (`develop`)
|
||
|
||
**What they are**
|
||
Sharp, *unsafe by design* tools meant exclusively for local development and experimentation.
|
||
|
||
These commands optimize for speed, learning, and iteration — not safety.
|
||
|
||
**Core properties**
|
||
|
||
* Destructive operations allowed
|
||
* May reset or mutate large amounts of data
|
||
* Assume a clean or disposable environment
|
||
* Explicitly gated in production
|
||
|
||
**Examples**
|
||
|
||
* Dropping and recreating databases
|
||
* Rolling migrations backward
|
||
* Loading fixtures or scenarios
|
||
* Generating fake or randomized data
|
||
|
||
**Safety model**
|
||
|
||
* Hard to run in production
|
||
* Requires explicit opt‑in if ever enabled
|
||
* Clear, noisy warnings when invoked
|
||
|
||
**Rule of thumb**
|
||
If it would be irresponsible to run against real user data, it belongs here.
|
||
|
||
---
|
||
|
||
## Why This Split Matters
|
||
|
||
Many frameworks blur these concerns, leading to:
|
||
|
||
* Fearful production operations
|
||
* Overpowered dev tools leaking into prod
|
||
* Environment‑specific behavior and bugs
|
||
|
||
By naming and enforcing these three command types:
|
||
|
||
* Intent is visible at the CLI level
|
||
* Safety properties are architectural, not cultural
|
||
* Developers can move fast *without* normalizing risk
|
||
|
||
---
|
||
|
||
## One‑Sentence Summary
|
||
|
||
> **App commands run the system, mgmt commands evolve it safely, and develop commands let you break things on purpose — but only where it’s allowed.**
|