@mxtommy/kip 4.4.0 → 4.5.0-beta.1

package/.github/copilot-instructions.md

@@ -132,6 +132,7 @@ Template:
 - CommonJS deps are explicitly allowed (js-quantities). Avoid introducing new CJS without adding to allowedCommonJsDependencies.
 - Use standalone components, signals, @if/@for; follow .github/instructions/angular.instructions.md for style.
 - Widget config UIs live under src/app/widget-config; path controls use custom validators (no Validators.required). Respect isPathConfigurable and pathRequired.
+- Documentation standard: Every public property and public method in TypeScript code MUST include full JSDoc with: purpose, parameters, return value, and at least one usage example. Apply this by default for all generated/edited code unless a file explicitly cannot use comments.
 
 ## Widgets: do this, not that (Host2)
 - Do: Provide a complete `DEFAULT_CONFIG` with all paths & options. Don’t: Scatter defaults across lifecycle hooks.
@@ -143,10 +144,12 @@ Template:
 
 ## Key files/dirs
 - Core services: `src/app/core/services/` (DataService, SignalKConnectionService, SignalKDeltaService, AppNetworkInitService, UnitsService, DataSetService, NotificationsService)
+- Plugin config foundation: `src/app/core/services/signalk-plugin-config.service.ts` (plugin-only detection, dependency validation, schema normalization metadata, and config persistence via `/plugins` endpoints)
 - Directives: `src/app/core/directives/` (widget-runtime, widget-streams, widget-metadata)
 - Widgets: `src/app/widgets/` (e.g., widget-numeric, widget-gauge-ng-*, widget-data-chart, widget-windtrends-chart, widget-autopilot)
 - Embedded host: `src/app/core/components/widget-embedded/`
 - Config UI: `src/app/widget-config/`
+- Plugin management (server plugins) is handled separately through `SignalkPluginConfigService` and `/plugins` REST endpoints. Keep install/uninstall out of scope unless explicitly added.
 - Build: `angular.json`, `package.json` scripts
 
 ## Debugging

package/.github/instructions/best-practices.instructions.md

@@ -53,3 +53,7 @@ You are an expert in TypeScript, Angular, and scalable web application developme
 - Design services around a single responsibility
 - Use the `providedIn: 'root'` option for singleton services
 - Use the `inject()` function instead of constructor injection
+
+## Documentation
+
+- Every public TypeScript property and public method MUST include full JSDoc with: purpose, parameters, return value, and at least one usage example.

package/.github/instructions/project.instructions.md

@@ -53,6 +53,7 @@ KIP Instrument MFD is an advanced and versatile marine instrumentation package d
 ## 6. Documentation & Comments
 - **Document all custom validators and business rules.**
 - **Update this file and the README with any major changes or new patterns.**
+- **JSDoc requirement:** Every public TypeScript property and public method must include full JSDoc containing: purpose, parameters, return value, and at least one usage example.
 
 ---
 
@@ -136,11 +137,11 @@ All major services in `src/app/core/services/` are summarized below for Copilot
   - Key methods: Data set CRUD, data source updates.
   - Dependencies: DataService, StorageService.
 
-- **SignalKPluginsService (`signalk-plugins.service.ts`)**
-  - Purpose: Manages Signal K plugin discovery, configuration, and state.
-  - Key methods: Plugin list management, config updates.
-  - Dependencies: SignalKConnectionService, DataService.
-  - Usage: Used to manage plugins and their configuration.
+- **SignalkPluginConfigService (`signalk-plugin-config.service.ts`)**
+  - Purpose: Plugin configuration foundation service for dependency checks and plugin state/config persistence via Signal K `/plugins` endpoints.
+  - Key methods: `listPlugins()`, `getPlugin()`, `getPluginConfig()`, `savePluginConfig()`, `setPluginEnabled()`, `validateDependency()`, `normalizePluginSchema()`.
+  - Dependencies: HttpClient, SignalKConnectionService.
+  - Usage: Source of truth for plugin detection and config save flows; no plugin install/uninstall support.
 
 - **SignalKRequestsService (`signalk-requests.service.ts`)**
   - Purpose: Handles requests to the Signal K server, such as PUT/POST operations and custom actions.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mxtommy/kip",
-  "version": "4.4.0",
+  "version": "4.5.0-beta.1",
   "description": "An advanced and versatile marine instrumentation package to display Signal K data.",
   "license": "MIT",
   "author": {

package/plugin/index.js

@@ -36,11 +36,18 @@ Object.defineProperty(exports, "__esModule", { value: true });
 const server_api_1 = require("@signalk/server-api");
 const openapi = __importStar(require("./openApi.json"));
 const start = (server) => {
+    const mutableOpenApi = JSON.parse(JSON.stringify(openapi.default ?? openapi));
     const API_PATHS = {
         DISPLAYS: `/displays`,
         INSTANCE: `/displays/:displayId`,
-        ACTIVE_SCREEN: `/displays/:displayId/screenIndex`,
-        CHANGE_SCREEN: `/displays/:displayId/activeScreen`
+        SCREEN_INDEX: `/displays/:displayId/screenIndex`,
+        ACTIVATE_SCREEN: `/displays/:displayId/activeScreen`
+    };
+    const PUT_CONTEXT = 'vessels.self';
+    const COMMAND_PATHS = {
+        SET_DISPLAY: 'kip.remote.setDisplay',
+        SET_SCREEN_INDEX: 'kip.remote.setScreenIndex',
+        REQUEST_ACTIVE_SCREEN: 'kip.remote.requestActiveScreen'
     };
     const CONFIG_SCHEMA = {
         properties: {
@@ -64,11 +71,6 @@ const start = (server) => {
         server.debug(`getAvailableDisplays: fullPath=${JSON.stringify(fullPath)}`);
         return typeof fullPath === 'object' && fullPath !== null ? fullPath : undefined;
     }
-    function pathToDotNotation(path) {
-        const dottedPath = path.replace(/\//g, '.').replace(/^\./, '');
-        server.debug(`pathToDotNotation: input path=${path}, dottedPath=${dottedPath}`);
-        return dottedPath;
-    }
     function sendOk(res, body) {
         if (body === undefined)
             return res.status(204).end();
@@ -77,12 +79,91 @@ const start = (server) => {
     function sendFail(res, statusCode, message) {
         return res.status(statusCode).json({ state: 'FAILED', statusCode, message });
     }
+    function completed(statusCode, message) {
+        return { state: 'COMPLETED', statusCode, message };
+    }
+    function isValidDisplayId(displayId) {
+        return typeof displayId === 'string' && /^[A-Za-z0-9-]+$/.test(displayId);
+    }
+    function applyDisplayWrite(displayId, suffix, value) {
+        const path = suffix ? `displays.${displayId}.${suffix}` : `displays.${displayId}`;
+        try {
+            server.handleMessage(plugin.id, {
+                updates: [
+                    {
+                        values: [
+                            {
+                                path: path,
+                                value: value ?? null
+                            }
+                        ]
+                    }
+                ]
+            }, server_api_1.SKVersion.v1);
+            return completed(200);
+        }
+        catch (error) {
+            const message = error?.message ?? 'Unable to write display path';
+            return completed(400, message);
+        }
+    }
+    function handleSetDisplay(value) {
+        const command = value;
+        if (!command || typeof command !== 'object') {
+            return completed(400, 'Command payload is required');
+        }
+        if (!isValidDisplayId(command.displayId)) {
+            return completed(400, 'Invalid displayId format');
+        }
+        const displayValue = command.display ?? null;
+        if (displayValue !== null && typeof displayValue !== 'object') {
+            return completed(400, 'display must be an object or null');
+        }
+        return applyDisplayWrite(command.displayId, null, displayValue);
+    }
+    function handleScreenWrite(value, suffix) {
+        const command = value;
+        if (!command || typeof command !== 'object') {
+            return completed(400, 'Command payload is required');
+        }
+        if (!isValidDisplayId(command.displayId)) {
+            return completed(400, 'Invalid displayId format');
+        }
+        const screenIdxValue = command.screenIdx ?? null;
+        if (screenIdxValue !== null && typeof screenIdxValue !== 'number') {
+            return completed(400, 'screenIdx must be a number or null');
+        }
+        return applyDisplayWrite(command.displayId, suffix, screenIdxValue);
+    }
+    function sendActionAsRest(res, result) {
+        if (result.statusCode === 200) {
+            return res.status(200).json({ state: 'SUCCESS', statusCode: 200 });
+        }
+        return sendFail(res, result.statusCode || 400, result.message || 'Command failed');
+    }
     const plugin = {
         id: 'kip',
         name: 'KIP',
         description: 'KIP server plugin',
         start: (settings) => {
             server.debug(`Starting plugin with settings: ${JSON.stringify(settings)}`);
+            if (server.registerPutHandler) {
+                server.registerPutHandler(PUT_CONTEXT, COMMAND_PATHS.SET_DISPLAY, (context, path, value) => {
+                    void context;
+                    void path;
+                    return handleSetDisplay(value);
+                }, plugin.id);
+                server.registerPutHandler(PUT_CONTEXT, COMMAND_PATHS.SET_SCREEN_INDEX, (context, path, value) => {
+                    void context;
+                    void path;
+                    return handleScreenWrite(value, 'screenIndex');
+                }, plugin.id);
+                server.registerPutHandler(PUT_CONTEXT, COMMAND_PATHS.REQUEST_ACTIVE_SCREEN, (context, path, value) => {
+                    void context;
+                    void path;
+                    return handleScreenWrite(value, 'activeScreen');
+                }, plugin.id);
+            }
             server.setPluginStatus(`Starting...`);
         },
         stop: () => {
@@ -92,7 +173,7 @@ const start = (server) => {
         },
         schema: () => CONFIG_SCHEMA,
         registerWithRouter(router) {
-            server.debug(`Registering plugin routes: ${API_PATHS.DISPLAYS}, ${API_PATHS.INSTANCE}, ${API_PATHS.ACTIVE_SCREEN}, ${API_PATHS.CHANGE_SCREEN}`);
+            server.debug(`Registering plugin routes: ${API_PATHS.DISPLAYS}, ${API_PATHS.INSTANCE}, ${API_PATHS.SCREEN_INDEX}, ${API_PATHS.ACTIVATE_SCREEN}`);
             // Validate/normalize :displayId where present
             router.param('displayId', (req, res, next, displayId) => {
                 if (displayId == null)
@@ -135,21 +216,12 @@ const start = (server) => {
             router.put(`${API_PATHS.INSTANCE}`, async (req, res) => {
                 server.debug(`** PUT ${API_PATHS.INSTANCE}. Params: ${JSON.stringify(req.params)} Body: ${JSON.stringify(req.body)}`);
                 try {
-                    const dottedPath = pathToDotNotation(req.path);
-                    server.debug(`Updating SK path ${dottedPath}`);
-                    server.handleMessage(plugin.id, {
-                        updates: [
-                            {
-                                values: [
-                                    {
-                                        path: dottedPath,
-                                        value: req.body ?? null
-                                    }
-                                ]
-                            }
-                        ]
-                    }, server_api_1.SKVersion.v1);
-                    return res.status(200).json({ state: 'SUCCESS', statusCode: 200 });
+                    const displayId = req.displayId;
+                    if (!displayId) {
+                        return sendFail(res, 400, 'Missing displayId parameter');
+                    }
+                    const result = handleSetDisplay({ displayId, display: req.body ?? null });
+                    return sendActionAsRest(res, result);
                 }
                 catch (error) {
                     const msg = `HandleMessage failed with errors!`;
@@ -158,24 +230,18 @@ const start = (server) => {
                     return sendFail(res, 400, error.message);
                 }
             });
-            router.put(`${API_PATHS.ACTIVE_SCREEN}`, async (req, res) => {
-                server.debug(`** PUT ${API_PATHS.ACTIVE_SCREEN}. Params: ${JSON.stringify(req.params)} Body: ${JSON.stringify(req.body)}`);
+            router.put(`${API_PATHS.SCREEN_INDEX}`, async (req, res) => {
+                server.debug(`** PUT ${API_PATHS.SCREEN_INDEX}. Params: ${JSON.stringify(req.params)} Body: ${JSON.stringify(req.body)}`);
                 try {
-                    const dottedPath = pathToDotNotation(req.path);
-                    server.debug(`Updating SK path ${dottedPath} with body.screenIdx`);
-                    server.handleMessage(plugin.id, {
-                        updates: [
-                            {
-                                values: [
-                                    {
-                                        path: dottedPath,
-                                        value: req.body.screenIdx !== undefined ? req.body.screenIdx : null
-                                    }
-                                ]
-                            }
-                        ]
-                    }, server_api_1.SKVersion.v1);
-                    return res.status(200).json({ state: 'SUCCESS', statusCode: 200 });
+                    const displayId = req.displayId;
+                    if (!displayId) {
+                        return sendFail(res, 400, 'Missing displayId parameter');
+                    }
+                    const result = handleScreenWrite({
+                        displayId,
+                        screenIdx: req.body?.screenIdx !== undefined ? req.body.screenIdx : null
+                    }, 'screenIndex');
+                    return sendActionAsRest(res, result);
                 }
                 catch (error) {
                     const msg = `HandleMessage failed with errors!`;
@@ -184,24 +250,18 @@ const start = (server) => {
                     return sendFail(res, 400, error.message);
                 }
             });
-            router.put(`${API_PATHS.CHANGE_SCREEN}`, async (req, res) => {
-                server.debug(`** PUT ${API_PATHS.CHANGE_SCREEN}. Params: ${JSON.stringify(req.params)} Body: ${JSON.stringify(req.body)}`);
+            router.put(`${API_PATHS.ACTIVATE_SCREEN}`, async (req, res) => {
+                server.debug(`** PUT ${API_PATHS.ACTIVATE_SCREEN}. Params: ${JSON.stringify(req.params)} Body: ${JSON.stringify(req.body)}`);
                 try {
-                    const dottedPath = pathToDotNotation(req.path);
-                    server.debug(`Updating SK path ${dottedPath} with body.screenIdx`);
-                    server.handleMessage(plugin.id, {
-                        updates: [
-                            {
-                                values: [
-                                    {
-                                        path: dottedPath,
-                                        value: req.body.screenIdx !== undefined ? req.body.screenIdx : null
-                                    }
-                                ]
-                            }
-                        ]
-                    }, server_api_1.SKVersion.v1);
-                    return res.status(200).json({ state: 'SUCCESS', statusCode: 200 });
+                    const displayId = req.displayId;
+                    if (!displayId) {
+                        return sendFail(res, 400, 'Missing displayId parameter');
+                    }
+                    const result = handleScreenWrite({
+                        displayId,
+                        screenIdx: req.body?.screenIdx !== undefined ? req.body.screenIdx : null
+                    }, 'activeScreen');
+                    return sendActionAsRest(res, result);
                 }
                 catch (error) {
                     const msg = `HandleMessage failed with errors!`;
@@ -252,8 +312,8 @@ const start = (server) => {
                     return sendFail(res, 400, error.message);
                 }
             });
-            router.get(`${API_PATHS.ACTIVE_SCREEN}`, (req, res) => {
-                server.debug(`*** GET ACTIVE_SCREEN ${API_PATHS.ACTIVE_SCREEN}. Params: ${JSON.stringify(req.params)}`);
+            router.get(`${API_PATHS.SCREEN_INDEX}`, (req, res) => {
+                server.debug(`*** GET SCREEN_INDEX ${API_PATHS.SCREEN_INDEX}. Params: ${JSON.stringify(req.params)}`);
                 try {
                     const displayId = req.displayId;
                     if (!displayId) {
@@ -272,23 +332,23 @@ const start = (server) => {
                     return sendFail(res, 400, error.message);
                 }
             });
-            router.get(`${API_PATHS.CHANGE_SCREEN}`, (req, res) => {
-                server.debug(`*** GET CHANGE_SCREEN ${API_PATHS.CHANGE_SCREEN}. Params: ${JSON.stringify(req.params)}`);
+            router.get(`${API_PATHS.ACTIVATE_SCREEN}`, (req, res) => {
+                server.debug(`*** GET ACTIVATE_SCREEN ${API_PATHS.ACTIVATE_SCREEN}. Params: ${JSON.stringify(req.params)}`);
                 try {
-                    const changeId = req.changeId;
-                    if (!changeId) {
-                        return sendFail(res, 400, 'Missing changeId parameter');
+                    const displayId = req.displayId;
+                    if (!displayId) {
+                        return sendFail(res, 400, 'Missing displayId parameter');
                     }
-                    const node = getDisplaySelfPath(changeId, 'activeScreen');
+                    const node = getDisplaySelfPath(displayId, 'activeScreen');
                     // eslint-disable-next-line @typescript-eslint/no-explicit-any
                     const idx = node?.value ?? null;
                     if (idx === undefined) {
-                        return sendFail(res, 404, `Change display screen Id ${changeId} not found in path`);
+                        return sendFail(res, 404, `Change display screen Id ${displayId} not found in path`);
                     }
                     return sendOk(res, idx);
                 }
                 catch (error) {
-                    server.error(`Error reading activeScreen for ${req.params?.changeId}: ${String(error.message || error)}`);
+                    server.error(`Error reading activeScreen for ${req.params?.displayId}: ${String(error.message || error)}`);
                     return sendFail(res, 400, error.message);
                 }
             });
@@ -302,7 +362,7 @@ const start = (server) => {
             }
             server.setPluginStatus(`Providing remote display screen control`);
         },
-        getOpenApi: () => openapi
+        getOpenApi: () => mutableOpenApi
     };
     return plugin;
 };

package/plugin/openApi.json

@@ -63,17 +63,11 @@
                 ]
             },
             "ScreenListOrNull": {
-                "oneOf": [
-                    {
-                        "type": "array",
-                        "items": {
-                            "$ref": "#/components/schemas/ScreenItem"
-                        }
-                    },
-                    {
-                        "type": "null"
-                    }
-                ]
+                "type": "array",
+                "nullable": true,
+                "items": {
+                    "$ref": "#/components/schemas/ScreenItem"
+                }
             },
             "SuccessResponse": {
                 "type": "object",
@@ -129,15 +123,9 @@
                 }
             },
             "AnyObjectOrNull": {
-                "oneOf": [
-                    {
-                        "type": "object",
-                        "additionalProperties": true
-                    },
-                    {
-                        "type": "null"
-                    }
-                ]
+                "type": "object",
+                "nullable": true,
+                "additionalProperties": true
             }
         },
         "parameters": {