dotfile-theme-manager/TODO.md

Dotfile Theme Manager TODO

Stage 0: Initialize the Project

1. Create base structure:
   • src/main.rs
   • src/cli.rs
   • src/theme.rs
   • src/state.rs
   • src/apply.rs
   • tests/
2. Add crates:
   • clap, anyhow, thiserror, serde, serde_json, dirs, shellexpand, chrono, tempfile.
3. Wire a basic CLI with subcommands:
   • list, status, apply <theme>, backup, rollback.
4. Exit criteria:
   • cargo build and cargo run -- --help work.

Stage 1: Theme Discovery + Path Mapping

1. Decide the themes root:
   • start with ~/dotfiles/themes.
2. Implement theme discovery from subdirectory names under the themes root.
3. Define the mapping rule:
   • the path inside a theme maps directly onto $HOME.
4. Add list command to print available themes.
5. Exit criteria:
   • Non-theme entries are ignored.
   • list shows valid themes.

Stage 2: State Tracking

1. Create state.json model:
   • active_theme, applied_at, entries.
2. Add read/write helpers in state.rs.
3. Implement status command:
   • active theme
   • last apply time
   • missing/broken link detection (optional for now).
4. Exit criteria:
   • status works before and after apply.

Stage 3: Dry-Run Planner

1. Build planner in apply.rs:
   • recursively enumerate files in the selected theme
   • resolve source absolute paths
   • map each theme-relative path onto $HOME
   • produce action list (CreateLink, BackupExisting, Replace, Skip).
2. Add apply <theme> --dry-run.
3. Print exactly what would happen.
4. Exit criteria:
   • dry-run output is deterministic and readable.

Stage 4: Real Apply with Safety

1. Implement apply execution:
   • ensure parent dirs exist
   • backup conflicting targets to ~/.config/theme-manager/backups/<timestamp>/...
   • create symlinks (Unix first).
2. If any step fails:
   • rollback changed targets from backups.
3. Only write state.json after full success.
4. Exit criteria:
   • Switching themes works.
   • Partial failure restores previous state.

Stage 5: Rollback Command

1. Implement rollback to restore most recent backup set.
2. Restore target files and clear/update state.
3. Exit criteria:
   • Manual rollback works after a bad apply.

Stage 6: Force Mode + Conflict Policy

1. Add --force for replacing unmanaged files.
2. Default behavior without --force:
   • refuse overwrite of unknown real files.
3. Add clear conflict messages with target path.
4. Exit criteria:
   • Safe by default; force is explicit.

Stage 7: Tests (Required Before v0.1)

1. Unit tests:
   • theme discovery
   • path mapping
   • planner decisions
   • state serialization/deserialization.
2. Integration tests (tests/ with tempfile):
   • apply from empty state
   • switch dracula -> catppuccin
   • conflict without --force
   • rollback on simulated failure.
3. Exit criteria:
   • cargo test green.

Stage 8: UX Polish

1. Improve CLI output:
   • summary counts (created, replaced, backed_up, skipped).
2. Add --verbose.
3. Add --json output for scripting (optional).
4. Exit criteria:
   • command output is clear and actionable.

Stage 9: Release Readiness

1. Add README examples and directory layout.
2. Add a sample theme tree under examples/ or in README docs.
3. Add cargo clippy -- -D warnings and cargo fmt --check in CI.
4. Tag v0.1.0.

Suggested Strict Order

1. Stage 0
2. Stage 1
3. Stage 3
4. Stage 4
5. Stage 2
6. Stage 5
7. Stage 6
8. Stage 7
9. Stage 8
10. Stage 9