From 407e286fc47d2e56de107e293c1946d617cc57b8 Mon Sep 17 00:00:00 2001
From: hyperpolymath <6759885+hyperpolymath@users.noreply.github.com>
Date: Tue, 26 May 2026 09:10:41 +0100
Subject: [PATCH] feat(launcher-standard): require --version mode with
 machine-greppable format
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Field bug reports against launchers consistently lack a version string —
"it's broken on my machine" with no way to tell which build, no commit
SHA, no way to bisect. The original launcher-standard required --help
but not --version, so launchers had no obligation to emit one.

This adds --version (also accepts -V) as a required meta-mode. The first
line of output MUST follow a machine-greppable format so bug reports and
log greps can pull the build identity reliably:

    {app-name} {version} ({build-sha-short}) [{platform}]
    e.g. aerie-launcher 0.4.2 (a1b2c3d) [linux-x86_64]

Additional lines (build date, runtime versions, dep tree summary) MAY
follow. Exit code MUST be 0 on success.

Both the a2ml and the prose adoc are updated in the same commit, per the
launcher/README.adoc §Sync requirement (and the lock-step CI gate
introduced in PR #172).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 docs/UX-standards/launcher-standard.adoc |  8 ++++++++
 launcher/launcher-standard.a2ml          | 15 ++++++++++++++-
 2 files changed, 22 insertions(+), 1 deletion(-)

diff --git a/docs/UX-standards/launcher-standard.adoc b/docs/UX-standards/launcher-standard.adoc
index 9ace12eb..5e3cdcd7 100644
--- a/docs/UX-standards/launcher-standard.adoc
+++ b/docs/UX-standards/launcher-standard.adoc
@@ -170,6 +170,14 @@ fi
 | `--help` / `-h`
 | Print usage text, including a description of every mode, the files the
   launcher reads/writes, and the detected platform.
+
+| `--version` / `-V`
+| Print the launcher's version on a single machine-greppable first line,
+  then exit 0. Format: `<app-name> <version> (<build-sha-short>) [<platform>]`
+  (e.g. `aerie-launcher 0.4.2 (a1b2c3d) [linux-x86_64]`). Additional lines
+  (build date, runtime versions) MAY follow. Required so field bug reports
+  can quote a specific build — a launcher without `--version` produces
+  unactionable issues.
 |===
 
 NOTE: `--integ` and `--disinteg` replace the earlier pattern of separate
diff --git a/launcher/launcher-standard.a2ml b/launcher/launcher-standard.a2ml
index 6075d9ec..dc57fcf4 100644
--- a/launcher/launcher-standard.a2ml
+++ b/launcher/launcher-standard.a2ml
@@ -46,7 +46,20 @@ final-shell       = "bash -l at REPO_DIR (never 'press enter to close')"
 # These are the modes every compliant launcher MUST implement.
 runtime = ["--start", "--stop", "--status", "--auto", "--browser"]
 integration = ["--integ", "--disinteg"]
-meta = ["--help"]
+meta = ["--help", "--version"]
+
+[version-output]
+# Required format for the `--version` mode. The first line MUST be
+# machine-greppable so field bug reports can quote it verbatim. Optional
+# additional lines (build SHA, build date, libc / runtime versions) MAY
+# follow on subsequent lines.
+#
+# Rationale: a launcher with no --version produces unactionable bug
+# reports — "it's broken on my machine" with no way to tell which build.
+first-line-format = "{app-name} {version} ({build-sha-short}) [{platform}]"
+example          = "aerie-launcher 0.4.2 (a1b2c3d) [linux-x86_64]"
+exit-code        = 0
+machine-greppable = true
 
 [optional-modes]
 # Modes launchers MAY implement for extra functionality.