pax_global_header00006660000000000000000000000064151651451670014525gustar00rootroot0000000000000052 comment=259b7174713081dd77da920dba515edc1f883cf7 ycode-0.12.0/000077500000000000000000000000001516514516700127105ustar00rootroot00000000000000ycode-0.12.0/.cursor/000077500000000000000000000000001516514516700143035ustar00rootroot00000000000000ycode-0.12.0/.cursor/rules/000077500000000000000000000000001516514516700154355ustar00rootroot00000000000000ycode-0.12.0/.cursor/rules/commit-messages.mdc000066400000000000000000000032151516514516700212200ustar00rootroot00000000000000--- description: Commit message conventions for all repositories alwaysApply: true --- # Commit Message Conventions ## Format ``` : ``` ## Types | Type | When | |------|------| | `feat` | New feature or capability | | `fix` | Bug fix | | `refactor` | Code restructuring with no behavior change | | `chore` | Maintenance, dependency updates, cleanup | | `docs` | Documentation only | | `style` | Formatting, whitespace (no logic change) | | `perf` | Performance improvement | | `test` | Adding or updating tests | ## Rules - **Imperative mood**: "add user auth" not "added user auth" or "adding user auth" - **Lowercase** after the type prefix: `feat: add domain management` - **No period** at the end of the subject line - **50 chars max** for the subject line (type + summary) - **Body** (if needed): wrap at 72 chars, separated by a blank line - **Focus on WHY** in the body, not what — the diff shows what changed - **No AI attribution**: never mention Cursor, AI, copilot, or assistant - **No filler words**: avoid "various", "some", "minor", "misc" — be specific - **No WIP commits**: if the work is incomplete, describe what IS done ## Examples ``` feat: add custom domain management to cloud settings refactor: extract tenant scoping into domain repository fix: prevent deletion of primary domain chore: remove orphaned management sync endpoint ``` ## Multi-concern commits (use bullet body) ``` refactor: clean up domain management feature - Remove dead unset-primary code path - Add tenant scoping to verification updates - Enforce 10-domain limit per tenant ``` ycode-0.12.0/.cursor/rules/pull-requests.mdc000066400000000000000000000045271516514516700207570ustar00rootroot00000000000000--- description: Pull request conventions for all repositories alwaysApply: true --- # Pull Request Conventions ## Title Use the same format as commit messages: ``` : ``` Examples: `feat: add custom domain management`, `fix: prevent primary domain deletion` ## Body Format ```markdown ## Summary <1-3 sentences explaining WHAT changed and WHY> ## Changes - Bullet list of specific changes grouped logically - Focus on behavior changes, not file-by-file diffs - Use imperative mood: "Add X" not "Added X" ## Test plan - [ ] Actionable checklist of how to verify the changes - [ ] Include edge cases worth testing ``` ## Rules - **Base branch**: always create PRs against the `develop` branch - **Assignee**: always assign the PR to the current GitHub user (`gh api user --jq '.login'`) - **Labels**: apply a label based on PR type — `Bug` for `fix:` PRs, `Feature request` for `feat:` PRs, `Improvement` for `refactor:` or `perf:` PRs, `Documentation` for `docs:` PRs. Skip labels for other types (chore, style, test) - **No AI attribution**: never mention Cursor, AI, copilot, or assistant - **Summary over detail**: reviewers read the diff — the PR describes intent - **Imperative mood** throughout: "Add", "Fix", "Remove", not past tense - **No filler**: avoid "various improvements", "some fixes" — be specific - **Link issues** when applicable: "Closes #123" in the summary - **Keep it scannable**: bullets over paragraphs, short lines - **Test plan is mandatory**: always include at least one verification step ## Example ```markdown ## Summary Add domain management UI and API for cloud tenants, allowing users to connect custom domains, verify DNS, and set a primary canonical URL. ## Changes - Add settings page at `/settings/domains` with add/remove/verify flows - Add API routes for domain CRUD, status checking, and primary selection - Integrate Vercel SDK for domain registration and DNS verification - Add middleware redirect from non-primary domains to primary - Enforce 10-domain limit per tenant ## Test plan - [ ] Add a custom domain and verify it appears in the list - [ ] Check DNS status shows correct records to configure - [ ] Set a domain as primary and confirm redirect works - [ ] Attempt to remove primary domain — should be blocked - [ ] Attempt to add 11th domain — should be rejected ``` ycode-0.12.0/.cursorrules000066400000000000000000001231111516514516700153000ustar00rootroot00000000000000# YCode Cursor AI Rules ## 🎯 Project Context **YCode** is a self-hosted visual website builder built with Next.js 15, TypeScript, Tailwind CSS, and Supabase. This is a **fast-moving team project** where multiple developers use Cursor simultaneously. Code consistency and abstraction are critical. --- ## 🧠 Core Philosophy: ALWAYS Think About Abstraction Before writing any code, ask yourself: 1. **Can this logic be extracted into a reusable hook?** 2. **Does a ShadCN component already exist for this UI element?** 3. **Is this component doing too many things? Should it be split?** 4. **Can this be a pure utility function instead of component logic?** 5. **Will another team member be able to reuse this easily?** **Golden Rule**: If you're writing the same code twice, abstract it. --- ## 🎨 1. ShadCN Components (MANDATORY) ### ALWAYS Use ShadCN for UI Primitives **Available ShadCN Components** (in `/components/ui/`): - `Button` - All button interactions - `Input` - Text inputs - `Textarea` - Multi-line text - `Label` - Form labels - `Select` - Dropdowns - `Tabs` - Tab navigation - `Dropdown Menu` - Context menus - `Popover` - Overlays - `Tooltip` - Hover hints - `Slider` - Range inputs - `Badge` - Status indicators - `Spinner` - Loading states - `Icon` - Lucide icons (via icon.tsx) ### ✅ CORRECT Usage ```typescript import { Button } from '@/components/ui/button'; import { Input } from '@/components/ui/input'; import { Icon } from '@/components/ui/icon'; export function SearchBar({ onSearch }: SearchBarProps) { const [query, setQuery] = useState(''); return (
setQuery(e.target.value)} placeholder="Search pages..." />
); } ``` ### ❌ FORBIDDEN - Never Do This ```typescript // ❌ WRONG: Custom button instead of ShadCN export function SearchBar({ onSearch }: SearchBarProps) { return ( ); } // ❌ WRONG: Custom input instead of ShadCN ``` ### Extending ShadCN Components If you need custom behavior, **compose** ShadCN components: ```typescript // ✅ CORRECT: Composition import { Button } from '@/components/ui/button'; import { Icon } from '@/components/ui/icon'; interface IconButtonProps { icon: string; label: string; onClick: () => void; } export function IconButton({ icon, label, onClick }: IconButtonProps) { return ( ); } ``` --- ## 🏗️ 2. Component Architecture & Abstraction ### Single Responsibility Principle Each component should do ONE thing well: ```typescript // ✅ GOOD: Small, focused components function PageListItem({ page, onSelect, isActive }: PageListItemProps) { return ( ); } function PageList({ pages, selectedId, onSelect }: PageListProps) { return (
{pages.map(page => ( ))}
); } // ❌ BAD: Monolithic component doing everything function PageManagement() { // 500 lines of code managing pages, settings, modals, etc. } ``` ### Extract Custom Hooks Move reusable logic into custom hooks: ```typescript // ✅ GOOD: Reusable hook export function useDebounce(value: T, delay: number): T { const [debouncedValue, setDebouncedValue] = useState(value); useEffect(() => { const handler = setTimeout(() => setDebouncedValue(value), delay); return () => clearTimeout(handler); }, [value, delay]); return debouncedValue; } // Usage in component function SearchInput() { const [query, setQuery] = useState(''); const debouncedQuery = useDebounce(query, 500); useEffect(() => { if (debouncedQuery) { performSearch(debouncedQuery); } }, [debouncedQuery]); } ``` ### Extract Utility Functions Keep components clean by moving pure functions to `/lib`: ```typescript // ✅ GOOD: Utility in /lib/layer-utils.ts export function findLayerById(layers: Layer[], id: string): Layer | null { for (const layer of layers) { if (layer.id === id) return layer; if (layer.children) { const found = findLayerById(layer.children, id); if (found) return found; } } return null; } // Usage in component import { findLayerById } from '@/lib/layer-utils'; function LayerEditor({ layers, selectedId }: LayerEditorProps) { const selectedLayer = findLayerById(layers, selectedId); // ... } ``` --- ## 📁 3. File & Naming Conventions ### File Names - **All files**: `kebab-case.tsx` (e.g., `page-settings.tsx`, `user-profile.tsx`) - **Components**: PascalCase export matching filename - File: `layer-renderer.tsx` → Export: `LayerRenderer` - **Utilities**: camelCase functions - File: `layer-utils.ts` → Export: `findLayerById` - **Hooks**: camelCase with `use` prefix - File: `use-debounce.ts` → Export: `useDebounce` ### Variable & Function Names ```typescript // Components & Types: PascalCase const UserProfile: React.FC = () => {}; interface LayerProps {} type PageStatus = 'draft' | 'published'; // Functions & Variables: camelCase const handleClick = () => {}; const userData = fetchUser(); function formatDate(date: Date) {} // Event Handlers: handleX pattern const handleSubmit = () => {}; const handlePageSelect = (id: string) => {}; const handleInputChange = (e: ChangeEvent) => {}; // Boolean: isX, hasX, shouldX const isLoading = false; const hasChildren = layers.length > 0; const shouldRender = isVisible && hasData; // Constants: SCREAMING_SNAKE_CASE const MAX_PAGE_SIZE = 100; const API_BASE_URL = 'https://api.example.com'; const DEFAULT_LAYER_CLASSES = 'flex gap-4'; ``` --- ## 📦 4. Import Organization **ALWAYS order imports consistently** to prevent merge conflicts: ```typescript // 1. React/Next.js core import React, { useState, useEffect, useMemo, useCallback } from 'react'; import { useRouter, usePathname } from 'next/navigation'; import Image from 'next/image'; // 2. External libraries (alphabetical) import { create } from 'zustand'; import debounce from 'lodash.debounce'; import { DndContext } from '@dnd-kit/core'; // 3. ShadCN UI components (alphabetical) import { Button } from '@/components/ui/button'; import { Input } from '@/components/ui/input'; import { Tabs, TabsList, TabsTrigger, TabsContent } from '@/components/ui/tabs'; // 4. Internal components (alphabetical) import { LayerRenderer } from '@/components/layers/LayerRenderer'; import { PageSettings } from './PageSettings'; import ElementLibrary from './ElementLibrary'; // 5. Stores (alphabetical) import { useEditorStore } from '@/stores/useEditorStore'; import { usePagesStore } from '@/stores/usePagesStore'; // 6. Utils, APIs, lib (alphabetical) import { pagesApi } from '@/lib/api'; import { cn } from '@/lib/utils'; import { findLayerById } from '@/lib/layer-utils'; // 7. Types (always last, alphabetical) import type { Layer, Page, PageLayers, Asset } from '@/types'; ``` --- ## 🛣️ 5. Path Aliases - When to Use What ### Rules: - Use `@/` for **everything outside current directory** - Use `./` **ONLY** for files in the **same directory** - Use `../` **sparingly** (max 1 level up, prefer `@/`) - **NEVER** use deep relative paths like `../../../../` ```typescript // ✅ CORRECT import { Button } from '@/components/ui/button'; import { useEditorStore } from '@/stores/useEditorStore'; import { PageSettings } from './PageSettings'; // Same directory import { findLayerById } from '@/lib/layer-utils'; // ❌ WRONG import { Button } from '../../../components/ui/button'; import { useEditorStore } from '../../stores/useEditorStore'; ``` --- ## ⚛️ 6. Server vs Client Components (Next.js 15) ### Default: Server Components **Don't add any directive** - components are Server Components by default. ### Add `'use client'` ONLY When: - Using React hooks (`useState`, `useEffect`, `useCallback`, etc.) - Using event handlers (`onClick`, `onChange`, `onSubmit`) - Using browser APIs (`window`, `localStorage`, `document`) - Using Zustand stores - Using client-only libraries ```typescript // ✅ Server Component (no directive) // app/[slug]/page.tsx export default async function Page({ params }: { params: { slug: string } }) { const page = await fetchPageBySlug(params.slug); return ; } // ✅ Client Component (with directive) // app/ycode/components/LayersTree.tsx 'use client'; import { useState } from 'react'; export default function LayersTree({ layers }: LayersTreeProps) { const [expanded, setExpanded] = useState>(new Set()); // Component using hooks and state } ``` ### Keep `'use client'` Close to Leaves Push client boundaries down the tree: ```typescript // ✅ GOOD: Server component wraps client component // app/page.tsx (Server Component) export default function Page() { return (
{/* Server */} {/* Client */}
{/* Server */}
); } // ❌ BAD: Everything is client-side unnecessarily 'use client'; export default function Page() { return (
{/* Unnecessarily client-side */}
{/* Unnecessarily client-side */}
); } ``` --- ## 🗄️ 7. Repository Pattern (Backend/API) ### NEVER Use Supabase Directly in API Routes **Architecture**: `API Route → Repository → Supabase Client` ```typescript // ✅ CORRECT: Use repository pattern // app/api/pages/[id]/route.ts import { NextRequest, NextResponse } from 'next/server'; import { getPageById, updatePage } from '@/lib/repositories/pageRepository'; export async function GET( request: NextRequest, { params }: { params: { id: string } } ) { try { const page = await getPageById(params.id); if (!page) { return NextResponse.json({ error: 'Page not found' }, { status: 404 }); } return NextResponse.json({ data: page }); } catch (error) { console.error('Error fetching page:', error); return NextResponse.json( { error: 'Failed to fetch page' }, { status: 500 } ); } } // ❌ WRONG: Direct Supabase in API route import { getSupabaseAdmin } from '@/lib/supabase-server'; export async function GET(request: NextRequest, { params }) { const supabase = await getSupabaseAdmin(); const { data } = await supabase.from('pages').select('*').eq('id', params.id); // WRONG! Use repository instead } ``` ### Create Repositories for All Data Entities **IMPORTANT**: Always use alias imports (`@/lib/...`) for all lib modules including `supabase-server` and repositories. Never use relative imports like `../supabase-server` or `../repositories/settingsRepository`. This ensures consistent behavior and allows overlays to work correctly in multi-tenant deployments. Example structure in `/lib/repositories/pageRepository.ts`: ```typescript import { getSupabaseAdmin } from '@/lib/supabase-server'; import type { Page } from '@/types'; export async function getAllPages(): Promise { const client = await getSupabaseAdmin(); const { data, error } = await client .from('pages') .select('*') .order('created_at', { ascending: false }); if (error) throw new Error(`Failed to fetch pages: ${error.message}`); return data || []; } export async function getPageById(id: string): Promise { const client = await getSupabaseAdmin(); const { data, error } = await client .from('pages') .select('*') .eq('id', id) .single(); if (error && error.code !== 'PGRST116') { throw new Error(`Failed to fetch page: ${error.message}`); } return data; } export async function createPage(pageData: Omit): Promise { const client = await getSupabaseAdmin(); const { data, error } = await client .from('pages') .insert(pageData) .select() .single(); if (error) throw new Error(`Failed to create page: ${error.message}`); return data; } ``` ### ALWAYS Use Upsert for Database Operations **NEVER execute queries in loops or use Promise.all for individual database operations.** Use batch operations with `upsert` instead of separate insert/update operations. ```typescript // ✅ CORRECT: Batch upsert operation const itemsToUpsert = items.map(item => ({ id: item.id, name: item.name, is_published: true, updated_at: new Date().toISOString(), })); await client .from('table_name') .upsert(itemsToUpsert, { onConflict: 'id,is_published', // Composite key }); // ❌ WRONG: Queries in loops for (const item of items) { const existing = await getItemById(item.id); if (existing) { await client.from('table_name').update(item).eq('id', item.id); } else { await client.from('table_name').insert(item); } } // ❌ WRONG: Promise.all with individual queries const updates = items.map(item => client.from('table_name').update(item).eq('id', item.id) ); await Promise.all(updates); ``` ### Rules 1. **ALWAYS** use `upsert` for insert/update operations 2. **NEVER** execute queries inside loops 3. **NEVER** use `Promise.all` with individual update queries 4. **ALWAYS** batch operations when possible 5. Use `onConflict` parameter to specify composite keys for upsert operations --- ## 🔄 8. API Response Format (Consistency) ### All API Routes MUST Return Consistent Format Use the `ApiResponse` type from `/types/index.ts`: ```typescript // ✅ Success response return NextResponse.json({ data: result }, { status: 200 }); // ✅ Error response return NextResponse.json({ error: 'Descriptive error message' }, { status: 400 }); // ✅ With optional message return NextResponse.json({ data: result, message: 'Page published successfully' }, { status: 200 }); ``` ### Status Codes - `200` - Success (GET, PUT) - `201` - Created (POST) - `204` - No Content (DELETE) - `400` - Bad Request (validation errors) - `404` - Not Found - `500` - Internal Server Error --- ## ⚠️ 9. Error Handling & Async Operations ### ALWAYS Follow This Pattern ```typescript // ✅ REQUIRED pattern for ALL async operations const handleAction = async () => { try { setLoading(true); setError(null); // Clear previous errors const result = await apiCall(); // Success handling setData(result); } catch (error) { console.error('Context-specific message:', error); setError(error instanceof Error ? error.message : 'Unknown error occurred'); } finally { setLoading(false); // Always runs } }; ``` ### In Components with UI State ```typescript function PageEditor({ pageId }: PageEditorProps) { const [page, setPage] = useState(null); const [loading, setLoading] = useState(true); const [error, setError] = useState(null); useEffect(() => { const loadPage = async () => { try { setLoading(true); const result = await pagesApi.getById(pageId); setPage(result.data); } catch (err) { setError(err instanceof Error ? err.message : 'Failed to load page'); } finally { setLoading(false); } }; loadPage(); }, [pageId]); if (loading) return ; if (error) return ; if (!page) return null; return
{/* Render page */}
; } ``` --- ## ⏳ 10. Loading States (MANDATORY) ### Always Show Loading for Async Operations ```typescript // ✅ CORRECT: Loading state shown function PageList() { const [pages, setPages] = useState([]); const [loading, setLoading] = useState(true); useEffect(() => { fetchPages().then(setPages).finally(() => setLoading(false)); }, []); if (loading) { return ; } return
{/* Render pages */}
; } // ❌ WRONG: No loading state function PageList() { const [pages, setPages] = useState([]); useEffect(() => { fetchPages().then(setPages); }, []); return
{/* Flashes empty state, then content */}
; } ``` ### Use ShadCN Spinner ```typescript import { Spinner } from '@/components/ui/spinner'; if (loading) return ; if (loading) return (
); ``` --- ## 🔀 11. Conditional Rendering - Early Returns ### Prefer Early Returns Over Nested Ternaries ```typescript // ✅ GOOD: Early returns (clean, readable) function PageEditor({ pageId }: PageEditorProps) { const { page, loading, error } = usePageData(pageId); if (loading) { return ; } if (error) { return ; } if (!page) { return ; } return (

{page.title}

{/* Main content */}
); } // ❌ BAD: Nested ternaries (hard to read, hard to maintain) function PageEditor({ pageId }: PageEditorProps) { const { page, loading, error } = usePageData(pageId); return loading ? ( ) : error ? ( ) : !page ? ( ) : (

{page.title}

{/* Main content */}
); } ``` ### For Simple Conditions Use inline ternaries for simple show/hide: ```typescript // ✅ GOOD: Simple inline conditional
{isVisible && } {count > 0 ? {count} : null}
``` --- ## 🎭 12. State Management with Zustand ### Keep Stores Focused and Domain-Specific ```typescript // ✅ GOOD: Focused store // stores/useEditorStore.ts import { create } from 'zustand'; interface EditorState { selectedLayerId: string | null; currentPageId: string | null; isLoading: boolean; isSaving: boolean; } interface EditorActions { setSelectedLayerId: (id: string | null) => void; setCurrentPageId: (id: string | null) => void; setLoading: (value: boolean) => void; setSaving: (value: boolean) => void; } type EditorStore = EditorState & EditorActions; export const useEditorStore = create((set) => ({ selectedLayerId: null, currentPageId: null, isLoading: false, isSaving: false, setSelectedLayerId: (id) => set({ selectedLayerId: id }), setCurrentPageId: (id) => set({ currentPageId: id }), setLoading: (value) => set({ isLoading: value }), setSaving: (value) => set({ isSaving: value }), })); ``` ### Use TypeScript Interfaces for Store Types Always define separate interfaces for state and actions, then combine them. --- ## ⚡ 13. Performance Optimization ### When to Optimize 1. **Profile First** - Don't optimize prematurely 2. **Use React DevTools Profiler** to identify slow components 3. **Optimize when you see actual performance issues** ### React.memo for Expensive Pure Components ```typescript // ✅ Use React.memo for pure components that render often import React, { memo } from 'react'; interface LayerItemProps { layer: Layer; onSelect: (id: string) => void; } const LayerItem: React.FC = memo(({ layer, onSelect }) => { return (
onSelect(layer.id)}> {layer.name}
); }); ``` ### useCallback for Functions Passed as Props ```typescript // ✅ useCallback prevents unnecessary re-renders function LayersList({ layers }: LayersListProps) { const handleSelect = useCallback((id: string) => { console.log('Selected:', id); }, []); // Empty deps - function never changes return ( <> {layers.map(layer => ( ))} ); } ``` ### useMemo for Expensive Calculations ```typescript // ✅ useMemo caches expensive computations function PageEditor({ pageId }: PageEditorProps) { const { draftsByPageId } = usePagesStore(); // Expensive: traverse tree structure const layersForCurrentPage = useMemo(() => { if (!pageId) return []; const draft = draftsByPageId[pageId]; return draft ? draft.layers : []; }, [pageId, draftsByPageId]); return ; } ``` --- ## ♿ 14. Accessibility (A11y) ### Required for All Interactive Elements ```typescript // ✅ GOOD: Accessible button This action cannot be undone // ❌ BAD: Not accessible
``` ### Checklist - ✅ Use semantic HTML (` // ✅ Using ShadCN ``` ### 2. Direct Supabase in API Routes ```typescript // ❌ Direct Supabase const supabase = await getSupabaseAdmin(); await supabase.from('pages').select(); // ✅ Use repository await getAllPages(); ``` ### 3. Nested Ternaries ```typescript // ❌ Nested ternaries return loading ? : error ? : ; // ✅ Early returns if (loading) return ; if (error) return ; return ; ``` ### 4. Missing Loading States ```typescript // ❌ No loading state const [data, setData] = useState([]); useEffect(() => { fetch().then(setData); }, []); return ; // ✅ With loading state const [data, setData] = useState([]); const [loading, setLoading] = useState(true); useEffect(() => { fetch().then(setData).finally(() => setLoading(false)); }, []); if (loading) return ; return ; ``` ### 5. Using `any` Type ```typescript // ❌ Using any function process(data: any) { } // ✅ Proper types function process(data: Page[]) { } ``` ### 6. Deep Relative Imports ```typescript // ❌ Deep relative paths import { Button } from '../../../../components/ui/button'; // ✅ Use path alias import { Button } from '@/components/ui/button'; ``` ### 7. Not Abstracting Repeated Logic ```typescript // ❌ Repeated debounce logic everywhere const [debouncedValue, setDebouncedValue] = useState(value); useEffect(() => { const timer = setTimeout(() => setDebouncedValue(value), 500); return () => clearTimeout(timer); }, [value]); // ✅ Extract to custom hook const debouncedValue = useDebounce(value, 500); ``` --- ## 🎯 Quick Checklist Before Committing - [ ] Using ShadCN components for all UI primitives? - [ ] Extracted reusable logic into hooks/utils? - [ ] Components are small and focused (single responsibility)? - [ ] Used proper TypeScript types (no `any`)? - [ ] Imports organized correctly? - [ ] Using `@/` path aliases (not relative paths)? - [ ] Loading states for all async operations? - [ ] Error handling with try/catch/finally? - [ ] Early returns instead of nested ternaries? - [ ] Added `'use client'` only when needed? - [ ] API routes use repository pattern? - [ ] Consistent API response format? - [ ] Event handlers named `handleX`? - [ ] Boolean props named `isX`, `hasX`, `shouldX`? - [ ] **Null check after `getSupabaseAdmin()` in ALL cases?** - [ ] **New icons added to BOTH type definition AND ICONS object?** - [ ] **Repository functions use dedicated `CreateXData` / `UpdateXData` interfaces?** - [ ] **Zod schemas use `message` parameter (not `required_error`)?** - [ ] Run `npm run lint:fix` and `npm run type-check`? - [ ] Sanitize design property inputs with `removeSpaces`? - [ ] Use `useControlledInput` for input state management? - [ ] **Migrations are idempotent (safe to run multiple times)?** --- ## 🔧 20. Supabase Client Null Checking (CRITICAL) ### ALWAYS Check for Null After getSupabaseAdmin() The `getSupabaseAdmin()` function can return `null` if Supabase is not configured. **ALWAYS** add a null check immediately after calling it. ```typescript // ✅ CORRECT: Always check for null export async function getPageById(id: string): Promise { const client = await getSupabaseAdmin(); if (!client) { throw new Error('Supabase not configured'); } const { data, error } = await client .from('pages') .select('*') .eq('id', id) .single(); if (error && error.code !== 'PGRST116') { throw new Error(`Failed to fetch page: ${error.message}`); } return data; } // ❌ WRONG: No null check - TypeScript error export async function getPageById(id: string): Promise { const client = await getSupabaseAdmin(); // TypeScript error: 'client' is possibly 'null' const { data, error } = await client .from('pages') .select('*') .eq('id', id) .single(); return data; } ``` ### In API Routes ```typescript // ✅ CORRECT: Return error response if client is null export async function GET(request: NextRequest) { try { const client = await getSupabaseAdmin(); if (!client) { return NextResponse.json( { error: 'Supabase not configured' }, { status: 500 } ); } // Use client safely const { data } = await client.from('pages').select('*'); return NextResponse.json({ data }); } catch (error) { return NextResponse.json({ error: 'Server error' }, { status: 500 }); } } ``` ### Rules 1. **ALWAYS** check `if (!client)` after `await getSupabaseAdmin()` 2. In repository functions: **throw an error** with descriptive message 3. In API routes: **return error response** with status 500 4. **NEVER** use the client without checking for null first --- ## 🎨 21. Icon Component Extension ### Adding New Icons When you need to add a new icon to the `Icon` component, follow these steps: **Step 1: Update the TypeScript Union Type** ```typescript // components/ui/icon.tsx export interface IconProps extends React.SVGProps { name: ( 'x' | 'layers' | 'database' | 'plus' | /* ...existing icons... */ | 'pencil' | 'eye' | 'eye-off' | 'trash' | 'upload' // Add your new icons here ); } ``` **Step 2: Add SVG Definition to ICONS Object** ```typescript // components/ui/icon.tsx const ICONS: Record = { // ...existing icons... pencil: ( <> ), trash: ( <> ), // Add more icons here }; ``` ### Rules 1. **ALWAYS** update both the type definition AND the ICONS object 2. Use **kebab-case** for icon names (e.g., `eye-off`, not `eyeOff`) 3. Get SVG paths from **Lucide icons** or **Heroicons** for consistency 4. Set `viewBox="0 0 12 12"` for all icons (they're scaled to 12x12) 5. Test the icon renders correctly before committing ### ❌ Common Mistake ```typescript // ❌ WRONG: Added icon to ICONS but forgot to update type // TypeScript error: Type '"new-icon"' is not assignable ``` --- ## 🗄️ 22. Repository Input Type Patterns ### Create Dedicated Input Interfaces for Repository Functions Instead of using complex `Omit<>` types, create clear input interfaces for create/update operations. ```typescript // ✅ CORRECT: Dedicated input interface import type { Component, Layer } from '@/types'; export interface CreateComponentData { name: string; layers: Layer[]; } export async function createComponent( componentData: CreateComponentData ): Promise { const client = await getSupabaseAdmin(); if (!client) { throw new Error('Supabase not configured'); } // The repository sets is_published, publish_key, etc. const { data, error } = await client .from('components') .insert({ name: componentData.name, layers: componentData.layers, is_published: false, publish_key: generateKey(), // ...other auto-generated fields }) .select() .single(); if (error) throw new Error(`Failed to create: ${error.message}`); return data; } // ❌ WRONG: Using Omit includes fields that should be auto-set export async function createComponent( componentData: Omit ): Promise { // This requires is_published and publish_key to be passed in, // but they should be set automatically! } ``` ### Pattern for Update Functions ```typescript // ✅ CORRECT: Update interface with all optional fields export interface UpdateComponentData { name?: string; layers?: Layer[]; // Only fields that can actually be updated } export async function updateComponent( id: string, componentData: UpdateComponentData ): Promise { // Implementation } ``` ### Rules 1. **CREATE**: Define `CreateXData` interface with only required input fields 2. **UPDATE**: Define `UpdateXData` interface with all optional fields 3. **NEVER** use `Omit` for input types 4. Auto-generated fields (`id`, `created_at`, `is_published`, `publish_key`) should NOT be in input interfaces 5. The repository layer is responsible for setting auto-generated fields --- ## 🔍 23. Zod Validation Best Practices ### Use Correct Parameter Names When defining Zod schemas, use the correct parameter names for your validation library version. ```typescript // ✅ CORRECT: Use 'message' for error messages const formSchema = z.object({ name: z.string().min(2, { message: 'Name must be at least 2 characters.', }), type: z.enum(['text', 'number', 'boolean', 'date', 'reference'], { message: 'Please select a field type.', }), }); // ❌ WRONG: Using 'required_error' (deprecated/invalid parameter) const formSchema = z.object({ type: z.enum(['text', 'number'], { required_error: 'Please select a type.', // TypeScript error }), }); ``` ### Common Zod Patterns ```typescript // String with constraints z.string().min(1, { message: 'Required' }).max(100) // Optional field z.string().optional() // Nullable field z.string().nullable() // Enum with message z.enum(['draft', 'published'], { message: 'Invalid status' }) // Number with range z.number().min(0).max(100) // Email validation z.string().email({ message: 'Invalid email' }) // Custom validation z.string().refine((val) => val.startsWith('test'), { message: 'Must start with "test"', }) ``` --- ## 🚀 Team Collaboration Best Practices ### For Fast-Moving Teams Using Cursor 1. **Think abstraction first** - Before coding, ask "Can I reuse something?" 2. **Use ShadCN religiously** - Never reinvent UI primitives 3. **Keep PRs small** - Small, focused changes prevent conflicts 4. **Follow naming conventions strictly** - Makes searching and refactoring easy 5. **Document complex logic** - Help your teammates understand WHY 6. **Run linters before committing** - Catch issues early 7. **Prefer composition over duplication** - DRY principle 8. **Use TypeScript properly** - Types are documentation --- ## 🗃️ 24. Database Migrations (CRITICAL for Templates) ### ALWAYS Write Idempotent Migrations Migrations MUST be safe to run multiple times. This is critical because: 1. **Template System**: When applying templates, migrations run on freshly inserted template data 2. **Schema already exists**: The database schema is already up-to-date when template migrations run 3. **Data transformations**: Only the data parts actually execute on template data ### Schema Changes: Use IF EXISTS / IF NOT EXISTS ```typescript // ✅ CORRECT: Idempotent schema changes export async function up(knex: Knex): Promise { // Check before adding column const hasColumn = await knex.schema.hasColumn('pages', 'new_field'); if (!hasColumn) { await knex.schema.alterTable('pages', (table) => { table.string('new_field').defaultTo(''); }); } } // ✅ CORRECT: Raw SQL with IF NOT EXISTS await knex.raw(` ALTER TABLE pages ADD COLUMN IF NOT EXISTS new_field TEXT DEFAULT ''; `); // ❌ WRONG: Will fail if column exists await knex.schema.alterTable('pages', (table) => { table.string('new_field').defaultTo(''); }); ``` ### Data Transformations: Use Safe WHERE Clauses ```typescript // ✅ CORRECT: Only updates rows that need it await knex.raw(` UPDATE pages SET slug = LOWER(REGEXP_REPLACE(name, '[^a-zA-Z0-9]+', '-', 'g')) WHERE slug IS NULL OR slug = ''; `); // ❌ WRONG: Overwrites all data on every run await knex('pages').update({ slug: knex.raw("LOWER(REGEXP_REPLACE(name, '[^a-zA-Z0-9]+', '-', 'g'))") }); ``` ### Template-Affecting Tables These tables are exported/imported with templates - migrations affecting them MUST be idempotent: - `pages`, `page_folders`, `page_layers` - `components` - `collections`, `collection_fields`, `collection_items`, `collection_item_values` - `assets`, `asset_folders` - `layer_styles` - `locales`, `translations` ### Migration Checklist - [ ] Schema changes use `IF NOT EXISTS` or check `hasColumn()` - [ ] Data updates use `WHERE` clauses that skip already-transformed rows - [ ] New NOT NULL columns have DEFAULT values - [ ] Migration can run twice without error - [ ] Migration can run on fresh template data ### Full Example ```typescript import { Knex } from 'knex'; export async function up(knex: Knex): Promise { // 1. Add column (idempotent) const hasColumn = await knex.schema.hasColumn('pages', 'seo_title'); if (!hasColumn) { await knex.schema.alterTable('pages', (table) => { table.string('seo_title').defaultTo(''); }); } // 2. Transform data (idempotent - only empty values) await knex.raw(` UPDATE pages SET seo_title = LEFT(name, 60) WHERE seo_title IS NULL OR seo_title = ''; `); } export async function down(knex: Knex): Promise { const hasColumn = await knex.schema.hasColumn('pages', 'seo_title'); if (hasColumn) { await knex.schema.alterTable('pages', (table) => { table.dropColumn('seo_title'); }); } } ``` --- **Remember**: Consistency > Cleverness. A fast-moving team needs predictable patterns, not creative solutions. ycode-0.12.0/.editorconfig000066400000000000000000000007461516514516700153740ustar00rootroot00000000000000# top-most EditorConfig file root = true # Default settings for all files [*] charset = utf-8 end_of_line = lf insert_final_newline = true trim_trailing_whitespace = true indent_style = space indent_size = 2 # TypeScript, JavaScript, JSX, TSX (additional code-specific settings) [*.{js,jsx,ts,tsx,mjs,cjs}] quote_type = single max_line_length = 100 # Markdown files (disable line length and trailing whitespace trimming) [*.md] trim_trailing_whitespace = false max_line_length = off ycode-0.12.0/.env.example000066400000000000000000000006341516514516700151360ustar00rootroot00000000000000# Supabase credentials SUPABASE_PUBLISHABLE_KEY= SUPABASE_SECRET_KEY= SUPABASE_CONNECTION_URL= SUPABASE_DB_PASSWORD= # Templates API NEXT_PUBLIC_TEMPLATE_API_URL= TEMPLATE_API_URL= TEMPLATE_UPLOAD_API_KEY= # Secret key for signing page auth cookies (can be generated using `openssl rand -hex 32`) PAGE_AUTH_SECRET= # Google Fonts API Key (only to used to execute `npm run fonts:update`) GOOGLE_FONTS_API_KEY= ycode-0.12.0/.github/000077500000000000000000000000001516514516700142505ustar00rootroot00000000000000ycode-0.12.0/.github/CODEOWNERS000066400000000000000000000000621516514516700156410ustar00rootroot00000000000000* @liamwalder @lunenas @tristan-mouchet @ysamcode ycode-0.12.0/.github/ISSUE_TEMPLATE/000077500000000000000000000000001516514516700164335ustar00rootroot00000000000000ycode-0.12.0/.github/ISSUE_TEMPLATE/bug-report.yml000066400000000000000000000036431516514516700212520ustar00rootroot00000000000000name: Bug Report description: Report a bug or unexpected behavior in Ycode labels: ["bug"] body: - type: markdown attributes: value: | Thanks for taking the time to report a bug! Please fill out the sections below so we can reproduce and fix the issue. - type: textarea id: description attributes: label: Description description: A clear and concise description of the bug. placeholder: Describe what went wrong... validations: required: true - type: textarea id: steps attributes: label: Steps to reproduce description: Detailed steps to reproduce the behavior. placeholder: | 1. Go to '...' 2. Click on '...' 3. Scroll down to '...' 4. See error validations: required: true - type: textarea id: expected attributes: label: Expected behavior description: What you expected to happen. validations: required: true - type: textarea id: actual attributes: label: Actual behavior description: What actually happened. validations: required: true - type: textarea id: screenshots attributes: label: Screenshots or screen recordings description: If applicable, add screenshots or recordings to help explain the problem. - type: dropdown id: deployment attributes: label: Deployment type options: - Self-hosted - Ycode Cloud validations: required: true - type: input id: browser attributes: label: Browser placeholder: e.g. Chrome 120, Firefox 121, Safari 17 - type: input id: os attributes: label: Operating system placeholder: e.g. macOS 15, Windows 11, Ubuntu 24.04 - type: textarea id: additional attributes: label: Additional context description: Any other context about the problem (error messages, console logs, etc.). ycode-0.12.0/.github/ISSUE_TEMPLATE/config.yml000066400000000000000000000004561516514516700204300ustar00rootroot00000000000000blank_issues_enabled: false contact_links: - name: Documentation url: https://docs.ycode.com about: Check the docs — your question may already be answered. - name: Discord Community url: https://discord.gg/xadfw2DV4q about: Chat with the community and get help with self-hosting. ycode-0.12.0/.github/ISSUE_TEMPLATE/feature-request.yml000066400000000000000000000027111516514516700223000ustar00rootroot00000000000000name: Feature Request description: Suggest a new feature or improvement for Ycode labels: ["enhancement"] body: - type: markdown attributes: value: | Thanks for suggesting a feature! Please describe your idea below. - type: textarea id: problem attributes: label: Problem or motivation description: What problem does this feature solve? Is it related to a frustration? placeholder: I'm always frustrated when... validations: required: true - type: textarea id: solution attributes: label: Proposed solution description: Describe the solution you'd like. Be as specific as possible. validations: required: true - type: textarea id: alternatives attributes: label: Alternatives considered description: Describe any alternative solutions or workarounds you've considered. - type: dropdown id: area attributes: label: Area description: Which part of Ycode does this relate to? options: - Visual Editor - Collections / CMS - Pages & Routing - Components - Assets & Media - Design Properties - Settings - API - Self-hosting / Deployment - Other validations: required: true - type: textarea id: additional attributes: label: Additional context description: Any mockups, screenshots, or references that help illustrate the feature. ycode-0.12.0/.github/PULL_REQUEST_TEMPLATE.md000066400000000000000000000004701516514516700200520ustar00rootroot00000000000000## Summary ## Changes - ## Test plan - [ ] ycode-0.12.0/.gitignore000066400000000000000000000011731516514516700147020ustar00rootroot00000000000000# dependencies /node_modules /.pnp .pnp.* .yarn/* !.yarn/patches !.yarn/plugins !.yarn/releases !.yarn/versions # testing /coverage /tmp # next.js /.next/ /out/ # production /build /dist # misc .DS_Store Thumbs.db *.pem # debug npm-debug.log* yarn-debug.log* yarn-error.log* .pnpm-debug.log* # env files .env* !.env.example # credentials *.credentials.json # IDE / editor config .idea/ .vscode/ .cursor/ .cursorrules *.swp *.swo *~ # OS files .AppleDouble .LSOverride ._* .Spotlight-V100 .Trashes # vercel .vercel # typescript *.tsbuildinfo next-env.d.ts # database *.sqlite3 *.sqlite # turbo .turbo # scripts release.sh ycode-0.12.0/.husky/000077500000000000000000000000001516514516700141315ustar00rootroot00000000000000ycode-0.12.0/.husky/pre-commit000066400000000000000000000000431516514516700161250ustar00rootroot00000000000000npx lint-staged npm run type-check ycode-0.12.0/.idea/000077500000000000000000000000001516514516700136705ustar00rootroot00000000000000ycode-0.12.0/.idea/.gitignore000066400000000000000000000002601516514516700156560ustar00rootroot00000000000000# Default ignored files /shelf/ /workspace.xml # Editor-based HTTP Client requests /httpRequests/ # Datasource local storage ignored files /dataSources/ /dataSources.local.xml ycode-0.12.0/.idea/dataSources.xml000066400000000000000000000016571516514516700167000ustar00rootroot00000000000000 sqlite.xerial true org.sqlite.JDBC jdbc:sqlite:$PROJECT_DIR$/laravel/database/database.sqlite $ProjectFileDir$ file://$APPLICATION_CONFIG_DIR$/jdbc-drivers/Xerial SQLiteJDBC/3.45.1/org/xerial/sqlite-jdbc/3.45.1.0/sqlite-jdbc-3.45.1.0.jar file://$APPLICATION_CONFIG_DIR$/jdbc-drivers/Xerial SQLiteJDBC/3.45.1/org/slf4j/slf4j-api/1.7.36/slf4j-api-1.7.36.jar ycode-0.12.0/.idea/modules.xml000066400000000000000000000004121516514516700160570ustar00rootroot00000000000000 ycode-0.12.0/.idea/php-test-framework.xml000066400000000000000000000007641516514516700201600ustar00rootroot00000000000000 ycode-0.12.0/.idea/php.xml000066400000000000000000000240371516514516700152070ustar00rootroot00000000000000 ycode-0.12.0/.idea/vcs.xml000066400000000000000000000002641516514516700152070ustar00rootroot00000000000000 ycode-0.12.0/.idea/ycode-4.iml000066400000000000000000000264161516514516700156500ustar00rootroot00000000000000 ycode-0.12.0/.vscode/000077500000000000000000000000001516514516700142515ustar00rootroot00000000000000ycode-0.12.0/.vscode/settings.json000066400000000000000000000003341516514516700170040ustar00rootroot00000000000000{ "editor.formatOnSave": false, "editor.codeActionsOnSave": { "source.fixAll.eslint": "explicit" }, "eslint.validate": [ "javascript", "javascriptreact", "typescript", "typescriptreact" ] } ycode-0.12.0/CHANGELOG.md000066400000000000000000000064011516514516700145220ustar00rootroot00000000000000# Changelog All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/), and this project adheres to [Semantic Versioning](https://semver.org/). ## [0.2.0] - 2026-03-03 ### Added - Filter layer with pagination integration for collections - Dynamic sorting linked to filter form inputs - Collection-sourced select options for reference field filtering - Cascading component overrides with enhanced instance management - Rich-text component overrides and editor UX improvements - Semantic `