ultra-builder-pro-cli 0.26.1 → 3.0.2

package/hooks/adapters/zcode.py

@@ -0,0 +1,227 @@
+#!/usr/bin/env python3
+"""ZCode wire adapter for Ultra's five file-first lifecycle hooks."""
+
+from __future__ import annotations
+
+import copy
+import json
+import os
+import re
+import subprocess
+import sys
+from pathlib import Path
+from typing import Any
+
+
+HOOK_ROOT = Path(__file__).resolve().parent.parent
+ALLOWED_FEATURES = {
+    "block_dangerous_commands.py",
+    "compact_context.py",
+    "mid_workflow_recall.py",
+    "post_edit_guard.py",
+    "session_context.py",
+}
+PATCH_FILE_RE = re.compile(r"^\*\*\* (?:Add|Update|Delete) File: (.+?)\s*$", re.MULTILINE)
+PATCH_MOVE_RE = re.compile(r"^\*\*\* Move to: (.+?)\s*$", re.MULTILINE)
+
+
+def normalize_input(payload: dict[str, Any]) -> dict[str, Any]:
+    """Translate ZCode's camelCase hook wire names to the shared contract."""
+    normalized = copy.deepcopy(payload)
+    aliases = {
+        "hookEventName": "hook_event_name",
+        "sessionId": "session_id",
+        "toolName": "tool_name",
+        "toolInput": "tool_input",
+        "toolResult": "tool_output",
+        "toolResponse": "tool_output",
+        "workspaceRoot": "workspace_root",
+    }
+    for source, target in aliases.items():
+        if source in normalized and target not in normalized:
+            normalized[target] = normalized[source]
+    if "cwd" not in normalized and isinstance(normalized.get("workspace_root"), str):
+        normalized["cwd"] = normalized["workspace_root"]
+    return normalized
+
+
+def _patch_paths(tool_input: Any) -> list[str]:
+    if not isinstance(tool_input, dict):
+        return []
+    patch = tool_input.get("command") or tool_input.get("patch") or ""
+    if not isinstance(patch, str):
+        return []
+    paths: list[str] = []
+    for match in [*PATCH_FILE_RE.findall(patch), *PATCH_MOVE_RE.findall(patch)]:
+        candidate = match.strip()
+        if candidate and candidate not in paths:
+            paths.append(candidate)
+    return paths
+
+
+def normalize_inputs(payload: dict[str, Any]) -> list[dict[str, Any]]:
+    normalized = normalize_input(payload)
+    if normalized.get("tool_name") != "ApplyPatch":
+        return [normalized]
+    paths = _patch_paths(normalized.get("tool_input"))
+    if not paths:
+        normalized["tool_name"] = "Edit"
+        return [normalized]
+    results: list[dict[str, Any]] = []
+    for file_path in paths:
+        item = copy.deepcopy(normalized)
+        item["tool_name"] = "Edit"
+        tool_input = item.get("tool_input")
+        item["tool_input"] = dict(tool_input) if isinstance(tool_input, dict) else {}
+        item["tool_input"]["file_path"] = file_path
+        results.append(item)
+    return results
+
+
+def _parse_output(stdout: str) -> dict[str, Any]:
+    text = stdout.strip()
+    if not text:
+        return {}
+    try:
+        value = json.loads(text)
+    except json.JSONDecodeError:
+        return {"systemMessage": f"Ultra hook returned non-JSON output: {text[:500]}"}
+    return value if isinstance(value, dict) else {}
+
+
+def adapt_output(output: dict[str, Any], event: str) -> dict[str, Any]:
+    """Project shared output onto ZCode's strict event-specific schema."""
+    if not isinstance(output, dict):
+        return {}
+    specific = output.get("hookSpecificOutput")
+    specific = specific if isinstance(specific, dict) else {}
+    context = specific.get("additionalContext") or output.get("additionalContext")
+
+    if event == "PreToolUse":
+        decision = specific.get("permissionDecision")
+        if decision in {"allow", "ask", "deny"}:
+            projected: dict[str, Any] = {
+                "hookEventName": "PreToolUse",
+                "permissionDecision": decision,
+            }
+            reason = specific.get("permissionDecisionReason") or output.get("reason")
+            if reason:
+                projected["permissionDecisionReason"] = str(reason)
+            if context:
+                projected["additionalContext"] = str(context)
+            return {"hookSpecificOutput": projected}
+        if output.get("decision") == "block":
+            reason = str(output.get("reason") or "Ultra blocked this tool call")
+            return {
+                "hookSpecificOutput": {
+                    "hookEventName": "PreToolUse",
+                    "permissionDecision": "deny",
+                    "permissionDecisionReason": reason,
+                }
+            }
+        return {}
+
+    if event in {
+        "SessionStart", "UserPromptSubmit", "PostToolUse",
+        "PostToolUseFailure", "Stop",
+    } and context:
+        return {
+            "hookSpecificOutput": {
+                "hookEventName": event,
+                "additionalContext": str(context),
+            }
+        }
+    return {}
+
+
+def _merge_outputs(outputs: list[dict[str, Any]], event: str) -> dict[str, Any]:
+    if not outputs:
+        return {}
+    for output in outputs:
+        specific = output.get("hookSpecificOutput")
+        if isinstance(specific, dict) and specific.get("permissionDecision") == "deny":
+            return output
+    contexts = []
+    for output in outputs:
+        specific = output.get("hookSpecificOutput")
+        if isinstance(specific, dict) and specific.get("additionalContext"):
+            contexts.append(str(specific["additionalContext"]))
+    if contexts:
+        return {
+            "hookSpecificOutput": {
+                "hookEventName": event,
+                "additionalContext": "\n\n".join(contexts),
+            }
+        }
+    return outputs[-1]
+
+
+def run_feature(feature: str, payload: dict[str, Any], feature_args: list[str]) -> dict[str, Any]:
+    if feature not in ALLOWED_FEATURES or Path(feature).name != feature:
+        return {"systemMessage": f"Ultra hook adapter refused unknown feature: {feature}"}
+    script = HOOK_ROOT / feature
+    if not script.is_file():
+        return {"systemMessage": f"Ultra hook feature is missing: {feature}"}
+
+    event = str(payload.get("hookEventName") or payload.get("hook_event_name") or "")
+    normalized_items = normalize_inputs(payload)
+    env = os.environ.copy()
+    env["UBP_HOOK_RUNTIME"] = "zcode"
+    plugin_data = env.get("ZCODE_PLUGIN_DATA") or env.get("CLAUDE_PLUGIN_DATA")
+    if plugin_data:
+        env["UBP_HOOK_DATA"] = plugin_data
+    cwd = normalized_items[0].get("cwd") if normalized_items else None
+    run_cwd = str(cwd) if isinstance(cwd, str) and Path(cwd).is_dir() else os.getcwd()
+
+    outputs: list[dict[str, Any]] = []
+    for normalized in normalized_items:
+        proc = subprocess.run(
+            [sys.executable, str(script), *feature_args],
+            input=json.dumps(normalized),
+            text=True,
+            capture_output=True,
+            cwd=run_cwd,
+            env=env,
+            timeout=30,
+            check=False,
+        )
+        if proc.stderr:
+            print(proc.stderr.rstrip(), file=sys.stderr)
+        if proc.returncode != 0:
+            outputs.append({
+                "systemMessage": (
+                    f"Ultra hook {feature} failed with exit {proc.returncode}: "
+                    f"{proc.stderr.strip()[:500]}"
+                )
+            })
+            continue
+        outputs.append(adapt_output(_parse_output(proc.stdout), event))
+    return _merge_outputs(outputs, event)
+
+
+def main() -> int:
+    if len(sys.argv) < 2:
+        print(json.dumps({"systemMessage": "Ultra ZCode hook adapter requires a feature name"}))
+        return 0
+    try:
+        payload = json.loads(sys.stdin.read() or "{}")
+        if not isinstance(payload, dict):
+            payload = {}
+    except json.JSONDecodeError as exc:
+        print(json.dumps({"systemMessage": f"Ultra hook input parse error: {exc}"}))
+        return 0
+    try:
+        output = run_feature(sys.argv[1], payload, sys.argv[2:])
+    except subprocess.TimeoutExpired:
+        output = {"systemMessage": f"Ultra hook {sys.argv[1]} timed out"}
+    except Exception as exc:
+        output = {"systemMessage": f"Ultra hook adapter error in {sys.argv[1]}: {exc}"}
+    # ZCode's hook wire schema is strict. Its official contract explicitly accepts an
+    # empty stdout stream as a successful no-op, so do not serialize an empty object.
+    if output:
+        print(json.dumps(output, ensure_ascii=False))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/hooks/compact_context.py

@@ -6,24 +6,140 @@ from __future__ import annotations
 import subprocess
 from datetime import datetime, timezone
 
-from _common import current_task, emit_context, project_root, read_payload, task_sections
+from _common import (
+    RESUME_NAVIGATION_LIMITATION,
+    current_task_selection,
+    emit_context,
+    project_root,
+    read_derived_project_file_snapshot,
+    read_payload,
+    render_task_diagnostics,
+    task_sections,
+    write_derived_project_file_atomic,
+)
+from session_context import _read_bounded_process_output
 
 
-def git_output(root, *args: str) -> str:
-    result = subprocess.run(
-        ["git", *args], cwd=root, text=True, capture_output=True, check=False, timeout=5
+COMPACT_SNAPSHOT_RELATIVE = ".ultra/.runtime/compact-snapshot.md"
+COMPACT_SNAPSHOT_MAX_BYTES = 1024 * 1024
+COMPACT_GIT_TIMEOUT_SECONDS = 5
+COMPACT_GIT_MAX_OUTPUT_BYTES = 256 * 1024
+
+
+def git_output(root, *args: str):
+    command = ["git", *args]
+    rendered = " ".join(command)
+    try:
+        process = subprocess.Popen(
+            command,
+            cwd=root,
+            stdin=subprocess.PIPE,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            shell=False,
+        )
+    except FileNotFoundError:
+        return "unavailable", {
+            "code": "compact_git_missing",
+            "message": f"Compact snapshot could not run `{rendered}` because Git is unavailable.",
+            "path": str(root),
+            "command": command,
+            "repair": (
+                "Restore a working Git executable and retry PreCompact; canonical task "
+                "Acceptance Criteria and the navigational Resume Note remain recoverable."
+            ),
+        }
+    except OSError as error:
+        return "unavailable", {
+            "code": "compact_git_execution_error",
+            "message": f"Compact snapshot could not execute `{rendered}`: {error}",
+            "path": str(root),
+            "command": command,
+            "repair": (
+                "Repair local Git execution and retry PreCompact; canonical task Acceptance "
+                "Criteria and the navigational Resume Note remain recoverable."
+            ),
+        }
+
+    stdout, _stderr, failure = _read_bounded_process_output(
+        process,
+        COMPACT_GIT_TIMEOUT_SECONDS,
+        COMPACT_GIT_MAX_OUTPUT_BYTES,
+        b"",
     )
-    return result.stdout.strip() if result.returncode == 0 else "unavailable"
+    if failure == "timeout":
+        return "unavailable", {
+            "code": "compact_git_timeout",
+            "message": (
+                f"Compact snapshot stopped `{rendered}` after the "
+                f"{COMPACT_GIT_TIMEOUT_SECONDS}-second execution ceiling."
+            ),
+            "path": str(root),
+            "command": command,
+            "repair": (
+                "Retry PreCompact after Git becomes responsive; canonical task Acceptance "
+                "Criteria and the navigational Resume Note remain recoverable."
+            ),
+        }
+    if failure == "output_too_large":
+        return "unavailable", {
+            "code": "compact_git_output_too_large",
+            "message": (
+                f"Compact snapshot stopped `{rendered}` after combined stdout and stderr "
+                f"exceeded the {COMPACT_GIT_MAX_OUTPUT_BYTES}-byte ceiling."
+            ),
+            "path": str(root),
+            "command": command,
+            "repair": (
+                f"Retry PreCompact after reducing Git command output below the "
+                f"{COMPACT_GIT_MAX_OUTPUT_BYTES}-byte combined stdout/stderr ceiling; "
+                "canonical task Acceptance Criteria and the navigational Resume Note remain recoverable."
+            ),
+        }
+    if process.returncode != 0:
+        return "unavailable", {
+            "code": "compact_git_nonzero",
+            "message": (
+                f"Compact snapshot observed `{rendered}` exit with code "
+                f"{process.returncode}."
+            ),
+            "path": str(root),
+            "command": command,
+            "returncode": process.returncode,
+            "repair": (
+                "Repair the local Git worktree or repository state and retry PreCompact; "
+                "canonical task Acceptance Criteria and the navigational Resume Note remain recoverable."
+            ),
+        }
+    return stdout.decode("utf-8", errors="replace").strip(), None
 
 
-def save_snapshot(root) -> None:
-    task = current_task(root)
-    sections = task_sections(root, task) if task else {"acceptance": "", "resume": ""}
+def save_snapshot(root):
+    selection = current_task_selection(root)
+    task = selection["task"]
+    sections = (
+        task_sections(root, task)
+        if task
+        else {
+            "acceptance": "",
+            "resume": "",
+            "diagnostics": selection["diagnostics"],
+        }
+    )
+    head, head_failure = git_output(root, "rev-parse", "HEAD")
+    worktree, worktree_failure = git_output(root, "status", "--short")
+    git_diagnostics = [
+        failure
+        for failure in (head_failure, worktree_failure)
+        if failure is not None
+    ]
+    snapshot_diagnostics = [*sections["diagnostics"], *git_diagnostics]
+    diagnostics = render_task_diagnostics(snapshot_diagnostics)
     text = [
         "# Ultra Compact Snapshot",
         "",
         f"Generated: {datetime.now(timezone.utc).isoformat()}",
-        f"HEAD: {git_output(root, 'rev-parse', 'HEAD')}",
+        f"HEAD: {head}",
         f"Task: {task.get('id') if task else 'none'}",
         "",
         "## Acceptance Criteria",
@@ -32,15 +148,30 @@ def save_snapshot(root) -> None:
         "## Resume Note",
         sections["resume"] or "_(none)_",
         "",
+        RESUME_NAVIGATION_LIMITATION,
+        "",
+        "## Task Diagnostics",
+        diagnostics or "_(none)_",
+        "",
         "## Worktree",
         "```text",
-        git_output(root, "status", "--short"),
+        worktree,
         "```",
         "",
     ]
-    file = root / ".ultra" / ".runtime" / "compact-snapshot.md"
-    file.parent.mkdir(parents=True, exist_ok=True)
-    file.write_text("\n".join(text), encoding="utf-8")
+    write_failure = write_derived_project_file_atomic(
+        root,
+        COMPACT_SNAPSHOT_RELATIVE,
+        "\n".join(text).encode("utf-8"),
+        max_bytes=COMPACT_SNAPSHOT_MAX_BYTES,
+        code_prefix="compact_snapshot_write",
+        label="Ultra compact snapshot",
+    )
+    published_diagnostics = list(sections["diagnostics"])
+    published_diagnostics.extend(git_diagnostics)
+    if write_failure is not None:
+        published_diagnostics.append(write_failure)
+    return published_diagnostics
 
 
 def main() -> int:
@@ -50,14 +181,42 @@ def main() -> int:
         return 0
     event = str(payload.get("hook_event_name") or payload.get("hookEventName") or "")
     if event == "PreCompact":
-        save_snapshot(root)
+        diagnostics = save_snapshot(root)
+        if diagnostics:
+            emit_context(
+                "PreCompact",
+                "Ultra compact snapshot diagnostic:\n"
+                + render_task_diagnostics(diagnostics),
+            )
         return 0
     if event in {"PostCompact", "SessionStart"} and (
         event == "PostCompact" or payload.get("source") == "compact"
     ):
-        file = root / ".ultra" / ".runtime" / "compact-snapshot.md"
-        if file.is_file():
-            emit_context("SessionStart", file.read_text(encoding="utf-8"))
+        snapshot, failure = read_derived_project_file_snapshot(
+            root,
+            COMPACT_SNAPSHOT_RELATIVE,
+            max_bytes=COMPACT_SNAPSHOT_MAX_BYTES,
+            code_prefix="compact_snapshot_read",
+            label="Ultra compact snapshot",
+        )
+        if snapshot is not None:
+            try:
+                text = snapshot["bytes"].decode("utf-8")
+            except UnicodeDecodeError:
+                failure = {
+                    "code": "compact_snapshot_read_invalid_utf8",
+                    "message": "Ultra compact snapshot must be valid UTF-8 Markdown.",
+                    "path": snapshot["path"],
+                }
+            else:
+                emit_context("SessionStart", text)
+                return 0
+        if failure is not None and not failure.get("code", "").endswith("_missing"):
+            emit_context(
+                "SessionStart",
+                "Ultra compact snapshot diagnostic:\n"
+                + render_task_diagnostics([failure]),
+            )
     return 0
 
 

package/hooks/mid_workflow_recall.py

@@ -1,7 +1,14 @@
 #!/usr/bin/env python3
 """Recall current acceptance before a source-reading or editing tool call."""
 
-from _common import current_task, emit_context, project_root, read_payload, task_sections
+from _common import (
+    current_task_selection,
+    emit_context,
+    project_root,
+    read_payload,
+    render_task_diagnostics,
+    task_sections,
+)
 
 
 def main() -> int:
@@ -9,14 +16,29 @@ def main() -> int:
     root = project_root(payload)  # Idle guard: no `.ultra/` means silent exit.
     if root is None:
         return 0
-    task = current_task(root)
+    selection = current_task_selection(root)
+    task = selection["task"]
     if not task:
+        diagnostics = render_task_diagnostics(selection["diagnostics"])
+        if diagnostics:
+            emit_context(
+                "PreToolUse",
+                f"Ultra task ledger diagnostics:\n{diagnostics}",
+            )
         return 0
-    acceptance = task_sections(root, task)["acceptance"]
-    if acceptance:
+    sections = task_sections(root, task)
+    parts = []
+    if sections["acceptance"]:
+        parts.append(
+            f"Ultra task {task.get('id')} acceptance reminder:\n{sections['acceptance']}"
+        )
+    diagnostics = render_task_diagnostics(sections["diagnostics"])
+    if diagnostics:
+        parts.append(f"Ultra task {task.get('id')} diagnostics:\n{diagnostics}")
+    if parts:
         emit_context(
             "PreToolUse",
-            f"Ultra task {task.get('id')} acceptance reminder:\n{acceptance}",
+            "\n\n".join(parts),
         )
     return 0