itamatrix 0.1.0

package/docs/ROUTING_CODES.md

@@ -0,0 +1,137 @@
+# ITA Matrix Routing & Extension Codes — reference
+
+Reference for constructing the two advanced per-slice inputs on ITA Matrix: **Routing Codes**
+(the flight *path*) and **Extension Codes** (faring & itinerary *filters*). Written for an
+agent skill that builds these strings from natural-language intent.
+
+Sources: [Google: Using the ITA Routing Codes](https://support.google.com/faqs/answer/2736497?hl=en),
+[Travel Codex routing guide](https://www.travelcodex.com/advanced-routing-language-in-ita/),
+[UponArriving extension-code guide](https://www.uponarriving.com/ita-matrix-guide/).
+
+> Two separate fields, per slice. Don't mix them: path goes in **Routing**, faring/filters go in
+> **Extension**. Both are optional. Codes are case-insensitive. Within Extension, separate
+> multiple commands with `;`.
+
+---
+
+## 1. Routing Codes (the path)
+
+Define which carriers / airports / operators a slice may use, and in what order.
+
+### Operators
+
+| Operator | Meaning | Example |
+|----------|---------|---------|
+| `,` | any-of (OR), **no spaces** | `AA,UA,DL` — any of the three |
+| `` (space) | sequence (then) | `UA SFO UA` — UA, via SFO, UA |
+| `~` | negation / exclude | `~CLT` — connect anywhere except CLT |
+| `+` | one or more | `UA+` — one or more UA flights |
+| `*` | zero or more | `AA* DL AA*` — a DL flight somewhere in an AA itinerary |
+| `?` | zero or one | `UA?` — optional UA segment |
+| `()` | grouping | `(AA,BA) LHR` |
+
+### Tokens
+
+| Token | Meaning | Example |
+|-------|---------|---------|
+| `XX` | airline (2-letter), marketing carrier by default | `BA` |
+| `XX####` | specific flight number | `UA882` |
+| `XX####-####` | flight-number range | `UA1000-2000` |
+| `AAA` | airport / city (3-letter) as a connection point | `NRT` |
+| `C:XX` | force **marketing** carrier | `C:BA` |
+| `O:XX` | force **operating** carrier | `O:AA` |
+| `X:AAA` | **require** connection at airport | `X:DFW` |
+| `N:` | nonstop only (no connections) | `N:` |
+| `F:` | direct (single flight number, stops allowed) | `F:` |
+
+### Inline path modifiers (`/ cmd`)
+
+Some filters can be appended inline in the Routing field with a leading slash:
+
+| Modifier | Meaning | Example |
+|----------|---------|---------|
+| `/ maxconnect mmm` | max connection minutes | `/ maxconnect 120` |
+| `/ minconnect mmm` | min connection minutes | `/ minconnect 45` |
+| `/ alliance NAME` | restrict to alliance | `/ alliance star-alliance` |
+
+> These overlap with Extension codes; prefer the Extension field for filters and keep Routing
+> for the path. Alliance names: `oneworld`, `skyteam`, `star-alliance`.
+
+### Routing examples
+
+| Intent | Routing |
+|--------|---------|
+| Only United, any routing | `UA+` |
+| Via Tokyo, Seoul, or Hong Kong | `NRT,ICN,HKG` |
+| American, avoid Charlotte | `AA+ ~CLT` |
+| Star Alliance carriers only | `UA,LH,NH,SQ,AC,TG+` |
+| Force connection in Dallas | `X:DFW` |
+| Specific flight then any | `UA882 UA+` |
+
+---
+
+## 2. Extension Codes (faring & filters)
+
+Separate multiple commands with `;`. Within a command, multiple values are space- or
+pipe-(`|`)-separated.
+
+### Itinerary filters
+
+| Code | Syntax | Example | Meaning |
+|------|--------|---------|---------|
+| Max segments | `MAXSTOP n` | `MAXSTOP 2` | cap number of flights |
+| Max duration | `MAXDUR h:mm` | `MAXDUR 6:45` | total journey time ceiling |
+| Max miles | `MAXMILES n` | `MAXMILES 2900` | distance ceiling |
+| Min miles | `MINMILES n` | `MINMILES 2600` | distance floor |
+| Min connect | `MINCONNECT h:mm` | `MINCONNECT 1:00` | min layover |
+| Max connect | `MAXCONNECT h:mm` | `MAXCONNECT 2:00` | max layover |
+| Pad connect | `PADCONNECT h:mm` | `PADCONNECT 0:30` | buffer beyond airline minimum |
+| Alliance | `ALLIANCE name` | `ALLIANCE oneworld` | alliance only |
+| Allow airlines | `AIRLINES a b` | `AIRLINES BA AF` | only these carriers |
+| Disallow airlines | `-AIRLINES a b` | `-AIRLINES AA BA` | block these carriers |
+| Allow operating | `OPAIRLINES a` | `OPAIRLINES AA` | by operating carrier |
+| Disallow operating | `-OPAIRLINES a` | `-OPAIRLINES AA` | block operating carrier |
+| Avoid cities | `-CITIES a b` | `-CITIES DFW ORD` | avoid connection hubs |
+| No codeshares | `-CODESHARE` | `-CODESHARE` | exclude codeshare flights |
+| No red-eyes | `-REDEYES` | `-REDEYES` | exclude red-eye flights |
+| No overnights | `-OVERNIGHTS` | `-OVERNIGHTS` | exclude overnight layovers |
+| No props | `-PROPS` | `-PROPS` | exclude propeller aircraft |
+
+### Faring codes (`f` / booking class / fare basis)
+
+| Code | Syntax | Example | Meaning |
+|------|--------|---------|---------|
+| Require cabin | `+CABIN code` | `+CABIN business` | mandate cabin (`first`/`business`/`premium-coach`/`coach`) |
+| Prohibit cabin | `-CABIN code` | `-CABIN coach` | block a cabin |
+| Booking class | `f bc=X` | `f bc=y` | require prime booking code |
+| Multiple booking | `f bc=X\|bc=Y` | `f bc=y\|bc=b` | any of several booking codes |
+| Fare basis | `f ..FFFF` | `f ..yup\|..f` | target fare basis codes |
+| Carrier + market + basis | `f CC.AAA+BBB.FFFF` | `f aa.lon+chi.yup` | full fare spec |
+| Carrier + basis | `f CC..FFFF` | `f aa..yup` | by airline + fare code |
+| Market only | `f .AAA+BBB.` | `f .lon+chi.` | by city pair |
+| Wildcard basis | `f ..X-` | `f ..y-\|..b-` | fare-basis prefix patterns |
+
+### Extension examples
+
+| Intent | Extension |
+|--------|-----------|
+| Short layovers, no overnights | `MINCONNECT 0:45; MAXCONNECT 2:00; -OVERNIGHTS` |
+| Business class, oneworld | `+CABIN business; ALLIANCE oneworld` |
+| Only BA/AF, full-fare Y | `AIRLINES BA AF; f bc=y` |
+| Avoid ORD & DFW, no props | `-CITIES ORD DFW; -PROPS` |
+| Cap trip at 9h, 2 stops max | `MAXDUR 9:00; MAXSTOP 2` |
+
+---
+
+## 3. Notes for the skill
+
+- **Validate field placement**: path-shaped intent → Routing; filter/fare intent → Extension.
+- **Cabin two ways**: the top-level `--cabin` (search option) sets the *displayed* cabin;
+  `+CABIN`/`-CABIN` in Extension enforces it at the fare level. Prefer `--cabin` for simple
+  cases; use Extension `+CABIN` when combining with other faring codes.
+- **Per slice**: each leg has its own Routing + Extension. Multi-city legs can differ.
+- **Uncertainty**: exact `f` faring grammar is community-documented, not officially published;
+  the skill should surface the constructed code to the user and let Matrix's own validation
+  reject malformed input rather than over-validating locally.
+- **Round-trip**: Matrix applies the same routing intent symmetrically unless a return-slice
+  routing is given explicitly.

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "itamatrix",
+  "version": "0.1.0",
+  "description": "CLI for ITA Matrix flight search",
+  "type": "module",
+  "bin": {
+    "itamatrix": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "docs",
+    "skills",
+    "DESIGN.md",
+    "README.md"
+  ],
+  "keywords": [
+    "ita-matrix",
+    "flights",
+    "airfare",
+    "cli",
+    "travel"
+  ],
+  "license": "MIT",
+  "author": "Eran Krakovsky",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ekrako/itamatrix.git"
+  },
+  "bugs": {
+    "url": "https://github.com/ekrako/itamatrix/issues"
+  },
+  "homepage": "https://github.com/ekrako/itamatrix#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsx src/cli.ts",
+    "gen:skill": "tsx scripts/gen-skill.ts",
+    "gen:skill:check": "tsx scripts/gen-skill.ts --check",
+    "lint:md": "markdownlint-cli2 \"**/*.md\"",
+    "prepare": "pre-commit install || true",
+    "test": "vitest run",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "chalk": "^5.3.0",
+    "cli-table3": "^0.6.5",
+    "commander": "^12.1.0",
+    "playwright": "^1.49.0",
+    "zod": "^3.24.1"
+  },
+  "devDependencies": {
+    "@semantic-release/changelog": "^6.0.3",
+    "@semantic-release/exec": "^7.1.0",
+    "@semantic-release/git": "^10.0.1",
+    "@types/node": "^22.10.0",
+    "markdownlint-cli2": "^0.15.0",
+    "semantic-release": "^25.0.5",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.8"
+  }
+}

package/skills/itamatrix/SKILL.md

@@ -0,0 +1,173 @@
+---
+name: itamatrix
+description: >-
+  Search flights on ITA Matrix from natural language. Use when the user wants to
+  find flights, compare fares, build a multi-city trip, or scan a price calendar,
+  and especially when the request implies advanced constraints (specific carriers,
+  alliances, connection hubs to force or avoid, layover limits, cabin/fare rules).
+  Translates the request into the `itamatrix` CLI plus ITA routing/extension codes.
+---
+
+# itamatrix — natural language → ITA Matrix search
+
+This skill drives the `itamatrix` CLI. Your job: turn a natural-language trip
+request into the right command + flags, encoding advanced intent as ITA
+**routing codes** (the path) and **extension codes** (faring/filters).
+
+## Prerequisites
+
+The CLI ships as `itamatrix` (`npx itamatrix ...` if not installed globally).
+On first use it may ask for the browser: `npx playwright install chromium`.
+Queries take 30–60 s (Matrix is slow server-side); repeated queries hit the cache.
+
+Always run with `--json` so you get structured output to parse and summarize.
+
+## Pick the command
+
+| Request shape | Command |
+|---------------|---------|
+| One-way or round-trip A→B | `search <origin> <dest> --depart … [--return …]` |
+| 3+ distinct legs / open-jaw | `multicity --leg O:D:DATE --leg …` (≥2 legs) |
+| "cheapest date to fly", flexible dates | `calendar <origin> <dest> --depart-range S:E [--trip-length N]` |
+
+Codes are airport/city codes (BOS, LON). Dates are `YYYY-MM-DD`. If the user
+gives a relative date ("next month"), resolve it to an absolute date first.
+
+## Map intent → flags
+
+Prefer plain flags for simple intent; reach for `--routing`/`--ext` only when a
+flag can't express it.
+
+| Intent | Use |
+|--------|-----|
+| cabin | `--cabin cheapest\|premium-economy\|business\|first` |
+| nonstop / max stops | `--stops none\|1\|2` |
+| "only UA and AA" (simple) | `--carriers UA,AA` |
+| number of travelers | `--adults N` |
+| how many results | `--limit N` (1–25 for search/multicity) |
+
+## Encode advanced intent → routing / extension codes
+
+Read **[../../docs/ROUTING_CODES.md](../../docs/ROUTING_CODES.md)** for the full
+grammar before constructing codes. Rules of thumb:
+
+- **Path intent → `--routing`.** Which carriers/airports/operators and in what
+  order. E.g. "via Tokyo or Seoul" → `--routing NRT,ICN`; "force a Dallas
+  connection" → `--routing X:DFW`; "American, avoid Charlotte" → `--routing "AA+ ~CLT"`.
+- **Filter / fare intent → `--ext`.** Layover limits, durations, alliance, no
+  red-eyes, fare basis. Separate commands with `;`. E.g. "short layovers, no
+  overnights" → `--ext "MINCONNECT 0:45; MAXCONNECT 2:00; -OVERNIGHTS"`;
+  "business on oneworld" → `--ext "+CABIN business; ALLIANCE oneworld"`.
+- Don't mix the two fields. Path goes in `--routing`, filters/fares in `--ext`.
+- The `f` faring grammar is community-documented, not official — let Matrix
+  validate. Don't over-restrict locally.
+
+## Workflow
+
+1. Parse the request: route(s), dates, travelers, and any constraints.
+2. Choose the command; resolve relative dates to absolute.
+3. Map constraints to flags first; encode the rest as `--routing` / `--ext`
+   using the reference doc.
+4. **Echo the constructed command to the user before running** — especially the
+   routing/extension codes, so they can confirm or correct the intent.
+5. Run with `--json`, parse, and present the results clearly (price, carriers,
+   stops, duration). On a CLI error, read the message — it names the bad flag —
+   and fix the command rather than guessing.
+
+## Command reference
+
+The block below is generated from the CLI's own command/option definitions by
+`scripts/gen-skill.ts` — do not edit it by hand. Run `npm run gen:skill` after
+changing the CLI; `npm run gen:skill:check` (pre-commit hook) fails if it drifts.
+
+<!-- BEGIN GENERATED: command-reference -->
+
+Global options (precede the subcommand):
+
+| Option | Meaning |
+|--------|---------|
+| `-V, --version` | output the version number |
+| `--json` | force JSON output |
+| `--table` | force table output |
+| `--no-cache` | bypass the result cache (always query live) |
+| `--cache-ttl <minutes>` | max age of a cached result in minutes (default 60) |
+
+### `search <origin> <dest>`
+
+Search one-way or round-trip flights
+
+| Option | Meaning |
+|--------|---------|
+| `--depart <date>` | departure date (YYYY-MM-DD) |
+| `--return <date>` | return date (YYYY-MM-DD) → round-trip |
+| `--one-way` | force one-way (ignore --return) |
+| `--adults <n>` | number of adults (default `1`) |
+| `--limit <n>` | max results, 1-25 (one Matrix page) (default `25`) |
+| `--cabin <cabin>` | cheapest \| premium-economy \| business \| first |
+| `--stops <stops>` | any \| none \| 1 \| 2 |
+| `--extra-stops <stops>` | any \| none \| 1 \| 2 |
+| `--carriers <list>` | comma-separated carriers, e.g. UA,AA (sugar for --routing) |
+| `--routing <codes>` | ITA routing codes (path) — see docs/ROUTING_CODES.md |
+| `--ext <codes>` | ITA extension codes (faring/filters) — see docs/ROUTING_CODES.md |
+| `--headful` | show the browser window (debug) |
+
+### `multicity`
+
+Search a multi-city itinerary (N legs)
+
+| Option | Meaning |
+|--------|---------|
+| `--leg <ORIGIN:DEST:DATE>` | a leg, e.g. JFK:NRT:2026-08-10 (repeatable, >= 2) |
+| `--adults <n>` | number of adults (default `1`) |
+| `--limit <n>` | max results, 1-25 (one Matrix page) (default `25`) |
+| `--cabin <cabin>` | cheapest \| premium-economy \| business \| first |
+| `--stops <stops>` | any \| none \| 1 \| 2 |
+| `--extra-stops <stops>` | any \| none \| 1 \| 2 |
+| `--carriers <list>` | comma-separated carriers, e.g. UA,AA (sugar for --routing) |
+| `--routing <codes>` | ITA routing codes applied to every leg |
+| `--ext <codes>` | ITA extension codes applied to every leg |
+| `--headful` | show the browser window (debug) |
+
+### `calendar <origin> <dest>`
+
+Price calendar: lowest fare per departure date over a range
+
+| Option | Meaning |
+|--------|---------|
+| `--depart-range <start:end>` | YYYY-MM-DD:YYYY-MM-DD |
+| `--trip-length <nights>` | round-trip nights; omit for one-way |
+| `--adults <n>` | number of adults (default `1`) |
+| `--limit <n>` | show only the N cheapest dates (default `25`) |
+| `--cabin <cabin>` | cheapest \| premium-economy \| business \| first |
+| `--stops <stops>` | any \| none \| 1 \| 2 |
+| `--extra-stops <stops>` | any \| none \| 1 \| 2 |
+| `--carriers <list>` | comma-separated carriers, e.g. UA,AA (sugar for --routing) |
+| `--routing <codes>` | ITA routing codes |
+| `--ext <codes>` | ITA extension codes |
+| `--headful` | show the browser window (debug) |
+
+<!-- END GENERATED: command-reference -->
+
+## Examples
+
+> "Cheapest business-class flight from Boston to London next August, oneworld only, nonstop."
+
+```bash
+itamatrix --json search BOS LON --depart 2026-08-15 \
+  --cabin business --stops none --ext "ALLIANCE oneworld"
+```
+
+> "Round the world: JFK to Tokyo, Tokyo to Singapore, Singapore home. Avoid overnight layovers."
+
+```bash
+itamatrix --json multicity \
+  --leg JFK:NRT:2026-08-10 --leg NRT:SIN:2026-08-15 --leg SIN:JFK:2026-08-20 \
+  --ext "-OVERNIGHTS"
+```
+
+> "What's the cheapest week in August to do a 7-night trip BOS→LAX on United?"
+
+```bash
+itamatrix --json calendar BOS LAX \
+  --depart-range 2026-08-01:2026-08-31 --trip-length 7 --carriers UA
+```