agentic-project-kit 1.0.1__py3-none-any.whl

agentic_project_kit/next_turn_pr_status.py

@@ -0,0 +1,255 @@
+from __future__ import annotations
+
+import argparse
+from collections.abc import Callable
+from dataclasses import asdict
+import json
+import re
+import subprocess
+from dataclasses import dataclass, replace
+from typing import Any, Literal
+
+Decision = Literal["green", "red", "pending", "no-checks", "unknown", "not-open"]
+FailedLogStatus = Literal["not-fetched", "fetched", "unavailable", "missing-run-id"]
+
+
+@dataclass(frozen=True)
+class FailedRunDiagnostic:
+    check_name: str
+    conclusion: str
+    run_id: str
+    details_url: str
+    command: str
+    log_status: FailedLogStatus = "not-fetched"
+    log_excerpt: str = ""
+    error: str = ""
+
+
+@dataclass(frozen=True)
+class PrStatusDecision:
+    pr: str
+    state: str
+    merge_state_status: str
+    head_ref_oid: str
+    decision: Decision
+    successful_checks: tuple[str, ...]
+    pending_checks: tuple[str, ...]
+    failed_checks: tuple[str, ...]
+    unknown_checks: tuple[str, ...]
+    failed_run_log_hint: str
+    failed_run_diagnostics: tuple[FailedRunDiagnostic, ...]
+
+
+def _check_name(item: dict[str, Any]) -> str:
+    return str(item.get("name") or item.get("workflowName") or item.get("__typename") or "unknown")
+
+
+def _run_id_from_details_url(details_url: str) -> str:
+    match = re.search(r"/actions/runs/([0-9]+)(?:/|$)", details_url)
+    return match.group(1) if match else ""
+
+
+def _failed_run_diagnostic(item: dict[str, Any], *, name: str, conclusion: str) -> FailedRunDiagnostic:
+    details_url = str(item.get("detailsUrl") or item.get("details_url") or "")
+    run_id = _run_id_from_details_url(details_url)
+    command = f"gh run view {run_id} --log-failed" if run_id else ""
+    return FailedRunDiagnostic(
+        check_name=name,
+        conclusion=conclusion,
+        run_id=run_id,
+        details_url=details_url,
+        command=command,
+    )
+
+
+def classify_pr_status(payload: dict[str, Any], *, pr: str = "") -> PrStatusDecision:
+    state = str(payload.get("state") or "UNKNOWN")
+    checks = payload.get("statusCheckRollup") or []
+    successful: list[str] = []
+    pending: list[str] = []
+    failed: list[str] = []
+    unknown: list[str] = []
+    failed_diagnostics: list[FailedRunDiagnostic] = []
+
+    if state != "OPEN":
+        decision: Decision = "not-open"
+    elif not isinstance(checks, list) or not checks:
+        decision = "no-checks"
+    else:
+        for item in checks:
+            if not isinstance(item, dict):
+                unknown.append("unknown")
+                continue
+            name = _check_name(item)
+            status = str(item.get("status") or "").upper()
+            conclusion = str(item.get("conclusion") or "").upper()
+            if status != "COMPLETED":
+                pending.append(name)
+            elif conclusion == "SUCCESS":
+                successful.append(name)
+            elif conclusion in {"FAILURE", "CANCELLED", "TIMED_OUT", "ACTION_REQUIRED"}:
+                failed.append(name)
+                failed_diagnostics.append(_failed_run_diagnostic(item, name=name, conclusion=conclusion))
+            else:
+                unknown.append(name)
+
+        if failed:
+            decision = "red"
+        elif pending:
+            decision = "pending"
+        elif unknown:
+            decision = "unknown"
+        else:
+            decision = "green"
+
+    hint = "none"
+    if decision == "red":
+        commands = [diagnostic.command for diagnostic in failed_diagnostics if diagnostic.command]
+        hint = f"run: {commands[0]}" if commands else "run: gh run view <failed-run-id> --log-failed"
+
+    return PrStatusDecision(
+        pr=pr,
+        state=state,
+        merge_state_status=str(payload.get("mergeStateStatus") or "UNKNOWN"),
+        head_ref_oid=str(payload.get("headRefOid") or ""),
+        decision=decision,
+        successful_checks=tuple(successful),
+        pending_checks=tuple(pending),
+        failed_checks=tuple(failed),
+        unknown_checks=tuple(unknown),
+        failed_run_log_hint=hint,
+        failed_run_diagnostics=tuple(failed_diagnostics),
+    )
+
+
+def _excerpt(text: str, *, max_lines: int) -> str:
+    lines = text.strip().splitlines()
+    if max_lines <= 0 or len(lines) <= max_lines:
+        return "\n".join(lines)
+    omitted = len(lines) - max_lines
+    return "\n".join([*lines[:max_lines], f"... ({omitted} lines omitted)"])
+
+
+def _fetch_failed_run_log(run_id: str) -> tuple[int, str, str]:
+    completed = subprocess.run(["gh", "run", "view", run_id, "--log-failed"], text=True, capture_output=True, check=False)
+    return completed.returncode, completed.stdout, completed.stderr
+
+
+def attach_failed_run_logs(
+    decision: PrStatusDecision,
+    *,
+    max_lines: int = 120,
+    fetcher: Callable[[str], tuple[int, str, str]] = _fetch_failed_run_log,
+) -> PrStatusDecision:
+    diagnostics: list[FailedRunDiagnostic] = []
+    for diagnostic in decision.failed_run_diagnostics:
+        if not diagnostic.run_id:
+            diagnostics.append(
+                replace(
+                    diagnostic,
+                    log_status="missing-run-id",
+                    error="failed check detailsUrl did not contain a GitHub Actions run id",
+                )
+            )
+            continue
+        returncode, stdout, stderr = fetcher(diagnostic.run_id)
+        if returncode == 0:
+            diagnostics.append(replace(diagnostic, log_status="fetched", log_excerpt=_excerpt(stdout, max_lines=max_lines)))
+            continue
+        diagnostics.append(
+            replace(
+                diagnostic,
+                log_status="unavailable",
+                log_excerpt=_excerpt(stdout, max_lines=max_lines),
+                error=(stderr.strip() or stdout.strip() or f"gh run view exited with {returncode}"),
+            )
+        )
+    return replace(decision, failed_run_diagnostics=tuple(diagnostics))
+
+
+def _render_indented_block(text: str, *, indent: str = "  ") -> list[str]:
+    if not text:
+        return [f"{indent}(none)"]
+    return [f"{indent}{line}" for line in text.splitlines()]
+
+
+def render_decision(decision: PrStatusDecision) -> str:
+    lines = [
+        "NEXT_TURN_PR_STATUS",
+        f"pr={decision.pr}",
+        f"state={decision.state}",
+        f"merge_state_status={decision.merge_state_status}",
+        f"head_ref_oid={decision.head_ref_oid}",
+        f"decision={decision.decision}",
+        "successful_checks:",
+        *[f"- {item}" for item in decision.successful_checks],
+        "pending_checks:",
+        *[f"- {item}" for item in decision.pending_checks],
+        "failed_checks:",
+        *[f"- {item}" for item in decision.failed_checks],
+        "unknown_checks:",
+        *[f"- {item}" for item in decision.unknown_checks],
+        f"failed_run_log_hint={decision.failed_run_log_hint}",
+        "failed_run_diagnostics:",
+    ]
+    for diagnostic in decision.failed_run_diagnostics:
+        lines.extend(
+            [
+                (
+                    f"- check={diagnostic.check_name} conclusion={diagnostic.conclusion} "
+                    f"run_id={diagnostic.run_id or '(missing)'} log_status={diagnostic.log_status}"
+                ),
+                f"  command={diagnostic.command or '(unavailable)'}",
+                f"  details_url={diagnostic.details_url or '(missing)'}",
+            ]
+        )
+        if diagnostic.error:
+            lines.append(f"  error={diagnostic.error}")
+        lines.append("  log_excerpt:")
+        lines.extend(_render_indented_block(diagnostic.log_excerpt, indent="    "))
+    lines.append("### RESULT: PASS ###")
+    return "\n".join(lines)
+
+
+def _run_gh(args: list[str]) -> str:
+    completed = subprocess.run(["gh", *args], text=True, capture_output=True, check=False)
+    if completed.returncode != 0:
+        raise RuntimeError(completed.stderr.strip() or completed.stdout.strip())
+    return completed.stdout
+
+
+def fetch_pr_payload(pr: str) -> dict[str, Any]:
+    raw = _run_gh([
+        "pr",
+        "view",
+        pr,
+        "--json",
+        "baseRefName,baseRefOid,headRefName,headRefOid,state,mergeStateStatus,statusCheckRollup,url",
+    ])
+    payload = json.loads(raw)
+    if not isinstance(payload, dict):
+        raise RuntimeError("gh pr view did not return a JSON object")
+    return payload
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(prog="next-turn-pr-status")
+    parser.add_argument("pr")
+    parser.add_argument("--json", action="store_true")
+    parser.add_argument("--no-failed-log-fetch", action="store_true")
+    parser.add_argument("--failed-log-lines", type=int, default=120)
+    args = parser.parse_args()
+
+    payload = fetch_pr_payload(args.pr)
+    decision = classify_pr_status(payload, pr=args.pr)
+    if decision.decision == "red" and not args.no_failed_log_fetch:
+        decision = attach_failed_run_logs(decision, max_lines=args.failed_log_lines)
+    if args.json:
+        print(json.dumps(asdict(decision), indent=2, sort_keys=True))
+    else:
+        print(render_decision(decision))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

agentic_project_kit/next_turn_result.py

@@ -0,0 +1,183 @@
+from __future__ import annotations
+
+import argparse
+import json
+from dataclasses import asdict, dataclass
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Literal
+
+WorkResult = Literal["PASS", "FAIL", "PENDING", "HARD_FAIL", "PASS_ALREADY_DONE", "NOOP"]
+EvidenceResult = Literal["PASS", "FAIL", "PARTIAL", "CHAT_ONLY", "NOT_REQUIRED", "LOCAL_LOG"]
+RemoteEvidence = Literal["PASS", "FAIL", "PARTIAL", "NOT_REQUIRED"]
+
+
+@dataclass(frozen=True)
+class NextTurnResult:
+    run_id: str
+    work_result: WorkResult
+    evidence_result: EvidenceResult
+    overall_result: WorkResult
+    remote_evidence: RemoteEvidence
+    terminal_log: str
+    remote_terminal_log: str
+    command_report: str
+    next_chat_reply: str
+    timestamp_utc: str
+    reason: str = ""
+
+
+def classify_next_chat_reply(overall_result: str, remote_evidence: str) -> str:
+    if overall_result in {"PASS", "PASS_ALREADY_DONE", "NOOP"}:
+        return "d"
+    if remote_evidence in {"PASS", "PARTIAL"}:
+        return "f"
+    return "paste-output"
+
+
+def build_result(
+    *,
+    run_id: str,
+    work_result: WorkResult,
+    evidence_result: EvidenceResult,
+    remote_evidence: RemoteEvidence,
+    terminal_log: str = "NONE",
+    remote_terminal_log: str = "NONE",
+    command_report: str = "NONE",
+    reason: str = "",
+) -> NextTurnResult:
+    next_chat_reply = classify_next_chat_reply(work_result, remote_evidence)
+    return NextTurnResult(
+        run_id=run_id,
+        work_result=work_result,
+        evidence_result=evidence_result,
+        overall_result=work_result,
+        remote_evidence=remote_evidence,
+        terminal_log=terminal_log,
+        remote_terminal_log=remote_terminal_log,
+        command_report=command_report,
+        next_chat_reply=next_chat_reply,
+        timestamp_utc=datetime.now(UTC).isoformat(),
+        reason=reason,
+    )
+
+
+def result_paths(run_id: str, root: Path | str = ".") -> tuple[Path, Path, Path]:
+    root_path = Path(root)
+    report = root_path / "docs" / "reports" / "command_runs" / f"{run_id}.json"
+    latest = root_path / "docs" / "reports" / "command_runs" / "next-turn-latest.json"
+    terminal = root_path / "docs" / "reports" / "terminal" / f"{run_id}.log"
+    return report, latest, terminal
+
+
+def write_result(result: NextTurnResult, root: Path | str = ".") -> tuple[Path, Path]:
+    report, latest, _terminal = result_paths(result.run_id, root)
+    report.parent.mkdir(parents=True, exist_ok=True)
+    payload = asdict(result)
+    report.write_text(json.dumps(payload, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+    latest.write_text(json.dumps(payload, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+    return report, latest
+
+
+
+def publish_local_evidence(
+    *,
+    run_id: str,
+    local_terminal_log: Path | str,
+    work_result: WorkResult,
+    evidence_result: EvidenceResult = "PASS",
+    reason: str = "",
+    root: Path | str = ".",
+) -> NextTurnResult:
+    root_path = Path(root)
+    source = Path(local_terminal_log)
+    _report, _latest, remote_terminal = result_paths(run_id, root_path)
+    remote_terminal.parent.mkdir(parents=True, exist_ok=True)
+
+    if not source.exists():
+        result = build_result(
+            run_id=run_id,
+            work_result=work_result,
+            evidence_result="FAIL",
+            remote_evidence="FAIL",
+            terminal_log=str(source),
+            remote_terminal_log=str(remote_terminal.relative_to(root_path)),
+            reason=f"local terminal log not found: {source}",
+        )
+        write_result(result, root_path)
+        return result
+
+    remote_terminal.write_text(source.read_text(encoding="utf-8", errors="replace"), encoding="utf-8")
+
+    result = build_result(
+        run_id=run_id,
+        work_result=work_result,
+        evidence_result=evidence_result,
+        remote_evidence="PARTIAL",
+        terminal_log=str(source),
+        remote_terminal_log=str(remote_terminal.relative_to(root_path)),
+        command_report=str((root_path / "docs" / "reports" / "command_runs" / f"{run_id}.json").relative_to(root_path)),
+        reason=reason,
+    )
+    write_result(result, root_path)
+    return result
+
+def render_summary(result: NextTurnResult) -> str:
+    return "\n".join(
+        [
+            "================================================================",
+            "SUMMARY",
+            f"WORK RESULT: {result.work_result}",
+            f"EVIDENCE RESULT: {result.evidence_result}",
+            f"OVERALL RESULT: {result.overall_result}",
+            f"REMOTE_EVIDENCE: {result.remote_evidence}",
+            f"terminal_log={result.terminal_log}",
+            f"remote_terminal_log={result.remote_terminal_log}",
+            f"command_report={result.command_report}",
+            f"NEXT_CHAT_REPLY: {result.next_chat_reply}",
+            f"CHAT_REPLY: {result.next_chat_reply}",
+            f"### RESULT: {result.overall_result} ###",
+            "================================================================",
+        ]
+    )
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(prog="next-turn-result")
+    parser.add_argument("--run-id", required=True)
+    parser.add_argument("--work-result", required=True, choices=["PASS", "FAIL", "PENDING", "HARD_FAIL", "PASS_ALREADY_DONE", "NOOP"])
+    parser.add_argument("--evidence-result", default="LOCAL_LOG")
+    parser.add_argument("--remote-evidence", default="NOT_REQUIRED")
+    parser.add_argument("--terminal-log", default="NONE")
+    parser.add_argument("--remote-terminal-log", default="NONE")
+    parser.add_argument("--command-report", default="NONE")
+    parser.add_argument("--reason", default="")
+    parser.add_argument("--publish-local-log", default="")
+    args = parser.parse_args()
+
+    if args.publish_local_log:
+        result = publish_local_evidence(
+            run_id=args.run_id,
+            local_terminal_log=args.publish_local_log,
+            work_result=args.work_result,
+            evidence_result=args.evidence_result,
+            reason=args.reason,
+        )
+    else:
+        result = build_result(
+            run_id=args.run_id,
+            work_result=args.work_result,
+            evidence_result=args.evidence_result,
+            remote_evidence=args.remote_evidence,
+            terminal_log=args.terminal_log,
+            remote_terminal_log=args.remote_terminal_log,
+            command_report=args.command_report,
+            reason=args.reason,
+        )
+        write_result(result)
+    print(render_summary(result))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

agentic_project_kit/next_turn_runner.py

@@ -0,0 +1,159 @@
+from __future__ import annotations
+
+import argparse
+import json
+import subprocess
+import sys
+from dataclasses import asdict, dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+import os
+
+from agentic_project_kit.next_turn_evidence import commit_and_push_evidence, publish_and_stage_evidence, render_finalize_result
+from agentic_project_kit.next_turn_slot import FIXED_SLOT_SCRIPT, FIXED_SLOT_YAML
+from agentic_project_kit.work_order_validator import default_local_result_log_path
+from agentic_project_kit.workspace import LEGACY_DEFAULTS, load_workspace
+
+LATEST_TERMINAL_LOG = Path(
+    os.environ.get(
+        "AGENTIC_KIT_NEXT_TURN_LOG",
+        (Path(LEGACY_DEFAULTS.tmp_root) / "next-turn-latest.log").as_posix(),
+    )
+)
+LATEST_COMMAND_REPORT = Path(
+    os.environ.get(
+        "AGENTIC_KIT_NEXT_TURN_REPORT",
+        (Path(LEGACY_DEFAULTS.tmp_root) / "next-turn-latest.json").as_posix(),
+    )
+)
+
+
+@dataclass(frozen=True)
+class NextTurnRunResult:
+    command_id: str
+    outcome: str
+    exit_code: int
+    script_path: str
+    yaml_path: str
+    terminal_log: str
+    command_report: str
+    timestamp_utc: str
+
+
+def _command_id_from_yaml(path: Path) -> str:
+    if not path.exists():
+        return "next-turn"
+    for line in path.read_text(encoding="utf-8").splitlines():
+        if line.startswith("command_id:"):
+            return line.split(":", 1)[1].strip() or "next-turn"
+    return "next-turn"
+
+
+def run_fixed_slot(root: Path | str = ".") -> NextTurnRunResult:
+    root_path = Path(root)
+    yaml_path = root_path / FIXED_SLOT_YAML
+    script_path = root_path / FIXED_SLOT_SCRIPT
+    terminal_log = (
+        root_path / LATEST_TERMINAL_LOG
+        if LATEST_TERMINAL_LOG != Path(LEGACY_DEFAULTS.tmp_root) / "next-turn-latest.log"
+        else default_local_result_log_path(root_path)
+    )
+    command_report = (
+        root_path / LATEST_COMMAND_REPORT
+        if LATEST_COMMAND_REPORT != Path(LEGACY_DEFAULTS.tmp_root) / "next-turn-latest.json"
+        else load_workspace(root_path).tmp_file("next-turn-latest.json")
+    )
+
+    terminal_log.parent.mkdir(parents=True, exist_ok=True)
+    command_report.parent.mkdir(parents=True, exist_ok=True)
+
+    command_id = _command_id_from_yaml(yaml_path)
+
+    if not yaml_path.exists() or not script_path.exists():
+        result = NextTurnRunResult(
+            command_id=command_id,
+            outcome="FAIL_NO_FIXED_SLOT",
+            exit_code=2,
+            script_path=str(FIXED_SLOT_SCRIPT),
+            yaml_path=str(FIXED_SLOT_YAML),
+            terminal_log=str(terminal_log),
+            command_report=str(command_report),
+            timestamp_utc=datetime.now(timezone.utc).isoformat(),
+        )
+        terminal_log.write_text("NEXT_TURN_RUNNER\noutcome=FAIL_NO_FIXED_SLOT\n### RESULT: FAIL ###\n", encoding="utf-8")
+        command_report.write_text(json.dumps(asdict(result), indent=2, sort_keys=True) + "\n", encoding="utf-8")
+        return result
+
+    completed = subprocess.run(
+        [sys.executable, str(script_path)],
+        cwd=root_path,
+        text=True,
+        capture_output=True,
+        check=False,
+    )
+    output = (completed.stdout or "") + (completed.stderr or "")
+    terminal_log.write_text(output, encoding="utf-8")
+
+    outcome = "PASS_EXECUTED" if completed.returncode == 0 else "FAIL_EXECUTED"
+    result = NextTurnRunResult(
+        command_id=command_id,
+        outcome=outcome,
+        exit_code=completed.returncode,
+        script_path=str(FIXED_SLOT_SCRIPT),
+        yaml_path=str(FIXED_SLOT_YAML),
+        terminal_log=str(terminal_log),
+        command_report=str(command_report),
+        timestamp_utc=datetime.now(timezone.utc).isoformat(),
+    )
+    command_report.write_text(json.dumps(asdict(result), indent=2, sort_keys=True) + "\n", encoding="utf-8")
+    if outcome == "PASS_EXECUTED":
+        yaml_path.unlink(missing_ok=True)
+        script_path.unlink(missing_ok=True)
+    return result
+
+
+def render_result(result: NextTurnRunResult) -> str:
+    status = "PASS" if result.outcome == "PASS_EXECUTED" else "FAIL"
+    return "\n".join(
+        [
+            "NEXT_TURN_RUNNER",
+            f"command_id={result.command_id}",
+            f"outcome={result.outcome}",
+            f"exit_code={result.exit_code}",
+            f"terminal_log={result.terminal_log}",
+            f"command_report={result.command_report}",
+            f"subresult={status}",
+        ]
+    )
+
+
+def work_result_from_outcome(outcome: str) -> str:
+    return "PASS" if outcome == "PASS_EXECUTED" else "FAIL"
+
+
+def publish_run_evidence(result: NextTurnRunResult, *, run_id: str, push: bool = True) -> str:
+    plan = publish_and_stage_evidence(
+        run_id=run_id,
+        local_terminal_log=result.terminal_log,
+        work_result=work_result_from_outcome(result.outcome),
+    )
+    finalize_result = commit_and_push_evidence(plan=plan, push=push)
+    return render_finalize_result(finalize_result)
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(prog="next-turn-run")
+    parser.add_argument("--publish-evidence", action="store_true")
+    parser.add_argument("--run-id", default="")
+    parser.add_argument("--no-push", action="store_true")
+    args = parser.parse_args()
+    result = run_fixed_slot()
+    print(render_result(result))
+    if args.publish_evidence:
+        run_id = args.run_id or result.command_id
+        print(publish_run_evidence(result, run_id=run_id, push=not args.no_push))
+    return 0 if result.outcome == "PASS_EXECUTED" else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())