doc(rules): add roo code rules

Author: adaptive-shield-matrix

.gitignore

@@ -87,7 +87,6 @@ convex/_generated
 astro
 
 # ai, ethereal and auto generated
-.roo/rules-code
 AGENTS.md
 
 # npm publishing

.roo/rules-code/convex.md

@@ -0,0 +1,126 @@
+# convex
+
+## Validator Patterns
+
+### DRY Validator Definition
+
+Define validators in a reusable, DRY pattern following the example in `convex/generate_image/generate_same/imageGenerationValidator.ts`:
+
+```typescript
+import { v } from "convex/values"
+
+// Define base fields as a const object
+export const someEntityValidatorFields = {
+  workspaceId: v.id("workspace"),
+  name: v.string(),
+  // ... other fields
+}
+
+// Create base validator
+export const someEntityValidator = v.object(someEntityValidatorFields)
+
+// Create variant with token for mutations/queries
+export const someEntityValidatorWithToken = v.object({ 
+  ...someEntityValidatorFields, 
+  token: v.string() 
+})
+
+// Export the type
+export type SomeEntityValidatorType = typeof someEntityValidator.type
+```
+
+### Type-Safe ID Definitions
+
+Use existing type-safe ID definitions like in `convex/auth/IdUser.ts`:
+
+```typescript
+import type { Id } from "../_generated/dataModel"
+
+export type IdUser = Id<"users">
+export type IdWorkspace = Id<"workspace">
+// Add other ID types as needed
+```
+
+## Query/Mutation Patterns
+
+### Function Variants
+
+Each query/mutation/internalQuery/internalMutation should have a corresponding `Fn` function variant, following the pattern in `convex/auth/crud/findUserByEmailQuery.ts`:
+
+```typescript
+import type { QueryCtx } from "../../_generated/server"
+import { internalQuery } from "../../_generated/server"
+import { v } from "convex/values"
+
+// Define the query
+export const findUserByEmailQuery = internalQuery({
+  args: { email: v.string() },
+  handler: async (ctx, args): Promise<Doc<"users"> | null> => {
+    return findUserByEmailFn(ctx, args.email)
+  },
+})
+
+// Define the Fn function variant for reuse
+export async function findUserByEmailFn(ctx: QueryCtx, email: string): Promise<Doc<"users"> | null> {
+  return await ctx.db
+    .query("users")
+    .withIndex("email", (q) => q.eq("email", email))
+    .unique()
+}
+```
+
+### Token Validation
+
+All mutations and queries should include a `token` parameter with validation:
+
+```typescript
+import { v } from "convex/values"
+import { mutation } from "../../_generated/server"
+
+export const someMutation = mutation({
+  args: {
+    // Use the validator with token
+    ...someEntityValidatorWithToken.fields,
+  },
+  handler: async (ctx, args) => {
+    // Validate token first
+    const user = await validateToken(ctx, args.token)
+    if (!user) {
+      throw new Error("Invalid token")
+    }
+    
+    // Proceed with mutation logic
+    return someMutationFn(ctx, args, user)
+  },
+})
+
+export async function someMutationFn(ctx: MutationCtx, args: SomeEntityValidatorType, user: Doc<"users">) {
+  // Mutation implementation
+}
+```
+
+## Data Transformation Patterns
+
+### Database to Model Transformation
+
+Create transformation functions to convert database documents to your application models:
+
+```typescript
+import type { UserProfile } from "@/auth/model/UserProfile"
+import type { Doc } from "../../_generated/dataModel"
+
+export function dbUsersToUserProfile(u: Doc<"users">): UserProfile {
+  const { _id, _creationTime, ...rest } = u
+  return { userId: _id, ...rest }
+}
+```
+
+## Best Practices
+
+1. **Always use validators** for all query/mutation arguments
+2. **Include token validation** in all public-facing mutations/queries
+3. **Create Fn variants** for all database operations to enable reuse
+4. **Use type-safe IDs** instead of string literals
+5. **Keep validators close** to where they're used
+6. **Export transformation functions** for consistent data conversion
+7. **Follow DRY principles** by defining base validators and extending them

.roo/rules-code/enums.md

@@ -0,0 +1,36 @@
+# Centralized definition of string literals
+
+- Define all magic strings as const objects
+- No magic strings scattered throughout the codebase
+- Create derived types using `keyof typeof`
+- Generate validation schemas using the const object values and `valibot` library
+- Export arrays of valid values
+
+```typescript
+import { getObjectValues } from "@/utils/obj/getObjectValues"
+import * as v from "valibot"
+
+// Type
+export type UserRole = keyof typeof userRole
+
+// Values
+export const userRole = {
+  user: "user",
+  admin: "admin",
+  dev: "dev",
+} as const
+
+// Schema
+export const userRoleSchema = v.enum(userRole)
+
+// Type checking to see if schema matches type
+function types1(a: v.InferOutput<typeof userRoleSchema>): UserRole {
+  return a
+}
+
+// Usage
+function handleLogin(provider: UserRole) {
+  // Type-safe provider handling
+  const user = userRole.user === provider
+}
+```

.roo/rules-code/functions.md

@@ -0,0 +1,37 @@
+# Function Modularization
+
+## Overview
+
+When refactoring code, particularly extracting functions from components, follow these guidelines to maintain clean, readable, and maintainable code structure.
+
+- Prefer `function` over `const` for functions
+- Prefer early `if(!matching) return` over `if (matching)` checks
+- Prefer early `if(!matching) continue` over `if (matching)` checks in for loops
+- Break large functions into smaller, focused functions
+- Break functions if using try catch
+- Each function should have a single responsibility
+- Name functions clearly based on their purpose
+- Keep functions pure when possible (no side effects)
+- Avoid else statements where possible
+- Do not use const arrow function to define functions
+- Always separate `fetch` calls into a separate function
+
+## General Principles
+
+### 1. Function Placement
+
+- **Component functions first**: Place the main component function at the top of the file, immediately after imports and type definitions.
+- **Helper/utility functions last**: Move extracted helper functions to the bottom of the file, after the main component.
+- **Dependency order**: Functions that depend on others should come after their dependencies.
+
+### 2. Function Declaration Style
+
+- **Use function declarations**: Prefer `function functionName() {}` over arrow function constants (`const functionName = () => {}`).
+- **Explicit return types**: Always specify return types for functions, especially when TypeScript can infer them.
+- **Clear parameter naming**: Use descriptive parameter names that indicate their purpose and types.
+
+### 3. Function Naming
+
+- **Descriptive names**: Functions should have names that clearly describe their purpose.
+- **PascalCase for components**: Component functions should use PascalCase.
+- **camelCase for utilities**: Helper/utility functions should use camelCase.

.roo/rules-code/include_imports_only_after_using_them.md

@@ -0,0 +1,14 @@
+# Import Management Guidelines
+
+Do NOT add import statements before using the corresponding symbols in the code.
+Reason: vscode auto optimizes them away on file save because they are unused.
+
+Example:
+
+```typescript
+// First, write code that uses the import
+const result = someFunction();
+
+// Then, add the import right before usage
+import { someFunction } from './library';
+```

.roo/rules-code/result.md

@@ -0,0 +1,19 @@
+# Result
+
+- Use `Result` types for expected errors
+- Always prefer to use Result over try-catch blocks
+- If using `fetch`: always use `PromiseResult` return type, validate output with `valibot`
+
+```ts
+import { type Result } from "~utils/result/Result"
+
+function processRequest(req: Request): SimpleResult<User> {
+  const result = validateRequest(req)
+  if (!result.success) return result
+
+  const user = getUser(result.data.id)
+  if (!result.success) return user
+
+  return user
+}
+```

.roo/rules-code/solid.md

@@ -0,0 +1,120 @@
+# solid.js
+
+## general
+
+- use `function` over const function expression
+- do not use default exports
+
+## use solid.js build-in components instead of react patterns
+
+### loops
+
+Instead of using `map()` inside JSX or manual `for` loops:
+
+- Prefer the `For` component from **solid-js** for list rendering.
+- Move repeating UI blocks into a dedicated function, defined just below the current component within the same file.
+
+### conditions
+
+Instead of adding conditional logic or early returns in React-like patterns:
+
+- Prefer using the `Show` component from solid-js for conditional rendering.
+- Place fallback component in a dedicated function, defined just below the current component within the same file.
+
+---
+
+## component classes
+
+### classMerge and classArr
+
+- **Standardize class organization** in Solid components using `classMerge` and `classArr` utility functions
+- **Always use `classMerge`** instead of template strings
+- **Group classes** by functional category:
+  ```tsx
+  ;[
+    "flex flex-col items-center justify-center", // layout
+    "min-h-screen", // sizing
+    "bg-gray-50 dark:bg-gray-900", // background
+    "p-4", // spacing
+  ]
+  ```
+- **Comment each group** with its purpose
+- **Order groups logically**:
+  - Layout/Positioning
+  - Sizing/Dimensions
+  - Backgrounds
+  - Borders/Shadows
+  - Typography
+  - Spacing/Margin/Padding
+  - Transitions/Animations
+  - State modifiers (hover/focus)
+- **Place props.class last** to enable proper override
+- Prefer `classArr` for static class lists without dynamic props
+- Use `classMerge` when dynamic class props are needed
+
+Incorrect Approach (String Templates):
+
+```tsx
+// ErrorPage.tsx
+<div class="flex flex-col items-center justify-center min-h-screen bg-gray-50 dark:bg-gray-900 p-4">
+```
+
+Correct Approach (ClassMerge + Grouped Arrays):
+
+```tsx
+import { classMerge } from "@/ui/utils/classMerge"
+
+<div class={classMerge(
+  "flex flex-col items-center justify-center", // layout
+  "min-h-screen", // sizing
+  "bg-gray-50 dark:bg-gray-900", // background
+  "p-4", // spacing
+  props.class,
+)}>
+```
+
+### text color classes
+
+Never use `text-gray-400`, `text-gray-500` or `text-gray-600` - use `text-muted-foreground` instead.
+
+---
+
+## component props
+
+### use and extend existing Interfaces
+
+Always include base utility types for exported general purpose components in "src/ui" folder:
+
+```ts
+import type { MayHaveChildren } from "@/ui/utils/MayHaveChildren"
+import type { MayHaveClassName } from "@/ui/utils/MayHaveClassName"
+
+export interface ComponentProps extends MayHaveClassName, MayHaveChildren {
+  // component-specific props
+}
+
+// usage example
+function MyComponent(p: ComponentProps) {}
+```
+
+if the component has an `icon` property have the props extend existing `MayHaveIcon` interface
+if the component has an `title` property have the props extend existing `MayHaveTitle` interface
+if the component has an `subtitle` property have the props extend existing `MayHaveSubtitle` interface
+
+### never use object deconstruction
+
+Always name the component properties, named `p`:
+
+```ts
+// bad
+function SessionButton({ session }: { session: UserSession }) {}
+
+// good
+function SessionButton(p: { session: UserSession }) {
+  // usage: how to access properties
+  p.session
+}
+```
+### use existing components defined in `src/ui`
+
+examples `ButtonIcon`