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

agentic_project_kit/entrypoint_slice_runner.py

@@ -0,0 +1,153 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+import re
+import subprocess
+from typing import Iterable, Literal
+
+StepClassification = Literal["PASS", "PENDING", "FAIL"]
+
+FAIL_RE = re.compile(r"### RESULT: (FAIL|NEEDS_HUMAN_REVIEW) ###|STATUS: (FAIL|NEEDS_HUMAN_REVIEW)|RESULT: (FAIL|NEEDS_HUMAN_REVIEW)")
+PENDING_RE = re.compile(r"### RESULT: (PENDING|WAIT) ###|STATUS: (PENDING|WAIT)|RESULT: (PENDING|WAIT)")
+PASS_RE = re.compile(
+    r"### RESULT: (PASS|DONE|NOOP|ALREADY_ON_MAIN|ALREADY_MERGED|ALREADY_RELEASED|DOI_VERIFIED|SUPERSEDED) ###"
+    r"|STATUS: (PASS|DONE|NOOP|ALREADY_ON_MAIN|ALREADY_MERGED|ALREADY_RELEASED|DOI_VERIFIED|SUPERSEDED)"
+    r"|RESULT: (PASS|DONE|NOOP|ALREADY_ON_MAIN|ALREADY_MERGED|ALREADY_RELEASED|DOI_VERIFIED|SUPERSEDED)"
+)
+
+
+@dataclass(frozen=True)
+class CommandStepResult:
+    number: int
+    command: str
+    exit_status: int
+    classification: StepClassification
+    output: str
+
+
+def classify_step_output(output: str, exit_status: int) -> StepClassification:
+    if FAIL_RE.search(output):
+        return "FAIL"
+    if PENDING_RE.search(output):
+        return "PENDING"
+    if PASS_RE.search(output):
+        return "PASS"
+    return "PASS" if exit_status == 0 else "FAIL"
+
+
+def load_plan(path: Path) -> list[str]:
+    if not path.exists():
+        raise FileNotFoundError(f"plan file not found: {path}")
+    commands: list[str] = []
+    for raw_line in path.read_text(encoding="utf-8").splitlines():
+        line = raw_line.strip()
+        if not line or line.startswith("#"):
+            continue
+        commands.append(raw_line)
+    return commands
+
+
+def run_command(repo_root: Path, command: str) -> tuple[int, str]:
+    completed = subprocess.run(
+        ["sh", "-c", command],
+        cwd=repo_root,
+        text=True,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.STDOUT,
+        check=False,
+    )
+    return completed.returncode, completed.stdout
+
+
+def run_steps(repo_root: Path, commands: Iterable[str]) -> tuple[int, list[CommandStepResult]]:
+    status = 0
+    results: list[CommandStepResult] = []
+    for index, command in enumerate(commands, start=1):
+        exit_status, output = run_command(repo_root, command)
+        classification = classify_step_output(output, exit_status)
+        results.append(CommandStepResult(index, command, exit_status, classification, output))
+        if classification == "PASS":
+            continue
+        status = 2 if classification == "PENDING" else 1
+        break
+    return status, results
+
+
+def _git(repo_root: Path, args: list[str]) -> tuple[int, str]:
+    completed = subprocess.run(
+        ["git", *args],
+        cwd=repo_root,
+        text=True,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.STDOUT,
+        check=False,
+    )
+    return completed.returncode, completed.stdout.strip()
+
+
+def render_run(plan_file: Path, results: list[CommandStepResult], final_status: int, branch: str, git_status: str) -> str:
+    lines = [
+        "",
+        "",
+        "",
+        "--------------------------------------------------------------------------------",
+        "--------------------------------------------------------------------------------",
+        "--------------------------------------------------------------------------------",
+        "",
+        "",
+        "",
+        "NS SLICE RUNNER",
+        "",
+        "### SAFETY ###",
+        "Safety: deterministic sequential runner; advances only after target-state PASS and stops immediately on retryable or failing states.",
+        f"plan={plan_file.as_posix()}",
+    ]
+    for result in results:
+        lines.extend(["", f"### STEP {result.number} ###", result.command])
+        if result.output:
+            lines.append(result.output.rstrip())
+        lines.append(f"STEP {result.number} RESULT: {result.classification}")
+        if result.classification == "PENDING":
+            lines.append("Stopping slice runner at retryable state; no dependent follow-up actions were run.")
+        elif result.classification == "FAIL":
+            lines.append("Stopping slice runner at first failing step.")
+    lines.extend(["", "### FINAL STATE ###", branch])
+    if git_status:
+        lines.append(git_status)
+    if final_status == 0:
+        lines.append("\n### RESULT: PASS ###")
+    elif final_status == 2:
+        lines.append("\n### RESULT: PENDING ###")
+    else:
+        lines.append("\n### RESULT: FAIL ###")
+    return "\n".join(lines)
+
+
+def run_slice(plan_file: Path, repo_root: Path) -> int:
+    try:
+        commands = load_plan(plan_file)
+    except FileNotFoundError:
+        print(f"ERROR: plan file not found: {plan_file}")
+        return 1
+    status, results = run_steps(repo_root, commands)
+    branch_rc, branch = _git(repo_root, ["branch", "--show-current"])
+    status_rc, git_status = _git(repo_root, ["status", "--short"])
+    final_status = status if branch_rc == 0 and status_rc == 0 else 1
+    print(render_run(plan_file, results, final_status, branch, git_status))
+    return final_status
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = argv if argv is not None else []
+    if not args:
+        print("ERROR: missing plan file. Usage: ./ns slice-runner <plan-file>")
+        print("Plan format: one shell command per line; blank lines and lines starting with # are ignored.")
+        return 1
+    return run_slice(Path(args[0]), Path(".").resolve())
+
+
+if __name__ == "__main__":
+    import sys
+
+    raise SystemExit(main(sys.argv[1:]))

agentic_project_kit/evidence_clean.py

@@ -0,0 +1,152 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+import shutil
+import subprocess
+
+
+TRACKED_WORKFLOW_EVIDENCE: tuple[str, ...] = (
+    ".agentic/workflow_state",
+    "docs/reports/CURRENT_WORKFLOW_OUTPUT.md",
+)
+
+
+@dataclass(frozen=True)
+class CleanCheckResult:
+    ok: bool
+    expected_log: str
+    unexpected_lines: tuple[str, ...]
+    raw_lines: tuple[str, ...]
+
+
+@dataclass(frozen=True)
+class EvidenceCleanResult:
+    ok: bool
+    before_status: tuple[str, ...]
+    restore_lines: tuple[str, ...]
+    removed_tmp_evidence: bool
+    untracked_doc_reports: tuple[str, ...]
+    after_status: tuple[str, ...]
+    errors: tuple[str, ...]
+
+
+def normalize_expected_log(repo_root: Path, expected_log: str | Path) -> str:
+    expected = Path(expected_log)
+    if expected.is_absolute():
+        expected = expected.resolve().relative_to(repo_root.resolve())
+    return expected.as_posix()
+
+
+def unexpected_status_lines(status_lines: list[str] | tuple[str, ...], expected_log: str) -> tuple[str, ...]:
+    allowed = "?? " + expected_log
+    unexpected: list[str] = []
+    for line in status_lines:
+        stripped = line.rstrip()
+        if stripped == "":
+            continue
+        if stripped == allowed:
+            continue
+        unexpected.append(stripped)
+    return tuple(unexpected)
+
+
+def _run_git(repo_root: Path, args: list[str]) -> tuple[int, str]:
+    completed = subprocess.run(
+        ["git", *args],
+        cwd=repo_root,
+        text=True,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.STDOUT,
+        check=False,
+    )
+    return completed.returncode, completed.stdout.strip()
+
+
+def read_git_status(repo_root: Path, *paths: str) -> tuple[str, ...]:
+    completed = subprocess.run(
+        ["git", "status", "--short", *paths],
+        cwd=repo_root,
+        text=True,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.STDOUT,
+        check=False,
+    )
+    if completed.returncode != 0:
+        return (completed.stdout.strip() or "git status failed",)
+    return tuple(line for line in completed.stdout.splitlines() if line.strip())
+
+
+def check_clean_except_expected_log(repo_root: Path, expected_log: str | Path) -> CleanCheckResult:
+    normalized = normalize_expected_log(repo_root, expected_log)
+    raw = read_git_status(repo_root)
+    unexpected = unexpected_status_lines(raw, normalized)
+    return CleanCheckResult(
+        ok=len(unexpected) == 0,
+        expected_log=normalized,
+        unexpected_lines=unexpected,
+        raw_lines=raw,
+    )
+
+
+def _path_is_tracked(repo_root: Path, path: str) -> bool:
+    returncode, _ = _run_git(repo_root, ["ls-files", "--error-unmatch", path])
+    return returncode == 0
+
+
+def _path_is_dirty(repo_root: Path, path: str) -> bool:
+    worktree_rc, _ = _run_git(repo_root, ["diff", "--quiet", "--", path])
+    index_rc, _ = _run_git(repo_root, ["diff", "--cached", "--quiet", "--", path])
+    return worktree_rc != 0 or index_rc != 0
+
+
+def _restore_known_tracked_workflow_evidence(repo_root: Path) -> tuple[tuple[str, ...], tuple[str, ...]]:
+    lines: list[str] = []
+    errors: list[str] = []
+    for path in TRACKED_WORKFLOW_EVIDENCE:
+        if not _path_is_tracked(repo_root, path):
+            lines.append(f"skip_untracked_path={path}")
+            continue
+        if not _path_is_dirty(repo_root, path):
+            lines.append(f"clean_tracked={path}")
+            continue
+        lines.append(f"restore_tracked={path}")
+        returncode, output = _run_git(repo_root, ["restore", "--staged", "--worktree", path])
+        if returncode != 0:
+            errors.append(output or f"git restore failed for {path}")
+    return tuple(lines), tuple(errors)
+
+
+def _remove_ignored_tmp_evidence(repo_root: Path) -> bool:
+    target = repo_root / "tmp" / "agent-evidence"
+    if not target.exists():
+        return False
+    shutil.rmtree(target)
+    return True
+
+
+def _untracked_doc_reports(repo_root: Path) -> tuple[str, ...]:
+    return tuple(line for line in read_git_status(repo_root, "docs/reports") if line.startswith("?? "))
+
+
+def clean_local_evidence(repo_root: Path) -> EvidenceCleanResult:
+    before = read_git_status(repo_root)
+    restore_lines, restore_errors = _restore_known_tracked_workflow_evidence(repo_root)
+    errors = list(restore_errors)
+    try:
+        removed_tmp = _remove_ignored_tmp_evidence(repo_root)
+    except OSError as exc:
+        removed_tmp = False
+        errors.append(str(exc))
+    untracked_reports = _untracked_doc_reports(repo_root)
+    after = read_git_status(repo_root)
+    ok = not errors and not untracked_reports
+    return EvidenceCleanResult(
+        ok=ok,
+        before_status=before,
+        restore_lines=restore_lines,
+        removed_tmp_evidence=removed_tmp,
+        untracked_doc_reports=untracked_reports,
+        after_status=after,
+        errors=tuple(errors),
+    )

agentic_project_kit/evidence_commit_paths.py

@@ -0,0 +1,214 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+import subprocess
+
+from agentic_project_kit.safe_push import safe_push
+
+
+@dataclass(frozen=True)
+class EvidenceCommitPathsResult:
+    success: bool
+    branch: str
+    head_before: str
+    commit_sha: str
+    paths: tuple[str, ...]
+    log_path: str | None
+    findings: tuple[str, ...]
+
+
+def _run_git(root: Path, args: list[str]) -> subprocess.CompletedProcess[str]:
+    return subprocess.run(["git", *args], cwd=root, text=True, capture_output=True, check=False)
+
+
+def _git_stdout(root: Path, args: list[str]) -> str:
+    result = _run_git(root, args)
+    if result.returncode != 0:
+        return ""
+    return result.stdout.strip()
+
+
+def _status_lines(root: Path) -> tuple[str, ...]:
+    result = _run_git(root, ["status", "--short", "--untracked-files=all"])
+    if result.returncode != 0:
+        return ()
+    return tuple(line for line in result.stdout.splitlines() if line.strip())
+
+
+def _path_is_dirty(status_line: str, rel_path: str) -> bool:
+    return status_line.strip().endswith(rel_path)
+
+
+def commit_paths(
+    *,
+    root: Path | str = Path("."),
+    paths: tuple[str, ...],
+    message: str,
+    log_path: str | None = None,
+    push: bool = False,
+    required_branch: str = "",
+    allow_main: bool = False,
+) -> EvidenceCommitPathsResult:
+    root_path = Path(root).resolve()
+    if not paths:
+        raise ValueError("at least one path is required")
+    if log_path:
+        if Path(log_path).is_absolute():
+            raise ValueError("log_path must be repository-relative")
+        if not log_path.startswith("docs/reports/terminal/"):
+            raise ValueError("log_path must start with docs/reports/terminal/")
+        if log_path not in paths:
+            paths = (*paths, log_path)
+
+    normalized_paths = tuple(dict.fromkeys(paths))
+    for rel in normalized_paths:
+        if Path(rel).is_absolute():
+            raise ValueError(f"path must be repository-relative: {rel}")
+        if rel.startswith(".git/") or rel == ".git":
+            raise ValueError(".git paths are not allowed")
+        if rel.startswith(".venv/") or rel == ".venv":
+            raise ValueError(".venv paths are not allowed")
+
+    branch = _git_stdout(root_path, ["branch", "--show-current"]) or "UNKNOWN"
+    if required_branch and branch != required_branch:
+        raise ValueError(f"current branch {branch!r} does not match required branch {required_branch!r}")
+    if branch == "main" and not allow_main:
+        raise ValueError("evidence commit-paths refuses to commit on main without --allow-main")
+    head_before = _git_stdout(root_path, ["rev-parse", "HEAD"]) or "UNKNOWN"
+    status_before = _status_lines(root_path)
+
+    if push:
+        push_preflight = safe_push(
+            root_path,
+            target_branch=branch,
+            purpose="evidence commit-paths publish branch",
+            dry_run=True,
+        )
+        if not push_preflight.ok:
+            return EvidenceCommitPathsResult(
+                False,
+                branch,
+                head_before,
+                "",
+                normalized_paths,
+                log_path,
+                tuple(["push preflight blocked evidence commit", *push_preflight.reasons]),
+            )
+
+    unexpected = [
+        line for line in status_before
+        if not any(_path_is_dirty(line, rel) for rel in normalized_paths)
+    ]
+    if unexpected:
+        return EvidenceCommitPathsResult(
+            False,
+            branch,
+            head_before,
+            "",
+            normalized_paths,
+            log_path,
+            tuple(["unexpected dirty paths before commit", *unexpected]),
+        )
+
+    deletion_lines = {line[3:] for line in status_before if line.startswith(" D ") or line.startswith("D  ")}
+    missing = [
+        rel for rel in normalized_paths
+        if not (root_path / rel).exists() and rel not in deletion_lines
+    ]
+    if missing:
+        return EvidenceCommitPathsResult(
+            False,
+            branch,
+            head_before,
+            "",
+            normalized_paths,
+            log_path,
+            tuple(f"missing path: {rel}" for rel in missing),
+        )
+
+    add_result = _run_git(root_path, ["add", "-A", "--", *normalized_paths])
+    if add_result.returncode != 0:
+        return EvidenceCommitPathsResult(
+            False,
+            branch,
+            head_before,
+            "",
+            normalized_paths,
+            log_path,
+            (add_result.stderr.strip() or add_result.stdout.strip() or "git add failed",),
+        )
+
+    diff_result = _run_git(root_path, ["diff", "--cached", "--quiet"])
+    if diff_result.returncode == 0:
+        return EvidenceCommitPathsResult(
+            True,
+            branch,
+            head_before,
+            head_before,
+            normalized_paths,
+            log_path,
+            ("no staged diff; no commit created",),
+        )
+
+    commit_result = _run_git(root_path, ["commit", "-m", message])
+    if commit_result.returncode != 0:
+        return EvidenceCommitPathsResult(
+            False,
+            branch,
+            head_before,
+            "",
+            normalized_paths,
+            log_path,
+            (commit_result.stderr.strip() or commit_result.stdout.strip() or "git commit failed",),
+        )
+
+    commit_sha = _git_stdout(root_path, ["rev-parse", "HEAD"]) or "UNKNOWN"
+    if push:
+        push_result = safe_push(
+            root_path,
+            target_branch=branch,
+            purpose="evidence commit-paths publish branch",
+        )
+        if not push_result.ok:
+            return EvidenceCommitPathsResult(
+                False,
+                branch,
+                head_before,
+                commit_sha,
+                normalized_paths,
+                log_path,
+                (push_result.stderr.strip() or push_result.stdout.strip() or "git push failed",),
+            )
+
+    status_after = _status_lines(root_path)
+    if status_after:
+        return EvidenceCommitPathsResult(
+            False,
+            branch,
+            head_before,
+            commit_sha,
+            normalized_paths,
+            log_path,
+            tuple(["dirty worktree after commit", *status_after]),
+        )
+
+    return EvidenceCommitPathsResult(True, branch, head_before, commit_sha, normalized_paths, log_path, ())
+
+
+def render_commit_paths_result(result: EvidenceCommitPathsResult) -> str:
+    lines = [
+        "EVIDENCE_COMMIT_PATHS",
+        f"success={'yes' if result.success else 'no'}",
+        f"branch={result.branch}",
+        f"head_before={result.head_before}",
+        f"commit_sha={result.commit_sha or 'NONE'}",
+    ]
+    if result.log_path:
+        lines.append(f"log_path={result.log_path}")
+    for path in result.paths:
+        lines.append(f"path={path}")
+    for finding in result.findings:
+        lines.append(f"finding={finding}")
+    lines.append(f"### RESULT: {'PASS' if result.success else 'FAIL'} ###")
+    return "\n".join(lines)