learn_bash_from_session_data 1.0.10 → 1.1.1

package/scripts/html_generator.py

@@ -158,6 +158,7 @@ def render_overview_tab(stats: dict[str, Any], commands: list[dict], categories:
     unique_commands = stats.get("unique_commands", 0)
     unique_utilities = stats.get("unique_utilities", 0)
     date_range = stats.get("date_range", {"start": "N/A", "end": "N/A"})
+
     # Get operators data for the "Bash Operators Used" section
     operators_used = stats.get("operators_used", {})
     operator_descriptions = {
@@ -312,6 +313,7 @@ def render_overview_tab(stats: dict[str, Any], commands: list[dict], categories:
                             </div>
                         </div>
                     </div>
+
                 </div>'''
 
 
@@ -425,12 +427,44 @@ def render_commands_tab(commands: list[dict]) -> str:
                                 <pre class="output-preview">{html.escape(output_preview)}</pre>
                             </div>'''
 
+        # Use cases from knowledge base
+        use_cases = cmd.get("use_cases", [])
+        use_cases_html = ""
+        if use_cases:
+            use_cases_html = '<div class="use-cases-section"><h5>Use Cases:</h5><ul class="use-cases-list">'
+            for uc in use_cases[:3]:
+                use_cases_html += f'<li>{html.escape(uc)}</li>'
+            use_cases_html += '</ul></div>'
+
+        # Gotchas / pitfalls from knowledge base
+        gotchas = cmd.get("gotchas", [])
+        gotchas_html = ""
+        if gotchas:
+            gotchas_html = '<div class="gotchas-section"><h5>Common Pitfalls:</h5><ul class="gotchas-list">'
+            for g in gotchas[:2]:
+                gotchas_html += f'<li>{html.escape(g)}</li>'
+            gotchas_html += '</ul></div>'
+
+        # Related commands
+        related = cmd.get("related", [])
+        related_html = ""
+        if related:
+            related_chips = ' '.join(f'<code class="related-cmd">{html.escape(r)}</code>' for r in related[:5])
+            related_html = f'<div class="related-section"><h5>Related:</h5> {related_chips}</div>'
+
+        # Man page / documentation link
+        man_url = cmd.get("man_url", "")
+        man_link_html = ""
+        if man_url:
+            man_link_html = f'<a class="man-link" href="{html.escape(man_url)}" target="_blank" rel="noopener noreferrer" title="Documentation">docs</a>'
+
         commands_html += f'''
                         <div class="command-card" data-category="{category}" data-frequency="{frequency}" data-name="{base_cmd}">
                             <div class="command-header" onclick="toggleCommand('{cmd_id}')">
                                 <div class="command-main">
                                     <code class="cmd">{base_cmd}</code>
                                     <span class="category-badge">{category}</span>
+                                    {man_link_html}
                                 </div>
                                 <div class="command-meta">
                                     <span class="cmd-preview">{' '.join(description.split())[:60]}{'...' if len(' '.join(description.split())) > 60 else ''}</span>
@@ -448,7 +482,10 @@ def render_commands_tab(commands: list[dict]) -> str:
                                 </div>
                                 {subcmd_html}
                                 {flags_html}
+                                {use_cases_html}
+                                {gotchas_html}
                                 {patterns_html}
+                                {related_html}
                                 {output_html}
                             </div>
                         </div>'''
@@ -563,16 +600,38 @@ def render_lessons_tab(categories: dict, commands: list[dict]) -> str:
             if subcmd_desc:
                 lesson_subcmd = f'<div class="lesson-subcmd"><em>{html.escape(subcmd_desc)}</em></div>'
 
+            # Use cases and gotchas from COMMAND_DB for lessons
+            lesson_use_cases = ""
+            cmd_db_info = COMMAND_DB.get(base_cmd.replace("&amp;", "&"), {})
+            uc_list = cmd_db_info.get("use_cases", [])
+            if uc_list:
+                uc_items = ''.join(f'<li>{html.escape(uc)}</li>' for uc in uc_list[:2])
+                lesson_use_cases = f'<div class="lesson-use-cases"><strong>When to use:</strong><ul>{uc_items}</ul></div>'
+
+            lesson_gotchas = ""
+            gotcha_list = cmd_db_info.get("gotchas", [])
+            if gotcha_list:
+                g_items = ''.join(f'<li>{html.escape(g)}</li>' for g in gotcha_list[:1])
+                lesson_gotchas = f'<div class="lesson-gotchas"><strong>Watch out:</strong><ul>{g_items}</ul></div>'
+
+            lesson_man_url = ""
+            man_link = cmd_db_info.get("man_url", "")
+            if man_link:
+                lesson_man_url = f'<a class="man-link" href="{html.escape(man_link)}" target="_blank" rel="noopener noreferrer">docs</a>'
+
             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>
+                                    {lesson_man_url}
                                 </div>
                                 <pre class="syntax-highlighted">{highlighted}</pre>
                                 <p class="lesson-description">{description}</p>
                                 {lesson_subcmd}
                                 {lesson_flags_html}
+                                {lesson_use_cases}
+                                {lesson_gotchas}
                             </div>'''
 
         # Patterns observed
@@ -584,6 +643,23 @@ def render_lessons_tab(categories: dict, commands: list[dict]) -> str:
                 patterns_html += f'<li>{html.escape(pattern)}</li>'
             patterns_html += '</ul></div>'
 
+        # Collect related commands across this category for cross-reference
+        related_set = set()
+        cat_base_cmds = {c.get("base_command", "") for c in cat_cmd_data}
+        for cmd_item in cat_cmd_data:
+            bc = cmd_item.get("base_command", "").replace("&amp;", "&")
+            cmd_db_info = COMMAND_DB.get(bc, {})
+            for rel in cmd_db_info.get("related", []):
+                if rel not in cat_base_cmds:
+                    related_set.add(rel)
+        related_html = ""
+        if related_set:
+            related_chips = ' '.join(
+                f'<code class="related-cmd">{html.escape(r)}</code>'
+                for r in sorted(related_set)[:12]
+            )
+            related_html = f'<div class="lesson-related-section"><h4>Explore Related Commands:</h4><div class="related-chips">{related_chips}</div></div>'
+
         lessons_html += f'''
                     <div class="lesson-section">
                         <h2 class="lesson-title">
@@ -601,6 +677,7 @@ def render_lessons_tab(categories: dict, commands: list[dict]) -> str:
                                 {cat_commands_html}
                             </div>
                             {patterns_html}
+                            {related_html}
                         </div>
                     </div>'''
 
@@ -696,6 +773,12 @@ def render_quiz_tab(quizzes: list[dict]) -> str:
         options = quiz.get("options", [])
         correct = quiz.get("correct_answer", 0)
         explanation = html.escape(quiz.get("explanation", ""))
+        q_man_url = quiz.get("man_url", "")
+
+        # Doc link for quiz context
+        q_meta_html = ""
+        if q_man_url:
+            q_meta_html = f'<div class="quiz-meta"><a class="man-link" href="{html.escape(q_man_url)}" target="_blank" rel="noopener noreferrer">docs</a></div>'
 
         options_html = ""
         for opt_idx, option in enumerate(options):
@@ -709,7 +792,10 @@ def render_quiz_tab(quizzes: list[dict]) -> str:
 
         questions_html += f'''
                     <div class="quiz-question" id="question-{q_id}">
-                        <div class="question-number">Question {idx + 1}</div>
+                        <div class="question-header">
+                            <div class="question-number">Question {idx + 1}</div>
+                            {q_meta_html}
+                        </div>
                         <div class="question-text">{question}</div>
                         <div class="quiz-options">
                             {options_html}
@@ -859,6 +945,17 @@ def get_inline_css() -> str:
         .dark-icon { display: none; }
         [data-theme="dark"] .light-icon { display: none; }
         [data-theme="dark"] .dark-icon { display: inline; }
+        [data-theme="dark"] .gotchas-section,
+        [data-theme="dark"] .lesson-gotchas { background: #3e2723; border-left-color: #ff8f00; }
+        [data-theme="dark"] .gotchas-list li,
+        [data-theme="dark"] .lesson-gotchas li { color: #ffcc80; }
+        [data-theme="dark"] .gotchas-section h5,
+        [data-theme="dark"] .lesson-gotchas strong { color: #ffb300; }
+        [data-theme="dark"] .use-cases-list li,
+        [data-theme="dark"] .lesson-use-cases li { color: #b0bec5; }
+        [data-theme="dark"] .related-cmd { background: #1a237e; color: #90caf9; }
+        [data-theme="dark"] .man-link { background: #0d47a1; color: #90caf9; }
+        [data-theme="dark"] .subcmd-section { background: #0d253f; border-left-color: #4a9eff; }
 
         /* Tabs */
         .tabs {
@@ -1458,6 +1555,39 @@ def get_inline_css() -> str:
         .complexity-intermediate { background: #fff3e0; color: #e65100; }
         .complexity-advanced { background: #fce4ec; color: #c62828; }
 
+        /* Enrichment: use cases */
+        .use-cases-section, .lesson-use-cases { margin: 8px 0; }
+        .use-cases-section h5, .lesson-use-cases strong { margin: 4px 0; color: #1a73e8; font-size: 0.85em; }
+        .use-cases-list { padding-left: 18px; margin: 4px 0; }
+        .use-cases-list li, .lesson-use-cases li { margin: 4px 0; line-height: 1.5; font-size: 0.9em; color: #444; }
+        .lesson-use-cases ul { padding-left: 18px; margin: 4px 0; list-style: disc; }
+        .lesson-use-cases li { font-size: 0.85em; color: #555; }
+
+        /* Enrichment: gotchas / pitfalls */
+        .gotchas-section, .lesson-gotchas { margin: 8px 0; background: #fff8e1; padding: 8px 12px; border-radius: 6px; border-left: 3px solid #f9a825; }
+        .gotchas-section h5, .lesson-gotchas strong { margin: 4px 0; color: #f57f17; font-size: 0.85em; }
+        .gotchas-list { padding-left: 18px; margin: 4px 0; }
+        .gotchas-list li, .lesson-gotchas li { margin: 4px 0; line-height: 1.5; font-size: 0.9em; color: #5d4037; }
+        .lesson-gotchas ul { padding-left: 18px; margin: 4px 0; list-style: disc; }
+
+        /* Enrichment: related commands */
+        .related-section { margin: 8px 0; }
+        .related-section h5 { display: inline; margin-right: 6px; color: #666; font-size: 0.85em; }
+        .related-cmd { background: #e8eaf6; color: #3949ab; padding: 2px 8px; border-radius: 10px; font-size: 0.8em; margin-right: 4px; cursor: default; }
+
+        /* Enrichment: man page link */
+        .man-link { font-size: 0.75em; padding: 2px 8px; border-radius: 10px; background: #e3f2fd; color: #1565c0; text-decoration: none; margin-left: 8px; font-weight: 500; }
+        .man-link:hover { background: #bbdefb; text-decoration: none; }
+
+        /* Quiz enrichment */
+        .question-header { display: flex; justify-content: space-between; align-items: center; margin-bottom: 8px; }
+        .quiz-meta { display: flex; gap: 6px; align-items: center; }
+
+        /* Lesson related commands */
+        .lesson-related-section { margin: 16px 0 8px; padding: 12px; background: var(--bg-secondary); border-radius: var(--radius-md); border: 1px solid var(--border-color); }
+        .lesson-related-section h4 { font-size: 0.9em; color: var(--text-secondary); margin-bottom: 8px; }
+        .related-chips { display: flex; flex-wrap: wrap; gap: 6px; }
+
         .syntax-highlighted .string {
             color: #ff6d01;
         }
@@ -2379,6 +2509,11 @@ def generate_html_files(
             'common_patterns': common_patterns[:6],
             'args': cmd.get('args', []),
             'is_new': False,
+            'man_url': cmd_info.get('man_url', ''),
+            'use_cases': cmd_info.get('use_cases', []),
+            'gotchas': cmd_info.get('gotchas', []),
+            'related': cmd_info.get('related', []),
+            'difficulty': cmd_info.get('difficulty', ''),
         })
 
     # Transform complexity distribution from numeric keys to string labels
@@ -2430,11 +2565,19 @@ def generate_html_files(
             else:
                 option_texts.append(str(opt))
 
+        # Extract base command from command_context for enrichment lookup
+        cmd_ctx = quiz.get('command_context', '')
+        base_cmd = cmd_ctx.split()[0] if cmd_ctx else ''
+        q_cmd_info = COMMAND_DB.get(base_cmd, {})
+
         formatted_quizzes.append({
             'question': quiz.get('question', ''),
             'options': option_texts,
             'correct_answer': correct_idx,
             'explanation': quiz.get('explanation', ''),
+            'difficulty': q_cmd_info.get('difficulty', ''),
+            'man_url': q_cmd_info.get('man_url', ''),
+            'base_command': base_cmd,
         })
 
     # Generate HTML