@harness-engineering/cli 1.23.2 → 1.24.0

package/dist/agents/skills/claude-code/zod-object-patterns/skill.yaml

@@ -0,0 +1,43 @@
+name: zod-object-patterns
+version: "1.0.0"
+description: Shape and compose Zod objects with pick, omit, partial, required, extend, merge, strict, and passthrough
+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-infer-types
+  - ts-utility-types
+stack_signals:
+  - zod
+  - typescript
+keywords:
+  - zod
+  - object
+  - pick
+  - omit
+  - partial
+  - extend
+  - merge
+  - strict
+  - passthrough
+metadata:
+  author: community
+  upstream: "zod.dev"
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/claude-code/zod-schema-definition/SKILL.md

@@ -0,0 +1,170 @@
+# Zod Schema Definition
+
+> Define runtime-validated TypeScript schemas with z.object, primitives, enums, literals, and schema composition
+
+## When to Use
+
+- You need runtime validation that also produces TypeScript types (no manual interface duplication)
+- You are receiving untrusted data: API responses, form submissions, environment variables, query params
+- You want a single source of truth for both runtime validation and static typing
+- You are starting a new data model and want to define it as a Zod schema first
+
+## Instructions
+
+1. Install Zod: `npm install zod`
+2. Import the `z` namespace: `import { z } from 'zod'`
+3. Define primitive fields — choose the right primitive for each field:
+   - `z.string()`, `z.number()`, `z.boolean()`, `z.date()`, `z.bigint()`, `z.symbol()`
+   - `z.undefined()`, `z.null()`, `z.void()`, `z.any()`, `z.unknown()`, `z.never()`
+4. Use `z.object()` to compose fields into a schema object — each key maps to a Zod type:
+
+```typescript
+import { z } from 'zod';
+
+const UserSchema = z.object({
+  id: z.string().uuid(),
+  name: z.string().min(1),
+  email: z.string().email(),
+  age: z.number().int().positive().optional(),
+  role: z.enum(['admin', 'editor', 'viewer']),
+  createdAt: z.date(),
+});
+```
+
+5. Use `z.enum()` for a fixed set of string literals — prefer over `z.union([z.literal(...)])` for simple cases:
+
+```typescript
+const StatusSchema = z.enum(['active', 'inactive', 'pending']);
+type Status = z.infer<typeof StatusSchema>; // 'active' | 'inactive' | 'pending'
+```
+
+6. Use `z.literal()` for exact value matching:
+
+```typescript
+const TrueSchema = z.literal(true);
+const FortyTwoSchema = z.literal(42);
+const HelloSchema = z.literal('hello');
+```
+
+7. Make fields optional or nullable explicitly:
+
+```typescript
+const ProfileSchema = z.object({
+  bio: z.string().optional(), // string | undefined
+  avatar: z.string().nullable(), // string | null
+  website: z.string().nullish(), // string | null | undefined
+});
+```
+
+8. Compose schemas by nesting them — use schema references, not re-definition:
+
+```typescript
+const AddressSchema = z.object({
+  street: z.string(),
+  city: z.string(),
+  zip: z.string().regex(/^\d{5}$/),
+});
+
+const OrderSchema = z.object({
+  id: z.string().uuid(),
+  shippingAddress: AddressSchema,
+  billingAddress: AddressSchema.optional(),
+});
+```
+
+9. Parse input data — use `.parse()` to throw on failure, `.safeParse()` to handle errors gracefully:
+
+```typescript
+// Throws ZodError if invalid
+const user = UserSchema.parse(rawData);
+
+// Returns { success: true, data } or { success: false, error }
+const result = UserSchema.safeParse(rawData);
+if (result.success) {
+  console.log(result.data); // fully typed
+} else {
+  console.error(result.error.issues);
+}
+```
+
+10. Export both the schema and its inferred type together:
+
+```typescript
+export const UserSchema = z.object({ ... })
+export type User = z.infer<typeof UserSchema>
+```
+
+## Details
+
+Zod schemas are composable objects — they are not just validators, they are type constructors. Every schema carries both a runtime validator and a TypeScript type. The `z.infer<typeof Schema>` pattern eliminates the dual-maintenance problem of keeping an interface and a validator in sync.
+
+**Schema composition strategies:**
+
+- **Flat schemas** — all fields in one `z.object()`. Good for simple models.
+- **Nested schemas** — reference child schemas by variable. Better for shared sub-shapes.
+- **Extended schemas** — use `.extend()` to add fields without re-defining the base. See `zod-object-patterns`.
+
+**Primitive coercion:**
+
+Zod does not coerce by default. `z.number().parse("42")` throws. Use `z.coerce.number()` when input may be a string (e.g., URL query params, form fields):
+
+```typescript
+const PageSchema = z.object({
+  page: z.coerce.number().int().positive().default(1),
+  limit: z.coerce.number().int().min(1).max(100).default(20),
+});
+```
+
+**Default values:**
+
+```typescript
+const ConfigSchema = z.object({
+  timeout: z.number().default(5000),
+  retries: z.number().default(3),
+  debug: z.boolean().default(false),
+});
+```
+
+**Recursive schemas:**
+
+For tree structures, use `z.lazy()`:
+
+```typescript
+type Category = {
+  name: string;
+  subcategories: Category[];
+};
+
+const CategorySchema: z.ZodType<Category> = z.lazy(() =>
+  z.object({
+    name: z.string(),
+    subcategories: z.array(CategorySchema),
+  })
+);
+```
+
+**When NOT to use Zod schema definition directly:**
+
+- For large union types with many variants — prefer `z.discriminatedUnion()` (see `zod-union-discriminated`)
+- For complex string patterns — use dedicated string validators (see `zod-string-validation`)
+- For full object manipulation — use object-level methods (see `zod-object-patterns`)
+
+## Source
+
+https://zod.dev
+
+## 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-schema-definition/skill.yaml

@@ -0,0 +1,42 @@
+name: zod-schema-definition
+version: "1.0.0"
+description: Define runtime-validated TypeScript schemas with z.object, primitives, enums, and composition
+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-string-validation
+  - zod-object-patterns
+  - zod-infer-types
+  - ts-utility-types
+stack_signals:
+  - zod
+  - typescript
+keywords:
+  - zod
+  - schema
+  - validation
+  - z.object
+  - z.enum
+  - z.literal
+  - runtime-types
+metadata:
+  author: community
+  upstream: "zod.dev"
+state:
+  persistent: false
+  files: []
+depends_on: []

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

@@ -0,0 +1,180 @@
+# Zod String Validation
+
+> Validate and transform strings with Zod's min, max, email, url, regex, trim, and custom error messages
+
+## When to Use
+
+- Validating user-facing string inputs: emails, URLs, passwords, usernames, phone numbers
+- Enforcing length constraints on text fields
+- Sanitizing strings by trimming or lowercasing before storing
+- Providing user-friendly error messages instead of Zod's defaults
+
+## Instructions
+
+1. Start with `z.string()` and chain validators in order from most permissive to most restrictive:
+
+```typescript
+import { z } from 'zod';
+
+const UsernameSchema = z
+  .string()
+  .min(3, 'Username must be at least 3 characters')
+  .max(20, 'Username cannot exceed 20 characters')
+  .regex(/^[a-z0-9_]+$/, 'Only lowercase letters, numbers, and underscores');
+```
+
+2. Use built-in format validators for common patterns:
+
+```typescript
+const ContactSchema = z.object({
+  email: z.string().email('Enter a valid email address'),
+  website: z.string().url('Enter a valid URL').optional(),
+  phone: z
+    .string()
+    .regex(/^\+?[1-9]\d{7,14}$/, 'Enter a valid phone number')
+    .optional(),
+});
+```
+
+3. Chain `.trim()` before length checks so whitespace does not count toward limits:
+
+```typescript
+const TitleSchema = z
+  .string()
+  .trim()
+  .min(1, 'Title is required')
+  .max(100, 'Title cannot exceed 100 characters');
+```
+
+4. Use `.toLowerCase()` and `.toUpperCase()` for normalization (these are transforms):
+
+```typescript
+const EmailSchema = z.string().trim().toLowerCase().email('Enter a valid email address');
+```
+
+5. Use `.transform()` for custom string shaping — the output type can differ from string:
+
+```typescript
+const SlugSchema = z
+  .string()
+  .trim()
+  .toLowerCase()
+  .transform((val) => val.replace(/\s+/g, '-').replace(/[^a-z0-9-]/g, ''));
+
+// SlugSchema.parse('  Hello World! ') → 'hello-world'
+```
+
+6. Use `.startsWith()` and `.endsWith()` for prefix/suffix constraints:
+
+```typescript
+const ApiKeySchema = z
+  .string()
+  .startsWith('sk_', 'API keys must start with sk_')
+  .length(32, 'API key must be exactly 32 characters');
+```
+
+7. Use `.includes()` for substring requirements:
+
+```typescript
+const PasswordSchema = z
+  .string()
+  .min(8, 'Password must be at least 8 characters')
+  .includes('@', { message: 'Password must contain @' }); // rarely used, prefer regex
+```
+
+8. Use `.ip()` for IP address validation (v4, v6, or both):
+
+```typescript
+const IpSchema = z.string().ip({ version: 'v4', message: 'Must be a valid IPv4 address' });
+const AnyIpSchema = z.string().ip(); // accepts v4 and v6
+```
+
+9. Use `.datetime()` for ISO 8601 datetime strings:
+
+```typescript
+const TimestampSchema = z.string().datetime({ message: 'Must be ISO 8601 format' });
+// Accepts: '2024-01-15T10:30:00Z', '2024-01-15T10:30:00.000Z'
+```
+
+10. Use `.uuid()` and `.cuid()` for ID format validation:
+
+```typescript
+const IdSchema = z.union([z.string().uuid(), z.string().cuid()]);
+```
+
+## Details
+
+**Custom error messages:**
+
+Every Zod string method accepts either a string message or an options object:
+
+```typescript
+// Short form
+z.string().min(8, 'Too short');
+
+// Long form — useful when you need to customize the error code or path
+z.string().min(8, { message: 'Password must be at least 8 characters', path: ['password'] });
+```
+
+**Order matters for transforms:**
+
+`.trim()`, `.toLowerCase()`, and `.toUpperCase()` are transforms under the hood. They run in order during parsing. Always put them before validation checks:
+
+```typescript
+// Correct: trim before min check
+z.string().trim().min(1, 'Required');
+
+// Wrong: min check runs on untrimmed string, '   ' passes
+z.string().min(1).trim();
+```
+
+**Distinguishing empty vs absent:**
+
+```typescript
+// Required, non-empty string
+const Required = z.string().min(1, 'This field is required');
+
+// Optional but non-empty when present
+const OptionalNonEmpty = z.string().min(1).optional();
+
+// Empty string treated as absent (common for HTML forms)
+const FormField = z
+  .string()
+  .transform((val) => (val === '' ? undefined : val))
+  .optional();
+```
+
+**Regex complexity:**
+
+For complex patterns, extract the regex to a named constant for testability:
+
+```typescript
+const SLUG_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+
+const SlugSchema = z.string().regex(SLUG_PATTERN, 'Invalid slug format');
+```
+
+**When NOT to use string validators directly:**
+
+- For object-level string fields with cross-field dependencies — use `.superRefine()` on the parent object (see `zod-transform-refine`)
+- For async uniqueness checks (e.g., email already taken) — use async refinements (see `zod-async-validation`)
+
+## Source
+
+https://zod.dev/api#strings
+
+## 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-string-validation/skill.yaml

@@ -0,0 +1,43 @@
+name: zod-string-validation
+version: "1.0.0"
+description: Validate and transform strings with Zod's min, max, email, url, regex, trim, and custom messages
+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-error-handling
+stack_signals:
+  - zod
+  - typescript
+keywords:
+  - zod
+  - string
+  - email
+  - url
+  - regex
+  - min
+  - max
+  - trim
+  - transform
+metadata:
+  author: community
+  upstream: "zod.dev"
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/claude-code/zod-transform-refine/SKILL.md

@@ -0,0 +1,193 @@
+# Zod Transform and Refine
+
+> Transform and validate data with Zod's transform, refine, superRefine, and preprocess APIs
+
+## When to Use
+
+- Converting parsed data to a different shape or type after validation (e.g., string to Date, string to number)
+- Adding custom validation logic beyond what built-in validators support
+- Implementing cross-field validation within a single schema
+- Pre-processing raw input before Zod's normal validation runs (e.g., JSON.parse, trimming)
+
+## Instructions
+
+1. Use `.transform()` to reshape or convert validated data — the output type can differ from the input type:
+
+```typescript
+import { z } from 'zod';
+
+// String to number
+const NumericStringSchema = z.string().transform((val) => parseInt(val, 10));
+// Input type: string, Output type: number
+
+// String to Date
+const DateStringSchema = z
+  .string()
+  .datetime()
+  .transform((val) => new Date(val));
+// Input type: string, Output type: Date
+
+// Object reshaping
+const RawUserSchema = z
+  .object({
+    first_name: z.string(),
+    last_name: z.string(),
+    email_address: z.string().email(),
+  })
+  .transform(({ first_name, last_name, email_address }) => ({
+    displayName: `${first_name} ${last_name}`,
+    email: email_address,
+  }));
+```
+
+2. Use `.refine()` for single-failure custom validation — the predicate returns true to pass, false to fail:
+
+```typescript
+const PasswordSchema = z
+  .object({
+    password: z.string().min(8),
+    confirm: z.string(),
+  })
+  .refine((data) => data.password === data.confirm, {
+    message: 'Passwords do not match',
+    path: ['confirm'], // which field the error should appear on
+  });
+```
+
+3. Use `.superRefine()` for multi-failure validation — you control exactly how many issues to add:
+
+```typescript
+const RegisterSchema = z
+  .object({
+    username: z.string(),
+    password: z.string(),
+    age: z.number(),
+  })
+  .superRefine((data, ctx) => {
+    if (data.password.length < 8) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.too_small,
+        minimum: 8,
+        type: 'string',
+        inclusive: true,
+        message: 'Password must be at least 8 characters',
+        path: ['password'],
+      });
+    }
+
+    if (data.age < 18) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: 'Must be 18 or older to register',
+        path: ['age'],
+      });
+    }
+  });
+```
+
+4. Use `z.preprocess()` to transform raw input before validation — useful for coercing from non-standard sources:
+
+```typescript
+// Parse JSON string before validating the object
+const JsonBodySchema = z.preprocess(
+  (val) => (typeof val === 'string' ? JSON.parse(val) : val),
+  z.object({ name: z.string(), count: z.number() })
+);
+
+// Convert empty string to undefined (common for HTML form inputs)
+const OptionalStringSchema = z.preprocess(
+  (val) => (val === '' ? undefined : val),
+  z.string().optional()
+);
+
+// Coerce comma-separated string to array
+const CsvArraySchema = z.preprocess(
+  (val) => (typeof val === 'string' ? val.split(',').map((s) => s.trim()) : val),
+  z.array(z.string())
+);
+```
+
+5. Chain transforms and refinements together with `.pipe()`:
+
+```typescript
+const AgeFromStringSchema = z.string().transform(Number).pipe(z.number().int().min(0).max(150));
+// First converts to number, then validates the number
+```
+
+6. Use `.transform()` with async operations — but then you must use `.parseAsync()`:
+
+```typescript
+const SlugCheckSchema = z.string().transform(async (slug) => {
+  const exists = await db.post.findUnique({ where: { slug } });
+  return { slug, exists: !!exists };
+});
+
+const result = await SlugCheckSchema.parseAsync('my-post');
+// { slug: 'my-post', exists: true }
+```
+
+## Details
+
+**Input vs output types:**
+
+When you use `.transform()`, the schema has different input and output types. `z.infer` gives the output type. To get the input type, use `z.input<typeof Schema>`:
+
+```typescript
+const ProcessedSchema = z
+  .object({
+    date: z.string().datetime(),
+  })
+  .transform(({ date }) => ({ date: new Date(date), year: new Date(date).getFullYear() }));
+
+type Input = z.input<typeof ProcessedSchema>; // { date: string }
+type Output = z.infer<typeof ProcessedSchema>; // { date: Date; year: number }
+```
+
+**Refine vs superRefine — when to choose:**
+
+| Scenario                           | Use                                                 |
+| ---------------------------------- | --------------------------------------------------- |
+| Single conditional check           | `.refine()`                                         |
+| Multiple independent checks        | `.superRefine()`                                    |
+| Type narrowing (e.g., `data is X`) | `.superRefine()` with `ctx.addIssue` + return NEVER |
+| Async validation                   | `.refine(async fn)` or `.superRefine(async fn)`     |
+
+**Accessing sibling fields in refinement:**
+
+`.refine()` on an object gives access to all fields — useful for cross-field constraints:
+
+```typescript
+const DateRangeSchema = z
+  .object({
+    startDate: z.date(),
+    endDate: z.date(),
+  })
+  .refine((data) => data.endDate > data.startDate, {
+    message: 'End date must be after start date',
+    path: ['endDate'],
+  });
+```
+
+**Preprocess vs coerce:**
+
+`z.preprocess()` runs before Zod's type check. `z.coerce` is a Zod-managed conversion. Prefer `z.coerce` for numeric/boolean coercion from strings; use `z.preprocess()` for anything more complex.
+
+## Source
+
+https://zod.dev/api#transform
+
+## 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.