kitowall 7.7.0 → 7.9.0

package/dist/core/setup.js

@@ -140,6 +140,11 @@ function bootstrapHostPath() {
 function bootstrapSystemPath() {
     return (0, node_path_1.join)(ROOT_DIR, 'scripts', 'bootstrap-system.sh');
 }
+async function assertBootstrapScriptExists(targetPath, label) {
+    if (await fileExists(targetPath))
+        return;
+    throw new Error(`${label} not found at ${targetPath}. Reinstala el CLI con: npm i -g --prefix ~/.local kitowall@latest`);
+}
 async function bootstrapVersionsPath() {
     return (0, node_path_1.join)(homeDir(), '.local', 'share', 'kitowall', 'bootstrap-versions.json');
 }
@@ -365,7 +370,9 @@ async function listSetupVersions() {
     return { ok: true, items };
 }
 async function runBootstrapHostMode(mode) {
-    const out = await (0, exec_1.run)('bash', [bootstrapHostPath()], {
+    const scriptPath = bootstrapHostPath();
+    await assertBootstrapScriptExists(scriptPath, 'bootstrap-host.sh');
+    const out = await (0, exec_1.run)('bash', [scriptPath], {
         env: {
             ...process.env,
             HOME: homeDir(),
@@ -377,7 +384,9 @@ async function runBootstrapHostMode(mode) {
     return { ok: true, code: out.code, logs: `${out.stdout}${out.stderr}` };
 }
 async function runBootstrapSystemItems(ids) {
-    const out = await (0, exec_1.run)('pkexec', ['bash', bootstrapSystemPath(), ...ids], {
+    const scriptPath = bootstrapSystemPath();
+    await assertBootstrapScriptExists(scriptPath, 'bootstrap-system.sh');
+    const out = await (0, exec_1.run)('pkexec', ['bash', scriptPath, ...ids], {
         env: {
             ...process.env,
             HOME: homeDir(),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kitowall",
-  "version": "7.7.0",
+  "version": "7.9.0",
   "description": "CLI/daemon for Hyprland wallpapers using swww with pack-based rotation.",
   "repository": {
     "type": "git",
@@ -10,6 +10,8 @@
   "type": "commonjs",
   "files": [
     "dist",
+    "scripts/bootstrap-host.sh",
+    "scripts/bootstrap-system.sh",
     "README.md",
     "LICENSE.md",
     "NOTICE.md",

package/scripts/bootstrap-host.sh

@@ -0,0 +1,552 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Host bootstrap for AppImage/non-Flatpak installations.
+# Installs system dependencies plus kitowall/kitsune/kitsune-rendercore binaries.
+
+KITSUNE_REPO="${KITSUNE_REPO:-https://github.com/KitotsuMolina/Kitsune.git}"
+KITSUNE_RENDERCORE_REPO="${KITSUNE_RENDERCORE_REPO:-https://github.com/KitotsuMolina/Kitsune-RenderCore.git}"
+KITSUNE_TAG="${KITSUNE_TAG:-}"
+KITSUNE_RENDERCORE_TAG="${KITSUNE_RENDERCORE_TAG:-}"
+KITOWALL_BOOTSTRAP_MODE="${KITOWALL_BOOTSTRAP_MODE:-full}"
+KITOWALL_SKIP_SYSTEM_DEPS="${KITOWALL_SKIP_SYSTEM_DEPS:-0}"
+
+BOOTSTRAP_KITSUNE_VERSION=""
+BOOTSTRAP_RENDERCORE_VERSION=""
+
+need_cmd() {
+  command -v "$1" >/dev/null 2>&1
+}
+
+prepend_user_path() {
+  local home_dir="${HOME:?HOME is required}"
+  export PATH="$home_dir/.local/bin:$home_dir/.cargo/bin:$PATH"
+}
+
+run_sudo() {
+  if need_cmd sudo; then
+    sudo "$@"
+  else
+    "$@"
+  fi
+}
+
+wait_pacman_lock() {
+  local lock_file="/var/lib/pacman/db.lck"
+  local tries=0
+  local max_tries=40
+
+  while [[ -e "$lock_file" ]]; do
+    # If a package manager is still running, just wait.
+    if pgrep -x pacman >/dev/null 2>&1 || \
+       pgrep -x yay >/dev/null 2>&1 || \
+       pgrep -x paru >/dev/null 2>&1 || \
+       pgrep -x makepkg >/dev/null 2>&1; then
+      tries=$((tries + 1))
+      if ((tries > max_tries)); then
+        echo "[bootstrap] pacman lock is busy for too long: $lock_file" >&2
+        return 1
+      fi
+      echo "[bootstrap] waiting for pacman lock (${tries}/${max_tries})..."
+      sleep 3
+      continue
+    fi
+
+    # No package process alive: stale lock, safe to remove.
+    echo "[bootstrap] removing stale pacman lock: $lock_file"
+    run_sudo rm -f "$lock_file"
+    break
+  done
+}
+
+ensure_user_bin_dirs() {
+  local home_dir
+  home_dir="${HOME:?HOME is required}"
+  mkdir -p "$home_dir/.local/bin" "$home_dir/.cargo/bin"
+  prepend_user_path
+}
+
+install_arch_deps() {
+  local repo_pkgs=(
+    nodejs npm
+    hyprland
+    swww
+    cava
+    pkgconf
+    gtk4
+    gtk4-layer-shell
+    jq
+    git
+    base-devel
+  )
+  # Avoid rust/rustup conflicts on Arch.
+  if need_cmd rustup; then
+    repo_pkgs+=(rustup)
+  elif need_cmd rustc && need_cmd cargo; then
+    :
+  else
+    repo_pkgs+=(rustup)
+  fi
+
+  echo "[bootstrap] installing Arch repo packages: ${repo_pkgs[*]}"
+  wait_pacman_lock
+  run_sudo pacman -S --needed --noconfirm "${repo_pkgs[@]}"
+}
+
+install_ubuntu_deps() {
+  local pkgs=(
+    nodejs npm
+    rustc cargo
+    pkg-config
+    libgtk-4-dev
+    jq curl git
+    cava
+  )
+  echo "[bootstrap] installing Debian/Ubuntu packages: ${pkgs[*]}"
+  run_sudo apt-get update
+  run_sudo apt-get install -y "${pkgs[@]}"
+}
+
+install_system_deps() {
+  if need_cmd pacman; then
+    install_arch_deps
+    return
+  fi
+  if need_cmd apt-get; then
+    install_ubuntu_deps
+    return
+  fi
+  echo "[bootstrap] unsupported distro package manager. Install manually: nodejs npm rust cargo pkg-config gtk4 gtk4-layer-shell swww hyprland cava" >&2
+  exit 1
+}
+
+install_kitowall_cli() {
+  if ! need_cmd npm; then
+    echo "[bootstrap] npm is not available after dependency install" >&2
+    exit 1
+  fi
+  local home_dir
+  home_dir="${HOME:?HOME is required}"
+  echo "[bootstrap] installing/updating kitowall CLI in user prefix ($home_dir/.local)"
+  npm i -g --prefix "$home_dir/.local" kitowall
+}
+
+install_github_release_bin() {
+  local repo="$1"         # owner/name
+  local asset_name="$2"   # exact asset name
+  local out_bin="$3"      # absolute output path
+
+  if ! need_cmd curl; then
+    echo "[bootstrap] missing curl for GitHub release install" >&2
+    return 1
+  fi
+
+  local asset_url="https://github.com/${repo}/releases/latest/download/${asset_name}"
+  local release_tag=""
+  local out_dir tmp_bin
+  out_dir="$(dirname "$out_bin")"
+  mkdir -p "$out_dir"
+  tmp_bin="$(mktemp "${out_dir}/.${asset_name}.XXXXXX.tmp")"
+
+  echo "[bootstrap] downloading ${repo} asset: ${asset_name}"
+  if ! curl -fL \
+      --retry 3 \
+      --retry-delay 2 \
+      -H "User-Agent: Kitowall-Bootstrap" \
+      -H "Accept: application/octet-stream" \
+      "$asset_url" -o "$tmp_bin"; then
+    rm -f "$tmp_bin"
+    release_tag="$(latest_release_tag "$repo" || true)"
+    if [[ -n "${release_tag:-}" ]]; then
+      asset_url="https://github.com/${repo}/releases/download/${release_tag}/${asset_name}"
+      echo "[bootstrap] retrying ${repo} asset with explicit tag: ${release_tag}"
+      tmp_bin="$(mktemp "${out_dir}/.${asset_name}.XXXXXX.tmp")"
+      if ! curl -fL \
+          --retry 3 \
+          --retry-delay 2 \
+          -H "User-Agent: Kitowall-Bootstrap" \
+          -H "Accept: application/octet-stream" \
+          "$asset_url" -o "$tmp_bin"; then
+        rm -f "$tmp_bin"
+        return 1
+      fi
+    else
+      return 1
+    fi
+  fi
+  chmod 755 "$tmp_bin"
+  mv -f "$tmp_bin" "$out_bin"
+}
+
+latest_release_tag() {
+  local repo="$1"
+
+  if ! need_cmd curl || ! need_cmd jq; then
+    return 1
+  fi
+
+  curl -fsSL "https://api.github.com/repos/${repo}/releases/latest" | jq -r '.tag_name // empty'
+}
+
+write_kitsune_wrapper() {
+  local home_dir="${HOME:?HOME is required}"
+  local share_dir="$home_dir/.local/share/kitsune"
+  local config_dir="$home_dir/.config/kitsune"
+  local state_dir="$home_dir/.local/state/kitsune"
+
+  mkdir -p "$home_dir/.local/bin" "$config_dir" "$state_dir/run"
+  rm -f "$home_dir/.local/bin/kitsune"
+  cat > "$home_dir/.local/bin/kitsune" <<EOF
+#!/usr/bin/env bash
+set -euo pipefail
+export KITSUNE_HOME="$share_dir"
+export KITSUNE_BIN_DIR="$share_dir/bin"
+export KITSUNE_CFG="$config_dir/base.conf"
+export KITSUNE_CAVA_CFG="$config_dir/cava.conf"
+export KITSUNE_RUN_PREFIX="$state_dir/run"
+mkdir -p "\$KITSUNE_RUN_PREFIX"
+exec "$share_dir/scripts/kitsune.sh" "\$@"
+EOF
+  chmod 755 "$home_dir/.local/bin/kitsune"
+}
+
+is_kitsune_bundle_corrupted() {
+  local home_dir="${HOME:?HOME is required}"
+  local script_path="$home_dir/.local/share/kitsune/scripts/kitsune.sh"
+
+  [[ ! -f "$script_path" ]] && return 0
+  grep -Fq 'exec "/home/' "$script_path" && grep -Fq '/scripts/kitsune.sh" "$@"' "$script_path"
+}
+
+is_kitsune_binary_corrupted() {
+  local home_dir="${HOME:?HOME is required}"
+  local bin_path="$home_dir/.local/share/kitsune/bin/kitsune"
+
+  [[ ! -f "$bin_path" ]] && return 0
+  file "$bin_path" 2>/dev/null | grep -Fq 'ELF' || return 0
+  return 1
+}
+
+repair_kitsune_host_layout() {
+  local home_dir="${HOME:?HOME is required}"
+  local share_dir="$home_dir/.local/share/kitsune"
+  local config_dir="$home_dir/.config/kitsune"
+  local state_dir="$home_dir/.local/state/kitsune"
+
+  if [[ ! -d "$share_dir/scripts" || ! -d "$share_dir/bin" ]]; then
+    echo "[bootstrap] kitsune share layout missing in $share_dir; run full bootstrap first" >&2
+    return 1
+  fi
+
+  if is_kitsune_binary_corrupted; then
+    echo "[bootstrap] kitsune binary is corrupted; restoring binaries from latest release"
+    install_kitsune_bins
+    return 0
+  fi
+
+  if is_kitsune_bundle_corrupted; then
+    echo "[bootstrap] kitsune bundle is corrupted; restoring bundle from latest release"
+    install_kitsune_bundle
+    return 0
+  fi
+
+  mkdir -p "$config_dir" "$state_dir/run"
+  if [[ -f "$share_dir/config/base.conf" && ! -f "$config_dir/base.conf" ]]; then
+    cp "$share_dir/config/base.conf" "$config_dir/base.conf"
+  fi
+  if [[ -f "$share_dir/config/cava.conf" && ! -f "$config_dir/cava.conf" ]]; then
+    cp "$share_dir/config/cava.conf" "$config_dir/cava.conf"
+  fi
+
+  write_kitsune_wrapper
+  echo "[bootstrap] repaired kitsune host layout"
+}
+
+install_kitsune_bundle() {
+  local home_dir="${HOME:?HOME is required}"
+  local share_dir="$home_dir/.local/share/kitsune"
+  local config_dir="$home_dir/.config/kitsune"
+  local state_dir="$home_dir/.local/state/kitsune"
+  local tmp_dir
+  tmp_dir="$(mktemp -d)"
+
+  if ! need_cmd curl || ! need_cmd jq || ! need_cmd tar; then
+    echo "[bootstrap] missing curl/jq/tar for kitsune bundle install" >&2
+    rm -rf "$tmp_dir"
+    return 1
+  fi
+
+  local api_url="https://api.github.com/repos/KitotsuMolina/Kitsune/releases/latest"
+  local tar_url
+  tar_url="$(curl -fsSL "$api_url" | jq -r '.tarball_url // empty')"
+  if [[ -z "${tar_url:-}" || "$tar_url" == "null" ]]; then
+    echo "[bootstrap] kitsune release tarball URL not found" >&2
+    rm -rf "$tmp_dir"
+    return 1
+  fi
+
+  echo "[bootstrap] downloading kitsune bundle sources"
+  curl -fL --retry 3 --retry-delay 2 "$tar_url" -o "$tmp_dir/kitsune.tar.gz"
+  tar -xzf "$tmp_dir/kitsune.tar.gz" -C "$tmp_dir"
+  local src_dir
+  src_dir="$(find "$tmp_dir" -mindepth 1 -maxdepth 1 -type d | head -n1)"
+  if [[ -z "${src_dir:-}" || ! -d "$src_dir/scripts" || ! -d "$src_dir/config" ]]; then
+    echo "[bootstrap] invalid kitsune source layout in tarball" >&2
+    rm -rf "$tmp_dir"
+    return 1
+  fi
+
+  mkdir -p "$share_dir" "$config_dir" "$state_dir"
+  rm -rf "$share_dir/scripts" "$share_dir/config" "$share_dir/completions"
+  cp -a "$src_dir/scripts" "$share_dir/"
+  cp -a "$src_dir/config" "$share_dir/"
+  [[ -d "$src_dir/completions" ]] && cp -a "$src_dir/completions" "$share_dir/" || true
+  mkdir -p "$share_dir/bin"
+
+  if [[ ! -f "$config_dir/base.conf" ]]; then
+    cp "$share_dir/config/base.conf" "$config_dir/base.conf"
+  fi
+  if [[ ! -f "$config_dir/cava.conf" ]]; then
+    cp "$share_dir/config/cava.conf" "$config_dir/cava.conf"
+  fi
+
+  # Ensure scripts point to prebuilt binaries instead of local cargo build paths.
+  sed -i \
+    -e '/^echo "\[i\] Building Rust renderer\.\.\."$/d' \
+    -e '/^cargo build --release --locked --bins$/d' \
+    -e '/^cargo build --release --bins$/d' \
+    -e '/^echo "\[i\] Building GTK overlay frontend\.\.\."$/d' \
+    -e '/^cargo build --release --bin kitsune-overlay$/d' \
+    -e 's|\./target/release/kitsune-overlay|"${KITSUNE_BIN_DIR:-./bin}"/kitsune-overlay|g' \
+    -e 's|\./target/release/kitsune|"${KITSUNE_BIN_DIR:-./bin}"/kitsune|g' \
+    -e 's|"${KITSUNE_BIN_DIR:-./bin}"/kitsune --config|"${KITSUNE_BIN_DIR:-./bin}"/kitsune run --config|g' \
+    "$share_dir/scripts/start.sh" \
+    "$share_dir/scripts/kitsune.sh"
+  sed -i -e '/^cargo build --release$/d' "$share_dir/scripts/install.sh" || true
+
+  write_kitsune_wrapper
+
+  rm -rf "$tmp_dir"
+}
+
+cargo_install_git_bin() {
+  local repo="$1"
+  local bin="$2"
+  local extra_args="$3"
+  local tag="${4:-}"
+
+  local args=(install --git "$repo" --locked --force "$bin")
+  if [[ -n "$tag" ]]; then
+    args+=(--tag "$tag")
+  fi
+  if [[ -n "$extra_args" ]]; then
+    # shellcheck disable=SC2206
+    local split_extra=($extra_args)
+    args+=("${split_extra[@]}")
+  fi
+
+  echo "[bootstrap] cargo ${args[*]}"
+  cargo "${args[@]}"
+}
+
+install_kitsune_bins() {
+  local home_dir="${HOME:?HOME is required}"
+  local bin_dir="$home_dir/.local/bin"
+  local share_bin_dir="$home_dir/.local/share/kitsune/bin"
+  local release_ok=0
+  mkdir -p "$share_bin_dir"
+
+  # Prefer prebuilt binaries from GitHub Releases to avoid local toolchain/submodule issues.
+  if install_github_release_bin "KitotsuMolina/Kitsune" "kitsune-linux-x86_64" "$share_bin_dir/kitsune" && \
+     install_github_release_bin "KitotsuMolina/Kitsune" "kitsune-overlay-linux-x86_64" "$share_bin_dir/kitsune-overlay" && \
+     install_github_release_bin "KitotsuMolina/Kitsune" "kitsune-color-resolve-linux-x86_64" "$share_bin_dir/kitsune-color-resolve" && \
+     install_github_release_bin "KitotsuMolina/Kitsune-RenderCore" "kitsune-rendercore-linux-x86_64" "$bin_dir/kitsune-rendercore"; then
+    ln -sf "$share_bin_dir/kitsune-overlay" "$bin_dir/kitsune-overlay"
+    ln -sf "$share_bin_dir/kitsune-color-resolve" "$bin_dir/kitsune-color-resolve"
+    BOOTSTRAP_KITSUNE_VERSION="$(latest_release_tag "KitotsuMolina/Kitsune" | sed 's/^v//')"
+    BOOTSTRAP_RENDERCORE_VERSION="$(latest_release_tag "KitotsuMolina/Kitsune-RenderCore" | sed 's/^v//')"
+    release_ok=1
+  fi
+
+  if [[ "$release_ok" -eq 1 ]]; then
+    install_kitsune_bundle || echo "[bootstrap] warning: failed to install kitsune script bundle; falling back to raw binary command" >&2
+    return
+  fi
+
+  echo "[bootstrap] warning: release binary install failed, falling back to cargo install" >&2
+  if ! need_cmd cargo; then
+    echo "[bootstrap] cargo is not available after dependency install" >&2
+    exit 1
+  fi
+  cargo_install_git_bin "$KITSUNE_REPO" kitsune "" "$KITSUNE_TAG"
+  cargo_install_git_bin "$KITSUNE_RENDERCORE_REPO" kitsune-rendercore "--features wayland-layer" "$KITSUNE_RENDERCORE_TAG"
+  BOOTSTRAP_KITSUNE_VERSION="${KITSUNE_TAG#v}"
+  BOOTSTRAP_RENDERCORE_VERSION="${KITSUNE_RENDERCORE_TAG#v}"
+}
+
+ensure_rendercore_service() {
+  if ! need_cmd kitsune-rendercore; then
+    echo "[bootstrap] warning: kitsune-rendercore binary not found; skipping service install" >&2
+    return
+  fi
+
+  local home_dir="${HOME:?HOME is required}"
+  local user_systemd_dir="$home_dir/.config/systemd/user"
+  local app_config_dir="$home_dir/.config/kitsune-rendercore"
+  local env_dst="$app_config_dir/env"
+  local map_dst="$app_config_dir/video-map.conf"
+  local bin_path
+  bin_path="$(command -v kitsune-rendercore || true)"
+  if [[ -z "$bin_path" ]]; then
+    echo "[bootstrap] warning: kitsune-rendercore binary path not found; skipping service install" >&2
+    return
+  fi
+
+  mkdir -p "$user_systemd_dir" "$app_config_dir"
+  if [[ ! -f "$env_dst" ]]; then
+    cat > "$env_dst" <<EOF
+# Kitsune RenderCore user env
+KRC_VIDEO_MAP_FILE=$map_dst
+KRC_VIDEO_FPS=30
+KRC_VIDEO_SPEED=1.0
+KRC_QUALITY=high
+KRC_PAUSE_ON_STEAM_GAME=true
+KRC_STEAM_POLL_MS=1000
+EOF
+  fi
+  if [[ ! -f "$map_dst" ]]; then
+    : > "$map_dst"
+  fi
+
+  cat > "$user_systemd_dir/kitsune-rendercore.service" <<EOF
+[Unit]
+Description=Kitsune RenderCore Live Wallpaper
+After=graphical-session.target
+Wants=graphical-session.target
+
+[Service]
+Type=simple
+Environment=PATH=$home_dir/.local/bin:$home_dir/.cargo/bin:/usr/local/bin:/usr/bin:/bin
+EnvironmentFile=-$env_dst
+ExecStart=$bin_path
+Restart=on-failure
+RestartSec=1
+
+[Install]
+WantedBy=default.target
+EOF
+
+  systemctl --user daemon-reload || true
+  systemctl --user enable kitsune-rendercore.service || true
+}
+
+verify_bins() {
+  local required_bins=()
+  if [[ "$KITOWALL_BOOTSTRAP_MODE" == "kitsune-only" || "$KITOWALL_BOOTSTRAP_MODE" == "kitsune-repair" ]]; then
+    required_bins=(kitsune kitsune-rendercore)
+  elif [[ "$KITOWALL_BOOTSTRAP_MODE" == "kitowall-only" ]]; then
+    required_bins=(kitowall)
+  else
+    required_bins=(kitowall kitsune kitsune-rendercore swww swww-daemon cava)
+  fi
+  local missing=()
+  for b in "${required_bins[@]}"; do
+    if ! need_cmd "$b"; then
+      missing+=("$b")
+    fi
+  done
+
+  if ((${#missing[@]} > 0)); then
+    echo "[bootstrap] missing binaries after bootstrap: ${missing[*]}" >&2
+
+    local needs_kitsune_recovery=0
+    for b in "${missing[@]}"; do
+      if [[ "$b" == "kitsune" || "$b" == "kitsune-rendercore" ]]; then
+        needs_kitsune_recovery=1
+        break
+      fi
+    done
+
+    if [[ "$needs_kitsune_recovery" -eq 1 ]]; then
+      echo "[bootstrap] attempting release-based recovery for Kitsune binaries" >&2
+      install_kitsune_bins
+      missing=()
+      for b in "${required_bins[@]}"; do
+        if ! need_cmd "$b"; then
+          missing+=("$b")
+        fi
+      done
+    fi
+
+    if ((${#missing[@]} > 0)); then
+      echo "[bootstrap] missing binaries after recovery: ${missing[*]}" >&2
+      exit 2
+    fi
+  fi
+}
+
+write_bootstrap_versions() {
+  local home_dir="${HOME:?HOME is required}"
+  local state_dir="$home_dir/.local/share/kitowall"
+  local state_file="$state_dir/bootstrap-versions.json"
+
+  mkdir -p "$state_dir"
+  cat > "$state_file" <<EOF
+{
+  "kitsune": {
+    "version": "${BOOTSTRAP_KITSUNE_VERSION}",
+    "source": "${KITOWALL_BOOTSTRAP_MODE}"
+  },
+  "kitsune-rendercore": {
+    "version": "${BOOTSTRAP_RENDERCORE_VERSION}",
+    "source": "${KITOWALL_BOOTSTRAP_MODE}"
+  }
+}
+EOF
+}
+
+main() {
+  # Some launchers provide a stale/non-existent CWD; recover to HOME.
+  cd "${HOME:?HOME is required}" || true
+  # Clean host Python env that can break AUR build tools (meson/python).
+  unset PYTHONHOME || true
+  unset PYTHONPATH || true
+
+  ensure_user_bin_dirs
+  if [[ "$KITOWALL_BOOTSTRAP_MODE" == "kitsune-repair" ]]; then
+    repair_kitsune_host_layout
+    verify_bins
+    echo "[ok] kitsune host repair complete"
+    exit 0
+  fi
+  if [[ "$KITOWALL_BOOTSTRAP_MODE" == "kitowall-only" ]]; then
+    if [[ "$KITOWALL_SKIP_SYSTEM_DEPS" != "1" ]]; then
+      install_system_deps
+    fi
+    install_kitowall_cli
+    verify_bins
+    echo "[ok] kitowall bootstrap complete"
+    echo "[paths] HOME=$HOME"
+    echo "[paths] kitowall=$(command -v kitowall || echo '<missing>')"
+    echo "[info] bootstrap finished; manual init is only needed on a fresh host without config"
+    exit 0
+  fi
+  if [[ "$KITOWALL_BOOTSTRAP_MODE" != "kitsune-only" && "$KITOWALL_SKIP_SYSTEM_DEPS" != "1" ]]; then
+    install_system_deps
+    install_kitowall_cli
+  elif [[ "$KITOWALL_BOOTSTRAP_MODE" != "kitsune-only" ]]; then
+    install_kitowall_cli
+  fi
+  install_kitsune_bins
+  ensure_rendercore_service
+  write_bootstrap_versions
+  verify_bins
+  echo "[ok] host bootstrap complete"
+  echo "[paths] HOME=$HOME"
+  echo "[paths] kitowall=$(command -v kitowall || echo '<missing>')"
+  echo "[paths] kitsune=$(command -v kitsune || echo '<missing>')"
+  echo "[paths] kitsune-rendercore=$(command -v kitsune-rendercore || echo '<missing>')"
+  echo "[info] bootstrap finished; manual init is only needed on a fresh host without config"
+}
+
+main "$@"

package/scripts/bootstrap-system.sh

@@ -0,0 +1,187 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Root-only helper for installing host system packages.
+# Intended to be invoked via pkexec from Kitowall.
+
+need_cmd() {
+  command -v "$1" >/dev/null 2>&1
+}
+
+require_root() {
+  if [[ "${EUID:-$(id -u)}" -ne 0 ]]; then
+    echo "[bootstrap-system] this helper must run as root" >&2
+    exit 1
+  fi
+}
+
+wait_pacman_lock() {
+  local lock_file="/var/lib/pacman/db.lck"
+  local tries=0
+  local max_tries=40
+
+  while [[ -e "$lock_file" ]]; do
+    if pgrep -x pacman >/dev/null 2>&1 || \
+       pgrep -x yay >/dev/null 2>&1 || \
+       pgrep -x paru >/dev/null 2>&1 || \
+       pgrep -x makepkg >/dev/null 2>&1; then
+      tries=$((tries + 1))
+      if ((tries > max_tries)); then
+        echo "[bootstrap-system] pacman lock busy for too long: $lock_file" >&2
+        return 1
+      fi
+      echo "[bootstrap-system] waiting for pacman lock (${tries}/${max_tries})..."
+      sleep 3
+      continue
+    fi
+
+    echo "[bootstrap-system] removing stale pacman lock: $lock_file"
+    rm -f "$lock_file"
+    break
+  done
+}
+
+install_arch_deps() {
+  local repo_pkgs=(
+    nodejs npm
+    hyprland
+    swww
+    cava
+    pkgconf
+    gtk4
+    gtk4-layer-shell
+    jq
+    git
+    base-devel
+  )
+
+  if need_cmd rustup; then
+    repo_pkgs+=(rustup)
+  elif need_cmd rustc && need_cmd cargo; then
+    :
+  else
+    repo_pkgs+=(rustup)
+  fi
+
+  echo "[bootstrap-system] installing Arch packages: ${repo_pkgs[*]}"
+  wait_pacman_lock
+  pacman -S --needed --noconfirm "${repo_pkgs[@]}"
+}
+
+arch_packages_for_ids() {
+  local id
+  local pkgs=()
+  for id in "$@"; do
+    case "$id" in
+      nodejs) pkgs+=(nodejs) ;;
+      npm) pkgs+=(npm) ;;
+      hyprctl) pkgs+=(hyprland) ;;
+      swww|swww-daemon) pkgs+=(swww) ;;
+      cava) pkgs+=(cava) ;;
+      pkgconf) pkgs+=(pkgconf) ;;
+      gtk4) pkgs+=(gtk4) ;;
+      gtk4-layer-shell) pkgs+=(gtk4-layer-shell) ;;
+      jq) pkgs+=(jq) ;;
+      git) pkgs+=(git) ;;
+      base-devel) pkgs+=(base-devel) ;;
+      rustup|cargo|rustc) pkgs+=(rustup) ;;
+    esac
+  done
+  printf '%s\n' "${pkgs[@]}" | awk 'NF && !seen[$0]++'
+}
+
+install_arch_selected() {
+  local requested=("$@")
+  local repo_pkgs=()
+  mapfile -t repo_pkgs < <(arch_packages_for_ids "${requested[@]}")
+  if ((${#repo_pkgs[@]} == 0)); then
+    echo "[bootstrap-system] no supported Arch packages mapped from: ${requested[*]}" >&2
+    return 1
+  fi
+  echo "[bootstrap-system] installing selected Arch packages: ${repo_pkgs[*]}"
+  wait_pacman_lock
+  pacman -S --needed --noconfirm "${repo_pkgs[@]}"
+}
+
+install_ubuntu_deps() {
+  local pkgs=(
+    nodejs npm
+    rustc cargo
+    pkg-config
+    libgtk-4-dev
+    jq curl git
+    cava
+  )
+  echo "[bootstrap-system] installing Debian/Ubuntu packages: ${pkgs[*]}"
+  apt-get update
+  apt-get install -y "${pkgs[@]}"
+}
+
+ubuntu_packages_for_ids() {
+  local id
+  local pkgs=()
+  for id in "$@"; do
+    case "$id" in
+      nodejs) pkgs+=(nodejs) ;;
+      npm) pkgs+=(npm) ;;
+      cava) pkgs+=(cava) ;;
+      jq) pkgs+=(jq) ;;
+      git) pkgs+=(git) ;;
+      rustup|cargo|rustc) pkgs+=(rustc cargo) ;;
+      pkgconf) pkgs+=(pkg-config) ;;
+      gtk4) pkgs+=(libgtk-4-dev) ;;
+    esac
+  done
+  printf '%s\n' "${pkgs[@]}" | awk 'NF && !seen[$0]++'
+}
+
+install_ubuntu_selected() {
+  local requested=("$@")
+  local pkgs=()
+  mapfile -t pkgs < <(ubuntu_packages_for_ids "${requested[@]}")
+  if ((${#pkgs[@]} == 0)); then
+    echo "[bootstrap-system] no supported Debian/Ubuntu packages mapped from: ${requested[*]}" >&2
+    return 1
+  fi
+  echo "[bootstrap-system] installing selected Debian/Ubuntu packages: ${pkgs[*]}"
+  apt-get update
+  apt-get install -y "${pkgs[@]}"
+}
+
+main() {
+  require_root
+
+  if (($# > 0)); then
+    if need_cmd pacman; then
+      install_arch_selected "$@"
+      echo "[ok] selected system dependencies installed"
+      exit 0
+    fi
+
+    if need_cmd apt-get; then
+      install_ubuntu_selected "$@"
+      echo "[ok] selected system dependencies installed"
+      exit 0
+    fi
+
+    echo "[bootstrap-system] unsupported distro package manager for selected install: $*" >&2
+    exit 1
+  fi
+
+  if need_cmd pacman; then
+    install_arch_deps
+    echo "[ok] system dependencies installed"
+    exit 0
+  fi
+
+  if need_cmd apt-get; then
+    install_ubuntu_deps
+    echo "[ok] system dependencies installed"
+    exit 0
+  fi
+
+  echo "[bootstrap-system] unsupported distro package manager. Install manually: nodejs npm rust cargo pkg-config gtk4 gtk4-layer-shell swww hyprland cava" >&2
+  exit 1
+}
+
+main "$@"