Disco Stu - Teal.fm Discord Bot#

This repository contains the Disco Stu Discord bot, supporting services, and shared packages used by the project. The workspace is a monorepo managed with pnpm and TypeScript; each app and package has its own package.json and build/dev scripts.

Repository Structure

• apps/ : Application code (runtime programs and services)
  • bot/ : Discord bot (commands, deploy script)
  • tapper/ : Backfill client for Tap service
  • web/ : Web server to handle OAuth
• packages/ : Shared libraries used across apps
  • common/ : Logging and shared utilities
  • database/ : Database access, Kysely migrations and seed scripts
  • tsconfig/ : Shared TypeScript config packages

Apps

• apps/bot — Discord bot

  • Entry: apps/bot/main.ts.
  • Key files: apps/bot/commands/*.ts (command handlers), apps/bot/deploy-commands.ts (registers commands with Discord), apps/bot/discord.d.ts (types).
  • Useful scripts (see apps/bot/package.json):
    • dev — run bot in watch mode with tsx --watch main.ts
    • deploy-commands — run deploy-commands.ts to push slash-command definitions to Discord
    • build — compile TypeScript to dist/
    • start — run compiled bot from dist/main.js

• apps/tapper — Tap client

  • Entry: apps/tapper/index.ts.
  • Purpose: Interact with tap service running at https://tap.xero.systems
  • Useful scripts (see apps/tapper/package.json):
    • dev — runs NODE_ENV=development tsx index.ts
    • start — run compiled dist/index.js in production

• apps/web — Web server

  • Entry: apps/web/index.ts.
  • Integrates with AT Protocol APIs and provides OAuth/web endpoints.
  • Useful scripts (see apps/web/package.json):
    • dev — tsx --watch index.ts to run in dev
    • build — compile TypeScript
    • start — run compiled server from dist/index.js

Packages

• packages/common — shared utilities and logging

  • Exports logging helpers and other common utilities used by apps. Build with pnpm --filter @tealfmbot/common build or use workspace protocol.
  • Scripts: build, build:watch, typecheck (see packages/common/package.json).

• packages/database — Kysely-based database layer

  • Contains DB helpers, migrate.ts, seed.ts, and Kysely codegen support.
  • Scripts (see packages/database/package.json):
    • migrate — run kysely migrate latest to apply migrations
    • codegen — run kysely-codegen to regenerate database.d.ts
    • seed — run tsx seed.ts to seed data
    • build, build:watch, typecheck

• packages/tsconfig — shared TypeScript configs

  • Provides base tsconfig settings shared by other packages.

Top-level scripts (see package.json)

• pnpm bot — start the bot dev script (pnpm --filter bot dev)
• pnpm tap — start the tapper dev script (pnpm --filter tapper dev)
• pnpm web — start the web app dev script (pnpm --filter web dev)
• pnpm build — run pnpm -r build to build all packages and apps
• pnpm build:watch — run watch builds across the monorepo
• pnpm dev:all — runs dev for all apps under apps/
• pnpm typecheck — run TypeScript checks across apps
• pnpm lint — run oxlint (project linter)
• pnpm format — run oxfmt to format code

Developer workflow

• Install dependencies: pnpm install (pnpm v10+ recommended)
• Develop a single app:
  • Bot: pnpm --filter bot dev or pnpm bot
  • Tapper: pnpm --filter tapper dev or pnpm tap
  • Web: pnpm --filter web dev or pnpm web
• Develop all apps concurrently: pnpm dev:all
• Build all packages and apps: pnpm build

Database tasks

• Migrations are managed via Kysely. Run migrations from the packages/database package:

pnpm --filter @tealfmbot/database migrate

• Regenerate types (codegen):

pnpm --filter @tealfmbot/database codegen

Docker / deployment

• Dockerfile and docker-compose.prod.yml are included for building and deploying container images.
• The repository contains build-and-publish-images.sh to build and publish images (will be a CI thing eventually).

Project tooling

• lefthook.yml configures git hooks.
• oxlint and oxfmt are used for linting and formatting.

Notes & tips

• To deploy Discord commands after changes, run the bot package deploy-commands script:

pnpm --filter bot deploy-commands

Contributing & Quickstart

If you want to contribute or get a local development environment running quickly, follow these steps:

• Clone the repo and install dependencies:

git clone https://tangled.org/dane.is.extraordinarily.cool/tealfmbot
cd tealfmbot
pnpm install

• Start and run database migrations

docker compose -f docker-compose.dev.yml up -d

cd packages/database

pnpm migrate

• Start individual apps in development:

# Bot
pnpm bot

# Tapper
pnpm tap

# Web
pnpm web

• Start all apps concurrently (monorepo dev):

pnpm dev:all

• Build everything:

pnpm build

• Run TypeScript checks and format/lint before opening a PR:

pnpm typecheck
pnpm lint
pnpm format

Please open issues or PRs for new features, and include clear reproduction steps and expected behavior.