@xonovex/skills 0.1.0

package/skills/typescript-to-lua-guidelines/reference/function-patterns.md

@@ -0,0 +1,59 @@
+# function-patterns: Function and Module Patterns
+
+**Guideline:** Use pure functions, module-level constants, and type-safe enums for efficient Lua.
+
+**Rationale:** Pure functions compile to simple Lua without closures. Constants generate efficient tables. Patterns align with Lua's procedural nature.
+
+**Example:**
+```typescript
+// Pure functions in namespace
+namespace Math {
+  export function add(a: number, b: number): number { return a + b }
+  export function multiply(a: number, b: number): number { return a * b }
+}
+
+// Module-level constants
+namespace Colors {
+  export const RED = 0xFF0000
+  export const GREEN = 0x00FF00
+  export const BLUE = 0x0000FF
+}
+
+// Numeric enums (efficient)
+enum Direction {
+  Up = 0,
+  Down = 1,
+  Left = 2,
+  Right = 3
+}
+
+// Enum utilities
+namespace DirectionUtils {
+  export function opposite(dir: Direction): Direction {
+    if (dir === Direction.Up) return Direction.Down
+    if (dir === Direction.Down) return Direction.Up
+    if (dir === Direction.Left) return Direction.Right
+    return Direction.Left
+  }
+}
+
+// Generic functions
+namespace Array {
+  export function map<T, U>(arr: T[], fn: (t: T) => U): U[] {
+    const result: U[] = []
+    for (let i = 0; i < arr.length; i++) {
+      result[i] = fn(arr[i])
+    }
+    return result
+  }
+}
+```
+
+**Techniques:**
+- Export pure functions in namespaces to organize code without closures
+- Define module-level constants in dedicated namespaces for reusability
+- Use numeric enums for efficient representation that compiles to simple numbers
+- Create utility namespaces with static functions for enum operations
+- Keep functions stateless to enable inline compilation
+- Use type parameters for generic functions to maintain type safety
+- Group related utilities in single namespaces to generate efficient tables

package/skills/typescript-to-lua-guidelines/reference/lua-interop.md

@@ -0,0 +1,49 @@
+# lua-interop: Integration with Lua APIs
+
+**Guideline:** Declare Lua globals with TypeScript types for type-safe integration.
+
+**Rationale:** Lua environments provide global APIs (LÖVE, Corona, custom engines). TypeScript declarations enable autocomplete, type checking, and full interop.
+
+**Example:**
+```typescript
+// LÖVE 2D game engine declarations
+declare const love: {
+  graphics: {
+    draw: (drawable: Drawable, x: number, y: number) => void
+    print: (text: string, x: number, y: number) => void
+    setColor: (r: number, g: number, b: number, a?: number) => void
+  }
+  window: {
+    setWidth: (width: number) => void
+    setHeight: (height: number) => void
+    getWidth: () => number
+    getHeight: () => number
+  }
+  timer: {
+    getDelta: () => number
+    getTime: () => number
+  }
+}
+
+// Custom engine example
+declare const engine: {
+  render: (meshId: number, transform: Matrix4) => void
+  physics: {
+    raycast: (origin: Vector3, direction: Vector3) => HitResult | null
+  }
+}
+
+// Type-safe usage
+love.graphics.setColor(1, 0, 0)  // Red
+love.graphics.print('Hello', 100, 50)
+const width = love.window.getWidth()
+```
+
+**Techniques:**
+- Use `declare const` to declare Lua global variables and libraries
+- Define complete type signatures for all global APIs and functions
+- Use string literal types for enum-like parameters (e.g., `"fill" | "line"`)
+- Group related functions in nested object types matching Lua structure
+- Document expected parameters and return types for each API call
+- Use union types for optional or variable-length parameters
+- Create type definitions that match exact Lua API signatures

package/skills/typescript-to-lua-guidelines/reference/module-organization.md

@@ -0,0 +1,42 @@
+# module-organization: Module Organization
+
+**Guideline:** Organize code in flat namespace hierarchies that map cleanly to Lua tables.
+
+**Rationale:** Nested namespaces compile to nested Lua tables, creating efficient module systems aligned with Lua patterns.
+
+**Example:**
+```typescript
+// Good: 2-level hierarchy, organized by feature
+namespace Physics {
+  namespace Collision {
+    export interface Circle { x: number; y: number; radius: number }
+    export function intersect(a: Circle, b: Circle): boolean {
+      const dx = a.x - b.x
+      const dy = a.y - b.y
+      const dist = Math.sqrt(dx * dx + dy * dy)
+      return dist < a.radius + b.radius
+    }
+  }
+  export function update(body: Body, dt: number) { /* ... */ }
+}
+
+namespace Rendering {
+  namespace Color {
+    export const RED = { r: 1, g: 0, b: 0 }
+    export const BLUE = { r: 0, g: 0, b: 1 }
+  }
+  export function draw(mesh: Mesh) { /* ... */ }
+}
+
+// Avoid: Too deep (translates to verbose Lua)
+namespace Game.Entities.Physics.Collision.Detection {}
+```
+
+**Techniques:**
+- Use nested namespaces for logical grouping that maps to Lua table structure
+- Export functions directly within namespaces (not as properties)
+- Keep hierarchy shallow: maximum 2-3 levels deep for clarity
+- Group related functionality together in single namespace
+- Organize by feature (Physics, Rendering, Input) rather than by file
+- Use consistent naming conventions across namespace hierarchy
+- Minimize cross-namespace dependencies for cleaner module structure

package/skills/typescript-to-lua-guidelines/reference/multi-return-functions.md

@@ -0,0 +1,47 @@
+# multi-return-functions: Lua Multi-Return Functions
+
+**Guideline:** Use `LuaMultiReturn` and `$multi()` for idiomatic Lua multiple-value returns.
+
+**Rationale:** Lua natively supports multiple returns, more efficient than arrays/objects. TSTL provides `LuaMultiReturn` for type-safe multi-returns.
+
+**Example:**
+```typescript
+import { LuaMultiReturn } from 'typescript-to-lua'
+
+// Simple multi-return
+function divmod(a: number, b: number): LuaMultiReturn<[number, number]> {
+  return $multi(Math.floor(a / b), a % b)
+}
+
+// Usage
+const [quotient, remainder] = divmod(17, 5)
+// quotient = 3, remainder = 2
+
+// Error handling with optional
+function parseJSON(json: string): LuaMultiReturn<[object | null, string | null]> {
+  try {
+    return $multi(JSON.parse(json), null)
+  } catch (e) {
+    return $multi(null, (e as Error).message)
+  }
+}
+
+// Usage
+const [data, err] = parseJSON('{"key": "value"}')
+if (err) console.error('Parse error:', err)
+else console.log('Data:', data)
+
+// Variadic returns
+function unpack<T extends any[]>(arr: T): LuaMultiReturn<T> {
+  return $multi(...arr)
+}
+```
+
+**Techniques:**
+- Import `LuaMultiReturn` from "typescript-to-lua" package
+- Declare return type as `LuaMultiReturn<[type1, type2, ...]>` for multiple values
+- Return using `$multi(value1, value2, ...)` function call syntax
+- Destructure multi-returns with `const [a, b] = func()` for clarity
+- Use for idiomatic Lua patterns like divmod that return quotient and remainder
+- Implement error handling by returning optional value with error message
+- Support variadic returns with spread operator inside $multi

package/skills/typescript-to-lua-guidelines/reference/namespaces-vs-classes.md

@@ -0,0 +1,52 @@
+# namespaces-vs-classes: Namespace vs Class Design
+
+**Guideline:** Prefer namespaces over classes for cleaner, more efficient Lua output.
+
+**Rationale:** Classes generate metatables and inheritance chains. Namespaces compile to simple Lua tables with functions, resulting in efficient output.
+
+**Example:**
+```typescript
+// AVOID: Class generates complex Lua with metatables
+class Vector {
+  constructor(public x: number, public y: number) {}
+  magnitude(): number {
+    return Math.sqrt(this.x * this.x + this.y * this.y)
+  }
+  normalize(): Vector {
+    const m = this.magnitude()
+    return new Vector(this.x / m, this.y / m)
+  }
+}
+
+// PREFER: Namespace generates simple Lua tables
+namespace Vector {
+  export interface Vec { x: number; y: number }
+
+  export function magnitude(v: Vec): number {
+    return Math.sqrt(v.x * v.x + v.y * v.y)
+  }
+
+  export function normalize(v: Vec): Vec {
+    const m = magnitude(v)
+    return { x: v.x / m, y: v.y / m }
+  }
+
+  export function add(a: Vec, b: Vec): Vec {
+    return { x: a.x + b.x, y: a.y + b.y }
+  }
+}
+
+// Usage
+const v: Vector.Vec = { x: 3, y: 4 }
+const mag = Vector.magnitude(v)      // 5
+const norm = Vector.normalize(v)     // { x: 0.6, y: 0.8 }
+```
+
+**Techniques:**
+- Use `export namespace` for grouping related functions instead of classes
+- Export functions directly within namespaces (not static methods)
+- Avoid classes for purely functional code, use namespaces for cleaner output
+- Keep functions pure and stateless within namespaces
+- Use composition patterns to share behavior across namespaces
+- Consider inheritance only when truly needed (rare in Lua)
+- Prefer namespace-based organization for utilities and helper functions

package/skills/typescript-to-lua-guidelines/reference/performance-tips.md

@@ -0,0 +1,68 @@
+# performance-tips: Performance Optimization Tips
+
+**Guideline:** Cache lookups, use numeric for-loops, and pre-allocate data structures for optimal performance.
+
+**Rationale:** Lua has different performance characteristics than JavaScript. Lookups, iterators, and dynamic allocation have costs. Pre-allocation aligns with LuaJIT optimization.
+
+**Example:**
+```typescript
+// SLOW: Repeated lookups, for-of loop
+for (const item of items) {
+  console.log(item)
+  Math.sqrt(item.value)  // Lookup Math each iteration
+}
+
+// FAST: Cache lookups, numeric loop
+const sqrt = Math.sqrt
+const itemsLen = items.length
+for (let i = 0; i < itemsLen; i++) {
+  const item = items[i]
+  console.log(item)
+  sqrt(item.value)  // Cached reference
+}
+
+// SLOW: Dynamic array growth
+const results: number[] = []
+for (const item of items) {
+  results.push(item * 2)  // Reallocates as it grows
+}
+
+// FAST: Pre-allocate
+const results = new Array<number>(items.length)
+for (let i = 0; i < items.length; i++) {
+  results[i] = items[i] * 2  // No reallocation
+}
+
+// SLOW: Table allocation in hot path
+function updatePositions(bodies: Body[]) {
+  for (const body of bodies) {
+    const delta = { x: 0, y: 0 }  // Allocates each call
+    delta.x = body.vx * dt
+    delta.y = body.vy * dt
+    body.x += delta.x
+    body.y += delta.y
+  }
+}
+
+// FAST: Reuse allocation
+const delta = { x: 0, y: 0 }
+function updatePositions(bodies: Body[]) {
+  for (let i = 0; i < bodies.length; i++) {
+    const body = bodies[i]
+    delta.x = body.vx * dt
+    delta.y = body.vy * dt
+    body.x += delta.x
+    body.y += delta.y
+  }
+}
+```
+
+**Techniques:**
+- Cache frequently-used global functions in local variables for fast lookup
+- Use numeric for-loops (`for (let i = 0; i < arr.length; i++)`) instead of for-of
+- Avoid for-of and for-in iterators that generate overhead in Lua
+- Pre-allocate arrays when final size is known to avoid dynamic growth
+- Minimize table allocations in hot paths (frequently-called functions)
+- Store module-level constants in locals within functions that use them
+- Profile hot paths and focus optimization on frequently-executed code
+- Use LuaJIT-friendly patterns: early allocation, numeric indices, minimal lookups

package/skills/typescript-to-lua-guidelines/reference/stable-tables.md

@@ -0,0 +1,60 @@
+# stable-tables: Stable Table Patterns
+
+**Guideline:** Define all table fields upfront to enable LuaJIT optimizations.
+
+**Rationale:** LuaJIT performs best with constant table shapes. Adding fields dynamically causes deoptimization. Pre-allocating fields enables optimal JIT compilation.
+
+**Example:**
+```typescript
+// SLOW: Dynamic property addition (deoptimizes JIT)
+const entity = { x: 0, y: 0 }
+entity.vx = 1     // Added after creation - bad for JIT
+entity.vy = 1     // Another dynamic addition
+entity.id = 123   // Yet another - very slow
+
+// FAST: All fields defined upfront
+interface Entity {
+  readonly x: number
+  readonly y: number
+  readonly vx: number
+  readonly vy: number
+  readonly id: number
+}
+
+function createEntity(x: number, y: number, id: number): Entity {
+  return {
+    x: x,
+    y: y,
+    vx: 0,    // All fields initialized
+    vy: 0,
+    id: id
+  }
+}
+
+// SLOW: Variable-sized arrays
+const buffers: number[][] = []
+function addData(id: number, data: number[]) {
+  buffers[id] = data  // Variable size - bad for JIT
+}
+
+// FAST: Pre-allocated arrays
+const maxEntities = 1000
+const posX = new Array<number>(maxEntities)  // Fixed size
+const posY = new Array<number>(maxEntities)
+const velocities: number[][] = new Array(maxEntities)
+
+for (let i = 0; i < maxEntities; i++) {
+  posX[i] = 0
+  posY[i] = 0
+  velocities[i] = [0, 0]  // Stable sub-arrays
+}
+```
+
+**Techniques:**
+- Define complete interfaces with all properties and types upfront
+- Initialize all fields in factory functions to establish table shape
+- Pre-allocate arrays with known sizes to avoid dynamic growth
+- Avoid dynamically adding properties after creation (hurts JIT)
+- Use `readonly` modifiers to signal immutability and stability
+- Create factory functions that set all fields in one operation
+- Keep table structure consistent across all instances of a type

package/skills/typescript-to-lua-guidelines/reference/tsconfig.md

@@ -0,0 +1,46 @@
+# tsconfig: TypeScript Configuration for TSTL
+
+**Guideline:** Configure TypeScript with strict mode and TSTL settings for optimal Lua generation.
+
+**Rationale:** Strict options catch errors early and generate predictable Lua. TSTL settings control targeting, libraries, and debugging.
+
+**Example:**
+```json
+{
+  "compilerOptions": {
+    "strict": true,
+    "noImplicitAny": true,
+    "strictNullChecks": true,
+    "strictFunctionTypes": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noImplicitReturns": true,
+    "noFallthroughCasesInSwitch": true,
+    "target": "ES2020",
+    "module": "esnext",
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true
+  },
+  "tstl": {
+    "luaTarget": "JIT",
+    "luaLibImport": "require",
+    "sourceMapTraceback": true,
+    "noHeader": false
+  }
+}
+```
+
+**Techniques:**
+- Enable `strict: true` for comprehensive type checking
+- Enable individual strict options: `noImplicitAny`, `strictNullChecks`, `strictFunctionTypes`
+- Enable `noUnusedLocals` and `noUnusedParameters` to catch dead code
+- Enable `noImplicitReturns` to ensure all code paths return
+- Enable `noFallthroughCasesInSwitch` for safer switch statements
+- Set `luaTarget` to appropriate runtime: "JIT" for LuaJIT, "5.3" for Lua 5.3, etc.
+- Set `luaLibImport` to "require" or "inline" for library loading strategy
+- Enable `sourceMapTraceback` for debugging information and stack traces

package/skills/typescript-to-lua-guidelines/reference/tstl-decorators.md

@@ -0,0 +1,61 @@
+# tstl-decorators: TSTL Decorators and Annotations
+
+**Guideline:** Use TSTL-specific decorators and JSDoc annotations to control Lua code generation.
+
+**Rationale:** TSTL decorators like `@luaTable` and `@luaIterator` fine-tune generated Lua. Custom decorators bridge TypeScript and Lua idioms.
+
+**Example:**
+```typescript
+/** @luaTable */
+interface Config {
+  host: string
+  port: number
+  debug: boolean
+}
+
+/** @luaIterator */
+function* enumerate<T>(arr: T[]): Generator<[number, T]> {
+  for (let i = 0; i < arr.length; i++) {
+    yield [i, arr[i]]
+  }
+}
+
+class Vector {
+  constructor(public x: number, public y: number) {}
+
+  // @noSelf means this function doesn't receive 'self' parameter
+  /** @noSelf */
+  static distance(a: Vector, b: Vector): number {
+    const dx = a.x - b.x
+    const dy = a.y - b.y
+    return Math.sqrt(dx * dx + dy * dy)
+  }
+
+  // Regular method gets self: parameter
+  magnitude(): number {
+    return Math.sqrt(this.x * this.x + this.y * this.y)
+  }
+}
+
+// Custom memoization decorator
+function memoize(fn: Function) {
+  const cache = new Map()
+  return (...args: any[]) => {
+    const key = JSON.stringify(args)
+    if (cache.has(key)) return cache.get(key)
+    const result = fn(...args)
+    cache.set(key, result)
+    return result
+  }
+}
+```
+
+**Techniques:**
+- Use `/** @luaTable */` JSDoc annotation for raw Lua table interfaces
+- Use `/** @luaIterator */` for generator-based iterators
+- Use `/** @noSelf */` for functions that don't use 'self' context
+- Use `/** @pureVirtual */` to mark abstract methods
+- Implement custom decorators for cross-cutting concerns
+- Apply decorators for performance optimizations: memoization, caching
+- Use decorators for logging, debugging, and tracing functionality
+- Apply decorators at method level for fine-grained code generation control

package/skills/typescript-to-lua-guidelines/reference/type-safety.md

@@ -0,0 +1,79 @@
+# type-safety: Type Safety Patterns
+
+**Guideline:** Use strict typing with readonly properties, discriminated unions, and complete annotations.
+
+**Rationale:** TypeScript's type system catches errors at compile time and guides TSTL. Patterns like discriminated unions provide type-safe error handling.
+
+**Example:**
+```typescript
+// Discriminated union for type-safe results
+type Result<T, E> =
+  | { kind: 'ok'; value: T }
+  | { kind: 'err'; error: E }
+
+namespace Result {
+  export function ok<T, E>(value: T): Result<T, E> {
+    return { kind: 'ok', value }
+  }
+
+  export function err<T, E>(error: E): Result<T, E> {
+    return { kind: 'err', error }
+  }
+
+  export function map<T, U, E>(
+    result: Result<T, E>,
+    fn: (t: T) => U
+  ): Result<U, E> {
+    if (result.kind === 'ok') {
+      return ok(fn(result.value))
+    }
+    return result
+  }
+}
+
+// Readonly properties signal immutability
+interface Position {
+  readonly x: number
+  readonly y: number
+}
+
+interface Entity {
+  readonly id: number
+  readonly position: Position
+  readonly velocity: readonly [number, number]  // Readonly tuple
+}
+
+// Complete generic types
+type Option<T> = { kind: 'some'; value: T } | { kind: 'none' }
+
+namespace Option {
+  export function some<T>(value: T): Option<T> {
+    return { kind: 'some', value }
+  }
+
+  export function none<T>(): Option<T> {
+    return { kind: 'none' }
+  }
+
+  export function getOrElse<T>(opt: Option<T>, def: T): T {
+    if (opt.kind === 'some') return opt.value
+    return def
+  }
+}
+
+// Type-safe usage
+const result: Result<number, string> = Result.ok(42)
+if (result.kind === 'ok') {
+  console.log(result.value)  // Type is number
+}
+```
+
+**Techniques:**
+- Use `readonly` modifiers for immutable properties to signal intent
+- Define complete interfaces with all properties typed explicitly
+- Implement discriminated unions for type-safe variant handling
+- Create namespaces paired with interfaces for factories and utilities
+- Use union types for optional or alternative values
+- Implement generic types for reusable patterns (Result<T, E>, Option<T>)
+- Use factory functions to enforce proper initialization
+- Provide utility functions as namespace members for convenience

package/skills/vitest-guidelines/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: vitest-guidelines
+description: >-
+  Trigger on `.test.ts`, `.spec.ts` files, test blocks. Use when writing Vitest 3+ tests with TypeScript. Apply for type safety in tests, HTTP testing, mocking patterns, test organization. Keywords: Vitest, test, spec, HTTP assertions, mock patterns, type safety, CORS preflight, timestamps, response casting.
+---
+
+# Vitest Testing Guidelines
+
+## Requirements
+
+- Vitest ≥ 3, TypeScript ≥ 5.8
+
+## Essentials
+
+- **Type safety** - Define response interfaces, cast JSON results, see [reference/type-safety.md](reference/type-safety.md), [reference/json-response-type-safety.md](reference/json-response-type-safety.md)
+- **HTTP testing** - Use HTTP 204 for OPTIONS, assert correct status codes, see [reference/http-testing.md](reference/http-testing.md), [reference/cors-preflight-status-code.md](reference/cors-preflight-status-code.md)
+- **Timestamp testing** - Avoid flaky comparisons, verify existence or add delays, see [reference/timestamp-testing.md](reference/timestamp-testing.md)
+- **Mock patterns** - Use simple type casting instead of complex generics, see [reference/mock-patterns.md](reference/mock-patterns.md)
+- **TypeScript config** - Verify project reference paths match structure, see [reference/typescript-config.md](reference/typescript-config.md), [reference/project-references-path-resolution.md](reference/project-references-path-resolution.md)
+- **Test organization** - Organize by endpoint/feature with nested describe blocks, see [reference/test-organization.md](reference/test-organization.md)
+
+## Progressive disclosure
+
+- Read [reference/type-safety.md](reference/type-safety.md) - When test variables lose type information
+- Read [reference/json-response-type-safety.md](reference/json-response-type-safety.md) - When calling res.json() without type assertions
+- Read [reference/http-testing.md](reference/http-testing.md) - When asserting HTTP status codes in API tests
+- Read [reference/cors-preflight-status-code.md](reference/cors-preflight-status-code.md) - When testing CORS OPTIONS requests
+- Read [reference/timestamp-testing.md](reference/timestamp-testing.md) - When tests fail intermittently due to timing
+- Read [reference/mock-patterns.md](reference/mock-patterns.md) - When creating mocks or stubs for tests
+- Read [reference/typescript-config.md](reference/typescript-config.md) - When test files aren't recognized by TypeScript
+- Read [reference/project-references-path-resolution.md](reference/project-references-path-resolution.md) - When imports fail in test files
+- Read [reference/test-organization.md](reference/test-organization.md) - When structuring test suites for large APIs

package/skills/vitest-guidelines/reference/cors-preflight-status-code.md

@@ -0,0 +1,34 @@
+# cors-preflight-status-code: CORS Preflight Status Code Expectations
+
+**Guideline:** OPTIONS preflight requests should return HTTP 204 (No Content), not 200 (OK).
+
+**Rationale:** HTTP 204 is the correct status code for OPTIONS requests with no response body.
+
+**Example:**
+
+```typescript
+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",
+      "Access-Control-Request-Headers": "Content-Type",
+    },
+  });
+
+  expect(res.status).toBe(204); // ✅ Correct
+  expect(res.headers.get("Access-Control-Allow-Origin")).toBe("*");
+  expect(res.headers.get("Access-Control-Allow-Methods")).toContain("POST");
+  expect(res.headers.get("Access-Control-Allow-Headers")).toContain(
+    "Content-Type",
+  );
+});
+```
+
+**Techniques:**
+- Always expect 204 status for OPTIONS requests in tests
+- Verify CORS headers are present (Access-Control-Allow-Origin, etc.)
+- Don't expect a response body from OPTIONS
+- Use the same pattern for all preflight request tests
+- Test both missing and present CORS headers