Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
249 lines (188 loc) · 8.18 KB

CONTRIBUTING.md

File metadata and controls

249 lines (188 loc) · 8.18 KB

Contributing to TermBeam

Thank you for your interest in contributing! Here's everything you need to know.

Prerequisites

  • Node.js ≥ 20
  • npm ≥ 9
  • Git
  • A terminal (macOS, Linux, or Windows with WSL)

Setup

# 1. Fork on GitHub, then clone your fork
git clone https://github.com/<your-username>/TermBeam.git
cd TermBeam

# 2. Install dependencies (also sets up pre-commit hooks via Husky)
npm install

# 3. Verify everything works
npm test

Development

Running Locally

# Start with auto-generated password (recommended for dev)
npm run dev

# Start with custom options
node bin/termbeam.js --port 8080 --password dev123

# Start with default settings (no password, localhost only)
npm start

Open the printed URL on your phone or browser to test the UI.

Project Structure

termbeam/
├── bin/termbeam.js          # CLI entry point (just requires src/server.js)
├── src/
│   ├── server.js             # Main orchestrator — wires everything together
│   ├── cli.js                # CLI argument parsing, --help, --version
│   ├── auth.js               # Authentication, tokens, rate limiting, login page
│   ├── logger.js             # Structured logger with configurable levels
│   ├── sessions.js           # SessionManager class — PTY lifecycle
│   ├── shells.js             # Shell detection (Windows + Unix)
│   ├── routes.js             # Express HTTP routes (API + pages)
│   ├── websocket.js          # WebSocket connection handling
│   ├── tunnel.js             # DevTunnel integration
│   └── version.js            # Smart version detection (npm vs dev)
├── public/
│   ├── index.html            # Session manager UI (mobile)
│   └── terminal.html         # Terminal UI (xterm.js + touch controls)
├── test/
│   ├── auth.test.js          # Auth module tests
│   ├── cli.test.js           # CLI argument parsing tests
│   ├── integration.test.js   # Integration tests (HTTP + WebSocket)
│   ├── logger.test.js        # Logger module tests
│   ├── routes.test.js        # HTTP route tests
│   ├── sessions.test.js      # Session manager tests (mocked PTY)
│   ├── shells.test.js        # Shell detection tests
│   ├── version.test.js       # Version detection tests
│   └── websocket.test.js     # WebSocket handler tests
├── docs/                     # MkDocs documentation source
├── .github/workflows/        # CI, release, and docs deployment
├── package.json
└── mkdocs.yml

Key Files to Know

File What it does When to edit
src/server.js Orchestrator Adding new middleware or startup logic
src/cli.js CLI parsing Adding new flags or env vars
src/routes.js HTTP routes Adding new API endpoints
src/websocket.js WebSocket handler Changing terminal I/O behavior
src/auth.js Auth system Changing authentication logic
src/sessions.js PTY management Changing how sessions are created/managed
src/logger.js Logging Changing log format or levels
src/shells.js Shell detection Adding new shell types
src/tunnel.js DevTunnel Changing tunnel creation or lifecycle
public/index.html Session list UI UI changes on the main screen
public/terminal.html Terminal UI Terminal rendering, touch controls

Making Changes

  1. Create a feature branch:

    git checkout -b feat/my-feature

  2. Make your changes. The pre-commit hook will automatically:

    • Format staged files with Prettier
    • Syntax-check JS files with node --check

  3. Run tests locally:

    npm test

  4. Test manually — start the server and verify on your phone:

    npm run dev

Testing

We use Node.js built-in test runner (node:test + node:assert). No extra test framework needed.

# Run all tests
npm test

# Run a specific test file
node --test test/auth.test.js

# Run tests with verbose output
node --test --test-reporter=spec test/*.test.js

Writing Tests

  • Tests live in test/<module>.test.js
  • Use node:test (describe/it) and node:assert
  • Mock node-pty for session tests (see test/sessions.test.js for the pattern)
  • Clear require.cache between tests when testing modules that read process.argv

What to Test

  • ✅ Pure logic (parsing, validation, token generation)
  • ✅ Middleware behavior (auth, rate limiting)
  • ✅ Session lifecycle (create, list, delete, shutdown)
  • ⚠️ WebSocket/HTTP integration — manual testing for now

Code Style

  • Formatter: Prettier (runs automatically via pre-commit hook)
  • Config: .prettierrc (single quotes, trailing commas, 100 char width)
  • Linting: node --check for syntax validation
  • Manual: npm run format to format all files, npm run lint to syntax-check

Key principles:

  • Minimal dependencies — prefer built-in Node APIs
  • Keep modules focused — one responsibility per file
  • Comment why, not what
  • Follow existing patterns in the codebase

Commit Convention

We use Conventional Commits:

<type>(<scope>): <description>
Type Description Example
feat New feature feat(auth): add OAuth2 support
fix Bug fix fix(terminal): handle resize on rotation
docs Documentation docs: update security guide
refactor Code restructuring refactor(sessions): extract PTY spawn logic
test Tests test(auth): add rate limit edge cases
chore Tooling/CI chore(ci): add Node 22 to matrix
perf Performance perf(ws): reduce JSON serialization overhead

Breaking changes: Add ! after the type:

feat!: require password by default

Submitting a Pull Request

  1. Push your branch to your fork
  2. Open a PR against main on dorlugasigal/TermBeam
  3. Fill in the PR template (if available)
  4. Ensure CI passes (tests run on Node 20, 22, 24)
  5. Wait for review — we'll provide feedback if needed

PR Checklist

  • Tests pass locally (npm test)
  • New features have tests
  • Commits follow conventional format
  • Documentation updated (if user-facing changes)
  • Manually tested on mobile (if UI changes)

Releasing (Maintainers Only)

Releases are triggered manually via GitHub Actions:

  1. Go to Actions → Release workflow
  2. Click Run workflow
  3. Select the bump type:
    • patch (0.0.x) — bug fixes, small changes
    • minor (0.x.0) — new features, backward compatible
    • major (x.0.0) — breaking changes
  4. The workflow automatically:
    • Bumps the version in package.json
    • Updates CHANGELOG.md with commit history
    • Commits, tags, and pushes
    • Publishes to npm
    • Creates a GitHub Release with auto-generated notes

Version Flow Example

Current: 1.2.3
  → patch bump → 1.2.4
  → minor bump → 1.3.0
  → major bump → 2.0.0

Documentation

Docs are built with MkDocs Material and deployed to GitHub Pages.

# Install mkdocs locally (one-time)
pip install mkdocs-material

# Preview docs
mkdocs serve

# Docs are in docs/ directory

Changes to docs/ or mkdocs.yml pushed to main auto-deploy to GitHub Pages.

Community

  • Be kind and respectful to all contributors
  • Welcome newcomers and help them get started
  • Give constructive feedback
  • Assume good intentions

Thank you for making TermBeam better! 📡