codecruise 0.1.0

package/config/skills/package-dev/SKILL.md

@@ -0,0 +1,498 @@
+---
+name: package-dev
+description: NPM package development patterns. Use when building libraries, SDKs, or reusable packages.
+---
+
+# Package Development Skill
+
+Standards for building production-grade NPM packages.
+
+## Package.json Structure
+
+```json
+{
+  "name": "@scope/package-name",
+  "version": "1.0.0",
+  "description": "Clear, concise description",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint .",
+    "prepublishOnly": "npm run build && npm run test && npm run typecheck"
+  },
+  "peerDependencies": {},
+  "dependencies": {},
+  "devDependencies": {}
+}
+```
+
+## API Surface Control
+
+### Minimal Exports
+
+Only export what consumers need:
+
+```typescript
+// src/index.ts
+
+// Public API - explicitly exported
+export { createClient } from './client';
+export { configure } from './config';
+export type { ClientOptions, Config } from './types';
+
+// Internal - NOT exported
+// - src/internal/parser.ts
+// - src/utils/helpers.ts
+```
+
+### No Accidental Public APIs
+
+```typescript
+// BAD - leaky abstraction
+export class Client {
+  public internalCache: Map<string, unknown>; // Exposed implementation detail
+
+  public _parseResponse(data: unknown) { // Internal method exposed
+    // ...
+  }
+}
+
+// GOOD - controlled API
+export class Client {
+  private cache: Map<string, unknown>;
+
+  private parseResponse(data: unknown) {
+    // ...
+  }
+
+  // Only public methods are part of API
+  public async fetch(url: string): Promise<Response> {
+    // ...
+  }
+}
+```
+
+### Barrel Files
+
+```typescript
+// src/index.ts - single entry point
+export * from './client';
+export * from './types';
+
+// src/client/index.ts - submodule barrel
+export { Client } from './client';
+export { createClient } from './factory';
+// Don't export: ./internal.ts, ./helpers.ts
+```
+
+## Dependency Management
+
+### Required vs Dev Dependencies
+
+| Category | Classification | Examples |
+|----------|---------------|----------|
+| Runtime requirement | `dependencies` | zod, axios |
+| Build tool | `devDependencies` | typescript, tsup |
+| Test framework | `devDependencies` | vitest, jest |
+| Linting | `devDependencies` | eslint, prettier |
+| Type definitions | `devDependencies` | @types/* |
+
+### Peer Dependencies
+
+Use for:
+- Frameworks the consumer must provide (React, Vue)
+- Packages that must be shared (avoiding duplicate instances)
+
+```json
+{
+  "peerDependencies": {
+    "react": "^18.0.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  }
+}
+```
+
+### Dependency Checklist
+
+Before adding any dependency:
+
+- [ ] Is it actively maintained? (commits in last 6 months)
+- [ ] Is it production-tested? (> 10k weekly downloads)
+- [ ] What's the bundle size impact? (use bundlephobia.com)
+- [ ] Are there security advisories?
+- [ ] Can we implement it ourselves in < 50 lines?
+- [ ] Is it tree-shakeable?
+
+### No Bloated Dependencies
+
+```typescript
+// BAD - pulling in huge library for one function
+import _ from 'lodash'; // 70KB
+const result = _.debounce(fn, 100);
+
+// GOOD - use native or small focused package
+import debounce from 'just-debounce-it'; // 0.3KB
+const result = debounce(fn, 100);
+
+// BETTER - implement simple utilities
+function debounce<T extends (...args: unknown[]) => unknown>(
+  fn: T,
+  ms: number
+): T {
+  let timeoutId: ReturnType<typeof setTimeout>;
+  return ((...args) => {
+    clearTimeout(timeoutId);
+    timeoutId = setTimeout(() => fn(...args), ms);
+  }) as T;
+}
+```
+
+## Bundle Optimization
+
+### Tree-Shaking
+
+```typescript
+// tsconfig.json
+{
+  "compilerOptions": {
+    "module": "ESNext",
+    "moduleResolution": "bundler"
+  }
+}
+
+// package.json
+{
+  "sideEffects": false
+}
+```
+
+### Named Exports Only
+
+```typescript
+// BAD - prevents tree-shaking
+export default {
+  createClient,
+  configure,
+  parseResponse,
+};
+
+// GOOD - enables tree-shaking
+export { createClient };
+export { configure };
+export { parseResponse };
+```
+
+### Code Splitting
+
+```typescript
+// Heavy functionality in separate entry point
+// package.json
+{
+  "exports": {
+    ".": "./dist/index.js",
+    "./heavy": "./dist/heavy.js"
+  }
+}
+
+// Consumer only imports what they need
+import { createClient } from '@scope/package';
+import { heavyOperation } from '@scope/package/heavy'; // Only when needed
+```
+
+### Bundle Size Budget
+
+Track in CI:
+
+```yaml
+# .github/workflows/bundle.yml
+- name: Check bundle size
+  run: |
+    npm run build
+    size=$(du -sb dist | cut -f1)
+    if [ $size -gt 50000 ]; then
+      echo "Bundle size $size exceeds 50KB limit"
+      exit 1
+    fi
+```
+
+## Versioning & Breaking Changes
+
+### Semver Compliance
+
+| Change Type | Version Bump | Example |
+|-------------|--------------|---------|
+| Bug fix | PATCH (0.0.X) | Fix null handling |
+| New feature (backward compatible) | MINOR (0.X.0) | Add new method |
+| Breaking change | MAJOR (X.0.0) | Remove/rename API |
+
+### Breaking Change Checklist
+
+Before making a breaking change:
+
+- [ ] Document in CHANGELOG.md
+- [ ] Provide migration guide
+- [ ] Consider deprecation period first
+- [ ] Update all examples and docs
+- [ ] Communicate in release notes
+
+### Deprecation Pattern
+
+```typescript
+/**
+ * @deprecated Use `newMethod` instead. Will be removed in v3.0.0.
+ */
+export function oldMethod(options: OldOptions): void {
+  console.warn(
+    'Deprecation warning: oldMethod is deprecated. ' +
+    'Use newMethod instead. This will be removed in v3.0.0.'
+  );
+
+  // Convert to new API internally
+  return newMethod(convertOptions(options));
+}
+
+export function newMethod(options: NewOptions): void {
+  // New implementation
+}
+```
+
+## Error Handling
+
+### Custom Error Classes
+
+```typescript
+export class PackageError extends Error {
+  constructor(
+    public code: string,
+    message: string,
+    public cause?: Error
+  ) {
+    super(message);
+    this.name = 'PackageError';
+  }
+}
+
+export class ConfigurationError extends PackageError {
+  constructor(message: string, cause?: Error) {
+    super('CONFIGURATION_ERROR', message, cause);
+    this.name = 'ConfigurationError';
+  }
+}
+
+export class NetworkError extends PackageError {
+  constructor(message: string, cause?: Error) {
+    super('NETWORK_ERROR', message, cause);
+    this.name = 'NetworkError';
+  }
+}
+```
+
+### Error Messages
+
+```typescript
+// BAD - unhelpful
+throw new Error('Invalid config');
+
+// GOOD - actionable
+throw new ConfigurationError(
+  `Invalid configuration: 'timeout' must be a positive number, received ${typeof timeout}. ` +
+  `See https://pkg.example.com/docs/config for valid options.`
+);
+```
+
+## TypeScript Patterns
+
+### Strict Types
+
+```typescript
+// tsconfig.json
+{
+  "compilerOptions": {
+    "strict": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true
+  }
+}
+```
+
+### Generic Constraints
+
+```typescript
+// Flexible but type-safe
+export function createStore<T extends Record<string, unknown>>(
+  initial: T
+): Store<T> {
+  // ...
+}
+
+// Consumer gets full type inference
+const store = createStore({ count: 0, name: 'test' });
+store.get('count'); // number
+store.get('name');  // string
+```
+
+### Overloads for Better DX
+
+```typescript
+// Multiple signatures for different use cases
+export function configure(options: FullOptions): Client;
+export function configure(apiKey: string): Client;
+export function configure(optionsOrKey: FullOptions | string): Client {
+  const options = typeof optionsOrKey === 'string'
+    ? { apiKey: optionsOrKey }
+    : optionsOrKey;
+
+  return new Client(options);
+}
+```
+
+## Testing
+
+### Test Public API Only
+
+```typescript
+// BAD - testing internals
+import { parseInternalFormat } from '../src/internal/parser';
+test('parseInternalFormat handles edge case', () => {
+  // Testing implementation detail
+});
+
+// GOOD - testing public behavior
+import { createClient } from '../src';
+test('client handles malformed response gracefully', () => {
+  const client = createClient({ apiKey: 'test' });
+  // Test observable behavior
+});
+```
+
+### Compatibility Tests
+
+```typescript
+// Test against multiple Node versions in CI
+// Test ESM and CJS imports work
+test('ESM import works', async () => {
+  const pkg = await import('../dist/index.js');
+  expect(pkg.createClient).toBeDefined();
+});
+
+test('CJS require works', () => {
+  const pkg = require('../dist/index.cjs');
+  expect(pkg.createClient).toBeDefined();
+});
+```
+
+## Documentation
+
+### README Structure
+
+```markdown
+# Package Name
+
+Brief description (1 sentence).
+
+## Installation
+
+\`\`\`bash
+npm install @scope/package
+\`\`\`
+
+## Quick Start
+
+\`\`\`typescript
+import { createClient } from '@scope/package';
+
+const client = createClient({ apiKey: 'xxx' });
+const result = await client.fetch('/endpoint');
+\`\`\`
+
+## API Reference
+
+### createClient(options)
+
+Creates a new client instance.
+
+**Parameters:**
+- `options.apiKey` (string, required) - Your API key
+- `options.timeout` (number, optional) - Request timeout in ms. Default: 5000
+
+**Returns:** `Client` instance
+
+**Example:**
+\`\`\`typescript
+const client = createClient({
+  apiKey: process.env.API_KEY,
+  timeout: 10000,
+});
+\`\`\`
+
+## License
+
+MIT
+```
+
+### JSDoc for Public APIs
+
+```typescript
+/**
+ * Creates a configured client instance.
+ *
+ * @param options - Configuration options
+ * @returns Configured client ready for use
+ *
+ * @example
+ * ```typescript
+ * const client = createClient({ apiKey: 'xxx' });
+ * ```
+ *
+ * @throws {ConfigurationError} If options are invalid
+ */
+export function createClient(options: ClientOptions): Client {
+  // ...
+}
+```
+
+## Publishing Checklist
+
+Before `npm publish`:
+
+- [ ] Version bumped appropriately (semver)
+- [ ] CHANGELOG.md updated
+- [ ] All tests pass
+- [ ] TypeScript compiles without errors
+- [ ] Bundle size within budget
+- [ ] `npm audit` shows no vulnerabilities
+- [ ] README is accurate and up-to-date
+- [ ] Examples work with new version
+- [ ] Breaking changes documented with migration guide
+- [ ] `files` field in package.json is correct
+- [ ] No sensitive files in published package