dc-recorder/docs/superpowers/plans/2026-05-15-selfbot-workspace-submodule.md

Selfbot Workspace Submodule 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: Replace the npm discord.js-selfbot-v13 dependency with a custom git submodule consumed through pnpm workspace resolution.

Architecture: The vendored selfbot library lives at vendor/discord.js-selfbot-v13 as a git submodule. The root package depends on it with workspace:*, and pnpm-workspace.yaml includes both the root package and the vendored package while preserving the existing onlyBuiltDependencies settings.

Tech Stack: Git submodules, pnpm workspaces, TypeScript, existing Node.js package scripts.

---

File Structure

• Create: .gitmodules if missing; otherwise modify it to include vendor/discord.js-selfbot-v13.
• Create: vendor/discord.js-selfbot-v13 via git submodule add; do not create files in this directory manually.
• Modify: pnpm-workspace.yaml to add packages while preserving onlyBuiltDependencies.
• Modify: package.json dependency discord.js-selfbot-v13 from ^3.7.1 to workspace:*.
• Modify: pnpm-lock.yaml by running pnpm, not by hand.

Task 1: Add the selfbot repository as a submodule

Files:

• Create/Modify: .gitmodules

• Create: vendor/discord.js-selfbot-v13

• Step 1: Confirm there is no existing submodule path

Run:

git submodule status --recursive || true
test ! -e vendor/discord.js-selfbot-v13

Expected: either no existing submodule output, or output that does not include vendor/discord.js-selfbot-v13; the test command exits successfully.

• Step 2: Add the upstream repository as a submodule

Run:

git submodule add https://github.com/aiko-chan-ai/discord.js-selfbot-v13.git vendor/discord.js-selfbot-v13

Expected: git clones the repository into vendor/discord.js-selfbot-v13 and creates or updates .gitmodules.

• Step 3: Change the submodule remote to the internal SSH repository

Run:

git -C vendor/discord.js-selfbot-v13 remote set-url origin ssh://git@43.134.105.109:22222/exceed/discord.js-selfbot.git
git config -f .gitmodules submodule.vendor/discord.js-selfbot-v13.url ssh://git@43.134.105.109:22222/exceed/discord.js-selfbot.git
git submodule sync vendor/discord.js-selfbot-v13

Expected: both the submodule checkout and .gitmodules use ssh://git@43.134.105.109:22222/exceed/discord.js-selfbot.git.

• Step 4: Verify submodule metadata

Run:

git -C vendor/discord.js-selfbot-v13 remote get-url origin
git config -f .gitmodules --get submodule.vendor/discord.js-selfbot-v13.path
git config -f .gitmodules --get submodule.vendor/discord.js-selfbot-v13.url

Expected output:

ssh://git@43.134.105.109:22222/exceed/discord.js-selfbot.git
vendor/discord.js-selfbot-v13
ssh://git@43.134.105.109:22222/exceed/discord.js-selfbot.git

Task 2: Configure pnpm workspace resolution

Files:

• Modify: pnpm-workspace.yaml

• Modify: package.json

• Step 1: Update pnpm workspace file

Edit pnpm-workspace.yaml to exactly:

packages:
  - .
  - vendor/discord.js-selfbot-v13

onlyBuiltDependencies:
  - '@discordjs/opus'
  - better-sqlite3
  - esbuild

Expected: the existing onlyBuiltDependencies entries remain unchanged, and workspace packages now include root plus the vendored selfbot package.

• Step 2: Update root dependency

Edit package.json so the dependencies block contains:

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

Expected: only the discord.js-selfbot-v13 version source changes; the rest of package.json remains unchanged.

• Step 3: Verify the submodule package name

Run:

node -e "const p=require('./vendor/discord.js-selfbot-v13/package.json'); if (p.name !== 'discord.js-selfbot-v13') { throw new Error('unexpected package name: '+p.name) } console.log(p.name)"

Expected output:

discord.js-selfbot-v13

Task 3: Refresh dependency lockfile and install links

Files:

• Modify: pnpm-lock.yaml

• Modify: node_modules locally, not committed

• Step 1: Refresh pnpm install state

Run:

pnpm install

Expected: pnpm completes successfully and updates pnpm-lock.yaml so discord.js-selfbot-v13 resolves from link:vendor/discord.js-selfbot-v13 or equivalent workspace link notation.

• Step 2: Verify pnpm resolves the workspace package

Run:

pnpm list discord.js-selfbot-v13 --depth 0

Expected: output shows discord.js-selfbot-v13 as a linked workspace dependency rather than the npm registry version.

• Step 3: Inspect the lockfile entry

Run:

grep -n "discord.js-selfbot-v13" pnpm-lock.yaml | head -20

Expected: the root importer entry for discord.js-selfbot-v13 references specifier: workspace:* and a workspace/link version.

Task 4: Validate root project compatibility

Files:

• Read-only validation for TypeScript project files.

• Step 1: Run TypeScript validation

Run:

pnpm run typecheck

Expected: command exits successfully.

• Step 2: If typecheck fails because the submodule package is unbuilt, build the submodule

Run only if Step 1 fails with missing compiled files or missing package entrypoint errors from vendor/discord.js-selfbot-v13:

pnpm --filter discord.js-selfbot-v13 install
npnpm --filter discord.js-selfbot-v13 run build
pnpm run typecheck

Expected: submodule package builds successfully and root typecheck passes.

If the package has no build script, inspect vendor/discord.js-selfbot-v13/package.json scripts and use the package's documented compile script, then rerun pnpm run typecheck.

• Step 3: Run lint if typecheck passes

Run:

pnpm run lint

Expected: command exits successfully or reports only pre-existing issues unrelated to .gitmodules, package.json, pnpm-workspace.yaml, or pnpm-lock.yaml.

Task 5: Review git diff and prepare handoff

Files:

• Review: .gitmodules

• Review: package.json

• Review: pnpm-workspace.yaml

• Review: pnpm-lock.yaml

• Review: vendor/discord.js-selfbot-v13 gitlink

• Step 1: Review changed files

Run:

git status --short
git diff -- .gitmodules package.json pnpm-workspace.yaml pnpm-lock.yaml
git diff --submodule

Expected: changes are limited to the design spec, plan, submodule metadata/gitlink, pnpm workspace config, root dependency, and lockfile. Existing unrelated README.md modifications remain untouched.

• Step 2: Summarize validation evidence

Record these command outcomes in the final response:

pnpm install: PASS or FAIL with error summary
pnpm run typecheck: PASS or FAIL with error summary
pnpm run lint: PASS, FAIL with error summary, or NOT RUN with reason

• Step 3: Do not commit unless explicitly asked

No commit command should run unless the user explicitly asks for a commit. If the user asks, use the repository commit workflow and stage only relevant files.

Self-Review

• Spec coverage: the plan covers submodule creation, remote replacement, workspace config, dependency rewrite, lockfile refresh, and validation.
• Placeholder scan: no TBD/TODO placeholders remain.
• Type consistency: package path, dependency name, and remote URL are consistent across tasks.