macsetup 0.1.0__py3-none-any.whl

macsetup/manifest.py

@@ -0,0 +1,321 @@
+"""Manifest loading and validation.
+
+Manifests are the source of truth: adding a package should be a data edit, not
+a code change. Pydantic catches a typo'd key at load time rather than halfway
+through an install.
+"""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Iterable
+from pathlib import Path
+from typing import Any, Literal
+
+import yaml
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+ALL = "*"
+
+
+class ManifestError(RuntimeError):
+    pass
+
+
+class Package(BaseModel):
+    """One installable. Accepts shorthand: `- git` or `- {name: arc, cask: true}`."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    name: str
+    cask: bool = False
+    mas: int | None = None
+
+    @model_validator(mode="before")
+    @classmethod
+    def _shorthand(cls, value: Any) -> Any:
+        return {"name": value} if isinstance(value, str) else value
+
+    def brewfile_line(self) -> str:
+        if self.mas is not None:
+            return f'mas "{self.name}", id: {self.mas}'
+        verb = "cask" if self.cask else "brew"
+        return f'{verb} "{self.name}"'
+
+
+class FileSpec(BaseModel):
+    """One file action. Exactly one of copy/render/block names the source.
+
+    copy   -- verbatim, e.g. a zsh fragment
+    render -- Jinja2 with machine vars, e.g. the ssh config
+    block  -- marker-delimited region inside a file macsetup does not own
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid", populate_by_name=True)
+
+    # `copy_` is aliased because a field literally named `copy` shadows
+    # BaseModel.copy; the manifest key stays `copy:`.
+    copy_: str | None = Field(default=None, alias="copy")
+    render: str | None = None
+    block: str | None = None
+    to: str | None = None
+    into: str | None = None
+    mode: str | None = None
+    comment: str = "#"
+    position: Literal["top", "bottom"] = "bottom"
+
+    _FIELDS = {"copy": "copy_", "render": "render", "block": "block"}
+
+    @model_validator(mode="after")
+    def _check(self) -> FileSpec:
+        kinds = [k for k, f in self._FIELDS.items() if getattr(self, f)]
+        if len(kinds) != 1:
+            raise ValueError(f"need exactly one of copy/render/block, got {kinds or 'none'}")
+        if self.kind == "block":
+            if not self.into:
+                raise ValueError("`block` needs `into:` (the file to edit)")
+            if self.to:
+                raise ValueError("`block` uses `into:`, not `to:`")
+        else:
+            if not self.to:
+                raise ValueError(f"`{self.kind}` needs `to:` (the destination path)")
+            if self.into:
+                raise ValueError(f"`{self.kind}` uses `to:`, not `into:`")
+        if self.mode:
+            try:
+                int(self.mode, 8)
+            except ValueError:
+                raise ValueError(f'mode {self.mode!r} is not octal, e.g. "600"') from None
+        return self
+
+    @property
+    def kind(self) -> str:
+        for kind, field_name in self._FIELDS.items():
+            if getattr(self, field_name):
+                return kind
+        raise AssertionError("validated above")
+
+    @property
+    def source(self) -> str:
+        return getattr(self, self._FIELDS[self.kind])
+
+    @property
+    def target(self) -> str:
+        return self.into if self.kind == "block" else self.to  # type: ignore[return-value]
+
+
+class Module(BaseModel):
+    """A unit of setup, and the thing the wizard offers as a choice.
+
+    `select: pick` means the wizard offers per-package checkboxes instead of
+    treating the module as atomic -- for genuine menus like editors, where
+    wanting half the module is normal.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    id: str
+    name: str
+    description: str = ""
+    always: bool = False
+    select: Literal["all", "pick"] = "all"
+    default: list[str] = Field(default_factory=list)
+    requires: list[str] = Field(default_factory=list)
+    packages: list[Package] = Field(default_factory=list)
+    files: list[FileSpec] = Field(default_factory=list)
+
+    @model_validator(mode="after")
+    def _check(self) -> Module:
+        names = {p.name for p in self.packages}
+        unknown = [d for d in self.default if d not in names]
+        if unknown:
+            raise ValueError(f"module {self.id!r}: default lists unknown packages {unknown}")
+        if self.select == "all" and self.default:
+            raise ValueError(f"module {self.id!r}: `default` only applies when select: pick")
+        return self
+
+    def selected_packages(self, picks: set[str] | None = None) -> list[Package]:
+        """Packages to install, honouring per-package picks for `select: pick`."""
+        if self.select == "all":
+            return list(self.packages)
+        chosen = picks if picks is not None else set(self.default)
+        return [p for p in self.packages if p.name in chosen]
+
+
+class Catalog(BaseModel):
+    modules: dict[str, Module]
+    profiles: dict[str, list[str]]
+
+    def module(self, module_id: str) -> Module:
+        try:
+            return self.modules[module_id]
+        except KeyError:
+            raise ManifestError(f"unknown module {module_id!r}") from None
+
+    def resolve(
+        self,
+        profile: str | None = None,
+        only: list[str] | None = None,
+        *,
+        include_always: bool | None = None,
+    ) -> list[Module]:
+        """Profile (or explicit module list) -> ordered, dependency-closed modules.
+
+        `always` modules are folded in unconditionally; `--only` is the one case
+        where that is skipped, since it means "just this, I know what I want".
+        Applying a saved machine selection overrides that with
+        include_always=True, since machine.toml stores optional modules only.
+
+        An *empty* `only` is a selection, not the absence of one: a machine.toml
+        with `modules = []` resolves to the always-on modules and nothing else.
+        Falling back to the profile there would report "need a profile" on a
+        machine that is configured and names its profile in the file.
+        """
+        if only is not None:
+            wanted = list(only)
+            include_always = False if include_always is None else include_always
+        else:
+            if profile is None:
+                raise ManifestError("need a profile or an explicit module list")
+            if profile not in self.profiles:
+                known = ", ".join(sorted(self.profiles))
+                raise ManifestError(f"unknown profile {profile!r} (have: {known})")
+            entries = self.profiles[profile]
+            wanted = list(self.modules) if ALL in entries else list(entries)
+            include_always = True if include_always is None else include_always
+
+        for module_id in wanted:
+            self.module(module_id)
+
+        seen: set[str] = set()
+        ordered: list[str] = []
+
+        def visit(module_id: str, trail: tuple[str, ...] = ()) -> None:
+            if module_id in seen:
+                return
+            if module_id in trail:
+                cycle = " -> ".join([*trail, module_id])
+                raise ManifestError(f"circular requires: {cycle}")
+            for dep in self.module(module_id).requires:
+                visit(dep, (*trail, module_id))
+            seen.add(module_id)
+            ordered.append(module_id)
+
+        if include_always:
+            for module_id, module in self.modules.items():
+                if module.always:
+                    visit(module_id)
+        for module_id in wanted:
+            visit(module_id)
+
+        return [self.modules[m] for m in ordered]
+
+    def unadopted(self, profile: str, selected: Iterable[str]) -> list[str]:
+        """Modules this machine could adopt but has not.
+
+        A hand-picked machine stores profile "custom", which is not a catalog
+        profile, and `state.py` falls back to the same string when the key is
+        missing. Treating an unknown profile as "the whole catalog" is what
+        keeps this check alive there -- gating it on a known profile name
+        disabled it on exactly the machines most likely to lag behind upstream.
+        """
+        candidates = (
+            {m.id for m in self.resolve(profile)} if profile in self.profiles else set(self.modules)
+        )
+        return sorted(candidates - set(selected))
+
+
+def _resolve_dir(env_var: str, name: str, sentinel: str) -> Path:
+    """Locate a data dir: env override, then repo checkout, then packaged copy."""
+    override = os.environ.get(env_var)
+    if override:
+        path = Path(override).expanduser()
+        if not path.is_dir():
+            raise ManifestError(f"{env_var} points at {path}, which is not a directory")
+        return path
+
+    repo = Path.cwd() / name
+    if (repo / sentinel).exists():
+        return repo
+
+    packaged = Path(__file__).parent / "_data" / name
+    if (packaged / sentinel).exists():
+        return packaged
+
+    raise ManifestError(f"no {name}/ found; set {env_var} or run from the repo root")
+
+
+def manifests_dir() -> Path:
+    return _resolve_dir("MACSETUP_MANIFESTS", "manifests", "profiles.yaml")
+
+
+def files_dir() -> Path:
+    """Where `copy:`/`render:`/`block:` sources are resolved from."""
+    return _resolve_dir("MACSETUP_FILES", "files", "zsh")
+
+
+def catalog_vars(root: Path | None = None) -> dict[str, str]:
+    """Default `render:` variables, declared by the catalog in vars.yaml.
+
+    Who you are is data, not code: the engine ships no name or email of its
+    own, so the same engine serves a public catalog and a private one. A
+    machine overrides individual values in the [vars] table of machine.toml.
+
+    Rendering uses StrictUndefined, so every variable a template references
+    must have a value here or in machine.toml -- a missing one is a hard error
+    rather than a silently empty `email = ` in a config file.
+    """
+    path = (root or manifests_dir()) / "vars.yaml"
+    if not path.is_file():
+        return {}
+    loaded = yaml.safe_load(path.read_text(encoding="utf-8")) or {}
+    if not isinstance(loaded, dict) or not isinstance(loaded.get("vars", {}), dict):
+        raise ManifestError(f"{path} must hold a `vars:` mapping of names to values")
+    return {str(k): str(v) for k, v in (loaded.get("vars") or {}).items()}
+
+
+def load_catalog(root: Path | None = None) -> Catalog:
+    root = root or manifests_dir()
+
+    profiles_file = root / "profiles.yaml"
+    if not profiles_file.is_file():
+        raise ManifestError(f"missing {profiles_file}")
+    profiles_doc = _read_yaml(profiles_file)
+    profiles = profiles_doc.get("profiles")
+    if not isinstance(profiles, dict):
+        raise ManifestError(f"{profiles_file}: expected a top-level `profiles:` mapping")
+
+    modules: dict[str, Module] = {}
+    for path in sorted((root / "modules").glob("*.yaml")):
+        try:
+            module = Module.model_validate(_read_yaml(path))
+        except Exception as exc:
+            raise ManifestError(f"{path.name}: {exc}") from exc
+        if module.id in modules:
+            raise ManifestError(f"{path.name}: duplicate module id {module.id!r}")
+        modules[module.id] = module
+
+    if not modules:
+        raise ManifestError(f"no module manifests found in {root / 'modules'}")
+
+    catalog = Catalog(modules=modules, profiles=profiles)
+
+    # Fail at load time rather than when someone selects the broken profile.
+    for name, entries in profiles.items():
+        for module_id in entries:
+            if module_id != ALL and module_id not in modules:
+                raise ManifestError(f"profile {name!r} references unknown module {module_id!r}")
+    for module in modules.values():
+        for dep in module.requires:
+            if dep not in modules:
+                raise ManifestError(f"module {module.id!r} requires unknown module {dep!r}")
+
+    return catalog
+
+
+def _read_yaml(path: Path) -> dict[str, Any]:
+    with path.open(encoding="utf-8") as handle:
+        data = yaml.safe_load(handle)
+    if not isinstance(data, dict):
+        raise ManifestError(f"{path}: expected a YAML mapping")
+    return data

macsetup/planner.py

@@ -0,0 +1,141 @@
+"""Turn a module selection plus machine state into a reviewable plan.
+
+Nothing here mutates anything. `plan` and `apply` share this code so the
+preview is always exactly what apply will act on.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from . import files as files_mod
+from .detect import System
+from .manifest import FileSpec, Module, Package
+
+
+@dataclass(frozen=True)
+class FileAction:
+    spec: FileSpec
+    outcome: files_mod.Outcome
+
+    @property
+    def pending(self) -> bool:
+        return self.outcome.pending
+
+
+@dataclass(frozen=True)
+class ModulePlan:
+    module: Module
+    missing: list[Package] = field(default_factory=list)
+    satisfied: list[Package] = field(default_factory=list)
+    skipped: list[Package] = field(default_factory=list)
+    file_actions: list[FileAction] = field(default_factory=list)
+
+    @property
+    def pending_files(self) -> list[FileAction]:
+        return [a for a in self.file_actions if a.pending]
+
+    @property
+    def pending(self) -> bool:
+        return bool(self.missing) or bool(self.pending_files)
+
+    @property
+    def selected(self) -> list[Package]:
+        return [*self.missing, *self.satisfied]
+
+
+@dataclass(frozen=True)
+class Plan:
+    modules: list[ModulePlan] = field(default_factory=list)
+
+    @property
+    def pending(self) -> list[ModulePlan]:
+        return [m for m in self.modules if m.pending]
+
+    @property
+    def missing_count(self) -> int:
+        return sum(len(m.missing) for m in self.modules)
+
+    @property
+    def satisfied_count(self) -> int:
+        return sum(len(m.satisfied) for m in self.modules)
+
+    @property
+    def file_change_count(self) -> int:
+        return sum(len(m.pending_files) for m in self.modules)
+
+    @property
+    def converged(self) -> bool:
+        return self.missing_count == 0 and self.file_change_count == 0
+
+    def selected_packages(self) -> list[Package]:
+        return [p for m in self.modules for p in m.selected]
+
+
+def _file_action(spec: FileSpec, root: Path, variables: dict[str, str]) -> FileAction:
+    source = root / spec.source
+    dest = files_mod.expand(spec.target)
+
+    if spec.kind == "copy":
+        outcome = files_mod.plan_copy(source, dest)
+    elif spec.kind == "render":
+        outcome = files_mod.plan_render(source, dest, variables)
+    else:
+        outcome = files_mod.plan_block(
+            dest,
+            source.read_text(encoding="utf-8"),
+            comment=spec.comment,
+            position=spec.position,
+        )
+    return FileAction(spec=spec, outcome=outcome)
+
+
+def build_plan(
+    modules: list[Module],
+    system: System,
+    picks: dict[str, set[str]] | None = None,
+    *,
+    files_root: Path | None = None,
+    variables: dict[str, str] | None = None,
+) -> Plan:
+    picks = picks or {}
+    variables = variables or {}
+    plans: list[ModulePlan] = []
+
+    for module in modules:
+        chosen = module.selected_packages(picks.get(module.id))
+        chosen_names = {p.name for p in chosen}
+        missing = [p for p in chosen if not system.has(p.name, cask=p.cask)]
+        satisfied = [p for p in chosen if system.has(p.name, cask=p.cask)]
+        skipped = [p for p in module.packages if p.name not in chosen_names]
+
+        actions: list[FileAction] = []
+        if module.files and files_root is not None:
+            actions = [_file_action(spec, files_root, variables) for spec in module.files]
+
+        plans.append(
+            ModulePlan(
+                module=module,
+                missing=missing,
+                satisfied=satisfied,
+                skipped=skipped,
+                file_actions=actions,
+            )
+        )
+
+    return Plan(modules=plans)
+
+
+def untracked(plan: Plan, system: System) -> tuple[list[str], list[str]]:
+    """Installed packages that no selected module accounts for.
+
+    Informational in Phase 1 -- this is what `macsetup prune` will eventually
+    offer to remove.
+    """
+    known_formulae = {p.name for p in plan.selected_packages() if not p.cask and p.mas is None}
+    known_casks = {p.name for p in plan.selected_packages() if p.cask}
+    return (
+        sorted(system.formulae - known_formulae),
+        sorted(system.casks - known_casks),
+    )

macsetup/runner.py

@@ -0,0 +1,71 @@
+"""The subprocess seam.
+
+Every external command goes through a Runner. Production uses SubprocessRunner;
+tests inject FakeRunner so planner logic can be exercised without touching the
+machine running the tests.
+"""
+
+from __future__ import annotations
+
+import subprocess
+from collections.abc import Sequence
+from dataclasses import dataclass, field
+from typing import Protocol
+
+
+@dataclass(frozen=True)
+class Result:
+    code: int
+    stdout: str = ""
+    stderr: str = ""
+
+    @property
+    def ok(self) -> bool:
+        return self.code == 0
+
+    def lines(self) -> list[str]:
+        return [line for line in self.stdout.splitlines() if line.strip()]
+
+
+class CommandError(RuntimeError):
+    def __init__(self, cmd: Sequence[str], result: Result) -> None:
+        self.cmd = list(cmd)
+        self.result = result
+        super().__init__(f"`{' '.join(cmd)}` exited {result.code}: {result.stderr.strip()}")
+
+
+class Runner(Protocol):
+    def run(self, cmd: Sequence[str], *, capture: bool = True, check: bool = False) -> Result: ...
+
+
+class SubprocessRunner:
+    """Runs commands for real.
+
+    capture=False streams straight to the terminal, which is what we want for
+    `brew bundle install` -- Homebrew's own progress output is better than
+    anything we would reconstruct from captured text.
+    """
+
+    def run(self, cmd: Sequence[str], *, capture: bool = True, check: bool = False) -> Result:
+        proc = subprocess.run(list(cmd), capture_output=capture, text=True)
+        result = Result(proc.returncode, proc.stdout or "", proc.stderr or "")
+        if check and not result.ok:
+            raise CommandError(cmd, result)
+        return result
+
+
+@dataclass
+class FakeRunner:
+    """Test double. Maps a joined command string to a canned Result."""
+
+    responses: dict[str, Result] = field(default_factory=dict)
+    calls: list[list[str]] = field(default_factory=list)
+    default: Result = Result(0)
+
+    def run(self, cmd: Sequence[str], *, capture: bool = True, check: bool = False) -> Result:
+        cmd = list(cmd)
+        self.calls.append(cmd)
+        result = self.responses.get(" ".join(cmd), self.default)
+        if check and not result.ok:
+            raise CommandError(cmd, result)
+        return result

macsetup/state.py

@@ -0,0 +1,102 @@
+"""Per-machine state.
+
+Lives outside the repo, in ~/.config/macsetup/machine.toml. Identical manifests
+in git plus a small local override file is what makes 5 machines tractable.
+
+The module list is stored explicitly rather than derived from the profile name.
+A module added to a profile upstream must not silently install itself on five
+machines the next time they sync -- `macsetup configure` adopts it deliberately.
+"""
+
+from __future__ import annotations
+
+import os
+import tomllib
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+import tomli_w
+
+from .manifest import catalog_vars
+
+
+def config_dir() -> Path:
+    override = os.environ.get("MACSETUP_CONFIG")
+    if override:
+        return Path(override).expanduser()
+    xdg = os.environ.get("XDG_CONFIG_HOME")
+    base = Path(xdg).expanduser() if xdg else Path.home() / ".config"
+    return base / "macsetup"
+
+
+def state_path() -> Path:
+    return config_dir() / "machine.toml"
+
+
+def builtin_vars(machine: str) -> dict[str, str]:
+    """Variables every render gets, with or without a machine.toml.
+
+    Defaults come from the catalog's vars.yaml, not from this package: the
+    engine has no opinion about who you are. On top of those, two are always
+    supplied here --
+
+    `machine`  the machine name, so one template can branch per machine
+    `home`     an absolute path, for config values whose reader does not
+               tilde-expand. git expands ~ in core.hooksPath; a GUI client
+               carrying its own git implementation may not.
+    """
+    return {**catalog_vars(), "machine": machine, "home": str(Path.home())}
+
+
+@dataclass
+class MachineState:
+    machine: str
+    profile: str
+    modules: list[str] = field(default_factory=list)
+    picks: dict[str, list[str]] = field(default_factory=dict)
+    vars: dict[str, str] = field(default_factory=dict)
+
+    def template_vars(self) -> dict[str, str]:
+        return {**builtin_vars(self.machine), **self.vars}
+
+    def picks_as_sets(self) -> dict[str, set[str]]:
+        return {module_id: set(names) for module_id, names in self.picks.items()}
+
+    def to_toml(self) -> dict[str, Any]:
+        doc: dict[str, Any] = {
+            "machine": self.machine,
+            "profile": self.profile,
+            "modules": list(self.modules),
+        }
+        if self.picks:
+            doc["picks"] = {k: sorted(v) for k, v in self.picks.items() if v}
+        if self.vars:
+            doc["vars"] = dict(self.vars)
+        return doc
+
+
+def load(path: Path | None = None) -> MachineState | None:
+    path = path or state_path()
+    if not path.is_file():
+        return None
+    with path.open("rb") as handle:
+        doc = tomllib.load(handle)
+    return MachineState(
+        machine=doc.get("machine", "unknown"),
+        profile=doc.get("profile", "custom"),
+        modules=list(doc.get("modules", [])),
+        picks={k: list(v) for k, v in (doc.get("picks") or {}).items()},
+        vars=dict(doc.get("vars") or {}),
+    )
+
+
+def save(state: MachineState, path: Path | None = None) -> Path:
+    path = path or state_path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    header = (
+        "# macsetup machine state -- written by `macsetup init` / `configure`.\n"
+        "# Safe to edit by hand; `modules` is the authoritative selection.\n\n"
+    )
+    path.write_text(header + tomli_w.dumps(state.to_toml()), encoding="utf-8")
+    return path