flow/docs/refactor-plan.md

Flow CLI Refactor Plan

Based on code review (2026-03-22) and architecture discussion. Spec: docs/superpowers/specs/2026-03-16-flow-architecture-redesign.md

Current State

The rewrite from the original "vibe-coded" codebase is largely complete. The four-layer architecture (core -> domain -> services -> commands) is in place, 303 tests pass, and the major structural problems from the old codebase (duplicated code, monkeypatching, dead modules, singleton abuse) have been resolved.

What remains is a second pass: finishing incomplete features, unifying the repo abstraction, and trimming redundant commands.

---

Agreed Command Surface

From the architecture discussion. This is the target.

flow remote enter <target>              # Host only. SSH+tmux into VM.
flow remote list                        # List configured targets.

flow dev create <name> -i <image>       # VM only. Create+start container.
flow dev attach <name>                  # Attach to container tmux session.
flow dev exec <name> [cmd...]           # Run command in container.
flow dev enter <name>                   # Interactive shell in container.
flow dev list                           # List dev containers.
flow dev stop <name>                    # Stop container.
flow dev rm <name>                      # Remove container.
flow dev respawn <name>                 # Respawn tmux panes.

flow dotfiles init --repo <url>         # Clone dotfiles repo + all module repos.
flow dotfiles link [--profile p]        # Reconcile symlinks (creates, fixes broken, removes stale).
flow dotfiles unlink [packages...]      # Remove managed symlinks.
flow dotfiles status [packages...]      # Show packages, link health, module info.
flow dotfiles edit <package>            # Pull -> $EDITOR -> commit+push.

flow dotfiles repos list                # List ALL managed repos (dotfiles + modules).
flow dotfiles repos status [--repo=x]   # Git status for one or all repos.
flow dotfiles repos pull [--repo=x]     # Pull one or all repos.
flow dotfiles repos push [--repo=x]     # Push one or all repos.

flow setup run [--profile p]            # Bootstrap a machine.
flow setup list                         # List profiles.
flow setup show <profile>              # Show profile plan.

flow packages install <name...>         # Install packages from manifest.
flow packages list [--all]              # List packages.
flow packages remove <name...>          # Remove packages.

flow projects check [--fetch]           # VM only. Git health across ~/projects.
flow projects fetch                     # Fetch all project remotes.
flow projects summary                   # Quick status overview.

Aliases

• dotfiles -> dot
• packages -> package, pkg
• projects -> project
• setup -> bootstrap
• dev attach -> dev connect
• dev rm -> dev remove
• dotfiles repos -> dotfiles repo

Global flags

• --version
• --quiet / -q
• --no-color

Commands removed (vs current implementation)

Removed	Reason
dotfiles sync	Redundant: repos pull + link
dotfiles relink	Redundant: link is idempotent
dotfiles undo	Redundant: unlink is the inverse of link
dotfiles clean	Folded into link (reconciliation handles broken symlinks)
dotfiles modules list	Replaced by dotfiles repos list
dotfiles modules sync	Replaced by dotfiles repos pull

Key design decision: modules are repos

The _module.yaml files define external git repos that provide content for dotfiles packages. These module repos are not git submodules -- they are regular git clones managed by flow.

The dotfiles repo itself is also a git clone managed by flow. So all managed git repos (the dotfiles repo + every module repo) share the same abstraction and the same commands.

dotfiles repos is the single entry point for all repo operations. There is no separate dotfiles modules subcommand group. The --repo=<name> flag filters to a specific repo when needed (dotfiles repo is named dotfiles, module repos are named by their package, e.g. nvim).

---

1. Unified Repos Abstraction

This is the most impactful change. Currently:

• repo_status/pull/push operate only on the dotfiles repo
• sync_modules handles module repos separately
• list_modules is a standalone method

Target: a single _discover_repos() -> list[RepoInfo] that returns all managed repos, and repo commands iterate over them.

1.1 Add RepoInfo model

# domain/dotfiles/models.py
@dataclass(frozen=True)
class RepoInfo:
    name: str           # "dotfiles" or module package name (e.g. "nvim")
    path: Path          # Local clone path
    remote: str         # Remote URL
    is_module: bool     # False for dotfiles repo, True for module repos

1.2 Implement _discover_repos

In DotfilesService: walk packages to find _module.yaml files, build RepoInfo for each module repo, plus one for the dotfiles repo itself.

1.3 Refactor repo commands

Replace repo_status, repo_pull, repo_push with methods that iterate _discover_repos(), filtered by --repo. Add repos_list.

1.4 Remove dotfiles modules subcommand group

Delete modules list and modules sync subparsers. Remove sync_modules, list_modules methods. Remove from completion candidates.

1.5 Update dotfiles init

init should clone the dotfiles repo, then discover _module.yaml files and clone all module repos. Currently it calls sync_modules() -- this should call repos_pull() instead (which pulls/clones all repos).

Files: models.py, services/dotfiles.py, commands/dotfiles.py, commands/completion.py.

---

2. Remove Redundant Commands

2.1 Remove dotfiles sync

Currently does git pull --ff-only + sync_modules + optional relink. After the repos unification, this is just repos pull + link. No need for a dedicated command.

2.2 Remove dotfiles relink

Currently calls link(). link is already idempotent -- calling it again reconciles state.

2.3 Remove dotfiles undo

unlink is the inverse of link. The backup/undo transaction machinery (_save_backup, _load_backup, _backup_path) can be deleted.

2.4 Fold dotfiles clean into dotfiles link

link should detect and remove broken symlinks as part of reconciliation, not require a separate clean step. Modify plan_link in domain/dotfiles/planning.py to include broken link removal in its plan.

Files: services/dotfiles.py, commands/dotfiles.py, commands/completion.py, domain/dotfiles/planning.py.

---

3. Previously Incomplete Features -- DONE

3.1 dotfiles edit -- DONE

Implemented: pull -> $EDITOR/$VISUAL -> scoped git add -> commit+push. Flag: --no-commit to skip auto-commit/push.

3.2 dotfiles status -- DONE

Enhanced: shows module info (branch:main), link health (ok/broken/not linked), package name filtering via positional args.

3.3 dotfiles repos list -- DONE

Shows all managed repos (dotfiles + modules) with: name, type, local path, clone status.

---

4. Spec Deviations

4.1 --no-color global flag -- DONE

Added to cli.py.

4.2 --dry-run coverage -- DONE for dotfiles

repos pull and repos push now have --dry-run. Remaining:

Command	Has it	Should have
dev stop	No	Consider
dev rm	No	Consider

4.3 Improvements over spec

These are correct deviations -- the implementation improved on the spec:

• core/containers.py + core/tmux.py extracted as adapters (spec had them inline)
• core/config_parse.py + core/yaml.py extracted for config parsing
• SystemRuntime extended with .containers and .tmux fields

---

5. Code Quality (done)

These were fixed in this session:

• FakeRunner consolidated from 3 test files into tests/fakes.py
• services/dotfiles.py now uses flow.core.yaml.load_yaml_file instead of raw yaml
• ContainerRuntime.binary no longer eagerly validates PATH for explicit modes

---

6. Future (defer)

6.1 Bootstrap as orchestrator

The spec envisions bootstrap as a pure orchestrator over packages + dotfiles + setup modules. Current implementation works but has its own package resolution logic. Defer until dotfiles and packages domains are fully stable.

6.2 Global --dry-run

If per-command --dry-run becomes a maintenance burden, promote to a global flag in cli.py.

---

7. Execution Status

All phases complete. 315 tests pass, 0 failures.

Phase A: Unify repos + trim commands -- DONE

1. RepoInfo model with module_ref field
2. _discover_repos() finds dotfiles + module repos
3. repos_list/status/pull/push iterate all repos with --repo filter
4. repos list subcommand added
5. dotfiles modules subcommand removed entirely
6. dotfiles sync, relink, undo, clean removed
7. Broken-symlink handling folded into plan_link
8. dotfiles init uses unified repos_pull()

Phase B: Complete features -- DONE

9. dotfiles edit implemented (pull -> $EDITOR -> commit+push, scoped git add)
10. dotfiles status enhanced (module info, link health, package filtering)

Phase C: CLI polish -- DONE

11. --no-color global flag added to cli.py
12. --dry-run added to repos pull and repos push
13. Zsh completion updated for new command surface

Phase D: Code quality -- DONE

14. Dispatch patterns: completion complete(), dotfiles _git_checkout_ref, bootstrap phases
15. FakeRunner consolidated to single tests/fakes.py (all 4 test files)
16. Bootstrap VALID_PHASES as single source of truth in models
17. Bootstrap models: Any types replaced with ProfilePackageEntry and PackageDef
18. Canonical ssh-keys field (removed ssh-keygen alias)
19. getattr defensive patterns removed from command handlers
20. Test coverage added: repos_status, repos_push, repos_pull --dry-run, status filtering, broken symlink repair
21. README updated to reflect new command surface

Remaining (deferred)

• Bootstrap as orchestrator (section 6.1)
• Global --dry-run (section 6.2)