diff --git a/docs/superpowers/plans/2026-05-14-library-modernization.md b/docs/superpowers/plans/2026-05-14-library-modernization.md new file mode 100644 index 0000000..c6239e2 --- /dev/null +++ b/docs/superpowers/plans/2026-05-14-library-modernization.md @@ -0,0 +1,183 @@ +# 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`.