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

{mac_upkeep-2.2.0 → mac_upkeep-2.3.0}/.github/workflows/test.yml

@@ -7,9 +7,14 @@ on:
 jobs:
   test:
     runs-on: macos-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
     steps:
       - uses: actions/checkout@v4
       - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: ${{ matrix.python-version }}
       - run: uv lock --check
       - run: uv sync
       - run: uv run ruff check src/ tests/

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

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

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

@@ -1,5 +1,21 @@
 # Changelog
 
+## [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)
+
+
+### Miscellaneous
+
+* improve PyPI metadata and CI coverage ([#30](https://github.com/calvindotsg/mac-upkeep/issues/30)) ([7428b61](https://github.com/calvindotsg/mac-upkeep/commit/7428b610d1523d0e4b22e397185ad68e01240940))
+
 ## [2.2.0](https://github.com/calvindotsg/mac-upkeep/compare/v2.1.2...v2.2.0) (2026-04-09)
 
 

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

@@ -23,8 +23,8 @@ defaults.toml → bundled task definitions (11 tasks), loaded via importlib.reso
 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)
 ```
@@ -64,6 +64,8 @@ Do not add conditions to the filter or remove the `force_tasks is None` guard fr
 - Thresholds are 6 days for weekly and 27 days for monthly (not 7/30 — buffer for launchd schedule drift after sleep/reboot). State tracked in `~/.local/state/mac-upkeep/last-run.json`.
 - **Safety net**: prevents redundant runs from 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,7 @@ 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).
 
 ### sudo + HOME
 

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

@@ -1,12 +1,11 @@
 Metadata-Version: 2.4
 Name: mac-upkeep
-Version: 2.2.0
+Version: 2.3.0
 Summary: Automated macOS maintenance CLI
 Project-URL: Homepage, https://github.com/calvindotsg/mac-upkeep
 Project-URL: Repository, https://github.com/calvindotsg/mac-upkeep
 Project-URL: Issues, https://github.com/calvindotsg/mac-upkeep/issues
 Project-URL: Changelog, https://github.com/calvindotsg/mac-upkeep/blob/main/CHANGELOG.md
-Project-URL: Documentation, https://github.com/calvindotsg/mac-upkeep#readme
 Author: Calvin
 License-Expression: MIT
 License-File: LICENSE
@@ -15,13 +14,13 @@ Classifier: Development Status :: 4 - Beta
 Classifier: Environment :: Console
 Classifier: Environment :: MacOS X
 Classifier: Intended Audience :: Developers
-Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: MacOS
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: System :: Systems Administration
+Classifier: Typing :: Typed
 Requires-Python: >=3.11
 Requires-Dist: typer>=0.12
 Description-Content-Type: text/markdown
@@ -71,7 +70,7 @@ uvx mac-upkeep run            # one-off without installing
 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
@@ -82,12 +81,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

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

@@ -43,7 +43,7 @@ uvx mac-upkeep run            # one-off without installing
 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 +54,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

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

@@ -22,7 +22,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.0 → mac_upkeep-2.3.0}/llms.txt

@@ -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 (weekly/monthly) with schedule drift buffers and next-run visibility
 - Custom tasks in user config.toml
 
 ## Links

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

@@ -1,25 +1,26 @@
 [project]
 name = "mac-upkeep"
-version = "2.2.0"
+version = "2.3.0"
 description = "Automated macOS maintenance CLI"
 readme = "README.md"
 license = "MIT"
+license-files = ["LICEN[CS]E*"]
 requires-python = ">=3.11"
 dependencies = ["typer>=0.12"]
-authors = [{name = "Calvin", url = "https://github.com/calvindotsg"}]
+authors = [{name = "Calvin"}]
 keywords = ["macos", "maintenance", "homebrew", "cli", "automation", "system-administration", "developer-tools", "cache-management"]
 classifiers = [
     "Development Status :: 4 - Beta",
     "Environment :: Console",
     "Environment :: MacOS X",
     "Intended Audience :: Developers",
-    "License :: OSI Approved :: MIT License",
     "Operating System :: MacOS",
     "Programming Language :: Python :: 3",
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
     "Programming Language :: Python :: 3.13",
     "Topic :: System :: Systems Administration",
+    "Typing :: Typed",
 ]
 
 [project.urls]
@@ -27,7 +28,6 @@ Homepage = "https://github.com/calvindotsg/mac-upkeep"
 Repository = "https://github.com/calvindotsg/mac-upkeep"
 Issues = "https://github.com/calvindotsg/mac-upkeep/issues"
 Changelog = "https://github.com/calvindotsg/mac-upkeep/blob/main/CHANGELOG.md"
-Documentation = "https://github.com/calvindotsg/mac-upkeep#readme"
 
 [project.scripts]
 mac-upkeep = "mac_upkeep.cli:app"

{mac_upkeep-2.2.0 → mac_upkeep-2.3.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"
@@ -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()
@@ -399,19 +415,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.0 → mac_upkeep-2.3.0}/src/mac_upkeep/tasks.py

@@ -70,6 +70,43 @@ def _update_last_run(task_key: str) -> None:
     _save_state(state)
 
 
+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'."""
+    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"
+    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'."""
+    if state is None:
+        state = _load_state()
+    last_run_str = state.get(task_key)
+    if not last_run_str:
+        return "now"
+    try:
+        last_run = datetime.fromisoformat(last_run_str)
+    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:
+        return "now"
+    if remaining == 1:
+        return "in 1 day"
+    return f"in {remaining} days"
+
+
 def strip_ansi(text: str) -> str:
     """Remove ANSI color codes from text."""
     return ANSI_PATTERN.sub("", text)
@@ -175,7 +212,8 @@ def _run(
 
     # Frequency: skip if ran recently (no --force = frequency applies)
     if not dry_run and force_tasks is None and not _should_run(task_key, config):
-        result = TaskResult(name, "skipped", reason="ran recently")
+        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
 

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

@@ -50,6 +50,19 @@ def test_tasks_command():
     assert result.exit_code == 0
     for name in ["brew_update", "gcloud", "mo_clean", "brew_bundle"]:
         assert name in result.output
+    assert "ready" in result.output
+
+
+def test_tasks_shows_not_found_status(tmp_path):
+    config_path = tmp_path / "config.toml"
+    with (
+        patch("mac_upkeep.cli.DEFAULT_CONFIG_PATH", config_path),
+        patch("mac_upkeep.config.get_brew_prefix", return_value="/opt/homebrew"),
+        patch("mac_upkeep.cli.shutil.which", return_value=None),
+    ):
+        result = runner.invoke(app, ["tasks"])
+    assert result.exit_code == 0
+    assert "not found" in result.output
 
 
 def test_force_invalid_shows_valid_tasks():
@@ -207,6 +220,51 @@ def test_run_no_notification_when_all_skipped(tmp_path, monkeypatch):
     mock_notify.assert_not_called()
 
 
+# --- status command ---
+
+_MOCK_SVC_INFO = {
+    "name": "mac-upkeep",
+    "running": False,
+    "loaded": True,
+    "exit_code": 0,
+    "status": "scheduled",
+    "cron": {"Month": "*", "Day": "*", "Weekday": 1, "Hour": 12, "Minute": 0},
+}
+
+
+def test_status_shows_service_info():
+    """Status shows service state when brew services is available."""
+    with patch("mac_upkeep.cli._get_service_info", return_value=_MOCK_SVC_INFO):
+        result = runner.invoke(app, ["status"])
+    assert result.exit_code == 0
+    assert "mac-upkeep v" in result.output
+    assert "scheduled" in result.output
+    assert "exit: 0" in result.output
+    assert "tasks" in result.output
+
+
+def test_status_graceful_degradation():
+    """Status shows task summary even when brew services is unavailable."""
+    with patch("mac_upkeep.cli._get_service_info", return_value=None):
+        result = runner.invoke(app, ["status"])
+    assert result.exit_code == 0
+    assert "mac-upkeep v" in result.output
+    assert "tasks" in result.output
+
+
+def test_status_overdue_tasks(tmp_path, monkeypatch):
+    """Tasks that have never run appear as overdue in summary."""
+    state_file = tmp_path / "last-run.json"
+    state_file.write_text("{}")  # empty state — all tasks eligible
+    monkeypatch.setattr("mac_upkeep.tasks._STATE_FILE", state_file)
+
+    with patch("mac_upkeep.cli._get_service_info", return_value=None):
+        result = runner.invoke(app, ["status"])
+
+    assert result.exit_code == 0
+    assert "overdue" in result.output
+
+
 def test_run_sends_notification_on_activity(tmp_path, monkeypatch):
     """Scheduled run: at least one task ran → notification sent."""
     state_file = tmp_path / "last-run.json"

{mac_upkeep-2.2.0 → mac_upkeep-2.3.0}/tests/test_tasks.py

@@ -14,6 +14,8 @@ from mac_upkeep.tasks import (
     _run,
     _should_run,
     _update_last_run,
+    format_last_run,
+    format_next_run,
     run_all_tasks,
     run_task,
     strip_ansi,
@@ -246,7 +248,7 @@ def test_run_frequency_skip(tmp_path, monkeypatch):
         detect="gcloud",
     )
     assert result.status == "skipped"
-    assert result.reason == "ran recently"
+    assert result.reason.startswith("ran recently, next")
 
 
 @patch("mac_upkeep.tasks.subprocess.run")
@@ -365,3 +367,68 @@ def test_failed_task_no_timestamp_update(mock_which, mock_run, tmp_path, monkeyp
     )
     assert result.status == "failed"
     assert not state_file.exists()
+
+
+# --- format_last_run ---
+
+
+def test_format_last_run_none():
+    assert format_last_run(None) == "never"
+
+
+def test_format_last_run_corrupt():
+    assert format_last_run("not-a-date") == "never"
+
+
+def test_format_last_run_today():
+    ts = datetime.now().isoformat(timespec="seconds")
+    assert format_last_run(ts) == "today"
+
+
+def test_format_last_run_one_day_ago():
+    ts = (datetime.now() - timedelta(days=1)).isoformat(timespec="seconds")
+    assert format_last_run(ts) == "1 day ago"
+
+
+def test_format_last_run_many_days_ago():
+    ts = (datetime.now() - timedelta(days=5)).isoformat(timespec="seconds")
+    assert format_last_run(ts) == "5 days ago"
+
+
+# --- format_next_run ---
+
+
+def test_format_next_run_never_ran(tmp_path, monkeypatch):
+    """Never ran → immediately eligible → 'now'."""
+    monkeypatch.setattr("mac_upkeep.tasks._STATE_FILE", tmp_path / "last-run.json")
+    config = Config.load()
+    assert format_next_run("gcloud", config) == "now"
+
+
+def test_format_next_run_within_threshold(tmp_path, monkeypatch):
+    """gcloud is monthly (27-day threshold), ran 1 day ago → 26 days remaining."""
+    state_file = tmp_path / "last-run.json"
+    recent = (datetime.now() - timedelta(days=1)).isoformat(timespec="seconds")
+    state_file.write_text(json.dumps({"gcloud": recent}))
+    monkeypatch.setattr("mac_upkeep.tasks._STATE_FILE", state_file)
+    config = Config.load()
+    assert format_next_run("gcloud", config) == "in 26 days"
+
+
+def test_format_next_run_past_threshold(tmp_path, monkeypatch):
+    """gcloud ran 30 days ago (past 27-day threshold) → 'now'."""
+    state_file = tmp_path / "last-run.json"
+    old = (datetime.now() - timedelta(days=30)).isoformat(timespec="seconds")
+    state_file.write_text(json.dumps({"gcloud": old}))
+    monkeypatch.setattr("mac_upkeep.tasks._STATE_FILE", state_file)
+    config = Config.load()
+    assert format_next_run("gcloud", config) == "now"
+
+
+def test_format_next_run_with_state_param(tmp_path, monkeypatch):
+    """Pre-loaded state dict bypasses file read and produces same result."""
+    monkeypatch.setattr("mac_upkeep.tasks._STATE_FILE", tmp_path / "last-run.json")
+    config = Config.load()
+    recent = (datetime.now() - timedelta(days=1)).isoformat(timespec="seconds")
+    state = {"gcloud": recent}
+    assert format_next_run("gcloud", config, state) == "in 26 days"

{mac_upkeep-2.2.0 → mac_upkeep-2.3.0}/uv.lock

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

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

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