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.