Local Development Setup

Guide for setting up a local development environment.

Prerequisites

• pnpm - Package manager (required for workspaces)
• Bun - Backend runtime
• OpenCode TUI 2.x, 2.0.15 or newer - curl -fsSL https://opencode.ai/v2/install | bash

Installation

# Clone the repository
git clone https://github.com/chriswritescode-dev/opencode-manager.git
cd opencode-manager

# Install dependencies
pnpm install

The pnpm dev command automatically runs scripts/setup-dev.sh first, which:

• Checks prerequisites (pnpm, bun, git, OpenCode TUI)
• Creates required workspace directories
• Copies .env.example to .env if missing

Then start development servers:

pnpm dev

This starts:

• Backend on http://localhost:5003
• Frontend on http://localhost:5173 (with HMR)

Project Structure

opencode-manager/
├── backend/              # Bun + Hono API server
│   ├── src/
│   │   ├── routes/       # API route handlers
│   │   ├── services/     # Business logic
│   │   ├── db/           # Database migrations and queries
│   │   │   └── migrations/  # Numbered migration files
│   │   ├── types/        # TypeScript types
│   │   ├── utils/        # Utility functions
│   │   └── index.ts      # Entry point
│   └── test/             # Backend tests
├── frontend/             # React + Vite SPA
│   ├── src/
│   │   ├── components/   # UI components
│   │   ├── pages/        # Page components
│   │   ├── hooks/        # Custom React hooks
│   │   ├── api/          # API client
│   │   ├── lib/          # Utilities
│   │   ├── stores/       # Zustand stores
│   │   └── contexts/     # React contexts
│   └── public/           # Static assets
├── shared/               # @opencode-manager/shared types and utilities
├── ocm-cli/              # ocm CLI for attaching a local OpenCode TUI to Manager repos
├── workspace/            # Runtime workspace for OpenCode
├── docs/                 # Documentation
├── scripts/              # Build and utility scripts
├── Dockerfile            # Docker image definition
└── docker-compose.yml    # Docker Compose configuration

Available Scripts

Root Level

pnpm dev          # Start both backend and frontend (runs setup-dev.sh first)
pnpm dev:backend  # Start backend only
pnpm dev:frontend # Start frontend only
pnpm build        # Build CLI, backend, and frontend
pnpm lint         # Lint CLI, frontend, and backend
pnpm test         # Run CLI, backend, and frontend tests

Backend

cd backend
bun --watch-path src --watch src/index.ts  # Start with hot reload
pnpm test                 # Run bun tests, then Vitest with coverage
vitest <file>             # Run single test file
vitest --ui               # Test UI
vitest --coverage         # Coverage report
eslint . --ext .ts        # Lint
tsc --noEmit              # TypeScript check

Frontend

cd frontend
pnpm dev          # Start Vite dev server
pnpm build        # Production build
pnpm lint         # ESLint
pnpm typecheck    # TypeScript check

Database

Using Bun's built-in SQLite (bun:sqlite) with numbered migrations.

Location

• Development: ./data/opencode.db
• Docker: /app/data/opencode.db

Schema Changes

1. Add new migration file in backend/src/db/migrations/ (e.g., 007-new-feature.ts)
2. Export the migration in backend/src/db/migrations/index.ts
3. Migrations run automatically on startup

Inspection

sqlite3 ./data/opencode.db

# Useful commands
.tables                  # List tables
.schema user             # Show table schema
SELECT * FROM user;      # View data

Testing

Running Tests

# All tests
cd backend && pnpm test

# Single file
cd backend && pnpm test src/services/repo.test.ts

# With UI
cd backend && pnpm test:ui

# With coverage
cd backend && pnpm test -- --coverage

Writing Tests

import path from 'path'
import { describe, it, expect } from 'vitest'
import { Database } from 'bun:sqlite'
import { getReposPath } from '@opencode-manager/shared/config/env'
import { migrate } from '../src/db/migration-runner'
import { allMigrations } from '../src/db/migrations'
import { createRepoRow } from '../src/services/repo'

describe('createRepoRow', () => {
  it('creates a ready local repo row', () => {
    const db = new Database(':memory:')
    migrate(db, allMigrations)

    const { repo, created } = createRepoRow(db, {
      name: 'demo',
      localPath: 'demo',
      fullPath: path.join(getReposPath(), 'demo'),
    })

    expect(created).toBe(true)
    expect(repo.cloneStatus).toBe('ready')
    expect(repo.isLocal).toBe(true)

    db.close()
  })
})

Coverage Requirements

Minimum 80% coverage is enforced.

Debugging

Backend

Logs output to terminal when running pnpm dev. For verbose debug logging:

# Add to .env
DEBUG=true

Frontend

1. Open browser DevTools (F12)
2. Check Console for errors
3. Check Network tab for API calls
4. Use React DevTools extension

Building

Development Build

pnpm build

Production Build

NODE_ENV=production pnpm build

Docker Build

docker build -t opencode-manager .

Common Issues

Port Already in Use

# Find process using port
lsof -i :5003

# Kill process
kill -9 <PID>

Module Not Found

# Clear node_modules and reinstall
rm -rf node_modules
rm -rf */node_modules
pnpm install

TypeScript Errors

# Check types
pnpm typecheck

# Clear TypeScript cache
rm -rf */tsconfig.tsbuildinfo

Database Issues

# Reset database
rm -f data/opencode.db
pnpm dev  # Database is recreated