@tikoci/centrs 0.1.0 → 0.1.2

package/commands/execute/README.md

@@ -52,6 +52,12 @@ Status: `rest-api`, `native-api`, `mac-telnet`, and `ssh` are `CHR-passed` (see
   else passes its `detail`/body plus the HTTP status through
   `mapRouterOsError({ transport: "rest-api", httpStatus })`. There is no longer
   a hand-rolled `routeros/*` table on the REST side.
+- **Run-time fault mapping — later (JG-28).** `mapRouterOsError`'s table covers
+  the faults seen so far; a known gap is errors that *pass* `:parse`/validation
+  but fail at **run time** (a syntactically valid command the router rejects when
+  executed). `tikoci/vscode-tikbook` has an error-string mapping for these worth
+  porting into `src/core/routeros-errors.ts`. Background research, not yet
+  scheduled — captured here so it isn't lost (no GitHub issue by design).
 - Output is *string*-shaped for script-mode; richer parsing is a future
   concern. The envelope must still distinguish RouterOS errors from successful
   runs (a 200 with a RouterOS error string is still an error — see
@@ -195,9 +201,9 @@ Protocol selection: an unresolved MAC target auto-selects mac-telnet (covered by
 ## Open shape questions
 
 - ~~How to expose multi-line / async / progress output~~ — **resolved:**
-  open-ended follow/streaming reads are the separate read-only `stream` verb
-  (NDJSON stream of envelopes; see `commands/stream/README.md`). `execute` stays
-  single-shot read/write; it does not grow a follow mode.
+  open-ended follow/streaming reads are `api … --stream` (NDJSON stream of
+  envelopes; see `commands/api/README.md`). `execute` stays single-shot
+  read/write; it does not grow a follow mode.
 - ~~Whether `--strict` should reject "succeeded with stderr-like content."~~ —
   **decided:** `--strict` promotes any warning on an otherwise-successful run to
   `ok: false` (nonzero exit), like `-Werror`; the default stays lenient

package/commands/retrieve/README.md

@@ -45,7 +45,7 @@ centrs retrieve <router> snmp <oid|MIB name> [flags]
 | `--attributes <a,b,c>`              | Alias for `--attribute` with comma-separated input.                                       |
 | `--all-attributes`                  | Equivalent to RouterOS `details=true`. Mutually exclusive with `--attribute(s)`.          |
 | `--list-attributes` (alias `--list`) | Return the available attribute names for the path. No `print`/`get` is run.              |
-| `--once`                            | Bounded single read of a monitor-style menu (RouterOS `once`): returns **one** envelope and never follows. Open-ended follow is the separate `stream` verb. See constitution: protocol selection. |
+| `--once`                            | Bounded single read of a monitor-style menu (RouterOS `once`): returns **one** envelope and never follows. Open-ended follow is `api … --stream`. See constitution: protocol selection. |
 | `--query <expr>`                    | RouterOS-side **row** filter (maps to `.query`), repeatable; returns matching rows as an **array**. This is how you read one row by name (`--query name=ether1`). **Not Implemented** yet — returns `validation/not-implemented`. |
 | `--filter <expr>`                   | RouterOS row filter; same `.query` mapping and not-implemented handling as `--query`.       |
 | `--where <attr>=<value>`            | Device-class selector: fan out across CDB records whose stored fact/comment-kv matches (e.g. `--where board=RB5009`). Repeatable (AND). Filters *which devices*, not RouterOS rows. See constitution: target selection. |

package/docs/CONSTITUTION.md

@@ -228,8 +228,8 @@ repeats. The union is **de-duped by CDB record index** and run through the same
 per-target pipeline; the `data` array is reassembled in resolved record order,
 not completion order, so repeated runs diff cleanly. Destructive multi-target
 operations (e.g. `devices remove` across a group) require `--force`. `terminal`
-and single-session `stream` are not fan-out surfaces and reject N>1 with
-`usage/fanout-not-supported`.
+and a single-session `api --stream` follow are not fan-out surfaces and reject
+N>1 with `usage/fanout-not-supported`.
 
 `--where` filters *which devices* by CDB-stored facts; keep it distinct from
 `retrieve`/`execute`'s `--query`/`--filter`, which filter *RouterOS rows* in the
@@ -266,7 +266,7 @@ Per-operation preferences, downgrade order in parens:
 | Operation | Preferred | Downgrade order |
 | --------- | --------- | --------------- |
 | retrieve  | rest-api, native-api; snmp for OID/MIB reads (future) | rest-api, native-api |
-| stream    | native-api, ssh | (REST cannot follow — 60s cap; bounded or rejected) |
+| api       | rest-api, native-api; `--stream` follow native-api only | rest-api, native-api (no silent downgrade) |
 | execute   | native-api → rest-api → mac-telnet | native-api, rest-api, mac-telnet, ssh, romon, winbox-terminal |
 | terminal  | ssh | mac-telnet (L2 only when ssh fails or MAC given) |
 | transfer  | size/direction-aware: rest-api/native-api for ≤60 KB writes & all reads (chunked), sftp for large uploads | sftp ⇄ rest/native by size; scp · fetch · ftp explicit-only |
@@ -288,9 +288,9 @@ Rules:
   access needs explicit ARP opt-in.
 - **`measure` (btest) is explicit-only** — never in the auto-select/downgrade
   chain, never a substitute, and no other command rides it.
-- Per-command selection **depth** lives in the command READMEs: `stream`'s
-  follow/NDJSON contract and the REST-cannot-follow constraint
-  (`commands/stream/README.md`), `transfer`'s size/direction-aware method
+- Per-command selection **depth** lives in the command READMEs: `api`'s
+  `--stream` follow/NDJSON contract and the REST-cannot-follow constraint
+  (`commands/api/README.md`), `transfer`'s size/direction-aware method
   selection and the explicit-only `scp`/`ftp`/`fetch`
   (`commands/transfer/README.md`), SNMP's MIB-cache
   (`commands/retrieve/README.md`), and btest's port/auth

package/docs/MATRIX.md

@@ -24,7 +24,7 @@ A cell advances only with the matching evidence in the same change.
 | Command  | rest-api      | native-api    | ssh           | mac-telnet    | snmp          | mndp          | romon         | winbox-terminal |
 | -------- | ------------- | ------------- | ------------- | ------------- | ------------- | ------------- | ------------- | ---------------- |
 | retrieve | `CHR-passed`  | `CHR-passed`  | —             | —             | `not-started` | —             | —             | —                |
-| stream   | —             | `designed`    | `designed`    | —             | —             | —             | —             | —                |
+| api      | `CHR-passed`  | `CHR-passed`  | —             | —             | —             | —             | —             | —                |
 | execute  | `CHR-passed`  | `CHR-passed`  | `CHR-passed`  | `CHR-passed`  | —             | —             | `not-started` | `not-started`    |
 | terminal | —             | —             | `CHR-passed`  | `CHR-passed`  | —             | —             | —             | —                |
 | transfer | `CHR-passed`  | `CHR-passed`  | `CHR-passed`  | —             | —             | —             | —             | —                |
@@ -56,13 +56,26 @@ verbose REST `board-name`), and the L2 validation policy are documented in
 `commands/discover/README.md`.
 
 There is no `update` command: `execute` is the single read/write surface for
-RouterOS add/set/remove, and `retrieve` stays read-only. See
-`docs/CONSTITUTION.md` (protocol selection).
-
-`stream` is `designed` (no code yet): the read-only follow surface (NDJSON
-stream-of-envelopes; native-api/ssh only — REST's 60s cap cannot follow) is
-specified in `commands/stream/README.md`. The native-api streaming reader it will
-consume already exists (`src/protocols/native-api.ts`).
+RouterOS *CLI-shaped* add/set/remove, and `retrieve` stays read-only. The `api`
+command is the structured one-command-per-operation surface (the verb trichotomy
+in `commands/api/README.md`); it can also write. See `docs/CONSTITUTION.md`
+(protocol selection).
+
+`api` is `CHR-passed` for `rest-api` and `native-api` (single-target): endpoint
+normalization, the method→verb map, the `/console/inspect` gate, write
+confirmation, `.query`/`.proplist`, `-f`/`-d`/`--input` bodies, `--raw`,
+`/execute` script-run (`=as-string=` for sync output on both transports), and
+open-ended `--stream` follow (native-api only — `NativeApiSession.listen()` +
+`/cancel`, NDJSON envelope frames with a terminating summary; `--via rest-api
+--stream` errors `transport/capability-unsupported`), green on CHR 7.23.1 via
+`test/integration/api.test.ts` + `api-native.test.ts` + `api-listen.test.ts`.
+Still deferred (own phase): multi-target fan-out (`--stream` is single-session).
+
+`api` **absorbs** the former `stream` command (folded — no separate row): the
+read-only follow surface is `api <router> <endpoint> --stream` (alias `--listen`;
+the `/listen` endpoint form infers it), native-api only, since REST's 60s cap
+cannot follow. `centrs stream`/`centrs tail` now error with a pointer to
+`api --stream`.
 
 `transfer` is `CHR-passed` for `rest-api`/`native-api` and for **sftp** (the
 `ssh` column's first method): `src/transfer.ts` + `src/cli/transfer.ts`
@@ -156,7 +169,7 @@ core and carry their own state, tracked here:
 
 | Surface | State | Spec | Notes |
 | ------- | ----- | ---- | ----- |
-| api (TS) | `CHR-passed` | `src/index.ts` | Root surface; everything else adapts it. |
+| ts-api | `CHR-passed` | `src/index.ts` | Root **TypeScript library** surface; everything else adapts it. (Renamed from `api (TS)` to avoid colliding with the `api` **command** row in the grid above — the command is a verb, this is the library.) |
 | cli | `coded` | `src/cli/` | `retrieve`/`execute`/`transfer`/`terminal`/`devices`/`discover`/`btest` wired. |
 | mcp | `CHR-passed` | `commands/mcp/` | Scoped-verb stdio MCP server; CDB-as-allowlist safety model. Phase 1 (explain/validate/retrieve/execute, resources) plus first Phase 2 CDB mutation (`centrs_devices add`) green on CHR 7.23 via `test/integration/mcp.test.ts`, including gated write execution. |
 | tui | `not-started` | `src/tui.ts` | Stub. |
@@ -186,12 +199,30 @@ The wire codec, the EC-SRP5 session/handshake (shared core byte-identical with
 mac-telnet's MTWEI, plus the net-new server role), the TCP/UDP data engines, the
 orchestrator + CLI, and the honest grounding caveat (the server gets direct CHR
 evidence over the QEMU SLIRP gateway `10.0.2.2`; the client gets direct CHR
-evidence over a host→guest `tcp:2000` forward — TCP only; UDP-receive is a soft
-smoke test and UDP client→CHR-server stays loopback/transitive over the SLIRP
-reverse path; TCP `connection-count > 1` fan-out is deferred; NDJSON is not
-adopted) are documented in `commands/btest/README.md` and the
-`src/protocols/btest.ts`, `src/protocols/btest-session.ts`, and
-`src/protocols/ec-srp5.ts` module headers.
+evidence over a host→guest `tcp:2000` forward (the forward carries TCP; UDP rides
+the guest→host gateway instead, below); UDP-receive was
+previously a soft smoke test because the SLIRP reverse path was believed to block
+real validation and a `connect()` socket filter was silently dropping all received
+datagrams — RouterOS sends UDP data **from a different source port** than the
+negotiated `serverUdpPort`, so the BSD receive filter rejected every packet;
+fixed by removing `connect()` and addressing sends explicitly, validated against
+a real RouterOS device at 163–203 Mbps receive and 104 Mbps bidirectional, and
+**CI now gates UDP client receive/both** — the server→client return rides the
+guest→host SLIRP gateway (`10.0.2.2:clientUdpPort`), needing no UDP forward and no
+quickchr change (#88 closed; the `connect()` filter fix in #86 is what enabled it);
+TCP
+`connection-count` reaches the server's command packet (#84) and centrs opens the
+negotiated extra TCP data connections — multi-connection **fan-out** (#87),
+grounded byte-for-byte against RouterOS 7.23.1 (secondary join
+`[token:u16 BE][0x02][0 …]`) and CHR-gated for the realized fan-out
+(`activeConnections == count`; no throughput-rise assertion — the SLIRP loopback is
+bandwidth-bound); authenticated sessions stay single-stream (warned); TCP
+`direction=both` demuxes the server's
+interleaved status frames so the client paces its TX from feedback and does not
+starve server→client RX (#85 fixed); the Windows unit tier skips UDP-loopback
+tests (#69); NDJSON is not adopted) are
+documented in `commands/btest/README.md` and the `src/protocols/btest.ts`,
+`src/protocols/btest-session.ts`, and `src/protocols/ec-srp5.ts` module headers.
 
 ## Priority order
 

package/docs/errors/routeros/btest-connection-count-single-stream.md

@@ -0,0 +1,22 @@
+# `routeros/btest-connection-count-single-stream`
+
+A **warning** (not a failure): `centrs btest client --protocol tcp
+--connection-count <n>` opened **fewer** TCP data connections than `n`. centrs
+does implement the multi-connection fan-out — it opens the extra connections that
+join the test with the server-negotiated session token — but it falls back to a
+single stream when the server negotiates **no** token. The common case is an
+**authenticated (EC-SRP5)** session: centrs does not yet capture the post-auth
+session token, so authenticated tests stay single-stream. A secondary connection
+that fails mid-handshake also reduces the realized count.
+
+The warning reports both the requested and the actually-active connection count.
+
+## Workaround
+
+- For full multi-stream throughput, run the test **unauthenticated**
+  (`/tool/bandwidth-server` with `authenticate=no`), where centrs negotiates the
+  token and opens all `n` connections.
+- Or run several `centrs btest client` processes in parallel and sum their
+  throughput.
+
+See `docs/CONSTITUTION.md` for the centrs error/warning contract.

package/docs/errors/routeros/btest-udp-tx-size-ignored.md

@@ -0,0 +1,15 @@
+# `routeros/btest-udp-tx-size-ignored`
+
+A non-fatal warning. For UDP `--direction both`, the btest wire protocol carries
+a **single** `tx-size` field, so the client and the server transmit with the
+same packet size. centrs maps `--local-udp-tx-size` to that field and discards
+`--remote-udp-tx-size`. This warning fires only when both flags are set to
+different values, so you know which size the session actually used.
+
+## Fix
+
+Drop `--remote-udp-tx-size` for `--direction both`, or set both flags to the
+same value. To size each direction independently, run two sessions:
+`--direction transmit` (uses `--local-udp-tx-size`) and `--direction receive`
+(uses `--remote-udp-tx-size`). See `commands/btest/README.md` and
+[`docs/CONSTITUTION.md`](../../CONSTITUTION.md).

package/docs/errors/usage/invalid-method.md

@@ -0,0 +1,23 @@
+# `usage/invalid-method`
+
+The -X/--method value is not a supported HTTP method.
+
+## Fix
+
+`centrs api` honors the HTTP method (`-X` / `--method`) literally against
+RouterOS's REST verb map. The accepted methods are `GET`, `PUT`, `PATCH`,
+`DELETE`, and `POST` (case-insensitive):
+
+| Method | RouterOS verb        |
+| ------ | -------------------- |
+| `GET`  | print / get          |
+| `PUT`  | add (RouterOS create) |
+| `PATCH`| set                  |
+| `DELETE`| remove              |
+| `POST` | run a command        |
+
+Pass one of those with `-X`, or omit the flag to use the default `GET`. Note the
+trap: **`PUT` is RouterOS's create**, not `POST`.
+
+See [`docs/CONSTITUTION.md`](../../CONSTITUTION.md) for the centrs error
+contract.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@tikoci/centrs",
-	"version": "0.1.0",
+	"version": "0.1.2",
 	"main": "src/index.ts",
 	"module": "src/index.ts",
 	"repository": {
@@ -12,7 +12,7 @@
 	"packageManager": "bun@1.3.13",
 	"devDependencies": {
 		"@agent-lint/cli": "^0.8.1",
-		"@biomejs/biome": "2.5.0",
+		"@biomejs/biome": "2.5.1",
 		"@secretlint/secretlint-rule-preset-recommend": "^13.0.2",
 		"@tikoci/quickchr": "^0.4.2",
 		"@types/bun": "^1.3.13",
@@ -57,11 +57,11 @@
 	"scripts": {
 		"ci": "bun run lint && bun run test && bun run build",
 		"git:pre-commit": "bun run lint",
-		"git:pre-push": "bun run ci",
+		"git:pre-push": "bun run lint:git:push",
 		"lint": "bun run lint:biome && bun run lint:typecheck",
 		"lint:git:commit": "bun run lint",
-		"lint:git:push": "bun run ci",
-		"lint:ci": "bun run lint && bun run lint:markdownlint && bun run lint:cspell && bun run lint:secretlint && bun run lint:agents",
+		"lint:git:push": "bun run lint:ci && bun run test && bun run build",
+		"lint:ci": "bun run lint && bun run lint:markdownlint && bun run lint:cspell && bun run lint:secretlint",
 		"lint:cspell": "cspell lint . --gitignore",
 		"lint:cspell:all": "cspell lint . --no-gitignore",
 		"lint:markdownlint": "markdownlint-cli2 \"**/*.md\" \"!.scratch/**\"",