@tikoci/centrs 0.1.1 → 0.1.3

package/src/execute.ts

@@ -9,6 +9,13 @@ import type {
 	Warning,
 } from "./core/envelope.ts";
 import { buildTip } from "./core/envelope.ts";
+import {
+	extractCompletionNames,
+	inspectChildren,
+	inspectCompletions,
+	isArgumentNode,
+	pathTokens,
+} from "./core/inspect.ts";
 import { mapRouterOsError } from "./core/routeros-errors.ts";
 import { CentrsError, serializeCentrsError } from "./errors.ts";
 import {
@@ -28,6 +35,7 @@ import {
 	effectiveHostCandidate,
 	isIpTransport,
 	isMacAddress,
+	loadEnvFileDefaults,
 	parseDuration,
 	parseResolvePolicy,
 	type ResolvedAuth,
@@ -132,20 +140,6 @@ export interface ResolvedExecuteRequest {
 	warnings: readonly Warning[];
 }
 
-interface InspectChildItem {
-	type?: string;
-	name?: string;
-	"node-type"?: string;
-}
-
-interface InspectCompletionItem {
-	type?: string;
-	name?: string;
-	completion?: string;
-	value?: string;
-	text?: string;
-}
-
 export async function execute(
 	request: ExecuteRequest,
 	env: Record<string, string | undefined> = Bun.env,
@@ -284,19 +278,29 @@ export async function runResolvedExecute(
 export async function resolveExecuteRequest(
 	request: ExecuteRequest,
 	env: Record<string, string | undefined>,
+	options: {
+		cdbResolution?: CdbResolution;
+		config?: Record<string, string | undefined>;
+	} = {},
 ): Promise<ResolvedExecuteRequest> {
 	validateExecuteRequestShape(request);
 	const canonical = canonicalizeExecuteCommand(request.command);
-	const cdbResolution = await resolveCdb(
-		{
-			targetInput: request.targetInput,
-			cdbFile: request.cdbFile,
-			cdbPassword: request.cdbPassword,
-		},
-		env,
-	);
-	const via = resolveExecuteProtocol(request, env, cdbResolution);
-	const format = resolveFormat(request, env);
+	const config = options.config ?? (await loadEnvFileDefaults(env));
+	// Fan-out passes the pre-resolved CDB record for a member (the CDB is loaded
+	// once in `expandCdbSelection`); single-target resolves it here.
+	const cdbResolution =
+		options.cdbResolution ??
+		(await resolveCdb(
+			{
+				targetInput: request.targetInput,
+				cdbFile: request.cdbFile,
+				cdbPassword: request.cdbPassword,
+			},
+			env,
+			config,
+		));
+	const via = resolveExecuteProtocol(request, env, cdbResolution, config);
+	const format = resolveFormat(request, env, config);
 	const validate = resolveBooleanSetting(
 		request.validate,
 		env,
@@ -304,18 +308,22 @@ export async function resolveExecuteRequest(
 		true,
 		"validate",
 		cdbResolution?.overrides.validate,
+		config,
 	);
 	const timeoutMs = resolveTimeoutSetting(
 		request.timeout,
 		env,
 		via.value,
 		cdbResolution?.overrides.timeoutMs,
+		config,
 	);
 	const maxResultsBytes = resolveOptionalIntegerSetting(
 		request.maxResultsBytes,
 		env,
 		"CENTRS_MAX_RESULTS",
 		"max-results",
+		undefined,
+		config,
 	);
 	const macResolution = isIpTransport(via.value)
 		? await resolveMacTarget({
@@ -323,7 +331,10 @@ export async function resolveExecuteRequest(
 				targetInput: request.targetInput,
 				cdbTarget: cdbResolution?.target,
 				env,
-				policy: parseResolvePolicy(request.resolve ?? env["CENTRS_RESOLVE"]),
+				config,
+				policy: parseResolvePolicy(
+					request.resolve ?? env["CENTRS_RESOLVE"] ?? config["CENTRS_RESOLVE"],
+				),
 				operation: "execute",
 			})
 		: undefined;
@@ -337,6 +348,7 @@ export async function resolveExecuteRequest(
 		env,
 		via.value,
 		cdbResolution,
+		config,
 	);
 	const auth = resolveAuth(
 		{
@@ -346,6 +358,7 @@ export async function resolveExecuteRequest(
 		},
 		env,
 		cdbResolution,
+		config,
 	);
 	const insecure = resolveBooleanSetting(
 		request.insecure,
@@ -354,6 +367,7 @@ export async function resolveExecuteRequest(
 		false,
 		"insecure",
 		cdbResolution?.overrides.insecure,
+		config,
 	);
 
 	return {
@@ -373,6 +387,79 @@ export async function resolveExecuteRequest(
 	};
 }
 
+export interface ExecuteGlobalContext {
+	via: RouterOsProtocol;
+	write: boolean;
+	summary: ExecuteRequestSummary;
+	settings: CommonSettingsMeta;
+}
+
+/**
+ * Resolve the target-independent settings (protocol, format, validate, timeout,
+ * max-results) for a fan-out's outer `meta.operation.request` summary and its
+ * transport-aware concurrency default. No CDB record is consulted; the global
+ * `--via` (default `native-api`) decides the summary and concurrency base. Also
+ * canonicalizes the command once so write-ness is known before any target runs.
+ */
+export function resolveExecuteGlobalContext(
+	request: ExecuteRequest,
+	env: Record<string, string | undefined>,
+	config: Record<string, string | undefined> = {},
+): ExecuteGlobalContext {
+	validateExecuteRequestShape(request);
+	const canonical = canonicalizeExecuteCommand(request.command);
+	const via = resolveExecuteProtocol(request, env, undefined, config);
+	const format = resolveFormat(request, env, config);
+	const validate = resolveBooleanSetting(
+		request.validate,
+		env,
+		"CENTRS_VALIDATE",
+		true,
+		"validate",
+		undefined,
+		config,
+	);
+	const timeoutMs = resolveTimeoutSetting(
+		request.timeout,
+		env,
+		via.value,
+		undefined,
+		config,
+	);
+	const maxResultsBytes = resolveOptionalIntegerSetting(
+		request.maxResultsBytes,
+		env,
+		"CENTRS_MAX_RESULTS",
+		"max-results",
+		undefined,
+		config,
+	);
+	return {
+		via: via.value,
+		write: isWriteShaped(canonical),
+		summary: {
+			command: request.command,
+			canonical,
+			write: isWriteShaped(canonical),
+			yes: request.yes ?? false,
+			validate: validate.value,
+			verbose: request.verbose ?? false,
+			timeoutMs: timeoutMs.value,
+			format: format.value,
+			maxResultsBytes: maxResultsBytes?.value,
+		},
+		settings: {
+			via: toCoreSource(via.source),
+			timeoutMs: toCoreSource(timeoutMs.source),
+			format: toCoreSource(format.source),
+			validate: toCoreSource(validate.source),
+			maxResultsBytes: maxResultsBytes
+				? toCoreSource(maxResultsBytes.source)
+				: undefined,
+		},
+	};
+}
+
 export function buildExecuteErrorEnvelope(
 	request: ExecuteRequest,
 	error: unknown,
@@ -735,24 +822,18 @@ async function inspectExecuteAttributes(
 	resolved: ResolvedExecuteRequest,
 	backend: ProtocolAdapter,
 ): Promise<string[]> {
-	const commandPath = inspectPath([
+	const commandTokens = [
 		...pathTokens(resolved.canonical.path),
 		resolved.canonical.verb,
-	]);
-	const children = (await backend.inspect(
-		"child",
-		commandPath,
-	)) as InspectChildItem[];
+	];
+	const children = await inspectChildren(backend, commandTokens);
 	const childAttributes = children
 		.filter(isArgumentNode)
 		.map((child) => child.name)
 		.filter(
 			(name): name is string => typeof name === "string" && name.length > 0,
 		);
-	const completionRows = (await backend.inspect(
-		"completion",
-		commandPath,
-	)) as InspectCompletionItem[];
+	const completionRows = await inspectCompletions(backend, commandTokens);
 	return [
 		...new Set([...childAttributes, ...extractCompletionNames(completionRows)]),
 	].sort();
@@ -769,16 +850,6 @@ async function runCommand(
 		return backend.execute({ path: "", command: "", script: resolved.command });
 	}
 	if (resolved.canonical.mode === "script") {
-		if (resolved.via.value === "native-api") {
-			throw new CentrsError({
-				code: "transport/unsupported-operation",
-				summary:
-					"The native API execute path requires a slash-prefixed RouterOS command.",
-				remediation:
-					"Use a path-shaped command such as `/system/identity/set name=x`, or pin `--via rest-api` for `/rest/execute` script mode.",
-				context: { via: resolved.via.value, command: resolved.command },
-			});
-		}
 		return backend.execute({ path: "", command: "", script: resolved.command });
 	}
 	return backend.execute({
@@ -819,7 +890,9 @@ async function assertWriteConfirmed(
 	});
 }
 
-async function promptForWriteConfirmation(prompt: string): Promise<boolean> {
+export async function promptForWriteConfirmation(
+	prompt: string,
+): Promise<boolean> {
 	process.stderr.write(prompt);
 	for await (const chunk of Bun.stdin.stream()) {
 		const answer = new TextDecoder().decode(chunk).trim().toLowerCase();
@@ -832,8 +905,9 @@ function resolveExecuteProtocol(
 	request: ExecuteRequest,
 	env: Record<string, string | undefined>,
 	cdb?: CdbResolution,
+	config: Record<string, string | undefined> = {},
 ): ResolvedSetting<RouterOsProtocol> {
-	const defaultVia = isUnresolvedMacTarget(request, env, cdb)
+	const defaultVia = isUnresolvedMacTarget(request, env, cdb, config)
 		? "mac-telnet"
 		: "native-api";
 	const via = resolveStringSetting(
@@ -844,6 +918,7 @@ function resolveExecuteProtocol(
 		"via",
 		undefined,
 		cdb?.overrides.via,
+		config,
 	);
 	if (!via) {
 		throw new CentrsError({
@@ -888,8 +963,13 @@ function isUnresolvedMacTarget(
 	request: ExecuteRequest,
 	env: Record<string, string | undefined>,
 	cdb?: CdbResolution,
+	config: Record<string, string | undefined> = {},
 ): boolean {
-	if (request.via !== undefined || env["CENTRS_VIA"] !== undefined) {
+	if (
+		request.via !== undefined ||
+		env["CENTRS_VIA"] !== undefined ||
+		config["CENTRS_VIA"] !== undefined
+	) {
 		return false;
 	}
 	// Decide the default transport from the *effective* target (host >
@@ -901,6 +981,7 @@ function isUnresolvedMacTarget(
 		targetInput: request.targetInput,
 		cdbTarget: cdb?.target,
 		env,
+		config,
 	});
 	return candidate ? isMacAddress(candidate) : false;
 }
@@ -908,6 +989,7 @@ function isUnresolvedMacTarget(
 function resolveFormat(
 	request: ExecuteRequest,
 	env: Record<string, string | undefined>,
+	config: Record<string, string | undefined> = {},
 ): ResolvedSetting<ExecuteOutputFormat> {
 	return resolveStringSetting(
 		request.format,
@@ -916,6 +998,8 @@ function resolveFormat(
 		"text",
 		"format",
 		parseOutputFormat,
+		undefined,
+		config,
 	) as ResolvedSetting<ExecuteOutputFormat>;
 }
 
@@ -941,6 +1025,7 @@ function resolveTimeoutSetting(
 	env: Record<string, string | undefined>,
 	via: RouterOsProtocol,
 	commentKv?: ResolvedSetting<number>,
+	config: Record<string, string | undefined> = {},
 ): ResolvedSetting<number> {
 	const resolved = resolveStringSetting(
 		timeout === undefined ? undefined : String(timeout),
@@ -961,6 +1046,7 @@ function resolveTimeoutSetting(
 			return parsed;
 		},
 		commentKv,
+		config,
 	);
 	if (!resolved) {
 		throw new Error("timeout resolution produced no value");
@@ -1299,28 +1385,6 @@ function syntaxCause(error: unknown): unknown {
 	return error;
 }
 
-function pathTokens(path: string): string[] {
-	return path.split("/").filter(Boolean);
-}
-
-function inspectPath(tokens: readonly string[]): string {
-	return tokens.join(",");
-}
-
-function isArgumentNode(child: InspectChildItem): boolean {
-	return child.type === "arg" || child["node-type"] === "arg";
-}
-
-function extractCompletionNames(
-	rows: readonly InspectCompletionItem[],
-): string[] {
-	return rows
-		.flatMap((row) => [row.completion, row.name, row.value, row.text])
-		.filter((value): value is string => typeof value === "string")
-		.map((value) => value.replace(/=.*$/, "").trim())
-		.filter((value) => value.length > 0);
-}
-
 function parseOutputFormat(value: string): ExecuteOutputFormat {
 	if (executeOutputFormats.includes(value as ExecuteOutputFormat)) {
 		return value as ExecuteOutputFormat;

package/src/index.ts

@@ -1,5 +1,52 @@
 export const centrsVersion = "0.1.0";
 
+export {
+	type ApiEnvelope,
+	type ApiErrorEnvelope,
+	type ApiMethod,
+	type ApiOperationMeta,
+	type ApiOutputFormat,
+	type ApiRequest,
+	type ApiRequestSummary,
+	type ApiStreamMeta,
+	type ApiStreamStopReason,
+	type ApiStreamSummary,
+	type ApiSuccessEnvelope,
+	api,
+	apiEnvelope,
+	apiListen,
+	apiMethods,
+	apiOutputFormats,
+	apiRequestSummaryFromRequest,
+	buildApiBody,
+	buildApiErrorEnvelope,
+	buildApiErrorEnvelopeFromResolved,
+	buildApiQuery,
+	buildProtocolApiRequest,
+	isApiMutating,
+	mapMethodToVerb,
+	type NormalizedApiEndpoint,
+	normalizeApiEndpoint,
+	parseApiMethod,
+	type ResolvedApiRequest,
+	renderApiEnvelope,
+	renderApiStreamLine,
+	resolveApiRequest,
+	runResolvedApi,
+	validateApiRequestShape,
+} from "./api.ts";
+export {
+	type ApiFanoutData,
+	type ApiFanoutEnvelope,
+	type ApiFanoutErrorEnvelope,
+	type ApiFanoutInternals,
+	type ApiFanoutOperationMeta,
+	type ApiFanoutOptions,
+	type ApiSelectionSummary,
+	apiFanout,
+	buildApiFanoutErrorEnvelope,
+	renderApiFanoutEnvelope,
+} from "./api-fanout.ts";
 export {
 	BTEST_CLIENT_CSV_HEADER,
 	BTEST_SERVER_CSV_HEADER,
@@ -41,6 +88,36 @@ export {
 	type SettingSourceKind,
 	type Warning,
 } from "./core/envelope.ts";
+export {
+	buildFanoutEnvelope,
+	buildFanoutResolveFailure,
+	commonVia,
+	FANOUT_BACKOFF_BASE_MS,
+	FANOUT_CONCURRENCY_DEFAULTS,
+	FANOUT_MAX_RETRIES,
+	FANOUT_RETRYABLE_CODES,
+	fanoutExitCode,
+	isRetryableFanoutError,
+	resolveFanoutConcurrency,
+	runBoundedPool,
+	runFanout,
+	runWithRetry,
+	summarizeFanout,
+} from "./core/fanout.ts";
+export {
+	extractCompletionNames,
+	type InspectBackend,
+	type InspectChildItem,
+	type InspectCompletionItem,
+	type InspectRequestKind,
+	inspectChildren,
+	inspectChildrenOrEmpty,
+	inspectCompletions,
+	inspectPath,
+	isArgumentNode,
+	isCommandNode,
+	pathTokens,
+} from "./core/inspect.ts";
 export {
 	encodeMndpPacket,
 	MNDP_BROADCAST_ADDRESS,
@@ -115,6 +192,7 @@ export {
 	type DevicesShowEnvelopeData,
 	type DevicesShowItem,
 	type DevicesWarning,
+	type DevicesWhereClause,
 	defaultCdbPath,
 	devicesOutputFormats,
 	editInteractiveOnlyError,
@@ -170,6 +248,7 @@ export {
 	canonicalizeExecuteCommand,
 	type ExecuteEnvelope,
 	type ExecuteErrorEnvelope,
+	type ExecuteGlobalContext,
 	type ExecuteOperationMeta,
 	type ExecuteOutputFormat,
 	type ExecuteRequest,
@@ -180,16 +259,32 @@ export {
 	executeOutputFormats,
 	isWriteShaped,
 	renderExecuteEnvelope,
+	resolveExecuteGlobalContext,
 	resolveExecuteRequest,
 	runResolvedExecute,
 	validateExecuteRequestShape,
 } from "./execute.ts";
 export {
+	buildExecuteFanoutErrorEnvelope,
+	type ExecuteFanoutData,
+	type ExecuteFanoutEnvelope,
+	type ExecuteFanoutErrorEnvelope,
+	type ExecuteFanoutInternals,
+	type ExecuteFanoutOperationMeta,
+	type ExecuteFanoutOptions,
+	type ExecuteSelectionSummary,
+	executeFanout,
+	renderExecuteFanoutEnvelope,
+} from "./execute-fanout.ts";
+export {
+	type ApiVerb,
 	createProtocolAdapter,
 	getProtocolPlan,
 	type ProtocolAdapter,
 	type ProtocolAdapterCapabilities,
 	type ProtocolAdapterConfig,
+	type ProtocolApiRequest,
+	type ProtocolApiResult,
 	type ProtocolCapability,
 	type ProtocolExecuteRequest,
 	type ProtocolExecuteResult,
@@ -201,27 +296,48 @@ export {
 	type RouterOsProtocol,
 } from "./protocols/index.ts";
 export {
+	type AltitudeType,
 	applyCommentKv,
+	type BboxPredicate,
 	type CdbGroupExpansion,
 	type CdbGroupResolveInput,
 	type CdbGroupTarget,
 	type CdbResolution,
 	type CdbResolveInput,
+	type CdbSelectionExpansion,
+	type CdbSelectionMember,
+	type CdbSelectionResolveInput,
+	type CommentKvGeoKey,
 	type CommentKvKey,
 	type CommentKvLayer,
 	type CommentKvOverrides,
 	type CommentKvResult,
 	type CommentKvUpdate,
 	type CommentKvWarning,
+	canonicalizeGeoKey,
 	coerceCommentKv,
 	commentKvAllowlist,
+	commentKvGeoKeys,
 	commentKvReservedKeys,
+	type DeviceLocation,
 	defaultPortForScheme,
+	deviceLocation,
 	expandCdbGroup,
+	expandCdbSelection,
+	isDefaultRecordTarget,
+	type NearPredicate,
+	type ParsedGpsTuple,
+	parseAltitude,
+	parseAltitudeType,
+	parseBbox,
 	parseBoolean,
 	parseCommentKv,
 	parseDuration,
+	parseGpsTuple,
 	parseHostCandidate,
+	parseLatLon,
+	parseNear,
+	parseRawCommentFacts,
 	type ResolvedAuth,
 	type ResolvedSetting,
 	type ResolvedTarget,
@@ -235,7 +351,9 @@ export {
 	resolveOptionalIntegerSetting,
 	resolveStringSetting,
 	resolveTarget,
+	type SelectionWhereClause,
 	type TargetResolveInput,
+	type TargetSelection,
 	toCoreSource,
 } from "./resolver/index.ts";
 export {
@@ -262,22 +380,47 @@ export {
 } from "./retrieve.ts";
 export {
 	buildRetrieveFanoutErrorEnvelope,
-	isRetryableFanoutError,
-	RETRIEVE_FANOUT_BACKOFF_BASE_MS,
-	RETRIEVE_FANOUT_CONCURRENCY_DEFAULTS,
-	RETRIEVE_FANOUT_MAX_RETRIES,
-	RETRIEVE_FANOUT_RETRYABLE_CODES,
 	type RetrieveFanoutData,
 	type RetrieveFanoutEnvelope,
 	type RetrieveFanoutErrorEnvelope,
+	type RetrieveFanoutInternals,
 	type RetrieveFanoutOperationMeta,
-	type RetrieveGroupInternals,
+	type RetrieveFanoutOptions,
+	type RetrieveSelectionSummary,
 	renderRetrieveFanoutEnvelope,
-	resolveFanoutConcurrency,
+	retrieveFanout,
 	retrieveGroup,
-	runBoundedPool,
-	summarizeFanout,
 } from "./retrieve-fanout.ts";
+export {
+	buildSettingsErrorEnvelope,
+	renderSettingsEnvelope,
+	type SettingsCommand,
+	type SettingsDefaultDeviceSummary,
+	type SettingsEnvelope,
+	type SettingsErrorEnvelope,
+	type SettingsGetArgs,
+	type SettingsGetData,
+	type SettingsKeyDef,
+	type SettingsKeyEntry,
+	type SettingsOperationMeta,
+	type SettingsOutputFormat,
+	type SettingsPrintArgs,
+	type SettingsPrintData,
+	type SettingsResetArgs,
+	type SettingsResetData,
+	type SettingsSetArgs,
+	type SettingsSetData,
+	type SettingsSuccessEnvelope,
+	type SettingsUnrecognizedEntry,
+	type SettingsValue,
+	settingsGet,
+	settingsManagedKeys,
+	settingsOutputFormats,
+	settingsPrint,
+	settingsRefusedKeys,
+	settingsReset,
+	settingsSet,
+} from "./settings.ts";
 export {
 	buildSshTerminalArgv,
 	buildTerminalErrorEnvelope,
@@ -290,6 +433,7 @@ export {
 export {
 	buildTransferErrorEnvelope,
 	FILE_READ_CHUNK_BYTES,
+	isTransferWriteVerb,
 	normalizeRemotePath,
 	REST_FILE_WRITE_CAP_BYTES,
 	renderTransferEnvelope,
@@ -312,6 +456,19 @@ export {
 	transferVerbs,
 	validateTransferRequestShape,
 } from "./transfer.ts";
+export {
+	buildTransferFanoutErrorEnvelope,
+	renderTransferFanoutEnvelope,
+	type TransferFanoutData,
+	type TransferFanoutEnvelope,
+	type TransferFanoutErrorEnvelope,
+	type TransferFanoutInternals,
+	type TransferFanoutOperationMeta,
+	type TransferFanoutOptions,
+	type TransferFanoutRequestSummary,
+	type TransferSelectionSummary,
+	transferFanout,
+} from "./transfer-fanout.ts";
 
 import { plannedProtocols, type RouterOsProtocol } from "./protocols/index.ts";
 

package/src/mcp/config.ts

@@ -46,16 +46,26 @@ export interface ResolveMcpConfigArgs {
 	cdbPassword?: string;
 	allowAdhocTargets?: boolean;
 	env?: Record<string, string | undefined>;
+	/**
+	 * The `centrs.env` config tier (`src/resolver/config-file.ts`), loaded by
+	 * the caller — `resolveMcpConfig` itself stays synchronous so it can keep
+	 * serving as a default-parameter value (`server.ts`). `CENTRS_CDB_PASSWORD`
+	 * deliberately never reads it, same as `resolveAuth`'s credential fields.
+	 */
+	config?: Record<string, string | undefined>;
 }
 
 export function resolveMcpConfig(
 	args: ResolveMcpConfigArgs = {},
 ): CentrsMcpConfig {
 	const env = args.env ?? Bun.env;
-	const explicitPath = args.cdbFile ?? env[ENV_CDB_FILE] ?? undefined;
+	const config = args.config ?? {};
+	const explicitPath =
+		args.cdbFile ?? env[ENV_CDB_FILE] ?? config[ENV_CDB_FILE] ?? undefined;
 	const cdbFile = explicitPath ?? defaultCdbPath(env);
 	const allowAdhocTargets =
-		args.allowAdhocTargets ?? env[ENV_ALLOW_ADHOC] === "1";
+		args.allowAdhocTargets ??
+		(env[ENV_ALLOW_ADHOC] ?? config[ENV_ALLOW_ADHOC]) === "1";
 	return {
 		cdbFile,
 		cdbFileExplicit: explicitPath !== undefined,