smart-home-engine 1.21.0 → 1.34.3

package/service/she-servicectl

@@ -0,0 +1,638 @@
+#!/bin/sh
+# she-servicectl — the one privileged helper she uses to manage xyz2mqtt adapter
+# instances on a host (roadmap I4, decision SV-4). Installed to /usr/local/bin and
+# allowed for the she user (or the SSH user on remote hosts) via sudoers:
+#
+#   she ALL=(root) NOPASSWD: /usr/local/bin/she-servicectl
+#
+# Everything she can do on this host is what this script allows. Every argument is
+# validated against a fixed pattern before anything is executed; free-form data
+# (env files, install options) travels on stdin, never on the command line.
+#
+# Adapters are npm packages built on mqtt-interfaces-core: a template unit
+# /etc/systemd/system/<adapter>@.service (fingerprint: an EnvironmentFile line for
+# /etc/<adapter>/%i.env — units written by older cores lack the shared broker.env
+# line, "list" reports that per adapter), instances = /etc/<adapter>/<instance>.env,
+# a wrapper or symlink /usr/local/bin/<adapter>.
+#
+#   she-servicectl version
+#   she-servicectl list                                            (adapters = template units + npm packages with mqttInterfaces)
+#   she-servicectl unit   <adapter> <instance> start|stop|restart|enable|disable|status
+#   she-servicectl logs   <adapter> <instance> [-n N] [--follow]
+#   she-servicectl env    <adapter> <instance> read|write        (write: file on stdin)
+#   she-servicectl broker-env read|write                          (write: file on stdin)
+#   she-servicectl schema <adapter>
+#   she-servicectl install   <adapter> <instance>                 (options as KEY=VALUE lines on stdin)
+#   she-servicectl uninstall <adapter> <instance>
+#   she-servicectl npm    <adapter> version|origin|install|update
+#   she-servicectl files  <adapter> <instance>                     JSON listing of /etc/<adapter>/ and /var/lib/<adapter>/<instance>/
+#   she-servicectl file   <adapter> <instance> read|write <path>  a file inside those two directories (write: content on stdin)
+#   she-servicectl asset  <adapter> <relpath>                      a file shipped in the adapter package (example, schema)
+#   she-servicectl self-update                                     replace this script with the one on stdin (she ships it)
+#   she-servicectl remove-key                                      drop the public key on stdin from the calling user's authorized_keys
+#   she-servicectl teardown [--force]                              remove she from this host: that key, the sudoers rule, this script,
+#                                                                  the she-services user (adapters and their instances stay untouched)
+#
+# Legacy units: an adapter installed the pre-core way runs as a plain <adapter>.service with its
+# env file in /etc/default/<adapter>. "list" reports them under "legacy"; unit/logs/env accept "-"
+# as the instance for that unit; "migrate <adapter> <name>" turns it into <adapter>@<name> via the
+# adapter's own --install (which carries state such as pairing keys over) and retires the old unit.
+
+set -eu
+
+VERSION=8
+BROKER_ENV=/etc/mqtt-interfaces/broker.env
+UNIT_DIR=/etc/systemd/system
+
+die() { printf 'she-servicectl: %s\n' "$*" >&2; exit 2; }
+
+# ── validation ──────────────────────────────────────────────────────────────────
+
+valid_adapter() { printf '%s' "$1" | grep -Eq '^[a-z0-9][a-z0-9._-]{0,213}$'; }
+valid_instance() { printf '%s' "$1" | grep -Eq '^[A-Za-z0-9_.-]{1,64}$'; }
+
+# a template unit written by mqtt-interfaces-core's installer: per-instance env file under /etc/<adapter>/
+installed_adapter() {
+    [ -f "$UNIT_DIR/$1@.service" ] && grep -Eq "^EnvironmentFile=-?/etc/$1/%i\.env" "$UNIT_DIR/$1@.service"
+}
+
+# does the template unit read the shared /etc/mqtt-interfaces/broker.env? (cores since 0.1 write it; older units do not)
+unit_reads_broker_env() {
+    grep -q "mqtt-interfaces/broker.env" "$UNIT_DIR/$1@.service" 2>/dev/null && printf 'true' || printf 'false'
+}
+
+need_adapter() {
+    valid_adapter "$1" || die "invalid adapter name: $1"
+}
+need_installed() {
+    need_adapter "$1"
+    installed_adapter "$1" || die "no mqtt-interfaces template unit for $1"
+}
+need_instance() {
+    valid_instance "$1" || die "invalid instance name: $1"
+}
+
+# a plain <adapter>.service of an npm-installed adapter (pre-core layout)
+legacy_unit() {
+    [ -f "$UNIT_DIR/$1.service" ] || return 1
+    grep -Eq "(/node_modules/$1/|/usr/local/bin/$1( |$))" "$UNIT_DIR/$1.service" 2>/dev/null
+}
+# the env file of a legacy unit: its EnvironmentFile= (leading - stripped), default /etc/default/<adapter>;
+# only /etc/default/<adapter> or something inside /etc/<adapter>/ is accepted
+legacy_env_file() {
+    f=$(sed -n 's/^EnvironmentFile=-\{0,1\}//p' "$UNIT_DIR/$1.service" 2>/dev/null | head -n 1)
+    [ -n "$f" ] || f="/etc/default/$1"
+    case "$f" in "/etc/default/$1"|"/etc/$1/"*) printf '%s' "$f" ;; *) return 1 ;; esac
+}
+# template instance (default) or, with instance "-", the legacy unit
+unit_name() {
+    if [ "$2" = "-" ]; then
+        legacy_unit "$1" || die "no legacy unit $1.service"
+        printf '%s.service' "$1"
+    else
+        need_installed "$1"; need_instance "$2"
+        printf '%s@%s.service' "$1" "$2"
+    fi
+}
+need_any() {
+    need_adapter "$1"
+    installed_adapter "$1" || legacy_unit "$1" || die "no mqtt-interfaces unit for $1"
+}
+
+# ── helpers ─────────────────────────────────────────────────────────────────────
+
+json_escape() {
+    # minimal JSON string escaping for the few free-form values (timestamps, paths)
+    printf '%s' "$1" | sed -e 's/\\/\\\\/g' -e 's/"/\\"/g' | tr -d '\n\r'
+}
+
+# the adapter's command: /usr/local/bin/<adapter> (wrapper or symlink), else PATH
+adapter_cmd() {
+    if [ -x "/usr/local/bin/$1" ]; then
+        printf '/usr/local/bin/%s' "$1"
+    else
+        command -v "$1" 2>/dev/null || return 1
+    fi
+}
+
+# node the adapter runs with (SV-17): parsed from a wrapper script, else PATH
+adapter_node() {
+    cmd=$(adapter_cmd "$1") || { command -v node; return; }
+    node=""
+    if [ ! -L "$cmd" ]; then
+        node=$(grep -o '[^" ]*/bin/node' "$cmd" 2>/dev/null | head -n 1 || true)
+    fi
+    if [ -n "$node" ] && [ -x "$node" ]; then
+        printf '%s' "$node"
+    else
+        command -v node
+    fi
+}
+
+adapter_npm() {
+    node=$(adapter_node "$1")
+    npm="$(dirname "$node")/npm"
+    if [ -x "$npm" ]; then printf '%s' "$npm"; else command -v npm; fi
+}
+
+# where the adapter's package lives (resolved through wrapper/symlink)
+adapter_dir() {
+    cmd=$(adapter_cmd "$1") || return 1
+    if [ -L "$cmd" ]; then
+        target=$(readlink -f "$cmd")
+    else
+        target=$(grep -o '[^" ]*\.js' "$cmd" 2>/dev/null | head -n 1 || true)
+        [ -n "$target" ] || target="$cmd"
+    fi
+    d=$(dirname "$target")
+    while [ "$d" != "/" ]; do
+        if [ -f "$d/package.json" ]; then printf '%s' "$d"; return 0; fi
+        d=$(dirname "$d")
+    done
+    return 1
+}
+
+adapter_version() {
+    cmd=$(adapter_cmd "$1") || { printf 'null'; return; }
+    v=$("$cmd" --version 2>/dev/null | tail -n 1 || true)
+    if [ -n "$v" ]; then printf '"%s"' "$(json_escape "$v")"; else printf 'null'; fi
+}
+
+# registry: the global npm tree knows the package; manual: deployed by tarball (SV-16)
+# registry: installed with npm install -g. Older npms list global packages in the hidden lockfile of the
+# global root; npm 11 keeps none there. A manual deploy (tarball extracted by deploy.sh, then
+# npm install --prefix <dir>) leaves a hidden lockfile *inside* the package — a registry install does not.
+adapter_origin() {
+    npm=$(adapter_npm "$1")
+    root=$("$npm" root -g 2>/dev/null || true)
+    lock="$root/.package-lock.json"
+    if [ -n "$root" ] && [ -f "$lock" ] && grep -q "\"node_modules/$1\"" "$lock"; then
+        printf 'registry'
+        return
+    fi
+    dir=$(adapter_dir "$1" 2>/dev/null || true)
+    if [ -n "$dir" ] && [ -f "$dir/node_modules/.package-lock.json" ]; then
+        printf 'manual'
+    else
+        printf 'registry'
+    fi
+}
+
+adapter_user() {
+    if id -u "$1" >/dev/null 2>&1; then printf '%s' "$1"; else printf 'root'; fi
+}
+
+# absolute path without control characters or ..
+valid_path() { printf '%s' "$1" | grep -Eq '^/[^[:cntrl:]]+$' && ! printf '%s' "$1" | grep -q '\.\.'; }
+
+# the two directories she may read and write instance files in
+managed_dir() {
+    case "$3" in
+        etc) printf '/etc/%s' "$1" ;;
+        state) printf '/var/lib/%s/%s' "$1" "$2" ;;
+    esac
+}
+
+# is $3 (an existing file, or a new file whose directory exists) inside the managed dirs of $1/$2?
+inside_managed() {
+    if [ -e "$3" ]; then
+        real=$(realpath "$3" 2>/dev/null) || return 1
+    else
+        pdir=$(realpath "$(dirname "$3")" 2>/dev/null) || return 1
+        real="$pdir/$(basename "$3")"
+    fi
+    for d in "$(managed_dir "$1" "$2" etc)" "$(managed_dir "$1" "$2" state)"; do
+        rd=$(realpath "$d" 2>/dev/null) || continue
+        case "$real" in "$rd"/*) return 0 ;; esac
+    done
+    return 1
+}
+
+# validate an env file on stdin (KEY=VALUE, comments, blank lines) into $1
+read_env_stdin() {
+    tmp=$1
+    cat > "$tmp"
+    if grep -Evq '^([A-Z][A-Z0-9_]*=.*|#.*|[[:space:]]*)$' "$tmp"; then
+        rm -f "$tmp"
+        die "env file: only KEY=VALUE lines and comments are allowed"
+    fi
+}
+
+# ── commands ────────────────────────────────────────────────────────────────────
+
+# ── adapters installed with npm but without a template unit yet ─────────────────
+# (a catalog install is `npm install -g <adapter>`; the unit appears with the first `--install`)
+npm_roots() {
+    r=$(command -v npm >/dev/null 2>&1 && npm root -g 2>/dev/null || true)
+    printf '%s\n/usr/local/lib/node_modules\n' "$r" | grep -v '^$' | LC_ALL=C sort -u
+}
+npm_adapters() {
+    for root in $(npm_roots); do
+        for pkg in "$root"/*/package.json; do
+            [ -f "$pkg" ] || continue
+            a=$(basename "$(dirname "$pkg")")
+            valid_adapter "$a" || continue
+            grep -q '"mqttInterfaces"' "$pkg" 2>/dev/null || continue
+            adapter_cmd "$a" >/dev/null 2>&1 || continue
+            printf '%s\n' "$a"
+        done
+    done | LC_ALL=C sort -u
+}
+
+cmd_version() {
+    printf '%s\n' "$VERSION"
+}
+
+cmd_list() {
+    hostname=$(hostname 2>/dev/null || uname -n)
+    node=$(command -v node >/dev/null 2>&1 && node --version 2>/dev/null || true)
+    printf '{"helper":%s,"hostname":"%s","node":%s,"brokerEnv":%s,"adapters":[' \
+        "$VERSION" "$(json_escape "$hostname")" \
+        "$([ -n "$node" ] && printf '"%s"' "$node" || printf 'null')" \
+        "$([ -f "$BROKER_ENV" ] && printf 'true' || printf 'false')"
+    first=1
+    adapters=""
+    legacy=""
+    for unit in "$UNIT_DIR"/*.service; do
+        [ -f "$unit" ] || continue
+        a=$(basename "$unit" .service)
+        case "$a" in *@) continue ;; esac
+        valid_adapter "$a" || continue
+        legacy_unit "$a" || continue
+        installed_adapter "$a" && continue # the template unit lists it below
+        legacy="$legacy $a"
+    done
+    for unit in "$UNIT_DIR"/*@.service $(for a in $legacy; do printf '%s ' "$UNIT_DIR/$a@.service.legacy-placeholder"; done); do
+        case "$unit" in *.legacy-placeholder) a=$(basename "$unit" @.service.legacy-placeholder) ;; *) [ -f "$unit" ] || continue; a=$(basename "$unit" @.service); installed_adapter "$a" || continue ;; esac
+        valid_adapter "$a" || continue
+        adapters="$adapters $a"
+        [ $first -eq 1 ] || printf ','
+        first=0
+        dir=$(adapter_dir "$a" 2>/dev/null || true)
+        printf '{"name":"%s","version":%s,"origin":"%s","path":%s,"node":"%s","brokerEnv":%s}' \
+            "$a" "$(adapter_version "$a")" "$(adapter_origin "$a")" \
+            "$([ -n "$dir" ] && printf '"%s"' "$(json_escape "$dir")" || printf 'null')" \
+            "$(json_escape "$(adapter_node "$a")")" "$(unit_reads_broker_env "$a")"
+    done
+    for a in $(npm_adapters); do
+        case " $adapters " in *" $a "*) continue ;; esac
+        [ $first -eq 1 ] || printf ','
+        first=0
+        dir=$(adapter_dir "$a" 2>/dev/null || true)
+        printf '{"name":"%s","version":%s,"origin":"%s","path":%s,"node":"%s","brokerEnv":false,"unit":false}' \
+            "$a" "$(adapter_version "$a")" "$(adapter_origin "$a")" \
+            "$([ -n "$dir" ] && printf '"%s"' "$(json_escape "$dir")" || printf 'null')" \
+            "$(json_escape "$(adapter_node "$a")")"
+    done
+    printf '],"legacy":['
+    first=1
+    seenlegacy=""
+    for a in $legacy $(for a in $adapters; do legacy_unit "$a" && printf '%s ' "$a"; done | tr ' ' '\n' | LC_ALL=C sort -u); do
+        legacy_unit "$a" || continue
+        case " $seenlegacy " in *" $a "*) continue ;; esac
+        seenlegacy="$seenlegacy $a"
+        [ $first -eq 1 ] || printf ','
+        first=0
+        show=$(systemctl show -p ActiveState -p SubState -p UnitFileState -p ExecMainStartTimestamp -p NRestarts "$a.service" 2>/dev/null || true)
+        active=$(printf '%s\n' "$show" | sed -n 's/^ActiveState=//p')
+        sub=$(printf '%s\n' "$show" | sed -n 's/^SubState=//p')
+        uf=$(printf '%s\n' "$show" | sed -n 's/^UnitFileState=//p')
+        since=$(printf '%s\n' "$show" | sed -n 's/^ExecMainStartTimestamp=//p')
+        nr=$(printf '%s\n' "$show" | sed -n 's/^NRestarts=//p')
+        envf=$(legacy_env_file "$a" 2>/dev/null || true)
+        printf '{"adapter":"%s","unit":"%s.service","active":"%s","sub":"%s","unitFile":"%s","since":"%s","restarts":%s,"envFile":%s}' \
+            "$a" "$a" "$(json_escape "$active")" "$(json_escape "$sub")" "$(json_escape "$uf")" \
+            "$(json_escape "$since")" "${nr:-0}" "$([ -n "$envf" ] && printf '"%s"' "$(json_escape "$envf")" || printf 'null')"
+    done
+    printf '],"instances":['
+    first=1
+    for a in $adapters; do
+        installed_adapter "$a" || continue
+        for envf in "/etc/$a"/*.env; do
+            [ -f "$envf" ] || continue
+            i=$(basename "$envf" .env)
+            valid_instance "$i" || continue
+            [ $first -eq 1 ] || printf ','
+            first=0
+            show=$(systemctl show -p ActiveState -p SubState -p UnitFileState -p ExecMainStartTimestamp -p NRestarts "$a@$i.service" 2>/dev/null || true)
+            active=$(printf '%s\n' "$show" | sed -n 's/^ActiveState=//p')
+            sub=$(printf '%s\n' "$show" | sed -n 's/^SubState=//p')
+            uf=$(printf '%s\n' "$show" | sed -n 's/^UnitFileState=//p')
+            since=$(printf '%s\n' "$show" | sed -n 's/^ExecMainStartTimestamp=//p')
+            nr=$(printf '%s\n' "$show" | sed -n 's/^NRestarts=//p')
+            printf '{"adapter":"%s","instance":"%s","active":"%s","sub":"%s","unitFile":"%s","since":"%s","restarts":%s}' \
+                "$a" "$i" "$(json_escape "$active")" "$(json_escape "$sub")" "$(json_escape "$uf")" \
+                "$(json_escape "$since")" "${nr:-0}"
+        done
+    done
+    printf ']}\n'
+}
+
+cmd_unit() {
+    [ $# -eq 3 ] || die "usage: unit <adapter> <instance|-> <action>"
+    need_adapter "$1"
+    u=$(unit_name "$1" "$2")
+    case "$3" in
+        start|stop|restart|enable|disable) systemctl "$3" "$u" ;;
+        status) systemctl show -p ActiveState -p SubState -p UnitFileState -p ExecMainStartTimestamp -p NRestarts -p MainPID "$u" ;;
+        *) die "unknown unit action: $3" ;;
+    esac
+}
+
+cmd_logs() {
+    [ $# -ge 2 ] || die "usage: logs <adapter> <instance|-> [-n N] [--follow]"
+    need_adapter "$1"
+    unit=$(unit_name "$1" "$2"); shift 2
+    lines=200; follow=0
+    while [ $# -gt 0 ]; do
+        case "$1" in
+            -n) shift; printf '%s' "${1:-}" | grep -Eq '^[0-9]{1,5}$' || die "-n needs a number"; lines=$1 ;;
+            --follow) follow=1 ;;
+            *) die "unknown logs option: $1" ;;
+        esac
+        shift
+    done
+    if [ $follow -eq 1 ]; then
+        exec journalctl -u "$unit" -n "$lines" -o json --no-pager -f
+    else
+        exec journalctl -u "$unit" -n "$lines" -o json --no-pager
+    fi
+}
+
+cmd_env() {
+    [ $# -eq 3 ] || die "usage: env <adapter> <instance|-> read|write"
+    need_adapter "$1"
+    if [ "$2" = "-" ]; then
+        legacy_unit "$1" || die "no legacy unit $1.service"
+        f=$(legacy_env_file "$1") || die "legacy env file of $1 is outside /etc/default and /etc/$1"
+    else
+        need_installed "$1"; need_instance "$2"
+        f="/etc/$1/$2.env"
+    fi
+    case "$3" in
+        read)
+            [ -f "$f" ] || die "no such instance: $1@$2"
+            cat "$f" ;;
+        write)
+            [ -f "$f" ] || die "no such instance: $1@$2 (use install)"
+            tmp=$(mktemp "$(dirname "$f")/.$(basename "$f").XXXXXX")
+            read_env_stdin "$tmp"
+            cp -p "$f" "$f.bak"
+            chown "root:$(adapter_user "$1")" "$tmp"
+            chmod 0640 "$tmp"
+            mv "$tmp" "$f"
+            printf 'wrote %s\n' "$f" ;;
+        *) die "unknown env action: $3" ;;
+    esac
+}
+
+cmd_broker_env() {
+    [ $# -eq 1 ] || die "usage: broker-env read|write"
+    case "$1" in
+        read)
+            if [ -f "$BROKER_ENV" ]; then cat "$BROKER_ENV"; fi ;;
+        write)
+            mkdir -p "$(dirname "$BROKER_ENV")"
+            tmp=$(mktemp "$(dirname "$BROKER_ENV")/.broker.env.XXXXXX")
+            read_env_stdin "$tmp"
+            [ -f "$BROKER_ENV" ] && cp -p "$BROKER_ENV" "$BROKER_ENV.bak"
+            chown root:root "$tmp"
+            chmod 0640 "$tmp"
+            mv "$tmp" "$BROKER_ENV"
+            printf 'wrote %s\n' "$BROKER_ENV" ;;
+        *) die "unknown broker-env action: $1" ;;
+    esac
+}
+
+cmd_schema() {
+    [ $# -eq 1 ] || die "usage: schema <adapter>"
+    need_adapter "$1"
+    cmd=$(adapter_cmd "$1") || die "adapter not installed: $1"
+    exec "$cmd" --config-schema
+}
+
+cmd_install() {
+    [ $# -eq 2 ] || die "usage: install <adapter> <instance>  (KEY=VALUE lines on stdin)"
+    need_adapter "$1"; need_instance "$2"
+    cmd=$(adapter_cmd "$1") || die "adapter not installed: $1"
+    tmp=$(mktemp)
+    read_env_stdin "$tmp"
+    # options become environment variables; the core reads <PREFIX>_* as defaults and
+    # --install writes them to /etc/<adapter>/<instance>.env
+    set -a
+    # shellcheck disable=SC1090
+    . "$tmp"
+    set +a
+    rm -f "$tmp"
+    exec "$cmd" --install --name "$2"
+}
+
+# legacy <adapter>.service → <adapter>@<name>: the adapter's own --install with the legacy env as
+# environment (it carries state such as pairing keys over), then the old unit is retired
+cmd_migrate() {
+    [ $# -eq 2 ] || die "usage: migrate <adapter> <name>"
+    need_adapter "$1"; need_instance "$2"
+    legacy_unit "$1" || die "no legacy unit $1.service"
+    cmd=$(adapter_cmd "$1") || die "adapter not installed: $1"
+    envf=$(legacy_env_file "$1") || die "legacy env file of $1 is outside /etc/default and /etc/$1"
+    [ -f "/etc/$1/$2.env" ] && die "instance $1@$2 already exists"
+    if [ -f "$envf" ]; then
+        set -a
+        # shellcheck disable=SC1090
+        . "$envf"
+        set +a
+    fi
+    "$cmd" --install --name "$2" || die "$1 --install failed"
+    systemctl disable --now "$1.service" >/dev/null 2>&1 || true
+    mv "$UNIT_DIR/$1.service" "$UNIT_DIR/$1.service.migrated"
+    [ -f "$envf" ] && mv "$envf" "$envf.migrated"
+    systemctl daemon-reload
+    printf 'migrated %s.service to %s@%s.service; old unit and env kept as .migrated\n' "$1" "$1" "$2"
+}
+
+cmd_uninstall() {
+    [ $# -eq 2 ] || die "usage: uninstall <adapter> <instance>"
+    need_installed "$1"; need_instance "$2"
+    cmd=$(adapter_cmd "$1") || die "adapter not installed: $1"
+    exec "$cmd" --uninstall --name "$2"
+}
+
+cmd_files() {
+    [ $# -eq 2 ] || die "usage: files <adapter> <instance>"
+    need_installed "$1"; need_instance "$2"
+    tmp=$(mktemp)
+    for d in "$(managed_dir "$1" "$2" etc)" "$(managed_dir "$1" "$2" state)"; do
+        [ -d "$d" ] || continue
+        # top level plus one level of subdirectories; no dotfiles
+        find "$d" -mindepth 1 -maxdepth 2 -not -name '.*' 2>/dev/null >> "$tmp"
+    done
+    printf '['
+    LC_ALL=C sort "$tmp" | while IFS= read -r f; do
+        [ -n "$f" ] || continue
+        if [ -d "$f" ]; then kind=dir; size=0; else kind=file; size=$(wc -c < "$f" | tr -d ' '); fi
+        mtime=$(stat -c %Y "$f" 2>/dev/null || stat -f %m "$f" 2>/dev/null || echo 0)
+        if [ -s "$tmp.sep" ]; then printf ','; else printf 1 > "$tmp.sep"; fi
+        printf '{"path":"%s","kind":"%s","size":%s,"mtime":%s}' "$(json_escape "$f")" "$kind" "$size" "$mtime"
+    done
+    rm -f "$tmp" "$tmp.sep"
+    printf ']\n'
+}
+
+cmd_file() {
+    [ $# -eq 4 ] || die "usage: file <adapter> <instance> read|write <path>"
+    need_installed "$1"; need_instance "$2"
+    valid_path "$4" || die "invalid path: $4"
+    inside_managed "$1" "$2" "$4" || die "path is outside /etc/$1 and /var/lib/$1/$2: $4"
+    case "$3" in
+        read)
+            [ -f "$4" ] || die "no such file: $4"
+            cat "$4" ;;
+        write)
+            dir=$(dirname "$4")
+            [ -d "$dir" ] || die "directory does not exist: $dir"
+            tmp=$(mktemp "$dir/.she.XXXXXX")
+            cat > "$tmp"
+            if [ -f "$4" ]; then
+                cp -p "$4" "$4.bak"
+                chown --reference="$4" "$tmp" 2>/dev/null || true
+                chmod --reference="$4" "$tmp" 2>/dev/null || true
+            else
+                chown "root:$(adapter_user "$1")" "$tmp"
+                chmod 0640 "$tmp"
+            fi
+            mv "$tmp" "$4"
+            printf 'wrote %s\n' "$4" ;;
+        *) die "unknown file action: $3" ;;
+    esac
+}
+
+cmd_asset() {
+    [ $# -eq 2 ] || die "usage: asset <adapter> <relpath>"
+    need_adapter "$1"
+    printf '%s' "$2" | grep -Eq '^[A-Za-z0-9_][A-Za-z0-9_./-]*$' || die "invalid asset path: $2"
+    printf '%s' "$2" | grep -q '\.\.' && die "invalid asset path: $2"
+    dir=$(adapter_dir "$1") || die "adapter not installed: $1"
+    f="$dir/$2"
+    [ -f "$f" ] || die "no such asset: $2"
+    real=$(realpath "$f"); rd=$(realpath "$dir")
+    case "$real" in "$rd"/*) ;; *) die "invalid asset path: $2" ;; esac
+    cat "$f"
+}
+
+# she pushes a newer copy of this script through the existing sudo rule: checked before it replaces us
+cmd_self_update() {
+    [ $# -eq 0 ] || die "usage: self-update  (new script on stdin)"
+    self=$(realpath "$0" 2>/dev/null) || self=/usr/local/bin/she-servicectl
+    tmp=$(mktemp)
+    cat > "$tmp"
+    if ! head -n 3 "$tmp" | grep -q '^# she-servicectl'; then rm -f "$tmp"; die "self-update: not a she-servicectl script"; fi
+    if ! grep -Eq '^VERSION=[0-9]+$' "$tmp"; then rm -f "$tmp"; die "self-update: no VERSION line"; fi
+    if ! sh -n "$tmp" 2>/dev/null; then rm -f "$tmp"; die "self-update: syntax error in the new script"; fi
+    newver=$(sed -n 's/^VERSION=\([0-9]*\)$/\1/p' "$tmp" | head -n 1)
+    cp -p "$self" "$self.bak" 2>/dev/null || true
+    install -m 755 -o root -g root "$tmp" "$self"
+    rm -f "$tmp"
+    printf 'she-servicectl updated %s -> %s at %s\n' "$VERSION" "$newver" "$self"
+}
+
+# ── removing she from this host ─────────────────────────────────────────────────
+# The account she logs in as is the sudo caller (root when she connects as root).
+caller_user() { printf '%s' "${SUDO_USER:-$(id -un)}"; }
+key_count() { grep -cE '^[^#[:space:]]' "$1" 2>/dev/null || true; }
+
+# drop every authorized_keys line of user $1 whose key material equals the key in file $2;
+# sets REMAINING to the number of keys left
+remove_key_lines() {
+    home=$(getent passwd "$1" | cut -d: -f6)
+    [ -n "$home" ] || die "no home directory for $1"
+    auth="$home/.ssh/authorized_keys"
+    keymat=$(awk 'NF >= 2 && $1 ~ /^(ssh-|ecdsa-|sk-)/ { print $2; exit }' "$2")
+    [ -n "$keymat" ] || die "not a public key"
+    if [ ! -f "$auth" ]; then REMAINING=0; printf 'no authorized_keys for %s, nothing to remove\n' "$1"; return 0; fi
+    before=$(key_count "$auth")
+    tmp=$(mktemp)
+    awk -v k="$keymat" '{ keep = 1; for (i = 1; i <= NF; i++) if ($i == k) keep = 0 } keep' "$auth" > "$tmp"
+    cat "$tmp" > "$auth"    # keeps owner and mode
+    rm -f "$tmp"
+    REMAINING=$(key_count "$auth")
+    printf 'removed %s key(s) from %s, %s remaining\n' "$((before - REMAINING))" "$auth" "$REMAINING"
+}
+
+cmd_remove_key() {
+    [ $# -eq 0 ] || die "usage: remove-key  (public key on stdin)"
+    tmp=$(mktemp); cat > "$tmp"
+    remove_key_lines "$(caller_user)" "$tmp"
+    rm -f "$tmp"
+}
+
+cmd_teardown() {
+    force=0
+    if [ $# -eq 1 ] && [ "$1" = "--force" ]; then force=1; elif [ $# -ne 0 ]; then die "usage: teardown [--force]  (she's public key on stdin, may be empty)"; fi
+    user=$(caller_user)
+    self=$(realpath "$0" 2>/dev/null) || self=/usr/local/bin/she-servicectl
+    REMAINING=0
+    tmp=$(mktemp); cat > "$tmp"
+    if grep -q . "$tmp"; then remove_key_lines "$user" "$tmp"; fi
+    rm -f "$tmp"
+    if [ "$user" != root ] && [ "$REMAINING" -gt 0 ] && [ $force -eq 0 ]; then
+        printf 'she-servicectl: teardown: %s other key(s) still in the authorized_keys of %s — another she instance may manage this host; remove everything anyway with --force\n' "$REMAINING" "$user" >&2
+        exit 3
+    fi
+    # sudoers: a file that allows nothing but the helper goes away, any other file loses the helper line
+    for f in /etc/sudoers.d/*; do
+        [ -f "$f" ] || continue
+        grep -qF "$self" "$f" || continue
+        if grep -vE '^[[:space:]]*(#|$)' "$f" | grep -qvF "$self"; then
+            tmp=$(mktemp); grep -vF "$self" "$f" > "$tmp"; cat "$tmp" > "$f"; rm -f "$tmp"
+            printf 'removed the she-servicectl line from %s\n' "$f"
+        else
+            rm -f "$f"; printf 'removed %s\n' "$f"
+        fi
+    done
+    # the she-services account is the bootstrap script's; no other account is ever removed
+    if [ "$user" = she-services ] && id she-services >/dev/null 2>&1; then
+        userdel -r -f she-services 2>/dev/null || userdel -f she-services
+        printf 'removed user she-services and its home directory\n'
+    fi
+    rm -f "$self.bak" "$self"
+    printf 'removed %s\n' "$self"
+}
+
+cmd_npm() {
+    [ $# -eq 2 ] || die "usage: npm <adapter> version|origin|install|update"
+    need_adapter "$1"
+    case "$2" in
+        version) adapter_version "$1"; printf '\n' ;;
+        origin) adapter_origin "$1"; printf '\n' ;;
+        install|update)
+            npm=$(adapter_npm "$1")
+            node=$(adapter_node "$1")
+            PATH="$(dirname "$node"):$PATH" exec "$npm" install -g "$1@latest" --no-audit --no-fund ;;
+        *) die "unknown npm action: $2" ;;
+    esac
+}
+
+# ── dispatch ────────────────────────────────────────────────────────────────────
+
+[ $# -ge 1 ] || die "usage: she-servicectl <command> …"
+c=$1; shift
+case "$c" in
+    version) cmd_version "$@" ;;
+    list) cmd_list "$@" ;;
+    unit) cmd_unit "$@" ;;
+    logs) cmd_logs "$@" ;;
+    env) cmd_env "$@" ;;
+    broker-env) cmd_broker_env "$@" ;;
+    schema) cmd_schema "$@" ;;
+    install) cmd_install "$@" ;;
+    uninstall) cmd_uninstall "$@" ;;
+    npm) cmd_npm "$@" ;;
+    files) cmd_files "$@" ;;
+    file) cmd_file "$@" ;;
+    asset) cmd_asset "$@" ;;
+    self-update) cmd_self_update "$@" ;;
+    migrate) cmd_migrate "$@" ;;
+    remove-key) cmd_remove_key "$@" ;;
+    teardown) cmd_teardown "$@" ;;
+    *) die "unknown command: $c" ;;
+esac

package/service/smart-home-engine.service

@@ -1,4 +1,4 @@
-[Unit]
+[Unit]
 Description=Smart Home Engine (she)
 Documentation=https://github.com/hobbyquaker/she
 After=network-online.target