bee: Instructions file for Codex

AGENTS.md

This file provides guidance to AI coding agents when working with code in this repository.

Overview

bee (bee) — a CLI for the Backlog project management service. pnpm workspace monorepo with ESM-only packages.

Commands

# Install (also installs the pre-commit hook via `vp config`)
vp install

# Format + lint + type check (oxfmt, oxlint, tsgolint — NOT ESLint / tsc)
vp check
vp check --fix

# Test
vp test                                              # all tests
vp test packages/backlog-utils/src/client.test.ts    # single file

# Build
vp run --filter @nulab/bee build

# Dev (CLI)
vp run --filter @nulab/bee dev

Module Resolution: bundler

TypeScript is configured with module: "preserve" / moduleResolution: "bundler". This means:

• Relative imports omit the file extension:

  // Correct
  import { foo } from "./foo";
  // Wrong
  import { foo } from "./foo.js";
  import { foo } from "./foo.ts";
  

• Inline type keyword — use import { type Foo, bar } instead of separate import type { Foo } (enforced by oxlint)

Architecture

apps/cli             — CLI entry point (commander.js, consola logging)
apps/docs            — Astro Starlight documentation site
packages/backlog-utils — Backlog API client wrapper (backlog-js, OAuth auto-refresh, rate-limit handling)
packages/cli-utils   — Shared CLI utilities (output formatting, table, splitArg, prompts)
packages/config      — CLI configuration management (~/.config/bee RC file, space/auth resolution)
packages/test-utils  — Shared test helpers (mock client, mock consola, process.exit spy)
packages/tsconfigs   — Shared TypeScript base config

Documentation site (apps/docs)

Command reference pages are auto-generated from CLI source code — do NOT create .md files under apps/docs/src/content/docs/commands/. The dynamic route apps/docs/src/pages/commands/[...slug].astro uses loadCommands() (in apps/docs/src/lib/commands.ts) to import each command's BeeCommand metadata at build time and render documentation pages automatically.