signalk-automation-plugin 0.0.1

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026 Hans Tool
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL WARRANTIES OF MERCHANTABILITY
+AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL,
+DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER
+RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF
+CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN
+CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,76 @@
+# signalk-automation-plugin
+
+YAML automations for [Signal K](https://signalk.org), in the spirit of Home Assistant: files you can git, helpers with restart behaviour, and a small webapp for last-run / decision records.
+
+Not Node-RED. Not a Home Assistant YAML clone. Actions are Signal K PUTs, helper writes, notifications, delays, and optional scripts.
+
+## In
+
+- YAML in an automations directory (preferably a git repo). Live snapshot lives in plugin data, not plugin options.
+- Helpers (`boolean` / `number` / `string` / `select`) with `on_start`:
+  - `restore` — survive reboot (save in plugin data, restore on start)
+  - `default` — set `default` on every start
+  - `none` — do nothing on start
+- Path triggers, `choose`, zones, cron `schedule`
+- Actions: `put`, `helper`, `notify`, `delay`, `run`
+- `run:` executes a file under configured `scriptsDir`. **stdout is the value; any stderr is fail**
+- Webapp: per-automation on/off, last result, last N decision records, live YAML, activate another git commit
+
+## Out
+
+- Node-RED flows
+- HA templates / Jinja
+- Arbitrary shell strings (only files under `scriptsDir`, no `..`)
+
+## Plugin config
+
+| Option | Meaning |
+| --- | --- |
+| Automations git / YAML directory | Folder with `*.yaml` at the top level. Git repo (or a subdir of one) → commit list in the webapp; “make live” archives only this folder |
+| Allowed scripts directory | Only relative `run.file` paths under this dir |
+| Decision records to keep | Ring buffer per automation |
+| Script timeout | Seconds |
+
+Do not paste automations into the admin form. Runtime state is `~/.signalk/plugin-config-data/signalk-automation-plugin/` (`state.json`, `live/`, `traces/`).
+
+## Example
+
+See `examples/automations.yaml`. Copy or point `automationsDir` at a repo of your own; bundled examples are `enabled: false`.
+
+```yaml
+helpers:
+  starlink_manual:
+    type: boolean
+    default: false
+    on_start: restore   # survive reboot
+    latch_on_external_put: electrical.switches.starlink.state
+
+automations:
+  - id: start_anchorwatch
+    trigger:
+      - path: winches.windlass.rode
+        above: 2
+        unit: m
+        for: 10s
+    action:
+      - put: navigation.anchor.watch
+        value: true
+```
+
+Script action:
+
+```yaml
+- run:
+    file: check-harbour.py
+  as: harbour_ok          # optional helper id to store stdout
+```
+
+## Webapp
+
+Webapps → **Automations**. Reads go through `/signalk/v1/api/signalk-automation-plugin/` (SK 2.x). Writes (on/off, make live, helper reset) use `/plugins/signalk-automation-plugin/` and need an admin session.
+
+## Auto-publish
+
+GitHub Action `.github/workflows/release.yml` patch-bumps and publishes to npm at most once per UTC day when `plugin/`, `lib/`, or `public/` changed. Trusted Publisher (OIDC), workflow filename **must stay** `release.yml`.
+
+The first npm version cannot use OIDC. Publish `0.0.1` once from a logged-in machine, then add the trusted publisher for `htool/signalk-automation-plugin` / `release.yml`.

package/examples/automations.yaml

@@ -0,0 +1,98 @@
+helpers:
+  starlink_manual:
+    type: boolean
+    name: Starlink handmatig
+    default: false
+    on_start: restore
+    latch_on_external_put: electrical.switches.starlink.state
+  charge_hold:
+    type: boolean
+    name: Thuis 60–80% laden
+    default: true
+    on_start: default
+
+zones:
+  home_harbour:
+    name: Thuishaven
+    lat: 52.37
+    lon: 5.22
+    radius: 150
+
+automations:
+  - id: start_anchorwatch
+    alias: Ketting uit → anchorwatch
+    enabled: false
+    trigger:
+      - path: winches.windlass.rode
+        above: 2
+        unit: m
+        for: 10s
+    action:
+      - put: navigation.anchor.watch
+        value: true
+
+  - id: shore_charge
+    alias: Walstroom laadbeleid
+    enabled: false
+    trigger:
+      - path: electrical.chargers.shore.connected
+      - path: electrical.batteries.house.capacity.stateOfCharge
+      - path: navigation.position
+    choose:
+      - alias: onderweg volladen
+        conditions:
+          - path: electrical.chargers.shore.connected
+            is: true
+          - not:
+              zone: home_harbour
+        action:
+          - put: electrical.switches.dolphinCharger.state
+            value: 1
+      - alias: thuis onder 60%
+        conditions:
+          - path: electrical.chargers.shore.connected
+            is: true
+          - zone: home_harbour
+          - path: electrical.batteries.house.capacity.stateOfCharge
+            below: 0.6
+        action:
+          - put: electrical.switches.dolphinCharger.state
+            value: 1
+      - alias: thuis boven 80%
+        conditions:
+          - zone: home_harbour
+          - path: electrical.batteries.house.capacity.stateOfCharge
+            above: 0.8
+        action:
+          - put: electrical.switches.dolphinCharger.state
+            value: 0
+
+  - id: starlink_standby
+    alias: Starlink standby-update
+    enabled: false
+    trigger:
+      - schedule: "0 4 * * *"
+    condition:
+      - helper: starlink_manual
+        is: false
+    action:
+      - put: electrical.switches.starlink.state
+        value: true
+      - delay: 15m
+      - put: electrical.switches.starlink.state
+        value: false
+
+  - id: harbour_via_script
+    alias: Voorbeeld script-conditie
+    enabled: false
+    trigger:
+      - path: electrical.chargers.shore.connected
+        is: true
+    condition:
+      - run: echo.sh
+        equals: home
+    action:
+      - notify:
+          path: electrical.chargers.shore
+          state: normal
+          message: script said home

package/examples/scripts/echo.sh

@@ -0,0 +1,2 @@
+#!/bin/sh
+printf '%s\n' home

package/examples/scripts/fail.sh

@@ -0,0 +1,3 @@
+#!/bin/sh
+printf '%s\n' nope >&2
+exit 1

package/lib/engine.js

@@ -0,0 +1,352 @@
+'use strict'
+
+const { toSi, parseDuration } = require('./units')
+const { inZone } = require('./geo')
+const { runScript } = require('./scripts')
+const { helperPath } = require('./helpers')
+
+function collectPaths (doc) {
+  const paths = new Set()
+  for (const auto of doc.automations || []) {
+    for (const t of auto.trigger || []) addPathsFromClause(paths, t)
+    for (const c of auto.condition || []) addPathsFromClause(paths, c)
+    for (const branch of auto.choose || []) {
+      for (const c of branch.conditions || []) addPathsFromClause(paths, c)
+    }
+    if (auto.latch_on_external_put) paths.add(auto.latch_on_external_put)
+  }
+  for (const def of Object.values(doc.helpers || {})) {
+    if (def.latch_on_external_put) paths.add(def.latch_on_external_put)
+  }
+  return Array.from(paths)
+}
+
+function addPathsFromClause (paths, clause) {
+  if (!clause || typeof clause !== 'object') return
+  if (clause.path) paths.add(clause.path)
+  if (clause.zone || clause.not && clause.not.zone) paths.add('navigation.position')
+  if (clause.helper) paths.add(helperPath(clause.helper))
+  if (clause.not) addPathsFromClause(paths, clause.not)
+  if (Array.isArray(clause.all)) clause.all.forEach((c) => addPathsFromClause(paths, c))
+  if (Array.isArray(clause.any)) clause.any.forEach((c) => addPathsFromClause(paths, c))
+}
+
+function getByPath (values, p) {
+  if (Object.prototype.hasOwnProperty.call(values, p)) return values[p]
+  return undefined
+}
+
+function compareNumber (actual, op, expected, unit) {
+  const a = Number(actual)
+  const b = toSi(expected, unit)
+  if (!Number.isFinite(a) || !Number.isFinite(b)) return false
+  if (op === 'above' || op === 'gt') return a > b
+  if (op === 'below' || op === 'lt') return a < b
+  if (op === 'gte') return a >= b
+  if (op === 'lte') return a <= b
+  return a === b
+}
+
+function evalClause (clause, ctx) {
+  if (!clause || typeof clause !== 'object') {
+    return { pass: false, error: 'empty clause', actual: null }
+  }
+  if (clause.not) {
+    const inner = evalClause(clause.not, ctx)
+    return {
+      pass: inner.error ? false : !inner.pass,
+      error: inner.error,
+      actual: inner.actual,
+      clause: { not: true }
+    }
+  }
+  if (Array.isArray(clause.all)) {
+    const parts = clause.all.map((c) => evalClause(c, ctx))
+    return {
+      pass: parts.every((p) => p.pass),
+      error: parts.find((p) => p.error)?.error || null,
+      actual: parts,
+      clause: { all: true }
+    }
+  }
+  if (Array.isArray(clause.any)) {
+    const parts = clause.any.map((c) => evalClause(c, ctx))
+    return {
+      pass: parts.some((p) => p.pass),
+      error: parts.find((p) => p.error)?.error || null,
+      actual: parts,
+      clause: { any: true }
+    }
+  }
+  if (clause.zone) {
+    const pos = getByPath(ctx.values, 'navigation.position')
+    const zone = ctx.zones[clause.zone]
+    const pass = zone ? inZone(pos, zone) : false
+    return {
+      pass,
+      error: zone ? null : 'Unknown zone: ' + clause.zone,
+      actual: pos,
+      path: 'navigation.position',
+      expected: clause.zone
+    }
+  }
+  if (clause.run) {
+    return {
+      async: true,
+      run: typeof clause.run === 'string' ? { file: clause.run } : clause.run,
+      equals: clause.equals,
+      is: clause.is
+    }
+  }
+  if (clause.schedule) {
+    const when = ctx.now ? new Date(ctx.now) : new Date()
+    const fromTick = ctx.trigger && ctx.trigger.schedule
+    const pass = fromTick ? cronMatch(clause.schedule, when) : false
+    return {
+      pass,
+      error: null,
+      actual: clause.schedule,
+      expected: fromTick ? ctx.trigger.schedule : 'schedule tick'
+    }
+  }
+  const path = clause.helper ? helperPath(clause.helper) : clause.path
+  if (!path) {
+    return { pass: false, error: 'clause needs path, helper, zone, or run', actual: null }
+  }
+  const actual = getByPath(ctx.values, path)
+  let pass = false
+  if (Object.prototype.hasOwnProperty.call(clause, 'is')) {
+    pass = actual === clause.is
+  } else if (Object.prototype.hasOwnProperty.call(clause, 'equals')) {
+    pass = actual === clause.equals || String(actual) === String(clause.equals)
+  } else if (Object.prototype.hasOwnProperty.call(clause, 'above')) {
+    pass = compareNumber(actual, 'above', clause.above, clause.unit)
+  } else if (Object.prototype.hasOwnProperty.call(clause, 'below')) {
+    pass = compareNumber(actual, 'below', clause.below, clause.unit)
+  } else if (Object.prototype.hasOwnProperty.call(clause, 'to')) {
+    pass = actual === clause.to
+  } else {
+    pass = actual !== undefined
+  }
+  return { pass, error: null, actual, path, expected: expectedOf(clause) }
+}
+
+function expectedOf (clause) {
+  if (clause.is !== undefined) return clause.is
+  if (clause.equals !== undefined) return clause.equals
+  if (clause.above !== undefined) return { above: clause.above, unit: clause.unit }
+  if (clause.below !== undefined) return { below: clause.below, unit: clause.unit }
+  if (clause.to !== undefined) return clause.to
+  return true
+}
+
+async function evalClauseAsync (clause, ctx) {
+  const first = evalClause(clause, ctx)
+  if (!first.async) return first
+  const ran = await ctx.runScript(first.run)
+  if (!ran.ok) {
+    return {
+      pass: false,
+      error: ran.error,
+      actual: ran.stdout,
+      run: first.run.file || first.run
+    }
+  }
+  let pass = true
+  if (first.equals !== undefined) pass = ran.value === first.equals || String(ran.value) === String(first.equals)
+  else if (first.is !== undefined) pass = ran.value === first.is
+  else pass = Boolean(ran.value)
+  return {
+    pass,
+    error: null,
+    actual: ran.value,
+    run: first.run.file || first.run
+  }
+}
+
+async function evalList (list, ctx) {
+  const results = []
+  for (const clause of list || []) {
+    const r = await evalClauseAsync(clause, ctx)
+    results.push(r)
+    if (!r.pass) return { pass: false, results }
+  }
+  return { pass: true, results }
+}
+
+function triggerMatchesPath (auto, changedPath) {
+  if (!changedPath) return true
+  const paths = new Set()
+  for (const t of auto.trigger || []) addPathsFromClause(paths, t)
+  const hasSchedule = (auto.trigger || []).some((t) => t.schedule)
+  if (paths.size === 0) return !hasSchedule
+  return paths.has(changedPath)
+}
+
+function cronMatch (expr, date) {
+  if (!expr) return false
+  const parts = String(expr).trim().split(/\s+/)
+  if (parts.length < 5) return false
+  const [min, hour, dom, mon, dow] = parts
+  return (
+    fieldMatch(min, date.getMinutes()) &&
+    fieldMatch(hour, date.getHours()) &&
+    fieldMatch(dom, date.getDate()) &&
+    fieldMatch(mon, date.getMonth() + 1) &&
+    fieldMatch(dow, date.getDay())
+  )
+}
+
+function fieldMatch (field, value) {
+  if (field === '*') return true
+  return String(field)
+    .split(',')
+    .some((bit) => {
+      if (bit.includes('/')) {
+        const [range, step] = bit.split('/')
+        const st = Number(step)
+        if (!Number.isFinite(st) || st <= 0) return false
+        if (range === '*') return value % st === 0
+      }
+      if (bit.includes('-')) {
+        const [a, b] = bit.split('-').map(Number)
+        return value >= a && value <= b
+      }
+      return Number(bit) === value
+    })
+}
+
+async function evaluateAutomation (auto, ctx) {
+  const record = {
+    ts: new Date(ctx.now || Date.now()).toISOString(),
+    id: auto.id,
+    result: 'skipped',
+    trigger: ctx.trigger || null,
+    conditions: [],
+    choose: null,
+    actions: []
+  }
+  if (!ctx.enabled) {
+    record.reason = 'disabled'
+    return record
+  }
+
+  const trig = await evalList(auto.trigger || [], ctx)
+  record.triggerResults = trig.results
+  if ((auto.trigger || []).length && !trig.pass) {
+    record.reason = 'trigger not matched'
+    return record
+  }
+
+  const cond = await evalList(auto.condition || [], ctx)
+  record.conditions = cond.results
+  if ((auto.condition || []).length && !cond.pass) {
+    const failed = cond.results.find((r) => r.error)
+    record.result = failed ? 'failure' : 'skipped'
+    record.reason = failed ? failed.error : 'condition not met'
+    return record
+  }
+
+  let actions = auto.action || []
+  if (auto.choose && auto.choose.length) {
+    let picked = null
+    for (const branch of auto.choose) {
+      const br = await evalList(branch.conditions || [], ctx)
+      if (br.pass) {
+        picked = branch
+        record.choose = branch.id || branch.alias || 'branch'
+        actions = branch.action || []
+        break
+      }
+    }
+    if (!picked) {
+      record.reason = 'no matching choose branch'
+      return record
+    }
+  }
+
+  for (const action of actions) {
+    const ran = await runAction(action, ctx)
+    record.actions.push(ran)
+    if (!ran.ok) {
+      record.result = 'failure'
+      record.reason = ran.error
+      return record
+    }
+  }
+  record.result = 'ok'
+  return record
+}
+
+async function runAction (action, ctx) {
+  if (!action || typeof action !== 'object') {
+    return { ok: false, error: 'empty action' }
+  }
+  if (action.put) {
+    try {
+      await ctx.put(action.put, action.value)
+      return { ok: true, type: 'put', path: action.put, value: action.value }
+    } catch (err) {
+      return { ok: false, type: 'put', path: action.put, error: err.message }
+    }
+  }
+  if (action.helper) {
+    try {
+      ctx.setHelper(action.helper, action.value)
+      return { ok: true, type: 'helper', helper: action.helper, value: action.value }
+    } catch (err) {
+      return { ok: false, type: 'helper', helper: action.helper, error: err.message }
+    }
+  }
+  if (action.notify) {
+    const n = action.notify
+    try {
+      await ctx.notify(n.path, n.state || 'alert', n.message || '')
+      return { ok: true, type: 'notify', path: n.path, state: n.state }
+    } catch (err) {
+      return { ok: false, type: 'notify', error: err.message }
+    }
+  }
+  if (action.delay != null) {
+    const ms = parseDuration(action.delay)
+    await ctx.sleep(ms)
+    return { ok: true, type: 'delay', ms }
+  }
+  if (action.run) {
+    const spec = typeof action.run === 'string' ? { file: action.run } : action.run
+    const ran = await ctx.runScript(spec)
+    if (!ran.ok) {
+      return { ok: false, type: 'run', file: spec.file, error: ran.error, stdout: ran.stdout }
+    }
+    if (action.as) {
+      ctx.setHelper(action.as, ran.value)
+    }
+    return { ok: true, type: 'run', file: spec.file, value: ran.value, stdout: ran.stdout }
+  }
+  return { ok: false, error: 'unknown action' }
+}
+
+function makeRunScript (opts) {
+  return function (spec) {
+    return runScript({
+      scriptsDir: opts.scriptsDir,
+      file: spec.file,
+      args: spec.args,
+      timeoutMs: opts.timeoutMs,
+      env: spec.env
+    })
+  }
+}
+
+module.exports = {
+  collectPaths,
+  evalClause,
+  evalClauseAsync,
+  evalList,
+  evaluateAutomation,
+  triggerMatchesPath,
+  cronMatch,
+  runAction,
+  makeRunScript,
+  parseDuration
+}

package/lib/geo.js

@@ -0,0 +1,32 @@
+'use strict'
+
+const EARTH_M = 6371000
+
+function haversineM (a, b) {
+  const lat1 = toRad(a.lat)
+  const lat2 = toRad(b.lat)
+  const dLat = toRad(b.lat - a.lat)
+  const dLon = toRad(b.lon - a.lon)
+  const h =
+    Math.sin(dLat / 2) ** 2 +
+    Math.cos(lat1) * Math.cos(lat2) * Math.sin(dLon / 2) ** 2
+  return 2 * EARTH_M * Math.asin(Math.min(1, Math.sqrt(h)))
+}
+
+function inZone (position, zone) {
+  if (!position || !zone) return false
+  if (!Number.isFinite(position.latitude) || !Number.isFinite(position.longitude)) {
+    return false
+  }
+  const d = haversineM(
+    { lat: position.latitude, lon: position.longitude },
+    { lat: zone.lat, lon: zone.lon }
+  )
+  return d <= Number(zone.radius)
+}
+
+function toRad (deg) {
+  return (Number(deg) * Math.PI) / 180
+}
+
+module.exports = { haversineM, inZone }

package/lib/git.js

@@ -0,0 +1,112 @@
+'use strict'
+
+const fs = require('fs')
+const path = require('path')
+const { spawnSync } = require('child_process')
+
+function runGit (args, cwd) {
+  const r = spawnSync('git', args, { cwd, encoding: 'utf8' })
+  if (r.status !== 0) {
+    const err = (r.stderr || r.stdout || '').trim()
+    throw new Error('git ' + args.join(' ') + ' failed: ' + err)
+  }
+  return (r.stdout || '').trim()
+}
+
+function isGitRepo (dir) {
+  if (!dir || !fs.existsSync(dir)) return false
+  try {
+    runGit(['rev-parse', '--is-inside-work-tree'], dir)
+    return true
+  } catch (_) {
+    return false
+  }
+}
+
+function listCommits (dir, limit) {
+  if (!isGitRepo(dir)) return []
+  const n = limit > 0 ? limit : 30
+  const out = runGit(
+    ['log', '-n', String(n), '--pretty=format:%H%x09%cI%x09%s'],
+    dir
+  )
+  if (!out) return []
+  return out.split('\n').map((line) => {
+    const [sha, date, ...rest] = line.split('\t')
+    return { sha, date, subject: rest.join('\t') }
+  })
+}
+
+function currentSha (dir) {
+  if (!isGitRepo(dir)) return null
+  try {
+    return runGit(['rev-parse', 'HEAD'], dir)
+  } catch (_) {
+    return null
+  }
+}
+
+function archiveTreeish (repoDir, sha) {
+  const root = path.resolve(runGit(['rev-parse', '--show-toplevel'], repoDir))
+  const dir = path.resolve(repoDir)
+  const rel = path.relative(root, dir).replace(/\\/g, '/')
+  if (!rel || rel === '.') return sha
+  if (rel.startsWith('..') || path.isAbsolute(rel)) {
+    throw new Error('automationsDir is outside the git repository')
+  }
+  return sha + ':' + rel
+}
+
+function materializeCommit (repoDir, sha, destDir) {
+  if (!sha) throw new Error('Commit sha is required')
+  if (!isGitRepo(repoDir)) throw new Error('automationsDir is not a git repository')
+  runGit(['cat-file', '-t', sha], repoDir)
+  const treeish = archiveTreeish(repoDir, sha)
+  const root = path.resolve(runGit(['rev-parse', '--show-toplevel'], repoDir))
+  const parent = path.dirname(path.resolve(destDir))
+  fs.mkdirSync(parent, { recursive: true })
+  const tmp = fs.mkdtempSync(path.join(parent, 'live-tmp-'))
+  try {
+    const archive = spawnSync('git', ['archive', '--format=tar', treeish], {
+      cwd: root,
+      encoding: 'buffer',
+      maxBuffer: 20 * 1024 * 1024
+    })
+    if (archive.status !== 0) {
+      throw new Error(
+        'git archive failed: ' + String(archive.stderr || archive.stdout || '')
+      )
+    }
+    const tar = spawnSync('tar', ['-x', '-C', tmp], {
+      input: archive.stdout,
+      encoding: 'buffer'
+    })
+    if (tar.status !== 0) {
+      throw new Error('tar extract failed: ' + String(tar.stderr || ''))
+    }
+    const bak = destDir + '.bak'
+    if (fs.existsSync(bak)) fs.rmSync(bak, { recursive: true, force: true })
+    if (fs.existsSync(destDir)) fs.renameSync(destDir, bak)
+    try {
+      fs.renameSync(tmp, destDir)
+      if (fs.existsSync(bak)) fs.rmSync(bak, { recursive: true, force: true })
+    } catch (err) {
+      if (fs.existsSync(bak) && !fs.existsSync(destDir)) {
+        fs.renameSync(bak, destDir)
+      }
+      throw err
+    }
+  } finally {
+    if (fs.existsSync(tmp)) fs.rmSync(tmp, { recursive: true, force: true })
+  }
+  return destDir
+}
+
+module.exports = {
+  runGit,
+  isGitRepo,
+  listCommits,
+  currentSha,
+  archiveTreeish,
+  materializeCommit
+}