ops-jrz1/docs/dev-onboarding.md

# Maubot Plugin Development - Dev Onboarding

This guide walks you through setting up your development environment for building maubot plugins.

## Prerequisites

1. **VS Code** with the [Remote-SSH extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-ssh)
2. **SSH key pair** - if you don't have one:
   ```bash
   ssh-keygen -t ed25519 -C "your-email@example.com"
   ```
3. **Your public key** - send this to the admin:
   ```bash
   cat ~/.ssh/id_ed25519.pub
   ```

## Getting Connected

Once the admin has set up your account, you'll receive connection details.

### 1. Configure SSH

Add this to your SSH config file (`~/.ssh/config` on Mac/Linux, `C:\Users\YOU\.ssh\config` on Windows):

```
Host maubot-dev
    HostName <server-ip>
    User <your-username>
    LocalForward 29316 127.0.0.1:29316
```

Replace `<server-ip>` and `<your-username>` with the values provided by your admin.

### Alternative: mosh for unstable connections

If you have a spotty internet connection, use [mosh](https://mosh.org/) instead of SSH. It handles disconnects and roaming gracefully:

```bash
mosh <your-username>@<server-ip>
```

Note: mosh doesn't support port forwarding, so you'll need a separate SSH tunnel for the maubot UI.

### 2. Connect with VS Code

1. Open VS Code
2. Press `F1` (or `Cmd+Shift+P` / `Ctrl+Shift+P`)
3. Type "Remote-SSH: Connect to Host"
4. Select `maubot-dev`
5. Wait for VS Code to connect

### 3. Open Your Plugin Folder

Once connected:
1. Click "Open Folder"
2. Navigate to `/home/<your-username>/plugins/hello_<your-username>`
3. Click "OK"

You should see your starter plugin files.

## Your First Plugin

Your starter plugin responds to two commands:
- `!hello` - Says hello
- `!ping` - Responds with pong

### Build and Deploy

1. Open the integrated terminal in VS Code (`Ctrl+`` ` or `View > Terminal`)

2. Build your plugin:
   ```bash
   make build
   ```
   This creates a `.mbp` file in the `dist/` folder.

3. Open the maubot admin UI:
   - In your browser, go to: http://localhost:29316
   - Log in (ask admin for credentials)

4. Upload your plugin:
   - Go to "Plugins" tab
   - Click "Upload new plugin"
   - Select your `.mbp` file from `dist/`

5. Create an instance:
   - Go to "Instances" tab
   - Click "Create instance"
   - Select your plugin and a bot user
   - Add `#devs-sandbox` to allowed rooms
   - Click "Create"

6. Test in Matrix:
   - Join the `#devs-sandbox` room
   - Type `!hello` - your bot should respond!

## Plugin Development

### File Structure

```
hello_yourname/
├── maubot.yaml          # Plugin manifest (name, version, etc.)
├── hello_yourname/      # Python module
│   ├── __init__.py      # Module init
│   └── bot.py           # Your bot code
├── Makefile             # Build commands
└── dist/                # Built .mbp files
```

### Adding Commands

Edit `hello_yourname/bot.py`:

```python
from maubot import Plugin, MessageEvent
from maubot.handlers import command

class Bot(Plugin):
    @command.new("hello")
    async def hello_command(self, evt: MessageEvent) -> None:
        await evt.reply("Hello!")

    # Add your new command here:
    @command.new("dice")
    async def dice_command(self, evt: MessageEvent) -> None:
        import random
        result = random.randint(1, 6)
        await evt.reply(f"🎲 You rolled a {result}!")
```

### Development Workflow

1. Edit your code in VS Code
2. Run `make build` in the terminal
3. In maubot admin, go to your instance and click "Reload"
4. Test your changes in Matrix

### Makefile Commands

| Command | Description |
|---------|-------------|
| `make build` | Build the .mbp plugin file |
| `make check` | Check Python syntax |
| `make clean` | Remove built files |

## Troubleshooting

### "Connection refused" when opening localhost:29316

The SSH tunnel isn't working. Make sure:
- You're connected via VS Code Remote-SSH
- Your SSH config has the `LocalForward` line
- Try disconnecting and reconnecting

### Plugin doesn't appear in maubot

- Check that `make build` completed without errors
- Make sure you uploaded the `.mbp` file from the `dist/` folder
- Check the maubot logs for errors

### Bot doesn't respond to commands

- Make sure the bot is in the room (check room members)
- Check that the room is in "allowed_rooms" in instance config
- Check maubot logs for errors
- Commands are case-sensitive: `!hello` not `!Hello`

### Syntax errors

Run `make check` to validate Python syntax before building.

### Need to see logs

In the maubot admin UI, go to "Logs" to see recent activity and errors.

## Resources

- [Maubot Documentation](https://docs.mau.fi/maubot/)
- [Maubot Plugin Examples](https://github.com/maubot)
- [Matrix Python SDK (mautrix)](https://docs.mau.fi/python/latest/)

## Shared Server Tools

This is a shared Unix server. Classic tools for seeing who's around and communicating:

| Command | What it does |
|---------|--------------|
| `who` | See who's logged in |
| `w` | Who's logged in + what they're doing |
| `finger <user>` | User info + their `.plan` file |
| `write <user>` | Send a message to their terminal |
| `wall` | Broadcast message to all logged-in users |
| `ytalk <user>` | Split-screen chat (both must be online) |

### Your .plan file

Create `~/.plan` to tell others what you're working on:

```bash
echo "Building a dice bot. Ask me about random numbers." > ~/.plan
```

Others can see it with `finger yourname`.

## Getting Help

- Ask in `#devs-sandbox` - other devs and admins can help
- Use `write` or `ytalk` if another dev is online
- Check the maubot logs for error messages
- Review the maubot documentation