memory-journal-mcp 8.0.1 → 9.1.0

package/skills/typescript/references/type-system.md

@@ -1,481 +0,0 @@
-# TypeScript Type System Reference
-
-> **Load when:** User asks about type annotations, interfaces vs types, unions, intersections, or type system fundamentals.
-
-Complete guide to TypeScript's structural type system.
-
-## Contents
-
-- [Type Annotations](#type-annotations)
-- [Interfaces vs Type Aliases](#interfaces-vs-type-aliases)
-- [Union and Intersection Types](#union-and-intersection-types)
-- [Literal Types](#literal-types)
-- [Type Guards and Narrowing](#type-guards-and-narrowing)
-- [The satisfies Operator](#the-satisfies-operator)
-
----
-
-## Type Annotations
-
-### Variable Annotations
-
-```typescript
-// Explicit type annotations
-const name: string = 'Alice'
-const age: number = 30
-const active: boolean = true
-
-// Type inference (preferred when obvious)
-const inferredName = 'Bob' // TypeScript infers string
-const inferredAge = 25 // TypeScript infers number
-
-// Arrays
-const numbers: number[] = [1, 2, 3]
-const strings: Array<string> = ['a', 'b', 'c']
-
-// Tuples (fixed-length arrays with specific types)
-const pair: [string, number] = ['age', 30]
-const triple: [string, number, boolean] = ['name', 1, true]
-```
-
-### Function Annotations
-
-```typescript
-// Function with typed parameters and return
-function greet(name: string): string {
-  return `Hello, ${name}!`
-}
-
-// Arrow function
-const add = (a: number, b: number): number => a + b
-
-// Optional parameters
-function greetOptional(name: string, greeting?: string): string {
-  return `${greeting ?? 'Hello'}, ${name}!`
-}
-
-// Default parameters
-function greetDefault(name: string, greeting: string = 'Hello'): string {
-  return `${greeting}, ${name}!`
-}
-
-// Rest parameters
-function sum(...numbers: number[]): number {
-  return numbers.reduce((a, b) => a + b, 0)
-}
-
-// Function type alias
-type Comparator<T> = (a: T, b: T) => number
-const numberCompare: Comparator<number> = (a, b) => a - b
-```
-
----
-
-## Interfaces vs Type Aliases
-
-### When to Use Interfaces
-
-```typescript
-// Interfaces are ideal for object shapes
-interface User {
-  id: string
-  name: string
-  email: string
-}
-
-// Interfaces can be extended
-interface Employee extends User {
-  employeeId: string
-  department: string
-}
-
-// Interfaces can be implemented by classes
-class Manager implements Employee {
-  constructor(
-    public id: string,
-    public name: string,
-    public email: string,
-    public employeeId: string,
-    public department: string
-  ) {}
-}
-
-// Declaration merging (interfaces only)
-interface Config {
-  apiUrl: string
-}
-
-interface Config {
-  timeout: number
-}
-
-// Config now has both apiUrl and timeout
-```
-
-### When to Use Type Aliases
-
-```typescript
-// Type aliases for unions
-type Status = 'pending' | 'approved' | 'rejected'
-
-// Type aliases for complex types
-type Handler = (event: Event) => void
-
-// Type aliases for mapped types
-type Nullable<T> = { [K in keyof T]: T[K] | null }
-
-// Type aliases for conditional types
-type NonNullable<T> = T extends null | undefined ? never : T
-
-// Type aliases for tuples
-type Point = [x: number, y: number]
-type RGB = [red: number, green: number, blue: number]
-```
-
-### Decision Guide
-
-| Use Case          | Prefer      |
-| ----------------- | ----------- |
-| Object shapes     | `interface` |
-| Extending objects | `interface` |
-| Class contracts   | `interface` |
-| Union types       | `type`      |
-| Tuple types       | `type`      |
-| Mapped types      | `type`      |
-| Conditional types | `type`      |
-| Primitive aliases | `type`      |
-
----
-
-## Union and Intersection Types
-
-### Union Types
-
-```typescript
-// Value can be one of several types
-type StringOrNumber = string | number
-
-// Discriminated unions (tagged unions)
-interface Dog {
-  kind: 'dog'
-  bark(): void
-}
-
-interface Cat {
-  kind: 'cat'
-  meow(): void
-}
-
-type Pet = Dog | Cat
-
-function speak(pet: Pet): void {
-  switch (pet.kind) {
-    case 'dog':
-      pet.bark()
-      break
-    case 'cat':
-      pet.meow()
-      break
-  }
-}
-```
-
-### Intersection Types
-
-```typescript
-// Value must satisfy all types
-interface HasName {
-  name: string
-}
-
-interface HasAge {
-  age: number
-}
-
-type Person = HasName & HasAge
-
-const person: Person = {
-  name: 'Alice',
-  age: 30,
-}
-
-// Practical: Extending with additional properties
-type WithTimestamp<T> = T & { createdAt: Date; updatedAt: Date }
-
-interface Article {
-  title: string
-  content: string
-}
-
-type TimestampedArticle = WithTimestamp<Article>
-```
-
----
-
-## Literal Types
-
-### String Literals
-
-```typescript
-// Specific string values
-type Direction = 'north' | 'south' | 'east' | 'west'
-type HttpMethod = 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH'
-
-function move(direction: Direction): void {
-  console.log(`Moving ${direction}`)
-}
-
-move('north') // OK
-move('up') // Error: Argument of type '"up"' is not assignable
-```
-
-### Numeric Literals
-
-```typescript
-type DiceRoll = 1 | 2 | 3 | 4 | 5 | 6
-type BinaryDigit = 0 | 1
-
-function roll(): DiceRoll {
-  return Math.ceil(Math.random() * 6) as DiceRoll
-}
-```
-
-### Template Literal Types
-
-```typescript
-// Construct string literal types
-type EventName = 'click' | 'hover' | 'focus'
-type HandlerName = `on${Capitalize<EventName>}`
-// "onClick" | "onHover" | "onFocus"
-
-// CSS unit types
-type CSSUnit = 'px' | 'em' | 'rem' | '%'
-type CSSValue = `${number}${CSSUnit}`
-
-const width: CSSValue = '100px' // OK
-const height: CSSValue = '50%' // OK
-const bad: CSSValue = '100' // Error
-```
-
----
-
-## Type Guards and Narrowing
-
-### Built-in Type Guards
-
-```typescript
-function process(value: string | number | null): string {
-  // typeof guard
-  if (typeof value === 'string') {
-    return value.toUpperCase()
-  }
-
-  // typeof guard for number
-  if (typeof value === 'number') {
-    return value.toFixed(2)
-  }
-
-  // null/undefined narrowing
-  if (value === null) {
-    return 'null'
-  }
-
-  // Exhaustiveness check
-  const _exhaustive: never = value
-  throw new Error(`Unhandled case: ${_exhaustive}`)
-}
-```
-
-### instanceof Guard
-
-```typescript
-class ApiError extends Error {
-  constructor(
-    public statusCode: number,
-    message: string
-  ) {
-    super(message)
-  }
-}
-
-class ValidationError extends Error {
-  constructor(public fields: string[]) {
-    super('Validation failed')
-  }
-}
-
-function handleError(error: Error): void {
-  if (error instanceof ApiError) {
-    console.log(`API Error ${error.statusCode}: ${error.message}`)
-  } else if (error instanceof ValidationError) {
-    console.log(`Validation Error on fields: ${error.fields.join(', ')}`)
-  } else {
-    console.log(`Unknown error: ${error.message}`)
-  }
-}
-```
-
-### Custom Type Guards
-
-```typescript
-interface User {
-  type: 'user'
-  name: string
-}
-
-interface Admin {
-  type: 'admin'
-  name: string
-  permissions: string[]
-}
-
-type Account = User | Admin
-
-// Type predicate: returns boolean but narrows type
-function isAdmin(account: Account): account is Admin {
-  return account.type === 'admin'
-}
-
-function getPermissions(account: Account): string[] {
-  if (isAdmin(account)) {
-    return account.permissions // TypeScript knows this is Admin
-  }
-  return []
-}
-```
-
-### Assertion Functions
-
-```typescript
-function assertDefined<T>(value: T | undefined, message: string): asserts value is T {
-  if (value === undefined) {
-    throw new Error(message)
-  }
-}
-
-function processUser(user: User | undefined): void {
-  assertDefined(user, 'User is required')
-  // After assertion, user is narrowed to User
-  console.log(user.name)
-}
-```
-
----
-
-## The satisfies Operator
-
-### Problem: Type Assertions Hide Bugs
-
-```typescript
-// Using 'as' can hide type errors
-const config = {
-  port: 3000,
-  host: 'localhost',
-} as Record<string, string | number>
-
-// No error, but port is now string | number
-const portString = config.port.toFixed(2) // Runtime error if port is string!
-```
-
-### Solution: satisfies Validates Without Widening
-
-```typescript
-// satisfies checks conformance but preserves literal types
-const config = {
-  port: 3000,
-  host: 'localhost',
-} satisfies Record<string, string | number>
-
-// TypeScript knows port is number, host is string
-config.port.toFixed(2) // OK - port is number
-config.host.toUpperCase() // OK - host is string
-```
-
-### Practical Use Cases
-
-```typescript
-// Color palette with constrained values
-const palette = {
-  primary: '#007bff',
-  secondary: '#6c757d',
-  success: '#28a745',
-} satisfies Record<string, `#${string}`>
-
-// TypeScript knows each property exists and is a hex string
-palette.primary.startsWith('#') // OK
-
-// Route configuration
-type RouteConfig = {
-  path: string
-  method: 'GET' | 'POST'
-  handler: () => void
-}
-
-const routes = {
-  home: { path: '/', method: 'GET', handler: () => {} },
-  login: { path: '/login', method: 'POST', handler: () => {} },
-} satisfies Record<string, RouteConfig>
-
-// TypeScript preserves literal types for each route
-routes.home.method // "GET" (not "GET" | "POST")
-```
-
----
-
-## Special Types
-
-### any vs unknown
-
-```typescript
-// any: Opt out of type checking (avoid)
-let anyValue: any = 'hello'
-anyValue.toFixed(2) // No error, but crashes at runtime
-
-// unknown: Type-safe any (prefer)
-let unknownValue: unknown = 'hello'
-unknownValue.toFixed(2) // Error: Object is of type 'unknown'
-
-// Must narrow unknown before use
-if (typeof unknownValue === 'string') {
-  unknownValue.toUpperCase() // OK after narrowing
-}
-```
-
-### never
-
-```typescript
-// never: Represents impossible values
-function fail(message: string): never {
-  throw new Error(message)
-}
-
-// Exhaustiveness checking with never
-type Shape = 'circle' | 'square'
-
-function getArea(shape: Shape): number {
-  switch (shape) {
-    case 'circle':
-      return Math.PI
-    case 'square':
-      return 1
-    default:
-      // If we add a new shape, this will error
-      const _exhaustive: never = shape
-      throw new Error(`Unknown shape: ${_exhaustive}`)
-  }
-}
-```
-
-### void vs undefined
-
-```typescript
-// void: Function doesn't return anything meaningful
-function log(message: string): void {
-  console.log(message)
-}
-
-// undefined: Explicit undefined value
-function findUser(id: string): User | undefined {
-  return users.get(id)
-}
-```

package/skills/vercel-ai-sdk/SKILL.md

@@ -1,48 +0,0 @@
----
-name: vercel-ai-sdk
-description: |
-  Vercel AI SDK best practices and patterns. Use when building AI applications with React/Next.js and `@ai-sdk/react`, `@ai-sdk/core`, or `@ai-sdk/ui`. Covers `useChat`, `streamText`, `generateObject`, tool calling, and streaming architectures. SECURITY: Never pass raw user inputs to executable tools without strict Zod schema validation.
----
-
-# Vercel AI SDK Guidelines
-
-The Vercel AI SDK is the de facto standard for building streaming AI applications in TypeScript and React.
-
-## 1. Core API (`@ai-sdk/core`)
-
-- **Text Generation**: Use `streamText` for any user-facing chat or text response to minimize perceived latency. Only use `generateText` for background tasks where the user is not waiting for a real-time response.
-- **Structured Outputs**: Use `streamObject` or `generateObject` paired with Zod schemas to guarantee type-safe JSON outputs. Never prompt the model manually to "return JSON".
-- **Tool Calling**: Define tools using the `tool()` helper with strict Zod schemas.
-
-```typescript
-import { streamText, tool } from 'ai'
-import { z } from 'zod'
-
-const result = streamText({
-  model: myModel,
-  messages,
-  tools: {
-    weather: tool({
-      description: 'Get the weather in a location',
-      parameters: z.object({ location: z.string() }),
-      execute: async ({ location }) => fetchWeather(location),
-    }),
-  },
-})
-```
-
-## 2. UI Hooks (`@ai-sdk/react`)
-
-- **`useChat`**: The primary hook for conversational interfaces. It automatically manages message history, streaming state, and tool invocations.
-- **Error Handling**: Implement the `onError` callback in `useChat` to gracefully handle API rate limits or network failures.
-- **Data Streaming**: Use the `data` property exported from `useChat` to stream auxiliary data (like tool execution metadata or citations) alongside the main text stream.
-
-## 3. Server Actions & Next.js Integration
-
-- **App Router**: When using Next.js App Router, implement Route Handlers (`app/api/chat/route.ts`) that return `result.toDataStreamResponse()` for seamless streaming to `useChat`.
-- **RSC (React Server Components)**: For generative UI, use the `ai/rsc` module to stream React components directly from the server to the client.
-
-## 4. Security & Safety
-
-- **Rate Limiting**: Always apply rate limiting to your chat endpoints, as LLM APIs are expensive and vulnerable to abuse.
-- **Provider API Keys**: Ensure `OPENAI_API_KEY` (or equivalent) is strictly kept server-side. Never expose these keys to the client.

package/skills/vitest-standard/SKILL.md

@@ -1,76 +0,0 @@
----
-name: vitest-standard
-description: |
-  Comprehensive unit testing expertise covering Vitest, test-driven 
-  development (TDD), mocking strategies, and production-grade best practices. 
-  Activates ONLY for unit testing scope (unit tests, integration tests, Vitest, TDD, Red-Green-Refactor, mocking, 
-  stubbing, spying, test coverage, and test architecture in TypeScript/Node projects). NOT for E2E testing (use Playwright).
-  If the user asks to "write tests" without specifying the type, you MUST ask "Unit, E2E, or both?" before proceeding.
----
-
-# Vitest Standard
-
-This skill provides opinionated, production-tested guidance for high-integrity unit testing with Vitest. It emphasizes behavior-driven design, strictly isolated tests, and the TDD lifecycle.
-
-## Golden Rules (Mandatory)
-
-1.  **Test Behavior, Not Implementation** — Assert what the code _does_, not how it _looks_ internally.
-2.  **Strict Isolation** — NO shared state between tests. Create new instances in `beforeEach`.
-3.  **Clean Mocks** — Use `vi.clearAllMocks()` in `beforeEach` to prevent call history leaks.
-4.  **No Magic Numbers** — Use descriptive variables for expected values.
-5.  **AAA Pattern** — Every test must follow Arrange-Act-Assert.
-6.  **Async/Await** — Always await promises; use `rejects.toThrow()` for error paths.
-7.  **Deterministic Tests** — No dependence on system time, environment variables, or randomness (mock them).
-8.  **Meaningful Names** — Use `it('should [action] when [condition]')` or Given-When-Then.
-9.  **Mock at Boundaries** — Mock external APIs, databases, and third-party SDKs; test your own logic.
-10. **Red-Green-Refactor** — Prefer writing tests before code to drive API design.
-11. **Security** — Use fake/mock credentials in all tests — never real API keys, tokens, or passwords. Load sensitive test config from `.env.test.local` (gitignored).
-
-## Core Patterns
-
-### AAA (Arrange-Act-Assert)
-
-```typescript
-it('should calculate total price', () => {
-  // Arrange: Setup data and environment
-  const cart = new ShoppingCart()
-  cart.addItem({ price: 10, quantity: 2 })
-
-  // Act: Execute the method being tested
-  const total = cart.getTotal()
-
-  // Assert: Verify the outcome
-  expect(total).toBe(20)
-})
-```
-
-### Mocking Example
-
-```typescript
-import { vi, it, expect } from 'vitest'
-
-it('mocks dependencies', () => {
-  const mockFn = vi.fn().mockReturnValue(42)
-  expect(mockFn()).toBe(42)
-  expect(mockFn).toHaveBeenCalledOnce()
-})
-```
-
-## Quick Reference: Assertions
-
-See **[assertions.md](references/assertions.md)** for a full list of Vitest assertions (`toBe`, `toEqual`, `toThrow`, etc.). This reference is auto-loaded only when writing test assertions.
-
----
-
-## Specialized References (Load On-Demand)
-
-| Scenario                     | Reference File                                              |
-| :--------------------------- | :---------------------------------------------------------- |
-| **Mocking & Doubles**        | [mocking.md](references/mocking.md)                         |
-| **Async & Error Handling**   | [async-and-errors.md](references/async-and-errors.md)       |
-| **Coverage & Configuration** | [coverage-and-config.md](references/coverage-and-config.md) |
-| **TDD Cycle**                | [tdd-patterns.md](references/tdd-patterns.md)               |
-
-## Example: TDD Calculator
-
-See [tdd-calculator.ts](examples/tdd-calculator.ts) for the Red-Green-Refactor workflow.

package/skills/vitest-standard/examples/service-mock.ts

@@ -1,60 +0,0 @@
-import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
-
-// Intercept external module
-vi.mock('./api', () => ({
-    fetchUser: vi.fn(),
-    updateUser: vi.fn(),
-}))
-
-// Mock instance for Dependency Injection
-const mockDb = {
-    save: vi.fn().mockResolvedValue({ id: '123' }),
-    delete: vi.fn().mockResolvedValue(true),
-}
-
-describe('UserService', () => {
-    let service: UserService
-
-    beforeEach(() => {
-        service = new UserService(mockDb as any)
-        vi.clearAllMocks() // Clear call history between tests
-    })
-
-    afterEach(() => {
-        vi.restoreAllMocks() // Restore spies/intercepted methods
-    })
-
-    it('should save user to database', async () => {
-        // Arrange
-        const user = { name: 'John Doe' }
-
-        // Act
-        const result = await service.saveUser(user)
-
-        // Assert
-        expect(mockDb.save).toHaveBeenCalledOnce()
-        expect(mockDb.save).toHaveBeenCalledWith(user)
-        expect(result.id).toBe('123')
-    })
-
-    it('should throw error for invalid id', async () => {
-        // Arrange
-        mockDb.save.mockRejectedValueOnce(new Error('Invalid ID'))
-
-        // Act & Assert (Async Error Path)
-        await expect(service.saveUser({ name: '' })).rejects.toThrow('Invalid ID')
-    })
-})
-
-class UserService {
-    constructor(private db: Database) {}
-    async saveUser(user: any) {
-        return this.db.save(user)
-    }
-}
-
-class Database {
-    async save(user: any): Promise<any> {
-        return { id: '' }
-    }
-}

package/skills/vitest-standard/examples/tdd-calculator.ts

@@ -1,41 +0,0 @@
-import { describe, it, expect } from 'vitest'
-
-// 1. RED: Write a failing test first
-describe('Calculator', () => {
-    it('should add numbers', () => {
-        const calc = new Calculator()
-        expect(calc.add(2, 3)).toBe(5)
-    })
-
-    it('should multiply numbers', () => {
-        const calc = new Calculator()
-        expect(calc.multiply(2, 3)).toBe(6)
-    })
-})
-
-// 2. GREEN: Minimal implementations
-class Calculator {
-    // Red -> Green -> Refactor cycle
-    add(a: number, b: number): number {
-        return a + b
-    }
-
-    // Next iteration:
-    multiply(a: number, b: number): number {
-        return a * b
-    }
-}
-
-// 3. REFACTOR (Example):
-class ImprovedCalculator {
-    // Drive the add method with any number of parameters
-    add(...numbers: number[]): number {
-        return numbers.reduce((sum, n) => sum + n, 0)
-    }
-}
-
-// 4. Test the refactored version
-it('should add multiple numbers in ImprovedCalculator', () => {
-    const calc = new ImprovedCalculator()
-    expect(calc.add(1, 2, 3, 4)).toBe(10)
-})