From d2ef745a630c2864b4a0a7f71e093e9470076a07 Mon Sep 17 00:00:00 2001 From: Evan Alter Date: Fri, 2 Oct 2026 13:22:25 -0500 Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9D=20docs:=20watchlist=20=E2=80=94=20?= =?UTF-8?q?one=20place=20for=20tools=20parked=20as=20"not=20yet",=20starti?= =?UTF-8?q?ng=20with=20pymacos?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Evaluations that end in "not yet" used to live only in a conversation, so the next time the tool came up it was researched from scratch. Each entry records what the thing is, why it matters to this setup, what stops us, and the concrete condition for another look, so revisiting is a check rather than a re-evaluation. CLAUDE.md's Key files points sessions at it. First entry: pymacos, whose settings.export/apply is a read-compare-write engine that could back or replace .macos, but whose repo was five days old at evaluation. Co-Authored-By: Claude Opus 5.5 (1M context) --- CLAUDE.md | 1 + docs/watchlist.md | 41 +++++++++++++++++++++++++++++++++++++++++ 2 files changed, 42 insertions(+) create mode 100644 docs/watchlist.md diff --git a/CLAUDE.md b/CLAUDE.md index 59081575680..19f35e63157 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -99,6 +99,7 @@ VMs; the test skips everywhere else unless `MACOS_APPLY_OK=1` is set. - **`.chezmoi.toml.tmpl`** — config template; prompts once for the machine class and pins `sourceDir` to the clone on macs - **`.chezmoiignore`** — target paths chezmoi must not manage (repo-level files everywhere, `CLAUDE.md` and `com.googlecode.iterm2.plist` among them; macOS GUI config off-mac; identity/secrets on `ephemeral`) - **`bootstrap.sh`** — deprecated wrapper around `chezmoi init --source . --apply` +- **`docs/watchlist.md`** — tools evaluated and parked as "not yet", each with what would make it worth another look; check it before re-evaluating something, and add to it when an evaluation ends in "not yet" - **`.macos`** — macOS `defaults write` settings; reads `$COMPUTER_NAME` env var for machine-specific naming - **`Brewfile`** — Homebrew formulae, casks, and Mac App Store apps (macOS only; `.chezmoiscripts/darwin/` runs `brew bundle` when it changes) - **`packages-apt.txt`** — Debian/Ubuntu/WSL package list (`.chezmoiscripts/linux/` installs it when it changes; skips gracefully without apt or sudo) diff --git a/docs/watchlist.md b/docs/watchlist.md new file mode 100644 index 00000000000..73f0859f228 --- /dev/null +++ b/docs/watchlist.md @@ -0,0 +1,41 @@ +# Watchlist + +Tools and changes worth keeping an eye on: not adopted yet, but likely to +matter to this setup later. Each entry says what it is, why it is +interesting here, what stops us today, and **what would make it worth +another look**, so that revisiting is a check rather than a re-evaluation. + +Add an entry when something gets evaluated and the answer is "not yet"; +delete it once it is adopted or ruled out for good (the commit that +removes it says which). + +## pymacos + +https://github.com/JeanExtreme002/pymacos +(docs: https://macos.readthedocs.io/en/latest/) + +- **Evaluated:** 2026-10-02, at v1.19.1. +- **What:** a zero-dependency Python library that controls macOS. Most of it + calls Apple's frameworks directly (CFPreferences, Security, Accessibility, + CoreGraphics, Vision) through a hand-written ctypes Objective-C bridge; + about a third of the modules just wrap CLI tools (`say`, `tmutil`, + `mdfind`, `shortcuts`, `launchctl`, `osascript`). +- **Why it matters here:** `macos.settings.export()` / `apply(json)` is a + read-compare-write convergence engine: it changes only settings that + differ, returns what changed, and restarts the Dock and Finder once. A + pinned `mac.json` could supplement or replace `.macos`, and covers what + `.macos` does badly or not at all: Dock contents, default apps per file + type, app and system shortcuts, login items. Ansible would add nothing + for a single machine converging its own settings. +- **What stops us:** the repo was five days old (created 2026-09-27, ~72 + PRs, 20 stars), with releases hours apart. Every framework call has its + types declared by hand, so a macOS change crashes or returns garbage + instead of failing cleanly. +- **Ceilings whatever runs it:** `hidutil` key remaps reset at reboot (they + need a login LaunchAgent); `set_default_for` asks the user to confirm on + macOS 26 and cannot set the default browser; Dock, wallpaper and window + control need the logged-in GUI session, not SSH. +- **Revisit when:** releases are weeks apart, it has users beyond its + author, and a few months have passed (earliest ~2027-01). Then: pin an + exact version, run `settings.export()` on a configured Mac, and diff + it against `.macos`.