mac-upkeep 2.1.0__tar.gz

mac_upkeep-2.1.0/.github/workflows/release.yml

@@ -0,0 +1,87 @@
+name: release
+on:
+  push:
+    branches: [main]
+permissions:
+  contents: write
+  pull-requests: write
+jobs:
+  release-please:
+    runs-on: ubuntu-latest
+    outputs:
+      release_created: ${{ steps.release.outputs.release_created }}
+      tag_name: ${{ steps.release.outputs.tag_name }}
+    steps:
+      - uses: actions/create-github-app-token@v2
+        id: app-token
+        with:
+          app-id: ${{ vars.RELEASE_PLEASE_APP_ID }}
+          private-key: ${{ secrets.RELEASE_PLEASE_PRIVATE_KEY }}
+      - id: release
+        uses: googleapis/release-please-action@v4
+        with:
+          token: ${{ steps.app-token.outputs.token }}
+          config-file: release-please-config.json
+
+      - name: Checkout release PR branch
+        if: ${{ steps.release.outputs.pr && !steps.release.outputs.release_created }}
+        uses: actions/checkout@v4
+        with:
+          token: ${{ steps.app-token.outputs.token }}
+          ref: release-please--branches--main
+
+      - name: Setup uv
+        if: ${{ steps.release.outputs.pr && !steps.release.outputs.release_created }}
+        uses: astral-sh/setup-uv@v5
+
+      - name: Update uv.lock in release PR
+        if: ${{ steps.release.outputs.pr && !steps.release.outputs.release_created }}
+        run: |
+          uv lock
+          if git diff --quiet uv.lock; then
+            echo "uv.lock already up to date"
+          else
+            git config user.name "github-actions[bot]"
+            git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+            git add uv.lock
+            git commit -m "chore: update uv.lock"
+            git push
+          fi
+
+  bump-tap:
+    needs: release-please
+    if: ${{ needs.release-please.outputs.release_created == 'true' }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/create-github-app-token@v2
+        id: app-token
+        with:
+          app-id: ${{ vars.RELEASE_PLEASE_APP_ID }}
+          private-key: ${{ secrets.RELEASE_PLEASE_PRIVATE_KEY }}
+          repositories: homebrew-tap
+      - name: Dispatch formula update
+        uses: peter-evans/repository-dispatch@v3
+        with:
+          token: ${{ steps.app-token.outputs.token }}
+          repository: calvindotsg/homebrew-tap
+          event-type: formula-update
+          client-payload: |-
+            {
+              "formula": "mac-upkeep",
+              "version": "${{ needs.release-please.outputs.tag_name }}",
+              "url": "https://github.com/calvindotsg/maintenance/archive/refs/tags/${{ needs.release-please.outputs.tag_name }}.tar.gz",
+              "type": "python"
+            }
+
+  pypi-publish:
+    needs: release-please
+    if: ${{ needs.release-please.outputs.release_created == 'true' }}
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv build
+      - uses: pypa/gh-action-pypi-publish@release/v1

mac_upkeep-2.1.0/.github/workflows/test.yml

@@ -0,0 +1,16 @@
+name: test
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+jobs:
+  test:
+    runs-on: macos-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv lock --check
+      - run: uv sync
+      - run: uv run ruff check src/ tests/
+      - run: uv run pytest

mac_upkeep-2.1.0/.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.pyc
+dist/
+*.egg-info/
+.ruff_cache/
+.pytest_cache/
+coverage/
+.DS_Store
+.claude/worktrees/
+.scratchpad/
+.venv/

mac_upkeep-2.1.0/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "2.1.0"
+}

mac_upkeep-2.1.0/CHANGELOG.md

@@ -0,0 +1,79 @@
+# Changelog
+
+## [2.1.0](https://github.com/calvindotsg/maintenance/compare/v2.0.0...v2.1.0) (2026-04-08)
+
+
+### Features
+
+* custom task support, detect auto-inference, validation ([#16](https://github.com/calvindotsg/maintenance/issues/16)) ([d8af4e6](https://github.com/calvindotsg/maintenance/commit/d8af4e62620ebbf1088e0e55c9faf7cdbe0f0785))
+* PyPI publishing and platform guard ([#18](https://github.com/calvindotsg/maintenance/issues/18)) ([af5e341](https://github.com/calvindotsg/maintenance/commit/af5e341e0798e7cd5e997de5d9dea17897ff369e))
+
+## [2.0.0](https://github.com/calvindotsg/maintenance/compare/v1.2.1...v2.0.0) (2026-04-08)
+
+
+### ⚠ BREAKING CHANGES
+
+* Package renamed from maintenance to mac-upkeep.
+
+### Features
+
+* rename package to mac-upkeep ([#15](https://github.com/calvindotsg/maintenance/issues/15)) ([aef9e86](https://github.com/calvindotsg/maintenance/commit/aef9e8604f3c3a95286f06274e7737d81ec1dc5a))
+* TOML-driven task registry + init/show-config commands ([#12](https://github.com/calvindotsg/maintenance/issues/12)) ([23a7f0b](https://github.com/calvindotsg/maintenance/commit/23a7f0b53931eae733a8a7bf9cf141e5c0460797))
+
+
+### Documentation
+
+* update README and CLAUDE.md for TOML-driven architecture ([#14](https://github.com/calvindotsg/maintenance/issues/14)) ([2ce0583](https://github.com/calvindotsg/maintenance/commit/2ce058350b5d0665113ec3064d299ce777709a30))
+
+
+### CI/CD
+
+* keep uv.lock in sync with release-please version bumps ([#10](https://github.com/calvindotsg/maintenance/issues/10)) ([d6a81a9](https://github.com/calvindotsg/maintenance/commit/d6a81a9c72cb3a764708d74e505b0f5a86a14697))
+
+## [1.2.1](https://github.com/calvindotsg/maintenance/compare/v1.2.0...v1.2.1) (2026-04-07)
+
+
+### Bug Fixes
+
+* --force filter, frequency scheduling, task discoverability ([#9](https://github.com/calvindotsg/maintenance/issues/9)) ([26a5ac1](https://github.com/calvindotsg/maintenance/commit/26a5ac123406836266480f246ba4c7f1b8789cd7))
+
+
+### Documentation
+
+* **claude:** document v1.2.0 patterns for AI agent effectiveness ([#7](https://github.com/calvindotsg/maintenance/issues/7)) ([a6d5f0d](https://github.com/calvindotsg/maintenance/commit/a6d5f0dca8c51cb2b97e71ea35c95771f9fb8abf))
+
+## [1.2.0](https://github.com/calvindotsg/maintenance/compare/v1.1.1...v1.2.0) (2026-04-07)
+
+
+### Features
+
+* add brew tasks, frequency scheduling, live TUI, and actionable notifications ([#5](https://github.com/calvindotsg/maintenance/issues/5)) ([9ee2381](https://github.com/calvindotsg/maintenance/commit/9ee23811fa60fbb483b4ff695aabc92a8c23899c))
+
+## [1.1.1](https://github.com/calvindotsg/maintenance/compare/v1.1.0...v1.1.1) (2026-04-06)
+
+
+### Bug Fixes
+
+* **tasks:** close stdin and add --force to uv cache prune ([#4](https://github.com/calvindotsg/maintenance/issues/4)) ([4692060](https://github.com/calvindotsg/maintenance/commit/46920604eaccf8e8402d8cb0e70bb3c0e4b22606))
+
+
+### Documentation
+
+* **claude:** add release-please manifest and token scoping constraints ([8cd3775](https://github.com/calvindotsg/maintenance/commit/8cd377570eb332fe00ef1367fc1743af84b2e667))
+
+## [1.1.0](https://github.com/calvindotsg/maintenance/compare/v1.0.0...v1.1.0) (2026-04-05)
+
+
+### Features
+
+* rich output, macOS notifications, and tap automation ([#1](https://github.com/calvindotsg/maintenance/issues/1)) ([c0d9577](https://github.com/calvindotsg/maintenance/commit/c0d9577c13dcf4902af37b3c4a72d448fb9e93a3))
+
+
+### Bug Fixes
+
+* add chmod 0440 to sudoers setup instructions ([060d848](https://github.com/calvindotsg/maintenance/commit/060d848de637e9db72168336d04ac516d2fb3ec4))
+
+
+### Miscellaneous
+
+* add release-please manifest and gitignore .scratchpad ([0e8d983](https://github.com/calvindotsg/maintenance/commit/0e8d983826ec2735667ed321e8ee77a5c2175343))

mac_upkeep-2.1.0/CLAUDE.md

@@ -0,0 +1,128 @@
+# CLAUDE.md
+
+## Quick Commands
+
+| Command | Purpose |
+|---------|---------|
+| `uv sync` | Install dependencies |
+| `uv run ruff check src/ tests/` | Lint |
+| `uv run ruff format src/ tests/` | Format |
+| `uv run pytest` | Run tests |
+| `uv run pytest --cov` | Run tests with coverage |
+| `uv run mac-upkeep run --dry-run` | Test CLI without side effects |
+| `uv run mac-upkeep init` | Generate starter config (auto-detect tools) |
+| `uv run mac-upkeep show-config --default` | Show all available task options |
+| `uv run mac-upkeep notify-test` | Verify macOS notification permissions |
+
+## Architecture
+
+```
+defaults.toml → bundled task definitions (11 tasks), loaded via importlib.resources
+config.py     → TaskDef dataclass, load_task_defs(), resolve_variables(), get_brew_prefix(),
+                Config.load() (3-layer merge: defaults.toml → user config → env vars)
+tasks.py      → _build_cmd(), run_task(), _run(), run_all_tasks() data-driven loop,
+                frequency scheduling, ANSI stripping
+cli.py        → Typer app: run, tasks, init, show-config, setup, status, logs, notify-test
+output.py     → TaskResult dataclass, Rich Live table TUI (interactive), Python logging (non-interactive)
+notify.py     → macOS notifications via terminal-notifier (preferred) / osascript (fallback)
+```
+
+Entry point: `mac_upkeep.cli:app` (registered in pyproject.toml `[project.scripts]`).
+
+Task execution order defined in `defaults.toml` `[run] order`. Users override in `~/.config/mac-upkeep/config.toml`.
+
+## Key Patterns
+
+### TOML-driven task registry
+
+- **`defaults.toml` is the single source of truth.** Adding a built-in task = 1 TOML entry. No Python code changes needed. The file is bundled via `importlib.resources.files("mac_upkeep")` and loaded at startup.
+- **`TaskDef` fields are minimal.** `defaults.toml` only specifies fields that differ from `TaskDef` dataclass defaults (`frequency="weekly"`, `enabled=True`, `sudo=False`, `shell=""`, `require_file=""`, `timeout=300`). Weekly tasks omit `frequency`.
+- **Config.load() reads user TOML once.** Parsed data is passed to `load_task_defs()` as a dict — avoids double file read. Brewfile and notification settings are extracted from the same parse.
+
+### Detection and execution
+
+- **`detect` is separate from `command`**: `detect` field specifies which binary to check with `shutil.which()`. This is separate from the command that runs. Reason: for sudo tasks, `_build_cmd()` prepends `["sudo", "-n"]` to the command — if detect used `cmd[0]`, it would check `shutil.which("sudo")` instead of the actual tool. Validated against topgrade's `require("binary")` pattern.
+- **`_build_cmd()` composable**: `sudo` and `shell` are independent flags. Both branches (shell vs non-shell) merge before the sudo check. No early return in the shell branch — sudo wraps the entire invocation.
+- **stdin closed for task subprocesses**: `stdin=subprocess.DEVNULL` prevents interactive tool hangs. Mole detects interactive mode via `[[ -t 0 ]]` (stdin is TTY) or unguarded `read_key` calls. Fisher uses `$last_pid` for job control which fails in non-interactive shells ([fisher#608](https://github.com/jorgebucaran/fisher/issues/608)), hence `shell = "fish --interactive -c"`.
+
+### Filter-then-frequency contract
+
+`_run()` has two early-return checks in strict order:
+1. **Filter** (`force_tasks is not None and task_key not in force_tasks`) — unconditional
+2. **Frequency** (`not dry_run and force_tasks is None and not _should_run()`) — conditional
+
+Do not add conditions to the filter or remove the `force_tasks is None` guard from frequency. `require_file` tasks are checked in `run_all_tasks()` BEFORE calling `_run()`, respecting filter→enabled→file order.
+
+### Frequency scheduling
+
+- Thresholds are 6 days for weekly and 27 days for monthly (not 7/30 — buffer for launchd schedule drift after sleep/reboot). State tracked in `~/.local/state/mac-upkeep/last-run.json`.
+- **Safety net**: prevents redundant runs from launchd coalescing, manual `mac-upkeep run`, or formula regressions re-enabling RunAtLoad. Do not remove even with `run_at_load false`. Homebrew defaults `run_at_load` to `true` ([service.rb:55](https://github.com/Homebrew/brew/blob/main/Library/Homebrew/service.rb)) — undocumented in Formula Cookbook.
+- Timestamps only update on successful non-dry-run execution. Corrupt/missing state file silently triggers re-run.
+
+### Output and notifications
+
+- **Interactive detection**: `sys.stdout.isatty()` switches between Rich Live table and Python logging. Same code path, different presentation.
+- **Rich Live TUI state separation**: `_TaskState` holds status/reason/duration; `_generate_table()` renders. Debug output scrolls ABOVE the pinned table via `self._live.console.print()` — never put debug content into `_TaskState`.
+- **Notifications always fire**: `notify()` is called regardless of `output.interactive`. The headless + notification + click-to-act pattern means notifications are the user's feedback channel for scheduled runs.
+- **terminal-notifier preferred**: `shutil.which("terminal-notifier")` tries the richer tool first. Fallback to osascript loses `-group` (dedup), `-activate` (focus terminal), `-open` (click action).
+- **Bundle ID detection chain**: `CMUX_BUNDLE_ID` env var → Ghostty.app plist via `defaults read` → `com.apple.Terminal` fallback.
+- **Rich is a transitive dependency**: `typer>=0.12` requires `rich>=12.3.0`. Using Rich adds zero new runtime dependencies.
+
+### sudo + HOME
+
+`sudo -n` with full path `$BREW_PREFIX/bin/mo`. Sudoers `env_keep += "HOME"` preserves user's home directory (otherwise `HOME=/var/root` and mole misses user caches). The `sudo` field in `TaskDef` exists instead of embedding `sudo` in the command so that: (a) dry-run can skip sudo, (b) `detect` infers the correct binary, (c) `mac-upkeep setup` can generate sudoers rules.
+
+### Brew prefix detection
+
+`get_brew_prefix()` lives in `config.py` (moved from tasks.py). Called once during `Config.load()` for `${BREW_PREFIX}` variable resolution. Subprocess call with architecture fallback — portable across Apple Silicon (`/opt/homebrew`) and Intel (`/usr/local`).
+
+## Non-Obvious Constraints
+
+- `gcloud-cli` is a Homebrew cask, not a formula — can't be a formula dependency. Auto-detected at runtime.
+- `mo_purge` non-interactive mode (stdin closed) auto-selects items not modified in the last 7 days. Interactive mode shows a TUI selector.
+- `mo_optimize` has three unguarded `read_key` calls that block on stdin. With stdin closed, `read` returns non-zero → prompts skipped. Safe operations still run.
+- `uv cache prune` requires `--force` in environments with long-running `uvx` processes (MCP servers). Without it, prune blocks on the cache lock ([astral-sh/uv#16112](https://github.com/astral-sh/uv/issues/16112)).
+- NOPASSWD in sudoers bypasses PAM entirely — no interaction with Touch ID (pam_tid) setup.
+- **launchd PATH requires `std_service_path_env`**: launchd default PATH is `/usr/bin:/bin:/usr/sbin:/sbin`. Without `environment_variables PATH: std_service_path_env` in the formula service block, all Homebrew-installed tools fail `shutil.which()`. Notifications fall back to osascript.
+- **No Python FileHandler for log file**: launchd redirects stderr to the log file. Python `FileHandler` causes duplicate lines. Log rotation handled by macOS newsyslog.d.
+- **newsyslog.d config** printed by `mac-upkeep setup` but NOT auto-installed (requires `sudo tee`).
+- **`terminal-notifier` is optional** — installed via `brew install terminal-notifier`.
+- **Do not open terminal windows from launchd** — fragile (focus stealing, macOS 13+ permission escalation). Use headless + notification + click-to-act.
+- **Testing**: `Config.load()` calls `get_brew_prefix()` which runs `subprocess.run(["brew", "--prefix"])`. Tests that mock `subprocess.run` or `shutil.which` will capture this call too (shared module objects). Mock `mac_upkeep.config.get_brew_prefix` directly in `init` command tests.
+
+## Release Process
+
+Automated via release-please + homebrew-tap dispatch:
+
+1. Commit changes using conventional commits, push to main
+2. release-please creates a release PR (bumps version in `pyproject.toml`, updates CHANGELOG.md)
+3. Release workflow auto-updates `uv.lock` on the PR branch, test.yml validates via `uv lock --check`
+4. Merge the release PR → GitHub release + tag created → `bump-tap` dispatches to homebrew-tap, `pypi-publish` publishes to PyPI
+5. Verify: check homebrew-tap Actions tab for successful formula update
+
+## Reusable Patterns
+
+This repo serves as a reference for Python CLI projects using Typer + UV.
+
+**Copy directly** (adjust versions/paths):
+- `.github/workflows/test.yml` — lint + test CI on macOS
+- `.github/workflows/release.yml` — release-please with GitHub App token + tap dispatch + PyPI Trusted Publishing (OIDC)
+- `release-please-config.json` + `.release-please-manifest.json` — config and version tracking (both required)
+- `pyproject.toml` structure — Hatchling build, Ruff lint+format, pytest config
+- `CONTRIBUTING.md` — dev setup, commit conventions, PR process
+
+**Adapt:**
+- TOML-driven task definitions with `importlib.resources` bundling — for any CLI needing an extensible command registry where adding a task shouldn't require code changes
+- `init` with system detection via `shutil.which()` — for any CLI replacing static example config files with generated, system-aware configs
+- 3-layer config merge (bundled `defaults.toml` → user `config.toml` → env vars) with field-level override — for any CLI needing layered configuration
+- `${VAR}` variable resolution in TOML fields — for portable paths across architectures (`${BREW_PREFIX}` resolves differently on Apple Silicon vs Intel)
+- Rich Live table TUI (`isatty()` detection + `_TaskState` + `Live` + `console.print()` above pinned table) for any CLI running interactively AND via scheduler
+- terminal-notifier with osascript fallback for any macOS launchd service needing actionable notifications
+- `repository_dispatch` + GitHub App for cross-repo automation
+- `subprocess.run(stdin=subprocess.DEVNULL)` for any CLI orchestrator wrapping interactive tools
+- Per-task frequency scheduling with XDG state file + threshold buffers for any periodic CLI tool
+- newsyslog.d config generation via setup command for any macOS launchd service needing log rotation
+
+**Project-specific (do not copy):**
+- Mole CLI wrapper and sudo/HOME/sudoers configuration
+- Homebrew tap formula + poet resource regeneration

mac_upkeep-2.1.0/CONTRIBUTING.md

@@ -0,0 +1,58 @@
+# Contributing
+
+## Development Setup
+
+> **Note:** macOS is required for development and testing.
+
+```bash
+git clone https://github.com/calvindotsg/mac-upkeep.git
+cd mac-upkeep
+uv sync
+```
+
+## Code Style
+
+```bash
+uv run ruff check src/ tests/     # Lint
+uv run ruff format src/ tests/    # Format
+```
+
+## Testing
+
+```bash
+uv run pytest                     # Run tests
+uv run pytest --cov               # With coverage
+```
+
+## Dependencies
+
+After modifying `pyproject.toml` dependencies, run `uv lock` to update the lockfile. CI runs `uv lock --check` and will fail on stale lockfiles.
+
+## Commit Conventions
+
+This project uses [Conventional Commits v1.0.0](https://www.conventionalcommits.org/en/v1.0.0/).
+
+| Type | When |
+|------|------|
+| `feat` | New task, CLI subcommand, or user-facing behavior |
+| `fix` | Bug fix (wrong exit code, broken task, etc.) |
+| `docs` | README, CLAUDE.md, CONTRIBUTING.md changes |
+| `chore` | Dependencies, config files |
+| `ci` | GitHub Actions workflows |
+| `test` | Test additions or fixes |
+| `refactor` | Code restructuring without behavior change |
+
+Examples:
+
+```
+feat: add docker system prune task
+fix: handle missing gcloud gracefully
+docs: update README with new task table
+chore: update typer to 0.13
+ci: add macOS runner to test matrix
+test: add test for mo purge failure path
+```
+
+## Release Process
+
+Automated via [release-please](https://github.com/googleapis/release-please). Use conventional commits — `feat:` and `fix:` trigger version bumps. See CLAUDE.md for full flow.

mac_upkeep-2.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 calvindotsg
+
+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.

mac_upkeep-2.1.0/PKG-INFO

@@ -0,0 +1,145 @@
+Metadata-Version: 2.4
+Name: mac-upkeep
+Version: 2.1.0
+Summary: Automated macOS maintenance CLI
+Project-URL: Homepage, https://github.com/calvindotsg/maintenance
+Project-URL: Repository, https://github.com/calvindotsg/maintenance
+Project-URL: Issues, https://github.com/calvindotsg/maintenance/issues
+Project-URL: Changelog, https://github.com/calvindotsg/maintenance/blob/main/CHANGELOG.md
+Author: Calvin
+License-Expression: MIT
+License-File: LICENSE
+Keywords: automation,cli,homebrew,macos,maintenance
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Environment :: MacOS X
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: System :: Systems Administration
+Requires-Python: >=3.11
+Requires-Dist: typer>=0.12
+Description-Content-Type: text/markdown
+
+# mac-upkeep
+
+Automated macOS maintenance CLI. Runs weekly via `brew services` to keep your dev environment clean.
+
+> **Requires macOS** — uses Homebrew, launchd, and macOS notifications.
+
+## Install
+
+```bash
+brew install calvindotsg/tap/mac-upkeep
+brew services start mac-upkeep  # Monday 12 PM weekly
+```
+
+Or via pip/uvx:
+
+```bash
+pip install mac-upkeep
+uvx mac-upkeep run       # one-off without installing
+```
+
+## Tasks
+
+Homebrew updates, dev tool cache pruning (gcloud, pnpm, uv), Fish plugin updates, system optimization via [mole](https://github.com/nicehash/mole), and Brewfile enforcement.
+
+```bash
+mac-upkeep tasks  # See all tasks with frequency and last-run status
+```
+
+Tasks auto-detect installed tools — missing tools are skipped. Each task runs on a weekly or monthly schedule. Use `--force <task>` to run a specific task on demand.
+
+## Usage
+
+```bash
+mac-upkeep run                       # Run tasks (frequency-checked)
+mac-upkeep run --dry-run             # Preview without executing
+mac-upkeep run --force brew_update   # Run only brew_update
+mac-upkeep run --force all           # Run all, ignoring schedule
+mac-upkeep run --debug               # Verbose output
+mac-upkeep tasks                     # List tasks with status
+mac-upkeep init                      # Generate config (detects your tools)
+mac-upkeep show-config --default     # Show all available task options
+mac-upkeep show-config               # Show your config overrides
+mac-upkeep setup                     # Print sudoers rules
+mac-upkeep status                    # Show brew service status
+mac-upkeep logs                      # View last 20 log lines
+mac-upkeep logs -f                   # Follow logs
+mac-upkeep --version                 # Show version
+```
+
+## Configuration
+
+Works out of the box with zero configuration. To customize, generate a starter config:
+
+```bash
+mac-upkeep init
+```
+
+This probes your system, detects installed tools, and writes a commented config to `~/.config/mac-upkeep/config.toml`. Only detected tasks are listed. Built-in defaults apply automatically — uncomment lines to override.
+
+To see all available tasks and options:
+
+```bash
+mac-upkeep show-config --default
+```
+
+### Override examples
+
+```toml
+# ~/.config/mac-upkeep/config.toml
+
+# Disable a task
+[tasks.gcloud]
+enabled = false
+
+# Change frequency (weekly or monthly)
+[tasks.brew_update]
+frequency = "monthly"
+
+# Set Brewfile path explicitly
+[paths]
+brewfile = "~/.config/Brewfile"
+```
+
+### Custom tasks
+
+Add your own tasks using the same format:
+
+```toml
+[tasks.docker_prune]
+description = "Prune Docker system"
+command = "docker system prune -f"
+detect = "docker"
+frequency = "monthly"
+
+# Control execution order
+[run]
+order = ["brew_update", "brew_upgrade", "docker_prune", "brew_cleanup", "brew_bundle"]
+```
+
+### Environment variables
+
+```bash
+MAC_UPKEEP_GCLOUD=false mac-upkeep run              # Disable a task
+MAC_UPKEEP_GCLOUD_FREQUENCY=monthly mac-upkeep run  # Override frequency
+```
+
+### Sudoers
+
+`mo_clean` and `mo_optimize` require passwordless sudo for the `mo` binary:
+
+```bash
+mac-upkeep setup | sudo tee /etc/sudoers.d/mac-upkeep && sudo chmod 0440 /etc/sudoers.d/mac-upkeep
+sudo visudo -c
+```
+
+## License
+
+MIT

mac_upkeep-2.1.0/README.md

@@ -0,0 +1,118 @@
+# mac-upkeep
+
+Automated macOS maintenance CLI. Runs weekly via `brew services` to keep your dev environment clean.
+
+> **Requires macOS** — uses Homebrew, launchd, and macOS notifications.
+
+## Install
+
+```bash
+brew install calvindotsg/tap/mac-upkeep
+brew services start mac-upkeep  # Monday 12 PM weekly
+```
+
+Or via pip/uvx:
+
+```bash
+pip install mac-upkeep
+uvx mac-upkeep run       # one-off without installing
+```
+
+## Tasks
+
+Homebrew updates, dev tool cache pruning (gcloud, pnpm, uv), Fish plugin updates, system optimization via [mole](https://github.com/nicehash/mole), and Brewfile enforcement.
+
+```bash
+mac-upkeep tasks  # See all tasks with frequency and last-run status
+```
+
+Tasks auto-detect installed tools — missing tools are skipped. Each task runs on a weekly or monthly schedule. Use `--force <task>` to run a specific task on demand.
+
+## Usage
+
+```bash
+mac-upkeep run                       # Run tasks (frequency-checked)
+mac-upkeep run --dry-run             # Preview without executing
+mac-upkeep run --force brew_update   # Run only brew_update
+mac-upkeep run --force all           # Run all, ignoring schedule
+mac-upkeep run --debug               # Verbose output
+mac-upkeep tasks                     # List tasks with status
+mac-upkeep init                      # Generate config (detects your tools)
+mac-upkeep show-config --default     # Show all available task options
+mac-upkeep show-config               # Show your config overrides
+mac-upkeep setup                     # Print sudoers rules
+mac-upkeep status                    # Show brew service status
+mac-upkeep logs                      # View last 20 log lines
+mac-upkeep logs -f                   # Follow logs
+mac-upkeep --version                 # Show version
+```
+
+## Configuration
+
+Works out of the box with zero configuration. To customize, generate a starter config:
+
+```bash
+mac-upkeep init
+```
+
+This probes your system, detects installed tools, and writes a commented config to `~/.config/mac-upkeep/config.toml`. Only detected tasks are listed. Built-in defaults apply automatically — uncomment lines to override.
+
+To see all available tasks and options:
+
+```bash
+mac-upkeep show-config --default
+```
+
+### Override examples
+
+```toml
+# ~/.config/mac-upkeep/config.toml
+
+# Disable a task
+[tasks.gcloud]
+enabled = false
+
+# Change frequency (weekly or monthly)
+[tasks.brew_update]
+frequency = "monthly"
+
+# Set Brewfile path explicitly
+[paths]
+brewfile = "~/.config/Brewfile"
+```
+
+### Custom tasks
+
+Add your own tasks using the same format:
+
+```toml
+[tasks.docker_prune]
+description = "Prune Docker system"
+command = "docker system prune -f"
+detect = "docker"
+frequency = "monthly"
+
+# Control execution order
+[run]
+order = ["brew_update", "brew_upgrade", "docker_prune", "brew_cleanup", "brew_bundle"]
+```
+
+### Environment variables
+
+```bash
+MAC_UPKEEP_GCLOUD=false mac-upkeep run              # Disable a task
+MAC_UPKEEP_GCLOUD_FREQUENCY=monthly mac-upkeep run  # Override frequency
+```
+
+### Sudoers
+
+`mo_clean` and `mo_optimize` require passwordless sudo for the `mo` binary:
+
+```bash
+mac-upkeep setup | sudo tee /etc/sudoers.d/mac-upkeep && sudo chmod 0440 /etc/sudoers.d/mac-upkeep
+sudo visudo -c
+```
+
+## License
+
+MIT