create-appystack 0.1.0

package/template/client/src/hooks/useServerStatus.test.ts

@@ -0,0 +1,133 @@
+import { describe, it, expect, beforeAll, beforeEach, afterAll, vi } from 'vitest';
+import { renderHook, waitFor } from '@testing-library/react';
+import express from 'express';
+import type { Server } from 'node:http';
+import type { AddressInfo } from 'node:net';
+import { useServerStatus } from './useServerStatus.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: 0,
+          clientUrl: 'http://localhost:5500',
+          uptime: 42,
+        },
+      });
+    });
+
+    app.get('/error', (_req, res) => {
+      res.status(500).json({ status: 'error', error: 'Internal Server Error' });
+    });
+
+    server = app.listen(0, () => {
+      serverPort = (server.address() as AddressInfo).port;
+      resolve();
+    });
+  });
+});
+
+// Route relative fetch calls to the real test server; runs after setup.ts beforeEach stub
+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('useServerStatus', () => {
+  it('starts with loading=true', () => {
+    const { result } = renderHook(() => useServerStatus());
+    expect(result.current.loading).toBe(true);
+    expect(result.current.health).toBeNull();
+    expect(result.current.info).toBeNull();
+    expect(result.current.error).toBeNull();
+  });
+
+  it('fetches /health and sets health state', async () => {
+    const { result } = renderHook(() => useServerStatus());
+
+    await waitFor(() => expect(result.current.loading).toBe(false));
+
+    expect(result.current.health).not.toBeNull();
+    expect(result.current.health?.status).toBe('ok');
+  });
+
+  it('fetches /api/info and sets info state', async () => {
+    const { result } = renderHook(() => useServerStatus());
+
+    await waitFor(() => expect(result.current.loading).toBe(false));
+
+    expect(result.current.info).not.toBeNull();
+    expect(result.current.info?.nodeVersion).toBe('v20.0.0');
+    expect(result.current.info?.environment).toBe('test');
+    expect(typeof result.current.info?.uptime).toBe('number');
+  });
+
+  it('sets error=null on success', async () => {
+    const { result } = renderHook(() => useServerStatus());
+
+    await waitFor(() => expect(result.current.loading).toBe(false));
+
+    expect(result.current.error).toBeNull();
+  });
+
+  it('sets error state when server returns 500', async () => {
+    // Temporarily override fetch to return 500 for both endpoints
+    const savedFetch = globalThis.fetch;
+    globalThis.fetch = vi.fn().mockResolvedValue({
+      ok: false,
+      status: 500,
+      json: async () => ({ status: 'error', error: 'Internal Server Error' }),
+    });
+
+    const { result } = renderHook(() => useServerStatus());
+
+    await waitFor(() => expect(result.current.loading).toBe(false));
+
+    expect(result.current.error).toBe('Server returned an error');
+    expect(result.current.health).toBeNull();
+
+    globalThis.fetch = savedFetch;
+  });
+
+  it('sets error state when server is unreachable', async () => {
+    // Temporarily override fetch to simulate network failure
+    const savedFetch = globalThis.fetch;
+    globalThis.fetch = vi.fn().mockRejectedValue(new Error('Failed to fetch'));
+
+    const { result } = renderHook(() => useServerStatus());
+
+    await waitFor(() => expect(result.current.loading).toBe(false));
+
+    expect(result.current.error).toBe('Failed to fetch');
+    expect(result.current.loading).toBe(false);
+
+    globalThis.fetch = savedFetch;
+  });
+});

package/template/client/src/hooks/useServerStatus.ts

@@ -0,0 +1,67 @@
+import { useEffect, useState } from 'react';
+import type { HealthResponse, ServerInfo } from '@appystack-template/shared';
+
+interface ServerStatus {
+  health: HealthResponse | null;
+  info: ServerInfo | null;
+  loading: boolean;
+  error: string | null;
+}
+
+/**
+ * Fetches server health (/health) and metadata (/api/info) on mount.
+ * @returns health status, server info, loading flag, and error string
+ */
+export function useServerStatus() {
+  const [status, setStatus] = useState<ServerStatus>({
+    health: null,
+    info: null,
+    loading: true,
+    error: null,
+  });
+
+  useEffect(() => {
+    const controller = new AbortController();
+    const signal = AbortSignal.any([controller.signal, AbortSignal.timeout(10000)]);
+
+    async function fetchStatus() {
+      try {
+        const [healthRes, infoRes] = await Promise.all([
+          fetch('/health', { signal }),
+          fetch('/api/info', { signal }),
+        ]);
+
+        if (!healthRes.ok || !infoRes.ok) {
+          throw new Error('Server returned an error');
+        }
+
+        const healthBody = await healthRes.json();
+        const infoBody = await infoRes.json();
+
+        setStatus({
+          health: healthBody.data,
+          info: infoBody.data,
+          loading: false,
+          error: null,
+        });
+      } catch (err) {
+        if (err instanceof Error && err.name === 'AbortError') {
+          return;
+        }
+        setStatus((prev) => ({
+          ...prev,
+          loading: false,
+          error: err instanceof Error ? err.message : 'Failed to connect to server',
+        }));
+      }
+    }
+
+    fetchStatus();
+
+    return () => {
+      controller.abort();
+    };
+  }, []);
+
+  return status;
+}

package/template/client/src/hooks/useSocket.test.ts

@@ -0,0 +1,152 @@
+import { describe, it, expect, beforeAll, afterAll, vi } from 'vitest';
+import { renderHook, waitFor, act } from '@testing-library/react';
+import { createServer } from 'node:http';
+import type { Server as HttpServer } from 'node:http';
+import type { AddressInfo } from 'node:net';
+import { Server as SocketServer } from 'socket.io';
+import type { ServerToClientEvents, ClientToServerEvents } from '@appystack-template/shared';
+import { SOCKET_EVENTS } from '@appystack-template/shared';
+import { useSocket, getSocketUrl } from './useSocket.js';
+
+let httpServer: HttpServer;
+let io: SocketServer<ClientToServerEvents, ServerToClientEvents>;
+let serverPort: number;
+
+beforeAll(() => {
+  return new Promise<void>((resolve) => {
+    httpServer = createServer();
+
+    io = new SocketServer<ClientToServerEvents, ServerToClientEvents>(httpServer, {
+      cors: { origin: '*' },
+    });
+
+    io.on('connection', (socket) => {
+      socket.on(SOCKET_EVENTS.CLIENT_PING, () => {
+        socket.emit(SOCKET_EVENTS.SERVER_PONG, {
+          message: 'pong',
+          timestamp: new Date().toISOString(),
+        });
+      });
+    });
+
+    httpServer.listen(0, () => {
+      serverPort = (httpServer.address() as AddressInfo).port;
+
+      // Set jsdom's location so socket.io-client connects to our test server
+      Object.defineProperty(window, 'location', {
+        value: new URL(`http://localhost:${serverPort}`),
+        writable: true,
+        configurable: true,
+      });
+
+      resolve();
+    });
+  });
+});
+
+afterAll(() => {
+  return new Promise<void>((resolve) => {
+    io.close(() => {
+      httpServer.close(() => resolve());
+    });
+  });
+});
+
+describe('useSocket', () => {
+  it('starts with connected=false', () => {
+    const { result, unmount } = renderHook(() => useSocket());
+    expect(result.current.connected).toBe(false);
+    unmount();
+  });
+
+  it('connects to the server and sets connected=true', async () => {
+    const { result, unmount } = renderHook(() => useSocket());
+
+    await waitFor(
+      () => {
+        expect(result.current.connected).toBe(true);
+      },
+      { timeout: 5000 }
+    );
+
+    unmount();
+  });
+
+  it('exposes the socket instance after connecting', async () => {
+    const { result, unmount } = renderHook(() => useSocket());
+
+    await waitFor(
+      () => {
+        expect(result.current.connected).toBe(true);
+      },
+      { timeout: 5000 }
+    );
+
+    // After connecting, the socket should be accessible
+    // Note: socketRef.current is returned; it may be set after the state update
+    expect(result.current.socket).toBeDefined();
+
+    unmount();
+  });
+
+  it('sets connected=false after unmount (disconnect)', async () => {
+    const { result, unmount } = renderHook(() => useSocket());
+
+    await waitFor(
+      () => {
+        expect(result.current.connected).toBe(true);
+      },
+      { timeout: 5000 }
+    );
+
+    // Capture the socket instance before unmounting so we can verify it is disconnectable
+    const socket = result.current.socket;
+    expect(typeof socket?.disconnect).toBe('function');
+
+    act(() => {
+      unmount();
+    });
+  });
+});
+
+describe('getSocketUrl', () => {
+  it('returns window.location.origin when VITE_SOCKET_URL is not set', () => {
+    // Ensure VITE_SOCKET_URL is absent; vi.stubEnv mutates import.meta.env in place
+    vi.stubEnv('VITE_SOCKET_URL', undefined as unknown as string);
+    // window.location was set in beforeAll to the test server origin
+    expect(getSocketUrl()).toBe(window.location.origin);
+    vi.unstubAllEnvs();
+  });
+
+  it('returns VITE_SOCKET_URL value when it is set', () => {
+    const customUrl = 'http://custom-socket-server:4000';
+    vi.stubEnv('VITE_SOCKET_URL', customUrl);
+    expect(getSocketUrl()).toBe(customUrl);
+    vi.unstubAllEnvs();
+  });
+});
+
+describe('useSocket — connect_error handling', () => {
+  it('exposes a socket that supports registering a connect_error listener without throwing', async () => {
+    const { result, unmount } = renderHook(() => useSocket());
+
+    await waitFor(
+      () => {
+        expect(result.current.connected).toBe(true);
+      },
+      { timeout: 5000 }
+    );
+
+    // Verify that the socket exposes the .on() method so callers can listen for connect_error.
+    // Socket.io reserves connect_error as an internal event — it cannot be user-emitted,
+    // but consumers can register listeners for it. Confirm the hook surface is correct.
+    expect(typeof result.current.socket?.on).toBe('function');
+
+    // Register a connect_error listener — this must not throw
+    expect(() => {
+      result.current.socket?.on('connect_error', () => {});
+    }).not.toThrow();
+
+    unmount();
+  });
+});

package/template/client/src/hooks/useSocket.ts

@@ -0,0 +1,43 @@
+import { useEffect, useRef, useState } from 'react';
+import { io } from 'socket.io-client';
+import type { Socket } from 'socket.io-client';
+import type { ServerToClientEvents, ClientToServerEvents } from '@appystack-template/shared';
+
+/** Typed Socket.io client instance for the AppyStack template event contracts. */
+export type AppSocket = Socket<ServerToClientEvents, ClientToServerEvents>;
+
+// Resolve the socket URL at connection time so test environments can set window.location first.
+// Override via VITE_SOCKET_URL env var if a different server is needed.
+export function getSocketUrl(): string {
+  return (import.meta.env.VITE_SOCKET_URL as string | undefined) ?? window.location.origin;
+}
+
+/**
+ * Socket.io connection hook for the AppyStack template.
+ * @returns socket ref (null until connected) and connected boolean
+ */
+export function useSocket() {
+  const socketRef = useRef<AppSocket | null>(null);
+  const [connected, setConnected] = useState(false);
+
+  useEffect(() => {
+    const socket: AppSocket = io(getSocketUrl(), {
+      transports: ['websocket', 'polling'],
+      reconnection: true,
+      reconnectionAttempts: 5, // give up after 5 attempts; set to Infinity to retry forever
+      reconnectionDelay: 1000, // initial delay before first reconnect attempt (ms)
+      reconnectionDelayMax: 5000, // maximum delay between attempts (ms)
+      randomizationFactor: 0.5, // jitter factor to avoid thundering herd (0 = no jitter)
+    });
+    socketRef.current = socket;
+
+    socket.on('connect', () => setConnected(true));
+    socket.on('disconnect', () => setConnected(false));
+
+    return () => {
+      socket.disconnect();
+    };
+  }, []);
+
+  return { socket: socketRef.current, connected };
+}

package/template/client/src/lib/utils.test.ts

@@ -0,0 +1,33 @@
+import { describe, it, expect } from 'vitest';
+import { cn } from './utils.js';
+
+describe('cn', () => {
+  it('merges class strings', () => {
+    expect(cn('px-4', 'py-2')).toBe('px-4 py-2');
+  });
+
+  it('resolves Tailwind conflicts — later class wins', () => {
+    expect(cn('bg-red-500', 'bg-blue-500')).toBe('bg-blue-500');
+  });
+
+  it('handles conditional classes — falsy values are skipped', () => {
+    const condition = false;
+    expect(cn('base', condition && 'skip', 'keep')).toBe('base keep');
+  });
+
+  it('handles undefined gracefully', () => {
+    expect(cn('a', undefined, 'b')).toBe('a b');
+  });
+
+  it('handles null gracefully', () => {
+    expect(cn('a', null, 'b')).toBe('a b');
+  });
+
+  it('returns empty string when given no arguments', () => {
+    expect(cn()).toBe('');
+  });
+
+  it('handles multiple Tailwind conflicts — last occurrence wins', () => {
+    expect(cn('p-2', 'p-4', 'p-8')).toBe('p-8');
+  });
+});

package/template/client/src/lib/utils.ts

@@ -0,0 +1,14 @@
+import { clsx, type ClassValue } from 'clsx';
+import { twMerge } from 'tailwind-merge';
+
+/**
+ * Merge Tailwind CSS classes without conflicts.
+ * Combines clsx (conditional classes) with tailwind-merge (deduplication).
+ *
+ * @example
+ * cn('bg-red-500', condition && 'text-white', 'bg-blue-500')
+ * // → 'text-white bg-blue-500'  (bg-red-500 is overridden by bg-blue-500)
+ */
+export function cn(...inputs: ClassValue[]): string {
+  return twMerge(clsx(inputs));
+}

package/template/client/src/main.test.tsx

@@ -0,0 +1,113 @@
+import { describe, it, expect, vi, beforeAll, afterAll, beforeEach } from 'vitest';
+import { render, screen } from '@testing-library/react';
+import { StrictMode } from 'react';
+import { ErrorBoundary } from 'react-error-boundary';
+import express from 'express';
+import type { Server } from 'node:http';
+import ErrorFallback from './components/ErrorFallback.js';
+import App from './App.js';
+
+// Capture native fetch before any stub replaces it
+const nativeFetch = globalThis.fetch;
+
+let server: Server;
+let serverPort: number;
+
+beforeAll(
+  () =>
+    new Promise<void>((resolve) => {
+      const app = express();
+      app.get('/health', (_, res) =>
+        res.json({ status: 'ok', timestamp: new Date().toISOString() })
+      );
+      app.get('/api/info', (_, res) =>
+        res.json({
+          status: 'ok',
+          data: { nodeVersion: 'test', environment: 'test', port: 0, clientUrl: '', uptime: 0 },
+        })
+      );
+      server = app.listen(0, () => {
+        serverPort = (server.address() as { port: number }).port;
+        resolve();
+      });
+    })
+);
+
+beforeEach(() => {
+  globalThis.fetch = (input, init) => {
+    const url =
+      typeof input === 'string' && input.startsWith('/')
+        ? `http://localhost:${serverPort}${input}`
+        : input;
+    return nativeFetch(url, init);
+  };
+});
+
+afterAll(
+  () =>
+    new Promise<void>((resolve) => {
+      server?.close(() => resolve());
+    })
+);
+
+// Component that always throws — used to test ErrorBoundary catching
+function ThrowingComponent(): never {
+  throw new Error('deliberate test error');
+}
+
+describe('main.tsx wiring — ErrorBoundary', () => {
+  it('renders without throwing when the app tree is mounted', () => {
+    expect(() =>
+      render(
+        <StrictMode>
+          <ErrorBoundary FallbackComponent={ErrorFallback}>
+            <App />
+          </ErrorBoundary>
+        </StrictMode>
+      )
+    ).not.toThrow();
+  });
+
+  it('shows ErrorFallback when a child component throws', () => {
+    // Suppress the expected console.error from react-error-boundary
+    const consoleSpy = vi.spyOn(console, 'error').mockImplementation(() => undefined);
+
+    render(
+      <StrictMode>
+        <ErrorBoundary FallbackComponent={ErrorFallback}>
+          <ThrowingComponent />
+        </ErrorBoundary>
+      </StrictMode>
+    );
+
+    expect(screen.getByRole('alert')).toBeInTheDocument();
+    expect(screen.getByText('Something went wrong')).toBeInTheDocument();
+    expect(screen.getByText('deliberate test error')).toBeInTheDocument();
+
+    consoleSpy.mockRestore();
+  });
+
+  it('renders a Try again button in the error fallback', () => {
+    const consoleSpy = vi.spyOn(console, 'error').mockImplementation(() => undefined);
+
+    render(
+      <ErrorBoundary FallbackComponent={ErrorFallback}>
+        <ThrowingComponent />
+      </ErrorBoundary>
+    );
+
+    expect(screen.getByRole('button', { name: 'Try again' })).toBeInTheDocument();
+
+    consoleSpy.mockRestore();
+  });
+
+  it('renders App content inside the ErrorBoundary wrapper', () => {
+    render(
+      <ErrorBoundary FallbackComponent={ErrorFallback}>
+        <App />
+      </ErrorBoundary>
+    );
+
+    expect(screen.getByText(/Production-ready RVETS stack boilerplate/)).toBeInTheDocument();
+  });
+});

package/template/client/src/main.tsx

@@ -0,0 +1,14 @@
+import { StrictMode } from 'react';
+import { createRoot } from 'react-dom/client';
+import { ErrorBoundary } from 'react-error-boundary';
+import App from './App.js';
+import ErrorFallback from './components/ErrorFallback.js';
+import './styles/index.css';
+
+createRoot(document.getElementById('root')!).render(
+  <StrictMode>
+    <ErrorBoundary FallbackComponent={ErrorFallback}>
+      <App />
+    </ErrorBoundary>
+  </StrictMode>
+);

package/template/client/src/pages/LandingPage.test.tsx

@@ -0,0 +1,30 @@
+import { describe, it, expect } from 'vitest';
+import { render, screen } from '@testing-library/react';
+import LandingPage from './LandingPage.js';
+
+describe('LandingPage', () => {
+  it('renders the AppyStack ASCII banner tagline', () => {
+    render(<LandingPage />);
+    expect(screen.getByText(/Production-ready RVETS stack boilerplate/)).toBeInTheDocument();
+  });
+
+  it('renders the placeholder content message', () => {
+    render(<LandingPage />);
+    expect(screen.getByText(/Your app content goes here/)).toBeInTheDocument();
+  });
+
+  it('references DemoPage in the placeholder text', () => {
+    render(<LandingPage />);
+    expect(screen.getByText('src/demo/DemoPage.tsx')).toBeInTheDocument();
+  });
+
+  it('renders a main content area', () => {
+    render(<LandingPage />);
+    expect(document.querySelector('main')).toBeInTheDocument();
+  });
+
+  it('renders a header element', () => {
+    render(<LandingPage />);
+    expect(document.querySelector('header')).toBeInTheDocument();
+  });
+});

package/template/client/src/pages/LandingPage.tsx

@@ -0,0 +1,29 @@
+// TODO: Replace this placeholder content with your app
+
+const ASCII_BANNER = `     _                      ____  _             _
+    / \\   _ __  _ __  _   _/ ___|| |_ __ _  ___| | __
+   / _ \\ | '_ \\| '_ \\| | | \\___ \\| __/ _\` |/ __| |/ /
+  / ___ \\| |_) | |_) | |_| |___) | || (_| | (__|   <
+ /_/   \\_\\ .__/| .__/ \\__, |____/ \\__\\__,_|\\___|_|\\_\\
+         |_|   |_|    |___/`;
+
+export default function LandingPage() {
+  return (
+    <div className="min-h-screen">
+      <header className="py-16 text-center bg-background">
+        <pre className="inline-block text-left text-sm md:text-base leading-tight text-primary font-mono">
+          {ASCII_BANNER}
+        </pre>
+        <p className="mt-4 text-lg text-primary/70 font-mono">
+          Production-ready RVETS stack boilerplate
+        </p>
+      </header>
+      <main className="max-w-5xl mx-auto px-6 py-12">
+        {/* TODO: Add your app content here */}
+        <p className="text-muted-foreground text-center">
+          Your app content goes here. See <code>src/demo/DemoPage.tsx</code> for feature examples.
+        </p>
+      </main>
+    </div>
+  );
+}

package/template/client/src/styles/index.css

@@ -0,0 +1,50 @@
+@import 'tailwindcss';
+
+@source "../";
+
+@theme {
+  /* Base */
+  --color-background: oklch(0.152 0.034 260);
+  --color-foreground: oklch(0.966 0.009 246);
+
+  /* Card */
+  --color-card: oklch(0.217 0.041 260);
+  --color-card-foreground: oklch(0.966 0.009 246);
+
+  /* Border */
+  --color-border: oklch(0.33 0.046 259);
+
+  /* Primary — terminal green */
+  --color-primary: oklch(0.723 0.213 142);
+  --color-primary-foreground: oklch(0.152 0.034 260);
+
+  /* Muted */
+  --color-muted: oklch(0.217 0.041 260);
+  --color-muted-foreground: oklch(0.672 0.025 249);
+
+  /* Destructive */
+  --color-destructive: oklch(0.628 0.219 27);
+  --color-destructive-foreground: oklch(0.966 0.009 246);
+}
+
+:root {
+  /* Semantic aliases matching ShadCN convention */
+  --background: oklch(0.152 0.034 260);
+  --foreground: oklch(0.966 0.009 246);
+  --card: oklch(0.217 0.041 260);
+  --border: oklch(0.33 0.046 259);
+  --primary: oklch(0.723 0.213 142);
+  --primary-foreground: oklch(0.152 0.034 260);
+  --muted-foreground: oklch(0.672 0.025 249);
+  --destructive: oklch(0.628 0.219 27);
+}
+
+body {
+  margin: 0;
+  background-color: var(--background);
+  color: var(--foreground);
+  font-family:
+    system-ui,
+    -apple-system,
+    sans-serif;
+}

package/template/client/src/test/msw/browser.ts

@@ -0,0 +1,4 @@
+import { setupWorker } from 'msw/browser';
+import { handlers } from './handlers.js';
+
+export const worker = setupWorker(...handlers);