signalk-race-control 0.12.0 → 0.12.2

package/index.js

@@ -3224,3 +3224,37 @@ module.exports = function (app) {
 
   return plugin;
 };
+
+// Exposes the pure, top-level helper functions above for unit testing —
+// none of this runs, or is even looked at, when SignalK loads the plugin
+// via `require('signalk-race-control')(app)`; it's a plain extra property
+// on the exported factory function, purely for `test/*.test.js` to import
+// without instantiating a whole plugin + mock app for logic that doesn't
+// need one.
+module.exports.internal = {
+  parseCsvText,
+  parseNorwegianNumber,
+  parseHandicapSheet,
+  stripHtmlToText,
+  parseKtkHtml,
+  extractGoogleSheetId,
+  parseManage2SailEventPage,
+  parseManage2SailEntries,
+  findHandicapSystem,
+  resolveHandicapSystem,
+  makeRaceId,
+  makeBoatId,
+  makeClassId,
+  raceSummary,
+  emptyCourse,
+  ensureRaceShape,
+  findClass,
+  effectiveStartTime,
+  distanceNm,
+  midpoint,
+  segmentsIntersect,
+  validateCoordPoint,
+  validateLine,
+  formatLocalDateTime,
+  buildOfflineTimerHtml
+};

package/package.json

@@ -1,19 +1,29 @@
 {
   "name": "signalk-race-control",
-  "version": "0.12.0",
+  "version": "0.12.2",
   "description": "SignalK plugin and webapp for tracking elapsed and handicap-corrected (Time-on-Time) race time, with a per-boat editable TCF and boat names pulled from AIS when available.",
   "main": "index.js",
   "author": "Joachim Bakke <github@heiamoss.com>",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/joabakk/signalk-race-control.git"
+  },
   "keywords": [
     "signalk-node-server-plugin",
     "signalk-webapp",
     "signalk-category-race"
   ],
   "engines": {
-    "node": ">=14"
+    "node": ">=18"
   },
   "license": "MIT",
+  "scripts": {
+    "test": "node --test"
+  },
   "dependencies": {
     "exceljs": "^4.4.0"
+  },
+  "overrides": {
+    "uuid": "^11.1.1"
   }
 }

package/public/app.js

@@ -2999,8 +2999,14 @@
         : tsToTimeInputValue(raceState.startTime);
     }
 
+    if (document.activeElement !== scheduleInput) {
+      scheduleInput.value = tsToDateTimeInputValue(raceState.scheduledStart);
+    }
     scheduleInput.disabled = !!raceState.startTime;
     scheduleBtn.disabled = !!raceState.startTime;
+    scheduleBtn.textContent = raceState.scheduledStart
+      ? 'Scheduled: ' + new Date(raceState.scheduledStart).toLocaleString()
+      : 'Schedule Start';
     cancelScheduleBtn.hidden = !raceState.scheduledStart || !!raceState.startTime;
 
     callOffInput.type = raceState.multiDay ? 'datetime-local' : 'time';

package/test/geometry.test.js

@@ -0,0 +1,110 @@
+const { test, describe } = require('node:test');
+const assert = require('node:assert/strict');
+const { distanceNm, midpoint, segmentsIntersect, validateCoordPoint, validateLine } = require('../index.js').internal;
+
+describe('distanceNm', () => {
+  test('is zero for the same point', () => {
+    assert.equal(distanceNm({ lat: 59.7, lon: 10.5 }, { lat: 59.7, lon: 10.5 }), 0);
+  });
+
+  test('one degree of latitude is ~60nm', () => {
+    const nm = distanceNm({ lat: 59, lon: 10 }, { lat: 60, lon: 10 });
+    assert.ok(Math.abs(nm - 60) < 1, `expected ~60nm, got ${nm}`);
+  });
+
+  test('is symmetric', () => {
+    const a = { lat: 59.72, lon: 10.54 };
+    const b = { lat: 59.68, lon: 10.56 };
+    assert.equal(distanceNm(a, b), distanceNm(b, a));
+  });
+});
+
+describe('midpoint', () => {
+  test('averages lat/lon', () => {
+    const m = midpoint({ lat: 59.7, lon: 10.5 }, { lat: 59.8, lon: 10.7 });
+    assert.equal(m.lat, 59.75);
+    assert.equal(m.lon, 10.6);
+  });
+});
+
+describe('segmentsIntersect', () => {
+  // A start line running roughly east-west, matching the shape of a real
+  // one in this app (pin + committee boat).
+  const startLineA = { lat: 59.723876, lon: 10.543537 };
+  const startLineB = { lat: 59.7257498, lon: 10.5352725 };
+
+  test('detects a genuine crossing from one side to the other', () => {
+    const before = { lat: 59.7242279, lon: 10.5392721 };
+    const after = { lat: 59.7253979, lon: 10.5395375 };
+    assert.equal(segmentsIntersect(before, after, startLineA, startLineB), true);
+  });
+
+  test('does not fire for a track that stays on one side', () => {
+    const p1 = { lat: 59.72, lon: 10.53 };
+    const p2 = { lat: 59.721, lon: 10.531 };
+    assert.equal(segmentsIntersect(p1, p2, startLineA, startLineB), false);
+  });
+
+  test('does not fire for a track that passes near but short of the line', () => {
+    // Heads toward the line's midpoint but stops well before reaching it.
+    const near = midpoint(startLineA, startLineB);
+    const short = { lat: (startLineA.lat + near.lat) / 2 - 0.01, lon: (startLineA.lon + near.lon) / 2 };
+    const shorter = { lat: short.lat + 0.0001, lon: short.lon + 0.0001 };
+    assert.equal(segmentsIntersect(short, shorter, startLineA, startLineB), false);
+  });
+
+  test('is symmetric in which segment is "the line" vs "the track"', () => {
+    const before = { lat: 59.7242279, lon: 10.5392721 };
+    const after = { lat: 59.7253979, lon: 10.5395375 };
+    assert.equal(
+      segmentsIntersect(before, after, startLineA, startLineB),
+      segmentsIntersect(startLineA, startLineB, before, after)
+    );
+  });
+});
+
+describe('validateCoordPoint', () => {
+  test('accepts a plain lat/lon', () => {
+    assert.deepEqual(validateCoordPoint({ lat: 59.7, lon: 10.5 }), { lat: 59.7, lon: 10.5 });
+  });
+
+  test('keeps a trimmed name when present', () => {
+    assert.deepEqual(validateCoordPoint({ lat: 1, lon: 2, name: '  Mark 1  ' }), { lat: 1, lon: 2, name: 'Mark 1' });
+  });
+
+  test('omits an empty/whitespace-only name rather than keeping ""', () => {
+    const out = validateCoordPoint({ lat: 1, lon: 2, name: '   ' });
+    assert.ok(!('name' in out));
+  });
+
+  const badPoints = [null, undefined, {}, { lat: 'x', lon: 2 }, { lat: 1, lon: NaN }, { lat: 91, lon: 0 }, { lat: -91, lon: 0 }, { lat: 0, lon: 181 }, { lat: 0, lon: -181 }];
+  for (const bad of badPoints) {
+    test(`rejects ${JSON.stringify(bad)}`, () => {
+      assert.equal(validateCoordPoint(bad), null);
+    });
+  }
+});
+
+describe('validateLine', () => {
+  test('null passes through as null (an explicitly cleared line)', () => {
+    assert.equal(validateLine(null), null);
+  });
+
+  test('validates both ends of a proper pair', () => {
+    const out = validateLine([{ lat: 1, lon: 2 }, { lat: 3, lon: 4 }]);
+    assert.deepEqual(out, [{ lat: 1, lon: 2 }, { lat: 3, lon: 4 }]);
+  });
+
+  test('undefined (invalid) for the wrong array length', () => {
+    assert.equal(validateLine([{ lat: 1, lon: 2 }]), undefined);
+    assert.equal(validateLine([{ lat: 1, lon: 2 }, { lat: 3, lon: 4 }, { lat: 5, lon: 6 }]), undefined);
+  });
+
+  test('undefined (invalid) when either end fails validation', () => {
+    assert.equal(validateLine([{ lat: 1, lon: 2 }, { lat: 'x', lon: 4 }]), undefined);
+  });
+
+  test('undefined (invalid) for a non-array', () => {
+    assert.equal(validateLine('not an array'), undefined);
+  });
+});

package/test/parsing.test.js

@@ -0,0 +1,246 @@
+const { test, describe } = require('node:test');
+const assert = require('node:assert/strict');
+const {
+  parseCsvText,
+  parseNorwegianNumber,
+  parseHandicapSheet,
+  stripHtmlToText,
+  parseKtkHtml,
+  extractGoogleSheetId,
+  parseManage2SailEventPage,
+  parseManage2SailEntries,
+  findHandicapSystem,
+  resolveHandicapSystem
+} = require('../index.js').internal;
+
+describe('parseCsvText', () => {
+  test('splits plain comma-separated rows', () => {
+    assert.deepEqual(parseCsvText('a,b,c\n1,2,3'), [
+      ['a', 'b', 'c'],
+      ['1', '2', '3']
+    ]);
+  });
+
+  test('keeps a comma inside a quoted field as part of that field', () => {
+    assert.deepEqual(parseCsvText('name,value\nSolli,"1,050"'), [
+      ['name', 'value'],
+      ['Solli', '1,050']
+    ]);
+  });
+
+  test('un-escapes a doubled quote inside a quoted field', () => {
+    assert.deepEqual(parseCsvText('a\n"say ""hi"""'), [['a'], ['say "hi"']]);
+  });
+
+  test('drops \\r before \\n but keeps rows intact', () => {
+    assert.deepEqual(parseCsvText('a,b\r\n1,2\r\n'), [
+      ['a', 'b'],
+      ['1', '2']
+    ]);
+  });
+});
+
+describe('parseNorwegianNumber', () => {
+  test('treats a comma as the decimal separator', () => {
+    assert.equal(parseNorwegianNumber('1,05'), 1.05);
+  });
+
+  test('still accepts a plain dot', () => {
+    assert.equal(parseNorwegianNumber('1.05'), 1.05);
+  });
+
+  test('null for null/undefined/blank input', () => {
+    assert.equal(parseNorwegianNumber(null), null);
+    assert.equal(parseNorwegianNumber(undefined), null);
+    assert.equal(parseNorwegianNumber('   '), null);
+  });
+
+  test('null for non-numeric text', () => {
+    assert.equal(parseNorwegianNumber('n/a'), null);
+  });
+});
+
+describe('parseHandicapSheet', () => {
+  const csv = [
+    'SSCA VET-tall 2026',
+    ',,,,,',
+    'Båt,Gyldig,Seilføring,VET 1,Klasse,Eier',
+    'RS 21 Solli,OK,Uten spinnaker,"1,050",IRC,Bakke',
+    ',,,,,', // blank name — must be skipped
+    'No Vets,OK,,,IRC,Nobody' // no parseable VET value — must be skipped
+  ].join('\n');
+
+  test('finds the header row and reads boats after it', () => {
+    const boats = parseHandicapSheet(csv);
+    assert.equal(boats.length, 1);
+    assert.equal(boats[0].name, 'RS 21 Solli');
+    assert.equal(boats[0].validity, 'OK');
+    assert.equal(boats[0].class, 'IRC');
+    assert.equal(boats[0].owner, 'Bakke');
+  });
+
+  test('reads the VET value and its label from the column before it', () => {
+    const boats = parseHandicapSheet(csv);
+    assert.deepEqual(boats[0].vets, [{ label: 'Uten spinnaker', value: 1.05 }]);
+  });
+
+  test('throws when the header row cannot be found', () => {
+    assert.throws(() => parseHandicapSheet('just,some,junk\n1,2,3'), /header row/);
+  });
+
+  test('falls back to a generic "VET n" label when the label column is blank', () => {
+    const noLabelCsv = ['Båt,Gyldig,,VET 1,Klasse', 'Solveig,OK,,"1,20",IRC'].join('\n');
+    const boats = parseHandicapSheet(noLabelCsv);
+    assert.equal(boats[0].vets[0].label, 'VET 1');
+  });
+});
+
+describe('stripHtmlToText', () => {
+  test('removes tags and decodes the entities this app actually emits', () => {
+    assert.equal(stripHtmlToText('<td>Solveig&nbsp;II &amp; co</td>'), 'Solveig II & co');
+  });
+
+  test('trims surrounding whitespace', () => {
+    assert.equal(stripHtmlToText('  <b>hi</b>  '), 'hi');
+  });
+});
+
+describe('parseKtkHtml', () => {
+  test('throws when there is no table on the page', () => {
+    assert.throws(() => parseKtkHtml('<html><body>no table here</body></html>'), /KLR table/);
+  });
+
+  test('parses one boat, one KLR value, plain "KLR" label', () => {
+    const html = '<table><tr><td>Boat</td><td>KLR</td></tr><tr><td>Njord</td><td>166</td></tr></table>';
+    const boats = parseKtkHtml(html);
+    assert.equal(boats.length, 1);
+    assert.equal(boats[0].name, 'Njord');
+    assert.deepEqual(boats[0].vets, [{ label: 'KLR', value: 1.66, raw: 166 }]);
+  });
+
+  test('groups multiple rows for the same boat (case-insensitively) and numbers the labels', () => {
+    const html =
+      '<table>' +
+      '<tr><td>Boat</td><td>KLR</td></tr>' +
+      '<tr><td>Solveig</td><td>166</td></tr>' +
+      '<tr><td>solveig</td><td>170</td></tr>' +
+      '</table>';
+    const boats = parseKtkHtml(html);
+    assert.equal(boats.length, 1);
+    assert.deepEqual(boats[0].vets, [
+      { label: 'KLR 1', value: 1.66, raw: 166 },
+      { label: 'KLR 2', value: 1.7, raw: 170 }
+    ]);
+  });
+
+  test('skips a row whose second cell is not a usable positive number', () => {
+    const html = '<table><tr><td>Boat</td><td>KLR</td></tr><tr><td>Njord</td><td>n/a</td></tr></table>';
+    assert.deepEqual(parseKtkHtml(html), []);
+  });
+});
+
+describe('extractGoogleSheetId', () => {
+  test('pulls the id out of a full sheets URL', () => {
+    assert.equal(
+      extractGoogleSheetId('https://docs.google.com/spreadsheets/d/1AbC-xyz_123/edit#gid=0'),
+      '1AbC-xyz_123'
+    );
+  });
+
+  test('null when no sheets link is present', () => {
+    assert.equal(extractGoogleSheetId('nothing relevant here'), null);
+  });
+});
+
+describe('parseManage2SailEventPage', () => {
+  const eventId = '12345678-1234-1234-1234-123456789012';
+  const html = `
+    <a href="/en-US/support/EventIssue?eventId=${eventId}">Report an issue</a>
+    <script>window.boostrapedResourceData = {"Regatta":[{"Id":"r1","Name":"ORC A"},{"Id":"r2","Name":"ORC B"}]};</script>
+  `;
+
+  test('extracts the event id and class list', () => {
+    const result = parseManage2SailEventPage(html);
+    assert.equal(result.eventId, eventId);
+    assert.deepEqual(result.classes, [
+      { id: 'r1', name: 'ORC A' },
+      { id: 'r2', name: 'ORC B' }
+    ]);
+  });
+
+  test('throws when the event id is missing', () => {
+    assert.throws(() => parseManage2SailEventPage('<html>nothing here</html>'), /event's id/);
+  });
+
+  test('throws when the resource data script is missing', () => {
+    assert.throws(
+      () => parseManage2SailEventPage(`<a href="/EventIssue?eventId=${eventId}"></a>`),
+      /class data/
+    );
+  });
+});
+
+describe('parseManage2SailEntries', () => {
+  test('picks a display name from the first available field, in priority order', () => {
+    const json = {
+      HcpName: 'YS',
+      Entries: [
+        { BoatName: 'Njord', SailNumber: 'NOR 1', Hcp: '95' },
+        { SailNumber: 'NOR 2', TeamName: 'Team Two', Hcp: '100' },
+        { TeamName: 'Team Three', SkipperName: 'Skipper Three', Hcp: '105' },
+        { SkipperName: 'Skipper Four', Hcp: '110' }
+      ]
+    };
+    const result = parseManage2SailEntries(json);
+    assert.deepEqual(result.entries.map((e) => e.name), ['Njord', 'NOR 2', 'Team Three', 'Skipper Four']);
+  });
+
+  test('accepts a comma decimal in Hcp', () => {
+    const result = parseManage2SailEntries({ Entries: [{ BoatName: 'Njord', Hcp: '95,5' }] });
+    assert.equal(result.entries[0].hcp, 95.5);
+  });
+
+  test('skips entries with no usable name or a non-positive/invalid Hcp', () => {
+    const json = {
+      Entries: [
+        { Hcp: '95' }, // no name at all
+        { BoatName: 'Njord', Hcp: '0' }, // zero
+        { BoatName: 'Njord', Hcp: 'n/a' } // unparseable
+      ]
+    };
+    const result = parseManage2SailEntries(json);
+    assert.equal(result.entries.length, 0);
+    assert.equal(result.skipped, 3);
+  });
+});
+
+describe('findHandicapSystem / resolveHandicapSystem', () => {
+  test('findHandicapSystem looks up by key', () => {
+    assert.equal(findHandicapSystem('py').key, 'py');
+    assert.equal(findHandicapSystem('nope'), null);
+  });
+
+  test('resolves YS on DSV-scale values (40-250) to "ys"', () => {
+    assert.deepEqual(resolveHandicapSystem('YS', [95, 100, 110]), { resolved: 'ys' });
+  });
+
+  test('resolves YS on RYA-scale values (400-3000) to "py"', () => {
+    assert.deepEqual(resolveHandicapSystem('YS', [950, 1000, 1100]), { resolved: 'py' });
+  });
+
+  test('reports candidates when YS values fit neither scale unambiguously', () => {
+    const result = resolveHandicapSystem('YS', [300]);
+    assert.equal(result.resolved, null);
+    assert.deepEqual(result.candidates, ['ys', 'py', 'tcf']);
+  });
+
+  test('PY/PN always resolves to "py" regardless of values', () => {
+    assert.deepEqual(resolveHandicapSystem('PY', []), { resolved: 'py' });
+    assert.deepEqual(resolveHandicapSystem('PN', [1]), { resolved: 'py' });
+  });
+
+  test('an unrecognized/blank name defaults to "tcf"', () => {
+    assert.deepEqual(resolveHandicapSystem('', []), { resolved: 'tcf' });
+    assert.deepEqual(resolveHandicapSystem('ORC', [1.05]), { resolved: 'tcf' });
+  });
+});

package/test/plugin.test.js

@@ -0,0 +1,328 @@
+const { test, describe, before, after } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const pluginFactory = require('../index.js');
+
+// ---- Minimal SignalK app + Express-router mocks --------------------------
+// Just enough surface for the plugin to run its full HTTP-facing behavior
+// without a real SignalK server: a scratch data directory for race-state.json,
+// and no-op stubs for everything optional (resourcesApi, activateRoute,
+// getSelfPath/getPath) so those best-effort code paths cleanly no-op, the
+// same as they do on a real server with no resources provider configured.
+
+function makeApp(dataDir) {
+  return {
+    getDataDirPath: () => dataDir,
+    setPluginStatus: () => {},
+    debug: () => {},
+    error: () => {}
+    // getSelfPath / getPath / resourcesApi / activateRoute deliberately
+    // absent — every call site already guards for that.
+  };
+}
+
+function makeRouter() {
+  const routes = [];
+  const register = (method) => (routePath, handler) => {
+    const keys = [];
+    const patternSrc = routePath.replace(/:[A-Za-z]+/g, (m) => {
+      keys.push(m.slice(1));
+      return '([^/]+)';
+    });
+    routes.push({ method, pattern: new RegExp(`^${patternSrc}$`), keys, handler });
+  };
+  return {
+    get: register('GET'),
+    post: register('POST'),
+    put: register('PUT'),
+    delete: register('DELETE'),
+    _routes: routes
+  };
+}
+
+// Invokes a registered route handler as Express would, minus anything this
+// plugin's handlers never rely on (headers, streaming, middleware order).
+function call(router, method, routePath, { body, query } = {}) {
+  const [pathname, qs] = routePath.split('?');
+  const route = router._routes.find((r) => r.method === method && r.pattern.test(pathname));
+  if (!route) throw new Error(`No route registered for ${method} ${routePath}`);
+  const match = route.pattern.exec(pathname);
+  const params = {};
+  route.keys.forEach((k, i) => {
+    params[k] = decodeURIComponent(match[i + 1]);
+  });
+  const parsedQuery = query || Object.fromEntries(new URLSearchParams(qs || ''));
+
+  return new Promise((resolve) => {
+    let statusCode = 200;
+    let settled = false;
+    const settle = (payload) => {
+      if (settled) return;
+      settled = true;
+      resolve({ status: statusCode, body: payload });
+    };
+    const res = {
+      status(code) {
+        statusCode = code;
+        return this;
+      },
+      json: settle,
+      send: settle
+    };
+    const req = { params, query: parsedQuery, body: body === undefined ? {} : body };
+    try {
+      const result = route.handler(req, res);
+      if (result && typeof result.catch === 'function') {
+        result.catch((e) => settle({ error: e.message }));
+      }
+    } catch (e) {
+      settle({ error: e.message });
+    }
+  });
+}
+
+describe('plugin shape', () => {
+  test('exposes the standard SignalK plugin interface', () => {
+    const dataDir = fs.mkdtempSync(path.join(os.tmpdir(), 'race-control-test-'));
+    const plugin = pluginFactory(makeApp(dataDir));
+    assert.equal(plugin.id, 'race-control');
+    assert.equal(plugin.name, 'Race Control');
+    assert.equal(typeof plugin.schema, 'object');
+    assert.equal(typeof plugin.start, 'function');
+    assert.equal(typeof plugin.stop, 'function');
+    assert.equal(typeof plugin.registerWithRouter, 'function');
+  });
+});
+
+describe('REST API — full race lifecycle', () => {
+  let plugin;
+  let router;
+  let raceId;
+
+  before(() => {
+    const dataDir = fs.mkdtempSync(path.join(os.tmpdir(), 'race-control-test-'));
+    plugin = pluginFactory(makeApp(dataDir));
+    plugin.start({});
+    router = makeRouter();
+    plugin.registerWithRouter(router);
+  });
+
+  after(() => {
+    plugin.stop();
+  });
+
+  test('POST /races rejects a blank name', async () => {
+    const res = await call(router, 'POST', '/races', { body: { name: '  ' } });
+    assert.equal(res.status, 400);
+  });
+
+  test('POST /races creates a race and makes it current', async () => {
+    const res = await call(router, 'POST', '/races', { body: { name: 'Onsdagsseilas' } });
+    assert.equal(res.status, 200);
+    assert.equal(res.body.race.name, 'Onsdagsseilas');
+    assert.equal(res.body.currentRaceId, res.body.race.id);
+    assert.deepEqual(res.body.race.course, { startLine: null, marks: [], finishLine: null });
+    raceId = res.body.race.id;
+  });
+
+  test('GET /races lists the created race', async () => {
+    const res = await call(router, 'GET', '/races');
+    assert.equal(res.status, 200);
+    assert.ok(res.body.races.some((r) => r.id === raceId));
+  });
+
+  test('GET /races/:id 404s for an unknown id', async () => {
+    const res = await call(router, 'GET', '/races/does-not-exist');
+    assert.equal(res.status, 404);
+  });
+
+  test('GET /races/:id returns the full race', async () => {
+    const res = await call(router, 'GET', `/races/${raceId}`);
+    assert.equal(res.status, 200);
+    assert.equal(res.body.id, raceId);
+  });
+
+  test('PUT /races/:id/course rejects an invalid mark', async () => {
+    const res = await call(router, 'PUT', `/races/${raceId}/course`, {
+      body: { marks: [{ lat: 'not a number', lon: 10.5 }] }
+    });
+    assert.equal(res.status, 400);
+  });
+
+  test('PUT /races/:id/course accepts a valid start/finish/marks', async () => {
+    const res = await call(router, 'PUT', `/races/${raceId}/course`, {
+      body: {
+        startLine: [{ lat: 59.723876, lon: 10.543537, name: 'Pin' }, { lat: 59.7257498, lon: 10.5352725, name: 'Committee' }],
+        finishLine: [{ lat: 59.681879, lon: 10.5640363 }, { lat: 59.6769532, lon: 10.5623646 }],
+        marks: [{ id: 'm1', lat: 59.7, lon: 10.55, name: 'Mark 1' }]
+      }
+    });
+    assert.equal(res.status, 200);
+    assert.equal(res.body.course.marks.length, 1);
+    assert.equal(res.body.course.startLine[0].name, 'Pin');
+  });
+
+  let boatId;
+  let classId;
+
+  test('POST /races/:id/boats rejects a blank name', async () => {
+    const res = await call(router, 'POST', `/races/${raceId}/boats`, { body: { name: '' } });
+    assert.equal(res.status, 400);
+  });
+
+  test('POST /races/:id/boats adds a boat', async () => {
+    const res = await call(router, 'POST', `/races/${raceId}/boats`, { body: { name: 'RS 21 Solli' } });
+    assert.equal(res.status, 200);
+    assert.equal(res.body.name, 'RS 21 Solli');
+    assert.equal(res.body.finishTime, null);
+    assert.equal(res.body.classId, null);
+    boatId = res.body.id;
+  });
+
+  test('POST /races/:id/classes adds a class', async () => {
+    const res = await call(router, 'POST', `/races/${raceId}/classes`, { body: { name: 'Cruisers' } });
+    assert.equal(res.status, 200);
+    assert.equal(res.body.classes.length, 1);
+    classId = res.body.classes[0].id;
+  });
+
+  test('PUT boat class rejects an unknown class id', async () => {
+    const res = await call(router, 'PUT', `/races/${raceId}/boats/${boatId}/class`, { body: { classId: 'nope' } });
+    assert.equal(res.status, 400);
+  });
+
+  test('PUT boat class assigns a real class', async () => {
+    const res = await call(router, 'PUT', `/races/${raceId}/boats/${boatId}/class`, { body: { classId } });
+    assert.equal(res.status, 200);
+    assert.equal(res.body.classId, classId);
+  });
+
+  test("PUT class startTime sets the class's staggered start", async () => {
+    const res = await call(router, 'PUT', `/races/${raceId}/classes/${classId}/startTime`, { body: { startTime: 5000 } });
+    assert.equal(res.status, 200);
+    assert.equal(res.body.classes[0].startTime, 5000);
+  });
+
+  test('POST /races/:id/start sets startTime and resets courseActivated', async () => {
+    const res = await call(router, 'POST', `/races/${raceId}/start`);
+    assert.equal(res.status, 200);
+    assert.ok(res.body.startTime > 0);
+    assert.equal(res.body.courseActivated, false);
+  });
+
+  test('PUT boat finishTime rejects a non-numeric/zero value', async () => {
+    const res = await call(router, 'PUT', `/races/${raceId}/boats/${boatId}/finishTime`, { body: { finishTime: 0 } });
+    assert.equal(res.status, 400);
+  });
+
+  test('PUT boat finishTime records a finish and clears dnf/dns', async () => {
+    const res = await call(router, 'PUT', `/races/${raceId}/boats/${boatId}/finishTime`, { body: { finishTime: Date.now() } });
+    assert.equal(res.status, 200);
+    assert.ok(res.body.finishTime > 0);
+    assert.equal(res.body.dnf, false);
+    assert.equal(res.body.dns, false);
+  });
+
+  test('PUT boat dnf clears the finish time it just set', async () => {
+    const res = await call(router, 'PUT', `/races/${raceId}/boats/${boatId}/dnf`, { body: { dnf: true } });
+    assert.equal(res.status, 200);
+    assert.equal(res.body.dnf, true);
+    assert.equal(res.body.finishTime, null);
+  });
+
+  test('PUT boat dns clears dnf (mutually exclusive states)', async () => {
+    const res = await call(router, 'PUT', `/races/${raceId}/boats/${boatId}/dns`, { body: { dns: true } });
+    assert.equal(res.status, 200);
+    assert.equal(res.body.dns, true);
+    assert.equal(res.body.dnf, false);
+  });
+
+  test('POST /races/:id/reset clears start time, class start times, and boat race state', async () => {
+    const res = await call(router, 'POST', `/races/${raceId}/reset`);
+    assert.equal(res.status, 200);
+    assert.equal(res.body.startTime, null);
+    assert.equal(res.body.classes[0].startTime, null);
+    const boat = Object.values(res.body.boats)[0];
+    assert.equal(boat.dns, false);
+    assert.equal(boat.dnf, false);
+    assert.equal(boat.finishTime, null);
+    // Boats and their class assignment survive a reset — only race/start
+    // state is cleared.
+    assert.equal(boat.classId, classId);
+  });
+
+  test('DELETE boat removes it', async () => {
+    const res = await call(router, 'DELETE', `/races/${raceId}/boats/${boatId}`);
+    assert.equal(res.status, 200);
+    const check = await call(router, 'GET', `/races/${raceId}`);
+    assert.equal(Object.keys(check.body.boats).length, 0);
+  });
+
+  test('DELETE class 404s for an unknown class', async () => {
+    const res = await call(router, 'DELETE', `/races/${raceId}/classes/nope`);
+    assert.equal(res.status, 404);
+  });
+
+  test('DELETE class removes it', async () => {
+    const res = await call(router, 'DELETE', `/races/${raceId}/classes/${classId}`);
+    assert.equal(res.status, 200);
+    assert.equal(res.body.classes.length, 0);
+  });
+
+  test('DELETE /races/:id removes the race entirely', async () => {
+    const res = await call(router, 'DELETE', `/races/${raceId}`);
+    assert.equal(res.status, 200);
+    const check = await call(router, 'GET', `/races/${raceId}`);
+    assert.equal(check.status, 404);
+  });
+});
+
+describe('/overpass proxy — falls back across mirrors', () => {
+  let plugin;
+  let router;
+  let originalFetch;
+
+  before(() => {
+    const dataDir = fs.mkdtempSync(path.join(os.tmpdir(), 'race-control-test-'));
+    plugin = pluginFactory(makeApp(dataDir));
+    plugin.start({});
+    router = makeRouter();
+    plugin.registerWithRouter(router);
+    originalFetch = global.fetch;
+  });
+
+  after(() => {
+    plugin.stop();
+    global.fetch = originalFetch;
+  });
+
+  test('400s when the query is missing', async () => {
+    const res = await call(router, 'GET', '/overpass');
+    assert.equal(res.status, 400);
+  });
+
+  test('falls through a failing mirror to the next and returns its data', async () => {
+    let calls = 0;
+    global.fetch = async () => {
+      calls++;
+      if (calls === 1) throw new Error('mirror unreachable');
+      return { ok: true, json: async () => ({ elements: [{ id: 1, tags: { 'seamark:name': 'Test Mark' } }] }) };
+    };
+    const res = await call(router, 'GET', '/overpass?data=%5Bout%3Ajson%5D');
+    assert.equal(res.status, 200);
+    assert.equal(res.body.elements[0].tags['seamark:name'], 'Test Mark');
+    assert.ok(calls >= 2, 'expected at least 2 mirror attempts after the first failure');
+  });
+
+  test('returns an empty element list when every mirror fails', async () => {
+    global.fetch = async () => {
+      throw new Error('unreachable');
+    };
+    const res = await call(router, 'GET', '/overpass?data=%5Bout%3Ajson%5D');
+    assert.equal(res.status, 200);
+    assert.deepEqual(res.body.elements, []);
+  });
+});

package/test/race-shape.test.js

@@ -0,0 +1,159 @@
+const { test, describe } = require('node:test');
+const assert = require('node:assert/strict');
+const { ensureRaceShape, effectiveStartTime, findClass, raceSummary, emptyCourse } = require('../index.js').internal;
+
+function bareRace(overrides) {
+  return Object.assign(
+    {
+      id: 'r1',
+      name: 'Test Race',
+      boats: {}
+    },
+    overrides
+  );
+}
+
+describe('emptyCourse', () => {
+  test('has null lines and no marks', () => {
+    assert.deepEqual(emptyCourse(), { startLine: null, marks: [], finishLine: null });
+  });
+});
+
+describe('ensureRaceShape', () => {
+  test('backfills every optional field on a bare/legacy race', () => {
+    const race = bareRace();
+    ensureRaceShape(race);
+    assert.deepEqual(race.course, { startLine: null, marks: [], finishLine: null });
+    assert.equal(race.selfBoatId, null);
+    assert.equal(race.stopTime, null);
+    assert.equal(race.scheduledCallOff, null);
+    assert.equal(race.multiDay, false);
+    assert.equal(race.courseActivated, false);
+    assert.deepEqual(race.classes, []);
+  });
+
+  test('leaves already-present fields alone', () => {
+    const race = bareRace({ multiDay: true, courseActivated: true, selfBoatId: 'b1' });
+    ensureRaceShape(race);
+    assert.equal(race.multiDay, true);
+    assert.equal(race.courseActivated, true);
+    assert.equal(race.selfBoatId, 'b1');
+  });
+
+  test('backfills every optional boat field', () => {
+    const race = bareRace({ boats: { b1: { id: 'b1', name: 'Solli' } } });
+    ensureRaceShape(race);
+    const b = race.boats.b1;
+    assert.deepEqual(b.track, []);
+    assert.equal(b.dnf, false);
+    assert.equal(b.dns, false);
+    assert.equal(b.dnfPosition, null);
+    assert.equal(b.startTime, null);
+    assert.equal(b.sailNumber, null);
+    assert.equal(b.classId, null);
+    assert.deepEqual(b.markTimes, {});
+  });
+
+  test('backfills a startTime on every class', () => {
+    const race = bareRace({ classes: [{ id: 'c1', name: 'Cruisers' }] });
+    ensureRaceShape(race);
+    assert.equal(race.classes[0].startTime, null);
+  });
+
+  test('clears a boat classId that no longer matches any class (deleted class)', () => {
+    const race = bareRace({
+      classes: [{ id: 'c1', name: 'Cruisers', startTime: null }],
+      boats: {
+        b1: { id: 'b1', name: 'Stays', classId: 'c1' },
+        b2: { id: 'b2', name: 'Stale', classId: 'c-deleted' }
+      }
+    });
+    ensureRaceShape(race);
+    assert.equal(race.boats.b1.classId, 'c1');
+    assert.equal(race.boats.b2.classId, null);
+  });
+
+  test('is idempotent — running it twice changes nothing further', () => {
+    const race = bareRace({ boats: { b1: { id: 'b1', name: 'Solli' } } });
+    ensureRaceShape(race);
+    const once = JSON.stringify(race);
+    ensureRaceShape(race);
+    assert.equal(JSON.stringify(race), once);
+  });
+});
+
+describe('findClass', () => {
+  test('finds a class by id', () => {
+    const race = bareRace({ classes: [{ id: 'c1', name: 'Cruisers' }, { id: 'c2', name: 'Racers' }] });
+    assert.equal(findClass(race, 'c2').name, 'Racers');
+  });
+
+  test('returns null for an unknown id', () => {
+    const race = bareRace({ classes: [{ id: 'c1', name: 'Cruisers' }] });
+    assert.equal(findClass(race, 'nope'), null);
+  });
+
+  test('returns null when the race has no classes array at all', () => {
+    assert.equal(findClass(bareRace(), 'c1'), null);
+  });
+});
+
+describe('effectiveStartTime — priority chain: boat > class > race', () => {
+  test("falls back to the race's own start time with no boat or class override", () => {
+    const race = bareRace({ startTime: 1000, classes: [] });
+    const boat = { classId: null, startTime: null };
+    assert.equal(effectiveStartTime(race, boat), 1000);
+  });
+
+  test("falls back to the boat's class start time over the race's", () => {
+    const race = bareRace({ startTime: 1000, classes: [{ id: 'c1', name: 'Cruisers', startTime: 2000 }] });
+    const boat = { classId: 'c1', startTime: null };
+    assert.equal(effectiveStartTime(race, boat), 2000);
+  });
+
+  test("a boat's own start time wins over its class's", () => {
+    const race = bareRace({ startTime: 1000, classes: [{ id: 'c1', name: 'Cruisers', startTime: 2000 }] });
+    const boat = { classId: 'c1', startTime: 3000 };
+    assert.equal(effectiveStartTime(race, boat), 3000);
+  });
+
+  test("a boat's own start time wins even with no class at all", () => {
+    const race = bareRace({ startTime: 1000, classes: [] });
+    const boat = { classId: null, startTime: 3000 };
+    assert.equal(effectiveStartTime(race, boat), 3000);
+  });
+
+  test('falls through to the race start when the boat is in a class with no start time of its own', () => {
+    const race = bareRace({ startTime: 1000, classes: [{ id: 'c1', name: 'Cruisers', startTime: null }] });
+    const boat = { classId: 'c1', startTime: null };
+    assert.equal(effectiveStartTime(race, boat), 1000);
+  });
+});
+
+describe('raceSummary', () => {
+  test('counts boats, finished, and DNF correctly', () => {
+    const race = bareRace({
+      createdAt: 42,
+      scheduledStart: null,
+      startTime: null,
+      boats: {
+        b1: { finishTime: 100, dnf: false },
+        b2: { finishTime: null, dnf: true },
+        b3: { finishTime: null, dnf: false }
+      }
+    });
+    const summary = raceSummary(race);
+    assert.equal(summary.boatCount, 3);
+    assert.equal(summary.finishedCount, 1);
+    assert.equal(summary.dnfCount, 1);
+    assert.equal(summary.id, 'r1');
+    assert.equal(summary.name, 'Test Race');
+  });
+
+  test('handles a race with no boats', () => {
+    const summary = raceSummary(bareRace());
+    assert.equal(summary.boatCount, 0);
+    assert.equal(summary.finishedCount, 0);
+    assert.equal(summary.dnfCount, 0);
+  });
+});