Skip to content

First-time setup on a new Mac leaves no broken links or deprecated steps #127

Open

Description

@ooloth

Current state

First-time setup on a new Mac creates broken links and runs scripts the repo has marked deprecated. features/setup/setup.zsh sources the zsh scripts in features/install/zsh/, eight of them from deprecated/ (lines 111, 113 to 118 and 120). One of those, deprecated/symlinks.zsh, links eight sources that no longer exist: tools/claude/config/commands, four k9s files, tools/tmux/config/battery.sh and two terminfo files. features/update/symlinks.bash is the maintained path, which sweeps broken links and then runs every link.bash (lines 16 to 34).

u also reports a failure on a fresh machine until tmux's install has run. tools/tmux/update.bash:11 calls "${TPM}/clean_plugins" with no check that tpm is there, and only tools/tmux/install.bash (lines 9 to 12) clones tpm, so the tmux update fails and u lists tmux among its failed updates.

Checked 2026-10-25

Ideal state

  • One setup script, run once on a fresh Mac, replaces features/setup/setup.zsh: it checks that it is on a Mac, keeps sudo alive, clones the dotfiles, runs each tool's install.bash in an explicit priority order, and then runs u
  • Setup creates its links by running features/update/symlinks.bash, so it leaves no broken links
  • u stays the command run regularly, and can be run again at any time: each tool's update.bash installs the tool if it is missing, then updates it
  • On a fresh machine, u installs rust, uv, node and tmux through their update.bash when they are missing, so none of them needs an install.bash for that
  • A tool has an install.bash only for a one-time side effect: tools/ssh generates SSH keys, tools/github registers the key with GitHub, verifies auth and switches the dotfiles remote from HTTPS to SSH, tools/zsh sets Homebrew zsh as the default shell, tools/content clones the personal content repo, and tools/macos applies macOS settings
  • tools/github/ holds its Brewfile, config link and shell aliases
  • The SSH key and GitHub auth logic worth keeping from tools/ssh/wip/ and tools/github/wip/ lives in those tools' install.bash
  • No wip/ folder remains in tools/git, tools/github, tools/obsidian, tools/ssh, tools/tmux, tools/uv, tools/zsh or features/setup
  • features/setup/setup.zsh and features/install/zsh/ no longer exist

Decisions

Constraints

Open

Starting points

  • features/setup/setup.zsh: today's setup, and the order it runs each step in
  • features/update/symlinks.bash: the maintained link step setup should call
  • features/update/tools.bash: u, which setup runs last

Activity

  1. changed the title [-]migrate setup.zsh to setup.bash using tools/x/bootstrap.bash pattern[/-] [+]migrate setup.zsh to setup.bash using tools/x/install.bash pattern[/+] on Apr 21, 2026
  2. added
    maintenanceUpkeep that changes how the repo is built, not what it does
    on Oct 6, 2026
  3. ooloth commented on Oct 18, 2026

    @ooloth
    OwnerAuthor

    features/install/zsh/deprecated/symlinks.zsh, which setup.zsh still sources, links 8 sources that no longer exist (tools/claude/config/commands, four k9s files, tools/tmux/config/battery.sh and two terminfo files), so first-time setup creates broken links today. features/update/symlinks.bash is the maintained path: it runs every link.bash and sweeps broken links, so the migration can call it instead of porting symlinks.zsh.

  4. changed the title [-]migrate setup.zsh to setup.bash using tools/x/install.bash pattern[/-] [+]First-time setup on a new Mac leaves no broken links or deprecated steps[/+] on Oct 25, 2026
  5. ooloth commented on Oct 26, 2026

    @ooloth
    OwnerAuthor

    scripts/checks/linting.bash now runs bash -n tools/zsh/utils.zsh (a833d68). The only reason utils.zsh has to parse as bash is that features/setup/wip/setup.bash sources it, so that step should be removed in the same change that deletes features/setup/wip/, along with its line in CONTRIBUTING.md and the "zsh utils" line in the comment at the top of linting.bash. Under decision 007 the replacement setup script is Python, so nothing else needs utils.zsh to stay parseable as bash. Before deleting the check, run grep -rn 'zsh/utils.zsh' --include='*.bash' --include='*.sh' . to confirm nothing else sources it. Only a comment in tools/homebrew/update.bash should still mention it.

  6. ooloth commented on Oct 31, 2026

    @ooloth
    OwnerAuthor

    First-time setup needs a step for private.env (#230). A fresh Mac has none, so each new shell warns that it is missing, and check fails in its private values step until it exists. Setup can't create the file, because its values exist only on the other Macs. So the step tells the person to copy private.env.example to ~/Repos/ooloth/dotfiles/private.env, fill in the keys whose # machines: line names this Mac, and chmod 600 it. On the work laptop it has to exist before uv is installed, because tools/uv/install.bash stops without PRIVATE_UV_INSTALLER_URL.

  7. ooloth commented on Nov 5, 2026

    @ooloth
    OwnerAuthor

    Setup now has a second kind of machine-local value to restore. Tokens belong in the login Keychain, not private.env (docs/standards/secrets.md, private.env.example), and the login Keychain does not sync between Macs. So a fresh Mac also needs a secret add step for each stored secret, such as jira-cli (with --account) and codefresh.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    maintenanceUpkeep that changes how the repo is built, not what it does

    Projects

    No projects

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions