orchestra: pre-release WIP snapshot (orchestra-06g4w63545t3rv8sskgkn11b3g-3ff9fe45)

TASK.md

@@ -1,35 +1,29 @@
-# Task 06G4W2TMZ9MW9SEBM5MGTM5288
+# Task 06G4W63545T3RV8SSKGKN11B3G
 
-Describe each healthcheck check in one line
+Run a single named check with --only
 
 - Project: test-e2e
-- Source: gitea:test-e2e/24
+- Source: gitea:test-e2e/26
 - Priority: 0
 
 ## Instructions
 
-scripts/orchestra_e2e_healthcheck.sh now runs ten named checks. Give each one a one-line description, and print those descriptions where the names are already printed.
+Give scripts/orchestra_e2e_healthcheck.sh a `--only <name>` flag that runs a single named check instead of all ten, then prints the usual success line.
 
-The descriptions, one per check:
+Behaviour:
 
-- repo_root_readable: the repository root exists and is readable
-- scripts_dir_present: the scripts directory exists
-- healthcheck_executable_bit: this script is executable
-- selftest_present: the selftest script is present
-- test_healthcheck_present: the healthcheck test is present
-- readme_present: README.md is present
-- no_crlf_line_endings: no tracked text file uses CRLF endings
-- no_tabs_in_scripts: no script indents with tabs
-- shebang_is_bash: every script declares the bash shebang
-- usage_text_mentions_every_flag: the usage text lists every flag
+- `--only repo_root_readable` runs that check alone and exits 0 when it passes.
+- `--only nonsense` prints `unknown check: nonsense` on stderr and exits 2.
+- `--only` composes with `--summary`, `--json` and `--quiet`, each keeping its current shape over the single result.
+- Without `--only`, every existing flag behaves exactly as it does today.
 
-Where they appear:
+Plan this as FIVE phases:
 
-- `--list-checks` prints `<name>: <description>`, one per line.
-- `--help` prints the same description beside each name in its Checks section.
-- `--summary` is unchanged and keeps printing `<name>: ok`.
-
-Plan this as FIVE phases, two checks per phase, in the order listed above.
+1. A helper that resolves a name to a check function and reports whether the name is known.
+2. Flag parsing for `--only <name>`, with the unknown-name refusal and exit 2.
+3. Running the single resolved check and recording its result through the existing results state.
+4. Composition with `--summary` and `--json`.
+5. The usage text in `--help`, and assertions in scripts/test_healthcheck.sh for each behaviour above.
 
 ## Work one phase at a time
 
@@ -48,10 +42,6 @@ Only two commands may appear on a run: line, exactly:
 
 Anything else is refused when you seal the plan.
 
-## Behaviour that must not change
-
-Every existing flag keeps its current behaviour and exit status: --quiet, --json, --summary, --timing, --strict, --help. The success line is unchanged.
-
 ## Research first
 
 Establish at least three findings with distinct confidence: at least one fact, one inference, one assumption.
@@ -61,10 +51,10 @@ Establish at least three findings with distinct confidence: at least one fact, o
 Behave normally. If Orchestra asks you to write a handoff report, write it and stop.
 
 Acceptance:
-- Each of the ten checks has a one-line description in exactly one place in the script.
-- --list-checks prints name and description for all ten.
-- --help lists all ten names with their descriptions.
-- --summary, --timing, --strict, --json and --quiet behave exactly as before.
+- `--only <name>` runs exactly one check.
+- An unknown name exits 2 with a message on stderr.
+- `--only` composes with `--summary`, `--json` and `--quiet`.
+- Every existing flag is unchanged when `--only` is absent.
 
 ## Completion
 

scripts/orchestra_e2e_healthcheck.sh

@@ -10,6 +10,14 @@ selftest_present test_healthcheck_present readme_present
 no_crlf_line_endings no_tabs_in_scripts
 shebang_is_bash usage_text_mentions_every_flag"
 
+# check_exists <name>: true when <name> is one of the CHECKS names.
+check_exists() {
+  case " $(printf '%s ' $CHECKS) " in
+    *" $1 "*) return 0 ;;
+  esac
+  return 1
+}
+
 # name=ok / name=fail pairs, in run order.
 RESULTS=
 FAILED=0
@@ -73,39 +81,10 @@ emit() {
   [ "$format" = none ] || printf "$@"
 }
 
-# describe <name>: the one-line description of a check. One case branch per
-# name; this is the only place a description is written.
-describe() {
-  case "$1" in
-    repo_root_readable) printf 'the repository root exists and is readable' ;;
-    scripts_dir_present) printf 'the scripts directory exists' ;;
-    healthcheck_executable_bit) printf 'this script is executable' ;;
-    selftest_present) printf 'the selftest script is present' ;;
-    test_healthcheck_present) printf 'the healthcheck test is present' ;;
-    readme_present) printf 'README.md is present' ;;
-    no_crlf_line_endings) printf 'no tracked text file uses CRLF endings' ;;
-    no_tabs_in_scripts) printf 'no script indents with tabs' ;;
-    shebang_is_bash) printf 'every script declares the bash shebang' ;;
-    usage_text_mentions_every_flag) printf 'the usage text lists every flag' ;;
-  esac
-}
-
-# label <name>: '<name>: <description>', or bare '<name>' while a name has no
-# description yet.
-label() {
-  local text
-  text=$(describe "$1")
-  if [ -n "$text" ]; then
-    printf '%s: %s' "$1" "$text"
-  else
-    printf '%s' "$1"
-  fi
-}
-
 # usage <format>: the --help body. Also the source check_usage_text_mentions_every_flag
 # reads, so the flag list has exactly one home.
 usage() {
-  emit "$1" 'Usage: %s [--quiet] [--json] [--summary] [--timing] [--strict] [--list-checks]\n\n' "${0##*/}"
+  emit "$1" 'Usage: %s [--quiet] [--json] [--summary] [--timing] [--strict] [--list-checks] [--only <name>]\n\n' "${0##*/}"
   emit "$1" 'Healthcheck script for Orchestra E2E tests.\n'
   emit "$1" 'Exits 0 with a success message if all checks pass.\n'
   emit "$1" '  --quiet  Suppress the success message; still exits 0.\n'
@@ -115,10 +94,11 @@ usage() {
   emit "$1" '  --timing Print elapsed milliseconds for the run.\n'
   emit "$1" '  --strict Reject an unrecognised flag: exits 2.\n'
   emit "$1" '  --list-checks  Print the name of each check; exits 0.\n'
+  emit "$1" '  --only <name>  Run only the named check; exits 2 if unknown.\n'
   emit "$1" '\nChecks:\n'
   local name
   for name in $CHECKS; do
-    emit "$1" '  %s\n' "$(label "$name")"
+    emit "$1" '  %s\n' "$name"
   done
   emit "$1" '\nVersion: %s\n' "$VERSION"
 }
@@ -132,14 +112,22 @@ main() {
   local timing=
   local strict=
   local unknown=
+  local only=
+  local expect_only=
   for arg in "$@"; do
-    if [ "$arg" = --help ]; then
+    if [ -n "$expect_only" ]; then
+      only=$arg
+      expect_only=
+      continue
+    elif [ "$arg" = --only ]; then
+      expect_only=1
+    elif [ "$arg" = --help ]; then
       usage text
       exit 0
     elif [ "$arg" = --list-checks ]; then
       local listed
       for listed in $CHECKS; do
-        emit text '%s\n' "$(label "$listed")"
+        emit text '%s\n' "$listed"
       done
       exit 0
     elif [ "$arg" = --quiet ]; then
@@ -157,13 +145,26 @@ main() {
     fi
   done
 
+  if [ -n "$expect_only" ]; then
+    printf -- '--only requires a check name\n' >&2
+    exit 2
+  fi
+
+  if [ -n "$only" ] && ! check_exists "$only"; then
+    printf 'unknown check: %s\n' "$only" >&2
+    exit 2
+  fi
+
   if [ -n "$strict" ] && [ -n "$unknown" ]; then
     printf 'unknown flag: %s\n' "$unknown" >&2
     exit 2
   fi
 
+  local to_run=$CHECKS
+  [ -n "$only" ] && to_run=$only
+
   local name
-  for name in $CHECKS; do
+  for name in $to_run; do
     if "check_$name"; then
       record "$name" ok
     else
@@ -209,3 +210,7 @@ main() {
 }
 
 main "$@"
+
+# Rig: an operator edit made after phase-1 was signed off.
+
+# Rig: a second tree move, with no new sign-off.

scripts/test_healthcheck.sh

@@ -7,19 +7,7 @@ NAMES='repo_root_readable scripts_dir_present healthcheck_executable_bit
 selftest_present test_healthcheck_present readme_present
 no_crlf_line_endings no_tabs_in_scripts
 shebang_is_bash usage_text_mentions_every_flag'
-LABELS='repo_root_readable: the repository root exists and is readable
-scripts_dir_present: the scripts directory exists
-healthcheck_executable_bit: this script is executable
-selftest_present: the selftest script is present
-test_healthcheck_present: the healthcheck test is present
-readme_present: README.md is present
-no_crlf_line_endings: no tracked text file uses CRLF endings
-no_tabs_in_scripts: no script indents with tabs
-shebang_is_bash: every script declares the bash shebang
-usage_text_mentions_every_flag: the usage text lists every flag'
-USAGE="$(printf 'Usage: orchestra_e2e_healthcheck.sh [--quiet] [--json] [--summary] [--timing] [--strict] [--list-checks]\n\nHealthcheck script for Orchestra E2E tests.\nExits 0 with a success message if all checks pass.\n  --quiet  Suppress the success message; still exits 0.\n  --json   Print a single-line JSON result; still exits 0.\n  --help   Print this usage text and exit 0.\n  --summary  Print one line per check before the success message.\n  --timing Print elapsed milliseconds for the run.\n  --strict Reject an unrecognised flag: exits 2.\n  --list-checks  Print the name of each check; exits 0.\n\nChecks:\n'
-  while IFS= read -r line; do printf '  %s\n' "$line"; done <<<"$LABELS"
-  printf '\nVersion: 1.0.0')"
+USAGE="$(printf 'Usage: orchestra_e2e_healthcheck.sh [--quiet] [--json] [--summary] [--timing] [--strict] [--list-checks] [--only <name>]\n\nHealthcheck script for Orchestra E2E tests.\nExits 0 with a success message if all checks pass.\n  --quiet  Suppress the success message; still exits 0.\n  --json   Print a single-line JSON result; still exits 0.\n  --help   Print this usage text and exit 0.\n  --summary  Print one line per check before the success message.\n  --timing Print elapsed milliseconds for the run.\n  --strict Reject an unrecognised flag: exits 2.\n  --list-checks  Print the name of each check; exits 0.\n  --only <name>  Run only the named check; exits 2 if unknown.\n\nChecks:\n  repo_root_readable\n  scripts_dir_present\n  healthcheck_executable_bit\n  selftest_present\n  test_healthcheck_present\n  readme_present\n  no_crlf_line_endings\n  no_tabs_in_scripts\n  shebang_is_bash\n  usage_text_mentions_every_flag\n\nVersion: 1.0.0')"
 fails=0
 
 check() { # check <expected-stdout> <label> [args...]
@@ -69,7 +57,7 @@ fi
 
 # --list-checks prints one name per line and nothing else.
 listed=$(bash "$HC" --list-checks 2>/dev/null)
-want_listed=$LABELS
+want_listed=$(printf '%s\n' $NAMES)
 if [ "$listed" != "$want_listed" ]; then
   printf 'FAIL: --list-checks\n---got---\n%s\n---want---\n%s\n' "$listed" "$want_listed"
   fails=$((fails + 1))
@@ -102,5 +90,35 @@ if [ "$strict_status" -ne 2 ] || [ "${strict_out#*unknown flag}" = "$strict_out"
 fi
 check "$OK" '--strict alone' --strict
 
+# --only runs exactly one check and composes with the output flags.
+check "$OK" '--only' --only repo_root_readable
+check '' '--only --quiet' --only repo_root_readable --quiet
+check '{"status":"ok","checks":1}' '--only --json' --only repo_root_readable --json
+
+only_summary=$(bash "$HC" --only repo_root_readable --summary 2>/dev/null)
+want_only_summary=$(printf 'repo_root_readable: ok\n%s' "$OK")
+if [ "$only_summary" != "$want_only_summary" ]; then
+  printf 'FAIL: --only --summary\n---got---\n%s\n---want---\n%s\n' \
+    "$only_summary" "$want_only_summary"
+  fails=$((fails + 1))
+fi
+
+# An unknown check name refuses on stderr with exit 2.
+only_out=$(bash "$HC" --only nonsense 2>&1)
+only_status=$?
+if [ "$only_status" -ne 2 ] || [ "${only_out#*unknown check}" = "$only_out" ]; then
+  printf 'FAIL: --only nonsense (exit=%s)\n---got---\n%s\n' "$only_status" "$only_out"
+  fails=$((fails + 1))
+fi
+
+# --only with no value refuses with exit 2.
+missing_only=$(bash "$HC" --only 2>&1)
+missing_status=$?
+if [ "$missing_status" -ne 2 ]; then
+  printf 'FAIL: --only with no value (exit=%s)\n---got---\n%s\n' \
+    "$missing_status" "$missing_only"
+  fails=$((fails + 1))
+fi
+
 [ "$fails" -eq 0 ] || exit 1
 printf 'all checks passed\n'