mac-upkeep 2.3.0__tar.gz → 2.4.0__tar.gz

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

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

{mac_upkeep-2.3.0 → mac_upkeep-2.4.0}/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [2.4.0](https://github.com/calvindotsg/mac-upkeep/compare/v2.3.0...v2.4.0) (2026-04-20)
+
+
+### Features
+
+* add git_sync task with daily frequency and handler dispatch ([#35](https://github.com/calvindotsg/mac-upkeep/issues/35)) ([5f4628f](https://github.com/calvindotsg/mac-upkeep/commit/5f4628f5eaae9ddc6941fff72c2eb4cd841390ee))
+
 ## [2.3.0](https://github.com/calvindotsg/mac-upkeep/compare/v2.2.1...v2.3.0) (2026-04-13)
 
 

{mac_upkeep-2.3.0 → mac_upkeep-2.4.0}/CLAUDE.md

@@ -19,7 +19,7 @@
 ## Architecture
 
 ```
-defaults.toml → bundled task definitions (11 tasks), loaded via importlib.resources
+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,
@@ -61,7 +61,7 @@ Do not add conditions to the filter or remove the `force_tasks is None` guard fr
 
 ### 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`.
+- Thresholds are 20 hours for daily, 6 days for weekly, 27 days for monthly (not 24h/7d/30d — buffer for launchd schedule drift after sleep/reboot). State tracked in `~/.local/state/mac-upkeep/last-run.json`.
 - **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).
@@ -77,6 +77,10 @@ Do not add conditions to the filter or remove the `force_tasks is None` guard fr
 - **Rich is a transitive dependency**: `typer>=0.12` requires `rich>=12.3.0`. Using Rich adds zero new runtime dependencies.
 - **`status` dashboard graceful degradation**: if `_get_service_info()` returns None (brew not installed, service not registered, or JSON parse failure), the service header is skipped and only the task scheduling summary is shown. Reuses `format_last_run()` and `format_next_run()` from tasks.py. Test by patching `mac_upkeep.cli._get_service_info` directly rather than mocking subprocess.run (avoids interfering with Config.load() → get_brew_prefix() subprocess call).
 
+### Handler-dispatched tasks
+
+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`.
+
 ### 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.
@@ -98,6 +102,8 @@ Do not add conditions to the filter or remove the `force_tasks is None` guard fr
 - **`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.
+- **`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.
 
 ## Release Process
 

{mac_upkeep-2.3.0 → mac_upkeep-2.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mac-upkeep
-Version: 2.3.0
+Version: 2.4.0
 Summary: Automated macOS maintenance CLI
 Project-URL: Homepage, https://github.com/calvindotsg/mac-upkeep
 Project-URL: Repository, https://github.com/calvindotsg/mac-upkeep
@@ -66,6 +66,7 @@ uvx mac-upkeep run            # one-off without installing
 | `mo_purge` | Remove old project artifacts ([mole](https://github.com/nicehash/mole)) | Monthly |
 | `brew_cleanup` | Remove old versions and cache files | Monthly |
 | `brew_bundle` | Remove packages not in Brewfile | Weekly |
+| `git_sync` | Pull configured git repositories | Daily |
 
 Tasks auto-detect installed tools — missing tools are skipped. Use `--force <task>` to run a specific task on demand.
 
@@ -117,7 +118,7 @@ mac-upkeep show-config --default
 [tasks.gcloud]
 enabled = false
 
-# Change frequency (weekly or monthly)
+# Change frequency (daily, weekly, or monthly)
 [tasks.brew_update]
 frequency = "monthly"
 
@@ -142,6 +143,31 @@ frequency = "monthly"
 order = ["brew_update", "brew_upgrade", "docker_prune", "brew_cleanup", "brew_bundle"]
 ```
 
+### git_sync
+
+Pull configured git repositories daily with `git pull --ff-only`. Opt-in — list your repos explicitly:
+
+```toml
+[git_sync]
+repos = [
+    "~/code/my-project",
+    "~/work/max-*",       # glob patterns supported
+]
+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.
+
+#### Authentication
+
+Any of the following work under launchd without mac-upkeep-side configuration:
+
+- **SSH + `IdentityAgent` (recommended under launchd):** a path-based entry in `~/.ssh/config` pointing at any SSH agent's UNIX socket. Works because the directive is a file path, not the `SSH_AUTH_SOCK` env var that launchd would strip.
+- **HTTPS + credential helper:** `gh auth setup-git` or `git config --global credential.helper osxkeychain`. Requires the helper binary on the launchd `PATH`.
+- **`[url].insteadOf` rewrite:** force SSH regardless of remote protocol by rewriting `https://<host>/` in `~/.gitconfig` to a matching SSH `Host` alias. Bypasses HTTPS auth entirely.
+
+git_sync sets `GIT_TERMINAL_PROMPT=0` and a no-op `GIT_ASKPASS` default (user-set `GIT_ASKPASS` is respected) so misconfigured auth fails in milliseconds instead of stalling to the 60 s subprocess timeout.
+
 ### Environment variables
 
 ```bash

{mac_upkeep-2.3.0 → mac_upkeep-2.4.0}/README.md

@@ -39,6 +39,7 @@ uvx mac-upkeep run            # one-off without installing
 | `mo_purge` | Remove old project artifacts ([mole](https://github.com/nicehash/mole)) | Monthly |
 | `brew_cleanup` | Remove old versions and cache files | Monthly |
 | `brew_bundle` | Remove packages not in Brewfile | Weekly |
+| `git_sync` | Pull configured git repositories | Daily |
 
 Tasks auto-detect installed tools — missing tools are skipped. Use `--force <task>` to run a specific task on demand.
 
@@ -90,7 +91,7 @@ mac-upkeep show-config --default
 [tasks.gcloud]
 enabled = false
 
-# Change frequency (weekly or monthly)
+# Change frequency (daily, weekly, or monthly)
 [tasks.brew_update]
 frequency = "monthly"
 
@@ -115,6 +116,31 @@ frequency = "monthly"
 order = ["brew_update", "brew_upgrade", "docker_prune", "brew_cleanup", "brew_bundle"]
 ```
 
+### git_sync
+
+Pull configured git repositories daily with `git pull --ff-only`. Opt-in — list your repos explicitly:
+
+```toml
+[git_sync]
+repos = [
+    "~/code/my-project",
+    "~/work/max-*",       # glob patterns supported
+]
+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.
+
+#### Authentication
+
+Any of the following work under launchd without mac-upkeep-side configuration:
+
+- **SSH + `IdentityAgent` (recommended under launchd):** a path-based entry in `~/.ssh/config` pointing at any SSH agent's UNIX socket. Works because the directive is a file path, not the `SSH_AUTH_SOCK` env var that launchd would strip.
+- **HTTPS + credential helper:** `gh auth setup-git` or `git config --global credential.helper osxkeychain`. Requires the helper binary on the launchd `PATH`.
+- **`[url].insteadOf` rewrite:** force SSH regardless of remote protocol by rewriting `https://<host>/` in `~/.gitconfig` to a matching SSH `Host` alias. Bypasses HTTPS auth entirely.
+
+git_sync sets `GIT_TERMINAL_PROMPT=0` and a no-op `GIT_ASKPASS` default (user-set `GIT_ASKPASS` is respected) so misconfigured auth fails in milliseconds instead of stalling to the 60 s subprocess timeout.
+
 ### Environment variables
 
 ```bash

{mac_upkeep-2.3.0 → mac_upkeep-2.4.0}/docs/reusable-patterns.md

@@ -15,6 +15,7 @@ Adjust versions/paths:
 ## 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
+- Handler registry dispatch (`HANDLERS: dict[str, Callable]` + `_run_handler`) — for any TOML-driven CLI that needs some tasks to run as Python rather than subprocess commands, without coupling the framework to specific handler implementations
 - `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)

{mac_upkeep-2.3.0 → mac_upkeep-2.4.0}/llms.txt

@@ -4,9 +4,9 @@
 
 ## What it does
 
-Runs 11 maintenance tasks on boot + weekly/monthly schedule via brew services:
+Runs maintenance tasks on boot + recurring schedule via brew services:
 Homebrew update/upgrade/cleanup, gcloud/pnpm/uv cache pruning, Fish plugin
-updates, mole system optimization, and Brewfile enforcement.
+updates, mole system optimization, Brewfile enforcement, and git repository sync.
 
 ## Install
 
@@ -20,7 +20,7 @@ updates, mole system optimization, and Brewfile enforcement.
 - TOML-driven task registry — add tasks without code changes
 - Rich Live TUI for interactive use, plain logging for launchd
 - macOS notifications via terminal-notifier with osascript fallback
-- Per-task frequency scheduling (weekly/monthly) with schedule drift buffers and next-run visibility
+- Per-task frequency scheduling (daily/weekly/monthly) with schedule drift buffers and next-run visibility
 - Custom tasks in user config.toml
 
 ## Links

{mac_upkeep-2.3.0 → mac_upkeep-2.4.0}/pyproject.toml

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

{mac_upkeep-2.3.0 → mac_upkeep-2.4.0}/src/mac_upkeep/cli.py

@@ -127,7 +127,7 @@ def run(
     Disable specific tasks via config file or MAC_UPKEEP_<TASK>=false environment variables.
 
     Task order: brew_update, brew_upgrade, gcloud, pnpm, uv, fisher,
-    mo_clean, mo_optimize, mo_purge, brew_cleanup, brew_bundle.
+    mo_clean, mo_optimize, mo_purge, brew_cleanup, brew_bundle, git_sync.
     brew_cleanup runs after mo_clean (which runs brew autoremove).
     brew_bundle runs last (homebrew/brew#21350).
 
@@ -319,6 +319,14 @@ def _generate_init_config(
     lines.append('# detect = "docker"')
     lines.append('# frequency = "monthly"')
     lines.append("#")
+    lines.append("# git_sync pulls configured repos daily (fast-forward only, skips dirty)")
+    lines.append("# [git_sync]")
+    lines.append("# repos = [")
+    lines.append('#     "~/Documents/github/org/repo",')
+    lines.append('#     "~/Documents/github/org/other-*",  # glob supported')
+    lines.append("# ]")
+    lines.append("# skip_dirty = true")
+    lines.append("#")
     if detected:
         order_str = str([t for t, _ in detected]).replace("'", '"')
         lines.append("# [run]")

{mac_upkeep-2.3.0 → mac_upkeep-2.4.0}/src/mac_upkeep/config.py

@@ -31,6 +31,7 @@ class TaskDef:
     shell: str = ""
     require_file: str = ""
     timeout: int = 300
+    handler: str = ""
 
 
 def get_brew_prefix() -> str:
@@ -133,12 +134,20 @@ def load_task_defs(
                     run_order.append(name)
 
     # Validate task definitions
+    from mac_upkeep.tasks import KNOWN_HANDLERS  # local import to avoid cycle
+
     for name, td in task_defs.items():
-        if not td.command:
-            raise ValueError(f"Task '{name}' has no command")
-        if td.frequency not in ("weekly", "monthly"):
+        if td.command and td.handler:
+            raise ValueError(f"Task '{name}': cannot set both 'command' and 'handler'")
+        if not td.command and not td.handler:
+            raise ValueError(f"Task '{name}' has no command or handler")
+        if td.handler and td.handler not in KNOWN_HANDLERS:
+            known = ", ".join(sorted(KNOWN_HANDLERS)) or "(none registered)"
+            raise ValueError(f"Task '{name}': unknown handler '{td.handler}' (known: {known})")
+        if td.frequency not in ("daily", "weekly", "monthly"):
             raise ValueError(
-                f"Task '{name}': frequency must be 'weekly' or 'monthly', got '{td.frequency}'"
+                f"Task '{name}': frequency must be 'daily', 'weekly', or 'monthly', "
+                f"got '{td.frequency}'"
             )
     for entry in run_order:
         if entry not in task_defs:
@@ -185,6 +194,7 @@ def _parse_task_def(name: str, data: dict) -> TaskDef:
         shell=data.get("shell", ""),
         require_file=data.get("require_file", ""),
         timeout=data.get("timeout", 300),
+        handler=data.get("handler", ""),
     )
 
 
@@ -197,6 +207,8 @@ class Config:
     brewfile: str | None = None
     notify: bool = True
     notify_sound: str = "Submarine"
+    git_sync_repos: list[str] = field(default_factory=list)
+    git_sync_skip_dirty: bool = True
 
     @classmethod
     def load(cls, path: Path = DEFAULT_CONFIG_PATH) -> Config:
@@ -217,6 +229,12 @@ class Config:
             if "sound" in notif:
                 config.notify_sound = str(notif["sound"])
 
+        # Extract git_sync settings from user config
+        if user_data and "git_sync" in user_data:
+            gs = user_data["git_sync"]
+            config.git_sync_repos = list(gs.get("repos", []))
+            config.git_sync_skip_dirty = bool(gs.get("skip_dirty", True))
+
         # 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.3.0 → mac_upkeep-2.4.0}/src/mac_upkeep/defaults.toml

@@ -65,6 +65,12 @@ command = "brew bundle cleanup --force --file=${BREWFILE}"
 detect = "brew"
 require_file = "${BREWFILE}"
 
+[tasks.git_sync]
+description = "Pull configured git repositories"
+handler = "git_sync"
+detect = "git"
+frequency = "daily"
+
 [run]
 order = [
     "brew_update",
@@ -78,4 +84,5 @@ order = [
     "mo_purge",
     "brew_cleanup",
     "brew_bundle",
+    "git_sync",
 ]

mac_upkeep-2.4.0/src/mac_upkeep/git_sync.py

@@ -0,0 +1,138 @@
+"""Built-in git_sync handler: fast-forward pulls a user-configured list of repos."""
+
+from __future__ import annotations
+
+import glob
+import os
+import re
+import subprocess
+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
+
+_ANSI_PATTERN = re.compile(r"\x1b\[[0-9;]*m")
+
+
+def _strip_ansi(text: str) -> str:
+    return _ANSI_PATTERN.sub("", text)
+
+
+def _build_env() -> dict[str, str]:
+    env = os.environ.copy()
+    env["GIT_TERMINAL_PROMPT"] = "0"
+    env.setdefault("GIT_ASKPASS", "/usr/bin/true")
+    return env
+
+
+def _run_git(path: str, args: list[str], *, timeout: int = 60) -> subprocess.CompletedProcess[str]:
+    return subprocess.run(
+        ["git", "-C", path, *args],
+        capture_output=True,
+        text=True,
+        timeout=timeout,
+        stdin=subprocess.DEVNULL,
+        env=_build_env(),
+    )
+
+
+def _resolve_paths(patterns: list[str], output: Output) -> list[str]:
+    """Expand user paths and globs; emit debug lines for empty matches."""
+    paths: list[str] = []
+    seen: set[str] = set()
+    for pattern in patterns:
+        expanded = os.path.expanduser(pattern)
+        if any(ch in expanded for ch in "*?["):
+            matches = sorted(glob.glob(expanded))
+            if not matches:
+                output.task_debug(f"no match: {pattern}")
+                continue
+            for m in matches:
+                if m not in seen:
+                    seen.add(m)
+                    paths.append(m)
+        else:
+            if expanded not in seen:
+                seen.add(expanded)
+                paths.append(expanded)
+    return paths
+
+
+def _sync_repo(path: str, *, skip_dirty: bool) -> tuple[str, str]:
+    """Sync one repo. Returns (status, reason) where status is pulled|up-to-date|skipped|failed."""
+    r = _run_git(path, ["rev-parse", "--is-inside-work-tree"])
+    if r.returncode != 0:
+        return "skipped", "not a git repo"
+
+    r = _run_git(path, ["remote"])
+    if r.returncode != 0 or not r.stdout.strip():
+        return "skipped", "no remote configured"
+
+    branch_r = _run_git(path, ["rev-parse", "--abbrev-ref", "HEAD"])
+    branch = branch_r.stdout.strip() or "?"
+    r = _run_git(path, ["rev-parse", "--abbrev-ref", "--symbolic-full-name", "@{upstream}"])
+    if r.returncode != 0:
+        return "skipped", f"no upstream (branch={branch})"
+
+    if skip_dirty:
+        r = _run_git(path, ["status", "--porcelain"])
+        if r.stdout.strip():
+            return "skipped", "dirty worktree"
+
+    r = _run_git(path, ["pull", "--ff-only"])
+    if r.returncode != 0:
+        stderr = _strip_ansi(r.stderr).strip().splitlines()
+        first = stderr[0] if stderr else f"exit {r.returncode}"
+        return "failed", first
+
+    stdout = _strip_ansi(r.stdout).strip().lower()
+    if "already up to date" in stdout or "already up-to-date" in stdout:
+        return "up-to-date", ""
+    return "pulled", ""
+
+
+def run_git_sync(config: Config, output: Output, dry_run: bool) -> TaskResult:
+    """Handler entry point. Aggregate per-repo results into a single TaskResult."""
+    patterns = list(config.git_sync_repos)
+    if not patterns:
+        return TaskResult("git_sync", "skipped", reason="no repos configured")
+
+    paths = _resolve_paths(patterns, output)
+    if not paths:
+        return TaskResult("git_sync", "skipped", reason="no repos matched")
+
+    if dry_run:
+        for path in paths:
+            output.task_debug(f"would pull: {path}")
+        return TaskResult("git_sync", "ok", reason=f"dry-run: {len(paths)} repos")
+
+    n_pulled = 0
+    n_skipped = 0
+    failures: list[str] = []
+    for path in paths:
+        status, reason = _sync_repo(path, skip_dirty=config.git_sync_skip_dirty)
+        display = f"{path}: {status}"
+        if reason:
+            display = f"{display} ({reason})"
+        output.task_debug(display)
+        if status in ("pulled", "up-to-date"):
+            n_pulled += 1
+        elif status == "skipped":
+            n_skipped += 1
+        else:
+            failures.append(os.path.basename(path.rstrip("/")))
+
+    if failures:
+        names = ", ".join(failures)
+        return TaskResult("git_sync", "failed", reason=f"{len(failures)} failed: {names}")
+
+    parts = []
+    if n_pulled:
+        parts.append(f"{n_pulled} pulled")
+    if n_skipped:
+        parts.append(f"{n_skipped} skipped")
+    reason = ", ".join(parts) if parts else "no repos processed"
+    return TaskResult("git_sync", "ok", reason=reason)

{mac_upkeep-2.3.0 → mac_upkeep-2.4.0}/src/mac_upkeep/tasks.py

@@ -10,7 +10,7 @@ import shlex
 import shutil
 import subprocess
 import time
-from datetime import datetime
+from datetime import datetime, timedelta
 from pathlib import Path
 from typing import TYPE_CHECKING
 
@@ -18,6 +18,8 @@ from mac_upkeep.config import Config, TaskDef, load_default_task_names
 from mac_upkeep.output import TaskResult
 
 if TYPE_CHECKING:
+    from collections.abc import Callable
+
     from mac_upkeep.output import Output
 
 logger = logging.getLogger("mac_upkeep")
@@ -32,7 +34,27 @@ ANSI_PATTERN = re.compile(r"\x1b\[[0-9;]*m")
 _xdg_state = os.environ.get("XDG_STATE_HOME", str(Path.home() / ".local" / "state"))
 _STATE_DIR = Path(_xdg_state) / "mac-upkeep"
 _STATE_FILE = _STATE_DIR / "last-run.json"
-FREQUENCY_THRESHOLDS = {"weekly": 6, "monthly": 27}  # days (buffer for schedule drift)
+FREQUENCY_THRESHOLDS: dict[str, timedelta] = {
+    "daily": timedelta(hours=20),
+    "weekly": timedelta(days=6),
+    "monthly": timedelta(days=27),
+}  # buffer for schedule drift
+
+# Handler registry: task handler name → (config, output, dry_run) -> TaskResult.
+# Tasks set handler="<name>" in defaults.toml to dispatch here instead of running a command.
+HANDLERS: dict[str, Callable[[Config, Output, bool], TaskResult]] = {}
+KNOWN_HANDLERS: set[str] = set()  # kept in sync with HANDLERS; read by config validation
+
+
+def _register_handlers() -> None:
+    """Register built-in handlers. Local import avoids any import-cycle risk."""
+    from mac_upkeep import git_sync
+
+    HANDLERS["git_sync"] = git_sync.run_git_sync
+    KNOWN_HANDLERS.add("git_sync")
+
+
+_register_handlers()
 
 
 def _load_state() -> dict[str, str]:
@@ -59,8 +81,8 @@ def _should_run(task_key: str, config: Config) -> bool:
         last_run = datetime.fromisoformat(last_run_str)
     except ValueError:
         return True
-    threshold_days = FREQUENCY_THRESHOLDS.get(config.get_frequency(task_key), 6)
-    return (datetime.now() - last_run).days >= threshold_days
+    threshold = FREQUENCY_THRESHOLDS.get(config.get_frequency(task_key), timedelta(days=6))
+    return (datetime.now() - last_run) >= threshold
 
 
 def _update_last_run(task_key: str) -> None:
@@ -71,23 +93,31 @@ def _update_last_run(task_key: str) -> None:
 
 
 def format_last_run(last_run_str: str | None) -> str:
-    """Humanize a last-run ISO timestamp: 'today', '1 day ago', 'N days ago', or 'never'."""
+    """Humanize a last-run ISO timestamp: 'just now', 'Xh ago', 'N days ago', or 'never'."""
     if not last_run_str:
         return "never"
     try:
         last_run = datetime.fromisoformat(last_run_str)
     except ValueError:
         return "never"
-    days = (datetime.now() - last_run).days
-    if days == 0:
-        return "today"
+    elapsed = datetime.now() - last_run
+    if elapsed < timedelta(days=1):
+        if elapsed < timedelta(minutes=5):
+            return "just now"
+        hours = int(elapsed.total_seconds() // 3600)
+        if hours == 0:
+            return "just now"
+        if hours == 1:
+            return "1 hour ago"
+        return f"{hours}h ago"
+    days = elapsed.days
     if days == 1:
         return "1 day ago"
     return f"{days} days ago"
 
 
 def format_next_run(task_key: str, config: Config, state: dict[str, str] | None = None) -> str:
-    """Return relative time until task is next eligible: 'now', 'in 1 day', 'in N days'."""
+    """Return relative time until task is next eligible: 'now', 'in Xh', 'in N days'."""
     if state is None:
         state = _load_state()
     last_run_str = state.get(task_key)
@@ -98,13 +128,21 @@ def format_next_run(task_key: str, config: Config, state: dict[str, str] | None
     except ValueError:
         return "now"
     frequency = config.get_frequency(task_key)
-    threshold = FREQUENCY_THRESHOLDS.get(frequency, 6)
-    remaining = threshold - (datetime.now() - last_run).days
-    if remaining <= 0:
+    threshold = FREQUENCY_THRESHOLDS.get(frequency, timedelta(days=6))
+    remaining = threshold - (datetime.now() - last_run)
+    if remaining <= timedelta(0):
         return "now"
-    if remaining == 1:
+    if remaining < timedelta(days=1):
+        hours = int(remaining.total_seconds() // 3600)
+        if hours == 0:
+            return "in <1h"
+        if hours == 1:
+            return "in 1 hour"
+        return f"in {hours}h"
+    remaining_days = threshold.days - (datetime.now() - last_run).days
+    if remaining_days == 1:
         return "in 1 day"
-    return f"in {remaining} days"
+    return f"in {remaining_days} days"
 
 
 def strip_ansi(text: str) -> str:
@@ -239,6 +277,57 @@ def _run(
     return result
 
 
+def _run_handler(
+    name: str,
+    td: TaskDef,
+    *,
+    config: Config,
+    output: Output,
+    dry_run: bool,
+    force_tasks: set[str] | None,
+) -> TaskResult:
+    """Dispatch a handler-driven task. Mirrors _run's filter/frequency/detect contract."""
+    task_key = name.lower().replace(" ", "_")
+
+    if force_tasks is not None and task_key not in force_tasks:
+        result = TaskResult(name, "skipped", reason="not selected")
+        output.task_done(result)
+        return result
+
+    if not dry_run and force_tasks is None and not _should_run(task_key, config):
+        next_str = format_next_run(task_key, config)
+        result = TaskResult(name, "skipped", reason=f"ran recently, next {next_str}")
+        output.task_done(result)
+        return result
+
+    if not config.is_enabled(task_key):
+        result = TaskResult(name, "skipped", reason="disabled")
+        output.task_done(result)
+        return result
+
+    if td.detect and not shutil.which(td.detect):
+        result = TaskResult(name, "skipped", reason="not installed")
+        output.task_done(result)
+        return result
+
+    output.task_start(name)
+    start = time.monotonic()
+    result = HANDLERS[td.handler](config, output, dry_run)
+    if result.duration == 0.0:
+        result = TaskResult(
+            result.name,
+            result.status,
+            reason=result.reason,
+            duration=time.monotonic() - start,
+        )
+    output.task_done(result)
+
+    if result.status == "ok" and not dry_run:
+        _update_last_run(task_key)
+
+    return result
+
+
 def run_all_tasks(
     *,
     config: Config,
@@ -254,6 +343,20 @@ def run_all_tasks(
         if td is None:
             continue
 
+        # Handler-dispatched tasks bypass subprocess command building
+        if td.handler:
+            results.append(
+                _run_handler(
+                    task_name,
+                    td,
+                    config=config,
+                    output=output,
+                    dry_run=dry_run,
+                    force_tasks=force_tasks,
+                )
+            )
+            continue
+
         # require_file tasks: check filter → enabled → file exists
         # (preserves current brew_bundle delegation pattern)
         if td.require_file and not Path(td.require_file).is_file():

{mac_upkeep-2.3.0 → mac_upkeep-2.4.0}/tests/test_cli.py

@@ -195,7 +195,7 @@ def test_show_config_user_config(tmp_path):
 def test_run_no_notification_when_all_skipped(tmp_path, monkeypatch):
     """Boot scenario: all tasks skip (ran recently) → no notification."""
     state_file = tmp_path / "last-run.json"
-    recent = (datetime.now() - timedelta(days=1)).isoformat(timespec="seconds")
+    recent = (datetime.now() - timedelta(hours=1)).isoformat(timespec="seconds")
     state = {
         name: recent
         for name in [
@@ -210,6 +210,7 @@ def test_run_no_notification_when_all_skipped(tmp_path, monkeypatch):
             "mo_purge",
             "brew_cleanup",
             "brew_bundle",
+            "git_sync",
         ]
     }
     state_file.write_text(json.dumps(state))