feat: implement incident response playbook with tests and docs

[zainabb-dev]

Overview

This PR implements the incident response playbook for the backend by adding responder-facing runbooks for outage triage, recovery, and postmortems. It introduces a dedicated incident-response module, exposes API endpoints for listing and retrieving runbooks, and documents the operational/security guidance in the repository.

Related Issue

Closes #100

Changes

⚙️ Incident Response Implementation

• [ADD] src/incidentResponse.data.ts

  • Added the canonical runbook data for:
    • api-outage
    • data-integrity
    • security-breach
  • Included triage, recovery, postmortem, and security guidance for each runbook.

• [ADD] src/incidentResponse.service.ts

  • Added runbook lookup and listing logic.
  • Added runbook ID validation to reject malformed identifiers.
  • Returned defensive copies so consumers cannot mutate in-memory runbook data.

• [ADD] src/incidentResponse.types.ts

  • Added structured TypeScript types for runbook summaries and full runbooks.

• [ADD] src/incidentResponse.routes.ts

  • Added GET /api/v1/incident-response
  • Added GET /api/v1/incident-response/:runbookId
  • Added 400 handling for invalid runbook IDs.
  • Added 404 handling for unknown runbooks.

🧩 App Structure

• [ADD] src/app.ts

  • Extracted Express app creation into a reusable factory for integration testing.
  • Registered the new incident-response routes alongside existing API routes.

• [MODIFY] src/index.ts

  • Refactored server startup to use the shared app factory.
  • Exported app and startServer for testability while preserving runtime behavior.

✅ Tests

• [ADD] src/app.test.ts

  • Added integration tests for:
    • /health
    • /api/v1/contracts
    • incident-response catalog endpoint
    • incident-response detail endpoint
    • invalid ID handling
    • unknown runbook handling

• [ADD] src/incidentResponse.service.test.ts

  • Added unit tests for:
    • runbook listing
    • normalized lookup behavior
    • defensive copy behavior
    • invalid ID rejection
    • missing runbook handling

• [ADD] src/index.test.ts

  • Added bootstrap tests for exported app/server startup behavior.

• [REMOVE] src/health.test.ts

  • Removed the placeholder test and replaced it with meaningful route coverage.

📚 Documentation

• [MODIFY] README.md

  • Added incident-response endpoint documentation.
  • Added security notes.
  • Added coverage test command for reviewers.

• [ADD] docs/backend/incident-response-playbook.md

  • Added reviewer-focused backend documentation for the runbooks, scope, review guidance, and security constraints.

📦 Dependencies

• [MODIFY] package.json
  • Added supertest
  • Added @types/supertest

Verification Results

Acceptance Criteria	Status
Incident response runbooks for outage triage, recovery, and postmortems are implemented	✅
API exposes runbook summaries and detailed runbook retrieval	✅
Malformed/unsafe runbook identifiers are rejected	✅
Tests cover unit and integration scenarios for impacted modules	✅
Repository documentation updated for reviewers and maintainers	✅
Build completes successfully	✅
Coverage for changed surface meets/exceeds requested threshold	✅

How to Test

# 1. Confirm you're on the branch
git branch --show-current

# 2. Install dependencies
npm install

# 3. Run the full test suite with coverage
npm test -- --coverage

# 4. Verify the project builds
npm run build

# 5. Optional: inspect the changed files
git diff -- README.md docs/backend src package.json package-lock.json

Security Notes

• Runbook identifiers are restricted to lowercase letters, numbers, and hyphens to prevent malformed/path-style lookups.
• Recovery guidance explicitly avoids bypassing authentication, rate limiting, or audit controls.
• Security-sensitive and data-integrity incidents include evidence-preservation and least-privilege recovery expectations.
• Runbook content is versioned in-repo so operational guidance stays reviewable and auditable.

Screenshots

✅ Test suite with coverage passes

A screenshot of:

npm test -- --coverage

✅ Build passes

A screenshot of:

npm run build

[drips-wave]

@zainabb-dev Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits