# 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](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](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](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/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](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](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:

```bash
pnpm --filter @tealfmbot/database migrate
```

- Regenerate types (codegen):

```bash
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:

```bash
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:

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

- Start and run database migrations

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

cd packages/database

pnpm migrate
```

- Start individual apps in development:

```bash
# Bot
pnpm bot

# Tapper
pnpm tap

# Web
pnpm web
```

- Start all apps concurrently (monorepo dev):

```bash
pnpm dev:all
```

- Build everything:

```bash
pnpm build
```

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

```bash
pnpm typecheck
pnpm lint
pnpm format
```

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