A discord bot for teal.fm
besaid.zone
discord
tealfm
music
1# Disco Stu - Teal.fm Discord Bot
2
3This 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.
4
5**Repository Structure**
6
7- `apps/` : Application code (runtime programs and services)
8 - `bot/` : Discord bot (commands, deploy script)
9 - `tapper/` : Backfill client for Tap service
10 - `web/` : Web server to handle OAuth
11- `packages/` : Shared libraries used across apps
12 - `common/` : Logging and shared utilities
13 - `database/` : Database access, Kysely migrations and seed scripts
14 - `tsconfig/` : Shared TypeScript config packages
15
16**Apps**
17
18- `apps/bot` — Discord bot
19 - Entry: `apps/bot/main.ts`.
20 - Key files: `apps/bot/commands/*.ts` (command handlers), `apps/bot/deploy-commands.ts` (registers commands with Discord), `apps/bot/discord.d.ts` (types).
21 - Useful scripts (see [apps/bot/package.json](apps/bot/package.json)):
22 - `dev` — run bot in watch mode with `tsx --watch main.ts`
23 - `deploy-commands` — run `deploy-commands.ts` to push slash-command definitions to Discord
24 - `build` — compile TypeScript to `dist/`
25 - `start` — run compiled bot from `dist/main.js`
26
27- `apps/tapper` — Tap client
28 - Entry: `apps/tapper/index.ts`.
29 - Purpose: Interact with tap service running at https://tap.xero.systems
30 - Useful scripts (see [apps/tapper/package.json](apps/tapper/package.json)):
31 - `dev` — runs `NODE_ENV=development tsx index.ts`
32 - `start` — run compiled `dist/index.js` in production
33
34- `apps/web` — Web server
35 - Entry: `apps/web/index.ts`.
36 - Integrates with AT Protocol APIs and provides OAuth/web endpoints.
37 - Useful scripts (see [apps/web/package.json](apps/web/package.json)):
38 - `dev` — `tsx --watch index.ts` to run in dev
39 - `build` — compile TypeScript
40 - `start` — run compiled server from `dist/index.js`
41
42**Packages**
43
44- `packages/common` — shared utilities and logging
45 - Exports logging helpers and other common utilities used by apps. Build with `pnpm --filter @tealfmbot/common build` or use workspace protocol.
46 - Scripts: `build`, `build:watch`, `typecheck` (see [packages/common/package.json](packages/common/package.json)).
47
48- `packages/database` — Kysely-based database layer
49 - Contains DB helpers, `migrate.ts`, `seed.ts`, and Kysely codegen support.
50 - Scripts (see [packages/database/package.json](packages/database/package.json)):
51 - `migrate` — run `kysely migrate latest` to apply migrations
52 - `codegen` — run `kysely-codegen` to regenerate `database.d.ts`
53 - `seed` — run `tsx seed.ts` to seed data
54 - `build`, `build:watch`, `typecheck`
55
56- `packages/tsconfig` — shared TypeScript configs
57 - Provides base tsconfig settings shared by other packages.
58
59**Top-level scripts** (see [package.json](package.json))
60
61- `pnpm bot` — start the bot dev script (`pnpm --filter bot dev`)
62- `pnpm tap` — start the tapper dev script (`pnpm --filter tapper dev`)
63- `pnpm web` — start the web app dev script (`pnpm --filter web dev`)
64- `pnpm build` — run `pnpm -r build` to build all packages and apps
65- `pnpm build:watch` — run watch builds across the monorepo
66- `pnpm dev:all` — runs `dev` for all apps under `apps/`
67- `pnpm typecheck` — run TypeScript checks across apps
68- `pnpm lint` — run `oxlint` (project linter)
69- `pnpm format` — run `oxfmt` to format code
70
71Developer workflow
72
73- Install dependencies: `pnpm install` (pnpm v10+ recommended)
74- Develop a single app:
75 - Bot: `pnpm --filter bot dev` or `pnpm bot`
76 - Tapper: `pnpm --filter tapper dev` or `pnpm tap`
77 - Web: `pnpm --filter web dev` or `pnpm web`
78- Develop all apps concurrently: `pnpm dev:all`
79- Build all packages and apps: `pnpm build`
80
81Database tasks
82
83- Migrations are managed via Kysely. Run migrations from the `packages/database` package:
84
85```bash
86pnpm --filter @tealfmbot/database migrate
87```
88
89- Regenerate types (codegen):
90
91```bash
92pnpm --filter @tealfmbot/database codegen
93```
94
95Docker / deployment
96
97- `Dockerfile` and `docker-compose.prod.yml` are included for building and deploying container images.
98- The repository contains `build-and-publish-images.sh` to build and publish images (will be a CI thing eventually).
99
100Project tooling
101
102- `lefthook.yml` configures git hooks.
103- `oxlint` and `oxfmt` are used for linting and formatting.
104
105Notes & tips
106
107- To deploy Discord commands after changes, run the bot package `deploy-commands` script:
108
109```bash
110pnpm --filter bot deploy-commands
111```
112
113**Contributing & Quickstart**
114
115If you want to contribute or get a local development environment running quickly, follow these steps:
116
117- Clone the repo and install dependencies:
118
119```bash
120git clone https://tangled.org/dane.is.extraordinarily.cool/tealfmbot
121cd tealfmbot
122pnpm install
123```
124
125- Start and run database migrations
126
127```bash
128docker compose -f docker-compose.dev.yml up -d
129
130cd packages/database
131
132pnpm migrate
133```
134
135- Start individual apps in development:
136
137```bash
138# Bot
139pnpm bot
140
141# Tapper
142pnpm tap
143
144# Web
145pnpm web
146```
147
148- Start all apps concurrently (monorepo dev):
149
150```bash
151pnpm dev:all
152```
153
154- Build everything:
155
156```bash
157pnpm build
158```
159
160- Run TypeScript checks and format/lint before opening a PR:
161
162```bash
163pnpm typecheck
164pnpm lint
165pnpm format
166```
167
168Please open issues or PRs for new features, and include clear reproduction steps and expected behavior.