@tikoci/centrs 0.1.2 → 0.1.4

package/src/index.ts

@@ -17,6 +17,7 @@ export {
 	apiListen,
 	apiMethods,
 	apiOutputFormats,
+	apiRequestSummaryFromRequest,
 	buildApiBody,
 	buildApiErrorEnvelope,
 	buildApiErrorEnvelopeFromResolved,
@@ -26,6 +27,7 @@ export {
 	mapMethodToVerb,
 	type NormalizedApiEndpoint,
 	normalizeApiEndpoint,
+	parseApiMethod,
 	type ResolvedApiRequest,
 	renderApiEnvelope,
 	renderApiStreamLine,
@@ -33,6 +35,18 @@ export {
 	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,
@@ -75,13 +89,18 @@ export {
 	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";
@@ -99,6 +118,24 @@ export {
 	isCommandNode,
 	pathTokens,
 } from "./core/inspect.ts";
+export {
+	assertCapability,
+	type CapabilityRequirement,
+	checkCapability,
+	compareRouterOsVersion,
+	type DeviceVersion,
+	type DeviceVersionSource,
+	type PreflightState,
+	type PreflightVerdict,
+	parseRouterOsVersion,
+	probeDeviceVersion,
+	type RouterOsVersionParts,
+	type RouterOsVersionRange,
+	renderSupportedRanges,
+	routerOsVersionAtLeast,
+	versionFactFromComment,
+	versionInRange,
+} from "./core/preflight.ts";
 export {
 	encodeMndpPacket,
 	MNDP_BROADCAST_ADDRESS,
@@ -173,6 +210,7 @@ export {
 	type DevicesShowEnvelopeData,
 	type DevicesShowItem,
 	type DevicesWarning,
+	type DevicesWhereClause,
 	defaultCdbPath,
 	devicesOutputFormats,
 	editInteractiveOnlyError,
@@ -228,6 +266,7 @@ export {
 	canonicalizeExecuteCommand,
 	type ExecuteEnvelope,
 	type ExecuteErrorEnvelope,
+	type ExecuteGlobalContext,
 	type ExecuteOperationMeta,
 	type ExecuteOutputFormat,
 	type ExecuteRequest,
@@ -238,10 +277,207 @@ 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";
+// The lexer's own names are module-scoped and read naturally there; at the
+// package root they need the `Explain` prefix every other explain export
+// carries — a bare `Argument` says nothing about which of centrs's surfaces it
+// belongs to. Aliasing at the re-export is the existing pattern here (see
+// `occurrences as explainOccurrences` below).
+//
+// `ExplainArgument` and `ExplainArgumentToken` are the same SHAPE in two
+// coordinate spaces: this one is what `lexArguments` returns, with spans
+// relative to the statement it was handed; the `Token` is that rebased into
+// document space by `explainCommand`. A consumer reading `explainCommand`'s
+// result wants the latter.
+export {
+	type Argument as ExplainArgument,
+	type ArgumentKind as ExplainArgumentKind,
+	type ArgumentReading as ExplainArgumentReading,
+	type ArgumentsRead as ExplainArgumentsRead,
+	type ArgumentsUnread as ExplainArgumentsUnread,
+	lexArguments as lexExplainArguments,
+	lexValueAnchors as lexExplainValueAnchors,
+	type ValueAnchor as ExplainValueAnchor,
+	type ValueAnchorKind as ExplainValueAnchorKind,
+	type ValueAnchorReading as ExplainValueAnchorReading,
+} from "./explain/args.ts";
+export {
+	DIRECTIVE_BODY,
+	HEAD_SCOPED_ARG_NAMES,
+	isScopeBrace,
+	matchBrace,
+	SCOPE_ARG_NAMES,
+	type ScopeBlock,
+	scopeBlocks,
+	scopeBodies,
+	scopeNameAt,
+} from "./explain/blocks.ts";
+export {
+	analyzeCoordinates,
+	byteSpanToRange,
+	byteToPosition,
+	type CharRun,
+	type CoordinateAnalysis,
+	coordinateDefects,
+	type Position,
+	positionToByte,
+	type Range,
+	runAtByte,
+	SUB,
+} from "./explain/coordinates.ts";
+export {
+	type Defect,
+	type DefectCode,
+	defectAt,
+	hasStructuralDefect,
+	isPositionalFact,
+	mergeDefects,
+	rebaseDefects,
+} from "./explain/defects.ts";
+export {
+	type DocumentAnalysis,
+	type Resolution,
+	resolveDocument,
+	resolveStatements,
+	type Span,
+	type StatementAnalysis,
+	type StatementResolution,
+} from "./explain/pathresolve.ts";
+export {
+	maskComments,
+	type QuotedStringScan,
+	type Segment,
+	type SegmentResult,
+	scanQuotedString,
+	segmentStatements,
+} from "./explain/segment.ts";
+export {
+	HIGHLIGHT_CLASS,
+	resolveSymbols,
+	type SymbolAnalysis,
+	type SymbolClass,
+	type SymbolOccurrence,
+	type SymbolRole,
+} from "./explain/symbols.ts";
+export type {
+	ExplainApiCandidateTransport,
+	ExplainExecuteTransport,
+	ExplainRestMethod,
+	ExplainRestRequest,
+	ExplainTransport,
+	ExplainTransportClassification,
+	ExplainUnknownTransport,
+} from "./explain/transport.ts";
+export {
+	VALUE_SHAPES,
+	type ValueContext as ExplainValueContext,
+	type ValueShape as ExplainValueShape,
+	type ValueShapeOptions as ExplainValueShapeOptions,
+	valueShapeHints as explainValueShapeHints,
+} from "./explain/values.ts";
+export {
+	type DocumentVerbSplit,
+	describeStatement,
+	isDirective,
+	type RunToken,
+	resolveVerb,
+	resolveVerbs,
+	runTokens,
+	type Sep,
+	type Split,
+	SUBMENU_DIRECTIVES,
+	splitRun,
+	VERBS,
+	type VerbAnalysis,
+	type VerbResolution,
+	type VerbSplit,
+	type VerbSplitCommandReading,
+	type VerbSplitMenuReading,
+	type VerbSplitRefusal,
+} from "./explain/verbsplit.ts";
+export {
+	classifyVerb,
+	containsWrite,
+	type Occurrence,
+	type OccurrenceClass,
+	// `occurrences` is too generic for the library root; the module-local name
+	// stays short because inside `write.ts` there is only one kind.
+	occurrences as explainOccurrences,
+	READ_VERBS,
+	ROOT_CMDS,
+	ROOT_DYNAMIC,
+	ROOT_WRITE,
+	WRITE_VERBS,
+	type WriteAnalysis,
+	type WriteVerdict,
+} from "./explain/write.ts";
+export {
+	buildExplainErrorEnvelope,
+	buildExplainFacetTip,
+	type ExplainArguments,
+	type ExplainArgumentToken,
+	type ExplainBlock,
+	type ExplainCanonical,
+	type ExplainCommandOptions,
+	type ExplainCommandReading,
+	type ExplainData,
+	type ExplainDiagnostic,
+	type ExplainEnvelope,
+	type ExplainEnvelopeOptions,
+	type ExplainErrorEnvelope,
+	type ExplainEvidence,
+	type ExplainFailOn,
+	type ExplainInput,
+	type ExplainMenuReading,
+	type ExplainOperationMeta,
+	type ExplainOutputFormat,
+	type ExplainPositionMapEntry,
+	type ExplainReading,
+	type ExplainRefusal,
+	type ExplainResolution,
+	type ExplainSeverity,
+	type ExplainSpan,
+	type ExplainSpanClass,
+	type ExplainSpanRange,
+	type ExplainStatement,
+	type ExplainStatementFacts,
+	type ExplainStructure,
+	type ExplainSubcommand,
+	type ExplainSubcommandFacts,
+	type ExplainSymbolClass,
+	type ExplainSymbolOccurrence,
+	type ExplainSymbols,
+	type ExplainToken,
+	type ExplainTokenClass,
+	type ExplainValueFacts,
+	type ExplainValueOccurrence,
+	type ExplainValueShapeFact,
+	type ExplainValues,
+	type ExplainValueTypeFact,
+	type ExplainVerdict,
+	explainCommand,
+	explainEnvelope,
+	explainExitCode,
+	explainFailOnLevels,
+	explainOutputFormats,
+	renderExplainEnvelope,
+} from "./explain.ts";
 export {
 	type ApiVerb,
 	createProtocolAdapter,
@@ -262,27 +498,45 @@ export {
 	type RouterOsProtocol,
 } from "./protocols/index.ts";
 export {
+	type AltitudeType,
 	applyCommentKv,
+	type BboxPredicate,
 	type CdbGroupExpansion,
 	type CdbGroupResolveInput,
 	type CdbGroupTarget,
 	type CdbResolution,
 	type CdbResolveInput,
+	type CommentKvGeoKey,
 	type CommentKvKey,
 	type CommentKvLayer,
 	type CommentKvOverrides,
 	type CommentKvResult,
 	type CommentKvUpdate,
 	type CommentKvWarning,
+	canonicalizeGeoKey,
 	coerceCommentKv,
 	commentKvAllowlist,
+	commentKvGeoKeys,
 	commentKvReservedKeys,
+	type DeviceLocation,
 	defaultPortForScheme,
+	deviceLocation,
 	expandCdbGroup,
+	expandSelection,
+	isDefaultRecordTarget,
+	type NearPredicate,
+	type ParsedGpsTuple,
+	parseAltitude,
+	parseAltitudeType,
+	parseBbox,
 	parseBoolean,
 	parseCommentKv,
 	parseDuration,
+	parseGpsTuple,
 	parseHostCandidate,
+	parseLatLon,
+	parseNear,
+	parseRawCommentFacts,
 	type ResolvedAuth,
 	type ResolvedSetting,
 	type ResolvedTarget,
@@ -296,7 +550,12 @@ export {
 	resolveOptionalIntegerSetting,
 	resolveStringSetting,
 	resolveTarget,
+	type SelectionExpansion,
+	type SelectionMember,
+	type SelectionResolveInput,
+	type SelectionWhereClause,
 	type TargetResolveInput,
+	type TargetSelection,
 	toCoreSource,
 } from "./resolver/index.ts";
 export {
@@ -326,11 +585,44 @@ export {
 	type RetrieveFanoutData,
 	type RetrieveFanoutEnvelope,
 	type RetrieveFanoutErrorEnvelope,
+	type RetrieveFanoutInternals,
 	type RetrieveFanoutOperationMeta,
-	type RetrieveGroupInternals,
+	type RetrieveFanoutOptions,
+	type RetrieveSelectionSummary,
 	renderRetrieveFanoutEnvelope,
+	retrieveFanout,
 	retrieveGroup,
 } 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,
@@ -343,6 +635,7 @@ export {
 export {
 	buildTransferErrorEnvelope,
 	FILE_READ_CHUNK_BYTES,
+	isTransferWriteVerb,
 	normalizeRemotePath,
 	REST_FILE_WRITE_CAP_BYTES,
 	renderTransferEnvelope,
@@ -365,6 +658,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,

package/src/mcp/tools.ts

@@ -33,6 +33,8 @@ import {
 	isWriteShaped,
 	validateExecuteEnvelope,
 } from "../execute.ts";
+import type { CommentKvUpdate } from "../resolver/comment-kv.ts";
+import { parseBbox, parseNear } from "../resolver/geo.ts";
 import { parseDuration } from "../resolver/settings.ts";
 import { buildRetrieveErrorEnvelope, retrieve } from "../retrieve.ts";
 import {
@@ -416,6 +418,24 @@ export const devicesInputShape = {
 		.describe(
 			"Group filter for op=list; first-class group field for op=add/set.",
 		),
+	where: z
+		.array(z.string())
+		.optional()
+		.describe(
+			"op=list device-class filters `attr=value` (repeatable, AND-combined; e.g. board=RB5009 or lat=37.7749).",
+		),
+	near: z
+		.string()
+		.optional()
+		.describe(
+			"op=list geo filter `<lat>,<lon>,<radius>` (lat-first; radius m/km/mi/ft, bare = km).",
+		),
+	bbox: z
+		.string()
+		.optional()
+		.describe(
+			"op=list geo filter `<south>,<west>,<north>,<east>` (lat-first bounding box).",
+		),
 	user: z.string().optional().describe("CDB username for op=add/set."),
 	password: z
 		.string()
@@ -454,6 +474,30 @@ export const devicesInputShape = {
 		.boolean()
 		.optional()
 		.describe("For op=set, reject comment keys outside the allowlist."),
+	lat: z
+		.number()
+		.optional()
+		.describe(
+			"Latitude in decimal degrees (-90..90) for op=add/set; a comment-kv fact, paired with lon (issue #146).",
+		),
+	lon: z
+		.number()
+		.optional()
+		.describe(
+			"Longitude in decimal degrees (-180..180) for op=add/set; a comment-kv fact, paired with lat.",
+		),
+	altitude: z
+		.number()
+		.optional()
+		.describe(
+			"Altitude in meters for op=add/set (may be negative); a comment-kv fact.",
+		),
+	altitudeType: z
+		.enum(["MSL", "AGL"])
+		.optional()
+		.describe(
+			"Vertical datum for altitude, op=add/set (default MSL when altitude is set).",
+		),
 	confirm: z
 		.boolean()
 		.optional()
@@ -478,6 +522,56 @@ function requireDevicesTarget(
 	});
 }
 
+/**
+ * Lower the typed `lat`/`lon`/`altitude`/`altitudeType` MCP args into comment-kv
+ * updates — the same core surface the CLI's `--lat`/`--lon`/`--gps` flags lower
+ * into (`src/cli/devices.ts`). Light touch: no alias handling here (the MCP
+ * schema only exposes the canonical field names), range/enum/pairing
+ * validation happens once in `validateCommentKvUpdates` (`src/devices.ts`).
+ */
+function buildGeoUpdates(args: DevicesArgs): CommentKvUpdate[] {
+	const updates: CommentKvUpdate[] = [];
+	if (args.lat !== undefined) {
+		updates.push({ key: "lat", value: String(args.lat) });
+	}
+	if (args.lon !== undefined) {
+		updates.push({ key: "lon", value: String(args.lon) });
+	}
+	if (args.altitude !== undefined) {
+		updates.push({ key: "altitude", value: String(args.altitude) });
+	}
+	if (args.altitudeType !== undefined) {
+		updates.push({ key: "altitude-type", value: args.altitudeType });
+	}
+	return updates;
+}
+
+/**
+ * Parse the MCP `where` array (`["attr=value", …]`) into device-class clauses
+ * for op=list. Geo-alias canonicalization happens centrally in `matchesWhere`
+ * (`src/resolver/facts.ts`), so this only splits on the first `=`.
+ */
+function parseMcpWhereClauses(
+	where: readonly string[] | undefined,
+): { key: string; value: string }[] | undefined {
+	if (where === undefined) {
+		return undefined;
+	}
+	return where.map((clause) => {
+		const eq = clause.indexOf("=");
+		if (eq <= 0) {
+			throw new CentrsError({
+				code: "input/invalid-command",
+				summary: `where clause must be \`attr=value\`; received: ${clause}`,
+				remediation:
+					"Pass device-class filters like `board=RB5009` or `lat=37.7749`.",
+				context: { where: clause },
+			});
+		}
+		return { key: clause.slice(0, eq), value: clause.slice(eq + 1) };
+	});
+}
+
 function resolveRecordType(recordType: string | undefined): number | undefined {
 	if (recordType === undefined) {
 		return undefined;
@@ -502,9 +596,49 @@ export async function handleDevices(
 ): Promise<McpEnvelope> {
 	try {
 		const cdb = await loadAllowlistCdb(config);
+		// GPS *setter* fields write via add/set only; the *query* selectors
+		// (where/near/bbox) select via list only. Reject the wrong-op combination
+		// instead of silently dropping the caller's input (mirrors the CLI's
+		// per-subcommand flag guard in src/cli/devices.ts).
+		if (
+			args.op !== "add" &&
+			args.op !== "set" &&
+			(args.lat !== undefined ||
+				args.lon !== undefined ||
+				args.altitude !== undefined ||
+				args.altitudeType !== undefined)
+		) {
+			throw new CentrsError({
+				code: "input/invalid-command",
+				summary: `GPS fields (lat/lon/altitude/altitudeType) are not valid for op="${args.op}".`,
+				remediation:
+					"Store GPS with op=add or op=set; drop the GPS fields for list/show/groups/edit/remove.",
+				context: { op: args.op },
+			});
+		}
+		if (
+			args.op !== "list" &&
+			(args.where !== undefined ||
+				args.near !== undefined ||
+				args.bbox !== undefined)
+		) {
+			throw new CentrsError({
+				code: "input/invalid-command",
+				summary: `Query selectors (where/near/bbox) are only valid for op="list", not op="${args.op}".`,
+				remediation:
+					"Use op=list with where/near/bbox to query the registry; for op=show name a target directly.",
+				context: { op: args.op },
+			});
+		}
 		switch (args.op) {
 			case "list":
-				return listDevices({ cdb, group: args.group });
+				return listDevices({
+					cdb,
+					group: args.group,
+					where: parseMcpWhereClauses(args.where),
+					near: args.near !== undefined ? parseNear(args.near) : undefined,
+					bbox: args.bbox !== undefined ? parseBbox(args.bbox) : undefined,
+				});
 			case "groups":
 				return listGroups({ cdb, withMembers: true });
 			case "show": {
@@ -527,6 +661,7 @@ export async function handleDevices(
 						profile: args.profile,
 						session: args.session,
 						comment: args.comment,
+						commentKvUpdates: buildGeoUpdates(args),
 						savedPassword: args.savedPassword,
 						force: args.force,
 					}),
@@ -542,7 +677,7 @@ export async function handleDevices(
 					await setDevice({
 						cdb,
 						target,
-						updates: args.updates,
+						updates: [...buildGeoUpdates(args), ...(args.updates ?? [])],
 						user: args.user,
 						password: args.password,
 						group: args.group,