aicp-cli 0.3.0__py3-none-any.whl

aicp/_utils.py

@@ -0,0 +1,183 @@
+"""Cross-platform helpers shared across aicp — macOS, Linux, Windows.
+
+Patterns (platform flags, ANSI/Windows VT enabling, ``have()``) mirror
+``~/Documents/Workspace/ai-accounts``'s ``src/ai_accounts/_utils.py`` so the
+two projects feel like one family; nothing is imported across the two repos,
+each ships its own copy (same posture the zsh original documents for
+``lib/spinner.sh`` and ``lib/box_render.py``).
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+import signal
+import subprocess
+import sys
+from pathlib import Path
+
+IS_WINDOWS = sys.platform == "win32"
+IS_MACOS = sys.platform == "darwin"
+IS_LINUX = sys.platform.startswith("linux")
+
+BOLD = "\033[1m"
+DIM = "\033[2m"
+RESET = "\033[0m"
+GREEN = "\033[38;5;82m"
+YELLOW = "\033[38;5;220m"
+RED = "\033[38;5;203m"
+CYAN = "\033[38;5;87m"
+MAGENTA = "\033[38;5;213m"
+BLUE = "\033[38;5;75m"
+
+
+def _enable_windows_ansi() -> bool:
+    """Turn on virtual-terminal processing so ANSI escapes render on Windows.
+
+    No-op (returns True) on non-Windows. On modern Windows 10+ consoles this
+    flips ENABLE_VIRTUAL_TERMINAL_PROCESSING for both stdout and stderr.
+    """
+    if not IS_WINDOWS:
+        return True
+    try:
+        import ctypes
+
+        kernel32 = ctypes.windll.kernel32  # type: ignore[attr-defined]
+        ENABLE_VT = 0x0004
+        ok = False
+        for std_handle in (-11, -12):  # STD_OUTPUT_HANDLE, STD_ERROR_HANDLE
+            handle = kernel32.GetStdHandle(std_handle)
+            if handle in (0, -1):
+                continue
+            mode = ctypes.c_uint32()
+            if not kernel32.GetConsoleMode(handle, ctypes.byref(mode)):
+                continue
+            if kernel32.SetConsoleMode(handle, mode.value | ENABLE_VT):
+                ok = True
+        return ok
+    except Exception:  # noqa: BLE001 - best-effort VT enable, any ctypes failure means "no"
+        return False
+
+
+# Enable VT once at import time so ANSI output renders on Windows terminals.
+_WIN_ANSI_OK = _enable_windows_ansi()
+
+
+def color_supported(stream=None) -> bool:
+    """Whether ANSI color/animation should be drawn on *stream* (default stderr)."""
+    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
+    if os.environ.get("NO_COLOR"):
+        return False
+    if IS_WINDOWS:
+        return _WIN_ANSI_OK or bool(os.environ.get("WT_SESSION"))
+    return True
+
+
+def have(cmd: str) -> bool:
+    """True if *cmd* resolves to an executable on PATH."""
+    return shutil.which(cmd) is not None
+
+
+def home_config_dir(env_var: str, default: Path) -> Path:
+    """Resolve a config path: ``$<env_var>`` override, else *default*."""
+    override = os.environ.get(env_var)
+    return Path(override) if override else default
+
+
+# ── interruptible subprocess ─────────────────────────────────────────────────
+#
+# The zsh original's ``_aicp_timeout`` wraps every CLI invocation with GNU
+# `timeout --foreground` specifically so Ctrl+C reaches the child directly:
+# without --foreground, `timeout` puts the child in a NEW process group, and
+# the terminal only delivers SIGINT to the FOREGROUND process group — so the
+# signal never reached the CLI, the CLI never exited, and the whole script
+# hung waiting on it (a real, previously-observed bug, not a theoretical one;
+# see the long comment above `_aicp_timeout` in bin/aicp). The documented cost
+# there is that a timeout then only signals the CLI itself, not any
+# grandchildren it spawned — an interruptible Ctrl+C is worth more than
+# reaping those.
+#
+# run_interruptible reproduces the same posture without shelling out to GNU
+# timeout at all:
+#   POSIX    the child is placed in THIS process's own process group (i.e. no
+#            new group is created for it — the same effect --foreground
+#            achieves), so Ctrl+C at the terminal reaches it directly, same as
+#            if it had been run with no wrapper at all.
+#   Windows  there is no equivalent "foreground process group" concept.
+#            CREATE_NEW_PROCESS_GROUP lets this process forward an interrupt to
+#            just the child WITHOUT also killing itself (plain Ctrl+C on
+#            Windows targets every process attached to the same console) — but
+#            that means the child does NOT receive the console's own Ctrl+C
+#            directly; the caller must catch KeyboardInterrupt and forward the
+#            event itself. The event sent is CTRL_BREAK_EVENT, not
+#            CTRL_C_EVENT: Win32's GenerateConsoleCtrlEvent (what
+#            Popen.send_signal calls under the hood) documents that
+#            CTRL_C_EVENT CANNOT target a specific, non-zero process group —
+#            the call reports success but the child is never actually
+#            signaled — while CTRL_BREAK_EVENT can. This is an honest
+#            limitation, not a full port of the POSIX behavior: a child that
+#            ignores CTRL_BREAK_EVENT (or is a console subsystem app with no
+#            handler installed), or that treats CTRL_BREAK as an unconditional
+#            kill rather than a graceful one (a real difference from Ctrl+C,
+#            which most well-behaved CLIs treat as cancellable), will not stop
+#            cleanly, and there is no equivalent of --foreground's direct
+#            delivery. Callers on Windows needing a hard kill should follow up
+#            with Popen.terminate()/kill() rather than assume the event lands.
+def run_interruptible(cmd, **kwargs) -> subprocess.CompletedProcess[str]:
+    """Run *cmd* so Ctrl+C reaches it directly (POSIX) or can be forwarded
+    (Windows), returning a ``subprocess.CompletedProcess`` like
+    ``subprocess.run`` would.
+
+    T2 layers a timeout and a kill-after grace period on top of this (its own
+    fallback-chain budget per CLI); T4 uses it bare for slow, uninterruptible
+    calls like ``git fetch``. Extra ``**kwargs`` are passed through to
+    ``subprocess.Popen`` unchanged (e.g. ``cwd``, ``env``, ``stdout``).
+    """
+    kwargs.setdefault("text", True)
+    if IS_WINDOWS:
+        kwargs["creationflags"] = kwargs.get("creationflags", 0) | subprocess.CREATE_NEW_PROCESS_GROUP
+        with subprocess.Popen(cmd, **kwargs) as proc:
+            try:
+                stdout, stderr = proc.communicate()
+            except KeyboardInterrupt:
+                try:
+                    # CTRL_C_EVENT cannot target a specific process group (Win32
+                    # would report success while never actually signaling the
+                    # child) — CTRL_BREAK_EVENT is the one that can. See the
+                    # module comment above for the full explanation.
+                    proc.send_signal(signal.CTRL_BREAK_EVENT)  # type: ignore[attr-defined]
+                except Exception:  # noqa: BLE001 - CTRL_BREAK_EVENT delivery can fail many ways; fall back to a hard terminate
+                    proc.terminate()
+                stdout, stderr = proc.communicate()
+                raise
+            except BaseException:
+                proc.kill()
+                raise
+        return subprocess.CompletedProcess(cmd, proc.returncode, stdout, stderr)
+
+    # POSIX: start_new_session=False (the default) keeps the child in this
+    # process's own process group — no new group is created for it, so the
+    # terminal's SIGINT (delivered to the whole foreground process group)
+    # reaches the child the same way it would with no wrapper at all. This is
+    # the direct equivalent of GNU `timeout --foreground`.
+    # `with Popen(...)` plus a kill on any unhandled exception, the way
+    # subprocess.run itself does it: between spawn and wait, anything escaping
+    # that is NOT the interrupt handled below would otherwise leave a live
+    # child behind with nobody left to reap it.
+    with subprocess.Popen(cmd, **kwargs) as proc:
+        try:
+            stdout, stderr = proc.communicate()
+        except KeyboardInterrupt:
+            # The child already received the same SIGINT (same process group);
+            # wait for it to unwind rather than second-guessing it with a kill.
+            stdout, stderr = proc.communicate()
+            raise
+        except BaseException:
+            proc.kill()
+            raise
+    return subprocess.CompletedProcess(cmd, proc.returncode, stdout, stderr)

aicp/budget.py

@@ -0,0 +1,158 @@
+"""Per-CLI timeout budget: a floor that grows with the diff, widened by history.
+
+Port of ``_aicp_budget``/``_aicp_history_budget`` in ``~/scripts/bin/aicp``.
+
+    floor     AICP_TIMEOUT_BASE      covers cold start plus a small prompt
+    growth    AICP_TIMEOUT_PER_FILE  per changed or untracked file
+              AICP_TIMEOUT_PER_100L  per 100 changed lines in tracked files
+    ceiling   AICP_TIMEOUT_MAX       so a real hang is still caught
+    override  AICP_STEP_TIMEOUT      pins the budget, skipping formula AND history
+
+The budget is computed per CLI, inside the fallback loop rather than once above
+it, so a fast CLI's own history never inflates a slow CLI's budget. History may
+only WIDEN the budget above the formula, never shrink it below — and the
+widened value is deliberately NOT re-capped at ``AICP_TIMEOUT_MAX``: that
+ceiling exists to bound the no-history default, while a recorded successful run
+is direct evidence this CLI legitimately needs that long.
+
+Every value is validated as a plain non-negative integer before any arithmetic.
+A malformed value falls back to :data:`FLOOR` with a stated note instead of
+crashing: a bad value in a config file would otherwise brick aicp in every repo
+on the machine, not just the one invocation that set it.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+
+from aicp import timing
+from aicp.i18n import t
+
+__all__ = ["FLOOR", "Budget", "compute"]
+
+FLOOR = 180  # the zsh original's own documented AICP_TIMEOUT_BASE default
+
+_DEFAULTS = {
+    "AICP_TIMEOUT_BASE": 180,
+    "AICP_TIMEOUT_PER_FILE": 15,
+    "AICP_TIMEOUT_PER_100L": 5,
+    "AICP_TIMEOUT_MAX": 1800,
+}
+
+_INT = re.compile(r"^[0-9]+$")  # zsh's <->; str.isdigit() would accept "²"
+
+
+@dataclass(frozen=True)
+class Budget:
+    """Seconds allowed for one CLI invocation, plus the note explaining it."""
+
+    seconds: int
+    note: str
+
+
+def _env(name: str, default: str) -> str:
+    """*name*'s value, treating exported-but-EMPTY as unset.
+
+    zsh sets every knob with ``: "${AICP_TIMEOUT_BASE:=180}"``, and ``:=``
+    substitutes the default for an unset **or empty** variable — so
+    ``AICP_TIMEOUT_BASE=""`` computes a real formula there rather than being
+    reported as a bad value. ``os.environ.get`` alone would not.
+    """
+    raw = os.environ.get(name)
+    return default if raw is None or raw == "" else raw
+
+
+def _int_env(name: str) -> int | None:
+    """The knob as an int, or None if it is set to something non-numeric."""
+    raw = _env(name, str(_DEFAULTS[name]))
+    return int(raw) if _INT.match(raw) else None
+
+
+def _git_count(args: list[str], cwd: Path | None) -> str:
+    try:
+        done = subprocess.run(
+            ["git", *args], cwd=cwd, capture_output=True, text=True, timeout=30, check=False
+        )
+    except (OSError, subprocess.SubprocessError):
+        return ""
+    return done.stdout if done.returncode == 0 else ""
+
+
+def _pending(cwd: Path | None) -> tuple[int, int]:
+    """``(changed files, changed lines)`` per git, or ``(0, 0)`` if it can't say."""
+    files = len(_git_count(["status", "--porcelain"], cwd).splitlines())
+    lines = 0
+    for row in _git_count(["diff", "HEAD", "--numstat"], cwd).splitlines():
+        added, _, rest = row.partition("\t")
+        deleted = rest.partition("\t")[0]
+        # Binary files report "-" for both counts; awk read those as 0 too.
+        lines += sum(int(n) for n in (added, deleted) if _INT.match(n))
+    return files, lines
+
+
+def _history(cli: str) -> int:
+    """This CLI's largest successful run, multiplied out — 0 if there is none."""
+    raw_lines = _env("AICP_TIMEOUT_HISTORY_LINES", "500")
+    lines = int(raw_lines) if _INT.match(raw_lines) else 0
+    try:
+        mult = float(_env("AICP_TIMEOUT_HISTORY_MULT", "1.3"))
+    except ValueError:
+        return 0  # unusable multiplier: no widening, same as no history at all
+    best = timing.max_ok_seconds(cli, lines=lines)
+    if best <= 0:
+        return 0
+    try:
+        # `(max * mult) + 0.999999` truncated — the zsh/awk expression, i.e. ceil.
+        widened = int(best * mult + 0.999999)
+    except (OverflowError, ValueError):
+        # float() accepts "inf"/"1e400"/"nan" without raising above, and the
+        # product then has no integer form at all. The zsh original gates the
+        # awk result the same way afterwards -- `[[ "$history" == <-> ]] ||
+        # history=0` -- rather than trusting the computation; a value settable
+        # from .aicprc must never be able to crash aicp in every repo on the
+        # machine, which is this module's stated no-crash invariant.
+        return 0
+    return max(widened, 0)
+
+
+def compute(cli: str, *, cwd: Path | None = None) -> Budget:
+    """The seconds *cli* gets for one step, and the note shown beside it."""
+    pinned = os.environ.get("AICP_STEP_TIMEOUT")
+    if pinned:
+        if _INT.match(pinned):
+            return Budget(int(pinned), t("budget_note_fixed", "fixed"))
+        return Budget(
+            FLOOR, t("budget_note_bad_step", "bad AICP_STEP_TIMEOUT — using floor")
+        )
+
+    knobs = {name: _int_env(name) for name in _DEFAULTS}
+    if any(value is None for value in knobs.values()):
+        return Budget(
+            FLOOR, t("budget_note_bad_env", "bad AICP_TIMEOUT_* value — using floor")
+        )
+
+    files, lines = _pending(cwd)
+    formula = (
+        knobs["AICP_TIMEOUT_BASE"]
+        + knobs["AICP_TIMEOUT_PER_FILE"] * files
+        + knobs["AICP_TIMEOUT_PER_100L"] * lines // 100
+    )
+    formula = min(formula, knobs["AICP_TIMEOUT_MAX"])
+
+    history = _history(cli)
+    if history > formula:
+        return Budget(
+            history,
+            t(
+                "budget_note_history",
+                "%s files · %s lines · history %ss",
+                files,
+                lines,
+                history,
+            ),
+        )
+    return Budget(formula, t("budget_note_plain", "%s files · %s lines", files, lines))