AGENTS.md

What this project is

termDRAW is a Bun-based TypeScript workspace for terminal-native diagramming.

• packages/opentui contains the published @termdraw/opentui embeddable OpenTUI library.
• packages/app contains the published @termdraw/app standalone CLI.
• packages/pi contains the published @termdraw/pi Pi integration package that mounts termDRAW through opentui-island.
• The repo root provides shared workspace scripts for formatting, linting, testing, typechecking, build checks, packaging checks, and Pi smoke coverage.

Important file entry points

• package.json — workspace scripts and maintenance commands
• tsconfig.json — shared TypeScript defaults for the workspace
• packages/opentui/src/draw-state.ts — retained object model, selection, transforms, undo/redo, export
• packages/opentui/src/app.ts — renderable chrome/editor surface and input handling
• packages/opentui/src/react.ts — OpenTUI React component bindings
• packages/app/src/main.tsx — standalone CLI runtime entrypoint
• packages/app/src/cli.tsx — Bun executable wrapper for the standalone app
• packages/pi/extensions/overlay.ts — Pi /termdraw command and editor insertion flow
• packages/pi/islands/termdraw.island.tsx — Pi island bridge component
• .github/workflows/* — CI and publishing automation

Architecture / mental model

• DrawState owns the drawing document, tool state, selection state, history, and exported output.
• TermDrawRenderable renders either the full app chrome or the bare editor surface on top of the shared state model.
• react.ts exposes TermDrawApp, TermDrawEditor, and TermDraw as OpenTUI React components.
• cli.tsx wraps the full app for local CLI usage.
• The Pi package adapts the same core UI through an island bridge and returns saved art back into the Pi editor.

Working rules

• Default to using Bun instead of Node.js.
• Use bun <file> instead of node <file> or ts-node <file>.
• Use bun test instead of Jest or Vitest commands.
• Use bun build <file.html|file.ts|file.css> instead of bundlers like webpack or esbuild.
• Use bun install instead of npm, yarn, or pnpm.
• Use bun run <script> instead of npm/yarn/pnpm script runners.
• Use bunx <package> <command> instead of npx <package> <command>.
• Bun already loads .env; do not add dotenv.
• Prefer Bun-native APIs when adding platform code:
  • Bun.serve() instead of Express
  • bun:sqlite instead of better-sqlite3
  • Bun.redis instead of ioredis
  • Bun.sql instead of pg or postgres.js
  • built-in WebSocket instead of ws
  • Bun.file instead of fs.readFile/writeFile when practical
• Keep the workspace split intact: reusable editor behavior belongs in packages/opentui, the standalone CLI belongs in packages/app, and Pi-specific integration logic belongs in packages/pi.
• Prefer targeted changes over broad rewrites.
• When changing editor behavior, add or update tests in packages/opentui.
• Run the Pi smoke flow when modifying Pi embed behavior, save messaging, or bridge wiring.

Validation commands

Run the smallest relevant set first, then the broader workspace checks before finishing larger changes.

• bun run format:check
• bun run lint
• bun test
• bun run typecheck
• bun run build
• bun run check
• bun run smoke:pi for Pi integration changes

Release / changelog rules

• Maintain the top-level CHANGELOG.md as the source of truth for user-visible changes.
• Keep upcoming work under ## [Unreleased] with these subsections:
  • ### Added
  • ### Changed
  • ### Fixed
• Append to existing subsections instead of creating duplicates.
• When cutting a release, move the relevant unreleased entries into a new immutable version section and then start a fresh ## [Unreleased] block.
• Use the released changelog section as the starting point for GitHub release notes.
• Prefer gh release create/edit --notes-file for multi-line release notes.
• Do not trust autogenerated GitHub release notes blindly; review and edit them.
• Prefer concise user-visible changelog entries over internal refactor details unless behavior changed.
• Keep all publishable packages on the exact same version at release time.
• When bumping versions, update every publishable package together and also update internal workspace dependency pins to the same version.
• For this repo, release @termdraw/opentui, @termdraw/app, and @termdraw/pi as a coordinated set unless there is an explicit reason not to.
• Use repo-level coordinated releases: create one root Git tag and one GitHub release per shared version, in the form vX.Y.Z.
• Publish all three packages for every coordinated release, even if one package had no code changes in that cut.
• Do not use package-specific release tags like app-vX.Y.Z, opentui-vX.Y.Z, or pi-vX.Y.Z for official releases.
• Before publishing, verify package versions are identical across all publishable packages.

Commit conventions

• Use Conventional Commit titles when practical: <type>[scope]: <description>.
• Keep commits focused and easy to review.
• Mention the validation commands you ran in PR descriptions or handoff notes.