# Design Document: upgrade-fixed-packages

## Overview

**Purpose**: This feature audits and upgrades version-pinned packages in `apps/app/package.json` that were frozen due to upstream bugs, ESM-only migrations, or licensing constraints. The build environment has shifted from webpack to Turbopack, and the runtime now targets Node.js 24 with stable `require(esm)` support, invalidating several original pinning reasons.

**Users**: Maintainers and developers benefit from up-to-date dependencies with bug fixes, security patches, and reduced technical debt.

**Impact**: Modifies `apps/app/package.json` dependency versions and comment blocks; touches source files where `escape-string-regexp` is replaced by native `RegExp.escape()`.

### Goals
- Verify each pinning reason against current upstream status
- Upgrade packages where the original constraint no longer applies
- Replace `escape-string-regexp` with native `RegExp.escape()` (Node.js 24)
- Update or remove comment blocks to reflect current state
- Produce audit documentation for future reference

### Non-Goals
- Replacing handsontable with an alternative library (license constraint remains; replacement is a separate initiative)
- Upgrading `@keycloak/keycloak-admin-client` to v19+ (significant API breaking changes; deferred to separate task)
- Major version upgrades of unrelated packages
- Modifying the build pipeline or Turbopack configuration

## Architecture

This is a dependency maintenance task, not a feature implementation. No new components or architectural changes are introduced.

### Existing Architecture Analysis

The pinned packages fall into distinct categories by their usage context:

| Category | Packages | Build Context |
|----------|----------|---------------|
| Server-only (tsc → CJS) | `escape-string-regexp`, `@aws-sdk/*`, `@keycloak/*` | Express server compiled by tsc |
| Client-only (Turbopack) | `string-width` (via @growi/editor), `bootstrap` | Bundled by Turbopack/Vite |
| Client + SSR | `next-themes` | Turbopack + SSR rendering |
| License-pinned | `handsontable`, `@handsontable/react` | Client-only |

Key enabler: Node.js ^24 provides stable `require(esm)` support, removing the fundamental CJS/ESM incompatibility that caused several pins.

### Technology Stack

| Layer | Choice / Version | Role in Feature | Notes |
|-------|------------------|-----------------|-------|
| Runtime | Node.js ^24 | Enables `require(esm)` and `RegExp.escape()` | ES2026 Stage 4 features available |
| Build (client) | Turbopack (Next.js 16) | Bundles ESM-only packages without issues | No changes needed |
| Build (server) | tsc (CommonJS output) | `require(esm)` handles ESM-only imports | Node.js 24 native support |
| Package manager | pnpm v10 | Manages dependency resolution | No changes needed |

## System Flows

### Upgrade Verification Flow

```mermaid
flowchart TD
    Start[Select package to upgrade] --> Update[Update version in package.json]
    Update --> Install[pnpm install]
    Install --> Build{turbo run build}
    Build -->|Pass| Lint{turbo run lint}
    Build -->|Fail| Revert[Revert package change]
    Lint -->|Pass| Test{turbo run test}
    Lint -->|Fail| Revert
    Test -->|Pass| Verify[Verify .next/node_modules symlinks]
    Test -->|Fail| Revert
    Verify --> Next[Proceed to next package]
    Revert --> Document[Document failure reason]
    Document --> Next
```

Each package is upgraded and verified independently. Failures are isolated and reverted without affecting other upgrades.

## Requirements Traceability

| Requirement | Summary | Components | Action |
|-------------|---------|------------|--------|
| 1.1 | Bootstrap bug investigation | PackageAudit | Verify #39798 fixed in v5.3.4 |
| 1.2 | next-themes issue investigation | PackageAudit | Verify #122 resolved; check v0.4.x compatibility |
| 1.3 | @aws-sdk constraint verification | PackageAudit | Confirm mongodb constraint is on different package |
| 1.4 | Document investigation results | AuditReport | Summary table in research.md |
| 2.1 | ESM compatibility per package | PackageAudit | Assess escape-string-regexp, string-width, @keycloak |
| 2.2 | Server build ESM support | PackageAudit | Verify Node.js 24 require(esm) for server context |
| 2.3 | Client build ESM support | PackageAudit | Confirm Turbopack handles ESM-only packages |
| 2.4 | Compatibility matrix | AuditReport | Table in research.md |
| 3.1 | Handsontable license check | PackageAudit | Confirm v7+ still non-MIT |
| 3.2 | Document pinning requirement | AuditReport | Note in audit summary |
| 4.1 | Update package.json versions and comments | UpgradeExecution | Modify versions and comment blocks |
| 4.2 | Build verification | UpgradeExecution | `turbo run build --filter @growi/app` |
| 4.3 | Lint verification | UpgradeExecution | `turbo run lint --filter @growi/app` |
| 4.4 | Test verification | UpgradeExecution | `turbo run test --filter @growi/app` |
| 4.5 | Revert on failure | UpgradeExecution | Git revert per package |
| 4.6 | Update comment blocks | UpgradeExecution | Remove or update comments |
| 5.1 | Audit summary table | AuditReport | Final summary with decisions |
| 5.2 | Document continued pinning | AuditReport | Reasons for remaining pins |
| 5.3 | Document upgrade rationale | AuditReport | What changed upstream |

## Components and Interfaces

| Component | Domain | Intent | Req Coverage | Key Dependencies |
|-----------|--------|--------|--------------|------------------|
| PackageAudit | Investigation | Research upstream status for each pinned package | 1.1–1.4, 2.1–2.4, 3.1–3.2 | GitHub issues, npm registry |
| UpgradeExecution | Implementation | Apply version changes and verify build | 4.1–4.6 | pnpm, turbo, tsc |
| SourceMigration | Implementation | Replace escape-string-regexp with RegExp.escape() | 4.1 | 9 source files |
| AuditReport | Documentation | Produce summary of all decisions | 5.1–5.3 | research.md |

### Investigation Layer

#### PackageAudit

| Field | Detail |
|-------|--------|
| Intent | Investigate upstream status of each pinned package and determine upgrade feasibility |
| Requirements | 1.1, 1.2, 1.3, 1.4, 2.1, 2.2, 2.3, 2.4, 3.1, 3.2 |

**Responsibilities & Constraints**
- Check upstream issue trackers for bug fix status
- Verify ESM compatibility against Node.js 24 `require(esm)` and Turbopack
- Confirm license status for handsontable
- Produce actionable recommendation per package

**Audit Decision Matrix**

| Package | Current | Action | Target | Risk | Rationale |
|---------|---------|--------|--------|------|-----------|
| `bootstrap` | `=5.3.2` | Upgrade | `^5.3.4` | Low | Bug #39798 fixed in v5.3.4 |
| `next-themes` | `^0.2.1` | Upgrade | `^0.4.4` | Medium | Original issue was misattributed; v0.4.x works with Pages Router |
| `escape-string-regexp` | `^4.0.0` | Replace | Remove dep | Low | Native `RegExp.escape()` in Node.js 24 |
| `string-width` | `=4.2.2` | Upgrade | `^7.0.0` | Low | Used only in ESM context (@growi/editor) |
| `@aws-sdk/client-s3` | `3.454.0` | Relax | `^3.454.0` | Low | Pinning comment was misleading |
| `@aws-sdk/s3-request-presigner` | `3.454.0` | Relax | `^3.454.0` | Low | Same as above |
| `@keycloak/keycloak-admin-client` | `^18.0.0` | Defer | No change | N/A | API breaking changes; separate task |
| `handsontable` | `=6.2.2` | Keep | No change | N/A | License constraint (non-MIT since v7) |
| `@handsontable/react` | `=2.1.0` | Keep | No change | N/A | Requires handsontable >= 7 |

### Implementation Layer

#### UpgradeExecution

| Field | Detail |
|-------|--------|
| Intent | Apply version changes incrementally with build verification |
| Requirements | 4.1, 4.2, 4.3, 4.4, 4.5, 4.6 |

**Responsibilities & Constraints**
- Upgrade one package at a time to isolate failures
- Run full verification suite (build, lint, test) after each change
- Revert and document any package that causes failures
- Update `// comments for dependencies` block to reflect new state

**Upgrade Order** (lowest risk first):
1. `@aws-sdk/*` — relax version range (no code changes)
2. `string-width` — upgrade in @growi/editor (isolated ESM package)
3. `bootstrap` — upgrade to ^5.3.4 (verify SCSS compilation)
4. `escape-string-regexp` → `RegExp.escape()` — source code changes across 9 files
5. `next-themes` — upgrade to ^0.4.x (review API changes across 12 files)

**Implementation Notes**
- After each upgrade, verify `.next/node_modules/` symlinks for Turbopack externalisation compliance (per `package-dependencies` rule)
- For bootstrap: run `pnpm run pre:styles-commons` and `pnpm run pre:styles-components` to verify SCSS compilation
- For next-themes: review v0.3.0 and v0.4.0 changelogs for breaking API changes before modifying code

#### SourceMigration

| Field | Detail |
|-------|--------|
| Intent | Replace all `escape-string-regexp` usage with native `RegExp.escape()` |
| Requirements | 4.1 |

**Files to Modify**:

`apps/app/src/` (6 files):
- `server/models/page.ts`
- `server/service/page/index.ts`
- `server/service/page-grant.ts`
- `server/routes/apiv3/users.js`
- `server/models/obsolete-page.js`
- `features/openai/server/services/openai.ts`

`packages/` (3 files):
- `packages/core/src/utils/page-path-utils/` (2 files)
- `packages/remark-lsx/src/server/routes/list-pages/index.ts`

**Migration Pattern**:
```typescript
// Before
import escapeStringRegexp from 'escape-string-regexp';
const pattern = new RegExp(escapeStringRegexp(input));

// After
const pattern = new RegExp(RegExp.escape(input));
```

**Implementation Notes**
- Remove `escape-string-regexp` from `apps/app/package.json` dependencies after migration
- Remove from `packages/core/package.json` and `packages/remark-lsx/package.json` if listed
- Verify `RegExp.escape()` TypeScript types are available (may need `@types/node` update or lib config)

### Documentation Layer

#### AuditReport

| Field | Detail |
|-------|--------|
| Intent | Document all audit decisions for future maintainers |
| Requirements | 5.1, 5.2, 5.3 |

**Deliverables**:
- Updated `// comments for dependencies` in package.json (only retained pins with current reasons)
- Updated `// comments for defDependencies` (handsontable entries unchanged)
- Summary in research.md with final decision per package

**Updated Comment Blocks** (target state):

```json
{
  "// comments for dependencies": {
    "@keycloak/keycloak-admin-client": "19.0.0 or above exports only ESM. API breaking changes require separate migration effort.",
    "next-themes": "(if upgrade fails) Document specific failure reason here"
  },
  "// comments for defDependencies": {
    "@handsontable/react": "v3 requires handsontable >= 7.0.0.",
    "handsontable": "v7.0.0 or above is no longer MIT license."
  }
}
```

Note: The exact final state depends on which upgrades succeed. If all planned upgrades pass, only `@keycloak` and `handsontable` entries remain.

## Testing Strategy

### Build Verification (per package)
- `turbo run build --filter @growi/app` — Turbopack client build + tsc server build
- `ls apps/app/.next/node_modules/ | grep <package>` — Externalisation check
- `pnpm run pre:styles-commons` — SCSS compilation (bootstrap only)

### Lint Verification (per package)
- `turbo run lint --filter @growi/app` — TypeScript type check + Biome

### Unit/Integration Tests (per package)
- `turbo run test --filter @growi/app` — Full test suite
- For `RegExp.escape()` migration: run tests for page model, page service, page-grant service specifically

### Regression Verification (final)
- Full build + lint + test after all upgrades applied together
- Verify `.next/node_modules/` symlink integrity via `check-next-symlinks.sh` (if available locally)

## Migration Strategy

```mermaid
flowchart LR
    Phase1[Phase 1: Low Risk] --> Phase2[Phase 2: Medium Risk]
    Phase1 --> P1a[aws-sdk relax range]
    Phase1 --> P1b[string-width upgrade]
    Phase2 --> P2a[bootstrap upgrade]
    Phase2 --> P2b[escape-string-regexp replace]
    Phase2 --> P2c[next-themes upgrade]
```

- **Phase 1** (low risk): @aws-sdk range relaxation, string-width upgrade — minimal code changes
- **Phase 2** (medium risk): bootstrap, escape-string-regexp replacement, next-themes — requires code review and/or source changes
- Each upgrade is independently revertible
- Deferred: @keycloak (high risk, separate task)
- No change: handsontable (license constraint)