@hustle-together/api-dev-tools 3.6.5 → 3.9.2

package/templates/dev-tools/_components/DevToolsLanding.tsx

@@ -0,0 +1,320 @@
+'use client';
+
+import { useEffect, useState } from 'react';
+import Link from 'next/link';
+import { HeroHeader } from '../../shared/HeroHeader';
+
+interface Registry {
+  version?: string;
+  apis?: Record<string, unknown>;
+  components?: Record<string, unknown>;
+  pages?: Record<string, unknown>;
+  combined?: Record<string, unknown>;
+}
+
+/**
+ * DevToolsLanding Component
+ *
+ * Central hub for all Hustle Developer Tools.
+ * Links to API Showcase, UI Showcase, and displays registry stats.
+ *
+ * Created with Hustle Dev Tools (v3.9.2)
+ */
+export function DevToolsLanding() {
+  const [registry, setRegistry] = useState<Registry>({});
+  const [loading, setLoading] = useState(true);
+
+  useEffect(() => {
+    fetch('/api/registry')
+      .then((res) => res.json())
+      .then((data) => {
+        setRegistry(data);
+        setLoading(false);
+      })
+      .catch(() => {
+        setLoading(false);
+      });
+  }, []);
+
+  const stats = {
+    apis: Object.keys(registry.apis || {}).length,
+    components: Object.keys(registry.components || {}).length,
+    pages: Object.keys(registry.pages || {}).length,
+    combined: Object.keys(registry.combined || {}).length,
+  };
+
+  const total = stats.apis + stats.components + stats.pages + stats.combined;
+
+  return (
+    <div className="min-h-screen bg-white dark:bg-gray-950">
+      <HeroHeader
+        title="Hustle Dev Tools"
+        badge="Developer Portal"
+        description={
+          <>
+            Central hub for <strong>API development</strong>,{' '}
+            <strong>UI components</strong>, and documentation. Built with the
+            Hustle Together workflow.
+          </>
+        }
+      />
+
+      <main className="mx-auto max-w-6xl px-8 py-12 md:px-16">
+        {/* Stats Bar */}
+        <div className="mb-8 flex flex-wrap items-center gap-6 border-2 border-black bg-gray-50 p-6 dark:border-gray-700 dark:bg-gray-900">
+          <div className="flex items-center gap-2">
+            <span className="text-3xl font-bold text-black dark:text-white">
+              {loading ? '...' : total}
+            </span>
+            <span className="text-gray-600 dark:text-gray-400">
+              Total Items
+            </span>
+          </div>
+          <div className="h-8 w-px bg-gray-300 dark:bg-gray-600" />
+          <div className="flex items-center gap-2">
+            <span className="font-bold text-black dark:text-white">
+              {stats.apis}
+            </span>
+            <span className="text-gray-600 dark:text-gray-400">APIs</span>
+          </div>
+          <div className="flex items-center gap-2">
+            <span className="font-bold text-black dark:text-white">
+              {stats.components}
+            </span>
+            <span className="text-gray-600 dark:text-gray-400">Components</span>
+          </div>
+          <div className="flex items-center gap-2">
+            <span className="font-bold text-black dark:text-white">
+              {stats.pages}
+            </span>
+            <span className="text-gray-600 dark:text-gray-400">Pages</span>
+          </div>
+          <div className="flex items-center gap-2">
+            <span className="font-bold text-black dark:text-white">
+              {stats.combined}
+            </span>
+            <span className="text-gray-600 dark:text-gray-400">Combined</span>
+          </div>
+        </div>
+
+        {/* Main Cards Grid */}
+        <div className="mb-12 grid gap-6 md:grid-cols-3">
+          {/* API Showcase Card */}
+          <Link
+            href="/api-showcase"
+            className="group flex flex-col border-2 border-black bg-white p-6 transition-all hover:border-[#BA0C2F] hover:shadow-[4px_4px_0px_0px_rgba(186,12,47,0.2)] dark:border-gray-700 dark:bg-gray-900"
+          >
+            <div className="mb-4 flex h-12 w-12 items-center justify-center border-2 border-[#BA0C2F] bg-[#BA0C2F]/10">
+              <svg
+                xmlns="http://www.w3.org/2000/svg"
+                width="24"
+                height="24"
+                viewBox="0 0 24 24"
+                fill="none"
+                stroke="currentColor"
+                strokeWidth="2"
+                strokeLinecap="round"
+                strokeLinejoin="round"
+                className="text-[#BA0C2F]"
+              >
+                <path d="M4 4h16c1.1 0 2 .9 2 2v12c0 1.1-.9 2-2 2H4c-1.1 0-2-.9-2-2V6c0-1.1.9-2 2-2z" />
+                <polyline points="22,6 12,13 2,6" />
+              </svg>
+            </div>
+            <h2 className="mb-2 text-xl font-bold text-black group-hover:text-[#BA0C2F] dark:text-white">
+              API Showcase
+            </h2>
+            <p className="mb-4 flex-1 text-sm text-gray-600 dark:text-gray-400">
+              Interactive testing and documentation for all API endpoints. Try
+              requests, view schemas, and copy curl commands.
+            </p>
+            <div className="flex items-center gap-2 text-sm font-bold text-[#BA0C2F]">
+              <span>{stats.apis} APIs</span>
+              <span>+</span>
+              <span>{stats.combined} Combined</span>
+            </div>
+          </Link>
+
+          {/* UI Showcase Card */}
+          <Link
+            href="/ui-showcase"
+            className="group flex flex-col border-2 border-black bg-white p-6 transition-all hover:border-[#BA0C2F] hover:shadow-[4px_4px_0px_0px_rgba(186,12,47,0.2)] dark:border-gray-700 dark:bg-gray-900"
+          >
+            <div className="mb-4 flex h-12 w-12 items-center justify-center border-2 border-[#BA0C2F] bg-[#BA0C2F]/10">
+              <svg
+                xmlns="http://www.w3.org/2000/svg"
+                width="24"
+                height="24"
+                viewBox="0 0 24 24"
+                fill="none"
+                stroke="currentColor"
+                strokeWidth="2"
+                strokeLinecap="round"
+                strokeLinejoin="round"
+                className="text-[#BA0C2F]"
+              >
+                <rect width="7" height="7" x="3" y="3" rx="1" />
+                <rect width="7" height="7" x="14" y="3" rx="1" />
+                <rect width="7" height="7" x="14" y="14" rx="1" />
+                <rect width="7" height="7" x="3" y="14" rx="1" />
+              </svg>
+            </div>
+            <h2 className="mb-2 text-xl font-bold text-black group-hover:text-[#BA0C2F] dark:text-white">
+              UI Showcase
+            </h2>
+            <p className="mb-4 flex-1 text-sm text-gray-600 dark:text-gray-400">
+              Live component previews with Sandpack. Edit code in real-time,
+              switch variants, and test responsive layouts.
+            </p>
+            <div className="flex items-center gap-2 text-sm font-bold text-[#BA0C2F]">
+              <span>{stats.components} Components</span>
+              <span>+</span>
+              <span>{stats.pages} Pages</span>
+            </div>
+          </Link>
+
+          {/* Registry Card */}
+          <Link
+            href="/api/registry"
+            target="_blank"
+            className="group flex flex-col border-2 border-black bg-white p-6 transition-all hover:border-[#BA0C2F] hover:shadow-[4px_4px_0px_0px_rgba(186,12,47,0.2)] dark:border-gray-700 dark:bg-gray-900"
+          >
+            <div className="mb-4 flex h-12 w-12 items-center justify-center border-2 border-[#BA0C2F] bg-[#BA0C2F]/10">
+              <svg
+                xmlns="http://www.w3.org/2000/svg"
+                width="24"
+                height="24"
+                viewBox="0 0 24 24"
+                fill="none"
+                stroke="currentColor"
+                strokeWidth="2"
+                strokeLinecap="round"
+                strokeLinejoin="round"
+                className="text-[#BA0C2F]"
+              >
+                <path d="M14.5 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V7.5L14.5 2z" />
+                <polyline points="14 2 14 8 20 8" />
+                <line x1="16" x2="8" y1="13" y2="13" />
+                <line x1="16" x2="8" y1="17" y2="17" />
+                <line x1="10" x2="8" y1="9" y2="9" />
+              </svg>
+            </div>
+            <h2 className="mb-2 text-xl font-bold text-black group-hover:text-[#BA0C2F] dark:text-white">
+              Registry JSON
+            </h2>
+            <p className="mb-4 flex-1 text-sm text-gray-600 dark:text-gray-400">
+              Raw JSON registry of all APIs, components, and pages. Central
+              source of truth for the showcase pages.
+            </p>
+            <div className="text-sm font-bold text-[#BA0C2F]">
+              Version: {registry.version || '1.0.0'}
+            </div>
+          </Link>
+        </div>
+
+        {/* Quick Actions */}
+        <div className="border-2 border-black bg-gray-50 p-6 dark:border-gray-700 dark:bg-gray-900">
+          <h3 className="mb-4 text-lg font-bold text-black dark:text-white">
+            Quick Actions
+          </h3>
+          <div className="grid gap-4 md:grid-cols-2 lg:grid-cols-4">
+            <QuickAction
+              title="Run Storybook"
+              command="pnpm storybook"
+              description="Component development server"
+            />
+            <QuickAction
+              title="Run Tests"
+              command="pnpm test"
+              description="Execute test suite"
+            />
+            <QuickAction
+              title="Create API"
+              command="/hustle-api-create"
+              description="Start new API workflow"
+            />
+            <QuickAction
+              title="Create Component"
+              command="/hustle-ui-create"
+              description="Start new UI workflow"
+            />
+          </div>
+        </div>
+
+        {/* Setup Instructions */}
+        <div className="mt-8 border-2 border-black bg-white p-6 dark:border-gray-700 dark:bg-gray-900">
+          <h3 className="mb-4 text-lg font-bold text-black dark:text-white">
+            Optional Setup
+          </h3>
+          <div className="grid gap-4 md:grid-cols-3">
+            <SetupCard
+              title="Storybook"
+              command="npx storybook@latest init"
+              description="Interactive component development and visual testing"
+            />
+            <SetupCard
+              title="Playwright"
+              command="npm init playwright@latest"
+              description="E2E testing and accessibility verification"
+            />
+            <SetupCard
+              title="Sandpack"
+              command="pnpm add @codesandbox/sandpack-react"
+              description="Live code previews in UI Showcase"
+            />
+          </div>
+        </div>
+      </main>
+    </div>
+  );
+}
+
+function QuickAction({
+  title,
+  command,
+  description,
+}: {
+  title: string;
+  command: string;
+  description: string;
+}) {
+  return (
+    <div className="border-2 border-black bg-white p-4 dark:border-gray-600 dark:bg-gray-800">
+      <h4 className="font-bold text-black dark:text-white">{title}</h4>
+      <code className="mt-2 block border border-gray-300 bg-gray-100 px-2 py-1 font-mono text-sm text-gray-700 dark:border-gray-600 dark:bg-gray-700 dark:text-gray-300">
+        {command}
+      </code>
+      <p className="mt-2 text-xs text-gray-600 dark:text-gray-400">
+        {description}
+      </p>
+    </div>
+  );
+}
+
+function SetupCard({
+  title,
+  command,
+  description,
+}: {
+  title: string;
+  command: string;
+  description: string;
+}) {
+  return (
+    <div className="flex flex-col border border-gray-200 bg-gray-50 p-4 dark:border-gray-700 dark:bg-gray-800">
+      <h4 className="font-bold text-black dark:text-white">{title}</h4>
+      <p className="mt-1 text-sm text-gray-600 dark:text-gray-400">
+        {description}
+      </p>
+      <button
+        onClick={() => navigator.clipboard.writeText(command)}
+        className="mt-3 border-2 border-black bg-white px-3 py-1.5 text-left font-mono text-sm text-gray-700 transition-colors hover:border-[#BA0C2F] hover:bg-gray-50 dark:border-gray-600 dark:bg-gray-700 dark:text-gray-300 dark:hover:bg-gray-600"
+      >
+        {command}
+        <span className="float-right text-gray-400">Copy</span>
+      </button>
+    </div>
+  );
+}
+
+export default DevToolsLanding;

package/templates/dev-tools/page.tsx

@@ -0,0 +1,10 @@
+import { DevToolsLanding } from './_components/DevToolsLanding';
+
+export const metadata = {
+  title: 'Hustle Dev Tools',
+  description: 'Developer tools for API and UI development with Hustle Together',
+};
+
+export default function DevToolsPage() {
+  return <DevToolsLanding />;
+}

package/templates/page/page.e2e.test.ts

@@ -0,0 +1,218 @@
+import { test, expect } from '@playwright/test';
+
+/**
+ * E2E Tests for __PAGE_NAME__ Page
+ *
+ * Created with Hustle UI Create workflow (v3.9.0)
+ *
+ * Run with: pnpm playwright test __PAGE_ROUTE__.spec.ts
+ */
+test.describe('__PAGE_NAME__ Page', () => {
+  test.beforeEach(async ({ page }) => {
+    // Navigate to the page before each test
+    await page.goto('/__PAGE_ROUTE__');
+  });
+
+  // ===================================
+  // Basic Rendering Tests
+  // ===================================
+
+  test('should load successfully', async ({ page }) => {
+    // Wait for page to be fully loaded
+    await page.waitForLoadState('networkidle');
+
+    // Check page title
+    await expect(page).toHaveTitle(/__PAGE_TITLE__/);
+  });
+
+  test('should display page heading', async ({ page }) => {
+    const heading = page.getByRole('heading', { level: 1 });
+    await expect(heading).toBeVisible();
+    await expect(heading).toContainText('__PAGE_TITLE__');
+  });
+
+  test('should display page description', async ({ page }) => {
+    const description = page.getByText('__PAGE_DESCRIPTION__');
+    await expect(description).toBeVisible();
+  });
+
+  // ===================================
+  // Responsive Tests
+  // ===================================
+
+  test('should be responsive on mobile', async ({ page }) => {
+    await page.setViewportSize({ width: 375, height: 667 });
+    await page.goto('/__PAGE_ROUTE__');
+
+    // Verify main content is visible
+    await expect(page.getByRole('main')).toBeVisible();
+
+    // Verify no horizontal scroll
+    const body = await page.locator('body');
+    const scrollWidth = await body.evaluate((el) => el.scrollWidth);
+    const clientWidth = await body.evaluate((el) => el.clientWidth);
+    expect(scrollWidth).toBeLessThanOrEqual(clientWidth + 1); // +1 for rounding
+  });
+
+  test('should be responsive on tablet', async ({ page }) => {
+    await page.setViewportSize({ width: 768, height: 1024 });
+    await page.goto('/__PAGE_ROUTE__');
+
+    await expect(page.getByRole('main')).toBeVisible();
+  });
+
+  test('should be responsive on desktop', async ({ page }) => {
+    await page.setViewportSize({ width: 1920, height: 1080 });
+    await page.goto('/__PAGE_ROUTE__');
+
+    await expect(page.getByRole('main')).toBeVisible();
+  });
+
+  // ===================================
+  // Accessibility Tests
+  // ===================================
+
+  test('should have no accessibility violations', async ({ page }) => {
+    // Note: Requires @axe-core/playwright
+    // const results = await new AxeBuilder({ page }).analyze();
+    // expect(results.violations).toEqual([]);
+
+    // Basic accessibility checks
+    // All images should have alt text
+    const images = await page.getByRole('img').all();
+    for (const img of images) {
+      await expect(img).toHaveAttribute('alt');
+    }
+
+    // All buttons should have accessible names
+    const buttons = await page.getByRole('button').all();
+    for (const button of buttons) {
+      const name = await button.getAttribute('aria-label') || await button.textContent();
+      expect(name?.trim()).toBeTruthy();
+    }
+  });
+
+  test('should be keyboard navigable', async ({ page }) => {
+    // Tab through interactive elements
+    await page.keyboard.press('Tab');
+
+    // Verify focus is visible
+    const focusedElement = page.locator(':focus');
+    await expect(focusedElement).toBeVisible();
+  });
+
+  // ===================================
+  // Performance Tests (TDD GATES)
+  // These thresholds match .claude/performance-budgets.json
+  // Tests FAIL if exceeded, triggering TDD loop-back
+  // ===================================
+
+  test('should load within performance budget', async ({ page }) => {
+    const startTime = Date.now();
+    await page.goto('/__PAGE_ROUTE__', { waitUntil: 'networkidle' });
+    const loadTime = Date.now() - startTime;
+
+    // THRESHOLD: Page load max 3000ms
+    // If this fails, optimize: code splitting, lazy loading, reduce bundle
+    expect(loadTime).toBeLessThan(3000);
+  });
+
+  test('should have acceptable memory usage', async ({ page }) => {
+    await page.goto('/__PAGE_ROUTE__');
+
+    // Get Chromium-specific metrics
+    const client = await page.context().newCDPSession(page);
+    const metrics = await client.send('Performance.getMetrics');
+
+    const jsHeapSize = metrics.metrics.find(m => m.name === 'JSHeapUsedSize')?.value || 0;
+    const domNodes = metrics.metrics.find(m => m.name === 'Nodes')?.value || 0;
+
+    // THRESHOLD: Memory max 50MB
+    // If this fails, check for: memory leaks, large state, unbounded lists
+    expect(jsHeapSize).toBeLessThan(50 * 1024 * 1024);
+
+    // THRESHOLD: DOM nodes max 1500
+    // If this fails, check for: unnecessary renders, infinite lists without virtualization
+    expect(domNodes).toBeLessThan(1500);
+  });
+
+  test('should not have layout thrashing', async ({ page }) => {
+    await page.goto('/__PAGE_ROUTE__');
+
+    const client = await page.context().newCDPSession(page);
+    const metrics = await client.send('Performance.getMetrics');
+
+    const layoutCount = metrics.metrics.find(m => m.name === 'LayoutCount')?.value || 0;
+    const layoutDuration = metrics.metrics.find(m => m.name === 'LayoutDuration')?.value || 0;
+
+    // THRESHOLD: Layout count max 10
+    // If this fails, batch DOM updates, use CSS transforms instead of layout properties
+    expect(layoutCount).toBeLessThan(10);
+
+    // THRESHOLD: Layout duration max 100ms
+    expect(layoutDuration * 1000).toBeLessThan(100);
+  });
+
+  test('should meet Core Web Vitals', async ({ page }) => {
+    await page.goto('/__PAGE_ROUTE__');
+
+    // Get paint timing
+    const paintTiming = await page.evaluate(() => {
+      const entries = performance.getEntriesByType('paint');
+      return {
+        fcp: entries.find(e => e.name === 'first-contentful-paint')?.startTime || 0,
+      };
+    });
+
+    // THRESHOLD: First Contentful Paint max 1500ms
+    // If this fails, optimize critical rendering path
+    expect(paintTiming.fcp).toBeLessThan(1500);
+
+    // Get LCP via PerformanceObserver result (if available)
+    const lcp = await page.evaluate(() => {
+      return new Promise<number>((resolve) => {
+        new PerformanceObserver((list) => {
+          const entries = list.getEntries();
+          const lastEntry = entries[entries.length - 1];
+          resolve(lastEntry?.startTime || 0);
+        }).observe({ type: 'largest-contentful-paint', buffered: true });
+
+        // Timeout fallback
+        setTimeout(() => resolve(0), 3000);
+      });
+    });
+
+    // THRESHOLD: Largest Contentful Paint max 2500ms
+    if (lcp > 0) {
+      expect(lcp).toBeLessThan(2500);
+    }
+  });
+
+  // ===================================
+  // Feature-Specific Tests
+  // ===================================
+
+  // TODO: Add tests for specific page features
+  // Example:
+  // test('should display user data when logged in', async ({ page }) => {
+  //   // Setup auth state
+  //   // await page.context().addCookies([...]);
+  //
+  //   await page.goto('/__PAGE_ROUTE__');
+  //   await expect(page.getByText('Welcome')).toBeVisible();
+  // });
+
+  // ===================================
+  // Error Handling Tests
+  // ===================================
+
+  test('should handle errors gracefully', async ({ page }) => {
+    // Intercept API calls to simulate errors (if applicable)
+    // await page.route('/api/*', route => route.fulfill({ status: 500 }));
+
+    await page.goto('/__PAGE_ROUTE__');
+
+    // Page should still render without crashing
+    await expect(page.getByRole('main')).toBeVisible();
+  });
+});

package/templates/page/page.tsx

@@ -0,0 +1,42 @@
+import type { Metadata } from 'next';
+
+/**
+ * Page metadata for SEO
+ */
+export const metadata: Metadata = {
+  title: '__PAGE_TITLE__',
+  description: '__PAGE_DESCRIPTION__',
+};
+
+/**
+ * __PAGE_NAME__ Page
+ *
+ * @description __PAGE_DESCRIPTION__
+ *
+ * Created with Hustle UI Create workflow (v3.9.0)
+ */
+export default async function __PAGE_NAME__Page() {
+  // Server-side data fetching (if needed)
+  // const data = await fetchData();
+
+  return (
+    <main className="container mx-auto px-4 py-8">
+      {/* Page Header */}
+      <header className="mb-8">
+        <h1 className="text-3xl font-bold tracking-tight">__PAGE_TITLE__</h1>
+        <p className="mt-2 text-muted-foreground">__PAGE_DESCRIPTION__</p>
+      </header>
+
+      {/* Page Content */}
+      <section className="space-y-6">
+        {/* Add your components here */}
+        <div className="rounded-lg border bg-card p-6">
+          <h2 className="text-xl font-semibold">Getting Started</h2>
+          <p className="mt-2 text-muted-foreground">
+            Replace this content with your page implementation.
+          </p>
+        </div>
+      </section>
+    </main>
+  );
+}

package/templates/performance-budgets.json

@@ -0,0 +1,58 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "description": "Performance budgets for UI components and pages. Tests will FAIL if these thresholds are exceeded.",
+  "version": "1.0.0",
+
+  "memory": {
+    "description": "Memory usage thresholds (in MB)",
+    "page_max_mb": 50,
+    "component_max_mb": 10,
+    "heap_growth_max_mb": 5
+  },
+
+  "renders": {
+    "description": "React render count thresholds",
+    "mount_max": 1,
+    "prop_change_max": 1,
+    "state_change_max": 1,
+    "unnecessary_renders_max": 0
+  },
+
+  "layout": {
+    "description": "Layout performance thresholds",
+    "count_max": 10,
+    "duration_max_ms": 100,
+    "style_recalc_max": 20
+  },
+
+  "timing": {
+    "description": "Load and interaction timing thresholds (in ms)",
+    "page_load_max_ms": 3000,
+    "first_contentful_paint_max_ms": 1500,
+    "time_to_interactive_max_ms": 3500,
+    "largest_contentful_paint_max_ms": 2500
+  },
+
+  "bundle": {
+    "description": "Bundle size thresholds (in KB)",
+    "component_max_kb": 50,
+    "page_max_kb": 200,
+    "chunk_max_kb": 100
+  },
+
+  "accessibility": {
+    "description": "Accessibility requirements",
+    "wcag_level": "AA",
+    "violations_max": 0,
+    "color_contrast_min": 4.5
+  },
+
+  "responsive": {
+    "description": "Responsive breakpoints to test",
+    "breakpoints": [
+      { "name": "mobile", "width": 375, "height": 667 },
+      { "name": "tablet", "width": 768, "height": 1024 },
+      { "name": "desktop", "width": 1920, "height": 1080 }
+    ]
+  }
+}

package/templates/registry.json

@@ -0,0 +1,13 @@
+{
+  "version": "1.0.0",
+  "updated_at": "",
+  "description": "Central registry tracking all APIs, components, and pages created through Hustle Dev Tools",
+
+  "apis": {},
+
+  "components": {},
+
+  "pages": {},
+
+  "combined": {}
+}