smart-home-engine 0.0.1 → 0.10.4

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) Sebastian Raff <hq@ccu.io> (https://github.com/hobbyquaker)
+
+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.

package/README.md

@@ -0,0 +1,76 @@
+# she - smart home engine
+
+[![License][mit-badge]][mit-url]
+
+> [!WARNING]
+> **This project is under heavy development and many features are not working yet.** The API is changing frequently and there are no stability guarantees yet.
+
+Your home, your rules - written in plain JavaScript.
+
+**she** is a Node.js daemon that loads your `.js` scripts into a sandboxed VM and wires them up to MQTT, Matter, and everything else your smart home throws at them. No cloud, no lock-in, no YAML sprawl, no opinionated bloated schemata. Just scripts that do exactly what you tell them.
+
+- **Scripts** — Monaco-based Script IDE, AI assistant, git integration, autocompletion, ...
+- **MQTT** — subscribe, publish, react to state changes with wildcards, conditions, and delays
+- **Matter** — pair and control Matter devices directly from your scripts
+- **sheDB** — a lightweight document store with map/reduce views, right in the daemon
+- **Scheduler** — cron expressions and solar events (`sunrise`, `sunset`, …) in one call
+- **Web UI** — script editor, package manager, MQTT browser, Matter device manager, sheDB-Frontend, log viewer
+
+## Motivation
+
+She is built around a simple idea: home automation should stay understandable, even as it grows. Instead of collecting adapters, bindings, integrations, and configuration layers, you work directly with devices, events, and logic. The result is a system that scales with your home without turning into a project of its own.
+
+At some point every smart home platform starts promising simplicity and ends up teaching you its own ecosystem. She takes a different approach. It's built around devices, messages, and automation logic - not around ever-growing collections of adapters, bindings, and abstractions.
+
+Spend your time automating your home, not maintaining your automation software. Less clicking through configuration screens, fewer plugins talking to plugins, and no need for YAML archaeology when something stops working. Just a straightforward path from devices to automations, built on open standards and designed for people who prefer understanding their system over managing it.
+
+The ideas behind **she** are the result of more than a decade of building smart home software. I started publishing home automation projects on GitHub in 2012 with ccu.io and later initiated the ioBroker project before leaving it in 2014. Around the same time, I created [mqtt-scripts](https://github.com/hobbyquaker/mqtt-scripts), which has been running my own home automation ever since. Over the years I have continued working professionally in the smart home industry.
+
+Recently, while experimenting with GitHub Copilot, I started modernizing parts of my existing software stack. What began as a small refactoring exercise quickly evolved into a bigger idea: replacing my twelve-year-old automation engine with a modern successor. The result is **she** - a combination of the proven concepts from mqtt-scripts, the event-sourced architecture of mqttDB, and a built-in Matter controller. A system that embraces open standards, integrates the growing Matter ecosystem, and remains true to the principles that made mqtt-scripts reliable enough to run a home for more than a decade.
+
+The goal is simple: a smart home that remains understandable years later. No migration-guide marathons, no plugin jungles, no configuration archaeology. Just automation infrastructure that grows with your home instead of growing into a hobby of its own.
+
+## Docs
+
+| | |
+|---|---|
+| [Getting started](doc/getting-started.md) | Install, write your first script, configure |
+| [CLI reference](doc/cli.md) | All flags and environment variables |
+| [Sandbox API](doc/sandbox-api.md) | Everything available inside a script |
+| [HTTP API](doc/http-api.md) | REST endpoints and WebSocket |
+| [sheDB](doc/db/README.md) | Embedded document store — script API, views, examples |
+| [Examples](doc/examples.md) | Real-world script patterns |
+
+## Quick look
+
+```js
+// lights.js
+
+// Follow a motion sensor
+she.mqtt.sub('home//hall/motion', { change: true }, (topic, val) => {
+    she.mqtt.set('home//hall/light', val ? 1 : 0);
+});
+
+// Solar schedule — no hardcoded times
+she.schedule('sunset',  () => she.mqtt.set('home//lights/outdoor', 1));
+she.schedule('sunrise', () => she.mqtt.set('home//lights/outdoor', 0));
+
+// Keep device metadata in sheDB
+she.db.set('hall/motion', { name: 'Hall PIR', location: 'hall' });
+```
+
+## Quick start
+
+```bash
+npm install -g smart-home-engine
+she
+```
+
+Then open **http://localhost:8080** and start writing.
+
+## License
+
+MIT © [Sebastian Raff](https://github.com/hobbyquaker)
+
+[mit-badge]: https://img.shields.io/badge/License-MIT-blue.svg?style=flat
+[mit-url]: LICENSE