sci-agent 0.2.0__py3-none-any.whl

simple_ci/actions/hooks.py

@@ -0,0 +1,153 @@
+"""Python Hook 查找、加载与结果脱敏工具。"""
+
+from __future__ import annotations
+
+import importlib.util
+from copy import deepcopy
+from pathlib import Path
+from types import ModuleType
+from typing import Any
+
+from simple_ci.actions.base import collect_secret_values, redact_secrets
+
+
+def run_hook(hook_name: str, context: dict[str, Any]) -> dict[str, Any]:
+    """按流水线、项目、全局顺序运行 Python Hook，并返回可序列化的字典结果。
+
+    Args:
+        hook_name: 不含 ``.py`` 后缀的 Hook 名称。
+        context: 传递给 Hook ``run(context)`` 的上下文，至少包含 args、target、
+            project、pipeline、step、run_id 等执行信息。
+
+    Returns:
+        Hook 返回的字典；加载失败、缺少 run 函数、异常或返回非字典时统一转换为
+        ``status=failed`` 且 ``exit_code=1`` 的失败结果。所有结果都会基于上下文中
+        的敏感字段做脱敏，避免 Hook 异常泄露 token/password 等凭据。
+    """
+
+    secret_values = collect_secret_values(context)
+    safe_context = _sanitize_value(context, secret_values)
+    hook_path = _find_hook_path(hook_name, context)
+    if hook_path is None:
+        return _failure(f"Hook not found: {hook_name}", secret_values)
+
+    try:
+        module = _load_hook_module(hook_name, hook_path)
+        run = getattr(module, "run", None)
+        if not callable(run):
+            return _failure(f"Hook {hook_name} must define run(context).", secret_values)
+        result = run(safe_context)
+        if not isinstance(result, dict):
+            return _failure(f"Hook {hook_name} run(context) must return a dict.", secret_values)
+        normalized = deepcopy(result)
+        if normalized.get("status") == "failed":
+            normalized["exit_code"] = 1
+        return _sanitize_value(normalized, secret_values)
+    except Exception as exc:  # noqa: BLE001 - Hook 是用户脚本边界，必须转换为失败结果。
+        return _failure(str(exc), secret_values)
+
+
+def _find_hook_path(hook_name: str, context: dict[str, Any]) -> Path | None:
+    """按 pipeline hooks > project hooks > global hooks 顺序查找 Hook 文件。"""
+
+    if not _is_safe_basename(hook_name):
+        return None
+
+    project = str(context.get("project") or "")
+    pipeline = str(context.get("pipeline") or context.get("pipeline_name") or "")
+    if not _is_safe_context_segment(project) or not _is_safe_context_segment(pipeline):
+        return None
+
+    candidates = (
+        (Path("sci") / "projects" / project / "pipeline" / pipeline / "hooks", f"{hook_name}.py"),
+        (Path("sci") / "projects" / project / "hooks", f"{hook_name}.py"),
+        (Path("sci") / "hooks", f"{hook_name}.py"),
+    )
+    for hooks_root, filename in candidates:
+        candidate = hooks_root / filename
+        if _is_within_hooks_root(candidate, hooks_root) and candidate.is_file():
+            return candidate
+    return None
+
+
+def _is_safe_basename(value: str) -> bool:
+    """校验 Hook 名称只能是安全 basename，禁止绝对路径、分隔符和 ``..``。"""
+
+    path = Path(value)
+    return (
+        bool(value)
+        and not path.is_absolute()
+        and path.name == value
+        and "/" not in value
+        and "\\" not in value
+        and ".." not in value
+    )
+
+
+def _is_safe_context_segment(value: str) -> bool:
+    """校验 project/pipeline 只能是单段路径名，避免目录穿越。"""
+
+    if not value:
+        return False
+    path = Path(value)
+    return (
+        not path.is_absolute()
+        and path.name == value
+        and "/" not in value
+        and "\\" not in value
+        and ".." not in value
+    )
+
+
+def _is_within_hooks_root(candidate: Path, hooks_root: Path) -> bool:
+    """确认解析后的候选文件仍位于对应 hooks 根目录下。"""
+
+    try:
+        candidate.resolve().relative_to(hooks_root.resolve())
+    except ValueError:
+        return False
+    return True
+
+
+def _load_hook_module(hook_name: str, hook_path: Path) -> ModuleType:
+    """使用 importlib 按文件路径加载 Hook，避免依赖 Hook 目录成为 Python 包。"""
+
+    module_name = f"simple_ci_user_hook_{hook_name}_{abs(hash(str(hook_path.resolve())))}"
+    spec = importlib.util.spec_from_file_location(module_name, hook_path)
+    if spec is None or spec.loader is None:
+        raise RuntimeError(f"Unable to load hook: {hook_name}")
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module
+
+
+def _failure(error: str, secret_values: set[str]) -> dict[str, Any]:
+    """构造标准 Hook 失败结果，并对错误文本做脱敏。"""
+
+    safe_error = redact_secrets(error, secret_values)
+    return {
+        "status": "failed",
+        "exit_code": 1,
+        "stdout_tail": "",
+        "stderr_tail": safe_error,
+        "error": safe_error,
+    }
+
+
+def _sanitize_value(value: Any, secret_values: set[str]) -> Any:
+    """递归脱敏 Hook 返回结果中的敏感字段和敏感值。"""
+
+    if isinstance(value, dict):
+        sanitized: dict[str, Any] = {}
+        for key, child in value.items():
+            key_text = str(key)
+            if any(part in key_text.lower() for part in ("token", "secret", "password", "credential")):
+                sanitized[key_text] = "***"
+            else:
+                sanitized[key_text] = _sanitize_value(child, secret_values)
+        return sanitized
+    if isinstance(value, list):
+        return [_sanitize_value(item, secret_values) for item in value]
+    if isinstance(value, str):
+        return redact_secrets(value, secret_values)
+    return deepcopy(value)

simple_ci/actions/image.py

@@ -0,0 +1,28 @@
+"""镜像相关内置动作的命令构造。"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def build_image_command(params: dict[str, Any]) -> list[str]:
+    """构造 docker build 命令，保留参数顺序以便测试和日志稳定。"""
+
+    image = str(params["image"])
+    tag = str(params.get("tag", "latest"))
+    command = ["docker", "build", str(params.get("context", "."))]
+    dockerfile = params.get("dockerfile")
+    if dockerfile:
+        command.extend(["-f", str(dockerfile)])
+    command.extend(["-t", f"{image}:{tag}"])
+    for key, value in (params.get("build_args") or {}).items():
+        command.extend(["--build-arg", f"{key}={value}"])
+    return command
+
+
+def build_push_command(params: dict[str, Any]) -> list[str]:
+    """构造 docker push 命令。"""
+
+    image = str(params["image"])
+    tag = str(params.get("tag", "latest"))
+    return ["docker", "push", f"{image}:{tag}"]

simple_ci/actions/source.py

@@ -0,0 +1,32 @@
+"""源码相关内置动作的命令构造。"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from simple_ci.actions.base import inject_basic_auth
+
+
+def build_git_pull_command(params: dict[str, Any]) -> list[str] | list[list[str]]:
+    """构造 git 拉取命令；目录已有 .git 时执行 fetch/reset，否则首次 clone。"""
+
+    original_repo = str(params["repo"])
+    repo = inject_basic_auth(original_repo, params.get("credential"))
+    branch = str(params.get("branch", "main"))
+    directory = str(params.get("directory") or params.get("checkout_dir") or ".")
+    checkout_path = Path(directory)
+    if not checkout_path.is_absolute():
+        base_dir = Path(str(params.get("cwd") or params.get("workdir") or "."))
+        checkout_path = base_dir / checkout_path
+    if (checkout_path / ".git").exists():
+        if repo != original_repo:
+            return [
+                ["git", "-C", directory, "fetch", repo, branch],
+                ["git", "-C", directory, "reset", "--hard", "FETCH_HEAD"],
+            ]
+        return [
+            ["git", "-C", directory, "fetch", "origin", branch],
+            ["git", "-C", directory, "reset", "--hard", f"origin/{branch}"],
+        ]
+    return ["git", "clone", "--branch", branch, repo, directory]

simple_ci/actions/target.py

@@ -0,0 +1,63 @@
+"""目标主机相关内置动作的命令构造。"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+
+def build_target_shell_command(params: dict[str, Any], payload: dict[str, Any] | None = None) -> list[str] | str:
+    """返回目标 shell 命令，支持 inline command 与 script+args 两种模式。
+
+    当配置 ``script`` 时，按流水线目录、项目目录、全局目录三层查找；script
+    名称拒绝绝对路径和 ``..``，避免越权执行工作区外文件。未配置 script 时
+    保持原有 inline ``command`` 能力。
+    """
+
+    if params.get("script"):
+        return _build_script_command(params, payload or {})
+    command = params.get("command")
+    if not isinstance(command, (str, list)):
+        raise ValueError("Missing target shell command.")
+    return command
+
+
+def _build_script_command(params: dict[str, Any], payload: dict[str, Any]) -> list[str]:
+    """解析 script 路径并拼接 argv 参数。"""
+
+    script_name = str(params["script"])
+    _validate_script_name(script_name)
+    root = Path(str(params.get("scripts_root") or payload.get("workspace_root") or params.get("cwd") or "."))
+    project_id = str(params.get("project") or payload.get("project") or "")
+    pipeline_id = str(params.get("pipeline") or payload.get("pipeline") or "")
+    candidates = [
+        root / "sci" / "projects" / project_id / "pipeline" / pipeline_id / "scripts" / script_name,
+        root / "sci" / "projects" / project_id / "scripts" / script_name,
+        root / "sci" / "scripts" / script_name,
+    ]
+    for candidate in candidates:
+        if candidate.is_file():
+            return [str(candidate), *_normalize_args(params.get("args", []))]
+    raise ValueError(f"target shell script not found: {script_name}")
+
+
+def _validate_script_name(script_name: str) -> None:
+    """校验 script 名称只能是工作区内相对路径。"""
+
+    path = Path(script_name)
+    if (
+        path.is_absolute()
+        or script_name.startswith(("/", "\\"))
+        or any(part == ".." for part in path.parts)
+    ):
+        raise ValueError(f"unsafe target shell script: {script_name}")
+
+
+def _normalize_args(value: Any) -> list[str]:
+    """把 args 规范为字符串 argv 列表；单个标量按一个参数处理。"""
+
+    if value in (None, ""):
+        return []
+    if isinstance(value, list):
+        return [str(item) for item in value]
+    return [str(value)]

simple_ci/cli/__init__.py

@@ -0,0 +1 @@
+"""Command-line handlers for sci-agent."""

simple_ci/cli/client.py

@@ -0,0 +1,104 @@
+from __future__ import annotations
+
+import time
+from typing import Any
+
+import httpx
+
+
+TERMINAL_STATUSES = {"success", "failed", "cancelled"}
+
+
+class ServerApiError(RuntimeError):
+    """表示 sci-agent server API 返回非成功响应或客户端处理失败。"""
+
+
+class SimpleCiClient:
+    """封装 sci-agent server HTTP API，供 CLI 以统一方式提交和查询运行。"""
+
+    def __init__(self, base_url: str, token: str, transport: httpx.BaseTransport | None = None) -> None:
+        self.base_url = base_url.rstrip("/") + "/"
+        self.token = token
+        self._client = httpx.Client(
+            base_url=self.base_url,
+            headers={"Authorization": f"Bearer {token}"},
+            transport=transport,
+        )
+
+    def __enter__(self) -> "SimpleCiClient":
+        """进入上下文管理器，返回当前客户端实例。"""
+
+        return self
+
+    def __exit__(self, exc_type: object, exc_value: object, traceback: object) -> None:
+        """退出上下文管理器时关闭底层 httpx.Client。"""
+
+        self.close()
+
+    def post_run(self, payload: dict[str, Any]) -> dict[str, Any]:
+        """提交流水线运行请求，并返回服务端创建的 run 快照。"""
+
+        return self._request_json("POST", "/api/v1/pipeline/run", json=payload)
+
+    def get_run(self, run_id: str) -> dict[str, Any]:
+        """查询指定 run_id 的当前状态快照。"""
+
+        return self._request_json("GET", f"/api/v1/runs/{run_id}")
+
+    def get_logs(self, run_id: str) -> dict[str, Any]:
+        """查询指定 run_id 的日志结构。"""
+
+        return self._request_json("GET", f"/api/v1/runs/{run_id}/logs")
+
+    def run_and_poll(
+        self,
+        payload: dict[str, Any],
+        interval_seconds: float = 5,
+        timeout_seconds: float = 1800,
+    ) -> dict[str, Any]:
+        """提交流水线并轮询，直到进入终态或超时。"""
+
+        deadline = time.monotonic() + timeout_seconds
+        run = self.post_run(payload)
+        run_id = str(run["run_id"])
+        while not self._is_terminal(run):
+            if time.monotonic() >= deadline:
+                raise TimeoutError(f"Timed out waiting for run {run_id}")
+            if interval_seconds > 0:
+                time.sleep(min(interval_seconds, max(0.0, deadline - time.monotonic())))
+            if time.monotonic() >= deadline:
+                raise TimeoutError(f"Timed out waiting for run {run_id}")
+            run = self.get_run(run_id)
+        return run
+
+    def close(self) -> None:
+        """关闭底层 httpx.Client，释放连接池资源。"""
+
+        self._client.close()
+
+    def _request_json(self, method: str, path: str, **kwargs: Any) -> dict[str, Any]:
+        """发送请求并统一处理错误，异常消息会脱敏 token 以避免泄露凭据。"""
+
+        response = self._client.request(method, path, **kwargs)
+        if not response.is_success:
+            raise ServerApiError(
+                f"Server API request failed with status {response.status_code}: "
+                f"{self._sanitize(response.text)}"
+            )
+        data = response.json()
+        if not isinstance(data, dict):
+            raise ServerApiError("Server API returned a non-object JSON response")
+        return data
+
+    def _sanitize(self, value: str) -> str:
+        """从错误文本中移除当前客户端 token，保证日志和异常不会暴露认证信息。"""
+
+        if not self.token:
+            return value
+        return value.replace(self.token, "***")
+
+    @staticmethod
+    def _is_terminal(run: dict[str, Any]) -> bool:
+        """判断 run 是否进入终态；未知状态按非终态处理以便继续轮询。"""
+
+        return str(run.get("status")) in TERMINAL_STATUSES

simple_ci/cli/config.py

@@ -0,0 +1,276 @@
+"""Simple CI 工作区配置加载器。
+
+负责把 ``sci/`` 目录下的 TOML/YAML 配置和根目录 ``.env`` 合并为领域模型。
+所有敏感值只用于填充模型字段，错误信息不得输出实际凭据内容。
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import tomllib
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Mapping
+
+import yaml
+from dotenv import dotenv_values
+
+from simple_ci.errors import ConfigError
+from simple_ci.models import Credential, Pipeline, Project, ProjectSource, Step, Target, TargetServer
+
+
+@dataclass
+class Workspace:
+    """Simple CI 工作区配置集合。"""
+
+    root: Path
+    targets: dict[str, Target]
+    credentials: dict[str, Credential]
+    projects: dict[str, Project]
+    pipelines: dict[str, Pipeline]
+
+
+def load_workspace(root: str | Path) -> Workspace:
+    """从工作区根目录加载 ``sci`` 配置。"""
+
+    root_path = Path(root)
+    sci_dir = root_path / "sci"
+    if not sci_dir.is_dir():
+        raise ConfigError(f"missing sci directory: {sci_dir}")
+
+    env = _load_env(root_path)
+    credentials = _load_credentials(sci_dir / "config.toml", env)
+    targets = _load_targets(sci_dir / "targets", env)
+    projects, pipelines = _load_projects(sci_dir / "projects", credentials)
+
+    return Workspace(
+        root=root_path,
+        targets=targets,
+        credentials=credentials,
+        projects=projects,
+        pipelines=pipelines,
+    )
+
+
+def _load_env(root: Path) -> dict[str, str]:
+    values: dict[str, str] = {}
+    env_file = root / ".env"
+    if env_file.exists():
+        for key, value in dotenv_values(env_file, encoding="utf-8").items():
+            if value is not None:
+                values[key] = value
+
+    for key, value in os.environ.items():
+        values[key] = value
+    return values
+
+
+def _load_credentials(config_path: Path, env: Mapping[str, str]) -> dict[str, Credential]:
+    data = _read_toml(config_path)
+    raw_credentials = data.get("credentials", {})
+    if not isinstance(raw_credentials, dict):
+        raise ConfigError("sci/config.toml field credentials must be a table")
+
+    credentials: dict[str, Credential] = {}
+    for credential_id, raw in raw_credentials.items():
+        section = _require_mapping(raw, f"credentials.{credential_id}")
+        type_ = _require_str(section, "type", f"credentials.{credential_id}")
+        username_env = _require_str(section, "username_env", f"credentials.{credential_id}")
+        password_env = _require_str(section, "password_env", f"credentials.{credential_id}")
+        username = _require_env(env, username_env)
+        password = _require_env(env, password_env)
+        credentials[credential_id] = Credential(
+            id=credential_id,
+            type=type_,
+            username_env=username_env,
+            password_env=password_env,
+            username=username,
+            password=password,
+        )
+    return credentials
+
+
+def _load_targets(targets_dir: Path, env: Mapping[str, str]) -> dict[str, Target]:
+    targets: dict[str, Target] = {}
+    if not targets_dir.exists():
+        return targets
+
+    for config_path in sorted(targets_dir.glob("*.toml")):
+        target_id = config_path.stem
+        data = _read_toml(config_path)
+        name = _require_str(data, "name", f"target {target_id}")
+        server_section = data.get("server", {})
+        server = _build_target_server(target_id, _require_mapping(server_section, f"target {target_id}.server"), env)
+        targets[target_id] = Target(
+            id=target_id,
+            name=name,
+            server=server,
+            vars=_optional_mapping(data, "vars", f"target {target_id}"),
+            description=_optional_str(data, "description"),
+            policy=_optional_mapping(data, "policy", f"target {target_id}"),
+        )
+    return targets
+
+
+def _build_target_server(target_id: str, server: Mapping[str, Any], env: Mapping[str, str]) -> TargetServer:
+    normalized_id = _normalize_env_id(target_id)
+    url_env = _optional_str(server, "url_env") or f"SERVER_{normalized_id}_URL"
+    token_env = _optional_str(server, "token_env") or f"SERVER_{normalized_id}_TOKEN"
+    return TargetServer(url=_require_env(env, url_env), token=_require_env(env, token_env))
+
+
+def _load_projects(
+    projects_dir: Path,
+    credentials: Mapping[str, Credential],
+) -> tuple[dict[str, Project], dict[str, Pipeline]]:
+    projects: dict[str, Project] = {}
+    pipelines: dict[str, Pipeline] = {}
+    if not projects_dir.exists():
+        return projects, pipelines
+
+    for project_dir in sorted(path for path in projects_dir.iterdir() if path.is_dir()):
+        project_id = project_dir.name
+        project = _load_project(project_id, project_dir / "config.toml", credentials)
+        projects[project_id] = project
+        pipelines.update(_load_pipelines(project_id, project_dir / "pipeline"))
+    return projects, pipelines
+
+
+def _load_project(project_id: str, config_path: Path, credentials: Mapping[str, Credential]) -> Project:
+    data = _read_toml(config_path)
+    name = _require_str(data, "name", f"project {project_id}")
+    source_section = _require_mapping(data.get("source"), f"project {project_id}.source")
+    credential = _optional_str(source_section, "credential") or None
+    if credential and credential not in credentials:
+        raise ConfigError(f"project {project_id} references unknown credential: {credential}")
+
+    return Project(
+        id=project_id,
+        name=name,
+        description=_optional_str(data, "description"),
+        vars=_optional_mapping(data, "vars", f"project {project_id}"),
+        source=ProjectSource(
+            repo=_require_str(source_section, "repo", f"project {project_id}.source"),
+            branch=_require_str(source_section, "branch", f"project {project_id}.source"),
+            credential=credential,
+        ),
+    )
+
+
+def _load_pipelines(project_id: str, pipeline_root: Path) -> dict[str, Pipeline]:
+    pipelines: dict[str, Pipeline] = {}
+    if not pipeline_root.exists():
+        return pipelines
+
+    for pipeline_dir in sorted(path for path in pipeline_root.iterdir() if path.is_dir()):
+        pipeline_id = pipeline_dir.name
+        pipelines[f"{project_id}/{pipeline_id}"] = _load_pipeline(pipeline_id, pipeline_dir)
+    return pipelines
+
+
+def _load_pipeline(pipeline_id: str, pipeline_dir: Path) -> Pipeline:
+    config = _read_toml(pipeline_dir / "config.toml")
+    pipeline_yml = _read_yaml_mapping(pipeline_dir / "pipeline.yml")
+    steps = pipeline_yml.get("steps")
+    if not isinstance(steps, list):
+        raise ConfigError(f"pipeline {pipeline_id} field steps must be a list")
+
+    return Pipeline(
+        id=pipeline_id,
+        name=_require_str(config, "name", f"pipeline {pipeline_id}"),
+        description=_optional_str(config, "description"),
+        vars=_optional_mapping(config, "vars", f"pipeline {pipeline_id}"),
+        steps=[_load_step(index, raw_step, pipeline_id) for index, raw_step in enumerate(steps)],
+    )
+
+
+def _load_step(index: int, raw_step: Any, pipeline_id: str) -> Step:
+    context = f"pipeline {pipeline_id} step {index + 1}"
+    data = _require_mapping(raw_step, context)
+    return Step(
+        name=_require_str(data, "name", context),
+        uses=_require_str(data, "uses", context),
+        with_=_optional_mapping(data, "with", context),
+        when=_optional_str(data, "when") or None,
+        pre=_optional_list(data, "pre", context),
+        after=_optional_list(data, "after", context),
+    )
+
+
+def _read_toml(path: Path) -> dict[str, Any]:
+    if not path.exists():
+        raise ConfigError(f"missing config file: {path}")
+    try:
+        with path.open("rb") as file_obj:
+            data = tomllib.load(file_obj)
+    except tomllib.TOMLDecodeError as exc:
+        raise ConfigError(f"invalid TOML file {path}: {exc}") from exc
+    if not isinstance(data, dict):
+        raise ConfigError(f"TOML file must contain a table: {path}")
+    return data
+
+
+def _read_yaml_mapping(path: Path) -> dict[str, Any]:
+    if not path.exists():
+        raise ConfigError(f"missing pipeline file: {path}")
+    try:
+        data = yaml.safe_load(path.read_text(encoding="utf-8"))
+    except yaml.YAMLError as exc:
+        raise ConfigError(f"invalid YAML file {path}: {exc}") from exc
+    if data is None:
+        data = {}
+    return dict(_require_mapping(data, f"pipeline file {path}"))
+
+
+def _require_mapping(value: Any, context: str) -> Mapping[str, Any]:
+    if not isinstance(value, dict):
+        raise ConfigError(f"{context} must be a table")
+    return value
+
+
+def _require_str(data: Mapping[str, Any], field: str, context: str) -> str:
+    value = data.get(field)
+    if not isinstance(value, str) or not value:
+        raise ConfigError(f"{context} missing required field: {field}")
+    return value
+
+
+def _optional_str(data: Mapping[str, Any], field: str) -> str:
+    value = data.get(field, "")
+    if value is None:
+        return ""
+    if not isinstance(value, str):
+        raise ConfigError(f"field {field} must be a string")
+    return value
+
+
+def _optional_mapping(data: Mapping[str, Any], field: str, context: str) -> dict[str, Any]:
+    value = data.get(field, {})
+    if not isinstance(value, dict):
+        raise ConfigError(f"{context} field {field} must be a table")
+    return dict(value)
+
+
+def _optional_list(data: Mapping[str, Any], field: str, context: str) -> list[dict[str, Any]]:
+    value = data.get(field, [])
+    if not isinstance(value, list):
+        raise ConfigError(f"{context} field {field} must be a list")
+    for item in value:
+        if not isinstance(item, dict):
+            raise ConfigError(f"{context} field {field} items must be tables")
+    return [dict(item) for item in value]
+
+
+def _require_env(env: Mapping[str, str], env_name: str) -> str:
+    value = env.get(env_name)
+    if value is None or value == "":
+        raise ConfigError(f"missing required environment variable: {env_name}")
+    return value
+
+
+def _normalize_env_id(value: str) -> str:
+    normalized = re.sub(r"[^0-9A-Za-z]+", "_", value).strip("_").upper()
+    if not normalized:
+        raise ConfigError("target id cannot be empty after normalization")
+    return normalized