@eskoubar95/spec 0.1.0 → 0.1.3

package/template/.cursor/rules/30-database.mdc

@@ -0,0 +1,183 @@
+---
+title: Database Patterns
+description: Database patterns - applies when database is detected
+owner: sdd-system
+severity: warn
+globs: "**/migrations/**, **/supabase/**, **/prisma/**"
+alwaysApply: false
+activation:
+  projectTypes: [web-app, api-service]
+  projectSizes: [small, medium, large, enterprise]
+  projectPhases: [initialization, expansion, maintenance, migration, legacy]
+  technologies: [postgres, mysql, mongodb, supabase, prisma]
+  requires: [10-engineering]
+---
+
+# Database Patterns
+
+## Purpose
+
+Database patterns for schema design, migrations, queries, ORM patterns, and raw SQL patterns. Applies when database work is detected (PostgreSQL, MySQL, MongoDB, Supabase, Prisma, etc.).
+
+## Principles
+
+- **Schema-First**: Design schema before writing queries
+- **Migration-Based**: All schema changes via migrations
+- **Index Hot Paths**: Index frequently queried columns
+- **RLS (Row Level Security)**: Enable RLS on user-facing tables
+- **Backup Strategy**: Regular backups, tested restore process
+
+## Schema Design
+
+**Table Organization:**
+- Group related tables
+- Use consistent naming (snake_case or camelCase)
+- Document table purposes
+- Define relationships explicitly
+
+**Column Design:**
+- Use appropriate data types
+- Set NOT NULL where appropriate
+- Use defaults where sensible
+- Add indexes for foreign keys
+
+**Relationships:**
+- One-to-many: Foreign key in child table
+- Many-to-many: Junction table
+- One-to-one: Foreign key in either table
+
+## Migrations
+
+**Migration Best Practices:**
+- All schema changes via migrations
+- Versioned migrations (timestamped)
+- Never edit existing migrations
+- Test migrations on staging first
+- Include rollback strategy
+
+**Migration Structure:**
+```
+migrations/
+  20240101000000_create_users_table.sql
+  20240102000000_add_email_to_users.sql
+  20240103000000_create_posts_table.sql
+```
+
+**Migration Guidelines:**
+- One logical change per migration
+- Include both up and down migrations
+- Test migrations on sample data
+- Document breaking changes
+
+## Queries
+
+**Query Patterns:**
+- Use parameterized queries (prevent SQL injection)
+- Select only needed columns (avoid SELECT *)
+- Use JOINs instead of N+1 queries
+- Batch related queries when possible
+
+**Performance:**
+- Index frequently queried columns
+- Use EXPLAIN ANALYZE to optimize
+- Avoid full table scans
+- Use pagination for large result sets
+
+## ORM Patterns
+
+**If Using ORM (Prisma, TypeORM, etc.):**
+- Use ORM query builder for type safety
+- Keep queries simple and readable
+- Use raw SQL only when necessary
+- Leverage ORM relationships
+
+**If Using Raw SQL:**
+- Use parameterized queries
+- Centralize query logic
+- Document complex queries
+- Test queries with sample data
+
+## Row Level Security (RLS)
+
+**RLS Best Practices:**
+- Enable RLS on all user-facing tables
+- Policies check `auth.uid()` for ownership
+- Service role bypasses RLS (server-side only)
+- Test RLS policies thoroughly
+
+**RLS Patterns:**
+- Users can only access their own data
+- Public data accessible to all
+- Admin data accessible to admins only
+- Complex policies for shared resources
+
+## Indexing
+
+**Index Strategy:**
+- Index foreign keys
+- Index frequently queried columns
+- Index columns used in WHERE clauses
+- Index columns used in JOINs
+- Don't over-index (writes become slower)
+
+**Index Types:**
+- B-tree indexes (default, most common)
+- GIN indexes (for arrays, full-text search)
+- GiST indexes (for geometric data)
+- Partial indexes (for filtered queries)
+
+## Transactions
+
+**Transaction Patterns:**
+- Use transactions for multi-step operations
+- Keep transactions short
+- Handle transaction errors
+- Rollback on errors
+
+**Transaction Guidelines:**
+- Start transaction
+- Perform operations
+- Commit on success
+- Rollback on error
+
+## Backup and Recovery
+
+**Backup Strategy:**
+- Regular automated backups
+- Test restore process
+- Document backup schedule
+- Store backups securely
+
+**Recovery:**
+- Test restore on staging
+- Document recovery procedure
+- Have rollback plan
+- Monitor backup success
+
+## Database-Specific Patterns
+
+**PostgreSQL:**
+- Use JSONB for flexible schemas
+- Use arrays for simple lists
+- Use enums for fixed sets
+- Use full-text search (tsvector)
+
+**MySQL:**
+- Use appropriate storage engines
+- Optimize for InnoDB
+- Use proper charset (utf8mb4)
+
+**MongoDB:**
+- Design documents for queries
+- Use indexes effectively
+- Avoid deep nesting
+- Use aggregation pipeline
+
+## Supabase-Specific
+
+**If Supabase Detected:**
+- Server-side: Use service role (bypasses RLS)
+- Client-side: Use anon key (respects RLS)
+- Never expose service role key
+- Use Supabase query builder
+- Generate TypeScript types

package/template/.cursor/rules/31-testing.mdc

@@ -0,0 +1,191 @@
+---
+title: Testing Patterns
+description: Testing patterns - applies when testing framework is detected
+owner: sdd-system
+severity: warn
+globs: "**/*.test.ts, **/*.test.tsx, **/*.spec.ts, **/*.spec.tsx, **/__tests__/**"
+alwaysApply: false
+activation:
+  projectTypes: [web-app, cli-tool, library, api-service, mobile-app]
+  projectSizes: [small, medium, large, enterprise]
+  projectPhases: [initialization, expansion, maintenance, migration, legacy]
+  technologies: [jest, vitest, playwright, cypress, testing-library]
+  requires: [10-engineering]
+---
+
+# Testing Patterns
+
+## Purpose
+
+Testing patterns for unit, integration, and e2e testing. Applies when testing framework is detected (Jest, Vitest, Playwright, Cypress, Testing Library, etc.).
+
+## Principles
+
+- **Test Behavior, Not Implementation**: Test what the code does, not how
+- **AAA Pattern**: Arrange-Act-Assert
+- **Cover Critical Paths**: Happy path, failure paths, edge cases
+- **Fast Feedback**: Tests should run quickly
+- **Maintainable Tests**: Tests should be easy to read and update
+
+## Test Structure
+
+**Test Organization:**
+- Co-locate tests with source files
+- OR: Mirror structure under `__tests__/`
+- Group related tests with `describe` blocks
+- Use intention-revealing test names
+
+**Test File Naming:**
+- `*.test.ts` or `*.test.tsx` for component tests
+- `*.spec.ts` or `*.spec.tsx` for specification tests
+- Match source file name
+
+## Unit Testing
+
+**What to Test:**
+- Individual functions and methods
+- Business logic
+- Utility functions
+- Pure functions
+
+**Unit Test Pattern:**
+```typescript
+describe('functionName', () => {
+  it('should do something specific', () => {
+    // Arrange
+    const input = { ... };
+    
+    // Act
+    const result = functionName(input);
+    
+    // Assert
+    expect(result).toEqual({ ... });
+  });
+});
+```
+
+**Best Practices:**
+- Test one thing per test
+- Use descriptive test names
+- Test edge cases
+- Test error cases
+- Avoid testing implementation details
+
+## Integration Testing
+
+**What to Test:**
+- Component interactions
+- API endpoint behavior
+- Database operations
+- Service layer integration
+
+**Integration Test Pattern:**
+```typescript
+describe('API endpoint', () => {
+  it('should handle request correctly', async () => {
+    // Arrange
+    const request = { ... };
+    
+    // Act
+    const response = await fetch('/api/v1/endpoint', {
+      method: 'POST',
+      body: JSON.stringify(request)
+    });
+    
+    // Assert
+    expect(response.status).toBe(201);
+    expect(await response.json()).toMatchObject({ ... });
+  });
+});
+```
+
+## E2E Testing
+
+**What to Test:**
+- User workflows
+- Critical user paths
+- Cross-browser compatibility
+- Real user scenarios
+
+**E2E Test Pattern:**
+```typescript
+describe('User workflow', () => {
+  it('should complete user journey', async () => {
+    // Navigate to page
+    await page.goto('/');
+    
+    // Interact with page
+    await page.click('button[data-testid="submit"]');
+    
+    // Verify result
+    await expect(page.locator('.success')).toBeVisible();
+  });
+});
+```
+
+## Test Data and Fixtures
+
+**Fixtures:**
+- Create reusable test data
+- Use factories for complex objects
+- Keep fixtures realistic
+- Avoid hard-coded test data in tests
+
+**Mocking:**
+- Mock external dependencies
+- Mock API calls
+- Mock database operations
+- Keep mocks simple and focused
+
+## Test Coverage
+
+**Coverage Goals:**
+- Critical paths: 100% coverage
+- Business logic: High coverage
+- UI components: Moderate coverage
+- Utilities: High coverage
+
+**What Not to Test:**
+- Third-party library code
+- Framework code
+- Trivial getters/setters
+- Implementation details
+
+## Testing Best Practices
+
+**Fast Tests:**
+- Unit tests should be fast (< 100ms)
+- Integration tests moderate speed
+- E2E tests can be slower
+
+**Reliable Tests:**
+- Tests should be deterministic
+- Avoid flaky tests
+- Use proper cleanup
+- Isolate tests from each other
+
+**Maintainable Tests:**
+- Tests should be readable
+- Use helper functions
+- Avoid duplication
+- Keep tests focused
+
+## Framework-Specific
+
+**Jest/Vitest:**
+- Use `describe` and `it` blocks
+- Use `beforeEach`/`afterEach` for setup
+- Use `mock` for mocking
+- Use `expect` for assertions
+
+**Testing Library:**
+- Query by role, label, test id
+- Avoid querying by implementation details
+- Test user-visible behavior
+- Use `screen` for queries
+
+**Playwright/Cypress:**
+- Test real user interactions
+- Use page object pattern
+- Keep tests independent
+- Use proper waits

package/template/.cursor/scripts/validate-helpers.js

@@ -0,0 +1,254 @@
+#!/usr/bin/env node
+
+/**
+ * Helper Metadata Validation Script
+ * 
+ * Validates helper metadata for consistency and correctness:
+ * - All helpers have YAML frontmatter
+ * - Section line ranges match actual section markers
+ * - Section titles match headings
+ * - All helpers documented in helper-metadata.md
+ * - Metadata consistency between frontmatter and registry
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const HELPERS_DIR = path.join(__dirname, '../commands/_shared');
+const METADATA_FILE = path.join(HELPERS_DIR, 'helper-metadata.md');
+
+// Colors for output
+const colors = {
+  reset: '\x1b[0m',
+  green: '\x1b[32m',
+  red: '\x1b[31m',
+  yellow: '\x1b[33m',
+  blue: '\x1b[34m',
+};
+
+function log(message, color = 'reset') {
+  console.log(`${colors[color]}${message}${colors.reset}`);
+}
+
+function parseYAMLFrontmatter(content) {
+  const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---/);
+  if (!frontmatterMatch) return null;
+  
+  const frontmatter = {};
+  const lines = frontmatterMatch[1].split('\n');
+  
+  let currentKey = null;
+  let currentValue = [];
+  let inArray = false;
+  
+  for (const line of lines) {
+    if (line.trim() === '') continue;
+    
+    // Check for array start
+    if (line.match(/^(\s*)([a-z_]+):\s*$/)) {
+      if (currentKey) {
+        frontmatter[currentKey] = currentValue.length === 1 ? currentValue[0] : currentValue;
+      }
+      currentKey = line.match(/^(\s*)([a-z_]+):\s*$/)[2];
+      currentValue = [];
+      inArray = true;
+      continue;
+    }
+    
+    // Check for array item
+    if (inArray && line.match(/^\s*-\s*(.+)$/)) {
+      currentValue.push(line.match(/^\s*-\s*(.+)$/)[1]);
+      continue;
+    }
+    
+    // Check for key-value
+    if (line.match(/^(\s*)([a-z_]+):\s*(.+)$/)) {
+      if (currentKey) {
+        frontmatter[currentKey] = currentValue.length === 1 ? currentValue[0] : currentValue;
+      }
+      const match = line.match(/^(\s*)([a-z_]+):\s*(.+)$/);
+      currentKey = match[2];
+      currentValue = [match[3]];
+      inArray = false;
+      continue;
+    }
+    
+    // Check for nested structure (sections)
+    if (line.match(/^\s+([a-z_]+):/)) {
+      // This is a nested key, skip for now (simplified parsing)
+      continue;
+    }
+  }
+  
+  if (currentKey) {
+    frontmatter[currentKey] = currentValue.length === 1 ? currentValue[0] : currentValue;
+  }
+  
+  return frontmatter;
+}
+
+function findSectionMarkers(content) {
+  const sections = [];
+  const lines = content.split('\n');
+  
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const sectionMatch = line.match(/^## Section: (.+?) \(Lines (\d+)-(\d+)\)$/);
+    if (sectionMatch) {
+      sections.push({
+        title: sectionMatch[1],
+        startLine: parseInt(sectionMatch[2]),
+        endLine: parseInt(sectionMatch[3]),
+        actualLine: i + 1,
+      });
+    }
+  }
+  
+  return sections;
+}
+
+function validateHelper(helperFile) {
+  const filePath = path.join(HELPERS_DIR, helperFile);
+  const content = fs.readFileSync(filePath, 'utf-8');
+  const issues = [];
+  
+  // 1. Check frontmatter exists
+  const frontmatter = parseYAMLFrontmatter(content);
+  if (!frontmatter) {
+    issues.push({ type: 'error', message: 'Missing YAML frontmatter' });
+    return { file: helperFile, issues };
+  }
+  
+  // 2. Check required fields
+  const requiredFields = ['helper_id', 'load_when', 'sections', 'always_load'];
+  for (const field of requiredFields) {
+    if (!(field in frontmatter)) {
+      issues.push({ type: 'error', message: `Missing required field: ${field}` });
+    }
+  }
+  
+  // 3. Check section markers match metadata
+  const sections = findSectionMarkers(content);
+  if (sections.length > 0 && frontmatter.sections) {
+    // Note: Simplified check - would need to parse sections from frontmatter properly
+    // For now, just check that sections exist
+    for (const section of sections) {
+      if (section.actualLine !== section.startLine) {
+        issues.push({
+          type: 'warning',
+          message: `Section "${section.title}" marker at line ${section.actualLine}, but metadata says ${section.startLine}`,
+        });
+      }
+    }
+  }
+  
+  return { file: helperFile, frontmatter, sections, issues };
+}
+
+function validateRegistry() {
+  const content = fs.readFileSync(METADATA_FILE, 'utf-8');
+  const helperFiles = fs.readdirSync(HELPERS_DIR)
+    .filter(f => f.endsWith('.md') && f !== 'helper-metadata.md');
+  
+  const registryHelpers = [];
+  const registryMatch = content.match(/### ([a-z-]+)\.md/g);
+  if (registryMatch) {
+    registryHelpers.push(...registryMatch.map(m => m.replace('### ', '').replace('.md', '')));
+  }
+  
+  const issues = [];
+  
+  // Check all helpers are in registry
+  for (const helperFile of helperFiles) {
+    const helperId = helperFile.replace('.md', '');
+    if (!registryHelpers.includes(helperId)) {
+      issues.push({
+        type: 'warning',
+        message: `${helperId}.md not documented in helper-metadata.md`,
+      });
+    }
+  }
+  
+  // Check registry has all helpers
+  for (const registryHelper of registryHelpers) {
+    if (!helperFiles.includes(`${registryHelper}.md`)) {
+      issues.push({
+        type: 'error',
+        message: `Registry documents ${registryHelper}.md but file doesn't exist`,
+      });
+    }
+  }
+  
+  return { helperFiles, registryHelpers, issues };
+}
+
+function main() {
+  log('🔍 Validating Helper Metadata...\n', 'blue');
+  
+  const helperFiles = fs.readdirSync(HELPERS_DIR)
+    .filter(f => f.endsWith('.md') && f !== 'helper-metadata.md');
+  
+  let totalIssues = 0;
+  let totalErrors = 0;
+  let totalWarnings = 0;
+  
+  // Validate each helper
+  for (const helperFile of helperFiles) {
+    const result = validateHelper(helperFile);
+    if (result.issues.length > 0) {
+      log(`\n📄 ${helperFile}:`, 'blue');
+      for (const issue of result.issues) {
+        if (issue.type === 'error') {
+          log(`  ❌ ${issue.message}`, 'red');
+          totalErrors++;
+        } else {
+          log(`  ⚠️  ${issue.message}`, 'yellow');
+          totalWarnings++;
+        }
+        totalIssues++;
+      }
+    } else {
+      log(`✅ ${helperFile}`, 'green');
+    }
+  }
+  
+  // Validate registry
+  log('\n📋 Validating Helper Registry...\n', 'blue');
+  const registryResult = validateRegistry();
+  
+  if (registryResult.issues.length > 0) {
+    for (const issue of registryResult.issues) {
+      if (issue.type === 'error') {
+        log(`  ❌ ${issue.message}`, 'red');
+        totalErrors++;
+      } else {
+        log(`  ⚠️  ${issue.message}`, 'yellow');
+        totalWarnings++;
+      }
+      totalIssues++;
+    }
+  } else {
+    log('✅ Helper registry is consistent', 'green');
+  }
+  
+  // Summary
+  log('\n' + '='.repeat(50), 'blue');
+  if (totalIssues === 0) {
+    log('✅ All validations passed!', 'green');
+    process.exit(0);
+  } else {
+    log(`\n📊 Summary:`, 'blue');
+    log(`   Total issues: ${totalIssues}`, totalErrors > 0 ? 'red' : 'yellow');
+    log(`   Errors: ${totalErrors}`, totalErrors > 0 ? 'red' : 'reset');
+    log(`   Warnings: ${totalWarnings}`, totalWarnings > 0 ? 'yellow' : 'reset');
+    log('\n⚠️  Some issues found. Please review and fix.', 'yellow');
+    process.exit(totalErrors > 0 ? 1 : 0);
+  }
+}
+
+if (require.main === module) {
+  main();
+}
+
+module.exports = { validateHelper, validateRegistry };
+

package/template/.sdd/detection-cache.json

@@ -0,0 +1 @@
+{}

package/template/.sdd/install-info.json

@@ -0,0 +1 @@
+{"version":"0.1.0","installed_date":"","installed_by":"cli","installation_type":""}

package/template/.sdd/version

@@ -0,0 +1 @@
+0.1.0

package/template/spec/00-root-spec.md

@@ -26,4 +26,11 @@ List uncertainties, assumptions, or things that need clarification.
 Only include risks that are already visible at this stage.
 
 ## 8. Notes
-Anything else discovered during discussion or research.
+Anything else discovered during discussion or research.
+
+## 9. Related Specifications
+If applicable, reference:
+- `spec/01-prd.md` (if PRD was created)
+- `spec/02-architecture.md` (if architecture is documented)
+- `spec/07-design-system.md` (if design is critical)
+- `spec/08-infrastructure.md` (if infrastructure is critical)