dotfiles.pro

Appearance

Roadmap ​

Substantial initiatives each have a design doc under roadmap/ (linked below); this file is the index. Per-role tweaks stay as one-liners.

Team provisioning ​

Offer the personal-repo starter as a GitLab template project and a GitHub template repository instead of copying the examples/ directory: roadmap/team-provisioning.md (#2)

  • SSH key handoff: an unattended path (a pre-seeded deploy key or token) so a non-interactive install.sh can clone a private repo on a keyless fresh machine, and which role owns that key afterwards: roadmap/ssh-key-handoff.md (#3)

CLI (dotpro) ​

  • Consolidate the four independently written copies of the mitogen strategy-plugin registration (install.sh, the ansible role's uv and apt tasks, and register_mitogen in the CLI) into one shared mechanism, so a layout change can't silently drop a path back to linear; the install.sh copy runs before the collection exists, so it needs an embedded shared snippet rather than a call into dotpro (#4)
  • Recheck the uv ansible-core pin often. The uv Ansible is pinned to ansible-core<2.21 (ansible_uv_ansible_core in the ansible role, DOTPRO_ANSIBLE_CORE in install.sh) because Mitogen can't read ansible-core 2.21's task results yet (UnifiedTaskResult is not iterable), so every mitogen task fails on it. Watch mitogen #1523 (2.21 support) / #1530 (Ubuntu 26.04) and lift the pin when it ships. (The separate apt-module _module_fqn respawn crash was fixed in the dotpro CLI by running the apt module under system python3 via an ansible_python_interpreter extra-var, not a mitogen version issue.) The ubuntu: CI matrix exercises both paths (#5)
  • Align the progress callback's up-front role prediction with Ansible's real tag evaluation so the all/tagged/untagged selectors predict the right roles: roadmap/progress-callback.md (#6)
  • Decide whether --output compact should drop the community.general.unixy stand-in now that the native per-role callback ships as the default progress mode (#7)
  • Settings capture (dotpro capture): subtract the keys your vars already manage, and add the generate / baseline adapters for full-default apps, where the file is not already just your overrides (v1 covers claude, git, vscode): roadmap/settings-capture.md (#8)
  • Feed the roles' detect.yaml hints into the dotpro init wizard: scan the fresh machine and preselect the matching roles, the day-0 counterpart of dotpro suggest (#9)
  • List the Tasks: a run will execute at startup the way the progress output already lists Roles:, so the up-front preview covers both (#10)
  • Single-host role parallelism (mitogen_parallel): spread the roles' independent local work across idle cores, shipped as its own dotfilespro package (a real strategy is a core-engine change; a 127.x pseudo-host + forks fallback works today). Parked: a measured cold converge puts the parallelizable local bucket at ~11s of disk-bound extraction (~5% cold ceiling, ~0% warm), so revisit only when the role set grows more extraction: roadmap/mitogen-parallel.md (#11)

Releases ​

Tag semantic releases, document the pinning gradient (pin what you don't control, track what you do), publish to Ansible Galaxy, and add README badges: roadmap/releases.md (#12)

Supply chain ​

Verify upstream artifacts before installing them. The apt and Homebrew paths inherit their package manager's signature checks, but a few direct downloads still do not: gcloud fetches release binaries with no checksum:, and the starship, opentofu, uv, and Homebrew installers fetch a vendor script and run it unverified. Whatever the URL serves gets run.

  • Verify gcloud's release download against a published SHA256 sum, and where upstream signs its releases (helm provenance, cosign-signed sums, GPG) verify the signature too, not just the digest (#13)
  • Pin or checksum the vendor install scripts (starship, opentofu, uv, Homebrew) rather than executing whatever the endpoint returns at apply time (#14)
  • Document the trust model next to the pinning gradient in roadmap/releases.md (pin what you don't control), and surface per-tool verification status in dotpro doctor (#15)

This is the trust counterpart to the version history that now records every upgrade: history says what changed, verification says the change is authentic.

Plugins ​

  • Recruit the first convention-following dotfiles plugin for the plugins index in docs/plugins.md. Install-grade Galaxy roles rarely reach the top tier: the alias-and-shell experience layer is exactly what a native role adds, which is why thin roles like composer and node stay planned rather than delegated (#16)

Artifact cleanup ​

The wsl, dotfiles, and windows roles each prune their own stale artifacts (Windows shims, repo symlinks, workspace launchers and shortcuts). Generalize that into a collection-wide convention: each role marks the artifacts it generates (~/.profile.d/ scripts and alias files, shims, versions.d entries) and an apply removes ones no longer declared in vars, so dropping a role or a variable doesn't leave stale files behind (the "Getting out" caveat in docs/alternatives.md).

The hard case is a dropped role: it doesn't run, so it can't prune itself; that needs a central marker sweep, not just a per-role prune. (#17)

Role conventions ​

  • Make an optional <role>_env dict rendered to ~/.profile.d/<role>.sh part of the role convention (wsl_env and googlecloud_env already work this way; unix_env sets machine-wide variables), and add an Environment section to the role README convention (#18)
  • Move the git role's worktree and git-statuses helper scripts (plain bash, templated into ~/scripts) into the bash/unix role as managed .sh files, beside notify and versions (#19)

Documentation ​

  • More asciinema demo recordings: every demo-worthy role is recorded and embedded in its README (the record-demo skill holds the pattern; each demo has a roles/<role>/screenplay.md and a roles/<role>/record-demo.sh). Remaining: the two live-agent cast slots the agents README reserves. Ruled out for now: aws, digitalocean, gitlab, googlecloud, googleworkspace, sentry (need live credentials; revisit with a mocked backend), docker (no daemon in the recording container), macos, windows, wsl (need their host OS), unix, zsh, python, opentofu (covered by another demo or too thin to fill three beats) (#20)

Devcontainers ​

A file-only bootstrap for minimal / no-Ansible boxes (servers, remote shells, devcontainers) that applies just the ~/.profile.d/ subset, rendered from the same role templates as the host: roadmap/devcontainers.md (#21)

Testing ​

Mirror the Ubuntu apply + idempotence harness onto macOS and Windows/WSL via a GitHub Actions mirror (GitLab shared runners run neither, and WSL needs a real Windows host): roadmap/testing.md (#22)

  • aws is held out of the test matrix until its AWSume install moves off a bare pip: into the system interpreter (fails under PEP 668 on Ubuntu 24.04+); switch to pipx/--user/venv, then re-add it (#23)

Agents ​

  • Give the agents README the Variables and Examples sections the other roles carry (#24)
  • A claudew wrapper that fronts claude --worktree, so a worktree-scoped session is one short command (#25)
  • MCP server management: a machine-level MCP inventory in the agents role that each tool role materializes into its agent's config, the way agents_skills feeds each tool's skill selection (the claude role's own claude_code_mcps writes Claude Code's servers); includes a dotfiles.pro blog post on MCPs vs CLIs: when a TOOLING.md CLI is enough and when an MCP server earns its place (#26)

macOS container runtime ​

macOS is a supported platform and the docker role already runs on it via colima. The open item is making the runtime a per-host choice (Apple container / Docker Desktop / podman) rather than colima only: roadmap/macos.md (#27)

  • Make docker compose work on macOS: Homebrew's docker-compose formula needs cliPluginsExtraDirs in ~/.docker/config.json, which the docker role never writes (unverified on a Mac) (#28)

Linux distributions ​

  • Support Arch and Fedora beyond Ubuntu: the delta is mostly package-manager mapping (pacman/dnf vs apt) in the platform role; decide whether each gets its own role like ubuntu or a shared Linux role with per-distro package maps (#29)

Ubuntu ​

  • Auto-detect the login shell so a zsh-on-Linux fleet picks up the framework without an explicit shell: zsh. The shell axis now ships (unix derives ~/.zprofile / ~/.zshrc sourcing from unix_shell, set shell: zsh in host_vars); the remaining nicety is defaulting shell from the user's actual login shell rather than the OS (#30)
  • Verify and document the collection on native Ubuntu desktop (non-WSL); nothing besides the wsl role should be WSL-specific (#31)

Windows ​

Extend the shipped windows role past interop-only management: roadmap/windows.md (#32)

  • WSL-side aliases that fire a workspace launcher from a Linux prompt (the wsl role ergonomics half) (#32)
  • Drive Windows browsers from WSL over CDP, for testing and agent tasks: launch a workspace-launcher browser instance with a remote-debugging port (its per-client --user-data-dir already clears Chrome 136's default-profile block) and connect from WSL via Playwright connectOverCDP; open question is the WSL→Windows path: mirrored networking in the wsl-role-managed .wslconfig, or a portproxy, since CDP binds to Windows localhost (#33)
  • scoop as a second package source next to winget (#32)
  • Per-window pixel geometry in the workspace launcher: let an app entry declare an explicit rectangle (or a FancyZones zone) so Move-AppWindow places beyond today's monitor + maximize granularity (#34)
  • Reliably place Windows Terminal windows from the workspace launcher: wt.exe hands off to WindowsTerminal.exe and exits, so Wait-AppWindow (keyed on the launched process basename wt) misses the window; map wt→WindowsTerminal in window discovery so monitor/maximize apply instead of only when no terminal is already open (#35)
  • Decide the SSH/WinRM transport for headless desired-state convergence, or keep everything on interop (#32)
  • Spin the Virtual Desktop Router out into its own git project/package in the dotfilespro ecosystem: it's already config-free and standalone, so it could ship independently of the windows role (PowerShell module / Gallery / winget) for people who don't use the rest of dotfilespro; open question is the packaging form and how the role then consumes it (#36)
  • Extract the virtual desktop name overlay (the always-on-top label the windows role templates) into a standalone, separately distributed app for non-dotfiles users, mirroring merlinai's VirtualDesktopOverlay; open question is packaging (winget / PowerShell Gallery / a compiled exe) and whether the role then installs that instead of shipping the script (#37)
  • Ask upstream for the primitive the toast click-to-focus workaround compensates for: kitty-style focus-on-click on Windows Terminal's own OSC 9 toasts, or exposing a session's hosting window/tab (microsoft/terminal#18692, #19818): either would let notify read the mapping instead of probing the window at prompt submit and stamping tab titles at ping time, shrinking the focus handler to plain window-plus-tab activation (#38)
  • Terminal Overview: an always-on-top panel of the Windows Terminal sessions that need attention across every virtual desktop and instance, fed by the notify pipeline (the bash attention fragment and claude hooks) and reusing the overlay's infrastructure: roadmap/terminal-overview.md (#39)

Virtual desktops and workspaces (Ubuntu, macOS) ​

Port the windows role's desktop/workspace model (desktops as converged state, workspaces as hotkeyed launchers that start apps on a desktop and monitor, isolated per-client app instances via --user-data-dir) to the other desktops:

  • Ubuntu/GNOME: static workspaces and names via gsettings (org.gnome.desktop.wm.preferences), direct-switch keybindings (switch-to-workspace-N), launcher scripts placing windows through gdbus/wmctrl or the auto-move-windows extension; .desktop entries with custom shortcuts as the trigger (#40)
  • macOS: Spaces have no API at all, so pick the dependency first: AeroSpace (own workspace model, no SIP changes), yabai (Space control needs SIP partially disabled), or Hammerspoon (launch + placement, hotkeys); then mirror the same vars on top (#41)

New roles ​

  • Expand the zsh role (it ships minimal: compinit, plus bash completions bridged through bashcompinit): native per-tool zsh completions, zsh options/history, and optional oh-my-zsh; plus a decision on which other shells to support (for example fish) and whether oh-my-zsh and starship overlap or compose (#42)
  • AI-tool roles beyond claude and codex (opencode, the GitHub Copilot CLI); decide which to support (#43)
  • gemini Google's Gemini CLI terminal agent, the Google sibling of the claude role (#44)
  • antigravity Google's Antigravity CLI, the Gemini CLI's successor for free-tier accounts; may subsume the planned gemini role once the migration settles (#44)
  • Security tooling roles: survey the many that one alternative ships and choose a curated set (#45)
  • node nvm, a default Node version, and npm global packages (e.g. Claude Code and the devcontainer CLI could move from raw npm install -g to this) (#57)
  • composer PHP Composer for PHP project workflows (PHP itself is often managed by other tooling, so keep it scoped to Composer) (#46)
  • firebase the Firebase CLI for project management, databases, and hosting; also ships as a Gemini CLI extension, so weigh standalone vs the planned gemini role (#47)
  • homebrew Linuxbrew under /home/linuxbrew; shares groundwork with the macos role's Homebrew setup (#48)
  • mkcert install mkcert and idempotently set up the local CA (replaces first-boot systemd hacks) (#49)
  • 1password op CLI as an alternative to the bitwarden role (#50)
  • slack install Slack and manage per-instance "profiles" on Linux and macOS so multiple isolated instances (per client/workspace) run side by side via --user-data-dir, the way the windows role's workspace entries already launch them on Windows (#51)
  • firefox cross-platform (like git/docker): policies.json for locked settings and forced extensions, a templated user.js for per-profile defaults, per-context profiles as the browser sibling of the slack model, and a stance on Firefox's new-style profiles feature (selector, avatars/icons): design in roadmap/firefox.md (#52)
  • vault HashiCorp Vault CLI as a runtime secrets backend alongside the bitwarden role and planned 1password, for fleets that centralize secrets in Vault (#53)
  • b2 Backblaze B2 CLI in a managed virtualenv (widely used for offsite backups; replaces ad-hoc pip install in install-time scripts) (#54)
  • warp Warp terminal via its apt repository; generally useful beyond any one company, like starship; guard for WSL/headless where the native Windows/macOS app is used instead (#55)
  • atuin encrypted shell-history sync, fuzzy Ctrl-R, and a SQLite history DB; a starship-shaped opt-in role whose interesting part is Bitwarden-backed sync across the fleet: design in roadmap/atuin.md (#56)
  • mise runtime/version manager (asdf successor) for node, python, etc.; could subsume the planned node (nvm) role into one tool (#57)
  • playwright maybe: the WSL→Windows CDP driving needs only the npm package, which the planned node role's npm globals can carry; a dedicated role earns its keep only if Linux browsers plus system deps (playwright install --with-deps) become fleet-level tooling (#58)
  • fzf fuzzy finder with shell key-bindings (Ctrl-T / Ctrl-R / Alt-C); pairs with atuin and zoxide (#59)
  • zoxide smarter cd that learns your most-used directories; a starship-shaped shell-hook role (#60)
  • bat / eza / delta modern cat / ls / git-diff-pager replacements; install + aliases (alias-pattern work), next to the ripgrep and fd the platform roles already install (#61)
  • direnv per-directory environment loading via a shell hook (#62)
  • jetbrains JetBrains Toolbox (manages PhpStorm/IntelliJ installs and updates itself); desktop-only, guard for WSL/headless (#63)

Bitwarden ​

  • Expand the two-sentence secrets answer in docs/faq.md (ansible-vault for vars, the bitwarden role for runtime lookups) into a guide; backs the Secrets row in docs/alternatives.md (#64)
  • Support encrypting secrets with ansible-vault (vaulted vars files, a vault-id) as the committed-to-repo path for local secrets, and document the other ways to get secrets into a play (environment, prompts, the bitwarden runtime lookups) alongside the vault approach (#65)

GitLab ​

  • Move glab credentials into the OS keyring, which the role declines today with --insecure-storage: glab keys entries glab:<hostname>:<key> and ignores GLAB_CONFIG_DIR, so accounts sharing a host would overwrite each other's token; needs per-account keying upstream, plus a Secret Service backend on Linux and WSL, where none is installed (#66)

Google Workspace ​

  • Add GAM, the de-facto third-party Workspace admin CLI, beside gws for admin at scale (users, groups, licenses), with the same per-shell account isolation as gws-account (#67)