Skip to content

Official Codebase of 3DCodeVerse

Python
7.2 KB
Raw Blame
#!/usr/bin/env bash
# 3dcodeverse plugin — idempotent installer / updater of the `3dcode` instruments.
#
#   bash harness/setup.sh [options]
#
# Does, in order: version checks (python 3.13, node >= 20.6) -> `pip install -e
# harness[<extras>]` (console script `3dcode`) -> `npm ci` in runtime_js *only when the
# lockfile moved* -> puppeteer chrome download (no-op when cached) -> `3dcode doctor`.
# Re-running is safe: every step is a no-op when it is already satisfied.
# Full guide: docs/INSTALL.md
set -euo pipefail

# The supported floor (docs/INSTALL.md §2.1).  Pinned to pyproject's requires-python
# and to codeverse3d/spatial/node.py NODE_MIN by tests/core/test_portability.py.
MIN_PY_MINOR=13      # python 3.13 (one fixed version)
MIN_NODE_MAJOR=20    # node 20.6+ (`node --import` module hooks)
MIN_NODE_MINOR=6

HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
HARNESS="$HERE"
RUNTIME_JS="$HARNESS/runtime_js"

PY="${PYTHON:-python3}"
EXTRAS="all"
DO_PYTHON=1
DO_NODE=1
DO_CHROME=1
DO_DOCTOR=1
FORCE_NPM=0
DOCTOR_ARGS=()

usage() {
  cat <<'USAGE'
usage: setup.sh [options]

  --extras LIST     pip extras to install (default: all; "" = none)
  --python BIN      python interpreter to install into (default: $PYTHON or python3)
  --no-python       skip the pip install step
  --no-node         skip `npm ci` in runtime_js
  --no-chrome       skip the puppeteer chrome download
  --no-doctor       skip the final `3dcode doctor`
  --force-npm       run `npm ci` even when node_modules looks up to date
                    (WARNING: npm ci deletes node_modules first — do not use
                    while renders/benches are running against this tree)
  --no-gpu          pass --no-gpu to doctor (skips the headless-Chrome probe)
  -h, --help        this message
USAGE
}

while [ $# -gt 0 ]; do
  case "$1" in
    --extras) EXTRAS="${2-}"; shift 2 ;;
    --extras=*) EXTRAS="${1#*=}"; shift ;;
    --python) PY="${2-}"; shift 2 ;;
    --python=*) PY="${1#*=}"; shift ;;
    --no-python) DO_PYTHON=0; shift ;;
    --no-node) DO_NODE=0; shift ;;
    --no-chrome) DO_CHROME=0; shift ;;
    --no-doctor) DO_DOCTOR=0; shift ;;
    --force-npm) FORCE_NPM=1; shift ;;
    --no-gpu) DOCTOR_ARGS+=(--no-gpu); shift ;;
    -h|--help) usage; exit 0 ;;
    *) echo "setup.sh: unknown option: $1" >&2; usage >&2; exit 2 ;;
  esac
done

step() { printf '\n\033[1m== %s\033[0m\n' "$*"; }
info() { printf '   %s\n' "$*"; }
die()  { printf '\033[31merror:\033[0m %s\n' "$*" >&2; exit 1; }

# --------------------------------------------------------------- prerequisites
step "prerequisites"

command -v "$PY" >/dev/null 2>&1 || die "python interpreter not found: $PY (install python 3.$MIN_PY_MINOR+ or pass --python)"
PY_VER="$("$PY" -c 'import sys; print("%d.%d.%d" % sys.version_info[:3])')"
"$PY" -c "import sys; sys.exit(0 if sys.version_info[:2] >= (3, $MIN_PY_MINOR) else 1)" \
  || die "python 3.$MIN_PY_MINOR+ required, found $PY_VER ($PY)"
info "python   $PY_VER  ($("$PY" -c 'import sys; print(sys.executable)'))"

# pip is a prerequisite, not a given: Debian/Ubuntu ship /usr/bin/python3 without it and
# mark it PEP 668 (EXTERNALLY-MANAGED), so the TL;DR install used to pass this whole block
# and then abort on the bare line "/usr/bin/python3: No module named pip" with no guidance.
if [ "$DO_PYTHON" -eq 1 ]; then
  if ! "$PY" -m pip --version >/dev/null 2>&1; then
    die "python has no pip: '$PY -m pip' is missing.
    Create a virtualenv and re-run with it (recommended — docs/INSTALL.md §3):
        $PY -m venv .venv && . .venv/bin/activate && bash $0
    On Debian/Ubuntu the venv and pip modules are packaged separately:
        sudo apt install python3-venv python3-pip"
  fi
  PIP_VER="$("$PY" -m pip --version | awk '{print $2}')"
  # PEP 668: pip refuses to install into an externally-managed interpreter, so say so
  # here rather than letting `pip install -e` fail three steps later.
  if "$PY" - <<'PEP668'
import os, sys, sysconfig
managed = os.path.exists(os.path.join(sysconfig.get_path("stdlib"), "EXTERNALLY-MANAGED"))
sys.exit(0 if managed and sys.prefix == sys.base_prefix else 1)
PEP668
  then
    die "python is PEP 668 externally-managed and this is not a virtualenv: $PY
    pip will refuse to install here.  Create one and re-run with it:
        $PY -m venv .venv && . .venv/bin/activate && bash $0
    (docs/INSTALL.md §3)"
  fi
  info "pip      $PIP_VER"
fi

command -v git >/dev/null 2>&1 || die "git not found (every round is a git commit in the run workspace)"
info "git      $(git --version | awk '{print $3}')"

NODE_OK=1
if command -v node >/dev/null 2>&1; then
  NODE_VER="$(node --version)"            # vNN.NN.NN
  NODE_NUM="${NODE_VER#v}"
  NODE_MAJOR="${NODE_NUM%%.*}"; NODE_REST="${NODE_NUM#*.}"; NODE_MINOR="${NODE_REST%%.*}"
  if [ "$NODE_MAJOR" -lt "$MIN_NODE_MAJOR" ] \
     || { [ "$NODE_MAJOR" -eq "$MIN_NODE_MAJOR" ] && [ "$NODE_MINOR" -lt "$MIN_NODE_MINOR" ]; }; then
    NODE_OK=0
    info "node     $NODE_VER  (need >= $MIN_NODE_MAJOR.$MIN_NODE_MINOR — three.js / scene / GLB tracks will not run)"
  else
    info "node     $NODE_VER"
  fi
else
  NODE_OK=0
  info "node     not found (three.js / scene / GLB export tracks will not run)"
fi

# Blender (optional: the blender / urdf_blender tracks) is found and version-checked by the
# closing doctor, through the harness's own resolver (docs/INSTALL.md §6).

# ------------------------------------------------------------------ python pkg
if [ "$DO_PYTHON" -eq 1 ]; then
  step "pip install -e $HARNESS${EXTRAS:+[$EXTRAS]}"
  if [ -n "$EXTRAS" ]; then
    "$PY" -m pip install -e "$HARNESS[$EXTRAS]"
  else
    "$PY" -m pip install -e "$HARNESS"
  fi
else
  step "pip install (skipped: --no-python)"
fi

# -------------------------------------------------------------------- runtime_js
if [ "$DO_NODE" -eq 1 ] && [ "$NODE_OK" -eq 1 ]; then
  step "runtime_js node_modules (three + puppeteer)"
  command -v npm >/dev/null 2>&1 || die "npm not found (it ships with node)"
  [ -f "$RUNTIME_JS/package-lock.json" ] || die "missing $RUNTIME_JS/package-lock.json"
  STAMP="$RUNTIME_JS/node_modules/.package-lock.json"
  if [ "$FORCE_NPM" -eq 1 ] || [ ! -d "$RUNTIME_JS/node_modules" ] || [ ! -f "$STAMP" ] \
     || [ "$RUNTIME_JS/package-lock.json" -nt "$STAMP" ]; then
    info "running npm ci (this deletes and re-creates node_modules)"
    ( cd "$RUNTIME_JS" && npm ci )
  else
    info "up to date — node_modules matches package-lock.json (use --force-npm to reinstall)"
  fi

  if [ "$DO_CHROME" -eq 1 ]; then
    step "puppeteer chrome (~/.cache/puppeteer)"
    ( cd "$RUNTIME_JS" && npx --no puppeteer browsers install chrome )
  fi
else
  step "runtime_js (skipped: no usable node, or --no-node)"
fi

# ----------------------------------------------------------------------- doctor
if [ "$DO_DOCTOR" -eq 1 ]; then
  step "3dcode doctor"
  # Verify what we just INSTALLED, not whatever happens to be first on PATH: with --python the
  # venv's entry point is not on PATH, so the doctor runs through the interpreter we installed into.
  if "$PY" -c 'import codeverse3d' >/dev/null 2>&1; then
    "$PY" -m codeverse3d.cli doctor ${DOCTOR_ARGS[@]+"${DOCTOR_ARGS[@]}"} || true
  else
    info "codeverse3d not importable by $PY — skipping doctor (run: $HARNESS/bin/3dcode doctor)"
  fi
fi

printf '\n\033[1mdone.\033[0m  Next: docs/INSTALL.md (install the plugin into your coding agent).\n'