example(dashboardapi): basic.flow.json demos end-to-end Grafana round-trip (#42)

Replaces the placeholder inject→dashboardapi→debug example with the full
chain: inject (simulating a measurement child registration) → dashboardapi
(composes dashboard JSON) → http request (POSTs to Grafana) → debug (shows
the response). Default targets http://grafana:3000 inside the Docker compose
network. Configure bearer token via the encrypted credentials field.

Refs #42

examples/basic.flow.json

@@ -1,6 +1,70 @@
 [
-  {"id":"dashboardAPI_basic_tab","type":"tab","label":"dashboardAPI basic","disabled":false,"info":"dashboardAPI basic example"},
-  {"id":"dashboardAPI_basic_node","type":"dashboardapi","z":"dashboardAPI_basic_tab","name":"dashboardAPI basic","x":420,"y":180,"wires":[["dashboardAPI_basic_dbg"]]},
-  {"id":"dashboardAPI_basic_inj","type":"inject","z":"dashboardAPI_basic_tab","name":"basic trigger","props":[{"p":"topic","vt":"str"},{"p":"payload","vt":"str"}],"topic":"ping","payload":"1","payloadType":"str","x":160,"y":180,"wires":[["dashboardAPI_basic_node"]]},
-  {"id":"dashboardAPI_basic_dbg","type":"debug","z":"dashboardAPI_basic_tab","name":"dashboardAPI basic debug","active":true,"tosidebar":true,"console":false,"tostatus":false,"complete":"true","targetType":"full","x":660,"y":180,"wires":[]}
+  {
+    "id": "dashboardAPI_basic_tab",
+    "type": "tab",
+    "label": "dashboardAPI basic — measurement → Grafana",
+    "disabled": false,
+    "info": "Demonstrates the round-trip:\n- inject simulates a child.register message from a measurement node\n- dashboardapi composes a Grafana dashboard for that child\n- http request posts the dashboard to Grafana\n- debug shows the HTTP response\n\nConfigure the dashboardapi node with your Grafana host/port + bearer token\n(encrypted via Node-RED credentials). Default targets http://grafana:3000\nfrom inside the Docker compose stack."
+  },
+  {
+    "id": "dashboardAPI_basic_node",
+    "type": "dashboardapi",
+    "z": "dashboardAPI_basic_tab",
+    "name": "dashboardAPI",
+    "protocol": "http",
+    "host": "grafana",
+    "port": 3000,
+    "folderUid": "",
+    "defaultBucket": "telemetry",
+    "x": 460,
+    "y": 200,
+    "wires": [["dashboardAPI_basic_http"]]
+  },
+  {
+    "id": "dashboardAPI_basic_inj",
+    "type": "inject",
+    "z": "dashboardAPI_basic_tab",
+    "name": "simulate child.register (measurement)",
+    "props": [
+      { "p": "topic", "vt": "str" },
+      { "p": "payload", "v": "{\"config\":{\"general\":{\"id\":\"meas-demo-001\",\"name\":\"FT-001 demo\"},\"functionality\":{\"softwareType\":\"measurement\",\"positionVsParent\":\"downstream\"}}}", "vt": "json" }
+    ],
+    "topic": "child.register",
+    "x": 180,
+    "y": 200,
+    "wires": [["dashboardAPI_basic_node"]]
+  },
+  {
+    "id": "dashboardAPI_basic_http",
+    "type": "http request",
+    "z": "dashboardAPI_basic_tab",
+    "name": "POST /api/dashboards/db",
+    "method": "use",
+    "ret": "obj",
+    "paytoqs": "ignore",
+    "url": "",
+    "tls": "",
+    "persist": false,
+    "proxy": "",
+    "authType": "",
+    "senderr": false,
+    "x": 720,
+    "y": 200,
+    "wires": [["dashboardAPI_basic_dbg"]]
+  },
+  {
+    "id": "dashboardAPI_basic_dbg",
+    "type": "debug",
+    "z": "dashboardAPI_basic_tab",
+    "name": "Grafana response",
+    "active": true,
+    "tosidebar": true,
+    "console": false,
+    "tostatus": false,
+    "complete": "payload",
+    "targetType": "msg",
+    "x": 960,
+    "y": 200,
+    "wires": []
+  }
 ]

src/commands/handlers.js

@@ -22,35 +22,9 @@ function resolveChildNode(childId, ctx) {
   return runtimeNode || flowNode || null;
 }
 
-// On child.register: build the dashboard graph (root + direct children) and
-// emit one Grafana upsert HTTP request per dashboard on Port 0.
-//
-// Diff-skip behavior (PRD F-1, S1 spike #32): if the latest flows:started
-// payload's `diff` indicates that NEITHER the dashboardAPI itself NOR this
-// child NOR its grandchildren changed, skip composition and log no-diff. The
-// first call after startup (no cached diff yet) regenerates unconditionally.
-function registerChild(source, msg, ctx) {
-  const childSource = resolveChildSource(msg.payload, ctx);
-  if (!childSource?.config) {
-    throw new Error('Missing or invalid child node');
-  }
-
-  const subtreeIds = source.subtreeIdsFor(ctx.node?.id, childSource);
-  const changed = source.subtreeChanged(source.lastFlowsStartedDiff, subtreeIds);
-  if (!changed) {
-    if (source.logger?.info) {
-      source.logger.info({
-        event: 'regen-skipped',
-        outcome: 'no-diff',
-        trigger: 'child.register',
-        dashboardApiId: ctx.node?.id,
-        childId: childSource?.config?.general?.id,
-        subtreeSize: subtreeIds.size,
-      });
-    }
-    return;
-  }
-
+// Shared emit path used by both child.register (auto, deploy-driven) and
+// regenerate-dashboard (manual). `trigger` distinguishes the two for logs.
+function emitDashboardsFor(source, childSource, ctx, msg, trigger) {
   const dashboards = source.generateDashboardsForGraph(childSource, {
     includeChildren: Boolean(msg.includeChildren ?? true),
   });
@@ -77,9 +51,73 @@ function registerChild(source, msg, ctx) {
         softwareType: dash.softwareType,
         uid: dash.uid,
         title: dash.title,
+        trigger,
       },
     });
   }
+
+  if (source.logger?.info) {
+    source.logger.info({
+      event: 'regen-emitted',
+      trigger,
+      dashboardApiId: ctx.node?.id,
+      childId: childSource?.config?.general?.id,
+      dashboardCount: dashboards.length,
+    });
+  }
 }
 
-module.exports = { registerChild };
+// On child.register: build the dashboard graph (root + direct children) and
+// emit one Grafana upsert HTTP request per dashboard on Port 0.
+//
+// Diff-skip behavior (PRD F-1, S1 spike #32): if the latest flows:started
+// payload's `diff` indicates that NEITHER the dashboardAPI itself NOR this
+// child NOR its grandchildren changed, skip composition and log no-diff. The
+// first call after startup (no cached diff yet) regenerates unconditionally.
+function registerChild(source, msg, ctx) {
+  const childSource = resolveChildSource(msg.payload, ctx);
+  if (!childSource?.config) {
+    throw new Error('Missing or invalid child node');
+  }
+
+  // Cache the child source for later manual regen (#41).
+  source.recordChild?.(childSource);
+
+  const subtreeIds = source.subtreeIdsFor(ctx.node?.id, childSource);
+  const changed = source.subtreeChanged(source.lastFlowsStartedDiff, subtreeIds);
+  if (!changed) {
+    if (source.logger?.info) {
+      source.logger.info({
+        event: 'regen-skipped',
+        outcome: 'no-diff',
+        trigger: 'child.register',
+        dashboardApiId: ctx.node?.id,
+        childId: childSource?.config?.general?.id,
+        subtreeSize: subtreeIds.size,
+      });
+    }
+    return;
+  }
+
+  emitDashboardsFor(source, childSource, ctx, msg, 'child.register');
+}
+
+// On regenerate-dashboard: re-emit dashboards for every cached child source,
+// bypassing the diff predicate. Useful as an operator escape hatch when
+// auto-regen missed an edge case or when the operator just wants to refresh.
+function regenerateDashboard(source, msg, ctx) {
+  const cached = source.cachedChildSources?.() || [];
+  if (source.logger?.info) {
+    source.logger.info({
+      event: 'manual-regen-requested',
+      trigger: 'manual',
+      dashboardApiId: ctx.node?.id,
+      cachedChildCount: cached.length,
+    });
+  }
+  for (const childSource of cached) {
+    emitDashboardsFor(source, childSource, ctx, msg, 'manual');
+  }
+}
+
+module.exports = { registerChild, regenerateDashboard };

src/commands/index.js

@@ -13,4 +13,10 @@ module.exports = [
     payloadSchema: { type: 'any' },
     handler: handlers.registerChild,
   },
+  {
+    topic: 'regenerate-dashboard',
+    aliases: ['regen'],
+    payloadSchema: { type: 'any' },
+    handler: handlers.regenerateDashboard,
+  },
 ];

src/specificClass.js

@@ -75,6 +75,20 @@ class DashboardApi {
       this.config.general.logging.logLevel,
       this.config.general.name
     );
+
+    // Light state cache for manual regen (#41). Stores the latest child
+    // source object per child id so `regenerate-dashboard` can re-emit
+    // dashboards without waiting for children to re-register.
+    this._lastChildSources = new Map();
+  }
+
+  recordChild(childSource) {
+    const id = childSource?.config?.general?.id;
+    if (id) this._lastChildSources.set(id, childSource);
+  }
+
+  cachedChildSources() {
+    return Array.from(this._lastChildSources.values());
   }
 
   _templatesDir() {

test/basic/slice41-manual-regen.basic.test.js

@@ -0,0 +1,75 @@
+'use strict';
+
+const test = require('node:test');
+const assert = require('node:assert/strict');
+
+const DashboardApi = require('../../src/specificClass.js');
+const handlers = require('../../src/commands/handlers.js');
+
+function makeCtx(sends, nodeId = 'dApi-1') {
+  return {
+    node: { id: nodeId },
+    RED: { nodes: { getNode: () => null } },
+    send: (m) => sends.push(m),
+    logger: null,
+  };
+}
+
+function makeChildPayload(id, softwareType = 'measurement') {
+  return {
+    config: {
+      general: { id, name: id },
+      functionality: { softwareType, positionVsParent: 'downstream' },
+    },
+  };
+}
+
+test('recordChild caches child source by id; subsequent ones replace by id', () => {
+  const api = new DashboardApi({});
+  api.recordChild(makeChildPayload('a'));
+  api.recordChild(makeChildPayload('b'));
+  api.recordChild(makeChildPayload('a')); // replace
+  assert.equal(api.cachedChildSources().length, 2);
+});
+
+test('regenerate-dashboard with no cached children is a no-op (no msgs emitted)', () => {
+  const api = new DashboardApi({});
+  const sends = [];
+  handlers.regenerateDashboard(api, { topic: 'regenerate-dashboard', payload: {} }, makeCtx(sends));
+  assert.equal(sends.length, 0);
+});
+
+test('regenerate-dashboard re-emits for each cached child, bypassing diff', () => {
+  const api = new DashboardApi({});
+  // Pre-populate cache as if two children had registered.
+  api.recordChild(makeChildPayload('m-1'));
+  api.recordChild(makeChildPayload('m-2'));
+
+  // Set a diff that says nothing changed — registerChild would skip, but
+  // regenerateDashboard should ignore the predicate.
+  api.lastFlowsStartedDiff = { added: [], changed: [], removed: [], rewired: [] };
+
+  const sends = [];
+  handlers.regenerateDashboard(api, { topic: 'regenerate-dashboard', payload: {} }, makeCtx(sends));
+  // Each child yields at least one dashboard message (the root for the child's view).
+  assert.ok(sends.length >= 2, `expected ≥2 emitted msgs, got ${sends.length}`);
+  // Every emitted msg carries trigger: 'manual' in meta.
+  for (const m of sends) assert.equal(m.meta?.trigger, 'manual');
+});
+
+test('child.register stamps trigger: child.register in emitted msg meta', () => {
+  const api = new DashboardApi({});
+  api.lastFlowsStartedDiff = null; // cold-start → always regen
+  const sends = [];
+  handlers.registerChild(api, { topic: 'child.register', payload: makeChildPayload('m-3') }, makeCtx(sends));
+  assert.ok(sends.length >= 1);
+  for (const m of sends) assert.equal(m.meta?.trigger, 'child.register');
+});
+
+test('command registry exposes regenerate-dashboard with regen alias', () => {
+  const registry = require('../../src/commands/index.js');
+  const entry = registry.find((e) => e.topic === 'regenerate-dashboard');
+  assert.ok(entry, 'topic registered');
+  assert.deepEqual(entry.aliases, ['regen']);
+  assert.equal(typeof entry.handler, 'function');
+});