groundwork-method 0.0.1 → 0.10.0

package/src/engineer-skills/groundwork-nextjs-engineer/references/documentation.md

@@ -0,0 +1,324 @@
+# Documentation
+
+## Table of Contents
+- [Philosophy: Structure Over Comments](#philosophy-structure-over-comments)
+- [Types and Zod as Documentation](#types-and-zod-as-documentation)
+- [What to Document](#what-to-document)
+- [What NOT to Document](#what-not-to-document)
+- [Component Documentation](#component-documentation)
+- [Server and Client Boundary Notes](#server-and-client-boundary-notes)
+- [Hook Documentation](#hook-documentation)
+- [Inline Comments](#inline-comments)
+- [In-Code Markers](#in-code-markers)
+- [Service README Template](#service-readme-template)
+
+---
+
+## Philosophy: Structure Over Comments
+
+Comments are promises that no compiler can verify. When code changes, TypeScript catches type errors and Vitest catches behavioral regressions — but stale TSDoc comments silently mislead. In a codebase where AI agents drive significant code velocity, comment drift is not hypothetical; it is the default outcome.
+
+**The hierarchy for TypeScript/React documentation:**
+1. **TypeScript types and interfaces** — the compiler rejects incorrect types (zero drift risk)
+2. **Zod `.describe()`** — part of the code; flows into validation errors and runtime behavior
+3. **Naming** — descriptive component/function/variable names (refactor > comment)
+4. **Test names** — executable documentation verified by CI
+5. **TSDoc on complex public APIs** — only when types genuinely cannot convey the intent
+6. **Inline "why" comments** — last resort for genuinely non-obvious decisions
+
+Everything at levels 1-4 is verified by tooling. Levels 5-6 are human promises with drift risk. Minimize them ruthlessly.
+
+---
+
+## Types and Zod as Documentation
+
+In the Next.js application codebase, **TypeScript types and Zod schemas are the primary documentation layer.** They are the single source of truth for data structures — verified by the compiler and used by the runtime.
+
+### TypeScript Interfaces as Documentation
+
+Well-typed interfaces make most prop/parameter documentation redundant:
+
+```tsx
+// The interface IS the documentation — no TSDoc needed
+interface MeetingCardProps {
+  meeting: Meeting;
+  onSelect?: (meetingId: string) => void;
+  variant?: "standard" | "elevated" | "inset";
+}
+```
+
+The types `Meeting`, `string`, and the union type `"standard" | "elevated" | "inset"` communicate everything a consumer needs to know. Adding comments like `/** The meeting to display */` is noise.
+
+### Zod `.describe()` as Documentation
+
+Zod `.describe()` is structural documentation that flows into validation errors and can be extracted by tooling. It cannot drift because it IS the code:
+
+```tsx
+export const meetingSchema = z.object({
+  id: z.string().uuid(),
+  title: z.string().min(1).max(200).describe("Human-readable meeting title"),
+  status: z.enum(["draft", "scheduled", "active", "completed"]),
+  scheduledAt: z.string().datetime().nullable(),
+});
+```
+
+**Rule:** Use `.describe()` only when the field name and type constraints don't tell the full story. `id: z.string().uuid()` is already self-documenting — `.describe("Meeting ID")` is pure noise.
+
+### When Types Are Enough
+
+```tsx
+// NO TSDoc needed — the types tell the complete story
+function getMeeting(id: string): Promise<Meeting | null>
+function deleteMeeting(id: string): Promise<void>
+function listMeetings(filter?: MeetingFilter): Promise<Meeting[]>
+```
+
+---
+
+## What to Document
+
+| What | How | Why |
+|------|-----|-----|
+| **Complex exported function** | TSDoc only if the signature doesn't convey the contract | Edge cases, error conditions, non-obvious behavior |
+| **Non-obvious props** | Comment on the interface property (not the component) | When the name + type isn't sufficient |
+| **Hook caching/revalidation** | TSDoc on the hook | Cannot be inferred from the return type |
+| **`"use client"` rationale** | Brief comment above the directive when it's non-obvious | Explains the architectural boundary decision |
+| **Side effects** | Note in TSDoc if invisible in the signature | Mutations, cache invalidation, analytics |
+
+---
+
+## What NOT to Document
+
+**Self-documenting components:**
+```tsx
+// BAD — the name + props type says everything
+/** MeetingCard displays a card for a meeting */
+export function MeetingCard({ meeting }: MeetingCardProps) {
+
+// GOOD — skip it; the name IS the documentation
+export function MeetingCard({ meeting }: MeetingCardProps) {
+```
+
+**Obvious props:**
+```tsx
+// BAD — noise
+interface DialogProps {
+  /** Whether the dialog is open */
+  open: boolean;
+  /** Called when the dialog open state changes */
+  onOpenChange: (open: boolean) => void;
+  /** The dialog title */
+  title: string;
+  /** The dialog content */
+  children: React.ReactNode;
+}
+
+// GOOD — the names + types are the documentation
+interface DialogProps {
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+  title: string;
+  children: React.ReactNode;
+}
+```
+
+**Comment only non-obvious props:**
+```tsx
+interface MeetingCardProps {
+  meeting: Meeting;
+
+  /**
+   * Memoize with `useCallback` to prevent re-renders
+   * inside virtualized lists.
+   */
+  onSelect?: (meetingId: string) => void;
+
+  variant?: "standard" | "elevated" | "inset";
+}
+```
+
+Here, `onSelect` has a non-obvious performance implication. The other props need no comments.
+
+**Thin page components:**
+```tsx
+// SKIP — the delegation IS the documentation
+export default async function MeetingsPage() {
+  const meetings = await listMeetings();
+  return <MeetingList meetings={meetings} />;
+}
+```
+
+**shadcn/ui primitives** — generated code, never add comments.
+
+**Zod fields where the name + constraints are clear:**
+```tsx
+// BAD — .describe() adds nothing
+status: z.enum(["draft", "scheduled", "active", "completed"]).describe("Meeting status")
+
+// GOOD — skip .describe() when it would just restate the field name
+status: z.enum(["draft", "scheduled", "active", "completed"])
+```
+
+**Tailwind utility classes** — the class names are the documentation.
+
+---
+
+## Component Documentation
+
+TSDoc on components is justified **only** when the component has non-obvious behavior that types cannot convey:
+
+```tsx
+/**
+ * Inline meeting editor with optimistic updates.
+ *
+ * Submits via Server Action and optimistically updates the SWR cache.
+ * Rolls back automatically on server error.
+ */
+"use client";
+
+export function MeetingEditor({ meeting }: MeetingEditorProps) {
+```
+
+The optimistic update + rollback behavior is invisible in the props — it justifies documentation. A simple `MeetingCard` that just renders data does not.
+
+---
+
+## Server and Client Boundary Notes
+
+The default is React Server Component — no documentation needed. Document the boundary **only** when using `"use client"` and the rationale is non-obvious:
+
+```tsx
+/**
+ * Client Component: requires useState for search input tracking
+ * and useTransition for non-blocking updates.
+ */
+"use client";
+
+export function MeetingSearch({ initialResults }: MeetingSearchProps) {
+```
+
+**Skip** when `"use client"` is obviously needed (event handlers, form state):
+```tsx
+// No boundary comment needed — "use client" is obviously required
+// for onClick handlers and useState
+"use client";
+
+export function MeetingForm({ onSubmit }: MeetingFormProps) {
+```
+
+---
+
+## Hook Documentation
+
+Custom hooks are the one area where TSDoc is frequently justified — the caching and revalidation behavior cannot be inferred from the return type:
+
+```tsx
+/**
+ * Fetches a meeting by ID with SWR caching.
+ * Revalidates on focus and reconnect.
+ * Seed with SWRConfig fallback to avoid loading flash.
+ */
+export function useMeeting(meetingId: string) {
+  return useSWR<Meeting>(`/api/meetings/${meetingId}`, fetcher);
+}
+```
+
+**Skip** for trivial hooks:
+```tsx
+// No TSDoc needed — the name + signature are clear
+export function useTheme() {
+  return useContext(ThemeContext);
+}
+```
+
+---
+
+## Inline Comments
+
+Inline comments within components or functions explain **why**, never **what**:
+
+```tsx
+export function MeetingList({ meetings }: MeetingListProps) {
+  // Sort descending — server returns chronological, dashboard needs reverse.
+  const sorted = useMemo(
+    () => [...meetings].sort((a, b) =>
+      new Date(b.scheduledAt).getTime() - new Date(a.scheduledAt).getTime()
+    ),
+    [meetings]
+  );
+
+  return (
+    // Fragment avoids extra div that breaks parent CSS grid layout.
+    <>
+      {sorted.map((meeting) => (
+        <MeetingCard key={meeting.id} meeting={meeting} />
+      ))}
+    </>
+  );
+}
+```
+
+---
+
+## In-Code Markers
+
+```tsx
+// TODO(bob): Add virtual scrolling for lists > 100 items. Issue #234.
+
+// FIXME(carol): Race between optimistic update and SWR revalidation
+// causes flicker. Needs mutate() with rollback.
+
+// HACK(dave): Workaround for Next.js 16 searchParams Suspense
+// requirement. Remove when framework provides a built-in solution.
+```
+
+Always include `(username)` and issue reference.
+
+---
+
+## Service README Template
+
+The app lives inside the workspace monorepo, so its README is a lean orientation page — purpose, how to run it, configuration — not a standalone open-source front door. No clone instructions, badges, or license stanza.
+
+```markdown
+# [App Name]
+
+One-sentence description of what this frontend does.
+
+## Architecture
+
+\```
+Pages (app/)
+  └── Features (components/<domain>/)
+        └── UI Primitives (components/ui/)
+        └── Hooks (hooks/)
+              └── API Client (lib/api.ts)
+                    └── Schemas (lib/schemas/)
+\```
+
+## Quick Start
+
+\```bash
+cp .env.example .env.local
+./dev start
+\```
+
+App: `http://localhost:3000`
+
+## Configuration
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `NEXT_PUBLIC_API_URL` | `http://localhost:8080` | Backend API |
+| `NEXT_PUBLIC_APP_ENV` | `development` | Environment |
+
+## Testing
+
+\```bash
+./dev test
+\```
+
+## Further Reading
+
+Durable architecture and policy live in `docs/` — this README covers only how to run the app.
+```

package/src/engineer-skills/groundwork-nextjs-engineer/references/error-boundaries.md

@@ -0,0 +1,383 @@
+# Error Boundaries
+
+## Table of Contents
+- [Error Hierarchy](#error-hierarchy)
+- [error.tsx](#errortsx)
+- [global-error.tsx](#global-errortsx)
+- [not-found.tsx](#not-foundtsx)
+- [Auth Errors](#auth-errors)
+- [Navigation API Gotcha](#navigation-api-gotcha)
+- [Redirects](#redirects)
+- [Hydration Errors](#hydration-errors)
+- [Post-Response Work with after()](#post-response-work-with-after)
+
+---
+
+## Error Hierarchy
+
+Errors bubble up from the component that throws to the nearest error boundary. Place `error.tsx` at different levels to control the granularity of error recovery.
+
+```
+app/
+├── error.tsx               # Catches errors from all children
+├── global-error.tsx        # Catches errors in root layout
+├── meetings/
+│   ├── error.tsx           # Catches errors in /meetings/*
+│   └── [id]/
+│       ├── error.tsx       # Catches errors in /meetings/[id]
+│       └── page.tsx
+└── layout.tsx              # Errors here go to global-error.tsx
+```
+
+An `error.tsx` boundary does **not** catch errors thrown in the `layout.tsx` of the same segment — those bubble up to the parent segment's error boundary or `global-error.tsx`.
+
+---
+
+## error.tsx
+
+Catches runtime errors in a route segment and its children. Provides a `reset` function to retry rendering.
+
+`error.tsx` **must** be a Client Component.
+
+```tsx
+// app/meetings/error.tsx
+'use client';
+
+export default function MeetingsError({
+  error,
+  reset,
+}: {
+  error: Error & { digest?: string };
+  reset: () => void;
+}) {
+  return (
+    <div className="surface-glass p-6 text-center" role="alert">
+      <h2 className="text-destructive">Something went wrong</h2>
+      <p className="text-muted-foreground mt-2">
+        Failed to load meetings. This has been logged.
+      </p>
+      <button
+        onClick={reset}
+        className="mt-4 px-4 py-2 bg-primary rounded"
+      >
+        Try again
+      </button>
+    </div>
+  );
+}
+```
+
+### Important
+
+- The `digest` property is a hash of the error that was thrown on the server. Use it for log correlation — never display it to users.
+- Sensitive error details (stack traces, internal messages) are stripped before reaching the client. Only generic messages should be shown to users.
+
+---
+
+## global-error.tsx
+
+Catches errors thrown in the **root layout**. Because the root layout is replaced entirely when this renders, `global-error.tsx` must include its own `<html>` and `<body>` tags.
+
+```tsx
+// app/global-error.tsx
+'use client';
+
+export default function GlobalError({
+  error,
+  reset,
+}: {
+  error: Error & { digest?: string };
+  reset: () => void;
+}) {
+  return (
+    <html>
+      <body>
+        <div style={{ padding: '2rem', textAlign: 'center' }}>
+          <h2>Something went wrong</h2>
+          <p>An unexpected error occurred. Please try refreshing the page.</p>
+          <button onClick={reset}>Try again</button>
+        </div>
+      </body>
+    </html>
+  );
+}
+```
+
+Note: `global-error.tsx` cannot use the app's CSS imports or layout — it replaces the entire document. Keep it self-contained with inline styles.
+
+---
+
+## not-found.tsx
+
+Custom 404 UI for a route segment. Place at any level to customise the 404 experience for that section of the app.
+
+```tsx
+// app/meetings/not-found.tsx
+import Link from 'next/link';
+
+export default function MeetingNotFound() {
+  return (
+    <div className="surface-glass p-8 text-center">
+      <h2 className="text-xl font-semibold">Meeting not found</h2>
+      <p className="text-muted-foreground mt-2">
+        This meeting may have been deleted or the link is incorrect.
+      </p>
+      <Link href="/meetings" className="mt-4 text-primary inline-block">
+        Back to meetings
+      </Link>
+    </div>
+  );
+}
+```
+
+### Triggering Not Found
+
+```tsx
+import { notFound } from 'next/navigation';
+
+export default async function MeetingPage({ params }: Props) {
+  const { id } = await params;
+  const meeting = await getMeeting(id);
+
+  if (!meeting) {
+    notFound();  // Renders closest not-found.tsx
+  }
+
+  return <MeetingDetail meeting={meeting} />;
+}
+```
+
+---
+
+## Auth Errors
+
+Trigger specific auth-related error pages:
+
+```tsx
+import { forbidden, unauthorized } from 'next/navigation';
+
+export default async function AdminPage() {
+  const session = await getSession();
+
+  if (!session) {
+    unauthorized();  // Renders unauthorized.tsx (401)
+  }
+
+  if (!session.hasAdminAccess) {
+    forbidden();     // Renders forbidden.tsx (403)
+  }
+
+  return <AdminDashboard />;
+}
+```
+
+Create corresponding error pages:
+
+```tsx
+// app/forbidden.tsx
+export default function Forbidden() {
+  return (
+    <div className="surface-glass p-8 text-center">
+      <h2>Access Denied</h2>
+      <p className="text-muted-foreground">
+        You don't have permission to view this resource.
+      </p>
+    </div>
+  );
+}
+
+// app/unauthorized.tsx
+export default function Unauthorized() {
+  return (
+    <div className="surface-glass p-8 text-center">
+      <h2>Sign In Required</h2>
+      <p className="text-muted-foreground">
+        Please sign in to access this page.
+      </p>
+    </div>
+  );
+}
+```
+
+---
+
+## Navigation API Gotcha
+
+`redirect()`, `notFound()`, `forbidden()`, and `unauthorized()` work by throwing special internal errors. If you wrap them in a try-catch, the catch block intercepts the navigation error and the navigation silently fails.
+
+```tsx
+// ❌ Bad — try-catch catches the navigation "error"
+'use server';
+
+async function createMeeting(formData: FormData) {
+  try {
+    const meeting = await db.meeting.create({ ... });
+    redirect(`/meetings/${meeting.id}`);  // This throws!
+  } catch (error) {
+    // redirect() throw is caught here — navigation fails silently!
+    return { error: 'Failed to create meeting' };
+  }
+}
+```
+
+### Fix 1: Call Navigation Outside try-catch
+
+```tsx
+// ✅ Good — navigation API outside the try-catch
+async function createMeeting(formData: FormData) {
+  let meeting;
+  try {
+    meeting = await db.meeting.create({ ... });
+  } catch (error) {
+    return { error: 'Failed to create meeting' };
+  }
+  redirect(`/meetings/${meeting.id}`);  // Outside try-catch
+}
+```
+
+### Fix 2: Re-throw with unstable_rethrow
+
+When the navigation must be inside the try-catch:
+
+```tsx
+import { unstable_rethrow } from 'next/navigation';
+
+async function createMeeting(formData: FormData) {
+  try {
+    const meeting = await db.meeting.create({ ... });
+    redirect(`/meetings/${meeting.id}`);
+  } catch (error) {
+    unstable_rethrow(error);  // Re-throws Next.js internal errors
+    return { error: 'Failed to create meeting' };
+  }
+}
+```
+
+### Affected Functions
+
+All of these throw internal errors — never wrap them in try-catch without `unstable_rethrow`:
+- `redirect()` — 307 temporary redirect
+- `permanentRedirect()` — 308 permanent redirect
+- `notFound()` — 404
+- `forbidden()` — 403
+- `unauthorized()` — 401
+
+---
+
+## Redirects
+
+```tsx
+import { redirect, permanentRedirect } from 'next/navigation';
+
+// 307 Temporary — use for most cases (auth redirects, feature gates)
+redirect('/new-path');
+
+// 308 Permanent — use for URL migrations (browsers cache this)
+permanentRedirect('/new-url');
+```
+
+Use `redirect()` for dynamic routing decisions (auth, feature flags). Use `permanentRedirect()` only when the old URL is permanently retired and should be cached by browsers and search engines.
+
+---
+
+## Hydration Errors
+
+Hydration errors occur when the server-rendered HTML doesn't match the client-rendered HTML. React detects the mismatch and throws an error.
+
+### Error Signs
+
+- "Hydration failed because the initial UI does not match"
+- "Text content does not match server-rendered HTML"
+
+### Common Causes and Fixes
+
+#### Browser APIs
+
+```tsx
+// ❌ Bad — window doesn't exist on server
+<div>{window.innerWidth}</div>
+
+// ✅ Good — render on client only after mount
+'use client';
+import { useState, useEffect } from 'react';
+
+export function WindowWidth() {
+  const [width, setWidth] = useState<number>();
+  useEffect(() => setWidth(window.innerWidth), []);
+  return <div>{width ?? 'Loading…'}</div>;
+}
+```
+
+#### Date/Time Rendering
+
+Server and client may be in different timezones:
+
+```tsx
+// ❌ Bad — different timezone on server vs client
+<span>{new Date().toLocaleString()}</span>
+
+// ✅ Good — render on client only
+'use client';
+const [time, setTime] = useState<string>();
+useEffect(() => setTime(new Date().toLocaleString()), []);
+```
+
+#### Random Values and IDs
+
+```tsx
+// ❌ Bad — Math.random differs between server and client
+<div id={Math.random().toString()}>
+
+// ✅ Good — useId generates stable IDs across server/client
+import { useId } from 'react';
+
+function Input() {
+  const id = useId();
+  return <input id={id} />;
+}
+```
+
+#### Invalid HTML Nesting
+
+```tsx
+// ❌ Bad — <div> inside <p> is invalid HTML
+<p><div>Content</div></p>
+
+// ❌ Bad — <p> inside <p> is invalid HTML
+<p><p>Nested</p></p>
+
+// ✅ Good — valid nesting
+<div><p>Content</p></div>
+```
+
+### Debugging Hydration Errors
+
+In development, click the hydration error overlay to see a diff of server vs client HTML. This pinpoints the exact element that mismatched.
+
+#### Third-Party Scripts
+
+Browser extensions and third-party scripts can inject DOM elements that don't exist in the server-rendered HTML, causing hydration mismatches. If you see hydration errors that disappear in Incognito Mode, a browser extension is the likely cause. Use `next/script` with `strategy="afterInteractive"` instead of raw `<script>` tags to avoid this.
+
+---
+
+## Post-Response Work with after()
+
+`after()` runs code after the response finishes streaming. Use it for logging, analytics, or cleanup that shouldn't delay the response.
+
+```tsx
+import { after } from 'next/server';
+
+export async function POST(request: Request) {
+  const data = await processRequest(request);
+
+  after(async () => {
+    // This runs after the response is sent
+    await logAnalytics(data);
+    await sendNotification(data);
+  });
+
+  return Response.json({ success: true });
+}
+```
+
+`after()` does not block the response. The client receives the response immediately while the deferred work runs in the background.