initial commit

.github/copilot-cli-instructions.md

@@ -0,0 +1,440 @@
+# GitHub Copilot CLI Instructions for bDS
+
+Quick reference for using GitHub Copilot CLI (`gh copilot`) with this Electron + TypeScript + SQLite project.
+
+## Project Context for CLI Queries
+
+When asking Copilot CLI for help, provide this context for better responses:
+
+```
+This is an Electron app using TypeScript, React, Drizzle ORM, and @libsql/client for SQLite.
+```
+
+---
+
+## Common CLI Patterns
+
+### Build & Development
+
+```bash
+# Ask how to run in development
+gh copilot suggest "how to run electron app in dev mode with vite HMR"
+
+# Ask about TypeScript compilation
+gh copilot suggest "compile typescript for electron main process with tsconfig"
+
+# Build commands for this project
+npm run build:main    # TypeScript -> JavaScript for main process
+npm run build:renderer # Vite build for React renderer
+npm run build         # Both
+npm start            # Launch Electron
+```
+
+### Database Operations
+
+```bash
+# Generate Drizzle migrations
+gh copilot suggest "generate drizzle orm migration for sqlite"
+
+# Query patterns
+gh copilot suggest "drizzle orm query to select with where clause typescript"
+
+# Turso sync
+gh copilot suggest "sync local sqlite with turso remote database libsql"
+```
+
+### Electron Commands
+
+```bash
+# IPC patterns
+gh copilot suggest "electron ipc invoke handler with typescript types"
+
+# Window management
+gh copilot suggest "electron create browser window with preload script"
+
+# Menu creation
+gh copilot suggest "electron application menu with keyboard shortcuts"
+```
+
+---
+
+## TypeScript Quick Fixes
+
+### Type Errors
+
+```bash
+# When you see "Type X is not assignable to type Y"
+gh copilot explain "typescript error Type X is not assignable to type Y"
+
+# For generic type issues
+gh copilot suggest "typescript generic function that returns same type as input"
+
+# Promise/async issues
+gh copilot suggest "typescript async function return type Promise"
+```
+
+### Common Patterns
+
+```bash
+# Discriminated unions
+gh copilot suggest "typescript discriminated union for status types"
+
+# Type guards
+gh copilot suggest "typescript type guard function to narrow union type"
+
+# Utility types
+gh copilot suggest "typescript Pick Omit Partial for interface modification"
+```
+
+---
+
+## SQLite & Drizzle Queries
+
+### Schema Definition
+
+```bash
+# Create new table
+gh copilot suggest "drizzle orm sqlite table schema with text integer columns"
+
+# Add index
+gh copilot suggest "drizzle orm create index on sqlite table"
+
+# Relations
+gh copilot suggest "drizzle orm one to many relation sqlite"
+```
+
+### Query Building
+
+```bash
+# Select with conditions
+gh copilot suggest "drizzle orm select where equals and order by"
+
+# Insert with returning
+gh copilot suggest "drizzle orm insert returning inserted row"
+
+# Update with conditions
+gh copilot suggest "drizzle orm update set where condition"
+
+# Transaction
+gh copilot suggest "drizzle orm transaction with multiple operations"
+```
+
+### LibSQL Specifics
+
+```bash
+# Local file database
+gh copilot suggest "libsql client connect to local sqlite file"
+
+# Remote Turso connection
+gh copilot suggest "libsql client connect turso with auth token"
+
+# Execute multiple statements
+gh copilot suggest "libsql execute multiple sql statements batch"
+```
+
+---
+
+## Sync Implementation
+
+### Conflict Detection
+
+```bash
+gh copilot suggest "detect sync conflicts using checksums typescript"
+gh copilot suggest "last-write-wins conflict resolution pattern"
+gh copilot suggest "vector clock for distributed sync"
+```
+
+### Offline Queue
+
+```bash
+gh copilot suggest "queue offline operations for later sync typescript"
+gh copilot suggest "exponential backoff retry logic async"
+gh copilot suggest "detect online offline status in electron"
+```
+
+### Sync Status
+
+```bash
+gh copilot suggest "track sync status pending synced error per record"
+gh copilot suggest "sync log table for audit trail"
+```
+
+---
+
+## React & Zustand
+
+### Store Patterns
+
+```bash
+gh copilot suggest "zustand store with typescript typed actions"
+gh copilot suggest "zustand selector to prevent unnecessary rerenders"
+gh copilot suggest "zustand persist middleware for local storage"
+```
+
+### Component Patterns
+
+```bash
+gh copilot suggest "react component with zustand store hook"
+gh copilot suggest "react useEffect cleanup for ipc listener"
+gh copilot suggest "react context provider with typescript"
+```
+
+---
+
+## Electron Security
+
+```bash
+# Secure IPC
+gh copilot suggest "electron context bridge expose api safely"
+
+# Input validation
+gh copilot suggest "validate ipc handler input zod typescript"
+
+# Content Security Policy
+gh copilot suggest "electron content security policy meta tag"
+```
+
+---
+
+## File Operations
+
+### Markdown with Frontmatter
+
+```bash
+gh copilot suggest "read markdown file with yaml frontmatter gray-matter"
+gh copilot suggest "write markdown file with yaml frontmatter node"
+gh copilot suggest "parse yaml frontmatter to typescript type"
+```
+
+### Media Files
+
+```bash
+gh copilot suggest "copy file to destination directory nodejs"
+gh copilot suggest "get image dimensions from file nodejs"
+gh copilot suggest "calculate file checksum md5 nodejs"
+```
+
+### Sidecar Pattern
+
+```bash
+gh copilot suggest "json sidecar metadata file for binary asset"
+gh copilot suggest "read write json file atomic operation"
+```
+
+---
+
+## Error Handling
+
+```bash
+# Custom errors
+gh copilot suggest "typescript custom error class with error code"
+
+# Result types
+gh copilot suggest "typescript result type success or error pattern"
+
+# Async error handling
+gh copilot suggest "try catch async await with typed error"
+```
+
+---
+
+## Test-Driven Development (TDD)
+
+**This project requires TDD. Write tests BEFORE implementation.**
+
+### TDD Workflow
+
+```bash
+# Step 1: Write failing test first
+gh copilot suggest "vitest test for function that does X should return Y"
+
+# Step 2: Make test pass with minimal code
+gh copilot suggest "minimal implementation to make vitest test pass"
+
+# Step 3: Refactor while keeping tests green
+gh copilot suggest "refactor function for readability typescript"
+```
+
+### Test Commands
+
+```bash
+npm run test           # Run all tests once
+npm run test:watch     # Watch mode (re-run on changes)
+npm run test:coverage  # Generate coverage report
+npm run test:ui        # Open Vitest UI in browser
+```
+
+### Writing Tests
+
+```bash
+# Create unit test
+gh copilot suggest "vitest unit test for typescript async function"
+
+# Test with mocks
+gh copilot suggest "vitest mock module fs promises typescript"
+
+# Test event emitters
+gh copilot suggest "vitest test eventemitter emit and listen"
+
+# Test error cases
+gh copilot suggest "vitest test async function throws error"
+```
+
+### Mock Patterns
+
+```bash
+# Mock database
+gh copilot suggest "vitest mock drizzle orm database connection"
+
+# Mock file system
+gh copilot suggest "vitest mock fs promises readFile writeFile"
+
+# Mock Electron
+gh copilot suggest "vitest mock electron app ipcMain"
+
+# Factory functions
+gh copilot suggest "typescript factory function create test data with overrides"
+```
+
+### Coverage
+
+```bash
+# Check coverage
+gh copilot suggest "vitest coverage v8 configuration"
+
+# Coverage thresholds
+gh copilot suggest "vitest minimum coverage threshold configuration"
+```
+
+### Testing Specific Scenarios
+
+```bash
+# Task management tests
+gh copilot suggest "vitest test async task queue with progress callback"
+
+# Sync engine tests
+gh copilot suggest "vitest test sync conflict detection by checksum"
+
+# Post engine tests
+gh copilot suggest "vitest test markdown frontmatter parse and serialize"
+
+# Media tests
+gh copilot suggest "vitest test file checksum calculation md5"
+```
+
+---
+
+## Git Operations
+
+```bash
+# Commits
+gh copilot suggest "git commit message for feature typescript"
+
+# Branching
+gh copilot suggest "git branch naming convention feature bugfix"
+
+# Stashing
+gh copilot suggest "git stash changes and apply later"
+```
+
+---
+
+## Project-Specific Commands
+
+### Quick Reference
+
+| Task | Command |
+|------|---------|
+| Install deps | `npm install` |
+| Dev mode | `npm run dev` (runs Vite + TSC watch) |
+| Build all | `npm run build` |
+| Start app | `npm start` |
+| Run tests | `npm run test` |
+| Watch tests | `npm run test:watch` |
+| Coverage | `npm run test:coverage` |
+| Build main only | `npm run build:main` |
+| Build renderer only | `npm run build:renderer` |
+
+### File Locations
+
+| What | Where |
+|------|-------|
+| Electron main | `src/main/` |
+| React renderer | `src/renderer/` |
+| Database schema | `src/main/database/schema.ts` |
+| Engine classes | `src/main/engine/` |
+| IPC handlers | `src/main/ipc/handlers.ts` |
+| React components | `src/renderer/components/` |
+| State store | `src/renderer/store/appStore.ts` |
+
+### Adding a Feature Checklist
+
+```bash
+# 1. Schema (if new data)
+gh copilot suggest "add column to drizzle sqlite table"
+
+# 2. Engine method
+gh copilot suggest "engine class method with event emitter typescript"
+
+# 3. IPC handler
+gh copilot suggest "electron ipc handle invoke pattern"
+
+# 4. Preload exposure
+gh copilot suggest "electron preload contextBridge expose"
+
+# 5. Store action
+gh copilot suggest "zustand action to update state"
+
+# 6. UI component
+gh copilot suggest "react component call electron api"
+```
+
+---
+
+## Troubleshooting
+
+### Common Issues
+
+```bash
+# Module not found
+gh copilot explain "cannot find module typescript error electron"
+
+# IPC not working
+gh copilot explain "electron ipc invoke not receiving response"
+
+# Database locked
+gh copilot explain "sqlite database is locked error"
+
+# Build fails
+gh copilot explain "vite build error cannot resolve module"
+```
+
+### Debugging
+
+```bash
+# Enable source maps
+gh copilot suggest "typescript source maps for electron debugging"
+
+# DevTools
+gh copilot suggest "open chrome devtools in electron app"
+
+# Logging
+gh copilot suggest "electron log to file in main process"
+```
+
+---
+
+## Best Practices Summary
+
+When asking Copilot CLI for code in this project:
+
+1. **Specify TypeScript** - Always mention "typescript" for typed responses
+2. **Mention Electron context** - "main process" or "renderer process"
+3. **Reference Drizzle** - Use "drizzle orm" not "raw sql"
+4. **Async patterns** - Request "async/await" not callbacks
+5. **Type safety** - Ask for "typed" or "with types" versions
+
+Example well-formed query:
+```bash
+gh copilot suggest "typescript async function to update drizzle orm record with transaction in electron main process"
+```