groundwork-method 0.0.1 → 0.11.0

package/src/generators/nextjs-app/files/app/api/proxy/__path__/route.ts.template

@@ -0,0 +1,126 @@
+import { NextRequest, NextResponse } from "next/server";
+<% if (auth === 'clerk') { %>import { auth } from "@clerk/nextjs/server";<% } %>
+import { trace, context, propagation, metrics } from "@opentelemetry/api";
+
+/**
+ * Server-side reverse proxy to the backend API.
+ *
+ * All client-side API calls go to `/api/proxy/<path>` and this Route Handler
+ * forwards them to the backend service. The backend URL is read from the
+ * `API_URL` environment variable at **runtime** — no build-time coupling.
+ *<% if (auth === 'clerk') { %>
+ * Authentication:
+ *  - Injects the user's Clerk session JWT into the Authorization header.
+ *  - If the user isn't authenticated, clerkMiddleware will have already
+ *    blocked the request before it reaches this handler.
+ *<% } %>
+ * Distributed Tracing:
+ *  - Injects the server-side `traceparent`/`tracestate` headers via OTel
+ *    propagation, creating end-to-end traces across services.
+ */
+
+/** Headers that should NOT be forwarded to the upstream. */
+const HOP_BY_HOP = new Set([
+    "connection",
+    "keep-alive",
+    "transfer-encoding",
+    "te",
+    "trailer",
+    "upgrade",
+    "host",
+]);
+
+// Custom metric: counts proxied requests, labelled by upstream route + method.
+// Exported via the PeriodicExportingMetricReader configured in instrumentation.ts.
+const proxyMeter = metrics.getMeter("<%= fileName %>-proxy");
+const proxyRequestCounter = proxyMeter.createCounter("proxy_requests_total", {
+    description: "Total number of requests forwarded by the API proxy.",
+});
+
+function getUpstreamUrl(request: NextRequest, path: string[]): string {
+    const base = process.env.API_URL ?? "http://localhost:4000";
+    const joined = `/${path.join("/")}`;
+    const search = request.nextUrl.search;
+    return `${base}${joined}${search}`;
+}
+
+async function forwardHeaders(incoming: Headers): Promise<HeadersInit> {
+    const out: Record<string, string> = {};
+
+    incoming.forEach((value, key) => {
+        if (!HOP_BY_HOP.has(key.toLowerCase())) {
+            out[key] = value;
+        }
+    });
+<% if (auth === 'clerk') { %>
+    // Inject the user's Clerk session JWT for authenticated requests.
+    try {
+        const { getToken } = await auth();
+        const clerkToken = await getToken();
+        if (clerkToken) {
+            out.Authorization = `Bearer ${clerkToken}`;
+        }
+    } catch {
+        // Auth failed - continue without token
+    }
+<% } %>
+    // Inject the server-side OTel trace context (traceparent + tracestate)
+    propagation.inject(context.active(), out);
+
+    return out;
+}
+
+async function handler(
+    request: NextRequest,
+    { params }: { params: Promise<{ path: string[] }> }
+): Promise<NextResponse> {
+    const { path } = await params;
+    const url = getUpstreamUrl(request, path);
+
+    const activeSpan = trace.getActiveSpan();
+    if (activeSpan) {
+        activeSpan.setAttribute("proxy.upstream_path", `/${path.join("/")}`);
+    }
+
+    proxyRequestCounter.add(1, {
+        "http.route": `/${path.join("/")}`,
+        "http.method": request.method,
+    });
+
+    try {
+        const upstream = await fetch(url, {
+            method: request.method,
+            headers: await forwardHeaders(request.headers),
+            body: request.body,
+            // @ts-expect-error -- Node fetch supports duplex for streaming request bodies
+            duplex: "half",
+        });
+
+        // Build response, forwarding status and filtered headers.
+        const responseHeaders = new Headers();
+        upstream.headers.forEach((value, key) => {
+            if (!HOP_BY_HOP.has(key.toLowerCase())) {
+                responseHeaders.set(key, value);
+            }
+        });
+
+        return new NextResponse(upstream.body, {
+            status: upstream.status,
+            statusText: upstream.statusText,
+            headers: responseHeaders,
+        });
+    } catch (err) {
+        // eslint-disable-next-line no-console
+        console.error("[api/proxy] upstream error:", err);
+        return NextResponse.json(
+            { detail: "Backend service unavailable" },
+            { status: 502 }
+        );
+    }
+}
+
+export const GET = handler;
+export const POST = handler;
+export const PUT = handler;
+export const PATCH = handler;
+export const DELETE = handler;

package/src/generators/nextjs-app/files/app/error.tsx

@@ -0,0 +1,39 @@
+"use client";
+
+/**
+ * Route-level error boundary.
+ *
+ * Catches errors thrown by page components within a route segment.
+ * Must be a Client Component.
+ */
+export default function Error({
+  error,
+  reset,
+}: {
+  error: Error & { digest?: string };
+  reset: () => void;
+}) {
+  return (
+    <div className="flex min-h-screen flex-col items-center justify-center gap-4 p-8 text-center">
+      <div className="space-y-2">
+        <h2 className="text-xl font-semibold tracking-tight text-foreground">
+          Something went wrong
+        </h2>
+        <p className="text-sm text-muted-foreground">
+          An error occurred while loading this page.
+        </p>
+        {error.digest && (
+          <p className="font-mono text-xs text-muted-foreground">
+            Error ID: {error.digest}
+          </p>
+        )}
+      </div>
+      <button
+        onClick={reset}
+        className="inline-flex items-center rounded-md bg-primary px-4 py-2 text-sm font-medium text-primary-foreground shadow-sm transition-colors hover:bg-primary/90"
+      >
+        Try again
+      </button>
+    </div>
+  );
+}

package/src/generators/nextjs-app/files/app/global-error.tsx

@@ -0,0 +1,68 @@
+"use client";
+
+/**
+ * Global error boundary.
+ *
+ * Catches errors thrown by the root layout itself (e.g., provider import
+ * failure). This is the last-resort fallback — it replaces the entire
+ * <html> since the root layout may be broken.
+ */
+export default function GlobalError({
+  error,
+  reset,
+}: {
+  error: Error & { digest?: string };
+  reset: () => void;
+}) {
+  return (
+    <html lang="en">
+      <body
+        style={{
+          display: "flex",
+          minHeight: "100vh",
+          alignItems: "center",
+          justifyContent: "center",
+          fontFamily: "system-ui, sans-serif",
+          backgroundColor: "#0a0a0f",
+          color: "#fafafa",
+        }}
+      >
+        <div style={{ textAlign: "center", maxWidth: "24rem", padding: "2rem" }}>
+          <h2 style={{ fontSize: "1.25rem", fontWeight: 600, marginBottom: "0.5rem" }}>
+            Something went wrong
+          </h2>
+          <p style={{ fontSize: "0.875rem", color: "#a1a1aa", marginBottom: "1rem" }}>
+            A critical error occurred. This has been logged.
+          </p>
+          {error.digest && (
+            <p
+              style={{
+                fontSize: "0.75rem",
+                color: "#71717a",
+                fontFamily: "monospace",
+                marginBottom: "1rem",
+              }}
+            >
+              Error ID: {error.digest}
+            </p>
+          )}
+          <button
+            onClick={reset}
+            style={{
+              padding: "0.5rem 1rem",
+              fontSize: "0.875rem",
+              fontWeight: 500,
+              borderRadius: "0.375rem",
+              border: "1px solid #27272a",
+              backgroundColor: "#18181b",
+              color: "#fafafa",
+              cursor: "pointer",
+            }}
+          >
+            Try again
+          </button>
+        </div>
+      </body>
+    </html>
+  );
+}

package/src/generators/nextjs-app/files/app/globals.css

@@ -0,0 +1,105 @@
+@import "tailwindcss";
+@import "tw-animate-css";
+/* Brand + atmosphere values are GENERATED into brand.css from
+   .groundwork/config/brand-tokens.json by the nextjs-app generator (parity with
+   electron-app/flutter-app). This file owns the structure — token mappings and
+   surface utilities — never the values. Re-run the design system and regenerate
+   to evolve the brand; do not hand-edit brand.css. */
+@import "./brand.css";
+
+@custom-variant dark (&:is(.dark *));
+
+@theme inline {
+  --color-background: var(--background);
+  --color-foreground: var(--foreground);
+  --font-sans: var(--font-geist-sans);
+  --font-mono: var(--font-geist-mono);
+  --color-sidebar-ring: var(--sidebar-ring);
+  --color-sidebar-border: var(--sidebar-border);
+  --color-sidebar-accent-foreground: var(--sidebar-accent-foreground);
+  --color-sidebar-accent: var(--sidebar-accent);
+  --color-sidebar-primary-foreground: var(--sidebar-primary-foreground);
+  --color-sidebar-primary: var(--sidebar-primary);
+  --color-sidebar-foreground: var(--sidebar-foreground);
+  --color-sidebar: var(--sidebar);
+  --color-chart-5: var(--chart-5);
+  --color-chart-4: var(--chart-4);
+  --color-chart-3: var(--chart-3);
+  --color-chart-2: var(--chart-2);
+  --color-chart-1: var(--chart-1);
+  --color-ring: var(--ring);
+  --color-input: var(--input);
+  --color-border: var(--border);
+  --color-destructive: var(--destructive);
+  --color-success: var(--success);
+  --color-warning: var(--warning);
+  --color-info: var(--info);
+  --color-accent-foreground: var(--accent-foreground);
+  --color-accent: var(--accent);
+  --color-muted-foreground: var(--muted-foreground);
+  --color-muted: var(--muted);
+  --color-secondary-foreground: var(--secondary-foreground);
+  --color-secondary: var(--secondary);
+  --color-primary-foreground: var(--primary-foreground);
+  --color-primary: var(--primary);
+  --color-popover-foreground: var(--popover-foreground);
+  --color-popover: var(--popover);
+  --color-card-foreground: var(--card-foreground);
+  --color-card: var(--card);
+  --radius-sm: calc(var(--radius) - 4px);
+  --radius-md: calc(var(--radius) - 2px);
+  --radius-lg: var(--radius);
+  --radius-xl: calc(var(--radius) + 4px);
+
+  /* Atmosphere tokens — values projected into brand.css; theme-aware via the
+     --gw-* custom properties (which the .dark block overrides). Generates the
+     shadow-low/mid/high, blur-*, and backdrop-blur-* utilities. */
+  --shadow-low: var(--gw-shadow-low);
+  --shadow-mid: var(--gw-shadow-mid);
+  --shadow-high: var(--gw-shadow-high);
+  --blur-subtle: var(--gw-blur-subtle);
+  --blur-standard: var(--gw-blur-standard);
+  --blur-heavy: var(--gw-blur-heavy);
+}
+
+@layer base {
+  * {
+    @apply border-border;
+  }
+  body {
+    @apply bg-background text-foreground;
+  }
+}
+
+@layer components {
+  /* Per-app surface treatments — the glass/elevated/hero vocabulary that used to
+     be a fixed catalogue in the engineer skill. Structure is stable; the tint,
+     border, blur, shadow, and gradient values are projected per app into brand.css.
+     Components apply these classes; they never hand-author the recipe. */
+  .surface-glass {
+    background-color: var(--gw-surface-glass-tint);
+    -webkit-backdrop-filter: blur(var(--gw-blur-standard));
+    backdrop-filter: blur(var(--gw-blur-standard));
+    border: 1px solid var(--gw-surface-glass-border);
+    box-shadow: var(--gw-shadow-mid);
+    border-radius: var(--radius-lg);
+  }
+  .surface-elevated {
+    background-color: var(--gw-surface-elevated-tint);
+    -webkit-backdrop-filter: blur(var(--gw-blur-heavy));
+    backdrop-filter: blur(var(--gw-blur-heavy));
+    border: 1px solid var(--gw-surface-elevated-border);
+    box-shadow: var(--gw-shadow-high);
+    border-radius: var(--radius-lg);
+  }
+  .surface-hero {
+    position: relative;
+    background-color: var(--gw-surface-hero-tint);
+    background-image: var(--gw-gradient-hero);
+    -webkit-backdrop-filter: blur(var(--gw-blur-standard));
+    backdrop-filter: blur(var(--gw-blur-standard));
+    border: 1px solid var(--gw-surface-hero-border);
+    box-shadow: var(--gw-shadow-high);
+    border-radius: var(--radius-xl);
+  }
+}

package/src/generators/nextjs-app/files/app/layout.tsx

@@ -0,0 +1,59 @@
+import type { Metadata, Viewport } from 'next'
+import { Geist, Geist_Mono } from 'next/font/google'
+import { Toaster } from 'sonner'
+import { ThemeProvider } from '@/components/theme-provider'
+import { TelemetryProvider } from '@/components/providers/telemetry'
+import './globals.css'
+
+const geistSans = Geist({
+  subsets: ["latin"],
+  variable: "--font-geist-sans",
+});
+
+const geistMono = Geist_Mono({
+  subsets: ["latin"],
+  variable: "--font-geist-mono",
+});
+
+export const metadata: Metadata = {
+  title: '<%= className %>',
+  description: '<%= className %> — powered by GroundWork',
+}
+
+export const viewport: Viewport = {
+  themeColor: [
+    { media: '(prefers-color-scheme: light)', color: '#fafafa' },
+    { media: '(prefers-color-scheme: dark)', color: '#1a1a1f' },
+  ],
+}
+
+export default async function RootLayout({
+  children,
+}: Readonly<{
+  children: React.ReactNode
+}>) {
+<% if (auth === 'clerk') { %>
+  const { default: Providers } = await import('@/components/providers/production')
+<% } else { %>
+  const { default: Providers } = await import('@/components/providers/default')
+<% } %>
+
+  return (
+    <html lang="en" suppressHydrationWarning>
+      <body className={`${geistSans.variable} ${geistMono.variable} font-sans antialiased`}>
+        <TelemetryProvider />
+        <ThemeProvider
+          attribute="class"
+          defaultTheme="dark"
+          enableSystem
+          disableTransitionOnChange
+        >
+          <Providers>
+            {children}
+            <Toaster position="bottom-right" richColors closeButton />
+          </Providers>
+        </ThemeProvider>
+      </body>
+    </html>
+  )
+}

package/src/generators/nextjs-app/files/app/loading.tsx

@@ -0,0 +1,13 @@
+/**
+ * Root loading UI.
+ *
+ * Rendered as a fallback while the page is loading. Next.js wraps
+ * the page component in a Suspense boundary using this component.
+ */
+export default function Loading() {
+  return (
+    <div className="flex min-h-screen items-center justify-center">
+      <div className="h-8 w-8 animate-spin rounded-full border-4 border-muted border-t-primary" />
+    </div>
+  );
+}

package/src/generators/nextjs-app/files/app/not-found.tsx

@@ -0,0 +1,30 @@
+import Link from "next/link";
+
+/**
+ * Root 404 page.
+ *
+ * Rendered when no route matches. This is a Server Component.
+ */
+export default function NotFound() {
+  return (
+    <div className="flex min-h-screen flex-col items-center justify-center gap-4 p-8 text-center">
+      <div className="space-y-2">
+        <h1 className="text-6xl font-bold tracking-tighter text-foreground">
+          404
+        </h1>
+        <h2 className="text-xl font-semibold tracking-tight text-foreground">
+          Page not found
+        </h2>
+        <p className="text-sm text-muted-foreground">
+          The page you&apos;re looking for doesn&apos;t exist or has been moved.
+        </p>
+      </div>
+      <Link
+        href="/"
+        className="inline-flex items-center rounded-md bg-primary px-4 py-2 text-sm font-medium text-primary-foreground shadow-sm transition-colors hover:bg-primary/90"
+      >
+        Go home
+      </Link>
+    </div>
+  );
+}

package/src/generators/nextjs-app/files/app/page.tsx

@@ -0,0 +1,20 @@
+/**
+ * Home page — Server Component.
+ *
+ * This is the landing page for the application. Replace this with
+ * your actual home page content.
+ */
+export default function HomePage() {
+  return (
+    <main className="flex min-h-screen flex-col items-center justify-center gap-6 p-8">
+      <div className="space-y-2 text-center">
+        <h1 className="text-4xl font-bold tracking-tighter text-foreground">
+          <%= className %>
+        </h1>
+        <p className="text-muted-foreground">
+          Your Next.js application is running.
+        </p>
+      </div>
+    </main>
+  );
+}

package/src/generators/nextjs-app/files/components/providers/default.tsx

@@ -0,0 +1,19 @@
+"use client";
+
+/**
+ * Default layout provider.
+ *
+ * Used when no authentication provider is configured.
+ * Serves as a passthrough — add cross-cutting client providers here
+ * (analytics, feature flags, etc.) as the project grows.
+ */
+
+import type { ReactNode } from "react";
+
+export default function DefaultLayoutProvider({
+  children,
+}: {
+  children: ReactNode;
+}) {
+  return <>{children}</>;
+}

package/src/generators/nextjs-app/files/components/providers/production.tsx

@@ -0,0 +1,32 @@
+"use client";
+
+/**
+ * Production layout provider.
+ *
+ * Wraps children with:
+ * 1. ClerkProvider — authentication
+ *
+ * Exported as `default` so layout.tsx can `await import()` uniformly.
+ */
+
+import { ClerkProvider } from "@clerk/nextjs";
+import { dark } from "@clerk/themes";
+import type { ReactNode } from "react";
+
+export default function ProductionLayoutProvider({
+  children,
+}: {
+  children: ReactNode;
+}) {
+  return (
+    <ClerkProvider
+      appearance={{ theme: dark }}
+      signInUrl="/sign-in"
+      signUpUrl="/sign-up"
+      signInFallbackRedirectUrl="/"
+      signUpFallbackRedirectUrl="/"
+    >
+      {children}
+    </ClerkProvider>
+  );
+}

package/src/generators/nextjs-app/files/components/providers/telemetry.tsx

@@ -0,0 +1,76 @@
+"use client";
+
+import { useEffect } from "react";
+
+/**
+ * Browser-side OpenTelemetry: traces client `fetch()` calls and propagates W3C
+ * traceparent to same-origin requests (the /api/proxy route continues the trace
+ * server-side). Scoped to fetch instrumentation to keep the client bundle small.
+ *
+ * Endpoint is read from NEXT_PUBLIC_OTEL_EXPORTER_OTLP_ENDPOINT (must be
+ * browser-reachable — the in-container `jaeger:4318` is NOT reachable from a
+ * browser, so default to localhost).
+ */
+export function TelemetryProvider() {
+    useEffect(() => {
+        let shutdown: (() => Promise<void>) | undefined;
+
+        (async () => {
+            const { WebTracerProvider, BatchSpanProcessor } = await import(
+                "@opentelemetry/sdk-trace-web"
+            );
+            const { OTLPTraceExporter } = await import(
+                "@opentelemetry/exporter-trace-otlp-http"
+            );
+            const { ZoneContextManager } = await import(
+                "@opentelemetry/context-zone"
+            );
+            const { FetchInstrumentation } = await import(
+                "@opentelemetry/instrumentation-fetch"
+            );
+            const { registerInstrumentations } = await import(
+                "@opentelemetry/instrumentation"
+            );
+            const { resourceFromAttributes } = await import(
+                "@opentelemetry/resources"
+            );
+            const { ATTR_SERVICE_NAME } = await import(
+                "@opentelemetry/semantic-conventions"
+            );
+
+            const endpoint =
+                process.env.NEXT_PUBLIC_OTEL_EXPORTER_OTLP_ENDPOINT ??
+                "http://localhost:4318";
+
+            const provider = new WebTracerProvider({
+                resource: resourceFromAttributes({
+                    [ATTR_SERVICE_NAME]: "browser",
+                }),
+                spanProcessors: [
+                    new BatchSpanProcessor(
+                        new OTLPTraceExporter({ url: `${endpoint}/v1/traces` })
+                    ),
+                ],
+            });
+
+            provider.register({ contextManager: new ZoneContextManager() });
+
+            registerInstrumentations({
+                instrumentations: [
+                    new FetchInstrumentation({
+                        // Propagate traceparent to same-origin /api/proxy calls.
+                        propagateTraceHeaderCorsUrls: [/.*/],
+                    }),
+                ],
+            });
+
+            shutdown = () => provider.shutdown();
+        })();
+
+        return () => {
+            void shutdown?.();
+        };
+    }, []);
+
+    return null;
+}

package/src/generators/nextjs-app/files/components/render-smoke.test.tsx

@@ -0,0 +1,29 @@
+import { describe, it, expect } from "vitest";
+import { render } from "@testing-library/react";
+import Loading from "@/app/loading";
+
+/**
+ * Component render tests — Tier 1 of the visual verification loop.
+ *
+ * A page-level behavioural test passes while a component throws on a prop or
+ * state combination it was never rendered with; this layer catches that in
+ * isolation, before any page integrates the component. Every component should
+ * render without throwing across the states the design system names — default,
+ * loading, empty, error, and long-content — not only the populated happy path.
+ *
+ * This example proves the harness on the scaffold's own `Loading` component.
+ * A bet extends this pattern per component it delivers, one `describe` block per
+ * component with one `it` per named state:
+ *
+ *   describe("UserCard", () => {
+ *     it("renders default", () => expect(render(<UserCard user={u} />).container.firstChild).not.toBeNull());
+ *     it("renders empty", () => expect(render(<UserCard user={null} />).container.firstChild).not.toBeNull());
+ *     it("renders long content", () => expect(render(<UserCard user={longName} />).container.firstChild).not.toBeNull());
+ *   });
+ */
+describe("Loading", () => {
+  it("renders without throwing", () => {
+    const { container } = render(<Loading />);
+    expect(container.firstChild).not.toBeNull();
+  });
+});

package/src/generators/nextjs-app/files/components/theme-provider.tsx

@@ -0,0 +1,11 @@
+'use client'
+
+import * as React from 'react'
+import {
+  ThemeProvider as NextThemesProvider,
+  type ThemeProviderProps,
+} from 'next-themes'
+
+export function ThemeProvider({ children, ...props }: ThemeProviderProps) {
+  return <NextThemesProvider {...props}>{children}</NextThemesProvider>
+}

package/src/generators/nextjs-app/files/components.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "https://ui.shadcn.com/schema.json",
+  "style": "new-york",
+  "rsc": true,
+  "tsx": true,
+  "tailwind": {
+    "config": "",
+    "css": "app/globals.css",
+    "baseColor": "neutral",
+    "cssVariables": true,
+    "prefix": ""
+  },
+  "aliases": {
+    "components": "@/components",
+    "utils": "@/lib/utils",
+    "ui": "@/components/ui",
+    "lib": "@/lib",
+    "hooks": "@/hooks"
+  },
+  "iconLibrary": "lucide"
+}