Skip to content

Commit 7ae32cf

Browse files
fix(launcher-standard): resolve 3 cross-doc contradictions (#170)
## Summary The launcher standard (`docs/UX-standards/launcher-standard.adoc` + `launcher/launcher-standard.a2ml`) and the lifecycle standard (`docs/UX-standards/LM-LA-LIFECYCLE-STANDARD.adoc`) disagreed on three points. Each was a real contradiction — not stylistic drift — and would have left a downstream implementer unsure which doc to follow. - **`--browser` was listed as an independent required mode** in the a2ml while prose calls it an alias for `--auto`. Split `[required-modes]` (canonical only) from a new `[aliases]` table mapping `--browser`/`--web` → `--auto`. Same enforcement, cleaner taxonomy. - **`--integ` / `--disinteg` supersede the standalone install/uninstall scripts** (per launcher-standard.adoc v0.2.0), but LM-LA never absorbed the change. Added `IMPORTANT` callouts to §Installation Standard and §Uninstallation Standard scoping the script templates as reference for what `--integ` / `--disinteg` must do internally, and marking the standalone scripts optional when those modes exist. - **`sudo` violation**: launcher-standard.adoc design principle 5 forbids elevated privileges, but the LM-LA templates ran `sudo dnf`, `sudo cp`, `sudo systemctl`. Added a "Privilege model" callout: sudo paths are opt-in platform-maintainer extensions for machine-wide deployment only; a launcher's `--integ` MUST NOT invoke them without explicit `--system` opt-in. Missing deps under a user install fail with an actionable message, not escalate. Spec version bumped 0.2.0 → 0.3.0 (taxonomy change in `[required-modes]`; behaviour for compliant launchers is unchanged because every accepted input is still accepted). ## Out of scope (follow-ups identified but deferred) Surfaced during the same review, not bundled here so this PR stays small enough to read: - No CI gate enforcing the prose↔a2ml lock-step requirement stated in `launcher/README.adoc:37-39`. - Hard-coded `/var/mnt/eclipse/repos/...` paths in the a2ml fallback and `.desktop` examples — breaks on non-eclipse hosts. - Browser launcher missing macOS `open`, WSL `wslview`, `\$BROWSER`. - `wait_for_server` flat-1s polling ignores the `wait-for-url-timeout-seconds` constant the a2ml already declares. - PID/log under predictable `/tmp/` names — symlink-attack target on shared hosts; should use `\$XDG_RUNTIME_DIR` / `\$XDG_STATE_HOME`. - `keepopen.sh` doesn't honour `NO_COLOR`. - `gui-dialog-chain` and `[soft-attach]` declared in a2ml without reference impl → every downstream launcher will reinvent. - `--version` mode missing entirely from required-modes. Happy to take any of these in follow-up PRs. ## Test plan - [x] AsciiDoc renders (visual diff — only added `[IMPORTANT]` blocks and one bullet) - [x] a2ml parses (additive `[aliases]` table + literal-string list shortening) - [ ] Downstream `launch-scaffolder` rebuild picks up the new `[aliases]` table (separate repo) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
1 parent 37ccfb4 commit 7ae32cf

2 files changed

Lines changed: 57 additions & 3 deletions

File tree

docs/UX-standards/LM-LA-LIFECYCLE-STANDARD.adoc

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -55,6 +55,41 @@ and warmup procedures for different user types.
5555

5656
== Installation Standard (LM/LA-INSTALL)
5757

58+
[IMPORTANT]
59+
.Relationship to `launcher-standard.adoc` `--integ` / `--disinteg`
60+
====
61+
As of `launcher-standard.adoc` v0.2.0, the *typical* install path for a
62+
hyperpolymath launcher is the launcher's own `--integ` mode, and removal
63+
is `--disinteg`. When a launcher implements those modes, a separate
64+
`scripts/install.sh` / `scripts/uninstall.sh` is **no longer required**.
65+
66+
This document remains authoritative for **what** must happen during install
67+
and uninstall (the desktop file, the icon, the integrity hashes, what to
68+
preserve on removal, etc.). `launcher-standard.adoc` is authoritative for
69+
**where** those operations are triggered from (the launcher binary itself).
70+
71+
The script-based templates in this section are the reference for what
72+
`--integ` / `--disinteg` must accomplish internally — they are not a
73+
parallel, separately-invoked install surface.
74+
====
75+
76+
[IMPORTANT]
77+
.Privilege model — user-level by default
78+
====
79+
Both `--integ` and the templates below MUST be runnable without elevated
80+
privileges. All paths default to the user's home (`~/.local/share`,
81+
`~/.config`, `~/.local/bin`), matching `launcher-standard.adoc` §System
82+
Integration Modes design principle 5 (*"No elevated privileges. No sudo."*).
83+
84+
`sudo` calls appear in the §Platform Maintainer Warmup template and in
85+
the optional dependency-bootstrap path below. These are **opt-in extensions
86+
for platform maintainers performing a machine-wide deployment** — they MUST
87+
NOT run as part of a default per-user install, and a launcher's `--integ`
88+
MUST NOT invoke them without explicit `--system` opt-in. If a dependency
89+
is missing under a user install, the correct response is to fail with an
90+
actionable error message, not to escalate.
91+
====
92+
5893
=== Requirements
5994

6095
Launchers and applications MUST provide:
@@ -63,6 +98,7 @@ Launchers and applications MUST provide:
6398
- Named: `<app-name>-install.sh`
6499
- Location: `<repo-root>/scripts/install.sh`
65100
- Permissions: `755` (executable)
101+
- **Optional** when the launcher implements `--integ` / `--disinteg`.
66102

67103
2. **Idempotent Operations**
68104
- Safe to run multiple times
@@ -352,6 +388,16 @@ log "✓ Platform setup complete!"
352388

353389
== Uninstallation Standard (LM/LA-UNINSTALL)
354390

391+
[IMPORTANT]
392+
.See §Installation Standard
393+
====
394+
The same `--integ`/`--disinteg` supersedence and user-level-privilege rules
395+
apply here. When the launcher implements `--disinteg`, a separate
396+
`scripts/uninstall.sh` is not required; the template below is the reference
397+
for what `--disinteg` must accomplish. `sudo` paths are opt-in
398+
platform-maintainer extensions and MUST NOT run by default.
399+
====
400+
355401
=== Uninstall Script Requirements
356402

357403
[source,bash]

launcher/launcher-standard.a2ml

Lines changed: 11 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -15,8 +15,8 @@
1515
# - standards/docs/UX-standards/LM-LA-LIFECYCLE-STANDARD.adoc (install/uninstall)
1616

1717
[spec]
18-
version = "0.2.0"
19-
date = "2026-04-17"
18+
version = "0.3.0"
19+
date = "2026-05-26"
2020
compliance = [
2121
"launcher-standard.adoc",
2222
"LM-LA-LIFECYCLE-STANDARD.adoc",
@@ -44,7 +44,9 @@ final-shell = "bash -l at REPO_DIR (never 'press enter to close')"
4444

4545
[required-modes]
4646
# These are the modes every compliant launcher MUST implement.
47-
runtime = ["--start", "--stop", "--status", "--auto", "--browser"]
47+
# Aliases (see [aliases] below) are not listed here — they are accepted
48+
# inputs, not independent obligations.
49+
runtime = ["--start", "--stop", "--status", "--auto"]
4850
integration = ["--integ", "--disinteg"]
4951
meta = ["--help", "--version"]
5052

@@ -61,6 +63,12 @@ example = "aerie-launcher 0.4.2 (a1b2c3d) [linux-x86_64]"
6163
exit-code = 0
6264
machine-greppable = true
6365

66+
[aliases]
67+
# Documented mode aliases. Launchers MUST accept these and route them to
68+
# the canonical mode. Prose: launcher-standard.adoc §Required Modes.
69+
"--browser" = "--auto"
70+
"--web" = "--auto"
71+
6472
[optional-modes]
6573
# Modes launchers MAY implement for extra functionality.
6674
developer = ["--debug", "--logs", "--tail"]

0 commit comments

Comments
 (0)