@shaykec/bridge 0.4.25 → 0.4.27

package/modules/debugging-systematically/workshop.yaml

@@ -0,0 +1,127 @@
+scenarios:
+  - id: null-reference
+    title: "Fix a Null/Undefined Crash"
+    difficulty: beginner
+    xp: 25
+    setup:
+      - "mkdir -p workshop && cd workshop"
+      - "npm init -y"
+    files:
+      - name: app.js
+        content: |
+          const user = { id: 1, profile: null };
+          function greet(user) {
+            return `Hello, ${user.profile.name}!`;
+          }
+          try {
+            console.log(greet(user));
+          } catch (e) {
+            console.error('Error:', e.message);
+          }
+        language: javascript
+        readonly: false
+    task: "Run node app.js. The program crashes because user.profile is null and we access user.profile.name. Find and fix the null reference so the program runs without error."
+    validations:
+      - label: "Program runs and prints a greeting"
+        check: output-contains
+        pattern: "Hello"
+    hints:
+      - "What value is user.profile when the crash happens? How could you guard before accessing .name?"
+      - "Options: check if profile exists before using it, use optional chaining (user.profile?.name), or provide a default."
+      - "Consider: user.profile ? user.profile.name : 'Guest' or user.profile?.name ?? 'Guest'."
+    agent_prompts:
+      on_start: "What happens when you try to read a property of null? How would you discover that without seeing the code?"
+
+  - id: async-race
+    title: "Fix an Async Race Condition"
+    difficulty: intermediate
+    xp: 35
+    setup:
+      - "mkdir -p workshop && cd workshop"
+      - "npm init -y"
+    files:
+      - name: fetchData.js
+        content: |
+          async function fetchUser(id) {
+            return new Promise(resolve => setTimeout(() => resolve({ id, name: 'User ' + id }), 100));
+          }
+          async function fetchOrders(userId) {
+            return new Promise(resolve => setTimeout(() => resolve([{ orderId: 1 }, { orderId: 2 }]), 150));
+          }
+          async function run() {
+            const user = fetchUser(1);
+            const orders = fetchOrders(1);
+            console.log('User:', user);
+            console.log('Orders:', orders);
+            console.log('Done');
+          }
+          run();
+        language: javascript
+        readonly: false
+    task: "Run node fetchData.js. The output shows Promise objects instead of data because we use the results before the promises resolve. Fix the timing so both fetches complete before we log, and the output shows the actual user and orders."
+    validations:
+      - label: "fetchData.js was modified"
+        check: file-changed
+        pattern: "fetchData.js"
+      - label: "Output shows user and orders data"
+        check: output-contains
+        pattern: "User:"
+    hints:
+      - "fetchUser and fetchOrders return Promises. We need to wait for them before using the results."
+      - "Use await on each call, or await Promise.all([user, orders]) to wait for both."
+      - "Ensure run() awaits the fetches before console.log."
+    agent_prompts:
+      on_start: "What's the difference between calling fetchUser(1) and awaiting it? When does the data become available?"
+
+  - id: off-by-one
+    title: "Fix an Off-by-One Error in Pagination"
+    difficulty: intermediate
+    xp: 30
+    setup:
+      - "mkdir -p workshop && cd workshop"
+      - "npm init -y"
+    files:
+      - name: pagination.js
+        content: |
+          function getPageRange(totalItems, itemsPerPage, page) {
+            const totalPages = Math.ceil(totalItems / itemsPerPage);
+            if (page < 1 || page > totalPages) return null;
+            const start = (page - 1) * itemsPerPage;
+            const end = start + itemsPerPage;
+            return { start, end };
+          }
+          module.exports = { getPageRange };
+        language: javascript
+        readonly: false
+      - name: pagination.test.js
+        content: |
+          const { getPageRange } = require('./pagination');
+          function runTests() {
+            let passed = 0;
+            let failed = 0;
+            const tests = [
+              () => { const r = getPageRange(25, 10, 1); if (r && r.start === 0 && r.end === 10) passed++; else failed++; },
+              () => { const r = getPageRange(25, 10, 2); if (r && r.start === 10 && r.end === 20) passed++; else failed++; },
+              () => { const r = getPageRange(25, 10, 3); if (r && r.start === 20 && r.end === 25) passed++; else failed++; },
+              () => { const r = getPageRange(30, 10, 3); if (r && r.start === 20 && r.end === 30) passed++; else failed++; },
+            ];
+            tests.forEach(t => t());
+            return { passed, failed };
+          }
+          const { passed, failed } = runTests();
+          console.log(`Passed: ${passed}, Failed: ${failed}`);
+          if (failed === 0) console.log('All tests passed');
+          process.exit(failed > 0 ? 1 : 0);
+        language: javascript
+        readonly: true
+    task: "Run node pagination.test.js. One or more tests fail because the last page's end index is wrong. Fix getPageRange so all tests pass. The end index should be the exclusive upper bound (e.g. for items 20-24, start=20, end=25)."
+    validations:
+      - label: "All tests passed"
+        check: output-contains
+        pattern: "All tests passed"
+    hints:
+      - "For the last page, we might have fewer items than itemsPerPage. What should end be?"
+      - "end should be Math.min(start + itemsPerPage, totalItems) so we never exceed totalItems."
+      - "Page 3 of 25 items with 10 per page: start=20, end should be 25, not 30."
+    agent_prompts:
+      on_start: "When you have 25 items and 10 per page, how many pages are there? What's the start and end index for the last page?"

package/modules/demo-test/content.md

@@ -0,0 +1,68 @@
+# Demo Test — All System Elements
+
+This module exists to exercise every content and visual element in Socrates. It is intentionally short — one or two examples of each element type — so it can be used for manual walkthroughs or automated regression tests.
+
+## Section 1: Basic Markdown
+
+Plain text with **bold**, *italic*, `inline code`, and [a link](https://example.com).
+
+- Bullet list item one
+- Bullet list item two
+- Bullet list item three
+
+1. Numbered item one
+2. Numbered item two
+3. Numbered item three
+
+> A blockquote to test rendering.
+
+## Section 2: Code Blocks
+
+```bash
+echo "Hello from a bash code block"
+```
+
+```javascript
+function greet(name) {
+  return `Hello, ${name}!`;
+}
+```
+
+## Section 3: Tables
+
+| Element | Type | Tested |
+|---------|------|--------|
+| Mermaid diagram | Visual | Yes |
+| Timed-choice quiz | Interactive | Yes |
+| Terminal practice | Interactive | Yes |
+| Command sprint game | Interactive | Yes |
+
+## Section 4: Mermaid Diagrams
+
+```mermaid
+flowchart LR
+    A[Content] -->|read| B[Walkthrough]
+    B -->|practice| C[Exercises]
+    C -->|test| D[Quiz]
+    D -->|play| E[Games]
+```
+
+```mermaid
+sequenceDiagram
+    participant U as User
+    participant T as Teacher
+    participant C as Canvas
+    U->>T: Start lesson
+    T->>C: Show diagram
+    C-->>U: Visual display
+    U->>T: Answer question
+    T->>U: Socratic feedback
+```
+
+## Section 5: Key Concepts
+
+**Progressive Enhancement**: Socrates works in three tiers — full (extension + canvas), canvas-only (SSE + REST), and terminal-only (CLI). Every teaching interaction must work in terminal mode at minimum.
+
+**Socratic Method**: The teacher asks, never tells. Users discover answers through guided questions and hands-on practice.
+
+**Gamification**: XP, belts, and progress tracking keep learners motivated. Belts range from White (0 XP) to Black (3000 XP).

package/modules/demo-test/exercises.md

@@ -0,0 +1,28 @@
+# Demo Test Exercises
+
+## Exercise 1: Create a File
+
+**Task:** Create a file called `test-output.txt` containing the text "Socrates works!" using a single terminal command.
+
+**Validation:**
+- [ ] File `test-output.txt` exists
+- [ ] File contains the exact text "Socrates works!"
+
+**Hints:**
+1. Use `echo` with output redirection (`>`)
+2. `echo "Socrates works!" > test-output.txt`
+
+---
+
+## Exercise 2: Explore a Module
+
+**Task:** List all files in the `demo-test` module directory and identify which file types are present.
+
+**Validation:**
+- [ ] User can list: module.yaml, content.md, walkthrough.md, quiz.md, exercises.md, quick-ref.md, resources.md, game.yaml, workshop.yaml
+- [ ] User identifies the purpose of at least 3 file types
+
+**Hints:**
+1. Use `ls` to list directory contents
+2. Each file serves a specific role: metadata, content, interactive elements
+3. The module.yaml is the entry point that describes the module

package/modules/demo-test/game.yaml

@@ -0,0 +1,171 @@
+games:
+  - type: command-sprint
+    title: "Socrates Command Sprint"
+    challenges:
+      - prompt: "List all files in the current directory (including hidden)."
+        answer: "ls -la"
+        alternates: ["ls -al", "ls -a -l"]
+        timeLimit: 15
+      - prompt: "Create a directory called 'test-dir'."
+        answer: "mkdir test-dir"
+        alternates: ["mkdir -p test-dir"]
+        timeLimit: 12
+      - prompt: "Write 'hello' to a file called output.txt."
+        answer: "echo hello > output.txt"
+        alternates: ["echo 'hello' > output.txt", "printf 'hello' > output.txt"]
+        timeLimit: 18
+
+  - type: speed-round
+    title: "Socrates Speed Round"
+    rounds:
+      - question: "Which tier always works, even without a browser?"
+        options:
+          - "Full tier"
+          - "Canvas tier"
+          - "Terminal tier"
+        answer: 2
+        timeLimit: 12
+      - question: "What method does Socrates use for teaching?"
+        options:
+          - "Lecture-based"
+          - "Socratic (question-based)"
+          - "Video-only"
+        answer: 1
+        timeLimit: 12
+      - question: "What color is the first belt in Socrates?"
+        options:
+          - "Yellow"
+          - "Green"
+          - "White"
+        answer: 2
+        timeLimit: 10
+
+  - type: bug-hunt
+    title: "Spot the Bug"
+    snippets:
+      - code: |
+          function add(a, b) {
+            return a - b;
+          }
+          console.log(add(2, 3)); // Expected: 5
+        bugLine: 2
+        explanation: "The function is named 'add' but uses subtraction (-) instead of addition (+)."
+        hint: "Look at the operator on line 2."
+      - code: |
+          const items = [1, 2, 3];
+          for (let i = 0; i <= items.length; i++) {
+            console.log(items[i]);
+          }
+        bugLine: 2
+        explanation: "Off-by-one error: <= should be <. When i equals items.length, items[i] is undefined."
+        hint: "Array indices go from 0 to length - 1."
+      - code: |
+          async function fetchUser(id) {
+            const res = fetch(`/api/users/${id}`);
+            return res.json();
+          }
+        bugLine: 2
+        explanation: "Missing 'await' before fetch(). Without it, res is a Promise, not a Response, so res.json() will fail."
+        hint: "This is an async function — are all async calls awaited?"
+
+  - type: classify
+    title: "Element Sorter"
+    categories:
+      - name: Interactive
+        color: "#58a6ff"
+      - name: Visual
+        color: "#3fb950"
+      - name: Content
+        color: "#f0883e"
+    items:
+      - text: "Quiz"
+        category: "Interactive"
+      - text: "Terminal practice"
+        category: "Interactive"
+      - text: "Game"
+        category: "Interactive"
+      - text: "Mermaid diagram"
+        category: "Visual"
+      - text: "Celebration animation"
+        category: "Visual"
+      - text: "Progress bar"
+        category: "Visual"
+      - text: "Markdown text"
+        category: "Content"
+      - text: "Quick reference"
+        category: "Content"
+      - text: "Resource links"
+        category: "Content"
+
+  - type: scenario
+    title: "The Module Author"
+    startHealth: 3
+    steps:
+      - id: start
+        situation: "You're creating a new learning module for Socrates. You have a topic in mind. What do you create first?"
+        choices:
+          - text: "Start with module.yaml to define metadata, XP, and triggers."
+            consequence: "Good instinct. The metadata file is the entry point that defines everything about the module."
+            health: 1
+            next: content
+          - text: "Jump straight into writing quiz questions."
+            consequence: "Quizzes are important, but without content there's nothing to quiz on."
+            health: -1
+            next: content
+          - text: "Write the content.md reference material first."
+            consequence: "Content is foundational, but you'll need module.yaml to register the module."
+            health: 0
+            next: yaml_later
+      - id: yaml_later
+        situation: "You've written great content but realize the module isn't recognized by the system. What's missing?"
+        choices:
+          - text: "Create module.yaml with slug, title, description, and XP config."
+            consequence: "Now the system can find and load your module."
+            health: 1
+            next: content
+          - text: "Add the module to registry.yaml directly."
+            consequence: "The registry references modules, but each module needs its own module.yaml first."
+            health: 0
+            next: content
+      - id: content
+        situation: "Your module.yaml and content.md are ready. What do you add next to make the module interactive?"
+        choices:
+          - text: "Add a walkthrough.md with Socratic questions and hint directives."
+            consequence: "The walkthrough is the heart of the teaching experience."
+            health: 1
+            next: finish
+          - text: "Add all six game types to game.yaml."
+            consequence: "Games are fun but a walkthrough should come first — it's the core teaching flow."
+            health: 0
+            next: finish
+          - text: "Skip interactivity — content is enough."
+            consequence: "Content alone is passive. Socrates is built around active learning."
+            health: -1
+            next: finish
+      - id: finish
+        situation: "Your module is taking shape. Time to finalize. What's your last step?"
+        choices:
+          - text: "Add quiz, exercises, games, quick-ref, and resources. Then test everything."
+            consequence: "Comprehensive and thorough. A well-rounded module with all element types."
+            health: 1
+            next: end
+          - text: "Ship it as-is and iterate later."
+            consequence: "Iterating is fine, but at least add a quiz to validate learning."
+            health: 0
+            next: end
+
+  - type: memory-match
+    title: "Element Pairs"
+    pairs:
+      - term: "canvas:quiz"
+        definition: "Interactive quiz with timed-choice, drag-order, matching"
+      - term: "canvas:terminal"
+        definition: "Practice terminal with task validation"
+      - term: "canvas:diagram"
+        definition: "Mermaid diagram visualization"
+      - term: "canvas:game"
+        definition: "Interactive game (sprint, scenario, etc.)"
+      - term: "canvas:celebrate"
+        definition: "XP award and level-up animation"
+      - term: "canvas:html"
+        definition: "Rich HTML content (images, videos, links)"

package/modules/demo-test/module.yaml

@@ -0,0 +1,41 @@
+slug: demo-test
+title: "Demo Test — All System Elements"
+version: 1.0.0
+description: "A short module that exercises every teaching element in Socrates. Used for manual and automated testing."
+category: meta
+tags: [demo, test, qa, all-elements]
+difficulty: beginner
+
+xp:
+  read: 10
+  walkthrough: 40
+  exercise: 25
+  quiz: 20
+  quiz-perfect-bonus: 10
+  game: 25
+  game-perfect-bonus: 15
+
+time:
+  quick: 2
+  read: 5
+  guided: 10
+
+prerequisites: []
+related: []
+
+triggers:
+  - "Run the demo test module"
+  - "Test all teaching elements"
+  - "Show me a demo of Socrates"
+
+visuals:
+  diagrams: [diagram-mermaid, diagram-flow]
+  quiz-types: [quiz-timed-choice, quiz-drag-order, quiz-matching, quiz-fill-blank]
+  game-types: [speed-round, bug-hunt, classify, scenario, command-sprint, memory-match]
+  playground: bash
+  web-embeds: true
+  workshop: true
+
+sources:
+  - url: "https://github.com/Socrates"
+    label: "Socrates Repository"

package/modules/demo-test/quick-ref.md

@@ -0,0 +1,54 @@
+# Demo Test Quick Reference
+
+## Module File Types
+| File | Purpose | Required |
+|------|---------|----------|
+| `module.yaml` | Metadata, XP, triggers, visuals config | Yes |
+| `content.md` | Reference content (the "textbook") | Yes |
+| `walkthrough.md` | Socratic guided lesson steps | No |
+| `quiz.md` | Quiz questions with answers | No |
+| `exercises.md` | Hands-on exercises with validation | No |
+| `quick-ref.md` | Cheat sheet / command reference | No |
+| `resources.md` | External links, videos, books | No |
+| `game.yaml` | Interactive games | No |
+| `workshop.yaml` | Workshop scenarios (editor + terminal) | No |
+
+## Quiz Types
+| Type | Directive | Use Case |
+|------|-----------|----------|
+| Timed choice | *(default)* | Multiple choice A/B/C/D |
+| Drag order | `<!-- VISUAL: drag-order -->` | Order items correctly |
+| Matching | `<!-- VISUAL: quiz-matching -->` | Match pairs |
+| Fill blank | `<!-- VISUAL: fill-blank -->` | Fill in missing text |
+
+## Game Types
+| Type | Data | Purpose |
+|------|------|---------|
+| `speed-round` | `rounds` | Timed multiple choice |
+| `bug-hunt` | `snippets` | Find bugs in code |
+| `classify` | `categories`, `items` | Sort items into groups |
+| `scenario` | `steps`, `startHealth` | Branching narrative |
+| `command-sprint` | `challenges` | Type correct commands |
+| `memory-match` | `pairs` | Match term/definition |
+
+## Walkthrough Hints
+| Hint | Visual Element |
+|------|---------------|
+| `hint:terminal` | Practice terminal |
+| `hint:diagram` | Mermaid diagram |
+| `hint:buttons` | Smart buttons |
+| `hint:card` | Info card |
+| `hint:code` | Code snippet |
+| `hint:list` | Smart list |
+| `hint:steps` | Step tracker |
+| `hint:progress` | Progress bar |
+| `hint:embed` | Web embed |
+| `hint:quiz inline` | Inline quiz |
+| `hint:celebrate` | Celebration |
+| `hint:video` | YouTube video |
+| `hint:game` | Game offer |
+
+## Belt Progression
+```
+White (0) → Yellow (50) → Green (150) → Blue (400) → Purple (800) → Brown (1500) → Black (3000)
+```

package/modules/demo-test/quiz.md

@@ -0,0 +1,74 @@
+# Demo Test Quiz
+
+## Question 1
+
+What is the Socratic method?
+
+A) Giving students the correct answer immediately
+B) Teaching through questions that guide the learner to discover answers
+C) Memorizing facts through repetition
+D) Watching video lectures passively
+
+<!-- ANSWER: B -->
+<!-- EXPLANATION: The Socratic method teaches by asking questions rather than providing direct answers. This forces active thinking and deeper understanding. Socrates uses this approach — the teacher asks, never tells. -->
+
+## Question 2
+
+How many tiers does Socrates's progressive enhancement support?
+
+A) 1
+B) 2
+C) 3
+D) 4
+
+<!-- ANSWER: C -->
+<!-- EXPLANATION: Socrates has three tiers: Full (extension + canvas via WebSocket), Canvas (SSE + REST), and Terminal (CLI only). Each tier degrades gracefully — terminal always works. -->
+
+## Question 3
+
+<!-- VISUAL: drag-order -->
+
+Put these Socrates learning activities in order from passive to most interactive:
+
+A) Playing a command-sprint game
+B) Reading content
+C) Answering a quiz
+D) Completing a terminal exercise
+
+<!-- ANSWER: B,C,D,A -->
+<!-- EXPLANATION: Reading is passive consumption. Quizzes test recall. Terminal exercises require hands-on practice. Games add time pressure and competition, making them the most actively engaging. -->
+
+## Question 4
+
+<!-- VISUAL: quiz-matching -->
+
+Match each belt color to its minimum XP requirement:
+
+A) White → 1) 0 XP
+B) Yellow → 2) 50 XP
+C) Green → 3) 150 XP
+D) Blue → 4) 400 XP
+
+<!-- ANSWER: A1,B2,C3,D4 -->
+<!-- EXPLANATION: Belts progress from White (0 XP) through Yellow (50), Green (150), Blue (400), Purple (800), Brown (1500), to Black (3000 XP). -->
+
+## Question 5
+
+Fill in the blank: In Socrates, all packages communicate through a shared ___0___ with JSON envelopes.
+
+<!-- VISUAL: fill-blank -->
+
+<!-- ANSWER: protocol -->
+<!-- EXPLANATION: The shared protocol (packages/shared/src/protocol.js) defines all 18 message types and the JSON envelope format. Every package uses this protocol to communicate. -->
+
+## Question 6
+
+Which of these is NOT a game type in Socrates?
+
+A) command-sprint
+B) memory-match
+C) word-search
+D) bug-hunt
+
+<!-- ANSWER: C -->
+<!-- EXPLANATION: Socrates supports six game types: speed-round, bug-hunt, classify, scenario, command-sprint, and memory-match. Word-search is not one of them. -->

package/modules/demo-test/resources.md

@@ -0,0 +1,21 @@
+# Demo Test — Resources
+
+## Project Docs
+
+- [Socrates SPEC.md](../../SPEC.md) — Single source of truth for the system.
+- [Architecture](../../docs/architecture.md) — System diagrams and data flow.
+
+## Socratic Method
+
+- [Stanford Encyclopedia — Socrates](https://plato.stanford.edu/entries/socrates/) — Philosophical background on Socratic dialogue.
+- [What is the Socratic Method?](https://www.youtube.com/watch?v=N6CAzYzrFiE) — Short video explainer.
+
+## Gamification in Education
+
+- [Gamification in Education: A Systematic Review](https://www.sciencedirect.com/science/article/pii/S0360131514002000) — Research on gamification effectiveness.
+- [Duolingo's Gamification Strategy](https://blog.duolingo.com/) — Real-world example of gamified learning.
+
+## Tools
+
+- [Mermaid Live Editor](https://mermaid.live/) — Test and preview Mermaid diagrams.
+- [Vitest](https://vitest.dev/) — The test framework used by Socrates.