chore(repo): switch package manager references from pnpm to utoo

.github/copilot-instructions.md

@@ -6,30 +6,30 @@
 
 Eggjs is a progressive Node.js framework for building enterprise-class server-side applications. Built on top of Koa.js, it provides a plugin system, conventions over configuration, and enterprise-grade features like clustering, logging, and security.
 
-This is a **pnpm monorepo** with multiple packages using pnpm workspaces and catalog mode for centralized dependency management.
+This is a **utoo monorepo** with multiple packages using utoo workspaces and catalog mode for centralized dependency management.
 
 ## Prerequisites and Environment Setup
 
-- **Node.js >= 20.19.0 required** - This is a hard requirement
-- Enable pnpm first: `corepack enable pnpm` (installs pnpm v10.16.0)
+- **Node.js >= 22.18.0 required** - This is a hard requirement
+- Enable utoo first: `corepack enable utoo`
 - **NEVER CANCEL** any build or test commands - they can take several minutes to complete
 
 ## Bootstrap and Build Process
 
 **Always run these commands in sequence after fresh clone:**
 
 ```bash
-# 1. Enable pnpm (required first)
-corepack enable pnpm
+# 1. Enable utoo (required first)
+corepack enable utoo
 
 # 2. Install all dependencies - takes ~63 seconds. NEVER CANCEL. Set timeout to 120+ seconds.
-pnpm install
+ut install --from pnpm
 
 # 3. Build all packages - takes ~14 seconds. NEVER CANCEL. Set timeout to 60+ seconds.
-pnpm run build
+ut run build
 
 # 4. Run linting (optional but recommended) - takes ~2 seconds
-pnpm run lint
+ut run lint
 ```
 
 ## Monorepo Structure
@@ -48,51 +48,51 @@ pnpm run lint
 ### Supporting Directories
 
 - **`examples/`** - Two example apps: `helloworld-commonjs` and `helloworld-typescript` (currently have runtime issues)
-- **`site/`** - Documentation website built with Dumi
+- **`site/`** - Documentation website built with VitePress
 
 ## Essential Commands and Timing
 
 ### Build Commands
 
-- `pnpm run build` - **Build all packages (~14 seconds). NEVER CANCEL. Set timeout to 60+ seconds.**
-- `pnpm run clean` - Clean all dist directories
+- `ut run build` - **Build all packages (~14 seconds). NEVER CANCEL. Set timeout to 60+ seconds.**
+- `ut run clean-dist` - Clean all dist directories
 
 ### Testing Commands
 
-- `pnpm run test` - **Run all tests (~2 minutes). NEVER CANCEL. Set timeout to 180+ seconds.**
-- `pnpm run test:cov` - **Run tests with coverage (~2 minutes). NEVER CANCEL. Set timeout to 180+ seconds.**
-- `pnpm run ci` - **Run test coverage + build (~2.1 minutes). NEVER CANCEL. Set timeout to 180+ seconds.**
+- `ut run test` - **Run all tests (~2 minutes). NEVER CANCEL. Set timeout to 180+ seconds.**
+- `ut run test:cov` - **Run tests with coverage (~2 minutes). NEVER CANCEL. Set timeout to 180+ seconds.**
+- `ut run ci` - **Run tests with coverage (~2 minutes). NEVER CANCEL. Set timeout to 180+ seconds.**
 
 ### Linting Commands
 
-- `pnpm run lint` - Run oxlint across all packages (~2 seconds)
+- `ut run lint` - Run oxlint across all packages (~2 seconds)
 
 ### Documentation Commands
 
-- `pnpm run site:dev` - Start documentation dev server at http://localhost:8000
-- `cd site && pnpm run build:skip` - **Build documentation site (~24 seconds). NEVER CANCEL. Set timeout to 60+ seconds.**
+- `ut run site:dev` - Start documentation dev server (defaults to VitePress port 5173)
+- `ut run site:build` - **Build documentation site (~24 seconds). NEVER CANCEL. Set timeout to 60+ seconds.**
 
 ### Example Applications (Currently Not Working)
 
-- `pnpm run example:commonjs` - Start CommonJS example (has runtime issues)
-- `pnpm run example:typescript` - Start TypeScript example (has runtime issues)
+- `ut run example:dev:commonjs` - Start CommonJS example (has runtime issues)
+- `ut run example:dev:typescript` - Start TypeScript example (has runtime issues)
 
 ## Package-Specific Commands
 
-Run commands for specific packages using `pnpm --filter=<package>`:
+Run commands for specific packages using `ut --filter=<package>`:
 
 ```bash
 # Examples
-pnpm --filter=egg run test
-pnpm --filter=@eggjs/core run build
-pnpm --filter=site run dev
+ut --filter=egg run test
+ut --filter=@eggjs/core run build
+ut --filter=site run dev
 ```
 
 ## Development Workflow
 
 ### 1. Making Changes
 
-- Always build packages first: `pnpm run build`
+- Always build packages first: `ut run build`
 - Work primarily in `packages/egg/src/` for core framework features
 - Use TypeScript throughout - all packages are TypeScript-based
 - Follow the existing directory conventions in `packages/egg/src/`:
@@ -108,16 +108,16 @@ pnpm --filter=site run dev
 
 ```bash
 # 1. Build all packages (required)
-pnpm run build
+ut run build
 
 # 2. Run linting
-pnpm run lint
+ut run lint
 
 # 3. Run tests (some failures are expected in fresh environment)
-pnpm run test
+ut run test
 
 # 4. Test documentation site
-pnpm run site:dev
+ut run site:dev
 ```
 
 ### 3. Testing Strategy
@@ -162,7 +162,7 @@ pnpm run site:dev
 - **All sub-project tsconfig.json files MUST extend from root:** `"extends": "../../tsconfig.json"`
 - Root tsconfig.json includes all packages in `references` array
 
-## pnpm Workspace & Catalog Dependencies
+## utoo Workspace & Catalog Dependencies
 
 - Dependencies defined in `pnpm-workspace.yaml` catalog section
 - Reference catalog entries: `"package-name": "catalog:"`
@@ -179,7 +179,7 @@ pnpm run site:dev
 
 ### Build Issues
 
-- Always run `pnpm run build` after making changes
+- Always run `ut run build` after making changes
 - TypeScript compilation errors will show clearly
 - Build warnings are generally acceptable
 
@@ -217,10 +217,10 @@ pnpm run site:dev
 
 After making changes, always verify:
 
-1. **Build Success**: `pnpm run build` completes without errors
-2. **Linting Passes**: `pnpm run lint` shows no new errors
-3. **Documentation Loads**: `pnpm run site:dev` starts successfully and site loads at http://localhost:8000
-4. **Tests Run**: `pnpm run test` executes (some failures expected, focus on your changes)
+1. **Build Success**: `ut run build` completes without errors
+2. **Linting Passes**: `ut run lint` shows no new errors
+3. **Documentation Loads**: `ut run site:dev` starts successfully and the printed VitePress URL responds
+4. **Tests Run**: `ut run test` executes (some failures expected, focus on your changes)
 
 **Remember**: This is a complex enterprise framework. Always build first, validate incrementally, and focus on the core packages (`egg`, `core`, `utils`) for most development work.
 

.github/workflows/ci.yml

@@ -37,7 +37,8 @@ jobs:
           node-version: '24'
 
       - name: Install dependencies
-        run: ut install --from pnpm
+        # Retry to absorb transient `exit 141` (SIGPIPE) from `ut install`.
+        run: ut install --from pnpm || (sleep 5 && ut install --from pnpm) || (sleep 10 && ut install --from pnpm)
 
       - name: Run lint
         run: ut run lint
@@ -160,7 +161,7 @@ jobs:
           node-version: ${{ matrix.node }}
 
       - name: Install dependencies
-        run: ut install --from pnpm
+        run: ut install --from pnpm || (sleep 5 && ut install --from pnpm) || (sleep 10 && ut install --from pnpm)
 
       - name: Run tests
         run: ut run ci
@@ -204,7 +205,7 @@ jobs:
           node-version: ${{ matrix.node }}
 
       - name: Install dependencies
-        run: ut install --from pnpm
+        run: ut install --from pnpm || (sleep 5 && ut install --from pnpm) || (sleep 10 && ut install --from pnpm)
 
       - name: Run tests
         run: |
@@ -245,7 +246,7 @@ jobs:
           node-version: ${{ matrix.node }}
 
       - name: Install dependencies
-        run: ut install --from pnpm
+        run: ut install --from pnpm || (sleep 5 && ut install --from pnpm) || (sleep 10 && ut install --from pnpm)
 
       - name: Run tests
         run: |

.github/workflows/e2e-test.yml

@@ -141,27 +141,39 @@ jobs:
         with:
           ecosystem-ci-project: ${{ matrix.project.name }}
 
-      - name: Install pnpm
-        uses: pnpm/action-setup@41ff72655975bd51cab0327fa583b6e92b6d3061 # v4
+      - name: Install utoo
+        uses: utooland/setup-utoo@3a51006d0b66afcc32d1b9177a4b200b74f4a8cb # pinned from main
 
       - name: Set up Node.js
         uses: actions/setup-node@6044e13b5dc448c55e2357c09f80417699197238 # v6
         with:
           node-version: ${{ matrix.project.node-version }}
 
       - name: Install dependencies
-        run: pnpm install --no-frozen-lockfile
+        run: ut install --from pnpm || (sleep 5 && ut install --from pnpm) || (sleep 10 && ut install --from pnpm)
 
       - name: Build all packages
-        env:
-          # publint pack defaults to npm (main CI env has no pnpm); in E2E we
-          # already have pnpm installed and npm pack against pnpm's symlinked
-          # node_modules is ~10x slower, so prefer pnpm pack here
-          PUBLINT_PACK: pnpm
-        run: pnpm build
+        run: ut run build
+
+      - name: Install pnpm (for `pnpm -r pack`)
+        # utoo's `ut pm-pack` does not resolve `workspace:` / `catalog:`
+        # protocols inside the packed manifests, so downstream `npm install`
+        # in the ecosystem-ci projects fails with EUNSUPPORTEDPROTOCOL.
+        # Keep pnpm available just for the pack step. The root packageManager
+        # pins the pnpm version for this action.
+        # Setup must come AFTER `ut install`: action-setup exports PNPM_HOME,
+        # which makes utoo's install path read pnpm config and crash with
+        # exit 141 (SIGPIPE).
+        uses: pnpm/action-setup@41ff72655975bd51cab0327fa583b6e92b6d3061 # v4
 
       - name: Pack packages into tgz
+        # `pnpm -r pack` resolves workspace:/catalog: deps in the emitted
+        # manifests, which `ut pm-pack` does not yet do. pnpm needs its own
+        # node_modules layout to resolve `workspace:` versions, so run
+        # `pnpm install --no-frozen-lockfile` first (cheap on top of the
+        # ut install since the deps are already in the global store).
         run: |
+          pnpm install --no-frozen-lockfile --ignore-scripts
           pnpm -r pack
 
       - name: Override dependencies from tgz in ${{ matrix.project.name }}

.github/workflows/release.yml

@@ -62,8 +62,8 @@ jobs:
           fetch-depth: 0
           token: ${{ secrets.GIT_TOKEN }}
 
-      - name: Setup pnpm
-        uses: pnpm/action-setup@41ff72655975bd51cab0327fa583b6e92b6d3061 # v4
+      - name: Setup utoo
+        uses: utooland/setup-utoo@3a51006d0b66afcc32d1b9177a4b200b74f4a8cb # pinned from main
 
       - name: Setup Node.js
         uses: actions/setup-node@6044e13b5dc448c55e2357c09f80417699197238 # v6
@@ -72,7 +72,10 @@ jobs:
           registry-url: 'https://registry.npmjs.org'
 
       - name: Install dependencies
-        run: pnpm install --no-frozen-lockfile
+        run: |
+          ut install --from pnpm || (sleep 5 && ut install --from pnpm) || (sleep 10 && ut install --from pnpm)
+          git restore package.json
+          git diff --exit-code -- package.json
 
       - name: Configure Git
         run: |
@@ -149,7 +152,7 @@ jobs:
           git push origin ${{ github.event.inputs.branch }} --tags
 
       - name: Run build
-        run: pnpm build
+        run: ut run build
 
       - name: Publish packages (dry run)
         if: ${{ github.event.inputs.dry_run == 'true' }}

AGENTS.md

@@ -6,7 +6,7 @@ If another agent-specific file exists, it should import or defer to this file fo
 
 ## Project Map
 
-Egg is maintained as a pnpm monorepo.
+Egg is maintained as a utoo monorepo.
 
 - `packages/` contains core framework packages and shared internals.
 - `plugins/` contains optional Egg integrations.
@@ -18,16 +18,17 @@ Egg is maintained as a pnpm monorepo.
 
 ## Core Commands
 
-- `pnpm install` hydrates the workspace.
-- `pnpm run build` builds all packages.
-- `pnpm run test` runs the main test suite.
-- `pnpm run lint` runs linting.
-- `pnpm run typecheck` runs TypeScript checking.
-- use filtered commands for focused work, for example `pnpm --filter=egg run test` or `pnpm --filter=site run dev`.
+- `corepack enable utoo` enables utoo on a clean machine.
+- `ut install --from pnpm` hydrates the workspace from the pnpm lock/workspace files.
+- `ut run build` builds all packages.
+- `ut run test` runs the main test suite.
+- `ut run lint` runs linting.
+- `ut run typecheck` runs TypeScript checking.
+- use filtered commands for focused work, for example `ut --filter=egg run test` or `ut --filter=site run dev`.
 
 ### Local CI
 
-Run tests **without building first**. The CI workflow (`ut install → ut run ci`) never runs `build` before tests. If `dist/` directories exist from a prior build, tegg plugin tests will fail with `duplicate proto` errors because globby scans both `src/*.ts` and `dist/*.js`, loading the same decorated class twice.
+Run tests **without building first**. The CI workflow (`ut install --from pnpm → ut run ci`) never runs `build` before tests. If `dist/` directories exist from a prior build, tegg plugin tests will fail with `duplicate proto` errors because globby scans both `src/*.ts` and `dist/*.js`, loading the same decorated class twice.
 
 When you see `duplicate proto` failures locally:
 
@@ -65,7 +66,7 @@ Then re-run tests.
 
 - review `SECURITY.md` before handling vulnerability-related work
 - do not commit secrets, credentials, or local-only URLs
-- keep local Node.js and pnpm versions aligned with the repository configuration
+- keep local Node.js and utoo versions aligned with the repository configuration
 
 ## Shared Knowledge Workflow