[#2848] Split provision example into demo, development module and example scripts.

.vortex/docs/content/drupal/provision-example.sh

@@ -8,11 +8,9 @@
 # This approach ensures a clear sequence and avoids potential ordering issues.
 #
 # Example:
-# - provision-10-example.sh
-# - provision-20-example.sh
-# - provision-30-example.sh
-#
-# shellcheck disable=SC2086
+# - provision-40-example.sh
+# - provision-50-example.sh
+# - provision-60-example.sh
 
 set -eu
 [ "${VORTEX_DEBUG-}" = "1" ] && set -x
@@ -22,6 +20,7 @@ set -eu
 info() { printf "   ==> %s\n" "${1}"; }
 note() { printf "       %s\n" "${1}"; }
 task() { printf "     > %s\n" "${1}"; }
+pass() { printf "     < %s\n" "${1}"; }
 
 drush() { ./vendor/bin/drush -y "$@"; }
 
@@ -31,24 +30,24 @@ info "Started example operations."
 environment="$(drush php:eval "print \Drupal\core\Site\Settings::get('environment');")"
 note "Environment: ${environment}"
 
-# 👇 Perform operations based on the current environment.
-if echo "${environment}" | grep -qxF -e local -e ci -e dev -e stage; then
-  note "Running example operations in non-production environment."
-
-  # 👇 Enable custom site modules and run its deployment hooks.
-  task "Installing custom site modules."
-  drush pm:install ys_base
-  drush pm:install ys_search
-  drush pm:install ys_demo
-
-  # 👇 Conditionally perform an action if this is a "fresh" database.
-  if [ "${VORTEX_PROVISION_OVERRIDE_DB:-0}" = "1" ]; then
-    note "Fresh database detected. Performing additional example operations."
-  else
-    note "Existing database detected. Performing additional example operations."
-  fi
-else
+# 👇 Stop early in the environments the operations should not run in.
+if ! echo "${environment}" | grep -qxF -e local -e ci -e dev -e stage; then
   note "Skipped example operations in production environment."
+  exit 0
+fi
+
+note "Running example operations in non-production environment."
+
+# 👇 Place your commands here.
+task "Performing an example operation."
+note "Replace this with your own commands."
+pass "Performed an example operation."
+
+# 👇 Conditionally perform an action if this is a "fresh" database.
+if [ "${VORTEX_PROVISION_OVERRIDE_DB:-0}" = "1" ]; then
+  note "Fresh database detected. Performing additional example operations."
+else
+  note "Existing database detected. Performing additional example operations."
 fi
 
 info "Finished example operations."

.vortex/docs/content/drupal/provision.mdx

@@ -233,11 +233,21 @@ specific order.
 
 To run custom scripts, create a new file in the `scripts` directory with the
 `provision-` prefix and the `.sh` extension, and make it executable with
-`chmod +x scripts/provision-10-example.sh`. The script will be automatically
+`chmod +x scripts/provision-50-custom.sh`. The script will be automatically
 discovered and executed.
 
 It is recommended to use a 2-digit suffix to control the order of execution:
-e.g., `provision-10-example.sh`, `provision-20-another-example.sh`.
+e.g., `provision-50-custom.sh`, `provision-60-another-custom.sh`.
+
+**Vortex** ships the following scripts:
+
+| Script                                | Purpose                                                  |
+|---------------------------------------|----------------------------------------------------------|
+| `provision-00-enable-demo-modules.sh` | Enables the modules and content model the demo site uses |
+| `provision-10-enable-dev-modules.sh`  | Enables the development modules                          |
+| `provision-20-migration.sh`           | Runs the content migration                               |
+| `provision-30-search-index.sh`        | Rebuilds the search index                                |
+| `provision-40-example.sh`             | A runnable example that performs no operations           |
 
 ### Conditional execution
 
@@ -280,6 +290,30 @@ import ProvisionScriptExample from '!!raw-loader!./provision-example.sh';
 
 </details>
 
+### Demo modules
+
+**Vortex** ships a `scripts/provision-00-enable-demo-modules.sh` custom script
+that stands up the demo site: it creates the content model, sets the site name,
+switches the administration interface to the core Navigation module, and installs
+the contrib, service and custom site modules before running their deployment
+hooks.
+
+It runs first so that the content model exists before the modules that depend on
+it are installed. Replace its operations with your own once the site stops
+relying on the demo content.
+
+### Development modules
+
+**Vortex** ships a `scripts/provision-10-enable-dev-modules.sh` custom script that
+installs the development modules - [Devel](https://www.drupal.org/project/devel)
+and [SDC Devel](https://www.drupal.org/project/sdc_devel).
+
+Development modules live in their own script so that they stay enabled after the
+demo and example scripts are adapted or removed.
+
+Both scripts run only in the `local`, `ci`, `dev` and `stage` environments. To
+opt out of either set of modules, remove the corresponding script.
+
 ### Search indexing
 
 Projects with the Solr service ship with a `scripts/provision-30-search-index.sh`

.vortex/installer/src/Prompts/Handlers/Modules.php

@@ -10,6 +10,13 @@
 
 class Modules extends AbstractHandler {
 
+  /**
+   * Modules installed by the dedicated development modules provision script.
+   *
+   * @var string[]
+   */
+  protected const DEV_MODULES = ['devel', 'sdc_devel'];
+
   /**
    * {@inheritdoc}
    */
@@ -83,8 +90,8 @@ public function process(): void {
         // Remove module from settings file.
         File::remove($t . '/' . $w . '/sites/default/includes/modules/settings.' . $module_name . '.php');
 
-        // Remove module from the provision example file.
-        File::replaceContentInFile($t . '/scripts/provision-10-example.sh', Replacement::create('module', function (string $content) use ($module_name): string {
+        // Remove module from the provision demo modules file.
+        File::replaceContentInFile($t . '/scripts/provision-00-enable-demo-modules.sh', Replacement::create('module', function (string $content) use ($module_name): string {
           $pattern = '/^(\s*)(drush\s+pm:install.*\b' . preg_quote($module_name, '/') . '\b.*)$/m';
           $content = preg_replace_callback($pattern, function (array $matches) use ($module_name): string {
             $indent = $matches[1];
@@ -108,6 +115,12 @@ public function process(): void {
       }
     }
 
+    // Without any development modules left to install, the script has no
+    // operations to perform, so remove it rather than shipping an empty shell.
+    if (count(array_intersect(static::DEV_MODULES, $selected_modules)) === 0) {
+      File::remove($t . '/scripts/provision-10-enable-dev-modules.sh');
+    }
+
     if (count($selected_modules) === 0) {
       File::removeTokenAsync('MODULE');
     }

.vortex/installer/tests/Fixtures/handler_process/_baseline/scripts/provision-00-enable-demo-modules.sh

@@ -0,0 +1,96 @@
+#!/usr/bin/env bash
+##
+# Enable the modules and the content model that the demo site is built from.
+#
+# This script is called during site provisioning via the provision script.
+#
+# Replace the operations below with your own once the site stops relying on the
+# demo content.
+#
+# shellcheck disable=SC2086
+
+set -eu
+[ "${VORTEX_DEBUG-}" = "1" ] && set -x
+
+# ------------------------------------------------------------------------------
+
+# @formatter:off
+info() { printf "   ==> %s\n" "${1}"; }
+note() { printf "       %s\n" "${1}"; }
+task() { printf "     > %s\n" "${1}"; }
+pass() { printf "     < %s\n" "${1}"; }
+fail() { printf "     ! %s\n" "${1}"; }
+# @formatter:on
+
+drush() { ./vendor/bin/drush -y "$@"; }
+
+# ------------------------------------------------------------------------------
+
+info "Started demo modules operations."
+
+environment="$(drush php:eval "print \Drupal\core\Site\Settings::get('environment');")"
+note "Environment: ${environment}"
+
+if ! echo "${environment}" | grep -qxF -e local -e ci -e dev -e stage; then
+  note "Skipped demo modules operations in production environment."
+  exit 0
+fi
+
+# The demo site modules attach behaviour to the 'page' content type, so it
+# must exist before those modules are installed and their deploy hooks run.
+task "Creating the content model."
+# Guard against environments where the Drupal CLI is not available.
+if [ -x ./vendor/bin/dr ]; then
+  ./vendor/bin/dr recipe "$(pwd)/recipes/page" --no-interaction
+fi
+pass "Created the content model."
+
+task "Setting site name."
+drush php:eval "\Drupal::service('config.factory')->getEditable('system.site')->set('name', 'star wars')->save();"
+pass "Set site name."
+
+# Use the core Navigation module as the administration interface and remove
+# the classic Toolbar so the two admin systems never run at once. Uninstall
+# only when Toolbar is actually enabled (it is absent on re-provision or a
+# navigation-based database); a genuine uninstall failure must still abort.
+task "Setting up the administration navigation."
+drush pm:install navigation
+if [ "$(drush php:eval "print \Drupal::moduleHandler()->moduleExists('toolbar');")" = "1" ]; then
+  drush pm:uninstall toolbar
+fi
+pass "Set up the administration navigation."
+
+task "Installing contrib modules."
+drush pm:install coffee config_split config_update media environment_indicator navigation_extra_tools pathauto redirect reroute_email robotstxt shield stage_file_proxy xmlsitemap
+pass "Installed contrib modules."
+
+task "Installing Redis module."
+drush pm:install redis || true
+pass "Installed Redis module."
+
+task "Installing and configuring ClamAV."
+drush pm:install clamav
+drush config-set clamav.settings mode_daemon_tcpip.hostname clamav
+pass "Installed and configured ClamAV."
+
+task "Installing Solr search modules."
+drush pm:install search_api search_api_solr
+pass "Installed Solr search modules."
+
+# Enable custom site module and run its deployment hooks.
+#
+# Note that deployment hooks for already enabled modules have run in the
+# parent "provision.sh" script.
+task "Installing custom site modules."
+drush pm:install sw_base
+
+drush pm:install sw_search
+
+drush pm:install sw_demo
+pass "Installed custom site modules."
+
+task "Running deployment hooks."
+drush deploy:hook
+pass "Ran deployment hooks."
+
+info "Finished demo modules operations."

.vortex/installer/tests/Fixtures/handler_process/_baseline/scripts/provision-10-enable-dev-modules.sh

@@ -0,0 +1,45 @@
+#!/usr/bin/env bash
+##
+# Enable development modules.
+#
+# This script is called during site provisioning via the provision script.
+#
+# Development modules are enabled here rather than in the example script so that
+# they remain available after the example script is adjusted or removed.
+
+set -eu
+[ "${VORTEX_DEBUG-}" = "1" ] && set -x
+
+# ------------------------------------------------------------------------------
+
+# @formatter:off
+info() { printf "   ==> %s\n" "${1}"; }
+note() { printf "       %s\n" "${1}"; }
+task() { printf "     > %s\n" "${1}"; }
+pass() { printf "     < %s\n" "${1}"; }
+fail() { printf "     ! %s\n" "${1}"; }
+# @formatter:on
+
+drush() { ./vendor/bin/drush -y "$@"; }
+
+# ------------------------------------------------------------------------------
+
+info "Started development modules operations."
+
+environment="$(drush php:eval "print \Drupal\core\Site\Settings::get('environment');")"
+note "Environment: ${environment}"
+
+if ! echo "${environment}" | grep -qxF -e local -e ci -e dev -e stage; then
+  note "Skipped installing development modules in production environment."
+  exit 0
+fi
+
+task "Installing Single Directory Component development tools."
+drush pm:install sdc_devel || true
+pass "Installed Single Directory Component development tools."
+
+task "Installing Devel module."
+drush pm:install devel || true
+pass "Installed Devel module."
+
+info "Finished development modules operations."