diff --git a/.cursor/rules/project-wide.mdc b/.cursor/rules/project-wide.mdc new file mode 100644 index 00000000..cb4e2f25 --- /dev/null +++ b/.cursor/rules/project-wide.mdc @@ -0,0 +1,63 @@ +--- +description: Project-Wide Rules for the Hypergraph monorepo and its packages +globs: +alwaysApply: true +--- + +# Hypergraph Project-Wide Rules + +## Monorepo Structure +- Use pnpm workspaces for package management +- Follow consistent package naming conventions +- Use workspace dependencies where appropriate +- Maintain proper package.json structure +- Use consistent versioning across packages + +## TypeScript Configuration +- Use strict TypeScript configuration +- Implement proper type definitions +- Use consistent import/export patterns +- Follow TypeScript best practices +- Use proper module resolution + +## Code Style +- Use Biome for linting and formatting +- Follow consistent naming conventions +- Use proper indentation and spacing +- Implement proper code organization +- Follow established file structure patterns + +## Testing +- Use Vitest for testing framework +- Write comprehensive unit tests +- Test both success and error scenarios +- Use proper mocking strategies +- Maintain good test coverage + +## Documentation +- Write clear, comprehensive documentation +- Use proper JSDoc comments +- Maintain up-to-date README files +- Document API interfaces +- Use consistent documentation patterns + +## Git Workflow +- Use conventional commit messages +- Implement proper branching strategy +- Use meaningful commit descriptions +- Follow established PR review process +- Maintain clean git history + +## Security +- Use secure dependencies +- Implement proper authentication +- Follow security best practices +- Use proper encryption where needed +- Maintain secure coding practices + +## Performance +- Optimize bundle sizes +- Implement proper caching strategies +- Use efficient algorithms +- Monitor performance metrics +- Follow performance best practices \ No newline at end of file diff --git a/.cursor/rules/root-config.mdc b/.cursor/rules/root-config.mdc new file mode 100644 index 00000000..ec6824b4 --- /dev/null +++ b/.cursor/rules/root-config.mdc @@ -0,0 +1,50 @@ +--- +description: Root Configuration Rules for the Hypergraph monorepo and its packages +globs: +alwaysApply: true +--- + +# Root Configuration Rules + +## Package Management +- Use pnpm for package management +- Maintain consistent workspace configuration +- Use proper dependency management +- Follow semantic versioning +- Use proper package.json structure + +## Build Configuration +- Use TypeScript for configuration +- Implement proper build scripts +- Use consistent build tooling +- Maintain proper output structure +- Use proper source maps + +## Linting and Formatting +- Use Biome for linting and formatting +- Maintain consistent code style +- Use proper ignore patterns +- Implement proper rule configuration +- Follow established conventions + +## Documentation +- Maintain comprehensive README +- Use proper documentation structure +- Include setup instructions +- Document development workflow +- Use consistent documentation style + +## CI/CD +- Use proper GitHub Actions +- Implement proper testing workflows +- Use proper deployment strategies +- Maintain proper environment configuration +- Follow security best practices + +## Development Tools +- Use proper development dependencies +- Implement proper tooling configuration +- Use consistent development workflow +- Maintain proper debugging setup +- Use proper IDE configuration + diff --git a/apps/connect/.cursor/rules/frontend-app.mdc b/apps/connect/.cursor/rules/frontend-app.mdc new file mode 100644 index 00000000..176210d7 --- /dev/null +++ b/apps/connect/.cursor/rules/frontend-app.mdc @@ -0,0 +1,56 @@ +--- +description: Connect frontend application patterns and conventions +globs: ["src/**/*.tsx", "src/**/*.ts"] +alwaysApply: false +--- + +# Connect Frontend App Rules + +## Technology Stack +- Use Vite for build tooling +- Use TanStack Router for routing +- Use TanStack Query for server state +- Use Tailwind CSS for styling +- Use React 19 with latest features + +## Component Architecture +- Use functional components with hooks +- Implement proper TypeScript interfaces +- Use the Hypergraph React SDK components +- Follow the established routing patterns + +## State Management +- Use XState Store for complex state +- Use React Query for server state +- Use Hypergraph contexts for app state +- Implement proper loading states + +## Authentication +- Use Privy for authentication +- Implement proper SIWE integration +- Handle authentication state properly +- Use secure authentication patterns + +## Routing +- Use TanStack Router for type-safe routing +- Implement proper route guards +- Use nested routing where appropriate +- Handle route parameters safely + +## Styling +- Use Tailwind CSS for styling +- Follow responsive design patterns +- Use consistent design tokens +- Implement proper accessibility + +## Performance +- Use React.memo for expensive components +- Implement proper code splitting +- Use lazy loading for routes +- Optimize bundle size + +## Testing +- Use React Testing Library +- Test user interactions +- Mock external dependencies +- Test authentication flows diff --git a/apps/create-hypergraph-app/.cursor/rules/cli-app.mdc b/apps/create-hypergraph-app/.cursor/rules/cli-app.mdc new file mode 100644 index 00000000..e0e16b60 --- /dev/null +++ b/apps/create-hypergraph-app/.cursor/rules/cli-app.mdc @@ -0,0 +1,55 @@ +--- +description: Create Hypergraph App CLI patterns and conventions +globs: ["src/**/*.ts"] +alwaysApply: false +--- + +# Create Hypergraph App CLI Rules + +## CLI Architecture +- Use Effect CLI for command-line interface +- Implement proper subcommands +- Use descriptive command names +- Provide helpful error messages +- Implement proper help text + +## Template System +- Use structured templates for scaffolding +- Implement proper template validation +- Use consistent template structure +- Provide clear template documentation +- Support multiple template types + +## File Operations +- Use safe file system operations +- Implement proper error handling +- Validate file paths and permissions +- Use consistent file naming +- Implement proper backup strategies + +## User Experience +- Provide clear progress indicators +- Implement proper error recovery +- Use consistent output formatting +- Provide helpful suggestions +- Implement proper validation + +## Code Generation +- Generate type-safe code +- Use consistent code formatting +- Implement proper imports +- Follow established patterns +- Generate comprehensive documentation + +## Testing +- Test CLI commands thoroughly +- Mock file system operations +- Test error scenarios +- Test template generation +- Use Vitest for testing + +## Distribution +- Use proper package.json configuration +- Implement proper binary setup +- Use TypeScript for type safety +- Follow npm publishing best practices diff --git a/apps/create-hypergraph/.cursor/rules/cli-tool.mdc b/apps/create-hypergraph/.cursor/rules/cli-tool.mdc new file mode 100644 index 00000000..a3a3bdd3 --- /dev/null +++ b/apps/create-hypergraph/.cursor/rules/cli-tool.mdc @@ -0,0 +1,55 @@ +--- +description: Create Hypergraph CLI tool patterns and conventions +globs: ["src/**/*.ts"] +alwaysApply: false +--- + +# Create Hypergraph CLI Rules + +## CLI Architecture +- Use Effect CLI for command-line interface +- Implement proper subcommands +- Use descriptive command names +- Provide helpful error messages +- Implement proper help text + +## Template System +- Use structured templates for scaffolding +- Implement proper template validation +- Use consistent template structure +- Provide clear template documentation +- Support multiple template types + +## File Operations +- Use safe file system operations +- Implement proper error handling +- Validate file paths and permissions +- Use consistent file naming +- Implement proper backup strategies + +## User Experience +- Provide clear progress indicators +- Implement proper error recovery +- Use consistent output formatting +- Provide helpful suggestions +- Implement proper validation + +## Code Generation +- Generate type-safe code +- Use consistent code formatting +- Implement proper imports +- Follow established patterns +- Generate comprehensive documentation + +## Testing +- Test CLI commands thoroughly +- Mock file system operations +- Test error scenarios +- Test template generation +- Use Vitest for testing + +## Distribution +- Use proper package.json configuration +- Implement proper binary setup +- Use TypeScript for type safety +- Follow npm publishing best practices diff --git a/apps/events/.cursor/rules/events-app.mdc b/apps/events/.cursor/rules/events-app.mdc new file mode 100644 index 00000000..e88d2049 --- /dev/null +++ b/apps/events/.cursor/rules/events-app.mdc @@ -0,0 +1,56 @@ +--- +description: Events application patterns and conventions +globs: ["src/**/*.tsx", "src/**/*.ts"] +alwaysApply: false +--- + +# Events App Rules + +## Technology Stack +- Use Vite for build tooling +- Use TanStack Router for routing +- Use React for UI components +- Use Tailwind CSS for styling +- Use Hypergraph SDK for data management + +## Event Management +- Implement proper event creation +- Use type-safe event schemas +- Implement proper event validation +- Handle event state management +- Use proper event lifecycle + +## User Management +- Implement proper user authentication +- Handle user permissions +- Manage user profiles +- Implement proper user state +- Use secure authentication patterns + +## Data Management +- Use Hypergraph for data storage +- Implement proper data synchronization +- Handle offline scenarios +- Use proper data validation +- Implement proper error handling + +## UI/UX +- Use consistent design patterns +- Implement responsive design +- Follow accessibility guidelines +- Use proper loading states +- Implement proper error states + +## Performance +- Optimize component rendering +- Implement proper caching +- Use lazy loading +- Optimize bundle size +- Monitor performance metrics + +## Testing +- Test user interactions +- Test event workflows +- Mock external dependencies +- Test error scenarios +- Use React Testing Library diff --git a/apps/next-example/.cursor/rules/nextjs-example.mdc b/apps/next-example/.cursor/rules/nextjs-example.mdc new file mode 100644 index 00000000..e9171c7c --- /dev/null +++ b/apps/next-example/.cursor/rules/nextjs-example.mdc @@ -0,0 +1,56 @@ +--- +description: Next.js example application patterns and conventions +globs: ["src/**/*.tsx", "src/**/*.ts"] +alwaysApply: false +--- + +# Next.js Example App Rules + +## Technology Stack +- Use Next.js 15+ for framework +- Use App Router for routing +- Use TypeScript for type safety +- Use Tailwind CSS for styling +- Use Hypergraph SDK for data + +## Next.js Patterns +- Use App Router structure +- Implement proper page components +- Use Server Components where appropriate +- Use Client Components for interactivity +- Follow Next.js best practices + +## Routing +- Use App Router file-based routing +- Implement proper dynamic routes +- Use proper route handlers +- Handle route parameters safely +- Implement proper redirects + +## Data Fetching +- Use Server Components for data fetching +- Implement proper loading states +- Handle error boundaries +- Use proper caching strategies +- Implement proper revalidation + +## Styling +- Use Tailwind CSS for styling +- Follow responsive design patterns +- Use consistent design tokens +- Implement proper accessibility +- Use CSS modules when needed + +## Performance +- Use Next.js optimizations +- Implement proper image optimization +- Use proper code splitting +- Optimize bundle size +- Monitor Core Web Vitals + +## Testing +- Use Next.js testing utilities +- Test page components +- Test API routes +- Mock external dependencies +- Test user interactions diff --git a/apps/server/.cursor/rules/backend-api.mdc b/apps/server/.cursor/rules/backend-api.mdc new file mode 100644 index 00000000..d40e3b17 --- /dev/null +++ b/apps/server/.cursor/rules/backend-api.mdc @@ -0,0 +1,59 @@ +--- +description: Server backend API patterns and conventions +globs: ["src/**/*.ts"] +alwaysApply: false +--- + +# Server Backend API Rules + +## Technology Stack +- Use Express.js for HTTP server +- Use Prisma for database operations +- Use Bun for runtime +- Use WebSocket for real-time communication +- Use Effect for functional programming + +## API Design +- Use RESTful API patterns +- Implement proper HTTP status codes +- Use consistent error response format +- Implement proper request validation +- Use middleware for cross-cutting concerns + +## Database +- Use Prisma for type-safe database access +- Implement proper migrations +- Use transactions for data consistency +- Implement proper indexing strategies +- Follow database naming conventions + +## Authentication +- Use Privy for authentication +- Implement proper SIWE validation +- Use secure session management +- Implement proper authorization checks + +## Security +- Use HPKE for encryption +- Implement proper CORS policies +- Use secure headers +- Validate all inputs +- Implement rate limiting + +## Error Handling +- Use Effect for error handling +- Implement proper error logging +- Return consistent error responses +- Handle edge cases gracefully + +## Performance +- Implement proper caching strategies +- Use connection pooling +- Optimize database queries +- Implement proper monitoring + +## Testing +- Test API endpoints thoroughly +- Mock external dependencies +- Test authentication flows +- Test error scenarios diff --git a/apps/typesync/.cursor/rules/typesync-app.mdc b/apps/typesync/.cursor/rules/typesync-app.mdc new file mode 100644 index 00000000..c96892cf --- /dev/null +++ b/apps/typesync/.cursor/rules/typesync-app.mdc @@ -0,0 +1,56 @@ +--- +description: TypeSync application patterns and conventions +globs: ["src/**/*.tsx", "src/**/*.ts"] +alwaysApply: false +--- + +# TypeSync App Rules + +## Technology Stack +- Use Vite for build tooling +- Use React for UI components +- Use Tailwind CSS for styling +- Use GraphQL for data fetching +- Use TypeScript for type safety + +## GraphQL Integration +- Use proper GraphQL queries +- Implement proper error handling +- Use GraphQL code generation +- Handle loading states properly +- Implement proper caching + +## Type Generation +- Generate type-safe code +- Use proper TypeScript interfaces +- Implement proper validation +- Handle complex type relationships +- Use consistent naming conventions + +## UI Components +- Use functional React components +- Implement proper TypeScript props +- Use consistent styling patterns +- Follow accessibility guidelines +- Implement responsive design + +## Data Management +- Handle GraphQL data properly +- Implement proper error states +- Use proper loading indicators +- Handle data synchronization +- Implement proper caching + +## Performance +- Optimize GraphQL queries +- Implement proper code splitting +- Use lazy loading +- Optimize bundle size +- Monitor performance + +## Testing +- Test GraphQL operations +- Test type generation +- Mock external dependencies +- Test error scenarios +- Use proper testing utilities diff --git a/docs/.cursor/rules/docusaurus-docs.mdc b/docs/.cursor/rules/docusaurus-docs.mdc new file mode 100644 index 00000000..9e7a656a --- /dev/null +++ b/docs/.cursor/rules/docusaurus-docs.mdc @@ -0,0 +1,56 @@ +--- +description: Docusaurus documentation patterns and conventions +globs: ["src/**/*.js", "src/**/*.jsx", "src/**/*.ts", "src/**/*.tsx", "docs/**/*.md", "docs/**/*.mdx"] +alwaysApply: false +--- + +# Docusaurus Documentation Rules + +## Documentation Structure +- Use clear, hierarchical organization +- Follow Docusaurus documentation patterns +- Use proper frontmatter for metadata +- Implement proper navigation structure +- Use consistent file naming + +## Content Guidelines +- Write clear, concise documentation +- Use proper markdown formatting +- Include code examples where appropriate +- Use proper syntax highlighting +- Implement proper linking between pages + +## Component Development +- Use React components for interactive elements +- Follow Docusaurus component patterns +- Implement proper TypeScript interfaces +- Use consistent styling patterns +- Follow accessibility guidelines + +## Styling +- Use Docusaurus theme system +- Implement custom CSS when needed +- Follow responsive design patterns +- Use consistent design tokens +- Implement proper dark mode support + +## Performance +- Optimize images and assets +- Use proper lazy loading +- Implement proper caching +- Optimize bundle size +- Monitor Core Web Vitals + +## SEO and Metadata +- Use proper meta tags +- Implement proper Open Graph tags +- Use structured data where appropriate +- Optimize for search engines +- Use proper canonical URLs + +## Testing +- Test documentation links +- Test interactive components +- Test responsive design +- Test accessibility +- Use proper testing utilities diff --git a/packages/hypergraph-react/.cursor/rules/react-patterns.mdc b/packages/hypergraph-react/.cursor/rules/react-patterns.mdc new file mode 100644 index 00000000..4477a0e4 --- /dev/null +++ b/packages/hypergraph-react/.cursor/rules/react-patterns.mdc @@ -0,0 +1,57 @@ +--- +description: React patterns and conventions for Hypergraph React components +globs: ["src/**/*.tsx", "src/**/*.ts", "test/**/*.tsx", "test/**/*.ts"] +alwaysApply: false +--- + +# Hypergraph React Rules + +## Component Architecture +- Use functional components with hooks +- Prefer composition over inheritance +- Implement proper TypeScript interfaces for props +- Use React Query for server state management +- Follow the established context pattern for HypergraphAppContext + +## State Management +- Use XState Store for complex state machines +- Implement proper loading and error states +- Use React Query for caching and synchronization +- Prefer local state for UI-only concerns + +## Hooks Patterns +- Create custom hooks for reusable logic +- Use the `use` prefix for custom hooks +- Implement proper dependency arrays +- Handle cleanup in useEffect hooks + +## Context Usage +- Use HypergraphAppContext for global app state +- Use HypergraphSpaceContext for space-specific state +- Implement proper context providers +- Avoid prop drilling with context + +## TypeScript Integration +- Use proper type definitions for all props +- Implement generic components where appropriate +- Use branded types from the core SDK +- Ensure type safety across component boundaries + +## Testing +- Use React Testing Library for component tests +- Tests are located in the `./test` directory +- Test user interactions, not implementation details +- Mock Hypergraph contexts appropriately +- Test both success and error scenarios + +## Performance +- Use React.memo for expensive components +- Implement proper key props for lists +- Use useMemo and useCallback appropriately +- Avoid unnecessary re-renders + +## Styling +- Use Tailwind CSS for styling +- Implement responsive design patterns +- Follow accessibility guidelines +- Use consistent spacing and typography diff --git a/packages/hypergraph/.cursor/rules/core-sdk.mdc b/packages/hypergraph/.cursor/rules/core-sdk.mdc new file mode 100644 index 00000000..33bbb713 --- /dev/null +++ b/packages/hypergraph/.cursor/rules/core-sdk.mdc @@ -0,0 +1,42 @@ +--- +description: Core Hypergraph SDK patterns and conventions +globs: ["src/**/*.ts", "test/**/*.ts"] +alwaysApply: false +--- + +# Core Hypergraph SDK Rules + +## Architecture Patterns +- Use Effect for functional programming patterns and error handling +- Follow local-first architecture principles with Automerge for CRDT +- Implement type-safe patterns with TypeScript strict mode +- Use snake_case for service names and API endpoints +- Prefer immutable data structures and pure functions + +## Module Structure +- Each module should export a clear public API +- Use barrel exports (index.ts) for clean imports +- Separate concerns: entity, identity, messages, space-events, etc. + +## Type Safety +- Use strict TypeScript configuration +- Prefer branded types for domain-specific identifiers +- Use discriminated unions for state management +- Implement proper error types with Effect + +## CRDT and Sync +- Use Automerge for conflict resolution +- Implement proper merge strategies for concurrent edits +- Handle offline-first scenarios gracefully + +## Crypto and Security +- Use Noble libraries for cryptographic operations +- Implement proper key management patterns +- Use secure random number generation + +## Testing +- Write comprehensive unit tests with Vitest +- Tests are located in the `./test` directory +- Test both success and error scenarios +- Mock external dependencies appropriately +- Use Effect testing utilities for functional code