Tomas Mirchev
6b7a48bb20
Independent re-audit surfaced 11 follow-ups across two layers of review
(my fresh-eyes read + a parallel agent pass). Bundled into a single
commit because changes are small and intertwined.
Symlink / state consistency:
- FileSystem.same_symlink now uses raw readlink() instead of resolve().
Aligns the three sites that ask "is this our link?" (_load_state,
_check_overwrite_safe, remove_symlink) on a single rule: exact-readlink
match. Following symlink chains would let externally-modified links
pass as ours and be silently overwritten.
- LinkedState.from_dict raises ConfigError on missing required fields
instead of .get(..., False) silent defaults. Matches InstalledState.
- LinkOp.source is now consistently None for remove_link ops; the
service derives expected_source from current.links. Removes the
asymmetry between in-state and orphan-broken removal ops.
- _apply_plan: rename shadowing local from link_target to spec.
Fail loud:
- _xdg() now treats XDG_CONFIG_HOME="" the same as unset. Previously
an empty env var produced Path("") and state files were written to
$PWD instead of ~/.local/state/flow.
- _resolve_target raises PlanConflict when a package contains a bare
_root entry (no path components) instead of silently dropping it.
- _strip_prefix raises FlowError when a declared install path does not
start with its section's expected prefix (e.g. etc/foo under install.bin).
Speculative abstraction removed (CLAUDE.md):
- core.template.substitute (the $VAR form) had no production callers --
deleted along with its tests; only the {{var}} form remains.
- SetupModule base class -- five subclasses, no shared behaviour, no
polymorphic call site. Deleted.
- Profile.arch -- parsed but never read. Deleted.
- PackagePlan.pm_command -- set but never read. Deleted (service
recomputes pm_install_command at the call site).
- FileSystem.ensure_dir(mode=...), .copy_file(sudo=...), .read_text(
default=...) -- no callers. Deleted along with their test.
- bootstrap _execute_action: the upfront `phase not in VALID_PHASES`
check duplicated the trailing exhaustive raise. Kept the trailing
raise as the single source of truth; phase set still documented in
VALID_PHASES.
Completion ctx threading:
- Removed _config()/_manifest() helpers that re-loaded from disk on
every completion call. _list_targets, _list_namespaces, _list_platforms,
_list_bootstrap_profiles, _list_manifest_packages now take ctx and
read from ctx.config / ctx.manifest.
Test coverage and e2e:
- e2e container test exercises a real `flow dotfiles link` (no dry-run)
and asserts the resulting symlinks point into the dotfiles dir;
reruns to verify idempotency.
- New tests: LinkedState corrupt-state ConfigError, LinkedState bad-version
ConfigError, bare-_root PlanConflict, service-level _root path routing
+ skip semantics.
- 11 stale test imports removed (pyflakes clean across src/ + tests/).
357 unit tests + 1 e2e (gated) all pass.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
flow
CLI for managing development environments: dotfiles, packages, dev containers, remote targets, and system bootstrap.
Quick start
make build && make install-local # installs to ~/.local/bin/flow
flow setup run linux-work # bootstrap a machine
flow dotfiles link # symlink dotfiles
flow dev create api -i tm0/node # spin up a dev container
flow dev attach api # attach via tmux
Commands
# Dotfiles
flow dotfiles link [--profile NAME] [--dry-run] [--skip PKG...]
flow dotfiles unlink [PACKAGES...] [--dry-run]
flow dotfiles status [PACKAGES...]
flow dotfiles edit PACKAGE [--no-commit] # pull -> $EDITOR -> commit+push
# Dotfiles repos (unified: dotfiles repo + module repos)
flow dotfiles repos list
flow dotfiles repos status [--repo NAME]
flow dotfiles repos pull [--repo NAME] [--dry-run]
flow dotfiles repos push [--repo NAME] [--dry-run]
# Packages
flow packages install [NAMES...] [--profile NAME] [--dry-run]
flow packages remove NAMES...
flow packages list [--all]
# Bootstrap
flow setup run PROFILE [--dry-run] # run a full bootstrap profile
flow setup show PROFILE # preview profile steps
flow setup list
# Remote targets
flow remote enter TARGET [--dry-run] # ssh + tmux into a remote target
flow remote list
# Dev containers (docker or podman)
flow dev create NAME -i IMAGE [-p PROJECT] [--dry-run]
flow dev attach NAME # tmux session into container
flow dev exec NAME [-- CMD...] # run a command in container
flow dev enter NAME # interactive shell
flow dev stop NAME [--kill]
flow dev remove NAME [-f]
flow dev respawn NAME # restart all tmux panes
flow dev list
# Projects
flow projects check [--fetch] # scan ~/projects for dirty repos
flow projects fetch # fetch all project remotes
flow projects summary # quick overview
# Shell completion
flow completion zsh # print zsh completion script
flow completion install-zsh # install to ~/.zsh/completions
# Global flags
flow --version
flow --quiet # suppress info output
flow --no-color # disable colored output
Aliases
dotfiles->dotdotfiles repos->dotfiles repopackages->package,pkgprojects->project,sync(with--fetchdefault)setup->bootstrapdev attach->dev connectdev remove->dev rm
Configuration
Loaded from ~/.config/flow/config.yaml, merged with dotfiles repo overlay at ~/.local/share/flow/dotfiles/_shared/flow/.config/flow/.
repository:
url: git@github.com:you/dotfiles.git
branch: main
paths:
projects: ~/projects
defaults:
container-runtime: auto # auto | docker | podman | podman-rootful
container-registry: registry.example.com
container-tag: latest
tmux-session: main
targets:
personal@orb: personal.orb
work@ec2:
host: work.ec2.internal
identity: ~/.ssh/id_work
Container runtime
container-runtime controls which engine flow dev uses:
auto-- detect docker or podman from PATH (default)docker-- force dockerpodman-- force podman, prefer rootless socketpodman-rootful-- force podman, prefer rootful socket (/run/podman/podman.sock)
When using podman, flow dev create automatically adds --security-opt label=disable for engine socket access. The socket is always mounted to /var/run/docker.sock inside the container (Podman's Docker-compatible API).
Dotfiles layout
_shared/ # Linked for all profiles
zsh/
.zshrc
nvim/
.config/nvim/
_module.yaml # External git module
.local/bin/
nvim-wrapper
dns/
_root/ # Absolute path marker (needs sudo)
etc/hosts
linux-work/ # Profile-specific layer
i3/
.config/i3/config
External modules
_module.yaml inside a package mounts an external git repo at that location:
source: github:org/nvim-config
ref:
branch: main
Modules are regular git clones managed by flow (not git submodules). They appear alongside the dotfiles repo in flow dotfiles repos list and are pulled/pushed with the same commands.
Manifest
Packages and profiles defined in YAML files under the flow config directory.
packages:
- name: fd
type: pkg
sources:
apt: fd-find
brew: fd
- name: neovim
type: binary
source: github:neovim/neovim
version: "0.10.4"
platform-map:
linux-x64: nvim-linux-x86_64.tar.gz
profiles:
linux-work:
os: linux
hostname: dev-box
locale: en_US.UTF-8
shell: zsh
packages:
- fd
- binary/neovim
ssh-keys:
- path: ~/.ssh/id_ed25519
type: ed25519
runcmd:
- echo "setup complete"
Architecture
Four layers: core (runtime primitives, config, errors) -> domain (pure functions, frozen dataclasses) -> services (I/O orchestration) -> commands (thin CLI adapters).
Core primitives (SystemRuntime): CommandRunner, FileSystem, GitClient, TmuxClient, ContainerRuntime.
Security
- Rejects root invocation
_root/dotfile paths require sudo for linking- Package post-install hooks run without sudo by default
Development
make deps # create .venv + install deps
.venv/bin/python -m pytest tests/ -v # run tests