docs(01): create phase 1 plan (2 plans, 2 waves)

2026-03-24 19:42:52 +01:00
parent e5af5162f9
commit 9229ffe19d
3 changed files with 519 additions and 3 deletions
--- a/.planning/phases/01-setup-git-foundation/01-01-PLAN.md
+++ b/.planning/phases/01-setup-git-foundation/01-01-PLAN.md
@@ -0,0 +1,257 @@
+---
+phase: 01-setup-git-foundation
+plan: 01
+type: execute
+wave: 1
+depends_on: []
+files_modified: [scripts/check-env.sh, scripts/validate-compose.sh, scripts/reset-env.sh]
+autonomous: true
+requirements: [SETUP-01, SETUP-02, SETUP-03, SETUP-04, INF-05]
+user_setup: []
+
+must_haves:
+  truths:
+    - "Studente puo eseguire script che verifica Docker Engine >= 24.0"
+    - "Studente puo eseguire script che verifica Docker Compose V2"
+    - "Studente puo eseguire script che verifica utility di rete (netcat, curl, iproute2)"
+    - "Studente puo eseguire script che riporta risorse di sistema (RAM, CPU)"
+    - "Studente puo validare file docker-compose.yml con script"
+    - "Studente puo eseguire cleanup completo ambiente (container, reti, volumi)"
+  artifacts:
+    - path: "scripts/check-env.sh"
+      provides: "Verifica ambiente Docker (versione, utility, risorse)"
+      min_lines: 80
+      contains: ["docker.*version", "compose", "netcat|nc", "curl", "free|meminfo"]
+    - path: "scripts/validate-compose.sh"
+      provides: "Validazione syntax docker-compose.yml"
+      min_lines: 30
+      contains: ["docker compose config", "YAML"]
+    - path: "scripts/reset-env.sh"
+      provides: "Cleanup Docker environment"
+      min_lines: 40
+      contains: ["docker ps", "docker network", "docker volume", "rm"]
+  key_links:
+    - from: "scripts/check-env.sh"
+      to: "Docker Engine"
+      via: "docker --version command"
+      pattern: "docker.*--version"
+    - from: "scripts/validate-compose.sh"
+      to: "docker-compose.yml"
+      via: "docker compose config parsing"
+      pattern: "docker compose config"
+    - from: "scripts/reset-env.sh"
+      to: "Docker daemon"
+      via: "docker CLI cleanup commands"
+      pattern: "docker.*rm"
+---
+
+<objective>
+Create validation scripts that verify Docker environment requirements and provide cleanup utilities for lab workflows.
+
+Purpose: Students need reliable tools to verify their Docker setup meets course requirements before starting labs, and a way to reset their environment between labs.
+Output: Three executable bash scripts (check-env.sh, validate-compose.sh, reset-env.sh) with clear error messages and appropriate exit codes.
+</objective>
+
+<execution_context>
+@/home/luca/.claude/get-shit-done/workflows/execute-plan.md
+@/home/luca/.claude/get-shit-done/templates/summary.md
+</execution_context>
+
+<context>
+@.planning/STATE.md
+@.planning/ROADMAP.md
+@.planning/REQUIREMENTS.md
+@.planning/phases/01-setup-git-foundation/01-RESEARCH.md
+@.planning/phases/01-setup-git-foundation/01-VALIDATION.md
+@CLAUDE.md
+</context>
+
+<tasks>
+
+<task type="auto">
+  <name>Task 1: Create environment check script (check-env.sh)</name>
+  <files>scripts/check-env.sh</files>
+  <action>
+Create bash script that verifies Docker environment meets course requirements. Script MUST include:
+
+1. **Standard header** (per CLAUDE.md):
+```bash
+#!/bin/bash
+# Laboratori Cloud - Environment Check Script
+# Part of: "Corso Soluzioni Cloud"
+#
+# Description: Verifies Docker Engine >= 24.0, Compose V2, network utilities, and system resources
+# Usage: ./scripts/check-env.sh
+```
+
+2. **Docker Engine version check:**
+   - Run `docker --version` to get version
+   - Parse major version number
+   - Exit with error if < 24.0
+   - Clear message: "ERROR: Docker Engine >= 24.0 required. Found: X.Y.Z"
+
+3. **Docker Compose V2 check:**
+   - Run `docker compose version` (V2 syntax, not `docker-compose`)
+   - Exit with error if command not found
+   - Clear message: "ERROR: Docker Compose V2 required. Use 'docker compose' not 'docker-compose'"
+
+4. **Network utilities check:**
+   - Check for `netcat` or `nc`
+   - Check for `curl`
+   - Check for `ip` (iproute2)
+   - Exit with error listing missing utilities
+
+5. **System resources check:**
+   - Report available RAM (using `free -h` or `/proc/meminfo`)
+   - Report CPU cores (using `nproc`)
+   - Warn if RAM < 8GB (recommended: 16GB per RESEARCH.md)
+
+6. **Exit codes:**
+   - 0: All checks pass
+   - 1: One or more checks fail
+   - Clear color-coded output (green for pass, red for fail)
+
+7. **Idempotency:** Script can be run multiple times without side effects
+
+DO NOT use interactive prompts. DO NOT require root. DO NOT modify system state.
+</action>
+  <verify>
+    <automated>./scripts/check-env.sh && echo "PASS" || echo "FAIL"</automated>
+  </verify>
+  <done>
+  Script exits 0 when Docker >= 24.0, Compose V2, and all utilities present.
+  Script exits 1 with clear error message when any requirement missing.
+  Script reports RAM and CPU resources accurately.
+  </done>
+</task>
+
+<task type="auto">
+  <name>Task 2: Create compose validation script (validate-compose.sh)</name>
+  <files>scripts/validate-compose.sh</files>
+  <action>
+Create bash script that validates docker-compose.yml files before deployment. Script MUST include:
+
+1. **Standard header:**
+```bash
+#!/bin/bash
+# Laboratori Cloud - Docker Compose Validation Script
+# Part of: "Corso Soluzioni Cloud"
+#
+# Description: Validates docker-compose.yml syntax using 'docker compose config'
+# Usage: ./scripts/validate-compose.sh [path-to-compose-file]
+```
+
+2. **Argument handling:**
+   - Accept path to compose file as first argument
+   - If no argument, show usage message and exit 1
+   - If file doesn't exist, exit 1 with clear error
+
+3. **Validation logic:**
+   - Run `docker compose -f [file] config` to parse YAML
+   - Exit 0 if config valid (YAML parses successfully)
+   - Exit 1 if config invalid (syntax errors, invalid directives)
+
+4. **Error reporting:**
+   - Show docker compose error output on failure
+   - Clear message: "ERROR: docker-compose.yml validation failed"
+
+5. **Edge cases:**
+   - Handle relative paths correctly
+   - Handle missing file gracefully
+   - Suppress docker compose verbose output unless error
+
+DO NOT deploy containers. DO NOT pull images. Validation only.
+</action>
+  <verify>
+    <automated>./scripts/validate-compose.sh /dev/null 2>&1 | grep -i "usage\|error" && echo "USAGE_SHOWN" || true</automated>
+  </verify>
+  <done>
+  Script shows usage when called without arguments.
+  Script exits 1 when given non-existent file.
+  Script exits 1 when given invalid YAML compose file.
+  Script exits 0 when given valid docker-compose.yml.
+  </done>
+</task>
+
+<task type="auto">
+  <name>Task 3: Create environment reset script (reset-env.sh)</name>
+  <files>scripts/reset-env.sh</files>
+  <action>
+Create bash script that cleans Docker environment between labs. Script MUST include:
+
+1. **Standard header:**
+```bash
+#!/bin/bash
+# Laboratori Cloud - Environment Reset Script
+# Part of: "Corso Soluzioni Cloud"
+#
+# Description: Stops all containers, removes all networks and volumes (with confirmation)
+# Usage: ./scripts/reset-env.sh [--dry-run]
+```
+
+2. **Safety features (per CLAUDE.md "Safety First"):**
+   - Default: Require user confirmation before destructive operations
+   - Support `--dry-run` flag to show what would be deleted without actually deleting
+   - Clear warning: "WARNING: This will stop ALL containers and remove ALL networks and volumes"
+
+3. **Cleanup operations in order:**
+   - Stop all running containers (`docker stop $(docker ps -q)`)
+   - Remove all containers (`docker rm $(docker ps -aq)`)
+   - Remove all user-created networks (`docker network ls -q` filter out bridge/host/none)
+   - Remove all volumes (with confirmation, separate from networks)
+   - Show count of objects removed
+
+4. **Exit codes:**
+   - 0: Cleanup completed successfully
+   - 1: User cancelled or error occurred
+
+5. **Idempotency:** Can be run safely on already-clean environment
+
+6. **Output:**
+   - Show progress for each operation
+   - Clear summary of what was removed
+   - No error if nothing to remove
+
+DO NOT remove Docker default networks (bridge, host, none). DO NOT remove Docker images.
+</action>
+  <verify>
+    <automated>./scripts/reset-env.sh --dry-run</automated>
+  </verify>
+  <done>
+  --dry-run flag shows what would be deleted without deleting.
+  Default mode requires user confirmation.
+  Script removes all containers, networks, and volumes when confirmed.
+  Script preserves default Docker networks (bridge, host, none).
+  Script exits 0 on successful cleanup.
+  </done>
+</task>
+
+</tasks>
+
+<verification>
+After all tasks complete:
+1. Run `./scripts/check-env.sh` — should report all requirements met
+2. Run `./scripts/validate-compose.sh` without arguments — should show usage
+3. Run `./scripts/reset-env.sh --dry-run` — should show what would be cleaned
+4. Verify all scripts are executable (`ls -l scripts/`)
+5. Verify scripts have standard headers per CLAUDE.md
+
+Cross-verification:
+- check-env.sh validates SETUP-01 (Docker >= 24.0), SETUP-02 (network utilities), SETUP-03 (resources), SETUP-04 (verification script)
+- validate-compose.sh validates INF-05 (compose validation before use)
+</verification>
+
+<success_criteria>
+1. All three scripts exist in scripts/ directory and are executable
+2. check-env.sh accurately detects Docker Engine >= 24.0, Compose V2, and network utilities
+3. validate-compose.sh catches YAML syntax errors in docker-compose.yml files
+4. reset-env.sh provides safe cleanup with --dry-run flag
+5. All scripts follow CLAUDE.md standards (headers, error messages, exit codes)
+</success_criteria>
+
+<output>
+After completion, create `.planning/phases/01-setup-git-foundation/01-01-SUMMARY.md` with:
+- Scripts created with line counts and key features
+- Test results from each script
+- Any deviations from RESEARCH.md specification
+</output>