@tikoci/centrs 0.1.9-next.27 → 0.1.9

package/docs/errors/input/empty-stdin.md

@@ -0,0 +1,27 @@
+# `input/empty-stdin`
+
+A flag that reads its value from stdin (e.g. `--password-stdin`) received
+nothing.
+
+`centrs devices add`/`set --password-stdin` strips one trailing newline (`\n`
+or `\r\n`) and refuses what is left if it is empty. An empty pipe is usually a
+mistake — an unset variable, a missing file, a command that printed nothing —
+so it is not treated as "clear the password".
+
+## Fix
+
+Pipe a non-empty value:
+
+```bash
+printf '%s' "$ROUTER_PW" | centrs devices set 192.0.2.5 --password-stdin
+centrs devices set 192.0.2.5 --password-stdin < pw.txt
+```
+
+To clear a stored password on purpose, say so with the argv flag:
+
+```bash
+centrs devices set 192.0.2.5 --password ""
+```
+
+See [`commands/devices/README.md`](https://github.com/tikoci/centrs/blob/main/commands/devices/README.md)
+for the record-password channels.

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

@@ -0,0 +1,28 @@
+# `input/invalid-stdin`
+
+A flag that reads its value from stdin (e.g. `--password-stdin`) received
+bytes that are not valid UTF-8 text, or began with a byte-order mark.
+
+`centrs devices add`/`set --password-stdin` strips one trailing newline (`\n`
+or `\r\n`) and decodes the rest as UTF-8. The CDB stores record strings as
+UTF-8 and drops a leading byte-order mark (U+FEFF) when it reads them back, so
+malformed bytes or a BOM would store a credential different from what was
+piped in. centrs refuses instead of guessing. The bytes are never echoed.
+
+## Fix
+
+Pipe the password as plain UTF-8 text:
+
+```bash
+printf '%s' "$ROUTER_PW" | centrs devices set 192.0.2.5 --password-stdin
+```
+
+If the value comes from a file an editor saved with a BOM (common on Windows),
+re-save it as UTF-8 without BOM, or strip the first three bytes:
+
+```bash
+tail -c +4 pw.txt | centrs devices set 192.0.2.5 --password-stdin
+```
+
+See [`commands/devices/README.md`](https://github.com/tikoci/centrs/blob/main/commands/devices/README.md)
+for the record-password channels.

package/docs/errors/usage/stdin-is-tty.md

@@ -0,0 +1,21 @@
+# `usage/stdin-is-tty`
+
+A flag that reads its value from stdin (e.g. `--password-stdin`) was given
+while stdin is a terminal.
+
+`--password-stdin` exists for automation: the value arrives on fd 0 so it never
+appears in argv or `ps`. centrs does not prompt for it at a terminal — waiting
+on a keyboard with no prompt would look like a hang, and echoing a typed secret
+would defeat the point. Interactive prompting is tracked separately.
+
+## Fix
+
+Pipe or redirect the value:
+
+```bash
+printf '%s' "$ROUTER_PW" | centrs devices add 192.0.2.5 --user admin --password-stdin
+centrs devices add 192.0.2.5 --user admin --password-stdin < pw.txt
+```
+
+See [`commands/devices/README.md`](https://github.com/tikoci/centrs/blob/main/commands/devices/README.md)
+for the record-password channels.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@tikoci/centrs",
-	"version": "0.1.9-next.27",
+	"version": "0.1.9",
 	"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.4.2",
+	"packageManager": "bun@1.4.4",
 	"license": "MIT",
 	"devDependencies": {
 		"@biomejs/biome": "2.6.3",
 		"@secretlint/secretlint-rule-preset-recommend": "^13.0.7",
-		"@types/bun": "1.4.2",
+		"@types/bun": "1.4.4",
 		"cloc": "^2.6.0-cloc",
 		"cspell": "^10.3.6",
 		"has-flag": "4.0.0",
@@ -42,7 +42,7 @@
 	},
 	"description": "All-in-one TypeScript library/CLI/MCP for interacting with MikroTik RouterOS devices (TUI stub)",
 	"engines": {
-		"bun": ">=1.3.11 <2"
+		"bun": ">=1.4.4 <2"
 	},
 	"private": false,
 	"files": [

package/src/cli/api.ts

@@ -188,7 +188,7 @@ export const apiCommand: CliCommandMetadata = {
 		{
 			flag: "--validate / --no-validate",
 			description:
-				"Run `/console/inspect` validation before the request (default true; `--validate=false` also accepted).",
+				"Validate structured requests with `/console/inspect`; `/execute` scripts run offline analysis, then RouterOS :parse (default true; `--validate=false` disables both stages).",
 		},
 		{
 			flag: "--format",

package/src/cli/common.ts

@@ -63,6 +63,7 @@ export interface CliCommandMetadata {
 	usage: string;
 	summary: string;
 	options: readonly CliCommandOption[];
+	subcommands?: readonly CliCommandMetadata[];
 }
 
 export function expectValue(

package/src/cli/devices.ts

@@ -46,7 +46,23 @@ import {
 	unknownFlagError,
 } from "./common.ts";
 
-export const devicesCommand: CliCommandMetadata = {
+/**
+ * Flags `init`/`encrypt` honor. They touch only the CDB file, never a record,
+ * so record, selection, and provenance flags would be silently ignored there.
+ */
+const CDB_FILE_FLAGS: Readonly<Record<"init" | "encrypt", readonly string[]>> =
+	{
+		init: ["--cdb-file", "--cdb-password", "--format", "--json", "--encrypt"],
+		encrypt: [
+			"--cdb-file",
+			"--cdb-password",
+			"--format",
+			"--json",
+			"--no-backup",
+		],
+	};
+
+const devicesMetadata: CliCommandMetadata = {
 	name: "devices",
 	usage:
 		"centrs devices <init|encrypt|list|show|groups|add|edit|set|remove> [args] [flags]",
@@ -73,7 +89,7 @@ export const devicesCommand: CliCommandMetadata = {
 			flag: "--cdb-password",
 			valueName: "<secret>",
 			description:
-				"Decrypt an encrypted CDB. Falls back to `CENTRS_CDB_PASSWORD`. Also used for `init --encrypt`, `encrypt`, and to re-encrypt on writes.",
+				"CDB password for encrypted reads, writes, explicit encrypted initialization and conversion. Falls back to `CENTRS_CDB_PASSWORD`; a password alone never converts an open CDB.",
 		},
 		{
 			flag: "--via",
@@ -85,7 +101,7 @@ export const devicesCommand: CliCommandMetadata = {
 			flag: "--group",
 			valueName: "<name>",
 			description:
-				"`list` filter / `add`,`edit` first-class group field for the target entry.",
+				"`list` filter / `add`,`set` first-class group field for the target entry.",
 		},
 		{
 			flag: "--where",
@@ -112,13 +128,13 @@ export const devicesCommand: CliCommandMetadata = {
 		{
 			flag: "--explain",
 			description:
-				"`show` only — include the raw `WinBoxCdbRecord` in `data.record`.",
+				"`show` only — include the raw `WinBoxCdbRecord` in `data.record` (its password field reads `<redacted>` unless `--show-password`).",
 		},
 		{
 			flag: "--match",
 			valueName: "<user=…|target=…|record-type>",
 			description:
-				"`show` — disambiguate when `<router>` matches several records: `user=<name>`, `target=<addr>`, or a record-type token.",
+				"`show`,`set`,`remove` — disambiguate when `<router>` matches several records: `user=<name>`, `target=<addr>`, or a record-type token.",
 		},
 		{
 			flag: "--user",
@@ -130,6 +146,16 @@ export const devicesCommand: CliCommandMetadata = {
 			valueName: "<secret>",
 			description: "`add`,`set` — first-class CDB password field.",
 		},
+		{
+			flag: "--password-stdin",
+			description:
+				"`add`,`set` — read the record password from stdin (one trailing newline stripped) so it never rides argv. Conflicts with `--password`.",
+		},
+		{
+			flag: "--show-password",
+			description:
+				"`show`,`add`,`set` — include the record password in cleartext. By default output carries `passwordSet` and withholds the password.",
+		},
 		{
 			flag: "--profile",
 			valueName: "<name>",
@@ -209,6 +235,21 @@ export const devicesCommand: CliCommandMetadata = {
 	],
 };
 
+export const devicesCommand: CliCommandMetadata = {
+	...devicesMetadata,
+	subcommands: (["init", "encrypt"] as const).map((name) => ({
+		name,
+		usage: `centrs devices ${name} [flags]`,
+		summary:
+			name === "init"
+				? "Create an empty CDB at the resolved path; existing readable files are left unchanged."
+				: "Encrypt an existing CDB in place, or verify an already-encrypted file; existing backups remain unchanged.",
+		options: devicesMetadata.options.filter((option) =>
+			CDB_FILE_FLAGS[name].includes(option.flag),
+		),
+	})),
+};
+
 type DevicesSubcommand =
 	| "init"
 	| "encrypt"
@@ -248,6 +289,8 @@ interface DevicesCliArgs {
 	match?: string;
 	user?: string;
 	password?: string;
+	passwordStdin?: boolean;
+	showPassword?: boolean;
 	profile?: string;
 	profileNone?: boolean;
 	profileOwn?: boolean;
@@ -268,22 +311,6 @@ interface DevicesCliArgs {
 	bbox?: BboxPredicate;
 }
 
-/**
- * Flags `init`/`encrypt` honor. They touch only the CDB file, never a record,
- * so record, selection, and provenance flags would be silently ignored there.
- */
-const CDB_FILE_FLAGS: Readonly<Record<"init" | "encrypt", readonly string[]>> =
-	{
-		init: ["--cdb-file", "--cdb-password", "--format", "--json", "--encrypt"],
-		encrypt: [
-			"--cdb-file",
-			"--cdb-password",
-			"--format",
-			"--json",
-			"--no-backup",
-		],
-	};
-
 function parseDevicesCliArgs(args: readonly string[]): DevicesCliArgs {
 	const parsed: DevicesCliArgs = {};
 	const positional: string[] = [];
@@ -344,6 +371,18 @@ function parseDevicesCliArgs(args: readonly string[]): DevicesCliArgs {
 				break;
 			case "--password":
 				parsed.password = expectValue(args, ++index, arg);
+				// `--password --password-stdin` would otherwise store the literal
+				// flag as the password and never read stdin. Treat it as both flags
+				// so the conflict check below refuses it.
+				if (parsed.password === "--password-stdin") {
+					parsed.passwordStdin = true;
+				}
+				break;
+			case "--password-stdin":
+				parsed.passwordStdin = true;
+				break;
+			case "--show-password":
+				parsed.showPassword = true;
 				break;
 			case "--profile":
 				parsed.profile = expectValue(args, ++index, arg);
@@ -415,6 +454,8 @@ function parseDevicesCliArgs(args: readonly string[]): DevicesCliArgs {
 	}
 
 	if (parsed.help) {
+		const sub = positional[0];
+		if (sub === "init" || sub === "encrypt") parsed.subcommand = sub;
 		return parsed;
 	}
 
@@ -504,6 +545,39 @@ function parseDevicesCliArgs(args: readonly string[]): DevicesCliArgs {
 		}
 	}
 
+	if (parsed.passwordStdin && sub !== "add" && sub !== "set") {
+		throw new CentrsError({
+			code: "input/invalid-command",
+			summary: `\`--password-stdin\` is not supported by \`centrs devices ${sub}\`.`,
+			remediation:
+				"`--password-stdin` writes a record password with `centrs devices add`/`set` (e.g. `printf '%s' \"$PW\" | centrs devices set <target> --password-stdin`).",
+			context: { subcommand: sub, flag: "--password-stdin" },
+		});
+	}
+	if (parsed.passwordStdin && parsed.password !== undefined) {
+		throw new CentrsError({
+			code: "usage/conflicting-flags",
+			summary: "`--password` and `--password-stdin` cannot be used together.",
+			remediation:
+				"Pass the record password one way: `--password-stdin` with the value on stdin (keeps it out of argv and `ps`), or `--password <secret>`.",
+			context: { subcommand: sub, flags: ["--password", "--password-stdin"] },
+		});
+	}
+	if (
+		parsed.showPassword === true &&
+		sub !== "show" &&
+		sub !== "add" &&
+		sub !== "set"
+	) {
+		throw new CentrsError({
+			code: "input/invalid-command",
+			summary: `\`--show-password\` is not supported by \`centrs devices ${sub}\`.`,
+			remediation:
+				"`--show-password` reveals the record password in `centrs devices show`, `add` and `set` output. Run `centrs devices show <target> --show-password`.",
+			context: { subcommand: sub, flag: "--show-password" },
+		});
+	}
+
 	if (sub === "show" || sub === "edit" || sub === "remove") {
 		if (rest.length !== 1) {
 			throw new Error(
@@ -663,17 +737,105 @@ function resolveProfile(parsed: DevicesCliArgs): string | undefined {
 	return parsed.profile;
 }
 
+/** Seams for {@link readPasswordStdin}; production reads the real fd 0. */
+export interface PasswordStdinSource {
+	/** Whether stdin is a terminal (defaults to `process.stdin.isTTY`). */
+	isTty?: boolean;
+	/** Read all of stdin as raw bytes (defaults to `Bun.stdin.bytes()`). */
+	read?: () => Promise<Uint8Array>;
+}
+
+// `fatal` rejects malformed UTF-8 instead of substituting U+FFFD; `ignoreBOM`
+// keeps a leading U+FEFF visible so it can be refused rather than dropped.
+const stdinPasswordDecoder = new TextDecoder("utf-8", {
+	fatal: true,
+	ignoreBOM: true,
+});
+
+/**
+ * Read a record password for `devices add`/`set --password-stdin` (#582).
+ *
+ * Exactly one trailing `\n` or `\r\n` is stripped (at the byte level) so
+ * `echo pw | …` works; any other whitespace is part of the password. The rest
+ * must be valid UTF-8 without a leading byte-order mark: the CDB stores record
+ * strings as UTF-8 and drops a leading BOM when it reads them back, so either
+ * would silently store a credential different from the bytes piped in. A TTY stdin is refused rather
+ * than prompted (interactive prompting is #160), and empty input is refused so
+ * clearing a stored password stays the deliberate `--password ""`. The value is
+ * never placed in an error summary, remediation, or context.
+ */
+export async function readPasswordStdin(
+	source: PasswordStdinSource = {},
+): Promise<string> {
+	const isTty = source.isTty ?? process.stdin.isTTY === true;
+	if (isTty) {
+		throw new CentrsError({
+			code: "usage/stdin-is-tty",
+			summary:
+				"`--password-stdin` reads the password from stdin, but stdin is a terminal.",
+			remediation:
+				"Pipe the password in (e.g. `printf '%s' \"$PW\" | centrs devices set <target> --password-stdin`) or redirect it from a file with `< pw.txt`. Interactive prompting is not supported.",
+			context: { flag: "--password-stdin" },
+		});
+	}
+	const raw = await (source.read ?? (() => Bun.stdin.bytes()))();
+	const end = raw.length;
+	const trimmed =
+		end >= 2 && raw[end - 2] === 0x0d && raw[end - 1] === 0x0a
+			? raw.subarray(0, end - 2)
+			: end >= 1 && raw[end - 1] === 0x0a
+				? raw.subarray(0, end - 1)
+				: raw;
+	if (trimmed.length === 0) {
+		throw new CentrsError({
+			code: "input/empty-stdin",
+			summary: "`--password-stdin` received an empty password on stdin.",
+			remediation:
+				'Pipe a non-empty password to stdin. To clear a stored password on purpose, use `centrs devices set <target> --password ""`.',
+			context: { flag: "--password-stdin" },
+		});
+	}
+	const invalid = (reason: string) =>
+		new CentrsError({
+			code: "input/invalid-stdin",
+			summary: `\`--password-stdin\` received ${reason}.`,
+			remediation:
+				"Pipe the password as UTF-8 text with no byte-order mark (e.g. `printf '%s' \"$PW\" | centrs devices set <target> --password-stdin`). Re-save a file written by an editor as UTF-8 without BOM.",
+			context: { flag: "--password-stdin", byteLength: trimmed.length },
+		});
+	let value: string;
+	try {
+		value = stdinPasswordDecoder.decode(trimmed);
+	} catch {
+		throw invalid("bytes that are not valid UTF-8");
+	}
+	if (value.startsWith("\uFEFF")) {
+		throw invalid("a leading byte-order mark (U+FEFF)");
+	}
+	return value;
+}
+
 export async function runDevicesCli(args: readonly string[]): Promise<number> {
 	let parsed: DevicesCliArgs | undefined;
 	let envSnapshot: Record<string, string | undefined> | undefined;
 	try {
 		parsed = parseDevicesCliArgs(args);
 		if (parsed.help) {
-			console.log(renderCommandHelp(describeCentrs(), devicesCommand));
+			const command =
+				devicesCommand.subcommands?.find(
+					(subcommand) => subcommand.name === parsed?.subcommand,
+				) ?? devicesCommand;
+			console.log(renderCommandHelp(describeCentrs(), command));
 			return 0;
 		}
 
 		envSnapshot = Bun.env;
+		// Read stdin before touching the CDB so a TTY or empty pipe fails fast
+		// without loading (or decrypting) anything. Only add/set get here with
+		// the flag; the parser refuses it on every other subcommand.
+		const password = parsed.passwordStdin
+			? await readPasswordStdin()
+			: parsed.password;
 		if (parsed.subcommand === "init" || parsed.subcommand === "encrypt") {
 			const options = {
 				cdbFile: parsed.cdbFile,
@@ -715,6 +877,7 @@ export async function runDevicesCli(args: readonly string[]): Promise<number> {
 					match: parsed.match,
 					via: parsed.via,
 					env: envSnapshot,
+					showPassword: parsed.showPassword,
 				});
 				break;
 			case "groups":
@@ -738,7 +901,7 @@ export async function runDevicesCli(args: readonly string[]): Promise<number> {
 					target: parsed.target,
 					recordType,
 					user: parsed.user,
-					password: parsed.password,
+					password,
 					group: parsed.group,
 					profile: resolveProfile(parsed),
 					session: parsed.session,
@@ -749,6 +912,7 @@ export async function runDevicesCli(args: readonly string[]): Promise<number> {
 					],
 					force: parsed.force,
 					strict: parsed.strict,
+					showPassword: parsed.showPassword,
 				});
 				break;
 			}
@@ -769,11 +933,12 @@ export async function runDevicesCli(args: readonly string[]): Promise<number> {
 						...(parsed.kvArgs ?? []).map(parseKvArg),
 					],
 					user: parsed.user,
-					password: parsed.password,
+					password,
 					group: parsed.group,
 					profile: resolveProfile(parsed),
 					session: parsed.session,
 					strict: parsed.strict,
+					showPassword: parsed.showPassword,
 				});
 				break;
 			case "remove":

package/src/cli/execute.ts

@@ -58,11 +58,11 @@ export const executeCommand: CliCommandMetadata = {
 	usage:
 		"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.",
+		"Run a RouterOS read or write command via native API, REST, SSH, or mac-telnet.",
 	options: [
 		{
 			flag: "--via",
-			valueName: "<native-api|rest-api|mac-telnet>",
+			valueName: "<native-api|rest-api|ssh|mac-telnet>",
 			description:
 				"Pin the protocol selector; no silent downgrade when set. A bare MAC target defaults to mac-telnet.",
 		},
@@ -141,7 +141,7 @@ export const executeCommand: CliCommandMetadata = {
 		{
 			flag: "--validate / --no-validate",
 			description:
-				"Run RouterOS :parse and /console/inspect validation before execution (default true; `--validate=false` also accepted).",
+				"Run offline analysis, then RouterOS :parse, plus `/console/inspect` for structured commands over native API/REST (default true; `--validate=false` disables both stages).",
 		},
 		{
 			flag: "--yes",

package/src/cli/settings.ts

@@ -191,6 +191,14 @@ function parseSettingsCliArgs(args: readonly string[]): SettingsCliArgs {
 		result.value = rest[1];
 	}
 
+	// A blank <attr> is the caller's input, so reject it here; after parsing,
+	// an untyped throw is reported as internal/* (#587).
+	if (result.attr !== undefined && result.attr.trim() === "") {
+		throw new Error(
+			`\`centrs settings ${result.subcommand}\` requires a non-empty <attr>.`,
+		);
+	}
+
 	return result;
 }
 
@@ -249,12 +257,26 @@ export async function runSettingsCli(args: readonly string[]): Promise<number> {
 	} catch (error) {
 		const format = parsed?.format ?? inferSettingsFormat(args);
 		const settingsFile = defaultSettingsPath(envSnapshot ?? Bun.env);
-		const centrsError = asCentrsError(error, {
-			code: "input/invalid-command",
-			summary: error instanceof Error ? error.message : String(error),
-			remediation:
-				"Use `centrs settings --help` to inspect the supported subcommands and flags.",
-		});
+		const summary = error instanceof Error ? error.message : String(error);
+		// Only argument parsing reports the caller's input. Once the arguments
+		// parsed, an untyped throw (a core or renderer fault) is a centrs bug,
+		// not something `--help` can fix (#587).
+		const centrsError = asCentrsError(
+			error,
+			parsed === undefined
+				? {
+						code: "input/invalid-command",
+						summary,
+						remediation:
+							"Use `centrs settings --help` to inspect the supported subcommands and flags.",
+					}
+				: {
+						code: "internal/settings-failed",
+						summary,
+						remediation:
+							"This is a centrs bug; re-run with `--json` and report the command and the error.",
+					},
+		);
 		const envelope = buildSettingsErrorEnvelope(
 			parsed?.subcommand ?? "print",
 			settingsFile,

package/src/core/error-catalog.ts

@@ -154,6 +154,11 @@ export const errorCatalog: readonly ErrorCatalogEntry[] = [
 	},
 
 	// input/*
+	{
+		code: "input/empty-stdin",
+		summary:
+			"A flag that reads its value from stdin (e.g. `--password-stdin`) received nothing.",
+	},
 	{
 		code: "input/incomplete-gps",
 		summary: "lat/lon (or a --gps tuple) were not given as a complete pair.",
@@ -200,6 +205,11 @@ export const errorCatalog: readonly ErrorCatalogEntry[] = [
 		summary:
 			"The RouterOS path is malformed: not slash-prefixed, a segment that is not a menu name, or characters a REST URL would reinterpret.",
 	},
+	{
+		code: "input/invalid-stdin",
+		summary:
+			"A flag that reads its value from stdin (e.g. `--password-stdin`) received bytes that are not valid UTF-8 text, or began with a byte-order mark.",
+	},
 	{
 		code: "input/invalid-target",
 		summary: "The target string is invalid for the requested operation.",
@@ -668,6 +678,11 @@ export const errorCatalog: readonly ErrorCatalogEntry[] = [
 		summary:
 			"stdin was redirected but the input came from the positional argument, so anything piped in was not analyzed.",
 	},
+	{
+		code: "usage/stdin-is-tty",
+		summary:
+			"A flag that reads its value from stdin (e.g. `--password-stdin`) was given while stdin is a terminal.",
+	},
 	{
 		code: "usage/fanout-not-supported",
 		summary: