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

agentic_project_kit/terminal_logging.py

@@ -0,0 +1,275 @@
+"""Terminal log wrapper utilities for local workflow runs.
+
+The module supports a deterministic handoff protocol:
+- run a command while teeing stdout/stderr to a terminal log,
+- keep a pointer to the latest terminal log,
+- inspect upload readiness,
+- upload only terminal-log artifacts on failure handoff.
+"""
+
+from __future__ import annotations
+
+import datetime as _dt
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+from agentic_project_kit.safe_push import safe_push
+from agentic_project_kit.workspace import LEGACY_DEFAULTS, load_workspace
+
+TERMINAL_DIR = Path(LEGACY_DEFAULTS.terminal_reports_root)
+LATEST_POINTER = TERMINAL_DIR / "LATEST_TERMINAL_LOG.txt"
+
+
+def _safe_name(name: str) -> str:
+    safe = "".join(ch if ch.isalnum() or ch in "-_" else "_" for ch in name.strip())
+    return safe or "run"
+
+
+def _terminal_dir(root: Path = Path(".")) -> Path:
+    if TERMINAL_DIR != Path(LEGACY_DEFAULTS.terminal_reports_root):
+        return TERMINAL_DIR
+    return load_workspace(root).terminal_reports_dir()
+
+
+def _latest_pointer(root: Path = Path(".")) -> Path:
+    if LATEST_POINTER != TERMINAL_DIR / "LATEST_TERMINAL_LOG.txt":
+        return LATEST_POINTER
+    return load_workspace(root).latest_terminal_log_pointer()
+
+
+def make_log_path(name: str, now: _dt.datetime | None = None) -> Path:
+    current = now or _dt.datetime.now()
+    stamp = current.strftime("%Y%m%d-%H%M%S")
+    return _terminal_dir() / f"{stamp}_{_safe_name(name)}.log"
+
+
+def write_latest_pointer(log_path: Path) -> None:
+    pointer = _latest_pointer()
+    pointer.parent.mkdir(parents=True, exist_ok=True)
+    pointer.write_text(log_path.as_posix() + "\n", encoding="utf-8")
+
+
+def read_latest_pointer() -> Path | None:
+    pointer = _latest_pointer()
+    if not pointer.exists():
+        return None
+    value = pointer.read_text(encoding="utf-8").strip()
+    if not value:
+        return None
+    return Path(value)
+
+
+def _is_allowed_terminal_artifact(path_text: str) -> bool:
+    workspace = load_workspace(Path("."))
+    latest = workspace.path_text(_latest_pointer())
+    terminal_dir = workspace.path_text(_terminal_dir())
+    return path_text == latest or (path_text.startswith(terminal_dir + "/") and path_text.endswith(".log"))
+
+
+def git_dirty_paths() -> list[str]:
+    proc = subprocess.run(["git", "status", "--porcelain"], text=True, capture_output=True, check=False)
+    paths: list[str] = []
+    for line in proc.stdout.splitlines():
+        if not line.strip():
+            continue
+        paths.append(line[3:])
+    return paths
+
+
+
+
+def terminal_clean_check() -> tuple[str, str]:
+    """Classify dirty state while allowing terminal-log artifacts."""
+
+    dirty = git_dirty_paths()
+    if not dirty:
+        return "PASS_CLEAN", "Working tree is clean."
+    forbidden = [path for path in dirty if not _is_allowed_terminal_artifact(path)]
+    if forbidden:
+        return "FAIL_DIRTY_NON_LOG_FILES", chr(10).join(forbidden)
+    return "PASS_ONLY_TERMINAL_LOG_DIRTY", chr(10).join(dirty)
+
+
+def remote_mutation_preflight() -> tuple[str, str]:
+    """Require a fully clean worktree before remote mutations or merge/sync verification."""
+
+    dirty = git_dirty_paths()
+    if dirty:
+        return "FAIL_DIRTY_WORKTREE_BEFORE_REMOTE_MUTATION", chr(10).join(dirty)
+    return "PASS_CLEAN_FOR_REMOTE_MUTATION", "Working tree is clean for remote mutation or merge verification."
+def terminal_status() -> tuple[str, str]:
+    latest = read_latest_pointer()
+    if latest is None:
+        return "PASS_NO_LOG", "No latest terminal log pointer exists."
+    if not latest.exists():
+        return "FAIL_INVALID_POINTER", f"Latest terminal log pointer targets missing file: {latest.as_posix()}"
+    return "PASS_LOG_READY", f"Latest terminal log: {latest.as_posix()}"
+
+
+def _has_result_marker(text: str) -> bool:
+    return "### RESULT: PASS ###" in text or "### RESULT: FAIL ###" in text or "### RESULT: PENDING ###" in text
+
+
+def finalize_terminal_log(tmp_log: Path, name: str) -> tuple[str, str]:
+    source = Path(tmp_log)
+    if not source.exists():
+        return "FAIL_SOURCE_MISSING", source.as_posix()
+    source_text = source.read_text(encoding="utf-8")
+    if not _has_result_marker(source_text):
+        return "FAIL_MISSING_RESULT_MARKER", source.as_posix()
+    source_resolved = source.resolve()
+    terminal_dir = _terminal_dir()
+    terminal_resolved = terminal_dir.resolve()
+    try:
+        source_resolved.relative_to(terminal_resolved)
+    except ValueError:
+        source_inside_terminal_dir = False
+    else:
+        source_inside_terminal_dir = True
+    if source_inside_terminal_dir:
+        return "FAIL_SOURCE_INSIDE_TERMINAL_DIR", source.as_posix()
+    terminal_dir.mkdir(parents=True, exist_ok=True)
+    target = make_log_path(name)
+    target.write_text(source_text, encoding="utf-8")
+    write_latest_pointer(target)
+    return "PASS_FINALIZED", target.as_posix()
+
+
+def run_logged(name: str, command: list[str]) -> int:
+    if not command:
+        print("FAIL_NO_COMMAND")
+        return 2
+    _terminal_dir().mkdir(parents=True, exist_ok=True)
+    log_path = make_log_path(name)
+    write_latest_pointer(log_path)
+    with log_path.open("w", encoding="utf-8") as log:
+        def emit(line: str) -> None:
+            print(line)
+            log.write(line + "\n")
+            log.flush()
+        emit(f"terminal_log={log_path.as_posix()}")
+        emit("### RUN: " + " ".join(command))
+        proc = subprocess.Popen(command, stdout=subprocess.PIPE, stderr=subprocess.STDOUT, text=True, env=os.environ.copy())
+        assert proc.stdout is not None
+        for raw in proc.stdout:
+            line = raw.rstrip("\n")
+            print(line)
+            log.write(line + "\n")
+        code = proc.wait()
+        emit(f"### EXIT: {code}")
+        emit("### RESULT: PASS ###" if code == 0 else "### RESULT: FAIL ###")
+    return code
+
+
+def _current_branch() -> str:
+    proc = subprocess.run(["git", "branch", "--show-current"], text=True, capture_output=True, check=False)
+    return proc.stdout.strip() if proc.returncode == 0 else ""
+
+
+def _refuse_unsafe_mutation_branch(required_branch: str = "", allow_main: bool = False) -> tuple[bool, str]:
+    branch = _current_branch()
+    if required_branch and branch != required_branch:
+        return False, f"FAIL_BRANCH_MISMATCH actual={branch or 'UNKNOWN'} required={required_branch}"
+    if branch == "main" and not allow_main:
+        return False, "FAIL_MAIN_MUTATION_NOT_ALLOWED"
+    if not branch:
+        return False, "FAIL_NO_CURRENT_BRANCH"
+    return True, branch
+
+
+def upload_terminal_output(required_branch: str = "", allow_main: bool = False) -> int:
+    branch_ok, branch_message = _refuse_unsafe_mutation_branch(required_branch=required_branch, allow_main=allow_main)
+    if not branch_ok:
+        print(branch_message)
+        return 1
+    outcome, message = terminal_status()
+    print(outcome)
+    print(message)
+    if outcome != "PASS_LOG_READY":
+        return 1
+    dirty = git_dirty_paths()
+    forbidden = [p for p in dirty if not _is_allowed_terminal_artifact(p)]
+    if forbidden:
+        print("FAIL_DIRTY_NON_LOG_FILES")
+        for item in forbidden:
+            print(item)
+        return 1
+    push_preflight = safe_push(
+        Path("."),
+        target_branch=branch_message,
+        purpose="upload terminal output log",
+        dry_run=True,
+    )
+    if not push_preflight.ok:
+        print("FAIL_PUSH_PREFLIGHT_BLOCKED")
+        for reason in push_preflight.reasons:
+            print(reason)
+        return push_preflight.returncode
+    latest = read_latest_pointer()
+    assert latest is not None
+    subprocess.run(["git", "add", latest.as_posix(), _latest_pointer().as_posix()], check=True)
+    diff = subprocess.run(["git", "diff", "--cached", "--quiet"], check=False)
+    if diff.returncode == 0:
+        print("PASS_ALREADY_UPLOADED")
+        return 0
+    subprocess.run(["git", "commit", "-m", "Upload terminal output log"], check=True)
+    pushed = safe_push(
+        Path("."),
+        target_branch=branch_message,
+        purpose="upload terminal output log",
+    )
+    if not pushed.ok:
+        print("FAIL_PUSH_FAILED")
+        return pushed.returncode
+    print("PASS_UPLOADED")
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = list(sys.argv[1:] if argv is None else argv)
+    if not args:
+        print("Usage: terminal_logging.py run-logged <name> -- <command...> | terminal-status | terminal-upload")
+        return 2
+    mode = args.pop(0)
+    if mode == "terminal-status":
+        outcome, message = terminal_status()
+        print(outcome)
+        print(message)
+        return 0 if outcome.startswith("PASS") else 1
+    if mode == "terminal-clean-check":
+        outcome, message = terminal_clean_check()
+        print(outcome)
+        print(message)
+        return 0 if outcome.startswith("PASS") else 1
+    if mode == "terminal-remote-preflight":
+        outcome, message = remote_mutation_preflight()
+        print(outcome)
+        print(message)
+        return 0 if outcome.startswith("PASS") else 1
+    if mode == "terminal-upload":
+        return upload_terminal_output()
+    if mode == "terminal-finalize":
+        if len(args) != 2:
+            print("FAIL_USAGE")
+            print("Usage: terminal-finalize <tmp-log> <name>")
+            return 2
+        outcome, message = finalize_terminal_log(Path(args[0]), args[1])
+        print(outcome)
+        print(message)
+        return 0 if outcome == "PASS_FINALIZED" else 1
+    if mode == "run-logged":
+        if "--" not in args:
+            print("FAIL_MISSING_SEPARATOR")
+            return 2
+        sep = args.index("--")
+        name = args[0] if sep > 0 else "run"
+        command = args[sep + 1:]
+        return run_logged(name, command)
+    print("FAIL_UNKNOWN_MODE")
+    return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

agentic_project_kit/todo.py

@@ -0,0 +1,97 @@
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from agentic_project_kit.workspace import LEGACY_DEFAULTS, load_workspace
+
+DEFAULT_TODO_PATH = Path(".agentic/todo.yaml")
+DEFAULT_RENDER_PATH = Path(LEGACY_DEFAULTS.docs_root) / "TODO.md"
+
+
+def load_todo(path: Path = DEFAULT_TODO_PATH) -> dict[str, Any]:
+    if not path.exists():
+        raise FileNotFoundError(f"TODO file not found: {path}")
+    data = yaml.safe_load(path.read_text(encoding="utf-8")) or {}
+    items = data.get("items")
+    if not isinstance(items, list):
+        raise ValueError(f"TODO file must contain an 'items' list: {path}")
+    return data
+
+
+def save_todo(data: dict[str, Any], path: Path = DEFAULT_TODO_PATH) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(
+        yaml.safe_dump(data, sort_keys=False, allow_unicode=True),
+        encoding="utf-8",
+    )
+
+
+def list_items(data: dict[str, Any], include_done: bool = False) -> list[dict[str, Any]]:
+    items = data.get("items", [])
+    if include_done:
+        return list(items)
+    return [item for item in items if item.get("status", "open") != "done"]
+
+
+def complete_item(
+    item_id: str,
+    evidence: str,
+    path: Path = DEFAULT_TODO_PATH,
+) -> dict[str, Any]:
+    data = load_todo(path)
+    for item in data["items"]:
+        if item.get("id") == item_id:
+            item["status"] = "done"
+            item["evidence"] = evidence
+            item["completed_at"] = datetime.now(timezone.utc).replace(microsecond=0).isoformat()
+            save_todo(data, path)
+            return item
+    raise KeyError(f"TODO item not found: {item_id}")
+
+
+def render_markdown(
+    todo_path: Path = DEFAULT_TODO_PATH,
+    output_path: Path = DEFAULT_RENDER_PATH,
+) -> str:
+    data = load_todo(todo_path)
+    if output_path == DEFAULT_RENDER_PATH:
+        output_path = load_workspace(Path(".")).docs_file("TODO.md")
+    lines: list[str] = [
+        "# TODO",
+        "",
+        "This file is generated from `.agentic/todo.yaml`.",
+        "",
+        "## Items",
+        "",
+    ]
+
+    for item in data["items"]:
+        done = item.get("status") == "done"
+        marker = "x" if done else " "
+        item_id = item.get("id", "UNKNOWN")
+        title = item.get("title", "")
+        owner = item.get("owner", "unknown")
+        priority = item.get("priority", "normal")
+        evidence_required = item.get("evidence_required", "")
+        evidence = item.get("evidence", "")
+        completed_at = item.get("completed_at", "")
+
+        lines.append(f"- [{marker}] **{item_id}** {title}  ")
+        lines.append(f"  Owner: {owner}  ")
+        lines.append(f"  Priority: {priority}  ")
+        if evidence_required:
+            lines.append(f"  Evidence required: `{evidence_required}`  ")
+        if evidence:
+            lines.append(f"  Evidence: `{evidence}`  ")
+        if completed_at:
+            lines.append(f"  Completed at: `{completed_at}`  ")
+        lines.append("")
+
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    text = "\n".join(lines).rstrip() + "\n"
+    output_path.write_text(text, encoding="utf-8")
+    return text

agentic_project_kit/transfer_closeout.py

@@ -0,0 +1,136 @@
+from __future__ import annotations
+
+import json
+import shutil
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from agentic_project_kit.transfer_state import build_transfer_state
+from agentic_project_kit.workspace import LEGACY_DEFAULTS, load_workspace
+
+
+LATEST_COMMAND_RUN = Path(LEGACY_DEFAULTS.command_runs_root) / "LATEST_COMMAND_RUN.txt"
+TRANSFER_ROOT = Path(".agentic/transfer")
+
+
+@dataclass(frozen=True)
+class TransferCloseout:
+    schema_version: int
+    removed_transfer_dir: bool
+    latest_command_run_path: str | None
+    latest_report_exists: bool
+    allowed_dirty_paths: list[str]
+    blocked_dirty_paths: list[str]
+    state: dict[str, Any]
+    result_status: str
+    returncode: int
+    next_action: str
+
+    def as_json_data(self) -> dict[str, Any]:
+        return {
+            "schema_version": self.schema_version,
+            "removed_transfer_dir": self.removed_transfer_dir,
+            "latest_command_run_path": self.latest_command_run_path,
+            "latest_report_exists": self.latest_report_exists,
+            "allowed_dirty_paths": self.allowed_dirty_paths,
+            "blocked_dirty_paths": self.blocked_dirty_paths,
+            "state": self.state,
+            "result_status": self.result_status,
+            "returncode": self.returncode,
+            "next_action": self.next_action,
+        }
+
+
+def _git_status_short(root: Path) -> list[str]:
+    process = subprocess.run(
+        ["git", "status", "--short", "--untracked-files=all"],
+        cwd=root,
+        text=True,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        check=False,
+    )
+    if process.returncode != 0:
+        raise RuntimeError(f"git status failed: {process.stderr.strip()}")
+    return [line.rstrip() for line in process.stdout.splitlines() if line.strip()]
+
+
+def _status_path(line: str) -> str:
+    # Handles normal short status lines. Rename lines are intentionally treated by their final token.
+    return line[3:].strip().split(" -> ")[-1]
+
+
+def _is_allowed_dirty(path: str, latest_report_path: str | None, latest_command_run: str) -> bool:
+    if path == latest_command_run:
+        return True
+    if latest_report_path and path == latest_report_path:
+        return True
+    return False
+
+
+def _read_latest_report_path(root: Path) -> tuple[str | None, bool]:
+    latest = load_workspace(root).latest_command_run_pointer()
+    if not latest.exists():
+        return None, False
+    value = latest.read_text(encoding="utf-8").strip()
+    if not value:
+        return None, False
+    report_path = value.splitlines()[-1].strip()
+    return report_path, (root / report_path).exists()
+
+
+def closeout_transfer(project_root: Path = Path("."), remove_transfer_dir: bool = True) -> TransferCloseout:
+    root = project_root.resolve()
+    removed = False
+
+    if remove_transfer_dir and (root / TRANSFER_ROOT).exists():
+        shutil.rmtree(root / TRANSFER_ROOT)
+        removed = True
+
+    latest_report_path, latest_report_exists = _read_latest_report_path(root)
+    workspace = load_workspace(root)
+    latest_command_run = workspace.path_text(workspace.latest_command_run_pointer())
+
+    status_lines = _git_status_short(root)
+    allowed: list[str] = []
+    blocked: list[str] = []
+    for line in status_lines:
+        path = _status_path(line)
+        if _is_allowed_dirty(path, latest_report_path, latest_command_run):
+            allowed.append(path)
+        else:
+            blocked.append(path)
+
+    state = build_transfer_state(root).as_json_data()
+
+    if blocked:
+        result_status = "BLOCKED"
+        returncode = 1
+        next_action = "Review blocked dirty paths before committing or running another transfer."
+    else:
+        result_status = "PASS"
+        returncode = 0
+        next_action = "Review allowed dirty evidence paths, then run project gates before commit."
+
+    return TransferCloseout(
+        schema_version=1,
+        removed_transfer_dir=removed,
+        latest_command_run_path=latest_report_path,
+        latest_report_exists=latest_report_exists,
+        allowed_dirty_paths=allowed,
+        blocked_dirty_paths=blocked,
+        state=state,
+        result_status=result_status,
+        returncode=returncode,
+        next_action=next_action,
+    )
+
+
+def closeout_transfer_json(project_root: Path = Path("."), remove_transfer_dir: bool = True) -> str:
+    return json.dumps(
+        closeout_transfer(project_root, remove_transfer_dir=remove_transfer_dir).as_json_data(),
+        indent=2,
+        sort_keys=True,
+    )