Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
205 lines (136 loc) · 4.32 KB

CONTRIBUTING.md

File metadata and controls

205 lines (136 loc) · 4.32 KB

Contributing to TeamCopilot

Development Setup

Prerequisites

  • Node.js 20+
  • npm
  • Python 3.10+

Install dependencies

From the repo root:

npm install
cd frontend
npm install
cd ..

TeamCopilot installs its forked OpenCode runtime from GitHub release tarballs, so you do not need any extra OpenCode setup for normal app development.

If you are working on the OpenCode runtime itself, clone and build the local fork separately too:

git clone https://github.com/rishabhpoddar/opencode.git opencode-fork
cd opencode-fork
bun install
bun run --cwd packages/opencode build
cd ..

Configure the environment

Create a local .env in the repo root:

cp .env.example .env

Default values in .env.example:

  • WORKSPACE_DIR=./my_workspaces
  • TEAMCOPILOT_HOST=0.0.0.0
  • TEAMCOPILOT_PORT=5124
  • OPENCODE_PORT=4096
  • OPENCODE_MODEL=openai/gpt-5.3-codex

Adjust these if needed before starting the app.

If you are using the repo-local OpenCode fork while developing the runtime, set OPENCODE_BIN_PATH in .env to:

OPENCODE_BIN_PATH=/Users/rishabhpoddar/Desktop/trythisapp/teamcopilot/opencode-fork/packages/opencode/dist/opencode-darwin-arm64/bin/opencode

opencode-fork/ is ignored by git in this repo, so it stays local to your machine.

The TeamCopilot runtime itself is pinned to the release assets in src/utils/opencode-release.ts, so normal installs use the published GitHub tarballs automatically.

Run in development mode

Use the combined dev server for hot reload:

npm run dev

This starts:

  • backend on TEAMCOPILOT_PORT from .env (default 5124)
  • frontend Vite dev server on 5173

Open http://localhost:5173 for frontend development.

Run backend or frontend separately

Backend only:

npm run dev:backend

Frontend only:

cd frontend
npm run dev

Verify a production build locally

npm run build
npm start

Open http://localhost:5124 unless you changed the port in .env.

Managing the Database

View Database Contents

# Open Prisma Studio (visual database browser)
npm run prisma:studio

Modify the Schema

  1. Edit prisma/schema.prisma
  2. Create and apply a migration:
npm run prisma:migrate:dev -- --name describe-your-changes

Reset Database

# Warning: This deletes all data
npm run prisma:migrate:reset

Releasing to npm

Use the root-level .agents/skills/release-teamcopilot-npm/SKILL.md skill when preparing an npm release.

Example prompts:

Use /release-teamcopilot-npm to dry-run the next npm release.

Use /release-teamcopilot-npm to publish the current package.json version to npm, then create the matching GitHub release.

The preferred command is now:

npm run release:teamcopilot

Add --with-opencode-fork when the release includes a new OpenCode fork build:

npm run release:teamcopilot -- --with-opencode-fork

Use --dry-run to exercise the full release flow without publishing:

npm run release:teamcopilot -- --dry-run

The command handles the lockfile refresh, test/build checks, and npm publish step for you. The skill still enforces these release checks:

  • package.json and package-lock.json versions must match
  • npm whoami must return trythisapp
  • npm run test must pass
  • npm run build must pass
  • npm pack --json must succeed

For the trythisapp npm account, the recommended release flow is a full dry run first, then a second publish step with:

npm run release:teamcopilot -- --skip-checks --otp <fresh-code>

That keeps the TOTP code fresh for the final publish step while still using the same release wrapper.

After a successful npm publish, the skill also creates a GitHub tag matching the package version and uses gh to create the GitHub release notes from changes since the previous release.

Troubleshooting

Port Already in Use

lsof -ti:5124 | xargs kill -9

Database Errors

# Reset and recreate the database
rm "$WORKSPACE_DIR/.sqlite/data.db"
npm run prisma:migrate:dev

Frontend Not Loading

Make sure the frontend is built:

cd frontend
npm run build