@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.
- package/README.md +28 -14
- package/dist/src/cli/commands/catalogue.d.ts +1 -2
- package/dist/src/cli/commands/catalogue.js +22 -9
- package/dist/src/cli/commands/portal.d.ts +0 -1
- package/dist/src/cli/commands/portal.js +18 -10
- package/dist/src/cli/index.d.ts +0 -1
- package/dist/src/cli/index.js +2 -1
- package/dist/src/cli/io.d.ts +17 -1
- package/dist/src/cli/io.js +22 -1
- package/dist/src/cli/program.d.ts +0 -1
- package/dist/src/cli/program.js +24 -6
- package/dist/src/cli/run.d.ts +0 -1
- package/dist/src/cli/run.js +9 -2
- package/dist/src/cli/shared.d.ts +28 -14
- package/dist/src/cli/shared.js +78 -40
- package/dist/src/client/client.d.ts +13 -6
- package/dist/src/client/client.js +100 -35
- package/dist/src/client/engine.d.ts +79 -6
- package/dist/src/client/engine.js +188 -74
- package/dist/src/client/errors.d.ts +13 -1
- package/dist/src/client/errors.js +30 -3
- package/dist/src/client/http.d.ts +0 -1
- package/dist/src/client/http.js +44 -36
- package/dist/src/client/index.d.ts +6 -5
- package/dist/src/client/index.js +4 -4
- package/dist/src/client/portals-list.d.ts +0 -1
- package/dist/src/client/portals-list.js +0 -1
- package/dist/src/client/portals.d.ts +35 -2
- package/dist/src/client/portals.js +50 -3
- package/dist/src/client/query.d.ts +0 -1
- package/dist/src/client/query.js +0 -1
- package/dist/src/client/types.d.ts +5 -1
- package/dist/src/client/types.js +0 -1
- package/dist/src/client/validate.d.ts +55 -0
- package/dist/src/client/validate.js +119 -0
- package/dist/src/index.d.ts +0 -1
- package/dist/src/index.js +0 -1
- package/package.json +2 -1
- package/dist/src/cli/commands/catalogue.d.ts.map +0 -1
- package/dist/src/cli/commands/catalogue.js.map +0 -1
- package/dist/src/cli/commands/portal.d.ts.map +0 -1
- package/dist/src/cli/commands/portal.js.map +0 -1
- package/dist/src/cli/index.d.ts.map +0 -1
- package/dist/src/cli/index.js.map +0 -1
- package/dist/src/cli/io.d.ts.map +0 -1
- package/dist/src/cli/io.js.map +0 -1
- package/dist/src/cli/program.d.ts.map +0 -1
- package/dist/src/cli/program.js.map +0 -1
- package/dist/src/cli/run.d.ts.map +0 -1
- package/dist/src/cli/run.js.map +0 -1
- package/dist/src/cli/shared.d.ts.map +0 -1
- package/dist/src/cli/shared.js.map +0 -1
- package/dist/src/client/client.d.ts.map +0 -1
- package/dist/src/client/client.js.map +0 -1
- package/dist/src/client/engine.d.ts.map +0 -1
- package/dist/src/client/engine.js.map +0 -1
- package/dist/src/client/errors.d.ts.map +0 -1
- package/dist/src/client/errors.js.map +0 -1
- package/dist/src/client/http.d.ts.map +0 -1
- package/dist/src/client/http.js.map +0 -1
- package/dist/src/client/index.d.ts.map +0 -1
- package/dist/src/client/index.js.map +0 -1
- package/dist/src/client/portals-list.d.ts.map +0 -1
- package/dist/src/client/portals-list.js.map +0 -1
- package/dist/src/client/portals.d.ts.map +0 -1
- package/dist/src/client/portals.js.map +0 -1
- package/dist/src/client/query.d.ts.map +0 -1
- package/dist/src/client/query.js.map +0 -1
- package/dist/src/client/types.d.ts.map +0 -1
- package/dist/src/client/types.js.map +0 -1
- package/dist/src/index.d.ts.map +0 -1
- 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:
|
|
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 ""
|
|
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
|
|
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
|
-
|
|
180
|
-
`
|
|
181
|
-
<https://suche.transparenz.hamburg.de/api/rest/enums
|
|
182
|
-
|
|
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:
|
|
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`
|
|
229
|
-
| `4` | not found (HTTP `404`)
|
|
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,9 +1,23 @@
|
|
|
1
1
|
// Commands over the catalogue: datasets, their resources, publishers, themes
|
|
2
2
|
// and tags.
|
|
3
|
-
import {
|
|
4
|
-
|
|
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
|
-
|
|
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"',
|
|
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",
|
|
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",
|
|
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",
|
|
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",
|
|
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,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 {
|
|
4
|
+
import { checkPortals } from "../../client/portals.js";
|
|
5
5
|
import { PORTALS } from "../../client/portals-list.js";
|
|
6
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
56
|
-
|
|
57
|
-
|
|
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
|
package/dist/src/cli/index.d.ts
CHANGED
package/dist/src/cli/index.js
CHANGED
|
@@ -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
|
package/dist/src/cli/io.d.ts
CHANGED
|
@@ -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
|
package/dist/src/cli/io.js
CHANGED
|
@@ -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
|
package/dist/src/cli/program.js
CHANGED
|
@@ -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 {
|
|
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
|
-
.
|
|
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>",
|
|
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
|
package/dist/src/cli/run.d.ts
CHANGED
package/dist/src/cli/run.js
CHANGED
|
@@ -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
|
package/dist/src/cli/shared.d.ts
CHANGED
|
@@ -1,22 +1,36 @@
|
|
|
1
1
|
import type { CliDeps } from "./io.js";
|
|
2
|
-
import type
|
|
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
|
|
7
|
-
*
|
|
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
|
-
/**
|
|
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
|
|
16
|
-
*
|
|
17
|
-
*
|
|
18
|
-
*
|
|
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
|
|
38
|
-
* ESC) but not DEL
|
|
39
|
-
*
|
|
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
|