frugal-iot-client 2.0.2 → 2.0.4

package/CLAUDE.md

@@ -280,6 +280,7 @@ const mt = document.querySelector('mqtt-wrapper')?.projectMt?.findTopic(this.sta
 | `frugaliot:organizationchanged` | `MqttWrapper.onOrganization` | `{ organization }` | capabilities are per organization, so this precedes any project |
 | `frugaliot:cardmove` / `cardmoveover` | `mqtt-devicecard` | `{ nodeId, delta }` / `{ nodeId, targetNodeId }` | the card asks to be moved; the grid decides what that means |
 | `frugaliot:cardmode` | `mqtt-devicecard` | `{ nodeId, mode }` | so the grid can remember what was open |
+| `frugaliot:flashfile` | `mqtt-admin` (OTA section) | `{ org, path }` | the ⚡ beside an OTA file: `mqtt-projectback` opens the Flash card and passes it on |
 
 ---
 
@@ -358,11 +359,14 @@ Every `addVocabulary` block must include **all four** language sections (EN, FR,
 
 ### How a string gets translated
 
-There are three ways a piece of UI text is translated. If a string doesn't go through one of these, it silently stays in English regardless of the selected language:
+There are four ways a piece of UI text is translated. If a string doesn't go through one of these, it silently stays in English regardless of the selected language:
 
 1. **Direct call to `getString(tag)`** — looks the string up in `languages`, falling back to the English value, falling back to `tag` itself. Used for names built dynamically (e.g. a graph's scale/axis name at `text: getString(this.name...)`).
 2. **Via `el(tag, attributes, children)`** — `el()` auto-translates certain *attributes* on certain *tags*, per the `i8ntags` table (currently `label`, `button`, `span`, `option`, `p`, `h1`–`h5`, `th`, all via their `textContent` attribute). Add a tag/attribute pair to `i8ntags` when a new kind of element needs translated text. Excluded even on a listed tag: values containing `:` or `/` (these are usually paths or key:value pairs, not prose), and values not starting with a letter (emoji/symbol-only content). Pass `i8n: false` on an element you know is untranslatable (a proper name, an id, dynamic per-row data).
 3. **Via a graph's scale name** — same as (1), a direct `getString()` call when building the Chart.js scale config.
+4. **Via `getStringWith(tag, value)`** — prose with a name in it. The table entry holds a `%s` and the value is substituted after the lookup: `getStringWith("Forget %s?", nodeId)`. Concatenating a translated fragment with the name instead pins the word order to English, which is wrong in HI. The `window.confirm` dialogs in `admin.js` are built this way.
+
+**Prose that `el()` skips can still be translated.** A paragraph containing a URL or a colon is excluded by (2), so call `getString()` on it yourself and pass `i8n: false` — otherwise `el()` looks up the already-translated text, misses, and falls back to translating it word by word.
 
 **Only `textContent` is translated — never a literal string passed as a DOM `children` argument.** `el('p', {}, ["Some text"])` bypasses the mechanism entirely because the filter inspects `attributes`, not `children`. Always write `el('p', {textContent: "Some text"})` instead. This applies to `p`, `h1`–`h5`, `span`, and any other tag in `i8ntags`.
 
@@ -374,6 +378,7 @@ When adding a new UI string: add matching entries to all four language sections
 
 - `el(tag, attributes, children)` — local wrapper around `EL` that applies i18n translation to label/button/span text. Pass `i8n: false` in attributes to suppress translation for names/IDs.
 - `getString(tag)` — look up a string in the current language(s); falls back to English.
+- `getStringWith(tag, value)` — as `getString`, then substitutes `value` for `%s` in the result, so a translation chooses where the name falls in the sentence.
 - `mqtt_subscribe(topic, cb)` — registers a subscription; replays on reconnect.
 - `GET(url, opts, cb)` — from `html-element-extended`; callback-style HTTP GET returning parsed JSON.
 - `XXX(args)` — debug log with a breakpoint hook; use for unexpected states. Leave calls in place.

package/admin.js

@@ -7,9 +7,23 @@
 
 import {EL, GET, HTMLElementExtended} from '/node_modules/html-element-extended/htmlelementextended.js';
 import mqtt from '/node_modules/mqtt/dist/mqtt.esm.js'; // https://www.npmjs.com/package/mqtt
-import { CssUrl, DELETE, POST, XXX, brokerHost, configSet, el, getString, hasCapability, mqttTempConnect, mqtt_subscribe, retainedPattern, locationParameterChange, mqtt_client, preferedLanguageSet, preferedLanguages, redirectToLogin, server_config } from './core.js';
+import { CssUrl, DELETE, POST, XXX, brokerHost, configSet, el, getString, getStringWith, hasCapability, mqttTempConnect, mqtt_subscribe, retainedPattern, locationParameterChange, mqtt_client, preferedLanguageSet, preferedLanguages, redirectToLogin, server_config } from './core.js';
 
 
+// The OTA upload is multipart, which POST() (JSON) cannot carry. Callback-style, like the rest.
+// The server answers every outcome with a redirect carrying ?message=, so the final URL is the reply.
+function postFormData(url, formData, cb) {
+  fetch(url, {method: 'POST', body: formData})
+    .then((res) => {
+      if (res.body) res.body.cancel(); // the redirect lands on a page we have no use for
+      const message = new URL(res.url, window.location.href).searchParams.get('message');
+      // No message means this was not the redirect we expect - a 401 back to login, say - so do not
+      // report a success the server did not claim
+      cb(null, message || (res.ok ? "Upload finished - check the list below" : `Upload failed (${res.status})`));
+    })
+    .catch((err) => cb(err));
+}
+
 // ---------- USB flashing over WebSerial ----------
 // The .bin files the OTA tab handles are application images. An ESP32 also needs a bootloader,
 // partition table and otadata, which are app-independent and kept in base/ - see FLASH_PLAN.md.
@@ -181,16 +195,47 @@ class MqttAdmin extends HTMLElementExtended { // TODO-89 may depend on organizat
     console.log(ev,val);
     this.getOrDeleteOtaFiles(`/ota_delete/${val}`);
   }
+  /*
+   * The flasher is a card of its own (cards.js), which may not be open - or even built - when the
+   * ⚡ beside a file here is clicked. So this asks, and mqtt-projectback opens that card and
+   * passes the request on to its mqtt-admin.
+   */
   onOtaFlash(path) {
-    const flashEl = this.state.elements.flash;
-    if (flashEl) flashEl.setRemoteSource(this.state.org, path);
+    document.dispatchEvent(new CustomEvent('frugaliot:flashfile',
+      {detail: {org: this.state.org, path}}));
+  }
+  // Called by mqtt-projectback on the flash card, once it is open: the mqtt-flash is in this shadow root.
+  flashRemote(org, path) {
+    const flashEl = this.renderRoot.querySelector('mqtt-flash');
+    if (!flashEl) { XXX(["flashRemote on an admin element that is not the flash section", this.state.section]); return; }
+    flashEl.setRemoteSource(org, path);
+  }
+  /*
+   * Posted here rather than by the browser: the server answers with a redirect to the `url` field
+   * below, so a plain form submit left the whole page on /dashboard/ with no organization chosen -
+   * away from the card that asked, and with the admin cards shut again.
+   */
+  onOtaUpload(ev) {
+    ev.preventDefault();
+    const form = ev.target;
+    this.message("Uploading");
+    postFormData('/ota_update', new FormData(form), (err, message) => {
+      this.message(err ? err.message : message, !err);
+      if (!err) form.reset();
+      this.getOtaFiles(); // says more than the message does: the file is either listed or it is not
+    });
   }
   otaFilesList() {
     return this.state.ota_files.length === 0 ?
       el('p', {textContent: "No OTA files uploaded yet."}) :
       el('p', {}, this.state.ota_files.map(f => [
-        el('span', {class: 'pseudolink', title: getString("Flash this over USB"), textContent: '⚡', onclick: this.onOtaFlash.bind(this, f)}),
-        el('span', {class: 'pseudolink', textContent: `🗑  ${f}`, onclick: this.onOtaDelete.bind(this,`${this.state.org}/${f}`)}),
+        hasCapability(this.state.org, 'OTAFLASH') // no flash card to send it to otherwise
+          ? el('span', {class: 'pseudolink otaicon', title: getString("Flash this over USB"), textContent: '⚡', onclick: this.onOtaFlash.bind(this, f)})
+          : null,
+        // The basket alone deletes; the name beside it downloads, which is what a name invites.
+        el('span', {class: 'pseudolink otaicon', title: getString("Delete this firmware"), textContent: '🗑', onclick: this.onOtaDelete.bind(this,`${this.state.org}/${f}`)}),
+        el('a', {href: `/ota_get/${this.state.org}/${f}`, download: `${f.replace(/\//g, '-')}-firmware.bin`,
+          title: getString("Download this firmware"), textContent: f, i8n: false}),
         el('br', {}),
         ])
       );
@@ -233,9 +278,9 @@ class MqttAdmin extends HTMLElementExtended { // TODO-89 may depend on organizat
     // Irreversible for any node still holding it, and those nodes cannot be told - they are the
     // ones not yet enrolled, so nothing on the server knows they exist.
     if (!window.confirm(
-      `Withdraw this enrolment secret?\n\n` +
-      `Any node flashed with it that has not enrolled yet will be refused and will need ` +
-      `reflashing. Nodes that have already enrolled are unaffected - they never present it again.`)) return;
+      getString("Withdraw this enrolment secret?") + "\n\n" +
+      getString("Any node flashed with it that has not enrolled yet will be refused and will need " +
+        "reflashing. Nodes that have already enrolled are unaffected - they never present it again."))) return;
     DELETE(`/enrolment_secret/${this.state.org}`, {secret}, (err, json) => {
       this.message(err ? err.message : (json && json.message) || getString("Withdrawn"), false);
       this.getEnrolmentSecrets();
@@ -358,13 +403,67 @@ class MqttAdmin extends HTMLElementExtended { // TODO-89 may depend on organizat
           : { label: "DOWN", hint: "The broker reports this bridge not connected" };
         return el('tr', {}, [
           el('td', {i8n: false, textContent: b.site}),
-          el('td', {i8n: false, title: getString(up.hint), textContent: up.label}),
+          el('td', {i8n: false, title: getString(up.hint), textContent: getString(up.label)}),
           el('td', {i8n: false, textContent: b.last_pull ? this.formatLastSeen(new Date(b.last_pull).toISOString()) : getString("Never seen")}),
           el('td', {i8n: false, textContent: b.created_at ? this.formatLastSeen(new Date(b.created_at).toISOString()) : ''}),
         ]);
       }),
     ]);
   }
+  /*
+   * Add a bridge, or re-issue an existing one's credentials.
+   *
+   * The result is shown once and is not stored anywhere it can be read back: the password is
+   * derived from a server secret and this row's timestamp, so the only copy is the one you put into
+   * the Pi's configuration. Re-running for the same site mints new ones and revokes the old, which
+   * is what makes it the way to recover from having lost them.
+   */
+  onBridgeAdd() {
+    const input = this.state.elements.bridge_site;
+    const site = (input && input.value || '').trim();
+    if (!site) { this.message(getString("Give the Pi a short name first")); return; }
+    if (this.state.bridges && this.state.bridges.some((b) => b.site === site)
+        && !window.confirm(
+          getStringWith('"%s" already exists.', site) + "\n\n" +
+          getString("Adding it again issues a new broker password and a new replica token, and the " +
+            "ones that Pi is using now stop working. It will stay disconnected until you put the " +
+            "new ones into its configuration and restart its broker."))) return;
+    POST(`/bridge_add/${this.state.org}`, { site }, (err, json) => {
+      if (err) { this.message(err.message); return; }
+      this.state.new_bridge = json;   // shown once, below
+      this.getBridges();              // refreshes the table and re-renders the card
+      this.replaceElement("bridge_new", this.newBridgeDetails());
+    });
+  }
+  /*
+   * What the Pi needs, once. Deliberately not fetchable again: there is no route that reads a
+   * bridge's password back, so losing it means issuing a new one.
+   */
+  newBridgeDetails() {
+    const b = this.state.new_bridge;
+    if (!b) return el('span', {});
+    return el('div', {class: 'bridge-new'}, [
+      el('h4', {textContent: "Copy these now - they are not shown again"}),
+      // el() will not translate a string containing ':' or '/', so ask for it directly
+      el('p', {i8n: false, textContent: getString(
+        "Run this on the Pi, in the directory the server is installed in. Replace the placeholder " +
+        "with this server's fully-qualified name - the one on its certificate, which you can check " +
+        "by opening https:// that name in a browser. It will then ask for the broker password and " +
+        "for the replica token, in that order, so have both of the values below to hand.")}),
+      el('pre', {i8n: false, textContent: b.command}),
+      el('table', {class: 'nodestates'}, [
+        el('tr', {}, [el('th', {textContent: "Broker account"}), el('td', {i8n: false, textContent: b.account})]),
+        el('tr', {}, [el('th', {textContent: "Broker password"}), el('td', {i8n: false, textContent: b.password})]),
+        el('tr', {}, [el('th', {textContent: "Replica token"}), el('td', {i8n: false, textContent: b.replica_token})]),
+      ]),
+      el('p', {i8n: false, textContent: getString(
+        "Two credentials for two different connections: the password is what the MQTT bridge logs " +
+        "in with on port 8883, and the token is what lets that Pi pull this organization's logins " +
+        "over HTTPS, so the same people can log in there too. The token can be skipped - press " +
+        "Enter at its prompt - and added later by doing this again. Neither is asked for on the " +
+        "command line, so that neither ends up in the Pi's shell history.")}),
+    ]);
+  }
   bridgesRestContent() {
     return el('div', {}, [
       this.refreshableHeading("Bridged Pis", this.getBridges),
@@ -375,6 +474,18 @@ class MqttAdmin extends HTMLElementExtended { // TODO-89 may depend on organizat
         "this organization's logins, which it does over HTTP - so a Pi can be checking in while " +
         "its bridge is down, and the two together say which half is broken."}),
       this.state.elements.bridges_list = this.bridgesList(),
+      el('section', {}, [
+        el('h3', {textContent: "Add a bridge"}),
+        el('p', {textContent:
+          "Give the Pi a short name - it becomes its broker account and cannot be changed later " +
+          "without reconfiguring that Pi. Lower-case letters, digits and hyphens."}),
+        el('div', {}, [
+          this.state.elements.bridge_site = el('input',
+            {i8n: false, type: 'text', name: 'site', placeholder: 'pi4', size: 16}),
+          el('button', {textContent: "Add", onclick: this.onBridgeAdd.bind(this)}),
+        ]),
+        this.state.elements.bridge_new = this.newBridgeDetails(),
+      ]),
     ]);
   }
   onNodeReset(project, nodeid) {
@@ -382,10 +493,10 @@ class MqttAdmin extends HTMLElementExtended { // TODO-89 may depend on organizat
     // credential being refused and enrols again) but it does cost that node a few minutes offline.
     // Worth asking, unlike the OTA deletes beside it where the file can simply be uploaded again.
     if (!window.confirm(
-      `Forget ${project}/${nodeid}?\n\n` +
-      `It will be issued a new broker credential the next time it asks. A node that is running ` +
-      `will be offline for a minute or two while it notices; a node whose filesystem was erased ` +
-      `needs this before it can rejoin at all.`)) return;
+      getStringWith("Forget %s?", `${project}/${nodeid}`) + "\n\n" +
+      getString("It will be issued a new broker credential the next time it asks. A node that is " +
+        "running will be offline for a minute or two while it notices; a node whose filesystem " +
+        "was erased needs this before it can rejoin at all."))) return;
     POST(`/node_reset/${this.state.org}`, { project, nodeid }, (err, json) => {
       this.message(err ? err.message : (json && json.message) || "Forgotten");
       this.getEnrolledNodes();
@@ -431,9 +542,9 @@ class MqttAdmin extends HTMLElementExtended { // TODO-89 may depend on organizat
   }
   onNodeState(project, nodeid, state) {
     if (state === 'denied' && !window.confirm(
-      `Deny ${nodeid}?\n\n` +
-      `Its broker account is deleted, so it stops being able to publish or subscribe, and it ` +
-      `cannot enrol again until you clear this. Use it for a node sending bad readings.`)) return;
+      getStringWith("Deny %s?", nodeid) + "\n\n" +
+      getString("Its broker account is deleted, so it stops being able to publish or subscribe, " +
+        "and it cannot enrol again until you clear this. Use it for a node sending bad readings."))) return;
     POST(`/node_state/${this.state.org}`, {project, nodeid, state}, (err, json) => {
       this.message(err ? err.message : (json && json.message) || getString("Done"), false);
       this.getEnrolledNodes();
@@ -1322,7 +1433,8 @@ class MqttAdmin extends HTMLElementExtended { // TODO-89 may depend on organizat
    // Content of the OTA tab below the organization dropdown - only rendered once an org is selected
    otaRestContent() {
      return el('div', {}, [
-       el('form', {action: '/ota_update', method: "post", enctype: "multipart/form-data"}, [
+       el('form', {action: '/ota_update', method: "post", enctype: "multipart/form-data",
+         onsubmit: this.onOtaUpload.bind(this)}, [
          el('input', {id: "url2", name: "url", type: "hidden", value: `/dashboard/`}),
          el('input', {id: "lang", name: "lang", type: "hidden", value: preferedLanguages.join(',')}),
          // The organization dropdown for this tab is a sibling of this form rather than inside it
@@ -1356,9 +1468,6 @@ class MqttAdmin extends HTMLElementExtended { // TODO-89 may depend on organizat
          this.refreshableHeading("Existing OTA Files", this.getOtaFiles),
          this.state.elements.ota_files = this.otaFilesList(),
        ]), // section ota
-       el('section', {}, [
-         this.state.section ? null : (this.state.elements.flash = el('mqtt-flash', {})), // its own card on the project back
-       ]), // section flash
      ]);
    }
    // Content of the Admin tab below the organization dropdown - only rendered once an org is selected
@@ -1596,6 +1705,10 @@ class MqttAdmin extends HTMLElementExtended { // TODO-89 may depend on organizat
      return el('div', {class: 'mqtt-admin'}, [
        this.state.org ? null
          : (this.state.elements[section.dropdown] = el('span', {textContent: "Waiting"})),
+       // message() had nowhere to write until now, so every failed fetch reported itself only to
+       // the console. One line per card, above whatever that card is saying.
+       this.state.elements.message = el('div', {class: 'message', i8n: false,
+         textContent: this.state.message || ''}),
        this.state.elements[section.rest] = this.gatedContent(section),
      ]);
    }

package/cards.js

@@ -733,6 +733,7 @@ const ADMIN_CARDS = [
   { section: 'message',  title: 'Publish Message',  capability: 'ADMIN' },
   { section: 'retained', title: 'Retained messages', capability: 'ADMIN' },
   { section: 'nodes',   title: 'Nodes',            capability: 'ADMIN' },
+  { section: 'bridges', title: 'Bridges',          capability: 'ADMIN' },
   { section: 'api',   title: 'API',             capability: 'ADMIN' },
 ];
 
@@ -747,6 +748,25 @@ class MqttProjectBack extends HTMLElementExtendedMinimum {
     super();
     this.state.elements = {};
     this.state.open = {};
+    this.onFlashFile = this.onFlashFile.bind(this);
+  }
+  connectedCallback() {
+    super.connectedCallback();
+    document.addEventListener('frugaliot:flashfile', this.onFlashFile);
+  }
+  disconnectedCallback() {
+    document.removeEventListener('frugaliot:flashfile', this.onFlashFile);
+    if (super.disconnectedCallback) super.disconnectedCallback();
+  }
+
+  // The OTA card asks; only this knows where the flasher is, and whether its card is open yet.
+  onFlashFile(e) {
+    const card = this.state.elements.flash;
+    if (!card) return; // No OTAFLASH here, so no card - the OTA list should not have offered it
+    if (!this.state.open.flash) this.toggle('flash');
+    const adminEl = card.querySelector('mqtt-admin');
+    if (adminEl) adminEl.flashRemote(e.detail.org, e.detail.path);
+    if (card.scrollIntoView) card.scrollIntoView({behavior: 'smooth', block: 'start'}); // jsdom has none
   }
 
   // An admin card has a summary and a back, and nothing that makes sense as a front: it is its name