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

package/core/scripts/functions/fun-specs-share.sh

@@ -0,0 +1,237 @@
+#!/usr/bin/env bash
+
+################################################################################
+## Sharing the specs that are worth sharing.
+################################################################################
+## SPDD's own claim is that "successful patterns naturally accumulate into a reusable prompt
+## library" and that each iteration "starts from accumulated assets". Accumulation does not happen
+## by itself: a template improved on one machine, in one workspace, improves nothing for anybody
+## else. Agents, skills and prompts already solve this — one shared repository, fetched with
+## `git archive` from the fetched remote branch, pulled into the workspace folder to read and edit.
+## This is the same mechanism for the same reason.
+##
+## **Only two kinds of spec are shared, and the exclusion is the design.**
+##
+##   _defaults/   the templates every spec starts from, and the review checklist.
+##   */00-constitution.md   the general spec of a product: what it is, who for, what it must
+##                          never become. Written once, revised rarely, useful to everyone who
+##                          touches that product.
+##
+## A NUMBERED spec — `001-some-change/` — is about one change, in one tree, at one moment. It is
+## the most valuable artifact locally and pure noise shared: nobody else's repository has that
+## change, and the analysis it contains was true of a commit they are not on. Sharing those would
+## turn the shared repository into a landfill of other people's finished work, and the templates
+## nobody could find in it would stop being pulled. So they stay local.
+##
+## Nothing here pushes. Promotion to the shared repository goes through the issue and MR/PR path
+## like every other change, because a template everybody inherits deserves a review.
+################################################################################
+
+# What is shared, as a predicate. One place, so the listing, the diff and the pull cannot disagree
+# about what "a shared spec" means.
+function specs_is_shared_path() {
+  local rel="$1";
+  case "${rel}" in
+    _defaults/*) return 0 ;;
+    */00-constitution.md) return 0 ;;
+    *) return 1 ;;
+  esac
+}
+
+function specs_root() { echo "${WORKSPACE_ROOT}/specs"; }
+
+# Where the shared specs live in the shared repository. A top level `specs/`, beside `prompts/` and
+# `.claude/`, because a spec is not a thing Claude Code loads — it is a thing people read.
+function specs_repo_path() { echo "specs"; }
+
+# The checkout the repository is read from, kept between runs. Gitignored and hidden from the
+# workspace listing, the way the AI-items checkout and the commands mirror are.
+function specs_checkout() { echo "$(specs_root)/dev-ai-agents"; }
+
+# Every shared spec in this workspace folder, as paths relative to specs/.
+function specs_local_shared() {
+  local root; root="$(specs_root)";
+  [ -d "${root}" ] || return 0 ;
+  ( cd "${root}" && find . -name '*.md' -o -name '*.yml' ) 2>/dev/null \
+    | sed 's|^\./||' | sort | while read -r rel ; do
+      specs_is_shared_path "${rel}" && echo "${rel}" ;
+    done
+}
+
+# Refresh the checkout and answer with the remote branch to read from. Prints nothing on success
+# beyond the one line saying what it did, because this runs inside every other verb.
+function specs_fetch_repo() {
+  local checkout; checkout="$(specs_checkout)";
+  ensure_gh_cli || return 1 ;
+  ensure_git_github_auth ;
+  if [ -d "${checkout}/.git" ] ; then
+    git -C "${checkout}" fetch --quiet origin || return 1 ;
+  else
+    echo "Cloning ${AI_ITEMS_REPO}…" >&2 ;
+    git clone --quiet "https://github.com/${AI_ITEMS_REPO}.git" "${checkout}" || {
+      echo "Could not clone ${AI_ITEMS_REPO} — check gh auth and repository access." >&2 ;
+      return 1 ;
+    }
+  fi
+  local remote_branch;
+  remote_branch=$(git -C "${checkout}" symbolic-ref --quiet --short refs/remotes/origin/HEAD 2>/dev/null) ;
+  echo "${remote_branch:-origin/${AI_ITEMS_REF:-main}}" ;
+}
+
+# The shared specs as the repository has them, extracted to a temporary directory. Read from the
+# FETCHED REMOTE BRANCH with git archive, never from the checkout's working tree: that clone may
+# sit on any branch and hold anybody's work in progress.
+function specs_remote_tree() {
+  local branch="$1" tmp;
+  tmp="$(mktemp -d)" || return 1 ;
+  # Both halves quiet: with no specs/ in the branch, git archive fails and tar then complains that
+  # an empty stream is not an archive. That pair of errors is the NORMAL answer the first time
+  # anybody runs this — the shared repository does not carry specs until somebody proposes one —
+  # and printing it makes a working command look broken.
+  if ! git -C "$(specs_checkout)" archive "${branch}" "$(specs_repo_path)" 2>/dev/null | tar -x -C "${tmp}" 2>/dev/null ; then
+    rm -rf "${tmp}" ;
+    return 1 ;
+  fi
+  echo "${tmp}" ;
+}
+
+# What the shared repository has.
+function specs_list_remote() {
+  local branch tmp base;
+  branch="$(specs_fetch_repo)" || return 1 ;
+  tmp="$(specs_remote_tree "${branch}")" || {
+    echo "Nothing at $(specs_repo_path)/ in ${branch} — the shared repository carries no specs yet." ;
+    return 0 ;
+  }
+  base="${tmp}/$(specs_repo_path)";
+  echo "";
+  echo "Shared specs in ${AI_ITEMS_REPO} (${branch#origin/})";
+  echo "";
+  ( cd "${base}" && find . -type f \( -name '*.md' -o -name '*.yml' \) | sed 's|^\./||' | sort ) \
+    | while read -r rel ; do printf '  %s\n' "${rel}" ; done
+  echo "";
+  rm -rf "${tmp}" ;
+}
+
+# What is here, what is shared, and where the two differ. The answer people actually want, and the
+# one that decides whether to pull.
+function specs_status() {
+  local branch tmp base root rel local_file state;
+  root="$(specs_root)";
+  echo "";
+  echo "Shared specs — ${root}";
+  echo "";
+  branch="$(specs_fetch_repo)" || { echo "  (the shared repository could not be read; showing local only)" ; branch='' ; }
+  if [ -n "${branch}" ] ; then
+    tmp="$(specs_remote_tree "${branch}")" || tmp='' ;
+    base="${tmp}/$(specs_repo_path)";
+  fi
+
+  printf '  %-52s %s\n' "SPEC" "STATE" ;
+  specs_local_shared | while read -r rel ; do
+    local_file="${root}/${rel}";
+    if [ -z "${branch}" ] || [ -z "${tmp}" ] || [ ! -f "${base}/${rel}" ] ; then
+      state="local only" ;
+    elif cmp -s "${local_file}" "${base}/${rel}" ; then
+      state="same as shared" ;
+    else
+      state="DIFFERS from shared" ;
+    fi
+    printf '  %-52s %s\n' "${rel}" "${state}" ;
+  done
+
+  # And what the repository has that this machine does not — the reason to run --pull.
+  if [ -n "${tmp}" ] && [ -d "${base}" ] ; then
+    ( cd "${base}" && find . -type f \( -name '*.md' -o -name '*.yml' \) | sed 's|^\./||' | sort ) \
+      | while read -r rel ; do
+          [ -f "${root}/${rel}" ] || printf '  %-52s %s\n' "${rel}" "in the repository only" ;
+        done
+  fi
+  echo "";
+  echo "  --pull to take the shared copy, --diff to see what changed first." ;
+  echo "";
+  [ -n "${tmp}" ] && rm -rf "${tmp}" ;
+  return 0 ;
+}
+
+# What would change if this were pulled. Shown before it is taken, never after: a template is read
+# by every future spec, and overwriting one unseen is how a local improvement disappears.
+function specs_diff() {
+  local want="$1" branch tmp base root rel shown=0;
+  root="$(specs_root)";
+  branch="$(specs_fetch_repo)" || return 1 ;
+  tmp="$(specs_remote_tree "${branch}")" || { echo "The shared repository carries no specs yet." ; return 0 ; }
+  base="${tmp}/$(specs_repo_path)";
+
+  ( cd "${base}" && find . -type f \( -name '*.md' -o -name '*.yml' \) | sed 's|^\./||' | sort ) \
+    | while read -r rel ; do
+        [ "${want}" == '_all_' ] || [ -z "${want}" ] || case "${rel}" in *"${want}"*) : ;; *) continue ;; esac
+        if [ ! -f "${root}/${rel}" ] ; then
+          echo "=== ${rel} — not here yet" ;
+        elif ! cmp -s "${root}/${rel}" "${base}/${rel}" ; then
+          echo "=== ${rel}" ;
+          diff -u "${root}/${rel}" "${base}/${rel}" | sed '1,2d' ;
+        fi
+      done
+  shown=$? ;
+  rm -rf "${tmp}" ;
+  return 0 ;
+}
+
+# Take the shared copy. A local file that differs is BACKED UP first, with the path printed: a pull
+# can move you backwards — the shared branch does not carry work still in review — and a template
+# somebody improved this morning must not vanish because they ran a sync this afternoon.
+function specs_pull() {
+  local want="$1" branch tmp base root rel dest backup stamp pulled=0;
+  root="$(specs_root)";
+  branch="$(specs_fetch_repo)" || return 1 ;
+  tmp="$(specs_remote_tree "${branch}")" || { echo "The shared repository carries no specs yet — nothing to pull." ; return 0 ; }
+  base="${tmp}/$(specs_repo_path)";
+  stamp="$(date +%Y-%m-%d-%H%M)";
+
+  while read -r rel ; do
+    [ -n "${rel}" ] || continue ;
+    [ "${want}" == '_all_' ] || [ -z "${want}" ] || case "${rel}" in *"${want}"*) : ;; *) continue ;; esac
+    specs_is_shared_path "${rel}" || continue ;
+    dest="${root}/${rel}";
+    if [ -f "${dest}" ] && cmp -s "${dest}" "${base}/${rel}" ; then continue ; fi
+    if [ -f "${dest}" ] ; then
+      backup="${WORKSPACE_ROOT}/backups/specs/${stamp}/${rel}";
+      mkdir -p "$(dirname "${backup}")" ;
+      cp "${dest}" "${backup}" ;
+      echo "  kept your copy at ${backup}" ;
+    fi
+    mkdir -p "$(dirname "${dest}")" ;
+    cp "${base}/${rel}" "${dest}" ;
+    echo "  pulled ${rel}" ;
+    pulled=$((pulled + 1)) ;
+  done < <( cd "${base}" && find . -type f \( -name '*.md' -o -name '*.yml' \) | sed 's|^\./||' | sort )
+
+  rm -rf "${tmp}" ;
+  echo "" ;
+  if [ "${pulled}" -eq 0 ] ; then
+    echo "Nothing to pull — everything shared is already what you have." ;
+  else
+    echo "${pulled} file(s) pulled from ${AI_ITEMS_REPO}." ;
+  fi
+}
+
+# Promoting a local improvement back to everybody. Deliberately NOT automated: a template is
+# inherited by every future spec in every workspace, so it goes through the same issue-and-PR path
+# as any other change. This prints exactly what to do, and creates nothing.
+function specs_propose() {
+  local root; root="$(specs_root)";
+  echo "";
+  echo "Sharing a spec back to ${AI_ITEMS_REPO}";
+  echo "";
+  echo "  Nothing here pushes. A template or a constitution is inherited by everyone who pulls it,"
+  echo "  so it is proposed and reviewed like any other change:";
+  echo "";
+  echo "    1. git -C $(specs_checkout) checkout -b <branch>";
+  echo "    2. copy your file into $(specs_checkout)/$(specs_repo_path)/<same relative path>";
+  echo "    3. commit, push, and open the PR on ${AI_ITEMS_REPO}";
+  echo "";
+  echo "  What is shared: _defaults/ and every 00-constitution.md. A numbered spec is about one";
+  echo "  change in one tree and is not shared — see fun-specs-share.sh for why.";
+  echo "";
+}

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

@@ -0,0 +1,347 @@
+#!/usr/bin/env bash
+
+# Second storage: whole workspace folders kept on another disk, each one a symlink from the tree.
+#
+# `storage.second` in settings.yml names the folder on that disk that holds them. A moved workspace is
+# `<root>/<name> -> <storage>/<name>`, so every script and the dashboard keep using `<root>/<name>`.
+#
+# Three rules hold throughout:
+#   * nothing is deleted without a flag that says so. A move keeps `<name>.pre-move`, a move back keeps
+#     the copy on the drive;
+#   * a copy is trusted only after a checksum compare finds no difference;
+#   * a workspace that holds DDEV projects is refused. DDEV bind-mounts a project's folder into its
+#     containers, and that has not been verified across a symlink onto another disk.
+
+STORAGE_RSYNC_FLAGS="${STORAGE_RSYNC_FLAGS:--aHAX}";
+STORAGE_COMPOSE_NAME="docker-compose.second-storage.yaml";
+
+# The configured path, one layer of quotes stripped (parse_yaml keeps them), no trailing slash.
+function storage_path() {
+  local p="${storage_second:-}" ;
+  p="${p#\"}" ; p="${p%\"}" ; p="${p#\'}" ; p="${p%\'}" ;
+  case "${p}" in ''|CHANGE_ME|none|off) return 0 ;; esac
+  printf '%s' "${p%/}" ;
+}
+
+function storage_say() { [ "${QUIET:-}" == 'yes' ] || echo "$@" ; }
+
+function storage_is_workspace() {
+  local w ;
+  for w in "${workspaces[@]}" ; do [ "${w}" == "$1" ] && return 0 ; done
+  return 1 ;
+}
+
+# local | second | elsewhere | broken | missing
+#   second     a symlink into the configured storage path that resolves
+#   elsewhere  a symlink that resolves, but not into the configured path
+#   broken     a symlink whose target is not there: the drive is not mounted, or it moved
+function storage_state() {
+  local link="${WORKSPACE_ROOT}/$1" storage target ;
+  storage="$(storage_path)" ;
+  if [ -L "${link}" ] ; then
+    target="$(readlink "${link}")" ;
+    [ -d "${link}" ] || { echo 'broken' ; return 0 ; } ;
+    if [ -n "${storage}" ] && [ "${target%/}" == "${storage}/$1" ] ; then echo 'second' ; else echo 'elsewhere' ; fi
+  elif [ -d "${link}" ] ; then
+    echo 'local' ;
+  else
+    echo 'missing' ;
+  fi
+}
+
+# Any DDEV project inside, at the depths projects live at (a project, or a project inside a clone).
+function storage_has_ddev() {
+  [ -n "$(find "$1" -mindepth 2 -maxdepth 4 -type f -path '*/.ddev/config.yaml' -print -quit 2>/dev/null)" ] ;
+}
+
+function storage_avail_bytes() { df -B1 --output=avail "$1" 2>/dev/null | tail -1 | tr -d ' ' ; }
+function storage_size_bytes()  { du -sb "$1" 2>/dev/null | cut -f1 ; }
+function storage_human()       { numfmt --to=iec --suffix=B "${1:-0}" 2>/dev/null || echo "${1:-0} bytes" ; }
+
+# True when both paths are on one filesystem, where a move frees nothing.
+function storage_same_fs() {
+  [ "$(stat -c %d "$1" 2>/dev/null)" == "$(stat -c %d "$2" 2>/dev/null)" ] ;
+}
+
+# The storage path exists and is on its own filesystem.
+function storage_mounted() {
+  local storage ; storage="$(storage_path)" ;
+  [ -n "${storage}" ] && [ -d "${storage}" ] && ! storage_same_fs "${storage}" "${WORKSPACE_ROOT}" ;
+}
+
+# Room for size plus a margin: 5%, at least 1 GiB.
+function storage_has_room() {
+  local size="$1" dest="$2" avail margin ;
+  avail="$(storage_avail_bytes "${dest}")" ;
+  margin=$(( size / 20 )) ; [ "${margin}" -lt 1073741824 ] && margin=1073741824 ;
+  [ -n "${avail}" ] && [ "${avail}" -ge $(( size + margin )) ] ;
+}
+
+# Lines that differ between two trees, by checksum. Empty means identical.
+function storage_diff() {
+  rsync ${STORAGE_RSYNC_FLAGS} -nc --delete --itemize-changes "$1/" "$2/" 2>&1 ;
+}
+
+function storage_copy() {
+  rsync ${STORAGE_RSYNC_FLAGS} --delete "$1/" "$2/" ;
+}
+
+# Copy, then compare. Prints why and returns 1 on any difference.
+function storage_copy_verified() {
+  local from="$1" to="$2" diff ;
+  storage_say "  copying ${from} → ${to}" ;
+  if ! storage_copy "${from}" "${to}" ; then
+    echo "  ✗ rsync failed. Nothing was swapped; ${from} is untouched." ; return 1 ;
+  fi
+  storage_say "  verifying by checksum" ;
+  diff="$(storage_diff "${from}" "${to}")" ;
+  if [ -n "${diff}" ] ; then
+    echo "  ✗ The copy differs from the source ($(printf '%s\n' "${diff}" | wc -l) lines). Nothing was swapped:" ;
+    printf '%s\n' "${diff}" | head -10 | sed 's/^/      /' ;
+    return 1 ;
+  fi
+  storage_say "  ✓ identical" ;
+}
+
+# The mount the drive needs in the dashboard container, one host path per line, at the same path.
+# Under /run/media/<user> the PARENT is mounted, because udisks picks the folder name at mount time
+# (`workspace`, then `workspace1` when a stale `workspace` is in the way), and a bind of the parent with
+# rslave also sees a drive mounted after the dashboard started.
+function storage_mount_sources() {
+  local storage link target ;
+  storage="$(storage_path)" ;
+  {
+    [ -n "${storage}" ] && printf '%s\n' "${storage}" ;
+    # Links that still point somewhere else (an old path) need their target too, or they break inside.
+    for link in "${WORKSPACE_ROOT}"/* ; do
+      [ -L "${link}" ] || continue ;
+      target="$(readlink "${link}")" ;
+      case "${target}" in /*) printf '%s\n' "$(dirname "${target}")" ;; esac
+    done
+  } | while read -r p ; do
+    case "${p}" in
+      "${WORKSPACE_ROOT}"|"${WORKSPACE_ROOT}"/*) ;;
+      /run/media/*/*) printf '%s\n' "$(printf '%s' "${p}" | cut -d/ -f1-4)" ;;
+      *) printf '%s\n' "${p}" ;;
+    esac
+  done | sort -u ;
+}
+
+function storage_compose() {
+  local sources src ;
+  sources="$(storage_mount_sources)" ;
+  [ -n "${sources}" ] || return 0 ;
+  echo "# Generated by core/scripts/storage.sh --mounts from storage.second in settings.yml." ;
+  echo "# This machine only: never committed, and rewritten by every run. Edit the setting, not this file." ;
+  echo "# The second storage, at the same path as on the host, so the workspace symlinks resolve in here." ;
+  echo "services:" ;
+  echo "  web:" ;
+  echo "    volumes:" ;
+  while read -r src ; do
+    case "${src}" in
+      /run/media/*) echo "      - ${src}:${src}:rslave" ;;
+      *)            echo "      - ${src}:${src}" ;;
+    esac
+  done <<< "${sources}" ;
+}
+
+function storage_compose_file() { echo "${WORKSPACE_ROOT}/core/workspace-app/.ddev/${STORAGE_COMPOSE_NAME}" ; }
+
+# Write (or remove) the dashboard's override. Says a restart is needed only when it changed.
+function storage_write_mounts() {
+  local file new old ;
+  file="$(storage_compose_file)" ;
+  [ -d "$(dirname "${file}")" ] || { echo "  ✗ No dashboard at $(dirname "$(dirname "${file}")")." ; return 1 ; } ;
+  new="$(storage_compose)" ;
+  old="$(cat "${file}" 2>/dev/null)" ;
+  if [ "${new}" == "${old}" ] ; then
+    storage_say "  ✓ dashboard mounts up to date${new:+ (${file##*/})}" ;
+    return 0 ;
+  fi
+  if [ -z "${new}" ] ; then
+    rm -f "${file}" ;
+    echo "  ✓ removed ${file##*/}: no second storage is set or linked" ;
+  else
+    printf '%s\n' "${new}" > "${file}" ;
+    echo "  ✓ wrote ${file#${WORKSPACE_ROOT}/}:" ;
+    grep '^      - ' "${file}" | sed 's/^      - /      /' ;
+  fi
+  echo "    The dashboard picks it up on its next restart:" ;
+  echo "      cd ${WORKSPACE_ROOT}/core/workspace-app && ddev restart" ;
+  echo "    Check no build job is running first; a restart orphans it." ;
+}
+
+# The stable fix for a udisks mount whose path can change: an fstab line by UUID to a fixed point.
+function storage_fstab_hint() {
+  local storage mnt uuid fstype label point stale ;
+  storage="$(storage_path)" ;
+  case "${storage}" in /run/media/*) ;; *) return 0 ;; esac
+  [ -d "${storage}" ] || return 0 ;
+  mnt="$(findmnt -no TARGET -T "${storage}" 2>/dev/null)" ;
+  uuid="$(findmnt -no UUID -T "${storage}" 2>/dev/null)" ;
+  fstype="$(findmnt -no FSTYPE -T "${storage}" 2>/dev/null)" ;
+  label="$(findmnt -no LABEL -T "${storage}" 2>/dev/null)" ;
+  [ -n "${uuid}" ] || return 0 ;
+  point="${STORAGE_MOUNT_POINT:-/mnt/workspace-storage}" ;
+  # udisks names the folder after the label and adds a digit when that name is taken.
+  stale="$(dirname "${mnt}")/${label}" ;
+  echo "" ;
+  echo "  ! ${mnt} is a udisks automount. Its path is picked at mount time (a leftover" ;
+  echo "    folder named after the label makes udisks add a digit), so after a reboot every" ;
+  echo "    workspace link can break. The stable fix, run by you (this tool never uses sudo):" ;
+  echo "      (cd ${WORKSPACE_ROOT}/core/workspace-app && ddev stop)   # it holds the mount open" ;
+  echo "      sudo mkdir -p ${point}" ;
+  echo "      echo 'UUID=${uuid}  ${point}  ${fstype:-auto}  defaults,nofail,x-systemd.device-timeout=10s  0  2' | sudo tee -a /etc/fstab" ;
+  echo "      sudo systemctl daemon-reload && sudo umount ${mnt} && sudo mount ${point}" ;
+  if [ "${stale}" != "${mnt}" ] && [ -d "${stale}" ] && [ -z "$(ls -A "${stale}" 2>/dev/null)" ] ; then
+    echo "      sudo rmdir ${stale}      # the empty leftover that pushed it to ${mnt##*/}" ;
+  fi
+  echo "    then set storage.second to ${point}${storage#${mnt}} and run:" ;
+  echo "      bash ${WORKSPACE_SCRIPTS}/storage.sh --relink --mounts" ;
+}
+
+function storage_status() {
+  local storage w state target size free_local free_second ;
+  storage="$(storage_path)" ;
+  echo "Second storage: ${storage:-not set (storage.second in settings.yml)}" ;
+  if [ -n "${storage}" ] ; then
+    if storage_mounted ; then
+      free_second="$(storage_avail_bytes "${storage}")" ;
+      echo "  mounted: $(findmnt -no TARGET,SOURCE,FSTYPE -T "${storage}" 2>/dev/null | tr -s ' ')" ;
+      echo "  free:    $(storage_human "${free_second}")" ;
+    elif [ -d "${storage}" ] ; then
+      echo "  ✗ ${storage} is on the same filesystem as the workspace: the drive is not mounted there." ;
+    else
+      echo "  ✗ ${storage} does not exist: the drive is not mounted." ;
+    fi
+  fi
+  free_local="$(storage_avail_bytes "${WORKSPACE_ROOT}")" ;
+  echo "Workspace: ${WORKSPACE_ROOT}" ;
+  echo "  free:    $(storage_human "${free_local}")" ;
+  echo "" ;
+  for w in "${workspaces[@]}" ; do
+    state="$(storage_state "${w}")" ;
+    target="" ;
+    [ -L "${WORKSPACE_ROOT}/${w}" ] && target=" → $(readlink "${WORKSPACE_ROOT}/${w}")" ;
+    case "${state}" in
+      local)     printf '  %-16s local\n' "${w}" ;;
+      second)    printf '  %-16s second storage%s\n' "${w}" "${target}" ;;
+      elsewhere) printf '  %-16s ! linked elsewhere%s\n' "${w}" "${target}" ;;
+      broken)    printf '  %-16s ✗ broken link%s\n' "${w}" "${target}" ;;
+      missing)   printf '  %-16s (no folder)\n' "${w}" ;;
+    esac
+    if [ -d "${WORKSPACE_ROOT}/${w}.pre-move" ] ; then
+      size="$(storage_size_bytes "${WORKSPACE_ROOT}/${w}.pre-move")" ;
+      printf '  %-16s   %s.pre-move kept locally, %s (--remove-pre-move %s frees it)\n' "" "${w}" "$(storage_human "${size}")" "${w}" ;
+    fi
+  done
+  if [ -n "$(storage_mount_sources)" ] && [ ! -f "$(storage_compose_file)" ] ; then
+    echo "" ;
+    echo "  ! The dashboard does not mount the second storage yet: run --mounts." ;
+  fi
+  storage_fstab_hint ;
+}
+
+function storage_move() {
+  local w="$1" storage src dest size ;
+  storage="$(storage_path)" ; src="${WORKSPACE_ROOT}/${w}" ; dest="${storage}/${w}" ;
+  storage_is_workspace "${w}" || { echo "  ✗ ${w} is not a workspace in settings.yml." ; return 1 ; } ;
+  [ -n "${storage}" ] || { echo "  ✗ Set storage.second in settings.yml first." ; return 1 ; } ;
+  case "${storage}/" in "${WORKSPACE_ROOT}/"*) echo "  ✗ ${storage} is inside the workspace." ; return 1 ;; esac
+  storage_mounted || { echo "  ✗ ${storage} is not mounted on its own filesystem." ; return 1 ; } ;
+  [ -w "${storage}" ] || { echo "  ✗ ${storage} is not writable by $(id -un)." ; return 1 ; } ;
+  [ "$(storage_state "${w}")" == 'local' ] || { echo "  ✗ ${w} is not a local folder ($(storage_state "${w}"))." ; return 1 ; } ;
+  if storage_has_ddev "${src}" ; then
+    echo "  ✗ ${w} holds DDEV projects. DDEV bind-mounts each project into its containers, and that" ;
+    echo "    is not verified across a symlink onto another disk. Back them up or remove them first." ;
+    return 1 ;
+  fi
+  [ -e "${src}.pre-move" ] && { echo "  ✗ ${src}.pre-move already exists. Remove it or move it aside first." ; return 1 ; } ;
+  if [ -e "${dest}" ] && [ -n "$(ls -A "${dest}" 2>/dev/null)" ] ; then
+    echo "  ✗ ${dest} already holds files. Nothing on the second storage is overwritten." ; return 1 ;
+  fi
+  size="$(storage_size_bytes "${src}")" ;
+  if ! storage_has_room "${size}" "${storage}" ; then
+    echo "  ✗ Not enough room: ${w} is $(storage_human "${size}"), ${storage} has $(storage_human "$(storage_avail_bytes "${storage}")") free (5%, at least 1 GiB, is kept spare)." ;
+    return 1 ;
+  fi
+  echo "Moving ${w} ($(storage_human "${size}")) to ${dest}" ;
+  if [ "${DRY_RUN:-}" == 'yes' ] ; then echo "  dry run: nothing copied." ; return 0 ; fi
+  echo "  Nothing should write into ${w} until this finishes." ;
+  mkdir -p "${dest}" || return 1 ;
+  storage_copy_verified "${src}" "${dest}" || return 1 ;
+  mv "${src}" "${src}.pre-move" || return 1 ;
+  if ! ln -s "${dest}" "${src}" ; then
+    mv "${src}.pre-move" "${src}" ; echo "  ✗ Could not make the link; ${w} is back where it was." ; return 1 ;
+  fi
+  echo "  ✓ ${src} → ${dest}" ;
+  echo "  The original is kept as ${src}.pre-move. When you are happy, free it with:" ;
+  echo "      bash ${WORKSPACE_SCRIPTS}/storage.sh --remove-pre-move ${w}" ;
+}
+
+function storage_back() {
+  local w="$1" src target stage size ;
+  src="${WORKSPACE_ROOT}/${w}" ;
+  storage_is_workspace "${w}" || { echo "  ✗ ${w} is not a workspace in settings.yml." ; return 1 ; } ;
+  case "$(storage_state "${w}")" in
+    second|elsewhere) ;;
+    broken) echo "  ✗ ${w} links to $(readlink "${src}"), which is not there. Mount the drive first." ; return 1 ;;
+    *) echo "  ✗ ${w} is not on second storage." ; return 1 ;;
+  esac
+  target="$(readlink -f "${src}")" ;
+  # A kept pre-move copy is the cheapest place to start: rsync only sends what changed since.
+  stage="${src}.pre-move" ;
+  [ -d "${stage}" ] || stage="${WORKSPACE_ROOT}/.${w}.moving-back" ;
+  size="$(storage_size_bytes "${target}")" ;
+  if ! storage_has_room "${size}" "${WORKSPACE_ROOT}" ; then
+    echo "  ✗ Not enough room: ${w} is $(storage_human "${size}"), the workspace disk has $(storage_human "$(storage_avail_bytes "${WORKSPACE_ROOT}")") free." ;
+    return 1 ;
+  fi
+  echo "Moving ${w} ($(storage_human "${size}")) back from ${target}" ;
+  if [ "${DRY_RUN:-}" == 'yes' ] ; then echo "  dry run: nothing copied." ; return 0 ; fi
+  mkdir -p "${stage}" || return 1 ;
+  storage_copy_verified "${target}" "${stage}" || return 1 ;
+  unlink "${src}" || return 1 ;
+  if ! mv "${stage}" "${src}" ; then
+    ln -s "${target}" "${src}" ; echo "  ✗ Could not put the folder in place; the link is restored." ; return 1 ;
+  fi
+  echo "  ✓ ${src} is a local folder again." ;
+  echo "  The copy on the second storage is kept: ${target}" ;
+  echo "  Delete it by hand when you no longer want it; this tool never deletes on the drive." ;
+}
+
+function storage_remove_pre_move() {
+  local w="$1" kept="${WORKSPACE_ROOT}/$1.pre-move" ;
+  [ -d "${kept}" ] || { echo "  ✗ There is no ${kept}." ; return 1 ; } ;
+  case "$(storage_state "${w}")" in
+    second|elsewhere) ;;
+    *) echo "  ✗ ${w} is not a working link to second storage, so ${kept} may be the only copy. Kept." ; return 1 ;;
+  esac
+  [ -n "$(ls -A "${WORKSPACE_ROOT}/${w}/" 2>/dev/null)" ] || { echo "  ✗ ${w} on second storage is empty. Kept ${kept}." ; return 1 ; } ;
+  if [ "${DRY_RUN:-}" == 'yes' ] ; then echo "  dry run: would remove ${kept}." ; return 0 ; fi
+  rm -rf "${kept}" && echo "  ✓ removed ${kept}" ;
+}
+
+# Point links at the configured path when the same folder is there (the drive got a new mount point).
+function storage_relink() {
+  local storage w link target changed=0 ;
+  storage="$(storage_path)" ;
+  [ -n "${storage}" ] || { echo "  ✗ Set storage.second in settings.yml first." ; return 1 ; } ;
+  for w in "${workspaces[@]}" ; do
+    link="${WORKSPACE_ROOT}/${w}" ;
+    [ -L "${link}" ] || continue ;
+    target="$(readlink "${link}")" ;
+    [ "${target%/}" == "${storage}/${w}" ] && continue ;
+    if [ -d "${storage}/${w}" ] && [ -n "$(ls -A "${storage}/${w}" 2>/dev/null)" ] ; then
+      if [ "${DRY_RUN:-}" == 'yes' ] ; then
+        echo "  would relink ${w}: ${target} → ${storage}/${w}" ;
+      else
+        ln -sfn "${storage}/${w}" "${link}" && echo "  ✓ ${w}: ${target} → ${storage}/${w}" ;
+      fi
+      changed=$((changed+1)) ;
+    else
+      echo "  ! ${w} links to ${target}; ${storage}/${w} is not there, so it is left alone." ;
+    fi
+  done
+  [ "${changed}" -gt 0 ] || storage_say "  ✓ every link already points at ${storage}" ;
+}