@tikoci/centrs 0.1.9-next.0 → 0.1.9-next.23

package/commands/execute/README.md

@@ -47,12 +47,23 @@ selection**, examples F1–F5). `romon` and `winbox-terminal` remain
   write-shaped operation. In script mode every command head in a statement
   (the statement start and each `[…]` or `{…}` body) must be a read: its verb
   is the first word past the known menu prefix, so `/ip address print` is a
-  read and `/user expire-password print` is not (examples W3). Root mutators such as `/import` and indirect
-  execution through `:execute` are write-shaped too, and so is any command
-  carrying `file=`: RouterOS redirects command output into a device file, so
-  `/ip/address/export file=address` creates `address.rsc` and
-  `/file/print file=test` creates `test.txt` even though `export` and `print`
-  are read verbs. The shared
+  read and `/user expire-password print` is not (examples W3). Script
+  directives that only output, branch or compute a value are reads, including
+  the pure functions `:serialize`, `:deserialize`, `:convert`, `:delay`,
+  `:find`, `:timestamp`, `:rndnum`/`:rndstr` and the `:to*` converters, and the
+  `{…}`-bodied `:retry` and `:time` (example W4, #458). The absolute
+  `/serialize` spelling counts too; a bare `serialize` keeps the menu-verb rule,
+  because after navigation it could name a menu command. RouterOS runs only a
+  `{…}` block in a script-typed argument, so every body is visible to the gate.
+  Root mutators such as `/import` and indirect
+  execution through `:execute` are write-shaped too, as are `:global`, `:set`
+  and `:parse`, and so is any command carrying `file=` or `file-name=`
+  (including argument prefixes such as `fi=` and `file-n=`, and the spaced
+  `file-name value` spelling under print/export/serialize, example W5):
+  RouterOS redirects output into a device file, so
+  `/ip/address/export file=address` creates `address.rsc`,
+  `/file/print file=test` creates `test.txt` and `:serialize … file-name=x`
+  creates `x`, even though `export`, `print` and `:serialize` are reads. The shared
   `rosetta`/`lsp-routeros-ts`
   canonicalizer is for canonicalization only — never the structured predicate
   (widening `structured` is a product regression). Pinned by
@@ -180,7 +191,9 @@ duplicate that table. Behavior notes the generated reference cannot carry:
 - `--` — use it when the command contains tokens that would otherwise be
   claimed as centrs flags; otherwise the command must be quoted as a single
   argument. In fan-out, positional targets come BEFORE `--` and the command
-  AFTER it (see **Target selection**).
+  AFTER it (see **Target selection**). centrs flags go before `--` too: one of
+  execute's own long flags after it (a trailing `--json`) is refused before
+  dialing as `usage/flag-after-separator`, with the corrected line (#459).
 
 ### Designed, not implemented
 
@@ -296,8 +309,12 @@ when the target is itself a CMR client.
   selects the controller. CDB selectors (`--group`/`--where`/`--all`/
   `--default`/geo), several targets, and `--via mac-telnet|ssh` are
   `usage/conflicting-flags`. `--labels` without `--cmr` is refused the same way.
-  Labels that no device has are accepted silently by RouterOS; an empty
-  selection is `ok: true` with the warning `cmr/empty-selection`. A device's
+  Labels that no device has are accepted silently by RouterOS. An empty
+  selection is `ok: true` with the warning `cmr/empty-selection` for a read,
+  and the outer error `cmr/empty-selection` for a write-shaped command, with
+  or without `--yes` (#460), as RouterOS refuses it (`no devices selected`). A
+  mistyped label then exits 1 instead of looking like a successful bulk write.
+  A device's
   identity selects it only while the controller's `/cmr auto-labels` includes
   `identity` (the default `all` does). On 7.26beta1, after `auto-labels=version`
   a client's row still *showed* its identity label but no longer matched it.
@@ -336,16 +353,33 @@ when the target is itself a CMR client.
 - **Write gate:** one `--yes`/TTY confirmation, naming how many clients will run
   it, how many were excluded, and through which controller. Clients that failed
   validation are never sent the command.
+- **The controller login is not the limit (#456).** On 7.26beta1, RouterOS
+  does not check the caller's policy against a CMR script. `run-script`
+  needed only `read` + `api` on the controller login, and
+  `/cmr/device/reboot` only `read` + `test` + `api`. A login refused a direct
+  write (`not enough permissions (9)`) still wrote to clients and to the
+  controller's own row through `run-script`, and rebooted a client through
+  both. So a "reader" login on a 7.26beta1 controller is not read-only, and
+  centrs' write gate (and `mcp=ro` on MCP) is the only gate. MikroTik
+  [says](https://forum.mikrotik.com/t/7-26beta-development-is-released/273582/139) 7.26beta2 refuses this for a `read` group; that is not yet
+  checked on a beta2 build. For a write,
+  centrs reads the login's own `/user` row and `/user/group` once (both are
+  readable with just `read` + `api`). When the login lacks `write`, `test` or
+  `reboot`, the result and the confirmation error carry
+  `cmr/caller-policy-not-enforced` naming what it lacks. A failed read only
+  loses the warning.
 - **Dispatch:** one call per validated member, sending the input unchanged with
   `timeout=` set from `--timeout` (capped at 55 s, under CMR's ~60 s per-call
   ceiling). Every call pins `strategy=parallel fail-policy=continue
   freeze-frame-interval=20ms`. **Never retried.**
 - **Outcomes** are a `FanoutData` envelope in inventory order, with exit codes
-  0/2/1. Each member's `meta.target.cmr` carries `{controller, id, deviceKey,
-  address}`. `success` → `data.ret` holds the client's output; a clipped
+  0/2/1. The outer `meta.target` is the controller, and the settings,
+  request and login every member shares are written once on the outer
+  envelope ([constitution](../../docs/CONSTITUTION.md#result-envelope)). Each
+  member's `meta.target.cmr` carries `{id, deviceKey, address}`. `success` → `data.ret` holds the client's output; a clipped
   output adds `cmr/output-truncated` and `meta.truncated`. `--max-results`
   applies per member, as in plain execute fan-out: a member whose rendered
-  envelope exceeds it (UTF-8 bytes) becomes `input/max-results-exceeded`, and
+  envelope (with its full meta, as it would render alone) exceeds it (UTF-8 bytes) becomes `input/max-results-exceeded`, and
   that error says the command already ran (`context.dispatched: true`). A `failed` runtime
   error maps through the usual `routeros/*` table. `skipped` →
   `cmr/client-disconnected`.
@@ -366,8 +400,15 @@ when the target is itself a CMR client.
 - **Validation metadata** reports what ran: `source: ":put [:parse ...] via cmr
   run-script"`, the same claim the console gate makes. There is no client
   `/console/inspect` stage.
-- **Not on MCP** until delegated authorization is designed (#449). `retrieve
-  --cmr` is deferred (#441).
+- **No progress stream.** `run-script` returns a client's output only when its
+  script ends, and no `/cmr` menu records a running script. To watch a long
+  CMR job, follow what it changes on a client:
+  `centrs retrieve <client> /ip/address --follow` while
+  `execute <controller> --cmr` adds addresses. That only works when the client
+  can also be reached directly; otherwise re-run a read through `--cmr`.
+- **Not on MCP** until delegated authorization is designed (#449). That design
+  must not assume RouterOS refuses a fleet write for a `!write` login (see
+  above). `retrieve --cmr` is deferred (#441).
 
 `/cmr/device/dashboard` is an interactive console view, refused as
 `cmr/console-only`. A plain path, abbreviated or not (`/cmr/dev/dash`), is
@@ -382,6 +423,59 @@ Calling `/cmr/device/run-script` yourself, through `api` or plain `execute`,
 validates only the controller request. The envelope then carries the warning
 `cmr/client-script-not-validated`.
 
+### Fleet commands run directly (#453)
+
+A controller's fleet commands are one request to one router that act on many
+devices: `/cmr/device/{reboot,upgrade,pair,run-script}`,
+`/cmr/upgrade/trigger`, `/cmr/upgrade/job/run-next`, and `add`, `set`,
+`remove`, `enable` or `disable` on `/cmr/vlan`, `/cmr/wifi`,
+`/cmr/wifi/radio` and `/cmr/upgrade`. They are write-shaped, so they need
+`--yes`. Before that gate, plain `execute` (and `api`) reads the controller's
+`/cmr/device` inventory, read-only, and resolves which rows the command
+reaches, where it can (see "Not resolved" below). The command still runs
+exactly as typed.
+
+- **The gate names the reach.** The prompt and the `usage/confirmation-required`
+  summary say how many CMR devices the command reaches and whether the
+  controller's own row (`controller=true`) is one of them. `error.context.cmr`
+  has `devices`, `connected`, `controllerIncluded`, `identities` and
+  `inventory`.
+- **How the selection is resolved.** `numbers` matches a row's `.id` or
+  identity. `labels` follows the manual's rules over the row's `labels` and
+  `auto-labels`: plain labels are OR, `+label` must match, `-label` excludes,
+  `all` selects every row, and an expression with only exclusions starts from
+  every row. On a 7.26beta1 lab this matched the device's own selection
+  (a `run-script` probe per row) for every expression tried; the lab test
+  re-checks it (CMR-D9). It is the controller's current view: a disconnected
+  device's `auto-labels` can be stale. `/cmr/upgrade/trigger` reaches the rows
+  whose `upgrade-rule` it names. A rule's `set`, `remove`, `enable` or
+  `disable` reads the rule's own `labels`; a `set` that changes `labels`
+  reaches the old and the new devices. WiFi band labels (`+2ghz`, `+5ghz`,
+  `+6ghz`) pick radios, not devices, so they are left out.
+- **Warnings, with or without `--yes`:**
+  - `cmr/selection-includes-controller`: the selection includes the
+    controller's own row (`labels=all` does, per the manual).
+  - `cmr/rule-selects-every-device`: a rule command with no device `labels`
+    (for `/cmr/vlan`, no `port-labels` either). The manual warns that such a
+    VLAN rule provisions every port of every connected device, the controller
+    included, and cuts the fleet's management access.
+  - `cmr/empty-selection`: by the controller's inventory now, nothing is
+    selected. RouterOS refuses this for a `/cmr/device` command; it accepts
+    a rule whose labels match nothing.
+  - `cmr/caller-policy-not-enforced` for `run-script` and `reboot`, as for
+    `--cmr` above (#456).
+- **Not resolved:** an abbreviated selector argument (`lab=all`),
+  `--via ssh` or `mac-telnet`, `/cmr/upgrade/job/run-next` (a job's devices
+  are not in the inventory), and a failed read. The gate still names the
+  fleet command and says why its reach is unknown, for example `would reach
+  the CMR devices it selects through controller ctl (not resolved: an upgrade
+  job's devices are not in the inventory)`, and `error.context.cmr` has
+  `unresolved` instead of the counts. A failed read never blocks the command,
+  and after a transport or login failure the policy read is skipped. Two
+  cases are not recognized as fleet commands at all and keep the plain
+  wording: script-shaped input (a positional id or `[find …]`) and CDB fan-out
+  to several controllers, which has its own gate.
+
 ## mac-telnet L2 validation
 
 Decided (2026-06-06): the real-L2 integration path is `@tikoci/quickchr`'s

package/commands/execute/examples.md

@@ -530,6 +530,25 @@ has no `result`, `syntax` or `semantic`. Its stages are `offline: passed`, then
 `device: skipped` with `reason: "not reached: transport/auth-failed"`. RouterOS
 answered 401 before `:parse` could give a verdict.
 
+### V9. A stray `}` that RouterOS would silently discard is refused (#504)
+
+A `}` or `]` that closes nothing at the top level makes RouterOS accept the
+script and stop reading there: everything from that byte on is dropped without a
+word. `/system identity set name=a}` sets the identity to `a`. `explain` reports
+it as a `warning`, because nothing is rejected (`commands/explain/examples.md`
+example 42). The gate refuses that one warning by code, because the script the
+device would run is not the one that was written.
+
+```bash
+centrs execute $R ':put "first"};:put "second"' --via rest-api --username $U --password $P --json
+```
+
+Envelope: `ok: false`, `error.code=validation/syntax`,
+`error.context.validationStage="offline"`, `error.context.span` covering the `}`
+through the end of the input, and
+`error.context.diagnostics[0].code="explain/canonicalizer/discarded-close"`. With
+`--validate=false` the device runs it and prints only `first`.
+
 ## Write authorization and returned runtime faults
 
 These regressions are transport-independent and run in
@@ -573,6 +592,47 @@ argument happens to be `print`, so it returns `usage/confirmation-required`.
 Every command head in a statement is checked, including `[…]` and `do={…}`
 bodies.
 
+### W4. Pure script functions are reads; an output file is not (#458)
+
+```bash
+centrs execute $R ':put [:serialize to=json [/system/resource/print as-value]]' --via rest-api --username $U --password $P </dev/null
+```
+
+Envelope: `ok: true` without `--yes`; `data.ret` parses as JSON whose
+`version` is the router's. `:delay`, `:convert`, `:deserialize`, `:find`,
+`:timestamp`, `:rndnum`, `:rndstr`, the `:to*` converters, `:retry` and `:time` are reads
+too; any command inside their arguments or `{…}` bodies is still checked.
+RouterOS runs only a `{…}` block in a script-typed argument and refuses a quoted
+string there, so no body hides in text. `:serialize … file-name=centrs-w4`
+creates a device file, so it returns `usage/confirmation-required`, as `file=`
+does under a read verb. `:global`, `:set`, `:execute` and `:parse` stay writes.
+
+### W5. Abbreviated output-file arguments keep the write gate
+
+```bash
+centrs execute $R '/system identity export fi=centrs-w5' --via rest-api --username $U --password $P </dev/null
+centrs execute $R ':serialize to=json value=1 file-n=centrs-w5.json' --via rest-api --username $U --password $P </dev/null
+```
+
+Both return `usage/confirmation-required` and create no file. The same
+commands with `--yes` pass validation and create `centrs-w5.rsc` and
+`centrs-w5.json`, respectively. Native API has the same result. Through
+`centrs_execute`, an `mcp=ro` record returns `cdb/write-not-permitted` with or
+without `confirm: true`, and creates no file.
+
+RouterOS also accepts `fi "centrs-w5"` and `file-n "centrs-w5.json"`, without
+`=`. They keep the same confirmation and MCP policy gates, including when
+serialize's file argument follows a nested value expression.
+
+`test/integration/execute-write-gate.test.ts` proves the refusal, absence and
+confirmed creation. The export control runs on the selected channel; the
+serialize control pins CHR 7.26beta1, where its file output was reproduced.
+The export uses CLI script spelling: structured attribute validation requires
+full argument names and rejects `fi` as `validation/unknown-attribute`.
+This is a grounding version, not an introduction boundary. Unknown or
+ambiguous output-file prefixes stay write-shaped until the device resolves
+them.
+
 ### R1. A post-validation `/execute` rejection fails the overall envelope
 
 ```bash
@@ -622,6 +682,16 @@ centrs execute --group no-such-group --via rest-api --cdb-file $CDB --json -- /s
 `ok: true`, `data.summary = { total: 0, ok: 0, failed: 0 }`,
 `warnings` include `cdb/empty-group`. Exit `0`.
 
+The same group with a write is an outer error, with or without `--yes`, so a
+misspelled group cannot pass for a successful bulk write (#460):
+
+```bash
+centrs execute --group no-such-group --via rest-api --cdb-file $CDB --yes --json -- '/system/identity/set name=x'
+```
+
+`ok: false`, `error.code` `cdb/empty-group`, `error.context.write` `true`.
+Exit `1`. Nothing is dialed.
+
 ### F3. `--where` device-class selector (subset)
 
 ```bash
@@ -763,7 +833,7 @@ transport.
 ### Q3. Repeated `--quickchr` fans out; an unknown machine is an inner failure
 
 ```bash
-centrs execute --quickchr $NAME --quickchr no-such-machine -- ':put 1' --json
+centrs execute --quickchr $NAME --quickchr no-such-machine --json -- ':put 1'
 ```
 
 Envelope: outer `ok: true`, `data.summary = { total: 2, ok: 1, failed: 1 }`;
@@ -775,9 +845,9 @@ the unknown machine's inner error is `quickchr/machine-not-found`. Exit code 2
 `test/integration/execute-cmr.test.ts` runs these on a two-CHR CMR lab
 (`test/integration/cmr-lab.ts`): `$CTL` is a 7.26beta1 controller with the
 `cmr` package, paired with one client over a socket link. Examples CMR1–CMR7
-and CMR10–CMR14 run over **both** `--via native-api` and `--via rest-api` to
+and CMR10–CMR18 run over **both** `--via native-api` and `--via rest-api` to
 the controller, with validation on. The same test first asserts the device
-behaviour the design depends on (CMR-D1–D8 in the test file).
+behaviour the design depends on (CMR-D1–D9 in the test file).
 
 ### CMR0. A router without CMR
 
@@ -856,6 +926,16 @@ centrs execute --quickchr $CTL --cmr --labels no-such-label -- ':put x'
 `ok: true`, `data.summary.total` is 0, warning `cmr/empty-selection`, exit
 code 0.
 
+The same labels with a write are an outer error, with or without `--yes`, as
+RouterOS itself refuses an empty selection (#460):
+
+```bash
+centrs execute --quickchr $CTL --cmr --labels no-such-label --yes -- '/system/note/set note="x"'
+```
+
+`ok: false`, `error.code` `cmr/empty-selection`, `error.context.write` `true`,
+exit code 1. No note changes.
+
 ### CMR8. CLI exit code for a mixed result
 
 CMR2 through `runCli` exits `2`.
@@ -920,6 +1000,21 @@ centrs execute --quickchr <client> --cmr --labels all -- ':put x'
 `cmr/not-a-controller`: the client runs 7.26beta1 but has no `cmr` package.
 `context.controllerIdentity` names the controller it is paired to.
 
+### CMR15. A controller login without `write` or `reboot`
+
+The controller has a group with `read,test,api,rest-api,!write,!reboot,!sensitive,!policy`
+and a user `$READER` in it. That login cannot write on the controller
+directly, but:
+
+```bash
+centrs execute 127.0.0.1 --port $API --username $READER --password $PW --cmr --labels <client> --yes -- '/system/note/set note="<marker>"'
+```
+
+The target is `ok`, the client's note reads `<marker>`, and the envelope warns
+`cmr/caller-policy-not-enforced` with `context.missing` `["write", "reboot"]`:
+CMR ran the script with `read,write,test,reboot` (#456). The same write as the
+lab's admin login has no such warning.
+
 ### CMR13. The dashboard behind a relative menu change
 
 ```bash
@@ -931,3 +1026,42 @@ The first is `cmr/console-only`: the controller's `:parse` resolves it to
 `/cmr/device/;(evl /cmr/device/dashboard)`, so it is refused before it runs.
 The second is `ok` with `data.ret` `CMR device dashboard`: a string that spells
 the words is not a command.
+
+### CMR16. A fleet command names the devices it reaches (#453)
+
+```bash
+centrs execute --quickchr $CTL -- '/cmr/device/reboot labels=all'
+```
+
+Without `--yes` (no TTY) this is `usage/confirmation-required`. Its summary
+says it would reach 2 CMR devices, the controller itself among them, and
+`error.context.cmr` is `{devices: 2, controllerIncluded: true}` with both
+identities. The envelope warns `cmr/selection-includes-controller`.
+Nothing reboots.
+
+### CMR17. A rule with no labels
+
+```bash
+centrs execute --quickchr $CTL --yes -- '/cmr/vlan/add vlan-ids=4001 disabled=yes comment=<marker>'
+```
+
+`ok: true` with the warning `cmr/rule-selects-every-device`: the rule has no
+`labels` and no `port-labels`. It is added disabled, so nothing is
+provisioned. Removing it by its `.id` warns the same way, read from the rule:
+
+```bash
+centrs execute --quickchr $CTL --yes -- '/cmr/vlan/remove numbers=<id>'
+```
+
+### CMR18. `run-script` called directly by a login without `write` or `reboot`
+
+With CMR15's restricted login:
+
+```bash
+centrs execute 127.0.0.1 --port $API --username $READER --password $PW --yes -- '/cmr/device/run-script labels=<client> script=":put centrs-cmr18"'
+```
+
+`ok: true`, with the warnings `cmr/caller-policy-not-enforced`
+(`context.missing` `["write", "reboot"]`) and
+`cmr/client-script-not-validated`. The same command as the lab's admin login
+has neither the policy warning nor `cmr/selection-includes-controller`.