dc-recorder/docs/superpowers/plans/2026-05-14-library-modernization.md

# Library Modernization Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Modernize runtime and development dependencies while preserving Discord monitoring, recording, database migration, dashboard, and test behavior.

**Architecture:** Treat modernization as dependency classification plus small source refactors. Remove redundant validation libraries by moving `src/validation.ts` to Zod, replace `fluent-ffmpeg` with a tiny direct `ffmpeg` process wrapper for the muxer scripts, and convert database migration code to ESM-safe imports. Keep high-risk Discord/audio/native packages unless audit proves a safe replacement exists.

**Tech Stack:** Node.js, pnpm, TypeScript, Zod, Drizzle ORM, better-sqlite3, pg, Express, ws, Vite, React, Vitest, Biome, Discord voice/audio packages.

---

## Dependency Audit Baseline

- Usage audit confirms `class-transformer`/`class-validator` are only used by `src/validation.ts`.
- Usage audit confirms `fluent-ffmpeg` is only used by `src/muxer.ts` and `src/muxer-aup3.ts`.
- `pnpm outdated --format table` reports `discord.js-selfbot-v13` and `fluent-ffmpeg` as deprecated.
- Outdated packages reported: `tsx`, `@types/node`, `p-retry`, `pino`, `pino-pretty`, `sodium-native`.
- Direct dependency classification: remove `class-transformer`, `class-validator`, `fluent-ffmpeg`, `@types/fluent-ffmpeg`; replace validation with Zod and ffmpeg wrapper with `node:child_process`; upgrade outdated packages; keep high-risk voice/audio packages unless a compatible replacement is proven.

## File Structure

- Modify `package.json`: dependency upgrades, removals, and script additions if needed.
- Modify `pnpm-lock.yaml`: regenerated by `pnpm install`.
- Modify `src/validation.ts`: replace `class-transformer` and `class-validator` with Zod.
- Modify `src/database/migrate.ts`: remove dynamic CommonJS `require` and `any` cast.
- Create `src/audio/ffmpegProcess.ts`: small wrapper around `node:child_process` for direct ffmpeg execution.
- Modify `src/muxer.ts`: use `runFfmpeg()` instead of `fluent-ffmpeg`.
- Modify `src/muxer-aup3.ts`: use `runFfmpeg()` instead of `fluent-ffmpeg`.
- Modify `src/recorder/decoder.ts`: keep `createRequire()` for optional native probing unless a better ESM-safe probe is identified during implementation.
- Add or modify tests under `tests/`: validation, migration helper behavior, and ffmpeg argument construction.

---

### Task 1: Capture Dependency Audit Baseline

**Files:**
- Modify: `docs/superpowers/plans/2026-05-14-library-modernization.md`
- Inspect: `package.json`
- Inspect: `pnpm-lock.yaml`
- Inspect: `src/**/*.ts`
- Inspect: `tests/**/*.ts`

- [x] **Step 1: List direct dependency usage**

Run:

```bash
grep -R "class-transformer\|class-validator\|fluent-ffmpeg\|@discordjs/opus\|@discordjs/voice\|@snazzah/davey\|discord.js-selfbot-v13\|libsodium-wrappers\|sodium-native\|prism-media\|drizzle-orm\|better-sqlite3\|pg\|express\|helmet\|p-retry\|pino\|pino-http\|prom-client\|react\|react-dom\|vite\|ws\|zod" -n src tests frontend package.json
```

Expected: output lists every direct package usage. Record the summary in the implementation notes during execution.

- [x] **Step 2: Check outdated dependencies**

Run:

```bash
pnpm outdated --format table
```

Expected: command exits non-zero if packages are outdated; use the table as audit input, not as failure.

- [x] **Step 3: Classify direct dependencies**

Use this classification as the starting point, adjusting only if Step 1 proves a package is unused or irreplaceable:

```text
remove: class-transformer, class-validator, fluent-ffmpeg, @types/fluent-ffmpeg
replace: class-transformer/class-validator -> zod; fluent-ffmpeg -> node:child_process ffmpeg wrapper
upgrade: @vitejs/plugin-react, better-sqlite3, discord.js-selfbot-v13, dotenv, drizzle-orm, express, helmet, libsodium-wrappers, p-retry, pg, pino, pino-http, prom-client, react, react-dom, sodium-native, vite, ws, zod, @biomejs/biome, @types/*, drizzle-kit, pino-pretty, tsx, vitest
keep unless compatible alternative is proven: @discordjs/opus, @discordjs/voice, @snazzah/davey, prism-media
```

- [x] **Step 4: Commit audit note if this task changes files**

If only commands were run, do not commit. If the plan is updated with audit notes, run:

```bash
git add docs/superpowers/plans/2026-05-14-library-modernization.md
git commit -m "docs: record dependency modernization audit"
```

Expected: commit succeeds only if a file changed.

---

### Task 2: Replace Class Validator Stack With Zod

**Files:**
- Modify: `src/validation.ts`
- Test: `tests/validation.test.ts`
- Modify later: `package.json`

- [ ] **Step 1: Write failing validation tests**
- [ ] **Step 2: Run validation tests to establish baseline**
- [ ] **Step 3: Replace implementation with Zod**
- [ ] **Step 4: Run validation tests**
- [ ] **Step 5: Commit validation refactor**

---

### Task 3: Convert Migration Code to ESM-Safe Drizzle Imports

**Files:**
- Modify: `src/database/migrate.ts`
- Test: `tests/database/migrate.test.ts`

- [ ] **Step 1: Extract SQLite database creation for testing**
- [ ] **Step 2: Add migration helper test**
- [ ] **Step 3: Run migration test**
- [ ] **Step 4: Run typecheck for migration typing**
- [ ] **Step 5: Commit migration refactor**

---

### Task 4: Replace Fluent FFmpeg With Direct Process Wrapper

**Files:**
- Create: `src/audio/ffmpegProcess.ts`
- Modify: `src/muxer.ts`
- Modify: `src/muxer-aup3.ts`
- Test: `tests/audio/ffmpegProcess.test.ts`

- [ ] **Step 1: Add ffmpeg wrapper tests**
- [ ] **Step 2: Run ffmpeg wrapper test to verify it fails**
- [ ] **Step 3: Implement ffmpeg process wrapper**
- [ ] **Step 4: Refactor `src/muxer.ts`**
- [ ] **Step 5: Refactor `src/muxer-aup3.ts`**
- [ ] **Step 6: Run ffmpeg wrapper tests**
- [ ] **Step 7: Run typecheck**
- [ ] **Step 8: Commit ffmpeg refactor**

---

### Task 5: Update Package Manifest and Lockfile

**Files:**
- Modify: `package.json`
- Modify: `pnpm-lock.yaml`

- [ ] **Step 1: Remove replaced packages**
- [ ] **Step 2: Upgrade dependencies interactively-free**
- [ ] **Step 3: Ensure package manager remains pnpm 10**
- [ ] **Step 4: Run install to verify lockfile**
- [ ] **Step 5: Commit dependency manifest changes**

---

### Task 6: Fix Upgrade Breakages

**Files:**
- Modify as needed: `src/**/*.ts`
- Modify as needed: `frontend/**/*.ts`
- Modify as needed: `frontend/**/*.tsx`
- Modify as needed: `tests/**/*.ts`
- Modify as needed: config files touched by upgraded tools

- [ ] **Step 1: Run typecheck**
- [ ] **Step 2: Run lint**
- [ ] **Step 3: Run tests**
- [ ] **Step 4: Run build**
- [ ] **Step 5: Commit breakage fixes**

---

### Task 7: Final Verification and Manual Dashboard Check

**Files:**
- No planned source changes

- [ ] **Step 1: Run full verification**
- [ ] **Step 2: Start dev server for dashboard check**
- [ ] **Step 3: Manually verify frontend build path if browser access is available**
- [ ] **Step 4: Check git status**

---

## Self-Review

- Spec coverage: audit, dependency classification, replacement/removal, ESM migration, lockfile regeneration, verification, and dashboard manual check are covered.
- Placeholder scan: no `TBD`, `TODO`, or unspecified implementation steps remain.
- Type consistency: helper names are consistent across tasks: `validateUserStateUpdate`, `initializeMigrationSqliteDatabase`, `buildMuxFfmpegArgs`, and `runFfmpeg`.