aicp-cli 0.3.0__py3-none-any.whl

aicp/notify.py

@@ -0,0 +1,87 @@
+"""The injected notifier — Telegram when it is there, a printed line when not.
+
+Port of ``_aicp_notify`` in ``~/scripts/bin/aicp``. Telegram lives in a
+different project (``$HOME/.claude``), so it is strictly optional: without it
+the same text is printed instead of being sent, and aicp keeps working for
+anyone who only has this repo.
+
+:func:`notify` is the real implementation behind ``contracts.NotifyFn`` — it
+is passed INTO the runner at the CLI entry point, never imported by it, so
+the runner stays free of any network or subprocess dependency. Two
+consequences are deliberate:
+
+* **Nothing raises out of here.** A notification is the last step of a run
+  that has usually already succeeded; a missing script, an unreadable path, a
+  non-zero exit or a killed child all degrade to the printed line.
+* **The script path comes from the environment only**, resolved per call.
+  ``AICP_TG_SEND`` is never read from ``.aicprc``: a config file is a
+  checked-in, shareable artifact, and a path in it would be an arbitrary
+  program this module then executes.
+"""
+
+from __future__ import annotations
+
+import os
+import subprocess
+from pathlib import Path
+
+from ._utils import DIM, RESET, have
+from .i18n import t
+
+__all__ = ["notify", "tg_send_script"]
+
+# Seconds the send script gets before it is killed and the printed line takes
+# over. A notification is the last step of a run that has usually already
+# committed and pushed, so an unbounded wait here holds the whole run hostage
+# to a hung network call — the exact opposite of the "degrades to a printed
+# line" promise in this module's docstring. Generous enough for a real
+# Telegram round trip, short enough that nobody watches a dead terminal.
+SEND_TIMEOUT = 15.0
+
+
+def tg_send_script() -> Path:
+    """``$AICP_TG_SEND``, else ``$HOME/.claude/scripts/tg-send.sh``."""
+    override = os.environ.get("AICP_TG_SEND")
+    if override:
+        return Path(override)
+    return Path.home() / ".claude" / "scripts" / "tg-send.sh"
+
+
+def _send(message: str) -> bool:
+    script = tg_send_script()
+    try:
+        if not script.is_file():
+            return False
+        # tg-send.sh is a bash script; run it under bash the way the zsh
+        # original does, falling back to executing it directly where bash is
+        # not on PATH (a Windows box without Git Bash).
+        cmd = (
+            ["bash", str(script), "send", message]
+            if have("bash")
+            else [str(script), "send", message]
+        )
+        done = subprocess.run(
+            cmd,
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+            check=False,
+            timeout=SEND_TIMEOUT,
+        )
+    except (OSError, subprocess.TimeoutExpired):
+        # A hung script degrades exactly like a missing one: subprocess.run has
+        # already killed and reaped it by the time TimeoutExpired is raised, so
+        # nothing is left running and the caller gets the printed line.
+        return False
+    return done.returncode == 0
+
+
+def notify(message: str) -> None:
+    """Send *message*, or say out loud that it could not be sent.
+
+    The NotifyFn the CLI entry point wires into the runner. Never raises, and
+    never prints the message itself on the failure path — only that the send
+    did not happen.
+    """
+    if _send(message):
+        return
+    print(f"{DIM}" + t("telegram_unavailable", "(telegram unavailable — message not sent)") + RESET)

aicp/present.py

@@ -0,0 +1,303 @@
+"""Terminal presentation: the spinner animation and the framed panel/table
+renderer, ported from ``~/scripts/lib/spinner.sh`` and
+``~/scripts/lib/box_render.py``.
+
+Pure Python, no subprocess: the zsh original shells out to ``box_render.py``
+once per render (a real, measured fork cost per panel drawn); this port pays
+that cost once, at import, and never again.
+
+Both pieces are TTY/``NO_COLOR``-gated the same way the shell/Python
+originals were: the spinner animation only draws when stderr is a TTY and
+``NO_COLOR`` is unset, falling back to ASCII frames off a UTF-8 locale.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import subprocess
+import sys
+import threading
+import unicodedata
+from collections.abc import Sequence
+from pathlib import Path
+
+from ._utils import BOLD, DIM, RESET
+from .i18n import t
+
+__all__ = [
+    "Spinner",
+    "render",
+    "render_panel",
+    "render_table",
+    "spinner_capture",
+    "spinner_enabled",
+    "spinner_run",
+    "width",
+]
+
+# ── spinner (lib/spinner.sh port) ────────────────────────────────────────────
+
+_FRAMES_BRAILLE = ("⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏")
+_FRAMES_ASCII = ("|", "/", "-", "\\")
+_SPINNER_INTERVAL = 0.08
+_SPINNER_COLOR = "\033[38;5;87m"
+
+
+def spinner_enabled(stream=None) -> bool:
+    """True when the animation should be drawn: *stream* (default stderr) is
+    a TTY and ``NO_COLOR`` is unset — the same gate the shell original uses."""
+    stream = stream if stream is not None else sys.stderr
+    try:
+        if not stream.isatty():
+            return False
+    except Exception:  # noqa: BLE001 - a stream with no working isatty() is never a TTY
+        return False
+    return not os.environ.get("NO_COLOR")
+
+
+def _locale_is_utf8() -> bool:
+    """Braille needs a UTF-8-capable locale; anything else gets ASCII frames.
+
+    Checked in the same precedence as the shell original: LC_ALL, then
+    LC_CTYPE, then LANG.
+    """
+    value = os.environ.get("LC_ALL") or os.environ.get("LC_CTYPE") or os.environ.get("LANG") or ""
+    return "utf-8" in value.lower() or "utf8" in value.lower()
+
+
+def _frames() -> tuple[str, ...]:
+    return _FRAMES_BRAILLE if _locale_is_utf8() else _FRAMES_ASCII
+
+
+class Spinner:
+    """Animate a message on stderr until stopped. Disabled (a no-op) when
+    :func:`spinner_enabled` is False — matching spinner.sh's TTY/NO_COLOR gate.
+
+    Usage::
+
+        spinner = Spinner("Fetching…")
+        spinner.start()
+        ...
+        spinner.stop()
+
+    or as a context manager: ``with Spinner("Fetching…"): ...``.
+    """
+
+    def __init__(self, message: str = "Working…", *, stream=None) -> None:
+        self._message = message
+        self._stream = stream if stream is not None else sys.stderr
+        self._enabled = spinner_enabled(self._stream)
+        self._frames = _frames()
+        self._stop_event = threading.Event()
+        self._thread: threading.Thread | None = None
+        self._lock = threading.Lock()
+
+    @property
+    def enabled(self) -> bool:
+        return self._enabled
+
+    def update(self, message: str) -> None:
+        with self._lock:
+            self._message = message
+
+    def _run(self) -> None:
+        i = 0
+        n = len(self._frames)
+        while not self._stop_event.is_set():
+            with self._lock:
+                message = self._message
+            frame = self._frames[i % n]
+            self._stream.write(f"\r{_SPINNER_COLOR}{frame}{RESET} {message}\033[K")
+            self._stream.flush()
+            i += 1
+            self._stop_event.wait(_SPINNER_INTERVAL)
+        self._stream.write("\r\033[K")
+        self._stream.flush()
+
+    def start(self) -> None:
+        if not self._enabled:
+            return
+        self.stop()  # matches spinner_start's own leading spinner_stop
+        self._stop_event.clear()
+        self._thread = threading.Thread(target=self._run, daemon=True)
+        self._thread.start()
+
+    def stop(self) -> None:
+        if self._thread is None:
+            return
+        self._stop_event.set()
+        self._thread.join()
+        self._thread = None
+
+    def __enter__(self) -> Spinner:  # noqa: PYI034 - Self needs 3.11+; this package supports 3.10
+        self.start()
+        return self
+
+    def __exit__(self, *exc_info: object) -> None:
+        self.stop()
+
+
+def spinner_run(message: str, cmd: Sequence[str], **kwargs) -> subprocess.CompletedProcess[str]:
+    """Animate *message* while *cmd* runs; relay its exit status.
+
+    Port of spinner.sh's ``spinner_run``. Output is inherited (not captured) —
+    use :func:`spinner_capture` to redirect it to a log instead.
+    """
+    spinner = Spinner(message)
+    spinner.start()
+    check = kwargs.pop("check", False)
+    try:
+        return subprocess.run(cmd, check=check, **kwargs)
+    finally:
+        spinner.stop()
+
+
+def spinner_capture(
+    logfile: str | Path, message: str, cmd: Sequence[str], **kwargs
+) -> subprocess.CompletedProcess[str]:
+    """Animate *message* while *cmd* runs, sending its combined stdout/stderr
+    to *logfile* instead of the screen. Port of spinner.sh's ``spinner_capture``.
+    """
+    spinner = Spinner(message)
+    spinner.start()
+    check = kwargs.pop("check", False)
+    try:
+        with open(logfile, "w", encoding="utf-8") as handle:
+            return subprocess.run(
+                cmd, stdout=handle, stderr=subprocess.STDOUT, check=check, **kwargs
+            )
+    finally:
+        spinner.stop()
+
+
+# ── box render (lib/box_render.py port) ──────────────────────────────────────
+
+FRAME = "\033[38;5;240m"
+HEADER = "\033[48;5;238;38;5;255m"
+STRIPE = "\033[48;5;235;38;5;252m"
+# Resolved at import like every other message: the column widths below are
+# measured from it, and a table cannot re-measure itself mid-run.
+VALUE_HEADER = t("panel_value_header", "VALUE")
+
+_ANSI = re.compile(r"\033\[[0-9;]*m")
+
+
+def width(text: str) -> int:
+    """Visible columns of *text*: ANSI escapes stripped, East-Asian
+    Wide/Fullwidth glyphs count two columns, combining marks count none."""
+    return sum(
+        0 if unicodedata.combining(ch) else 2 if unicodedata.east_asian_width(ch) in "WF" else 1
+        for ch in _ANSI.sub("", text)
+    )
+
+
+def _reband(text: str, band: str) -> str:
+    """*text* with *band* re-armed after every RESET it embeds — a colored
+    cell ends in RESET, which clears the background too; without re-arming, a
+    banded row would lose its stripe from that cell onward."""
+    return text.replace(RESET, RESET + band) if band else text
+
+
+def render_panel(
+    rows: Sequence[tuple[str, str]],
+    title: str,
+    accent: str,
+    zebra: bool = False,
+    notes: Sequence[str] = (),
+) -> list[str]:
+    """Render *rows* (label, value pairs) as a titled rounded-frame panel.
+
+    ``zebra`` shades every other row full-width; a single-row panel never
+    bands (nothing to alternate against). ``notes`` are extra full-width,
+    already-colored lines drawn inside the same frame below the rows (a blank
+    separator first, then one line per note) — for content that isn't a
+    (label, value) pair, such as the config menu's per-row help text and its
+    key-hint footer. A row whose ``value`` is empty is a section heading
+    (e.g. the config menu's "Steps"/"General"/"Tools" groups) — bold, then a
+    dim rule out to the frame, spanning the full width instead of sharing the
+    label/value columns. Weight and the rule carry the separation, not a
+    fifth hue: bold against DIM labels reads as a heading at a glance, while
+    CYAN/GREEN/MAGENTA stay free to mean what a *value* means elsewhere (a
+    changeable setting, a state, the repo name), and the frame's own colour
+    stays chrome. Bold on the terminal's default foreground — the same
+    treatment as *title* — rather than a hardcoded white, so the heading
+    survives a light-background theme.
+    """
+    label_w = max(width(k) for k, v in rows if v)
+    value_w = max((width(v) for _, v in rows if v), default=0)
+    inner = max(
+        label_w + value_w + 6,
+        width(title) + 3,
+        *(width(n) + 4 for n in notes),
+        *(width(k) + 4 for k, v in rows if not v),
+    )
+    dashes = inner - width(title) - 3
+    out = [f"{accent}╭─ {BOLD}{title}{RESET}{accent} {'─' * dashes}╮{RESET}"]
+    for i, (label, value) in enumerate(rows):
+        if not value:
+            rule = max(inner - 4 - width(label), 0)
+            tail = f" {DIM}{'─' * rule}{RESET} " if rule else " " * (inner - 2 - width(label))
+            out.append(f"{accent}│{RESET}  {BOLD}{label}{RESET}{tail}{accent}│{RESET}")
+            continue
+        pad = " " * (label_w - width(label))
+        vpad = " " * (value_w - width(value))
+        trail = " " * (inner - 4 - label_w - value_w)
+        content = f"  {DIM}{label}{pad}{RESET}  {value}{vpad}{trail}"
+        band = STRIPE if (zebra and len(rows) > 1 and i % 2) else ""
+        body = f"{band}{_reband(content, band)}{RESET}" if band else content
+        out.append(f"{accent}│{RESET}{body}{accent}│{RESET}")
+    if notes:
+        out.append(f"{accent}│{RESET}{' ' * inner}{accent}│{RESET}")
+        for note in notes:
+            pad = " " * (inner - 2 - width(note))
+            out.append(f"{accent}│{RESET}  {note}{pad}{accent}│{RESET}")
+    out.append(f"{accent}╰{'─' * inner}╯{RESET}")
+    return out
+
+
+def render_table(rows: Sequence[tuple[str, str]], title: str) -> list[str]:
+    """Render *rows* (label, value pairs) as a two-column table with a
+    banded header row and zebra-striped body rows."""
+    widths = [
+        max(width(title), *(width(k) for k, _ in rows)),
+        max(width(VALUE_HEADER), *(width(v) for _, v in rows)),
+    ]
+
+    def rule(left: str, mid: str, right: str) -> str:
+        return FRAME + left + mid.join("─" * (w + 2) for w in widths) + right + RESET
+
+    def row(cells: Sequence[str], band: str = "") -> str:
+        parts = [
+            f" {_reband(c, band)}{' ' * max(w - width(c), 0)} " for c, w in zip(cells, widths)
+        ]
+        edge = f"{FRAME}│{RESET}"
+        if not band:
+            return edge + edge.join(parts) + edge
+        return f"{edge}{band}{(FRAME + '│' + band).join(parts)}{RESET}{edge}"
+
+    return [
+        rule("╭", "┬", "╮"),
+        row([f"{BOLD}{title}{RESET}", f"{BOLD}{VALUE_HEADER}{RESET}"], HEADER),
+        rule("├", "┼", "┤"),
+        *(row([k, v], STRIPE if i % 2 else "") for i, (k, v) in enumerate(rows)),
+        rule("╰", "┴", "╯"),
+    ]
+
+
+def render(
+    rows: Sequence[tuple[str, str]],
+    title: str,
+    *,
+    mode: str = "table",
+    accent: str = FRAME,
+    zebra: bool = False,
+) -> list[str]:
+    """Dispatch to :func:`render_panel`/:func:`render_table`, drawing nothing
+    for empty *rows* — the single entry point callers should use (mirrors
+    ``box_render.py``'s CLI, which exits 0 with no output for empty stdin,
+    rather than calling the two renderers directly and having to remember
+    the empty-input guard themselves)."""
+    if not rows:
+        return []
+    return render_panel(rows, title, accent, zebra) if mode == "panel" else render_table(rows, title)

aicp/quota.py

@@ -0,0 +1,115 @@
+"""Cross-run quota cooldown: ``{"<cli>": <expiry epoch>}`` in ``~/.aicp/quota.json``.
+
+:attr:`aicp.runner.StepResult.quota_clis` excludes an exhausted CLI for the rest
+of ONE run. That is too short: a token/rate-limit wall usually stands for hours,
+so every later run walked into it again and paid a full budget per step for a CLI
+that could not succeed. This module is the persistent half — a CLI that reported
+a supported quota signal is skipped until its window expires.
+
+Deliberately its OWN file rather than a key in ``state.json``:
+:func:`aicp.skills._save_state` rewrites that file as ``{"version", "skills"}``
+and would drop anything else at the top level, and :mod:`aicp.runner` imports no
+sibling feature module (see its docstring), which rules out reaching for the
+skills installer's reader. A peer of ``timing.log`` in aicp's own directory keeps
+both properties.
+
+The window is ``AICP_QUOTA_COOLDOWN`` seconds. ``0`` switches the feature off
+entirely — the escape hatch for a CLI wrongly sidelined — and any value that is
+not a plain integer in ``(0, _MAX_COOLDOWN]`` falls back to :data:`DEFAULT_COOLDOWN`,
+which is :mod:`aicp.budget`'s posture: a bad config value never bricks aicp.
+
+Nothing here is ever allowed to break a run. A missing, corrupt or unwritable
+file reads as "no cooldowns", so the worst a failure can cost is one wasted CLI
+invocation — never a changed exit code, and never a blocked commit.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import time
+from pathlib import Path
+
+__all__ = ["DEFAULT_COOLDOWN", "cooldown_seconds", "cooling", "quota_path", "record"]
+
+#: One hour. Short on purpose: over-skipping sidelines a CLI that has already
+#: recovered, while under-skipping costs a single wasted invocation, so the
+#: asymmetry favors erring short and self-healing fast.
+DEFAULT_COOLDOWN = 3600
+
+#: A week. A cooldown longer than any real quota window is almost certainly a
+#: typo, and accepting it would sideline a CLI for good with nothing on screen
+#: to explain why.
+_MAX_COOLDOWN = 7 * 24 * 3600
+
+
+def quota_path() -> Path:
+    """``~/.aicp/quota.json`` — beside ``timing.log``, never in a CLI's own dir."""
+    return Path.home() / ".aicp" / "quota.json"
+
+
+def cooldown_seconds() -> int:
+    """The configured window: ``0`` (disabled), else 1..:data:`_MAX_COOLDOWN`."""
+    raw = os.environ.get("AICP_QUOTA_COOLDOWN")
+    if raw is None:
+        return DEFAULT_COOLDOWN
+    try:
+        value = int(raw)
+    except ValueError:
+        return DEFAULT_COOLDOWN
+    if value == 0:
+        return 0
+    return value if 0 < value <= _MAX_COOLDOWN else DEFAULT_COOLDOWN
+
+
+def _expiry(value: object) -> float | None:
+    """*value* as an epoch, or None if the file holds something else there.
+
+    ``isinstance(True, int)`` is true in Python, so a JSON ``true`` would other-
+    wise read as the epoch 1 and count as a (long-expired) entry.
+    """
+    if isinstance(value, bool) or not isinstance(value, (int, float)):
+        return None
+    return float(value)
+
+
+def _load(path: Path) -> dict[str, object]:
+    """Every recorded cooldown. Missing/corrupt/unreadable all mean "none"."""
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, UnicodeDecodeError, json.JSONDecodeError):
+        return {}
+    return data if isinstance(data, dict) else {}
+
+
+def cooling(cli: str, *, path: Path | None = None, now: float | None = None) -> int:
+    """Seconds left on *cli*'s cooldown, or 0 if it is free to run."""
+    if cooldown_seconds() <= 0:
+        return 0
+    expiry = _expiry(_load(path or quota_path()).get(cli))
+    if expiry is None:
+        return 0
+    return max(0, int(expiry - (time.time() if now is None else now)))
+
+
+def record(cli: str, *, path: Path | None = None, now: float | None = None) -> None:
+    """Start *cli*'s cooldown, pruning expired entries. Never raises."""
+    window = cooldown_seconds()
+    if window <= 0:
+        return
+    stamp = time.time() if now is None else now
+    target = path or quota_path()
+    try:
+        target.parent.mkdir(parents=True, exist_ok=True)
+        live = {
+            name: expiry
+            for name, value in _load(target).items()
+            if (expiry := _expiry(value)) is not None and expiry > stamp
+        }
+        live[cli] = int(stamp + window)
+        # A plain write, not the atomic replace state.json needs: a torn file
+        # already reads as "no cooldowns" via _load, so the guard that makes a
+        # corrupt file harmless makes atomicity buy nothing on top.
+        target.write_text(json.dumps(live, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+    except OSError:
+        return