npm package: @jameshiltonbarber/openpr
Description: CLI for reviewing pull requests and working OpenPR jobs from local coding agents.
Latest version: 0.1.3

# OpenPR

OpenPR is a polished MVP for a PR acceleration marketplace. It is designed around one core promise: reduce merge latency by routing the right review or implementation work back into GitHub fast enough to matter.

The current direction is GitHub-first:

- Login should happen through GitHub
- Repos, pull requests, and issues should sync from GitHub
- Product surfaces should minimize manual CRUD and focus on routing, matching, and delivery decisions

For local prototyping, the fastest path is Vault-backed token mode:

- configure WorkOS AuthKit env vars
- optionally add `GITHUB_OWNER` to constrain the repo list
- sign in and open `/app/settings`
- save the GitHub access token and optional Linear API key into WorkOS Vault
- use the synced PR and issue selectors in the request flows
- use the live review inbox at `/app/reviews/live`

The product deliberately treats work types differently:

- Review jobs are assignment-based. A maintainer posts a request with budget, urgency, review depth, and notes. The system matches one qualified reviewer or AI-backed operator.
- Fix jobs are scoped delivery requests. A maintainer can open the work to trusted contributors or agents and award one accepted solution.

## Stack

- Next.js App Router
- TypeScript
- Tailwind CSS v4
- shadcn/ui-style component primitives
- Drizzle ORM
- Postgres schema shaped for Neon
- Inngest workflow scaffolding
- Vercel-friendly route and deployment structure

## What’s included

- Marketing landing page focused on PR acceleration
- App dashboard with review jobs, fix jobs, activity, and spend/latency cards
- Review request creation flow
- Fix request creation flow
- Marketplace view for assigned reviews and open fix jobs
- Job detail page with timeline, delivery area, feedback state, and simulated GitHub bot activity
- Contributor launch packs for fix jobs with seeded prompts, branch names, PR copy, and local agent commands
- Reviewer reputation page with execution provenance and model/vendor details
- Maintainer analytics page
- Drizzle schema with audit-oriented tables
- Seed script for Neon/Postgres
- Mock GitHub App webhook/service layer
- Mock GitHub login route
- Local `openpr-agent` CLI with an Ink terminal UI for tool detection, job polling, review handoff, evaluation, and run-command generation
- Mock Inngest functions for sync, matching, bot comments, and reputation updates

## Information architecture

Routes:

- `/` marketing landing page
- `/app` dashboard overview
- `/app/reviews/live` Vault-backed review inbox
- `/app/reviews/live/[owner]/[repo]/[number]` live PR review workspace
- `/app/reviews/new` create review request
- `/app/fixes/new` create fix request
- `/app/settings` integration secret settings
- `/app/jobs` marketplace
- `/app/jobs/[jobId]` job detail
- `/app/reviewers/[reviewerId]` reviewer profile and reputation
- `/app/analytics` maintainer analytics
- `/api/github/webhooks` GitHub App webhook entrypoint
- `/api/inngest` Inngest function handler

Folders:

- [`src/app`](/Users/jhb/GitHub/openpr/src/app) route tree and route handlers
- [`src/components`](/Users/jhb/GitHub/openpr/src/components) shared app shell and UI building blocks
- [`src/components/ui`](/Users/jhb/GitHub/openpr/src/components/ui) shadcn-style primitives
- [`src/features/jobs`](/Users/jhb/GitHub/openpr/src/features/jobs) job forms and server actions
- [`src/lib`](/Users/jhb/GitHub/openpr/src/lib) domain types, demo data, formatting, GitHub services, and Inngest client/functions
- [`src/db`](/Users/jhb/GitHub/openpr/src/db) Drizzle schema and db client
- [`scripts/seed.ts`](/Users/jhb/GitHub/openpr/scripts/seed.ts) demo seeding for Postgres

## Domain model

Core tables in [`src/db/schema.ts`](/Users/jhb/GitHub/openpr/src/db/schema.ts):

- `users`
- `orgs`
- `github_installations`
- `repositories`
- `pull_requests`
- `issues`
- `jobs`
- `job_assignments`
- `reviewer_profiles`
- `skills`
- `reviewer_skills`
- `job_deliveries`
- `maintainer_feedback`
- `payouts`
- `disputes`
- `reputation_events`
- `activity_entries`

Important modeling choices:

- Jobs have `type: review | fix`
- Review jobs are assignment-driven
- Fix jobs can stay open and later be awarded
- Payout and reputation are stored separately
- Delivery provenance is first-class: execution mode, vendor, model, and operator label are stored on assignments and deliveries
- History-heavy entities are append-only where practical: deliveries, payouts, reputation events, activity entries, and feedback records

## Running locally

1. Install dependencies:

```bash
pnpm install
```

2. Create an env file:

```bash
cp .env.example .env.local
```

3. Start the app:

```bash
pnpm dev
```

4. Open [http://localhost:3000](http://localhost:3000)

5. Use the local contributor agent:

```bash
pnpm agent tools
pnpm agent review review-authpath-412
pnpm agent review circle-health-berlin/app#1046 --provider codex-cli --dry-run
pnpm agent jobs --provider codex-cli --skills react,testing
pnpm agent evaluate fix-vectorbase-233 --provider codex-cli --prompt "Only accept tightly scoped frontend fixes."
pnpm agent listen --provider codex-cli --orgs vectorbase,authpath --skills react,typescript --auto-accept --accept-prompt "Accept only small frontend bugs that fit in one sitting." --run-evaluator
```

## Install the CLI

Install the published CLI globally:

```bash
npm install -g @jameshiltonbarber/openpr
```

Then run the same agent workflows without `pnpm`:

```bash
openpr tools
openpr review circle-health-berlin/app#1046 --provider codex-cli --dry-run
openpr jobs --provider codex-cli --skills react,testing
openpr listen --provider codex-cli --orgs vectorbase,authpath --skills react,typescript
```

## Environment variables

See [`.env.example`](/Users/jhb/GitHub/openpr/.env.example).

- `POSTGRES_URL`: preferred runtime connection string for Vercel/Neon
- `POSTGRES_URL_NON_POOLING`: preferred migration/Drizzle CLI connection string when available
- `DATABASE_URL`: fallback connection string for local setups or non-Vercel environments
- `INNGEST_EVENT_KEY`: optional for live Inngest event delivery
- `INNGEST_SIGNING_KEY`: optional for hosted Inngest verification
- `OPENPR_BASE_URL`: base URL used by the local contributor CLI. Defaults to `https://openpr.hiltonbarber.com`; set it to `http://localhost:3000` when targeting a local dev server.
- `OPENPR_AGENT_SHARED_SECRET`: optional bearer secret for `/api/agent/*`
- `WORKOS_CLIENT_ID`: WorkOS AuthKit client id
- `WORKOS_API_KEY`: WorkOS AuthKit API key
- `WORKOS_COOKIE_PASSWORD`: 32+ character secret used to encrypt the WorkOS session cookie
- `NEXT_PUBLIC_WORKOS_REDIRECT_URI`: callback URL configured in WorkOS, typically `http://localhost:3000/auth/callback`
- `OPENPR_CURSOR_CLI_EVALUATE_TEMPLATE`: optional override for local Cursor evaluation command templating
- `OPENPR_CURSOR_CLI_RUN_TEMPLATE`: optional override for local Cursor run command templating
- `OPENPR_CODEX_CLI_EVALUATE_TEMPLATE`: optional override for local Codex evaluation command templating
- `OPENPR_CODEX_CLI_RUN_TEMPLATE`: optional override for local Codex run command templating
- `GITHUB_CLIENT_ID`: optional for a real GitHub OAuth login URL
- `GITHUB_REDIRECT_URI`: optional override for the GitHub OAuth callback URL
- `GITHUB_OWNER`: optional owner/org filter when using the GitHub token stored in WorkOS Vault
- `GITHUB_API_URL`: optional GitHub Enterprise API base URL override
- `GITHUB_APP_ID`: placeholder for the future GitHub App
- `GITHUB_APP_PRIVATE_KEY`: placeholder for installation auth
- `GITHUB_WEBHOOK_SECRET`: placeholder for real webhook signature verification

The UI runs on demo data by default, so a database is not required just to view the product.

Integration secrets no longer live in app env vars. After signing in, go to `/app/settings` and save:

- a GitHub personal access token as the GitHub integration secret
- optionally a Linear personal API key for ticket-context pulls

When a GitHub token is present in WorkOS Vault, the review client enables:

- a live review inbox sourced from open pull requests your token can read
- fetching line-level PR review comments and issue-thread discussion
- posting general PR comments
- replying to existing PR review comments

The local `openpr-agent` CLI uses the new `/api/agent/*` routes to:

- detect installed local coding CLIs such as Claude Code, Codex CLI, and Cursor CLI
- resolve review targets from an OpenPR job id or a raw `owner/repo#pr` ref
- check out the target PR locally and generate a PR-level review comment with the selected local CLI
- list open fix jobs for contributors
- fetch seeded task packs, repo bootstrap commands, and PR scaffolding
- run a prompt-driven evaluation pass before claiming a job
- auto-listen for new jobs from subscribed orgs and evaluate them with a contributor-authored prompt

## Database workflow

Generate SQL artifacts:

```bash
pnpm db:generate
```

Push schema to a connected Postgres database:

```bash
pnpm db:push
```

Seed demo data:

```bash
pnpm db:seed
```

## Core data model

The schema now has a stable backend-facing core on top of the seeded marketplace demo:

- `orgs` is the workspace record
- `workspace_memberships` maps users into workspaces with role and status
- `users` stores the canonical app user
- `user_identities` stores external auth/provider identities such as WorkOS and GitHub
- `repositories` is the canonical repo record, including provider and sync state
- `jobs` is the canonical work item record, with `orgId` acting as the workspace foreign key
- `job_lanes` defines the marketplace lanes a workspace can operate, including defaults for bidding, response targets, and execution style
- `provider_profiles` is the generalized marketplace profile for anyone doing work on the platform
- `provider_roles` lets one provider participate in multiple roles such as reviewer, contributor, and compute provider
- `provider_lane_memberships` tracks which providers are approved for which workspace lanes
- `job_bids` stores structured bidding and quoting against open jobs
- `job_contributions` stores the actual work units attached to a job, including review, implementation, and validation contributions
- `provider_scorecards` stores human review of provider performance for now, instead of relying purely on an opaque score
- `job_runs`, `job_run_events`, and `job_run_artifacts` capture runtime execution history

For API/frontend contracts, use the normalized record mappers in
[`src/lib/core/records.ts`](/Users/jhb/GitHub/openpr/src/lib/core/records.ts).
They expose stable `WorkspaceRecord`, `UserRecord`, `RepositoryRecord`, `JobRecord`, and `RunRecord`
shapes even where the underlying table names are still legacy (`orgs`, `orgId`, etc.).

Run tests:

```bash
pnpm test
```

## Mock integrations

GitHub:

- [`src/app/api/auth/github/login/route.ts`](/Users/jhb/GitHub/openpr/src/app/api/auth/github/login/route.ts) provides a mocked GitHub-first login entrypoint
- [`src/app/api/github/webhooks/route.ts`](/Users/jhb/GitHub/openpr/src/app/api/github/webhooks/route.ts) accepts pull request webhook payloads
- [`src/lib/github/auth.ts`](/Users/jhb/GitHub/openpr/src/lib/github/auth.ts) builds login targets and OAuth URLs
- [`src/lib/github/service.ts`](/Users/jhb/GitHub/openpr/src/lib/github/service.ts) contains WorkOS Vault-backed repo, PR, issue, and review comment calls plus placeholder GitHub App behaviors
- [`src/lib/github/bot.ts`](/Users/jhb/GitHub/openpr/src/lib/github/bot.ts) renders simulated bot-native comment bodies

Linear:

- [`src/lib/linear/service.ts`](/Users/jhb/GitHub/openpr/src/lib/linear/service.ts) pulls assigned Linear issues through the GraphQL API and maps them into fix-request source context
- [`src/lib/fix-request-sources.ts`](/Users/jhb/GitHub/openpr/src/lib/fix-request-sources.ts) merges GitHub and Linear work items for the fix request flow
- [`src/app/app/settings/page.tsx`](/Users/jhb/GitHub/openpr/src/app/app/settings/page.tsx) provides the in-app settings surface that writes integration secrets into WorkOS Vault

Contributor agent:

- [`scripts/openpr-agent.tsx`](/Users/jhb/GitHub/openpr/scripts/openpr-agent.tsx) provides a local CLI for `review`, `jobs`, `task-pack`, `evaluate`, `run`, and `listen`
- [`src/app/api/agent/jobs/route.ts`](/Users/jhb/GitHub/openpr/src/app/api/agent/jobs/route.ts) lists open contributor jobs
- [`src/app/api/agent/jobs/[jobId]/review-target/route.ts`](/Users/jhb/GitHub/openpr/src/app/api/agent/jobs/%5BjobId%5D/review-target/route.ts) resolves a review job into a GitHub PR target
- [`src/app/api/agent/jobs/[jobId]/task-pack/route.ts`](/Users/jhb/GitHub/openpr/src/app/api/agent/jobs/%5BjobId%5D/task-pack/route.ts) returns seeded task packs
- [`src/app/api/agent/jobs/[jobId]/claim/route.ts`](/Users/jhb/GitHub/openpr/src/app/api/agent/jobs/%5BjobId%5D/claim/route.ts) mocks local claims for the listener

Inngest:

- [`src/lib/inngest/client.ts`](/Users/jhb/GitHub/openpr/src/lib/inngest/client.ts) defines the client
- [`src/lib/inngest/functions.ts`](/Users/jhb/GitHub/openpr/src/lib/inngest/functions.ts) scaffolds webhook sync, internal activity, review matching, reviewer notification, bot comment simulation, and reputation updates

## TODOs for a production implementation

- Add first-class line comment creation from the live review workspace
- Exchange installation tokens and add real GitHub App posting for labels, assignments, and check runs
- Persist agent claims, task-pack issuance, and contributor state in the database
- Replace mocked claim flow with real assignment locks and PR submission tracking
- Persist form submissions via Drizzle inserts and drive redirect/state from the database
- Replace demo data with server-side queries
- Add auth, org membership, billing, and payout rails
- Add dispute resolution tooling and moderation workflows
- Add tests for schema, route handlers, and form actions

## Verification

Validated locally with:

```bash
pnpm lint
pnpm typecheck
pnpm test
pnpm build
```