@ouro.bot/cli 0.1.0-alpha.97 → 0.1.0-alpha.971

package/deploy/unraid/docker-man-template-xml.cjs

@@ -0,0 +1,105 @@
+"use strict"
+
+const { TextDecoder } = require("node:util")
+
+const DECLARATION = "<?xml version=\"1.0\"?>"
+const ROOT_OPEN = "<Container version=\"2\">"
+const ROOT_CLOSE = "</Container>"
+const NAME_START = /^[A-Za-z_]$/u
+const NAME_CHARACTER = /^[A-Za-z0-9_.:-]$/u
+const XML_WHITESPACE = /^[\t\n\r ]$/u
+const UTF8_DECODER = new TextDecoder("utf-8", { fatal: true })
+
+function decodeUtf8(value) {
+  if (typeof value === "string") return value
+  if (!(value instanceof Uint8Array)) throw new TypeError("DockerMan template bytes are invalid")
+  return UTF8_DECODER.decode(value)
+}
+
+function skipWhitespace(value, start) {
+  let index = start
+  while (XML_WHITESPACE.test(value[index] ?? "")) index += 1
+  return index
+}
+
+function readName(value, start) {
+  if (!NAME_START.test(value[start] ?? "")) return null
+  let index = start + 1
+  while (NAME_CHARACTER.test(value[index] ?? "")) index += 1
+  return { name: value.slice(start, index), index }
+}
+
+function readOpenTag(xml, start) {
+  if (xml[start] !== "<") return null
+  const parsedName = readName(xml, start + 1)
+  if (!parsedName) return null
+  const attributes = new Map()
+  let index = parsedName.index
+  while (index < xml.length) {
+    if (xml[index] === ">") return { name: parsedName.name, attributes: Object.fromEntries(attributes), form: "text", index: index + 1 }
+    if (xml.startsWith("/>", index)) return { name: parsedName.name, attributes: Object.fromEntries(attributes), form: "empty", index: index + 2 }
+    const whitespaceEnd = skipWhitespace(xml, index)
+    if (whitespaceEnd === index) return null
+    index = whitespaceEnd
+    if (xml[index] === ">" || xml.startsWith("/>", index)) continue
+    const attribute = readName(xml, index)
+    if (!attribute || attributes.has(attribute.name)) return null
+    index = skipWhitespace(xml, attribute.index)
+    if (xml[index] !== "=") return null
+    index = skipWhitespace(xml, index + 1)
+    if (xml[index] !== "\"") return null
+    const end = xml.indexOf("\"", index + 1)
+    if (end === -1) return null
+    const value = xml.slice(index + 1, end)
+    if (!/^[\x20-\x7E]*$/u.test(value) || value.includes("<") || value.includes("&")) return null
+    attributes.set(attribute.name, value)
+    index = end + 1
+  }
+  return null
+}
+
+function hasValidXmlCharacters(value) {
+  for (const character of value) {
+    const codePoint = character.codePointAt(0)
+    if (!(codePoint === 0x9 || codePoint === 0xA || codePoint === 0xD
+      || (codePoint >= 0x20 && codePoint <= 0xD7FF)
+      || (codePoint >= 0xE000 && codePoint <= 0xFFFD)
+      || (codePoint >= 0x10000 && codePoint <= 0x10FFFF))) return false
+  }
+  return true
+}
+
+// Canonical DockerMan dialect: exact declaration and Container root, flat leaf children, double-quoted ASCII attributes, and literal text without entities or auxiliary XML constructs.
+function parseDockerManTemplateXml(input) {
+  let xml
+  try { xml = decodeUtf8(input) } catch { return null }
+  if (!hasValidXmlCharacters(xml) || !xml.startsWith(DECLARATION)) return null
+  let index = skipWhitespace(xml, DECLARATION.length)
+  if (!xml.startsWith(ROOT_OPEN, index)) return null
+  index += ROOT_OPEN.length
+  const children = []
+  while (index < xml.length) {
+    index = skipWhitespace(xml, index)
+    if (xml.startsWith(ROOT_CLOSE, index)) {
+      index = skipWhitespace(xml, index + ROOT_CLOSE.length)
+      return index === xml.length ? { root: { name: "Container", attributes: { version: "2" } }, children } : null
+    }
+    const child = readOpenTag(xml, index)
+    if (!child) return null
+    index = child.index
+    if (child.form === "empty") {
+      children.push({ name: child.name, attributes: child.attributes, form: child.form, text: "" })
+      continue
+    }
+    const close = `</${child.name}>`
+    const end = xml.indexOf("<", index)
+    if (end === -1 || !xml.startsWith(close, end)) return null
+    const text = xml.slice(index, end)
+    if (text.includes("&") || text.includes("]]>")) return null
+    children.push({ name: child.name, attributes: child.attributes, form: child.form, text })
+    index = end + close.length
+  }
+  return null
+}
+
+module.exports = { decodeUtf8, parseDockerManTemplateXml }

package/deploy/unraid/install.sh

@@ -0,0 +1,274 @@
+#!/bin/bash
+# Ouro Butler installer for Unraid 7.2 or newer.
+#
+# Run it as root in the Unraid web terminal. Download it and read it first if you like:
+#   curl -fsSLo /tmp/ouro-butler-install.sh https://github.com/ourostack/ouroboros/releases/latest/download/install.sh
+#   bash /tmp/ouro-butler-install.sh
+#
+# What it does, in order (each step says what it is doing as it goes):
+#   1. checks this is Unraid 7.2+, as root, with Docker running and no Butler installed yet
+#   2. asks for your name, the Butler's name, a vault email, your Anthropic API key and your Telegram bot token
+#      (secrets are read with the terminal's echo off and never appear in a command line)
+#   3. pulls the Butler image and seeds the Butler's files under /mnt/user/appdata/ouro-butler
+#   4. creates the Butler's vault (you choose its unlock phrase) and stores the Anthropic key in it
+#   5. creates two Unraid API keys for the Butler (read-only, and read plus Docker update) and stores them in the vault
+#   6. finds your Telegram user id when you message the bot, then installs the root authority that holds the bot
+#      token and starts the Butler
+#
+# Options:
+#   --version <0.1.0-alpha.N>   install this release instead of the newest one
+#   --vault-server <url>        use your own Vaultwarden-compatible server instead of https://vault.ouro.bot
+#   --help                      print this header
+set -euo pipefail
+umask 077
+
+IMAGE_REPO=ghcr.io/ourostack/ouroboros-butler
+APPDATA=/mnt/user/appdata/ouro-butler
+RUNTIME=$APPDATA/runtime/.ouro-cli
+BUNDLE=$APPDATA/agent/sanctuary.ouro
+STAGE=$APPDATA/installer
+AUTHORITY=/mnt/user/appdata/ouro-authority
+EVENTS=/boot/config/custom/ouro-events
+CONTAINER=ouro-butler
+AGENT=sanctuary
+TTY=/dev/tty
+VERSION=""
+VAULT_SERVER=""
+
+say() { printf '\n== %s\n' "$*"; }
+ok() { printf '  ok   %s\n' "$*"; }
+die() { printf '\nSTOPPED: %s\n' "$*" >&2; exit 1; }
+
+ask() { # ask <variable> <prompt> [default]
+  local answer
+  printf '%s%s: ' "$2" "${3:+ [$3]}" > "$TTY"
+  IFS= read -r answer < "$TTY" || die "no answer read from the terminal"
+  printf -v "$1" '%s' "${answer:-${3:-}}"
+}
+
+ask_secret() { # ask_secret <variable> <prompt>
+  local answer saved
+  saved=$(stty -g < "$TTY")
+  printf '%s (input is hidden): ' "$2" > "$TTY"
+  stty -echo < "$TTY"
+  IFS= read -r answer < "$TTY" || { stty "$saved" < "$TTY"; die "no answer read from the terminal"; }
+  stty "$saved" < "$TTY"
+  printf '\n' > "$TTY"
+  printf -v "$1" '%s' "$answer"
+}
+
+confirm() { local reply; ask reply "$1 (y/n)" n; case "$reply" in y|Y|yes|YES) return 0 ;; *) return 1 ;; esac; }
+
+while (($# > 0)); do
+  case "$1" in
+    --version) VERSION="${2:?--version needs a value, for example 0.1.0-alpha.970}"; shift 2 ;;
+    --vault-server) VAULT_SERVER="${2:?--vault-server needs a URL}"; shift 2 ;;
+    --help|-h) sed -n '2,/^set -euo/p' "$0" | sed '$d; s/^# \{0,1\}//'; exit 0 ;;
+    *) die "unknown option $1 (see --help)" ;;
+  esac
+done
+
+# The ouro CLI from the Butler image, run against the Butler's own files as the Butler's user.
+ouro() {
+  docker run --rm --pull=never --network host --user 10001:10001 \
+    --mount "type=bind,src=$RUNTIME,dst=/home/ouro/.ouro-cli" \
+    --mount "type=bind,src=$BUNDLE,dst=/home/ouro/AgentBundles/$AGENT.ouro" \
+    --entrypoint node "$IMAGE" /opt/ouro/dist/heart/daemon/ouro-entry.js "$@"
+}
+ouro_stdin() {
+  docker run --rm -i --pull=never --network host --user 10001:10001 \
+    --mount "type=bind,src=$RUNTIME,dst=/home/ouro/.ouro-cli" \
+    --mount "type=bind,src=$BUNDLE,dst=/home/ouro/AgentBundles/$AGENT.ouro" \
+    --entrypoint node "$IMAGE" /opt/ouro/dist/heart/daemon/ouro-entry.js "$@"
+}
+ouro_interactive() {
+  docker run --rm -it --pull=never --network host --user 10001:10001 \
+    --mount "type=bind,src=$RUNTIME,dst=/home/ouro/.ouro-cli" \
+    --mount "type=bind,src=$BUNDLE,dst=/home/ouro/AgentBundles/$AGENT.ouro" \
+    --entrypoint node "$IMAGE" /opt/ouro/dist/heart/daemon/ouro-entry.js "$@" < "$TTY"
+}
+
+# Write a private file owned by the Butler's user from stdin.
+write_butler_file() {
+  local path=$1
+  cat > "$path.tmp.$$"
+  chown 10001:10001 "$path.tmp.$$"
+  chmod 0600 "$path.tmp.$$"
+  mv -f "$path.tmp.$$" "$path"
+}
+
+# ---------------------------------------------------------------------------------------------------------------
+say "1. checking this host"
+test "$(id -u)" = 0 || die "run this as root (the Unraid web terminal is root)"
+test -r "$TTY" || die "this installer needs a terminal for its questions; run it in the Unraid web terminal"
+test -r /etc/unraid-version || die "this is not Unraid (no /etc/unraid-version)"
+UNRAID_VERSION=$(sed -n 's/^version="\([0-9.]*\).*/\1/p' /etc/unraid-version)
+IFS=. read -r UNRAID_MAJOR UNRAID_MINOR _ <<< "$UNRAID_VERSION"
+if ((UNRAID_MAJOR < 7 || (UNRAID_MAJOR == 7 && UNRAID_MINOR < 2))); then die "Unraid $UNRAID_VERSION is too old; the Butler needs Unraid 7.2 or newer"; fi
+ok "Unraid $UNRAID_VERSION"
+command -v node >/dev/null || die "node is missing (Unraid 7.2 ships it at /usr/local/bin/node)"
+command -v unraid-api >/dev/null || die "unraid-api is missing (Unraid 7.2 ships it)"
+docker info >/dev/null 2>&1 || die "Docker is not running; start it in Settings > Docker"
+ok "node, unraid-api and Docker are available"
+! docker container inspect "$CONTAINER" >/dev/null 2>&1 || die "an $CONTAINER container already exists; this installer is for a first install (upgrades use the Butler's own upgrade path)"
+test ! -e "$AUTHORITY/active.json" || die "a Butler authority is already installed on this host"
+ok "no Butler installed yet"
+
+if test -z "$VERSION"; then
+  VERSION=$(node -e 'fetch("https://registry.npmjs.org/-/package/@ouro.bot/cli/dist-tags").then(r => r.json()).then(t => process.stdout.write(t.latest)).catch(() => process.exit(1))') \
+    || die "could not look up the newest Butler release; pass --version"
+fi
+[[ "$VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+(-[A-Za-z0-9.]+)?$ ]] || die "version $VERSION does not look like a release version"
+IMAGE=$IMAGE_REPO:$VERSION
+ok "installing Ouro Butler $VERSION"
+
+# ---------------------------------------------------------------------------------------------------------------
+say "2. a few questions"
+printf 'The Butler lives on this server and talks to you on Telegram. You can change any name later in\n%s/house/house.json.\n\n' "$BUNDLE" > "$TTY"
+ask OWNER_NAME "Your first name" ""
+test -n "$OWNER_NAME" || die "a name is needed so the Butler knows who it works for"
+ask BUTLER_NAME "What should the Butler call itself" "Butler"
+ask HOUSEHOLD_NAME "A name for this household or server" "$(hostname)"
+printf '\nThe Butler keeps its secrets in a Bitwarden-compatible vault. It gets its own vault account, so use an\nemail address no other Butler uses (for example you+butler@example.com). No mail is sent to it.\n' > "$TTY"
+ask VAULT_EMAIL "Vault account email" ""
+[[ "$VAULT_EMAIL" == *@*.* ]] || die "that does not look like an email address"
+printf '\nThe Butler thinks with Anthropic models. Create an API key at https://console.anthropic.com/settings/keys\n' > "$TTY"
+ask_secret ANTHROPIC_KEY "Anthropic API key"
+[[ "$ANTHROPIC_KEY" == sk-ant-* ]] || die "Anthropic API keys start with sk-ant-"
+printf '\nCreate a Telegram bot for the Butler: message @BotFather, send /newbot, and copy the token it gives you.\n' > "$TTY"
+ask_secret BOT_TOKEN "Telegram bot token"
+[[ "$BOT_TOKEN" =~ ^[0-9]+:[A-Za-z0-9_-]+$ ]] || die "that does not look like a Telegram bot token (digits, a colon, then letters)"
+BOT_INFO=$(TOKEN="$BOT_TOKEN" node -e '
+  fetch(`https://api.telegram.org/bot${process.env.TOKEN}/getMe`).then(r => r.json()).then(b => {
+    if (!b.ok) process.exit(2)
+    process.stdout.write(`${b.result.id}\t${b.result.username}`)
+  }).catch(() => process.exit(1))') || die "Telegram did not accept that bot token"
+BOT_USERNAME=${BOT_INFO#*$'\t'}
+ok "Telegram knows the bot @$BOT_USERNAME"
+
+# ---------------------------------------------------------------------------------------------------------------
+say "3. Butler image and files"
+docker pull "$IMAGE" >/dev/null || die "could not pull $IMAGE"
+ok "pulled $IMAGE"
+install -d -m 0700 -o 10001 -g 10001 "$APPDATA" "$APPDATA/runtime" "$APPDATA/agent" "$RUNTIME" "$BUNDLE"
+install -d -m 0700 -o 0 -g 0 "$AUTHORITY" "$STAGE"
+if test ! -f "$RUNTIME/machine.json"; then
+  NOW=$(date -u +%Y-%m-%dT%H:%M:%S.000Z)
+  printf '{\n  "schemaVersion": 1,\n  "machineId": "%s",\n  "createdAt": "%s",\n  "updatedAt": "%s",\n  "hostnameAliases": []\n}\n' "$AGENT" "$NOW" "$NOW" | write_butler_file "$RUNTIME/machine.json"
+fi
+if test ! -f "$BUNDLE/agent.json"; then
+  test -z "$(find "$BUNDLE" -mindepth 1 -print -quit)" || die "$BUNDLE has files but no agent.json; move it aside and run the installer again"
+  docker run --rm --pull=never --network=none --user 10001:10001 \
+    --mount "type=bind,src=$BUNDLE,dst=/home/ouro/AgentBundles/$AGENT.ouro" \
+    --entrypoint /bin/sh "$IMAGE" -ceu '
+      cp -R /opt/ouro/deploy/unraid/sanctuary.ouro/. /home/ouro/AgentBundles/sanctuary.ouro/
+      find /home/ouro/AgentBundles/sanctuary.ouro -type d -exec chmod 0700 {} +
+      find /home/ouro/AgentBundles/sanctuary.ouro -type f -exec chmod 0600 {} +'
+fi
+ok "Butler files seeded in $BUNDLE"
+install -d -m 0700 -o 10001 -g 10001 "$BUNDLE/house"
+OWNER_NAME=$OWNER_NAME BUTLER_NAME=$BUTLER_NAME HOUSEHOLD_NAME=$HOUSEHOLD_NAME node -e '
+  const house = { ownerName: process.env.OWNER_NAME, butlerName: process.env.BUTLER_NAME, householdName: process.env.HOUSEHOLD_NAME, publicEndpoints: [], requiredContainers: [] }
+  process.stdout.write(`${JSON.stringify(house, null, 2)}\n`)' | write_butler_file "$BUNDLE/house/house.json"
+if test ! -f "$BUNDLE/house/HOUSE.md"; then
+  printf '# %s\n\n%s owns this Unraid server and is the person %s works for.\n\nAdd anything the Butler should know about this household here: who lives here, what each container is for, what matters most. The Butler reads this file at the start of every conversation.\n' \
+    "$HOUSEHOLD_NAME" "$OWNER_NAME" "$BUTLER_NAME" | write_butler_file "$BUNDLE/house/HOUSE.md"
+fi
+ok "house description written to $BUNDLE/house"
+
+ASSETS=ouro-butler-installer-assets
+docker rm -f "$ASSETS" >/dev/null 2>&1 || true
+docker create --name "$ASSETS" "$IMAGE" >/dev/null
+docker cp "$ASSETS:/opt/ouro/deploy/unraid/sanctuary-butler-upgrade.mjs" "$STAGE/sanctuary-butler-upgrade.mjs" >/dev/null
+docker cp "$ASSETS:/opt/ouro/deploy/unraid/ouro-events/bootstrap-spool.sh" "$STAGE/bootstrap-spool.sh" >/dev/null
+docker rm -f "$ASSETS" >/dev/null
+chown 0:0 "$STAGE"/*; chmod 0700 "$STAGE"/*
+bash "$STAGE/bootstrap-spool.sh" --install-only
+bash "$EVENTS/bootstrap-spool.sh" --mount
+ok "event spool mounted and registered to mount at boot"
+
+# ---------------------------------------------------------------------------------------------------------------
+say "4. vault and model provider"
+VAULT_STATUS=$(ouro vault status --agent "$AGENT" --store plaintext-file 2>&1 || true)
+if [[ "$VAULT_STATUS" != *"local unlock: available"* ]]; then
+  printf 'Creating the vault. Choose an unlock phrase and keep it somewhere safe: it is the only way to recover\nthe Butler'"'"'s secrets if this server is lost.\n' > "$TTY"
+  ouro_interactive vault create --agent "$AGENT" --email "$VAULT_EMAIL" ${VAULT_SERVER:+--server "$VAULT_SERVER"} --store plaintext-file \
+    || die "vault creation did not finish; run the installer again to retry"
+fi
+ok "vault ready"
+printf '%s' "$ANTHROPIC_KEY" | ouro_stdin auth --agent "$AGENT" --provider anthropic --api-key-file /dev/stdin >/dev/null \
+  || die "storing the Anthropic key failed"
+unset ANTHROPIC_KEY
+for LANE in outward inner; do
+  ouro check --agent "$AGENT" --lane "$LANE" >/dev/null 2>&1 || die "the $LANE model lane did not answer; check the Anthropic key and your account's credit"
+done
+ok "Anthropic key stored in the vault; both model lanes answer"
+
+# ---------------------------------------------------------------------------------------------------------------
+say "5. Unraid API access"
+PORT=$(sed -n 's/^PORT="\{0,1\}\([0-9]*\)"\{0,1\}$/\1/p' /boot/config/ident.cfg 2>/dev/null | head -1)
+GRAPHQL_URL="http://127.0.0.1${PORT:+$( [ "$PORT" = 80 ] || printf ':%s' "$PORT")}/graphql"
+READ_PERMISSIONS="ARRAY:READ_ANY,DASHBOARD:READ_ANY,DISK:READ_ANY,DOCKER:READ_ANY,INFO:READ_ANY,LOGS:READ_ANY,NOTIFICATIONS:READ_ANY,SHARE:READ_ANY,VARS:READ_ANY"
+STAMP=$(date +%Y%m%d%H%M%S)
+create_unraid_key() { # create_unraid_key <name> <permissions> <vault field>
+  # Unraid 7.2's CLI refuses --permissions without a role ("Invalid data structure"); GUEST adds only own-profile access.
+  unraid-api apikey --create --name "$1" --roles GUEST --permissions "$2" --description "Ouro Butler $3" --json 2>/dev/null \
+    | node -e '
+        let text = ""; process.stdin.on("data", (c) => text += c).on("end", () => {
+          const start = text.indexOf("{"); if (start < 0) process.exit(1)
+          const key = JSON.parse(text.slice(start)).key; if (typeof key !== "string" || !key) process.exit(1)
+          process.stdout.write(key) })' \
+    | ouro_stdin vault config set --agent "$AGENT" --key "$3" --scope machine --value-file /dev/stdin >/dev/null \
+    || die "creating the Unraid API key $1 failed"
+}
+create_unraid_key "Butler RO $STAMP" "$READ_PERMISSIONS" unraidReadApiKey
+create_unraid_key "Butler RW $STAMP" "$READ_PERMISSIONS,DOCKER:UPDATE_ANY" unraidWriteApiKey
+ouro vault config set --agent "$AGENT" --key unraidGraphqlUrl --scope machine --value "$GRAPHQL_URL" >/dev/null
+ok "API keys \"Butler RO $STAMP\" and \"Butler RW $STAMP\" created (see Settings > Management Access > API Keys)"
+
+# ---------------------------------------------------------------------------------------------------------------
+say "6. Telegram and the root authority"
+test ! -L "$AUTHORITY/incoming-token" || die "$AUTHORITY/incoming-token is a link; remove it and run again"
+printf '%s' "$BOT_TOKEN" > "$AUTHORITY/incoming-token.tmp.$$"
+chmod 0600 "$AUTHORITY/incoming-token.tmp.$$"
+mv -f "$AUTHORITY/incoming-token.tmp.$$" "$AUTHORITY/incoming-token"
+unset BOT_TOKEN
+printf '\nOpen Telegram, find @%s and send it any message (for example "hello"). Waiting up to 3 minutes...\n' "$BOT_USERNAME" > "$TTY"
+OWNER_INFO=$(node -e '
+  const token = require("node:fs").readFileSync(process.argv[1], "utf8").trim()
+  const api = (method, query) => fetch(`https://api.telegram.org/bot${token}/${method}?${query}`).then((r) => r.json())
+  const deadline = Date.now() + 180000
+  ;(async () => {
+    while (Date.now() < deadline) {
+      const body = await api("getUpdates", "timeout=20&allowed_updates=%5B%22message%22%5D").catch(() => null)
+      const updates = body && body.ok ? body.result : []
+      const latest = updates.filter((u) => u.message && u.message.chat && u.message.chat.type === "private" && u.message.from).pop()
+      if (latest) {
+        await api("getUpdates", `offset=${latest.update_id + 1}&timeout=0`).catch(() => null)
+        const from = latest.message.from
+        process.stdout.write(`${from.id}\t${from.first_name || ""}${from.username ? ` (@${from.username})` : ""}`)
+        return
+      }
+      if (body && body.ok === false) { process.stderr.write(`Telegram: ${body.description}\n`); process.exit(2) }
+    }
+    process.exit(1)
+  })()' "$AUTHORITY/incoming-token") || die "no message reached the bot; run the installer again and message the bot when asked"
+OWNER_ID=${OWNER_INFO%%$'\t'*}
+confirm "The message came from ${OWNER_INFO#*$'\t'}. Is that you" || die "only the owner should message the bot during install; run the installer again"
+ok "owner Telegram id found"
+
+UPGRADE=(node "$STAGE/sanctuary-butler-upgrade.mjs")
+"${UPGRADE[@]}" preflight "$VERSION" --fresh || die "preflight found a problem (above); nothing has been installed yet"
+"${UPGRADE[@]}" prepare "$VERSION" --fresh --owner-id "$OWNER_ID" || die "prepare found a problem (above)"
+LOG=/var/log/ouro-butler-install.log
+printf 'Installing the authority and starting the Butler. This runs on even if this terminal closes; its log is %s.\n' "$LOG" > "$TTY"
+setsid nohup "${UPGRADE[@]}" install "$VERSION" > "$LOG" 2>&1 < /dev/null &
+INSTALL_PID=$!
+tail -n +1 --pid="$INSTALL_PID" -f "$LOG"
+wait "$INSTALL_PID" || die "install did not complete and was rolled back; the log is $LOG"
+"${UPGRADE[@]}" verify || die "the Butler is installed but verify found a problem (above)"
+
+say "done"
+printf 'Ouro Butler %s is running. Say hello to @%s on Telegram.\n' "$VERSION" "$BOT_USERNAME"
+printf 'Tell it about your household in %s/house/HOUSE.md.\n' "$BUNDLE"
+printf 'Keep the vault unlock phrase you chose somewhere safe.\n'

package/deploy/unraid/migrate-sanctuary-bundle.mjs

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+import * as path from "node:path"
+import { pathToFileURL } from "node:url"
+
+const USAGE = "Usage: migrate-sanctuary-bundle.mjs --package-root <path> --agent-root <path> --operation <migrate|seed|rollback|finalize-rollback|commit|status|inspect> [--rollback-image-id <sha256:id> --target-image-id <sha256:id>]"
+const BASE_KEYS = ["--package-root", "--agent-root", "--operation"]
+const MIGRATE_KEYS = [...BASE_KEYS, "--rollback-image-id", "--target-image-id"]
+
+function parseArguments(args) {
+  if (args.length % 2 !== 0) throw new Error(USAGE)
+  const values = new Map()
+  for (let index = 0; index < args.length; index += 2) {
+    const key = args[index]
+    const value = args[index + 1]
+    if (values.has(key) || typeof value !== "string" || value.length === 0) throw new Error(USAGE)
+    values.set(key, value)
+  }
+  const operation = values.get("--operation")
+  if (!["migrate", "seed", "rollback", "finalize-rollback", "commit", "status", "inspect"].includes(operation)) throw new Error(USAGE)
+  const expectedKeys = operation === "migrate" ? MIGRATE_KEYS : BASE_KEYS
+  if (values.size !== expectedKeys.length || expectedKeys.some((key) => !values.has(key)) || [...values.keys()].some((key) => !expectedKeys.includes(key))) throw new Error(USAGE)
+  return values
+}
+
+export function runSanctuaryBundleOperation(args, dependencies) {
+  const values = parseArguments(args)
+  const packageRoot = values.get("--package-root")
+  const agentRoot = values.get("--agent-root")
+  const operation = values.get("--operation")
+  const result = operation === "migrate"
+    ? dependencies.migrate({ packageRoot, agentRoot, retainRollback: true, rollbackImageId: values.get("--rollback-image-id"), targetImageId: values.get("--target-image-id") })
+    // A fresh install has no earlier image to roll back to, so it writes the packaged files without a rollback record.
+    : operation === "seed"
+      ? dependencies.migrate({ packageRoot, agentRoot, retainRollback: false })
+    : operation === "rollback"
+      ? { rolledBack: dependencies.rollback(agentRoot, { retainRecord: true }) }
+      // `rollback` keeps crash-retry evidence; the host uses `finalize-rollback` only after old production is audited, ready, and restored to autostart.
+      : operation === "finalize-rollback"
+        ? { rolledBack: dependencies.rollback(agentRoot, { retainRecord: false }) }
+        : operation === "commit"
+          ? { committed: dependencies.commit(agentRoot) }
+          : operation === "status"
+            ? dependencies.status(agentRoot)
+            : dependencies.inspect({ packageRoot, agentRoot, runtimePackageVersion: dependencies.getPackageVersion() })
+  if (result === null || ("rolledBack" in result && !result.rolledBack) || ("committed" in result && !result.committed)) throw new Error(`${operation} found no pending Sanctuary bundle transaction`)
+  return result
+}
+
+export async function runSanctuaryBundleCli(args = process.argv.slice(2), output = process.stdout) {
+  const migration = await import("../../dist/heart/daemon/sanctuary-bundle-migration.js")
+  const manifest = await import("../../dist/mind/bundle-manifest.js")
+  const result = runSanctuaryBundleOperation(args, {
+    commit: migration.commitSanctuaryPackageManagedBundle,
+    getPackageVersion: manifest.getPackageVersion,
+    inspect: migration.inspectSanctuaryPackageManagedBundle,
+    migrate: migration.migrateSanctuaryPackageManagedBundle,
+    rollback: migration.rollbackSanctuaryPackageManagedBundle,
+    status: migration.inspectSanctuaryPackageManagedBundleRollback,
+  })
+  output.write(`${JSON.stringify(result)}\n`)
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href) await runSanctuaryBundleCli()

package/deploy/unraid/ouro-events/bootstrap-spool.sh

@@ -0,0 +1,92 @@
+#!/bin/bash
+set -euo pipefail
+
+SPOOL_ROOT="/boot/config/custom/ouro-events/spool"
+INSTALL_PATH="/boot/config/custom/ouro-events/bootstrap-spool.sh"
+GO_FILE="/boot/config/go"
+TMPFS_OPTIONS="size=4m,mode=0755,uid=0,gid=0,nodev,nosuid,noexec"
+BOOT_HOOK="/bin/bash /boot/config/custom/ouro-events/bootstrap-spool.sh --mount"
+ACTION="mount"
+
+while (($# > 0)); do
+  case "$1" in
+    --mount|--install-only|--self-test) ACTION="${1#--}"; shift ;;
+    --go-file) GO_FILE="${2:?missing --go-file value}"; shift 2 ;;
+    --install-path) INSTALL_PATH="${2:?missing --install-path value}"; shift 2 ;;
+    *) echo "ouro event spool bootstrap: invalid argument: $1" >&2; exit 2 ;;
+  esac
+done
+
+mount_spool() {
+  local target="$1"
+  /bin/mkdir -p "$target"
+  /bin/chown 0:0 "$target"
+  /bin/chmod 0755 "$target"
+  if /bin/mountpoint -q "$target"; then
+    [[ "$(/bin/findmnt -n -o FSTYPE --target "$target")" == "tmpfs" ]] || { echo "ouro event spool bootstrap: canonical path is already a non-tmpfs mount" >&2; return 1; }
+  else
+    /bin/mount -t tmpfs -o "$TMPFS_OPTIONS" ouro-events-spool "$target"
+  fi
+  [[ "$(/bin/stat -c '%u:%g:%a' "$target")" == "0:0:755" ]] || { echo "ouro event spool bootstrap: tmpfs identity or mode is unsafe" >&2; return 1; }
+  local options
+  options="$(/bin/findmnt -n -o OPTIONS --target "$target")"
+  for required in nodev nosuid noexec; do
+    [[ ",$options," == *",$required,"* ]] || { echo "ouro event spool bootstrap: tmpfs is missing $required" >&2; return 1; }
+  done
+  local size_bytes
+  size_bytes="$(/bin/findmnt -bn -o SIZE --target "$target")"
+  [[ "$size_bytes" =~ ^[0-9]+$ && "$size_bytes" -le 4194304 ]] || { echo "ouro event spool bootstrap: tmpfs exceeds its 4 MiB bound" >&2; return 1; }
+}
+
+install_boot_hook() {
+  local install_dir resolved_source resolved_install
+  install_dir="$(dirname "$INSTALL_PATH")"
+  /bin/mkdir -p "$install_dir"
+  resolved_source="$(cd "$(dirname "$0")" && pwd -P)/$(basename "$0")"
+  resolved_install="$(cd "$install_dir" && pwd -P)/$(basename "$INSTALL_PATH")"
+  if [[ "$resolved_source" != "$resolved_install" ]]; then
+    install -m 0700 "$0" "$INSTALL_PATH"
+  else
+    /bin/chmod 0700 "$INSTALL_PATH"
+  fi
+  [[ -f "$GO_FILE" ]] || printf '#!/bin/bash\n' > "$GO_FILE"
+  if ! grep -Fqx "$BOOT_HOOK" "$GO_FILE"; then
+    local temporary="${GO_FILE}.ouro-events.$$"
+    awk -v hook="$BOOT_HOOK" 'NR == 1 && /^#!/ { print; print hook; next } NR == 1 { print hook } { print }' "$GO_FILE" > "$temporary"
+    /bin/chmod 0700 "$temporary"
+    /bin/mv "$temporary" "$GO_FILE"
+  fi
+}
+
+self_test() {
+  [[ "$(/usr/bin/id -u)" == "0" ]] || { echo "ouro event spool bootstrap self-test requires root" >&2; return 1; }
+  local test_root target readonly_view
+  test_root="$(/usr/bin/mktemp -d /tmp/ouro-event-spool.XXXXXX)"
+  target="$test_root/spool"
+  readonly_view="$test_root/readonly"
+  /bin/chmod 0755 "$test_root"
+  /bin/mkdir "$target" "$readonly_view"
+  cleanup() {
+    /bin/umount "$readonly_view" 2>/dev/null || true
+    /bin/umount "$target" 2>/dev/null || true
+    /bin/rmdir "$readonly_view" "$target" "$test_root" 2>/dev/null || true
+  }
+  trap cleanup EXIT
+  mount_spool "$target"
+  /usr/bin/printf 'probe\n' > "$target/probe"
+  /bin/chown 0:0 "$target/probe"
+  /bin/chmod 0444 "$target/probe"
+  /bin/mount --bind "$target" "$readonly_view"
+  /bin/mount -o remount,bind,ro,nodev,nosuid,noexec "$readonly_view"
+  /usr/bin/setpriv --reuid=10001 --regid=10001 --clear-groups /usr/bin/test -r "$readonly_view/probe"
+  [[ ",$(/bin/findmnt -n -o OPTIONS --target "$readonly_view")," == *",ro,"* ]] || { echo "ouro event spool bootstrap: test bind is not read-only" >&2; return 1; }
+  echo "uid10001-ro-bind: pass"
+  cleanup
+  trap - EXIT
+}
+
+case "$ACTION" in
+  mount) mount_spool "$SPOOL_ROOT" ;;
+  install-only) install_boot_hook ;;
+  self-test) self_test ;;
+esac