mac-upkeep 2.2.1__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.2.1 → mac_upkeep-2.4.0}/CHANGELOG.md

@@ -1,5 +1,21 @@
 # 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)
+
+
+### Features
+
+* add next scheduled run visibility to tasks and run ([6317ce1](https://github.com/calvindotsg/mac-upkeep/commit/6317ce18c041a8f29a8e8534a061bfd3aec24343))
+* add next scheduled run visibility to tasks and run ([34dbe93](https://github.com/calvindotsg/mac-upkeep/commit/34dbe93fab3781d7ce669c852b6c06eb0ab8d5ca))
+* redesign status command as scheduling dashboard ([#34](https://github.com/calvindotsg/mac-upkeep/issues/34)) ([86ca27c](https://github.com/calvindotsg/mac-upkeep/commit/86ca27cb7f7b1fd8878996552246061ebdd6d598))
+
 ## [2.2.1](https://github.com/calvindotsg/mac-upkeep/compare/v2.2.0...v2.2.1) (2026-04-09)
 
 

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

@@ -19,12 +19,12 @@
 ## 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,
-                frequency scheduling, ANSI stripping
-cli.py        → Typer app: run, tasks, init, show-config, setup, status, logs, notify-test
+                frequency scheduling, format_last_run(), format_next_run(), ANSI stripping
+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)
 notify.py     → macOS notifications via terminal-notifier (preferred) / osascript (fallback)
 ```
@@ -61,9 +61,11 @@ 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).
+- **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.
 
 ### Output and notifications
 
@@ -73,6 +75,11 @@ Do not add conditions to the filter or remove the `force_tasks is None` guard fr
 - **terminal-notifier preferred**: `shutil.which("terminal-notifier")` tries the richer tool first. Fallback to osascript loses `-group` (dedup), `-activate` (focus terminal), `-open` (click action).
 - **Bundle ID detection chain**: `CMUX_BUNDLE_ID` env var → Ghostty.app plist via `defaults read` → `com.apple.Terminal` fallback.
 - **Rich is a transitive dependency**: `typer>=0.12` requires `rich>=12.3.0`. Using Rich adds zero new runtime dependencies.
+- **`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
 
@@ -95,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.2.1 → mac_upkeep-2.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mac-upkeep
-Version: 2.2.1
+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,11 +66,12 @@ 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.
 
 ```bash
-mac-upkeep tasks  # See all tasks with frequency and last-run status
+mac-upkeep tasks  # See all tasks with status, frequency, and next run
 ```
 
 ## Usage
@@ -81,12 +82,12 @@ mac-upkeep run --dry-run             # Preview without executing
 mac-upkeep run --force brew_update   # Run only brew_update
 mac-upkeep run --force all           # Run all, ignoring schedule
 mac-upkeep run --debug               # Verbose output
-mac-upkeep tasks                     # List tasks with status
+mac-upkeep tasks                     # List tasks with status and next run
 mac-upkeep init                      # Generate config (detects your tools)
 mac-upkeep show-config --default     # Show all available task options
 mac-upkeep show-config               # Show your config overrides
 mac-upkeep setup                     # Print sudoers rules
-mac-upkeep status                    # Show brew service status
+mac-upkeep status                    # Show scheduling dashboard
 mac-upkeep logs                      # View last 20 log lines
 mac-upkeep logs -f                   # Follow logs
 mac-upkeep --version                 # Show version
@@ -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.2.1 → mac_upkeep-2.4.0}/README.md

@@ -39,11 +39,12 @@ 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.
 
 ```bash
-mac-upkeep tasks  # See all tasks with frequency and last-run status
+mac-upkeep tasks  # See all tasks with status, frequency, and next run
 ```
 
 ## Usage
@@ -54,12 +55,12 @@ mac-upkeep run --dry-run             # Preview without executing
 mac-upkeep run --force brew_update   # Run only brew_update
 mac-upkeep run --force all           # Run all, ignoring schedule
 mac-upkeep run --debug               # Verbose output
-mac-upkeep tasks                     # List tasks with status
+mac-upkeep tasks                     # List tasks with status and next run
 mac-upkeep init                      # Generate config (detects your tools)
 mac-upkeep show-config --default     # Show all available task options
 mac-upkeep show-config               # Show your config overrides
 mac-upkeep setup                     # Print sudoers rules
-mac-upkeep status                    # Show brew service status
+mac-upkeep status                    # Show scheduling dashboard
 mac-upkeep logs                      # View last 20 log lines
 mac-upkeep logs -f                   # Follow logs
 mac-upkeep --version                 # Show version
@@ -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.2.1 → 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)
@@ -22,7 +23,7 @@ Adjust versions/paths:
 - terminal-notifier with osascript fallback for any macOS launchd service needing actionable notifications
 - `repository_dispatch` + GitHub App for cross-repo automation
 - `subprocess.run(stdin=subprocess.DEVNULL)` for any CLI orchestrator wrapping interactive tools
-- Per-task frequency scheduling with XDG state file + threshold buffers for any periodic CLI tool
+- Per-task frequency scheduling with XDG state file + threshold buffers + humanized next-run/last-run formatting for any periodic CLI tool
 - `RunAtLoad true` + application-level frequency thresholds for reliable launchd scheduling on laptops — `StartCalendarInterval` does NOT coalesce from power-off (only sleep), so RunAtLoad is the reliable trigger with thresholds preventing over-running
 - Notification suppression when all tasks skip (`has_activity` guard) — for any RunAtLoad service that would otherwise notify on every boot
 - newsyslog.d config generation via setup command for any macOS launchd service needing log rotation

{mac_upkeep-2.2.1 → 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
+- 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.2.1 → mac_upkeep-2.4.0}/pyproject.toml

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

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

@@ -4,6 +4,7 @@ from __future__ import annotations
 
 import getpass
 import importlib.resources
+import json
 import logging
 import os
 import shutil
@@ -27,7 +28,7 @@ from mac_upkeep.config import (
 )
 from mac_upkeep.notify import detect_terminal_bundle_id, format_summary, notify
 from mac_upkeep.output import Output
-from mac_upkeep.tasks import TASKS, _load_state, run_all_tasks
+from mac_upkeep.tasks import TASKS, _load_state, format_last_run, format_next_run, run_all_tasks
 
 app = typer.Typer(
     help="Automated macOS mac-upkeep CLI.\n\n"
@@ -126,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).
 
@@ -188,20 +189,35 @@ def tasks() -> None:
         table.add_column("Task", min_width=14)
         table.add_column("Description", min_width=20)
         table.add_column("Frequency", min_width=8)
-        table.add_column("Enabled", min_width=7)
+        table.add_column("Status", min_width=8)
         table.add_column("Last Run", min_width=10)
+        table.add_column("Next Run", min_width=10)
 
         for name, td in task_list:
-            enabled = "[green]yes[/green]" if td.enabled else "[dim]no[/dim]"
-            last_run = state.get(name, "never")
-            table.add_row(name, td.description, td.frequency, enabled, last_run)
+            if not td.enabled:
+                status = "[dim]disabled[/dim]"
+            elif shutil.which(td.detect) is None:
+                status = "[yellow]not found[/yellow]"
+            else:
+                status = "[green]ready[/green]"
+            last_run = format_last_run(state.get(name))
+            next_run = "[dim]—[/dim]" if not td.enabled else format_next_run(name, config, state)
+            table.add_row(name, td.description, td.frequency, status, last_run, next_run)
 
         Console(highlight=False).print(table)
     else:
         for name, td in task_list:
-            enabled = "yes" if td.enabled else "no"
-            last_run = state.get(name, "never")
-            typer.echo(f"{name}\t{td.description}\t{td.frequency}\t{enabled}\t{last_run}")
+            if not td.enabled:
+                status = "disabled"
+            elif shutil.which(td.detect) is None:
+                status = "not found"
+            else:
+                status = "ready"
+            last_run = format_last_run(state.get(name))
+            next_run = "—" if not td.enabled else format_next_run(name, config, state)
+            typer.echo(
+                f"{name}\t{td.description}\t{td.frequency}\t{status}\t{last_run}\t{next_run}"
+            )
 
 
 @app.command()
@@ -303,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]")
@@ -399,19 +423,159 @@ def setup() -> None:
     typer.echo("#   | sudo tee /etc/newsyslog.d/mac-upkeep.conf")
 
 
-@app.command()
-def status() -> None:
-    """Show brew service status for mac-upkeep."""
+def _get_service_info() -> dict | None:
+    """Query brew services info as JSON. Returns None on failure."""
     try:
         result = subprocess.run(
-            ["brew", "services", "info", "mac-upkeep"],
+            ["brew", "services", "info", "mac-upkeep", "--json"],
             capture_output=True,
             text=True,
         )
-        typer.echo(result.stdout.strip())
-    except FileNotFoundError:
-        typer.echo("brew not found. Install Homebrew first.")
-        raise typer.Exit(1)
+        if result.returncode != 0:
+            return None
+        data = json.loads(result.stdout)
+        return data[0] if data else None
+    except (FileNotFoundError, json.JSONDecodeError, IndexError, OSError):
+        return None
+
+
+_WEEKDAY_NAMES = [
+    "Sunday",
+    "Monday",
+    "Tuesday",
+    "Wednesday",
+    "Thursday",
+    "Friday",
+    "Saturday",
+]
+
+
+def _format_cron_schedule(cron: dict, loaded: bool) -> str:
+    """Convert launchd cron dict + loaded flag to schedule string."""
+    wd = cron.get("Weekday")
+    hour = cron.get("Hour", 0)
+    minute = cron.get("Minute", 0)
+    day_name = _WEEKDAY_NAMES[wd] if wd is not None and 0 <= wd <= 6 else "?"
+    period = "AM" if hour < 12 else "PM"
+    h12 = hour % 12 or 12
+    schedule = f"Every {day_name} at {h12}:{minute:02d} {period}"
+    if loaded:
+        schedule += " + on boot"
+    return schedule
+
+
+def _next_trigger_date(cron: dict) -> str:
+    """Compute next launchd trigger date from cron weekday. Returns 'Mon Apr 14' style."""
+    from datetime import date, timedelta
+
+    launchd_wd = cron.get("Weekday")
+    if launchd_wd is None:
+        return "—"
+    # launchd: 0=Sunday, 1=Monday, ..., 6=Saturday
+    # Python weekday: 0=Monday, ..., 6=Sunday → py_wd = (launchd_wd - 1) % 7
+    py_wd = (launchd_wd - 1) % 7
+    today = date.today()
+    days_ahead = (py_wd - today.weekday()) % 7
+    next_date = today + timedelta(days=days_ahead)
+    return next_date.strftime("%a %b %-d")
+
+
+@app.command()
+def status() -> None:
+    """Show scheduling dashboard: service state, schedule, and tasks due."""
+    try:
+        v = pkg_version("mac-upkeep")
+    except Exception:
+        v = "unknown"
+
+    config = Config.load()
+    state = _load_state()
+    svc = _get_service_info()
+
+    task_list = [
+        (name, config.task_defs[name]) for name in config.run_order if name in config.task_defs
+    ]
+    total = len(task_list)
+    ready_count = disabled_count = not_found_count = 0
+    overdue: list = []
+    due_soon: list = []
+
+    for name, td in task_list:
+        if not td.enabled:
+            disabled_count += 1
+            continue
+        if shutil.which(td.detect) is None:
+            not_found_count += 1
+            continue
+        ready_count += 1
+        next_str = format_next_run(name, config, state)
+        last_str = format_last_run(state.get(name))
+        if next_str == "now":
+            overdue.append((name, td, last_str, next_str))
+        elif next_str in ("in 1 day", "in 2 days"):
+            due_soon.append((name, td, last_str, next_str))
+
+    tasks_needing_attention = overdue + due_soon
+
+    summary_parts = [f"{total} tasks", f"{ready_count} ready"]
+    if disabled_count:
+        summary_parts.append(f"{disabled_count} disabled")
+    if not_found_count:
+        summary_parts.append(f"{not_found_count} not found")
+    if overdue:
+        summary_parts.append(f"{len(overdue)} overdue")
+    summary_line = ", ".join(summary_parts)
+
+    if sys.stdout.isatty():
+        from rich.console import Console
+
+        console = Console(highlight=False)
+        console.print(f"[bold]mac-upkeep v{v}[/bold]")
+        console.print()
+        if svc:
+            svc_status = svc.get("status", "unknown")
+            exit_code = svc.get("exit_code", "?")
+            cron = svc.get("cron")
+            loaded = svc.get("loaded", False)
+            exit_str = f"{exit_code} (success)" if exit_code == 0 else str(exit_code)
+            console.print(f"  [dim]Service  [/dim]  {svc_status}")
+            if cron:
+                console.print(f"  [dim]Schedule [/dim]  {_format_cron_schedule(cron, loaded)}")
+            console.print(f"  [dim]Last exit[/dim]  {exit_str}")
+            console.print()
+        if tasks_needing_attention:
+            console.print("  [bold]Tasks due:[/bold]")
+            for name, td, last_str, next_str in tasks_needing_attention:
+                if next_str == "now":
+                    next_display = "[red]⚠ overdue[/red]"
+                else:
+                    next_display = f"[yellow]{next_str}[/yellow]"
+                console.print(
+                    f"    {name:<18} {td.frequency:<8} last: {last_str:<16} {next_display}"
+                )
+            console.print()
+            console.print(f"  {summary_line}")
+        else:
+            cron = svc.get("cron") if svc else None
+            if cron:
+                next_trigger = _next_trigger_date(cron)
+                console.print(
+                    f"  [green]{summary_line} up to date[/green], next run {next_trigger}"
+                )
+            else:
+                console.print(f"  [green]{summary_line} up to date[/green]")
+    else:
+        header_parts = [f"mac-upkeep v{v}"]
+        if svc:
+            header_parts.append(svc.get("status", "unknown"))
+            exit_code = svc.get("exit_code", "?")
+            header_parts.append(f"exit: {exit_code}")
+            cron = svc.get("cron")
+            if cron:
+                next_trigger = _next_trigger_date(cron)
+                header_parts.append(f"next: {next_trigger}")
+        typer.echo(" | ".join(header_parts))
+        typer.echo(summary_line)
 
 
 @app.command()

{mac_upkeep-2.2.1 → 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.2.1 → 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",
 ]