@tikoci/centrs 0.1.4 → 0.1.7

package/docs/errors/cdb/file-exists.md

@@ -0,0 +1,23 @@
+# `cdb/file-exists`
+
+`devices init` found a CDB already at the resolved location and wrote nothing.
+
+This is a warning on a successful result, not an error. Like `git init`,
+`centrs devices init` never overwrites an existing CDB. When the file there
+already loads as a CDB, `init` succeeds with `data.created: false` and
+`data.recordCount` set to the number of records it holds, and leaves the file
+byte-for-byte untouched. A bootstrap script can therefore run `init`
+unconditionally.
+
+A file at that path that does not load as a CDB is not reported here. `init`
+fails with the load error instead (`cdb/parse-failed`, or
+`cdb/password-required` for an encrypted CDB without `--cdb-password`), and
+still leaves the file alone.
+
+## Fix
+
+Usually nothing: the CDB you asked for exists.
+
+- To see what it holds: `centrs devices list --cdb-file PATH`.
+- To start fresh, pick a different path (`centrs devices init --cdb-file
+  NEW_PATH`), or move the existing file aside yourself; centrs never deletes it.

package/docs/errors/input/invalid-target.md

@@ -2,8 +2,30 @@
 
 The target string is invalid for the requested operation.
 
+A command's `<router>` is looked up in the CDB first: its `target`, or an
+`identity=` / `mac=` / `ip=` comment lookup key. When nothing matches, centrs
+treats the string as a host. This error means it is not a valid host either,
+or it is a URL that carries a path. Common causes:
+
+- **`quickchr:NAME`**: there is no `quickchr:` target prefix. A quickchr VM is
+  selected with a flag: `--quickchr NAME`.
+- **A typo or stray characters**, such as spaces or an extra `:` (`a b`,
+  `bad:host:name`).
+- **A base URL with a path**, such as `http://192.0.2.1/rest`. The RouterOS
+  menu path is a separate argument.
+
+The rejected string is in the error's `context.target`.
+
 ## Fix
 
-See [`docs/CONSTITUTION.md`](../../CONSTITUTION.md) for the centrs error
-contract. This stub will be expanded with the typical trigger and remediation
-for `input/invalid-target`.
+Pass one of the accepted target forms:
+
+| Form | Example |
+| ---- | ------- |
+| CDB target or lookup key | `edge1` (see `centrs devices list`) |
+| IP address or hostname, optional `:port` | `192.0.2.1`, `router.example:8080` |
+| Base URL without a path | `https://192.0.2.1:8443` |
+| quickchr VM | `--quickchr NAME` (a flag, not a prefix) |
+
+With an explicit `--cdb-file` and no `__default__` fallback record, a string
+that matches no record stops earlier with `cdb/not-found-target`.

package/docs/errors/routeros/invalid-value.md

@@ -1,12 +1,13 @@
 # `routeros/invalid-value`
 
-RouterOS rejected the value supplied for an argument. The offending argument
-name is captured in `context.argument`.
+RouterOS rejected a supplied value. When RouterOS names the offending argument,
+it is captured in `context.argument`.
 
 ## Typical RouterOS strings
 
 - `invalid value for argument <name>`
 - `invalid value of <name>`
+- `input does not match ...`
 
 ## Fix
 

package/docs/errors/transport/cancel-unacknowledged.md

@@ -0,0 +1,24 @@
+# `transport/cancel-unacknowledged`
+
+RouterOS did not acknowledge a stream's /cancel within the timeout; centrs ended
+the stream and closed the session locally.
+
+## When it happens
+
+This is a **warning** on the summary envelope of `centrs api … --stream`, not a
+failure. The stream stopped for its normal reason (`--duration` elapsed, or
+Ctrl-C), and centrs sent RouterOS `/cancel` for the `/listen`. A cooperating
+router answers with an `interrupted` trap and `!done` within milliseconds. This
+one did not answer within `--timeout`, so centrs stopped waiting, closed the
+native API session and finished.
+
+The summary's `stopReason` is still the reason the stream stopped. The warning
+records that the router never confirmed the cancel, so the stop was local.
+
+## Fix
+
+- Usually nothing: the stream ended when you asked, and the session is closed.
+- If it repeats against one router, the API connection is likely stalled (a
+  router under load, or a firewall or NAT device holding the TCP session).
+  Check the router's CPU and the path to it before relying on long-lived
+  streams there.

package/docs/errors/validation/syntax.md

@@ -1,9 +1,34 @@
 # `validation/syntax`
 
-RouterOS rejected the command syntax during the :parse gate.
+The command syntax was rejected by the validation gate — offline analysis, or
+the RouterOS `:parse` probe.
+
+The gate has two stages
+([`docs/CONSTITUTION.md` → Validation is the product](../../CONSTITUTION.md#validation-is-the-product)),
+and `error.context.validationStage` says which one spoke:
+
+- **`"offline"`** — centrs rejected the input before any connection was opened,
+  and `meta.validation.stages[]` shows the device stage `skipped`: the router was
+  never asked. The **corpus-gated analyzer** is the whole of this stage, and
+  `error.context.validationSource` names it. `error.context.span` carries the
+  offending byte range (end-exclusive) and `error.context.diagnostics[]` the
+  analyzer's own `explain/<analyzer>/<slug>` codes.
+
+  A quote-balance supplement used to sit beside it for the unterminated `"` or
+  `'` the analyzer passed, reporting no span. It is gone (GH#355): the analyzer
+  rejects a bare `'` itself now, with the byte span, and the supplement's own
+  model of `'` as a delimiter was false-rejecting input RouterOS accepts.
+- **absent** — RouterOS itself rejected it, through `:put [:parse "…"]`. When the
+  device reported a `(line N column M)`, it is on `error.position`, which is
+  RouterOS's authoritative 1-based **byte** column and is never synthesized by
+  centrs. An offline rejection never carries `error.position`.
 
 ## Fix
 
-See [`docs/CONSTITUTION.md`](../../CONSTITUTION.md) for the centrs error
-contract. This stub will be expanded with the typical trigger and remediation
-for `validation/syntax`.
+Run `centrs explain '<command>'` to see the offending bytes in context, fix the
+RouterOS CLI syntax — quotes and bracketed expressions most often — and retry.
+
+`--validate=false` bypasses **both** stages. Use it only to probe a RouterOS edge
+centrs reads wrong, never to work around a rejection you believe is correct: if
+the validator rejects something a real router accepts, the validator is the bug
+(constitution: validation is the product).

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@tikoci/centrs",
-	"version": "0.1.4",
+	"version": "0.1.7",
 	"main": "src/index.ts",
 	"module": "src/index.ts",
 	"repository": {
@@ -31,6 +31,7 @@
 	"exports": {
 		".": "./src/index.ts",
 		"./cli": "./src/cli.ts",
+		"./explain": "./src/explain.ts",
 		"./mcp": "./src/mcp.ts",
 		"./tui": "./src/tui.ts",
 		"./webproxy": "./src/webproxy.ts",
@@ -64,7 +65,7 @@
 		"lint": "bun run lint:biome && bun run lint:typecheck",
 		"lint:git:commit": "bun run lint:biome",
 		"lint:git:push": "bun run lint:ci",
-		"lint:ci": "bun run lint && bun run docs:cli:check && bun run explain:value-census:readme:check && bun run explain:token-census:readme:check && bun run explain:operator-readme:check && bun run lint:markdownlint && bun run lint:cspell && bun run lint:secretlint",
+		"lint:ci": "bun run lint && bun run docs:cli:check && bun run explain:value-census:readme:check && bun run explain:token-census:readme:check && bun run explain:highlight-agreement:readme:check && bun run explain:operator-readme:check && bun run explain:bracket-equals:readme:check && bun run lint:markdownlint && bun run lint:cspell && bun run lint:secretlint",
 		"lint:cspell": "cspell lint . --gitignore",
 		"lint:cspell:all": "cspell lint . --no-gitignore",
 		"lint:markdownlint": "markdownlint-cli2 \"**/*.md\" \"!.scratch/**\"",
@@ -92,9 +93,18 @@
 		"docs:cli": "bun run scripts/gen-cli-docs.ts",
 		"docs:cli:check": "bun run scripts/gen-cli-docs.ts --check",
 		"docs:errors": "bun run scripts/gen-error-pages.ts",
+		"explain:bracket-equals": "bun run scripts/explain-bracket-equals.ts",
+		"explain:bracket-equals:check": "bun run scripts/explain-bracket-equals.ts --check",
+		"explain:bracket-equals:readme": "bun run scripts/explain-bracket-equals.ts --readme",
+		"explain:bracket-equals:readme:check": "bun run scripts/explain-bracket-equals.ts --readme --check",
+		"explain:browser-consumer": "bun run scripts/explain-browser-consumer.ts",
 		"explain:catalog": "bun run scripts/gen-explain-catalog.ts",
 		"explain:catalog:check": "bun run scripts/gen-explain-catalog.ts --check",
 		"explain:corpus-census": "bun run scripts/explain-corpus-census.ts",
+		"explain:highlight-agreement": "bun run scripts/explain-highlight-agreement.ts",
+		"explain:highlight-agreement:check": "bun run scripts/explain-highlight-agreement.ts --check",
+		"explain:highlight-agreement:readme": "bun run scripts/explain-highlight-agreement.ts --readme",
+		"explain:highlight-agreement:readme:check": "bun run scripts/explain-highlight-agreement.ts --readme --check",
 		"explain:highlight-slice": "bun run scripts/explain-highlight-slice.ts",
 		"explain:menus": "bun run scripts/gen-explain-menus.ts",
 		"explain:operator-census": "bun run scripts/explain-operator-census.ts",
@@ -116,6 +126,7 @@
 		"explain:value-census:check": "bun run scripts/explain-value-census.ts --check",
 		"explain:value-census:readme": "bun run scripts/explain-value-census.ts --readme",
 		"explain:value-census:readme:check": "bun run scripts/explain-value-census.ts --readme --check",
+		"explain:arg-reach": "bun run scripts/explain-arg-reach-sweep.ts",
 		"explain:token-census": "bun run scripts/explain-token-census.ts",
 		"explain:token-census:check": "bun run scripts/explain-token-census.ts --check",
 		"explain:token-census:readme": "bun run scripts/explain-token-census.ts --readme",

package/src/api-fanout.ts

@@ -39,6 +39,7 @@ import type {
 	CentrsSuccessEnvelope,
 	FanoutData,
 	FanoutSummary,
+	ValidationTrace,
 } from "./core/envelope.ts";
 import {
 	buildFanoutEnvelope,
@@ -49,6 +50,7 @@ import {
 	runFanout,
 	summarizeFanout,
 } from "./core/fanout.ts";
+import { toYaml } from "./core/yaml.ts";
 import { CentrsError, serializeCentrsError } from "./errors.ts";
 import { promptForWriteConfirmation } from "./execute.ts";
 import { plannedProtocols, type RouterOsProtocol } from "./protocols/index.ts";
@@ -61,7 +63,6 @@ import {
 	type SelectionResolveInput,
 	type TargetSelection,
 } from "./resolver/index.ts";
-import { toYaml } from "./retrieve.ts";
 
 /** Compact description of the selector that produced the fan-out. */
 export interface ApiSelectionSummary {
@@ -246,6 +247,11 @@ export async function apiFanout(
 	await assertFanoutWriteConfirmed(request, requestSummary, method, expansion);
 
 	const execute = internals.execute ?? runResolvedApi;
+	// Per-target validation trace. `execute` and `onExecuteError` are separate
+	// callbacks that share only the resolved request, so the request object is
+	// the key: without it a per-target error envelope would reconstruct
+	// `meta.validation` instead of reporting the gate that actually ran (GH#354).
+	const traces = new WeakMap<ResolvedApiRequest, ValidationTrace>();
 	const sleep = internals.sleep ?? defaultFanoutSleep;
 
 	const targets = await runFanout<
@@ -292,11 +298,18 @@ export async function apiFanout(
 				target: memberTargetMeta(member),
 				warnings: member.kind === "cdb" ? [...member.resolution.warnings] : [],
 			}),
-		execute: async (resolved, member) =>
-			relabelAdhocMember(await execute(resolved), member),
+		execute: async (resolved, member) => {
+			const trace: ValidationTrace = {};
+			traces.set(resolved, trace);
+			return relabelAdhocMember(await execute(resolved, trace), member);
+		},
 		onExecuteError: (resolved, member, error) =>
 			relabelAdhocMember(
-				buildApiErrorEnvelopeFromResolved(resolved, error),
+				buildApiErrorEnvelopeFromResolved(
+					resolved,
+					error,
+					traces.get(resolved),
+				),
 				member,
 			),
 		sleep,