@vue-skuilder/db 0.1.18 → 0.1.21

package/docs/todo-strategy-state-storage.md

@@ -1,278 +0,0 @@
-# TODO: Strategy-Specific State Storage in UserDB
-
-## Status: NOT STARTED
-
-## Goal
-
-Enable NavigationStrategies (ContentNavigators) to persist their own state data in the
-user's database, allowing strategies to maintain context across sessions.
-
-## Current State
-
-### What Strategies Can Read
-
-| Data | Method | Notes |
-|------|--------|-------|
-| User's global ELO | `user.getCourseRegDoc(courseId).elo.global` | ✅ Available |
-| User's per-tag ELO | `user.getCourseRegDoc(courseId).elo.tags` | ✅ Available |
-| Seen cards | `user.getSeenCards(courseId)` | ✅ Card IDs only |
-| Active cards | `user.getActiveCards()` | ✅ Available |
-| Pending reviews | `user.getPendingReviews(courseId)` | ✅ ScheduledCard objects |
-| Card history | `user.putCardRecord()` returns `CardHistory` | 🟡 Only after write |
-
-### What Strategies Cannot Do
-
-- **Store arbitrary state**: No namespaced storage for strategy-specific data
-- **Track temporal patterns**: No easy way to record "when did I last introduce tag X?"
-- **Persist learning context**: Strategy state is lost between sessions
-
-## Use Cases
-
-### 1. InterferenceMitigator
-
-**Need**: Track when interfering concepts were last introduced together.
-
-```typescript
-// Desired: Store last introduction time per tag
-{
-  "lastIntroduction": {
-    "letter-b": "2024-01-15T10:30:00Z",
-    "letter-d": "2024-01-16T14:20:00Z"
-  }
-}
-```
-
-### 2. Minimal Pairs Strategy (Future)
-
-**Need**: Track discrimination training progress between confusable pairs.
-
-```typescript
-// Desired: Store discrimination scores per pair
-{
-  "pairScores": {
-    "b-d": { "correct": 15, "total": 20, "lastPracticed": "..." },
-    "m-n": { "correct": 8, "total": 10, "lastPracticed": "..." }
-  }
-}
-```
-
-### 3. Adaptive Pacing Strategy (Future)
-
-**Need**: Track user's engagement patterns and optimal session timing.
-
-```typescript
-// Desired: Store engagement metrics
-{
-  "sessionMetrics": {
-    "avgAccuracyByTimeOfDay": { "morning": 0.85, "afternoon": 0.78 },
-    "optimalSessionLength": 180,  // seconds
-    "fatigueThreshold": 12        // cards before accuracy drops
-  }
-}
-```
-
-## Proposed Solutions
-
-### Option A: Extend CourseRegistration
-
-Add a `strategyState` field to the existing `CourseRegistration` document.
-
-**Schema:**
-```typescript
-interface CourseRegistration {
-  // ... existing fields ...
-  
-  /**
-   * Strategy-specific state, keyed by strategy ID or type.
-   * Each strategy owns its own namespace.
-   */
-  strategyState?: {
-    [strategyKey: string]: unknown;
-  };
-}
-```
-
-**Pros:**
-- No new document types
-- Lives alongside other course-specific user data
-- Already synced via existing mechanisms
-
-**Cons:**
-- Potential for large documents if strategies store lots of data
-- All strategies share one document (contention on updates)
-
----
-
-### Option B: Separate Strategy State Documents
-
-Create a new document type for strategy state.
-
-**Schema:**
-```typescript
-interface StrategyStateDoc {
-  _id: `STRATEGY_STATE-${courseId}-${strategyKey}`;
-  docType: DocType.STRATEGY_STATE;
-  courseId: string;
-  strategyKey: string;  // e.g., "interferenceMitigator" or strategy instance ID
-  data: unknown;
-  updatedAt: string;
-}
-```
-
-**Pros:**
-- Clean separation
-- No document size concerns
-- Independent updates (no contention)
-
-**Cons:**
-- New document type to manage
-- More queries to fetch state
-
----
-
-### Option C: Generic Key-Value Store in UserDB
-
-Add generic methods for namespaced storage.
-
-**Interface:**
-```typescript
-interface UserDBWriter {
-  // ... existing methods ...
-  
-  /**
-   * Store data in a namespaced location.
-   * @param namespace - Unique namespace (e.g., "strategy:interferenceMitigator:course123")
-   * @param data - Arbitrary JSON-serializable data
-   */
-  putNamespacedData(namespace: string, data: unknown): Promise<void>;
-  
-  /**
-   * Retrieve namespaced data.
-   * @param namespace - The namespace to retrieve
-   * @returns The stored data, or null if not found
-   */
-  getNamespacedData<T>(namespace: string): Promise<T | null>;
-  
-  /**
-   * Delete namespaced data.
-   * @param namespace - The namespace to delete
-   */
-  deleteNamespacedData(namespace: string): Promise<void>;
-}
-```
-
-**Pros:**
-- Most flexible
-- Reusable beyond strategies
-- Clean API
-
-**Cons:**
-- Very generic (might be too permissive)
-- Namespace collision risk
-
----
-
-## Recommended Approach
-
-**Option B (Separate Documents)** with a convenience wrapper:
-
-```typescript
-// In ContentNavigator base class or a mixin
-abstract class ContentNavigator {
-  // ... existing methods ...
-  
-  /**
-   * Get this strategy's persisted state for the current course.
-   */
-  protected async getStrategyState<T>(): Promise<T | null> {
-    const key = `STRATEGY_STATE-${this.course.getCourseID()}-${this.strategyKey}`;
-    try {
-      return await this.user.get<T>(key);
-    } catch (e) {
-      return null;  // Not found
-    }
-  }
-  
-  /**
-   * Persist this strategy's state for the current course.
-   */
-  protected async putStrategyState<T>(data: T): Promise<void> {
-    const key = `STRATEGY_STATE-${this.course.getCourseID()}-${this.strategyKey}`;
-    const existing = await this.getStrategyState<T>();
-    await this.user.put({
-      _id: key,
-      _rev: existing?._rev,
-      docType: DocType.STRATEGY_STATE,
-      courseId: this.course.getCourseID(),
-      strategyKey: this.strategyKey,
-      data,
-      updatedAt: new Date().toISOString(),
-    });
-  }
-  
-  /**
-   * Unique key for this strategy instance.
-   * Override in subclasses if multiple instances need separate state.
-   */
-  protected get strategyKey(): string {
-    return this.constructor.name;  // e.g., "InterferenceMitigatorNavigator"
-  }
-}
-```
-
-## Implementation Plan
-
-### Phase 1: Add DocType and Interface
-
-1. Add `STRATEGY_STATE` to `DocType` enum in `packages/db/src/core/types/types-legacy.ts`
-2. Define `StrategyStateDoc` interface
-3. Add prefix to `DocTypePrefixes`
-
-### Phase 2: Add UserDB Methods
-
-1. Add `getStrategyState()` and `putStrategyState()` to `UserDBInterface`
-2. Implement in `CouchUserDB`
-
-### Phase 3: Add ContentNavigator Helpers
-
-1. Add protected helper methods to `ContentNavigator` base class
-2. Document usage pattern
-
-### Phase 4: Update Strategies
-
-1. Update `InterferenceMitigatorNavigator` to use state storage
-2. Add tests for state persistence
-
-## Files to Create/Modify
-
-| File | Action | Description |
-|------|--------|-------------|
-| `packages/db/src/core/types/types-legacy.ts` | MODIFY | Add STRATEGY_STATE DocType |
-| `packages/db/src/core/types/strategyState.ts` | CREATE | StrategyStateDoc interface |
-| `packages/db/src/core/interfaces/userDB.ts` | MODIFY | Add state storage methods |
-| `packages/db/src/impl/couch/userDB.ts` | MODIFY | Implement state storage |
-| `packages/db/src/core/navigators/index.ts` | MODIFY | Add helper methods to base class |
-| `packages/db/src/core/navigators/interferenceMitigator.ts` | MODIFY | Use state storage |
-
-## Test Cases
-
-1. **Store and retrieve**: Write state, read it back, verify equality
-2. **Update existing**: Write state, update it, verify new value
-3. **Separate namespaces**: Two strategies store data, each gets their own
-4. **Cross-session persistence**: Store state, simulate new session, verify data persists
-5. **Missing state**: Read state that doesn't exist, get null (not error)
-
-## Open Questions
-
-1. **State migration**: How to handle strategy state when strategy config changes?
-2. **State cleanup**: When a strategy is deleted, should its state be cleaned up?
-3. **State size limits**: Should we enforce maximum state size?
-4. **Sync behavior**: How does state sync across devices for multi-device users?
-
-## Related Files
-
-- `packages/db/src/core/interfaces/userDB.ts` — UserDB interface
-- `packages/db/src/impl/couch/userDB.ts` — UserDB implementation
-- `packages/db/src/core/navigators/index.ts` — ContentNavigator base class
-- `packages/db/src/core/types/types-legacy.ts` — DocType enum
-- `packages/db/docs/navigators-architecture.md` — Architecture overview

package/src/core/navigators/hardcodedOrder.ts

@@ -1,163 +0,0 @@
-import type {
-  CourseDBInterface,
-  QualifiedCardID,
-  StudySessionNewItem,
-  StudySessionReviewItem,
-  UserDBInterface,
-} from '..';
-import type { ContentNavigationStrategyData } from '../types/contentNavigationStrategy';
-import type { ScheduledCard } from '../types/user';
-import { ContentNavigator } from './index';
-import type { WeightedCard } from './index';
-import type { CardGenerator, GeneratorContext } from './generators/types';
-import { logger } from '../../util/logger';
-
-// ============================================================================
-// HARDCODED ORDER NAVIGATOR
-// ============================================================================
-//
-// A generator strategy that presents cards in a fixed, author-defined order.
-//
-// Use case: When course authors want explicit control over content sequencing,
-// e.g., teaching letters in a specific pedagogical order.
-//
-// The order is defined in serializedData as a JSON array of card IDs.
-// Earlier positions in the array get higher scores.
-//
-// ============================================================================
-
-/**
- * A navigation strategy that presents cards in a fixed order.
- *
- * Implements CardGenerator for use in Pipeline architecture.
- * Also extends ContentNavigator for backward compatibility with legacy code.
- *
- * Scoring:
- * - Earlier cards in the sequence get higher scores
- * - Reviews get score 1.0 (highest priority)
- * - New cards scored by position: 1.0 - (position / total) * 0.5
- */
-export default class HardcodedOrderNavigator extends ContentNavigator implements CardGenerator {
-  /** Human-readable name for CardGenerator interface */
-  name: string;
-
-  private orderedCardIds: string[] = [];
-
-  constructor(
-    user: UserDBInterface,
-    course: CourseDBInterface,
-    strategyData: ContentNavigationStrategyData
-  ) {
-    super(user, course, strategyData);
-    this.name = strategyData.name || 'Hardcoded Order';
-
-    if (strategyData.serializedData) {
-      try {
-        this.orderedCardIds = JSON.parse(strategyData.serializedData);
-      } catch (e) {
-        logger.error('Failed to parse serializedData for HardcodedOrderNavigator', e);
-      }
-    }
-  }
-
-  async getPendingReviews(): Promise<(StudySessionReviewItem & ScheduledCard)[]> {
-    const reviews = await this.user.getPendingReviews(this.course.getCourseID());
-    return reviews.map((r) => {
-      return {
-        ...r,
-        contentSourceType: 'course',
-        contentSourceID: this.course.getCourseID(),
-        cardID: r.cardId,
-        courseID: r.courseId,
-        reviewID: r._id,
-        status: 'review',
-      };
-    });
-  }
-
-  async getNewCards(limit: number = 99): Promise<StudySessionNewItem[]> {
-    const activeCardIds = (await this.user.getActiveCards()).map((c: QualifiedCardID) => c.cardID);
-
-    const newCardIds = this.orderedCardIds.filter((cardId) => !activeCardIds.includes(cardId));
-
-    const cardsToReturn = newCardIds.slice(0, limit);
-
-    return cardsToReturn.map((cardId) => {
-      return {
-        cardID: cardId,
-        courseID: this.course.getCourseID(),
-        contentSourceType: 'course',
-        contentSourceID: this.course.getCourseID(),
-        status: 'new',
-      };
-    });
-  }
-
-  /**
-   * Get cards in hardcoded order with scores based on position.
-   *
-   * Earlier cards in the sequence get higher scores.
-   * Score formula: 1.0 - (position / totalCards) * 0.5
-   * This ensures scores range from 1.0 (first card) to 0.5+ (last card).
-   *
-   * This method supports both the legacy signature (limit only) and the
-   * CardGenerator interface signature (limit, context).
-   *
-   * @param limit - Maximum number of cards to return
-   * @param _context - Optional GeneratorContext (currently unused, but required for interface)
-   */
-  async getWeightedCards(limit: number, _context?: GeneratorContext): Promise<WeightedCard[]> {
-    const activeCardIds = (await this.user.getActiveCards()).map((c: QualifiedCardID) => c.cardID);
-    const reviews = await this.getPendingReviews();
-
-    // Filter out already-active cards
-    const newCardIds = this.orderedCardIds.filter((cardId) => !activeCardIds.includes(cardId));
-
-    const totalCards = newCardIds.length;
-
-    // Score new cards by position in sequence
-    const scoredNew: WeightedCard[] = newCardIds.slice(0, limit).map((cardId, index) => {
-      const position = index + 1;
-      const score = Math.max(0.5, 1.0 - (index / totalCards) * 0.5);
-
-      return {
-        cardId,
-        courseId: this.course.getCourseID(),
-        score,
-        provenance: [
-          {
-            strategy: 'hardcodedOrder',
-            strategyName: this.strategyName || this.name,
-            strategyId: this.strategyId || 'NAVIGATION_STRATEGY-hardcoded',
-            action: 'generated',
-            score,
-            reason: `Position ${position} of ${totalCards} in fixed sequence, new card`,
-          },
-        ],
-      };
-    });
-
-    // Score reviews at 1.0 (highest priority)
-    const scoredReviews: WeightedCard[] = reviews.map((r) => ({
-      cardId: r.cardID,
-      courseId: r.courseID,
-      score: 1.0,
-      provenance: [
-        {
-          strategy: 'hardcodedOrder',
-          strategyName: this.strategyName || this.name,
-          strategyId: this.strategyId || 'NAVIGATION_STRATEGY-hardcoded',
-          action: 'generated',
-          score: 1.0,
-          reason: 'Scheduled review, highest priority',
-        },
-      ],
-    }));
-
-    // Combine (reviews already sorted at top due to score=1.0)
-    const all = [...scoredReviews, ...scoredNew];
-    all.sort((a, b) => b.score - a.score);
-
-    return all.slice(0, limit);
-  }
-}

package/src/util/tuiLogger.ts

@@ -1,139 +0,0 @@
-// TUI-aware logging utility that redirects logs to file in Node.js
-import * as fs from 'fs';
-import * as path from 'path';
-import { getAppDataDirectory } from './dataDirectory';
-
-let logFile: string | null = null;
-let isNodeEnvironment = false;
-
-/**
- * Initialize TUI logging - redirect console logs to file in Node.js
- */
-export function initializeTuiLogging(): void {
-  // Detect Node.js environment
-  isNodeEnvironment = typeof window === 'undefined' && typeof process !== 'undefined';
-  
-  if (!isNodeEnvironment) {
-    return; // Browser environment - keep normal console logging
-  }
-
-  try {
-    // Set up log file path
-    logFile = path.join(getAppDataDirectory(), 'lastrun.log');
-    
-    // Clear previous log file
-    if (fs.existsSync(logFile)) {
-      fs.unlinkSync(logFile);
-    }
-    
-    // Create initial log entry
-    const startTime = new Date().toISOString();
-    fs.writeFileSync(logFile, `=== TUI Session Started: ${startTime} ===\n`);
-    
-    // Redirect console methods to file
-    const originalConsole = {
-      // eslint-disable-next-line no-console
-      log: console.log,
-      // eslint-disable-next-line no-console
-      error: console.error,
-      // eslint-disable-next-line no-console
-      warn: console.warn,
-      // eslint-disable-next-line no-console
-      info: console.info
-    };
-    
-    const writeToLog = (level: string, args: any[]) => {
-      const timestamp = new Date().toISOString();
-      const message = args.map(arg => 
-        typeof arg === 'object' ? JSON.stringify(arg, null, 2) : String(arg)
-      ).join(' ');
-      
-      const logEntry = `[${timestamp}] ${level}: ${message}\n`;
-      
-      try {
-        fs.appendFileSync(logFile!, logEntry);
-      } catch (err) {
-        // Fallback to original console if file write fails
-        originalConsole.error('Failed to write to log file:', err);
-        originalConsole[level.toLowerCase() as keyof typeof originalConsole](...args);
-      }
-    };
-    
-    // Override console methods
-    // eslint-disable-next-line no-console
-    console.log = (...args) => writeToLog('INFO', args);
-    // eslint-disable-next-line no-console
-    console.info = (...args) => writeToLog('INFO', args);
-    // eslint-disable-next-line no-console
-    console.warn = (...args) => writeToLog('WARN', args);
-    // eslint-disable-next-line no-console
-    console.error = (...args) => writeToLog('ERROR', args);
-    
-    // Store original methods for potential restoration
-    (console as any)._originalMethods = originalConsole;
-    
-    // eslint-disable-next-line no-console
-    console.log('TUI logging initialized - logs redirected to', logFile);
-    
-  } catch (err) {
-    // eslint-disable-next-line no-console
-    console.error('Failed to initialize TUI logging:', err);
-  }
-}
-
-/**
- * Get the current log file path (for debugging)
- */
-export function getLogFilePath(): string | null {
-  return logFile;
-}
-
-/**
- * Show user-facing message (always visible in TUI)
- */
-export function showUserMessage(message: string): void {
-  if (isNodeEnvironment) {
-    // In Node.js, write directly to stdout to bypass log redirection
-    process.stdout.write(message + '\n');
-  } else {
-    // In browser, use normal console
-    // eslint-disable-next-line no-console
-    console.log(message);
-  }
-}
-
-/**
- * Show user-facing error (always visible in TUI)
- */
-export function showUserError(message: string): void {
-  if (isNodeEnvironment) {
-    // In Node.js, write directly to stderr to bypass log redirection
-    process.stderr.write('Error: ' + message + '\n');
-  } else {
-    // In browser, use normal console
-    // eslint-disable-next-line no-console
-    console.error(message);
-  }
-}
-
-/**
- * Logger object with standard log levels
- */
-export const logger = {
-  debug: (message: string, ...args: any[]) => {
-    // eslint-disable-next-line no-console
-    console.log(`[DEBUG] ${message}`, ...args);
-  },
-  info: (message: string, ...args: any[]) => {
-    // eslint-disable-next-line no-console
-    console.info(`[INFO] ${message}`, ...args);
-  },
-  warn: (message: string, ...args: any[]) => {
-    // eslint-disable-next-line no-console
-    console.warn(`[WARN] ${message}`, ...args);
-  },
-  error: (message: string, ...args: any[]) => {
-    // eslint-disable-next-line no-console
-    console.error(`[ERROR] ${message}`, ...args);
-  },
-};