Skip to content

setup

setup

Sandbox-owned setup receipt and downward readiness checks.

check_setup(cfg=None, *, live=False)

Check this installation and its Shield dependency without changing state.

Live checks also discover required host tools in the current environment. Parents compose these results, never reading another owner's receipt.

Source code in src/terok_sandbox/setup.py 
29
30
31
32
33
34
35
36
37
38
39
def check_setup(cfg: SandboxConfig | None = None, *, live: bool = False) -> tuple[SetupCheck, ...]:
    """Check this installation and its Shield dependency without changing state.

    Live checks also discover required host tools in the current environment.
    Parents compose these results, never reading another owner's receipt.
    """
    cfg = cfg or SandboxConfig()
    children = ShieldHooks.check_setup(live=live and not cfg.shield_disabled)
    if cfg.shield_disabled:
        children = tuple(check for check in children if check.status is SetupStatus.DOWNGRADE)
    return (*children, setup_receipt(cfg).check(), *check_artifacts(cfg, live=live))

setup_receipt(cfg)

Describe only sandbox's installed version and persistent setup inputs.

Source code in src/terok_sandbox/setup.py 
42
43
44
45
46
47
48
49
50
51
52
53
def setup_receipt(cfg: SandboxConfig) -> SetupReceipt:
    """Describe only sandbox's installed version and persistent setup inputs."""
    return SetupReceipt(
        cfg.state_dir / _RECEIPT_NAME,
        _OWNER,
        version(_OWNER),
        {
            "python": python_identity(),
            "credentials": str(cfg.db_path),
            "host_tools": hashlib.sha256(host_tools_source().encode()).hexdigest(),
        },
    )

check_artifacts(cfg, *, live=False)

Verify required owned artifacts independently of the receipt.

Source code in src/terok_sandbox/setup.py 
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
def check_artifacts(cfg: SandboxConfig, *, live: bool = False) -> tuple[SetupCheck, ...]:
    """Verify required owned artifacts independently of the receipt."""
    checks = list(check_supervisor_hooks(root=cfg.state_dir, live=live))
    try:
        with cfg.db_path.open("rb") as db:
            header = db.read(len(_SQLITE_HEADER))
        ready = len(header) == len(_SQLITE_HEADER) and header != _SQLITE_HEADER
    except OSError:
        ready = False
    checks.append(
        SetupCheck(
            _OWNER,
            "credentials",
            SetupStatus.READY if ready else SetupStatus.MISSING,
            "" if ready else "Encrypted credentials database missing; run setup",
        )
    )
    if live:
        checks.extend(check_host_tools())
    return tuple(checks)

check_host_tools()

Discover required host tools before setup or managed launch changes state.

Source code in src/terok_sandbox/setup.py 
78
79
80
81
82
83
84
85
86
87
88
def check_host_tools() -> tuple[SetupCheck, ...]:
    """Discover required host tools before setup or managed launch changes state."""
    return tuple(
        SetupCheck(
            _OWNER,
            name,
            SetupStatus.READY if find_host_tool(name) else SetupStatus.MISSING,
            f"{name} must be executable on PATH",
        )
        for name in ("podman", "git")
    )