@tikoci/centrs 0.1.6 → 0.1.7

package/docs/CONSTITUTION.md

@@ -84,8 +84,10 @@ validator, with CHR evidence.
   `expected`. Rejection forms are `(evl bad parameter <name> (line N column M)
   /path)`, `(<%% bad command name <name> (line N column M) …)`, and the
   line-anchored `expected … (line N column M)` (spellings: `expected end of
-  command`, `expected command name`, `expected input value`) / `syntax error
-  (line N column M)`. That text rides the **HTTP-200 `ret` value** (REST,
+  command`, `expected command name`, `expected input value`), `missing … (line
+  N column M)` (`missing closing brace`, `missing value for where`; GH#375) and
+  `syntax error (line N column M)`. Every bare form is anchored at a line start
+  with the position suffix, because an accepted return can echo those words. That text rides the **HTTP-200 `ret` value** (REST,
   `as-string`), the native `as-string` `ret`, and the console's printed output
   alike — so a single `:put [:parse ...]` covers both the syntax and the
   **unknown-attribute** gate on every transport. centrs sends `as-string` and now
@@ -535,8 +537,10 @@ as bibliography entries in `GLOSSARY.txt` — e.g. `netmiko`,
 ### Canonicalizer ownership
 
 centrs owns the **script-vs-structured execution gate** — the load-bearing
-discriminator for which validation runs and whether the write-confirmation prompt
-fires; widening what counts as `structured` is a product regression. The shared,
+discriminator for validation and transport shape; widening what counts as
+`structured` is a product regression. Write confirmation is a separate,
+fail-closed safety predicate over the original CLI string: falling back to raw
+script transport must never turn a write into a read. The shared,
 pure command canonicalizer that `rosetta` / `lsp-routeros-ts` publish is for
 canonicalization only, never the structured-mode predicate. The gate contract,
 its pinning test, and the parser-vendoring preconditions are documented in
@@ -546,5 +550,6 @@ its pinning test, and the parser-vendoring preconditions are documented in
 Richer schema-free analysis must distinguish **ambiguous** (multiple plausible
 readings) from **unknown** (no safe reading) and abstain in both cases rather than
 inventing a command, path, symbol class, or transport mapping. These explain-only
-verdicts never widen or reinterpret the execution gate's `mode` or `writeShaped`
-decision.
+verdicts never widen or reinterpret the execution gate's `mode`. The execution
+safety predicate remains deliberately conservative and independent of richer
+explain-only inference.

package/docs/errors/cdb/create-failed.md

@@ -0,0 +1,20 @@
+# `cdb/create-failed`
+
+A new CDB file could not be created at the resolved location.
+
+`centrs devices init` creates an empty CDB at the path from `--cdb-file`,
+`CENTRS_CDB_FILE`, or the default `~/.config/tikoci/winbox.cdb`, making any
+missing parent directories. This error means the filesystem refused: typically
+a directory on the path is not writable by the current user, or a path
+component is a file rather than a directory. The underlying filesystem error
+(for example `EACCES`) is preserved as the error's `cause`; run
+with `--json` to see it.
+
+Nothing is written when this fails.
+
+## Fix
+
+- Check the permissions of the directories on the path shown in the error.
+- Or choose a writable location:
+  `centrs devices init --cdb-file PATH`, then pass the same `--cdb-file PATH`
+  (or set `CENTRS_CDB_FILE`) on later commands.

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/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@tikoci/centrs",
-	"version": "0.1.6",
+	"version": "0.1.7",
 	"main": "src/index.ts",
 	"module": "src/index.ts",
 	"repository": {

package/src/api.ts

@@ -3,9 +3,10 @@
  *
  * The structured middle of the verb trichotomy (see `commands/api/README.md`):
  * one command per operation (no code blocks), structured input **and** output,
- * validated through `/console/inspect`, runnable over REST or the native API. The
+ * validated through `/console/inspect` (or live `:parse` for `/execute` scripts),
+ * runnable over REST or the native API. The
  * orchestrator is transport-agnostic — it normalizes the endpoint, resolves the
- * method→verb map, runs the inspect gate and the write-confirmation gate, then
+ * method→verb map, runs the validation and write-confirmation gates, then
  * hands a normalized {@link ProtocolApiRequest} to the adapter. REST vs native
  * mechanics (id-in-URL vs `=.id=`, `.query` vs `?`-words) live in the adapter.
  *
@@ -33,9 +34,13 @@ import {
 	isCommandNode,
 	pathTokens,
 } from "./core/inspect.ts";
+import { mapRouterOsResultError } from "./core/routeros-errors.ts";
 import { toYaml } from "./core/yaml.ts";
 import { CentrsError, serializeCentrsError } from "./errors.ts";
-import { promptForWriteConfirmation } from "./execute.ts";
+import {
+	promptForWriteConfirmation,
+	validateRouterOsScript,
+} from "./execute.ts";
 import {
 	assertOfflineSyntax,
 	isOfflineGateRejection,
@@ -46,6 +51,7 @@ import {
 	createProtocolAdapter,
 	type ProtocolAdapter,
 	type ProtocolApiRequest,
+	type ProtocolApiResult,
 	plannedProtocols,
 	type RouterOsProtocol,
 } from "./protocols/index.ts";
@@ -293,6 +299,11 @@ export async function runResolvedApi(
 	trace: ValidationTrace = {},
 ): Promise<ApiSuccessEnvelope> {
 	assertListenCapability(resolved);
+	// Validate the complete request shape before constructing a backend or
+	// running either validation stage. In particular, `/execute` must reject
+	// extra body fields deterministically instead of letting live `:parse`
+	// surface an unrelated transport or authentication failure first.
+	const protocolRequest = buildProtocolApiRequest(resolved);
 	const backend = createProtocolAdapter({
 		protocol: resolved.via.value,
 		host: resolved.target.host,
@@ -320,7 +331,11 @@ export async function runResolvedApi(
 		// reports the gate that actually settled rather than a guess.
 		trace.validation = validation;
 
-		const result = await backend.apiRequest(buildProtocolApiRequest(resolved));
+		const result = await backend.apiRequest(protocolRequest);
+		const routerOsFailure = apiRouterOsFailureFromResult(resolved, result);
+		if (routerOsFailure) {
+			throw routerOsFailure;
+		}
 		return {
 			ok: true,
 			data: result.data,
@@ -333,6 +348,35 @@ export async function runResolvedApi(
 	}
 }
 
+/**
+ * A `/execute` run that RouterOS *transported* successfully but *rejected* at
+ * runtime.
+ *
+ * `as-string` makes the console's own text the reply body, so a rejected
+ * script comes back as an ordinary 200/`!done` carrying `no such item`. Both
+ * adapters surface that text as `data`, so without this the caller-addressed
+ * `/execute` would report a failure as `ok: true` — exactly the shape
+ * `execute` normalizes in `routerOsFailureFromResult`. Structured path
+ * requests are untouched: their faults already arrive as HTTP >=400 or a
+ * `!trap`, and their `data` is a record, not console text.
+ */
+function apiRouterOsFailureFromResult(
+	resolved: ResolvedApiRequest,
+	result: ProtocolApiResult,
+): CentrsError | undefined {
+	if (!resolved.scriptMode || typeof result.data !== "string") {
+		return undefined;
+	}
+	const via = resolved.via.value;
+	return mapRouterOsResultError(result.data, {
+		transport:
+			via === "rest-api" || via === "mac-telnet" || via === "ssh"
+				? via
+				: "native-api",
+		context: { via },
+	});
+}
+
 /**
  * The open-ended `--stream` follow path: an async generator yielding one
  * {@link ApiEnvelope} per `/listen` change frame, then a terminating summary
@@ -399,14 +443,18 @@ async function* streamResolvedApi(
 	const startedAt = Date.now();
 	let frames = 0;
 	let stopReason: ApiStreamStopReason | undefined;
+	let cancelUnacknowledged = false;
 	let durationTimer: ReturnType<typeof setTimeout> | undefined;
+	// The first stop cause wins: the cancel grace window keeps the loop alive
+	// after a stop, so a later timer or frame must not relabel it.
 	const onExternalAbort = (): void => {
 		stopReason ??= "interrupted";
+		clearTimeout(durationTimer);
 		controller.abort();
 	};
 	if (resolved.durationMs !== undefined) {
 		durationTimer = setTimeout(() => {
-			stopReason = "duration-elapsed";
+			stopReason ??= "duration-elapsed";
 			controller.abort();
 		}, resolved.durationMs);
 	}
@@ -423,11 +471,14 @@ async function* streamResolvedApi(
 		for await (const record of backend.listen(protocolRequest, {
 			signal: controller.signal,
 			onListening,
+			onCancelUnacknowledged: () => {
+				cancelUnacknowledged = true;
+			},
 		})) {
 			frames += 1;
 			yield streamFrameEnvelope(resolved, validation, record, frames);
 			if (resolved.count !== undefined && frames >= resolved.count) {
-				stopReason = "count-reached";
+				stopReason ??= "count-reached";
 				break;
 			}
 		}
@@ -437,6 +488,15 @@ async function* streamResolvedApi(
 			stopReason ?? "interrupted",
 			frames,
 			Date.now() - startedAt,
+			cancelUnacknowledged
+				? [
+						{
+							code: "transport/cancel-unacknowledged",
+							message: `RouterOS did not acknowledge /cancel within ${resolved.timeoutMs.value}ms; centrs closed the session locally.`,
+							context: { timeoutMs: resolved.timeoutMs.value },
+						},
+					]
+				: [],
 		);
 	} catch (error) {
 		// A mid-stream failure is itself a frame, tagged `stream.kind="frame"` so
@@ -496,6 +556,7 @@ function streamSummaryEnvelope(
 	stopReason: ApiStreamStopReason,
 	frames: number,
 	durationMs: number,
+	streamWarnings: readonly Warning[] = [],
 ): ApiSuccessEnvelope {
 	const summary: ApiStreamSummary = { stopReason, frames, durationMs };
 	const meta = metaFromResolved(resolved, validation, summary);
@@ -504,7 +565,7 @@ function streamSummaryEnvelope(
 	return {
 		ok: true,
 		data: summary,
-		warnings: [...resolved.warnings],
+		warnings: [...resolved.warnings, ...streamWarnings],
 		tips: [],
 		meta,
 	};
@@ -955,8 +1016,9 @@ export function buildProtocolApiRequest(
 	return request;
 }
 
-/** The api device-stage validator: structured input is inspected, never `:parse`d. */
+/** The api device-stage validator for structured path input. */
 const API_DEVICE_STAGE_SOURCE = "/console/inspect request=child";
+const API_SCRIPT_DEVICE_STAGE_SOURCE = ":put [:parse]";
 
 interface ApiValidationResult {
 	validation: EnvelopeValidationMeta;
@@ -976,11 +1038,9 @@ async function validateApiRequest(
 	trace: ValidationTrace = {},
 ): Promise<ApiValidationResult> {
 	if (resolved.scriptMode) {
-		// `/execute` carries a CLI string, so `/console/inspect` has nothing to
-		// inspect — which until GH#354 meant the script was sent with NO gate at
-		// all (`syntax: false`, `semantic: "not-applicable"`, `result: "passed"`).
-		// The offline analyzer is the whole gate here: a syntax fault is now a
-		// byte span and no round trip, where before it reached the device.
+		// `/execute` carries a CLI string, so use the same offline -> live `:parse`
+		// pipeline as `execute`. `/console/inspect` remains inapplicable because
+		// there is no structured menu path/body to inspect.
 		const script = scriptOf(resolved);
 		const offline = script
 			? assertOfflineSyntax(script, {
@@ -989,6 +1049,9 @@ async function validateApiRequest(
 				})
 			: undefined;
 		trace.offlineVerdict = offline?.verdict;
+		if (script !== undefined) {
+			await validateRouterOsScript(script, backend, resolved.via.value);
+		}
 		const offlineReason =
 			offline === undefined
 				? "no `script` field to analyze"
@@ -998,9 +1061,12 @@ async function validateApiRequest(
 		return {
 			validation: {
 				enabled: true,
-				source: offline === undefined ? "not-applicable" : OFFLINE_GATE_SOURCE,
+				source:
+					offline === undefined
+						? "not-applicable"
+						: API_SCRIPT_DEVICE_STAGE_SOURCE,
 				result: "passed",
-				syntax: offline !== undefined,
+				syntax: script !== undefined,
 				semantic: "not-applicable",
 				stages: [
 					{
@@ -1011,10 +1077,11 @@ async function validateApiRequest(
 					},
 					{
 						stage: "device",
-						source: "/console/inspect request=child",
-						result: "skipped",
-						reason:
-							"`/execute` is a CLI string, not a menu path; RouterOS re-validates it on the run",
+						source: API_SCRIPT_DEVICE_STAGE_SOURCE,
+						result: script === undefined ? "skipped" : "passed",
+						...(script === undefined
+							? { reason: "no `script` field to parse" }
+							: {}),
 					},
 				],
 			},
@@ -1441,7 +1508,7 @@ function failedApiValidationMeta(
 				{ stage: "offline", source: OFFLINE_GATE_SOURCE, result: "failed" },
 				{
 					stage: "device",
-					source: API_DEVICE_STAGE_SOURCE,
+					source: apiDeviceStageSource(resolved),
 					result: "skipped",
 					reason: "offline analysis rejected the script; no connection opened",
 				},
@@ -1455,12 +1522,17 @@ function failedApiValidationMeta(
 	const deviceRejected = error.code.startsWith("validation/");
 	return {
 		enabled: true,
-		source: "/console/inspect",
+		source: apiDeviceStageSource(resolved),
 		result: "failed",
 		syntax: false,
 		semantic: resolved.scriptMode ? "not-applicable" : false,
 		...(deviceRejected
-			? { stages: [offlineApiStage(resolved, trace), deviceStageFailed()] }
+			? {
+					stages: [
+						offlineApiStage(resolved, trace),
+						deviceStageFailed(resolved),
+					],
+				}
 			: {}),
 	};
 }
@@ -1494,10 +1566,18 @@ function offlineApiStage(
 	};
 }
 
-function deviceStageFailed(): EnvelopeValidationStage {
+function apiDeviceStageSource(resolved: ResolvedApiRequest): string {
+	return resolved.scriptMode
+		? API_SCRIPT_DEVICE_STAGE_SOURCE
+		: API_DEVICE_STAGE_SOURCE;
+}
+
+function deviceStageFailed(
+	resolved: ResolvedApiRequest,
+): EnvelopeValidationStage {
 	return {
 		stage: "device",
-		source: API_DEVICE_STAGE_SOURCE,
+		source: apiDeviceStageSource(resolved),
 		result: "failed",
 	};
 }
@@ -1518,7 +1598,11 @@ function disabledApiValidationMeta(
 		semantic: resolved.scriptMode ? "not-applicable" : false,
 		stages: [
 			{ stage: "offline", source: OFFLINE_GATE_SOURCE, result: "skipped" },
-			{ stage: "device", source: API_DEVICE_STAGE_SOURCE, result: "skipped" },
+			{
+				stage: "device",
+				source: apiDeviceStageSource(resolved),
+				result: "skipped",
+			},
 		],
 	};
 }

package/src/cli/devices.ts

@@ -22,6 +22,7 @@ import {
 	describeCentrs,
 	devicesOutputFormats,
 	editInteractiveOnlyError,
+	initCdb,
 	listDevices,
 	listGroups,
 	loadCdb,
@@ -46,7 +47,8 @@ import {
 
 export const devicesCommand: CliCommandMetadata = {
 	name: "devices",
-	usage: "centrs devices <list|show|groups|add|edit|set|remove> [args] [flags]",
+	usage:
+		"centrs devices <init|list|show|groups|add|edit|set|remove> [args] [flags]",
 	summary:
 		"Inspect and mutate the CDB-backed device registry. `devices` is the only command that writes the CDB.",
 	options: [
@@ -197,6 +199,7 @@ export const devicesCommand: CliCommandMetadata = {
 };
 
 type DevicesSubcommand =
+	| "init"
 	| "list"
 	| "show"
 	| "groups"
@@ -378,6 +381,7 @@ function parseDevicesCliArgs(args: readonly string[]): DevicesCliArgs {
 	}
 
 	const subcommands: readonly DevicesSubcommand[] = [
+		"init",
 		"list",
 		"show",
 		"groups",
@@ -389,14 +393,14 @@ function parseDevicesCliArgs(args: readonly string[]): DevicesCliArgs {
 	const [rawSub, ...rest] = positional;
 	if (rawSub === undefined) {
 		throw new Error(
-			"`centrs devices` requires a subcommand: list, show, groups, add, edit, set, or remove.",
+			"`centrs devices` requires a subcommand: init, list, show, groups, add, edit, set, or remove.",
 		);
 	}
 	// Resolve aliases (print/get/rm/delete) to the canonical verb before validating.
 	const sub = SUBCOMMAND_ALIASES[rawSub] ?? (rawSub as DevicesSubcommand);
 	if (!subcommands.includes(sub)) {
 		throw new Error(
-			`Unknown devices subcommand: ${rawSub}. Use list, show, groups, add, edit, set, or remove (aliases: print, get, rm, delete).`,
+			`Unknown devices subcommand: ${rawSub}. Use init, list, show, groups, add, edit, set, or remove (aliases: print, get, rm, delete).`,
 		);
 	}
 	parsed.subcommand = sub;
@@ -606,6 +610,15 @@ export async function runDevicesCli(args: readonly string[]): Promise<number> {
 		}
 
 		envSnapshot = Bun.env;
+		if (parsed.subcommand === "init") {
+			const envelope = await initCdb({
+				cdbFile: parsed.cdbFile,
+				cdbPassword: parsed.cdbPassword,
+				env: envSnapshot,
+			});
+			console.log(renderDevicesEnvelope(envelope, parsed.format ?? "text"));
+			return 0;
+		}
 		const cdb = await loadCdb({
 			cdbFile: parsed.cdbFile,
 			cdbPassword: parsed.cdbPassword,

package/src/core/error-catalog.ts

@@ -40,6 +40,10 @@ export const errorCatalog: readonly ErrorCatalogEntry[] = [
 		code: "cdb/already-exists",
 		summary: "A CDB entry with that target already exists.",
 	},
+	{
+		code: "cdb/create-failed",
+		summary: "A new CDB file could not be created at the resolved location.",
+	},
 	{
 		code: "cdb/created",
 		summary: "A new CDB file was created at the resolved location.",
@@ -57,6 +61,11 @@ export const errorCatalog: readonly ErrorCatalogEntry[] = [
 		code: "cdb/empty-selection",
 		summary: "The target selection matched no CDB records.",
 	},
+	{
+		code: "cdb/file-exists",
+		summary:
+			"`devices init` found a CDB already at the resolved location and wrote nothing.",
+	},
 	{
 		code: "cdb/invalid-option",
 		summary: "A comment kv-soup option carried an invalid value.",
@@ -430,6 +439,11 @@ export const errorCatalog: readonly ErrorCatalogEntry[] = [
 		summary:
 			"Auto-selection moved the operation to a different method (informational auto-hop).",
 	},
+	{
+		code: "transport/cancel-unacknowledged",
+		summary:
+			"RouterOS did not acknowledge a stream's /cancel within the timeout; centrs ended the stream and closed the session locally.",
+	},
 	{
 		code: "transport/capability-unsupported",
 		summary: "The chosen transport cannot perform this kind of operation.",