fix: delete pages before versions to prevent foreign key constraint failure

[Copilot]

Problem

Users were unable to delete documentation versions through the web UI or API, encountering a FOREIGN KEY constraint failed error. The only workaround was to delete the entire Docker volume, which was far from ideal.

{"message":"Failed to remove docs mcp server: Failed to remove version caused by SqliteError: FOREIGN KEY constraint failed"}

Root Cause

The database schema has a hierarchical structure with foreign key relationships:

libraries → versions → pages → documents

Where:

• pages.version_id REFERENCES versions(id)
• documents.page_id REFERENCES pages(id)

When deleting a version, the code was executing deletions in the wrong order:

1. ✅ Delete documents
2. ❌ Delete version (fails because pages still reference the version via version_id)

The pages table was introduced in migration 009 to normalize page-level metadata, but the deletion logic wasn't updated to account for this new intermediate table.

Solution

Added a deletePages prepared statement and updated the removeVersion method to delete entities in the correct order to respect foreign key constraints:

1. Delete documents (removes FK constraint documents.page_id → pages.id)
2. Delete pages (new step - removes FK constraint pages.version_id → versions.id)
3. Delete version (now succeeds - removes FK constraint versions.library_id → libraries.id)
4. Delete library if no other versions remain

Changes

• Added deletePages prepared statement that deletes all pages for a given library and version
• Updated removeVersion method to call deletePages between document and version deletion
• Added inline comments documenting the deletion order and foreign key dependencies
• Added comprehensive test coverage for version deletion scenarios

Testing

• ✅ All 195 store-related tests pass
• ✅ Added 2 new test cases specifically validating the fix:
  • Complete version removal with library deletion
  • Partial version removal with library retention
• ✅ Manual integration test confirms the exact bug scenario is resolved
• ✅ Verified fix works through entire call stack: Web UI → RemoveTool → DocumentManagementService → DocumentStore

Impact

Users can now successfully delete documentation versions through the web UI and MCP tools without encountering foreign key constraint errors, eliminating the need to delete entire Docker volumes as a workaround.

Fixes #[issue_number]

Original prompt

---

This section details on the original issue you should resolve

<issue_title>bug: can't delete docs from the database</issue_title>
<issue_description>scraping and everything else looks like it functions okay. however, when i try to delete the a doc, i get:

{"message":"Failed to remove docs mcp server: Failed to remove version caused by SqliteError: FOREIGN KEY constraint failed"}

only way i can delete docs is if i delete the whole subvolume, which isn't ideal

nixos 25.11
running it in docker v28.4.0

not sure what other info to include

docker-compose:

services:
  docs-mcp-server:
    image: ghcr.io/arabold/docs-mcp-server:latest
    container_name: docs-mcp-server
    ports:
      - "6280:6280"
    volumes:
      - ./docs-mcp-data:/data
    environment:
      - DOCS_MCP_TELEMETRY=false
    command: ["--protocol", "http", "--host", "0.0.0.0", "--port", "6280"]
    restart: unless-stopped
```</issue_description>

<agent_instructions>We recently introduced "pages" as a parent structure that contains "chunks" or "documents" in our database. My assumption is that we might try to delete pages first before we delete the respective documents. 

It it crucial, however, to consider that documents and pages belong to specific _versions_ of a library. We cannot and must not delete by URI, as the same URI could exist across different versions and even different libraries. Make sure to consider the data structure before proposing any changes.</agent_instructions>

## Comments on the Issue (you are @copilot in this section)

<comments>
</comments>

Fixes #252

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

[github-actions]

🎉 This PR is included in version 1.26.2 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀