Feature/quest persistence

[Kaycee276]

Description

This PR implements persistent file-based storage for the gamification quest system, resolving an issue where agent progress and quest claims were lost on every server restart/deploy (Closes #187 ). It ensures that quest data remains durable using atomic write patterns (similar to the x402 receipt store).

Changes Made

• Atomic File Persistence (quest-persistence.ts):

  • Replaced the global __openStellarQuestStore__ and __openStellarQuestCompletions__ in-memory structures with disk reads/writes to /.data/quest-progress.json.
  • Implemented atomic filesystem operations (writeFileSync to a .tmp extension followed by renameSync to the final .json path) to prevent partial file corruption if the process crashes mid-write.

• Daily Auto-Reset Mechanism:

  • Added a lastResetDate key to the schema.
  • Automatically clears daily scoped quests from the active StoredQuest lists the first time the file is read after midnight UTC.

• Idempotent Time-Bound Claim Tracking (quest-completions.ts):

  • QuestCompletionRecord now stores the claimedAt timestamp and questType.
  • hasClaimedQuest dynamically determines if the quest was completed within the current reset cycle (today for daily, this week for weekly) preventing agents from double-dipping, while avoiding deletion of historical completion records.

• Quest History Endpoint:

  • Added a new GET /api/quests/[agentId]/history endpoint.
  • Returns paginated history (page, pageSize), returning up to the last 30 completed quests sorted descending by claim time, seamlessly hydrated against static QUEST_DEFINITIONS and actively tracked subtasks.

• Comprehensive Testing:

  • Created lib/gamification/__tests__/quest-persistence.test.ts.
  • Thoroughly tests process restarts by mocking node:fs and running isolated in-memory clears.
  • Validates correct renameSync atomic flows and strict UTC midnight time boundary resets using fake timers.

Acceptance Criteria Met

• Quest progress survives a server restart
• History endpoint returns paginated results
• Atomic write pattern used (no partial-file corruption on crash)
• No in-memory fallback that hides write failures

[sonarqubecloud]

Quality Gate passed

Issues
7 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud