nightshift-cli 0.1.0__py3-none-any.whl

nightshift/__init__.py

@@ -0,0 +1,8 @@
+"""nightshift — your AI works the night shift.
+
+Read-only reviews of your projects while you're busy, one digest every morning.
+"""
+
+__version__ = "0.1.0"
+
+APP_NAME = "nightshift"

nightshift/__main__.py

@@ -0,0 +1,4 @@
+from nightshift.cli import main
+
+if __name__ == "__main__":
+    main()

nightshift/adapters/__init__.py

@@ -0,0 +1,61 @@
+"""Provider adapters.
+
+Each adapter wraps one AI coding CLI the user already pays for. Adapters are
+strictly read-only: they may inspect a project, never modify it.
+"""
+
+from __future__ import annotations
+
+import inspect
+
+from nightshift.adapters.base import Adapter, AdapterError, RunResult, Status
+from nightshift.adapters.claude_code import ClaudeCodeAdapter
+from nightshift.adapters.codex import CodexAdapter
+from nightshift.adapters.copilot import CopilotAdapter
+
+_REGISTRY: dict[str, type] = {
+    "claude_code": ClaudeCodeAdapter,
+    "codex": CodexAdapter,
+    "copilot": CopilotAdapter,
+}
+
+
+def get(name: str, binary: str | None = None) -> Adapter:
+    """Instantiate the adapter registered under ``name``.
+
+    ``binary`` overrides where the adapter looks for its CLI. Left ``None``, the
+    adapter keeps its own default and finds it on PATH as before.
+    """
+    try:
+        cls = _REGISTRY[name]
+    except KeyError:
+        known = ", ".join(sorted(_REGISTRY))
+        raise AdapterError(f"unknown provider {name!r} — known: {known}") from None
+    if binary is None:
+        return cls()  # type: ignore[return-value]
+    # Asked by name rather than caught as a TypeError: `cls(binary=...)` raising
+    # TypeError from somewhere deeper inside __init__ would look identical, and
+    # we would report the wrong cause for it.
+    if "binary" not in inspect.signature(cls).parameters:
+        raise AdapterError(
+            f"provider {name!r} does not take a custom binary path — it does not "
+            f"run a CLI of its own. Remove `binary` from providers.{name}."
+        )
+    return cls(binary=binary)  # type: ignore[return-value]
+
+
+def names() -> list[str]:
+    return sorted(_REGISTRY)
+
+
+__all__ = [
+    "Adapter",
+    "AdapterError",
+    "ClaudeCodeAdapter",
+    "CodexAdapter",
+    "CopilotAdapter",
+    "RunResult",
+    "Status",
+    "get",
+    "names",
+]

nightshift/adapters/_process.py

@@ -0,0 +1,219 @@
+"""Process machinery shared by adapters that drive a streaming CLI.
+
+Extracted when the Codex adapter arrived. Both it and Claude Code spawn a CLI,
+read newline-delimited JSON off its stdout, and must guarantee the child tree
+dies at the deadline instead of living on holding provider quota while cron sits
+on the lock.
+
+That guarantee is the reason this module exists rather than a second copy of it.
+Getting it right took two fixes — a deadline disarmed before the child was
+reaped (13c0d3f) and a kill aimed at a pid that could already have been reused
+— and a duplicate would have needed both, twice, discovered twice.
+
+Nothing here knows what any event *means*. Translating lines into findings is
+each adapter's job; this only promises the process starts, is read to the end,
+and is dead when we return.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import signal
+import subprocess
+import threading
+import time
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Callable
+
+from nightshift.adapters.base import Event, OnEvent
+
+#: Slack given to a process that should already be dying, before we conclude the
+#: deadline timer failed and kill the tree ourselves.
+REAP_GRACE_S = 10
+
+
+@dataclass
+class StreamOutcome:
+    """How a streamed run ended. Says nothing about what it produced."""
+
+    returncode: int
+    timed_out: bool
+    stderr_lines: list[str] = field(default_factory=list)
+
+    @property
+    def stderr_head(self) -> str:
+        """First line of stderr, or an exit-code summary — for ``detail``."""
+        stderr = "\n".join(self.stderr_lines).strip()
+        if stderr:
+            return stderr.splitlines()[0]
+        return f"exit {self.returncode}"
+
+
+def parse_line(line: str) -> dict | None:
+    """One NDJSON event, or ``None`` for anything we can't read.
+
+    A malformed line is skipped rather than fatal: the stream is telemetry, and
+    the run's outcome must not hinge on our parsing every frame of it.
+    """
+    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 clip(text: str, limit: int) -> str:
+    text = str(text or "").replace("\n", " ").strip()
+    return text if len(text) <= limit else text[: limit - 1] + "…"
+
+
+def format_input(value: object, limit: int = 60) -> str:
+    """Render tool input as ``key: value``, short enough for one line."""
+    if not isinstance(value, dict) or not value:
+        return ""
+    return ", ".join(f"{k}: {clip(v, limit)}" for k, v in list(value.items())[:2])
+
+
+def summarize(content: object, limit: int = 70) -> str:
+    """One line describing a tool result."""
+    if isinstance(content, list):
+        content = " ".join(
+            str(b.get("text", "")) for b in content if isinstance(b, dict)
+        )
+    text = str(content or "").strip()
+    if not text:
+        return ""
+    lines = text.splitlines()
+    first = lines[0]
+    if len(first) > limit:
+        first = first[: limit - 1] + "…"
+    if len(lines) > 1:
+        first += f"  (+{len(lines) - 1} lines)"
+    return first
+
+
+def emit(on_event: OnEvent, event: Event) -> None:
+    """A broken renderer must not fail a run that has already been billed."""
+    try:
+        on_event(event)
+    except Exception:  # noqa: BLE001 - the callback is the caller's problem
+        pass
+
+
+def _drain(stream, sink: list[str]) -> None:
+    if stream is None:
+        return
+    try:
+        for line in stream:
+            sink.append(line.rstrip("\n"))
+    except (OSError, ValueError):
+        pass
+
+
+def kill_tree(proc: subprocess.Popen) -> None:
+    """Kill the CLI and anything it spawned.
+
+    ``start_new_session`` made it a process-group leader precisely so this can
+    reach its children.
+    """
+    try:
+        os.killpg(os.getpgid(proc.pid), signal.SIGKILL)
+    except (OSError, ProcessLookupError):
+        try:
+            proc.kill()
+        except OSError:
+            pass
+
+
+def stream_ndjson(
+    argv: list[str],
+    cwd: Path,
+    timeout_s: int,
+    on_line: Callable[[dict], None],
+) -> StreamOutcome:
+    """Run ``argv``, feeding each NDJSON line on stdout to ``on_line``.
+
+    Returns once the child is reaped. Raises ``FileNotFoundError`` / ``OSError``
+    if it could not be started at all — the caller owns that story, since only it
+    knows which binary was missing.
+
+    ``on_line`` runs on this thread and must not raise.
+    """
+    proc = subprocess.Popen(
+        argv,
+        cwd=str(cwd),
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        stdin=subprocess.DEVNULL,
+        text=True,
+        bufsize=1,
+        start_new_session=True,
+    )
+
+    timed_out = threading.Event()
+    guard = threading.Lock()
+    reaped = False
+
+    def on_deadline() -> None:
+        # The timer races the normal exit. Once the process has been waited for,
+        # its pid can be reused — killing "it" would then SIGKILL an unrelated
+        # process group.
+        with guard:
+            if reaped or proc.poll() is not None:
+                return
+            timed_out.set()
+            kill_tree(proc)
+
+    deadline = time.monotonic() + timeout_s
+    timer = threading.Timer(timeout_s, on_deadline)
+    timer.daemon = True
+    timer.start()
+
+    stderr_lines: list[str] = []
+    drain = threading.Thread(target=_drain, args=(proc.stderr, stderr_lines), daemon=True)
+    drain.start()
+
+    try:
+        for line in proc.stdout or ():
+            payload = parse_line(line)
+            if payload is not None:
+                on_line(payload)
+    finally:
+        # The timer stays armed across the wait, because it is the only thing
+        # that can end a child which closed stdout and then hung — an EOF here
+        # does not mean the process is going to exit. Cancelling it before an
+        # unbounded wait() left nothing to terminate such a run, and cron would
+        # sit on the lock until someone noticed.
+        try:
+            proc.wait(timeout=max(deadline - time.monotonic(), 0) + REAP_GRACE_S)
+        except subprocess.TimeoutExpired:
+            # The timer should have fired by now; it did not, so do its job.
+            kill_tree(proc)
+            try:
+                proc.wait(timeout=REAP_GRACE_S)
+            except subprocess.TimeoutExpired:
+                pass
+        timer.cancel()
+        with guard:
+            # Only now may on_deadline be told to keep its hands off: the process
+            # is reaped and its pid is free to be reused.
+            reaped = True
+        drain.join(timeout=2)
+        # Close the pipes rather than leaving them to the collector.
+        for pipe in (proc.stdout, proc.stderr):
+            try:
+                if pipe is not None:
+                    pipe.close()
+            except OSError:
+                pass
+
+    return StreamOutcome(
+        returncode=proc.returncode,
+        timed_out=timed_out.is_set(),
+        stderr_lines=stderr_lines,
+    )

nightshift/adapters/base.py

@@ -0,0 +1,171 @@
+"""The adapter contract: what nightshift needs from any AI coding CLI."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime
+from pathlib import Path
+from typing import Callable, Literal, Protocol, runtime_checkable
+
+Status = Literal["ok", "failed", "timeout", "skipped"]
+
+#: Statuses that consumed provider quota and so must hit the ledger.
+BILLED_STATUSES: frozenset[str] = frozenset({"ok", "failed", "timeout"})
+
+EventKind = Literal["start", "thinking", "text", "tool", "tool_result", "result", "error"]
+
+
+class AdapterError(Exception):
+    """A problem with an adapter itself, not with the run it attempted."""
+
+
+@dataclass
+class Event:
+    """One thing an adapter saw while a run was still in flight.
+
+    Adapters emit these only when a caller asks for them; the digest is built
+    from :class:`RunResult`, never from events. Nothing here is load-bearing —
+    dropping every event must still leave the run correct.
+    """
+
+    kind: EventKind
+    #: Assistant prose, a tool result summary, or an error message.
+    text: str = ""
+    #: Tool name, for ``tool``/``tool_result``.
+    tool: str = ""
+    #: Short rendering of tool input, e.g. ``pattern: *.py``.
+    detail: str = ""
+
+
+#: Called on the run's thread as events arrive. Must never raise.
+OnEvent = Callable[[Event], None]
+
+
+@dataclass
+class RunResult:
+    """The outcome of one (project, task) attempt.
+
+    ``skipped`` never comes from an adapter — the scheduler synthesises it when
+    a gate refuses the run, so the digest can show what did *not* happen.
+    """
+
+    provider: str
+    project: str
+    task: str
+    status: Status
+    findings_md: str
+    started_at: datetime
+    duration_s: float
+    #: Populated for skipped/failed runs; shown in the digest run log.
+    detail: str = ""
+    attempt: int = 1
+
+    def to_dict(self) -> dict:
+        return {
+            "provider": self.provider,
+            "project": self.project,
+            "task": self.task,
+            "status": self.status,
+            "findings_md": self.findings_md,
+            "started_at": self.started_at.isoformat(),
+            "duration_s": round(self.duration_s, 3),
+            "detail": self.detail,
+            "attempt": self.attempt,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict) -> RunResult:
+        return cls(
+            provider=data["provider"],
+            project=data["project"],
+            task=data["task"],
+            status=data["status"],
+            findings_md=data.get("findings_md", ""),
+            started_at=datetime.fromisoformat(data["started_at"]),
+            duration_s=float(data.get("duration_s", 0.0)),
+            detail=data.get("detail", ""),
+            attempt=int(data.get("attempt", 1)),
+        )
+
+    @property
+    def billed(self) -> bool:
+        """Did this attempt consume provider quota?"""
+        return self.status in BILLED_STATUSES
+
+
+@dataclass
+class Availability:
+    """Why an adapter can or cannot be used right now."""
+
+    ok: bool
+    reason: str = ""
+
+
+@runtime_checkable
+class Adapter(Protocol):
+    """A read-only wrapper around one AI coding CLI."""
+
+    name: str
+
+    def available(self) -> bool:
+        """Is the CLI installed, on PATH, and authenticated?"""
+        ...
+
+    def availability(self) -> Availability:
+        """Like :meth:`available`, but explains itself for ``nightshift status``."""
+        ...
+
+    def last_human_use(self) -> datetime | None:
+        """When a human last drove this CLI, or ``None`` if unknowable.
+
+        The scheduler uses this to stay out of the user's way; ``None`` is read
+        as "idle", since an adapter that cannot tell should not block runs.
+        """
+        ...
+
+    def run(
+        self,
+        prompt: str,
+        project_dir: Path,
+        timeout_s: int,
+        on_event: OnEvent | None = None,
+    ) -> RunResult:
+        """Execute ``prompt`` against ``project_dir`` read-only.
+
+        When ``on_event`` is given the adapter should report progress as it
+        happens; when it is ``None`` the adapter stays silent, which is what
+        cron wants. The :class:`RunResult` must not depend on which was used.
+        """
+        ...
+
+
+@dataclass
+class StubAdapter:
+    """Base for adapters that are documented but not yet implemented."""
+
+    name: str = "stub"
+    help_wanted_url: str = "https://github.com/kishormorol/nightshift/issues"
+
+    def available(self) -> bool:
+        return False
+
+    def availability(self) -> Availability:
+        return Availability(
+            ok=False,
+            reason=f"the {self.name} adapter is not implemented yet — help wanted: "
+            f"{self.help_wanted_url}",
+        )
+
+    def last_human_use(self) -> datetime | None:
+        return None
+
+    def run(
+        self,
+        prompt: str,
+        project_dir: Path,
+        timeout_s: int,
+        on_event: OnEvent | None = None,
+    ) -> RunResult:
+        raise NotImplementedError(
+            f"the {self.name} adapter is a documented stub — see {self.help_wanted_url}"
+        )