macsetup 0.1.0__tar.gz

macsetup-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,131 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+  workflow_call: # release.yml runs the full suite before publishing
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  # Everything that does not need a Mac. Fast, and the job that gates a PR.
+  lint-and-test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      # Pinned to an exact tag on purpose: setup-uv published floating major
+      # tags up to v6 and then stopped, so `@v10` is not a resolvable ref even
+      # though v10.3.2 is the current release. Bump this deliberately.
+      - uses: astral-sh/setup-uv@v10.3.2
+        with:
+          enable-cache: true
+
+      # --locked rather than plain sync: a pyproject edit that was never
+      # reflected in uv.lock should fail here, not drift silently.
+      - run: uv sync --locked
+
+      - run: uv run ruff check .
+      - run: uv run ruff format --check .
+      - run: uv run pytest -q
+      - run: shellcheck install.sh
+
+      # The suite loads the catalog and resolves every profile, so a YAML typo
+      # or a dangling `requires:` already fails above. This covers the other
+      # packaging invariant: manifests/ and files/ are force-included into the
+      # wheel as _data/, and without them `uv tool install macsetup` installs
+      # an engine with nothing to run against.
+      - name: the wheel carries the example catalog
+        run: |
+          uv build --wheel
+          for want in \
+            macsetup/_data/manifests/profiles.yaml \
+            macsetup/_data/manifests/vars.yaml \
+            macsetup/_data/manifests/modules/core.yaml \
+            macsetup/_data/files/shell/zshrc-block.zsh \
+            macsetup/_data/files/git/gitconfig.j2; do
+            if ! unzip -l dist/*.whl | grep -q "$want"; then
+              echo "::error file=pyproject.toml::$want is missing from the wheel"
+              exit 1
+            fi
+          done
+          echo "wheel contains the catalog"
+
+  # plan and apply shell out to `brew list`, so these need a runner that has
+  # Homebrew. This is the end-to-end pass: detect, plan, Brewfile generation
+  # and the file appliers, against a real brew rather than FakeRunner.
+  catalog:
+    runs-on: macos-latest
+    steps:
+      - uses: actions/checkout@v7
+      # Pinned to an exact tag on purpose: setup-uv published floating major
+      # tags up to v6 and then stopped, so `@v10` is not a resolvable ref even
+      # though v10.3.2 is the current release. Bump this deliberately.
+      - uses: astral-sh/setup-uv@v10.3.2
+        with:
+          enable-cache: true
+      - run: uv sync --locked
+
+      - name: the catalog loads
+        run: uv run macsetup modules
+
+      # No machine.toml exists on a runner, so every profile is exercised
+      # through the --profile path with picks falling back to their defaults.
+      - name: every profile plans and dry-runs
+        run: |
+          profiles=$(uv run python -c \
+            "import yaml;print(' '.join(yaml.safe_load(open('manifests/profiles.yaml'))['profiles']))")
+          echo "profiles: $profiles"
+          for p in $profiles; do
+            echo "::group::$p"
+            uv run macsetup plan --profile "$p"
+            uv run macsetup apply --profile "$p" --dry-run --yes
+            echo "::endgroup::"
+          done
+
+      - name: brewfiles generate
+        run: uv run macsetup plan --profile full --show-brewfile
+
+      - name: status and untracked run against a real machine
+        run: |
+          uv run macsetup status --profile minimal
+          uv run macsetup untracked --profile minimal
+
+      # The file appliers for real, against a throwaway HOME. `shell` has no
+      # packages, so brew is never invoked and nothing on the runner changes.
+      - name: file actions apply in a sandbox
+        run: |
+          sb=$(mktemp -d)
+          HOME="$sb" MACSETUP_CONFIG="$sb/.config" \
+            uv run macsetup apply --only shell --only git-identity --yes
+          test -f "$sb/.zshrc"
+          test -f "$sb/.config/macsetup/zsh/00-homebrew.zsh"
+          test -f "$sb/.config/macsetup/zsh/10-completion.zsh"
+          test -f "$sb/.config/macsetup/example-gitconfig"
+          # vars.yaml supplies the defaults now that the engine ships none
+          grep -q 'you@example.com' "$sb/.config/macsetup/example-gitconfig"
+          grep -q '>>> macsetup >>>' "$sb/.zshrc"
+          echo "file actions verified"
+
+      # The one-line installer, piped the way the README shows it, against a
+      # throwaway HOME. The runner already has brew and uv, so this covers the
+      # macsetup install and the hand-off; running it twice proves re-runs work.
+      - name: install.sh bootstraps and re-runs
+        run: |
+          sb=$(mktemp -d)
+          for run in 1 2; do
+            HOME="$sb" MACSETUP_SOURCE="$PWD" bash -s -- plan --profile minimal < install.sh
+          done
+          test -x "$sb/.local/bin/macsetup"
+
+      # Re-applying a converged machine must be a no-op, not a second write.
+      - name: applying twice is idempotent
+        run: |
+          sb=$(mktemp -d)
+          export HOME="$sb" MACSETUP_CONFIG="$sb/.config"
+          uv run macsetup apply --only shell --yes >/dev/null
+          uv run macsetup apply --only shell --yes | tee /tmp/second.txt
+          grep -q 'Nothing to do' /tmp/second.txt

macsetup-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,55 @@
+name: Release
+
+# Pushing a tag like v0.2.0 publishes that version to PyPI. Bump `version` in
+# pyproject.toml first; the tag has to match it or nothing is published.
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  # The full CI run, Linux and macOS, gates the upload: a tag on a commit that
+  # never passed CI should not reach PyPI.
+  ci:
+    uses: ./.github/workflows/ci.yml
+
+  build:
+    needs: ci
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      # Pinned to an exact tag on purpose; see the note in ci.yml.
+      - uses: astral-sh/setup-uv@v10.3.2
+
+      # PyPI versions are permanent -- a mismatch caught here costs a re-tag,
+      # one caught after upload costs a version number.
+      - name: tag matches pyproject version
+        run: |
+          version=$(uv version --short)
+          if [ "v$version" != "$GITHUB_REF_NAME" ]; then
+            echo "::error file=pyproject.toml::tag $GITHUB_REF_NAME but pyproject says $version"
+            exit 1
+          fi
+
+      - run: uv build
+      - uses: actions/upload-artifact@v7
+        with:
+          name: dist
+          path: dist/
+
+  # Separate from build so the OIDC token that can publish never shares a job
+  # with the build. Trusted publishing: no API token is stored anywhere, PyPI
+  # trusts this workflow + environment directly.
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/macsetup/
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

macsetup-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+.venv/
+.pytest_cache/
+.ruff_cache/
+__pycache__/
+*.pyc
+dist/

macsetup-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sergio Infante
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

macsetup-0.1.0/PKG-INFO

@@ -0,0 +1,255 @@
+Metadata-Version: 2.5
+Name: macsetup
+Version: 0.1.0
+Summary: Declarative provisioning for macOS: packages and dotfiles, with a preview
+Project-URL: Homepage, https://github.com/neosergio/macsetup
+Project-URL: Issues, https://github.com/neosergio/macsetup/issues
+License-Expression: MIT
+License-File: LICENSE
+Keywords: brew-bundle,dotfiles,homebrew,macos,provisioning
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS :: MacOS X
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: System :: Installation/Setup
+Requires-Python: >=3.12
+Requires-Dist: jinja2>=3.1.6
+Requires-Dist: pydantic>=2.9
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: questionary>=2.1.1
+Requires-Dist: rich>=13.7
+Requires-Dist: tomli-w>=1.0
+Requires-Dist: typer>=0.15
+Description-Content-Type: text/markdown
+
+# macsetup
+
+[![CI](https://github.com/neosergio/macsetup/actions/workflows/ci.yml/badge.svg)](https://github.com/neosergio/macsetup/actions/workflows/ci.yml)
+
+Declarative provisioning for macOS. Describe what a machine should have in
+YAML; `macsetup plan` shows you the difference against reality, and
+`macsetup apply` closes it.
+
+```
+$ macsetup plan
+┏━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━┓
+┃ Module       ┃ Package                      ┃ State     ┃
+┡━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━┩
+│ core         │ git, gh                      │ satisfied │
+│ cli          │ ripgrep                      │ install   │
+│ cli          │ ~/.config/macsetup/zsh/90-…  │ update    │
+│ lang-python  │ uv                           │ satisfied │
+└──────────────┴──────────────────────────────┴───────────┘
+1 to install, 1 file to update, 6 satisfied
+```
+
+Adding software is a YAML edit, never a code change. Re-running on a converged
+machine is a no-op, and `plan` and `apply` share the same planner, so the
+preview is exactly what apply acts on.
+
+Built for the case where you have **several** Macs that should share an
+environment without every machine getting every package.
+
+## Install
+
+One line, on a Mac with nothing on it yet:
+
+```sh
+/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/neosergio/macsetup/main/install.sh)"
+```
+
+[`install.sh`](install.sh) installs Homebrew if it is missing, then uv, then
+macsetup, and ends in the `init` wizard. Each step checks first, so it is safe
+to re-run. Arguments replace the wizard, for unattended machines:
+
+```sh
+curl -fsSL https://raw.githubusercontent.com/neosergio/macsetup/main/install.sh \
+  | bash -s -- apply --profile work --yes
+```
+
+If you already have Homebrew, the manual route is three commands:
+
+```sh
+brew install uv
+uv tool install macsetup
+macsetup init
+```
+
+`init` runs a wizard (machine name → profile → per-module choices), saves the
+result to `~/.config/macsetup/machine.toml`, and applies it. After that no
+flags are needed.
+
+```sh
+macsetup plan        # what apply would do; changes nothing
+macsetup apply       # do it
+macsetup status      # drift: manifest vs this machine
+macsetup untracked   # installed packages no selected module accounts for
+macsetup modules     # the whole catalog and its profiles
+```
+
+Every wizard answer has a flag equivalent, so a machine can be provisioned
+unattended: `macsetup apply --profile work --yes`.
+
+## Your own catalog
+
+macsetup ships a small example catalog so a fresh install has something to run
+against. It is an example — replace it with yours:
+
+```sh
+export MACSETUP_MANIFESTS=~/dotfiles/manifests
+export MACSETUP_FILES=~/dotfiles/files
+```
+
+Both are resolved in that order: the environment variable, then a `manifests/`
+or `files/` directory in the current working directory, then the copy baked
+into the wheel. Keeping your catalog in a private repo and the engine public
+is the intended arrangement.
+
+### Modules
+
+One file per module in `manifests/modules/`, where `id` matches the filename
+stem:
+
+```yaml
+id: cli
+name: CLI tools
+requires: [fonts]          # dependency-closed at resolve time
+packages:
+  - ripgrep                          # formula
+  - {name: ghostty, cask: true}      # cask
+files:
+  - copy: zsh/cli.zsh
+    to: ~/.config/macsetup/zsh/90-cli.zsh
+```
+
+**Casks must be marked explicitly.** Several names exist in both namespaces —
+`docker` is the CLI formula *and* Docker Desktop the cask — and a bare
+`brew install docker` silently picks the formula. Marking casks is the single
+biggest class of bug the manifest format exists to prevent.
+
+`always: true` puts a module on every machine regardless of profile.
+`select: pick` turns a module into a per-package menu in the wizard, with
+`default:` pre-ticked. Pydantic forbids unknown keys, so a typo fails at load
+rather than halfway through an install.
+
+### Profiles
+
+`manifests/profiles.yaml` bundles modules into named sets; `"*"` means
+everything.
+
+```yaml
+profiles:
+  work: [cli, lang-python, editors]
+  minimal: [cli]
+  full: ["*"]
+```
+
+`machine.toml` stores the **resolved module list**, not just the profile name,
+so a module added to a profile upstream cannot silently install itself on
+every machine the next time they sync. `status` reports unadopted modules;
+`configure` adopts them.
+
+### Files
+
+Three actions:
+
+```yaml
+files:
+  - copy: zsh/python.zsh                        # verbatim
+    to: ~/.config/macsetup/zsh/20-python.zsh
+  - render: git/gitconfig.j2                    # Jinja2 + machine vars
+    to: ~/.gitconfig
+    mode: "600"
+  - block: shell/zshrc-block.zsh                # region in a file you don't own
+    into: ~/.zshrc
+    position: top                               # default bottom
+```
+
+`block:` maintains a marker-delimited region. Lines outside the markers are
+preserved; re-applying rewrites only what's between them. `position: top`
+exists because some formats are order-sensitive — an `Include` in `ssh_config`
+is ignored if it lands after a matching block.
+
+`render:` substitutes variables from `manifests/vars.yaml`, overridden per
+machine by the `[vars]` table in `machine.toml`, plus `machine` and `home`
+which are always supplied. Rendering uses `StrictUndefined`: a template
+referencing a variable with no value is a hard error, not a silently empty
+setting.
+
+Before overwriting a file it did not create, `copy`/`render` leave a
+`.macsetup-bak` copy alongside it.
+
+**Nothing is symlinked.** A symlink would point into the installed wheel and
+break on the next upgrade, so files are copied and you re-run `apply` after
+editing a fragment.
+
+## Design notes
+
+A few decisions that are load-bearing, in case you're reading the source:
+
+**Data is separate from code.** `manifests/` says what to install;
+`src/macsetup/` only knows how. If adding software requires touching Python,
+something is wrong.
+
+**`brew list` runs exactly twice per invocation**, cached in `detect.py` —
+never once per package. Checking 60 packages costs two subprocess calls, so a
+converged machine plans in well under a second regardless of catalog size.
+There is a test asserting the call count.
+
+**Installs delegate to `brew bundle`** against a generated Brewfile rather than
+shelling out per package. Homebrew already knows about retries, cask
+quarantine and sudo prompts. Generated Brewfiles stay in
+`~/.cache/macsetup/brewfiles/` so a failure can be inspected.
+
+**`apply` never upgrades.** `brew bundle install` upgrades by default; macsetup
+passes `--no-upgrade` so converging a machine cannot turn into a 40-minute
+upgrade run. `--upgrade` is opt-in.
+
+**Subprocess calls go through `runner.py`.** That protocol is the test seam —
+the suite runs without touching the machine.
+
+## Development
+
+```sh
+uv sync
+uv run macsetup plan -p work
+uv run pytest                 # no machine access required
+uv run ruff check . && uv run ruff format .
+uv tool install -e .          # put `macsetup` on PATH, tracking this checkout
+```
+
+Tests never mutate the machine: `FakeRunner` stands in for subprocesses, and
+file steps run against a sandboxed `HOME`. To try the file actions safely:
+
+```sh
+SB=/tmp/ms-try; mkdir -p $SB
+HOME=$SB MACSETUP_CONFIG=$SB/.config uv run macsetup apply --only shell --yes
+```
+
+`shell` has no packages, so that never invokes brew.
+
+CI runs the same two things on every push. Lint, the suite and a check that
+the wheel still carries the catalog go on Linux; `plan` and `apply` shell out
+to `brew list`, so every profile is planned and dry-run on a macOS runner,
+along with the file appliers against a throwaway `HOME` and a second apply to
+prove re-running converges to nothing.
+
+## Not built yet
+
+- `sync` (git pull + apply), `add`, `prune`, `upgrade`, `doctor`
+- macOS `defaults write` tweaks as a step type
+- Mac App Store apps (`brew bundle` handles `mas` entries natively; no manifest
+  uses them yet)
+
+## Prior art
+
+[chezmoi](https://www.chezmoi.io/) does dotfiles thoroughly but not packages.
+`brew bundle` does packages but has no preview, no drift report and no notion
+of per-machine subsets. [nix-darwin](https://github.com/LnL7/nix-darwin) does
+all of it and more, if you want to learn Nix. macsetup is the middle: plain
+YAML, Homebrew underneath, a plan you read before anything happens.
+
+## License
+
+MIT