Contributing

Guidelines for contributing to Portless CLI development

Development Setup

Portless uses a pnpm workspace monorepo with Turborepo for build orchestration. The publishable package lives in packages/portless/.

Prerequisites

• Node.js 20 or higher
• pnpm (install via npm install -g pnpm)
• Git
• macOS or Linux (Windows support may work but is not officially supported)

Clone and Install

# Clone the repository
git clone https://github.com/mattdanielmurphy/portless.git
cd portless

# Install all dependencies
pnpm install

Build

Build all packages in the monorepo:

pnpm build

This uses Turborepo to build packages in dependency order.

Run Tests

Portless has a comprehensive test suite:

# Run all tests
pnpm test

# Run tests with coverage report
pnpm test:coverage

# Run tests in watch mode (for development)
pnpm test:watch

Linting and Type Checking

# Lint all packages
pnpm lint

# Type-check all packages
pnpm typecheck

# Format code with Prettier
pnpm format

Local Development

To test your changes locally:

1. Build the package:

   pnpm build
   

2. Link it globally:

   cd packages/portless
   npm link
   

3. Use it in any project:

   portless run next dev
   

4. After changes, rebuild and the linked version will update:

   pnpm build
   

Debugging

For debugging the proxy server:

# Run in foreground to see all logs
portless proxy start --foreground

# Check the proxy log file
cat ~/.portless/proxy.log

# Check active routes
portless list

Monorepo Structure

portless/
├── packages/
│   └── portless/           # Main CLI package (publishable)
│       ├── src/
│       │   ├── cli.ts      # CLI entry point and command parsing
│       │   ├── proxy.ts    # HTTP/HTTPS proxy server logic
│       │   ├── routes.ts   # Route storage and management
│       │   ├── certs.ts    # TLS certificate generation
│       │   ├── hosts.ts    # /etc/hosts file management
│       │   ├── auto.ts     # Project name inference and worktree detection
│       │   ├── cli-utils.ts # CLI helper functions
│       │   ├── utils.ts    # General utilities
│       │   └── types.ts    # TypeScript type definitions
│       ├── package.json
│       └── tsconfig.json
├── skills/                 # Agent skills for AI coding assistants
│   └── portless/
│       └── SKILL.md        # Agent instructions for using portless
├── turbo.json              # Turborepo configuration
├── pnpm-workspace.yaml     # pnpm workspace config
├── CHANGELOG.md            # Version history
├── README.md               # Main documentation
└── AGENTS.md               # Rules for AI agents working on the repo

Package Manager Rules

Portless uses pnpm for all package management:

# Add a dependency
pnpm add <package>

# Add a dev dependency
pnpm add -D <package>

# Install all dependencies
pnpm install

# Run scripts
pnpm build
pnpm test

Exception: Global install instructions for end users should use npm install -g since it’s universal and most developers have npm by default.

Making Changes

Code Style

• No emojis anywhere in the codebase (code, comments, output, docs)
• Use TypeScript for all source files
• Follow the existing code style (enforced by ESLint and Prettier)
• Write clear, concise comments for complex logic

Testing

• Add tests for new features
• Update existing tests when changing behavior
• Ensure all tests pass before submitting a PR:
  pnpm test
  

Documentation

When a change affects how humans or agents use portless, update all three of these:

1. README.md - User-facing documentation
2. skills/portless/SKILL.md - Agent skill for AI coding assistants
3. packages/portless/src/cli.ts - --help output

This ensures consistency across all documentation surfaces.

Pull Request Guidelines

Before Submitting

1. Test your changes:

   pnpm test
   pnpm typecheck
   pnpm lint
   

2. Update the changelog: Add a description of your changes to CHANGELOG.md under the “Unreleased” section (or create one if it doesn’t exist).

3. Update documentation if needed (see above).

4. Build successfully:

   pnpm build
   

PR Title Format

Use conventional commit format:

• feat: add support for custom proxy headers
• fix: resolve certificate trust issue on Arch Linux
• docs: update installation instructions
• refactor: simplify route matching logic
• test: add e2e tests for worktree detection

PR Description

Include:

1. What - What changes did you make?
2. Why - Why were these changes necessary?
3. How - How did you implement the solution?
4. Testing - What testing did you do?

Example:

## What
Adds support for custom proxy headers via `--header` flag.

## Why
Users need to pass custom headers to backend services for
authentication or routing purposes.

## How
Extended the proxy request logic to include headers from a new
`--header` flag that can be specified multiple times.

## Testing
- Added unit tests for header parsing
- Tested manually with Next.js and Express apps
- Verified headers appear in backend logs

Review Process

1. A maintainer will review your PR
2. Address any feedback or requested changes
3. Once approved, a maintainer will merge your PR
4. Your changes will be included in the next release

Commit Messages

Use clear, descriptive commit messages:

# Good
git commit -m "fix: handle ECONNREFUSED gracefully in proxy"
git commit -m "feat: add --app-port flag for fixed port assignment"
git commit -m "docs: document Safari DNS workaround"

# Avoid
git commit -m "fix bug"
git commit -m "update code"
git commit -m "changes"

Release Process

(For maintainers)

1. Update version in packages/portless/package.json
2. Move “Unreleased” section in CHANGELOG.md to a new version section
3. Commit changes: git commit -m "chore: release v0.x.x"
4. Create git tag: git tag v0.x.x
5. Push changes and tag: git push && git push --tags
6. Publish to npm:
   cd packages/portless
   npm publish
   

Getting Help

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Documentation: https://port1355.dev

Code of Conduct

Be respectful and considerate of others. We’re all here to make portless better.

• Be welcoming and inclusive
• Respect differing viewpoints and experiences
• Accept constructive criticism gracefully
• Focus on what’s best for the community
• Show empathy towards other community members

Thank you for contributing to Portless!