Pick help's palette from the terminal's background, in teal

Help asks the terminal for its background (OSC 11) and uses a palette for
a dark or a light one; other runs, and help where the terminal doesn't
answer, keep the palette that reads on both. Only help asks: the answer
is read off the terminal's input, and a command that prompts afterwards
lost the answer typed ahead. Every colored run of text is bold.

AGI-1169 AGI-1174

Author: zmofei

CHANGELOG.md

@@ -25,12 +25,15 @@ that may never merge. They are not releases and are not listed here.
   sentence. Help text only; `--schema` always had the full description.
 
 - Color reads on light and dark terminal themes alike. Tables, tips, the
-  banner and help notes use a small fixed palette (Mapbox blue, gray, red)
-  whose colors all clear 3.5:1 on common themes, instead of the
-  terminal's own bright blue and dim, which fell below 2:1 on some light
-  ones. A terminal not known to show 24-bit color gets bold and plain text
-  instead. New `--no-color` flag turns color off, as `NO_COLOR` does, and
-  `FORCE_COLOR=1` now keeps color in a pipe; either way off wins.
+  banner and help use a small fixed palette (teal, gray, red) instead of
+  the terminal's own bright blue and dim, which fell below 2:1 on some
+  light themes; every colored run of text is bold. Help asks the terminal
+  for its background and uses a palette made for a dark or a light one;
+  everything else, and help where the terminal doesn't answer, uses one
+  that reads on both. A terminal not known to show 24-bit color gets bold
+  and plain text instead. New `--no-color` flag turns color off, as
+  `NO_COLOR` does, and `FORCE_COLOR=1` now keeps color in a pipe; either
+  way off wins.
 
 - Top-level `mapbox --help` lists commands in groups (Maps and data,
   Search, Account, Coding agents, CLI), each with a line saying what it
@@ -39,7 +42,7 @@ that may never merge. They are not releases and are not listed here.
   Subcommand help uses clap's compact layout for `--help` as well as
   `-h`, with the command's full description at the top, and points to
   `mapbox --help` for the global options instead of repeating them; they
-  still work on every command. Headings are blue; names to type and values
+  still work on every command. Headings are teal; names to type and values
   to fill in are bold in the terminal's own foreground; notes are gray. clap's yellow and green in usage errors
   are bold now too.
   Help text only: no command, flag, exit code or result output changes.

Cargo.lock

@@ -103,6 +103,13 @@ dirs = "5"
 # are needed for `parse_to_serde_value`, which decodes straight into a
 # `serde_json::Value`.
 jsonc-parser = { version = "0.34.0", features = ["serde", "serde_json"] }
+# Asks the terminal for its background color (OSC 11), so help can use the
+# palette for a dark or a light one. It reads the answer off the terminal,
+# which takes raw mode and a timed read — `unsafe` this crate does not
+# have — and it sends a second query every terminal answers, so one without
+# OSC 11 is known at once instead of after the timeout. Asked only by a run
+# that shows help; see src/output/theme.rs.
+terminal-colorsaurus = "1"
 
 [dev-dependencies]
 # Integration tests build fake Mapbox tokens; same crate the CLI already uses.

Cargo.toml

@@ -472,9 +472,10 @@ At a terminal, a run opens with a `mapbox · v<version>` line on stderr, and
 help, tables, labels and tips are in color. Neither reaches a pipe or a
 file. `-q`/`--quiet` (or `MAPBOX_QUIET=1`) hides the banner. `--no-color`
 or `NO_COLOR` turns color off; `FORCE_COLOR=1` keeps it on into a pipe, for
-a pager such as `less -R`, and `--no-color`/`NO_COLOR` win over it. The colors are fixed and chosen
-to read on light and dark themes alike; a terminal not known to show 24-bit
-color gets bold text instead.
+a pager such as `less -R`, and `--no-color`/`NO_COLOR` win over it. The
+colors are fixed and chosen to read on light and dark themes alike; help
+asks the terminal for its background to pick a palette for it. A terminal
+not known to show 24-bit color gets bold text instead.
 
 ### `--schema`
 

README.md

@@ -459,6 +459,26 @@ fn page_width() -> usize {
     detected.map_or(MAX_WIDTH, |w| w.min(MAX_WIDTH))
 }
 
+/// Whether argv asks for help, read before clap parses it: `-h` or `--help`
+/// anywhere before `--`, or `help` as the first word that is not an option.
+/// The one kind of run allowed to ask the terminal for its background (see
+/// `output::theme::allow_background_query`). A miss costs only the fallback
+/// palette; a false match on a command that prompts would cost the answer
+/// typed ahead, which is why `help` counts only as the subcommand.
+pub fn help_requested(argv: &[std::ffi::OsString]) -> bool {
+    let mut first_word = true;
+    for arg in argv.iter().skip(1).filter_map(|arg| arg.to_str()) {
+        match arg {
+            "--" => return false,
+            "-h" | "--help" => return true,
+            "help" if first_word => return true,
+            _ if !arg.starts_with('-') => first_word = false,
+            _ => {}
+        }
+    }
+    false
+}
+
 /// The copy of the tree that parses, and so renders every subcommand's
 /// help: compact, and about the command itself.
 ///
@@ -663,13 +683,15 @@ mod tests {
         assert!(missing.is_empty(), "{}", missing.join("\n"));
     }
 
-    /// Help and clap's errors use bold and the palette's fixed colors, never
+    /// Help and clap's errors use bold and the palettes' fixed colors, never
     /// one of the sixteen a terminal theme decides — and without 24-bit
     /// color, no color at all. See `output::theme`.
     #[test]
     fn theme_safe_colors_only() {
-        for truecolor in [true, false] {
-            let app = app().styles(crate::output::theme::styles_for(truecolor));
+        use crate::output::theme::{styles_in, Look, LOOKS};
+        for &look in LOOKS {
+            let truecolor = look != Look::Bold;
+            let app = app().styles(styles_in(look));
             let parsing = for_parsing(apply(app));
             for argv in [
                 &["mapbox", "--help"][..],
@@ -687,18 +709,18 @@ mod tests {
                 let problems = unsafe_styles(&text, truecolor);
                 assert!(
                     problems.is_empty(),
-                    "{argv:?} (truecolor: {truecolor}) uses {problems:?}:\n{text}"
+                    "{argv:?} ({look:?}) uses {problems:?}:\n{text}"
                 );
             }
         }
     }
 
     /// The SGR parameters in `text` that are neither a reset, bold, nor —
-    /// with `truecolor` — a 24-bit color from the palette.
+    /// with `truecolor` — a 24-bit color from one of the palettes.
     fn unsafe_styles(text: &str, truecolor: bool) -> Vec<String> {
-        let palette: Vec<String> = crate::output::theme::PALETTE
+        let palette: Vec<String> = crate::output::theme::colors()
             .iter()
-            .map(|(c, _)| format!("{};{};{}", c.0, c.1, c.2))
+            .map(|c| format!("{};{};{}", c.0, c.1, c.2))
             .collect();
         let mut problems = Vec::new();
         for sequence in text.split("\x1b[").skip(1) {
@@ -734,6 +756,26 @@ mod tests {
         problems
     }
 
+    #[test]
+    fn help_is_recognized_only_where_it_asks_for_help() {
+        let asks = |args: &[&str]| {
+            let argv: Vec<std::ffi::OsString> = std::iter::once("mapbox")
+                .chain(args.iter().copied())
+                .map(Into::into)
+                .collect();
+            help_requested(&argv)
+        };
+        assert!(asks(&["--help"]));
+        assert!(asks(&["styles", "list", "-h"]));
+        assert!(asks(&["help", "styles"]));
+        assert!(asks(&["--no-color", "help"]));
+        // A style named "help" is a value, not a request: deleting it
+        // prompts, and the prompt must keep its answer.
+        assert!(!asks(&["styles", "delete", "help"]));
+        assert!(!asks(&["tilesets-cli", "--", "--help"]));
+        assert!(!asks(&["styles", "list"]));
+    }
+
     fn shown(text: &str) -> Vec<String> {
         pieces(text)
             .iter()

src/help_layout.rs

@@ -837,6 +837,9 @@ fn cli() -> u8 {
     if output::style::requested_off(&raw_argv) {
         output::style::turn_off();
     }
+    if help_layout::help_requested(&raw_argv) {
+        output::theme::allow_background_query(output::on_a_terminal());
+    }
 
     let mut app = build_app(&specs);
     // Here rather than in `build_app`, which tests call directly and which

src/main.rs

@@ -352,6 +352,12 @@ fn tip_lines(tips: &[String], color: bool) -> Vec<String> {
         .collect()
 }
 
+/// Whether either output stream is a terminal — something that can be asked
+/// for its background color (see `theme::allow_background_query`).
+pub fn on_a_terminal() -> bool {
+    std::io::stdout().is_terminal() || std::io::stderr().is_terminal()
+}
+
 /// Whether a result written to stdout may carry color. Only a terminal:
 /// `-o text > file` must leave a file with no escapes in it.
 pub fn result_in_color() -> bool {