Improve the select boot failure help. (#145)

This fixes the error messages displayed when a boot command could not be
found by both differentiating the cases where this can occur with their
own specialized messages and improving the guidance in general.

As part of these messaging fixes, support for hiding commands is added
by omitting descriptions for those named commands you wish to hide from
the boot failure help screen.

Fixes #143
Fixes #144

CHANGES.md

@@ -1,5 +1,12 @@
 # Release Notes
 
+## 0.13.0
+
+This release improves the help screen for BusyBox scies with more clear messages for the various
+causes of boot command selection failure. It also adds the ability to hide internal-only named boot
+commands by omitting a description for those commands (This only kicks in if at least one named
+command has a description).
+
 ## 0.12.0
 
 This release adds support for using placeholders in the `scie.lift.base` lift manifest value as well

Cargo.toml

@@ -5,7 +5,7 @@ members = [
 
 [package]
 name = "scie-jump"
-version = "0.12.0"
+version = "0.13.0"
 description = "The self contained interpreted executable launcher."
 authors = [
     "John Sirois <[email protected]>",

docs/packaging.md

@@ -288,7 +288,9 @@ variable, e.g.: `SCIE_BOOT=some_other_command ./coursier`. If there is no defaul
 and the `SCIE_BOOT` environment variable is not set, a help screen will be printed listing all the
 commands you defined in the lift manifest. You can add a "lift.description" to provide overall help
 in this help page as well as a "description" for each command to provide help displayed after the
-command name.
+command name. If any named command has a description (or there is a default command), then only
+named commands with descriptions will appear in the help page. You can use this behavior to hide
+internal-only commands by giving them no description.
 
 This style of multi-command scie with no default command is called a [BusyBox](
 https://busybox.net/), and it functions like one. Instead of using `SCIE_BOOT` to address a command,

examples/busybox/default-only-lift.linux-x86_64.json

@@ -0,0 +1,21 @@
+{
+  "scie": {
+    "lift": {
+      "name": "default-only",
+      "boot": {
+        "commands": {
+          "": {
+            "exe": "{cpython}/python/bin/python3.11",
+            "args": ["-c", "import sys; print('.'.join(map(str, sys.version_info[:3])))"]
+          }
+        }
+      },
+      "files": [
+        {
+          "name": "cpython-3.11.5+20230826-x86_64-unknown-linux-gnu-install_only.tar.gz",
+          "key": "cpython"
+        }
+      ]
+    }
+  }
+}

examples/busybox/lift.linux-x86_64.json

@@ -0,0 +1,18 @@
+{
+  "scie": {
+    "lift": {
+      "name": "no-commands",
+      "boot": {
+        "commands": {}
+      },
+      "files": [
+        {
+          "name": "cpython-3.11.5+20230826-x86_64-unknown-linux-gnu-install_only.tar.gz"
+        }
+      ]
+    }
+  },
+  "fetch": [
+    "https://github.com/indygreg/python-build-standalone/releases/download/20230826/cpython-3.11.5+20230826-x86_64-unknown-linux-gnu-install_only.tar.gz"
+  ]
+}

examples/busybox/mixed-no-default-desc-lift.linux-x86_64.json

@@ -0,0 +1,36 @@
+{
+  "scie": {
+    "lift": {
+      "name": "mixed-no-default-desc",
+      "description": "The scie's overall description.",
+      "boot": {
+        "commands": {
+          "": {
+            "exe": "{cpython}/python/bin/python3.11",
+            "args": ["-c", "import sys; print('.'.join(map(str, sys.version_info[:3])))"]
+          },
+          "foo": {
+            "description": "Prints foo.",
+            "exe": "{cpython}/python/bin/python3.11",
+            "args": ["-c", "print('foo')"]
+          },
+          "bar": {
+            "exe": "{cpython}/python/bin/python3.11",
+            "args": ["-c", "print('bar')"]
+          },
+          "runs-baz": {
+            "description": "Runs baz.",
+            "exe": "{cpython}/python/bin/python3.11",
+            "args": ["-c", "print('ran baz')"]
+          }
+        }
+      },
+      "files": [
+        {
+          "name": "cpython-3.11.5+20230826-x86_64-unknown-linux-gnu-install_only.tar.gz",
+          "key": "cpython"
+        }
+      ]
+    }
+  }
+}

examples/busybox/mixed-with-default-desc-lift.linux-x86_64.json

@@ -0,0 +1,37 @@
+{
+  "scie": {
+    "lift": {
+      "name": "mixed-with-default-desc",
+      "description": "The scie's overall description.",
+      "boot": {
+        "commands": {
+          "": {
+            "description": "Prints the Python version.",
+            "exe": "{cpython}/python/bin/python3.11",
+            "args": ["-c", "import sys; print('.'.join(map(str, sys.version_info[:3])))"]
+          },
+          "foo": {
+            "description": "Prints foo.",
+            "exe": "{cpython}/python/bin/python3.11",
+            "args": ["-c", "print('foo')"]
+          },
+          "bar": {
+            "exe": "{cpython}/python/bin/python3.11",
+            "args": ["-c", "print('bar')"]
+          },
+          "runs-baz": {
+            "description": "Runs baz.",
+            "exe": "{cpython}/python/bin/python3.11",
+            "args": ["-c", "print('ran baz')"]
+          }
+        }
+      },
+      "files": [
+        {
+          "name": "cpython-3.11.5+20230826-x86_64-unknown-linux-gnu-install_only.tar.gz",
+          "key": "cpython"
+        }
+      ]
+    }
+  }
+}

examples/busybox/named-commands-only-no-desc-lift.linux-x86_64.json

@@ -0,0 +1,25 @@
+{
+  "scie": {
+    "lift": {
+      "name": "named-commands-only-no-desc",
+      "boot": {
+        "commands": {
+          "foo": {
+            "exe": "{cpython}/python/bin/python3.11",
+            "args": ["-c", "print('foo')"]
+          },
+          "bar": {
+            "exe": "{cpython}/python/bin/python3.11",
+            "args": ["-c", "print('bar')"]
+          }
+        }
+      },
+      "files": [
+        {
+          "name": "cpython-3.11.5+20230826-x86_64-unknown-linux-gnu-install_only.tar.gz",
+          "key": "cpython"
+        }
+      ]
+    }
+  }
+}

examples/busybox/named-commands-only-with-desc-lift.linux-x86_64.json

@@ -0,0 +1,31 @@
+{
+  "scie": {
+    "lift": {
+      "name": "named-commands-only-with-desc",
+      "boot": {
+        "commands": {
+          "foo": {
+            "description": "Prints foo.",
+            "exe": "{cpython}/python/bin/python3.11",
+            "args": ["-c", "print('foo')"]
+          },
+          "bar": {
+            "exe": "{cpython}/python/bin/python3.11",
+            "args": ["-c", "print('bar')"]
+          },
+          "runs-baz": {
+            "description": "Runs baz.",
+            "exe": "{cpython}/python/bin/python3.11",
+            "args": ["-c", "print('ran baz')"]
+          }
+        }
+      },
+      "files": [
+        {
+          "name": "cpython-3.11.5+20230826-x86_64-unknown-linux-gnu-install_only.tar.gz",
+          "key": "cpython"
+        }
+      ]
+    }
+  }
+}

examples/busybox/test.sh

@@ -0,0 +1,143 @@
+# Copyright 2022 Science project contributors.
+# Licensed under the Apache License, Version 2.0 (see LICENSE).
+
+# shellcheck source=../common.sh
+source "${COMMON}"
+trap gc EXIT
+
+check_cmd diff mktemp
+
+OUTPUT="$(mktemp)"
+gc "${OUTPUT}"
+
+
+# Test no boot commands error.
+"${SCIE_JUMP}" "${LIFT}"
+gc "${PWD}/no-commands${EXE_EXT}"
+
+./no-commands 2>"${OUTPUT}" && die "Expected ./no-commands to fail to execute."
+diff -u \
+<(cat <<EOF
+Error: The ./no-commands${EXE_EXT} scie is malformed - it has no boot commands.
+
+You might begin debugging by inspecting the output of \`SCIE=inspect ./no-commands${EXE_EXT}\`.
+EOF
+) "${OUTPUT}"
+
+
+# Test no named commands error.
+"${SCIE_JUMP}" "default-only-lift.${OS_ARCH}.json"
+gc "${PWD}/default-only${EXE_EXT}"
+
+diff -u <(echo "3.11.5") <(./default-only)
+
+SCIE_BOOT=dne ./default-only 2>"${OUTPUT}" && die "Expected SCIE_BOOT=dne ./default-only to fail to execute."
+diff -u \
+<(cat <<EOF
+Error: \`SCIE_BOOT=dne\` was found in the environment but "dne" does not correspond to any default-only commands.
+
+The ./default-only scie contains no alternate boot commands.
+EOF
+) "${OUTPUT}"
+
+
+# Test named commands only help is displayed for all commands when no named commands have
+# descriptions - a bare BusyBox.
+"${SCIE_JUMP}" "named-commands-only-no-desc-lift.${OS_ARCH}.json"
+gc "${PWD}/named-commands-only-no-desc${EXE_EXT}"
+
+diff -u <(echo "foo") <(SCIE_BOOT=foo ./named-commands-only-no-desc)
+diff -u <(echo "foo") <(./named-commands-only-no-desc foo)
+diff -u <(echo "bar") <(SCIE_BOOT=bar ./named-commands-only-no-desc)
+diff -u <(echo "bar") <(./named-commands-only-no-desc bar)
+
+SCIE_BOOT=dne ./named-commands-only-no-desc 2>"${OUTPUT}" && die "Expected SCIE_BOOT=dne ./named-commands-only-no-desc to fail to execute."
+diff -u \
+<(cat <<EOF
+Error: \`SCIE_BOOT=dne\` was found in the environment but "dne" does not correspond to any named-commands-only-no-desc commands.
+
+Please select from the following boot commands:
+
+foo
+bar
+
+You can select a boot command by setting the SCIE_BOOT environment variable or else by passing it as the 1st argument.
+EOF
+) "${OUTPUT}"
+
+
+# Test named commands only help is displayed only for commands with descriptions.
+"${SCIE_JUMP}" "named-commands-only-with-desc-lift.${OS_ARCH}.json"
+gc "${PWD}/named-commands-only-with-desc${EXE_EXT}"
+
+diff -u <(echo "foo") <(SCIE_BOOT=foo ./named-commands-only-with-desc)
+diff -u <(echo "foo") <(./named-commands-only-with-desc foo)
+diff -u <(echo "bar") <(SCIE_BOOT=bar ./named-commands-only-with-desc)
+diff -u <(echo "bar") <(./named-commands-only-with-desc bar)
+diff -u <(echo "ran baz") <(SCIE_BOOT=runs-baz ./named-commands-only-with-desc)
+diff -u <(echo "ran baz") <(./named-commands-only-with-desc runs-baz)
+
+SCIE_BOOT=dne ./named-commands-only-with-desc 2>"${OUTPUT}" && die "Expected SCIE_BOOT=dne ./named-commands-only-with-desc to fail to execute."
+diff -u \
+<(cat <<EOF
+Error: \`SCIE_BOOT=dne\` was found in the environment but "dne" does not correspond to any named-commands-only-with-desc commands.
+
+Please select from the following boot commands:
+
+foo       Prints foo.
+runs-baz  Runs baz.
+
+You can select a boot command by setting the SCIE_BOOT environment variable or else by passing it as the 1st argument.
+EOF
+) "${OUTPUT}"
+
+
+# Test a mixed-mode scie with a default command, named commands with descriptions and named commands
+# with no descriptions (hidden commands).
+"${SCIE_JUMP}" "mixed-no-default-desc-lift.${OS_ARCH}.json"
+gc "${PWD}/mixed-no-default-desc${EXE_EXT}"
+
+diff -u <(echo "3.11.5") <(./mixed-no-default-desc)
+diff -u <(echo "3.11.5") <(./mixed-no-default-desc "1st arg goes to default command which ignores all args.")
+diff -u <(echo "foo") <(SCIE_BOOT=foo ./mixed-no-default-desc)
+diff -u <(echo "bar") <(SCIE_BOOT=bar ./mixed-no-default-desc)
+diff -u <(echo "ran baz") <(SCIE_BOOT=runs-baz ./mixed-no-default-desc)
+
+SCIE_BOOT=dne ./mixed-no-default-desc 2>"${OUTPUT}" && die "Expected SCIE_BOOT=dne ./mixed-no-default-desc to fail to execute."
+diff -u \
+<(cat <<EOF
+Error: \`SCIE_BOOT=dne\` was found in the environment but "dne" does not correspond to any mixed-no-default-desc commands.
+
+The scie's overall description.
+
+Please select from the following boot commands:
+
+<default> (when SCIE_BOOT is not set in the environment)
+foo                                                       Prints foo.
+runs-baz                                                  Runs baz.
+
+You can select a boot command by setting the SCIE_BOOT environment variable.
+EOF
+) "${OUTPUT}"
+
+
+# Test default command with its own description.
+"${SCIE_JUMP}" "mixed-with-default-desc-lift.${OS_ARCH}.json"
+gc "${PWD}/mixed-with-default-desc${EXE_EXT}"
+
+SCIE_BOOT=dne ./mixed-with-default-desc 2>"${OUTPUT}" && die "Expected SCIE_BOOT=dne ./mixed-with-default-desc to fail to execute."
+diff -u \
+<(cat <<EOF
+Error: \`SCIE_BOOT=dne\` was found in the environment but "dne" does not correspond to any mixed-with-default-desc commands.
+
+The scie's overall description.
+
+Please select from the following boot commands:
+
+<default> (when SCIE_BOOT is not set in the environment)  Prints the Python version.
+foo                                                       Prints foo.
+runs-baz                                                  Runs baz.
+
+You can select a boot command by setting the SCIE_BOOT environment variable.
+EOF
+) "${OUTPUT}"

jump/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "jump"
-version = "0.12.0"
+version = "0.13.0"
 description = "The bulk of the scie-jump binary logic."
 authors = [
     "John Sirois <[email protected]>",