Compare commits
4 Commits
5de05a0d01
...
6d579207f3
| Author | SHA1 | Date | |
|---|---|---|---|
| 6d579207f3 | |||
| 431622d05c | |||
| b1f66107c0 | |||
| b764bc98c7 |
@@ -1,53 +0,0 @@
|
||||
{
|
||||
"permissions": {
|
||||
"allow": [
|
||||
"Bash(node -e ':*)",
|
||||
"Bash(node --check services/tickets.js)",
|
||||
"Bash(node --check config.js)",
|
||||
"Bash(node --check handlers/commands.js)",
|
||||
"Bash(node --check handlers/buttons.js)",
|
||||
"Bash(node --check gmail-poll.js)",
|
||||
"Bash(node --check handlers/pendingCloses.js)",
|
||||
"Bash(node --check commands/register.js)",
|
||||
"Bash(grep -E \"\\\\.js$|\\\\.json$|^d\")",
|
||||
"Bash(grep -r \"require\\\\|import\" /opt/broccolini-bot/*.js /opt/broccolini-bot/routes/*.js /opt/broccolini-bot/api/*.js)",
|
||||
"Bash(grep -r \"require\\\\|import\" /opt/broccolini-bot/*.js)",
|
||||
"Bash(grep *)",
|
||||
"Bash(npm install *)",
|
||||
"Bash(node -e \"require\\('./routes/bosscord'\\)\")",
|
||||
"Bash(node -e \"require\\('./routes/internalApi'\\)\")",
|
||||
"Bash(node -e \"require\\('express-rate-limit'\\)\")",
|
||||
"Bash(node --check services/surgeChecker.js)",
|
||||
"Bash(node --check services/patternChecker.js)",
|
||||
"Bash(node --check services/chatAlertChecker.js)",
|
||||
"Bash(node --check services/debugLog.js)",
|
||||
"Bash(node --check services/staffChannel.js)",
|
||||
"Bash(node --check handlers/messages.js)",
|
||||
"Bash(node *)",
|
||||
"Bash(npm info *)",
|
||||
"Bash(npm ls *)",
|
||||
"Bash(curl -sk http://127.0.0.1:12752/css/main.css)",
|
||||
"Bash(curl -sk http://127.0.0.1:12752/js/app.js)",
|
||||
"Bash(curl -sk -o /dev/null -w \"HTTP %{http_code}\\\\n\" http://127.0.0.1:12752/css/main.css)",
|
||||
"Bash(curl -sk -o /dev/null -w \"HTTP %{http_code}\\\\n\" http://127.0.0.1:12752/js/app.js)",
|
||||
"Bash(docker compose *)",
|
||||
"Bash(curl -sI http://100.114.205.53:12752/healthz)",
|
||||
"Bash(curl -s http://100.114.205.53:12752/healthz)",
|
||||
"mcp__plugin_context7_context7__query-docs",
|
||||
"Bash(curl -sI http://100.114.205.53:12752/api/config)",
|
||||
"Bash(curl -sI http://100.114.205.53:12752/)",
|
||||
"Bash(curl -sI http://100.114.205.53:12752/login)",
|
||||
"Bash(curl -sI http://100.114.205.53:12752/some/nonexistent/path)",
|
||||
"Bash(curl -sI http://100.114.205.53:12752/js/app.js)",
|
||||
"Bash(curl -sI http://100.114.205.53:12752/js/util.js)",
|
||||
"Bash(curl -sI http://100.114.205.53:12752/js/notifications.js)",
|
||||
"Bash(docker exec *)",
|
||||
"Bash(curl -sI http://100.114.205.53:12752/api/notifications/alerts)",
|
||||
"Bash(git log *)",
|
||||
"Bash(curl *)",
|
||||
"Bash(docker inspect *)",
|
||||
"Bash(git -C /opt/broccolini-bot tag)",
|
||||
"Bash(git -C /opt/broccolini-bot branch)"
|
||||
]
|
||||
}
|
||||
}
|
||||
1
.gitignore
vendored
1
.gitignore
vendored
@@ -54,3 +54,4 @@ cursor.yml
|
||||
|
||||
*.bak
|
||||
*.bak-*
|
||||
CLAUDE.md
|
||||
|
||||
129
CLAUDE.md
129
CLAUDE.md
@@ -1,129 +0,0 @@
|
||||
# CLAUDE.md
|
||||
|
||||
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||||
|
||||
## Default mode: reviewer-first
|
||||
|
||||
Default output is **scoped improvement prompts**, not code edits. Output format:
|
||||
|
||||
```
|
||||
## [Short title]
|
||||
**Files:** [files to read/modify]
|
||||
**Problem:** [1-2 sentences]
|
||||
**Fix:** [specific instructions — what to change, not how to think about it]
|
||||
**Verify:** [how to confirm]
|
||||
```
|
||||
|
||||
Keep each prompt to a 5–20 minute task; decompose larger issues.
|
||||
|
||||
When the user asks for direct fixes, make them — but still avoid unsolicited refactors, rename sweeps, or cleanup beyond the stated scope.
|
||||
|
||||
## Project
|
||||
- **broccolini-bot** — Discord ticketing + support bot for Indifferent Broccoli (game hosting).
|
||||
- **Repo:** `/opt/broccolini-bot/` · **Gitea:** `ssh://git@100.114.205.53:2222/indifferentketchup/broccolini-bot.git`
|
||||
- **DB:** Self-hosted MongoDB on same host as bot, database `broccoli_db`. Dedicated user per DB.
|
||||
- **Host port 8892 → container port 5000** (`CONFIG.PORT`, env `DISCORD_ONLY_PORT`).
|
||||
- **Deploy:** `cd /opt/broccolini-bot && git pull && docker compose up --build -d` · tail: `docker logs broccolini-bot --tail 50 -f`
|
||||
|
||||
## Commands
|
||||
- `npm start` — run the bot (entry: `broccolini-discord.js`).
|
||||
- `npm run start:test` — run with `ENV_FILE=.env.test`.
|
||||
- `npm run start:1p` / `start:test:1p` — inject secrets via 1Password CLI (`op run`).
|
||||
- `npm run test-mongodb` / `test-mongodb:test` — connectivity probe; no test suite exists.
|
||||
- No lint step configured. No unit/integration test framework.
|
||||
- **Verification:** prefer `node --check <file>` for syntax, and inline `node -e "..."` for behavior. For tightly-coupled modules, stub deps via `Module._resolveFilename` override (see `services/channelQueue.js` tests in session history).
|
||||
|
||||
Many files under `scripts/` are one-shot maintenance utilities (backups, user lookups, transcript mapping). They are not wired into CI or into the bot's runtime.
|
||||
|
||||
## Stack
|
||||
Node.js **CommonJS** · Discord.js 14 · Express 5 · Mongoose 6 · googleapis · express-rate-limit · p-queue · dotenv/dotenv-expand.
|
||||
|
||||
## Hard Rules
|
||||
|
||||
1. **CommonJS only.** `require` / `module.exports`. Never `import`.
|
||||
2. **Read before write.** Never propose or make changes to a file without first reading its current contents.
|
||||
3. **Route channel operations through `services/channelQueue.js`**: `enqueueSend`, `enqueueRename`, `enqueueMove`, `enqueueDelete` (awaits both rename+send tails before deleting). Bypass sites are tagged `// TODO(queue-migrate):` — grep to find them; migrate incrementally when touching.
|
||||
4. **Logging is fire-and-forget.** Never `await logSystem/logError/logAutomation/logGmail/...`. Chain `.catch(() => {})` instead.
|
||||
5. **Use `ChannelType` enum from `discord.js`**, not bare integers (`0`, `4`, `5`, `12`, `15`).
|
||||
6. **Mongoose schema defaults:** pass function references (`default: Date.now`), never invocations (`default: Date.now()` pins all documents to module-load time).
|
||||
7. **No unsolicited refactors.** Don't rename, reorganize, or restructure beyond the fix's scope.
|
||||
8. **Backup before destructive data ops.** Provide the backup command first when the fix touches collections/files.
|
||||
|
||||
## Architecture
|
||||
|
||||
Single Node process. Entry: `broccolini-discord.js`.
|
||||
|
||||
### Startup order
|
||||
1. Module load: env validation, Discord `Client` created, `interactionCreate` / `messageCreate` listeners registered, `client.login(...)` called.
|
||||
2. Public Express app (`app`) is defined at module scope with a **503 gate** — any `/api/*` request before `appReady` returns 503.
|
||||
3. `client.once('ready')` (fires after Discord handshake): connects MongoDB, mounts bOSScord routes on `/api` (only if `BOSSCORD_API_KEY` set), calls `app.listen(CONFIG.PORT, CONFIG.HEALTHCHECK_HOST)`, sets `appReady = true`, then starts all background `setInterval`s.
|
||||
4. The **internal** Express app (`internalApp`) listens separately on `0.0.0.0:INTERNAL_API_PORT` inside the bot container at module load, guarded by `INTERNAL_API_SECRET`. Not publicly exposed — reachable only from peers on the `broccoli-net` docker network (notably the settings-site container).
|
||||
|
||||
### Two HTTP surfaces
|
||||
- **Public (`app`)** — `GET /` healthcheck + `/api/*` (bOSScord consumer). CORS origin is `process.env.BOSSCORD_CLIENT_ORIGIN` (default `http://100.114.205.53:3081`). Rate-limited 60 req/min/IP. Auth: `Authorization: Bearer ${BOSSCORD_API_KEY}`.
|
||||
- **Internal (`internalApp`)** — `broccoli-net` only (binds `0.0.0.0` inside the bot container; no host `ports:` publish), `/internal/*`. Rate-limited 10 req/min. Auth: `x-internal-secret` header. `POST /config` enforces an explicit `ALLOWED_CONFIG_KEYS` allowlist; unknown keys return 400. `POST /restart` exits the process so the container supervisor restarts it.
|
||||
|
||||
`routes/internalApi.js` is required at module scope by `broccolini-discord.js` *before* the parent's `module.exports` populates — reaching back to the parent (e.g., `trackInterval`, `trackTimeout`, `clearGmailPollInterval`) must use a **lazy `require('../broccolini-discord')` inside the handler**, not a top-level destructure.
|
||||
|
||||
### Intervals & shutdown
|
||||
- Every `setInterval` inside `ready` is wrapped via `trackInterval(...)` into the module-scoped `activeIntervals` Set.
|
||||
- `handleShutdown(signal)` is idempotent (`shuttingDown` flag): clears every tracked interval, closes both HTTP servers, calls `client.destroy()`, calls `closeMongoDB()`, then `process.exit(0)`. Wired to SIGTERM/SIGINT.
|
||||
- `setGmailPollInterval(ms)` and `clearGmailPollInterval()` manage the Gmail poll handle and keep it in sync with `activeIntervals`.
|
||||
|
||||
### Interaction error handling
|
||||
Every `interactionCreate` branch runs through `runHandler(name, interaction, fn)` which catches, `logError`s, and replies ephemerally `'Something went wrong.'` (uses `followUp` when the interaction is already deferred/replied). Setup buttons have their own try/catch for a custom error message.
|
||||
|
||||
### Tickets (`services/tickets.js`, `models.js`)
|
||||
- `Ticket` schema has indexes on `{gmailThreadId}` (unique), `{status, lastActivity}`, `{senderEmail, status}`, `{discordThreadId}`.
|
||||
- **Discord-originated tickets** use `gmailThreadId` with prefix `discord-` / `discord-msg-` — skip the Gmail reply path entirely.
|
||||
- Renames route through `utils/renamer.js` (RENAMER_BOT secondary token). On 401/403/429 from the secondary, `services/channelQueue.js` falls back to the primary bot via `channel.setName`. `canRename()` in `services/tickets.js` is retained as an always-ok shim for back-compat. `Ticket.renameCount` / `Ticket.renameWindowStart` remain in the schema but are now unread/unwritten orphan fields.
|
||||
- `getOrCreateTicketCategory()` handles Discord's 50-channels-per-category ceiling by creating `"<name> (Overflow N)"` categories; `cleanupEmptyOverflowCategory()` removes empties. The primary category is never deleted.
|
||||
- Scheduled jobs in `ready`: `checkAutoClose`, `checkAutoUnclaim`, `reconcileDeletedTicketChannels`, plus `services/staffNotifications.js#notifyAllStaffUnclaimed` and the pattern/surge/chat checkers.
|
||||
|
||||
### Gmail bridge (`gmail-poll.js`, `services/gmail.js`)
|
||||
- Polls `is:unread category:primary`, creates or appends to ticket channels.
|
||||
- **Auth failure halts polling.** On `invalid_grant` / `unauthorized` / 401: `pollSuspended = true`, the poll interval is cleared via `require('./broccolini-discord').clearGmailPollInterval()`, admin is DM'd once. Polling does **not** auto-retry — container must restart after re-auth.
|
||||
- `services/gmail.js` exports `sendGmailReply`, `sendTicketClosedEmail`, `sendTicketNotificationEmail`, `getGmailClient`. All HTML bodies go through `escapeHtml()`; `Date.now`-derived variables in templates come from `CONFIG` (`TICKET_CLOSE_MESSAGE`, `TICKET_CLOSE_SIGNATURE`, `SUPPORT_NAME`, `LOGO_URL`, `SIGNATURE`, `EMAIL_SIGNATURE`).
|
||||
|
||||
### Pattern / surge / chat (`services/patternStore.js` et al.)
|
||||
- In-memory counters bucketed into `today` / `week` / `month`, with scheduled resets at midnight / Monday 00:00 / 1st 00:00.
|
||||
- `escalatingCooldowns` entries carry a `lastUsed` timestamp; a 6-hour interval prunes entries idle for >48h. The cleanup interval is `.unref()`-ed so shutdown isn't blocked by it.
|
||||
|
||||
### `.env` persistence (`services/configPersistence.js`)
|
||||
- Values are stored in **backtick** containers because dotenv v17 only decodes `\n`/`\r` inside `"…"` (not `\"` or `\\`) — backticks preserve quotes + literal newlines verbatim. `readEnvFile` joins multi-line backtick values; `writeEnvFile` re-reads after write and throws on key-count mismatch.
|
||||
|
||||
## bOSScord integration
|
||||
|
||||
bOSScord is a separate React + Express cockpit app that consumes this bot's `/api/*` endpoints.
|
||||
- Base URL: `http://100.114.205.53:8892/api` · Bearer `${BOSSCORD_API_KEY}`.
|
||||
- bOSScord uses its own database (`bosscord_db`) — do not mix models.
|
||||
- **Response-shape changes on `/api/*` are breaking** for bOSScord. Coordinate or version.
|
||||
|
||||
## Known bad state
|
||||
|
||||
- **Gmail `invalid_grant`** — `REFRESH_TOKEN` is a stale placeholder. Poll suspends automatically on auth error; the rest of the bot still works. Fix by regenerating the token (`node get-refresh-token.js`) and restarting.
|
||||
- **`STAFF_EMOJIS` encoding** — some emoji entries render malformed. Root cause not identified.
|
||||
- **Escalation button** — handler misfires in some flows. Root cause not identified.
|
||||
|
||||
Do not re-report these as new findings.
|
||||
|
||||
## Environment highlights
|
||||
|
||||
Names and full tables are in `README.md` / `.env.example`. Ones that commonly trip up new code:
|
||||
|
||||
| Var | Notes |
|
||||
|-----|-------|
|
||||
| `DISCORD_TOKEN` **or** `DISCORD_BOT_TOKEN` | First non-empty after trim wins. |
|
||||
| `DISCORD_ONLY_PORT` | Maps to `CONFIG.PORT` (default 5000). |
|
||||
| `HEALTHCHECK_HOST` | Omit for all-interfaces; set `127.0.0.1` for local-only. |
|
||||
| `BOSSCORD_API_KEY` | Without it, `/api/*` is never mounted. |
|
||||
| `BOSSCORD_CLIENT_ORIGIN` | CORS origin for bOSScord (not `BOSSCORD_CORS_ORIGIN`). |
|
||||
| `INTERNAL_API_SECRET` | Without it, the internal settings API is never started. |
|
||||
| `INTERNAL_API_PORT` | Internal app's port (127.0.0.1 bind). |
|
||||
| `REFRESH_TOKEN` | Gmail OAuth; currently stale — see Known bad state. |
|
||||
|
||||
## Settings site
|
||||
|
||||
`settings-site/` contains a separate Express app (`settings-site/server.js`) for the admin UI — it talks to `internalApp` via `INTERNAL_API_SECRET`. It is **not** part of this bot's process. Changes to the bot's `/internal/config` contract (e.g., the `ALLOWED_CONFIG_KEYS` set) may break the settings UI. See `settings-site/CLAUDE.md` for that subproject's architecture and conventions.
|
||||
|
||||
Its Docker build context is `settings-site/` only — parent-repo files (e.g., `utils.js`) are unreachable inside the container. Any shared helper must be inlined or the build context widened in `docker-compose.yml`.
|
||||
@@ -1,76 +0,0 @@
|
||||
# CLAUDE.md
|
||||
|
||||
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||||
|
||||
## Scope
|
||||
|
||||
This is the **settings-site** subdirectory of the broccolini-bot repo. It is a **separate Express process** that provides an admin web UI for editing the bot's runtime config. It is **not** part of the bot's Node process.
|
||||
|
||||
The parent repo's rules in `/opt/broccolini-bot/CLAUDE.md` still apply here — especially **CommonJS only**, **read before write**, and **no unsolicited refactors**. Read that file alongside this one.
|
||||
|
||||
## Commands
|
||||
|
||||
- `npm start` — run the settings site (`node server.js`).
|
||||
- `npm run dev` — run with `node --watch` for auto-reload.
|
||||
- No lint, no test framework, no build step. Frontend is vanilla JS served from `public/` — no bundler.
|
||||
- Deploy via its own compose file: `docker compose up --build -d` from this directory. Container name `broccolini-settings`, joins external `broccoli-net`.
|
||||
|
||||
## Architecture
|
||||
|
||||
### Two processes, one `.env`
|
||||
The settings site is a thin HTTPS-oriented proxy in front of the bot's internal API:
|
||||
|
||||
```
|
||||
browser ──► settings server.js (:SETTINGS_PORT, default 12752)
|
||||
│ session auth (SETTINGS_ADMIN_PASSWORD)
|
||||
▼
|
||||
bot internalApp (broccoli-net only, INTERNAL_API_PORT, default 12753)
|
||||
│ header auth (x-internal-secret = INTERNAL_API_SECRET)
|
||||
▼
|
||||
routes/internalApi.js in /opt/broccolini-bot
|
||||
```
|
||||
|
||||
`server.js` loads `../.env` (the **bot's** env file) — both processes share it. `docker-compose.yml` also mounts `env_file: ../.env`, not a local one. There is no settings-site-specific env beyond what's in `.env.example`.
|
||||
|
||||
### Proxied endpoints
|
||||
`server.js` exposes five authenticated endpoints that forward to the bot's `/internal/*` API via `callBot()`:
|
||||
|
||||
| Settings route | Bot route |
|
||||
|---|---|
|
||||
| `GET /api/config` | `GET /internal/config` |
|
||||
| `POST /api/config` | `POST /internal/config` |
|
||||
| `GET /api/discord/guild` | `GET /internal/discord/guild` |
|
||||
| `POST /api/restart` | `POST /internal/restart` |
|
||||
| `GET /api/restart/status` | `GET /internal/restart/status` |
|
||||
| `GET /api/notifications/alerts` | `GET /internal/notifications/alerts` |
|
||||
| `GET /api/notifications/state` | `GET /internal/notifications/state` |
|
||||
| `POST /api/notifications/toggle` | `POST /internal/notifications/toggle` |
|
||||
|
||||
Every response-shape change in the bot's `/internal/*` handlers (`routes/internalApi.js`) is a breaking change here. The bot also gates `POST /internal/config` on an `ALLOWED_CONFIG_KEYS` allowlist — **adding a new field to the UI requires adding the key to that Set in the bot first**, otherwise the save returns 400 for that key.
|
||||
|
||||
### Second admin password
|
||||
`server.js` accepts an optional `SETTINGS_ADMIN_PASSWORD_2`. If set, the `/login` handler grants the same session for either password; no audit distinction between them. The primary `SETTINGS_ADMIN_PASSWORD` is still required at startup — only the second is optional. Both are redacted by the bot's `GET /internal/config` response.
|
||||
|
||||
### Session cookie requires HTTPS
|
||||
`server.js:20-26` sets `cookie.secure: true`. Browsers will refuse to persist the session cookie over plain HTTP, so login silently fails when not behind an HTTPS reverse proxy (`SETTINGS_DOMAIN` is the deployed domain). If you're reproducing a login bug, check this first before debugging auth logic. The `session secret` falls back to `'fallback-secret-change-me'` when `INTERNAL_API_SECRET` is unset — don't rely on the fallback in any environment that matters.
|
||||
|
||||
### Client-side routing
|
||||
`public/js/` is split into focused modules (phase 4 refactor): `app.js` (bootstrap), `router.js`, `fields.js`, `notifications.js`, `discord.js`, `login.js`, `util.js` — no bundler, loaded via `<script>` tags. Routes live in the `ROUTES` map (`router.js:4`); the server has a catch-all back to `index.html` (`server.js:202`, Express 5 `'/*splat'` syntax), so adding a client route only requires editing `ROUTES`.
|
||||
|
||||
### Config field binding (frontend)
|
||||
Any form element with `data-key="SOME_CONFIG_KEY"` participates in the editor:
|
||||
- `populateFields()` (`fields.js:11`) fills it from `GET /api/config` and wires change listeners.
|
||||
- Checkboxes serialize to the strings `'true'` / `'false'`, and `<input type="color">` serializes to `0xRRGGBB` — this matches how the bot stores these values.
|
||||
- `pendingChanges` accumulates diffs; `saveConfig()` POSTs the whole diff at once.
|
||||
- `data-smart="channel|category|role|member|multi-member"` swaps the bare `<input>` for a searchable Discord picker backed by `GET /api/discord/guild` (see `public/js/discord.js`).
|
||||
|
||||
**To add a new editable config field:** (1) add the key to the bot's `ALLOWED_CONFIG_KEYS`, (2) add a `<input data-key="NEW_KEY">` (optionally `data-smart=…`) inside the appropriate `.section` in `public/index.html`. No JS changes needed.
|
||||
|
||||
### Notification thresholds editor
|
||||
The Notifications section is **not** a simple `data-key` field — it's a custom editor in `notifications.js` that serializes into a single hidden `NOTIFICATION_THRESHOLDS_JSON` field. Alert metadata is now a **dynamic registry** (phase 5): the bot is canonical and serves it via `GET /api/notifications/alerts`; `notifications.js` uses `FALLBACK_TAB_KEYS` only if the fetch fails. **To add a new alert key, register it in the bot** (not in this codebase) — the UI picks it up automatically on next load. Threshold values accept whole numbers or duration strings matching `^(\d+[mhd])+$` (e.g. `15m`, `1h`, `1d6h`).
|
||||
|
||||
## Gotchas
|
||||
|
||||
- The frontend has no framework and no build — edit `public/js/*.js` directly; changes are live on reload.
|
||||
- `getaddrinfo` failures from `callBot()` surface to the UI as "Bot unreachable" (502). This is almost always the bot process being down or the internal port being wrong, not a bug in this codebase.
|
||||
- `docker-compose.yml` binds the port to the Tailscale IP `100.114.205.53:12752` — not `0.0.0.0`. Changing that binding has security implications.
|
||||
Reference in New Issue
Block a user