@webship.co/workspace 1.0.0-alpha1 → 1.0.0-beta2

package/core/scripts/functions/fun-testing.sh

@@ -0,0 +1,329 @@
+#!/usr/bin/env bash
+
+# The automated-testing stack of an EXISTING project: set it up, and run it.
+#
+# The cmd-automated-testing-*-project.sh builders in the test workspace do this as part of
+# building a site from nothing — they delete the directory first, which is exactly what you do not
+# want on a project you already have. These two verbs are the same stack applied to a project that
+# is already there.
+#
+# Two stacks are supported:
+#
+#   in-project  Some project templates ship a DDEV testing command of their own —
+#               `ddev init-full-automated-testing` installs the site if needed, adds the testing
+#               users and prepares Playwright. If the command is in the project, it is the right
+#               one, because it knows that project.
+#   webship-js  Everything else gets webship-js (Playwright + Cucumber-js) through its DDEV add-on,
+#               github.com/webship/ddev-webship-js, which scaffolds cucumber.js, the feature files,
+#               the step definitions and the report/screenshot/video directories, preserving
+#               anything already there.
+#
+# Both write their results to <project>/tests/reports/, which is what the dashboard's Tests menu
+# reads.
+
+# Which stack a project has, or would get.
+# Where Playwright keeps its browsers.
+#
+# NOT the default `~/.cache/ms-playwright` inside the web container: that lives in the container's
+# writable layer, so a `ddev restart` — which `ddev init-full-automated-testing` and the add-on both
+# do as part of setting up — throws away the 113 MB that had just been downloaded, and the next run
+# fails with "Executable doesn't exist at …/chrome-headless-shell". `/mnt/ddev-global-cache` is a
+# docker volume DDEV mounts into every web container, so the download survives a restart AND is
+# shared by every project instead of being fetched once per site. The directory names carry the
+# Playwright build number, so two projects on two versions do not collide.
+readonly TESTING_BROWSERS_PATH='/mnt/ddev-global-cache/ms-playwright';
+
+# Install the browsers if they are not already in the shared cache. Idempotent and quick when they
+# are, so it is safe to call before every run — which is what makes a wiped container self-heal
+# rather than failing 275 scenarios in 1.6 seconds.
+# PLAYWRIGHT_SKIP_BROWSER_GC=1 is not optional here.
+#
+# `playwright install` sweeps the browsers directory and DELETES every build its own version does
+# not know about. In a per-container cache that is housekeeping; in a SHARED one it is one project
+# destroying another's browser — and it did: installing for the dashboard (Playwright 1.62,
+# chromium 1234) removed the 1223 build a project's suite was running against, which failed the
+# remaining 213 of its 275 scenarios with "Executable doesn't exist" twenty minutes in. Skipping the
+# collection leaves both builds in place; they are a few hundred MB and the disk is not the problem
+# a shared cache was solving.
+# The shared libraries chromium itself needs (libnspr4, libnss3, the X and font
+# stack). They belong in the IMAGE, not in a running container: `ddev restart`
+# recreates the container, so `playwright install-deps` run once at setup time is
+# gone by the next suite and every scenario dies at browser launch with
+#   error while loading shared libraries: libnspr4.so
+# A build file in .ddev/web-build/ is rebuilt into the image on every start, so
+# the libraries survive restarts, rebuilds and a `ddev delete` + rebuild.
+readonly TESTING_BROWSER_LIBS_BUILD='.ddev/web-build/Dockerfile.playwright';
+
+function testing_write_browser_libs_build() {
+  local project_path="$1";
+  mkdir -p "${project_path}/.ddev/web-build" || return 1 ;
+  cat > "${project_path}/${TESTING_BROWSER_LIBS_BUILD}" <<'DOCKERFILE'
+# The shared libraries Playwright's chromium needs, baked into the web image so
+# they survive `ddev restart` — installed by the workspace testing tooling.
+# Playwright resolves the package names for this Debian release itself; the apt
+# list is the fallback for a build with no network access to npm.
+RUN npx --yes playwright@1.56 install-deps chromium || \
+    (apt-get update && apt-get install -y --no-install-recommends \
+      libnspr4 libnss3 libdbus-1-3 libatk1.0-0t64 libatk-bridge2.0-0t64 libcups2t64 \
+      libdrm2 libatspi2.0-0t64 libxcomposite1 libxdamage1 libxfixes3 libxrandr2 \
+      libgbm1 libxkbcommon0 libasound2t64 libpango-1.0-0 libcairo2 fonts-liberation \
+      && rm -rf /var/lib/apt/lists/*)
+DOCKERFILE
+}
+
+# Is chromium actually able to start in this project's web container?
+function testing_browser_libs_ok() {
+  ddev exec 'ldconfig -p | grep -q libnspr4' > /dev/null 2>&1 ;
+}
+
+# Make sure it is, rebuilding the image once if it is not. Called before every
+# run, so a project that predates this — or one whose image was rebuilt from an
+# older config — heals itself instead of failing the whole suite at step one.
+function testing_ensure_browser_libs() {
+  local project_path="$1";
+  if testing_browser_libs_ok ; then
+    return 0 ;
+  fi
+  echo "";
+  echo "The chromium libraries are missing from this project's web container — adding them to the image.";
+  testing_write_browser_libs_build "${project_path}" || return 1 ;
+  ddev restart || return 1 ;
+  if testing_browser_libs_ok ; then
+    echo "The browser libraries are in place.";
+    return 0 ;
+  fi
+  echo "The browser libraries are still missing after the rebuild — check ${TESTING_BROWSER_LIBS_BUILD}.";
+  return 1 ;
+}
+
+function testing_install_browsers() {
+  echo "Making sure the Playwright browsers are in the shared DDEV cache.";
+  ddev exec "PLAYWRIGHT_BROWSERS_PATH=${TESTING_BROWSERS_PATH} PLAYWRIGHT_SKIP_BROWSER_GC=1 npx playwright install chromium" || return 1 ;
+}
+
+function testing_stack() {
+  local project_path="$1";
+  if [ -f "${project_path}/.ddev/commands/web/init-full-automated-testing" ] ; then
+    printf 'in-project' ; return 0 ;
+  fi
+  # webship-js (github.com/webship/webship-js) is cucumber-js + Playwright, and its footprint is
+  # the cucumber.js config at the project root plus the step definitions it points at.
+  if [ -f "${project_path}/cucumber.js" ] || [ -d "${project_path}/tests/step-definitions" ] ; then
+    printf 'webship-js' ; return 0 ;
+  fi
+  printf 'none';
+}
+
+# npm or yarn, decided by what the project actually carries rather than by preference: running
+# `npm run` in a yarn workspace re-resolves the tree and can leave it unbuildable.
+function testing_package_runner() {
+  local project_path="$1";
+  [ -f "${project_path}/yarn.lock" ] && { printf 'yarn' ; return 0 ; }
+  printf 'npm';
+}
+
+function testing_require_project() {
+  local project_path="$1";
+  if [ ! -d "${project_path}" ] ; then
+    echo "No project ${PROJECT_NAME} in ${WORKSPACE_ROOT}/${doc_name}.";
+    return 1 ;
+  fi
+  if [ ! -f "${project_path}/.ddev/config.yaml" ] ; then
+    echo "${doc_name}/${PROJECT_NAME} is not a DDEV project — the testing stack runs inside DDEV.";
+    return 1 ;
+  fi
+  return 0 ;
+}
+
+# Set the testing environment up on an existing project. Idempotent: the in-project command checks
+# what is installed before it installs anything, and the webship add-on preserves every file it
+# finds, so a second run adds what a first run missed rather than resetting the suite.
+function testing_configure() {
+  local project_path="${WORKSPACE_ROOT}/${doc_name}/${PROJECT_NAME}" stack runner;
+  testing_require_project "${project_path}" || return 1 ;
+  cd "${project_path}" || return 1 ;
+
+  stack="$(testing_stack "${project_path}")";
+  echo "";
+  echo "Setting up automated testing for ${doc_name}/${PROJECT_NAME}.";
+  echo "";
+
+  ddev start -y || return 1 ;
+
+  case "${stack}" in
+    in-project)
+      echo "This project ships its own DDEV testing command — using it.";
+      ddev init-full-automated-testing || return 1 ;
+      ;;
+    *)
+      # Also the path for `webship-js`: the add-on owns the scaffold, and re-getting it is how you
+      # pick up a newer version of it.
+      echo "Adding the webship-js DDEV add-on (Playwright + Cucumber-js).";
+      if ! ddev add-on get webship/ddev-webship-js ; then
+        # The add-on declares a minimum DDEV version, and the failure reads as an add-on error
+        # rather than as "your DDEV is too old", which is what it actually means.
+        echo "";
+        echo "  The add-on could not be installed. It requires a newer DDEV than this machine has:";
+        echo "    installed: $(ddev version 2>/dev/null | awk '$1 == "DDEV" && $2 == "version" {print $3}')";
+        echo "  Update DDEV (https://ddev.readthedocs.io/en/stable/users/install/ddev-upgrade/),";
+        echo "  then run this command again.";
+        return 1 ;
+      fi
+      # The add-on scaffolds on post-start, so the restart is part of the install, not a nicety.
+      ddev restart || return 1 ;
+      ;;
+  esac
+
+  runner="$(testing_package_runner "${project_path}")";
+  if [ -f "${project_path}/package.json" ] ; then
+    echo "";
+    echo "Installing the JS dependencies and the chromium browser.";
+    ddev ${runner} install || true ;
+    testing_write_browser_libs_build "${project_path}" ;
+    testing_ensure_browser_libs "${project_path}" || true ;
+    testing_install_browsers || true ;
+  fi
+
+  # A site under test should fail loudly and serve unaggregated assets: a CSS aggregate makes a
+  # failure screenshot unreadable, and a swallowed error is a scenario that fails for the wrong
+  # reason. Best-effort — a non-Drupal project simply has no drush.
+  if ddev drush status --field=bootstrap 2>/dev/null | grep -qi successful ; then
+    echo "";
+    echo "Tuning the site for testing (no aggregation, all errors visible).";
+    ddev drush config:set system.performance css.preprocess 0 --yes > /dev/null 2>&1 ;
+    ddev drush config:set system.performance js.preprocess 0 --yes > /dev/null 2>&1 ;
+    ddev drush config:set system.logging error_level all --yes > /dev/null 2>&1 ;
+    ddev drush cache:rebuild > /dev/null 2>&1 ;
+  fi
+
+  echo "";
+  echo "*---------------------------------------------------------------------*";
+  echo "  Testing is set up on ${doc_name}/${PROJECT_NAME} ($(testing_stack "${project_path}")).";
+  echo "";
+  echo "  Run it:      bash cmd-tools-testing.sh ${PROJECT_NAME} --run";
+  echo "  One feature: bash cmd-tools-testing.sh ${PROJECT_NAME} --run --path tests/features/<name>.feature";
+  echo "  By tag:      bash cmd-tools-testing.sh ${PROJECT_NAME} --run --tags @critical";
+  echo "";
+  echo "  The report lands in tests/reports/, and the dashboard's Tests menu reads it.";
+  echo "*---------------------------------------------------------------------*";
+}
+
+# Run the suite. Everything happens inside DDEV — the browsers are in the web container, and the
+# site under test is reachable there by its own name.
+function testing_run() {
+  local project_path="${WORKSPACE_ROOT}/${doc_name}/${PROJECT_NAME}" stack runner script started status;
+  testing_require_project "${project_path}" || return 1 ;
+  cd "${project_path}" || return 1 ;
+
+  stack="$(testing_stack "${project_path}")";
+  if [ "${stack}" == 'none' ] ; then
+    echo "${doc_name}/${PROJECT_NAME} has no testing stack yet.";
+    echo "  Set it up first: bash cmd-tools-testing.sh ${PROJECT_NAME} --configure";
+    return 1 ;
+  fi
+
+  # Start it only if it is not already up. `ddev start` on a running project RECREATES its
+  # containers whenever the project rewrites its own config on boot (the site-template projects do,
+  # for Storybook) — which throws away the container, occasionally trips the health wait, and used
+  # to take the freshly downloaded browsers with it. A running project is left alone.
+  if ddev describe -j 2>/dev/null | grep -q '"status":"running"' ; then
+    echo "${doc_name}/${PROJECT_NAME} is already running.";
+  else
+    ddev start -y || return 1 ;
+  fi
+
+  # A restart between setting up and running empties the container's own cache, so check before
+  # opening a browser rather than after 275 scenarios have failed for the same missing file. The
+  # libraries chromium links against are checked the same way and for the same reason.
+  testing_ensure_browser_libs "${project_path}" || return 1 ;
+  testing_install_browsers || return 1 ;
+  runner="$(testing_package_runner "${project_path}")";
+  started="$(date +%s)";
+
+  echo "";
+  echo "Running the ${BROWSER} suite of ${doc_name}/${PROJECT_NAME}.";
+  echo "";
+
+  # webship-js is cucumber-js driving Playwright, configured by the project's own cucumber.js.
+  # The package scripts are the contract — `test:chromium` is
+  #   BROWSER=chromium node ./node_modules/@cucumber/cucumber/bin/cucumber.js --config cucumber.js
+  # — so an unfiltered run calls the script rather than reimplementing it, and a filtered run
+  # reproduces exactly that command with the filter appended. The browser and headed-ness travel
+  # as the environment variables the config reads (BROWSER, HEADLESS), not as flags cucumber has
+  # no idea about.
+  local env_prefix="PLAYWRIGHT_BROWSERS_PATH=${TESTING_BROWSERS_PATH} BROWSER=${BROWSER}";
+  [ "${HEADED}" == 'yes' ] && env_prefix="${env_prefix} HEADLESS=false";
+  local cucumber="node ./node_modules/@cucumber/cucumber/bin/cucumber.js --config cucumber.js";
+  local filter="";
+  # Narrowing to one feature is an ENV var here, not a positional argument: these projects'
+  # cucumber.js sets `paths: [process.env.FEATURES || 'tests/features/**/*.feature']`, and a config
+  # `paths` wins over the path you type — passing it positionally silently ran all 275 scenarios.
+  # A directory is expanded to the glob cucumber expects, so `--path tests/features/02-user` works.
+  if [ ! "${TESTING_PATH}" == '_none_' ] ; then
+    local features="${TESTING_PATH}";
+    case "${features}" in
+      *.feature|*'*'*) : ;;
+      *) features="${features%/}/**/*.feature" ;;
+    esac
+    env_prefix="${env_prefix} FEATURES=\"${features}\"";
+    filter="${filter} ";
+  fi
+  [ ! "${TAGS}" == '_none_' ] && filter="${filter} --tags \"${TAGS}\"";
+  [ ! "${RETRY}" == '_none_' ] && filter="${filter} --retry ${RETRY}";
+  # --dry-run compiles the suite and matches every step against the definitions without opening a
+  # browser: seconds instead of the ~20 minutes a full suite takes, and it is what catches
+  # an undefined step or a broken tag expression before a real run does.
+  [ "${DRY_RUN}" == 'yes' ] && filter="${filter} --dry-run";
+
+  if [ -n "${filter}" ] ; then
+    echo "  ddev exec ${env_prefix} ${cucumber} ${filter}";
+    ddev exec "${env_prefix} ${cucumber} ${filter}" ;
+    status=$? ;
+  else
+    script="test:${BROWSER}";
+    echo "  ddev ${runner} run ${script}";
+    [ "${HEADED}" == 'yes' ] && script="test:headed";
+    ddev exec "${env_prefix} ${runner} run ${script}" ;
+    status=$? ;
+  fi
+
+  # The HTML report the dashboard reads is written by webship-js's own hook, unless the run
+  # disabled it (WEBSHIP_REPORT_DISABLE=1, which CI does). Regenerate it when the JSON is there
+  # and the HTML is not, so a run always leaves the artifact the Tests menu links to.
+  if [ -f tests/reports/cucumber_report.json ] && [ ! -f tests/reports/cucumber_report.html ] ; then
+    if grep -q '"generate-reports"' package.json 2>/dev/null ; then
+      echo "";
+      echo "Generating the HTML report.";
+      ddev ${runner} run generate-reports || true ;
+    fi
+  fi
+
+  echo "";
+  echo "*---------------------------------------------------------------------*";
+  if [ "${status}" -eq 0 ] ; then
+    echo "  The suite passed in $(( $(date +%s) - started ))s.";
+  else
+    # A failing suite is a result, not a tooling error — say so plainly and point at the evidence
+    # rather than burying it in a non-zero exit.
+    echo "  The suite FAILED (exit ${status}) after $(( $(date +%s) - started ))s.";
+    echo "  Every failed step leaves a screenshot and a DOM dump; each scenario leaves a recording.";
+  fi
+  echo "";
+  echo "  Report:      ${doc_name}/${PROJECT_NAME}/tests/reports/cucumber_report.html";
+  echo "  Screenshots: ${doc_name}/${PROJECT_NAME}/tests/screenshots/";
+  echo "  Recordings:  ${doc_name}/${PROJECT_NAME}/tests/videos/";
+  echo "  The dashboard's Tests menu shows all three, newest first.";
+  echo "*---------------------------------------------------------------------*";
+  return ${status} ;
+}
+
+function testing_command() {
+  # --configure is the default, so it is only meaningful as a word — except together with --run,
+  # where "set it up and then run it" is a real thing to ask for and used to lose the setup half.
+  if [ "${CONFIGURE}" == 'yes' ] || [ ! "${RUN}" == 'yes' ] ; then
+    testing_configure || return 1 ;
+  fi
+  if [ "${RUN}" == 'yes' ] ; then
+    testing_run ;
+  fi
+}

package/core/scripts/functions/fun-users.sh

@@ -0,0 +1,87 @@
+#!/usr/bin/env bash
+
+# Load the default user list of a distribution: `set_<distribution>_users` lives
+# in functions/fun-distribution-<distribution>.sh, next to that distribution's
+# install functions. Each cmd-*.sh sets distribution_name itself.
+function load_distribution_users () {
+  distribution_functions="${WORKSPACE_SCRIPTS}/functions/fun-distribution-${distribution_name}.sh" ;
+  if [ -f "${distribution_functions}" ]; then
+    source "${distribution_functions}" ;
+  fi
+
+  if declare -f set_${distribution_name}_users > /dev/null ; then
+    set_${distribution_name}_users ;
+  else
+    echo "No default user list for '${distribution_name}' — add set_${distribution_name}_users() to fun-distribution-${distribution_name}.sh." ;
+  fi
+
+  # Callers that only know the project (cmd-tools-add-users.sh) get the docroot
+  # from the project's own DDEV config.
+  if [ -z "${distribution_webroot}" ] && [ -f "${WORKSPACE_ROOT}/${doc_name}/${PROJECT_NAME}/.ddev/config.yaml" ]; then
+    distribution_webroot=$(grep '^docroot:' "${WORKSPACE_ROOT}/${doc_name}/${PROJECT_NAME}/.ddev/config.yaml" | awk '{print $2}') ;
+  fi
+}
+
+# Add users to a project.
+function add_users () {
+
+  # Add Drush if it was not in the system.
+  add_drush ;
+
+  load_distribution_users ;
+
+  cd ${WORKSPACE_ROOT}/${doc_name}/${PROJECT_NAME}/${distribution_webroot}/;
+
+  for user in ${users[@]}
+  do
+    user_name="user_${user}_name";
+    user_mail="user_${user}_mail";
+    user_password="user_${user}_password";
+    user_role="user_${user}_role";
+
+    echo " ---------------------------------------------------------------- ";
+    echo "      User name: ${!user_name}";
+    echo "      User mail: ${!user_mail}";
+    echo "  User password: ${!user_password}";
+    echo "      User role: ${!user_role}";
+    echo " ================================================================= ";
+
+    ddev drush user:create "${!user_name}" --mail="${!user_mail}" --password="${!user_password}" ;
+    if [ "${!user_role}" == '_none_' ] ; then
+      echo "   No user role for this user" ;
+    else
+      ddev drush user:role:add "${!user_role}" "${!user_name}" ;
+    fi
+  done
+
+  echo "Cache rebuilding ...";
+  ddev drush cache:rebuild ;
+
+  cd ${WORKSPACE_ROOT}/${doc_name};
+}
+
+# Cancle users from a project and delete their content.
+function cancel_users () {
+
+  # Add Drush if it was not in the system.
+  add_drush ;
+
+  load_distribution_users ;
+
+  cd ${WORKSPACE_ROOT}/${doc_name}/${PROJECT_NAME}/${distribution_webroot}/;
+
+  for user in ${users[@]}
+  do
+    user_name="user_${user}_name";
+
+    echo " ---------------------------------------------------------------- ";
+    echo "      User name: ${!user_name}";
+    echo " ================================================================= ";
+    ddev drush user:cancel --delete-content "${!user_name}" -y ;
+  done
+
+  echo "Cache rebuilding ...";
+  ddev drush cache:rebuild ;
+
+  cd ${WORKSPACE_ROOT}/${doc_name};
+}

package/core/scripts/functions/fun-version.sh

@@ -0,0 +1,72 @@
+#!/usr/bin/env bash
+
+################################################################################
+## What version of the Webship Workspace is this machine running?
+################################################################################
+## One answer, in one place, because three different things install this tree and
+## until now only ONE of them left a trace:
+##
+##   install.sh            a fresh machine          -> stamped nothing
+##   sync-tooling.sh --pull  a machine with the clone -> stamped nothing
+##   update.sh             a machine on releases    -> wrote .app-version
+##
+## So `update.sh --check` answered "Installed: (untracked)" and offered an update
+## on a tree that was already current, for ever, on every machine that had not been
+## updated by the updater. With one person that is a curiosity. Across a team it is
+## the support question — "what version are you on?" — that nobody can answer, and
+## an update prompt that everyone learns to ignore.
+##
+## The stamp is a plain file, core/workspace-app/.app-version, holding a tag and
+## nothing else. Not git: the live tree is not a checkout (`~/workspace` has no
+## .git), which is exactly why `git describe` cannot be the answer.
+################################################################################
+
+# Where the stamp lives. WORKSPACE_PATH is core/, set by bootstrap.sh.
+function workspace_version_file() {
+  echo "${WORKSPACE_PATH:-$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)}/workspace-app/.app-version"
+}
+
+# The version this tree reports, or an empty string. Never invents one: a wrong
+# version is worse than an absent one, because it stops the question being asked.
+function workspace_version() {
+  local f
+  f="$(workspace_version_file)"
+  [ -f "${f}" ] || return 0
+  head -1 "${f}" | tr -d '[:space:]'
+}
+
+# Record the version this tree is now at. Callers pass what they actually
+# installed; nobody guesses.
+function workspace_version_stamp() {
+  local version="${1:-}"
+  local f
+  [ -n "${version}" ] || return 1
+  f="$(workspace_version_file)"
+  mkdir -p "$(dirname "${f}")" 2>/dev/null
+  printf '%s\n' "${version}" > "${f}" || return 1
+  return 0
+}
+
+# The newest release tag, from the repository. Used when a caller knows it is
+# installing "whatever is current" rather than a named tag — a fresh install from
+# a downloaded ZIP, say. Empty when the network or gh is unavailable, and the
+# caller must treat that as "unknown", never as "up to date".
+function workspace_latest_tag() {
+  local repo="${1:-webship/workspace}" tag=''
+  if command -v gh > /dev/null 2>&1 ; then
+    tag="$(gh api "repos/${repo}/releases/latest" --jq .tag_name 2>/dev/null)"
+  fi
+  if [ -z "${tag}" ] && command -v curl > /dev/null 2>&1 ; then
+    tag="$(curl -fsSL --max-time 15 "https://api.github.com/repos/${repo}/releases/latest" 2>/dev/null \
+           | sed -n 's/.*"tag_name": *"\([^"]*\)".*/\1/p' | head -1)"
+  fi
+  echo "${tag}"
+}
+
+# The version of a git clone of this repository, for sync-tooling.sh --pull: there
+# the source IS a checkout, so the tag it is on is the honest answer.
+function workspace_clone_version() {
+  local clone="${1:-}"
+  [ -n "${clone}" ] && [ -d "${clone}/.git" ] || return 0
+  git -C "${clone}" describe --tags --abbrev=0 2>/dev/null
+}

package/core/scripts/functions/fun-video-edit.sh

@@ -0,0 +1,48 @@
+#!/usr/bin/env bash
+
+# Edit a video into a new version of itself. The work is in libs/video_edit.py; this hands it the ElevenLabs
+# settings, which only a section added with that voice uses.
+
+function video_edit_engine() {
+  ELEVENLABS_API_KEY="$(elevenlabs_key)" ELEVENLABS_API_BASE="$(elevenlabs_base)" \
+    ELEVENLABS_MODEL="$(elevenlabs_model)" ELEVENLABS_VOICE="$(elevenlabs_voice)" \
+    python3 "${WORKSPACE_SCRIPTS}/libs/video_edit.py" "$@" ;
+}
+
+function video_edit_usage() {
+  cat <<'USAGE'
+usage: cmd-tools-video-edit.sh -a ACTION --video V.mp4 [options]
+
+  -a info                                     size, frame rate and length
+  -a edit --out NEW.mp4 [changes]             a new version with the changes; the original is never touched
+
+changes (any number together):
+  --speed 0.25-4          play faster or slower          --length 1:30   make it exactly that long
+  --trim 0:05-0:40        keep only that stretch         --remove T03,T05  cut sections of the script out
+  --add-title T --add-text "..." --add-after T03|start|end [--engine piper|elevenlabs --voice ID]
+                          a new section: a Webship logo card, spoken by the voice
+  --intro-card 3 [--intro-title T --intro-subtitle S]    the Webship logo before the video (1-10 seconds)
+  --outro-card 3 [--outro-title T --outro-subtitle S]    the Webship logo after it
+  --intro-music F --outro-music F [--intro-seconds 8 --outro-seconds 8 --music-volume 0.5]
+  --clone                 a plain copy to re-work (what a new version starts as)
+  --script S.md [--script-out O.md]   the timed voiceover script; it is rewritten for the new version
+
+An existing output is refused unless --force. Only a section spoken with ElevenLabs spends credits: it prints
+a plan and stops unless --confirm is given. Exit codes: 0 ok, 1 error, 2 usage, 3 no key, 4 plan only.
+USAGE
+}
+
+function video_edit_main() {
+  local action='edit';
+  while [ $# -gt 0 ] ; do
+    case "$1" in
+      -h|--help) video_edit_usage ; return 0 ;;
+      -a|--action) action="$2"; shift 2 || { video_edit_usage >&2 ; return 2 ; } ;;
+      *) break ;;
+    esac
+  done
+  case "${action}" in
+    info|edit) video_edit_engine "${action}" "$@" ;;
+    *) echo "Unknown action: ${action}" >&2 ; video_edit_usage >&2 ; return 2 ;;
+  esac
+}

package/core/scripts/functions/fun-voice.sh

@@ -0,0 +1,45 @@
+#!/usr/bin/env bash
+
+# Voices for the audio workspace: Piper (voice-narration) and ElevenLabs, one text spoken to one file.
+# The engine and its arguments are in libs/voice.py; this only hands it the ElevenLabs settings.
+
+function voice_engine() {
+  ELEVENLABS_API_KEY="$(elevenlabs_key)" ELEVENLABS_API_BASE="$(elevenlabs_base)" \
+    ELEVENLABS_MODEL="$(elevenlabs_model)" ELEVENLABS_VOICE="$(elevenlabs_voice)" \
+    python3 "${WORKSPACE_SCRIPTS}/libs/voice.py" "$@" ;
+}
+
+function voice_usage() {
+  cat <<'USAGE'
+usage: cmd-tools-voice.sh -a ACTION [options]
+
+  -a engines [--json]                         which engines this machine can use, and why not
+  -a voices --engine piper|elevenlabs         the voices of one engine [--search WORD] [--limit N]
+  -a speak --engine piper|elevenlabs --text-file F --out F.wav|F.mp3 [--voice ID] [--model ID]
+  -a voiceover --engine piper|elevenlabs --script S.md --video V.mp4 --out O.mp4 --voice ID [--model ID] [--drop-optional]
+                                              a timed voiceover script, or any transcript, spoken over a video
+  -a sound --text-file F --out F.mp3 [--duration 0.5-30] [--loop] [--influence 0-1]   (ElevenLabs)
+                                              a sound effect from a description
+  -a music --text-file F --out F.mp3 [--length 3-600] [--instrumental]                 (ElevenLabs)
+                                              music from a description
+
+Piper is free and local. ElevenLabs spends credits, so speak, voiceover, sound and music print a plan and stop
+unless --confirm is given. An existing output is refused unless --force. Add --json for machine-readable output.
+Exit codes: 0 ok, 1 error, 2 usage, 3 no key, 4 plan only.
+USAGE
+}
+
+function voice_main() {
+  local action='engines';
+  while [ $# -gt 0 ] ; do
+    case "$1" in
+      -h|--help) voice_usage ; return 0 ;;
+      -a|--action) action="$2"; shift 2 || { voice_usage >&2 ; return 2 ; } ;;
+      *) break ;;
+    esac
+  done
+  case "${action}" in
+    engines|voices|speak|voiceover|sound|music) voice_engine "${action}" "$@" ;;
+    *) echo "Unknown action: ${action}" >&2 ; voice_usage >&2 ; return 2 ;;
+  esac
+}

package/core/scripts/functions/fun-wordpress.sh

@@ -0,0 +1,59 @@
+#!/usr/bin/env bash
+
+# WordPress on DDEV: an example of a non-Drupal builder.
+#
+# Two shapes, picked by the builder:
+#   wordpress_shape="core"     WordPress itself, downloaded with wp-cli, docroot at the project root.
+#   wordpress_shape="bedrock"  roots/bedrock, WordPress managed by Composer, docroot web/.
+#
+# DDEV writes wp-config-ddev.php for the database, so nothing here writes database settings.
+
+function build_wordpress() {
+  local base_url="https://${PROJECT_NAME}.ddev.site" ;
+  local docroot="" ;
+  [ "${wordpress_shape}" == 'bedrock' ] && docroot="web" ;
+
+  cd ${WORKSPACE_ROOT}/${doc_name} || exit 1 ;
+
+  drop_database ;
+  rm -rf "${PROJECT_NAME}" ;
+  mkdir -p "${PROJECT_NAME}" ;
+  cd ${WORKSPACE_ROOT}/${doc_name}/${PROJECT_NAME} || exit 1 ;
+
+  local php_version="${PHP_VERSION:-${site_php_version:-}}" ;
+  ddev config --project-type=wordpress --docroot="${docroot}" --project-name=${PROJECT_NAME} \
+    ${php_version:+--php-version=${php_version}} --auto || exit 1 ;
+  ddev_up start -y || exit 1 ;
+
+  if [ "${wordpress_shape}" == 'bedrock' ] ; then
+    ddev composer create-project "roots/bedrock:${site_version}" --no-interaction || { echo "composer create-project failed." ; exit 1 ; } ;
+    # Bedrock reads its settings from .env; DDEV's database is always db/db/db.
+    {
+      echo "DB_NAME='db'" ; echo "DB_USER='db'" ; echo "DB_PASSWORD='db'" ; echo "DB_HOST='db'" ;
+      echo "WP_ENV='development'" ; echo "WP_HOME='${base_url}'" ; echo 'WP_SITEURL="${WP_HOME}/wp"' ;
+      local key ;
+      for key in AUTH_KEY SECURE_AUTH_KEY LOGGED_IN_KEY NONCE_KEY AUTH_SALT SECURE_AUTH_SALT LOGGED_IN_SALT NONCE_SALT ; do
+        echo "${key}='$(head -c 32 /dev/urandom | od -An -tx1 | tr -d ' \n')'" ;
+      done
+    } > .env ;
+  else
+    ddev wp core download --version="${site_version}" || { echo "wp core download failed." ; exit 1 ; } ;
+  fi
+
+  if [ "${INSTALL}" == 'yes' ] ; then
+    ddev wp core install --url="${base_url}" --title="${doc_name} ${PROJECT_NAME}" \
+      --admin_user="${account_name}" --admin_password="${account_pass}" --admin_email="${account_mail}" \
+      --skip-email || { echo "wp core install failed." ; exit 1 ; } ;
+    echo "${doc_name} ${PROJECT_NAME} has been installed!!!!";
+    echo "Go to ${base_url}/wp-admin and log in as ${account_name}";
+  else
+    echo "${doc_name} ${PROJECT_NAME} is ready to install!!!!";
+    echo "Go to ${base_url}";
+  fi
+
+  if [ "${LAUNCH}" == 'yes' ] ; then
+    ddev launch ;
+  fi
+
+  cd ${WORKSPACE_ROOT}/${doc_name};
+}