sdd-mcp-server 3.0.2 → 3.1.0

package/dist/cli/sdd-mcp-cli.js

@@ -10,6 +10,7 @@
  */
 import { main as installSkillsMain, mainInstall as installMain } from './install-skills.js';
 import { main as migrateKiroMain } from './migrate-kiro.js';
+import { main as migrateSteeringMain } from './migrate-steering.js';
 const HELP = `
 SDD MCP CLI
 
@@ -19,6 +20,7 @@ Commands:
   install           Install SDD skills AND steering documents (recommended)
   install-skills    Install SDD skills only (legacy)
   migrate-kiro      Migrate .kiro directory to .spec (v2.1.0+)
+  migrate-steering  Migrate steering docs to consolidated components (v3.1.0+)
 
 Options:
   --help, -h        Show this help message
@@ -32,6 +34,8 @@ Examples:
   npx sdd-mcp-server install-skills --list       # List available skills
   npx sdd-mcp-server migrate-kiro                # Migrate .kiro to .spec
   npx sdd-mcp-server migrate-kiro --dry-run      # Preview migration
+  npx sdd-mcp-server migrate-steering            # Migrate static steering docs
+  npx sdd-mcp-server migrate-steering --dry-run  # Preview steering migration
 
 Running without a command starts the MCP server (for IDE integrations).
 `;
@@ -58,6 +62,11 @@ async function main() {
             process.argv = [process.argv[0], process.argv[1], ...args.slice(1)];
             await migrateKiroMain();
             break;
+        case 'migrate-steering':
+            // Remove the command from args and pass the rest to migrate-steering
+            process.argv = [process.argv[0], process.argv[1], ...args.slice(1)];
+            await migrateSteeringMain();
+            break;
         default:
             console.error(`Unknown command: ${command}`);
             console.log(HELP);

package/dist/cli/sdd-mcp-cli.js.map

@@ -1 +1 @@
-{"version":3,"file":"sdd-mcp-cli.js","sourceRoot":"","sources":["../../src/cli/sdd-mcp-cli.ts"],"names":[],"mappings":";AAEA;;;;;;;;GAQG;AAEH,OAAO,EAAE,IAAI,IAAI,iBAAiB,EAAE,WAAW,IAAI,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAC5F,OAAO,EAAE,IAAI,IAAI,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAE5D,MAAM,IAAI,GAAG;;;;;;;;;;;;;;;;;;;;;;;;CAwBZ,CAAC;AAEF,KAAK,UAAU,IAAI;IACjB,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IACnC,MAAM,OAAO,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;IAExB,IAAI,CAAC,OAAO,IAAI,OAAO,KAAK,QAAQ,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;QACzD,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAClB,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IAED,QAAQ,OAAO,EAAE,CAAC;QAChB,KAAK,SAAS;YACZ,qDAAqD;YACrD,OAAO,CAAC,IAAI,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;YACpE,MAAM,WAAW,EAAE,CAAC;YACpB,MAAM;QAER,KAAK,gBAAgB;YACnB,8BAA8B;YAC9B,OAAO,CAAC,IAAI,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;YACpE,MAAM,iBAAiB,EAAE,CAAC;YAC1B,MAAM;QAER,KAAK,cAAc;YACjB,iEAAiE;YACjE,OAAO,CAAC,IAAI,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;YACpE,MAAM,eAAe,EAAE,CAAC;YACxB,MAAM;QAER;YACE,OAAO,CAAC,KAAK,CAAC,oBAAoB,OAAO,EAAE,CAAC,CAAC;YAC7C,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;YAClB,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACpB,CAAC;AACH,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;IACrB,OAAO,CAAC,KAAK,CAAC,QAAQ,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC;IACvC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}
+{"version":3,"file":"sdd-mcp-cli.js","sourceRoot":"","sources":["../../src/cli/sdd-mcp-cli.ts"],"names":[],"mappings":";AAEA;;;;;;;;GAQG;AAEH,OAAO,EAAE,IAAI,IAAI,iBAAiB,EAAE,WAAW,IAAI,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAC5F,OAAO,EAAE,IAAI,IAAI,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAC5D,OAAO,EAAE,IAAI,IAAI,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAEpE,MAAM,IAAI,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;CA2BZ,CAAC;AAEF,KAAK,UAAU,IAAI;IACjB,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IACnC,MAAM,OAAO,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;IAExB,IAAI,CAAC,OAAO,IAAI,OAAO,KAAK,QAAQ,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;QACzD,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAClB,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IAED,QAAQ,OAAO,EAAE,CAAC;QAChB,KAAK,SAAS;YACZ,qDAAqD;YACrD,OAAO,CAAC,IAAI,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;YACpE,MAAM,WAAW,EAAE,CAAC;YACpB,MAAM;QAER,KAAK,gBAAgB;YACnB,8BAA8B;YAC9B,OAAO,CAAC,IAAI,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;YACpE,MAAM,iBAAiB,EAAE,CAAC;YAC1B,MAAM;QAER,KAAK,cAAc;YACjB,iEAAiE;YACjE,OAAO,CAAC,IAAI,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;YACpE,MAAM,eAAe,EAAE,CAAC;YACxB,MAAM;QAER,KAAK,kBAAkB;YACrB,qEAAqE;YACrE,OAAO,CAAC,IAAI,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;YACpE,MAAM,mBAAmB,EAAE,CAAC;YAC5B,MAAM;QAER;YACE,OAAO,CAAC,KAAK,CAAC,oBAAoB,OAAO,EAAE,CAAC,CAAC;YAC7C,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;YAClB,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACpB,CAAC;AACH,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;IACrB,OAAO,CAAC,KAAK,CAAC,QAAQ,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC;IACvC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/hooks/post-tool-use/log-tool-execution.md

@@ -0,0 +1,51 @@
+---
+name: log-tool-execution
+description: Logs all tool executions for debugging and audit purposes
+event: post-tool-use
+priority: 50
+enabled: false
+---
+
+# Log Tool Execution Hook
+
+This hook logs all tool executions to a local log file for debugging and auditing.
+
+## Purpose
+
+- **Debugging** - Trace issues by reviewing tool invocation history
+- **Auditing** - Track what actions were taken during a session
+- **Learning** - Analyze patterns in tool usage over time
+
+## Log Format
+
+```
+[2024-01-15T10:30:00.000Z] TOOL_EXEC
+  tool: sdd-requirements
+  feature: user-authentication
+  duration: 1250ms
+  status: success
+  output_files:
+    - .spec/specs/user-authentication/requirements.md
+```
+
+## Log Location
+
+Logs are written to:
+- Default: `.sdd/logs/tool-execution.log`
+- Configurable via `SDD_LOG_PATH` environment variable
+
+## Configuration
+
+```yaml
+# In .sdd/config.yaml
+hooks:
+  log-tool-execution:
+    enabled: true
+    log_level: info  # debug, info, warn, error
+    max_log_size: 10MB
+    retain_days: 30
+```
+
+## Note
+
+This hook is disabled by default to avoid unnecessary disk I/O during normal development. Enable it when debugging or for compliance requirements.

package/hooks/post-tool-use/update-spec-status.md

@@ -0,0 +1,50 @@
+---
+name: update-spec-status
+description: Automatically updates spec.json status after SDD tool completion
+event: post-tool-use
+priority: 100
+enabled: true
+---
+
+# Update Spec Status Hook
+
+This hook automatically updates the spec.json file after SDD workflow tools complete successfully.
+
+## Trigger Conditions
+
+Triggered after these tools complete successfully:
+- `sdd-init` - Sets status to "initialized"
+- `sdd-requirements` - Sets requirements phase to "generated"
+- `sdd-approve requirements` - Sets requirements phase to "approved"
+- `sdd-design` - Sets design phase to "generated"
+- `sdd-approve design` - Sets design phase to "approved"
+- `sdd-tasks` - Sets tasks phase to "generated"
+- `sdd-approve tasks` - Sets tasks phase to "approved"
+- `sdd-implement` - Updates task completion status
+
+## Status Updates
+
+```json
+{
+  "workflow_status": {
+    "current_phase": "design",
+    "phases": {
+      "requirements": {
+        "status": "approved",
+        "completed_at": "2024-01-15T10:30:00Z"
+      },
+      "design": {
+        "status": "in_progress",
+        "started_at": "2024-01-15T11:00:00Z"
+      }
+    }
+  }
+}
+```
+
+## Benefits
+
+1. **Audit Trail** - Track when each phase was completed
+2. **Workflow Validation** - Enable pre-tool-use hooks to validate phase order
+3. **Progress Visibility** - Show current workflow status in sdd-status
+4. **Automation** - Enable CI/CD integration based on spec status

package/hooks/pre-tool-use/check-test-coverage.md

@@ -0,0 +1,51 @@
+---
+name: check-test-coverage
+description: Reminds developers to write tests first when implementing features
+event: pre-tool-use
+priority: 90
+enabled: true
+---
+
+# Check Test Coverage Hook
+
+This hook promotes TDD by reminding developers to write tests before implementation.
+
+## Trigger Conditions
+
+Triggered before code modification tools:
+- File writes to `src/**/*.ts` (excluding test files)
+- Code generation requests
+- Implementation-related tool calls
+
+## Validation Logic
+
+```
+IF modifying source file (not test file) THEN
+  CHECK if corresponding test file exists
+  IF no test file THEN
+    WARN about TDD best practice
+    SUGGEST creating test file first
+```
+
+## Example Prompt
+
+```
+🧪 TDD Reminder
+
+You're about to modify 'src/services/UserService.ts' but no
+corresponding test file was found.
+
+Consider creating 'src/__tests__/services/UserService.test.ts'
+first and writing failing tests for the expected behavior.
+
+TDD Flow:
+1. Write failing test (Red)
+2. Implement code to pass test (Green)
+3. Refactor for quality (Refactor)
+```
+
+## Configuration
+
+This hook can be configured via environment variables:
+- `SDD_TDD_STRICT=true` - Block modifications without tests
+- `SDD_TDD_REMINDER=true` - Show reminder but allow proceeding (default)

package/hooks/pre-tool-use/validate-sdd-workflow.md

@@ -0,0 +1,55 @@
+---
+name: validate-sdd-workflow
+description: Validates that SDD workflow phases are followed in correct order
+event: pre-tool-use
+priority: 100
+enabled: true
+---
+
+# Validate SDD Workflow Hook
+
+This hook validates that the SDD workflow phases are being followed correctly before tool invocation.
+
+## Trigger Conditions
+
+Triggered before these tools are invoked:
+- `sdd-design` (requires `sdd-requirements` to be completed first)
+- `sdd-tasks` (requires `sdd-design` to be completed first)
+- `sdd-implement` (requires `sdd-tasks` to be completed first)
+
+## Validation Logic
+
+```
+IF tool == 'sdd-design' THEN
+  CHECK that requirements.md exists and is approved
+  CHECK that spec.json shows requirements phase completed
+
+IF tool == 'sdd-tasks' THEN
+  CHECK that design.md exists and is approved
+  CHECK that spec.json shows design phase completed
+
+IF tool == 'sdd-implement' THEN
+  CHECK that tasks.md exists
+  CHECK that spec.json shows tasks phase completed
+```
+
+## On Validation Failure
+
+If validation fails:
+1. Display warning message explaining which phase is missing
+2. Suggest running the correct phase first
+3. Allow override with explicit `--skip-validation` flag
+
+## Example Warning
+
+```
+⚠️ SDD Workflow Violation
+
+You're attempting to run 'sdd-design' but the requirements phase
+has not been completed yet.
+
+Please run 'sdd-requirements' first to generate the requirements
+document, then have it reviewed and approved before proceeding.
+
+To skip this check: sdd-design --skip-validation
+```

package/hooks/session-end/remind-uncommitted-changes.md

@@ -0,0 +1,58 @@
+---
+name: remind-uncommitted-changes
+description: Reminds developer of uncommitted changes before ending session
+event: session-end
+priority: 90
+enabled: true
+---
+
+# Remind Uncommitted Changes Hook
+
+This hook checks for uncommitted changes and reminds the developer before the session ends.
+
+## Actions
+
+1. **Check Git Status**
+   - Detect uncommitted changes
+   - Identify untracked files
+   - Check for stashed changes
+
+2. **Display Warning**
+   ```
+   ⚠️ Uncommitted Changes Detected
+
+   You have changes that haven't been committed:
+
+   Modified:
+     • src/hooks/HookLoader.ts
+     • src/__tests__/hooks/HookLoader.test.ts
+
+   Untracked:
+     • hooks/pre-tool-use/validate-sdd-workflow.md
+
+   Consider committing your changes before ending the session.
+   Run: /sdd-commit to create a commit with proper message
+   ```
+
+3. **Suggest Actions**
+   - Offer to run commit command
+   - Show diff summary
+   - Remind about push to remote
+
+## Configuration
+
+```yaml
+# In .sdd/config.yaml
+hooks:
+  remind-uncommitted-changes:
+    enabled: true
+    include_untracked: true
+    warn_large_diff: true
+    large_diff_threshold: 500  # lines
+```
+
+## Benefits
+
+- **Prevent Lost Work** - Don't lose changes between sessions
+- **Clean State** - End sessions with clean working directory
+- **Team Sync** - Remind to push for team visibility

package/hooks/session-end/save-session-summary.md

@@ -0,0 +1,72 @@
+---
+name: save-session-summary
+description: Saves a summary of the session for continuity between sessions
+event: session-end
+priority: 100
+enabled: true
+---
+
+# Save Session Summary Hook
+
+This hook saves a summary of the session when it ends, enabling seamless continuity in future sessions.
+
+## What Gets Saved
+
+1. **Workflow Progress**
+   - Features worked on during session
+   - Phases completed
+   - Tasks implemented
+
+2. **Decisions Made**
+   - Architecture decisions
+   - Implementation choices
+   - Trade-offs considered
+
+3. **Context to Preserve**
+   - Current working state
+   - Pending items
+   - Blockers or questions
+
+## Summary Location
+
+```
+.spec/sessions/
+└── 2024-01-15T10-30-00Z.md
+```
+
+## Summary Format
+
+```markdown
+# Session Summary - 2024-01-15
+
+## Duration
+Started: 10:30 AM | Ended: 2:45 PM (4h 15m)
+
+## Features Worked On
+
+### plugin-architecture-v3
+- Completed: requirements phase approved
+- In Progress: design phase
+- Next: Complete component diagram
+
+### user-authentication
+- Implemented: Tasks 1.1, 1.2, 1.3
+- Tests: 12 new tests, all passing
+- Blockers: Need OAuth provider decision
+
+## Key Decisions
+1. Using BaseManager pattern for all component managers
+2. Hooks organized by event type in nested directories
+3. YAML frontmatter for all component metadata
+
+## Continuation Notes
+- Resume design.md at "Data Flow" section
+- Review OAuth options before next session
+- Run integration tests after completing design
+```
+
+## Benefits
+
+- **Seamless Continuity** - Start next session with full context
+- **Knowledge Preservation** - Decisions and context don't get lost
+- **Progress Tracking** - Clear record of work accomplished

package/hooks/session-start/load-project-context.md

@@ -0,0 +1,62 @@
+---
+name: load-project-context
+description: Loads project context and steering documents at session start
+event: session-start
+priority: 100
+enabled: true
+---
+
+# Load Project Context Hook
+
+This hook loads project-specific context and steering documents when a new session starts.
+
+## Actions
+
+1. **Detect Project Type**
+   - Check for `.spec/steering/` directory
+   - Identify project technology stack
+   - Load appropriate steering documents
+
+2. **Load Steering Documents**
+   ```
+   .spec/steering/
+   ├── PROJECT.md      # Project overview and conventions
+   ├── AGENTS.md       # Agent configuration
+   ├── ARCHITECTURE.md # System architecture
+   └── custom/         # Project-specific guides
+   ```
+
+3. **Restore Workflow State**
+   - Read `.spec/specs/*/spec.json` for active features
+   - Identify current phase for each feature
+   - Surface any incomplete workflows
+
+4. **Set Session Context**
+   - Configure AI persona based on active agent
+   - Apply relevant rules
+   - Activate appropriate context mode
+
+## Session Initialization Message
+
+```
+📋 Project Context Loaded
+
+Project: sdd-mcp
+Type: Node.js/TypeScript
+Active Features:
+  • plugin-architecture-v3 (design phase)
+  • user-authentication (implementation phase)
+
+Steering Documents:
+  ✓ PROJECT.md loaded
+  ✓ AGENTS.md loaded
+  ✓ 3 custom guides loaded
+
+Ready to continue. Run /sdd-status for full workflow state.
+```
+
+## Benefits
+
+- **Consistent Context** - Every session starts with full project understanding
+- **Workflow Continuity** - Pick up where you left off
+- **Best Practices** - Steering documents are always active

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sdd-mcp-server",
-  "version": "3.0.2",
+  "version": "3.1.0",
   "description": "MCP server for spec-driven development workflows across AI-agent CLIs and IDEs",
   "main": "dist/index.js",
   "bin": {
@@ -12,6 +12,10 @@
     "dist/**/*",
     "skills/**/*",
     "steering/**/*",
+    "rules/**/*",
+    "contexts/**/*",
+    "agents/**/*",
+    "hooks/**/*",
     "sdd-entry.js",
     "mcp-server.js",
     "atomicWrite.js",

package/rules/coding-style.md

@@ -0,0 +1,97 @@
+---
+name: coding-style
+description: Enforce consistent TypeScript/JavaScript coding conventions and design principles
+priority: 100
+alwaysActive: true
+---
+
+# Coding Style Rules
+
+## TypeScript/JavaScript Guidelines
+
+### Type Safety
+- Use explicit types for function parameters and return values
+- Avoid `any` type - use `unknown` or proper generics instead
+- Enable strict mode in TypeScript configuration
+
+### Naming Conventions
+- **Classes**: PascalCase (e.g., `UserService`)
+- **Functions/Methods**: camelCase (e.g., `getUserById`)
+- **Constants**: UPPER_SNAKE_CASE (e.g., `MAX_RETRIES`)
+- **Files**: kebab-case (e.g., `user-service.ts`)
+
+### Functions
+- Keep functions small and focused (single responsibility)
+- Limit function parameters to 3-4; use options object for more
+- Use early returns to reduce nesting
+
+### Code Organization
+- One class per file (with rare exceptions)
+- Keep files under 300 lines when possible
+- Write self-documenting code - minimize inline comments
+
+---
+
+# Core Design Principles
+
+**Golden Rule**: Always ask "Does this code follow SOLID, DRY, KISS, YAGNI?" before committing.
+
+## SOLID Principles
+
+### S - Single Responsibility Principle (SRP)
+A class/module should have one, and only one, reason to change.
+
+### O - Open/Closed Principle (OCP)
+Open for extension, closed for modification. Use interfaces/abstractions.
+
+### L - Liskov Substitution Principle (LSP)
+Derived classes must be substitutable for their base classes.
+
+### I - Interface Segregation Principle (ISP)
+No client should depend on methods it doesn't use. Keep interfaces small.
+
+### D - Dependency Inversion Principle (DIP)
+Depend on abstractions, not concrete implementations. Use dependency injection.
+
+## DRY (Don't Repeat Yourself)
+Every piece of knowledge should have a single, authoritative representation.
+
+## KISS (Keep It Simple)
+Simplicity should be a key goal. Avoid unnecessary complexity.
+
+## YAGNI (You Aren't Gonna Need It)
+Don't implement functionality until it's actually needed.
+
+---
+
+## Code Review Checklist
+
+### SOLID
+- [ ] Does each class/module have a single responsibility?
+- [ ] Can I extend functionality without modifying existing code?
+- [ ] Are interfaces small and focused?
+- [ ] Do dependencies point toward abstractions?
+
+### DRY
+- [ ] Is there any duplicated logic that should be extracted?
+- [ ] Are magic numbers/strings extracted to constants?
+
+### KISS
+- [ ] Is the solution as simple as possible?
+- [ ] Are variable/function names clear without comments?
+
+### YAGNI
+- [ ] Is every feature actually needed now?
+- [ ] Are there "future-proofing" additions that can be removed?
+
+---
+
+## Common Anti-Patterns to Avoid
+
+| Anti-Pattern | Violates | Fix |
+|--------------|----------|-----|
+| God Object/Class | SRP | Split into focused classes |
+| Copy-Paste Programming | DRY | Extract common logic |
+| Premature Optimization | KISS, YAGNI | Optimize when needed |
+| Long Parameter List | KISS | Use parameter objects |
+| Magic Numbers | DRY | Extract to named constants |

package/rules/error-handling.md

@@ -0,0 +1,134 @@
+---
+name: error-handling
+description: Error handling patterns and best practices
+priority: 90
+alwaysActive: true
+---
+
+# Error Handling Rules
+
+## Error Types
+
+### Custom Error Classes
+Define domain-specific errors for better handling:
+
+```typescript
+class ValidationError extends Error {
+  constructor(message: string, public field?: string) {
+    super(message);
+    this.name = 'ValidationError';
+  }
+}
+
+class NotFoundError extends Error {
+  constructor(resource: string, id: string) {
+    super(`${resource} with id "${id}" not found`);
+    this.name = 'NotFoundError';
+  }
+}
+
+class AuthorizationError extends Error {
+  constructor(action: string) {
+    super(`Not authorized to ${action}`);
+    this.name = 'AuthorizationError';
+  }
+}
+```
+
+## Error Handling Patterns
+
+### Try-Catch Best Practices
+```typescript
+// Good: Specific error handling
+try {
+  await saveUser(user);
+} catch (error) {
+  if (error instanceof ValidationError) {
+    return { status: 400, message: error.message };
+  }
+  if (error instanceof DuplicateError) {
+    return { status: 409, message: 'User already exists' };
+  }
+  // Re-throw unexpected errors
+  throw error;
+}
+
+// Bad: Swallowing all errors
+try {
+  await saveUser(user);
+} catch (error) {
+  console.log('Something went wrong');
+  // Error lost, no recovery, no logging
+}
+```
+
+### Async Error Handling
+```typescript
+// Always use try-catch with async/await
+async function fetchData(): Promise<Data> {
+  try {
+    const response = await fetch(url);
+    if (!response.ok) {
+      throw new HttpError(response.status, response.statusText);
+    }
+    return await response.json();
+  } catch (error) {
+    logger.error('Failed to fetch data', { error, url });
+    throw error;
+  }
+}
+```
+
+### Error Propagation
+- Let errors bubble up to appropriate handlers
+- Add context when re-throwing
+- Don't catch errors you can't handle
+
+```typescript
+// Good: Add context when re-throwing
+async function processOrder(orderId: string): Promise<void> {
+  try {
+    await validateOrder(orderId);
+    await chargePayment(orderId);
+    await fulfillOrder(orderId);
+  } catch (error) {
+    throw new OrderProcessingError(
+      `Failed to process order ${orderId}`,
+      { cause: error }
+    );
+  }
+}
+```
+
+## Logging Errors
+
+### What to Log
+- Error message and stack trace
+- Request/operation context
+- User identifier (not PII)
+- Timestamp
+
+### What NOT to Log
+- Passwords or tokens
+- Personal identifiable information (PII)
+- Full credit card numbers
+- Internal implementation details in production
+
+### Log Levels
+- **ERROR**: Unexpected failures requiring attention
+- **WARN**: Handled issues that may indicate problems
+- **INFO**: Normal operations, significant events
+- **DEBUG**: Detailed information for troubleshooting
+
+## User-Facing Errors
+
+### Never Expose
+- Stack traces
+- Database errors
+- Internal paths
+- Implementation details
+
+### Always Provide
+- Clear, actionable message
+- Error code for support reference
+- Next steps when possible