@tikoci/centrs 0.1.1 → 0.1.2

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.1",
+	"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/**\"",