termcast AGENTS.md

Project Coding Guidelines

NOTICE: AGENTS.md is generated using pnpm agents.md and should NEVER be manually updated. only update PREFIX.md

ALWAYS use pnpm to install dependencies

---

termcast specific rules

Porting @raycast/api components and hooks to termcast

ALWAYS use termcast to import things, instead of relative imports. This is possible thanks to exports in package.json. for example:

import {List} from 'termcast'

ALWAYS use .tsx extension for every new file.

NEVER use mocks in vitest tests

When running the e2e vitest suite, ALWAYS use the repo scripts (pnpm e2e, pnpm e2e <file>, pnpm e2e -u). NEVER run vitest directly.

prefer object args instead of positional args. as a way to implement named arguments, put the typescript definition inline

see files in the repo

use git ls-files | tree --fromfile to see files in the repo. this command will ignore files ignored by git

Goal

This project ports @raycast/api components and apis to use @opentui/react and other Bun APIs

We are basically implementing the package @raycast/api from scratch. DO NOT implement functions exported by @raycast/utils

This should be done one piece at a time, one hook and component at a time

Porting a new Raycast component or feature

Here is the process to follow to implement each API:

• decide which component or hook or function we are porting
• read the .d.ts of the @raycast/api package for the component or hook
• generate a new file or decide to which file to add this new API in src folder
• start by adding a signature without any actual implementation. Only a function or class or constant without any actual implementation
• try typechecking with pnpm run tsc. fix any errors that is not related to the missing implementation (like missing returns)
• then think, is the signature the same as Raycast?
• start implementing the component or function, before doing this
  • decide on what @opentui/react components to use
  • do so by reading opentui .d.ts files and see available components
  • read .d.ts to understand available styling options and attributes
• typecheck
• if the added feature is a component or adds support for a new prop for a component, add an example usage component in the src/examples directory. create a descriptive name for it in the file. use simple-{component-name} for basic implementations examples
• if the implemented feature is function or other API, add an action in the file examples/miscellaneus.tsx, add a list item for the new feature, for example "show a error toast" if we are implementing toasts
• do not add an example if our feature is already covered by other example files
• DO NOT run the examples then. instead ask me to do it. do not add these as scripts in package.json
• typecheck to make sure the example is correct