devstack 0.1.0

package/templates/base/claude/skills/zod/references/refine-vs-superrefine.md

@@ -0,0 +1,159 @@
+---
+title: Choose refine() vs superRefine() Correctly
+impact: MEDIUM
+impactDescription: refine() only reports one error; superRefine() enables multiple issues and custom error codes
+tags: refine, superRefine, validation, custom
+---
+
+## Choose refine() vs superRefine() Correctly
+
+`.refine()` is for simple single-condition validation returning boolean. `.superRefine()` gives you a context object to add multiple issues with custom error codes and paths. Choose based on your error reporting needs.
+
+**Incorrect (using refine for multiple checks):**
+
+```typescript
+import { z } from "zod";
+
+// refine can only report one error at a time
+const passwordSchema = z.string().refine(
+  password => {
+    // Checks all conditions but only reports first failure
+    if (password.length < 8) return false; // Only this error shown
+    if (!/[A-Z]/.test(password)) return false;
+    if (!/[0-9]/.test(password)) return false;
+    return true;
+  },
+  { message: "Password does not meet requirements" }
+);
+
+passwordSchema.parse("weak");
+// Only shows: "Password does not meet requirements"
+// User doesn't know WHICH requirements failed
+```
+
+**Correct (using superRefine for multiple issues):**
+
+```typescript
+import { z } from "zod";
+
+const passwordSchema = z.string().superRefine((password, ctx) => {
+  if (password.length < 8) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      message: "Password must be at least 8 characters",
+    });
+  }
+
+  if (!/[A-Z]/.test(password)) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      message: "Password must contain an uppercase letter",
+    });
+  }
+
+  if (!/[0-9]/.test(password)) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      message: "Password must contain a number",
+    });
+  }
+
+  if (!/[!@#$%^&*]/.test(password)) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      message: "Password must contain a special character",
+    });
+  }
+});
+
+passwordSchema.safeParse("weak");
+// Shows ALL failures:
+// - "Password must be at least 8 characters"
+// - "Password must contain an uppercase letter"
+// - "Password must contain a number"
+// - "Password must contain a special character"
+```
+
+**When to use refine():**
+
+```typescript
+// Simple boolean condition with one error message
+const adultSchema = z.number().refine(age => age >= 18, { message: "Must be 18 or older" });
+
+// Cross-field validation with single outcome
+const formSchema = z
+  .object({
+    password: z.string(),
+    confirmPassword: z.string(),
+  })
+  .refine(data => data.password === data.confirmPassword, {
+    message: "Passwords must match",
+    path: ["confirmPassword"],
+  });
+
+// Async validation
+const emailSchema = z
+  .string()
+  .email()
+  .refine(
+    async email => {
+      const exists = await checkEmailExists(email);
+      return !exists;
+    },
+    { message: "Email already registered" }
+  );
+```
+
+**When to use superRefine():**
+
+```typescript
+// Multiple independent checks on same value
+// Cross-field validation with multiple possible errors
+// Need custom error codes for i18n or client handling
+// Need to add issues at specific paths
+
+const orderSchema = z
+  .object({
+    items: z.array(
+      z.object({
+        productId: z.string(),
+        quantity: z.number(),
+      })
+    ),
+    promoCode: z.string().optional(),
+  })
+  .superRefine(async (order, ctx) => {
+    // Check each item's availability
+    for (let i = 0; i < order.items.length; i++) {
+      const item = order.items[i];
+      const available = await checkInventory(item.productId, item.quantity);
+
+      if (!available) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          path: ["items", i, "quantity"], // Specific path
+          message: `Only ${available} units available`,
+        });
+      }
+    }
+
+    // Validate promo code
+    if (order.promoCode) {
+      const valid = await validatePromoCode(order.promoCode);
+      if (!valid) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          path: ["promoCode"],
+          message: "Invalid or expired promo code",
+        });
+      }
+    }
+  });
+```
+
+**When NOT to use this pattern:**
+
+- Simple single-condition checks (use refine for simplicity)
+- Transform needed instead of validation (use transform)
+
+Reference: [Zod API - refine/superRefine](https://zod.dev/api#refine)

package/templates/base/claude/skills/zod/references/schema-avoid-optional-abuse.md

@@ -0,0 +1,94 @@
+---
+title: Avoid Overusing Optional Fields
+impact: CRITICAL
+impactDescription: Excessive optional fields create schemas that accept almost anything; forces null checks throughout codebase
+tags: schema, optional, nullable, required
+---
+
+## Avoid Overusing Optional Fields
+
+Making too many fields optional creates overly permissive schemas that validate almost any input. This pushes validation downstream into business logic, requiring defensive null checks everywhere instead of guaranteeing data shape at the boundary.
+
+**Incorrect (optional abuse):**
+
+```typescript
+import { z } from "zod";
+
+// Every field optional - almost anything passes
+const userSchema = z.object({
+  id: z.string().optional(),
+  name: z.string().optional(),
+  email: z.string().optional(),
+  role: z.string().optional(),
+});
+
+type User = z.infer<typeof userSchema>;
+// { id?: string; name?: string; email?: string; role?: string }
+
+// Empty object passes validation!
+userSchema.parse({}); // ✓ Valid: {}
+
+function greetUser(user: User) {
+  // Forced to add null checks everywhere
+  if (user.name) {
+    console.log(`Hello, ${user.name}`);
+  } else {
+    console.log("Hello, stranger"); // Shouldn't happen if data is clean
+  }
+}
+```
+
+**Correct (explicit required vs optional):**
+
+```typescript
+import { z } from "zod";
+
+// Required fields are required, optional fields are intentional
+const userSchema = z.object({
+  id: z.string().uuid(), // Required
+  name: z.string().min(1), // Required, non-empty
+  email: z.string().email(), // Required
+  role: z.enum(["admin", "user", "guest"]), // Required
+  nickname: z.string().optional(), // Intentionally optional
+  bio: z.string().nullable(), // Can be explicitly null
+});
+
+type User = z.infer<typeof userSchema>;
+
+// Empty object fails validation
+userSchema.parse({}); // ✗ Throws ZodError
+
+function greetUser(user: User) {
+  // user.name is guaranteed to exist
+  console.log(`Hello, ${user.name}`);
+
+  // Only optional fields need checks
+  if (user.nickname) {
+    console.log(`Also known as: ${user.nickname}`);
+  }
+}
+```
+
+**Use `.partial()` for update schemas:**
+
+```typescript
+// Base schema with required fields
+const userSchema = z.object({
+  id: z.string().uuid(),
+  name: z.string().min(1),
+  email: z.string().email(),
+});
+
+// All fields optional for PATCH updates
+const updateUserSchema = userSchema.partial();
+
+// Only specific fields optional
+const createUserSchema = userSchema.partial({ id: true });
+```
+
+**When NOT to use this pattern:**
+
+- When modeling partial updates (PATCH endpoints)
+- When fields genuinely may not exist (legacy data, external APIs)
+
+Reference: [Zod API - optional](https://zod.dev/api#optional)

package/templates/base/claude/skills/zod/references/schema-coercion-for-form-data.md

@@ -0,0 +1,89 @@
+---
+title: Use Coercion for Form and Query Data
+impact: CRITICAL
+impactDescription: Form data and query params are always strings; without coercion, z.number() rejects "42" and z.boolean() rejects "true"
+tags: schema, coerce, forms, query-params
+---
+
+## Use Coercion for Form and Query Data
+
+HTML forms and URL query parameters always transmit data as strings. Using `z.number()` on form data will fail because `"42"` is not a number. Use `z.coerce.number()` to automatically convert strings to the correct type.
+
+**Incorrect (no coercion for form data):**
+
+```typescript
+import { z } from "zod";
+
+const searchSchema = z.object({
+  query: z.string(),
+  page: z.number(), // Expects actual number
+  limit: z.number(),
+  showDeleted: z.boolean(), // Expects actual boolean
+});
+
+// Form data / query params are strings
+const formData = new URLSearchParams("query=test&page=1&limit=10&showDeleted=true");
+const params = Object.fromEntries(formData);
+// { query: 'test', page: '1', limit: '10', showDeleted: 'true' }
+
+searchSchema.parse(params);
+// ZodError: Expected number, received string at "page"
+// ZodError: Expected number, received string at "limit"
+// ZodError: Expected boolean, received string at "showDeleted"
+```
+
+**Correct (using coercion):**
+
+```typescript
+import { z } from "zod";
+
+const searchSchema = z.object({
+  query: z.string(),
+  page: z.coerce.number().int().positive().default(1),
+  limit: z.coerce.number().int().min(1).max(100).default(10),
+  showDeleted: z.coerce.boolean().default(false),
+});
+
+// Form data / query params are strings
+const formData = new URLSearchParams("query=test&page=1&limit=10&showDeleted=true");
+const params = Object.fromEntries(formData);
+
+const result = searchSchema.parse(params);
+// { query: 'test', page: 1, limit: 10, showDeleted: true }
+// Types are correct: number, number, boolean
+```
+
+**Available coercion types:**
+
+```typescript
+z.coerce.string(); // Converts anything to string via String(value)
+z.coerce.number(); // Converts via Number(value), NaN fails validation
+z.coerce.boolean(); // Truthy/falsy conversion
+z.coerce.bigint(); // Converts via BigInt(value)
+z.coerce.date(); // Converts via new Date(value)
+```
+
+**Coercion edge cases:**
+
+```typescript
+// z.coerce.number() behavior
+z.coerce.number().parse("42"); // 42
+z.coerce.number().parse(""); // 0 (empty string becomes 0!)
+z.coerce.number().parse("abc"); // ZodError (NaN fails)
+
+// z.coerce.boolean() behavior
+z.coerce.boolean().parse("true"); // true
+z.coerce.boolean().parse("false"); // true! (non-empty string is truthy)
+z.coerce.boolean().parse(""); // false
+z.coerce.boolean().parse("0"); // true! (non-empty string)
+
+// For strict boolean parsing from strings:
+const strictBooleanSchema = z.enum(["true", "false"]).transform(v => v === "true");
+```
+
+**When NOT to use this pattern:**
+
+- When receiving JSON payloads (already typed correctly)
+- When you want strict type checking without conversion
+
+Reference: [Zod API - Coercion](https://zod.dev/api#coercion)

package/templates/base/claude/skills/zod/references/schema-string-validations.md

@@ -0,0 +1,87 @@
+---
+title: Apply String Validations at Schema Definition
+impact: CRITICAL
+impactDescription: Unvalidated strings allow SQL injection, XSS, and malformed data; validating at schema level catches issues at the boundary
+tags: schema, string, validation, security
+---
+
+## Apply String Validations at Schema Definition
+
+Plain `z.string()` accepts any string including empty strings, extremely long strings, and malicious content. Apply constraints like `min()`, `max()`, `email()`, `url()`, or `regex()` at schema definition to reject invalid data at the boundary.
+
+**Incorrect (no string validations):**
+
+```typescript
+import { z } from "zod";
+
+const commentSchema = z.object({
+  author: z.string(), // Empty string passes
+  email: z.string(), // "not-an-email" passes
+  content: z.string(), // 10MB string passes, script tags pass
+  website: z.string().optional(), // "javascript:alert(1)" passes
+});
+
+// All of these pass validation
+commentSchema.parse({
+  author: "", // Empty - who wrote this?
+  email: "invalid", // Not a real email
+  content: '<script>alert("XSS")</script>'.repeat(100000), // XSS + huge
+  website: "javascript:void(0)", // Dangerous URL
+});
+```
+
+**Correct (string validations applied):**
+
+```typescript
+import { z } from "zod";
+
+const commentSchema = z.object({
+  author: z.string().min(1, "Author is required").max(100, "Author name too long"),
+
+  email: z.string().email("Invalid email address"),
+
+  content: z.string().min(1, "Comment cannot be empty").max(5000, "Comment too long"),
+
+  website: z
+    .string()
+    .url("Invalid URL")
+    .refine(
+      url => url.startsWith("http://") || url.startsWith("https://"),
+      "Only http/https URLs allowed"
+    )
+    .optional(),
+});
+
+// Invalid data is rejected
+commentSchema.parse({
+  author: "",
+  email: "invalid",
+  content: "",
+});
+// ZodError with all violations listed
+```
+
+**Common string validations:**
+
+```typescript
+z.string().min(1); // Non-empty (most common need)
+z.string().max(255); // Database varchar limit
+z.string().length(36); // Exact length (UUIDs)
+z.string().email(); // Email format
+z.string().url(); // URL format
+z.string().uuid(); // UUID format
+z.string().cuid(); // CUID format
+z.string().regex(/^[a-z0-9-]+$/); // Custom pattern (slugs)
+z.string().startsWith("https://"); // Prefix check
+z.string().endsWith(".pdf"); // Suffix check
+z.string().includes("@"); // Contains check
+z.string().trim(); // Strips whitespace (transform)
+z.string().toLowerCase(); // Normalizes case (transform)
+```
+
+**When NOT to use this pattern:**
+
+- When accepting arbitrary user content for display only (sanitize on output instead)
+- When building a passthrough/proxy that shouldn't validate content
+
+Reference: [Zod API - Strings](https://zod.dev/api#strings)

package/templates/base/claude/skills/zod/references/schema-use-enums.md

@@ -0,0 +1,106 @@
+---
+title: Use Enums for Fixed String Values
+impact: CRITICAL
+impactDescription: Plain strings accept any value including typos; enums restrict to valid values and enable autocomplete
+tags: schema, enum, literal, union
+---
+
+## Use Enums for Fixed String Values
+
+When a field should only accept specific values (status, role, type), use `z.enum()` or `z.literal()` instead of `z.string()`. Plain strings accept any value including typos, while enums provide validation, type safety, and IDE autocomplete.
+
+**Incorrect (plain string for fixed values):**
+
+```typescript
+import { z } from "zod";
+
+const orderSchema = z.object({
+  id: z.string(),
+  status: z.string(), // Accepts any string
+  priority: z.string(), // No constraints
+});
+
+type Order = z.infer<typeof orderSchema>;
+// { id: string; status: string; priority: string }
+
+// Typos and invalid values pass validation
+orderSchema.parse({
+  id: "123",
+  status: "pendng", // Typo passes
+  priority: "super-urgent", // Invalid value passes
+});
+
+function processOrder(order: Order) {
+  if (order.status === "pending") {
+    // Might never match due to typos
+    // ...
+  }
+}
+```
+
+**Correct (using z.enum):**
+
+```typescript
+import { z } from "zod";
+
+const OrderStatus = z.enum(["pending", "processing", "shipped", "delivered"]);
+const Priority = z.enum(["low", "medium", "high"]);
+
+const orderSchema = z.object({
+  id: z.string(),
+  status: OrderStatus,
+  priority: Priority,
+});
+
+type Order = z.infer<typeof orderSchema>;
+// { id: string; status: 'pending' | 'processing' | 'shipped' | 'delivered'; priority: 'low' | 'medium' | 'high' }
+
+// Typos are caught at validation
+orderSchema.parse({
+  id: "123",
+  status: "pendng", // ZodError: Invalid enum value
+  priority: "super-urgent", // ZodError: Invalid enum value
+});
+
+// Extract enum values for reuse
+OrderStatus.options; // ['pending', 'processing', 'shipped', 'delivered']
+type OrderStatusType = z.infer<typeof OrderStatus>; // 'pending' | 'processing' | ...
+```
+
+**For native TypeScript enums:**
+
+```typescript
+enum Role {
+  Admin = "admin",
+  User = "user",
+  Guest = "guest",
+}
+
+// Use z.nativeEnum for TS enums
+const userSchema = z.object({
+  role: z.nativeEnum(Role),
+});
+```
+
+**For single literal values (discriminated unions):**
+
+```typescript
+const successResponse = z.object({
+  status: z.literal("success"),
+  data: z.unknown(),
+});
+
+const errorResponse = z.object({
+  status: z.literal("error"),
+  message: z.string(),
+});
+
+const response = z.discriminatedUnion("status", [successResponse, errorResponse]);
+```
+
+**When NOT to use this pattern:**
+
+- When the set of valid values is dynamic or user-defined
+- When values come from a database that may have more options
+
+Reference: [Zod API - Enums](https://zod.dev/api#enums)

package/templates/base/claude/skills/zod/references/schema-use-primitives-correctly.md

@@ -0,0 +1,63 @@
+---
+title: Use Primitive Schemas Correctly
+impact: CRITICAL
+impactDescription: Incorrect primitive selection causes validation to pass on wrong types; using z.any() or z.unknown() loses all type safety
+tags: schema, primitives, types, basics
+---
+
+## Use Primitive Schemas Correctly
+
+Zod provides specific schemas for each primitive type. Using the wrong schema (e.g., `z.string()` when you need `z.number()`) or falling back to `z.any()` defeats the purpose of validation entirely, allowing corrupt data through.
+
+**Incorrect (wrong primitive or any):**
+
+```typescript
+import { z } from "zod";
+
+// Using any loses all type safety
+const userSchema = z.object({
+  id: z.any(), // Accepts anything - no validation
+  age: z.string(), // Wrong type - age should be number
+  active: z.any(), // Should be boolean
+});
+
+// This passes validation but data is wrong
+userSchema.parse({ id: null, age: "twenty", active: "yes" });
+// Result: { id: null, age: "twenty", active: "yes" }
+```
+
+**Correct (specific primitives):**
+
+```typescript
+import { z } from "zod";
+
+const userSchema = z.object({
+  id: z.string().uuid(), // Specific format validation
+  age: z.number().int().positive(), // Correct type with constraints
+  active: z.boolean(), // Exact boolean type
+});
+
+// Now invalid data is rejected
+userSchema.parse({ id: null, age: "twenty", active: "yes" });
+// Throws ZodError with specific field errors
+```
+
+**Available primitive schemas:**
+
+- `z.string()` - strings with optional regex, min, max, email, url, uuid
+- `z.number()` - numbers with optional int, positive, negative, min, max
+- `z.bigint()` - BigInt values
+- `z.boolean()` - true/false only
+- `z.date()` - Date objects
+- `z.symbol()` - Symbol type
+- `z.undefined()` - undefined only
+- `z.null()` - null only
+- `z.void()` - undefined (for function returns)
+- `z.never()` - no valid value
+
+**When NOT to use this pattern:**
+
+- When you genuinely need to accept any value (rare - consider `z.unknown()` instead)
+- When migrating legacy code incrementally (use `z.any()` temporarily, then fix)
+
+Reference: [Zod Primitives](https://zod.dev/api#primitives)

package/templates/base/claude/skills/zod/references/schema-use-unknown-not-any.md

@@ -0,0 +1,86 @@
+---
+title: Use z.unknown() Instead of z.any()
+impact: CRITICAL
+impactDescription: z.any() bypasses TypeScript's type system entirely; z.unknown() forces type narrowing before use
+tags: schema, unknown, any, type-safety
+---
+
+## Use z.unknown() Instead of z.any()
+
+`z.any()` infers to `any` type, disabling TypeScript's type checking for that value. `z.unknown()` infers to `unknown`, which forces you to narrow the type before using it. This preserves type safety while still allowing any input.
+
+**Incorrect (using z.any):**
+
+```typescript
+import { z } from "zod";
+
+const eventSchema = z.object({
+  type: z.string(),
+  payload: z.any(), // Infers to 'any'
+});
+
+type Event = z.infer<typeof eventSchema>;
+// { type: string; payload: any }
+
+function handleEvent(event: Event) {
+  // No type error - TypeScript allows anything
+  console.log(event.payload.foo.bar.baz); // Runtime crash if structure is wrong
+}
+```
+
+**Correct (using z.unknown):**
+
+```typescript
+import { z } from "zod";
+
+const eventSchema = z.object({
+  type: z.string(),
+  payload: z.unknown(), // Infers to 'unknown'
+});
+
+type Event = z.infer<typeof eventSchema>;
+// { type: string; payload: unknown }
+
+function handleEvent(event: Event) {
+  // TypeScript error: Object is of type 'unknown'
+  console.log(event.payload.foo); // Won't compile
+
+  // Must narrow type first
+  if (typeof event.payload === "object" && event.payload !== null) {
+    // Now TypeScript knows it's an object
+  }
+}
+```
+
+**Better approach with discriminated unions:**
+
+```typescript
+import { z } from "zod";
+
+const userCreatedSchema = z.object({
+  type: z.literal("user.created"),
+  payload: z.object({
+    userId: z.string(),
+    email: z.string().email(),
+  }),
+});
+
+const orderPlacedSchema = z.object({
+  type: z.literal("order.placed"),
+  payload: z.object({
+    orderId: z.string(),
+    amount: z.number(),
+  }),
+});
+
+const eventSchema = z.discriminatedUnion("type", [userCreatedSchema, orderPlacedSchema]);
+
+// Full type safety for each event type
+```
+
+**When NOT to use this pattern:**
+
+- When you're consuming a third-party API where you truly don't know the shape
+- When prototyping and will add proper types later
+
+Reference: [Zod API - unknown](https://zod.dev/api#unknown)