@jackwener/opencli 1.7.21 → 1.8.0

package/clis/12306/me.js

@@ -0,0 +1,73 @@
+/**
+ * 12306 account summary for the logged-in user.
+ *
+ * Returns non-sensitive identity fields plus masked email / mobile.
+ * Use `--include-sensitive` to surface unmasked values from 12306's
+ * own response (12306 already masks the ID number server-side; this
+ * adapter never decodes that mask).
+ */
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import { AuthRequiredError, CommandExecutionError } from '@jackwener/opencli/errors';
+import { isAuthLikePayload, maskEmail, maskMobile, maskChineseName, require12306Login, requireEvaluateObject } from './utils.js';
+
+const ACCOUNT_INFO_URL = 'https://kyfw.12306.cn/otn/modifyUser/initQueryUserInfoApi';
+
+cli({
+    site: '12306',
+    name: 'me',
+    access: 'read',
+    description: 'Show the logged-in 12306 account summary. Sensitive fields (real name, email, mobile, birth date) are masked by default; pass --include-sensitive to opt in.',
+    domain: 'kyfw.12306.cn',
+    strategy: Strategy.COOKIE,
+    browser: true,
+    args: [
+        { name: 'include-sensitive', type: 'boolean', default: false, help: 'Reveal unmasked real name / email / mobile / birth date. The 12306 ID-number mask is server-side and never decoded.' },
+    ],
+    columns: ['username', 'real_name', 'email', 'mobile', 'birth_date', 'sex', 'country', 'user_type', 'member', 'active'],
+    func: async (page, kwargs) => {
+        if (!page) throw new CommandExecutionError('Browser session required for 12306 me');
+        await page.goto('https://kyfw.12306.cn/otn/view/index.html');
+        await require12306Login(page, AuthRequiredError);
+        const json = requireEvaluateObject(await page.evaluate(`async () => {
+      const r = await fetch(${JSON.stringify(ACCOUNT_INFO_URL)}, { credentials: 'include' });
+      if (!r.ok) return { __http: r.status };
+      try {
+        return await r.json();
+      } catch (err) {
+        return { __parse: String(err && err.message || err) };
+      }
+    }`), 'account info');
+        if (json?.__http) {
+            if ([401, 403].includes(Number(json.__http))) {
+                throw new AuthRequiredError('kyfw.12306.cn', '12306 account info requires a valid login session');
+            }
+            throw new CommandExecutionError(`12306 returned HTTP ${json.__http} for account info`);
+        }
+        if (json?.__parse) {
+            throw new CommandExecutionError(`12306 account info returned non-JSON body: ${json.__parse}`);
+        }
+        if (isAuthLikePayload(json)) {
+            throw new AuthRequiredError('kyfw.12306.cn', '12306 account info requires a valid login session');
+        }
+        if (json?.status !== true || !json?.data?.userDTO) {
+            throw new CommandExecutionError('12306 account info payload missing userDTO');
+        }
+        const dto = json.data.userDTO;
+        const loginDto = dto.loginUserDTO || {};
+        const username = loginDto.user_name || loginDto.name || '';
+        const realName = loginDto.real_name || loginDto.realname || '';
+        const include = kwargs['include-sensitive'] === true;
+        return [{
+            username,
+            real_name: include ? realName : maskChineseName(realName),
+            email: include ? (dto.email || '') : maskEmail(dto.email || ''),
+            mobile: include ? (dto.mobile_no || '') : maskMobile(dto.mobile_no || ''),
+            birth_date: include ? (dto.born_date || '') : (dto.born_date || '').slice(0, 4),
+            sex: dto.sex_code === 'M' ? '男' : (dto.sex_code === 'F' ? '女' : ''),
+            country: dto.country_code || '',
+            user_type: json.data.userTypeName || '',
+            member: dto.flag_member === '1',
+            active: dto.is_active === '1',
+        }];
+    },
+});

package/clis/12306/orders.js

@@ -0,0 +1,96 @@
+/**
+ * 12306 in-progress orders for the logged-in user.
+ *
+ * Returns orders that have not yet been ridden / refunded / completed
+ * (the `noComplete` slice). Order history covering completed and
+ * refunded tickets uses a separate endpoint that requires extra
+ * referer / page-state handshakes and is left for a follow-up so this
+ * command can ship reliably.
+ */
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import { AuthRequiredError, CommandExecutionError, EmptyResultError } from '@jackwener/opencli/errors';
+import { isAuthLikePayload, maskChineseName, require12306Login, requireEvaluateObject } from './utils.js';
+
+const NO_COMPLETE_URL = 'https://kyfw.12306.cn/otn/queryOrder/queryMyOrderNoComplete';
+
+cli({
+    site: '12306',
+    name: 'orders',
+    access: 'read',
+    description: 'List in-progress 12306 orders (not yet ridden, refunded, or completed) for the logged-in user',
+    domain: 'kyfw.12306.cn',
+    strategy: Strategy.COOKIE,
+    browser: true,
+    args: [
+        { name: 'include-sensitive', type: 'boolean', default: false, help: 'Reveal unmasked passenger names in order rows. Masked by default.' },
+    ],
+    columns: ['order_id', 'order_date', 'train_code', 'from_station', 'to_station', 'departure', 'passengers', 'status', 'amount'],
+    func: async (page, kwargs) => {
+        if (!page) throw new CommandExecutionError('Browser session required for 12306 orders');
+        await page.goto('https://kyfw.12306.cn/otn/view/index.html');
+        await require12306Login(page, AuthRequiredError);
+        const include = kwargs['include-sensitive'] === true;
+        const json = requireEvaluateObject(await page.evaluate(`async () => {
+      const r = await fetch(${JSON.stringify(NO_COMPLETE_URL)}, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+        body: '_json_att=', credentials: 'include',
+      });
+      if (!r.ok) return { __http: r.status };
+      try {
+        return await r.json();
+      } catch (err) {
+        return { __parse: String(err && err.message || err) };
+      }
+    }`), 'orders');
+        if (json?.__http) {
+            if ([401, 403].includes(Number(json.__http))) {
+                throw new AuthRequiredError('kyfw.12306.cn', '12306 orders requires a valid login session');
+            }
+            throw new CommandExecutionError(`12306 returned HTTP ${json.__http} for queryMyOrderNoComplete`);
+        }
+        if (json?.__parse) {
+            throw new CommandExecutionError(`12306 orders returned non-JSON body: ${json.__parse}`);
+        }
+        if (isAuthLikePayload(json)) {
+            throw new AuthRequiredError('kyfw.12306.cn', '12306 orders requires a valid login session');
+        }
+        if (json?.status !== true) {
+            throw new CommandExecutionError('12306 queryMyOrderNoComplete returned a failure status');
+        }
+        let orders;
+        if (Array.isArray(json?.data?.orderDBList)) {
+            orders = json.data.orderDBList;
+        } else if (Array.isArray(json?.data?.orderDTODataList)) {
+            orders = json.data.orderDTODataList;
+        } else if (Array.isArray(json?.data?.orders)) {
+            orders = json.data.orders;
+        } else if (Array.isArray(json?.data)) {
+            orders = json.data;
+        } else {
+            throw new CommandExecutionError('12306 queryMyOrderNoComplete payload missing order list array');
+        }
+        if (orders.length === 0) {
+            throw new EmptyResultError('No in-progress 12306 orders on this account');
+        }
+        return orders.map((o) => {
+            const tickets = Array.isArray(o.tickets) ? o.tickets : [];
+            const passengerNames = tickets
+                .map((t) => t.passenger_name || '')
+                .filter(Boolean)
+                .map((name) => include ? name : maskChineseName(name))
+                .join(', ');
+            return {
+                order_id: o.sequence_no || o.order_id || o.sequenceNo || '',
+                order_date: o.order_date || '',
+                train_code: o.train_code_page || o.station_train_code || o.train_code || '',
+                from_station: o.from_station_name_page || o.from_station_name || '',
+                to_station: o.to_station_name_page || o.to_station_name || '',
+                departure: o.start_train_date_page || o.start_train_date || '',
+                passengers: passengerNames,
+                status: o.ticket_status_name || o.order_status_name || o.statusName || '',
+                amount: o.ticket_total_price_page || o.ticket_total_price || '',
+            };
+        });
+    },
+});

package/clis/12306/passengers.js

@@ -0,0 +1,90 @@
+/**
+ * 12306 saved passenger list for the logged-in user.
+ *
+ * 12306 already masks ID numbers (`xxxx***********xxx`) and mobile
+ * numbers (`138****xxxx`) server-side. This adapter further masks the
+ * passenger's Chinese real name and birth date by default; pass
+ * `--include-sensitive` to surface the unmasked-by-12306 fields.
+ */
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import { ArgumentError, AuthRequiredError, CommandExecutionError, EmptyResultError } from '@jackwener/opencli/errors';
+import { isAuthLikePayload, maskChineseName, require12306Login, requireEvaluateObject } from './utils.js';
+
+const PASSENGER_QUERY_URL = 'https://kyfw.12306.cn/otn/passengers/query';
+const MAX_PAGE_SIZE = 50;
+
+function normalizeLimit(value, defaultValue, max) {
+    if (value === undefined || value === null || value === '') return defaultValue;
+    const n = Number(value);
+    if (!Number.isInteger(n) || n < 1) throw new ArgumentError(`limit must be a positive integer (1-${max})`);
+    if (n > max) throw new ArgumentError(`limit must be <= ${max}`);
+    return n;
+}
+
+cli({
+    site: '12306',
+    name: 'passengers',
+    access: 'read',
+    description: 'List the logged-in user\'s saved 12306 passengers. Sensitive fields are masked by default; pass --include-sensitive to opt in.',
+    domain: 'kyfw.12306.cn',
+    strategy: Strategy.COOKIE,
+    browser: true,
+    args: [
+        { name: 'limit', type: 'int', default: 20, help: `Max passengers to return (1-${MAX_PAGE_SIZE})` },
+        { name: 'include-sensitive', type: 'boolean', default: false, help: 'Reveal unmasked real names and birth dates. The 12306 ID-number / mobile masks are server-side and never decoded.' },
+    ],
+    columns: ['name', 'sex', 'born_year', 'id_type', 'id_no', 'mobile', 'passenger_type', 'country'],
+    func: async (page, kwargs) => {
+        if (!page) throw new CommandExecutionError('Browser session required for 12306 passengers');
+        const limit = normalizeLimit(kwargs.limit, 20, MAX_PAGE_SIZE);
+        const include = kwargs['include-sensitive'] === true;
+
+        await page.goto('https://kyfw.12306.cn/otn/view/index.html');
+        await require12306Login(page, AuthRequiredError);
+        const json = requireEvaluateObject(await page.evaluate(`async () => {
+      const body = "pageIndex=1&pageSize=${MAX_PAGE_SIZE}";
+      const r = await fetch(${JSON.stringify(PASSENGER_QUERY_URL)}, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+        body, credentials: 'include',
+      });
+      if (!r.ok) return { __http: r.status };
+      try {
+        return await r.json();
+      } catch (err) {
+        return { __parse: String(err && err.message || err) };
+      }
+    }`), 'passengers');
+        if (json?.__http) {
+            if ([401, 403].includes(Number(json.__http))) {
+                throw new AuthRequiredError('kyfw.12306.cn', '12306 passengers requires a valid login session');
+            }
+            throw new CommandExecutionError(`12306 returned HTTP ${json.__http} for passengers/query`);
+        }
+        if (json?.__parse) {
+            throw new CommandExecutionError(`12306 passengers returned non-JSON body: ${json.__parse}`);
+        }
+        if (isAuthLikePayload(json)) {
+            throw new AuthRequiredError('kyfw.12306.cn', '12306 passengers requires a valid login session');
+        }
+        if (json?.status !== true || !Array.isArray(json?.data?.datas)) {
+            throw new CommandExecutionError('12306 passengers payload missing data.datas array');
+        }
+        const datas = json.data.datas;
+        if (datas.length === 0) {
+            throw new EmptyResultError('No saved passengers on this 12306 account');
+        }
+        return datas.slice(0, limit).map((p) => ({
+            name: include ? (p.passenger_name || '') : maskChineseName(p.passenger_name || ''),
+            sex: p.sex_name || '',
+            born_year: (p.born_date || '').slice(0, 4),
+            id_type: p.passenger_id_type_name || '',
+            id_no: p.passenger_id_no || '',
+            mobile: p.mobile_no || '',
+            passenger_type: p.passenger_type_name || '',
+            country: p.country_code || '',
+        }));
+    },
+});
+
+export const __test__ = { normalizeLimit };

package/clis/12306/price.js

@@ -0,0 +1,166 @@
+/**
+ * 12306 ticket price lookup for a single train + segment.
+ *
+ * Cascades three anonymous API calls:
+ *   1. /otn/leftTicket/init: mint session cookies
+ *   2. /otn/czxx/queryByTrainNo: resolve from/to station_no within the
+ *      train route (price endpoint addresses stops by station_no, not
+ *      telecode)
+ *   3. /otn/leftTicket/queryTicketPrice: ticket prices keyed by seat
+ *      letter (M=一等座, O=二等座, A9=商务座, A1=硬座, A3=硬卧,
+ *      A4=软卧, F=动卧, P=特等座, WZ=无座, etc.)
+ */
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import { ArgumentError, CommandExecutionError, EmptyResultError } from '@jackwener/opencli/errors';
+import { fetchStationBundle, mintSession, resolveStation, validateDate } from './utils.js';
+
+const UA = 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/127.0 Safari/537.36';
+const TRAIN_NO_RE = /^[0-9A-Z]{8,18}$/;
+const SEAT_TYPES_RE = /^[A-Z0-9]{1,32}$/;
+
+const SEAT_LETTERS = {
+    'A9': '商务座',
+    'P': '特等座',
+    'M': '一等座',
+    'O': '二等座',
+    'A1': '硬座',
+    'A3': '硬卧',
+    'A4': '软卧',
+    'F': '动卧',
+    'WZ': '无座',
+};
+
+async function queryStopsForPrice(cookieHeader, trainNo, fromCode, toCode, date, fetchImpl = fetch) {
+    const url = `https://kyfw.12306.cn/otn/czxx/queryByTrainNo?train_no=${trainNo}&from_station_telecode=${fromCode}&to_station_telecode=${toCode}&depart_date=${date}`;
+    const resp = await fetchImpl(url, {
+        headers: {
+            'User-Agent': UA,
+            'Referer': 'https://kyfw.12306.cn/otn/leftTicket/init',
+            'Cookie': cookieHeader,
+        },
+    });
+    if (!resp.ok) throw new CommandExecutionError(`12306 queryByTrainNo returned HTTP ${resp.status}`);
+    let json;
+    try {
+        json = await resp.json();
+    } catch {
+        throw new CommandExecutionError('12306 queryByTrainNo returned non-JSON body');
+    }
+    if (json?.status !== true || !Array.isArray(json?.data?.data)) {
+        throw new CommandExecutionError('12306 queryByTrainNo returned an unexpected payload shape');
+    }
+    return json.data.data;
+}
+
+function pickStationNos(stops, fromCode, toCode, fromName, toName) {
+    const matches = (s, code, name) => (s.station_name && name && s.station_name === name);
+    const fromStop = stops.find((s) => matches(s, fromCode, fromName));
+    const toStop = stops.find((s) => matches(s, toCode, toName));
+    if (!fromStop) throw new CommandExecutionError(`Train does not stop at ${fromName}`);
+    if (!toStop) throw new CommandExecutionError(`Train does not stop at ${toName}`);
+    return { fromNo: fromStop.station_no, toNo: toStop.station_no };
+}
+
+async function queryPrice(cookieHeader, trainNo, fromNo, toNo, seatTypes, date, fetchImpl = fetch) {
+    const url = `https://kyfw.12306.cn/otn/leftTicket/queryTicketPrice?train_no=${trainNo}&from_station_no=${fromNo}&to_station_no=${toNo}&seat_types=${seatTypes}&train_date=${date}`;
+    const resp = await fetchImpl(url, {
+        headers: {
+            'User-Agent': UA,
+            'Referer': 'https://kyfw.12306.cn/otn/leftTicket/init',
+            'Cookie': cookieHeader,
+        },
+    });
+    if (!resp.ok) throw new CommandExecutionError(`12306 queryTicketPrice returned HTTP ${resp.status}`);
+    let json;
+    try {
+        json = await resp.json();
+    } catch {
+        throw new CommandExecutionError('12306 queryTicketPrice returned non-JSON body');
+    }
+    if (json?.status !== true || !json?.data) {
+        throw new CommandExecutionError('12306 queryTicketPrice returned an unexpected payload shape');
+    }
+    return json.data;
+}
+
+function parsePriceData(priceData) {
+    const rows = [];
+    for (const [letter, value] of Object.entries(priceData)) {
+        if (letter === 'train_no' || letter === 'OT') continue;
+        if (typeof value !== 'string' || !value) continue;
+        // 12306 doubles up some prices as bare numerics ("9": "21580"), which
+        // mirror their letter sibling ("A9": "¥2158.0") in cents/no-decimal
+        // form. Skip the bare numeric letter codes to avoid duplicates.
+        if (/^\d+$/.test(letter)) continue;
+        if (!/^[A-Z]/.test(letter)) continue;
+        const numeric = value.replace(/^¥/, '');
+        if (!/^[\d.]+$/.test(numeric)) continue;
+        rows.push({
+            seat_code: letter,
+            seat_name: SEAT_LETTERS[letter] || letter,
+            price: numeric,
+            currency: 'CNY',
+        });
+    }
+    rows.sort((a, b) => Number(b.price) - Number(a.price));
+    return rows;
+}
+
+cli({
+    site: '12306',
+    name: 'price',
+    access: 'read',
+    description: 'Look up 12306 ticket prices by seat class for one train on a given date and segment (anonymous, no login required)',
+    domain: 'kyfw.12306.cn',
+    strategy: Strategy.PUBLIC,
+    browser: false,
+    args: [
+        { name: 'train-no', positional: true, required: true, help: 'Internal train_no from `12306 trains` (e.g. 24000000G10L)' },
+        { name: 'from', required: true, help: 'Origin station (Chinese name, telecode, or pinyin) - must be a stop of this train' },
+        { name: 'to', required: true, help: 'Destination station - must be a stop of this train' },
+        { name: 'date', required: true, help: 'Departure date in YYYY-MM-DD' },
+        { name: 'seat-types', default: 'OM9PA1A3A4FWZ', help: 'Seat-type letters to query (default covers the common classes). Examples: OM9 (二等/一等/商务), A1A3A4 (硬座/硬卧/软卧).' },
+    ],
+    columns: ['seat_code', 'seat_name', 'price', 'currency'],
+    func: async (kwargs) => {
+        const trainNo = String(kwargs['train-no'] ?? '').trim();
+        if (!trainNo) throw new ArgumentError('<train-no> must not be empty');
+        if (!TRAIN_NO_RE.test(trainNo)) {
+            throw new ArgumentError(
+                `<train-no> "${trainNo}" does not look like a 12306 internal train_no`,
+                'Use the train_no field from `12306 trains` output (e.g. 24000000G10L), not the public code (G1).',
+            );
+        }
+        const fromArg = String(kwargs.from ?? '').trim();
+        const toArg = String(kwargs.to ?? '').trim();
+        if (!fromArg) throw new ArgumentError('--from station must not be empty');
+        if (!toArg) throw new ArgumentError('--to station must not be empty');
+        const date = validateDate(kwargs.date);
+        const seatTypes = String(kwargs['seat-types'] ?? '').trim() || 'OM9PA1A3A4FWZ';
+        if (!SEAT_TYPES_RE.test(seatTypes)) {
+            throw new ArgumentError('--seat-types must contain only 12306 seat letters/digits (A-Z, 0-9)');
+        }
+
+        const stations = await fetchStationBundle();
+        const fromStation = resolveStation(stations, fromArg);
+        const toStation = resolveStation(stations, toArg);
+        if (fromStation.code === toStation.code) {
+            throw new ArgumentError(`--from and --to must differ; both resolved to ${fromStation.name} (${fromStation.code})`);
+        }
+
+        const cookieHeader = await mintSession();
+        const stops = await queryStopsForPrice(cookieHeader, trainNo, fromStation.code, toStation.code, date);
+        const { fromNo, toNo } = pickStationNos(stops, fromStation.code, toStation.code, fromStation.name, toStation.name);
+        const priceData = await queryPrice(cookieHeader, trainNo, fromNo, toNo, seatTypes, date);
+        const rows = parsePriceData(priceData);
+        if (rows.length === 0) {
+            throw new EmptyResultError(
+                `No prices returned for train_no=${trainNo} ${fromStation.name} -> ${toStation.name} on ${date}`,
+                'Try a different seat-types letter set, or check that this train operates on the date.',
+            );
+        }
+        return rows;
+    },
+});
+
+export const __test__ = { parsePriceData, pickStationNos, queryStopsForPrice, queryPrice, SEAT_LETTERS };

package/clis/12306/stations.js

@@ -0,0 +1,66 @@
+/**
+ * 12306 station search.
+ *
+ * Queries the public `station_name.js` bundle and filters by the user's
+ * keyword. Anonymous, no session needed.
+ */
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import { ArgumentError, EmptyResultError } from '@jackwener/opencli/errors';
+import { fetchStationBundle } from './utils.js';
+
+const MAX_LIMIT = 50;
+
+function normalizeLimit(value, defaultValue, max) {
+    if (value === undefined || value === null || value === '') return defaultValue;
+    const n = Number(value);
+    if (!Number.isInteger(n) || n < 1) {
+        throw new ArgumentError(`limit must be a positive integer (1-${max})`);
+    }
+    if (n > max) {
+        throw new ArgumentError(`limit must be <= ${max}`);
+    }
+    return n;
+}
+
+cli({
+    site: '12306',
+    name: 'stations',
+    access: 'read',
+    description: 'Search 12306 (China Railway) stations by Chinese name, telecode, or pinyin keyword',
+    domain: 'kyfw.12306.cn',
+    strategy: Strategy.PUBLIC,
+    browser: false,
+    args: [
+        { name: 'keyword', positional: true, required: true, help: 'Chinese substring (上海), telecode (AOH), or pinyin (shanghai)' },
+        { name: 'limit', type: 'int', default: 20, help: `Maximum results (1-${MAX_LIMIT})` },
+    ],
+    columns: ['name', 'code', 'pinyin', 'abbr', 'city'],
+    func: async (kwargs) => {
+        const keyword = String(kwargs.keyword ?? '').trim();
+        if (!keyword) throw new ArgumentError('keyword must not be empty');
+        const limit = normalizeLimit(kwargs.limit, 20, MAX_LIMIT);
+
+        const stations = await fetchStationBundle();
+        const lower = keyword.toLowerCase();
+        const matches = stations.filter((s) =>
+            s.name.includes(keyword)
+            || s.code === keyword.toUpperCase()
+            || s.pinyin.includes(lower)
+            || s.abbr.includes(lower)
+            || s.short.includes(lower)
+            || s.city.includes(keyword),
+        );
+        if (matches.length === 0) {
+            throw new EmptyResultError(`No 12306 stations match "${keyword}"`);
+        }
+        return matches.slice(0, limit).map((s) => ({
+            name: s.name,
+            code: s.code,
+            pinyin: s.pinyin,
+            abbr: s.abbr,
+            city: s.city,
+        }));
+    },
+});
+
+export const __test__ = { normalizeLimit };

package/clis/12306/train.js

@@ -0,0 +1,91 @@
+/**
+ * 12306 train stop details - list every station a train calls at,
+ * with arrival / departure / stopover time.
+ *
+ * Requires the internal `train_no` returned by `12306 trains`
+ * (`24000000G10L`), not the public train code (`G1`).
+ */
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import { ArgumentError, CommandExecutionError, EmptyResultError } from '@jackwener/opencli/errors';
+import { fetchStationBundle, mintSession, resolveStation, validateDate } from './utils.js';
+
+const UA = 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/127.0 Safari/537.36';
+const TRAIN_NO_RE = /^[0-9A-Z]{8,18}$/;
+
+async function queryStops(cookieHeader, trainNo, fromCode, toCode, date, fetchImpl = fetch) {
+    const url = `https://kyfw.12306.cn/otn/czxx/queryByTrainNo?train_no=${trainNo}&from_station_telecode=${fromCode}&to_station_telecode=${toCode}&depart_date=${date}`;
+    const resp = await fetchImpl(url, {
+        headers: {
+            'User-Agent': UA,
+            'Referer': 'https://kyfw.12306.cn/otn/leftTicket/init',
+            'Cookie': cookieHeader,
+        },
+    });
+    if (!resp.ok) {
+        throw new CommandExecutionError(`12306 queryByTrainNo returned HTTP ${resp.status}`);
+    }
+    let json;
+    try {
+        json = await resp.json();
+    } catch {
+        throw new CommandExecutionError('12306 queryByTrainNo returned non-JSON body');
+    }
+    if (json?.status !== true || !Array.isArray(json?.data?.data)) {
+        throw new CommandExecutionError(`12306 queryByTrainNo returned an unexpected payload shape`);
+    }
+    return json.data.data;
+}
+
+cli({
+    site: '12306',
+    name: 'train',
+    access: 'read',
+    description: 'List every station a 12306 train calls at, with arrival / departure / stopover time (anonymous, no login required)',
+    domain: 'kyfw.12306.cn',
+    strategy: Strategy.PUBLIC,
+    browser: false,
+    args: [
+        { name: 'train-no', positional: true, required: true, help: 'Internal train_no from `12306 trains` (e.g. 24000000G10L), not the public code (G1)' },
+        { name: 'from', required: true, help: 'Origin station for the segment: Chinese name, telecode, or pinyin' },
+        { name: 'to', required: true, help: 'Destination station for the segment' },
+        { name: 'date', required: true, help: 'Departure date in YYYY-MM-DD' },
+    ],
+    columns: ['station_no', 'station_name', 'arrive_time', 'start_time', 'stopover_time'],
+    func: async (kwargs) => {
+        const trainNo = String(kwargs['train-no'] ?? '').trim();
+        if (!trainNo) throw new ArgumentError('<train-no> must not be empty');
+        if (!TRAIN_NO_RE.test(trainNo)) {
+            throw new ArgumentError(
+                `<train-no> "${trainNo}" does not look like a 12306 internal train_no`,
+                'Use the train_no field from `12306 trains` output (e.g. 24000000G10L), not the public code (G1).',
+            );
+        }
+        const fromArg = String(kwargs.from ?? '').trim();
+        const toArg = String(kwargs.to ?? '').trim();
+        if (!fromArg) throw new ArgumentError('--from station must not be empty');
+        if (!toArg) throw new ArgumentError('--to station must not be empty');
+        const date = validateDate(kwargs.date);
+
+        const stations = await fetchStationBundle();
+        const fromStation = resolveStation(stations, fromArg);
+        const toStation = resolveStation(stations, toArg);
+        if (fromStation.code === toStation.code) {
+            throw new ArgumentError(`--from and --to must differ; both resolved to ${fromStation.name} (${fromStation.code})`);
+        }
+
+        const cookieHeader = await mintSession();
+        const stops = await queryStops(cookieHeader, trainNo, fromStation.code, toStation.code, date);
+        if (stops.length === 0) {
+            throw new EmptyResultError(`No stops returned for train_no=${trainNo} on ${date}`);
+        }
+        return stops.map((s) => ({
+            station_no: s.station_no || '',
+            station_name: s.station_name || '',
+            arrive_time: s.arrive_time === '----' ? '' : (s.arrive_time || ''),
+            start_time: s.start_time === '----' ? '' : (s.start_time || ''),
+            stopover_time: s.stopover_time === '----' ? '' : (s.stopover_time || ''),
+        }));
+    },
+});
+
+export const __test__ = { queryStops, TRAIN_NO_RE };