@tikoci/centrs 0.1.6 → 0.1.8-next.0

package/src/btest.ts

@@ -16,7 +16,13 @@
 
 import { createServer } from "node:net";
 import type { CentrsEnvelope, EnvelopeMeta } from "./core/envelope.ts";
-import { asCentrsError, CentrsError, serializeCentrsError } from "./errors.ts";
+import {
+	asCentrsError,
+	CentrsError,
+	formatCentrsErrorText,
+	serializeCentrsError,
+	terminalSafeLine,
+} from "./errors.ts";
 import {
 	BTEST_PORT,
 	BTEST_UDP_PORT_START,
@@ -868,7 +874,11 @@ function renderClientCsv(envelope: BtestClientEnvelope): string {
 	if (envelope.ok)
 		for (const r of envelope.data.reports) lines.push(btestClientCsvRow(r));
 	else
-		lines.push(`# error: [${envelope.error.code}] ${envelope.error.summary}`);
+		lines.push(
+			terminalSafeLine(
+				`# error: [${envelope.error.code}] ${envelope.error.summary}`,
+			),
+		);
 	return lines.join("\n");
 }
 
@@ -877,7 +887,11 @@ function renderServerCsv(envelope: BtestServerEnvelope): string {
 	if (envelope.ok)
 		for (const s of envelope.data.sessions) lines.push(btestServerCsvRow(s));
 	else
-		lines.push(`# error: [${envelope.error.code}] ${envelope.error.summary}`);
+		lines.push(
+			terminalSafeLine(
+				`# error: [${envelope.error.code}] ${envelope.error.summary}`,
+			),
+		);
 	return lines.join("\n");
 }
 
@@ -902,14 +916,14 @@ export function btestServerSummaryLine(d: BtestServerData): string {
 }
 
 function renderClientText(envelope: BtestClientEnvelope): string {
-	if (!envelope.ok) return formatErrorText(envelope.error);
+	if (!envelope.ok) return formatCentrsErrorText(envelope.error);
 	const lines = envelope.data.reports.map(formatBtestReportText);
 	lines.push(btestClientSummaryLine(envelope.data));
 	return lines.join("\n");
 }
 
 function renderServerText(envelope: BtestServerEnvelope): string {
-	if (!envelope.ok) return formatErrorText(envelope.error);
+	if (!envelope.ok) return formatCentrsErrorText(envelope.error);
 	const lines = [btestServerSummaryLine(envelope.data)];
 	for (const s of envelope.data.sessions) lines.push(formatBtestSessionText(s));
 	for (const w of envelope.warnings)
@@ -917,18 +931,6 @@ function renderServerText(envelope: BtestServerEnvelope): string {
 	return lines.join("\n");
 }
 
-function formatErrorText(error: {
-	code: string;
-	summary: string;
-	remediation?: string;
-	detailsUrl?: string;
-}): string {
-	const lines = [`[${error.code}] ${error.summary}`];
-	if (error.remediation) lines.push(`Fix: ${error.remediation}`);
-	if (error.detailsUrl) lines.push(`Details: ${error.detailsUrl}`);
-	return lines.join("\n");
-}
-
 // Compact YAML renderer (per-command, matching the discover surface).
 function renderYaml(value: unknown, indent = ""): string {
 	if (value === null || value === undefined) return `${indent}null`;

package/src/cli/api.ts

@@ -2,10 +2,11 @@ import {
 	type ApiOutputFormat,
 	type ApiRequest,
 	apiEnvelope,
-	apiListen,
 	apiOutputFormats,
+	apiStream,
 	buildApiErrorEnvelope,
 	normalizeApiEndpoint,
+	removedListenError,
 	renderApiEnvelope,
 	renderApiStreamLine,
 } from "../api.ts";
@@ -48,7 +49,8 @@ import {
 
 export const apiCommand: CliCommandMetadata = {
 	name: "api",
-	usage: "centrs api <router> <endpoint> [flags]",
+	usage:
+		"centrs api <router> <endpoint> [flags] | centrs api --host <host|url> <endpoint> [flags]",
 	summary:
 		"Structured RouterOS API passthrough (gh-api style) over REST or native API.",
 	options: [
@@ -78,13 +80,13 @@ export const apiCommand: CliCommandMetadata = {
 			flag: "--query / --filter",
 			valueName: "<expr>",
 			description:
-				"RouterOS-side row filter, AND-combined, repeatable: name=value, name!=value, name>value, name<value, name.",
+				"Row filter written as after `print where` (`disabled`, `mtu>=1500 and !dynamic`), sent as query words; repeatable, AND-ed. No `~` or `in`.",
 		},
 		{
 			flag: "--raw-query",
 			valueName: "<word>",
 			description:
-				"Verbatim RouterOS query word (repeatable) for OR / absence / stack expressions.",
+				"Verbatim RouterOS query word (repeatable), e.g. has-property `name`, absence `-name`, or stack ops `#|` `#&` `#!`.",
 		},
 		{
 			flag: "--attribute / --proplist",
@@ -102,14 +104,15 @@ export const apiCommand: CliCommandMetadata = {
 				"Confirm a mutating (non-read) request in non-interactive runs.",
 		},
 		{
-			flag: "--stream / --listen",
+			flag: "--stream",
 			description:
-				"Follow changes as an NDJSON envelope stream (native-api only; the `/listen` endpoint infers it). Ends with a summary envelope.",
+				"Stream the command's native replies (`!re` rows and `!empty`) as NDJSON, then a summary envelope. Never changes the command: a GET streams one print. To follow changes, request `<menu>/listen`, which implies it.",
 		},
 		{
 			flag: "--count",
 			valueName: "<n>",
-			description: "Stop a `--stream` after N change frames.",
+			description:
+				"Stop a `--stream` after N `!re` rows; `!empty` replies do not count (not the device count= argument).",
 		},
 		{
 			flag: "--duration",
@@ -126,7 +129,8 @@ export const apiCommand: CliCommandMetadata = {
 		{
 			flag: "--host",
 			valueName: "<host|url>",
-			description: "Override the resolved host or base URL for the target.",
+			description:
+				"Host or base URL to dial. With no <router> it is the target (no CDB lookup); with one it overrides the resolved host.",
 		},
 		{
 			flag: "--port",
@@ -176,7 +180,7 @@ export const apiCommand: CliCommandMetadata = {
 		},
 		{
 			flag: "--format",
-			valueName: "<json|yaml|text>",
+			valueName: "<json|ndjson|yaml|text>",
 			description:
 				"Output format. Defaults to json for api; `CENTRS_FORMAT` overrides.",
 		},
@@ -205,7 +209,9 @@ interface ApiCliArgs extends ApiRequest {
 export function parseApiCliArgs(args: readonly string[]): ApiCliArgs {
 	const parsed: ApiCliArgs = { endpoint: "" };
 	const positional: string[] = [];
+	const positionalIndexes: number[] = [];
 	const selectionFlags = emptySelectionFlags();
+	let listenFlag = false;
 
 	for (let index = 0; index < args.length; index += 1) {
 		const arg = args[index];
@@ -234,8 +240,10 @@ export function parseApiCliArgs(args: readonly string[]): ApiCliArgs {
 				parsed.raw = true;
 				break;
 			case "--stream":
+				parsed.stream = true;
+				break;
 			case "--listen":
-				parsed.listen = true;
+				listenFlag = true;
 				break;
 			case "--validate":
 				parsed.validate = true;
@@ -345,10 +353,18 @@ export function parseApiCliArgs(args: readonly string[]): ApiCliArgs {
 					throw unknownFlagError("api", arg, apiCommand.options);
 				}
 				positional.push(arg);
+				positionalIndexes.push(index);
 				break;
 			}
 		}
 	}
+	if (listenFlag) {
+		throw removedListenError(
+			positional.at(-1) ?? "",
+			"cli",
+			listenReplacement(args, positionalIndexes.at(-1), parsed.method),
+		);
+	}
 
 	// api/retrieve positional boundary: the FINAL positional is the endpoint; every
 	// preceding positional is a fan-out target.
@@ -360,6 +376,79 @@ export function parseApiCliArgs(args: readonly string[]): ApiCliArgs {
 	return parsed;
 }
 
+/**
+ * The exact command `--listen` meant (#402): a GET becomes the menu's
+ * `/listen` endpoint, anything else keeps its command and streams. Secrets in
+ * the original arguments are not echoed back. Any value can carry one (a
+ * `-f script=` body holds whole commands), so every request value is a
+ * placeholder: `-f`/query values keep their key and operator, a `-d` body and
+ * passwords are replaced whole. Flag names, the method and the endpoint stay.
+ */
+function listenReplacement(
+	args: readonly string[],
+	endpointIndex: number | undefined,
+	method: string | undefined,
+): string {
+	const get = (method ?? "GET").toUpperCase() === "GET";
+	const words: string[] = [];
+	for (let index = 0; index < args.length; index += 1) {
+		const arg = args[index] as string;
+		if (arg === "--listen") {
+			if (!get) words.push("--stream");
+			continue;
+		}
+		if (index === endpointIndex && get && !normalizeApiEndpoint(arg).listen) {
+			words.push(shellWord(`${arg.replace(/\/+$/, "")}/listen`));
+			continue;
+		}
+		words.push(shellWord(arg));
+		const value = args[index + 1];
+		const placeholder =
+			value === undefined ? undefined : redactedValue(arg, value);
+		if (placeholder !== undefined) {
+			words.push(placeholder);
+			index += 1;
+		}
+	}
+	return `centrs api ${words.join(" ")}`;
+}
+
+/**
+ * The placeholder that stands in for a request value, or `undefined` for a
+ * flag whose value is echoed (method, transport, bounds, names). Placeholders
+ * are left unquoted, like `<router>`.
+ */
+function redactedValue(flag: string, value: string): string | undefined {
+	switch (flag) {
+		case "--password":
+		case "--cdb-password":
+			return "<password>";
+		case "-d":
+		case "--data":
+			return "<json>";
+		case "-f":
+		case "--field":
+		case "--query":
+		case "--filter":
+		case "--raw-query": {
+			// Keep `key` plus its operator (`=`, `!=`, `<`, `>`); a bare word
+			// such as `#|` or `name` carries no value and is echoed.
+			let at = 0;
+			while (at < value.length && !"=<>".includes(value.charAt(at))) at += 1;
+			if (at === value.length) return shellWord(value);
+			return `${shellWord(value.slice(0, at + 1))}<value>`;
+		}
+		default:
+			return undefined;
+	}
+}
+
+function shellWord(word: string): string {
+	return /^[\w@%+=:,./*-]+$/.test(word)
+		? word
+		: `'${word.replaceAll("'", "'\\''")}'`;
+}
+
 export async function runApiCli(args: readonly string[]): Promise<number> {
 	let parsed: ApiCliArgs | undefined;
 	try {
@@ -404,7 +493,7 @@ export async function runApiCli(args: readonly string[]): Promise<number> {
 
 		// Fan-out mode (selector flag present, or >1 positional target) has its own
 		// envelope shape, guards, and granular exit code. It runs first and rejects
-		// `--stream`/`--listen` + fan-out itself (single-session is exclusive).
+		// `--stream` + fan-out itself (single-session is exclusive).
 		if (isFanoutMode(selectionFlags, targetPositionals.length)) {
 			return await runApiFanoutCli(
 				parsed,
@@ -419,22 +508,28 @@ export async function runApiCli(args: readonly string[]): Promise<number> {
 			parsed.quickchr = selectionFlags.quickchr[0];
 		}
 
-		// Open-ended follow (`--stream`/`--listen`, or a `/listen` endpoint) consumes
+		// A stream (`--stream`, or a `/listen` endpoint) consumes
 		// the NDJSON envelope stream instead of a single one-shot envelope.
 		const streaming =
-			parsed.listen === true ||
+			parsed.stream === true ||
 			(parsed.endpoint.length > 0 &&
 				normalizeApiEndpoint(parsed.endpoint).listen);
 		if (streaming) {
-			return await runApiListenCli(parsed, args);
+			return await runApiStreamCli(parsed, args);
 		}
 
-		if (!parsed.targetInput && parsed.quickchr === undefined) {
+		// The `--host` flag stands in for a missing `<router>` (#428), with no CDB
+		// lookup; `CENTRS_HOST` never counts.
+		if (
+			!parsed.targetInput &&
+			parsed.quickchr === undefined &&
+			parsed.host === undefined
+		) {
 			throw missingTargetError({
 				command: "api",
 				summary: "`centrs api` requires a <router> and an <endpoint>.",
 				remediation:
-					"Pass the router host/identity then the endpoint, e.g. `centrs api 192.0.2.10 ip/address`.",
+					"Pass the router host/identity then the endpoint, e.g. `centrs api 192.0.2.10 ip/address`, or name the host with `--host <host|url>`.",
 			});
 		}
 
@@ -477,7 +572,7 @@ export async function runApiCli(args: readonly string[]): Promise<number> {
 					verbose: parsed.verbose ?? false,
 				}),
 			);
-		} else if (format === "json" || format === "yaml") {
+		} else if (format !== "text") {
 			const envelope = withTips(
 				buildApiErrorEnvelope(parsed ?? { endpoint: "" }, error),
 				tips,
@@ -526,14 +621,14 @@ async function runApiFanoutCli(
 				context: { flags: ["--raw", "fanout"] },
 			});
 		}
-		// `--listen`/`--stream` is single-session.
+		// `--stream` is single-session.
 		const listenRequested =
-			(parsed.listen ?? false) || endpointInfersListen(parsed.endpoint);
+			(parsed.stream ?? false) || endpointInfersListen(parsed.endpoint);
 		if (listenRequested) {
 			throw new CentrsError({
 				code: "usage/fanout-not-supported",
 				summary:
-					"`api --stream`/`--listen` is single-session and cannot fan out across multiple targets.",
+					"`api --stream` is single-session and cannot fan out across multiple targets.",
 				remediation:
 					"Follow a stream against a single router (no `--group`/`--where`/`--all`/`--default`/multiple positionals).",
 				context: { capability: "listen" },
@@ -573,7 +668,7 @@ async function runApiFanoutCli(
 	}
 }
 
-/** Whether an endpoint's trailing segment infers `--listen` (without throwing). */
+/** Whether an endpoint's trailing `listen` segment implies `--stream` (without throwing). */
 function endpointInfersListen(endpoint: string): boolean {
 	try {
 		return normalizeApiEndpoint(endpoint).listen;
@@ -583,13 +678,11 @@ function endpointInfersListen(endpoint: string): boolean {
 }
 
 /**
- * Consume the open-ended `--stream` follow: print one line per change frame
- * (NDJSON under `json`, human rows under `text`), then the terminating summary.
- * Ctrl-C (SIGINT) cancels the listen and still emits the summary. The exit code
- * reflects whether the stream *started* cleanly — a failure before the first
- * frame is `1`; a mid-stream error frame leaves a started stream at `0`.
+ * Emit all structured stream outcomes on stdout. Any failure sets exit 1,
+ * including a terminal error after successful rows. Raw mode retains its
+ * stderr error contract; Ctrl-C requests bounded cancellation.
  */
-async function runApiListenCli(
+async function runApiStreamCli(
 	parsed: ApiCliArgs,
 	args: readonly string[],
 ): Promise<number> {
@@ -598,26 +691,25 @@ async function runApiListenCli(
 	const onSigint = (): void => controller.abort();
 	process.on("SIGINT", onSigint);
 	let exitCode = 0;
-	let first = true;
 	try {
-		for await (const envelope of apiListen(
+		for await (const envelope of apiStream(
 			parsed,
 			Bun.env,
 			controller.signal,
 		)) {
+			// `--raw` is bare payloads only; a notice has none.
+			if (parsed.raw && envelope.meta.operation?.stream?.kind === "notice")
+				continue;
 			const line = renderApiStreamLine(envelope, format, {
 				raw: parsed.raw,
 				verbose: parsed.verbose,
 			});
-			if (envelope.ok) {
+			if (envelope.ok || !parsed.raw) {
 				console.log(line);
 			} else {
 				console.error(line);
-				if (first) {
-					exitCode = 1;
-				}
 			}
-			first = false;
+			if (!envelope.ok) exitCode = 1;
 		}
 	} finally {
 		process.off("SIGINT", onSigint);

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/cli/execute.ts

@@ -43,7 +43,7 @@ import {
 export const executeCommand: CliCommandMetadata = {
 	name: "execute",
 	usage:
-		"centrs execute <target> <command> [flags] | centrs execute <target...> -- <command> [flags] | centrs execute --group <name> <command> [flags]",
+		"centrs execute <target> <command> [flags] | centrs execute <target...> -- <command> [flags] | centrs execute --host <host|url> [--] <command> [flags] | centrs execute --group <name> <command> [flags]",
 	summary:
 		"Run a RouterOS read or write command via native API, REST, or mac-telnet.",
 	options: [
@@ -57,7 +57,8 @@ export const executeCommand: CliCommandMetadata = {
 		{
 			flag: "--host",
 			valueName: "<host|url>",
-			description: "Override the resolved host or base URL for the target.",
+			description:
+				"Host or base URL to dial. With no <target> it is the target (no CDB lookup); with one it overrides the resolved host.",
 		},
 		{
 			flag: "--port",
@@ -270,6 +271,10 @@ export function parseExecuteCliArgs(args: readonly string[]): ExecuteCliArgs {
 	//   - `--` present: targets are the positionals BEFORE it, command is AFTER it.
 	//   - selector flag (or `--quickchr`) present, no `--`: every positional is the
 	//     command (targets come from the flag).
+	//   - `--host` flag with a lone positional, no `--`: that positional is the
+	//     command and `--host` stands in for `<router>` (#428). Two or more keep
+	//     the legacy split, so `execute <mac> <cmd> --host <udp-endpoint>` (the
+	//     mac-telnet delivery override) still parses. `CENTRS_HOST` never counts.
 	//   - otherwise (no `--`, no selector): legacy single-target split — first
 	//     positional is the target, the rest is the command. Multiple positional
 	//     targets therefore REQUIRE `--`.
@@ -280,6 +285,9 @@ export function parseExecuteCliArgs(args: readonly string[]): ExecuteCliArgs {
 	} else if (hasSelector) {
 		parsed.targetPositionals = [];
 		parsed.command = positional.join(" ");
+	} else if (parsed.host !== undefined && positional.length === 1) {
+		parsed.targetPositionals = [];
+		parsed.command = positional[0] ?? "";
 	} else {
 		parsed.targetPositionals =
 			positional[0] !== undefined ? [positional[0]] : [];
@@ -331,13 +339,18 @@ export async function runExecuteCli(args: readonly string[]): Promise<number> {
 		// No positional at all: lead with the missing-target guidance (CDB picker /
 		// discover) rather than the missing-command error — there is nothing to run
 		// without a device. A lone positional is treated as the target, so the
-		// "requires a command" path still fires for `execute <target>`.
-		if (!parsed.targetInput && parsed.quickchr === undefined) {
+		// "requires a command" path still fires for `execute <target>`. The
+		// `--host` flag is a target of its own, with no CDB lookup.
+		if (
+			!parsed.targetInput &&
+			parsed.quickchr === undefined &&
+			parsed.host === undefined
+		) {
 			throw missingTargetError({
 				command: "execute",
 				summary: "`centrs execute` requires a <target> and a RouterOS command.",
 				remediation:
-					'Pass the router host/identity then the command, e.g. `centrs execute 192.0.2.10 "/system/resource/print"`.',
+					'Pass the router host/identity then the command, e.g. `centrs execute 192.0.2.10 "/system/resource/print"`, or name the host with `--host <host|url>`.',
 			});
 		}