create-aron-app 0.1.6 → 0.1.8

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

@@ -1,268 +0,0 @@
----
-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

@@ -1,64 +0,0 @@
----
-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.