Dotfiles

Recovery configuration for Taylor's macOS development environment.

The current snapshot was captured from an Apple Silicon Mac running macOS 15. It includes shell configuration, Git defaults, package manifests, VS Code settings, iTerm preferences, and curated macOS preferences. Credentials, software inventories, and device identity files are intentionally excluded.

Before the setup UI

The restore choices are presented with @clack/prompts. Clack needs Node.js 20.12.0 or newer, but it does not require Homebrew, full Xcode, or an Apple Developer account.

On a new Mac:

1. Finish macOS Setup Assistant, sign in to an administrator account, and connect to the internet.

2. Open Terminal and run:

   git --version

3. macOS opens the Command Line Tools installer. Choose Install, accept the Command Line Tools License Agreement, and wait for it to finish.

4. Clone this repository:

   mkdir -p ~/dev
   git clone https://github.com/tay1orjones/dotfiles.git ~/dev/dotfiles
   cd ~/dev/dotfiles

Apple's standalone Command Line Tools are sufficient. Full Xcode and its first-launch components are not required for this setup. When full Xcode is already selected but incomplete, setup prints the optional command needed before using Xcode build tools.

Interactive restore

Run:

./setup.sh

Before Clack starts, the Bash bootstrap:

1. Verifies macOS, an interactive terminal, and Apple Command Line Tools.
2. Uses an existing compatible Node.js, or installs NVM v0.40.6 with its script method and installs the current stable Node.js.
3. Runs npm ci --ignore-scripts using the pinned package-lock.json.
4. Starts the grouped Clack restore selector.

Every restore category can be selected independently:

• Homebrew and captured Homebrew formulae.
• Captured global npm tools.
• Oh My Zsh.
• Zsh/shell files, legacy Bash files, and personal Git settings.
• VS Code application, extensions, and settings as three separate choices.
• iTerm application and tracked preferences as separate choices.
• General, keyboard, trackpad, Magic Mouse, Dock/Finder, and screen-lock macOS preferences as separate choices.

VS Code extensions and settings are not part of the recommended initial selection. Leave them unchecked when VS Code Settings Sync will restore them.

The selector shows the resolved plan and any automatically added dependencies before asking for confirmation. Existing files are timestamped and backed up before symlinks replace them. Canceling or selecting nothing makes no restore changes.

Useful non-interactive checks:

npm run setup -- --list
npm run setup -- --dry-run --select=shell,git,vscode-app
npm run setup -- --dry-run --all

Capture the current Mac

Run the snapshot script before reviewing changes for publication:

./snapshot.sh
git status --short
git diff -- Brewfile npm/globals.txt vscode/extensions.txt \
  macos/current-preferences.tsv

The snapshot script captures:

• Explicit Homebrew formulae, global npm package names, VS Code extensions, application names, and Dock labels in ignored .snapshot-private review files.
• A curated set of pointer, keyboard, Dock, Finder, and screen-lock defaults.

Review the private candidates and manually update the public Brewfile, npm/globals.txt, and vscode/extensions.txt manifests. Application and Dock inventories remain private. This prevents a machine snapshot from automatically publishing employer-specific software or other identifying inventory.

The script does not export complete preference domains because they can contain account, device, recent-file, and application state. It also does not copy npm, GitHub, SSH, editor MCP, or cloud credentials.

VS Code settings are tracked in vscode/settings.json. Review the live file at ~/Library/Application Support/Code/User/settings.json before updating the tracked copy because extensions may place credentials there.

iTerm is configured to load portable preferences from extra. Its plist should be reviewed whenever iTerm writes new changes. Full application exports are not tracked because they can contain license values, account identifiers, or device state.

Pointer settings

The captured trackpad tracking speed is 2.5. Tap to click and three-finger drag are disabled, secondary click and Force Click are enabled, and click pressure is light.

The source Mac has no explicit com.apple.mouse.scaling value, so the mouse restore leaves external mouse tracking speed at the macOS default. Magic Mouse gesture and scrolling values are captured separately.

Credentials

The shell reads the Hue bridge host and API username from macOS Keychain. Add them without placing their values in shell history:

read -s HUE_BRIDGE_HOST
security add-generic-password -U -a "$USER" -s "Hue Bridge Host" -w "$HUE_BRIDGE_HOST"
unset HUE_BRIDGE_HOST

read -s HUE_API_USERNAME
security add-generic-password -U -a "$USER" -s "Hue API Username" -w "$HUE_API_USERNAME"
unset HUE_API_USERNAME

Never add these files to the repository:

• ~/.npmrc
• ~/.config/gh/hosts.yml
• SSH private keys
• VS Code mcp.json
• .env files or exported password-manager data

The previous Hue API username remains in the public Git history. Removing it from the current file does not revoke it or remove it from earlier commits. The credential must be rotated on the Hue bridge before separately rewriting the repository history.