create-aron-app 0.1.0 → 0.1.1

package/templates/_base/.cursor/agents/skills/shadcn/rules/icons.md

@@ -0,0 +1,101 @@
+# Icons
+
+**Always use the project's configured `iconLibrary` for imports.** Check the `iconLibrary` field from project context: `lucide` → `lucide-react`, `tabler` → `@tabler/icons-react`, etc. Never assume `lucide-react`.
+
+---
+
+## Icons in Button use data-icon attribute
+
+Add `data-icon="inline-start"` (prefix) or `data-icon="inline-end"` (suffix) to the icon. No sizing classes on the icon.
+
+**Incorrect:**
+
+```tsx
+<Button>
+  <SearchIcon className="mr-2 size-4" />
+  Search
+</Button>
+```
+
+**Correct:**
+
+```tsx
+<Button>
+  <SearchIcon data-icon="inline-start"/>
+  Search
+</Button>
+
+<Button>
+  Next
+  <ArrowRightIcon data-icon="inline-end"/>
+</Button>
+```
+
+---
+
+## No sizing classes on icons inside components
+
+Components handle icon sizing via CSS. Don't add `size-4`, `w-4 h-4`, or other sizing classes to icons inside `Button`, `DropdownMenuItem`, `Alert`, `Sidebar*`, or other shadcn components. Unless the user explicitly asks for custom icon sizes.
+
+**Incorrect:**
+
+```tsx
+<Button>
+  <SearchIcon className="size-4" data-icon="inline-start" />
+  Search
+</Button>
+
+<DropdownMenuItem>
+  <SettingsIcon className="mr-2 size-4" />
+  Settings
+</DropdownMenuItem>
+```
+
+**Correct:**
+
+```tsx
+<Button>
+  <SearchIcon data-icon="inline-start" />
+  Search
+</Button>
+
+<DropdownMenuItem>
+  <SettingsIcon />
+  Settings
+</DropdownMenuItem>
+```
+
+---
+
+## Pass icons as component objects, not string keys
+
+Use `icon={CheckIcon}`, not a string key to a lookup map.
+
+**Incorrect:**
+
+```tsx
+const iconMap = {
+  check: CheckIcon,
+  alert: AlertIcon,
+}
+
+function StatusBadge({ icon }: { icon: string }) {
+  const Icon = iconMap[icon]
+  return <Icon />
+}
+
+<StatusBadge icon="check" />
+```
+
+**Correct:**
+
+```tsx
+// Import from the project's configured iconLibrary (e.g. lucide-react, @tabler/icons-react).
+import { CheckIcon } from "lucide-react"
+
+function StatusBadge({ icon: Icon }: { icon: React.ComponentType }) {
+  return <Icon />
+}
+
+<StatusBadge icon={CheckIcon} />
+```

package/templates/_base/.cursor/agents/skills/shadcn/rules/styling.md

@@ -0,0 +1,162 @@
+# Styling & Customization
+
+See [customization.md](../customization.md) for theming, CSS variables, and adding custom colors.
+
+## Contents
+
+- Semantic colors
+- Built-in variants first
+- className for layout only
+- No space-x-* / space-y-*
+- Prefer size-* over w-* h-* when equal
+- Prefer truncate shorthand
+- No manual dark: color overrides
+- Use cn() for conditional classes
+- No manual z-index on overlay components
+
+---
+
+## Semantic colors
+
+**Incorrect:**
+
+```tsx
+<div className="bg-blue-500 text-white">
+  <p className="text-gray-600">Secondary text</p>
+</div>
+```
+
+**Correct:**
+
+```tsx
+<div className="bg-primary text-primary-foreground">
+  <p className="text-muted-foreground">Secondary text</p>
+</div>
+```
+
+---
+
+## No raw color values for status/state indicators
+
+For positive, negative, or status indicators, use Badge variants, semantic tokens like `text-destructive`, or define custom CSS variables — don't reach for raw Tailwind colors.
+
+**Incorrect:**
+
+```tsx
+<span className="text-emerald-600">+20.1%</span>
+<span className="text-green-500">Active</span>
+<span className="text-red-600">-3.2%</span>
+```
+
+**Correct:**
+
+```tsx
+<Badge variant="secondary">+20.1%</Badge>
+<Badge>Active</Badge>
+<span className="text-destructive">-3.2%</span>
+```
+
+If you need a success/positive color that doesn't exist as a semantic token, use a Badge variant or ask the user about adding a custom CSS variable to the theme (see [customization.md](../customization.md)).
+
+---
+
+## Built-in variants first
+
+**Incorrect:**
+
+```tsx
+<Button className="border border-input bg-transparent hover:bg-accent">
+  Click me
+</Button>
+```
+
+**Correct:**
+
+```tsx
+<Button variant="outline">Click me</Button>
+```
+
+---
+
+## className for layout only
+
+Use `className` for layout (e.g. `max-w-md`, `mx-auto`, `mt-4`), **not** for overriding component colors or typography. To change colors, use semantic tokens, built-in variants, or CSS variables.
+
+**Incorrect:**
+
+```tsx
+<Card className="bg-blue-100 text-blue-900 font-bold">
+  <CardContent>Dashboard</CardContent>
+</Card>
+```
+
+**Correct:**
+
+```tsx
+<Card className="max-w-md mx-auto">
+  <CardContent>Dashboard</CardContent>
+</Card>
+```
+
+To customize a component's appearance, prefer these approaches in order:
+1. **Built-in variants** — `variant="outline"`, `variant="destructive"`, etc.
+2. **Semantic color tokens** — `bg-primary`, `text-muted-foreground`.
+3. **CSS variables** — define custom colors in the global CSS file (see [customization.md](../customization.md)).
+
+---
+
+## No space-x-* / space-y-*
+
+Use `gap-*` instead. `space-y-4` → `flex flex-col gap-4`. `space-x-2` → `flex gap-2`.
+
+```tsx
+<div className="flex flex-col gap-4">
+  <Input />
+  <Input />
+  <Button>Submit</Button>
+</div>
+```
+
+---
+
+## Prefer size-* over w-* h-* when equal
+
+`size-10` not `w-10 h-10`. Applies to icons, avatars, skeletons, etc.
+
+---
+
+## Prefer truncate shorthand
+
+`truncate` not `overflow-hidden text-ellipsis whitespace-nowrap`.
+
+---
+
+## No manual dark: color overrides
+
+Use semantic tokens — they handle light/dark via CSS variables. `bg-background text-foreground` not `bg-white dark:bg-gray-950`.
+
+---
+
+## Use cn() for conditional classes
+
+Use the `cn()` utility from the project for conditional or merged class names. Don't write manual ternaries in className strings.
+
+**Incorrect:**
+
+```tsx
+<div className={`flex items-center ${isActive ? "bg-primary text-primary-foreground" : "bg-muted"}`}>
+```
+
+**Correct:**
+
+```tsx
+import { cn } from "@/lib/utils"
+
+<div className={cn("flex items-center", isActive ? "bg-primary text-primary-foreground" : "bg-muted")}>
+```
+
+---
+
+## No manual z-index on overlay components
+
+`Dialog`, `Sheet`, `Drawer`, `AlertDialog`, `DropdownMenu`, `Popover`, `Tooltip`, `HoverCard` handle their own stacking. Never add `z-50` or `z-[999]`.

package/templates/_base/.cursor/commands/pr.md

@@ -0,0 +1,7 @@
+Create a pull request for the current changes.
+
+1. Look at the staged and unstaged changes with `git diff`
+2. Write a clear commit message based on what changed
+3. Commit and push to the current branch
+4. Use `gh pr create` to open a pull request with title/description
+5. Return the PR URL when done

package/templates/_base/.cursor/rules/api_architecture.mdc

@@ -0,0 +1,268 @@
+---
+description: Backend architecture overview for the Convex API. Covers folder structure, schema design patterns, function conventions, and getting started steps.
+globs: apps/api/**/*.ts
+---
+
+# Backend API Architecture
+
+This is the Convex backend located in `apps/api/`. It uses `convex-ents` for relational data modeling and `zQuery`/`zMutation` wrappers from `convex-helpers` for all public functions.
+
+## Folder Structure
+
+```
+apps/api/
+├── <entity>/
+│   ├── schema.ts   # Ent definition (table shape + edges + indexes)
+│   ├── types.ts    # Zod schemas and TypeScript types
+│   └── crud.ts     # CRUD operations (GET → UPDATE → CREATE → DELETE)
+├── schema.ts       # Main schema — spreads all entity ent objects
+├── types.ts        # Shared context types (QueryCtx, MutationCtx, Ent<T>)
+└── functions.ts    # zQuery / zMutation wrappers using convex-ents
+```
+
+### Example: `todos/`
+
+The `todos/` directory is the canonical example of how to structure a new entity:
+
+```
+apps/api/todos/
+├── schema.ts   # todoEnts — defines the todos table
+├── types.ts    # CreateTodo, UpdateTodo Zod types
+└── crud.ts     # getTodo, listTodos, updateTodo, createTodo, deleteTodo
+```
+
+## Adding a New Entity
+
+1. Create `apps/api/<entity>/schema.ts` — define the ent and export `<entity>Ents`
+2. Create `apps/api/<entity>/types.ts` — define Zod schemas and TypeScript types
+3. Create `apps/api/<entity>/crud.ts` — implement CRUD using `zQuery`/`zMutation`
+4. Spread the new ent in `apps/api/schema.ts`:
+
+```typescript
+import { todoEnts } from "@/api/todos/schema";
+import { entityEnts } from "@/api/<entity>/schema";
+import { defineEntSchema, getEntDefinitions } from "convex-ents";
+
+const schema = defineEntSchema({
+  ...todoEnts,
+  ...entityEnts,
+});
+
+export default schema;
+export const entDefinitions = getEntDefinitions(schema);
+```
+
+## Schema Design Patterns
+
+### Ent Definitions (`schema.ts`)
+
+```typescript
+import { v } from "convex/values";
+import { defineEnt } from "convex-ents";
+
+export const entityEnts = {
+  entities: defineEnt({
+    title: v.string(),
+    userId: v.string(),
+    isCompleted: v.boolean(),
+  })
+    .edge("relatedEntity")
+    .index("by_user_id", ["userId"]),
+};
+```
+
+- Export as `{ tableName: defineEnt({...}) }` objects
+- Always add indexes for fields you query by
+- Name indexes `by_<field>` or `by_<field1>_and_<field2>`
+
+### Types (`types.ts`)
+
+```typescript
+import { z } from "zod";
+
+export type CreateEntity = z.infer<typeof CreateEntity>;
+export const CreateEntity = z.object({
+  title: z.string().min(1),
+  userId: z.string(),
+});
+```
+
+- All Zod schemas go here, not in schema.ts
+- Use `zodToConvex()` from `convex-helpers/server/zod` when you need a Convex validator from a Zod schema
+
+### CRUD (`crud.ts`)
+
+Functions are always ordered: **GET → UPDATE → CREATE → DELETE**
+
+```typescript
+import { zMutation, zQuery } from "@/api/functions";
+import { zid } from "convex-helpers/server/zod";
+import { z } from "zod";
+
+export const getEntity = zQuery({
+  args: { entityId: zid("entities") },
+  handler: async (ctx, args) => ctx.table("entities").getX(args.entityId),
+});
+
+export const listEntities = zQuery({
+  args: { userId: z.string() },
+  handler: async (ctx, args) =>
+    ctx.table("entities", "by_user_id", (q) => q.eq("userId", args.userId)),
+});
+
+export const updateEntity = zMutation({
+  args: { entityId: zid("entities"), title: z.string().optional() },
+  handler: async (ctx, args) => {
+    const { entityId, ...updates } = args;
+    const entity = await ctx.table("entities").getX(entityId);
+    return entity.patch(updates);
+  },
+});
+
+export const createEntity = zMutation({
+  args: { title: z.string().min(1), userId: z.string() },
+  handler: async (ctx, args) =>
+    ctx.table("entities").insert({ title: args.title, userId: args.userId, isCompleted: false }),
+});
+
+export const deleteEntity = zMutation({
+  args: { entityId: zid("entities") },
+  handler: async (ctx, args) => {
+    const entity = await ctx.table("entities").getX(args.entityId);
+    await entity.delete();
+  },
+});
+```
+
+## Documentation Style
+
+- **NEVER** add JSDoc or any comments before exported function definitions
+- Function names should be self-documenting
+- Only add inline comments for complex business logic that can't be expressed through code alone
+- NO comments like `// Get entity by ID` or `// Update entity` above functions
+
+## Ent Methods
+
+Prefer the throwing variants when you expect the entity to exist:
+
+| Use | When |
+|---|---|
+| `getX(id)` | Entity must exist — throws if not found |
+| `get(id)` | Entity may not exist — returns `null` |
+| `uniqueX(...)` | Index query must return exactly one result |
+| `unique(...)` | Index query may return zero results |
+| `firstX(...)` | Query must return at least one result |
+| `first(...)` | Query may return zero results |
+
+```typescript
+// Good — entity is expected to exist
+const todo = await ctx.table("todos").getX(todoId);
+return todo.patch(updates);
+
+// Good — entity may not exist
+const entity = await ctx.table("entities").get(entityId);
+if (!entity) {
+  throw new ConvexError("Entity not found");
+}
+
+// Bad — redundant null-check on getX result
+const todo = await ctx.table("todos").get(todoId);
+if (!todo) {
+  throw new ConvexError("Todo not found");
+}
+```
+
+## Error Handling
+
+- Use `ConvexError` from `convex/values` for all business logic errors
+- Trust `getX()` and `uniqueX()` to throw — don't add redundant null checks after them
+- Only add explicit null checks when using `get()` or `first()`
+- Keep error messages concise and actionable
+
+```typescript
+import { ConvexError } from "convex/values";
+
+// validate before the DB operation
+if (count <= 0) {
+  throw new ConvexError("Limit reached");
+}
+```
+
+## Common Patterns
+
+### Edge Operations
+
+```typescript
+// Load a related entity
+const related = await entity.edge("relatedEntity");
+
+// Add to an edge collection
+await entity.patch({
+  relation: { add: [relatedId] },
+});
+
+// Remove from an edge collection
+await entity.patch({
+  relation: { remove: [relatedId] },
+});
+```
+
+### Returning an Entity with Edges
+
+```typescript
+const related = await entity.edge("relatedEntity");
+return { ...entity, related };
+```
+
+### Standard Update Pattern
+
+```typescript
+const { entityId, ...updates } = args;
+const entity = await ctx.table("entities").getX(entityId);
+return entity.patch(updates);
+```
+
+### Index Queries
+
+```typescript
+// Query by named index
+return ctx.table("entities", "by_user_id", (q) =>
+  q.eq("userId", args.userId)
+);
+
+// Query with a filter (use indexes instead where possible)
+return ctx
+  .table("entities")
+  .filter((q) => q.eq(q.field("fieldName"), value))
+  .first();
+```
+
+## Validation Helpers
+
+- Validation functions belong in the shared `@/utils/` package
+- Keep CRUD files focused solely on database operations
+- Reuse validators across multiple entities rather than duplicating logic
+
+## Getting Started
+
+### 1. Install dependencies
+
+```bash
+bun install
+```
+
+### 2. Start the Convex dev server
+
+```bash
+npx convex dev
+```
+
+This pushes the schema and regenerates types in `_generated/`.
+
+### 3. Configure environment
+
+Copy `.env.local.example` to `.env.local` and fill in:
+- `CONVEX_DEPLOYMENT` — from Convex dashboard
+- `NEXT_PUBLIC_CONVEX_URL` — from Convex dashboard
+- `NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY` — from Clerk dashboard
+- `CLERK_SECRET_KEY` — from Clerk dashboard

package/templates/_base/.cursor/rules/coding_standards.mdc

@@ -0,0 +1,64 @@
+---
+description: Project-wide coding standards covering import ordering, naming conventions, code style, and testing policy. Apply across all TypeScript/TSX files.
+globs: **/*.ts,**/*.tsx
+---
+
+# Coding Standards
+
+## Naming Conventions
+
+### Functions
+- Use verb + noun: `getEntity`, `updateEntity`, `createEntity`, `deleteEntity`
+- Be specific when needed: `getEntityByEmail`, `updateEntityField`
+- Avoid abbreviations unless widely understood
+- Avoid verbose qualifiers: prefer `updateEntity` over `updateEntityCoreDetails`
+
+### Fields
+- `camelCase` for all field names
+- Use `userId` — not `clerkId` or other provider-specific names
+
+### Variables
+- Keep names concise and descriptive
+- Use singular for single items (`todo`, `entity`) and plural for collections (`todos`, `entities`)
+- Destructure to extract IDs: `const { entityId, ...updates } = args;`
+
+## Code Style
+
+### Formatting
+- Single blank line between functions
+- No blank lines at the start or end of a function body
+- 2-space indentation
+- Trailing commas in multi-line arrays and objects
+
+### Conditional Logic
+
+Prefer concise conditionals — avoid unnecessary intermediate variables:
+
+```typescript
+// Good
+const count = entity.limit ?? 0;
+if (count <= 0) {
+  throw new ConvexError("Limit reached");
+}
+
+// Bad
+const remaining = entity.limit ?? 0;
+if (!entity.limit || entity.limit <= 0) {
+  throw new ConvexError("Limit reached");
+}
+```
+
+### Async / Await
+- Always `await` async operations — never fire-and-forget unless intentional
+- Chain operations when it improves readability
+- Use `Promise.all()` for independent parallel operations
+
+### Validation
+- Validate business rules before any database operation
+- Centralise reusable validation in `@/utils/`
+- Throw `ConvexError` with clear, actionable messages
+- Keep CRUD files thin — validation logic belongs in utils
+
+## Testing
+
+Test files **should not** be created unless explicitly requested. Focus on implementation quality over test coverage.