bee AGENTS.md

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
pnpm install

# Lint (oxlint, NOT ESLint)
pnpm run lint
pnpm run lint:fix

# Type check (tsc --noEmit per package via turbo)
pnpm run typecheck

# Format (oxfmt)
pnpm run format
pnpm run format:check

# Test
pnpm run test                                              # all tests
pnpm --filter @repo/backlog-utils exec vitest run src/client.test.ts # single file

# Build
pnpm --filter @nulab/bee build

# Dev (CLI)
pnpm --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, vi.clearAllMocks setup)
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.