ultra-builder-pro-cli 5.0.0 → 6.0.0

package/hooks/adapters/zcode.py

@@ -1,227 +0,0 @@
-#!/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/block_dangerous_commands.py

@@ -1,201 +0,0 @@
-#!/usr/bin/env python3
-"""Block a narrow set of externally destructive shell effects."""
-
-from __future__ import annotations
-
-import hashlib
-import json
-import os
-import re
-import shlex
-import subprocess
-
-from _common import emit_context, project_root, read_payload
-
-
-APPROVAL_VAR = "UBP_DANGEROUS_COMMAND_APPROVED"
-APPROVAL_PREFIX = re.compile(rf"^\s*{APPROVAL_VAR}=\S*\s+")
-
-HEREDOC = re.compile(
-    r"<<-?\s*(['\"]?)(?P<tag>[A-Za-z_]\w*)\1(?P<rest>[^\n]*)\n(?P<body>.*?)^\s*(?P=tag)\s*$",
-    re.DOTALL | re.MULTILINE,
-)
-# Commands whose heredoc is a payload rather than a script. Deliberately short: an
-# unlisted sink keeps its body in scope, so the cost of an omission is a false positive,
-# never a missed effect.
-DATA_SINK = re.compile(r"\bgit\s+(?:commit|tag|notes)\b", re.IGNORECASE)
-SEARCH_COMMANDS = {"egrep", "fgrep", "grep", "rg"}
-SHELL_CONTROL = {";", ";;", "&", "&&", "|", "||", "(", ")", "\n"}
-
-
-def strip_data_heredocs(command: str) -> str:
-    """Drop heredoc bodies that are data for a known sink.
-
-    Describing an effect inside a commit message is not performing it, and a message
-    that mentions one used to be blocked as though it did.
-
-    Bodies are kept whenever they might be executed: an interpreter reading a heredoc
-    runs it, so stripping there would make quoting style a way around this gate. The
-    body survives unless the delimiter is quoted, the segment introducing it is a
-    listed data sink, and nothing on the heredoc's own line pipes it somewhere else.
-    An unquoted delimiter performs parameter, command and arithmetic expansion before
-    the sink receives the data, so its body remains executable shell input.
-    """
-    def resolve(match: re.Match) -> str:
-        segment = re.split(r"\|\||&&|[;&|\n]", command[:match.start()])[-1]
-        if (
-            not match.group(1)
-            or "|" in match.group("rest")
-            or not DATA_SINK.search(segment)
-        ):
-            return match.group(0)
-        tag = match.group("tag")
-        return f"<<{tag}\n{tag}"
-
-    return HEREDOC.sub(resolve, command)
-
-
-def effect_of(command: str) -> str:
-    """The command reduced to what it actually does.
-
-    Strips an inline approval assignment, then any heredoc body that is data for a
-    known sink. What remains is the effect: the part worth classifying and hashing.
-
-    The digest must identify the *effect*, not the spelling of the retry. Without this,
-    prepending the variable changes the command text, which changes the digest, which
-    means the quoted digest is never the one that matches -- the repair path is a loop.
-
-    The assigned value is discarded on purpose. Only the process environment authorizes,
-    because the command string is composed by the model and honouring an inline value
-    would let it approve itself.
-    """
-    return strip_data_heredocs(APPROVAL_PREFIX.sub("", command, count=1))
-
-
-def is_inert_search(command: str) -> bool:
-    """Return true when a search query is data, not executable shell input."""
-    if any(marker in command for marker in ("$(", "<(", ">(", "`")):
-        return False
-    try:
-        lexer = shlex.shlex(command, posix=True, punctuation_chars=";&|()\n")
-        lexer.whitespace = " \t\r"
-        lexer.whitespace_split = True
-        lexer.commenters = ""
-        tokens = list(lexer)
-    except ValueError:
-        return False
-    if not tokens or any(token in SHELL_CONTROL for token in tokens):
-        return False
-    return os.path.basename(tokens[0]) in SEARCH_COMMANDS
-
-
-def protected_push(command: str, root) -> bool:
-    if not re.search(r"\bgit\s+push\b", command, re.IGNORECASE):
-        return False
-    if re.search(r"\b(?:main|master|production|prod)\b", command, re.IGNORECASE):
-        return True
-    result = subprocess.run(
-        ["git", "branch", "--show-current"], cwd=root, text=True,
-        capture_output=True, check=False, timeout=3,
-    )
-    return result.stdout.strip() in {"main", "master", "production", "prod"}
-
-
-def destructive_protected_push(command: str, root) -> bool:
-    """Detect history rewrites or deletion, not ordinary additive publication."""
-    if not protected_push(command, root):
-        return False
-    match = re.search(r"\bgit\s+push\b", command, re.IGNORECASE)
-    if match is None:
-        return False
-    segment = re.split(r"\|\||&&|[;&|\n]", command[match.end():], maxsplit=1)[0]
-    force_or_delete = re.search(
-        r"(?:^|\s)(?:-f|--force(?:-with-lease(?:=\S+)?|-if-includes)?|--delete)(?=\s|$)",
-        segment,
-        re.IGNORECASE,
-    )
-    forced_refspec = re.search(r"(?:^|\s)(?:\+\S+|:\S+)(?=\s|$)", segment)
-    return force_or_delete is not None or forced_refspec is not None
-
-
-def classify(command: str, root) -> str | None:
-    if destructive_protected_push(command, root):
-        return "protected branch history rewrite or deletion"
-    if re.search(r"\b(?:drop\s+(?:table|database|schema)|truncate\s+(?:table\s+)?)\b", command, re.IGNORECASE):
-        return "destructive database operation"
-    if re.search(r"\b(?:cast\s+send|solana\s+transfer|bitcoin-cli\s+send|near\s+send|aptos\s+move\s+run)\b", command, re.IGNORECASE):
-        return "funds or on-chain transaction"
-    if re.search(
-        r"\b(?:API_KEY|ACCESS_TOKEN|AUTH_TOKEN|SECRET|PASSWORD)\s*=\s*['\"]?(?!\$|\$\{)[^\s'\"]{8,}",
-        command,
-        re.IGNORECASE,
-    ):
-        return "hard-coded credential"
-    if re.search(r"\beval\s+['\"]?\$|\bexec\s*\([^)]*\binput\s*\(", command, re.IGNORECASE):
-        return "user-controlled code execution"
-    return None
-
-
-def advisory(command: str, root) -> str | None:
-    if protected_push(command, root):
-        return (
-            "Ultra observed a protected branch push. This portable hook cannot receive "
-            "the host's trusted owner-approval receipt, so it does not replace the host's "
-            "native authority flow. Proceed only after explicit owner authorization and "
-            "verify the remote result."
-        )
-    if re.search(
-        r"\b(?:alembic\s+upgrade|prisma\s+migrate|knex\s+migrate|sequelize\s+db:migrate|rails\s+db:migrate|manage\.py\s+migrate)\b",
-        command,
-        re.IGNORECASE,
-    ):
-        return (
-            "Ultra observed a database migration command. Confirm the target environment, "
-            "backup or rollback path, and owner authorization before any irreversible effect."
-        )
-    return None
-
-
-def main() -> int:
-    payload = read_payload()
-    root = project_root(payload)  # Idle guard: no `.ultra/` means silent exit.
-    if root is None:
-        return 0
-    tool_input = payload.get("tool_input")
-    tool_input = tool_input if isinstance(tool_input, dict) else {}
-    command = tool_input.get("command")
-    if not isinstance(command, str) or not command.strip():
-        return 0
-    effect = effect_of(command)
-    if is_inert_search(effect):
-        return 0
-    threat = classify(effect, root)
-    if threat is None:
-        note = advisory(effect, root)
-        if note:
-            emit_context("PreToolUse", note)
-        return 0
-    digest = hashlib.sha256(effect.encode()).hexdigest()
-    if os.environ.get(APPROVAL_VAR) == digest:
-        return 0
-    reason = (
-        f"Ultra blocked {threat}. Protected effect: the exact shell command, "
-        f"digest {digest}. Authorization comes from the owner's environment, never from "
-        f"the command text. Either run it yourself, or export "
-        f"{APPROVAL_VAR}={digest} in the environment that launches the agent and ask "
-        f"again. Prefixing the assignment onto this command does not authorize it."
-    )
-    print(json.dumps({
-        "decision": "block",
-        "reason": reason,
-        "hookSpecificOutput": {
-            "hookEventName": "PreToolUse",
-            "permissionDecision": "deny",
-            "permissionDecisionReason": reason,
-        },
-    }))
-    return 0
-
-
-if __name__ == "__main__":
-    raise SystemExit(main())

package/hooks/compact_context.py

@@ -1,224 +0,0 @@
-#!/usr/bin/env python3
-"""Save and restore a disposable compact snapshot from canonical files."""
-
-from __future__ import annotations
-
-import subprocess
-from datetime import datetime, timezone
-
-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
-
-
-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"",
-    )
-    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):
-    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: {head}",
-        f"Task: {task.get('id') if task else 'none'}",
-        "",
-        "## Acceptance Criteria",
-        sections["acceptance"] or "_(none)_",
-        "",
-        "## Resume Note",
-        sections["resume"] or "_(none)_",
-        "",
-        RESUME_NAVIGATION_LIMITATION,
-        "",
-        "## Task Diagnostics",
-        diagnostics or "_(none)_",
-        "",
-        "## Worktree",
-        "```text",
-        worktree,
-        "```",
-        "",
-    ]
-    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:
-    payload = read_payload()
-    root = project_root(payload)  # Idle guard: no `.ultra/` means silent exit.
-    if root is None:
-        return 0
-    event = str(payload.get("hook_event_name") or payload.get("hookEventName") or "")
-    if event == "PreCompact":
-        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"
-    ):
-        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
-
-
-if __name__ == "__main__":
-    raise SystemExit(main())