@tikoci/centrs 0.1.2 → 0.1.3

package/CHANGELOG.md

@@ -8,6 +8,65 @@ documenting cross-cutting shifts that affect contributors and consumers.
 
 ## Unreleased
 
+## 0.1.3 — 2026-07-06
+
+Patch release. `@tikoci/centrs@0.1.3`.
+
+### Added
+
+- **`api` command over rest-api + native-api is `CHR-passed`.** `centrs api`
+  brings a `gh api`-style structured passthrough to both transports, and folds
+  the old standalone `stream` command into `api --stream` (native-api only,
+  `--listen` alias): a `NativeApiSession.listen()` reader with `/cancel`
+  support emits NDJSON frames plus a run summary. Grounded against real CHR
+  7.23.1.
+- **Multi-target fan-out is uniform across `api`, `retrieve`, `execute`, and
+  `transfer`.** A shared `expandCdbSelection` + `runFanout` + `fanoutExitCode`
+  core (extracted once, consumed by all four commands) lets any command take a
+  CDB selector and run over every matching device. The positional boundary
+  that ends the selector differs per command (final positional for
+  `api`/`retrieve`, `--` for `execute`, the verb keyword for `transfer`);
+  `terminal` and `api --stream` explicitly reject `N > 1` selections since
+  neither has a sane multi-target framing.
+- **`settings` command (`print` / `get` / `set` / `reset`).** A managed-key
+  registry for the real `CENTRS_*` environment keys backs an atomic
+  `centrs.env` writer: `set` validates per key, canonicalizes booleans to
+  `1`/`0` on disk, warns (never blocks) on consequential values
+  (`insecure=true`, `transfer-via=ftp`), and never partially writes on a
+  validation failure; `reset` deletes the managed line rather than blanking it
+  (a blank value would itself mean "set to empty" for a bash-sourced file) and
+  leaves foreign lines/comments untouched. Bare `centrs settings` behaves like
+  `print` regardless of TTY. Four new error/warning codes
+  (`settings/reserved-key`, `settings/unknown-key`,
+  `settings/consequential-value`, `settings/skip-env-file-active`) plus
+  `internal/settings-failed`, all cataloged. `CHR-passed` via 32
+  fixture-backed integration examples.
+- **Device GPS: lat/lon/altitude storage + `--near` / `--bbox` geo
+  predicates.** `centrs devices` now stores GPS coordinates per device
+  (lat-first ordering, chosen so agents guess the field order correctly) and
+  supports proximity
+  (`--near`) and bounding-box (`--bbox`) selection predicates. `CHR-passed`
+  via fixture-backed integration coverage.
+- **Registry⇄MATRIX drift guard + "did you mean?" flag errors.** A CI-checked
+  guard keeps the command/protocol registry and `docs/MATRIX.md` from
+  silently drifting apart; unrecognized CLI flags now suggest the closest
+  known flag instead of a bare rejection.
+- **GitHub Pages: published API reference + error catalog.** `typedoc` output
+  and the generated error-code catalog now publish to GitHub Pages on push.
+
+### Fixed
+
+- **Windows unit-test portability for `settings` and MNDP.** Path-separator
+  and related platform assumptions in the `settings` and MNDP unit suites are
+  now Windows-safe (#170).
+- **A real CodeQL-caught ReDoS in the device GPS geo-predicate parser**, fixed
+  rather than suppressed.
+
+### Changed
+
+- **CodeQL house-rules pack promoted to the default run**, alongside CodeRabbit
+  review-tone tuning and a reduced GitHub-checks timeout (15 → 7 minutes).
+
 ## 0.1.2 — 2026-06-26
 
 Patch release. `@tikoci/centrs@0.1.2`.

package/GLOSSARY.txt

@@ -139,6 +139,7 @@ MNDP
 NAND # NAND flash memory; write-back caches file writes up to ~40s on some MikroTik boards
 netmiko # [Multi-vendor library to simplify Paramiko SSH connections to network devices](https://github.com/ktbyers/netmiko)
 netwatch
+nullglob # bash shopt that makes an unmatched glob expand to zero words instead of the literal pattern
 npk # MikroTik package format
 nvme-over-tcp # supported by RouterOS **with** rose-storage.npk extra-package
 OID
@@ -148,6 +149,7 @@ PRGA
 proplist
 pywinauto
 QML
+qll # CodeQL library file extension (.qll), e.g. CleartextLoggingCustomizations.qll
 qmljsdebugger
 quickchr
 RAML
@@ -161,12 +163,15 @@ rosetta
 routeros
 routeros-skills
 rsc # RouterOS script / export file extension (.rsc)
+SARIF # Static Analysis Results Interchange Format; CodeQL's code-scanning analysis download format
 scp
 scriptability
 scriptable
+shopt # bash builtin for toggling shell options (e.g. nullglob)
 Sikuli
 SikuliX
 skillcheck
+startswith # jq builtin filter that tests whether a string begins with a given prefix
 SNMP
 SPI
 SRP
@@ -184,6 +189,7 @@ TIKOCI
 tiktui
 TLV
 traceroute
+tostring # jq builtin filter that renders a value as its JSON string representation
 tsc
 tzsp
 TZSP
@@ -434,3 +440,68 @@ toarray
 # Logic shorthand ("if and only if") used in api write-gate doc comments; cspell's
 # markdown dictionary knows it but the TypeScript one does not.
 iff
+
+# GitHub Pages build vocabulary (scripts/build-pages-site.ts, pages.yaml)
+# typedoc/pandoc: the API-reference generator and the markdown->HTML converter
+#   the Pages build chains together. gfm: GitHub-Flavored Markdown, pandoc's
+#   input format for the error pages. larr: the "←" left-arrow HTML entity
+#   in the back-to-docs link. nojekyll: the marker file that disables GitHub
+#   Pages' Jekyll processing for an Actions-deployed artifact. extensionless:
+#   describes the `details_url` contract (docs/errors/README.md) — no `.html`.
+typedoc
+pandoc
+gfm
+larr
+nojekyll
+extensionless
+# nothrow: Bun Shell's `$` method to disable throwing on a non-zero exit
+# (scripts/agent-check.ts), so the caller can inspect output either way.
+nothrow
+
+# check-command spec vocabulary (commands/check/README.md, examples.md)
+# TikTOML: centrs-owned readable device-inventory format (#137); check's
+#   metadata feeds it. routerboard: RouterBOARD firmware/hardware menu
+#   (/system/routerboard). rscmd: the tikbook RouterOS command-notebook file
+#   extension (.rscmd), the format the check spec was grounded against.
+TikTOML
+routerboard
+rscmd
+# RTT: round-trip time, the host->router connect-latency reach signal. tojson: the
+#   /system/script helper (:serialize to=json) the batched execute reads reuse.
+#   qrcode: the /ip/cloud vpn-wireguard-client-config-qrcode field token (redacted
+#   by the cloud check, referenced when documenting redaction).
+RTT
+tojson
+qrcode
+
+# Device GPS vocabulary (issue #146, commands/devices/README.md "Location /
+# GPS", src/resolver/geo.ts). MSL/AGL: the two supported altitude-type vertical
+#   datums (mean sea level / above ground level); stored case-insensitively but
+#   normalized to upper case. EPSG: the geodetic coordinate-reference-system
+#   registry (EPSG:4326 = WGS84 lat/lon), cited for the lat-first ordering
+#   rationale. bbox: the --bbox geo selector (bounding box). wgs: WGS84, the
+#   geodetic datum GPS coordinates use; appears only as a deliberately-invalid
+#   --altitude-type value in tests/examples. antimeridian: the 180° meridian a
+#   --bbox may not cross in v1. GEOSEARCH: the Redis command whose m/km/mi/ft
+#   radius-unit vocabulary --near borrows. IUGG: the geodesy union whose mean
+#   Earth radius the haversine uses. SFO/OAK: airports used as a known-distance
+#   haversine fixture in tests. ele/GPX: `ele` is GPX's altitude element, kept as
+#   an input alias for `altitude` (GPX = the GPS Exchange Format). Geolocation:
+#   the W3C Geolocation API, cited (with ISO 6709 / EPSG / IETF geo:) for why
+#   `altitude` — not `elevation` — is the canonical field name.
+MSL
+msl
+AGL
+agl
+Agl
+EPSG
+bbox
+wgs
+antimeridian
+GEOSEARCH
+IUGG
+SFO
+sfo
+ele
+GPX
+Geolocation

package/README.md

@@ -4,6 +4,12 @@
 CLI (with MCP, TUI, and HTTP proxy frontends planned) for talking to MikroTik
 RouterOS devices through a regularized, validated interface.
 
+Preview builds are published on npm. To inspect the CLI without installing it:
+
+```bash
+bunx @tikoci/centrs --help
+```
+
 It is a **friendly conduit**, not a high-level configuration abstraction. It
 helps humans and agents reach RouterOS over the right protocol, with the right
 credentials and ports, and validates RouterOS-shaped commands before running
@@ -11,9 +17,12 @@ them. It does **not** hide RouterOS behind helpers like `createVlanOnBridge()`
 — you still speak RouterOS. Validation and structured diagnostics are the
 product; without them this would just be a worse `curl`.
 
-> **Status:** early and in active development. The library, device registry, and
-> first MCP server phases are CHR-verified; the CLI is wired (`coded`); encrypted-CDB
-> writes are still blocked, and the TUI/proxy frontends are planned.
+> **Status:** early npm preview, active development. `@tikoci/centrs` is
+> published on npm, but command flags and envelopes may still change before a
+> stable release. Check current dist-tags with
+> `npm view @tikoci/centrs dist-tags --json`. The library, device registry, and
+> first MCP server phases are CHR-verified; the CLI is wired (`coded`);
+> encrypted-CDB writes are still blocked, and the TUI/proxy frontends are planned.
 > `docs/MATRIX.md` is the single source of truth for what works today — treat
 > anything not green there as not-yet-shipped.
 
@@ -104,16 +113,23 @@ CDB tags, and `devices set` refuses to put them there. Unknown keys produce a
 `cdb/unknown-option` warning and are ignored, so a stray `=` in human prose
 never breaks anything.
 
-Settings resolve lowest-to-highest: **built-in defaults → project config →
-comment-kv → `CENTRS_*` env → CLI flag / API arg.** Every result envelope
-reports which source won each setting under `meta.settings`, so you can always
-see *why* a given port or transport was chosen.
+Settings resolve lowest-to-highest: **built-in defaults → user config file
+(`centrs.env`) → comment-kv → `CENTRS_*` env → CLI flag / API arg.** Every
+result envelope reports which source won each setting under `meta.settings`,
+so you can always see *why* a given port or transport was chosen.
 
 ### Groups, discovery, and the MCP allowlist all ride on the CDB
 
 - **Groups** are CDB-native: an entry's `group` field is just a string, and
   `--group prod-edge` fans a single command out to every entry that shares it.
-  There is no separate group-definition file.
+  There is no separate group-definition file. Groups are one selector in a
+  **uniform fan-out grammar** shared by `api`, `retrieve`, `execute`, and
+  `transfer`: mix `<router>` positionals, repeatable `--group`/`--where
+  <attr>=<value>`, `--all`, and `--default` (de-duped by CDB record index). Every
+  fan-out returns the locked `FanoutData` envelope (per-target results, not
+  metadata) with a granular exit code (`0` all ok / `2` partial / `1` all failed);
+  a multi-target write is gated once by `--yes` naming the blast radius. See
+  `docs/CONSTITUTION.md` (Target selection grammar).
 - **Discovery** writes back into the CDB: `discover --save` records MNDP
   neighbors as new entries tagged `group=discovered` with a `source=mndp`
   marker — hints to curate, not authoritative inventory.

package/SECURITY.md

@@ -14,14 +14,14 @@ Please include the affected files or workflow, reproduction details, and impact.
 
 The repository's [Security tab](https://github.com/tikoci/centrs/security) is the live source of current alerts and advisories. This section describes *what* checks run and *why*, so the doc stays meaningful even when the badge is at 0.
 
-- **CodeQL** — repo-managed workflow at [`.github/workflows/codeql.yaml`](.github/workflows/codeql.yaml) with config [`.github/codeql-config.yml`](.github/codeql-config.yml). Query suite: `security-and-quality` (security-extended + code-quality). Languages: `javascript-typescript`, `actions`. Schedule: push to `main`, pull requests to `main`, weekly cron, and manual dispatch.
-- **Code Quality (AI findings, preview)** — intended to be enabled in GitHub. [`.github/workflows/codeql.yaml`](.github/workflows/codeql.yaml) includes a non-failing forward-compat probe for a future AI-findings API. AI findings are noisy and self-contradicting; we accept the noise because the second-opinion catches real issues that the static suite misses. Steady-state goal is 0 open findings. False positives are dismissed via the GitHub UI with a written justification — that text is the audit-log contract.
+- **CodeQL** — repo-managed workflow at [`.github/workflows/codeql.yaml`](.github/workflows/codeql.yaml) with config [`.github/codeql-config.yml`](.github/codeql-config.yml). Query suite: `security-and-quality` (security-extended + code-quality) plus a small custom pack, [`.github/codeql-house-rules/`](.github/codeql-house-rules/), that structurally checks a handful of repo-specific invariants (currently: `apiFanout` must call its named protocol/validation gates) — see `.github/instructions/github-security-quality.instructions.md` for scope and the verify-before-promote discipline for adding more rules there. Languages: `javascript-typescript`, `actions`. Schedule: push to `main`, pull requests to `main`, weekly cron, and manual dispatch.
+- **Code Quality (AI findings, preview)** — confirmed active in GitHub as of 2026-07-03 (not just "intended"; see [issue #166](https://github.com/tikoci/centrs/issues/166)). [`.github/workflows/codeql.yaml`](.github/workflows/codeql.yaml) includes a non-failing forward-compat probe for a future AI-findings API. AI findings are noisy and self-contradicting; we accept the noise because the second-opinion catches real issues that the static suite misses. Steady-state goal is 0 open findings. False positives are dismissed via the GitHub UI with a written justification — that text is the audit-log contract. Side effect: GitHub's own Code Quality scan runs in parallel with our Advanced Setup and posts a same-named `Analyze (javascript-typescript)` check, so PR checks lists show it twice — cosmetic, tracked in #166, not a required check either way (see issue #118).
 - **Dependency review** — not enabled. GitHub dependency review follows dependency-graph ecosystem support, and this Bun-only repository currently does not have a supported lockfile for that gate.
 - **Dependabot security updates** — enabled and configured in [`.github/dependabot.yaml`](.github/dependabot.yaml).
 - **Secret scanning** — enabled in GitHub, with push protection.
 - **Private vulnerability reporting** — enabled via GitHub Security Advisories.
 
-Some GitHub Security tab data, especially Code Quality AI findings, is not currently available through stable unauthenticated APIs. Human review in the GitHub UI remains part of the security workflow.
+Some GitHub Security tab data, especially Code Quality AI findings, is not reachable through the default workflow `GITHUB_TOKEN` (`repos/{owner}/{repo}/code-quality/findings` 403s there even with `security-events: read`) — it does respond with an elevated/owner-scoped token, but no findings have been recorded yet to confirm the response shape end-to-end (see #166). Human review in the GitHub UI remains part of the security workflow until that's wired up.
 
 ## Supported versions
 

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
 
@@ -72,11 +73,28 @@ when a bare-collection `POST` carries create-looking fields.
 | `--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. |
+| `--group <name>` / `--where <attr>=<value>` / `--near <lat>,<lon>,<radius>` / `--bbox <south>,<west>,<north>,<east>` / `--all` / `--default` / `--concurrency <n>` | Multi-target fan-out (see below). Repeatable `--group`/`--where`; `--near`/`--bbox` select by device GPS (lat-first; see constitution: target selection). The union de-dupes by CDB record index. |
 | 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`.
+## 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,104 @@ 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).