Installation & Deployment
Relevant source files
The following files were used as context for generating this wiki page:
Installation and deployment for the Oh My Pi project involves setting up the @oh-my-pi/pi-coding-agent (the omp CLI), managing monorepo-wide releases, and configuring secure publishing environments. The project relies heavily on the Bun runtime for development tasks and script execution.
Sources: packages/coding-agent/DEVELOPMENT.md:1-12, scripts/release.ts:1-10
Development Environment Setup
Local development is centered around the Bun runtime. Developers primarily interact with the packages/coding-agent/ directory to manage the CLI's lifecycle.
Core Development Commands
The following table summarizes the essential commands for setting up and maintaining the coding agent:
| Task | Command | Description |
|---|---|---|
| Full Check | bun run check | Runs typechecking and linting (the primary gate). |
| Build Binary | bun run build | Compiles the dist/omp binary. |
| Install Dependencies | bun install | Regenerates lockfiles and installs packages. |
| Tooling Fix | bun run fix | Auto-fixes linting, formats prompts, and updates docs index. |
| Tool View Generation | bun run gen:tool-views | Rebuilds React tool renderers for the web collaborator. |
Sources: packages/coding-agent/DEVELOPMENT.md:15-28, scripts/release.ts:211-213
Repository Guidelines Generation
For fresh installations or new environments, an init agent can be used to scan the codebase and generate a Repository Guidelines document (AGENTS.md). This process involves parallel exploration agents scanning core source code, tests, configs, and scripts to synthesize findings into a single architectural overview.
Sources: packages/coding-agent/src/prompts/agents/init.md:1-20
Release Workflow
The project uses a centralized release script (scripts/release.ts) to manage versioning, changelogs, and CI synchronization across the monorepo.
Automated Release Sequence
The release process follows a strict linear sequence to ensure repository integrity and CI compliance.
The diagram shows the sequence of operations required to transition the repository from a development state to a tagged release state.
Sources: scripts/release.ts:153-294
Native Sentinel Management
A critical part of the release involves the pi-natives version sentinel. During a release, the script renames the Rust-side js_name literal to match the new version. This prevents binary incompatibility where a .node file from a previous release might be exposed to a new JS loader.
Sources: scripts/release.ts:192-208
NPM Deployment & Trust Configuration
Oh My Pi utilizes NPM Trusted Publishers (OIDC) to allow CI jobs to publish packages with provenance and without long-lived tokens.
Trusted Publisher Setup
Before CI can publish, each package must be linked to the GitHub repository workflow. This is handled by a specialized script that drives npm trust github for all public packages.
The sequence shows how local trust configuration enables future automated publishing from GitHub Actions.
Sources: scripts/setup-npm-trust.ts:10-40
Package Aggregation
The trust configuration and release notes generation depend on accurate package discovery within the packages/ and crates/ directories.
| Component Type | Discovery Method | Action |
|---|---|---|
| Public Packages | package.json (not private) | Configured for NPM trust and versioned. |
| Native Leaves | LEAF_TARGETS list | Auto-bootstrapped with placeholders if missing on registry. |
| Rust Crates | Cargo.toml workspace | Versioned via sd and cargo generate-lockfile. |
Sources: scripts/setup-npm-trust.ts:130-155, scripts/release.ts:178-200
Release Notes Generation
Release notes are aggregated from per-package CHANGELOG.md files. This system ensures that changes finalized under "silent" tags (tags created but not officially released due to CI cancellations) are rolled into the next successful release.
Aggregation Logic
- Floor Resolution: The script identifies the last successfully published release via the GitHub CLI (
gh release list). - Span Extraction: It extracts all version headers between the floor and the target version.
- Category Merging: Items are grouped by package name and then merged into canonical buckets (e.g., Breaking Changes, Added, Fixed).
- Deduplication: Bullet lines are deduplicated by trimmed text.
Sources: scripts/ci-release-notes.ts:15-60, scripts/ci-release-notes.ts:240-270
Conclusion
Installation and deployment in Oh My Pi are characterized by a "check-gate" philosophy where the Bun runtime enforces type and linting integrity before any deployment action. The system combines local interactive trust setup with fully automated, OIDC-secured CI publishing, ensuring a robust path from development to release.