chore: add cursor roles

.cursor/rules/code-style.mdc

@@ -0,0 +1,99 @@
+---
+description: Code Style & Structure specifics
+globs: "**/*.{ts,tsx}"
+---
+## Code Style Guidelines
+
+- Write concise, functional code with proper types
+  ```ts
+  // Good
+  function mergeConfigs<T>(base: T, override: Partial<T>): T {
+    return { ...base, ...override }
+  }
+
+  // Avoid
+  class ConfigMerger {
+    merge(base: any, override: any) {
+      return Object.assign({}, base, override)
+    }
+  }
+  ```
+
+- Use Bun native modules when available
+  ```ts
+  // Good
+  import { file } from 'bun'
+  const config = await file('config.json').json()
+
+  // Avoid
+  import { readFile } from 'fs/promises'
+  const config = JSON.parse(await readFile('config.json', 'utf-8'))
+  ```
+
+- Use descriptive variable names with proper prefixes
+  ```ts
+  // Good
+  const isConfigValid = validateConfig(config)
+  const hasCustomOptions = Boolean(options.custom)
+  const shouldUseDefaults = !configExists || isConfigEmpty
+
+  // Avoid
+  const valid = check(cfg)
+  const custom = options.custom ? true : false
+  const defaults = !exists || empty
+  ```
+
+- Write proper JSDoc comments for public APIs
+  ```ts
+  /**
+   * Loads configuration from a file or remote endpoint
+   * @param options - Configuration options
+   * @param options.name - Name of the config file
+   * @param options.cwd - Working directory (default: process.cwd())
+   * @returns Resolved configuration object
+   * @throws {ConfigError} When config loading fails
+   * @example
+   * ```ts
+   * const config = await loadConfig({
+   *   name: 'myapp',
+   *   defaultConfig: { port: 3000 }
+   * })
+   * ```
+   */
+  async function loadConfig<T>(options: Config<T>): Promise<T>
+  ```
+
+- Use proper module organization
+  ```ts
+  // config.ts
+  export { loadConfig } from './loader'
+  export type { Config, ConfigOptions } from './types'
+  export { ConfigError } from './errors'
+  ```
+
+- Follow consistent error handling patterns
+  ```ts
+  // Good
+  const result = await loadConfig(options).catch(error => {
+    console.error('Config loading failed:', error)
+    return options.defaultConfig
+  })
+
+  // Avoid
+  try {
+    const result = await loadConfig(options)
+  } catch (e) {
+    console.log('Error:', e)
+  }
+  ```
+
+- Use proper type assertions
+  ```ts
+  // Good
+  const config = result as Config
+  if (!isValidConfig(config))
+    throw new Error('Invalid config')
+
+  // Avoid
+  const config = result as any
+  ```

.cursor/rules/documentation.mdc

@@ -0,0 +1,70 @@
+---
+description: Documentation specific rules
+globs: "**/*.{ts,tsx,md}"
+---
+## Documentation Guidelines
+
+## API Documentation
+- Document all public APIs thoroughly
+- Include TypeScript type information
+- Provide clear function signatures
+- Document config options and defaults
+- Include return type information
+- Document async behavior
+
+## Configuration Examples
+- Provide basic usage examples
+- Include complex configuration examples
+- Document all supported config formats
+- Show browser usage examples
+- Include TypeScript configuration examples
+- Document config merging behavior
+
+## Type Documentation
+- Document generic type parameters
+- Explain type constraints
+- Document interface properties
+- Include type union explanations
+- Document type generation features
+- Provide type utility examples
+
+## Error Documentation
+- Document common error scenarios
+- Include error handling examples
+- Document error recovery options
+- Explain validation errors
+- Document browser-specific errors
+- Include troubleshooting guides
+
+## Code Examples
+- Include runnable code examples
+- Provide TypeScript examples
+- Show error handling patterns
+- Include browser environment examples
+- Document testing approaches
+- Include CLI usage examples
+
+## Best Practices
+- Keep documentation up to date
+- Use consistent formatting
+- Include inline code comments
+- Document breaking changes
+- Maintain a changelog
+- Include version information
+
+## File Structure
+- Maintain clear docs organization
+- Use proper markdown formatting
+- Include table of contents
+- Organize by topic
+- Keep related docs together
+- Use proper headings
+
+## Documentation Standards
+- Use clear and concise language
+- Include proper code blocks
+- Document all parameters
+- Provide return value descriptions
+- Include usage notes
+- Document dependencies
+- Keep examples current

.cursor/rules/error-handling.mdc

@@ -0,0 +1,89 @@
+---
+description: Error Handling and Validation specifics
+globs: "**/*.{ts,tsx}"
+---
+## Error Handling Guidelines
+
+- Use early returns and guard clauses for validation
+  ```ts
+  function loadConfig<T>(options: Config<T>) {
+    if (!options.name)
+      throw new Error('Config name is required')
+
+    if (!isObject(options.defaultConfig))
+      throw new Error('Default config must be an object')
+
+    // Continue with valid input
+  }
+  ```
+
+- Implement proper error types
+  ```ts
+  class ConfigError extends Error {
+    constructor(
+      message: string,
+      public readonly code: string,
+      public readonly details?: unknown
+    ) {
+      super(message)
+      this.name = 'ConfigError'
+    }
+  }
+  ```
+
+- Use descriptive error messages
+  ```ts
+  throw new ConfigError(
+    `Failed to load config file: ${filePath}`,
+    'CONFIG_LOAD_ERROR',
+    { cause: error }
+  )
+  ```
+
+- Handle async errors properly
+  ```ts
+  async function loadConfigFile(path: string) {
+    try {
+      const content = await Bun.file(path).text()
+      return JSON.parse(content)
+    } catch (error) {
+      if (error instanceof SyntaxError)
+        throw new ConfigError('Invalid JSON in config file', 'PARSE_ERROR')
+      throw new ConfigError('Failed to read config file', 'READ_ERROR')
+    }
+  }
+  ```
+
+- Implement proper error logging
+  ```ts
+  function handleError(error: unknown) {
+    if (error instanceof ConfigError) {
+      console.error(`[${error.code}] ${error.message}`)
+      if (error.details)
+        console.debug('Error details:', error.details)
+    } else {
+      console.error('Unexpected error:', error)
+    }
+  }
+  ```
+
+- Use error boundaries for unexpected errors
+  ```ts
+  try {
+    await loadConfig(options)
+  } catch (error) {
+    handleError(error)
+    return options.defaultConfig ?? {}
+  }
+  ```
+
+- Ensure errors are typed when using Result types
+  ```ts
+  import { Result, ok, err } from 'neverthrow'
+
+  function validateConfig(config: unknown): Result<Config, ConfigError> {
+    if (!isValidConfig(config))
+      return err(new ConfigError('Invalid config format', 'VALIDATION_ERROR'))
+    return ok(config)
+  }
+  ```

.cursor/rules/key-conventions.mdc

@@ -0,0 +1,87 @@
+---
+description: Key code conventions
+globs: "**/*.{ts,tsx}"
+---
+## Key Conventions
+
+- Prefer browser-compatible implementations when possible
+  ```ts
+  // Good - Browser compatible
+  const config = await fetch('/api/config').then(r => r.json())
+
+  // Avoid - Node.js specific
+  const config = require('./config')
+  ```
+
+- Aim for comprehensive test coverage
+  ```ts
+  // Test both success and failure cases
+  describe('loadConfig', () => {
+    it('success case - load config', async () => {})
+    it('failure case - handle errors', async () => {})
+    it('edge case - malformed config', async () => {})
+  })
+  ```
+
+- Use proper TypeScript types instead of `any`
+  ```ts
+  // Good
+  function loadConfig<T extends Record<string, unknown>>(options: Config<T>): Promise<T>
+
+  // Avoid
+  function loadConfig(options: any): Promise<any>
+  ```
+
+- Use consistent error handling and logging
+  ```ts
+  // Good
+  console.error('Failed to load config:', error)
+  return options.defaultConfig
+
+  // Avoid
+  console.log('Error:', e)
+  throw e
+  ```
+
+- Follow file naming conventions
+  ```
+  config.ts           // Core functionality
+  config.test.ts      // Test files
+  config.types.ts     // Type definitions
+  .{name}.config.ts   // Config files
+  ```
+
+- Use proper exports and imports
+  ```ts
+  // Good
+  export { loadConfig } from './loader'
+  export type { Config } from './types'
+
+  // Avoid
+  export default {
+    loadConfig,
+    Config,
+  }
+  ```
+
+- Maintain consistent directory structure
+  ```
+  src/           // Source code
+  ├─ index.ts    // Main exports
+  ├─ types.ts    // Type definitions
+  ├─ config.ts   // Configuration
+  ├─ merge.ts    // Deep merge
+  └─ utils/      // Utilities
+  ```
+
+- Follow ESLint rules and maintain consistent style
+  ```ts
+  // Good - Follow ESLint config
+  const config = {
+    name: 'app',
+    port: 3000,
+  }
+
+  // Avoid - Inconsistent style
+  const config={name:'app',port:3000}
+  ```