TODO Checklist for env_sync.rb Project
🔧 Setup • Create new Git repository and branch env-sync • Ensure Ruby 2.5+ is installed (ruby -v) • Add .gitignore (e.g., /log, /tmp, .env*, .bak*, *.swp) • Choose test framework (Minitest or RSpec) and add to project • Install RuboCop (optional) for linting
⸻
🚀 Milestone 1 — Project Skeleton & CLI Stub • M1-S1 Create env_sync.rb with shebang; make executable; print stub message • Commit & run script (./env_sync.rb) • M1-S2 Add OptionParser with --auto-accept, --quiet, --help; print parsed options • Test flags manually • Commit • M1-S3 Accept optional directory arg; validate exists; error on invalid • Test with valid & invalid paths • Commit
⸻
🗂️ Milestone 2 — EnvParser Implementation • M2-S1 Add EnvParser.parse stub (return empty array) • M2-S2 Implement basic parsing (skip comments/blank/export, capture key/value) • Write unit tests for basic parsing cases • M2-S3 Detect & store quoting style; strip quotes from value • M2-S4 Introduce EnvParser::ParseError; edge-case tests (malformed lines) • All tests green; commit
⸻
🔍 Milestone 3 — DiffEngine • M3-S1 Create DiffEngine.missing_keys • M3-S2 Pretty console diff of missing keys (no prompts yet) • Add unit tests for ordering & detection • Commit
⸻
💬 Milestone 4 — PromptUI & Interactivity • M4-S1 Implement PromptUI.confirm? loop (Y/n) • Integrate with Runner; collect accepted keys • M4-S2 Wire --auto-accept to bypass prompts • Manual interactive test and auto-accept test • Commit
⸻
🛡️ Milestone 5 — Backup & FileWriter • M5-S1 Add BackupManager.backup (timestamped copy) • M5-S2 Add FileWriter.append_missing preserving quoting & order • Integration test with Tempfile (backup + append) • M5-S3 Wire full end-to-end flow; remove debug prints • Commit
⸻
🎛️ Milestone 6 — UX Polish & Extra Flags • M6-S1 Implement --quiet (suppress summary) • M6-S2 Add --version and improve --help banner • M6-S3 Refine summary output & pluralization • Update CLI usage examples in README • Commit
⸻
🛠️ Milestone 7 — Robustness & Documentation • M7-S1 Enhanced ParseError with filename/lineno; rescue in Runner • M7-S2 Define and use custom exit codes (OK, PARSE_ERROR, IO_ERROR, RUNTIME_ERROR) • M7-S3 Add README Usage section (≤20 lines) • Commit
⸻
🔗 Milestone 8 — Git Hook Integration • M8-S1 Create scripts/pre-commit.sh invoking script with --auto-accept --quiet • Make script executable; test hook in sample repo • Update README with install instructions • Commit
⸻
📦 Release & Versioning • Bump version to v1.0.0 in script and README • Create CHANGELOG.md entry for initial release • Tag release (git tag v1.0.0 && git push --tags)
⸻
✅ Testing Matrix • Unit tests: EnvParser (comments, quotes, malformed) • Unit tests: DiffEngine (order, detection) • Integration: CLI default flow (prompts) • Integration: --auto-accept flow • Integration: --quiet flag (no output) • Error: missing .env.example • Error: unreadable files (permission denied) • Error: malformed lines raise ParseError (exit 10) • Backup file created with correct timestamp pattern
⸻
🧹 Code Quality & Maintenance • Run RuboCop (or ruby -c) for syntax & style • Ensure NO external gem dependencies (stdlib only) • Review code for readability and clear module boundaries • Add inline YARD docs where helpful
⸻
📝 Documentation • Expand README with installation, examples, flags table • Add LICENSE (MIT?) • Add CONTRIBUTING.md guidelines
⸻
🔄 Final Manual Verification • Run script with sample .env.example / .env pair; verify added keys • Verify backup file contents match original .env • Test script on large .env.example (>100 keys) • Execute Git pre-commit hook in real commit; ensure it blocks on missing keys when not auto-accepted • Merge branch into main / master
⸻
Happy coding!