Metadata-Version: 2.4
Name: terok-util
Version: 0.2.0
Summary: Shared utility library for the terok-* sibling packages
License-Expression: Apache-2.0
License-File: LICENSE
License-File: LICENSES/Apache-2.0.txt
Keywords: terok,shared,utilities
Author: Jiri Vyskocil
Author-email: jiri@vyskocil.com
Maintainer: Jiri Vyskocil
Maintainer-email: jiri@vyskocil.com
Requires-Python: >=3.12,<4.0
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries
Classifier: Typing :: Typed
Requires-Dist: platformdirs (>=4.10.0)
Requires-Dist: ruamel.yaml (>=0.18)
Project-URL: Changelog, https://github.com/terok-ai/terok-util/blob/master/CHANGELOG.md
Project-URL: Documentation, https://terok-ai.github.io/terok-util/
Project-URL: Homepage, https://terok-ai.github.io/terok-util/
Project-URL: Issues, https://github.com/terok-ai/terok-util/issues
Project-URL: Repository, https://github.com/terok-ai/terok-util
Project-URL: Security, https://github.com/terok-ai/terok-util/security/policy
Description-Content-Type: text/markdown

<!--
SPDX-FileCopyrightText: 2026 Jiri Vyskocil
SPDX-License-Identifier: Apache-2.0
-->

<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="https://terok-ai.github.io/terok/terok-logo-w.svg">
    <img src="https://terok-ai.github.io/terok/terok-logo-b.svg" alt="terok-util" width="120">
  </picture>
</p>

# terok-util

[![PyPI](https://img.shields.io/pypi/v/terok-util)](https://pypi.org/project/terok-util/)
[![License: Apache-2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
[![REUSE status](https://api.reuse.software/badge/github.com/terok-ai/terok-util)](https://api.reuse.software/info/github.com/terok-ai/terok-util)

Shared utility library for the [`terok-*`](https://github.com/terok-ai)
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`](https://github.com/terok-ai/terok-shield),
[`terok-clearance`](https://github.com/terok-ai/terok-clearance),
[`terok-sandbox`](https://github.com/terok-ai/terok-sandbox),
[`terok-executor`](https://github.com/terok-ai/terok-executor), and
[`terok`](https://github.com/terok-ai/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

```bash
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](LICENSE).

