feat(12306): add full read adapter (stations / trains / train / price / me / passengers / orders)

[Benjamin-eecs]

Description

Closes #1589 with the full 12306 (中国铁路) adapter the issue proposes. Seven commands across two strategies:

Strategy	Command	What
PUBLIC (no login)	12306 stations <keyword>	Search station bundle by Chinese name, telecode, full pinyin, or short alias
PUBLIC	12306 trains <from> <to> --date YYYY-MM-DD	Trains between two stations on a given date with per-seat-class availability
PUBLIC	12306 train <train-no> --from --to --date	Full stop list for one train segment
PUBLIC	12306 price <train-no> --from --to --date	Ticket prices keyed by seat class for one segment
COOKIE (login)	12306 me	Account summary, sensitive fields masked by default
COOKIE	12306 passengers	Saved-passenger list, sensitive fields masked
COOKIE	12306 orders	In-progress orders (not yet ridden / refunded / completed)

No CAPTCHA / slider / SMS bypass, no credential storage, no ticket sniping, no order submission, no payment - per the issue's Non-goals list.

Type of Change

• 🐛 Bug fix
• ✨ New feature
• 🌐 New site adapter
• 📝 Documentation
• ♻️ Refactor
• 🔧 CI / build / tooling

Checklist

• I ran the checks relevant to this PR
• I updated tests or docs if needed
• I included output or screenshots when useful

Implementation notes worth flagging

Anonymous session minting

12306 rejects bare anonymous query endpoints with HTTP 302 -> /mormhweb/logFiles/error.html. The adapter first hits /otn/leftTicket/init to mint JSESSIONID / route / BIGipServerotn cookies, then attaches them to subsequent queries. No CAPTCHA / slider path is invoked. Cookies are not persisted to disk; they live only for the lifetime of the command invocation.

Endpoint name rotation (queryO / queryZ / queryA / queryG / ...)

12306 rotates the train-query endpoint name every few weeks. When the wrong name is hit the server returns {"c_url": "leftTicket/queryG", "c_name": "CLeftTicketUrl", "status": false} pointing to the current correct name. trains walks a list of known names, captures the rotation hint, retries against the suggested name, and mutates the runtime list so subsequent calls in the same process skip the warm-up round trip.

Login detection via document.cookie, not page.getCookies({url})

12306 sets the auth cookie tk and the session cookie JSESSIONID with Path=/otn. CDP Network.getCookies filters by URL path: even with the page navigated to https://kyfw.12306.cn/otn/view/index.html and the user fully logged in, page.getCookies({ url: 'https://kyfw.12306.cn' }) returns 7 cookies without tk / JSESSIONID, because that URL has path /, not /otn. Switched the login check to read document.cookie via page.evaluate, which exposes the navigated page's full visible-cookie set regardless of path. Centralized as require12306Login in utils.js so all three authenticated commands share the same check (and so future maintainers know not to "fix" it back to page.getCookies).

Booking-handshake secret field is stripped

The |-separated train wire record carries a base64 secret token at position 0 used to construct booking handshakes. Since this PR is read-only and the issue rules out booking, parseTrainRecord parses but does not surface that field, and a regression unit test asserts it cannot leak via the adapter contract:

it('does not expose the booking-handshake secret token', () => {
    const row = parseTrainRecord(fields.join('|'), stationByCode);
    expect(Object.values(row)).not.toContain('SECRET_TOKEN_DO_NOT_LEAK');
    expect('secret' in row).toBe(false);
});

Sensitive-field masking on authenticated commands

• me: real name (Chinese mask, e.g. 张*), email (e.g. xxx@xxx.xxx), mobile (12306 already masks server-side and the adapter preserves that, e.g. xxx-xxx-xxxx), birth date (year only).
• passengers: passenger name (Chinese mask) + birth year (year only); 12306 already masks ID number (e.g. xxxxxxxxxxxxxxxxxxx) and mobile server-side and this adapter never decodes those.
• Both expose --include-sensitive to opt back into the unmasked fields the user is entitled to see on their own account.

orders scope

Returns the queryMyOrderNoComplete slice (orders that have not yet been ridden / refunded / completed). The historical queryMyOrderApi endpoint requires extra page-state handshakes that proved fragile when probed - the server returned 302s into the error landing page under repeated anonymous calls. Left as a follow-up so this command can ship reliably for the immediate "what's still on my account" use case.

price cascading

Cascades three anonymous API calls per invocation: init -> queryByTrainNo (to resolve segment station_no within the train route - the price endpoint addresses stops by station_no, not telecode) -> queryTicketPrice. 12306 returns prices keyed by one-or-two-letter seat codes (A9 商务座 / M 一等座 / O 二等座 / WZ 无座 / etc.) and additionally doubles some up as bare numeric codes (e.g. "9": "21580" mirrors "A9": "¥2158.0"); the bare-numeric duplicates are filtered out so the row set is one-per-seat-class.

Station resolution

resolveStation matches Chinese name (上海虹桥), telecode (AOH), full pinyin (shanghaihongqiao), and short alias (shhq). Anything else raises ArgumentError with a hint. Match order is exact-name first to prevent 北京 matching 北京北 by substring.

Strict limit validation

limit arguments use a small inline validator that throws ArgumentError on non-integer / out-of-range input rather than silently clamping. Mirrors the typed-error pattern owner used in #1397 (grok) and #1370 (coupang).

Screenshots / Output

Live verified anonymously and authenticated against kyfw.12306.cn, sleeping 15-25 seconds between hits to keep 12306's anti-abuse throttle gentle. All commands run via node ./dist/src/main.js from this branch's worktree so the local clis/12306/ adapters in this PR are loaded.

Anonymous commands (real API output)

$ node ./dist/src/main.js 12306 stations 上海 --limit 5 -f json
[
  { "name": "练塘",     "code": "LTU", "pinyin": "liantang",         "abbr": "lt",   "city": "上海" },
  { "name": "上海",     "code": "SHH", "pinyin": "shanghai",         "abbr": "sh",   "city": "上海" },
  { "name": "上海南",   "code": "SNH", "pinyin": "shanghainan",      "abbr": "shn",  "city": "上海" },
  { "name": "上海虹桥", "code": "AOH", "pinyin": "shanghaihongqiao", "abbr": "shhq", "city": "上海" },
  { "name": "上海西",   "code": "SXH", "pinyin": "shanghaixi",       "abbr": "shx",  "city": "上海" }
]

$ node ./dist/src/main.js 12306 trains 北京 上海 --date 2026-05-22 --limit 1 -f json
[
  {
    "train_no": "240000G54700", "code": "G547",
    "from_station": "北京南", "to_station": "上海虹桥",
    "from_code": "VNP", "to_code": "AOH",
    "start_time": "06:18", "arrive_time": "12:11", "duration": "05:53",
    "available": true,
    "business_seat": "无", "first_seat": "有", "second_seat": "有",
    "soft_sleeper": "", "hard_sleeper": "", "hard_seat": "", "no_seat": "无"
  }
]

$ node ./dist/src/main.js 12306 train 24000000G10L --from 北京南 --to 上海虹桥 --date 2026-05-22 -f json
[
  { "station_no": "01", "station_name": "北京南",   "arrive_time": "",      "start_time": "06:30", "stopover_time": ""      },
  { "station_no": "02", "station_name": "沧州西",   "arrive_time": "07:18", "start_time": "07:20", "stopover_time": "2分钟" },
  { "station_no": "03", "station_name": "德州东",   "arrive_time": "07:45", "start_time": "07:47", "stopover_time": "2分钟" },
  { "station_no": "04", "station_name": "曲阜东",   "arrive_time": "08:34", "start_time": "08:36", "stopover_time": "2分钟" },
  { "station_no": "05", "station_name": "南京南",   "arrive_time": "10:13", "start_time": "10:15", "stopover_time": "2分钟" },
  { "station_no": "06", "station_name": "苏州北",   "arrive_time": "10:59", "start_time": "11:01", "stopover_time": "2分钟" },
  { "station_no": "07", "station_name": "上海虹桥", "arrive_time": "11:24", "start_time": "11:24", "stopover_time": ""      }
]

$ node ./dist/src/main.js 12306 price 24000000G10L --from 北京南 --to 上海虹桥 --date 2026-05-22 -f json
[
  { "seat_code": "A9", "seat_name": "商务座", "price": "2158.0", "currency": "CNY" },
  { "seat_code": "P",  "seat_name": "特等座", "price": "1163.0", "currency": "CNY" },
  { "seat_code": "M",  "seat_name": "一等座", "price": "1035.0", "currency": "CNY" },
  { "seat_code": "WZ", "seat_name": "无座",   "price": "626.0",  "currency": "CNY" },
  { "seat_code": "O",  "seat_name": "二等座", "price": "626.0",  "currency": "CNY" }
]

Authenticated commands (shape-only; real values redacted for this PR body)

The three authenticated commands were exercised live on a Mac mini against a logged-in 12306 account. Output shape below uses synthetic placeholder values; the real PII (12306 username, family name, partial ID prefix, partial mobile, email) is not posted here. The actual run was verified locally and the masking logic was tested against the real response (see "Sensitive-field masking" above).

$ node ./dist/src/main.js 12306 me -f json
[
  {
    "username":   "<account>",
    "real_name":  "<masked>",
    "email":      "<x***x>@<domain>",
    "mobile":     "<3-digits>****<4-digits>",
    "birth_date": "<YYYY>",
    "sex":        "<男|女>",
    "country":    "CHN",
    "user_type":  "成人",
    "member":     false,
    "active":     <bool>
  }
]

$ node ./dist/src/main.js 12306 passengers -f json
[
  {
    "name":           "<surname>*<...>",
    "sex":            "<男|女>",
    "born_year":      "<YYYY>",
    "id_type":        "居民身份证",
    "id_no":          "<4-digits>***********<3-digits>",
    "mobile":         "<3-digits>****<4-digits>",
    "passenger_type": "成人",
    "country":        "CHN"
  },
  ...
]

12306 orders was also exercised live; the account currently has no in-progress orders, so the command correctly surfaces EMPTY_RESULT: No in-progress 12306 orders on this account rather than fabricating an empty array.

If you want a non-redacted copy of the authenticated-command output to confirm masking behaviour, ping me on the PR and I'll DM the raw output.

Test plan

• npm run build: manifest compiles, 828 entries, git diff cli-manifest.json contains only new 12306 entries (no absolute filesystem paths)
• npm run check:typed-error-lint: passes (current=173, baseline=173, new=0, resolved=0)
• npm run check:silent-column-drop: passes (current=102, baseline=102, new=0, resolved=0)
• npx vitest run --project adapter clis/12306/utils.test.js: 23 tests passing across
  • parseStationBundle: structured-record extraction + skip records without telecode
  • resolveStation: name / telecode / pinyin / short-alias matches + empty / unknown / unknown-but-telecode-shaped failure modes
  • validateDate: format check + impossible calendar dates
  • buildCookieHeader: join Set-Cookie lines
  • parseTrainRecord: full-shape extraction, secret-field non-leak regression, telecode fallback when bundle is missing, short-record null
  • mask helpers: maskEmail (3+ char local-part + edge cases), maskMobile (preserves 12306's own mask), maskChineseName (1 / 2 / 3+ char names)
  • parsePriceData: bare-numeric-duplicate filter, sort by descending price, unknown letter codes fall back to letter as name
• Live anonymous: stations / trains / train / price against kyfw.12306.cn from a Mac mini session with 15-25 s sleeps between hits
• Live authenticated: me / passengers / orders after the user logged in to 12306 in the OpenCLI bridge Chrome on Mac mini; cookies surfaced via document.cookie correctly (see require12306Login note above)
• Reviewer to confirm masking defaults match the project's expectation. The current defaults: real name -> Chinese-mask, email -> local-part mask, mobile -> preserve 12306's own mask, birth date -> year only. --include-sensitive opts in to the unmasked-by-12306 fields.

Out of scope

• Order history (queryMyOrderApi): needs extra page-state handshakes; left as a follow-up so the immediate "in-progress orders" path can ship without flakiness.
• Ticket sniping / order submission / payment / CAPTCHA bypass / password storage: explicitly out of scope per the issue's Non-goals.

[Copilot]

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.