Contributing Guidelines

​

Scope and Compliance

• Official OAuth authentication flows only - PKCE-based OAuth2 with proper token lifecycle management
• No token scraping, cookie extraction, or auth bypasses - All authentication must use legitimate OAuth endpoints
• No rate-limit circumvention techniques - Respect OpenAI’s rate limiting and usage policies
• No commercial multi-user resale features - This is a developer productivity tool for individual use

​

Local Setup

git clone https://github.com/ndycode/codex-multi-auth.git
cd codex-multi-auth
npm ci

npm run typecheck  # TypeScript strict mode validation
npm run lint       # ESLint (TS + scripts)
npm test           # Vitest suite (87 files, 2071 tests)
npm run build      # tsc + copy oauth-success.html

# Test the CLI wrapper
./scripts/codex.js --version

# Verify repo hygiene
npm run clean:repo:check

​

Development Standards

​

Code Quality Requirements

• TypeScript strict mode - All code must pass strict: true compilation
• No type escape hatches - Forbidden: as any, @ts-ignore, @ts-expect-error
• Behavior-focused tests - All user-visible changes require test coverage
• Documentation parity - Keep docs aligned when commands, flags, paths, or defaults change

​

TypeScript Conventions

// Template literal types for compile-time safety
type QuotaKey = `quota-${string}`;

// Discriminated unions for state management
type TokenResult = 
  | { success: true; accessToken: string }
  | { success: false; error: string };

// Zod for runtime validation
import { z } from 'zod';
const AccountSchema = z.object({
  accountId: z.string(),
  refreshToken: z.string(),
  addedAt: z.number(),
  lastUsed: z.number(),
});

​

Documentation Requirements

• README.md - High-level overview and quick start
• docs/getting-started.md - Installation and first-time setup
• docs/features.md - Feature descriptions and use cases
• Affected docs/reference/* files - Command references, settings, paths

​

Pull Request Process

git checkout -b feature/account-health-improvements

npm run typecheck  # Must pass with no errors
npm run lint       # Must pass with no warnings
npm test           # All 2071 tests must pass
npm run build      # Must build successfully

codex --version
codex auth status
codex auth report --json

​

Issue and Feature Requests

​

Before Opening Issues

• Search existing issues and PRs - Avoid duplicates
• Reproduce on latest main when possible
• Include exact commands, output, and environment data

​

Bug Report Requirements

codex --version
codex auth status
codex auth report --json
npm ls -g codex-multi-auth

# Environment
node --version
npm --version
uname -a  # or `ver` on Windows

​

Feature Request Format

• User impact - Who benefits and how?
• Policy/compliance consideration - Does this align with OpenAI terms?
• Alternatives considered - What other approaches did you evaluate?
• Implementation sketch - Rough technical approach (optional)

​

Security Reporting

1. Contact the maintainer privately via GitHub profile contact channel
2. Include vulnerability description, reproduction steps, and impact assessment
3. Target response time: within 48 hours

​

Code of Conduct

​

Expected Behavior

• Respectful, constructive communication
• Technically grounded discussions with evidence
• Clear reproduction steps when reporting issues
• Focus on facts and problem-solving

​

Unacceptable Behavior

• Requests to violate policy boundaries or OpenAI terms
• Credential sharing or unsafe security guidance
• Abusive or hostile communication
• Demands for features that enable terms violations

​

Testing Philosophy

• 80% coverage threshold across statements, branches, functions, and lines
• Property-based testing for rotation logic and edge cases (using fast-check)
• Chaos testing for fault injection scenarios
• Windows filesystem safety - All cleanup uses removeWithRetry with EBUSY backoff

​

Repository Hygiene

# Clean generated files deterministically
npm run clean:repo

# Validate repo hygiene (CI-gated)
npm run clean:repo:check

• dist/ - Build output
• .tmp*/ - Temporary directories
• coverage/ - Test coverage reports
• node_modules/ - Dependencies

​

License