@tikoci/centrs 0.1.8 → 0.1.9-next.22

package/docs/errors/cmr/outcome-unknown.md

@@ -0,0 +1,29 @@
+# `cmr/outcome-unknown`
+
+`execute --cmr` sent the command to a CMR client, but no final status came back
+for it. The command **may have run, may still be running, or may not have
+run**.
+
+## Typical trigger
+
+- CMR reported `failed` with `timed out (6)` (the `timeout=` centrs passes, from
+  `--timeout`) or `std failure: timeout (13)` (CMR's own ~60 s ceiling per call).
+- centrs stopped waiting: its local deadline passed, the operation was
+  cancelled, or the controller connection dropped after the request was sent.
+- The client changed its CMR key (`ids`) during the call, or the controller's
+  inventory could not be re-read afterwards to confirm which client answered.
+
+On RouterOS 7.26beta1, a timed-out or cancelled `run-script` **kept running on
+the client**, and its side effects landed afterwards (#441, #450). A timeout is
+not a rollback.
+
+## Fix
+
+- Check the client's state before doing anything else. Read the menu the
+  command changed, directly or through the controller.
+- Do not re-run a command that is not idempotent until you know it did not run.
+  centrs never retries a CMR dispatch.
+- For long work, raise `--timeout` (up to 55 s per call). Anything needing more
+  than CMR's ~60 s ceiling belongs in a script or scheduler entry on the client.
+
+See [`commands/execute/README.md`](../../../commands/execute/README.md) → CMR.

package/docs/errors/cmr/output-truncated.md

@@ -0,0 +1,16 @@
+# `cmr/output-truncated`
+
+A warning: CMR clipped a client's command output at its cap (about 60 KiB on
+7.26beta1) and appended `...(+N B)`. The command **completed**; only the
+returned text is incomplete. The envelope's `meta.truncated` records it.
+
+## Typical trigger
+
+A command that prints a lot, such as a large `print` or `/export`, run with
+`execute --cmr`.
+
+## Fix
+
+Narrow the output on the client: `print` with `where` and `proplist=`, or
+`:put` only the fields you need. For a full configuration, save it to a file on
+the client instead of printing it.

package/docs/errors/cmr/policy-denied.md

@@ -0,0 +1,31 @@
+# `cmr/policy-denied`
+
+A CMR client ran the command and refused one of its statements with
+`not enough permissions (9)`.
+
+CMR runs `run-script` scripts on each client with only the `read`, `write`,
+`test` and `reboot` policies, and without a user session. Validation cannot
+catch this: the client's `:parse` accepts the command, and the policy check
+happens only when it runs.
+
+The refused statement did not run, and the script stopped there. Statements
+before it **did** run: CMR does not roll them back. Their output, followed by
+the diagnostic, is in `context.output`.
+
+## Typical trigger
+
+- `/user add`, `/user group add` (needs `policy`).
+- `/tool sniffer` (needs `sniff`).
+
+Reading a sensitive value is not this error: it succeeds and returns `*` or an
+empty value.
+
+## Fix
+
+Check what the earlier statements changed. Then run only the refused
+statement, and the ones after it, on the device directly with a user that has
+the policy:
+
+```sh
+centrs execute <device> -- '<command>'
+```

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/cmr/selection-incomplete.md

@@ -0,0 +1,18 @@
+# `cmr/selection-incomplete`
+
+centrs asked the controller, for every `/cmr/device` row, whether it matches
+`--labels`. At least one row got no answer, so the selection is not known and
+**nothing was run**.
+
+## Typical trigger
+
+A per-device preflight call timed out, was cancelled, or lost its connection
+before the controller either refused it (`no devices selected`, so not a
+member) or returned a row (a member).
+
+## Fix
+
+- Check that the controller is reachable and responsive, then retry.
+- Raise `--timeout` if the controller is slow.
+- centrs never runs a partial selection, because a smaller set that reports
+  success would hide the clients it skipped.

package/docs/errors/cmr/validation-incomplete.md

@@ -0,0 +1,23 @@
+# `cmr/validation-incomplete`
+
+The validation result from a CMR client was incomplete, so the command was
+**not** sent to it. The other members are unaffected.
+
+## Typical trigger
+
+centrs validates on each client with `:put [:parse <command>]; :put "<nonce>"`
+through `run-script`. The result is rejected before it is classified when:
+
+- the status was not `success` (for example `timed out (6)`);
+- the output was clipped by CMR's ~60 KiB cap (`...(+N B)`);
+- the nonce line that proves the output is complete is missing;
+- the `:parse` return was empty or was not parse output (IL).
+
+An empty or clipped result is not a pass. Without the completeness check,
+missing output would have read as "no diagnostic".
+
+## Fix
+
+- Make sure the client is connected and responsive, then retry.
+- Very large commands can exceed the output cap once `:parse` echoes them back.
+  Split the work into smaller commands.

package/docs/errors/routeros/version-unsupported.md

@@ -9,6 +9,10 @@ error.
 Distinct from `routeros/unsupported-capability`, where the chosen *protocol*
 cannot carry the operation at all regardless of device version.
 
+`execute --cmr` raises it with `capability: cmr-controller` when the target has
+no `/cmr/device` and runs RouterOS older than 7.26beta1, where CMR first
+shipped. That check reads the version only after the missing menu, not before.
+
 ## Context fields
 
 - `capability` — stable slug of the missing operation.

package/docs/errors/transport/write-outcome-unknown.md

@@ -0,0 +1,24 @@
+# `transport/write-outcome-unknown`
+
+A warning on a failed write. The request had already been sent when the
+transport failed (a dropped connection, a REST 5xx, a timeout), so the router
+may have run it. The error beside this warning says how the call ended, not
+whether the write happened.
+
+## Typical trigger
+
+- A connection closed or reset after an `execute` or `api` write was sent.
+- A REST 5xx or a timeout on a write.
+
+centrs never retries a write that it has sent, in single-target or fan-out
+mode, because replaying an `add`, a script run or a counter change would apply
+it twice (#448). In fan-out, a write is retried only when a retryable
+transport failure (`transport/network` or `transport/connection-closed`) ends
+it *before* it was sent, for example during remote validation or a native API
+login. Any other failure, sent or not, is not retried.
+
+## Fix
+
+Check the router's state before running the write again. For example, read
+back the menu you changed with `centrs retrieve`. Re-run only what did not
+apply.

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/docs/errors/usage/missing-labels.md

@@ -0,0 +1,19 @@
+# `usage/missing-labels`
+
+`centrs execute --cmr` was given no `--labels` expression.
+
+## Typical trigger
+
+`--cmr` runs the command on the CMR clients a label expression selects, and the
+expression is required so the blast radius is always explicit.
+
+## Fix
+
+Pass RouterOS label syntax: a comma list where plain labels are OR, `+label`
+must match, `-label` excludes, and `all` selects every device, including the
+controller:
+
+```sh
+centrs execute ctl --cmr --labels all -- ':put [/system/identity/get name]'
+centrs execute ctl --cmr --labels site-a,+edge,-ctl --yes -- '/ip/dns/set servers=192.0.2.53'
+```

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@tikoci/centrs",
-	"version": "0.1.8",
+	"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

@@ -47,6 +47,7 @@ import {
 	buildFanoutResolveFailure,
 	commonVia,
 	defaultFanoutSleep,
+	mayRetryUnsentWrite,
 	resolveFanoutConcurrency,
 	runFanout,
 	summarizeFanout,
@@ -61,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,
@@ -86,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;
 }
 
@@ -105,7 +110,10 @@ export interface ApiFanoutInternals {
 		env: Record<string, string | undefined>,
 		config?: Record<string, string | undefined>,
 	) => Promise<SelectionExpansion>;
-	execute?: (resolved: ResolvedApiRequest) => Promise<ApiSuccessEnvelope>;
+	execute?: (
+		resolved: ResolvedApiRequest,
+		trace: ValidationTrace,
+	) => Promise<ApiSuccessEnvelope>;
 	sleep?: (ms: number) => Promise<void>;
 }
 
@@ -121,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,
 	};
 }
@@ -238,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: [],
@@ -318,6 +332,8 @@ export async function apiFanout(
 				),
 				member,
 			),
+		mayRetry: (resolved) =>
+			mayRetryUnsentWrite(requestSummary.write, traces.get(resolved)),
 		sleep,
 	});