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

package/core/scripts/plugins.sh

@@ -0,0 +1,152 @@
+#!/usr/bin/env bash
+## Plugins of the Webship Workspace dashboard: require, activate, install, configure.
+##
+##   bash core/scripts/plugins.sh --list                       what is installed, activated, placed
+##   bash core/scripts/plugins.sh --require <npm spec>         npm install into the dashboard
+##                                                             (github:webship/workspace-upsun, a tarball, a path)
+##   bash core/scripts/plugins.sh --activate <name>            plugins.<name>.enabled: true in settings.yml
+##   bash core/scripts/plugins.sh --install <name>             place what its manifest names in the workspace
+##   bash core/scripts/plugins.sh --configure <name>           its own settings file, created from the template
+##   bash core/scripts/plugins.sh --deactivate <name>          enabled: false (the files stay)
+##   bash core/scripts/plugins.sh --uninstall <name>           remove what --install placed
+##   bash core/scripts/plugins.sh --restart                    restart the dashboard app, so it loads the change
+##
+## A plugin is a node package with a `workspacePlugin` manifest in its package.json, kept in its
+## own repository (github.com/webship/workspace-<name>). The four steps are what it takes to turn a
+## feature on; --list shows which step a plugin is at. --install is idempotent and says when the
+## dashboard container needs `ddev restart` (a compose file or host mount it brought).
+
+set -u
+WORKSPACE_SCRIPTS="${WORKSPACE_SCRIPTS:-$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)}";
+WORKSPACE_ROOT="${WORKSPACE_ROOT:-$(cd "${WORKSPACE_SCRIPTS}/../.." && pwd)}";
+# The dashboard app lives beside these scripts (not necessarily under WORKSPACE_ROOT: a test points the
+# root at a temporary tree while the code stays here).
+APP="$(cd "${WORKSPACE_SCRIPTS}/../workspace-app" && pwd)";
+SETTINGS="${WORKSPACE_ROOT}/core/config/settings.yml";
+
+usage() { sed -n '2,20p' "${BASH_SOURCE[0]}" | sed 's/^## \{0,1\}//'; }
+
+# Inside the dashboard container the app runs supervised; on the host there is nothing to restart but
+# the container's process, reached through docker.
+restart_app() {
+  # A test drives these verbs against a temporary tree; it must never restart the dashboard that serves.
+  [ -n "${WORKSPACE_PLUGINS_NO_RESTART:-}" ] && return 0 ;
+  if command -v supervisorctl > /dev/null 2>&1 && supervisorctl status webextradaemons:workspace-app > /dev/null 2>&1 ; then
+    supervisorctl restart webextradaemons:workspace-app ;
+  elif command -v docker > /dev/null 2>&1 ; then
+    docker exec ddev-workspace-web supervisorctl restart webextradaemons:workspace-app 2>/dev/null \
+      || echo "The dashboard is not running; it will load the change when it starts." ;
+  fi
+}
+
+# One settings.yml edit, through the same code the Settings page uses, so comments survive.
+set_plugin_setting() {
+  local name="$1" key="$2" value="$3" ;
+  ( cd "${APP}" && node -e '
+    const [name, key, value] = process.argv.slice(1);
+    const { upsertSettingsValue } = require("./settings-file");
+    upsertSettingsValue("settings.yml", `plugins.${name}.${key}`, value === "true" ? true : value === "false" ? false : value);
+  ' "${name}" "${key}" "${value}" ) ;
+}
+
+plugin_module() { ( cd "${APP}" && node plugin-manifest.js --json "$1" 2>/dev/null | node -e 'let s="";process.stdin.on("data",d=>s+=d).on("end",()=>{const p=JSON.parse(s||"null");process.stdout.write(p&&p.module?p.module:"")})' ) ; }
+plugin_known()  { ( cd "${APP}" && node plugin-manifest.js "$1" > /dev/null 2>&1 ) ; }
+# A plugin that IS a workspace folder names it in its manifest (workspace.key); activating it puts the
+# key on settings.yml's workspaces list (the dashboard's order), deactivating takes it off.
+plugin_workspace_key() { ( cd "${APP}" && node plugin-manifest.js --json "$1" 2>/dev/null | node -e 'let s="";process.stdin.on("data",d=>s+=d).on("end",()=>{const p=JSON.parse(s||"null");const w=p&&p.manifest&&p.manifest.workspace;process.stdout.write(w&&w.key?String(w.key):"")})' ) ; }
+set_workspaces_list() {
+  local verb="$1" key="$2" ;
+  [ -n "${key}" ] || return 0 ;
+  ( cd "${APP}" && node -e '
+    const [verb, key] = process.argv.slice(1);
+    const { upsertSettingsList } = require("./settings-file");
+    const { loadSettings } = require("./workspaces");
+    const now = (loadSettings().workspaces || []).map(String);
+    const next = verb === "add" ? (now.includes(key) ? now : [...now, key]) : now.filter((k) => k !== key);
+    if (next.join(",") !== now.join(",")) upsertSettingsList("settings.yml", "workspaces", next);
+    process.stdout.write(verb === "add" ? (now.includes(key) ? "" : `Workspace ${key} added to the workspaces list.\n`) : (now.includes(key) ? `Workspace ${key} taken off the workspaces list (the folder and its settings stay).\n` : ""));
+  ' "${verb}" "${key}" ) ;
+}
+
+verb="${1:-}"; name="${2:-}";
+case "${verb}" in
+  -h|--help|'') usage ; exit 0 ;;
+
+  --list)
+    echo "Plugins the dashboard can see (core/workspace-app), and the step each is at:" ;
+    ( cd "${APP}" && node -e '
+      const { rows, STEPS } = require("./plugins-page");
+      for (const p of rows()) {
+        const step = p.step >= 3 ? "ready" : `${STEPS[p.step]} · next: ${["activate", "install", "configure"][p.step]}`;
+        const missing = p.placed.missing && p.placed.missing.length ? ` (missing ${p.placed.missing.length} placed file(s): --install again)` : "";
+        console.log(`  ${p.name.padEnd(18)} ${(p.module || p.spec || "-").padEnd(36)} ${(p.version || "").padEnd(8)} ${step}${missing}`);
+      }
+    ' ) ;;
+
+  --require)
+    [ -n "${name}" ] || { echo "Which package? e.g. --require github:webship/workspace-upsun" ; exit 1 ; } ;
+    echo "→ npm install ${name} (core/workspace-app)" ;
+    # The plugin repositories are private: let git borrow the gh CLI's login for github.com, the way
+    # the commands tooling does, so a github: spec resolves without a token in the environment.
+    if command -v gh > /dev/null 2>&1 && gh api user --jq .login > /dev/null 2>&1 ; then
+      export GIT_CONFIG_COUNT=1 GIT_CONFIG_KEY_0="credential.https://github.com.helper" GIT_CONFIG_VALUE_0="!gh auth git-credential" ;
+    fi
+    ( cd "${APP}" && npm install --no-audit --no-fund "${name}" ) || exit 1 ;
+    echo "Required. Next: --activate <name> (the name is the manifest's: --list shows it)." ;;
+
+  --activate)
+    [ -n "${name}" ] || { echo "Which plugin? --list shows them." ; exit 1 ; } ;
+    plugin_known "${name}" || { echo "No plugin named '${name}' is installed in the dashboard. --require it first." ; exit 1 ; } ;
+    module="$(plugin_module "${name}")" ;
+    set_plugin_setting "${name}" enabled true ;
+    [ -n "${module}" ] && set_plugin_setting "${name}" module "${module}" ;
+    set_workspaces_list add "$(plugin_workspace_key "${name}")" ;
+    echo "Activated: plugins.${name} in core/config/settings.yml. Next: --install ${name}." ;;
+
+  --deactivate)
+    [ -n "${name}" ] || { echo "Which plugin?" ; exit 1 ; } ;
+    set_plugin_setting "${name}" enabled false ;
+    set_workspaces_list remove "$(plugin_workspace_key "${name}")" ;
+    echo "Deactivated: plugins.${name}.enabled: false. Its files stay; --uninstall removes them." ;
+    restart_app ;;
+
+  --install)
+    [ -n "${name}" ] || { echo "Which plugin? --list shows them." ; exit 1 ; } ;
+    out="$( cd "${APP}" && node plugin-install.js install "${name}" )" || { echo "${out}" ; exit 1 ; } ;
+    echo "${out}" | grep -v '^RESTART_' ;
+    host="${WORKSPACE_SCRIPTS}/plugins/${name}/host-install.sh" ;
+    if [ -f "${host}" ] ; then
+      echo "→ the host side (${name}):" ;
+      bash "${host}" --check || true ;
+    fi
+    if echo "${out}" | grep -q '^RESTART_NEEDED' ; then
+      echo "" ;
+      echo "The dashboard container needs a restart for the compose file or host mount this plugin brought:" ;
+      echo "  cd ${APP} && ddev restart" ;
+    else
+      restart_app ;
+    fi
+    echo "Installed. Next: --configure ${name}." ;;
+
+  --uninstall)
+    [ -n "${name}" ] || { echo "Which plugin?" ; exit 1 ; } ;
+    ( cd "${APP}" && node plugin-install.js uninstall "${name}" ) | grep -v '^RESTART_' ;
+    set_plugin_setting "${name}" enabled false ;
+    echo "Uninstalled and deactivated. The package stays in node_modules: npm uninstall <module> in core/workspace-app removes it." ;
+    restart_app ;;
+
+  --configure)
+    [ -n "${name}" ] || { echo "Which plugin?" ; exit 1 ; } ;
+    file="$( cd "${APP}" && node -e 'const p=require("./plugin-manifest").pluginByName(process.argv[1]);process.stdout.write(p&&p.manifest.settingsFile?p.manifest.settingsFile:"")' "${name}" )" ;
+    [ -n "${file}" ] || { echo "${name} has no settings file of its own." ; exit 0 ; } ;
+    if [ ! -f "${WORKSPACE_ROOT}/core/config/${file}" ] ; then
+      ( cd "${APP}" && node plugin-install.js install "${name}" > /dev/null ) ;
+    fi
+    echo "Its settings: ${WORKSPACE_ROOT}/core/config/${file}" ;
+    echo "Edit it there, or on the dashboard: https://workspace.ddev.site/settings/${file}" ;
+    sed 's/^\(.*token.*:\).*/\1 <hidden>/' "${WORKSPACE_ROOT}/core/config/${file}" ;;
+
+  --restart) restart_app ;;
+
+  *) usage ; exit 1 ;;
+esac

package/core/scripts/release.sh

@@ -0,0 +1,69 @@
+#!/usr/bin/env bash
+
+# Cut the next release of this tooling: stamp the version, tag the branch, publish
+# the release. The stamp is written BEFORE the tag, so a machine can never be on a
+# release while still reporting the one before it.
+#
+# Confirm-gated: without --confirm it prints the plan and creates nothing. A tag
+# and a release page are public and permanent, and neither should be a side effect
+# of asking what would happen.
+
+# 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 ;
+
+ARGPARSE_DESCRIPTION="Release the next tag of this tooling (stamps the version first)"
+source ${WORKSPACE_SCRIPTS}/args/arg-release.sh || exit 1 ;
+
+shift $#;
+
+CLONE="${WORKSPACE_ROOT}/products/workspace"
+REMOTE='github'
+
+if [ ! -d "${CLONE}/.git" ]; then
+  echo "No clone at ${CLONE}. Releases are cut from the git checkout, not from the live tree." >&2
+  exit 1
+fi
+
+REPO="$(release_repo)" || exit 1
+
+echo "Checking the clone…"
+release_ready "${CLONE}" "${BRANCH}" "${REMOTE}" || READY=1
+
+CURRENT="$(release_current_tag "${CLONE}")"
+if [ -n "${TAG}" ]; then
+  NEXT="${TAG}"
+else
+  NEXT="$(release_next_tag "${CURRENT}")"
+  if [ -z "${NEXT}" ]; then
+    echo "Cannot work out the next tag from '${CURRENT:-none}'. Name one with --tag." >&2
+    exit 1
+  fi
+fi
+
+if git -C "${CLONE}" rev-parse -q --verify "refs/tags/${NEXT}" > /dev/null 2>&1 ; then
+  echo "${NEXT} already exists. A released tag is never moved." >&2
+  exit 1
+fi
+
+release_plan "${CLONE}" "${BRANCH}" "${CURRENT}" "${NEXT}" "${REPO}"
+
+if [ "${NO_GATE}" != 'yes' ]; then
+  release_gate "${CLONE}" || GATED=1
+else
+  echo "Gate skipped (--no-gate)."
+fi
+
+if [ "${CONFIRM}" != 'yes' ]; then
+  echo "Nothing was created. Add --confirm to cut ${NEXT}."
+  exit 0
+fi
+
+if [ -n "${READY}" ] || [ -n "${GATED}" ]; then
+  echo "" >&2
+  echo "Refusing to release: the checks above did not pass." >&2
+  exit 1
+fi
+
+release_cut "${CLONE}" "${BRANCH}" "${NEXT}" "${REPO}" "${NOTES}" "${REMOTE}"

package/core/scripts/storage.sh

@@ -0,0 +1,39 @@
+#!/usr/bin/env bash
+
+# Keep whole workspace folders on a second disk: storage.second in settings.yml.
+# A moved workspace is a symlink, <root>/<name> -> <storage>/<name>, so nothing else changes.
+#
+#   bash core/scripts/storage.sh                      status (the default)
+#   bash core/scripts/storage.sh --move videos        copy, verify, swap to a symlink
+#   bash core/scripts/storage.sh --remove-pre-move videos
+#   bash core/scripts/storage.sh --back videos        the reverse
+#   bash core/scripts/storage.sh --mounts             the dashboard container's mounts
+#   bash core/scripts/storage.sh --relink --mounts    after the drive got a new mount point
+
+# 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 ;
+
+
+ARGPARSE_DESCRIPTION="Keep workspace folders on a second disk (storage.second in settings.yml)"
+source ${WORKSPACE_SCRIPTS}/args/arg-storage.sh || exit 1 ;
+
+shift $#;
+
+status=0 ;
+[ -n "${MOVE}" ] && { storage_move "${MOVE}" || exit 1 ; } ;
+[ -n "${BACK}" ] && { storage_back "${BACK}" || exit 1 ; } ;
+[ -n "${REMOVE_PRE_MOVE}" ] && { storage_remove_pre_move "${REMOVE_PRE_MOVE}" || status=1 ; } ;
+[ "${RELINK}" == 'yes' ] && { storage_relink || status=1 ; } ;
+# A move or a relink changes what the dashboard has to mount, so --mounts runs last.
+if [ "${MOUNTS}" == 'yes' ] && [ "${DRY_RUN}" != 'yes' ] ; then
+  storage_write_mounts || status=1 ;
+elif [ -n "${MOVE}${BACK}" ] && [ "${DRY_RUN}" != 'yes' ] && [ "$(storage_compose)" != "$(cat "$(storage_compose_file)" 2>/dev/null)" ] ; then
+  echo "" ;
+  echo "  ! The dashboard's mounts no longer match. Run: bash ${WORKSPACE_SCRIPTS}/storage.sh --mounts" ;
+fi
+if [ "${STATUS}" == 'yes' ] || [ -z "${MOVE}${BACK}${REMOVE_PRE_MOVE}${RELINK}${MOUNTS}" ] ; then
+  storage_status ;
+fi
+exit ${status} ;

package/core/scripts/sync-tooling.sh

@@ -0,0 +1,246 @@
+#!/usr/bin/env bash
+
+# Copy the tooling from the Webship Workspace git clone into the live workspace
+# it is checked out inside — the step that follows every merged PR.
+#
+#   ~/workspace/products/workspace   the clone: where commits and PRs happen
+#   ~/workspace                      the live tree: where projects are built
+#
+# It syncs the shared core/, each workspace folder's cmd-*.sh, README.md and
+# *.code-workspace, and prunes commands the clone no longer ships. Built
+# project content is never touched.
+#
+# core/config/settings.yml is DELIBERATELY not synced: the live copy holds the
+# real account password and API keys, while the committed one ships CHANGE_ME
+# and sk-change-this placeholders. Only the `workspaces:` list is reconciled,
+# and only by reporting what is missing.
+
+# 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 ;
+
+
+ARGPARSE_DESCRIPTION="Sync the workspace tooling from the git clone into the live workspace"
+argparse "$@" <<EOF || exit 1
+parser.add_argument('CLONE_NAME',
+                    default='workspace',
+                    nargs='?',
+                    help='The clone directory inside the products workspace [default %(default)s].')
+parser.add_argument('-p', '--pull',
+                    action='store_true',
+                    default=False,
+                    help='git pull the clone first (fast-forward only), so a merged PR is picked up.')
+parser.add_argument('-n', '--dry-run',
+                    action='store_true',
+                    default=False,
+                    help='Show what would change and copy nothing.')
+parser.add_argument('-s', '--skip-tests',
+                    action='store_true',
+                    default=False,
+                    help='Skip the smoke test that normally runs after the sync.')
+EOF
+
+shift $#;
+
+# The clone lives in the products workspace: it is a Webship product like any other.
+source_root="${WORKSPACE_ROOT}/products/${CLONE_NAME}";
+# Where this script itself is, so the prune below cannot delete the file it is running from.
+self_path="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/$(basename "${BASH_SOURCE[0]}")";
+target_root="${WORKSPACE_ROOT}";
+
+if [ ! -d "${source_root}/core/scripts" ]; then
+  echo "No workspace clone at ${source_root}.";
+  echo "Expected the git checkout of webship/workspace there.";
+  exit 1 ;
+fi
+
+if [ "${source_root}" == "${target_root}" ]; then
+  echo "The clone and the live workspace are the same directory — nothing to sync.";
+  exit 1 ;
+fi
+
+rsync_flags="-a";
+if [ "${DRY_RUN}" == 'yes' ] ; then
+  rsync_flags="-a --dry-run --itemize-changes";
+  echo "DRY RUN — nothing will be written.";
+fi
+
+echo "*---------------------------------------------------------------------*";
+echo "  Sync tooling";
+echo "    from ${source_root}";
+echo "      to ${target_root}";
+echo "*---------------------------------------------------------------------*";
+
+if [ "${PULL}" == 'yes' ] ; then
+  echo "";
+  echo "Updating the clone…";
+  (cd "${source_root}" && git pull --ff-only) || {
+    echo "git pull failed — resolve the clone's state first, then re-run.";
+    exit 1 ;
+  }
+fi
+
+echo "";
+echo "Clone is at: $(cd "${source_root}" && git log --oneline -1 2>/dev/null || echo 'not a git checkout')";
+
+# Shared scripts: mirrored, so a deleted function or arg file disappears here too.
+echo "";
+echo "→ core/scripts";
+rsync ${rsync_flags} --delete "${source_root}/core/scripts/" "${target_root}/core/scripts/" ;
+
+# Per-workspace settings only. settings.yml stays local: it holds real secrets.
+echo "→ core/config/workspace.*.settings.yml";
+rsync ${rsync_flags} "${source_root}"/core/config/workspace.*.settings.yml "${target_root}/core/config/" ;
+
+# The dashboard, minus what belongs to the running instance.
+echo "→ core/workspace-app";
+rsync ${rsync_flags} --exclude=node_modules --exclude=actions.log --exclude=logs --exclude=.chats --exclude=.memory --exclude=.voice-cache --exclude=.auth \
+  "${source_root}/core/workspace-app/" "${target_root}/core/workspace-app/" ;
+
+# Each workspace folder's commands and docs — never its built projects.
+# AGENTS.md and CLAUDE.md come across too: they are what a Claude Code session
+# started anywhere under a workspace reads to find its context and its rules.
+echo "→ <workspace>/cmd-*.sh, README.md, AGENTS.md, CLAUDE.md, *.code-workspace";
+for workspace_dir in "${source_root}"/*/ ; do
+  workspace_name=$(basename "${workspace_dir}");
+  # A workspace on second storage whose drive is not mounted: writing through the dangling link would
+  # recreate its folder under the mount point, on the wrong disk. Skip it and say so.
+  if [ -L "${target_root}/${workspace_name}" ] && [ ! -d "${target_root}/${workspace_name}" ] ; then
+    echo "   skipped ${workspace_name}: it links to $(readlink "${target_root}/${workspace_name}"), which is not mounted" ;
+    continue ;
+  fi
+  [ -d "${target_root}/${workspace_name}" ] || mkdir -p "${target_root}/${workspace_name}" ;
+  # scripts/ carries the assets a builder copies into a project. It is empty for
+  # the site templates now that the front-end libraries come from Composer, but
+  # the include stays: a builder that needs to ship an asset again should not
+  # have to rediscover why the file never reached the live tree.
+  rsync ${rsync_flags} --include='cmd-*.sh' --include='README.md' --include='AGENTS.md' \
+    --include='CLAUDE.md' --include='*.code-workspace' \
+    --include='scripts/' --include='scripts/**' \
+    --exclude='*' "${workspace_dir}" "${target_root}/${workspace_name}/" ;
+done
+
+# The specs workspace is the one whose CONTENT is the deliverable rather than its commands: the
+# templates every spec starts from, and the constitution of each product. Those are committed, so
+# a --pull that skipped them left a machine with the command and none of the material it reads —
+# `-a constitution` would answer "no template", on a tree that has one in the repository.
+#
+# Only the two shared kinds. A numbered spec is about one change in one tree and belongs to
+# whoever is making it.
+if [ -d "${source_root}/specs" ] ; then
+  echo "→ specs/_defaults and every 00-constitution.md";
+  rsync ${rsync_flags} --include='_defaults/' --include='_defaults/**' \
+    --include='*/' --include='00-constitution.md' \
+    --exclude='*' "${source_root}/specs/" "${target_root}/specs/" ;
+fi
+
+# core/workspace-app was just mirrored, and two files in it carry THIS machine's docker
+# GID — the Dockerfile's group and the compose group_add. The clone cannot know that
+# number, so a pull would leave the dashboard unable to reach Docker: every project
+# Stopped, no Start/Stop item, and nothing to suggest a permissions problem. Re-align
+# it here, where the overwrite happened.
+if [ -f "${WORKSPACE_SCRIPTS}/docker-gid.sh" ] && [ "${DRY_RUN}" != 'yes' ] ; then
+  echo "";
+  echo "→ the dashboard's Docker access";
+  bash "${WORKSPACE_SCRIPTS}/docker-gid.sh" || true ;
+fi
+
+# The same for the second storage: the mounts that let the dashboard follow a workspace symlink onto
+# another disk are this machine's paths, generated from storage.second. Rewritten only when they differ.
+if [ -f "${WORKSPACE_SCRIPTS}/storage.sh" ] && [ "${DRY_RUN}" != 'yes' ] ; then
+  bash "${WORKSPACE_SCRIPTS}/storage.sh" --mounts --quiet || true ;
+fi
+
+# The tree's own root CLAUDE.md — the file that tells a session how to work out which
+# workspace it is in. Placed only when missing: it is a live-tree file, and
+# overwriting it would discard whatever this machine has added.
+if [ ! -f "${target_root}/CLAUDE.md" ] && [ -f "${source_root}/core/templates/workspace-root-CLAUDE.md" ] ; then
+  cp "${source_root}/core/templates/workspace-root-CLAUDE.md" "${target_root}/CLAUDE.md" ;
+  echo "   placed ${target_root}/CLAUDE.md from the template (it was missing)" ;
+fi
+
+# Commands the clone dropped (a removed builder, a renamed tool).
+echo "";
+echo "→ pruning commands the clone no longer ships";
+pruned=0;
+cd "${target_root}";
+for command_file in */cmd-*.sh ; do
+  [ -f "${command_file}" ] || continue ;
+  # Never delete the script performing the sync. This is not hypothetical: the release
+  # that moved autostart, brand-tokens and sync-tooling into core/scripts is pulled BY
+  # the old products/cmd-tools-sync-tooling.sh, which the clone no longer ships — and
+  # bash reads a script as it executes, so removing it mid-run can truncate the rest.
+  if [ "$(cd "$(dirname "${command_file}")" && pwd)/$(basename "${command_file}")" == "${self_path}" ] ; then
+    echo "   keeping ${command_file} — it is running this sync. Delete it by hand, then use";
+    echo "   core/scripts/$(basename "${command_file}" | sed 's/^cmd-tools-//') from now on.";
+    continue ;
+  fi
+  if [ ! -f "${source_root}/${command_file}" ]; then
+    if [ "${DRY_RUN}" == 'yes' ] ; then
+      echo "   would remove ${command_file}";
+    else
+      rm -f "${command_file}";
+    fi
+    pruned=$((pruned+1));
+  fi
+done
+echo "   ${pruned} stale command(s)";
+
+# settings.yml is not copied, so a workspace added in the clone would be
+# invisible here. Report it rather than editing a file with real secrets.
+echo "";
+echo "→ checking the workspaces: list";
+missing_workspaces="";
+for workspace_name in $(grep -A100 '^workspaces:' "${source_root}/core/config/settings.yml" | grep '^  - ' | sed 's/^  - //') ; do
+  if ! grep -q "^  - ${workspace_name}$" "${target_root}/core/config/settings.yml" ; then
+    missing_workspaces="${missing_workspaces} ${workspace_name}";
+  fi
+done
+if [ -n "${missing_workspaces}" ]; then
+  echo "   MISSING from your ${target_root}/core/config/settings.yml:${missing_workspaces}";
+  echo "   Add them to its workspaces: list — it is not synced because it holds your real";
+  echo "   account password and API keys. The list order is the dashboard card order.";
+else
+  echo "   up to date";
+fi
+
+if [ "${DRY_RUN}" == 'yes' ] ; then
+  echo "";
+  echo "DRY RUN — nothing was written.";
+  exit 0 ;
+fi
+
+echo "";
+  # Stamp the version this pull brought in. The clone IS a checkout, so the tag it sits on
+  # is the honest answer — and without this a machine that keeps up to date via the clone
+  # reports "(untracked)" to update.sh for ever and is told to update to what it already has.
+  if command -v workspace_clone_version > /dev/null 2>&1 ; then
+    sync_tag="$(workspace_clone_version "${source_root}")" ;
+    if [ -n "${sync_tag}" ] ; then
+      WORKSPACE_PATH="${target_root}/core" workspace_version_stamp "${sync_tag}" \
+        && echo "→ recorded this tree as ${sync_tag}" ;
+    else
+      echo "→ the clone is on no tag, so the version is not recorded" ;
+    fi
+  fi
+
+if [ ! "${SKIP_TESTS}" == 'yes' ] ; then
+  echo "";
+  echo "→ smoke test";
+  (cd "${target_root}" && bash core/scripts/tests/cmd-smoke-test.sh 2>&1 | tail -3) ;
+fi
+
+echo "";
+echo "*---------------------------------------------------------------------*";
+echo "  Synced.";
+echo "";
+echo "  If core/workspace-app/.ddev/ or its Dockerfile changed, rebuild the";
+echo "  dashboard container so it picks that up — when no build jobs are";
+echo "  running, because the job registry is in memory:";
+echo "    cd ${target_root}/core/workspace-app && ddev restart";
+echo "";
+echo "  For a change to server.js or workspaces.js alone, restarting the app";
+echo "  is enough (supervisord respawns it):";
+echo "    docker exec ddev-workspace-web sh -c 'pkill -f \"node server.js\"'";
+echo "*---------------------------------------------------------------------*";

package/core/scripts/tests/cmd-smoke-test.sh

@@ -0,0 +1,109 @@
+#!/usr/bin/env bash
+# Smoke-test every cmd-*.sh in every workspace folder, plus the machine-level scripts
+# in core/scripts that used to be cmd-*.sh in one.
+#
+# For each script:
+#  1. bash -n            — syntax check (always)
+#  2. --help execution   — only for argparse-based scripts (safe: argparse
+#                          prints usage and exits before any real work),
+#                          which exercises bootstrap.sh, parse_yaml, the
+#                          workspace + distribution configs and arg-*.sh
+#  3. workspace-name     — builder scripts must carry the "# workspace-name:"
+#                          header the dashboard shows in Build dropdowns
+#
+# Exit code: number of failing scripts (0 = all green).
+
+# 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
+
+pass=0; fail=0; failures=()
+
+# The registered workspaces, plus commands/ — which is a Settings section rather than
+# a workspace, but still ships a cmd-*.sh that must pass the same checks. Without it
+# here, deregistering that folder silently dropped its script from the run.
+# The machine-level scripts: autostart.sh and sync-tooling.sh were
+# cmd-*.sh in products/ until they moved here, and moving a script out of a workspace
+# folder must not quietly drop it from the run — that happened once already, to
+# commands/. Named explicitly rather than globbed, because core/scripts is also full
+# of libraries and bootstrap files that are sourced, never run. So every NEW machine
+# script has to be added here by hand — host-mounts.sh and upsun-ai.sh had been
+# sitting in core/scripts untested because that step was missed.
+MACHINE_SCRIPTS=(autostart.sh sync-tooling.sh install.sh trust-https.sh docker-gid.sh host-mounts.sh storage.sh plugins.sh)
+
+for ws in "${workspaces[@]}" commands core/scripts; do
+  dir="${WORKSPACE_ROOT}/${ws}"
+  [ -d "$dir" ] || continue
+  if [ "$ws" == 'core/scripts' ] ; then
+    scripts=()
+    for name in "${MACHINE_SCRIPTS[@]}"; do
+      [ -f "${dir}/${name}" ] && scripts+=("${dir}/${name}")
+    done
+  else
+    scripts=("$dir"/cmd-*.sh)
+  fi
+  for f in "${scripts[@]}"; do
+    [ -f "$f" ] || continue
+    rel="${ws}/$(basename "$f")"
+    err=""
+
+    # 1. Syntax
+    if ! bash -n "$f" 2>/tmp/cmd-smoke-err; then
+      err="syntax: $(head -1 /tmp/cmd-smoke-err)"
+    fi
+
+    # 2. argparse scripts: run --help (safe, exercises the full bootstrap chain)
+    if [ -z "$err" ] && grep -q 'argparse "\$@"\|arg-${distribution_name}\|arg-\${distribution_name}\|--help)' "$f"; then
+      if ! (cd "$dir" && timeout 30 bash "$f" --help >/tmp/cmd-smoke-out 2>&1); then
+        # argparse exits non-zero on --help in some versions; accept if usage was printed
+        if ! grep -qi "usage" /tmp/cmd-smoke-out; then
+          err="--help: $(tail -1 /tmp/cmd-smoke-out | cut -c1-120)"
+        fi
+      fi
+    fi
+
+    # 3. The function the script ends by calling must actually EXIST after bootstrap.
+    #    `--help` returns before that line, so a script whose function file was never added to
+    #    bootstrap-functions.sh passes every check above and then dies with "command not found"
+    #    the first time it is run for real. That is how sixteen site-template builders shipped.
+    if [ -z "$err" ]; then
+      for fn in $(grep -oE '^[a-z_][a-z0-9_]* ;$' "$f" | tr -d ' ;' | sort -u); do
+        # A machine script may define the function it ends by calling, in itself.
+        grep -qE "^(function )?${fn}\(\)" "$f" && continue
+        if ! (cd "$dir" && bash -c 'source "$1" >/dev/null 2>&1; declare -F "$2" >/dev/null' \
+                _ "${WORKSPACE_SCRIPTS}/bootstrap.sh" "$fn") ; then
+          err="calls ${fn}() but nothing defines it — is its file sourced in bootstrap-functions.sh?"
+          break
+        fi
+      done
+    fi
+
+    # 4. Builder scripts must have the human-readable name header.
+    #    A builder is cmd-<distribution><version>-project.sh. cmd-tool-*/cmd-tools-* are the
+    #    workspace's own tools — projects/cmd-tool-backup-project.sh ends in -project.sh too,
+    #    and is not a builder.
+    if [ -z "$err" ] && [[ "$(basename "$f")" == cmd-*-project.sh ]] \
+       && [[ "$(basename "$f")" != cmd-tool-* ]] && [[ "$(basename "$f")" != cmd-tools-* ]] \
+       && [[ "$(basename "$f")" != cmd-automated-testing-* ]] && [[ "$(basename "$f")" != cmd-bulk-* ]]; then
+      if ! grep -q "^# workspace-name:" "$f"; then
+        err="missing '# workspace-name:' header"
+      fi
+    fi
+
+    if [ -z "$err" ]; then
+      pass=$((pass+1))
+      printf "PASS  %s\n" "$rel"
+    else
+      fail=$((fail+1))
+      failures+=("$rel — $err")
+      printf "FAIL  %s — %s\n" "$rel" "$err"
+    fi
+  done
+done
+
+echo
+echo "=================================================="
+echo " cmd- smoke test: ${pass} passed, ${fail} failed"
+echo "=================================================="
+for f in "${failures[@]}"; do echo " ✗ $f"; done
+exit $fail