@7365admin1/core 3.81.0 → 3.83.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@7365admin1/core",
   "license": "MIT",
-  "version": "3.81.0",
+  "version": "3.83.0",
   "author": "7365admin1",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -13,7 +13,7 @@
     "build": "tsup src/index.ts --format cjs,esm --dts && shx cp -r src/public dist && shx cp -r src/utils/handlebars dist",
     "release": "yarn run build && changeset publish",
     "lint": "tsc",
-    "test": "tsup src/config.ts src/utils/robot-cloud.util.ts src/utils/robot-tracking.util.ts src/utils/robot-apps.util.ts src/utils/robot-permission.util.ts src/utils/anpr-revoke.util.ts src/utils/anpr-plate.util.ts src/utils/vehicle-request.util.ts src/utils/camera-view.util.ts src/utils/camera-bulk-import.util.ts src/utils/dashboard-metrics.util.ts src/utils/camera-capability.util.ts src/utils/camera-playback.util.ts src/services/camera-device-http.service.ts src/utils/camera-alert.util.ts src/utils/dahua-protocol.util.ts src/utils/site-name.util.ts src/utils/service-provider-invite.util.ts src/utils/notification-category.util.ts src/utils/hid-card.util.ts src/utils/hid-json.util.ts src/utils/hid-access.util.ts src/models/customer-site.model.ts src/models/site-camera.model.ts src/models/member.model.ts src/models/subscription.model.ts src/utils/session-id.util.ts src/utils/occurrence-query.util.ts src/utils/occurrence-book-create.util.ts src/utils/update-result.util.ts src/utils/hid-amico-authz.util.ts src/utils/promo-code-currency.util.ts src/utils/console-audit.util.ts src/utils/org-suspension.util.ts src/utils/session-revoke.util.ts src/models/hid-amico.model.ts src/models/patrol-email.model.ts src/utils/patrol-email-pdf.util.ts src/utils/visitor-status.util.ts src/utils/self-service-email.util.ts src/utils/hid-secret.util.ts src/models/visitor-invite.model.ts src/models/guard-invite.model.ts src/utils/site-timezone.util.ts src/utils/bulletin-service-apps.util.ts src/models/bulletin-board.model.ts src/utils/vehicle-import.util.ts src/utils/expired-vehicle-sweep.util.ts src/models/vehicle.model.ts src/controllers/chat.controller.ts src/utils/file-owner.util.ts src/utils/console-permission.util.ts src/utils/role-scope.util.ts src/utils/org-default-roles.util.ts src/utils/org-modules.util.ts src/utils/site-modules.util.ts src/utils/resident-app-modules.util.ts src/utils/resident-default-role.util.ts src/utils/invite-role-scope.util.ts src/models/personal-emergency-chain.model.ts src/utils/self-signup-files.util.ts src/models/person.model.ts src/utils/module-gate.util.ts src/utils/member-lookup.util.ts src/utils/notification-access.util.ts src/utils/module-access.util.ts src/services/module-gate.service.ts src/controllers/site.controller.ts src/controllers/organization.controller.ts src/controllers/member.controller.ts src/utils/org-owner-repair.util.ts src/utils/socket-session.util.ts src/utils/people-create-gate.util.ts src/utils/service-app-type.util.ts --format esm --out-dir test/.build --no-dts --silent && node --test test/*.test.mjs",
+    "test": "tsup src/config.ts src/utils/robot-cloud.util.ts src/utils/robot-adapter.util.ts src/utils/robot-tracking.util.ts src/utils/robot-apps.util.ts src/utils/robot-permission.util.ts src/utils/lift-contract.util.ts src/utils/anpr-revoke.util.ts src/utils/anpr-plate.util.ts src/utils/vehicle-request.util.ts src/utils/camera-view.util.ts src/utils/camera-bulk-import.util.ts src/utils/dashboard-metrics.util.ts src/utils/camera-capability.util.ts src/utils/camera-playback.util.ts src/services/camera-device-http.service.ts src/utils/camera-alert.util.ts src/utils/dahua-protocol.util.ts src/utils/site-name.util.ts src/utils/service-provider-invite.util.ts src/utils/notification-category.util.ts src/utils/hid-card.util.ts src/utils/hid-json.util.ts src/utils/hid-access.util.ts src/models/customer-site.model.ts src/models/site-camera.model.ts src/models/member.model.ts src/models/subscription.model.ts src/utils/session-id.util.ts src/utils/occurrence-query.util.ts src/utils/occurrence-book-create.util.ts src/utils/update-result.util.ts src/utils/hid-amico-authz.util.ts src/utils/promo-code-currency.util.ts src/utils/console-audit.util.ts src/utils/org-suspension.util.ts src/utils/session-revoke.util.ts src/models/hid-amico.model.ts src/models/patrol-email.model.ts src/utils/patrol-email-pdf.util.ts src/utils/visitor-status.util.ts src/utils/self-service-email.util.ts src/utils/hid-secret.util.ts src/models/visitor-invite.model.ts src/models/guard-invite.model.ts src/utils/site-timezone.util.ts src/utils/bulletin-service-apps.util.ts src/models/bulletin-board.model.ts src/utils/vehicle-import.util.ts src/utils/expired-vehicle-sweep.util.ts src/models/vehicle.model.ts src/controllers/chat.controller.ts src/utils/file-owner.util.ts src/utils/console-permission.util.ts src/utils/role-scope.util.ts src/utils/org-default-roles.util.ts src/utils/org-modules.util.ts src/utils/site-modules.util.ts src/utils/resident-app-modules.util.ts src/utils/resident-default-role.util.ts src/utils/invite-role-scope.util.ts src/models/personal-emergency-chain.model.ts src/utils/self-signup-files.util.ts src/models/person.model.ts src/utils/module-gate.util.ts src/utils/member-lookup.util.ts src/utils/notification-access.util.ts src/utils/module-access.util.ts src/services/module-gate.service.ts src/controllers/site.controller.ts src/controllers/organization.controller.ts src/controllers/member.controller.ts src/utils/org-owner-repair.util.ts src/utils/socket-session.util.ts src/utils/people-create-gate.util.ts src/utils/service-app-type.util.ts --format esm --out-dir test/.build --no-dts --silent && node --test test/*.test.mjs",
     "test:camera": "yarn test",
     "test:e2e": "yarn build && node --test --test-concurrency=1 --test-timeout=600000 \"test/e2e/*.test.mjs\""
   },

package/test/lift-contract.test.mjs

@@ -0,0 +1,271 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+
+import {
+  LIFT_DOOR,
+  LIFT_MODE,
+  LIFT_MOTION,
+  LIFT_REQUEST,
+  createLiftSimulator,
+  holdsLift,
+  isLiftAvailable,
+  isSafeToCross,
+  servesFloor,
+} from "./.build/utils/lift-contract.util.mjs";
+
+/* --------------------------------------------------------------------------
+ * The lift is the one part of this system that can injure somebody, and the
+ * Inovance register map has not arrived, so every decision here is made against
+ * a simulator rather than a real car. These assert the decisions that would
+ * otherwise only be discovered on a live lift.
+ *
+ * Enum values match rmf_lift_msgs verbatim (open-rmf/rmf_internal_msgs).
+ * ----------------------------------------------------------------------- */
+
+const FLOORS = ["L1", "L2", "L3", "L4"];
+const sim = (o = {}) => createLiftSimulator({ name: "LIFT-A", floors: FLOORS, ...o });
+
+const stateWith = (over = {}) => ({
+  liftName: "LIFT-A",
+  liftTime: 0,
+  availableFloors: [...FLOORS],
+  currentFloor: "L1",
+  destinationFloor: "L1",
+  doorState: LIFT_DOOR.OPEN,
+  motionState: LIFT_MOTION.STOPPED,
+  currentMode: LIFT_MODE.HUMAN,
+  sessionId: "",
+  ...over,
+});
+
+/* ------------------------------------------------- the enums match RMF */
+
+test("the enum values are rmf_lift_msgs values, not our own numbering", () => {
+  assert.deepEqual(LIFT_DOOR, { CLOSED: 0, MOVING: 1, OPEN: 2 });
+  assert.deepEqual(LIFT_MOTION, { STOPPED: 0, UP: 1, DOWN: 2, UNKNOWN: 3 });
+  assert.deepEqual(LIFT_MODE, {
+    UNKNOWN: 0, HUMAN: 1, AGV: 2, FIRE: 3, OFFLINE: 4, EMERGENCY: 5,
+  });
+  assert.deepEqual(LIFT_REQUEST, { END_SESSION: 0, AGV_MODE: 1, HUMAN_MODE: 2 });
+});
+
+/* ------------------------------------------------------------ availability */
+
+test("a lift in FIRE or EMERGENCY mode is never available", () => {
+  // During an evacuation the lift belongs to the fire service. A robot must not
+  // be queued for it, whatever else is true.
+  for (const mode of [LIFT_MODE.FIRE, LIFT_MODE.EMERGENCY, LIFT_MODE.OFFLINE, LIFT_MODE.UNKNOWN]) {
+    const s = stateWith({ currentMode: mode });
+    assert.equal(isLiftAvailable(s), false, `mode ${mode}`);
+    assert.equal(isSafeToCross(s, "L1"), false, `mode ${mode}`);
+  }
+});
+
+test("a lift that has never reported is not available", () => {
+  assert.equal(isLiftAvailable(null), false);
+  assert.equal(isSafeToCross(null, "L1"), false);
+  assert.equal(servesFloor(null, "L1"), false);
+});
+
+/* -------------------------------------------------------- crossing the door */
+
+test("a MOVING door is not an open door", () => {
+  // The branch that matters most: telling a robot to cross a closing door plane
+  // is how a robot gets struck.
+  assert.equal(isSafeToCross(stateWith({ doorState: LIFT_DOOR.MOVING }), "L1"), false);
+  assert.equal(isSafeToCross(stateWith({ doorState: LIFT_DOOR.CLOSED }), "L1"), false);
+  assert.equal(isSafeToCross(stateWith({ doorState: LIFT_DOOR.OPEN }), "L1"), true);
+});
+
+test("a car still in motion is never safe to cross, doors notwithstanding", () => {
+  for (const motion of [LIFT_MOTION.UP, LIFT_MOTION.DOWN, LIFT_MOTION.UNKNOWN]) {
+    assert.equal(
+      isSafeToCross(stateWith({ motionState: motion, doorState: LIFT_DOOR.OPEN }), "L1"),
+      false,
+      `motion ${motion}`
+    );
+  }
+});
+
+test("a car at the WRONG floor is not safe to cross", () => {
+  // A passenger redirecting the car mid-journey is exactly this case.
+  assert.equal(isSafeToCross(stateWith({ currentFloor: "L3" }), "L1"), false);
+  assert.equal(isSafeToCross(stateWith({ currentFloor: "L3" }), "L3"), true);
+});
+
+/* ------------------------------------------------------------- the session */
+
+test("an empty session id never holds the lift", () => {
+  // Otherwise a caller that forgot to set one is handed a lift somebody is riding.
+  assert.equal(holdsLift(stateWith({ sessionId: "" }), ""), false);
+  assert.equal(holdsLift(stateWith({ sessionId: "j-1" }), ""), false);
+  assert.equal(holdsLift(stateWith({ sessionId: "" }), "j-1"), false);
+  assert.equal(holdsLift(stateWith({ sessionId: "j-1" }), "j-1"), true);
+});
+
+test("a floor the lift does not serve is not a destination", () => {
+  assert.equal(servesFloor(stateWith(), "L9"), false);
+  assert.equal(servesFloor(stateWith(), ""), false);
+  assert.equal(servesFloor(stateWith(), "L3"), true);
+});
+
+/* ------------------------------------------------------------- simulator */
+
+test("a requested lift travels, arrives, and opens its doors", async () => {
+  const lift = sim({ msPerFloor: 1_000 });
+
+  await lift.request({
+    liftName: "LIFT-A", sessionId: "j-1",
+    requestType: LIFT_REQUEST.AGV_MODE, destinationFloor: "L3",
+    doorState: LIFT_DOOR.OPEN,
+  });
+
+  let s = await lift.read();
+  assert.equal(s.motionState, LIFT_MOTION.UP);
+  assert.equal(s.doorState, LIFT_DOOR.CLOSED, "doors shut while travelling");
+  assert.equal(isSafeToCross(s, "L3"), false);
+
+  lift.tick(2_000); // two floors
+  s = await lift.read();
+  assert.equal(s.currentFloor, "L3");
+  assert.equal(s.motionState, LIFT_MOTION.STOPPED);
+  assert.equal(s.doorState, LIFT_DOOR.OPEN);
+  assert.equal(isSafeToCross(s, "L3"), true);
+});
+
+test("the doors close themselves — this is why the hold must be refreshed", async () => {
+  // The tightest timing in the whole design: a passenger lift times its doors
+  // out while the robot is still crossing.
+  const lift = sim({ msPerFloor: 1_000, doorDwellMs: 4_000 });
+  await lift.request({
+    liftName: "LIFT-A", sessionId: "j-1",
+    requestType: LIFT_REQUEST.AGV_MODE, destinationFloor: "L1",
+    doorState: LIFT_DOOR.OPEN,
+  });
+
+  assert.equal((await lift.read()).doorState, LIFT_DOOR.OPEN);
+  lift.tick(4_000);
+  assert.equal((await lift.read()).doorState, LIFT_DOOR.CLOSED, "closed on its own");
+});
+
+test("refreshing the hold keeps the doors open", async () => {
+  const lift = sim({ doorDwellMs: 4_000 });
+  await lift.request({
+    liftName: "LIFT-A", sessionId: "j-1",
+    requestType: LIFT_REQUEST.AGV_MODE, destinationFloor: "L1",
+    doorState: LIFT_DOOR.OPEN,
+  });
+
+  for (let i = 0; i < 5; i++) {
+    lift.tick(3_000);
+    await lift.refresh("j-1");
+  }
+  assert.equal((await lift.read()).doorState, LIFT_DOOR.OPEN);
+});
+
+test("refreshing somebody else's session does NOT hold the doors", async () => {
+  const lift = sim({ doorDwellMs: 4_000 });
+  await lift.request({
+    liftName: "LIFT-A", sessionId: "j-1",
+    requestType: LIFT_REQUEST.AGV_MODE, destinationFloor: "L1",
+    doorState: LIFT_DOOR.OPEN,
+  });
+
+  lift.tick(3_000);
+  await lift.refresh("j-2"); // not the holder
+  lift.tick(2_000);
+  assert.equal((await lift.read()).doorState, LIFT_DOOR.CLOSED);
+});
+
+test("a lift held by one journey is refused to another, not stolen", async () => {
+  const lift = sim();
+  await lift.request({
+    liftName: "LIFT-A", sessionId: "j-1",
+    requestType: LIFT_REQUEST.AGV_MODE, destinationFloor: "L2",
+    doorState: LIFT_DOOR.OPEN,
+  });
+
+  await assert.rejects(
+    () => lift.request({
+      liftName: "LIFT-A", sessionId: "j-2",
+      requestType: LIFT_REQUEST.AGV_MODE, destinationFloor: "L4",
+      doorState: LIFT_DOOR.OPEN,
+    }),
+    /held by j-1/
+  );
+});
+
+test("release is safe to call twice, and frees the lift for the next journey", async () => {
+  const lift = sim();
+  await lift.request({
+    liftName: "LIFT-A", sessionId: "j-1",
+    requestType: LIFT_REQUEST.AGV_MODE, destinationFloor: "L2",
+    doorState: LIFT_DOOR.OPEN,
+  });
+
+  await lift.release("j-1");
+  await lift.release("j-1"); // the watchdog fires unconditionally
+  const s = await lift.read();
+  assert.equal(s.sessionId, "");
+  assert.equal(s.currentMode, LIFT_MODE.HUMAN, "handed back to passengers");
+
+  await lift.request({
+    liftName: "LIFT-A", sessionId: "j-2",
+    requestType: LIFT_REQUEST.AGV_MODE, destinationFloor: "L4",
+    doorState: LIFT_DOOR.OPEN,
+  });
+  assert.equal((await lift.read()).sessionId, "j-2");
+});
+
+test("releasing a lift somebody else holds does nothing", async () => {
+  const lift = sim();
+  await lift.request({
+    liftName: "LIFT-A", sessionId: "j-1",
+    requestType: LIFT_REQUEST.AGV_MODE, destinationFloor: "L2",
+    doorState: LIFT_DOOR.OPEN,
+  });
+
+  await lift.release("j-2");
+  assert.equal((await lift.read()).sessionId, "j-1", "still held by j-1");
+});
+
+test("a floor the lift does not serve is refused", async () => {
+  const lift = sim();
+  await assert.rejects(
+    () => lift.request({
+      liftName: "LIFT-A", sessionId: "j-1",
+      requestType: LIFT_REQUEST.AGV_MODE, destinationFloor: "B2",
+      doorState: LIFT_DOOR.OPEN,
+    }),
+    /does not serve B2/
+  );
+});
+
+test("END_SESSION hands the lift back to passengers", async () => {
+  const lift = sim();
+  await lift.request({
+    liftName: "LIFT-A", sessionId: "j-1",
+    requestType: LIFT_REQUEST.AGV_MODE, destinationFloor: "L2",
+    doorState: LIFT_DOOR.OPEN,
+  });
+  assert.equal((await lift.read()).currentMode, LIFT_MODE.AGV);
+
+  await lift.request({
+    liftName: "LIFT-A", sessionId: "j-1",
+    requestType: LIFT_REQUEST.END_SESSION, destinationFloor: "L2",
+    doorState: LIFT_DOOR.CLOSED,
+  });
+  const s = await lift.read();
+  assert.equal(s.sessionId, "");
+  assert.equal(s.currentMode, LIFT_MODE.HUMAN);
+});
+
+test("read() returns a copy — a caller cannot mutate the lift", async () => {
+  const lift = sim();
+  const s = await lift.read();
+  s.availableFloors.push("L99");
+  s.currentFloor = "L4";
+  const again = await lift.read();
+  assert.equal(again.availableFloors.includes("L99"), false);
+  assert.equal(again.currentFloor, "L1");
+});

package/test/robot-adapter.test.mjs

@@ -0,0 +1,179 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+
+import {
+  ROBOT_CAPABILITIES,
+  clearRobotAdapters,
+  commandSupported,
+  missingForTier,
+  registerRobotAdapter,
+  registeredRobotBrands,
+  robotAdapterFor,
+  robotTier,
+  supports,
+  uncontrollableFleetWarning,
+} from "./.build/utils/robot-adapter.util.mjs";
+
+/* --------------------------------------------------------------------------
+ * The goal changed: fleet management for every brand and model on the market,
+ * not one vendor. That only works if the screens ask the ROBOT what it can do
+ * instead of assuming, so these guard the capability model and the registry.
+ *
+ * The capability names and the tier requirements are Open-RMF's, verbatim from
+ * the "Fleet Adapters" table in ros2multirobotbook. Keeping them is what lets a
+ * brand's datasheet be read straight into a tier.
+ * ----------------------------------------------------------------------- */
+
+const ALL = Object.fromEntries(ROBOT_CAPABILITIES.map((c) => [c, true]));
+const caps = (...names) => Object.fromEntries(names.map((n) => [n, true]));
+
+/* ------------------------------------------------------------------ tiers */
+
+test("everything supported is Full Control", () => {
+  assert.equal(robotTier(ALL), "full-control");
+});
+
+test("nothing supported is no-interface — a real answer, not an error", () => {
+  // Our own security robot is this today: a web page on a building's LAN.
+  assert.equal(robotTier({}), "no-interface");
+  assert.equal(robotTier(null), "no-interface");
+  assert.equal(robotTier(undefined), "no-interface");
+});
+
+test("a tier needs EVERY requirement — partial credit misses the point", () => {
+  const nearlyFull = { ...ALL };
+  delete nearlyFull.relocalize;
+  assert.notEqual(robotTier(nearlyFull), "full-control");
+
+  const trafficLight = caps(
+    "readLocation", "pauseResume", "battery", "sendToDock",
+    "startProcess", "pauseProcess", "processCompletion",
+  );
+  assert.equal(robotTier(trafficLight), "traffic-light");
+
+  const { battery, ...noBattery } = trafficLight;
+  assert.notEqual(robotTier(noBattery), "traffic-light");
+});
+
+test("Ounitech today does not reach even Read Only", () => {
+  // What their documented API actually gives: pose, dock, and "start a process"
+  // (start-area-cleaning). No battery, no path/ETA, no reliable completion.
+  const ounitech = caps("readLocation", "sendToDock", "startProcess");
+  assert.equal(robotTier(ounitech), "no-interface");
+
+  // And this is the ask that moves them, in order.
+  assert.deepEqual(missingForTier(ounitech, "read-only"), [
+    "pathAndEta",
+    "battery",
+    "processCompletion",
+  ]);
+  assert.deepEqual(missingForTier(ounitech, "traffic-light"), [
+    "pauseResume",
+    "battery",
+    "pauseProcess",
+    "processCompletion",
+  ]);
+});
+
+test("a capability set with false values does not count as support", () => {
+  assert.equal(supports({ battery: false }, "battery"), false);
+  assert.equal(supports({ battery: true }, "battery"), true);
+  assert.equal(supports({}, "battery"), false);
+  assert.equal(supports(null, "battery"), false);
+});
+
+test("a prototype key is not a capability", () => {
+  // hasOwnProperty, not a bare lookup - otherwise "constructor" reads as true.
+  assert.equal(supports({}, "constructor"), false);
+  assert.equal(supports({}, "toString"), false);
+});
+
+/* ------------------------------------------- the shared-space safety rule */
+
+test("two uncontrollable fleets in one space is refused", () => {
+  // Open-RMF: at most ONE read-only fleet in a shared space, "having none is
+  // ideal". A read-only cleaning fleet plus a no-interface security robot is
+  // exactly the pair to warn about.
+  assert.equal(uncontrollableFleetWarning(["read-only"]).ok, true);
+  assert.equal(uncontrollableFleetWarning(["no-interface"]).ok, true);
+  assert.equal(uncontrollableFleetWarning(["full-control", "read-only"]).ok, true);
+
+  const bad = uncontrollableFleetWarning(["read-only", "no-interface"]);
+  assert.equal(bad.ok, false);
+  assert.equal(bad.count, 2);
+  assert.match(bad.message, /at most one/i);
+});
+
+test("controllable fleets never trigger the warning, however many", () => {
+  const many = ["full-control", "full-control", "traffic-light", "traffic-light"];
+  assert.equal(uncontrollableFleetWarning(many).ok, true);
+  assert.equal(uncontrollableFleetWarning([]).ok, true);
+});
+
+/* --------------------------------------------------------------- commands */
+
+test("a command the brand never claimed is refused", () => {
+  const readOnlyish = caps("readLocation");
+  for (const kind of ["full", "area", "spot", "return", "pause", "navigate", "relocalize"]) {
+    assert.equal(commandSupported(readOnlyish, kind), false, kind);
+  }
+  assert.equal(commandSupported(ALL, "navigate"), true);
+});
+
+test("each command maps to the capability it actually needs", () => {
+  assert.equal(commandSupported(caps("startProcess"), "area"), true);
+  assert.equal(commandSupported(caps("startProcess"), "return"), false);
+  assert.equal(commandSupported(caps("sendToDock"), "return"), true);
+  assert.equal(commandSupported(caps("pauseProcess"), "cancel"), true);
+  assert.equal(commandSupported(caps("navigateToPoint"), "navigate"), true);
+});
+
+test("an unknown command kind is refused, not defaulted", () => {
+  for (const kind of ["selfDestruct", "", null, undefined, "constructor"]) {
+    assert.equal(commandSupported(ALL, kind), false, String(kind));
+  }
+});
+
+/* --------------------------------------------------------------- registry */
+
+test("an adapter is found by brand, and never by fallback", () => {
+  clearRobotAdapters();
+  const a = { brand: "brand-a", displayName: "Brand A", capabilities: ALL, listRobots: async () => [], getRobot: async () => null };
+  registerRobotAdapter(a);
+
+  assert.equal(robotAdapterFor("brand-a"), a);
+  // Falling back to the only registered adapter would send one brand's robot a
+  // command in a protocol it does not speak.
+  assert.equal(robotAdapterFor("brand-b"), null);
+  assert.equal(robotAdapterFor(""), null);
+  assert.equal(robotAdapterFor(null), null);
+  assert.equal(robotAdapterFor(undefined), null);
+  assert.equal(robotAdapterFor(42), null);
+});
+
+test("an adapter without a brand is refused at registration", () => {
+  clearRobotAdapters();
+  assert.throws(() => registerRobotAdapter({ displayName: "x" }), /must name its brand/);
+  assert.throws(() => registerRobotAdapter(null), /must name its brand/);
+});
+
+test("the brand list reports each brand's tier, for a settings picker", () => {
+  clearRobotAdapters();
+  registerRobotAdapter({ brand: "good", displayName: "Good", capabilities: ALL, listRobots: async () => [], getRobot: async () => null });
+  registerRobotAdapter({ brand: "poor", displayName: "Poor", capabilities: caps("readLocation"), listRobots: async () => [], getRobot: async () => null });
+
+  assert.deepEqual(registeredRobotBrands().sort((x, y) => x.brand.localeCompare(y.brand)), [
+    { brand: "good", displayName: "Good", tier: "full-control" },
+    { brand: "poor", displayName: "Poor", tier: "no-interface" },
+  ]);
+});
+
+test("re-registering a brand replaces it rather than duplicating", () => {
+  clearRobotAdapters();
+  const base = { brand: "x", displayName: "One", capabilities: {}, listRobots: async () => [], getRobot: async () => null };
+  registerRobotAdapter(base);
+  registerRobotAdapter({ ...base, displayName: "Two" });
+
+  assert.equal(registeredRobotBrands().length, 1);
+  assert.equal(robotAdapterFor("x").displayName, "Two");
+});

package/test/robot-command.test.mjs

@@ -0,0 +1,140 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+
+import { parseRobotCommand } from "./.build/utils/robot-cloud.util.mjs";
+
+/* --------------------------------------------------------------------------
+ * POST /robots/:id/command is the only endpoint that makes a physical machine
+ * move, and the vendor API returns no command id - so a command sent wrongly
+ * cannot be identified afterwards, let alone cancelled on its own.
+ *
+ * The rule these guard: fields are REFUSED on the commands that do not use
+ * them, never ignored. Silently dropping a spot polygon from an area command
+ * would send the robot to clean the wrong thing and report success.
+ * ----------------------------------------------------------------------- */
+
+const ok = (body) => {
+  const r = parseRobotCommand(body);
+  assert.equal(r.ok, true, r.ok ? "" : r.message);
+  return r.command;
+};
+const bad = (body, re) => {
+  const r = parseRobotCommand(body);
+  assert.equal(r.ok, false, `expected refusal for ${JSON.stringify(body)}`);
+  if (re) assert.match(r.message, re);
+  return r.message;
+};
+
+const DEFAULTS = { cleanTimes: 1, modeFlag: 1, subModeFlag: 0, levelFlag: 1 };
+
+/* ------------------------------------------------------------- the kinds */
+
+test("a full clean takes the documented defaults", () => {
+  assert.deepEqual(ok({ kind: "full" }), { kind: "full", options: DEFAULTS });
+});
+
+test("an area clean carries its area names", () => {
+  assert.deepEqual(ok({ kind: "area", areas: ["AREA-FF0B0B83"] }), {
+    kind: "area",
+    areas: ["AREA-FF0B0B83"],
+    options: DEFAULTS,
+  });
+});
+
+test("a spot clean carries its polygon", () => {
+  const points = [
+    { x: 504, y: 416 }, { x: 504, y: 480 },
+    { x: 555, y: 480 }, { x: 555, y: 416 },
+  ];
+  assert.deepEqual(ok({ kind: "spot", points }), {
+    kind: "spot", points, options: DEFAULTS,
+  });
+});
+
+test("a return command carries nothing at all", () => {
+  assert.deepEqual(ok({ kind: "return" }), { kind: "return" });
+});
+
+test("an unknown kind is refused", () => {
+  for (const kind of ["mop", "", null, undefined, 1, "FULL"]) {
+    bad({ kind }, /kind must be one of/);
+  }
+  bad(null, /command body is required/);
+  bad("full", /command body is required/);
+});
+
+/* ------------------------------- fields refused where they do not belong */
+
+test("a spot polygon on an area command is REFUSED, not ignored", () => {
+  // Ignoring it would clean the wrong thing and report success.
+  bad({ kind: "area", areas: ["A"], points: [{ x: 1, y: 1 }] }, /points is only valid/);
+});
+
+test("area names on a spot or full command are refused", () => {
+  bad({ kind: "spot", points: [{x:1,y:1},{x:2,y:2},{x:3,y:3}], areas: ["A"] }, /areas is only valid/);
+  bad({ kind: "full", areas: ["A"] }, /areas is only valid/);
+});
+
+test("a return command refuses cleaning options and shapes", () => {
+  // Returning to dock has no mode, no level and no area.
+  for (const extra of [
+    { cleanTimes: 2 }, { modeFlag: 2 }, { subModeFlag: 1 }, { levelFlag: 3 },
+    { areas: ["A"] }, { points: [{ x: 1, y: 1 }] },
+  ]) {
+    bad({ kind: "return", ...extra }, /not valid for a return command/);
+  }
+});
+
+/* --------------------------------------------------------- option ranges */
+
+test("modeFlag, subModeFlag and levelFlag accept only their documented values", () => {
+  // 1 vacuum / 2 washing / 3 dry dust mop — confirmed against the three buttons
+  // on the robot's handlebar.
+  for (const v of [1, 2, 3]) assert.equal(ok({ kind: "full", modeFlag: v }).options.modeFlag, v);
+  for (const v of [0, 4, -1, 1.5, "1", null]) bad({ kind: "full", modeFlag: v }, /modeFlag/);
+
+  for (const v of [0, 1]) assert.equal(ok({ kind: "full", subModeFlag: v }).options.subModeFlag, v);
+  for (const v of [2, -1, "0"]) bad({ kind: "full", subModeFlag: v }, /subModeFlag/);
+
+  for (const v of [1, 2, 3]) assert.equal(ok({ kind: "full", levelFlag: v }).options.levelFlag, v);
+  for (const v of [0, 4, "2"]) bad({ kind: "full", levelFlag: v }, /levelFlag/);
+});
+
+test("cleanTimes accepts 0 (forever) through 99, and nothing else", () => {
+  assert.equal(ok({ kind: "full", cleanTimes: 0 }).options.cleanTimes, 0);
+  assert.equal(ok({ kind: "full", cleanTimes: 99 }).options.cleanTimes, 99);
+  for (const v of [-1, 100, 1.5, "3", null, NaN]) bad({ kind: "full", cleanTimes: v }, /cleanTimes/);
+});
+
+/* ------------------------------------------------------------- the shapes */
+
+test("an area command needs at least one real area name", () => {
+  bad({ kind: "area" }, /areas must be/);
+  bad({ kind: "area", areas: [] }, /areas must be/);
+  bad({ kind: "area", areas: [""] }, /areas must be/);
+  bad({ kind: "area", areas: [1, 2] }, /areas must be/);
+  bad({ kind: "area", areas: "AREA-1" }, /areas must be/);
+});
+
+test("a spot command needs at least 3 points — fewer cannot enclose anything", () => {
+  bad({ kind: "spot" }, /at least 3/);
+  bad({ kind: "spot", points: [{ x: 1, y: 1 }] }, /at least 3/);
+  bad({ kind: "spot", points: [{ x: 1, y: 1 }, { x: 2, y: 2 }] }, /at least 3/);
+});
+
+test("a spot point must be two finite numbers", () => {
+  const three = (p) => [{ x: 1, y: 1 }, { x: 2, y: 2 }, p];
+  for (const p of [
+    { x: 1 }, { y: 1 }, { x: "1", y: 1 }, { x: 1, y: null },
+    { x: 1e999, y: 1 }, null, "1,1", [1, 1],
+  ]) {
+    bad({ kind: "spot", points: three(p) }, /points must be/);
+  }
+});
+
+test("a prototype key cannot masquerade as a command field", () => {
+  // hasOwnProperty, not a bare `in` — otherwise "constructor" reads as present.
+  const cmd = ok({ kind: "full" });
+  assert.deepEqual(cmd.options, DEFAULTS);
+  assert.equal(parseRobotCommand({ kind: "return", constructor: 1 }).ok, true);
+});