create-appystack 0.1.0

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

@@ -0,0 +1,67 @@
+import { describe, it, expect, beforeAll, beforeEach, afterAll } from 'vitest';
+import { render, screen, waitFor } from '@testing-library/react';
+import express from 'express';
+import type { Server } from 'node:http';
+import App from './App.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(
+  () =>
+    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());
+    })
+);
+
+describe('App', () => {
+  it('renders the tagline from LandingPage', async () => {
+    render(<App />);
+    expect(screen.getByText(/Production-ready RVETS stack boilerplate/)).toBeInTheDocument();
+  });
+
+  it('displays the status grid from DemoPage (DEV mode)', async () => {
+    render(<App />);
+    await waitFor(() => expect(screen.getByTestId('status-grid')).toBeInTheDocument(), {
+      timeout: 5000,
+    });
+  });
+
+  it('displays the tech stack section from DemoPage (DEV mode)', async () => {
+    render(<App />);
+    await waitFor(() => expect(screen.getByTestId('tech-stack')).toBeInTheDocument());
+  });
+});

package/template/client/src/App.tsx

@@ -0,0 +1,11 @@
+import DemoPage from './demo/DemoPage.js';
+import LandingPage from './pages/LandingPage.js';
+
+export default function App() {
+  return (
+    <>
+      <LandingPage />
+      {import.meta.env.DEV && <DemoPage />}
+    </>
+  );
+}

package/template/client/src/components/ErrorFallback.test.tsx

@@ -0,0 +1,64 @@
+import { describe, it, expect, vi } from 'vitest';
+import { render, screen, fireEvent } from '@testing-library/react';
+import ErrorFallback from './ErrorFallback.js';
+
+describe('ErrorFallback', () => {
+  it('renders the error message', () => {
+    const error = new Error('Something exploded');
+    const resetErrorBoundary = vi.fn();
+
+    render(<ErrorFallback error={error} resetErrorBoundary={resetErrorBoundary} />);
+
+    expect(screen.getByText('Something exploded')).toBeInTheDocument();
+  });
+
+  it('renders the "Something went wrong" heading', () => {
+    const error = new Error('Test error');
+    const resetErrorBoundary = vi.fn();
+
+    render(<ErrorFallback error={error} resetErrorBoundary={resetErrorBoundary} />);
+
+    expect(screen.getByText('Something went wrong')).toBeInTheDocument();
+  });
+
+  it('renders the Try again button', () => {
+    const error = new Error('Test error');
+    const resetErrorBoundary = vi.fn();
+
+    render(<ErrorFallback error={error} resetErrorBoundary={resetErrorBoundary} />);
+
+    expect(screen.getByRole('button', { name: 'Try again' })).toBeInTheDocument();
+  });
+
+  it('calls resetErrorBoundary when Try again is clicked', () => {
+    const error = new Error('Test error');
+    const resetErrorBoundary = vi.fn();
+
+    render(<ErrorFallback error={error} resetErrorBoundary={resetErrorBoundary} />);
+
+    fireEvent.click(screen.getByRole('button', { name: 'Try again' }));
+
+    expect(resetErrorBoundary).toHaveBeenCalledOnce();
+  });
+
+  it('has role="alert" on the container', () => {
+    const error = new Error('Alert test');
+    const resetErrorBoundary = vi.fn();
+
+    render(<ErrorFallback error={error} resetErrorBoundary={resetErrorBoundary} />);
+
+    expect(screen.getByRole('alert')).toBeInTheDocument();
+  });
+
+  it('renders non-Error values as strings', () => {
+    const error = 'plain string error';
+    const resetErrorBoundary = vi.fn();
+
+    // FallbackProps expects error to be an Error, but component handles non-Error via String()
+    render(
+      <ErrorFallback error={error as unknown as Error} resetErrorBoundary={resetErrorBoundary} />
+    );
+
+    expect(screen.getByText('plain string error')).toBeInTheDocument();
+  });
+});

package/template/client/src/components/ErrorFallback.tsx

@@ -0,0 +1,18 @@
+import type { FallbackProps } from 'react-error-boundary';
+
+export default function ErrorFallback({ error, resetErrorBoundary }: FallbackProps) {
+  return (
+    <div role="alert" className="p-6 bg-red-900/20 border border-red-500 rounded-lg text-center">
+      <h2 className="text-red-400 text-lg font-bold mb-2">Something went wrong</h2>
+      <pre className="text-red-300 text-sm mb-4">
+        {error instanceof Error ? error.message : String(error)}
+      </pre>
+      <button
+        onClick={resetErrorBoundary}
+        className="px-4 py-2 bg-red-600 text-white rounded hover:bg-red-500"
+      >
+        Try again
+      </button>
+    </div>
+  );
+}

package/template/client/src/config/env.test.ts

@@ -0,0 +1,64 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+
+describe('requireEnv', () => {
+  beforeEach(() => {
+    vi.resetModules();
+  });
+
+  it('throws with "Missing required environment variable: KEY" when key is absent', async () => {
+    vi.stubEnv('VITE_MISSING_KEY', undefined as unknown as string);
+    const { requireEnv } = await import(/* @vite-ignore */ './env.ts');
+    expect(() => requireEnv('VITE_MISSING_KEY')).toThrow(
+      'Missing required environment variable: VITE_MISSING_KEY'
+    );
+    vi.unstubAllEnvs();
+  });
+
+  it('returns the value when key is present', async () => {
+    vi.stubEnv('VITE_MY_VAR', 'hello');
+    const { requireEnv } = await import(/* @vite-ignore */ './env.ts');
+    expect(requireEnv('VITE_MY_VAR')).toBe('hello');
+    vi.unstubAllEnvs();
+  });
+});
+
+describe('optionalEnv', () => {
+  beforeEach(() => {
+    vi.resetModules();
+  });
+
+  it('returns the default when key is absent', async () => {
+    vi.stubEnv('VITE_ABSENT_KEY', undefined as unknown as string);
+    const { optionalEnv } = await import(/* @vite-ignore */ './env.ts');
+    expect(optionalEnv('VITE_ABSENT_KEY', 'fallback')).toBe('fallback');
+    vi.unstubAllEnvs();
+  });
+
+  it('returns the actual value when key is present', async () => {
+    vi.stubEnv('VITE_PRESENT_KEY', 'actual');
+    const { optionalEnv } = await import(/* @vite-ignore */ './env.ts');
+    expect(optionalEnv('VITE_PRESENT_KEY', 'fallback')).toBe('actual');
+    vi.unstubAllEnvs();
+  });
+});
+
+describe('clientEnv', () => {
+  it('has apiUrl and appName fields', async () => {
+    const { clientEnv } = await import(/* @vite-ignore */ './env.ts');
+    expect(clientEnv).toHaveProperty('apiUrl');
+    expect(clientEnv).toHaveProperty('appName');
+  });
+
+  it('apiUrl defaults to empty string when VITE_API_URL is not set', async () => {
+    // In the test environment, VITE_API_URL is not set, so default applies
+    const { clientEnv } = await import(/* @vite-ignore */ './env.ts');
+    // The value is either '' (default) or whatever the test env has configured
+    expect(typeof clientEnv.apiUrl).toBe('string');
+  });
+
+  it('appName defaults to "AppyStack" when VITE_APP_NAME is not set', async () => {
+    const { clientEnv } = await import(/* @vite-ignore */ './env.ts');
+    // In the test environment VITE_APP_NAME is not set, so default should apply
+    expect(clientEnv.appName).toBe('AppyStack');
+  });
+});

package/template/client/src/config/env.ts

@@ -0,0 +1,34 @@
+/**
+ * Require an environment variable to be set.
+ * Throws at module load time if missing.
+ */
+export function requireEnv(key: string): string {
+  const value = import.meta.env[key] as string | undefined;
+  if (!value) {
+    throw new Error(`Missing required environment variable: ${key}`);
+  }
+  return value;
+}
+
+/**
+ * Read an optional environment variable with a fallback default.
+ */
+export function optionalEnv(key: string, defaultValue: string): string {
+  return (import.meta.env[key] as string | undefined) ?? defaultValue;
+}
+
+/**
+ * Validated client environment configuration.
+ * All VITE_ vars are accessed here — not scattered through the codebase.
+ *
+ * To add a new required var: clientEnv.myVar = requireEnv('VITE_MY_VAR')
+ * To add a new optional var: clientEnv.myVar = optionalEnv('VITE_MY_VAR', 'default')
+ */
+export const clientEnv = {
+  /** Base URL for API requests. Empty string uses the Vite dev proxy. */
+  apiUrl: optionalEnv('VITE_API_URL', ''),
+  /** Application display name shown in the UI. */
+  appName: optionalEnv('VITE_APP_NAME', 'AppyStack'),
+  // TODO: Add required vars using requireEnv(), e.g.:
+  // myRequiredVar: requireEnv('VITE_MY_REQUIRED_VAR'),
+};

package/template/client/src/contexts/AppContext.test.tsx

@@ -0,0 +1,81 @@
+import { describe, it, expect } from 'vitest';
+import { render, screen, renderHook, act } from '@testing-library/react';
+import { AppProvider, useApp } from './AppContext.js';
+
+describe('AppProvider', () => {
+  it('renders children', () => {
+    render(
+      <AppProvider>
+        <span>hello</span>
+      </AppProvider>
+    );
+    expect(screen.getByText('hello')).toBeInTheDocument();
+  });
+
+  it('provides initial state with count 0', () => {
+    const { result } = renderHook(() => useApp(), {
+      wrapper: AppProvider,
+    });
+    expect(result.current.state.count).toBe(0);
+  });
+});
+
+describe('AppContext — actions', () => {
+  it('increment action increments count', () => {
+    const { result } = renderHook(() => useApp(), {
+      wrapper: AppProvider,
+    });
+
+    act(() => {
+      result.current.dispatch({ type: 'increment' });
+    });
+
+    expect(result.current.state.count).toBe(1);
+  });
+
+  it('decrement action decrements count', () => {
+    const { result } = renderHook(() => useApp(), {
+      wrapper: AppProvider,
+    });
+
+    act(() => {
+      result.current.dispatch({ type: 'decrement' });
+    });
+
+    expect(result.current.state.count).toBe(-1);
+  });
+
+  it('reset action resets count to 0', () => {
+    const { result } = renderHook(() => useApp(), {
+      wrapper: AppProvider,
+    });
+
+    act(() => {
+      result.current.dispatch({ type: 'increment' });
+      result.current.dispatch({ type: 'increment' });
+      result.current.dispatch({ type: 'increment' });
+    });
+
+    expect(result.current.state.count).toBe(3);
+
+    act(() => {
+      result.current.dispatch({ type: 'reset' });
+    });
+
+    expect(result.current.state.count).toBe(0);
+  });
+});
+
+describe('useApp — error boundary', () => {
+  it('throws when used outside an AppProvider', () => {
+    // Suppress the expected error output from React in the test console
+    const consoleError = console.error;
+    console.error = () => {};
+
+    expect(() => {
+      renderHook(() => useApp());
+    }).toThrow('useApp must be used within an AppProvider');
+
+    console.error = consoleError;
+  });
+});

package/template/client/src/contexts/AppContext.tsx

@@ -0,0 +1,52 @@
+import { createContext, useContext, useReducer, type ReactNode } from 'react';
+
+// TODO: Replace with your actual application state shape
+interface State {
+  count: number;
+}
+
+// TODO: Replace with your actual action types
+type Action = { type: 'increment' } | { type: 'decrement' } | { type: 'reset' };
+
+const initialState: State = { count: 0 };
+
+function reducer(state: State, action: Action): State {
+  switch (action.type) {
+    case 'increment':
+      return { count: state.count + 1 };
+    case 'decrement':
+      return { count: state.count - 1 };
+    case 'reset':
+      return initialState;
+    default:
+      return state;
+  }
+}
+
+interface AppContextValue {
+  state: State;
+  dispatch: React.Dispatch<Action>;
+}
+
+const AppContext = createContext<AppContextValue | null>(null);
+
+/**
+ * Provides global application state to the component tree.
+ * Wrap your app root (or a section of it) with this provider.
+ */
+export function AppProvider({ children }: { children: ReactNode }) {
+  const [state, dispatch] = useReducer(reducer, initialState);
+  return <AppContext.Provider value={{ state, dispatch }}>{children}</AppContext.Provider>;
+}
+
+/**
+ * Access global application state and dispatch.
+ * Must be used within an AppProvider.
+ */
+export function useApp(): AppContextValue {
+  const ctx = useContext(AppContext);
+  if (!ctx) {
+    throw new Error('useApp must be used within an AppProvider');
+  }
+  return ctx;
+}

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

@@ -0,0 +1,97 @@
+import { describe, it, expect, vi } from 'vitest';
+import { render, screen, waitFor } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import ContactForm from './ContactForm.js';
+
+describe('ContactForm — renders', () => {
+  it('renders the name field', () => {
+    render(<ContactForm />);
+    expect(screen.getByLabelText('Name')).toBeInTheDocument();
+  });
+
+  it('renders the email field', () => {
+    render(<ContactForm />);
+    expect(screen.getByLabelText('Email')).toBeInTheDocument();
+  });
+
+  it('renders the message field', () => {
+    render(<ContactForm />);
+    expect(screen.getByLabelText('Message')).toBeInTheDocument();
+  });
+
+  it('renders the submit button', () => {
+    render(<ContactForm />);
+    expect(screen.getByRole('button', { name: 'Send' })).toBeInTheDocument();
+  });
+});
+
+describe('ContactForm — validation errors', () => {
+  it('shows validation error when name is too short', async () => {
+    const user = userEvent.setup();
+    render(<ContactForm />);
+
+    await user.type(screen.getByLabelText('Name'), 'A');
+    await user.click(screen.getByRole('button', { name: 'Send' }));
+
+    await waitFor(() => {
+      const alerts = screen.getAllByRole('alert');
+      const nameError = alerts.find(
+        (el) => el.textContent === 'Name must be at least 2 characters'
+      );
+      expect(nameError).toBeTruthy();
+    });
+  });
+
+  it('shows validation error for invalid email', async () => {
+    const user = userEvent.setup();
+    render(<ContactForm />);
+
+    await user.type(screen.getByLabelText('Email'), 'not-an-email');
+    await user.click(screen.getByRole('button', { name: 'Send' }));
+
+    await waitFor(() => {
+      const alerts = screen.getAllByRole('alert');
+      const emailError = alerts.find((el) => el.textContent === 'Invalid email address');
+      expect(emailError).toBeTruthy();
+    });
+  });
+
+  it('shows validation error when message is too short', async () => {
+    const user = userEvent.setup();
+    render(<ContactForm />);
+
+    await user.type(screen.getByLabelText('Message'), 'Too short');
+    await user.click(screen.getByRole('button', { name: 'Send' }));
+
+    await waitFor(() => {
+      const alerts = screen.getAllByRole('alert');
+      const msgError = alerts.find((el) =>
+        el.textContent?.includes('Message must be at least 10 characters')
+      );
+      expect(msgError).toBeTruthy();
+    });
+  });
+});
+
+describe('ContactForm — valid submission', () => {
+  it('calls onSubmit with correct data when form is valid', async () => {
+    const consoleSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+    const user = userEvent.setup();
+    render(<ContactForm />);
+
+    await user.type(screen.getByLabelText('Name'), 'Alice Example');
+    await user.type(screen.getByLabelText('Email'), 'alice@example.com');
+    await user.type(screen.getByLabelText('Message'), 'Hello, this is a valid test message.');
+    await user.click(screen.getByRole('button', { name: 'Send' }));
+
+    await waitFor(() => {
+      expect(consoleSpy).toHaveBeenCalledWith({
+        name: 'Alice Example',
+        email: 'alice@example.com',
+        message: 'Hello, this is a valid test message.',
+      });
+    });
+
+    consoleSpy.mockRestore();
+  });
+});

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

@@ -0,0 +1,100 @@
+import { useForm } from 'react-hook-form';
+import { zodResolver } from '@hookform/resolvers/zod';
+import { z } from 'zod';
+import { cn } from '@/lib/utils.js';
+
+const schema = z.object({
+  name: z.string().min(2, 'Name must be at least 2 characters'),
+  email: z.string().email('Invalid email address'),
+  message: z.string().min(10, 'Message must be at least 10 characters'),
+});
+
+type FormData = z.infer<typeof schema>;
+
+export default function ContactForm() {
+  const {
+    register,
+    handleSubmit,
+    formState: { errors },
+  } = useForm<FormData>({
+    resolver: zodResolver(schema),
+  });
+
+  const onSubmit = (data: FormData) => {
+    console.log(data); // TODO: wire to your API
+  };
+
+  return (
+    <form onSubmit={handleSubmit(onSubmit)} noValidate className="space-y-4 max-w-md">
+      <div>
+        <label htmlFor="name" className="block text-sm font-medium mb-1 text-muted-foreground">
+          Name
+        </label>
+        <input
+          id="name"
+          type="text"
+          placeholder="Your name"
+          {...register('name')}
+          className={cn(
+            'w-full px-3 py-2 rounded text-sm bg-background text-foreground border',
+            errors.name ? 'border-destructive' : 'border-border'
+          )}
+        />
+        {errors.name && (
+          <span role="alert" className="text-red-400 text-xs mt-1 block">
+            {errors.name.message}
+          </span>
+        )}
+      </div>
+
+      <div>
+        <label htmlFor="email" className="block text-sm font-medium mb-1 text-muted-foreground">
+          Email
+        </label>
+        <input
+          id="email"
+          type="email"
+          placeholder="you@example.com"
+          {...register('email')}
+          className={cn(
+            'w-full px-3 py-2 rounded text-sm bg-background text-foreground border',
+            errors.email ? 'border-destructive' : 'border-border'
+          )}
+        />
+        {errors.email && (
+          <span role="alert" className="text-red-400 text-xs mt-1 block">
+            {errors.email.message}
+          </span>
+        )}
+      </div>
+
+      <div>
+        <label htmlFor="message" className="block text-sm font-medium mb-1 text-muted-foreground">
+          Message
+        </label>
+        <textarea
+          id="message"
+          rows={4}
+          placeholder="Your message..."
+          {...register('message')}
+          className={cn(
+            'w-full px-3 py-2 rounded text-sm resize-none bg-background text-foreground border',
+            errors.message ? 'border-destructive' : 'border-border'
+          )}
+        />
+        {errors.message && (
+          <span role="alert" className="text-red-400 text-xs mt-1 block">
+            {errors.message.message}
+          </span>
+        )}
+      </div>
+
+      <button
+        type="submit"
+        className="px-4 py-2 rounded text-sm font-medium transition-colors bg-primary text-primary-foreground"
+      >
+        Send
+      </button>
+    </form>
+  );
+}

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

@@ -0,0 +1,56 @@
+/**
+ * TEMPLATE DEMO PAGE — delete this file and its references when you start building your app.
+ * Shows all AppyStack template features working together.
+ */
+
+import { useState } from 'react';
+import ContactForm from './ContactForm.js';
+import SocketDemo from './SocketDemo.js';
+import StatusGrid from './StatusGrid.js';
+import TechStackDisplay from './TechStackDisplay.js';
+
+export default function DemoPage() {
+  const [showForm, setShowForm] = useState(false);
+
+  return (
+    <div className="border-t border-border">
+      <div className="max-w-5xl mx-auto px-6 py-4">
+        <p className="text-xs font-mono text-primary/70 uppercase tracking-widest">
+          Template Demo — delete when building your app
+        </p>
+      </div>
+
+      <main className="max-w-5xl mx-auto px-6 py-12 space-y-12">
+        <section>
+          <h2 className="text-2xl font-bold mb-6 text-foreground">System Status</h2>
+          <StatusGrid />
+        </section>
+
+        <section>
+          <h2 className="text-2xl font-bold mb-6 text-foreground">Socket.io</h2>
+          <SocketDemo />
+        </section>
+
+        <section>
+          <TechStackDisplay />
+        </section>
+
+        <section>
+          <button
+            onClick={() => setShowForm((prev) => !prev)}
+            className="text-sm font-medium px-4 py-2 rounded transition-colors bg-card border border-border text-muted-foreground"
+          >
+            {showForm ? 'Hide example form' : 'Show example form'}
+          </button>
+
+          {showForm && (
+            <div className="mt-4 rounded-xl p-6 bg-card border border-border">
+              <h2 className="text-lg font-semibold mb-4 text-foreground">React Hook Form + Zod</h2>
+              <ContactForm />
+            </div>
+          )}
+        </section>
+      </main>
+    </div>
+  );
+}