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

package/core/scripts/plugins/upsun/functions/fun-upsun.sh

@@ -0,0 +1,304 @@
+#!/usr/bin/env bash
+
+# Upsun (https://upsun.com) is where workspace projects run in the cloud —
+# client demos, sandboxes, the public Webship demo. A project links to Upsun
+# through `upsun project:set-remote <id>`, which writes .upsun/local/project.yaml
+# and adds an `upsun` git remote; deploys are `upsun push`.
+#
+# These functions are the local ⇄ cloud bridge for one project directory.
+# Everything defaults to read-only; the mutating verbs (--link, --init, --push)
+# each demand an explicit flag, and nothing here ever creates or deletes an
+# Upsun project or environment.
+
+# Make sure the upsun CLI is available. It is installed system-wide or per
+# https://docs.upsun.com/administration/cli.html — not something to install
+# silently, since it immediately carries the user's cloud credentials.
+function ensure_upsun() {
+  if command -v upsun > /dev/null 2>&1 ; then
+    return 0 ;
+  fi
+  echo "The upsun CLI is not installed. Install it first:" ;
+  echo "  curl -fsSL https://raw.githubusercontent.com/upsun/cli/main/installer.sh | bash" ;
+  echo "  (or: brew install upsun/tap/upsun-cli)" ;
+  echo "then authenticate with: upsun auth:browser-login" ;
+  echo "For CI: set an API token and UPSUN_CLI_NO_INTERACTION=1 instead." ;
+  return 1 ;
+}
+
+# The Upsun project ID a directory is linked to, if any.
+function upsun_linked_id() {
+  local link_file="$1/.upsun/local/project.yaml";
+  if [ -f "${link_file}" ]; then
+    grep '^id:' "${link_file}" | awk '{print $2}' ;
+  fi
+}
+
+# The environment (branch) a project's local tooling works against.
+#
+# Kept in .upsun/local/, which the CLI's own README calls its local-only directory and which
+# `upsun project:set-remote` already excluded from git via .git/info/exclude — so remembering a
+# branch dirties no repository, and a project that is cloned fresh simply has no selection yet.
+UPSUN_ENV_FILE=".upsun/local/workspace-environment";
+
+function upsun_selected_env() {
+  local file="$1/${UPSUN_ENV_FILE}";
+  [ -f "${file}" ] && head -1 "${file}" | tr -d '[:space:]' ;
+}
+
+function upsun_select_env() {
+  local project_path="$1" env="$2";
+  mkdir -p "${project_path}/.upsun/local" ;
+  printf '%s\n' "${env}" > "${project_path}/${UPSUN_ENV_FILE}" ;
+}
+
+# Which environment a run acts on: --environment for this run, else the remembered selection,
+# else nothing (the caller decides whether that is fatal). Deliberately NOT defaulting to
+# `main`: pulling production data because nobody said otherwise is exactly the accident worth
+# preventing.
+function upsun_target_env() {
+  local project_path="$1";
+  if [ ! "${ENVIRONMENT}" == '_none_' ] ; then printf '%s' "${ENVIRONMENT}"; return 0 ; fi
+  upsun_selected_env "${project_path}";
+}
+
+# Where this project serves from — Drupal's two conventions, plus the flat case.
+function upsun_docroot() {
+  local project_path="$1";
+  for candidate in web docroot ; do
+    [ -d "${project_path}/${candidate}" ] && { printf '%s' "${candidate}"; return 0 ; }
+  done
+  printf '%s' "";
+}
+
+# Pull the database of one environment into the local DDEV project.
+#
+# Read-only in the cloud and destructive locally, which is the opposite way round from the rest of
+# this file: the local database is REPLACED. So the local one is exported first, unconditionally,
+# and the run says where that copy went before it starts.
+function upsun_pull_db() {
+  local project_path="$1" linked_id="$2" env="$3";
+  local stamp out dump safety;
+
+  stamp="$(date +%Y-%m-%d-%H%M%S)";
+  out="${backups}/${doc_name}/${PROJECT_NAME}";
+  mkdir -p "${out}" ;
+  dump="${out}/${PROJECT_NAME}-upsun-${env}-${stamp}.sql.gz";
+  safety="${out}/${PROJECT_NAME}-before-upsun-pull-${stamp}.sql.gz";
+
+  echo "";
+  echo "Pulling the ${env} database of Upsun project ${linked_id}.";
+  echo "  This is client data: it lands on this machine and in ${out}.";
+  echo "  Sanitize it before sharing — see the drupal-thin-db-export skill.";
+  echo "";
+
+  # The local database is replaced, so it is exported first. A pull that ate an afternoon's work
+  # because nobody thought to dump it is a bad pull.
+  if [ "${NO_SAFETY_BACKUP:-no}" == 'yes' ] ; then
+    echo "Skipping the local database export, as asked. The current local data will be lost.";
+  else
+    echo "Exporting the current local database first.";
+    (cd "${project_path}" && ddev export-db --file="${safety}") \
+      || echo "  (no local database to export yet — continuing)";
+  fi
+
+  echo "Dumping ${env} from Upsun.";
+  local upsun_app ;
+  upsun_app=$(cd "${project_path}" && upsun apps -p "${linked_id}" -e "${env}" --pipe 2>/dev/null | grep -v '^storybook$' | head -1) ;
+  upsun_app="${upsun_app:-drupal}" ;
+  (cd "${project_path}" && upsun db:dump -p "${linked_id}" -e "${env}" --app "${upsun_app}" --gzip -f "${dump}") || return 1 ;
+
+  echo "Importing it into DDEV.";
+  (cd "${project_path}" && ddev start -y > /dev/null && ddev import-db --file="${dump}") || return 1 ;
+
+  echo "";
+  echo "  Imported ${env} into ${doc_name}/${PROJECT_NAME}.";
+  echo "    pulled dump:   ${dump}";
+  echo "    local backup:  ${safety}";
+  echo "  Drupal sites usually need: ddev drush updb -y && ddev drush cr";
+}
+
+# Pull the files mount of one environment into the local site.
+#
+# Only the public files mount, and only into this project's own docroot: the private mount and the
+# rest of the tree are not what "the images are missing locally" means, and downloading a client's
+# private files onto a laptop is not something to do as a side effect.
+function upsun_pull_files() {
+  local project_path="$1" linked_id="$2" env="$3";
+  local docroot mount target;
+
+  docroot="$(upsun_docroot "${project_path}")";
+  if [ -z "${docroot}" ] ; then
+    echo "No web/ or docroot/ in ${doc_name}/${PROJECT_NAME} — nothing to pull files into.";
+    return 1 ;
+  fi
+  mount="${docroot}/sites/default/files";
+  target="${project_path}/${mount}";
+
+  echo "";
+  echo "Pulling the ${env} files mount of Upsun project ${linked_id} into ${mount}.";
+  echo "  This is client data. rsync-style: it adds and overwrites, and does not delete.";
+  echo "";
+  mkdir -p "${target}" ;
+  local upsun_app ;
+  upsun_app=$(cd "${project_path}" && upsun apps -p "${linked_id}" -e "${env}" --pipe 2>/dev/null | grep -v '^storybook$' | head -1) ;
+  upsun_app="${upsun_app:-drupal}" ;
+  (cd "${project_path}" && upsun mount:download -p "${linked_id}" -e "${env}" --app "${upsun_app}" \
+     --mount "${mount}" --target "${target}" -y) || return 1 ;
+
+  echo "";
+  echo "  Files are in ${mount}.";
+  echo "  If Drupal still shows broken images: ddev drush cr";
+}
+
+function upsun_project_tool() {
+  ensure_upsun || return 1 ;
+
+  local project_path="${WORKSPACE_ROOT}/${doc_name}/${PROJECT_NAME}";
+  local linked_id="";
+
+  if [ ! -d "${project_path}" ]; then
+    echo "No such project: ${project_path}";
+    return 1 ;
+  fi
+
+  cd "${project_path}" ;
+  linked_id=$(upsun_linked_id "${project_path}") ;
+
+  # --link <id>: formalize the hand-ritual. Refuses to silently relink a
+  # project that already points somewhere (the webship-com-site/website_starter
+  # duplicate-ID mixup is exactly what this guards against).
+  if [ ! "${LINK}" == '_none_' ] ; then
+    if [ -n "${linked_id}" ] && [ ! "${linked_id}" == "${LINK}" ] && [ ! "${FORCE}" == 'yes' ] ; then
+      echo "${doc_name}/${PROJECT_NAME} is already linked to Upsun project ${linked_id}." ;
+      echo "Re-run with --force to relink it to ${LINK}." ;
+      return 1 ;
+    fi
+    upsun project:set-remote "${LINK}" || return 1 ;
+    echo "Linked ${doc_name}/${PROJECT_NAME} → ${LINK}." ;
+    linked_id="${LINK}";
+  fi
+
+  # --init: scaffold .upsun/config.yaml for a project that has none. Upsun's
+  # own generator asks the stack questions interactively. For a Drupal project
+  # the official path is better than the generic generator, so point at it.
+  if [ "${INIT}" == 'yes' ] ; then
+    if [ -f ".upsun/config.yaml" ]; then
+      echo ".upsun/config.yaml already exists — edit it instead of re-initializing." ;
+    else
+      if grep -q '"drupal/core' composer.json 2>/dev/null ; then
+        echo "This is a Drupal project. The official Upsun paths for Drupal:" ;
+        echo "  - upsun/drupal-scaffold — a composer plugin that places .upsun/config.yaml and" ;
+        echo "    settings.upsun.php into an existing recommended-project structure:" ;
+        echo "      composer config repositories.upsun-drupal-scaffold vcs https://github.com/upsun/drupal-scaffold" ;
+        echo "      composer config --json --merge extra.drupal-scaffold.allowed-packages '[\"upsun/drupal-scaffold\"]'" ;
+        echo "      ddev composer require upsun/drupal-scaffold" ;
+        echo "  - the Drupal reference config in the upsun skill (references/config/drupal.md," ;
+        echo "    from github.com/upsun/ai): build/deploy hooks with drush, mounts, redis, crons." ;
+        echo "  Verify image versions against https://meta.upsun.com/images before committing." ;
+        echo "" ;
+        echo "Running the generic generator anyway:" ;
+      fi
+      upsun project:init || return 1 ;
+    fi
+  fi
+
+  # --push: deploy the current branch. Outward-facing, so say exactly what is
+  # about to happen and let upsun's own confirmation gate it.
+  if [ "${PUSH}" == 'yes' ] ; then
+    if [ -z "${linked_id}" ]; then
+      echo "Not linked to an Upsun project — run with --link <id> first." ;
+      return 1 ;
+    fi
+    echo "Pushing branch '$(git rev-parse --abbrev-ref HEAD 2>/dev/null)' of ${doc_name}/${PROJECT_NAME} to Upsun project ${linked_id}…" ;
+    if [ ! "${ENVIRONMENT}" == '_none_' ] ; then
+      upsun push --target "${ENVIRONMENT}" || return 1 ;
+    else
+      upsun push || return 1 ;
+    fi
+  fi
+
+  # --environments: the branch list, which is what you pick from.
+  if [ "${ENVIRONMENTS}" == 'yes' ] ; then
+    if [ -z "${linked_id}" ] ; then
+      echo "Not linked to an Upsun project — run with --link <id> first." ;
+      return 1 ;
+    fi
+    upsun environment:list -p "${linked_id}" || return 1 ;
+    echo "";
+    echo "  Select one:  bash cmd-tools-upsun.sh ${PROJECT_NAME} --select <environment>";
+  fi
+
+  # --select: remember which environment this project works against, so the pulls take no flag.
+  if [ ! "${SELECT}" == '_none_' ] ; then
+    if [ -z "${linked_id}" ] ; then
+      echo "Not linked to an Upsun project — run with --link <id> first." ;
+      return 1 ;
+    fi
+    # Checked against the real list rather than taken on trust: a typo would otherwise be
+    # discovered by a pull that dumps the wrong branch, or none.
+    if ! upsun environment:list -p "${linked_id}" --pipe 2>/dev/null | grep -qx "${SELECT}" ; then
+      echo "Upsun project ${linked_id} has no environment called '${SELECT}'." ;
+      echo "  List them: bash cmd-tools-upsun.sh ${PROJECT_NAME} --environments" ;
+      return 1 ;
+    fi
+    upsun_select_env "${project_path}" "${SELECT}" ;
+    echo "${doc_name}/${PROJECT_NAME} now works against the ${SELECT} environment." ;
+  fi
+
+  # --pull-db / --pull-files: bring the cloud's data down. Read-only in the cloud, destructive
+  # locally, and client data either way — so each needs its own flag and an environment that was
+  # named or selected. There is no default environment on purpose.
+  if [ "${PULL_DB}" == 'yes' ] || [ "${PULL_FILES}" == 'yes' ] ; then
+    local target_env;
+    target_env="$(upsun_target_env "${project_path}")";
+    if [ -z "${linked_id}" ] ; then
+      echo "Not linked to an Upsun project — run with --link <id> first." ;
+      return 1 ;
+    fi
+    if [ -z "${target_env}" ] ; then
+      echo "No environment selected. Pick one first — a pull must never guess which branch it takes data from:" ;
+      echo "  bash cmd-tools-upsun.sh ${PROJECT_NAME} --environments" ;
+      echo "  bash cmd-tools-upsun.sh ${PROJECT_NAME} --select <environment>" ;
+      echo "  (or name it for this run: --environment <environment>)" ;
+      return 1 ;
+    fi
+    [ "${PULL_DB}" == 'yes' ] && { upsun_pull_db "${project_path}" "${linked_id}" "${target_env}" || return 1 ; }
+    [ "${PULL_FILES}" == 'yes' ] && { upsun_pull_files "${project_path}" "${linked_id}" "${target_env}" || return 1 ; }
+  fi
+
+  # --logs / --activities: recent deploy output and activity trail.
+  if [ "${LOGS}" == 'yes' ] ; then
+    upsun activity:log --type environment.push 2>/dev/null || upsun activity:log || true ;
+  fi
+  if [ "${ACTIVITIES}" == 'yes' ] ; then
+    upsun activity:list --limit 10 || true ;
+  fi
+
+  # Default (and after any verb): status.
+  echo "";
+  echo "*---------------------------------------------------------------------*";
+  echo "  ${doc_name}/${PROJECT_NAME} on Upsun";
+  if [ -z "${linked_id}" ]; then
+    echo "    not linked. Link it with:";
+    echo "      bash cmd-tools-upsun.sh ${PROJECT_NAME} --link <upsun-project-id>";
+    echo "    (find the ID with: upsun projects)";
+  else
+    echo "    project: ${linked_id}";
+    if [ -f ".upsun/config.yaml" ]; then
+      echo "    config:  .upsun/config.yaml present";
+    else
+      echo "    config:  MISSING — scaffold it with --init before a first push";
+    fi
+    local selected;
+    selected="$(upsun_selected_env "${project_path}")";
+    echo "    branch:  ${selected:-none selected — --environments then --select <name>}";
+    echo "";
+    upsun environment:list 2>/dev/null || echo "    (could not list environments — check upsun auth:info)";
+    echo "";
+    echo "  URLs: upsun url --primary   |   deploy: bash cmd-tools-upsun.sh ${PROJECT_NAME} --push";
+    echo "  Data: --pull-db and --pull-files bring ${selected:-the selected environment} down into DDEV.";
+  fi
+  echo "*---------------------------------------------------------------------*";
+
+  cd "${WORKSPACE_ROOT}/${doc_name}";
+}

package/core/scripts/plugins/upsun/host-install.sh

@@ -0,0 +1,99 @@
+#!/usr/bin/env bash
+## The host side of the Upsun plugin: the upsun CLI on this machine, the dashboard's API token,
+## and Upsun's agent toolkit. Run by core/scripts/plugins.sh --install upsun, and by
+## core/scripts/install.sh for every installed plugin that ships one. Idempotent: whatever is
+## already there is reported, not redone. Offered, never automatic: the CLI holds cloud
+## credentials for real environments, so putting it on a machine is a person's decision.
+set -u
+WORKSPACE_ROOT="${WORKSPACE_ROOT:-$(cd "$(dirname "${BASH_SOURCE[0]}")/../../../../.." && pwd)}";
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)";
+confirm() { local a; read -r -p "$1 [y/N] " a < /dev/tty 2>/dev/null || return 1; [[ "${a}" =~ ^[Yy] ]]; }
+PKG='';
+command -v brew > /dev/null 2>&1 && PKG='brew';
+
+# The upsun CLI: a per-person OAuth session, mounted into the dashboard from the host rather
+# than installed in the image. ~/.local/bin is where the tarball route puts it and is not always
+# on PATH, so `command -v` alone reports it missing on a machine that has it.
+UPSUN_BIN='';
+for candidate in "$(command -v upsun 2>/dev/null)" "${HOME}/.local/bin/upsun" "${HOME}/.upsun-cli/bin/upsun" ; do
+  [ -n "${candidate}" ] && [ -x "${candidate}" ] && { UPSUN_BIN="${candidate}"; break; }
+done
+if [ -n "${UPSUN_BIN}" ] ; then
+  printf '  ✓ %-16s %s\n' "upsun" "${UPSUN_BIN}" ;
+else
+  printf '  ✗ %-16s %s\n' "upsun" "missing — deploys and the UPSUN menu need it (developer.upsun.com/cli)" ;
+fi
+
+# The DASHBOARD's Upsun access is separate from the host CLI's: `upsun login` writes a session
+# into the host keyring, which the container cannot reach, so the container needs an API TOKEN in
+# core/config/plugin.upsun.settings.yml. Checked by SHAPE, never printed: an Atlassian token in
+# that field is refused by Upsun with a message that reads like an expiry.
+TOKEN_STATE="$(python3 - "${WORKSPACE_ROOT}/core/config/plugin.upsun.settings.yml" <<'PYEOF' 2>/dev/null || echo unknown
+import io, re, sys
+try:
+    s = io.open(sys.argv[1], encoding='utf-8').read()
+except Exception:
+    print('unset'); raise SystemExit
+m = re.search(r'^cli_token:\s*(\S+)', s, re.M)
+t = m.group(1) if m else ''
+if not t or t in ('CHANGE_ME', "''", '""'):
+    print('unset')
+elif t.startswith('ATATT'):
+    print('atlassian')
+else:
+    print('set')
+PYEOF
+)";
+case "${TOKEN_STATE}" in
+  set)       printf '  ✓ %-16s %s\n' "upsun token" "set for the dashboard (plugin.upsun.settings.yml)" ;;
+  atlassian) printf '  ✗ %-16s %s\n' "upsun token" "cli_token holds an ATLASSIAN token — Upsun refuses it" ;;
+  unset)     printf '  ✗ %-16s %s\n' "upsun token" "cli_token not set — every UPSUN action in the dashboard fails" ;;
+  *)         ;;
+esac
+
+# Upsun's own AI toolkit for coding agents: developer.upsun.com/ai
+if bash "${HERE}/upsun-ai.sh" --check --quiet > /dev/null 2>&1 ; then
+  printf '  ✓ %-16s %s\n' "upsun AI" "skill + read-only MCP installed" ;
+else
+  printf '  ✗ %-16s %s\n' "upsun AI" "Upsun's agent skill/MCP not installed (developer.upsun.com/ai)" ;
+fi
+
+[ "${1:-}" == '--check' ] && exit 0 ;
+
+if [ -z "${UPSUN_BIN}" ] && confirm "Install the Upsun CLI (deploys, environments — holds cloud credentials)?" ; then
+  case "${PKG}" in
+    brew) brew install upsun/tap/upsun-cli ;;
+    *)
+      # Upsun's own installer sets up an apt repository, so it needs root and an interactive
+      # password. The release tarball needs neither: one static binary into ~/.local/bin.
+      upsun_ver="$(wget -qO- https://api.github.com/repos/upsun/cli/releases/latest 2>/dev/null \
+        | sed -n 's/.*"tag_name": *"v\([^"]*\)".*/\1/p' | head -1)" ;
+      if [ -n "${upsun_ver}" ] ; then
+        upsun_tgz="upsun_${upsun_ver}_linux_amd64.tar.gz" ;
+        [ "$(uname -m)" == 'aarch64' ] && upsun_tgz="upsun_${upsun_ver}_linux_arm64.tar.gz" ;
+        upsun_tmp="$(mktemp -d)" ;
+        if wget -qO "${upsun_tmp}/upsun.tgz" "https://github.com/upsun/cli/releases/download/v${upsun_ver}/${upsun_tgz}" \
+           && tar -xzf "${upsun_tmp}/upsun.tgz" -C "${upsun_tmp}" upsun ; then
+          mkdir -p "${HOME}/.local/bin" ;
+          install -m 0755 "${upsun_tmp}/upsun" "${HOME}/.local/bin/upsun" ;
+          echo "  Installed upsun ${upsun_ver} to ~/.local/bin/upsun (no root needed)." ;
+        else
+          echo "  Could not fetch the release tarball — falling back to Upsun's installer (needs sudo)." ;
+          curl -fsSL https://raw.githubusercontent.com/upsun/cli/main/installer.sh | bash ;
+        fi
+        rm -rf "${upsun_tmp}" ;
+      else
+        curl -fsSL https://raw.githubusercontent.com/upsun/cli/main/installer.sh | bash ;
+      fi ;;
+  esac
+  echo "  Sign in with:  upsun login   (it opens your browser, then writes SSH certificates)" ;
+  echo "  The DASHBOARD needs its own credential: put an UPSUN API token in cli_token in" ;
+  echo "  core/config/plugin.upsun.settings.yml (Upsun console -> My profile -> API tokens)." ;
+fi
+
+# Upsun's AI toolkit — the skill that teaches an agent the Upsun CLI and its config format, and
+# the hosted MCP server, registered READ-ONLY (Upsun's own beta default; writes there are
+# permanent on live environments).
+if confirm "Install Upsun's agent skill and read-only MCP server (developer.upsun.com/ai)?" ; then
+  bash "${HERE}/upsun-ai.sh" || true ;
+fi

package/core/scripts/plugins/upsun/host-mounts.txt

@@ -0,0 +1 @@
+~/.upsun-cli

package/core/scripts/plugins/upsun/upsun-ai.sh

@@ -0,0 +1,133 @@
+#!/usr/bin/env bash
+
+################################################################################
+## Webship Workspace — install Upsun's own AI toolkit for coding agents
+################################################################################
+## Upsun publishes a skill and an MCP server for coding agents:
+##
+##   https://developer.upsun.com/ai
+##   https://github.com/upsun/ai        the toolkit: plugin + skill + MCP
+##   https://github.com/upsun/skills    the skill on its own
+##
+## The skill teaches an agent the Upsun CLI — 130+ commands across 30 namespaces,
+## plus per-framework config recipes including Drupal and PHP — so it writes a
+## working `.upsun/config.yaml` the first time instead of learning by failed
+## deploy. The MCP server answers the same questions over HTTP when no CLI is
+## available.
+##
+##   bash core/scripts/upsun-ai.sh            install the skill, register the MCP
+##   bash core/scripts/upsun-ai.sh --check    report, change nothing
+##   bash core/scripts/upsun-ai.sh --quiet     only speak when something is wrong
+##
+## Two deliberate choices:
+##
+## - **The MCP is registered read-only** (`enable-write: false`, which is Upsun's
+##   own default). This is a CLI that manages live client environments; an agent
+##   that can read them is useful, an agent that can change them is a decision for
+##   a person, per environment, not a default of a setup script.
+## - **The skill is copied, not symlinked**, into ~/.claude/skills/upsun — the same
+##   place cmd-tools-ai-items.sh installs Webship's own skills, so it is visible to
+##   `--source claude` and cannot vanish when a temporary clone is cleaned up.
+##
+## Self-contained plain bash, like trust-https.sh and host-mounts.sh beside it.
+################################################################################
+
+set -u
+
+CHECK_ONLY='no'
+QUIET='no'
+while [ $# -gt 0 ]; do
+  case "$1" in
+    -c|--check) CHECK_ONLY='yes'; shift ;;
+    -q|--quiet) QUIET='yes'; shift ;;
+    -h|--help)  sed -n '3,33p' "${BASH_SOURCE[0]}" | sed 's/^## \{0,1\}//'; exit 0 ;;
+    *) echo "Unknown option: $1 (see --help)"; exit 1 ;;
+  esac
+done
+
+REPO='https://github.com/upsun/ai.git'
+SKILL_SRC='plugins/upsun/skills/upsun'
+SKILL_DEST="${HOME}/.claude/skills/upsun"
+MCP_URL='https://mcp.upsun.com/mcp'
+
+function say()  { [ "${QUIET}" == 'yes' ] || echo "$@" ; }
+function warn() { echo "$@" ; }
+function have() { command -v "$1" > /dev/null 2>&1 ; }
+
+PROBLEMS=0
+
+# ------------------------------------------------------------------- the skill ---
+
+skill_installed='no'
+[ -f "${SKILL_DEST}/SKILL.md" ] && skill_installed='yes'
+
+if [ "${skill_installed}" == 'yes' ] ; then
+  say "  ✓ upsun skill      ~/.claude/skills/upsun ($(find "${SKILL_DEST}" -type f | wc -l) files)"
+elif [ "${CHECK_ONLY}" == 'yes' ] ; then
+  warn "  ✗ upsun skill      not installed — an agent has to learn the Upsun CLI by failing"
+  PROBLEMS=$((PROBLEMS + 1))
+else
+  if ! have git ; then
+    warn "  ✗ git is needed to fetch the skill."
+    PROBLEMS=$((PROBLEMS + 1))
+  else
+    tmp="$(mktemp -d)"
+    # A shallow clone: this is 164KB of Markdown, and none of its history matters here.
+    if git clone --quiet --depth=1 "${REPO}" "${tmp}/ai" 2>/dev/null \
+       && [ -f "${tmp}/ai/${SKILL_SRC}/SKILL.md" ] ; then
+      mkdir -p "${HOME}/.claude/skills"
+      rm -rf "${SKILL_DEST}"
+      cp -r "${tmp}/ai/${SKILL_SRC}" "${SKILL_DEST}"
+      say "  ✓ upsun skill      installed to ~/.claude/skills/upsun ($(find "${SKILL_DEST}" -type f | wc -l) files)"
+    else
+      warn "  ✗ could not fetch ${REPO} — check network access to GitHub."
+      PROBLEMS=$((PROBLEMS + 1))
+    fi
+    rm -rf "${tmp}"
+  fi
+fi
+
+# --------------------------------------------------------------------- the MCP ---
+
+if ! have claude ; then
+  say "  – upsun MCP        skipped: the claude CLI is not installed"
+else
+  if claude mcp get upsun > /dev/null 2>&1 ; then
+    say "  ✓ upsun MCP        registered (claude mcp get upsun)"
+  elif [ "${CHECK_ONLY}" == 'yes' ] ; then
+    warn "  ✗ upsun MCP        not registered"
+    PROBLEMS=$((PROBLEMS + 1))
+  else
+    # enable-write: false is Upsun's own default and it stays that way here: see the
+    # header. The token comes from the environment so no credential is written into
+    # ~/.claude.json — ${UPSUN_API_TOKEN} is expanded when the server is loaded.
+    if claude mcp add --transport http upsun "${MCP_URL}" -s user \
+         --header 'upsun-api-token: ${UPSUN_API_TOKEN:-}' \
+         --header 'enable-write: false' > /dev/null 2>&1 ; then
+      say "  ✓ upsun MCP        registered read-only at ${MCP_URL}"
+    else
+      warn "  ✗ could not register the upsun MCP server with the claude CLI."
+      PROBLEMS=$((PROBLEMS + 1))
+    fi
+  fi
+fi
+
+# ------------------------------------------------------------------ what next ---
+
+say ""
+if [ "${CHECK_ONLY}" == 'yes' ] ; then
+  [ "${PROBLEMS}" -eq 0 ] && { say "Upsun's AI toolkit is installed."; exit 0; }
+  warn "Upsun's AI toolkit is incomplete — run without --check to install it."
+  exit 1
+fi
+
+if [ "${PROBLEMS}" -eq 0 ] ; then
+  say "Upsun's AI toolkit is installed. Two things it needs from you:"
+  say "  • The skill reaches a session after a restart."
+  say "  • The MCP authenticates with an UPSUN API token, not the browser session:"
+  say "      export UPSUN_API_TOKEN=…    (Upsun console → My profile → API tokens)"
+  say "    It must be an Upsun token — an Atlassian token is refused with a message"
+  say "    that reads like an expiry rather than the wrong kind of token."
+  exit 0
+fi
+exit 1