devstack 0.1.0

package/templates/base/claude/skills/zod/references/perf-zod-mini.md

@@ -0,0 +1,118 @@
+---
+title: Use Zod Mini for Bundle-Sensitive Applications
+impact: LOW-MEDIUM
+impactDescription: Full Zod is ~17kb gzipped; Zod Mini is ~1.9kb - 85% smaller for frontend-critical bundles
+tags: perf, bundle, mini, tree-shaking
+---
+
+## Use Zod Mini for Bundle-Sensitive Applications
+
+For frontend applications where bundle size is critical, use `@zod/mini` instead of `zod`. Zod Mini provides the same validation capabilities with a functional API that tree-shakes better, reducing bundle size by ~85%.
+
+**When to consider Zod Mini:**
+
+```typescript
+// Your app if:
+// - Bundle size is critical (mobile-first, slow networks)
+// - Edge functions with size limits
+// - Simple validation needs (no complex transforms)
+// - Tree-shaking is important
+
+// Zod: ~17kb gzipped
+import { z } from "zod";
+
+// Zod Mini: ~1.9kb gzipped (when tree-shaken)
+import * as z from "@zod/mini";
+```
+
+**Standard Zod (method chaining):**
+
+```typescript
+import { z } from "zod";
+
+// Methods are attached to schema objects - hard to tree-shake
+const userSchema = z.object({
+  name: z.string().min(1).max(100),
+  email: z.string().email(),
+  age: z.number().int().positive(),
+});
+
+const result = userSchema.safeParse(data);
+```
+
+**Zod Mini (functional API):**
+
+```typescript
+import * as z from "@zod/mini";
+
+// Functions are imported individually - tree-shakeable
+const userSchema = z.object({
+  name: z.pipe(z.string(), z.minLength(1), z.maxLength(100)),
+  email: z.pipe(z.string(), z.email()),
+  age: z.pipe(z.number(), z.int(), z.positive()),
+});
+
+const result = z.safeParse(userSchema, data);
+```
+
+**API differences:**
+
+```typescript
+// Standard Zod
+z.string().min(5).max(100).email();
+z.number().int().positive();
+z.array(z.string()).min(1);
+schema.parse(data);
+schema.safeParse(data);
+
+// Zod Mini
+z.pipe(z.string(), z.minLength(5), z.maxLength(100), z.email());
+z.pipe(z.number(), z.int(), z.positive());
+z.pipe(z.array(z.string()), z.minLength(1));
+z.parse(schema, data);
+z.safeParse(schema, data);
+```
+
+**When to stick with regular Zod:**
+
+```typescript
+// Use regular Zod when:
+// - Server-side where bundle size doesn't matter
+// - Complex schemas with many transforms
+// - Need full method chaining ergonomics
+// - Bundle size isn't a constraint
+
+// The 17kb isn't huge - only optimize if needed
+// Server: 17kb is negligible
+// Browser: 17kb ≈ 0.6ms additional startup on 3G
+```
+
+**Shared schemas between packages:**
+
+```typescript
+// shared-schemas/package.json
+{
+  "dependencies": {
+    "@zod/mini": "^4.0.0"  // Mini for frontend-shared schemas
+  }
+}
+
+// If you need both, Zod Mini schemas work with regular Zod
+// But prefer consistency - pick one for your codebase
+```
+
+**Bundle size comparison:**
+
+| Package     | Gzipped Size | Use Case        |
+| ----------- | ------------ | --------------- |
+| `zod@3`     | ~13kb        | Legacy, stable  |
+| `zod@4`     | ~17kb        | Full features   |
+| `@zod/mini` | ~1.9kb       | Bundle-critical |
+
+**When NOT to use this pattern:**
+
+- Server-side applications (bundle size irrelevant)
+- When method chaining ergonomics are preferred
+- Complex schemas that benefit from full API
+
+Reference: [Zod Mini](https://zod.dev/packages/mini)

package/templates/base/claude/skills/zod/references/refine-add-path.md

@@ -0,0 +1,149 @@
+---
+title: Add Path to Refinement Errors
+impact: MEDIUM
+impactDescription: Errors without path show at object level; adding path highlights the specific field that failed
+tags: refine, path, errors, forms
+---
+
+## Add Path to Refinement Errors
+
+When using `.refine()` on object schemas for cross-field validation, add a `path` option to indicate which field the error relates to. Without it, the error appears at the object level, making form error display confusing.
+
+**Incorrect (error at object level):**
+
+```typescript
+import { z } from "zod";
+
+const formSchema = z
+  .object({
+    password: z.string().min(8),
+    confirmPassword: z.string(),
+  })
+  .refine(
+    data => data.password === data.confirmPassword,
+    { message: "Passwords do not match" } // No path specified
+  );
+
+const result = formSchema.safeParse({
+  password: "secret123",
+  confirmPassword: "different",
+});
+
+if (!result.success) {
+  const flattened = result.error.flatten();
+  // {
+  //   formErrors: ['Passwords do not match'],  // At form level!
+  //   fieldErrors: {}  // Empty - no field association
+  // }
+}
+
+// Form UI can't highlight which field has the error
+```
+
+**Correct (error with path):**
+
+```typescript
+import { z } from "zod";
+
+const formSchema = z
+  .object({
+    password: z.string().min(8),
+    confirmPassword: z.string(),
+  })
+  .refine(data => data.password === data.confirmPassword, {
+    message: "Passwords do not match",
+    path: ["confirmPassword"], // Error appears on this field
+  });
+
+const result = formSchema.safeParse({
+  password: "secret123",
+  confirmPassword: "different",
+});
+
+if (!result.success) {
+  const flattened = result.error.flatten();
+  // {
+  //   formErrors: [],
+  //   fieldErrors: {
+  //     confirmPassword: ['Passwords do not match']  // Associated with field
+  //   }
+  // }
+}
+
+// Form can now show error next to confirmPassword input
+```
+
+**Multiple cross-field validations:**
+
+```typescript
+const dateRangeSchema = z
+  .object({
+    startDate: z.coerce.date(),
+    endDate: z.coerce.date(),
+    minDays: z.number().optional(),
+    maxDays: z.number().optional(),
+  })
+  .refine(data => data.endDate >= data.startDate, {
+    message: "End date must be after start date",
+    path: ["endDate"],
+  })
+  .refine(
+    data => {
+      if (!data.minDays) return true;
+      const days = (data.endDate.getTime() - data.startDate.getTime()) / 86400000;
+      return days >= data.minDays;
+    },
+    { message: "Date range is too short", path: ["endDate"] }
+  )
+  .refine(
+    data => {
+      if (!data.maxDays) return true;
+      const days = (data.endDate.getTime() - data.startDate.getTime()) / 86400000;
+      return days <= data.maxDays;
+    },
+    { message: "Date range is too long", path: ["endDate"] }
+  );
+```
+
+**With superRefine for multiple path errors:**
+
+```typescript
+const orderSchema = z
+  .object({
+    billingAddress: z.object({
+      street: z.string(),
+      city: z.string(),
+    }),
+    shippingAddress: z.object({
+      street: z.string(),
+      city: z.string(),
+    }),
+    sameAsBilling: z.boolean(),
+  })
+  .superRefine((data, ctx) => {
+    if (data.sameAsBilling) {
+      // If sameAsBilling but addresses differ, show errors on shipping
+      if (data.shippingAddress.street !== data.billingAddress.street) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          message: "Must match billing address",
+          path: ["shippingAddress", "street"], // Nested path
+        });
+      }
+      if (data.shippingAddress.city !== data.billingAddress.city) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          message: "Must match billing address",
+          path: ["shippingAddress", "city"],
+        });
+      }
+    }
+  });
+```
+
+**When NOT to use this pattern:**
+
+- When the error genuinely applies to the whole object
+- Simple single-field refinements (path is implicit)
+
+Reference: [Zod API - refine](https://zod.dev/api#refine)

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

@@ -0,0 +1,138 @@
+---
+title: Use catch() for Fault-Tolerant Parsing
+impact: MEDIUM
+impactDescription: parse() fails on first invalid field; catch() provides fallback values, enabling partial success with degraded data
+tags: refine, catch, fallback, resilience
+---
+
+## Use catch() for Fault-Tolerant Parsing
+
+When parsing data that might have some invalid fields but you want to accept what's valid, use `.catch()` to provide fallback values instead of failing entirely. This enables graceful degradation for partially corrupted data.
+
+**Incorrect (all-or-nothing parsing):**
+
+```typescript
+import { z } from "zod";
+
+const userPrefsSchema = z.object({
+  theme: z.enum(["light", "dark"]),
+  fontSize: z.number().min(8).max(32),
+  language: z.string(),
+  notifications: z.boolean(),
+});
+
+// Corrupted localStorage data
+const stored = {
+  theme: "invalid-theme", // Bad
+  fontSize: 200, // Bad
+  language: "en", // Good
+  notifications: "yes", // Bad - should be boolean
+};
+
+userPrefsSchema.parse(stored);
+// ZodError: Invalid enum value at "theme"
+// User loses ALL their preferences because one field is bad
+```
+
+**Correct (fault-tolerant with catch):**
+
+```typescript
+import { z } from "zod";
+
+const userPrefsSchema = z.object({
+  theme: z.enum(["light", "dark"]).catch("light"),
+  fontSize: z.number().min(8).max(32).catch(16),
+  language: z.string().catch("en"),
+  notifications: z.boolean().catch(true),
+});
+
+// Corrupted data
+const stored = {
+  theme: "invalid-theme",
+  fontSize: 200,
+  language: "en",
+  notifications: "yes",
+};
+
+const prefs = userPrefsSchema.parse(stored);
+// {
+//   theme: 'light',      // Fallback used
+//   fontSize: 16,        // Fallback used
+//   language: 'en',      // Original value preserved
+//   notifications: true  // Fallback used
+// }
+// User gets mostly working preferences instead of error
+```
+
+**Catch with factory function:**
+
+```typescript
+// Factory function receives the caught error
+const schema = z.object({
+  data: z.array(z.number()).catch(ctx => {
+    console.warn("Invalid data array:", ctx.error);
+    return []; // Return empty array as fallback
+  }),
+});
+```
+
+**Use case: API response resilience:**
+
+```typescript
+const productSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  price: z.number().positive(),
+  // Legacy field that might be missing or wrong format
+  legacyCode: z.string().catch("UNKNOWN"),
+  // External data that might be malformed
+  metadata: z.record(z.string()).catch({}),
+});
+
+// API returns partial data
+const apiResponse = {
+  id: "prod-123",
+  name: "Widget",
+  price: 29.99,
+  legacyCode: null, // Bad - should be string
+  metadata: "invalid", // Bad - should be object
+};
+
+const product = productSchema.parse(apiResponse);
+// Works! Returns product with fallbacks for bad fields
+```
+
+**Difference between catch() and default():**
+
+```typescript
+// .default() - only fills in undefined
+z.string().default("fallback");
+// undefined -> 'fallback'
+// null -> ZodError
+// '' -> '' (empty string is valid)
+
+// .catch() - fallback for ANY parse failure
+z.string().catch("fallback");
+// undefined -> 'fallback'
+// null -> 'fallback'
+// 123 -> 'fallback'
+// Even valid strings pass through unchanged
+```
+
+**Combining catch with validation:**
+
+```typescript
+// Catch only specific validation failures
+const schema = z.string().email().catch("invalid@example.com"); // Fallback if not valid email
+
+// Chain for complex defaults
+const ageSchema = z.coerce.number().int().min(0).max(120).catch(0); // Invalid ages become 0
+```
+
+**When NOT to use this pattern:**
+
+- When invalid data should cause errors (strict validation)
+- When you need to know which fields failed (use safeParse)
+- Critical fields that must be valid
+
+Reference: [Zod API - catch](https://zod.dev/api#catch)

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

@@ -0,0 +1,132 @@
+---
+title: Use default() for Optional Fields with Defaults
+impact: MEDIUM
+impactDescription: Manual default handling spreads logic across codebase; .default() centralizes defaults in schema
+tags: refine, default, optional, configuration
+---
+
+## Use default() for Optional Fields with Defaults
+
+When a field is optional but should have a default value when missing, use `.default()` instead of handling defaults in business logic. This keeps default values centralized in the schema and ensures consistent behavior.
+
+**Incorrect (defaults spread across codebase):**
+
+```typescript
+import { z } from "zod";
+
+const configSchema = z.object({
+  timeout: z.number().optional(),
+  retries: z.number().optional(),
+  debug: z.boolean().optional(),
+});
+
+type Config = z.infer<typeof configSchema>;
+
+function createClient(config: Config) {
+  // Defaults handled in business logic - duplicated everywhere
+  const timeout = config.timeout ?? 5000;
+  const retries = config.retries ?? 3;
+  const debug = config.debug ?? false;
+
+  // ...
+}
+
+function createOtherClient(config: Config) {
+  // Same defaults duplicated - risk of inconsistency
+  const timeout = config.timeout ?? 5000;
+  const retries = config.retries ?? 3; // What if someone uses 2 here?
+  const debug = config.debug ?? false;
+
+  // ...
+}
+```
+
+**Correct (defaults in schema):**
+
+```typescript
+import { z } from "zod";
+
+const configSchema = z.object({
+  timeout: z.number().default(5000),
+  retries: z.number().default(3),
+  debug: z.boolean().default(false),
+});
+
+type Config = z.infer<typeof configSchema>;
+// { timeout: number; retries: number; debug: boolean }
+// No optional - defaults fill in missing values
+
+function createClient(config: Config) {
+  // config.timeout is guaranteed to exist
+  console.log(config.timeout); // 5000 if not provided
+  console.log(config.retries); // 3 if not provided
+  console.log(config.debug); // false if not provided
+}
+
+// Parse fills in defaults
+configSchema.parse({});
+// { timeout: 5000, retries: 3, debug: false }
+
+configSchema.parse({ timeout: 10000 });
+// { timeout: 10000, retries: 3, debug: false }
+```
+
+**Input type vs Output type with defaults:**
+
+```typescript
+const schema = z.object({
+  name: z.string(),
+  role: z.enum(["admin", "user"]).default("user"),
+});
+
+type SchemaInput = z.input<typeof schema>;
+// { name: string; role?: 'admin' | 'user' }
+
+type SchemaOutput = z.output<typeof schema>;
+// { name: string; role: 'admin' | 'user' }
+
+// Input type is optional, output type is required
+```
+
+**Default with factory function:**
+
+```typescript
+// Static default
+const schema1 = z.object({
+  id: z.string().default("temp-id"),
+});
+
+// Factory function for dynamic defaults
+const schema2 = z.object({
+  id: z.string().default(() => crypto.randomUUID()),
+  createdAt: z.date().default(() => new Date()),
+});
+
+// Each parse creates new values
+schema2.parse({}); // { id: 'abc-123...', createdAt: 2024-01-15... }
+schema2.parse({}); // { id: 'def-456...', createdAt: 2024-01-15... }
+```
+
+**Combining with optional/nullable:**
+
+```typescript
+// .optional().default() - if undefined, use default
+z.string().optional().default("fallback");
+
+// .nullable().default() - null stays null, only undefined gets default
+z.string().nullable().default("fallback");
+// null -> null
+// undefined -> 'fallback'
+
+// .nullish().default() - both null and undefined get default
+z.string().nullish().default("fallback");
+// null -> 'fallback'
+// undefined -> 'fallback'
+```
+
+**When NOT to use this pattern:**
+
+- When absence of value has different meaning than default
+- When defaults depend on other fields (use transform)
+
+Reference: [Zod API - default](https://zod.dev/api#default)

package/templates/base/claude/skills/zod/references/refine-transform-coerce.md

@@ -0,0 +1,103 @@
+---
+title: Distinguish transform() from refine() and coerce()
+impact: MEDIUM
+impactDescription: Using wrong method causes validation to pass with wrong data; each method has distinct purpose
+tags: refine, transform, coerce, conversion
+---
+
+## Distinguish transform() from refine() and coerce()
+
+`.refine()` validates and returns boolean, `.transform()` converts data to new format, and `.coerce` converts input before validation. Using the wrong one causes bugs where validation passes but data is wrong.
+
+**Purpose of each method:**
+
+```typescript
+import { z } from "zod";
+
+// coerce: Convert type BEFORE validation
+// Input: unknown -> Output: validated type
+z.coerce.number().parse("42"); // Converts "42" to 42, then validates as number
+
+// refine: Validate with custom logic, return boolean
+// Input: T -> Output: T (unchanged, but validated)
+z.number().refine(n => n > 0); // Validates n > 0, returns n unchanged
+
+// transform: Convert to different type AFTER validation
+// Input: T -> Output: U (different type)
+z.string().transform(s => s.length); // Validates string, returns length
+```
+
+**Incorrect (using transform for validation):**
+
+```typescript
+// Wrong: transform should convert, not validate
+const schema = z.number().transform(n => {
+  if (n < 0) throw new Error("Must be positive"); // Don't throw in transform
+  return n;
+});
+```
+
+**Correct (using appropriate method):**
+
+```typescript
+import { z } from "zod";
+
+// VALIDATION: Use refine - returns boolean, data unchanged
+const positiveNumber = z.number().refine(n => n > 0, { message: "Must be positive" });
+
+positiveNumber.parse(5); // 5
+positiveNumber.parse(-1); // ZodError: Must be positive
+
+// CONVERSION: Use transform - returns new value
+const stringLength = z.string().transform(s => s.length);
+
+type StringLength = z.infer<typeof stringLength>; // number
+stringLength.parse("hello"); // 5
+
+// COERCION: Use coerce - converts input type
+const coercedNumber = z.coerce.number();
+
+coercedNumber.parse("42"); // 42 (from string)
+coercedNumber.parse(42); // 42 (already number)
+```
+
+**Combining methods correctly:**
+
+```typescript
+// Input: string -> Coerce to number -> Validate positive -> Transform to dollars
+const priceSchema = z.coerce
+  .number()
+  .refine(n => n >= 0, "Price cannot be negative")
+  .transform(cents => `$${(cents / 100).toFixed(2)}`);
+
+priceSchema.parse("1999"); // "$19.99"
+priceSchema.parse("-100"); // ZodError: Price cannot be negative
+```
+
+**Order of operations:**
+
+```typescript
+const schema = z
+  .preprocess(val => val, z.string()) // 1. preprocess (before type check)
+  .transform(s => s.trim()) // 2. transform (after type check)
+  .refine(s => s.length > 0) // 3. refine (custom validation)
+  .transform(s => s.toUpperCase()); // 4. another transform
+
+// Input flows: preprocess -> type check -> transforms/refines in order
+```
+
+**Use case comparison:**
+
+| Need                         | Method                   | Example        |
+| ---------------------------- | ------------------------ | -------------- |
+| Convert string to number     | `z.coerce.number()`      | Form input     |
+| Validate number is positive  | `.refine(n => n > 0)`    | Business rule  |
+| Convert cents to dollars     | `.transform(n => n/100)` | Display format |
+| Trim whitespace before check | `z.preprocess`           | Input cleanup  |
+
+**When NOT to use this pattern:**
+
+- Simple type coercion: use `z.coerce.*`
+- Simple validation: use built-in methods like `.min()`, `.email()`
+
+Reference: [Zod API - transform](https://zod.dev/api#transform)