learn_bash_from_session_data 1.0.6 → 1.0.7

package/bin/learn-bash.js

@@ -240,26 +240,29 @@ function checkPython() {
  */
 function openInBrowser(filePath) {
   const platform = os.platform();
+  const isWindows = platform === 'win32' ||
+    process.env.MSYSTEM != null ||
+    (process.env.OSTYPE && process.env.OSTYPE.includes('msys')) ||
+    isWSL();
   let cmd;
   let args;
 
-  switch (platform) {
-    case 'darwin':
-      cmd = 'open';
-      args = [filePath];
-      break;
-    case 'win32':
-      cmd = 'cmd';
-      args = ['/c', 'start', '', filePath];
-      break;
-    default:
-      // Linux and others
-      cmd = 'xdg-open';
-      args = [filePath];
+  if (platform === 'darwin') {
+    cmd = 'open';
+    args = [filePath];
+  } else if (isWindows) {
+    // Works from native Windows, MSYS, Git Bash, and WSL
+    cmd = process.env.COMSPEC || 'cmd.exe';
+    args = ['/c', 'start', '', filePath.replace(/\//g, '\\')];
+  } else {
+    cmd = 'xdg-open';
+    args = [filePath];
   }
 
   try {
-    spawn(cmd, args, { detached: true, stdio: 'ignore' }).unref();
+    const child = spawn(cmd, args, { detached: true, stdio: 'ignore' });
+    child.on('error', () => {});  // Suppress async spawn errors
+    child.unref();
     return true;
   } catch (e) {
     return false;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "learn_bash_from_session_data",
-  "version": "1.0.6",
+  "version": "1.0.7",
   "description": "Learn bash from your Claude Code sessions - extracts commands and generates interactive HTML lessons with 400+ commands, quizzes, and comprehensive coverage",
   "main": "bin/learn-bash.js",
   "bin": {

package/scripts/html_generator.py

@@ -12,6 +12,16 @@ from pathlib import Path
 import html
 import json
 
+try:
+    from scripts.knowledge_base import COMMAND_DB, get_flags_for_command, get_command_info
+except ImportError:
+    try:
+        from knowledge_base import COMMAND_DB, get_flags_for_command, get_command_info
+    except ImportError:
+        COMMAND_DB = {}
+        def get_flags_for_command(cmd): return {}
+        def get_command_info(cmd): return None
+
 
 def _generate_html_impl(analysis_result: dict[str, Any], quizzes: list[dict[str, Any]]) -> str:
     """
@@ -376,7 +386,7 @@ def render_commands_tab(commands: list[dict]) -> str:
         # Syntax highlighted command
         highlighted = _syntax_highlight(cmd.get("full_command", ""))
 
-        # Flags breakdown
+        # Flags breakdown with descriptions
         flags = cmd.get("flags", [])
         flags_html = ""
         if flags:
@@ -384,9 +394,27 @@ def render_commands_tab(commands: list[dict]) -> str:
             for flag in flags:
                 flag_name = html.escape(flag.get("flag", ""))
                 flag_desc = html.escape(flag.get("description", ""))
-                flags_html += f'<li><code class="flag">{flag_name}</code> - {flag_desc}</li>'
+                if flag_desc:
+                    flags_html += f'<li><code class="flag">{flag_name}</code> <span class="flag-desc">{flag_desc}</span></li>'
+                else:
+                    flags_html += f'<li><code class="flag">{flag_name}</code></li>'
             flags_html += '</ul></div>'
 
+        # Subcommand description
+        subcommand_desc = cmd.get("subcommand_desc", "")
+        subcmd_html = ""
+        if subcommand_desc:
+            subcmd_html = f'<div class="subcmd-section"><span class="subcmd-label">Subcommand:</span> {html.escape(subcommand_desc)}</div>'
+
+        # Common patterns / examples from knowledge base
+        common_patterns = cmd.get("common_patterns", [])
+        patterns_html = ""
+        if common_patterns:
+            patterns_html = '<div class="patterns-section"><h5>Common Patterns:</h5><ul class="patterns-list">'
+            for pattern in common_patterns[:5]:
+                patterns_html += f'<li><code>{html.escape(pattern)}</code></li>'
+            patterns_html += '</ul></div>'
+
         # Output preview
         output_preview = cmd.get("output_preview", "")
         output_html = ""
@@ -418,7 +446,9 @@ def render_commands_tab(commands: list[dict]) -> str:
                                     <h5>Description:</h5>
                                     <p>{description}</p>
                                 </div>
+                                {subcmd_html}
                                 {flags_html}
+                                {patterns_html}
                                 {output_html}
                             </div>
                         </div>'''
@@ -512,13 +542,37 @@ def render_lessons_tab(categories: dict, commands: list[dict]) -> str:
             complexity = cmd.get("complexity", "simple")
             highlighted = _syntax_highlight(cmd.get("full_command", ""))
 
+            # Get flags and patterns for this command from COMMAND_DB
+            cmd_flags = cmd.get("flags", [])
+            lesson_flags_html = ""
+            if cmd_flags:
+                lesson_flags_html = '<div class="lesson-flags"><strong>Flags used:</strong> '
+                flag_parts = []
+                for flag in cmd_flags:
+                    fname = html.escape(flag.get("flag", "") if isinstance(flag, dict) else str(flag))
+                    fdesc = html.escape(flag.get("description", "") if isinstance(flag, dict) else "")
+                    if fdesc:
+                        flag_parts.append(f'<code class="flag">{fname}</code> ({fdesc})')
+                    else:
+                        flag_parts.append(f'<code class="flag">{fname}</code>')
+                lesson_flags_html += ', '.join(flag_parts) + '</div>'
+
+            # Subcommand info
+            subcmd_desc = cmd.get("subcommand_desc", "")
+            lesson_subcmd = ""
+            if subcmd_desc:
+                lesson_subcmd = f'<div class="lesson-subcmd"><em>{html.escape(subcmd_desc)}</em></div>'
+
             cat_commands_html += f'''
                             <div class="lesson-command">
                                 <div class="lesson-command-header">
                                     <code class="cmd">{base_cmd}</code>
+                                    <span class="lesson-complexity complexity-{complexity}">{complexity}</span>
                                 </div>
                                 <pre class="syntax-highlighted">{highlighted}</pre>
                                 <p class="lesson-description">{description}</p>
+                                {lesson_subcmd}
+                                {lesson_flags_html}
                             </div>'''
 
         # Patterns observed
@@ -1384,6 +1438,22 @@ def get_inline_css() -> str:
             color: #34a853;
         }
 
+        .flag-desc { color: #6c757d; margin-left: 4px; }
+        .flags-list li { margin: 4px 0; line-height: 1.5; }
+        .subcmd-section { background: #f0f7ff; padding: 8px 12px; border-radius: 6px; margin: 8px 0; border-left: 3px solid #4a9eff; }
+        .subcmd-label { font-weight: 600; color: #4a9eff; }
+        .patterns-section { margin: 8px 0; }
+        .patterns-section h5 { margin: 4px 0; color: #666; font-size: 0.85em; }
+        .patterns-list { list-style: none; padding: 0; margin: 4px 0; }
+        .patterns-list li { padding: 3px 0; }
+        .patterns-list code { background: #f5f5f5; padding: 2px 6px; border-radius: 3px; font-size: 0.85em; }
+        .lesson-flags { margin: 6px 0; font-size: 0.9em; color: #555; }
+        .lesson-subcmd { font-size: 0.9em; color: #4a9eff; margin: 4px 0; }
+        .lesson-complexity { font-size: 0.75em; padding: 2px 8px; border-radius: 10px; margin-left: 8px; }
+        .complexity-simple { background: #e8f5e9; color: #2e7d32; }
+        .complexity-intermediate { background: #fff3e0; color: #e65100; }
+        .complexity-advanced { background: #fce4ec; color: #c62828; }
+
         .syntax-highlighted .string {
             color: #ff6d01;
         }
@@ -2107,27 +2177,70 @@ def generate_html_files(
     # Transform commands to expected format
     formatted_commands = []
     for cmd in analyzed_commands:
-        # Convert flags to expected format (list of dicts with 'flag' and 'description')
+        cmd_str = cmd.get('command', '')
+        base_cmd = cmd.get('base_command', cmd_str.split()[0] if cmd_str else '')
+        complexity_score = cmd.get('complexity', 1)
+
+        # Look up COMMAND_DB info for this command
+        cmd_info = COMMAND_DB.get(base_cmd, {})
+        kb_flags = get_flags_for_command(base_cmd)
+
+        # Convert flags to expected format WITH descriptions from knowledge base
         raw_flags = cmd.get('flags', [])
         formatted_flags = []
         for f in raw_flags:
-            if isinstance(f, dict):
-                formatted_flags.append(f)
+            if isinstance(f, dict) and 'flag' in f:
+                # Already formatted - but enrich description if empty
+                flag_name = f.get('flag', '')
+                flag_desc = f.get('description', '')
+                if not flag_desc and flag_name in kb_flags:
+                    flag_desc = kb_flags[flag_name]
+                formatted_flags.append({'flag': flag_name, 'description': flag_desc})
             elif isinstance(f, str):
-                formatted_flags.append({'flag': f, 'description': ''})
-
-        cmd_str = cmd.get('command', '')
-        complexity_score = cmd.get('complexity', 1)
+                # Raw flag string - look up description from knowledge base
+                flag_desc = kb_flags.get(f, '')
+                # For combined flags like -la, try individual characters
+                if not flag_desc and len(f) > 2 and f.startswith('-') and not f.startswith('--'):
+                    char_descs = []
+                    for char in f[1:]:
+                        single = f'-{char}'
+                        if single in kb_flags:
+                            char_descs.append(f'{single}: {kb_flags[single]}')
+                    if char_descs:
+                        flag_desc = '; '.join(char_descs)
+                formatted_flags.append({'flag': f, 'description': flag_desc})
+
+        # Get educational description from COMMAND_DB if session description is empty/generic
+        session_desc = cmd.get('description', '')
+        kb_desc = cmd_info.get('description', '')
+        description = session_desc if session_desc else kb_desc
+
+        # Get subcommand info (for commands like git, docker, npm)
+        subcommands = cmd_info.get('subcommands', {})
+        # Try to identify the subcommand from the full command
+        cmd_tokens = cmd_str.split() if cmd_str else []
+        subcommand_desc = ''
+        if subcommands and len(cmd_tokens) > 1:
+            for token in cmd_tokens[1:]:
+                if not token.startswith('-') and token in subcommands:
+                    subcommand_desc = subcommands[token]
+                    break
+
+        # Get common patterns from COMMAND_DB
+        common_patterns = cmd_info.get('common_patterns', [])
 
         formatted_commands.append({
-            'base_command': cmd.get('base_command', cmd_str.split()[0] if cmd_str else ''),
+            'base_command': base_cmd,
             'full_command': cmd_str,
             'category': cmd.get('category', 'Other'),
             'complexity': complexity_to_label(complexity_score),
             'complexity_score': complexity_score,
             'frequency': frequency_map.get(cmd_str, 1),
-            'description': cmd.get('description', ''),
+            'description': description,
             'flags': formatted_flags,
+            'subcommand_desc': subcommand_desc,
+            'common_patterns': common_patterns[:6],
+            'args': cmd.get('args', []),
             'is_new': False,
         })
 

package/scripts/quiz_generator.py

@@ -729,20 +729,44 @@ def _generate_distractor_flags(cmd: str, correct_flag: str, count: int = 3) -> l
 
 
 def _generate_distractor_descriptions(correct_desc: str, count: int = 3) -> list[str]:
-    """Generate plausible wrong descriptions."""
+    """Generate plausible wrong descriptions using command-level descriptions for length parity."""
     distractors = []
 
-    # Collect all descriptions from merged sources
-    all_descriptions = []
-    for cmd in _get_all_flagged_commands():
-        all_descriptions.extend(_get_flags_for_cmd(cmd).values())
-
-    # Remove duplicates and the correct answer
-    all_descriptions = list(set(all_descriptions))
-    all_descriptions = [d for d in all_descriptions if d.lower() != correct_desc.lower()]
-
-    random.shuffle(all_descriptions)
-    return all_descriptions[:count]
+    # First: collect command-level descriptions from COMMAND_DB (similar length to correct answer)
+    cmd_descriptions = []
+    for cmd_name in COMMAND_DB:
+        cmd_info = COMMAND_DB[cmd_name]
+        desc = cmd_info.get('description', '')
+        if desc and desc.lower() != correct_desc.lower():
+            # Truncate very long descriptions to similar length as correct answer
+            max_len = max(len(correct_desc) + 40, 80)
+            if len(desc) > max_len:
+                desc = desc[:max_len].rsplit(' ', 1)[0] + '...'
+            cmd_descriptions.append(desc)
+
+    if cmd_descriptions:
+        random.shuffle(cmd_descriptions)
+        distractors.extend(cmd_descriptions[:count])
+
+    # Fallback: use flag descriptions if not enough command descriptions
+    if len(distractors) < count:
+        all_flag_descs = []
+        for cmd in _get_all_flagged_commands():
+            all_flag_descs.extend(_get_flags_for_cmd(cmd).values())
+        all_flag_descs = list(set(all_flag_descs))
+        all_flag_descs = [d for d in all_flag_descs if d.lower() != correct_desc.lower()]
+        random.shuffle(all_flag_descs)
+        distractors.extend(all_flag_descs[:count - len(distractors)])
+
+    # Remove duplicates
+    seen = set()
+    unique = []
+    for d in distractors:
+        dl = d.lower()
+        if dl not in seen:
+            seen.add(dl)
+            unique.append(d)
+    return unique[:count]
 
 
 def generate_what_does_quiz(
@@ -793,9 +817,27 @@ def generate_what_does_quiz(
         for rel_cmd in related_cmds[:3 - len(distractor_descriptions)]:
             distractor_descriptions.append(f"Runs {rel_cmd} to process files")
 
-    # Ensure we have exactly 3 distractors
+    # Ensure we have exactly 3 distractors with plausible alternatives
+    fallback_actions = [
+        f"List directory contents with detailed file information",
+        f"Search recursively through files for matching patterns",
+        f"Display or modify file permissions and ownership",
+        f"Compress or archive files for storage and transfer",
+        f"Monitor system processes and resource usage",
+        f"Download files from a remote server or URL",
+        f"Edit configuration files in the default text editor",
+        f"Install or update packages from the package manager",
+    ]
+    random.shuffle(fallback_actions)
+    fb_idx = 0
     while len(distractor_descriptions) < 3:
-        distractor_descriptions.append(f"Performs an unrelated {base_cmd} operation")
+        if fb_idx < len(fallback_actions):
+            fallback = fallback_actions[fb_idx]
+            if fallback.lower() != correct_desc.lower():
+                distractor_descriptions.append(fallback)
+            fb_idx += 1
+        else:
+            distractor_descriptions.append(f"Run a system utility to process input data")
 
     # Create options (shuffle positions)
     options = []
@@ -929,19 +971,20 @@ def generate_build_command_quiz(
     parsed = _parse_command(cmd_string)
     base_cmd = parsed["base"]
 
-    # Create the correct command structure
-    correct_components = [base_cmd] + parsed["flags"] + parsed["args"]
-    correct_answer = " ".join(correct_components)
+    # Use the original command string as correct answer (preserves flag-argument ordering)
+    correct_answer = cmd_string.strip()
 
-    # Generate wrong arrangements
+    # Generate wrong arrangements using parsed components
+    all_parts = [base_cmd] + parsed["flags"] + parsed["args"]
     distractors = []
 
-    # Distractor 1: Wrong order
-    if len(correct_components) > 2:
-        wrong_order = correct_components.copy()
+    # Distractor 1: Wrong order of components
+    if len(all_parts) > 2:
+        wrong_order = all_parts.copy()
         random.shuffle(wrong_order)
-        if wrong_order != correct_components:
-            distractors.append(" ".join(wrong_order))
+        wrong_str = " ".join(wrong_order)
+        if wrong_str != correct_answer:
+            distractors.append(wrong_str)
 
     # Distractor 2: Missing flag
     if parsed["flags"]:
@@ -961,15 +1004,31 @@ def generate_build_command_quiz(
         wrong_cmd = [related[0]] + parsed["flags"] + parsed["args"]
         distractors.append(" ".join(wrong_cmd))
 
-    # Ensure we have exactly 3 distractors
+    # Ensure we have exactly 3 distractors with plausible alternatives
+    # Use real flags from the knowledge base as fallback distractors
+    all_cmd_flags = list(_get_flags_for_cmd(base_cmd).keys())
+    random.shuffle(all_cmd_flags)
+    fb_flag_idx = 0
     while len(distractors) < 3:
-        # Add a clearly wrong option
-        distractors.append(f"{base_cmd} --invalid-option")
+        if fb_flag_idx < len(all_cmd_flags):
+            fallback_flag = all_cmd_flags[fb_flag_idx]
+            fallback_cmd = f"{base_cmd} {fallback_flag} {' '.join(parsed['args'])}"
+            if fallback_cmd.strip() != correct_answer:
+                distractors.append(fallback_cmd.strip())
+            fb_flag_idx += 1
+        else:
+            # Use a related command as last resort
+            related = _get_related_commands(base_cmd)
+            if related:
+                rel = related[len(distractors) % len(related)]
+                distractors.append(f"{rel} {' '.join(parsed['flags'])} {' '.join(parsed['args'])}".strip())
+            else:
+                distractors.append(f"{base_cmd} {' '.join(parsed['args'])}".strip())
 
     # Remove duplicates and correct answer from distractors
     distractors = list(set(d for d in distractors if d != correct_answer))[:3]
     while len(distractors) < 3:
-        distractors.append(f"{base_cmd} --wrong-flag")
+        distractors.append(f"{base_cmd} {' '.join(parsed['args'])}".strip())
 
     # Create options
     all_answers = [correct_answer] + distractors[:3]
@@ -1203,7 +1262,13 @@ def generate_quiz_set(
     target_build = max(1, int(count * 0.2))
     target_spot_diff = max(1, int(count * 0.15))
 
-    used_commands = set()
+    # Track used commands per quiz type to avoid repeating the same command
+    used_per_type = {
+        QuizType.WHAT_DOES: set(),
+        QuizType.WHICH_FLAG: set(),
+        QuizType.BUILD_COMMAND: set(),
+        QuizType.SPOT_DIFFERENCE: set(),
+    }
 
     # Generate "What does this do?" questions
     random.shuffle(weighted_commands)
@@ -1211,38 +1276,47 @@ def generate_quiz_set(
         if len([q for q in questions if q.quiz_type == QuizType.WHAT_DOES]) >= target_what_does:
             break
         cmd_id = cmd.get("command", "")
-        if cmd_id not in used_commands:
+        if cmd_id not in used_per_type[QuizType.WHAT_DOES]:
             q = generate_what_does_quiz(cmd)
             questions.append(q)
-            used_commands.add(cmd_id)
+            used_per_type[QuizType.WHAT_DOES].add(cmd_id)
 
     # Generate "Which flag?" questions
     random.shuffle(weighted_commands)
     for cmd in weighted_commands:
         if len([q for q in questions if q.quiz_type == QuizType.WHICH_FLAG]) >= target_which_flag:
             break
-        q = generate_which_flag_quiz(cmd)
-        if q:
-            questions.append(q)
+        cmd_id = cmd.get("command", "")
+        if cmd_id not in used_per_type[QuizType.WHICH_FLAG]:
+            q = generate_which_flag_quiz(cmd)
+            if q:
+                questions.append(q)
+                used_per_type[QuizType.WHICH_FLAG].add(cmd_id)
 
     # Generate "Build the command" questions
     random.shuffle(weighted_commands)
     for cmd in weighted_commands:
         if len([q for q in questions if q.quiz_type == QuizType.BUILD_COMMAND]) >= target_build:
             break
-        q = generate_build_command_quiz(cmd)
-        questions.append(q)
+        cmd_id = cmd.get("command", "")
+        if cmd_id not in used_per_type[QuizType.BUILD_COMMAND]:
+            q = generate_build_command_quiz(cmd)
+            questions.append(q)
+            used_per_type[QuizType.BUILD_COMMAND].add(cmd_id)
 
     # Generate "Spot the difference" questions
     random.shuffle(weighted_commands)
     for cmd in weighted_commands:
         if len([q for q in questions if q.quiz_type == QuizType.SPOT_DIFFERENCE]) >= target_spot_diff:
             break
-        variant = _create_similar_command_variant(cmd)
-        if variant:
-            q = generate_spot_difference_quiz(cmd, variant)
-            if q:
-                questions.append(q)
+        cmd_id = cmd.get("command", "")
+        if cmd_id not in used_per_type[QuizType.SPOT_DIFFERENCE]:
+            variant = _create_similar_command_variant(cmd)
+            if variant:
+                q = generate_spot_difference_quiz(cmd, variant)
+                if q:
+                    questions.append(q)
+                    used_per_type[QuizType.SPOT_DIFFERENCE].add(cmd_id)
 
     # Shuffle final questions
     random.shuffle(questions)