macsetup 0.1.0__py3-none-any.whl

macsetup/wizard.py

@@ -0,0 +1,169 @@
+"""The interactive selection flow.
+
+Only ever *decides* things -- it returns a MachineState and touches nothing
+else. Installing is apply's job, planning is planner's. Keeping the wizard
+free of side effects is what lets every answer also be expressible as a flag.
+"""
+
+from __future__ import annotations
+
+import socket
+
+import questionary
+from questionary import Choice
+
+from .detect import System
+from .manifest import Catalog, Module
+from .runner import Runner
+from .state import MachineState
+
+CUSTOM = "custom"
+
+_STYLE = questionary.Style(
+    [
+        ("qmark", "fg:cyan bold"),
+        ("question", "bold"),
+        ("answer", "fg:cyan"),
+        ("pointer", "fg:cyan bold"),
+        ("highlighted", "fg:cyan bold"),
+        ("selected", "fg:green"),
+        ("instruction", "fg:#888888"),
+    ]
+)
+
+
+class WizardAborted(RuntimeError):
+    pass
+
+
+def _ask(question):
+    answer = question.ask()
+    if answer is None:
+        raise WizardAborted("cancelled")
+    return answer
+
+
+def default_machine_name(runner: Runner) -> str:
+    result = runner.run(["scutil", "--get", "ComputerName"])
+    if result.ok and result.stdout.strip():
+        return result.stdout.strip()
+    return socket.gethostname().removesuffix(".local")
+
+
+def _module_label(module: Module, system: System) -> str:
+    total = len(module.packages)
+    installed = sum(1 for p in module.packages if system.has(p.name, cask=p.cask))
+    suffix = f"{installed}/{total} installed" if installed else f"{total} pkg"
+    detail = f" — {module.description}" if module.description else ""
+    return f"{module.id:<14} [{suffix}]{detail}"
+
+
+def run(
+    catalog: Catalog,
+    system: System,
+    runner: Runner,
+    *,
+    current: MachineState | None = None,
+) -> MachineState:
+    """Ask the questions. Returns the chosen state; saving is the caller's job."""
+
+    machine = _ask(
+        questionary.text(
+            "Name this machine",
+            default=current.machine if current else default_machine_name(runner),
+            style=_STYLE,
+        )
+    ).strip()
+
+    profile_choices = [
+        Choice(
+            title=f"{name:<10} {'everything' if entries == ['*'] else f'{len(entries)} modules'}",
+            value=name,
+        )
+        for name, entries in catalog.profiles.items()
+    ]
+    profile_choices.append(Choice(title="custom     pick modules yourself", value=CUSTOM))
+
+    profile = _ask(
+        questionary.select(
+            "Profile",
+            choices=profile_choices,
+            default=next(
+                (c for c in profile_choices if c.value == (current.profile if current else "work")),
+                None,
+            ),
+            style=_STYLE,
+        )
+    )
+
+    # Pre-tick from the current machine if reconfiguring, otherwise the profile.
+    # An empty saved selection falls through to the profile on purpose: pre-ticking
+    # nothing makes plain Enter save nothing, so an empty machine.toml would
+    # otherwise re-empty itself every time the wizard runs.
+    if current and current.modules and profile == current.profile:
+        preselected = set(current.modules)
+    elif profile == CUSTOM:
+        preselected = set()
+    else:
+        preselected = {m.id for m in catalog.resolve(profile) if not m.always}
+
+    optional = [m for m in catalog.modules.values() if not m.always]
+    always = [m for m in catalog.modules.values() if m.always]
+    if always:
+        names = ", ".join(m.id for m in always)
+        questionary.print(f"  always included: {names}", style="fg:#888888")
+
+    chosen = _ask(
+        questionary.checkbox(
+            "Modules for this machine",
+            choices=[
+                Choice(
+                    title=_module_label(m, system),
+                    value=m.id,
+                    checked=m.id in preselected,
+                )
+                for m in optional
+            ],
+            style=_STYLE,
+        )
+    )
+
+    # requires may pull in modules the user did not tick; surface that rather
+    # than silently installing something they did not choose.
+    resolved = catalog.resolve(only=chosen)
+    pulled = [m.id for m in resolved if m.id not in chosen and not m.always]
+    if pulled:
+        questionary.print(f"  + required by your selection: {', '.join(pulled)}", style="fg:yellow")
+
+    selected_ids = [m.id for m in resolved if not m.always]
+
+    picks: dict[str, list[str]] = {}
+    for module in resolved:
+        if module.select != "pick":
+            continue
+        if current and module.id in current.picks:
+            checked = set(current.picks[module.id])
+        else:
+            checked = set(module.default)
+        choices = []
+        for package in module.packages:
+            mark = "  (installed)" if system.has(package.name, cask=package.cask) else ""
+            choices.append(
+                Choice(
+                    title=f"{package.name}{mark}",
+                    value=package.name,
+                    checked=package.name in checked,
+                )
+            )
+        answer = _ask(
+            questionary.checkbox(f"{module.name} — choose packages", choices=choices, style=_STYLE)
+        )
+        picks[module.id] = list(answer)
+
+    return MachineState(
+        machine=machine,
+        profile=profile,
+        modules=selected_ids,
+        picks=picks,
+        vars=dict(current.vars) if current else {},
+    )

macsetup-0.1.0.dist-info/METADATA

@@ -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

macsetup-0.1.0.dist-info/RECORD

@@ -0,0 +1,32 @@
+macsetup/__init__.py,sha256=XaUMTRQDMeOi9KFq2M2WfVSq87BbjxQ88uF3kl6t5Gs,81
+macsetup/brewfile.py,sha256=BXg17LSbtfDHW0o5hArYpxxD-ZZx_p2JmWUtBtsbuWo,2322
+macsetup/cli.py,sha256=JRGKk8aEOdmgqLocj_fFgbFmwYtNNHfwNh9K9liDDP8,17699
+macsetup/detect.py,sha256=tNids4Cv-9C77c1CGEC2m8_9Bbzu-9ZKns-o9ln11ww,1563
+macsetup/files.py,sha256=S0oOVbCl2Ns-SkxwRgVU1xS_Evq0RqnzgVU4k8awZqw,5194
+macsetup/manifest.py,sha256=zkoNYoBE23gKcYPHMc0uAUtjbc9YmAiRlySHvndyY-w,12036
+macsetup/planner.py,sha256=473VxyYYeTtzmdaZspbmrbdQ1a4ZhtbNW3LoM0t_VfQ,4241
+macsetup/runner.py,sha256=Cq7_W1sit5zg6MguLvBkFM2Px54c90fVFr89Tzdle8c,2233
+macsetup/state.py,sha256=jlKiOxxBOpNcMBtekZTpq_3himlFzojXCEJcpi1LOXY,3422
+macsetup/wizard.py,sha256=oOl8h485T4XPqMbAvLB9O5Bu0b85LhDVKZU5SaS5MTw,5351
+macsetup/_data/files/git/gitconfig.j2,sha256=gpeUG8-sNpehJ9EXntoLwdlsJNCrIiPHvvG5zrOmeeY,500
+macsetup/_data/files/shell/zshrc-block.zsh,sha256=yHXw5U9Vyp3DB9zma59k4Oo3Dj90zxU6qKARcKBfE1g,234
+macsetup/_data/files/zsh/00-homebrew.zsh,sha256=PBJkPfefy40uB2415t4DXeGuXyTHdjMqOrxgS-9u4w8,474
+macsetup/_data/files/zsh/10-completion.zsh,sha256=VnPCobzCCFwtpvDqe-xfrWRTuQTa-xxyQmxMBdlm2Z0,938
+macsetup/_data/files/zsh/cli.zsh,sha256=zq-UujtIOiacPX40pvtJzkeWMqRVx9Qw6zUoEaHk-7Q,916
+macsetup/_data/files/zsh/node.zsh,sha256=XISalK4-90fBmNYSlgzsMaGkFCyKFL4XwAkGv92QzjE,377
+macsetup/_data/files/zsh/python.zsh,sha256=W8v5_bYgYCT5TEIr4p8g2zTqWIupLXYjhrDaDKShJ8g,489
+macsetup/_data/manifests/profiles.yaml,sha256=hfiJ3_KCRh7PvApdzCl7xHDgjeFn0-A_1cs8bO76mNg,596
+macsetup/_data/manifests/vars.yaml,sha256=ltXckqGmtD7HoYCicl5KXdCCCscdwvek-LSIdqhXu5Q,439
+macsetup/_data/manifests/modules/cli.yaml,sha256=WaC8bF-tcCJ5CceAidDV6hJiEYW2yvghRhmw50ixJgo,469
+macsetup/_data/manifests/modules/core.yaml,sha256=OeLHEYB5nZ7gXEJPK31P3RDGgslqJXqya1j0rZkGXo0,118
+macsetup/_data/manifests/modules/editors.yaml,sha256=vnzxbWIz1X29L5NlRef_Wi3ntyOjT-SCuRLcWPmFmQQ,621
+macsetup/_data/manifests/modules/fonts.yaml,sha256=AIBIIuPz0Y1zELGIdbaeCecyBy1zYJMEfgq4k3sDfz8,147
+macsetup/_data/manifests/modules/git-identity.yaml,sha256=BjUHAXIyVJC-a5RIBo4Eh0YQIluGuWgYHuMSfze2L1Y,741
+macsetup/_data/manifests/modules/lang-node.yaml,sha256=g64UiC0F025RxlIkrFoVCFR-tp2anCNetvcSck9lQ0g,171
+macsetup/_data/manifests/modules/lang-python.yaml,sha256=2PJXLw4qibmEnriBABwTt-8de4ZhSlOJ96pwbNaxiDI,193
+macsetup/_data/manifests/modules/shell.yaml,sha256=i-ccXMNyF1-JNG3BXM--m045_Aq3UeEOScV_hi8k5q8,766
+macsetup-0.1.0.dist-info/METADATA,sha256=oc-NKvHcBLFUhU0aM8MG_LgyKmabQIyrGXznvIWd3tc,9597
+macsetup-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+macsetup-0.1.0.dist-info/entry_points.txt,sha256=aqEEFnIkOEgSnrbNChMkdVQf37CJ5NaCh6N53OMPNG8,46
+macsetup-0.1.0.dist-info/licenses/LICENSE,sha256=fC6gbDhxVx-OgjDtdsNFmtniABmXidQ3-nhlXcPqs0w,1071
+macsetup-0.1.0.dist-info/RECORD,,

macsetup-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

macsetup-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+macsetup = macsetup.cli:app

macsetup-0.1.0.dist-info/licenses/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.