macsetup 0.1.0__py3-none-any.whl

macsetup/__init__.py

@@ -0,0 +1 @@
+"""Declarative provisioning for macOS: packages and dotfiles, with a preview."""

macsetup/_data/files/git/gitconfig.j2

@@ -0,0 +1,17 @@
+# Managed by macsetup. Edits here are overwritten on the next `macsetup apply`;
+# the source is files/git/gitconfig.j2 in the manifests repo.
+#
+# Rendered on {{ machine }}.
+
+[user]
+	name = {{ git_name }}
+	email = {{ git_email }}
+
+[init]
+	defaultBranch = main
+
+# Refuse to invent an identity. Without this, an unset user.email makes git
+# silently guess you@<hostname>.local and stamp it on the commit -- a wrong
+# address you only discover later, in a published history.
+[user]
+	useConfigOnly = true

macsetup/_data/files/shell/zshrc-block.zsh

@@ -0,0 +1,6 @@
+# Sources every fragment macsetup has installed. Add a fragment by adding it to
+# a module manifest -- this block never needs to change.
+for _f in "$HOME"/.config/macsetup/zsh/*.zsh(N); do
+  [ -r "$_f" ] && source "$_f"
+done
+unset _f

macsetup/_data/files/zsh/00-homebrew.zsh

@@ -0,0 +1,10 @@
+# HOMEBREW_PREFIX, without shelling out to `brew --prefix` on every startup.
+# `brew shellenv` would set this, but it costs a subprocess and PATH is already
+# handled by /etc/paths.d, so just resolve the two possible locations.
+if [[ -z ${HOMEBREW_PREFIX} ]]; then
+  if [[ -x /opt/homebrew/bin/brew ]]; then
+    export HOMEBREW_PREFIX=/opt/homebrew      # Apple Silicon
+  elif [[ -x /usr/local/bin/brew ]]; then
+    export HOMEBREW_PREFIX=/usr/local         # Intel
+  fi
+fi

macsetup/_data/files/zsh/10-completion.zsh

@@ -0,0 +1,22 @@
+# zsh completion. Must run before any fragment that calls compdef -- tool
+# completion scripts fail with "command not found: compdef" otherwise.
+#
+# Homebrew drops completions in share/zsh/site-functions (_brew, _git, _gh,
+# _docker, _uv, _uvx, _wezterm, _zed, _aws), so adding it to fpath is all that
+# is needed; no per-tool `eval` at startup.
+if [[ -n ${HOMEBREW_PREFIX} && -d ${HOMEBREW_PREFIX}/share/zsh/site-functions ]]; then
+  fpath=("${HOMEBREW_PREFIX}/share/zsh/site-functions" $fpath)
+fi
+
+autoload -Uz compinit
+
+# compinit's security audit is slow, so run it in full at most once a day and
+# use the cached dump otherwise. -i skips the prompt about Homebrew's
+# group-writable directories, which are expected rather than suspicious.
+_ms_zcompdump="${ZDOTDIR:-$HOME}/.zcompdump"
+if [[ -n ${_ms_zcompdump}(#qN.mh+24) ]]; then
+  compinit -i -d "${_ms_zcompdump}"
+else
+  compinit -C -i -d "${_ms_zcompdump}"
+fi
+unset _ms_zcompdump

macsetup/_data/files/zsh/cli.zsh

@@ -0,0 +1,18 @@
+# The two `cli` tools that need shell wiring rather than just a binary on PATH.
+#
+# Installed as 90-cli.zsh so zoxide initialises after every other fragment:
+# zoxide's own doctor check wants its init at the end of the shell config, and
+# it says so on stderr when it is not. The gap to 40-p10k leaves room for
+# fragments that have to load earlier.
+
+# `always` rather than the default `auto`, which drops the icons as soon as the
+# output is not a terminal -- `ls | less` should still show them. The glyphs come
+# from the Nerd Font, which is why the cli module requires the fonts module.
+alias ls="eza --icons=always"
+
+# zoxide tracks visited directories and jumps to a match on a partial name.
+# Aliasing cd to z keeps `cd some/real/path` working, since z falls back to a
+# plain cd when the argument resolves to a real directory. `zi` still opens the
+# interactive picker.
+eval "$(zoxide init zsh)"
+alias cd="z"

macsetup/_data/files/zsh/node.zsh

@@ -0,0 +1,8 @@
+# Node — nvm, installed via Homebrew. HOMEBREW_PREFIX comes from
+# 00-homebrew.zsh; the literal fallback keeps this fragment usable standalone.
+export NVM_DIR="$HOME/.nvm"
+
+_ms_nvm="${HOMEBREW_PREFIX:-/opt/homebrew}/opt/nvm"
+[ -s "$_ms_nvm/nvm.sh" ] && \. "$_ms_nvm/nvm.sh"
+[ -s "$_ms_nvm/etc/bash_completion.d/nvm" ] && \. "$_ms_nvm/etc/bash_completion.d/nvm"
+unset _ms_nvm

macsetup/_data/files/zsh/python.zsh

@@ -0,0 +1,12 @@
+# Python — uv only. pyenv and poetry were dropped on 2026-07-26.
+#
+# No completion setup here: Homebrew already installs _uv and _uvx into
+# site-functions, which 10-completion.zsh puts on fpath. Calling
+# `uv generate-shell-completion` at startup would duplicate that and cost two
+# subprocesses per shell.
+
+# `uv tool install` puts shims here.
+export PATH="$HOME/.local/bin:$PATH"
+
+# Prefer uv's managed interpreters over whatever the system ships.
+export UV_PYTHON_PREFERENCE=managed

macsetup/_data/manifests/modules/cli.yaml

@@ -0,0 +1,16 @@
+id: cli
+name: CLI tools
+description: Terminal utilities
+# eza renders Nerd Font glyphs, so the font is a hard dependency rather than
+# something the wizard could leave unticked. Anything with hard dependencies
+# belongs in its own module for exactly this reason.
+requires: [fonts]
+packages:
+  - tree
+  - ripgrep
+  - eza
+  - zoxide
+files:
+  # 90 so zoxide's init is the last fragment to run; see the file.
+  - copy: zsh/cli.zsh
+    to: ~/.config/macsetup/zsh/90-cli.zsh

macsetup/_data/manifests/modules/core.yaml

@@ -0,0 +1,7 @@
+id: core
+name: Core
+description: Installed on every machine, no questions asked
+always: true
+packages:
+  - git
+  - gh

macsetup/_data/manifests/modules/editors.yaml

@@ -0,0 +1,16 @@
+id: editors
+name: Editors & IDEs
+description: Pick the ones this machine needs
+# `select: pick` turns this into a per-package menu in the wizard, with
+# `default:` pre-ticked.
+#
+# Picks gate packages, not files: a module's `files` are applied whenever the
+# module is selected, whichever packages you tick. So anything that ships
+# config cannot live as a pick -- its config would land on machines that
+# unticked it. Give those their own module instead.
+select: pick
+default: [visual-studio-code]
+packages:
+  - {name: visual-studio-code, cask: true}
+  - {name: zed, cask: true}
+  - {name: jetbrains-toolbox, cask: true}

macsetup/_data/manifests/modules/fonts.yaml

@@ -0,0 +1,5 @@
+id: fonts
+name: Fonts
+description: Nerd Fonts, pulled in by anything that renders glyphs
+packages:
+  - {name: font-meslo-lg-nerd-font, cask: true}

macsetup/_data/manifests/modules/git-identity.yaml

@@ -0,0 +1,15 @@
+id: git-identity
+name: Git identity
+description: A rendered gitconfig, as a demonstration of `render:`
+# Rendered rather than copied: identity is the one part that may differ per
+# machine. Override git_name / git_email in the [vars] table of machine.toml;
+# the catalog defaults are in manifests/vars.yaml.
+#
+# The destination is deliberately inert. This is the catalog that ships inside
+# the wheel, so `macsetup init` on a machine that has not written its own
+# manifests yet will run it -- and an example that overwrites a real
+# ~/.gitconfig on first run is a trap, not a demonstration. Point this at
+# ~/.gitconfig in your own catalog, once you mean it.
+files:
+  - render: git/gitconfig.j2
+    to: ~/.config/macsetup/example-gitconfig

macsetup/_data/manifests/modules/lang-node.yaml

@@ -0,0 +1,8 @@
+id: lang-node
+name: Node
+description: nvm, so a project can pin its own version
+packages:
+  - nvm
+files:
+  - copy: zsh/node.zsh
+    to: ~/.config/macsetup/zsh/30-node.zsh

macsetup/_data/manifests/modules/lang-python.yaml

@@ -0,0 +1,8 @@
+id: lang-python
+name: Python
+description: uv, and nothing else -- it supplies its own interpreters
+packages:
+  - uv
+files:
+  - copy: zsh/python.zsh
+    to: ~/.config/macsetup/zsh/20-python.zsh

macsetup/_data/manifests/modules/shell.yaml

@@ -0,0 +1,18 @@
+id: shell
+name: Shell
+description: The managed ~/.zshrc block, Homebrew prefix and zsh completion
+always: true
+# No packages: this module exists purely to place files. `apply --only shell`
+# therefore never invokes brew, which makes it the safest module to try
+# against a sandboxed HOME.
+files:
+  # One managed block in a file macsetup does not own. Lines outside the
+  # markers are left alone; re-applying rewrites only between them.
+  - block: shell/zshrc-block.zsh
+    into: ~/.zshrc
+  # Numbered so they load before the tool fragments: completion must be
+  # initialised before anything calls compdef.
+  - copy: zsh/00-homebrew.zsh
+    to: ~/.config/macsetup/zsh/00-homebrew.zsh
+  - copy: zsh/10-completion.zsh
+    to: ~/.config/macsetup/zsh/10-completion.zsh

macsetup/_data/manifests/profiles.yaml

@@ -0,0 +1,26 @@
+# Profiles bundle modules. Modules marked `always: true` are folded in
+# automatically and do not need listing here.
+#
+# These are an example. Replace them with the way you actually use your
+# machines -- `brew bundle dump` on each one and diffing the results is a
+# good way to turn guesswork into data.
+profiles:
+  work:
+    - cli
+    - git-identity
+    - lang-python
+    - lang-node
+    - editors
+
+  personal:
+    - cli
+    - git-identity
+    - lang-python
+    - editors
+
+  # A loaner or travel machine: enough to be useful in a terminal, nothing else.
+  minimal:
+    - cli
+
+  full:
+    - "*"

macsetup/_data/manifests/vars.yaml

@@ -0,0 +1,10 @@
+# Default values for `render:` template variables. The engine ships none of
+# its own -- identity is data, so it lives here with the manifests that use
+# it. A machine overrides any of these in the [vars] table of
+# ~/.config/macsetup/machine.toml.
+#
+# Rendering uses StrictUndefined: a template referencing a variable with no
+# value is a hard error, not a silently empty setting.
+vars:
+  git_name: Your Name
+  git_email: you@example.com

macsetup/brewfile.py

@@ -0,0 +1,59 @@
+"""Brewfile generation and the `brew bundle` driver.
+
+macsetup does not install anything itself. It decides *what* should be
+installed and hands a generated Brewfile to Homebrew's bundler, which already
+knows about retries, cask quarantine, sudo prompts and upgrade semantics.
+
+Generated files are written to a predictable cache dir and deliberately left
+behind after a run, so a failure can be inspected.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from pathlib import Path
+
+from .manifest import Package
+from .runner import Runner
+
+CACHE_DIR = Path.home() / ".cache" / "macsetup" / "brewfiles"
+
+
+def render(packages: Iterable[Package], *, header: str | None = None) -> str:
+    lines: list[str] = []
+    if header:
+        lines += [f"# {header}", "# generated by macsetup -- edits will be overwritten", ""]
+    # Taps and formulae before casks; brew bundle is order-insensitive but this
+    # reads far better when you open the file to debug something.
+    packages = list(packages)
+    lines += [p.brewfile_line() for p in packages if not p.cask and p.mas is None]
+    lines += [p.brewfile_line() for p in packages if p.cask]
+    lines += [p.brewfile_line() for p in packages if p.mas is not None]
+    return "\n".join(lines) + "\n"
+
+
+def write(module_id: str, packages: Iterable[Package], *, cache_dir: Path | None = None) -> Path:
+    directory = cache_dir or CACHE_DIR
+    directory.mkdir(parents=True, exist_ok=True)
+    path = directory / f"{module_id}.Brewfile"
+    path.write_text(render(packages, header=f"module: {module_id}"), encoding="utf-8")
+    return path
+
+
+def install(runner: Runner, brewfile: Path, *, upgrade: bool = False, jobs: int | None = None):
+    """Run `brew bundle install` against a generated Brewfile.
+
+    Homebrew upgrades outdated dependencies by default, which is wrong for
+    convergence -- adding one package should not turn into a 40 minute upgrade
+    of everything. So `--no-upgrade` unless explicitly asked.
+    """
+    cmd = ["brew", "bundle", "install", f"--file={brewfile}"]
+    if not upgrade:
+        cmd.append("--no-upgrade")
+    if jobs:
+        cmd.append(f"--jobs={jobs}")
+    return runner.run(cmd, capture=False)
+
+
+def check(runner: Runner, brewfile: Path):
+    return runner.run(["brew", "bundle", "check", f"--file={brewfile}"])