strata - Utilities Documentation

Self-contained utility modules. No cross-imports between utils modules; no imports from services/, controllers/, or commands/.

config.py

Package-level constants. Import instead of hard-coding strings.

from strata.utils.config import SOLUTION_DIR, SOLUTION_FILE, SCRIPT_EXTENSIONS
# SOLUTION_DIR = ".strata"
# SOLUTION_FILE = "solution.json"
# SCRIPT_EXTENSIONS = {".sh", ".bash", ".py", ".ps1"}

system.py

Path resolution, UUID generation, subprocess execution.

resolve_path(base_path, target_path=None, *sub_paths, repo_map=None) — resolves paths with @repo-name/... cross-repo reference support. Raises ValueError for unknown @ references or absolute sub_paths.

resolve_work_path(explicit=None) — workspace root discovery: explicit path → .strata/ upward walk → CWD.

normalize_path(path) — strips invalid filesystem characters.

generate_uuid() — UUID v4 string.

run_command(args, cwd, timeout, env) — subprocess wrapper returning a CommandResult(stdout, stderr, returncode).

from strata.utils.system import resolve_path, resolve_work_path, run_command

path = resolve_path("/base", "@myrepo/config/file.yaml", repo_map={"myrepo": "/repos/myrepo"})
root = resolve_work_path()  # auto-discovers .strata/ ancestor
result = run_command(["git", "status"], cwd="/repo")

configuration_loader.py

Low-level YAML loader and deep merger. No schema knowledge.

ConfigurationLoader — methods:

  • load_yaml_file(file_path: Path) — load single YAML file

  • load_yaml_files(file_paths: List[Path]) — load and deep-merge a list

  • load_and_merge_yaml_files(base, overrides_list) — explicit base + overrides

  • deep_merge(base, override) — recursive dict merge (override wins on conflict)

  • apply_overrides(base, overrides) — alias for deep_merge

from strata.utils.configuration_loader import ConfigurationLoader
from pathlib import Path

loader = ConfigurationLoader()
config = loader.load_yaml_file(Path("config/logging.yaml"))
merged = loader.apply_overrides(config, {"level": "DEBUG"})

service_cache.py

In-process service instance cache to avoid re-parsing YAML on repeated loads.

from strata.utils.service_cache import get_cached_service, cache_service, clear_cache

instance = get_cached_service(MyService, file_path="/path/to/file.yaml")
if instance is None:
    instance = MyService.load("/path/to/file.yaml")
    cache_service(MyService, instance, file_path="/path/to/file.yaml")

Used internally by BaseService.load(). Call clear_cache() between tests.

templater.py

File template processor: expands *.template.* files using Jinja2 ({{ VAR }}), then optionally deletes the template source.

from strata.utils.templater import TemplateProcessor
from pathlib import Path

processor = TemplateProcessor(template_dir=Path("terraform/"), cleanup_templates=True)
processor.process_all_templates()  # main.template.tf → main.tf

ansible_utils.py

Shared helper for locating Ansible Galaxy requirements files.

find_ansible_requirements_file(directory: Path) -> Optional[Path] — checks requirements.yml then collections/requirements.yml under the given directory. Returns the first match or None.

Used by both AnsibleCollectionCollector and AnsibleDeployer to avoid duplicated discovery logic.

from strata.utils.ansible_utils import find_ansible_requirements_file

req = find_ansible_requirements_file(Path("deploy/configure"))
# returns Path("deploy/configure/requirements.yml") or None

sbom_utils.py

Pure-function PURL helpers and floating-tag detection. No imports from builders, services, or integrations.

is_floating_tag(tag) — returns True for None, empty string, well-known moving tags (latest, main, dev, edge, …), or any non-semver string. Returns False for pinned semver strings and digests.

parse_image_ref(image) — splits a container image reference into (name, tag, digest).

image_to_purl(image) — converts a container image reference to a pkg:docker/… PURL string.

helm_chart_to_purl(name, version, repository=None) — pkg:helm/… PURL with optional repository_url qualifier.

terraform_provider_to_purl(source, version=None) — pkg:terraform/… PURL.

ansible_collection_to_purl(name, version=None) / ansible_role_to_purl(name, version=None) — pkg:ansible/… PURLs.

from strata.utils.sbom_utils import is_floating_tag, image_to_purl, helm_chart_to_purl

is_floating_tag("latest")          # True
is_floating_tag("v3.0.1")          # False
image_to_purl("traefik:v3.0.1")   # "pkg:docker/traefik@v3.0.1"
helm_chart_to_purl("authentik", "2024.12.0", "https://charts.goauthentik.io")
# "pkg:helm/authentik@2024.12.0?repository_url=https%3A%2F%2Fcharts.goauthentik.io"

version.py

Reads the installed package version from package metadata.

from strata.utils.version import get_version
print(get_version())  # e.g. "1.2.3"