feat(aws): safe spin foundation — deterministic tags, owner-scoped status, group-guarded down, live interlock; tests+CI; docs (Closes #2)

Why
- Prevent accidental cloud modification while enabling iterative learning.
- Ensure we only touch our own resources via strict tags and owner scoping.

What
- Tag model: Project=cloud-starter | ManagedBy=spin | Owner=<you> | SpinGroup=<id>
- Owner-scoped filters in status/down; pagination for describe_instances
- Safety interlock: live requires SPIN_LIVE=1 + --apply
- Down requires --group (override env exists but discouraged)
- Helpful NoCredentials/ClientError messages
- README: dry-run by default; env vars; live interlock; examples
- Tests: dry-run JSON shape; group guard; moto-backed live round-trip
- CI: pip install -e ".[test]" + pytest -q + CLI smoke

Notes
- “Session” tag renamed to SpinGroup for clarity; equivalent scoping boundary.

Author: thenarfer

.github/workflows/ci.yml

@@ -1,22 +1,26 @@
-name: ci
+name: CI
+
 on:
   pull_request:
   push:
     branches: [ main ]
 
 jobs:
-  check:
+  test:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-python@v5
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
         with:
           python-version: '3.11'
+
       - name: Install (editable) + test deps
         run: |
           python -m pip install -U pip
-          pip install -e .[test]
-      - name: CLI smoke
-        run: spin --help
+          pip install -e ".[test]"
+
       - name: Run tests
         run: pytest -q

.gitignore

@@ -39,3 +39,6 @@ dist/
 # JetBrains
 .idea/
 *.iml
+
+# Artifacts
+*.egg-info/

README.md

@@ -1,53 +1,48 @@
 # Cloud Starter
 
-A transparent learning project to practice Product Ownership and disciplined delivery.
-
+A transparent learning project to practice Product Ownership and disciplined delivery.  
 **Product Goal:** Enable developers to self-serve a few on-demand servers for tests within minutes.
 
 ---
 
 ## Sprint 2 — MVP
 
-**Sprint Goal:** Deliver an **installable `spin` CLI** (`pip install -e .`) that exposes  
-`up | status | down` (dry-run only) and define a deterministic tag model for upcoming AWS calls.
+**Sprint Goal:** Deliver an **installable `spin` CLI** (`pip install -e .`) that exposes `up | status | down`.  
+By default the CLI is **dry-run** and **does not contact AWS**. Live calls only happen if **both**:
+1) you pass `--apply`, **and**
+2) the environment has `SPIN_LIVE=1`.
+
+This gives us a safe “seatbelt” while we learn.
 
-**Scope (this sprint)**
-- Single provider: **AWS** (no live API calls yet)
-- Commands: `spin up --count X`, `spin status`, `spin down` (all **dry-run** output)
-- Deterministic tags for future resources:
+### Scope (this sprint)
+- Single provider: **AWS**
+- Commands: `spin up --count X`, `spin status`, `spin down`
+- Deterministic tag model for future resources:
   - `Project=cloud-starter`
   - `ManagedBy=spin`
-  - `Owner=<github-handle>`
+  - `Owner=<your-handle>` (required)
   - `SpinGroup=<id>`
 
-**Non-goals (not in this sprint)**
+### Non-goals (not in this sprint)
 - Multi-cloud (Azure/GCP), Terraform/IaC
 - SSH/provisioners, IAM hardening
 - Autoscaling, budgets/policies beyond basic teardown
 - Monitoring/alerts
-- Real instance lifecycle (that starts next)
+- Real instance lifecycle beyond the minimal demo
 
 ---
 
 ## Prerequisites
 
 - Python **>= 3.11**
-- (For later sprints) AWS credentials & region configured (`AWS_PROFILE` or envs / `~/.aws`)
-- Default region used by `spin`: **eu-north-1** (override with `--region` or `SPIN_REGION`)
-
----
-
-## Run tests
-```
-pytest -q
-```
+- **Owner is required:** set `SPIN_OWNER` to your handle/email
+- Default region: **eu-north-1** (override with `SPIN_REGION` or `--region`)
+- For live calls (later): configure AWS credentials (`AWS_PROFILE` or `~/.aws`)
 
 ---
 
 ## Quick start (dev)
 
-Install in a virtual environment using editable mode:
-
 ```bash
 python -m venv .venv
 # Windows: .venv\Scripts\activate
@@ -57,9 +52,10 @@ python -m pip install -U pip
 pip install -e .
 ````
 
-Verify the CLI and try the dry-run commands:
+Check the CLI and try dry-run:
 
 ```bash
+export SPIN_OWNER=@yourhandle
 spin --help
 spin up --count 2
 spin status
@@ -68,12 +64,42 @@ spin down
 
 **Notes**
 
-* All commands are **dry-run** in Sprint 2 (they print what would happen).
-* Environment overrides:
+* With no `--apply` or without `SPIN_LIVE=1`, output is JSON previews and **no AWS calls** are made.
+* `spin down` requires `--group` for destructive actions (override via `SPIN_ALLOW_GLOBAL_DOWN=1` only if you really mean it).
+
+---
+
+## Live operations (guarded; optional)
+
+Only when you’re ready and have credentials:
+
+```bash
+export SPIN_OWNER=@yourhandle
+export SPIN_LIVE=1
+spin up --count 1 --apply          # touches AWS
+spin status
+spin down --group <id> --apply
+```
+
+---
+
+## Environment variables
+
+* `SPIN_OWNER` (required): logical owner tag.
+* `SPIN_REGION` (optional): default region (falls back to `AWS_DEFAULT_REGION` then `eu-north-1`).
+* `SPIN_DRY_RUN` (default `1`): when `1`, `status` also avoids AWS.
+* `SPIN_LIVE` (default `0`): must be `1` **and** you must pass `--apply` to perform live actions.
+* `SPIN_ALLOW_GLOBAL_DOWN` (default `0`): allow `down` without `--group` (dangerous; owner-scoped still).
+
+---
+
+## Run tests
+
+```bash
+pytest -q
+```
 
-  * `SPIN_REGION` (default `eu-north-1`)
-  * `AWS_PROFILE` (optional; used in later sprints)
-  * `SPIN_GROUP` (default `dev`) — used in tags to group resources
+Tests cover dry-run behavior and a safe “live” flow under `moto`.
 
 ---
 
@@ -91,11 +117,11 @@ spin down
 
 ## Roadmap (high level)
 
-* **Sprint 2 (this sprint):** installable CLI, dry-run commands, tag model
-* **Next:** wire minimal AWS calls in `eu-north-1` using the tag schema; `status` lists instances; safe `down`
+* **Sprint 2 (this sprint):** installable CLI, dry-run commands, tag model, safety interlocks
+* **Next:** wire minimal AWS calls in `eu-north-1`; `status` lists instances; safe `down`
 
 ---
 
 ## License
 
-MIT
+MIT

pyproject.toml

@@ -4,16 +4,17 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "cloud-starter"
-description = "Learning project: minimal spin CLI with up|status|down (dry-run)."
+description = "Learning project: minimal spin CLI with up|status|down (dry-run by default; live only with interlock)."
 readme = "README.md"
 requires-python = ">=3.11"
 license = { text = "MIT" }
 authors = [{ name = "Marius Trovik" }]
 keywords = ["cli", "aws", "learning", "cloud"]
-# No runtime deps yet; boto3 will come in #3.
-dependencies = []
 
-# We'll keep version in code:
+# Boto is needed at import time because the CLI imports the aws module.
+dependencies = ["boto3>=1.34", "botocore>=1.34"]
+
+# Version comes from code
 dynamic = ["version"]
 
 [tool.setuptools]
@@ -29,4 +30,7 @@ where = ["src"]
 spin = "cloud_starter.cli:main"
 
 [project.optional-dependencies]
-test = ["pytest>=8"]
+test = [
+  "pytest>=8",
+  "moto[boto3]>=5"
+]

requirements.txt

@@ -0,0 +1,4 @@
+boto3
+botocore
+pytest
+moto[boto3]