Implement dotfiles CLI

[virtualian]

Summary

Build @virtualian/dotfiles-cli — a TypeScript + Bun CLI that syncs shell and application configuration across machines using a bare git repository. Replaces the previous Bash script approach with a cross-platform npm package.

Technique origin: StreakyCobra on Hacker News (2016), popularized by Atlassian's Git tutorial

Architecture

@virtualian/dotfiles-cli
  src/
    cli.ts              ← entry point + dispatcher
    commands/
      init.ts
      sync.ts
      audit.ts
      bootstrap.ts
      add.ts
      ls.ts
      help.ts
    git.ts              ← git wrapper (--git-dir, --work-tree)
  bin/
    dotfiles            ← shim: #!/usr/bin/env bun
  package.json

Pass-through dispatcher: known subcommands are handled in src/commands/, everything else forwards to git --git-dir=$HOME/.dotfiles/ --work-tree=$HOME. All git commands work — unknown input goes straight through.

~/.dotfiles/      ← bare git repo (history only, no working tree)
$HOME             ← working tree (where actual config files live)

Custom Commands

Command	What It Does
dotfiles help	Show all commands
dotfiles init	Create bare repo at ~/.dotfiles with default ignore rules
dotfiles sync [message]	Stage tracked changes + commit + push. Default message: sync YYYY-MM-DD
dotfiles ls	List all tracked files
dotfiles audit	Scan tracked files for secrets (private keys, .env, API tokens)
dotfiles bootstrap <repo-url>	Full new-machine setup: clone, backup conflicts, checkout, configure
dotfiles add <path>	Add file to tracking (warns on directories, shows dry-run first)

Git Pass-Through

Every git command works as you'd expect — the CLI forwards anything it doesn't recognize:

dotfiles status          # → git status
dotfiles diff            # → git diff
dotfiles log --oneline   # → git log --oneline
dotfiles stash           # → git stash
dotfiles branch -a       # → git branch -a

Technical Details

• Language: TypeScript + Bun (not Bash — cross-platform, testable, proper error handling)
• Runtime: Bun (~25ms startup, built-in testing via bun test)
• Git calls: Bun.$ for shell execution (quiet mode for capturing, passthrough for interactive)
• Ignore rules: $GIT_DIR/info/exclude (avoids polluting $HOME with .gitignore)
• Directory add protection: dotfiles add <dir> shows dry-run preview via git add -n, requires confirmation
• Audit: File-level patterns (.pem, .key, .env) + content-level regex (api_key=, secret:, token=, password=)

Sensitive Data Protection

Three layers:

1. Default ignore rules — dotfiles init configures exclusions for private keys, .env files, known sensitive paths
2. Directory warnings — dotfiles add <dir> shows dry-run preview, asks for confirmation
3. Audit command — dotfiles audit scans tracked files for secrets, returns non-zero if found

Distribution

# npm registry (primary)
bun add -g @virtualian/dotfiles-cli

# Standalone binary (no runtime needed)
bun build --compile --target=bun-darwin-arm64 src/cli.ts --outfile dotfiles-macos
bun build --compile --target=bun-linux-x64 src/cli.ts --outfile dotfiles-linux

# Direct from repo
bun install -g github:virtualian/dotfiles-cli

Acceptance Criteria

• dotfiles help shows all custom and pass-through commands
• dotfiles init creates bare repo at ~/.dotfiles with default ignore rules
• dotfiles init sets status.showUntrackedFiles no
• dotfiles sync stages tracked changes, commits, and pushes in one command
• dotfiles sync "custom msg" uses custom commit message
• dotfiles sync with no changes prints clean message, exits 0
• dotfiles ls lists tracked files
• dotfiles audit detects secret files, returns non-zero
• dotfiles audit passes on clean repo
• dotfiles add <dir> warns and shows dry-run before proceeding
• dotfiles add <file> works without prompting
• dotfiles bootstrap <url> clones, backs up conflicts, checks out, configures
• dotfiles bootstrap with existing ~/.dotfiles fails with clear error
• All unknown subcommands pass through to git correctly
• dotfiles status, dotfiles log, dotfiles diff all work
• Published to npm as @virtualian/dotfiles-cli
• bun test passes all tests
• No dependencies beyond Bun + git

Reference

Full design document: Plans/dotfiles-bare-repo-guide.md

[virtualian]

Update: Smart Diff + Interactive Merge (4d30449)

dotfiles diff promoted from git pass-through to custom command:

Smart diff (no args):

• Auto-fetches remote silently
• Three-section display: Local Changes, Incoming (remote → local), Diverged (both changed)
• Color output with summary line
• Graceful offline handling

Interactive merge for diverged files:

• Per-file resolution: keep local / keep remote / manual merge / skip
• Shows actual diff content for each diverged file
• Backs up originals to ~/.dotfiles-backup-resolve-TIMESTAMP/
• Commit prompt after resolution

Pass-through preserved: dotfiles diff <any-args> still forwards to git.

New architecture entry: src/commands/diff.ts

Additional acceptance criteria:

• dotfiles diff (no args) fetches remote and shows 3-section summary
• dotfiles diff offline shows local changes with warning
• dotfiles diff --cached passes through to git (no fetch)
• Diverged files prompt interactive resolution
• Resolution backs up originals before any changes
• dotfiles diff with no changes prints "Everything in sync."

[virtualian]

Update: Init file proposal + Merge command (68f8ac0)

dotfiles init redesigned:

• Scans for common dotfiles (~/.zshrc, ~/.gitconfig, ~/.ssh/config, ~/.claude/*, etc.)
• Presents interactive checklist — found files pre-selected, missing files shown as (not found)
• Commits selected files as "Initial dotfiles"
• Prompts for remote URL (optional)
• Quick Start reduced from 14 lines to 2 commands

dotfiles merge — new standalone command:

• Extracted from dotfiles diff (diff is now purely read-only)
• Only operates on diverged (conflicting) files
• Interactive per-file resolution: keep local / keep remote / manual merge / skip / quit
• Backs up originals to ~/.dotfiles-backup-resolve-TIMESTAMP/ before any changes
• Prompts to commit resolved files

Additional acceptance criteria:

• dotfiles init scans and proposes common dotfiles
• dotfiles init pre-selects found files, shows (not found) for missing
• dotfiles init commits selected files and prompts for remote
• dotfiles merge with no conflicts prints "Nothing to merge"
• dotfiles merge walks through diverged files interactively
• dotfiles merge backs up originals before resolution
• dotfiles diff no longer prompts for merge (hints only)