@xonovex/skills 0.1.0

package/skills/vitest-guidelines/reference/http-testing.md

@@ -0,0 +1,57 @@
+# http-testing: HTTP Testing Patterns
+
+**Guideline:** Use correct HTTP status codes in test assertions (204 for OPTIONS/DELETE, 201 for creation, 200 for GET).
+
+**Rationale:** Correct status codes ensure tests align with HTTP standards and detect real failures.
+
+**Example:**
+
+```typescript
+// CORS Preflight
+it("should handle CORS preflight", async () => {
+  const res = await app.request("/api/users", {
+    method: "OPTIONS",
+    headers: {
+      Origin: "https://example.com",
+      "Access-Control-Request-Method": "POST",
+    },
+  });
+
+  expect(res.status).toBe(204); // ✅ Correct for OPTIONS
+  expect(res.headers.get("Access-Control-Allow-Origin")).toBeDefined();
+});
+
+// Status Code Assertions
+it("should create resource", async () => {
+  const res = await app.request("/api/users", {method: "POST", body: data});
+  expect(res.status).toBe(201); // ✅ Created
+});
+
+it("should get resource", async () => {
+  const res = await app.request("/api/users/123");
+  expect(res.status).toBe(200); // ✅ OK with body
+});
+
+it("should delete resource", async () => {
+  const res = await app.request("/api/users/123", {method: "DELETE"});
+  expect(res.status).toBe(204); // ✅ No Content
+});
+
+it("should validate input", async () => {
+  const res = await app.request("/api/users", {method: "POST", body: invalid});
+  expect(res.status).toBe(400); // ✅ Bad Request
+});
+
+it("should handle missing resource", async () => {
+  const res = await app.request("/api/users/999");
+  expect(res.status).toBe(404); // ✅ Not Found
+});
+```
+
+**Techniques:**
+- Use 204 for OPTIONS preflight requests (CORS)
+- Use 204 for successful DELETE operations without response body
+- Use 201 for resource creation (POST that creates new resource)
+- Use 200 for successful operations with response body
+- Use 400 for validation failures and bad requests
+- Use 404 for missing resources

package/skills/vitest-guidelines/reference/json-response-type-safety.md

@@ -0,0 +1,40 @@
+# json-response-type-safety: JSON Response Type Safety in Tests
+
+**Guideline:** Define response interfaces and cast JSON results to maintain type safety in tests.
+
+**Rationale:** Type casting prevents unsafe assignment errors and enables IDE autocomplete and refactoring.
+
+**Example:**
+
+```typescript
+// Define interfaces at file top
+interface User {
+  id: string;
+  email: string;
+}
+
+interface ErrorResponse {
+  title: string;
+  status: number;
+}
+
+// Use in tests
+it("should return user", async () => {
+  const res = await app.request("/api/users/123");
+  const json = (await res.json()) as User;
+  expect(json.id).toBe("123"); // ✅ Type-safe
+});
+
+it("should return error", async () => {
+  const res = await app.request("/api/users/invalid");
+  const json = (await res.json()) as ErrorResponse;
+  expect(json.status).toBe(404); // ✅ Type-safe
+});
+```
+
+**Techniques:**
+- Create test-specific interfaces at the top of test files
+- Use type assertion: `const json = (await res.json()) as ExpectedType`
+- Reuse interfaces across multiple tests
+- Match interface properties to actual API response shape
+- Cast before property access to avoid unsafe-assignment ESLint errors

package/skills/vitest-guidelines/reference/mock-patterns.md

@@ -0,0 +1,53 @@
+# mock-patterns: Simple Type Casting for Vitest Mocks
+
+**Guideline:** Use simple type casting for Vitest mocks instead of complex generic typing.
+
+**Rationale:** Simple casting is more maintainable and readable than complex generic typing.
+
+**Example:**
+
+```typescript
+import {expect, it, vi} from "vitest";
+
+interface User {
+  id: string;
+  email: string;
+}
+
+// ✅ Simple - easy to read and maintain
+it("should call user service", async () => {
+  const mockUser: User = {id: "123", email: "test@example.com"};
+  const getUserFn = vi.fn();
+  getUserFn.mockResolvedValue(mockUser);
+
+  const result = await getUserFn("123");
+  expect(result).toEqual(mockUser);
+  expect(getUserFn).toHaveBeenCalledWith("123");
+});
+
+// ✅ Good - type cast when needed
+it("should handle error", async () => {
+  const getUserFn = vi.fn();
+  (getUserFn as ReturnType<typeof vi.fn>).mockRejectedValue(
+    new Error("Not found"),
+  );
+
+  await expect(getUserFn("999")).rejects.toThrow("Not found");
+});
+
+// ✅ Good - simple sync mock
+it("should transform data", () => {
+  const transformFn = vi.fn();
+  transformFn.mockReturnValue({transformed: true});
+
+  const result = transformFn({input: "data"});
+  expect(result.transformed).toBe(true);
+});
+```
+
+**Techniques:**
+- Create mocks with `vi.fn()` without complex generics
+- Use type casting when setting return values
+- Let TypeScript infer types from usage
+- Only add types when necessary for test assertions
+- Prefer simple casting over advanced mock type patterns

package/skills/vitest-guidelines/reference/project-references-path-resolution.md

@@ -0,0 +1,36 @@
+# project-references-path-resolution: Path Resolution in TypeScript Project References
+
+**Guideline:** Verify directory structure before configuring project references; calculate relative paths carefully from current package to target.
+
+**Rationale:** Incorrect paths cause "File not found" errors and build failures in CI/CD pipelines.
+
+**Example:**
+
+```bash
+# Verify structure
+$ ls packages/
+templates/ shared/ apps/
+
+# Calculate path: packages/templates/my-template → packages/shared/shared-core
+# Up 2 levels (..), down through shared/, then shared-core/
+```
+
+```json
+// Correct reference
+{"references": [{"path": "../../shared/shared-core"}]}
+
+// Wrong - goes up 3 levels
+// {"path": "../../../shared/shared-core"}  ❌
+
+// Wrong - missing "shared" directory
+// {"path": "../../shared-core"}  ❌
+```
+
+**Techniques:**
+- ls verification: Use `ls` to check actual directory structure before configuring
+- Relative paths: Calculate from current package up (..) then down to target
+- tsc --build: Test with TypeScript build to verify paths resolve
+- Error messages: Read build errors to identify which paths failed
+- Monorepo structure: Understand packages/, apps/, shared/ hierarchy
+- Counting levels: Each up (..) represents one directory level
+- Off-by-one errors: Most common mistake - verify counting twice

package/skills/vitest-guidelines/reference/test-organization.md

@@ -0,0 +1,25 @@
+# test-organization: Test Directory Structure and Suite Organization
+
+**Guideline:** Organize tests by endpoint/feature with nested describe blocks and clear directory structure.
+
+**Rationale:** Well-organized tests are easy to navigate, maintain, and update.
+
+**Example:**
+
+```
+test/
+├── app.test.ts           # Application-level tests
+├── health.test.ts        # Health check endpoints
+└── api/
+    ├── users.test.ts     # User CRUD operations
+    └── auth.test.ts      # Authentication flows
+```
+
+**Techniques:**
+- Create `test/` directory at package root
+- Mirror API structure in test files (e.g., `test/api/users.test.ts`)
+- Use nested `describe` blocks for endpoint grouping
+- Name test files after features: `{feature}.test.ts`
+- Group related tests in inner `describe` blocks
+- Use descriptive `it` statements that explain expected behavior
+- Test both success and error cases for each endpoint

package/skills/vitest-guidelines/reference/timestamp-testing.md

@@ -0,0 +1,55 @@
+# timestamp-testing: Avoiding Flaky Timestamp Comparisons
+
+**Guideline:** Don't compare timestamps from rapid operations; they may complete in the same millisecond.
+
+**Rationale:** Fast operations can complete within milliseconds, making timestamp comparisons flaky and unreliable.
+
+**Example:**
+
+```typescript
+// ✅ Preferred - verify existence and type
+it("should update timestamp", async () => {
+  const created = await createUser();
+  const updated = await updateUser(created.id);
+
+  expect(updated.updatedAt).toBeDefined();
+  expect(typeof updated.updatedAt).toBe("string");
+  expect(new Date(updated.updatedAt)).toBeInstanceOf(Date);
+});
+
+// ✅ Alternative - add explicit delay
+it("should update timestamp with delay", async () => {
+  const created = await createUser();
+  await new Promise((resolve) => setTimeout(resolve, 10)); // 10ms delay
+  const updated = await updateUser(created.id);
+
+  expect(updated.updatedAt).not.toBe(created.updatedAt);
+});
+
+// ✅ Good - verify timestamp is after a known point
+it("should have recent timestamp", async () => {
+  const before = new Date().toISOString();
+  const created = await createUser();
+
+  expect(created.createdAt >= before).toBe(true);
+});
+
+// ✅ Good - verify timestamp changed (with reasonable buffer)
+it("should update timestamp", async () => {
+  const created = await createUser();
+  const createdTime = new Date(created.createdAt).getTime();
+
+  await new Promise((resolve) => setTimeout(resolve, 50));
+  const updated = await updateUser(created.id);
+  const updatedTime = new Date(updated.updatedAt).getTime();
+
+  expect(updatedTime).toBeGreaterThan(createdTime);
+});
+```
+
+**Techniques:**
+- Verify timestamp exists and is correct type (preferred approach)
+- Add explicit delay (10-50ms) before second operation if comparison needed
+- Use timestamp ranges (before/after) instead of exact equality
+- Verify timestamp format/structure instead of comparing values
+- Mock time if deterministic testing is required

package/skills/vitest-guidelines/reference/type-safety.md

@@ -0,0 +1,55 @@
+# type-safety: Type Safety in Tests
+
+**Guideline:** Always define interfaces for response shapes and cast JSON parsing results to maintain type safety.
+
+**Rationale:** Type assertions enable IDE autocomplete and prevent unsafe assignment errors.
+
+**Example:**
+
+```typescript
+import {describe, expect, it} from "vitest";
+
+// Define reusable interfaces at the top
+interface User {
+  id: string;
+  email: string;
+  name: string;
+  createdAt: string;
+}
+
+interface ErrorResponse {
+  title: string;
+  status: number;
+  issues?: {path: string[]; message: string}[];
+}
+
+describe("Users API", () => {
+  it("should create user", async () => {
+    const res = await app.request("/api/users", {
+      method: "POST",
+      body: JSON.stringify({email: "test@example.com"}),
+    });
+
+    const json = (await res.json()) as User;
+    expect(json.email).toBe("test@example.com"); // Type-safe!
+  });
+
+  it("should validate email", async () => {
+    const res = await app.request("/api/users", {
+      method: "POST",
+      body: JSON.stringify({email: "invalid"}),
+    });
+
+    const json = (await res.json()) as ErrorResponse;
+    expect(json.status).toBe(400);
+    expect(json.issues).toBeDefined(); // Type-safe!
+  });
+});
+```
+
+**Techniques:**
+- Define interfaces for expected response shapes at the top of test files
+- Cast all JSON parsing results: `const json = (await res.json()) as ResponseType`
+- Create reusable interfaces for common response types (User, ErrorResponse, etc.)
+- Use the same interfaces across multiple tests in the same file
+- Match interface properties to actual API response shapes

package/skills/vitest-guidelines/reference/typescript-config.md

@@ -0,0 +1,43 @@
+# typescript-config: TypeScript Project Configuration for Tests
+
+**Guideline:** Verify directory structure before configuring TypeScript project references and test inclusion in tsconfig.json.
+
+**Rationale:** Incorrect configuration causes compilation failures and broken builds in CI/CD.
+
+**Example:**
+
+```json
+// For packages/templates/X referencing packages/shared/Y
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "dist"
+  },
+  "references": [
+    {
+      "path": "../../shared/shared-core" // ✅ Correct - verified with ls
+    },
+    {
+      "path": "../../shared/shared-types"
+    }
+  ],
+  "include": [
+    "src", // ✅ Source files
+    "test", // ✅ Test files
+    "vitest.config.ts" // ✅ Vitest config
+  ],
+  "exclude": [
+    "dist", // ✅ Build output
+    "node_modules" // ✅ Dependencies
+  ]
+}
+```
+
+**Techniques:**
+- Check actual directory structure with `ls` or file explorer before configuring
+- Calculate relative paths from current package to referenced packages
+- Add project references with correct relative paths
+- Include test directories in `include` array (e.g., "test")
+- Exclude build artifacts and node_modules from compilation
+- Test compilation with `tsc --build` to verify paths resolve

package/skills/zod-guidelines/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: zod-guidelines
+description: >-
+  Trigger on `.ts` files with Zod imports or validation patterns. Use when working with Zod 4.0+ for runtime validation. Apply for API validation, schema composition, type inference, default values. Keywords: Zod, z.uuid(), z.email(), z.iso.datetime(), schema composition, safeParse, z.infer, defaults, validation patterns.
+---
+
+# Zod Coding Guidelines
+
+## Requirements
+
+- Zod ≥ 4.0
+
+## Essentials
+
+- **Use v4 validators** - `z.uuid()`, `z.email()`, `z.iso.datetime()` (not `z.string().uuid()`)
+- **Name schemas PascalCase** - Derive with `.omit()`, `.extend()`, `.pick()`, `.merge()`, see [reference/schema-organization.md](reference/schema-organization.md)
+- **Validate at boundaries** - Use `.safeParse()` for I/O, `.pipe()` for transforms, see [reference/validation-patterns.md](reference/validation-patterns.md)
+- **Infer types from schemas** - `z.infer<typeof Schema>` for TypeScript types, see [reference/validation-patterns.md](reference/validation-patterns.md)
+- **Module-level schemas** - Define for reuse, keep close to usage, see [reference/schema-organization.md](reference/schema-organization.md)
+- **Match default output types** - Defaults must align with transformations, see [reference/default-values-output-type.md](reference/default-values-output-type.md)
+
+## Progressive Disclosure
+
+### Guidelines
+
+- Read [reference/schema-organization.md](reference/schema-organization.md) - When organizing schemas across modules or files
+- Read [reference/validation-patterns.md](reference/validation-patterns.md) - When choosing between safeParse, parse, or pipe
+- Read [reference/default-values-output-type.md](reference/default-values-output-type.md) - When default values cause type mismatches
+
+### Migration from Zod v3
+
+- Read [reference/migration-v4.md](reference/migration-v4.md) - When migrating from Zod v3 or using deprecated validators
+- Read [reference/migration-string-validators.md](reference/migration-string-validators.md) - When replacing z.string().uuid() patterns

package/skills/zod-guidelines/reference/default-values-output-type.md

@@ -0,0 +1,63 @@
+# default-values-output-type: Default Values Must Match Output Type
+
+**Guideline:** When using `.transform()` or `.pipe()`, ensure `.default()` matches the final output type, not the input type.
+
+**Rationale:** Zod v4 requires defaults to match the transformed output type; mismatched types cause TypeScript errors and prevent proper type narrowing.
+
+**Example:**
+
+```typescript
+// ✅ Correct - default matches output type (number)
+const PaginationSchema = z.object({
+  page: z
+    .string()
+    .regex(/^\d+$/)
+    .transform(Number)
+    .pipe(z.number().int().min(1))
+    .default(1), // Number, matches output type
+
+  limit: z
+    .string()
+    .regex(/^\d+$/)
+    .transform(Number)
+    .pipe(z.number().int().min(1).max(100))
+    .default(10), // Number, matches output type
+});
+
+type Pagination = z.infer<typeof PaginationSchema>;
+// Result: {page: number, limit: number}
+
+// ✅ Boolean transformation
+const ConfigSchema = z.object({
+  debug: z
+    .string()
+    .transform((val) => val === "true")
+    .pipe(z.boolean())
+    .default(false), // Boolean, matches output type
+
+  verbose: z
+    .string()
+    .transform((val) => val === "1")
+    .pipe(z.boolean())
+    .default(true), // Boolean, matches output type
+});
+
+// ✅ Complex transformation
+const PortSchema = z
+  .string()
+  .transform(Number)
+  .pipe(z.number().int().min(1024).max(65535))
+  .default(3000); // Number, matches output type
+
+type Port = z.infer<typeof PortSchema>;
+// Result: number
+```
+
+**Techniques:**
+- Match defaults to final output type, not input type
+- With `.transform(Number)`, use `.default(1)` not `.default("1")`
+- With `.transform(Boolean)`, use `.default(true)` not `.default("true")`
+- Check TypeScript compilation errors for type mismatches
+- Determine output type by tracing through transformation chain
+- Use `z.infer<typeof Schema>` to verify final types
+- Test with `safeParse()` to catch runtime type issues

package/skills/zod-guidelines/reference/migration-string-validators.md

@@ -0,0 +1,38 @@
+# string-validation-method-changes: String Validation Method Changes
+
+**Guideline:** Use standalone validators `z.uuid()` and `z.iso.datetime()` instead of deprecated string refinements `z.string().uuid()` and `z.string().datetime()`.
+
+**Rationale:** Zod v4 deprecated string refinements; standalone methods are more efficient and prevent ESLint deprecation warnings.
+
+**Example:**
+
+```typescript
+// ✅ Correct - Zod v4 standalone validators
+const EventSchema = z.object({
+  id: z.uuid(), // Standalone UUID validator
+  eventId: z.uuid(), // Use for any UUID field
+  scheduledAt: z.iso.datetime(), // Standalone datetime validator
+  createdAt: z.iso.datetime(), // Use for any ISO datetime
+  updatedAt: z.iso.datetime(),
+});
+
+// Infer type
+type Event = z.infer<typeof EventSchema>;
+// Result: {id: string, eventId: string, scheduledAt: string, ...}
+
+// Validation
+const result = EventSchema.safeParse(data);
+if (result.success) {
+  console.log(result.data.id); // Type-safe access
+}
+```
+
+**Techniques:**
+- Replace `z.string().uuid()` with `z.uuid()`
+- Replace `z.string().email()` with `z.email()`
+- Replace `z.string().url()` with `z.url()`
+- Replace `z.string().datetime()` with `z.iso.datetime()`
+- Replace `z.string().date()` with `z.iso.date()`
+- Replace `z.string().time()` with `z.iso.time()`
+- Run linter to verify no deprecation warnings
+- Test validation to ensure behavior unchanged

package/skills/zod-guidelines/reference/migration-v4.md

@@ -0,0 +1,46 @@
+# v4-migration: Zod v4 Migration Guide
+
+**Guideline:** Use Zod v4 standalone validators like `z.uuid()`, `z.email()`, and `z.iso.datetime()` instead of deprecated v3 string refinement methods.
+
+**Rationale:** Zod v4 changed from string refinements to standalone validators that are more efficient, type-safe, and avoid ESLint deprecation warnings.
+
+**Example:**
+
+```typescript
+// ✅ Correct (v4) - standalone validators
+const UserSchema = z.object({
+  id: z.uuid(), // Not z.string().uuid()
+  email: z.email(), // Not z.string().email()
+  website: z.url(), // Not z.string().url()
+  createdAt: z.iso.datetime(), // Not z.string().datetime()
+  birthDate: z.iso.date(), // Not z.string().date()
+  checkInTime: z.iso.time(), // Not z.string().time()
+});
+
+// Enum usage (unchanged)
+enum Status {
+  Active = "active",
+  Inactive = "inactive",
+}
+const StatusSchema = z.enum(Status);
+
+// String literal unions (unchanged)
+const RoleSchema = z.enum(["admin", "user", "guest"]);
+
+// Default values with transformations
+const ConfigSchema = z.object({
+  port: z.string().transform(Number).pipe(z.number()).default(3000), // ✅ Default matches output type (number)
+
+  timeout: z.string().transform(Number).pipe(z.number()).default(5000), // ✅ Not .default("5000")
+});
+```
+
+**Techniques:**
+- Replace `z.string().uuid()` with `z.uuid()`
+- Replace `z.string().email()` with `z.email()`
+- Replace `z.string().url()` with `z.url()`
+- Replace `z.string().datetime()` with `z.iso.datetime()`
+- Replace `z.string().date()` with `z.iso.date()`
+- Replace `z.string().time()` with `z.iso.time()`
+- Update defaults to match output types with transformations
+- Run linter to verify no deprecation warnings

package/skills/zod-guidelines/reference/schema-organization.md

@@ -0,0 +1,73 @@
+# schema-organization: Schema Organization Patterns
+
+**Guideline:** Name schemas with PascalCase suffix, compose with `.merge()`, `.pick()`, `.partial()`, and always infer types using `z.infer<typeof Schema>`.
+
+**Rationale:** Schema-first design provides single source of truth for types and validation, enabling reusable composition and reducing duplication.
+
+**Example:**
+
+```typescript
+// ✅ Base schema with common fields
+const BaseEntitySchema = z.object({
+  id: z.uuid(),
+  createdAt: z.iso.datetime(),
+  updatedAt: z.iso.datetime(),
+});
+
+// ✅ Extend with .merge()
+export const UserSchema = BaseEntitySchema.merge(
+  z.object({
+    email: z.email(),
+    name: z.string().min(1).max(100),
+    role: z.enum(["admin", "user", "guest"]),
+  }),
+);
+
+// ✅ Infer type from schema
+export type User = z.infer<typeof UserSchema>;
+
+// ✅ Create input schemas with .pick()
+export const CreateUserSchema = UserSchema.pick({
+  email: true,
+  name: true,
+  role: true,
+});
+
+export type CreateUser = z.infer<typeof CreateUserSchema>;
+
+// ✅ Make fields optional with .partial()
+export const UpdateUserSchema = UserSchema.pick({
+  email: true,
+  name: true,
+  role: true,
+}).partial();
+
+export type UpdateUser = z.infer<typeof UpdateUserSchema>;
+
+// ✅ Simplified view with .pick()
+export const UserSummarySchema = UserSchema.pick({
+  id: true,
+  email: true,
+  name: true,
+});
+
+export type UserSummary = z.infer<typeof UserSummarySchema>;
+
+// Usage in API
+async function createUser(input: unknown): Promise<User> {
+  const data = CreateUserSchema.parse(input);
+  // data is type-safe: CreateUser
+  const user = await db.users.create(data);
+  return UserSchema.parse(user);
+}
+```
+
+**Techniques:**
+- Name all schemas with PascalCase + "Schema" suffix
+- Define schemas at module level for reuse
+- Always infer types: `type User = z.infer<typeof UserSchema>`
+- Use `.merge()` to combine schemas
+- Use `.pick()` to select specific fields
+- Use `.partial()` to make fields optional
+- Create base schemas for common patterns
+- Keep schemas close to their usage

package/skills/zod-guidelines/reference/validation-patterns.md

@@ -0,0 +1,37 @@
+# validation-patterns: Validation Patterns
+
+**Guideline:** Use `.safeParse()` for external input; `.parse()` for controlled data; `.pipe()` for type-safe transformations.
+
+**Rationale:** Runtime type safety ensures external input never crashes your application.
+
+**Example:**
+
+```typescript
+// API input with safeParse
+const result = CreateUserSchema.safeParse(req.body);
+if (!result.success) {
+  return res.status(400).json({error: result.error.issues});
+}
+const user = await createUser(result.data);
+
+// Query transformation with pipe
+const PaginationSchema = z.object({
+  page: z.string().regex(/^\d+$/).transform(Number)
+    .pipe(z.number().int().min(1)).default(1),
+  limit: z.string().regex(/^\d+$/).transform(Number)
+    .pipe(z.number().int().min(1).max(100)).default(10),
+});
+
+// Controlled data (safe to use parse)
+const validated = InternalSchema.parse(data);
+```
+
+**Techniques:**
+- `.safeParse()`: Use for external input (API, user, services); never throws
+- `.parse()`: Use only for controlled data; throws on validation failure
+- Check `result.success`: Always verify before accessing `result.data`
+- `.transform()`: Apply type conversion before pipe validation
+- `.pipe()`: Chain type-safe transformations for multi-step validation
+- `.default()`: Provide fallback values for optional fields
+- Error handling: Always `.safeParse()` untrusted input, never `.parse()`
+- Error context: Preserve error details in API responses