Imported from Cloudflare-Studio/ask-bonk (AGENTS.md). Install upstream with npx skills add Cloudflare-Studio/ask-bonk. Copyright stays with the author.

AGENTS.md

Last verified: 2026-07-03.

GitHub code review bot built on Cloudflare Workers, Flue, Hono, Durable Objects, and TypeScript. Use bun only.

Commands

bun install --frozen-lockfile                    # CI install; use after dependency changes to verify lockfile
bun install                                      # update bun.lock after package.json changes
bun update                                       # update dependencies within package.json ranges
bun run tsc --noEmit                             # typecheck Worker app
bun run test                                     # Vitest in Workers pool; do not use `bun test`
bun run test -- test/index.spec.ts               # focused test file
bun run lint                                     # oxlint
bun run build                                    # flue build --target cloudflare -> dist/ask_bonk
bunx wrangler types --check                      # verify worker-configuration.d.ts is current
bunx wrangler types                              # regenerate Worker bindings after wrangler/config changes
bunx wrangler deploy --dry-run --config dist/ask_bonk/wrangler.json --var BONK_VERSION:ci --var BONK_COMMIT:local
bun run dev                                      # Flue local dev server
bun run cli                                      # interactive installer/workflow CLI

Before considering a code change complete, run at least bun run tsc --noEmit, bun run test, and bun run lint. For Flue, Worker config, dependency, or deploy-path changes, also run bun run build, bunx wrangler types --check, and the generated-config dry-run deploy above.

When package.json changes, run bun install and commit package.json with bun.lock. CI uses bun install --frozen-lockfile.

Dependency Updates

• Use bun update for routine dependency refreshes. Keep updates within the existing package.json ranges unless the task explicitly asks for range or major-version changes.
• Commit both package.json and bun.lock whenever resolved dependency versions change. If package.json was edited manually, run bun install to refresh bun.lock before validation.
• For dependency PR summaries, list the packages that changed, call out major/minor changes and any packages intentionally excluded, and note source or test fixes required by dependency API changes.
• Wrangler, Workerd, @cloudflare/vitest-pool-workers, Flue, binding, migration, compatibility-date, and wrangler.jsonc changes can all change generated Worker types. Run bunx wrangler types after these changes, commit worker-configuration.d.ts when it changes, then run bunx wrangler types --check.
• Treat worker-configuration.d.ts header-only runtime changes as real generated output. Recent Wrangler updates have failed checks until the generated workerd@... version in this file was refreshed.
• Dependency update PRs must pass bun install --frozen-lockfile, bun run tsc --noEmit, bun run test, bun run lint, bun run build, bunx wrangler types --check, and the generated-config dry-run deploy command before they are complete.

Architecture

• src/index.ts is the Wrangler entrypoint shim: it exports the default app and RepoAgent only.
• src/app.ts owns the Hono app, non-Flue HTTP routes, auth endpoints, /stats, the legacy /webhooks route, and handleGitHubDelivery().
• src/channels/github.ts exports the Flue GitHub channel. The canonical webhook route is generated by Flue at /channels/github/webhook.
• src/workflows/github-setup.ts, src/workflows/github-track.ts, and src/workflows/github-finalize.ts are internal Flue workflows backing the OIDC-protected /api/github/* compatibility routes. They run through the Cloudflare Flue target and generated workflow Durable Objects.
• src/github-workflow-jobs.ts owns the shared setup, track, and finalize job logic used by those workflows.
• src/cloudflare.ts exports Cloudflare entrypoints for Flue discovery. Keep it in sync with exported Durable Object classes.
• src/agent.ts defines RepoAgent, the Durable Object that tracks workflow runs and posts/edit failure comments.
• github/action.yml and github/script/*.ts are the composite action that runs OpenCode inside GitHub Actions. The Worker does not run OpenCode itself.
• cli/ is the interactive installer/workflow generator. It uses gh CLI helpers and Handlebars templates.
• ae_queries/ SQL files are imported by Wrangler text rules for /stats Analytics Engine endpoints.

Webhooks And Flue

• Keep both webhook paths working: /channels/github/webhook is canonical Flue, /webhooks is legacy GitHub App compatibility.
• Do not replace /webhooks with a redirect. GitHub sends signed POST bodies; signature verification must see the exact body.
• The legacy /webhooks handler should use createGitHubChannel with GITHUB_WEBHOOK_SECRET and then call the same handleGitHubDelivery() path.
• If the Flue channel cannot read GITHUB_WEBHOOK_SECRET at module init, it uses an unguessable fallback so the generated route fails closed. Do not reintroduce a public fallback secret.
• /ask, Sandbox, and the container Dockerfile were removed. Only keep historical Sandbox mentions in Durable Object migrations (v4 create, v6 delete).

Auth And GitHub API

• All /api/github/* endpoints must follow: extractBearerToken() -> validateOIDCAndExtractRepo() -> compare OIDC owner/repo claims with request body owner/repo -> proceed.
• The /api/github/setup, POST /api/github/track, and PUT /api/github/track handlers must keep the OIDC checks above before admitting internal Flue workflows. The workflow routes themselves are internal-only and guarded by an unguessable in-process header from src/internal-workflows.ts.
• Cross-repo token exchange must keep all three checks: same org, public-to-private visibility block, and actor write access.
• PAT exchange remains disabled unless ENABLE_PAT_EXCHANGE is set.
• Use createOctokit() / createOctokitForRepo() from src/github.ts and src/oidc.ts; installation IDs are cached in APP_INSTALLATIONS and stale 404 cache entries are retried via API lookup.

RepoAgent Durable Object

• Durable Object name format is {owner}/{repo}. Persist owner and repo in state; alarm wakeups may not have this.name available.
• There are three finalization paths: action-driven PUT /api/github/track, DO alarm polling, and workflow_run.completed webhook safety net.
• RepoAgent still owns external GitHub Actions run state. Do not remove it just because setup/track/finalize are Flue workflows; OpenCode still runs in GitHub Actions, so Bonk needs cross-request active-run state, alarm polling, and failure-comment edit history outside Flue workflow run records.
• Reevaluate moving or reducing RepoAgent only when Bonk can run OpenCode inside a Flue-managed isolated sandbox and use Flue workflow run state as the primary execution record.
• workflow_run.completed must only post comments for tracked runs. Untracked workflow runs are metrics-only to avoid failure-comment spam.
• this.schedule() calls must stay wrapped in try/catch; the workflow_run webhook is the backup if scheduling fails.
• Failure comments are edited in place by context key (i:{issueNumber} or rc:{reviewCommentId}); preserve the create/edit fallback behavior.

GitHub Action Pitfalls

• Composite action steps do not share environment variables unless values are written to GITHUB_ENV. Outputs require core.setOutput() and steps.<id>.outputs.*.
• finalize.ts must never call core.setFailed(). It runs under if: always() and must not mask the real OpenCode failure.
• GitHub reports downstream skipped steps as skipped, not failure; keep the client-side and server-side remapping/treatment as failure.
• actions/checkout persists GITHUB_TOKEN in http.https://github.com/.extraheader. The action must replace it with the App installation token so Bonk pushes trigger CI.
• Multiline GITHUB_ENV and step output writes use random BONK_<uuid> delimiters to avoid injection.

Error Handling And Logging

• Use Result from better-result at API boundaries and domain TaggedError classes from src/errors.ts.
• Every Result.tryPromise needs a typed catch mapper. Do not allow unknown exceptions to leak through result types.
• Log through src/log.ts; never use raw console.log/info/error in app code.
• Use errorWithException() for exception logging because it sanitizes secrets. Git errors can contain tokenized remote URLs.
• Log event names are snake_case; include useful context such as request_id, owner, repo, issue_number, run_id, actor, and duration_ms when available.

Tests And Config

• Tests run through Vitest 4 with cloudflareTest() from @cloudflare/vitest-pool-workers; do not import the removed @cloudflare/vitest-pool-workers/config path.
• Tests should exercise real parsing, validation, request handlers, fixtures, and API boundaries. Avoid tests that only verify mocked structures.
• wrangler.jsonc is the source Worker config. bun run build writes the deployable Flue artifact to dist/ask_bonk/wrangler.json.
• worker-configuration.d.ts is generated. Regenerate it after Wrangler, binding, migration, compatibility date, or config changes.
• Prefer JSONC for config files unless a tool requires strict JSON.

Code Style

• Keep related code together; avoid new helpers/files until reuse or composition is real.
• Use type-only imports for types and group imports as external packages first, then local modules.
• External API code belongs in its domain file (github.ts, oidc.ts, workflow.ts, etc.).
• Comments should explain why, especially at I/O, external orchestration, and stateful boundaries. Skip comments that restate simple code.
• Cloudflare Worker code must use Workers-compatible APIs. Do not add Node-only fs, path, or child_process usage to src/.