panll-launcher.sh

#!/usr/bin/env bash
# SPDX-License-Identifier: MPL-2.0
# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>
#
# @a2ml-metadata begin
# (
#   id                   = "panll-launcher"
#   type                 = "launcher"
#   version              = "0.2.0"
#   app-name             = "panll"
#   app-display          = "PanLL"
#   app-url              = "http://localhost:8000/public/"
#   runtime-kind         = "server-url"
#   standards-compliance = [
#     "launcher-standard.adoc"
#     "LM-LA-LIFECYCLE-STANDARD.adoc"
#     "cross-platform-system-integration-modes"
#   ]
#   standard-spec-version = "0.1.0"
#   generator             = "launch-scaffolder"
# )
# @a2ml-metadata end
#
# ============================================================================
# panll-launcher.sh — PanLL
# ============================================================================
# GENERATED by launch-scaffolder from panll.launcher.a2ml.
# Do NOT edit this file directly — your edits will be overwritten on the next
# `launch-scaffolder realign`. Put per-app tweaks in the [exceptions] block of
# the .launcher.a2ml config instead.
# ============================================================================

set -euo pipefail

# ----------------------------------------------------------------------------
# CONFIGURATION
# ----------------------------------------------------------------------------

APP_NAME="panll"
APP_DISPLAY="PanLL"
APP_DESC="PanLL — panels framework (TEA + workspace layer + Stapeln integration)"
APP_CATEGORIES="Development;Utility;"
APP_GENERIC_NAME="PanLL"
RUNTIME_KIND="server-url"

REPO_DIR="/var/mnt/eclipse/repos/panll"
ICON_SOURCE="/var/mnt/eclipse/repos/panll/assets/icon-256.png"

# Absolute path back to the per-app `<app>.launcher.a2ml` config that
# produced this script. Consumed by the --integ / --disinteg arms when
# the `launch-scaffolder` binary is on $PATH, so they can delegate to
# the Rust implementation instead of running the shell fallback.
CONFIG_FILE="/var/mnt/eclipse/repos/panll/panll.launcher.a2ml"

URL="http://localhost:8000/public/"
APP_PORT="8000"
WAIT_SECONDS="15"

PID_FILE="/tmp/panll-server.pid"
LOG_FILE="/tmp/panll-server.log"

# Explicit argv from [runtime].command
START_COMMAND=(just serve )

MODE="${1:---auto}"
FORCE="false"
[[ "${2:-}" == "--force" ]] && FORCE="true"

# ----------------------------------------------------------------------------
# LOGGING HELPERS
# ----------------------------------------------------------------------------

log()  { echo -e "\033[0;32m[$APP_DISPLAY]\033[0m $1"; }
warn() { echo -e "\033[0;33m[$APP_DISPLAY]\033[0m $1" >&2; }
err()  { echo -e "\033[0;31m[$APP_DISPLAY]\033[0m ERROR: $1" >&2; }

is_gui_context() {
    [ ! -t 2 ] && { [ -n "${DISPLAY:-}" ] || [ -n "${WAYLAND_DISPLAY:-}" ]; }
}

gui_error() {
    local title="$1"
    local body="$2"
    err "$title"
    echo "$body" | sed 's/^/  /' >&2
    if is_gui_context; then
        if   command -v kdialog     >/dev/null 2>&1; then kdialog --title "$APP_DISPLAY: $title" --error "$body" 2>/dev/null &
        elif command -v zenity      >/dev/null 2>&1; then zenity --error --title="$APP_DISPLAY: $title" --text="$body" --width=500 2>/dev/null &
        elif command -v notify-send >/dev/null 2>&1; then notify-send --urgency=critical --icon=dialog-error "$APP_DISPLAY: $title" "$body" 2>/dev/null &
        elif command -v xmessage    >/dev/null 2>&1; then xmessage -center "$APP_DISPLAY: $title\n\n$body" 2>/dev/null &
        fi
    fi
}

# ----------------------------------------------------------------------------
# PLATFORM DETECTION
# ----------------------------------------------------------------------------

detect_platform() {
    case "$(uname -s)" in
        Linux*)                          echo "linux"   ;;
        Darwin*)                         echo "macos"   ;;
        CYGWIN*|MINGW*|MSYS*|Windows_NT) echo "windows" ;;
        *)                               echo "unknown" ;;
    esac
}
PLATFORM="$(detect_platform)"

case "$PLATFORM" in
    linux)
        APPS_DIR="$HOME/.local/share/applications"
        ICON_DIR="$HOME/.local/share/icons/hicolor/256x256/apps"
        DESKTOP_SHORTCUT_DIR="$HOME/Desktop"
        BIN_DIR="$HOME/.local/bin"
        DESKTOP_FILE_TARGET="$APPS_DIR/${APP_NAME}.desktop"
        DESKTOP_SHORTCUT_TARGET="$DESKTOP_SHORTCUT_DIR/${APP_NAME}.desktop"
        ICON_TARGET="$ICON_DIR/${APP_NAME}.png"
        LAUNCHER_TARGET="$BIN_DIR/${APP_NAME}-launcher"
        ;;
    macos)
        APPS_DIR="$HOME/Applications"
        DESKTOP_SHORTCUT_DIR="$HOME/Desktop"
        BIN_DIR="$HOME/.local/bin"
        DESKTOP_FILE_TARGET="$APPS_DIR/${APP_DISPLAY}.app"
        DESKTOP_SHORTCUT_TARGET="$DESKTOP_SHORTCUT_DIR/${APP_DISPLAY}.command"
        ICON_TARGET="$APPS_DIR/${APP_DISPLAY}.app/Contents/Resources/icon.png"
        LAUNCHER_TARGET="$BIN_DIR/${APP_NAME}-launcher"
        ;;
    windows)
        APPDATA_DIR="${APPDATA:-$HOME/AppData/Roaming}"
        START_MENU_DIR="$APPDATA_DIR/Microsoft/Windows/Start Menu/Programs"
        DESKTOP_SHORTCUT_DIR="$HOME/Desktop"
        BIN_DIR="$HOME/.local/bin"
        DESKTOP_FILE_TARGET="$START_MENU_DIR/${APP_DISPLAY}.lnk"
        DESKTOP_SHORTCUT_TARGET="$DESKTOP_SHORTCUT_DIR/${APP_DISPLAY}.lnk"
        ICON_TARGET="$BIN_DIR/${APP_NAME}.ico"
        LAUNCHER_TARGET="$BIN_DIR/${APP_NAME}-launcher.sh"
        ;;
    *)
        APPS_DIR=""; DESKTOP_SHORTCUT_DIR=""; BIN_DIR="$HOME/.local/bin"
        DESKTOP_FILE_TARGET=""; DESKTOP_SHORTCUT_TARGET=""; ICON_TARGET=""
        LAUNCHER_TARGET="$BIN_DIR/${APP_NAME}-launcher"
        ;;
esac

# ----------------------------------------------------------------------------
# PROCESS MANAGEMENT
# ----------------------------------------------------------------------------

is_running() {
    [ -f "$PID_FILE" ] && kill -0 "$(cat "$PID_FILE")" 2>/dev/null
}

clear_stale_pid() {
    if [ -f "$PID_FILE" ] && ! kill -0 "$(cat "$PID_FILE")" 2>/dev/null; then
        rm -f "$PID_FILE"
    fi
}

wait_for_url() {
    local max_wait=${1:-15}
    local waited=0
    while [ "$waited" -lt "$max_wait" ]; do
        if command -v curl >/dev/null 2>&1 && curl -fsS "$URL" >/dev/null 2>&1; then
            return 0
        fi
        sleep 1
        waited=$((waited + 1))
    done
    return 1
}

start_server() {
    clear_stale_pid
if is_running; then
        log "Already running (PID $(cat "$PID_FILE"))"
        return 0
    fi

    if [ -z "${START_COMMAND:-}" ] || { [ ! "${START_COMMAND:0:1}" = "(" ] && [ ! -x "${START_COMMAND%% *}" ] && ! command -v "${START_COMMAND%% *}" >/dev/null 2>&1; }; then
        if [ -z "${START_COMMAND:-}" ]; then
            gui_error "No startup command found" \
"$APP_DISPLAY is installed, but I don't know how to start it. Check the
[runtime].startup-command-search or [runtime].command in panll.launcher.a2ml."
            return 1
        fi
    fi

    log "Starting $APP_DISPLAY..."
    cd "$REPO_DIR" 2>/dev/null || true
nohup "${START_COMMAND[@]}" >"$LOG_FILE" 2>&1 &
    echo $! > "$PID_FILE"

    sleep 0.2
    if ! kill -0 "$(cat "$PID_FILE")" 2>/dev/null; then
        gui_error "Process exited immediately" "Check $LOG_FILE"
        rm -f "$PID_FILE"
        return 1
    fi

if ! wait_for_url "$WAIT_SECONDS"; then
        gui_error "Server did not start" \
"$APP_DISPLAY did not become reachable at $URL within $WAIT_SECONDS seconds.
Check $LOG_FILE — and try: curl -v $URL"
        if command -v feedback-o-tron >/dev/null 2>&1; then
            feedback-o-tron --event "launcher:start_failed" \
                --app "$APP_NAME" --url "$URL" --log "$LOG_FILE" \
                --error "Timeout after $WAIT_SECONDS seconds" 2>/dev/null || true
        fi
        return 1
    fi
    log "Server started (PID $(cat "$PID_FILE")) — $URL"
    return 0
}

stop_server() {
if ! is_running; then
        log "No running instance found"
        return 0
    fi
    log "Stopping $APP_DISPLAY..."
    kill "$(cat "$PID_FILE")" 2>/dev/null || true
    rm -f "$PID_FILE"
    log "Stopped"
}

open_browser() {
    if [ -z "$URL" ]; then
        log "No URL configured for $APP_DISPLAY"
        return 1
    fi
if ! is_running; then
        err "Server is not running — use --start or --auto first"
        return 1
    fi
    log "Opening $URL..."
    case "$PLATFORM" in
        linux)
            if   command -v xdg-open >/dev/null 2>&1; then xdg-open "$URL" &
            elif command -v firefox  >/dev/null 2>&1; then firefox  "$URL" &
            elif command -v chromium >/dev/null 2>&1; then chromium "$URL" &
            else warn "No browser found — open manually: $URL"; fi ;;
        macos)   open "$URL" 2>/dev/null || warn "Open manually: $URL" ;;
        windows)
            if   command -v start    >/dev/null 2>&1; then start    "$URL"
            elif command -v cygstart >/dev/null 2>&1; then cygstart "$URL"
            else warn "Open manually: $URL"; fi ;;
        *) warn "Unknown platform — open manually: $URL" ;;
    esac
}

# ----------------------------------------------------------------------------
# SYSTEM INTEGRATION — --integ / --disinteg
# ----------------------------------------------------------------------------

already_integrated() {
    [ -f "$DESKTOP_FILE_TARGET" ] || [ -f "$LAUNCHER_TARGET" ]
}

write_linux_desktop_file() {
    local target="$1"
    local icon_name
    if [ -f "$ICON_TARGET" ]; then
        icon_name="$APP_NAME"
    else
        icon_name="package-x-generic"
    fi
    cat > "$target" <<EOF
[Desktop Entry]
Type=Application
Version=1.0
Name=$APP_DISPLAY
GenericName=$APP_GENERIC_NAME
Comment=$APP_DESC
Exec=$LAUNCHER_TARGET --auto
Icon=$icon_name
Terminal=false
Categories=$APP_CATEGORIES
StartupNotify=true
StartupWMClass=$APP_NAME
Actions=stop;status;

[Desktop Action stop]
Name=Stop
Exec=$LAUNCHER_TARGET --stop

[Desktop Action status]
Name=Status
Exec=$LAUNCHER_TARGET --status
EOF
    chmod 444 "$target"
}

do_integ_linux() {
    mkdir -p "$APPS_DIR" "$ICON_DIR" "$BIN_DIR" "$DESKTOP_SHORTCUT_DIR"
    local script_path="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/$(basename "${BASH_SOURCE[0]}")"
    cp "$script_path" "$LAUNCHER_TARGET"
    chmod +x "$LAUNCHER_TARGET"
    log "  + launcher: $LAUNCHER_TARGET"

    if [ -n "$ICON_SOURCE" ] && [ -f "$ICON_SOURCE" ]; then
        cp "$ICON_SOURCE" "$ICON_TARGET"
        log "  + icon:     $ICON_TARGET"
    else
        log "  · no custom icon — using system fallback (package-x-generic)"
    fi

    write_linux_desktop_file "$DESKTOP_FILE_TARGET"
    log "  + menu:     $DESKTOP_FILE_TARGET"
    write_linux_desktop_file "$DESKTOP_SHORTCUT_TARGET"
    log "  + desktop:  $DESKTOP_SHORTCUT_TARGET"

    command -v update-desktop-database >/dev/null 2>&1 && \
        update-desktop-database "$APPS_DIR" 2>/dev/null || true
    if command -v gio >/dev/null 2>&1; then
        gio set "$DESKTOP_FILE_TARGET"     "metadata::trusted" true 2>/dev/null || true
        gio set "$DESKTOP_SHORTCUT_TARGET" "metadata::trusted" true 2>/dev/null || true
    fi
    if [ -x "/var/mnt/eclipse/repos/.desktop-tools/verify-desktop-integrity.sh" ]; then
        /var/mnt/eclipse/repos/.desktop-tools/verify-desktop-integrity.sh --generate 2>/dev/null \
            && log "  + integrity hashes generated" \
            || log "  · integrity hash generation failed (non-fatal)"
    fi
}

do_integ() {
    # Fast path: delegate to `launch-scaffolder provision` when it's on
    # $PATH and the source config is still where it was at mint time.
    # Keeps one authoritative implementation instead of drifting between
    # this template and the Rust binary. Falls through to the shell
    # implementation if either condition fails.
    if command -v launch-scaffolder >/dev/null 2>&1 && [ -n "$CONFIG_FILE" ] && [ -f "$CONFIG_FILE" ]; then
        local forward=(launch-scaffolder provision --integ "$CONFIG_FILE" --no-confirm)
        [ "$FORCE" = "true" ] && forward+=(--force)
        log "Delegating to launch-scaffolder provision..."
        exec "${forward[@]}"
    fi

    if already_integrated && [ "$FORCE" != "true" ]; then
        warn "$APP_DISPLAY is already integrated."
        read -rp "Reinstall? [y/N] " confirm
        [[ ! "$confirm" =~ ^[Yy]$ ]] && { log "Nothing changed."; return 0; }
    fi
    log "Integrating $APP_DISPLAY with the $PLATFORM desktop..."
    case "$PLATFORM" in
        linux) do_integ_linux ;;
        *)     err "Only Linux integration is implemented in the generated template so far."; return 1 ;;
    esac
    log "✓ $APP_DISPLAY is now in your menu and on your Desktop."
}

do_disinteg() {
    # Fast path: delegate to `launch-scaffolder provision --disinteg`
    # when available. Stop any running process first so the binary
    # doesn't have to re-implement the process-management arm.
if is_running; then
        log "  • stopping running server"
        stop_server
    fi
    if command -v launch-scaffolder >/dev/null 2>&1 && [ -n "$CONFIG_FILE" ] && [ -f "$CONFIG_FILE" ]; then
        log "Delegating to launch-scaffolder provision..."
        exec launch-scaffolder provision --disinteg "$CONFIG_FILE" --no-confirm
    fi

    log "Removing $APP_DISPLAY system integration..."
    local removed_anything="false"
    local targets=(
        "$DESKTOP_FILE_TARGET"
        "$DESKTOP_SHORTCUT_TARGET"
        "$ICON_TARGET"
        "$LAUNCHER_TARGET"
    )
    for t in "${targets[@]}"; do
        [ -z "$t" ] && continue
        if [ -e "$t" ] || [ -L "$t" ]; then
            rm -rf "$t"
            log "  - removed $t"
            removed_anything="true"
        fi
    done
    [ "$PLATFORM" = "linux" ] && command -v update-desktop-database >/dev/null 2>&1 && \
        update-desktop-database "$APPS_DIR" 2>/dev/null || true
    rm -f "$PID_FILE"
    if [ "$removed_anything" = "true" ]; then
        log "✓ $APP_DISPLAY removed from your system."
    else
        log "Nothing to remove — $APP_DISPLAY was not integrated here."
    fi
}

show_help() {
    cat <<EOF
$APP_DISPLAY launcher — $APP_DESC

Usage: $0 [MODE] [--force]

Runtime modes:

  --auto       Start server and open the browser (default)
  --start      Start the server only (no browser)
  --stop       Stop the running server
  --status     Show running status and URL
  --browser    Open the browser (server must already be running)

System integration:
  --integ      Install desktop entry + shortcut + icon (idempotent; --force to reinstall)
  --disinteg   Remove everything --integ installed (idempotent)

Misc:
  --help       This text

Detected platform: $PLATFORM
Runtime kind:      $RUNTIME_KIND
Repo:              $REPO_DIR
EOF
}

# ----------------------------------------------------------------------------
# MAIN SWITCH
# ----------------------------------------------------------------------------

case "$MODE" in
    --start)          start_server ;;
    --stop)           stop_server ;;
    --status)
        if is_running; then
            log "Running (PID $(cat "$PID_FILE"))${URL:+ — $URL}"
        else
            log "Not running${URL:+ — $URL}"
        fi
        ;;
    --browser|--web)
open_browser
        ;;
    --auto)
start_server && open_browser
        ;;
    --integ)          do_integ ;;
    --disinteg)       do_disinteg ;;
    --help|-h)        show_help ;;
    *)
        err "Unknown mode: $MODE"
        show_help
        exit 2
        ;;
esac