"""훅 opt-in 해석 — 환경 변수 > 설정 파일 `hub:` 절, 한 곳·순수 (계획 2026-09-27 L6 §2.2 · 2026-09-28 L10 §2.6 · D-L10-6). | 입력 | 뜻 | | ------------------------------------- | -------------------------------------------------------------------------------------- | | `HUB_DATABASE_URL` | 있으면 hub 다리를 켠다(출처 `env`). 값은 읽지 않는다 — 부모 환경 그대로 자식에게 간다 | | 설정 파일 `hub.database_url` | 환경 변수가 없을 때만 opt-in(출처 `config`) — **사람 셸만**. 값은 자식 환경으로만 간다 | | `SOLAR_EVAL_HUB_CONFIRM` | `local` 이면 `--i-understand-local-data`. 다른 값은 무시 + 경고 한 줄 | | 설정 파일 `hub.confirm` | `local` 만 — **URL 출처가 설정일 때만**, 사람 셸만(아래 "규칙 9 의 의도된 예외") | | `SOLAR_EVAL_STRICT_INGEST` | `1`·`true`·`yes` 면 `--strict-ingest` 와 같다 | | `HUB_TEXT_MODE` | 색인 키에만 쓴다(기본 `inline`) | | `AGENT_SESSION_MARKERS`(아래 목록) | 에이전트 세션 표식 — 하나라도 있으면 확인(환경·설정)과 설정 출처 opt-in 을 무시한다 | | `SOLAR_EVAL_HOOK_DEBUG` | `1`·`true`·`yes` 면 봉쇄한 예외의 트레이스백을 WARNING 로그로(기본 DEBUG) | **에이전트 세션 가드(D-L6-16 · D-L10-6).** 표식 목록 `AGENT_SESSION_MARKERS` 는 이 모듈 한 곳이다 — Claude Code 의 `CLAUDECODE` 와, Codex 가 셸 도구·Seatbelt 샌드박스 자식에 설정한다고 그 레포 `AGENTS.md` 가 적은 `CODEX_SANDBOX`· `CODEX_SANDBOX_NETWORK_DISABLED`(Q-L10-22 — 문서로 확인한 것만). 표식이 하나라도 비어 있지 않으면 `SOLAR_EVAL_HUB_CONFIRM`· `hub.confirm` 을 무시하고, 설정 파일 `hub.database_url` 도 무시한다(hub 다리 `skipped:not_opted_in` + 경고 한 줄). 사람 셸에는 영향이 없다. 표식을 잘못 더해도 사람 셸에서 설정 opt-in 이 꺼질 뿐이라 안전 쪽이다. **규칙 9 의 의도된 예외(L10 검토 F1-3).** 마스터 §4 규칙 9 는 "`HUB_DATABASE_URL`·확인은 셸 프로필이 아니라 명령 앞에" 다. 설정 파일 `hub.confirm: local` 은 그 규칙의 **의도된 예외**다 — 사람 셸에서, URL 도 설정 파일에 있을 때만 효력이 있다(환경 URL 과 설정 confirm 을 섞지 않는다 — 환경에 테스트 URL 을 준 시험 자식이 사용자 확인을 줍지 않게, 검토 F1-1). URL 값은 어디에도 싣지 않는다 — 경고·`repr` 에 없고, 설정 출처 값은 `HubOptIn.secrets` 로 가림·거부 목록에만 간다. """ from __future__ import annotations import os from collections.abc import Mapping from dataclasses import dataclass, field from typing import Any, Literal ENV_HUB_DATABASE_URL = "HUB_DATABASE_URL" ENV_HUB_CONFIRM = "SOLAR_EVAL_HUB_CONFIRM" ENV_STRICT_INGEST = "SOLAR_EVAL_STRICT_INGEST" ENV_HUB_TEXT_MODE = "HUB_TEXT_MODE" ENV_HOOK_DEBUG = "SOLAR_EVAL_HOOK_DEBUG" #: 에이전트 세션 표식 — 한 곳(D-L10-6 · Q-L10-22). 첫 원소는 Claude Code. AGENT_SESSION_MARKERS: tuple[str, ...] = ( "CLAUDECODE", "CODEX_SANDBOX", "CODEX_SANDBOX_NETWORK_DISABLED", ) #: 옛 이름(L6) — 첫 표식의 별칭. ENV_AGENT_SESSION = AGENT_SESSION_MARKERS[0] #: `SOLAR_EVAL_HUB_CONFIRM`·`hub.confirm` 이 받는 유일한 값. CONFIRM_LOCAL = "local" #: hub CLI 의 사용자 DB 쓰기 확인 플래그. CONFIRM_FLAG = "--i-understand-local-data" TRUTHY = frozenset({"1", "true", "yes"}) DEFAULT_TEXT_MODE = "inline" #: 이보다 짧은 값은 우연히 겹칠 수 있어 가림·거부하지 않는다(URL 은 이보다 길다). MIN_SECRET_LENGTH = 8 SOURCE_ENV = "env" SOURCE_CONFIG = "config" HubSource = Literal["env", "config"] _MARKERS_LABEL = "·".join(AGENT_SESSION_MARKERS) #: 사람이 직접 부를 적재 한 줄(URL 자리는 `…`). MANUAL_INGEST = "HUB_DATABASE_URL=… make hub-ingest CASE= CONFIRM=local" #: 콘솔 경고 문구(값은 싣지 않는다). WARN_CONFIRM_IGNORED_AGENT = ( f"{ENV_HUB_CONFIRM}·설정 파일 hub.confirm 을 무시한다 — 에이전트 세션({_MARKERS_LABEL})에서는 " f"사용자 DB 쓰기 확인을 넘기지 않는다. 사람이 직접: {MANUAL_INGEST}" ) WARN_CONFIRM_UNKNOWN_VALUE = ( f"{ENV_HUB_CONFIRM} 값이 '{CONFIRM_LOCAL}' 이 아니라 무시한다 (받는 값: {CONFIRM_LOCAL})" ) WARN_CONFIG_CONFIRM_UNKNOWN_VALUE = ( f"설정 파일 hub.confirm 값이 '{CONFIRM_LOCAL}' 이 아니라 무시한다 (받는 값: {CONFIRM_LOCAL})" ) WARN_CONFIG_OPTIN_IGNORED_AGENT = ( f"설정 파일 hub.database_url 을 무시한다 — 에이전트 세션({_MARKERS_LABEL})에서는 설정 파일 opt-in·확인을 " f"쓰지 않는다. 사람이 직접: {MANUAL_INGEST}" ) #: 설정 모양 오류 — `{problems}` 는 키 이름만 담은 문제 목록(`HubConfig.problems`). WARN_CONFIG_HUB_INVALID = "설정 파일 hub: 절을 무시한다 — {problems}" @dataclass(frozen=True) class ConfirmDecision: """`--i-understand-local-data` 를 붙일지와, 무시했다면 그 이유(콘솔 경고 한 줄).""" confirm_local: bool warning: str | None = None @dataclass(frozen=True) class HubOptIn: """opt-in 해석 결과. `child_env` 는 설정 출처일 때만(부모 환경 + URL), `secrets` 는 설정 출처 URL 값 — 둘 다 repr 밖.""" source: HubSource | None child_env: Mapping[str, str] | None = field(default=None, repr=False) confirm: ConfirmDecision = ConfirmDecision(False) warnings: tuple[str, ...] = () secrets: tuple[str, ...] = field(default=(), repr=False) @property def opted_in(self) -> bool: return self.source is not None def _env(env: Mapping[str, str] | None) -> Mapping[str, str]: return os.environ if env is None else env def is_agent_session(env: Mapping[str, str] | None = None) -> bool: """에이전트 세션인가 — `AGENT_SESSION_MARKERS` 중 하나라도 비어 있지 않다.""" source = _env(env) return any(source.get(marker, "").strip() for marker in AGENT_SESSION_MARKERS) def resolve_hub_optin(env: Mapping[str, str] | None = None, config: Any | None = None) -> HubOptIn: """환경 변수 > 설정 파일 `hub:` 절(§2.6 표). `config` 는 `cli.config.HubConfig`(없으면 None).""" source_env = _env(env) agent = is_agent_session(source_env) url, confirm, problems = _config_fields(config) warnings: list[str] = [] if problems: warnings.append(WARN_CONFIG_HUB_INVALID.format(problems="; ".join(problems))) secrets = _secrets_of(url) if source_env.get(ENV_HUB_DATABASE_URL, "").strip(): decision = _env_confirm(source_env, agent) or ConfirmDecision(False) return HubOptIn(SOURCE_ENV, None, decision, tuple(warnings), secrets) if url is None or problems: return HubOptIn(None, None, ConfirmDecision(False), tuple(warnings), secrets) if agent: warnings.append(WARN_CONFIG_OPTIN_IGNORED_AGENT) return HubOptIn(None, None, ConfirmDecision(False), tuple(warnings), secrets) child_env = {**source_env, ENV_HUB_DATABASE_URL: url} decision = _env_confirm(source_env, agent) or _config_confirm(confirm) return HubOptIn(SOURCE_CONFIG, child_env, decision, tuple(warnings), secrets) def config_secrets(config: Any | None) -> tuple[str, ...]: """설정 출처 비밀(`hub.database_url` 값) — 상태 파일 거부·콘솔 가림 목록에 더한다(§2.6 "비밀"). 쓰지 않은 설정 값도 넣는다.""" return _secrets_of(_config_fields(config)[0]) def _secrets_of(url: str | None) -> tuple[str, ...]: return (url,) if url is not None and len(url) >= MIN_SECRET_LENGTH else () def _config_fields(config: Any | None) -> tuple[str | None, str | None, tuple[str, ...]]: """`HubConfig` 의 (URL, confirm, 문제) — 값이 문자열이 아니면 없는 것으로 본다.""" if config is None: return None, None, () url = getattr(config, "database_url", None) confirm = getattr(config, "confirm", None) problems = tuple(getattr(config, "problems", ()) or ()) url = url.strip() if isinstance(url, str) and url.strip() else None confirm = confirm.strip() if isinstance(confirm, str) and confirm.strip() else None return url, confirm, problems def _env_confirm(env: Mapping[str, str], agent: bool) -> ConfirmDecision | None: """`SOLAR_EVAL_HUB_CONFIRM` 해석 — 비어 있으면 None(설정 confirm 으로 넘어간다). 에이전트 세션이면 `local` 도 무시.""" raw = env.get(ENV_HUB_CONFIRM, "").strip() if not raw: return None if raw != CONFIRM_LOCAL: return ConfirmDecision(False, WARN_CONFIRM_UNKNOWN_VALUE) if agent: return ConfirmDecision(False, WARN_CONFIRM_IGNORED_AGENT) return ConfirmDecision(True) def _config_confirm(confirm: str | None) -> ConfirmDecision: """설정 `hub.confirm` — URL 출처가 설정이고 사람 셸일 때만 부른다.""" if confirm is None: return ConfirmDecision(False) if confirm != CONFIRM_LOCAL: return ConfirmDecision(False, WARN_CONFIG_CONFIRM_UNKNOWN_VALUE) return ConfirmDecision(True) def strict_requested(flag: bool, env: Mapping[str, str] | None = None) -> bool: """`--strict-ingest` 또는 `SOLAR_EVAL_STRICT_INGEST` 가 참(`1`·`true`·`yes`, 대소문자 무시).""" return flag or _env(env).get(ENV_STRICT_INGEST, "").strip().lower() in TRUTHY def hook_debug_requested(env: Mapping[str, str] | None = None) -> bool: """`SOLAR_EVAL_HOOK_DEBUG` 가 참 — 봉쇄한 예외의 트레이스백을 WARNING 로그로 올린다(현장 진단용).""" return _env(env).get(ENV_HOOK_DEBUG, "").strip().lower() in TRUTHY def text_mode(env: Mapping[str, str] | None = None) -> str: """`HUB_TEXT_MODE` 해석값(비었으면 `inline`) — 색인 키에만 쓴다(D-L6-7).""" return _env(env).get(ENV_HUB_TEXT_MODE, "").strip() or DEFAULT_TEXT_MODE