Prefer N-card selection by list index so full card numbers are not echoed through JSON output or required in shell history. Keep direct card-number input as a compatibility escape hatch with an explicit warning.\n\nConstraint: PR #231 scope is limited to ktx-booking docs, helper, and tests.\nRejected: Require users to copy full card numbers from ncard-list | exposes sensitive identifiers in logs and shell history.\nConfidence: high\nScope-risk: narrow\nDirective: Keep N-card list outputs masked; prefer index-based selection for future reservation flows.\nTested: python3 -m py_compile scripts/ktx_booking.py scripts/test_ktx_booking.py; PYTHONPATH=scripts python3 -m unittest scripts.test_ktx_booking; npm run lint; npm run typecheck; npm test\nNot-tested: Live Korail N-card reservation; requires real user credentials and owned N-card.
- ncard-list: 보유 N카드 목록 조회 (owned_ncards)
- ncard-search: N카드 할인 열차 조회 (search_owned_ncard_trains)
- reserve --ncard-no: N카드 번호로 할인 승객 예약
- NCardPassenger는 별도 try/except ImportError 블록으로 분리해
표준 korail2 환경에서도 모듈이 정상 로드되도록 처리
- korail2-ncard 미설치 시 N카드 커맨드에서 설치 안내 출력
- 관련 테스트 7개 추가 (총 18개)
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* Protect explicit Korail train-type replay
Issue #171 added explicit train-type selection for non-KTX Korail routes. The merged implementation already wires search and reserve through TRAIN_TYPE_MAP; this follow-up locks that behavior with command-level and parser regression coverage, removes stale test import noise, and aligns the skill shortlist wording with the broader train_type output.
Constraint: The ktx-booking skill keeps ktx as the default train type for backward compatibility.
Rejected: Encode train type into train_id in this follow-up | larger selector schema change already marked as non-blocking UX follow-up.
Confidence: high
Scope-risk: narrow
Directive: Do not hardcode command_search or command_reserve back to TrainType.KTX; keep parser choices derived from TRAIN_TYPE_MAP.
Tested: python3 scripts/ktx_booking.py search --help
Tested: python3 scripts/ktx_booking.py reserve --help
Tested: PYTHONPATH=scripts python3 -m unittest scripts.test_ktx_booking
Tested: python3 -m py_compile scripts/ktx_booking.py scripts/test_ktx_booking.py
Tested: PYTHONNOUSERSITE=1 PYTHONPATH=scripts python3 -S -c 'import ktx_booking; print(ktx_booking._KORAIL_IMPORT_ERROR); print(ktx_booking.TRAIN_TYPE_MAP["itx-cheongchun"])'
Tested: PYTHONNOUSERSITE=1 PYTHONPATH=scripts python3 -m unittest discover -s scripts -p 'test_ktx_booking.py'
Tested: python3 -S scripts/ktx_booking.py search --help; python3 -S scripts/ktx_booking.py reserve --help
Tested: npm run lint
Tested: npm run typecheck
Tested: npm test
Not-tested: Live Korail search/reserve requiring credentials and external availability
* Guard KTX search default during train-type regression
Issue #171 locked explicit train-type choices for Korail search and reserve flows. The follow-up review found reserve default coverage but no direct search default assertion, so this adds the narrow parser regression without changing runtime behavior.\n\nConstraint: Issue #171 requires search and reserve train-type behavior to stay regression-covered.\nRejected: Broaden command-level tests for every train type | parser choices already loop over TRAIN_TYPE_MAP and command forwarding is covered for the non-KTX regression route.\nConfidence: high\nScope-risk: narrow\nTested: PYTHONPATH=scripts python3 -m unittest scripts.test_ktx_booking\nTested: python3 -m py_compile scripts/ktx_booking.py scripts/test_ktx_booking.py\nTested: npm run lint\nTested: npm run typecheck\nTested: npm test\nNot-tested: live Korail search/reserve requiring credentials and external service availability
* Tighten KTX train-type regression tests
The Issue #171 follow-up already locked the train-type CLI behavior. This pass addresses the remaining review cleanup in the modified test file by narrowing the normalized train_id before reuse and tidying formatting without changing behavior.
Constraint: Keep the PR scoped to ktx-booking regression coverage and documentation
Rejected: Encode train_type into train_id in this follow-up | broader selector migration is outside the approved regression scope
Confidence: high
Scope-risk: narrow
Tested: PYTHONPATH=scripts python3 -m unittest scripts.test_ktx_booking
Tested: python3 -m py_compile scripts/ktx_booking.py scripts/test_ktx_booking.py
Tested: pyright scripts/test_ktx_booking.py
Tested: npm run lint
Tested: npm run typecheck
Tested: npm test
Not-tested: live Korail search/reserve requiring credentials and external service availability
The CLI hardcoded TrainType.KTX in command_search and command_reserve,
which silently excluded ITX-청춘, ITX-새마을, 무궁화호, etc. Routes
served only by non-KTX trains (e.g. 남춘천→용산 via ITX-청춘) returned
zero results with no error.
Add an explicit --train-type flag (default: ktx) so the skill keeps
its KTX-first identity but lets users opt into other Korail train
types when needed:
ktx, itx-saemaeul, mugunghwa, nuriro, tonggeun,
itx-cheongchun, airport, all
Default stays as ktx — fully backward compatible. SKILL.md updated
with usage examples for both search and reserve.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Agent environments (OpenClaw, Claude Code, Codex) assume users delegate
credentials to the agent. sops+age added setup friction without real
security benefit since the agent decrypts on every call anyway.
New model: skills declare required env var names; how they are supplied
is up to the agent (own vault, shell env, or ~/.config/k-skill/secrets.env
as the default fallback with 0600 permissions).
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
The validate job was failing because the KTX helper regression suite imported optional runtime dependencies directly from the module top level. GitHub Actions does not inherit the local user site-packages that made those imports succeed on the workstation, so the test suite died before it could exercise the helper logic.
This change makes the helper import-safe in minimal environments by deferring requests usage, providing lightweight fallbacks for optional Korail/Crypto imports during unit tests, and surfacing an explicit install command when the real runtime dependencies are actually needed. The docs now list pycryptodome alongside korail2, and the regression suite forces PYTHONNOUSERSITE=1 so CI keeps exercising the dependency-light path instead of accidentally relying on a developer machine.
Constraint: PR #19 must keep npm run ci green on GitHub Actions without assuming user-level Python packages
Constraint: The KTX helper still needs the real korail2 and pycryptodome packages for live reservation flows
Rejected: Installing ad-hoc Python packages in the CI workflow | hides the import-safety regression instead of fixing the helper/test contract
Rejected: Removing the Python regression suite from skill-docs coverage | would lose the guard on the train_id reservation flow
Confidence: high
Scope-risk: narrow
Reversibility: clean
Directive: Keep the KTX helper importable under PYTHONNOUSERSITE=1 and document every required runtime package in both the skill and install docs
Tested: PYTHONNOUSERSITE=1 python3 -m unittest discover -s scripts -p test_ktx_booking.py
Tested: node --test scripts/skill-docs.test.js
Tested: npm run ci
Not-tested: GitHub Actions validate rerun after push
Reserve used to replay search results and trust a fresh ordinal index, which could silently target a different train when sold-out entries disappeared or ordering changed. This change emits a stable train_id from search output, requires reserve to match the exact train identity on replay, and updates docs/tests to lock the safer CLI contract.
Constraint: Korail search results can reorder between search and reserve while the helper still needs to replay the live lookup
Rejected: Keep --train-index as the reserve selector | still allows silent wrong-train bookings when the result set shifts
Confidence: high
Scope-risk: narrow
Reversibility: clean
Directive: If upstream train identity fields change, update the train_id payload and the docs/tests together before changing reserve selection again
Tested: python3 -m py_compile scripts/ktx_booking.py; python3 -m unittest discover -s scripts -p test_ktx_booking.py; node --test scripts/skill-docs.test.js; npm run ci; live search/reservations/reserve/cancel/reservations with sops-managed Korail credentials
Not-tested: Forced live stale-train_id failure against a disappearing train between search and reserve
The feature branch already restored the patched Korail helper, so this follow-up stays narrow: lock the documented helper flags in regression tests and teach both KTX docs surfaces about the search and waiting-list toggles the live CLI already supports.
Constraint: Follow-up had to stay compatible with the shipped scripts/ktx_booking.py parser and existing PR scope
Rejected: Expand README into a full command matrix | duplicates the dedicated KTX docs and skill guide
Confidence: high
Scope-risk: narrow
Directive: When the helper CLI changes, update both KTX docs surfaces and the regression assertions in the same change
Tested: node --test scripts/skill-docs.test.js
Tested: python3 -m py_compile scripts/ktx_booking.py
Tested: npm run ci
Tested: live python3 scripts/ktx_booking.py search/reservations/reserve/cancel via sops-managed Korail credentials
Not-tested: 예약대기 success path on a sold-out train
Korail's current mobile endpoints reject the published raw korail2
examples with MACRO ERROR, so this change adds a repo-local
helper that patches Dynapath token/Sid/version behavior and reroutes
KTX docs/tests to the helper-based flow.
Constraint: Must keep credentials in sops-managed secrets and prove the flow with a real reservation
Rejected: Fork and publish a patched korail2 package | broader release surface than this repo needs
Confidence: high
Scope-risk: moderate
Directive: Re-check the helper constants and private korail2 hooks whenever Korail changes its mobile anti-bot flow
Tested: python3 -m py_compile scripts/ktx_booking.py
Tested: npm run ci
Tested: Live search via scripts/ktx_booking.py search 서울 부산 20260328 000000 --include-no-seats --include-waiting-list
Tested: Live reserve/cancel via scripts/ktx_booking.py reserve/cancel/reservations on March 28, 2026 KTX #001
Not-tested: Final payment completion after reservation
This snapshots the current repository updates as a coherent release-prep
baseline: workspace/package scaffolding, release automation docs and
workflows, refreshed skill/setup documentation, roadmap expansion, and
the README thumbnail polish.
Constraint: Node packages in this repo must use npm workspaces and Changesets for releases
Constraint: Python release automation stays scaffold-only until a real package exists
Rejected: Split the current work into multiple commits | user asked to commit the current changes together
Confidence: medium
Scope-risk: moderate
Reversibility: clean
Directive: Keep release docs, workflows, and package metadata aligned when adding future packages
Tested: npm run ci
Not-tested: GitHub Actions execution on remote after push
The train skills no longer share a generic wrapper. SRT now documents the dedicated SRTrain surface, and KTX now documents korail2 directly, which makes the install path, imports, and reservation examples match the libraries the user explicitly validated.
Constraint: SRT and KTX should stay separate skills with their own native library surfaces
Rejected: Keep the shared koreantrain abstraction | it hides the real backend and weakens trust in the examples
Confidence: high
Scope-risk: narrow
Reversibility: clean
Directive: Keep future train-skill examples aligned with the concrete upstream library each skill depends on
Tested: bash scripts/validate-skills.sh
Tested: Import and signature inspection for SRTrain and korail2 from temporary installs
Not-tested: Live login and booking against SRT and Korail services
Credential-bearing skills now point to a shared cross-platform setup based on sops plus age instead of a hosted password manager. The repo also gains a default setup skill and a small verification script so users can bring one encrypted secrets file to every relevant skill.
Constraint: The secret workflow must work on macOS, Linux, and Windows without mandatory vendor signup
Rejected: Keep 1Password CLI as the default | it requires account creation and sign-in
Rejected: Plaintext .env as the default | too easy to leak in a repo and too easy for tools to read at rest
Confidence: high
Scope-risk: moderate
Reversibility: clean
Directive: If a future skill needs stronger isolation than exec-env provides, expose a capability wrapper instead of injecting the raw secret
Tested: bash scripts/validate-skills.sh
Tested: npx --yes skills add . --list
Tested: bash scripts/check-setup.sh (expected failure without sops/age installed)
Not-tested: End-to-end sops encryption and exec-env flow on a machine with sops and age installed
SRT and KTX were the highest-signal v1 skills because existing Python tooling already exposes search and reservation flows. The skills intentionally split search from reservation so the agent can summarize choices before performing side effects.
Constraint: Booking actions are side-effectful and must not run on ambiguous train choices
Rejected: Merge SRT and KTX into one generic train skill | separate entry points are easier to discover and install
Confidence: medium
Scope-risk: moderate
Reversibility: clean
Directive: Keep reserve and cancel steps gated on an identified train or reservation target
Tested: bash scripts/validate-skills.sh
Not-tested: Live login and reservation against SRT/Korail services
