diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md index 0a7bb42..22644c8 100644 --- a/.claude/CLAUDE.md +++ b/.claude/CLAUDE.md @@ -1,3 +1,120 @@ +Default to using Bun instead of Node.js. + +- Use `bun ` instead of `node ` or `ts-node ` +- Use `bun test` instead of `jest` or `vitest` +- Use `bun build ` instead of `webpack` or `esbuild` +- Use `bun install` instead of `npm install` or `yarn install` or `pnpm install` +- Use `bun run + + +``` + +With the following `frontend.tsx`: + +```tsx#frontend.tsx +import React from "react"; +import { createRoot } from "react-dom/client"; + +// import .css files directly and it works +import './index.css'; + +const root = createRoot(document.body); + +export default function Frontend() { + return

Hello, world!

; +} + +root.render(); +``` + +Then, run index.ts + +```sh +bun --hot ./index.ts +``` + +For more information, read the Bun API docs in `node_modules/bun-types/docs/**.mdx`. + + +## CLI Icons + +All CLI output icons are centralized in `src/ui.ts` via the `icons` object. When adding or modifying CLI output: + +- Import icons from `src/ui.ts` — never hardcode symbols or emoji inline +- Use clean geometric Unicode glyphs (▸ ◆ ● ◎ etc.) — no emoji (🔑 📁 🔒 etc.) +- Emoji render inconsistently across terminals and break monospace alignment +- Each icon must be wrapped with its semantic color function (e.g. `green("✔")`, `red("✖")`) +- When adding a new icon, add it to the `icons` object in `src/ui.ts` with a comment noting the Unicode codepoint + # Ultracite Code Standards This project uses **Ultracite**, a zero-config preset that enforces strict code quality standards through automated formatting and linting. @@ -121,3 +238,19 @@ Biome's linter will catch most issues automatically. Focus your attention on: --- Most formatting and common issues are automatically fixed by Biome. Run `bun x ultracite fix` before committing to ensure compliance. + +## CLI Icons + +All CLI output icons are centralized in `src/ui.ts` via the `icons` object. When adding or modifying CLI output: + +- Import icons from `src/ui.ts` — never hardcode symbols or emoji inline +- Use clean geometric Unicode glyphs (▸ ◆ ● ◎ etc.) — no emoji (🔑 📁 🔒 etc.) +- Emoji render inconsistently across terminals and break monospace alignment +- Each icon must be wrapped with its semantic color function (e.g. `green("✔")`, `red("✖")`) +- When adding a new icon, add it to the `icons` object in `src/ui.ts` with a comment noting the Unicode codepoint + + +## Effect libraries + +check this out for more info: +`https://effect.website/llms-full.txt` diff --git a/.gitignore b/.gitignore index b77a4c3..21bc42e 100644 --- a/.gitignore +++ b/.gitignore @@ -145,8 +145,7 @@ vite.config.ts.timestamp-* # Claude *.local.json -.claude -skills-lock.json +.claude/settings.*.json .kiro .agents .vercel diff --git a/CLAUDE.md b/CLAUDE.md index 09f322c..7f3f0e1 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -116,6 +116,141 @@ All CLI output icons are centralized in `src/ui.ts` via the `icons` object. When - Each icon must be wrapped with its semantic color function (e.g. `green("✔")`, `red("✖")`) - When adding a new icon, add it to the `icons` object in `src/ui.ts` with a comment noting the Unicode codepoint +# Ultracite Code Standards + +This project uses **Ultracite**, a zero-config preset that enforces strict code quality standards through automated formatting and linting. + +## Quick Reference + +- **Format code**: `bun x ultracite fix` +- **Check for issues**: `bun x ultracite check` +- **Diagnose setup**: `bun x ultracite doctor` + +Biome (the underlying engine) provides robust linting and formatting. Most issues are automatically fixable. + +--- + +## Core Principles + +Write code that is **accessible, performant, type-safe, and maintainable**. Focus on clarity and explicit intent over brevity. + +### Type Safety & Explicitness + +- Use explicit types for function parameters and return values when they enhance clarity +- Prefer `unknown` over `any` when the type is genuinely unknown +- Use const assertions (`as const`) for immutable values and literal types +- Leverage TypeScript's type narrowing instead of type assertions +- Use meaningful variable names instead of magic numbers - extract constants with descriptive names + +### Modern JavaScript/TypeScript + +- Use arrow functions for callbacks and short functions +- Prefer `for...of` loops over `.forEach()` and indexed `for` loops +- Use optional chaining (`?.`) and nullish coalescing (`??`) for safer property access +- Prefer template literals over string concatenation +- Use destructuring for object and array assignments +- Use `const` by default, `let` only when reassignment is needed, never `var` + +### Async & Promises + +- Always `await` promises in async functions - don't forget to use the return value +- Use `async/await` syntax instead of promise chains for better readability +- Handle errors appropriately in async code with try-catch blocks +- Don't use async functions as Promise executors + +### React & JSX + +- Use function components over class components +- Call hooks at the top level only, never conditionally +- Specify all dependencies in hook dependency arrays correctly +- Use the `key` prop for elements in iterables (prefer unique IDs over array indices) +- Nest children between opening and closing tags instead of passing as props +- Don't define components inside other components +- Use semantic HTML and ARIA attributes for accessibility: + - Provide meaningful alt text for images + - Use proper heading hierarchy + - Add labels for form inputs + - Include keyboard event handlers alongside mouse events + - Use semantic elements (`