--- name: pp-haneda-airport description: "Query first-party Haneda flight boards with precise dates, codeshares and terminal handoffs. Trigger phrases: `Haneda flight status`, `Haneda arrivals and departures`, `Haneda terminal and gate`, `Haneda codeshare lookup`, `use haneda-airport`, `run haneda-airport`." author: "zjsng" license: "Apache-2.0" argument-hint: " [args] | install cli|mcp" allowed-tools: "Read Bash" metadata: openclaw: requires: bins: - haneda-airport-pp-cli install: - kind: go bins: [haneda-airport-pp-cli] module: github.com/mvanhorn/printing-press-library/library/travel/haneda-airport/cmd/haneda-airport-pp-cli --- # Haneda Airport — Printing Press CLI For this unpublished local build, use its staged `build/stage/bin/haneda-airport-pp-cli` binary after building from source. Public library installation instructions below apply once published. ## Prerequisites: Install the CLI This skill drives the `haneda-airport-pp-cli` binary. **You must verify the CLI is installed before invoking any command from this skill.** If it is missing, install it first: 1. Install via the Printing Press installer. It defaults binaries to `$HOME/.local/bin` on macOS/Linux and `%LOCALAPPDATA%\Programs\PrintingPress\bin` on Windows: ```bash npx -y @mvanhorn/printing-press-library install haneda-airport --cli-only ``` 2. Verify: `haneda-airport-pp-cli --version` 3. Ensure the reported install directory is on `$PATH` for the agent/runtime that will invoke this skill. If the `npx` install fails (no Node, offline, etc.), fall back to a direct Go install (requires Go 1.26.6 or newer). This installs into `$GOPATH/bin` (default `$HOME/go/bin`), so add that directory to `$PATH` instead: ```bash go install github.com/mvanhorn/printing-press-library/library/travel/haneda-airport/cmd/haneda-airport-pp-cli@latest ``` If `--version` reports "command not found" after install, the runtime cannot see the binary directory on `$PATH`. Do not proceed with skill commands until verification succeeds. Read domestic and international arrivals and departures, inspect source disruptions and published schedules, and compare your saved observations. Explicit source timestamps and unknown fields keep terminal planning grounded in what the airport actually reports. ## When to Use This CLI Use for dated Haneda public flight status, codeshare lookup, delays/cancellations, terminal planning and published schedule inspection. Use saved snapshots for explicit offline observations and change comparison. ## Anti-triggers Do not use this CLI for: - No seat or fare inventory, booking, payment or account operations. - No guaranteed connections or inferred operating-carrier/actual-time claims. ## Unique Capabilities Additional capabilities combine the source's flight facts with local observations. ### Flight planning and observations - **`snapshot save`** — Preserve timestamped scoped boards locally. _Preserve timestamped scoped boards locally._ ```bash haneda-airport-pp-cli snapshot save --file /tmp/haneda-board.json --kind international --direction departure ``` - **`snapshot search`** — Filter a saved board without network access. _Filter a saved board without network access._ ```bash haneda-airport-pp-cli snapshot search --file /tmp/haneda-board.json --flight NH849 --limit 5 ``` - **`snapshot diff`** — See changed status, time and terminal facilities. _See changed status, time and terminal facilities._ ```bash haneda-airport-pp-cli snapshot diff --before /tmp/haneda-before.json --after /tmp/haneda-after.json ``` - **`plan`** — Find the source terminal, gates and check-in handoffs. _Find the source terminal, gates and check-in handoffs._ ```bash haneda-airport-pp-cli plan NH849 --kind international --agent ``` - **`flights rollover`** — Inspect adjacent service days and cross-midnight changes. _Inspect adjacent service days and cross-midnight changes._ ```bash haneda-airport-pp-cli flights rollover --kind international --direction departure --limit 5 ``` ## Discovery Signals Native Chrome exposed the public workflows and assets. Anonymous HTTP replay confirmed the request contracts; the enriched capture records those replay exchanges. - Replay coverage: 14 public API exchanges across 10 endpoint shapes - Protocols: rest_json (75% confidence) - Candidate command ideas: create_search — Derived from observed POST /en/app/api/v2/flight/search traffic.; list_city_list_search.json — Derived from observed GET /site_resource/flight/data/dms/city_list_search.json traffic.; list_company_list_search.json — Derived from observed GET /site_resource/flight/data/dms/company_list_search.json traffic.; list_flight_status.json — Derived from observed GET /en/app_resource/flight/flightStatus/flight_status.json traffic.; list_hdacfasc.json — Derived from observed GET /app_resource/flight/data/dms/hdacfasc.json traffic.; list_hdacfdsc.json — Derived from observed GET /app_resource/flight/data/dms/hdacfdsc.json traffic. ## Cookbook Use the following recipes for a small board, arrivals, disruptions and published schedules. ## Recipes ### Small flight board ```bash haneda-airport-pp-cli flights search --kind international --limit 5 --agent --select flights.id,flights.source_primary_flight,flights.scheduled_at,flights.status,sources.reported_at,observed_at ``` Keep useful flight facts and source time in compact agent output. ### Domestic arrivals ```bash haneda-airport-pp-cli flights search --kind domestic --direction arrival --destination CTS --limit 5 --agent ``` Airport and source city aliases are resolved without changing codeshare identity. ### Disruptions ```bash haneda-airport-pp-cli flights disruptions --kind international --direction both --limit 10 --agent ``` Separate airport summary counts from the returned delayed/canceled/diverted flight groups. ### Monthly schedule ```bash haneda-airport-pp-cli schedule search --kind international --flight NH849 --limit 5 --agent ``` Inspect published periods and operating weekdays with explicit feed coverage. ### Codeshare detail ```bash haneda-airport-pp-cli flights detail UA8003 --kind international --direction departure --limit 5 --agent ``` Resolve a marketing number through the source-primary-only endpoint and bounded board fallback; retain the original listed group. ### Padded terminal lookup ```bash haneda-airport-pp-cli plan NH0849 --kind international --direction departure --agent ``` Find the same primary group with a zero-padded number and use source terminal/facility handoffs. ### Midnight and adjacent days ```bash haneda-airport-pp-cli flights rollover --kind international --direction both --limit 5 --agent ``` Inspect explicit service and revised dates. Empty output means this observation contained no matching rollover evidence. ### Preserve an observation ```bash haneda-airport-pp-cli snapshot save --kind international --direction both --file ./haneda-before.json --agent ``` Write a complete local observation; choose a new filename if it already exists. No provider state is changed. ### Search a saved group ```bash haneda-airport-pp-cli snapshot search --file ./haneda-before.json --flight UA8003 --limit 5 --agent ``` After saving the preceding observation, resolve its marketing group offline with its original time and age. ### Compare observations ```bash haneda-airport-pp-cli snapshot diff --before ./haneda-before.json --after ./haneda-after.json --limit 5 --agent ``` First save a second board to haneda-after.json with the same date/kind/direction. No changes is a valid result; disappearance is not inferred cancellation. ### Resolve an airline ```bash haneda-airport-pp-cli catalog airlines --kind international --query ANA --limit 5 --agent ``` Retain provider airline identifiers, IATA flight prefixes, Japanese names and canonical airline URLs. ## Command Reference | Command | Purpose | | --- | --- | | `flights search` | Live domestic/international arrivals and departures; local flight, airline, airport/city, status and terminal filters | | `flights detail [flight-or-id]` | Resolve a listed number or board ID to its source group, full facilities and canonical detail link | | `flights disruptions` | Source-declared delayed, canceled and diverted services, plus a separately scoped airport summary | | `flights rollover` | Adjacent service days and explicit revised dates crossing midnight | | `plan [flight-or-id]` | Flight facilities, terminal floor, inter-terminal transfer and connection-guide handoffs | | `catalog airports` | English/Japanese names, airport codes and distinct source city values | | `catalog airlines` | English/Japanese names, source airline codes, flight prefixes and airline URLs | | `schedule search` | Published feed windows, service periods and weekdays; accepts full listed flight numbers | | `snapshot save` | Fetch a complete unfiltered board and atomically save an observation | | `snapshot search` | Filter one saved observation without network requests | | `snapshot diff` | Compare two complete observations with identical source/date/kind/direction coverage | Use `--kind domestic|international|all` and `--direction departure|arrival|both`. Defaults are international departures; detail and plan search both directions. `--destination` identifies the other airport: destination for departures, origin for arrivals. `--airline` matches any listed airline, including marketing codeshares; `--flight` accepts full numbers such as NH849 or UA8003. Detail and plan also resolve zero padding such as NH0849. `--status` accepts a source category or exact source status text, a comma-separated list, or `all` / `unknown`. Empty CSV tokens are errors. `--terminal T1|T2|T3` filters known terminals. All result pages default to 20 groups, with `--limit 1..200` and `--offset 0..20000`. `next_offset` refers to the locally filtered result. Re-running a live page fetches a new observation, so totals may change between pages. Use a saved snapshot for stable offline paging. ## Flight evidence and dates `--date YYYY-MM-DD` is a JST service-day query and defaults to today for live boards. The source supports domestic dates from today and international dates from yesterday, through three calendar months. An `all` query uses the domestic start. The provider may include flights from adjacent service days; their `service_date` and stable `hnd:kind:direction:YYYYMMDD:primary` IDs retain those days. Use `--service-day-only` to narrow to the requested day, or `flights rollover` to inspect rollover evidence. Each `listed_flights` array retains source order. Its first number is `source_primary_flight`; the source does not establish that this is the operating carrier, so `operating_flight` stays null. Marketing codeshares match the same group without replacing its identity. Detail tries the source's primary-only exact endpoint, then performs a bounded board lookup when a codeshare or padded number needs resolution. `coverage.query_mode` and `coverage.flight_lookup` disclose the lookup scope. `scheduled_at` and `revised_at` are distinct RFC3339 timestamps in JST. Revised times use the provider's explicit changed date, including earlier calendar days; `time_change_minutes` can be negative. The provider does not label a changed time as estimated versus actual, so `actual_at` stays null. Missing values remain null or empty arrays. `unknown_fields` identifies unavailable operator/actual time, airport, schedule/revision, terminal, boarding-gate and check-in-counter facts, plus unknown status/category or terminal mapping; a blank category with visible status text is still a known status. Gates, check-in counters, security checkpoints and arrival exits have separate fields. An arrival exit is not an aircraft boarding gate. Full `facilities` entries carry available provider map/detail links when requested with `--include-facilities` or via detail/plan. `observed_at` is the local fetch time. Board `sources.reported_at` is the provider response time, not proof of when an individual flight last changed; board `source_updated_at` stays null. Monthly schedule `sources.updated_at` preserves its published `last_upd`. The disruption summary has its own `gettingAt` and coverage, so its counts need not equal a dated or filtered board. Airline information can arrive late; use the canonical flight/airline links for current operational guidance. Monthly feeds expose raw `period_start` / `period_end`, each service's operating period, and weekdays. An optional exact `--date` must lie inside the feed's published window and applies period/weekday rules. Haneda clock times use JST. Remote international airport times remain unassigned to a timezone/day when the feed does not establish them. Schedule lookup uses a listed flight number; board IDs belong to `flights detail`. ## Saved observations `snapshot save` records every group in the selected date/kind/direction scope with source totals and observation time. It refuses truncated scans. The default destination is a timestamped JSON file under the CLI cache's `haneda-snapshots` directory; `--file` chooses an explicit path, and replacing an existing regular file requires `--overwrite`. Files are capped at 8 MiB. Search uses `--file` or the latest cached observation. Explicit kind/direction requests must fit its coverage; explicit `--date` must match its source request date and selects only that service day. Uncovered requests are errors, while a covered query may return zero matching groups. Default search still preserves adjacent service-day rows. Snapshot data is explicitly local; it is never an implicit live fallback. Ages over five minutes set `stale_snapshot` by default and retain the original timestamps. `snapshot search --max-age 30m` chooses another positive age threshold. Diff uses explicit `--before` / `--after`, or the newest compatible cached pair with matching origin/date/kind/direction. A newest unpaired scope does not hide an older compatible pair. Automatic selection examines at most 64 MiB. If a valid compatible pair has already been found, a scan stop caused by the budget or an unreadable/malformed older file preserves that comparison with `cache_selection_complete:false` and `cache_selection_notes`; a newer pair may remain unexamined. Choose explicit paths for exact pair selection. Without a known pair, a stopped scan is an error. Full provider facility entries and map handoffs participate in material changes. Missing baselines return empty results with `baseline_sufficient:false`. Explicitly selected malformed snapshots, invalid timestamps, missing source scopes, count mismatches and incomplete observations are errors; the bounded automatic selection exception above applies only to older files after a fully validated pair is already known. A disappeared group is `no_longer_reported`, never inferred canceled. Only the source's status establishes a reported cancellation. ## Request bounds Domain commands have a 30-second hard deadline, no automatic retries, at most 20 requests, a 4 MiB response cap and a 16 MiB aggregate cap. The adaptive source limiter defaults to two requests per second. Board/catalog metadata is reused only within one command; live boards are freshly fetched. `budget` reports the actual request and response-byte counts. Typical single-kind boards use three requests; all kinds/both directions use eight. Detail fallback can add up to four board requests. Source failures and rate limits are errors rather than empty successes. `--max-scan-records` defaults to 5000 and permits 1..20000. A reached cap is explicit in `scan_cap_hit`; filtered totals then cover only examined records. A failed component aborts an `all`/`both` scope. Airport status, schedules and terminal facilities do not establish seat inventory, fares, reservations or guaranteed connections. **Raw source diagnostics** — The hidden `source` group preserves read-only provider shapes and is excluded from MCP tools. Domain commands above provide normalized planning facts. - `haneda-airport-pp-cli source airlines-domestic` — Read the raw first-party airlines-domestic JSON source. - `haneda-airport-pp-cli source airlines-international` — Read the raw first-party airlines-international JSON source. - `haneda-airport-pp-cli source airports-domestic` — Read the raw first-party airports-domestic JSON source. - `haneda-airport-pp-cli source airports-international` — Read the raw first-party airports-international JSON source. - `haneda-airport-pp-cli source board` — Read the raw first-party board JSON source. - `haneda-airport-pp-cli source disruption-summary` — Read the raw first-party disruption-summary JSON source. - `haneda-airport-pp-cli source schedule-domestic-arrivals` — Read the raw first-party schedule-domestic-arrivals JSON source. - `haneda-airport-pp-cli source schedule-domestic-departures` — Read the raw first-party schedule-domestic-departures JSON source. - `haneda-airport-pp-cli source schedule-international-arrivals` — Read the raw first-party schedule-international-arrivals JSON source. - `haneda-airport-pp-cli source schedule-international-departures` — Read the raw first-party schedule-international-departures JSON source. ### Finding the right command When you know what you want to do but not which command does it, ask the CLI directly: ```bash haneda-airport-pp-cli which "" ``` `which` resolves a natural-language capability query to the best matching command from this CLI's curated feature index. Exit code `0` means at least one match; exit code `2` means no confident match — fall back to `--help` or use a narrower query. `--json` (and other machine formats) keep that exit-2 contract and write `{"matches":[]}` on stdout so agents can inspect the envelope without treating a miss as success. ## Auth Setup The supported source paths are anonymous. No API key, login, reservation or browser runtime is required. Run `haneda-airport-pp-cli doctor` to verify setup. ## Agent Mode Add `--agent` to any command. Expands to: `--json --compact --no-input --no-color`. Global format flags share one contract on promoted, novel, sync, and `--deliver` paths: - `--json` — one JSON document on stdout (sync progress events go to stderr) - `--compact` — keep identity/status/timestamp fields; does not change the document vs stream shape - `--csv` / `--plain` — tabular rows (collection envelopes unwrap to the row array) - `--quiet` — one identity value per row, no envelope - **Pipeable** — JSON on stdout, errors on stderr - **Filterable** — `--select` keeps a subset of fields. Dotted paths descend into nested structures; arrays traverse element-wise. Critical for keeping context small on verbose APIs: ```bash haneda-airport-pp-cli source airlines-domestic --agent --select en,ja,ko ``` - **Previewable** — `--dry-run` shows the request without sending - **Offline observations** — use `snapshot search` and `snapshot diff` for saved board files; live domain commands reject `--data-source local` - **Non-interactive** — never prompts, every input is a flag - **Read-only** — do not use this CLI for create, update, delete, publish, comment, upvote, invite, order, send, or other mutating requests ### Response envelope Commands that read from the local store or the API wrap output in a provenance envelope: ```json { "meta": {"source": "live" | "local" | "computed", "synced_at": "...", "reason": "..."}, "results": } ``` Parse `.results` fo