@tikoci/centrs 0.1.7 → 0.1.8

package/CHANGELOG.md

@@ -6,6 +6,262 @@ The product evolves as a stream of changes; there are no alpha gates.
 Per-feature status is tracked in `docs/MATRIX.md`. Use this file for
 documenting cross-cutting shifts that affect contributors and consumers.
 
+## Unreleased
+
+## 0.1.8 — 2026-10-12
+
+Release (npm tag `latest`; `next` moves forward to 0.1.8). Everything in
+0.1.8-next.0 below, plus two fixes from field-testing it.
+
+### Fixed
+
+- `retrieve --wait` with no deadline value names `--wait` (#445). Written as a
+  bare switch, `--wait --until 'expr'` read `--until` as the deadline and
+  shifted the predicate into a second target, so the CLI reported
+  `usage/fanout-not-supported`. It now fails `settings/invalid-timeout`
+  ("Received the flag: --until"), and every deadline without a unit gets the
+  `--wait`-specific message. A real multi-target `--wait` still gets the
+  fanout refusal.
+- MCP accepts a registered device by its `identity=`, `mac=` or `ip=` comment
+  key, as the CLI does (#444). The allowlist gate now matches with the same
+  resolver the call dials with, so the `mcp=` write policy checked is the
+  policy of the record the call runs against. A name on more than one record
+  fails `identity/ambiguous` with the candidates in `context.matches` and an
+  MCP remediation, instead of resolving to the first.
+
+## 0.1.8-next.0 — 2026-10-12
+
+Pre-release (npm tag `next`; `latest` stays on 0.1.7). Install with
+`bunx @tikoci/centrs@next`.
+
+### Maintenance
+
+- Refresh vulnerable dependencies within existing ranges and use Bun's
+  Dependabot ecosystem for `bun.lock` (#390). Preserve the dependency group
+  and the `has-flag` major-version ignore. Remaining dependency advisories
+  and updater verification are tracked in #390.
+- Pre-release dependency alignment (#390): runtime ranges now floor at the
+  tested versions (`@modelcontextprotocol/sdk ^1.32.1`, `zod ^4.6.7`),
+  `smol-toml` is overridden past its advisories, and `@types/bun` is pinned
+  exactly to the 1.3.14 runtime (re-pin tracked in #438). The two residual
+  advisories (`braces`, `katex`) are dev-tool-only and do not ship in the
+  package.
+
+### Added
+
+- **`retrieve --wait` establishes readiness or a condition by a deadline (#364).**
+  One final envelope over REST or native API, with elapsed time, attempts and
+  completed observations. `--until` uses the shared query grammar and succeeds
+  on any matching selected row; `--until-empty` requires a completed zero-row
+  read. Already-true conditions succeed immediately. Only transient transport
+  errors retry; authentication and validation fail immediately. `--timeout`
+  bounds each request, and optional `--sample` sets observation cadence.
+- **`retrieve --follow` keeps a menu's rows current over native API (#396).**
+  Snapshot rows, one `synced` line, then a line per change, as NDJSON; an
+  `.id` sweep (`--sweep`, default 10s) reports removals RouterOS never sends
+  on view menus. Single target; `--query` / `--filter` (#397) use device
+  membership reads and filtered sweeps, with membership removals distinguished
+  from wire deletions. `--sweep`
+  needs a unit (`10s`); only `0` (off) may be bare.
+- **`retrieve --sample <interval>` re-reads a menu on a timer.** One line per
+  complete read (`data` is the whole read), then a summary; `--count` and
+  `--duration` bound it. Works over REST and native API, on list menus and
+  singletons, and sees counters `--follow` cannot. The interval needs a unit
+  (`5s`): a bare number is refused because RouterOS and centrs read it
+  differently.
+- **`retrieve --query` filters rows on the router (#397).** Write what you
+  would after `print where` (`type=ether and !disabled`, `mtu>=1500`,
+  `(a=1 or b=2)`); centrs compiles it to the API query, so the router filters.
+  `--filter` is the same flag; repeats are AND-ed. Property names are
+  validated, and bare names are asked of the router (`disabled` → `=yes`,
+  `comment` → "is set"). `~`, `in` and script values fail
+  `input/unsupported-query`. Works with `--sample`, fan-out and `--follow`.
+  Checked on CHR against RouterOS's own `find where`.
+- `--format ndjson` for `retrieve`. Library: `retrieveFollow()`,
+  `retrieveSample()`, and `renderRetrieveStreamLine()` for both (it replaces
+  the unreleased `renderRetrieveFollowLine()`).
+
+### Fixed
+
+- `execute` honors an explicit target URL, and native-api honors a typed port
+  (#426, from #384). With no `via` pinned, an `http(s)://host[:port]` target
+  selects rest-api on that scheme and port instead of silently dialing native
+  API on 8728; `meta.settings.via` reports `via:target-url`. A port typed into
+  the target (`host:9`, `--host`, `CENTRS_HOST`) now reaches native-api on
+  every command, below the port settings (`--port`, `CENTRS_PORT`, `port=`,
+  config), as it already did for ssh and REST. An explicit `:80`/`:443`, which
+  URL parsing normalizes away, is kept for native-api and ssh. A matched CDB
+  record's own port is unchanged. A `--quickchr` target keeps native-api
+  whatever `CENTRS_HOST` holds.
+
+- A pinned CDB no longer refuses an address it has no record for (#427, from
+  #384). With `--cdb-file`, `CENTRS_CDB_FILE`, `CENTRS_CDB_PASSWORD` or a
+  `centrs.env` CDB path, an IP, `[IPv6]:port`, `http(s)://` URL or MAC that
+  matches no record is dialed as a literal host, as it is with no CDB. This
+  holds on every command and in fan-out, where each such member also failed. A
+  DNS name or identity that matches nothing still fails closed with
+  `cdb/not-found-target`, and MCP still accepts only registered targets. An
+  IPv6 literal now dials over native-api, ssh, terminal and btest. Before, the
+  address was passed to them still in brackets (`[2001:db8::1]`) and failed to
+  resolve. SFTP, which needs the brackets, keeps them. A bare IPv6 target
+  (`2001:db8::1`, no port) is now accepted everywhere instead of
+  `input/invalid-target`. Error messages bracket an IPv6 endpoint
+  (`[2001:db8::1]:8728`).
+
+- The `--host` flag can stand in for `<router>` (#428, from #384).
+  `execute --host http://192.0.2.10:8080 '<cmd>'`, `execute --host <host> --
+  <cmd>`, `retrieve --host <host> <path>`, `api --host <host> <endpoint>`,
+  `transfer --host <host> <verb>` and `terminal --host <host>` (ssh) now reach
+  the router instead of failing `input/invalid-command` for a missing target.
+  With no `<router>` there is no CDB lookup, so auth comes from flags, env or
+  config. `CENTRS_HOST` doesn't change how positionals are read. Two or more
+  `execute` positionals without `--` still split as `<target> <command>`, so
+  `execute <mac> <cmd> --via mac-telnet --host <udp-host>` is unchanged. The
+  `upload`/`download` aliases still read their first positional as the target.
+
+- A one-shot `retrieve` that fails after resolution keeps the resolved meta
+  (#433). A refused connection, auth failure or validation error now reports
+  `meta.target` (host, port, base URL, record, sources), `meta.via`,
+  `meta.settings` and `meta.operation.auth`, as `execute`, `api` and `transfer`
+  already did. Before, it reported `meta.via: null` and only the typed input.
+  The MCP `centrs_retrieve` tool had the same gap and is fixed too. New
+  library export: `retrieveEnvelope()`, which never throws.
+
+- Error envelopes no longer report validation `failed` when the validator
+  never answered or had passed (#435). A transport or auth failure (and, for
+  `retrieve`, a `routeros/*` error) that stops the gate now omits
+  `meta.validation.result` and the `syntax`/`semantic` summaries. Each stage
+  the gate did not reach reports `skipped` with
+  `reason: "not reached: <error.code>"`. `retrieve` now records the gate's
+  result, so a read that fails after inspect passed reports `passed`. Success
+  envelopes now carry `result: "passed"` too. `--validate=false` reports
+  `{enabled: false, source: "disabled"}` instead of `result: "failed"`. Only a
+  gate refusal reports `failed`. On an `execute` rejection, `syntax: true` now
+  means only a name-level refusal; a `:parse` refusal (syntax, unknown path,
+  missing package, unavailable menu) is `syntax: false` with no `semantic`.
+  Before, every device rejection said `syntax: true`. A failure in `api`'s
+  `--query` boolean probe after the gate passed now reports `passed`. Applies
+  to `execute`, `api` (including `--stream`) and every `retrieve` mode. `ValidationTrace` is now a public
+  type, and `retrieve()` accepts `{ trace }`. The shape is interim until the
+  live-explain review (#236).
+
+- SSH execute, SFTP and terminal add `IdentitiesOnly=yes` when a private key is
+  selected, preventing fallback to unrelated SSH agent identities (#177).
+  Explicit OpenSSH `IdentityFile` configuration continues to apply.
+
+- Query QA declares the RouterOS version split for unquoted firewall `where`
+  literals. Testing/development builds select rows that 7.24.5 does not;
+  both API transports retain exact result checks on either side of the split.
+
+- Fan-out FAIL rows and btest client/server CSV error comments replace terminal
+  controls with spaces (#395, #415). Compact error text stays on one line,
+  including target labels and verbose remediation; JSON/YAML keep the raw values.
+
+- **`api --stream` is now a literal stream of the wire (#402).** Following a
+  menu is the `<menu>/listen` endpoint (GET; implies `--stream` and
+  native-api); a GET with `--stream` streams one literal print. RouterOS's
+  `!empty` is no longer dropped: every reply is a frame, `reply: "re"` (a row)
+  or `"empty"` (`data: null`), and one received after a local stop carries
+  `afterStop: true`. `--count` counts rows only. Property lists and queries go out
+  as typed; `tip/filtered-follow` and `tip/follow-proplist` say what RouterOS
+  will not report, and request-shape tips lead the stream as a `notice`
+  envelope. `--format ndjson` prints every envelope as one compact line,
+  one-shot or streamed. **Breaking:** `--listen` and `ApiRequest.listen` are
+  removed (`usage/removed-flag`, which prints the replacement command with
+  values redacted); `apiListen()` is renamed `apiStream()`, and
+  `ProtocolAdapter.listen()` is `stream()`.
+
+- **`transfer` moves `/file` contents as bytes on REST and native API
+  (#404).** centrs decoded and encoded file contents as UTF-8, so every
+  non-UTF-8 byte became U+FFFD (a 2,842-byte file downloaded as 3,422 bytes).
+  Library: `ProtocolExecuteRequest` and `NativeApiCommand` gain an opt-in
+  `binary` mode; a code unit above U+00FF is refused
+  (`internal/byte-string`). Every other command stays UTF-8.
+
+- `transfer download` checks the local destination before reading the device
+  (#403). A missing parent directory, a destination that is a directory, or a
+  write that still fails reports the new `input/local-destination` (the OS
+  error rides as `cause`) instead of `internal/unhandled` after a full read.
+  Download replaces an existing local file, like `curl -o` and `scp` (#406);
+  `--force` guards device destinations only, and the docs now say so.
+
+- A `transfer` failure after resolution keeps the resolved meta (#391):
+  `meta.target`, `meta.via`, `meta.settings` and `meta.operation.auth`, with
+  no secret values. Batch SSH (sftp `transfer`, `execute --via ssh`) never
+  sends a password, and the `auth/failed` remediation now says so and names
+  the key source; `error.context.sshKeySelected` is new. When a password was
+  resolved, `tip/sftp-password-not-used` and
+  `tip/transfer-password-transport` explain it and suggest `--via rest` or
+  `native-api`. New library export: `transferEnvelope()`, which never throws.
+
+- `explain` reads the CLI Reference layout `manual.mikrotik.com` has served
+  since 2026-10-06, and its path catalog now includes RouterOS 7.26beta1
+  (#417). 47 paths are added (`/cmr/*`, `/system/dashboard`,
+  `/interface/wifi/dashboard`, `/tool/apptraffic`, and others), so commands
+  such as `/cmr/device/reboot` resolve instead of warning.
+
+- **`api --query` uses the `print where` grammar too (#397).** A bare name is
+  now `=yes` for a boolean (was "has the property"; that is
+  `--raw-query name`), `<`/`<=` include rows without the property as `where`
+  does, and a value containing an operator stays one value (`comment=a>b` was
+  sent as `>comment=a=b`). With `--validate=false` or `--raw`, a bare name
+  fails `input/invalid-query`.
+
+- Native API one-shot and incremental commands share their sentence builder;
+  structured POST queries/projections reach both transports. Mutation and script
+  requests reject unused query/projection flags, and PUT/POST reject a
+  trailing row id instead of dropping it. Stream outcomes are read from
+  `meta.operation.stream`; failed summaries retain cancellation warnings, and
+  received terminal attributes survive a local stop (#400).
+
+- **Native `api --stream` runs commands instead of always appending `/listen`
+  (#399).** POST ping/monitor/print commands forward their attributes and emit
+  replies incrementally; terminal attributes are retained. (#402, above,
+  then made GET-menu streams literal.) Natural completion is `completed`; RouterOS/transport
+  failures produce one `ok:false` summary and a nonzero exit, even after rows.
+  **Breaking stream contract:** structured error envelopes now appear on stdout;
+  failed summary counts/reason live in metadata, with no `data` key. Raw errors
+  retain stderr behavior. Fatal sessions close locally even if the peer does not.
+
+- **A menu the device does not have is no longer reported as a syntax error
+  (#361).** RouterOS's `:parse` answers `/zerotier/print` on a router without
+  the package with `syntax error (line 1 column 10)`, and `/zerotier print`
+  with `bad command name zerotier`. Both point at the segment it could not
+  resolve. centrs now locates that segment and looks the path up in its path
+  catalog (every RouterOS 7.10–7.25 build, all extra packages):
+  `validation/package-missing` when MikroTik publishes the menu behind a
+  package (`error.context.packages`, with `/system/package/print` as the fix),
+  `validation/menu-unavailable` when the gate is hardware, build or version
+  (`/interface/w60g` needs `60ghz`; `error.context.gates`), and
+  `validation/unknown-path` when no published build has it. The path can end
+  in a command (`/system/license/output` is `nochr`), and the summary says so.
+  A real syntax fault, and any rejection centrs cannot locate exactly (a
+  menu-scope block, a menu named on an earlier line, a segment written twice),
+  stays `validation/syntax`. Applies to every
+  transport, since all of them classify the same `:parse` return. **Breaking
+  for code that branches on `validation/syntax`** for these rejections: match
+  `validation/package-missing`, `validation/menu-unavailable` and
+  `validation/unknown-path` as well.
+- **Every command now renders errors the same way, and keeps the router's own
+  words (#362).** `execute`, `retrieve`, `api`, `transfer`, `settings`, the
+  fan-outs and five others each had their own text renderer; most dropped the
+  `Details:` link and RouterOS's position, and the device's own verdict was
+  shown only with `--verbose`. All of them now use `formatCentrsErrorText`,
+  which prints, in order: `[code] summary`, `At:` (RouterOS's line/column, or
+  the offline gate's byte span with the bytes it covers), `Device said:`
+  (RouterOS's message, one line, omitted when the summary already quotes it),
+  `Fix:` and `Details:`. A test pins all fourteen renderers to the same text.
+  `api --stream --format text` prints the same fields on one line, joined by
+  ` — ` (`formatCentrsErrorLine`).
+  Two remediation messages stopped claiming a cause they can't know: a device-stage
+  `:parse` rejection no longer says "fix the quotes" (an absent menu or missing
+  package is rejected in the same words; #361 separates them) and points to
+  `centrs explain`, and the `routeros/api-trap` catch-all no longer says the
+  command is likely invalid. The `:parse` preflight wrapper in `execute` also
+  stopped dropping RouterOS's message from `context.detail`. `--json` output is
+  unchanged apart from those remediation strings and the restored
+  `context.detail`.
+
 ## 0.1.7 — 2026-09-27
 
 ### Added

package/GLOSSARY.txt

@@ -69,6 +69,7 @@ Addrs
 ajv
 amazonq
 amm
+~askpass # OpenSSH SSH_ASKPASS helper; the CHR password-login control in ssh-auth-policy.test.ts
 AT-SPI
 awk
 axuielement
@@ -148,6 +149,8 @@ nullglob # bash shopt that makes an unmatched glob expand to zero words instead
 npk # MikroTik package format
 nvme-over-tcp # supported by RouterOS **with** rose-storage.npk extra-package
 OID
+# %OSPF: Open Shortest Path First; RouterOS dynamic routing adjacency protocol.
+OSPF
 PII # Personally Identifiable Information
 PON # passive optical network; RouterOS /interface/ethernet/pon menu
 POV
@@ -309,6 +312,7 @@ ENOTSUP
 EAFNOSUPPORT
 ECONNREFUSED
 ECONNRESET
+EHOSTDOWN
 REUSEPORT
 REUSEADDR
 # L2 bridge frame-parsing terms (test/integration/mndp-l2-bridge.ts):
@@ -339,6 +343,15 @@ creds
 Streamable
 # modelcontextprotocol: npm scope of the MCP SDK (@modelcontextprotocol/sdk).
 modelcontextprotocol
+# nextid: RouterOS `.nextid` on a listen frame after a move (the next row's id; *FFFFFFFF = last).
+nextid
+# WHATWG: the web standards body whose Encoding spec makes TextDecoder("latin1") windows-1252, not a byte decoder (#404).
+WHATWG
+# followable: a RouterOS menu `retrieve --follow` can follow — a list menu whose `print` takes `follow-only` in `/console/inspect` (`validation/not-followable` otherwise; #396).
+followable
+# BFD: Bidirectional Forwarding Detection (`/routing/bfd`); its sessions accept `listen` but never send changes (#396 round 2).
+BFD
+jsc # Bun's `bun:jsc` module (JavaScriptCore heap stats), used by the `--sample` memory regression test
 # WIP: work in progress (used for the upstream MikroTik Docusaurus docs site).
 WIP
 # adhoc: future inline host+credential targets; Phase 1 MCP uses CDB-only targets.
@@ -468,6 +481,12 @@ toarray
 # markdown dictionary knows it but the TypeScript one does not.
 iff
 
+# Dependency vocabulary (package.json overrides)
+# smol: smol-toml, a markdownlint-cli2/cspell transitive pinned past an advisory.
+# katex: a markdownlint-cli2 transitive with a residual dev-only advisory.
+smol
+katex
+
 # 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
@@ -757,3 +776,16 @@ dgram # Node's `node:dgram` UDP socket module — reached by `mac-telnet`, and o
 elsy # the misspelled `else` in `:if (1=1) do={…} elsy {…}` — rejected as `expected end of command` on CHR 7.21.5/7.23.5/7.24.2/7.25beta3, which is what proves the bare-brace `else {` acceptance is a real device fact and not a probe artifact (#347)
 prnt # a misspelt `print` verb — `/ip/address/prnt` is the offline analyzer's ABSTENTION fixture (`verdict: warn`, not `fail`), which is what proves the two-stage validation gate passes an abstention through to the device rather than refusing it (#354)
 zzznotamenu # a menu name no RouterOS build has — `/ip { zzznotamenu { print } }` is a `syntax error` on device, so menu-scope resolution is schema-dependent and a catalog MISS must abstain rather than accept (#348)
+
+# #361 absent-menu controls. Deliberate NON-words: each names a path no RouterOS
+# build has, or quotes a published gate verbatim, so the spelling is load-bearing.
+nosuch # a top-level menu no RouterOS build has — `/nosuch` is `bad command name nosuch` on CHR 7.23.7, the `validation/unknown-path` control (#361)
+nosuchmenu # a submenu no RouterOS build has — `/ip/nosuchmenu/print` is `syntax error (line 1 column 15)` on CHR 7.23.7, pointing at the `/` after it (#361)
+nosuchverb # a command no RouterOS build has under a real menu — `/ip/address/nosuchverb` is `bad command name nosuchverb` on CHR 7.23.7 (#361)
+qqq # the second segment of the parse-oracle row `/zzz qqq print`, captured on CHR 7.23.3 (GH#230)
+userman # MikroTik's published package name `userman-5` for `/user-manager`; the installable package is `user-manager` (#361)
+nochr # a CLI-Reference syscap that excludes CHR — `/system/license/output` is published `nochr` (#361)
+
+# #417 CLI Reference refresh (7.26beta1).
+cmr # MikroTik's optional `cmr` controller package and the `/cmr` menu tree it adds (7.26beta1); the catalog carries `package="cmr"` as its published gate, e.g. `/cmr/device/reboot` (#417)
+apptraffic # two paths new in 7.26beta1 with different published gates: the `/tool/apptraffic` settings menu (conditions `!mmips, !powerpc, !smips`) and the `/cmr/device/apptraffic` command (package `cmr`, no conditions) (#417)

package/README.md

@@ -58,9 +58,9 @@ product; without them this would just be a worse `curl`.
 
 | Command    | Purpose |
 | ---------- | ------- |
-| `retrieve` | Read RouterOS state over REST/native API and SNMP OID/MIB values. |
+| `retrieve` | Read RouterOS state over REST/native API and SNMP OID/MIB values. `--follow` keeps a menu's rows current over native API (snapshot, then a line per change; NDJSON); `--sample <interval>` re-reads it on a timer for counters; `--query` filters on the router with the `print where` grammar; `--wait` retries until a read succeeds (or an optional `--until` condition holds), up to a deadline. |
 | `execute`  | Run RouterOS CLI-shaped read/write commands (add/set/remove) over native API/REST/L2 surfaces. |
-| `api`      | Structured RouterOS API passthrough (gh-api style): one command per operation, structured in/out, can write, over REST or native API. Open-ended follow is `api … --stream` (native API; NDJSON). |
+| `api`      | Structured RouterOS API passthrough (gh-api style): one command per operation, structured in/out, can write, over REST or native API. Follow changes with `api … <menu>/listen`; `--stream` streams any command's replies (native API; NDJSON). |
 | `terminal` | Open an interactive console, primarily SSH or MAC-Telnet. |
 | `check`    | Probe reachability and management protocol availability. **Designed, not implemented** — see `docs/MATRIX.md`. |
 | `explain`  | Analyze a RouterOS command before running it: canonical form, syntax diagnostics, and what is valid at a path. Offline analysis runs today; the live-device probes are designed. |

package/SECURITY.md

@@ -17,7 +17,7 @@ The repository's [Security tab](https://github.com/tikoci/centrs/security) is th
 - **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).
+- **Dependabot security updates** — unsupported for Bun in GitHub's [ecosystem support table](https://docs.github.com/en/code-security/reference/supply-chain-security/supported-ecosystems-and-repositories). [`.github/dependabot.yaml`](.github/dependabot.yaml) configures weekly Bun **version updates** and GitHub Actions updates. Dependency security cleanup also requires `bun audit` and reviewed lockfile upgrades.
 - **Secret scanning** — enabled in GitHub, with push protection.
 - **Private vulnerability reporting** — enabled via GitHub Security Advisories.
 

package/commands/AGENTS.md

@@ -29,7 +29,8 @@ dependencies within the selected capability; they do not replace its status.
 Commands are centrs **verbs** (`retrieve`, `execute`, `api`, `devices`,
 `discover`, `check`, `explain`, `terminal`, `settings`), never one tool per
 RouterOS command. Open-ended follow
-is folded into `api --stream` (no separate `stream` verb). Sub-verbs and their
+is a flag, not a verb: `retrieve --follow` keeps state, `api --stream` is the
+literal wire (no separate `stream` verb). Sub-verbs and their
 aliases are canonical across CLI / API / MCP:
 
 | Canonical | Aliases          | Meaning                                  |

package/commands/api/AGENTS.md

@@ -29,18 +29,13 @@ inspect-client TS patterns — `tikoci/lsp-routeros-ts`
 - **HTTP method map (REST):** `GET`→print, `PUT`→add (**create**), `PATCH`→set,
   `DELETE`→remove, `POST`→universal (run any console command). PUT — not POST — is
   RouterOS's create.
-- **Multi-frame results: bounded → array; open-ended → native `/listen` only.**
-  *Nuance (do not over-read the REST docs).* RouterOS REST **does** run
-  `duration=` / `monitor` commands — it regularizes the native `!re` frames into a
-  JSON **array of `.section` records** and returns the whole array in one response,
-  bounded by the **60 s** REST cap (a command asked to run longer terminates early
-  with an error). Native has **no** such cap. So a `duration=`/`monitor` command is
-  an **ordinary bounded `api` call** that returns a `.section` array on both
-  transports (native's `talk()` accumulates the `!re` until `!done`) — **not**
-  NDJSON. The only thing that needs the NDJSON streaming path is **open-ended
-  follow** (native `/listen`, which never sends `!done`); REST genuinely cannot do
-  open-ended follow. ⇒ `--listen` (open-ended) is native-only; `duration=` commands
-  are normal one-shot calls. (CONFIRMED below.)
+- **Multi-frame results: one-shot → array; incremental replies → native API.**
+  REST regularizes bounded native `!re` replies into a JSON array and retains
+  its 60 s cap. A one-shot native call also accumulates rows until `!done`.
+  GH#399 adds incremental native command replies with `--stream`, including
+  bounded commands and open-ended ping/monitor/print interval. Method semantics,
+  terminal outcomes and subscription limitations live in the README;
+  examples L6–L16 ground the extended path.
 - **`/listen` semantics.** Emits `!re` on change; a deleted/disappeared item's
   `!re` carries the dead flag (docs say `=.dead=yes`; **CHR 7.23.1 sends
   `.dead=true`** — see CONFIRMED below); it never self-terminates. Cancel with
@@ -68,15 +63,18 @@ inspect-client TS patterns — `tikoci/lsp-routeros-ts`
 
 Two layers, both grounded above:
 
-- **`--query` / `--filter`** — structured convenience, **AND-combined** (RouterOS
-  default), repeatable. Each maps to one query word:
-  - `name=value` → `name=value` (eq)
-  - `name!=value` → two words `name=value`, `#!` (eq then NOT-top)
-  - `name>value` / `name<value` → `>name=value` / `<name=value`
-  - `name` (no `=`) → `name` (has-property)
-  Multiple `--query` emit their words in order; RouterOS's implicit AND applies (no
-  `#&` injected). `--query` cannot express OR or arbitrary stacks — that is
-  `--raw-query`.
+- **`--query` / `--filter`** — the `print where` grammar, shared with
+  `retrieve --query` (`src/core/query.ts`, #397), repeatable and AND-ed.
+  `and`/`or`/`!`/parentheses compile to `#&`/`#|`/`#!`; `a!=v` → `a=v` `#!`;
+  `a<v` → `<a=v` `-a` `#|` and `a<=v` → `>a=v` `#!` (`where` counts a row
+  without `a` as smaller than any value; API `<`/`>` skip it); a bare name → `a=yes` for a boolean, otherwise
+  the has-property word `a`, decided by asking the device (completion after
+  `where a=` offers exactly `yes`/`no` for a boolean). The table, refusals and
+  CHR differential (`find where` vs `.query`, 58 expressions, 7.23.7 + 7.24.5)
+  are in `commands/retrieve/README.md` → Query. Until #397 the structured form
+  was a per-word splitter where a bare name meant has-property, `<` skipped
+  rows without the property, and an operator anywhere in the string split it
+  (`comment=a>b` → `>comment=a=b`).
 - **`--raw-query <word>`** — power-user escape hatch, repeatable. Each value is a
   **verbatim RouterOS query word** (absence `-name`, OR `#|`, AND `#&`, NOT `#!`,
   or any `>`/`<`/`=` form). Emitted as-is: a `.query` element over REST, a
@@ -203,8 +201,9 @@ green on CHR 7.23.1.
 ## CONFIRMED ON CHR (Phase 4 `--stream` follow — CHR 7.23.1, 2026-06-30)
 
 Validated by `test/integration/api-listen.test.ts` (L1–L4) on CHR 7.23.1.
-`--stream` is the primary flag; `--listen` is an alias; a `/listen` endpoint
-infers both. Native-api only (REST's 60s cap → `transport/capability-unsupported`).
+Since #402 the `/listen` endpoint is the only way to listen (it implies
+`--stream`); `--listen` is removed. Native-api only (REST's 60s cap →
+`transport/capability-unsupported`).
 
 - **CONFIRMED — `NativeApiSession.listen()` + `/cancel` end-to-end.** Opening
   `/ip/address/listen` (own `.tag`) and adding an address over REST yields an
@@ -212,13 +211,39 @@ infers both. Native-api only (REST's 60s cap → `transport/capability-unsupport
   .tag=<n>` and the listen closes via the `interrupted` trap (category 2) then
   `!done` — the generator ends **without** throwing (the interrupted trap is the
   normal cancel, not an error). A non-interrupted trap or transport closure does
-  throw. Re-confirms the Phase-0 spike through the real `apiListen()` path.
+  throw. Re-confirms the Phase-0 spike through the real `apiListen()` path (now
+  `apiStream()`).
 - **CONFIRMED — deletion frames carry `.dead=true`.** Removing a pre-seeded
   address over REST while listening emits a minimal `{ ".id", ".dead":"true" }`
   `!re` (re-confirms `.dead=true`, not the docs' `=.dead=yes`).
-- **Stream shape:** each `!re` → one NDJSON envelope frame
-  (`meta.operation.stream.kind="frame"`, string values, `.dead` preserved); the
-  stream ends with a summary envelope (`stream.kind="summary"`,
-  `data.stopReason` ∈ `count-reached`/`duration-elapsed`/`interrupted`/
-  `transport-error`, plus `frames`/`durationMs`). The CLI exit code keys on
-  whether the stream *started* cleanly, not on per-frame `ok`.
+- **Stream shape:** each `!re` → one envelope frame
+  (`meta.operation.stream.kind="frame"`, string values, `.dead` preserved).
+  GH#399 supersedes the original terminal/exit behavior: natural completion is
+  distinct from cancellation; a failure summary has `ok:false`, and any failure
+  exits nonzero. The current contract lives in the README.
+
+- **CONFIRMED — addressed-listen deletes (L15), CHR 7.23.7:** `test/integration/api-listen.test.ts`
+  covers `/ip/address/listen ?.id=<id>` both without projection and with
+  `.proplist=address,.id,.dead`. Removing the seeded address must produce
+  `{ ".id": <id>, ".dead": "true" }`. The ID query matches a deletion frame
+  because it carries `.id`; a predicate on another column may hide that frame.
+
+## CONFIRMED ON CHR (#402 literal `--stream` — 7.23.7 + 7.24.5, 2026-10-07)
+
+`api` stopped adding `.id,.dead` to a listen's `.proplist` and stopped
+rejecting filtered listens, so these are now the device's own answers, pinned
+by `test/integration/api-listen.test.ts` (L4, L9, L10, L15, L18):
+
+- **`.proplist=address` strips `.id` and `.dead` from delete frames, even
+  under `?.id=`.** An addressed listen's delete arrives as an `!re` with no
+  attributes (`{}`); an unaddressed one has no `.dead` frame for the row.
+  The `?.id=` exception only holds when the projection names `.id,.dead`
+  (or there is none). This corrects the 2026-10-06 note that it held "with
+  and without `.proplist`": that run had centrs's forced `.id,.dead`.
+- **A filtered listen (`?interface=ether1`) sends nothing for the delete of
+  a matching row.** The only reply in the window is the `!empty` that answers
+  the cancel.
+- **Cancelling a listen that sent nothing** → `!trap` interrupted, `!empty`,
+  `!done`. centrs emits that `!empty` as a frame with `afterStop: true`.
+- **`print interval=1` on an empty table** (`/ip/firewall/raw`) → one
+  `!empty` per tick.