signalk-maintenance-tracker 1.0.0

package/package.json

@@ -0,0 +1,82 @@
+{
+  "name": "signalk-maintenance-tracker",
+  "version": "1.0.0",
+  "description": "Track recurring boat maintenance tasks with runtime and calendar based intervals.",
+  "main": "dist/index.js",
+  "license": "MIT",
+  "author": "Zach Hoeken <hoeken@gmail.com>",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/hoeken/signalk-maintenance-tracker"
+  },
+  "keywords": [
+    "signalk-node-server-plugin",
+    "signalk-webapp",
+    "signalk-category-utility",
+    "signalk",
+    "maintenance",
+    "boat"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "watch:backend": "tsc -w",
+    "typecheck:frontend": "npm --prefix frontend run typecheck",
+    "test:backend": "vitest run",
+    "test:frontend": "npm --prefix frontend run test",
+    "test": "npm run test:backend && npm run test:frontend",
+    "icons": "npm --prefix frontend run icons",
+    "clean": "rm -rf dist",
+    "lint": "eslint .",
+    "lint:fix": "eslint --fix .",
+    "format": "eslint --fix . && prettier --write .",
+    "format:check": "eslint . && prettier --check .",
+    "prepublishOnly": "npm run build",
+    "release": "git tag -d v$npm_package_version; git tag v$npm_package_version && git push && git push origin v$npm_package_version",
+    "prepare": "husky"
+  },
+  "lint-staged": {
+    "*.{ts,js,mjs,cjs}": [
+      "eslint --fix",
+      "prettier --write"
+    ],
+    "*.{json,css,html,md,yml,yaml}": "prettier --write"
+  },
+  "signalk": {
+    "displayName": "Maintenance Tracker",
+    "appIcon": "icons/icon-192.png",
+    "screenshots": [
+      "./docs/screenshots/homepage.png",
+      "./docs/screenshots/dark-mode.png",
+      "./docs/screenshots/task-detail.png",
+      "./docs/screenshots/edit-task.png",
+      "./docs/screenshots/completed.png",
+      "./docs/screenshots/main-log.png"
+    ]
+  },
+  "files": [
+    "dist/",
+    "public/",
+    "docs/screenshots/",
+    "CHANGELOG.md"
+  ],
+  "engines": {
+    "node": ">=22.5"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@types/express": "^4.17.21",
+    "@types/node": "^24.0.0",
+    "@types/supertest": "^6.0.0",
+    "eslint": "^10.6.0",
+    "eslint-config-prettier": "^10.1.8",
+    "express": "^4.19.0",
+    "globals": "^17.7.0",
+    "husky": "^9.1.7",
+    "lint-staged": "^17.0.8",
+    "prettier": "^3.9.4",
+    "supertest": "^7.0.0",
+    "typescript": "^5.5.0",
+    "typescript-eslint": "^8.63.0",
+    "vitest": "^3.0.0"
+  }
+}

package/public/app/api/client.js

@@ -0,0 +1,75 @@
+/**
+ * Thin fetch wrapper for the plugin REST API (§7.6). Prefixes the base path,
+ * sends the same-origin session cookie, normalizes JSON + errors, and routes
+ * 401/403 into the auth layer.
+ */
+import { onUnauthorized } from '../auth/auth.js';
+
+export const API_BASE = '/plugins/signalk-maintenance-tracker/api';
+
+export class ApiError extends Error {
+  /**
+   * @param {number} status
+   * @param {string} code
+   * @param {string} message
+   */
+  constructor(status, code, message) {
+    super(message);
+    this.name = 'ApiError';
+    this.status = status;
+    this.code = code;
+  }
+}
+
+/**
+ * @param {string} path e.g. '/tasks?page=1'
+ * @param {{ method?: string, body?: unknown }} [options]
+ * @returns {Promise<any>} parsed JSON body (null for 204)
+ */
+export async function apiFetch(path, options) {
+  const opts = options || {};
+  /** @type {RequestInit} */
+  const init = { method: opts.method || 'GET', credentials: 'same-origin' };
+  if (opts.body !== undefined) {
+    init.headers = { 'Content-Type': 'application/json' };
+    init.body = JSON.stringify(opts.body);
+  }
+  const res = await fetch(API_BASE + path, init);
+  if (res.status === 401 || res.status === 403) onUnauthorized();
+  const text = await res.text();
+  /** @type {any} */
+  let body = null;
+  if (text) {
+    try {
+      body = JSON.parse(text);
+    } catch {
+      body = null;
+    }
+  }
+  if (!res.ok) {
+    const errInfo = body && body.error ? body.error : {};
+    throw new ApiError(
+      res.status,
+      errInfo.code || 'http_' + res.status,
+      errInfo.message || 'Request failed (' + res.status + ')',
+    );
+  }
+  return body;
+}
+
+/**
+ * Build a query string from params, skipping empty values.
+ * @param {Record<string, string|number|undefined|null>} [params]
+ * @returns {string} '' or '?a=b&c=d'
+ */
+export function buildQuery(params) {
+  if (!params) return '';
+  const usp = new URLSearchParams();
+  for (const key of Object.keys(params)) {
+    const value = params[key];
+    if (value !== undefined && value !== null && value !== '')
+      usp.set(key, String(value));
+  }
+  const qs = usp.toString();
+  return qs ? '?' + qs : '';
+}

package/public/app/api/hooks.js

@@ -0,0 +1,159 @@
+/**
+ * Signals-backed resource hooks + mutations over the plugin REST API (§7.6).
+ * Mutations invalidate the affected keys on success so the UI updates
+ * immediately instead of waiting for the next poll.
+ */
+import { apiFetch, buildQuery } from './client.js';
+import { useResource, invalidate } from './resource.js';
+
+/** @typedef {import('../types.js').TaskDTO} TaskDTO */
+/** @typedef {import('../types.js').LogDTO} LogDTO */
+/** @typedef {import('../types.js').TagDTO} TagDTO */
+/** @typedef {import('../types.js').TaskInput} TaskInput */
+/** @typedef {import('../types.js').LogInput} LogInput */
+
+/** Default poll interval for live-updating lists (§7.6). */
+export const POLL_MS = 5000;
+
+/** @param {string} slug */
+function encodeSlug(slug) {
+  return encodeURIComponent(slug);
+}
+
+/**
+ * @param {Record<string, string|number|undefined|null>} [params]
+ * @returns {import('./resource.js').ResourceState<import('../types.js').Page<TaskDTO>>}
+ */
+export function useTasks(params) {
+  const query = buildQuery(params);
+  return useResource('tasks' + query, () => apiFetch('/tasks' + query), {
+    refetchInterval: POLL_MS,
+  });
+}
+
+/**
+ * @param {string} slug
+ * @returns {import('./resource.js').ResourceState<TaskDTO>}
+ */
+export function useTask(slug) {
+  return useResource(
+    'task/' + slug,
+    () => apiFetch('/tasks/' + encodeSlug(slug)),
+    {
+      refetchInterval: POLL_MS,
+    },
+  );
+}
+
+/**
+ * @param {string} slug
+ * @returns {import('./resource.js').ResourceState<{data: LogDTO[]}>}
+ */
+export function useTaskLogs(slug) {
+  return useResource(
+    'task/' + slug + '/logs',
+    () => apiFetch('/tasks/' + encodeSlug(slug) + '/logs'),
+    {
+      refetchInterval: POLL_MS,
+    },
+  );
+}
+
+/**
+ * @param {Record<string, string|number|undefined|null>} [params]
+ * @returns {import('./resource.js').ResourceState<import('../types.js').Page<LogDTO>>}
+ */
+export function useLogs(params) {
+  const query = buildQuery(params);
+  return useResource('logs' + query, () => apiFetch('/logs' + query), {
+    refetchInterval: POLL_MS,
+  });
+}
+
+/**
+ * @returns {import('./resource.js').ResourceState<{data: TagDTO[]}>}
+ */
+export function useTags() {
+  return useResource('tags', () => apiFetch('/tags'), {
+    refetchInterval: POLL_MS,
+  });
+}
+
+/**
+ * Plugin health/version (§8.5). Fetched once; the version can't change
+ * without a server restart, so no polling.
+ * @returns {import('./resource.js').ResourceState<{version: string}>}
+ */
+export function useHealth() {
+  return useResource('health', () => apiFetch('/health'));
+}
+
+// ---- mutations ----
+
+/**
+ * @param {TaskInput} input
+ * @returns {Promise<TaskDTO>}
+ */
+export async function createTask(input) {
+  const task = await apiFetch('/tasks', { method: 'POST', body: input });
+  invalidate('tasks', 'tags');
+  return task;
+}
+
+/**
+ * @param {string} slug
+ * @param {TaskInput} input
+ * @returns {Promise<TaskDTO>}
+ */
+export async function updateTask(slug, input) {
+  const task = await apiFetch('/tasks/' + encodeSlug(slug), {
+    method: 'PUT',
+    body: input,
+  });
+  invalidate('tasks', 'task/' + slug, 'tags', 'logs');
+  if (task && task.slug !== slug) invalidate('task/' + task.slug);
+  return task;
+}
+
+/** @param {string} slug */
+export async function deleteTask(slug) {
+  await apiFetch('/tasks/' + encodeSlug(slug), { method: 'DELETE' });
+  invalidate('tasks', 'task/' + slug, 'tags', 'logs');
+}
+
+/**
+ * Mark complete (§7.5): create a log entry for the task.
+ * @param {string} slug
+ * @param {LogInput} input
+ * @returns {Promise<LogDTO>}
+ */
+export async function addLog(slug, input) {
+  const entry = await apiFetch('/tasks/' + encodeSlug(slug) + '/logs', {
+    method: 'POST',
+    body: input,
+  });
+  invalidate('tasks', 'task/' + slug, 'logs');
+  return entry;
+}
+
+/**
+ * @param {number} id
+ * @param {LogInput} input
+ * @returns {Promise<LogDTO>}
+ */
+export async function updateLog(id, input) {
+  const entry = await apiFetch('/logs/' + id, { method: 'PUT', body: input });
+  invalidate('tasks', 'logs');
+  if (entry && entry.task_slug) invalidate('task/' + entry.task_slug);
+  return entry;
+}
+
+/**
+ * @param {number} id
+ * @param {string} [taskSlug] invalidates that task's detail/logs when known
+ */
+export async function deleteLog(id, taskSlug) {
+  await apiFetch('/logs/' + id, { method: 'DELETE' });
+  invalidate('tasks', 'logs');
+  if (taskSlug) invalidate('task/' + taskSlug);
+}

package/public/app/api/resource.js

@@ -0,0 +1,156 @@
+/**
+ * Hand-rolled signals-backed resource layer (§7.6): cache-by-key, polling
+ * while subscribed, and invalidation. The essentials of react-query in a few
+ * dozen lines, with no post-Chromium-69 runtime APIs.
+ */
+import { signal } from '../../vendor/signals.js';
+import { useEffect } from '../../vendor/preact-hooks.js';
+
+/**
+ * @template T
+ * @typedef {{ data: T|null, error: Error|null, loading: boolean }} ResourceState
+ */
+
+/**
+ * @typedef {Object} Entry
+ * @property {string} key
+ * @property {() => Promise<any>} fetcher
+ * @property {number} refetchInterval 0 = never poll
+ * @property {import('../../vendor/signals.js').Signal<ResourceState<any>>} state
+ * @property {number} subscribers
+ * @property {ReturnType<typeof setInterval>|null} timer
+ * @property {number} fetchId
+ * @property {boolean} fetched
+ */
+
+/** @type {Map<string, Entry>} */
+const registry = new Map();
+
+/**
+ * @param {string} key
+ * @param {() => Promise<any>} fetcher
+ * @param {{ refetchInterval?: number }} [options]
+ * @returns {Entry}
+ */
+function getEntry(key, fetcher, options) {
+  let entry = registry.get(key);
+  if (!entry) {
+    entry = {
+      key: key,
+      fetcher: fetcher,
+      refetchInterval:
+        options && options.refetchInterval ? options.refetchInterval : 0,
+      state: signal({ data: null, error: null, loading: true }),
+      subscribers: 0,
+      timer: null,
+      fetchId: 0,
+      fetched: false,
+    };
+    registry.set(key, entry);
+  }
+  entry.fetcher = fetcher; // latest closure wins (params live in the key)
+  return entry;
+}
+
+/** @param {Entry} entry */
+function runFetch(entry) {
+  const id = ++entry.fetchId;
+  const prev = entry.state.value;
+  entry.state.value = { data: prev.data, error: prev.error, loading: true };
+  entry.fetched = true;
+  entry.fetcher().then(
+    function (data) {
+      if (id === entry.fetchId)
+        entry.state.value = { data: data, error: null, loading: false };
+    },
+    function (error) {
+      // keep stale data visible; surface the error alongside it
+      if (id === entry.fetchId)
+        entry.state.value = { data: prev.data, error: error, loading: false };
+    },
+  );
+}
+
+/**
+ * Subscribe to a keyed resource for the lifetime of the calling component.
+ * Fetches on first subscribe, polls (shared per key) while any subscriber is
+ * mounted, and re-fetches when a component subscribes to an idle key again.
+ *
+ * Reading the returned state inside render subscribes the component via
+ * @preact/signals, so it re-renders on data/error/loading changes.
+ *
+ * @template T
+ * @param {string} key
+ * @param {() => Promise<T>} fetcher
+ * @param {{ refetchInterval?: number }} [options]
+ * @returns {ResourceState<T>}
+ */
+export function useResource(key, fetcher, options) {
+  const entry = getEntry(key, fetcher, options);
+  useEffect(
+    function () {
+      entry.subscribers++;
+      if (entry.subscribers === 1) {
+        if (!entry.fetched || !entry.state.value.loading) runFetch(entry);
+        if (entry.refetchInterval > 0 && !entry.timer) {
+          entry.timer = setInterval(function () {
+            runFetch(entry);
+          }, entry.refetchInterval);
+        }
+      }
+      return function () {
+        entry.subscribers--;
+        if (entry.subscribers <= 0 && entry.timer) {
+          clearInterval(entry.timer);
+          entry.timer = null;
+        }
+      };
+    },
+    [key],
+  );
+  return entry.state.value;
+}
+
+/**
+ * Invalidate resources by key prefix: live ones (with subscribers) refetch
+ * immediately; idle ones are dropped so their next mount refetches.
+ * 'tasks' matches 'tasks' and 'tasks?…' but not 'task/…'.
+ * @param {...string} prefixes
+ */
+export function invalidate() {
+  const prefixes = Array.prototype.slice.call(arguments);
+  const keys = Array.from(registry.keys());
+  for (const key of keys) {
+    const hit = prefixes.some(function (prefix) {
+      return (
+        key === prefix ||
+        key.indexOf(prefix + '?') === 0 ||
+        key.indexOf(prefix + '/') === 0
+      );
+    });
+    if (!hit) continue;
+    const entry = registry.get(key);
+    if (!entry) continue;
+    if (entry.subscribers > 0) runFetch(entry);
+    else registry.delete(key);
+  }
+}
+
+/** Refetch/drop everything (used after login, §7.7). */
+export function invalidateAll() {
+  const keys = Array.from(registry.keys());
+  for (const key of keys) {
+    const entry = registry.get(key);
+    if (!entry) continue;
+    if (entry.subscribers > 0) runFetch(entry);
+    else registry.delete(key);
+  }
+}
+
+/** Test helper: forget all cached resources. */
+export function resetResources() {
+  for (const entry of registry.values()) {
+    if (entry.timer) clearInterval(entry.timer);
+  }
+  registry.clear();
+}

package/public/app/api/signalkPaths.js

@@ -0,0 +1,66 @@
+/**
+ * SignalK runtime-path discovery for the task editor (§8.4). Fetches the
+ * vessels/self snapshot ONCE per app session (lazily, on first task-editor
+ * open), flattens it to candidate path names, and serves autocomplete from
+ * the cached list. Never a source of runtime *values* — those come from the
+ * plugin API as current_runtime.
+ */
+import { useResource } from './resource.js';
+
+/**
+ * Keys that are leaf metadata, not path segments, in the REST snapshot.
+ * @type {Record<string, boolean>}
+ */
+const NON_PATH_KEYS = {
+  value: true,
+  values: true,
+  timestamp: true,
+  $source: true,
+  source: true,
+  meta: true,
+  pgn: true,
+  sentence: true,
+};
+
+/**
+ * Flatten a vessels/self REST snapshot into dotted candidate paths. A node
+ * carrying a `value` key is a leaf; only numeric (or still-null) leaves are
+ * candidates for a runtime path.
+ * @param {any} node
+ * @param {string} [prefix]
+ * @param {string[]} [out]
+ * @returns {string[]} sorted candidate paths
+ */
+export function flattenPaths(node, prefix, out) {
+  const paths = out || [];
+  if (!node || typeof node !== 'object') return paths;
+  if (Object.prototype.hasOwnProperty.call(node, 'value')) {
+    if (prefix && (typeof node.value === 'number' || node.value === null))
+      paths.push(prefix);
+    return paths;
+  }
+  for (const key of Object.keys(node)) {
+    if (NON_PATH_KEYS[key]) continue;
+    const child = node[key];
+    if (!child || typeof child !== 'object') continue; // identity strings like uuid/mmsi
+    flattenPaths(child, prefix ? prefix + '.' + key : key, paths);
+  }
+  if (!prefix) paths.sort();
+  return paths;
+}
+
+/**
+ * @returns {import('./resource.js').ResourceState<string[]>}
+ */
+export function useSignalKPaths() {
+  // No refetchInterval: fetched once and cached for the session (§8.4).
+  return useResource('sk-paths', async () => {
+    const res = await fetch('/signalk/v1/api/vessels/self', {
+      credentials: 'same-origin',
+    });
+    if (!res.ok)
+      throw new Error('SignalK snapshot failed (' + res.status + ')');
+    const snapshot = await res.json();
+    return flattenPaths(snapshot);
+  });
+}

package/public/app/app.js

@@ -0,0 +1,71 @@
+/**
+ * App shell (§7.2): header (title, nav, theme toggle), route switch, footer
+ * (plugin links, auth control), toaster, and the globally-mounted login modal.
+ */
+import { html } from './lib/html.js';
+import { route, matchPath } from './lib/router.js';
+import { useHealth } from './api/hooks.js';
+import { Toaster } from './components/Toaster.js';
+import { ThemeToggle } from './components/ThemeToggle.js';
+import { AuthControl } from './components/AuthControl.js';
+import { LoginModal } from './components/LoginModal.js';
+import { TaskListPage } from './pages/TaskListPage.js';
+import { TaskDetailPage } from './pages/TaskDetailPage.js';
+import { MasterLogPage } from './pages/MasterLogPage.js';
+
+export function App() {
+  const current = route.value;
+  const detailParams = matchPath('/tasks/:slug', current.path);
+  const health = useHealth();
+  const version = health.data && health.data.version;
+
+  let page;
+  if (detailParams) {
+    page = html`<${TaskDetailPage}
+      slug=${detailParams.slug}
+      key=${detailParams.slug}
+    />`;
+  } else if (current.path === '/log') {
+    page = html`<${MasterLogPage} />`;
+  } else {
+    page = html`<${TaskListPage} />`;
+  }
+
+  return html`
+    <div class="shell">
+      <header class="shell-header">
+        <a class="shell-title" href="#/">Maintenance Tracker</a>
+        <nav class="shell-nav">
+          <a
+            class=${'nav-link' + (!detailParams && current.path !== '/log' ? ' active' : '')}
+            href="#/"
+            >Tasks</a
+          >
+          <a
+            class=${'nav-link' + (current.path === '/log' ? ' active' : '')}
+            href="#/log"
+            >Log</a
+          >
+        </nav>
+        <${ThemeToggle} />
+      </header>
+      <main class="shell-main">${page}</main>
+      <footer class="shell-footer">
+        <div class="shell-footer-links">
+          <a
+            href="https://www.npmjs.com/package/signalk-maintenance-tracker"
+            target="_blank"
+            rel="noopener"
+            >signalk-maintenance-tracker</a
+          >
+          ${version && html`<span class="dot-spacer">·</span><span>v${version}</span>`}
+        </div>
+        <div class="shell-footer-auth">
+          <${AuthControl} />
+        </div>
+      </footer>
+      <${Toaster} />
+      <${LoginModal} />
+    </div>
+  `;
+}