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:

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:

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:

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:

pnpm install

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

• Step 4: Capture baseline checks

Run:

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:

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

Expected: exists under devDependencies.

• Step 2: Replace devDependency with workspace reference

Change that entry to:

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

Keep peer dependency unchanged:

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

• Step 3: Reinstall

Run:

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:

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:

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:

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:

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:

"otplib": "^13.0.0"

Do not change package name or selfbot exports.

• Step 4: Reinstall

Run:

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:

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:

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:

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:

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

Example:

"drizzle-kit": "^0.32.0"

Use actual latest version from npm output.

• Step 3: Reinstall

Run:

pnpm install

Expected: install completes.

• Step 4: Verify esbuild-kit packages gone

Run:

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:

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:

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:

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:

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:

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

Do not edit code yet.

• Step 4: Reinstall

Run:

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:

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:

pnpm run typecheck
pnpm run test

Expected: both pass.

• Step 7: Verify deprecated node-pre-gyp chain gone

Run:

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:

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:

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

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:

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

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

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

• Step 4: Reinstall

Run:

pnpm install

Expected: native dependencies install or reuse existing builds successfully.

• Step 5: Verify prebuild-install status

Run:

pnpm why prebuild-install

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

• Step 6: Run checks

Run:

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:

pnpm install

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

• Step 2: Run owner query for all known deprecated names

Run:

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:

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:

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:

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

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

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:

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:

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.