ultra-builder-pro-cli 0.25.1 → 0.26.0

package/hooks/_common.py

@@ -0,0 +1,113 @@
+"""Small file-first helpers shared by Ultra hooks."""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import sys
+from pathlib import Path
+from typing import Any
+
+
+def read_payload() -> dict[str, Any]:
+    try:
+        value = json.loads(sys.stdin.read() or "{}")
+    except json.JSONDecodeError:
+        return {}
+    return value if isinstance(value, dict) else {}
+
+
+def project_root(payload: dict[str, Any]) -> Path | None:
+    candidate = payload.get("cwd") or payload.get("workspace_root") or os.getcwd()
+    path = Path(str(candidate)).resolve()
+    if path.is_file():
+        path = path.parent
+    for current in (path, *path.parents):
+        if (current / ".ultra").is_dir():
+            return current
+    return None
+
+
+def markdown_section(text: str, heading: str) -> str:
+    pattern = re.compile(
+        rf"^##\s+{re.escape(heading)}\s*$\n(?P<body>.*?)(?=^##\s+|\Z)",
+        re.MULTILINE | re.DOTALL | re.IGNORECASE,
+    )
+    match = pattern.search(text)
+    return match.group("body").strip() if match else ""
+
+
+def read_tasks(root: Path) -> list[dict[str, Any]]:
+    try:
+        value = json.loads((root / ".ultra" / "tasks.json").read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return []
+    tasks = value.get("tasks", []) if isinstance(value, dict) else value
+    return [item for item in tasks if isinstance(item, dict)] if isinstance(tasks, list) else []
+
+
+def current_task(root: Path) -> dict[str, Any] | None:
+    tasks = read_tasks(root)
+    for status in ("in_progress", "pending"):
+        for task in tasks:
+            if task.get("status") == status:
+                return task
+    return None
+
+
+def project_file(root: Path, value: str, *, ultra_default: bool = False) -> Path | None:
+    relative = Path(value)
+    if relative.is_absolute():
+        return None
+    ultra_shorthands = {"changes", "contexts", "decisions", "evidence", "progress", "reviews", "specs"}
+    first = relative.parts[0] if relative.parts else ""
+    if first == ".ultra":
+        base = root
+    elif ultra_default and first in ultra_shorthands:
+        base = root / ".ultra"
+    else:
+        base = root
+    candidate = (base / relative).resolve()
+    try:
+        candidate.relative_to(root.resolve())
+    except ValueError:
+        return None
+    return candidate
+
+
+def context_path(root: Path, task: dict[str, Any]) -> Path | None:
+    value = task.get("context_file")
+    if not isinstance(value, str) or not value:
+        return None
+    return project_file(root, value, ultra_default=True)
+
+
+def task_sections(root: Path, task: dict[str, Any]) -> dict[str, str]:
+    file = context_path(root, task)
+    try:
+        text = file.read_text(encoding="utf-8") if file else ""
+    except OSError:
+        text = ""
+    return {
+        "acceptance": markdown_section(text, "Acceptance Criteria"),
+        "resume": markdown_section(text, "Resume Note"),
+    }
+
+
+def emit_context(event: str, text: str) -> None:
+    if not text.strip():
+        return
+    print(json.dumps({
+        "hookSpecificOutput": {
+            "hookEventName": event,
+            "additionalContext": text.strip(),
+        }
+    }))
+
+
+def write_json_atomic(file: Path, payload: dict[str, Any]) -> None:
+    file.parent.mkdir(parents=True, exist_ok=True)
+    temporary = file.with_suffix(f"{file.suffix}.tmp-{os.getpid()}")
+    temporary.write_text(f"{json.dumps(payload, indent=2)}\n", encoding="utf-8")
+    temporary.replace(file)

package/hooks/adapters/codex.py

@@ -1,11 +1,11 @@
 #!/usr/bin/env python3
-"""Codex wire adapter for Ultra Builder Pro hooks.
+"""Codex wire adapter for Ultra Builder Pro's five file-first hooks.
 
 Codex and Claude Code share the JSON-on-stdin command-hook shape, but differ
 at three important boundaries:
 
 - Codex emits ``apply_patch`` with the patch text in ``tool_input.command``;
-  legacy Ultra edit hooks expect one ``Edit`` event per ``file_path``.
+  the post-edit sensor expects one ``Edit`` event per ``file_path``.
 - Codex rejects ``permissionDecision: ask`` in PreToolUse output. Ultra warning
   decisions therefore become advisory ``systemMessage`` values.
 - Each event has a strict output schema. This adapter removes foreign fields
@@ -30,13 +30,11 @@ from typing import Any
 
 HOOK_ROOT = Path(__file__).resolve().parent.parent
 ALLOWED_FEATURES = {
-    "active_task_context.py",
-    "health_check.py",
-    "pre_stop_check.py",
-    "subagent_tracker.py",
-    "workflow_checkpoint.py",
-    "workflow_context.py",
-    "workflow_resume.py",
+    "block_dangerous_commands.py",
+    "compact_context.py",
+    "mid_workflow_recall.py",
+    "post_edit_guard.py",
+    "session_context.py",
 }
 UNIVERSAL_OUTPUT_FIELDS = {"continue", "stopReason", "suppressOutput", "systemMessage"}
 PATCH_FILE_RE = re.compile(r"^\*\*\* (?:Add|Update|Delete) File: (.+?)\s*$", re.MULTILINE)
@@ -58,7 +56,7 @@ def _patch_paths(tool_input: Any) -> list[str]:
 
 
 def normalize_inputs(payload: dict[str, Any]) -> list[dict[str, Any]]:
-    """Return legacy-compatible input(s) for one Codex hook payload."""
+    """Return file-first hook input(s) for one Codex hook payload."""
     normalized = copy.deepcopy(payload)
     if normalized.get("tool_response") is not None and normalized.get("tool_output") is None:
         normalized["tool_output"] = normalized["tool_response"]
@@ -90,7 +88,7 @@ def _universal(output: dict[str, Any]) -> dict[str, Any]:
 
 
 def adapt_output(output: dict[str, Any], event: str) -> dict[str, Any]:
-    """Convert a legacy hook result to the strict Codex event output schema."""
+    """Convert a shared hook result to the strict Codex event output schema."""
     if not isinstance(output, dict):
         return {}
     result = _universal(output)
@@ -239,11 +237,6 @@ def run_feature(feature: str, payload: dict[str, Any], feature_args: list[str])
         return {"systemMessage": f"Ultra hook feature is missing: {feature}"}
 
     event = str(payload.get("hook_event_name") or "")
-    if feature == "workflow_resume.py" and event == "PostCompact":
-        payload = dict(payload)
-        payload["hook_event_name"] = "SessionStart"
-        payload["source"] = "compact"
-
     env = os.environ.copy()
     env["UBP_HOOK_RUNTIME"] = "codex"
     plugin_data = env.get("PLUGIN_DATA") or env.get("CLAUDE_PLUGIN_DATA")

package/hooks/adapters/grok.py

@@ -14,11 +14,11 @@ from typing import Any
 
 HOOK_ROOT = Path(__file__).resolve().parent.parent
 ALLOWED_FEATURES = {
-    "active_task_context.py",
-    "health_check.py",
-    "pre_stop_check.py",
-    "subagent_tracker.py",
-    "workflow_checkpoint.py",
+    "block_dangerous_commands.py",
+    "compact_context.py",
+    "mid_workflow_recall.py",
+    "post_edit_guard.py",
+    "session_context.py",
 }
 
 

package/hooks/adapters/kimi.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python3
-"""Kimi Code wire adapter for Ultra Builder Pro lifecycle hooks.
+"""Kimi Code wire adapter for Ultra Builder Pro's five file-first hooks.
 
-Kimi 0.26 uses snake_case JSON input compatible with the workflow hooks, but
+Kimi uses snake_case JSON input compatible with the shared hooks, but
 its output contract accepts only ``message`` plus an optional structured deny.
 This adapter preserves explicit projection denials and optional Stop decisions, converts foreign context
 fields into Kimi messages, and fails open with diagnostic evidence.
@@ -20,18 +20,16 @@ from typing import Any
 
 HOOK_ROOT = Path(__file__).resolve().parent.parent
 ALLOWED_FEATURES = {
-    "active_task_context.py",
-    "health_check.py",
-    "pre_stop_check.py",
-    "subagent_tracker.py",
-    "workflow_checkpoint.py",
-    "workflow_context.py",
-    "workflow_resume.py",
+    "block_dangerous_commands.py",
+    "compact_context.py",
+    "mid_workflow_recall.py",
+    "post_edit_guard.py",
+    "session_context.py",
 }
 
 
 def normalize_input(payload: dict[str, Any]) -> dict[str, Any]:
-    """Add only the legacy aliases required by the shared workflow hooks."""
+    """Add only aliases required by the shared file-first hooks."""
     normalized = copy.deepcopy(payload)
     agent_name = normalized.get("agent_name")
     if isinstance(agent_name, str) and agent_name:
@@ -101,10 +99,6 @@ def run_feature(feature: str, payload: dict[str, Any], feature_args: list[str])
 
     event = str(payload.get("hook_event_name") or "")
     normalized = normalize_input(payload)
-    if feature == "workflow_resume.py" and event == "PostCompact":
-        normalized["hook_event_name"] = "SessionStart"
-        normalized["source"] = "compact"
-
     env = os.environ.copy()
     env["UBP_HOOK_RUNTIME"] = "kimi"
     plugin_data = env.get("PLUGIN_DATA") or env.get("KIMI_PLUGIN_ROOT")

package/hooks/block_dangerous_commands.py

@@ -0,0 +1,95 @@
+#!/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 subprocess
+
+from _common import emit_context, project_root, read_payload
+
+
+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 classify(command: str, root) -> str | None:
+    if protected_push(command, root):
+        return "protected branch push"
+    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) -> str | None:
+    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
+    threat = classify(command, root)
+    if threat is None:
+        note = advisory(command)
+        if note:
+            emit_context("PreToolUse", note)
+        return 0
+    digest = hashlib.sha256(command.encode()).hexdigest()
+    if os.environ.get("UBP_DANGEROUS_COMMAND_APPROVED") == digest:
+        return 0
+    reason = (
+        f"Ultra blocked {threat}. Protected effect: the exact shell command. "
+        f"After explicit owner authorization, rerun with "
+        f"UBP_DANGEROUS_COMMAND_APPROVED={digest}."
+    )
+    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

@@ -0,0 +1,65 @@
+#!/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 current_task, emit_context, project_root, read_payload, task_sections
+
+
+def git_output(root, *args: str) -> str:
+    result = subprocess.run(
+        ["git", *args], cwd=root, text=True, capture_output=True, check=False, timeout=5
+    )
+    return result.stdout.strip() if result.returncode == 0 else "unavailable"
+
+
+def save_snapshot(root) -> None:
+    task = current_task(root)
+    sections = task_sections(root, task) if task else {"acceptance": "", "resume": ""}
+    text = [
+        "# Ultra Compact Snapshot",
+        "",
+        f"Generated: {datetime.now(timezone.utc).isoformat()}",
+        f"HEAD: {git_output(root, 'rev-parse', 'HEAD')}",
+        f"Task: {task.get('id') if task else 'none'}",
+        "",
+        "## Acceptance Criteria",
+        sections["acceptance"] or "_(none)_",
+        "",
+        "## Resume Note",
+        sections["resume"] or "_(none)_",
+        "",
+        "## Worktree",
+        "```text",
+        git_output(root, "status", "--short"),
+        "```",
+        "",
+    ]
+    file = root / ".ultra" / ".runtime" / "compact-snapshot.md"
+    file.parent.mkdir(parents=True, exist_ok=True)
+    file.write_text("\n".join(text), encoding="utf-8")
+
+
+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":
+        save_snapshot(root)
+        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"))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/hooks/mid_workflow_recall.py

@@ -0,0 +1,25 @@
+#!/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
+
+
+def main() -> int:
+    payload = read_payload()
+    root = project_root(payload)  # Idle guard: no `.ultra/` means silent exit.
+    if root is None:
+        return 0
+    task = current_task(root)
+    if not task:
+        return 0
+    acceptance = task_sections(root, task)["acceptance"]
+    if acceptance:
+        emit_context(
+            "PreToolUse",
+            f"Ultra task {task.get('id')} acceptance reminder:\n{acceptance}",
+        )
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/hooks/post_edit_guard.py

@@ -0,0 +1,105 @@
+#!/usr/bin/env python3
+"""Record mechanical task evidence observations after an edit."""
+
+from __future__ import annotations
+
+import json
+import re
+from datetime import datetime, timezone
+from pathlib import Path
+
+from _common import (
+    current_task,
+    emit_context,
+    project_file,
+    project_root,
+    read_payload,
+    write_json_atomic,
+)
+
+
+DIMENSIONS = (
+    "tests_written",
+    "tests_passed",
+    "persistence_real",
+    "feature_flags_audit",
+    "vertical_slice",
+    "spec_trace",
+)
+
+
+def slug(value: str) -> str:
+    return re.sub(r"[^a-z0-9]+", "-", value.lower()).strip("-")
+
+
+def trace_observation(root: Path, task: dict) -> str:
+    trace = task.get("trace_to")
+    if not isinstance(trace, str) or "#" not in trace:
+        return "missing"
+    name, anchor = trace.rsplit("#", 1)
+    file = project_file(root, name, ultra_default=True)
+    if file is None:
+        return "missing"
+    try:
+        headings = re.findall(r"^#{1,6}\s+(.+?)\s*$", file.read_text(encoding="utf-8"), re.MULTILINE)
+    except OSError:
+        return "missing"
+    return "observed" if slug(anchor) in {slug(heading) for heading in headings} else "missing"
+
+
+def main() -> int:
+    payload = read_payload()
+    root = project_root(payload)  # Idle guard: no `.ultra/` means silent exit.
+    if root is None:
+        return 0
+    task = current_task(root)
+    if not task:
+        return 0
+    tool_input = payload.get("tool_input")
+    tool_input = tool_input if isinstance(tool_input, dict) else {}
+    changed = str(tool_input.get("file_path") or tool_input.get("path") or "")
+    relative = ""
+    if changed:
+        try:
+            relative = str(Path(changed).resolve().relative_to(root))
+        except ValueError:
+            relative = ""
+
+    file = root / ".ultra" / "progress" / f"{task.get('id')}.json"
+    try:
+        progress = json.loads(file.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        progress = {}
+    if not isinstance(progress, dict):
+        progress = {}
+    existing_evidence = progress.get("evidence")
+    existing_evidence = existing_evidence if isinstance(existing_evidence, dict) else {}
+    progress["task_id"] = str(task.get("id"))
+    progress["evidence"] = {
+        name: existing_evidence.get(name, "unknown")
+        if isinstance(existing_evidence.get(name, "unknown"), str)
+        else "unknown"
+        for name in DIMENSIONS
+    }
+    touched_files = progress.get("touched_files")
+    progress["touched_files"] = list(dict.fromkeys(
+        item for item in touched_files if isinstance(item, str) and item
+    )) if isinstance(touched_files, list) else []
+    if relative and relative not in progress["touched_files"]:
+        progress["touched_files"].append(relative)
+    if re.search(r"(?:^|/)(?:test|tests|__tests__)/|(?:\.test|\.spec)\.", relative, re.IGNORECASE):
+        progress["evidence"]["tests_written"] = "observed"
+    progress["evidence"]["spec_trace"] = trace_observation(root, task)
+    progress["updated_at"] = datetime.now(timezone.utc).isoformat()
+    write_json_atomic(file, progress)
+
+    unknown = [name for name, value in progress["evidence"].items() if value == "unknown"]
+    emit_context(
+        "PostToolUse",
+        f"Ultra evidence sensor updated task {task.get('id')}. Still unobserved: {', '.join(unknown) or 'none'}.",
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/hooks/session_context.py

@@ -0,0 +1,30 @@
+#!/usr/bin/env python3
+"""Inject the one-line goal and current task acceptance at session start."""
+
+from _common import current_task, emit_context, markdown_section, project_root, read_payload, task_sections
+
+
+def main() -> int:
+    payload = read_payload()
+    root = project_root(payload)  # Idle guard: no `.ultra/` means silent exit.
+    if root is None:
+        return 0
+    try:
+        north_star = (root / ".ultra" / "north-star.md").read_text(encoding="utf-8")
+    except OSError:
+        north_star = ""
+    parts = []
+    one_line = markdown_section(north_star, "One-line")
+    if one_line:
+        parts.append(f"Ultra north star:\n{one_line}")
+    task = current_task(root)
+    if task:
+        acceptance = task_sections(root, task)["acceptance"]
+        if acceptance:
+            parts.append(f"Current task {task.get('id')} acceptance:\n{acceptance}")
+    emit_context("SessionStart", "\n\n".join(parts))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())