terok-util
Shared utility library for the terok-*
sibling packages.
terok-util sits at the bottom of the terok dependency chain: every
sibling package depends on it, and it depends on nothing else in the
ecosystem. It collects the small set of cross-cutting bits that would
otherwise be duplicated (or quietly diverge) across
terok-shield,
terok-clearance,
terok-sandbox,
terok-executor, and
terok.
What's in the box
| Module | Use case |
|---|
cli_types | CommandDef / ArgDef / CommandTree — argparse-driven CLI registry types used by every sibling that exposes a CLI tree. |
fs | ensure_dir, ensure_dir_writable, write_sensitive_file (atomic O_CREAT | O_EXCL 0o600 writer). |
paths | namespace_state_dir, namespace_config_dir, namespace_runtime_dir — XDG-aware path resolution for a per-namespace deployment. |
config_stack | ConfigStack + deep_merge — layered round-trip YAML config merge engine. |
security | sanitize_tty — strips C0 / C1 / ANSI sequences from untrusted strings before rendering to the operator's terminal (CWE-150 mitigation). |
podman | podman_userns_args — rootless --userns=keep-id:uid=1000,gid=1000 builder. |
Installation
pip install terok-util
The package is published as a Python wheel; siblings pin to a specific
GitHub-release wheel URL via pyproject.toml.
Convention
The rule for what belongs here: if two or more terok-* packages
need it, it lives in terok-util. Single-package helpers stay in
the package that owns them. The __all__ declaration in
src/terok_util/__init__.py is the contract — symbols listed there
are stable across minor releases.
License
Apache-2.0. See LICENSE.
Matrix reporting
terok-matrix --report report.json [slots...] writes an atomic JSON snapshot
alongside the normal terminal output. It updates after build and test transitions,
and retains completed verdicts if the matrix is interrupted. The destination is
independent of the engine's temporary workspace.
The snapshot has schema_version: 1, matrix state, exit_code, error, elapsed
duration in seconds, and a slots object keyed by slot name. Each slot records
its state, reason, observed version, optional suspected network_hint,
duration, and within-slot skips. Slot states are pending, building, built,
testing, passed, failed, build_failed, skipped, cancelled, or error.
A build-only run leaves successful slots built, not passed.
Consumers can poll this file without parsing terminal output. SIGTERM and Ctrl-C
finalize the report; SIGKILL cannot, so the supervising process must report that
interruption. Configuration errors before execution may leave no report.
