git:20260814.bcdb586 to git:20260819.665016a

# AGENTS.md

## Monorepo Overview

Bun-based monorepo with workspace packages under `packages/*`. The marketing site (devintern.com) and its server code live in a separate repository.

| Package | Role | Published |

| ------------------------------ | --------------------------------------------------------------------------------------------------------------------- | --------------- |

| `@getdevintern/code` | CLI for task automation (`devintern`): Jira + multi-PM support, configurable AI agent | yes |

| `@getdevintern/pm` | CLI for PM task/story creation (`devpm`): supports Jira, Linear, Trello, Azure DevOps, Asana, GitHub Issues, Markdown | yes |

| `@devintern/pm-desktop` | Electron desktop app for `@getdevintern/pm`: multi-ticket AI task creation for your tracker | no, application |

| `@devintern/agent-harness` | Shared agent harness abstraction | no, source-only |

| `@devintern/dashboard-ui` | Local observability dashboard UI (Vite + React), bundled into `@getdevintern/code` at build time | no, source-only |

| `@devintern/auth` | Shared Supabase auth utilities (CLI login/session) | no, source-only |

| `@devintern/license-check` | Shared license checking | no, source-only |

| `@getdevintern/license-policy` | Shared entitlement policy and secretless Polar key validation | no, source-only |

| `@devintern/text-formatter` | Shared text formatting | no, source-only |

| `@devintern/utils` | Shared utilities (`fetchWithRetry`, CLI auto-update check, etc.) | no, source-only |

| `@devintern/task-trackers` | Shared task tracker config and API clients (Jira, Linear, Trello, etc.) | no, source-only |

**Tooling:** Bun exclusively: runtime, package manager, bundler, and test runner. Do not use `node`, `npm`, `pnpm`, `jest`, or `vitest`.

## Developer Commands

```bash

bun install

bun run build

bun run typecheck

bun run test

bun run format

bun run lint

# Single package

bun run --filter @getdevintern/code test

bun run --filter @getdevintern/pm build

```

**Pre-commit (lefthook):** runs `format` (with `stage_fixed`), then `lint`, then `typecheck` sequentially (not parallel). If you commit manually without lefthook, run them in that order.

## Package-Specific Notes

### `@getdevintern/code`

- Entry: `src/index.ts`

- Tests: `bun test` (Bun native test runner in `tests/`)

- Build: `bun run build.ts`: bundles with `Bun.build`, then replaces shebang from `node` to `bun` in `dist/index.js`

- Run locally: `bun start TASK-123`

- Tests use isolated temp directories, essential for parallel execution (do not share temp dirs across tests)

- Uses `bun:sqlite` for webhook queue

### `@getdevintern/pm`

- Runtime abstraction: file I/O, path resolution, stdin, and CLI args are centralized under `lib/runtime/` using Node.js built-ins. Application code must not use `Bun.*` runtime APIs.

- Build target is Node.js so the bundle runs under plain Node.js and Electron; `ink`, `react`, and `ink-scroll-view` stay external and resolve at runtime.

### `@devintern/pm-desktop`

- Electron app built with electron-vite; React + shadcn/ui renderer

- Runtime pin: Electron `43.3.0` (exact — electron-builder rejects ranges) with `electron-vite` `^5.0.0`. Requires macOS 12+ (Electron dropped 11 in v38). Electron 42+ downloads its binary lazily on first `electron`/`electron-vite` run (no npm `postinstall`); root `trustedDependencies` still lists `electron` for Bun lifecycle trust.

- Dev: `bun run dev`; build: `bun run build` (output in `out/`, not committed)

- Package installers: `bun run package` / `package:linux|mac` (electron-builder → `release/`). Public macOS releases are Developer ID signed and notarized; see `packages/pm-desktop/README.md` and `RELEASE.md`

- Binaries: **published** GitHub Releases on this repo (`pm-desktop-v*`) with installers + `latest-mac.yml` / `latest-linux.yml`

- Auto-update via `electron-updater` against those published Releases (packaged builds only; no-op in dev)

- Reuses the pm engine via `@getdevintern/pm/engine` and `@getdevintern/pm/config`; issue-type defaults via `@getdevintern/pm/issue-types`; in-app project setup via `@getdevintern/pm/init` (main) and `@getdevintern/pm/init-shared` (renderer-safe metadata)

- Multi-ticket workspaces: sidebar of open tickets with independent composer/output state; agent streams route by `requestId` (see `renderer/src/state/ticket-workspaces.ts`)

- Anonymous product analytics (PostHog): set `POSTHOG_API_KEY` (and optional `POSTHOG_HOST`) at **build** time via `packages/pm-desktop/.env` (see `.env.example`), shell, or CI so electron-vite can bake them into the main bundle; missing key → analytics no-ops. Users can opt out in Settings.

### Source-only shared packages

`agent-harness`, `auth`, `license-check`, `license-policy`, `text-formatter`, `utils`, `task-trackers`:

- No build step. `build` script just echoes.

- Consumed directly via `"exports": { ".": "./src/index.ts" }`.

- Other packages depend on them via `"workspace:*"`.

## TypeScript / Lint / Format

- Formatter: `oxfmt` (not Prettier)

- Linter: `oxlint` (not ESLint)

- Root `.oxlintrc.json` is the shared baseline; nested config discovery applies it to every package's `oxlint .`. Plugins: `typescript`, `unicorn`, `oxc`, `react`, `jsdoc`, `import`, `promise`. `categories.correctness` stays at `warn`; all configured `react/*` rules (including hooks) and enabled import hygiene rules (`import/no-cycle`, `no-duplicates`, `first`, etc.) are `error`. Export-layout rules (`import/group-exports`, `import/exports-last`) stay `off` — they ban the monorepo's inline `export function`/`export type` style. CommonJS is allowed only in `*.{cjs,cts}` via override. Noisy JSDoc `require-*` rules for typed codebases (`require-param-type`, `require-returns-type`, etc.) are off. Side-effect imports (CSS, `dotenv/config`) use `oxlint-disable-next-line import/no-unassigned-import` with a reason.

- Strict TypeScript with `bun-types`, `moduleResolution: bundler`, `allowImportingTsExtensions: true`

- `packages/code` has `noUncheckedIndexedAccess: false` (differs from `packages/pm` which enables it)

## Documentation

Product documentation lives in `docs/{code,pm}` and is also rendered at https://devintern.com/docs. Update the relevant Markdown guide when changing user-facing CLI behavior, flags, or environment variables.

## References

- `packages/code/CLAUDE.md`: detailed architecture for `@getdevintern/code` (workflows, config, output structure)

- `packages/pm/CLAUDE.md`: Bun CLI patterns, file I/O, shell commands