prizmkit 1.1.107 → 1.1.109

package/bundled/dev-pipeline/prizmkit_runtime/runner_recovery.py

@@ -123,7 +123,7 @@ def run_recovery(paths: RuntimePaths, legacy_args: tuple[str, ...] = ()) -> tupl
         return 1, "", "No supported AI CLI command was found for recovery\n"
     env = RunnerEnvironment.from_env()
     stream_json = False
-    if env.live_output:
+    if env.live_output and getattr(config.ai_client, "launch_profile", None) is None:
         stream_json = detect_stream_json_support(config.ai_client.command, config.ai_client.platform).enabled
     launcher = AISessionLauncher(
         AISessionConfig(
@@ -139,7 +139,9 @@ def run_recovery(paths: RuntimePaths, legacy_args: tuple[str, ...] = ()) -> tupl
             verbose=env.verbose,
             live_output=env.live_output,
             use_stream_json=stream_json,
+            launch_profile=getattr(config.ai_client, "launch_profile", None),
             stale_kill_threshold_seconds=env.stale_kill_threshold_seconds,
+            heartbeat_stale_threshold_seconds=env.heartbeat_stale_threshold_seconds,
             live_progress_interval_seconds=env.heartbeat_interval_seconds,
             live_banner=False,
             suppress_stream_output=True,

package/bundled/dev-pipeline/prizmkit_runtime/runners.py

@@ -29,6 +29,7 @@ from .gitops import (
 from .runner_bookkeeping import (
     commit_final_bookkeeping,
     commit_pre_branch_bookkeeping,
+    commit_preflight_ready_changes,
     commit_task_branch_changes,
     commit_wip_changes,
 )
@@ -389,6 +390,20 @@ def _process_item(
     execution_root = paths.project_root
 
     try:
+        preflight = commit_preflight_ready_changes(paths.project_root, item_id)
+        if preflight.committed:
+            _emit_info(f"Preflight: preserved existing user-visible changes before {family.kind} task {item_id}")
+        elif preflight.attempted:
+            detail = ""
+            if preflight.result is not None:
+                detail = (preflight.result.stderr or preflight.result.stdout).strip()
+            _emit_warning(f"Preflight: failed to preserve existing changes before {family.kind} task {item_id}")
+            if detail:
+                _emit_warning(detail.splitlines()[0][:500])
+            raise RuntimeError(f"Preflight dirty workspace preservation failed before {family.kind} task {item_id}")
+        else:
+            _emit_info(f"Preflight: no user-visible changes to preserve before {family.kind} task {item_id}")
+
         if use_worktree:
             worktree_runtime = worktree_runtime_context(
                 branch_context,
@@ -499,7 +514,9 @@ def _process_item(
             if invocation.dry_run:
                 return "dry_run"
             _emit_prompt_summary(prompt, session_id)
-            stream_json = detect_stream_json_support(config.ai_client.command, config.ai_client.platform).enabled
+            stream_json = False
+            if getattr(config.ai_client, "launch_profile", None) is None:
+                stream_json = detect_stream_json_support(config.ai_client.command, config.ai_client.platform).enabled
             base_head = run_git_command(execution_root, ("rev-parse", "HEAD")).stdout.strip()
             session_result = AISessionLauncher(
                 AISessionConfig(
@@ -515,7 +532,9 @@ def _process_item(
                     verbose=env.verbose,
                     live_output=env.live_output,
                     use_stream_json=stream_json,
+                    launch_profile=getattr(config.ai_client, "launch_profile", None),
                     stale_kill_threshold_seconds=env.stale_kill_threshold_seconds,
+                    heartbeat_stale_threshold_seconds=env.heartbeat_stale_threshold_seconds,
                     live_progress_interval_seconds=env.heartbeat_interval_seconds,
                     live_banner=False,
                     suppress_stream_output=True,

package/bundled/dev-pipeline/prizmkit_runtime/runtime_helper.py

@@ -0,0 +1,508 @@
+"""Cross-platform helper CLI for prompt runtime operations.
+
+The helpers in this module use Python standard-library APIs for file checks,
+source discovery, text search, platform detection, executable checks, port
+readiness, process cleanup, and lightweight browser-readiness polling. Stdout
+starts with deterministic markers so generated AI prompts can branch on text
+instead of shell exit-code chains.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import shutil
+import socket
+import subprocess
+import sys
+import time
+import urllib.error
+import urllib.request
+from dataclasses import asdict, dataclass
+from pathlib import Path
+from typing import Any
+
+from .paths import resolve_runtime_paths
+from .platform_detection import resolve_platform, resolve_skill
+from .processes import is_pid_running, terminate_pid_tree
+
+SOURCE_EXTENSIONS = (
+    ".js",
+    ".jsx",
+    ".ts",
+    ".tsx",
+    ".mjs",
+    ".cjs",
+    ".py",
+    ".go",
+    ".rs",
+    ".java",
+    ".kt",
+    ".rb",
+    ".php",
+    ".cs",
+    ".swift",
+    ".sh",
+    ".ps1",
+    ".md",
+    ".json",
+    ".yaml",
+    ".yml",
+    ".toml",
+)
+
+DEFAULT_EXCLUDES = (
+    ".git",
+    "node_modules",
+    "__pycache__",
+    ".pytest_cache",
+    ".mypy_cache",
+    "dist",
+    "build",
+    "vendor",
+)
+
+
+@dataclass(frozen=True)
+class HelperResult:
+    """Structured helper result rendered as marker text or JSON."""
+
+    marker: str
+    ok: bool
+    fields: dict[str, Any]
+    exit_code: int = 0
+
+
+def _path(value: str | Path) -> Path:
+    return Path(value).expanduser().resolve()
+
+
+def _relative(path: Path, root: Path) -> str:
+    try:
+        return path.relative_to(root).as_posix()
+    except ValueError:
+        return path.as_posix()
+
+
+def render_result(result: HelperResult, *, json_output: bool = False) -> str:
+    """Render a helper result without writing to stdout."""
+    if json_output:
+        payload = {"marker": result.marker, "ok": result.ok, **result.fields}
+        return json.dumps(payload, ensure_ascii=False, sort_keys=True)
+
+    lines = [result.marker]
+    for key, value in result.fields.items():
+        if value is None:
+            continue
+        if isinstance(value, (list, tuple)):
+            for item in value:
+                lines.append(f"{key}: {item}")
+        elif isinstance(value, dict):
+            lines.append(f"{key}: {json.dumps(value, ensure_ascii=False, sort_keys=True)}")
+        else:
+            lines.append(f"{key}: {value}")
+    return "\n".join(lines)
+
+
+def _emit(result: HelperResult, *, json_output: bool = False) -> int:
+    print(render_result(result, json_output=json_output))
+    return result.exit_code
+
+
+def _add_json(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("--json", action="store_true", help="Emit a single JSON object instead of marker text.")
+
+
+def _iter_files(root: Path, *, excludes: tuple[str, ...] = DEFAULT_EXCLUDES):
+    if root.is_file():
+        yield root
+        return
+    if not root.is_dir():
+        return
+    for current_root, dir_names, file_names in os.walk(root):
+        dir_names[:] = sorted(name for name in dir_names if name not in excludes)
+        for file_name in sorted(file_names):
+            yield Path(current_root) / file_name
+
+
+def _artifact_exists(args: argparse.Namespace) -> HelperResult:
+    target = _path(args.path)
+    exists = target.exists()
+    exists_marker = getattr(args, "exists_marker", "EXISTS")
+    missing_marker = getattr(args, "missing_marker", "MISSING")
+    return HelperResult(exists_marker if exists else missing_marker, exists, {"path": str(target), "type": "dir" if target.is_dir() else "file" if target.is_file() else "missing"})
+
+
+def _artifact_ensure_dir(args: argparse.Namespace) -> HelperResult:
+    target = _path(args.path)
+    target.mkdir(parents=True, exist_ok=True)
+    return HelperResult("DIR_READY", True, {"path": str(target)})
+
+
+def _artifact_touch(args: argparse.Namespace) -> HelperResult:
+    target = _path(args.path)
+    target.parent.mkdir(parents=True, exist_ok=True)
+    target.touch(exist_ok=True)
+    return HelperResult("TOUCHED", True, {"path": str(target)})
+
+
+def _artifact_list(args: argparse.Namespace) -> HelperResult:
+    target = _path(args.path)
+    if not target.is_dir():
+        return HelperResult("MISSING", False, {"path": str(target), "entries": []}, 1)
+    entries = []
+    for child in sorted(target.iterdir(), key=lambda item: item.name):
+        entries.append({"name": child.name, "type": "dir" if child.is_dir() else "file" if child.is_file() else "other"})
+    if args.json:
+        return HelperResult("LIST", True, {"path": str(target), "entries": entries})
+    lines = [f"{entry['type']}:{entry['name']}" for entry in entries]
+    return HelperResult("LIST", True, {"path": str(target), "entry": lines})
+
+
+def _artifact_tree(args: argparse.Namespace) -> HelperResult:
+    root = _path(args.path)
+    if not root.exists():
+        return HelperResult("MISSING", False, {"path": str(root), "entries": []}, 1)
+    max_depth = max(0, int(args.max_depth))
+    entries: list[str] = []
+    if root.is_file():
+        entries.append(root.name)
+    else:
+        for current_root, dir_names, file_names in os.walk(root):
+            current = Path(current_root)
+            depth = len(current.relative_to(root).parts) if current != root else 0
+            if depth >= max_depth:
+                dir_names[:] = []
+            dir_names[:] = sorted(name for name in dir_names if name not in DEFAULT_EXCLUDES)
+            for directory in dir_names:
+                entries.append(f"{_relative(current / directory, root)}/")
+            for file_name in sorted(file_names):
+                entries.append(_relative(current / file_name, root))
+    return HelperResult("TREE", True, {"path": str(root), "entries": entries} if args.json else {"path": str(root), "entry": entries})
+
+
+def _artifact_source_files(args: argparse.Namespace) -> HelperResult:
+    root = _path(args.path)
+    extensions = tuple(args.ext or SOURCE_EXTENSIONS)
+    files = [
+        _relative(file_path, root if root.is_dir() else root.parent)
+        for file_path in _iter_files(root)
+        if file_path.suffix in extensions
+    ]
+    return HelperResult("SOURCE_FILES", True, {"path": str(root), "files": files} if args.json else {"path": str(root), "file": files})
+
+
+def _text_search(args: argparse.Namespace) -> HelperResult:
+    target = _path(args.path)
+    pattern = args.pattern
+    count = 0
+    matches: list[str] = []
+    for file_path in _iter_files(target):
+        try:
+            text = file_path.read_text(encoding="utf-8", errors="ignore")
+        except OSError:
+            continue
+        file_count = text.count(pattern)
+        if file_count:
+            count += file_count
+            matches.append(_relative(file_path, target if target.is_dir() else target.parent))
+    found = count > 0
+    return HelperResult("FOUND" if found else "NOT_FOUND", found, {"count": count, "match": matches})
+
+
+def _text_count(args: argparse.Namespace) -> HelperResult:
+    target = _path(args.path)
+    count = 0
+    for file_path in _iter_files(target):
+        try:
+            count += file_path.read_text(encoding="utf-8", errors="ignore").count(args.pattern)
+        except OSError:
+            continue
+    return HelperResult("COUNT", True, {"count": count})
+
+
+def _text_contains(args: argparse.Namespace) -> HelperResult:
+    target = _path(args.path)
+    if not target.is_file():
+        return HelperResult("GATE:MISSING", False, {"path": str(target), "reason": "file_missing"}, 1)
+    try:
+        found = args.pattern in target.read_text(encoding="utf-8", errors="ignore")
+    except OSError as exc:
+        return HelperResult("GATE:MISSING", False, {"path": str(target), "reason": type(exc).__name__}, 1)
+    return HelperResult(args.found_marker if found else args.missing_marker, found, {"path": str(target), "pattern": args.pattern})
+
+
+def _platform_detect(args: argparse.Namespace) -> HelperResult:
+    paths = resolve_runtime_paths(project_root=args.project_root, pipeline_root=args.pipeline_root)
+    resolution = resolve_platform(paths.project_root)
+    marker = resolution.platform.upper() if resolution.platform else "NOT_INSTALLED"
+    return HelperResult(marker, bool(resolution.platform), {"platform": resolution.platform, "source": resolution.source, "notes": list(resolution.notes)})
+
+
+def _platform_skill(args: argparse.Namespace) -> HelperResult:
+    paths = resolve_runtime_paths(project_root=args.project_root, pipeline_root=args.pipeline_root)
+    resolution = resolve_skill(paths.project_root, args.skill, platform=args.platform, prefix=args.prefix)
+    fields = {
+        "platform": resolution.platform,
+        "skill": resolution.skill,
+        "path": str(resolution.path) if resolution.path else None,
+        "candidates": [asdict(candidate) | {"path": str(candidate.path)} for candidate in resolution.candidates],
+    }
+    return HelperResult(resolution.marker, resolution.marker == "SKILL_EXISTS", fields)
+
+
+def _executable_check(args: argparse.Namespace) -> HelperResult:
+    executable = shutil.which(args.name)
+    return HelperResult("INSTALLED" if executable else "NOT_INSTALLED", bool(executable), {"name": args.name, "path": executable})
+
+
+def _executable_version(args: argparse.Namespace) -> HelperResult:
+    executable = shutil.which(args.name)
+    if not executable:
+        return HelperResult("NOT_INSTALLED", False, {"name": args.name}, 1)
+    command = [executable, *(args.arg or ["--version"])]
+    try:
+        completed = subprocess.run(command, stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True, timeout=args.timeout, check=False)
+    except (OSError, subprocess.TimeoutExpired) as exc:
+        return HelperResult("VERSION_ERROR", False, {"name": args.name, "error": type(exc).__name__}, 1)
+    output = (completed.stdout or completed.stderr or "").strip().splitlines()
+    return HelperResult("VERSION", completed.returncode == 0, {"name": args.name, "path": executable, "version": output[0] if output else "", "return_code": completed.returncode}, completed.returncode)
+
+
+def _port_check(args: argparse.Namespace) -> HelperResult:
+    port = int(args.port)
+    sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+    try:
+        sock.settimeout(float(args.timeout))
+        in_use = sock.connect_ex((args.host, port)) == 0
+    finally:
+        sock.close()
+    return HelperResult("PORT_IN_USE" if in_use else "PORT_FREE", not in_use, {"host": args.host, "port": port})
+
+
+def _process_status_pid(args: argparse.Namespace) -> HelperResult:
+    pid = int(args.pid)
+    running = is_pid_running(pid)
+    return HelperResult("PROCESS_RUNNING" if running else "PROCESS_NOT_RUNNING", running, {"pid": pid})
+
+
+def _process_cleanup_pid(args: argparse.Namespace) -> HelperResult:
+    pid = int(args.pid)
+    result = terminate_pid_tree(pid, "runtime_helper_cleanup", grace_seconds=float(args.grace_seconds))
+    marker = "PROCESS_TERMINATED" if result.terminated else "PROCESS_NOT_RUNNING" if not is_pid_running(pid) else "PROCESS_CLEANUP_FAILED"
+    return HelperResult(marker, marker != "PROCESS_CLEANUP_FAILED", {"pid": pid, "forced": result.forced, "details": list(result.details)})
+
+
+def _process_cleanup_port(args: argparse.Namespace) -> HelperResult:
+    # The Python standard library cannot portably map listening ports to owning
+    # PIDs on all supported platforms without shelling out to lsof/netstat/taskkill.
+    # Keep this deterministic and safe instead of pretending cleanup happened.
+    port_result = _port_check(argparse.Namespace(port=args.port, host=args.host, timeout=args.timeout))
+    marker = "PORT_FREE" if port_result.marker == "PORT_FREE" else "UNSUPPORTED"
+    ok = marker == "PORT_FREE"
+    return HelperResult(marker, ok, {"host": args.host, "port": int(args.port), "reason": "pid_lookup_by_port_not_available_in_python_stdlib"}, 0 if ok else 2)
+
+
+def _process_start(args: argparse.Namespace) -> HelperResult:
+    command = list(args.command)
+    if command and command[0] == "--":
+        command = command[1:]
+    if not command:
+        return HelperResult("PROCESS_START_FAILED", False, {"reason": "missing_command"}, 2)
+    cwd = _path(args.cwd or ".")
+    stdout_target = subprocess.DEVNULL if not args.stdout else open(_path(args.stdout), "a", encoding="utf-8")
+    stderr_target = subprocess.DEVNULL if not args.stderr else open(_path(args.stderr), "a", encoding="utf-8")
+    try:
+        process = subprocess.Popen(
+            [str(part) for part in command],
+            cwd=cwd,
+            stdout=stdout_target,
+            stderr=stderr_target,
+            stdin=subprocess.DEVNULL,
+            start_new_session=(os.name != "nt"),
+            creationflags=getattr(subprocess, "CREATE_NEW_PROCESS_GROUP", 0) if os.name == "nt" else 0,
+        )
+    except OSError as exc:
+        return HelperResult("PROCESS_START_FAILED", False, {"reason": type(exc).__name__, "error": str(exc)}, 1)
+    finally:
+        for target in (stdout_target, stderr_target):
+            if hasattr(target, "close"):
+                target.close()
+    if args.pid_file:
+        pid_file = _path(args.pid_file)
+        pid_file.parent.mkdir(parents=True, exist_ok=True)
+        pid_file.write_text(f"{process.pid}\n", encoding="utf-8")
+    return HelperResult("PROCESS_STARTED", True, {"pid": process.pid, "pid_file": str(_path(args.pid_file)) if args.pid_file else None})
+
+
+def _web_wait_ready(args: argparse.Namespace) -> HelperResult:
+    deadline = time.monotonic() + float(args.timeout)
+    statuses: list[str] = []
+    while time.monotonic() <= deadline:
+        try:
+            request = urllib.request.Request(args.url, method="GET")
+            with urllib.request.urlopen(request, timeout=float(args.request_timeout)) as response:
+                status = int(response.status)
+            statuses.append(str(status))
+            if status in args.status:
+                return HelperResult("READY", True, {"url": args.url, "status": status})
+        except urllib.error.HTTPError as exc:
+            statuses.append(str(exc.code))
+            if int(exc.code) in args.status:
+                return HelperResult("READY", True, {"url": args.url, "status": int(exc.code)})
+        except (OSError, urllib.error.URLError, TimeoutError) as exc:
+            statuses.append(type(exc).__name__)
+        time.sleep(float(args.interval))
+    return HelperResult("NOT_READY", False, {"url": args.url, "observed": statuses[-5:]}, 1)
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="prizmkit-runtime-helper", description="Cross-platform PrizmKit prompt runtime helper CLI.")
+    subparsers = parser.add_subparsers(dest="group", required=True)
+
+    artifact = subparsers.add_parser("artifact", help="Artifact and source discovery helpers")
+    artifact_sub = artifact.add_subparsers(dest="action", required=True)
+    exists = artifact_sub.add_parser("exists", help="Check whether a path exists")
+    exists.add_argument("path")
+    exists.add_argument("--exists-marker", default="EXISTS")
+    exists.add_argument("--missing-marker", default="MISSING")
+    _add_json(exists)
+    exists.set_defaults(func=_artifact_exists)
+    ensure_dir = artifact_sub.add_parser("ensure-dir", help="Create a directory if missing")
+    ensure_dir.add_argument("path")
+    _add_json(ensure_dir)
+    ensure_dir.set_defaults(func=_artifact_ensure_dir)
+    touch = artifact_sub.add_parser("touch", help="Create a file and parent directories if missing")
+    touch.add_argument("path")
+    _add_json(touch)
+    touch.set_defaults(func=_artifact_touch)
+    list_parser = artifact_sub.add_parser("list", help="List a directory deterministically")
+    list_parser.add_argument("path")
+    _add_json(list_parser)
+    list_parser.set_defaults(func=_artifact_list)
+    tree = artifact_sub.add_parser("tree", help="Render a deterministic tree")
+    tree.add_argument("path")
+    tree.add_argument("--max-depth", type=int, default=3)
+    _add_json(tree)
+    tree.set_defaults(func=_artifact_tree)
+    source = artifact_sub.add_parser("source-files", help="Discover source files")
+    source.add_argument("path")
+    source.add_argument("--ext", action="append", help="Extension to include, e.g. .py")
+    _add_json(source)
+    source.set_defaults(func=_artifact_source_files)
+
+    text = subparsers.add_parser("text", help="Text search helpers")
+    text_sub = text.add_subparsers(dest="action", required=True)
+    search = text_sub.add_parser("search", help="Search text under a path")
+    search.add_argument("path")
+    search.add_argument("--pattern", required=True)
+    _add_json(search)
+    search.set_defaults(func=_text_search)
+    count = text_sub.add_parser("count", help="Count text occurrences under a path")
+    count.add_argument("path")
+    count.add_argument("--pattern", required=True)
+    _add_json(count)
+    count.set_defaults(func=_text_count)
+    contains = text_sub.add_parser("contains", help="Check one file contains text and emit gate markers")
+    contains.add_argument("path")
+    contains.add_argument("--pattern", required=True)
+    contains.add_argument("--found-marker", default="GATE:PASS")
+    contains.add_argument("--missing-marker", default="GATE:MISSING")
+    _add_json(contains)
+    contains.set_defaults(func=_text_contains)
+
+    platform = subparsers.add_parser("platform", help="AI platform and skill detection")
+    platform_sub = platform.add_subparsers(dest="action", required=True)
+    detect = platform_sub.add_parser("detect", help="Detect current AI platform")
+    detect.add_argument("--project-root")
+    detect.add_argument("--pipeline-root")
+    _add_json(detect)
+    detect.set_defaults(func=_platform_detect)
+    skill = platform_sub.add_parser("skill", help="Detect a platform skill")
+    skill.add_argument("skill")
+    skill.add_argument("--platform", default="auto")
+    skill.add_argument("--project-root")
+    skill.add_argument("--pipeline-root")
+    skill.add_argument("--prefix", action="store_true")
+    _add_json(skill)
+    skill.set_defaults(func=_platform_skill)
+
+    executable = subparsers.add_parser("executable", help="Executable checks")
+    executable_sub = executable.add_subparsers(dest="action", required=True)
+    check = executable_sub.add_parser("check", help="Check executable availability")
+    check.add_argument("name")
+    _add_json(check)
+    check.set_defaults(func=_executable_check)
+    version = executable_sub.add_parser("version", help="Run executable version command")
+    version.add_argument("name")
+    version.add_argument("--arg", action="append", default=None)
+    version.add_argument("--timeout", type=float, default=10.0)
+    _add_json(version)
+    version.set_defaults(func=_executable_version)
+
+    port = subparsers.add_parser("port", help="Port readiness helpers")
+    port_sub = port.add_subparsers(dest="action", required=True)
+    port_check = port_sub.add_parser("check", help="Check whether a TCP port is in use")
+    port_check.add_argument("port", type=int)
+    port_check.add_argument("--host", default="127.0.0.1")
+    port_check.add_argument("--timeout", type=float, default=0.5)
+    _add_json(port_check)
+    port_check.set_defaults(func=_port_check)
+
+    process = subparsers.add_parser("process", help="Process lifecycle helpers")
+    process_sub = process.add_subparsers(dest="action", required=True)
+    start = process_sub.add_parser("start", help="Start a process and optionally write a PID file")
+    start.add_argument("--pid-file")
+    start.add_argument("--cwd")
+    start.add_argument("--stdout")
+    start.add_argument("--stderr")
+    start.add_argument("command", nargs=argparse.REMAINDER)
+    _add_json(start)
+    start.set_defaults(func=_process_start)
+    status_pid = process_sub.add_parser("status-pid", help="Check whether a PID is running")
+    status_pid.add_argument("pid", type=int)
+    _add_json(status_pid)
+    status_pid.set_defaults(func=_process_status_pid)
+    cleanup_pid = process_sub.add_parser("cleanup-pid", help="Best-effort cleanup by PID")
+    cleanup_pid.add_argument("pid", type=int)
+    cleanup_pid.add_argument("--grace-seconds", type=float, default=2.0)
+    _add_json(cleanup_pid)
+    cleanup_pid.set_defaults(func=_process_cleanup_pid)
+    cleanup_port = process_sub.add_parser("cleanup-port", help="Best-effort cleanup by port when supported")
+    cleanup_port.add_argument("port", type=int)
+    cleanup_port.add_argument("--host", default="127.0.0.1")
+    cleanup_port.add_argument("--timeout", type=float, default=0.5)
+    _add_json(cleanup_port)
+    cleanup_port.set_defaults(func=_process_cleanup_port)
+
+    web = subparsers.add_parser("web", help="Browser/server readiness helpers")
+    web_sub = web.add_subparsers(dest="action", required=True)
+    wait_ready = web_sub.add_parser("wait-ready", help="Wait for an HTTP endpoint to be ready")
+    wait_ready.add_argument("--url", required=True)
+    wait_ready.add_argument("--timeout", type=float, default=30.0)
+    wait_ready.add_argument("--interval", type=float, default=2.0)
+    wait_ready.add_argument("--request-timeout", type=float, default=2.0)
+    wait_ready.add_argument("--status", action="append", type=int, default=[200, 302])
+    _add_json(wait_ready)
+    wait_ready.set_defaults(func=_web_wait_ready)
+
+    return parser
+
+
+def run_helper_command(argv: list[str] | tuple[str, ...]) -> HelperResult:
+    """Run a helper command argv and return the structured result."""
+    parser = build_parser()
+    args = parser.parse_args(list(argv))
+    return args.func(args)
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    result = args.func(args)
+    return _emit(result, json_output=bool(getattr(args, "json", False)))
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())