@maschinenlesbar.org/marktstammdatenregister-cli 0.0.8 → 0.2.0

package/README.md

@@ -27,14 +27,16 @@ npm install -g @maschinenlesbar.org/marktstammdatenregister-cli   # the `mastr`
 npm install @maschinenlesbar.org/marktstammdatenregister-cli
 ```
 
+Requires **Node.js 22.12+**.
+
 ## CLI
 
 Four datasets, each paged and filterable. Prints `{ total, data }` (or just the
 count with `--total`).
 
 ```bash
-mastr stromerzeugung --total                       # how many electricity-generation units? → 9063887
-mastr stromerzeugung --filter "Energieträger~eq~'2495'" --total   # …how many are solar? → 6267133
+mastr stromerzeugung --total                       # how many electricity-generation units? → 9562366 (2026-10-05; it grows)
+mastr stromerzeugung --filter "Energieträger~eq~'2495'" --total   # …how many are solar? → 6545851
 mastr stromerzeugung --sort "Bruttoleistung-desc" --page-size 20 --iso-dates
 mastr gaserzeugung --page 1 --page-size 50
 mastr filters stromerzeugung                        # the filterable columns + dropdown codes
@@ -46,12 +48,15 @@ Categories: `stromerzeugung`, `stromverbrauch`, `gaserzeugung`, `gasverbrauch`.
 (ops `eq|neq|sw|ct|nct|ew|null|nn`, plus the strict `gt`/`lt` for numbers and dates);
 there is **no working `~or~`** (the register drops everything after it, so the CLI
 rejects it) — for several codes of one dropdown, list them in one value:
-`Energieträger~eq~'2497,2498'`. Discover the German field names and dropdown codes with `mastr filters <category>`. A
-**wrong `FilterName` is silently ignored** (you get the unfiltered set), and a **wrong
-`--sort` key returns 0 rows**; a malformed spec or an unknown operator (e.g. `gte`) is
-rejected before any request (exit 2), because the register would answer it with a wrong
-count. Verify filter names
-with `mastr filters` and sanity-check with `--total`; sort keys are record field names
+`Energieträger~eq~'2497,2498'`. Discover the German field names and dropdown codes with `mastr filters <category>`.
+The register silently ignores a FilterName it doesn't know (you'd get the unfiltered set)
+and answers an unknown dropdown code with 0 rows, so the CLI checks every FilterName and
+every `eq`/`neq` dropdown code against the category's columns (one extra request) and
+rejects an unknown one (exit 2, with "did you mean"); a name typed with a decomposed umlaut,
+padding or in another case is sent the register's way. A malformed spec or an unknown
+operator (e.g. `gte`) is rejected too. Several `--filter` flags are joined with `~and~`;
+any other option given twice is a usage error. A **wrong `--sort` key returns 0 rows**:
+sanity-check with `--total`; sort keys are record field names
 (`Bruttoleistung`), not FilterNames — list them with
 `mastr stromerzeugung --page-size 1 --compact | jq '.data[0] | keys'`. **Dates** come as Microsoft
 `/Date(ms)/` strings — add `--iso-dates` to convert them to ISO-8601.
@@ -67,9 +72,15 @@ import { MastrClient, parseMsDate } from "@maschinenlesbar.org/marktstammdatenre
 const mastr = new MastrClient();
 const solar = await mastr.stromerzeugung({ filter: "Energieträger~eq~'2495'", pageSize: 10 });
 solar.total; // total matching units
+await mastr.count("stromerzeugung", { filter: "Energieträger~eq~'2495'" }); // just the count, one-row request
 parseMsDate(String(solar.data[0]?.EinheitRegistrierungsdatum)); // Date | null
 ```
 
+The client checks a filter's FilterNames and dropdown codes against the category's columns
+(`filterColumns()`, fetched once per client and category) and throws `MastrValidationError`
+for one the register would ignore; `new MastrClient({ allowUnknownFilters: true })` skips that
+check and its request. A query key it doesn't know (`filtr`) is refused the same way.
+
 Build filters from user input with `buildFilter`, not string interpolation: a filter
 value cannot contain `~` (the register splits on it and has no escape), so
 `` `Ort~eq~'${input}'` `` lets an input like `Münster'~and~Energieträger~eq~'2497` add a

package/dist/src/cli/commands/units.d.ts

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

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

@@ -3,7 +3,7 @@
 // `filters` command to discover the filterable columns and their dropdown codes.
 import { Argument } from "commander";
 import { MAX_PAGE, MAX_PAGE_SIZE } from "../../client/client.js";
-import { action, parseBoundedInt, parseFilter, parseNonEmpty, renderJson } from "../shared.js";
+import { action, once, parseBoundedInt, parseFilter, parseSort, renderJson } from "../shared.js";
 // `sortKey` is a record field that exists in that category's rows (live 2026-09-26):
 // only stromerzeugung rows carry Bruttoleistung/Nettonennleistung, so the stderr hint
 // must not suggest it for the other three.
@@ -19,21 +19,22 @@ const RUN = {
     gaserzeugung: (c, q) => c.gaserzeugung(q),
     gasverbrauch: (c, q) => c.gasverbrauch(q),
 };
+/** Build a CountQuery (filter and sort) from this command's parsed options. */
+function buildCountQuery(opts) {
+    const q = {};
+    if (typeof opts["sort"] === "string")
+        q.sort = opts["sort"];
+    if (typeof opts["filter"] === "string")
+        q.filter = opts["filter"];
+    return q;
+}
 /** Build a UnitQuery from this command's parsed options. */
 function buildQuery(opts) {
-    const q = {};
+    const q = buildCountQuery(opts);
     if (typeof opts["page"] === "number")
         q.page = opts["page"];
     if (typeof opts["pageSize"] === "number")
         q.pageSize = opts["pageSize"];
-    if (typeof opts["sort"] === "string")
-        q.sort = opts["sort"];
-    if (typeof opts["filter"] === "string")
-        q.filter = opts["filter"];
-    // `--total` needs only the match count (returned regardless of page size), so
-    // request a single row instead of fetching and discarding a full page.
-    if (opts["total"] === true)
-        q.pageSize = 1;
     return q;
 }
 export function registerCommands(program, deps) {
@@ -41,16 +42,22 @@ export function registerCommands(program, deps) {
         program
             .command(cat.name)
             .description(cat.desc)
-            .option("--page <n>", "1-based page number", parseBoundedInt(1, MAX_PAGE), 1)
-            .option("--page-size <n>", `rows per page (1..${MAX_PAGE_SIZE})`, parseBoundedInt(1, MAX_PAGE_SIZE), 25)
+            .option("--page <n>", "1-based page number", once("--page", parseBoundedInt(1, MAX_PAGE)), 1)
+            .option("--page-size <n>", `rows per page (1..${MAX_PAGE_SIZE})`, once("--page-size", parseBoundedInt(1, MAX_PAGE_SIZE)), 25)
             .option("--sort <spec>", "sort: FieldKey-asc | FieldKey-desc, where FieldKey is a record field name, not a " +
-            `FilterName (e.g. ${cat.sortKey}-desc)`, parseNonEmpty)
+            `FilterName (e.g. ${cat.sortKey}-desc)`, once("--sort", parseSort))
             .option("--filter <spec>", "filter: FilterName~op~'value'~and~… (see `filters`; ops eq|neq|sw|ct|nct|ew|null|nn|gt|lt, " +
-            "gt/lt strict; null/nn take ''). A malformed spec or unknown op is rejected. No ~or~: " +
-            "for several dropdown codes use one comma list, e.g. Energieträger~eq~'2497,2498'", parseFilter)
-            .option("--total", "print only the total match count, not the rows")
+            "gt/lt strict; null/nn take ''). A malformed spec, an unknown op, a FilterName the " +
+            "category doesn't have or a dropdown code it doesn't list is rejected. Repeatable: " +
+            "several --filter are joined with ~and~. No ~or~: for several dropdown codes use one " +
+            "comma list, e.g. Energieträger~eq~'2497,2498'", parseFilter)
+            .option("--total", "print only the total match count, not the rows (a one-row request; --page and --page-size are ignored)")
             .action(action(deps, async ({ client, global, opts }) => {
-            const page = await RUN[cat.name](client, buildQuery(opts));
+            // `--total` is the library's count(): a one-row request for the match count.
+            const total = opts["total"] === true
+                ? await client.count(cat.name, buildCountQuery(opts))
+                : undefined;
+            const page = total === undefined ? await RUN[cat.name](client, buildQuery(opts)) : { total };
             // An unknown --sort key or --filter operator makes the server return 0 rows
             // (not an error), which reads like "no matches". Nudge the user toward the
             // likely cause. Sort keys are the record's field names (`Bruttoleistung`);
@@ -61,14 +68,14 @@ export function registerCommands(program, deps) {
                     "not the FilterNames from `mastr filters`; list them with " +
                     `\`mastr ${cat.name} --page-size 1 --compact | jq '.data[0] | keys'\`.`);
             }
-            // An unknown operator is already a usage error (filterProblem); what is left
-            // that silently gives 0 rows is a value the register can't match.
+            // An unknown operator, FilterName or dropdown code is already a usage error; what
+            // is left that silently gives 0 rows is a value the register can't match.
             if (page.total === 0 && typeof opts["filter"] === "string") {
-                deps.io.err("Note: 0 results with --filter set. If you expected matches, check the values: a " +
-                    "dropdown takes its code (the Value from `mastr filters`), not its label, decimals " +
-                    "take a point ('4999.999'), and gt/lt are strict.");
+                deps.io.err("Note: 0 results with --filter set. If you expected matches, check the values: eq " +
+                    "on a text column matches the whole text (ct matches a part), decimals take a " +
+                    "point ('4999.999'), and gt/lt are strict.");
             }
-            renderJson(deps, global, opts["total"] === true ? page.total : page);
+            renderJson(deps, global, total ?? page);
         }));
     }
     program
@@ -79,4 +86,3 @@ export function registerCommands(program, deps) {
         renderJson(deps, global, await client.filterColumns(category));
     }));
 }
-//# sourceMappingURL=units.js.map

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

@@ -1,3 +1,2 @@
 #!/usr/bin/env node
 export {};
-//# sourceMappingURL=index.d.ts.map

package/dist/src/cli/index.js

@@ -1,11 +1,13 @@
 #!/usr/bin/env node
 // Bin shim: parse argv, run the CLI, and set the process exit code. All real
 // logic lives in run.ts (testable without spawning a subprocess).
+import { handleOutputErrors } from "./io.js";
 import { run } from "./run.js";
+// Before run(): a reader that closes the pipe early (`| head`) must not end in a stack trace.
+handleOutputErrors();
 run(process.argv.slice(2)).then((code) => {
     process.exitCode = code;
 }, (err) => {
     process.stderr.write(`Unexpected error: ${err instanceof Error ? err.message : String(err)}\n`);
     process.exitCode = 1;
 });
-//# sourceMappingURL=index.js.map

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

@@ -8,5 +8,22 @@ export interface CliDeps {
     /** Build a client from the resolved global options (injectable for tests). */
     createClient(options: MastrClientOptions): MastrClient;
 }
+/** The two process streams, as far as `handleOutputErrors` needs them. */
+export interface OutputStreams {
+    stdout: Pick<NodeJS.WriteStream, "on">;
+    stderr: Pick<NodeJS.WriteStream, "on">;
+}
+/**
+ * Handle write errors on stdout/stderr, which Node otherwise reports as an
+ * unhandled 'error' event: a raw stack trace and exit 1.
+ *
+ * A reader that stops early — `| head`, `| jq` exiting on the first match, a closed
+ * pager — closes the pipe while the CLI is still writing, and the next write fails
+ * with EPIPE. That is ordinary use, so the process exits 0 at once, quietly. Any
+ * other stdout error prints one `Output error: <message>` line to stderr and exits
+ * 1. On stderr an EPIPE is ignored, so a failed run keeps its exit code; any other stderr
+ * error exits 1 silently (there is nowhere left to report it).
+ * The bin shim installs this once, before `run()`.
+ */
+export declare function handleOutputErrors(streams?: OutputStreams, exit?: (code: number) => void): void;
 export declare const defaultIO: CliIO;
-//# sourceMappingURL=io.d.ts.map

package/dist/src/cli/io.js

@@ -1,7 +1,32 @@
 // 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.
+/**
+ * Handle write errors on stdout/stderr, which Node otherwise reports as an
+ * unhandled 'error' event: a raw stack trace and exit 1.
+ *
+ * A reader that stops early — `| head`, `| jq` exiting on the first match, a closed
+ * pager — closes the pipe while the CLI is still writing, and the next write fails
+ * with EPIPE. That is ordinary use, so the process exits 0 at once, quietly. Any
+ * other stdout error prints one `Output error: <message>` line to stderr and exits
+ * 1. On stderr an EPIPE is ignored, so a failed run keeps its exit code; any other stderr
+ * error exits 1 silently (there is nowhere left to report it).
+ * The bin shim installs this once, before `run()`.
+ */
+export function handleOutputErrors(streams = process, exit = (code) => process.exit(code)) {
+    streams.stdout.on("error", (err) => {
+        if (err.code === "EPIPE")
+            return exit(0);
+        process.stderr.write(`Output error: ${err.message}\n`);
+        exit(1);
+    });
+    // stderr's reader going away doesn't make a failed run a success: ignore EPIPE there and
+    // let the run's own exit code stand (`2>&1 | true` must not turn a usage error into 0).
+    streams.stderr.on("error", (err) => {
+        if (err.code !== "EPIPE")
+            exit(1);
+    });
+}
 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/program.d.ts

@@ -4,4 +4,3 @@ export declare const VERSION: string;
 /** Default dependencies: real client + real stdout/stderr. */
 export declare const defaultDeps: CliDeps;
 export declare function buildProgram(deps?: CliDeps): Command;
-//# sourceMappingURL=program.d.ts.map

package/dist/src/cli/program.js

@@ -7,7 +7,8 @@ import { Command } from "commander";
 import { defaultIO } from "./io.js";
 import { MastrClient } from "../client/client.js";
 import { MAX_TIMEOUT_MS } from "../client/http.js";
-import { parseIntArg, parseBoundedInt, parseHeaderValue, parseBaseUrl } from "./shared.js";
+import { MAX_RETRIES } from "../client/engine.js";
+import { once, parseIntArg, parseBoundedInt, parseHeaderValue, parseBaseUrl } from "./shared.js";
 import { registerCommands } from "./commands/units.js";
 /**
  * Single source of truth for the version: read from package.json at runtime
@@ -41,15 +42,14 @@ export function buildProgram(deps = defaultDeps) {
         "and narrowed with --filter (see `filters` for the field names and codes). Use " +
         "--total for just the match count, and --iso-dates to convert /Date(…)/ timestamps.")
         .version(VERSION)
-        .option("--base-url <url>", "API base URL (http/https only)", parseBaseUrl, "https://www.marktstammdatenregister.de/MaStR")
-        .option("--timeout <ms>", "time limit per request in ms, whole response included (0 = no timeout)", parseBoundedInt(0, MAX_TIMEOUT_MS))
-        .option("--user-agent <ua>", "User-Agent header value", parseHeaderValue)
-        .option("--max-retries <n>", "retries for transient 429/503 responses (0..10; each waits the server's Retry-After, up to 30 s)", parseBoundedInt(0, 10))
-        .option("--max-response-bytes <n>", "cap response body size in bytes (0 = unlimited; default 100 MiB)", parseIntArg)
+        .option("--base-url <url>", "API base URL (http/https only)", once("--base-url", parseBaseUrl), "https://www.marktstammdatenregister.de/MaStR")
+        .option("--timeout <ms>", "time limit per request in ms, whole response included (0 = no timeout)", once("--timeout", parseBoundedInt(0, MAX_TIMEOUT_MS)))
+        .option("--user-agent <ua>", "User-Agent header value", once("--user-agent", parseHeaderValue))
+        .option("--max-retries <n>", `retries for transient 429/503 responses and reset connections (0..${MAX_RETRIES}; each waits the server's Retry-After, up to 30 s)`, once("--max-retries", parseBoundedInt(0, MAX_RETRIES)))
+        .option("--max-response-bytes <n>", "cap response body size in bytes (0 = unlimited; default 100 MiB)", once("--max-response-bytes", parseIntArg))
         .option("--compact", "print JSON on a single line instead of pretty-printed")
         .option("--iso-dates", "rewrite MaStR /Date(ms)/ timestamps to ISO-8601")
         .showHelpAfterError();
     registerCommands(program, deps);
     return program;
 }
-//# sourceMappingURL=program.js.map

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

@@ -1,3 +1,12 @@
 import type { CliDeps } from "./io.js";
+/**
+ * `deps` with an `io` that redacts the credentials of every argument from everything it
+ * prints. Commander echoes rejected values in its errors (`option '--base-url <url>'
+ * argument '…' is invalid`, an unknown command, a surplus argument), so whatever path a
+ * credential takes to stdout or stderr, the exact userinfo (as `credentialsIn` finds it,
+ * plus its JSON-quoted form) is replaced by `***`. A pattern alone can't delimit a password
+ * with spaces, quotes, `#`, `?` or `/`; the exact strings can. Without credentials the
+ * output passes through unchanged.
+ */
+export declare function withRedactedOutput(deps: CliDeps, argv: readonly string[]): CliDeps;
 export declare function run(argv: string[], deps?: CliDeps): Promise<number>;
-//# sourceMappingURL=run.d.ts.map

package/dist/src/cli/run.js

@@ -3,7 +3,7 @@
 // captured output and exit code without spawning a subprocess.
 import { CommanderError } from "commander";
 import { buildProgram, defaultDeps } from "./program.js";
-import { MastrApiError, MastrError, MastrNetworkError, MastrValidationError, } from "../client/errors.js";
+import { MastrApiError, MastrError, MastrNetworkError, MastrValidationError, credentialsIn, redactCredentials, } from "../client/errors.js";
 /**
  * Process exit codes. Distinct codes let scripts tell apart a usage error, a
  * missing resource, a transport failure, and a catch-all.
@@ -32,7 +32,33 @@ function configureTree(command, deps) {
     for (const child of command.commands)
         configureTree(child, deps);
 }
+/**
+ * `deps` with an `io` that redacts the credentials of every argument from everything it
+ * prints. Commander echoes rejected values in its errors (`option '--base-url <url>'
+ * argument '…' is invalid`, an unknown command, a surplus argument), so whatever path a
+ * credential takes to stdout or stderr, the exact userinfo (as `credentialsIn` finds it,
+ * plus its JSON-quoted form) is replaced by `***`. A pattern alone can't delimit a password
+ * with spaces, quotes, `#`, `?` or `/`; the exact strings can. Without credentials the
+ * output passes through unchanged.
+ */
+export function withRedactedOutput(deps, argv) {
+    // An `--option=value` token is echoed as its value alone.
+    const values = argv.map((token) => token.startsWith("-") && token.includes("=") ? token.slice(token.indexOf("=") + 1) : token);
+    const secrets = new Set();
+    for (const source of [...argv, ...values]) {
+        for (const secret of credentialsIn(source)) {
+            secrets.add(secret);
+            secrets.add(JSON.stringify(secret).slice(1, -1));
+        }
+    }
+    if (secrets.size === 0)
+        return deps;
+    const list = [...secrets];
+    const redact = (text) => redactCredentials(text, list);
+    return { ...deps, io: { out: (text) => deps.io.out(redact(text)), err: (text) => deps.io.err(redact(text)) } };
+}
 export async function run(argv, deps = defaultDeps) {
+    deps = withRedactedOutput(deps, argv);
     const program = buildProgram(deps);
     configureTree(program, deps);
     // A bare invocation (no command) is a help request, not an error: print help
@@ -82,4 +108,3 @@ export async function run(argv, deps = defaultDeps) {
         return EXIT.OTHER;
     }
 }
-//# sourceMappingURL=run.js.map

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

@@ -1,5 +1,6 @@
 import type { CliDeps } from "./io.js";
 import type { MastrClientOptions } from "../client/client.js";
+import { type Problem } from "../client/validate.js";
 /**
  * commander value-parser: a plain base-10 non-negative integer.
  *
@@ -8,32 +9,47 @@ import type { MastrClientOptions } from "../client/client.js";
  * literals (`0x10`, `0b10`, `1e3`), signs, padding and decimals.
  */
 export declare function parseIntArg(value: string): number;
-/** commander value-parser: a non-empty (after trimming) string. */
-export declare function parseNonEmpty(value: string): string;
+/**
+ * Build a commander value-parser from a library rule: the rule's reason becomes the
+ * usage error, a valid value passes unchanged.
+ */
+export declare function parseWith(problem: Problem<string>): (value: string) => string;
+/** commander value-parser: a non-empty (after trimming) string (the library's `nonBlankProblem`). */
+export declare const parseNonEmpty: (value: string) => string;
+/** commander value-parser for `--sort`: the library's `sortProblem` (not blank). */
+export declare const parseSort: (value: string) => string;
 /**
  * commander value-parser for `--filter`: non-blank, and not a spec the register would
- * misread (see `filterProblem`), so it becomes a usage error before any request.
+ * misread (see `filterProblem`, run on the `normalizeFilter`ed spec as the client sends
+ * it), so it becomes a usage error before any request. The flag can be repeated: a second
+ * `--filter` is joined to the first with `~and~` (it used to replace it silently, and
+ * "solar in Bavaria" became "every unit in Bavaria"). The FilterNames and dropdown codes
+ * are checked by the client against the category's columns.
  */
-export declare function parseFilter(value: string): string;
+export declare function parseFilter(value: string, previous?: string): string;
 /**
- * commander value-parser for `--base-url`: non-empty and http/https-only.
- *
- * The transport already rejects any non-http(s) scheme, so this is defence in
- * depth — but doing the check at parse time turns a bad scheme (e.g. `file:` /
- * `data:` / `ftp:`) into a friendly usage error (exit 2) with the value the user
- * actually typed, rather than a network error (exit 6) echoing the fully built
- * request URL. The transport check stays the enforcement point for library callers.
+ * Wrap a value-parser so its option may be given only once: commander keeps the last of a
+ * repeated option and drops the others without a word (`--sort A --sort B` sorted by B,
+ * `--page 2 --page 3` fetched page 3). A repeat is a usage error naming the flag. A fresh
+ * program is built per `run()`, so the state lives as long as one parse.
+ */
+export declare function once<T>(flag: string, parse: (value: string) => T): (value: string) => T;
+/**
+ * commander value-parser for `--base-url`: the library's `baseUrlProblem` (non-blank,
+ * no whitespace, an absolute http(s) URL without a query or fragment), whose reason
+ * becomes a usage error (exit 2) naming the value the user typed. The CLI keeps no
+ * rules of its own; the client constructor enforces the same rule for library callers.
  */
-export declare function parseBaseUrl(value: string): string;
+export declare const parseBaseUrl: (value: string) => string;
 /** Build a commander value-parser for an integer constrained to [min, max]. */
 export declare function parseBoundedInt(min: number, max: number): (value: string) => number;
 /**
- * commander value-parser for a value that ends up in an HTTP header (User-Agent).
- * Rejects control characters — a CR/LF (or other C0/DEL byte) would otherwise reach
- * Node's HTTP layer and throw an opaque `ERR_INVALID_CHAR`. Tab (0x09) is allowed;
- * checked by char code so the source stays free of control bytes.
+ * commander value-parser for a value that ends up in an HTTP header (User-Agent):
+ * the library's `headerValueProblem` (not blank, Latin-1 without control
+ * characters; tab is fine), whose reason becomes the usage error. The engine runs
+ * the same rule on `userAgent`.
  */
-export declare function parseHeaderValue(value: string): string;
+export declare const parseHeaderValue: (value: string) => string;
 export interface GlobalOptions {
     baseUrl?: string;
     timeout?: number;
@@ -74,4 +90,3 @@ export interface ActionContext {
  * 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.js

@@ -3,8 +3,9 @@
 import { InvalidArgumentError } from "commander";
 import { isoifyDates } from "../client/client.js";
 import { MastrParseError } from "../client/errors.js";
-import { filterProblem } from "../client/filter.js";
+import { filterProblem, normalizeFilter } from "../client/filter.js";
 import { isBidiControl } from "../client/engine.js";
+import { baseUrlProblem, headerValueProblem, nonBlankProblem, sortProblem, } from "../client/validate.js";
 /**
  * commander value-parser: a plain base-10 non-negative integer.
  *
@@ -22,60 +23,59 @@ export function parseIntArg(value) {
     }
     return n;
 }
-/** commander value-parser: a non-empty (after trimming) string. */
-export function parseNonEmpty(value) {
-    if (value.trim() === "") {
-        throw new InvalidArgumentError("Expected a non-empty value.");
-    }
-    return value;
+/**
+ * Build a commander value-parser from a library rule: the rule's reason becomes the
+ * usage error, a valid value passes unchanged.
+ */
+export function parseWith(problem) {
+    return (value) => {
+        const reason = problem(value);
+        if (reason !== undefined)
+            throw new InvalidArgumentError(reason);
+        return value;
+    };
 }
+/** commander value-parser: a non-empty (after trimming) string (the library's `nonBlankProblem`). */
+export const parseNonEmpty = parseWith(nonBlankProblem);
+/** commander value-parser for `--sort`: the library's `sortProblem` (not blank). */
+export const parseSort = parseWith(sortProblem);
 /**
  * commander value-parser for `--filter`: non-blank, and not a spec the register would
- * misread (see `filterProblem`), so it becomes a usage error before any request.
+ * misread (see `filterProblem`, run on the `normalizeFilter`ed spec as the client sends
+ * it), so it becomes a usage error before any request. The flag can be repeated: a second
+ * `--filter` is joined to the first with `~and~` (it used to replace it silently, and
+ * "solar in Bavaria" became "every unit in Bavaria"). The FilterNames and dropdown codes
+ * are checked by the client against the category's columns.
  */
-export function parseFilter(value) {
+export function parseFilter(value, previous) {
     parseNonEmpty(value);
-    const problem = filterProblem(value);
+    const problem = filterProblem(normalizeFilter(value));
     if (problem !== undefined)
         throw new InvalidArgumentError(problem);
-    return value;
+    return previous === undefined ? value : `${previous}~and~${value}`;
 }
 /**
- * commander value-parser for `--base-url`: non-empty and http/https-only.
- *
- * The transport already rejects any non-http(s) scheme, so this is defence in
- * depth — but doing the check at parse time turns a bad scheme (e.g. `file:` /
- * `data:` / `ftp:`) into a friendly usage error (exit 2) with the value the user
- * actually typed, rather than a network error (exit 6) echoing the fully built
- * request URL. The transport check stays the enforcement point for library callers.
+ * Wrap a value-parser so its option may be given only once: commander keeps the last of a
+ * repeated option and drops the others without a word (`--sort A --sort B` sorted by B,
+ * `--page 2 --page 3` fetched page 3). A repeat is a usage error naming the flag. A fresh
+ * program is built per `run()`, so the state lives as long as one parse.
  */
-export function parseBaseUrl(value) {
-    const trimmed = value.trim();
-    if (trimmed === "") {
-        throw new InvalidArgumentError("Expected a non-empty value.");
-    }
-    let parsed;
-    try {
-        parsed = new URL(trimmed);
-    }
-    catch {
-        throw new InvalidArgumentError("Expected an absolute http(s) URL.");
-    }
-    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
-        throw new InvalidArgumentError("Only http and https URLs are supported.");
-    }
-    // Paths are appended to the base URL as a string, so a query or fragment would
-    // swallow every request path ("http://h/#f" requests "/" for every command).
-    if (/[?#]/.test(value)) {
-        throw new InvalidArgumentError("A base URL cannot have a query (?) or fragment (#).");
-    }
-    // new URL() trims surrounding whitespace silently; the raw value is what the
-    // engine uses, so reject it rather than guess.
-    if (value !== value.trim()) {
-        throw new InvalidArgumentError("A base URL cannot have surrounding whitespace.");
-    }
-    return value;
+export function once(flag, parse) {
+    let seen = false;
+    return (value) => {
+        if (seen)
+            throw new InvalidArgumentError(`${flag} was given more than once; give it once.`);
+        seen = true;
+        return parse(value);
+    };
 }
+/**
+ * commander value-parser for `--base-url`: the library's `baseUrlProblem` (non-blank,
+ * no whitespace, an absolute http(s) URL without a query or fragment), whose reason
+ * becomes a usage error (exit 2) naming the value the user typed. The CLI keeps no
+ * rules of its own; the client constructor enforces the same rule for library callers.
+ */
+export const parseBaseUrl = parseWith(baseUrlProblem);
 /** Build a commander value-parser for an integer constrained to [min, max]. */
 export function parseBoundedInt(min, max) {
     return (value) => {
@@ -88,20 +88,12 @@ export function parseBoundedInt(min, max) {
     };
 }
 /**
- * commander value-parser for a value that ends up in an HTTP header (User-Agent).
- * Rejects control characters — a CR/LF (or other C0/DEL byte) would otherwise reach
- * Node's HTTP layer and throw an opaque `ERR_INVALID_CHAR`. Tab (0x09) is allowed;
- * checked by char code so the source stays free of control bytes.
+ * commander value-parser for a value that ends up in an HTTP header (User-Agent):
+ * the library's `headerValueProblem` (not blank, Latin-1 without control
+ * characters; tab is fine), whose reason becomes the usage error. The engine runs
+ * the same rule on `userAgent`.
  */
-export function parseHeaderValue(value) {
-    for (let i = 0; i < value.length; i++) {
-        const c = value.charCodeAt(i);
-        if ((c < 0x20 && c !== 0x09) || c === 0x7f) {
-            throw new InvalidArgumentError("Value contains control characters.");
-        }
-    }
-    return value;
-}
+export const parseHeaderValue = parseWith(headerValueProblem);
 /** Translate resolved global CLI options into client options. */
 export function toEngineOptions(global) {
     const options = {};
@@ -176,4 +168,3 @@ export function action(deps, fn) {
         await fn({ client, global, opts: command.opts() }, positionals);
     };
 }
-//# sourceMappingURL=shared.js.map