Reduce duplicate dependency storage across worktrees

.github/agents/spx-upgrader.md

@@ -12,7 +12,7 @@ You are a release specialist dedicated to upgrading spx across goplus/builder sa
 - Refresh Go modules in `tools/ai/`, `tools/spxls/`, and `tools/ispx/` via `go get github.com/goplus/spx/v2@v<version>` followed by `go mod tidy` in each directory
 - Execute `bash spx-gui/install-spx.sh` to download the matching runtime assets and remove any temporary archives
 - Execute `bash build-wasm.sh` in `spx-gui/` to build Wasm components
-- Run `npm ci`, `npm run lint`, `npm run test -- --run` in `spx-gui/`, plus `go test ./...` inside `tools/ai/`, `tools/spxls/`, and `tools/ispx/` if there are packages to test
+- Run `pnpm install --frozen-lockfile`, `pnpm run lint`, `pnpm run test -- --run` in `spx-gui/`, plus `go test ./...` inside `tools/ai/`, `tools/spxls/`, and `tools/ispx/` if there are packages to test
 - Verify `git status` is clean beyond the expected files, then create a commit titled `chore(deps): bump spx to <version>` and draft a PR with release notes and validation logs
 - If any command fails, stop immediately and report the exact output instead of continuing
 

.github/workflows/release.yml

@@ -26,16 +26,16 @@ jobs:
         uses: actions/setup-node@v6
         with:
           node-version: 24.11.1
-          cache: npm
-          cache-dependency-path: spx-gui/package-lock.json
+          cache: pnpm
+          cache-dependency-path: spx-gui/pnpm-lock.yaml
 
       - name: Install Node modules
         working-directory: spx-gui
-        run: npm ci --prefer-offline
+        run: pnpm install --frozen-lockfile
 
       - name: Build account frontend
         working-directory: spx-gui
-        run: npm run build:account
+        run: pnpm run build:account
 
       - name: Deploy builder_account
         uses: ./.github/actions/deploy
@@ -47,7 +47,7 @@ jobs:
 
       - name: Build account frontend for mainland China deployment
         working-directory: spx-gui
-        run: VITE_MODE=production-cn npm run build:account
+        run: VITE_MODE=production-cn pnpm run build:account
 
       - name: Deploy builder_account_cn
         uses: ./.github/actions/deploy

.github/workflows/validate.yml

@@ -13,37 +13,29 @@ jobs:
     steps:
       - uses: actions/checkout@v7
 
-      - name: Cache Node modules
-        uses: actions/cache@v6
-        env:
-          cache-name: cache-node-modules
-        with:
-          path: spx-gui/node_modules
-          key: ${{runner.os}}-${{runner.arch}}-${{env.cache-name}}-${{hashFiles('spx-gui/package-lock.json')}}
-          restore-keys: |
-            ${{runner.os}}-${{runner.arch}}-${{env.cache-name}}-
-
       - name: Enable Corepack
         run: corepack enable
 
       - name: Set up Node.js
         uses: actions/setup-node@v6
         with:
           node-version: 24.11.1
-          cache: npm
-          cache-dependency-path: spx-gui/package-lock.json
+          cache: pnpm
+          cache-dependency-path: |
+            spx-gui/pnpm-lock.yaml
+            tutorial/pnpm-lock.yaml
 
       - name: Install Node modules
-        run: npm ci --prefer-offline
+        run: pnpm install --frozen-lockfile
 
       - name: Run Vue TSC
-        run: npm run type-check
+        run: pnpm run type-check
 
       - name: Run ESLint
-        run: npm run lint
+        run: pnpm run lint
 
       - name: Run format check
-        run: npm run format-check
+        run: pnpm run format-check
 
       - name: Setup Go
         uses: actions/setup-go@v6
@@ -59,10 +51,10 @@ jobs:
         run: ./build-wasm.sh
 
       - name: Run Vitest
-        run: npm run test
+        run: pnpm run test
 
       - name: Build
-        run: npm run build
+        run: pnpm run build
 
   tools-ai-test:
     runs-on: ubuntu-latest

spx-gui/.vscode/tasks.json

@@ -2,10 +2,10 @@
   "version": "2.0.0",
   "tasks": [
     {
-      "label": "npm run dev",
+      "label": "pnpm run dev",
       "detail": "Run dev server for spx-gui",
-      "type": "npm",
-      "script": "dev",
+      "type": "shell",
+      "command": "pnpm run dev",
       "presentation": {
         "panel": "dedicated"
       },

spx-gui/AGENTS.md

@@ -99,17 +99,17 @@ When working with backend unique string identifiers such as `username`, project
 * Check `src/models/project/index.test.ts` for examples of constructing mock `Project` instances.
 * If test cases fail due to minor issues, fix them in the source code.
 * If test cases fail due to complex reasons, leave the test case unchanged and add a comment explaining the issue.
-* When running test cases, use the `--run` option to disable watch mode and get notified when tests finish. For example: `npm run test -- --run src/components/editor/editing.test.ts` or `npx vitest --run src/components/editor/editing.test.ts` runs tests in `editing.test.ts` in non-watch mode.
+* When running test cases, use the `--run` option to disable watch mode and get notified when tests finish. For example: `pnpm run test -- --run src/components/editor/editing.test.ts` or `pnpm exec vitest --run src/components/editor/editing.test.ts` runs tests in `editing.test.ts` in non-watch mode.
 * It's OK to use type assertions like `as any` or `as unknown` to bypass type errors if you are sure of the types, but try to avoid them if possible.
 * Avoid data sharing among test cases. Each test case should be independent and not rely on the state set by another test case.
 
 ## Static Checks and Formatting
 
-* `npm run type-check` runs TypeScript type checking.
-* `npm run lint` runs ESLint.
-* `npm run test` runs unit tests.
+* `pnpm run type-check` runs TypeScript type checking.
+* `pnpm run lint` runs ESLint.
+* `pnpm run test` runs unit tests.
 * Run the appropriate checks when making large changes and there are no pending TODOs that would cause static checks to fail.
-* Use Prettier (`npx prettier --write <file>`) for code formatting after making changes.
+* Use Prettier (`pnpm exec prettier --write <file>`) for code formatting after making changes.
 
 ## Vue Component Development
 
@@ -193,7 +193,7 @@ This section describes how we handle browser compatibility in the spx-gui projec
 
 ### Target Browsers
 
-We specify target browsers via the `browserslist` field in `package.json`. This configuration is used by various tools to determine which browser features need transpilation or polyfilling. You can list the final set of supported browsers by running `npx browserslist` in the project root.
+We specify target browsers via the `browserslist` field in `package.json`. This configuration is used by various tools to determine which browser features need transpilation or polyfilling. You can list the final set of supported browsers by running `pnpm exec browserslist` in the project root.
 
 ### Build-time Transpilation
 

spx-gui/README.md

@@ -3,18 +3,25 @@
 ## Environment Requirements
 
 - **Node.js**: >= 20.11.1
+- **pnpm**: ^11.9.0
 - **Go**: >= 1.25.0
 
 ## Install Dependencies
 
+If pnpm is not available, enable it with Corepack first:
+
+```bash
+corepack enable pnpm
+```
+
 ```bash
-npm install
+pnpm install
 ```
 
 ## Run the Project in Development Mode
 
 ```bash
-npm run dev
+pnpm run dev
 ```
 
 ## Development Standards
@@ -45,7 +52,7 @@ npm run dev
 Use the NPM script `format` to format your code with Prettier:
 
 ```shell
-npm run format
+pnpm run format
 ```
 
 Format on PR for changed files is required. You can also turn on the feature Format on Save in VSCode.

spx-gui/build/Dockerfile

@@ -24,12 +24,14 @@ FROM ${NODE_BASE_IMAGE} AS frontend-builder
 
 WORKDIR /app/spx-gui
 
-COPY spx-gui/package.json spx-gui/package-lock.json .
+COPY spx-gui/package.json spx-gui/pnpm-lock.yaml spx-gui/pnpm-workspace.yaml .
 COPY spx-gui/public ./public
 COPY spx-gui/install-spx.sh .
 COPY spx-gui/build-tutorial-books.sh .
 ARG NPM_CONFIG_REGISTRY
-RUN npm install
+# pnpm reads npm config from lowercase npm_config_* environment variables.
+ENV npm_config_registry=${NPM_CONFIG_REGISTRY}
+RUN corepack enable && pnpm install --frozen-lockfile
 
 COPY spx-gui .
 COPY docs ../docs
@@ -41,7 +43,7 @@ COPY --from=go-builder /app/spx-gui/src/assets /app/spx-gui/src/assets
 ARG VITE_MODE
 
 ENV NODE_OPTIONS=--max-old-space-size=4096
-RUN npm run build
+RUN pnpm run build
 
 ################################################################################
 

spx-gui/build/Dockerfile.account

@@ -5,17 +5,19 @@ FROM ${NODE_BASE_IMAGE} AS frontend-builder
 
 WORKDIR /app/spx-gui
 
-COPY spx-gui/package.json spx-gui/package-lock.json .
+COPY spx-gui/package.json spx-gui/pnpm-lock.yaml spx-gui/pnpm-workspace.yaml .
 
 ARG NPM_CONFIG_REGISTRY
-RUN npm install --ignore-scripts
+# pnpm reads npm config from lowercase npm_config_* environment variables.
+ENV npm_config_registry=${NPM_CONFIG_REGISTRY}
+RUN corepack enable && pnpm install --frozen-lockfile --ignore-scripts
 
 COPY spx-gui .
 
 ARG VITE_MODE
 
 ENV NODE_OPTIONS=--max-old-space-size=4096
-RUN npm run build:account
+RUN pnpm run build:account
 
 FROM ${NGINX_BASE_IMAGE}
 

spx-gui/install-spx.sh

@@ -1,49 +1,31 @@
 #!/bin/bash
-set -e
+set -euo pipefail
 
 cd "$(dirname "$0")"
 
 # Keep this version in sync with `VITE_SPX_VERSION` in `src/apps/xbuilder/.env`.
 SPX_VERSION="2.0.4"
 
 SPX_NAME="spx_${SPX_VERSION}"
-SPX_RELEASE_URL="https://github.com/goplus/spx/releases/download/v${SPX_VERSION}/spx_web.zip"
+SPX_PACKAGE_DIR="./node_modules/@xgo-pkgs/spx"
 SPX_TARGET_DIR="./public/${SPX_NAME}"
-SPX_STAGING_DIR="./public/.${SPX_NAME}.tmp"
-SPX_ZIP_PATH="${SPX_STAGING_DIR}/spx_web.zip"
 
-if [[ -d "${SPX_TARGET_DIR}" ]]; then
-  exit 0
+if [[ ! -d "${SPX_PACKAGE_DIR}" ]]; then
+  echo "missing ${SPX_PACKAGE_DIR}" >&2
+  echo "run pnpm install to install @xgo-pkgs/spx@${SPX_VERSION}" >&2
+  exit 1
 fi
 
-trap 'rm -rf "${SPX_STAGING_DIR}"' EXIT
-
-rm -rf "${SPX_STAGING_DIR}"
-mkdir -p "${SPX_STAGING_DIR}"
-
-if wget --spider --quiet "${SPX_RELEASE_URL}"; then
-  wget -O "${SPX_ZIP_PATH}" "${SPX_RELEASE_URL}"
-else
-  ghcr_token="$(wget -qO- "https://ghcr.io/token?service=ghcr.io&scope=repository:goplus/spx:pull" | awk -F'"' '/"token":/{print $4}')"
-  if [[ -z "${ghcr_token}" ]]; then
-    echo "failed to get GHCR token for goplus/spx" >&2
-    exit 1
+if [[ -L "${SPX_TARGET_DIR}" ]]; then
+  if target_real="$(realpath "${SPX_TARGET_DIR}" 2>/dev/null)" \
+    && package_real="$(realpath "${SPX_PACKAGE_DIR}")" \
+    && [[ "${target_real}" == "${package_real}" ]]; then
+    exit 0
   fi
-
-  blob_digest="$(wget -qO- \
-      --header="Authorization: Bearer ${ghcr_token}" \
-      --header='Accept: application/vnd.oci.image.manifest.v1+json, application/vnd.oci.artifact.manifest.v1+json, application/vnd.docker.distribution.manifest.v2+json' \
-      "https://ghcr.io/v2/goplus/spx/manifests/web-zip-${SPX_VERSION}" \
-      | tr -d '[:space:]' \
-      | sed -n 's/.*"mediaType":"application\/zip"[^}]*"digest":"\([^"]*\)".*/\1/p')"
-  if [[ -z "${blob_digest}" ]]; then
-    echo "failed to resolve OCI blob digest for ghcr.io/goplus/spx:web-zip-${SPX_VERSION}" >&2
-    exit 1
-  fi
-
-  wget -O "${SPX_ZIP_PATH}" --header="Authorization: Bearer ${ghcr_token}" "https://ghcr.io/v2/goplus/spx/blobs/${blob_digest}"
+  rm "${SPX_TARGET_DIR}"
+elif [[ -e "${SPX_TARGET_DIR}" ]]; then
+  rm -rf "${SPX_TARGET_DIR}"
 fi
 
-unzip -o "${SPX_ZIP_PATH}" -d "${SPX_STAGING_DIR}"
-rm -f "${SPX_ZIP_PATH}"
-mv "${SPX_STAGING_DIR}" "${SPX_TARGET_DIR}"
+mkdir -p "$(dirname "${SPX_TARGET_DIR}")"
+ln -s "../node_modules/@xgo-pkgs/spx" "${SPX_TARGET_DIR}"