Tomas Mirchev
c0e2758057
- Atomic state writes (tempfile + os.replace) so a crash mid-write cannot corrupt linked.json. - Managed-symlink guards in FileSystem.create_symlink and the new remove_symlink: refuse to overwrite or delete a path unless it is absent or already a symlink pointing to the expected source. Stops silent user-file deletion in the plan/apply race window. - plan_link adopts orphan symlinks whose readlink already matches the desired source, so a partial-apply failure can be recovered by rerun. - _load_state warns loudly on each stale entry it drops, and status() no longer rewrites linked.json as a side effect of read. - _apply_plan dispatches exhaustively; unknown LinkOp types raise. - Remove _checkout_module_ref early-return for branch == "main" -- it assumed the remote default was main, breaking master-default repos. Always run the explicit checkout (idempotent). - Warn when a module's cache_dir is absent during link, suggesting flow dotfiles repos pull. - LinkOp.type and ModuleRef.ref_type tightened to Literal[...]; dead "create_dir" enum value removed from the model. Tests: +29 covering atomic writes, overwrite guards, remove_symlink semantics, orphan adoption (match/mismatch), partial-failure rerun, status read-only, branch/tag/commit checkout argv, uncloned-module warning, stale-state warnings. 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