vibes-plug 2.5.0 → 2.11.0

package/skills/dependency-upgrade-migrator/SKILL.md

@@ -1,295 +1,301 @@
----
-name: dependency-upgrade-migrator
-description: "Expert guide for dependency upgrades, breaking change migrations, codemod automation, and package audit remediation / Panduan ahli untuk upgrade dependensi, migrasi breaking change, otomasi codemod, dan remediasi audit paket."
+---
+name: dependency-upgrade-migrator
+description: "Expert guide for dependency upgrades, breaking change migrations, codemod automation, and package audit remediation / Panduan ahli untuk upgrade dependensi, migrasi breaking change, otomasi codemod, dan remediasi audit paket."
 author: "Roedy Rustam"
----
-
-# Dependency Upgrade Migrator (2026 Edition)
-
-[English](#english) | [Bahasa Indonesia](#bahasa-indonesia)
-
----
-
-<a name="english"></a>
-## English
-
-### Description
-Production-grade guide for safely upgrading dependencies, migrating through breaking changes, and maintaining healthy dependency trees. Covers **automated upgrade tooling** (`npm-check-updates`, `taze`, Renovate Bot), **major framework migration guides** (React 18→19, Next.js 14→15, Tailwind v3→v4), **codemod automation** (jscodeshift, ts-morph), **vulnerability remediation** (`npm audit`, `pnpm audit`), **lockfile hygiene**, **monorepo alignment** (pnpm catalogs), and **breaking change detection workflows**.
-
-### Trigger Conditions
-Activate this skill when:
-- Upgrading major versions of frameworks (React, Next.js, Tailwind, etc.).
-- Running security audits and remediating vulnerabilities.
-- Setting up automated dependency update bots (Renovate, Dependabot).
-- Writing or running codemods for API migration.
-- Cleaning up dependency trees and removing unused packages.
-- Aligning dependency versions across monorepo packages.
-
----
-
-### 1. Upgrade Strategy Matrix
-
-| Upgrade Type | Risk Level | Strategy | Tools |
-|---|---|---|---|
-| **Patch** (1.0.x) | 🟢 Low | Auto-merge after tests pass | Renovate, Dependabot |
-| **Minor** (1.x.0) | 🟡 Medium | Auto-merge with manual review | Renovate + test suite |
-| **Major** (x.0.0) | 🔴 High | Manual review, migration guide, branch | Manual + codemods |
-| **Security** (any) | 🔴 Critical | Immediate upgrade, hotfix | `npm audit fix`, manual |
-
----
-
-### 2. Pre-Upgrade Checklist
-
-```markdown
-- [ ] Run `pnpm audit` / `npm audit` to identify vulnerabilities
-- [ ] Check changelog/migration guide for the target version
-- [ ] Ensure test suite is passing on current version (baseline)
-- [ ] Create a dedicated branch for the upgrade
-- [ ] Check peer dependency compatibility
-- [ ] Review breaking changes list
-- [ ] Identify files that need codemod transformation
-- [ ] Back up lockfile before changes
-```
-
----
-
-### 3. Automated Upgrade Tooling
-
-#### Checking for Updates
-```bash
-# Using taze (recommended — supports monorepos)
-npx taze major          # Show available major upgrades
-npx taze minor -w       # Auto-write minor updates to package.json
-npx taze -r             # Recursive (monorepo)
-
-# Using npm-check-updates
-npx ncu                 # Show available updates
-npx ncu -u              # Auto-write updates to package.json
-npx ncu --target minor  # Only show minor updates
-```
-
-#### Renovate Bot Configuration
-```json
-// renovate.json
-{
-  "$schema": "https://docs.renovatebot.com/renovate-schema.json",
-  "extends": ["config:best-practices"],
-  "labels": ["dependencies"],
-  "schedule": ["after 10pm and before 5am every weekday"],
-  "packageRules": [
-    {
-      "matchUpdateTypes": ["patch"],
-      "automerge": true,
-      "automergeType": "pr"
-    },
-    {
-      "matchUpdateTypes": ["minor"],
-      "automerge": true,
-      "automergeType": "pr",
-      "requiredStatusChecks": ["ci/test", "ci/build"]
-    },
-    {
-      "matchUpdateTypes": ["major"],
-      "automerge": false,
-      "labels": ["major-upgrade", "manual-review"]
-    },
-    {
-      "matchPackageNames": ["typescript", "react", "next"],
-      "automerge": false,
-      "labels": ["core-dependency"]
-    }
-  ]
-}
-```
-
----
-
-### 4. Major Framework Migration Guides
-
-#### React 18 → 19
-```typescript
-// Key breaking changes:
-// 1. forwardRef no longer needed (ref is a regular prop)
-// ❌ Before (React 18)
-const Input = forwardRef<HTMLInputElement, Props>((props, ref) => (
-  <input ref={ref} {...props} />
-));
-
-// ✅ After (React 19)
-function Input({ ref, ...props }: Props & { ref?: React.Ref<HTMLInputElement> }) {
-  return <input ref={ref} {...props} />;
-}
-
-// 2. useActionState replaces useFormState
-// ❌ Before: import { useFormState } from 'react-dom'
-// ✅ After:  import { useActionState } from 'react'
-
-// 3. use() hook for promises and context
-// ✅ New: const data = use(fetchPromise);
-// ✅ New: const theme = use(ThemeContext);
-```
-
-#### Next.js 14 → 15
-```typescript
-// Key changes:
-// 1. params/searchParams are now async in page/layout/route
-// ❌ Before: export default function Page({ params }: { params: { id: string } })
-// ✅ After:  export default async function Page({ params }: { params: Promise<{ id: string }> }) {
-//             const { id } = await params;
-
-// 2. Caching: fetch() no longer cached by default
-// ❌ Before: fetch() was cached by default
-// ✅ After:  fetch(url, { cache: 'force-cache' }) for explicit caching
-
-// 3. Route handlers: GET is no longer cached by default
-// Add: export const dynamic = 'force-static' if you want caching
-```
-
-#### Tailwind CSS v3 → v4
-```css
-/* Key changes: */
-/* 1. Configuration moves from JS to CSS */
-/* ❌ Before: tailwind.config.js with theme.extend */
-/* ✅ After: @theme directive in CSS */
-
-@import 'tailwindcss';
-
-@theme {
-  --color-primary: oklch(0.6 0.2 260);
-  --font-sans: 'Inter', sans-serif;
-  --breakpoint-sm: 40rem;
-}
-
-/* 2. No more @tailwind directives */
-/* ❌ Before: @tailwind base; @tailwind components; @tailwind utilities; */
-/* ✅ After:  @import 'tailwindcss'; */
-
-/* 3. Renamed utilities */
-/* ❌ Before: bg-opacity-50 */
-/* ✅ After:  bg-black/50 */
-```
-
----
-
-### 5. Codemod Automation (jscodeshift)
-
-```typescript
-// codemods/remove-forward-ref.ts
-import type { API, FileInfo } from 'jscodeshift';
-
-export default function removeForwardRef(fileInfo: FileInfo, api: API) {
-  const j = api.jscodeshift;
-  const root = j(fileInfo.source);
-
-  // Find all forwardRef calls and transform them
-  root.find(j.CallExpression, {
-    callee: { name: 'forwardRef' },
-  }).forEach((path) => {
-    // Extract the inner component function
-    const args = path.node.arguments;
-    if (args.length > 0 && (args[0].type === 'ArrowFunctionExpression' || args[0].type === 'FunctionExpression')) {
-      // Replace forwardRef(...) with the inner function
-      j(path).replaceWith(args[0]);
-    }
-  });
-
-  // Remove forwardRef import
-  root.find(j.ImportSpecifier, { imported: { name: 'forwardRef' } }).remove();
-
-  return root.toSource({ quote: 'single' });
-}
-
-// Run: npx jscodeshift -t codemods/remove-forward-ref.ts src/ --extensions=tsx,ts
-```
-
----
-
-### 6. Vulnerability Remediation
-
-```bash
-# Audit current state
-pnpm audit                          # Show vulnerabilities
-pnpm audit --fix                    # Auto-fix where possible
-
-# For stubborn transitive dependencies
-pnpm patch <package>@<version>      # Create a local patch
-# or
-pnpm overrides                      # Force specific version in package.json
-
-# package.json — Force resolution
-{
-  "pnpm": {
-    "overrides": {
-      "vulnerable-package": ">=2.0.0"
-    }
-  }
-}
-```
-
----
-
-### 7. Dependency Cleanup
-
-```bash
-# Find unused dependencies
-npx depcheck                        # Detect unused deps
-npx depcheck --ignores="@types/*"   # Ignore type packages
-
-# Find duplicate packages
-pnpm dedupe                         # Deduplicate lockfile
-pnpm why <package>                  # See why a package is installed
-
-# Monorepo: Align versions with pnpm catalogs
-# pnpm-workspace.yaml
-catalog:
-  react: "^19.0.0"
-  typescript: "^5.7.0"
-  "@tanstack/react-query": "^5.60.0"
-```
-
----
-
-### Common Pitfalls to Avoid
-
-| Anti-Pattern | Problem | Correct Approach |
-|---|---|---|
-| Upgrading all deps at once | Hard to identify breaking changes | Upgrade one major dep at a time |
-| Ignoring peer dependency warnings | Runtime errors, subtle bugs | Resolve all peer dep conflicts |
-| No test suite before upgrading | Can't verify nothing broke | Ensure tests pass before AND after |
-| `npm audit fix --force` blindly | Can introduce breaking changes | Review each fix manually for major bumps |
-| Skipping changelogs | Missing breaking changes | Always read CHANGELOG/migration guide |
-| No lockfile in version control | Non-reproducible builds | Always commit `pnpm-lock.yaml` |
-
----
-
-### Integration with Other Skills
-
-- `monorepo-architect` — pnpm catalogs, workspace dependency alignment
-- `vibe-code-gardener` — Post-upgrade cleanup, dead code removal
-- `production-ready-hardener` — Security audit phase
-- `ci-cd-devops-architect` — Renovate Bot CI/CD integration
-- `e2e-testing-expert` — Regression testing after major upgrades
-
----
-
-<a name="bahasa-indonesia"></a>
-## Bahasa Indonesia
-
-### Deskripsi
-Panduan tingkat produksi untuk upgrade dependensi yang aman, migrasi melalui breaking change, dan pemeliharaan dependency tree yang sehat. Mencakup **tooling upgrade otomatis** (`taze`, Renovate Bot), **panduan migrasi framework utama** (React 18→19, Next.js 14→15, Tailwind v3→v4), **otomasi codemod** (jscodeshift, ts-morph), **remediasi kerentanan** (`pnpm audit`), **kebersihan lockfile**, dan **penyelarasan dependensi monorepo** (pnpm catalogs).
-
-### Kondisi Pemicu
-Aktifkan skill ini ketika:
-- Mengupgrade versi mayor framework (React, Next.js, Tailwind, dll).
-- Menjalankan audit keamanan dan memperbaiki kerentanan.
-- Menyiapkan bot update dependensi otomatis (Renovate, Dependabot).
-- Menulis atau menjalankan codemod untuk migrasi API.
-- Membersihkan dependency tree dan menghapus paket yang tidak digunakan.
-
-### Integrasi dengan Skill Lain
-
-- `monorepo-architect` — pnpm catalogs, penyelarasan dependensi workspace
-- `vibe-code-gardener` — Pembersihan pasca-upgrade, penghapusan dead code
-- `production-ready-hardener` — Fase audit keamanan
-- `ci-cd-devops-architect` — Integrasi Renovate Bot CI/CD
-- `e2e-testing-expert` — Pengujian regresi setelah upgrade mayor
+---
+
+# Dependency Upgrade Migrator (2026 Edition)
+
+[English](#english) | [Bahasa Indonesia](#bahasa-indonesia)
+
+---
+
+<a name="english"></a>
+## English
+
+### Orchestration & Integration
+Connects and orchestrates with relevant domain skills like `brainstorming`, `zero-to-prod-orchestrator`, and `project-context-mapper` to ensure cohesive execution.
+
+### Description
+Production-grade guide for safely upgrading dependencies, migrating through breaking changes, and maintaining healthy dependency trees. Covers **automated upgrade tooling** (`npm-check-updates`, `taze`, Renovate Bot), **major framework migration guides** (React 18→19, Next.js 14→15, Tailwind v3→v4), **codemod automation** (jscodeshift, ts-morph), **vulnerability remediation** (`npm audit`, `pnpm audit`), **lockfile hygiene**, **monorepo alignment** (pnpm catalogs), and **breaking change detection workflows**.
+
+### Trigger Conditions
+Activate this skill when:
+- Upgrading major versions of frameworks (React, Next.js, Tailwind, etc.).
+- Running security audits and remediating vulnerabilities.
+- Setting up automated dependency update bots (Renovate, Dependabot).
+- Writing or running codemods for API migration.
+- Cleaning up dependency trees and removing unused packages.
+- Aligning dependency versions across monorepo packages.
+
+---
+
+### 1. Upgrade Strategy Matrix
+
+| Upgrade Type | Risk Level | Strategy | Tools |
+|---|---|---|---|
+| **Patch** (1.0.x) | 🟢 Low | Auto-merge after tests pass | Renovate, Dependabot |
+| **Minor** (1.x.0) | 🟡 Medium | Auto-merge with manual review | Renovate + test suite |
+| **Major** (x.0.0) | 🔴 High | Manual review, migration guide, branch | Manual + codemods |
+| **Security** (any) | 🔴 Critical | Immediate upgrade, hotfix | `npm audit fix`, manual |
+
+---
+
+### 2. Pre-Upgrade Checklist
+
+```markdown
+- [ ] Run `pnpm audit` / `npm audit` to identify vulnerabilities
+- [ ] Check changelog/migration guide for the target version
+- [ ] Ensure test suite is passing on current version (baseline)
+- [ ] Create a dedicated branch for the upgrade
+- [ ] Check peer dependency compatibility
+- [ ] Review breaking changes list
+- [ ] Identify files that need codemod transformation
+- [ ] Back up lockfile before changes
+```
+
+---
+
+### 3. Automated Upgrade Tooling
+
+#### Checking for Updates
+```bash
+# Using taze (recommended — supports monorepos)
+npx taze major          # Show available major upgrades
+npx taze minor -w       # Auto-write minor updates to package.json
+npx taze -r             # Recursive (monorepo)
+
+# Using npm-check-updates
+npx ncu                 # Show available updates
+npx ncu -u              # Auto-write updates to package.json
+npx ncu --target minor  # Only show minor updates
+```
+
+#### Renovate Bot Configuration
+```json
+// renovate.json
+{
+  "$schema": "https://docs.renovatebot.com/renovate-schema.json",
+  "extends": ["config:best-practices"],
+  "labels": ["dependencies"],
+  "schedule": ["after 10pm and before 5am every weekday"],
+  "packageRules": [
+    {
+      "matchUpdateTypes": ["patch"],
+      "automerge": true,
+      "automergeType": "pr"
+    },
+    {
+      "matchUpdateTypes": ["minor"],
+      "automerge": true,
+      "automergeType": "pr",
+      "requiredStatusChecks": ["ci/test", "ci/build"]
+    },
+    {
+      "matchUpdateTypes": ["major"],
+      "automerge": false,
+      "labels": ["major-upgrade", "manual-review"]
+    },
+    {
+      "matchPackageNames": ["typescript", "react", "next"],
+      "automerge": false,
+      "labels": ["core-dependency"]
+    }
+  ]
+}
+```
+
+---
+
+### 4. Major Framework Migration Guides
+
+#### React 18 → 19
+```typescript
+// Key breaking changes:
+// 1. forwardRef no longer needed (ref is a regular prop)
+// ❌ Before (React 18)
+const Input = forwardRef<HTMLInputElement, Props>((props, ref) => (
+  <input ref={ref} {...props} />
+));
+
+// ✅ After (React 19)
+function Input({ ref, ...props }: Props & { ref?: React.Ref<HTMLInputElement> }) {
+  return <input ref={ref} {...props} />;
+}
+
+// 2. useActionState replaces useFormState
+// ❌ Before: import { useFormState } from 'react-dom'
+// ✅ After:  import { useActionState } from 'react'
+
+// 3. use() hook for promises and context
+// ✅ New: const data = use(fetchPromise);
+// ✅ New: const theme = use(ThemeContext);
+```
+
+#### Next.js 14 → 15
+```typescript
+// Key changes:
+// 1. params/searchParams are now async in page/layout/route
+// ❌ Before: export default function Page({ params }: { params: { id: string } })
+// ✅ After:  export default async function Page({ params }: { params: Promise<{ id: string }> }) {
+//             const { id } = await params;
+
+// 2. Caching: fetch() no longer cached by default
+// ❌ Before: fetch() was cached by default
+// ✅ After:  fetch(url, { cache: 'force-cache' }) for explicit caching
+
+// 3. Route handlers: GET is no longer cached by default
+// Add: export const dynamic = 'force-static' if you want caching
+```
+
+#### Tailwind CSS v3 → v4
+```css
+/* Key changes: */
+/* 1. Configuration moves from JS to CSS */
+/* ❌ Before: tailwind.config.js with theme.extend */
+/* ✅ After: @theme directive in CSS */
+
+@import 'tailwindcss';
+
+@theme {
+  --color-primary: oklch(0.6 0.2 260);
+  --font-sans: 'Inter', sans-serif;
+  --breakpoint-sm: 40rem;
+}
+
+/* 2. No more @tailwind directives */
+/* ❌ Before: @tailwind base; @tailwind components; @tailwind utilities; */
+/* ✅ After:  @import 'tailwindcss'; */
+
+/* 3. Renamed utilities */
+/* ❌ Before: bg-opacity-50 */
+/* ✅ After:  bg-black/50 */
+```
+
+---
+
+### 5. Codemod Automation (jscodeshift)
+
+```typescript
+// codemods/remove-forward-ref.ts
+import type { API, FileInfo } from 'jscodeshift';
+
+export default function removeForwardRef(fileInfo: FileInfo, api: API) {
+  const j = api.jscodeshift;
+  const root = j(fileInfo.source);
+
+  // Find all forwardRef calls and transform them
+  root.find(j.CallExpression, {
+    callee: { name: 'forwardRef' },
+  }).forEach((path) => {
+    // Extract the inner component function
+    const args = path.node.arguments;
+    if (args.length > 0 && (args[0].type === 'ArrowFunctionExpression' || args[0].type === 'FunctionExpression')) {
+      // Replace forwardRef(...) with the inner function
+      j(path).replaceWith(args[0]);
+    }
+  });
+
+  // Remove forwardRef import
+  root.find(j.ImportSpecifier, { imported: { name: 'forwardRef' } }).remove();
+
+  return root.toSource({ quote: 'single' });
+}
+
+// Run: npx jscodeshift -t codemods/remove-forward-ref.ts src/ --extensions=tsx,ts
+```
+
+---
+
+### 6. Vulnerability Remediation
+
+```bash
+# Audit current state
+pnpm audit                          # Show vulnerabilities
+pnpm audit --fix                    # Auto-fix where possible
+
+# For stubborn transitive dependencies
+pnpm patch <package>@<version>      # Create a local patch
+# or
+pnpm overrides                      # Force specific version in package.json
+
+# package.json — Force resolution
+{
+  "pnpm": {
+    "overrides": {
+      "vulnerable-package": ">=2.0.0"
+    }
+  }
+}
+```
+
+---
+
+### 7. Dependency Cleanup
+
+```bash
+# Find unused dependencies
+npx depcheck                        # Detect unused deps
+npx depcheck --ignores="@types/*"   # Ignore type packages
+
+# Find duplicate packages
+pnpm dedupe                         # Deduplicate lockfile
+pnpm why <package>                  # See why a package is installed
+
+# Monorepo: Align versions with pnpm catalogs
+# pnpm-workspace.yaml
+catalog:
+  react: "^19.0.0"
+  typescript: "^5.7.0"
+  "@tanstack/react-query": "^5.60.0"
+```
+
+---
+
+### Common Pitfalls to Avoid
+
+| Anti-Pattern | Problem | Correct Approach |
+|---|---|---|
+| Upgrading all deps at once | Hard to identify breaking changes | Upgrade one major dep at a time |
+| Ignoring peer dependency warnings | Runtime errors, subtle bugs | Resolve all peer dep conflicts |
+| No test suite before upgrading | Can't verify nothing broke | Ensure tests pass before AND after |
+| `npm audit fix --force` blindly | Can introduce breaking changes | Review each fix manually for major bumps |
+| Skipping changelogs | Missing breaking changes | Always read CHANGELOG/migration guide |
+| No lockfile in version control | Non-reproducible builds | Always commit `pnpm-lock.yaml` |
+
+---
+
+### Integration with Other Skills
+
+- `monorepo-architect` — pnpm catalogs, workspace dependency alignment
+- `vibe-code-gardener` — Post-upgrade cleanup, dead code removal
+- `production-ready-hardener` — Security audit phase
+- `ci-cd-devops-architect` — Renovate Bot CI/CD integration
+- `e2e-testing-expert` — Regression testing after major upgrades
+
+---
+
+<a name="bahasa-indonesia"></a>
+## Bahasa Indonesia
+
+### Integrasi Orkestrasi
+Terhubung dan mengorkestrasi skill domain yang relevan seperti `brainstorming`, `zero-to-prod-orchestrator`, dan `project-context-mapper` untuk memastikan eksekusi yang kohesif.
+
+### Deskripsi
+Panduan tingkat produksi untuk upgrade dependensi yang aman, migrasi melalui breaking change, dan pemeliharaan dependency tree yang sehat. Mencakup **tooling upgrade otomatis** (`taze`, Renovate Bot), **panduan migrasi framework utama** (React 18→19, Next.js 14→15, Tailwind v3→v4), **otomasi codemod** (jscodeshift, ts-morph), **remediasi kerentanan** (`pnpm audit`), **kebersihan lockfile**, dan **penyelarasan dependensi monorepo** (pnpm catalogs).
+
+### Kondisi Pemicu
+Aktifkan skill ini ketika:
+- Mengupgrade versi mayor framework (React, Next.js, Tailwind, dll).
+- Menjalankan audit keamanan dan memperbaiki kerentanan.
+- Menyiapkan bot update dependensi otomatis (Renovate, Dependabot).
+- Menulis atau menjalankan codemod untuk migrasi API.
+- Membersihkan dependency tree dan menghapus paket yang tidak digunakan.
+
+### Integrasi dengan Skill Lain
+
+- `monorepo-architect` — pnpm catalogs, penyelarasan dependensi workspace
+- `vibe-code-gardener` — Pembersihan pasca-upgrade, penghapusan dead code
+- `production-ready-hardener` — Fase audit keamanan
+- `ci-cd-devops-architect` — Integrasi Renovate Bot CI/CD
+- `e2e-testing-expert` — Pengujian regresi setelah upgrade mayor