.cursorrules

# Cursor Rules for SDK Kit

## Project Context

SDK Kit is a TypeScript framework for building JavaScript SDKs with a functional plugin architecture inspired by JSTag3.

## Code Style & Conventions

### TypeScript
- Use strict TypeScript settings
- Prefer functional patterns over classes where appropriate
- Use explicit return types for public APIs
- Export types alongside implementations

### Plugin Architecture
- Plugins MUST be pure functions that receive (plugin, instance, config)
- Use capability injection (Plugin & Emitter & Defaulter)
- Always call plugin.ns() to set namespace
- Use plugin.expose() to add public APIs

### Naming Conventions
- Package names: `@lytics/sdk-kit-*`
- Plugin functions: `*Plugin` (e.g., `storagePlugin`)
- Internal classes: PascalCase (e.g., `EventEmitter`)
- Public APIs: camelCase (e.g., `sdk.init()`)

### File Organization
```
packages/core/src/
├── sdk.ts              # Main SDK class
├── types/              # Type definitions
├── capabilities/       # Capability implementations
├── util/               # Utilities
└── index.ts            # Public exports
```

## Testing
- Use Vitest for all tests
- Colocate tests with source: `*.test.ts`
- Mock external dependencies
- Test plugins in isolation

## Build & Development
- Use `pnpm` for package management
- Use Turborepo for builds
- TypeScript for compilation (not Vite for core packages)
- Biome for linting/formatting

## Key Principles

1. **Functional Plugins**: Plugins are functions, not classes
2. **Capability Injection**: Explicit dependencies via parameters
3. **Type Safety**: Full TypeScript coverage
4. **Tree-Shakeable**: Build-time plugin exclusion
5. **Zero Dependencies**: Core has no runtime dependencies

## Common Commands

```bash
pnpm build              # Build all packages
pnpm test               # Run all tests
pnpm lint               # Lint code
pnpm format             # Format code
pnpm -F "@lytics/sdk-kit" dev  # Watch mode for core
```

## Commit Conventions

Use Conventional Commits:
- `feat:` - New features
- `fix:` - Bug fixes
- `docs:` - Documentation
- `refactor:` - Code refactoring
- `test:` - Test changes
- `chore:` - Build/tooling changes

## Implementation Notes

### When implementing SDK core:
1. Start with types (Plugin, SDK, Config)
2. Implement capabilities (Emitter, Config, Lifecycle)
3. Build SDK class using capabilities
4. Add plugin registration (use method)
5. Test with mock plugins

### When implementing plugins:
1. Follow the plugin function signature
2. Set namespace first (plugin.ns())
3. Set defaults (plugin.defaults())
4. Expose public API (plugin.expose())
5. Listen to events (instance.on())
6. Document usage in JSDoc

## Reference Implementation

```typescript
// Good plugin example
export default function myPlugin(
  plugin: Plugin,
  instance: SDK,
  config: Config
) {
  plugin.ns('my.plugin');
  
  plugin.defaults({
    my: { setting: 'default' }
  });
  
  plugin.expose({
    myMethod() {
      const value = config.get('my.setting');
      plugin.emit('my:event', { value });
    }
  });
  
  instance.on('sdk:ready', () => {
    console.log('Plugin initialized');
  });
}
```

## Anti-Patterns to Avoid

- ❌ Don't use classes for plugins (use functions)
- ❌ Don't add runtime dependencies to core
- ❌ Don't expose internal implementation details
- ❌ Don't mutate config after init
- ❌ Don't use `any` types in public APIs

## Workflow

We follow a **spec-driven workflow**:
1. **Specs** define what to build (`specs/*/spec.md`, `plan.md`, `tasks.md`)
2. **GitHub issues** track progress
3. **Implementation** follows specs

See `WORKFLOW.md` for full process documentation.

## References

- `WORKFLOW.md` - Development process and workflow
- `specs/` - Feature specifications (source of truth)
- `ROADMAP.md` - High-level phases
- JSTag3 architecture (inspiration)
- Pathfora will be built on SDK Kit