Development

🛠️ Development

Set up, build, test, and contribute to opencode-codex-quota.

---

📋 Prerequisites

Requirement	Version
Node.js	>= 20
TypeScript	>= 6.0
npm	Latest

---

🚀 Setup

# Clone the repository
git clone https://github.com/guyinwonder168/opencode-codex-quota.git
cd opencode-codex-quota

# Install dependencies
npm install

---

📦 Commands

Command	Description
npm run build	TypeScript → dist/
npm run typecheck	Type checking only (no emit)
npm test	Run all tests
npm run test:coverage	Run tests with coverage report
npm run lint	Check code style (Biome)
npm run lint:fix	Fix code style issues

---

🧪 Testing

Tests use vitest with the Arrange-Act-Assert pattern. Mocks for fetch and fs are set up per test.

# Run all tests
npm test

# Run specific test file
npm test -- tests/auth-reader.test.ts

# Run with coverage
npm run test:coverage

Test Files

File	Coverage
tests/auth-reader.test.ts	Auth reading, JWT parsing, E1/E2/E3/E9/E10/E11 errors
tests/api-client.test.ts	API calls, timeout, validation, E4–E8 errors
tests/markdown.test.ts	Progress bars, clock formatting, compact/full output
tests/errors.test.ts	All E1–E11 error message formatting
tests/index.test.ts	Plugin module shape, hooks, command registration
tests/integration.test.ts	Full pipeline from auth → API → Markdown

---

🏗️ Project Structure

opencode-codex-quota/
├── src/
│   ├── index.ts              # Plugin entry point, tool definition
│   ├── types.ts              # All TypeScript interfaces
│   ├── services/
│   │   ├── auth-reader.ts    # Read auth.json → parse JWT → credentials
│   │   └── api-client.ts     # Call wham/usage → typed QuotaResponse
│   └── formatter/
│       ├── markdown.ts       # QuotaResponse → Markdown string
│       └── errors.ts         # Error codes → Markdown error messages
└── tests/
    ├── auth-reader.test.ts
    ├── api-client.test.ts
    ├── markdown.test.ts
    ├── errors.test.ts
    ├── index.test.ts
    └── integration.test.ts

---

🔧 Local Testing

After building, point OpenCode at your local package:

{
  "plugin": ["./path/to/opencode-codex-quota"]
}

Then run /codex_quota in OpenCode to test.

---

📏 Code Quality

The project uses Biome for linting and formatting:

• No any types — enforced by noExplicitAny: "error"
• No banned imports — enforced by noBannedImports: "error"
• 2-space indentation — spaces, not tabs
• Organized imports — auto-sorted

Run npm run lint before committing.

---

🔄 Commit Strategy

Commits follow a structured wave pattern:

Commit	Description
1	chore: project scaffolding with node.js, typescript, biome config
2	feat: add TypeScript type definitions for API + auth
3	feat: AuthReader service — read auth.json, parse JWT, handle E1-E11 errors
4	feat: ApiClient service — query wham/usage with timeout, validation, E4-E8 errors
5	feat: Formatter — Markdown output with compact/full modes, progress bars, time formatting
6	feat: error formatter — Markdown output for all E1-E11 scenarios
7	feat: plugin entry point — codex_quota tool with compact/full modes
8	test: integration tests — full pipeline from auth through API to markdown output
9	docs: add README with installation, usage, and development instructions

---

🤝 Contributing

Contributions are welcome! See CONTRIBUTING.md for guidelines.

---

📖 Next Steps

• Architecture — Understand the component design
• Technical-Reference — API details and type definitions