hunter-harness 0.1.3 → 0.2.1

package/resources/harness/general/scripts/harness_events.py

@@ -1,680 +0,0 @@
-#!/usr/bin/env python3
-"""Harness events.ndjson writer and execution-log renderer (D2).
-
-Subcommands:
-  append  — append one schema_version 2 event, then auto-render execution-log.md
-  render  — full re-render of logs/execution-log.md from events.ndjson
-  summary — phase durations, event counts, and issue list (JSON)
-
-Python 3.10+, stdlib only. UTF-8 without BOM. Windows path safe.
-"""
-
-from __future__ import annotations
-
-import argparse
-import contextlib
-import datetime as dt
-import json
-import os
-import sys
-import tempfile
-import time
-import uuid
-from pathlib import Path
-from typing import Any
-
-
-if hasattr(sys.stdout, "reconfigure"):
-    sys.stdout.reconfigure(encoding="utf-8")
-if hasattr(sys.stderr, "reconfigure"):
-    sys.stderr.reconfigure(encoding="utf-8")
-
-
-EVENT_TYPES = frozenset(
-    {
-        "phase.start",
-        "phase.end",
-        "command",
-        "verification",
-        "artifact",
-        "issue",
-        "decision",
-    }
-)
-
-SCHEMA_VERSION = 2
-HEADER_LINE = (
-    "本文件由 harness_events.py 自动渲染，请勿手工编辑；事实源为 events.ndjson"
-)
-
-# Optional fields accepted on append; only non-None values are written.
-OPTIONAL_FIELDS = (
-    "command",
-    "exit_code",
-    "duration_ms",
-    "note",
-    "name",
-    "status",
-    "path",
-    "kind",
-    "code",
-    "severity",
-    "message",
-    "decision",
-    "reason",
-)
-
-
-def now_iso() -> str:
-    return dt.datetime.now().astimezone().isoformat(timespec="milliseconds")
-
-
-def emit_json(payload: dict[str, Any], *, as_json: bool) -> None:
-    if as_json:
-        sys.stdout.write(json.dumps(payload, ensure_ascii=False, indent=2) + "\n")
-    else:
-        ok = payload.get("ok", True)
-        msg = payload.get("message") or payload.get("path") or ("ok" if ok else "error")
-        sys.stdout.write(f"{msg}\n")
-
-
-def emit_error(message: str, *, as_json: bool, code: int = 1) -> int:
-    payload = {"ok": False, "error": message}
-    if as_json:
-        sys.stderr.write(json.dumps(payload, ensure_ascii=False) + "\n")
-    else:
-        sys.stderr.write(f"error: {message}\n")
-    return code
-
-
-def resolve_change_dir(raw: str) -> Path:
-    return Path(raw).expanduser().resolve()
-
-
-def events_path(change_dir: Path) -> Path:
-    return change_dir / "events.ndjson"
-
-
-def execution_log_path(change_dir: Path) -> Path:
-    return change_dir / "logs" / "execution-log.md"
-
-
-def parse_timestamp(value: Any) -> dt.datetime | None:
-    if not isinstance(value, str) or not value.strip():
-        return None
-    text = value.strip()
-    if text.endswith("Z"):
-        text = text[:-1] + "+00:00"
-    try:
-        return dt.datetime.fromisoformat(text)
-    except ValueError:
-        return None
-
-
-def duration_ms_between(start: Any, end: Any) -> int | None:
-    start_dt = parse_timestamp(start)
-    end_dt = parse_timestamp(end)
-    if start_dt is None or end_dt is None:
-        return None
-    return max(0, int((end_dt - start_dt).total_seconds() * 1000))
-
-
-def normalize_event(raw: dict[str, Any]) -> dict[str, Any]:
-    """Normalize schema_version 1/2 events for rendering and summary."""
-    event = dict(raw)
-    version = event.get("schema_version", 1)
-    try:
-        version_int = int(version)
-    except (TypeError, ValueError):
-        version_int = 1
-    event["schema_version"] = version_int
-    if "note" not in event or event["note"] is None:
-        event["note"] = ""
-    return event
-
-
-def load_events(path: Path) -> list[dict[str, Any]]:
-    if not path.exists():
-        return []
-    events: list[dict[str, Any]] = []
-    text = path.read_text(encoding="utf-8-sig")
-    for line_no, line in enumerate(text.splitlines(), start=1):
-        stripped = line.strip()
-        if not stripped:
-            continue
-        try:
-            obj = json.loads(stripped)
-        except json.JSONDecodeError as exc:
-            raise ValueError(f"invalid JSON at {path} line {line_no}: {exc}") from exc
-        if not isinstance(obj, dict):
-            raise ValueError(f"event at {path} line {line_no} is not an object")
-        events.append(normalize_event(obj))
-    return events
-
-
-def atomic_append_line(path: Path, line: str) -> None:
-    """Write line to a temp file first, then append to the target (append-only)."""
-    path.parent.mkdir(parents=True, exist_ok=True)
-    payload = line if line.endswith("\n") else line + "\n"
-    # Ensure UTF-8 without BOM for the temp payload.
-    data = payload.encode("utf-8")
-    fd, tmp_name = tempfile.mkstemp(
-        prefix=f".{path.name}.",
-        suffix=".tmp",
-        dir=str(path.parent),
-    )
-    tmp_path = Path(tmp_name)
-    try:
-        with os.fdopen(fd, "wb") as tmp_f:
-            tmp_f.write(data)
-            tmp_f.flush()
-            os.fsync(tmp_f.fileno())
-        with path.open("ab") as out_f:
-            out_f.write(data)
-            out_f.flush()
-            os.fsync(out_f.fileno())
-    finally:
-        try:
-            tmp_path.unlink(missing_ok=True)
-        except OSError:
-            pass
-
-
-@contextlib.contextmanager
-def event_file_lock(lock_path: Path, timeout_seconds: float = 10.0):
-    """Acquire a cross-process exclusive lock or raise TimeoutError.
-
-    §6.2: Windows uses msvcrt.locking; POSIX uses fcntl.flock. The lock file is
-    ``<change-dir>/events.ndjson.lock``. On timeout the caller must fail non-zero
-    -- never continue without a lock. ``finally`` always unlocks and closes.
-    """
-    lock_path.parent.mkdir(parents=True, exist_ok=True)
-    # Ensure at least 1 byte exists; msvcrt.locking on an empty file can misbehave
-    # on some Windows versions.
-    if not lock_path.exists() or lock_path.stat().st_size == 0:
-        with open(lock_path, "ab") as seed_f:
-            seed_f.write(b"\0")
-    handle = open(lock_path, "r+b")
-    try:
-        handle.seek(0)
-        _acquire_file_lock(handle, lock_path, timeout_seconds)
-        try:
-            yield
-        finally:
-            _release_file_lock(handle)
-    finally:
-        handle.close()
-
-
-def _acquire_file_lock(handle, lock_path: Path, timeout_seconds: float) -> None:
-    deadline = time.monotonic() + timeout_seconds
-    if os.name == "nt":
-        import msvcrt
-
-        while True:
-            try:
-                msvcrt.locking(handle.fileno(), msvcrt.LK_NBLCK, 1)
-                return
-            except OSError:
-                if time.monotonic() >= deadline:
-                    raise TimeoutError(
-                        f"timeout acquiring event lock {lock_path} after {timeout_seconds}s"
-                    )
-                time.sleep(0.02)
-    else:
-        import fcntl
-
-        while True:
-            try:
-                fcntl.flock(handle.fileno(), fcntl.LOCK_EX | fcntl.LOCK_NB)
-                return
-            except OSError:
-                if time.monotonic() >= deadline:
-                    raise TimeoutError(
-                        f"timeout acquiring event lock {lock_path} after {timeout_seconds}s"
-                    )
-                time.sleep(0.02)
-
-
-def _release_file_lock(handle) -> None:
-    try:
-        if os.name == "nt":
-            import msvcrt
-
-            handle.seek(0)
-            msvcrt.locking(handle.fileno(), msvcrt.LK_UNLCK, 1)
-        else:
-            import fcntl
-
-            fcntl.flock(handle.fileno(), fcntl.LOCK_UN)
-    except OSError:
-        pass
-
-
-def new_event_id(existing: list[dict[str, Any]] | None = None) -> str:
-    """Return a full-entropy event id.
-
-    §6.2: UUID 不需要扫描历史去重；直接使用完整 ``uuid.uuid4().hex``。
-    ``existing`` is accepted for backward-compat callers but intentionally unused.
-    """
-    return f"evt-{uuid.uuid4().hex}"
-
-
-def build_event(args: argparse.Namespace, existing: list[dict[str, Any]]) -> dict[str, Any]:
-    event: dict[str, Any] = {
-        "schema_version": SCHEMA_VERSION,
-        "id": new_event_id(existing),
-        "timestamp": now_iso(),
-        "phase": args.phase,
-        "type": args.type,
-    }
-    for field in OPTIONAL_FIELDS:
-        value = getattr(args, field, None)
-        if value is None:
-            continue
-        event[field] = value
-    if "note" not in event:
-        event["note"] = ""
-    return event
-
-
-def status_symbol(status: Any, reason: Any = None) -> str:
-    text = str(status or "").strip().lower()
-    reason_text = str(reason or "").strip()
-    ok_set = {"ok", "passed", "pass", "success", "green", "✅", "✅ok"}
-    warn_set = {"warn", "warning", "yellow", "skipped", "skip", "🟡", "🟡warn"}
-    fail_set = {"fail", "failed", "error", "red", "blocked", "❌", "❌fail"}
-    if text in ok_set or text.startswith("ok") or "✅" in text:
-        return "✅OK"
-    if text in warn_set or "warn" in text or "🟡" in text:
-        return f"🟡WARN({reason_text})" if reason_text else "🟡WARN"
-    if text in fail_set or "fail" in text or "error" in text or "❌" in text:
-        return f"❌FAIL({reason_text})" if reason_text else "❌FAIL"
-    if reason_text:
-        return f"{status}({reason_text})"
-    return str(status or "unknown")
-
-
-def severity_symbol(severity: Any, message: Any = None) -> str:
-    text = str(severity or "").strip().lower()
-    msg = str(message or "").strip()
-    if text in {"error", "fail", "failed", "critical"}:
-        return f"❌FAIL({msg})" if msg else "❌FAIL"
-    if text in {"warn", "warning"}:
-        return f"🟡WARN({msg})" if msg else "🟡WARN"
-    if text in {"info", "ok", "note"}:
-        return f"✅OK({msg})" if msg else "✅OK"
-    return f"{severity}: {msg}" if msg else str(severity or "issue")
-
-
-def format_duration(ms: int | None) -> str:
-    if ms is None:
-        return "—"
-    if ms < 1000:
-        return f"{ms}ms"
-    seconds = ms / 1000
-    if seconds < 60:
-        return f"{seconds:.1f}s"
-    minutes = int(seconds // 60)
-    rem = seconds - minutes * 60
-    return f"{minutes}m{rem:04.1f}s"
-
-
-def group_events_by_phase(events: list[dict[str, Any]]) -> list[tuple[str, list[dict[str, Any]]]]:
-    """Preserve first-seen phase order; keep events in file order within each phase."""
-    order: list[str] = []
-    buckets: dict[str, list[dict[str, Any]]] = {}
-    for event in events:
-        phase = str(event.get("phase") or "unknown")
-        if phase not in buckets:
-            order.append(phase)
-            buckets[phase] = []
-        buckets[phase].append(event)
-    return [(phase, buckets[phase]) for phase in order]
-
-
-def phase_start_time(phase_events: list[dict[str, Any]]) -> str:
-    for event in phase_events:
-        if event.get("type") == "phase.start":
-            return str(event.get("timestamp") or "")
-    if phase_events:
-        return str(phase_events[0].get("timestamp") or "")
-    return ""
-
-
-def phase_duration_ms(phase_events: list[dict[str, Any]]) -> int | None:
-    start_ts = None
-    end_ts = None
-    for event in phase_events:
-        etype = event.get("type")
-        if etype == "phase.start" and start_ts is None:
-            start_ts = event.get("timestamp")
-        elif etype == "phase.end":
-            end_ts = event.get("timestamp")
-    if start_ts and end_ts:
-        return duration_ms_between(start_ts, end_ts)
-    # Fallback: first to last timestamp in the phase bucket.
-    stamps = [e.get("timestamp") for e in phase_events if e.get("timestamp")]
-    if len(stamps) >= 2:
-        return duration_ms_between(stamps[0], stamps[-1])
-    return None
-
-
-def render_command_block(commands: list[dict[str, Any]]) -> list[str]:
-    if not commands:
-        return []
-    if len(commands) == 1:
-        event = commands[0]
-        cmd = event.get("command") or ""
-        exit_code = event.get("exit_code")
-        exit_text = "?" if exit_code is None else str(exit_code)
-        duration = format_duration(
-            int(event["duration_ms"]) if isinstance(event.get("duration_ms"), int) else None
-        )
-        note = str(event.get("note") or "").strip()
-        parts = [f"- command: `{cmd}`", f"exit={exit_text}", f"duration={duration}"]
-        if note:
-            parts.append(f"note={note}")
-        return [" · ".join(parts)]
-
-    lines = [
-        "",
-        "| 命令 | exit | duration | note |",
-        "| --- | ---: | ---: | --- |",
-    ]
-    for event in commands:
-        cmd = str(event.get("command") or "").replace("|", "\\|")
-        exit_code = event.get("exit_code")
-        exit_text = "?" if exit_code is None else str(exit_code)
-        duration = format_duration(
-            int(event["duration_ms"]) if isinstance(event.get("duration_ms"), int) else None
-        )
-        note = str(event.get("note") or "").replace("|", "\\|")
-        lines.append(f"| `{cmd}` | {exit_text} | {duration} | {note} |")
-    lines.append("")
-    return lines
-
-
-def render_event_line(event: dict[str, Any]) -> list[str]:
-    etype = event.get("type")
-    if etype == "phase.start":
-        note = str(event.get("note") or "").strip()
-        suffix = f" — {note}" if note else ""
-        return [f"- phase.start @ {event.get('timestamp', '')}{suffix}"]
-    if etype == "phase.end":
-        note = str(event.get("note") or "").strip()
-        suffix = f" — {note}" if note else ""
-        return [f"- phase.end @ {event.get('timestamp', '')}{suffix}"]
-    if etype == "verification":
-        name = event.get("name") or "(unnamed)"
-        symbol = status_symbol(event.get("status"), event.get("reason") or event.get("note"))
-        return [f"- verification: {name} → {symbol}"]
-    if etype == "decision":
-        decision = event.get("decision") or ""
-        reason = event.get("reason") or event.get("note") or ""
-        if reason:
-            return [f"- decision: {decision} — {reason}"]
-        return [f"- decision: {decision}"]
-    if etype == "issue":
-        symbol = severity_symbol(event.get("severity"), event.get("message"))
-        code = event.get("code")
-        prefix = f"[{code}] " if code else ""
-        return [f"- issue: {prefix}{symbol}"]
-    if etype == "artifact":
-        path = event.get("path") or ""
-        kind = event.get("kind")
-        if kind:
-            return [f"- artifact: `{path}` ({kind})"]
-        return [f"- artifact: `{path}`"]
-    if etype == "command":
-        return render_command_block([event])
-    # Unknown types: skip from human log to keep size down.
-    return []
-
-
-def render_execution_log(events: list[dict[str, Any]]) -> str:
-    lines: list[str] = [
-        f"> [!warning] {HEADER_LINE}",
-        "",
-        "# Execution Log",
-        "",
-    ]
-    if not events:
-        lines.append("_（暂无事件）_")
-        lines.append("")
-        return "\n".join(lines)
-
-    for phase, phase_events in group_events_by_phase(events):
-        start = phase_start_time(phase_events) or "—"
-        duration = phase_duration_ms(phase_events)
-        lines.append(f"## {phase} — {start}")
-        lines.append("")
-        if duration is not None:
-            lines.append(f"- 阶段耗时: {format_duration(duration)}")
-        # Collapse consecutive commands into one table.
-        buffer: list[dict[str, Any]] = []
-
-        def flush_commands() -> None:
-            nonlocal buffer
-            if buffer:
-                lines.extend(render_command_block(buffer))
-                buffer = []
-
-        for event in phase_events:
-            if event.get("type") == "command":
-                buffer.append(event)
-                continue
-            flush_commands()
-            lines.extend(render_event_line(event))
-        flush_commands()
-        lines.append("")
-
-    return "\n".join(lines).rstrip() + "\n"
-
-
-def write_execution_log(change_dir: Path, content: str) -> Path:
-    path = execution_log_path(change_dir)
-    path.parent.mkdir(parents=True, exist_ok=True)
-    # UTF-8 without BOM
-    path.write_text(content, encoding="utf-8", newline="\n")
-    return path
-
-
-def build_summary(change_dir: Path, events: list[dict[str, Any]]) -> dict[str, Any]:
-    phases: dict[str, Any] = {}
-    issues: list[dict[str, Any]] = []
-
-    for phase, phase_events in group_events_by_phase(events):
-        start_ts = None
-        end_ts = None
-        for event in phase_events:
-            if event.get("type") == "phase.start" and start_ts is None:
-                start_ts = event.get("timestamp")
-            elif event.get("type") == "phase.end":
-                end_ts = event.get("timestamp")
-        duration = None
-        if start_ts and end_ts:
-            duration = duration_ms_between(start_ts, end_ts)
-        phases[phase] = {
-            "event_count": len(phase_events),
-            "started_at": start_ts,
-            "ended_at": end_ts,
-            "duration_ms": duration,
-        }
-
-    for event in events:
-        if event.get("type") != "issue":
-            continue
-        issues.append(
-            {
-                "id": event.get("id"),
-                "timestamp": event.get("timestamp"),
-                "phase": event.get("phase"),
-                "code": event.get("code"),
-                "severity": event.get("severity"),
-                "message": event.get("message"),
-            }
-        )
-
-    return {
-        "ok": True,
-        "change_dir": str(change_dir),
-        "event_count": len(events),
-        "phases": phases,
-        "issues": issues,
-    }
-
-
-def cmd_append(args: argparse.Namespace) -> int:
-    as_json = bool(args.json)
-    if args.type not in EVENT_TYPES:
-        return emit_error(
-            f"unsupported type: {args.type}; expected one of {sorted(EVENT_TYPES)}",
-            as_json=as_json,
-        )
-    change_dir = resolve_change_dir(args.change_dir)
-    path = events_path(change_dir)
-    lock_path = change_dir / "events.ndjson.lock"
-
-    # §6.1/§6.2: 普通 append = 加锁 -> 追加一行 -> fsync -> 解锁，不 load 历史、不渲染。
-    # new_event_id 用完整 uuid，无需扫描去重。锁覆盖 atomic_append_line 的
-    # open/write/flush/fsync 全过程。
-    event = build_event(args, [])
-    line = json.dumps(event, ensure_ascii=False, separators=(",", ":"))
-    try:
-        with event_file_lock(lock_path):
-            atomic_append_line(path, line)
-    except (OSError, TimeoutError) as exc:
-        return emit_error(f"append failed: {exc}", as_json=as_json)
-
-    # §6.1: phase.end append -> 追加成功后执行一次 render（从完整 events 重建 log）。
-    # 普通 command/issue 等 append 不渲染（O(1)）；显式 `render` 子命令随时重建。
-    rendered = False
-    log_path = None
-    log_lines = None
-    if args.type == "phase.end":
-        try:
-            events = load_events(path)
-            content = render_execution_log(events)
-            log_path = write_execution_log(change_dir, content)
-            log_lines = len(content.splitlines())
-            rendered = True
-        except (OSError, ValueError) as exc:
-            return emit_error(f"phase.end render failed: {exc}", as_json=as_json)
-
-    payload: dict[str, Any] = {
-        "ok": True,
-        "action": "append",
-        "event": event,
-        "events_path": str(path),
-        "rendered": rendered,
-    }
-    if log_path is not None:
-        payload["execution_log_path"] = str(log_path)
-        payload["execution_log_lines"] = log_lines
-    emit_json(payload, as_json=as_json)
-    return 0
-
-
-def cmd_render(args: argparse.Namespace) -> int:
-    as_json = bool(args.json)
-    change_dir = resolve_change_dir(args.change_dir)
-    path = events_path(change_dir)
-    try:
-        events = load_events(path)
-        content = render_execution_log(events)
-        log_path = write_execution_log(change_dir, content)
-    except (OSError, ValueError) as exc:
-        return emit_error(f"render failed: {exc}", as_json=as_json)
-
-    payload = {
-        "ok": True,
-        "action": "render",
-        "events_path": str(path),
-        "execution_log_path": str(log_path),
-        "event_count": len(events),
-        "execution_log_lines": len(content.splitlines()),
-    }
-    emit_json(payload, as_json=as_json)
-    return 0
-
-
-def cmd_summary(args: argparse.Namespace) -> int:
-    # Structured summary is always JSON (task card: summary --json).
-    change_dir = resolve_change_dir(args.change_dir)
-    path = events_path(change_dir)
-    try:
-        events = load_events(path)
-        payload = build_summary(change_dir, events)
-    except (OSError, ValueError) as exc:
-        return emit_error(f"summary failed: {exc}", as_json=True)
-
-    emit_json(payload, as_json=True)
-    return 0
-
-
-def build_parser() -> argparse.ArgumentParser:
-    common = argparse.ArgumentParser(add_help=False)
-    common.add_argument(
-        "--json",
-        action="store_true",
-        help="emit machine-readable JSON on stdout",
-    )
-
-    parser = argparse.ArgumentParser(
-        prog="harness_events.py",
-        description="Append/render/summarize harness change events.ndjson",
-        parents=[common],
-    )
-    sub = parser.add_subparsers(dest="command_name", required=True)
-
-    p_append = sub.add_parser(
-        "append",
-        parents=[common],
-        help="append one event and auto-render execution-log",
-    )
-    p_append.add_argument("--change-dir", required=True)
-    p_append.add_argument("--phase", required=True)
-    p_append.add_argument("--type", required=True)
-    p_append.add_argument("--command", default=None)
-    p_append.add_argument("--exit-code", type=int, default=None)
-    p_append.add_argument("--duration-ms", type=int, default=None)
-    p_append.add_argument("--note", default=None)
-    p_append.add_argument("--name", default=None)
-    p_append.add_argument("--status", default=None)
-    p_append.add_argument("--path", default=None)
-    p_append.add_argument("--kind", default=None)
-    p_append.add_argument("--code", default=None)
-    p_append.add_argument("--severity", default=None)
-    p_append.add_argument("--message", default=None)
-    p_append.add_argument("--decision", default=None)
-    p_append.add_argument("--reason", default=None)
-    p_append.set_defaults(func=cmd_append)
-
-    p_render = sub.add_parser(
-        "render",
-        parents=[common],
-        help="re-render execution-log.md from events.ndjson",
-    )
-    p_render.add_argument("--change-dir", required=True)
-    p_render.set_defaults(func=cmd_render)
-
-    p_summary = sub.add_parser(
-        "summary",
-        parents=[common],
-        help="summarize phases/issues from events.ndjson",
-    )
-    p_summary.add_argument("--change-dir", required=True)
-    p_summary.set_defaults(func=cmd_summary)
-
-    return parser
-
-
-def main(argv: list[str] | None = None) -> int:
-    parser = build_parser()
-    args = parser.parse_args(argv)
-    return int(args.func(args))
-
-
-if __name__ == "__main__":
-    raise SystemExit(main())