@tikoci/centrs 0.1.2 → 0.1.4

package/commands/api/README.md

@@ -6,17 +6,18 @@ CDB / env / flags, validates the request through `/console/inspect`, runs the
 single REST or native-API operation, and returns the result in the standard
 envelope.
 
-Status: `CHR-passed` over `rest-api` and `native-api` (single-target),
-including open-ended `--stream` follow (native-api only), per `docs/MATRIX.md`;
-multi-target fan-out is a later phase. This file describes intent and flags; the
-matrix holds the cell states. Load-bearing rules — envelope, errors, settings
-precedence, identity, validation, protocol selection — live in
+Status: `CHR-passed` over `rest-api` and `native-api`, including multi-target
+fan-out and open-ended `--stream` follow (native-api only), per
+`docs/MATRIX.md`. This file describes intent and flags; the matrix holds the
+cell states. Load-bearing rules — envelope, errors, settings precedence,
+identity, validation, protocol selection — live in
 [`docs/CONSTITUTION.md`](../../docs/CONSTITUTION.md); the `(constitution: …)`
 notes below point there rather than restating them.
 
 `api` absorbs the former `stream` command: open-ended follow is `api <router>
 <endpoint> --stream` (or the `/listen` endpoint form). `--listen` is an accepted
-alias of `--stream`.
+alias of `--stream`. Streaming is single-session — it cannot combine with
+multi-target fan-out (see below).
 
 ## Where `api` sits — the verb trichotomy
 
@@ -56,27 +57,45 @@ when a bare-collection `POST` carries create-looking fields.
 
 ## Flags
 
-| Flag | Behavior |
-| ---- | -------- |
-| `-X` / `--method <verb>` | HTTP method, default `GET`, case-insensitive. |
-| `-f <key=value>` | String field, repeatable; assembled into the JSON body. Values pass through verbatim (no type-guessing). |
-| `-d` / `--data <json>` | Raw JSON request body. Collides with `-f` → `usage/conflicting-flags`. |
-| `--input <file\|->` | Read the raw JSON body from a file or stdin (`-`). |
-| `--query` / `--filter <expr>` | RouterOS-side row filter, AND-combined, repeatable. `name=value` (eq), `name!=value` (ne), `name>value`/`name<value` (cmp), `name` (has-property). Maps to REST `.query` words / native `?` words. |
-| `--raw-query <word>` | Verbatim RouterOS query word (repeatable) for OR / absence / stack expressions — e.g. `--raw-query type=ether --raw-query type=vlan --raw-query '#\|'` (OR). Emitted as-is; the caller owns the stack. |
-| `--attribute` / `--proplist <a,b>` | Property projection → `.proplist`. |
-| `--raw` | Strip the envelope; emit bare RouterOS JSON. Implies `--validate=false`; does **not** imply `--yes`. |
-| `--yes` | Confirm a mutating (non-read) request in non-interactive runs. |
-| `--stream` (alias `--listen`) | Native-api-only open-ended follow → NDJSON stream of envelopes, ending with a summary envelope. Inferred from a `/listen` endpoint. `--via rest-api --stream` errors `transport/capability-unsupported` (REST's 60 s cap cannot follow). |
-| `--duration <dur>` / `--count <n>` | Bound a `--stream`: stop after a wall-clock window / after N frames. |
-| `--validate[=false]` | Default `true`. Gate is `/console/inspect` (see Validation). |
-| `--via <protocol>` | `rest-api` (default) or `native-api`. No silent downgrade. |
-| `--format <json\|yaml\|text>` | Output format. Defaults to `json` for `api` (machine-first); `CENTRS_FORMAT` overrides. Under `--stream`, `json`/`yaml` emit one compact envelope per line (NDJSON); `text` emits a concise row per frame. |
-| target/auth | `--host`, `--port`, `--username`/`--user`/`-u`, `--password`, `--insecure`, `--timeout`, `--cdb-file`, `--cdb-password`, `--resolve <none\|arp>` — same single-target resolver as `retrieve`/`execute`. |
-
-Multi-target fan-out (`--group` / `--where` / `--all` / `--default` /
-`--concurrency`, reusing `src/core/fanout.ts`) lands in a later phase. When it
-does, `--stream` is single-session: N>1 targets → `usage/fanout-not-supported`.
+Implemented flags are generated from the CLI metadata into
+[`docs/CLI.md` → api](../../docs/CLI.md#api); this file does not duplicate
+that table, and `api` has no designed-but-unimplemented flags. Behavior notes
+the generated reference cannot carry:
+
+- `-f` values pass through verbatim (no type-guessing); `-d`/`--input`
+  collide with `-f` → `usage/conflicting-flags`.
+- `--query`/`--filter` map to REST `.query` words / native `?` words.
+- `--raw-query` is emitted as-is; the caller owns the stack — e.g.
+  `--raw-query type=ether --raw-query type=vlan --raw-query '#|'` (OR).
+- `--via rest-api --stream` errors `transport/capability-unsupported`
+  (REST's 60 s cap cannot follow).
+- Under `--stream`, `--format json`/`yaml` emit one compact envelope per
+  line (NDJSON); `text` emits a concise row per frame.
+- The target/auth flags (`--host`, `--port`, `--username`, `--password`,
+  `--insecure`, `--timeout`, `--cdb-file`, `--cdb-password`, `--resolve`)
+  use the same single-target resolver as `retrieve`/`execute`; `--quickchr`
+  resolves host/port/auth from the live `@tikoci/quickchr` descriptor
+  instead (constitution: resolution providers).
+
+## Fan-out (multi-target)
+
+Selecting more than one router — any selector flag (`--group` / `--where` /
+`--near` / `--bbox` / `--all` / `--default`) or more than one positional target — switches `api` into
+**fan-out mode** (`src/api-fanout.ts`, on the shared `src/core/fanout.ts` engine
+and the `src/resolver/selection.ts` grammar). A plain single-positional call
+stays the single-target envelope. Output is the locked `FanoutData` envelope
+(`data = { summary, targets[] }`; outer `ok` = orchestration success; per-target
+failures are inner `ok:false`), and the process exit code is granular: `0`
+all-ok, `2` partial, `1` orchestration error or every target failed. See
+`docs/CONSTITUTION.md` (Target selection) for the shared grammar and `--where`
+vs `--query` distinction.
+
+- **Writes fan out under `--yes`**, confirmed once up front (not per target).
+  Without `--yes`, the error names the blast radius (how many routers) and that
+  `--yes` is required.
+- **`--listen`/`--stream` is single-session** → `usage/fanout-not-supported` in
+  fan-out mode. **`--raw` strips the envelope** → `usage/conflicting-flags` in
+  fan-out mode (per-target envelopes can't be bare).
 
 ## Validation
 

package/commands/api/examples.md

@@ -1,11 +1,13 @@
 # api — examples
 
-Each numbered example is an executable spec, asserted by CHR integration tests
-(booted by `@tikoci/quickchr`): `test/integration/api.test.ts` (rest-api
-examples), `test/integration/api-native.test.ts` (native-api examples, N…), and
-`test/integration/api-listen.test.ts` (streaming examples, L…), with example N ↔
-assertion N. If a line here is not exercised by a test, the test file is wrong; if
-a line passes only with `--validate=false`, the implementation is wrong (see
+Each numbered example is an executable spec asserted by CHR integration tests
+(booted by `@tikoci/quickchr`), example N ↔ assertion N:
+`test/integration/api.test.ts` (rest-api examples),
+`test/integration/api-native.test.ts` (native-api examples, N…),
+`test/integration/api-listen.test.ts` (streaming examples, L…), and
+`test/integration/api-fanout.test.ts` (fan-out examples, F…). If a line here is not
+exercised by a test, the test file is wrong; if a line passes only with
+`--validate=false`, the implementation is wrong (see
 [`docs/CONSTITUTION.md`](../../docs/CONSTITUTION.md)).
 
 `$R` is `<host>:<rest-port>` resolved by quickchr. `$A` is `<host>` and
@@ -323,3 +325,119 @@ centrs api $A ip/address --stream --duration 2s --via native-api --port $API_POR
 
 With no change during the window, the stream ends after ~2 s with a summary
 envelope whose `data.stopReason=duration-elapsed`. Exit code 0.
+
+## fanout (multi-target, F…)
+
+These run against a CDB fixture with two records sharing group `$G`: record 0 is
+the live CHR (comment `board=chr`), record 1 is an unreachable host (comment
+`board=dead`). Fan-out output is the locked `FanoutData` envelope
+(`data = { summary, targets[] }`; outer `ok` = orchestration success; per-target
+failures are inner `ok:false`), with the granular exit code (0 all-ok / 2 partial /
+1 all-failed or orchestration error). See `test/integration/api-fanout.test.ts`.
+The `--raw`/`--listen` + fan-out guards are network-free and validated in
+`test/integration/cli-smoke.test.ts`.
+
+### F1. `--group` fans a GET out; a dead target is an inner failure
+
+```bash
+centrs api --group $G ip/address --cdb-file $CDB --json
+```
+
+`ok: true`, `data.summary = { total: 2, ok: 1, failed: 1 }`, `data.targets[]` in
+record-index order (`[0, 1]`): target 0 is an inner success (`meta.via=rest-api`),
+target 1 is inner `ok:false` with `error.code=transport/connection-refused`.
+`meta.operation.kind=fanout`. Exit code 2.
+
+### F2. `--where` selects only the matching device
+
+```bash
+centrs api --where board=chr ip/address --cdb-file $CDB --json
+```
+
+The device-class selector matches only record 0, so `data.summary = { total: 1,
+ok: 1, failed: 0 }`, one inner success. Exit code 0.
+
+### F3. An empty selection is `ok:true` with summary 0/0/0
+
+```bash
+centrs api --group no-such-group ip/address --cdb-file $CDB --json
+```
+
+`ok: true`, `data.summary = { total: 0, ok: 0, failed: 0 }`, `data.targets = []`,
+and a `cdb/empty-group` warning. Exit code 0.
+
+### F4. A mutating fan-out without `--yes` is rejected, naming the blast radius
+
+```bash
+centrs api -X PUT ip/address -f address=10.99.0.1/32 -f interface=ether1 --group $G --cdb-file $CDB --json
+```
+
+Non-interactive and unconfirmed: outer `ok:false`,
+`error.code=usage/confirmation-required`, and the message names the router count
+(`2 router(s)`) and that `--yes` is required. No write is attempted. Exit code 1.
+
+### F5. A mutating fan-out with `--yes` writes across the selected devices
+
+```bash
+centrs api -X PUT ip/address -f address=10.99.0.7/32 -f interface=ether1 --where board=chr --yes --cdb-file $CDB --json
+```
+
+Confirmed once up front; the add runs on record 0 only (selected by `--where`).
+`data.summary = { total: 1, ok: 1, failed: 0 }`, the inner success carries the
+created `.id`. Exit code 0.
+
+The fixture for F6–F9 adds record 2 — the reserved `__default__` credential record.
+
+### F6. `--all` fans across every record except `__default__`
+
+```bash
+centrs api --all ip/address --cdb-file $CDB --json
+```
+
+`data.summary = { total: 2, ok: 1, failed: 1 }`, `data.targets[]` record indices
+`[0, 1]` (record 2 `__default__` is excluded). Exit code 2.
+
+### F7. A positional + `--group` union de-dupes by record index
+
+```bash
+centrs api $R0 --group $G ip/address --cdb-file $CDB --json
+```
+
+`$R0` is record 0's target, also a member of `$G`; the union is `{0, 1}` — record
+indices `[0, 1]`, `total = 2` (not 3). Exit code 2.
+
+### F8. `--concurrency` bounds the worker pool
+
+```bash
+centrs api --group $G --concurrency 1 ip/address --cdb-file $CDB --json
+```
+
+Runs one target at a time; `meta.operation.concurrency = 1`, still
+`data.summary = { total: 2, ok: 1, failed: 1 }`. (`--concurrency 2abc` / `1.5` are
+rejected at parse time with `usage/invalid-concurrency`.) Exit code 2.
+
+### F9. `--default` selects `__default__`, which fails the connectable guard
+
+```bash
+centrs api --default ip/address --cdb-file $CDB --json
+```
+
+The reserved record is a credential fallback, not a connectable router, so its one
+target fails deterministically: inner `ok:false` with
+`error.code=target/unresolved` (never a `transport/dns` attempt on `"__default__"`).
+`data.summary = { total: 1, ok: 0, failed: 1 }`. Exit code 1 (every target failed).
+
+## quickchr targets (#134)
+
+`$NAME` is the machine name of a running quickchr-managed CHR. Host/port/auth
+come from the live descriptor (see `commands/retrieve/examples.md` Q-series).
+Covered by `test/integration/quickchr-target.test.ts`.
+
+### Q1. GET against a quickchr target
+
+```bash
+centrs api --quickchr $NAME system/resource --json
+```
+
+Envelope: `ok: true`, `data` is the resource object,
+`meta.target.source.kind=provider`.

package/commands/btest/README.md

@@ -80,38 +80,27 @@ centrs btest server [--authenticate[=false]] [--user U] [--password P] \
 
 ## Flags
 
-### `btest client <router>`
-
-| Flag | RouterOS analog / default | Notes |
-| ---- | ------------------------- | ----- |
-| `--protocol <udp\|tcp>` | `protocol`, default `udp` | UDP measures raw throughput + loss; TCP measures goodput. |
-| `--direction <receive\|transmit\|both>` | `direction`, default `receive` | `receive` = download (server→client), `transmit` = upload. |
-| `--duration <dur>` | `duration` | Bounds the run; reuses `parseDuration`. Omit for open-ended (Ctrl-C). |
-| `--interval <dur>` | `interval`, default `1s` | Report cadence (`20ms`..`5s`). One report frame per interval. |
-| `--connection-count <n>` | `connection-count` (1..255) | **TCP only.** Parallel TCP data connections. centrs opens the negotiated extra connections (join format grounded against RouterOS 7.23.1) so throughput aggregates across streams. **Authenticated (EC-SRP5) sessions stay single-stream** — the post-auth token is not captured — and emit a `routeros/btest-connection-count-single-stream` warning. |
-| `--local-udp-tx-size <n>` | `local-udp-tx-size` (28..64000) | **UDP only.** Client→server packet size. |
-| `--remote-udp-tx-size <n>` | `remote-udp-tx-size` (28..64000) | **UDP only.** Server→client packet size. |
-| `--local-tx-speed <bps>` | `local-tx-speed` | Cap on client→server rate (bits/sec). |
-| `--remote-tx-speed <bps>` | `remote-tx-speed` | Cap on server→client rate (bits/sec). |
-| `--random-data` | `random-data`, default off | Incompressible payload (defeats link compression; CPU-heavier). |
-| `--user` / `--password` | `user` / `password` | Fall back to CDB / `CENTRS_*`. Required when the server has `authenticate=yes`. |
-| `--port <n>` | — (default `2000`) | Control port override. |
-| `--format <text\|csv\|json\|yaml>` | — (default `text`) | `text` = live human reports; `csv` = streaming CSV records; `json`/`yaml` = final summary envelope. |
-| `--csv` | — | Shortcut for `--format csv`. |
-
-### `btest server`
-
-| Flag | RouterOS analog / default | Notes |
-| ---- | ------------------------- | ----- |
-| `--authenticate[=false]` | `authenticate`, **default `true`** | Require EC-SRP5 auth; `--authenticate=false` accepts anonymous clients. |
-| `--user` / `--password` | — | The accepted credential when `authenticate=true` (v1: one user). Falls back to `CENTRS_*`. |
-| `--bind <addr>` | **centrs-only** | Listen address; **default `127.0.0.1`**. Use `0.0.0.0` to expose on the LAN. |
-| `--port <n>` | — (default `2000`) | Control-connection port. |
-| `--allocate-udp-ports-from <n>` | `allocate-udp-ports-from` | Base of the UDP data-port range; default `2001` (just above the TCP/2000 control port). |
-| `--max-sessions <n>` | `max-sessions` (1..1000), default `100` | Concurrent test cap; further clients get `routeros/btest-too-many-sessions`. |
-| `--duration <dur>` | — | Optional auto-stop; otherwise runs until Ctrl-C. |
-| `--format <text\|csv\|json\|yaml>` | — (default `text`) | `text` = human session log; `csv` = streaming CSV records; `json`/`yaml` = final summary envelope. |
-| `--csv` | — | Shortcut for `--format csv`. |
+Implemented flags are generated from the CLI metadata into
+[`docs/CLI.md` → btest](../../docs/CLI.md#btest) — one table for both
+subcommands, with `(client)`/`(server)` markers scoping each flag; "did you
+mean?" hints are scoped to the active mode. This file does not duplicate that
+table. Behavior notes the generated reference cannot carry:
+
+- Flag names mirror the RouterOS analogs verbatim (`protocol`, `direction`,
+  `local-udp-tx-size`, `connection-count`, `authenticate`,
+  `allocate-udp-ports-from`, …); centrs-only additions are `--bind`, `--port`,
+  the shared `--format`/`--csv`, and the CDB credential flags.
+- `--direction receive` = download (server→client), `transmit` = upload.
+- `--connection-count` is TCP-only; **authenticated (EC-SRP5) sessions stay
+  single-stream** — the post-auth token is not captured — and emit a
+  `routeros/btest-connection-count-single-stream` warning (see Open
+  questions).
+- `--user`/`--password` fall back to CDB / `CENTRS_*`; required when the
+  server has `authenticate=yes`. On the server they are the accepted
+  credential (v1: one user).
+- Option ranges (`28..64000` UDP sizes, `1..255` connections, `20ms..5s`
+  interval, `1..1000` sessions) are validated before any socket opens (see
+  Errors).
 
 ## How it works