Development Setup
Relevant source files
The following files were used as context for generating this wiki page:
This page provides the necessary technical information to set up, develop, and verify the PlanQueue extension. PlanQueue is a TypeScript-based extension for the Oh My Pi (OMP) coding agent harness that utilizes the Bun runtime for development and testing.
The development environment is designed to ensure strict type safety through TypeScript and consistent code styling via the Biome toolchain. The project architecture separates OMP-specific wiring in src/main.ts from pure logic imported from the @aryrabelo/planqueue-core package.
Sources: CONTRIBUTING.md:14-17, README.md:139-142, package.json:44-53
Prerequisites and Installation
The project requires the Bun runtime (version 1.0.0 or higher) for dependency management and execution.
Environment Requirements
| Requirement | Specification | Source |
|---|---|---|
| Runtime | Bun >= 1.0.0 | CONTRIBUTING.md:5 |
| Language | TypeScript | package.json:52 |
| OS Interface | Node.js APIs (via Bun) | tsconfig.json:8 |
Initial Setup
To prepare the local development environment, clone the repository and install dependencies using Bun:
bun install
To integrate the local development build into an active OMP harness for testing, use the following OMP command:
omp plugin link
Sources: CONTRIBUTING.md:9-11, CONTRIBUTING.md:25-27
Development Workflow and Verification
The project enforces a "full gate" verification process that must pass before opening a pull request. This process includes linting, type checking, and unit testing.
Verification Commands
Developers should run the following combined command to verify changes:
bun run lint && bun run typecheck && bun test
Sources: CONTRIBUTING.md:15-17
Logic and Architecture Flow
The following diagram illustrates the relationship between the development tools and the code verification flow:
The diagram shows how source code must pass through multiple validation layers (Biome, TypeScript Compiler, and Bun Test) before reaching the pull request stage.
Sources: CONTRIBUTING.md:14-22, package.json:40-44
Project Configuration
The project behavior and code style are defined through several configuration files.
Biome Configuration (biome.json)
Biome is used for both linting and formatting. It is configured to use tabs for indentation and double quotes for JavaScript/TypeScript files.
| Rule Category | Setting | Description |
|---|---|---|
| Formatter | indentStyle: "tab" | Uses tabs for code indentation. |
| Linter | preset: "recommended" | Applies standard recommended linting rules. |
| JavaScript | quoteStyle: "double" | Enforces double quotes for strings. |
| Suspicious | noExplicitAny: "error" | Disallows the use of the any type. |
Sources: biome.json:11-12, biome.json:17-19, biome.json:34-36
TypeScript Configuration (tsconfig.json)
The project uses strict mode for TypeScript to ensure type safety.
- Target/Module:
ESNext - Module Resolution:
bundler - Strict Mode: Enabled (
true) - Unchecked Indexed Access: Enabled for safer array/object access.
Sources: tsconfig.json:3-10, CONTRIBUTING.md:19-20
Development Standards and Conventions
To maintain code quality, developers must adhere to the following conventions:
- Pure Modules: Logic contained in pure modules (e.g., within
planqueue-core) must remain free of OMP host imports. All OMP-specific wiring and integration must live insrc/main.ts. - Testing: Any new pure logic must be accompanied by a corresponding test in the
tests/directory. - Commits: Use English and follow the Conventional Commits standard.
- Formatting: Run
bun run format(which executesbiome check --write .) before committing changes to apply auto-fixes and formatting.
Sources: CONTRIBUTING.md:19-23, package.json:44
Component Relationship Diagram
The following class diagram represents the high-level interaction between the OMP Extension API and the internal PlanQueue components:
The diagram depicts the OMP extension lifecycle where PlanQueueExtension acts as the orchestrator, utilizing the OMP ExtensionAPI to manage the QueueController and update UI components.
Sources: src/main.ts:167-175, src/main.ts:400-430
Conclusion
The Development Setup for PlanQueue leverages the Bun ecosystem to provide a high-performance environment with strict linting and type-safety requirements. By adhering to the established verification gates and code conventions, contributors ensure that the extension remains stable and maintainable within the OMP ecosystem.
Sources: CONTRIBUTING.md:1-23, README.md:139-145