chore(misc-dev-scripts): release 0.5.1

CHANGES.md

@@ -3,7 +3,8 @@
 
 ## Table of Contents <!-- omit in toc -->
 
-- [0.5.0 - 26th August 2026](#050---1st-september-2026)
+- [0.5.1 - 14th September 2026](#051---14th-september-2026)
+- [0.5.0 - 1st September 2026](#050---1st-september-2026)
 - [0.4.2 - 25th August 2026](#042---25th-august-2026)
 - [0.4.1 - 17th August 2026](#041---17th-august-2026)
 - [0.4.0 - 16th August 2026](#040---16th-august-2026)
@@ -12,6 +13,16 @@
 - [0.1.1 - 11th August 2026](#011---11th-august-2026)
 
 
+## 0.5.1 - 14th September 2026
+
+* **shell-scripts/run_all_unit_tests/python/run_all_unit_tests.sh**:
+  * prefer project-local **`.venv/bin/python`** when present (before **`PYTHON_COMMAND_PATH`** / PATH discovery; avoids Apple/Xcode `python3`);
+  * load **`.sis/project_name.txt`** (fallback: directory basename) and optional **`.sis/script_info_lines.txt`** into `--help`;
+* Updated **shell-scripts/run_all_unit_tests/README.md** (venv preference; `.sis` help contract);
+* Updated **README.md** (JavaScript among shipped variants; Python prefers **`.venv`** when present);
+* Updated **NEWS.md** to the three-column chronology (**Date** | **News Item** | **Details**);
+
+
 ## 0.5.0 - 1st September 2026
 
 * **shell-scripts/run_all_unit_tests/javascript/run_all_unit_tests.sh**:

NEWS.md

@@ -1,15 +1,16 @@
 # misc-dev-scripts - News <!-- omit in toc -->
 
 
-| Date             | News Item      |
-| ---------------- | -------------- |
-| 1st September 2026 | [0.5.0 released](https://github.com/synesissoftware/misc-dev-scripts/releases/tag/0.5.0) |
-| 25th August 2026 | [0.4.2 released](https://github.com/synesissoftware/misc-dev-scripts/releases/tag/0.4.2) |
-| 17th August 2026 | [0.4.1 released](https://github.com/synesissoftware/misc-dev-scripts/releases/tag/0.4.1) |
-| 16th August 2026 | [0.4.0 released](https://github.com/synesissoftware/misc-dev-scripts/releases/tag/0.4.0) |
-| 15th August 2026 | [0.3.0 released](https://github.com/synesissoftware/misc-dev-scripts/releases/tag/0.3.0) |
-| 12th August 2026 | [0.2.0 released](https://github.com/synesissoftware/misc-dev-scripts/releases/tag/0.2.0) |
-| 11th August 2026 | [0.1.1 released](https://github.com/synesissoftware/misc-dev-scripts/releases/tag/0.1.1) |
+| Date                 | News Item | Details |
+| -------------------- | --------- | ------- |
+| 14th September 2026  | [**misc-dev-scripts** 0.5.1](https://github.com/synesissoftware/misc-dev-scripts/releases/tag/0.5.1) released | Python `.sis` help + prefer project `.venv` |
+| 1st September 2026   | [**misc-dev-scripts** 0.5.0](https://github.com/synesissoftware/misc-dev-scripts/releases/tag/0.5.0) released | JavaScript `run_all_unit_tests` runner      |
+| 25th August 2026     | [**misc-dev-scripts** 0.4.2](https://github.com/synesissoftware/misc-dev-scripts/releases/tag/0.4.2) released | Ruby `tput` TERM/TTY guard                  |
+| 17th August 2026     | [**misc-dev-scripts** 0.4.1](https://github.com/synesissoftware/misc-dev-scripts/releases/tag/0.4.1) released | Ruby rbenv discovery / failure propagation  |
+| 16th August 2026     | [**misc-dev-scripts** 0.4.0](https://github.com/synesissoftware/misc-dev-scripts/releases/tag/0.4.0) released | Python discovery and `--help` alignment     |
+| 15th August 2026     | [**misc-dev-scripts** 0.3.0](https://github.com/synesissoftware/misc-dev-scripts/releases/tag/0.3.0) released | Ruby `--rbenv-versions` via `RBENV_VERSION` |
+| 12th August 2026     | [**misc-dev-scripts** 0.2.0](https://github.com/synesissoftware/misc-dev-scripts/releases/tag/0.2.0) released | Ruby `--lib` / RUBYLIB                      |
+| 11th August 2026     | [**misc-dev-scripts** 0.1.1](https://github.com/synesissoftware/misc-dev-scripts/releases/tag/0.1.1) released | Initial docs, CI, and layout                |
 
 
 <!-- ########################### end of file ########################### -->

README.md

@@ -19,7 +19,7 @@ Miscellaneous Development Scripts
 
 ## Introduction
 
-**misc-dev-scripts** is a small catalog of shell helpers intended to be **copied** into Synesis (and related) language libraries — principally **run_all_unit_tests.sh** variants for **Python** and **Ruby** today, with further languages planned.
+**misc-dev-scripts** is a small catalog of shell helpers intended to be **copied** into Synesis (and related) language libraries — principally **run_all_unit_tests.sh** variants for **JavaScript**, **Python**, and **Ruby** today, with further languages planned.
 
 Canonical copies live under **shell-scripts/**; consuming projects keep a root-level **run_all_unit_tests.sh**. When updating a consumer, cite this repository’s **VERSION** in that project’s **CHANGES.md**.
 
@@ -35,10 +35,11 @@ See [**shell-scripts/run_all_unit_tests/README.md**](./shell-scripts/run_all_uni
 
 Language variants:
 
-* [**Python**](./shell-scripts/run_all_unit_tests/python/run_all_unit_tests.sh) — `unittest` discovery under **tests/**;
+* [**JavaScript**](./shell-scripts/run_all_unit_tests/javascript/run_all_unit_tests.sh) — `npm` / `pnpm` / `yarn` **`test`**;
+* [**Python**](./shell-scripts/run_all_unit_tests/python/run_all_unit_tests.sh) — `unittest` discovery under **tests/** (prefers **`.venv`** when present);
 * [**Ruby**](./shell-scripts/run_all_unit_tests/ruby/run_all_unit_tests.sh) — Test::Unit suite **test/unit/ts_all.rb** (or per-file `tc_*.rb` with `--separate`);
 
-Use `--help` on either variant for the authoritative flag list.
+Use `--help` on any variant for the authoritative flag list.
 
 
 ## Related projects

TODO.md

@@ -25,6 +25,7 @@
 * [x] invoke discovery as `python -m unittest discover -s <tests-dir> …`;
 * [x] Prefer `command -v` over `which`; quote `basename` expansions (Ruby already done; Python now aligned);
 * [x] Drop `python2` from default discovery; require `--include-python2-in-search` or `--assume-python2` when only `python2` is available;
+* [x] Prefer project-local **`.venv/bin/python`** when present; wire **`.sis/project_name.txt`** / **`.sis/script_info_lines.txt`** into `--help`;
 
 
 ### **Ruby** **run_all_unit_tests.sh**:

VERSION

@@ -1 +1 @@
-0.5.0
+0.5.1

shell-scripts/run_all_unit_tests/README.md

@@ -69,7 +69,7 @@ Use `--help` on the installed script for the authoritative flag list.
 ## Layout contracts
 
 * **JavaScript**: the script’s directory is treated as the project root (or the present working directory with `--pwd`); when **node_modules** is absent, dependencies are installed first (**npm ci** / **npm install**, or **pnpm** / **yarn** lockfile equivalents) unless **`--no-install`** is given; unit-tests are then executed via **`npm test`**, **`pnpm test`**, or **`yarn test`** (auto-detected from **pnpm-lock.yaml** / **yarn.lock**, or forced with `--npm` / `--pnpm` / `--yarn`); **package.json** must define the **`test`** script;
-* **Python**: the script’s directory is treated as the project root; tests live under **tests/** and are discovered with `python -m unittest discover -s <tests-dir>` (subdirectories participate when they contain `__init__.py`);
+* **Python**: the script’s directory is treated as the project root; tests live under **tests/** and are discovered with `python -m unittest discover -s <tests-dir>` (subdirectories participate when they contain `__init__.py`); optional **`.sis/project_name.txt`** (fallback: directory basename) and **`.sis/script_info_lines.txt`** feed `--help`;
 * **Ruby**: default suite is **test/unit/ts_all.rb**; with `--separate`, every **tc_*.rb** under the project tree is executed individually; `--pwd` uses the present working directory as the project root instead of the script directory; `--rbenv-versions` requires an available **rbenv** (**.ruby-version** is optional; **.ruby-version-exclusions** remains optional);
 
 
@@ -78,10 +78,11 @@ Use `--help` on the installed script for the authoritative flag list.
 **Python** (used when `--python-cmd-path` / `-p` is not given), in order:
 
 1. **`--assume-python2`** — if set, use `python2` (must be on `PATH` / executable);
-2. **`PYTHON_COMMAND_PATH`** — if set and executable, used as the interpreter;
-3. **`PYTHON_CMD_PATH`** — same, if the previous is unset or not executable;
-4. otherwise probe `python3`, then `python` on `PATH`; with **`--include-python2-in-search`**, also probe `python2`;
-5. if neither Python 2 flag is set and only `python2` is present on `PATH`, the script exits with an error suggesting **`--include-python2-in-search`** or **`--assume-python2`**;
+2. project-local **`.venv/bin/python`** — if executable, used as the interpreter (avoids Apple/Xcode `python3` on `PATH`);
+3. **`PYTHON_COMMAND_PATH`** — if set and executable, used as the interpreter;
+4. **`PYTHON_CMD_PATH`** — same, if the previous is unset or not executable;
+5. otherwise probe `python3`, then `python` on `PATH`; with **`--include-python2-in-search`**, also probe `python2`;
+6. if neither Python 2 flag is set and only `python2` is present on `PATH`, the script exits with an error suggesting **`--include-python2-in-search`** or **`--assume-python2`**;
 
 **JavaScript** and **Ruby**: colours use `tput` only when **`$TERM`** is set and stdout is a TTY (override with **`FG_BLUE`**, **`FG_RED`**, **`FD_BOLD`**, **`FD_NONE`**).
 

shell-scripts/run_all_unit_tests/python/run_all_unit_tests.sh

@@ -7,7 +7,7 @@
 #           calling directory
 #
 # Created:  13th February 2019
-# Updated:  11th August 2026
+# Updated:  14th September 2026
 #
 # Copyright (c) Matthew Wilson, 2019-2026
 # All rights reserved
@@ -54,6 +54,13 @@ done
 Dir="$(cd -P "$( dirname "$Source" )" && pwd)"
 Basename="$(basename "$Source")"
 
+ProjectNameFile="$Dir/.sis/project_name.txt"
+if [ -f "$ProjectNameFile" ]; then
+  ProjectName=$(tr -d '[:space:]' < "$ProjectNameFile")
+else
+  ProjectName=$(basename "$Dir")
+fi
+
 
 AssumePython2=
 IncludePython2InSearch=
@@ -84,9 +91,13 @@ do
       ;;
     --help)
 
+      [ -f "$Dir/.sis/script_info_lines.txt" ] && cat "$Dir/.sis/script_info_lines.txt"
+      echo
       cat << EOF
 USAGE: $Basename { | --help | [ --assume-python2 ] [ --include-python2-in-search ] [ --python-cmd-path <python-cmd-path> | -p <python-cmd-path> ] }
 
+${ProjectName} unit tests
+
 flags/options:
 
   --help
@@ -138,6 +149,18 @@ else
 
   # try and find a suitable command
 
+  # Prefer a project-local venv when present (avoids Apple/Xcode python3 on
+  # PATH, which must not be used for local install/test).
+  if [ "x_$PythonCommandPath" = "x_" ]; then
+
+    if [ -x "$Dir/.venv/bin/python" ]; then
+
+      PythonCommandPath="$Dir/.venv/bin/python"
+
+      echo "found project venv python '$PythonCommandPath'"
+    fi
+  fi
+
   if [ "x_$PythonCommandPath" = "x_" ]; then
 
     if [ "y_$PYTHON_COMMAND_PATH" != "y_" ]; then