@tikoci/centrs 0.1.3 → 0.1.6

package/src/cli/selection.ts

@@ -65,6 +65,12 @@ export const selectionCommandOptions: readonly CliCommandOption[] = [
 		flag: "--default",
 		description: "Select the reserved `__default__` record.",
 	},
+	{
+		flag: "--quickchr",
+		valueName: "<name>",
+		description:
+			"Target a running quickchr-managed CHR VM by name (repeatable; fans out when repeated). Exclusive of positional targets and CDB selectors; conflicts with direct connection overrides (--host/--port/--username/--password, and --ssh-key where the command has it).",
+	},
 	{
 		flag: "--concurrency",
 		valueName: "<n>",
@@ -81,11 +87,13 @@ export interface SelectionFlags {
 	bbox?: BboxPredicate;
 	all: boolean;
 	default: boolean;
+	/** Repeatable `--quickchr <name>` (named-live-provider; exclusive in v1). */
+	quickchr: string[];
 	concurrency?: number;
 }
 
 export function emptySelectionFlags(): SelectionFlags {
-	return { groups: [], where: [], all: false, default: false };
+	return { groups: [], where: [], all: false, default: false, quickchr: [] };
 }
 
 /** The selection flag tokens, for a command's `--help` table + unknown-flag suggestions. */
@@ -96,6 +104,7 @@ export const selectionFlagTokens = [
 	"--bbox",
 	"--all",
 	"--default",
+	"--quickchr",
 	"--concurrency",
 ] as const;
 
@@ -143,6 +152,9 @@ export function consumeSelectionFlag(
 		case "--bbox":
 			acc.bbox = parseBbox(expectValue(args, index + 1, arg));
 			return index + 1;
+		case "--quickchr":
+			acc.quickchr.push(expectValue(args, index + 1, arg));
+			return index + 1;
 		case "--concurrency": {
 			const raw = expectValue(args, index + 1, arg);
 			const parsed = parseStrictInteger(raw);
@@ -175,26 +187,74 @@ export function buildTargetSelection(
 		where: flags.where,
 		near: flags.near,
 		bbox: flags.bbox,
+		quickchr: flags.quickchr,
 	};
 }
 
+/** True when any CDB selector flag is present (quickchr and positionals excluded). */
+function hasCdbSelector(flags: SelectionFlags): boolean {
+	return (
+		flags.all ||
+		flags.default ||
+		flags.groups.length > 0 ||
+		flags.where.length > 0 ||
+		flags.near !== undefined ||
+		flags.bbox !== undefined
+	);
+}
+
+/**
+ * `--quickchr` exclusivity (v1, `docs/CONSTITUTION.md` → Resolution providers):
+ * a command targets quickchr machines OR CDB/literal targets, never both.
+ * Commands call this after splitting positionals, in both single-target and
+ * fan-out mode; relaxing it later is additive.
+ */
+export function assertQuickchrExclusive(
+	flags: SelectionFlags,
+	targetPositionalCount: number,
+): void {
+	if (flags.quickchr.length === 0) {
+		return;
+	}
+	if (hasCdbSelector(flags) || targetPositionalCount > 0) {
+		throw new CentrsError({
+			code: "usage/conflicting-flags",
+			summary:
+				"`--quickchr` is exclusive: a command targets quickchr machines or CDB/literal targets, not both.",
+			remediation:
+				"Drop the positional target / CDB selector (or the `--quickchr` flag) so the selection has one target source.",
+			context: {
+				quickchr: [...flags.quickchr],
+				positionals: targetPositionalCount,
+			},
+		});
+	}
+}
+
 /**
- * Fan-out mode is keyed on INTENT, not resolved count: any selector flag, or more
- * than one positional target. A plain single-positional call stays single-target
- * (never `FanoutData`); a selector that resolves to one/zero members is still
- * fan-out mode. See `docs/CONSTITUTION.md` (Target selection).
+ * True when any target-taking flag is present, so positionals are operation
+ * args, not targets. Superset of {@link isFanoutMode}'s flag term: a single
+ * `--quickchr` names the target (like a lone positional, still single-target
+ * mode) but already claims the positional slots.
+ */
+export function hasTargetSelector(flags: SelectionFlags): boolean {
+	return hasCdbSelector(flags) || flags.quickchr.length > 0;
+}
+
+/**
+ * Fan-out mode is keyed on INTENT, not resolved count: any selector flag, more
+ * than one positional target, or a repeated `--quickchr`. A plain
+ * single-positional call — and a single `--quickchr <name>` — stays
+ * single-target (never `FanoutData`); a selector that resolves to one/zero
+ * members is still fan-out mode. See `docs/CONSTITUTION.md` (Target selection).
  */
 export function isFanoutMode(
 	flags: SelectionFlags,
 	targetPositionalCount: number,
 ): boolean {
 	return (
-		flags.all ||
-		flags.default ||
-		flags.groups.length > 0 ||
-		flags.where.length > 0 ||
-		flags.near !== undefined ||
-		flags.bbox !== undefined ||
+		hasCdbSelector(flags) ||
+		flags.quickchr.length > 1 ||
 		targetPositionalCount > 1
 	);
 }

package/src/cli/settings.ts

@@ -36,7 +36,7 @@ export const settingsCommand: CliCommandMetadata = {
 	name: "settings",
 	usage: "centrs settings [print|get|set|reset] [args] [flags]",
 	summary:
-		"Manage centrs's own global preferences (centrs.env) and inspect the __default__ CDB record.",
+		"Manage centrs's own global preferences (`centrs.env`) and inspect the `__default__` CDB record.",
 	options: [
 		{
 			flag: "--all",
@@ -47,7 +47,7 @@ export const settingsCommand: CliCommandMetadata = {
 			flag: "--cdb-file",
 			valueName: "<path>",
 			description:
-				"`print` only — CDB to probe for the __default__ record summary (falls back to normal CDB resolution; never centrs.env).",
+				"`print` only — CDB to probe for the `__default__` record summary (falls back to normal CDB resolution; never centrs.env).",
 		},
 		{
 			flag: "--cdb-password",

package/src/cli/terminal.ts

@@ -6,6 +6,7 @@
  * `process.*`); the core relay in `../terminal.ts` stays io-agnostic.
  */
 
+import { toYaml } from "../core/yaml.ts";
 import {
 	asCentrsError,
 	CentrsError,
@@ -18,7 +19,6 @@ import {
 	type TerminalIo,
 	type TerminalRequest,
 } from "../index.ts";
-import { toYaml } from "../retrieve.ts";
 import {
 	type CliCommandMetadata,
 	expectValue,

package/src/cli/transfer.ts

@@ -23,6 +23,7 @@ import {
 	transferOutputFormats,
 	transferVerbs,
 } from "../index.ts";
+import { assertNoQuickchrOverrideConflict } from "../resolver/index.ts";
 import {
 	type CliCommandMetadata,
 	expectValue,
@@ -38,6 +39,7 @@ import {
 	withTips,
 } from "./missing-target.ts";
 import {
+	assertQuickchrExclusive,
 	buildTargetSelection,
 	consumeSelectionFlag,
 	emptySelectionFlags,
@@ -82,8 +84,7 @@ export const transferCommand: CliCommandMetadata = {
 				"Accept a self-signed TLS cert (https/api-ssl) or a new SSH host key. Default verifies.",
 		},
 		{
-			flag: "--force",
-			valueName: "(--overwrite)",
+			flag: "--force / --overwrite",
 			description: "Replace an existing destination. Default refuses it.",
 		},
 		...selectionCommandOptions,
@@ -99,10 +100,10 @@ export const transferCommand: CliCommandMetadata = {
 				"Confirm a mutating fan-out (upload/remove/mkdir/copy) across multiple routers in non-interactive runs.",
 		},
 		{
-			flag: "--verify",
+			flag: "--verify / --no-verify",
 			valueName: "<size|checksum|off>",
 			description:
-				"Post-transfer integrity check. Default size; --no-verify skips.",
+				"Post-transfer integrity check. Default size; `--no-verify` skips.",
 		},
 		{
 			flag: "--type",
@@ -147,6 +148,7 @@ export const transferCommand: CliCommandMetadata = {
 				"Output format. Defaults to text; --json / --yaml shortcuts.",
 		},
 		{ flag: "--json", description: "Shortcut for --format json." },
+		{ flag: "--yaml", description: "Shortcut for --format yaml." },
 		{
 			flag: "--cdb-file",
 			valueName: "<path>",
@@ -479,7 +481,10 @@ function assemblePositionals(
 	selectionFlags: SelectionFlags,
 	fixedVerb?: TransferVerb,
 ): { request: TransferRequest; targetPositionals: readonly string[] } {
-	const hasSelector = isFanoutMode(selectionFlags, 0);
+	// Any target-taking flag (CDB selector or `--quickchr`) claims the target
+	// slots, so every positional belongs to the verb/paths.
+	const hasSelector =
+		isFanoutMode(selectionFlags, 0) || selectionFlags.quickchr.length > 0;
 	let verb: TransferVerb;
 	let targetPositionals: readonly string[];
 	let rest: readonly string[];
@@ -522,9 +527,21 @@ function assemblePositionals(
 
 	const request: TransferRequest = { verb, ...flags };
 	applyVerbPaths(request, verb, rest);
+	assertQuickchrExclusive(selectionFlags, targetPositionals.length);
+	// Direct connection overrides conflict with `--quickchr` globally: reject at
+	// parse time so a repeated `--quickchr` gets one usage error (exit 1), never
+	// per-member failures. The resolver re-checks for library callers.
+	if (selectionFlags.quickchr.length > 0) {
+		assertNoQuickchrOverrideConflict(request, selectionFlags.quickchr[0] ?? "");
+	}
 
-	// Single-target (not fan-out mode) needs exactly one resolved target.
+	// Single-target (not fan-out mode) needs exactly one resolved target: one
+	// positional, or one `--quickchr <name>` (the named-live-provider).
 	if (!isFanoutMode(selectionFlags, targetPositionals.length)) {
+		if (selectionFlags.quickchr.length === 1) {
+			request.quickchr = selectionFlags.quickchr[0];
+			return { request, targetPositionals };
+		}
 		const targetInput = targetPositionals[0];
 		if (!targetInput) {
 			throw missingTargetError({

package/src/cli.ts

@@ -2,9 +2,11 @@
 
 import { apiCommand, runApiCli } from "./cli/api.ts";
 import { btestCommand, runBtestCli } from "./cli/btest.ts";
+import type { CliCommandMetadata } from "./cli/common.ts";
 import { devicesCommand, runDevicesCli } from "./cli/devices.ts";
 import { discoverCommand, runDiscoverCli } from "./cli/discover.ts";
 import { executeCommand, runExecuteCli } from "./cli/execute.ts";
+import { explainCliCommand, runExplainCli } from "./cli/explain.ts";
 import { mcpCommand, runMcpCli } from "./cli/mcp.ts";
 import { retrieveCommand, runRetrieveCli } from "./cli/retrieve.ts";
 import { runSettingsCli, settingsCommand } from "./cli/settings.ts";
@@ -13,18 +15,26 @@ import { runTransferCli, transferCommand } from "./cli/transfer.ts";
 import { asCentrsError, formatCentrsErrorText } from "./errors.ts";
 import { describeCentrs, plannedProtocols, plannedSurfaces } from "./index.ts";
 
-const commandSummaries: ReadonlyArray<{ name: string; summary: string }> = [
+/** Every CLI command's metadata, in help/docs order. `scripts/gen-cli-docs.ts` renders `docs/CLI.md` from this. */
+export const cliCommands: ReadonlyArray<CliCommandMetadata> = [
 	retrieveCommand,
 	executeCommand,
 	apiCommand,
 	transferCommand,
 	terminalCommand,
+	explainCliCommand,
 	devicesCommand,
 	discoverCommand,
 	btestCommand,
 	mcpCommand,
 	settingsCommand,
-].map((command) => ({ name: command.name, summary: command.summary }));
+];
+
+const commandSummaries: ReadonlyArray<{ name: string; summary: string }> =
+	cliCommands.map((command) => ({
+		name: command.name,
+		summary: command.summary,
+	}));
 
 export function renderCliHelp(): string {
 	return [
@@ -75,6 +85,9 @@ export async function runCli(
 		if (command === "download") {
 			return await runTransferCli(rest, { fixedVerb: "download" });
 		}
+		if (command === "explain") {
+			return await runExplainCli(rest);
+		}
 		if (command === "devices") {
 			return await runDevicesCli(rest);
 		}

package/src/core/envelope.ts

@@ -27,7 +27,9 @@ import type { RouterOsProtocol } from "../protocols/index.ts";
 /**
  * Where a resolved setting/identity field came from. Precedence (low → high)
  * is config < comment-kv < env < cli; `cdb` and `arp` describe identity
- * resolution rather than settings precedence.
+ * resolution rather than settings precedence, and `provider` marks a field a
+ * named-live-provider supplied (e.g. `--quickchr`), which bypasses the ladder
+ * entirely (`docs/CONSTITUTION.md` → Resolution providers).
  */
 export type SettingSourceKind =
 	| "default"
@@ -36,7 +38,8 @@ export type SettingSourceKind =
 	| "env"
 	| "cli"
 	| "cdb"
-	| "arp";
+	| "arp"
+	| "provider";
 
 export interface SettingSource {
 	kind: SettingSourceKind;
@@ -108,6 +111,50 @@ export interface EnvelopeTargetMeta {
 	sources?: Record<string, SettingSource>;
 }
 
+/**
+ * One stage of the two-stage validation gate (GH#354).
+ *
+ * `offline` is the corpus-gated analyzer (`src/offline-gate.ts`): it opens no
+ * connection, so a `failed` offline stage means the device was never contacted.
+ * `device` is the RouterOS-side preflight — `:put [:parse …]` and/or
+ * `/console/inspect request=child`, depending on the command and transport.
+ *
+ * Stages appear in the order they run, and a stage that did not run is still
+ * listed with `result: "skipped"`. That is the point of the array: a reader must
+ * be able to tell "the device accepted it" from "the device was never asked".
+ */
+export interface EnvelopeValidationStage {
+	stage: "offline" | "device";
+	/** Validator identity, e.g. `offline explain (canonicalizer)` or `:put [:parse]`. */
+	source: string;
+	result: "passed" | "failed" | "skipped";
+	/** Why a stage was skipped, when the reason is not simply `validate=false`. */
+	reason?: string;
+}
+
+/**
+ * Mutable sink that lets an error path report the validation that ACTUALLY ran.
+ *
+ * `runResolvedExecute` / `runResolvedApi` finish the gate and then do the real
+ * work, and the error envelope is built by a *different* function after the
+ * throw unwinds past them. Without this, a `routeros/*` fault on the run — which
+ * happens with both gate stages already green — got a reconstructed
+ * `result: "failed"` that erased the real outcome. The runner writes
+ * {@link ValidationTrace.validation} the moment the gate returns; the error
+ * builder prefers it over anything it could guess (GH#354, PR #356 review).
+ */
+export interface ValidationTrace {
+	/** The completed gate result, set once validation finishes. */
+	validation?: EnvelopeValidationMeta;
+	/**
+	 * The stage-1 verdict, recorded as soon as stage 1 returns — before stage 2
+	 * can throw. `warn` is an abstention, and an error envelope that reported it
+	 * as `passed` would be telling a consumer the analyzer read bytes it declined
+	 * to judge.
+	 */
+	offlineVerdict?: "pass" | "warn";
+}
+
 export interface EnvelopeValidationMeta {
 	enabled: boolean;
 	/** Validator identity, e.g. `/console/inspect` or `:put [:parse]`. */
@@ -118,6 +165,15 @@ export interface EnvelopeValidationMeta {
 	/** Semantic `/console/inspect` gate status, or not-applicable for script mode. */
 	semantic?: boolean | "not-applicable";
 	availableAttributes?: readonly string[];
+	/**
+	 * Per-stage detail for the gate described in
+	 * `docs/CONSTITUTION.md` → "Validation is the product".
+	 *
+	 * The flat `source` / `syntax` / `semantic` fields above stay the summary
+	 * view and keep their meaning; this is the breakdown behind them. Absent on
+	 * surfaces that have no RouterOS-command gate at all (`btest`).
+	 */
+	stages?: readonly EnvelopeValidationStage[];
 }
 
 export interface EnvelopeTimingMeta {

package/src/core/error-catalog.ts

@@ -234,6 +234,31 @@ export const errorCatalog: readonly ErrorCatalogEntry[] = [
 		summary: "A received MNDP datagram could not be decoded.",
 	},
 
+	// quickchr/*
+	{
+		code: "quickchr/package-unavailable",
+		summary: "The optional `@tikoci/quickchr` package is not installed.",
+	},
+	{
+		code: "quickchr/unsupported",
+		summary:
+			"The installed `@tikoci/quickchr` is too old or speaks a newer descriptor version than centrs understands.",
+	},
+	{
+		code: "quickchr/machine-not-found",
+		summary: "No quickchr machine is registered under that name.",
+	},
+	{
+		code: "quickchr/machine-stopped",
+		summary:
+			"The quickchr machine is not running, so it has no live connection facts.",
+	},
+	{
+		code: "quickchr/unsupported-via",
+		summary:
+			"The chosen `--via` has no usable service on the quickchr machine (not forwarded, unavailable, or SSH without batch-capable auth).",
+	},
+
 	// routeros/*
 	{
 		code: "routeros/api-fatal",
@@ -323,6 +348,11 @@ export const errorCatalog: readonly ErrorCatalogEntry[] = [
 		code: "routeros/unsupported-capability",
 		summary: "The chosen protocol does not support this command capability.",
 	},
+	{
+		code: "routeros/version-unsupported",
+		summary:
+			"The device's RouterOS version does not provide the operation this command needs.",
+	},
 
 	// settings/*
 	{
@@ -435,6 +465,11 @@ export const errorCatalog: readonly ErrorCatalogEntry[] = [
 		summary:
 			"Peer verification was disabled via --insecure (TLS / SSH host-key checks skipped).",
 	},
+	{
+		code: "transport/provider-trust",
+		summary:
+			"Peer verification is relaxed for a named-live-provider endpoint (a quickchr VM's self-signed TLS cert / ephemeral SSH host key), trusted by the provider's loopback-forward voucher.",
+	},
 	{
 		code: "transport/local-tool-missing",
 		summary:
@@ -475,6 +510,11 @@ export const errorCatalog: readonly ErrorCatalogEntry[] = [
 		code: "usage/invalid-concurrency",
 		summary: "The --concurrency value must be an integer >= 1.",
 	},
+	{
+		code: "usage/stdin-ignored",
+		summary:
+			"stdin was redirected but the input came from the positional argument, so anything piped in was not analyzed.",
+	},
 	{
 		code: "usage/fanout-not-supported",
 		summary:
@@ -514,7 +554,8 @@ export const errorCatalog: readonly ErrorCatalogEntry[] = [
 	},
 	{
 		code: "validation/syntax",
-		summary: "RouterOS rejected the command syntax during the :parse gate.",
+		summary:
+			"The command syntax was rejected by the validation gate — offline analysis, or the RouterOS :parse probe.",
 	},
 	{
 		code: "validation/unknown-attribute",

package/src/core/execute-command.ts

@@ -0,0 +1,148 @@
+/**
+ * The **script-vs-structured execution gate** and its canonical command shape.
+ *
+ * `execute.ts` owned this pair, which put every consumer of the gate — the MCP
+ * tool surface and `explain`'s offline analysis among them — one import away
+ * from the transport stack (`mac-telnet` -> `node:dgram`, `native-api` ->
+ * `node:crypto`). The functions themselves are pure string work, so they live in
+ * `src/core/` and `execute.ts` re-exports them: the public API, the locked
+ * contract table in `test/unit/execute-canonicalize-contract.test.ts`, and the
+ * gate's behavior are all unchanged by the move (#312).
+ *
+ * Nothing here reads settings, the filesystem, CDB, or a device. Changing that
+ * re-couples `explain`'s browser entry to the transport graph.
+ */
+
+export interface CanonicalExecuteCommand {
+	mode: "structured" | "script";
+	input: string;
+	path: string;
+	verb: string;
+	attributes: Record<string, string>;
+	queries: string[];
+}
+
+/**
+ * The **script-vs-structured execution gate** — centrs's load-bearing
+ * discriminator (with {@link isWriteShaped}) for which validation runs and
+ * whether the write-confirmation prompt fires. centrs owns this gate; the shared,
+ * prose-tolerant, multi-command canonicalizer that `rosetta` / `lsp-routeros-ts`
+ * publish is for *canonicalization*, never the structured-mode predicate —
+ * widening what counts as `structured` is a product regression. Behavior is
+ * pinned by `test/unit/execute-canonicalize-contract.test.ts`.
+ *
+ * centrs deliberately does **not** vendor the shared parser yet. Preconditions
+ * for adopting it: (1) that contract stays green (no gate widening); (2) the
+ * vendored file is clean under centrs's strict `tsconfig` (or explicitly
+ * quarantined with justification); (3) `lsp-routeros-ts` also vendors/consumes
+ * the same parser shape, so it is genuinely shared, not a premature first copy.
+ */
+export function canonicalizeExecuteCommand(
+	input: string,
+): CanonicalExecuteCommand {
+	const asScript = (): CanonicalExecuteCommand => ({
+		mode: "script",
+		input,
+		path: "",
+		verb: "",
+		attributes: {},
+		queries: [],
+	});
+
+	const trimmed = input.trim();
+	if (!trimmed.startsWith("/")) {
+		return asScript();
+	}
+
+	const tokens = tokenizeRouterOsCli(trimmed);
+	const pathToken = tokens[0] ?? "";
+	const pathParts = pathToken.split("/").filter(Boolean);
+	if (pathParts.length < 2) {
+		return asScript();
+	}
+
+	const verb = pathParts.at(-1) ?? "";
+	const path = `/${pathParts.slice(0, -1).join("/")}`;
+	const attributes: Record<string, string> = {};
+	const queries: string[] = [];
+	for (const token of tokens.slice(1)) {
+		// `[...]` subshell selectors (e.g. `numbers=[find ...]`) cannot be
+		// represented as a structured attribute map: the inner command contains
+		// spaces this tokenizer splits on, which would mangle a write-shaped
+		// command into corrupt key=value pairs. Fall back to the raw-script path
+		// so RouterOS evaluates the subshell with its real semantics.
+		if (token.includes("[") || token.includes("]")) {
+			return asScript();
+		}
+		if (token.startsWith("?")) {
+			queries.push(token);
+			continue;
+		}
+		const separator = token.indexOf("=");
+		if (separator <= 0) {
+			return asScript();
+		}
+		attributes[token.slice(0, separator)] = token.slice(separator + 1);
+	}
+
+	return {
+		mode: "structured",
+		input,
+		path,
+		verb,
+		attributes,
+		queries,
+	};
+}
+
+export function isWriteShaped(command: CanonicalExecuteCommand): boolean {
+	return (
+		command.mode === "structured" &&
+		["add", "set", "remove"].includes(command.verb)
+	);
+}
+
+function tokenizeRouterOsCli(input: string): string[] {
+	const tokens: string[] = [];
+	let current = "";
+	let quote: '"' | "'" | undefined;
+	let escaped = false;
+	for (const char of input) {
+		if (escaped) {
+			current += char;
+			escaped = false;
+			continue;
+		}
+		if (char === "\\") {
+			escaped = true;
+			continue;
+		}
+		if (quote) {
+			if (char === quote) {
+				quote = undefined;
+			} else {
+				current += char;
+			}
+			continue;
+		}
+		if (char === '"' || char === "'") {
+			quote = char;
+			continue;
+		}
+		if (/\s/.test(char)) {
+			if (current.length > 0) {
+				tokens.push(current);
+				current = "";
+			}
+			continue;
+		}
+		current += char;
+	}
+	if (escaped) {
+		current += "\\";
+	}
+	if (current.length > 0) {
+		tokens.push(current);
+	}
+	return tokens;
+}

package/src/core/inspect.ts

@@ -5,10 +5,16 @@
  * (path tokenizing, the comma-path join, node-type predicates, completion-name
  * extraction). This module is the single home so a third consumer — `api`, and a
  * future `explain`/`check` — reuses one grounded implementation instead of
- * forking a fourth. It deliberately holds only the transport-agnostic
- * *primitives*; each command composes its own discovery strategy on top (their
- * strategies differ: `retrieve` probes print/get support, `execute` unions
- * child-args with completions), so the strategy stays in the command.
+ * forking a fourth. It holds the transport-agnostic *primitives* plus the one
+ * discovery strategy that is shared verbatim: {@link inspectArgumentNames},
+ * command-level `request=child` only, used by `execute` and `api`. Strategies
+ * that differ stay in the command — `retrieve` probes print/get support and
+ * reads argument-level completion (`print,proplist` / `get,value-name`) with a
+ * child fallback.
+ *
+ * Command-level `request=completion` is not part of any argument-discovery
+ * strategy: on RouterOS 7.12.2 it hangs the REST handler and closes the
+ * native-API connection. See {@link inspectArgumentNames}.
  *
  * Grounding: the request modes mirror `tikoci/lsp-routeros-ts`
  * (`server/src/routeros.ts` `InspectRequest`). The behavioral facts (the array-
@@ -131,6 +137,32 @@ export async function inspectChildren(
 	)) as InspectChildItem[];
 }
 
+/**
+ * Return the argument names exposed by `request=child` at a command path.
+ *
+ * Do not supplement this with a command-level `request=completion`: RouterOS
+ * 7.12.2 hangs the REST handler and closes the native-API connection for that
+ * request shape, while `child` returns the complete argument list immediately.
+ * Argument-level completion (for example `print,proplist`) is a distinct probe
+ * and remains available through {@link inspectCompletions}.
+ */
+export async function inspectArgumentNames(
+	backend: InspectBackend,
+	tokens: readonly string[],
+): Promise<string[]> {
+	const children = await inspectChildren(backend, tokens);
+	return [
+		...new Set(
+			children
+				.filter(isArgumentNode)
+				.map((child) => child.name)
+				.filter(
+					(name): name is string => typeof name === "string" && name.length > 0,
+				),
+		),
+	].sort();
+}
+
 /** `request=completion` for a token path. */
 export async function inspectCompletions(
 	backend: InspectBackend,