@tikoci/centrs 0.1.1 → 0.1.3

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

@@ -106,6 +106,54 @@ export interface ProtocolExecuteResult {
 	ret?: string;
 }
 
+/**
+ * RouterOS verb the `api` orchestrator resolved from the HTTP method (the gh-api
+ * `-X` map: `GET`→print, `PUT`→add, `PATCH`→set, `DELETE`→remove, `POST`→run).
+ * `print` covers list, get-singleton, and get-one (disambiguated by `id`).
+ */
+export type ApiVerb = "print" | "add" | "set" | "remove" | "run";
+
+/**
+ * A normalized `api` request the orchestrator hands to a transport. It is
+ * transport-agnostic: the REST adapter maps the verb to an HTTP method + URL
+ * (id-in-path, `.query`/`.proplist` body), the native adapter maps it to a
+ * tagged `talk` (`=.id=`, `?`-prefixed queries, `=.proplist=`). The orchestrator
+ * owns method→verb, validation, and the write gate; the adapter only executes.
+ */
+export interface ProtocolApiRequest {
+	verb: ApiVerb;
+	/** Slash path without id, e.g. `/ip/address`. For `run`, the command target (`/interface/monitor-traffic`); ignored when `script` is set. */
+	path: string;
+	/** Object id (`*1`) for get-one/set/remove — REST puts it in the URL, native in `=.id=`. */
+	id?: string;
+	/** Body fields (string values), the JSON object for add/set or the args for a `run` command. */
+	attributes?: Record<string, string>;
+	/** Row filter in REST `.query` form (no leading `?`), e.g. `["type=ether", "#!"]`; native prefixes each with `?`. */
+	query?: readonly string[];
+	/** Property projection → REST `.proplist` / native `=.proplist=`. */
+	proplist?: readonly string[];
+	/** Raw console line for the `/execute` script form (`run`); when set, `path`/`attributes` are ignored. */
+	script?: string;
+}
+
+/** Result of an `apiRequest` round-trip: the response body shaped for the envelope. */
+export interface ProtocolApiResult {
+	/** REST returns the body verbatim (array / object / scalar); native re-maps `!re` records to the same rest-style shape. */
+	data: unknown;
+}
+
+/** Options for an open-ended `listen` follow. */
+export interface ProtocolListenOptions {
+	/** Abort the listen (sends `/cancel`); the generator then ends cleanly. */
+	signal?: AbortSignal;
+	/**
+	 * Fired once the subscription is on the wire (connection up, listen sentence
+	 * written) — a real "listening" barrier for callers/tests that must act only
+	 * after the follow is established, instead of a blind timer.
+	 */
+	onListening?: () => void;
+}
+
 /**
  * Runtime transport seam. The orchestrator drives validation and data fetch
  * through these operations so REST and native-api share the same pipeline and
@@ -124,6 +172,18 @@ export interface ProtocolAdapter {
 	list(path: string, options: RetrieveListOptions): Promise<unknown[]>;
 	/** Run a CLI-shaped command (WP-1c write surface). */
 	execute(request: ProtocolExecuteRequest): Promise<ProtocolExecuteResult>;
+	/** Run a normalized structured `api` request (the gh-api passthrough surface). */
+	apiRequest(request: ProtocolApiRequest): Promise<ProtocolApiResult>;
+	/**
+	 * Open-ended `/listen` follow (native-api only). Yields one rest-style change
+	 * record per `!re` frame (deletions carry `.dead`), until cancelled via
+	 * `options.signal` or the consumer stopping. REST and console transports
+	 * reject with `transport/capability-unsupported`.
+	 */
+	listen(
+		request: ProtocolApiRequest,
+		options: ProtocolListenOptions,
+	): AsyncIterable<Record<string, unknown>>;
 	/** Release any underlying connection. Safe to call when never connected. */
 	close(): Promise<void>;
 }
@@ -207,10 +267,105 @@ class RestAdapter implements ProtocolAdapter {
 		return normalizeRestExecute(data);
 	}
 
+	async apiRequest(request: ProtocolApiRequest): Promise<ProtocolApiResult> {
+		const base = request.path.replace(/\/$/, "");
+		switch (request.verb) {
+			case "print": {
+				const hasQuery = (request.query?.length ?? 0) > 0;
+				const hasProplist = (request.proplist?.length ?? 0) > 0;
+				if (request.id && !hasQuery && !hasProplist) {
+					// GET one by id: RouterOS REST addresses a single object in the URL.
+					return {
+						data: await this.requestRest("GET", `${base}/${request.id}`),
+					};
+				}
+				if (request.id || hasQuery || hasProplist) {
+					// A GET cannot carry a body, so `.query`/`.proplist` projection (and an
+					// id, folded into `.query` as `.id=`) rides a POST to the `/print`
+					// sub-endpoint — the documented REST idiom, matching native's `?`-words.
+					const data = await this.requestRest(
+						"POST",
+						`${base}/print`,
+						restQueryBody(request),
+					);
+					// An id addresses one row → unwrap to a single object, matching the
+					// GET-by-id shape and native's `?.id=` read.
+					if (request.id && Array.isArray(data)) {
+						return { data: data[0] ?? null };
+					}
+					return { data };
+				}
+				return { data: await this.requestRest("GET", base) };
+			}
+			case "add":
+				return {
+					data: await this.requestRest("PUT", base, request.attributes ?? {}),
+				};
+			case "set":
+				return {
+					data: await this.requestRest(
+						"PATCH",
+						`${base}/${request.id}`,
+						request.attributes ?? {},
+					),
+				};
+			case "remove":
+				return {
+					data: await this.requestRest("DELETE", `${base}/${request.id}`),
+				};
+			case "run": {
+				if (request.script !== undefined) {
+					// Sync script run: `as-string` makes `/rest/execute` block and return the
+					// captured output rather than scheduling an async job (CHR-grounded).
+					const body = await this.requestRest("POST", "/execute", {
+						script: request.script,
+						"as-string": "",
+					});
+					const result = normalizeRestExecute(body);
+					return { data: result.ret ?? result.records };
+				}
+				return {
+					data: await this.requestRest("POST", base, request.attributes ?? {}),
+				};
+			}
+			default:
+				return exhaustiveApiVerb(request.verb);
+		}
+	}
+
+	// REST cannot hold an open-ended follow (the 60s cap); listen is native-only.
+	// biome-ignore lint/correctness/useYield: a throw-only async generator yields nothing.
+	async *listen(): AsyncGenerator<Record<string, unknown>> {
+		throw new CentrsError({
+			code: "transport/capability-unsupported",
+			summary: "REST cannot follow an open-ended `--stream` (60s cap).",
+			remediation:
+				"Open-ended follow is native-api only: use `--via native-api`, or drop `--stream` for a bounded one-shot.",
+			context: { protocol: this.protocol, capability: "listen" },
+		});
+	}
+
 	async close(): Promise<void> {
 		// REST is stateless; nothing to release.
 	}
 
+	private async requestRest(
+		method: string,
+		path: string,
+		body?: Record<string, unknown>,
+	): Promise<unknown> {
+		const init: RequestInit =
+			body === undefined
+				? { method }
+				: {
+						method,
+						body: JSON.stringify(body),
+						headers: { "Content-Type": "application/json" },
+					};
+		const response = await this.fetchRest(path, init);
+		return response.data;
+	}
+
 	private async restGet(path: string): Promise<unknown> {
 		const response = await this.fetchRest(path, { method: "GET" });
 		return response.data;
@@ -455,23 +610,135 @@ 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) {
+			case "print": {
+				const command: NativeApiCommand = { command: `${base}/print` };
+				const queries: string[] = [];
+				// REST `.query` words map 1:1 to native `?`-prefixed words (CHR-grounded).
+				for (const word of request.query ?? []) {
+					queries.push(`?${word}`);
+				}
+				// No native get-one-by-id shorthand: address a single row with `?.id=`.
+				if (request.id) {
+					queries.push(`?.id=${request.id}`);
+				}
+				if (queries.length > 0) {
+					command.queries = queries;
+				}
+				if (request.proplist && request.proplist.length > 0) {
+					command.proplist = request.proplist;
+				}
+				const records = repliesToRecords(await this.talk(command));
+				return { data: request.id ? (records[0] ?? null) : records };
+			}
+			case "add": {
+				const records = repliesToRecords(
+					await this.talk({
+						command: `${base}/add`,
+						attributes: request.attributes ?? {},
+					}),
+				);
+				return { data: restStyleMutationData(records) };
+			}
+			case "set": {
+				const records = repliesToRecords(
+					await this.talk({
+						command: `${base}/set`,
+						attributes: {
+							...(request.attributes ?? {}),
+							".id": request.id ?? "",
+						},
+					}),
+				);
+				return { data: restStyleMutationData(records) };
+			}
+			case "remove": {
+				const records = repliesToRecords(
+					await this.talk({
+						command: `${base}/remove`,
+						attributes: { ".id": request.id ?? "" },
+					}),
+				);
+				return { data: restStyleMutationData(records) };
+			}
+			case "run": {
+				if (request.script !== undefined) {
+					const records = await this.executeScript(request.script);
+					return { data: restStyleRunData(records) };
+				}
+				const command: NativeApiCommand = { command: base };
+				if (request.attributes && Object.keys(request.attributes).length > 0) {
+					command.attributes = request.attributes;
+				}
+				return { data: repliesToRecords(await this.talk(command)) };
+			}
+			default:
+				return exhaustiveApiVerb(request.verb);
+		}
+	}
+
+	async *listen(
+		request: ProtocolApiRequest,
+		options: ProtocolListenOptions,
+	): AsyncGenerator<Record<string, unknown>> {
+		const base = request.path.replace(/\/$/, "");
+		const command: NativeApiCommand = { command: `${base}/listen` };
+		// A listen can filter which changes it follows with the same `?`-words /
+		// `=.proplist=` as print (REST `.query` word == native `?`-word minus `?`).
+		const queries = (request.query ?? []).map((word) => `?${word}`);
+		// An addressed row (`ip/address/*1 --stream`) follows just that row, the
+		// same `?.id=` mapping one-shot native reads use.
+		if (request.id) {
+			queries.push(`?.id=${request.id}`);
+		}
+		if (queries.length > 0) {
+			command.queries = queries;
+		}
+		if (request.proplist && request.proplist.length > 0) {
+			command.proplist = request.proplist;
+		}
+		const session = await this.connect();
+		for await (const reply of session.listen(command, options)) {
+			// Each `!re` becomes a rest-style record (string values; `.dead` preserved).
+			yield { ...reply.attributes };
+		}
+	}
+
 	async close(): Promise<void> {
 		this.session?.close();
 		this.session = undefined;
@@ -614,6 +881,15 @@ class MacTelnetAdapter implements ProtocolAdapter {
 		return { records: [], ret: output };
 	}
 
+	apiRequest(): Promise<ProtocolApiResult> {
+		return Promise.reject(this.unsupported("structured api requests"));
+	}
+
+	// biome-ignore lint/correctness/useYield: a reject-only async generator yields nothing.
+	async *listen(): AsyncGenerator<Record<string, unknown>> {
+		throw this.unsupported("open-ended listen streaming");
+	}
+
 	async close(): Promise<void> {
 		this.console?.close();
 		this.transport?.close();
@@ -756,11 +1032,83 @@ class SshExecAdapter implements ProtocolAdapter {
 		return { records: [], ret: output };
 	}
 
+	apiRequest(): Promise<ProtocolApiResult> {
+		return Promise.reject(this.unsupported("structured api requests"));
+	}
+
+	// biome-ignore lint/correctness/useYield: a reject-only async generator yields nothing.
+	async *listen(): AsyncGenerator<Record<string, unknown>> {
+		throw this.unsupported("open-ended listen streaming");
+	}
+
 	close(): Promise<void> {
 		return Promise.resolve();
 	}
 }
 
+/** REST `.query` / `.proplist` projection body for a POST `/print`. */
+function restQueryBody(request: ProtocolApiRequest): Record<string, unknown> {
+	const body: Record<string, unknown> = {};
+	// Fold an id into `.query` as `.id=<id>` so id+query/proplist reads work over
+	// REST exactly as they do over native (`?.id=` plus the `?`-words).
+	const query = [
+		...(request.id ? [`.id=${request.id}`] : []),
+		...(request.query ?? []),
+	];
+	if (query.length > 0) {
+		body[".query"] = query;
+	}
+	if (request.proplist && request.proplist.length > 0) {
+		body[".proplist"] = request.proplist;
+	}
+	return body;
+}
+
+/**
+ * Re-map a native add/set/remove reply to the rest-style shape. `add` returns the
+ * new id in `=ret=`; surface it as `{".id": ret}` (REST returns the created
+ * object with `.id`). `set`/`remove` reply with a bare `!done` (no records) → no
+ * meaningful body, mirrored as `null`.
+ */
+function restStyleMutationData(
+	records: readonly Record<string, string>[],
+): unknown {
+	if (records.length === 0) {
+		return null;
+	}
+	const record = records[0] ?? {};
+	const ret = record["ret"];
+	if (typeof ret === "string" && /^\*[0-9A-F]+$/i.test(ret)) {
+		return { ".id": ret };
+	}
+	return records.length === 1 ? record : records;
+}
+
+/** Re-map a native `/execute` reply: prefer the captured `ret` string, else the records. */
+function restStyleRunData(records: readonly Record<string, string>[]): unknown {
+	const ret = records.length === 1 ? records[0]?.["ret"] : undefined;
+	if (typeof ret === "string") {
+		return ret;
+	}
+	return records.length === 1 ? records[0] : records;
+}
+
+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>[] };