cheaphelp 1.0.0__py3-none-any.whl

cheaphelp/__init__.py

@@ -0,0 +1,10 @@
+"""cheaphelp package.
+
+An AI software-engineer that triages GitHub issues, plans, implements, and reviews changes on your repos using cheap OpenRouter models via the opencode harness.
+"""
+
+from __future__ import annotations
+
+from cheaphelp._internal.cli import get_parser, main
+
+__all__: list[str] = ["get_parser", "main"]

cheaphelp/__main__.py

@@ -0,0 +1,14 @@
+"""Entry-point module, in case you use `python -m cheaphelp`.
+
+Why does this file exist, and why `__main__`? For more info, read:
+
+- https://www.python.org/dev/peps/pep-0338/
+- https://docs.python.org/3/using/cmdline.html#cmdoption-m
+"""
+
+import sys
+
+from cheaphelp._internal.cli import main
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))

cheaphelp/_internal/cleanup.py

@@ -0,0 +1,111 @@
+"""Workspace maintenance: prune build clones the harness no longer needs.
+
+The orchestrator keeps two kinds of clone under ``<workspace>/clones/``:
+
+- a shared read-only clone per repo, ``<owner>__<repo>`` (reused every tick), and
+- a build clone per issue, ``<owner>__<repo>__issue-<n>`` (used while the issue is
+  being implemented).
+
+Build clones are only needed while an issue is *live* (open). Once it closes they
+are dead weight — and they are large (a full working tree each). This module
+removes build clones for closed issues, and any clone belonging to a repo that is
+no longer registered. Per-issue **state** under ``state/`` is intentionally left
+untouched so it stays available for inspection and debugging.
+"""
+
+from __future__ import annotations
+
+import shutil
+from collections.abc import Callable, Iterable
+from pathlib import Path
+
+from cheaphelp._internal.config import Workspace
+from cheaphelp._internal.lock import RunLock
+from cheaphelp._internal.registry import RepoEntry
+
+Logger = Callable[[str], None]
+
+
+def iter_issue_work_clones(workspace: Workspace, owner: str, name: str) -> dict[int, Path]:
+    """Map issue number -> build-clone path for one repo's per-issue clones.
+
+    The repo's shared clone (``<owner>__<repo>``, no ``__issue-`` suffix) is never
+    included. Matching by the known ``<owner>__<repo>__issue-`` prefix avoids the
+    ambiguity of splitting on ``__`` (repo names may contain underscores).
+    """
+    prefix = f"{owner}__{name}__issue-"
+    clones: dict[int, Path] = {}
+    if not workspace.clones_dir.exists():
+        return clones
+    for path in workspace.clones_dir.iterdir():
+        if path.is_dir() and path.name.startswith(prefix):
+            suffix = path.name[len(prefix) :]
+            if suffix.isdigit():
+                clones[int(suffix)] = path
+    return clones
+
+
+def prune_repo_work_clones(
+    workspace: Workspace,
+    repo: RepoEntry,
+    live_numbers: set[int],
+    *,
+    dry_run: bool = False,
+    log: Logger | None = None,
+) -> list[int]:
+    """Remove build clones for this repo's issues that are no longer live.
+
+    ``live_numbers`` is the set of currently-open issue numbers; any build clone for
+    an issue outside it is removed. Returns the issue numbers whose clones were
+    removed (or, in dry-run, would be).
+    """
+    log = log or (lambda _m: None)
+    removed: list[int] = []
+    for number, path in sorted(iter_issue_work_clones(workspace, repo.owner, repo.name).items()):
+        if number in live_numbers:
+            continue
+        if dry_run:
+            log(f"  · would remove build clone for {repo.slug}#{number}")
+            removed.append(number)
+            continue
+        # Guard against a concurrent tick still using this issue's clone. Closed
+        # issues are never actionable, so this should never contend in practice.
+        with RunLock(workspace.issue_lock_path(repo.owner, repo.name, number)) as lock:
+            if not lock.acquired:
+                continue
+            shutil.rmtree(path, ignore_errors=True)
+        log(f"  · removed build clone for {repo.slug}#{number}")
+        removed.append(number)
+    return removed
+
+
+def prune_orphan_clones(
+    workspace: Workspace,
+    repos: Iterable[RepoEntry],
+    *,
+    dry_run: bool = False,
+    log: Logger | None = None,
+) -> list[str]:
+    """Remove clone dirs (shared or per-issue) for repos no longer registered.
+
+    Returns the clone directory names that were removed (or would be, in dry-run).
+    """
+    log = log or (lambda _m: None)
+    if not workspace.clones_dir.exists():
+        return []
+    known = {f"{r.owner}__{r.name}" for r in repos}
+    removed: list[str] = []
+    for path in workspace.clones_dir.iterdir():
+        if not path.is_dir():
+            continue
+        # A clone belongs to a registered repo if its name equals "<owner>__<repo>"
+        # or starts with "<owner>__<repo>__issue-".
+        if any(path.name == k or path.name.startswith(f"{k}__issue-") for k in known):
+            continue
+        if dry_run:
+            log(f"  · would remove orphaned clone {path.name}")
+        else:
+            shutil.rmtree(path, ignore_errors=True)
+            log(f"  · removed orphaned clone {path.name}")
+        removed.append(path.name)
+    return removed

cheaphelp/_internal/cli.py

@@ -0,0 +1,372 @@
+# Why does this file exist, and why not put this in `__main__`?
+#
+# You might be tempted to import things from `__main__` later,
+# but that will cause problems: the code will get executed twice:
+#
+# - When you run `python -m cheaphelp` python will execute
+#   `__main__.py` as a script. That means there won't be any
+#   `cheaphelp.__main__` in `sys.modules`.
+# - When you import `__main__` it will get executed again (as a module) because
+#   there's no `cheaphelp.__main__` in `sys.modules`.
+
+from __future__ import annotations
+
+import argparse
+import sys
+from typing import Any
+
+from cheaphelp._internal import commands, debug
+
+
+class _DebugInfo(argparse.Action):
+    def __init__(self, nargs: int | str | None = 0, **kwargs: Any) -> None:
+        super().__init__(nargs=nargs, **kwargs)
+
+    def __call__(self, *args: Any, **kwargs: Any) -> None:  # noqa: ARG002
+        debug._print_debug_info()
+        sys.exit(0)
+
+
+def get_parser() -> argparse.ArgumentParser:
+    """Return the CLI argument parser.
+
+    Returns:
+        An argparse parser.
+    """
+    parser = argparse.ArgumentParser(
+        prog="cheaphelp",
+        description="An AI software-engineer for your GitHub repositories, powered by "
+        "cheap OpenRouter models via the opencode harness.",
+    )
+    parser.add_argument("-V", "--version", action="version", version=f"%(prog)s {debug._get_version()}")
+    parser.add_argument("--debug-info", action=_DebugInfo, help="Print debug information.")
+    parser.add_argument(
+        "--home",
+        metavar="DIR",
+        help="Workspace directory (default: $CHEAPHELP_HOME or ~/.cheaphelp).",
+    )
+
+    subparsers = parser.add_subparsers(dest="command", metavar="<command>")
+
+    # init
+    p_init = subparsers.add_parser("init", help="Create or update the workspace.")
+    p_init.add_argument("--github-token", help="GitHub personal access token.")
+    p_init.add_argument("--openrouter-key", help="OpenRouter API key.")
+    p_init.add_argument("--no-prompt", action="store_true", help="Never prompt for secrets.")
+    p_init.set_defaults(func=commands.cmd_init)
+
+    # repo
+    p_repo = subparsers.add_parser("repo", help="Manage registered repositories.")
+    repo_sub = p_repo.add_subparsers(dest="repo_command", metavar="<action>")
+    p_add = repo_sub.add_parser("add", help="Register a repository (owner/name).")
+    p_add.add_argument("slug", help="Repository as owner/name or a GitHub URL.")
+    p_add.add_argument(
+        "--checks",
+        default="",
+        help="Quality-gate shell command run in the clone before a PR is opened "
+        '(e.g. "ruff check . && pytest"). A failing gate sends the issue back to planning.',
+    )
+    p_add.add_argument(
+        "--autofix",
+        default="",
+        help="Shell command run in the clone before the gate to auto-fix trivial "
+        'issues (e.g. "ruff check --fix . ; ruff format ."). Changes are committed.',
+    )
+    p_add.add_argument(
+        "--max-diff-files",
+        type=int,
+        default=None,
+        metavar="N",
+        help="Maximum files allowed in a single PR for this repo (0 = unlimited, default 30).",
+    )
+    p_add.add_argument(
+        "--max-diff-lines",
+        type=int,
+        default=None,
+        metavar="N",
+        help="Maximum lines (added+removed) allowed in a single PR (0 = unlimited, default 1000).",
+    )
+    p_add.set_defaults(func=commands.cmd_repo_add)
+    p_list = repo_sub.add_parser("list", help="List registered repositories.")
+    p_list.add_argument(
+        "--json",
+        action="store_true",
+        help="Output the list of registered repositories as a JSON array.",
+    )
+    p_list.set_defaults(func=commands.cmd_repo_list)
+    p_rm = repo_sub.add_parser("remove", help="Unregister a repository.")
+    p_rm.add_argument("slug")
+    p_rm.set_defaults(func=commands.cmd_repo_remove)
+    p_set = repo_sub.add_parser(
+        "set",
+        help="Update checks/autofix on an already-registered repository.",
+    )
+    p_set.add_argument("slug", help="Repository as owner/name or a GitHub URL.")
+    p_set.add_argument(
+        "--checks",
+        default=None,
+        help="Replace the quality-gate shell command. Pass an empty string to disable the gate.",
+    )
+    p_set.add_argument(
+        "--autofix",
+        default=None,
+        help="Replace the auto-fix shell command. Pass an empty string to disable auto-fix.",
+    )
+    p_set.add_argument(
+        "--max-diff-files",
+        type=int,
+        default=None,
+        metavar="N",
+        help="Maximum files allowed in a single PR for this repo (0 = unlimited, default 30).",
+    )
+    p_set.add_argument(
+        "--max-diff-lines",
+        type=int,
+        default=None,
+        metavar="N",
+        help="Maximum lines (added+removed) allowed in a single PR (0 = unlimited, default 1000).",
+    )
+    p_set.set_defaults(func=commands.cmd_repo_set)
+    p_update = repo_sub.add_parser(
+        "update",
+        help="Update checks/autofix/max-diff-* on an already-registered repository (alias of `set`).",
+    )
+    p_update.add_argument("slug", help="Repository as owner/name or a GitHub URL.")
+    p_update.add_argument(
+        "--checks",
+        default=None,
+        help="Replace the quality-gate shell command. Pass an empty string to disable the gate.",
+    )
+    p_update.add_argument(
+        "--autofix",
+        default=None,
+        help="Replace the auto-fix shell command. Pass an empty string to disable auto-fix.",
+    )
+    p_update.add_argument(
+        "--max-diff-files",
+        type=int,
+        default=None,
+        metavar="N",
+        help="Maximum files allowed in a single PR for this repo (0 = unlimited, default 30).",
+    )
+    p_update.add_argument(
+        "--max-diff-lines",
+        type=int,
+        default=None,
+        metavar="N",
+        help="Maximum lines (added+removed) allowed in a single PR (0 = unlimited, default 1000).",
+    )
+    p_update.set_defaults(func=commands.cmd_repo_set)
+    p_en = repo_sub.add_parser("enable", help="Enable processing for a repository.")
+    p_en.add_argument("slug")
+    p_en.set_defaults(func=lambda a: commands.cmd_repo_toggle(a, enabled=True))
+    p_dis = repo_sub.add_parser("disable", help="Disable processing for a repository.")
+    p_dis.add_argument("slug")
+    p_dis.set_defaults(func=lambda a: commands.cmd_repo_toggle(a, enabled=False))
+
+    # run
+    p_run = subparsers.add_parser("run", help="Run the orchestrator. Default: one tick.")
+    p_run.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Report what would happen without acting (applies to every tick in a multi-tick run).",
+    )
+    p_run.add_argument(
+        "-n",
+        "--num-ticks",
+        type=int,
+        default=1,
+        metavar="N",
+        help="Run exactly N ticks, sleeping --sleep seconds between each (default 1). "
+        "Mutually exclusive with --continuous.",
+    )
+    p_run.add_argument(
+        "--continuous",
+        action="store_true",
+        help="Run until a tick produces no work, capped at --max-ticks. Mutually exclusive with --num-ticks.",
+    )
+    p_run.add_argument(
+        "--max-ticks",
+        type=int,
+        default=20,
+        metavar="N",
+        help="Hard cap on total ticks when --continuous is used (default 20). Ignored when --num-ticks is set.",
+    )
+    p_run.add_argument(
+        "--sleep",
+        type=float,
+        default=30.0,
+        metavar="N",
+        help="Seconds to sleep between ticks in multi-tick mode (default 30).",
+    )
+    p_run.add_argument(
+        "--max-issues",
+        type=int,
+        default=0,
+        metavar="N",
+        help=(
+            "Cap the number of issues processed per repo in this tick "
+            "(0 = unlimited, default 0). Overrides max_issues_per_tick from "
+            "config.json when > 0."
+        ),
+    )
+    p_run.set_defaults(func=commands.cmd_run)
+
+    # systemd
+    p_sys = subparsers.add_parser("systemd", help="Manage the systemd user timer.")
+    sys_sub = p_sys.add_subparsers(dest="systemd_command", metavar="<action>")
+    p_sys_install = sys_sub.add_parser("install", help="Install and start the timer.")
+    p_sys_install.add_argument(
+        "--interval",
+        default="10m",
+        help="Timer firing interval, e.g. 30s, 10m, 2h (default: 10m).",
+    )
+    p_sys_install.add_argument(
+        "--continuous",
+        action=argparse.BooleanOptionalAction,
+        default=True,
+        help=(
+            "Each timer firing runs `cheaphelp run --continuous`, draining the "
+            "backlog (repeated ticks until one is idle, capped at --max-ticks) "
+            "instead of a single tick (default: enabled). Use --no-continuous "
+            "for one tick per firing."
+        ),
+    )
+    p_sys_install.add_argument(
+        "--max-ticks",
+        type=int,
+        default=20,
+        metavar="N",
+        help="Cap on ticks per timer firing in continuous mode (default 20).",
+    )
+    p_sys_install.add_argument(
+        "--sleep",
+        type=float,
+        default=30.0,
+        metavar="N",
+        help="Seconds to sleep between ticks in continuous mode (default 30).",
+    )
+    p_sys_install.add_argument(
+        "--linger",
+        action="store_true",
+        help=(
+            "After installing the timer, run `loginctl enable-linger $USER` so the "
+            "user timer keeps firing after logout. Suppresses the lingering tip. "
+            "Failures are reported as warnings; install is not aborted."
+        ),
+    )
+    p_sys_install.set_defaults(func=commands.cmd_systemd_install)
+    sys_sub.add_parser("uninstall", help="Stop and remove the timer.").set_defaults(
+        func=commands.cmd_systemd_uninstall,
+    )
+    sys_sub.add_parser("status", help="Show timer status.").set_defaults(
+        func=commands.cmd_systemd_status,
+    )
+
+    # agents
+    p_agents = subparsers.add_parser("agents", help="Manage agent prompts and opencode config.")
+    agents_sub = p_agents.add_subparsers(dest="agents_command", metavar="<action>")
+    p_sync = agents_sub.add_parser("sync", help="Regenerate opencode.json from prompts + config.")
+    p_sync.add_argument("--force", action="store_true", help="Overwrite workspace prompts.")
+    p_sync.set_defaults(func=commands.cmd_agents_sync)
+
+    # config
+    p_config = subparsers.add_parser("config", help="View or change configuration settings.")
+    config_sub = p_config.add_subparsers(dest="config_command", metavar="<action>")
+    p_cfg_show = config_sub.add_parser("show", help="Print the effective configuration.")
+    p_cfg_show.set_defaults(func=commands.cmd_config_show)
+    p_cfg_get = config_sub.add_parser("get", help="Look up a single config value by dotted path.")
+    p_cfg_get.add_argument("key", help="Dotted path to a config key (e.g. models.worker).")
+    p_cfg_get.set_defaults(func=commands.cmd_config_get)
+    p_cfg_set = config_sub.add_parser("set", help="Set a config value by dotted path.")
+    p_cfg_set.add_argument("key", help="Dotted path to a config key (e.g. agent_timeout).")
+    p_cfg_set.add_argument("value", help="New value for the config key.")
+    p_cfg_set.set_defaults(func=commands.cmd_config_set)
+
+    # doctor
+    subparsers.add_parser("doctor", help="Check workspace, tokens and opencode.").set_defaults(
+        func=commands.cmd_doctor,
+    )
+
+    # status
+    p_status = subparsers.add_parser(
+        "status",
+        help="List open issues for each enabled repo and their pipeline stage.",
+    )
+    p_status.add_argument(
+        "--costs",
+        action="store_true",
+        help="Also show the cumulative cost per issue (read from <issue_dir>/cost.json).",
+    )
+    p_status.set_defaults(func=commands.cmd_status)
+
+    # clean
+    p_clean = subparsers.add_parser(
+        "clean",
+        help="Remove build clones for closed issues and unregistered repos (keeps state).",
+    )
+    p_clean.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Report what would be removed without deleting anything.",
+    )
+    p_clean.set_defaults(func=commands.cmd_clean)
+
+    # retry
+    p_retry = subparsers.add_parser(
+        "retry",
+        help="Un-stick an issue labeled 'needs-human' and run one orchestrator tick.",
+    )
+    p_retry.add_argument("slug", help="Repository as owner/name or a GitHub URL.")
+    p_retry.add_argument("number", type=int, help="Issue number to retry.")
+    p_retry.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Report the planned actions without making API or filesystem changes.",
+    )
+    p_retry.add_argument(
+        "-y",
+        "--yes",
+        action="store_true",
+        help="Skip the confirmation prompt.",
+    )
+    p_retry.set_defaults(func=commands.cmd_retry)
+
+    # logs
+    p_logs = subparsers.add_parser("logs", help="Show recent run activity, or follow it live.")
+    p_logs.add_argument(
+        "--follow",
+        "-f",
+        action="store_true",
+        help="Stream new log lines as they are appended (Ctrl-C to stop).",
+    )
+    p_logs.add_argument(
+        "--issue",
+        type=int,
+        metavar="N",
+        help="Show only lines that reference issue #N.",
+    )
+    p_logs.set_defaults(func=commands.cmd_logs)
+
+    return parser
+
+
+def main(args: list[str] | None = None) -> int:
+    """Run the main program.
+
+    This function is executed when you type `cheaphelp` or `python -m cheaphelp`.
+
+    Parameters:
+        args: Arguments passed from the command line.
+
+    Returns:
+        An exit code.
+    """
+    parser = get_parser()
+    opts = parser.parse_args(args=args)
+
+    func = getattr(opts, "func", None)
+    if func is None:
+        parser.print_help()
+        return 1
+    return func(opts)