refactor-1

docs/architecture.md

@@ -0,0 +1,52 @@
+## Flow CLI Architecture
+
+### Layers
+
+`flow` now follows a stricter adapter/service/runtime split:
+
+- `flow.cli`
+  - global startup, platform/config loading, top-level error handling
+- `flow.commands.*`
+  - argparse registration and compatibility wrappers only
+- `flow.services.*`
+  - domain behavior for SSH entry, containers, dotfiles, bootstrap, packages, and project sync
+- `flow.core.system`
+  - shared process, git, filesystem, and JSON state primitives
+- `flow.core.*`
+  - config loading, platform detection, console output, variables
+
+### Runtime Safety
+
+Mutating operations are centralized behind `flow.core.system`:
+
+- `CommandRunner`
+  - subprocess execution and shell streaming
+- `GitClient`
+  - repository-scoped git execution
+- `FileSystem`
+  - directory creation, copy, symlink, removal, JSON/text writes
+- `JsonStateStore`
+  - state persistence with explicit paths
+
+This keeps command handlers out of the business of directly creating, deleting, or overwriting filesystem state.
+
+### Domain Boundaries
+
+- `services.ssh`
+  - parses enter targets, resolves host templates, builds the SSH handoff
+- `services.containers`
+  - owns container create/exec/connect/list/stop/remove/respawn logic
+- `services.projects`
+  - owns git status/fetch/summary logic for project directories
+- `services.package_defs`
+  - normalizes manifest package definitions and binary package install logic
+- `services.packages`
+  - package state listing/install/remove behavior
+- `services.bootstrap`
+  - provisioning orchestration, package-manager resolution, hooks, shell/locale/hostname setup
+- `services.dotfiles`
+  - repo sync, module discovery, link planning, transactional undo, status, edit flow
+
+### Compatibility Strategy
+
+The current CLI surface is preserved. The command modules still expose a small set of legacy helper symbols because the existing tests use them directly, but the behavioral implementation now lives in the service layer.

docs/flows.md

@@ -0,0 +1,86 @@
+## Feature Inventory
+
+### Core Features
+
+- `enter`
+  - SSH into a named environment target with optional tmux auto-attach
+- `dev`
+  - create, exec into, attach to, list, stop, remove, and respawn development containers
+- `dotfiles`
+  - clone the dotfiles repo, link/unlink/relink configs, undo link transactions, inspect status, sync modules, clean broken links, edit packages, and interact with repo state
+- `bootstrap`
+  - run machine bootstrap profiles with packages, env validation, hostname/locale/shell setup, ssh-keygen, `runcmd`, config linking, and post-link hooks
+- `package`
+  - install/list/remove binary packages defined in the manifest
+- `sync`
+  - inspect git project health, fetch remotes, and summarize project state
+- `completion`
+  - dynamic zsh completion generation and installation
+
+### Supported Flows
+
+#### Access a host
+
+1. Resolve `[user@]namespace@platform`
+2. Expand platform host template or configured target override
+3. Optionally warn about missing remote terminfo
+4. Open SSH, optionally into tmux
+
+#### Start a dev container
+
+1. Resolve runtime (`docker` or `podman`)
+2. Normalize image shorthand
+3. Apply labels and common host mounts
+4. Start the container
+5. `flow dev connect` attaches through tmux or falls back to direct exec
+
+#### Manage dotfiles
+
+1. Clone dotfiles repo
+2. Optionally sync external module repos
+3. Resolve shared + profile packages
+4. Validate target conflicts
+5. Snapshot replaced targets
+6. Apply links transactionally
+7. Undo from persisted transaction state if needed
+
+#### Bootstrap a machine
+
+1. Load and validate a profile
+2. Detect or select the package manager
+3. Check required environment variables
+4. Apply hostname/locale/shell prerequisites
+5. Install profile packages
+6. Run package hooks
+7. Generate SSH keys
+8. Run `runcmd`
+9. Link dotfiles for the profile
+10. Run post-link hooks
+
+### Command Surface Review
+
+### Keep
+
+- `enter`
+- `dev`
+- `dotfiles`
+- `bootstrap`
+- `package`
+- `sync`
+- `completion`
+
+### Keep But Treat As Convenience Aliases
+
+- `dotfiles sync`
+  - effectively `repo pull` + `modules sync`
+- `dotfiles relink`
+  - effectively `unlink` + `link`
+- `sync summary`
+  - effectively `sync check --no-fetch`
+
+### Commands That Need Follow-Up Product Decisions
+
+- `package remove`
+  - today it forgets install state but does not uninstall files; either rename it to `forget` or implement real uninstall semantics
+- `dotfiles edit`
+  - current auto-commit/push behavior is powerful but risky; it may deserve an explicit confirm-or-dry-run mode before wider use