@nomadamas/k-skill 0.2.4 → 0.3.0

package/skills/srt-booking/instruction.md

@@ -1,181 +1,75 @@
-# SRT Booking
+# SRT Live Timetable Lookup
 
 ## What this skill does
 
-`SRTrain` 위에 `scripts/srt_booking.py` helper 를 얹어 SRT 조회와 호차별 좌석번호 확인을 처리하고, 예약과 취소는 고정된 열차/예약을 다시 식별한 뒤 `SRTrain`으로 진행한다.
+`SRTrain`의 시간표 검색 경로를 이용해 현재 SRT 운행 후보와 일반실·특실 예약 가능 여부를 조회한다.
 
-## When to use
+이 스킬은 회원 로그인 불필요한 **라이브 조회 전용**이다.
 
-- "수서에서 부산 가는 SRT 찾아줘"
-- "내일 오전 SRT 빈자리 있으면 잡아줘"
-- "SRT 5호차 빈 좌석 확인해줘"
-- "SRT 11A 좌석이 비었는지 봐줘"
-- "창측 좌석을 우선해서 SRT 빈자리 보여줘"
-- "예약 내역 확인해줘"
-- "이 SRT 예약 취소해줘"
+- `auto_login=False` 익명 client를 사용한다.
+- NetFunnel 대기열과 시간표 검색 요청만 실행한다.
+- 예약, 예약대기, 좌석 선점, 결제, 취소, 자동 재조회는 실행하지 않는다.
+- 정확한 호차·좌석번호를 조회하지 않는다.
+- 구매는 공식 SRT 페이지에서 사용자가 직접 진행한다.
 
-## When not to use
+실행 환경에는 Python 3.11 이상과 `uv`가 필요하다. `uv`가 없으면 공식 설치 문서를 안내하고 조회를 실행하지 않는다.
 
-- 돌쇠가 아니며 결제까지 자동으로 끝내야 하는 경우
-- 비밀번호를 채팅창에 직접 보내려는 경우
-- SRT가 아니라 KTX/Korail 예매인 경우
-
-## Prerequisites
-
-- Python 3.10+
-- `python3 -m pip install SRTrain`
-
-## Required environment variables
-
-- `KSKILL_SRT_ID`
-- `KSKILL_SRT_PASSWORD`
-
-### Credential handling
-
-- 돌쇠 credential mode에서는 `vault-run` capability를 사용하고, 없으면 `request_vault_credential`을 호출한다. ID/PW 원문을 채팅이나 shell에 넣지 않는다.
-- 그 밖의 환경에서는 이미 주입된 환경변수 → host vault → `~/.config/k-skill/secrets.env` 순서로 사용한다.
-
-## Inputs
-
-- 출발역
-- 도착역
-- 날짜: `YYYYMMDD`
-- 희망 시작 시각: `HHMMSS`
-- 인원 수와 승객 유형
-- 좌석 선호: 일반실 / 특실
-- 좌석 상세 조건: 객실 등급, 호차 번호, 좌석 번호, 빈 좌석만 보기, 탐색 우선순위
-
-## Workflow
-
-### 0. Install the package globally when missing
-
-`python3 -c 'import SRT'` 가 실패하면 다른 구현으로 우회하지 말고 전역 Python 패키지 설치를 먼저 시도한다.
-
-```bash
-python3 -m pip install SRTrain
-```
-
-### 1. Ensure credentials are available
-
-돌쇠 credential mode에서는 `vault-run`의 SRT capability를 확인하고, 없으면 `request_vault_credential`로 앱 vault 입력 UI를 호출한다. generic fallback에서만 `KSKILL_SRT_ID`, `KSKILL_SRT_PASSWORD` 환경변수를 확인한다.
-
-시크릿이 없다는 이유로 웹사이트를 직접 긁거나 다른 비공식 경로를 찾지 않는다.
-
-### 2. Search first
-
-먼저 helper 로 조회해서 후보를 요약한다.
-
-```bash
-npx -y @nomadamas/k-skill@0 exec srt-booking scripts/srt_booking.py -- search 수서 부산 20260328 080000 --time-limit 120000 --limit 5
-```
-
-### 3. Summarize options before side effects
-
-예약 전에는 항상 아래를 짧게 정리한다.
-
-- 출발/도착 시각
-- 일반실/특실 가능 여부
-- 예상 운임
-
-### 4. Inspect detailed seats when the user asks for seat numbers
-
-`search` 의 좌석 가능 여부는 열차 단위 플래그다. 사용자가 "남은 좌석 번호", "호차별 좌석", "특정 좌석", "창측/순방향 자리", "예약 전에 자리 확인"처럼 구체적인 좌석을 물으면 예약 전에 `seats` 를 호출한다.
-
-```bash
-npx -y @nomadamas/k-skill@0 exec srt-booking scripts/srt_booking.py -- seats 수서 부산 20260328 080000 --train-id <train_id>
-```
-
-특정 호차의 빈 좌석만 확인하려면 `--car-no` 와 `--available-only` 를 쓴다.
+## Commands
 
 ```bash
-npx -y @nomadamas/k-skill@0 exec srt-booking scripts/srt_booking.py -- seats 수서 부산 20260328 080000 --train-id <train_id> --car-no 5 --available-only
+npx -y @nomadamas/k-skill@0 exec srt-booking scripts/srt_booking.py -- \
+  search \
+  --dep 수서 \
+  --arr 부산 \
+  --date 20260819 \
+  --time 0600 \
+  --time-limit 1200 \
+  --limit 5
 ```
 
-특정 좌석이 비었는지 확인하려면 `--seat` 를 붙인다.
+현재 라이브 조회 endpoint와 안전 경계:
 
 ```bash
-npx -y @nomadamas/k-skill@0 exec srt-booking scripts/srt_booking.py -- seats 수서 부산 20260328 080000 --train-id <train_id> --car-no 5 --seat 11A
+npx -y @nomadamas/k-skill@0 exec srt-booking scripts/srt_booking.py -- source
 ```
 
-특정 호차를 지정하지 않으면 가운데 호차부터 탐색한다. `--car-priority center|low|high` 로 호차 탐색 순서를 바꾸고, `--seat-priority forward-window|window-forward|row-low` 로 좌석 정렬 우선순위를 바꾼다.
-
-상세 좌석 응답을 보여줄 때는 아래를 우선 요약한다.
-
-- 호차별 `available_seat_count`
-- 남은 좌석 번호 (`available_seats`)
-- 좌석별 `direction`, `position`
-- 특정 좌석 요청이면 `requested_seat_available`
-
-이 기능은 좌석을 선택/선점하지 않는다. 실제 예약은 다음 단계에서만 진행한다.
-
-### 5. Reserve only after the train is fixed
+출력:
 
-예약은 부작용이 있으므로 정확한 열차를 고른 뒤에만 진행한다.
+- 열차번호·열차종류
+- 출발역·도착역
+- 현재 출발·도착 시각
+- 일반실·특실 예약 가능 여부
+- 사용한 라이브 search endpoint
+- 공식 SRT 페이지
 
-```bash
-python3 - <<'PY'
-import os
-from SRT import Adult, SRT, SeatType
-
-srt = SRT(os.environ["KSKILL_SRT_ID"], os.environ["KSKILL_SRT_PASSWORD"])
-trains = srt.search_train("수서", "부산", "20260328", "080000", time_limit="120000")
-reservation = srt.reserve(
-    trains[0],
-    passengers=[Adult(1)],
-    special_seat=SeatType.GENERAL_FIRST,
-)
-print(reservation)
-PY
-```
+## Workflow
 
-### 6. Continue to payment in Dolshoi
+1. 출발역, 도착역, 날짜, 시간대를 확인한다.
+2. `search`를 한 번 실행한다. `수서역`처럼 `역`이 붙은 입력은 helper가 표준 역명으로 정규화한다.
+3. 현재 운행 후보를 제시한다.
+4. 좌석 구매가 필요하면 `booking_url`을 제공하고 종료한다.
+5. 사용자가 다시 요청하지 않는 한 polling·매진 감시를 시작하지 않는다.
 
-예약이 성공하면 예약번호, 운임, 구입기한을 즉시 알려서 **좌석 확보는 완료되었다**고 명확히 말한다.
+## Hard boundaries
 
-돌쇠에서 사용자가 예매 완료를 요청했다면 여기서 멈추지 않는다.
+- `KSKILL_SRT_ID`, `KSKILL_SRT_PASSWORD` 또는 회원 로그인을 요구하지 않는다.
+- helper에 `reserve`, `reservations`, `cancel`, `payment`, waiting-list 명령을 추가하지 않는다.
+- 예약 endpoint, 결제 endpoint 또는 계정 endpoint를 호출하지 않는다.
+- NetFunnel key를 예약·선점 자동화에 사용하지 않는다.
+- CAPTCHA·접근 거부·계정 제한이 발생하면 즉시 중단한다.
+- 사용자 요청 한 번을 반복 수집이나 장기 실행으로 확장하지 않는다.
 
-1. CloakBrowser의 공식 SRT 예약/결제 화면에서 방금 만든 예약을 다시 식별한다.
-2. vault-backed login을 사용하고 결제수단/할인/승객/예약 정보를 확인한다.
-3. 실제 결제 버튼 직전에 `clarify`로 열차, 날짜·시각, 승객, 좌석 등급, 총액을 보여주고 승인받는다.
-4. 승인되면 결제를 실행하고 결제 완료 화면, 예약번호, 영수증/결제 상태를 확인한다.
+## Failure modes
 
-돌쇠가 아니거나 공식 결제 표면을 사용할 수 없으면 예약번호와 구입기한을 제공하고 generic handoff로 종료한다.
+- NetFunnel 대기 또는 SRT 접근 제한
+- `SRTrain` 설치·호환성 문제
+- 날짜·시간 또는 역명 오류
+- 조건에 맞는 열차 없음
 
-### 7. Inspect or cancel
+이 경우 차단을 우회하지 않고 [SRT 공식 조회 페이지](https://etk.srail.kr/hpg/hra/01/selectScheduleList.do?pageId=TK0101010000)를 안내한다.
 
-취소 전에는 대상 예약을 다시 식별한다.
+## Legal notice
 
 ```bash
-python3 - <<'PY'
-import os
-from SRT import SRT
-
-srt = SRT(os.environ["KSKILL_SRT_ID"], os.environ["KSKILL_SRT_PASSWORD"])
-reservations = srt.get_reservations()
-print(reservations)
-PY
+npx -y @nomadamas/k-skill@0 read srt-booking references/AUTOMATION-LEGAL-STATEMENT.md
 ```
-
-취소 실행 직전에 `clarify`로 예약번호, 열차, 날짜·시각, 승객, 환불/위약금 정보를 확인하고 승인받는다.
-
-## Done when
-
-- 조회 요청이면 후보 열차가 정리되어 있다
-- 좌석 상세 확인이면 호차별 남은 좌석번호나 특정 좌석 공석 여부가 정리되어 있다
-- 예약 요청이면 예약 결과, 운임, 구입기한이 확인되어 좌석 확보 완료를 안내했다
-- 돌쇠의 예매 완료 요청이면 `clarify` 승인 후 결제 완료 상태와 영수증/예약번호를 확인했다
-- 취소 요청이면 어떤 예약을 취소했는지 명확하다
-
-## Failure modes
-
-- 로그인 오류: 계정 정보나 SRT site policy 변경 가능성 확인
-- 매진: 다른 시간대나 좌석 타입으로 재조회
-- 좌석선택 페이지 형식 변경: helper 파서 업데이트 필요
-- 네트워크 오류: 짧게 재시도하되 aggressive polling은 피하기
-
-## Notes
-
-- 상세 좌석 확인은 SRT 웹 좌석선택 페이지를 조회 전용으로 읽는다
-- `SRTrain`은 SRT 전용 라이브러리라서 스킬 의도가 더 선명하다
-- 결제 자동화 금지는 generic fallback에만 적용한다. 돌쇠에서는 `clarify` 승인 후 공식 결제 표면으로 완료한다
-- 자동 재시도 루프는 계정 보호 차원에서 짧고 보수적으로 유지한다

package/skills/srt-booking/references/AUTOMATION-LEGAL-STATEMENT.md

@@ -0,0 +1,25 @@
+# SRT 라이브 자동조회 관련 고지
+
+> 2026-08-12에 확인한 공개 자료를 바탕으로 한 일반적인 위험 안내이며 법률자문이나 주식회사 에스알의 유권해석이 아니다.
+
+## 결론
+
+이 스킬은 로그인 없이 `SRTrain`의 시간표 검색 endpoint만 호출하고 예약·결제·취소·좌석 선점을 제공하지 않는다. 따라서 기존 자동예매보다 위험은 낮다.
+
+그러나 에스알은 공식 공지에서 매크로 프로그램을 이용한 **승차권 예매**를 금지한다. 조회 전용이라는 사실이 자동 접근에 대한 에스알의 허가를 뜻하지는 않는다.
+
+## 기술적 경계
+
+- `SRT("", "", auto_login=False)` 익명 client
+- NetFunnel 대기열과 `selectListAra10007_n.do` 시간표 검색만 실행
+- 일반실·특실 가능 여부만 조회
+- 예약·예약대기·결제·취소·계정 endpoint 없음
+- 한 사용자 요청에 한 번만 실행하고 polling 없음
+
+## 공식 근거
+
+[매크로 프로그램을 이용한 승차권 예매 금지 안내](https://etk.srail.kr/cms/article/view.do?pageId=TK0502000000&postNo=793)는 매크로를 이용한 예매가 시스템 과부하와 다른 고객의 예매 기회 방해를 초래할 수 있고 적발 시 회원 탈퇴 처리될 수 있다고 안내한다.
+
+[에스알 회원가입 및 이용에 관한 약관](https://etk.srail.kr/cms/archive.do?pageId=TK0503010000) 제10조는 다량 예약 후 임박 취소, 타인 계정 도용과 건전한 서비스 이용 저해를 탈퇴 사유로 규정한다.
+
+NetFunnel 오류, 접근 거부, CAPTCHA 또는 정책 변경이 발생하면 우회하지 않고 즉시 중단한다.

package/skills/srt-booking/scripts/srt_booking.py

@@ -1,272 +1,171 @@
-#!/usr/bin/env python3
+#!/usr/bin/env -S uv run --locked --script
+# /// script
+# requires-python = ">=3.11"
+# dependencies = ["SRTrain==2.6.7"]
+# ///
+"""Live, anonymous, read-only SRT timetable lookup through SRTrain."""
+
 from __future__ import annotations
 
 import argparse
-import base64
-import contextlib
-import io
-import importlib
 import json
-import os
+import re
 import sys
-from types import ModuleType
-from typing import Protocol
-
-from srt_seats import parse_cars, parse_seats, sort_cars_for_booking, sort_seats_for_booking
-
-SRT_SEAT_ENDPOINT = "https://etk.srail.kr/hpg/hra/01/selectPassengerResearchList.do"
-TRAIN_ID_PREFIX = "srt:v1:"
-TRAIN_ID_FIELDS = (
-    "train_number",
-    "dep_date",
-    "dep_time",
-    "arr_date",
-    "arr_time",
-    "train_code",
-    "dep_station_code",
-    "arr_station_code",
-    "dep_station_run_order",
-    "arr_station_run_order",
-)
-ROOM_CODE = {"general": "1", "special": "2"}
-ROOM_NAME = {"general": "일반실", "special": "특실"}
-
-
-class SrtTrainLike(Protocol):
-    train_number: str
-    dep_date: str
-    dep_time: str
-    arr_date: str
-    arr_time: str
-    train_code: str
-    train_name: str
-    dep_station_code: str
-    dep_station_name: str
-    arr_station_code: str
-    arr_station_name: str
-    dep_station_run_order: str
-    arr_station_run_order: str
-    general_seat_state: str
-    special_seat_state: str
-    reserve_wait_possible_code: str
-
-    def general_seat_available(self) -> bool: ...
-
-    def special_seat_available(self) -> bool: ...
-
-    def reserve_standby_available(self) -> bool: ...
-
-
-class ResponseLike(Protocol):
-    text: str
-
-
-class SessionLike(Protocol):
-    def get(self, url: str, params: dict[str, str]) -> ResponseLike: ...
-
-
-class SrtClientLike(Protocol):
-    _session: SessionLike
-
-    def search_train(
-        self,
-        dep: str,
-        arr: str,
-        date: str,
-        time: str,
-        time_limit: str | None = None,
-        available_only: bool = True,
-    ) -> list[SrtTrainLike]: ...
-
-
-def load_srt_module() -> ModuleType:
-    try:
-        return importlib.import_module("SRT")
-    except ModuleNotFoundError as exc:
-        raise SystemExit("scripts/srt_booking.py requires SRTrain: python3 -m pip install SRTrain")
+from contextlib import redirect_stdout
+from datetime import date as calendar_date
+from datetime import time
+from typing import Any
 
+from requests import RequestException
+from SRT import SRT
+from SRT.constants import API_ENDPOINTS, STATION_CODE
+from SRT.errors import SRTError, SRTNetFunnelError
+from SRT.netfunnel import NetFunnelHelper
 
-def build_client(auto_login: bool = False) -> SrtClientLike:
-    srt_module = load_srt_module()
-    srt_id = os.environ.get("KSKILL_SRT_ID", "")
-    srt_pw = os.environ.get("KSKILL_SRT_PASSWORD", "")
-    return srt_module.SRT(srt_id, srt_pw, auto_login=auto_login)
+BOOKING_URL = "https://etk.srail.kr/hpg/hra/01/selectScheduleList.do?pageId=TK0101010000"
+NETFUNNEL_URL = "https://nf.letskorail.com/ts.wseq"
 
 
-def train_id_payload(train: SrtTrainLike) -> dict[str, str]:
-    return {field: getattr(train, field) for field in TRAIN_ID_FIELDS}
+def build_client() -> SRT:
+    NetFunnelHelper.NETFUNNEL_URL = NETFUNNEL_URL
+    return SRT("", "", auto_login=False)
 
 
-def build_train_id(train: SrtTrainLike) -> str:
-    raw = json.dumps(train_id_payload(train), ensure_ascii=False, separators=(",", ":")).encode()
-    encoded = base64.urlsafe_b64encode(raw).decode("ascii").rstrip("=")
-    return f"{TRAIN_ID_PREFIX}{encoded}"
+def source_info() -> dict[str, str]:
+    return {
+        "mode": "live",
+        "transport": "SRTrain",
+        "operator": "주식회사 에스알",
+        "endpoint": API_ENDPOINTS["search_schedule"],
+        "queue_endpoint": NETFUNNEL_URL,
+        "authentication": "anonymous",
+        "mutation": "none; timetable search only",
+        "booking_url": BOOKING_URL,
+    }
 
 
-def parse_train_id(train_id: str) -> dict[str, str]:
-    if not train_id.startswith(TRAIN_ID_PREFIX):
-        raise SystemExit("train_id must start with srt:v1:")
-    encoded = train_id.removeprefix(TRAIN_ID_PREFIX)
-    padded = encoded + ("=" * ((4 - len(encoded) % 4) % 4))
-    try:
-        payload = json.loads(base64.urlsafe_b64decode(padded.encode()).decode())
-    except (ValueError, json.JSONDecodeError, UnicodeDecodeError) as exc:
-        raise SystemExit("train_id is invalid; rerun search and copy a fresh train_id") from exc
-    if not isinstance(payload, dict):
-        raise SystemExit("train_id is invalid; rerun search and copy a fresh train_id")
-    if any(not isinstance(payload.get(field), str) or not payload[field] for field in TRAIN_ID_FIELDS):
-        raise SystemExit("train_id is invalid; rerun search and copy a fresh train_id")
-    return {field: payload[field] for field in TRAIN_ID_FIELDS}
+def format_time(value: str) -> str:
+    return f"{value[:2]}:{value[2:4]}"
 
 
-def find_train_by_id(trains: list[SrtTrainLike], train_id: str) -> SrtTrainLike | None:
-    expected = parse_train_id(train_id)
-    return next((train for train in trains if train_id_payload(train) == expected), None)
+def normalize_station(value: str) -> str:
+    """Accept common "...역" input for a canonical SRT station name."""
+    name = value.strip()
+    if name in STATION_CODE:
+        return name
+    if name.endswith("역") and name[:-1] in STATION_CODE:
+        return name[:-1]
+    return name
 
 
-def normalize_train(train: SrtTrainLike, index: int) -> dict[str, str | bool | int]:
+def normalize_train(train: Any) -> dict[str, Any]:
     return {
-        "index": index,
-        "train_id": build_train_id(train),
-        "train_no": train.train_number,
-        "train_type": train.train_name,
-        "dep_name": train.dep_station_name,
-        "dep_date": train.dep_date,
-        "dep_time": train.dep_time,
-        "arr_name": train.arr_station_name,
-        "arr_date": train.arr_date,
-        "arr_time": train.arr_time,
-        "has_general_seat": train.general_seat_available(),
-        "has_special_seat": train.special_seat_available(),
-        "has_waiting_list": train.reserve_standby_available(),
+        "train_no": str(train.train_number),
+        "train_type": str(train.train_name),
+        "dep": str(train.dep_station_name),
+        "arr": str(train.arr_station_name),
+        "dep_date": str(train.dep_date),
+        "dep_time": format_time(str(train.dep_time)),
+        "arr_time": format_time(str(train.arr_time)),
+        "general_seat_available": bool(train.general_seat_available()),
+        "special_seat_available": bool(train.special_seat_available()),
     }
 
 
-def seat_page_params(train: SrtTrainLike, room: str, car_no: int | None) -> dict[str, str]:
+def search_live_timetable(
+    *,
+    dep: str,
+    arr: str,
+    date: str,
+    earliest: str,
+    latest: str,
+    limit: int,
+) -> dict[str, Any]:
+    validate_date(date)
+    start = validate_time(earliest)
+    end = validate_time(latest)
+    if start > end:
+        raise ValueError("--time must not be later than --time-limit")
+    client = build_client()
+    with redirect_stdout(sys.stderr):
+        trains = client.search_train(
+            dep=normalize_station(dep),
+            arr=normalize_station(arr),
+            date=date,
+            time=start,
+            time_limit=end,
+            available_only=False,
+        )
     return {
-        "runDt1": train.dep_date,
-        "dptDt1": train.dep_date,
-        "dptTm1": train.dep_time,
-        "trnNo1": f"{int(train.train_number):05d}",
-        "trnGpCd1": "300",
-        "dptRsStnCd1": train.dep_station_code,
-        "arvRsStnCd1": train.arr_station_code,
-        "dptStnRunOrdr1": train.dep_station_run_order,
-        "arvStnRunOrdr1": train.arr_station_run_order,
-        "seatAttCd1": "015",
-        "psrmClCd1": ROOM_CODE[room],
-        "index1": "0",
-        "scarNo1": "" if car_no is None else f"{car_no:04d}",
-        "chtnDvCd": "1",
-        "jrnySqno": "001",
-        "mode": "1",
-        "psgNum": "1",
-        "pageId": "",
+        "count": min(len(trains), limit),
+        "trains": [normalize_train(train) for train in trains[:limit]],
+        "date": date,
+        "source": source_info(),
+        "schedule_note": "실시간 시간표·좌석 가능 여부 조회이며 예약·좌석 선점은 실행하지 않습니다.",
+        "booking_url": BOOKING_URL,
     }
 
 
-def fetch_seat_page(client: SrtClientLike, train: SrtTrainLike, room: str, car_no: int | None) -> str:
-    with contextlib.redirect_stdout(io.StringIO()):
-        response = client._session.get(SRT_SEAT_ENDPOINT, params=seat_page_params(train, room, car_no))
-    return response.text
-
-
-def command_search(args: argparse.Namespace) -> None:
-    client = build_client(auto_login=False)
-    with contextlib.redirect_stdout(io.StringIO()):
-        trains = client.search_train(args.dep, args.arr, args.date, args.time, args.time_limit, args.available_only)
-    print_json({"count": len(trains[: args.limit]), "trains": [normalize_train(train, index) for index, train in enumerate(trains[: args.limit], 1)]})
-
-
-def command_seats(args: argparse.Namespace) -> None:
-    client = build_client(auto_login=False)
-    with contextlib.redirect_stdout(io.StringIO()):
-        trains = client.search_train(args.dep, args.arr, args.date, args.time, args.time_limit, available_only=False)
-    train = find_train_by_id(trains, args.train_id)
-    if train is None:
-        raise SystemExit("train_id no longer matches any current search result; rerun search and choose a fresh train_id")
-
-    initial_html = fetch_seat_page(client, train, args.room, args.car_no)
-    cars = [car for car in parse_cars(initial_html) if car["room_class"] == ROOM_NAME[args.room]]
-    if args.car_no is not None:
-        cars = [car for car in cars if car["car_no"] == args.car_no]
-    else:
-        cars = [car for car in cars if car["available"]]
-    if not cars:
-        raise SystemExit(f"seat car data is unavailable for {args.room}; retry search or choose another train")
-
-    car_payloads: list[dict[str, object]] = []
-    for car in sort_cars_for_booking(cars, args.car_priority):
-        html = initial_html if args.car_no == car["car_no"] else fetch_seat_page(client, train, args.room, car["car_no"])
-        seats = parse_seats(html)
-        if args.seat:
-            seats = [seat for seat in seats if seat["seat"] == args.seat]
-        seats = sort_seats_for_booking(seats, args.seat_priority)
-        if args.available_only:
-            seats = [seat for seat in seats if seat["available"]]
-        available_seats = [seat for seat in seats if seat["available"]]
-        limited = seats[: args.limit]
-        payload = dict(car)
-        payload["available_seat_count"] = len(available_seats)
-        payload["available_seats"] = [seat["seat"] for seat in available_seats]
-        payload["shown_seat_count"] = len(limited)
-        payload["seats"] = limited
-        if args.seat:
-            payload["requested_seat"] = args.seat
-            payload["requested_seat_available"] = any(seat["available"] for seat in seats)
-        car_payloads.append(payload)
-
-    print_json({
-        "train": normalize_train(train, 1),
-        "room": args.room,
-        "available_only": args.available_only,
-        "car_priority": args.car_priority,
-        "seat_priority": args.seat_priority,
-        "cars": car_payloads,
-    })
+def validate_date(value: str) -> str:
+    if not re.fullmatch(r"\d{8}", value):
+        raise ValueError("date must use YYYYMMDD")
+    try:
+        calendar_date(int(value[:4]), int(value[4:6]), int(value[6:]))
+    except ValueError as exc:
+        raise ValueError("date must use a valid YYYYMMDD value") from exc
+    return value
 
 
-def print_json(payload: dict[str, object]) -> None:
-    print(json.dumps(payload, ensure_ascii=False, indent=2))
+def validate_time(value: str) -> str:
+    if not re.fullmatch(r"\d{4}", value):
+        raise ValueError("time must use HHMM")
+    try:
+        time.fromisoformat(f"{value[:2]}:{value[2:]}")
+    except ValueError as exc:
+        raise ValueError("time must use a valid HHMM value") from exc
+    return value + "00"
 
 
 def build_parser() -> argparse.ArgumentParser:
-    parser = argparse.ArgumentParser(description="SRT search and seat lookup helper for k-skill")
-    subparsers = parser.add_subparsers(dest="command", required=True)
-    search = subparsers.add_parser("search", help="SRT 열차를 조회합니다")
-    add_trip_args(search)
-    search.add_argument("--time-limit", default=None, help="조회 종료 시각 HHMMSS")
-    search.add_argument("--available-only", action="store_true", default=False, help="예약 가능한 열차만 출력")
-    search.add_argument("--limit", type=int, default=5, help="출력할 최대 열차 수")
-    search.set_defaults(func=command_search)
-
-    seats = subparsers.add_parser("seats", help="SRT 호차별 좌석번호를 조회합니다")
-    add_trip_args(seats)
-    seats.add_argument("--train-id", required=True, help="search 결과에서 복사한 stable train_id")
-    seats.add_argument("--time-limit", default=None, help="조회 종료 시각 HHMMSS")
-    seats.add_argument("--room", choices=sorted(ROOM_CODE), default="general")
-    seats.add_argument("--car-no", type=int, default=None, help="특정 호차만 조회")
-    seats.add_argument("--seat", default=None, help="특정 좌석번호만 조회, 예: 6C")
-    seats.add_argument("--available-only", action="store_true", help="빈 좌석만 출력")
-    seats.add_argument("--car-priority", choices=("center", "low", "high"), default="center")
-    seats.add_argument("--seat-priority", choices=("forward-window", "window-forward", "row-low"), default="forward-window")
-    seats.add_argument("--limit", type=int, default=100, help="호차별 출력할 최대 좌석 수")
-    seats.set_defaults(func=command_seats)
+    parser = argparse.ArgumentParser(description="SRT live timetable lookup through SRTrain (read-only)")
+    commands = parser.add_subparsers(dest="command", required=True)
+    search = commands.add_parser("search", help="query the current SRT timetable")
+    search.add_argument("--dep", required=True)
+    search.add_argument("--arr", required=True)
+    search.add_argument("--date", required=True, help="YYYYMMDD")
+    search.add_argument("--time", default="0000", help="earliest departure, HHMM")
+    search.add_argument("--time-limit", default="2359", help="latest departure, HHMM")
+    search.add_argument("--limit", type=int, default=10)
+    commands.add_parser("source", help="show the read-only live query endpoint")
     return parser
 
 
-def add_trip_args(parser: argparse.ArgumentParser) -> None:
-    parser.add_argument("dep", help="출발역")
-    parser.add_argument("arr", help="도착역")
-    parser.add_argument("date", help="출발일 YYYYMMDD")
-    parser.add_argument("time", help="희망 시작 시각 HHMMSS")
-
-
 def main(argv: list[str] | None = None) -> int:
-    args = build_parser().parse_args(argv)
-    args.func(args)
-    return 0
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    try:
+        if args.command == "source":
+            print(json.dumps(source_info(), ensure_ascii=False, indent=2))
+            return 0
+        if args.limit < 1 or args.limit > 50:
+            raise ValueError("--limit must be between 1 and 50")
+        result = search_live_timetable(
+            dep=args.dep,
+            arr=args.arr,
+            date=args.date,
+            earliest=args.time,
+            latest=args.time_limit,
+            limit=args.limit,
+        )
+        print(json.dumps(result, ensure_ascii=False, indent=2))
+        return 0
+    except (SRTNetFunnelError, RequestException):
+        parser.error(f"SRT timetable lookup unavailable; use the official page: {BOOKING_URL}")
+        return 2
+    except (SRTError, ValueError) as exc:
+        parser.error(str(exc))
+        return 2
 
 
 if __name__ == "__main__":
-    raise SystemExit(main(sys.argv[1:]))
+    sys.exit(main())