nightshift-cli 0.1.0__py3-none-any.whl

nightshift/events.py

@@ -0,0 +1,293 @@
+"""Append-only event logs, so a run can be watched from another process.
+
+cron starts each run in its own process, so a dashboard opened at 2am has no
+callback to subscribe to and no way back into a run that began an hour ago.
+Every run therefore publishes what it sees to a file as it goes, and
+``nightshift watch`` tails it.
+
+Nothing here is load-bearing. The digest is built from stored results, never
+from these logs; a run whose event log could not be written is still a correct
+run, and deleting the whole directory loses nothing but the view.
+
+The files hold tool inputs and snippets of the repo being reviewed, so they are
+created ``0600`` under a ``0700`` directory rather than left world-readable.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import time
+from datetime import date, datetime
+from pathlib import Path
+from typing import Iterator
+
+from nightshift.adapters.base import Event, RunResult
+from nightshift.config import state_dir
+
+#: Event logs older than this are pruned on the next run.
+KEEP_DAYS = 14
+
+#: How long a reader waits before checking a file for new lines again.
+POLL_S = 0.2
+
+#: A log with no new line for this long is treated as abandoned. Its writer
+#: was killed, or wedged, and no ``end`` is ever coming — a reader that waits
+#: for one would block forever. Comfortably longer than the default run
+#: timeout so a slow-but-live run is never mistaken for a dead one.
+STALE_AFTER_S = 900.0
+
+
+def events_dir() -> Path:
+    return state_dir() / "events"
+
+
+def day_dir(on: date) -> Path:
+    return events_dir() / on.isoformat()
+
+
+def _slug(text: str) -> str:
+    keep = [c if (c.isalnum() or c in "-_") else "-" for c in text.strip().lower()]
+    return "".join(keep).strip("-") or "unknown"
+
+
+def log_path(project: str, task: str, started: datetime, attempt: int = 1) -> Path:
+    stem = f"{_slug(project)}-{_slug(task)}-{started.strftime('%H%M%S')}"
+    if attempt > 1:
+        stem += f"-retry{attempt - 1}"
+    return day_dir(started.date()) / f"{stem}.ndjson"
+
+
+class EventLog:
+    """One run's events, appended as newline-delimited JSON.
+
+    Every method swallows its own errors. A full disk or a read-only home must
+    cost the view, not the run.
+    """
+
+    def __init__(self, path: Path):
+        self.path = path
+        self._fh = None
+
+    # ---- writing ------------------------------------------------------
+
+    @classmethod
+    def open(
+        cls,
+        project: str,
+        task: str,
+        provider: str,
+        started: datetime,
+        attempt: int = 1,
+    ) -> EventLog:
+        log = cls(log_path(project, task, started, attempt))
+        try:
+            # mkdir's mode applies to the leaf only, so events/ itself would
+            # otherwise be born with whatever the umask says.
+            events_dir().mkdir(parents=True, exist_ok=True, mode=0o700)
+            log.path.parent.mkdir(parents=True, exist_ok=True, mode=0o700)
+            fd = os.open(str(log.path), os.O_WRONLY | os.O_CREAT | os.O_APPEND, 0o600)
+            log._fh = os.fdopen(fd, "a", encoding="utf-8")
+        except OSError:
+            log._fh = None
+            return log
+        log._append(
+            {
+                "kind": "meta",
+                "project": project,
+                "task": task,
+                "provider": provider,
+                "started_at": started.isoformat(),
+                "attempt": attempt,
+            }
+        )
+        return log
+
+    def _append(self, payload: dict) -> None:
+        if self._fh is None:
+            return
+        payload.setdefault("t", datetime.now().isoformat(timespec="milliseconds"))
+        try:
+            # One json.dumps per line, flushed but not fsynced: a reader in
+            # another process sees it immediately, and a lost tail on a crash
+            # costs nothing the result file does not already hold.
+            self._fh.write(json.dumps(payload, ensure_ascii=False) + "\n")
+            self._fh.flush()
+        except (OSError, ValueError, TypeError):
+            self.close_quietly()
+
+    def write(self, event: Event) -> None:
+        """Record one adapter event. Safe to pass straight to ``on_event``."""
+        self._append(
+            {
+                "kind": event.kind,
+                "text": event.text,
+                "tool": event.tool,
+                "detail": event.detail,
+            }
+        )
+
+    def finish(self, result: RunResult, findings: int = 0) -> None:
+        self._append(
+            {
+                "kind": "end",
+                "status": result.status,
+                "duration_s": round(result.duration_s, 3),
+                "detail": result.detail,
+                "findings": findings,
+            }
+        )
+        self.close_quietly()
+
+    def close_quietly(self) -> None:
+        fh, self._fh = self._fh, None
+        if fh is None:
+            return
+        try:
+            fh.close()
+        except OSError:
+            pass
+
+
+# ---- reading ----------------------------------------------------------
+
+
+def parse(line: str) -> dict | None:
+    """One event, or ``None`` for a blank, torn, or unreadable line."""
+    line = line.strip()
+    if not line:
+        return None
+    try:
+        payload = json.loads(line)
+    except json.JSONDecodeError:
+        return None
+    return payload if isinstance(payload, dict) else None
+
+
+def read(path: Path) -> list[dict]:
+    try:
+        text = path.read_text(encoding="utf-8", errors="replace")
+    except OSError:
+        return []
+    return [p for p in (parse(line) for line in text.splitlines()) if p is not None]
+
+
+def is_finished(path: Path) -> bool:
+    events = read(path)
+    return bool(events) and events[-1].get("kind") == "end"
+
+
+def is_stale(path: Path, stale_after_s: float = STALE_AFTER_S) -> bool:
+    """Has nothing been appended to ``path`` for a long time?
+
+    An interrupted run leaves a log with no ``end``; without this a reader
+    cannot tell it from a run still in flight, and waits on it forever.
+    """
+    try:
+        return (time.time() - path.stat().st_mtime) > stale_after_s
+    except OSError:
+        return True
+
+
+def logs_for(on: date) -> list[Path]:
+    try:
+        return sorted(day_dir(on).glob("*.ndjson"))
+    except OSError:
+        return []
+
+
+def recent_logs(limit: int = 20) -> list[Path]:
+    """Newest run logs first, across every day we still keep.
+
+    Ordered by mtime rather than by name: a log's name starts with the project
+    slug, so sorting on it groups by project and only then by clock — which is
+    not "recent" at all once two projects are registered.
+    """
+    try:
+        found = list(events_dir().rglob("*.ndjson"))
+    except OSError:
+        return []
+
+    def when(path: Path) -> float:
+        try:
+            return path.stat().st_mtime
+        except OSError:
+            return 0.0
+
+    found.sort(key=when, reverse=True)
+    return found[:limit]
+
+
+def follow(
+    path: Path,
+    stop_after_end: bool = True,
+    stale_after_s: float = STALE_AFTER_S,
+) -> Iterator[dict]:
+    """Yield events from ``path``, waiting for more until the run ends.
+
+    Returns on the ``end`` event, or once the log has gone quiet for
+    ``stale_after_s``. Waiting only for ``end`` would hang forever on the log
+    of a run that was killed, and take the whole watcher down with it.
+
+    A partial final line — the writer was mid-append — is left alone and
+    retried rather than parsed as garbage.
+    """
+    try:
+        fh = path.open("r", encoding="utf-8", errors="replace")
+    except OSError:
+        return
+    try:
+        buffer = ""
+        last_line_at = time.monotonic()
+        while True:
+            chunk = fh.readline()
+            if not chunk:
+                if time.monotonic() - last_line_at > stale_after_s:
+                    return
+                time.sleep(POLL_S)
+                continue
+            last_line_at = time.monotonic()
+            buffer += chunk
+            if not buffer.endswith("\n"):
+                # Torn write: wait for the writer to finish the line.
+                continue
+            payload = parse(buffer)
+            buffer = ""
+            if payload is None:
+                continue
+            yield payload
+            if stop_after_end and payload.get("kind") == "end":
+                return
+    finally:
+        try:
+            fh.close()
+        except OSError:
+            pass
+
+
+# ---- housekeeping -----------------------------------------------------
+
+
+def prune(keep_days: int = KEEP_DAYS, today: date | None = None) -> int:
+    """Delete event logs older than ``keep_days``. Returns days removed."""
+    today = today or date.today()
+    removed = 0
+    try:
+        days = [d for d in events_dir().iterdir() if d.is_dir()]
+    except OSError:
+        return 0
+    for directory in days:
+        try:
+            on = date.fromisoformat(directory.name)
+        except ValueError:
+            continue  # not ours; leave it alone
+        if (today - on).days <= keep_days:
+            continue
+        try:
+            for child in directory.iterdir():
+                child.unlink()
+            directory.rmdir()
+            removed += 1
+        except OSError:
+            continue
+    return removed

nightshift/lock.py

@@ -0,0 +1,197 @@
+"""A cooperative lockfile so two cron ticks never run at once."""
+
+from __future__ import annotations
+
+import errno
+import json
+import logging
+import os
+import time as _time
+from dataclasses import dataclass
+from pathlib import Path
+
+from nightshift.config import state_dir
+
+log = logging.getLogger("nightshift")
+
+#: How far past the longest legitimate run a lock may live before we presume
+#: its holder died. This multiplies the *whole* run budget — every attempt at
+#: its full timeout — and must exceed it rather than equal it: a threshold a
+#: healthy run can reach is a live lock waiting to be broken.
+STALE_MULTIPLIER = 2
+
+
+def lock_path() -> Path:
+    return state_dir() / "lock"
+
+
+class LockBusy(Exception):
+    """Another nightshift run holds the lock."""
+
+
+@dataclass
+class LockInfo:
+    pid: int
+    acquired_at: float
+
+    @property
+    def age_s(self) -> float:
+        return max(0.0, _time.time() - self.acquired_at)
+
+
+class Lock:
+    """An exclusive lock built on ``O_CREAT | O_EXCL``.
+
+    Stale locks — left behind by a run that was killed before it could clean up
+    — are broken automatically once they outlive :attr:`stale_after_s`.
+
+    That threshold is measured against the longest a healthy holder can take,
+    which is every attempt running to its full timeout, not one. This docstring
+    used to say "twice the run timeout, strictly longer than any healthy run can
+    survive"; with two attempts allowed and a multiplier of two those were the
+    same number, so a healthy run that used its whole budget landed exactly on
+    the threshold and any overhead put it past. Its live lock would be broken
+    and a second run would start beside it — the one thing the lock exists to
+    prevent.
+
+    Callers that retry must therefore say so via ``attempts``, or the lock will
+    size the threshold for a single run.
+    """
+
+    def __init__(
+        self,
+        path: Path | None = None,
+        timeout_s: int = 600,
+        attempts: int = 1,
+    ):
+        self.path = path or lock_path()
+        self.timeout_s = timeout_s
+        #: Total tries the holder may make, each up to ``timeout_s`` — the first
+        #: one included, not retries stacked on top of it. ``attempts=2`` is one
+        #: try and one retry, matching the scheduler's ``range(1, MAX_ATTEMPTS + 1)``.
+        #: Read as "retries" it would double the threshold it was meant to set.
+        self.attempts = max(int(attempts), 1)
+        self._held = False
+        #: Stamp we wrote when we took the lock. Together with the pid it is
+        #: what makes a lockfile *ours* rather than merely present — see
+        #: :meth:`release`. A pid alone cannot say: two Lock objects in one
+        #: process share one, and the OS reuses pids.
+        self._acquired_at: float | None = None
+
+    @property
+    def max_run_s(self) -> float:
+        """The longest a healthy holder can legitimately take."""
+        return self.timeout_s * self.attempts
+
+    @property
+    def stale_after_s(self) -> float:
+        return self.max_run_s * STALE_MULTIPLIER
+
+    def read(self) -> LockInfo | None:
+        try:
+            data = json.loads(self.path.read_text(encoding="utf-8"))
+            return LockInfo(pid=int(data["pid"]), acquired_at=float(data["acquired_at"]))
+        except FileNotFoundError:
+            return None
+        except (json.JSONDecodeError, KeyError, ValueError, OSError, TypeError):
+            # An unreadable lock is indistinguishable from an abandoned one; fall
+            # back to its mtime so it can still go stale and be broken.
+            try:
+                return LockInfo(pid=-1, acquired_at=self.path.stat().st_mtime)
+            except OSError:
+                return None
+
+    def is_stale(self, info: LockInfo | None = None) -> bool:
+        info = info or self.read()
+        return info is not None and info.age_s > self.stale_after_s
+
+    def _write(self) -> None:
+        acquired_at = _time.time()
+        fd = os.open(self.path, os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o644)
+        with os.fdopen(fd, "w", encoding="utf-8") as fh:
+            json.dump({"pid": os.getpid(), "acquired_at": acquired_at}, fh)
+        self._acquired_at = acquired_at
+
+    def _is_ours(self, info: LockInfo | None) -> bool:
+        """Is the lockfile on disk the one *we* wrote?
+
+        The pid cannot settle this alone: two Lock objects in one process share
+        it, and the OS reuses pids. The acquisition stamp can — nothing else
+        wrote that float.
+        """
+        if info is None or self._acquired_at is None:
+            return False
+        return info.pid == os.getpid() and info.acquired_at == self._acquired_at
+
+    def acquire(self) -> None:
+        """Take the lock, breaking it first if it has gone stale.
+
+        Raises :class:`LockBusy` if a live run holds it.
+        """
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        try:
+            self._write()
+            self._held = True
+            return
+        except FileExistsError:
+            pass
+        except OSError as exc:  # pragma: no cover - platform dependent
+            if exc.errno != errno.EEXIST:
+                raise
+
+        info = self.read()
+        if info is None:
+            # Vanished between the failed create and the read — retry once.
+            try:
+                self._write()
+                self._held = True
+                return
+            except FileExistsError:
+                raise LockBusy("another nightshift run just took the lock") from None
+
+        if not self.is_stale(info):
+            raise LockBusy(
+                f"another nightshift run is in progress (pid {info.pid}, "
+                f"started {info.age_s:.0f}s ago)"
+            )
+
+        self.break_stale()
+        try:
+            self._write()
+            self._held = True
+        except FileExistsError:
+            raise LockBusy("another nightshift run just took the lock") from None
+
+    def break_stale(self) -> None:
+        try:
+            self.path.unlink()
+        except FileNotFoundError:
+            pass
+
+    def release(self) -> None:
+        """Give up the lock, but only if the lockfile is still ours.
+
+        A run that overran had its lock broken as stale, and someone else is
+        working now. Unlinking on the way out would delete *their* lockfile and
+        let a third run start alongside a live one — the exact thing the lock
+        exists to prevent, brought about by the cleanup rather than the overrun.
+        """
+        if not self._held:
+            return
+        self._held = False
+
+        if not self._is_ours(self.read()):
+            log.debug("not releasing %s — it is no longer our lock", self.path)
+            return
+
+        try:
+            self.path.unlink()
+        except FileNotFoundError:
+            pass
+
+    def __enter__(self) -> Lock:
+        self.acquire()
+        return self
+
+    def __exit__(self, *exc_info: object) -> None:
+        self.release()

nightshift/prompts/code_review.md

@@ -0,0 +1,24 @@
+You are reviewing a codebase as a careful senior engineer.
+
+**You may only read.** Do not modify, create, or delete any file. Do not run
+commands that mutate state. If you cannot inspect something without changing
+it, skip it and say so.
+
+Review the project for correctness and maintainability problems that a
+reviewer would genuinely raise: logic errors, unhandled failure modes, race
+conditions, resource leaks, misleading names, and code that will surprise the
+next reader. Prefer a few real problems over many nitpicks.
+
+Output format — a markdown list, one finding per line, each line:
+
+`- HIGH|MED|LOW <repo-relative/path.ext>:<line> — <one-line recommendation>`
+
+Rules:
+- Prefix every finding with exactly one of `HIGH`, `MED`, or `LOW`.
+- `HIGH` = likely to cause incorrect behaviour, data loss, or a security hole.
+  `MED` = real bug or risk with limited blast radius. `LOW` = worth fixing but
+  harmless today.
+- Every finding must cite a repo-relative `file:line`.
+- Give exactly one line of recommendation per finding — say what to do, not
+  just what is wrong.
+- If the project is clean, output exactly: `No findings.`

nightshift/prompts/dead_links.md

@@ -0,0 +1,21 @@
+You are checking a project's documentation for dead references.
+
+**You may only read.** Do not modify, create, or delete any file. Do not fetch
+the network — judge links from the repository contents alone.
+
+Look for: relative links and image paths that point at files which do not exist
+in the repo, anchors pointing at headings that are absent, references to moved
+or deleted docs, links to repositories or paths that contradict the project's
+own name and layout, and TODO placeholder URLs left in published docs.
+
+Output format — a markdown list, one finding per line, each line:
+
+`- HIGH|MED|LOW <repo-relative/path.ext>:<line> — <one-line recommendation>`
+
+Rules:
+- Prefix every finding with exactly one of `HIGH`, `MED`, or `LOW`.
+- `HIGH` = a link in the README's install or quickstart path is broken.
+  `MED` = a broken link in body documentation. `LOW` = a cosmetic or TODO link.
+- Every finding must cite the repo-relative `file:line` of the link itself.
+- Name the correct target in the recommendation when you can infer it.
+- If every reference resolves, output exactly: `No findings.`

nightshift/prompts/deps_audit.md

@@ -0,0 +1,23 @@
+You are auditing a project's dependencies.
+
+**You may only read.** Do not modify, create, or delete any file. Do not run
+installers, upgrades, or any command that mutates the lockfile or environment.
+
+Read the manifests and lockfiles present (`requirements.txt`, `pyproject.toml`,
+`package.json`, `package-lock.json`, `go.mod`, `Cargo.toml`, `Dockerfile`, …).
+Look for: dependencies with known advisories, unpinned or floating versions,
+unpinned container base images, abandoned packages, and duplicate or
+conflicting version constraints.
+
+Output format — a markdown list, one finding per line, each line:
+
+`- HIGH|MED|LOW <repo-relative/path.ext>:<line> — <one-line recommendation>`
+
+Rules:
+- Prefix every finding with exactly one of `HIGH`, `MED`, or `LOW`.
+- `HIGH` = known exploitable advisory, or a wholly unpinned base image.
+  `MED` = advisory needing a precondition, or a floating major version.
+  `LOW` = routine upgrade available.
+- Every finding must cite a repo-relative `file:line`.
+- Name the package and the target version in the recommendation.
+- If the project is clean, output exactly: `No findings.`

nightshift/prompts/docs_drift.md

@@ -0,0 +1,21 @@
+You are checking whether a project's documentation still matches its code.
+
+**You may only read.** Do not modify, create, or delete any file.
+
+Compare the README, docs, and inline setup instructions against what the code
+actually does: command names and Makefile targets that were renamed or removed,
+documented flags and environment variables that no longer exist, install steps
+that would fail on a clean machine, examples importing symbols that moved, and
+documented defaults that no longer match the code.
+
+Output format — a markdown list, one finding per line, each line:
+
+`- HIGH|MED|LOW <repo-relative/path.ext>:<line> — <one-line recommendation>`
+
+Rules:
+- Prefix every finding with exactly one of `HIGH`, `MED`, or `LOW`.
+- `HIGH` = documented quickstart is broken and a new user would be blocked.
+  `MED` = a documented command or flag is wrong. `LOW` = stale prose.
+- Cite the **documentation** `file:line` that is wrong, and name the code that
+  contradicts it in the recommendation.
+- If the docs match the code, output exactly: `No findings.`

nightshift/prompts/security_audit.md

@@ -0,0 +1,23 @@
+You are auditing a codebase for security problems.
+
+**You may only read.** Do not modify, create, or delete any file. Do not run
+commands that mutate state, and never exfiltrate secrets you find — cite the
+location, not the value.
+
+Look for: injection (SQL, shell, template), missing authentication or
+authorization on routes and handlers, secrets committed to the repo, unsafe
+deserialization, path traversal, weak or missing crypto, permissive CORS,
+tokens without expiry, and unsafe defaults in configuration.
+
+Output format — a markdown list, one finding per line, each line:
+
+`- HIGH|MED|LOW <repo-relative/path.ext>:<line> — <one-line recommendation>`
+
+Rules:
+- Prefix every finding with exactly one of `HIGH`, `MED`, or `LOW`.
+- `HIGH` = exploitable, or a secret is exposed. `MED` = a real weakness needing
+  a precondition. `LOW` = hardening.
+- Every finding must cite a repo-relative `file:line`.
+- If you find a credential, write `<redacted>` in place of its value.
+- Give exactly one line of recommendation per finding.
+- If the project is clean, output exactly: `No findings.`

nightshift/prompts.py

@@ -0,0 +1,66 @@
+"""Prompt template resolution.
+
+Two sources, in order: the user's own ``~/.nightshift/prompts/`` and the
+templates packaged with nightshift. Any ``.md`` file in either directory is a
+valid task name, so a user can add a task by dropping in a file — and can
+override a shipped template by using the same filename.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from nightshift.config import state_dir
+
+PACKAGED_PROMPTS = Path(__file__).parent / "prompts"
+
+
+class PromptError(Exception):
+    """A prompt template could not be resolved."""
+
+
+def user_prompts() -> Path:
+    return state_dir() / "prompts"
+
+
+def prompt_dirs() -> list[Path]:
+    """Search path, highest precedence first."""
+    return [user_prompts(), PACKAGED_PROMPTS]
+
+
+def available_tasks() -> list[str]:
+    """Every task name resolvable right now."""
+    tasks: set[str] = set()
+    for directory in prompt_dirs():
+        if not directory.is_dir():
+            continue
+        for path in directory.glob("*.md"):
+            if path.is_file():
+                tasks.add(path.stem)
+    return sorted(tasks)
+
+
+def find(task: str) -> Path | None:
+    for directory in prompt_dirs():
+        candidate = directory / f"{task}.md"
+        if candidate.is_file():
+            return candidate
+    return None
+
+
+def load(task: str) -> str:
+    """Read the template for ``task``."""
+    path = find(task)
+    if path is None:
+        known = ", ".join(available_tasks()) or "none found"
+        raise PromptError(
+            f"no prompt template for task {task!r} — looked in "
+            f"{', '.join(str(d) for d in prompt_dirs())}. Available tasks: {known}"
+        )
+    try:
+        text = path.read_text(encoding="utf-8").strip()
+    except OSError as exc:
+        raise PromptError(f"cannot read prompt {path}: {exc}") from exc
+    if not text:
+        raise PromptError(f"prompt template {path} is empty")
+    return text