Migrate Rules from Files to Supabase Database

.claude/commands/generate-types-from-supabase.md

@@ -0,0 +1,33 @@
+You are a skilled TypeScript developer tasked with creating a library of DTO (Data Transfer Object) types and a Command Model for the application. Your task is to analyse the database model definition, and then create appropriate DTO types that accurately represent the data structures required by the API, while maintaining the connection to the underlying database models.
+
+First, carefully review the following input data:
+
+<database_models>
+@database.types.ts
+</database_models>
+
+Your task is to create TypeScript type definitions for the DTO and Command Models, ensuring that they are derived from the database models. Follow these steps:
+
+1. Analyse the database models.
+2. Create DTO and Command Model types, using the database entity definitions.
+3. Ensure consistency between DTO and Command Models.
+4. Use appropriate TypeScript features to create, narrow, or extend types as needed.
+5. Perform a final check to ensure that all DTOs are included and correctly linked to entity definitions.
+
+Before creating the final output, work inside the <dto_analysis> tags in your thinking block to show your thought process and ensure that all requirements are met. In your analysis:
+- List all DTOs and Command Models, numbering each one.
+- For each DTO and Command Model:
+- Identify the relevant database entities and any necessary type transformations.
+  - Describe the TypeScript functions or tools you plan to use.
+  - Create a brief outline of the DTO and Command Model structure.
+- Explain how you will ensure that each DTO and Command Model is directly or indirectly linked to the entity type definitions.
+
+After completing your analysis, provide the final definitions for the DTO and Command Model types that will appear in the src/types.ts file. Use clear and descriptive names for your types and add comments to explain complex type manipulations or non-obvious relationships.
+
+Remember:
+- Make sure that all DTOs and Command Models are included.
+- Each DTO and Command Model should directly refer to one or more database entities.
+- Use TypeScript features such as Pick, Omit, Partial, etc. as needed.
+- Add comments to explain complex or non-obvious type manipulations.
+
+The final result should consist solely of the DTO and Command Model type definitions that you will save in the src/types - create new files and/or update existing files, without duplicating or re-doing any work done in the thinking block.

CLAUDE.md

@@ -20,25 +20,27 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ### Testing
 - `npm run test` - Run unit tests with Vitest
-- `npm run test:watch` - Run tests in watch mode
+- `npm run test:watch` - Run tests in watch mode  
 - `npm run test:ui` - Run tests with UI interface
 - `npm run test:coverage` - Generate test coverage report
 - `npm run test:e2e` - Run end-to-end tests with Playwright
 - `npm run test:e2e:ui` - Run E2E tests with UI
 - `npm run test:e2e:codegen` - Generate test code with Playwright
 
 ### Special Scripts
-- `npm run generate-rules` - Generate rules JSON from TypeScript definitions
+- `npm run generate-rules` - Generate rules JSON from TypeScript definitions (required before running MCP server locally)
 
 ## Architecture Overview
 
 ### Technology Stack
 - **Framework**: Astro 5 with React 18.3 integration
-- **Styling**: Tailwind CSS 4
-- **State Management**: Zustand for client-side state
-- **Database**: Supabase (PostgreSQL with real-time features)
-- **Testing**: Vitest for unit tests, Playwright for E2E tests
-- **Authentication**: Supabase Auth with email/password and password reset
+- **Styling**: Tailwind CSS 4 with Typography plugin
+- **State Management**: Zustand for client-side state with URL persistence
+- **Database**: Supabase (PostgreSQL with auth and real-time features)
+- **Testing**: Vitest (unit tests with JSDOM), Playwright (E2E with Page Object Model)
+- **Authentication**: Supabase Auth with email/password and password reset flow
+- **Validation**: Zod for schema validation, React Hook Form for forms
+- **Build Tools**: TypeScript 5, TSX for scripts
 
 ### Project Structure
 
@@ -49,51 +51,79 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 - `services/` - Business logic services, notably `RulesBuilderService`
 - `store/` - Zustand stores for state management
 - `hooks/` - Custom React hooks
+- `features/` - Feature flags system for environment-based functionality control
+- `i18n/` - Internationalization with translations
+- `db/` - Database types and utilities
 
 #### Key Components Architecture
-- **Rules System**: Rules are organized by technology stacks (frontend, backend, database, etc.) and stored in `src/data/rules/`
-- **Rules Builder Service**: Core service in `src/services/rules-builder/` that generates markdown content using strategy pattern (single-file vs multi-file output)
-- **Collections System**: User can save and manage rule collections via `collectionsStore`
-- **Feature Flags**: Environment-based feature toggling system in `src/features/featureFlags.ts`
+- **Rules System**: Rules are organized by technology stacks (frontend, backend, database, etc.) and stored in `src/data/rules/`. Each rule category exports typed rule arrays.
+- **Rules Builder Service**: Core service in `src/services/rules-builder/` that generates markdown content using strategy pattern (single-file vs multi-file output strategies)
+- **Collections System**: User can save and manage rule collections via `collectionsStore` with dirty state tracking and Supabase persistence
+- **Feature Flags**: Environment-based feature toggling system in `src/features/featureFlags.ts` controlling API endpoints, pages, and UI components
 
 #### MCP Server (`mcp-server/`)
 Standalone Cloudflare Worker implementing Model Context Protocol for programmatic access to AI rules. Provides tools:
-- `listAvailableRules` - Get available rule categories
-- `getRuleContent` - Fetch specific rule content
+- `listAvailableRules` - Get available rule categories with identifiers and stack hierarchy
+- `getRuleContent` - Fetch specific rule content by library identifier
+
+Deployed at: `https://10x-rules-mcp-server.przeprogramowani.workers.dev/sse`
 
 ### State Management Pattern
 The application uses Zustand with multiple specialized stores:
-- `techStackStore` - Manages selected libraries and tech stack
+- `techStackStore` - Manages selected libraries and tech stack with URL sync
 - `collectionsStore` - Handles saved rule collections with dirty state tracking
-- `authStore` - Authentication state management
-- `projectStore` - Project metadata (name, description)
+- `authStore` - Authentication state management with Supabase session handling
+- `projectStore` - Project metadata (name, description) with URL persistence
+- `navigationStore` - UI navigation state
 
 ### Environment Configuration
 - Uses Astro's environment schema for type-safe environment variables
-- Supports three environments: `local`, `integration`, `prod`
-- Feature flags control functionality per environment
+- Supports three environments: `local`, `integration`, `prod` (via `PUBLIC_ENV_NAME`)
+- Feature flags control functionality per environment (.ai/feature-flags.md)
 - Requires `.env.local` with Supabase credentials and Cloudflare Turnstile keys
 
 ### Database Integration
 - Supabase integration with TypeScript types in `src/db/database.types.ts`
 - Collections are stored in Supabase with user association
-- Real-time capabilities available but not currently utilized
+- Authentication flow includes email verification and password reset
+- Rate limiting implemented for API endpoints
 
 ### Testing Strategy
-- Unit tests use Vitest with React Testing Library and JSDOM
+- Unit tests use Vitest with React Testing Library and JSDOM environment
 - E2E tests use Playwright with Page Object Model pattern
-- Test files located in `tests/` for unit tests and `e2e/` for E2E tests
-- All tests run in CI/CD pipeline
+- Test setup includes MSW for API mocking
+- Tests run in CI/CD pipeline via GitHub Actions
+- E2E tests use `.env.integration` for isolated testing environment
 
 ### Rules Content System
 Rules are defined as TypeScript objects and exported from category-specific files in `src/data/rules/`. The system supports:
-- Categorization by technology layers (frontend, backend, database, etc.)
-- Library-specific rules with placeholder replacement
-- Multi-file vs single-file output strategies
-- Markdown generation with project context
+- Categorization by technology layers (frontend, backend, database, testing, infrastructure, accessibility, coding standards)
+- Library-specific rules with placeholder replacement ({{project_name}}, {{library}})
+- Multi-file vs single-file output strategies based on editor type
+- Markdown generation with project context and library-specific content
 
 ### Development Workflow
-1. Rules contributions go in `src/data/rules/` with corresponding translations in `src/i18n/translations.ts`
-2. Use feature flags to control new functionality rollout
-3. Collections allow users to save and share rule combinations
-4. The MCP server enables programmatic access for AI assistants
+1. Rules contributions go in `src/data/rules/` with corresponding translations in `src/i18n/translations.ts` (unit tests will fail without translations)
+2. Use feature flags to control new functionality rollout across environments
+3. Collections allow users to save and share rule combinations with authentication
+4. The MCP server enables programmatic access for AI assistants (Cursor, Claude, etc.)
+5. Run `npm run generate-rules` after modifying rules to update `preparedRules.json` for MCP server
+
+## Important Development Instructions
+
+### Key Development Principles
+- Do what has been asked; nothing more, nothing less
+- NEVER create files unless they're absolutely necessary for achieving your goal
+- ALWAYS prefer editing existing files to creating new ones
+- NEVER proactively create documentation files (*.md) or README files unless explicitly requested
+
+### Working with Rules
+- When adding new rules, they must be added to both `src/data/rules/` TypeScript files AND corresponding translations in `src/i18n/translations.ts`
+- Unit tests will fail if translations are missing for new rules
+- Always run `npm run migrate-rules` after adding rules to sync them with the database
+- Run `npm run generate-rules` after modifying rules to update `preparedRules.json` for the MCP server
+
+### Database vs File-Based Rules
+- The system supports both database-stored rules (default) and file-based fallback
+- Use `USE_DATABASE_RULES=false` environment variable to force file-based rules during development
+- Database rules allow updates without code deployments

README.md

@@ -80,13 +80,14 @@ CF_CAPTCHA_SECRET_KEY=1x0000000000000000000000000000000AA
 - React 18.3
 - Tailwind 4
 - Zustand
+- Supabase (PostgreSQL)
 - Lucide React
 
 ## Project Components
 
 This repository contains multiple key components:
 
--   **AI Rules Builder UI (Root):** The main Astro/React application providing the web interface for creating and managing AI rules.
+-   **AI Rules Builder UI (Root):** The main Astro/React application providing the web interface for creating and managing AI rules. Rules are dynamically loaded from Supabase database with automatic fallback to file-based rules for reliability.
 -   **MCP Server (`./mcp-server`):** A Cloudflare Worker implementing the Model Context Protocol (MCP). This server allows AI assistants (like Cursor, Claude, etc.) to programmatically access the defined AI rules via specific tools (`listAvailableRules`, `getRuleContent`). This enables integration with editors for fetching context-aware coding guidelines. For detailed setup, usage, and planned features, see the [MCP Server README](./mcp-server/README.md).
 
 ### Feature Flags
@@ -99,6 +100,27 @@ The project uses a feature flags system to separate deployments from releases. F
 
 For detailed documentation about feature flags implementation, see `.ai/feature-flags.md`.
 
+### Rules Management
+
+The application supports both database-stored and file-based rules:
+
+- **Database Rules (Default):** Rules are stored in Supabase and can be updated without code deployments
+- **File-Based Fallback:** Automatic fallback to TypeScript files in `src/data/rules/` if database is unavailable
+- **Environment Control:** Use `USE_DATABASE_RULES=false` to disable database rules entirely
+
+#### Available Scripts
+
+```bash
+# Migrate existing rules from files to database
+npm run migrate-rules
+
+# Development server (uses database rules by default)
+npm run dev
+
+# Generate rules JSON for MCP server
+npm run generate-rules
+```
+
 ### Testing
 
 This project uses a comprehensive testing stack including unit tests and end-to-end tests.
@@ -154,12 +176,19 @@ Tests are automatically run in the CI/CD pipeline using GitHub Actions. See `.gi
 
 ## Contributions
 
-Send updates to:
+### Adding New Rules
+
+- Add rules to appropriate files in `src/data/rules/`
+- Update `src/data/dictionaries.ts` for new libraries
+- Add translations in `src/i18n/translations.ts` (required for tests to pass)
+- Run `npm run migrate-rules` to sync with database
 
-- `src/data/dictionaries.ts`
-- `src/data/rules/...`
+### Development Workflow
 
-Important: Introduce translations for new rules in `src/i18n/translations.ts`, otherwise the unit test will fail.
+1. Add new rules via database or update TypeScript files
+2. If adding new libraries, update dictionaries and translations
+3. Test locally with both database and fallback modes
+4. Submit pull request with proper documentation
 
 ## How to Write Effective Rules
 

astro.config.mjs

@@ -20,10 +20,12 @@ export default defineConfig({
       CF_CAPTCHA_SITE_KEY: envField.string({
         context: 'server',
         access: 'secret',
+        optional: true,
       }),
       CF_CAPTCHA_SECRET_KEY: envField.string({
         context: 'server',
         access: 'secret',
+        optional: true,
       }),
     },
   },