flow/README.md

# flow

CLI for managing development environments: dotfiles, packages, dev containers, remote targets, and system bootstrap.

## Quick start

```bash
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

```bash
# 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... [--dry-run]
flow packages list [--all]

# Bootstrap
flow setup run [PROFILE|--profile NAME] [--dry-run] [--var KEY=VALUE]
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` -> `dot`
- `dotfiles repos` -> `dotfiles repo`
- `packages` -> `package`, `pkg`
- `projects` -> `project`; `flow sync` -> `flow projects check --fetch`
- `setup` -> `bootstrap`, `provision`
- `remote enter` -> `enter`
- `dev attach` -> `dev connect`
- `dev remove` -> `dev rm`

## Configuration

Loaded from `~/.config/flow/config.yaml`, merged with dotfiles repo overlay at `~/.local/share/flow/dotfiles/_shared/flow/.config/flow/`.

```yaml
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 docker
- `podman` -- force podman, prefer rootless socket
- `podman-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:

```yaml
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.

```yaml
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

Flow uses an action-centered runtime:

- **cli** parses Typer command arguments and calls app use-cases.
- **app** resolves config/state, builds `ActionPlan` objects for executor-managed work, and keeps only explicit interactive boundaries outside the executor.
- **domain** modules keep planning and resolution logic pure with frozen dataclasses.
- **actions** are the execution boundary: `DomainAction` records domain intent, expansion converts it to `PrimitiveAction`, and `ActionExecutor` handles dry-run rendering, audit logging, rollback, and dispatch.
- **adapters** provide runtime primitives through `SystemRuntime`: `CommandRunner`, `FileSystem`, `GitClient`, `TmuxClient`, `ContainerRuntime`, download, and archive adapters.

Action audit records are appended to `actions.jsonl` under the relevant flow state directory.

## Security

- Rejects root invocation
- `_root/` dotfile paths require sudo for linking
- Package post-install hooks run without sudo by default

## Development

```bash
make deps                              # create .venv + install deps
.venv/bin/python -m pytest tests/ -v --ignore=tests/e2e
FLOW_RUN_E2E=1 .venv/bin/python -m pytest tests/e2e/ -v  # requires docker or podman
```