@maschinenlesbar.org/govdata-cli 0.0.1

package/LICENSING.md

@@ -0,0 +1,47 @@
+# Licensing
+
+`govdata-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 `govdata-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,198 @@
+# govdata-cli
+
+A TypeScript **API client** and **command-line interface** for the open
+[GovData](https://www.govdata.de/) **CKAN Action API** (`ckan.govdata.de`) — the
+central German open-data catalogue (Bund/Länder/Kommunen): search datasets,
+inspect packages, organizations, groups, tags and resources.
+
+- **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 CKAN envelope, search result and parameter objects, plus a generic `action` escape hatch.
+- **Well tested** — unit tests on Node's built-in test runner (`node --test`), every HTTP response mocked.
+- **Read-only, no auth** — only CKAN read actions are wrapped; no key required.
+
+## 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:
+govdata --help
+```
+
+---
+
+## CLI usage
+
+CKAN wraps every response in `{ help, success, result }`; this CLI prints the
+unwrapped **`result`** (and exits non-zero if `success` is false). `--compact` for
+a single line.
+
+### Global options
+
+| Option | Description |
+| --- | --- |
+| `--base-url <url>` | API base URL (default `https://ckan.govdata.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 be given before or after the command, e.g.
+`govdata --compact search Haushalt` or `govdata search Haushalt --compact`.
+
+### Commands
+
+```text
+search [query] [--rows <n>] [--start <n>] [--sort <expr>] [--fq <filter> ...]
+package <id>                  show one dataset
+packages [--limit] [--offset] list dataset names
+organizations [--all-fields]  list organizations (publishers)
+organization <id>             show one organization
+groups [--all-fields]         list groups (themes)
+group <id>                    show one group
+tags [--query <substring>]    list tags
+resource <id>                 show one resource (distribution)
+action <name> [--param key=value ...]   call any CKAN action (generic)
+```
+
+### Examples
+
+```bash
+# Search datasets, newest first
+govdata search Haushalt --rows 5 --sort "metadata_modified desc"
+
+# Filter by organization and format
+govdata search --fq organization:destatis --fq res_format:CSV
+
+# A specific dataset
+govdata package <dataset-id-or-name>
+
+# Publishers
+govdata organizations
+
+# Any action not wrapped above
+govdata action package_search --param q=Klima --param rows=3
+```
+
+Exit codes: `0` success (and for `--help`/`--version`), `4` on a `404` from the API, `1` for any other error (incl. a CKAN `success:false`) and for commander usage/parse errors.
+
+---
+
+## Library usage
+
+```ts
+import { GovDataClient, GovDataError } from "@maschinenlesbar.org/govdata-cli";
+
+const client = new GovDataClient(); // defaults to https://ckan.govdata.de
+
+const hits = await client.packageSearch({ q: "Haushalt", rows: 5 });
+const dataset = await client.packageShow(hits.results[0]!.id as string);
+const orgs = await client.organizationList();
+
+// Generic escape hatch for any read action:
+const tags = await client.action<string[]>("tag_list", { query: "energie" });
+
+try {
+  await client.packageShow("does-not-exist");
+} catch (err) {
+  if (err instanceof GovDataError) console.error(err.message);
+}
+```
+
+### Client options
+
+```ts
+new GovDataClient({
+  baseUrl: "https://ckan.govdata.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
+
+`packageSearch`, `packageShow`, `packageList`, `organizationList`, `organizationShow`,
+`groupList`, `groupShow`, `tagList`, `resourceShow`, and the generic `action(name, params)`.
+
+---
+
+## Architecture
+
+```
+src/
+  client/
+    types.ts     # CkanEnvelope, PackageSearchResult + parameter objects
+    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    # GovDataError / GovDataApiError / GovDataNetworkError / GovDataParseError
+    client.ts    # GovDataClient — CKAN actions over the engine (with result-unwrapping)
+  cli/
+    io.ts        # injectable I/O seam (stdout/stderr)
+    shared.ts    # option parsers, global-option resolver, JSON renderer
+    commands/    # search / package / organizations / groups / tags / resource / action
+    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 client unwraps CKAN's `{ help, success, result }` envelope and raises `GovDataError`
+  when `success` is false, so callers work directly with `result`.
+- A generic `action(name, params)` exposes every read action even where there is no typed convenience method. The action name is validated against `^[a-z0-9_]+$` and URL-encoded, so it cannot inject extra path segments, query string, or fragments into the request URL.
+- Redirects are followed up to `maxRedirects`; if a redirect crosses origin, the request headers are dropped so nothing (e.g. a future auth/cookie header) leaks to another host.
+
+---
+
+## 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`** — action URL/param mapping, result unwrapping, success:false handling — mocked transport.
+- **`cli.test.ts`** — end-to-end command parsing, `--param`/`--fq` handling 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/catalogue.d.ts

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"catalogue.d.ts","sourceRoot":"","sources":["../../../../src/cli/commands/catalogue.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEzC,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AA6BxC,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,GAAG,IAAI,CA8H/E"}

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

@@ -0,0 +1,105 @@
+import { InvalidArgumentError } from "commander";
+import { action, parseIntArg, renderJson } from "../shared.js";
+/** commander accumulator for a repeatable string option. */
+function collect(value, previous = []) {
+    return previous.concat([value]);
+}
+/** commander accumulator for repeatable `key=value` pairs into a record. */
+function collectKeyValue(value, previous = {}) {
+    const eq = value.indexOf("=");
+    // Throw commander's InvalidArgumentError (not a GovDataError) so the failure
+    // is formatted as a usage error with `error:` prefix and help, consistent
+    // with other parse-time flag validation (e.g. `--rows abc`).
+    if (eq <= 0) {
+        throw new InvalidArgumentError(`Invalid --param "${value}". Expected key=value.`);
+    }
+    const key = value.slice(0, eq);
+    // Reject a duplicated key rather than silently overwriting the earlier value.
+    if (Object.prototype.hasOwnProperty.call(previous, key)) {
+        throw new InvalidArgumentError(`Duplicate --param key "${key}".`);
+    }
+    return { ...previous, [key]: value.slice(eq + 1) };
+}
+export function registerCatalogueCommands(program, deps) {
+    program
+        .command("search [query]")
+        .description("Search datasets (Solr query syntax)")
+        .option("--rows <n>", "max results", parseIntArg)
+        .option("--start <n>", "offset for paging", parseIntArg)
+        .option("--sort <expr>", 'e.g. "metadata_modified desc"')
+        .option("--fq <filter>", "filter query, e.g. organization:destatis (repeatable)", collect)
+        .action(action(deps, async ({ client, global, opts }, [query]) => {
+        renderJson(deps, global, await client.packageSearch({
+            q: query,
+            rows: opts["rows"],
+            start: opts["start"],
+            sort: opts["sort"],
+            fq: opts["fq"],
+        }));
+    }));
+    program
+        .command("package <id>")
+        .description("Show one dataset by id or name")
+        .action(action(deps, async ({ client, global }, [id]) => {
+        renderJson(deps, global, await client.packageShow(id));
+    }));
+    program
+        .command("packages")
+        .description("List dataset names")
+        .option("--limit <n>", "max names", parseIntArg)
+        .option("--offset <n>", "offset for paging", parseIntArg)
+        .action(action(deps, async ({ client, global, opts }) => {
+        renderJson(deps, global, await client.packageList({
+            limit: opts["limit"],
+            offset: opts["offset"],
+        }));
+    }));
+    program
+        .command("organizations")
+        .description("List organizations (data publishers)")
+        .option("--all-fields", "return full objects instead of names")
+        .action(action(deps, async ({ client, global, opts }) => {
+        renderJson(deps, global, await client.organizationList({ all_fields: opts["allFields"] }));
+    }));
+    program
+        .command("organization <id>")
+        .description("Show one organization")
+        .action(action(deps, async ({ client, global }, [id]) => {
+        renderJson(deps, global, await client.organizationShow(id));
+    }));
+    program
+        .command("groups")
+        .description("List groups (themes/categories)")
+        .option("--all-fields", "return full objects instead of names")
+        .action(action(deps, async ({ client, global, opts }) => {
+        renderJson(deps, global, await client.groupList({ all_fields: opts["allFields"] }));
+    }));
+    program
+        .command("group <id>")
+        .description("Show one group")
+        .action(action(deps, async ({ client, global }, [id]) => {
+        renderJson(deps, global, await client.groupShow(id));
+    }));
+    program
+        .command("tags")
+        .description("List tags")
+        .option("--query <substring>", "filter tags by substring")
+        .action(action(deps, async ({ client, global, opts }) => {
+        renderJson(deps, global, await client.tagList(opts["query"]));
+    }));
+    program
+        .command("resource <id>")
+        .description("Show one resource (distribution) by id")
+        .action(action(deps, async ({ client, global }, [id]) => {
+        renderJson(deps, global, await client.resourceShow(id));
+    }));
+    program
+        .command("action <name>")
+        .description("Call any CKAN action by name (generic escape hatch)")
+        .option("--param <key=value>", "query parameter (repeatable)", collectKeyValue)
+        .action(action(deps, async ({ client, global, opts }, [name]) => {
+        const params = opts["param"] ?? {};
+        renderJson(deps, global, await client.action(name, params));
+    }));
+}
+//# sourceMappingURL=catalogue.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"catalogue.js","sourceRoot":"","sources":["../../../../src/cli/commands/catalogue.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,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 { GovDataClient } 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): GovDataClient;
+}
+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,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACzD,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,aAAa,CAAC;CACrD;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;AAsBvC,eAAO,MAAM,OAAO,QAAgB,CAAC;AAErC,yEAAyE;AACzE,eAAO,MAAM,WAAW,EAAE,OAGzB,CAAC;AAEF,wBAAgB,YAAY,CAAC,IAAI,GAAE,OAAqB,GAAG,OAAO,CA+BjE"}

package/dist/src/cli/program.js

@@ -0,0 +1,55 @@
+// 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 { GovDataClient } from "../client/client.js";
+import { parseIntArg } from "./shared.js";
+import { registerCatalogueCommands } from "./commands/catalogue.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 GovDataClient(options),
+};
+export function buildProgram(deps = defaultDeps) {
+    const program = new Command();
+    program
+        .name("govdata")
+        .description("CLI for the open GovData CKAN catalogue API (https://ckan.govdata.de/api/3/action)")
+        .version(VERSION)
+        .option("--base-url <url>", "API base URL", "https://ckan.govdata.de")
+        .option("--timeout <ms>", "per-request timeout in milliseconds", parseIntArg)
+        .option("--user-agent <ua>", "User-Agent header value")
+        .option("--max-retries <n>", "retries for transient 429/503 responses", 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")
+        .showHelpAfterError();
+    // A bare invocation (no subcommand) should print help to stdout and exit 0,
+    // matching `govdata help` / `govdata --help`. Without an explicit root action,
+    // commander writes help to stderr and exits 1 for the empty-command case.
+    program.action(() => {
+        program.help();
+    });
+    registerCatalogueCommands(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,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,yBAAyB,EAAE,MAAM,yBAAyB,CAAC;AAEpE;;;;;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,aAAa,CAAC,OAAO,CAAC;CACtD,CAAC;AAEF,MAAM,UAAU,YAAY,CAAC,OAAgB,WAAW;IACtD,MAAM,OAAO,GAAG,IAAI,OAAO,EAAE,CAAC;IAE9B,OAAO;SACJ,IAAI,CAAC,SAAS,CAAC;SACf,WAAW,CACV,oFAAoF,CACrF;SACA,OAAO,CAAC,OAAO,CAAC;SAChB,MAAM,CAAC,kBAAkB,EAAE,cAAc,EAAE,yBAAyB,CAAC;SACrE,MAAM,CAAC,gBAAgB,EAAE,qCAAqC,EAAE,WAAW,CAAC;SAC5E,MAAM,CAAC,mBAAmB,EAAE,yBAAyB,CAAC;SACtD,MAAM,CAAC,mBAAmB,EAAE,yCAAyC,EAAE,WAAW,CAAC;SACnF,MAAM,CACL,0BAA0B,EAC1B,kEAAkE,EAClE,WAAW,CACZ;SACA,MAAM,CAAC,WAAW,EAAE,uDAAuD,CAAC;SAC5E,kBAAkB,EAAE,CAAC;IAExB,4EAA4E;IAC5E,+EAA+E;IAC/E,0EAA0E;IAC1E,OAAO,CAAC,MAAM,CAAC,GAAG,EAAE;QAClB,OAAO,CAAC,IAAI,EAAE,CAAC;IACjB,CAAC,CAAC,CAAC;IAEH,yBAAyB,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;IAEzC,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 { GovDataApiError, GovDataError } 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 GovDataApiError) {
+            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 GovDataError) {
+            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,eAAe,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAEpE;;;;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,eAAe,EAAE,CAAC;YACnC,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,YAAY,EAAE,CAAC;YAChC,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,32 @@
+import type { CliDeps } from "./io.js";
+import type { EngineOptions } from "../client/engine.js";
+/** commander value-parser: a non-negative integer. */
+export declare function parseIntArg(value: string): number;
+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;AACvC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEzD,sDAAsD;AACtD,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAajD;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"}