@maschinenlesbar.org/bundeshaushalt-cli 0.0.1

package/LICENSING.md

@@ -0,0 +1,47 @@
+# Licensing
+
+`bundeshaushalt-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 `bundeshaushalt-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,203 @@
+# bundeshaushalt-cli
+
+A TypeScript **API client** and **command-line interface** for the open
+[Bundeshaushalt](https://bundeshaushalt.de/) budget-data API (`bundeshaushalt.de`)
+— the **German federal budget**: expenses and income by budget item, functional
+area or economic group, planned vs. realised.
+
+- **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 budget elements, metadata and the account/quota/unit enums.
+- **Well tested** — unit tests on Node's built-in test runner (`node --test`), every HTTP response mocked.
+- **Read-only, no auth** — the budget-data API needs no key; this client only reads.
+
+## 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:
+bundeshaushalt --help
+```
+
+---
+
+## How the data is shaped
+
+A query is a **year** + **account** (`expenses` / `income`). Optionally narrow by:
+
+- **quota** — `target` (planned) or `actual` (realised),
+- **unit** — `single` (budget item), `function` (functional area) or `group` (economic group),
+- **id** — drill into one element (a budget number; `G-` prefix for groups, `F-` for functions).
+
+The response carries the selected `detail`, its `children` (so you can walk the
+tree by passing a child's `id` back in), `parents`, and `related` cross-references.
+
+> **Stability / data coverage.** This client talks to an **undocumented, internal
+> endpoint** of the portal (`/internalapi/budgetData` — note the `internalapi`
+> path). It is **not** a published, stable public API: it can change shape,
+> rate-limit, or disappear **without notice**. The data is served without
+> authentication and currently covers years from `2012` onward (the exact upper
+> range depends on what the portal has published). Treat this dependency as
+> best-effort, especially for any production or commercial use.
+
+### Global options
+
+| Option | Description |
+| --- | --- |
+| `--base-url <url>` | API base URL (default `https://bundeshaushalt.de`) |
+| `--timeout <ms>` | Per-request timeout (default `30000`) |
+| `--user-agent <ua>` | `User-Agent` header value |
+| `--max-retries <n>` | Retries for transient `429`/`503` responses (default `2`) |
+| `--max-response-bytes <n>` | Cap response body size in bytes (`0` = unlimited; default 100 MiB) |
+| `--compact` | Print JSON on a single line |
+
+Global options may appear **before or after** the command, e.g. both
+`bundeshaushalt --compact expenses 2024` and `bundeshaushalt expenses 2024 --compact`
+work (they are resolved with commander's `optsWithGlobals`).
+
+### Commands
+
+```text
+budget <year> <account> [--quota target|actual] [--unit single|function|group] [--id <id>]
+expenses <year> [--quota] [--unit] [--id]    shortcut for: budget <year> expenses
+income   <year> [--quota] [--unit] [--id]    shortcut for: budget <year> income
+```
+
+(`<year>` is a four-digit year between `2012` and the current year, inclusive;
+the upper bound is derived from the current year so it stays meaningful over time.)
+
+### Examples
+
+```bash
+# Top-level federal expenses for 2024
+bundeshaushalt expenses 2024
+
+# Realised income, 2023
+bundeshaushalt income 2023 --quota actual
+
+# Expenses grouped by economic group
+bundeshaushalt budget 2024 expenses --unit group
+
+# Drill into one budget element by id
+bundeshaushalt budget 2024 expenses --id 090168301
+```
+
+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 { BundeshaushaltClient, HaushaltApiError } from "@maschinenlesbar.org/bundeshaushalt-cli";
+
+const client = new BundeshaushaltClient(); // defaults to https://bundeshaushalt.de
+
+const top = await client.budgetData({ year: 2024, account: "expenses" });
+console.log(top.meta.year, top.children.length, "children");
+
+const drill = await client.budgetData({ year: 2024, account: "expenses", id: "090168301" });
+
+try {
+  await client.budgetData({ year: 1999, account: "expenses" });
+} catch (err) {
+  if (err instanceof HaushaltApiError) console.error(err.status, err.detail);
+}
+```
+
+### Client options
+
+```ts
+new BundeshaushaltClient({
+  baseUrl: "https://bundeshaushalt.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
+});
+```
+
+### Methods
+
+`client.budgetData({ year, account, quota?, unit?, id? })`. The `AccountValues` /
+`QuotaValues` / `UnitValues` enums are exported for reference.
+
+---
+
+## Architecture
+
+```
+src/
+  client/
+    enums.ts     # Account / Quota / Unit value sets + MIN_YEAR
+    types.ts     # BudgetData / BudgetElement / BudgetMeta + param object
+    query.ts     # dependency-free query-string builder
+    http.ts      # the Transport interface + default node:http/https transport
+    engine.ts    # URL building, retry/backoff, redirects, JSON decoding, error mapping
+    errors.ts    # HaushaltError / HaushaltApiError / HaushaltNetworkError / HaushaltParseError
+    client.ts    # BundeshaushaltClient — the budget-data surface over the engine
+  cli/
+    io.ts        # injectable I/O seam (stdout/stderr/file)
+    shared.ts    # option parsers, global-option resolver, JSON renderer
+    commands/    # budget + expenses/income shortcuts
+    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.
+- `account`/`quota`/`unit` are validated against their enums and the year is range-checked before any request.
+
+---
+
+## 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`.
+- **`engine.test.ts`** — URL building, JSON decoding, error mapping, 429/503 retry, redirects — mocked transport.
+- **`client.test.ts`** — the budget-data URL/param mapping and optional-parameter pruning — mocked transport.
+- **`cli.test.ts`** — command parsing, the expenses/income shortcuts, validation and exit codes — mocked client.
+
+## 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/budget.d.ts

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

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

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

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

@@ -0,0 +1,86 @@
+import { action, assertEnum, renderJson } from "../shared.js";
+import { HaushaltError } from "../../client/errors.js";
+import { AccountValues, QuotaValues, UnitValues, MIN_YEAR } from "../../client/enums.js";
+/**
+ * Upper bound for an accepted year. Derived from the current year (rather than a
+ * hard-coded literal) so the validator stays meaningful as years advance.
+ *
+ * Capped at the current year: the portal only serves data up to (and including)
+ * the current budget year. Allowing current year + 1 turned a predictable
+ * client-side rejection into a network round-trip that the API answers with 404.
+ */
+function maxYear() {
+    return new Date().getUTCFullYear();
+}
+/** Parse + range-check a positional year (a four-digit integer in range). */
+function requireYear(value) {
+    const ceiling = maxYear();
+    // Validate the raw four-digit shape before coercing, so loose inputs like
+    // "2024.0" or " 2024 " are rejected rather than silently normalised.
+    if (!/^\d{4}$/.test(value)) {
+        throw new HaushaltError(`Invalid year "${value}". Expected a four-digit year between ${MIN_YEAR} and ${ceiling}.`);
+    }
+    const n = Number(value);
+    if (n < MIN_YEAR || n > ceiling) {
+        throw new HaushaltError(`Invalid year "${value}". Expected a four-digit year between ${MIN_YEAR} and ${ceiling}.`);
+    }
+    return n;
+}
+/** Build the optional quota/unit/id params shared by all budget commands. */
+function optionsFrom(opts) {
+    const params = {};
+    if (opts["quota"] !== undefined) {
+        params.quota = assertEnum(String(opts["quota"]), QuotaValues, "quota");
+    }
+    if (opts["unit"] !== undefined) {
+        params.unit = assertEnum(String(opts["unit"]), UnitValues, "unit");
+    }
+    if (opts["id"] !== undefined) {
+        const raw = String(opts["id"]);
+        // A value that looks like an option flag (e.g. `--id --quota`) is almost
+        // certainly a missing-value mistake: commander otherwise swallows the next
+        // flag as the id and sends `id=--quota` to the API. Reject it locally.
+        if (raw.startsWith("-")) {
+            throw new HaushaltError(`Invalid id "${raw}". The --id value looks like an option; did you forget to supply an id?`);
+        }
+        const id = raw.trim();
+        // Reject empty/whitespace ids so bad input fails locally with a clear
+        // message instead of producing an opaque API error (or `id=` in the query).
+        if (id.length === 0) {
+            throw new HaushaltError(`Invalid id "". Expected a non-empty budget number.`);
+        }
+        // Reject surrounding whitespace rather than silently trimming it: silent
+        // mutation can mask copy-paste errors and collapse two distinct inputs.
+        if (id !== raw) {
+            throw new HaushaltError(`Invalid id "${raw}". Surrounding whitespace is not allowed.`);
+        }
+        params.id = id;
+    }
+    return params;
+}
+function addBudgetOptions(cmd) {
+    return cmd
+        .option("--quota <quota>", `target | actual (default target)`)
+        .option("--unit <unit>", `single | function | group (default single)`)
+        .option("--id <id>", 'budget number id ("G-" prefix for groups, "F-" for functions)');
+}
+export function registerBudgetCommands(program, deps) {
+    addBudgetOptions(program
+        .command("budget <year> <account>")
+        .description(`Federal budget data (account: ${AccountValues.join(" | ")})`)).action(action(deps, async ({ client, global, opts }, [year, account]) => {
+        renderJson(deps, global, await client.budgetData({
+            year: requireYear(year),
+            account: assertEnum(account, AccountValues, "account"),
+            ...optionsFrom(opts),
+        }));
+    }));
+    // Convenience shortcuts that preset the account.
+    const shortcut = (name, account, desc) => {
+        addBudgetOptions(program.command(`${name} <year>`).description(desc)).action(action(deps, async ({ client, global, opts }, [year]) => {
+            renderJson(deps, global, await client.budgetData({ year: requireYear(year), account, ...optionsFrom(opts) }));
+        }));
+    };
+    shortcut("expenses", "expenses", "Federal expenses for a year (shortcut)");
+    shortcut("income", "income", "Federal income for a year (shortcut)");
+}
+//# sourceMappingURL=budget.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"budget.js","sourceRoot":"","sources":["../../../../src/cli/commands/budget.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC9D,OAAO,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AACvD,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAIzF;;;;;;;GAOG;AACH,SAAS,OAAO;IACd,OAAO,IAAI,IAAI,EAAE,CAAC,cAAc,EAAE,CAAC;AACrC,CAAC;AAED,6EAA6E;AAC7E,SAAS,WAAW,CAAC,KAAa;IAChC,MAAM,OAAO,GAAG,OAAO,EAAE,CAAC;IAC1B,0EAA0E;IAC1E,qEAAqE;IACrE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QAC3B,MAAM,IAAI,aAAa,CACrB,iBAAiB,KAAK,yCAAyC,QAAQ,QAAQ,OAAO,GAAG,CAC1F,CAAC;IACJ,CAAC;IACD,MAAM,CAAC,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;IACxB,IAAI,CAAC,GAAG,QAAQ,IAAI,CAAC,GAAG,OAAO,EAAE,CAAC;QAChC,MAAM,IAAI,aAAa,CACrB,iBAAiB,KAAK,yCAAyC,QAAQ,QAAQ,OAAO,GAAG,CAC1F,CAAC;IACJ,CAAC;IACD,OAAO,CAAC,CAAC;AACX,CAAC;AAED,6EAA6E;AAC7E,SAAS,WAAW,CAAC,IAA6B;IAChD,MAAM,MAAM,GAA2C,EAAE,CAAC;IAC1D,IAAI,IAAI,CAAC,OAAO,CAAC,KAAK,SAAS,EAAE,CAAC;QAChC,MAAM,CAAC,KAAK,GAAG,UAAU,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,EAAE,WAAW,EAAE,OAAO,CAAC,CAAC;IACzE,CAAC;IACD,IAAI,IAAI,CAAC,MAAM,CAAC,KAAK,SAAS,EAAE,CAAC;QAC/B,MAAM,CAAC,IAAI,GAAG,UAAU,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,EAAE,UAAU,EAAE,MAAM,CAAC,CAAC;IACrE,CAAC;IACD,IAAI,IAAI,CAAC,IAAI,CAAC,KAAK,SAAS,EAAE,CAAC;QAC7B,MAAM,GAAG,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;QAC/B,yEAAyE;QACzE,2EAA2E;QAC3E,uEAAuE;QACvE,IAAI,GAAG,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;YACxB,MAAM,IAAI,aAAa,CACrB,eAAe,GAAG,yEAAyE,CAC5F,CAAC;QACJ,CAAC;QACD,MAAM,EAAE,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC;QACtB,sEAAsE;QACtE,4EAA4E;QAC5E,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACpB,MAAM,IAAI,aAAa,CAAC,oDAAoD,CAAC,CAAC;QAChF,CAAC;QACD,yEAAyE;QACzE,wEAAwE;QACxE,IAAI,EAAE,KAAK,GAAG,EAAE,CAAC;YACf,MAAM,IAAI,aAAa,CAAC,eAAe,GAAG,2CAA2C,CAAC,CAAC;QACzF,CAAC;QACD,MAAM,CAAC,EAAE,GAAG,EAAE,CAAC;IACjB,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,SAAS,gBAAgB,CAAC,GAAY;IACpC,OAAO,GAAG;SACP,MAAM,CAAC,iBAAiB,EAAE,kCAAkC,CAAC;SAC7D,MAAM,CAAC,eAAe,EAAE,4CAA4C,CAAC;SACrE,MAAM,CAAC,WAAW,EAAE,+DAA+D,CAAC,CAAC;AAC1F,CAAC;AAED,MAAM,UAAU,sBAAsB,CAAC,OAAgB,EAAE,IAAa;IACpE,gBAAgB,CACd,OAAO;SACJ,OAAO,CAAC,yBAAyB,CAAC;SAClC,WAAW,CAAC,iCAAiC,aAAa,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAC9E,CAAC,MAAM,CACN,MAAM,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,EAAE,CAAC,IAAI,EAAE,OAAO,CAAC,EAAE,EAAE;QAC/D,UAAU,CACR,IAAI,EACJ,MAAM,EACN,MAAM,MAAM,CAAC,UAAU,CAAC;YACtB,IAAI,EAAE,WAAW,CAAC,IAAK,CAAC;YACxB,OAAO,EAAE,UAAU,CAAC,OAAQ,EAAE,aAAa,EAAE,SAAS,CAAC;YACvD,GAAG,WAAW,CAAC,IAAI,CAAC;SACrB,CAAC,CACH,CAAC;IACJ,CAAC,CAAC,CACH,CAAC;IAEF,iDAAiD;IACjD,MAAM,QAAQ,GAAG,CAAC,IAAY,EAAE,OAAgB,EAAE,IAAY,EAAE,EAAE;QAChE,gBAAgB,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,IAAI,SAAS,CAAC,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAC1E,MAAM,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,EAAE,EAAE;YACtD,UAAU,CACR,IAAI,EACJ,MAAM,EACN,MAAM,MAAM,CAAC,UAAU,CAAC,EAAE,IAAI,EAAE,WAAW,CAAC,IAAK,CAAC,EAAE,OAAO,EAAE,GAAG,WAAW,CAAC,IAAI,CAAC,EAAE,CAAC,CACrF,CAAC;QACJ,CAAC,CAAC,CACH,CAAC;IACJ,CAAC,CAAC;IACF,QAAQ,CAAC,UAAU,EAAE,UAAU,EAAE,wCAAwC,CAAC,CAAC;IAC3E,QAAQ,CAAC,QAAQ,EAAE,QAAQ,EAAE,sCAAsC,CAAC,CAAC;AACvE,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,13 @@
+import type { BundeshaushaltClient } from "../client/client.js";
+import type { EngineOptions } from "../client/engine.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: EngineOptions): BundeshaushaltClient;
+}
+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,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAChE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEzD,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,aAAa,GAAG,oBAAoB,CAAC;CAC5D;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;AAgBtE,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/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;AA4BvC,eAAO,MAAM,OAAO,QAAgB,CAAC;AAErC,yEAAyE;AACzE,eAAO,MAAM,WAAW,EAAE,OAGzB,CAAC;AAEF,wBAAgB,YAAY,CAAC,IAAI,GAAE,OAAqB,GAAG,OAAO,CA2BjE"}

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 { BundeshaushaltClient } from "../client/client.js";
+import { parseIntArg, parseBoundedIntArg } from "./shared.js";
+import { registerBudgetCommands } from "./commands/budget.js";
+/**
+ * Sane upper bound for `--max-retries`. A larger value would let a transient
+ * 429/503 spin the retry loop (with growing backoff) for effectively forever.
+ */
+const MAX_RETRIES_LIMIT = 100;
+/**
+ * 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 BundeshaushaltClient(options),
+};
+export function buildProgram(deps = defaultDeps) {
+    const program = new Command();
+    program
+        .name("bundeshaushalt")
+        .description("CLI for the open German federal budget API (https://bundeshaushalt.de)")
+        .version(VERSION)
+        .option("--base-url <url>", "API base URL", "https://bundeshaushalt.de")
+        .option("--timeout <ms>", "per-request timeout in milliseconds", parseIntArg, 30_000)
+        .option("--user-agent <ua>", "User-Agent header value")
+        .option("--max-retries <n>", "retries for transient 429/503 responses", parseBoundedIntArg(MAX_RETRIES_LIMIT), 2)
+        .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();
+    registerBudgetCommands(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,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAC9D,OAAO,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AAE9D;;;GAGG;AACH,MAAM,iBAAiB,GAAG,GAAG,CAAC;AAE9B;;;;;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,oBAAoB,CAAC,OAAO,CAAC;CAC7D,CAAC;AAEF,MAAM,UAAU,YAAY,CAAC,OAAgB,WAAW;IACtD,MAAM,OAAO,GAAG,IAAI,OAAO,EAAE,CAAC;IAE9B,OAAO;SACJ,IAAI,CAAC,gBAAgB,CAAC;SACtB,WAAW,CAAC,wEAAwE,CAAC;SACrF,OAAO,CAAC,OAAO,CAAC;SAChB,MAAM,CAAC,kBAAkB,EAAE,cAAc,EAAE,2BAA2B,CAAC;SACvE,MAAM,CAAC,gBAAgB,EAAE,qCAAqC,EAAE,WAAW,EAAE,MAAM,CAAC;SACpF,MAAM,CAAC,mBAAmB,EAAE,yBAAyB,CAAC;SACtD,MAAM,CACL,mBAAmB,EACnB,yCAAyC,EACzC,kBAAkB,CAAC,iBAAiB,CAAC,EACrC,CAAC,CACF;SACA,MAAM,CACL,0BAA0B,EAC1B,kEAAkE,EAClE,WAAW,CACZ;SACA,MAAM,CAAC,WAAW,EAAE,uDAAuD,CAAC;SAC5E,kBAAkB,EAAE,CAAC;IAExB,sBAAsB,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;IAEtC,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,CAyBtF"}

package/dist/src/cli/run.js

@@ -0,0 +1,48 @@
+// 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 { HaushaltApiError, HaushaltError } 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) {
+            // Help/version requests exit 0; genuine parse errors carry their own code.
+            return err.exitCode;
+        }
+        if (err instanceof HaushaltApiError) {
+            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 HaushaltError) {
+            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,gBAAgB,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEtE;;;;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,2EAA2E;YAC3E,OAAO,GAAG,CAAC,QAAQ,CAAC;QACtB,CAAC;QACD,IAAI,GAAG,YAAY,gBAAgB,EAAE,CAAC;YACpC,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,aAAa,EAAE,CAAC;YACjC,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"}

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

@@ -0,0 +1,51 @@
+import type { CliDeps } from "./io.js";
+import type { EngineOptions } from "../client/engine.js";
+/**
+ * commander value-parser: a non-negative integer in plain decimal notation.
+ *
+ * Deliberately strict: only `/^\d+$/` is accepted. `Number()` would otherwise
+ * coerce empty strings (→0, which silently disables size/retry caps), hex/octal/
+ * binary (`0x10`→16), scientific (`1e9`), a leading `+`, and surrounding
+ * whitespace — none of which a user typing a "non-negative integer" intends.
+ */
+export declare function parseIntArg(value: string): number;
+/**
+ * commander value-parser: a non-negative integer with an inclusive upper bound.
+ * Used for options like `--max-retries` where an absurdly large value would turn
+ * a transient-error retry loop into an effective hang (DoS).
+ */
+export declare function parseBoundedIntArg(max: number): (value: string) => number;
+/**
+ * Validate a positional argument against an allowed set (commander does not
+ * support .choices() on positional args). Throws a HaushaltError so run() prints a
+ * clear message and exits 1.
+ */
+export declare function assertEnum<T extends string>(value: string, allowed: readonly T[], argName: string): T;
+export interface GlobalOptions {
+    baseUrl?: string;
+    timeout?: number;
+    userAgent?: string;
+    maxRetries?: number;
+    maxResponseBytes?: number;
+    compact?: boolean;
+}
+/** Translate resolved global CLI options into client EngineOptions. */
+export declare function toEngineOptions(global: GlobalOptions): EngineOptions;
+/** 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;AAEvC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEzD;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAKjD;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAQzE;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,CAAC,SAAS,MAAM,EACzC,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,SAAS,CAAC,EAAE,EACrB,OAAO,EAAE,MAAM,GACd,CAAC,CAKH;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,uEAAuE;AACvE,wBAAgB,eAAe,CAAC,MAAM,EAAE,aAAa,GAAG,aAAa,CAQpE;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"}