launcher-standard.a2ml

# SPDX-License-Identifier: PMPL-1.0-or-later
# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>
#
# launcher-standard.a2ml — canonical declarative description of a
# hyperpolymath-compliant desktop launcher.
#
# This file is the source of truth for what a compliant launcher looks like.
# It is baked into the launch-scaffolder binary at build time via
# include_str!(), and can be overridden at runtime via --standard <file> or
# $LAUNCH_SCAFFOLDER_STANDARD.
#
# See also:
#   - standards/rhodium-standard-repositories/spec/LANGUAGE-POLICY.adoc
#   - standards/docs/UX-standards/launcher-standard.adoc (prose version)
#   - standards/docs/UX-standards/LM-LA-LIFECYCLE-STANDARD.adoc (install/uninstall)

[spec]
version = "0.2.0"
date = "2026-04-17"
compliance = [
    "launcher-standard.adoc",
    "LM-LA-LIFECYCLE-STANDARD.adoc",
    "cross-platform-system-integration-modes",
    "fallback-ladder-keepopen",
]

[fallback-ladder]
# keepopen.sh wraps every primary desktop-file Exec line. It turns launcher
# failures from invisible flashes into loud, labelled banners, and lands the
# user in an interactive shell at the repo root if everything fails.
#
# See launcher-standard.adoc §Fallback Ladder for the prose version.
wrapper             = "keepopen.sh"
canonical-path      = "developer-ecosystem/standards/launcher/keepopen.sh"
deployed-symlink    = "/var/mnt/eclipse/repos/.desktop-tools/keepopen.sh"
calling-convention  = "keepopen.sh APP_NAME REPO_DIR \"GUI_CMD\" \"TUI_CMD\" [LOG_FILE]"
stages = [
    { name = "gui",   colour = "yellow", on-failure = "show-banner-then-try-tui" },
    { name = "tui",   colour = "red",    on-failure = "show-banner-then-drop-to-shell" },
    { name = "shell", colour = "green",  behaviour  = "exec-bash-login-at-repo-dir" },
]
banner-visibility = "loud"   # Intentionally ugly — visibility beats aesthetics.
final-shell       = "bash -l at REPO_DIR (never 'press enter to close')"

[required-modes]
# These are the modes every compliant launcher MUST implement.
runtime = ["--start", "--stop", "--status", "--auto", "--browser"]
integration = ["--integ", "--disinteg"]
meta = ["--help"]

[optional-modes]
# Modes launchers MAY implement for extra functionality.
developer = ["--debug", "--logs", "--tail"]

[default-mode]
# Mode selected when the launcher is invoked with no arguments.
mode = "--auto"

[runtime]
# Required runtime behaviour.
background = "nohup"
pid-file-pattern = "/tmp/{app-name}-server.pid"
log-file-pattern = "/tmp/{app-name}-server.log"
wait-for-url-timeout-seconds = 15
startup-command-search = [
    "{repo-dir}/scripts/run.sh",
    "{repo-dir}/dev.sh",
]

[error-visibility]
# When the launcher runs in a GUI context (no tty + DISPLAY/WAYLAND_DISPLAY set),
# errors must be visible to the user via a GUI dialog, not only to stderr.
#
# Reference implementation: launcher/gui-error.sh — exposes
# `hp_gui_error "title" "message"`. Downstream launchers SHOULD source
# this rather than re-implement the dialog ladder, so the spec stays
# consistent across the estate.
#
# Env override: NO_GUI_ERROR=1 suppresses the dialog attempt (stderr
# still gets the message). Useful in CI / scripted invocation.
reference-impl    = "launcher/gui-error.sh"
gui-dialog-chain  = ["kdialog", "zenity", "notify-send", "xmessage"]
always-also-to-stderr = true
suppress-env-var  = "NO_GUI_ERROR"

[integration.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-permissions = 444
# If no custom icon is available, fall back to this freedesktop named icon.
icon-fallback = "package-x-generic"
refresh-command = "update-desktop-database"
trust-command = "gio set {file} metadata::trusted true"

[integration.macos]
apps-dir = "$HOME/Applications"
desktop-shortcut-dir = "$HOME/Desktop"
bin-dir = "$HOME/.local/bin"
bundle-pattern = "{app-display}.app"
shortcut-pattern = "{app-display}.command"

[integration.windows]
start-menu-dir = "$APPDATA/Microsoft/Windows/Start Menu/Programs"
desktop-shortcut-dir = "$HOME/Desktop"
bin-dir = "$HOME/.local/bin"
shortcut-pattern = "{app-display}.lnk"
# Fallback when PowerShell is not reachable under Git Bash / WSL.
bat-fallback = true

[integrity]
# Per LM-LA-LIFECYCLE §LM/LA-INSTALL: after --integ completes, generate
# integrity hashes via an external tool.
verification-tool = "verify-desktop-integrity.sh"
fallback-paths = [
    "/var/mnt/eclipse/repos/.desktop-tools/verify-desktop-integrity.sh",
]
fatal-on-failure = false  # missing verifier is a log line, not an error

[disinteg]
# What --disinteg removes and what it deliberately leaves alone.
remove = [
    "desktop-file",
    "desktop-shortcut",
    "icon",
    "launcher-binary",
    "start-menu-entry",
    "bat-fallback-shortcuts",
    "pid-file",
]
preserve = [
    "$HOME/.config/{app-name}/",
    "/tmp/{app-name}-server.log",
    "{repo-dir}",
]

[soft-attach]
# Optional ecosystem integrations — called if present, silently skipped
# if absent. Each tool entry carries an explicit `trigger` naming the
# hook point at which the launcher should invoke it.
#
# Reference implementation: launcher/soft-attach.sh — exposes three
# primitives:
#   hp_soft_attach_present "command"          → 0 if on PATH
#   hp_soft_attach_run "command line"         → run if first token present
#   hp_soft_attach_event "tool" "event" [...] → invoke `tool emit event ...`
# Downstream launchers SHOULD source this rather than re-implement.
#
# Trigger values: "on-start-failed", "on-start-succeeded", "on-integ-failed",
# "on-user-request". Additional triggers may be added as the lifecycle grows.
reference-impl = "launcher/soft-attach.sh"
tools = [
    { name = "feedback-o-tron", style = "event",   trigger = "on-start-failed", event = "launcher:start_failed" },
    { name = "hypatia",         style = "command", trigger = "on-start-failed", command = "hypatia diagnose --app {app-name} --log {log-file}" },
    { name = "panic-attack",    style = "command", trigger = "on-start-failed", command = "panic-attack assail {repo-dir}" },
]

[a2ml-metadata-block]
# Every generated launcher must carry this metadata block in its header so it
# can be re-parsed by `launch-scaffolder config` and `realign`.
required-fields = [
    "id",
    "type",
    "version",
    "app-name",
    "app-display",
    "app-url",
    "standards-compliance",
    "modes",
    "platforms",
    "lifecycle-phases-covered",
    "lifecycle-phases-deferred",
]