@webship.co/workspace 1.0.0-beta1 → 1.0.0-rc1

package/core/scripts/args/arg-website.sh

@@ -0,0 +1,25 @@
+#!/usr/bin/env bash
+
+# The Website project template (drupal/website) is installed by the Webship
+# installer, which offers the three Webship site templates. Pick one.
+
+argparse "$@" <<EOF || exit 1
+parser.add_argument('PROJECT_NAME',
+                    help='The name of the project. It becomes https://<PROJECT_NAME>.ddev.site')
+parser.add_argument('-t', '--template',
+                    default="website_starter",
+                    choices=['website_starter', 'webship_starter', 'webship_portal'],
+                    help='The site template the Webship installer installs [default %(default)s].')
+parser.add_argument('-a', '--add-users',
+                    action='store_true',
+                    default=False,
+                    help='Add the default set of users after the install.')
+parser.add_argument('-f', '--with-pending-fixes',
+                    action='store_true',
+                    default=False,
+                    help='Pin the web* issue-fork branches that are not merged yet (webblog MR !4, webreleases MR !5).')
+parser.add_argument('-p', '--php-version',
+                    default="",
+                    choices=['8.5', '8.4', '8.3', '8.2', '8.1', '8.0', '7.4'],
+                    help='PHP version for the project container. The seven most recent PHP releases DDEV supports; empty means the builder default. Example: --php-version 8.3')
+EOF

package/core/scripts/args/arg-wordpress.sh

@@ -0,0 +1,18 @@
+#!/usr/bin/env bash
+
+argparse "$@" <<ARGEOF || exit 1
+parser.add_argument('PROJECT_NAME',
+                    help='The name of the project.')
+parser.add_argument('-i', '--install',
+                    action='store_true',
+                    default=False,
+                    help='Install WordPress, with the workspace account as the administrator.')
+parser.add_argument('-l', '--launch',
+                    action='store_true',
+                    default=False,
+                    help='Open the site in a browser when it is ready.')
+parser.add_argument('--php-version',
+                    default="",
+                    choices=['8.5', '8.4', '8.3', '8.2', '8.1'],
+                    help='PHP version for the project container; empty means DDEV\'s default. Example: --php-version 8.3')
+ARGEOF

package/core/scripts/autostart-run.sh

@@ -0,0 +1,162 @@
+#!/usr/bin/env bash
+
+# What the boot service runs. Kept as its own file, not inlined into the unit, so that what runs at
+# boot is the same thing you can run by hand and read the output of — `core/scripts/autostart.sh --now`
+# calls exactly this.
+#
+# The whole job is: wait until Docker will actually answer, then `ddev start` the configured projects.
+# The waiting is the part that matters. At boot this races dockerd, and `ddev start` against a socket
+# that is not listening yet fails in a way that leaves the project half-configured — so it polls
+# rather than assuming, and gives up loudly instead of silently doing nothing.
+
+# No `set -u`: bootstrap.sh and libs/bash-yaml.sh both read variables that are legitimately unset
+# (WORKSPACE_REPO, parse_yaml's optional prefix), so it aborts the chain before Docker is even
+# checked. Nothing else in this tree sets it either.
+
+WORKSPACE_SCRIPTS="${WORKSPACE_SCRIPTS:-$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)}";
+source "${WORKSPACE_SCRIPTS}/bootstrap.sh" || exit 1 ;
+
+eval $(parse_yaml "${WORKSPACE_CONFIG}/settings.yml" 2>/dev/null);
+
+log() { printf '%s  %s\n' "$(date '+%Y-%m-%d %H:%M:%S')" "$1" ; }
+
+# WHICH PROJECTS, and why this is not just a list of names.
+#
+# A hand-maintained list is wrong within a week: you build a project, you never think about this file
+# again, and after the next reboot it is not there. So the setting takes a small vocabulary as well as
+# literal names:
+#
+#   workspace   just the dashboard. The default, and usually the right answer — it boots in seconds
+#               and you can start anything else from it with one click.
+#   running     whatever was running when the machine last shut down cleanly. This is what people
+#               actually mean by "bring my work back", and it needs no maintenance.
+#   all         every project DDEV has registered. Honest about the cost: 11 projects here is 11×
+#               (web + db) containers competing for RAM and disk at boot.
+#   a,b,c       exactly these, in this order.
+#
+# The dashboard is ALWAYS first and always included, whatever the setting says. It is the way in to
+# everything else, so a boot that brings back four sites and no dashboard is a worse outcome than one
+# that brings back only the dashboard.
+readonly STATE_FILE="${WORKSPACE_PATH}/state/autostart-was-running";
+
+function resolve_projects() {
+  local setting="${dashboard_autostart:-workspace}" resolved="";
+
+  case "${setting}" in
+    all)
+      resolved="$(ddev list --json-output 2>/dev/null | jq -r '.raw[]?.name // empty' 2>/dev/null | paste -sd, -)";
+      ;;
+    running)
+      # Recorded by the service's ExecStop on a clean shutdown. A hard poweroff never runs ExecStop,
+      # so the file may be stale or missing — the dashboard-only fallback below covers that rather
+      # than the boot failing over a missing file.
+      [ -f "${STATE_FILE}" ] && resolved="$(cat "${STATE_FILE}" 2>/dev/null)";
+      [ -z "${resolved}" ] && log "no record of what was running (hard poweroff?) — starting the dashboard only" ;
+      ;;
+    *)
+      resolved="${setting}";
+      ;;
+  esac
+
+  # Dashboard first, then the rest, no duplicates and order preserved.
+  printf 'workspace\n%s\n' "$(printf '%s' "${resolved}" | tr ',' '\n')" \
+    | sed 's/^[[:space:]]*//; s/[[:space:]]*$//' | sed '/^$/d' | awk '!seen[$0]++';
+}
+
+# `--list` prints what WOULD start and exits. The status display calls this rather than re-deriving
+# the list, so the two can never disagree about what a reboot will bring back — the same reason the
+# checks command asks checks_plan.js instead of keeping its own copy of the map.
+if [ "${1:-}" == '--list' ] ; then
+  resolve_projects ;
+  exit 0 ;
+fi
+
+# Docker, before anything else. 24 × 5s = two minutes, which covers a cold boot on a slow disk
+# without hanging the unit for the full 900s timeout when Docker is genuinely broken.
+attempt=0 ;
+until docker info > /dev/null 2>&1 ; do
+  attempt=$(( attempt + 1 )) ;
+  if [ "${attempt}" -ge 24 ] ; then
+    log "Docker did not become available after 2 minutes. Nothing was started." ;
+    exit 1 ;
+  fi
+  log "waiting for Docker… (${attempt}/24)" ;
+  sleep 5 ;
+done
+log "Docker is up." ;
+
+# DDEV's own shared infrastructure, before any project. `ddev-router` and `ddev-ssh-agent` are not
+# projects — every project depends on them, but nothing owns starting them back up.
+#
+# This is the actual bug behind "ddev start did not work" and the boot service silently not
+# starting the dashboard: a laptop suspend/reboot leaves these containers `exited` (Docker gives
+# them no restart policy, same as every project container), and an EXITED container has no live
+# network attachment, so Docker's own DNS has nothing to resolve `ddev-router` to. The web
+# container's nginx fails at startup with "host not found in upstream ddev-router", supervisord
+# gives up after three quick retries, and the WHOLE container exits — cleanly, exit code 0, which
+# is why this reads as nothing having failed while nothing comes up either.
+#
+# `ddev start` does not reliably fix this on its own: it recreates the PROJECT's containers and
+# leaves the router exactly as it found it. Confirmed by hand — starting the router first, then
+# `ddev start`, works in one try; `ddev start` alone against a dead router does not, however many
+# times it is retried.
+for infra in ddev-router ddev-ssh-agent ; do
+  # Absent entirely is fine — a machine that has never run a project has neither yet, and `ddev
+  # start` creates what it needs. Only an EXISTING, stopped container is the failure to repair.
+  state="$(docker inspect "${infra}" --format '{{.State.Status}}' 2>/dev/null)" ;
+  if [ -n "${state}" ] && [ "${state}" != 'running' ] ; then
+    log "${infra} is ${state}, not running — starting it before any project." ;
+    docker start "${infra}" > /dev/null 2>&1 ;
+    # Give it a moment to attach to the network and pass its own health check before the project
+    # that depends on it starts racing it. Not a hard wait: if it is still not running after this,
+    # the project start below will fail loudly and say why, rather than hanging silently on it.
+    for _ in 1 2 3 4 5 6 ; do
+      [ "$(docker inspect "${infra}" --format '{{.State.Status}}' 2>/dev/null)" == 'running' ] && break ;
+      sleep 2 ;
+    done
+  fi
+done
+
+projects="$(resolve_projects | paste -sd' ' -)";
+log "starting: ${projects}" ;
+
+status=0 ;
+for project in ${projects} ; do
+  case "${project}" in
+    workspace) project_path="${WORKSPACE_PATH}/workspace-app" ;;
+    *)         project_path="$(ddev list --json-output 2>/dev/null \
+                   | jq -r --arg n "${project}" '.raw[]? | select(.name==$n) | .approot' 2>/dev/null | head -1)" ;;
+  esac
+
+  if [ -z "${project_path}" ] || [ ! -d "${project_path}/.ddev" ] ; then
+    log "skipping ${project}: no DDEV project found for it." ;
+    continue ;
+  fi
+
+  log "starting ${project} (${project_path})…" ;
+  if ( cd "${project_path}" && ddev start -y ) ; then
+    log "started ${project}." ;
+  else
+    log "FAILED to start ${project}." ;
+    status=1 ;
+  fi
+done
+
+# The screen runner belongs to the same "the machine came back" job. Sessions run on the
+# HOST — that is the whole point of them, so `screen -r` works in your own terminal and a
+# browser an agent drives opens on your desktop — and the dashboard runs in a container,
+# which cannot start a host process. So without this, every Screens page action and every
+# item-sync button answers "its runner is not up" until somebody runs one command, on a
+# machine that otherwise looks fully set up.
+screen_host="${WORKSPACE_PATH}/workspace-app/scripts/screen-host.sh";
+if [ -f "${screen_host}" ] ; then
+  if bash "${screen_host}" --status 2>/dev/null | grep -q '^Running' ; then
+    log "screen runner already up." ;
+  elif bash "${screen_host}" --start > /dev/null 2>&1 ; then
+    log "started the screen runner." ;
+  else
+    log "could not start the screen runner — the Screens page will say so." ;
+  fi
+fi
+
+exit "${status}" ;

package/core/scripts/autostart-stop.sh

@@ -0,0 +1,30 @@
+#!/usr/bin/env bash
+
+# Record which projects were running, so `autostart: running` has something to restore.
+#
+# Run as the service's ExecStop, which systemd calls on a clean shutdown or reboot. A hard poweroff
+# never runs it, so the file can be stale or absent — the boot side treats that as "dashboard only"
+# rather than failing, because a boot that starts nothing is worse than a boot that starts one thing.
+#
+# It records rather than acts: nothing here stops a project. `ddev poweroff` on shutdown would be
+# tidier in theory and is wrong in practice — Docker is already going down around it, and a half-
+# stopped project is how a database volume gets corrupted.
+
+WORKSPACE_SCRIPTS="${WORKSPACE_SCRIPTS:-$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)}";
+source "${WORKSPACE_SCRIPTS}/bootstrap.sh" || exit 0 ;
+
+STATE_DIR="${WORKSPACE_PATH}/state";
+STATE_FILE="${STATE_DIR}/autostart-was-running";
+
+mkdir -p "${STATE_DIR}" 2>/dev/null ;
+
+running="$(ddev list --json-output 2>/dev/null \
+  | jq -r '.raw[]? | select(.status=="running") | .name' 2>/dev/null | paste -sd, -)";
+
+# Only overwrite when the answer is believable. If Docker is already gone the query returns nothing,
+# and writing that empty result would erase a perfectly good record from the previous shutdown.
+if [ -n "${running}" ] ; then
+  printf '%s\n' "${running}" > "${STATE_FILE}" ;
+fi
+
+exit 0 ;

package/core/scripts/autostart-watch.sh

@@ -0,0 +1,43 @@
+#!/usr/bin/env bash
+
+# Runs every couple of minutes from webship-workspace-watch.timer.
+#
+# The boot service starts the dashboard once. When Docker itself restarts afterwards (an update, a crash,
+# somebody running `systemctl restart docker`), every DDEV container stops and nothing starts them again,
+# so every workspace URL answers 404 until a person notices. This notices: it remembers when Docker last
+# started, and when that moment has changed it runs the same script the boot service runs, once.
+#
+# It never starts anything just because the dashboard is not running. A dashboard stopped on purpose
+# stays stopped; only "Docker came back since I last looked" restores it.
+#
+# Overrides, for tests: AUTOSTART_WATCH_STATE (the stamp file), AUTOSTART_WATCH_DOCKER_STAMP (the value
+# systemd would report) and AUTOSTART_WATCH_RUN (what to run instead of autostart-run.sh).
+
+WORKSPACE_SCRIPTS="${WORKSPACE_SCRIPTS:-$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)}"
+STATE="${AUTOSTART_WATCH_STATE:-${XDG_STATE_HOME:-${HOME}/.local/state}/webship-workspace/docker-started}"
+RUN="${AUTOSTART_WATCH_RUN:-bash ${WORKSPACE_SCRIPTS}/autostart-run.sh}"
+
+log() { printf '%s  %s\n' "$(date '+%Y-%m-%d %H:%M:%S')" "$1" ; }
+
+if [ -n "${AUTOSTART_WATCH_DOCKER_STAMP+x}" ] ; then
+  current="${AUTOSTART_WATCH_DOCKER_STAMP}"
+else
+  [ "$(systemctl is-active docker 2>/dev/null)" = "active" ] || exit 0
+  current="$(systemctl show docker --property=ActiveEnterTimestamp --value 2>/dev/null)"
+fi
+[ -n "${current}" ] || exit 0
+
+mkdir -p "$(dirname "${STATE}")"
+previous="$(cat "${STATE}" 2>/dev/null)"
+
+if [ -z "${previous}" ] ; then
+  printf '%s\n' "${current}" > "${STATE}"
+  log "first look: Docker started ${current}; nothing to do"
+  exit 0
+fi
+[ "${current}" = "${previous}" ] && exit 0
+
+# Record it BEFORE running, so a start that fails is not retried every two minutes.
+printf '%s\n' "${current}" > "${STATE}"
+log "Docker restarted (${previous} -> ${current}); starting the dashboard again"
+bash -c "${RUN}"

package/core/scripts/autostart.sh

@@ -0,0 +1,26 @@
+#!/usr/bin/env bash
+
+# The dashboard's own hostnames, and getting it back after a reboot.
+#
+# A DDEV project's containers carry `restart: no`, so nothing brings the dashboard back when the
+# machine boots — every workspace URL then answers 404 from a router with nothing behind it. This
+# installs a systemd USER service that runs `ddev start` for the configured projects at boot, and
+# manages `hub_domain` — the one field every dashboard URL and DDEV's own routing are built from.
+#
+# Machine setup rather than per-project work, which is why it lives in core/scripts beside
+# sync-tooling.sh and install.sh: it is run once when a machine is set up, takes no project name, and
+# configures the box rather than acting on a project.
+
+# Bootstrap.
+# Find the workspace tooling from this script, so a fresh clone needs no setup.
+WORKSPACE_SCRIPTS="${WORKSPACE_SCRIPTS:-$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)}";
+source ${WORKSPACE_SCRIPTS}/bootstrap.sh || exit 1 ;
+
+eval $(parse_yaml ${WORKSPACE_CONFIG}/settings.yml);
+
+ARGPARSE_DESCRIPTION="Bring the dashboard back after a reboot, and set the domain everything is built from"
+source ${WORKSPACE_SCRIPTS}/args/arg-autostart.sh || exit 1 ;
+
+shift $#;
+
+autostart_command ;

package/core/scripts/bootstrap-functions.sh

@@ -0,0 +1,117 @@
+#!/usr/bin/env bash
+
+# Include users functions.
+source ${WORKSPACE_SCRIPTS}/functions/fun-users.sh || exit 1 ;
+
+# Include Default settings functions.
+source ${WORKSPACE_SCRIPTS}/functions/fun-default-settings.sh || exit 1 ;
+
+# Include Database functions.
+source ${WORKSPACE_SCRIPTS}/functions/fun-database.sh || exit 1 ;
+source ${WORKSPACE_SCRIPTS}/functions/fun-ddev-telemetry.sh || exit 1 ;
+source ${WORKSPACE_SCRIPTS}/functions/fun-ddev-nodejs.sh || exit 1 ;
+
+# Include Files functions.
+source ${WORKSPACE_SCRIPTS}/functions/fun-files.sh || exit 1 ;
+
+# Include backup functions.
+source ${WORKSPACE_SCRIPTS}/functions/fun-backup-item.sh || exit 1 ;
+
+# Include clone-project functions.
+source ${WORKSPACE_SCRIPTS}/functions/fun-clone-project.sh || exit 1 ;
+source ${WORKSPACE_SCRIPTS}/functions/fun-git-worktrees.sh || exit 1 ;
+source ${WORKSPACE_SCRIPTS}/functions/fun-ddev-hostnames.sh || exit 1 ;
+source ${WORKSPACE_SCRIPTS}/functions/fun-hostnames-cli.sh || exit 1 ;
+
+# Include screen-session functions.
+source ${WORKSPACE_SCRIPTS}/functions/fun-screen.sh || exit 1 ;
+
+# Include project removal functions.
+source ${WORKSPACE_SCRIPTS}/functions/fun-remove-project.sh || exit 1 ;
+
+# Include drush functions.
+source ${WORKSPACE_SCRIPTS}/functions/fun-drush.sh || exit 1 ;
+
+# Include distribution functions.
+source ${WORKSPACE_SCRIPTS}/functions/fun-build-distribution.sh || exit 1 ;
+
+# Include site template functions.
+source ${WORKSPACE_SCRIPTS}/functions/fun-build-site-template.sh || exit 1 ;
+
+# Include the Website stack and the Webships API build families.
+source ${WORKSPACE_SCRIPTS}/functions/fun-build-website.sh || exit 1 ;
+source ${WORKSPACE_SCRIPTS}/functions/fun-build-webships.sh || exit 1 ;
+
+# Include Obsidian (reading a project's graph as a vault) functions.
+
+
+# Include AI provider key functions.
+source ${WORKSPACE_SCRIPTS}/functions/fun-ai-providers.sh || exit 1 ;
+
+# Include GitLab CI (gitlab-ci-local green-gate) functions.
+source ${WORKSPACE_SCRIPTS}/functions/fun-gitlab-ci.sh || exit 1 ;
+
+# Include AI item (agents/skills/prompts) functions.
+source ${WORKSPACE_SCRIPTS}/functions/fun-ai-items.sh || exit 1 ;
+source ${WORKSPACE_SCRIPTS}/functions/fun-ai-items-lock.sh || exit 1 ;
+source ${WORKSPACE_SCRIPTS}/functions/fun-ai-items-sources.sh || exit 1 ;
+
+# Include workspace command management functions.
+source ${WORKSPACE_SCRIPTS}/functions/fun-commands.sh || exit 1 ;
+
+# Include Penpot (self-hosted design platform in DDEV) functions.
+source ${WORKSPACE_SCRIPTS}/functions/fun-penpot.sh || exit 1 ;
+source ${WORKSPACE_SCRIPTS}/functions/fun-wordpress.sh || exit 1 ;
+source ${WORKSPACE_SCRIPTS}/functions/fun-odoo.sh || exit 1 ;
+source ${WORKSPACE_SCRIPTS}/functions/fun-avatar.sh || exit 1 ;
+
+
+# Include Milvus (self-hosted vector database in DDEV) functions.
+source ${WORKSPACE_SCRIPTS}/functions/fun-milvus.sh || exit 1 ;
+
+# Include RAG index build (ragify) functions.
+source ${WORKSPACE_SCRIPTS}/functions/fun-ragify.sh || exit 1 ;
+
+# Include rag workspace (the index store and its MCP wiring) functions.
+source ${WORKSPACE_SCRIPTS}/functions/fun-rag.sh || exit 1 ;
+
+# Include Google Drive (push a workspace folder to a Drive folder, and its MCP server) functions.
+
+# Include automated-testing (set up and run a project's suite) functions.
+source ${WORKSPACE_SCRIPTS}/functions/fun-testing.sh || exit 1 ;
+
+# The code-quality checks a package already declares (cmd-tools-checks.sh).
+source ${WORKSPACE_SCRIPTS}/functions/fun-checks.sh || exit 1 ;
+
+# Reclaiming the disk that removed projects left behind (cmd-tools-reclaim.sh).
+source ${WORKSPACE_SCRIPTS}/functions/fun-reclaim.sh || exit 1 ;
+
+# The dashboard's hostnames and its boot service (core/scripts/autostart.sh).
+source ${WORKSPACE_SCRIPTS}/functions/fun-autostart.sh || exit 1 ;
+
+# ElevenLabs, for the final voiceover of a narrated video (videos/cmd-tools-elevenlabs.sh).
+source ${WORKSPACE_SCRIPTS}/functions/fun-elevenlabs.sh || exit 1 ;
+
+# Voices for the audio workspace: Piper and ElevenLabs (audio/cmd-tools-voice.sh).
+source ${WORKSPACE_SCRIPTS}/functions/fun-voice.sh || exit 1 ;
+source ${WORKSPACE_SCRIPTS}/functions/fun-video-edit.sh || exit 1 ;
+
+# Include SPDD (structured-prompt-driven design artifacts) functions.
+source ${WORKSPACE_SCRIPTS}/functions/fun-spdd.sh || exit 1 ;
+source ${WORKSPACE_SCRIPTS}/functions/fun-specs-share.sh || exit 1 ;
+
+# trim_project_name — the one place PROJECT_NAME gets a trailing slash trimmed, called from every
+# cmd-*.sh that takes one.
+source ${WORKSPACE_SCRIPTS}/functions/fun-project-name.sh || exit 1 ;
+source ${WORKSPACE_SCRIPTS}/functions/fun-version.sh || exit 1 ;
+source ${WORKSPACE_SCRIPTS}/functions/fun-release.sh || exit 1 ;
+
+# Workspace folders kept on a second disk (core/scripts/storage.sh).
+source ${WORKSPACE_SCRIPTS}/functions/fun-storage.sh || exit 1 ;
+
+# The functions installed plugins ship (core/scripts/plugins.sh --install <name> puts them in
+# core/scripts/plugins/<name>/functions/). Sourced last, so a plugin can build on everything above.
+for plugin_functions_file in "${WORKSPACE_SCRIPTS}"/plugins/*/functions/*.sh ; do
+  [ -f "${plugin_functions_file}" ] || continue ;
+  source "${plugin_functions_file}" || exit 1 ;
+done

package/core/scripts/bootstrap-libraries.sh

@@ -0,0 +1,10 @@
+#!/usr/bin/env bash
+
+# Include Bash YAML library.
+source ${WORKSPACE_SCRIPTS}/libs/bash-yaml.sh || exit 1 ;
+
+# Include the arguments parser
+source ${WORKSPACE_SCRIPTS}/libs/argparse.sh || exit 1 ;
+
+# Include Bash Progress Bar library.
+source ${WORKSPACE_SCRIPTS}/libs/progress-bar.sh || exit 1 ;

package/core/scripts/bootstrap.sh

@@ -0,0 +1,71 @@
+#!/usr/bin/env bash
+
+current_path=$(pwd);
+user_name="$USER";
+
+# Where this tooling comes from, and where a proposed change is filed. Captured HERE, before
+# settings.yml is parsed: parse_yaml would overwrite an exported override with the file's value,
+# and an export is meant to win for a one-off run.
+_env_workspace_repo="${WORKSPACE_REPO}";
+_env_workspace_repo_ref="${WORKSPACE_REPO_REF}";
+_env_ai_items_repo="${AI_ITEMS_REPO}";
+_env_ai_items_ref="${AI_ITEMS_REF}";
+
+# These were WEBSHIP_WORKSPACE_* until the rename. Anyone still exporting the old names meant them
+# as an override, so honour them rather than silently ignoring the override and picking the
+# checkout instead.
+WORKSPACE_ROOT="${WORKSPACE_ROOT:-${WEBSHIP_WORKSPACE_ROOT}}";
+WORKSPACE_PATH="${WORKSPACE_PATH:-${WEBSHIP_WORKSPACE_PATH}}";
+WORKSPACE_SCRIPTS="${WORKSPACE_SCRIPTS:-${WEBSHIP_WORKSPACE_SCRIPTS}}";
+WORKSPACE_CONFIG="${WORKSPACE_CONFIG:-${WEBSHIP_WORKSPACE_CONFIG}}";
+
+# Locate the workspace from this file, so a fresh clone works with no setup:
+# core/scripts/bootstrap.sh -> core/scripts -> core -> the workspace root.
+# Exported WORKSPACE_* variables still win, for a workspace kept
+# somewhere other than the checkout that is running.
+WORKSPACE_SCRIPTS="${WORKSPACE_SCRIPTS:-$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)}";
+WORKSPACE_PATH="${WORKSPACE_PATH:-$(dirname "${WORKSPACE_SCRIPTS}")}";
+WORKSPACE_ROOT="${WORKSPACE_ROOT:-$(dirname "${WORKSPACE_PATH}")}";
+WORKSPACE_CONFIG="${WORKSPACE_CONFIG:-${WORKSPACE_PATH}/config}";
+export WORKSPACE_ROOT WORKSPACE_PATH WORKSPACE_SCRIPTS WORKSPACE_CONFIG ;
+
+# Include Bootstrap libraries.
+source ${WORKSPACE_SCRIPTS}/bootstrap-libraries.sh || exit 1 ;
+
+# Include Bootstrap functions.
+source ${WORKSPACE_SCRIPTS}/bootstrap-functions.sh || exit 1 ;
+
+# Load settings.
+eval $(parse_yaml ${WORKSPACE_CONFIG}/settings.yml);
+
+# The settings files installed plugins own (core/config/plugin.<name>.settings.yml), as
+# plugin_<name>_<key> variables, so a plugin's bash hooks read the same values the dashboard does.
+for plugin_settings_file in "${WORKSPACE_CONFIG}"/plugin.*.settings.yml ; do
+  [ -f "${plugin_settings_file}" ] || continue ;
+  plugin_settings_name="$(basename "${plugin_settings_file}" .settings.yml)";
+  plugin_settings_name="${plugin_settings_name#plugin.}";
+  eval $(parse_yaml "${plugin_settings_file}" "plugin_${plugin_settings_name//-/_}_");
+done
+unset plugin_settings_file plugin_settings_name ;
+
+# settings.yml carries no paths: they follow the checkout, for whoever is running
+# it. Set root/path/scripts/config/backups there only to override that.
+root="${root:-${WORKSPACE_ROOT}}";
+path="${path:-${WORKSPACE_PATH}}";
+scripts="${scripts:-${WORKSPACE_SCRIPTS}}";
+config="${config:-${WORKSPACE_CONFIG}}";
+backups="${backups:-${root}/backups}";
+
+# The tooling repository, from sources.tooling in settings.yml. The commands tooling compares
+# against it, pulls from it, and proposes back to it.
+WORKSPACE_REPO="${_env_workspace_repo:-${sources_tooling_repo:-webship/workspace}}";
+WORKSPACE_REPO_REF="${_env_workspace_repo_ref:-${sources_tooling_ref:-1.0.x}}";
+
+# The shared AI agents, skills and prompts come from their own repository, and go back to it the
+# same way commands go back to the tooling one.
+AI_ITEMS_REPO="${_env_ai_items_repo:-${sources_ai_items_repo:-webship/ai-agents}}";
+AI_ITEMS_REF="${_env_ai_items_ref:-${sources_ai_items_ref:-main}}";
+export WORKSPACE_REPO WORKSPACE_REPO_REF AI_ITEMS_REPO AI_ITEMS_REF ;
+
+# The backups folder is the one directory that is not in the checkout.
+mkdir -p "${backups}" 2>/dev/null ;

package/core/scripts/ddev-shim/ddev

@@ -0,0 +1,122 @@
+#!/usr/bin/env bash
+
+################################################################################
+## `ddev`, serialised on the router. A shim, not a replacement.
+################################################################################
+## Every router-mutating verb — start, stop, restart, poweroff, delete — tears the
+## ONE shared ddev-router down and brings it back with the routes of whatever is
+## running. Two at a time race on a single container: one removes it while the
+## other has just created it, and the loser can leave it removed for good. What
+## that looks like is the whole workspace going dark — every *.ddev.site address,
+## the dashboard's hub included — with healthy web containers behind it, and DDEV
+## then refusing to start anything at all:
+##
+##     Failed to start workspace: Error response from daemon:
+##     No such container: ddev-router
+##
+## Recovering needs `ddev poweroff`. Five clicks in thirty-eight seconds did it.
+##
+## The dashboard's own buttons and its AI assistant already take this lock. This
+## shim is for every OTHER caller — a cmd-*.sh script, an agent, a person in a
+## terminal or in `ddev ssh` — because a rule that each caller must remember is a
+## rule that gets forgotten, including by callers nobody has written yet.
+##
+## Install: PATH must reach this file before the real ddev.
+##   container: /usr/local/sbin/ddev  (PATH has /usr/local/sbin before /usr/local/bin)
+##   host:      core/scripts/install.sh offers it, same path, needs sudo
+##
+## FOUR RULES THIS FILE LIVES BY, because a wrong shim breaks every ddev call on
+## the machine — including the dashboard's own status reads every twenty seconds:
+##
+##   1. The real ddev is resolved by ABSOLUTE PATH and checked not to be this
+##      file. Resolving through PATH would find the shim again and fork forever.
+##   2. Anything that is not a router verb is exec'd immediately, with no lock,
+##      no subshell and no added latency. `ddev list --json-output` must cost
+##      exactly what it cost before.
+##   3. Nothing here is fatal. If flock is missing, or the lock file cannot be
+##      created, it says so once on stderr and runs the command anyway. Refusing
+##      to run ddev because a lock could not be taken would be a worse failure
+##      than the one being prevented.
+##   4. It never re-locks a lock already held. The dashboard wraps its own calls
+##      in flock, and taking the same lock again from inside would deadlock for
+##      the full timeout — so DDEV_ROUTER_LOCK_HELD is the interlock, set by
+##      whoever holds it and exported here for anything ddev itself shells out to.
+################################################################################
+
+set -u
+
+# --- 1. the real ddev, by absolute path, and never this file -------------------
+SELF="$(readlink -f "${BASH_SOURCE[0]}" 2>/dev/null || echo "${BASH_SOURCE[0]}")"
+REAL_DDEV=''
+for candidate in /usr/local/bin/ddev /usr/bin/ddev /opt/homebrew/bin/ddev /snap/bin/ddev ; do
+  [ -x "${candidate}" ] || continue
+  [ "$(readlink -f "${candidate}" 2>/dev/null || echo "${candidate}")" == "${SELF}" ] && continue
+  REAL_DDEV="${candidate}"
+  break
+done
+if [ -z "${REAL_DDEV}" ] ; then
+  echo "ddev: this is the workspace's router-lock shim, and the real ddev binary was not found" >&2
+  echo "      (looked in /usr/local/bin, /usr/bin, /opt/homebrew/bin, /snap/bin)" >&2
+  exit 127
+fi
+
+# --- 2. which verb is this? ----------------------------------------------------
+# `ddev [global flags] <verb> [args]`, so the verb is the first argument that is
+# not a flag and not a flag's value. Only the verb matters here, and an unknown
+# shape falls through to the pass-through path, which is the safe direction.
+VERB=''
+for arg in "$@" ; do
+  case "${arg}" in
+    -*) continue ;;
+    *)  VERB="${arg}"; break ;;
+  esac
+done
+
+case "${VERB}" in
+  start|stop|restart|poweroff|delete) ;;
+  # Everything else — list, describe, drush, composer, exec, ssh, snapshot,
+  # export-db, add-on, config, and every verb added in future — is none of this
+  # shim's business. Straight through, same process, no measurable overhead.
+  *) exec "${REAL_DDEV}" "$@" ;;
+esac
+
+# --- 3. the lock ---------------------------------------------------------------
+# Already held by a caller above us: run, do not re-lock (see rule 4).
+if [ -n "${DDEV_ROUTER_LOCK_HELD:-}" ] ; then
+  exec "${REAL_DDEV}" "$@"
+fi
+
+WS_ROOT="${WORKSPACE_ROOT:-${HOME}/workspace}"
+LOCK="${WS_ROOT}/.ddev-router.lock"
+
+if ! command -v flock > /dev/null 2>&1 ; then
+  echo "ddev: flock is not installed, so '${VERB}' runs unserialised — concurrent" >&2
+  echo "      start/stop can destroy the shared ddev-router. Install util-linux." >&2
+  exec "${REAL_DDEV}" "$@"
+fi
+
+# The lock file has to be creatable. It normally exists already; when it does not
+# (a fresh checkout, a different WORKSPACE_ROOT) create it, and if that fails say
+# so and carry on rather than blocking the command.
+if [ ! -e "${LOCK}" ] ; then
+  if ! ( umask 022 && : > "${LOCK}" ) 2>/dev/null ; then
+    echo "ddev: cannot create ${LOCK}, so '${VERB}' runs unserialised." >&2
+    exec "${REAL_DDEV}" "$@"
+  fi
+fi
+
+# Say something only when there is really something to wait for: a free lock has
+# to cost nothing and print nothing, or every start grows a line of noise.
+if ! flock -n "${LOCK}" true 2>/dev/null ; then
+  echo "ddev: waiting — another ddev start/stop/restart holds the router lock." >&2
+  echo "      They cannot run at once: each one recreates the shared ddev-router." >&2
+fi
+
+# Exported so anything the real ddev shells out to (including ddev calling itself)
+# does not queue behind a lock this process already owns.
+export DDEV_ROUTER_LOCK_HELD=1
+
+# -w: bounded, so a wedged start cannot hold the queue for ever. The command's own
+# exit status is what leaves this script, because callers check it.
+flock -w 1800 "${LOCK}" "${REAL_DDEV}" "$@"
+exit $?