create-appystack 0.1.0

package/template/client/src/demo/SocketDemo.test.tsx

@@ -0,0 +1,160 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { render, screen, fireEvent, act } from '@testing-library/react';
+
+// Hoisted mutable state so vi.mock factory can reference it
+const mockSocketState = vi.hoisted(() => ({
+  socket: null as { once: ReturnType<typeof vi.fn>; emit: ReturnType<typeof vi.fn> } | null,
+  connected: false,
+  mockOnce: vi.fn(),
+  mockEmit: vi.fn(),
+}));
+
+vi.mock('../hooks/useSocket.js', () => ({
+  useSocket: () => ({
+    socket: mockSocketState.socket,
+    connected: mockSocketState.connected,
+  }),
+}));
+
+import SocketDemo from './SocketDemo.js';
+
+describe('SocketDemo — disconnected (default)', () => {
+  beforeEach(() => {
+    mockSocketState.socket = null;
+    mockSocketState.connected = false;
+    mockSocketState.mockOnce.mockReset();
+    mockSocketState.mockEmit.mockReset();
+  });
+
+  it('renders the Socket.io Demo heading', () => {
+    render(<SocketDemo />);
+    expect(screen.getByText('Socket.io Demo')).toBeInTheDocument();
+  });
+
+  it('renders the Send Ping button', () => {
+    render(<SocketDemo />);
+    expect(screen.getByRole('button', { name: 'Send Ping' })).toBeInTheDocument();
+  });
+
+  it('renders the Send Ping button disabled when disconnected', () => {
+    render(<SocketDemo />);
+    const button = screen.getByRole('button', { name: 'Send Ping' });
+    expect(button).toBeDisabled();
+  });
+
+  it('shows disconnected status on initial render', () => {
+    render(<SocketDemo />);
+    expect(screen.getByText('Status: disconnected')).toBeInTheDocument();
+  });
+
+  it('does not show pong response before any ping is sent', () => {
+    render(<SocketDemo />);
+    expect(screen.queryByText(/server:pong received/)).not.toBeInTheDocument();
+  });
+});
+
+describe('SocketDemo — connected state', () => {
+  beforeEach(() => {
+    mockSocketState.mockOnce.mockReset();
+    mockSocketState.mockEmit.mockReset();
+    mockSocketState.socket = {
+      once: mockSocketState.mockOnce,
+      emit: mockSocketState.mockEmit,
+    };
+    mockSocketState.connected = true;
+  });
+
+  it('shows connected status when socket is connected', () => {
+    render(<SocketDemo />);
+    expect(screen.getByText('Status: connected')).toBeInTheDocument();
+  });
+
+  it('button is enabled when connected', () => {
+    render(<SocketDemo />);
+    const button = screen.getByRole('button', { name: 'Send Ping' });
+    expect(button).not.toBeDisabled();
+  });
+
+  it('sendPing calls socket.once and socket.emit when clicked', async () => {
+    render(<SocketDemo />);
+    const button = screen.getByRole('button', { name: 'Send Ping' });
+
+    await act(async () => {
+      fireEvent.click(button);
+    });
+
+    expect(mockSocketState.mockOnce).toHaveBeenCalledTimes(1);
+    expect(mockSocketState.mockEmit).toHaveBeenCalledTimes(1);
+  });
+
+  it('shows waiting state after ping is sent', async () => {
+    // mockOnce never fires, so waiting=true persists
+    mockSocketState.mockOnce.mockImplementation(() => {});
+
+    render(<SocketDemo />);
+    const button = screen.getByRole('button', { name: 'Send Ping' });
+
+    await act(async () => {
+      fireEvent.click(button);
+    });
+
+    expect(screen.getByText('Waiting for pong...')).toBeInTheDocument();
+  });
+
+  it('shows pong response after server:pong event fires', async () => {
+    let pongHandler: ((data: { message: string; timestamp: string }) => void) | null = null;
+    mockSocketState.mockOnce.mockImplementation(
+      (_event: string, handler: (data: { message: string; timestamp: string }) => void) => {
+        pongHandler = handler;
+      }
+    );
+
+    render(<SocketDemo />);
+    const button = screen.getByRole('button', { name: 'Send Ping' });
+
+    await act(async () => {
+      fireEvent.click(button);
+    });
+
+    await act(async () => {
+      pongHandler?.({ message: 'pong', timestamp: new Date().toISOString() });
+    });
+
+    expect(screen.getByText(/server:pong received/)).toBeInTheDocument();
+  });
+});
+
+describe('SocketDemo — disconnect after connect', () => {
+  it('Send Ping button is disabled when socket disconnects', () => {
+    // Start disconnected — simulate a socket that has dropped
+    mockSocketState.socket = null;
+    mockSocketState.connected = false;
+
+    render(<SocketDemo />);
+    const button = screen.getByRole('button', { name: 'Send Ping' });
+    expect(button).toBeDisabled();
+  });
+
+  it('shows disconnected status text when socket is not connected', () => {
+    mockSocketState.socket = null;
+    mockSocketState.connected = false;
+
+    render(<SocketDemo />);
+    expect(screen.getByText('Status: disconnected')).toBeInTheDocument();
+  });
+
+  it('Send Ping button becomes enabled when socket reconnects', () => {
+    // Simulate reconnection: connected=true and socket object available
+    mockSocketState.mockOnce.mockReset();
+    mockSocketState.mockEmit.mockReset();
+    mockSocketState.socket = {
+      once: mockSocketState.mockOnce,
+      emit: mockSocketState.mockEmit,
+    };
+    mockSocketState.connected = true;
+
+    render(<SocketDemo />);
+    const button = screen.getByRole('button', { name: 'Send Ping' });
+    expect(button).not.toBeDisabled();
+  });
+});

package/template/client/src/demo/SocketDemo.tsx

@@ -0,0 +1,65 @@
+import { useState } from 'react';
+import { SOCKET_EVENTS } from '@appystack-template/shared';
+import { useSocket } from '../hooks/useSocket.js';
+import { cn } from '@/lib/utils.js';
+
+interface PongResponse {
+  message: string;
+  timestamp: string;
+}
+
+export default function SocketDemo() {
+  const { socket, connected } = useSocket();
+  const [lastPong, setLastPong] = useState<PongResponse | null>(null);
+  const [waiting, setWaiting] = useState(false);
+
+  const sendPing = () => {
+    if (!socket || !connected) return;
+
+    setWaiting(true);
+
+    socket.once(SOCKET_EVENTS.SERVER_PONG, (data) => {
+      setLastPong(data);
+      setWaiting(false);
+    });
+
+    socket.emit(SOCKET_EVENTS.CLIENT_PING);
+  };
+
+  return (
+    <div className="rounded-xl p-5 bg-card border border-border">
+      <div className="flex items-center gap-2 mb-3">
+        <span
+          className={`inline-block w-3 h-3 rounded-full ${connected ? 'bg-green-500' : 'bg-red-500'}`}
+        />
+        <h3 className="text-lg font-semibold text-foreground">Socket.io Demo</h3>
+      </div>
+
+      <div className="text-sm space-y-3 text-muted-foreground">
+        <p>Status: {connected ? 'connected' : 'disconnected'}</p>
+
+        <button
+          onClick={sendPing}
+          disabled={!connected || waiting}
+          className={cn(
+            'px-4 py-2 rounded text-sm font-medium transition-colors disabled:opacity-50 disabled:cursor-not-allowed',
+            connected
+              ? 'bg-primary text-primary-foreground'
+              : 'bg-card border border-border text-muted-foreground'
+          )}
+        >
+          {waiting ? 'Waiting for pong...' : 'Send Ping'}
+        </button>
+
+        {lastPong && (
+          <div className="mt-3 p-3 rounded text-sm bg-background border border-primary">
+            <p className="text-primary">server:pong received — {lastPong.message}</p>
+            <p className="mt-1 text-primary/70">
+              {new Date(lastPong.timestamp).toLocaleTimeString()}
+            </p>
+          </div>
+        )}
+      </div>
+    </div>
+  );
+}

package/template/client/src/demo/StatusGrid.test.tsx

@@ -0,0 +1,181 @@
+import { describe, it, expect, beforeAll, beforeEach, afterAll, afterEach, vi } from 'vitest';
+import { render, screen, waitFor } from '@testing-library/react';
+import express from 'express';
+import type { Server } from 'node:http';
+import type { AddressInfo } from 'node:net';
+import StatusGrid from './StatusGrid.js';
+
+// Capture the native fetch at module load time, before any test setup stubs it
+const nativeFetch = globalThis.fetch;
+
+let server: Server;
+let serverPort: number;
+
+beforeAll(() => {
+  return new Promise<void>((resolve) => {
+    const app = express();
+
+    app.get('/health', (_req, res) => {
+      res.json({ status: 'ok', data: { status: 'ok' }, timestamp: new Date().toISOString() });
+    });
+
+    app.get('/api/info', (_req, res) => {
+      res.json({
+        status: 'ok',
+        data: {
+          nodeVersion: 'v20.0.0',
+          environment: 'test',
+          port: 5501,
+          clientUrl: 'http://localhost:5500',
+          uptime: 99,
+        },
+      });
+    });
+
+    server = app.listen(0, () => {
+      serverPort = (server.address() as AddressInfo).port;
+      resolve();
+    });
+  });
+});
+
+beforeEach(() => {
+  globalThis.fetch = (input: RequestInfo | URL, init?: RequestInit) => {
+    const url =
+      typeof input === 'string' && input.startsWith('/')
+        ? `http://localhost:${serverPort}${input}`
+        : input;
+    return nativeFetch(url, init);
+  };
+});
+
+afterAll(() => {
+  return new Promise<void>((resolve) => {
+    server.close(() => resolve());
+  });
+});
+
+describe('StatusGrid', () => {
+  it('shows loading state on initial render', () => {
+    render(<StatusGrid />);
+    expect(screen.getByText('Connecting to server...')).toBeInTheDocument();
+  });
+
+  it('renders the status-grid container once loaded', async () => {
+    render(<StatusGrid />);
+    await waitFor(() => expect(screen.getByTestId('status-grid')).toBeInTheDocument(), {
+      timeout: 5000,
+    });
+  });
+
+  it('shows API Health card after loading', async () => {
+    render(<StatusGrid />);
+    await waitFor(() => expect(screen.getByText('API Health')).toBeInTheDocument(), {
+      timeout: 5000,
+    });
+  });
+
+  it('shows WebSocket card after loading', async () => {
+    render(<StatusGrid />);
+    await waitFor(() => expect(screen.getByText('WebSocket')).toBeInTheDocument(), {
+      timeout: 5000,
+    });
+  });
+
+  it('shows Environment card after loading', async () => {
+    render(<StatusGrid />);
+    await waitFor(() => expect(screen.getByText('Environment')).toBeInTheDocument(), {
+      timeout: 5000,
+    });
+  });
+
+  it('shows Runtime card after loading', async () => {
+    render(<StatusGrid />);
+    await waitFor(() => expect(screen.getByText('Runtime')).toBeInTheDocument(), {
+      timeout: 5000,
+    });
+  });
+
+  it('shows server health status ok after loading', async () => {
+    render(<StatusGrid />);
+    await waitFor(() => expect(screen.getByText('Status: ok')).toBeInTheDocument(), {
+      timeout: 5000,
+    });
+  });
+
+  it('shows environment info from server', async () => {
+    render(<StatusGrid />);
+    await waitFor(() => expect(screen.getByText('Mode: test')).toBeInTheDocument(), {
+      timeout: 5000,
+    });
+  });
+});
+
+describe('StatusGrid — error state (server unreachable)', () => {
+  beforeEach(() => {
+    // Override fetch to simulate a server that is completely unreachable
+    vi.stubGlobal('fetch', () => Promise.reject(new Error('Network error')));
+  });
+
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  it('shows error fallback for API Health card', async () => {
+    render(<StatusGrid />);
+    await waitFor(
+      () => {
+        // When health is null and there is an error, the fallback paragraph should appear
+        // StatusGrid renders "Unable to reach server" or the error message
+        const errorTexts = screen.queryAllByText(/Network error|Unable to reach server/);
+        expect(errorTexts.length).toBeGreaterThan(0);
+      },
+      { timeout: 5000 }
+    );
+  });
+
+  it('shows error fallback for Environment card when info is null', async () => {
+    render(<StatusGrid />);
+    await waitFor(
+      () => {
+        // When info is null, both Environment and Runtime cards show the error
+        const errorTexts = screen.queryAllByText(/Network error|No data/);
+        expect(errorTexts.length).toBeGreaterThan(0);
+      },
+      { timeout: 5000 }
+    );
+  });
+});
+
+describe('StatusDot — isolation via StatusGrid', () => {
+  it('renders green indicator dots when server is reachable (ok=true)', async () => {
+    render(<StatusGrid />);
+    await waitFor(() => expect(screen.getByTestId('status-grid')).toBeInTheDocument(), {
+      timeout: 5000,
+    });
+    // After loading with a healthy server, API Health and info cards are ok=true
+    // StatusDot renders bg-green-500 when ok=true
+    const greenDots = document.querySelectorAll('.bg-green-500');
+    expect(greenDots.length).toBeGreaterThan(0);
+  });
+
+  it('renders red indicator dots when server is unreachable (ok=false)', async () => {
+    vi.stubGlobal('fetch', () => Promise.reject(new Error('Network error')));
+
+    render(<StatusGrid />);
+
+    // Wait for loading to complete (the loading text disappears)
+    await waitFor(
+      () => {
+        expect(screen.queryByText('Connecting to server...')).not.toBeInTheDocument();
+      },
+      { timeout: 5000 }
+    );
+
+    // StatusDot renders bg-red-500 when ok=false (health and info both null)
+    const redDots = document.querySelectorAll('.bg-red-500');
+    expect(redDots.length).toBeGreaterThan(0);
+
+    vi.unstubAllGlobals();
+  });
+});

package/template/client/src/demo/StatusGrid.tsx

@@ -0,0 +1,77 @@
+import { useServerStatus } from '../hooks/useServerStatus.js';
+import { useSocket } from '../hooks/useSocket.js';
+
+function StatusDot({ ok }: { ok: boolean }) {
+  return (
+    <span className={`inline-block w-3 h-3 rounded-full ${ok ? 'bg-green-500' : 'bg-red-500'}`} />
+  );
+}
+
+function StatusCard({
+  title,
+  ok,
+  children,
+}: {
+  title: string;
+  ok: boolean;
+  children: React.ReactNode;
+}) {
+  return (
+    <div className="rounded-xl p-5 bg-card border border-border">
+      <div className="flex items-center gap-2 mb-3">
+        <StatusDot ok={ok} />
+        <h3 className="text-lg font-semibold text-foreground">{title}</h3>
+      </div>
+      <div className="text-sm text-muted-foreground">{children}</div>
+    </div>
+  );
+}
+
+export default function StatusGrid() {
+  const { health, info, loading, error } = useServerStatus();
+  const { connected } = useSocket();
+
+  if (loading) {
+    return <div className="text-center py-8 text-muted-foreground">Connecting to server...</div>;
+  }
+
+  return (
+    <div className="grid grid-cols-1 md:grid-cols-2 gap-4" data-testid="status-grid">
+      <StatusCard title="API Health" ok={!!health}>
+        {health ? (
+          <>
+            <p>Status: {health.status}</p>
+          </>
+        ) : (
+          <p className="text-red-400">{error || 'Unable to reach server'}</p>
+        )}
+      </StatusCard>
+
+      <StatusCard title="WebSocket" ok={connected}>
+        <p>Status: {connected ? 'connected' : 'disconnected'}</p>
+      </StatusCard>
+
+      <StatusCard title="Environment" ok={!!info}>
+        {info ? (
+          <>
+            <p>Mode: {info.environment}</p>
+            <p>Port: {info.port}</p>
+          </>
+        ) : (
+          <p className="text-red-400">{error || 'No data'}</p>
+        )}
+      </StatusCard>
+
+      <StatusCard title="Runtime" ok={!!info}>
+        {info ? (
+          <>
+            <p>Node: {info.nodeVersion}</p>
+            <p>Uptime: {Math.floor(info.uptime)}s</p>
+          </>
+        ) : (
+          <p className="text-red-400">{error || 'No data'}</p>
+        )}
+      </StatusCard>
+    </div>
+  );
+}

package/template/client/src/demo/TechStackDisplay.test.tsx

@@ -0,0 +1,63 @@
+import { describe, it, expect } from 'vitest';
+import { render, screen } from '@testing-library/react';
+import TechStackDisplay from './TechStackDisplay.js';
+
+describe('TechStackDisplay', () => {
+  it('renders the Tech Stack heading', () => {
+    render(<TechStackDisplay />);
+    expect(screen.getByText('Tech Stack')).toBeInTheDocument();
+  });
+
+  it('renders the Client category', () => {
+    render(<TechStackDisplay />);
+    expect(screen.getByText('Client')).toBeInTheDocument();
+  });
+
+  it('renders the Server category', () => {
+    render(<TechStackDisplay />);
+    expect(screen.getByText('Server')).toBeInTheDocument();
+  });
+
+  it('renders the Cross-cutting category', () => {
+    render(<TechStackDisplay />);
+    expect(screen.getByText('Cross-cutting')).toBeInTheDocument();
+  });
+
+  it('renders the Testing & Quality category', () => {
+    render(<TechStackDisplay />);
+    expect(screen.getByText('Testing & Quality')).toBeInTheDocument();
+  });
+
+  it('renders all 4 categories in the tech stack', () => {
+    render(<TechStackDisplay />);
+    const container = screen.getByTestId('tech-stack');
+    // 4 category headings: Client, Server, Cross-cutting, Testing & Quality
+    const categoryHeadings = container.querySelectorAll('h3');
+    expect(categoryHeadings).toHaveLength(4);
+  });
+
+  it('renders React in the Client category', () => {
+    render(<TechStackDisplay />);
+    expect(screen.getByText('React')).toBeInTheDocument();
+  });
+
+  it('renders Express in the Server category', () => {
+    render(<TechStackDisplay />);
+    expect(screen.getByText('Express')).toBeInTheDocument();
+  });
+
+  it('renders TypeScript in the Cross-cutting category', () => {
+    render(<TechStackDisplay />);
+    expect(screen.getByText('TypeScript')).toBeInTheDocument();
+  });
+
+  it('renders Vitest in the Testing & Quality category', () => {
+    render(<TechStackDisplay />);
+    expect(screen.getByText('Vitest')).toBeInTheDocument();
+  });
+
+  it('renders the data-testid attribute', () => {
+    render(<TechStackDisplay />);
+    expect(screen.getByTestId('tech-stack')).toBeInTheDocument();
+  });
+});

package/template/client/src/demo/TechStackDisplay.tsx

@@ -0,0 +1,75 @@
+interface TechItem {
+  name: string;
+  version: string;
+  description: string;
+}
+
+interface TechCategory {
+  title: string;
+  items: TechItem[];
+}
+
+const techStack: TechCategory[] = [
+  {
+    title: 'Client',
+    items: [
+      { name: 'React', version: '19', description: 'UI component library' },
+      { name: 'Vite', version: '7', description: 'Build tool & dev server' },
+      { name: 'TailwindCSS', version: '4', description: 'Utility-first CSS framework' },
+      { name: 'Socket.io Client', version: '4', description: 'Real-time WebSocket client' },
+    ],
+  },
+  {
+    title: 'Server',
+    items: [
+      { name: 'Express', version: '5', description: 'HTTP server framework' },
+      { name: 'Socket.io', version: '4', description: 'Real-time WebSocket server' },
+      { name: 'Pino', version: '9', description: 'High-performance JSON logger' },
+      { name: 'Zod', version: '3', description: 'TypeScript-first schema validation' },
+    ],
+  },
+  {
+    title: 'Cross-cutting',
+    items: [
+      { name: 'TypeScript', version: '5', description: 'Type-safe JavaScript' },
+      { name: 'ESLint', version: '9', description: 'Flat config linting' },
+      { name: 'Prettier', version: '3', description: 'Code formatting' },
+      { name: 'npm Workspaces', version: '-', description: 'Monorepo package management' },
+    ],
+  },
+  {
+    title: 'Testing & Quality',
+    items: [
+      { name: 'Vitest', version: '4', description: 'Unit & integration testing' },
+      { name: 'Testing Library', version: '16', description: 'React component testing' },
+      { name: 'Supertest', version: '7', description: 'HTTP assertion testing' },
+      { name: 'Helmet', version: '8', description: 'Security headers middleware' },
+    ],
+  },
+];
+
+export default function TechStackDisplay() {
+  return (
+    <div data-testid="tech-stack">
+      <h2 className="text-2xl font-bold mb-6 text-foreground">Tech Stack</h2>
+      <div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-4 gap-4">
+        {techStack.map((category) => (
+          <div key={category.title} className="rounded-xl p-5 bg-card border border-border">
+            <h3 className="text-lg font-semibold mb-3 text-primary">{category.title}</h3>
+            <ul className="space-y-2">
+              {category.items.map((item) => (
+                <li key={item.name}>
+                  <span className="font-medium text-foreground">{item.name}</span>
+                  {item.version !== '-' && (
+                    <span className="text-xs ml-1 text-muted-foreground">v{item.version}</span>
+                  )}
+                  <p className="text-xs text-muted-foreground">{item.description}</p>
+                </li>
+              ))}
+            </ul>
+          </div>
+        ))}
+      </div>
+    </div>
+  );
+}