@maschinenlesbar.org/regionalatlas-cli 0.0.1

package/LICENSING.md

@@ -0,0 +1,47 @@
+# Licensing
+
+`regionalatlas-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 `regionalatlas-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,85 @@
+# regionalatlas-cli
+
+A dependency-light **TypeScript client + CLI** for the **Regionalatlas Deutschland** —
+the regional-statistics indicators of the **Statistische Ämter des Bundes und der
+Länder** (Destatis and the 16 Länder offices), broken down per **Bundesland /
+Regierungsbezirk / Kreis / Gemeinde**. Backed by a public **ArcGIS MapServer** plus a
+static indicator catalogue.
+
+- **No API key.** The regional-statistics data is open.
+- **Zero runtime HTTP dependencies.** Built on `node:http`/`https`; the CLI's only
+  runtime dependency is `commander`.
+- **Library + CLI.** Use the typed `RegionalatlasClient`, or the `regionalatlas` command.
+
+> **We provide the tool, not the data.** The data is © the **Statistische Ämter des
+> Bundes und der Länder** under **Datenlizenz Deutschland – Namensnennung 2.0**
+> (dl-de/by-2.0) — free to use with attribution. See [DATA_LICENSE.md](DATA_LICENSE.md).
+
+## Install
+
+```bash
+npm install -g @maschinenlesbar.org/regionalatlas-cli   # the `regionalatlas` command
+# or as a library:
+npm install @maschinenlesbar.org/regionalatlas-cli
+```
+
+## CLI
+
+```bash
+regionalatlas themes                                             # the 21 subject areas
+regionalatlas indicators --search bevölkerung                    # matching indicators
+regionalatlas indicators --theme Bevölkerung --year 2024         # filter by theme + year
+regionalatlas query AI002-1-5 --level land --year 2020           # 16 Bundesländer rows
+regionalatlas query AI002-1-5 --level kreis                      # ~400 Kreise (latest year)
+regionalatlas query AI002-1-5 --level land --region Bayern       # one region
+regionalatlas query AI002-1-5 --level land --fields ai0201       # project value fields
+```
+
+- **`themes`** lists the subject areas (Themenbereiche) and their indicator counts.
+- **`indicators`** lists the indicators — `code`, short title, year range — with
+  `--theme` / `--year` / `--search` filters.
+- **`query <code>`** fetches the data rows for an indicator at a geo level (`--level`,
+  default `land`), for a year (`--year`, default the indicator's latest). `--region`
+  and `--fields` filter and project **client-side**.
+
+Global flags: `--base-url`, `--catalog-url`, `--timeout`, `--user-agent`,
+`--max-retries`, `--max-response-bytes`, `--compact`. See [Usage.md](Usage.md).
+
+## Library
+
+```ts
+import { RegionalatlasClient } from "@maschinenlesbar.org/regionalatlas-cli";
+
+const c = new RegionalatlasClient();
+await c.themes();                                                 // the subject areas
+await c.indicators({ search: "bevölkerung" });                    // matching indicators
+const rows = await c.query({ indicator: "AI002-1-5", level: "land", year: 2020 });
+```
+
+## Two hosts
+
+Unlike most siblings, this CLI talks to **two** upstreams (documented in
+[DEVELOPING.md](DEVELOPING.md)):
+
+1. the **indicator catalogue** (`services.json` on statistikportal.de), and
+2. the **ArcGIS MapServer** data query on gis-idmz.nrw.de, whose `dynamicLayer`
+   runs a raw SQL join.
+
+Because the data query embeds raw SQL, the indicator, geo level, and year are all
+**validated against the catalogue allowlist before any SQL is built** — a bogus
+indicator never reaches the server. See the injection-guard section in
+[DEVELOPING.md](DEVELOPING.md).
+
+## Documentation
+
+- [Usage.md](Usage.md) — commands, options, the geo levels, exit codes
+- [DEVELOPING.md](DEVELOPING.md) — architecture, the two-host split, the SQL guard
+- [GLOSSARY.md](GLOSSARY.md) — AGS, typ / geo levels, Indikator, table code, precision flags
+- [DATA_LICENSE.md](DATA_LICENSE.md) — the dl-de/by-2.0 data terms
+- [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/regions.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=regions.d.ts.map

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

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

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

@@ -0,0 +1,66 @@
+// Command group for the Regionalatlas CLI:
+//   - `themes`      list the 21 subject areas (title + indicator count)
+//   - `indicators`  list indicators (code, short title, years), with filters
+//   - `query`       fetch data rows for an indicator at a chosen geo level
+import { action, parseFieldList, parseLevel, parseNonEmpty, parseYear, renderJson, } from "../shared.js";
+/** A one-line year range summary (e.g. "2000–2024" or a single year). */
+function yearRange(years) {
+    if (years.length === 0)
+        return "—";
+    const first = years[0];
+    const last = years[years.length - 1];
+    return first === last ? String(first) : `${first}–${last}`;
+}
+export function registerCommands(program, deps) {
+    program
+        .command("themes")
+        .description("List the subject areas (Themenbereiche) with their indicator counts")
+        .action(action(deps, async ({ client, global }) => {
+        renderJson(deps, global, await client.themes());
+    }));
+    program
+        .command("indicators")
+        .description("List indicators (Indikatoren): code, short title, available years")
+        .option("--theme <substr>", "filter by theme title (case-insensitive substring)", parseNonEmpty)
+        .option("--year <yyyy>", "only indicators offering this year", parseYear)
+        .option("--search <substr>", "filter over code + short + long title (case-insensitive)", parseNonEmpty)
+        .action(action(deps, async ({ client, global, opts }) => {
+        const filter = {};
+        if (typeof opts["theme"] === "string")
+            filter.theme = opts["theme"];
+        if (typeof opts["year"] === "number")
+            filter.year = opts["year"];
+        if (typeof opts["search"] === "string")
+            filter.search = opts["search"];
+        const indicators = await client.indicators(filter);
+        renderJson(deps, global, indicators.map((ind) => ({
+            code: ind.code,
+            table: ind.table,
+            theme: ind.theme,
+            titleShort: ind.titleShort,
+            years: yearRange(ind.years),
+        })));
+    }));
+    program
+        .command("query")
+        .description("Fetch indicator data rows per region (Bundesland / Kreis / Gemeinde)")
+        .argument("<indicator-code>", "indicator code (AI002-1-5) or table form (ai002_1_5)", parseNonEmpty)
+        .option("--level <level>", "geo level: land | regierungsbezirk | kreis | gemeinde", parseLevel, "land")
+        .option("--year <yyyy>", "reporting year (defaults to the indicator's latest)", parseYear)
+        .option("--region <name|ags>", "keep only rows matching this name (substring) or AGS", parseNonEmpty)
+        .option("--fields <a,b,c>", "keep only these value fields (comma-separated)", parseFieldList)
+        .action(action(deps, async ({ client, global, opts }, [indicator]) => {
+        const query = {
+            indicator: indicator,
+            level: typeof opts["level"] === "string" ? opts["level"] : "land",
+        };
+        if (typeof opts["year"] === "number")
+            query.year = opts["year"];
+        if (typeof opts["region"] === "string")
+            query.region = opts["region"];
+        if (Array.isArray(opts["fields"]))
+            query.fields = opts["fields"];
+        renderJson(deps, global, await client.query(query));
+    }));
+}
+//# sourceMappingURL=regions.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"regions.js","sourceRoot":"","sources":["../../../../src/cli/commands/regions.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 { RegionalatlasClient, RegionalatlasClientOptions } 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: RegionalatlasClientOptions): RegionalatlasClient;
+}
+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,mBAAmB,EAAE,0BAA0B,EAAE,MAAM,qBAAqB,CAAC;AAE3F,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,0BAA0B,GAAG,mBAAmB,CAAC;CACxE;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,CAuCjE"}

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 { RegionalatlasClient } from "../client/client.js";
+import { parseIntArg, parseBoundedInt, parseHeaderValue, parseHttpUrl } from "./shared.js";
+import { registerCommands } from "./commands/regions.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 RegionalatlasClient(options),
+};
+export function buildProgram(deps = defaultDeps) {
+    const program = new Command();
+    program
+        .name("regionalatlas")
+        .description("CLI for the Regionalatlas Deutschland — regional-statistics indicators of the " +
+        "Statistische Ämter des Bundes und der Länder, per Bundesland / Regierungsbezirk / " +
+        "Kreis / Gemeinde. No API key needed. `themes` lists the subject areas; `indicators` " +
+        "lists the indicators (with --theme/--year/--search filters); `query <code> --level " +
+        "<land|kreis|…>` fetches the data rows for a year.")
+        .version(VERSION)
+        .option("--base-url <url>", "ArcGIS data host base URL", parseHttpUrl, "https://www.gis-idmz.nrw.de")
+        .option("--catalog-url <url>", "indicator catalogue URL (services.json)", parseHttpUrl, "https://regionalatlas.statistikportal.de/taskrunner/services.json")
+        .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,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAC1D,OAAO,EAAE,WAAW,EAAE,eAAe,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3F,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAEzD;;;;;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,mBAAmB,CAAC,OAAO,CAAC;CAC5D,CAAC;AAEF,MAAM,UAAU,YAAY,CAAC,OAAgB,WAAW;IACtD,MAAM,OAAO,GAAG,IAAI,OAAO,EAAE,CAAC;IAE9B,OAAO;SACJ,IAAI,CAAC,eAAe,CAAC;SACrB,WAAW,CACV,gFAAgF;QAC9E,oFAAoF;QACpF,sFAAsF;QACtF,qFAAqF;QACrF,mDAAmD,CACtD;SACA,OAAO,CAAC,OAAO,CAAC;SAChB,MAAM,CACL,kBAAkB,EAClB,2BAA2B,EAC3B,YAAY,EACZ,6BAA6B,CAC9B;SACA,MAAM,CACL,qBAAqB,EACrB,yCAAyC,EACzC,YAAY,EACZ,mEAAmE,CACpE;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,CAkDtF"}

package/dist/src/cli/run.js

@@ -0,0 +1,85 @@
+// 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 { RegionalatlasApiError, RegionalatlasError, RegionalatlasNetworkError, RegionalatlasValidationError, } 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,
+    /** HTTP 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;
+        }
+        if (err instanceof RegionalatlasValidationError) {
+            deps.io.err(`Error: ${err.message}`);
+            return EXIT.USAGE;
+        }
+        if (err instanceof RegionalatlasApiError) {
+            deps.io.err(`Error: ${err.message}`);
+            if (err.status === 404)
+                return EXIT.NOT_FOUND;
+            // A 3xx means the base URL redirected (the canonical host answers directly),
+            // so it is a base-URL misconfiguration — a usage error.
+            if (err.status !== undefined && err.status >= 300 && err.status < 400)
+                return EXIT.USAGE;
+            return EXIT.OTHER;
+        }
+        if (err instanceof RegionalatlasNetworkError) {
+            deps.io.err(`Error: ${err.message}`);
+            if (/maxResponseBytes/.test(err.message)) {
+                deps.io.err("Hint: the response exceeded the size cap. Narrow the query (a coarser --level) or " +
+                    "raise --max-response-bytes <n> (0 = unlimited).");
+            }
+            return EXIT.NETWORK;
+        }
+        if (err instanceof RegionalatlasError) {
+            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,73 @@
+import type { CliDeps } from "./io.js";
+import type { RegionalatlasClientOptions } from "../client/client.js";
+/**
+ * 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, signs, padding and decimals.
+ */
+export declare function parseIntArg(value: string): number;
+/** commander value-parser: a 4-digit year (integer 1000..9999). */
+export declare function parseYear(value: string): number;
+/** commander value-parser: a non-empty (after trimming) string. */
+export declare function parseNonEmpty(value: string): string;
+/**
+ * commander value-parser for `--level`: resolves a friendly name/alias to the
+ * canonical level name, rejecting an unknown level at parse time (exit 2) with a
+ * clear message. The client re-resolves it (defence in depth) and only the fixed
+ * integer `typ` ever enters SQL.
+ */
+export declare function parseLevel(value: string): string;
+/**
+ * commander value-parser for a comma-separated field list. Splits on commas,
+ * trims, and drops empty entries. Field names are validated/projected client-side
+ * later, so this only produces a clean array.
+ */
+export declare function parseFieldList(value: string): string[];
+/**
+ * commander value-parser for `--base-url` / `--catalog-url`: a non-empty,
+ * well-formed URL whose scheme is `http:` or `https:`. Validating here (parse time)
+ * rejects a bad scheme (`file:`, `ftp:`, ...) as a usage error (exit 2) with a clear
+ * message, rather than letting it reach the transport and surface as a network error
+ * (exit 6). The transport re-checks the scheme as defence in depth.
+ */
+export declare function parseHttpUrl(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`. 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;
+    catalogUrl?: string;
+    timeout?: number;
+    userAgent?: string;
+    maxRetries?: number;
+    maxResponseBytes?: number;
+    compact?: boolean;
+}
+/** Translate resolved global CLI options into client options. */
+export declare function toEngineOptions(global: GlobalOptions): RegionalatlasClientOptions;
+/** 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":"AAKA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,qBAAqB,CAAC;AAGtE;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CASjD;AAED,mEAAmE;AACnE,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAK/C;AAED,mEAAmE;AACnE,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAKnD;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAShD;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CAStD;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAelD;AAED,+EAA+E;AAC/E,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAOnF;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAQtD;AAED,MAAM,WAAW,aAAa;IAC5B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,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,iEAAiE;AACjE,wBAAgB,eAAe,CAAC,MAAM,EAAE,aAAa,GAAG,0BAA0B,CASjF;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"}