GMW/docs/superpowers/plans/2026-05-19-deprecated-dependency-removal.md

# Deprecated Dependency Removal 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:** Remove deprecated packages from `pnpm-lock.yaml` where maintained replacements exist, and vendor/submodule only when no clean replacement exists.

**Architecture:** Treat dependency cleanup as package graph surgery: identify owner, change one dependency source at a time, reinstall, verify lockfile, then run project checks. Existing vendored workspaces stay source of truth for selfbot and discord-video-stream patches.

**Tech Stack:** Node.js, pnpm workspaces, TypeScript, Vitest, Biome, git submodules.

---

## File Structure

- Modify: `package.json` — root dependency versions, workspace references, `pnpm.onlyBuiltDependencies`, optional `pnpm.overrides` if needed.
- Modify: `pnpm-workspace.yaml` — workspace package list for any new submodule/vendor package.
- Modify: `pnpm-lock.yaml` — regenerated by `pnpm install` only.
- Modify: `vendor/discord-video-stream/package.json` — dev dependency on `discord.js-selfbot-v13` should use workspace package instead of registry.
- Modify: `vendor/discord.js-selfbot-v13/package.json` — replace deprecated `otplib@12` chain if compatible.
- Possibly create: `vendor/<package-name>` — only if package has no maintained replacement and strict cleanup still needs local patching.

## Deprecated Package Owners

Known current owners:

```text
drizzle-kit -> @esbuild-kit/esm-loader -> @esbuild-kit/core-utils
discord.js-selfbot-v13 -> otplib@12 -> @otplib/plugin-crypto, @otplib/plugin-thirty-two, @otplib/preset-default
@discordjs/opus -> @discordjs/node-pre-gyp -> npmlog, are-we-there-yet, gauge, rimraf@3, glob@7, inflight
better-sqlite3 -> prebuild-install
@lng2004/node-datachannel -> prebuild-install
```

## Task 1: Establish Baseline

**Files:**
- Read: `package.json`
- Read: `pnpm-workspace.yaml`
- Read: `vendor/discord-video-stream/package.json`
- Read: `vendor/discord.js-selfbot-v13/package.json`

- [ ] **Step 1: Capture current git state**

Run:

```bash
git status --short
```

Expected: includes existing intended changes for `package.json`, `pnpm-workspace.yaml`, `pnpm-lock.yaml`, `.gitmodules`, and `vendor/discord-video-stream`. Do not revert user changes.

- [ ] **Step 2: Capture dependency owners**

Run:

```bash
pnpm why discord.js-selfbot-v13 @esbuild-kit/core-utils @esbuild-kit/esm-loader @otplib/plugin-crypto @otplib/plugin-thirty-two @otplib/preset-default are-we-there-yet fs-then-native gauge inflight lodash.pick npmlog prebuild-install stream-connect test-value
```

Expected: output maps deprecated packages to direct owners. Save relevant owner names in notes for next tasks.

- [ ] **Step 3: Capture install warning baseline**

Run:

```bash
pnpm install
```

Expected: install completes. Warnings may mention deprecated transitive packages.

- [ ] **Step 4: Capture baseline checks**

Run:

```bash
pnpm run typecheck
pnpm run test
```

Expected: both pass before dependency changes. If failing, stop and report exact failures before continuing.

## Task 2: Patch `discord-video-stream` Workspace Selfbot Reference

**Files:**
- Modify: `vendor/discord-video-stream/package.json`
- Modify: `pnpm-lock.yaml`

- [ ] **Step 1: Inspect current devDependency**

Open `vendor/discord-video-stream/package.json` and find:

```json
"discord.js-selfbot-v13": "^3.7.1"
```

Expected: exists under `devDependencies`.

- [ ] **Step 2: Replace devDependency with workspace reference**

Change that entry to:

```json
"discord.js-selfbot-v13": "workspace:*"
```

Keep peer dependency unchanged:

```json
"peerDependencies": {
  "discord.js-selfbot-v13": "^3.6.0"
}
```

- [ ] **Step 3: Reinstall**

Run:

```bash
pnpm install
```

Expected: lockfile uses local workspace for `discord.js-selfbot-v13` in `vendor/discord-video-stream` importer.

- [ ] **Step 4: Verify no registry selfbot fetch from discord-video-stream**

Run:

```bash
pnpm why discord.js-selfbot-v13
```

Expected: root and discord-video-stream both point to `link:vendor/discord.js-selfbot-v13` or workspace link.

- [ ] **Step 5: Run checks**

Run:

```bash
pnpm run typecheck
pnpm run test
```

Expected: both pass.

## Task 3: Upgrade or Patch `otplib` Chain in Vendored Selfbot

**Files:**
- Modify: `vendor/discord.js-selfbot-v13/package.json`
- Modify: `pnpm-lock.yaml`

- [ ] **Step 1: Locate selfbot otplib dependency**

Run:

```bash
node -e "const p=require('./vendor/discord.js-selfbot-v13/package.json'); console.log(p.dependencies?.otplib || p.devDependencies?.otplib)"
```

Expected: prints `^12.x` or `12.x`.

- [ ] **Step 2: Check latest otplib version**

Run:

```bash
npm view otplib version deprecated --json
```

Expected: latest version is not deprecated.

- [ ] **Step 3: Change selfbot dependency to otplib latest major**

In `vendor/discord.js-selfbot-v13/package.json`, replace existing `otplib` dependency value with latest non-deprecated major range. Example if latest is 13.x:

```json
"otplib": "^13.0.0"
```

Do not change package name or selfbot exports.

- [ ] **Step 4: Reinstall**

Run:

```bash
pnpm install
```

Expected: install completes. `@otplib/plugin-crypto`, `@otplib/plugin-thirty-two`, and `@otplib/preset-default` should disappear if otplib v13 no longer pulls them.

- [ ] **Step 5: Verify otplib deprecated plugins gone**

Run:

```bash
pnpm why @otplib/plugin-crypto @otplib/plugin-thirty-two @otplib/preset-default
```

Expected: no dependency path for those packages. If they remain under `otplib`, inspect latest otplib metadata and stop before vendoring otplib.

- [ ] **Step 6: Run checks**

Run:

```bash
pnpm run typecheck
pnpm run test
```

Expected: both pass. If selfbot code breaks due otplib API changes, revert only the otplib version change and report API mismatch.

## Task 4: Upgrade `drizzle-kit` to Remove `@esbuild-kit/*`

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

- [ ] **Step 1: Check current and latest drizzle-kit**

Run:

```bash
node -e "const p=require('./package.json'); console.log(p.devDependencies['drizzle-kit'])"
npm view drizzle-kit version deprecated --json
```

Expected: latest version is not deprecated.

- [ ] **Step 2: Update root devDependency if newer version exists**

If latest version is newer than `0.31.10`, change `package.json` devDependency:

```json
"drizzle-kit": "^<latest-version>"
```

Example:

```json
"drizzle-kit": "^0.32.0"
```

Use actual latest version from npm output.

- [ ] **Step 3: Reinstall**

Run:

```bash
pnpm install
```

Expected: install completes.

- [ ] **Step 4: Verify esbuild-kit packages gone**

Run:

```bash
pnpm why @esbuild-kit/core-utils @esbuild-kit/esm-loader
```

Expected: no dependency path. If latest `drizzle-kit` still pulls them, keep latest only if project checks pass; do not vendor `drizzle-kit` unless user confirms dev-only strictness.

- [ ] **Step 5: Run drizzle commands**

Run:

```bash
pnpm run db:generate -- --help
pnpm run db:migrate -- --help
```

Expected: commands print help or usage without crashing. Do not run actual migrations.

- [ ] **Step 6: Run checks**

Run:

```bash
pnpm run typecheck
pnpm run test
```

Expected: both pass.

## Task 5: Remove or Replace Direct `@discordjs/opus`

**Files:**
- Modify: `package.json`
- Modify: `pnpm-lock.yaml`
- Inspect: `src/recorder/decoder.ts`
- Inspect: `tests/decoder.test.ts`

- [ ] **Step 1: Find project usage of `@discordjs/opus`**

Run:

```bash
grep -R "@discordjs/opus\|OpusEncoder\|OpusDecoder" -n src tests package.json
```

Expected: usage locations show whether direct package is imported by project code or only required indirectly by `prism-media`.

- [ ] **Step 2: Check `@discordjs/voice` encryption/audio requirements**

Run:

```bash
pnpm why @discordjs/opus prism-media
```

Expected: shows `@discordjs/voice` and root dependency relationships.

- [ ] **Step 3: Test removal in package manifest**

Remove root dependency line from `package.json`:

```json
"@discordjs/opus": "^0.10.0",
```

Do not edit code yet.

- [ ] **Step 4: Reinstall**

Run:

```bash
pnpm install
```

Expected: install completes. If install or peer resolution fails, restore `@discordjs/opus` and continue to Step 8.

- [ ] **Step 5: Run decoder-specific tests**

Run:

```bash
pnpm run test -- tests/decoder.test.ts
```

Expected: tests pass or skip native opus gracefully. If tests fail because native opus is required by project behavior, restore `@discordjs/opus` and continue to Step 8.

- [ ] **Step 6: Run full checks**

Run:

```bash
pnpm run typecheck
pnpm run test
```

Expected: both pass.

- [ ] **Step 7: Verify deprecated node-pre-gyp chain gone**

Run:

```bash
pnpm why @discordjs/node-pre-gyp npmlog are-we-there-yet gauge rimraf glob inflight
```

Expected: no dependency path through `@discordjs/opus`. If gone, task complete.

- [ ] **Step 8: If `@discordjs/opus` is required, try maintained alternatives**

Run:

```bash
npm view opusscript version deprecated --json
npm view @evan/opus version deprecated --json
```

Expected: identify non-deprecated candidate. Do not switch unless package supports same runtime path used by `prism-media` or direct project imports.

- [ ] **Step 9: If no compatible maintained alternative exists, vendor decision checkpoint**

Stop and report:

```text
@discordjs/opus still required. No compatible maintained replacement verified. Next action requires cloning/vendoring smallest package owner or accepting deprecated native install chain.
```

Do not clone without user confirmation of target repository.

## Task 6: Evaluate `prebuild-install` Owners

**Files:**
- Modify: `package.json` only if safe upgrade exists
- Modify: `vendor/discord-video-stream/package.json` only if safe upgrade exists
- Modify: `pnpm-lock.yaml`

- [ ] **Step 1: Check owner versions**

Run:

```bash
npm view better-sqlite3 version deprecated --json
npm view @lng2004/node-datachannel version deprecated --json
node -e "const root=require('./package.json'); const dvs=require('./vendor/discord-video-stream/package.json'); console.log({betterSqlite3: root.dependencies['better-sqlite3'], nodeDatachannel: dvs.dependencies['@lng2004/node-datachannel']})"
```

Expected: latest versions known.

- [ ] **Step 2: Upgrade `better-sqlite3` if newer version exists**

If latest is newer than current, change `package.json`:

```json
"better-sqlite3": "^<latest-version>"
```

Use actual latest version.

- [ ] **Step 3: Upgrade `@lng2004/node-datachannel` if newer version exists**

If latest is newer than current and package name still matches discord-video-stream requirements, change `vendor/discord-video-stream/package.json`:

```json
"@lng2004/node-datachannel": "<latest-version>"
```

Use exact latest version only if upstream uses exact published builds.

- [ ] **Step 4: Reinstall**

Run:

```bash
pnpm install
```

Expected: native dependencies install or reuse existing builds successfully.

- [ ] **Step 5: Verify `prebuild-install` status**

Run:

```bash
pnpm why prebuild-install
```

Expected: either no dependency path, or only native owners remain.

- [ ] **Step 6: Run checks**

Run:

```bash
pnpm run typecheck
pnpm run test
```

Expected: both pass.

- [ ] **Step 7: If `prebuild-install` remains**

Stop and report owner paths. Do not vendor native packages unless no maintained version removes it and user explicitly wants native submodule maintenance.

## Task 7: Final Deprecation Audit

**Files:**
- Modify: `pnpm-lock.yaml` through install only

- [ ] **Step 1: Run clean install audit**

Run:

```bash
pnpm install
```

Expected: no deprecated package warnings where maintained replacements were applied.

- [ ] **Step 2: Run owner query for all known deprecated names**

Run:

```bash
pnpm why discord.js-selfbot-v13 @esbuild-kit/core-utils @esbuild-kit/esm-loader @otplib/plugin-crypto @otplib/plugin-thirty-two @otplib/preset-default are-we-there-yet fs-then-native gauge inflight lodash.pick npmlog prebuild-install stream-connect test-value @discordjs/node-pre-gyp
```

Expected: no paths for packages removed by prior tasks. Remaining paths must be only approved unavoidable native/package-owner cases.

- [ ] **Step 3: Check npm deprecation metadata for remaining suspect packages**

Run:

```bash
node - <<'NODE'
const {execFileSync}=require('child_process');
const pkgs=['discord.js-selfbot-v13','@esbuild-kit/core-utils','@esbuild-kit/esm-loader','@otplib/plugin-crypto','@otplib/plugin-thirty-two','@otplib/preset-default','are-we-there-yet','fs-then-native','gauge','inflight','lodash.pick','npmlog','prebuild-install','stream-connect','test-value','@discordjs/node-pre-gyp'];
for (const p of pkgs) {
  try {
    const out=execFileSync('npm',['view',p,'deprecated','--json'],{encoding:'utf8'}).trim();
    if (out && out !== 'null') console.log(`${p}: ${JSON.parse(out)}`);
  } catch {
    console.log(`${p}: npm view failed`);
  }
}
NODE
```

Expected: command prints metadata only. Compare printed package names with `pnpm why` output.

- [ ] **Step 4: Run final checks**

Run:

```bash
pnpm run typecheck
pnpm run test
pnpm run lint
```

Expected: all pass.

## Task 8: Document Remaining Unavoidable Deprecated Packages

**Files:**
- Modify: `docs/superpowers/specs/2026-05-19-deprecated-dependency-removal-design.md`

- [ ] **Step 1: If no deprecated packages remain, append success note**

Append this section:

```markdown
## Final Audit Result

All known deprecated packages from the initial audit were removed from the active pnpm dependency graph.
```

- [ ] **Step 2: If deprecated packages remain, append owner note**

Append this section with actual owner paths from `pnpm why`:

```markdown
## Final Audit Result

Remaining deprecated packages after maintained upgrade attempts:

- `<package>` remains via `<owner path>`. Reason: `<no maintained replacement found | native install chain still used by latest upstream | user-approved vendored package>`.

These are candidates for future vendoring/submodule patching if strict lockfile cleanup remains required.
```

- [ ] **Step 3: Run final git diff review**

Run:

```bash
git diff -- package.json pnpm-workspace.yaml pnpm-lock.yaml vendor/discord-video-stream/package.json vendor/discord.js-selfbot-v13/package.json docs/superpowers/specs/2026-05-19-deprecated-dependency-removal-design.md
```

Expected: diff contains only dependency migration changes and audit note.

## Task 9: Commit Checkpoint Only If User Requests Commit

**Files:**
- Stage only changed package/spec/submodule files relevant to dependency cleanup.

- [ ] **Step 1: Show status**

Run:

```bash
git status --short
```

Expected: changed files match work done.

- [ ] **Step 2: Ask before committing**

Ask user whether to commit. Do not commit unless explicitly requested.

- [ ] **Step 3: If user asks to commit, create commit**

Use exact changed file list, not `git add -A`. Commit message:

```bash
git commit -m "$(cat <<'EOF'
chore: remove deprecated dependency graph entries

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
EOF
)"
```

Expected: commit succeeds without bypassing hooks.

## Self-Review

- Spec coverage: plan covers replace-first, workspace patches, submodule/vendor checkpoint, verification, and final audit documentation.
- Placeholder scan: no TBD/TODO placeholders; steps include exact commands and expected outcomes.
- Type consistency: paths and package names match current workspace files and dependency owners.