Discord operations service for the Valkyria Wardogs clan. English slash command names, Czech descriptions and replies by default, with explicit English response selection. The website is maintained separately in ValkyriaWDG/www.
The service includes a reproducible Discord simulation lab: production command handlers, real PostgreSQL, local HTTP fixtures and a browser evidence viewer. Start with the documentation index or member and administrator guide. Bot provisioning, credentials and live Discord/game-server acceptance remain separate gates; see STATUS.md and live acceptance.
/helpand/account: command help, fresh membership and configured capabilities./server statusand/server players: private, role-authorized server information./admin broadcast,kick,ban,unban,map,restart: saved 60-second confirmations, fresh authorization, atomic claims and durable audit. Restart means restart the match, not the host process. Game writes start disabled.- Discord role observations and departures produce a transactional, signed outbox for the website. Delivery starts disabled. The proposed receiver contract must be implemented and verified with the website before enabling it.
- PostgreSQL migrations, process lease, safe unknown outcomes, health endpoints, container/CI definitions and repository-native agent workflows.
- Private signed management API with fresh Discord grants, durable replay protection and persisted desired/effective safe settings.
- Match/result publications and server boards, durable event cursor and message bindings, with separate create/edit recovery semantics.
- Czech/English private signup buttons using the website's canonical roster through the versioned website contract. These extensions start disabled; see activation and recovery.
The website owns Discord OAuth, sessions, administrator login and website RBAC. This service does not mint website sessions or grant permissions from an unverified event. No generic server console command or arbitrary host-control endpoint is exposed.
Use Node 24 (.node-version) and the exact pnpm version in package.json.
pnpm install --frozen-lockfile
pnpm lint
pnpm format:check
pnpm typecheck
pnpm test
pnpm build
pnpm check:repository
pnpm check:commits
pnpm demo
node dist/main.js --offlineThe demo prints a synthetic command transcript: help, status, confirmation,
single dispatch, duplicate rejection and role revocation. It never contacts Discord
or a game server. Offline health returns /health/live 200 and /health/ready 503;
this deliberately does not claim live readiness.
Copy config/bot.example.json to ignored config/bot.json, then run
pnpm commands:register for an offline command manifest. No token is required.
Actual registration is a separate, explicitly targeted operation in the
operations guide.
For database tests, set TEST_DATABASE_URL to a disposable dedicated PostgreSQL
database, then run pnpm test:integration. Tests clear fixture tables; this command
fails if its database configuration is missing. The unit suite does not include DB tests.
The lab uses fictional members and servers; it does not require or use a Discord
token. Follow the database setup for a disposable PostgreSQL
fixture and set LAB_DATABASE_URL as shown there. Then:
pnpm exec playwright install chromium
pnpm test:e2e
pnpm lab:run
pnpm test:visual
pnpm lab:serveOpen http://127.0.0.1:4178. The read-only viewer displays actual serialized command
responses beside database and HTTP assertions. Scenarios cover all six administrative
operations, Czech/English help, lost permissions, duplicate/expired confirmations,
unknown outcomes, Discord delivery failures, durable audit and signed role delivery.
The lab guide explains scope, screenshots and regeneration.
Generated reports and browser captures stay in .local/lab; the
screenshot gallery contains reviewed, dated evidence with
source revisions, captions and SHA-256 hashes.
flowchart LR
Discord[Discord slash commands and role events] --> Bot[Bot service]
Bot --> DB[(Dedicated PostgreSQL)]
Bot --> RCON[Allowlisted Wardogs HTTPS API]
DB --> Outbox[Signed role event outbox]
Outbox --> Web[Website receiver: separate implementation]
Web -->|Signed private management| Bot
Bot -->|Signed event feed and participation| Web
Bot -->|Publication queue| Discord
| Area | Entry point |
|---|---|
| Architecture and scope | Design, implementation plan |
| Discord and game API | Commands, Wardogs wire evidence |
| Auth integration | Website contract |
| Operations and future work | Runbook, roadmap |
| Agent delivery | AGENTS.md, CLAUDE.md, skills |
| Review and proof | Contributing, evidence policy |
CI checks source, unit and real PostgreSQL behavior, builds and smoke-tests the container, and runs the full simulated Discord pipeline with Chromium captures. All three jobs must pass the required Quality gate. Image publication is a separate, initially disabled workflow: a reviewed main SHA, successful CI, protected environment and configured private registry are required. It does not deploy. See release workflow.
Only example configuration belongs in Git. Runtime .env and config/bot.json are
ignored; .env is not loaded automatically by the application. Export environment
variables or use Node's --env-file option as documented in the runbook.
The optional BOT_EXTENSIONS_FILE selects an ignored extensions JSON. Without it,
management, publication workers and signup buttons remain disabled. Copy the supplied
config/extensions.example.json only when preparing the separately accepted integration.
No open-source license grant has been selected for this repository yet. Public source availability does not grant a license to Valkyria branding or third-party game assets. Four unmodified Wardogs press-kit images are cataloged for an offline presentation proposal; they are not activated in live commands. See NOTICE for provenance and copyright exclusions. Private parent-workspace configuration is not included.
