vibefast-cli 0.2.4 → 0.3.0

package/2/.claude/commands/update-tech-stack.md

@@ -0,0 +1,325 @@
+---
+allowed-tools: Read, Glob, Grep, Write, MultiEdit, TodoWrite, Bash
+description: Update tech stack documentation based on dependency changes and technical evolution
+---
+
+# Update Tech Stack Documentation
+
+**User Request:** $ARGUMENTS
+
+## Context
+
+- Project root: !`pwd`
+- Package.json: @package.json
+- Current tech doc: @.claude/docs/tech-stack.md
+- **Project Structure:** !`bash .claude/scripts/tree.sh`
+- Last modified: !`stat -f "%Sm" .claude/docs/tech-stack.md 2>/dev/null || echo "No existing document"`
+- Recent package changes: !`git diff HEAD~10 HEAD -- package.json 2>/dev/null | grep -E "^[+-]" | head -20 || echo "No recent changes"`
+
+## Goal
+
+Update the existing Tech Stack Documentation to reflect current technical state, dependency changes, new tools adoption, and infrastructure evolution. Maintain technical accuracy while documenting all changes.
+
+## Process
+
+### 1. Document Analysis
+
+- Read existing tech-stack.md thoroughly
+- Note documented versions and configurations
+- Understand current technical baseline
+- Identify sections that may need updates
+
+### 2. Technical Change Detection
+
+**Think deeply about technical evolution in the codebase.**
+
+Analyze for:
+
+- **Dependency Changes:** New packages, version updates, removals
+- **Framework Evolution:** Major version upgrades, breaking changes
+- **Tool Adoption:** New dev tools, linters, formatters, testing frameworks
+- **Infrastructure Shifts:** Deployment, hosting, monitoring changes
+- **Database Evolution:** Schema changes, new ORMs, migrations
+- **Integration Updates:** New APIs, services, authentication providers
+
+_Extended thinking helps identify cascading dependency updates, understand version compatibility issues, and recognize architectural implications of technical changes._
+
+### 3. Automated Comparison
+
+```bash
+# Compare current vs documented dependencies
+# Check for version mismatches
+# Identify new configuration files
+# Detect new tool configurations
+```
+
+### 4. Interactive Technical Q&A
+
+Ask targeted questions about:
+
+- Non-discoverable infrastructure changes
+- Deployment and hosting updates
+- New external service integrations
+- Workflow and process changes
+
+### 5. Update Documentation
+
+Update incrementally:
+
+- Preserve accurate technical information
+- Update version numbers precisely
+- Add new sections for major additions
+- Mark deprecated technologies
+
+### 6. Save and Verify
+
+- Suggest backup for major changes
+- Update CLAUDE.md commands if needed
+- Verify all versions are accurate
+
+## Technical Questions Template
+
+### 🔄 Version Updates & Dependencies
+
+**1. Which major dependencies have been updated?**
+
+Review your recent dependency changes:
+
+a) **Framework upgrades** (Next.js, React, etc.) with breaking changes  
+b) **Tool updates** (TypeScript, ESLint, etc.) requiring config changes  
+c) **New dependencies** added for features or development  
+d) **Removed packages** that are no longer needed  
+e) **All of the above** - Major technical overhaul
+
+**2. Have you changed your package manager or Node version?**
+
+a) **Same setup** - No changes to tooling  
+b) **Node upgrade** - Updated Node.js version  
+c) **Package manager switch** - Changed from npm/yarn/pnpm  
+d) **Monorepo adoption** - Moved to workspace setup
+
+### 🏗️ Infrastructure Evolution
+
+**3. Have your deployment or hosting arrangements changed?**
+
+Current deployment is documented as: [show from existing doc]
+
+a) **Same platform** - Just configuration updates  
+b) **Platform migration** - Moved to different provider  
+c) **Architecture change** - Serverless, containers, etc.  
+d) **Multi-region** - Expanded geographic deployment
+
+**4. Database or storage changes?**
+
+a) **Version upgrade** - Same DB, newer version  
+b) **Migration** - Switched database systems  
+c) **New caching** - Added Redis, Memcached, etc.  
+d) **Storage addition** - New file storage, CDN  
+e) **No changes** - Same setup as before
+
+### 🛠️ Development Workflow Updates
+
+**5. New development tools or practices?**
+
+Select all that apply:
+
+- [ ] New testing framework or strategy
+- [ ] Added code quality tools (linters, formatters)
+- [ ] CI/CD pipeline changes
+- [ ] Docker/containerization adoption
+- [ ] New build tools or bundlers
+- [ ] Performance monitoring tools
+
+**6. External service integrations?**
+
+Have you added or changed:
+
+a) **Payment processing** - New or updated provider  
+b) **Authentication** - Different auth service  
+c) **Email/SMS** - Communication service changes  
+d) **Monitoring** - New error tracking or analytics  
+e) **APIs** - Additional third-party integrations  
+f) **None** - Same external services
+
+### 🔐 Security & Compliance
+
+**7. Security tool adoption?**
+
+- [ ] Vulnerability scanning (Snyk, etc.)
+- [ ] Secret management changes
+- [ ] New authentication methods
+- [ ] Compliance tools (GDPR, etc.)
+- [ ] Security headers/policies
+- [ ] None of the above
+
+## Update Strategy
+
+### Version Precision
+
+```typescript
+// ❌ Outdated
+"next": "^13.0.0"
+
+// ✅ Current and precise
+"next": "14.2.5"
+```
+
+### Configuration Updates
+
+- Update all config examples to match current files
+- Include new configuration options
+- Remove deprecated settings
+- Add migration notes for breaking changes
+
+### New Technology Sections
+
+When adding major new tools:
+
+```markdown
+### [New Tool Category]
+
+**Tool:** [Name] [Version]
+**Purpose:** [Why it was adopted]
+**Configuration:** [Key settings]
+**Integration:** [How it connects with other tools]
+```
+
+## Document Update Areas
+
+### Always Check:
+
+1. **package.json changes**
+
+   ```bash
+   # Compare all dependencies
+   # Note version changes
+   # Identify new packages
+   ```
+
+2. **Configuration files**
+   - tsconfig.json updates
+   - New .config files
+   - Build tool configurations
+   - Linting rule changes
+
+3. **Development scripts**
+   - New npm/pnpm scripts
+   - Changed command purposes
+   - Removed scripts
+
+4. **Infrastructure files**
+   - Dockerfile changes
+   - CI/CD workflows
+   - Deployment configs
+   - Environment examples
+
+### Conditional Updates:
+
+- **Architecture:** Only if fundamental changes
+- **Conventions:** Only if standards changed
+
+## Execution Steps
+
+### 1. Start with Analysis
+
+```bash
+# Check current dependencies vs documented
+diff <(jq -r '.dependencies | keys[]' package.json | sort) \
+     <(grep -E '^\*\*.*:' .claude/docs/tech-stack.md | cut -d: -f1 | sed 's/\*//g' | sort)
+
+# Review recent dependency commits
+git log --oneline --grep="dep" --since="30 days ago"
+
+# Check for new config files
+find . -name "*.config.*" -newer .claude/docs/tech-stack.md 2>/dev/null
+```
+
+**Think deeply about:** "What technical decisions drove these changes? How do version updates affect the overall architecture? What new capabilities do these tools enable?"
+
+### 2. Interactive Q&A
+
+- Present technical questions clearly
+- Include current state from documentation
+- Wait for detailed responses
+
+### 3. Update Documentation
+
+Follow incremental approach:
+
+```markdown
+<!-- Version update example -->
+
+**Before:** React 18.2.0
+**After:** React 18.3.1 - Includes new compiler optimizations
+
+<!-- New tool example -->
+
+### Code Quality Tools
+
+**New Addition:**
+
+- **Biome:** 1.8.3 - Replaced ESLint and Prettier
+  - Faster performance (10x)
+  - Single configuration file
+  - Built-in formatting
+```
+
+### 4. Commands Update
+
+Update CLAUDE.md if new scripts discovered:
+
+```markdown
+### Development
+
+- `pnpm dev` - Start development server
+- `pnpm check` - NEW: Run Biome linting and formatting
+- `pnpm test:e2e` - NEW: Run Playwright tests
+```
+
+### 5. Save and Backup
+
+```bash
+# Optional backup
+cp .claude/docs/tech-stack.md .claude/docs/tech-stack.backup.md
+
+# Save updated document
+# Overwrite .claude/docs/tech-stack.md
+```
+
+## Key Principles
+
+### DO:
+
+- **Exact Versions:** Use precise version numbers from lock files
+- **Config Accuracy:** Match actual configuration files
+- **Change Rationale:** Explain why tools were adopted/changed
+- **Migration Notes:** Document breaking changes and updates
+- **Performance Impact:** Note improvements or concerns
+
+### DON'T:
+
+- **Generic Updates:** Avoid vague version ranges
+- **Assumption:** Verify every technical detail
+- **Old Information:** Remove outdated configurations
+- **Wishful Documentation:** Only document what exists
+- **Sensitive Data:** Never include secrets or keys
+
+## Output
+
+- **Format:** Markdown (`.md`)
+- **Location:** `.claude/docs/`
+- **Filename:** `tech-stack.md` (overwrites)
+- **Backup:** Suggest for major changes
+
+## Final Checklist
+
+1. ✅ Read existing tech-stack.md completely
+2. ✅ Analyze all dependency changes
+3. ✅ Check configuration file updates
+4. ✅ Review infrastructure changes
+5. ✅ Ask targeted technical questions
+6. ✅ Update with exact versions
+7. ✅ Include configuration examples
+8. ✅ Update CLAUDE.md commands
+9. ✅ Suggest backup if major changes
+10. ✅ Verify technical accuracy

package/2/.claude/docs/CONVEX_FEATURES_PLAN.md

@@ -0,0 +1,249 @@
+# Convex Features Demo Plan
+
+## Overview
+
+This plan outlines the implementation of a minimal todo application that demonstrates ALL Convex features defined in the schema. The app will showcase queries, mutations, actions, relationships, search, aggregates, triggers, and more.
+
+## Schema Features to Demonstrate
+
+### 1. **Core Models**
+
+- **Users**: Profile management, role-based access, soft deletion
+- **Todos**: CRUD operations, priorities, due dates, soft deletion
+- **Projects**: Project management, public/private visibility, archiving
+- **Tags**: Tag management with color coding
+- **Comments**: Nested comments with replies
+
+### 2. **Relationships**
+
+- 1:1 - User profile edges
+- 1:many - User→Todos, Project→Todos, Todo→Comments
+- Many:many - Todos↔Tags, Projects↔Members, Comments↔Replies
+
+### 3. **Advanced Features**
+
+- **Search**: Full-text search on todos (title/description)
+- **Aggregates**: Todo counts by user, project, status
+- **Triggers**: Auto-update aggregates, validation
+- **Soft Deletion**: Todos with deletionTime
+- **Indexes**: Optimized queries for filtering
+- **Pagination**: Todo lists with cursor-based pagination
+
+## Implementation Structure
+
+### Backend Files (`convex/`)
+
+#### 1. **todos.ts** - Todo CRUD
+
+- `list` - Paginated query with filters (status, project, tags)
+- `search` - Full-text search with filters
+- `get` - Single todo with relations
+- `create` - With validation, rate limiting
+- `update` - Patch updates with optimistic UI
+- `toggleComplete` - Quick status toggle
+- `delete` - Soft delete
+- `restore` - Undelete soft-deleted todos
+- `bulkDelete` - Batch operations
+- `reorder` - Drag-and-drop support
+
+#### 2. **projects.ts** - Project Management
+
+- `list` - User's projects (owned + member)
+- `get` - Project with members and todo count
+- `create` - With owner assignment
+- `update` - Name, description, visibility
+- `archive` - Soft archive
+- `addMember` - Add project member
+- `removeMember` - Remove project member
+- `leave` - Leave project as member
+- `transfer` - Transfer ownership
+
+#### 3. **tags.ts** - Tag System
+
+- `list` - User's tags with usage count
+- `create` - New tag with color
+- `update` - Rename/recolor
+- `delete` - Remove tag (cascade from todos)
+- `merge` - Merge two tags
+- `popular` - Most used tags
+
+#### 4. **todoComments.ts** - Comment System
+
+- `list` - Comments for a todo (nested)
+- `create` - Add comment
+- `reply` - Reply to comment
+- `update` - Edit comment
+- `delete` - Remove comment
+- `react` - Add reaction/emoji
+
+#### 5. **todoInternal.ts** - Internal Functions
+
+- `processOverdueTodos` - Mark overdue todos
+- `cleanupDeletedTodos` - Hard delete old soft-deleted
+- `calculateStats` - User/project statistics
+
+#### 6. **aggregates.ts** - Count Operations
+
+- Todo count by user
+- Todo count by project
+- Todo count by status
+- Tag usage count
+- Comment count per todo
+
+#### 7. **triggers.ts** - Database Triggers
+
+- Update aggregates on todo changes
+- Validate todo title length
+- Auto-assign creation timestamps
+- Cascade soft deletes
+
+### Frontend Structure (`src/`)
+
+#### 1. **Pages**
+
+- `/` - Dashboard with todo lists
+- `/projects` - Project management
+- `/projects/[id]` - Project detail with todos
+- `/tags` - Tag management
+- `/search` - Global search
+- `/settings` - User settings
+
+#### 2. **Components**
+
+- `TodoList` - Paginated list with filters
+- `TodoItem` - Single todo with actions
+- `TodoForm` - Create/edit todo
+- `TodoFilters` - Status, project, tag filters
+- `TodoSearch` - Search bar with results
+- `ProjectCard` - Project preview
+- `ProjectMembers` - Member management
+- `TagPicker` - Multi-select tags
+- `CommentThread` - Nested comments
+- `StatsWidget` - Aggregate displays
+
+#### 3. **Features to Showcase**
+
+- **Real-time Updates**: Live todo changes
+- **Optimistic UI**: Instant feedback
+- **Pagination**: Load more pattern
+- **Search**: Debounced full-text search
+- **Filters**: Combined filtering
+- **Drag & Drop**: Reorder todos
+- **Keyboard Shortcuts**: Quick actions
+- **Skeleton Loading**: Smooth loading states
+- **Error Handling**: User-friendly errors
+- **Rate Limiting**: Prevent spam
+
+## Key Patterns to Demonstrate
+
+### 1. **Authentication Context**
+
+```typescript
+// Use pre-loaded ctx.user
+handler: async (ctx, args) => {
+  await ctx.user.patch({ lastActive: Date.now() });
+};
+```
+
+### 2. **Edge Traversal**
+
+```typescript
+// Efficient relationship queries
+const todos = await user
+  .edge('todos')
+  .filter((q) => q.eq(q.field('completed'), false))
+  .order('desc')
+  .take(10);
+```
+
+### 3. **Aggregates with Triggers**
+
+```typescript
+// O(log n) counts
+const todoCount = await aggregateTodosByUser.count(ctx, {
+  namespace: userId,
+});
+```
+
+### 4. **Search with Filters**
+
+```typescript
+// Full-text + field filters
+const results = await ctx
+  .table('todos')
+  .search('search_title_description', (q) =>
+    q.search('title', query).eq('userId', userId).eq('completed', false),
+  )
+  .take(20);
+```
+
+### 5. **Pagination with Streams**
+
+```typescript
+// Complex filters with consistent pages
+const stream = await stream(ctx.db, schema)
+  .query('todos')
+  .filterWith(async (todo) => {
+    const tags = await todo.edge('tags');
+    return tags.some((t) => selectedTags.includes(t._id));
+  })
+  .paginate(args.paginationOpts);
+```
+
+## UI/UX Approach
+
+### Design Principles
+
+- **Minimal & Clean**: Focus on functionality over aesthetics
+- **Compact Layout**: Dense information display
+- **Instant Feedback**: Optimistic updates everywhere
+- **Keyboard First**: Shortcuts for power users
+- **Mobile Friendly**: Responsive design
+
+### Component Structure
+
+- Use shadcn/ui components exclusively
+- Minimal custom styling
+- Focus on demonstrating Convex features
+- Clear labeling of feature demos
+
+## Testing Checklist
+
+- [ ] All CRUD operations work
+- [ ] Real-time updates across sessions
+- [ ] Search returns relevant results
+- [ ] Filters combine correctly
+- [ ] Pagination loads smoothly
+- [ ] Aggregates update instantly
+- [ ] Soft delete/restore works
+- [ ] Rate limiting prevents spam
+- [ ] Error messages are helpful
+- [ ] Loading states are smooth
+- [ ] Mobile layout is usable
+- [ ] Keyboard shortcuts work
+
+## Development Order
+
+1. **Phase 1**: Core Todo CRUD
+   - Basic todo operations
+   - Real-time updates
+   - Soft deletion
+
+2. **Phase 2**: Projects & Relationships
+   - Project CRUD
+   - Todo-project association
+   - Member management
+
+3. **Phase 3**: Tags & Search
+   - Tag system
+   - Full-text search
+   - Combined filters
+
+4. **Phase 4**: Comments & Aggregates
+   - Comment threads
+   - Count displays
+   - Trigger setup
+
+5. **Phase 5**: Polish
+   - Loading states
+   - Error handling (toast)

package/2/.claude/docs/project-status.md

@@ -0,0 +1,25 @@
+## Project Status: Pre-MVP
+
+**Current Stage**: Pre-MVP (highest velocity to ship)
+
+### DO Care About (Production-Ready Foundation)
+
+- **Security**: Authentication, authorization, session management
+- **Data Validation**: Zod schemas for all inputs
+- **Error Handling**: User-friendly error messages and proper error states
+- **Type Safety**: Full TypeScript coverage and type-safe APIs
+- **Data Integrity**: Proper database constraints and relationships
+- **Code Patterns**: Follow existing patterns in the codebase
+- **Core Features**: Complete implementation including error states
+- **API Security**: Rate limiting, protected procedures, userId filters
+
+### DO NOT Care About (Skip for Velocity)
+
+- **Breaking Changes**: Not deployed yet, refactor freely
+- **Unit Testing**: Unless specifically requested
+- **Performance Optimization**: Unless blocking functionality
+- **Backward Compatibility**: No existing users
+- **Migration Scripts**: No production data yet
+- **Extensive Documentation**: Unless requested
+- **Edge Cases**: That don't block core functionality
+- **Premature Abstractions**: Build what's needed now

package/2/.claude/docs/project-structure.md

@@ -0,0 +1,7 @@
+# Project Structure
+
+_Last Updated: 2025-07-27_
+
+```
+
+```