"""훅 콘솔 — 다리별 한 줄과 되살리기 명령 문구 (계획 2026-09-27 L6 §2.6 표 · §2.7 · 검토 F16). 되살리기 명령의 URL 자리는 늘 `HUB_DATABASE_URL=…` 이다 — 값은 어디에도 싣지 않는다(D-L6-4). 실패 줄은 빨강 + 되살리기. 레거시 화면(`public`)은 L10 컷오버로 코드에서 사라졌다 — 레거시 수동 적재 줄은 없다(계획 2026-09-28 L10 §2.6 · L6b 후속 1). hub opt-in 이 없으면(`not_opted_in`) 빨간 줄로 "이 run 은 hub(/v1)에 없다" 와 켜는 법·지금 싣는 명령을 안내한다(마스터 D-M2-18). 요약 머리에는 훅 전체 경과 초(상태 파일의 `started_at`→`finished_at`, 잠금 대기 포함)를 붙인다 — 첫 실데이터 run(U-L6a-1)에서 콘솔만으로 hub 적재 시간을 알 수 없었기 때문이다. 시각이 없거나 형식이 다르면 붙이지 않는다. """ from __future__ import annotations from collections.abc import Iterable, Mapping from datetime import datetime from typing import Any import click from solar_eval.hub_hook import optin from solar_eval.hub_hook.types import ( CASE_BLOCKED_PREFIX, CASE_FAILED_PREFIX, FILTER_NO_MATCH, HUB_ERR_CONFIRMATION_REQUIRED, HUB_ERR_CONNECTION_FAILED, HUB_FAILED_PREFIX, LEG_BUNDLE, LEG_HOOK, LEG_HUB, LEG_LOCK, LEG_PUBLISH, LOCK_TIMEOUT, NOT_OPTED_IN, RUN_NOT_OK_PREFIX, SCHEMA_MISMATCH, SKIP_CASE_UNMAPPED, SKIP_DATA_HOME_INSIDE_REPO, SKIP_DATA_HOME_MISMATCH, SKIP_NO_REPO_ROOT, SKIP_NOT_REPO_MANAGED, SMOKE_RUN, STAGE_CASE_LOCK, STATUS_FAILED, STATUS_OK, STATUS_SKIPPED, HookResult, LegResult, Skip, ) URL_PLACEHOLDER = "HUB_DATABASE_URL=…" #: 상태 파일 시각 형식(`hook._now` 와 같다). HOOK_TIME_FORMAT = "%Y-%m-%dT%H:%M:%SZ" LEG_LABELS = { LEG_BUNDLE: "번들", LEG_HUB: "hub 적재", LEG_LOCK: "case 잠금", LEG_HOOK: "훅", LEG_PUBLISH: "채점 발행", } SKIP_REASONS = { SKIP_NOT_REPO_MANAGED: "레포 관리 프로젝트가 아니다", SKIP_NO_REPO_ROOT: "레포 config 루트가 없다(--projects-dir 등)", SKIP_CASE_UNMAPPED: "project 가 case 에 매핑되지 않는다 — make bundle-census 로 확인", SKIP_DATA_HOME_MISMATCH: "엔진 아카이브가 데이터 홈 밖이다", SKIP_DATA_HOME_INSIDE_REPO: "데이터 홈이 레포 안이다 — 훅 파생물은 git 밖에 둔다(CBS_DATA_HOME)", } #: 요약 줄에 싣는 번들 다리 detail 키(순서대로). _BUNDLE_SUMMARY_KEYS = ( (("backfill", "wrap"), "wrap"), (("backfill", "eval_wrap"), "eval-wrap"), (("rescore", "status"), "재채점"), (("indexes",), "색인"), ) # ── 되살리기 명령 ──────────────────────────────────────────────────────── def hub_ingest_command(case_ref: str) -> str: return f"{URL_PLACEHOLDER} make hub-ingest CASE={case_ref} CONFIRM=local" def hub_backfill_command(case_ref: str, run_id: str) -> str: return f'make hub-backfill CASE={case_ref} ARGS="--run {run_id}"' def hub_recovery(code: str, case_ref: str, run_id: str) -> str: """hub 다리 실패 코드 → 되살리기 문구(§2.6 표).""" ingest = hub_ingest_command(case_ref) if code == f"{HUB_FAILED_PREFIX}{HUB_ERR_CONFIRMATION_REQUIRED}": return _confirmation_hint(ingest) if code == f"{HUB_FAILED_PREFIX}{HUB_ERR_CONNECTION_FAILED}": return f"make experiment-hub-up 뒤 {ingest}" if code == f"{CASE_FAILED_PREFIX}{STAGE_CASE_LOCK}": return f"앞 적재가 끝난 뒤 {ingest}" if code.startswith((CASE_BLOCKED_PREFIX, CASE_FAILED_PREFIX)): return f"{ingest} 후 이슈 표(/v1/{case_ref}) 확인" if code == SCHEMA_MISMATCH: return ( f"hub 스키마 판이 다르다 — {URL_PLACEHOLDER} make hub-m1-local CASE={case_ref} " "CONFIRM=local SKIP_PULL=1 FROM=backfill (주의: 재구성은 모든 case 를 지운다, case 마다 다시)" ) if code.startswith(RUN_NOT_OK_PREFIX): return f"{hub_backfill_command(case_ref, run_id)} 뒤 {ingest}" if code == FILTER_NO_MATCH: return f"pnpm 워크스페이스에 @poc/eval-store 가 없다 — pnpm install 뒤 {ingest}" return ingest #: 사용자 DB 쓰기 확인 안내(사람 셸) — 영속 `hub.confirm` 은 마스터 §4 규칙 9 의 의도된 예외다(L10 §2.6 · 검토 F1-3). CONFIRMATION_HINT_HUMAN = ( "사용자 DB 에 쓰려면 명령 앞에 SOLAR_EVAL_HUB_CONFIRM=local 을 붙이거나 설정 파일 hub.confirm: local" "(사람 셸만 · URL 도 설정에 있을 때만 — 규칙 9 의 의도된 예외)" ) #: `not_opted_in` 빨간 줄의 머리(사람·에이전트 공통). NOT_OPTED_IN_HEAD = "hub opt-in 없음 — 이 run 은 hub(/v1)에 없다." def not_opted_in_hint(case_ref: str) -> str: """hub opt-in 이 없다 — 빨간 줄 안내(마스터 D-M2-18 · L10 §2.6 표 "둘 다 없음"). URL 값은 싣지 않는다. 에이전트 세션(`optin.AGENT_SESSION_MARKERS`)은 설정 파일 `hub.database_url` 을 무시하므로(D-L10-6) "설정 파일로 켜라" 를 말하지 않고 사람이 부를 명령만 준다 — 바로 앞 "설정 파일을 무시한다" 경고와 어긋나지 않게(리뷰 L10 지적 3, `_confirmation_hint` 와 같은 갈래). """ ingest = hub_ingest_command(case_ref) if optin.is_agent_session(): return f"{NOT_OPTED_IN_HEAD} 에이전트 세션은 설정 파일 opt-in 을 따르지 않는다 — 사람이 직접: {ingest}" return ( f"{NOT_OPTED_IN_HEAD} 켜려면 설정 파일 hub.database_url 또는 명령 앞 " f"{URL_PLACEHOLDER}. 지금 싣기: {ingest}" ) def _confirmation_hint(ingest: str) -> str: """hub 가 사용자 DB 쓰기 확인을 요구했다. 에이전트 세션(`optin.AGENT_SESSION_MARKERS`)은 확인을 무시하므로 사람이 부를 명령을 안내한다.""" if optin.is_agent_session(): return f"에이전트 세션은 사용자 DB 쓰기 확인을 넘기지 않는다 — 사람이 직접: {ingest}" return CONFIRMATION_HINT_HUMAN def default_hint(leg_name: str, leg: LegResult, case_ref: str | None, run_id: str) -> str | None: """다리가 hint 를 싣지 않았을 때 콘솔이 붙이는 안내.""" if leg.hint is not None or case_ref is None: return leg.hint if leg.status == STATUS_SKIPPED and leg_name == LEG_HUB and leg.code == NOT_OPTED_IN: return not_opted_in_hint(case_ref) if leg.status != STATUS_FAILED: return None if leg_name == LEG_HUB: return hub_recovery(leg.code, case_ref, run_id) if leg_name == LEG_LOCK and leg.code == LOCK_TIMEOUT: return f"같은 case 의 다른 훅이 끝난 뒤 {hub_backfill_command(case_ref, run_id)} → {hub_ingest_command(case_ref)}" return f"{hub_backfill_command(case_ref, run_id)} → {hub_ingest_command(case_ref)}" # ── 출력 ───────────────────────────────────────────────────────────────── def echo_no_ingest(project: str, run_id: str, case_ref: str | None) -> None: """`--no-ingest` — hub 훅 전체를 건너뛴다는 한 줄(Q-M2-4). `project` 는 호출자 시그니처 유지용이다(L10 — 레거시 줄 삭제).""" del project # 레거시 화면 수동 적재 줄이 L10 에서 사라졌다(계획 2026-09-28 L10 §2.6) if case_ref is None: click.secho("\nhub 훅 건너뜀(--no-ingest)", fg="yellow") return revive = f"{hub_backfill_command(case_ref, run_id)} → {hub_ingest_command(case_ref)}" click.secho(f"\nhub 훅 건너뜀(--no-ingest) — 되살리기: {revive}", fg="yellow") def echo_skip(skip: Skip, project: str) -> None: """hub 대상이 아닌 run — 한 줄(standalone 은 부르지 않는다).""" reason = SKIP_REASONS.get(skip.code, skip.code) paths = " · ".join(f"{k}={v}" for k, v in skip.detail.items()) suffix = f" ({paths})" if paths else "" click.secho(f"\nhub 훅 건너뜀: {skip.code} — {reason}{suffix}", fg="yellow") def echo_smoke(case_ref: str) -> None: """`--limit` 스모크 run — 한 줄(잠금·상태 파일 없음, D-L6-10 · 완료 정의 §0.4-2).""" click.secho( f"\nhub 훅 건너뜀: {SMOKE_RUN} — --limit 스모크 run 은 번들·hub 에 싣지 않는다 ({case_ref})", fg="yellow", ) def elapsed_seconds(result: HookResult) -> int | None: """훅 전체 경과 초(`started_at`→`finished_at`). 시각이 없거나 형식이 다르거나 음수면 None.""" if not result.started_at or not result.finished_at: return None try: started = datetime.strptime(result.started_at, HOOK_TIME_FORMAT) finished = datetime.strptime(result.finished_at, HOOK_TIME_FORMAT) except ValueError: return None seconds = int((finished - started).total_seconds()) return seconds if seconds >= 0 else None def echo_summary(result: HookResult, project: str) -> None: """다리마다 한 줄 + 실패면 되살리기(§2.7). 머리에 경과 초. 레거시 화면 줄은 L10 에서 없어졌다.""" elapsed = elapsed_seconds(result) suffix = f" · 경과 {elapsed} s" if elapsed is not None else "" click.secho( f"\nExperiment Hub 훅 — {result.case or project} · {result.run_id}{suffix}", fg="blue", bold=True ) for name, leg in result.legs.items(): _echo_leg(name, leg, result.case, result.run_id) def _echo_leg(name: str, leg: LegResult, case_ref: str | None, run_id: str) -> None: label = f" {LEG_LABELS.get(name, name):<10}" hint = default_hint(name, leg, case_ref, run_id) if leg.status == STATUS_OK: details = _ok_details(leg.detail) click.secho(f"{label} ok{f' ({details})' if details else ''}", fg="green") elif leg.status == STATUS_FAILED: click.secho(f"{label} 실패 — {leg.code}", fg="red", bold=True) if hint: click.secho(f" {'':<10} 되살리기: {hint}", fg="red") elif leg.status == STATUS_SKIPPED: # hub opt-in 없음은 빨간 줄(D-M2-18 — 이 run 은 /v1 에 없다), 그 밖 건너뜀은 노랑 color = "red" if (name, leg.code) == (LEG_HUB, NOT_OPTED_IN) else "yellow" click.secho(f"{label} 건너뜀 — {leg.code}{f'. {hint}' if hint else ''}", fg=color) else: click.secho(f"{label} 돌지 않음 — {leg.code}", fg="yellow") def _ok_details(detail: Mapping[str, Any]) -> str: parts = [] for path, label in _BUNDLE_SUMMARY_KEYS: value: Any = detail for key in path: value = value.get(key) if isinstance(value, Mapping) else None if isinstance(value, str): parts.append(f"{label} {value}") return " · ".join(parts) def echo_batch_hub(leg: LegResult, case_ref: str, run_ids: Iterable[str]) -> None: """batch 끝 hub 다리 한 줄(D-L6-12).""" ids = list(run_ids) _echo_leg(LEG_HUB, leg, case_ref, ids[0] if len(ids) == 1 else "") def echo_batch_summary(results: Iterable[HookResult | None]) -> None: """batch 끝 요약 "훅: ok N · 실패 M · 건너뜀 K"(건너뜀 = 훅이 돌 다리가 없었던 run).""" ok = failed = skipped = 0 for result in results: if result is not None and not result.ok: failed += 1 elif result is not None and any(leg.status == STATUS_OK for leg in result.legs.values()): ok += 1 else: skipped += 1 color = "red" if failed else "green" click.secho(f"훅: ok {ok} · 실패 {failed} · 건너뜀 {skipped}", fg=color) def echo_warning(message: str) -> None: click.secho(f" ⚠ {message}", fg="yellow", err=True) def echo_hook_crashed(code: str) -> None: """훅 바깥 겹이 예외를 잡았다 — run 결과는 그대로다(D-L6-2).""" click.secho(f"\nExperiment Hub 훅이 예기치 않게 멈췄다 — {code} (run 결과는 디스크에 있다)", fg="red") def echo_status_write_failed(code: str) -> None: echo_warning(f"훅 상태 파일을 쓰지 못했다 — {code}")