Skip to content

CONTRIBUTE.md

Latest commit

 

History

History
102 lines (77 loc) · 4.1 KB

CONTRIBUTE.md

File metadata and controls

102 lines (77 loc) · 4.1 KB
Raw

Contributing to ULW

Thanks for helping improve ULW. This project is a VS Code extension that embeds an Open TUI terminal MUX in the sidebar, with node-pty for PTY support, xterm.js for rendering, tmux/zellij session management, and HTTP API communication with OpenCode.

Requirements

  • VS Code 1.106.0 or higher
  • Node.js 20.0.0 or higher
  • npm
  • OpenCode available on your PATH when testing OpenCode-specific behavior
  • tmux when testing tmux session, pane, or window behavior

Local Setup

git clone https://github.com/islee23520/ulwcode.git
cd ulwcode
npm install
npm run compile

For a local VSIX install, run:

npm run build-and-install

Development Commands

npm run compile        # Development webpack build
npm run watch          # Rebuild on changes
npm run package        # Production webpack build
npm run test           # Vitest unit tests
npm run test:watch     # Vitest watch mode
npm run test:coverage  # Vitest coverage report
npm run test:e2e       # VS Code extension E2E tests
npm run test:all       # Unit + E2E tests
npm run lint           # ESLint for src/**/*.ts
npm run format         # Prettier for source files

Coverage thresholds are enforced in vitest.config.ts: 80% lines, 80% functions, 80% statements, and 70% branches.

Project Structure

  • src/extension.ts: VS Code extension entry point.
  • src/core/: lifecycle orchestration and command registration.
  • src/providers/: VS Code webview providers for the terminal and dashboard.
  • src/services/: instance state, tmux, HTTP API, context, and other backend services.
  • src/terminals/: node-pty terminal process lifecycle.
  • src/webview/: browser-only terminal and dashboard code.
  • src/types.ts: shared host-to-webview and webview-to-host message contracts.
  • src/test/mocks/: manual vscode and node-pty mocks for tests.
  • dist/: webpack output generated by builds.

Coding Guidelines

  • Keep TypeScript strict-mode clean.
  • Follow existing naming: PascalCase classes and lowercase entrypoints such as extension.ts and main.ts.
  • Keep extension host code in core/, providers/, services/, and terminals/.
  • Keep webview code browser-only. Do not use Node APIs such as fs, path, or os in src/webview/.
  • Put shared host/webview message shape changes in src/types.ts.
  • Keep tmux logic in TmuxSessionManager; providers should delegate tmux operations to services.
  • Do not duplicate instance state outside InstanceStore.
  • Use OutputChannelService.getInstance() instead of constructing OutputChannelService directly.
  • Follow the existing manual mock patterns in src/test/mocks/.

Testing Changes

Run the smallest useful validation first, then widen before opening a PR.

For most changes:

npm run lint
npm run test
npm run compile

For packaging, activation, or VS Code integration changes, also run:

npm run test:e2e
npm run package

When changing terminal rendering, dashboard UI, commands, tmux behavior, or OpenCode communication, manually test the feature in VS Code after building or installing the VSIX.

Pull Request Checklist

  • Keep the change focused on one behavior or fix.
  • Sign the CLA when the pull request check asks for it. The CLA bot accepts the comment I have read the CLA Document and I hereby sign the CLA.
  • Add or update colocated *.test.ts tests when logic changes.
  • Update README.md or docs/ when user-visible behavior, commands, shortcuts, or settings change.
  • Update CHANGELOG.md for release-facing changes.
  • Confirm generated artifacts such as dist/, build/, coverage output, screenshots, logs, and .vsix files are not committed unless explicitly requested.
  • Do not commit local agent, editor, or test artifacts such as .opencode/, .sisyphus/, .claude/, .synapse/, .vscode-test/, or coverage/.

Release Notes

Publishing is tag-triggered through .github/workflows/publish.yml. Tags matching v* build the extension and publish to both the VS Code Marketplace and Open VSX using repository secrets. Do not place marketplace tokens or local credentials in source files or documentation.