@harness-engineering/cli 1.23.1 → 1.24.0

package/dist/agents/skills/claude-code/zod-array-validation/SKILL.md

@@ -0,0 +1,160 @@
+# Zod Array Validation
+
+> Validate arrays, tuples, records, maps, and sets with Zod's collection primitives
+
+## When to Use
+
+- Validating lists of items with consistent shape (e.g., API response arrays, batch inputs)
+- Validating key-value maps where keys and values have known types
+- Working with fixed-length, typed positional data using tuples
+- Ensuring collections meet cardinality constraints (non-empty, length limits)
+
+## Instructions
+
+1. Use `z.array()` for lists of items with a uniform element schema:
+
+```typescript
+import { z } from 'zod';
+
+const TagsSchema = z.array(z.string());
+const NumberListSchema = z.array(z.number().positive());
+const UserListSchema = z.array(UserSchema);
+```
+
+2. Constrain array length with `.min()`, `.max()`, and `.length()`:
+
+```typescript
+const AtLeastOneSchema = z.array(z.string()).min(1, 'At least one item required');
+const BoundedSchema = z.array(z.number()).min(1).max(10);
+const ExactSizeSchema = z.array(z.string()).length(3, 'Must have exactly 3 items');
+```
+
+3. Use `.nonempty()` as a type-aware alternative to `.min(1)` — the inferred type becomes a non-empty tuple:
+
+```typescript
+const NonEmptyTags = z.array(z.string()).nonempty('At least one tag is required');
+type NonEmptyTags = z.infer<typeof NonEmptyTags>; // [string, ...string[]]
+```
+
+4. Use `z.tuple()` for fixed-length arrays with positional types:
+
+```typescript
+const PointSchema = z.tuple([z.number(), z.number()]);
+// [x, y] — exactly two numbers
+
+const RGBSchema = z.tuple([
+  z.number().min(0).max(255),
+  z.number().min(0).max(255),
+  z.number().min(0).max(255),
+]);
+
+// Tuple with rest element (fixed prefix + variable suffix)
+const AtLeastTwoStrings = z.tuple([z.string(), z.string()]).rest(z.string());
+```
+
+5. Use `z.record()` for key-value maps where keys are strings and values share a type:
+
+```typescript
+// Record with string keys and number values
+const ScoreMapSchema = z.record(z.number());
+// Equivalent to { [key: string]: number }
+
+// Record with validated string keys
+const EnvVarsSchema = z.record(z.string().min(1));
+
+// Record with typed keys (uses z.enum or z.string())
+const FeatFlagsSchema = z.record(z.enum(['featureA', 'featureB', 'featureC']), z.boolean());
+```
+
+6. Use `z.map()` for JavaScript `Map` objects:
+
+```typescript
+const StringToNumberMap = z.map(z.string(), z.number());
+// Parses: new Map([['a', 1], ['b', 2]])
+```
+
+7. Use `z.set()` for JavaScript `Set` objects:
+
+```typescript
+const UniqueTagsSchema = z.set(z.string());
+const BoundedSetSchema = z.set(z.number()).min(1).max(5);
+// Parses: new Set([1, 2, 3])
+```
+
+8. Use `.element` to access the element schema of an array for composition:
+
+```typescript
+const ItemsSchema = z.array(z.object({ id: z.string(), name: z.string() }));
+const ItemSchema = ItemsSchema.element; // z.ZodObject<...>
+type Item = z.infer<typeof ItemSchema>;
+```
+
+## Details
+
+**Array vs tuple — when to choose:**
+
+| Scenario                           | Use                   |
+| ---------------------------------- | --------------------- |
+| Variable-length, homogeneous items | `z.array()`           |
+| Fixed-length, positional items     | `z.tuple()`           |
+| Key-value pairs with string keys   | `z.record()`          |
+| JS Map/Set preservation            | `z.map()` / `z.set()` |
+
+**Unique element validation:**
+
+Zod does not have built-in uniqueness checking. Use `.refine()`:
+
+```typescript
+const UniqueStringsSchema = z.array(z.string()).refine((arr) => new Set(arr).size === arr.length, {
+  message: 'Array must contain unique values',
+});
+```
+
+**Transforming arrays:**
+
+```typescript
+// Sort after parsing
+const SortedNumbersSchema = z.array(z.number()).transform((arr) => [...arr].sort((a, b) => a - b));
+
+// Deduplicate
+const DeduplicatedSchema = z.array(z.string()).transform((arr) => [...new Set(arr)]);
+
+// Flatten
+const FlatTagsSchema = z.array(z.array(z.string())).transform((arr) => arr.flat());
+```
+
+**Paginated response pattern:**
+
+```typescript
+function paginatedSchema<T extends z.ZodTypeAny>(itemSchema: T) {
+  return z.object({
+    data: z.array(itemSchema),
+    total: z.number().int().nonnegative(),
+    page: z.number().int().positive(),
+    pageSize: z.number().int().positive(),
+  });
+}
+
+const PaginatedUsersSchema = paginatedSchema(UserSchema);
+type PaginatedUsers = z.infer<typeof PaginatedUsersSchema>;
+```
+
+## Source
+
+https://zod.dev/api#arrays
+
+## Process
+
+1. Read the instructions and examples in this document.
+2. Apply the patterns to your implementation, adapting to your specific context.
+3. Verify your implementation against the details and edge cases listed above.
+
+## Harness Integration
+
+- **Type:** knowledge — this skill is a reference document, not a procedural workflow.
+- **No tools or state** — consumed as context by other skills and agents.
+
+## Success Criteria
+
+- The patterns described in this document are applied correctly in the implementation.
+- Edge cases and anti-patterns listed in this document are avoided.

package/dist/agents/skills/claude-code/zod-array-validation/skill.yaml

@@ -0,0 +1,42 @@
+name: zod-array-validation
+version: "1.0.0"
+description: Validate arrays, tuples, records, maps, and sets with Zod's collection primitives
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths:
+  - "**/*.schema.ts"
+  - "**/*.schema.tsx"
+  - "**/schemas/**"
+  - "**/validation/**"
+related_skills:
+  - zod-schema-definition
+  - zod-union-discriminated
+  - zod-infer-types
+stack_signals:
+  - zod
+  - typescript
+keywords:
+  - zod
+  - array
+  - tuple
+  - record
+  - map
+  - set
+  - nonempty
+  - collection
+metadata:
+  author: community
+  upstream: "zod.dev"
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/claude-code/zod-async-validation/SKILL.md

@@ -0,0 +1,205 @@
+# Zod Async Validation
+
+> Run async Zod validation with parseAsync, safeParseAsync, async refinements, and external checks
+
+## When to Use
+
+- Validating uniqueness constraints against a database (e.g., email not already registered)
+- Calling an external service during validation (e.g., checking if an address is deliverable)
+- Running async transforms that fetch or process data
+- Using Zod in an async context (server actions, API handlers) where awaiting is natural
+
+## Instructions
+
+1. Use `.parseAsync()` when your schema contains async refinements or transforms:
+
+```typescript
+import { z } from 'zod';
+import { db } from '@/lib/db';
+
+const UniqueEmailSchema = z
+  .string()
+  .email()
+  .refine(
+    async (email) => {
+      const existing = await db.user.findUnique({ where: { email } });
+      return !existing;
+    },
+    { message: 'Email address is already registered' }
+  );
+
+// Must await — throws ZodError on failure
+const validEmail = await UniqueEmailSchema.parseAsync(rawEmail);
+```
+
+2. Use `.safeParseAsync()` for error handling without try/catch:
+
+```typescript
+const result = await UniqueEmailSchema.safeParseAsync(rawEmail);
+
+if (!result.success) {
+  const errors = result.error.flatten();
+  return { success: false, errors: errors.formErrors };
+}
+
+return { success: true, email: result.data };
+```
+
+3. Add async refinements to object schemas for cross-field async checks:
+
+```typescript
+const CreateAccountSchema = z
+  .object({
+    username: z.string().min(3).max(20),
+    email: z.string().email(),
+    password: z.string().min(8),
+  })
+  .superRefine(async (data, ctx) => {
+    const emailTaken = await db.user.findUnique({ where: { email: data.email } });
+    if (emailTaken) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: 'Email is already in use',
+        path: ['email'],
+      });
+    }
+
+    const usernameTaken = await db.user.findUnique({ where: { username: data.username } });
+    if (usernameTaken) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: 'Username is already taken',
+        path: ['username'],
+      });
+    }
+  });
+
+// In a server action:
+const result = await CreateAccountSchema.safeParseAsync(formData);
+```
+
+4. Use async transforms for data enrichment during parsing:
+
+```typescript
+const UserIdSchema = z
+  .string()
+  .uuid()
+  .transform(async (id) => {
+    const user = await db.user.findUniqueOrThrow({ where: { id } });
+    return user; // Output type is User, not string
+  });
+
+type ResolvedUser = z.infer<typeof UserIdSchema>; // User (database type)
+
+const user = await UserIdSchema.parseAsync(rawId);
+```
+
+5. Short-circuit expensive async checks using synchronous pre-checks:
+
+```typescript
+const SlugSchema = z
+  .string()
+  .min(1)
+  .regex(/^[a-z0-9-]+$/, 'Invalid slug format')
+  .refine(
+    async (slug) => {
+      // Only hit DB if synchronous checks pass
+      const existing = await db.post.findUnique({ where: { slug } });
+      return !existing;
+    },
+    { message: 'Slug is already in use' }
+  );
+```
+
+6. Parallelize multiple async checks using `Promise.all` inside `superRefine`:
+
+```typescript
+const CreatePostSchema = z
+  .object({
+    slug: z.string().regex(/^[a-z0-9-]+$/),
+    categoryId: z.string().uuid(),
+    authorId: z.string().uuid(),
+  })
+  .superRefine(async (data, ctx) => {
+    const [slugExists, categoryExists, authorExists] = await Promise.all([
+      db.post.findUnique({ where: { slug: data.slug } }),
+      db.category.findUnique({ where: { id: data.categoryId } }),
+      db.user.findUnique({ where: { id: data.authorId } }),
+    ]);
+
+    if (slugExists) {
+      ctx.addIssue({ code: z.ZodIssueCode.custom, message: 'Slug already used', path: ['slug'] });
+    }
+    if (!categoryExists) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: 'Category not found',
+        path: ['categoryId'],
+      });
+    }
+    if (!authorExists) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: 'Author not found',
+        path: ['authorId'],
+      });
+    }
+  });
+```
+
+## Details
+
+**Sync schema with async context:**
+
+A schema without async refinements or transforms can still be used with `.parseAsync()` — it just resolves synchronously:
+
+```typescript
+// This works fine (resolves synchronously under the hood)
+const result = await z.string().email().safeParseAsync(rawEmail);
+```
+
+**Error: "Schema must be used with parseAsync" — when it appears:**
+
+If a schema has an async refinement and you call `.parse()` (not `.parseAsync()`), Zod throws a synchronous error. This is a common mistake when extracting schemas from server-side code.
+
+**Timeout and abort:**
+
+Zod does not have built-in timeout support for async refinements. Wrap your async checks with a timeout utility if needed:
+
+```typescript
+async function withTimeout<T>(promise: Promise<T>, ms: number): Promise<T> {
+  const timeout = new Promise<never>((_, reject) =>
+    setTimeout(() => reject(new Error('Validation timeout')), ms)
+  )
+  return Promise.race([promise, timeout])
+}
+
+// Use inside refine:
+.refine(async (email) => {
+  return withTimeout(checkEmailUniqueness(email), 3000)
+})
+```
+
+**Caching in async refinements:**
+
+Do not cache Zod schema instances that hold open DB connections or closures. Create them in the request scope or use a factory function.
+
+## Source
+
+https://zod.dev/api#parseAsync
+
+## Process
+
+1. Read the instructions and examples in this document.
+2. Apply the patterns to your implementation, adapting to your specific context.
+3. Verify your implementation against the details and edge cases listed above.
+
+## Harness Integration
+
+- **Type:** knowledge — this skill is a reference document, not a procedural workflow.
+- **No tools or state** — consumed as context by other skills and agents.
+
+## Success Criteria
+
+- The patterns described in this document are applied correctly in the implementation.
+- Edge cases and anti-patterns listed in this document are avoided.

package/dist/agents/skills/claude-code/zod-async-validation/skill.yaml

@@ -0,0 +1,40 @@
+name: zod-async-validation
+version: "1.0.0"
+description: Run async Zod validation with parseAsync, safeParseAsync, async refinements, and external checks
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths:
+  - "**/*.schema.ts"
+  - "**/*.schema.tsx"
+  - "**/schemas/**"
+  - "**/validation/**"
+related_skills:
+  - zod-transform-refine
+  - zod-error-handling
+  - zod-nextjs-integration
+stack_signals:
+  - zod
+  - typescript
+keywords:
+  - zod
+  - parseAsync
+  - safeParseAsync
+  - async-refinement
+  - external-validation
+  - database-check
+metadata:
+  author: community
+  upstream: "zod.dev"
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/claude-code/zod-error-handling/SKILL.md

@@ -0,0 +1,206 @@
+# Zod Error Handling
+
+> Handle Zod validation failures with safeParse, ZodError, error.format, error.flatten, and custom error maps
+
+## When to Use
+
+- Returning field-level validation errors to the client (API responses, form feedback)
+- Logging or monitoring validation failures without crashing
+- Providing localized or application-specific error messages
+- Building a validation error response shape consistent across your API
+
+## Instructions
+
+1. Use `.safeParse()` instead of `.parse()` whenever the caller needs to handle errors — it never throws:
+
+```typescript
+import { z } from 'zod';
+
+const UserSchema = z.object({
+  name: z.string().min(1),
+  email: z.string().email(),
+  age: z.number().int().min(0),
+});
+
+const result = UserSchema.safeParse(rawInput);
+
+if (!result.success) {
+  // result.error is a ZodError
+  console.error(result.error.issues);
+  return { errors: result.error.format() };
+}
+
+// result.data is typed
+const user = result.data;
+```
+
+2. Use `error.format()` to produce a nested error object mirroring the schema shape:
+
+```typescript
+const result = UserSchema.safeParse({ name: '', email: 'not-an-email', age: -1 });
+
+if (!result.success) {
+  const formatted = result.error.format();
+  /*
+  {
+    _errors: [],
+    name: { _errors: ['String must contain at least 1 character(s)'] },
+    email: { _errors: ['Invalid email'] },
+    age: { _errors: ['Number must be greater than or equal to 0'] }
+  }
+  */
+}
+```
+
+3. Use `error.flatten()` for a flat error object — simpler to consume in UI frameworks:
+
+```typescript
+const flattened = result.error.flatten();
+/*
+{
+  formErrors: [],           // top-level (non-field) errors
+  fieldErrors: {
+    name: ['String must contain at least 1 character(s)'],
+    email: ['Invalid email'],
+    age: ['Number must be greater than or equal to 0']
+  }
+}
+*/
+
+// Access field errors
+const nameErrors = flattened.fieldErrors.name ?? [];
+```
+
+4. Inspect raw issues for fine-grained error handling:
+
+```typescript
+import { z, ZodIssueCode } from 'zod';
+
+const result = UserSchema.safeParse(rawInput);
+if (!result.success) {
+  for (const issue of result.error.issues) {
+    console.log(issue.path); // ['email']
+    console.log(issue.code); // 'invalid_string'
+    console.log(issue.message); // 'Invalid email'
+  }
+}
+```
+
+5. Use `z.setErrorMap()` to override error messages globally (e.g., for i18n):
+
+```typescript
+import { z, ZodErrorMap, ZodIssueCode } from 'zod';
+
+const customErrorMap: ZodErrorMap = (issue, ctx) => {
+  if (issue.code === ZodIssueCode.invalid_type) {
+    if (issue.expected === 'string') {
+      return { message: 'This field requires a text value' };
+    }
+  }
+  if (issue.code === ZodIssueCode.too_small && issue.type === 'string') {
+    return { message: `Must be at least ${issue.minimum} characters` };
+  }
+  return { message: ctx.defaultError };
+};
+
+z.setErrorMap(customErrorMap);
+```
+
+6. Pass a custom error map per-parse without setting it globally:
+
+```typescript
+const result = UserSchema.safeParse(rawInput, {
+  errorMap: (issue, ctx) => {
+    if (issue.path[0] === 'email') {
+      return { message: 'Please enter a valid email address' };
+    }
+    return { message: ctx.defaultError };
+  },
+});
+```
+
+7. Build a reusable API error response from Zod errors:
+
+```typescript
+function formatValidationError(error: z.ZodError): Record<string, string[]> {
+  return error.flatten().fieldErrors as Record<string, string[]>;
+}
+
+// In a Next.js API route or server action:
+const result = CreateUserSchema.safeParse(await req.json());
+if (!result.success) {
+  return Response.json(
+    { success: false, errors: formatValidationError(result.error) },
+    { status: 400 }
+  );
+}
+```
+
+## Details
+
+**ZodError structure:**
+
+A `ZodError` is an `Error` subclass with an `issues` array. Each issue has:
+
+| Field     | Type                   | Description                                            |
+| --------- | ---------------------- | ------------------------------------------------------ |
+| `code`    | `ZodIssueCode`         | The error category (e.g., `invalid_type`, `too_small`) |
+| `path`    | `(string \| number)[]` | Path to the failing field                              |
+| `message` | `string`               | Human-readable error message                           |
+
+**Checking for specific error types:**
+
+```typescript
+import { ZodError, ZodIssueCode } from 'zod';
+
+function isValidationError(err: unknown): err is ZodError {
+  return err instanceof ZodError;
+}
+
+function hasEmailError(err: ZodError): boolean {
+  return err.issues.some(
+    (issue) => issue.path.includes('email') && issue.code === ZodIssueCode.invalid_string
+  );
+}
+```
+
+**safeParseAsync:**
+
+For schemas with async refinements or transforms, use `safeParseAsync()`:
+
+```typescript
+const result = await UserSchema.safeParseAsync(rawInput);
+```
+
+**Logging without sensitive data:**
+
+Before logging Zod errors, sanitize the input to avoid logging passwords or tokens:
+
+```typescript
+if (!result.success) {
+  logger.warn('Validation failed', {
+    issues: result.error.issues.map((i) => ({ path: i.path, code: i.code, message: i.message })),
+    // Do NOT log the raw input
+  });
+}
+```
+
+## Source
+
+https://zod.dev/error-handling
+
+## Process
+
+1. Read the instructions and examples in this document.
+2. Apply the patterns to your implementation, adapting to your specific context.
+3. Verify your implementation against the details and edge cases listed above.
+
+## Harness Integration
+
+- **Type:** knowledge — this skill is a reference document, not a procedural workflow.
+- **No tools or state** — consumed as context by other skills and agents.
+
+## Success Criteria
+
+- The patterns described in this document are applied correctly in the implementation.
+- Edge cases and anti-patterns listed in this document are avoided.

package/dist/agents/skills/claude-code/zod-error-handling/skill.yaml

@@ -0,0 +1,41 @@
+name: zod-error-handling
+version: "1.0.0"
+description: Handle Zod validation failures with safeParse, ZodError, error.format, error.flatten, and custom error maps
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths:
+  - "**/*.schema.ts"
+  - "**/*.schema.tsx"
+  - "**/schemas/**"
+  - "**/validation/**"
+related_skills:
+  - zod-schema-definition
+  - zod-transform-refine
+  - zod-nextjs-integration
+stack_signals:
+  - zod
+  - typescript
+keywords:
+  - zod
+  - ZodError
+  - safeParse
+  - error.format
+  - error.flatten
+  - errorMap
+  - validation-errors
+metadata:
+  author: community
+  upstream: "zod.dev"
+state:
+  persistent: false
+  files: []
+depends_on: []