@leanspec/cli 0.3.0

package/templates/examples/api-refactor/README.md

@@ -0,0 +1,81 @@
+# API Refactor Demo
+
+> **Tutorial**: [Refactoring with Specs](https://lean-spec.dev/docs/tutorials/refactoring-specs)
+
+## Scenario
+
+You're maintaining a Node.js application that started simple but has grown messy. The app integrates with multiple external services (weather API, currency converter, timezone lookup), but all the HTTP logic is tangled together in the main application code.
+
+You want to extract a reusable API client module that:
+- Centralizes HTTP request handling
+- Provides a clean interface for service calls
+- Handles errors consistently
+- Makes the code easier to test and maintain
+
+## What's Here
+
+A monolithic Node.js app with:
+- Weather lookup feature (calls external API)
+- Currency conversion (calls external API)
+- Timezone lookup (calls external API)
+- All HTTP logic mixed into business logic (tight coupling)
+- No error handling abstraction
+- Hard to test individual parts
+
+**Files:**
+- `src/app.js` - Main application with all features
+- `src/services/weatherService.js` - Weather API calls (tightly coupled)
+- `src/services/currencyService.js` - Currency API calls (tightly coupled)
+- `src/services/timezoneService.js` - Timezone API calls (tightly coupled)
+
+## Getting Started
+
+```bash
+# Install dependencies
+npm install
+
+# Run the app
+npm start
+
+# Try the features:
+# - Weather: Get weather for a city
+# - Currency: Convert between currencies
+# - Timezone: Look up timezone info
+```
+
+## Your Mission
+
+Refactor the HTTP logic into a clean, reusable API client. Follow the tutorial and ask your AI assistant:
+
+> "Help me refactor this app using LeanSpec. I want to extract a reusable API client module that centralizes all the HTTP logic."
+
+The AI will guide you through:
+1. Creating a refactoring spec
+2. Designing the API client interface
+3. Extracting the HTTP logic step by step
+4. Updating services to use the new client
+5. Verifying everything still works
+
+## Current Problems
+
+- **Duplicated code**: Each service reimplements HTTP requests
+- **No error handling**: Errors handled inconsistently
+- **Hard to test**: Can't mock HTTP calls easily
+- **Tight coupling**: Business logic mixed with HTTP details
+- **No retry logic**: Network failures aren't handled
+
+These are perfect opportunities to practice refactoring with specs!
+
+## Expected Result
+
+After refactoring, you should have:
+```
+src/
+  app.js (unchanged interface)
+  client/
+    apiClient.js (new - centralized HTTP logic)
+  services/
+    weatherService.js (simplified - uses apiClient)
+    currencyService.js (simplified - uses apiClient)
+    timezoneService.js (simplified - uses apiClient)
+```

package/templates/examples/api-refactor/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "api-refactor-demo",
+  "version": "1.0.0",
+  "description": "Monolithic Node.js app for LeanSpec Tutorial 3",
+  "type": "module",
+  "scripts": {
+    "start": "node src/app.js",
+    "dev": "node --watch src/app.js"
+  },
+  "keywords": ["leanspec", "tutorial", "demo"],
+  "author": "",
+  "license": "MIT",
+  "dependencies": {
+    "node-fetch": "^3.3.2"
+  }
+}

package/templates/examples/api-refactor/src/app.js

@@ -0,0 +1,40 @@
+import { getWeather } from './services/weatherService.js';
+import { convertCurrency } from './services/currencyService.js';
+import { getTimezone } from './services/timezoneService.js';
+
+console.log('=== Multi-Service App Demo ===\n');
+
+// Demo 1: Weather lookup
+console.log('1. Weather Lookup:');
+try {
+  const weather = await getWeather('London');
+  console.log(`   ${weather.city}: ${weather.temp}°C, ${weather.condition}`);
+} catch (error) {
+  console.log(`   Error: ${error.message}`);
+}
+
+console.log('');
+
+// Demo 2: Currency conversion
+console.log('2. Currency Conversion:');
+try {
+  const result = await convertCurrency(100, 'USD', 'EUR');
+  console.log(`   ${result.amount} ${result.from} = ${result.converted} ${result.to}`);
+} catch (error) {
+  console.log(`   Error: ${error.message}`);
+}
+
+console.log('');
+
+// Demo 3: Timezone lookup
+console.log('3. Timezone Lookup:');
+try {
+  const timezone = await getTimezone('America/New_York');
+  console.log(`   ${timezone.name}: ${timezone.offset} (${timezone.abbreviation})`);
+} catch (error) {
+  console.log(`   Error: ${error.message}`);
+}
+
+console.log('');
+console.log('Notice: All services work, but they all duplicate HTTP logic!');
+console.log('Your task: Extract a reusable API client module.');

package/templates/examples/api-refactor/src/services/currencyService.js

@@ -0,0 +1,43 @@
+import fetch from 'node-fetch';
+
+/**
+ * Convert currency
+ * 
+ * PROBLEM: Duplicates HTTP logic from weatherService
+ * - Same fetch boilerplate
+ * - Same error handling pattern
+ * - Same JSON parsing
+ * - Should be using a shared HTTP client!
+ */
+export async function convertCurrency(amount, from, to) {
+  // Mock API endpoint (replace with real API in production)
+  const url = `https://api.exchangerate.host/convert?from=${from}&to=${to}&amount=${amount}`;
+  
+  try {
+    const response = await fetch(url);
+    
+    if (!response.ok) {
+      throw new Error(`Currency API error: ${response.status}`);
+    }
+    
+    const data = await response.json();
+    
+    // Business logic: Transform API response to our format
+    return {
+      amount,
+      from,
+      to,
+      converted: data.result || (amount * 0.85).toFixed(2),
+      rate: data.info?.rate || 0.85,
+    };
+  } catch (error) {
+    // For demo, return mock data on error
+    return {
+      amount,
+      from,
+      to,
+      converted: (amount * 0.85).toFixed(2),
+      rate: 0.85,
+    };
+  }
+}

package/templates/examples/api-refactor/src/services/timezoneService.js

@@ -0,0 +1,41 @@
+import fetch from 'node-fetch';
+
+/**
+ * Get timezone information
+ * 
+ * PROBLEM: Yet another copy of the same HTTP logic!
+ * - Third time we're writing fetch + error handling + JSON parsing
+ * - Violates DRY principle
+ * - Makes testing hard (need to mock fetch in 3 places)
+ * - Changes to HTTP logic need updates in 3 files
+ */
+export async function getTimezone(zone) {
+  // Mock API endpoint (replace with real API in production)
+  const url = `http://worldtimeapi.org/api/timezone/${zone}`;
+  
+  try {
+    const response = await fetch(url);
+    
+    if (!response.ok) {
+      throw new Error(`Timezone API error: ${response.status}`);
+    }
+    
+    const data = await response.json();
+    
+    // Business logic: Transform API response to our format
+    return {
+      name: data.timezone || zone,
+      offset: data.utc_offset || '-05:00',
+      abbreviation: data.abbreviation || 'EST',
+      datetime: data.datetime || new Date().toISOString(),
+    };
+  } catch (error) {
+    // For demo, return mock data on error
+    return {
+      name: zone,
+      offset: '-05:00',
+      abbreviation: 'EST',
+      datetime: new Date().toISOString(),
+    };
+  }
+}

package/templates/examples/api-refactor/src/services/weatherService.js

@@ -0,0 +1,42 @@
+import fetch from 'node-fetch';
+
+/**
+ * Get weather for a city
+ * 
+ * PROBLEM: This function has HTTP logic mixed with business logic
+ * - Manual fetch calls
+ * - Manual error handling
+ * - Manual JSON parsing
+ * - No retry logic
+ * - Hard to test (can't mock HTTP)
+ */
+export async function getWeather(city) {
+  // Mock API endpoint (replace with real API in production)
+  const url = `https://api.weatherapi.com/v1/current.json?key=mock&q=${city}`;
+  
+  try {
+    const response = await fetch(url);
+    
+    if (!response.ok) {
+      throw new Error(`Weather API error: ${response.status}`);
+    }
+    
+    const data = await response.json();
+    
+    // Business logic: Transform API response to our format
+    return {
+      city: data.location?.name || city,
+      temp: data.current?.temp_c || Math.floor(Math.random() * 30),
+      condition: data.current?.condition?.text || 'Sunny',
+      humidity: data.current?.humidity || Math.floor(Math.random() * 100),
+    };
+  } catch (error) {
+    // For demo, return mock data on error
+    return {
+      city,
+      temp: Math.floor(Math.random() * 30),
+      condition: 'Sunny (mock data)',
+      humidity: Math.floor(Math.random() * 100),
+    };
+  }
+}

package/templates/examples/dark-theme/README.md

@@ -0,0 +1,66 @@
+# Dark Theme Demo
+
+> **Tutorial**: [Adding Dark Theme Support](https://lean-spec.dev/docs/tutorials/adding-dark-theme)
+
+## Scenario
+
+You're building a professional admin dashboard for a SaaS product. The dashboard looks modern and works great, but users keep requesting a dark mode option for late-night monitoring sessions and to reduce eye strain during extended use. Currently, the dashboard only has a bright light theme.
+
+## What's Here
+
+A professional admin dashboard with:
+- Interactive data visualization with charts (Chart.js)
+- Real-time statistics cards with animations
+- Sidebar navigation and top bar
+- Activity feed with recent events
+- Responsive layout
+- Clean, modern light theme
+- No dark mode support (yet!)
+
+**Files:**
+- `src/server.js` - Express server for static files
+- `src/public/index.html` - Dashboard interface with sidebar, charts, and stats
+- `src/public/style.css` - Current light theme styles (CSS custom properties ready)
+- `src/public/app.js` - Dashboard logic, chart initialization, and animations
+
+## Getting Started
+
+```bash
+# Install dependencies
+npm install
+
+# Start the server
+npm start
+
+# Open in your browser:
+# http://localhost:3000
+```
+
+## Your Mission
+
+Add dark theme support with automatic switching based on system preferences. Follow the tutorial and ask your AI assistant:
+
+> "Help me add dark theme support to this admin dashboard using LeanSpec. It should automatically switch based on the user's system theme preference."
+
+The AI will guide you through:
+1. Creating a spec for dark theme support
+2. Designing CSS custom properties for dark mode colors
+3. Implementing the `@media (prefers-color-scheme: dark)` query
+4. Ensuring charts adapt to the theme
+5. Testing the theme switching
+
+## Current Limitations
+
+- Only light theme available
+- No manual theme toggle
+- Chart colors don't adapt to theme
+- No theme persistence across sessions
+
+These are perfect opportunities to practice spec-driven development!
+
+## Tech Stack
+
+- **Frontend**: Vanilla HTML, CSS, JavaScript
+- **Charts**: Chart.js 4.4.0
+- **Backend**: Express.js (serving static files)
+- **Styling**: CSS Custom Properties (CSS Variables)

package/templates/examples/dark-theme/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "dark-theme-demo",
+  "version": "1.0.0",
+  "description": "Professional admin dashboard for LeanSpec Dark Theme Tutorial",
+  "type": "module",
+  "scripts": {
+    "start": "node src/server.js",
+    "dev": "node --watch src/server.js"
+  },
+  "keywords": ["leanspec", "tutorial", "demo", "dashboard", "admin"],
+  "author": "",
+  "license": "MIT",
+  "dependencies": {
+    "express": "^4.18.2"
+  }
+}

package/templates/examples/dark-theme/src/public/app.js

@@ -0,0 +1,277 @@
+// Admin Dashboard - Interactive data visualization
+// This is a starting point for adding dark theme support
+
+// ============================================
+// Initialize Charts
+// ============================================
+
+function initializeCharts() {
+  // Revenue Chart
+  const revenueCtx = document.getElementById('revenueChart');
+  if (revenueCtx) {
+    new Chart(revenueCtx, {
+      type: 'line',
+      data: {
+        labels: ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun'],
+        datasets: [{
+          label: 'Revenue',
+          data: [4200, 5100, 4800, 6200, 5800, 7100, 6500],
+          borderColor: '#0066cc',
+          backgroundColor: 'rgba(0, 102, 204, 0.1)',
+          borderWidth: 2,
+          tension: 0.4,
+          fill: true,
+          pointBackgroundColor: '#0066cc',
+          pointBorderColor: '#fff',
+          pointBorderWidth: 2,
+          pointRadius: 4,
+          pointHoverRadius: 6
+        }]
+      },
+      options: {
+        responsive: true,
+        maintainAspectRatio: false,
+        plugins: {
+          legend: {
+            display: false
+          },
+          tooltip: {
+            backgroundColor: 'rgba(0, 0, 0, 0.8)',
+            padding: 12,
+            borderRadius: 8,
+            titleColor: '#fff',
+            bodyColor: '#fff',
+            callbacks: {
+              label: function(context) {
+                return '$' + context.parsed.y.toLocaleString();
+              }
+            }
+          }
+        },
+        scales: {
+          y: {
+            beginAtZero: true,
+            grid: {
+              color: 'rgba(0, 0, 0, 0.05)'
+            },
+            ticks: {
+              callback: function(value) {
+                return '$' + value.toLocaleString();
+              }
+            }
+          },
+          x: {
+            grid: {
+              display: false
+            }
+          }
+        }
+      }
+    });
+  }
+
+  // Traffic Chart
+  const trafficCtx = document.getElementById('trafficChart');
+  if (trafficCtx) {
+    new Chart(trafficCtx, {
+      type: 'doughnut',
+      data: {
+        labels: ['Organic', 'Direct', 'Social', 'Referral'],
+        datasets: [{
+          data: [42, 28, 18, 12],
+          backgroundColor: [
+            '#0066cc',
+            '#00a854',
+            '#7c3aed',
+            '#ff8c00'
+          ],
+          borderWidth: 0,
+          hoverOffset: 8
+        }]
+      },
+      options: {
+        responsive: true,
+        maintainAspectRatio: false,
+        plugins: {
+          legend: {
+            position: 'bottom',
+            labels: {
+              padding: 16,
+              usePointStyle: true,
+              pointStyle: 'circle',
+              font: {
+                size: 12
+              }
+            }
+          },
+          tooltip: {
+            backgroundColor: 'rgba(0, 0, 0, 0.8)',
+            padding: 12,
+            borderRadius: 8,
+            titleColor: '#fff',
+            bodyColor: '#fff',
+            callbacks: {
+              label: function(context) {
+                return context.label + ': ' + context.parsed + '%';
+              }
+            }
+          }
+        }
+      }
+    });
+  }
+}
+
+// ============================================
+// Animate Stats on Load
+// ============================================
+
+function animateValue(element, start, end, duration) {
+  const range = end - start;
+  const increment = range / (duration / 16);
+  let current = start;
+  
+  const timer = setInterval(() => {
+    current += increment;
+    if ((increment > 0 && current >= end) || (increment < 0 && current <= end)) {
+      element.textContent = formatStatValue(end);
+      clearInterval(timer);
+    } else {
+      element.textContent = formatStatValue(Math.floor(current));
+    }
+  }, 16);
+}
+
+function formatStatValue(value) {
+  if (value >= 1000) {
+    return value.toLocaleString();
+  }
+  return value.toString();
+}
+
+function animateStats() {
+  const stats = [
+    { id: 'totalUsers', value: 2847 },
+    { id: 'revenue', value: 45231, prefix: '$' },
+    { id: 'completedTasks', value: 892 },
+    { id: 'activeProjects', value: 24 }
+  ];
+  
+  stats.forEach(stat => {
+    const element = document.getElementById(stat.id);
+    if (element) {
+      if (stat.prefix) {
+        const originalText = element.textContent;
+        element.textContent = stat.prefix + '0';
+        animateValue(element, 0, stat.value, 1000);
+        const timer = setInterval(() => {
+          if (element.textContent !== stat.prefix + '0') {
+            const currentVal = element.textContent.replace(/[^0-9]/g, '');
+            element.textContent = stat.prefix + Number(currentVal).toLocaleString();
+          }
+        }, 16);
+        setTimeout(() => clearInterval(timer), 1000);
+      } else {
+        element.textContent = '0';
+        animateValue(element, 0, stat.value, 1000);
+      }
+    }
+  });
+}
+
+// ============================================
+// Recent Activity
+// ============================================
+
+function loadRecentActivity() {
+  const activities = [
+    {
+      type: 'user',
+      title: 'New user registration',
+      description: 'Sarah Johnson joined the platform',
+      time: '5 minutes ago',
+      icon: `<svg width="20" height="20" viewBox="0 0 20 20" fill="none">
+        <path d="M10 11C12.2091 11 14 9.20914 14 7C14 4.79086 12.2091 3 10 3C7.79086 3 6 4.79086 6 7C6 9.20914 7.79086 11 10 11Z" stroke="currentColor" stroke-width="2"/>
+        <path d="M3 17C3 14.2386 5.23858 12 8 12H12C14.7614 12 17 14.2386 17 17" stroke="currentColor" stroke-width="2"/>
+      </svg>`
+    },
+    {
+      type: 'report',
+      title: 'Monthly report generated',
+      description: 'Q4 2024 performance summary is ready',
+      time: '1 hour ago',
+      icon: `<svg width="20" height="20" viewBox="0 0 20 20" fill="none">
+        <rect x="3" y="3" width="14" height="14" rx="2" stroke="currentColor" stroke-width="2"/>
+        <path d="M7 8H13M7 12H10" stroke="currentColor" stroke-width="2" stroke-linecap="round"/>
+      </svg>`
+    },
+    {
+      type: 'alert',
+      title: 'Server capacity warning',
+      description: 'CPU usage exceeded 80% threshold',
+      time: '3 hours ago',
+      icon: `<svg width="20" height="20" viewBox="0 0 20 20" fill="none">
+        <path d="M10 6V10M10 14H10.01M10 18C14.4183 18 18 14.4183 18 10C18 5.58172 14.4183 2 10 2C5.58172 2 2 5.58172 2 10C2 14.4183 5.58172 18 10 18Z" stroke="currentColor" stroke-width="2" stroke-linecap="round"/>
+      </svg>`
+    },
+    {
+      type: 'user',
+      title: 'Team member added',
+      description: 'Michael Chen joined the Development team',
+      time: '5 hours ago',
+      icon: `<svg width="20" height="20" viewBox="0 0 20 20" fill="none">
+        <path d="M10 11C12.2091 11 14 9.20914 14 7C14 4.79086 12.2091 3 10 3C7.79086 3 6 4.79086 6 7C6 9.20914 7.79086 11 10 11Z" stroke="currentColor" stroke-width="2"/>
+        <path d="M3 17C3 14.2386 5.23858 12 8 12H12C14.7614 12 17 14.2386 17 17" stroke="currentColor" stroke-width="2"/>
+      </svg>`
+    },
+    {
+      type: 'report',
+      title: 'Backup completed',
+      description: 'Database backup finished successfully',
+      time: '8 hours ago',
+      icon: `<svg width="20" height="20" viewBox="0 0 20 20" fill="none">
+        <path d="M3 12L9 18L21 6" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"/>
+      </svg>`
+    }
+  ];
+  
+  const activityList = document.getElementById('activityList');
+  if (activityList) {
+    activityList.innerHTML = activities.map(activity => `
+      <div class="activity-item">
+        <div class="activity-icon ${activity.type}">
+          ${activity.icon}
+        </div>
+        <div class="activity-content">
+          <div class="activity-title">${activity.title}</div>
+          <div class="activity-description">${activity.description}</div>
+          <div class="activity-time">${activity.time}</div>
+        </div>
+      </div>
+    `).join('');
+  }
+}
+
+// ============================================
+// Initialize Dashboard
+// ============================================
+
+document.addEventListener('DOMContentLoaded', () => {
+  // Initialize all components
+  animateStats();
+  initializeCharts();
+  loadRecentActivity();
+  
+  // Add subtle hover effects
+  document.querySelectorAll('.stat-card').forEach(card => {
+    card.addEventListener('mouseenter', (e) => {
+      e.currentTarget.style.transform = 'translateY(-4px)';
+    });
+    card.addEventListener('mouseleave', (e) => {
+      e.currentTarget.style.transform = 'translateY(0)';
+    });
+  });
+  
+  console.log('✓ Dashboard initialized');
+  console.log('💡 Try adding dark theme support with CSS custom properties!');
+});