@silverassist/agents-toolkit 2.0.0

package/templates/shared/instructions/react-components.instructions.md

@@ -0,0 +1,196 @@
+---
+applyTo: "**/components/**/*.tsx"
+---
+# React Component Standards
+
+## Component Structure
+
+**✅ ALWAYS use folder structure** with `index.tsx`:
+
+```
+components/
+└── domain/                    # Domain folder (auth, checkout, etc.)
+    ├── index.ts               # Barrel export for domain
+    └── component-name/        # kebab-case folder
+        ├── index.tsx          # Main component (export default)
+        ├── types.ts           # Component-specific types (if needed)
+        └── __tests__/         # Tests folder
+            └── component-name.test.tsx
+```
+
+## Export Pattern
+
+### Components: Default Export
+
+Per Next.js recommendation, components use `export default` for better tree-shaking:
+
+```tsx
+// ✅ CORRECT: Default export for components
+interface ButtonProps {
+  onClick: () => void;
+  children: React.ReactNode;
+}
+
+export default function Button({ onClick, children }: ButtonProps) {
+  return <button onClick={onClick}>{children}</button>;
+}
+
+// ❌ INCORRECT: Named export for components (worse tree-shaking)
+export function Button({ onClick, children }: ButtonProps) {
+  return <button onClick={onClick}>{children}</button>;
+}
+
+// ❌ INCORRECT: Arrow function (loses name in stack traces)
+export default const Button = ({ onClick, children }: ButtonProps) => {
+  return <button onClick={onClick}>{children}</button>;
+};
+```
+
+### Barrel Exports for Domains
+
+Re-export components from domain `index.ts`:
+
+```typescript
+// src/components/auth/index.ts
+export { default as LoginForm } from "./login-form";
+export { default as RegisterForm } from "./register-form";
+
+// Usage - clean imports
+import { LoginForm, RegisterForm } from "@/components/auth";
+```
+
+### Non-Components: Named Exports
+
+Helpers, types, hooks use named exports:
+
+```typescript
+// types.ts
+export interface User { }
+export type Status = "active" | "inactive";
+
+// helpers.ts
+export function formatUserName(user: User): string { }
+```
+
+## Server vs Client Components
+
+### Server Component (Default)
+
+```tsx
+// src/components/dashboard/stats-card/index.tsx
+import { getStats } from "@/data/stats";
+
+interface StatsCardProps {
+  title: string;
+}
+
+export default async function StatsCard({ title }: StatsCardProps) {
+  const stats = await getStats(); // Direct data fetching
+  
+  return (
+    <div>
+      <h3>{title}</h3>
+      <p>{stats.value}</p>
+    </div>
+  );
+}
+```
+
+### Client Component (Interactive)
+
+```tsx
+// src/components/checkout/add-to-cart/index.tsx
+"use client";
+
+import { useState } from "react";
+
+interface AddToCartProps {
+  productId: string;
+}
+
+export default function AddToCart({ productId }: AddToCartProps) {
+  const [quantity, setQuantity] = useState(1);
+  
+  return (
+    <button onClick={() => setQuantity(q => q + 1)}>
+      Add ({quantity})
+    </button>
+  );
+}
+```
+
+## Props Interface
+
+**✅ ALWAYS define props interface inside the component file**:
+
+```tsx
+// ✅ CORRECT: Interface defined in component file
+interface UserCardProps {
+  user: User;
+  onSelect?: (user: User) => void;
+  className?: string;
+}
+
+export default function UserCard({ user, onSelect, className }: UserCardProps) {
+  return (
+    <div className={className}>
+      <h2>{user.name}</h2>
+    </div>
+  );
+}
+```
+
+## Hook Placement (CRITICAL)
+
+**✅ ALL hooks MUST come BEFORE any conditional returns**:
+
+```tsx
+// ✅ CORRECT: Hooks first, then early returns
+export default function UserList({ users }: UserListProps) {
+  const [filter, setFilter] = useState("");
+  const filteredUsers = useMemo(() => 
+    users.filter(u => u.name.includes(filter)), 
+    [users, filter]
+  );
+
+  // Early returns AFTER all hooks
+  if (!users?.length) {
+    return <p>No users found</p>;
+  }
+
+  return <ul>{/* ... */}</ul>;
+}
+
+// ❌ INCORRECT: Hook after conditional
+export default function UserList({ users }: UserListProps) {
+  if (!users?.length) return null;  // ❌ Early return before hooks
+  
+  const [filter, setFilter] = useState("");  // ❌ Error!
+  return <ul>{/* ... */}</ul>;
+}
+```
+
+## Event Handlers
+
+**✅ Use `handle` prefix** for event handlers:
+
+```tsx
+import type { ChangeEvent, SyntheticEvent } from "react";
+
+export default function Form() {
+  const handleSubmit = (e: SyntheticEvent<HTMLFormElement>) => {
+    e.preventDefault();
+    // ...
+  };
+
+  const handleInputChange = (e: ChangeEvent<HTMLInputElement>) => {
+    // ...
+  };
+
+  return (
+    <form onSubmit={handleSubmit}>
+      <input onChange={handleInputChange} />
+    </form>
+  );
+}
+```

package/templates/shared/instructions/server-actions.instructions.md

@@ -0,0 +1,429 @@
+---
+applyTo: "**/actions/**/*.ts"
+---
+# Server Actions Standards
+
+> **Security First**: Server Actions create public HTTP endpoints. Treat them with the same
+> security assumptions as any public API endpoint.
+
+## File Structure
+
+Organize actions by domain (consistent with DDD principles):
+
+```
+actions/
+├── auth/
+│   ├── login.ts
+│   └── register.ts
+├── user/
+│   └── update-profile.ts
+└── contact/
+    └── submit-form.ts
+data/                    # Data Access Layer (DAL)
+├── user-dto.ts
+├── auth.ts
+└── db.ts
+```
+
+For smaller projects, flat structure is acceptable:
+
+```
+actions/
+├── auth-actions.ts
+├── user-actions.ts
+└── contact-actions.ts
+data/
+├── dal.ts               # Centralized Data Access Layer
+└── dto.ts               # Data Transfer Objects
+```
+
+## Security Architecture
+
+### Data Access Layer (DAL)
+
+**CRITICAL**: Create a dedicated Data Access Layer for all data operations. Never access
+databases or sensitive data directly in Server Actions.
+
+```typescript
+// data/dal.ts
+import "server-only";
+import { cache } from "react";
+import { cookies } from "next/headers";
+
+/**
+ * Cached user retrieval - safe to call multiple times
+ * Uses React cache to deduplicate requests within a render
+ */
+export const getCurrentUser = cache(async () => {
+  const cookieStore = await cookies();
+  const token = cookieStore.get("AUTH_TOKEN");
+  const decodedToken = await decryptAndValidate(token);
+
+  // Return minimal, safe user object - NOT the full database record
+  return new User(decodedToken.id);
+});
+
+/**
+ * Get user profile with authorization checks
+ * Returns only safe, filtered data (DTO pattern)
+ */
+export async function getUserProfileDTO(userId: string) {
+  const currentUser = await getCurrentUser();
+  const userData = await db.user.findUnique({ where: { id: userId } });
+
+  // Return only authorized fields
+  return {
+    username: canSeeUsername(currentUser) ? userData.username : null,
+    email: canSeeEmail(currentUser, userData) ? userData.email : null,
+    // Never expose: password, tokens, internal IDs, etc.
+  };
+}
+```
+
+### Server-Only Marker
+
+**CRITICAL**: Always mark DAL files with `server-only` to prevent client-side imports:
+
+```typescript
+// data/dal.ts
+import "server-only";
+
+// This file will cause a build error if imported in client code
+```
+
+Install the package: `npm install server-only`
+
+## Action Pattern
+
+```typescript
+"use server";
+
+import { revalidatePath } from "next/cache";
+import { getCurrentUser } from "@/data/dal";
+import { createUserInDB } from "@/data/user-dto";
+
+/**
+ * State returned from server actions
+ */
+interface ActionState {
+  success: boolean;
+  message: string;
+  data?: unknown;
+  errors?: Record<string, string>;
+}
+
+/**
+ * Creates a new user
+ * @param prevState - Previous form state
+ * @param formData - Form data from submission
+ * @returns Action result state
+ */
+export async function createUser(
+  prevState: ActionState,
+  formData: FormData
+): Promise<ActionState> {
+  try {
+    // 1. ALWAYS verify authentication first
+    const user = await getCurrentUser();
+    if (!user) {
+      return {
+        success: false,
+        message: "You must be signed in to perform this action",
+      };
+    }
+
+    // 2. ALWAYS verify authorization
+    if (!user.canCreateUsers) {
+      return {
+        success: false,
+        message: "You do not have permission to create users",
+      };
+    }
+
+    // 3. ALWAYS validate ALL inputs (never trust client data)
+    const name = formData.get("name") as string;
+    const email = formData.get("email") as string;
+
+    if (!name || !email) {
+      return {
+        success: false,
+        message: "Missing required fields",
+        errors: {
+          name: !name ? "Name is required" : "",
+          email: !email ? "Email is required" : "",
+        },
+      };
+    }
+
+    // 4. Use DAL for data operations (never direct DB access)
+    const result = await createUserInDB({ name, email });
+
+    // 5. Revalidate cache after mutations
+    revalidatePath("/users");
+
+    return {
+      success: true,
+      message: "User created successfully",
+      data: result, // Return only safe DTO, not raw DB result
+    };
+  } catch (error) {
+    return {
+      success: false,
+      message: error instanceof Error ? error.message : "Unknown error",
+    };
+  }
+}
+```
+
+## Security Rules (CRITICAL)
+
+### 1. Always use "use server" directive
+```typescript
+"use server";
+```
+
+### 2. ALWAYS authenticate and authorize
+```typescript
+// ❌ INCORRECT: No auth check
+export async function deleteUser(userId: string) {
+  await db.user.delete({ where: { id: userId } });
+}
+
+// ✅ CORRECT: Auth + authz before any operation
+export async function deleteUser(userId: string) {
+  const currentUser = await getCurrentUser();
+  if (!currentUser) {
+    throw new Error("You must be signed in");
+  }
+  if (!currentUser.isAdmin && currentUser.id !== userId) {
+    throw new Error("Not authorized");
+  }
+  await deleteUserFromDB(userId); // Use DAL
+}
+```
+
+### 3. NEVER trust client input
+```typescript
+// ❌ INCORRECT: Trusting client data
+export async function updateRole(formData: FormData) {
+  const isAdmin = formData.get("isAdmin") === "true";
+  await db.user.update({ data: { isAdmin } }); // Vulnerable!
+}
+
+// ✅ CORRECT: Re-verify permissions server-side
+export async function updateRole(formData: FormData) {
+  const currentUser = await getCurrentUser();
+  if (!currentUser?.isSuperAdmin) {
+    return { success: false, message: "Not authorized" };
+  }
+  // Now safe to proceed...
+}
+```
+
+### 4. Return state, don't redirect
+```typescript
+// ❌ INCORRECT: Don't call redirect in actions
+redirect("/success");
+
+// ✅ CORRECT: Return state and handle redirect in client
+return { success: true, redirectTo: "/success" };
+```
+
+### 5. Validate all inputs with schema validation
+```typescript
+import { z } from "zod";
+
+const CreateUserSchema = z.object({
+  name: z.string().min(2).max(100),
+  email: z.string().email(),
+});
+
+export async function createUser(prevState: ActionState, formData: FormData) {
+  const validatedFields = CreateUserSchema.safeParse({
+    name: formData.get("name"),
+    email: formData.get("email"),
+  });
+
+  if (!validatedFields.success) {
+    return {
+      success: false,
+      message: "Invalid fields",
+      errors: validatedFields.error.flatten().fieldErrors,
+    };
+  }
+
+  // Use validatedFields.data (sanitized)
+}
+```
+
+### 6. Handle errors gracefully (don't leak internals)
+```typescript
+try {
+  // action logic
+} catch (error) {
+  // Log full error server-side
+  console.error("Action error:", error);
+
+  // Return generic message to client (don't expose internals)
+  return {
+    success: false,
+    message: "An error occurred. Please try again.",
+  };
+}
+```
+
+### 7. Revalidate after mutations
+```typescript
+revalidatePath("/affected-path");
+// or
+revalidateTag("users");
+```
+
+### 8. Avoid mutations during rendering
+```typescript
+// ❌ INCORRECT: Side effect during render
+export default async function Page({ searchParams }) {
+  if (searchParams.get("logout")) {
+    cookies().delete("AUTH_TOKEN"); // Bad!
+  }
+  return <div>...</div>;
+}
+
+// ✅ CORRECT: Use Server Action
+export default function Page() {
+  return (
+    <form action={logout}>
+      <button type="submit">Logout</button>
+    </form>
+  );
+}
+```
+
+## Closures Security
+
+When defining Server Actions inside components, be aware that closed-over variables
+are sent to the client (encrypted). Never close over sensitive data:
+
+```typescript
+// ⚠️ Sensitive data in closure (encrypted but still transmitted)
+export default async function Page() {
+  const secretKey = process.env.SECRET_KEY; // Don't do this!
+
+  async function submit() {
+    "use server";
+    // secretKey is captured and sent to client (encrypted)
+  }
+
+  return <form action={submit}>...</form>;
+}
+
+// ✅ CORRECT: Read secrets inside the action
+export default function Page() {
+  async function submit() {
+    "use server";
+    const secretKey = process.env.SECRET_KEY; // Safe - read server-side
+  }
+
+  return <form action={submit}>...</form>;
+}
+```
+
+## Using with useActionState
+
+```tsx
+"use client";
+
+import { useActionState } from "react";
+import { createUser } from "@/actions/user-actions";
+
+const initialState = { success: false, message: "" };
+
+export function UserForm() {
+  const [state, formAction, isPending] = useActionState(
+    createUser,
+    initialState
+  );
+
+  return (
+    <form action={formAction}>
+      <input name="name" required />
+      <input name="email" type="email" required />
+      <button type="submit" disabled={isPending}>
+        {isPending ? "Saving..." : "Save"}
+      </button>
+      {state.message && (
+        <p role="alert" className={state.success ? "text-green-600" : "text-red-600"}>
+          {state.message}
+        </p>
+      )}
+    </form>
+  );
+}
+```
+
+## Troubleshooting
+
+### Error: "Failed to find Server Action"
+
+**Cause**: Next.js creates encrypted, non-deterministic IDs for Server Actions. These IDs
+are recalculated between builds. In multi-server environments (self-hosted), each instance
+may have different encryption keys.
+
+**Solutions**:
+
+1. **Self-hosting with multiple servers**: Configure a consistent encryption key:
+   ```bash
+   # .env
+   NEXT_SERVER_ACTIONS_ENCRYPTION_KEY="your-aes-gcm-encrypted-key"
+   ```
+   The key must be AES-GCM encrypted and consistent across all servers.
+
+2. **Vercel**: Use [Skew Protection](https://vercel.com/docs/deployments/skew-protection) to
+   keep assets and functions from previous versions available after a deploy.
+
+3. **Local development**: If it occurs in development, restart the dev server (`npm run dev`).
+
+4. **Corrupted cache**: Clear the Next.js cache:
+   ```bash
+   rm -rf .next
+   npm run build
+   ```
+
+### Error: Action doesn't execute / Does nothing
+
+Verify that:
+- The function has `"use server"` at the top of the file OR inside the function
+- The form uses `action={formAction}` (not `onSubmit`)
+- There are no JavaScript errors in the browser console
+
+### Error: "Functions cannot be passed directly to Client Components"
+
+```typescript
+// ❌ INCORRECT: Passing function directly
+<ClientComponent onSubmit={serverAction} />
+
+// ✅ CORRECT: Use in form action or useActionState
+<form action={serverAction}>...</form>
+
+// ✅ CORRECT: Wrap in client component
+"use client";
+export function FormWrapper({ action }) {
+  const [state, formAction] = useActionState(action, initialState);
+  return <form action={formAction}>...</form>;
+}
+```
+
+## Security Checklist
+
+Before deploying any Server Action, verify:
+
+- [ ] `"use server"` directive is present
+- [ ] User is authenticated (if required)
+- [ ] User is authorized for the specific action
+- [ ] All inputs are validated (use Zod or similar)
+- [ ] Data access goes through DAL (not direct DB queries)
+- [ ] No sensitive data in closures
+- [ ] Error messages don't leak internal details
+- [ ] Cache is revalidated after mutations
+- [ ] DAL files are marked with `server-only`
+- [ ] `NEXT_SERVER_ACTIONS_ENCRYPTION_KEY` configured (if multi-server self-hosting)