1.9 KiB
1.9 KiB
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.