Support workflow consumers without a local DevTools dependency

.github/actions/changelog/create-dependabot-entry/run.sh

@@ -1,15 +1,15 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
-entry_message="$(php -r 'require "vendor/autoload.php"; $resolver = new \FastForward\DevTools\Changelog\DependabotChangelogEntryMessageResolver(); echo $resolver->resolve(getenv("INPUT_PULL_REQUEST_TITLE") ?: "", (int) (getenv("INPUT_PULL_REQUEST_NUMBER") ?: 0));')"
+entry_message="$(php -r 'require getenv("DEV_TOOLS_AUTOLOAD") ?: "vendor/autoload.php"; $resolver = new \FastForward\DevTools\Changelog\DependabotChangelogEntryMessageResolver(); echo $resolver->resolve(getenv("INPUT_PULL_REQUEST_TITLE") ?: "", (int) (getenv("INPUT_PULL_REQUEST_NUMBER") ?: 0));')"
 
 git fetch --no-tags --depth=1 origin "+refs/heads/${INPUT_BASE_REF}:refs/remotes/origin/${INPUT_BASE_REF}"
 git fetch --no-tags --depth=1 origin "+refs/heads/${INPUT_HEAD_REF}:refs/remotes/origin/${INPUT_HEAD_REF}"
 git switch -C "${INPUT_HEAD_REF}" "refs/remotes/origin/${INPUT_HEAD_REF}"
 git config user.name "github-actions[bot]"
 git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
 
-if composer dev-tools changelog:check -- --file="${INPUT_CHANGELOG_FILE}" --against="origin/${INPUT_BASE_REF}" >/dev/null 2>&1; then
+if dev-tools changelog:check --file="${INPUT_CHANGELOG_FILE}" --against="origin/${INPUT_BASE_REF}" >/dev/null 2>&1; then
     {
         echo "created=false"
         echo "status=already-present"
@@ -19,7 +19,7 @@ if composer dev-tools changelog:check -- --file="${INPUT_CHANGELOG_FILE}" --agai
     exit 0
 fi
 
-composer dev-tools changelog:entry -- --type=changed --file="${INPUT_CHANGELOG_FILE}" "${entry_message}"
+dev-tools changelog:entry --type=changed --file="${INPUT_CHANGELOG_FILE}" "${entry_message}"
 git add "${INPUT_CHANGELOG_FILE}"
 
 if git diff --cached --quiet -- "${INPUT_CHANGELOG_FILE}"; then
@@ -35,7 +35,7 @@ fi
 git commit -m "Add changelog entry for Dependabot PR #${INPUT_PULL_REQUEST_NUMBER}"
 git push origin "HEAD:${INPUT_HEAD_REF}"
 
-if ! composer dev-tools changelog:check -- --file="${INPUT_CHANGELOG_FILE}" --against="origin/${INPUT_BASE_REF}" >/dev/null 2>&1; then
+if ! dev-tools changelog:check --file="${INPUT_CHANGELOG_FILE}" --against="origin/${INPUT_BASE_REF}" >/dev/null 2>&1; then
     {
         echo "created=false"
         echo "status=missing"

.github/actions/changelog/render-release-notes/run.sh

@@ -2,4 +2,4 @@
 set -euo pipefail
 
 mkdir -p "$(dirname "${INPUT_OUTPUT_FILE}")"
-composer dev-tools changelog:show -- "${INPUT_VERSION}" --file="${INPUT_CHANGELOG_FILE}" > "${INPUT_OUTPUT_FILE}"
+dev-tools changelog:show "${INPUT_VERSION}" --file="${INPUT_CHANGELOG_FILE}" > "${INPUT_OUTPUT_FILE}"

.github/actions/changelog/resolve-version/run.sh

@@ -5,7 +5,7 @@ if [ -n "${INPUT_VERSION}" ]; then
     version="${INPUT_VERSION}"
     source="input"
 else
-    version="$(composer dev-tools changelog:next-version -- --file="${INPUT_CHANGELOG_FILE}")"
+    version="$(dev-tools changelog:next-version --file="${INPUT_CHANGELOG_FILE}")"
     source="inferred"
 fi
 

.github/actions/github/resolve-predictable-conflicts/resolve-changelog.php

@@ -6,7 +6,7 @@
 use FastForward\DevTools\Changelog\Parser\ChangelogParser;
 use FastForward\DevTools\Changelog\Renderer\MarkdownRenderer;
 
-$autoload = getenv('DEV_TOOLS_AUTO_RESOLVE_AUTOLOAD') ?: getcwd() . '/vendor/autoload.php';
+$autoload = getenv('DEV_TOOLS_AUTO_RESOLVE_AUTOLOAD') ?: getenv('DEV_TOOLS_AUTOLOAD') ?: getcwd() . '/vendor/autoload.php';
 
 if (! is_file($autoload)) {
     fwrite(STDERR, sprintf("Composer autoload file not found: %s\n", $autoload));

.github/actions/php/setup-composer/action.yml

@@ -1,5 +1,5 @@
 name: Setup PHP and Composer Dependencies
-description: Setup PHP, warm Composer cache, mark safe directories, and install dependencies.
+description: Setup PHP, install Composer dependencies when available, and expose a deterministic DevTools runtime.
 
 inputs:
   php-version:
@@ -29,6 +29,21 @@ inputs:
     description: Additional newline-separated directories to mark as safe for git.
     required: false
     default: ''
+  dev-tools-source-directory:
+    description: Checked-out DevTools workflow source used to resolve the fallback runtime when the consumer does not install DevTools locally.
+    required: false
+    default: .dev-tools-actions
+
+outputs:
+  dev-tools-binary:
+    description: Absolute path to the resolved DevTools binary.
+    value: ${{ steps.expose-dev-tools.outputs.binary }}
+  dev-tools-autoload:
+    description: Absolute path to the runtime autoload file used by packaged workflow helpers.
+    value: ${{ steps.expose-dev-tools.outputs.autoload }}
+  dev-tools-source:
+    description: Runtime source selected for this job, either `local` or `workflow`.
+    value: ${{ steps.expose-dev-tools.outputs.source }}
 
 runs:
   using: composite
@@ -40,15 +55,6 @@ runs:
         extensions: ${{ inputs.extensions }}
         coverage: ${{ inputs.coverage }}
 
-    - name: Cache Composer dependencies
-      uses: actions/cache@v5
-      with:
-        path: ${{ inputs.cache-dir }}
-        key: ${{ runner.os }}-composer-${{ inputs.php-version }}-${{ hashFiles('**/composer.lock') }}
-        restore-keys: |
-          ${{ runner.os }}-composer-${{ inputs.php-version }}-
-          ${{ runner.os }}-composer-
-
     - name: Mark workspace as safe for git
       shell: bash
       env:
@@ -64,11 +70,48 @@ runs:
           done
         fi
 
-    - name: Install dependencies
+    - name: Detect consumer Composer manifest
+      id: consumer-composer
       shell: bash
+      run: |
+        if [ -f composer.json ]; then
+          echo "present=true" >> "$GITHUB_OUTPUT"
+        else
+          echo "present=false" >> "$GITHUB_OUTPUT"
+        fi
+
+    - name: Install consumer dependencies
+      if: steps.consumer-composer.outputs.present == 'true'
+      uses: ramsey/composer-install@65e4f84970763564f46a70b8a54b90d033b3bdda # 4.0.0
       env:
         COMPOSER_AUTH: '{"github-oauth": {"github.com": "${{ github.token }}"} }'
         COMPOSER_CACHE_DIR: ${{ inputs.cache-dir }}
         COMPOSER_ROOT_VERSION: ${{ inputs.root-version }}
-        INPUT_INSTALL_OPTIONS: ${{ inputs.install-options }}
-      run: composer install ${INPUT_INSTALL_OPTIONS}
+      with:
+        composer-options: ${{ inputs.install-options }}
+
+    - name: Resolve DevTools runtime source
+      id: resolve-dev-tools
+      shell: bash
+      env:
+        INPUT_DEV_TOOLS_SOURCE_DIRECTORY: ${{ inputs.dev-tools-source-directory }}
+      run: ${{ github.action_path }}/detect-dev-tools-runtime.sh
+
+    - name: Install fallback DevTools runtime
+      if: steps.resolve-dev-tools.outputs.needs-fallback == 'true'
+      uses: ramsey/composer-install@65e4f84970763564f46a70b8a54b90d033b3bdda # 4.0.0
+      env:
+        COMPOSER_AUTH: '{"github-oauth": {"github.com": "${{ github.token }}"} }'
+        COMPOSER_CACHE_DIR: ${{ inputs.cache-dir }}
+      with:
+        working-directory: ${{ inputs.dev-tools-source-directory }}
+        composer-options: --prefer-dist --no-plugins --no-scripts
+        require-lock-file: 'true'
+        custom-cache-suffix: dev-tools-runtime
+
+    - name: Expose DevTools runtime
+      id: expose-dev-tools
+      shell: bash
+      env:
+        INPUT_DEV_TOOLS_SOURCE_DIRECTORY: ${{ inputs.dev-tools-source-directory }}
+      run: ${{ github.action_path }}/expose-dev-tools-runtime.sh

.github/actions/php/setup-composer/detect-dev-tools-runtime.sh

@@ -0,0 +1,20 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+source "$(dirname "$0")/dev-tools-runtime-lib.sh"
+
+resolve_dev_tools_runtime
+
+needs_fallback='false'
+
+if runtime_requires_workflow_fallback; then
+    needs_fallback='true'
+fi
+
+{
+    printf 'source=%s\n' "${DEV_TOOLS_RUNTIME_SOURCE}"
+    printf 'needs-fallback=%s\n' "${needs_fallback}"
+    printf 'binary=%s\n' "${DEV_TOOLS_RUNTIME_BINARY}"
+    printf 'autoload=%s\n' "${DEV_TOOLS_RUNTIME_AUTOLOAD}"
+    printf 'source-directory=%s\n' "${DEV_TOOLS_SOURCE_DIRECTORY}"
+} >> "${GITHUB_OUTPUT}"

.github/actions/php/setup-composer/dev-tools-runtime-lib.sh

@@ -0,0 +1,94 @@
+#!/usr/bin/env bash
+
+resolve_dev_tools_workspace_path() {
+    local input_path="${1:-.}"
+
+    if [[ "${input_path}" = /* ]]; then
+        printf '%s\n' "${input_path}"
+
+        return
+    fi
+
+    printf '%s/%s\n' "$(pwd)" "${input_path#./}"
+}
+
+workspace_is_dev_tools_repository() {
+    local workspace_root="${1:?Workspace root is required}"
+    local composer_json="${workspace_root}/composer.json"
+
+    if [ ! -f "${composer_json}" ]; then
+        return 1
+    fi
+
+    php -r '
+        $composer = json_decode((string) file_get_contents($argv[1]), true);
+
+        if (! is_array($composer)) {
+            exit(1);
+        }
+
+        exit(($composer["name"] ?? null) === "fast-forward/dev-tools" ? 0 : 1);
+    ' "${composer_json}"
+}
+
+resolve_dev_tools_runtime() {
+    local source_directory_input="${INPUT_DEV_TOOLS_SOURCE_DIRECTORY:-.dev-tools-actions}"
+
+    DEV_TOOLS_WORKSPACE_ROOT="$(pwd)"
+    DEV_TOOLS_SOURCE_DIRECTORY="$(resolve_dev_tools_workspace_path "${source_directory_input}")"
+    DEV_TOOLS_LOCAL_AUTOLOAD="${DEV_TOOLS_WORKSPACE_ROOT}/vendor/autoload.php"
+    DEV_TOOLS_LOCAL_INSTALLED_BINARY="${DEV_TOOLS_WORKSPACE_ROOT}/vendor/bin/dev-tools"
+    DEV_TOOLS_LOCAL_INSTALLED_PACKAGE_ROOT="${DEV_TOOLS_WORKSPACE_ROOT}/vendor/fast-forward/dev-tools"
+    DEV_TOOLS_LOCAL_REPOSITORY_BINARY="${DEV_TOOLS_WORKSPACE_ROOT}/bin/dev-tools"
+
+    if [ -x "${DEV_TOOLS_LOCAL_INSTALLED_BINARY}" ] && [ -f "${DEV_TOOLS_LOCAL_AUTOLOAD}" ] && workspace_is_dev_tools_repository "${DEV_TOOLS_LOCAL_INSTALLED_PACKAGE_ROOT}"; then
+        DEV_TOOLS_RUNTIME_SOURCE='local'
+        DEV_TOOLS_RUNTIME_BINARY="${DEV_TOOLS_LOCAL_INSTALLED_BINARY}"
+        DEV_TOOLS_RUNTIME_AUTOLOAD="${DEV_TOOLS_LOCAL_AUTOLOAD}"
+
+        return 0
+    fi
+
+    if [ -x "${DEV_TOOLS_LOCAL_REPOSITORY_BINARY}" ] && [ -f "${DEV_TOOLS_LOCAL_AUTOLOAD}" ] && workspace_is_dev_tools_repository "${DEV_TOOLS_WORKSPACE_ROOT}"; then
+        DEV_TOOLS_RUNTIME_SOURCE='local'
+        DEV_TOOLS_RUNTIME_BINARY="${DEV_TOOLS_LOCAL_REPOSITORY_BINARY}"
+        DEV_TOOLS_RUNTIME_AUTOLOAD="${DEV_TOOLS_LOCAL_AUTOLOAD}"
+
+        return 0
+    fi
+
+    if [ ! -d "${DEV_TOOLS_SOURCE_DIRECTORY}" ]; then
+        echo "The DevTools workflow source directory was not found: ${DEV_TOOLS_SOURCE_DIRECTORY}" >&2
+
+        return 1
+    fi
+
+    if ! workspace_is_dev_tools_repository "${DEV_TOOLS_SOURCE_DIRECTORY}"; then
+        echo "The DevTools workflow source directory does not point to the fast-forward/dev-tools package: ${DEV_TOOLS_SOURCE_DIRECTORY}" >&2
+        echo "Checkout the full php-fast-forward/dev-tools source into ${source_directory_input} before using this action." >&2
+
+        return 1
+    fi
+
+    DEV_TOOLS_RUNTIME_SOURCE='workflow'
+    DEV_TOOLS_RUNTIME_BINARY="${DEV_TOOLS_SOURCE_DIRECTORY}/bin/dev-tools"
+    DEV_TOOLS_RUNTIME_AUTOLOAD="${DEV_TOOLS_SOURCE_DIRECTORY}/vendor/autoload.php"
+}
+
+runtime_requires_workflow_fallback() {
+    [ "${DEV_TOOLS_RUNTIME_SOURCE}" = 'workflow' ]
+}
+
+ensure_resolved_runtime_is_available() {
+    if [ ! -x "${DEV_TOOLS_RUNTIME_BINARY}" ]; then
+        echo "Resolved DevTools binary is not executable: ${DEV_TOOLS_RUNTIME_BINARY}" >&2
+
+        return 1
+    fi
+
+    if [ ! -f "${DEV_TOOLS_RUNTIME_AUTOLOAD}" ]; then
+        echo "Resolved DevTools autoload file was not found: ${DEV_TOOLS_RUNTIME_AUTOLOAD}" >&2
+
+        return 1
+    fi
+}

.github/actions/php/setup-composer/expose-dev-tools-runtime.sh

@@ -0,0 +1,36 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+source "$(dirname "$0")/dev-tools-runtime-lib.sh"
+
+resolve_dev_tools_runtime
+ensure_resolved_runtime_is_available
+
+runtime_directory="${RUNNER_TEMP:-${TMPDIR:-/tmp}}/dev-tools-runtime/bin"
+wrapper_path="${runtime_directory}/dev-tools"
+
+mkdir -p "${runtime_directory}"
+
+{
+    printf '#!/usr/bin/env bash\n'
+    printf 'set -euo pipefail\n'
+    printf 'exec %q "$@"\n' "${DEV_TOOLS_RUNTIME_BINARY}"
+} > "${wrapper_path}"
+
+chmod +x "${wrapper_path}"
+
+{
+    printf 'DEV_TOOLS_BINARY=%s\n' "${DEV_TOOLS_RUNTIME_BINARY}"
+    printf 'DEV_TOOLS_AUTOLOAD=%s\n' "${DEV_TOOLS_RUNTIME_AUTOLOAD}"
+    printf 'DEV_TOOLS_AUTO_RESOLVE_AUTOLOAD=%s\n' "${DEV_TOOLS_RUNTIME_AUTOLOAD}"
+    printf 'DEV_TOOLS_RUNTIME_SOURCE=%s\n' "${DEV_TOOLS_RUNTIME_SOURCE}"
+} >> "${GITHUB_ENV}"
+
+printf '%s\n' "${runtime_directory}" >> "${GITHUB_PATH}"
+
+{
+    printf 'binary=%s\n' "${DEV_TOOLS_RUNTIME_BINARY}"
+    printf 'autoload=%s\n' "${DEV_TOOLS_RUNTIME_AUTOLOAD}"
+    printf 'source=%s\n' "${DEV_TOOLS_RUNTIME_SOURCE}"
+    printf 'command=%s\n' "${wrapper_path}"
+} >> "${GITHUB_OUTPUT}"

.github/workflows/auto-resolve-conflicts.yml

@@ -63,8 +63,6 @@ jobs:
                   repository: php-fast-forward/dev-tools
                   ref: ${{ github.repository == 'php-fast-forward/dev-tools' && github.sha || 'main' }}
                   path: .dev-tools-actions
-                  sparse-checkout: |
-                      .github/actions
 
             - name: Setup PHP and install dependencies
               uses: ./.dev-tools-actions/.github/actions/php/setup-composer

.github/workflows/changelog.yml

@@ -108,8 +108,6 @@ jobs:
                   repository: php-fast-forward/dev-tools
                   ref: ${{ github.repository == 'php-fast-forward/dev-tools' && (github.event_name == 'pull_request_target' && github.event.pull_request.base.sha || github.sha) || 'main' }}
                   path: .dev-tools-actions
-                  sparse-checkout: |
-                      .github/actions
 
             - name: Setup PHP and install dependencies
               uses: ./.dev-tools-actions/.github/actions/php/setup-composer
@@ -133,7 +131,7 @@ jobs:
                   pull-request-title: ${{ env.PULL_REQUEST_TITLE }}
 
             - name: Verify changelog update
-              run: composer dev-tools changelog:check -- --file="${CHANGELOG_FILE}" --against="origin/${BASE_REF}"
+              run: dev-tools changelog:check --file="${CHANGELOG_FILE}" --against="origin/${BASE_REF}"
 
             - uses: ./.dev-tools-actions/.github/actions/summary/write
               with:
@@ -199,8 +197,6 @@ jobs:
                   repository: php-fast-forward/dev-tools
                   ref: ${{ github.repository == 'php-fast-forward/dev-tools' && (github.event_name == 'pull_request_target' && github.event.pull_request.base.sha || github.sha) || 'main' }}
                   path: .dev-tools-actions
-                  sparse-checkout: |
-                      .github/actions
 
             - name: Setup PHP and install dependencies
               uses: ./.dev-tools-actions/.github/actions/php/setup-composer
@@ -221,7 +217,7 @@ jobs:
                   RELEASE_VERSION: ${{ steps.version.outputs.value }}
               run: |
                   release_date="$(date -u +%F)"
-                  composer dev-tools changelog:promote -- "${RELEASE_VERSION}" --file="${CHANGELOG_FILE}" --date="${release_date}"
+                  dev-tools changelog:promote "${RELEASE_VERSION}" --file="${CHANGELOG_FILE}" --date="${release_date}"
 
             - name: Render release notes preview
               uses: ./.dev-tools-actions/.github/actions/changelog/render-release-notes
@@ -308,8 +304,6 @@ jobs:
                   repository: php-fast-forward/dev-tools
                   ref: ${{ github.repository == 'php-fast-forward/dev-tools' && (github.event_name == 'pull_request_target' && github.event.pull_request.base.sha || github.sha) || 'main' }}
                   path: .dev-tools-actions
-                  sparse-checkout: |
-                      .github/actions
 
             - name: Setup PHP and install dependencies
               uses: ./.dev-tools-actions/.github/actions/php/setup-composer

.github/workflows/reports.yml

@@ -77,8 +77,6 @@ jobs:
                 repository: php-fast-forward/dev-tools
                 ref: ${{ github.repository == 'php-fast-forward/dev-tools' && (github.event_name == 'pull_request_target' && github.event.pull_request.base.sha || github.sha) || 'main' }}
                 path: .dev-tools-actions
-                sparse-checkout: |
-                  .github/actions
 
             - name: Setup PHP and install dependencies
               uses: ./.dev-tools-actions/.github/actions/php/setup-composer
@@ -91,7 +89,7 @@ jobs:
             - name: Generate reports
               env:
                 COMPOSER_ROOT_VERSION: ${{ env.REPORTS_ROOT_VERSION }}
-              run: composer dev-tools reports -- --target="${REPORTS_TARGET}" --coverage="${REPORTS_TARGET}/coverage" --metrics="${REPORTS_TARGET}/metrics"
+              run: dev-tools reports --target="${REPORTS_TARGET}" --coverage="${REPORTS_TARGET}/coverage" --metrics="${REPORTS_TARGET}/metrics"
 
             - name: Fix permissions
               run: |