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

## Summary
- switch documented repository workflows from pnpm to utoo/ut
- update CI/release/E2E workflow commands for utoo install/build paths
- address review feedback from #5961 by making release install
retry-safe and making `ut create egg@beta` the primary package README
quickstart command

This supersedes #5961 because the local OAuth git push path cannot
update workflow files on the fork branch without `workflow` scope.

## Tests
- `ut install --from pnpm`
- `ut run fmtcheck -- .github/workflows/release.yml
packages/egg/README.md`
- `ut run lint`

## Notes
- `git commit` used `--no-verify` locally because the repo pre-commit
hook runs `oxlint --type-aware --fix` on a Markdown/YAML-only staged set
and fails with `No files found to lint`; full `ut run lint` passed.

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **Documentation**
* Updated development and quickstart guides to reflect new monorepo
tooling workflow.
  * Updated CI/CD workflows and build processes for new tooling.
  * Refreshed command examples across all documentation and guides.

* **Chores**
  * Node.js minimum version requirement increased to 22.18.0+.
  * Monorepo tooling updated from `pnpm` to `utoo` (`ut` CLI).
  * Development and build commands updated accordingly.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: killagu

.github/copilot-instructions.md

@@ -6,33 +6,33 @@
 
 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 >= 22.18.0 required** - This is a hard requirement
-- Enable pnpm first: `corepack enable pnpm` (uses the `packageManager` version from `package.json`, currently pnpm v10.28.0)
+- Enable utoo first: `corepack enable utoo`
 - **NEVER CANCEL** any build or test commands - they can take several minutes to complete
 
 ## Bootstrap and Build Process
 
 **Run these commands after a 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. Run pnpm run lint to check code quality across all packages - takes ~2 seconds
-pnpm run lint
+# 3. Run lint to check code quality across all packages - takes ~2 seconds
+ut run lint
 
 # 4. Build all packages when validating build output - takes ~14 seconds. NEVER CANCEL. Set timeout to 60+ seconds.
-pnpm run build
+ut run build
 ```
 
-Run unit tests from a clean source tree, not immediately after `pnpm run build`.
+Run unit tests from a clean source tree, not immediately after `ut run build`.
 The main CI test job installs dependencies with `ut install --from pnpm` and
 runs tests with `ut run ci`; it does not run `build` before tests.
 
@@ -52,44 +52,44 @@ runs tests with `ut run ci`; it does not run `build` before tests.
 ### 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 tests with coverage (~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.1 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
@@ -111,17 +111,17 @@ pnpm --filter=site run dev
 **Always perform these validation steps after making changes:**
 
 ```bash
-# 1. Run pnpm run lint to check code quality across all packages
-pnpm run lint
+# 1. Run lint to check code quality across all packages
+ut run lint
 
 # 2. Run tests from a clean tree (some failures are expected in fresh environment)
-pnpm run test
+ut run test
 
 # 3. Build all packages when build output or packaging behavior is relevant
-pnpm run build
+ut run build
 
 # 4. Test documentation site when docs changed
-pnpm run site:dev
+ut run site:dev
 ```
 
 ### 3. Testing Strategy
@@ -166,7 +166,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:"`
@@ -187,7 +187,7 @@ pnpm run site:dev
 
 ### Build Issues
 
-- Run `pnpm run build` when validating build output, package exports, or changes
+- Run `ut run build` when validating build output, package exports, or changes
   that affect generated artifacts.
 - TypeScript compilation errors will show clearly
 - Build warnings are generally acceptable
@@ -226,10 +226,10 @@ pnpm run site:dev
 
 After making changes, always verify:
 
-1. **Linting Passes**: `pnpm run lint` shows no new errors
-2. **Tests Run From Clean Sources**: `pnpm run test` executes without stale build artifacts interfering
-3. **Documentation Loads**: `pnpm run site:dev` starts successfully and site loads at http://localhost:8000
-4. **Build Success When Relevant**: `pnpm run build` completes without errors
+1. **Linting Passes**: `ut run lint` shows no new errors
+2. **Tests Run From Clean Sources**: `ut run test` executes without stale build artifacts interfering
+3. **Documentation Loads**: `ut run site:dev` starts successfully and the printed VitePress URL responds
+4. **Build Success When Relevant**: `ut run build` completes without errors
 
 **Remember**: This is a complex enterprise framework. Validate incrementally, keep unit tests isolated from stale build artifacts, and focus on the core packages (`egg`, `core`, `utils`) for most development work.
 

.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
+          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.
@@ -20,6 +20,7 @@ Egg is maintained as a pnpm monorepo.
 
 The repository runs on [utoo](https://github.com/utooland/utoo) (`ut`); the workspace is still defined in `pnpm-workspace.yaml` (catalog mode), so `ut install` reads it via `--from pnpm`.
 
+- `corepack enable utoo` enables utoo on a clean machine.
 - `ut install --from pnpm` hydrates the workspace.
 - `ut run build` builds all packages.
 - `ut run test` runs the main test suite.
@@ -29,7 +30,7 @@ The repository runs on [utoo](https://github.com/utooland/utoo) (`ut`); the work
 
 ### 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:
 

README.md

@@ -27,72 +27,73 @@ English | [简体中文](./README.zh-CN.md)
 Follow the commands listed below.
 
 ```bash
+$ corepack enable utoo
 $ mkdir showcase && cd showcase
-$ pnpm create egg@beta
-$ pnpm install
-$ pnpm run dev
+$ ut create egg@beta
+$ ut install
+$ ut run dev
 $ open http://localhost:7001
 ```
 
-> Node.js >= 20.19.0 required, [supports `require(esm)` by default](https://nodejs.org/en/blog/release/v20.19.0).
+> Node.js >= 22.18.0 required.
 
 ## Monorepo Structure
 
-This project is structured as a pnpm monorepo with the following packages:
+This project is structured as a utoo monorepo with the following packages:
 
 - `packages/egg` - Main Eggjs framework
 - `examples/helloworld-commonjs` - CommonJS example application
 - `examples/helloworld-typescript` - TypeScript example application
 - `site` - Documentation website
 
-The monorepo uses **pnpm catalog mode** for centralized dependency management, ensuring consistent versions across all packages.
+The monorepo uses **utoo catalog mode** for centralized dependency management, ensuring consistent versions across all packages.
 
 ### Development Commands
 
 ```bash
 # Install dependencies for all packages
-pnpm install
+ut install --from pnpm
 
 # Build all packages
-pnpm run build
+ut run build
 
 # Test all packages
-pnpm run test
+ut run test
 
 # Run specific package commands
-pnpm --filter=egg run test
-pnpm --filter=@examples/helloworld-typescript run dev
-pnpm --filter=site run dev
+ut --filter=egg run test
+ut --filter=@examples/helloworld-typescript run dev
+ut --filter=site run dev
 ```
 
 ### Local External Services
 
 Some DAL, ORM, Redis, and ecosystem benchmark paths need local MySQL and Redis services. Start the repository-aligned Docker services before running those tests on a clean machine:
 
 ```bash
-utoo run dev:services:start
+ut run dev:services:start
 ```
 
 This starts MySQL 8 and Redis 7, matching the main CI service versions, and creates the databases used by local DAL/ORM/e2e fixtures: `test`, `apple`, `banana`, `test_runtime_datasource`, `test_runtime_dao`, `test_dal_plugin`, `test_dal_standalone`, `cnpmcore`, and `cnpmcore_unittest`.
 
 Useful commands:
 
 ```bash
-utoo run dev:services:status
-utoo run dev:services:stop
-utoo run dev:services:reset
+ut run dev:services:status
+ut run dev:services:stop
+ut run dev:services:reset
 ```
 
 The default host ports are `127.0.0.1:3306` for MySQL and `127.0.0.1:6379` for Redis. If either port is already used, the start command stops before changing containers. Keep using the existing service if it is compatible with CI, or stop it and run the command again. You can change Docker host ports with `EGG_DEV_SERVICES_MYSQL_PORT` and `EGG_DEV_SERVICES_REDIS_PORT`; however, the full DAL/ORM/Redis local test path still expects the default host ports.
 
 Image overrides are available for compatibility checks:
 
 ```bash
-EGG_DEV_SERVICES_MYSQL_IMAGE=mysql:5.7 utoo run dev:services:start
-EGG_DEV_SERVICES_REDIS_IMAGE=redis:7 utoo run dev:services:start
+EGG_DEV_SERVICES_MYSQL_IMAGE=mysql:5.7 ut run dev:services:start
+EGG_DEV_SERVICES_REDIS_IMAGE=redis:7 ut run dev:services:start
 ```
 
-Run `utoo run dev:services:reset` before switching MySQL image families, for example between MySQL 8 and MySQL 5.7, because MySQL data directories are not downgrade-compatible across major versions.
+Run `ut run dev:services:reset` before switching MySQL image families, for example between MySQL 8 and MySQL 5.7, because MySQL data directories are not downgrade-compatible across major versions.
 
 Current hard-coded service assumptions:
 

README.zh-CN.md

@@ -21,15 +21,16 @@
 - 深度框架定制
 - 丰富的[插件](https://github.com/search?q=topic%3Aegg-plugin&type=Repositories)
 
-> 支持 Node.js >= 20.19.0 及以上版本，[默认支持 `require(esm)`](https://nodejs.org/en/blog/release/v20.19.0)。
+> 支持 Node.js >= 22.18.0 及以上版本。
 
 ## 快速开始
 
 ```bash
+corepack enable utoo
 mkdir showcase && cd showcase
-pnpm create egg@beta
-pnpm install
-pnpm run dev
+ut create egg@beta
+ut install
+ut run dev
 
 open http://localhost:7001
 ```

packages/egg/README.md

@@ -21,14 +21,17 @@
 Follow the commands listed below.
 
 ```bash
+$ corepack enable utoo
 $ mkdir showcase && cd showcase
-$ npm init egg --type=simple # Optionally pnpm create egg --type=simple
-$ pnpm install
-$ pnpm run dev
+$ ut create egg@beta
+# Or with npm:
+$ npm init egg --type=simple
+$ ut install
+$ ut run dev
 $ open http://localhost:7001
 ```
 
-> Node.js >= 20.19.0 required, [supports `require(esm)` by default](https://nodejs.org/en/blog/release/v20.19.0).
+> Node.js >= 22.18.0 required.
 
 ## Documentations
 

plugins/redis/README.md

@@ -265,10 +265,10 @@ Run docker compose to start test redis service
 docker compose -f docker-compose.yml up -d
 ```
 
-Run the unit tests
+Run the plugin unit tests from the monorepo root
 
 ```bash
-pnpm test
+ut execute vitest run plugins/redis/test/redis.test.ts --bail 1 --retry 2 --testTimeout 20000 --hookTimeout 20000
 ```
 
 Stop test redis service

scripts/dev-services.js

@@ -131,7 +131,7 @@ async function assertPortAvailable(service, port, containerPort, running) {
     throw new Error(
       [
         `${service} is already running for this compose project on ${current}, but this run requested 127.0.0.1:${port}.`,
-        'Re-run with the same EGG_DEV_SERVICES_* port override, or use `utoo run dev:services:reset` before changing ports.',
+        'Re-run with the same EGG_DEV_SERVICES_* port override, or use `ut run dev:services:reset` before changing ports.',
       ].join('\n'),
     );
   }
@@ -195,7 +195,7 @@ async function start() {
       [
         message,
         'The compose stack is still running so Docker health status and logs can be inspected.',
-        'After fixing the issue, run `utoo run dev:services:reset` to clean up before starting again.',
+        'After fixing the issue, run `ut run dev:services:reset` to clean up before starting again.',
       ].join('\n'),
       { cause: err },
     );