everlights 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 5470906a45eb2946bbf14cdba11dc89917ad92244e2b224f655513ff944ee66a
+  data.tar.gz: 1c6f03b3cfa021d8c16692fb555d39a15416c54a82cda3058fe15faae585049b
+SHA512:
+  metadata.gz: ef7f03a9d96aa9fbf041cc566bc4e14c7960a9c070630a5633353f55a4acb111aad1092e17abe928673f4225a21c50b75eb0a5195113f30f8d39291b1cbc58c4
+  data.tar.gz: 815c442cc1d22a33676bec89a25578b70463c10be529ce77e3699c1c355db5b11a567f2ebca9b76a092bae68b65fbd5b23deee80bfa25b087cdb7f79706209ee

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ricky Chilcott
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,172 @@
+# everlights
+
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="assets/everlights-dark.png">
+    <img src="assets/everlights-light.png" alt="EverLights" width="300">
+  </picture>
+</p>
+
+A Ruby client and CLI for the EverLights v3 Smart Lights Bridge. It talks to the bridge directly on your local network: no cloud, no account, and no dependencies outside Ruby's standard library.
+
+Use it to show colors now, manage saved sequences, and put shows on the calendar weeks or months ahead. The bridge stores scheduled shows itself, so they run with no computer on.
+
+> Unofficial. Not affiliated with or endorsed by EverLights. The EverLights name and logo belong to their owner.
+
+## Install
+
+```sh
+gem install everlights
+export EVERLIGHTS_HOST=192.168.1.50   # your bridge's IP (EverLights app → device information)
+```
+
+Requires Ruby 3.1+.
+
+## CLI
+
+```sh
+everlights bridge                                  # firmware, network, cloud, zone health
+everlights show                                    # what's playing, e.g. "Halloween Fade (Halloween show)"
+
+everlights play "Hallows Eve"                      # a saved sequence, now
+everlights set FF0000 00FF00 --effect twinkle=100  # ad-hoc colors, now
+everlights off                                     # lights dark
+everlights clear                                   # hand control back to the calendar
+
+everlights sequence list fall                      # * marks sequences you created
+everlights sequence add "Candy Cane" FF0000 FFFFFF --effect chase=60
+everlights sequence update "Candy Cane" FF0000 00FF00 FFFFFF   # replace colors/effects
+everlights sequence remove "Candy Cane"
+
+everlights calendar list --limit 30                # upcoming shows (default 365 days)
+everlights calendar add 2026-12-01 Christmas "Candy Cane:30,Christmas" --until 2027-01-01
+everlights calendar add 2026-12-31 "New Year" "New Year's" --start 20:00 --end 01:00
+everlights calendar remove 2026-12-24 Christmas    # one night
+```
+
+- **Calendar defaults:** a show starts at dusk and ends at 23:00. Each sequence plays for 20 seconds unless you write `name:seconds`.
+- **Times** use your machine's local time zone. An end time earlier than the start means the next morning. `--until` repeats the show nightly and stays correct across DST changes.
+- **Effects:** `bars blink chase fade gradient lightning melt pingPong random reverseChase strobe twinkle wipe`, each with a strength from 0 to 255.
+- **JSON:** add `--json` to list commands and `bridge`.
+- **Now commands** (`set`, `play`, `off`): during a running show they only last until its next sequence change.
+- **Bridge upkeep:** `everlights bridge time [TIME]` sets the clock (default now; the bridge normally syncs via NTP). `everlights bridge reboot --yes` restarts it.
+
+## Sync: your year of shows from one file
+
+Describe your own sequences and a schedule once. `everlights sync` then builds them on the bridge for the months ahead:
+
+```sh
+cp config/everlights.example.yml config/everlights.yml   # gitignored; edit the IP, location and schedule
+everlights sync --dry-run                                # print the plan
+everlights sync                                          # apply it
+```
+
+```yaml
+bridge: {host: 192.168.1.50}
+location: {lat: 40.0, lon: -83.0}   # dusk = sunset, calculated per night
+horizon_days: 120
+sequences:
+  My Birthday: {colors: [FF1E8C, FFC400, 00A8FF], effects: {chase: 60, twinkle: 180}}
+schedule:                           # higher in the list wins a shared night
+  - {name: Christmas Day, on: Dec 25, sequences: [Christmas, "Candy Cane Lane:30"], end: "01:00"}
+  - {name: Christmas Season, from: Dec 1, to: Jan 1, sequences: [Christmas, Winter]}
+  - {name: Thanksgiving, on: 4th Thursday of November, sequences: [Thanksgiving]}
+  - {name: Easter, on: Easter, sequences: [Easter]}
+  - {name: Fall Weekends, every: [Friday, Saturday], from: Sep 15, to: Nov 20, start: dusk+15, sequences: [Fall Wave]}
+```
+
+- **When a rule applies:**
+  - `on:` takes a date (`2027-03-14`), a yearly date (`Dec 25`), `Nth Weekday of Month`, `last Monday of May`, or `Easter`.
+  - `from:`/`to:` repeats nightly, every year, and can cross New Year.
+  - `every:` takes weekdays, optionally limited by `from:`/`to:`.
+- **Times:** `start:` is `dusk`, `dusk+15` or `"18:30"`; `end:` defaults to `"23:00"`. An end earlier than the start means the next morning.
+- **Future only:** sync adds only nights that start more than 15 minutes from now. Each rule becomes one calendar entry, and re-running sync rolls the window forward.
+- **Leaves your app-made shows alone:** sync only changes or deletes what it created, tracked in `config/.sync-state.yml`. It skips nights an app-made show already covers, and refuses names that clash with built-ins or app-made items. If the state file is lost, `--adopt` takes back items whose names match the config.
+- **All or nothing:** every config problem is reported before anything is written.
+- **Config location:** `--config` or `$EVERLIGHTS_CONFIG`. The config's `bridge.host` is used by every command unless `--host` or `$EVERLIGHTS_HOST` is set.
+- **Time zone:** set `timezone:` in the config, or it uses your machine's.
+
+To keep the calendar topped up, run it on a schedule, for example monthly from cron:
+`0 9 1 * * cd ~/everlights && everlights sync >> config/sync.log 2>&1`
+
+## Ruby
+
+```ruby
+require "everlights"
+
+el = Everlights::Client.new("192.168.1.50")    # or ENV["EVERLIGHTS_HOST"]
+
+el.play "Hallows Eve"
+el.set "FF0000", "00FF00", effects: {twinkle: 100}
+el.off
+el.clear
+el.status                      # bridge info hash; el.set_time, el.reboot
+el.now_playing                 # {zone => {name:, show:, off:, pattern:, effects:}}
+
+el.sequences.list("fall")
+el.sequences.add "Candy Cane", "FF0000", "FFFFFF", effects: {chase: 60}
+el.sequences.update "Candy Cane", "FF0000", "00FF00"
+el.sequences.remove "Candy Cane"
+
+el.calendar.list(limit: 30)  # => [{date:, start:, finish:, dusk:, name:, event_id:, sequences: [[name, secs]]}]
+el.calendar.add "2026-12-01", "Christmas", {"Candy Cane" => 30, "Christmas" => 20}, through: "2027-01-01"
+el.calendar.add "2026-12-31", "New Year", ["New Year's"], start: "20:00", finish: "01:00"
+el.calendar.remove "2026-12-24", "Christmas"
+
+config = Everlights::Sync.load_config("config/everlights.yml")
+plan = Everlights::Sync.new(el, config, state_path: "config/.sync-state.yml").plan
+puts plan
+plan.apply!
+```
+
+`Client` also exposes the raw endpoints: `status`, `zones`, `program`, `set_program`, `sequence_list`, `create_event`, `update_event` and so on.
+
+## AI agent skill
+
+`skills/everlights/SKILL.md` teaches an AI agent, such as Claude Code, to drive the CLI: what to check first, confirming before any change to the lights, and recipes. To install it:
+
+```sh
+ln -s "$(pwd)/skills/everlights" ~/.claude/skills/everlights
+```
+
+## Protocol
+
+The bridge (an ESP32) serves plain JSON over HTTP on port 80, with no authentication:
+
+| Endpoint | |
+|---|---|
+| `GET /v1` | bridge status, including zones |
+| `GET /v1/zones` | zones (pixel runs) |
+| `GET POST DELETE /v1/zones/{serial}/sequence` | what a zone shows right now |
+| `GET POST /v1/sequences`, `PUT DELETE /v1/sequences/{id}` | saved sequences |
+| `GET POST /v1/events`, `PUT DELETE /v1/events/{id}` | calendar |
+| `PUT /v1/time`, `GET /v1/reboot` | clock; reboot (note: a GET) |
+
+Verified against bridge firmware B4042, radio R3052 and zone firmware N3063. Firmware updates arrive over the air from EverLights' cloud; there is no local update endpoint.
+
+Not yet confirmed:
+- What each effect's 0–255 value does.
+- How the bridge handles overlapping calendar entries.
+- **Dusk:** the bridge stores the 17:00 placeholder start as given; the EverLights app writes the actual dusk time. It's unclear whether the bridge honors `StartAtDusk` on its own, so a "dusk" show may start at 17:00.
+
+Observed on the bridge (`ruby -Ilib test/live_check.rb` repeats the round trip):
+- Sequence durations are seconds.
+- Sequences you add are filed in the app's `Personal/` group and appear in the EverLights app under Personal.
+- During a show, `set`/`play` only lasts until the show's next sequence change. `clear` briefly blanks the zone, then the show resumes.
+- `GET /v1/zones/{serial}/sequence` reports what's on the lights, including what a running show is playing.
+
+## Development
+
+```sh
+ruby -Ilib -e 'Dir["test/*_test.rb"].each { require "./#{_1}" }'
+```
+
+The tests run against a fake bridge, so no hardware is needed.
+
+## Credits
+
+The protocol work builds on [weswitt/everlights3](https://github.com/weswitt/everlights3), whose OpenAPI spec mapped the endpoints, and [theOrakle/everlightsv3](https://github.com/theOrakle/everlightsv3), which is also the source of the logo images. There is also a Home Assistant [core integration](https://www.home-assistant.io/integrations/everlights) for the older v2 bridge.
+
+## License
+
+MIT

data/exe/everlights

@@ -0,0 +1,192 @@
+#!/usr/bin/env ruby
+require_relative "../lib/everlights"
+require "optparse"
+
+USAGE = <<~TXT
+  Usage: everlights COMMAND [args] [options]
+
+  Bridge:
+    bridge                                firmware, network, cloud, zone health
+    bridge time [TIME]                    set the bridge clock (default now)
+    bridge reboot --yes                   restart the bridge
+    zones                                 raw zone data (JSON)
+
+  Now (a running show takes back over at its next sequence change):
+    show                                  what each zone is playing
+    set COLOR... [--effect E[=N]]         show colors now
+    play SEQUENCE                         show a saved sequence now
+    off                                   lights dark
+    clear                                 hand control back to the calendar
+
+  Sequences:
+    sequence list [FILTER]
+    sequence add NAME COLOR... [--effect E[=N]]...
+    sequence update NAME COLOR... [--effect E[=N]]...   replace colors and effects
+    sequence remove NAME
+
+  Calendar:
+    calendar list [--limit DAYS]          upcoming shows, default next 365 days
+    calendar add DATE NAME SEQ[:SECS],... [--start HH:MM] [--end HH:MM] [--until DATE]
+                                          default dusk to 23:00, 20s per sequence
+    calendar remove DATE NAME
+
+  Sync (config/everlights.yml: sequences + schedule, see config/everlights.example.yml):
+    sync [--dry-run] [--adopt]            build sequences and the calendar ahead; prints the plan
+
+  Options:
+TXT
+
+opts = {effects: {}, limit: 365}
+parser = OptionParser.new do |o|
+  o.banner = USAGE
+  o.on("--host HOST", "bridge IP (default $EVERLIGHTS_HOST, then the config's bridge.host)") { opts[:host] = _1 }
+  o.on("--config PATH", "config file (default $EVERLIGHTS_CONFIG, then config/everlights.yml)") { opts[:config] = _1 }
+  o.on("--zone SERIAL", "limit set/play/off/clear/show to a zone (repeatable)") { (opts[:zones] ||= []) << _1 }
+  o.on("--effect E[=N]", "N 0-255 (default 128): #{Everlights::EFFECTS.join(" ")}") do |e|
+    type, value = e.split("=")
+    opts[:effects][type] = value
+  end
+  o.on("--limit DAYS", Integer, "calendar list horizon") { opts[:limit] = _1 }
+  o.on("--start HH:MM", "fixed start instead of dusk") { opts[:start] = _1 }
+  o.on("--end HH:MM", "default 23:00; earlier than start = next morning") { opts[:end] = _1 }
+  o.on("--until DATE", "repeat nightly through DATE") { opts[:until] = _1 }
+  o.on("--json", "JSON output for lists, show and bridge") { opts[:json] = true }
+  o.on("--yes", "confirm bridge reboot") { opts[:yes] = true }
+  o.on("--dry-run", "sync: print the plan only") { opts[:dry_run] = true }
+  o.on("--adopt", "sync: take over bridge items whose names match the config") { opts[:adopt] = true }
+end
+parser.parse!
+abort parser.help if ARGV.empty?
+
+def json(obj) = puts(JSON.pretty_generate(obj))
+
+begin
+  config_path = opts[:config] || ENV["EVERLIGHTS_CONFIG"] || "config/everlights.yml"
+  config = if File.exist?(config_path) then Everlights::Sync.load_config(config_path)
+           elsif opts[:config] || ENV["EVERLIGHTS_CONFIG"] then raise Everlights::Error, "no config at #{config_path}"
+           end
+  ENV["TZ"] = config["timezone"] if config&.dig("timezone")
+  el = Everlights::Client.new(opts[:host] || ENV["EVERLIGHTS_HOST"] || config&.dig("bridge", "host"))
+  zones = opts[:zones]
+  cmd = ARGV.shift
+  cmd = "#{cmd} #{ARGV.shift}" if %w[sequence calendar].include?(cmd) ||
+                                   (cmd == "bridge" && %w[time reboot].include?(ARGV.first))
+  arg = ARGV.join(" ")
+
+  case cmd
+  when "bridge"
+    b = el.status
+    if opts[:json] then json(b)
+    else
+      at = ->(v) { v ? Time.parse(v).localtime.strftime("%Y-%m-%d %H:%M:%S") : "?" }
+      net = b["network"] || {}
+      puts "Bridge #{b["serial"]}  firmware #{b["firmwareVersion"]}, radio #{b["radioFirmwareVersion"]}"
+      puts "  network  #{net["interface"] || "?"} #{b["localIp"]}, ntp #{net["ntp"] ? "ok" : "off"}"
+      puts "  cloud    #{b["serverReachable"] ? "reachable" : "UNREACHABLE"}, last check-in #{at.(b["lastServerCheckin"])}"
+      puts "  reboots  #{b["rebootCount"]}"
+      b["zones"].each do |z|
+        puts "Zone #{z["serial"]}  firmware #{z["firmwareVersion"]}, #{z["configuredLength"]} pixels #{z["colorOrder"]}, #{z["active"] ? "active" : "INACTIVE"}"
+        puts "  signal   rssi #{z["rssi"]}, snr #{z["snr"]}"
+        puts "  sensors  temperature #{z["temperature"]}, voltage #{z["voltage"]}, current #{z["current"]} (raw, units unknown)"
+        puts "  last     request #{at.(z["lastRequestDate"])}, response #{at.(z["lastResponseDate"])}, reboots #{z["rebootCount"]}"
+      end
+    end
+  when "bridge time"
+    time = ARGV.empty? ? Time.now : Time.parse(arg)
+    el.set_time(time)
+    puts "bridge clock set to #{time}"
+  when "bridge reboot"
+    abort "rebooting interrupts the lights; rerun with --yes" unless opts[:yes]
+    el.reboot
+    puts "rebooting bridge"
+  when "zones" then json el.zones
+  when "show"
+    playing = el.now_playing(zones: zones)
+    if opts[:json] then json(playing)
+    else
+      playing.each do |zone, p|
+        what = if p[:off] then "off"
+               elsif p[:name] then "#{p[:name]}#{" (#{p[:show]} show)" if p[:show]}"
+               else "custom colors #{p[:pattern].join(" ")}"
+               end
+        fx = p[:effects].map { "#{_1["effectType"]}=#{_1["value"]}" }.join(" ")
+        puts "#{zone}  #{what}#{"  #{fx}" unless fx.empty?}"
+      end
+    end
+  when "set"
+    abort "set needs colors" if ARGV.empty?
+    el.set(*ARGV, effects: opts[:effects], zones: zones)
+    puts "showing #{arg}"
+  when "play" then puts "playing #{el.play(arg, zones: zones)["alias"]}"
+  when "off"
+    el.off(zones: zones)
+    puts "off"
+  when "clear"
+    el.clear(zones: zones)
+    puts "cleared, calendar in control"
+
+  when "sequence list"
+    seqs = el.sequences.list(arg)
+    if opts[:json] then json(seqs)
+    else
+      seqs.each do |s|
+        mark = s["id"].start_with?(Everlights::BUILTIN_PREFIX) ? " " : "*"
+        fx = s["effects"].map { "#{_1["effectType"]}=#{_1["value"]}" }.join(" ")
+        puts "#{mark} #{s["alias"].ljust(28)} #{s["pattern"].size.to_s.rjust(3)} color#{"s" unless s["pattern"].size == 1}#{" " if s["pattern"].size == 1}  #{fx}"
+      end
+    end
+  when "sequence add"
+    name, *colors = ARGV
+    abort "sequence add NAME COLOR..." if colors.empty?
+    el.sequences.add(name, *colors, effects: opts[:effects])
+    puts "added sequence #{name}"
+  when "sequence update"
+    name, *colors = ARGV
+    abort "sequence update NAME COLOR..." if colors.empty?
+    el.sequences.update(name, *colors, effects: opts[:effects])
+    puts "updated sequence #{name}"
+  when "sequence remove"
+    el.sequences.remove(arg)
+    puts "removed sequence #{arg}"
+
+  when "calendar list"
+    shows = el.calendar.list(limit: opts[:limit])
+    if opts[:json]
+      json(shows.map { |s| s.merge(date: s[:date].iso8601, start: s[:start].iso8601, finish: s[:finish].iso8601) })
+    elsif shows.empty?
+      puts "nothing scheduled in the next #{opts[:limit]} days"
+    else
+      shows.each do |s|
+        window = "#{s[:dusk] ? "dusk" : s[:start].strftime("%H:%M")}-#{s[:finish].strftime("%H:%M")}"
+        seqs = s[:sequences].map { |n, secs| "#{n}:#{secs}" }.join(", ")
+        puts "#{s[:start].strftime("%a %Y-%m-%d")}  #{window.ljust(11)}  #{s[:name]}  (#{seqs})"
+      end
+    end
+  when "calendar add"
+    date, name, *rest = ARGV
+    abort "calendar add DATE NAME SEQ[:SECS],..." if rest.empty?
+    el.calendar.add(date, name, rest.join(" "), start: opts[:start], finish: opts[:end] || "23:00", through: opts[:until])
+    puts "added #{name} on #{date}#{" through #{opts[:until]}" if opts[:until]}"
+  when "calendar remove"
+    date, *name = ARGV
+    abort "calendar remove DATE NAME" if name.empty?
+    el.calendar.remove(date, name.join(" "))
+    puts "removed #{name.join(" ")} on #{date}"
+
+  when "sync"
+    raise Everlights::Error, "no config at #{config_path}; copy config/everlights.example.yml to start" unless config
+    state_path = File.join(File.dirname(config_path), ".sync-state.yml")
+    plan = Everlights::Sync.new(el, config, state_path: state_path, adopt: opts[:adopt]).plan
+    puts plan
+    if plan.empty? then nil
+    elsif opts[:dry_run] then puts "\n(dry run: nothing applied)"
+    else
+      plan.apply!
+      puts "\nApplied."
+    end
+
+  else abort parser.help
+  end
+rescue Everlights::Error, IndexError, ArgumentError, TypeError, Date::Error, SystemCallError, Net::OpenTimeout => e
+  abort "error: #{e.message}"
+end

data/lib/everlights/sync.rb

@@ -0,0 +1,433 @@
+require "yaml"
+
+module Everlights
+  # Builds sequences and calendar entries on the bridge from a config (see config/everlights.example.yml).
+  #
+  #   config = Everlights::Sync.load_config("config/everlights.yml")
+  #   plan = Everlights::Sync.new(el, config, state_path: "config/.sync-state.yml").plan  # raises Error listing every config problem
+  #   puts plan
+  #   plan.apply!
+  #
+  # Sync only creates, changes and deletes what it created itself (tracked in the state file).
+  # Times are local: set ENV["TZ"] (the CLI uses the config's `timezone:`) before planning.
+  class Sync
+    MARGIN = 15 * 60 # never add a night that starts sooner than this
+    ORDINALS = {"1st" => 1, "first" => 1, "2nd" => 2, "second" => 2, "3rd" => 3, "third" => 3,
+                "4th" => 4, "fourth" => 4, "5th" => 5, "fifth" => 5, "last" => -1}.freeze
+    PHASE = {sequence: {adopt: 0, create: 0, update: 0, delete: 2, untrack: 2, forget: 2},
+             event: Hash.new(1)}.freeze # sequences exist before events use them; deleted after events stop
+
+    Action = Struct.new(:kind, :op, :name, :detail, :run)
+
+    Plan = Struct.new(:actions, :skips, :horizon, :sync) do
+      def empty? = actions.empty?
+      def apply! = sync.apply(self)
+
+      def to_s
+        mark = {create: "+", update: "~", delete: "-", adopt: "@", untrack: "=", forget: "="}
+        out = []
+        {sequence: "Sequences", event: "Calendar (next #{horizon} days)"}.each do |kind, title|
+          rows = actions.select { _1.kind == kind }
+          next if rows.empty?
+          out << title
+          rows.each { |a| out << "  #{mark[a.op]} #{a.op.to_s.ljust(7)} #{a.name}#{": #{a.detail}" if a.detail}" }
+        end
+        lost, other = skips.partition { |_, _, why| why.end_with?(" wins this night") }
+        unless other.empty?
+          out << "Skipped"
+          other.each { |d, rule, why| out << "    #{d.strftime("%a %Y-%m-%d")}  #{rule}: #{why}" }
+        end
+        unless lost.empty?
+          out << "Nights taken by a higher rule"
+          lost.group_by { |_, rule, why| [rule, why.delete_suffix(" wins this night")] }.each do |(rule, winner), rows|
+            days = rows.map(&:first)
+            span = days.size == 1 ? days[0].strftime("%b %-d") : "#{days[0].strftime("%b %-d")} – #{days[-1].strftime("%b %-d")}"
+            out << "    #{rule}: #{days.size} night#{"s" unless days.size == 1} to #{winner} (#{span})"
+          end
+        end
+        out << "Nothing to change." if empty?
+        out.join("\n")
+      end
+    end
+
+    def self.load_config(path)
+      config = YAML.safe_load_file(path, permitted_classes: [Date]) || {}
+      # YAML 1.1 reads the key `on:` as boolean true; put it back
+      Array(config["schedule"]).each { |r| r["on"] = r.delete(true) if r.is_a?(Hash) && r.key?(true) }
+      config
+    rescue Psych::SyntaxError => e
+      raise Error, "#{path}: #{e.message}"
+    end
+
+    def initialize(client, config, state_path: nil, adopt: false, now: Time.now)
+      @c, @cfg, @state_path, @adopt, @now = client, config || {}, state_path, adopt, now
+    end
+
+    def plan
+      @errors = []
+      @state = load_state
+      bridge_seqs = @c.sequence_list
+      bridge_events = @c.event_list
+      actions = @adopt ? adopt(bridge_seqs, bridge_events) : []
+      owned_seq_ids = @state["sequences"].values
+      owned_event_ids = @state["events"].values
+      config_seqs = @cfg["sequences"] || {}
+
+      # Names a rule can use: built-ins and app-made sequences, plus the config's own.
+      seq_ids = {}
+      bridge_seqs.each { |s| seq_ids[s["alias"].downcase] ||= s["id"] unless owned_seq_ids.include?(s["id"]) }
+
+      config_seqs.each do |name, spec|
+        spec ||= {}
+        pattern = check("sequence #{name.inspect}") { Everlights.colors(spec["colors"]) }
+        effects = check("sequence #{name.inspect}") { Everlights.effects(spec["effects"]) }
+        @errors << "sequence #{name.inspect}: needs colors" if pattern&.empty?
+        clash = bridge_seqs.find { _1["alias"].casecmp?(name) && !owned_seq_ids.include?(_1["id"]) }
+        if clash
+          @errors << if clash["id"].start_with?(BUILTIN_PREFIX)
+                       "sequence #{name.inspect} has the same name as a built-in; rename it"
+                     else
+                       "sequence #{name.inspect} already exists on the bridge (made in the app?); rename it or run with --adopt"
+                     end
+          next
+        end
+        current = bridge_seqs.find { _1["id"] == @state["sequences"][name] }
+        id = current ? current["id"] : SecureRandom.uuid
+        seq_ids[name.downcase] = id
+        next unless pattern && effects
+        if current.nil?
+          actions << Action.new(:sequence, :create, name, "#{pattern.size} color#{"s" unless pattern.size == 1}",
+                                -> { @c.create_sequence(name, pattern: pattern, effects: effects, id: id); @state["sequences"][name] = id })
+        elsif current["pattern"] != pattern || current["effects"] != effects
+          actions << Action.new(:sequence, :update, name, "#{pattern.size} color#{"s" unless pattern.size == 1}",
+                                -> { @c.update_sequence(current, pattern: pattern, effects: effects) })
+        end
+      end
+
+      rules = (@cfg["schedule"] || []).each_with_index.filter_map { |r, i| compile_rule(r || {}, i, seq_ids) }
+      dupes = Array(@cfg["schedule"]).filter_map { _1["name"].to_s.strip.downcase if _1.is_a?(Hash) }
+                                     .reject(&:empty?).tally.select { _2 > 1 }.keys
+      @errors << "rule names must be unique: #{dupes.join(", ")}" if dupes.any?
+      rules.each do |r|
+        clash = bridge_events.find { _1["alias"].casecmp?(r[:name]) && !owned_event_ids.include?(_1["id"]) }
+        @errors << "rule #{r[:name].inspect} has the same name as calendar entry #{clash["alias"].inspect} made outside sync; rename it or run with --adopt" if clash
+      end
+      raise Error, "config problems, nothing applied:\n  - #{@errors.uniq.join("\n  - ")}" if @errors.any?
+
+      # Which rule gets each night, and when it starts and ends.
+      horizon = Integer(@cfg["horizon_days"] || 120)
+      today = @now.to_date
+      others = bridge_events.reject { owned_event_ids.include?(_1["id"]) }.flat_map do |e|
+        e["occurrences"].map { |o| [e["alias"], Time.parse(o["start"]), Time.parse(o["end"])] }
+      end
+      wanted = Hash.new { |h, k| h[k] = [] }
+      skips = []
+      (today..today + horizon).each do |d|
+        winner, *losers = rules.select { _1[:matches].(d) }
+        next unless winner
+        losers.each { skips << [d, _1[:name], "#{winner[:name]} wins this night"] }
+        s, e = window(winner, d)
+        if e.nil?
+          skips << [d, winner[:name], "dusk (#{s.strftime("%H:%M")}) is after its end time"]
+        elsif s <= @now + MARGIN
+          skips << [d, winner[:name], "already started or starts within 15 minutes"]
+        elsif (other = others.find { |_, os, oe| os < e && s < oe })
+          skips << [d, winner[:name], "#{other[0].inspect} (made outside sync) has this night"]
+        else
+          wanted[winner[:name]] << [s, e]
+        end
+      end
+
+      # One calendar entry per rule. Nights already under way stay; ended ones are dropped.
+      live = ->(event) { event["occurrences"].select { |o| Time.parse(o["start"]) <= @now + MARGIN && Time.parse(o["end"]) > @now } }
+      rules.each do |r|
+        nights = wanted[r[:name]]
+        current = bridge_events.find { _1["id"] == @state["events"][r[:name]] }
+        kept = current ? live.(current).map { [Time.parse(_1["start"]), Time.parse(_1["end"])] } : []
+        occurrences = kept + nights
+        flags = r[:start][:dusk] ? ["StartAtDusk"] : []
+        if current.nil?
+          next if nights.empty?
+          id = SecureRandom.uuid
+          actions << Action.new(:event, :create, r[:name], describe(r, nights), lambda {
+            @c.create_event(r[:name], sequences: r[:seqs], occurrences: nights, flags: flags, id: id)
+            @state["events"][r[:name]] = id
+          })
+        elsif occurrences.empty?
+          actions << Action.new(:event, :delete, r[:name], "no nights left in the window",
+                                -> { @c.delete_event(current["id"]); @state["events"].delete(r[:name]) })
+        elsif changed?(current, r[:seqs], occurrences, flags)
+          actions << Action.new(:event, :update, r[:name], describe(r, nights), lambda {
+            @c.update_event(current.merge("sequences" => r[:seqs].map { |sid, secs| {"sequenceId" => sid, "duration" => secs} },
+                                          "occurrences" => occurrences.map { |s, e| {"start" => Everlights.stamp(s), "end" => Everlights.stamp(e)} },
+                                          "flags" => flags))
+          })
+        end
+      end
+
+      # Rules removed from the config: delete their entries, but never cut off a show that's under way.
+      (@state["events"].keys - rules.map { _1[:name] }).each do |name|
+        current = bridge_events.find { _1["id"] == @state["events"][name] }
+        if current.nil?
+          actions << Action.new(:event, :forget, name, "already gone from the bridge", -> { @state["events"].delete(name) })
+        elsif (keep = live.(current)).empty?
+          actions << Action.new(:event, :delete, name, "removed from config",
+                                -> { @c.delete_event(current["id"]); @state["events"].delete(name) })
+        elsif keep != current["occurrences"]
+          actions << Action.new(:event, :update, name, "removed from config; keeping tonight's show, deleted next sync",
+                                -> { @c.update_event(current.merge("occurrences" => keep)) })
+        end
+      end
+
+      # Sequences removed from the config: delete, unless something made outside sync still plays them.
+      (@state["sequences"].keys - config_seqs.keys).each do |name|
+        id = @state["sequences"][name]
+        if bridge_seqs.none? { _1["id"] == id }
+          actions << Action.new(:sequence, :forget, name, "already gone from the bridge", -> { @state["sequences"].delete(name) })
+        elsif (user = bridge_events.find { |e| !owned_event_ids.include?(e["id"]) && e["sequences"].any? { _1["sequenceId"] == id } })
+          actions << Action.new(:sequence, :untrack, name, "still used by #{user["alias"].inspect}; keeping it, no longer synced",
+                                -> { @state["sequences"].delete(name) })
+        else
+          actions << Action.new(:sequence, :delete, name, "removed from config",
+                                -> { @c.delete_sequence(id); @state["sequences"].delete(name) })
+        end
+      end
+
+      Plan.new(actions, skips, horizon, self)
+    end
+
+    def apply(plan)
+      plan.actions.each_with_index.sort_by { |a, i| [PHASE[a.kind][a.op], i] }.each { |a, _| a.run.() }
+    ensure
+      save_state
+    end
+
+    # --- dates ---
+
+    # Anonymous Gregorian algorithm.
+    def self.easter(year)
+      a, b, c = year % 19, year / 100, year % 100
+      d, e = b / 4, b % 4
+      g = (b - (b + 8) / 25 + 1) / 3
+      h = (19 * a + b - d - g + 15) % 30
+      l = (32 + 2 * e + 2 * (c / 4) - h - (c % 4)) % 7
+      m = (a + 11 * h + 22 * l) / 451
+      Date.new(year, (h + l - 7 * m + 114) / 31, ((h + l - 7 * m + 114) % 31) + 1)
+    end
+
+    # n = 1..5, or -1 for last; nil when the month has no such day
+    def self.nth_weekday(year, month, wday, n)
+      if n.negative?
+        last = Date.new(year, month, -1)
+        return last - (last.wday - wday) % 7
+      end
+      first = Date.new(year, month, 1)
+      d = first + (wday - first.wday) % 7 + 7 * (n - 1)
+      d.month == month ? d : nil
+    end
+
+    # NOAA sunrise/sunset algorithm (Almanac for Computers, 1990). Within a minute or two of published times.
+    def self.sunset(date, lat, lon)
+      rad = Math::PI / 180
+      lng_hour = lon / 15.0
+      t = date.yday + ((18 - lng_hour) / 24)
+      m = 0.9856 * t - 3.289
+      l = (m + 1.916 * Math.sin(m * rad) + 0.020 * Math.sin(2 * m * rad) + 282.634) % 360
+      ra = (Math.atan(0.91764 * Math.tan(l * rad)) / rad) % 360
+      ra = (ra + (l / 90).floor * 90 - (ra / 90).floor * 90) / 15
+      sin_dec = 0.39782 * Math.sin(l * rad)
+      cos_dec = Math.cos(Math.asin(sin_dec))
+      cos_h = (Math.cos(90.833 * rad) - sin_dec * Math.sin(lat * rad)) / (cos_dec * Math.cos(lat * rad))
+      raise Error, "no sunset at latitude #{lat} on #{date}" unless cos_h.between?(-1, 1)
+      ut = (Math.acos(cos_h) / rad / 15 + ra - 0.06571 * t - 6.622 - lng_hour) % 24
+      time = (Time.utc(date.year, date.month, date.day) + ut * 3600).localtime
+      time += 86_400 while time.to_date < date # western longitudes: sunset is the next UTC day
+      time -= 86_400 while time.to_date > date
+      time
+    end
+
+    private
+
+    def check(where)
+      yield
+    rescue Error, ArgumentError, TypeError => e
+      @errors << "#{where}: #{e.message}"
+      nil
+    end
+
+    def load_state
+      state = @state_path && File.exist?(@state_path) ? YAML.safe_load_file(@state_path) : nil
+      {"sequences" => {}, "events" => {}}.merge(state || {})
+    end
+
+    def save_state
+      return unless @state_path && @state
+      File.write(@state_path, "# Written by `everlights sync`: what it created on the bridge. Don't edit.\n#{YAML.dump(@state)}")
+    end
+
+    def adopt(bridge_seqs, bridge_events)
+      actions = []
+      (@cfg["sequences"] || {}).each_key do |name|
+        next if @state["sequences"].key?(name)
+        s = bridge_seqs.find { _1["alias"].casecmp?(name) && !_1["id"].start_with?(BUILTIN_PREFIX) }
+        next unless s
+        @state["sequences"][name] = s["id"]
+        actions << Action.new(:sequence, :adopt, name, "now managed by sync", -> {})
+      end
+      (@cfg["schedule"] || []).each do |r|
+        name = r && r["name"].to_s
+        next if name.to_s.empty? || @state["events"].key?(name)
+        e = bridge_events.find { _1["alias"].casecmp?(name) }
+        next unless e
+        @state["events"][name] = e["id"]
+        actions << Action.new(:event, :adopt, name, "now managed by sync", -> {})
+      end
+      actions
+    end
+
+    def compile_rule(r, i, seq_ids)
+      name = r["name"].to_s.strip
+      where = name.empty? ? "rule ##{i + 1}" : "rule #{name.inspect}"
+      @errors << "#{where}: needs a name" if name.empty?
+      defaults = {"start" => "dusk", "end" => "23:00", "seconds" => DEFAULT_SECONDS}.merge(@cfg["defaults"] || {})
+      matches = matcher(r, where)
+      start = check(where) { parse_start(r.fetch("start", defaults["start"])) }
+      finish = check(where) { parse_hm(r.fetch("end", defaults["end"])) }
+      if start&.dig(:dusk) && !(@cfg.dig("location", "lat") && @cfg.dig("location", "lon"))
+        @errors << "#{where}: dusk needs `location: {lat:, lon:}` in the config"
+      end
+      seconds = r.fetch("seconds", defaults["seconds"])
+      @errors << "#{where}: needs sequences" if Array(r["sequences"]).empty?
+      seqs = Array(r["sequences"]).map do |spec|
+        ref, secs = spec.to_s.strip.split(/:(?=\d+\z)/)
+        id = seq_ids[ref.to_s.downcase]
+        @errors << "#{where}: unknown sequence #{ref.inspect}" unless id
+        [id, check(where) { Integer(secs || seconds) }]
+      end
+      return nil if name.empty? || !matches || !start || !finish || seqs.empty? || seqs.flatten.include?(nil)
+      {name: name, matches: matches, start: start, end: finish, seqs: seqs}
+    end
+
+    def matcher(r, where)
+      on, every, range = r["on"], r["every"], r.key?("from") || r.key?("to")
+      if [on, every].compact.size + (range && !every ? 1 : 0) != 1
+        @errors << "#{where}: needs exactly one of `on:`, `from:`/`to:`, or `every:`"
+        return nil
+      end
+      return check(where) { on_matcher(on) } if on
+      in_range = range ? check(where) { range_matcher(r["from"], r["to"]) } : ->(_) { true }
+      return in_range unless every && in_range
+      days = check(where) { Array(every).map { weekday(_1) } }
+      days && ->(d) { days.include?(d.wday) && in_range.(d) }
+    end
+
+    def on_matcher(v)
+      at = date_expr(v)
+      ->(d) { (d.year - 1..d.year + 1).any? { at.(_1) == d } } # offsets can cross a year boundary
+    end
+
+    def range_matcher(from, to)
+      raise Error, "`from:` and `to:` go together" unless from && to
+      first_of, last_of = date_expr(from), date_expr(to)
+      lambda do |d|
+        (d.year - 1..d.year).any? do |y|
+          first, last = first_of.(y), last_of.(y)
+          last = last_of.(y + 1) if first && last && last < first # e.g. Dec 1 to Jan 6 wraps the new year
+          first && last && d.between?(first, last)
+        end
+      end
+    end
+
+    # A date expression -> lambda(year) -> Date or nil:
+    #   "2027-03-14", "Dec 25", "4th Thursday of November", "last Monday of May", "Easter",
+    #   each optionally shifted by days: "Easter-47", "4th Thursday of November+1"
+    def date_expr(v)
+      return ->(_) { v } if v.is_a?(Date)
+      text = v.to_s.strip
+      begin
+        base_expr(text)
+      rescue Error => e
+        m = text.match(/\A(.*\S)\s*([+-])\s*(\d+)\z/) or raise e
+        base = base_expr(m[1]) # with an offset, report what's wrong with the date before it
+        days = m[3].to_i * (m[2] == "-" ? -1 : 1)
+        ->(y) { base.(y)&.+(days) }
+      end
+    end
+
+    def base_expr(text)
+      case text
+      when /\A\d{4}-\d{1,2}-\d{1,2}\z/
+        date = Date.parse(text)
+        ->(_) { date }
+      when /\Aeaster\z/i
+        ->(y) { Sync.easter(y) }
+      when /\A(\S+)\s+(\S+)\s+of\s+(\S+)\z/i
+        ordinal, day_name, month_name = $1, $2, $3
+        nth = ORDINALS[ordinal.downcase] or raise Error, "can't read #{text.inspect}; try \"4th Thursday of November\" or \"last Monday of May\""
+        wday, mon = weekday(day_name), month(month_name)
+        ->(y) { Sync.nth_weekday(y, mon, wday, nth) }
+      else
+        m = text.match(/\A([A-Za-z]+\.?)\s+(\d{1,2})\z/) or raise Error, "can't read date #{text.inspect}; try \"Dec 25\" or \"Easter-47\""
+        mon, day = month(m[1]), m[2].to_i
+        raise Error, "no such date #{text.inspect}" unless Date.valid_date?(2024, mon, day)
+        ->(y) { Date.valid_date?(y, mon, day) ? Date.new(y, mon, day) : nil } # Feb 29 only in leap years
+      end
+    end
+
+    # Full name or three-letter abbreviation
+    def month(s) = name_index(Date::MONTHNAMES, Date::ABBR_MONTHNAMES, s) || raise(Error, "unknown month #{s.inspect}")
+    def weekday(s) = name_index(Date::DAYNAMES, Date::ABBR_DAYNAMES, s) || raise(Error, "unknown weekday #{s.inspect}")
+    def name_index(full, abbr, s) = [full, abbr].lazy.filter_map { |names| names.index { _1&.casecmp?(s.to_s.delete_suffix(".")) } }.first
+
+    # "dusk", "dusk+15", "dusk-10" or "HH:MM"
+    def parse_start(v)
+      return {dusk: true, offset: Integer($1.delete(" "), 10)} if v.to_s.strip =~ /\Adusk\s*([+-]\s*\d+)\z/i
+      return {dusk: true, offset: 0} if v.to_s.strip.casecmp?("dusk")
+      {dusk: false, hm: parse_hm(v)}
+    end
+
+    # YAML reads an unquoted 18:30 as a base-60 number: seconds (66600) in Psych 5+, minutes (1110) before.
+    YAML_MINUTE = YAML.safe_load("x: 1:00")["x"] / 60
+
+    # "18:30", or the number YAML made of an unquoted 18:30
+    def parse_hm(v)
+      return (v / YAML_MINUTE).divmod(60) if v.is_a?(Integer)
+      m = v.to_s.strip.match(/\A(\d{1,2}):(\d{2})\z/) or raise Error, "can't read time #{v.inspect}; want HH:MM"
+      h, min = m[1].to_i, m[2].to_i
+      raise Error, "no such time #{v.inspect}" unless h < 24 && min < 60
+      [h, min]
+    end
+
+    def window(r, d)
+      s = if r[:start][:dusk]
+            Sync.sunset(d, @cfg.dig("location", "lat").to_f, @cfg.dig("location", "lon").to_f) + r[:start][:offset] * 60
+          else
+            at(d, r[:start][:hm])
+          end
+      s = Time.at(s.to_i) # whole seconds, so re-planning compares equal
+      e = at(d, r[:end])
+      if e <= s
+        return [s, nil] if r[:end][0] >= 12 # an evening end already past dusk: no show, not a 24-hour one
+        e = at(d + 1, r[:end]) # "01:00" means the next morning
+      end
+      [s, e]
+    end
+
+    def at(d, (h, m)) = Time.new(d.year, d.month, d.day, h, m) # wall clock, so DST doesn't shift shows
+
+    def changed?(event, seqs, occurrences, flags)
+      have = [event["sequences"].map { [_1["sequenceId"], _1["duration"]] },
+              event["occurrences"].map { [Time.parse(_1["start"]).to_i, Time.parse(_1["end"]).to_i] },
+              event["flags"]]
+      have != [seqs, occurrences.map { |s, e| [s.to_i, e.to_i] }, flags]
+    end
+
+    def describe(r, nights)
+      return "nothing new in the window" if nights.empty?
+      s, e = nights.first
+      start = r[:start][:dusk] ? "dusk (#{s.strftime("%H:%M")})" : s.strftime("%H:%M")
+      span = nights.size == 1 ? s.strftime("%b %-d") : "#{s.strftime("%b %-d")} – #{nights.last[0].strftime("%b %-d")}"
+      "#{nights.size} night#{"s" unless nights.size == 1}, #{span}, #{start}–#{e.strftime("%H:%M")}"
+    end
+  end
+end

data/lib/everlights.rb

@@ -0,0 +1,256 @@
+require "net/http"
+require "json"
+require "securerandom"
+require "time"
+
+# Client for the EverLights Smart Lights Bridge local HTTP API (no auth, port 80).
+# Endpoints from github.com/weswitt/everlights3 OpenAPI spec, verified on firmware B4042.
+#
+#   el = Everlights::Client.new("192.168.1.50")
+#   el.play "Hallows Eve"
+#   el.sequences.add "Candy Cane", "FF0000", "FFFFFF", effects: {chase: 60}
+#   el.calendar.add "2026-12-01", "Christmas", "Candy Cane:30,Christmas", through: "2027-01-01"
+#   el.calendar.list(limit: 30)
+#   el.calendar.remove "2026-12-25", "Christmas"
+module Everlights
+  Error = Class.new(StandardError)
+
+  ALL_ZONES = "000000000000" # what the app writes into zoneSerials for "every zone"
+  PERSONAL_GROUP = "Personal/" # where the app files user-made sequences
+  BUILTIN_PREFIX = "00000000-0000-0000-0000-" # ids of EverLights' stock sequences
+  DEFAULT_SECONDS = 20
+  EFFECTS = %w[bars blink chase fade gradient lightning melt pingPong random reverseChase strobe twinkle wipe].freeze
+
+  class Client
+    def initialize(host = nil, timeout: 10)
+      host ||= ENV["EVERLIGHTS_HOST"]
+      raise Error, "no host: pass one or set EVERLIGHTS_HOST" unless host
+      uri = URI("http://#{host}")
+      @http = Net::HTTP.new(uri.host, uri.port)
+      @http.open_timeout = @http.read_timeout = timeout
+    end
+
+    def sequences = Sequences.new(self)
+    def calendar = Calendar.new(self)
+
+    def status = get("/v1")
+    def zones = get("/v1/zones")
+    def zone_serials = zones.map { _1["serial"] }
+
+    # Show something right now. During a running show this lasts only until the show's next sequence change.
+    def set(*colors, effects: {}, zones: nil)
+      (zones || zone_serials).each { set_program(_1, pattern: colors.flatten, effects: effects) }
+    end
+
+    def play(name, zones: nil)
+      seq = find_sequence(name)
+      (zones || zone_serials).each { set_program(_1, pattern: seq["pattern"], effects: seq["effects"]) }
+      seq
+    end
+
+    # Hands control back to the calendar.
+    def clear(zones: nil) = (zones || zone_serials).each { clear_program(_1) }
+
+    # Lights dark: an empty pattern, as theOrakle/everlightsv3 does. A running show resumes at its next change.
+    def off(zones: nil) = (zones || zone_serials).each { set_program(_1, pattern: []) }
+
+    # What each zone shows right now:
+    #   {serial => {name:, show:, off:, pattern:, effects:}}
+    # name: the sequence (the bridge names it during a show; otherwise matched by colors+effects), nil = custom colors
+    # show: the running calendar entry it belongs to, if any
+    def now_playing(zones: nil)
+      seqs = sequence_list
+      now = Time.now
+      running = calendar.list(limit: 1, now: now).select { _1[:start] <= now && now <= _1[:finish] }
+      (zones || zone_serials).to_h do |zone|
+        prog = program(zone) || {}
+        pattern, effects = prog["pattern"] || [], prog["effects"] || []
+        name = prog["alias"] || seqs.find { _1["pattern"] == pattern && _1["effects"] == effects }&.fetch("alias")
+        name = nil if pattern.empty?
+        show = name && running.find { |s| s[:sequences].any? { |seq_name, _| seq_name == name } }&.fetch(:name)
+        [zone, {name: name, show: show, off: pattern.empty?, pattern: pattern, effects: effects}]
+      end
+    end
+
+    # --- raw endpoints ---
+
+    def program(zone) = get("/v1/zones/#{zone}/sequence")
+
+    def set_program(zone, pattern:, effects: {})
+      request(Net::HTTP::Post, "/v1/zones/#{zone}/sequence",
+              colorMode: "rgb", pattern: colors(pattern), effects: effects_body(effects))
+    end
+
+    def clear_program(zone) = request(Net::HTTP::Delete, "/v1/zones/#{zone}/sequence")
+
+    def sequence_list = get("/v1/sequences")
+
+    def find_sequence(name_or_id)
+      sequence_list.find { _1["id"] == name_or_id || _1["alias"].casecmp?(name_or_id.to_s.strip) } ||
+        raise(Error, "no sequence named #{name_or_id.inspect}")
+    end
+
+    def create_sequence(name, pattern:, effects: {}, id: SecureRandom.uuid)
+      request(Net::HTTP::Post, "/v1/sequences",
+              id: id, alias: name, groups: [PERSONAL_GROUP], colorMode: "rgb",
+              pattern: colors(pattern), effects: effects_body(effects), lastChanged: stamp(Time.now))
+    end
+
+    # seq: a hash from #sequence_list; pattern and effects replace its own
+    def update_sequence(seq, pattern:, effects: {})
+      request(Net::HTTP::Put, "/v1/sequences/#{seq["id"]}",
+              seq.merge("pattern" => colors(pattern), "effects" => effects_body(effects), "lastChanged" => stamp(Time.now)))
+    end
+
+    def delete_sequence(id) = request(Net::HTTP::Delete, "/v1/sequences/#{id}")
+
+    def event_list = get("/v1/events")
+
+    # sequences: [[sequence_id, seconds], ...]  occurrences: [[start_time, end_time], ...]
+    def create_event(name, sequences:, occurrences:, zones: [ALL_ZONES], flags: [], id: SecureRandom.uuid)
+      request(Net::HTTP::Post, "/v1/events",
+              id: id, alias: name, group: "User Created",
+              sequences: sequences.map { |id, secs| {sequenceId: id, duration: secs} },
+              zoneSerials: zones,
+              occurrences: occurrences.map { |s, e| {start: stamp(s), end: stamp(e)} },
+              flags: flags, lastChanged: stamp(Time.now))
+    end
+
+    # event: a hash from #event_list, edited
+    def update_event(event)
+      request(Net::HTTP::Put, "/v1/events/#{event["id"]}", event.merge("lastChanged" => stamp(Time.now)))
+    end
+
+    def delete_event(id) = request(Net::HTTP::Delete, "/v1/events/#{id}")
+
+    def set_time(time = Time.now) = request(Net::HTTP::Put, "/v1/time", time: stamp(time))
+    def reboot = get("/v1/reboot")
+
+    private
+
+    def get(path) = request(Net::HTTP::Get, path)
+
+    def request(verb, path, body = nil)
+      req = verb.new(path, "Content-Type" => "application/json")
+      req.body = JSON.generate(body) if body
+      res = @http.request(req)
+      raise Error, "#{verb::METHOD} #{path} -> #{res.code}: #{res.body}" unless res.is_a?(Net::HTTPSuccess)
+      res.body.to_s.empty? ? nil : JSON.parse(res.body)
+    end
+
+    def colors(pattern) = Everlights.colors(pattern)
+    def effects_body(effects) = Everlights.effects(effects)
+    def stamp(t) = Everlights.stamp(t)
+  end
+
+  # ["#ff0000", ...] -> ["FF0000", ...]
+  def self.colors(pattern)
+    Array(pattern).map do |c|
+      hex = c.to_s.delete_prefix("#").upcase
+      raise Error, "bad color #{c.inspect}, want RRGGBB" unless hex.match?(/\A\h{6}\z/)
+      hex
+    end
+  end
+
+  # {chase: 100} or the API's [{"effectType" => "chase", "value" => 100}] -> API form with string keys
+  def self.effects(effects)
+    (effects || {}).map do |e|
+      type, value = e.is_a?(Hash) ? e.values_at("effectType", "value") : e
+      raise Error, "unknown effect #{type}, want one of: #{EFFECTS.join(" ")}" unless EFFECTS.include?(type.to_s)
+      {"effectType" => type.to_s, "value" => Integer(value || 128)}
+    end
+  end
+
+  def self.stamp(t) = (t.is_a?(Time) ? t : Time.parse(t.to_s)).getutc.iso8601(6)
+
+  class Sequences
+    def initialize(client) = @c = client
+
+    def list(filter = nil) = @c.sequence_list.select { _1["alias"].downcase.include?(filter.to_s.downcase) }
+
+    def add(name, *colors, effects: {}) = @c.create_sequence(name, pattern: colors.flatten, effects: effects)
+
+    # Replaces its colors and effects; calendar entries using it keep working.
+    def update(name, *colors, effects: {}) = @c.update_sequence(own(name), pattern: colors.flatten, effects: effects)
+
+    def remove(name)
+      seq = own(name)
+      users = @c.event_list.select { |e| e["sequences"].any? { _1["sequenceId"] == seq["id"] } }
+      raise Error, "#{seq["alias"]} is used by: #{users.map { _1["alias"] }.join(", ")}" if users.any?
+      @c.delete_sequence(seq["id"])
+    end
+
+    private
+
+    def own(name)
+      seq = @c.find_sequence(name)
+      raise Error, "#{seq["alias"]} is built in, leaving it" if seq["id"].start_with?(BUILTIN_PREFIX)
+      seq
+    end
+  end
+
+  class Calendar
+    def initialize(client) = @c = client
+
+    # Upcoming shows, one hash per night, soonest first.
+    def list(limit: 365, now: Time.now)
+      names = @c.sequence_list.to_h { [_1["id"], _1["alias"]] }
+      horizon = now + limit * 86_400
+      @c.event_list.flat_map do |e|
+        e["occurrences"].filter_map do |o|
+          s, f = Time.parse(o["start"]).localtime, Time.parse(o["end"]).localtime
+          next if f < now || s > horizon
+          {date: s.to_date, start: s, finish: f, dusk: e["flags"].include?("StartAtDusk"),
+           name: e["alias"], event_id: e["id"],
+           sequences: e["sequences"].map { [names.fetch(_1["sequenceId"], _1["sequenceId"]), _1["duration"]] }}
+        end
+      end.sort_by { _1[:start] }
+    end
+
+    # sequences: "A:20,B:30" or {"A" => 20, "B" => 30} or ["A", "B"]; seconds default to 20.
+    # No start: means start at dusk. finish earlier than start means the next morning.
+    def add(date, name, sequences, start: nil, finish: "23:00", through: nil)
+      first = to_date(date)
+      last = through ? to_date(through) : first
+      raise Error, "through (#{last}) is before #{first}" if last < first
+      seqs = parse_sequences(sequences).map { |ref, secs| [@c.find_sequence(ref)["id"], secs] }
+      start_hm = start ? hm(start) : [17, 0] # ponytail: placeholder; the StartAtDusk flag moves it
+      end_hm = hm(finish)
+      occurrences = (first..last).map do |d|
+        s, f = at(d, start_hm), at(d, end_hm)
+        [s, f <= s ? at(d + 1, end_hm) : f]
+      end
+      @c.create_event(name, sequences: seqs, occurrences: occurrences, flags: start ? [] : ["StartAtDusk"])
+    end
+
+    # Drops that night from every event with this name; deletes events left empty.
+    def remove(date, name)
+      day = to_date(date)
+      removed = 0
+      @c.event_list.select { _1["alias"].casecmp?(name) }.each do |e|
+        keep, drop = e["occurrences"].partition { Time.parse(_1["start"]).localtime.to_date != day }
+        next if drop.empty?
+        removed += drop.size
+        keep.empty? ? @c.delete_event(e["id"]) : @c.update_event(e.merge("occurrences" => keep))
+      end
+      raise Error, "nothing named #{name.inspect} on #{day}" if removed.zero?
+      removed
+    end
+
+    private
+
+    def parse_sequences(seqs)
+      pairs = case seqs
+              when String then seqs.split(",").map { _1.strip.split(/:(?=\d+\z)/) }
+              else seqs.map { Array(_1) } # Hash yields pairs, Array yields names or pairs
+              end
+      pairs.map { |ref, secs| [ref, Integer(secs || DEFAULT_SECONDS)] }
+    end
+
+    def to_date(d) = d.respond_to?(:to_date) ? d.to_date : Date.parse(d.to_s)
+    def hm(t) = t.to_s.split(":").map { Integer(_1, 10) }
+    def at(d, h_m) = Time.new(d.year, d.month, d.day, *h_m) # wall clock, so DST doesn't shift shows
+  end
+end
+
+require_relative "everlights/sync"

data/skills/everlights/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: everlights
+description: Control EverLights permanent outdoor lights through the local bridge using the `everlights` CLI. Use when the user wants to change the house lights now, design a color sequence, or schedule a light show for a date or holiday ("put up Christmas lights for December", "make the roofline orange tonight", "what's scheduled?").
+---
+
+# EverLights
+
+The `everlights` CLI talks to the bridge on the LAN (no auth). It needs `EVERLIGHTS_HOST` (bridge IP) or `--host`. Lists print text (add `--json` for JSON); `status`, `zones` and `show` print JSON.
+
+## Before you write anything
+
+1. Run `everlights calendar list` and `everlights show` (names what's playing and which show it's from) first (`everlights bridge` if something seems broken). Report what's already scheduled or showing.
+2. Confirm before every write: `set`, `play`, `off`, `clear`, `sequence add/update/remove`, `calendar add/remove` and `bridge time`. These change real lights on a real house, so state the exact command you'll run.
+3. Only run `bridge reboot --yes` when the user explicitly asks; it interrupts the lights. The CLI refuses to remove built-in sequences, or sequences an event still uses.
+
+## Concepts
+
+- **Zone**: one run of pixels, identified by serial. `everlights zones` lists them. Commands default to all zones; `--zone SERIAL` narrows one.
+- **Sequence**: a saved pattern of hex colors (`RRGGBB`, repeated along the run) plus up to a few effects. The bridge has about 96 built-ins (`everlights sequence list xmas` searches by name; `*` marks user-made ones). Sequences added here show up in the EverLights app under Personal. Built-in names include "Birthday", so give personal sequences distinct names (e.g. "My Birthday").
+- **Effect**: `--effect TYPE=N`, N 0-255 (default 128; higher seems faster). Types: bars blink chase fade gradient lightning melt pingPong random reverseChase strobe twinkle wipe. Built-ins often stack two, e.g. `fade` + `reverseChase`.
+- **Manual program** (`set`/`play`): shows immediately. During a scheduled show, it only lasts until the show's next sequence change (about 20 seconds). Outside a show it stays. `clear` hands control back to the calendar.
+- **Calendar entry**: a scheduled show. It cycles its sequences (`NAME:SECONDS`, default 20) during each night's window. The bridge stores it, so it runs with no computer on. Default window: dusk to 23:00.
+
+## Recipes
+
+```sh
+everlights play "Hallows Eve"                     # built-in sequence now
+everlights set FF0000 00FF00 --effect twinkle=100 # ad-hoc colors now
+everlights off                                    # dark
+everlights clear                                  # back to the calendar
+
+everlights sequence add "Candy Cane" FF0000 FF0000 FFFFFF FFFFFF --effect chase=60
+everlights sequence update "Candy Cane" FF0000 00FF00 --effect chase=60
+everlights sequence remove "Candy Cane"
+
+everlights calendar list --limit 30               # next 30 days (default 365)
+everlights calendar add 2026-12-01 Christmas "Candy Cane:30,Christmas" --until 2027-01-01
+everlights calendar add 2026-12-31 "New Year" "New Year's" --start 20:00 --end 01:00
+everlights calendar remove 2026-12-24 Christmas   # one night; removes the entry if it was the last
+```
+
+Dates and times use the machine's local time zone. An `--end` earlier than the start means the next morning. `--until` repeats nightly and stays correct across DST changes. Add `--json` to `list` commands for machine-readable output.
+
+### Ruby (same operations)
+
+```ruby
+require "everlights"
+el = Everlights::Client.new("192.168.1.50")   # or ENV["EVERLIGHTS_HOST"]
+el.play "Hallows Eve"; el.set "FF0000", "00FF00", effects: {twinkle: 100}; el.clear
+el.sequences.list("xmas"); el.sequences.add("Candy Cane", "FF0000", "FFFFFF", effects: {chase: 60}); el.sequences.remove("Candy Cane")
+el.calendar.list(limit: 30)                    # [{date:, start:, finish:, dusk:, name:, event_id:, sequences: [[name, secs]]}]
+el.calendar.add "2026-12-01", "Christmas", "Candy Cane:30,Christmas", through: "2027-01-01"  # or {"Candy Cane" => 30}
+el.calendar.add "2026-12-31", "New Year", ["New Year's"], start: "20:00", finish: "01:00"
+el.calendar.remove "2026-12-24", "Christmas"
+```
+
+## Sync (planning shows months ahead)
+
+When the user wants a recurring or seasonal plan ("Christmas every December", "Fridays in football season"), edit `config/everlights.yml` rather than adding calendar entries one by one. The format reference is `config/everlights.example.yml`.
+
+1. Edit `sequences:` or `schedule:`. Rules higher in the list win nights they share.
+2. Run `everlights sync --dry-run` and show the user the plan, including the Skipped section.
+3. Run `everlights sync` only after they confirm.
+
+Sync only changes what it created itself. Config problems abort before anything is written; fix every one it lists. Use `--adopt` only when the user says the state file was lost.
+
+## Unverified
+ (tell the user if it matters)
+
+- Whether "dusk" shows really start at dusk. The bridge stores a 17:00 placeholder, so they may start at 17:00. Use `--start` when the exact time matters.
+- What N means for each effect.
+- Whether a calendar entry overlapping another replaces it or conflicts. Check `calendar list` afterwards.
+- `calendar remove` on a night that isn't an entry's last edits the event with a PUT. The API spec has it; not yet tried on the bridge.

metadata

@@ -0,0 +1,51 @@
+--- !ruby/object:Gem::Specification
+name: everlights
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Ricky Chilcott
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: 'Control EverLights permanent lights over the LAN: show colors, manage
+  sequences, and schedule shows ahead on the bridge''s calendar. Unofficial; stdlib
+  only.'
+email: ricky@rickychilcott.com
+executables:
+- everlights
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- exe/everlights
+- lib/everlights.rb
+- lib/everlights/sync.rb
+- skills/everlights/SKILL.md
+homepage: https://github.com/rickychilcott/everlights
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/rickychilcott/everlights
+  bug_tracker_uri: https://github.com/rickychilcott/everlights/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.7.1
+specification_version: 4
+summary: Client and CLI for the EverLights Smart Lights Bridge local API
+test_files: []