@maschinenlesbar.org/mudab-cli 0.0.1

package/LICENSING.md

@@ -0,0 +1,47 @@
+# Licensing
+
+`mudab-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 `mudab-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,78 @@
+# mudab-cli
+
+A tiny, dependency-light **TypeScript client + CLI** for the **MUDAB**
+(Meeresumweltdatenbank — the German marine environment database) REST API:
+marine-monitoring data from the coastal Bundesländer and research institutions,
+hosted by the Bundesanstalt für Gewässerkunde (BfG) and surfaced by the
+Umweltbundesamt (UBA). A [bund.dev](https://bund.dev) API.
+
+- **No API key.** The API is open — no auth, no account.
+- **Zero runtime HTTP dependencies.** Built on `node:http`/`https`; the CLI's only
+  runtime dependency is `commander`.
+- **Library + CLI.** Use the typed `MudabClient` in code, or the `mudab` command.
+
+> **We provide the tool, not the data.** The data is © its providers (see
+> [DATA_LICENSE.md](DATA_LICENSE.md)); its terms are **not** stated as open — check
+> before redistributing.
+
+## Install
+
+```bash
+npm install -g @maschinenlesbar.org/mudab-cli   # the `mudab` command
+# or as a library:
+npm install @maschinenlesbar.org/mudab-cli
+```
+
+## CLI
+
+Every command lists one dataset. Results are paged with `--from`/`--count`
+(default **100** rows); `--all` fetches the whole table.
+
+```bash
+mudab stations --count 5                      # measurement stations
+mudab project-stations                        # monitoring projects (region, institute)
+mudab parameters --compartment wasser         # water parameters
+mudab measurements --from 0 --count 200       # station measurements (page it — huge)
+mudab plc-stations                            # HELCOM PLC river-load stations
+mudab plc-measurements --all                  # river pollutant loads
+mudab compartments                            # compartment code table (offline)
+```
+
+> **The API does no server-side filtering or sorting.** Its OpenAPI spec advertises
+> `filter`/`orderby` on every endpoint, but the live server **ignores** them, so the
+> CLI does not offer filter flags. Fetch a page and filter with `jq`:
+>
+> ```bash
+> mudab parameters --all --compact | jq '[.[] | select(.COMPT_DS=="CW")]'
+> ```
+
+Global flags: `--base-url`, `--timeout`, `--user-agent`, `--max-retries`,
+`--max-response-bytes`, `--compact`. See [Usage.md](Usage.md) for the full reference.
+
+## Library
+
+```ts
+import { MudabClient } from "@maschinenlesbar.org/mudab-cli";
+
+const mudab = new MudabClient();
+const stations = await mudab.stations({ range: { from: 0, count: 10 } });
+const waterParams = await mudab.parameters({ range: { from: 0, count: 50 } }, "wasser");
+```
+
+Each method returns a typed row array (the client extracts it from the API's
+single-key wrapper object). Only `range` is honoured by the server — see the note in
+`FilterRequest`.
+
+## Documentation
+
+- [Usage.md](Usage.md) — full command reference and exit codes
+- [DEVELOPING.md](DEVELOPING.md) — architecture, testing, the live-API quirks
+- [GLOSSARY.md](GLOSSARY.md) — MUDAB domain terms (stations, compartments, PLC)
+- [DATA_LICENSE.md](DATA_LICENSE.md) — upstream data terms (distinct from the code license)
+- [SKILLS.md](SKILLS.md) — the Claude Code skills this repo ships
+
+## Licence
+
+Code is dual-licensed **AGPL-3.0-or-later OR commercial** — see
+[LICENSING.md](LICENSING.md). No external code contributions are accepted (see
+[CONTRIBUTING.md](CONTRIBUTING.md)); bug reports and AGPL forks are welcome.

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

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"list.d.ts","sourceRoot":"","sources":["../../../../src/cli/commands/list.ts"],"names":[],"mappings":"AAKA,OAAO,EAAU,KAAK,OAAO,EAAE,MAAM,WAAW,CAAC;AACjD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AAkDxC,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,GAAG,IAAI,CAmCtE"}

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

@@ -0,0 +1,70 @@
+// Command group for the MUDAB CLI: one list command per endpoint (stations,
+// parameters, measurements, and the HELCOM PLC set), plus an offline
+// `compartments` code table. Every list command shares the range/filter/orderby
+// options and returns the endpoint's row array as JSON.
+import { Option } from "commander";
+import { action, addListOptions, buildFilterRequest, renderJson } from "../shared.js";
+const LIST_COMMANDS = [
+    { name: "stations", desc: "List measurement stations (STATION_SMALL)", run: (c, r) => c.stations(r) },
+    {
+        name: "project-stations",
+        desc: "List project stations (PROJECTSTATION_SMALL)",
+        run: (c, r) => c.projectStations(r),
+    },
+    {
+        name: "measurements",
+        desc: "List individual station measurements (MV_STATION_MSMNT) — a very large table",
+        run: (c, r) => c.measurements(r),
+    },
+    {
+        name: "plc-stations",
+        desc: "List HELCOM PLC stations (V_PLC_STATION)",
+        run: (c, r) => c.plcStations(r),
+    },
+    {
+        name: "plc-parameters",
+        desc: "List parameters measured at PLC stations (V_GEMESSENE_PARA_PLC)",
+        run: (c, r) => c.plcParameters(r),
+    },
+    {
+        name: "plc-measurements",
+        desc: "List measured values at PLC stations (V_MESSWERTE_PLC)",
+        run: (c, r) => c.plcMeasurements(r),
+    },
+];
+const PARAMETER_COMPARTMENTS = ["biologie", "biota", "wasser", "sediment"];
+/**
+ * The compartment (COMPT_DS) code table, verified live. NOTE: this is NOT
+ * exhaustive — the API also returns codes outside the documented set (e.g. `MM`).
+ */
+const COMPARTMENTS = [
+    { code: "CW", label: "Wasser (water)", parameterCompartment: "wasser" },
+    { code: "CS", label: "Sediment", parameterCompartment: "sediment" },
+    { code: "CF", label: "Biota", parameterCompartment: "biota" },
+    { code: "BL", label: "Biologie (biology)", parameterCompartment: "biologie" },
+];
+export function registerCommands(program, deps) {
+    for (const sub of LIST_COMMANDS) {
+        const cmd = program.command(sub.name).description(sub.desc);
+        addListOptions(cmd).action(action(deps, async ({ client, global, opts }) => {
+            renderJson(deps, global, await sub.run(client, buildFilterRequest(opts)));
+        }));
+    }
+    // `parameters` also offers the compartment-specific endpoints via --compartment.
+    const params = program
+        .command("parameters")
+        .description("List measured parameters (MV_PARAMETER)")
+        .addOption(new Option("--compartment <c>", "restrict to a compartment's parameter endpoint").choices(PARAMETER_COMPARTMENTS));
+    addListOptions(params).action(action(deps, async ({ client, global, opts }) => {
+        const compartment = opts["compartment"];
+        const req = buildFilterRequest(opts);
+        renderJson(deps, global, await client.parameters(req, compartment));
+    }));
+    program
+        .command("compartments")
+        .description("Print the compartment (COMPT_DS) code table — works offline, no request")
+        .action(action(deps, async ({ global }) => {
+        renderJson(deps, global, COMPARTMENTS);
+    }));
+}
+//# sourceMappingURL=list.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"list.js","sourceRoot":"","sources":["../../../../src/cli/commands/list.ts"],"names":[],"mappings":"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"}

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,11 @@
+#!/usr/bin/env node
+// Bin shim: parse argv, run the CLI, and set the process exit code. All real
+// logic lives in run.ts (testable without spawning a subprocess).
+import { run } from "./run.js";
+run(process.argv.slice(2)).then((code) => {
+    process.exitCode = code;
+}, (err) => {
+    process.stderr.write(`Unexpected error: ${err instanceof Error ? err.message : String(err)}\n`);
+    process.exitCode = 1;
+});
+//# 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,6EAA6E;AAC7E,kEAAkE;AAElE,OAAO,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC;AAE/B,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAC7B,CAAC,IAAI,EAAE,EAAE;IACP,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC;AAC1B,CAAC,EACD,CAAC,GAAY,EAAE,EAAE;IACf,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,qBAAqB,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAChG,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;AACvB,CAAC,CACF,CAAC"}

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

@@ -0,0 +1,12 @@
+import type { MudabClient, MudabClientOptions } from "../client/client.js";
+export interface CliIO {
+    out(text: string): void;
+    err(text: string): void;
+}
+export interface CliDeps {
+    io: CliIO;
+    /** Build a client from the resolved global options (injectable for tests). */
+    createClient(options: MudabClientOptions): MudabClient;
+}
+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":"AAGA,OAAO,KAAK,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAE3E,MAAM,WAAW,KAAK;IACpB,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CACzB;AAED,MAAM,WAAW,OAAO;IACtB,EAAE,EAAE,KAAK,CAAC;IACV,8EAA8E;IAC9E,YAAY,CAAC,OAAO,EAAE,kBAAkB,GAAG,WAAW,CAAC;CACxD;AAED,eAAO,MAAM,SAAS,EAAE,KAGvB,CAAC"}

package/dist/src/cli/io.js

@@ -0,0 +1,7 @@
+// 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.
+export const defaultIO = {
+    out: (text) => process.stdout.write(text + "\n"),
+    err: (text) => process.stderr.write(text + "\n"),
+};
+//# 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,sEAAsE;AAetE,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;CACjD,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. */
+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;AAsBvC,eAAO,MAAM,OAAO,QAAgB,CAAC;AAErC,8DAA8D;AAC9D,eAAO,MAAM,WAAW,EAAE,OAGzB,CAAC;AAEF,wBAAgB,YAAY,CAAC,IAAI,GAAE,OAAqB,GAAG,OAAO,CAkCjE"}

package/dist/src/cli/program.js

@@ -0,0 +1,54 @@
+// 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 { MudabClient } from "../client/client.js";
+import { parseIntArg, parseBoundedInt, parseHeaderValue, parseNonEmpty } from "./shared.js";
+import { registerCommands } from "./commands/list.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. */
+export const defaultDeps = {
+    io: defaultIO,
+    createClient: (options) => new MudabClient(options),
+};
+export function buildProgram(deps = defaultDeps) {
+    const program = new Command();
+    program
+        .name("mudab")
+        .description("CLI for the MUDAB (Meeresumweltdatenbank) API — marine-monitoring data from " +
+        "the German coastal Bundesländer and research institutions, hosted by the " +
+        "Bundesanstalt für Gewässerkunde (geoportal.bafg.de). No API key needed. " +
+        "Each command lists one dataset, paged with --from/--count (default 100 rows; " +
+        "--all fetches everything). NOTE: the API ignores server-side filtering/sorting, " +
+        "so filter with jq on the --compact output.")
+        .version(VERSION)
+        .option("--base-url <url>", "API base URL", parseNonEmpty, "https://geoportal.bafg.de/mudab/rest/BaseController/FilterElements")
+        .option("--timeout <ms>", "per-request timeout in ms (0 = no timeout)", parseIntArg)
+        .option("--user-agent <ua>", "User-Agent header value", parseHeaderValue)
+        .option("--max-retries <n>", "retries for transient 429/503 responses (0..10)", parseBoundedInt(0, 10))
+        .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")
+        .showHelpAfterError();
+    registerCommands(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,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAClD,OAAO,EAAE,WAAW,EAAE,eAAe,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5F,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAEtD;;;;;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,8DAA8D;AAC9D,MAAM,CAAC,MAAM,WAAW,GAAY;IAClC,EAAE,EAAE,SAAS;IACb,YAAY,EAAE,CAAC,OAAO,EAAE,EAAE,CAAC,IAAI,WAAW,CAAC,OAAO,CAAC;CACpD,CAAC;AAEF,MAAM,UAAU,YAAY,CAAC,OAAgB,WAAW;IACtD,MAAM,OAAO,GAAG,IAAI,OAAO,EAAE,CAAC;IAE9B,OAAO;SACJ,IAAI,CAAC,OAAO,CAAC;SACb,WAAW,CACV,8EAA8E;QAC5E,2EAA2E;QAC3E,0EAA0E;QAC1E,+EAA+E;QAC/E,kFAAkF;QAClF,4CAA4C,CAC/C;SACA,OAAO,CAAC,OAAO,CAAC;SAChB,MAAM,CACL,kBAAkB,EAClB,cAAc,EACd,aAAa,EACb,oEAAoE,CACrE;SACA,MAAM,CAAC,gBAAgB,EAAE,4CAA4C,EAAE,WAAW,CAAC;SACnF,MAAM,CAAC,mBAAmB,EAAE,yBAAyB,EAAE,gBAAgB,CAAC;SACxE,MAAM,CAAC,mBAAmB,EAAE,iDAAiD,EAAE,eAAe,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;SACtG,MAAM,CACL,0BAA0B,EAC1B,kEAAkE,EAClE,WAAW,CACZ;SACA,MAAM,CAAC,WAAW,EAAE,uDAAuD,CAAC;SAC5E,kBAAkB,EAAE,CAAC;IAExB,gBAAgB,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;IAEhC,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;AAqCvC,wBAAsB,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,IAAI,GAAE,OAAqB,GAAG,OAAO,CAAC,MAAM,CAAC,CAoDtF"}

package/dist/src/cli/run.js

@@ -0,0 +1,87 @@
+// 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 { MudabApiError, MudabError, MudabNetworkError, MudabValidationError, } from "../client/errors.js";
+/**
+ * Process exit codes. Distinct codes let scripts tell apart a usage error, a
+ * missing resource, a transport failure, and a catch-all.
+ */
+const EXIT = {
+    /** Usage / parse / client-side validation error. */
+    USAGE: 2,
+    /** 404 — resource not found. */
+    NOT_FOUND: 4,
+    /** Network / transport failure (DNS, connection, timeout, size-cap). */
+    NETWORK: 6,
+    /** Any other error. */
+    OTHER: 1,
+};
+/**
+ * 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);
+    // A bare invocation (no command) is a help request, not an error: print help
+    // to stdout and exit 0, matching `--help`.
+    if (argv.length === 0) {
+        deps.io.out(program.helpInformation().replace(/\n$/, ""));
+        return 0;
+    }
+    try {
+        await program.parseAsync(argv, { from: "user" });
+        return 0;
+    }
+    catch (err) {
+        if (err instanceof CommanderError) {
+            // Help/version requests exit 0; every genuine usage/parse error maps to a
+            // single USAGE code (commander's own exitCode is 1, indistinguishable from
+            // the catch-all).
+            return err.exitCode === 0 ? 0 : EXIT.USAGE;
+        }
+        // Client-side validation (e.g. --all combined with --from/--count) — a usage error.
+        if (err instanceof MudabValidationError) {
+            deps.io.err(`Error: ${err.message}`);
+            return EXIT.USAGE;
+        }
+        if (err instanceof MudabApiError) {
+            deps.io.err(`Error: ${err.message}`);
+            if (err.status === 404)
+                return EXIT.NOT_FOUND;
+            // A 3xx means the base URL redirected (e.g. the legacy MUDABAnwendung path).
+            // The canonical host answers directly, so this is a base-URL misconfiguration
+            // — a usage error, not a generic API failure.
+            if (err.status >= 300 && err.status < 400)
+                return EXIT.USAGE;
+            return EXIT.OTHER;
+        }
+        if (err instanceof MudabNetworkError) {
+            deps.io.err(`Error: ${err.message}`);
+            if (/maxResponseBytes/.test(err.message)) {
+                deps.io.err("Hint: the response exceeded the size cap. Narrow with --from/--count " +
+                    "or raise --max-response-bytes <n> (0 = unlimited).");
+            }
+            return EXIT.NETWORK;
+        }
+        if (err instanceof MudabError) {
+            deps.io.err(`Error: ${err.message}`);
+            return EXIT.OTHER;
+        }
+        deps.io.err(`Unexpected error: ${err instanceof Error ? err.message : String(err)}`);
+        return EXIT.OTHER;
+    }
+}
+//# 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":"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"}

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

@@ -0,0 +1,79 @@
+import type { Command } from "commander";
+import type { CliDeps } from "./io.js";
+import type { MudabClientOptions } from "../client/client.js";
+import type { FilterRequest } from "../client/types.js";
+/** Default `range.count` — MUDAB returns the WHOLE table when no range is sent. */
+export declare const DEFAULT_COUNT = 100;
+/**
+ * commander value-parser: a plain base-10 non-negative integer.
+ *
+ * Uses a strict regex rather than `Number()` coercion, which would otherwise
+ * accept empty/whitespace strings (`Number("") === 0`), hex/binary/scientific
+ * literals (`0x10`, `0b10`, `1e3`), signs, padding and decimals.
+ */
+export declare function parseIntArg(value: string): number;
+/** commander value-parser: a non-empty (after trimming) string. */
+export declare function parseNonEmpty(value: string): string;
+/** Build a commander value-parser for an integer constrained to [min, max]. */
+export declare function parseBoundedInt(min: number, max: number): (value: string) => number;
+/**
+ * commander value-parser for a value that ends up in an HTTP header (User-Agent).
+ * Rejects control characters — a CR/LF (or other C0/DEL byte) would otherwise
+ * reach Node's HTTP layer and throw an opaque `ERR_INVALID_CHAR`, which escapes
+ * typed-error handling and surfaces as an ugly "Unexpected error". Tab (0x09) is
+ * allowed; checked by char code so the source stays free of control bytes.
+ */
+export declare function parseHeaderValue(value: string): string;
+export interface GlobalOptions {
+    baseUrl?: string;
+    timeout?: number;
+    userAgent?: string;
+    maxRetries?: number;
+    maxResponseBytes?: number;
+    compact?: boolean;
+}
+/**
+ * Options shared by every list command. Only paging (range) is offered: the API's
+ * OpenAPI spec advertises `filter` and `orderby` on every endpoint, but the live
+ * server silently ignores both (verified — a filter that should match nothing
+ * still returns the full page), so exposing them would be a filter that doesn't
+ * filter. Filter/sort client-side instead (e.g. pipe `--compact` output to `jq`).
+ */
+export interface ListOptions {
+    from?: number;
+    count?: number;
+    all?: boolean;
+}
+/** Translate resolved global CLI options into client options. */
+export declare function toEngineOptions(global: GlobalOptions): MudabClientOptions;
+/**
+ * Add the shared list options (range / filter / orderby) to a command.
+ * Kept in one place so every list command exposes an identical surface.
+ */
+export declare function addListOptions(cmd: Command): Command;
+/**
+ * Build the request body from parsed list options — a `range` (paging) only.
+ *
+ * `range` is omitted entirely with `--all`; otherwise `count` defaults to
+ * {@link DEFAULT_COUNT} so a bare command never dumps a whole table, and `from`
+ * defaults to 0 (the server answers a count-only range with an HTTP 500).
+ */
+export declare function buildFilterRequest(opts: ListOptions): FilterRequest;
+/** Render a JSON value to stdout, pretty by default, compact with --compact. */
+export declare function renderJson(deps: CliDeps, global: GlobalOptions, value: unknown): void;
+export interface ActionContext {
+    client: ReturnType<CliDeps["createClient"]>;
+    global: GlobalOptions;
+    /** This command's own parsed options. */
+    opts: Record<string, unknown>;
+}
+/**
+ * Wrap an async command action with consistent global-option resolution and
+ * client construction. The callback receives a context (client + resolved global
+ * options + this command's options) and the command's positional arguments.
+ *
+ * Commander invokes actions as (arg1, ..., argN, options, command); we slice off
+ * the trailing options object and command instance to recover the positionals.
+ */
+export declare function action(deps: CliDeps, fn: (ctx: ActionContext, positionals: string[]) => Promise<void>): (...args: unknown[]) => Promise<void>;
+//# sourceMappingURL=shared.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"shared.d.ts","sourceRoot":"","sources":["../../../src/cli/shared.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEzC,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAE9D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAExD,mFAAmF;AACnF,eAAO,MAAM,aAAa,MAAM,CAAC;AAEjC;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CASjD;AAED,mEAAmE;AACnE,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAKnD;AAED,+EAA+E;AAC/E,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAOnF;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAQtD;AAED,MAAM,WAAW,aAAa;IAC5B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,WAAW;IAC1B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,GAAG,CAAC,EAAE,OAAO,CAAC;CACf;AAED,iEAAiE;AACjE,wBAAgB,eAAe,CAAC,MAAM,EAAE,aAAa,GAAG,kBAAkB,CAQzE;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAQpD;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,WAAW,GAAG,aAAa,CAQnE;AAED,gFAAgF;AAChF,wBAAgB,UAAU,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,aAAa,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI,CAGrF;AAED,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,UAAU,CAAC,OAAO,CAAC,cAAc,CAAC,CAAC,CAAC;IAC5C,MAAM,EAAE,aAAa,CAAC;IACtB,yCAAyC;IACzC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC/B;AAED;;;;;;;GAOG;AACH,wBAAgB,MAAM,CACpB,IAAI,EAAE,OAAO,EACb,EAAE,EAAE,CAAC,GAAG,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,EAAE,KAAK,OAAO,CAAC,IAAI,CAAC,GAC/D,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAQvC"}