miniapp-api/test/.trae/skills/bugpack-deploy/SKILL.md

---
name: "bugpack-deploy"
description: "Deploy and configure BugPack (bug screenshot to AI instructions tool) on Windows with MSYS2. Invoke when user asks to setup/install/deploy BugPack or fix its build/runtime issues."
---

# BugPack Deploy Skill

This skill guides the deployment of [BugPack](https://github.com/duhuazhu/BugPack) on Windows using MSYS2 environment.

## Prerequisites

- Windows OS
- MSYS2 installed (usually at `C:\msys64` or `D:\msys64`)
- Internet connection for downloading packages

## Environment Setup

### 1. MSYS2 Configuration

Open MSYS2 terminal and update the system:

```bash
pacman -Syu
# If prompted to close terminal, close and reopen, then run:
pacman -Su
```

### 2. Install Required Tools

```bash
pacman -S --noconfirm git curl make
pacman -S --noconfirm mingw-w64-x86_64-nodejs
pacman -S --noconfirm mingw-w64-x86_64-gcc
```

### 3. Node.js Environment Variables

Add to `~/.bashrc` or export manually:

```bash
export PATH="/mingw64/bin:$PATH"
export LD_LIBRARY_PATH="/mingw64/bin:$LD_LIBRARY_PATH"
```

**Note**: `LD_LIBRARY_PATH` is required because `libnode.dll` is in `/mingw64/bin`.

### 4. Create Node.js Symlinks (Optional but recommended)

```bash
ln -sf /mingw64/bin/node.exe /usr/bin/node
ln -sf /mingw64/lib/node_modules/npm/bin/npm-cli.js /usr/bin/npm
ln -sf /mingw64/lib/node_modules/npm/bin/npx-cli.js /usr/bin/npx
```

## Deployment Steps

### 1. Download BugPack

```bash
# Option A: Clone with git
git clone https://github.com/duhuazhu/BugPack.git
cd BugPack

# Option B: Download and extract ZIP
curl -L -o BugPack.zip https://github.com/duhuazhu/BugPack/archive/refs/heads/main.zip
unzip BugPack.zip
cd BugPack-main
```

### 2. Install Dependencies

```bash
npm install
```

### 3. Build Project

```bash
npm run build
```

### 4. Fix Static File Path (Production Mode)

**Issue**: Server looks for `src/client/index.html` but built files are in `dist/client/`.

**Fix**: Edit `src/server/index.ts`:

```typescript
// Before (line ~47):
const clientDir = path.resolve(__dirname, '../client')

// After:
const clientDir = path.resolve(__dirname, '../../dist/client')
const devClientDir = path.resolve(__dirname, '../client')
const staticDir = fs.existsSync(clientDir) ? clientDir : devClientDir

if (fs.existsSync(staticDir)) {
  app.use(express.static(staticDir))
  app.get('*', (req, res) => {
    if (!req.path.startsWith('/api') && !req.path.startsWith('/uploads')) {
      res.sendFile(path.join(staticDir, 'index.html'))
    }
  })
}
```

### 5. Start Server

```bash
# Development mode (with auto-reload)
npm run dev:server

# Or specify custom port
PORT=3458 npm run dev:server
```

Server will start at `http://localhost:3457` (or your custom port).

## Common Issues & Solutions

### Issue 1: `node: command not found`

**Cause**: Node.js installed in `/mingw64/bin` but not in PATH.

**Solution**:
```bash
export PATH="/mingw64/bin:$PATH"
```

### Issue 2: `libnode.dll: cannot open shared object file`

**Cause**: DLL not found in library path.

**Solution**:
```bash
export LD_LIBRARY_PATH="/mingw64/bin:$LD_LIBRARY_PATH"
```

### Issue 3: `better-sqlite3` build fails with `make: cc: No such file`

**Cause**: C compiler not installed.

**Solution**:
```bash
pacman -S --noconfirm mingw-w64-x86_64-gcc make
```

### Issue 4: `ENOENT: no such file or directory, stat '.../src/client/index.html'`

**Cause**: Server configured for dev mode but running production build.

**Solution**: Apply the static file path fix in Step 4 above.

### Issue 5: `EADDRINUSE: address already in use :::3457`

**Cause**: Another instance is running.

**Solution**:
```bash
# Use different port
PORT=3458 npm run dev:server
```

### Issue 6: MSYS2 mirror network issues

**Symptom**: All mirrors return "Could not resolve host".

**Solution**: Network environment issue. Try:
1. Check internet connection
2. Switch to different network
3. Or configure specific mirror:
```bash
cat > /etc/pacman.d/mirrorlist.mingw64 << 'EOF'
Server = https://mirrors.tuna.tsinghua.edu.cn/msys2/mingw/x86_64/
Server = https://mirrors.ustc.edu.cn/msys2/mingw/x86_64/
EOF
pacman -Syy
```

## Verification

After deployment, verify:

```bash
# Check server is running
curl -s http://localhost:3457 | head -5

# Expected output: HTML content starting with <!DOCTYPE html>
```

## MCP Server Configuration

To integrate with Trae/Cursor/Claude Code, add MCP config:

```json
{
  "mcpServers": {
    "bugpack": {
      "command": "npx",
      "args": ["bugpack-mcp", "--mcp"]
    }
  }
}
```

## Tech Stack

| Component | Technology |
|-----------|------------|
| Frontend | React 18 + TypeScript + Tailwind CSS |
| Backend | Express + Node.js |
| Database | SQLite (better-sqlite3) |
| Annotation | Fabric.js v6 |
| Build Tool | Vite |

## Data Storage

All data stored locally:
- **Data directory**: `~/.bugpack/data/`
- **Database**: `bugpack.db`
- **Screenshots**: `uploads/{ProjectName}/{uuid}.{ext}`