← Files ClaraARCHIVED FILE

scripts/archive_cli.py

9.38 KB · Nov 21, 2026 · 00:11 UTC

↓ Download file

See the change to this file →

"""Record a bound Vera command's actual stdout before releasing it to its caller."""

from __future__ import annotations

import json
import logging
import os
import subprocess
import sys
import tempfile
from concurrent.futures import ThreadPoolExecutor
from contextlib import ExitStack
from pathlib import Path
from typing import Any

from archive_emit import _run_roots, bind_output, selected_run
from archive_reporting import record_send
from archive_reporting_failure import REPORTING_ERRORS, reporting_failure

__all__ = ["run_command", "run_entrypoint"]


def run_entrypoint(main: Any, component_file: Path) -> int | None:
    """Make direct Vera CLI invocation use the same owned sending boundary."""
    if (
        os.environ.get("VERA_REPORTING_INTERNAL") == "1"
        or os.environ.get("VERA_REPORTING_CAPTURED") == "1"
    ):
        return main()
    component = component_file.resolve().parents[1].name
    try:
        roots = _run_roots(sys.argv[1:])
    except REPORTING_ERRORS as error:
        reporting_failure(component, sys.argv[1:], error, stage="bind")
    else:
        if not roots:
            return main()
    product_root = Path(__file__).resolve().parents[1]
    return run_command(
        [
            sys.executable,
            "-X",
            "utf8",
            "-I",
            "-B",
            "-c",
            "import runpy,sys; from pathlib import Path; "
            "script=Path(sys.argv[1]); sys.path.insert(0,str(script.parent)); "
            "sys.argv=sys.argv[1:]; runpy.run_path(str(script),run_name='__main__')",
            str(component_file.resolve()),
            *sys.argv[1:],
        ],
        plugin_root=product_root,
        component=component,
        arguments=[str(component_file), *sys.argv[1:]],
        check=False,
    ).returncode


def run_command(
    command: list[str],
    *,
    plugin_root: Path,
    component: str,
    arguments: list[str],
    **options: Any,
) -> subprocess.CompletedProcess:
    """Hand the code lease to the child before a launcher can be terminated."""
    from verified_execution import acquire_execution_lease

    try:
        roots = _run_roots(arguments)
    except REPORTING_ERRORS as error:
        reporting_failure(component, arguments, error, stage="checkpoint_discovery")
        roots = set()
    contexts = [root / "context.json" for root in roots] if len(roots) == 1 else []
    lease = acquire_execution_lease(plugin_root)
    try:
        _checkpoint(contexts, plugin_root)
        if lease is not None:
            options["pass_fds"] = tuple(
                dict.fromkeys((*options.get("pass_fds", ()), lease))
            )
        return _run_command(
            command,
            plugin_root=plugin_root,
            component=component,
            arguments=arguments,
            **options,
        )
    finally:
        _checkpoint(contexts, plugin_root)
        if lease is not None:
            os.close(lease)


def _checkpoint(contexts: list[Path], plugin_root: Path) -> None:
    """Preserve completed stages around helpers without making backup a new gate."""
    if not contexts:
        return
    for vendor in (
        plugin_root / "vendor/modules",
        plugin_root.parent / "_shared/vendor/modules",
    ):
        if (vendor / "vera_assurance").is_dir():
            if str(vendor) not in sys.path:
                sys.path.insert(0, str(vendor))
            break
    try:
        from vera_assurance.recovery import checkpoint_run

        for context in contexts:
            checkpoint_run(context)
    except (*REPORTING_ERRORS, ImportError) as error:
        logging.getLogger(__name__).warning(
            "Work remains available; its recovery checkpoint could not refresh (%s). Retain this job and retry the checkpoint.",
            type(error).__name__,
        )


def _run_command(
    command: list[str],
    *,
    plugin_root: Path,
    component: str,
    arguments: list[str],
    **options: Any,
) -> subprocess.CompletedProcess:
    """Measure producer bytes and deliver work even if its record cannot be saved."""
    manifest = next(
        (
            plugin_root / name
            for name in (
                ".codex-plugin/plugin.json",
                ".claude-plugin/plugin.json",
            )
            if (plugin_root / name).is_file()
        ),
        None,
    )
    if (
        os.environ.get("VERA_REPORTING_INTERNAL") == "1"
        or manifest is None
        or json.loads(manifest.read_text(encoding="utf-8"))["name"] != "vera"
    ):
        return subprocess.run(command, **options)
    environment = options.get("env")
    options["env"] = {
        **(os.environ if environment is None else environment),
        "VERA_REPORTING_CAPTURED": "1",
    }
    try:
        binding = bind_output(component, arguments)
        if binding is None and selected_run(component, arguments) is not None:
            raise ValueError("The selected reporting collection is closed")
    except REPORTING_ERRORS as error:
        reporting_failure(component, arguments, error, stage="bind")
        binding = None
    if binding is None:
        return subprocess.run(command, **options)
    root = Path(binding["run_root"])
    destination = options.pop("stderr", None)
    if arguments and (component, Path(arguments[0]).name) in {
        ("management-control-pack", "preview_report.py"),
        ("open-item-reconciliation", "review_server.py"),
    }:
        return _stream_preview(command, root, binding, component, destination, options)
    with ExitStack() as capture:
        try:
            stdout = capture.enter_context(tempfile.TemporaryFile())
            stderr = capture.enter_context(tempfile.TemporaryFile())
        except OSError as error:
            # Capture is optional bookkeeping. Launch exactly once even when
            # its temporary storage is unavailable, retaining the caller's sink.
            capture.close()
            reporting_failure(component, arguments, error, stage="capture", root=root)
            return subprocess.run(command, stderr=destination, **options)
        completed = subprocess.run(command, stdout=stdout, stderr=stderr, **options)
        stdout.seek(0)
        stderr.seek(0)
        out, err = stdout.read(), stderr.read()
        # Installed CLI helpers return UTF-8 text. Never replace undecodable bytes
        # and then claim the replacement is the exact outgoing payload.
        try:
            payload = {"stdout": out.decode("utf-8")}
            if destination is None:
                payload["stderr"] = err.decode("utf-8")
            # Pin the reporting revision; a concurrent closure must not rewrite
            # its sealed report. A delivery gap is separate from the work outcome.
            record_send(
                root,
                payload,
                channel="cli:" + component,
                request=arguments,
                expected_revision=binding["report_revision"],
            )
        except REPORTING_ERRORS as error:
            reporting_failure(component, arguments, error, stage="delivery", root=root)
        sys.stdout.buffer.write(out)
        sys.stdout.buffer.flush()
        if destination is None:
            sys.stderr.buffer.write(err)
            sys.stderr.buffer.flush()
        else:
            destination.flush()
            if hasattr(destination, "buffer"):
                destination.buffer.write(err)
                destination.buffer.flush()
            else:
                destination.write(err)
                destination.flush()
        return completed


def _stream_preview(command, root, binding, component, destination, options):
    """Release a local preview server's startup URL without waiting for shutdown."""
    options.pop("check", None)
    with subprocess.Popen(
        command, stdout=subprocess.PIPE, stderr=subprocess.PIPE, **options
    ) as child:

        def transfer(stream, name):
            for line in iter(stream.readline, b""):
                if name == "stderr" and destination is not None:
                    destination.flush()
                    target = (
                        destination.buffer
                        if hasattr(destination, "buffer")
                        else destination
                    )
                    target.write(line)
                    target.flush()
                    continue
                try:
                    payload = (
                        {"stdout": line.decode("utf-8")}
                        if name == "stdout"
                        else {"stdout": "", "stderr": line.decode("utf-8")}
                    )
                    record_send(
                        root,
                        payload,
                        channel="cli:" + component,
                        expected_revision=binding["report_revision"],
                    )
                except REPORTING_ERRORS as error:
                    reporting_failure(
                        component, [], error, stage="preview_delivery", root=root
                    )
                target = sys.stdout if name == "stdout" else sys.stderr
                target.buffer.write(line)
                target.buffer.flush()
            return True

        with ThreadPoolExecutor(max_workers=2) as workers:
            stdout = workers.submit(transfer, child.stdout, "stdout")
            stderr = workers.submit(transfer, child.stderr, "stderr")
            stdout.result()
            stderr.result()
        code = child.wait()
    return subprocess.CompletedProcess(command, code)

SHA-256: 786c6d01451706127c39b93f986482e157dfa0d5076f651372c33b9e7e180298