@maschinenlesbar.org/nina-warnungen-cli 0.0.1

package/LICENSING.md

@@ -0,0 +1,47 @@
+# Licensing
+
+`nina-warnungen-cli` is **dual-licensed**. You may use it under **either** of the
+following, at your choice:
+
+## 1. Open source — AGPL-3.0-or-later (default)
+
+Free to use, modify, and distribute under the
+[GNU Affero General Public License v3.0 or later](LICENSE).
+
+The key obligation is the AGPL's **§13 network clause**: if you run a modified
+version of this software to provide a service to others over a network, you must
+make the complete corresponding source code of your modified version available
+to the users of that service. The usual copyleft terms also apply when you
+distribute the software or works based on it.
+
+This is the right option for open-source projects, internal and personal use,
+evaluation, and anyone able to comply with the AGPL.
+
+## 2. Commercial license
+
+If the AGPL's obligations do not fit your situation — for example, you want to:
+
+- embed `nina-warnungen-cli` in a **closed-source / proprietary product**, or
+- run a **modified version as a proprietary network service (SaaS)** without
+  disclosing your source, or
+- keep your modifications private,
+
+then a separate **commercial license** is available. It grants use of the same
+code without the AGPL's copyleft and network-disclosure obligations, under
+negotiated terms.
+
+**To obtain a commercial license, contact:** sebs@2xs.org
+
+## Why this is possible
+
+The copyright holder owns 100% of the source code in this repository and can
+therefore offer it under more than one license simultaneously. This project does
+**not** accept external code contributions (see [CONTRIBUTING.md](CONTRIBUTING.md)),
+which keeps copyright ownership single and unambiguous — a prerequisite for
+offering the commercial option. The only third-party dependency that ships with
+the package, [`commander`](https://github.com/tj/commander.js), is MIT-licensed
+and compatible with both licensing options.
+
+---
+
+Copyright © 2026 Sebastian Schürmann. All rights reserved.

package/README.md

@@ -0,0 +1,227 @@
+# nina-warnungen-cli
+
+A TypeScript **API client** and **command-line interface** for the open
+[NINA API](https://nina.api.bund.dev/) (`warnung.bund.de`) — the federal
+civil-protection warning system run by the **BBK** (Bundesamt für Bevölkerungsschutz
+und Katastrophenhilfe). It aggregates **MoWaS**, **KATWARN**, **BIWAPP**,
+**DWD severe-weather**, **flood (LHP)** and **police** alerts.
+
+- **Zero runtime HTTP dependencies** — built on Node's built-in `http`/`https` (no axios, no fetch polyfill).
+- **One small dependency** for the CLI: [`commander`](https://github.com/tj/commander.js).
+- **Strongly typed** — typed client surface, warning summaries and the source enum.
+- **Well tested** — unit tests on Node's built-in test runner (`node --test`), every HTTP response mocked.
+- **Read-only, no auth** — the NINA API needs no key; this client only reads.
+
+New to NINA, or terms like *MoWaS*, *Amtlicher Regionalschlüssel (ARS)* or the
+CAP *Severity* levels? See **[GLOSSARY.md](GLOSSARY.md)** for the domain concepts
+and the project's own vocabulary.
+
+## Requirements
+
+- Node.js **>= 20** (uses the stable built-in test runner, ESM and top-level `await`).
+
+## Install
+
+```bash
+npm install
+npm run build        # compiles TypeScript to dist/
+```
+
+Run the CLI without a global install:
+
+```bash
+node dist/src/cli/index.js --help
+# or, after `npm link` / global install:
+nina --help
+```
+
+---
+
+## CLI usage
+
+Search/list commands print pretty JSON to stdout; `warning geojson` writes the raw
+GeoJSON bytes to stdout or to a file via `-o/--output`. The body is buffered in
+memory (bounded by `--max-response-bytes`), not streamed. As a sanity check, if the
+server returns a body whose `Content-Type` does not contain `json` (e.g. a
+`text/html` gateway error page served with a `200` status), the CLI prints a
+warning to stderr before writing it. This is a `Content-Type`-only check — the live
+API serves GeoJSON as `application/json`, so it does not (and cannot) verify that
+the bytes are actually valid GeoJSON, only that the type string looks JSON-ish.
+
+### Global options
+
+| Option | Description |
+| --- | --- |
+| `--base-url <url>` | API base URL (default `https://warnung.bund.de`) |
+| `--timeout <ms>` | Per-request timeout (default `30000`; `0` disables the timeout — waits indefinitely) |
+| `--user-agent <ua>` | `User-Agent` header value |
+| `--max-retries <n>` | Retries for transient `429`/`503` responses (default `2`, capped at `10`) |
+| `--max-response-bytes <n>` | Cap response body size in bytes (`0` = unlimited; default 100 MiB) |
+| `--compact` | Print JSON on a single line |
+| `-o, --output <file>` | For downloads: write bytes to a file instead of stdout |
+
+Global options may be given **before or after** the command, e.g.
+`nina --compact map-data dwd` and `nina map-data dwd --compact` are equivalent.
+
+An identifier that begins with `-` would otherwise be parsed as an option; pass it
+after a `--` separator so it is treated as a positional, e.g.
+`nina warning get -- -odd.identifier`.
+
+Numeric options (`--timeout`, `--max-retries`, `--max-response-bytes`) accept only
+plain non-negative decimal integers; values like `5.0`, `0x10`, `1e3`, `-1` or a
+leading/trailing space are rejected as usage errors.
+
+> **Note on `--base-url` + `--output`:** the base URL is trusted as given, so
+> `nina --base-url <any-http(s)-host> -o <file> ...` is effectively a general
+> "fetch this URL and write it to a file" tool. Only `http`/`https` are allowed
+> (`file:`/`ftp:` are rejected) and redirects are **never followed**, but point it
+> only at hosts you trust. Setting `--max-response-bytes 0` disables the in-memory
+> response-size guard entirely (including the 100 MiB default).
+
+### Commands
+
+```text
+sources                          list the valid warning sources
+map-data <source>                current warnings from a source
+                                 (mowas | katwarn | biwapp | dwd | lhp | police)
+warning   get <id>               full CAP warning by identifier
+warning   geojson <id>           warning geometry as GeoJSON (-o to save)
+dashboard <ars>                  warnings for a region (Amtlicher Regionalschlüssel / AGS)
+archive   mapping <id> | get <id>   MoWaS archive (history + a past warning)
+reference notfalltipps | event-codes | data-version
+```
+
+### Examples
+
+```bash
+# Current severe-weather warnings from the DWD
+nina map-data dwd
+
+# A specific warning (identifier from a map-data entry's `id`)
+nina warning get mow.DE-BY-A-W083-20240101
+
+# Its geometry, saved to a file
+nina -o warn.geojson warning geojson mow.DE-BY-A-W083-20240101
+
+# All warnings affecting a district by its regional key
+nina dashboard 055150000000
+
+# Poll for changes cheaply
+nina --compact reference data-version
+```
+
+Exit codes: `0` success, `4` on a `404` from the API, `1` for any other error, non-zero for usage errors.
+
+---
+
+## Library usage
+
+```ts
+import { NinaClient, NinaApiError, type NinaSource } from "@maschinenlesbar.org/nina-warnungen-cli";
+
+const client = new NinaClient(); // defaults to https://warnung.bund.de
+
+const alerts = await client.mapData("dwd");          // MapWarning[]
+const full = await client.warnings.get(alerts[0]!.id);
+const region = await client.dashboard("055150000000");
+
+const geo = await client.warnings.geojson(alerts[0]!.id); // raw bytes
+await import("node:fs/promises").then((fs) => fs.writeFile("warn.geojson", geo.data));
+
+try {
+  await client.warnings.get("DOES-NOT-EXIST");
+} catch (err) {
+  if (err instanceof NinaApiError) console.error(err.status, err.detail);
+}
+```
+
+### Client options
+
+```ts
+new NinaClient({
+  baseUrl: "https://warnung.bund.de",
+  timeoutMs: 15_000,
+  maxRetries: 3,              // 429 / 503 are retried with linear backoff
+  maxResponseBytes: 50 << 20, // abort responses larger than 50 MiB (0 = unlimited)
+  userAgent: "my-app/1.0",
+  transport: customTransport, // inject your own HTTP transport
+});
+```
+
+### Resource groups
+
+`client.mapData(source)`, `client.dashboard(ars)`, `client.warnings` (`.get` / `.geojson`),
+`client.archive` (`.mapping` / `.get`), `client.reference` (`.notfalltipps` / `.eventCodes` / `.dataVersion`).
+
+---
+
+## Architecture
+
+```
+src/
+  client/
+    enums.ts     # NinaSource + severity value sets (runtime + type)
+    types.ts     # response interfaces (typed summaries; full warnings as JsonObject)
+    query.ts     # dependency-free query-string builder
+    http.ts      # the Transport interface + default node:http/https transport
+    engine.ts    # URL building, retry/backoff, JSON/raw decoding, error mapping
+    errors.ts    # NinaError / NinaApiError / NinaNetworkError / NinaParseError
+    client.ts    # NinaClient — resource groups over the engine
+  cli/
+    io.ts        # injectable I/O seam (stdout/stderr/file)
+    shared.ts    # option parsers, global-option resolver, JSON/raw renderers
+    commands/    # warnings + archive/reference (misc) command groups
+    program.ts   # assembles the commander program from injectable deps
+    run.ts       # parses argv -> exit code (no process.exit; testable)
+    index.ts     # #! bin shim
+```
+
+**Design notes**
+
+- The HTTP layer is a single `Transport` function (`(req) => Promise<HttpResponse>`). The default
+  uses `node:http`/`node:https`; tests inject a mock. This keeps the client free of any HTTP framework.
+- The CLI is built around injectable `CliDeps` (client factory + I/O), so the whole program can be
+  driven in-process by tests with a mocked client and captured output — no subprocesses.
+- Full CAP warning payloads are deeply nested and standard-specific, so they are returned as
+  faithful raw `JsonObject`s rather than partially-guessed types.
+- The transport issues exactly one request and **does not follow 3xx redirects** — a redirect is
+  surfaced as a `NinaApiError` like any other non-2xx status. This avoids replaying headers to a
+  redirect target (no cross-host header leak / SSRF via `Location`).
+
+---
+
+## Testing
+
+```bash
+npm test          # builds, then runs `node --test` over dist/test
+```
+
+- **`query.test.ts`** — query-string serialisation.
+- **`http.test.ts`** — the default transport against a real loopback `http.createServer` (GET, unsupported protocol, size cap, timeout, no-redirect-follow).
+- **`engine.test.ts`** — URL building, JSON/raw decoding, error mapping, 429/503 retry, redirect-as-error, size-cap forwarding — mocked transport.
+- **`client.test.ts`** — every endpoint's method/URL mapping, including identifier URL-encoding — mocked transport.
+- **`cli.test.ts`** — end-to-end command parsing, rendering, file output and exit codes, plus negative paths (network/parse/API errors, write failures, content-type warning) — mocked client.
+- **`shared.test.ts`** — the `parseIntArg` value parser (accepts plain decimals, rejects everything else).
+
+## Continuous integration
+
+GitHub Actions workflows under `.github/workflows/`:
+
+- **ci.yml** — type-check, build and test on Node 20/22/24 for every push and PR.
+- **release.yml** — on a `v*` tag: verify the tag matches `package.json`, test, `npm pack`, and create a GitHub Release with the tarball.
+- **publish.yml** — manual dispatch: publish to npm via OIDC **Trusted Publishing** (no stored `NPM_TOKEN`) with provenance.
+- **docs.yml** — build TypeDoc API docs and deploy to GitHub Pages on each `v*` tag.
+
+## License
+
+**Dual-licensed** — use it under **either**:
+
+- **[AGPL-3.0-or-later](LICENSE)** (default, free). Note the AGPL's §13 network
+  clause: if you run a modified version as a network service, you must offer that
+  modified source to the service's users.
+- **Commercial license** (paid), for closed-source / proprietary or SaaS use
+  without the AGPL's obligations.
+
+See **[LICENSING.md](LICENSING.md)** for details, and **[CONTRIBUTING.md](CONTRIBUTING.md)**
+for the contribution policy (this project does not accept external code
+contributions). Commercial enquiries: **sebs@2xs.org**.

package/dist/src/cli/commands/misc.d.ts

@@ -0,0 +1,4 @@
+import type { Command } from "commander";
+import type { CliDeps } from "../io.js";
+export declare function registerMiscCommands(program: Command, deps: CliDeps): void;
+//# sourceMappingURL=misc.d.ts.map

package/dist/src/cli/commands/misc.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"misc.d.ts","sourceRoot":"","sources":["../../../../src/cli/commands/misc.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AAGxC,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,GAAG,IAAI,CAiD1E"}

package/dist/src/cli/commands/misc.js

@@ -0,0 +1,36 @@
+import { action, renderJson, requireIdentifier } from "../shared.js";
+export function registerMiscCommands(program, deps) {
+    const archive = program.command("archive").description("MoWaS archive (historical warnings)");
+    archive
+        .command("mapping <identifier>")
+        .description("Revision history for an archived MoWaS identifier")
+        .action(action(deps, async ({ client, global }, [id]) => {
+        renderJson(deps, global, await client.archive.mapping(requireIdentifier(id, "identifier")));
+    }));
+    archive
+        .command("get <identifier>")
+        .description("A specific archived MoWaS warning")
+        .action(action(deps, async ({ client, global }, [id]) => {
+        renderJson(deps, global, await client.archive.get(requireIdentifier(id, "identifier")));
+    }));
+    const reference = program.command("reference").description("Static reference data");
+    reference
+        .command("notfalltipps")
+        .description("Emergency-preparedness tips (German)")
+        .action(action(deps, async ({ client, global }) => {
+        renderJson(deps, global, await client.reference.notfalltipps());
+    }));
+    reference
+        .command("event-codes")
+        .description("The CAP event-code catalogue")
+        .action(action(deps, async ({ client, global }) => {
+        renderJson(deps, global, await client.reference.eventCodes());
+    }));
+    reference
+        .command("data-version")
+        .description("Current data version/hash (useful for change detection)")
+        .action(action(deps, async ({ client, global }) => {
+        renderJson(deps, global, await client.reference.dataVersion());
+    }));
+}
+//# sourceMappingURL=misc.js.map

package/dist/src/cli/commands/misc.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"misc.js","sourceRoot":"","sources":["../../../../src/cli/commands/misc.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAErE,MAAM,UAAU,oBAAoB,CAAC,OAAgB,EAAE,IAAa;IAClE,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,WAAW,CAAC,qCAAqC,CAAC,CAAC;IAE9F,OAAO;SACJ,OAAO,CAAC,sBAAsB,CAAC;SAC/B,WAAW,CAAC,mDAAmD,CAAC;SAChE,MAAM,CACL,MAAM,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE;QAC9C,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,iBAAiB,CAAC,EAAG,EAAE,YAAY,CAAC,CAAC,CAAC,CAAC;IAC/F,CAAC,CAAC,CACH,CAAC;IAEJ,OAAO;SACJ,OAAO,CAAC,kBAAkB,CAAC;SAC3B,WAAW,CAAC,mCAAmC,CAAC;SAChD,MAAM,CACL,MAAM,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE;QAC9C,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,iBAAiB,CAAC,EAAG,EAAE,YAAY,CAAC,CAAC,CAAC,CAAC;IAC3F,CAAC,CAAC,CACH,CAAC;IAEJ,MAAM,SAAS,GAAG,OAAO,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC,WAAW,CAAC,uBAAuB,CAAC,CAAC;IAEpF,SAAS;SACN,OAAO,CAAC,cAAc,CAAC;SACvB,WAAW,CAAC,sCAAsC,CAAC;SACnD,MAAM,CACL,MAAM,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE,EAAE;QACxC,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,MAAM,CAAC,SAAS,CAAC,YAAY,EAAE,CAAC,CAAC;IAClE,CAAC,CAAC,CACH,CAAC;IAEJ,SAAS;SACN,OAAO,CAAC,aAAa,CAAC;SACtB,WAAW,CAAC,8BAA8B,CAAC;SAC3C,MAAM,CACL,MAAM,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE,EAAE;QACxC,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,MAAM,CAAC,SAAS,CAAC,UAAU,EAAE,CAAC,CAAC;IAChE,CAAC,CAAC,CACH,CAAC;IAEJ,SAAS;SACN,OAAO,CAAC,cAAc,CAAC;SACvB,WAAW,CAAC,yDAAyD,CAAC;SACtE,MAAM,CACL,MAAM,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE,EAAE;QACxC,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,MAAM,CAAC,SAAS,CAAC,WAAW,EAAE,CAAC,CAAC;IACjE,CAAC,CAAC,CACH,CAAC;AACN,CAAC"}

package/dist/src/cli/commands/warnings.d.ts

@@ -0,0 +1,4 @@
+import type { Command } from "commander";
+import type { CliDeps } from "../io.js";
+export declare function registerWarningCommands(program: Command, deps: CliDeps): void;
+//# sourceMappingURL=warnings.d.ts.map

package/dist/src/cli/commands/warnings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"warnings.d.ts","sourceRoot":"","sources":["../../../../src/cli/commands/warnings.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AAIxC,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,GAAG,IAAI,CAiD7E"}

package/dist/src/cli/commands/warnings.js

@@ -0,0 +1,38 @@
+import { action, assertEnum, renderJson, renderRaw, requireIdentifier } from "../shared.js";
+import { NinaSourceValues } from "../../client/enums.js";
+export function registerWarningCommands(program, deps) {
+    program
+        .command("sources")
+        .description("List the valid warning sources")
+        .action(action(deps, async ({ global }) => {
+        renderJson(deps, global, [...NinaSourceValues]);
+    }));
+    program
+        .command("map-data <source>")
+        .description(`Current warnings from a source (${NinaSourceValues.join(" | ")})`)
+        .action(action(deps, async ({ client, global }, [source]) => {
+        const s = assertEnum(source, NinaSourceValues, "source");
+        renderJson(deps, global, await client.mapData(s));
+    }));
+    const warning = program.command("warning").description("A single warning by identifier");
+    warning
+        .command("get <identifier>")
+        .description("Get the full CAP warning for an identifier")
+        .action(action(deps, async ({ client, global }, [id]) => {
+        renderJson(deps, global, await client.warnings.get(requireIdentifier(id, "identifier")));
+    }));
+    warning
+        .command("geojson <identifier>")
+        .description("Download the warning's geometry as GeoJSON (-o to write a file)")
+        .action(action(deps, async ({ client, global }, [id]) => {
+        const geojson = await client.warnings.geojson(requireIdentifier(id, "identifier"));
+        renderRaw(deps, global, geojson, "json");
+    }));
+    program
+        .command("dashboard <ars>")
+        .description("Warnings affecting a region (Amtlicher Regionalschlüssel / AGS)")
+        .action(action(deps, async ({ client, global }, [ars]) => {
+        renderJson(deps, global, await client.dashboard(requireIdentifier(ars, "region key")));
+    }));
+}
+//# sourceMappingURL=warnings.js.map

package/dist/src/cli/commands/warnings.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"warnings.js","sourceRoot":"","sources":["../../../../src/cli/commands/warnings.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,UAAU,EAAE,SAAS,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAC5F,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAEzD,MAAM,UAAU,uBAAuB,CAAC,OAAgB,EAAE,IAAa;IACrE,OAAO;SACJ,OAAO,CAAC,SAAS,CAAC;SAClB,WAAW,CAAC,gCAAgC,CAAC;SAC7C,MAAM,CACL,MAAM,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE;QAChC,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,CAAC,GAAG,gBAAgB,CAAC,CAAC,CAAC;IAClD,CAAC,CAAC,CACH,CAAC;IAEJ,OAAO;SACJ,OAAO,CAAC,mBAAmB,CAAC;SAC5B,WAAW,CAAC,mCAAmC,gBAAgB,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC;SAC/E,MAAM,CACL,MAAM,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,EAAE,EAAE;QAClD,MAAM,CAAC,GAAG,UAAU,CAAC,MAAO,EAAE,gBAAgB,EAAE,QAAQ,CAAC,CAAC;QAC1D,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC;IACpD,CAAC,CAAC,CACH,CAAC;IAEJ,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,WAAW,CAAC,gCAAgC,CAAC,CAAC;IAEzF,OAAO;SACJ,OAAO,CAAC,kBAAkB,CAAC;SAC3B,WAAW,CAAC,4CAA4C,CAAC;SACzD,MAAM,CACL,MAAM,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE;QAC9C,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,iBAAiB,CAAC,EAAG,EAAE,YAAY,CAAC,CAAC,CAAC,CAAC;IAC5F,CAAC,CAAC,CACH,CAAC;IAEJ,OAAO;SACJ,OAAO,CAAC,sBAAsB,CAAC;SAC/B,WAAW,CAAC,iEAAiE,CAAC;SAC9E,MAAM,CACL,MAAM,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE;QAC9C,MAAM,OAAO,GAAG,MAAM,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,iBAAiB,CAAC,EAAG,EAAE,YAAY,CAAC,CAAC,CAAC;QACpF,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;IAC3C,CAAC,CAAC,CACH,CAAC;IAEJ,OAAO;SACJ,OAAO,CAAC,iBAAiB,CAAC;SAC1B,WAAW,CAAC,iEAAiE,CAAC;SAC9E,MAAM,CACL,MAAM,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE,CAAC,GAAG,CAAC,EAAE,EAAE;QAC/C,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,MAAM,CAAC,SAAS,CAAC,iBAAiB,CAAC,GAAI,EAAE,YAAY,CAAC,CAAC,CAAC,CAAC;IAC1F,CAAC,CAAC,CACH,CAAC;AACN,CAAC"}

package/dist/src/cli/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/src/cli/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/cli/index.ts"],"names":[],"mappings":""}

package/dist/src/cli/index.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+// Binary entry point. Thin shim around run(); all logic lives in run.ts/program.ts.
+import { run } from "./run.js";
+const exitCode = await run(process.argv.slice(2));
+process.exitCode = exitCode;
+//# sourceMappingURL=index.js.map

package/dist/src/cli/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/cli/index.ts"],"names":[],"mappings":";AACA,oFAAoF;AAEpF,OAAO,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC;AAE/B,MAAM,QAAQ,GAAG,MAAM,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;AAClD,OAAO,CAAC,QAAQ,GAAG,QAAQ,CAAC"}

package/dist/src/cli/io.d.ts

@@ -0,0 +1,17 @@
+import type { NinaClient } from "../client/client.js";
+import type { EngineOptions } from "../client/engine.js";
+export interface CliIO {
+    out(text: string): void;
+    err(text: string): void;
+    /** Persist raw bytes to a file. */
+    writeFile(path: string, data: Buffer): void;
+    /** Write raw bytes to stdout (binary-safe). */
+    outBinary(data: Buffer): void;
+}
+export interface CliDeps {
+    io: CliIO;
+    /** Build a client from the resolved global options (injectable for tests). */
+    createClient(options: EngineOptions): NinaClient;
+}
+export declare const defaultIO: CliIO;
+//# sourceMappingURL=io.d.ts.map

package/dist/src/cli/io.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"io.d.ts","sourceRoot":"","sources":["../../../src/cli/io.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AACtD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAGzD,MAAM,WAAW,KAAK;IACpB,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,mCAAmC;IACnC,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5C,+CAA+C;IAC/C,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CAC/B;AAED,MAAM,WAAW,OAAO;IACtB,EAAE,EAAE,KAAK,CAAC;IACV,8EAA8E;IAC9E,YAAY,CAAC,OAAO,EAAE,aAAa,GAAG,UAAU,CAAC;CAClD;AAED,eAAO,MAAM,SAAS,EAAE,KAevB,CAAC"}

package/dist/src/cli/io.js

@@ -0,0 +1,22 @@
+// I/O seam for the CLI. Everything the CLI writes goes through a CliIO object so
+// tests can capture output instead of hitting the real stdout/stderr/filesystem.
+import { writeFileSync } from "node:fs";
+import { NinaIOError } from "../client/errors.js";
+export const defaultIO = {
+    out: (text) => process.stdout.write(text + "\n"),
+    err: (text) => process.stderr.write(text + "\n"),
+    writeFile: (path, data) => {
+        // A failed file write (no such dir, EISDIR, EACCES) is a routine,
+        // user-caused condition — classify it as a NinaError so run() prints a clean
+        // "Error: ..." rather than the "Unexpected error:" wording for internal bugs.
+        try {
+            writeFileSync(path, data);
+        }
+        catch (cause) {
+            const reason = cause instanceof Error ? cause.message : String(cause);
+            throw new NinaIOError(`Failed to write ${path}: ${reason}`, { cause });
+        }
+    },
+    outBinary: (data) => process.stdout.write(data),
+};
+//# sourceMappingURL=io.js.map

package/dist/src/cli/io.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"io.js","sourceRoot":"","sources":["../../../src/cli/io.ts"],"names":[],"mappings":"AAAA,iFAAiF;AACjF,iFAAiF;AAEjF,OAAO,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAGxC,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAiBlD,MAAM,CAAC,MAAM,SAAS,GAAU;IAC9B,GAAG,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,GAAG,IAAI,CAAC;IAChD,GAAG,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,GAAG,IAAI,CAAC;IAChD,SAAS,EAAE,CAAC,IAAI,EAAE,IAAI,EAAE,EAAE;QACxB,kEAAkE;QAClE,6EAA6E;QAC7E,8EAA8E;QAC9E,IAAI,CAAC;YACH,aAAa,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;QAC5B,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,MAAM,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YACtE,MAAM,IAAI,WAAW,CAAC,mBAAmB,IAAI,KAAK,MAAM,EAAE,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC;QACzE,CAAC;IACH,CAAC;IACD,SAAS,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC;CAChD,CAAC"}

package/dist/src/cli/program.d.ts

@@ -0,0 +1,7 @@
+import { Command } from "commander";
+import type { CliDeps } from "./io.js";
+export declare const VERSION: string;
+/** Default dependencies: real client + real stdout/stderr/filesystem. */
+export declare const defaultDeps: CliDeps;
+export declare function buildProgram(deps?: CliDeps): Command;
+//# sourceMappingURL=program.d.ts.map

package/dist/src/cli/program.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"program.d.ts","sourceRoot":"","sources":["../../../src/cli/program.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAuBvC,eAAO,MAAM,OAAO,QAAgB,CAAC;AAErC,yEAAyE;AACzE,eAAO,MAAM,WAAW,EAAE,OAGzB,CAAC;AAEF,wBAAgB,YAAY,CAAC,IAAI,GAAE,OAAqB,GAAG,OAAO,CAmCjE"}

package/dist/src/cli/program.js

@@ -0,0 +1,53 @@
+// Assemble the full commander program. The program is built around an injectable
+// CliDeps so the entire CLI can be driven in tests with a mocked client and
+// captured output.
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { Command } from "commander";
+import { defaultIO } from "./io.js";
+import { NinaClient } from "../client/client.js";
+import { parseIntArg } from "./shared.js";
+import { registerWarningCommands } from "./commands/warnings.js";
+import { registerMiscCommands } from "./commands/misc.js";
+/**
+ * Single source of truth for the version: read from package.json at runtime
+ * rather than duplicating a literal that can silently drift after a release bump.
+ * From the compiled location (dist/src/cli/program.js) package.json is three
+ * directories up; the same offset holds for the source under src/cli.
+ */
+function readVersion() {
+    try {
+        const pkgUrl = new URL("../../../package.json", import.meta.url);
+        const pkg = JSON.parse(readFileSync(fileURLToPath(pkgUrl), "utf8"));
+        return pkg.version ?? "0.0.0";
+    }
+    catch {
+        return "0.0.0";
+    }
+}
+export const VERSION = readVersion();
+/** Default dependencies: real client + real stdout/stderr/filesystem. */
+export const defaultDeps = {
+    io: defaultIO,
+    createClient: (options) => new NinaClient(options),
+};
+export function buildProgram(deps = defaultDeps) {
+    const program = new Command();
+    program
+        .name("nina")
+        .description("CLI for the open NINA civil-protection warning API (https://warnung.bund.de) — " +
+        "MoWaS, KATWARN, BIWAPP, DWD severe weather, flood (LHP) and police alerts.")
+        .version(VERSION)
+        .option("--base-url <url>", "API base URL", "https://warnung.bund.de")
+        .option("--timeout <ms>", "per-request timeout in milliseconds (0 disables; waits indefinitely)", parseIntArg)
+        .option("--user-agent <ua>", "User-Agent header value")
+        .option("--max-retries <n>", "retries for transient 429/503 responses (capped at 10)", parseIntArg)
+        .option("--max-response-bytes <n>", "cap response body size in bytes (0 = unlimited; default 100 MiB)", parseIntArg)
+        .option("--compact", "print JSON on a single line instead of pretty-printed")
+        .option("-o, --output <file>", "for downloads: write bytes to this file instead of stdout")
+        .showHelpAfterError();
+    registerWarningCommands(program, deps);
+    registerMiscCommands(program, deps);
+    return program;
+}
+//# sourceMappingURL=program.js.map

package/dist/src/cli/program.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"program.js","sourceRoot":"","sources":["../../../src/cli/program.ts"],"names":[],"mappings":"AAAA,iFAAiF;AACjF,4EAA4E;AAC5E,mBAAmB;AAEnB,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,OAAO,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AACpC,OAAO,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AACjD,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,uBAAuB,EAAE,MAAM,wBAAwB,CAAC;AACjE,OAAO,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAE1D;;;;;GAKG;AACH,SAAS,WAAW;IAClB,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,uBAAuB,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACjE,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,aAAa,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,CAAyB,CAAC;QAC5F,OAAO,GAAG,CAAC,OAAO,IAAI,OAAO,CAAC;IAChC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,OAAO,CAAC;IACjB,CAAC;AACH,CAAC;AAED,MAAM,CAAC,MAAM,OAAO,GAAG,WAAW,EAAE,CAAC;AAErC,yEAAyE;AACzE,MAAM,CAAC,MAAM,WAAW,GAAY;IAClC,EAAE,EAAE,SAAS;IACb,YAAY,EAAE,CAAC,OAAO,EAAE,EAAE,CAAC,IAAI,UAAU,CAAC,OAAO,CAAC;CACnD,CAAC;AAEF,MAAM,UAAU,YAAY,CAAC,OAAgB,WAAW;IACtD,MAAM,OAAO,GAAG,IAAI,OAAO,EAAE,CAAC;IAE9B,OAAO;SACJ,IAAI,CAAC,MAAM,CAAC;SACZ,WAAW,CACV,iFAAiF;QAC/E,4EAA4E,CAC/E;SACA,OAAO,CAAC,OAAO,CAAC;SAChB,MAAM,CAAC,kBAAkB,EAAE,cAAc,EAAE,yBAAyB,CAAC;SACrE,MAAM,CACL,gBAAgB,EAChB,sEAAsE,EACtE,WAAW,CACZ;SACA,MAAM,CAAC,mBAAmB,EAAE,yBAAyB,CAAC;SACtD,MAAM,CACL,mBAAmB,EACnB,wDAAwD,EACxD,WAAW,CACZ;SACA,MAAM,CACL,0BAA0B,EAC1B,kEAAkE,EAClE,WAAW,CACZ;SACA,MAAM,CAAC,WAAW,EAAE,uDAAuD,CAAC;SAC5E,MAAM,CAAC,qBAAqB,EAAE,2DAA2D,CAAC;SAC1F,kBAAkB,EAAE,CAAC;IAExB,uBAAuB,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;IACvC,oBAAoB,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;IAEpC,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/src/cli/run.d.ts

@@ -0,0 +1,3 @@
+import type { CliDeps } from "./io.js";
+export declare function run(argv: string[], deps?: CliDeps): Promise<number>;
+//# sourceMappingURL=run.d.ts.map

package/dist/src/cli/run.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../../../src/cli/run.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAiBvC,wBAAsB,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,IAAI,GAAE,OAAqB,GAAG,OAAO,CAAC,MAAM,CAAC,CAiCtF"}

package/dist/src/cli/run.js

@@ -0,0 +1,56 @@
+// Run the CLI and resolve to a process exit code. Kept separate from the bin
+// shim so tests can call run() directly with injected deps and assert on the
+// captured output and exit code without spawning a subprocess.
+import { CommanderError } from "commander";
+import { buildProgram, defaultDeps } from "./program.js";
+import { NinaApiError, NinaError } from "../client/errors.js";
+/**
+ * Apply exitOverride + output redirection to every command in the tree.
+ * commander does not propagate these to subcommands, so a parse error on a
+ * subcommand would otherwise call process.exit() and bypass our error handling.
+ */
+function configureTree(command, deps) {
+    command.exitOverride();
+    command.configureOutput({
+        writeOut: (str) => deps.io.out(str.replace(/\n$/, "")),
+        writeErr: (str) => deps.io.err(str.replace(/\n$/, "")),
+    });
+    for (const child of command.commands)
+        configureTree(child, deps);
+}
+export async function run(argv, deps = defaultDeps) {
+    const program = buildProgram(deps);
+    configureTree(program, deps);
+    try {
+        await program.parseAsync(argv, { from: "user" });
+        return 0;
+    }
+    catch (err) {
+        if (err instanceof CommanderError) {
+            // When commander has displayed help — whether from an explicit --help
+            // (code "commander.helpDisplayed", exitCode 0) or from a bare invocation /
+            // bare command group with no subcommand (code "commander.help", exitCode 1)
+            // — the visible output is the same successful help text, so exit 0 in both
+            // cases for a consistent "showed help" result. Genuine parse errors
+            // (unknown command/option, missing argument) keep their own non-zero code.
+            if (err.code === "commander.help" || err.code === "commander.helpDisplayed") {
+                return 0;
+            }
+            return err.exitCode;
+        }
+        if (err instanceof NinaApiError) {
+            deps.io.err(`Error: ${err.message}`);
+            // Map a few notable statuses to distinct exit codes for scripting.
+            if (err.status === 404)
+                return 4;
+            return 1;
+        }
+        if (err instanceof NinaError) {
+            deps.io.err(`Error: ${err.message}`);
+            return 1;
+        }
+        deps.io.err(`Unexpected error: ${err instanceof Error ? err.message : String(err)}`);
+        return 1;
+    }
+}
+//# sourceMappingURL=run.js.map

package/dist/src/cli/run.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run.js","sourceRoot":"","sources":["../../../src/cli/run.ts"],"names":[],"mappings":"AAAA,6EAA6E;AAC7E,6EAA6E;AAC7E,+DAA+D;AAE/D,OAAO,EAAE,cAAc,EAAgB,MAAM,WAAW,CAAC;AACzD,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAEzD,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAE9D;;;;GAIG;AACH,SAAS,aAAa,CAAC,OAAgB,EAAE,IAAa;IACpD,OAAO,CAAC,YAAY,EAAE,CAAC;IACvB,OAAO,CAAC,eAAe,CAAC;QACtB,QAAQ,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;QACtD,QAAQ,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;KACvD,CAAC,CAAC;IACH,KAAK,MAAM,KAAK,IAAI,OAAO,CAAC,QAAQ;QAAE,aAAa,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;AACnE,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,GAAG,CAAC,IAAc,EAAE,OAAgB,WAAW;IACnE,MAAM,OAAO,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC;IACnC,aAAa,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;IAE7B,IAAI,CAAC;QACH,MAAM,OAAO,CAAC,UAAU,CAAC,IAAI,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC;QACjD,OAAO,CAAC,CAAC;IACX,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAI,GAAG,YAAY,cAAc,EAAE,CAAC;YAClC,sEAAsE;YACtE,2EAA2E;YAC3E,4EAA4E;YAC5E,2EAA2E;YAC3E,oEAAoE;YACpE,2EAA2E;YAC3E,IAAI,GAAG,CAAC,IAAI,KAAK,gBAAgB,IAAI,GAAG,CAAC,IAAI,KAAK,yBAAyB,EAAE,CAAC;gBAC5E,OAAO,CAAC,CAAC;YACX,CAAC;YACD,OAAO,GAAG,CAAC,QAAQ,CAAC;QACtB,CAAC;QACD,IAAI,GAAG,YAAY,YAAY,EAAE,CAAC;YAChC,IAAI,CAAC,EAAE,CAAC,GAAG,CAAC,UAAU,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC;YACrC,mEAAmE;YACnE,IAAI,GAAG,CAAC,MAAM,KAAK,GAAG;gBAAE,OAAO,CAAC,CAAC;YACjC,OAAO,CAAC,CAAC;QACX,CAAC;QACD,IAAI,GAAG,YAAY,SAAS,EAAE,CAAC;YAC7B,IAAI,CAAC,EAAE,CAAC,GAAG,CAAC,UAAU,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC;YACrC,OAAO,CAAC,CAAC;QACX,CAAC;QACD,IAAI,CAAC,EAAE,CAAC,GAAG,CAAC,qBAAqB,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACrF,OAAO,CAAC,CAAC;IACX,CAAC;AACH,CAAC"}