@tikoci/centrs 0.1.2 → 0.1.3

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";
@@ -173,6 +192,7 @@ export {
 	type DevicesShowEnvelopeData,
 	type DevicesShowItem,
 	type DevicesWarning,
+	type DevicesWhereClause,
 	defaultCdbPath,
 	devicesOutputFormats,
 	editInteractiveOnlyError,
@@ -228,6 +248,7 @@ export {
 	canonicalizeExecuteCommand,
 	type ExecuteEnvelope,
 	type ExecuteErrorEnvelope,
+	type ExecuteGlobalContext,
 	type ExecuteOperationMeta,
 	type ExecuteOutputFormat,
 	type ExecuteRequest,
@@ -238,10 +259,23 @@ 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,
@@ -262,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,
@@ -296,7 +351,9 @@ export {
 	resolveOptionalIntegerSetting,
 	resolveStringSetting,
 	resolveTarget,
+	type SelectionWhereClause,
 	type TargetResolveInput,
+	type TargetSelection,
 	toCoreSource,
 } from "./resolver/index.ts";
 export {
@@ -326,11 +383,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 +433,7 @@ export {
 export {
 	buildTransferErrorEnvelope,
 	FILE_READ_CHUNK_BYTES,
+	isTransferWriteVerb,
 	normalizeRemotePath,
 	REST_FILE_WRITE_CAP_BYTES,
 	renderTransferEnvelope,
@@ -365,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,

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,

package/src/protocols/adapter.ts

@@ -610,23 +610,39 @@ class NativeApiAdapter implements ProtocolAdapter {
 	async execute(
 		request: ProtocolExecuteRequest,
 	): Promise<ProtocolExecuteResult> {
-		const command: NativeApiCommand = request.script
-			? { command: "/execute", attributes: { script: request.script } }
-			: { command: `${request.path.replace(/\/$/, "")}/${request.command}` };
-		if (
-			!request.script &&
-			request.attributes &&
-			Object.keys(request.attributes).length > 0
-		) {
+		if (request.script !== undefined) {
+			return normalizeNativeExecute(await this.executeScript(request.script));
+		}
+		const command: NativeApiCommand = {
+			command: `${request.path.replace(/\/$/, "")}/${request.command}`,
+		};
+		if (request.attributes && Object.keys(request.attributes).length > 0) {
 			command.attributes = request.attributes;
 		}
-		if (!request.script && request.queries && request.queries.length > 0) {
+		if (request.queries && request.queries.length > 0) {
 			command.queries = request.queries;
 		}
 		const replies = await this.talk(command);
 		return { records: repliesToRecords(replies) };
 	}
 
+	/**
+	 * Run a script through native `/execute` with `as-string`, the sole shared
+	 * path for both the CLI-shaped `execute` command and the `api` run+script
+	 * verb: without `as-string` the native API schedules a background job and
+	 * returns only its id rather than the captured output (CHR-grounded —
+	 * mirrors REST `/rest/execute`).
+	 */
+	private async executeScript(
+		script: string,
+	): Promise<Record<string, string>[]> {
+		const replies = await this.talk({
+			command: "/execute",
+			attributes: { script, "as-string": "" },
+		});
+		return repliesToRecords(replies);
+	}
+
 	async apiRequest(request: ProtocolApiRequest): Promise<ProtocolApiResult> {
 		const base = request.path.replace(/\/$/, "");
 		switch (request.verb) {
@@ -682,15 +698,7 @@ class NativeApiAdapter implements ProtocolAdapter {
 			}
 			case "run": {
 				if (request.script !== undefined) {
-					// `as-string` makes `/execute` run synchronously and return the captured
-					// output; without it the native API schedules a job and returns its id
-					// (CHR-grounded — mirrors REST `/rest/execute`).
-					const records = repliesToRecords(
-						await this.talk({
-							command: "/execute",
-							attributes: { script: request.script, "as-string": "" },
-						}),
-					);
+					const records = await this.executeScript(request.script);
 					return { data: restStyleRunData(records) };
 				}
 				const command: NativeApiCommand = { command: base };
@@ -1089,6 +1097,18 @@ function exhaustiveApiVerb(verb: never): never {
 	throw new Error(`Unhandled api verb: ${String(verb)}`);
 }
 
+/** Re-map an `as-string` native `/execute` reply into `ProtocolExecuteResult`,
+ * mirroring `normalizeRestExecute`'s `ret`-vs-records split. */
+function normalizeNativeExecute(
+	records: readonly Record<string, string>[],
+): ProtocolExecuteResult {
+	const ret = records.length === 1 ? records[0]?.["ret"] : undefined;
+	if (typeof ret === "string") {
+		return { records: [], ret };
+	}
+	return { records: [...records] };
+}
+
 function normalizeRestExecute(data: unknown): ProtocolExecuteResult {
 	if (Array.isArray(data)) {
 		return { records: data.filter(isPlainObject) as Record<string, string>[] };

package/src/protocols/index.ts

@@ -7,6 +7,11 @@
  * Status per protocol is the implementation reality (`implemented` flag).
  * Per-cell status across commands is in `docs/MATRIX.md`. Selection rules
  * are in `docs/CONSTITUTION.md` (protocol selection).
+ *
+ * Contract with MATRIX (asserted by `test/unit/protocol-registry.test.ts`):
+ * every `CHR-passed` cell in the `docs/MATRIX.md` grid implies its protocol
+ * here is `implemented: true` and lists the matching capability. MATRIX stays
+ * the only status surface; this registry must never under-claim against it.
  */
 
 export type ProtocolCapability =
@@ -35,7 +40,7 @@ export const protocolPlans = [
 	},
 	{
 		id: "native-api",
-		capabilities: ["retrieve", "execute", "proxy"],
+		capabilities: ["retrieve", "execute", "transfer", "proxy"],
 		notes:
 			"Binary API (TCP 8728 / TLS 8729). Transport base implemented in native-api.ts (word/sentence codec, login, tagged talk); command wiring tracked in docs/MATRIX.md.",
 		implemented: true,
@@ -44,8 +49,8 @@ export const protocolPlans = [
 		id: "ssh",
 		capabilities: ["execute", "terminal", "transfer"],
 		notes:
-			"Reuses host ssh client. Important execute/terminal path after grounding.",
-		implemented: false,
+			"Reuses host ssh client. execute/terminal/transfer all CHR-passed (docs/MATRIX.md); facts in ssh.ts, sftp.ts, terminal.ts.",
+		implemented: true,
 	},
 	{
 		id: "snmp",
@@ -56,8 +61,9 @@ export const protocolPlans = [
 	{
 		id: "mndp",
 		capabilities: ["discover"],
-		notes: "Passive hint source only; not authoritative inventory.",
-		implemented: false,
+		notes:
+			"Passive hint source only; not authoritative inventory. discover CHR-passed (docs/MATRIX.md); facts in src/data/mndp.ts.",
+		implemented: true,
 	},
 	{
 		id: "mac-telnet",

package/src/resolver/cdb.ts

@@ -153,6 +153,7 @@ function warningFromDevices(warning: DevicesWarning): ResolverWarning {
 export async function resolveCdb(
 	input: CdbResolveInput,
 	env: Record<string, string | undefined>,
+	config: Record<string, string | undefined> = {},
 ): Promise<CdbResolution | undefined> {
 	if (!input.targetInput) {
 		return undefined;
@@ -162,12 +163,18 @@ export async function resolveCdb(
 		cdbFile: input.cdbFile,
 		cdbPassword: input.cdbPassword,
 		env,
+		config,
 	});
+	// A user-configured `centrs.env` default CDB path counts as explicit, same
+	// as an env var: it is an intentional choice, not the built-in fallback,
+	// so a missing file there should surface as a real error rather than
+	// silently degrading to "no CDB in play".
 	const explicitCdb =
 		input.cdbFile !== undefined ||
 		input.cdbPassword !== undefined ||
 		env[ENV_CDB_FILE] !== undefined ||
-		env[ENV_CDB_PASSWORD] !== undefined;
+		env[ENV_CDB_PASSWORD] !== undefined ||
+		config[ENV_CDB_FILE] !== undefined;
 	if (!explicitCdb && !(await Bun.file(settings.cdbFile.value).exists())) {
 		return undefined;
 	}
@@ -178,6 +185,7 @@ export async function resolveCdb(
 			cdbFile: input.cdbFile,
 			cdbPassword: input.cdbPassword,
 			env,
+			config,
 		});
 	} catch (error) {
 		if (
@@ -312,7 +320,7 @@ export async function expandCdbGroup(
 	return { targets, warnings, empty: false };
 }
 
-function resolutionFromEntry(
+export function resolutionFromEntry(
 	entry: WinBoxCdbEntry,
 	recordIndex: number,
 ): CdbResolution {