@djm204/agent-skills 1.0.0

package/templates/languages/javascript-expert/.cursor/rules/testing.mdc

@@ -0,0 +1,76 @@
+---
+description: JavaScript Testing
+alwaysApply: false
+---
+
+# JavaScript Testing
+
+- Tests are production code — same quality standards
+- Test behavior and contracts, never implementation details
+- Every bug fix starts with a failing test
+- If it's hard to test, the design is wrong
+
+## Unit Tests
+
+```typescript
+describe('clamp', () => {
+  it('returns value when within range', () => { expect(clamp(5, 0, 10)).toBe(5); });
+  it('returns min when below range', () => { expect(clamp(-5, 0, 10)).toBe(0); });
+  it('returns max when above range', () => { expect(clamp(15, 0, 10)).toBe(10); });
+});
+
+// Parameterized
+it.each([
+  ['Hello World', 'hello-world'],
+  ['Special!@#Chars', 'specialchars'],
+])('slugify "%s" → "%s"', (input, expected) => { expect(slugify(input)).toBe(expected); });
+```
+
+## Component Tests
+
+```tsx
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+
+it('adds a new todo when form is submitted', async () => {
+  const user = userEvent.setup();
+  render(<TodoList />);
+  await user.type(screen.getByRole('textbox', { name: /new todo/i }), 'Buy milk');
+  await user.click(screen.getByRole('button', { name: /add/i }));
+  expect(screen.getByText('Buy milk')).toBeInTheDocument();
+});
+```
+
+## Mocking (MSW for APIs)
+
+```typescript
+import { http, HttpResponse } from 'msw';
+import { setupServer } from 'msw/node';
+const server = setupServer(
+  http.get('/api/users/:id', ({ params }) => HttpResponse.json({ id: params.id, name: 'Test' })),
+);
+beforeAll(() => server.listen({ onUnhandledRequest: 'error' }));
+afterEach(() => server.resetHandlers());
+afterAll(() => server.close());
+```
+
+- Mock at boundaries (HTTP, DB), not internals — if you need to mock internals, redesign
+- Use dependency injection for testability
+
+## E2E Tests (Playwright)
+
+```typescript
+test('login flow', async ({ page }) => {
+  await page.goto('/login');
+  await page.getByLabel('Email').fill('user@example.com');
+  await page.getByLabel('Password').fill('password');
+  await page.getByRole('button', { name: 'Sign in' }).click();
+  await expect(page).toHaveURL('/dashboard');
+});
+```
+
+## Anti-Patterns
+
+- Never test implementation details (internal state, class names)
+- Never `setTimeout` for waiting — use `waitFor` or `findBy`
+- Never let tests depend on execution order; never ignore flaky tests

package/templates/languages/javascript-expert/.cursor/rules/tooling.mdc

@@ -0,0 +1,72 @@
+---
+description: JavaScript Tooling
+alwaysApply: false
+---
+
+# JavaScript Tooling
+
+Modern JavaScript tooling configuration and best practices.
+
+## TypeScript Configuration
+
+```jsonc
+{
+  "compilerOptions": {
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "exactOptionalPropertyTypes": true,
+    "verbatimModuleSyntax": true,
+    "isolatedModules": true,
+    "moduleResolution": "bundler",
+    "module": "ESNext",
+    "target": "ES2022"
+  }
+}
+```
+
+## Package Management
+
+- `"type": "module"` in package.json, `"engines": { "node": ">=20" }`
+- Pin exact versions for apps, ranges for libraries
+- Audit regularly (`npm audit`), prefer zero-dependency packages
+- Check bundle size before adding (`bundlephobia.com`), remove unused (`npx depcheck`)
+
+## Linting (ESLint Flat Config)
+
+```javascript
+import tseslint from 'typescript-eslint';
+export default tseslint.config(
+  ...tseslint.configs.strictTypeChecked,
+  { rules: {
+    '@typescript-eslint/no-explicit-any': 'error',
+    '@typescript-eslint/no-floating-promises': 'error',
+    '@typescript-eslint/no-misused-promises': 'error',
+    'no-console': ['warn', { allow: ['warn', 'error'] }],
+  }},
+);
+```
+
+## Build Tools
+
+- **Vite** (frontend): `target: 'es2022'`, sourcemaps, manual chunks for vendor splitting
+- **tsup** (libraries): ESM output, `dts: true`, `treeshake: true`, `splitting: true`
+
+## Git Hooks
+
+```jsonc
+{
+  "scripts": {
+    "prepare": "husky",
+    "check": "npm run typecheck && npm run lint && npm run test"
+  },
+  "lint-staged": {
+    "*.{ts,tsx}": ["eslint --fix", "prettier --write"],
+    "*.{json,md,yml}": ["prettier --write"]
+  }
+}
+```
+
+## Debugging
+
+- Node.js: `node --inspect-brk app.js` + Chrome DevTools
+- Use structured logging over `console.log` — never log passwords, tokens, or PII

package/templates/languages/javascript-expert/.cursor/rules/typescript-deep-dive.mdc

@@ -0,0 +1,77 @@
+---
+description: TypeScript Deep Dive
+alwaysApply: false
+---
+
+# TypeScript Deep Dive
+
+Advanced type system mastery. Builds on `overview.mdc` (discriminated unions, branded types, const assertions).
+
+## Generics
+
+```typescript
+function getProperty<T, K extends keyof T>(obj: T, key: K): T[K] { return obj[key]; }
+function merge<T extends object, U extends object>(a: T, b: U): T & U { return { ...a, ...b }; }
+```
+
+## Conditional Types
+
+```typescript
+type Awaited<T> = T extends Promise<infer U> ? Awaited<U> : T;
+type ToArray<T> = T extends unknown ? T[] : never; // Distributive
+type ToArrayNonDist<T> = [T] extends [unknown] ? T[] : never; // Non-distributive
+```
+
+## Mapped Types
+
+```typescript
+type Getters<T> = { [K in keyof T as `get${Capitalize<string & K>}`]: () => T[K] };
+type PickByType<T, V> = { [K in keyof T as T[K] extends V ? K : never]: T[K] };
+type DeepReadonly<T> = {
+  readonly [K in keyof T]: T[K] extends object ? T[K] extends Function ? T[K] : DeepReadonly<T[K]> : T[K];
+};
+```
+
+## Template Literal Types
+
+```typescript
+type ExtractParams<T extends string> =
+  T extends `${string}:${infer P}/${infer Rest}` ? P | ExtractParams<`/${Rest}`>
+  : T extends `${string}:${infer P}` ? P : never;
+type Params = ExtractParams<'/users/:userId/posts/:postId'>; // "userId" | "postId"
+```
+
+## `satisfies` Operator
+
+```typescript
+const routes = {
+  home: { path: '/', component: HomePage },
+} satisfies Record<string, { path: string; component: React.ComponentType }>;
+// routes.home.path is literal "/" — not widened to string
+```
+
+## Runtime Boundary Validation
+
+```typescript
+import { z } from 'zod';
+const UserSchema = z.object({ id: z.string().uuid(), email: z.string().email(), role: z.enum(['admin', 'user']) });
+type User = z.infer<typeof UserSchema>; // Single source of truth
+
+// Validate at every I/O boundary — types disappear at runtime
+const parsed = UserSchema.safeParse(body);
+if (!parsed.success) return Response.json({ errors: parsed.error.flatten().fieldErrors }, { status: 400 });
+```
+
+## Type Predicates
+
+```typescript
+function isUser(value: unknown): value is User {
+  return typeof value === 'object' && value !== null && 'id' in value && 'email' in value;
+}
+```
+
+## Anti-Patterns
+
+- Never `any` — use `unknown` then narrow with type guards or Zod
+- Never `as` to silence errors — use runtime validation
+- Never `enum` — use string literal unions (`type Status = 'active' | 'inactive'`)

package/templates/languages/javascript-expert/CLAUDE.md

@@ -0,0 +1,479 @@
+# JavaScript & TypeScript Expert Development Guide
+
+Comprehensive guidelines for principal-level JavaScript and TypeScript engineering across all runtimes, frameworks, and paradigms.
+
+**This template covers both JavaScript and TypeScript.** TypeScript is the default — all code is written in strict TypeScript. Advanced type system patterns (conditional types, mapped types, generics, runtime validation) are included.
+
+---
+
+## Overview
+
+This guide applies to:
+- Node.js services, CLIs, and tooling
+- React, Vue, Angular, Svelte, and other UI frameworks
+- Vanilla JavaScript and Web APIs
+- TypeScript (strict mode, always) — including advanced type system patterns
+- Build tools, bundlers, and transpilers
+- Testing at every level (unit, integration, E2E, performance)
+
+### Core Philosophy
+
+JavaScript is the runtime. Know it deeply:
+- The event loop is not optional knowledge — it's the foundation
+- Prototypes, closures, and the module system are first principles
+- The spec (ECMAScript) is the source of truth, not blog posts
+- Every abstraction leaks — understand what's underneath
+
+### Key Principles
+
+1. **Language Mastery Over Framework Dependence** - Frameworks come and go, JS fundamentals are permanent
+2. **Type Safety Is Non-Negotiable** - TypeScript strict mode, always
+3. **Functional by Default** - Pure functions and composition, classes when lifecycle demands it
+4. **Performance Is a Feature** - Profile before optimizing, measure don't guess
+5. **Error Handling Is Control Flow** - Result types over thrown exceptions
+
+### Project Structure
+
+```
+src/
+├── core/              # Pure business logic, zero dependencies
+├── adapters/          # External integrations (DB, HTTP, FS)
+├── services/          # Orchestration layer
+├── utils/             # Pure utility functions
+├── types/             # TypeScript type definitions
+├── __tests__/         # Test files
+└── index.ts           # Public API surface
+```
+
+---
+
+## Language Deep Dive
+
+### The Event Loop
+
+Understanding execution order is fundamental:
+
+```typescript
+console.log('1 - sync');
+setTimeout(() => console.log('2 - macrotask'), 0);
+Promise.resolve().then(() => console.log('3 - microtask'));
+queueMicrotask(() => console.log('4 - microtask'));
+console.log('5 - sync');
+// Output: 1, 5, 3, 4, 2
+```
+
+### Type Safety
+
+```typescript
+// Discriminated unions over optional fields
+type Result<T, E = Error> =
+  | { ok: true; value: T }
+  | { ok: false; error: E };
+
+// Branded types for domain safety
+type UserId = string & { readonly __brand: unique symbol };
+
+// Const assertions and template literal types
+const EVENTS = ['click', 'keydown', 'submit'] as const;
+type EventName = (typeof EVENTS)[number];
+```
+
+### TypeScript Deep Dive
+
+Advanced type system patterns beyond the basics:
+
+```typescript
+// Conditional types
+type Awaited<T> = T extends Promise<infer U> ? Awaited<U> : T;
+
+// Mapped types with key remapping
+type Getters<T> = {
+  [K in keyof T as `get${Capitalize<string & K>}`]: () => T[K];
+};
+
+// Template literal type extraction
+type ExtractParams<T extends string> =
+  T extends `${string}:${infer Param}/${infer Rest}`
+    ? Param | ExtractParams<`/${Rest}`>
+    : T extends `${string}:${infer Param}` ? Param : never;
+
+// satisfies — validate without widening
+const config = { port: 3000, host: 'localhost' } satisfies Record<string, string | number>;
+// config.port is still number, not string | number
+
+// Runtime boundary validation with Zod
+const UserSchema = z.object({ id: z.string().uuid(), email: z.string().email() });
+type User = z.infer<typeof UserSchema>;
+// Types disappear at runtime — validate at every I/O boundary
+```
+
+### Functional Patterns
+
+```typescript
+const pipe = <T>(...fns: Array<(arg: T) => T>) =>
+  (value: T): T => fns.reduce((acc, fn) => fn(acc), value);
+
+const processUser = pipe(validateInput, normalizeEmail, hashPassword);
+```
+
+### Async Patterns
+
+```typescript
+// Parallel independent operations
+const [users, posts] = await Promise.all([fetchUsers(), fetchPosts()]);
+
+// Race with timeout
+const withTimeout = <T>(promise: Promise<T>, ms: number): Promise<T> =>
+  Promise.race([
+    promise,
+    new Promise<never>((_, reject) =>
+      setTimeout(() => reject(new Error(`Timeout after ${ms}ms`)), ms)
+    ),
+  ]);
+
+// Async iteration for streams
+async function* readChunks(stream: ReadableStream<Uint8Array>) {
+  const reader = stream.getReader();
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      yield value;
+    }
+  } finally {
+    reader.releaseLock();
+  }
+}
+```
+
+### Generators and Lazy Evaluation
+
+```typescript
+function* filter<T>(iterable: Iterable<T>, predicate: (item: T) => boolean) {
+  for (const item of iterable) {
+    if (predicate(item)) yield item;
+  }
+}
+
+function* take<T>(iterable: Iterable<T>, count: number) {
+  let i = 0;
+  for (const item of iterable) {
+    if (i++ >= count) break;
+    yield item;
+  }
+}
+```
+
+### Error Handling
+
+```typescript
+// Result types for expected failures
+function parseConfig(raw: string): Result<Config> {
+  try {
+    const parsed = JSON.parse(raw);
+    const validated = ConfigSchema.safeParse(parsed);
+    if (!validated.success) {
+      return { ok: false, error: new ValidationError(validated.error) };
+    }
+    return { ok: true, value: validated.data };
+  } catch {
+    return { ok: false, error: new ParseError('Invalid JSON') };
+  }
+}
+
+// Reserve throw for invariant violations
+function assertNonNull<T>(value: T | null | undefined, msg: string): asserts value is T {
+  if (value == null) throw new Error(`Invariant: ${msg}`);
+}
+```
+
+---
+
+## Node.js Patterns
+
+### Graceful Shutdown
+
+```typescript
+const shutdown = async (signal: string) => {
+  console.log(`Received ${signal}, shutting down...`);
+  server.close();
+  await db.disconnect();
+  process.exit(0);
+};
+
+process.on('SIGTERM', () => shutdown('SIGTERM'));
+process.on('SIGINT', () => shutdown('SIGINT'));
+```
+
+### Streams
+
+```typescript
+import { pipeline } from 'node:stream/promises';
+
+await pipeline(
+  createReadStream('input.log'),
+  new Transform({
+    transform(chunk, _encoding, callback) {
+      const filtered = chunk.toString()
+        .split('\n')
+        .filter((line: string) => line.includes('ERROR'))
+        .join('\n');
+      callback(null, filtered);
+    },
+  }),
+  createGzip(),
+  createWriteStream('errors.log.gz'),
+);
+```
+
+### Worker Threads
+
+```typescript
+import { Worker, isMainThread, parentPort, workerData } from 'node:worker_threads';
+
+if (isMainThread) {
+  const runWorker = <T>(data: unknown): Promise<T> =>
+    new Promise((resolve, reject) => {
+      const worker = new Worker(new URL(import.meta.url), { workerData: data });
+      worker.on('message', resolve);
+      worker.on('error', reject);
+    });
+} else {
+  const result = performExpensiveComputation(workerData);
+  parentPort!.postMessage(result);
+}
+```
+
+### Configuration
+
+```typescript
+import { z } from 'zod';
+
+const EnvSchema = z.object({
+  NODE_ENV: z.enum(['development', 'production', 'test']),
+  PORT: z.coerce.number().int().positive().default(3000),
+  DATABASE_URL: z.string().url(),
+});
+
+export const env = EnvSchema.parse(process.env);
+```
+
+---
+
+## React Patterns
+
+### Server Components First (React 19+)
+
+```tsx
+// Default: Server Component — no 'use client'
+async function ProjectList() {
+  const projects = await db.projects.findMany();
+  return <ul>{projects.map(p => <ProjectCard key={p.id} project={p} />)}</ul>;
+}
+
+// Only add 'use client' when you need interactivity
+'use client';
+function SearchInput({ onSearch }: { onSearch: (q: string) => void }) {
+  const [query, setQuery] = useState('');
+  return <input value={query} onChange={e => setQuery(e.target.value)} />;
+}
+```
+
+### Composition Patterns
+
+```tsx
+// Compound components
+function Tabs({ children }: { children: React.ReactNode }) {
+  const [active, setActive] = useState(0);
+  return <TabsContext.Provider value={{ active, setActive }}>{children}</TabsContext.Provider>;
+}
+Tabs.List = function TabList({ children }) { ... };
+Tabs.Panel = function TabPanel({ children, index }) { ... };
+```
+
+### State Management Hierarchy
+
+1. `useState` — local state
+2. `useReducer` — complex local state with actions
+3. Context — low-frequency shared state (theme, auth, locale)
+4. External store (Zustand, Jotai) — high-frequency shared state
+
+### Anti-Patterns
+
+```tsx
+// Never: useEffect for derived state
+const fullName = `${firstName} ${lastName}`; // Just compute it
+
+// Never: index as key for dynamic lists
+{items.map(item => <Item key={item.id} item={item} />)}
+
+// Never: Object literals as default props
+const EMPTY: readonly Item[] = [];
+function List({ items = EMPTY }: { items?: readonly Item[] }) { ... }
+```
+
+---
+
+## Testing
+
+### Philosophy
+
+- Tests are production code — same quality standards
+- Test behavior and contracts, never implementation details
+- Every bug fix starts with a failing test
+- If it's hard to test, the design is wrong
+
+### Unit Tests
+
+```typescript
+describe('clamp', () => {
+  it('returns value when within range', () => {
+    expect(clamp(5, 0, 10)).toBe(5);
+  });
+  it('returns min when value is below range', () => {
+    expect(clamp(-5, 0, 10)).toBe(0);
+  });
+  it('returns max when value is above range', () => {
+    expect(clamp(15, 0, 10)).toBe(10);
+  });
+});
+```
+
+### Parameterized Tests
+
+```typescript
+it.each([
+  ['Hello World', 'hello-world'],
+  ['  spaces  ', 'spaces'],
+  ['Special!@#Characters', 'specialcharacters'],
+])('converts "%s" to "%s"', (input, expected) => {
+  expect(slugify(input)).toBe(expected);
+});
+```
+
+### Component Tests
+
+```tsx
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+
+it('adds a new todo when form is submitted', async () => {
+  const user = userEvent.setup();
+  render(<TodoList />);
+  await user.type(screen.getByRole('textbox', { name: /new todo/i }), 'Buy milk');
+  await user.click(screen.getByRole('button', { name: /add/i }));
+  expect(screen.getByText('Buy milk')).toBeInTheDocument();
+});
+```
+
+### API Mocking with MSW
+
+```typescript
+import { http, HttpResponse } from 'msw';
+import { setupServer } from 'msw/node';
+
+const server = setupServer(
+  http.get('/api/users/:id', ({ params }) => {
+    return HttpResponse.json({ id: params.id, name: 'Test User' });
+  }),
+);
+
+beforeAll(() => server.listen({ onUnhandledRequest: 'error' }));
+afterEach(() => server.resetHandlers());
+afterAll(() => server.close());
+```
+
+### E2E Tests
+
+```typescript
+import { test, expect } from '@playwright/test';
+
+test('login flow', async ({ page }) => {
+  await page.goto('/login');
+  await page.getByLabel('Email').fill('user@example.com');
+  await page.getByLabel('Password').fill('password');
+  await page.getByRole('button', { name: 'Sign in' }).click();
+  await expect(page).toHaveURL('/dashboard');
+});
+```
+
+### Test Anti-Patterns
+
+- Never test implementation details (internal state, class names)
+- Never use `setTimeout` for waiting — use `waitFor` or `findBy`
+- Never let tests depend on execution order
+- Never ignore flaky tests — a flaky test is a bug
+
+---
+
+## Performance
+
+### Profiling First
+
+```typescript
+performance.mark('operation-start');
+doExpensiveWork();
+performance.mark('operation-end');
+performance.measure('operation', 'operation-start', 'operation-end');
+```
+
+### V8 Optimization
+
+- Keep function argument shapes consistent (monomorphic)
+- Initialize all object properties in the same order
+- Use `Map`/`Set` for dynamic collections, plain objects for static shapes
+- Use `TypedArray` for numeric data
+
+### Memory Management
+
+- Use `AbortController` signals for event listener cleanup
+- Use `WeakMap`/`WeakRef` for caches that shouldn't prevent GC
+- Avoid closures that capture large scopes — extract only what's needed
+
+### Bundle Size
+
+- Dynamic imports for code splitting
+- Named exports for tree-shaking
+- Prefer native APIs (`structuredClone`, `Intl`, `URL`, `crypto.randomUUID`)
+
+---
+
+## Tooling
+
+### TypeScript Config
+
+```jsonc
+{
+  "compilerOptions": {
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "exactOptionalPropertyTypes": true,
+    "verbatimModuleSyntax": true,
+    "module": "ESNext",
+    "target": "ES2022"
+  }
+}
+```
+
+### Dependency Hygiene
+
+- Pin exact versions for applications
+- Audit regularly (`npm audit`)
+- Prefer zero-dependency packages
+- Check bundle size before adding (`bundlephobia.com`)
+
+---
+
+## Definition of Done
+
+A JavaScript feature is complete when:
+
+- [ ] TypeScript strict mode passes with zero errors
+- [ ] All code paths have explicit types (no `any`)
+- [ ] Unit tests cover logic branches and edge cases
+- [ ] Integration tests verify external boundaries
+- [ ] Error cases are tested, not just happy paths
+- [ ] No floating promises
+- [ ] No memory leaks in long-running paths
+- [ ] Bundle impact assessed (client-side code)
+- [ ] Code reviewed and approved