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

package/docs/CONSTITUTION.md

@@ -177,8 +177,29 @@ Notes:
   lossless rule applies to **stdout** only: **stderr** carries progress and
   interactive prompts (discover scan progress, write/ambiguity confirmation) and
   is exempt — use it sparingly, since most operations are fast.
+- **Text stdout is data** (#470). In text mode a single-target `execute`,
+  `api`, `retrieve` or `transfer` writes only `data` (or its error) to stdout.
+  The notes around it go to stderr: the `--verbose` header first, then one
+  `warning [<code>]: <message>` line per warning, then the `Tips:` footer, on
+  success and on failure alike. `transport/provider-trust` is left out of text
+  because it rides every quickchr run over TLS or SSH. `--json` keeps
+  everything, `api --raw` stays a bare payload, and fan-out text is a report,
+  not data, so it keeps its warnings on stdout. A text stream writes only its
+  data rows (`frame`, `sample`) to stdout; its `started`, `synced` and
+  `summary` lines, tips, warnings and errors go to stderr (#473).
 - `data` is the only field whose *shape* varies by command. Everything else —
   including `warnings` and `tips` — is invariant in shape; only contents differ.
+- **Shared meta is written once** (#461, #462). A fan-out target's
+  `meta.settings` keeps only the keys whose source differs from the outer
+  `meta.settings`, and its `meta.operation` drops `request` and `auth` when
+  they equal the outer operation's. When every target agrees on `auth`, or
+  on a setting the outer `meta.settings` lacks, it moves to the outer
+  envelope. A reader takes the target's value, else
+  the outer one (`expandFanoutTarget`). A stream (`retrieve --follow`,
+  `retrieve --sample`, `api --stream`) opens with a `started` line that
+  carries the full meta and any request advice in `tips`, and ends with a
+  full-meta `summary` (`--follow`'s `synced` is full too). The data lines
+  between (`frame`, `sample`) carry only `meta.operation` (#473).
 
 ## Error model
 
@@ -304,8 +325,10 @@ Fan-out output is the locked **`FanoutData`** envelope: `data = { summary, targe
 is an inner `ok:false` envelope (output, not metadata). `targets[]` is reassembled
 in resolved record order, not completion order, so repeated runs diff cleanly. The
 **process exit code** is granular and uniform across fan-out commands: `0` every
-target ok (or an empty selection), `2` partial (some ok, some failed), `1`
-orchestration error or every target failed.
+target ok (or an empty selection for a read), `2` partial (some ok, some
+failed), `1` orchestration error or every target failed. An empty selection is
+a warning for a read and an orchestration error for a write, `--yes` or not,
+so a mistyped selector never passes for a successful bulk write (#460).
 
 A multi-target **RouterOS write** (e.g. `execute` / `api` add/set/remove across a
 selection) is gated by **`--yes`**, confirmed **once** up front; when it is missing

package/docs/MATRIX.md

@@ -187,10 +187,11 @@ Wire, auth, TCP/UDP, and CI caveats live in `commands/btest/README.md` and the
 (#450), which runs one validated command on CMR clients through their
 controller. The contract is in
 [`commands/execute/README.md` → CMR](../commands/execute/README.md#cmr-clients-through-their-controller---cmr),
-with examples CMR0–CMR14. The CMR-vs-centrs feature map is on #441
-(2026-10-13). Next, in order: the fleet blast-radius gate for controller fleet
-commands (#453), then #449's read-only slice (a `devices` view of members and a
-default controller). Deferred: CDB linkage (#449) and `retrieve --cmr` (#441).
+with examples CMR0–CMR15. Also done: the fleet blast-radius gate for
+controller fleet commands run with plain `execute` or `api` (#453), with
+examples CMR16–CMR18 and api CMR1. The feature map of CMR against centrs is
+on #441 (2026-10-13). Next is the read-only slice of #449 (a `devices` view
+of members and a default controller). Deferred: CDB linkage (#449) and `retrieve --cmr` (#441).
 Live `explain` resumes after this.
 
 **The native-api / NDJSON line** (maintainer decision on

package/docs/errors/cdb/empty-group.md

@@ -2,8 +2,24 @@
 
 The named CDB group contains no records.
 
+## Typical trigger
+
+A fan-out selected only by `--group` (no other selector) whose group matched
+no record: a misspelled or case-mismatched group name, or a group whose last
+member was removed.
+
+- For a **read**, it is a warning on an `ok: true` fan-out envelope with
+  `summary { total: 0, ok: 0, failed: 0 }` and exit code 0.
+- For a **write-shaped** fan-out (`execute` write, a mutating `api` method,
+  `transfer upload|remove|mkdir|copy`) it is an outer error (`ok: false`, exit
+  code 1), with or without `--yes`. `context.write` is `true`.
+
+Any other empty selection (`--where`, `--all`, positionals, mixed) is
+[`cdb/empty-selection`](empty-selection.md).
+
 ## Fix
 
-See [`docs/CONSTITUTION.md`](../../CONSTITUTION.md) for the centrs error
-contract. This stub will be expanded with the typical trigger and remediation
-for `cdb/empty-group`.
+Run `centrs devices groups` to see the groups that exist and their member
+counts, then re-run with the right name. See
+[`docs/CONSTITUTION.md`](../../CONSTITUTION.md) (Target selection) for the
+selector grammar.

package/docs/errors/cdb/empty-selection.md

@@ -5,9 +5,15 @@ The target selection matched no CDB records.
 ## Fix
 
 A fan-out selection involving `--where` / `--all` / `--default` / positionals (on
-its own or mixed with `--group`) resolved to zero targets. This is reported as a
-warning on an `ok: true` fan-out envelope with `summary { total: 0, ok: 0, failed:
-0 }`, not a hard failure — there was simply nothing to run.
+its own or mixed with `--group`) resolved to zero targets.
+
+- For a **read**, it is a warning on an `ok: true` fan-out envelope with
+  `summary { total: 0, ok: 0, failed: 0 }` and exit code 0: there was simply
+  nothing to read.
+- For a **write-shaped** fan-out (`execute` write, a mutating `api` method,
+  `transfer upload|remove|mkdir|copy`) it is an outer error (`ok: false`, exit
+  code 1), with or without `--yes`, so a mistyped selector does not look like
+  a successful bulk write. `context.write` is `true`.
 
 A **group-only** empty (bare `--group`, no other selector) is reported as
 [`cdb/empty-group`](empty-group.md) instead, naming the group that matched nothing;

package/docs/errors/cmr/caller-policy-not-enforced.md

@@ -0,0 +1,46 @@
+# `cmr/caller-policy-not-enforced`
+
+A warning on `execute --cmr`, and on `/cmr/device/run-script` or
+`/cmr/device/reboot` run directly with `execute` or `api`: the controller login
+lacks a policy that the command runs with on the clients, and RouterOS does
+not check it. The login does not limit what a CMR command can change.
+
+## Typical trigger
+
+A write through `--cmr` with a controller login whose group lacks `write`,
+`test` or `reboot`, such as a "reader" account given to an agent. CMR runs
+every `run-script` script on each selected client with `read`, `write`,
+`test` and `reboot`, the controller's own row included. On 7.26beta1,
+RouterOS checked only that the caller had `read` and `api`. These results
+come from the CHR reproduction on #456 (REST, two-CHR lab, 2026-10-13); the
+same `run-script` write was seen on real hardware, and the integration test
+re-proves it (CMR15 in `commands/execute/examples.md`):
+
+| Controller login | Direct write or reboot | Through CMR |
+| --- | --- | --- |
+| `read,api,rest-api` | `not enough permissions (9)` | `run-script` wrote to a client and rebooted it |
+| `read,test,api,rest-api` | `not enough permissions (9)` | `run-script` wrote to the controller's own row; `/cmr/device/reboot` rebooted a client |
+
+MikroTik [says](https://forum.mikrotik.com/t/7-26beta-development-is-released/273582/139) this is fixed for 7.26beta2: a `read` group will not
+be allowed to do it. That has not been checked on a beta2 build yet. centrs
+still warns on any version, because the warning reads the login's policy, not
+the RouterOS version. On a build that refuses the write, the members fail
+instead and the warning only says what the login lacks.
+
+`context` names the login (`username`, `group`), the policies it lacks
+(`missing`) and the ones the command runs with (`runsWith`): `read`, `write`,
+`test` and `reboot` for `run-script`, and `reboot` for `/cmr/device/reboot`.
+centrs reads the policy once per run, from the login's own `/user` row and
+`/user/group`, and only for a write. When that read fails (for example a
+RADIUS login with no `/user` row) there is no warning. Other fleet commands
+(`/cmr/device/upgrade`, `pair`, the rule menus) were not measured, so they
+carry no such warning.
+
+## Fix
+
+Nothing failed; this is information. Do not treat a controller login as
+read-only once the `cmr` package is installed (on 7.26beta1 at least). The
+gates that hold are centrs' own: pass `--yes` only when you intend the write
+on every selected client, and over MCP keep the controller's record at
+`mcp=ro` (the default), which refuses CMR fleet commands outright. Give an
+agent a login on the controller only if it may change every paired device.

package/docs/errors/cmr/empty-selection.md

@@ -1,8 +1,22 @@
 # `cmr/empty-selection`
 
-A warning: the `--labels` expression matched no device in the controller's
-`/cmr/device` inventory, so nothing ran. The result is an empty selection with
-exit code 0, the same as an empty CDB group.
+The `--labels` expression of `execute --cmr` matched no device in the
+controller's `/cmr/device` inventory, so nothing ran.
+
+- For a **read**, it is a warning: `ok: true` with an empty selection and exit
+  code 0, the same as an empty CDB group. A collector that polls a sometimes
+  empty label stays quiet.
+- For a **write-shaped** command it is an error (`ok: false`, exit code 1),
+  with or without `--yes`, so a misspelled label does not look like a
+  successful bulk write. RouterOS refuses an empty selection the same way
+  (`no devices selected`). `context.write` is `true`.
+
+The same code is a **warning** on a CMR fleet command run directly with
+`execute` or `api`, such as `/cmr/vlan/add labels=EDGE` or
+`/cmr/device/reboot labels=Edge`: by the controller's inventory now, its
+selection reaches no device. RouterOS refuses an empty selection for a
+`/cmr/device` command itself; it accepts a rule whose labels match nothing,
+and the rule applies to devices that get the label later.
 
 ## Typical trigger
 

package/docs/errors/cmr/rule-selects-every-device.md

@@ -0,0 +1,32 @@
+# `cmr/rule-selects-every-device`
+
+A warning on `execute` or `api` to a CMR controller: a `/cmr/vlan`,
+`/cmr/wifi`, `/cmr/wifi/radio` or `/cmr/upgrade` rule command has no device
+`labels`, so the rule applies to every device the controller manages, the
+controller included. For `/cmr/vlan` it fires only when `port-labels` is
+missing too.
+
+## Typical trigger
+
+- `/cmr/vlan/add vlan-ids=10` with no `labels` and no `port-labels`. The
+  manual warns that such a rule moves every port of every connected device
+  into `cmr-bridge`, the controller included, which cuts the whole fleet's
+  management access.
+- `/cmr/wifi/add ssid=Office` with no `labels`, or labels that are only band
+  labels (`+5ghz`). The network takes over the radios of every device.
+- `set`, `remove`, `enable` or `disable` of an existing rule that has no
+  `labels`. Its reach is every device too.
+
+centrs reads the rule's `labels` from the command (`add`) or from the rule
+itself (the other verbs). A rule added without `labels` stores none (7.26beta1
+CHR). The command still runs as typed; the warning rides the envelope, and
+the write gate's prompt and `usage/confirmation-required` summary repeat it.
+
+## Fix
+
+Give the rule explicit selectors, for example
+`/cmr/vlan/add labels=office-ap port-labels=ether1 vlan-ids=10 role=trunk`.
+Check which devices a label selects with
+`centrs retrieve <controller> /cmr/device` (`labels`, `auto-labels`). Answer
+`yes` or pass `--yes` only if every device, the controller included, is
+intended.

package/docs/errors/cmr/selection-includes-controller.md

@@ -0,0 +1,27 @@
+# `cmr/selection-includes-controller`
+
+A warning on `execute` or `api` to a CMR controller: a fleet command such as
+`/cmr/device/reboot` or `/cmr/device/run-script` selects the controller's own
+`/cmr/device` row (`controller=true`) as well as its clients. The command acts
+on the controller too.
+
+## Typical trigger
+
+- `labels=all`: per the manual, `all` selects every device, the CMR server
+  included.
+- An exclusion-only expression such as `labels=-core`, which starts from every
+  device.
+- A label the controller also carries, such as its architecture (`x86`) or
+  RouterOS version, from `auto-labels`.
+
+centrs reads the controller's inventory and evaluates the manual's label
+rules over each row's `labels` and `auto-labels`. On a 7.26beta1 lab this
+matched the device's own selection for every expression tried. The result is
+the controller's current view: a disconnected device's `auto-labels` can be
+stale. `context` names the controller and the number of devices selected.
+
+## Fix
+
+Nothing failed; this is information. To leave the controller out, exclude it
+explicitly, for example `labels=all,-<controller identity>` (its identity is
+an automatic label while `/cmr auto-labels` includes identity).

package/docs/errors/usage/flag-after-separator.md

@@ -0,0 +1,34 @@
+# `usage/flag-after-separator`
+
+A centrs flag was written after `--`, where every token is RouterOS input.
+
+## Fix
+
+Move the flag before `--`. The error's remediation prints the corrected
+command line:
+
+```sh
+centrs execute r1 -- '/system/identity/print' --json   # refused
+centrs execute r1 --json -- '/system/identity/print'   # fixed
+```
+
+A bare `--` ends centrs option parsing, so without this check a trailing
+`--json` was sent to RouterOS and failed there as `unknown-attribute`. The check
+covers `execute` (including `--cmr`) and `explain`. It matches only a token that
+is exactly one of the command's long flags (or its `--flag=value` spelling);
+short aliases such as `-u` pass through as RouterOS input. If RouterOS really
+needs such a token, put it inside the quoted command. Password values are
+replaced by `<password>` in the printed command line.
+Credentials embedded in a positional target or a `--host` value are redacted
+to `***@host`, including when `--host` is moved before the separator.
+Credentials in an explicit URL are redacted even when its colon is percent-encoded;
+bare CDB identities such as `rtr@site` remain unchanged. A bare target with
+a percent-encoded colon is masked in diagnostics while remaining eligible
+for CDB identity lookup.
+
+For boolean flags that accept no value (such as `--json` and `--yes`), the
+error explains how to remove an unsupported `=value` rather than printing
+a command that the parser would reject.
+
+See [`docs/CONSTITUTION.md`](../../CONSTITUTION.md) for the centrs error
+contract.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@tikoci/centrs",
-	"version": "0.1.9-next.0",
+	"version": "0.1.9-next.22",
 	"main": "src/index.ts",
 	"module": "src/index.ts",
 	"repository": {
@@ -9,12 +9,12 @@
 	},
 	"homepage": "https://github.com/tikoci/centrs#readme",
 	"bugs": "https://github.com/tikoci/centrs/issues",
-	"packageManager": "bun@1.3.14",
+	"packageManager": "bun@1.4.2",
 	"license": "MIT",
 	"devDependencies": {
 		"@biomejs/biome": "2.5.15",
 		"@secretlint/secretlint-rule-preset-recommend": "^13.0.7",
-		"@types/bun": "1.3.14",
+		"@types/bun": "1.4.2",
 		"cloc": "^2.6.0-cloc",
 		"cspell": "^10.3.6",
 		"has-flag": "4.0.0",
@@ -74,12 +74,14 @@
 		"lint:biome": "biome check .",
 		"lint:fix": "biome check --write .",
 		"lint:secretlint": "secretlint \"**/*\"",
+		"lint:actions": "uvx zizmor --offline .",
 		"test": "bun test",
 		"test:smoke": "bun test test/integration/cli-smoke.test.ts",
 		"test:integration:fast": "bun test test/integration/devices.test.ts test/integration/settings.test.ts",
 		"test:integration:settings": "bun test test/integration/settings.test.ts",
-		"test:integration:smoke": "CENTRS_RUN_FAST_INTEGRATION=1 bun test test/integration/chr-smoke.test.ts",
-		"test:integration": "CENTRS_RUN_FAST_INTEGRATION=1 bun test test/integration/",
+		"chr:prefetch": "bun run scripts/chr-prefetch.ts",
+		"test:integration:smoke": "bun run chr:prefetch && CENTRS_RUN_FAST_INTEGRATION=1 bun test test/integration/chr-smoke.test.ts",
+		"test:integration": "bun run chr:prefetch && CENTRS_RUN_FAST_INTEGRATION=1 bun test test/integration/",
 		"test:integration:stable": "CENTRS_CHR_CHANNEL=stable bun run test:integration",
 		"test:integration:long-term": "CENTRS_CHR_CHANNEL=long-term bun run test:integration",
 		"test:integration:testing": "CENTRS_CHR_CHANNEL=testing bun run test:integration",

package/src/api-fanout.ts

@@ -62,9 +62,11 @@ import {
 import { promptForWriteConfirmation } from "./execute.ts";
 import { plannedProtocols, type RouterOsProtocol } from "./protocols/index.ts";
 import {
+	emptyWriteSelectionError,
 	expandSelection,
 	isDefaultRecordTarget,
 	loadEnvFileDefaults,
+	redactTargetInput,
 	type SelectionExpansion,
 	type SelectionMember,
 	type SelectionResolveInput,
@@ -87,6 +89,8 @@ export interface ApiFanoutOperationMeta {
 	concurrency: number;
 	summary: FanoutSummary;
 	request: ApiRequestSummary;
+	/** Hoisted from the targets when every target used the same login (#461). */
+	auth?: { username?: string; passwordProvided: boolean };
 	selection: ApiSelectionSummary;
 }
 
@@ -125,7 +129,7 @@ function summarizeSelection(selection: TargetSelection): ApiSelectionSummary {
 		where: selection.where.map((clause) => `${clause.key}=${clause.value}`),
 		all: selection.all,
 		default: selection.default,
-		positionals: selection.positionals,
+		positionals: selection.positionals.map((value) => redactTargetInput(value)),
 		quickchr: selection.quickchr,
 	};
 }
@@ -242,6 +246,12 @@ export async function apiFanout(
 	const concurrency = resolveFanoutConcurrency(options.concurrency, via);
 
 	if (expansion.empty) {
+		if (requestSummary.write) {
+			throw emptyWriteSelectionError(
+				expansion,
+				`${method} ${requestSummary.path}`,
+			);
+		}
 		return buildApiFanoutSuccess({
 			summary: { total: 0, ok: 0, failed: 0 },
 			targets: [],