mac-upkeep 3.0.2__tar.gz → 3.0.4__tar.gz

mac_upkeep-3.0.4/.github/dependabot.yml

@@ -0,0 +1,20 @@
+# Actions are pinned to full commit SHAs, which is only safe if the pins are
+# maintained rather than frozen. Dependabot updates a SHA pin and rewrites the
+# trailing `# vX.Y.Z` comment alongside it.
+version: 2
+updates:
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+    commit-message:
+      prefix: ci
+      # NOTE: `ci` DOES cut a release in this repo - v3.0.2 was produced by a single
+      # `ci:` commit. So each grouped Dependabot PR will open a release-please PR.
+      # That is triage, not breakage: close a release PR whose only contents are
+      # action-pin bumps, exactly as for any other ci/docs/chore-only release PR.
+      # Weekly is kept deliberately - stale SHA pins are the risk this file exists
+      # to manage, and pin freshness matters more than release-PR noise.
+    groups:
+      actions:
+        patterns: ["*"]

mac_upkeep-3.0.4/.github/workflows/pr-checks.yml

@@ -0,0 +1,42 @@
+# Reject a `Release-As:` trailer at the point it would enter the repository.
+#
+# squash_merge_commit_message is COMMIT_MESSAGES, so a squashed PR's body is the
+# contributor's own commit messages. release-please parses a `Release-As:` footer
+# and short-circuits all version derivation, so a merged benign-looking PR can
+# dictate the published version -- and PyPI never permits version reuse.
+#
+# An anchored semver check in release.yml is NOT sufficient on its own: the
+# payload `Release-As: 99.0.0` yields the perfectly well-formed tag v99.0.0.
+# release.yml's verify-version job catches the jump; this catches the trailer.
+name: pr-checks
+on:
+  pull_request:
+    branches: [main]
+permissions:
+  contents: read
+jobs:
+  no-release-as:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          fetch-depth: 0
+      - name: Reject Release-As trailers
+        env:
+          BASE: ${{ github.event.pull_request.base.sha }}
+          HEAD: ${{ github.event.pull_request.head.sha }}
+          # squash_merge_commit_title is COMMIT_OR_PR_TITLE, so for a multi-commit PR
+          # the squashed subject comes from the PR title -- which is not in git log.
+          PR_TITLE: ${{ github.event.pull_request.title }}
+          PR_BODY: ${{ github.event.pull_request.body }}
+        run: |
+          set -euo pipefail
+          {
+            git log --format='%B' "$BASE..$HEAD"
+            printf '%s\n%s\n' "$PR_TITLE" "$PR_BODY"
+          } > /tmp/release-as-scan.txt
+          if grep -qiE '^[[:space:]]*Release-As:' /tmp/release-as-scan.txt; then
+            echo "::error::A Release-As trailer overrides release-please version derivation. Remove it."
+            exit 1
+          fi
+          echo "No Release-As trailer found."

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

@@ -0,0 +1,176 @@
+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@bcd2ba49218906704ab6c1aa796996da409d3eb1 # v3.2.0
+        id: app-token
+        with:
+          client-id: ${{ vars.RELEASE_PLEASE_CLIENT_ID }}
+          private-key: ${{ secrets.RELEASE_PLEASE_PRIVATE_KEY }}
+      - id: release
+        uses: googleapis/release-please-action@45996ed1f6d02564a971a2fa1b5860e934307cf7 # v5.0.0
+        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@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        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@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+
+      - name: Update uv.lock in release PR
+        if: ${{ steps.release.outputs.pr && !steps.release.outputs.release_created }}
+        env:
+          GH_TOKEN: ${{ steps.app-token.outputs.token }}
+          APP_SLUG: ${{ steps.app-token.outputs.app-slug }}
+        run: |
+          uv lock
+          if git diff --quiet uv.lock; then
+            echo "uv.lock already up to date"
+          else
+            BOT_USER_ID=$(gh api "/users/${APP_SLUG}[bot]" --jq .id)
+            git config user.name "${APP_SLUG}[bot]"
+            git config user.email "${BOT_USER_ID}+${APP_SLUG}[bot]@users.noreply.github.com"
+            git add uv.lock
+            git commit -m "chore: update uv.lock"
+            git push
+          fi
+
+  # Gate BOTH release_created consumers. release-please honours a `Release-As:`
+  # footer and short-circuits all version derivation, and squash merges put a
+  # contributor's own commit messages into the commit that lands on main -- so a
+  # merged PR can dictate the published version. An anchored semver regex alone
+  # does NOT help: the payload `Release-As: 99.0.0` produces the perfectly
+  # well-formed tag v99.0.0. The size of the jump is what gives it away.
+  verify-version:
+    needs: release-please
+    if: ${{ needs.release-please.outputs.release_created == 'true' }}
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          fetch-depth: 0
+      - name: Refuse implausible version jumps
+        env:
+          TAG: ${{ needs.release-please.outputs.tag_name }}
+        run: |
+          set -euo pipefail
+          [[ "$TAG" =~ ^v([0-9]+)\.([0-9]+)\.([0-9]+)$ ]] || {
+            echo "::error::Refusing malformed tag: $TAG"; exit 1; }
+          new_major=${BASH_REMATCH[1]}; new_minor=${BASH_REMATCH[2]}; new_patch=${BASH_REMATCH[3]}
+
+          # Compare against the highest EXISTING release tag, not the manifest:
+          # by the time this job runs the release PR has merged, so
+          # .release-please-manifest.json already holds the new version and would
+          # always compare equal.
+          prev=$(git tag --list 'v[0-9]*.[0-9]*.[0-9]*' --sort=-v:refname \
+                 | grep -v -x -F "$TAG" | head -n1 || true)
+          if [[ -z "$prev" ]]; then
+            echo "No previous release tag; skipping jump check."
+            exit 0
+          fi
+          [[ "$prev" =~ ^v([0-9]+)\.([0-9]+)\.([0-9]+)$ ]] || {
+            echo "::error::Unparseable previous tag: $prev"; exit 1; }
+          cur_major=${BASH_REMATCH[1]}; cur_minor=${BASH_REMATCH[2]}; cur_patch=${BASH_REMATCH[3]}
+
+          # Allowlist the three bumps release-please can actually produce, rather than
+          # bounding only upward major/minor movement -- a one-sided check accepts any
+          # version DECREASE and any patch jump, so `Release-As: 3.0.99` sails through.
+          if   (( new_major == cur_major + 1 && new_minor == 0 && new_patch == 0 )); then :
+          elif (( new_major == cur_major && new_minor == cur_minor + 1 && new_patch == 0 )); then :
+          elif (( new_major == cur_major && new_minor == cur_minor \
+                  && new_patch == cur_patch + 1 )); then :
+          else
+            echo "::error::Implausible bump $prev -> $TAG; a Release-As trailer may have been merged."
+            echo "::error::Expected one of: v$((cur_major + 1)).0.0, v${cur_major}.$((cur_minor + 1)).0, v${cur_major}.${cur_minor}.$((cur_patch + 1))"
+            exit 1
+          fi
+          echo "$prev -> $TAG is a normal bump."
+
+  # Build is separated from publish so that anything injected into the build
+  # environment cannot reach the OIDC credentials. `[build-system] requires` is
+  # unbounded and uv.lock does not cover build requirements at all, so six
+  # packages resolve fresh from the live index and then execute here. PyPA's own
+  # guidance: "only set the id-token: write permission in the job that does
+  # publishing... try to separate building from publishing".
+  build:
+    needs: [release-please, verify-version]
+    if: ${{ needs.release-please.outputs.release_created == 'true' }}
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+      - run: uv build
+      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
+        with:
+          name: dist
+          path: dist/
+          if-no-files-found: error
+
+  pypi-publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2
+
+  bump-tap:
+    needs: [release-please, verify-version]
+    if: ${{ needs.release-please.outputs.release_created == 'true' }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1 # v3.2.0
+        id: app-token
+        with:
+          client-id: ${{ vars.RELEASE_PLEASE_CLIENT_ID }}
+          private-key: ${{ secrets.RELEASE_PLEASE_PRIVATE_KEY }}
+          repositories: homebrew-tap
+      # Build the payload with jq rather than string interpolation, so payload
+      # STRUCTURE can never depend on tag content. A double quote is a legal git
+      # ref character, and an interpolated tag containing one produced malformed
+      # JSON that silently broke the tap bump.
+      - id: payload
+        env:
+          TAG: ${{ needs.release-please.outputs.tag_name }}
+        run: |
+          set -euo pipefail
+          json=$(jq -cn --arg tag "$TAG" '{
+            formula: "mac-upkeep",
+            version: $tag,
+            type: "python",
+            url: ("https://github.com/calvindotsg/mac-upkeep/archive/refs/tags/" + $tag + ".tar.gz")
+          }')
+          echo "json=$json" >> "$GITHUB_OUTPUT"
+      - name: Dispatch formula update
+        uses: peter-evans/repository-dispatch@28959ce8df70de7be546dd1250a005dd32156697 # v4.0.1
+        with:
+          token: ${{ steps.app-token.outputs.token }}
+          repository: calvindotsg/homebrew-tap
+          event-type: formula-update
+          client-payload: ${{ steps.payload.outputs.json }}

{mac_upkeep-3.0.2 → mac_upkeep-3.0.4}/.github/workflows/test.yml

@@ -11,8 +11,8 @@ jobs:
       matrix:
         python-version: ["3.11", "3.12", "3.13"]
     steps:
-      - uses: actions/checkout@v7
-      - uses: astral-sh/setup-uv@v10.0.1
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
         with:
           python-version: ${{ matrix.python-version }}
       - run: uv lock --check

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

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

{mac_upkeep-3.0.2 → mac_upkeep-3.0.4}/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## [3.0.4](https://github.com/calvindotsg/mac-upkeep/compare/v3.0.3...v3.0.4) (2026-08-20)
+
+
+### Bug Fixes
+
+* close six findings from security audit run-1 ([#53](https://github.com/calvindotsg/mac-upkeep/issues/53)) ([c83f865](https://github.com/calvindotsg/mac-upkeep/commit/c83f86587c435a07356639a06c26300a829d67cc))
+
+
+### CI/CD
+
+* harden the release pipeline against findings F-05, F-06 and F-11 ([#54](https://github.com/calvindotsg/mac-upkeep/issues/54)) ([1d1fb5f](https://github.com/calvindotsg/mac-upkeep/commit/1d1fb5fd2e99e0e0d9bc6bd72da34e244fce44f4))
+
+## [3.0.3](https://github.com/calvindotsg/mac-upkeep/compare/v3.0.2...v3.0.3) (2026-08-17)
+
+
+### Bug Fixes
+
+* report handler tasks as dry-run instead of as having executed ([#51](https://github.com/calvindotsg/mac-upkeep/issues/51)) ([1db8054](https://github.com/calvindotsg/mac-upkeep/commit/1db8054d65da313f6fe4d51f00932d126fc59c79))
+
 ## [3.0.2](https://github.com/calvindotsg/mac-upkeep/compare/v3.0.1...v3.0.2) (2026-08-16)
 
 

{mac_upkeep-3.0.2 → mac_upkeep-3.0.4}/CLAUDE.md

@@ -23,9 +23,10 @@ defaults.toml → bundled task definitions, 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, format_last_run(), format_next_run(), ANSI stripping
+                frequency scheduling, format_last_run(), format_next_run()
 cli.py        → Typer app: run, tasks, init, show-config, setup, status (dashboard), logs, notify-test
-output.py     → TaskResult dataclass, Rich Live table TUI (interactive), Python logging (non-interactive)
+output.py     → TaskResult dataclass, Rich Live table TUI (interactive), Python logging
+                (non-interactive), strip_control_sequences() (shared sanitiser)
 notify.py     → macOS notifications via terminal-notifier (preferred) / osascript (fallback)
 ```
 
@@ -103,6 +104,95 @@ Reclaims Electron/editor caches mole's classifier structurally misses (`Service
 - **`_is_safe_target`** refuses anything not ≥2 segments below `~/Library/Application Support`, and refuses symlinks — mirrors mole's `validate_path_for_deletion`.
 - Ships **`enabled = false`** (opt-in: it's `rm -rf` and reaches all users, like `pnpm`). Targets default to Notion + Zed; override with `[[editor_cache.apps]]` (`name`/`process`/`min_size_mb`/`targets`) in user config.
 
+### Fail-closed contracts (security audit run-1)
+
+Four gates were changed from fail-open to fail-closed. Each looks like an inconsequential
+default until you notice which direction it fails in; do not "simplify" them back.
+
+- **`Config.is_enabled()` returns `False` for an unknown key**, not `True`. Every caller
+  derives the key from a real `TaskDef` via `normalize_task_key()`, so a miss means the two
+  keyspaces diverged — which must never resolve to "run it". This is only safe *because*
+  keys are normalised at load: alone, it would stop a legitimately-enabled custom task with
+  a capitalised name from ever running. The two changes ship together or not at all.
+- **`normalize_task_key()` is applied once in `load_task_defs()`** — to default keys, user
+  keys, and `run.order` entries — so `tasks.py`'s `task_key` derivation is an identity
+  operation. Before, `[tasks.DockerPrune]` was stored raw, `is_enabled` missed, and
+  `enabled = false` was ignored while the dashboard cheerfully printed "disabled". Two names
+  normalising to one key is a `ValueError`, because otherwise the winner depends on TOML
+  table order.
+- **User field types are validated** (`_FIELD_TYPES` + `_check_field`) in *both* the override
+  branch and `_parse_task_def`. `enabled = "false"` — quoting a TOML boolean, the most common
+  TOML mistake — used to leave a truthy string and run the task anyway; `sudo = "false"`
+  *added* `sudo -n`. `bool` subclasses `int`, so `timeout = true` needs the explicit
+  `isinstance(value, bool)` rejection.
+- **`MAC_UPKEEP_<TASK>` is an allowlist of truthy strings**, not a denylist of falsy ones.
+  `off`, `disabled` and `""` previously all enabled the task.
+
+### require_file must distinguish "unset" from "resolved to nothing"
+
+`TaskDef.require_file_declared` records that the template was non-empty *before* variable
+resolution. The old guard `if td.require_file and not Path(...).is_file()` short-circuited on
+the empty string, so `brew_bundle` ran `--file=` — which Homebrew treats as absent, falling
+back to `$PWD/Brewfile`, evaluating it as Ruby and then uninstalling everything it does not
+list. It also failed on every run for every user with no Brewfile, burning retry backoff and
+a notification each time. Related: `_discover_brewfile()` must never regain a CWD-relative
+candidate, and `run_task` passes `cwd="/"` so no task can be steered by the caller's
+directory (launchd already provides `/`).
+
+### git_sync: repository config is untrusted input
+
+A repo's own `.git/config` can make git execute a command, and `safe.directory` does not
+help — it keys on ownership, and an extracted archive is owned by the invoking user.
+`_run_git` therefore prepends `_trusted_overrides()` to **every** call, not just `pull`:
+`git status --porcelain`, the `skip_dirty` *safety* check, is itself enough to trigger
+`core.fsmonitor` and filter drivers. All sinks below were verified to fire on git 2.55.
+
+- `_STATIC_OVERRIDES` are unconditional: `core.fsmonitor=`, `core.hooksPath=/dev/null`,
+  `protocol.ext.allow=never` (a repo can set `protocol.ext.allow=always` and get `ext::`
+  back), `protocol.file.allow=never` (the only working block for `remote.<n>.uploadpack`,
+  which a per-name `-c` override does *not* beat), and `protocol.git.allow=never` (the only
+  working block for `core.gitProxy` — `-c core.gitProxy=` does **not** disable it).
+- **Multi-valued and single-valued keys need opposite treatment, and confusing them is a
+  live outage.** `_INHERITED_LIST_KEYS` (`credential.helper`) is reset with an empty entry —
+  which for a list key means "discard what git accumulated" — then the user's global/system
+  values are appended back. A bare reset without the re-add would break nearly every macOS
+  user, because Homebrew git ships `credential.helper = osxkeychain` at *system* scope, and
+  the helper fires on an HTTP 401 despite `GIT_ASKPASS` and `GIT_TERMINAL_PROMPT`.
+  `_INHERITED_SCALAR_KEYS` (`core.sshCommand`) must instead be **set** to the user's value
+  or to an explicit default. An empty entry there is not a reset: git execs the empty string,
+  and every SSH remote fails with `error: cannot run :` on every run — a retry storm for the
+  default configuration, which is the one the README documents.
+- **Known residual, do not claim otherwise:** `filter.<driver>.clean` from a planted
+  `.gitattributes` still executes on `status`. Driver names are arbitrary, so no fixed `-c`
+  set covers them, and git has no "ignore repo-local config" switch. Enrolment discipline is
+  the real control. Before adding a "this is the only remaining sink" claim anywhere, re-derive
+  the list against the installed git — `core.gitProxy` was missed on the first pass precisely
+  because the sink list was taken as complete rather than re-tested.
+- `_trusted_cache` is process-global; `tests/conftest.py` seeds it with the static half so
+  argv is deterministic and the `git config` probes are not caught by tests that patch
+  `git_sync.subprocess.run`. Tests exercising the inherited half reset it to `None`.
+
+### Untrusted text is never Rich markup
+
+`output.py` renders subprocess and remote-derived text as a literal `rich.text.Text`, never
+interpolated into a markup string — in `task_debug` *and* in `summary`'s failure detail. A
+bracketed path like `[/usr/local]` raises `MarkupError` (which used to abort the run and
+leave the cursor hidden, since `Live.__exit__` never ran), and `[link=…]` renders a real
+OSC-8 hyperlink with attacker-chosen target and anchor text inside our own failure summary.
+`strip_control_sequences()` in `output.py` is the single sanitiser for both `tasks.py` and
+`git_sync.py`; it covers all escape sequences plus stray C0/C1 characters, not just SGR
+colour codes. It deliberately does **not** touch `[` — markup is handled by `Text`, not by
+escaping.
+
+### No single task may abort the run
+
+`run_task` catches `OSError` (a shim whose shebang interpreter vanished is the routine
+trigger), `run_all_tasks` wraps each task in a catch-all, and `cli.run` passes its own
+`results` list in so `output.summary()` and `notify()` still describe whatever completed.
+Under launchd the notification is the user's only feedback channel, and `summary()` is what
+exits the Rich `Live` context. The dead `CalledProcessError` branch was removed — `check=True`
+is never passed, so it read as coverage that did not exist.
+
 ### sudo + HOME/USER/LOGNAME
 
 `sudo -n` with full path `$BREW_PREFIX/bin/mo`. Sudoers `env_keep += "HOME USER LOGNAME"`. 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.
@@ -139,7 +229,7 @@ env USER=root MOLE_DRY_RUN=1 mo optimize | grep -A2 'Permission Repair' # enters
 - **Config/state paths are import-time constants**, so setting `XDG_CONFIG_HOME` from a fixture is too late — patch `mac_upkeep.config.DEFAULT_CONFIG_PATH`, `mac_upkeep.cli.DEFAULT_CONFIG_PATH`, `tasks._STATE_FILE` and `tasks._RETRY_FILE` objects directly. `Config.load(path=None)` resolves `DEFAULT_CONFIG_PATH` **at call time**; as a default argument it would bind at def time and silently ignore every patch.
 - **`git_sync` SSH auth under launchd** relies on `~/.ssh/config` `IdentityAgent` (path-based, e.g. 1Password socket). `SSH_AUTH_SOCK` env vars are NOT inherited by LaunchAgents, so env-based agent forwarding won't work here — the `IdentityAgent` directive is the supported path.
 - **`git_sync` forces `GIT_TERMINAL_PROMPT=0` and defaults `GIT_ASKPASS=/usr/bin/true`** (user-set `GIT_ASKPASS` is respected) — fail-fast on auth misconfiguration instead of stalling to the 60 s subprocess timeout. A genuine stall (network/server hang) still hits the timeout, so `_run_git` catches `subprocess.TimeoutExpired` and returns a synthetic `CompletedProcess(returncode=124, stderr="timed out after {timeout}s")`. That marks only the affected repo failed and lets the loop continue — a hung pull cannot abort the whole run (which would otherwise skip `output.summary()`/`notify()` and later tasks).
-- **`git_sync` failure reasons belong in the aggregate `TaskResult`, not only `output.task_debug()`** — debug output is suppressed without `--debug`, so the log recorded `13 failed: <names>` with no cause, which is not diagnosable after the fact. `_format_failures()` groups repos by reason because the common case is one shared cause (a network drop failing every repo at once); it caps names per group and truncates long messages so a 16-repo outage cannot blow up the log line or the notification body.
+- **`git_sync` failure reasons belong in the aggregate `TaskResult`, not only `output.task_debug()`** — debug output is suppressed without `--debug` on the non-interactive path (`Output.debug` is set but not consulted by the interactive branch, so a TTY always sees it), so the log recorded `13 failed: <names>` with no cause, which is not diagnosable after the fact. `_format_failures()` groups repos by reason because the common case is one shared cause (a network drop failing every repo at once); it caps names per group and truncates long messages so a 16-repo outage cannot blow up the log line or the notification body.
 
 ## Release Process
 

{mac_upkeep-3.0.2 → mac_upkeep-3.0.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: mac-upkeep
-Version: 3.0.2
+Version: 3.0.4
 Summary: Automated macOS maintenance CLI
 Project-URL: Homepage, https://github.com/calvindotsg/mac-upkeep
 Project-URL: Repository, https://github.com/calvindotsg/mac-upkeep
@@ -127,6 +127,23 @@ frequency = "monthly"
 brewfile = "~/.config/Brewfile"
 ```
 
+Task fields are type-checked. TOML booleans are unquoted — `enabled = false`, not
+`enabled = "false"` — and a quoted one is now rejected with an error rather than
+silently leaving the task enabled. Task names are matched case- and space-insensitively
+(`[tasks.Docker Prune]` and `[tasks.docker_prune]` are the same task, and declaring both
+is an error).
+
+#### Brewfile discovery
+
+With no `[paths] brewfile` and no `MAC_UPKEEP_BREWFILE`/`HOMEBREW_BUNDLE_FILE`, only two
+absolute locations are searched: `$XDG_CONFIG_HOME/Brewfile` (default `~/.config/Brewfile`)
+and `~/.Brewfile`. **The current working directory is deliberately not searched.**
+`brew bundle` evaluates a Brewfile as Ruby and `brew_bundle` runs `cleanup --force`, so a
+CWD-relative lookup made whichever project directory your shell happened to be in able to
+run code and uninstall every package it did not list. If no Brewfile is found the task
+skips; it no longer runs with an empty `--file=`, which Homebrew resolved back to
+`$PWD/Brewfile`.
+
 ### Custom tasks
 
 Add your own tasks using the same format:
@@ -158,6 +175,32 @@ skip_dirty = true         # skip repos with uncommitted changes
 
 Each repo is skipped with a reason if it's not a git repo, has no remote, has no upstream branch, or (when `skip_dirty = true`) has uncommitted changes.
 
+#### Only enrol repositories you created
+
+**A git repository's own `.git/config` can make git execute commands.** Point a `repos` glob only at directories you created yourself — never at a downloads, sync, backup, or vendor-drop directory. A tree that arrives by archive, restore, or file sync brings its `.git/config` and `.git/hooks` with it, and `safe.directory` does not help: it keys on ownership, and anything you unpacked is owned by you. A plain `git clone` does *not* carry these, so cloning is unaffected.
+
+mac-upkeep neutralises the directives it can, on every git call — not just on `pull`, because `git status --porcelain` (the `skip_dirty` check itself) is enough to trigger some of them:
+
+| Neutralised | How |
+|---|---|
+| `core.fsmonitor` | reset to empty |
+| `.git/hooks/*` | `core.hooksPath=/dev/null` |
+| `credential.helper` | list reset, then your own global/system helpers re-added |
+| `core.sshCommand` | set to your own global/system value, else explicitly `ssh` |
+| `ext::` transport | `protocol.ext.allow=never` |
+| `remote.<name>.uploadpack` | `protocol.file.allow=never` |
+| `core.gitProxy` | `protocol.git.allow=never` |
+
+Note the asymmetry in the middle two rows. `credential.helper` is multi-valued, so an empty entry resets git's accumulated list. `core.sshCommand` is single-valued, so an empty entry is not a reset — git would try to execute the empty string and every SSH remote would fail. Single-valued keys are therefore *set*, never blanked.
+
+Three consequences worth knowing:
+
+- **Local-path remotes no longer work** under git_sync (`fatal: transport 'file' not allowed`). This is deliberate — it is what closes the `uploadpack` execution path. Pull from a bare mirror on an external disk outside mac-upkeep.
+- **`git://` remotes no longer work** (`fatal: transport 'git' not allowed`). Also deliberate: `core.gitProxy` runs an arbitrary command for that transport and cannot be neutralised any other way. `git://` is unauthenticated and unencrypted; use SSH or HTTPS.
+- **Repository hooks do not run** during git_sync, so a `post-merge` hook that installs dependencies will not fire on an unattended pull.
+
+This is defence in depth, not a sandbox. Git has no "ignore this repository's config" switch. The known remaining execution path is `filter.<driver>.clean` from a planted `.gitattributes`, which fires on `git status`: driver names are arbitrary, so no fixed override covers them. Enrolment discipline is the control that actually holds.
+
 #### Authentication
 
 Any of the following work under launchd without mac-upkeep-side configuration:
@@ -175,6 +218,11 @@ MAC_UPKEEP_GCLOUD=false mac-upkeep run              # Disable a task
 MAC_UPKEEP_GCLOUD_FREQUENCY=monthly mac-upkeep run  # Override frequency
 ```
 
+`MAC_UPKEEP_<TASK>` enables the task only for an explicitly truthy value —
+`true`, `1`, `yes`, or `on`. **Anything else disables it**, including `off`, `disabled`
+and the empty string, which previously all *enabled* the task by falling through a
+denylist of `false`/`0`/`no`.
+
 ### Sudoers
 
 `mo_clean` and `mo_optimize` require passwordless sudo for the `mo` binary:
@@ -195,6 +243,22 @@ Validate before installing — a malformed file in `/etc/sudoers.d/` can lock yo
 >
 > 3.0.0 generates `env_keep += "HOME USER LOGNAME"`. Verify with `sudo -n $(brew --prefix)/bin/mo optimize </dev/null >/dev/null; echo $?` — it should print `0`.
 
+### Log file permissions
+
+`mac-upkeep setup` now prints the `newsyslog.d` line with mode **640** instead of 644. The
+log records `git_sync` failures by repository name, which enumerates your private and
+employer-internal repositories, and `$(brew --prefix)/var/log` is world-traversable — unlike
+`~/Library`, nothing else gates it. Owner plus the `admin` group keeps `mac-upkeep logs`
+working.
+
+> **⚠ Already installed?** Like the sudoers file, `/etc/newsyslog.d/mac-upkeep.conf` is
+> **not** upgraded by `brew upgrade`, and existing log files keep their 644 mode. Rewrite
+> the conf from `mac-upkeep setup`, then:
+>
+> ```bash
+> sudo chmod 640 "$(brew --prefix)"/var/log/mac-upkeep.log*
+> ```
+
 ## Contributing
 
 See [CONTRIBUTING.md](https://github.com/calvindotsg/mac-upkeep/blob/main/CONTRIBUTING.md) for development setup and conventions.

{mac_upkeep-3.0.2 → mac_upkeep-3.0.4}/README.md

@@ -100,6 +100,23 @@ frequency = "monthly"
 brewfile = "~/.config/Brewfile"
 ```
 
+Task fields are type-checked. TOML booleans are unquoted — `enabled = false`, not
+`enabled = "false"` — and a quoted one is now rejected with an error rather than
+silently leaving the task enabled. Task names are matched case- and space-insensitively
+(`[tasks.Docker Prune]` and `[tasks.docker_prune]` are the same task, and declaring both
+is an error).
+
+#### Brewfile discovery
+
+With no `[paths] brewfile` and no `MAC_UPKEEP_BREWFILE`/`HOMEBREW_BUNDLE_FILE`, only two
+absolute locations are searched: `$XDG_CONFIG_HOME/Brewfile` (default `~/.config/Brewfile`)
+and `~/.Brewfile`. **The current working directory is deliberately not searched.**
+`brew bundle` evaluates a Brewfile as Ruby and `brew_bundle` runs `cleanup --force`, so a
+CWD-relative lookup made whichever project directory your shell happened to be in able to
+run code and uninstall every package it did not list. If no Brewfile is found the task
+skips; it no longer runs with an empty `--file=`, which Homebrew resolved back to
+`$PWD/Brewfile`.
+
 ### Custom tasks
 
 Add your own tasks using the same format:
@@ -131,6 +148,32 @@ skip_dirty = true         # skip repos with uncommitted changes
 
 Each repo is skipped with a reason if it's not a git repo, has no remote, has no upstream branch, or (when `skip_dirty = true`) has uncommitted changes.
 
+#### Only enrol repositories you created
+
+**A git repository's own `.git/config` can make git execute commands.** Point a `repos` glob only at directories you created yourself — never at a downloads, sync, backup, or vendor-drop directory. A tree that arrives by archive, restore, or file sync brings its `.git/config` and `.git/hooks` with it, and `safe.directory` does not help: it keys on ownership, and anything you unpacked is owned by you. A plain `git clone` does *not* carry these, so cloning is unaffected.
+
+mac-upkeep neutralises the directives it can, on every git call — not just on `pull`, because `git status --porcelain` (the `skip_dirty` check itself) is enough to trigger some of them:
+
+| Neutralised | How |
+|---|---|
+| `core.fsmonitor` | reset to empty |
+| `.git/hooks/*` | `core.hooksPath=/dev/null` |
+| `credential.helper` | list reset, then your own global/system helpers re-added |
+| `core.sshCommand` | set to your own global/system value, else explicitly `ssh` |
+| `ext::` transport | `protocol.ext.allow=never` |
+| `remote.<name>.uploadpack` | `protocol.file.allow=never` |
+| `core.gitProxy` | `protocol.git.allow=never` |
+
+Note the asymmetry in the middle two rows. `credential.helper` is multi-valued, so an empty entry resets git's accumulated list. `core.sshCommand` is single-valued, so an empty entry is not a reset — git would try to execute the empty string and every SSH remote would fail. Single-valued keys are therefore *set*, never blanked.
+
+Three consequences worth knowing:
+
+- **Local-path remotes no longer work** under git_sync (`fatal: transport 'file' not allowed`). This is deliberate — it is what closes the `uploadpack` execution path. Pull from a bare mirror on an external disk outside mac-upkeep.
+- **`git://` remotes no longer work** (`fatal: transport 'git' not allowed`). Also deliberate: `core.gitProxy` runs an arbitrary command for that transport and cannot be neutralised any other way. `git://` is unauthenticated and unencrypted; use SSH or HTTPS.
+- **Repository hooks do not run** during git_sync, so a `post-merge` hook that installs dependencies will not fire on an unattended pull.
+
+This is defence in depth, not a sandbox. Git has no "ignore this repository's config" switch. The known remaining execution path is `filter.<driver>.clean` from a planted `.gitattributes`, which fires on `git status`: driver names are arbitrary, so no fixed override covers them. Enrolment discipline is the control that actually holds.
+
 #### Authentication
 
 Any of the following work under launchd without mac-upkeep-side configuration:
@@ -148,6 +191,11 @@ MAC_UPKEEP_GCLOUD=false mac-upkeep run              # Disable a task
 MAC_UPKEEP_GCLOUD_FREQUENCY=monthly mac-upkeep run  # Override frequency
 ```
 
+`MAC_UPKEEP_<TASK>` enables the task only for an explicitly truthy value —
+`true`, `1`, `yes`, or `on`. **Anything else disables it**, including `off`, `disabled`
+and the empty string, which previously all *enabled* the task by falling through a
+denylist of `false`/`0`/`no`.
+
 ### Sudoers
 
 `mo_clean` and `mo_optimize` require passwordless sudo for the `mo` binary:
@@ -168,6 +216,22 @@ Validate before installing — a malformed file in `/etc/sudoers.d/` can lock yo
 >
 > 3.0.0 generates `env_keep += "HOME USER LOGNAME"`. Verify with `sudo -n $(brew --prefix)/bin/mo optimize </dev/null >/dev/null; echo $?` — it should print `0`.
 
+### Log file permissions
+
+`mac-upkeep setup` now prints the `newsyslog.d` line with mode **640** instead of 644. The
+log records `git_sync` failures by repository name, which enumerates your private and
+employer-internal repositories, and `$(brew --prefix)/var/log` is world-traversable — unlike
+`~/Library`, nothing else gates it. Owner plus the `admin` group keeps `mac-upkeep logs`
+working.
+
+> **⚠ Already installed?** Like the sudoers file, `/etc/newsyslog.d/mac-upkeep.conf` is
+> **not** upgraded by `brew upgrade`, and existing log files keep their 644 mode. Rewrite
+> the conf from `mac-upkeep setup`, then:
+>
+> ```bash
+> sudo chmod 640 "$(brew --prefix)"/var/log/mac-upkeep.log*
+> ```
+
 ## Contributing
 
 See [CONTRIBUTING.md](https://github.com/calvindotsg/mac-upkeep/blob/main/CONTRIBUTING.md) for development setup and conventions.

{mac_upkeep-3.0.2 → mac_upkeep-3.0.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "mac-upkeep"
-version = "3.0.2"
+version = "3.0.4"
 description = "Automated macOS maintenance CLI"
 readme = "README.md"
 license = "MIT"