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

• Step 1: List direct dependency usage

Run:

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.

• Step 2: Check outdated dependencies

Run:

pnpm outdated --format table

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

• Step 3: Classify direct dependencies

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

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

• 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:

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.