coding-os 0.3.2__py3-none-any.whl

cli/config_composer.py

@@ -0,0 +1,349 @@
+"""Compose per-stack `.coding-os/` configs at `cos init`.
+
+Base defaults are deep-merged with each installed stack's overlay, data-driven
+(iterates the `templates` list — Rule 11) and multi-stack-correct. Idempotent:
+never clobbers an existing target. SSOT: docs/engineering/config-composition.md.
+"""
+
+from __future__ import annotations
+
+import copy
+import json
+from pathlib import Path
+from typing import Any
+
+import click
+import yaml
+
+# Per-file merge spec: top-level key → strategy. Strategies:
+#   "union_by:<key>"  list of dicts, union by <key> (later wins on collision)
+#   "union_list"      list of scalars, order-preserving dedupe
+#   "dict_merge"      recursive: dicts merge, nested lists union, scalars override
+#   "override"        later value wins wholesale
+# A key present in an overlay but absent from the spec defaults to "override".
+RAG_SPEC: dict[str, str] = {
+    "sources": "union_by:path",
+    "exclude": "union_list",
+    "graph": "dict_merge",
+}
+SCRUMBAN_SPEC: dict[str, str] = {
+    "swimlanes": "union_by:id",
+    "wip_limits": "dict_merge",
+    "workflow_policy": "dict_merge",
+    "label_families": "union_by:name",
+}
+DOMAIN_SPEC: dict[str, str] = {
+    "refs_by_tag": "dict_merge",
+    "domain_map": "dict_merge",
+    "playbook_map": "dict_merge",
+    "default_refs": "override",
+    "default_domain": "override",
+    "default_playbook": "override",
+}
+
+# (filename, spec, format) for each composed config.
+_COMPOSED: tuple[tuple[str, dict[str, str], str], ...] = (
+    ("rag-config.yaml", RAG_SPEC, "yaml"),
+    ("scrumban-config.yaml", SCRUMBAN_SPEC, "yaml"),
+    ("domain-config.json", DOMAIN_SPEC, "json"),
+)
+
+# Filenames excluded from `_overlay_scaffold` so they don't shadow the composed
+# output (first-writer-wins). Kept here as the single source.
+COMPOSED_FILENAMES: frozenset[str] = frozenset(name for name, _, _ in _COMPOSED)
+
+
+def _union_list(base: list[Any], overlay: list[Any]) -> list[Any]:
+    out: list[Any] = []
+    seen: set[str] = set()
+    for item in [*base, *overlay]:
+        marker = item if isinstance(item, str) else json.dumps(item, sort_keys=True)
+        if marker in seen:
+            continue
+        seen.add(marker)
+        out.append(item)
+    return out
+
+
+class _ConflictLog:
+    """Same-key/different-value collisions, reported instead of silently
+    resolved (config-composition.md § Merge preview + conflict surfacing).
+    Later-wins stays the resolution rule — this only makes it visible."""
+
+    def __init__(self) -> None:
+        self.entries: list[str] = []
+        self.source = "?"
+
+    def record(self, path: str, old: Any, new: Any) -> None:
+        old_s, new_s = json.dumps(old, sort_keys=True), json.dumps(new, sort_keys=True)
+        self.entries.append(f"{path}: {old_s} → {new_s} (winner: {self.source})")
+
+
+def _union_by_key(
+    base: list[Any], overlay: list[Any], key: str, log: _ConflictLog, path: str
+) -> list[Any]:
+    out = [copy.deepcopy(item) for item in base]
+    index = {item.get(key): i for i, item in enumerate(out) if isinstance(item, dict)}
+    for item in overlay:
+        if isinstance(item, dict) and item.get(key) in index:
+            slot = index[item[key]]
+            if out[slot] != item:
+                log.record(f"{path}[{item[key]}]", out[slot], item)
+            out[slot] = copy.deepcopy(item)  # later wins on collision
+        else:
+            if isinstance(item, dict):
+                index[item.get(key)] = len(out)
+            out.append(copy.deepcopy(item))
+    return out
+
+
+def _deep_merge(base: Any, overlay: Any, log: _ConflictLog, path: str) -> Any:
+    if isinstance(base, dict) and isinstance(overlay, dict):
+        out = copy.deepcopy(base)
+        for k, v in overlay.items():
+            out[k] = _deep_merge(out[k], v, log, f"{path}.{k}") if k in out else copy.deepcopy(v)
+        return out
+    if isinstance(base, list) and isinstance(overlay, list):
+        return _union_list(base, overlay)
+    if base is not None and base != overlay:
+        log.record(path, base, overlay)
+    return copy.deepcopy(overlay)
+
+
+def _merge_value(
+    base_val: Any, overlay_val: Any, strategy: str, log: _ConflictLog, path: str
+) -> Any:
+    if overlay_val is None:
+        return base_val
+    if strategy == "union_list":
+        return _union_list(base_val or [], overlay_val or [])
+    if strategy == "override":
+        if base_val is not None and base_val != overlay_val:
+            log.record(path, base_val, overlay_val)
+        return copy.deepcopy(overlay_val)
+    if strategy == "dict_merge":
+        return _deep_merge(base_val or {}, overlay_val, log, path)
+    if strategy.startswith("union_by:"):
+        return _union_by_key(
+            base_val or [], overlay_val or [], strategy.split(":", 1)[1], log, path
+        )
+    raise ValueError(f"unknown merge strategy: {strategy!r}")
+
+
+def _stack_scaffold_dir(stack_id: str, templates_dir: Path) -> Path:
+    """Resolve a stack's scaffold dir — bundled first, then a community overlay
+    ($COS_USER_TEMPLATES_DIR, TASK-479). Bundled stacks resolve byte-identically; a
+    nonexistent path is returned unchanged so _load() returns None gracefully."""
+    bundled = templates_dir / stack_id / "scaffold"
+    if bundled.is_dir():
+        return bundled
+    from cli._resources import overlay_template_dirs
+
+    for root in overlay_template_dirs():
+        candidate = root / stack_id / "scaffold"
+        if candidate.is_dir():
+            return candidate
+    return bundled
+
+
+def compose(
+    base: dict[str, Any],
+    overlays: list[dict[str, Any]],
+    spec: dict[str, str],
+    *,
+    overlay_names: list[str] | None = None,
+    conflicts: list[str] | None = None,
+) -> dict[str, Any]:
+    """Deep-merge `base` with each overlay in order per the strategy `spec`.
+
+    When `conflicts` is passed, every same-key/different-value collision is
+    appended as "<key>[id]: old → new (winner: <overlay_name>)". A stack's
+    delta overriding the BASE default is the designed contract, not a
+    conflict — only overlay-vs-overlay collisions (second overlay onward)
+    are recorded, so a single-stack init never reports any.
+    """
+    log = _ConflictLog()
+    result = copy.deepcopy(base)
+    for position, overlay in enumerate(overlays):
+        if not isinstance(overlay, dict):
+            continue
+        log.source = (
+            overlay_names[position]
+            if overlay_names and position < len(overlay_names)
+            else f"overlay[{position}]"
+        )
+        record_this_pass = conflicts is not None and position > 0
+        for key in [*spec, *(k for k in overlay if k not in spec)]:
+            if key not in overlay:
+                continue
+            before = len(log.entries)
+            result[key] = _merge_value(
+                result.get(key), overlay[key], spec.get(key, "override"), log, key
+            )
+            if not record_this_pass:
+                del log.entries[before:]
+    if conflicts is not None:
+        conflicts.extend(log.entries)
+    return result
+
+
+def _load(path: Path, fmt: str) -> dict[str, Any] | None:
+    if not path.is_file():
+        return None
+    text = path.read_text(encoding="utf-8")
+    try:
+        data = json.loads(text) if fmt == "json" else yaml.safe_load(text)
+    except (yaml.YAMLError, json.JSONDecodeError) as exc:
+        raise click.ClickException(f"{path} is not valid {fmt.upper()}: {exc}") from exc
+    return data if isinstance(data, dict) else None
+
+
+_YAML_HEADER = (
+    "# GENERATED by `cos init` — composed from base defaults + every installed\n"
+    "# stack. Edit freely: init/update never clobbers an existing file. Schema +\n"
+    "# merge rules: docs/engineering/config-composition.md\n\n"
+)
+
+
+def _dump(data: dict[str, Any], fmt: str) -> str:
+    if fmt == "json":
+        return json.dumps(data, indent=2, ensure_ascii=False) + "\n"
+    body = yaml.safe_dump(data, sort_keys=False, default_flow_style=False, allow_unicode=True)
+    return _YAML_HEADER + body
+
+
+def _compose_one(
+    filename: str,
+    spec: dict[str, str],
+    fmt: str,
+    templates: list[str],
+    templates_dir: Path,
+    conflicts: list[str] | None,
+) -> dict[str, Any] | None:
+    base = _load(templates_dir / "_base" / "scaffold" / ".coding-os" / filename, fmt)
+    overlays: list[dict[str, Any]] = []
+    overlay_names: list[str] = []
+    for stack_id in templates:
+        overlay = _load(_stack_scaffold_dir(stack_id, templates_dir) / ".coding-os" / filename, fmt)
+        if overlay is not None:
+            overlays.append(overlay)
+            overlay_names.append(stack_id)
+    if base is None and not overlays:
+        return None
+    file_conflicts: list[str] = []
+    merged = compose(
+        base or {}, overlays, spec, overlay_names=overlay_names, conflicts=file_conflicts
+    )
+    if conflicts is not None:
+        conflicts.extend(f"{filename}: {entry}" for entry in file_conflicts)
+    return merged
+
+
+def compose_coding_os_configs(
+    project: Path,
+    state: Path,
+    templates: list[str],
+    *,
+    templates_dir: Path,
+    conflicts: list[str] | None = None,
+) -> list[str]:
+    """Compose `.coding-os/` configs from base + installed stacks. Returns written names."""
+    written: list[str] = []
+    for filename, spec, fmt in _COMPOSED:
+        target = state / filename
+        if target.exists():
+            continue  # idempotent — never clobber a user / prior-run file
+        merged = _compose_one(filename, spec, fmt, templates, templates_dir, conflicts)
+        if merged is None:
+            continue
+        target.parent.mkdir(parents=True, exist_ok=True)
+        target.write_text(_dump(merged, fmt), encoding="utf-8")
+        written.append(filename)
+    return written
+
+
+def preview_coding_os_configs(
+    templates: list[str],
+    *,
+    templates_dir: Path,
+) -> tuple[dict[str, dict[str, Any]], list[str]]:
+    """Compute the composed configs WITHOUT writing — `cos init --dry-config`.
+
+    Returns ({filename: merged}, conflicts). The wizard's merge-preview source."""
+    merged_by_file: dict[str, dict[str, Any]] = {}
+    conflicts: list[str] = []
+    for filename, spec, fmt in _COMPOSED:
+        merged = _compose_one(filename, spec, fmt, templates, templates_dir, conflicts)
+        if merged is not None:
+            merged_by_file[filename] = merged
+    return merged_by_file, conflicts
+
+
+def recompose_for_added_stack(
+    project: Path,
+    state: Path,
+    stack_id: str,
+    *,
+    templates_dir: Path,
+) -> list[str]:
+    """Merge a newly-added stack's `.coding-os/` overlay onto the existing configs.
+
+    Merges onto the CURRENT composed file (not a fresh base) so user edits and
+    prior stacks are preserved; re-adding the same stack is a no-op (union
+    dedupes). Used by `cos add-stack`. SSOT: docs/engineering/config-composition.md.
+    """
+    written: list[str] = []
+    base_dir = templates_dir / "_base" / "scaffold" / ".coding-os"
+    for filename, spec, fmt in _COMPOSED:
+        overlay = _load(_stack_scaffold_dir(stack_id, templates_dir) / ".coding-os" / filename, fmt)
+        if overlay is None:
+            continue
+        target = state / filename
+        existing = _load(target, fmt)
+        base = existing if existing is not None else (_load(base_dir / filename, fmt) or {})
+        merged = compose(base, [overlay], spec)
+        target.parent.mkdir(parents=True, exist_ok=True)
+        target.write_text(_dump(merged, fmt), encoding="utf-8")
+        written.append(filename)
+    return written
+
+
+def recompose_for_removed_stack(
+    project: Path,
+    state: Path,
+    remaining_templates: list[str],
+    *,
+    templates_dir: Path,
+) -> list[str]:
+    """Rebuild the composed `.coding-os/` configs from base + the REMAINING stacks.
+
+    A merged config cannot be un-merged for a single stack (union strategies are
+    lossy), so removal recomposes each file fresh from the base defaults plus
+    every still-installed stack's overlay — dropping the removed stack's
+    contribution. Used by `cos remove-stack`; the caller backs up the targets
+    first because this DISCARDS any user edits layered onto the composed files.
+    A file is rewritten only when the recompose differs from the current target,
+    so the operation is diff-minimal and idempotent. SSOT:
+    docs/engineering/config-composition.md.
+    """
+    written: list[str] = []
+    base_dir = templates_dir / "_base" / "scaffold" / ".coding-os"
+    for filename, spec, fmt in _COMPOSED:
+        target = state / filename
+        if not target.is_file():
+            continue  # nothing composed here — nothing to rebuild
+        base = _load(base_dir / filename, fmt)
+        overlays: list[dict[str, Any]] = []
+        for stack_id in remaining_templates:
+            overlay = _load(
+                _stack_scaffold_dir(stack_id, templates_dir) / ".coding-os" / filename, fmt
+            )
+            if overlay is not None:
+                overlays.append(overlay)
+        merged = compose(base or {}, overlays, spec)
+        new_text = _dump(merged, fmt)
+        if target.read_text(encoding="utf-8") == new_text:
+            continue  # recompose is a no-op for this file
+        target.write_text(new_text, encoding="utf-8")
+        written.append(filename)
+    return written

cli/core_version.py

@@ -0,0 +1,41 @@
+"""Core-version stamp — records which coding-os core scaffolded/updated a
+consumer project so `cos doctor` can warn on drift. Consumers pin to core
+via live symlinks with no version signal (D6); a breaking hook/MCP change
+otherwise breaks them silently on `cos update`. TASK-078."""
+
+from __future__ import annotations
+
+import json
+from datetime import datetime, timezone
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as _pkg_version
+from pathlib import Path
+
+STAMP_FILENAME = "core-version.json"
+
+
+def current_core_version() -> str:
+    try:
+        return _pkg_version("coding-os")
+    except PackageNotFoundError:
+        return "unknown"
+
+
+def stamp_core_version(state_dir: Path, *, now_iso: str | None = None) -> Path:
+    state_dir.mkdir(parents=True, exist_ok=True)
+    path = state_dir / STAMP_FILENAME
+    payload = {
+        "core_version": current_core_version(),
+        "stamped_at": now_iso or datetime.now(timezone.utc).isoformat(timespec="seconds"),
+    }
+    path.write_text(json.dumps(payload, indent=2) + "\n", encoding="utf-8")
+    return path
+
+
+def read_stamped_version(state_dir: Path) -> str | None:
+    try:
+        raw = (state_dir / STAMP_FILENAME).read_text(encoding="utf-8")
+        value = json.loads(raw).get("core_version")
+        return value if isinstance(value, str) else None
+    except (OSError, ValueError):
+        return None

cli/cron_commands.py

@@ -0,0 +1,278 @@
+"""CLI subcommands for scheduled job management: cos cron *."""
+
+from __future__ import annotations
+
+import json
+import os
+import platform
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+import click
+
+CODING_OS_ROOT = Path(__file__).resolve().parent.parent.parent
+_PLIST_SRC = (
+    CODING_OS_ROOT
+    / "src"
+    / "core"
+    / "scheduled"
+    / "launchd"
+    / "com.codingos.nightly.plist.template"
+)
+_PLIST_DEST = Path.home() / "Library" / "LaunchAgents" / "com.codingos.nightly.plist"
+_GLOBAL_SUMMARY = Path.home() / ".coding-os" / "scheduled" / "last_summary.json"
+_NIGHTLY_SCRIPT = CODING_OS_ROOT / "src" / "core" / "scheduled" / "nightly.py"
+
+_SYSTEMD_SRC = CODING_OS_ROOT / "src" / "core" / "scheduled" / "systemd"
+_SERVICE_SRC = _SYSTEMD_SRC / "coding-os-nightly.service.template"
+_TIMER_SRC = _SYSTEMD_SRC / "coding-os-nightly.timer.template"
+_SYSTEMD_USER_DIR = Path.home() / ".config" / "systemd" / "user"
+_SERVICE_DEST = _SYSTEMD_USER_DIR / "coding-os-nightly.service"
+_TIMER_DEST = _SYSTEMD_USER_DIR / "coding-os-nightly.timer"
+_TIMER_UNIT = "coding-os-nightly.timer"
+
+
+def _uv_path() -> str:
+    uv = shutil.which("uv")
+    if not uv:
+        raise click.ClickException("uv not found in PATH. Install: https://docs.astral.sh/uv/")
+    return uv
+
+
+def _cos_nightly_path() -> str:
+    """Prefer installed cos-nightly entry point; fall back to uv run."""
+    installed = shutil.which("cos-nightly")
+    if installed:
+        return installed
+    return ""
+
+
+def _render_plist(hour: int) -> str:
+    if not _PLIST_SRC.exists():
+        raise click.ClickException(f"plist template not found: {_PLIST_SRC}")
+
+    nightly_bin = _cos_nightly_path()
+    if nightly_bin:
+        # installed entry point — direct exec, no uv needed
+        program_args = f"""  <array>
+    <string>{nightly_bin}</string>
+  </array>"""
+    else:
+        # dev / editable install — use uv run
+        uv = _uv_path()
+        program_args = f"""  <array>
+    <string>{uv}</string>
+    <string>run</string>
+    <string>--project</string>
+    <string>{CODING_OS_ROOT}</string>
+    <string>python</string>
+    <string>{_NIGHTLY_SCRIPT}</string>
+  </array>"""
+
+    template = _PLIST_SRC.read_text()
+    # Replace ProgramArguments block (template has uv-run style — override entirely)
+    import re
+
+    template = re.sub(
+        r"<key>ProgramArguments</key>\s*<array>.*?</array>",
+        f"<key>ProgramArguments</key>\n{program_args}",
+        template,
+        flags=re.DOTALL,
+    )
+    return (
+        template.replace("{{HOME}}", str(Path.home()))
+        .replace("{{PATH}}", os.environ.get("PATH", ""))
+        .replace("{{CRON_HOUR}}", str(hour))
+        # {{CODING_OS_ROOT}} and {{UV_PATH}} no longer in body after substitution above
+        .replace("{{CODING_OS_ROOT}}", str(CODING_OS_ROOT))
+        .replace("{{UV_PATH}}", _uv_path())
+    )
+
+
+def _exec_args() -> list[str]:
+    """Nightly invocation — prefer the installed cos-nightly binary, else uv run."""
+    nightly_bin = _cos_nightly_path()
+    if nightly_bin:
+        return [nightly_bin]
+    return [_uv_path(), "run", "--project", str(CODING_OS_ROOT), "python", str(_NIGHTLY_SCRIPT)]
+
+
+def _render_systemd(hour: int) -> tuple[str, str]:
+    if not _SERVICE_SRC.exists() or not _TIMER_SRC.exists():
+        raise click.ClickException(f"systemd templates not found under {_SYSTEMD_SRC}")
+    exec_start = " ".join(_exec_args())
+    service = (
+        _SERVICE_SRC.read_text()
+        .replace("{{EXEC_START}}", exec_start)
+        .replace("{{PATH}}", os.environ.get("PATH", ""))
+        .replace("{{HOME}}", str(Path.home()))
+    )
+    timer = _TIMER_SRC.read_text().replace("{{CRON_HOUR}}", f"{hour:02d}")
+    return service, timer
+
+
+def _systemctl(*args: str) -> subprocess.CompletedProcess:
+    return subprocess.run(["systemctl", "--user", *args], capture_output=True, text=True)
+
+
+def _install_launchd(hour: int) -> str:
+    rendered = _render_plist(hour)
+    _PLIST_DEST.parent.mkdir(parents=True, exist_ok=True)
+    _PLIST_DEST.write_text(rendered)
+    result = subprocess.run(
+        ["launchctl", "load", "-w", str(_PLIST_DEST)], capture_output=True, text=True
+    )
+    if result.returncode != 0:
+        raise click.ClickException(f"launchctl load failed: {result.stderr.strip()}")
+    return "cos-nightly binary" if _cos_nightly_path() else "uv run (dev mode)"
+
+
+def _install_systemd(hour: int) -> None:
+    if not shutil.which("systemctl"):
+        raise click.ClickException("systemctl not found — install systemd or schedule via crontab.")
+    service, timer = _render_systemd(hour)
+    _SYSTEMD_USER_DIR.mkdir(parents=True, exist_ok=True)
+    _SERVICE_DEST.write_text(service)
+    _TIMER_DEST.write_text(timer)
+    _systemctl("daemon-reload")
+    r = _systemctl("enable", "--now", _TIMER_UNIT)
+    if r.returncode != 0:
+        raise click.ClickException(f"systemctl enable failed: {r.stderr.strip()}")
+
+
+def _uninstall_systemd() -> bool:
+    if shutil.which("systemctl"):
+        _systemctl("disable", "--now", _TIMER_UNIT)
+    removed = False
+    for dest in (_TIMER_DEST, _SERVICE_DEST):
+        if dest.exists():
+            dest.unlink()
+            removed = True
+    if shutil.which("systemctl"):
+        _systemctl("daemon-reload")
+    return removed
+
+
+@click.group("cron")
+def cron_cmd() -> None:
+    """Manage the nightly scheduled maintenance job (CRON A)."""
+
+
+@cron_cmd.command("install")
+@click.option(
+    "--hour", default=3, show_default=True, metavar="0-23", help="Hour of day to run (local time)."
+)
+def cron_install(hour: int) -> None:
+    """Install + load the nightly job (macOS launchd / Linux systemd user timer)."""
+    if not 0 <= hour <= 23:
+        raise click.ClickException("--hour must be 0-23")
+
+    log_dir = Path.home() / ".coding-os" / "scheduled"
+    log_dir.mkdir(parents=True, exist_ok=True)
+
+    system = platform.system()
+    if system == "Darwin":
+        mode = _install_launchd(hour)
+        click.echo(f"✓ cron installed (launchd, {mode}) — runs daily at {hour:02d}:00")
+        click.echo(f"  plist: {_PLIST_DEST}")
+    elif system == "Linux":
+        _install_systemd(hour)
+        mode = "cos-nightly binary" if _cos_nightly_path() else "uv run (dev mode)"
+        click.echo(f"✓ cron installed (systemd --user timer, {mode}) — runs daily at {hour:02d}:00")
+        click.echo(f"  unit:  {_TIMER_DEST}")
+    else:
+        raise click.ClickException(
+            f"unsupported OS {system!r}; schedule `cos cron run` via crontab instead."
+        )
+    click.echo(f"  logs:  {log_dir}")
+
+
+@cron_cmd.command("uninstall")
+def cron_uninstall() -> None:
+    """Unload + remove the nightly job (launchd on macOS / systemd timer on Linux)."""
+    system = platform.system()
+    if system == "Darwin":
+        subprocess.run(["launchctl", "unload", "-w", str(_PLIST_DEST)], capture_output=True)
+        if _PLIST_DEST.exists():
+            _PLIST_DEST.unlink()
+            click.echo("✓ cron uninstalled")
+        else:
+            click.echo("nothing to uninstall (plist not found)")
+    elif system == "Linux":
+        if _uninstall_systemd():
+            click.echo("✓ cron uninstalled")
+        else:
+            click.echo("nothing to uninstall (timer not found)")
+    else:
+        click.echo(f"nothing to uninstall on {system}")
+
+
+@cron_cmd.command("run")
+@click.option("--dry-run", is_flag=True, help="Simulate without writing.")
+@click.option("--project", "slug", default=None, metavar="SLUG", help="Run only this project slug.")
+@click.option("--verbose", "-v", is_flag=True)
+@click.option("--reset-failures", is_flag=True, help="Clear failure counter first.")
+def cron_run(dry_run: bool, slug: str | None, verbose: bool, reset_failures: bool) -> None:
+    """Run nightly maintenance now."""
+    # Import nightly directly — no subprocess, no PYTHONPATH injection.
+    # Both installed (uv tool install) and dev (editable) paths work because
+    # pyproject.toml maps "scheduled" → "src/core/scheduled" so nightly is importable.
+    try:
+        from scheduled import nightly  # type: ignore[import]
+    except ImportError as exc:
+        raise click.ClickException(f"scheduled package not importable: {exc}") from exc
+
+    argv: list[str] = []
+    if dry_run:
+        argv.append("--dry-run")
+    if slug:
+        argv += ["--project", slug]
+    if verbose:
+        argv.append("--verbose")
+    if reset_failures:
+        argv.append("--reset-failures")
+
+    click.echo("[cron] running nightly maintenance…", err=True)
+    rc = nightly.main(argv)
+    sys.exit(rc if rc else 0)
+
+
+@cron_cmd.command("status")
+def cron_status() -> None:
+    """Show last nightly run summary."""
+    system = platform.system()
+    if system == "Linux":
+        installed = _TIMER_DEST.exists()
+        loaded = bool(installed and shutil.which("systemctl")) and (
+            _systemctl("is-enabled", _TIMER_UNIT).returncode == 0
+        )
+    else:
+        installed = _PLIST_DEST.exists()
+        loaded = False
+        if installed and system == "Darwin":
+            r = subprocess.run(["launchctl", "list", "com.codingos.nightly"], capture_output=True)
+            loaded = r.returncode == 0
+
+    click.echo(f"installed : {installed}")
+    click.echo(f"loaded    : {loaded}")
+
+    if _GLOBAL_SUMMARY.exists():
+        try:
+            data = json.loads(_GLOBAL_SUMMARY.read_text())
+            click.echo(f"last run  : {data.get('run_at', 'unknown')}")
+            for proj in data.get("projects", []):
+                slug = proj.get("slug", "?")
+                err = proj.get("last_error")
+                failures = proj.get("consecutive_failures", 0)
+                click.echo(f"  [{slug}] failures={failures} error={err or 'none'}")
+                for task, info in (proj.get("tasks") or {}).items():
+                    status = info.get("status", "?")
+                    reason = info.get("reason", "")
+                    suffix = f" ({reason})" if reason else ""
+                    click.echo(f"    {task}: {status}{suffix}")
+        except (json.JSONDecodeError, OSError) as exc:
+            click.echo(f"could not read summary: {exc}")
+    else:
+        click.echo("no run recorded yet — run: cos cron run")