Clean action runtime project state

docs/architecture.md

@@ -0,0 +1,124 @@
+# Flow Architecture
+
+This document describes the current action-runtime architecture.
+
+## Runtime Shape
+
+Flow is organized around a canonical action plan:
+
+```text
+cli -> app -> domain -> actions -> adapters
+```
+
+The important boundary is `ActionPlan -> ActionExecutor -> ActionResult`.
+
+- `cli`: Typer command declarations and argument parsing in `src/flow/cli.py`.
+- `app`: command use-cases in `src/flow/app/`. These load config/state, compose
+  domain planners, and submit action plans.
+- `domain`: pure models, parsers, resolvers, and planners in `src/flow/domain/`.
+- `actions`: canonical action models, expansion, execution, dry-run rendering,
+  JSONL audit logging, and rollback in `src/flow/actions/`.
+- `adapters`: filesystem, process, git, package-manager, download, archive,
+  container, and tmux implementations in `src/flow/adapters/`.
+
+The filesystem is not the core abstraction. It is one adapter used by the
+executor. The core abstraction is the action plan.
+
+## Actions
+
+`DomainAction` captures user intent:
+
+- `kind`: `dotfiles`, `package`, `project`, `repo`, `container`, `remote`,
+  `setup`, or `completion`
+- `action`: `link`, `unlink`, `install`, `remove`, `update`, `pull`, `push`,
+  `create`, `stop`, and related verbs
+- `payload`: typed-by-domain data or already expanded primitive actions
+- `rollback_policy`: `rollbackable`, `barrier`, or `none`
+
+`PrimitiveAction` is the executor-owned operation set:
+
+- filesystem: create/remove symlink, write, write JSON, copy, copy tree, remove,
+  chmod
+- git: clone, pull, push, fetch, checkout, status
+- process: argv command or explicit user shell hook
+- packages/assets: download and archive extraction
+- containers: run, start, stop, kill, remove, exec
+- tmux: new session, set option, respawn pane
+
+Domain actions are expanded before execution. Dry-run output and audit logging
+come from the same primitive list that real execution uses.
+
+## Rollback
+
+Rollback is explicit and best effort.
+
+Supported file/state primitives record reverse actions before mutation. On
+failure, the executor rolls back in reverse order until it reaches a barrier.
+External boundaries such as package-manager commands, user shell hooks, git
+pushes, container lifecycle operations, and interactive command handoffs are not
+guaranteed to roll back.
+
+## Command Surface
+
+Implemented commands:
+
+```text
+flow dotfiles init|link|unlink|status|edit
+flow dotfiles repos list|status|pull|push
+flow packages install|remove|list
+flow setup run|show|list
+flow remote enter|list
+flow enter
+flow dev create|attach|connect|exec|enter|stop|remove|rm|respawn|list
+flow projects check|fetch|summary
+flow sync
+flow completion zsh|install-zsh
+```
+
+Global flags:
+
+```text
+flow --version
+flow --quiet
+flow --no-color
+```
+
+Mutating non-interactive commands expose `--dry-run` where a preview is useful:
+dotfiles link/unlink, dotfiles repo pull/push, package install/remove, setup
+run, remote enter, and dev create.
+
+## Dotfiles And Modules
+
+The dotfiles repo and `_module.yaml` repos share one abstraction: managed repos.
+`flow dotfiles repos` operates on both. Modules are regular git clones cached
+under the flow data directory; they are not git submodules.
+
+Link planning treats conflicts and missing modules as pre-execution failures.
+State is written through actions, and broken tracked symlinks are repaired by
+the same link reconciliation path.
+
+## Packages
+
+Package manifests are parsed into typed dataclasses. Package-manager commands
+are built as argv lists by the package adapter. Binary and AppImage installs
+expand into download, archive, copy/chmod, cleanup, post-install barrier, and
+state-write primitives.
+
+`packages remove` is strict: it refuses unknown packages, removes tracked files,
+and writes updated state through the executor.
+
+## Tests And Guards
+
+The test suite covers:
+
+- action executor dry-run, audit logs, rollback, barriers, domain expansion, and
+  primitive dispatch
+- dotfiles discovery, module handling, conflict behavior, rollback, and repo
+  operations
+- package manifest parsing, package-manager argv, binary installs, archive
+  safety, strict removal, and post-install barriers
+- Typer CLI invocation, help output, completion, and error reporting
+- Docker/Podman e2e for the example dotfiles repo when `FLOW_RUN_E2E=1`
+
+Static guard tests reject direct mutating filesystem and command APIs outside
+`actions`, `adapters`, and tests.