Skip to content

AGENTS.md

Latest commit

 

History

History
44 lines (32 loc) · 3.41 KB

AGENTS.md

File metadata and controls

44 lines (32 loc) · 3.41 KB
Raw

Tooee

Terminal micro-apps built on OpenTUI, published under the @tooee npm org.

Commands

bun install          # Install dependencies
bun run check        # Type check packages and every examples/* package (TypeScript 7, local tsc)
bun test             # Run tests
bun run lint         # Lint with oxlint

Lefthook (lefthook.yml) runs lint:staged and check before each commit. After a checkout, merge, or rebase changes bun.lock or a package.json, it runs bun install in worktrees that already have node_modules. A new worktree needs one bun install first.

Releases

User-facing changes should include a Tegami release note. See docs/releasing.md for the format and release flow; do not edit package versions or tags manually.

Tech Stack

  • Runtime: Bun
  • UI: OpenTUI (@opentui/core, @opentui/react) — Zig native TUI renderer with React reconciler
  • Language: TypeScript 7 native compiler (strict, noEmit, allowImportingTsExtensions). Editors need TypeScript 7 language support; the package ships no tsserver.
  • JSX: react-jsx with jsxImportSource: @opentui/react

Key Conventions

  • Each app package (view, ask, choose) exports a React component, a launch() function, and TypeScript interfaces
  • Actions use ActionDefinition[] from @tooee/commands — no per-app action types
  • useCommand() registers commands; useModalNavigationCommands() provides vim-style navigation
  • Config: three-tier resolution (global ~/.config/tooee/, project .tooee/, overrides)
  • Themes: OpenCode-compatible JSON with ui, syntax, diff, markdown color groups
  • @tooee/shell is the composition layer — TooeeProvider wraps all providers, launchCli() creates renderers
  • Hotkey format: ctrl+x, sequences g g, leader keys <leader>n
  • Raw useKeyboard policy: app-level useKeyboard handlers MUST guard with useHasOverlay() (from @tooee/overlays) or be ported to useCommand. Raw handlers subscribe before the command dispatcher (child effects run first), so modal command surfaces cannot suspend them and key.preventDefault() does not protect them — an unguarded handler double-handles keys while an overlay is open. See the @tooee/commands README.
  • Diff rendering: @tooee/diff is the only package allowed to import hunkdiff (pinned exactly, pre-1.0). It owns the diff content format, the DiffView row document, and the ```diff/```patch Markdown fence renderer — see its README for the row model and known limits.
  • Mermaid rendering: @tooee/renderers registers the beautiful-mermaid ASCII renderer for ```mermaid fences by default. @tooee/mermaid-pele is an opt-in image renderer (Pele SVG rasterized with resvg) that apps register through codeBlockRenderers. No other package may depend on pele or @resvg/resvg-js, and @tooee/view must not register the Pele renderer by default.
  • Store conventions: stateful interaction systems use @xstate/store event stores with thin React adapters — see docs/store-conventions.md for when to use a store vs useState vs an effect, file layout, testing, and selector discipline.

Documentation