@baldurpan/create-ai-workflow 0.2.0

package/templates/standards/react/state-management.md

@@ -0,0 +1,123 @@
+# State Management
+
+## Hierarchy
+
+Choose the simplest state mechanism that works. Escalate only when necessary.
+
+```
+1. URL state          — shareable, bookmarkable, free
+2. Server state       — TanStack Query (cached, synchronized, background-refreshed)
+3. Local state        — useState / useReducer
+4. Context            — for shared UI state (theme, current user, modal stack)
+5. Zustand            — only when Context is insufficient
+6. Redux              — never
+```
+
+## URL State
+
+Prefer URL state for anything that should be shareable, bookmarkable, or survive a refresh:
+
+- Filters, search queries, pagination, selected tab
+- Use TanStack Router's typed search params (validated with Zod)
+
+```ts
+// TanStack Router — typed search params
+const search = invoicesRoute.useSearch();
+const navigate = invoicesRoute.useNavigate();
+
+function setStatus(status: InvoiceStatus) {
+  navigate({ search: (prev) => ({ ...prev, status, page: 1 }) });
+}
+```
+
+See [`../tooling/tanstack-router.md`](../tooling/tanstack-router.md) for the full pattern (route definition, validation, loaders).
+
+## Server State — TanStack Query
+
+For data that lives on the server, TanStack Query is the default:
+
+```ts
+const { data: invoices, isLoading } = useQuery({
+  queryKey: ["invoices", filters],
+  queryFn: () => fetchInvoices(filters),
+  staleTime: 60_000,
+});
+
+const { mutate: createInvoice } = useMutation({
+  mutationFn: createInvoiceFn,
+  onSuccess: () => {
+    queryClient.invalidateQueries({ queryKey: ["invoices"] });
+  },
+});
+```
+
+Do not duplicate server state into local state. Do not use `useEffect` + `useState` for data fetching.
+
+## Local State
+
+For UI-only state that does not need to be shared:
+
+```ts
+const [isOpen, setIsOpen] = useState(false);
+const [activeTab, setActiveTab] = useState<"overview" | "details">("overview");
+```
+
+Use `useReducer` when state transitions are complex or interrelated:
+
+```ts
+type Action =
+  | { type: "SET_STEP"; step: number }
+  | { type: "SUBMIT" }
+  | { type: "RESET" };
+
+function reducer(state: WizardState, action: Action): WizardState { ... }
+
+const [state, dispatch] = useReducer(reducer, initialState);
+```
+
+## Context
+
+Use Context for state that many components need but that does not belong in the server:
+
+- Current user / session
+- Theme / color scheme
+- Open modals / toasts
+- Feature flags
+
+Keep Context providers small. Do not put everything in a single `AppContext`.
+
+## Zustand
+
+Use Zustand when:
+- State is complex and cross-cutting enough that Context causes re-render issues
+- Multiple independent slices of UI state need to be coordinated
+
+```ts
+const useInvoiceStore = create<InvoiceStore>((set) => ({
+  selectedIds: [],
+  toggleSelected: (id) =>
+    set((state) => ({
+      selectedIds: state.selectedIds.includes(id)
+        ? state.selectedIds.filter((x) => x !== id)
+        : [...state.selectedIds, id],
+    })),
+}));
+```
+
+## Never Redux
+
+Redux adds ceremony, boilerplate, and indirection that is not justified for modern React applications. TanStack Query + Zustand + URL state covers all real use cases with far less overhead.
+
+## PRIORITY
+
+```
+URL state > Server state > Local state > Context > Zustand
+```
+
+## See Also
+
+- [`../tooling/tanstack-router.md`](../tooling/tanstack-router.md) — typed URL state, loaders
+- [`../tooling/tanstack-query.md`](../tooling/tanstack-query.md) — server state cache
+- [`use-effect.md`](use-effect.md) — what useEffect is and isn't for
+- [`forms.md`](forms.md) — form state management
+- [`hooks.md`](hooks.md) — composing hooks for stateful logic

package/templates/standards/react/testing.md

@@ -0,0 +1,118 @@
+# Testing
+
+## Philosophy
+
+Test behavior, not implementation. A test that breaks when you rename a variable is a bad test. A test that breaks when user-visible behavior changes is a good test.
+
+Reference: [Common mistakes with React Testing Library](https://kentcdodds.com/blog/common-mistakes-with-react-testing-library)
+
+## Tooling
+
+- **Vitest** — test runner (fast, native ESM, compatible with Jest API)
+- **Testing Library** — component testing (`@testing-library/react`, `@testing-library/user-event`)
+- **Playwright** — E2E tests for critical user flows only
+
+## DO
+
+- Test from the user's perspective — what does the user see and do?
+- Query by accessible role, label, or text — not by `data-testid` or CSS class
+- Use `userEvent` over `fireEvent` for realistic interaction simulation
+- Test the happy path and the critical error paths
+- Write unit tests for pure utility functions and complex business logic
+- Write integration tests for feature flows (form submission, data fetching, state transitions)
+
+## DO NOT
+
+- Test implementation details (internal state, private methods, component structure)
+- Use snapshot tests — they break constantly and encode nothing meaningful
+- Mock things you do not own (browser APIs, global state) without good reason
+- Assert on CSS class names or DOM structure
+- Write tests that are tightly coupled to component internals
+
+## Query Priority
+
+Follow Testing Library's recommended query priority:
+
+```
+1. getByRole          — best: matches what a screen reader sees
+2. getByLabelText     — for form inputs
+3. getByPlaceholderText — last resort for inputs
+4. getByText          — for non-interactive elements
+5. getByDisplayValue  — for form elements with a value
+6. getByAltText       — for images
+7. getByTitle         — for title attributes
+8. getByTestId        — last resort only (requires data-testid attribute)
+```
+
+## Example — Integration Test
+
+```tsx
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { CreateInvoiceForm } from "./CreateInvoiceForm";
+
+test("submits the form with valid data", async () => {
+  const user = userEvent.setup();
+  const onSubmit = vi.fn();
+
+  render(<CreateInvoiceForm onSubmit={onSubmit} />);
+
+  await user.type(screen.getByLabelText("Title"), "Q4 Report");
+  await user.type(screen.getByLabelText("Amount"), "500");
+  await user.click(screen.getByRole("button", { name: "Create" }));
+
+  expect(onSubmit).toHaveBeenCalledWith({ title: "Q4 Report", amount: 500 });
+});
+
+test("shows validation errors for empty fields", async () => {
+  const user = userEvent.setup();
+
+  render(<CreateInvoiceForm onSubmit={vi.fn()} />);
+
+  await user.click(screen.getByRole("button", { name: "Create" }));
+
+  expect(screen.getByRole("alert")).toHaveTextContent("Title is required");
+});
+```
+
+## Playwright — E2E (Critical Flows Only)
+
+Reserve Playwright for flows that are:
+- Business-critical (checkout, authentication, data export)
+- Too complex to integration-test meaningfully
+- Dependent on real browser behavior (file upload, clipboard, print)
+
+```ts
+test("user can log in and view their dashboard", async ({ page }) => {
+  await page.goto("/login");
+  await page.getByLabel("Email").fill("user@example.com");
+  await page.getByLabel("Password").fill("password");
+  await page.getByRole("button", { name: "Sign in" }).click();
+  await expect(page.getByRole("heading", { name: "Dashboard" })).toBeVisible();
+});
+```
+
+## File Colocation
+
+```
+features/
+  invoices/
+    InvoiceTable.tsx
+    InvoiceTable.test.tsx   ← colocated with the component
+    useInvoiceSort.ts
+    useInvoiceSort.test.ts  ← colocated with the hook
+```
+
+## PRIORITY
+
+```
+Integration tests > Unit tests > E2E tests
+Behavior > Implementation
+```
+
+## See Also
+
+- [`component-design.md`](component-design.md) — testable component structure
+- [`hooks.md`](hooks.md) — testing custom hooks via the components that use them
+- [`accessibility.md`](accessibility.md) — query by role, label, text
+- [`../architecture/refactoring.md`](../architecture/refactoring.md) — write tests before refactoring untested code

package/templates/standards/react/use-effect.md

@@ -0,0 +1,110 @@
+# useEffect
+
+## Core Rule
+
+`useEffect` is an escape hatch for synchronizing with external systems. It is not a general-purpose lifecycle hook.
+
+## VALID uses
+
+- Synchronizing with external systems (WebSocket, EventEmitter, third-party widget)
+- DOM APIs that require imperative access (focus management, scroll position, canvas)
+- Subscriptions (event listeners, pub/sub, real-time)
+- Timers and intervals
+- Imperative bridges to non-React code
+
+## INVALID uses
+
+- Deriving state from props or other state
+- Syncing two pieces of React state together
+- Fetching data (use TanStack Query instead)
+- Responding to user events (handle directly in event handlers)
+- Updating state on prop change (compute during render instead)
+
+## Examples
+
+### Correct — external system sync
+
+```ts
+useEffect(() => {
+  const socket = new WebSocket(url);
+  socket.addEventListener("message", handleMessage);
+  return () => {
+    socket.removeEventListener("message", handleMessage);
+    socket.close();
+  };
+}, [url, handleMessage]);
+```
+
+### Correct — DOM API
+
+```ts
+useEffect(() => {
+  if (isOpen) {
+    inputRef.current?.focus();
+  }
+}, [isOpen]);
+```
+
+### Incorrect — derived state
+
+```ts
+// BAD — deriving state with useEffect
+const [fullName, setFullName] = useState("");
+useEffect(() => {
+  setFullName(`${firstName} ${lastName}`);
+}, [firstName, lastName]);
+
+// GOOD — compute during render
+const fullName = `${firstName} ${lastName}`;
+```
+
+### Incorrect — state synchronization
+
+```ts
+// BAD — syncing two pieces of state
+useEffect(() => {
+  setDraftValue(externalValue);
+}, [externalValue]);
+
+// GOOD — use a key to reset controlled state
+<Input key={externalValue} defaultValue={externalValue} />
+```
+
+### Incorrect — data fetching
+
+```ts
+// BAD — manual fetch in useEffect
+useEffect(() => {
+  let cancelled = false;
+  fetchUser(id).then((data) => {
+    if (!cancelled) setUser(data);
+  });
+  return () => { cancelled = true; };
+}, [id]);
+
+// GOOD — use TanStack Query
+const { data: user } = useQuery({
+  queryKey: ["user", id],
+  queryFn: () => fetchUser(id),
+});
+```
+
+## Dependency Array Rules
+
+- Always specify the dependency array — never omit it
+- Include all reactive values used inside the effect
+- If a dependency changes too often, consider `useRef` or restructuring
+- Do not use `// eslint-disable-line react-hooks/exhaustive-deps` to suppress warnings — fix the underlying issue
+
+## PRIORITY
+
+```
+No effect > Computed value > Event handler > useEffect
+```
+
+## See Also
+
+- [`state-management.md`](state-management.md) — where state should actually live
+- [`hooks.md`](hooks.md) — composing hooks without useEffect abuse
+- [`../tooling/tanstack-query.md`](../tooling/tanstack-query.md) — data fetching without useEffect
+- [`anti-patterns.md`](anti-patterns.md) — common useEffect mistakes

package/templates/standards/security/api-security.md

@@ -0,0 +1,136 @@
+# API Security
+
+## Core Rules
+
+- Validate all input (see [validation.md](validation.md))
+- Authenticate all protected routes
+- Authorize every resource access
+- Return minimal, appropriate HTTP status codes
+- Rate limit public and sensitive endpoints
+- Never expose internal error details to clients
+
+## HTTP Status Codes
+
+Use precise status codes:
+
+| Code | When |
+|---|---|
+| `200` | Successful GET, PATCH, PUT |
+| `201` | Successful POST (resource created) |
+| `204` | Successful DELETE (no content) |
+| `400` | Malformed request (bad JSON, missing required field) |
+| `401` | Not authenticated |
+| `403` | Authenticated but not authorized |
+| `404` | Resource not found |
+| `409` | Conflict (duplicate, optimistic lock failure) |
+| `422` | Validation error (well-formed but invalid data) |
+| `429` | Rate limit exceeded |
+| `500` | Internal server error |
+
+## Error Responses
+
+Return structured errors. Never expose stack traces or internal details:
+
+```ts
+// BAD — exposes internals
+res.status(500).json({ error: error.stack });
+
+// GOOD — structured, safe
+res.status(422).json({
+  error: "Validation failed",
+  fields: result.error.flatten().fieldErrors,
+});
+```
+
+## Rate Limiting
+
+Apply rate limiting to all public APIs:
+
+```ts
+const ratelimit = new Ratelimit({
+  redis: Redis.fromEnv(),
+  limiter: Ratelimit.slidingWindow(100, "1 m"), // 100 req/min
+});
+
+export async function middleware(req: NextRequest) {
+  const ip = req.ip ?? "unknown";
+  const { success, limit, remaining } = await ratelimit.limit(ip);
+
+  if (!success) {
+    return NextResponse.json({ error: "Too many requests" }, {
+      status: 429,
+      headers: {
+        "X-RateLimit-Limit": limit.toString(),
+        "X-RateLimit-Remaining": remaining.toString(),
+      },
+    });
+  }
+}
+```
+
+## CORS
+
+Configure CORS explicitly. Do not allow all origins in production:
+
+```ts
+const corsOptions = {
+  origin: process.env.NODE_ENV === "production"
+    ? ["https://app.example.com"]
+    : ["http://localhost:3000"],
+  methods: ["GET", "POST", "PUT", "PATCH", "DELETE"],
+  credentials: true,
+};
+```
+
+## SQL Injection Prevention
+
+Use parameterized queries. Prisma handles this automatically:
+
+```ts
+// SAFE — Prisma parameterizes automatically
+const user = await db.user.findUnique({ where: { email } });
+
+// DANGEROUS — never concatenate user input into raw SQL
+const user = await db.$queryRawUnsafe(`SELECT * FROM users WHERE email = '${email}'`);
+
+// SAFE — use $queryRaw with tagged template (automatically parameterized)
+const user = await db.$queryRaw`SELECT * FROM users WHERE email = ${email}`;
+```
+
+## Content Security Policy
+
+Set a Content Security Policy header to mitigate XSS:
+
+```ts
+// Next.js — next.config.ts
+const securityHeaders = [
+  { key: "X-Content-Type-Options", value: "nosniff" },
+  { key: "X-Frame-Options", value: "DENY" },
+  { key: "X-XSS-Protection", value: "1; mode=block" },
+  { key: "Referrer-Policy", value: "strict-origin-when-cross-origin" },
+  {
+    key: "Content-Security-Policy",
+    value: [
+      "default-src 'self'",
+      "script-src 'self' 'unsafe-inline'", // tighten after audit
+      "style-src 'self' 'unsafe-inline'",
+      "img-src 'self' data: https:",
+    ].join("; "),
+  },
+];
+```
+
+## DO NOT
+
+- Expose database errors or stack traces to the client
+- Trust user-supplied IDs for authorization
+- Use `*` for CORS `Access-Control-Allow-Origin` in production
+- Accept file uploads without size and MIME type validation
+- Log request bodies that may contain passwords or payment data
+
+## See Also
+
+- [`validation.md`](validation.md) — input validation patterns
+- [`auth.md`](auth.md) — authentication and authorization
+- [`../typescript/error-handling.md`](../typescript/error-handling.md) — structured error responses
+- [`../architecture/api-design.md`](../architecture/api-design.md) — error shape conventions

package/templates/standards/security/auth.md

@@ -0,0 +1,112 @@
+# Authentication and Authorization
+
+## Core Rules
+
+- Authentication confirms identity. Authorization confirms permission. Both are required.
+- Never trust client-supplied user IDs or roles without server-side verification
+- Always verify authorization on the server — never rely solely on client-side checks
+- Use an established auth library — do not build custom auth from scratch
+
+## Preferred Libraries
+
+- **Auth.js** (Next.js) — sessions, OAuth, credentials, magic links
+- **Clerk** — managed auth with pre-built UI components
+- **Lucia** — lightweight, flexible, self-hosted
+
+## Session Handling
+
+```ts
+// Server-side — always verify the session server-side
+import { auth } from "~/lib/auth";
+
+export async function GET(req: Request) {
+  const session = await auth();
+  if (!session?.user) {
+    return new Response("Unauthorized", { status: 401 });
+  }
+  // use session.user.id — never use a userId from the request body
+  const invoices = await getInvoicesForUser(session.user.id);
+  return Response.json(invoices);
+}
+```
+
+## Authorization Checks
+
+Always check permissions on the server, for every request:
+
+```ts
+async function getInvoice(invoiceId: string, requestingUserId: string) {
+  const invoice = await db.invoice.findUnique({ where: { id: invoiceId } });
+  if (!invoice) throw new NotFoundError("Invoice", invoiceId);
+
+  // Authorization — verify the user owns this resource
+  if (invoice.userId !== requestingUserId) {
+    throw new ForbiddenError("You do not have access to this invoice");
+  }
+
+  return invoice;
+}
+```
+
+## Token Storage
+
+| Token Type | Recommended Storage | Avoid |
+|---|---|---|
+| Session cookies | `HttpOnly`, `Secure`, `SameSite=Lax` cookies | `localStorage` |
+| JWT (short-lived) | `HttpOnly` cookie | `localStorage` |
+| Refresh tokens | `HttpOnly` cookie | `localStorage` or `sessionStorage` |
+
+`localStorage` is accessible to JavaScript and vulnerable to XSS. Always use `HttpOnly` cookies for auth tokens.
+
+## Password Handling
+
+```ts
+import bcrypt from "bcryptjs";
+
+// Hashing
+const hash = await bcrypt.hash(plaintext, 12); // min 12 rounds
+
+// Verification — use timing-safe comparison
+const isValid = await bcrypt.compare(plaintext, hash);
+```
+
+- Never store plaintext passwords
+- Use bcrypt, argon2, or scrypt — not MD5 or SHA-1
+- Minimum 12 rounds for bcrypt
+
+## CSRF Protection
+
+- Use `SameSite=Lax` or `SameSite=Strict` on session cookies
+- Use CSRF tokens for state-changing requests if cookies are `SameSite=None`
+- Auth.js and Clerk handle CSRF automatically
+
+## Rate Limiting Auth Endpoints
+
+Apply rate limiting to:
+- Login endpoints
+- Password reset endpoints
+- OTP/magic link endpoints
+
+```ts
+import { Ratelimit } from "@upstash/ratelimit";
+
+const ratelimit = new Ratelimit({
+  limiter: Ratelimit.slidingWindow(5, "15 m"), // 5 attempts per 15 minutes
+});
+
+const { success } = await ratelimit.limit(ip);
+if (!success) return new Response("Too many attempts", { status: 429 });
+```
+
+## DO NOT
+
+- Use the user's ID from request body for authorization decisions — always use the server session
+- Return different HTTP status codes for "user not found" vs. "wrong password" (user enumeration)
+- Log passwords or tokens
+- Implement custom crypto or JWT libraries
+
+## See Also
+
+- [`secrets.md`](secrets.md) — secret storage and rotation
+- [`api-security.md`](api-security.md) — rate limiting and CORS
+- [`validation.md`](validation.md) — validating auth requests

package/templates/standards/security/secrets.md

@@ -0,0 +1,105 @@
+# Secrets Management
+
+## Core Rules
+
+- Never commit secrets to version control
+- Never log secrets
+- Never expose backend secrets to the client
+- Rotate secrets that have been compromised or accidentally exposed
+
+## Environment Variables
+
+Store secrets in environment variables. Never hardcode them.
+
+```
+# .env.local (gitignored — for local development only)
+DATABASE_URL=postgres://user:password@localhost:5432/mydb
+JWT_SECRET=your-secret-key
+STRIPE_SECRET_KEY=sk_test_...
+```
+
+```
+# .env.example (committed — shows required vars without values)
+DATABASE_URL=
+JWT_SECRET=
+STRIPE_SECRET_KEY=
+SENDGRID_API_KEY=
+```
+
+## `.gitignore`
+
+Always include:
+
+```gitignore
+.env
+.env.local
+.env.*.local
+*.pem
+*.key
+```
+
+## Validate at Startup
+
+```ts
+// lib/env.ts (server-only)
+import { z } from "zod";
+
+const envSchema = z.object({
+  DATABASE_URL: z.string().url(),
+  JWT_SECRET: z.string().min(32),
+  STRIPE_SECRET_KEY: z.string().startsWith("sk_"),
+  NODE_ENV: z.enum(["development", "test", "production"]).default("development"),
+});
+
+export const env = envSchema.parse(process.env);
+```
+
+Fail fast on startup if required secrets are missing or malformed.
+
+## Client vs. Server Secrets
+
+| Type | Where | Prefix (Vite/Next.js) | Example |
+|---|---|---|---|
+| Server-only | Server environment | No prefix | `DATABASE_URL`, `JWT_SECRET` |
+| Client-safe | Client environment | `VITE_` / `NEXT_PUBLIC_` | `VITE_API_BASE_URL` |
+
+Never put a secret key in a `VITE_` or `NEXT_PUBLIC_` variable — it will be embedded in the client bundle.
+
+## CI/CD Secrets
+
+- Use the CI provider's secret store (GitHub Actions secrets, Vercel env vars, etc.)
+- Use separate secrets for each environment (dev, staging, production)
+- Limit secret access to only the jobs that need them
+
+## Secret Scanning
+
+- Enable GitHub's secret scanning on all repositories
+- Add `gitleaks` or `truffleHog` to pre-commit hooks for local detection
+
+```bash
+# Install gitleaks pre-commit hook
+brew install gitleaks
+gitleaks protect --staged
+```
+
+## If a Secret Is Exposed
+
+1. Rotate it immediately — assume it has been compromised
+2. Revoke the old secret in the provider's dashboard
+3. Audit access logs for unauthorized use
+4. Update all environments with the new secret
+5. Review git history and remove the commit from public branches if possible
+
+## DO NOT
+
+- Hardcode API keys, passwords, or tokens in source code
+- Log secrets (even in debug mode)
+- Pass secrets as command-line arguments (visible in process list)
+- Store secrets in `localStorage` or cookies without encryption
+- Use the same secret across environments
+
+## See Also
+
+- [`auth.md`](auth.md) — token storage and rotation
+- [`api-security.md`](api-security.md) — error responses that don't leak details
+- [`../tooling/observability.md`](../tooling/observability.md) — redacting before logging