@vue-skuilder/db 0.1.16 → 0.1.18

package/docs/todo-strategy-authoring.md

@@ -0,0 +1,401 @@
+# NavigationStrategy Authoring Tools
+
+## Status: UI COMPLETE ✅ (CLI/MCP Optional)
+
+## Goal
+
+Provide tools for course authors to create and configure NavigationStrategy documents
+without direct database manipulation. This includes UI components, CLI commands, and
+potentially MCP tools.
+
+**UI implementation completed.** CLI and MCP remain as optional future enhancements for
+scriptable/agent-based workflows.
+
+## Current State (Updated)
+
+### What Exists ✅
+
+| Component | Location | Status |
+|-----------|----------|--------|
+| `HardcodedOrderConfigForm.vue` | `packages/edit-ui/src/components/NavigationStrategy/` | ✅ Complete |
+| `HierarchyConfigForm.vue` | `packages/edit-ui/src/components/NavigationStrategy/` | ✅ Complete |
+| `InterferenceConfigForm.vue` | `packages/edit-ui/src/components/NavigationStrategy/` | ✅ Complete |
+| `RelativePriorityConfigForm.vue` | `packages/edit-ui/src/components/NavigationStrategy/` | ✅ Complete |
+| `NavigationStrategyEditor.vue` | `packages/edit-ui/src/components/NavigationStrategy/` | ✅ All strategy types supported |
+| `NavigationStrategyList.vue` | `packages/edit-ui/src/components/NavigationStrategy/` | ✅ Compact layout, edit/delete |
+| `CourseDB.addNavigationStrategy()` | `packages/db/src/impl/couch/courseDB.ts` | ✅ DB write method |
+| `CourseDB.updateNavigationStrategy()` | `packages/db/src/impl/couch/courseDB.ts` | ✅ DB update method |
+| `CourseDB.getAllNavigationStrategies()` | `packages/db/src/impl/couch/courseDB.ts` | ✅ DB read method |
+
+### What's Complete
+
+- ✅ UI forms for all four strategy types (Hardcoded, Hierarchy, Interference, RelativePriority)
+- ✅ Dual input modes (Visual Editor / JSON Editor) for each form
+- ✅ Tag loading from course database
+- ✅ Real-time validation with error messages
+- ✅ Edit functionality for existing strategies
+- ✅ Compact, non-modal two-column layout
+- ✅ Responsive design (desktop and mobile)
+- ✅ Full CRUD operations (Create, Read, Update, Delete)
+
+### What's Optional (Future Enhancements)
+
+- ⏸️ CLI commands for strategy creation (scriptable workflows)
+- ⏸️ MCP tools for agent-based authoring (LLM-guided config generation)
+- ⏸️ Strategy behavior preview/simulation
+
+## Strategy Types and Their Configs
+
+### 1. HierarchyDefinition
+
+```typescript
+interface HierarchyConfig {
+  prerequisites: {
+    [tagId: string]: TagPrerequisite[];
+  };
+  delegateStrategy?: string;  // default: "elo"
+}
+
+interface TagPrerequisite {
+  tag: string;
+  masteryThreshold?: {
+    minElo?: number;
+    minCount?: number;
+  };
+}
+```
+
+**Example:**
+```json
+{
+  "prerequisites": {
+    "cvc-words": [
+      { "tag": "letter-sounds", "masteryThreshold": { "minCount": 10, "minElo": 1050 } }
+    ],
+    "blends": [
+      { "tag": "cvc-words", "masteryThreshold": { "minCount": 20 } }
+    ]
+  },
+  "delegateStrategy": "elo"
+}
+```
+
+**UI Requirements:**
+- Tag selector (from course's available tags)
+- Prerequisite builder (tag → requires tags with thresholds)
+- Threshold inputs (minCount, minElo)
+- Delegate strategy selector
+
+---
+
+### 2. InterferenceMitigator
+
+```typescript
+interface InterferenceConfig {
+  interferenceSets: InterferenceGroup[];
+  maturityThreshold?: {
+    minCount?: number;
+    minElo?: number;
+    minElapsedDays?: number;
+  };
+  defaultDecay?: number;
+  delegateStrategy?: string;
+}
+
+interface InterferenceGroup {
+  tags: string[];
+  decay?: number;
+}
+```
+
+**Example:**
+```json
+{
+  "interferenceSets": [
+    { "tags": ["letter-b", "letter-d", "letter-p"], "decay": 0.9 },
+    { "tags": ["letter-m", "letter-n"], "decay": 0.7 }
+  ],
+  "maturityThreshold": { "minCount": 15, "minElapsedDays": 3 },
+  "defaultDecay": 0.8
+}
+```
+
+**UI Requirements:**
+- Interference group builder (add/remove groups)
+- Tag multi-selector for each group
+- Decay slider (0-1) per group
+- Maturity threshold inputs
+- Delegate strategy selector
+
+---
+
+### 3. RelativePriority
+
+```typescript
+interface RelativePriorityConfig {
+  tagPriorities: { [tagId: string]: number };
+  defaultPriority?: number;
+  combineMode?: 'max' | 'average' | 'min';
+  priorityInfluence?: number;
+  delegateStrategy?: string;
+}
+```
+
+**Example:**
+```json
+{
+  "tagPriorities": {
+    "letter-s": 0.95,
+    "letter-t": 0.90,
+    "letter-a": 0.88,
+    "letter-x": 0.10,
+    "letter-z": 0.05
+  },
+  "defaultPriority": 0.5,
+  "combineMode": "max",
+  "priorityInfluence": 0.5
+}
+```
+
+**UI Requirements:**
+- Tag list with priority sliders (0-1)
+- Default priority input
+- Combine mode selector (max/average/min)
+- Priority influence slider
+- Delegate strategy selector
+
+---
+
+## Implementation Options
+
+### Option A: Extend NavigationStrategyEditor.vue
+
+**Pros:**
+- Single location for all strategy editing
+- Consistent with existing UI patterns
+- User-facing, accessible to course authors
+
+**Cons:**
+- More complex Vue component
+- Requires form validation logic
+
+**Implementation:**
+1. Add strategy type selector dropdown
+2. Conditional rendering of config forms based on type
+3. Form validation before save
+4. Serialize config to `serializedData` JSON
+
+---
+
+### Option B: CLI Commands
+
+**Pros:**
+- Scriptable, automatable
+- Good for bulk operations
+- Can be used by agents
+
+**Cons:**
+- Not user-friendly for non-technical authors
+- Requires terminal access
+
+**Implementation:**
+```bash
+# Create a hierarchy strategy
+yarn cli strategy:create <courseId> \
+  --type hierarchy \
+  --name "Phonics Progression" \
+  --config ./hierarchy-config.json
+
+# Create an interference strategy
+yarn cli strategy:create <courseId> \
+  --type interference \
+  --config ./interference-config.json
+
+# List strategies
+yarn cli strategy:list <courseId>
+
+# Set default strategy
+yarn cli strategy:set-default <courseId> <strategyId>
+
+# Delete strategy
+yarn cli strategy:delete <courseId> <strategyId>
+```
+
+**Files to modify:**
+- `packages/cli/src/commands/` — Add strategy commands
+- `packages/cli/src/index.ts` — Register new commands
+
+---
+
+### Option C: MCP Tools
+
+**Pros:**
+- Agent-accessible for automated course building
+- Consistent with existing MCP pattern
+- Can leverage LLM for config generation
+
+**Cons:**
+- Requires MCP client
+- Not directly user-facing
+
+**Implementation:**
+Add to `packages/mcp/src/tools/`:
+
+```typescript
+// create_navigation_strategy tool
+{
+  name: 'create_navigation_strategy',
+  description: 'Create a navigation strategy for the course',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      strategyType: { enum: ['hierarchy', 'interference', 'relativePriority'] },
+      name: { type: 'string' },
+      description: { type: 'string' },
+      config: { type: 'object' }
+    }
+  }
+}
+```
+
+---
+
+## Implementation Completed: UI-First Approach ✅
+
+**Phase 1: UI Forms (COMPLETED)**
+- ✅ All four strategy configuration forms implemented
+- ✅ Visual editor with guided inputs
+- ✅ JSON editor for power users
+- ✅ Tag selectors, sliders, multi-selects
+- ✅ Validation and error messages
+- ✅ Edit/Create/Delete functionality
+- ✅ Compact two-column layout (list + form)
+
+**Phase 2 (Optional): CLI Commands**
+- Scriptable strategy creation from JSON files
+- Bulk operations and automation
+- Terminal-based workflows
+- **Status:** Not started, optional enhancement
+
+**Phase 3 (Optional): MCP Tools**
+- Agent-accessible strategy authoring
+- LLM-guided config generation
+- Extends existing MCP infrastructure
+- **Status:** Not started, optional enhancement
+
+---
+
+## Validation Requirements
+
+All authoring tools should validate:
+
+1. **Tag existence**: All referenced tags exist in the course
+2. **Circular dependencies** (Hierarchy): No circular prerequisite chains
+3. **Config completeness**: Required fields present
+4. **Value ranges**: Scores/thresholds in valid ranges (e.g., 0-1)
+5. **Delegate validity**: Delegate strategy type exists
+
+```typescript
+interface ValidationResult {
+  valid: boolean;
+  errors: Array<{
+    field: string;
+    message: string;
+  }>;
+  warnings: Array<{
+    field: string;
+    message: string;
+  }>;
+}
+```
+
+---
+
+## Files Created/Modified
+
+### UI Implementation (COMPLETED ✅)
+
+| File | Action | Description | Status |
+|------|--------|-------------|--------|
+| `packages/edit-ui/src/components/NavigationStrategy/HardcodedOrderConfigForm.vue` | CREATED | Card ID list form | ✅ |
+| `packages/edit-ui/src/components/NavigationStrategy/HierarchyConfigForm.vue` | CREATED | Prerequisite gating config | ✅ |
+| `packages/edit-ui/src/components/NavigationStrategy/InterferenceConfigForm.vue` | CREATED | Interference groups config | ✅ |
+| `packages/edit-ui/src/components/NavigationStrategy/RelativePriorityConfigForm.vue` | CREATED | Tag priorities config | ✅ |
+| `packages/edit-ui/src/components/NavigationStrategy/NavigationStrategyEditor.vue` | MODIFIED | Two-column layout, all strategy types | ✅ |
+| `packages/edit-ui/src/components/NavigationStrategy/NavigationStrategyList.vue` | MODIFIED | Compact density, simplified display | ✅ |
+
+### CLI Implementation (OPTIONAL, NOT STARTED)
+
+| File | Action | Description | Status |
+|------|--------|-------------|--------|
+| `packages/cli/src/commands/strategy.ts` | CREATE | Strategy management commands | ⏸️ |
+| `packages/cli/src/utils/strategy-validation.ts` | CREATE | Config validation utilities | ⏸️ |
+| `packages/cli/src/index.ts` | MODIFY | Register strategy commands | ⏸️ |
+
+### MCP Implementation (OPTIONAL, NOT STARTED)
+
+| File | Action | Description | Status |
+|------|--------|-------------|--------|
+| `packages/mcp/src/tools/create-navigation-strategy.ts` | CREATE | Create strategy tool | ⏸️ |
+| `packages/mcp/src/tools/update-navigation-strategy.ts` | CREATE | Update strategy tool | ⏸️ |
+| `packages/mcp/src/tools/list-navigation-strategies.ts` | CREATE | List strategies tool | ⏸️ |
+| `packages/mcp/src/tools/delete-navigation-strategy.ts` | CREATE | Delete strategy tool | ⏸️ |
+| `packages/mcp/src/types/tools.ts` | MODIFY | Add strategy schemas | ⏸️ |
+| `packages/mcp/src/tools/index.ts` | MODIFY | Export new tools | ⏸️ |
+
+---
+
+## Key Features Delivered
+
+### Dual Input Modes
+All forms support two modes for flexibility:
+- **Visual Editor**: Guided UI with selectors, sliders, and inputs
+- **JSON Editor**: Direct JSON editing with real-time validation
+
+### Strategy-Specific Capabilities
+
+**HierarchyConfigForm:**
+- Add/remove prerequisite rules
+- Tag selectors for gated tags and their prerequisites
+- Mastery thresholds (minCount, minElo)
+- Delegate strategy selector
+
+**InterferenceConfigForm:**
+- Add/remove interference groups
+- Multi-tag selector for each group
+- Per-group decay sliders (0-1)
+- Maturity threshold configuration (minCount, minElo, minElapsedDays)
+- Default decay setting
+
+**RelativePriorityConfigForm:**
+- Individual priority sliders for all course tags
+- Default priority configuration
+- Combine mode selector (max/average/min)
+- Priority influence slider
+
+### User Experience
+- **Compact Layout**: Two-column design (strategy list + form)
+- **Always Visible**: No modal dialogs, form always accessible
+- **Responsive**: Works on desktop and mobile
+- **Real-time Validation**: Inline error messages
+- **Tag Loading**: Automatically fetches course tags
+- **Edit Support**: Click any strategy to edit
+
+---
+
+## Access
+
+The NavigationStrategy editor is accessible in:
+- **studio-ui**: `/course-editor` route → "Navigation" tab
+- **platform-ui**: `/edit/:courseId` route → "Navigation" tab
+
+---
+
+## Related Files
+
+- `packages/db/src/core/types/contentNavigationStrategy.ts` — Strategy data schema
+- `packages/db/src/impl/couch/courseDB.ts` — DB methods for strategies
+- `packages/db/src/core/navigators/hierarchyDefinition.ts` — Config interface reference
+- `packages/db/src/core/navigators/interferenceMitigator.ts` — Config interface reference
+- `packages/db/src/core/navigators/relativePriority.ts` — Config interface reference
+- `packages/edit-ui/src/components/NavigationStrategy/` — UI components (all forms)

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

@@ -0,0 +1,278 @@
+# 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/eslint.config.mjs

@@ -3,7 +3,7 @@ import backendConfig from '../../eslint.config.backend.mjs';
 export default [
   ...backendConfig,
   {
-    ignores: ['node_modules/**', 'dist/**', 'eslint.config.mjs', 'tsup.config.ts'],
+    ignores: ['node_modules/**', 'dist/**', 'eslint.config.mjs', 'tsup.config.ts', 'vitest.config.ts'],
   },
   {
     languageOptions: {