@tikoci/centrs 0.1.3 → 0.1.6

package/docs/errors/usage/stdin-ignored.md

@@ -0,0 +1,28 @@
+# `usage/stdin-ignored`
+
+stdin was redirected but the input came from the positional argument, so
+anything piped in was not analyzed.
+
+This is a **warning**, not an error: the analysis ran and its result is exactly
+what the arguments asked for. What the warning reports is that a second possible
+input source was present and lost.
+
+## Fix
+
+Name the source you meant:
+
+```bash
+cat script.rsc | centrs explain --file -  # analyze stdin
+centrs explain '/ip/route print'          # analyze the positional
+```
+
+The live form spells the same thing (`… | centrs explain edge1 --file -`) and is
+already parsed, but it is refused with
+[`usage/not-implemented`](not-implemented.md) until the phase-2 live probes
+land — so it is not a fix you can apply today.
+
+`explain` reads ambient stdin only when no positional could be the input, so a
+positional always wins. It cannot check whether the pipe actually carries bytes
+without consuming fd 0, which is why the collision is reported rather than
+resolved. See [`commands/explain/README.md`](https://github.com/tikoci/centrs/blob/main/commands/explain/README.md)
+for the positional grammar.

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/docs/errors/validation/unknown-attribute.md

@@ -1,9 +1,42 @@
 # `validation/unknown-attribute`
 
-An attribute is not valid for the path/verb per /console/inspect.
+An attribute or argument is not valid for the requested RouterOS operation.
+The validator rejects the request before RouterOS executes it.
+
+## Context keys
+
+Context keys vary by validation mechanism. Callers must not assume every key
+below is present on every `validation/unknown-attribute` rejection.
+
+| Key | Type | Notes |
+| --- | ---- | ----- |
+| `parameter` | `string` | First offending name. Present on retrieve and inspect-gated rejections, and on console `:parse` when RouterOS reports `bad parameter <name>`. |
+| `requestedAttributes` | `string[]` | Full requested name list. Retrieve and inspect-gated API/execute validation only. |
+| `availableAttributes` | `string[]` | Names exposed for the path/verb. Retrieve and inspect-gated API/execute validation only. |
+| `path` | `string` | Slash-prefixed RouterOS path (for example `/ip/address`). Retrieve and inspect-gated API/execute validation only. |
+| `verb` | `string` | Verb when applicable (`print`, `add`, `set`, …). Inspect-gated API/execute validation only; retrieve is path-only. |
+| `validationSource` | `string` | Validation provenance. Inspect-gated API/execute and console `:parse` only; retrieve does not currently emit it. |
+| `command` | `string` | Original CLI command. Console `:parse` only. |
+| `detail` | `string` | Raw RouterOS parse diagnostic. Console `:parse` only. |
+
+Console `:parse` may also put RouterOS' byte location in the top-level
+`error.position` field. On older RouterOS versions, an unknown name can produce
+only a generic syntax diagnostic; that is reported as `validation/syntax`
+because no parameter identity is available.
+
+Provenance:
+
+- `src/api.ts:988,1033` — REST/native `validateApiRequest` (print vs add/set branches)
+- `src/execute.ts:742` — REST `validateRestExecute`
+- `src/retrieve.ts:233` — REST `retrieve` attribute projection
+- `src/protocols/mac-telnet-console.ts:674` — console `:parse` (`bad parameter <name>`) over mac-telnet/ssh
+- `src/core/routeros-errors.ts:128` — `!trap`/`detail` `unknown parameter <name>` (routeros/unknown-attribute sibling)
 
 ## 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/unknown-attribute`.
+For `retrieve` and inspect-gated API/execute validation, check the name against
+`/console/inspect`; `retrieve --list-attributes` lists the available properties.
+For console `:parse`, compare `context.parameter` with the RouterOS parameters
+for `context.command`; `context.detail` preserves the device's raw diagnostic.
+Use `--validate=false` only when intentionally probing an undocumented RouterOS
+edge.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@tikoci/centrs",
-	"version": "0.1.3",
+	"version": "0.1.6",
 	"main": "src/index.ts",
 	"module": "src/index.ts",
 	"repository": {
@@ -9,11 +9,11 @@
 	},
 	"homepage": "https://github.com/tikoci/centrs#readme",
 	"bugs": "https://github.com/tikoci/centrs/issues",
-	"packageManager": "bun@1.3.13",
+	"packageManager": "bun@1.3.14",
+	"license": "MIT",
 	"devDependencies": {
-		"@biomejs/biome": "2.5.2",
+		"@biomejs/biome": "2.5.7",
 		"@secretlint/secretlint-rule-preset-recommend": "^13.0.2",
-		"@tikoci/quickchr": "^0.4.2",
 		"@types/bun": "^1.3.13",
 		"cloc": "^2.6.0-cloc",
 		"cspell": "^10.0.0",
@@ -22,13 +22,16 @@
 		"secretlint": "^13.0.2",
 		"typedoc": "^0.28.19"
 	},
-	"optionalDependencies": {},
+	"optionalDependencies": {
+		"@tikoci/quickchr": "^0.4.7"
+	},
 	"peerDependencies": {
 		"typescript": "^6.0.3"
 	},
 	"exports": {
 		".": "./src/index.ts",
 		"./cli": "./src/cli.ts",
+		"./explain": "./src/explain.ts",
 		"./mcp": "./src/mcp.ts",
 		"./tui": "./src/tui.ts",
 		"./webproxy": "./src/webproxy.ts",
@@ -45,22 +48,24 @@
 	"files": [
 		"src/",
 		"commands/",
+		"docs/CLI.md",
 		"docs/CONSTITUTION.md",
 		"docs/MATRIX.md",
 		"docs/errors/",
 		"README.md",
 		"CHANGELOG.md",
 		"SECURITY.md",
+		"LICENSE",
 		"GLOSSARY.txt"
 	],
 	"scripts": {
-		"ci": "bun run lint && bun run test && bun run build",
-		"git:pre-commit": "bun run lint",
+		"ci": "bun run lint:ci && bun run test && bun run build",
+		"git:pre-commit": "bun run lint:git:commit",
 		"git:pre-push": "bun run lint:git:push",
 		"lint": "bun run lint:biome && bun run lint:typecheck",
-		"lint:git:commit": "bun run lint",
-		"lint:git:push": "bun run lint:ci && bun run test && bun run build",
-		"lint:ci": "bun run lint && bun run lint:markdownlint && bun run lint:cspell && bun run lint:secretlint",
+		"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: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/**\"",
@@ -82,9 +87,50 @@
 		"test:ci": "bun test --coverage",
 		"test:all": "bun run test:ci",
 		"check:agent": "bun run scripts/agent-check.ts",
+		"corpus:fetch": "bun run scripts/corpus-fetch.ts",
 		"build": "bun build src/index.ts src/cli.ts src/mcp.ts src/tui.ts src/webproxy.ts src/protocols/index.ts --outdir dist --target bun",
 		"build:doc:api": "typedoc --out docs/api src/index.ts",
+		"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",
+		"explain:operator-census:check": "bun run scripts/explain-operator-census.ts --check",
+		"explain:operator-readme": "bun run scripts/explain-operator-slice.ts --readme",
+		"explain:operator-readme:check": "bun run scripts/explain-operator-slice.ts --readme --check",
+		"explain:operator-slice": "bun run scripts/explain-operator-slice.ts",
+		"explain:probe:brace-slots": "bun run scripts/probes/explain-brace-slot-sweep.ts",
+		"explain:probe:escapes": "bun run scripts/probes/explain-escape-sweep.ts",
+		"explain:probe:highlight-recapture": "bun run scripts/probes/explain-highlight-recapture.ts",
+		"explain:probe:operators": "bun run scripts/probes/explain-operator-sweep.ts",
+		"explain:probe:symbol-anchors": "bun run scripts/probes/explain-symbol-anchors.ts",
+		"explain:probe:symbol-arms-score": "bun run scripts/probes/explain-symbol-arms-score.ts",
+		"explain:probe:symbol-bad-sigil-replay": "bun run scripts/probes/explain-symbol-bad-sigil-replay.ts",
+		"explain:probe:symbol-classes-replay": "bun run scripts/probes/explain-symbol-classes-replay.ts",
+		"explain:probe:version-floors": "bun run scripts/probes/explain-version-floors.ts",
+		"explain:menus:check": "bun run scripts/gen-explain-menus.ts --check",
+		"explain:value-census": "bun run scripts/explain-value-census.ts",
+		"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",
+		"explain:token-census:readme:check": "bun run scripts/explain-token-census.ts --readme --check",
 		"security": "bun run lint:secretlint && bun run lint:markdownlint"
 	},
 	"type": "module",

package/src/api-fanout.ts

@@ -7,7 +7,7 @@
  * `ApiEnvelope`s into the locked `FanoutData` shape (`src/core/envelope.ts`).
  *
  * Boundaries (see `commands/api/README.md`, `docs/CONSTITUTION.md`):
- *   - The CDB is loaded ONCE (`expandCdbSelection`); a cdb member is resolved
+ *   - The CDB is loaded ONCE (`expandSelection`); a cdb member is resolved
  *     with its pre-resolved record, so `resolveCdb`'s `__default__` synthetic
  *     fallback never collides ad-hoc literals.
  *   - A `--default` / `__default__` member is guarded from being dialed as the
@@ -39,6 +39,7 @@ import type {
 	CentrsSuccessEnvelope,
 	FanoutData,
 	FanoutSummary,
+	ValidationTrace,
 } from "./core/envelope.ts";
 import {
 	buildFanoutEnvelope,
@@ -49,19 +50,19 @@ 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";
 import {
-	type CdbSelectionExpansion,
-	type CdbSelectionMember,
-	type CdbSelectionResolveInput,
-	expandCdbSelection,
+	expandSelection,
 	isDefaultRecordTarget,
 	loadEnvFileDefaults,
+	type SelectionExpansion,
+	type SelectionMember,
+	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 {
@@ -70,6 +71,8 @@ export interface ApiSelectionSummary {
 	all: boolean;
 	default: boolean;
 	positionals: readonly string[];
+	/** quickchr machine names (`--quickchr`, repeatable; exclusive of the rest). */
+	quickchr?: readonly string[];
 }
 
 export interface ApiFanoutOperationMeta {
@@ -92,10 +95,10 @@ export type ApiFanoutErrorEnvelope =
 export interface ApiFanoutInternals {
 	expand?: (
 		selection: TargetSelection,
-		input: CdbSelectionResolveInput,
+		input: SelectionResolveInput,
 		env: Record<string, string | undefined>,
 		config?: Record<string, string | undefined>,
-	) => Promise<CdbSelectionExpansion>;
+	) => Promise<SelectionExpansion>;
 	execute?: (resolved: ResolvedApiRequest) => Promise<ApiSuccessEnvelope>;
 	sleep?: (ms: number) => Promise<void>;
 }
@@ -113,6 +116,7 @@ function summarizeSelection(selection: TargetSelection): ApiSelectionSummary {
 		all: selection.all,
 		default: selection.default,
 		positionals: selection.positionals,
+		quickchr: selection.quickchr,
 	};
 }
 
@@ -120,7 +124,7 @@ function summarizeSelection(selection: TargetSelection): ApiSelectionSummary {
 function fanoutVia(
 	request: ApiRequest,
 	env: Record<string, string | undefined>,
-	expansion: CdbSelectionExpansion,
+	expansion: SelectionExpansion,
 ): RouterOsProtocol {
 	// Deliberately CLI/env only, not `config` — see the note above this
 	// function's caller.
@@ -139,7 +143,7 @@ function fanoutVia(
 	return anyNative ? "native-api" : "rest-api";
 }
 
-function memberTargetMeta(member: CdbSelectionMember): {
+function memberTargetMeta(member: SelectionMember): {
 	input?: string;
 	identity?: string;
 	recordIndex?: number;
@@ -151,6 +155,9 @@ function memberTargetMeta(member: CdbSelectionMember): {
 			recordIndex: member.recordIndex,
 		};
 	}
+	if (member.kind === "quickchr") {
+		return { input: member.name, identity: member.name };
+	}
 	return { input: member.input };
 }
 
@@ -163,7 +170,7 @@ function memberTargetMeta(member: CdbSelectionMember): {
  */
 function relabelAdhocMember(
 	envelope: ApiEnvelope,
-	member: CdbSelectionMember,
+	member: SelectionMember,
 ): ApiEnvelope {
 	if (member.kind !== "literal") {
 		return envelope;
@@ -209,7 +216,7 @@ export async function apiFanout(
 		assertApiProtocolSupported(pinnedVia);
 	}
 
-	const expand = internals.expand ?? expandCdbSelection;
+	const expand = internals.expand ?? expandSelection;
 	const expansion = await expand(
 		selection,
 		{
@@ -240,10 +247,15 @@ 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<
-		CdbSelectionMember,
+		SelectionMember,
 		ResolvedApiRequest,
 		ApiEnvelope
 	>({
@@ -267,6 +279,15 @@ export async function apiFanout(
 					{ cdbResolution: member.resolution, config },
 				);
 			}
+			if (member.kind === "quickchr") {
+				// The live descriptor resolves here, per member — a stopped/unknown
+				// machine is an inner per-target failure, not an expansion error.
+				return resolveApiRequest(
+					{ ...request, targetInput: undefined, quickchr: member.name },
+					env,
+					{ config },
+				);
+			}
 			return resolveApiRequest({ ...request, targetInput: member.input }, env, {
 				config,
 			});
@@ -277,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,
@@ -302,7 +330,7 @@ async function assertFanoutWriteConfirmed(
 	request: ApiRequest,
 	summary: ApiRequestSummary,
 	method: string,
-	expansion: CdbSelectionExpansion,
+	expansion: SelectionExpansion,
 ): Promise<void> {
 	if (!summary.write || request.yes) {
 		return;
@@ -329,7 +357,7 @@ async function assertFanoutWriteConfirmed(
 interface ApiFanoutSuccessInput {
 	summary: FanoutSummary;
 	targets: readonly ApiEnvelope[];
-	warnings: CdbSelectionExpansion["warnings"];
+	warnings: SelectionExpansion["warnings"];
 	via: RouterOsProtocol | null;
 	concurrency: number;
 	requestSummary: ApiRequestSummary;