feat: [docs] clarify pinned tool delivery

.devcontainer/post_create_command.sh

@@ -18,7 +18,7 @@ npm install -g @devcontainers/cli
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd -P)"
 REPOSITORY_ROOT="$(cd "${SCRIPT_DIR}/.." && pwd -P)"
 
-sudo "${REPOSITORY_ROOT}/tools/tool_installer.py" install actionlint bazelisk buildifier ruff shellcheck yamlfmt
+sudo "${REPOSITORY_ROOT}/tools/internal/devcontainer/install.py" install actionlint bazelisk buildifier ruff shellcheck yamlfmt
 
 pre-commit install
 

.pre-commit-config.yaml

@@ -38,35 +38,41 @@ repos:
       # Formatters
       - id: yamlfmt
         name: yamlfmt
-        entry: tools/run_tool.sh yamlfmt
+        entry: tools/run-tool yamlfmt
         language: system
         types: [yaml]
       - id: ruff-format
         name: ruff format
-        entry: tools/run_tool.sh ruff format
+        entry: tools/run-tool ruff format
         language: system
         types: [python]
       - id: buildifier
         name: buildifier
-        entry: tools/run_tool.sh buildifier
+        entry: tools/run-tool buildifier
         language: system
         types: [bazel]
       # Static Code Analysis Tools
       - id: actionlint
         name: actionlint
-        entry: tools/run_tool.sh actionlint
+        entry: tools/run-tool actionlint
         language: system
         files: ^\.github/workflows/.*\.(yml|yaml)$
       - id: shellcheck
         name: shellcheck
-        entry: tools/run_tool.sh shellcheck
+        entry: tools/run-tool shellcheck
         language: system
         types: [shell]
       - id: ruff-check
         name: ruff check
-        entry: tools/run_tool.sh ruff check
+        entry: tools/run-tool ruff check
         language: system
         types: [python]
+      - id: tool-documentation
+        name: check tool documentation
+        entry: python3 tools/internal/sync_readme.py
+        language: system
+        pass_filenames: false
+        files: ^tools/(README\.md|internal/(sync_readme\.py|devcontainer/install\.py)|lockfiles/.*\.lock\.json)$
   - repo: https://github.com/eclipse-score/tooling
     rev: 31ff8eee214e4e97ef8f5cb46e443273515b63ec
     hooks:

MODULE.bazel

@@ -17,15 +17,15 @@ bazel_dep(name = "rules_multitool", version = "1.11.1")
 
 multitool = use_extension("@rules_multitool//multitool:extension.bzl", "multitool")
 multitool.hub(lockfile = "//tools:lockfiles/actionlint.lock.json")
+multitool.hub(lockfile = "//tools:lockfiles/apm.lock.json")
+multitool.hub(lockfile = "//tools:lockfiles/bazelisk.lock.json")
+multitool.hub(lockfile = "//tools:lockfiles/buildifier.lock.json")
+multitool.hub(lockfile = "//tools:lockfiles/opencode.lock.json")
 multitool.hub(lockfile = "//tools:lockfiles/ruff.lock.json")
 multitool.hub(lockfile = "//tools:lockfiles/shellcheck.lock.json")
-multitool.hub(lockfile = "//tools:lockfiles/yamlfmt.lock.json")
-multitool.hub(lockfile = "//tools:lockfiles/uv.lock.json")
-multitool.hub(lockfile = "//tools:lockfiles/buildifier.lock.json")
 multitool.hub(lockfile = "//tools:lockfiles/starpls.lock.json")
-multitool.hub(lockfile = "//tools:lockfiles/bazelisk.lock.json")
-multitool.hub(lockfile = "//tools:lockfiles/apm.lock.json")
-multitool.hub(lockfile = "//tools:lockfiles/opencode.lock.json")
+multitool.hub(lockfile = "//tools:lockfiles/uv.lock.json")
+multitool.hub(lockfile = "//tools:lockfiles/yamlfmt.lock.json")
 use_repo(multitool, "multitool")
 
 register_toolchains("@multitool//toolchains:all")

README.md

@@ -17,7 +17,7 @@ SPDX-License-Identifier: Apache-2.0
 # Common DevContainer for Eclipse S-CORE
 This repository contains the common [development container](https://containers.dev) for [Eclipse S-CORE](https://github.com/eclipse-score).
 It contains all tools required to develop (modify, build, ...) Eclipse S-CORE.
-All tool version are well-defined, and all tools are pre-configured to work as expected for Eclipse S-CORE development.
+All tool versions are well-defined, and all tools are pre-configured to work as expected for Eclipse S-CORE development.
 The container is [pre-built](https://containers.dev/guide/prebuild) in GitHub Actions as part of this repository, [tested, published](./docs/ci.md), and ready for use.
 
 Using the pre-built container in an Eclipse S-CORE repository is described in the [Usage](#usage) section.
@@ -79,7 +79,14 @@ Afterwards, Visual Studio Code should show this in the lower left corner of your
 
 ### Inside the Container
 
-Open a Terminal, and - for example - type `bazel build ...` to execute the default build of the repository.
+Open a terminal and, for example, run `bazel build ...` to execute the
+repository's default build.
+
+For pinned command-line tools that are also available outside the container,
+use the repository's `.devcontainer/run-tool` wrapper. It selects the
+container installation here and the matching Bazel target on the host. See
+[Pinned command-line tools](tools/README.md) for the supported commands and
+setup.
 
 After you have build the code, create [compilation databases](https://clang.llvm.org/docs/JSONCompilationDatabase.html) via Visual Studio Code [Task](https://code.visualstudio.com/docs/debugtest/tasks):
 

src/s-core-devcontainer/.devcontainer/bazel-feature/install.sh

@@ -29,7 +29,7 @@ rm -f "${COPY_TARGET}/devcontainer-features.env" "${COPY_TARGET}/devcontainer-fe
 DEBIAN_FRONTEND=noninteractive
 
 # Read tool versions + metadata into environment variables
-. /usr/local/share/score-tools/versions.sh /devcontainer/features/bazel/versions.yaml
+. /usr/local/share/score-tools/internal/devcontainer/load_feature_versions.sh /devcontainer/features/bazel/versions.yaml
 
 ARCHITECTURE=$(dpkg --print-architecture)
 
@@ -40,7 +40,7 @@ apt-get update
 apt-get install apt-transport-https -y
 
 # Lockfile-managed Bazel tooling
-/usr/local/share/score-tools/tool_installer.py install bazelisk buildifier starpls
+/usr/local/share/score-tools/internal/devcontainer/install.py install bazelisk buildifier starpls
 
 # Bazelisk + Bazel
 ln -sf /usr/local/bin/bazelisk /usr/local/bin/bazel

src/s-core-devcontainer/.devcontainer/bazel-feature/tests/test_default.sh

@@ -16,11 +16,11 @@
 set -euo pipefail
 
 # Read tool versions + metadata into environment variables
-. /usr/local/share/score-tools/versions.sh /devcontainer/features/bazel/versions.yaml
+. /usr/local/share/score-tools/internal/devcontainer/load_feature_versions.sh /devcontainer/features/bazel/versions.yaml
 
-bazelisk_lockfile_version="$(/usr/local/share/score-tools/tool_installer.py version bazelisk)"
-buildifier_lockfile_version="$(/usr/local/share/score-tools/tool_installer.py version buildifier)"
-starpls_lockfile_version="$(/usr/local/share/score-tools/tool_installer.py version starpls)"
+bazelisk_lockfile_version="$(/usr/local/share/score-tools/internal/devcontainer/install.py version bazelisk)"
+buildifier_lockfile_version="$(/usr/local/share/score-tools/internal/devcontainer/install.py version buildifier)"
+starpls_lockfile_version="$(/usr/local/share/score-tools/internal/devcontainer/install.py version starpls)"
 # Bazel-related tools
 ## This is the bazel version preinstalled in the devcontainer.
 ## A solid test would disable the network interface first to prevent a different version from being downloaded,

src/s-core-devcontainer/.devcontainer/devcontainer-lock.json

@@ -16,4 +16,4 @@
       "integrity": "sha256:00fd45550f578d9d515044d9e2226e908dbc3d7aa6fcb9dee4d8bdb60be114cf"
     }
   }
-}
+}

src/s-core-devcontainer/.devcontainer/s-core-local/install.sh

@@ -31,7 +31,7 @@ rm -f "${COPY_TARGET}/devcontainer-features.env" "${COPY_TARGET}/devcontainer-fe
 DEBIAN_FRONTEND=noninteractive
 
 # Read tool versions + metadata into environment variables
-. /usr/local/share/score-tools/versions.sh /devcontainer/features/s-core-local/versions.yaml
+. /usr/local/share/score-tools/internal/devcontainer/load_feature_versions.sh /devcontainer/features/s-core-local/versions.yaml
 
 ARCHITECTURE=$(dpkg --print-architecture)
 KERNEL=$(uname -s)
@@ -58,7 +58,7 @@ apt-get install -y "python${python_version}" python3-pip python3-venv
 apt-get install -y flake8 python3-autopep8 black python3-yapf mypy pydocstyle pycodestyle bandit pipenv virtualenv pylint
 
 # Lockfile-managed local developer tools
-/usr/local/share/score-tools/tool_installer.py install shellcheck ruff actionlint yamlfmt uv uvx apm opencode
+/usr/local/share/score-tools/internal/devcontainer/install.py install shellcheck ruff actionlint yamlfmt uv uvx apm opencode
 
 # GraphViz
 # The Ubuntu Noble package of GraphViz

src/s-core-devcontainer/.devcontainer/s-core-local/tests/test_default.sh

@@ -19,16 +19,16 @@ ARCHITECTURE=$(dpkg --print-architecture)
 KERNEL=$(uname -s)
 
 # Read tool versions + metadata into environment variables
-. /usr/local/share/score-tools/versions.sh /devcontainer/features/s-core-local/versions.yaml
-
-shellcheck_lockfile_version="$(/usr/local/share/score-tools/tool_installer.py version shellcheck)"
-ruff_lockfile_version="$(/usr/local/share/score-tools/tool_installer.py version ruff)"
-actionlint_lockfile_version="$(/usr/local/share/score-tools/tool_installer.py version actionlint)"
-yamlfmt_lockfile_version="$(/usr/local/share/score-tools/tool_installer.py version yamlfmt)"
-uv_lockfile_version="$(/usr/local/share/score-tools/tool_installer.py version uv)"
-uvx_lockfile_version="$(/usr/local/share/score-tools/tool_installer.py version uvx)"
-apm_lockfile_version="$(/usr/local/share/score-tools/tool_installer.py version apm)"
-opencode_lockfile_version="$(/usr/local/share/score-tools/tool_installer.py version opencode)"
+. /usr/local/share/score-tools/internal/devcontainer/load_feature_versions.sh /devcontainer/features/s-core-local/versions.yaml
+
+shellcheck_lockfile_version="$(/usr/local/share/score-tools/internal/devcontainer/install.py version shellcheck)"
+ruff_lockfile_version="$(/usr/local/share/score-tools/internal/devcontainer/install.py version ruff)"
+actionlint_lockfile_version="$(/usr/local/share/score-tools/internal/devcontainer/install.py version actionlint)"
+yamlfmt_lockfile_version="$(/usr/local/share/score-tools/internal/devcontainer/install.py version yamlfmt)"
+uv_lockfile_version="$(/usr/local/share/score-tools/internal/devcontainer/install.py version uv)"
+uvx_lockfile_version="$(/usr/local/share/score-tools/internal/devcontainer/install.py version uvx)"
+apm_lockfile_version="$(/usr/local/share/score-tools/internal/devcontainer/install.py version apm)"
+opencode_lockfile_version="$(/usr/local/share/score-tools/internal/devcontainer/install.py version opencode)"
 
 # pre-commit, it is available via $PATH in login shells, but not in non-login shells
 check "validate pre-commit is working and has the correct version" bash -c "pre-commit --version | grep '4.5.1'"