mac-upkeep 2.4.2__tar.gz → 2.5.1__tar.gz

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

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

{mac_upkeep-2.4.2 → mac_upkeep-2.5.1}/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [2.5.1](https://github.com/calvindotsg/mac-upkeep/compare/v2.5.0...v2.5.1) (2026-06-15)
+
+
+### Bug Fixes
+
+* show handler tasks as ready in tasks dashboard, not "not found" ([#43](https://github.com/calvindotsg/mac-upkeep/issues/43)) ([788646a](https://github.com/calvindotsg/mac-upkeep/commit/788646aff95bb05f7589227691fd43b736f47ddc))
+
+## [2.5.0](https://github.com/calvindotsg/mac-upkeep/compare/v2.4.2...v2.5.0) (2026-06-15)
+
+
+### Features
+
+* add editor_cache task for Notion/Zed caches mole misses ([#41](https://github.com/calvindotsg/mac-upkeep/issues/41)) ([fd4d3e6](https://github.com/calvindotsg/mac-upkeep/commit/fd4d3e63968f88528095e7700f53dbf02f3d1fc8))
+
 ## [2.4.2](https://github.com/calvindotsg/mac-upkeep/compare/v2.4.1...v2.4.2) (2026-06-15)
 
 

{mac_upkeep-2.4.2 → mac_upkeep-2.5.1}/CLAUDE.md

@@ -65,7 +65,7 @@ Do not add conditions to the filter or remove the `force_tasks is None` guard fr
 - **Safety net**: prevents redundant runs from RunAtLoad boot triggers, launchd coalescing, and manual `mac-upkeep run`. `run_at_load true` is intentional — `StartCalendarInterval` does NOT coalesce from power-off (only sleep), so RunAtLoad is essential for laptops that reboot frequently.
 - Timestamps only update on successful non-dry-run execution. Corrupt/missing state file silently triggers re-run.
 - **`FREQUENCY_THRESHOLDS` is dual-purpose**: used for gating in `_should_run()` and for display in `format_next_run()`. `format_next_run()` accepts an optional `state` dict parameter to avoid redundant `_load_state()` calls — the `tasks` command pre-loads state once; `_run()` skip path omits it (one-off read is fine).
-- **Status column priority in `tasks` command**: `disabled → not found → ready` mirrors the check order in `run_task()` (disabled check then detection check) but is computed independently in `cli.py` using `td.enabled` and `shutil.which(td.detect)`. `td.detect` is already variable-resolved and auto-inferred by `Config.load()`, so `shutil.which(td.detect)` works directly — no raw TOML variable resolution needed.
+- **Status column priority in `tasks` command**: `disabled → not found → ready` mirrors the check order in `run_task()` (disabled check then detection check) but is computed independently in `cli.py` using `td.enabled` and `shutil.which(td.detect)`. `td.detect` is already variable-resolved and auto-inferred by `Config.load()`, so `shutil.which(td.detect)` works directly — no raw TOML variable resolution needed. The detection check is guarded by `td.detect and ...`: handler tasks (e.g. `editor_cache`) carry an empty `detect`, so they short-circuit to `ready`/`disabled` instead of a misleading `not found` (`shutil.which("")` is `None`). This mirrors the execution gate in `_run_handler` (`if td.detect and not shutil.which(td.detect)`).
 
 ### Output and notifications
 
@@ -81,6 +81,18 @@ Do not add conditions to the filter or remove the `force_tasks is None` guard fr
 
 A TaskDef with `handler="<name>"` and empty `command` bypasses subprocess building: `run_all_tasks` routes it through `_run_handler`, which applies filter + frequency + `detect` gates then calls `HANDLERS[name](config, output, dry_run)`. Handler modules register themselves in `tasks._register_handlers()` (called at import). `KNOWN_HANDLERS` drives config validation — unknown handler names are rejected early. Handlers emit per-step output via `output.task_debug()` and return one aggregate `TaskResult`.
 
+**Adding a handler is a 3-edit change** (see `editor_cache` as the second exemplar after `git_sync`): the module + `_register_handlers()`/`KNOWN_HANDLERS` line + a `[tasks.<name>]` block (with `handler=`, no `command`) in `defaults.toml` plus its `run.order` entry. **Gotcha:** every new `defaults.toml` task breaks fixtures that hardcode the task count and patched `KNOWN_HANDLERS` sets — grep `tests/` for the old count and `KNOWN_HANDLERS` monkeypatches (memory: "grep test fixtures when adding tasks to defaults.toml").
+
+### editor_cache handler
+
+Reclaims Electron/editor caches mole's classifier structurally misses (`Service Worker`, `node/cache` don't match its `[Cc]ache|[Ll]og|...` regex). Source-validated against `tw93/mole`:
+
+- **Surgical targeting**: clear `Service Worker/CacheStorage` (the bloat), never the parent `Service Worker/` — its `Database/` holds the SW registrations (mole never deletes it).
+- **Running-app guard via `pgrep -x`** (mole's technique; robust under launchd, no TCC/GUI dependency unlike osascript) — deleting a running Electron app's cache can corrupt state, so the app must be closed.
+- **Zed `node/cache` is npm's `--cache`** (`zed-industries/zed` `node_runtime.rs:603`): clearing only re-downloads tarballs on the next LSP install; installed servers keep working. Size-gated (`min_size_mb`, default 2048) to skip pointless re-downloads.
+- **`_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.
+
 ### 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.

{mac_upkeep-2.4.2 → mac_upkeep-2.5.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mac-upkeep
-Version: 2.4.2
+Version: 2.5.1
 Summary: Automated macOS maintenance CLI
 Project-URL: Homepage, https://github.com/calvindotsg/mac-upkeep
 Project-URL: Repository, https://github.com/calvindotsg/mac-upkeep

{mac_upkeep-2.4.2 → mac_upkeep-2.5.1}/pyproject.toml

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

{mac_upkeep-2.4.2 → mac_upkeep-2.5.1}/src/mac_upkeep/cli.py

@@ -196,7 +196,7 @@ def tasks() -> None:
         for name, td in task_list:
             if not td.enabled:
                 status = "[dim]disabled[/dim]"
-            elif shutil.which(td.detect) is None:
+            elif td.detect and shutil.which(td.detect) is None:
                 status = "[yellow]not found[/yellow]"
             else:
                 status = "[green]ready[/green]"
@@ -209,7 +209,7 @@ def tasks() -> None:
         for name, td in task_list:
             if not td.enabled:
                 status = "disabled"
-            elif shutil.which(td.detect) is None:
+            elif td.detect and shutil.which(td.detect) is None:
                 status = "not found"
             else:
                 status = "ready"

{mac_upkeep-2.4.2 → mac_upkeep-2.5.1}/src/mac_upkeep/config.py

@@ -209,6 +209,7 @@ class Config:
     notify_sound: str = "Submarine"
     git_sync_repos: list[str] = field(default_factory=list)
     git_sync_skip_dirty: bool = True
+    editor_cache_apps: list[dict] = field(default_factory=list)
 
     @classmethod
     def load(cls, path: Path = DEFAULT_CONFIG_PATH) -> Config:
@@ -235,6 +236,11 @@ class Config:
             config.git_sync_repos = list(gs.get("repos", []))
             config.git_sync_skip_dirty = bool(gs.get("skip_dirty", True))
 
+        # Extract editor_cache app overrides from user config (else handler uses
+        # its built-in DEFAULT_APPS).
+        if user_data and "editor_cache" in user_data:
+            config.editor_cache_apps = list(user_data["editor_cache"].get("apps", []))
+
         # Extract brewfile from user config
         if user_data and "paths" in user_data and "brewfile" in user_data["paths"]:
             config.brewfile = user_data["paths"]["brewfile"]

{mac_upkeep-2.4.2 → mac_upkeep-2.5.1}/src/mac_upkeep/defaults.toml

@@ -75,6 +75,15 @@ handler = "git_sync"
 detect = "git"
 frequency = "daily"
 
+[tasks.editor_cache]
+description = "Clear Electron/editor caches when their apps are closed"
+handler = "editor_cache"
+frequency = "monthly"
+# Opt-in: deletes app caches (rm -rf) and ships to all users. Enable per-machine
+# via `[tasks.editor_cache]\nenabled = true`. Targets Notion + Zed by default;
+# override with [[editor_cache.apps]] in your config.
+enabled = false
+
 [run]
 order = [
     "brew_update",
@@ -89,4 +98,5 @@ order = [
     "brew_cleanup",
     "brew_bundle",
     "git_sync",
+    "editor_cache",
 ]

mac_upkeep-2.5.1/src/mac_upkeep/editor_cache.py

@@ -0,0 +1,213 @@
+"""Built-in editor_cache handler: reclaim Electron/editor caches mole can't see.
+
+Apps like Notion (Electron) and Zed leave multi-GB caches under names that
+mole's risk classifier ignores ("Service Worker", "node/cache"), so they are
+never cleaned by `mo clean`. This handler targets those paths directly, but
+only when the owning app is closed (deleting a running Electron app's cache can
+corrupt its state) and, optionally, only above a size threshold.
+
+Safety mirrors tw93/mole: surgical sub-folder targeting (e.g. the
+`Service Worker/CacheStorage` bloat, never the sibling `Database` that holds the
+service-worker registrations), a `pgrep -x` running-app guard (robust under
+launchd, unlike osascript), and a path guard that refuses anything not strictly
+under ~/Library/Application Support.
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+import stat
+import subprocess
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from mac_upkeep.output import TaskResult
+
+if TYPE_CHECKING:
+    from mac_upkeep.config import Config
+    from mac_upkeep.output import Output
+
+# Built-in targets. Each app is cleaned only when its `process` is not running.
+# `min_size_mb` gates a target: 0 = always clean when closed; >0 = only when the
+# target exceeds the threshold (Zed re-downloads LSP tarballs, so small caches
+# aren't worth the re-fetch). Paths use ~ and are expanded at run time.
+DEFAULT_APPS: list[dict] = [
+    {
+        "name": "Notion",
+        "process": "Notion",
+        "min_size_mb": 0,
+        "targets": [
+            "~/Library/Application Support/Notion/Partitions/notion/Service Worker/CacheStorage",
+            "~/Library/Application Support/Notion/Partitions/notion/Cache",
+            "~/Library/Application Support/Notion/Partitions/notion/Code Cache",
+            "~/Library/Application Support/Notion/Partitions/notion/GPUCache",
+        ],
+    },
+    {
+        "name": "Zed",
+        "process": "zed",
+        "min_size_mb": 2048,
+        "targets": [
+            "~/Library/Application Support/Zed/node/cache",
+        ],
+    },
+]
+
+# Deletion is refused for anything not strictly below this directory.
+_SAFE_ROOT = Path.home() / "Library" / "Application Support"
+
+
+def _dir_size(path: Path) -> int:
+    """Total bytes under path, following no symlinks. 0 if unreadable."""
+    total = 0
+    for root, _dirs, files in os.walk(path, followlinks=False):
+        for name in files:
+            fp = Path(root) / name
+            try:
+                st = fp.lstat()
+            except OSError:
+                continue
+            # Skip symlinks: count only real bytes that deletion reclaims. Test
+            # the mode bits from the single lstat above rather than a second
+            # os.path.islink syscall (avoids a stat-vs-stat TOCTOU).
+            if not stat.S_ISLNK(st.st_mode):
+                total += st.st_size
+    return total
+
+
+def _pgrep_running(process: str) -> bool:
+    """True if a process named exactly `process` appears to be running (pgrep -x).
+
+    Fail-closed: any uncertainty returns True so the caller skips deletion. An
+    empty/missing process name, a pgrep that errors (exit >=2 = bad args /
+    internal error, distinct from exit 1 = no match), or an OS/timeout error all
+    count as "assume running, don't delete".
+    """
+    if not process:
+        return True
+    try:
+        result = subprocess.run(
+            ["pgrep", "-x", process],
+            capture_output=True,
+            stdin=subprocess.DEVNULL,
+            timeout=10,
+        )
+    except (OSError, subprocess.TimeoutExpired):
+        return True
+    # pgrep exit codes: 0 = match (running), 1 = no match (not running),
+    # >=2 = pgrep itself errored → fail-closed (treat as running).
+    return result.returncode != 1
+
+
+def _is_safe_target(path: Path) -> bool:
+    """Guard before any rmtree: refuse anything not safely deep under _SAFE_ROOT.
+
+    Mirrors mole's validate_path_for_deletion: the resolved path must live
+    strictly inside ~/Library/Application Support, be at least two segments below
+    it (so an app's whole support dir can never be the target), and not be a
+    symlink (which could redirect deletion elsewhere).
+    """
+    if path.is_symlink():
+        return False
+    try:
+        resolved = path.resolve()
+        root = _SAFE_ROOT.resolve()
+    except OSError:
+        return False
+    if not resolved.is_relative_to(root):
+        return False
+    return len(resolved.relative_to(root).parts) >= 2
+
+
+def _clean_target(target: Path, min_size_mb: int, output: Output, dry_run: bool) -> int:
+    """Clean one target dir if eligible. Returns bytes freed (0 if skipped)."""
+    if not target.is_dir():
+        # A path that exists but isn't a directory is almost certainly a
+        # misconfigured target — surface it (the handler's debug output is the
+        # only feedback channel under launchd). A missing path is normal (most
+        # machines lack most default targets), so stay silent there.
+        if target.exists():
+            output.task_debug(f"  skipped (not a directory): {target}")
+        return 0
+    if not _is_safe_target(target):
+        output.task_debug(f"  refused unsafe path: {target}")
+        return 0
+    # Operate on the canonical resolved path so the validated path and the
+    # deleted path are identical — closes any symlink-swap TOCTOU between the
+    # _is_safe_target check and the rmtree. Re-validate the resolved path.
+    try:
+        safe = target.resolve(strict=True)
+    except OSError:
+        return 0
+    if not _is_safe_target(safe):
+        output.task_debug(f"  refused unsafe path: {target}")
+        return 0
+
+    size = _dir_size(safe)
+    size_mb = size // (1024 * 1024)
+    if size_mb < min_size_mb:
+        output.task_debug(f"  {target.name}: {size_mb}MB below {min_size_mb}MB threshold, skipped")
+        return 0
+
+    if dry_run:
+        output.task_debug(f"  would clean {target.name}: {size_mb}MB")
+        return size
+
+    try:
+        shutil.rmtree(safe)
+    except OSError as exc:
+        output.task_debug(f"  failed to clean {target.name}: {exc}")
+        raise
+    output.task_debug(f"  cleaned {target.name}: {size_mb}MB")
+    return size
+
+
+def run_editor_cache(config: Config, output: Output, dry_run: bool) -> TaskResult:
+    """Handler entry point. Clear configured editor caches for closed apps."""
+    apps = config.editor_cache_apps or DEFAULT_APPS
+
+    total_freed = 0
+    n_cleaned = 0
+    n_running = 0
+    failures: list[str] = []
+
+    for app in apps:
+        name = app.get("name", "?")
+        process = app.get("process", "")
+        min_size_mb = int(app.get("min_size_mb", 0))
+        targets = [Path(os.path.expanduser(t)) for t in app.get("targets", [])]
+
+        if _pgrep_running(process):
+            output.task_debug(f"{name}: skipped, app is running")
+            n_running += 1
+            continue
+
+        app_freed = 0
+        try:
+            for target in targets:
+                app_freed += _clean_target(target, min_size_mb, output, dry_run)
+        except OSError:
+            failures.append(name)
+            continue
+
+        if app_freed:
+            n_cleaned += 1
+            total_freed += app_freed
+
+    if failures:
+        return TaskResult(
+            "editor_cache", "failed", reason=f"{len(failures)} failed: {', '.join(failures)}"
+        )
+
+    freed_mb = total_freed // (1024 * 1024)
+    if dry_run:
+        return TaskResult("editor_cache", "ok", reason=f"dry-run: would free {freed_mb}MB")
+
+    parts: list[str] = []
+    if n_cleaned:
+        parts.append(f"{freed_mb}MB freed")
+    if n_running:
+        parts.append(f"{n_running} running")
+    reason = ", ".join(parts) if parts else "nothing to clean"
+    return TaskResult("editor_cache", "ok", reason=reason)

{mac_upkeep-2.4.2 → mac_upkeep-2.5.1}/src/mac_upkeep/tasks.py

@@ -48,11 +48,14 @@ KNOWN_HANDLERS: set[str] = set()  # kept in sync with HANDLERS; read by config v
 
 def _register_handlers() -> None:
     """Register built-in handlers. Local import avoids any import-cycle risk."""
-    from mac_upkeep import git_sync
+    from mac_upkeep import editor_cache, git_sync
 
     HANDLERS["git_sync"] = git_sync.run_git_sync
     KNOWN_HANDLERS.add("git_sync")
 
+    HANDLERS["editor_cache"] = editor_cache.run_editor_cache
+    KNOWN_HANDLERS.add("editor_cache")
+
 
 _register_handlers()
 

{mac_upkeep-2.4.2 → mac_upkeep-2.5.1}/tests/test_cli.py

@@ -65,6 +65,34 @@ def test_tasks_shows_not_found_status(tmp_path):
     assert "not found" in result.output
 
 
+def test_tasks_handler_without_detect_shows_ready():
+    # A handler task has no `detect` binary; even when shutil.which() returns None
+    # for everything, it must show "ready" (or "disabled") — never "not found".
+    from mac_upkeep.config import Config, TaskDef
+
+    cfg = Config()
+    cfg.task_defs = {
+        "editor_cache": TaskDef(
+            name="editor_cache",
+            description="handler task",
+            command="",
+            handler="editor_cache",
+            detect="",
+            enabled=True,
+        )
+    }
+    cfg.run_order = ["editor_cache"]
+    with (
+        patch("mac_upkeep.cli.Config.load", return_value=cfg),
+        patch("mac_upkeep.cli.shutil.which", return_value=None),
+    ):
+        result = runner.invoke(app, ["tasks"])
+    assert result.exit_code == 0
+    line = next(line for line in result.output.splitlines() if line.startswith("editor_cache"))
+    assert "ready" in line
+    assert "not found" not in line
+
+
 def test_force_invalid_shows_valid_tasks():
     result = runner.invoke(app, ["run", "--force", "nonexistent"])
     assert result.exit_code == 1

{mac_upkeep-2.4.2 → mac_upkeep-2.5.1}/tests/test_config.py

@@ -34,7 +34,7 @@ def test_task_def_defaults():
 def test_load_defaults_returns_all_tasks():
     data = _load_defaults()
     assert "tasks" in data
-    assert len(data["tasks"]) == 12
+    assert len(data["tasks"]) == 13
     assert "brew_update" in data["tasks"]
     assert "brew_bundle" in data["tasks"]
 
@@ -44,8 +44,8 @@ def test_load_defaults_has_run_order():
     assert "run" in data
     order = data["run"]["order"]
     assert order[0] == "brew_update"
-    assert order[-1] == "git_sync"
-    assert len(order) == 12
+    assert order[-1] == "editor_cache"
+    assert len(order) == 13
 
 
 # --- load_default_task_names ---
@@ -53,10 +53,10 @@ def test_load_defaults_has_run_order():
 
 def test_load_default_task_names():
     tasks, order = load_default_task_names()
-    assert len(tasks) == 12
+    assert len(tasks) == 13
     assert tasks["brew_update"] == "Update Homebrew package database"
     assert order[0] == "brew_update"
-    assert order[-1] == "git_sync"
+    assert order[-1] == "editor_cache"
 
 
 # --- resolve_variables ---
@@ -93,7 +93,7 @@ def test_resolve_variables_no_vars():
 def test_load_task_defs_defaults_only():
     variables = {"BREW_PREFIX": "/opt/homebrew", "BREWFILE": "", "HOME": "/users/me"}
     task_defs, run_order = load_task_defs(None, variables)
-    assert len(task_defs) == 12
+    assert len(task_defs) == 13
     assert "brew_update" in task_defs
     assert task_defs["brew_update"].command == "brew update"
     assert task_defs["brew_update"].detect == "brew"
@@ -103,7 +103,7 @@ def test_load_task_defs_defaults_only():
     assert task_defs["mo_clean"].command == "/opt/homebrew/bin/mo clean"
     assert task_defs["fisher"].shell == "fish --interactive -c"
     assert run_order[0] == "brew_update"
-    assert run_order[-1] == "git_sync"
+    assert run_order[-1] == "editor_cache"
 
 
 def test_load_task_defs_user_override():
@@ -235,7 +235,7 @@ def test_validation_empty_command():
 def test_validation_command_and_handler_conflict(monkeypatch):
     import pytest
 
-    monkeypatch.setattr("mac_upkeep.tasks.KNOWN_HANDLERS", {"stub", "git_sync"})
+    monkeypatch.setattr("mac_upkeep.tasks.KNOWN_HANDLERS", {"stub", "git_sync", "editor_cache"})
     variables = {"BREW_PREFIX": "/opt/homebrew", "BREWFILE": "", "HOME": "/users/me"}
     user_data = {
         "tasks": {
@@ -253,8 +253,8 @@ def test_validation_command_and_handler_conflict(monkeypatch):
 def test_validation_unknown_handler(monkeypatch):
     import pytest
 
-    # Keep git_sync registered so default task validates; only "nope" is unknown
-    monkeypatch.setattr("mac_upkeep.tasks.KNOWN_HANDLERS", {"git_sync"})
+    # Keep default handlers registered so default tasks validate; only "nope" is unknown
+    monkeypatch.setattr("mac_upkeep.tasks.KNOWN_HANDLERS", {"git_sync", "editor_cache"})
     variables = {"BREW_PREFIX": "/opt/homebrew", "BREWFILE": "", "HOME": "/users/me"}
     user_data = {
         "tasks": {
@@ -270,7 +270,7 @@ def test_validation_unknown_handler(monkeypatch):
 
 
 def test_validation_accepts_handler_with_empty_command(monkeypatch):
-    monkeypatch.setattr("mac_upkeep.tasks.KNOWN_HANDLERS", {"stub", "git_sync"})
+    monkeypatch.setattr("mac_upkeep.tasks.KNOWN_HANDLERS", {"stub", "git_sync", "editor_cache"})
     variables = {"BREW_PREFIX": "/opt/homebrew", "BREWFILE": "", "HOME": "/users/me"}
     user_data = {
         "tasks": {
@@ -346,7 +346,7 @@ def test_custom_task_appended_to_default_order():
     # Custom task appended after all default tasks
     assert "my_task" in run_order
     assert run_order[-1] == "my_task"
-    assert len(run_order) == 13
+    assert len(run_order) == 14
 
 
 def test_custom_task_not_duplicated_with_explicit_order():
@@ -371,12 +371,36 @@ def test_custom_task_not_duplicated_with_explicit_order():
 
 def test_load_nonexistent_config_returns_defaults():
     config = Config.load(Path("/nonexistent/config.toml"))
-    assert len(config.task_defs) == 12
+    assert len(config.task_defs) == 13
     assert config.run_order[0] == "brew_update"
     assert config.is_enabled("brew_update") is True
     assert config.get_frequency("gcloud") == "monthly"
 
 
+def test_load_editor_cache_apps(tmp_path):
+    cfg_path = tmp_path / "config.toml"
+    cfg_path.write_text(
+        "[[editor_cache.apps]]\n"
+        'name = "Notion"\n'
+        'process = "Notion"\n'
+        "min_size_mb = 0\n"
+        'targets = ["~/Library/Application Support/Notion/X"]\n'
+    )
+    config = Config.load(cfg_path)
+    assert len(config.editor_cache_apps) == 1
+    app = config.editor_cache_apps[0]
+    assert app["name"] == "Notion"
+    assert app["process"] == "Notion"
+    assert app["targets"] == ["~/Library/Application Support/Notion/X"]
+
+
+def test_load_editor_cache_apps_absent_defaults_empty(tmp_path):
+    cfg_path = tmp_path / "config.toml"
+    cfg_path.write_text('[tasks.brew_update]\nfrequency = "monthly"\n')
+    config = Config.load(cfg_path)
+    assert config.editor_cache_apps == []
+
+
 def test_config_is_enabled():
     config = Config.load(Path("/nonexistent/config.toml"))
     assert config.is_enabled("brew_update") is True

mac_upkeep-2.5.1/tests/test_editor_cache.py

@@ -0,0 +1,350 @@
+"""Tests for the editor_cache handler."""
+
+from __future__ import annotations
+
+import os
+import subprocess
+from unittest.mock import MagicMock
+
+from mac_upkeep import editor_cache
+from mac_upkeep.config import Config
+from mac_upkeep.editor_cache import (
+    DEFAULT_APPS,
+    _dir_size,
+    _is_safe_target,
+    _pgrep_running,
+    run_editor_cache,
+)
+
+
+def _config(apps: list[dict] | None = None) -> Config:
+    config = Config.load()
+    config.editor_cache_apps = apps if apps is not None else []
+    return config
+
+
+def _app(name: str, targets: list[str], *, process: str = "FakeApp", min_size_mb: int = 0) -> dict:
+    return {"name": name, "process": process, "min_size_mb": min_size_mb, "targets": targets}
+
+
+def _make_cache(root, *parts, size: int = 1024) -> str:
+    """Create a cache dir at least two levels under root with `size` bytes inside."""
+    d = root.joinpath(*parts)
+    d.mkdir(parents=True, exist_ok=True)
+    (d / "blob").write_bytes(b"x" * size)
+    return str(d)
+
+
+def _use_tmp_root(monkeypatch, tmp_path, *, running: bool = False) -> None:
+    """Point the safety root at tmp_path and control the pgrep guard."""
+    monkeypatch.setattr(editor_cache, "_SAFE_ROOT", tmp_path)
+    monkeypatch.setattr(editor_cache, "_pgrep_running", lambda _proc: running)
+
+
+# --- _dir_size ---
+
+
+def test_dir_size_sums_files(tmp_path):
+    (tmp_path / "a").write_bytes(b"x" * 100)
+    sub = tmp_path / "sub"
+    sub.mkdir()
+    (sub / "b").write_bytes(b"y" * 250)
+    assert _dir_size(tmp_path) == 350
+
+
+def test_dir_size_ignores_symlinks(tmp_path):
+    real = tmp_path / "real"
+    real.write_bytes(b"x" * 500)
+    (tmp_path / "link").symlink_to(real)
+    # Only the real 500 bytes count; the symlink adds nothing.
+    assert _dir_size(tmp_path) == 500
+
+
+# --- _pgrep_running ---
+
+
+def test_pgrep_running_true(monkeypatch):
+    monkeypatch.setattr(
+        editor_cache.subprocess,
+        "run",
+        lambda *a, **k: subprocess.CompletedProcess(a, returncode=0),
+    )
+    assert _pgrep_running("Notion") is True
+
+
+def test_pgrep_running_false(monkeypatch):
+    monkeypatch.setattr(
+        editor_cache.subprocess,
+        "run",
+        lambda *a, **k: subprocess.CompletedProcess(a, returncode=1),
+    )
+    assert _pgrep_running("Notion") is False
+
+
+def test_pgrep_running_assumes_running_on_error(monkeypatch):
+    def _boom(*a, **k):
+        raise OSError("pgrep missing")
+
+    monkeypatch.setattr(editor_cache.subprocess, "run", _boom)
+    # Fail closed: if we can't tell, never delete.
+    assert _pgrep_running("Notion") is True
+
+
+def test_pgrep_running_error_code_assumes_running(monkeypatch):
+    # pgrep exit >=2 = pgrep itself errored (bad args/internal), NOT "no match".
+    monkeypatch.setattr(
+        editor_cache.subprocess,
+        "run",
+        lambda *a, **k: subprocess.CompletedProcess(a, returncode=2),
+    )
+    assert _pgrep_running("--weird") is True
+
+
+def test_pgrep_running_timeout_assumes_running(monkeypatch):
+    def _timeout(*a, **k):
+        raise subprocess.TimeoutExpired(cmd=["pgrep"], timeout=10)
+
+    monkeypatch.setattr(editor_cache.subprocess, "run", _timeout)
+    assert _pgrep_running("Notion") is True
+
+
+def test_pgrep_running_empty_process_assumes_running():
+    # A missing `process` must not silently bypass the running-app guard.
+    assert _pgrep_running("") is True
+
+
+# --- _is_safe_target ---
+
+
+def test_is_safe_target_accepts_deep_path(monkeypatch, tmp_path):
+    monkeypatch.setattr(editor_cache, "_SAFE_ROOT", tmp_path)
+    target = tmp_path / "Notion" / "CacheStorage"
+    target.mkdir(parents=True)
+    assert _is_safe_target(target) is True
+
+
+def test_is_safe_target_rejects_root_and_app_dir(monkeypatch, tmp_path):
+    monkeypatch.setattr(editor_cache, "_SAFE_ROOT", tmp_path)
+    assert _is_safe_target(tmp_path) is False  # the root itself
+    app = tmp_path / "Notion"
+    app.mkdir()
+    assert _is_safe_target(app) is False  # one segment below root
+
+
+def test_is_safe_target_rejects_outside_root(monkeypatch, tmp_path):
+    monkeypatch.setattr(editor_cache, "_SAFE_ROOT", tmp_path / "inside")
+    (tmp_path / "inside").mkdir()
+    outside = tmp_path / "elsewhere" / "cache"
+    outside.mkdir(parents=True)
+    assert _is_safe_target(outside) is False
+
+
+def test_is_safe_target_rejects_symlink(monkeypatch, tmp_path):
+    monkeypatch.setattr(editor_cache, "_SAFE_ROOT", tmp_path)
+    real = tmp_path / "Notion" / "CacheStorage"
+    real.mkdir(parents=True)
+    link = tmp_path / "Notion" / "link"
+    link.symlink_to(real)
+    assert _is_safe_target(link) is False
+
+
+# --- run_editor_cache ---
+
+
+def test_skips_when_app_running(monkeypatch, tmp_path):
+    _use_tmp_root(monkeypatch, tmp_path, running=True)
+    target = _make_cache(tmp_path, "Notion", "CacheStorage", size=4096)
+    config = _config([_app("Notion", [target])])
+    output = MagicMock()
+
+    result = run_editor_cache(config, output, dry_run=False)
+
+    assert os.path.isdir(target)  # not deleted
+    assert result.status == "ok"
+    assert "running" in result.reason
+
+
+def test_cleans_when_app_closed(monkeypatch, tmp_path):
+    _use_tmp_root(monkeypatch, tmp_path, running=False)
+    target = _make_cache(tmp_path, "Notion", "CacheStorage", size=1024)
+    config = _config([_app("Notion", [target])])
+    output = MagicMock()
+
+    result = run_editor_cache(config, output, dry_run=False)
+
+    assert not os.path.exists(target)  # deleted
+    assert result.status == "ok"
+    assert "MB freed" in result.reason
+
+
+def test_reason_combines_freed_and_running(monkeypatch, tmp_path):
+    # Two apps: one running (skipped), one closed with a large cache (cleaned).
+    # Exercises the ", ".join(parts) path with both segments populated.
+    monkeypatch.setattr(editor_cache, "_SAFE_ROOT", tmp_path)
+    monkeypatch.setattr(editor_cache, "_pgrep_running", lambda proc: proc == "Zed")
+    closed = _make_cache(tmp_path, "Notion", "CacheStorage", size=1024)
+    config = _config(
+        [
+            _app("Notion", [closed], process="Notion"),
+            _app("Zed", [str(tmp_path / "Zed" / "cache")], process="Zed"),
+        ]
+    )
+    output = MagicMock()
+
+    result = run_editor_cache(config, output, dry_run=False)
+
+    assert result.status == "ok"
+    assert "MB freed" in result.reason
+    assert "running" in result.reason
+
+
+def test_size_gate_skips_small_cache(monkeypatch, tmp_path):
+    _use_tmp_root(monkeypatch, tmp_path, running=False)
+    target = _make_cache(tmp_path, "Zed", "node", "cache", size=1024)
+    config = _config([_app("Zed", [target], min_size_mb=2048)])
+    output = MagicMock()
+    # Report a sub-threshold size without writing 2 GB.
+    monkeypatch.setattr(editor_cache, "_dir_size", lambda _p: 100 * 1024 * 1024)
+
+    result = run_editor_cache(config, output, dry_run=False)
+
+    assert os.path.isdir(target)  # below threshold → kept
+    assert result.reason == "nothing to clean"
+
+
+def test_size_gate_cleans_large_cache(monkeypatch, tmp_path):
+    _use_tmp_root(monkeypatch, tmp_path, running=False)
+    target = _make_cache(tmp_path, "Zed", "node", "cache", size=1024)
+    config = _config([_app("Zed", [target], min_size_mb=2048)])
+    output = MagicMock()
+    # Report an over-threshold size without writing 3 GB.
+    monkeypatch.setattr(editor_cache, "_dir_size", lambda _p: 3000 * 1024 * 1024)
+
+    result = run_editor_cache(config, output, dry_run=False)
+
+    assert not os.path.exists(target)  # above threshold → cleaned
+    assert "3000MB freed" in result.reason
+
+
+def test_dry_run_deletes_nothing(monkeypatch, tmp_path):
+    _use_tmp_root(monkeypatch, tmp_path, running=False)
+    target = _make_cache(tmp_path, "Notion", "CacheStorage", size=1024)
+    config = _config([_app("Notion", [target])])
+    output = MagicMock()
+
+    result = run_editor_cache(config, output, dry_run=True)
+
+    assert os.path.isdir(target)  # preserved
+    assert result.status == "ok"
+    assert "would free" in result.reason
+    assert any("would clean" in c[0][0] for c in output.task_debug.call_args_list)
+
+
+def test_dry_run_with_running_app(monkeypatch, tmp_path):
+    # dry-run + every app running: exercises the dry-run early return when
+    # nothing would be freed (n_running > 0).
+    _use_tmp_root(monkeypatch, tmp_path, running=True)
+    target = _make_cache(tmp_path, "Notion", "CacheStorage", size=1024)
+    config = _config([_app("Notion", [target])])
+    output = MagicMock()
+
+    result = run_editor_cache(config, output, dry_run=True)
+
+    assert os.path.isdir(target)  # nothing deleted
+    assert result.status == "ok"
+    assert result.reason == "dry-run: would free 0MB"
+
+
+def test_missing_target_is_skipped(monkeypatch, tmp_path):
+    _use_tmp_root(monkeypatch, tmp_path, running=False)
+    missing = str(tmp_path / "Notion" / "CacheStorage")  # never created
+    config = _config([_app("Notion", [missing])])
+    output = MagicMock()
+
+    result = run_editor_cache(config, output, dry_run=False)
+
+    assert result.status == "ok"
+    assert result.reason == "nothing to clean"
+
+
+def test_empty_config_falls_back_to_default_apps(monkeypatch):
+    # No app override → DEFAULT_APPS used. Force every app "running" so nothing
+    # is deleted; the running count proves all defaults were iterated.
+    monkeypatch.setattr(editor_cache, "_pgrep_running", lambda _proc: True)
+    config = _config([])
+    output = MagicMock()
+
+    result = run_editor_cache(config, output, dry_run=False)
+
+    assert result.status == "ok"
+    assert result.reason == f"{len(DEFAULT_APPS)} running"
+
+
+def test_custom_apps_replace_default_apps(monkeypatch):
+    # A non-empty editor_cache_apps must REPLACE DEFAULT_APPS, not merge with it.
+    checked: list[str] = []
+    monkeypatch.setattr(editor_cache, "_pgrep_running", lambda proc: checked.append(proc) or True)
+    config = _config([_app("Custom", ["~/x"], process="CustomProc")])
+
+    run_editor_cache(config, MagicMock(), dry_run=False)
+
+    # Only the custom app's process is consulted — no Notion/zed from DEFAULT_APPS.
+    assert checked == ["CustomProc"]
+
+
+def test_file_target_skipped_with_feedback(monkeypatch, tmp_path):
+    # A target that exists but is a file (misconfig) is skipped WITH a debug line.
+    _use_tmp_root(monkeypatch, tmp_path, running=False)
+    appdir = tmp_path / "App"
+    appdir.mkdir()
+    file_target = appdir / "cache"
+    file_target.write_text("x")
+    config = _config([_app("App", [str(file_target)])])
+    output = MagicMock()
+
+    result = run_editor_cache(config, output, dry_run=False)
+
+    assert os.path.isfile(file_target)  # not deleted
+    assert result.status == "ok"
+    assert any("not a directory" in c[0][0] for c in output.task_debug.call_args_list)
+
+
+def test_rmtree_failure_reports_failed(monkeypatch, tmp_path):
+    _use_tmp_root(monkeypatch, tmp_path, running=False)
+    target = _make_cache(tmp_path, "Notion", "CacheStorage", size=1024)
+    config = _config([_app("Notion", [target])])
+    output = MagicMock()
+
+    def _boom(_path):
+        raise OSError("permission denied")
+
+    monkeypatch.setattr(editor_cache.shutil, "rmtree", _boom)
+
+    result = run_editor_cache(config, output, dry_run=False)
+
+    assert result.status == "failed"
+    assert "Notion" in result.reason
+
+
+def test_multi_target_first_failure_aborts_remaining(monkeypatch, tmp_path):
+    # An app with multiple targets: a failure on target 1 marks the app failed
+    # and abandons its remaining targets (Notion ships 4 default targets).
+    _use_tmp_root(monkeypatch, tmp_path, running=False)
+    t1 = _make_cache(tmp_path, "App", "cache1", size=1024)
+    t2 = _make_cache(tmp_path, "App", "cache2", size=1024)
+    config = _config([_app("App", [t1, t2])])
+    output = MagicMock()
+    calls = {"n": 0}
+
+    def _boom(_path):
+        calls["n"] += 1
+        raise OSError("permission denied")
+
+    monkeypatch.setattr(editor_cache.shutil, "rmtree", _boom)
+
+    result = run_editor_cache(config, output, dry_run=False)
+
+    assert result.status == "failed"
+    assert "App" in result.reason
+    assert calls["n"] == 1  # bailed after target 1; target 2 never attempted
+    assert os.path.isdir(t2)  # remaining target untouched

{mac_upkeep-2.4.2 → mac_upkeep-2.5.1}/tests/test_tasks.py

@@ -527,7 +527,7 @@ def test_handler_dispatch_runs_and_records_state(tmp_path, monkeypatch):
 
     handler, calls = _stub_handler()
     monkeypatch.setitem(HANDLERS, "stub", handler)
-    monkeypatch.setattr("mac_upkeep.tasks.KNOWN_HANDLERS", {"stub", "git_sync"})
+    monkeypatch.setattr("mac_upkeep.tasks.KNOWN_HANDLERS", {"stub", "git_sync", "editor_cache"})
 
     config = Config.load()
     config.task_defs["stub_task"] = TaskDef(
@@ -558,7 +558,7 @@ def test_handler_dispatch_frequency_gate_skips(tmp_path, monkeypatch):
 
     handler, calls = _stub_handler()
     monkeypatch.setitem(HANDLERS, "stub", handler)
-    monkeypatch.setattr("mac_upkeep.tasks.KNOWN_HANDLERS", {"stub", "git_sync"})
+    monkeypatch.setattr("mac_upkeep.tasks.KNOWN_HANDLERS", {"stub", "git_sync", "editor_cache"})
 
     config = Config.load()
     config.task_defs["stub_task"] = TaskDef(
@@ -585,7 +585,7 @@ def test_handler_dispatch_force_filter(tmp_path, monkeypatch):
 
     handler, calls = _stub_handler()
     monkeypatch.setitem(HANDLERS, "stub", handler)
-    monkeypatch.setattr("mac_upkeep.tasks.KNOWN_HANDLERS", {"stub", "git_sync"})
+    monkeypatch.setattr("mac_upkeep.tasks.KNOWN_HANDLERS", {"stub", "git_sync", "editor_cache"})
 
     config = Config.load()
     config.task_defs["stub_task"] = TaskDef(
@@ -611,7 +611,7 @@ def test_handler_dispatch_detect_miss(tmp_path, monkeypatch):
 
     handler, calls = _stub_handler()
     monkeypatch.setitem(HANDLERS, "stub", handler)
-    monkeypatch.setattr("mac_upkeep.tasks.KNOWN_HANDLERS", {"stub", "git_sync"})
+    monkeypatch.setattr("mac_upkeep.tasks.KNOWN_HANDLERS", {"stub", "git_sync", "editor_cache"})
     monkeypatch.setattr("mac_upkeep.tasks.shutil.which", lambda _: None)
 
     config = Config.load()

{mac_upkeep-2.4.2 → mac_upkeep-2.5.1}/uv.lock

@@ -43,7 +43,7 @@ wheels = [
 
 [[package]]
 name = "mac-upkeep"
-version = "2.4.2"
+version = "2.5.1"
 source = { editable = "." }
 dependencies = [
     { name = "typer" },

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

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