@maschinenlesbar.org/ckan-cli 0.0.5 → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (72) hide show
  1. package/README.md +28 -14
  2. package/dist/src/cli/commands/catalogue.d.ts +1 -2
  3. package/dist/src/cli/commands/catalogue.js +22 -9
  4. package/dist/src/cli/commands/portal.d.ts +0 -1
  5. package/dist/src/cli/commands/portal.js +18 -10
  6. package/dist/src/cli/index.d.ts +0 -1
  7. package/dist/src/cli/index.js +2 -1
  8. package/dist/src/cli/io.d.ts +17 -1
  9. package/dist/src/cli/io.js +22 -1
  10. package/dist/src/cli/program.d.ts +0 -1
  11. package/dist/src/cli/program.js +24 -6
  12. package/dist/src/cli/run.d.ts +0 -1
  13. package/dist/src/cli/run.js +9 -2
  14. package/dist/src/cli/shared.d.ts +28 -14
  15. package/dist/src/cli/shared.js +78 -40
  16. package/dist/src/client/client.d.ts +13 -6
  17. package/dist/src/client/client.js +100 -35
  18. package/dist/src/client/engine.d.ts +79 -6
  19. package/dist/src/client/engine.js +188 -74
  20. package/dist/src/client/errors.d.ts +13 -1
  21. package/dist/src/client/errors.js +30 -3
  22. package/dist/src/client/http.d.ts +0 -1
  23. package/dist/src/client/http.js +44 -36
  24. package/dist/src/client/index.d.ts +6 -5
  25. package/dist/src/client/index.js +4 -4
  26. package/dist/src/client/portals-list.d.ts +0 -1
  27. package/dist/src/client/portals-list.js +0 -1
  28. package/dist/src/client/portals.d.ts +35 -2
  29. package/dist/src/client/portals.js +50 -3
  30. package/dist/src/client/query.d.ts +0 -1
  31. package/dist/src/client/query.js +0 -1
  32. package/dist/src/client/types.d.ts +5 -1
  33. package/dist/src/client/types.js +0 -1
  34. package/dist/src/client/validate.d.ts +55 -0
  35. package/dist/src/client/validate.js +119 -0
  36. package/dist/src/index.d.ts +0 -1
  37. package/dist/src/index.js +0 -1
  38. package/package.json +2 -1
  39. package/dist/src/cli/commands/catalogue.d.ts.map +0 -1
  40. package/dist/src/cli/commands/catalogue.js.map +0 -1
  41. package/dist/src/cli/commands/portal.d.ts.map +0 -1
  42. package/dist/src/cli/commands/portal.js.map +0 -1
  43. package/dist/src/cli/index.d.ts.map +0 -1
  44. package/dist/src/cli/index.js.map +0 -1
  45. package/dist/src/cli/io.d.ts.map +0 -1
  46. package/dist/src/cli/io.js.map +0 -1
  47. package/dist/src/cli/program.d.ts.map +0 -1
  48. package/dist/src/cli/program.js.map +0 -1
  49. package/dist/src/cli/run.d.ts.map +0 -1
  50. package/dist/src/cli/run.js.map +0 -1
  51. package/dist/src/cli/shared.d.ts.map +0 -1
  52. package/dist/src/cli/shared.js.map +0 -1
  53. package/dist/src/client/client.d.ts.map +0 -1
  54. package/dist/src/client/client.js.map +0 -1
  55. package/dist/src/client/engine.d.ts.map +0 -1
  56. package/dist/src/client/engine.js.map +0 -1
  57. package/dist/src/client/errors.d.ts.map +0 -1
  58. package/dist/src/client/errors.js.map +0 -1
  59. package/dist/src/client/http.d.ts.map +0 -1
  60. package/dist/src/client/http.js.map +0 -1
  61. package/dist/src/client/index.d.ts.map +0 -1
  62. package/dist/src/client/index.js.map +0 -1
  63. package/dist/src/client/portals-list.d.ts.map +0 -1
  64. package/dist/src/client/portals-list.js.map +0 -1
  65. package/dist/src/client/portals.d.ts.map +0 -1
  66. package/dist/src/client/portals.js.map +0 -1
  67. package/dist/src/client/query.d.ts.map +0 -1
  68. package/dist/src/client/query.js.map +0 -1
  69. package/dist/src/client/types.d.ts.map +0 -1
  70. package/dist/src/client/types.js.map +0 -1
  71. package/dist/src/index.d.ts.map +0 -1
  72. package/dist/src/index.js.map +0 -1
package/README.md CHANGED
@@ -43,10 +43,12 @@ ckan search elbe --rows 5
43
43
  ```
44
44
 
45
45
  All administrative regulations (*Verwaltungsvorschriften*), using a filter
46
- query on one of Hamburg's own fields:
46
+ query on one of Hamburg's own fields. The filter takes the **stemmed** value
47
+ the search index holds: Hamburg's API page writes `verwaltungsvorschriften`,
48
+ which also matches the *Dienstanweisungen* and returns twice as many records.
47
49
 
48
50
  ```bash
49
- ckan search --fq extras_registerobject_type:verwaltungsvorschriften --rows 5
51
+ ckan search --fq extras_registerobject_type:verwaltungsvorschrift --rows 5
50
52
  ```
51
53
 
52
54
  The result is unwrapped from CKAN's `{ help, success, result }` envelope, so you
@@ -147,14 +149,16 @@ action <name> [--param key=value …] call any CKAN action (generic)
147
149
  > **Several `--fq` filters** are sent as CKAN's `fq_list`, never as a repeated
148
150
  > `fq` key, which CKAN answers with HTTP 409.
149
151
 
150
- > **Blank values are refused.** `ckan search ""`, `--fq ""` or `tags --query ""`
151
- > exit 1 before any request, instead of silently running an unfiltered search.
152
+ > **Blank values are refused.** `ckan search ""`, `--fq ""`, `tags --query ""` or
153
+ > `action … --param q=` exit 1 before any request, instead of silently running an unfiltered search.
154
+ > So does a forgotten value (`--fq --rows 5`): a value of `--fq`, `--facet`,
155
+ > `--sort` or `tags --query` cannot start with `--`.
152
156
 
153
157
  ### Paging and list flags
154
158
 
155
159
  | Command | Flags |
156
160
  | --- | --- |
157
- | `packages` | `--limit <n>`, `--offset <n>` |
161
+ | `packages` | `--limit <n>` (1 or more; omit for the whole list), `--offset <n>` |
158
162
  | `organizations`, `groups` | `--all-fields` (full objects instead of names), `--limit <n>`, `--offset <n>` |
159
163
 
160
164
  > **`--all-fields` lists are complete.** CKAN caps them at 25 entries
@@ -175,14 +179,18 @@ before any request is sent.
175
179
  - **Mostly documents, not datasets.** Hamburg publishes what the Hamburg
176
180
  Transparency Act (HmbTG) requires: council papers, contracts, reports,
177
181
  regulations, geodata. Most records have `type: "document"`.
178
- - **The *Informationsgegenstand*** is in `extras_registerobject_type`
179
- (`verwaltungsvorschriften`, `vertraege_oeff_interesse`, `gutachten`,
180
- `geodaten`, …). Hamburg lists the allowed values at
181
- <https://suche.transparenz.hamburg.de/api/rest/enums>. That endpoint is
182
- Hamburg-specific, not part of the CKAN Action API.
182
+ - **The *Informationsgegenstand*** is in `extras_registerobject_type`. Filter
183
+ it with the **stemmed** value the search index holds (`verwaltungsvorschrift`,
184
+ `vertrageoffinteress`, `gutacht`, `geodat`, …). Hamburg's own value list at
185
+ <https://suche.transparenz.hamburg.de/api/rest/enums> (Hamburg-specific, not
186
+ part of the CKAN Action API) gives other spellings: `vertraege_oeff_interesse`
187
+ matches nothing, and a full word such as `verwaltungsvorschriften` over-matches.
188
+ List the values that work, with their counts:
189
+ `ckan --compact search --rows 0 --facet extras_registerobject_type --facet-limit -1`.
190
+ The [Glossary](GLOSSARY.md) has the details.
183
191
  - **Several filters work.** Hamburg's API page says only one filter can be
184
192
  used; with `fq_list` (repeat `--fq`) they combine:
185
- `ckan search --fq extras_registerobject_type:verwaltungsvorschriften --fq organization:workflows`.
193
+ `ckan search --fq extras_registerobject_type:verwaltungsvorschrift --fq organization:workflows`.
186
194
  - **Tags are free text.** Many tags are whole keyword lists in a single string,
187
195
  so `tags --query` matches substrings of those strings.
188
196
 
@@ -225,14 +233,20 @@ ckan package bezirk-wandsbek-drucksache-22-3573-2 | jq '.resources[] | {format,
225
233
 
226
234
  | Code | Meaning |
227
235
  | --- | --- |
228
- | `0` | success (also `--help` / `--version`) |
229
- | `4` | not found (HTTP `404`), e.g. an unknown dataset id |
236
+ | `0` | success (also `--help`, `help [command]`, `--version` and a bare `ckan`) |
237
+ | `4` | not found (HTTP `404`): an unknown id on `package`/`resource`/`organization`/`group`, or, on any command, no CKAN at this URL (a wrong `--base-url`, a portal that left CKAN) |
230
238
  | `1` | any other error — bad usage, validation error (`409`), unknown action (`400`), CKAN `success:false`, network failure |
231
239
 
232
240
  CKAN's error text is shown on stderr, e.g.
233
241
  `Validation Error: rows: Invalid integer` or
234
242
  `Bad request - Action name not known: …`.
235
243
 
244
+ > **Numbers pass through JavaScript.** The output is the parsed and re-serialised
245
+ > JSON, so an integer above 2⁵³ (9,007,199,254,740,992) loses its last digits and a
246
+ > number beyond the double range (`1e400`) prints as `null`. CKAN metadata rarely
247
+ > holds such numbers; for an exact copy of the raw answer, use `curl` on
248
+ > `<site>/api/3/action/<name>`.
249
+
236
250
  ## Global options
237
251
 
238
252
  | Option | Description |
@@ -244,7 +258,7 @@ CKAN's error text is shown on stderr, e.g.
244
258
  | `--portal <id>` | a known portal by id (`ckan portals`); cannot be combined with `--base-url` |
245
259
  | `--timeout <ms>` | Per-request timeout (default `30000`; at most `2147483647`) |
246
260
  | `--user-agent <ua>` | `User-Agent` header value |
247
- | `--max-retries <n>` | Retries for transient `429`/`503` responses (default `2`) |
261
+ | `--max-retries <n>` | Retries for transient `429`/`503` responses (`0`–`10`, default `2`). Each retry waits the server's `Retry-After` (up to 30 s; a longer one is not retried) or else backs off linearly |
248
262
  | `--max-response-bytes <n>` | Cap response body size in bytes (`0` = unlimited; default 100 MiB) |
249
263
 
250
264
  ## Claude Code skills
@@ -1,4 +1,3 @@
1
- import type { Command } from "commander";
1
+ import { type Command } from "commander";
2
2
  import type { CliDeps } from "../io.js";
3
3
  export declare function registerCatalogueCommands(program: Command, deps: CliDeps): void;
4
- //# sourceMappingURL=catalogue.d.ts.map
@@ -1,9 +1,23 @@
1
1
  // Commands over the catalogue: datasets, their resources, publishers, themes
2
2
  // and tags.
3
- import { action, collectNonEmpty, parseIntArg, parseNonEmpty, renderJson } from "../shared.js";
4
- /** commander value-parser for --facet-limit: a count, or -1 for every value. */
3
+ import { InvalidArgumentError } from "commander";
4
+ import { facetLimitProblem } from "../../client/validate.js";
5
+ import { action, collectNonEmpty, parseBoundedInt, parseIntArg, parseNonEmpty, parseOptionValue, renderJson, } from "../shared.js";
6
+ /**
7
+ * commander value-parser for a list --limit: 1 or more. CKAN reads `limit=0` as
8
+ * "no limit" and would send the whole list; leave --limit out for that.
9
+ */
10
+ const parseLimit = parseBoundedInt(1, Number.MAX_SAFE_INTEGER);
11
+ /**
12
+ * commander value-parser for --facet-limit: a count, or -1 for every value (the
13
+ * library's facetLimitProblem rule).
14
+ */
5
15
  function parseFacetLimit(value) {
6
- return value === "-1" ? -1 : parseIntArg(value);
16
+ const n = /^-\d+$/.test(value) ? Number(value) : parseIntArg(value);
17
+ const reason = facetLimitProblem(n);
18
+ if (reason !== undefined)
19
+ throw new InvalidArgumentError(reason);
20
+ return n;
7
21
  }
8
22
  export function registerCatalogueCommands(program, deps) {
9
23
  program
@@ -12,7 +26,7 @@ export function registerCatalogueCommands(program, deps) {
12
26
  .argument("[query]", "full-text query, e.g. elbe or title:haushalt", parseNonEmpty)
13
27
  .option("--rows <n>", "max results (servers cap this, usually at 1000)", parseIntArg)
14
28
  .option("--start <n>", "offset for paging", parseIntArg)
15
- .option("--sort <expr>", 'e.g. "metadata_modified desc"', parseNonEmpty)
29
+ .option("--sort <expr>", 'e.g. "metadata_modified desc"', parseOptionValue)
16
30
  .option("--fq <filter>", "filter query, e.g. organization:allris (repeatable; all must match)", collectNonEmpty)
17
31
  .option("--facet <field>", "count values of a field, e.g. res_format (repeatable)", collectNonEmpty)
18
32
  .option("--facet-limit <n>", "max values per facet (default 50; -1 = all)", parseFacetLimit)
@@ -58,7 +72,7 @@ export function registerCatalogueCommands(program, deps) {
58
72
  program
59
73
  .command("packages")
60
74
  .description("List dataset names")
61
- .option("--limit <n>", "max names", parseIntArg)
75
+ .option("--limit <n>", "max names (1 or more; omit for all)", parseLimit)
62
76
  .option("--offset <n>", "offset for paging", parseIntArg)
63
77
  .action(action(deps, async ({ client, global, opts }) => {
64
78
  renderJson(deps, global, await client.packageList({
@@ -70,7 +84,7 @@ export function registerCatalogueCommands(program, deps) {
70
84
  .command("organizations")
71
85
  .description("List organizations (data publishers)")
72
86
  .option("--all-fields", "return full objects instead of names")
73
- .option("--limit <n>", "max entries", parseIntArg)
87
+ .option("--limit <n>", "max entries (1 or more; omit for all)", parseLimit)
74
88
  .option("--offset <n>", "offset for paging", parseIntArg)
75
89
  .action(action(deps, async ({ client, global, opts }) => {
76
90
  renderJson(deps, global, await client.organizationList({
@@ -83,7 +97,7 @@ export function registerCatalogueCommands(program, deps) {
83
97
  .command("groups")
84
98
  .description("List groups (themes/categories)")
85
99
  .option("--all-fields", "return full objects instead of names")
86
- .option("--limit <n>", "max entries", parseIntArg)
100
+ .option("--limit <n>", "max entries (1 or more; omit for all)", parseLimit)
87
101
  .option("--offset <n>", "offset for paging", parseIntArg)
88
102
  .action(action(deps, async ({ client, global, opts }) => {
89
103
  renderJson(deps, global, await client.groupList({
@@ -95,9 +109,8 @@ export function registerCatalogueCommands(program, deps) {
95
109
  program
96
110
  .command("tags")
97
111
  .description("List tags")
98
- .option("--query <substring>", "only tags containing this substring", parseNonEmpty)
112
+ .option("--query <substring>", "only tags containing this substring", parseOptionValue)
99
113
  .action(action(deps, async ({ client, global, opts }) => {
100
114
  renderJson(deps, global, await client.tagList({ query: opts["query"] }));
101
115
  }));
102
116
  }
103
- //# sourceMappingURL=catalogue.js.map
@@ -1,4 +1,3 @@
1
1
  import type { Command } from "commander";
2
2
  import type { CliDeps } from "../io.js";
3
3
  export declare function registerPortalCommands(program: Command, deps: CliDeps): void;
4
- //# sourceMappingURL=portal.d.ts.map
@@ -1,25 +1,33 @@
1
1
  // Commands about the portal itself rather than its datasets.
2
2
  import { InvalidArgumentError } from "commander";
3
3
  import { action, renderJson, toEngineOptions } from "../shared.js";
4
- import { checkPortal, mapLimit, withCheck } from "../../client/portals.js";
4
+ import { checkPortals } from "../../client/portals.js";
5
5
  import { PORTALS } from "../../client/portals-list.js";
6
- /** How many portals `portals --check` checks at once. */
7
- const CHECK_CONCURRENCY = 6;
6
+ import { isBlank } from "../../client/validate.js";
8
7
  /** commander accumulator for repeatable `key=value` pairs into a record. */
9
8
  function collectKeyValue(value, previous = {}) {
10
9
  const eq = value.indexOf("=");
11
10
  // Throw commander's InvalidArgumentError (not a CkanError) so the failure is
12
11
  // formatted as a usage error with `error:` prefix and help, consistent with
13
12
  // other parse-time flag validation (e.g. `--rows abc`).
14
- if (eq <= 0) {
13
+ const key = value.slice(0, Math.max(eq, 0));
14
+ // A blank key (`=x`, ` =x`) names no parameter: the library refuses it too.
15
+ if (eq < 0 || isBlank(key)) {
15
16
  throw new InvalidArgumentError(`Invalid --param "${value}". Expected key=value.`);
16
17
  }
17
- const key = value.slice(0, eq);
18
18
  // Reject a duplicated key rather than silently overwriting the earlier value.
19
19
  if (Object.prototype.hasOwnProperty.call(previous, key)) {
20
20
  throw new InvalidArgumentError(`Duplicate --param key "${key}".`);
21
21
  }
22
- return { ...previous, [key]: value.slice(eq + 1) };
22
+ // A blank value is refused by the library as well (CKAN reads an empty
23
+ // parameter as unset, so `--param q=` would run the action unfiltered); here it
24
+ // is a usage error that names the flag.
25
+ const paramValue = value.slice(eq + 1);
26
+ if (isBlank(paramValue)) {
27
+ throw new InvalidArgumentError(`Invalid --param "${value}". The value must not be blank.`);
28
+ }
29
+ // A computed key in a literal is an own data property, even for `__proto__`.
30
+ return { ...previous, [key]: paramValue };
23
31
  }
24
32
  export function registerPortalCommands(program, deps) {
25
33
  program
@@ -52,10 +60,10 @@ export function registerPortalCommands(program, deps) {
52
60
  renderJson(deps, global, PORTALS);
53
61
  return;
54
62
  }
55
- const today = new Date().toISOString().slice(0, 10);
56
- const engine = toEngineOptions(global);
57
- const checked = await mapLimit(PORTALS, CHECK_CONCURRENCY, async (portal) => withCheck(portal, await checkPortal(deps.createClient({ ...engine, baseUrl: portal.url })), today));
63
+ const checked = await checkPortals(PORTALS, {
64
+ engineOptions: toEngineOptions(global),
65
+ createClient: deps.createClient,
66
+ });
58
67
  renderJson(deps, global, checked);
59
68
  });
60
69
  }
61
- //# sourceMappingURL=portal.js.map
@@ -1,3 +1,2 @@
1
1
  #!/usr/bin/env node
2
2
  export {};
3
- //# sourceMappingURL=index.d.ts.map
@@ -1,6 +1,7 @@
1
1
  #!/usr/bin/env node
2
2
  // Binary entry point. Thin shim around run(); all logic lives in run.ts/program.ts.
3
+ import { handleOutputErrors } from "./io.js";
3
4
  import { run } from "./run.js";
5
+ handleOutputErrors();
4
6
  const exitCode = await run(process.argv.slice(2));
5
7
  process.exitCode = exitCode;
6
- //# sourceMappingURL=index.js.map
@@ -11,5 +11,21 @@ export interface CliDeps {
11
11
  /** Build a client from the resolved global options (injectable for tests). */
12
12
  createClient(options: EngineOptions): CkanClient;
13
13
  }
14
+ /** The two process streams, as far as `handleOutputErrors` needs them. */
15
+ export interface OutputStreams {
16
+ stdout: Pick<NodeJS.WriteStream, "on">;
17
+ stderr: Pick<NodeJS.WriteStream, "on">;
18
+ }
19
+ /**
20
+ * Handle write errors on stdout/stderr, which Node otherwise reports as an
21
+ * unhandled 'error' event: a raw stack trace and exit 1.
22
+ *
23
+ * A reader that stops early — `| head`, `| jq` exiting on the first match, a closed
24
+ * pager — closes the pipe while the CLI is still writing, and the next write fails
25
+ * with EPIPE. That is ordinary use, so the process exits 0 at once, quietly. Any
26
+ * other stdout error prints one `Output error: <message>` line to stderr and exits
27
+ * 1; any other stderr error exits 1 silently (there is nowhere left to report it).
28
+ * The bin shim installs this once, before `run()`.
29
+ */
30
+ export declare function handleOutputErrors(streams?: OutputStreams, exit?: (code: number) => void): void;
14
31
  export declare const defaultIO: CliIO;
15
- //# sourceMappingURL=io.d.ts.map
@@ -1,8 +1,29 @@
1
1
  // I/O seam for the CLI. Everything the CLI writes goes through a CliIO object so
2
2
  // tests can capture output instead of hitting the real stdout/stderr, and the
3
3
  // environment is injected so tests never depend on the real process.env.
4
+ /**
5
+ * Handle write errors on stdout/stderr, which Node otherwise reports as an
6
+ * unhandled 'error' event: a raw stack trace and exit 1.
7
+ *
8
+ * A reader that stops early — `| head`, `| jq` exiting on the first match, a closed
9
+ * pager — closes the pipe while the CLI is still writing, and the next write fails
10
+ * with EPIPE. That is ordinary use, so the process exits 0 at once, quietly. Any
11
+ * other stdout error prints one `Output error: <message>` line to stderr and exits
12
+ * 1; any other stderr error exits 1 silently (there is nowhere left to report it).
13
+ * The bin shim installs this once, before `run()`.
14
+ */
15
+ export function handleOutputErrors(streams = process, exit = (code) => process.exit(code)) {
16
+ streams.stdout.on("error", (err) => {
17
+ if (err.code === "EPIPE")
18
+ return exit(0);
19
+ process.stderr.write(`Output error: ${err.message}\n`);
20
+ exit(1);
21
+ });
22
+ streams.stderr.on("error", (err) => {
23
+ exit(err.code === "EPIPE" ? 0 : 1);
24
+ });
25
+ }
4
26
  export const defaultIO = {
5
27
  out: (text) => process.stdout.write(text + "\n"),
6
28
  err: (text) => process.stderr.write(text + "\n"),
7
29
  };
8
- //# sourceMappingURL=io.js.map
@@ -4,4 +4,3 @@ export declare const VERSION: string;
4
4
  /** Default dependencies: real client + real stdout/stderr + real environment. */
5
5
  export declare const defaultDeps: CliDeps;
6
6
  export declare function buildProgram(deps?: CliDeps): Command;
7
- //# sourceMappingURL=program.d.ts.map
@@ -6,9 +6,10 @@ import { fileURLToPath } from "node:url";
6
6
  import { Command, InvalidArgumentError, Option } from "commander";
7
7
  import { defaultIO } from "./io.js";
8
8
  import { CkanClient } from "../client/client.js";
9
- import { DEFAULT_BASE_URL } from "../client/engine.js";
9
+ import { DEFAULT_BASE_URL, MAX_RETRIES, MAX_RETRY_AFTER_MS } from "../client/engine.js";
10
10
  import { MAX_TIMEOUT_MS } from "../client/http.js";
11
- import { parseBaseUrl, parseBoundedInt, parseIntArg, parsePortal } from "./shared.js";
11
+ import { redactUrl } from "../client/errors.js";
12
+ import { parseBaseUrl, parseBoundedInt, parseHeaderValue, parseIntArg, parsePortal } from "./shared.js";
12
13
  import { registerCatalogueCommands } from "./commands/catalogue.js";
13
14
  import { registerPortalCommands } from "./commands/portal.js";
14
15
  /**
@@ -36,24 +37,39 @@ export const defaultDeps = {
36
37
  };
37
38
  export function buildProgram(deps = defaultDeps) {
38
39
  const program = new Command();
40
+ const baseUrlDefault = deps.env["CKAN_BASE_URL"] || DEFAULT_BASE_URL;
39
41
  program
40
42
  .name("ckan")
41
43
  .description("CLI for any CKAN open-data portal (Action API v3)")
42
44
  .version(VERSION)
43
- .option("--base-url <url>", "CKAN site URL (env CKAN_BASE_URL)", parseBaseUrl, deps.env["CKAN_BASE_URL"] || DEFAULT_BASE_URL)
45
+ .addOption(new Option("--base-url <url>", "CKAN site URL (env CKAN_BASE_URL)")
46
+ .argParser(parseBaseUrl)
47
+ // The help shows the default without userinfo: a password in
48
+ // CKAN_BASE_URL must not end up in `--help` output or CI logs.
49
+ .default(baseUrlDefault, JSON.stringify(redactUrl(baseUrlDefault))))
44
50
  .addOption(new Option("--portal <id>", "a known portal by id (see `ckan portals`)")
45
51
  .argParser(parsePortal)
46
52
  .conflicts("baseUrl"))
47
53
  .option("--timeout <ms>", "per-request timeout in milliseconds", parseBoundedInt(0, MAX_TIMEOUT_MS))
48
- .option("--user-agent <ua>", "User-Agent header value")
49
- .option("--max-retries <n>", "retries for transient 429/503 responses", parseIntArg)
54
+ .option("--user-agent <ua>", "User-Agent header value", parseHeaderValue)
55
+ .option("--max-retries <n>", `retries for transient 429/503 responses (0..${MAX_RETRIES}; each waits the server's Retry-After, up to ${MAX_RETRY_AFTER_MS / 1000} s)`, parseBoundedInt(0, MAX_RETRIES))
50
56
  .option("--max-response-bytes <n>", "cap response body size in bytes (0 = unlimited; default 100 MiB)", parseIntArg)
51
57
  .option("--compact", "print JSON on a single line instead of pretty-printed")
52
58
  .showHelpAfterError();
53
59
  // A bare invocation (no subcommand) should print help to stdout and exit 0,
54
60
  // matching `ckan help` / `ckan --help`. Without an explicit root action,
55
61
  // commander writes help to stderr and exits 1 for the empty-command case.
62
+ // A root action turns off two things commander otherwise does for a program
63
+ // with subcommands, so both are restored: the implicit `help [command]`
64
+ // subcommand (helpCommand(true)), and the "unknown command" error — the
65
+ // action receives the stray operand (allowExcessArguments below) and reports
66
+ // it, instead of commander's "too many arguments".
67
+ program.helpCommand(true);
56
68
  program.action(() => {
69
+ const [unknown] = program.args;
70
+ if (unknown !== undefined) {
71
+ program.error(`error: unknown command '${unknown}'`, { code: "commander.unknownCommand" });
72
+ }
57
73
  program.help();
58
74
  });
59
75
  // commander runs value parsers on flags but not on defaults, so a base URL
@@ -72,6 +88,8 @@ export function buildProgram(deps = defaultDeps) {
72
88
  });
73
89
  registerCatalogueCommands(program, deps);
74
90
  registerPortalCommands(program, deps);
91
+ // Set after the subcommands exist (they copy this setting when created), so it
92
+ // applies to the root only: a stray operand reaches the root action above.
93
+ program.allowExcessArguments(true);
75
94
  return program;
76
95
  }
77
- //# sourceMappingURL=program.js.map
@@ -1,3 +1,2 @@
1
1
  import type { CliDeps } from "./io.js";
2
2
  export declare function run(argv: string[], deps?: CliDeps): Promise<number>;
3
- //# sourceMappingURL=run.d.ts.map
@@ -3,7 +3,9 @@
3
3
  // captured output and exit code without spawning a subprocess.
4
4
  import { CommanderError } from "commander";
5
5
  import { buildProgram, defaultDeps } from "./program.js";
6
- import { CkanApiError, CkanError } from "../client/errors.js";
6
+ import { CkanApiError, CkanError, CkanValidationError } from "../client/errors.js";
7
+ /** The exit code of a usage error: commander's own for a rejected option value. */
8
+ const USAGE_EXIT = 1;
7
9
  /**
8
10
  * Apply exitOverride + output redirection to every command in the tree.
9
11
  * commander does not propagate these to subcommands, so a parse error on a
@@ -30,6 +32,12 @@ export async function run(argv, deps = defaultDeps) {
30
32
  // Help/version requests exit 0; genuine parse errors carry their own code.
31
33
  return err.exitCode;
32
34
  }
35
+ if (err instanceof CkanValidationError) {
36
+ // An input the library refused before any request (a rule the commander
37
+ // parsers do not see, e.g. one across parameters): a usage error.
38
+ deps.io.err(`Error: ${err.message}`);
39
+ return USAGE_EXIT;
40
+ }
33
41
  if (err instanceof CkanApiError) {
34
42
  deps.io.err(`Error: ${err.message}`);
35
43
  // Map a few notable statuses to distinct exit codes for scripting.
@@ -45,4 +53,3 @@ export async function run(argv, deps = defaultDeps) {
45
53
  return 1;
46
54
  }
47
55
  }
48
- //# sourceMappingURL=run.js.map
@@ -1,22 +1,36 @@
1
1
  import type { CliDeps } from "./io.js";
2
- import type { EngineOptions } from "../client/engine.js";
2
+ import { type EngineOptions } from "../client/engine.js";
3
3
  /** commander value-parser: a non-negative integer. */
4
4
  export declare function parseIntArg(value: string): number;
5
5
  /**
6
- * commander value-parser: a value that is not blank. A blank filter would
7
- * otherwise be dropped and the command would silently run unfiltered.
6
+ * commander value-parser: a value that is not blank (the library's blankProblem
7
+ * rule, reported as a usage error before the client is built).
8
8
  */
9
9
  export declare function parseNonEmpty(value: string): string;
10
- /** commander accumulator for a repeatable option whose values must not be blank. */
10
+ /**
11
+ * commander value-parser for a value that ends up in an HTTP header (`--user-agent`):
12
+ * the library's headerValueProblem rule (not blank, no control characters but tab,
13
+ * nothing above U+00FF), reported as a usage error.
14
+ */
15
+ export declare function parseHeaderValue(value: string): string;
16
+ /**
17
+ * commander value-parser for a text option's value: not blank, and not another
18
+ * long option. commander takes the next argument as the value of an option that
19
+ * needs one, even when it is a flag, so a forgotten value (`search --fq --rows 5`)
20
+ * silently shifted the rest into the query (`fq=--rows`, `q=5`) and still exited
21
+ * 0. No CKAN filter, sort, facet field or tag query starts with `--`; a single `-`
22
+ * (a negated Solr filter, `-organization:x`) stays allowed.
23
+ */
24
+ export declare function parseOptionValue(value: string): string;
25
+ /** commander accumulator for a repeatable option whose values are checked by parseOptionValue. */
11
26
  export declare function collectNonEmpty(value: string, previous?: string[]): string[];
12
- /** Build a commander value-parser for a non-negative integer within [min, max]. */
27
+ /** Build a commander value-parser for a non-negative integer within [min, max] (the library's intRangeProblem). */
13
28
  export declare function parseBoundedInt(min: number, max: number): (value: string) => number;
14
29
  /**
15
- * commander value-parser for --base-url: reject a non-http(s) scheme at parse
16
- * time so `file:`, `ftp:`, etc. fail fast with a usage error rather than only
17
- * being caught later in the transport. The default transport also re-checks the
18
- * scheme per hop (and RequestEngine.buildUrl guards it for custom transports),
19
- * but this surfaces the mistake up front and independently of the transport.
30
+ * commander value-parser for --base-url (and CKAN_BASE_URL, via the preAction hook
31
+ * in program.ts): the library's baseUrlProblem rule (not blank, no whitespace, an
32
+ * absolute http(s) URL, no query string or fragment), reported as a usage error
33
+ * before the client is built.
20
34
  */
21
35
  export declare function parseBaseUrl(value: string): string;
22
36
  /** commander value-parser for --portal: the URL of a portal in the built-in list. */
@@ -34,9 +48,10 @@ export interface GlobalOptions {
34
48
  /** Translate resolved global CLI options into client EngineOptions. */
35
49
  export declare function toEngineOptions(global: GlobalOptions): EngineOptions;
36
50
  /**
37
- * Escape the control characters JSON.stringify leaves raw. It escapes C0 (including
38
- * ESC) but not DEL or the C1 range U+0080–U+009F, and terminals may act on those —
39
- * U+009B is the 8-bit form of CSI. The output is server data, so escape them; the
51
+ * Escape the characters JSON.stringify leaves raw although a terminal acts on them.
52
+ * It escapes C0 (including ESC) but not DEL, the C1 range U+0080–U+009F (U+009B is
53
+ * the 8-bit form of CSI) or the bidi formatting characters (isBidiControl), which
54
+ * reorder the text that follows. The output is server data, so escape them; the
40
55
  * result is equivalent, valid JSON (these characters only occur inside strings).
41
56
  * Checked by char code so the source stays free of control bytes.
42
57
  */
@@ -58,4 +73,3 @@ export interface ActionContext {
58
73
  * the trailing options object and command instance to recover the positionals.
59
74
  */
60
75
  export declare function action(deps: CliDeps, fn: (ctx: ActionContext, positionals: string[]) => Promise<void>): (...args: unknown[]) => Promise<void>;
61
- //# sourceMappingURL=shared.d.ts.map