viafrei 1.3.22 → 1.4.8

package/API.md

@@ -9,7 +9,7 @@ the server's own text, reproduced verbatim, because that text is what an
 assistant reads when it decides which tool to call; paraphrasing it here would
 document a different server.
 
-**It is a dated snapshot, taken on 2026-09-28.** Generating this file makes
+**It is a dated snapshot, taken on 2026-09-29.** Generating this file makes
 it impossible for the document and the snapshot to disagree — CI regenerates and
 compares — but it cannot keep the snapshot from ageing against the live server,
 because a capture is a point in time. **The source of truth is the running
@@ -17,12 +17,12 @@ server:** connect any MCP client and call `tools/list`.
 
 | | |
 | --- | --- |
-| Server | `viafrei` 1.3.22 |
+| Server | `viafrei` 1.4.8 |
 | MCP protocol | `2025-06-18` |
 | Streamable HTTP | https://mcp.viafrei.de/mcp |
 | Legacy HTTP+SSE | https://mcp.viafrei.de/sse |
-| Captured from | `https://mcp.viafrei.de/mcp` on 2026-09-28 |
-| Surface | 18 tools, 10 resources, 2 resource templates, 9 prompts |
+| Captured from | `https://mcp.viafrei.de/mcp` on 2026-09-29 |
+| Surface | 19 tools, 10 resources, 2 resource templates, 9 prompts |
 | Parameter schemas | JSON Schema draft-07 |
 | Capabilities | `tools`, `resources`, `prompts`, `logging` |
 
@@ -31,7 +31,7 @@ No API key. No account. No sign-up.
 ## Contents
 
 - [How to read a result](#how-to-read-a-result)
-- [Tools](#tools) — 18
+- [Tools](#tools) — 19
 - [Resources](#resources) — 10
 - [Resource templates](#resource-templates) — 2
 - [Prompts](#prompts) — 9
@@ -86,7 +86,7 @@ The server's own instructions to a connecting client, verbatim:
 
 **Read-only** — it changes nothing. Reaches a third-party source (open world). Idempotent: true. Destructive: false.
 
-> Returns the cheapest petrol stations for one fuel grade around a place or coordinate, with price per litre, brand, address, distance and open state. Use when the user asks where to fill up, what fuel costs nearby, or for a cheap stop on a drive. Do NOT use for charging an electric car (call find_charging_station), for price history, or for motorway traffic (call check_autobahn_traffic). Radius ≤ 25 km, at most 10 stations. The result names the age of any price over an hour old. Prices are for consumer information only; the result's attribution line and the MTS-K note must be shown to the user.
+> Returns the cheapest stations for one fuel grade near a place or coordinate: price per litre, brand, address, distance, open state. Use when the user asks where to fill up or what fuel costs. Do NOT use for charging an electric car (call find_charging_station), price history, or traffic (call check_autobahn_traffic). Radius ≤ 25 km, at most 10 stations. For a brand, a name, open now or at a named time, or nearest-first, call find_fuel_station. Each line names the age of its price and opening-hours claim. Prices are consumer information only; the attribution line and MTS-K note must be shown.
 
 | parameter | type | required | default | constraints |
 | --- | --- | --- | --- | --- |
@@ -106,6 +106,42 @@ The server's own instructions to a connecting client, verbatim:
 - **`place`** — Where to look, as free text: a city ("München", "Munich"), a district or Kreis ("Kreis Fulda"), a Bundesland, a station or stop ("Hamburg Hbf"), a motorway ("A7"), or a street address with a house number ("Hauptstraße 12, 36037 Fulda"). Use this instead of coordinates whenever the person named a place. An address needs its town or postcode — a street and a number alone exist in many towns. Give either place OR lat+lon, never both.
 - **`radius_km`** — Search radius around the place in kilometres (1–25, default 5). The provider's terms cap it at 25 km — a larger circle is a dataset request, not a consumer question.
 
+### `find_fuel_station` — Find a filling station
+
+**Read-only** — it changes nothing. Reaches a third-party source (open world). Idempotent: true. Destructive: false.
+
+> Finds filling stations around a place or coordinate under any combination of filters — grade, brand, name, open now, open at a time you name, open 24 h — sorted by distance, price or name. Use when the question is WHICH station: the closest diesel to a stop, an ARAL open tonight, what one forecourt sells. Do NOT use for the plain "where is fuel cheapest" question (call find_cheapest_fuel) or for charging an electric car (call find_charging_station). Every result carries the attribution and the MTS-K note, and says how old each price and opening-hours claim is.
+
+| parameter | type | required | default | constraints |
+| --- | --- | --- | --- | --- |
+| `brand` | string | no | — | min length 1 |
+| `fuel` | string | no | — | one of `"e5"`, `"e10"`, `"diesel"` |
+| `language` | string | no | `"de"` | one of `"de"`, `"en"` |
+| `lat` | number | no | — | min -90; max 90 |
+| `limit` | integer | no | `5` | min 1; max 10 |
+| `lon` | number | no | — | min -180; max 180 |
+| `name` | string | no | — | min length 1 |
+| `open_at` | string | no | — | pattern `^(?:\d{1,2}:\d{2}\|\d{4}-\d{2}-\d{2}[T ]\d{1,2}:\d{2})$` |
+| `open_now` | boolean | no | `false` | — |
+| `place` | string | no | — | min length 1 |
+| `radius_km` | number | no | `5` | min 1; max 25 |
+| `sort` | string | no | `"distance"` | one of `"distance"`, `"price"`, `"name"` |
+| `whole_day` | boolean | no | `false` | — |
+
+- **`brand`** — Only stations of this brand, matched case-insensitively anywhere in the brand field: "ARAL", "Shell", "TotalEnergies", "JET". Use it when the person named a chain ("die ARAL an der B1"). Free stations often carry no brand at all and are then not matched by any brand.
+- **`fuel`** — Only stations with a current price for this grade: "e5" (Super E5), "e10" (Super E10) or "diesel". Omit to get every station near the place whatever it sells — the answer then lists all the grades it holds a price for. Required when sort is "price", because a price ordering needs a grade.
+- **`language`** — Set this on every call to the language the person is writing in: "en" if they wrote English, "de" if they wrote German. Do not leave it out because it has a default — the default is only the fallback when the language is genuinely unclear, and an English question answered in German is a wrong answer. Place names, station names and road numbers are never translated in either language; in English the German term is kept in parentheses so the person recognises it on signs and in local apps.
+- **`lat`** — Latitude in WGS 84, e.g. 48.137. Use with lon when the caller already holds coordinates; otherwise use place.
+- **`limit`** — How many stations to return (1–10, default 5).
+- **`lon`** — Longitude in WGS 84, e.g. 11.576. Use with lat; otherwise use place.
+- **`name`** — Part of the station's own name or brand, case-insensitive: "Autohof", "Raststätte Fulda". Use it when the person named a specific forecourt rather than a chain. Combine with place to keep the search local.
+- **`open_at`** — Only stations open at that time in Germany (Europe/Berlin): "23:30" means the next time the clock shows 23:30, and "2026-09-30 06:15" a specific local date and time. Use it for "is it still open tonight". Do not pass it together with open_now — they ask the same question about two different clocks.
+- **`open_now`** — When true, only stations the published opening hours say are open at this moment. Default false. A station whose hours we have never read is NOT returned by this filter and is counted in the answer instead — the result never guesses that an unknown station is open.
+- **`place`** — Where to look, as free text: a city ("München", "Munich"), a district or Kreis ("Kreis Fulda"), a Bundesland, a station or stop ("Hamburg Hbf"), a motorway ("A7"), or a street address with a house number ("Hauptstraße 12, 36037 Fulda"). Use this instead of coordinates whenever the person named a place. An address needs its town or postcode — a street and a number alone exist in many towns. Give either place OR lat+lon, never both.
+- **`radius_km`** — Search radius around the place in kilometres (1–25, default 5). 25 km is the provider's own ceiling — a larger circle is a dataset request, not a consumer question.
+- **`sort`** — Order of the answer: "distance" (nearest first, the default — use it for "closest diesel to Hamburg Hbf"), "price" (cheapest first, needs fuel), or "name" (alphabetical, for a person scanning a list of a brand's forecourts).
+- **`whole_day`** — When true, only stations the provider flags as open around the clock (24/7). Default false. Use it for a night drive; it is a stricter filter than open_now, which is satisfied by a station that closes at 22:00.
+
 ### `find_parking` — Parking nearby
 
 **Read-only** — it changes nothing. Answers from data this service already holds (closed world). Idempotent: true. Destructive: false.
@@ -334,7 +370,7 @@ The server's own instructions to a connecting client, verbatim:
 
 **Read-only** — it changes nothing. Answers from data this service already holds (closed world). Idempotent: true. Destructive: false.
 
-> Returns how punctual public transport is right now in one German region: the share of distinct trips more than 5 minutes late at least once, trips with a cancelled stop, the trend against the previous window, and how many trips that rests on. Use when the user asks whether buses and trains are running normally, or whether a strike or storm is disrupting local transport. Do NOT use for one line, trip or station — per-line realtime is not available; the region's figures are the answer. Region-wide aggregates only; window ≤ 120 minutes. CC BY-SA 4.0: show the attribution line to the user.
+> Returns how punctual public transport is right now in one German region: the share of distinct trips at least once more than 5 minutes late, trips with a cancelled stop, the trend against the previous window, and how many trips that rests on. Use when the user asks whether buses and trains are running normally, or whether a strike or storm is disrupting local transport. Do NOT use for one line, trip or station — per-line realtime is unavailable; the region's figures are the answer. Region-wide aggregates only; window ≤ 120 min. CC BY-SA (share-alike): show the attribution line to the user.
 
 | parameter | type | required | default | constraints |
 | --- | --- | --- | --- | --- |
@@ -619,5 +655,5 @@ single call.
 ---
 
 Generated from `catalogue.json` by `scripts/gen-api-doc.mjs`. The snapshot was
-read from `https://mcp.viafrei.de/mcp` on 2026-09-28; no tool was invoked to
+read from `https://mcp.viafrei.de/mcp` on 2026-09-29; no tool was invoked to
 produce it, so no data provider was contacted.

package/CHANGELOG.md

@@ -7,6 +7,275 @@ a Changelog and the versions follow Semantic Versioning.
 
 Nothing yet.
 
+## [1.4.8] - 2026-09-29
+
+**A version-sync release.** The bridge is published at the version the ViaFrei server
+is serving, so that `npx viafrei@X.Y.Z` and the endpoint it relays to are named by one
+number. `mcp.viafrei.de` moved to `1.4.8`, so the bridge follows. 1.4.7 is absent from
+the registry for the same reason 1.4.0–1.4.5 were: that platform version carried no
+bridge change.
+
+**Nothing in the bridge changed at all** — not the runtime, not the tooling, not a
+gate. The diff against 1.4.6 is the three version fields plus the re-captured API
+reference. If 1.4.6 works for you, this is the same code under a number that matches
+the server.
+
+### Changed
+
+- **The API reference is re-captured at 1.4.8** (`API.md`, `catalogue.json`). Unlike
+  1.4.6's re-capture, this one is only a date and a version string: the server's
+  surface did **not** change between 1.4.6 and 1.4.8. Verified rather than assumed —
+  the same 19 tools, 10 resources, 2 resource templates and 9 prompts, with no tool
+  added or removed, no description altered and no `required` list moved, compared
+  field-by-field against the stored snapshot before the new one was written.
+
+  That distinction is the whole reason this entry says so out loud. At 1.4.6 the
+  shipped reference was *wrong* — it omitted a tool the server exposed. Here it was
+  merely *old*. The two need different remedies and only one of them is honest in each
+  case, so which one applied is recorded rather than left for a reader to guess.
+
+  Captured read-only: `initialize`, `tools/list`, `resources/list`,
+  `resources/templates/list`, `prompts/list`. No tool was invoked, so no data provider
+  was contacted, and the session was deleted afterwards. The two substitutions the
+  snapshot documents are unchanged and asserted on the way in and out: 19 of 19
+  `$schema` URIs dropped, exactly 2 long patterns stored as `patternLength`.
+
+## [1.4.6] - 2026-09-29
+
+**The version number is prod's, not this package's own count.** The bridge is released
+at the version the ViaFrei server is actually serving — `mcp.viafrei.de` reports
+`1.4.6` — so that `npx viafrei@X.Y.Z` and the endpoint it relays to can be named by
+one number. That is why this release skips from 1.3.22 to 1.4.6 with no 1.4.0 through
+1.4.5 on the registry: those platform versions carried no bridge change.
+
+The shipped API reference is re-captured from that same server, so the package, the
+endpoint and the documentation all name 1.4.6. It had been left at a 1.3.22 capture,
+which review caught.
+
+Nothing in the bridge's own runtime behaviour changed. Every flag, every environment
+variable, every exit code and every message is what 1.3.22 shipped. What changed is the
+machinery around it — two gates the 1.3.22 release wanted and could not have, one because
+the failure it prevents happened *during* that release, and one that had been kept in step
+by hand since 1.3.15 — plus seven refactors and one documentation fix.
+
+### Added
+
+- **Every external program these scripts run now has a deadline** (`runTool` in
+  `scripts/tools.mjs`, `npm run test:tools`), because on 2026-09-28 one of them stopped
+  returning and nothing noticed.
+
+  A `git` call inside the tarball gate's self-test hung on a GitHub runner. The job had
+  no timeout either, so it ran for **1 hour 49 minutes** before being cancelled by hand;
+  the publish job hit the same stall and sat for 15 minutes with a tag already pushed.
+  Both stopped after the same case and the Node 22 job of the same commit passed, so it
+  reproduces rather than being a one-off (#25).
+
+  **A hang is the one failure mode everything else here is built to prevent.** These
+  scripts refuse by name, prove their controls can say no, and treat a check that read
+  nothing as a failure — and a hung subprocess defeats all of it at once, because it
+  cannot be told apart from work in progress: no exit code, no message, and a log that
+  simply stops. There is now no unbounded external program in `scripts/`: every one goes
+  through a single wrapper with a 120-second default, roughly 120 times the slowest
+  legitimate call here. No count is written down — the bare-name sweep is the instrument,
+  and it fails if a call appears that does not go through the wrapper. (This branch
+  CONVERTED 22 sites across six files; that is a figure about the change, not an
+  inventory of the tree, and an earlier draft of this sentence used it as both.)
+
+  Only a **timeout** is translated, into a refusal naming the program, its arguments and
+  the limit. Every other failure is re-thrown untouched, because each gate decides
+  "refused" from `status`, `stdout` and `stderr` on the thrown error, and wrapping those
+  would break the thing the gates measure. Both halves are asserted.
+
+  **Renaming the call sites nearly disabled the gate that watches them.** The bare-name
+  sweep looked for `execFileSync(`; routing 22 calls through `runTool(` would have left
+  it green over the whole set while covering none of it — the exact silent-hole failure
+  that file exists to refuse. It is caught structurally now: the function names live in
+  one `SPAWNERS` array that both the sweep and its own precondition are derived from, so
+  the two cannot drift again. The only reason this was noticed is that the precondition
+  went red on its own when it found zero spawning files.
+
+- **A gate on the manifest and lockfile versions** (`scripts/check-versions.mjs`,
+  `npm run check:versions`), in **both** workflows (#18).
+
+  Cutting 1.3.15 left `package.json` at `1.3.15` while `package-lock.json` still said
+  `1.3.12`, on a tree seven review rounds had confirmed, and every gate passed. The
+  measured reason: **`npm ci` does not compare the root `version` field at all** —
+  checked on npm 11.19.1 and on the 12.0.2 the publish workflow pins — so nothing in
+  build, test, pack or the tarball gate reads that pair. It has been kept in step by hand
+  ever since, and 1.3.16 and 1.3.22 each said so in their commit messages. "Done
+  deliberately" is the failure mode, not the remedy.
+
+  It lives in `ci.yml` as well as `publish.yml` so the drift surfaces on the push that
+  introduces it rather than at the tag, when the only remedy is a new version. Its exit
+  codes are distinct on purpose — **2** could not run, **1** ran and disagreed — so "I
+  could not read the lockfile" can never look like "I read it and was satisfied". Its
+  self-test covers the mutant #18 asks for and the one that would otherwise agree about
+  nothing — three ABSENT fields are all equal to each other. No case count is written
+  here; `npm run test:versions` prints the one to trust.
+
+### Changed
+
+- **All seven `javascript:S3776` cognitive-complexity findings are gone** (#19), measured
+  on the push rather than claimed: seven CRITICAL findings on `main` before, **zero**
+  after, and zero new issues of any rule. `parseOptions` 22, `remote.onmessage` 18,
+  `checkManifest` 20, the tarball gate's `main` 31, `tokenCandidates` 18, `decodings` 18
+  and `scanFile` 27 are each split by concern, and every extraction MOVED lines rather
+  than rewriting them. No behaviour change — that is the point of the entry being here
+  and not under Fixed.
+
+  The refactor exposed five things nothing was testing, each proved by deleting it and
+  watching the suite stay green: `-h` had no case at all; `setProtocolVersion` had none,
+  so the negotiate-down test asserted that the bridge *complains* about a version and
+  never that it *applies* it; half of one error sentence was unreachable because every
+  fixture carried a `supported` list; a dependency check's early exit could be deleted
+  because every private-scope fixture also happened to be a valid range; and
+  `"is this a listed private name?"` was written out by hand **three** times in
+  `rules.mjs`, in the file that decides whether a commit may be published. All five are
+  closed. The gate self-test went from 107 cases to 110.
+
+- **Both workflow jobs carry `timeout-minutes: 15`** (#25). There was no timeout on any
+  job, so GitHub's default six hours applied — which is how a hung step ran for nearly
+  two. Fifteen minutes is nine times the observed duration of a successful run (~100 s
+  for CI, ~95 s for publish), so it cannot fire on a slow-but-working build, and it ends
+  a hung one in minutes.
+
+- **`publish.yml` refuses a tag whose commit `main` does not contain** (#18). A tag alone
+  decides what is published, so a tag pushed from any branch would have published from
+  it. The ancestry is answerable because the checkout is already full-depth, and the ref
+  is fetched explicitly so an unresolvable `origin/main` is an error rather than a skip.
+
+- **The `npm` deployment environment now says what it gates and why it has no protection
+  rule** (#18): it is the OIDC subject npm's trusted publisher is configured against, so
+  it is part of the credential, and it has no required reviewer deliberately — the
+  release is already gated by a verdict covering HEAD and by every gate running against
+  the exact tarball uploaded. Recorded so "no rule needed" is distinguishable from
+  "nobody looked".
+
+### Fixed
+
+- **The shipped API reference described the wrong server.** `API.md` and
+  `catalogue.json` both ship, and both still said `viafrei 1.3.22` from a 2026-09-28
+  capture — in a package published as 1.4.6, whose whole point is that the package and
+  the endpoint are named by one number. Found in review, and it was not merely dated:
+  re-capturing from `mcp.viafrei.de` shows the surface genuinely moved. The server
+  exposes a nineteenth tool, `find_fuel_station`, that the reference did not mention at
+  all, and `find_cheapest_fuel` and `check_transit_disruption` have new descriptions.
+
+  Re-captured read-only — `initialize`, `tools/list`, `resources/list`,
+  `resources/templates/list`, `prompts/list`, no tool invoked, so no data provider was
+  contacted — and the session was closed afterwards. The two substitutions the snapshot
+  documents are unchanged and were asserted rather than assumed: every tool's `$schema`
+  URI is dropped (19 of 19), and the two 288-character date patterns are stored as
+  `patternLength`.
+
+  **No gate could have caught this**, which is the part worth keeping. `check:docs`
+  passed throughout: it proves `API.md` matches `catalogue.json`, so a stale pair passes
+  together. Nothing in this repository compares the snapshot against the running server,
+  and `npm ci`-style version agreement cannot see it either. The reference's currency is
+  checked by a person at the cut, and that is now a step rather than a habit.
+
+- **`SOURCES.md` printed an attribution string the server had stopped sending** (#332).
+  The shipped document is what a reader consults to know whose data they are looking at,
+  so a stale attribution line there is wrong in the one place it matters.
+
+- **Every push ran CI twice** (#23). `push: branches: ['**']` and `pull_request` both
+  fired for a branch with an open pull request, so one push ran the whole matrix twice —
+  four `build-and-test` jobs for two Node versions, doubling the wait and the minutes for
+  no added signal. `push` is now `main` only; everything else arrives through its pull
+  request. The cost is named in the workflow rather than discovered later: a branch pushed
+  with **no** pull request now gets no CI. That is the right trade here — the flow is
+  push-then-open-immediately, the reviewer reads local commits before the push, and the
+  publish workflow re-runs every gate against the tag regardless.
+
+- **Four README links resolved on the package page but not inside the tarball** (#23).
+  `README.md` ships and linked to `CODE_OF_CONDUCT.md`, `CONTRIBUTING.md`, `SECURITY.md`
+  and `SUPPORT.md`, none of which do. Three were pre-existing — verified in the published
+  1.3.15 tarball — and `SUPPORT.md` was added by 1.3.16, so that release made an existing
+  condition one worse. npm rewrites relative links in the rendered README to the
+  repository, so it only bit someone reading an unpacked tarball. All four are now
+  absolute, which is the honest form: a link that means "the repository" says so, and it
+  survives any packaging change. The two that remain relative, `API.md` and `SOURCES.md`,
+  are files the tarball carries — and that is now **asserted by the tarball gate**, which
+  reads the README *inside* the built tarball, extracts every relative Markdown link and
+  fails if one is not among the shipped paths. So the fifth such link is caught rather
+  than noticed three releases later. An earlier draft of this sentence said "asserted"
+  when nothing asserted it, which is the third time an entry in this file has claimed a
+  mechanism the tree did not contain; this time the mechanism was written instead of the
+  sentence being softened.
+
+  The rule then arrived with **no case in the gate's own self-test**, and the suite's case
+  count stayed where it was, which is how the review found it: a count that does not move
+  when a rule is added is the suite saying so. It now has two cases, because the rule's
+  first draft could not see an ANCHORED link — `](CONTRIBUTING.md#merging)` to a file the
+  tarball does not carry passed silently, and that is the likeliest fifth link there is.
+  Each was proved red on its own: neutering the rule fails both, and restoring the
+  anchor-blind capture fails only the anchored one.
+
+- **Two comments carried counts that read as inventories** (#23). `scripts/tools.mjs` said
+  "TWENTY sites were changed in all" where twenty was what one commit changed, not what
+  the tree holds; it now says so. `scripts/tools.test.mjs` said a third caller of the
+  shared precondition arrived "within the week" when it arrived the **same day**, which is
+  the harder version of its own point.
+
+### Deliberately not done
+
+- **`javascript:S2187` on every self-test** (#23, item 1) — *cannot be done from the
+  repository.* SonarCloud reads `scripts/*.test.mjs` as test files, finds no framework
+  assertions, and reports "add some tests to this file or delete it" at BLOCKER on each.
+  There are **five** as of this branch, because the version gate above brings its own — so
+  this work adds a file to the class it is declaring unfixable, which is the part worth
+  knowing before the next self-test is written.
+  Measured: analysis here is **Automatic** (no scanner step in any workflow) and
+  `api/settings/values` returns no `sonar.tests` or `sonar.test.inclusions`, so the test
+  patterns live in SonarCloud's own UI and changing them needs a token this repository
+  does not hold. A `sonar-project.properties` was **not** added, because Automatic
+  Analysis may ignore it and a config file that silently does nothing is worse than the
+  finding. The two real options are a UI change to the test patterns, or renaming the
+  convention to `*.selftest.mjs` — which touches `package.json` scripts, CI steps and the
+  sweep that counts them. The quality gate passes on all five conditions either way.
+
+- **The four remaining bare `.sort()` calls** — left, and named so the next person is not
+  ambushed. SonarCloud raised `javascript:S2871` (CRITICAL, type BUG) on the `.sort()` in
+  `relativeMarkdownLinks` and took the new-code reliability rating to D against an A
+  threshold, which is a required check. The line's behaviour was never wrong — every
+  element is a string and code-unit order is what is wanted — but the round-3 refactor
+  moved the expression into a new exported function, so a pattern older than this branch
+  became *new code* and failed a gate it had never been measured by. That is the trap, and
+  it is still loaded four times over:
+
+      git grep -n '\.sort()' -- '*.mjs' '*.ts' | grep -v '^\S*:[0-9]*: \*'
+
+  finds them in `scripts/check-tarball.mjs`, twice in `scripts/tools.test.mjs`, and in
+  `test/relay.test.ts`. All four are string arrays and all four are correct today; none is
+  in this PR's new-code period, so none fails the gate now. **Converting them here would
+  add three files to a diff that is already fifteen**, so they are recorded instead: the
+  next PR that so much as moves one of those lines should expect a CRITICAL BUG on code it
+  only touched, and should fix it in that PR rather than discovering it from a red required
+  check after the push, which is how this one was found.
+
+  Not `localeCompare`, whichever PR does it. It is what the rule suggests and it is wrong
+  here twice: it reorders (`B a` becomes `a B`) and it is locale-dependent (`ä` sorts before
+  `z` under `en`/`de` and after it under `sv`), so a gate's output would depend on the
+  runner. The comparator added here says only what the default already did, and the order
+  is pinned by a case in the self-test.
+
+- **A shared assertion harness for the self-tests** (#23, item 5) — declined, on the
+  issue's own condition. Each self-test defines its own `check()`/`refuse()` pair, and the
+  issue says to unify them only if it can be done without weakening the per-file refusal
+  wording. It cannot, cheaply: the refusals deliberately name different builders and exit
+  by different routes, and that difference is load-bearing — it is what tells a reader
+  which fixture failed. The duplication is seven small functions across five files — four
+  define `check()`, three define `refuse()` — not the eleven-line block that caused the
+  3.1% duplication failure `fixture-root.mjs` was extracted to fix.
+
+### Note on a count in the 1.3.16 entry below
+
+That entry says the tool sweep reads "thirty-two source files". It now reads **34**,
+because this work adds two. The published entry is **left alone**: it was measured at
+that release and editing a shipped block to keep a number current is how a changelog
+stops being a record. The figure to trust is the one `npm run test:tools` prints, which
+is why nothing here states a total either.
+
 ## [1.3.22] - 2026-09-28
 
 **A fresh snapshot of the production server, and the version number that goes with it.

package/README.md

@@ -161,7 +161,7 @@ Restart the client and ask it one of the questions above.
 | **[API.md](API.md)** | Every tool with its parameters, types, defaults and constraints, plus the resources, resource templates and prompts. Generated from a dated snapshot of the running server, so the descriptions are the server's own words — which is what your assistant actually reads when it picks a tool. |
 | **[Wiki](https://github.com/mavrovde/viafrei-bridge/wiki)** | The prose half: [connecting your assistant](https://github.com/mavrovde/viafrei-bridge/wiki/Connecting-your-assistant), [tools at a glance](https://github.com/mavrovde/viafrei-bridge/wiki/Tools-at-a-glance), the [roadmap](https://github.com/mavrovde/viafrei-bridge/wiki/Roadmap) and an [FAQ](https://github.com/mavrovde/viafrei-bridge/wiki/FAQ). |
 | **[SOURCES.md](SOURCES.md)** | Every publisher, what it covers, its licence, and the attribution line to reproduce — including the conditions that are licence breaches rather than style problems. |
-| **[SUPPORT.md](SUPPORT.md)** | Where a question, a bad answer or a security report should go, and what makes a report easy to act on. |
+| **[SUPPORT.md](https://github.com/mavrovde/viafrei-bridge/blob/main/SUPPORT.md)** | Where a question, a bad answer or a security report should go, and what makes a report easy to act on. |
 
 ### Worked use cases
 
@@ -339,8 +339,8 @@ This is said plainly so nobody spends an evening looking for the server code.
 
 ## Contributing
 
-Yes, please — see [CONTRIBUTING.md](CONTRIBUTING.md) and
-[CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md). Issues and discussions are open. The
+Yes, please — see [CONTRIBUTING.md](https://github.com/mavrovde/viafrei-bridge/blob/main/CONTRIBUTING.md) and
+[CODE_OF_CONDUCT.md](https://github.com/mavrovde/viafrei-bridge/blob/main/CODE_OF_CONDUCT.md). Issues and discussions are open. The
 bridge is small and self-contained, which is exactly what makes it a reasonable
 thing to send a first patch to.
 
@@ -352,7 +352,7 @@ cannot get any other way.
 ## Security
 
 Never open a public issue for a key, a token or anything that looks like one.
-See [SECURITY.md](SECURITY.md) for the private reporting path.
+See [SECURITY.md](https://github.com/mavrovde/viafrei-bridge/blob/main/SECURITY.md) for the private reporting path.
 
 ## Licence
 

package/SOURCES.md

@@ -310,13 +310,13 @@ sourceNote              : null
 ```
 
 So GovData's harvest is faithful and there is no versioned statement anywhere in
-the chain. The attribution string the server emits today still names 4.0; that is
-a defect at the source, tracked there, and it will be corrected in the server
-rather than by rewording this page — what this page documents is what the server
-actually sends.
+the chain, and the attribution string the server emits says exactly that: the
+licence is CC BY-SA and the version is unstated. It named 4.0 until v1.4.1, which
+corrected it at the source rather than by rewording this page — what this page
+documents is what the server actually sends.
 
 ```
-Echtzeitdaten: DELFI e.V. via Mobilithek, CC BY-SA 4.0
+Echtzeitdaten: DELFI e.V. via Mobilithek, CC BY-SA
 ```
 
 Share-alike. See [the obligation above](#public-transport-realtime-is-share-alike):

package/dist/bridge.d.ts

@@ -8,16 +8,4 @@ export interface BridgeHooks {
 export interface BridgeHandle {
     close: () => Promise<void>;
 }
-/**
- * Relay every JSON-RPC message between a local stdio client and a remote
- * Streamable-HTTP MCP endpoint, in both directions, unchanged.
- *
- * The bridge is deliberately a *message* relay and not a client/server pair
- * that re-implements the protocol: it never has an opinion about a method it
- * has not heard of, so a tool added on the server works here the same day
- * without a release. The only messages it looks inside are `initialize` and its
- * answer - because the session's protocol version has to end up on the HTTP
- * headers, and because a version the server cannot speak deserves a sentence
- * rather than a stack trace.
- */
 export declare function startBridge(options: Options, hooks: BridgeHooks): Promise<BridgeHandle>;

package/dist/bridge.js

@@ -52,17 +52,44 @@ function readSupportedVersions(data) {
     return [...new Set(versions)];
 }
 /**
- * Relay every JSON-RPC message between a local stdio client and a remote
- * Streamable-HTTP MCP endpoint, in both directions, unchanged.
+ * Reconcile the server's answer to `initialize`, and return the line that must
+ * end the session — AFTER the answer has been relayed, never instead of it, which
+ * is why this returns the line rather than exiting.
  *
- * The bridge is deliberately a *message* relay and not a client/server pair
- * that re-implements the protocol: it never has an opinion about a method it
- * has not heard of, so a tool added on the server works here the same day
- * without a release. The only messages it looks inside are `initialize` and its
- * answer - because the session's protocol version has to end up on the HTTP
- * headers, and because a version the server cannot speak deserves a sentence
- * rather than a stack trace.
+ * Extracted from `remote.onmessage`, which was cognitive complexity 18 (#19) with
+ * this nested four deep inside the relay path. Nothing here decides anything new:
+ * a usable version is applied through `onNegotiated`, a mismatch warns and relays
+ * unchanged, a rejection returns the fatal line, and any other shape is relayed
+ * with no comment.
+ *
+ * Two of the three behaviours this moved were NOT covered when the move was made,
+ * measured by deleting them: `setProtocolVersion` and the "did not say which
+ * versions" half of the sentence both survived with the whole suite green. Both
+ * now have a case. The third — `initialized = true` — is still ungated: it is
+ * observable only through a LATER failure's exit code, and it sits inside the
+ * `onNegotiated` callback whose invocation the new header case does gate. So a
+ * callback that stops firing is caught; a callback that fires and drops that one
+ * assignment is not. Said here rather than left for someone to assume otherwise.
  */
+function reconcileInitialize(message, session) {
+    if (isJSONRPCResultResponse(message)) {
+        const served = readProtocolVersion(message.result);
+        if (served === undefined) {
+            return undefined;
+        }
+        session.onNegotiated(served);
+        if (session.requested !== undefined && served !== session.requested) {
+            session.warn(`viafrei: ${session.url} speaks MCP protocol ${served}, this client asked for ${session.requested}; relaying the server's answer unchanged`);
+        }
+        return undefined;
+    }
+    if (isJSONRPCErrorResponse(message)) {
+        const supported = readSupportedVersions(message.error.data);
+        const spoken = supported.length > 0 ? `the server speaks ${supported.join(', ')}` : `the server did not say which versions it speaks`;
+        return `viafrei: ${session.url} rejected MCP protocol version ${session.requested ?? '(unspecified)'}; ${spoken}`;
+    }
+    return undefined;
+}
 export async function startBridge(options, hooks) {
     const remote = new StreamableHTTPClientTransport(new URL(options.url), {
         fetch: createFetch(options.timeoutMs),
@@ -153,21 +180,15 @@ export async function startBridge(options, hooks) {
         let fatalAfterRelay;
         if (pending !== undefined && id !== undefined) {
             pendingInitialize.delete(id);
-            if (isJSONRPCResultResponse(message)) {
-                const served = readProtocolVersion(message.result);
-                if (served !== undefined) {
+            fatalAfterRelay = reconcileInitialize(message, {
+                requested: pending.requested,
+                url: options.url,
+                onNegotiated: served => {
                     remote.setProtocolVersion?.(served);
                     initialized = true;
-                    if (pending.requested !== undefined && served !== pending.requested) {
-                        hooks.warn(`viafrei: ${options.url} speaks MCP protocol ${served}, this client asked for ${pending.requested}; relaying the server's answer unchanged`);
-                    }
-                }
-            }
-            else if (isJSONRPCErrorResponse(message)) {
-                const supported = readSupportedVersions(message.error.data);
-                const spoken = supported.length > 0 ? `the server speaks ${supported.join(', ')}` : `the server did not say which versions it speaks`;
-                fatalAfterRelay = `viafrei: ${options.url} rejected MCP protocol version ${pending.requested ?? '(unspecified)'}; ${spoken}`;
-            }
+                },
+                warn: hooks.warn
+            });
         }
         void local.send(message).then(() => {
             if (fatalAfterRelay !== undefined) {

package/dist/config.d.ts

@@ -59,11 +59,5 @@ export interface Options {
 }
 export declare class UsageError extends Error {
 }
-/**
- * Parse argv (without `node` and the script) plus the environment.
- *
- * Precedence is the one people expect: a flag beats an environment variable,
- * an environment variable beats the built-in default.
- */
 export declare function parseOptions(argv: readonly string[], env?: NodeJS.ProcessEnv): Options;
 export declare function helpText(version: string): string;

package/dist/config.js

@@ -103,6 +103,95 @@ function validateUrl(raw, source) {
  * Precedence is the one people expect: a flag beats an environment variable,
  * an environment variable beats the built-in default.
  */
+/**
+ * Flags that take no value, and which boolean each one sets.
+ *
+ * A table rather than a chain of `===` comparisons, so an alias is a KEY: adding
+ * `-?` is one line and cannot be added to one spelling and forgotten in another.
+ * The risk a table carries is the opposite one - a key silently absent - so the
+ * aliases are pinned in `config.test.ts` as equivalences to their long forms
+ * rather than one case each. `-h` had no case at all before this table existed,
+ * and deleting it from the old chain left the whole suite green.
+ */
+const BOOLEAN_FLAGS = new Map([
+    ['--help', 'showHelp'],
+    ['-h', 'showHelp'],
+    ['--version', 'showVersion'],
+    ['-V', 'showVersion']
+]);
+const VALUE_FLAGS = [
+    {
+        names: ['--url'],
+        apply: (options, value, source) => {
+            options.url = validateUrl(value, source);
+        }
+    },
+    {
+        names: ['--header', '-H'],
+        apply: (options, value, source) => {
+            const [name, headerValue] = parseHeader(value, source);
+            options.headers[name] = headerValue;
+        }
+    },
+    {
+        names: ['--timeout'],
+        apply: (options, value, source) => {
+            options.timeoutMs = parseTimeout(value, source);
+        }
+    }
+];
+/**
+ * The environment, applied before argv so that a flag beats a variable by
+ * POSITION rather than by a rule — and so a `--header` of the same name
+ * overwrites this one while a `--header` of a different name joins it.
+ */
+function applyEnvironment(options, env) {
+    const url = env[URL_ENV_VAR]?.trim();
+    if (url !== undefined && url !== '') {
+        options.url = validateUrl(url, URL_ENV_VAR);
+    }
+    const timeout = env[TIMEOUT_ENV_VAR]?.trim();
+    if (timeout !== undefined && timeout !== '') {
+        options.timeoutMs = parseTimeout(timeout, TIMEOUT_ENV_VAR);
+    }
+    const headers = env[HEADER_ENV_VAR];
+    if (headers === undefined || headers.trim() === '') {
+        return;
+    }
+    for (const line of headers.split(HEADER_ENV_SEPARATOR)) {
+        // A blank line is skipped rather than refused, so a trailing newline in
+        // the variable is not an error.
+        if (line.trim() !== '') {
+            const [name, value] = parseHeader(line, HEADER_ENV_VAR);
+            options.headers[name] = value;
+        }
+    }
+}
+/**
+ * One argument. `readValue` consumes the NEXT argv entry and is called only for a
+ * flag that needs it, so `--url` at the end of argv still refuses by the same
+ * route it always did.
+ */
+function applyArgument(options, argument, readValue) {
+    const booleanTarget = BOOLEAN_FLAGS.get(argument);
+    if (booleanTarget !== undefined) {
+        options[booleanTarget] = true;
+        return;
+    }
+    for (const flag of VALUE_FLAGS) {
+        const [canonical] = flag.names;
+        if (flag.names.includes(argument)) {
+            flag.apply(options, readValue(), canonical);
+            return;
+        }
+        const inline = `${canonical}=`;
+        if (argument.startsWith(inline)) {
+            flag.apply(options, argument.slice(inline.length), canonical);
+            return;
+        }
+    }
+    throw new UsageError(`unknown argument ${JSON.stringify(argument)} - run "viafrei --help" for the list`);
+}
 export function parseOptions(argv, env = process.env) {
     const options = {
         url: DEFAULT_MCP_URL,
@@ -111,66 +200,17 @@ export function parseOptions(argv, env = process.env) {
         showVersion: false,
         showHelp: false
     };
-    const urlFromEnv = env[URL_ENV_VAR];
-    if (urlFromEnv !== undefined && urlFromEnv.trim() !== '') {
-        options.url = validateUrl(urlFromEnv.trim(), URL_ENV_VAR);
-    }
-    const timeoutFromEnv = env[TIMEOUT_ENV_VAR];
-    if (timeoutFromEnv !== undefined && timeoutFromEnv.trim() !== '') {
-        options.timeoutMs = parseTimeout(timeoutFromEnv.trim(), TIMEOUT_ENV_VAR);
-    }
-    // Before the argv loop, so a --header of the same name overwrites this one
-    // and a --header of a different name joins it — the same precedence --url
-    // has over VIAFREI_MCP_URL, established by position rather than by a rule.
-    const headersFromEnv = env[HEADER_ENV_VAR];
-    if (headersFromEnv !== undefined && headersFromEnv.trim() !== '') {
-        for (const line of headersFromEnv.split(HEADER_ENV_SEPARATOR)) {
-            if (line.trim() === '') {
-                continue;
-            }
-            const [name, value] = parseHeader(line, HEADER_ENV_VAR);
-            options.headers[name] = value;
-        }
-    }
+    applyEnvironment(options, env);
     for (let index = 0; index < argv.length; index += 1) {
         const argument = argv[index];
-        const next = () => {
+        applyArgument(options, argument, () => {
             const value = argv[index + 1];
             if (value === undefined || value.startsWith('--')) {
                 throw new UsageError(`${argument} expects a value`);
             }
             index += 1;
             return value;
-        };
-        if (argument === '--help' || argument === '-h') {
-            options.showHelp = true;
-        }
-        else if (argument === '--version' || argument === '-V') {
-            options.showVersion = true;
-        }
-        else if (argument === '--url') {
-            options.url = validateUrl(next(), '--url');
-        }
-        else if (argument.startsWith('--url=')) {
-            options.url = validateUrl(argument.slice('--url='.length), '--url');
-        }
-        else if (argument === '--header' || argument === '-H') {
-            const [name, value] = parseHeader(next());
-            options.headers[name] = value;
-        }
-        else if (argument.startsWith('--header=')) {
-            const [name, value] = parseHeader(argument.slice('--header='.length));
-            options.headers[name] = value;
-        }
-        else if (argument === '--timeout') {
-            options.timeoutMs = parseTimeout(next(), '--timeout');
-        }
-        else if (argument.startsWith('--timeout=')) {
-            options.timeoutMs = parseTimeout(argument.slice('--timeout='.length), '--timeout');
-        }
-        else {
-            throw new UsageError(`unknown argument ${JSON.stringify(argument)} - run "viafrei --help" for the list`);
-        }
+        });
     }
     return options;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "viafrei",
-  "version": "1.3.22",
+  "version": "1.4.8",
   "description": "German traffic, rail, parking, charging, fuel, address and weather data in your AI assistant - MCP, no API key. stdio bridge to the hosted ViaFrei MCP server.",
   "keywords": [
     "mcp",
@@ -69,8 +69,10 @@
     "test:leaks": "node scripts/check-leaks.test.mjs",
     "test:tools": "node scripts/tools.test.mjs",
     "test:docs": "node scripts/gen-api-doc.test.mjs",
+    "test:versions": "node scripts/check-versions.test.mjs",
     "check:tarball": "node scripts/check-tarball.mjs",
     "check:leaks": "node scripts/check-leaks.mjs",
+    "check:versions": "node scripts/check-versions.mjs",
     "docs:api": "node scripts/gen-api-doc.mjs",
     "check:docs": "node scripts/gen-api-doc.mjs --check",
     "rules:show": "node scripts/show-rules.mjs"