@zerwiz/ymir 0.1.4 → 0.1.7

package/bin/ymir-platform.sh

@@ -0,0 +1,348 @@
+#!/usr/bin/env bash
+# ymir-platform.sh — the portability layer.
+#
+# Ymir must run on Linux, macOS and Windows (through WSL2 or MSYS/Git Bash).
+# GNU coreutils are not guaranteed: BSD `readlink` has no `-f`, BSD `stat` uses
+# `-f` not `-c`, macOS `date` has no `%N`, and `nproc`, `setsid`, `flock` and
+# `/proc` do not exist there at all. This file is the ONE place that knows a
+# platform difference; every other script calls these functions.
+#
+# Sourced, never executed:   . "$ROOT/bin/ymir-platform.sh"
+# It defines functions only and has no side effects.
+#
+# Convention: every function is `ymir_*`, prints to stdout, and never exits the
+# caller. A capability that is genuinely absent returns a non-zero status so the
+# caller can decide; a capability with a sane fallback always succeeds.
+
+# ── platform ─────────────────────────────────────────────────────────────────
+
+ymir_os() {  # linux | macos | wsl | msys | unknown
+  case "$(uname -s 2>/dev/null)" in
+    Linux*)
+      if [ -r /proc/version ] && grep -qiE 'microsoft|wsl' /proc/version 2>/dev/null; then
+        printf 'wsl'
+      else
+        printf 'linux'
+      fi ;;
+    Darwin*)               printf 'macos' ;;
+    MINGW*|MSYS*|CYGWIN*)  printf 'msys' ;;
+    *)                     printf 'unknown' ;;
+  esac
+}
+
+ymir_has_gnu() {  # true when GNU-style tool flags are available
+  case "$(ymir_os)" in linux|wsl|msys) return 0 ;; *) return 1 ;; esac
+}
+
+# ── basic tools ──────────────────────────────────────────────────────────────
+
+ymir_nproc() {  # CPU count
+  if command -v nproc >/dev/null 2>&1; then nproc
+  elif command -v sysctl >/dev/null 2>&1 && sysctl -n hw.ncpu >/dev/null 2>&1; then sysctl -n hw.ncpu
+  elif command -v getconf >/dev/null 2>&1; then getconf _NPROCESSORS_ONLN 2>/dev/null || printf '4'
+  else printf '4'; fi
+}
+
+ymir_readlink_f() {  # resolve symlinks; BSD readlink has no -f
+  [ $# -ge 1 ] || return 1
+  local p=$1
+  if readlink -f -- "$p" >/dev/null 2>&1; then readlink -f -- "$p"; return 0; fi
+  # Portable resolution: follow one link at a time, keeping the result absolute.
+  local dir base target hops=0
+  case "$p" in /*) : ;; *) p="$PWD/$p" ;; esac
+  while [ -L "$p" ] && [ "$hops" -lt 40 ]; do
+    hops=$((hops+1))
+    dir=$(dirname "$p"); base=$(basename "$p")
+    target=$(readlink "$p") || break
+    case "$target" in /*) p="$target" ;; *) p="$dir/$target" ;; esac
+  done
+  # normalise . and .. lexically
+  local resolved
+  resolved=$(printf '%s' "$p" | awk -F/ '{
+    n=0; for (i=1;i<=NF;i++) { if ($i==""||$i==".") continue; if ($i=="..") { if (n>0) n--; continue } a[++n]=$i }
+    out=""; for (i=1;i<=n;i++) out=out"/"a[i]; if (out=="") out="/"; print out }')
+  # Mirror GNU -f: every component but the last must exist, or the call fails
+  # and prints nothing. Callers rely on that to detect a dangling link.
+  if [ ! -d "$(dirname "$resolved")" ]; then return 1; fi
+  printf '%s' "$resolved"
+}
+
+ymir_epoch_ns() {  # high-resolution epoch for timing (BSD date has no %N)
+  local s n
+  s=$(date +%s 2>/dev/null) || s=0
+  n=$(date +%N 2>/dev/null)
+  case "$n" in ''|*[!0-9]*) n=000000000 ;; esac
+  printf '%s%s' "$s" "$n"
+}
+
+ymir_realpath_dir() {  # directory of the running script, resolved
+  local src=${1:-${BASH_SOURCE[0]}}
+  dirname "$(ymir_readlink_f "$src" 2>/dev/null || printf '%s' "$src")"
+}
+
+# ── stat: GNU -c vs BSD -f ───────────────────────────────────────────────────
+
+ymir_stat_mtime() {  # epoch seconds
+  if ymir_has_gnu; then stat -c %Y -- "$1" 2>/dev/null
+  else stat -f %m -- "$1" 2>/dev/null; fi
+}
+
+ymir_stat_size() {   # bytes
+  if ymir_has_gnu; then stat -c %s -- "$1" 2>/dev/null
+  else stat -f %z -- "$1" 2>/dev/null; fi
+}
+
+ymir_stat_id() {     # "<device>:<inode>" — identity of a file
+  if ymir_has_gnu; then stat -c '%d:%i' -- "$1" 2>/dev/null
+  else stat -f '%d:%i' -- "$1" 2>/dev/null; fi
+}
+
+ymir_stat_birth() {  # birth/creation time as epoch seconds, or 0 when unknown
+  local b=''
+  if ymir_has_gnu; then
+    b=$(stat -c %W -- "$1" 2>/dev/null)
+  else
+    b=$(stat -f %B -- "$1" 2>/dev/null)   # macOS: %B is birth time
+  fi
+  case "$b" in ''|*[!0-9]*) printf '0' ;; *) printf '%s' "$b" ;; esac
+}
+
+ymir_stat_mode() {   # "file" | "dir" | "link" | "other"
+  local f
+  if ymir_has_gnu; then f=$(stat -c %F -- "$1" 2>/dev/null)
+  else f=$(stat -f %HT -- "$1" 2>/dev/null); fi
+  case "$f" in
+    *directory*)                printf 'dir' ;;
+    *symbolic*|*link*)          printf 'link' ;;
+    *regular*|*"regular file"*) printf 'file' ;;
+    '')                         printf 'other' ;;
+    *)                          printf 'other' ;;
+  esac
+}
+
+# ── processes ────────────────────────────────────────────────────────────────
+
+ymir_pid_alive() {  # 0 when the pid exists
+  [ -n "${1:-}" ] && kill -0 "$1" 2>/dev/null
+}
+
+ymir_pid_cmdline() {  # the command line of a pid, one line; empty when gone
+  local pid=${1:-}
+  [ -n "$pid" ] || return 1
+  if [ -r "/proc/$pid/cmdline" ]; then
+    tr '\0' ' ' <"/proc/$pid/cmdline" 2>/dev/null
+  else
+    ps -o command= -p "$pid" 2>/dev/null     # works on macOS and BSD
+  fi
+}
+
+ymir_pid_matches() {  # 0 when the pid is alive AND its cmdline contains the mark
+  local pid=${1:-} mark=${2:-}
+  ymir_pid_alive "$pid" || return 1
+  [ -n "$mark" ] || return 0
+  ymir_pid_cmdline "$pid" 2>/dev/null | grep -q -- "$mark"
+}
+
+ymir_kill_matching() {  # <pattern> [signal] — signal processes whose cmdline matches
+  local pat=${1:-} sig=${2:-TERM}
+  [ -n "$pat" ] || return 1
+  if command -v pkill >/dev/null 2>&1; then
+    pkill -"$sig" -f -- "$pat" 2>/dev/null || true
+    return 0
+  fi
+  # No pkill (some MSYS/WSL images): ps + kill, never matching our own line.
+  local pids
+  pids=$(ps -eo pid=,args= 2>/dev/null | grep -F -- "$pat" | grep -v -e grep -e ymir_kill_matching | awk '{print $1}')
+  [ -n "$pids" ] && kill -s "$sig" $pids 2>/dev/null || true
+  return 0
+}
+
+ymir_detach() {  # run a command detached from this shell's lifetime
+  # setsid where available (Linux/WSL); MSYS has it; macOS does not.
+  if command -v setsid >/dev/null 2>&1; then
+    setsid "$@" < /dev/null &
+  else
+    nohup "$@" < /dev/null > /dev/null 2>&1 &
+  fi
+  printf '%s' "$!"
+}
+
+# ── locking: flock vs a portable mkdir lock ─────────────────────────────────
+
+ymir_lock() {  # <lockfile> <cmd...> — run cmd under an exclusive lock, or fail
+  local lock=$1; shift
+  if command -v flock >/dev/null 2>&1; then
+    exec 9>"$lock" 2>/dev/null || return 1
+    flock -n 9 || return 1
+    "$@"; local rc=$?
+    exec 9>&- 2>/dev/null || true
+    return $rc
+  fi
+  # Portable fallback: mkdir is atomic on every filesystem we care about.
+  local d="${lock}.d"
+  mkdir "$d" 2>/dev/null || return 1
+  "$@"; local rc=$?
+  rmdir "$d" 2>/dev/null || true
+  return $rc
+}
+
+# ── services: systemd (Linux) vs launchd (macOS) vs nothing ─────────────────
+
+ymir_service_backend() {  # systemd | launchd | none
+  if command -v systemctl >/dev/null 2>&1 && systemctl --user >/dev/null 2>&1; then printf 'systemd'
+  elif command -v launchctl >/dev/null 2>&1; then printf 'launchd'
+  else printf 'none'; fi
+}
+
+ymir_service_active() {  # <name> -> 0 when running
+  case "$(ymir_service_backend)" in
+    systemd) systemctl --user is-active --quiet "$1" 2>/dev/null ;;
+    launchd) launchctl list 2>/dev/null | grep -q -- "$1" ;;
+    *)       return 1 ;;
+  esac
+}
+
+# ── containers: Docker or rootless Podman ───────────────────────────────────
+
+# Which container engine to use. Fedora ships rootless Podman and frequently has
+# no `docker` at all; Debian/Ubuntu usually have Docker. YMIR_CONTAINER_ENGINE
+# forces one. Prints the engine name and returns 0, or returns 1 when none of
+# them can actually be reached.
+ymir_container_engine() {
+  local e
+  for e in ${YMIR_CONTAINER_ENGINE:-} docker podman; do
+    [ -n "$e" ] || continue
+    command -v "$e" >/dev/null 2>&1 || continue
+    # podman answers `info` with no daemon; docker needs one running. Accept either.
+    if "$e" info >/dev/null 2>&1; then printf '%s' "$e"; return 0; fi
+  done
+  return 1
+}
+
+# The engine binary that exists, even if its daemon is not reachable. Useful for
+# diagnostics that want to name the engine rather than run it.
+ymir_container_engine_name() {
+  local e
+  for e in ${YMIR_CONTAINER_ENGINE:-} docker podman; do
+    [ -n "$e" ] || continue
+    command -v "$e" >/dev/null 2>&1 && { printf '%s' "$e"; return 0; }
+  done
+  return 1
+}
+
+# true when SELinux is enforcing (Fedora). A bind mount into a container then
+# needs the :Z relabel, or the container is denied access to the host path.
+ymir_selinux_enforcing() {
+  if [ -r /sys/fs/selinux/enforce ]; then
+    [ "$(cat /sys/fs/selinux/enforce 2>/dev/null)" = 1 ]
+  elif command -v getenforce >/dev/null 2>&1; then
+    [ "$(getenforce 2>/dev/null)" = "Enforcing" ]
+  else
+    return 1
+  fi
+}
+
+# true when the resolved engine is Podman — including when the `docker` binary is
+# really Podman (the podman-docker shim), which names itself in `info`.
+ymir_engine_is_podman() {
+  local e
+  e="$(ymir_container_engine 2>/dev/null || ymir_container_engine_name 2>/dev/null)" || return 1
+  [ -n "$e" ] || return 1
+  [ "$e" = podman ] && return 0
+  "$e" info 2>/dev/null | grep -qi podman
+}
+
+# true when rootless Podman: bind-mount ownership then needs --userns=keep-id so
+# files land owned by the invoking user. Docker (and rootful Podman) do not.
+ymir_rootless_podman() {
+  ymir_engine_is_podman && [ "$(id -u)" -ne 0 ]
+}
+
+# true when Ymir itself is running inside a container (podman or docker).
+ymir_in_container() {
+  [ -e /run/.containerenv ] || [ -e /.dockerenv ] || [ -n "${container:-}" ]
+}
+
+# The `-v` suffix for a bind mount: `:Z` whenever SELinux is enforcing — Docker
+# and Podman both need the relabel there — else empty. Append to `<host>:<ctr>`.
+ymir_volume_suffix() {
+  ymir_selinux_enforcing && printf ':Z'
+}
+
+# ── GPUs: report what exists, without assuming NVIDIA ───────────────────────
+
+ymir_gpu_name() {  # best-effort device name, or empty
+  if command -v nvidia-smi >/dev/null 2>&1; then
+    nvidia-smi --query-gpu=name --format=csv,noheader 2>/dev/null | head -1
+  elif command -v rocm-smi >/dev/null 2>&1; then
+    rocm-smi --showproductname 2>/dev/null | head -2 | tr '\n' ' '
+  elif [ "$(ymir_os)" = macos ]; then
+    printf 'Apple Silicon (unified memory)'
+  else
+    printf ''
+  fi
+}
+
+ymir_gpu_mem_used() {  # MiB in use, or "?" when unknown
+  if command -v nvidia-smi >/dev/null 2>&1; then
+    nvidia-smi --query-gpu=memory.used --format=csv,noheader,nounits 2>/dev/null | head -1 || printf '?'
+  elif command -v rocm-smi >/dev/null 2>&1; then
+    rocm-smi --showmemuse 2>/dev/null | grep -oE '[0-9]+' | head -1 || printf '?'
+  else
+    printf '?'
+  fi
+}
+
+ymir_llama_server() {  # locate a llama-server without assuming a path
+  local c
+  for c in "${LLAMA_SERVER:-}" llama-server; do
+    [ -n "$c" ] || continue
+    if command -v "$c" >/dev/null 2>&1; then command -v "$c"; return 0; fi
+  done
+  for c in /opt/homebrew/bin/llama-server /usr/local/bin/llama-server; do
+    [ -x "$c" ] && { printf '%s' "$c"; return 0; }
+  done
+  return 1
+}
+
+# ── paths ────────────────────────────────────────────────────────────────────
+
+ymir_tmp() {  # a private temporary directory, on every OS
+  local base=${TMPDIR:-${TEMP:-/tmp}}
+  mktemp -d "${base%/}/ymir.XXXXXX" 2>/dev/null || mktemp -d
+}
+
+ymir_expand_tilde() {  # expand a leading ~ in a user-supplied path
+  case "${1:-}" in
+    '~')   printf '%s' "$HOME" ;;
+    '~/'*) printf '%s/%s' "$HOME" "${1#\~/}" ;;
+    *)     printf '%s' "$1" ;;
+  esac
+}
+
+# ── isolation: is bwrap usable here? ─────────────────────────────────────────
+
+# True when bubblewrap can actually create the namespaces it needs. This is a
+# real probe, not a presence check: inside a hardened container (rootless Podman
+# Quadlet), nested user namespaces are often denied and bwrap fails with
+# "Creating new namespace failed: Operation not permitted". Callers must degrade,
+# never assume.
+ymir_bwrap_available() {
+  command -v bwrap >/dev/null 2>&1 || return 1
+  bwrap --unshare-all --die-with-parent --ro-bind / / true >/dev/null 2>&1
+}
+
+# True when Ymir itself is running inside a container (podman or docker).
+ymir_in_container() {
+  [ -e /run/.containerenv ] || [ -e /.dockerenv ] || [ -n "${container:-}" ]
+}
+
+# The isolation layers available here, outermost first. Prints a csv of any of
+# `container,bwrap,none` — the caller picks, never assumes bwrap.
+ymir_isolation_layers() {
+  local out=""
+  ymir_in_container && out="container"
+  if ymir_bwrap_available; then out="${out:+$out,}bwrap"; fi
+  [ -n "$out" ] || out="none"
+  printf '%s' "$out"
+}

package/bin/ymir-say.sh

@@ -0,0 +1,110 @@
+#!/usr/bin/env bash
+# ymir-say.sh — let Ymir speak on the Allfather's desktop.
+#
+# Ymir works for hours without him watching. When something is worth knowing — a
+# job done, a crash seen, an alarm that could not be delivered, a task needing a
+# word — it should reach him where he already is: an Omarchy desktop
+# notification, with a durable line on disk so a missed popup is still found.
+#
+# This is the single owner of "Ymir speaks on the desktop". Anything with news
+# calls it, so the manner (glyph, urgency, app identity) cannot drift.
+#
+# Usage:
+#   bin/ymir-say.sh <headline> [body] [--urgency low|normal|critical] [--glyph G]
+#   bin/ymir-say.sh --mark-done "<what>"     # a job finished
+#   bin/ymir-say.sh --mark-alarm "<what>"    # something needs him soon
+#   bin/ymir-say.sh --mark-fail "<what>"     # something went wrong
+#   bin/ymir-say.sh status                   # what has been said, and where it went
+#   bin/ymir-say.sh --version
+#
+# The desktop notifier is Omarchy's own when present, else notify-send. With
+# neither, the line is still recorded — a silent host is not a lost message.
+set -u
+
+VERSION="1.0.0"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+
+# The roots that live OUTSIDE the code tree: this machine's records and the
+# runtime state belong to the home the operator chose at installation, never in
+# the tree — a packaged install replaces its tree on upgrade (Rule 04).
+if [ -z "${YMIR_HOARD_LIB_LOADED:-}" ]; then
+  _yr="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+  for _yc in "$_yr/hoard-lib.sh" "$(dirname "$_yr")/bin/hoard-lib.sh"; do
+    [ -r "$_yc" ] && { . "$_yc"; YMIR_HOARD_LIB_LOADED=1; break; }
+  done
+  unset _yr _yc
+fi
+hoard_state_dir YMIR_STATE_DIR
+hoard_data_dir YMIR_DATA_DIR
+STATE_DIR="${BROKK_STATE_OVERRIDE:-$YMIR_STATE_DIR}"
+LOG="$STATE_DIR/ymir-said.log"
+
+case "${1-}" in
+  -v|-V|--version) printf '%s\n' "$VERSION"; exit 0 ;;
+  -h|--help|"") sed -n '2,22p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;;
+  status)
+    if [ -r "$LOG" ]; then
+      printf 'ymir-say[%d]{when,mark,who,what}:\n' "$(grep -c . "$LOG" 2>/dev/null || echo 0)"
+      tail -8 "$LOG" | while IFS=$'\t' read -r when mark who what; do
+        printf '  "%s","%s","%s","%s"\n' "$when" "$mark" "$who" "$what"
+      done
+    else
+      printf 'ymir-say[1]{state}:\n  "nothing said yet"\n'
+    fi
+    exit 0 ;;
+esac
+
+URGENCY="normal"
+GLYPH=""
+MARK="note"
+case "${1-}" in
+  --mark-done)  MARK="done";  URGENCY="low";      GLYPH="✓"; set -- "${2:-A job finished}" "${3:-}" ;;
+  --mark-alarm) MARK="alarm"; URGENCY="critical"; GLYPH="!"; set -- "${2:-Needs your word}" "${3:-}" ;;
+  --mark-fail)  MARK="fail";  URGENCY="critical"; GLYPH="✗"; set -- "${2:-Something went wrong}" "${3:-}" ;;
+esac
+
+HEADLINE="${1:-}"
+BODY="${2:-}"
+shift 2 2>/dev/null || true
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --urgency) URGENCY=${2:-normal}; shift 2 ;;
+    --glyph)   GLYPH=${2:-}; shift 2 ;;
+    --mark)    MARK=${2:-note}; shift 2 ;;
+    *) shift ;;
+  esac
+done
+
+[ -n "$HEADLINE" ] || { printf 'error: ymir-say needs a headline\nhelp: bin/ymir-say.sh "<headline>" ["<body>"]\n' >&2; exit 2; }
+
+WHO="${YMIR_SAY_WHO:-Ymir}"
+[ -n "$GLYPH" ] || GLYPH="•"
+
+mkdir -p "$STATE_DIR" 2>/dev/null || true
+printf '%s\t%s\t%s\t%s\n' "$(date -u +%Y-%m-%dT%H:%M:%SZ)" "$MARK" "$HEADLINE" "$BODY" >>"$LOG" 2>/dev/null || true
+
+TITLE="$GLYPH $WHO — $HEADLINE"
+fired=0
+if command -v omarchy-notification-send >/dev/null 2>&1; then
+  if [ -n "$BODY" ]; then
+    omarchy-notification-send -u "$URGENCY" -g "$GLYPH" "$TITLE" "$BODY" >/dev/null 2>&1 && fired=1
+  else
+    omarchy-notification-send -u "$URGENCY" -g "$GLYPH" "$TITLE" >/dev/null 2>&1 && fired=1
+  fi
+fi
+if [ "$fired" = 0 ] && command -v notify-send >/dev/null 2>&1; then
+  if [ -n "$BODY" ]; then
+    notify-send -u "$URGENCY" "$TITLE" "$BODY" >/dev/null 2>&1 && fired=1
+  else
+    notify-send -u "$URGENCY" "$TITLE" >/dev/null 2>&1 && fired=1
+  fi
+fi
+
+# The durable line was written either way; only report the channel's fate.
+if [ "$fired" = 1 ]; then
+  printf 'ymir-say[1]{mark,urgency,channel}:\n  "%s","%s","desktop"\n' "$MARK" "$URGENCY"
+  exit 0
+fi
+printf 'ymir-say[1]{mark,urgency,channel}:\n  "%s","%s","record only (no desktop notifier)"\n' "$MARK" "$URGENCY"
+exit 0

package/bin/ymir-setup-auth.sh

@@ -0,0 +1,119 @@
+#!/usr/bin/env bash
+# ymir-setup-auth.sh — set the operator's Ymir credential at first setup.
+#
+# Two doors into the gate (apps/hlidskjalf/server):
+#   * a local password  -> HLIDSKJALF_AUTH="<user>:<password>" (the gate's own login)
+#   * GitHub sign-in     -> GITHUB_CLIENT_ID + GITHUB_CLIENT_SECRET (a GitHub OAuth app;
+#                           the gate's /api/auth/github names a login, it never grants
+#                           access on its own — an account/invite is still required).
+# A secret is never printed or logged; both doors write .env.local (0600, gitignored).
+#
+# Usage:
+#   ymir-setup-auth.sh status                 # which door (if any) is configured
+#   ymir-setup-auth.sh set [--user U]         # prompt for an operator password
+#   ymir-setup-auth.sh github                 # prompt for a GitHub OAuth app's keys
+#   ymir-setup-auth.sh --version | --help
+set -u
+
+VERSION="1.0.0"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+
+# The operator's credentials are theirs and live in the HOME they chose — never
+# in the code tree, which a packaged install replaces on upgrade (Rule 04).
+if [ -z "${YMIR_HOARD_LIB_LOADED:-}" ]; then
+  _yr="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+  for _yc in "$_yr/hoard-lib.sh" "$(dirname "$_yr")/bin/hoard-lib.sh"; do
+    [ -r "$_yc" ] && { . "$_yc"; YMIR_HOARD_LIB_LOADED=1; break; }
+  done
+  unset _yr _yc
+fi
+hoard_local_env _YMIR_ENV_DEFAULT
+ENV_FILE="${YMIR_ENV_FILE:-$_YMIR_ENV_DEFAULT}"
+
+usage() { sed -n '2,17p' "$0" | sed 's/^# \{0,1\}//'; }
+die() { printf 'error: %s\n' "$1" >&2; exit 1; }
+
+env_has() { grep -q "^$1=" "$ENV_FILE" 2>/dev/null; }
+
+# Replace or append a key in .env.local without ever putting the value in argv
+# (printf is a shell builtin; the value never reaches a child process's args).
+set_env_key() {  # <key> <value>
+  local key=$1 val=$2 tmp="" line
+  mkdir -p "$(dirname "$ENV_FILE")"
+  [ -f "$ENV_FILE" ] || : >"$ENV_FILE"
+  chmod 600 "$ENV_FILE" 2>/dev/null || true
+  tmp="$(mktemp)" || die "could not create a temp file"
+  while IFS= read -r line || [ -n "$line" ]; do
+    case "$line" in "$key="*) continue ;; esac
+    printf '%s\n' "$line"
+  done <"$ENV_FILE" >"$tmp"
+  printf '%s=%s\n' "$key" "$val" >>"$tmp"
+  mv "$tmp" "$ENV_FILE" || die "could not write $ENV_FILE"
+  chmod 600 "$ENV_FILE" 2>/dev/null || true
+}
+
+prompt_secret() {  # <prompt> <result-var>
+  local prompt=$1 result_var=$2 value=""
+  if [ -t 0 ]; then
+    printf '%s' "$prompt"
+    stty -echo 2>/dev/null || true
+    IFS= read -r value || true
+    stty echo 2>/dev/null || true
+    printf '\n'
+  else
+    IFS= read -r value || true
+  fi
+  printf -v "$result_var" '%s' "$value"
+}
+
+ACTION="${1:-status}"; shift || true
+case "$ACTION" in
+  -v|-V|--version) printf '%s\n' "$VERSION"; exit 0 ;;
+  -h|--help|"") usage; exit 0 ;;
+esac
+
+case "$ACTION" in
+  status)
+    if env_has HLIDSKJALF_AUTH; then
+      printf 'auth[1]{door,env,file}:\n  "password","HLIDSKJALF_AUTH","%s"\n' "$ENV_FILE"
+    elif env_has GITHUB_CLIENT_ID && env_has GITHUB_CLIENT_SECRET; then
+      printf 'auth[1]{door,env,file}:\n  "github","GITHUB_CLIENT_ID+GITHUB_CLIENT_SECRET","%s"\n' "$ENV_FILE"
+    else
+      printf 'auth[1]{door,env,file}:\n  "none","-","%s"\n' "$ENV_FILE"
+    fi
+    ;;
+
+  set)
+    user="${USER:-operator}"
+    while [ $# -gt 0 ]; do case "$1" in --user) user=${2-}; shift 2 ;; *) shift ;; esac; done
+    [ -t 0 ] || die "ymir-setup-auth set needs an interactive terminal (or set HLIDSKJALF_AUTH in $ENV_FILE yourself)"
+    printf 'Operator username [%s]: ' "$user"; IFS= read -r u || true; [ -n "${u:-}" ] && user="$u"
+    prompt_secret 'Password: ' pass
+    [ -n "$pass" ] || die "empty password — refusing to set a blank credential"
+    prompt_secret 'Confirm:  ' pass2
+    [ "$pass" = "$pass2" ] || die "passwords do not match"
+    set_env_key HLIDSKJALF_AUTH "$user:$pass"
+    printf 'auth[1]{door,set,file}:\n  "password","%s","%s"\n' "$user" "$ENV_FILE"
+    printf 'next: restart the gate so it reads the new credential (scripts/stop.sh; scripts/start.sh)\n'
+    ;;
+
+  github)
+    [ -t 0 ] || die "ymir-setup-auth github needs an interactive terminal"
+    printf 'Create a GitHub OAuth app (Settings > Developer settings > OAuth Apps), set its\n'
+    printf 'callback to http://127.0.0.1:3889/api/auth/github/callback, then paste:\n\n'
+    printf 'Client ID: '; IFS= read -r cid || true
+    [ -n "${cid:-}" ] || die "empty client id"
+    prompt_secret 'Client secret: ' csec
+    [ -n "$csec" ] || die "empty client secret"
+    set_env_key GITHUB_CLIENT_ID "$cid"
+    set_env_key GITHUB_CLIENT_SECRET "$csec"
+    printf 'auth[1]{door,set,file}:\n  "github","GITHUB_CLIENT_ID","%s"\n' "$ENV_FILE"
+    if command -v gh >/dev/null 2>&1 && ! gh auth status >/dev/null 2>&1; then
+      printf 'hint: run `gh auth login` too — repo access (PRs, deploys) is separate from sign-in.\n'
+    fi
+    printf 'next: restart the gate (scripts/stop.sh; scripts/start.sh)\n'
+    ;;
+
+  *) printf 'error: unknown action %s\nhelp: ymir-setup-auth.sh [status|set|github]\n' "$ACTION" >&2; exit 2 ;;
+esac