@albeorla/launchd-kit 1.0.0

package/README.md

@@ -0,0 +1,42 @@
+# launchd-kit
+
+Shared tooling for managing local LaunchAgents.
+
+## What Lives Here
+- `bin/`: install/uninstall/reload/status/log helpers
+- `plist-monitor/`: Discord webhook monitoring
+- `plist-status.py`: terminal status dashboard
+- `templates/`: plist templates
+
+## Environment Variables
+- `LAUNCHD_LABEL_PREFIX` (default: `com.user.`)
+- `LAUNCHD_PLIST_GLOB` (default: `*/<prefix>*.plist`)
+- `LAUNCHD_INSTALL_DIR` (default: `~/Library/LaunchAgents`)
+- `PLIST_MONITOR_ENV` (optional `.env` path override)
+
+## Typical Usage (local wrapper justfile)
+In each repo, add a small `justfile` that calls `launchd-kit/bin/*`.
+
+Example:
+- `just install` → `~/dev/launchd-kit/bin/launchd-install '*/com.user.admin.*.plist'`
+- `just status` → `~/dev/launchd-kit/bin/launchd-status`
+
+## Creating Jobs
+See `docs/new-job.md` and the generator:
+- `bin/launchd-new-job`
+
+## Monitoring
+`plist-monitor` scans all loaded agents by prefix (defaults to `com.user.`).
+You can override the filter via `LAUNCHD_PREFIX_FILTER` in the monitor's environment.
+
+Suggested model:
+- One global monitor job (e.g., in `admin`) with `LAUNCHD_PREFIX_FILTER=com.user.` to watch all agents.
+- Domain repos only define their own jobs; they don't need their own monitor unless you want per-domain alerts.
+
+## Recommended Job Layout
+In each repo, keep jobs self-contained:
+- `jobs/<job>/job.sh`
+- `jobs/<job>/com.user.<domain_id>.<job>.plist`
+- `jobs/<job>/README.md`
+
+If you prefer existing layouts (e.g., `scripts/` + `*.plist`), keep them; just point the glob in your wrapper justfile.

package/bin/launchd-install

@@ -0,0 +1,27 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+prefix="${LAUNCHD_LABEL_PREFIX:-com.user.}"
+plist_glob="${1:-${LAUNCHD_PLIST_GLOB:-*/${prefix}*.plist}}"
+install_dir="${LAUNCHD_INSTALL_DIR:-$HOME/Library/LaunchAgents}"
+uid=$(id -u)
+
+shopt -s nullglob
+plists=( $plist_glob )
+
+if [[ ${#plists[@]} -eq 0 ]]; then
+    echo "No plists matched pattern: $plist_glob" >&2
+    exit 1
+fi
+
+mkdir -p "$install_dir"
+
+count=0
+for plist in "${plists[@]}"; do
+    name=$(basename "$plist")
+    ln -sf "$(pwd)/$plist" "$install_dir/$name"
+    launchctl bootstrap gui/"$uid" "$install_dir/$name" 2>/dev/null || true
+    count=$((count + 1))
+done
+
+echo "Installed $count agent(s)"

package/bin/launchd-log-dirs

@@ -0,0 +1,9 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+prefix="${LAUNCHD_LABEL_PREFIX:-com.user.}"
+plutil -p "$HOME/Library/LaunchAgents/${prefix}"*.plist \
+  | grep -o '"/tmp/[^"]*"' \
+  | tr -d '"' \
+  | xargs -n1 dirname \
+  | sort -u

package/bin/launchd-logs

@@ -0,0 +1,21 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+_self="$0"
+[ -L "$_self" ] && { _t="$(readlink "$_self")"; [[ "$_t" != /* ]] && _t="$(dirname "$_self")/$_t"; _self="$_t"; }
+SCRIPT_DIR="$(cd "$(dirname "$_self")" && pwd)"
+
+"$SCRIPT_DIR/launchd-log-dirs" > /tmp/launchd-kit-log-dirs.txt
+mapfile -t dirs < /tmp/launchd-kit-log-dirs.txt
+
+if [[ ${#dirs[@]} -eq 0 ]]; then
+    echo "No log directories found" >&2
+    exit 1
+fi
+
+globs=()
+for d in "${dirs[@]}"; do
+    globs+=("$d"/*.log)
+done
+
+exec tail -F "${globs[@]}"

package/bin/launchd-logs-all

@@ -0,0 +1,21 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+_self="$0"
+[ -L "$_self" ] && { _t="$(readlink "$_self")"; [[ "$_t" != /* ]] && _t="$(dirname "$_self")/$_t"; _self="$_t"; }
+SCRIPT_DIR="$(cd "$(dirname "$_self")" && pwd)"
+
+"$SCRIPT_DIR/launchd-log-dirs" > /tmp/launchd-kit-log-dirs.txt
+mapfile -t dirs < /tmp/launchd-kit-log-dirs.txt
+
+if [[ ${#dirs[@]} -eq 0 ]]; then
+    echo "No log directories found" >&2
+    exit 1
+fi
+
+globs=()
+for d in "${dirs[@]}"; do
+    globs+=("$d"/*)
+done
+
+exec tail -F "${globs[@]}"

package/bin/launchd-logs-err

@@ -0,0 +1,21 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+_self="$0"
+[ -L "$_self" ] && { _t="$(readlink "$_self")"; [[ "$_t" != /* ]] && _t="$(dirname "$_self")/$_t"; _self="$_t"; }
+SCRIPT_DIR="$(cd "$(dirname "$_self")" && pwd)"
+
+"$SCRIPT_DIR/launchd-log-dirs" > /tmp/launchd-kit-log-dirs.txt
+mapfile -t dirs < /tmp/launchd-kit-log-dirs.txt
+
+if [[ ${#dirs[@]} -eq 0 ]]; then
+    echo "No log directories found" >&2
+    exit 1
+fi
+
+globs=()
+for d in "${dirs[@]}"; do
+    globs+=("$d"/*.err)
+done
+
+exec tail -F "${globs[@]}"

package/bin/launchd-new-job

@@ -0,0 +1,85 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+_self="$0"
+[ -L "$_self" ] && { _t="$(readlink "$_self")"; [[ "$_t" != /* ]] && _t="$(dirname "$_self")/$_t"; _self="$_t"; }
+SCRIPT_DIR="$(cd "$(dirname "$_self")" && pwd)"
+
+usage() {
+    cat <<'USAGE'
+Usage:
+  launchd-new-job \
+    --label com.user.<domain>.<job> \
+    --program /abs/path/to/job.sh \
+    --working-dir /abs/path/to/repo \
+    [--interval 3600] \
+    [--log-dir /tmp/<domain>] \
+    --out path/to/com.user.<domain>.<job>.plist
+
+Notes:
+- Generates a StartInterval plist using templates/job.plist.tmpl
+- For calendar schedules, edit the plist manually
+USAGE
+}
+
+label=""
+program=""
+working_dir=""
+interval="3600"
+log_dir=""
+out_path=""
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --label) label="$2"; shift 2;;
+        --program) program="$2"; shift 2;;
+        --working-dir) working_dir="$2"; shift 2;;
+        --interval) interval="$2"; shift 2;;
+        --log-dir) log_dir="$2"; shift 2;;
+        --out) out_path="$2"; shift 2;;
+        -h|--help) usage; exit 0;;
+        *) echo "Unknown arg: $1" >&2; usage; exit 1;;
+    esac
+
+done
+
+if [[ -z "$label" || -z "$program" || -z "$working_dir" || -z "$out_path" ]]; then
+    echo "Missing required arguments" >&2
+    usage
+    exit 1
+fi
+
+job_name="${label##*.}"
+
+domain="launchd"
+if [[ "$label" =~ ^com\.user\.([^\.]+)\..+ ]]; then
+    domain="${BASH_REMATCH[1]}"
+fi
+
+if [[ -z "$log_dir" ]]; then
+    log_dir="/tmp/${domain}"
+fi
+
+stdout_path="${log_dir}/${job_name}.log"
+stderr_path="${log_dir}/${job_name}.err"
+
+mkdir -p "$log_dir"
+mkdir -p "$(dirname "$out_path")"
+
+template_path="$SCRIPT_DIR/../templates/job.plist.tmpl"
+
+if [[ ! -f "$template_path" ]]; then
+    echo "Template not found: $template_path" >&2
+    exit 1
+fi
+
+sed \
+  -e "s#{{LABEL}}#${label}#g" \
+  -e "s#{{PROGRAM}}#${program}#g" \
+  -e "s#{{START_INTERVAL}}#${interval}#g" \
+  -e "s#{{WORKING_DIRECTORY}}#${working_dir}#g" \
+  -e "s#{{STDOUT_PATH}}#${stdout_path}#g" \
+  -e "s#{{STDERR_PATH}}#${stderr_path}#g" \
+  "$template_path" > "$out_path"
+
+echo "Wrote plist: $out_path"

package/bin/launchd-reload

@@ -0,0 +1,25 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+prefix="${LAUNCHD_LABEL_PREFIX:-com.user.}"
+plist_glob="${1:-${LAUNCHD_PLIST_GLOB:-*/${prefix}*.plist}}"
+install_dir="${LAUNCHD_INSTALL_DIR:-$HOME/Library/LaunchAgents}"
+uid=$(id -u)
+
+shopt -s nullglob
+plists=( $plist_glob )
+
+if [[ ${#plists[@]} -eq 0 ]]; then
+    echo "No plists matched pattern: $plist_glob" >&2
+    exit 1
+fi
+
+for plist in "${plists[@]}"; do
+    name=$(basename "$plist")
+    label="${name%.plist}"
+    launchctl bootout gui/"$uid"/"$label" 2>/dev/null || true
+    ln -sf "$(pwd)/$plist" "$install_dir/$name"
+    launchctl bootstrap gui/"$uid" "$install_dir/$name" 2>/dev/null || true
+done
+
+echo "Reloaded ${#plists[@]} agent(s)"

package/bin/launchd-status

@@ -0,0 +1,9 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+_self="$0"
+[ -L "$_self" ] && { _t="$(readlink "$_self")"; [[ "$_t" != /* ]] && _t="$(dirname "$_self")/$_t"; _self="$_t"; }
+SCRIPT_DIR="$(cd "$(dirname "$_self")" && pwd)"
+
+prefix="${LAUNCHD_LABEL_PREFIX:-com.user.}"
+python3 "$SCRIPT_DIR/../plist-status.py" --prefix "$prefix"

package/bin/launchd-uninstall

@@ -0,0 +1,24 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+prefix="${LAUNCHD_LABEL_PREFIX:-com.user.}"
+plist_glob="${1:-${LAUNCHD_PLIST_GLOB:-*/${prefix}*.plist}}"
+install_dir="${LAUNCHD_INSTALL_DIR:-$HOME/Library/LaunchAgents}"
+uid=$(id -u)
+
+shopt -s nullglob
+plists=( $plist_glob )
+
+if [[ ${#plists[@]} -eq 0 ]]; then
+    echo "No plists matched pattern: $plist_glob" >&2
+    exit 1
+fi
+
+for plist in "${plists[@]}"; do
+    name=$(basename "$plist")
+    label="${name%.plist}"
+    launchctl bootout gui/"$uid"/"$label" 2>/dev/null || true
+    rm -f "$install_dir/$name"
+done
+
+echo "Uninstalled ${#plists[@]} agent(s)"

package/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "@albeorla/launchd-kit",
+  "version": "1.0.0",
+  "description": "Shared tooling for managing macOS LaunchAgents",
+  "bin": {
+    "launchd-install": "bin/launchd-install",
+    "launchd-log-dirs": "bin/launchd-log-dirs",
+    "launchd-logs": "bin/launchd-logs",
+    "launchd-logs-all": "bin/launchd-logs-all",
+    "launchd-logs-err": "bin/launchd-logs-err",
+    "launchd-new-job": "bin/launchd-new-job",
+    "launchd-reload": "bin/launchd-reload",
+    "launchd-status": "bin/launchd-status",
+    "launchd-uninstall": "bin/launchd-uninstall"
+  },
+  "files": ["bin", "templates", "plist-monitor", "plist-status.py"],
+  "publishConfig": { "access": "public" },
+  "license": "ISC"
+}

package/plist-monitor/.env.example

@@ -0,0 +1,3 @@
+DISCORD_WEBHOOK_PLIST_MONITOR=https://discord.com/api/webhooks/YOUR_ID/YOUR_TOKEN
+SEND_HEALTHY_NOTIFICATION=true
+LAUNCHD_PREFIX_FILTER=com.user.

package/plist-monitor/README.md

@@ -0,0 +1,11 @@
+# plist-monitor
+
+Discord webhook notifier for LaunchAgent health monitoring. Sends daily embeds showing failed jobs, today's runs, and upcoming schedule.
+
+**Schedule:** Daily at 8:00 AM  
+**Logs:** `/tmp/com.user.admin.plist-monitor.{log,err}`  
+**Env:** `.env` (see `.env.example` for template). You can override the env path with `PLIST_MONITOR_ENV`.
+
+Template plist: `../templates/plist-monitor.plist.tmpl`
+
+Note: `com.user.admin.plist-monitor.plist` is an admin-specific example. Copy and edit the label, paths, and log locations for each repo that uses it.

package/plist-monitor/plist-monitor.py

@@ -0,0 +1,514 @@
+#!/usr/bin/env python3
+"""
+Plist Monitor - Discord webhook for LaunchAgent monitoring.
+
+Usage:
+    ./plist-monitor.py                 # Send if healthy notification enabled
+    ./plist-monitor.py --force         # Always send notification
+
+Reads configuration from .env file in the same directory.
+"""
+
+import json
+import os
+import subprocess
+import sys
+from dataclasses import dataclass
+from datetime import datetime, timedelta
+from pathlib import Path
+
+# pip install discord-webhook python-dotenv
+from discord_webhook import DiscordWebhook, DiscordEmbed
+from dotenv import load_dotenv
+
+# Load .env from a specific path if provided, otherwise from the script directory
+_script_dir = Path(__file__).parent
+_env_path = Path(os.environ["PLIST_MONITOR_ENV"]) if os.environ.get("PLIST_MONITOR_ENV") else (_script_dir / ".env")
+load_dotenv(_env_path)
+
+# Colors (decimal format for Discord)
+COLOR_SUCCESS = 0x2ECC71  # Green
+COLOR_ERROR = 0xE74C3C    # Red
+COLOR_INFO = 0x3498DB     # Blue
+
+# Default prefix filter (can be overridden by LAUNCHD_PREFIX_FILTER env var)
+DEFAULT_PREFIXES = "com.user."
+
+# Exit code explanations
+EXIT_CODE_HINTS = {
+    0: "Success",
+    1: "General error",
+    2: "Misuse of shell command",
+    126: "Permission denied (chmod +x?)",
+    127: "Command not found",
+    128: "Invalid exit argument",
+    130: "Terminated (SIGINT)",
+    137: "Killed (OOM or SIGKILL)",
+    139: "Segfault (SIGSEGV)",
+    143: "Terminated (SIGTERM)",
+}
+
+
+def get_exit_hint(code: str) -> str:
+    """Return human-readable hint for exit code."""
+    try:
+        c = int(code)
+        if c in EXIT_CODE_HINTS:
+            return EXIT_CODE_HINTS[c]
+        if c > 128:
+            return f"Signal {c - 128}"
+        if c < 0:
+            return f"Signal {abs(c)}"
+        return "Unknown"
+    except ValueError:
+        return ""
+
+
+@dataclass
+class Job:
+    """Represents a LaunchAgent job."""
+    label: str
+    domain: str
+    name: str
+    exit_code: str
+    last_run_epoch: int
+    next_run_epoch: int
+    schedule: str
+    interval: int = 0  # StartInterval seconds, 0 if calendar-based
+
+    @property
+    def is_healthy(self) -> bool:
+        return self.exit_code in ("0", "-")
+
+    @property
+    def display_name(self) -> str:
+        return f"{self.domain}.{self.name}"
+
+    @property
+    def cadence(self) -> str:
+        """Schedule cadence without time prefix (e.g., 'daily' from '6am daily')."""
+        for c in ("daily", "weekly", "monthly"):
+            if c in self.schedule:
+                return c
+        return self.schedule
+
+
+def get_jobs(prefixes: list[str] | None = None) -> list[Job]:
+    """Get LaunchAgent jobs matching any of the prefixes."""
+    if prefixes is None:
+        prefix_str = os.environ.get("LAUNCHD_PREFIX_FILTER", DEFAULT_PREFIXES)
+        prefixes = [p.strip() for p in prefix_str.split(",") if p.strip()]
+
+    result = subprocess.run(["launchctl", "list"], capture_output=True, text=True)
+    home = Path.home()
+    now = datetime.now()
+    jobs = []
+
+    for line in result.stdout.strip().split("\n")[1:]:
+        parts = line.split("\t")
+        if len(parts) < 3:
+            continue
+
+        _, exit_code, label = parts
+        # Check if label matches any prefix, skip plist-monitor itself
+        if not any(label.startswith(p) for p in prefixes) or "plist-monitor" in label:
+            continue
+
+        # Parse domain.name from label
+        short = label.removeprefix("com.user.")
+        domain, name = short.split(".", 1) if "." in short else ("misc", short)
+
+        # Get schedule and timing info
+        plist = home / f"Library/LaunchAgents/{label}.plist"
+        schedule, next_epoch, interval = parse_schedule(plist, now)
+        last_run = get_last_run(plist, label, home)
+
+        jobs.append(Job(
+            label=label,
+            domain=domain,
+            name=name,
+            exit_code=exit_code,
+            last_run_epoch=last_run,
+            next_run_epoch=next_epoch,
+            schedule=schedule,
+            interval=interval,
+        ))
+
+    return jobs
+
+
+def parse_schedule(plist: Path, now: datetime) -> tuple[str, int, int]:
+    """Parse schedule from plist, return (schedule_str, next_run_epoch, interval_secs)."""
+    if not plist.exists():
+        return "unknown", 0, 0
+
+    try:
+        result = subprocess.run(
+            ["plutil", "-convert", "json", "-o", "-", str(plist)],
+            capture_output=True, text=True
+        )
+        data = json.loads(result.stdout)
+    except (json.JSONDecodeError, subprocess.SubprocessError):
+        return "unknown", 0, 0
+
+    start_interval = data.get("StartInterval")
+    if start_interval:
+        if start_interval <= 60:
+            schedule = f"every {start_interval}s"
+        elif start_interval < 3600:
+            schedule = f"every {start_interval // 60}m"
+        elif start_interval == 3600:
+            schedule = "hourly"
+        else:
+            schedule = f"every {start_interval // 3600}h"
+        next_epoch = int(now.timestamp()) + start_interval
+        return schedule, next_epoch, start_interval
+
+    interval = data.get("StartCalendarInterval", {})
+    if isinstance(interval, list):
+        interval = interval[0] if interval else {}
+
+    hour = interval.get("Hour", 0)
+    minute = interval.get("Minute", 0)
+    day = interval.get("Day")
+    weekday = interval.get("Weekday")
+
+    # Format schedule string
+    if hour is not None:
+        h = hour if hour <= 12 else hour - 12
+        if hour == 0:
+            h = 12
+        ampm = "am" if hour < 12 else "pm"
+        time_str = f"{h}{ampm}"
+    else:
+        time_str = ""
+
+    if day is not None:
+        suffix = {1: "st", 2: "nd", 3: "rd", 21: "st", 22: "nd", 23: "rd", 31: "st"}.get(day, "th")
+        schedule = f"{time_str} {day}{suffix} monthly"
+    elif weekday is not None:
+        days = ["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"]
+        schedule = f"{time_str} {days[weekday]}"
+    else:
+        schedule = f"{time_str} daily"
+
+    # Calculate next run as an absolute target time
+    target = now.replace(hour=hour or 0, minute=minute or 0, second=0, microsecond=0)
+
+    if weekday is not None:
+        days_ahead = (weekday - now.weekday()) % 7
+        if days_ahead == 0 and target <= now:
+            days_ahead = 7
+        target += timedelta(days=days_ahead)
+    elif day is not None:
+        if now.day > day or (now.day == day and target <= now):
+            month = now.month + 1 if now.month < 12 else 1
+            year = now.year if now.month < 12 else now.year + 1
+            target = target.replace(year=year, month=month, day=day)
+        else:
+            target = target.replace(day=day)
+    else:
+        if target <= now:
+            target += timedelta(days=1)
+
+    return schedule.strip(), int(target.timestamp()), 0
+
+
+def get_last_run(plist: Path, label: str, home: Path) -> int:
+    """Get last run timestamp from log file mtime (uses most recent of stdout/stderr)."""
+    candidates = []
+
+    # Add paths from plist (check both stdout and stderr)
+    if plist.exists():
+        try:
+            result = subprocess.run(
+                ["plutil", "-convert", "json", "-o", "-", str(plist)],
+                capture_output=True, text=True
+            )
+            data = json.loads(result.stdout)
+            for key in ("StandardOutPath", "StandardErrorPath"):
+                if path := data.get(key):
+                    candidates.append(Path(path))
+        except (json.JSONDecodeError, subprocess.SubprocessError):
+            pass
+
+    # Fallback: check /tmp/ with label-based naming
+    candidates.append(Path(f"/tmp/{label}.log"))
+    candidates.append(Path(f"/tmp/{label}.err"))
+
+    # Find the most recent mtime across all existing candidates
+    latest_mtime = 0
+    for path in candidates:
+        if path.exists():
+            mtime = int(path.stat().st_mtime)
+            if mtime > latest_mtime:
+                latest_mtime = mtime
+    return latest_mtime
+
+
+def format_time(epoch: int) -> str:
+    """Format epoch as local time string like '6:15 AM'."""
+    if epoch <= 0:
+        return "?"
+    return datetime.fromtimestamp(epoch).strftime("%-I:%M %p")
+
+
+def estimate_runs_today(interval: int) -> int:
+    """Estimate how many times an interval-based job ran since midnight."""
+    if interval <= 0:
+        return 0
+    now = datetime.now()
+    midnight = now.replace(hour=0, minute=0, second=0, microsecond=0)
+    secs = (now - midnight).total_seconds()
+    return max(0, int(secs / interval))
+
+
+def static_relative(secs: int) -> str:
+    """Format seconds-from-now as static human-readable relative text."""
+    if secs < 0:
+        return "now"
+    if secs < 3600:
+        return f"{secs // 60}m"
+    if secs < 86400:
+        h = secs // 3600
+        return f"{h}h"
+    days = secs // 86400
+    if days == 1:
+        return "1d"
+    if days < 14:
+        return f"{days}d"
+    if days < 60:
+        weeks = days // 7
+        return f"{weeks}w"
+    months = days // 30
+    return f"~{months}mo"
+
+
+def get_midnight_epoch() -> int:
+    """Get epoch timestamp for local midnight today."""
+    now = datetime.now()
+    midnight = now.replace(hour=0, minute=0, second=0, microsecond=0)
+    return int(midnight.timestamp())
+
+
+def build_attention_embed(failed_jobs: list[Job], total_jobs: int) -> DiscordEmbed | None:
+    """Build embed for jobs needing attention. Returns None if all healthy."""
+    if not failed_jobs:
+        return None
+
+    embed = DiscordEmbed(
+        title=f"Needs Attention ({len(failed_jobs)}/{total_jobs})",
+        color=COLOR_ERROR
+    )
+    embed.set_footer(text=os.uname().nodename)
+    embed.set_timestamp()
+
+    sorted_jobs = sorted(failed_jobs, key=lambda j: -j.last_run_epoch)[:10]
+    w = max(len(j.display_name) for j in sorted_jobs)
+
+    lines = []
+    for job in sorted_jobs:
+        name = job.display_name.ljust(w)
+        hint = get_exit_hint(job.exit_code)
+        exit_info = f"exit {job.exit_code} {hint}" if hint else f"exit {job.exit_code}"
+        retry = format_time(job.next_run_epoch) if job.next_run_epoch else "?"
+        lines.append(f"✗ {name}  {exit_info}")
+        lines.append(f"  {''.ljust(w)}  retry {retry} · {job.schedule}")
+
+    overflow = ""
+    if len(failed_jobs) > 10:
+        overflow = f"\n*+{len(failed_jobs) - 10} more*"
+
+    embed.description = f"```\n{chr(10).join(lines)}\n```{overflow}"
+    return embed
+
+
+def build_ran_today_embed(jobs: list[Job]) -> DiscordEmbed | None:
+    """Build embed for jobs that ran today (since local midnight)."""
+    midnight = get_midnight_epoch()
+
+    # Include calendar jobs with recent logs AND interval jobs that are healthy (running)
+    today_jobs = [
+        j for j in jobs
+        if j.last_run_epoch >= midnight or (j.interval and j.is_healthy)
+    ]
+
+    if not today_jobs:
+        return None
+
+    # Sort: interval jobs (by estimated runs desc), then calendar jobs (by last run desc)
+    today_jobs.sort(key=lambda j: (0 if j.interval else 1, -j.last_run_epoch))
+
+    display = today_jobs[:15]
+    w = max(len(j.display_name) for j in display)
+
+    embed = DiscordEmbed(title=f"Ran Today ({len(today_jobs)})", color=COLOR_SUCCESS)
+    embed.set_footer(text=os.uname().nodename)
+    embed.set_timestamp()
+
+    lines = []
+    for job in display:
+        status = "✓" if job.is_healthy else "✗"
+        name = job.display_name.ljust(w)
+        if job.interval:
+            runs = estimate_runs_today(job.interval)
+            lines.append(f"{status} {name}  ×{runs:<4} {job.cadence}")
+        else:
+            time_str = format_time(job.last_run_epoch)
+            lines.append(f"{status} {name}  {time_str:>8}  {job.cadence}")
+
+    overflow = ""
+    if len(today_jobs) > 15:
+        overflow = f"\n*+{len(today_jobs) - 15} more*"
+
+    embed.description = f"```\n{chr(10).join(lines)}\n```{overflow}"
+    return embed
+
+
+def build_coming_up_embed(jobs: list[Job], now_epoch: int) -> DiscordEmbed | None:
+    """Build embed for jobs coming up within 24h."""
+    window_secs = 24 * 3600
+
+    upcoming = [
+        j for j in jobs
+        if j.next_run_epoch > now_epoch and (j.next_run_epoch - now_epoch) <= window_secs
+    ]
+
+    if not upcoming:
+        return None
+
+    upcoming.sort(key=lambda j: j.next_run_epoch)
+
+    display = upcoming[:10]
+    w = max(len(j.display_name) for j in display)
+
+    embed = DiscordEmbed(title=f"Up Next ({len(upcoming)})", color=COLOR_INFO)
+    embed.set_footer(text=os.uname().nodename)
+    embed.set_timestamp()
+
+    lines = []
+    for i, job in enumerate(display):
+        marker = "▸" if i == 0 else "·"
+        name = job.display_name.ljust(w)
+        time_str = format_time(job.next_run_epoch)
+        eta = static_relative(job.next_run_epoch - now_epoch)
+        lines.append(f"{marker} {name}  {time_str:>8}  {eta:>4}")
+
+    overflow = ""
+    if len(upcoming) > 10:
+        overflow = f"\n*+{len(upcoming) - 10} more*"
+
+    embed.description = f"```\n{chr(10).join(lines)}\n```{overflow}"
+    return embed
+
+
+def build_later_embed(jobs: list[Job], now_epoch: int) -> DiscordEmbed | None:
+    """Build embed for jobs scheduled beyond 24h."""
+    soon_secs = 24 * 3600
+
+    later = [
+        j for j in jobs
+        if j.next_run_epoch > now_epoch and (j.next_run_epoch - now_epoch) > soon_secs
+    ]
+
+    if not later:
+        return None
+
+    later.sort(key=lambda j: j.next_run_epoch)
+
+    display = later[:10]
+    w = max(len(j.display_name) for j in display)
+
+    embed = DiscordEmbed(title=f"Later ({len(later)})", color=COLOR_INFO)
+    embed.set_footer(text=os.uname().nodename)
+    embed.set_timestamp()
+
+    lines = []
+    for job in display:
+        name = job.display_name.ljust(w)
+        eta = static_relative(job.next_run_epoch - now_epoch)
+        lines.append(f"· {name}  in {eta:>4}  {job.schedule}")
+
+    overflow = ""
+    if len(later) > 10:
+        overflow = f"\n*+{len(later) - 10} more*"
+
+    embed.description = f"```\n{chr(10).join(lines)}\n```{overflow}"
+    return embed
+
+
+def build_embeds(jobs: list[Job]) -> list[DiscordEmbed]:
+    """Build Discord embeds - separate concerns for clarity."""
+    now_epoch = int(datetime.now().timestamp())
+    failed = [j for j in jobs if not j.is_healthy]
+
+    embeds = []
+
+    if attention := build_attention_embed(failed, len(jobs)):
+        embeds.append(attention)
+
+    if ran_today := build_ran_today_embed(jobs):
+        embeds.append(ran_today)
+
+    if coming_up := build_coming_up_embed(jobs, now_epoch):
+        embeds.append(coming_up)
+
+    if later := build_later_embed(jobs, now_epoch):
+        embeds.append(later)
+
+    if not embeds:
+        embed = DiscordEmbed(title="🟢 All Quiet", color=COLOR_SUCCESS)
+        embed.description = f"**{len(jobs)}** services healthy, no recent activity"
+        embed.set_footer(text=os.uname().nodename)
+        embed.set_timestamp()
+        embeds.append(embed)
+
+    return embeds
+
+
+def send_notification(webhook_url: str, jobs: list[Job]) -> bool:
+    """Send Discord notification."""
+    webhook = DiscordWebhook(url=webhook_url)
+
+    for embed in build_embeds(jobs):
+        webhook.add_embed(embed)
+
+    response = webhook.execute()
+
+    if response.ok:
+        print(f"[INFO] Discord notification sent (HTTP {response.status_code})")
+        return True
+    else:
+        print(f"[ERROR] Discord failed: {response.status_code} {response.text}", file=sys.stderr)
+        return False
+
+
+def main():
+    webhook_url = os.environ.get("DISCORD_WEBHOOK_PLIST_MONITOR")
+    if not webhook_url:
+        print("[ERROR] DISCORD_WEBHOOK_PLIST_MONITOR not set", file=sys.stderr)
+        print("[ERROR] Create .env file from .env.example in this directory", file=sys.stderr)
+        sys.exit(1)
+
+    send_healthy = os.environ.get("SEND_HEALTHY_NOTIFICATION", "").lower() == "true"
+    force = "--force" in sys.argv
+
+    print("[INFO] Starting job status check...")
+
+    jobs = get_jobs()
+    failed = [j for j in jobs if not j.is_healthy]
+
+    print(f"[INFO] Found {len(jobs)} jobs, {len(failed)} failed")
+
+    if failed or send_healthy or force:
+        if send_notification(webhook_url, jobs):
+            sys.exit(0)
+        else:
+            sys.exit(2)
+    else:
+        print("[INFO] All healthy, skipping notification (set SEND_HEALTHY_NOTIFICATION=true to enable)")
+        sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

package/plist-status.py

@@ -0,0 +1,186 @@
+#!/usr/bin/env python3
+"""
+Plist Status Dashboard - Terminal display for all com.user.* LaunchAgents.
+
+Usage:
+    python3 plist-status.py              # Show all com.user.* agents
+    python3 plist-status.py --prefix X   # Override prefix filter
+"""
+
+import json
+import os
+import subprocess
+import sys
+from datetime import datetime, timedelta
+from pathlib import Path
+
+
+def parse_plist_json(plist_path: Path) -> dict:
+    """Convert plist to JSON dict."""
+    try:
+        result = subprocess.run(
+            ["plutil", "-convert", "json", "-o", "-", str(plist_path)],
+            capture_output=True, text=True
+        )
+        return json.loads(result.stdout)
+    except (json.JSONDecodeError, subprocess.SubprocessError):
+        return {}
+
+
+def get_next_run(data: dict, now: datetime) -> str:
+    """Calculate next run time from plist schedule."""
+    interval = data.get("StartCalendarInterval", {})
+    start_interval = data.get("StartInterval")
+
+    if start_interval:
+        return f"every {start_interval}s"
+
+    if isinstance(interval, list):
+        interval = interval[0] if interval else {}
+
+    if not interval:
+        return "manual"
+
+    hour = interval.get("Hour", 0)
+    minute = interval.get("Minute", 0)
+    day = interval.get("Day")
+    weekday = interval.get("Weekday")
+
+    target = now.replace(hour=hour, minute=minute, second=0, microsecond=0)
+
+    if weekday is not None:
+        days_ahead = (weekday - now.weekday()) % 7
+        if days_ahead == 0 and target <= now:
+            days_ahead = 7
+        target += timedelta(days=days_ahead)
+    elif day is not None:
+        if now.day > day or (now.day == day and target <= now):
+            month = now.month + 1 if now.month < 12 else 1
+            year = now.year if now.month < 12 else now.year + 1
+            target = target.replace(year=year, month=month, day=day)
+        else:
+            target = target.replace(day=day)
+    else:
+        if target <= now:
+            target += timedelta(days=1)
+
+    delta = target - now
+    if delta.days > 0:
+        return f"{delta.days}d {delta.seconds // 3600}h"
+    elif delta.seconds > 3600:
+        return f"{delta.seconds // 3600}h {(delta.seconds % 3600) // 60}m"
+    else:
+        return f"{delta.seconds // 60}m"
+
+
+def get_log_mtime(data: dict, label: str) -> str:
+    """Get last run time from log file mtime."""
+    candidates = []
+    for key in ("StandardOutPath", "StandardErrorPath"):
+        if path := data.get(key):
+            candidates.append(Path(path))
+    candidates.append(Path(f"/tmp/{label}.log"))
+
+    latest = 0
+    for p in candidates:
+        if p.exists():
+            mtime = int(p.stat().st_mtime)
+            if mtime > latest:
+                latest = mtime
+
+    if latest == 0:
+        return "never"
+
+    dt = datetime.fromtimestamp(latest)
+    now = datetime.now()
+    delta = now - dt
+
+    if delta.days == 0:
+        return dt.strftime("%H:%M today")
+    elif delta.days == 1:
+        return dt.strftime("%H:%M yesterday")
+    elif delta.days < 7:
+        return dt.strftime("%a %H:%M")
+    else:
+        return dt.strftime("%Y-%m-%d")
+
+
+def get_log_path(data: dict) -> str:
+    """Get log path from plist."""
+    path = data.get("StandardOutPath", "")
+    if path:
+        return path
+    return "-"
+
+
+def main():
+    prefix = "com.user."
+    if "--prefix" in sys.argv:
+        idx = sys.argv.index("--prefix")
+        if idx + 1 < len(sys.argv):
+            prefix = sys.argv[idx + 1]
+
+    # Get loaded agents
+    result = subprocess.run(["launchctl", "list"], capture_output=True, text=True)
+    loaded = {}
+    for line in result.stdout.strip().split("\n")[1:]:
+        parts = line.split("\t")
+        if len(parts) >= 3:
+            _, exit_code, label = parts
+            if label.startswith(prefix):
+                loaded[label] = exit_code
+
+    # Scan plists in ~/Library/LaunchAgents/
+    agents_dir = Path.home() / "Library/LaunchAgents"
+    plists = sorted(agents_dir.glob(f"{prefix}*.plist"))
+
+    now = datetime.now()
+    rows = []
+
+    for plist in plists:
+        label = plist.stem
+        data = parse_plist_json(plist)
+        exit_code = loaded.get(label, "unloaded")
+        is_loaded = label in loaded
+
+        status = "✓" if exit_code == "0" else ("─" if exit_code == "-" else f"✗ {exit_code}")
+        if not is_loaded:
+            status = "○ unloaded"
+
+        last_run = get_log_mtime(data, label)
+        next_run = get_next_run(data, now) if is_loaded else "-"
+        log_path = get_log_path(data)
+
+        # Short label: strip prefix
+        short = label.removeprefix("com.user.")
+
+        rows.append((short, status, last_run, next_run, log_path))
+
+    if not rows:
+        print(f"No agents found matching {prefix}*")
+        return
+
+    # Calculate column widths
+    headers = ("AGENT", "STATUS", "LAST RUN", "NEXT RUN", "LOG")
+    widths = [max(len(h), max(len(r[i]) for r in rows)) for i, h in enumerate(headers)]
+
+    # Print header
+    header_line = "  ".join(h.ljust(w) for h, w in zip(headers, widths))
+    print(f"\n{header_line}")
+    print("─" * len(header_line))
+
+    # Print rows
+    for row in rows:
+        print("  ".join(val.ljust(w) for val, w in zip(row, widths)))
+
+    # Summary
+    total = len(rows)
+    healthy = sum(1 for r in rows if r[1].startswith("✓") or r[1].startswith("─"))
+    failed = sum(1 for r in rows if r[1].startswith("✗"))
+    unloaded = sum(1 for r in rows if "unloaded" in r[1])
+
+    print(f"\n{total} agents: {healthy} healthy, {failed} failed, {unloaded} unloaded\n")
+
+
+if __name__ == "__main__":
+    main()

package/templates/job.plist.tmpl

@@ -0,0 +1,25 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>Label</key>
+    <string>{{LABEL}}</string>
+
+    <key>ProgramArguments</key>
+    <array>
+        <string>{{PROGRAM}}</string>
+    </array>
+
+    <key>StartInterval</key>
+    <integer>{{START_INTERVAL}}</integer>
+
+    <key>WorkingDirectory</key>
+    <string>{{WORKING_DIRECTORY}}</string>
+
+    <key>StandardOutPath</key>
+    <string>{{STDOUT_PATH}}</string>
+
+    <key>StandardErrorPath</key>
+    <string>{{STDERR_PATH}}</string>
+</dict>
+</plist>

package/templates/plist-monitor.plist.tmpl

@@ -0,0 +1,42 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>Label</key>
+    <string>{{LABEL}}</string>
+
+    <key>ProgramArguments</key>
+    <array>
+        <string>{{PYTHON}}</string>
+        <string>{{SCRIPT}}</string>
+    </array>
+
+    <key>RunAtLoad</key>
+    <false/>
+
+    <key>StartCalendarInterval</key>
+    <dict>
+        <key>Hour</key>
+        <integer>{{HOUR}}</integer>
+        <key>Minute</key>
+        <integer>{{MINUTE}}</integer>
+    </dict>
+
+    <key>WorkingDirectory</key>
+    <string>{{WORKING_DIRECTORY}}</string>
+
+    <key>EnvironmentVariables</key>
+    <dict>
+        <key>PLIST_MONITOR_ENV</key>
+        <string>{{ENV_PATH}}</string>
+        <key>LAUNCHD_PREFIX_FILTER</key>
+        <string>{{PREFIX_FILTER}}</string>
+    </dict>
+
+    <key>StandardOutPath</key>
+    <string>{{STDOUT_PATH}}</string>
+
+    <key>StandardErrorPath</key>
+    <string>{{STDERR_PATH}}</string>
+</dict>
+</plist>