prizmkit 1.1.57 → 1.1.60

package/bundled/dev-pipeline-windows/scripts/update-checkpoint.py

@@ -0,0 +1,173 @@
+#!/usr/bin/env python3
+"""Safely update a workflow-checkpoint.json step status.
+
+Instead of having the AI hand-write JSON, this script reads the checkpoint,
+validates the update, and writes it back atomically.
+
+Usage:
+  python3 update-checkpoint.py --checkpoint-path <path> --step <skill-or-id> --status <status>
+  python3 update-checkpoint.py --checkpoint-path <path> --step prizmkit-implement --status completed
+  python3 update-checkpoint.py --checkpoint-path <path> --step S04 --status in_progress
+  python3 update-checkpoint.py --checkpoint-path <path> --step prizmkit-code-review --status failed --note "max rounds exhausted"
+
+Exit codes:
+  0 = success
+  1 = validation error (step not found, invalid status, etc.)
+  2 = file error (not found, corrupted JSON)
+
+Output (stdout): JSON with {ok: true, step_id, skill, old_status, new_status} or {ok: false, error}
+"""
+
+import argparse
+import json
+import os
+import sys
+import tempfile
+
+VALID_STATUSES = {"pending", "in_progress", "completed", "skipped", "failed"}
+
+
+def _load_checkpoint(path):
+    """Load checkpoint JSON. Returns (data, error_string)."""
+    if not os.path.isfile(path):
+        return None, "File not found: {}".format(path)
+    try:
+        with open(path, "r", encoding="utf-8") as f:
+            data = json.load(f)
+    except json.JSONDecodeError as e:
+        return None, "Corrupted JSON: {}".format(e)
+    except IOError as e:
+        return None, "Cannot read file: {}".format(e)
+
+    if "steps" not in data or not isinstance(data["steps"], list):
+        return None, "Invalid checkpoint: missing 'steps' array"
+    return data, None
+
+
+def _write_checkpoint(path, data):
+    """Write checkpoint JSON atomically using a temp file + rename."""
+    parent = os.path.dirname(os.path.abspath(path))
+    if parent and not os.path.isdir(parent):
+        os.makedirs(parent, exist_ok=True)
+
+    tmp_path = None
+    try:
+        fd, tmp_path = tempfile.mkstemp(
+            dir=parent, suffix=".tmp", prefix=".checkpoint-"
+        )
+        with os.fdopen(fd, "w", encoding="utf-8") as f:
+            json.dump(data, f, indent=2, ensure_ascii=False)
+            f.write("\n")
+        os.replace(tmp_path, os.path.abspath(path))
+    except (IOError, OSError) as e:
+        # Clean up temp file on error
+        if tmp_path is not None and os.path.exists(tmp_path):
+            os.unlink(tmp_path)
+        return "Cannot write file: {}".format(e)
+    return None
+
+
+def _find_step(steps, identifier):
+    """Find a step by skill name or step ID.
+
+    Returns (index, step_dict) or (None, None).
+    """
+    for i, step in enumerate(steps):
+        if step.get("skill") == identifier or step.get("id") == identifier:
+            return i, step
+    return None, None
+
+
+def update_checkpoint(checkpoint_path, step_identifier, new_status, note=None):
+    """Update a single step's status in the checkpoint file.
+
+    Returns a result dict: {ok, step_id, skill, old_status, new_status} or {ok, error}.
+    """
+    if new_status not in VALID_STATUSES:
+        return {
+            "ok": False,
+            "error": "Invalid status '{}'. Must be one of: {}".format(
+                new_status, ", ".join(sorted(VALID_STATUSES))
+            ),
+        }
+
+    data, err = _load_checkpoint(checkpoint_path)
+    if err:
+        return {"ok": False, "error": err}
+
+    idx, step = _find_step(data["steps"], step_identifier)
+    if step is None:
+        available = [
+            "{} ({})".format(s.get("id", "?"), s.get("skill", "?"))
+            for s in data["steps"]
+        ]
+        return {
+            "ok": False,
+            "error": "Step '{}' not found. Available: {}".format(
+                step_identifier, ", ".join(available)
+            ),
+        }
+
+    old_status = step.get("status", "unknown")
+    step["status"] = new_status
+
+    if note:
+        step["note"] = note
+
+    err = _write_checkpoint(checkpoint_path, data)
+    if err:
+        return {"ok": False, "error": err}
+
+    return {
+        "ok": True,
+        "step_id": step.get("id"),
+        "skill": step.get("skill"),
+        "old_status": old_status,
+        "new_status": new_status,
+    }
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Safely update a workflow-checkpoint.json step status.",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog=(
+            "Examples:\n"
+            "  %(prog)s --checkpoint-path .prizmkit/specs/my-feature/workflow-checkpoint.json "
+            "--step prizmkit-implement --status completed\n"
+            "  %(prog)s --checkpoint-path .prizmkit/bugfix/B-001/workflow-checkpoint.json "
+            "--step S04 --status in_progress\n"
+            "  %(prog)s --checkpoint-path .prizmkit/refactor/R-001/workflow-checkpoint.json "
+            "--step prizmkit-code-review --status failed --note 'max rounds exhausted'"
+        ),
+    )
+    parser.add_argument(
+        "--checkpoint-path", required=True, help="Path to workflow-checkpoint.json"
+    )
+    parser.add_argument(
+        "--step",
+        required=True,
+        help="Step identifier (skill name like 'prizmkit-implement' or step ID like 'S04')",
+    )
+    parser.add_argument(
+        "--status",
+        required=True,
+        choices=sorted(VALID_STATUSES),
+        help="New status for the step",
+    )
+    parser.add_argument(
+        "--note",
+        default=None,
+        help="Optional note to attach to the step (e.g., failure reason)",
+    )
+
+    args = parser.parse_args()
+    result = update_checkpoint(
+        args.checkpoint_path, args.step, args.status, args.note
+    )
+    print(json.dumps(result, indent=2, ensure_ascii=False))
+    return 0 if result.get("ok") else (2 if "File not found" in result.get("error", "") or "Corrupted" in result.get("error", "") else 1)
+
+
+if __name__ == "__main__":
+    sys.exit(main())