ultra-builder-pro-cli 0.25.1 → 0.26.1

package/hooks/block_dangerous_commands.py

@@ -0,0 +1,201 @@
+#!/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

@@ -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())

package/package.json

@@ -1,21 +1,14 @@
 {
   "name": "ultra-builder-pro-cli",
-  "version": "0.25.1",
-  "description": "Explicitly invoked Ultra Builder Pro workflows for Claude Code, OpenCode, Codex CLI, Kimi Code, and Grok Build, with a project-local MCP persistence and safety kernel.",
+  "version": "0.26.1",
+  "description": "File-first Ultra Builder Pro workflows for Claude Code, OpenCode, Codex CLI, Kimi Code, and Grok Build.",
   "bin": {
     "ultra-builder-pro-cli": "bin/install.js",
-    "ubp": "bin/install.js",
-    "ubp-orchestrator": "bin/orchestrator.js",
-    "ultra-tools": "ultra-tools/cli.cjs"
+    "ubp": "bin/install.js"
   },
   "files": [
     "bin",
     "adapters",
-    "ultra-tools",
-    "mcp-server",
-    "orchestrator",
-    "commands",
-    "agents",
     "skills/ultra-init",
     "skills/ultra-research",
     "skills/ultra-plan",
@@ -26,47 +19,30 @@
     "skills/ultra-status",
     "skills/ultra-think",
     "skills/ultra-change",
-    "skills/ultra-doctor",
-    "skills/code-review-expert",
-    "skills/security-rules",
-    "skills/integration-rules",
-    "skills/testing-rules",
-    "skills/cc-collab",
-    "skills/codex-collab",
-    "skills/ultra-verify",
+    "skills/ultra-delegate",
+    "skills/ultra-grilling",
+    "skills/ultra-domain-modeling",
+    "skills/ultra-tdd",
+    "hooks/_common.py",
     "hooks/*.py",
     "hooks/adapters/*.py",
     "hooks/README.md",
-    "spec/mcp-tools.yaml",
-    "spec/cli-protocol.md",
-    "spec/schemas",
     "LICENSE",
     "CHANGELOG.md",
-    "settings.json",
     ".ultra-template",
-    "docs/ROADMAP.md",
+    "docs/PHILOSOPHY.md",
     "docs/ARCHITECTURE.md",
     "docs/ARTIFACT-AUTHORITY.md",
     "docs/WORKFLOW-LIFECYCLE.md",
-    "docs/LEGACY-CLI-CROSSWALK.md",
-    "docs/AGENT-CONTEXT.md",
     "docs/SKILL-AUTHORING.md",
-    "docs/COMMIT-HASH-BACKFILL.md",
     "docs/DECISIONS.md",
-    "docs/STATE-DB-ACCESS-POLICY.md",
     "docs/PLUGIN-ISOLATION-CONTRACT.md",
     "docs/RUNTIME-COMPAT-MATRIX.md",
-    "!**/__pycache__/**",
     "!**/*.pyc",
     "!**/*.pyo",
     "!**/*.test.cjs",
     "!**/tests/**",
-    "!mcp-server/test-support/**",
-    "!mcp-server/lib/workflow-state.cjs",
-    "!mcp-server/lib/decision-dialogue.cjs",
-    "!mcp-server/lib/context-spine.cjs",
-    "!mcp-server/lib/project-breadcrumb.cjs",
-    "!mcp-server/lib/spec-learning.cjs"
+    "!**/__pycache__/**"
   ],
   "keywords": [
     "claude-code",
@@ -78,7 +54,7 @@
     "cli",
     "multi-runtime",
     "ultra-builder-pro",
-    "mcp",
+    "file-first",
     "meta-prompting",
     "context-engineering"
   ],
@@ -97,28 +73,17 @@
   },
   "scripts": {
     "test": "npm run test:all",
-    "test:state": "node --test 'mcp-server/**/*.test.cjs'",
-    "test:orch": "node --test 'orchestrator/**/*.test.cjs'",
-    "test:spec": "node spec/scripts/test-all.cjs",
-    "test:rest": "node --test adapters/_shared/tests/*.test.cjs adapters/tests/*.test.cjs ultra-tools/*.test.cjs tests/conformance/**/*.test.cjs tests/*.test.cjs",
-    "test:all": "npm run test:state && npm run test:orch && npm run test:spec && npm run test:rest",
+    "test:node": "node --test adapters/_shared/tests/*.test.cjs tests/*.test.cjs",
+    "test:all": "npm run test:node && npm run test:hooks",
     "test:hooks": "pytest hooks/tests -q",
-    "verify:release": "npm run test:all && npm run test:hooks && npm audit --omit=dev --audit-level=high",
+    "verify:release": "npm run test:all && npm audit --omit=dev --audit-level=high",
     "prepublishOnly": "npm run verify:release",
     "install:claude": "node bin/install.js --claude --local",
-    "install:kimi": "node bin/install.js --kimi --local",
-    "install:grok": "node bin/install.js --grok --local",
-    "install:all": "node bin/install.js --all --local"
+    "install:kimi": "node bin/install.js --kimi --global",
+    "install:grok": "node bin/install.js --grok --global",
+    "install:all": "node bin/install.js --all --global"
   },
   "dependencies": {
-    "@modelcontextprotocol/server": "2.0.0-beta.5",
-    "@vercel/ncc": "0.38.4",
-    "ajv": "^8.17.1",
-    "ajv-formats": "^3.0.1",
-    "better-sqlite3": "^11.5.0",
     "js-yaml": "^4.1.0"
-  },
-  "devDependencies": {
-    "@modelcontextprotocol/client": "2.0.0-beta.5"
   }
 }