sailkick-boat 0.29.0 → 0.30.0

package/README.md

@@ -363,6 +363,46 @@ at all. The raw channels are always recorded regardless, so the cloud can recomp
 history if the maths ever changes: the recorded channel is a materialisation, not the only
 truth.
 
+## Sails — the boat is the only writer
+
+Sailkick records every instrument value but has no idea which sails are set, so the polar
+estimator averages a full-main-and-genoa curve together with a three-reefs-and-staysail
+one. Recording the plan as a time series is what will let it tell them apart.
+
+`POST /api/sails {"plan":"genoa:0+main:2"}` publishes an ordinary SignalK delta on
+`sails.plan`, and the gapless spool carries it to the cloud like any other value. The
+**cloud refuses the same request** (`501 sail-write-not-here`), deliberately: one writer
+keeps `<id>_raw` a faithful mirror of the boat's own SignalK, the write is offline-correct
+for free — sail changes happen at sea, which is exactly when the cloud is unreachable —
+and no Influx *write* token has to live in the cloud beside the password hashes.
+
+```
+genoa:0+main:0        full main and full genoa
+main:2+staysail:0     two reefs, staysail, no headsail
+genoa:2+stormjib:0    genoa furled two steps AND the storm jib set
+bare                  nothing up
+```
+
+`<id>:<reefs>` per **set** sail, joined by `+`, **sorted by id**. Any combination is
+expressible, which is the point — a cutter flies genoa and staysail together, heavy
+weather means a partly-furled genoa *and* the storm jib, downwind means twin headsails. A
+fixed slot per station cannot say any of that.
+
+**Sorting is the contract**, so the write door validates by round-tripping through the
+vendored encoder (`shared/engine/sails.js`, pinned by hash) and **refuses** anything
+non-canonical rather than fixing it up. `main:2+genoa:0` names the right sails and hashes
+differently from `genoa:0+main:2`; accepting it would split the polar cloud this feature
+exists to unify — silently, and visible only much later as a mysteriously noisy polar. A
+client sending it is using its own encoder, which is the actual bug.
+
+`bare` rather than an empty string distinguishes "the crew says nothing is up" from "we
+have no sail data", which is null. Under bare poles in a survival storm that difference is
+real.
+
+`/api/config` gains `sailPlanWritable: true` — a **capability**, not a deployment test:
+the dev box runs the cloud server on a LAN and self-hosters run it as their edge, so "am I
+the cloud?" is the wrong question. The screen reads only the capability.
+
 ## Alerts and alarms, evaluated on board
 
 Rules — anchor drag, wind over or under a threshold, a big wind shift, boat speed below

package/index.js

@@ -12,6 +12,7 @@ const { createAisTargets } = require('./lib/ais/targets')
 const { createProfile } = require('./lib/profile')
 const { createPerf } = require('./lib/perf')
 const { createAlerts } = require('./lib/alerts')
+const { createSails } = require('./lib/sails')
 const { createCloud } = require('./lib/cloud')
 const { resolveAccountConfig } = require('./lib/account')
 
@@ -109,6 +110,7 @@ module.exports = function (app) {
   let cloud = null
   let perf = null
   let alerts = null
+  let sails = null
   let proxyPort = null // what the launcher page needs to build its links
   let pairedSlug = null
   let statusTimer = null
@@ -425,6 +427,16 @@ module.exports = function (app) {
         }
       }
 
+      // The sail-plan write door. No config toggle: it is inert until the crew posts a
+      // plan, and a boat that cannot record its sails is the status quo this fixes.
+      try {
+        sails = createSails(app, { pluginId: plugin.id })
+        pOpts.sails = sails // proxy dispatches POST /api/sails and claims sailPlanWritable
+      } catch (e) {
+        (app.error || console.error)('[sailkick-boat] sails start failed: ' + e.message)
+        sails = null
+      }
+
       if (pOpts.history.enabled !== false) {
         try {
           // ringSource = the telemetry module: when no local InfluxDB token is set
@@ -530,6 +542,7 @@ module.exports = function (app) {
     if (profile) parts.push(profile.status())
     if (perf) parts.push(perf.status())
     if (alerts) parts.push(alerts.status())
+    if (sails) parts.push(sails.status())
     if (ais) parts.push(ais.status())
     if (backfill) parts.push(backfill.status())
     try { app.setPluginStatus(parts.join('   |   ') || 'idle (both features off)') } catch {}
@@ -559,6 +572,7 @@ module.exports = function (app) {
     cloud = null
     perf = null
     alerts = null
+    sails = null
     proxyPort = null
     pairedSlug = null
     proxy = null

package/lib/proxy/index.js

@@ -97,6 +97,7 @@ function createProxy (app, options) {
       aisTargets: options.aisTargets || null,
       profile: options.profile || null,
       alerts: options.alerts || null, // claims alertsEvaluatedHere in /api/config, see serveConfig
+      sails: options.sails || null, // the sail-plan write door; claims sailPlanWritable
       boat: options.boat || null, // { perfKey, slug } — patched into /api/config, see serveConfig
       openAccess: options.openAccess !== false
     }
@@ -266,6 +267,24 @@ function createProxy (app, options) {
     if (cfg.profile && cfg.profile.available() && cfg.profile.handles(req.url)) {
       return cfg.profile.handle(req, res)
     }
+    // Set which sails are up. The boat is the ONLY host that accepts this — the cloud
+    // answers 501 sail-write-not-here — because the plan reaches InfluxDB by being
+    // published as a SignalK delta here and spooled like every other value: one writer,
+    // offline-correct by construction, and no Influx write token in the cloud. Never
+    // proxied upstream, whatever the outcome.
+    if (req.method === 'POST' && cfg.sails && cfg.sails.available() &&
+        req.url.split('?')[0] === '/api/sails') {
+      return readJsonBody(req).then((body) => {
+        const r = cfg.sails.setPlan(body || {})
+        res.statusCode = r.ok ? 200 : (r.status || 400)
+        res.setHeader('Content-Type', 'application/json')
+        res.end(JSON.stringify(r.ok ? { ok: true, plan: r.plan, at: r.at } : { ok: false, code: r.code, message: r.message }))
+      }).catch((e) => {
+        res.statusCode = 500
+        res.setHeader('Content-Type', 'application/json')
+        res.end(JSON.stringify({ ok: false, code: 'sails-error', message: e.message }))
+      })
+    }
     // /api/config drives the app's login gate + Trends toggle. On the single-tenant
     // boat we serve it with auth turned off (no cloud login over the offline HTTP
     // mirror) and history forced on when we serve it locally. All other config passes
@@ -332,6 +351,14 @@ function createProxy (app, options) {
           // banner unless a host claims them — rules stored with nothing watching them is
           // the failure it is warning about. This plugin IS that host, on board, so say so.
           if (cfg.alerts && cfg.alerts.available()) j.alertsEvaluatedHere = true
+          // A CAPABILITY, not a deployment test: the sails screen is read-only unless a
+          // host says it can publish the delta. "Am I the cloud?" is the wrong question —
+          // the dev box runs the cloud server on a LAN and self-hosters run it as their
+          // edge, so a self-hosted single-boat cloud looks exactly like a boat otherwise.
+          if (cfg.sails && cfg.sails.available()) j.sailPlanWritable = true
+          // Display only. Nothing may branch on this — that is what the capability flags
+          // above are for; this exists so the UI can tell a human where data comes from.
+          j.deployment = 'boat'
           // The cloud fills `boat` only for a logged-in session, and the mirror forwards no
           // cookie — so it always arrived as null and the app had no identity. Harmless for
           // most of the UI, but public/engine/polar-cloud.js keys the performance data cloud

package/lib/sails/index.js

@@ -0,0 +1,86 @@
+'use strict'
+
+// The sail plan write door — the one place a sail plan enters the system.
+//
+// Sailkick records every instrument value but has no idea which sails are set, so the
+// polar estimator averages a full-main-and-genoa curve together with a
+// three-reefs-and-staysail one. Recording the plan as a time series is what will let it
+// tell them apart later.
+//
+// THE WRITE HAPPENS HERE AND NOWHERE ELSE. The app posts a plan to whichever server
+// served it, and only the boat's mirror accepts one; the cloud answers 501
+// `sail-write-not-here` so a stale client gets JSON it can show a human. The reasons are
+// worth restating because they are the whole design:
+//
+//   - <id>_raw stays a faithful mirror of the boat's own SignalK: one writer.
+//   - It is offline-correct for free. Sail changes happen at sea, which is exactly when
+//     the cloud is unreachable — the gapless spool already solves that, so the app needs
+//     no outbox of its own.
+//   - No Influx WRITE token has to live in the cloud next to the password hashes.
+//
+// Publishing is an ordinary SignalK delta on `sails.plan`, so everything downstream gets
+// it for nothing: lib/sync spools it to the cloud bucket like any other value (string
+// fields already work end to end — steering.autopilot.state proves it), the vendored
+// mapper turns it into BoatState.sailPlan, and the app's sails screen renders identically
+// on the boat and in the cloud.
+
+const { isCanonicalPlan, decodePlan, describePlan, BARE } = require('./sails')
+
+function createSails (app, options = {}) {
+  const log = (m) => (app.debug ? app.debug('[sails] ' + m) : console.log('[sailkick-boat:sails]', m))
+  const warn = (m) => (app.error ? app.error('[sailkick-boat:sails] ' + m) : console.error('[sailkick-boat:sails]', m))
+
+  let last = null // { plan, at } — what we published, for the status line
+  let writes = 0
+
+  // POST /api/sails  { plan: "<canonical string>" } -> { ok, plan } | { ok:false, ... }
+  function setPlan (body) {
+    const plan = body && typeof body.plan === 'string' ? body.plan.trim() : null
+    if (!plan) {
+      return { ok: false, status: 400, code: 'bad-plan', message: 'body must be { plan: "<sail plan>" }' }
+    }
+    // Round-trip validation with the VENDORED encoder, so nothing that would decode
+    // differently than it was written ever reaches SignalK. The sort order is the whole
+    // contract — it is the key the polar work groups by — and "main:0+genoa:0" is
+    // exactly the kind of string that looks right and hashes wrong.
+    if (!isCanonicalPlan(plan)) {
+      return {
+        ok: false,
+        status: 400,
+        code: 'bad-plan',
+        message: `"${plan}" is not a canonical sail plan. Expected <id>:<reefs> per set sail, joined by "+", sorted by id (e.g. "genoa:0+main:2"), or "${BARE}".`
+      }
+    }
+    if (!app.handleMessage) {
+      return { ok: false, status: 503, code: 'no-signalk', message: 'this plugin cannot publish to SignalK' }
+    }
+    const at = new Date().toISOString()
+    try {
+      app.handleMessage(options.pluginId || 'sailkick-boat', {
+        updates: [{ timestamp: at, values: [{ path: 'sails.plan', value: plan }] }]
+      })
+    } catch (e) {
+      warn('could not publish the sail plan: ' + e.message)
+      return { ok: false, status: 500, code: 'publish-failed', message: e.message }
+    }
+    last = { plan, at }
+    writes++
+    // Worth a normal log line, not a debug one: this is crew input, and "when did we put
+    // the second reef in" is a question people ask afterwards.
+    log(`sails: ${describePlan(plan)}  (${plan})`)
+    return { ok: true, plan, at }
+  }
+
+  function status () {
+    if (!last) return 'sails: none set yet'
+    return `sails: ${describePlan(last.plan)}${writes > 1 ? ` (${writes} changes)` : ''}`
+  }
+
+  // Mirrors lib/history / lib/alerts: the proxy asks before claiming, in /api/config,
+  // that this host can accept a sail plan.
+  function available () { return !!app.handleMessage }
+
+  return { setPlan, status, available, _last: () => last, _decode: decodePlan }
+}
+
+module.exports = { createSails }

package/lib/sails/sails.js

@@ -0,0 +1,180 @@
+// VENDORED from sailkick/shared/engine/sails.js @ 1571308  sha256:7965d2e3e610e9fd
+// Do not edit here — fix upstream and re-vendor. ONE definition of how a sail plan is
+// written down, or the same plan hashes two ways and silently splits the polar cloud
+// this feature exists to unify — visible only much later, as a mysteriously noisy polar.
+// test/sails.test.js replays the upstream suite against this copy to prove it matches.
+//
+// Converted ESM -> CommonJS ONLY (export keywords removed, module.exports appended).
+// No logic changed.
+//
+// The boat is the ONLY writer of a sail plan: the app posts one to whichever server
+// served it, and only this mirror accepts it (the cloud answers 501). That keeps
+// <id>_raw a faithful mirror of the boat's own SignalK with one writer, makes the write
+// offline-correct for free — sail changes happen at sea, which is exactly when the cloud
+// is unreachable, and the gapless spool already solves that — and keeps an Influx write
+// token out of the cloud next to the password hashes.
+
+// Sail plan — ONE definition of how a sail plan is written down, shared by every host
+// that records or reads one: the boat plugin (which publishes it onto SignalK) and the
+// cloud (which displays it and will later group polar samples by it). Pure and
+// dependency-free, like shared/engine/alerts.js, for the same reason: a second
+// implementation that disagrees is the failure mode this file exists to prevent.
+//
+// THE ENCODING
+//
+//   "genoa:0+main:0"        full main and full genoa
+//   "main:2+staysail:0"     two reefs, staysail, no headsail
+//   "genoa:2+stormjib:0"    genoa furled two steps AND the storm jib set
+//   "bare"                  nothing up
+//
+// `<id>:<reefs>` per ACTIVE sail, joined by "+", SORTED BY ID. Only sails that are
+// actually set appear — "main down" is simply the main's absence, not a `down` state.
+// That is what lets any combination be expressed: a cutter's genoa + staysail, a
+// heavy-weather partly-furled genoa + storm jib, twin headsails poled out downwind.
+// A fixed slot per station cannot say any of those, which is why there isn't one.
+//
+// SORTING IS THE WHOLE CONTRACT. The string is the join key the polar work will group
+// by, so the same sail plan MUST produce the same bytes every time. An encoder that
+// emitted insertion order would split one polar cloud into several that look unrelated
+// — silently, and only visible much later as a mysteriously noisy polar. Hence
+// encodePlan sorts, and the round-trip tests assert it.
+//
+// `bare` (rather than "") distinguishes "the crew says nothing is up" from "we have no
+// sail data at all", which is null/absent. Under bare poles in a survival storm that
+// distinction is real information.
+
+// A sail id: lowercase, url-safe, and free of the encoding's own delimiters.
+const ID_RE = /^[a-z0-9][a-z0-9-]{0,31}$/;
+const STATIONS = ['main', 'head', 'flying'];
+const SAIL_STATIONS = STATIONS;
+const BARE = 'bare';
+const MAX_REEFS = 5;
+const MAX_SAILS = 12;   // a plan longer than this is a bug or an attack, not a rig
+
+// The inventory a boat gets before anyone edits it. Deliberately over-complete: it is
+// far easier to delete the sails you don't carry than to remember the ones you do.
+// `reefs` is how many REDUCED steps the sail has below full — 0 means it is all-or-
+// nothing (a spinnaker is up or it isn't). For a furling headsail these are furl steps.
+const DEFAULT_INVENTORY = [
+  { id: 'main',      name: 'Mainsail',  station: 'main',   reefs: 3 },
+  { id: 'genoa',     name: 'Genoa',     station: 'head',   reefs: 2 },
+  { id: 'jib',       name: 'Jib',       station: 'head',   reefs: 1 },
+  { id: 'staysail',  name: 'Staysail',  station: 'head',   reefs: 0 },
+  { id: 'stormjib',  name: 'Storm jib', station: 'head',   reefs: 0 },
+  { id: 'trysail',   name: 'Trysail',   station: 'main',   reefs: 0 },
+  { id: 'code0',     name: 'Code 0',    station: 'flying', reefs: 0 },
+  { id: 'spinnaker', name: 'Spinnaker', station: 'flying', reefs: 0 },
+];
+
+// [{ id, reefs }] → the canonical string. Ignores entries with an unusable id, and
+// clamps a negative/NaN reef count to 0 rather than emitting a string that won't parse:
+// a UI bug must not be able to write an unreadable record into the boat's history.
+function encodePlan(sails) {
+  if (!Array.isArray(sails)) return BARE;
+  const seen = new Map();
+  for (const s of sails) {
+    const id = typeof s?.id === 'string' ? s.id.trim().toLowerCase() : '';
+    if (!ID_RE.test(id)) continue;
+    const n = Number(s.reefs);
+    seen.set(id, Number.isFinite(n) ? Math.max(0, Math.min(MAX_REEFS, Math.round(n))) : 0);
+  }
+  if (!seen.size) return BARE;
+  return [...seen.entries()]
+    .sort((a, b) => (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0))   // byte order, not locale
+    .map(([id, reefs]) => `${id}:${reefs}`)
+    .join('+');
+}
+
+// The canonical string → [{ id, reefs }], in the string's own (sorted) order.
+//
+// Deliberately TOLERANT: history outlives the inventory. A sail deleted from the boat's
+// inventory today still appears in every plan recorded before it went, and a decoder
+// that threw would take the whole screen — and later the whole polar split — down with
+// it. Unparseable segments are dropped; `null`/absent/unknown input decodes to [].
+function decodePlan(str) {
+  if (typeof str !== 'string') return [];
+  const s = str.trim();
+  if (!s || s === BARE) return [];
+  const out = [];
+  const seen = new Set();
+  for (const seg of s.split('+').slice(0, MAX_SAILS)) {
+    const i = seg.indexOf(':');
+    if (i < 0) continue;
+    const id = seg.slice(0, i).trim().toLowerCase();
+    if (!ID_RE.test(id) || seen.has(id)) continue;
+    const reefs = Number(seg.slice(i + 1).trim());
+    if (!Number.isInteger(reefs) || reefs < 0 || reefs > MAX_REEFS) continue;
+    seen.add(id);
+    out.push({ id, reefs });
+  }
+  return out;
+}
+
+// True when the string is one this encoder could have produced. Used at the write door:
+// the boat validates an incoming plan by round-tripping it, so nothing that would decode
+// differently than it was written ever reaches SignalK.
+function isCanonicalPlan(str) {
+  return typeof str === 'string' && encodePlan(decodePlan(str)) === str.trim();
+}
+
+// The key polar samples will be GROUPED BY. Identity today — the plan string already is
+// the key. It exists as a named seam because the polar work will want to coarsen plans
+// into equivalence classes (a code 0 barely changes the upwind curve; a reef does), and
+// when it does, that decision belongs here next to the encoding rather than scattered
+// through the estimator.
+function sailPlanKey(str) {
+  return typeof str === 'string' && str.trim() ? str.trim() : null;
+}
+
+// Render a plan for a human: "2 reefs · Staysail". `inventory` supplies display names;
+// a sail missing from it falls back to its id, so historical plans stay readable after
+// the sail is deleted. Returns '—' for no data, 'Bare poles' for an explicit bare.
+function describePlan(str, inventory = DEFAULT_INVENTORY) {
+  if (typeof str !== 'string' || !str.trim()) return '—';
+  if (str.trim() === BARE) return 'Bare poles';
+  const byId = new Map((inventory || []).map((s) => [s.id, s]));
+  const parts = decodePlan(str).map(({ id, reefs }) => {
+    const name = byId.get(id)?.name || id;
+    if (!reefs) return name;
+    // The main is reefed; a furling headsail is furled. Same integer, different word —
+    // saying "1 reef" about a genoa reads wrong to anyone who has actually sailed.
+    return byId.get(id)?.station === 'main'
+      ? `${reefs} reef${reefs > 1 ? 's' : ''}`
+      : `${name} −${reefs}`;
+  });
+  return parts.length ? parts.join(' · ') : 'Bare poles';
+}
+
+// Validate one INVENTORY item (not a plan) — the profile section's write guard, in the
+// shape of validateRule() in shared/engine/alerts.js. A malformed sail stores looking
+// fine and then silently mislabels every polar sample recorded against it, so it is
+// rejected at the door rather than tolerated.
+function validateSail(s) {
+  if (!s || typeof s !== 'object') return { ok: false, error: 'sail must be an object' };
+  const id = typeof s.id === 'string' ? s.id.trim().toLowerCase() : '';
+  if (!ID_RE.test(id)) {
+    return { ok: false, error: `sail id "${s.id}" must be lowercase letters, digits or dashes (max 32) — it is written into every recorded plan` };
+  }
+  if (typeof s.name !== 'string' || !s.name.trim() || s.name.length > 40) {
+    return { ok: false, error: 'sail name is required (max 40 characters)' };
+  }
+  if (!STATIONS.includes(s.station)) {
+    return { ok: false, error: `sail station "${s.station}" must be one of ${STATIONS.join(', ')}` };
+  }
+  if (!Number.isInteger(s.reefs) || s.reefs < 0 || s.reefs > MAX_REEFS) {
+    return { ok: false, error: `sail reefs must be a whole number between 0 and ${MAX_REEFS}` };
+  }
+  return { ok: true };
+}
+
+module.exports = {
+  encodePlan,
+  decodePlan,
+  isCanonicalPlan,
+  sailPlanKey,
+  describePlan,
+  validateSail,
+  DEFAULT_INVENTORY,
+  SAIL_STATIONS,
+  BARE
+}

package/lib/telemetry/contract.js

@@ -27,10 +27,10 @@
 // old path no longer existed. They now fail rather than skip when the checkout is present
 // and the file is not; a guard that disappears when its subject moves is not a guard.
 
-// sha256(app shared/engine/signalk-map.js)[0..12] as ported in v0.18.6
+// sha256(app shared/engine/signalk-map.js)[0..12] as ported in v0.30.0 (the sails merge)
 const { request } = require('../net') // owned connection pool + real error codes
 
-const PINNED_APP_HASH = '3e42369c002b'
+const PINNED_APP_HASH = 'fd79e3688591'
 
 function createContractCheck (app, options = {}) {
   const warn = (m) => (app.error ? app.error('[sailkick-boat:contract] ' + m) : console.error('[sailkick-boat:contract]', m))

package/lib/telemetry/signalk-map.js

@@ -1,12 +1,13 @@
-// VENDORED from sailkick/shared/engine/signalk-map.js @ dc57057  sha256:3e42369c002b7cb7
-// (the app moved it public/engine -> shared/engine in 8fd58cf; content and hash unchanged)
+// VENDORED from sailkick/shared/engine/signalk-map.js @ 1571308  sha256:fd79e368859133d8
 // Do not edit here — fix upstream and re-vendor. One SignalK -> BoatState mapping, or
 // the boat and the app quietly disagree (it has drifted twice; both times silently).
 //
 // Converted ESM -> CommonJS ONLY. No logic changed.
 //
-// Re-vendored after b519a9f (course + depth precedence) and 348c3d9 (heading true
-// authoritative) — both of which came from findings handed over from this repo.
+// Re-vendored after b519a9f (course + depth precedence), 348c3d9 (heading true
+// authoritative) — both from findings handed over from this repo — and the sails merge
+// (1571308), which adds the `sails.plan` case: the boat's mirror is the only writer of
+// that path, so this copy has to understand what it publishes.
 
 // SignalK → BoatState mapping — pure, dependency-free, so it's shared by both
 // the client provider (public/ui/boat-panel.js, browser WebSocket) and the
@@ -152,6 +153,17 @@ function signalkValuesToPatch(values) {
       case 'navigation.datetime':                 // GNSS UTC time (from the satellites)
         if (typeof v.value === 'string') patch.gpsTime = v.value;
         break;
+      // Which sails are set — a canonical plan string (shared/engine/sails.js), not a
+      // sensor reading: the crew publishes it from the app. Kept VERBATIM here; this
+      // mapper stays pure string-passing and the encoding lives in one place.
+      //
+      // A null is SKIPPED, like every sensor path and unlike the course paths above:
+      // the plan is a step function, so "the source went quiet" must leave the last
+      // known plan standing, not blank it. "Nothing is up" is the explicit string
+      // `bare`, which is exactly why that sentinel exists.
+      case 'sails.plan':
+        if (typeof v.value === 'string' && v.value.trim()) patch.sailPlan = v.value.trim();
+        break;
       default:
         break; // ignore everything else
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sailkick-boat",
-  "version": "0.29.0",
+  "version": "0.30.0",
   "description": "Run the sailkick app on board with no internet: charts, weather, climatology, trends and AIS all served from the boat itself. With a sailkick account it also syncs your metrics to the cloud in real time. Alpha, invite-only — info@sailkick.io",
   "main": "index.js",
   "scripts": {