@tikoci/centrs 0.1.0

package/src/cli/execute.ts

@@ -0,0 +1,333 @@
+import { asCentrsError, formatCentrsErrorText } from "../errors.ts";
+import {
+	buildExecuteErrorEnvelope,
+	type ExecuteOutputFormat,
+	type ExecuteRequest,
+	executeEnvelope,
+	executeOutputFormats,
+	renderExecuteEnvelope,
+} from "../execute.ts";
+import { describeCentrs } from "../index.ts";
+import {
+	type CliCommandMetadata,
+	expectValue,
+	renderCommandHelp,
+} from "./common.ts";
+
+export const executeCommand: CliCommandMetadata = {
+	name: "execute",
+	usage: "centrs execute <target> <command> [flags]",
+	summary:
+		"Run a RouterOS read or write command via native API, REST, or mac-telnet.",
+	options: [
+		{
+			flag: "--via",
+			valueName: "<native-api|rest-api|mac-telnet>",
+			description:
+				"Pin the protocol selector; no silent downgrade when set. A bare MAC target defaults to mac-telnet.",
+		},
+		{
+			flag: "--host",
+			valueName: "<host|url>",
+			description: "Override the resolved host or base URL for the target.",
+		},
+		{
+			flag: "--port",
+			valueName: "<port>",
+			description: "Override the resolved management port.",
+		},
+		{
+			flag: "--username / --user / -u",
+			valueName: "<name>",
+			description:
+				"RouterOS username (aliases `--user`, `-u`). Falls back to `CENTRS_USERNAME`.",
+		},
+		{
+			flag: "--password",
+			valueName: "<secret>",
+			description: "RouterOS password. Falls back to `CENTRS_PASSWORD`.",
+		},
+		{
+			flag: "--ssh-key",
+			valueName: "<path>",
+			description:
+				"`--via ssh`: explicit private-key path. Falls back to `CENTRS_SSH_KEY` / the `ssh-agent`.",
+		},
+		{
+			flag: "--insecure",
+			description:
+				"Disable SSH host-key verification (`--via ssh`: accepts changed/impersonated keys, not just new) or accept a self-signed `api-ssl` TLS cert. Default verifies.",
+		},
+		{
+			flag: "--cdb-file",
+			valueName: "<path>",
+			description: "Read target credentials from a WinBox CDB file.",
+		},
+		{
+			flag: "--cdb-password",
+			valueName: "<password>",
+			description: "Decrypt an encrypted WinBox CDB file.",
+		},
+		{
+			flag: "--resolve",
+			valueName: "<none|arp>",
+			description:
+				"Resolve a MAC-address target to an IP via the host ARP cache (default none).",
+		},
+		{
+			flag: "--timeout",
+			valueName: "<duration>",
+			description: "Per-request timeout (for REST, max 60s).",
+		},
+		{
+			flag: "--validate[=false]",
+			description:
+				"Run RouterOS :parse and /console/inspect validation before execution (default true).",
+		},
+		{
+			flag: "--yes",
+			description:
+				"Confirm write-shaped add/set/remove commands in non-interactive runs.",
+		},
+		{
+			flag: "--max-results",
+			valueName: "<bytes>",
+			description: "Fail if the rendered envelope exceeds this byte budget.",
+		},
+		{
+			flag: "--format",
+			valueName: "<text|json|yaml>",
+			description:
+				"Output format for the CLI response. Defaults to text; use --json or --format json for the structured envelope.",
+		},
+		{
+			flag: "--json",
+			description: "Shortcut for `--format json`.",
+		},
+		{
+			flag: "--verbose",
+			description: "Include additional context in text output.",
+		},
+		{
+			flag: "--",
+			description:
+				"End centrs option parsing: every following token is the literal RouterOS command, even flag-shaped ones (e.g. `-- /interface print where disabled=yes`).",
+		},
+	],
+};
+
+interface ExecuteCliArgs extends ExecuteRequest {
+	help?: boolean;
+	format?: ExecuteOutputFormat;
+}
+
+export function parseExecuteCliArgs(args: readonly string[]): ExecuteCliArgs {
+	const parsed: ExecuteCliArgs = { command: "" };
+	const positional: string[] = [];
+	let endOfOptions = false;
+
+	for (let index = 0; index < args.length; index += 1) {
+		const arg = args[index];
+		if (arg === undefined) {
+			continue;
+		}
+		// A bare `--` ends centrs option parsing: every later token is part of the
+		// literal RouterOS command, even flag-shaped ones. Lets a command carry
+		// tokens like `--` / `-foo` (or a value that looks like a flag) without the
+		// parser claiming them. `--` itself is consumed, not added to the command.
+		if (endOfOptions) {
+			positional.push(arg);
+			continue;
+		}
+		if (arg === "--") {
+			endOfOptions = true;
+			continue;
+		}
+		if (arg.startsWith("--validate=")) {
+			parsed.validate = parseBooleanFlag(arg.slice("--validate=".length), arg);
+			continue;
+		}
+		switch (arg) {
+			case "--help":
+			case "-h":
+				parsed.help = true;
+				break;
+			case "--json":
+				parsed.format = "json";
+				break;
+			case "--verbose":
+				parsed.verbose = true;
+				break;
+			case "--yes":
+				parsed.yes = true;
+				break;
+			case "--validate":
+				parsed.validate = true;
+				break;
+			case "--no-validate":
+				parsed.validate = false;
+				break;
+			case "--via":
+				parsed.via = expectValue(args, ++index, arg);
+				break;
+			case "--host":
+				parsed.host = expectValue(args, ++index, arg);
+				break;
+			case "--port":
+				parsed.port = parseIntegerFlag(expectValue(args, ++index, arg), arg);
+				break;
+			case "--user":
+			case "-u":
+			case "--username":
+				parsed.username = expectValue(args, ++index, arg);
+				break;
+			case "--password":
+				parsed.password = expectValue(args, ++index, arg);
+				break;
+			case "--ssh-key":
+				parsed.sshKey = expectValue(args, ++index, arg);
+				break;
+			case "--insecure":
+				parsed.insecure = true;
+				break;
+			case "--cdb-file":
+				parsed.cdbFile = expectValue(args, ++index, arg);
+				break;
+			case "--cdb-password":
+				parsed.cdbPassword = expectValue(args, ++index, arg);
+				break;
+			case "--resolve":
+				parsed.resolve = expectValue(args, ++index, arg);
+				break;
+			case "--timeout":
+				parsed.timeout = expectValue(args, ++index, arg);
+				break;
+			case "--max-results":
+				parsed.maxResultsBytes = parseIntegerFlag(
+					expectValue(args, ++index, arg),
+					arg,
+				);
+				break;
+			case "--format": {
+				const value = expectValue(args, ++index, arg);
+				if (!executeOutputFormats.includes(value as ExecuteOutputFormat)) {
+					throw new Error(
+						`--format must be one of ${executeOutputFormats.join(", ")}; got ${value}.`,
+					);
+				}
+				parsed.format = value as ExecuteOutputFormat;
+				break;
+			}
+			default:
+				if (arg.startsWith("-")) {
+					throw new Error(`Unknown execute flag: ${arg}`);
+				}
+				positional.push(arg);
+				break;
+		}
+	}
+
+	parsed.targetInput = positional[0];
+	parsed.command = positional.slice(1).join(" ");
+	parsed.stdinIsTty = process.stdin.isTTY;
+	return parsed;
+}
+
+export async function runExecuteCli(args: readonly string[]): Promise<number> {
+	let parsed: ExecuteCliArgs | undefined;
+	try {
+		parsed = parseExecuteCliArgs(args);
+		if (parsed.help) {
+			console.log(renderCommandHelp(describeCentrs(), executeCommand));
+			return 0;
+		}
+
+		const envelope = await executeEnvelope(parsed);
+		const resolvedFormat =
+			(
+				envelope.meta.operation as {
+					request?: { format?: ExecuteOutputFormat };
+				}
+			)?.request?.format ??
+			parsed.format ??
+			"text";
+		const rendered = renderExecuteEnvelope(envelope, resolvedFormat, {
+			verbose: parsed.verbose,
+		});
+		if (envelope.ok) {
+			console.log(rendered);
+			return 0;
+		}
+		console.error(rendered);
+		return 1;
+	} catch (error) {
+		// Parse/usage errors land here too: surface them through the same typed
+		// envelope as every other runner (no raw message, no exit code 2).
+		const format = inferExecuteFormat(args, parsed);
+		if (format === "json" || format === "yaml") {
+			const envelope = buildExecuteErrorEnvelope(
+				parsed ?? { command: "" },
+				error,
+			);
+			console.error(
+				renderExecuteEnvelope(envelope, format, {
+					verbose: parsed?.verbose ?? false,
+				}),
+			);
+		} else {
+			console.error(
+				formatCentrsErrorText(
+					asCentrsError(error, {
+						code: "input/invalid-command",
+						summary: error instanceof Error ? error.message : String(error),
+						remediation:
+							"Use `centrs execute --help` to inspect the supported command shape and flags.",
+					}),
+					{ verbose: parsed?.verbose ?? args.includes("--verbose") },
+				),
+			);
+		}
+		return 1;
+	}
+}
+
+function inferExecuteFormat(
+	args: readonly string[],
+	parsed?: ExecuteCliArgs,
+): ExecuteOutputFormat {
+	if (parsed?.format) {
+		return parsed.format;
+	}
+	if (args.includes("--json")) {
+		return "json";
+	}
+	const index = args.indexOf("--format");
+	if (index >= 0) {
+		const value = args[index + 1];
+		if (
+			value !== undefined &&
+			executeOutputFormats.includes(value as ExecuteOutputFormat)
+		) {
+			return value as ExecuteOutputFormat;
+		}
+	}
+	return "text";
+}
+
+function parseIntegerFlag(value: string, flag: string): number {
+	const parsed = Number.parseInt(value, 10);
+	if (!Number.isInteger(parsed)) {
+		throw new Error(`${flag} must be an integer; got ${value}.`);
+	}
+	return parsed;
+}
+
+function parseBooleanFlag(value: string, flag: string): boolean {
+	if (["true", "1", "yes", "on"].includes(value.toLowerCase())) {
+		return true;
+	}
+	if (["false", "0", "no", "off"].includes(value.toLowerCase())) {
+		return false;
+	}
+	throw new Error(`${flag} must be true or false; got ${value}.`);
+}

package/src/cli/mcp.ts

@@ -0,0 +1,109 @@
+/**
+ * `centrs mcp` CLI surface: starts the stdio MCP server. Arg parsing here is
+ * deliberately thin — the server's behavior is governed by the CDB allowlist
+ * and the global toggles (`--cdb-file`/`--cdb-password`/
+ * `--allow-adhoc-targets`), resolved in `../mcp/config.ts`.
+ *
+ * Transport is stdio only; HTTP/remote access is the proxy surface's job.
+ */
+
+import { asCentrsError, formatCentrsErrorText } from "../errors.ts";
+import { describeCentrs } from "../index.ts";
+import { resolveMcpConfig } from "../mcp/config.ts";
+import { runMcpStdio } from "../mcp/server.ts";
+import {
+	type CliCommandMetadata,
+	expectValue,
+	renderCommandHelp,
+} from "./common.ts";
+
+export const mcpCommand: CliCommandMetadata = {
+	name: "mcp",
+	usage: "centrs mcp [start] [--cdb-file <path>] [--allow-adhoc-targets]",
+	summary:
+		"Start the centrs MCP server (stdio) — scoped RouterOS tools gated by the CDB allowlist.",
+	options: [
+		{
+			flag: "--cdb-file",
+			valueName: "<path>",
+			description:
+				"CDB allowlist path (default `~/.config/tikoci/winbox.cdb`, or CENTRS_CDB_FILE).",
+		},
+		{
+			flag: "--cdb-password",
+			valueName: "<password>",
+			description:
+				"Decrypt password for an encrypted CDB (or CENTRS_CDB_PASSWORD).",
+		},
+		{
+			flag: "--allow-adhoc-targets",
+			description:
+				"Reserved unsafe escape hatch for future inline targets; current tools still use CDB-only targets.",
+		},
+		{ flag: "--help", description: "Show this help." },
+	],
+};
+
+interface McpCliArgs {
+	help?: boolean;
+	cdbFile?: string;
+	cdbPassword?: string;
+	allowAdhocTargets?: boolean;
+}
+
+export function parseMcpCliArgs(args: readonly string[]): McpCliArgs {
+	const parsed: McpCliArgs = {};
+	for (let index = 0; index < args.length; index += 1) {
+		const arg = args[index];
+		switch (arg) {
+			case "start":
+				// Optional verb; `centrs mcp` and `centrs mcp start` are equivalent.
+				break;
+			case "--help":
+			case "-h":
+				parsed.help = true;
+				break;
+			case "--cdb-file":
+				parsed.cdbFile = expectValue(args, ++index, "--cdb-file");
+				break;
+			case "--cdb-password":
+				parsed.cdbPassword = expectValue(args, ++index, "--cdb-password");
+				break;
+			case "--allow-adhoc-targets":
+				parsed.allowAdhocTargets = true;
+				break;
+			default:
+				throw new Error(`Unknown flag for centrs mcp: ${arg}`);
+		}
+	}
+	return parsed;
+}
+
+export async function runMcpCli(args: readonly string[]): Promise<number> {
+	try {
+		const parsed = parseMcpCliArgs(args);
+		if (parsed.help) {
+			console.log(renderCommandHelp(describeCentrs(), mcpCommand));
+			return 0;
+		}
+		const config = resolveMcpConfig({
+			cdbFile: parsed.cdbFile,
+			cdbPassword: parsed.cdbPassword,
+			allowAdhocTargets: parsed.allowAdhocTargets,
+		});
+		await runMcpStdio(config);
+		return 0;
+	} catch (error) {
+		console.error(
+			formatCentrsErrorText(
+				asCentrsError(error, {
+					code: "internal/mcp-start",
+					summary: error instanceof Error ? error.message : String(error),
+					remediation:
+						"Check `centrs mcp --help` for supported flags and the CDB path.",
+				}),
+			),
+		);
+		return 1;
+	}
+}