flow/docs/refactor-plan.md

Flow CLI Refactor Status

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

Current State

The action-runtime rewrite is implemented. cli.py is a thin Typer adapter, flow.app owns application orchestration, domain modules keep pure planning and resolution logic, and executor-managed mutations are represented as action plans before they reach runtime adapters.

The old structural problems from the original codebase (duplicated flows, monkeypatching, dead modules, singleton-style runtime access) have been removed from the active command paths. The remaining refactor work is deferred cleanup, not a blocker for the action-centered architecture.

---

Command Surface

This is the implemented command surface.

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] [--dry-run]
flow dotfiles repos push [--repo=x] [--dry-run]

flow setup run [profile|--profile p] [--dry-run] [--var KEY=VALUE]
flow setup list                         # List profiles.
flow setup show <profile>              # Show profile plan.

flow packages install [name...] [--profile p] [--dry-run]
flow packages list [--all]              # List packages.
flow packages remove <name...> [--dry-run]

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; flow sync -> flow projects check --fetch
• setup -> bootstrap, provision
• remote enter -> enter
• dev attach -> dev connect
• dev rm -> dev remove
• dotfiles repos -> dotfiles repo

Global flags

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

Commands Removed During Refactor

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

Action-Centered Architecture

The runtime boundary is flow.actions.

• ActionPlan is the unit of execution. It can contain high-level DomainAction entries and direct PrimitiveAction entries.
• DomainAction records intent from a domain such as dotfiles, packages, repos, remote targets, containers, completion, or setup.
• expand_actions() converts domain actions into primitive actions. Some domains supply already expanded primitive plans when the service has concrete runtime arguments.
• PrimitiveAction is the canonical executor input for filesystem, process, git, download, archive, container, and tmux operations.
• ActionExecutor owns dry-run output, append-only JSONL audit logging, rollback stack management, rollback barriers, and dispatch into SystemRuntime.

App use-cases construct plans and pass them to the executor for action-backed commands. Direct runtime calls are limited to explicit interactive boundaries such as attaching to tmux or entering a container shell. Domain modules stay free of I/O where the current implementation has pure resolution/planning functions.

Rollback is best-effort and explicit. Actions default to rollbackable; external boundaries such as shell commands, remote sessions, and non-reversible git/container operations use barrier or none policies.

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).

---

Completed Work

Unified Repos Abstraction

RepoInfo with module_ref is the canonical repo model. _discover_repos() finds the dotfiles repo and module repos, and repos list/status/pull/push iterate that single collection with an optional --repo filter. dotfiles init uses the same pull-or-clone flow.

Command Trimming

Removed redundant dotfiles commands:

• dotfiles sync: use dotfiles repos pull plus dotfiles link
• dotfiles relink: dotfiles link is idempotent
• dotfiles undo: use dotfiles unlink
• dotfiles clean: broken symlink repair is part of link planning
• dotfiles modules list/sync: use dotfiles repos list/pull

Feature Completion

• dotfiles edit: pull -> $EDITOR/$VISUAL -> scoped git add -> commit+push, with --no-commit to skip auto-commit/push.
• dotfiles status: module info, link health, and package filtering.
• dotfiles repos list: all managed repos with name, type, local path, and clone status.
• --no-color: global flag added to cli.py.
• --dry-run: supported by dotfiles link/unlink, repos pull/push, packages install, setup run, remote enter, and dev create.

Improvements Over Spec

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

• adapters/containers.py + adapters/tmux.py extracted as adapters (spec had them inline)
• core/config_parse.py + core/yaml.py extracted for config parsing
• SystemRuntime extended with containers, tmux, download, and archive runtime fields
• flow.actions extracted as the canonical execution layer instead of leaving mutation dispatch in individual app use-cases

---

CI

The GitHub Actions workflow is split into two jobs:

• unit: installs dependencies and runs pytest tests/ -v --ignore=tests/e2e
• e2e: verifies Docker is available, sets FLOW_RUN_E2E=1, and runs pytest tests/e2e/ -v

---

Optional Future Work

These are optional refinements, not blockers for the action-centered rewrite.

Global --dry-run

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