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

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

@@ -0,0 +1,179 @@
+#!/usr/bin/env bash
+
+# ElevenLabs for the final voiceover of a narrated video (videos/cmd-tools-elevenlabs.sh).
+# The key is read here and handed to libs/elevenlabs.py in one process's environment, never on a command line.
+
+ELEVENLABS_BLOCK='
+# ElevenLabs, for the final voiceover of a narrated video (videos/cmd-tools-elevenlabs.sh). Nothing is
+# sent to ElevenLabs unless a person agrees to a run. ELEVENLABS_API_KEY in the environment wins over api_key.
+# voice_id may be an id or a voice name such as Brian; voice and model are accepted for voice_id and model_id.
+elevenlabs:
+  api_key: CHANGE_ME
+  voice_id: ask
+  model_id: eleven_v4
+  region: global
+  # Brand names are respelled for the voice only (built in: Webship=Var-dot; Webship=Var-base). Add more as
+  # "Word=Respelling; Word=Respelling" when a voice misreads one.
+  pronunciation: ""
+';
+
+# parse_yaml keeps a value's quotes.
+function elevenlabs_setting() {
+  local value="$1";
+  case "${value}" in
+    \"*\") value="${value#\"}"; value="${value%\"}" ;;
+    \'*\') value="${value#\'}"; value="${value%\'}" ;;
+  esac
+  printf '%s' "${value}";
+}
+
+function elevenlabs_key_source() {
+  local settings_key;
+  settings_key="$(elevenlabs_setting "${elevenlabs_api_key}")";
+  if [ -n "${ELEVENLABS_API_KEY:-}" ] ; then echo 'environment' ; return 0 ; fi
+  case "${settings_key}" in
+    ''|CHANGE_ME|sk-change-this) return 1 ;;
+  esac
+  echo 'settings.yml';
+}
+
+function elevenlabs_key() {
+  case "$(elevenlabs_key_source)" in
+    environment) printf '%s' "${ELEVENLABS_API_KEY}" ;;
+    settings.yml) elevenlabs_setting "${elevenlabs_api_key}" ;;
+  esac
+}
+
+function elevenlabs_base() {
+  if [ -n "${ELEVENLABS_API_BASE:-}" ] ; then echo "${ELEVENLABS_API_BASE%/}" ; return 0 ; fi
+  case "$(elevenlabs_setting "${elevenlabs_region}")" in
+    us) echo 'https://api.us.elevenlabs.io' ;;
+    eu) echo 'https://api.eu.residency.elevenlabs.io' ;;
+    in) echo 'https://api.in.residency.elevenlabs.io' ;;
+    sg) echo 'https://api.sg.residency.elevenlabs.io' ;;
+    *) echo 'https://api.elevenlabs.io' ;;
+  esac
+}
+
+function elevenlabs_model() {
+  local model;
+  model="$(elevenlabs_setting "${elevenlabs_model_id:-${elevenlabs_model:-}}")";
+  echo "${ELEVENLABS_MODEL:-${model:-eleven_v4}}";
+}
+
+function elevenlabs_voice() {
+  local voice;
+  voice="$(elevenlabs_setting "${elevenlabs_voice_id:-${elevenlabs_voice:-}}")";
+  case "${voice}" in ''|ask|CHANGE_ME) voice='' ;; esac
+  echo "${ELEVENLABS_VOICE:-${voice}}";
+}
+
+function elevenlabs_engine() {
+  ELEVENLABS_API_KEY="$(elevenlabs_key)" ELEVENLABS_API_BASE="$(elevenlabs_base)" \
+    ELEVENLABS_MODEL="$(elevenlabs_model)" ELEVENLABS_VOICE="$(elevenlabs_voice)" \
+    ELEVENLABS_PRONUNCIATION="${ELEVENLABS_PRONUNCIATION:-$(elevenlabs_setting "${elevenlabs_pronunciation:-}")}" \
+    python3 "${WORKSPACE_SCRIPTS}/libs/elevenlabs.py" "$@" ;
+}
+
+function elevenlabs_status() {
+  local key_source voice;
+  key_source="$(elevenlabs_key_source)";
+  voice="$(elevenlabs_voice)";
+  echo "ElevenLabs";
+  if [ -n "${key_source}" ] ; then echo "  key:     set (${key_source})" ; else echo "  key:     not set" ; fi
+  echo "  block:   $(grep -q '^elevenlabs:' "${WORKSPACE_CONFIG}/settings.yml" 2>/dev/null && echo 'in settings.yml' || echo 'missing from settings.yml (run -a init)')";
+  echo "  server:  $(elevenlabs_base)";
+  echo "  model:   $(elevenlabs_model)";
+  echo "  voice:   ${voice:-ask each time (list them with -a voices)}";
+  if [ -z "${key_source}" ] ; then
+    echo "";
+    echo "No key, so the final voiceover stage is not offered. Add one at /settings (ElevenLabs); never paste it into a chat.";
+    return 3 ;
+  fi
+}
+
+function elevenlabs_init() {
+  local file="${WORKSPACE_CONFIG}/settings.yml";
+  if [ ! -f "${file}" ] ; then echo "No settings.yml at ${file}." ; return 1 ; fi
+  if grep -q '^elevenlabs:' "${file}" ; then
+    echo "settings.yml already has an elevenlabs: block. Set api_key at /settings (ElevenLabs).";
+    return 0 ;
+  fi
+  [ -n "$(tail -c1 "${file}")" ] && printf '\n' >> "${file}" ;
+  printf '%s' "${ELEVENLABS_BLOCK}" >> "${file}" ;
+  echo "Added an elevenlabs: block to ${file} with a placeholder key. Open /settings, find ElevenLabs and set the key there.";
+}
+
+function elevenlabs_mcp() {
+  local name='elevenlabs' url;
+  url="$(elevenlabs_base)/v1/mcp";
+  if ! command -v claude > /dev/null 2>&1 ; then echo "The Claude Code CLI (claude) is not on PATH." ; return 1 ; fi
+  case "$1" in
+    status)
+      timeout 60 claude mcp get "${name}" 2>&1 || echo "Not registered in Claude Code yet. Run -a mcp-register." ;
+      ;;
+    register)
+      if claude mcp get "${name}" > /dev/null 2>&1 ; then
+        echo "${name} is already registered. -a mcp-unregister removes it first if the address must change.";
+        return 0 ;
+      fi
+      claude mcp add --transport http --scope user "${name}" "${url}" || return 1 ;
+      echo "";
+      echo "Registered ${name} (${url}). No key is stored: it signs in with OAuth.";
+      echo "  Open a NEW session, run /mcp, pick ${name} and sign in with your ElevenLabs account.";
+      echo "  It manages ElevenLabs agents and can generate speech samples. An agent update is published directly,";
+      echo "  with no draft, so keep its write tools on ask-first in the client.";
+      ;;
+    unregister)
+      claude mcp remove --scope user "${name}" && echo "Removed ${name} from the Claude Code CLI." ;
+      ;;
+  esac
+}
+
+function elevenlabs_usage() {
+  cat <<'USAGE'
+usage: cmd-tools-elevenlabs.sh -a ACTION [options]
+
+Free, nothing is sent to ElevenLabs:
+  -a status                      key, voice, model and server (exit 3 when no key is set)
+  -a init                        add the elevenlabs: block to settings.yml when it is missing
+  -a sections --script FILE      the timed sections of a voiceover script and their characters
+
+Reads the account, no credits spent:
+  -a check                       status, plan and characters left
+  -a voices [--search WORD]      the voices on the account
+
+Spends credits, so it prints a plan and stops unless --confirm is given:
+  -a speak --text-file F --out F.mp3 [--voice ID]
+  -a voiceover --script S.md --video V.mp4 --out O.mp4 [--voice ID] [--drop-optional] [--max-speedup 1.08] [--redo]
+  -a isolate --audio TAKE --out CLEAN.mp3
+  -a polish --audio TAKE --video V.mp4 --out O.mp4 [--isolate] [--no-normalize]
+
+The hosted MCP server (OAuth, no key stored):
+  -a mcp-status | mcp-register | mcp-unregister
+
+Add --json for machine-readable output and --force to replace an existing file.
+Exit codes: 0 ok, 1 error, 2 usage, 3 no key, 4 plan only, 5 sections do not fit.
+USAGE
+}
+
+function elevenlabs_main() {
+  local action='status';
+  while [ $# -gt 0 ] ; do
+    case "$1" in
+      -h|--help) elevenlabs_usage ; return 0 ;;
+      -a|--action) action="$2"; shift 2 || { elevenlabs_usage >&2 ; return 2 ; } ;;
+      *) break ;;
+    esac
+  done
+  case "${action}" in
+    status) elevenlabs_status ;;
+    init) elevenlabs_init ;;
+    check) elevenlabs_status && elevenlabs_engine account "$@" ;;
+    sections|voices|speak|isolate|voiceover|polish) elevenlabs_engine "${action}" "$@" ;;
+    mcp-status) elevenlabs_mcp status ;;
+    mcp-register) elevenlabs_mcp register ;;
+    mcp-unregister) elevenlabs_mcp unregister ;;
+    *) echo "Unknown action: ${action}" >&2 ; elevenlabs_usage >&2 ; return 2 ;;
+  esac
+}

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

@@ -0,0 +1,19 @@
+#!/usr/bin/env bash
+
+# Change file permissions and ownership
+function set_chmod() {
+  sudo chmod 775 -R ${WORKSPACE_ROOT}/${doc_name}/${PROJECT_NAME} ;
+}
+
+# Change file permissions and ownership
+function set_chown() {
+  sudo chown www-data:${user_name} -R ${WORKSPACE_ROOT}/${doc_name}/${PROJECT_NAME} ;
+}
+
+# Securing file permissions and ownership.
+function set_chmod_chown() {
+  echo "Securing file permissions and ownership";
+  sudo chmod 775 -R ${WORKSPACE_ROOT}/${doc_name}/${PROJECT_NAME} ;
+  sudo chown www-data:${user_name} -R ${WORKSPACE_ROOT}/${doc_name}/${PROJECT_NAME} ;
+}
+

package/core/scripts/functions/fun-git-worktrees.sh

@@ -0,0 +1,142 @@
+#!/usr/bin/env bash
+
+################################################################################
+## Knowing what a project's folder IS, before anything deletes it.
+################################################################################
+## Once a project can be cloned as a git worktree (see fun-clone-project.sh) a
+## workspace folder holds three different kinds of thing that all look identical
+## in `ls`:
+##
+##   plain     a git checkout that nothing else depends on
+##   primary   the checkout that owns the real .git — other folders live off it
+##   linked    a worktree; its .git is a FILE pointing at the primary's
+##
+## The difference matters exactly once, and destructively:
+##
+##   * Deleting a PRIMARY deletes the shared .git, and every linked worktree of it
+##     becomes an orphan — a directory full of files git can no longer say
+##     anything about. The branches, the stashes and the reflog go with it. That
+##     is unrecoverable in a way that deleting a worktree is not.
+##   * Deleting a LINKED worktree is cheap — unless it holds commits that were
+##     never pushed, which is the one thing `git worktree remove` will happily
+##     destroy for you.
+##
+## So remove_project asks these questions first and refuses rather than guessing.
+## Everything here is read-only except git_worktree_prune, which only tidies
+## administrative data git itself calls stale.
+################################################################################
+
+# plain | primary | linked | none — what this directory is.
+function git_worktree_role() {
+  local dir="${1:-}" common toplevel
+  [ -n "${dir}" ] && [ -d "${dir}" ] || { echo 'none' ; return 0 ; }
+  git -C "${dir}" rev-parse --git-dir > /dev/null 2>&1 || { echo 'none' ; return 0 ; }
+
+  # In a linked worktree the git dir sits INSIDE the primary's .git as
+  # worktrees/<name>, so the two paths differ. In the primary they are the same.
+  local gitdir gitcommon
+  gitdir="$(git -C "${dir}" rev-parse --absolute-git-dir 2>/dev/null)"
+  gitcommon="$(git -C "${dir}" rev-parse --path-format=absolute --git-common-dir 2>/dev/null)"
+  if [ -n "${gitdir}" ] && [ -n "${gitcommon}" ] && [ "${gitdir}" != "${gitcommon}" ] ; then
+    echo 'linked' ; return 0 ;
+  fi
+  # The primary. Whether it is "primary" or merely "plain" is about whether
+  # anything else depends on it.
+  if [ -n "$(git_worktree_others "${dir}")" ] ; then
+    echo 'primary' ;
+  else
+    echo 'plain' ;
+  fi
+}
+
+# The other worktrees of this repository, one absolute path per line, this
+# directory excluded. Parsed from the porcelain form, which is stable output
+# meant for scripts — `git worktree list` without it aligns columns and would
+# break on a path containing spaces.
+function git_worktree_others() {
+  local dir="${1:-}" self
+  [ -n "${dir}" ] && [ -d "${dir}" ] || return 0
+  git -C "${dir}" rev-parse --git-dir > /dev/null 2>&1 || return 0
+  self="$(cd "${dir}" && pwd -P)"
+  git -C "${dir}" worktree list --porcelain 2>/dev/null \
+    | sed -n 's/^worktree //p' \
+    | while IFS= read -r p ; do
+        [ -n "${p}" ] || continue
+        # Compare resolved paths: a symlinked workspace root would otherwise make
+        # a folder look like a different one from itself.
+        [ "$( (cd "${p}" 2>/dev/null && pwd -P) || echo "${p}")" == "${self}" ] && continue
+        echo "${p}" ;
+      done
+}
+
+# The primary worktree's path — where the real .git lives.
+function git_worktree_primary() {
+  local dir="${1:-}"
+  [ -n "${dir}" ] && [ -d "${dir}" ] || return 0
+  git -C "${dir}" rev-parse --git-dir > /dev/null 2>&1 || return 0
+  git -C "${dir}" worktree list --porcelain 2>/dev/null | sed -n '1s/^worktree //p'
+}
+
+# The branch checked out here, or '' when detached.
+function git_worktree_branch() {
+  local dir="${1:-}" b
+  b="$(git -C "${dir}" rev-parse --abbrev-ref HEAD 2>/dev/null)"
+  [ "${b}" == 'HEAD' ] && b=''
+  echo "${b}"
+}
+
+# How many commits reachable from HEAD are on NO remote — i.e. what deleting this
+# folder would destroy. Counting against every remote rather than against an
+# upstream, because a worktree branch created locally has no upstream at all and
+# `@{upstream}` would simply error, which is the case that most needs the answer.
+function git_worktree_unpushed() {
+  local dir="${1:-}" n
+  [ -n "${dir}" ] && [ -d "${dir}" ] || { echo 0 ; return 0 ; }
+  git -C "${dir}" rev-parse --git-dir > /dev/null 2>&1 || { echo 0 ; return 0 ; }
+  n="$(git -C "${dir}" rev-list --count HEAD --not --remotes 2>/dev/null)"
+  echo "${n:-0}"
+}
+
+# Uncommitted work in the folder: tracked changes plus untracked files that are
+# not ignored. Unpushed commits are not the only thing a delete throws away.
+function git_worktree_dirty() {
+  local dir="${1:-}"
+  [ -n "${dir}" ] && [ -d "${dir}" ] || { echo 0 ; return 0 ; }
+  git -C "${dir}" rev-parse --git-dir > /dev/null 2>&1 || { echo 0 ; return 0 ; }
+  # `grep -c` prints 0 AND exits 1 when nothing matches, so a `|| echo 0` fallback
+  # prints a SECOND zero and the caller reads "0 0". Count the lines instead.
+  local n
+  n="$(git -C "${dir}" status --porcelain --untracked-files=normal 2>/dev/null | wc -l | tr -d '[:space:]')"
+  echo "${n:-0}"
+}
+
+# After a worktree's directory is gone, its registration in the primary is stale.
+# git says so on every `worktree list` until it is pruned, and a new worktree at
+# the same path is refused while it stands. Only ever called with the primary.
+function git_worktree_prune() {
+  local primary="${1:-}"
+  [ -n "${primary}" ] && [ -d "${primary}" ] || return 0
+  git -C "${primary}" worktree prune 2>/dev/null || true
+}
+
+# One human line about a folder, for a listing or a confirmation. Says nothing at
+# all for a folder that is not a git checkout, so callers can print it blind.
+function git_worktree_summary() {
+  local dir="${1:-}" role others n branch unpushed
+  role="$(git_worktree_role "${dir}")"
+  case "${role}" in
+    none) return 0 ;;
+    linked)
+      branch="$(git_worktree_branch "${dir}")"
+      unpushed="$(git_worktree_unpushed "${dir}")"
+      printf 'a git worktree on %s of %s' "${branch:-a detached HEAD}" "$(git_worktree_primary "${dir}")" ;
+      [ "${unpushed}" -gt 0 ] && printf ' — %s unpushed commit(s)' "${unpushed}" ;
+      echo ;;
+    primary)
+      n="$(git_worktree_others "${dir}" | grep -c .)"
+      echo "the main checkout, with ${n} worktree(s) depending on its .git" ;;
+    plain)
+      branch="$(git_worktree_branch "${dir}")"
+      echo "a git checkout on ${branch:-a detached HEAD}" ;;
+  esac
+}

package/core/scripts/functions/fun-gitlab-ci.sh

@@ -0,0 +1,156 @@
+#!/usr/bin/env bash
+
+# gitlab-ci-local (https://github.com/firecow/gitlab-ci-local) runs a project's
+# GitLab CI pipeline in local Docker containers. It is how the Webship
+# green-gate is enforced: before committing to an issue-fork branch or pushing
+# anything to git.drupalcode.org, the full pipeline runs locally and the push
+# waits until every stage and every job is green.
+#
+# Drupal projects include drupal/gitlab_templates, whose jobs die on an unset
+# _GITLAB_TEMPLATES_REPO unless the template variables are resolved. The
+# standard fix is a wrapper that adds --remote-variables over SSH (upstream
+# says HTTPS clones "do not work completely without issues"), which these
+# functions install once as ~/.local/bin/drupal-ci-local.
+
+# Make sure gitlab-ci-local is on PATH; offer the install paths if not.
+function ensure_gitlab_ci_local() {
+  if command -v gitlab-ci-local > /dev/null 2>&1 ; then
+    return 0 ;
+  fi
+  echo "gitlab-ci-local is not installed — installing with npm.";
+  npm install -g gitlab-ci-local || {
+    echo "npm install failed. Alternatives:" ;
+    echo "  brew install gitlab-ci-local          # macOS" ;
+    echo "  see https://github.com/firecow/gitlab-ci-local#installation" ;
+    return 1 ;
+  }
+  command -v gitlab-ci-local > /dev/null 2>&1 || {
+    echo "Still not on PATH — check npm's global bin directory." ;
+    return 1 ;
+  }
+}
+
+# The Drupal wrapper: gitlab-ci-local plus the drupal/gitlab_templates remote
+# variables. Written once, then everything Drupal runs through it.
+function ensure_drupal_ci_wrapper() {
+  local wrapper="${HOME}/.local/bin/drupal-ci-local";
+  if [ -x "${wrapper}" ]; then
+    return 0 ;
+  fi
+  mkdir -p "${HOME}/.local/bin" ;
+  cat > "${wrapper}" <<'WRAP'
+#!/bin/bash
+# gitlab-ci-local wired for drupal/gitlab_templates. SSH on purpose: upstream
+# documents that HTTPS template clones do not work completely without issues.
+gitlab-ci-local \
+  --remote-variables git@git.drupal.org:project/gitlab_templates=includes/include.drupalci.variables.yml=main \
+  --variable="_GITLAB_TEMPLATES_REPO=project/gitlab_templates" \
+  "$@"
+WRAP
+  chmod +x "${wrapper}" ;
+  echo "Installed ${wrapper}." ;
+}
+
+# Everything a run needs, checked up front with real error messages.
+function gitlab_ci_local_doctor() {
+  local ok=0;
+  ensure_gitlab_ci_local || ok=1 ;
+  ensure_drupal_ci_wrapper || ok=1 ;
+  if ! docker info > /dev/null 2>&1 ; then
+    echo "Docker is not reachable — every job runs in a container. Start Docker first." ;
+    ok=1 ;
+  fi
+  if ! ssh -o BatchMode=yes -o ConnectTimeout=8 git@git.drupal.org 2>&1 | grep -q 'Welcome to GitLab' ; then
+    echo "SSH to git.drupal.org failed — the Drupal template variables are fetched over SSH." ;
+    echo "Load your key into ssh-agent, or add one: https://git.drupalcode.org/-/user_settings/ssh_keys" ;
+    ok=1 ;
+  fi
+  return ${ok} ;
+}
+
+# Run a project's pipeline (or one job) with the green-gate framing.
+function gitlab_ci_local_run() {
+  local project_path="${WORKSPACE_ROOT}/${doc_name}/${PROJECT_NAME}";
+
+  if [ ! -d "${project_path}" ]; then
+    echo "No such project: ${project_path}";
+    return 1 ;
+  fi
+
+  gitlab_ci_local_doctor || return 1 ;
+  cd "${project_path}" ;
+
+  # Pick the file: --slim prefers the project's committed .gitlab-ci-local.yml
+  # (the reproducible subset); otherwise the real pipeline.
+  local ci_args="";
+  local runner="drupal-ci-local";
+  if [ "${SLIM}" == 'yes' ] ; then
+    if [ ! -f ".gitlab-ci-local.yml" ]; then
+      echo "No .gitlab-ci-local.yml in this project — run without --slim, or add one";
+      echo "(see the webship-gitlab-ci-local-runner skill for the pattern).";
+      return 1 ;
+    fi
+    ci_args="--file .gitlab-ci-local.yml";
+    runner="gitlab-ci-local";   # the slim file is self-contained, no templates
+  elif [ ! -f ".gitlab-ci.yml" ]; then
+    echo "No .gitlab-ci.yml here — nothing to run.";
+    return 1 ;
+  fi
+
+  if [ ! "${VARIABLE}" == '_none_' ] ; then
+    ci_args="${ci_args} --variable ${VARIABLE}";
+  fi
+
+  # gitignore the artifacts dir once, quietly.
+  if [ -d .git ] && ! grep -qs '^\.gitlab-ci-local/' .gitignore 2>/dev/null ; then
+    echo ".gitlab-ci-local/" >> .gitignore ;
+    echo "Added .gitlab-ci-local/ to .gitignore (artifacts and logs land there)." ;
+  fi
+
+  if [ "${LIST}" == 'yes' ] ; then
+    ${runner} ${ci_args} --list ;
+    return $? ;
+  fi
+
+  echo "*---------------------------------------------------------------------*";
+  echo "  Green-gate run: ${doc_name}/${PROJECT_NAME}${JOB:+ — job: ${JOB}}";
+  echo "*---------------------------------------------------------------------*";
+
+  local output_file;
+  output_file=$(mktemp) ;
+  if [ -n "${JOB}" ] && [ ! "${JOB}" == '_none_' ] ; then
+    ${runner} ${ci_args} "${JOB}" 2>&1 | tee "${output_file}" ;
+  else
+    ${runner} ${ci_args} 2>&1 | tee "${output_file}" ;
+  fi
+  local status=${PIPESTATUS[0]} ;
+
+  # Known blocker: gitlab-ci-local crashes evaluating any rule whose =~ regex
+  # embeds a $variable (firecow/gitlab-ci-local#1893), and drupal/gitlab_templates
+  # has used that pattern for years — every ref, every gitlab-ci-local version.
+  # Until that lands upstream, the slim .gitlab-ci-local.yml is the only
+  # runnable path for a templates-based project.
+  if [ ${status} -ne 0 ] && grep -q 'Error attempting to evaluate the following rules' "${output_file}" ; then
+    echo "";
+    echo "This is firecow/gitlab-ci-local#1893: a \$variable nested inside an =~ regex";
+    echo "crashes rule evaluation, and drupal/gitlab_templates uses that pattern on";
+    echo "every ref. The full templates pipeline cannot run locally until that bug";
+    echo "is fixed upstream. Run the reproducible subset instead:";
+    echo "  bash cmd-tools-gitlab-ci-local.sh ${PROJECT_NAME} --slim";
+    echo "(add a .gitlab-ci-local.yml first if the project has none — the";
+    echo "webship-gitlab-ci-local-runner skill carries the pattern), and gate the";
+    echo "template-only jobs on the remote pipeline.";
+  fi
+  rm -f "${output_file}" ;
+
+  echo "";
+  if [ ${status} -eq 0 ] ; then
+    echo "GREEN — every executed job passed. Jobs that cannot run locally are";
+    echo "not a pass: gate those on the remote pipeline before merging.";
+  else
+    echo "RED (exit ${status}) — the push is blocked. Fix the failing job and";
+    echo "re-run; never mask it with allow_failure or || true.";
+  fi
+  cd "${WORKSPACE_ROOT}/${doc_name}";
+  return ${status} ;
+}

package/core/scripts/functions/fun-hostnames-cli.sh

@@ -0,0 +1,88 @@
+#!/usr/bin/env bash
+
+# The command layer over fun-ddev-hostnames.sh: one project, or a listing of the
+# whole workspace. Kept apart from the functions that touch DDEV so the reporting
+# path cannot accidentally write anything.
+
+function hostnames_command() {
+  local workspace_dir="${WORKSPACE_ROOT}/${doc_name}"
+  local project="${PROJECT_NAME}"
+
+  if [ -z "${project}" ] || [ "${project}" == '_none_' ] ; then
+    hostnames_list_workspace ;
+    return 0 ;
+  fi
+
+  project="$(trim_project_name "${project}")"
+  local dir="${workspace_dir}/${project}"
+  if [ ! -d "${dir}" ] ; then
+    echo "No project '${project}' in ${workspace_dir}." ; return 1 ;
+  fi
+  if [ ! -f "${dir}/.ddev/config.yaml" ] ; then
+    echo "'${project}' is not a DDEV project — there is no hostname to change." ; return 1 ;
+  fi
+
+  local changed='no'
+  if [ "${REMOVE}" != '_none_' ] && [ -n "${REMOVE}" ] ; then
+    ddev_hostnames_remove "${dir}" "${REMOVE}" || return 1 ;
+    changed='yes' ;
+  fi
+  local to_add=()
+  [ "${ADD}" != '_none_' ] && [ -n "${ADD}" ] && to_add+=("${ADD}")
+  if [ "${WITH_WORKSPACE}" == 'yes' ] ; then
+    to_add+=("$(ddev_workspace_hostname "${project}" "${doc_name}")")
+  fi
+  if [ "${#to_add[@]}" -gt 0 ] ; then
+    echo "Adding to ${doc_name}/${project}:" ;
+    ddev_hostnames_add "${dir}" "${to_add[@]}" || return 1 ;
+    changed='yes' ;
+  fi
+
+  echo "" ;
+  echo "*---------------------------------------------------------------------*" ;
+  echo "  ${doc_name}/${project} answers at" ;
+  echo "*---------------------------------------------------------------------*" ;
+  ddev_hostnames_report "${dir}" "${project}" "${doc_name}" ;
+
+  # --start is honoured whether or not anything changed here. It was gated on
+  # `changed` at first, so `--start` on a project whose hostname was added a
+  # minute ago printed the report and did nothing — and the hostname stayed 404,
+  # which looks exactly like the feature not working.
+  if [ "${changed}" == 'yes' ] || [ "${START}" == 'yes' ] ; then
+    if [ "${START}" == 'yes' ] ; then
+      echo "" ;
+      echo "Starting the project so the router picks the change up…" ;
+      ( cd "${dir}" && ddev start -y ) || return 1 ;
+    else
+      echo "" ;
+      echo "  Not live yet: a hostname reaches the router on the next start." ;
+      echo "  Re-run with --start, or: cd ${dir} && ddev start" ;
+    fi
+  fi
+}
+
+# Every project in this workspace and what it answers at. The reason this exists
+# as a listing: two projects claiming one hostname is invisible one project at a
+# time, and it is exactly the mistake --with-workspace exists to avoid.
+function hostnames_list_workspace() {
+  local workspace_dir="${WORKSPACE_ROOT}/${doc_name}" d p extra tld
+  tld="$(ddev_project_tld)"
+  echo "*---------------------------------------------------------------------*" ;
+  echo "  ${doc_name}: what each project answers at  (TLD: ${tld})" ;
+  echo "*---------------------------------------------------------------------*" ;
+  local found=0
+  for d in "${workspace_dir}"/*/ ; do
+    [ -d "${d}" ] || continue
+    p="$(basename "${d}")"
+    [ -f "${d}/.ddev/config.yaml" ] || continue
+    found=$((found+1))
+    extra="$(ddev_hostnames_list "${d}" | paste -sd' ' -)"
+    printf "  %-34s %s\n" "${p}" "$(ddev_project_name "${d}" 2>/dev/null).${tld}" ;
+    [ -n "${extra}" ] && printf "  %-34s + %s\n" "" "${extra}" ;
+  done
+  [ "${found}" -eq 0 ] && echo "  no DDEV projects here." ;
+  echo "" ;
+  echo "  Add one:     bash cmd-tools-hostnames.sh <project> --add <label> --start" ;
+  echo "  Or the flat, workspace-qualified one (<project>-${doc_name}):" ;
+  echo "               bash cmd-tools-hostnames.sh <project> --with-workspace --start" ;
+}