chore: add git-branch-porter skill for Claude Code (#407)

## Summary
- Add a project-level Claude Code skill (`git-branch-porter`) that
documents the workflow for porting commits between divergent long-lived
branches (e.g., master → next)
- Includes reference docs for CJS→ESM conversion patterns and pnpm
catalog/dedupe troubleshooting
- Skill is auto-loaded by Claude Code from `.claude/skills/` when
working in this repo

## Files
```
.claude/skills/git-branch-porter/
├── SKILL.md                        # 7-step porting workflow
└── references/
    ├── esm-patterns.md             # CJS → ESM conversion catalog
    └── pnpm-troubleshooting.md     # pnpm workspace fixes
```

## Test plan
- [x] Skill validates and packages successfully via skill-creator
- [x] Claude Code loads the skill from project `.claude/skills/`
directory

🤖 Generated with [Claude Code](https://claude.com/claude-code)

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

## Summary by CodeRabbit

* **Documentation**
* Added Git Branch Porter workflow guide with step-by-step instructions
for cherry-picking commits across branches
  * Added ESM conversion patterns reference with code examples
* Added pnpm workspace troubleshooting guide covering dependency
management and configuration best practices

<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Co-authored-by: killa <killa07071201@gmail.com>
Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>

Author: 4 people

.claude/skills/git-branch-porter/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: git-branch-porter
+description: Port (cherry-pick) commits between long-lived divergent branches in monorepos, especially CJS-to-ESM migrations. Use when asked to backport, forward-port, or cherry-pick batches of commits across branches that have diverged significantly (e.g., master → next). Covers git worktree setup, batch cherry-picking, ESM conversion, pnpm workspace/catalog fixes, test troubleshooting, and CI verification.
+---
+
+# Git Branch Porter
+
+Port commits between divergent long-lived branches in a monorepo, handling module system differences (CJS → ESM), dependency management, and CI.
+
+## Workflow
+
+### 1. Setup
+
+Use a **git worktree** to work on the target branch without disturbing the main checkout:
+
+```bash
+git worktree add ../repo-port target-branch
+cd ../repo-port
+git checkout -b port/source-to-target
+git remote add fork git@github.com:USER/REPO.git  # if using a fork
+```
+
+### 2. Identify Commits
+
+Find commits on the source branch not yet on the target:
+
+```bash
+# From target branch, find divergence point
+git log --oneline target-branch..source-branch
+```
+
+Review each commit to assess portability. Skip version bumps (`chore(release)`) and commits already applied.
+
+### 3. Batch Cherry-Pick
+
+Cherry-pick in small batches (5-10 commits) for manageable conflict resolution:
+
+```bash
+git cherry-pick <oldest>^..<newest> --no-commit
+# Resolve conflicts, then:
+git commit --no-verify -m "port: batch N - description"
+```
+
+Use `--no-commit` to stage all changes, fix ESM issues, then commit once. When conflicts arise, prefer the target branch's patterns (ESM) over the source's (CJS).
+
+### 4. Apply ESM Fixes
+
+After cherry-picking CJS code onto an ESM branch, apply conversions. See [references/esm-patterns.md](references/esm-patterns.md) for the complete pattern catalog.
+
+Key conversions:
+- `require()` → `import` / `import type`
+- `module.exports` → `export default`
+- Add `.ts` extensions to relative imports
+- `__dirname` → `import.meta.dirname`
+- Router/config files: convert to `export default` function
+
+### 5. Fix Dependencies
+
+pnpm workspaces with `catalog:` protocol need special attention when versions drift. See [references/pnpm-troubleshooting.md](references/pnpm-troubleshooting.md) for common issues.
+
+Key patterns:
+- Pin floating dist-tags to exact versions in `pnpm-workspace.yaml` catalog
+- Use pnpm `overrides` in root `package.json` for transitive dependency control
+- Run `pnpm dedupe` after changes, verify with `pnpm dedupe --check`
+- Add package `exports` entries when downstream packages need new entry points
+
+### 6. Test & Verify
+
+Run the full test suite locally before pushing:
+
+```bash
+pnpm test              # vitest (core packages)
+pnpm run test:mocha    # mocha (plugin packages)
+pnpm dedupe --check    # lockfile consistency
+```
+
+Common test fixes:
+- Increase timeouts for app boot under concurrent load: `beforeAll(fn, 30_000)`
+- Fix import paths in test fixtures (CJS → ESM)
+- Update mock configurations for ESM module loading
+
+### 7. Push & CI
+
+```bash
+git push fork port/source-to-target
+gh pr create --base target-branch --title "port: commits from source"
+gh pr checks <PR_NUMBER>          # monitor CI
+gh run view <RUN_ID> --log-failed # inspect failures
+```
+
+## Tips
+
+- Use `--no-verify` when pre-commit hooks fail due to cross-branch incompatibilities; run lint separately before the final push
+- Commit after each batch for easier bisection if issues arise
+- When `pnpm dedupe --check` fails in CI but passes locally, check for `--frozen-lockfile` differences — CI uses frozen lockfile which preserves exact lockfile state
+- For packages that need new export paths, add them to both `exports` in `package.json` and create the corresponding source file

.claude/skills/git-branch-porter/references/esm-patterns.md

@@ -0,0 +1,160 @@
+# ESM Conversion Patterns
+
+Pattern catalog for converting CJS code to ESM when cherry-picking between branches.
+
+## Import Conversions
+
+### require → import
+
+```javascript
+// CJS
+const { Foo, Bar } = require('./foo');
+const baz = require('baz');
+
+// ESM
+import { Foo, Bar } from './foo.ts';
+import baz from 'baz';
+```
+
+### Type-only imports
+
+```typescript
+// CJS
+const { SomeType } = require('./types');
+
+// ESM — use `import type` when the import is only used in type positions
+import type { SomeType } from './types.ts';
+```
+
+### Dynamic require → dynamic import
+
+```javascript
+// CJS
+const mod = require(dynamicPath);
+
+// ESM
+const mod = await import(dynamicPath);
+```
+
+## Export Conversions
+
+### module.exports → export default
+
+```javascript
+// CJS
+module.exports = function(app) { ... };
+
+// ESM
+export default function(app) { ... };
+```
+
+### Named exports
+
+```javascript
+// CJS
+exports.foo = foo;
+exports.bar = bar;
+
+// ESM
+export { foo, bar };
+```
+
+## Path & Globals
+
+### __dirname / __filename
+
+```javascript
+// CJS
+const dir = __dirname;
+const file = __filename;
+
+// ESM (Node 20.11+ / 21.2+)
+const dir = import.meta.dirname;
+const file = import.meta.filename;
+
+// ESM (Node < 20.11)
+import { fileURLToPath } from 'node:url';
+import { dirname } from 'node:path';
+const file = fileURLToPath(import.meta.url);
+const dir = dirname(file);
+```
+
+### Relative import extensions
+
+In ESM source (TypeScript with `"type": "module"`), relative imports must include the file extension:
+
+```typescript
+// Wrong
+import { Foo } from './foo';
+
+// Correct — use .ts in source when TypeScript resolves .ts files directly
+import { Foo } from './foo.ts';
+
+// Correct — use .js when TypeScript emits .js files (outDir build)
+import { Foo } from './foo.js';
+```
+
+Check the project's `tsconfig.json` `moduleResolution` and build setup to determine which extension to use.
+
+## Egg.js-Specific Patterns
+
+### Router files
+
+```typescript
+// CJS
+module.exports = app => {
+  app.router.get('/', app.controller.home.index);
+};
+
+// ESM
+import type { Application } from 'egg';
+export default (app: Application) => {
+  app.router.get('/', app.controller.home.index);
+};
+```
+
+### Config files
+
+```typescript
+// CJS
+module.exports = appInfo => {
+  const config = {};
+  config.keys = appInfo.name;
+  return config;
+};
+
+// ESM
+import type { EggAppConfig } from 'egg';
+export default (appInfo: { name: string }) => {
+  const config = {} as Partial<EggAppConfig>;
+  config.keys = appInfo.name;
+  return config;
+};
+```
+
+### Plugin config
+
+```typescript
+// CJS
+exports.tegg = { enable: true, package: '@eggjs/tegg-plugin' };
+
+// ESM
+export const tegg = { enable: true, package: '@eggjs/tegg-plugin' };
+```
+
+## Test Fixture Conversions
+
+Test fixtures often have their own `package.json`. Ensure:
+- `"type": "module"` is set
+- All imports use ESM syntax
+- Mock setup uses ESM-compatible patterns
+
+```typescript
+// CJS test
+const mm = require('egg-mock');
+const assert = require('assert');
+
+// ESM test
+import { strict as assert } from 'node:assert';
+import mm from '@eggjs/mock';
+```

.claude/skills/git-branch-porter/references/pnpm-troubleshooting.md

@@ -0,0 +1,110 @@
+# pnpm Workspace Troubleshooting
+
+Common issues when porting commits in pnpm monorepos with catalog mode.
+
+## Floating Dist-Tags Resolve to Incompatible Versions
+
+**Problem**: Catalog uses floating dist-tags like `egg: beta` which resolve to the latest beta. Over time, the resolved version changes and may be incompatible.
+
+**Symptom**: `pnpm install --force` or `pnpm dedupe` upgrades transitive dependencies, breaking tests with errors like `GlobalGraph.instance is not set` or bundled plugin conflicts.
+
+**Fix**: Pin exact versions in both catalog and overrides:
+
+```yaml
+# pnpm-workspace.yaml
+catalog:
+  egg: 4.1.0-beta.26          # was: beta
+  '@eggjs/mock': 7.0.0-beta.26
+  '@eggjs/bin': 8.0.0-beta.26
+```
+
+```json
+// package.json
+{
+  "pnpm": {
+    "overrides": {
+      "egg": "4.1.0-beta.26",
+      "@eggjs/mock": "7.0.0-beta.26",
+      "@eggjs/bin": "8.0.0-beta.26"
+    }
+  }
+}
+```
+
+**Why both?** Catalog pins affect workspace packages. Overrides affect transitive dependencies from published packages (e.g., `standalone` → `egg@beta` → `@eggjs/ajv-plugin@beta.36`).
+
+**Note on catalog and publishing**: `catalog:` protocol is resolved to actual versions at publish time. Pinning in catalog affects what gets published. Overrides are workspace-only and don't affect published packages.
+
+## pnpm dedupe --check Fails in CI but Passes Locally
+
+**Problem**: CI uses `pnpm install --frozen-lockfile` which preserves the exact lockfile, while local `pnpm install` may subtly adjust resolution.
+
+**Common causes**:
+1. Peer dependency resolution differences (e.g., `axios@1.13.5` vs `axios@1.13.5(debug@4.4.3)`)
+2. Different pnpm store state between local and CI
+
+**Fix approaches**:
+1. Run `pnpm dedupe` locally, commit the updated lockfile
+2. If dedupe creates a circular issue (fix → check → wants reverse), try:
+   - Add overrides for the problematic package
+   - Delete `node_modules` and `pnpm-lock.yaml`, run fresh `pnpm install`, then `pnpm dedupe`
+   - Pin the problematic transitive dependency version
+
+## Adding New Package Export Paths
+
+**Problem**: A published package at version X doesn't export a path that downstream packages need (e.g., `@eggjs/ajv-plugin@beta.36` imports `@eggjs/tegg-plugin/types` but the workspace version doesn't export it).
+
+**Fix**: Add the export in the workspace package:
+
+```json
+// plugin/tegg/package.json
+{
+  "exports": {
+    ".": "./src/index.ts",
+    "./types": "./src/types.ts",    // add new export
+    "./package.json": "./package.json"
+  }
+}
+```
+
+Create the source file if it doesn't exist. For example, `plugin/ajv` needs to re-export types from `@eggjs/tegg-plugin`:
+
+```typescript
+// plugin/ajv/src/types.ts
+export {}; // This creates an empty module. If re-exporting, change to 'export * from ...'
+```
+
+## Bundled Dependencies in Newer Versions
+
+**Problem**: A newer version of a package (e.g., `egg@4.1.0-beta.36`) bundles sub-packages (like `@eggjs/aop-plugin`, `@eggjs/eventbus-plugin`) that conflict with workspace versions.
+
+**Symptom**: Published bundled packages have `GlobalGraph.instance` assertions that fail because they get a different `GlobalGraph` singleton from the workspace packages.
+
+**Fix**: Pin to the older version that doesn't bundle these packages, using both catalog pins and overrides as described above.
+
+## Test Timeout Issues Under Concurrent Load
+
+**Problem**: vitest runs tests concurrently. App boot in `beforeAll` hooks can take >5s under load, exceeding the default 5000ms timeout.
+
+**Fix**: Add explicit timeouts to slow hooks:
+
+```typescript
+// vitest
+beforeAll(async () => {
+  app = mm.app({ baseDir: '...' });
+  await app.ready();
+}, 30_000);  // 30 second timeout
+
+it('slow test', async () => {
+  // ...
+}, 30_000);
+```
+
+For mocha, set timeout in the describe/it block:
+
+```typescript
+describe('suite', function() {
+  this.timeout(30000);
+  // ...
+});
+```