If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/TrashUwU/PokeAssistant shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Slowing — last commit 7mo ago

• Last commit 7mo ago
• 3 active contributors
• CI configured
• Tests present
• ⚠ Slowing — last commit 7mo ago
• ⚠ Small team — 3 contributors active in recent commits
• ⚠ Single-maintainer risk — top contributor 98% of recent commits
• ⚠ No license — legally unclear to depend on

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live TrashUwU/PokeAssistant repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/TrashUwU/PokeAssistant.

What it runs against: a local clone of TrashUwU/PokeAssistant — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in TrashUwU/PokeAssistant | Confirms the artifact applies here, not a fork | | 2 | Default branch main exists | Catches branch renames | | 3 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 4 | Last commit ≤ 232 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of TrashUwU/PokeAssistant. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/TrashUwU/PokeAssistant.git
#   cd PokeAssistant
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of TrashUwU/PokeAssistant and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "TrashUwU/PokeAssistant(\\.git)?\\b" \\
  && ok "origin remote is TrashUwU/PokeAssistant" \\
  || miss "origin remote is not TrashUwU/PokeAssistant (artifact may be from a fork)"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "src/index.js" \\
  && ok "src/index.js" \\
  || miss "missing critical file: src/index.js"
test -f "src/package.json" \\
  && ok "src/package.json" \\
  || miss "missing critical file: src/package.json"
test -f "src/main.sh" \\
  && ok "src/main.sh" \\
  || miss "missing critical file: src/main.sh"
test -f "README.md" \\
  && ok "README.md" \\
  || miss "missing critical file: README.md"
test -f "src/TROUBLESHOOT.md" \\
  && ok "src/TROUBLESHOOT.md" \\
  || miss "missing critical file: src/TROUBLESHOOT.md"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 232 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~202d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/TrashUwU/PokeAssistant"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

PokeAssistant is a Discord.js bot (v12.5.3) that monitors Pokétwo spawns in Discord servers and uses image recognition (via Jimp and a lightweight AI model) to identify Pokémon with ~85% accuracy, then automatically pings users/roles based on rarity rules—legendary/mythical spawns trigger role pings + message pins, shiny hunt matches trigger DMs, quest spawns trigger specific notifications. It solves the problem of manually watching chat for rare Pokémon spawns in competitive gaming communities. Monolithic structure: entry point at src/index.js with shell wrapper src/main.sh, uses @replit/database and quick.db for state persistence (configuration stored in Replit DB or local file), all bot logic in single codebase rather than modular plugins. Image processing pipeline (Jimp) chains with axios calls to unspecified prediction endpoint.

Pokétwo players and server administrators who want automated legendary/shiny hunt notifications without manually scanning chat; the bot runs on user accounts via Replit, making it accessible to non-developers seeking competitive advantage in Pokétwo communities.

Actively maintained but early-stage: Version 4.0.0 with 73 premium users indicates live usage, but minimal test coverage (only test/index.rb and test/main.js with no visible assertions), no CI/CD beyond a basic node.js workflow, and single-maintainer (TrashUwU) creates sustainability risk. Suitable for hobby/gaming use, not production-grade infrastructure.

High dependency surface area (discord.js, jimp, axios, axios-retry, request, shelljs) with no lock file visible in file list creates supply-chain risk; no production-grade error handling apparent, 85% accuracy rate on Pokémon identification means frequent false positives, and aggressive auto-update mechanism (mentioned in features) could break user setups silently. No visible security audit for a bot handling user authentication tokens.

No specific recent commits visible in file list, but README indicates v4.0.0 is current with ongoing premium feature tier expansion (faster prediction, decreased rate limits, automated Who's-That-Pokémon). Support server and GitHub issues are primary community channels.

git clone https://github.com/TrashUwU/PokeAssistant.git
cd PokeAssistant/src
npm install
node index.js

Requires Discord bot token and Replit DB credentials (stored in environment variables based on @replit/database dependency).

Daily commands:

cd src && npm install && node index.js

Bot expects DISCORD_TOKEN and Replit DB credentials in environment; runs continuously as long-lived process listening for message events. Alternatively via src/main.sh shell wrapper for Replit deployment.

• src/index.js — Main entry point for the Discord bot; contains core event listeners and message handling logic that must be understood to grasp the bot's flow
• src/package.json — Declares all dependencies (discord.js, jimp, quick.db) that are essential to the bot's functionality; version compatibility is critical
• src/main.sh — Shell script that starts the bot; needed to understand deployment and runtime environment setup
• README.md — Documents bot features (Legendary pings, Shiny Hunt detection, Quest Ping) and setup instructions that guide contributor onboarding
• src/TROUBLESHOOT.md — Troubleshooting guide explaining common issues and their resolutions; critical for debugging contributor problems
• .github/workflows/node.js.yml — CI/CD pipeline configuration that validates code before merge; contributors must understand test expectations

• Discord.js Client (discord.js) — Maintains WebSocket connection to Discord; routes incoming messages to event listeners
  • Failure mode: Bot disconnects and stops receiving spawns; requires reconnection via main.sh restart
• Spawn Detection & Image Analysis (jimp, discord.js message events) — Intercepts Pokétwo bot messages, parses spawn images, and identifies species using jimp
  • Failure mode: Misidentified Pokémon or missed spawns if image parsing fails or encounters unsupported format
• User Data Persistence (quick.db, @replit/database) — Stores and retrieves shiny hunt lists, quest progress, and notification preferences via quick.db
  • Failure mode: User preferences lost on bot restart if quick.db corruption occurs; no fallback to remote backup
• Feature Dispat — undefined

Add a New Pokémon Detection Feature (e.g., Regional Variant Ping)

1. Open src/index.js and locate the spawn detection message event listener that parses the Pokétwo spawn image (src/index.js)
2. Add a new conditional block after the legendary/mythical check to identify regional variants using jimp image analysis (src/index.js)
3. Query the quick.db database to fetch users subscribed to that regional variant (src/index.js)
4. Send a ping embed to the subscribed user with the variant Pokémon details (src/index.js)
5. Add test case in test/main.js to validate the new feature triggers correctly (test/main.js)

Add a New User Configuration Command (e.g., Set Notification Preference)

1. In src/index.js, add a new Discord command listener (e.g., for '!setnotify') in the message handler (src/index.js)
2. Parse the command arguments and validate user input (src/index.js)
3. Store the preference in quick.db with the user ID as key (src/index.js)
4. Return a confirmation message to the user (src/index.js)
5. Update README.md with documentation of the new command and its usage (README.md)

Integrate a New External Pokémon Data API

1. In src/index.js, add a new axios request with axios-retry configuration pointing to the new API endpoint (src/index.js)
2. Extract and normalize the response data to match the bot's internal Pokémon data structure (src/index.js)
3. Cache the API response in quick.db to reduce repeated calls (src/index.js)
4. Update src/TROUBLESHOOT.md with troubleshooting steps if the new API is unavailable (src/TROUBLESHOOT.md)
5. Add integration tests in test/main.js to validate the new API integration (test/main.js)

• discord.js v12.5.3 — Provides event-driven Discord API bindings; essential for real-time spawn message detection and user pings
• jimp 0.16.1 — Pure JavaScript image processing library; used to identify Pokémon species from Pokétwo spawn screenshots without external service calls
• quick.db v7.1.3 — Lightweight embedded JSON database; fast local storage for user preferences, shiny hunt lists, and cached Pokémon metadata
• axios v0.21.1 + axios-retry — HTTP client with built-in retry logic; resilient fetching of Pokémon data APIs and handling transient network failures
• @replit/database v2.0.1 — Replit-native database for deployment persistence; ensures data survives bot restarts on the Replit platform

• Single monolithic src/index.js file

  • Why: Simpler deployment on Replit; avoids module resolution complexity
  • Consequence: Reduced code modularity; harder to test and maintain as feature complexity grows; file becomes increasingly large

• Synchronous jimp image parsing in event handlers

  • Why: Simpler logic flow; image processing is relatively fast for screenshots
  • Consequence: Blocking event loop during image analysis; potential slowdown if processing many simultaneous spawns

• Local quick.db vs. centralized remote database

  • Why: Faster access and no external dependency; suitable for single-instance bot
  • Consequence: Data is local to the bot instance; cannot share state across multiple bot instances; data loss if instance crashes before backup

• Discord.js v12 (legacy, unmaintained)

  • Why: Stable and widely documented; was standard when project forked from Chamburr's version
  • Consequence: No Discord API v10+ support; missing recent Discord features; potential incompatibility with future Discord changes

• Does not provide a web dashboard or admin panel; all configuration is command-driven
• Does not support multi-instance horizontal scaling; data is stored locally per bot instance
• Does not handle authentication or permission systems beyond Discord's native roles
• Does not log detailed analytics or metrics; focus is on real-time event triggering, not business intelligence

Replit DB credentials must be injected via environment (no .env.example provided); discord.js v12.5.3 is EOL (v14+ breaks API—gateway intents required in newer versions), quick.db has no visible schema validation (corruption risk on restart), image inference endpoint URL not in package.json (hardcoded in index.js or fetched dynamically), axios-retry auto-retries may mask rate-limit issues, and shelljs execution in src/main.sh could be unsafe if user input flows through.

• Discord Gateway Intents — discord.js v12 uses implicit intents, but v14+ requires explicit declaration; missing intents cause silent message event drops, breaking the core spawn-detection loop
• Image Recognition / Sprite Classification — The 85% accuracy bottleneck; Jimp extracts sprites, but actual classification happens via external ML endpoint (undocumented); understanding model confidence scores helps tune false-positive thresholds
• Rate Limiting & Token Bucket — Discord enforces strict message-send rate limits; axios-retry with exponential backoff mitigates, but naive re-pinging multiple users on legendary spawn risks ban (premium tier promises 'decreased rate limit' via queue management)
• Event-Driven Architecture — Bot is message listener (on('message') in discord.js); prediction and notification dispatch must be non-blocking to avoid missing spawns during processing latency
• Persistence Layer Fallback (Replit DB vs quick.db) — Dual storage (cloud @replit/database + local quick.db) creates consistency risk if sync fails; understanding which tier owns truth (read-after-write consistency) is critical for bug reproduction
• Auto-Update via Shell Wrapper — src/main.sh pulls latest code and restarts process automatically; users may not realize breaking changes are applied without consent, causing silent feature regressions

• discord-js/discord.js — Core dependency (v12.5.3); users need to understand gateway events, intents, and client lifecycle for modifications
• oliver-zhang/pokeapi — Pokémon data source alternative; if inference endpoint fails, pokeapi offers REST lookups for Pokédex metadata
• quick-db/quick.db — State persistence library used; docs needed to understand schema design, corruption recovery, and cluster safety

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive unit tests for src/index.js core Discord event handlers

The repo lacks test coverage for the main bot logic. Currently test/main.js and test/index.rb exist but appear unused/minimal. The core Pokemon identification, legendary ping, shiny hunt ping, and quest ping features in src/index.js need automated tests to prevent regressions as contributors add features.

• [ ] Create test suite in test/ that mocks discord.js client events (message, spawn detection)
• [ ] Add tests for Pokemon identification logic from spawn image parsing
• [ ] Add tests for role ping logic when legendaries spawn
• [ ] Add tests for shiny hunt notification filtering
• [ ] Integrate tests into .github/workflows/node.js.yml CI pipeline to run on PRs

Add GitHub Actions workflow for dependency security scanning and updates

The package.json has outdated dependencies (discord.js 12.5.3 is EOL, axios 0.21.1 has known vulnerabilities). The existing node.js.yml workflow only runs tests. Adding Dependabot or npm audit scanning would catch security issues early and encourage automated dependency updates.

• [ ] Create .github/workflows/security.yml with npm audit step
• [ ] Add .github/dependabot.yml configuration for automated dependency PR creation
• [ ] Document security update process in src/TROUBLESHOOT.md
• [ ] Add security badge to README.md

Extract Pokemon identification logic from src/index.js into a dedicated src/utils/pokemon-identifier.js module

src/index.js likely contains mixed concerns (Discord bot setup, image parsing, Pokemon identification). Extracting image→Pokemon identification into a reusable module with jimp image processing logic would improve testability and allow the community to improve detection accuracy independently.

• [ ] Create src/utils/ directory structure
• [ ] Move jimp-based Pokemon detection logic to src/utils/pokemon-identifier.js with exported functions
• [ ] Create src/utils/ping-handlers.js for legendary/shiny/quest ping business logic
• [ ] Update src/index.js to import and use these modules
• [ ] Add unit tests in test/ for pokemon-identifier.js with sample spawn images

• Add Jest test suite for src/index.js message event handlers—currently test/ files are stale (Ruby/JS mismatch); covering prediction dispatch logic would catch regressions in role-ping and DM notification flows: medium: No test infrastructure; mocking discord.js events and quick.db is non-trivial but high value
• Document Pokémon identification accuracy rate per generation (Gen 1-8) in README—the '85% overall' claim lacks granularity; add breakdown showing which Pokémon have high false-positive rates: easy: Users deploy blindly without knowing which spawns will mis-identify; add metrics table to README
• Create .env.example file listing required environment variables (DISCORD_TOKEN, REPLIT_DB_URL, inference endpoint URL if applicable) with descriptions: easy: Onboarding friction; new contributors won't know what config to set up, causing cryptic 'undefined' errors at runtime
• Upgrade discord.js from v12.5.3 to v14.x and add Gateway Intents configuration—v12 will hit Discord API breaking changes soon: hard: Technical debt; prevents long-term maintenance and breaks bot on next Discord API rotation

• Critical · Outdated axios dependency with known vulnerabilities — src/package.json - dependencies.axios. axios version 0.21.1 contains multiple known security vulnerabilities including CVE-2021-41773 and other issues. This version is from 2021 and has not received security updates. Fix: Update axios to the latest stable version (1.6.0+). Run: npm update axios
• Critical · Deprecated 'request' library with unpatched vulnerabilities — src/package.json - dependencies.request. The 'request' package (2.88.2) is deprecated and no longer maintained. It contains known security vulnerabilities and will not receive security patches. Fix: Replace with modern alternatives like axios, node-fetch, or undici. Remove 'request' and 'request-promise' dependencies.
• High · Outdated discord.js version — src/package.json - dependencies.discord.js. discord.js version 12.5.3 is significantly outdated (released 2020). Current versions are 14.x+. Older versions may have unpatched security issues and lack security improvements. Fix: Update to discord.js v14 or latest stable version. Run: npm update discord.js
• High · Outdated jimp image processing library — src/package.json - dependencies.jimp. jimp version 0.16.1 is outdated and may contain unpatched vulnerabilities in image processing. Image manipulation libraries are common attack vectors. Fix: Update jimp to the latest version (1.6.0+). Run: npm update jimp
• High · Insecure quick.db version — src/package.json - dependencies.quick.db. quick.db version 7.1.3 is outdated. Modern versions (9.x+) provide better security and data integrity. Older versions may have vulnerabilities in data storage. Fix: Update quick.db to version 9.x or later. Consider using more robust database solutions for sensitive data. Run: npm update quick.db
• High · Potential credential exposure via environment variables — Repository root and src/. No .env.example or environment variable documentation visible. Discord bot tokens and database credentials are likely stored in untracked .env files, risking accidental commits. Fix: Create a .env.example file documenting all required environment variables. Ensure .env is in .gitignore. Use process.env for all sensitive configuration.
• Medium · Outdated axios-retry dependency — src/package.json - dependencies.axios-retry. axios-retry version 3.2.0 is outdated. Current versions are 3.8.0+. May contain unpatched issues. Fix: Update to the latest version. Run: npm update axios-retry
• Medium · shelljs execution risk — src/package.json - dependencies.shelljs. shelljs 0.8.4 is present. If user input is passed to shell commands via this library, it creates command injection vulnerabilities. Fix: Audit all shelljs usage in src/index.js. Avoid passing user input to shell commands. Consider using native Node.js alternatives instead of shell execution.
• Medium · Missing Security Headers and Input Validation — src/index.js (content not provided). No evidence of input validation or sanitization for Discord message content. Bot processes user-supplied data which could lead to injection attacks. Fix: Implement input validation for all user-supplied data. Sanitize before processing. Use Discord.js built-in escaping methods.
• Low · No dependency lock file visible — src/package.json directory. Unable to verify if package-lock.json or yarn.lock exists and is tracked. Reproducible builds require locked dependency versions. Fix: Ensure package-lock.json is committed to version control. Use 'npm ci' in production instead of 'npm install'.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.