Hook failures during upgrade from pre-0.5.0 to v0.5.x due to renamed scripts

[tormi]

Summary

When upgrading from a pre-0.5.0 version to v0.5.x, ddev restart produces multiple hook failures:

bash: ~/.ddev/wunderio/core/_run-scripts.sh: No such file or directory
Task failed: Exec command '~/.ddev/wunderio/core/_run-scripts.sh hooks-host-post-start.sh' on the host: exit status 127

bash: line 1: /mnt/ddev-global-cache/wunderio/core/_run-scripts.sh: No such file or directory
Task failed: Exec command '$WUNDERIO_GLOBAL_CACHE_WUNDERIO/core/_run-scripts.sh hooks-web-post-start.sh' in container/service 'web': exit status 127

bash: ~/.ddev/wunderio/core/hooks-host-post-start-update-check.sh: No such file or directory
Task failed: Exec command '~/.ddev/wunderio/core/hooks-host-post-start-update-check.sh' on the host: exit status 127

The site starts successfully, but the errors are confusing for developers.

Environment

• DDEV: v1.25.1
• Platform: macOS (arm64), Docker Desktop
• Addon: wunderio/ddev-wunderio-drupal v0.5.2

Root cause

v0.5.0 changed the hook script structure:

Pre-0.5.0 (old)	v0.5.0+ (new)
_run-scripts.sh	wdr-core.sh
hooks-host-post-start.sh (flat in core/)	hooks/host-post-start.sh (in hooks/ subdir)
hooks-host-post-start-update-check.sh (flat)	hooks/host-post-start-update-check.sh
hooks-web-post-start.sh (flat)	hooks/web-post-start.sh

During ddev restart:

1. The pre-start hook detects the outdated addon and runs ddev add-on get wunderio/ddev-wunderio-drupal, installing v0.5.x.
2. v0.5.x replaces the global files in ~/.ddev/wunderio/core/ with the new structure (removing _run-scripts.sh, adding wdr-core.sh and hooks/ subdir).
3. However, the post-start hooks for the current restart cycle were already loaded from the old config.wunderio.yaml before the addon was updated.
4. The old-style hook commands try to execute scripts that no longer exist, causing exit status 127 errors.

This is a one-time transitional issue — a race condition between the addon self-update in pre-start and the already-parsed post-start hooks. Running ddev restart a second time resolves it.

Suggestions

1. Add backward-compatibility shims

Ship thin wrapper scripts at the old paths that forward to the new ones during the transitional period:

# ~/.ddev/wunderio/core/_run-scripts.sh  (shim)
#!/usr/bin/env bash
exec "$(dirname "$0")/wdr-core.sh" "$@"

These can be removed in a later release.

2. Use removal_actions in the addon manifest

List the old files to be deleted on upgrade:

removal_actions:
  - global: wunderio/core/_run-scripts.sh
  - global: wunderio/core/hooks-host-post-start.sh
  - global: wunderio/core/hooks-web-post-start.sh
  - global: wunderio/core/hooks-host-post-start-update-check.sh

3. Add a cleanup step to pre-start

Extend the existing pre-start hook to remove known deprecated files:

pre-start:
  - exec-host: |
      rm -f "${DDEV_GLOBAL_DIR}/wunderio/core/_run-scripts.sh"
      rm -f "${DDEV_GLOBAL_DIR}/wunderio/core/hooks-host-post-start.sh"

4. Version-guard the post-start hooks

Add existence checks so hooks are resilient to version mismatches:

post-start:
  - exec-host: |
      if [ -x "${DDEV_GLOBAL_DIR}/wunderio/core/wdr-core.sh" ]; then
        "${DDEV_GLOBAL_DIR}/wunderio/core/wdr-core.sh" hooks host-post-start.sh
      fi

5. Document the upgrade path

Note in release notes that upgrading from pre-0.5.0 may require running ddev restart twice.