devex-cli 0.24.0__py3-none-any.whl

agent_experience/commands/pr/scripts/delta.py

@@ -0,0 +1,84 @@
+"""`agex pr delta` — sibling project alignment dump."""
+
+from __future__ import annotations
+
+from importlib.resources import files
+from pathlib import Path
+
+import yaml
+
+from agent_experience.commands.pr.assets.rules.next_step_rules import delta_next_step
+from agent_experience.commands.pr.scripts._footer import render_footer
+from agent_experience.core import config as cfg_mod
+from agent_experience.core.backend import resolve_backend
+from agent_experience.core.prog import prog_name
+from agent_experience.core.render import render_string
+
+_TEMPLATES_PKG = "agent_experience.commands.pr.assets.templates"
+_DEFAULT_CLAUDE_MD_LINES = 50
+
+
+def _load_siblings(project_dir: Path) -> list[Path] | None:
+    skills_local = project_dir / ".claude" / "skills.local.yaml"
+    if not skills_local.exists():
+        return None
+    data = yaml.safe_load(skills_local.read_text(encoding="utf-8")) or {}
+    raw = data.get("sibling_projects") or []
+    return [Path(p) for p in raw]
+
+
+def _claude_md_lines() -> int:
+    try:
+        cfg = cfg_mod.load()
+    except Exception:
+        return _DEFAULT_CLAUDE_MD_LINES
+    return int(cfg.pr.get("delta_claude_md_lines", _DEFAULT_CLAUDE_MD_LINES))
+
+
+def _gather(sibling: Path, claude_md_lines: int) -> dict:
+    claude_md = sibling / "CLAUDE.md"
+    culture = sibling / "culture.yaml"
+    head = None
+    if claude_md.exists():
+        lines = claude_md.read_text(encoding="utf-8").splitlines()
+        head = "\n".join(lines[:claude_md_lines])
+    culture_text = culture.read_text(encoding="utf-8") if culture.exists() else None
+    return {
+        "name": sibling.name,
+        "path": str(sibling),
+        "claude_md_head": head,
+        "culture_yaml": culture_text,
+    }
+
+
+def run(agent: str | None, project_dir: Path) -> tuple[str, int, str]:
+    backend = resolve_backend(agent, project_dir)
+    siblings = _load_siblings(project_dir)
+    claude_md_lines = _claude_md_lines()
+
+    if siblings is None:
+        prog = prog_name()
+        stdout = (
+            f"# `{prog} pr delta`\n\n"
+            "No `.claude/skills.local.yaml` found.  Copy "
+            "`.claude/skills.local.yaml.example` and fill `sibling_projects`.\n"
+        )
+        stderr = (
+            f"{prog}: copy .claude/skills.local.yaml.example to "
+            ".claude/skills.local.yaml and fill sibling_projects\n"
+        )
+        return stdout, 0, stderr
+
+    template = files(_TEMPLATES_PKG).joinpath("delta.md.j2").read_text(encoding="utf-8")
+    rendered_siblings = [_gather(s, claude_md_lines) for s in siblings]
+    footer_key, footer_ctx = delta_next_step()
+    footer = render_footer(footer_key, backend, footer_ctx)
+    stdout = render_string(
+        template,
+        {
+            "siblings": rendered_siblings,
+            "claude_md_lines": claude_md_lines,
+            "footer": footer,
+        },
+    )
+    return stdout, 0, ""

agent_experience/commands/pr/scripts/lint.py

@@ -0,0 +1,72 @@
+"""`agex pr lint` — portability + alignment-trigger lint on the working diff."""
+
+from __future__ import annotations
+
+import subprocess
+from importlib.resources import files
+from pathlib import Path
+
+from agent_experience.commands.pr.assets.rules.lint_rules import (
+    Violation,
+    check_alignment_trigger,
+    check_files,
+)
+from agent_experience.commands.pr.assets.rules.next_step_rules import lint_next_step
+from agent_experience.commands.pr.scripts._footer import render_footer
+from agent_experience.core.backend import resolve_backend
+from agent_experience.core.render import render_string
+
+_TEMPLATES_PKG = "agent_experience.commands.pr.assets.templates"
+
+
+def _collect_diff() -> list[tuple[str, str]]:
+    """Return [(path, post-change content)] for staged + unstaged files.
+
+    For deleted files, returns an empty content string — rules treat that as
+    nothing to lint.
+    """
+    paths_staged = subprocess.run(
+        ["git", "diff", "--staged", "--name-only"],
+        capture_output=True,
+        text=True,
+        check=False,
+    ).stdout.splitlines()
+    paths_unstaged = subprocess.run(
+        ["git", "diff", "--name-only"],
+        capture_output=True,
+        text=True,
+        check=False,
+    ).stdout.splitlines()
+    paths = sorted(set(paths_staged) | set(paths_unstaged))
+    out: list[tuple[str, str]] = []
+    for p in paths:
+        try:
+            content = Path(p).read_text(encoding="utf-8", errors="replace")
+        except (FileNotFoundError, IsADirectoryError):
+            content = ""
+        out.append((p, content))
+    return out
+
+
+def run(agent: str | None, project_dir: Path, exit_on_violation: bool) -> tuple[str, int, str]:
+    backend = resolve_backend(agent, project_dir)
+
+    file_pairs = _collect_diff()
+    violations: list[Violation] = check_files(file_pairs)
+    alignment_triggered = check_alignment_trigger([p for p, _ in file_pairs])
+
+    footer_key, footer_ctx = lint_next_step(violations, alignment_triggered)
+    footer = render_footer(footer_key, backend, footer_ctx)
+
+    template = files(_TEMPLATES_PKG).joinpath("lint_result.md.j2").read_text(encoding="utf-8")
+    stdout = render_string(
+        template,
+        {
+            "violations": [v.__dict__ for v in violations],
+            "alignment_triggered": alignment_triggered,
+            "footer": footer,
+        },
+    )
+
+    exit_code = 1 if (exit_on_violation and violations) else 0
+    return stdout, exit_code, ""

agent_experience/commands/pr/scripts/open_.py

@@ -0,0 +1,104 @@
+"""`agex pr open` — gh pr create with auto-signed body and idempotency."""
+
+from __future__ import annotations
+
+import sys
+from importlib.resources import files
+from pathlib import Path
+
+from agent_experience.commands.pr.assets.rules.next_step_rules import open_next_step
+from agent_experience.commands.pr.scripts import _journal, review
+from agent_experience.commands.pr.scripts._footer import render_footer
+from agent_experience.core import github
+from agent_experience.core.backend import resolve_backend
+from agent_experience.core.render import render_string
+
+_TEMPLATES_PKG = "agent_experience.commands.pr.assets.templates"
+
+
+def _read_body(body_file: Path | None) -> str:
+    if body_file is None:
+        return sys.stdin.read()
+    return body_file.read_text(encoding="utf-8")
+
+
+def _signed(body: str, nick: str) -> tuple[str, bool]:
+    sig = f"- {nick} (Claude)"
+    if sig in body:
+        return body, True
+    sep = "" if body.endswith("\n") else "\n"
+    return f"{body}{sep}\n{sig}\n", True
+
+
+def run(
+    agent: str | None,
+    project_dir: Path,
+    title: str,
+    body_file: Path | None,
+    draft: bool,
+    delayed_read: bool = False,
+) -> tuple[str, int, str]:
+    backend = resolve_backend(agent, project_dir)
+    nick = github.resolve_nick(project_dir)
+
+    existing = github.pr_view(None)
+    if existing is not None and existing.get("state") == "OPEN":
+        pr = int(existing["number"])
+        url = existing.get("url", "")
+        was_already_open = True
+        signed = False
+    else:
+        body = _read_body(body_file)
+        body, signed = _signed(body, nick)
+        pr = github.pr_create(title=title, body=body, draft=draft)
+        url = ""
+        was_already_open = False
+        _journal.append({"type": "pr_opened", "pr": pr, "title": title})
+
+    # Auto-post the Qodo agentic-review trigger out of the box for a freshly
+    # created, non-draft PR.  Skipped for drafts (not review-ready yet — use
+    # `pr review` to trigger later) and for already-open PRs (idempotent
+    # re-opens shouldn't spam the thread).
+    #
+    # The trigger post is best-effort: PR creation is the primary side effect
+    # and has already succeeded, so a transient `gh` failure here must NOT abort
+    # the command (which would tell the user to rerun `pr open`, only to skip
+    # the trigger forever as an already-open PR).  On failure we keep exit 0 and
+    # point the user at `pr review` to retry just the trigger.
+    review_posted = False
+    review_failed = False
+    if not was_already_open and not draft:
+        try:
+            review.post_trigger(pr)
+            review_posted = True
+        except RuntimeError:
+            review_failed = True
+
+    footer_key, footer_ctx = open_next_step(pr, was_already_open)
+    footer = render_footer(footer_key, backend, footer_ctx)
+
+    template = files(_TEMPLATES_PKG).joinpath("pr_open_result.md.j2").read_text(encoding="utf-8")
+    stdout = render_string(
+        template,
+        {
+            "pr": pr,
+            "url": url,
+            "title": title,
+            "signed": signed,
+            "draft": draft,
+            "was_already_open": was_already_open,
+            "review_posted": review_posted,
+            "review_failed": review_failed,
+            "review_command": review.QODO_REVIEW_TRIGGER,
+            "footer": footer,
+        },
+    )
+
+    if delayed_read and not was_already_open:
+        from agent_experience.commands.pr.scripts import read as read_script
+
+        read_stdout, read_exit, _ = read_script.run(
+            agent=agent, project_dir=project_dir, pr=pr, wait=180
+        )
+        return stdout + "\n" + read_stdout, read_exit, ""
+    return stdout, 0, ""

agent_experience/commands/pr/scripts/read.py

@@ -0,0 +1,151 @@
+"""`agex pr read` — unified PR briefing.
+
+v0.1: one-shot read.  Task 17 adds --wait + readiness loop.
+"""
+
+from __future__ import annotations
+
+import subprocess
+import sys
+import time
+from importlib.resources import files
+from pathlib import Path
+from typing import Any
+
+from agent_experience.commands.pr.assets.rules.next_step_rules import (
+    read_next_step,
+    read_wait_timeout_step,
+)
+from agent_experience.commands.pr.scripts import _journal, _qodo, _readiness, _sonar
+from agent_experience.commands.pr.scripts._footer import render_footer
+from agent_experience.core import github
+from agent_experience.core.backend import resolve_backend
+from agent_experience.core.render import render_string
+
+_TEMPLATES_PKG = "agent_experience.commands.pr.assets.templates"
+
+
+def _has_recent_local_commits(journal_events: list[dict[str, Any]], pr: int) -> bool:
+    """True if `git log` shows commits authored after the most recent
+    `pr_read` event for this PR.  No event yet → False (first read)."""
+    last_read = next(
+        (e for e in reversed(journal_events) if e.get("type") == "pr_read" and e.get("pr") == pr),
+        None,
+    )
+    if last_read is None:
+        return False
+    ts = last_read["ts"]
+    out = subprocess.run(
+        ["git", "log", f"--since={ts}", "--pretty=%H"],
+        capture_output=True,
+        text=True,
+        check=False,
+    ).stdout.strip()
+    return bool(out)
+
+
+def run(
+    agent: str | None,
+    project_dir: Path,
+    pr: int | None,
+    wait: int | None,
+) -> tuple[str, int, str]:
+    backend = resolve_backend(agent, project_dir)
+    pr_number = github.resolve_pr_number(pr)
+
+    waited_secs = 0
+    waiting_for: list[str] = []
+    if wait is not None and wait > 0:
+        required = _readiness.required_reviewers()
+        deadline = wait
+        ready = False
+        while waited_secs < deadline:
+            comments = github.pr_comments(pr_number)
+            ready, waiting_for = _readiness.is_ready(comments, required)
+            sys.stderr.write(
+                _readiness.heartbeat("pr_read --wait", pr_number, waited_secs, ready, waiting_for)
+            )
+            sys.stderr.flush()
+            if ready:
+                _journal.append(
+                    {"type": "readiness_arrived", "pr": pr_number, "waited_secs": waited_secs}
+                )
+                break
+            interval = min(_readiness.POLL_INTERVAL_SEC, max(1, deadline - waited_secs))
+            time.sleep(interval)
+            waited_secs += interval
+        if not ready:
+            # Timeout — render still-waiting briefing.
+            pr_meta = github.pr_view(str(pr_number))
+            checks = github.pr_checks(pr_number)
+            comments = github.pr_comments(pr_number)
+            qodo = _qodo.parse(comments)
+            footer_key, footer_ctx = read_wait_timeout_step(pr_number, waiting_for)
+            footer = render_footer(footer_key, backend, footer_ctx)
+            template = (
+                files(_TEMPLATES_PKG).joinpath("pr_briefing.md.j2").read_text(encoding="utf-8")
+            )
+            stdout = render_string(
+                template,
+                {
+                    "pr": pr_number,
+                    "pr_meta": pr_meta,
+                    "checks": checks,
+                    "comments": comments,
+                    "qodo": qodo,
+                    "sonar_gate": None,
+                    "sonar_issues": [],
+                    "waiting_for": waiting_for,
+                    "footer": footer,
+                },
+            )
+            return stdout, 0, ""
+
+    # Either no --wait, or readiness arrived: full briefing path.
+    pr_meta = github.pr_view(str(pr_number))
+    checks = github.pr_checks(pr_number)
+    comments = github.pr_comments(pr_number)
+    qodo = _qodo.parse(comments)
+    project_key = _sonar.project_key()
+    sonar_gate = github.sonar_quality_gate(project_key, pr_number)
+    sonar_issues = github.sonar_new_issues(project_key, pr_number)
+
+    threads_unresolved = _readiness.threads_unresolved(pr_number)
+    journal_events = _journal.load()
+    has_recent_commits = _has_recent_local_commits(journal_events, pr_number)
+    ci_red = any(c.get("conclusion") == "failure" for c in checks)
+
+    _journal.append(
+        {
+            "type": "pr_read",
+            "pr": pr_number,
+            "comment_count": len(comments),
+            "threads_unresolved": threads_unresolved,
+            "ci_state": "failure" if ci_red else "ok",
+        }
+    )
+
+    footer_key, footer_ctx = read_next_step(
+        pr=pr_number,
+        threads_unresolved=threads_unresolved,
+        has_recent_local_commits=has_recent_commits,
+        ci_red=ci_red,
+    )
+    footer = render_footer(footer_key, backend, footer_ctx)
+
+    template = files(_TEMPLATES_PKG).joinpath("pr_briefing.md.j2").read_text(encoding="utf-8")
+    stdout = render_string(
+        template,
+        {
+            "pr": pr_number,
+            "pr_meta": pr_meta,
+            "checks": checks,
+            "comments": comments,
+            "qodo": qodo,
+            "sonar_gate": sonar_gate,
+            "sonar_issues": sonar_issues,
+            "waiting_for": [],
+            "footer": footer,
+        },
+    )
+    return stdout, 0, ""

agent_experience/commands/pr/scripts/reply.py

@@ -0,0 +1,160 @@
+"""`agex pr reply` — batch JSONL replies + thread resolution."""
+
+from __future__ import annotations
+
+import json
+import sys
+from dataclasses import dataclass
+from importlib.resources import files
+from pathlib import Path
+
+from agent_experience.commands.pr.assets.rules.next_step_rules import reply_next_step
+from agent_experience.commands.pr.scripts import _journal
+from agent_experience.commands.pr.scripts._footer import render_footer
+from agent_experience.core import github
+from agent_experience.core.backend import resolve_backend
+from agent_experience.core.prog import prog_name
+from agent_experience.core.render import render_string
+
+_TEMPLATES_PKG = "agent_experience.commands.pr.assets.templates"
+
+
+@dataclass
+class _Failure:
+    line: int
+    reason: str
+    entry: str
+
+
+def _signed(body: str, nick: str) -> str:
+    sig = f"- {nick} (Claude)"
+    if sig in body:
+        return body
+    sep = "" if body.endswith("\n") else "\n"
+    return f"{body}{sep}\n{sig}\n"
+
+
+def _validate_entry(raw_line: str, lineno: int) -> tuple[dict | None, _Failure | None, bool]:
+    """Parse and validate one JSONL line.
+
+    Returns (entry, None, False) on success, or (None, failure, is_parse_error)
+    on error.  The caller should break and record parse_error_line when
+    is_parse_error is True.
+    """
+    try:
+        entry = json.loads(raw_line)
+    except json.JSONDecodeError as exc:
+        return None, _Failure(line=lineno, reason=f"JSONL parse error: {exc}", entry=raw_line), True
+    if not isinstance(entry, dict) or not isinstance(entry.get("body"), str):
+        return (
+            None,
+            _Failure(
+                line=lineno,
+                reason="missing or invalid 'body' field (must be string)",
+                entry=raw_line,
+            ),
+            False,
+        )
+    return entry, None, False
+
+
+def _post_entry(entry: dict, nick: str, pr: int) -> bool:
+    """Post one reply + optional thread resolution; append journal events.
+
+    Returns True if a thread was resolved (caller increments resolved count).
+    Raises RuntimeError on gh failure — caller records the failure and stops.
+    """
+    body = _signed(entry["body"], nick)
+    github.pr_post_comment(pr=pr, body=body, in_reply_to=entry.get("in_reply_to"))
+    _journal.append(
+        {
+            "type": "pr_reply",
+            "pr": pr,
+            "thread_id": entry.get("thread_id"),
+            "in_reply_to": entry.get("in_reply_to"),
+        }
+    )
+    thread_id = entry.get("thread_id")
+    if thread_id:
+        github.pr_resolve_thread(thread_id)
+        return True
+    return False
+
+
+def _process_line(
+    raw_line: str, lineno: int, nick: str, pr: int
+) -> tuple[int, int, _Failure | None, bool]:
+    """Process one JSONL line. Returns (posted_delta, resolved_delta, failure, is_parse_error).
+
+    Caller breaks the loop when failure is not None.
+    """
+    entry, failure, is_parse_error = _validate_entry(raw_line, lineno)
+    if failure is not None:
+        return 0, 0, failure, is_parse_error
+    try:
+        did_resolve = _post_entry(entry, nick, pr)  # type: ignore[arg-type]
+    except RuntimeError as exc:
+        return 0, 0, _Failure(line=lineno, reason=str(exc), entry=raw_line), False
+    return 1, (1 if did_resolve else 0), None, False
+
+
+def _stderr_for_failures(failures: list[_Failure], parse_error_line: int | None, pr: int) -> str:
+    """Build the instructive stderr line for the failure case."""
+    prog = prog_name()
+    if parse_error_line is not None:
+        return (
+            f"{prog}: fix line {parse_error_line} (see stdout) and resubmit "
+            f"lines {parse_error_line}..end to '{prog} pr reply {pr}'\n"
+        )
+    first_failed = failures[0].line
+    return (
+        f"{prog}: resubmit lines {first_failed}..end from the table above "
+        f"to '{prog} pr reply {pr}'\n"
+    )
+
+
+def run(
+    agent: str | None,
+    project_dir: Path,
+    pr: int,
+) -> tuple[str, int, str]:
+    backend = resolve_backend(agent, project_dir)
+    nick = github.resolve_nick(project_dir)
+    raw = sys.stdin.read()
+
+    posted = 0
+    resolved = 0
+    failures: list[_Failure] = []
+    parse_error_line: int | None = None
+
+    for lineno, raw_line in enumerate(raw.splitlines(), start=1):
+        if not raw_line.strip():
+            continue
+        dp, dr, failure, is_parse_error = _process_line(raw_line, lineno, nick, pr)
+        posted += dp
+        resolved += dr
+        if failure is not None:
+            if is_parse_error:
+                parse_error_line = lineno
+            failures.append(failure)
+            break
+
+    _journal.append({"type": "pr_batch_replied", "pr": pr, "count": posted, "resolved": resolved})
+
+    footer_key, footer_ctx = reply_next_step(pr=pr, failure_count=len(failures))
+    footer = render_footer(footer_key, backend, footer_ctx)
+
+    template = files(_TEMPLATES_PKG).joinpath("pr_reply_result.md.j2").read_text(encoding="utf-8")
+    stdout = render_string(
+        template,
+        {
+            "pr": pr,
+            "count": posted,
+            "resolved": resolved,
+            "failures": [f.__dict__ for f in failures],
+            "footer": footer,
+        },
+    )
+    if not failures:
+        return stdout, 0, ""
+    return stdout, 1, _stderr_for_failures(failures, parse_error_line, pr)

agent_experience/commands/pr/scripts/review.py

@@ -0,0 +1,59 @@
+"""`agex pr review` — post the Qodo agentic-review trigger comment.
+
+Qodo's current command to start an agentic PR review is ``/agentic_review``.
+The legacy ``/improve`` command is deprecated (Qodo emits a deprecation banner
+when it is used), so agex never posts ``/improve``.  ``QODO_REVIEW_TRIGGER`` is
+the single source of truth for the command string — any future Qodo rename is a
+one-line change here, picked up by both this verb and the auto-post on
+``pr open``.
+"""
+
+from __future__ import annotations
+
+from importlib.resources import files
+from pathlib import Path
+
+from agent_experience.commands.pr.assets.rules.next_step_rules import review_next_step
+from agent_experience.commands.pr.scripts import _journal
+from agent_experience.commands.pr.scripts._footer import render_footer
+from agent_experience.core import github
+from agent_experience.core.backend import resolve_backend
+from agent_experience.core.render import render_string
+
+_TEMPLATES_PKG = "agent_experience.commands.pr.assets.templates"
+
+# The non-deprecated Qodo command to start an agentic code review. Single
+# source of truth — referenced here and by the `pr open` auto-post.
+QODO_REVIEW_TRIGGER = "/agentic_review"
+
+
+def post_trigger(pr: int) -> int:
+    """Post the Qodo review-trigger comment on ``pr``; return the comment ID.
+
+    Also appends a ``pr_review_triggered`` journal event.  Shared by the
+    ``pr review`` verb and the ``pr open`` auto-post.
+    """
+    comment_id = github.pr_post_comment(pr, QODO_REVIEW_TRIGGER, None)
+    _journal.append({"type": "pr_review_triggered", "pr": pr, "command": QODO_REVIEW_TRIGGER})
+    return comment_id
+
+
+def run(agent: str | None, project_dir: Path, pr: int | None) -> tuple[str, int, str]:
+    backend = resolve_backend(agent, project_dir)
+    pr_number = github.resolve_pr_number(pr)
+
+    post_trigger(pr_number)
+
+    footer_key, footer_ctx = review_next_step(pr_number)
+    footer = render_footer(footer_key, backend, footer_ctx)
+
+    template = files(_TEMPLATES_PKG).joinpath("pr_review_result.md.j2").read_text(encoding="utf-8")
+    stdout = render_string(
+        template,
+        {
+            "pr": pr_number,
+            "command": QODO_REVIEW_TRIGGER,
+            "footer": footer,
+        },
+    )
+    return stdout, 0, ""