signalk-automation-plugin 0.0.1

package/lib/helpers.js

@@ -0,0 +1,60 @@
+'use strict'
+
+function coerce (def, value) {
+  if (!def) return value
+  if (def.type === 'boolean') {
+    if (value === true || value === 'true' || value === 1 || value === '1') return true
+    if (value === false || value === 'false' || value === 0 || value === '0') return false
+    return Boolean(value)
+  }
+  if (def.type === 'number') {
+    const n = Number(value)
+    if (!Number.isFinite(n)) throw new Error('Helper ' + def.id + ' expects a number')
+    return n
+  }
+  const s = value == null ? '' : String(value)
+  if (def.type === 'select' && def.options.length && !def.options.includes(s)) {
+    throw new Error('Helper ' + def.id + ' value not in options')
+  }
+  return s
+}
+
+function initHelpers (defs, persisted) {
+  const values = {}
+  const saved = persisted && typeof persisted === 'object' ? persisted : {}
+  for (const [id, def] of Object.entries(defs || {})) {
+    const mode = def.on_start || 'none'
+    if (mode === 'restore') {
+      if (Object.prototype.hasOwnProperty.call(saved, id)) {
+        values[id] = coerce(def, saved[id])
+      } else if (def.default !== undefined) {
+        values[id] = coerce(def, def.default)
+      }
+    } else if (mode === 'default') {
+      if (def.default !== undefined) values[id] = coerce(def, def.default)
+    }
+    // none: leave unset
+  }
+  return values
+}
+
+function persistableHelpers (defs, values) {
+  const out = {}
+  for (const [id, def] of Object.entries(defs || {})) {
+    if (def.on_start !== 'restore') continue
+    if (!Object.prototype.hasOwnProperty.call(values, id)) continue
+    out[id] = values[id]
+  }
+  return out
+}
+
+function helperPath (id) {
+  return 'automations.helpers.' + id
+}
+
+module.exports = {
+  coerce,
+  initHelpers,
+  persistableHelpers,
+  helperPath
+}

package/lib/runtime.js

@@ -0,0 +1,270 @@
+'use strict'
+
+const fs = require('fs')
+const path = require('path')
+const yaml = require('./yaml')
+const helpers = require('./helpers')
+const store = require('./store')
+const git = require('./git')
+const engine = require('./engine')
+
+class Runtime {
+  constructor (opts) {
+    this.app = opts.app
+    this.pluginId = opts.pluginId
+    this.dataDir = opts.dataDir
+    this.automationsDir = opts.automationsDir
+    this.scriptsDir = opts.scriptsDir
+    this.traceCount = opts.traceCount || 20
+    this.scriptTimeoutMs = (opts.scriptTimeoutSeconds || 30) * 1000
+    this.now = opts.now || (() => Date.now())
+    this.sleep = opts.sleep || ((ms) => new Promise((r) => setTimeout(r, ms)))
+    this.putFn = opts.put
+    this.notifyFn = opts.notify
+    this.log = opts.log || { debug () {}, error () {} }
+
+    this.doc = yaml.emptyDoc()
+    this.state = store.emptyState()
+    this.values = {}
+    this.helperValues = {}
+    this.lastTruthy = {}
+    this.pendingSince = {}
+    this.lastDebounce = {}
+    this.lastCronMinute = ''
+    this.unsubscribes = []
+  }
+
+  load () {
+    this.state = store.loadState(this.dataDir)
+    const live = store.liveDir(this.dataDir)
+    const from = fs.existsSync(live) ? live : this.automationsDir
+    this.doc = yaml.loadYamlDir(from)
+    this.helperValues = helpers.initHelpers(this.doc.helpers, this.state.helpers)
+    this.persistHelpers()
+    for (const [id, value] of Object.entries(this.helperValues)) {
+      this.values[helpers.helperPath(id)] = value
+    }
+  }
+
+  persistHelpers () {
+    this.state.helpers = helpers.persistableHelpers(this.doc.helpers, this.helperValues)
+    store.saveState(this.dataDir, this.state)
+  }
+
+  isEnabled (auto) {
+    if (Object.prototype.hasOwnProperty.call(this.state.enabled, auto.id)) {
+      return !!this.state.enabled[auto.id]
+    }
+    return auto.enabled !== false
+  }
+
+  setEnabled (id, enabled) {
+    this.state.enabled[id] = !!enabled
+    store.saveState(this.dataDir, this.state)
+  }
+
+  setHelper (id, value) {
+    const def = this.doc.helpers[id]
+    if (!def) throw new Error('Unknown helper: ' + id)
+    const coerced = helpers.coerce(def, value)
+    this.helperValues[id] = coerced
+    this.values[helpers.helperPath(id)] = coerced
+    this.persistHelpers()
+    return coerced
+  }
+
+  resetHelper (id) {
+    const def = this.doc.helpers[id]
+    if (!def) throw new Error('Unknown helper: ' + id)
+    if (def.default === undefined) {
+      delete this.helperValues[id]
+      delete this.values[helpers.helperPath(id)]
+    } else {
+      this.helperValues[id] = helpers.coerce(def, def.default)
+      this.values[helpers.helperPath(id)] = this.helperValues[id]
+    }
+    this.persistHelpers()
+    return this.helperValues[id]
+  }
+
+  setPathValue (p, value, meta) {
+    this.values[p] = value
+    if (meta && meta.$source) {
+      this.values[p + '.$source'] = meta.$source
+    }
+  }
+
+  async handlePathChange (p, value, source) {
+    this.setPathValue(p, value, { $source: source })
+    this.applyLatches(p, source)
+    for (const auto of this.doc.automations) {
+      if (!engine.triggerMatchesPath(auto, p)) continue
+      await this.maybeRun(auto, { path: p, value })
+    }
+  }
+
+  applyLatches (p, source) {
+    const fromSelf = source && String(source).includes(this.pluginId)
+    if (fromSelf) return
+    for (const def of Object.values(this.doc.helpers)) {
+      if (def.latch_on_external_put === p && def.type === 'boolean') {
+        if (this.values[p]) this.setHelper(def.id, true)
+      }
+    }
+  }
+
+  async tickSchedule (date) {
+    const d = date || new Date(this.now())
+    const key = d.getFullYear() + '-' + d.getMonth() + '-' + d.getDate() + '-' + d.getHours() + '-' + d.getMinutes()
+    if (key === this.lastCronMinute) return
+    this.lastCronMinute = key
+    for (const auto of this.doc.automations) {
+      const schedules = (auto.trigger || []).filter((t) => t.schedule)
+      if (!schedules.length) continue
+      const hit = schedules.some((t) => engine.cronMatch(t.schedule, d))
+      if (hit) await this.maybeRun(auto, { schedule: schedules[0].schedule })
+    }
+  }
+
+  async maybeRun (auto, trigger) {
+    if (!this.isEnabled(auto)) return
+    const ctx = this.makeCtx(trigger)
+    const trig = await engine.evalList(auto.trigger || [], ctx)
+    const matched = !(auto.trigger || []).length || trig.pass
+
+    if (!matched) {
+      this.lastTruthy[auto.id] = false
+      delete this.pendingSince[auto.id]
+      return
+    }
+
+    const hold = holdMs(auto)
+    if (hold > 0) {
+      if (!this.pendingSince[auto.id]) this.pendingSince[auto.id] = this.now()
+      if (this.now() - this.pendingSince[auto.id] < hold) return
+    }
+
+    const prev = !!this.lastTruthy[auto.id]
+    const edge = auto.edge || 'rising'
+    if (edge === 'rising' && prev) return
+    if (edge === 'falling') return
+    this.lastTruthy[auto.id] = true
+
+    if (auto.debounceMs && this.lastDebounce[auto.id] && this.now() - this.lastDebounce[auto.id] < auto.debounceMs) {
+      return
+    }
+
+    this.lastDebounce[auto.id] = this.now()
+    const record = await engine.evaluateAutomation(auto, this.makeCtx(trigger))
+    this.state.lastRun[auto.id] = {
+      ts: record.ts,
+      result: record.result,
+      reason: record.reason || null
+    }
+    store.saveState(this.dataDir, this.state)
+    store.appendTrace(this.dataDir, auto.id, record, this.traceCount)
+    return record
+  }
+
+  makeCtx (trigger) {
+    return {
+      values: this.values,
+      zones: this.doc.zones,
+      enabled: true,
+      trigger,
+      now: this.now(),
+      put: (p, value) => this.put(p, value),
+      notify: (p, state, message) => this.notify(p, state, message),
+      setHelper: (id, value) => this.setHelper(id, value),
+      sleep: this.sleep,
+      runScript: engine.makeRunScript({
+        scriptsDir: this.scriptsDir,
+        timeoutMs: this.scriptTimeoutMs
+      })
+    }
+  }
+
+  async put (p, value) {
+    this.values[p] = value
+    if (this.putFn) return this.putFn(p, value)
+  }
+
+  async notify (p, state, message) {
+    if (this.notifyFn) return this.notifyFn(p, state, message)
+  }
+
+  snapshot () {
+    return {
+      started: true,
+      activeSha: this.state.activeSha,
+      automationsDir: this.automationsDir || null,
+      errors: this.doc.errors,
+      files: this.doc.files,
+      yaml: yaml.combinedYaml(this.doc),
+      helpers: Object.values(this.doc.helpers).map((def) => ({
+        id: def.id,
+        name: def.name,
+        type: def.type,
+        on_start: def.on_start,
+        default: def.default,
+        options: def.options,
+        value: Object.prototype.hasOwnProperty.call(this.helperValues, def.id)
+          ? this.helperValues[def.id]
+          : null,
+        set: Object.prototype.hasOwnProperty.call(this.helperValues, def.id)
+      })),
+      automations: this.doc.automations.map((auto) => ({
+        id: auto.id,
+        alias: auto.alias,
+        enabled: this.isEnabled(auto),
+        yamlEnabled: auto.enabled !== false,
+        lastRun: this.state.lastRun[auto.id] || null
+      })),
+      zones: Object.values(this.doc.zones),
+      commits: git.isGitRepo(this.automationsDir)
+        ? git.listCommits(this.automationsDir, 40)
+        : []
+    }
+  }
+
+  traces (id) {
+    return store.loadTraces(this.dataDir, id)
+  }
+
+  activateCommit (sha) {
+    const dest = store.liveDir(this.dataDir)
+    const incoming = dest + '.incoming'
+    if (fs.existsSync(incoming)) fs.rmSync(incoming, { recursive: true, force: true })
+    git.materializeCommit(this.automationsDir, sha, incoming)
+    const next = yaml.loadYamlDir(incoming)
+    if (next.errors.length) {
+      fs.rmSync(incoming, { recursive: true, force: true })
+      const err = next.errors.map((e) => e.file + ': ' + e.message).join('; ')
+      throw new Error('YAML invalid, live not changed: ' + err)
+    }
+    const bak = dest + '.bak'
+    if (fs.existsSync(bak)) fs.rmSync(bak, { recursive: true, force: true })
+    if (fs.existsSync(dest)) fs.renameSync(dest, bak)
+    fs.renameSync(incoming, dest)
+    if (fs.existsSync(bak)) fs.rmSync(bak, { recursive: true, force: true })
+    this.state.activeSha = sha
+    store.saveState(this.dataDir, this.state)
+    this.load()
+    return this.snapshot()
+  }
+}
+
+function holdMs (auto) {
+  for (const t of auto.trigger || []) {
+    if (t.for) {
+      try {
+        return engine.parseDuration(t.for)
+      } catch (_) {
+        return 0
+      }
+    }
+  }
+  return 0
+}
+
+module.exports = { Runtime }

package/lib/scripts.js

@@ -0,0 +1,120 @@
+'use strict'
+
+const fs = require('fs')
+const path = require('path')
+const { execFile } = require('child_process')
+
+function resolveScript (scriptsDir, file) {
+  if (!scriptsDir) {
+    throw new Error('scriptsDir is not configured')
+  }
+  if (!file || typeof file !== 'string') {
+    throw new Error('Script file is required')
+  }
+  if (path.isAbsolute(file)) {
+    throw new Error('Script path must be relative to scriptsDir')
+  }
+  const root = path.resolve(scriptsDir)
+  const resolved = path.resolve(root, file)
+  const rel = path.relative(root, resolved)
+  if (rel.startsWith('..') || path.isAbsolute(rel)) {
+    throw new Error('Script path escapes scriptsDir')
+  }
+  if (!fs.existsSync(resolved)) {
+    throw new Error('Script not found: ' + file)
+  }
+  return resolved
+}
+
+function interpreterFor (scriptPath) {
+  const ext = path.extname(scriptPath).toLowerCase()
+  if (ext === '.py') return { cmd: 'python3', args: [scriptPath] }
+  if (ext === '.sh') return { cmd: 'bash', args: [scriptPath] }
+  return { cmd: scriptPath, args: [] }
+}
+
+function parseOutput (stdout) {
+  const text = String(stdout || '').trim()
+  if (!text) return { stdout: '', value: '' }
+  if (
+    (text.startsWith('{') && text.endsWith('}')) ||
+    (text.startsWith('[') && text.endsWith(']'))
+  ) {
+    try {
+      return { stdout: text, value: JSON.parse(text) }
+    } catch (_) {
+      /* fall through */
+    }
+  }
+  if (text === 'true') return { stdout: text, value: true }
+  if (text === 'false') return { stdout: text, value: false }
+  const n = Number(text)
+  if (text !== '' && Number.isFinite(n)) return { stdout: text, value: n }
+  return { stdout: text, value: text }
+}
+
+function runScript (opts) {
+  const scriptsDir = opts.scriptsDir
+  const file = opts.file
+  const extraArgs = Array.isArray(opts.args) ? opts.args.map(String) : []
+  const timeout = opts.timeoutMs || 30000
+  const env = Object.assign({}, process.env, opts.env || {})
+  const exec = opts.execFile || execFile
+
+  let resolved
+  try {
+    resolved = resolveScript(scriptsDir, file)
+  } catch (err) {
+    return Promise.resolve({
+      ok: false,
+      error: err.message,
+      stdout: '',
+      stderr: '',
+      value: null
+    })
+  }
+
+  const interp = interpreterFor(resolved)
+  const args = interp.args.concat(extraArgs)
+
+  return new Promise((resolve) => {
+    exec(
+      interp.cmd,
+      args,
+      { cwd: path.resolve(scriptsDir), timeout, env, maxBuffer: 1024 * 1024 },
+      (err, stdout, stderr) => {
+        const errText = String(stderr || '').trim()
+        if (errText) {
+          resolve({
+            ok: false,
+            error: 'stderr: ' + errText,
+            stdout: String(stdout || ''),
+            stderr: errText,
+            value: null
+          })
+          return
+        }
+        if (err) {
+          resolve({
+            ok: false,
+            error: err.killed ? 'Script timed out' : err.message,
+            stdout: String(stdout || ''),
+            stderr: errText,
+            value: null
+          })
+          return
+        }
+        const parsed = parseOutput(stdout)
+        resolve({
+          ok: true,
+          error: null,
+          stdout: parsed.stdout,
+          stderr: '',
+          value: parsed.value
+        })
+      }
+    )
+  })
+}
+
+module.exports = { resolveScript, interpreterFor, parseOutput, runScript }

package/lib/store.js

@@ -0,0 +1,75 @@
+'use strict'
+
+const fs = require('fs')
+const path = require('path')
+
+function emptyState () {
+  return {
+    helpers: {},
+    enabled: {},
+    activeSha: null,
+    lastRun: {}
+  }
+}
+
+function loadState (dir) {
+  const file = path.join(dir, 'state.json')
+  try {
+    const raw = JSON.parse(fs.readFileSync(file, 'utf8'))
+    return Object.assign(emptyState(), raw)
+  } catch (_) {
+    return emptyState()
+  }
+}
+
+function saveState (dir, state) {
+  fs.mkdirSync(dir, { recursive: true })
+  const tmp = path.join(dir, 'state.json.tmp')
+  const file = path.join(dir, 'state.json')
+  fs.writeFileSync(tmp, JSON.stringify(state, null, 2) + '\n')
+  fs.renameSync(tmp, file)
+}
+
+function tracesPath (dir, id) {
+  return path.join(dir, 'traces', safeId(id) + '.json')
+}
+
+function loadTraces (dir, id) {
+  try {
+    const data = JSON.parse(fs.readFileSync(tracesPath(dir, id), 'utf8'))
+    return Array.isArray(data) ? data : []
+  } catch (_) {
+    return []
+  }
+}
+
+function appendTrace (dir, id, record, max) {
+  const cap = max > 0 ? max : 20
+  const list = loadTraces(dir, id)
+  list.unshift(record)
+  while (list.length > cap) list.pop()
+  const folder = path.join(dir, 'traces')
+  fs.mkdirSync(folder, { recursive: true })
+  const tmp = tracesPath(dir, id) + '.tmp'
+  fs.writeFileSync(tmp, JSON.stringify(list, null, 2) + '\n')
+  fs.renameSync(tmp, tracesPath(dir, id))
+  return list
+}
+
+function liveDir (dir) {
+  return path.join(dir, 'live')
+}
+
+function safeId (id) {
+  return String(id || 'unknown').replace(/[^A-Za-z0-9._-]+/g, '_')
+}
+
+module.exports = {
+  emptyState,
+  loadState,
+  saveState,
+  loadTraces,
+  appendTrace,
+  liveDir,
+  tracesPath
+}

package/lib/units.js

@@ -0,0 +1,40 @@
+'use strict'
+
+const TO_SI = {
+  m: 1,
+  km: 1000,
+  nm: 1852,
+  kn: 0.514444,
+  kt: 0.514444,
+  '%': 0.01,
+  percent: 0.01,
+  s: 1,
+  min: 60,
+  h: 3600
+}
+
+function toSi (value, unit) {
+  if (unit == null || unit === '') return value
+  const key = String(unit).trim()
+  const factor = TO_SI[key] != null ? TO_SI[key] : TO_SI[key.toLowerCase()]
+  if (factor == null) {
+    throw new Error('Unknown unit: ' + unit)
+  }
+  return Number(value) * factor
+}
+
+function parseDuration (raw) {
+  if (raw == null) return 0
+  if (typeof raw === 'number' && Number.isFinite(raw)) return raw
+  const s = String(raw).trim()
+  const m = s.match(/^(\d+(?:\.\d+)?)(ms|s|m|h)?$/i)
+  if (!m) throw new Error('Invalid duration: ' + raw)
+  const n = Number(m[1])
+  const unit = (m[2] || 'ms').toLowerCase()
+  if (unit === 'ms') return n
+  if (unit === 's') return n * 1000
+  if (unit === 'm') return n * 60 * 1000
+  return n * 60 * 60 * 1000
+}
+
+module.exports = { toSi, parseDuration }