File size: 10,361 Bytes
3dfc93b
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
"""ν›… 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=<a/c> 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