@vibe-interviewing/scenarios 0.1.0 → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 vibe-interviewing contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -4,9 +4,11 @@ Built-in interview scenarios for [vibe-interviewing](https://github.com/cpaczek/
 
 ## Available Scenarios
 
-| Scenario                | Difficulty | Time    | Description                                                                      |
-| ----------------------- | ---------- | ------- | -------------------------------------------------------------------------------- |
-| `rate-limiter-boundary` | Medium     | ~30-45m | Off-by-one in express-rate-limit's sliding window lets one extra request through |
+| Scenario                   | Type     | Difficulty | Time    | Description                                             |
+| -------------------------- | -------- | ---------- | ------- | ------------------------------------------------------- |
+| `patch-data-loss`          | Debug    | Hard       | ~30-45m | PATCH requests silently drop fields from records        |
+| `storage-adapter-refactor` | Refactor | Medium     | ~45-60m | Refactor tightly-coupled storage for pluggable backends |
+| `webhook-notifications`    | Feature  | Hard       | ~45-60m | Build a webhook notification system for a REST API      |
 
 ## Creating Custom Scenarios
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vibe-interviewing/scenarios",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Built-in interview scenarios for vibe-interviewing",
   "type": "module",
   "main": "./index.js",
@@ -9,13 +9,15 @@
     "index.js",
     "index.d.ts",
     "registry.yaml",
-    "rate-limiter-boundary/"
+    "patch-data-loss/",
+    "storage-adapter-refactor/",
+    "webhook-notifications/"
   ],
-  "scripts": {},
   "license": "MIT",
   "repository": {
     "type": "git",
     "url": "https://github.com/cpaczek/vibe-interviewing.git",
     "directory": "packages/scenarios"
-  }
-}
+  },
+  "scripts": {}
+}

package/patch-data-loss/scenario.yaml

@@ -0,0 +1,127 @@
+name: patch-data-loss
+description: 'PATCH requests silently drop fields from records'
+type: debug
+difficulty: hard
+estimated_time: '30-45m'
+tags:
+  - node
+  - rest-api
+  - json-server
+  - data-integrity
+
+repo: 'https://github.com/typicode/json-server'
+commit: '6ad7562b6aba175bec616d342e1319e8dbbad1af'
+
+setup:
+  - 'npm install'
+
+patch:
+  # Replace the fixture data with richer records so field loss is observable
+  - file: 'fixtures/db.json'
+    find: |
+      {
+        "posts": [
+          { "id": "1", "title": "a title" },
+          { "id": "2", "title": "another title" }
+        ],
+        "comments": [
+          { "id": "1", "text": "a comment about post 1", "postId": "1" },
+          { "id": "2", "text": "another comment about post 1", "postId": "1" }
+        ],
+        "profile": {
+          "name": "typicode"
+        }
+      }
+    replace: |
+      {
+        "products": [
+          { "id": "1", "name": "Wireless Headphones", "price": 79.99, "category": "electronics", "description": "Noise-cancelling over-ear headphones", "inStock": true, "rating": 4.5 },
+          { "id": "2", "name": "Running Shoes", "price": 129.99, "category": "footwear", "description": "Lightweight trail running shoes", "inStock": true, "rating": 4.2 },
+          { "id": "3", "name": "Coffee Maker", "price": 49.99, "category": "kitchen", "description": "12-cup programmable coffee maker", "inStock": false, "rating": 3.8 },
+          { "id": "4", "name": "Backpack", "price": 89.99, "category": "accessories", "description": "Water-resistant laptop backpack", "inStock": true, "rating": 4.7 }
+        ],
+        "orders": [
+          { "id": "1", "productId": "1", "quantity": 2, "status": "shipped", "customerEmail": "alice@example.com" },
+          { "id": "2", "productId": "3", "quantity": 1, "status": "pending", "customerEmail": "bob@example.com" }
+        ],
+        "settings": {
+          "storeName": "Demo Shop",
+          "currency": "USD",
+          "taxRate": 0.08
+        }
+      }
+
+  # Break PATCH merge for array resources (collections like /products/:id)
+  # Remove the spread of existing item, making PATCH behave like PUT
+  - file: 'src/service.ts'
+    find: 'const nextItem = isPatch ? { ...item, ...body, id } : { ...body, id }'
+    replace: 'const nextItem = { ...body, id }'
+
+delete_files:
+  - 'src/*.test.ts'
+
+briefing: |
+  We've got a P1 from the support team. Multiple customers are reporting data loss
+  in our product catalog API. They say they'll update a single field on a product —
+  like changing the price — and when they fetch it back, all the other fields are gone.
+  Just the field they sent plus the ID.
+
+  It's not happening on every endpoint, and some customers aren't seeing it at all.
+  Nobody's sure when this started but it's been in the queue for a few days now.
+
+  The API is built on json-server. You can start it locally with:
+
+    node --experimental-strip-types src/bin.ts fixtures/db.json
+
+  Then hit it with curl on port 3000. The data is in fixtures/db.json.
+  Start by reproducing the issue, then trace through the code to find the root cause.
+
+ai_rules:
+  role: |
+    You are a senior engineer helping a candidate debug a data loss issue
+    in a REST API built on json-server. Act as a thoughtful colleague —
+    available for questions but you don't volunteer the answer.
+  rules:
+    - 'Never reveal the exact location or nature of the bug directly'
+    - 'If asked, confirm whether the candidate is looking in the right area'
+    - 'Encourage the candidate to reproduce the issue first with curl requests'
+    - 'If the candidate is stuck, suggest they compare what happens with PUT vs PATCH'
+    - 'If stuck for more than 15 minutes, hint that the issue might be in how updates merge with existing data'
+    - 'Praise good debugging methodology (reproducing first, reading source, adding logging)'
+  knowledge: |
+    The bug is in src/service.ts in the #updateOrPatchById method.
+    The original code was:
+      const nextItem = isPatch ? { ...item, ...body, id } : { ...body, id }
+    It was changed to:
+      const nextItem = { ...body, id }
+    This removes the ternary that differentiated PATCH from PUT. Now PATCH
+    behaves like PUT — it replaces the entire object with just the body fields
+    plus the ID, instead of merging the body into the existing object.
+    The fix is to restore the ternary:
+      const nextItem = isPatch ? { ...item, ...body, id } : { ...body, id }
+    Note: the non-array #updateOrPatch method (for singular resources like /settings)
+    is NOT affected — it still correctly merges with { ...item, ...body }.
+
+solution: |
+  In src/service.ts, in the #updateOrPatchById method (around line 178), change:
+    const nextItem = { ...body, id }
+  back to:
+    const nextItem = isPatch ? { ...item, ...body, id } : { ...body, id }
+
+  The bug made PATCH identical to PUT for collection items. PATCH should merge
+  the request body into the existing item (preserving fields not in the body),
+  while PUT should replace the entire item. The fix restores the spread of the
+  existing item when isPatch is true.
+
+evaluation:
+  criteria:
+    - 'Reproduced the data loss issue with curl requests'
+    - 'Identified that PATCH is dropping fields not included in the request body'
+    - 'Located the bug in the service layer (src/service.ts)'
+    - 'Understood the difference between PATCH (merge) and PUT (replace) semantics'
+    - 'Applied the correct fix restoring the merge behavior'
+    - 'Verified the fix works by re-testing with curl'
+    - 'Used AI effectively as a debugging partner'
+  expected_fix: 'Restore the ternary in #updateOrPatchById: isPatch ? { ...item, ...body, id } : { ...body, id }'
+
+license: MIT

package/registry.yaml

@@ -1,7 +1,19 @@
 scenarios:
-  - name: rate-limiter-boundary
-    description: "Off-by-one in express-rate-limit's sliding window lets one extra request through"
-    difficulty: medium
+  - name: patch-data-loss
+    description: 'PATCH requests silently drop fields from records'
+    difficulty: hard
     estimated_time: '30-45m'
-    repo: 'https://github.com/express-rate-limit/express-rate-limit'
-    commit: '4e8b18bf972eff2890ed67bd11d8a08a2c6502d5'
+    repo: 'https://github.com/typicode/json-server'
+    commit: '6ad7562b6aba175bec616d342e1319e8dbbad1af'
+  - name: storage-adapter-refactor
+    description: 'Refactor tightly-coupled storage layer to support pluggable backends'
+    difficulty: medium
+    estimated_time: '45-60m'
+    repo: 'https://github.com/typicode/json-server'
+    commit: '6ad7562b6aba175bec616d342e1319e8dbbad1af'
+  - name: webhook-notifications
+    description: 'Build a webhook notification system for a REST API'
+    difficulty: hard
+    estimated_time: '45-60m'
+    repo: 'https://github.com/typicode/json-server'
+    commit: '6ad7562b6aba175bec616d342e1319e8dbbad1af'

package/storage-adapter-refactor/scenario.yaml

@@ -0,0 +1,84 @@
+name: storage-adapter-refactor
+description: 'Refactor tightly-coupled storage layer to support pluggable backends'
+type: refactor
+difficulty: medium
+estimated_time: '45-60m'
+tags:
+  - node
+  - rest-api
+  - json-server
+  - architecture
+  - design-patterns
+
+repo: 'https://github.com/typicode/json-server'
+commit: '6ad7562b6aba175bec616d342e1319e8dbbad1af'
+
+setup:
+  - 'npm install'
+
+delete_files:
+  - 'src/*.test.ts'
+
+briefing: |
+  We're turning json-server into a more flexible tool. Right now the entire data
+  layer is hardcoded to lowdb — the Service class directly imports and uses Low<Data>,
+  reads/writes through this.#db.data, and calls this.#db.write(). This coupling means
+  anyone who wants to use a different storage backend (in-memory for tests, SQLite for
+  persistence, Redis for shared state) has to fork the whole thing.
+
+  Your job: refactor the data layer so storage is pluggable. Define a clean storage
+  interface, wrap the existing lowdb usage in an adapter that implements it, and
+  refactor the Service class to depend on the interface instead of lowdb directly.
+  Then create an in-memory adapter as a second implementation to prove the
+  interface works.
+
+  The server runs locally:
+
+    node --experimental-strip-types src/bin.ts fixtures/db.json
+
+  Make sure the server still works exactly the same with the JSON file adapter
+  after your refactoring. You can test with curl on port 3000.
+
+ai_rules:
+  role: |
+    You are a senior engineer helping a candidate refactor a storage layer.
+    Guide them on design decisions but don't dictate the architecture.
+  rules:
+    - 'Let the candidate drive the interface design — there are multiple valid approaches'
+    - 'If asked, discuss trade-offs between different abstraction levels'
+    - 'Encourage them to keep the interface minimal — only what Service actually needs'
+    - 'Suggest they start by identifying all the places Service touches the database'
+    - 'If they over-engineer (too many methods, complex generics), gently suggest simplifying'
+    - 'Remind them to verify the server still works after each refactoring step'
+  knowledge: |
+    The Service class in src/service.ts directly depends on Low<Data> from lowdb.
+    It accesses data through this.#db.data (a Record<string, Item[] | Item>) and
+    persists changes with this.#db.write(). The key coupling points are:
+    - Constructor takes Low<Data>
+    - #get reads from this.#db.data[name]
+    - create/update/patch/destroy all call this.#db.write() after mutations
+    - The embed/nullifyForeignKey/deleteDependents functions also access db.data
+
+    A good refactoring would:
+    1. Define a StorageAdapter interface with methods like get(name), set(name, data), write()
+    2. Create a LowdbAdapter that wraps the current Low<Data> behavior
+    3. Create an InMemoryAdapter that stores data in a plain object
+    4. Update Service to accept StorageAdapter instead of Low<Data>
+    5. Update app.ts/bin.ts to create the adapter and pass it through
+
+    The candidate should notice that the helper functions (embed, nullifyForeignKey,
+    deleteDependents) also access db.data directly, which is a design decision —
+    either move them into Service or make them work through the adapter.
+
+evaluation:
+  criteria:
+    - 'Identified all coupling points between Service and lowdb'
+    - 'Designed a clean, minimal storage interface'
+    - 'Implemented a lowdb adapter that preserves existing behavior'
+    - 'Implemented an in-memory adapter'
+    - 'Refactored Service to use the interface instead of lowdb directly'
+    - 'Server still works correctly after refactoring (verified with curl)'
+    - 'Made thoughtful design decisions about abstraction level'
+    - 'Used AI effectively as an architecture partner'
+
+license: MIT

package/webhook-notifications/scenario.yaml

@@ -0,0 +1,128 @@
+name: webhook-notifications
+description: 'Build a webhook notification system for a REST API'
+type: feature
+difficulty: hard
+estimated_time: '45-60m'
+tags:
+  - node
+  - rest-api
+  - json-server
+  - webhooks
+  - event-driven
+
+repo: 'https://github.com/typicode/json-server'
+commit: '6ad7562b6aba175bec616d342e1319e8dbbad1af'
+
+setup:
+  - 'npm install'
+
+patch:
+  # Replace fixture data with richer records for more interesting webhook payloads
+  - file: 'fixtures/db.json'
+    find: |
+      {
+        "posts": [
+          { "id": "1", "title": "a title" },
+          { "id": "2", "title": "another title" }
+        ],
+        "comments": [
+          { "id": "1", "text": "a comment about post 1", "postId": "1" },
+          { "id": "2", "text": "another comment about post 1", "postId": "1" }
+        ],
+        "profile": {
+          "name": "typicode"
+        }
+      }
+    replace: |
+      {
+        "products": [
+          { "id": "1", "name": "Wireless Headphones", "price": 79.99, "category": "electronics", "inStock": true },
+          { "id": "2", "name": "Running Shoes", "price": 129.99, "category": "footwear", "inStock": true },
+          { "id": "3", "name": "Coffee Maker", "price": 49.99, "category": "kitchen", "inStock": false }
+        ],
+        "orders": [
+          { "id": "1", "productId": "1", "quantity": 2, "status": "shipped" },
+          { "id": "2", "productId": "3", "quantity": 1, "status": "pending" }
+        ],
+        "webhooks": []
+      }
+
+delete_files:
+  - 'src/*.test.ts'
+
+briefing: |
+  We need to add webhook support to our product catalog API so that external
+  integrations can react to changes in real time. Right now if a third-party system
+  wants to know when a product is updated or an order is created, they have to poll.
+
+  Build a webhook notification system:
+
+  1. Clients register webhooks by POSTing to /webhooks with a URL and optional
+     event filter (e.g., only notify on "products" changes)
+  2. When any resource is created, updated, or deleted, the server sends a POST
+     request to all matching registered webhook URLs
+  3. Clients can list their webhooks (GET /webhooks) and delete them (DELETE /webhooks/:id)
+
+  The webhook payload should include what happened: the event type (create/update/delete),
+  which resource, and the affected data.
+
+  The server runs locally:
+
+    node --experimental-strip-types src/bin.ts fixtures/db.json
+
+  Test with curl on port 3000. You can use a simple listener (like a second
+  HTTP server or a request-catching service) to verify webhook delivery.
+
+acceptance_criteria:
+  - 'POST /webhooks with { "url": "...", "resource": "products" } registers a webhook'
+  - 'POST /webhooks with { "url": "..." } (no resource filter) registers for all events'
+  - 'GET /webhooks returns all registered webhooks'
+  - 'DELETE /webhooks/:id removes a webhook'
+  - 'When a resource is created (POST /products), matching webhooks receive a notification'
+  - 'When a resource is updated (PUT or PATCH /products/:id), matching webhooks receive a notification'
+  - 'When a resource is deleted (DELETE /products/:id), matching webhooks receive a notification'
+  - 'Webhook payload includes: event type, resource name, affected data, and timestamp'
+  - 'Failed webhook deliveries do not crash the server or block the API response'
+  - 'Existing CRUD endpoints still work correctly'
+
+ai_rules:
+  role: |
+    You are a senior engineer helping a candidate build a webhook notification
+    system. Guide their design decisions but let them drive the implementation.
+  rules:
+    - 'Help the candidate understand the existing codebase structure when asked'
+    - 'If asked about design choices, discuss trade-offs (sync vs async delivery, retry strategies, etc.)'
+    - 'Encourage starting with the simplest working implementation, then iterating'
+    - 'Suggest they write a small test listener to verify webhook delivery'
+    - 'If they get bogged down in edge cases (retries, backoff, ordering), redirect to core functionality first'
+    - 'Praise clean integration with the existing codebase patterns'
+  knowledge: |
+    The json-server codebase has a clean separation:
+    - src/app.ts defines routes and delegates to Service
+    - src/service.ts handles CRUD logic with lowdb
+    - The "webhooks" array is already seeded in db.json as an empty array
+
+    A good implementation would:
+    1. Use the existing Service class to manage webhook registrations (CRUD on /webhooks)
+       — json-server already handles any resource in db.json, so GET/POST/DELETE /webhooks
+       works out of the box. The candidate might realize this or build custom handlers.
+    2. Add middleware or post-response hooks in app.ts that fire after mutations
+    3. Use fetch() to deliver webhook payloads asynchronously (fire-and-forget)
+    4. Structure the payload as: { event: "create"|"update"|"delete", resource: "products", data: {...}, timestamp: "..." }
+
+    Key insight: since "webhooks" is already a resource in db.json, the candidate
+    gets CRUD for webhook registrations for free via json-server's existing routing.
+    They just need to add the notification delivery logic.
+
+evaluation:
+  criteria:
+    - 'Webhook registration works (create, list, delete)'
+    - 'Notifications are delivered on create, update, and delete operations'
+    - 'Webhook payload contains event type, resource, data, and timestamp'
+    - 'Resource filtering works (webhooks can subscribe to specific resources)'
+    - 'Failed deliveries are handled gracefully (no crashes, no blocking)'
+    - 'Clean integration with existing codebase patterns'
+    - 'Tested end-to-end with a webhook listener'
+    - 'Used AI effectively as a development partner'
+
+license: MIT

package/rate-limiter-boundary/scenario.yaml

@@ -1,71 +0,0 @@
-name: rate-limiter-boundary
-description: "Off-by-one in express-rate-limit's sliding window lets one extra request through"
-difficulty: medium
-estimated_time: '30-45m'
-tags:
-  - node
-  - express
-  - middleware
-  - rate-limiting
-  - off-by-one
-
-repo: 'https://github.com/express-rate-limit/express-rate-limit'
-commit: '4e8b18bf972eff2890ed67bd11d8a08a2c6502d5'
-
-setup:
-  - 'npm install --ignore-scripts'
-
-patch:
-  - file: 'source/rate-limit.ts'
-    find: 'if (totalHits > limit) {'
-    replace: 'if (totalHits > limit + 1) {'
-
-briefing: |
-  Hey — we're getting reports from a few customers that our rate limiting isn't working correctly. They're saying they can make one more request than the configured limit before getting a 429.
-
-  For example, if the limit is set to 5, clients can make 6 successful requests before being blocked. It's not a huge deal but it's inconsistent and a couple of enterprise customers have flagged it in their security audits.
-
-  We're using express-rate-limit. I've already cloned the repo and set it up locally — can you dig into the source and figure out what's going on?
-
-  To run the tests: `npx jest --no-coverage`
-
-  The main source is in `source/` and tests are in `test/library/`. Good luck!
-
-ai_rules:
-  role: |
-    You are a senior engineer helping a candidate debug an off-by-one error
-    in the express-rate-limit middleware. Act as a patient but not overly
-    helpful colleague — you're available for questions but you don't
-    volunteer the answer.
-  rules:
-    - 'Never reveal the exact location or nature of the bug directly'
-    - 'If asked, confirm whether the candidate is looking in the right area'
-    - 'Encourage the candidate to write or run tests to reproduce the issue'
-    - 'If the candidate is stuck for more than 10 minutes, suggest looking at where totalHits is compared to the limit'
-    - 'Praise good debugging methodology (reading tests, adding logging, bisecting)'
-  knowledge: |
-    The bug is on line 507 of source/rate-limit.ts. The comparison
-    `if (totalHits > limit)` was changed to `if (totalHits > limit + 1)`.
-    This means the rate limiter allows limit+1 requests instead of limit
-    requests before returning 429. The fix is to change it back to
-    `if (totalHits > limit)`.
-
-solution: |
-  In source/rate-limit.ts line 507, change:
-    `if (totalHits > limit + 1) {`
-  back to:
-    `if (totalHits > limit) {`
-
-  The off-by-one was introduced by adding `+ 1` to the limit comparison,
-  allowing one extra request through before rate limiting kicks in.
-
-evaluation:
-  criteria:
-    - 'Identified the bug location in source/rate-limit.ts'
-    - 'Understood the off-by-one nature of the bug'
-    - 'Used tests or manual testing to reproduce the issue'
-    - 'Applied the correct fix'
-    - 'Used AI effectively as a debugging partner'
-  expected_fix: 'Change `totalHits > limit + 1` back to `totalHits > limit`'
-
-license: MIT