learn_bash_from_session_data 1.0.4 → 1.0.5

package/bash-learner-output/run-2026-02-05-155949/summary.json

@@ -0,0 +1,163 @@
+{
+  "metadata": {
+    "generated_at": "2026-02-05T15:59:49.814630",
+    "run_id": "run-2026-02-05-155949",
+    "version": "1.0.5"
+  },
+  "input": {
+    "sessions_processed": 10,
+    "session_files": [
+      {
+        "filename": "081cfcfd-cde6-4304-89ca-6ac61faf8d85.jsonl",
+        "path": "/mnt/c/Users/brand/.claude/projects/C--Users-brand-Development-Project-Workspace-active-development-session-with-chris/081cfcfd-cde6-4304-89ca-6ac61faf8d85.jsonl",
+        "size": "759.1 KB",
+        "modified": "2026-02-05 11:01:08"
+      },
+      {
+        "filename": "2ee58010-e794-48d8-a1b7-0ba14e06e7b7.jsonl",
+        "path": "/mnt/c/Users/brand/.claude/projects/C--Users-brand/2ee58010-e794-48d8-a1b7-0ba14e06e7b7.jsonl",
+        "size": "1.8 KB",
+        "modified": "2026-02-05 10:22:23"
+      },
+      {
+        "filename": "ef6494ae-aca1-43b1-800d-d5586069d42c.jsonl",
+        "path": "/mnt/c/Users/brand/.claude/projects/C--Users-brand/ef6494ae-aca1-43b1-800d-d5586069d42c.jsonl",
+        "size": "1.8 KB",
+        "modified": "2026-01-23 14:32:05"
+      },
+      {
+        "filename": "6b1fb6cd-5865-4a5f-97f9-5e1e46d79f81.jsonl",
+        "path": "/mnt/c/Users/brand/.claude/projects/C--Users-brand/6b1fb6cd-5865-4a5f-97f9-5e1e46d79f81.jsonl",
+        "size": "3.7 KB",
+        "modified": "2026-01-19 22:44:52"
+      },
+      {
+        "filename": "9db5f466-5bc4-4778-94ba-b10d72e8c464.jsonl",
+        "path": "/mnt/c/Users/brand/.claude/projects/C--Users-brand/9db5f466-5bc4-4778-94ba-b10d72e8c464.jsonl",
+        "size": "916.0 B",
+        "modified": "2026-01-19 09:25:47"
+      },
+      {
+        "filename": "dfc82e92-9786-4baf-a5df-44046f21f90a.jsonl",
+        "path": "/mnt/c/Users/brand/.claude/projects/C--Users-brand-Development-Project-Workspace-active-development-en-consulta/dfc82e92-9786-4baf-a5df-44046f21f90a.jsonl",
+        "size": "1.0 KB",
+        "modified": "2026-01-16 06:42:34"
+      },
+      {
+        "filename": "b3c0facc-2728-48a5-a1d0-0fed6b049cf2.jsonl",
+        "path": "/mnt/c/Users/brand/.claude/projects/C--Users-brand/b3c0facc-2728-48a5-a1d0-0fed6b049cf2.jsonl",
+        "size": "116.0 B",
+        "modified": "2026-01-08 21:01:17"
+      },
+      {
+        "filename": "846d1c3c-05e3-4d86-9aae-c8bd266962d4.jsonl",
+        "path": "/mnt/c/Users/brand/.claude/projects/C--Users-brand/846d1c3c-05e3-4d86-9aae-c8bd266962d4.jsonl",
+        "size": "1.8 KB",
+        "modified": "2026-01-08 21:00:57"
+      },
+      {
+        "filename": "agent-a979d7c.jsonl",
+        "path": "/mnt/c/Users/brand/.claude/projects/C--Users-brand/agent-a979d7c.jsonl",
+        "size": "2.0 KB",
+        "modified": "2026-01-06 20:47:47"
+      },
+      {
+        "filename": "agent-a1fb460.jsonl",
+        "path": "/mnt/c/Users/brand/.claude/projects/C--Users-brand/agent-a1fb460.jsonl",
+        "size": "1.9 KB",
+        "modified": "2026-01-06 20:47:44"
+      }
+    ],
+    "total_entries": 438
+  },
+  "analysis": {
+    "raw_commands_found": 37,
+    "unique_commands": 53,
+    "categories": [
+      "Unknown",
+      "Package Management",
+      "Text Processing",
+      "File System",
+      "Shell Builtins",
+      "Development",
+      "Git",
+      "Search & Navigation",
+      "Process & System"
+    ],
+    "category_counts": {
+      "Unknown": 5,
+      "Package Management": 4,
+      "Text Processing": 3,
+      "File System": 7,
+      "Shell Builtins": 3,
+      "Development": 5,
+      "Git": 24,
+      "Search & Navigation": 1,
+      "Process & System": 1
+    },
+    "top_base_commands": [
+      {
+        "command": "cd",
+        "count": 18
+      },
+      {
+        "command": "git",
+        "count": 17
+      },
+      {
+        "command": "gh",
+        "count": 9
+      },
+      {
+        "command": "python",
+        "count": 5
+      },
+      {
+        "command": "mkdir",
+        "count": 3
+      },
+      {
+        "command": "ls",
+        "count": 3
+      },
+      {
+        "command": "echo",
+        "count": 3
+      },
+      {
+        "command": "session-slides",
+        "count": 3
+      },
+      {
+        "command": "pip",
+        "count": 2
+      },
+      {
+        "command": "head",
+        "count": 2
+      }
+    ],
+    "operators_used": {
+      "||": 4,
+      "|": 3,
+      "2>&1": 8,
+      "2>/dev/null": 5,
+      "&&": 29,
+      ">": 5,
+      "<": 13
+    },
+    "complexity_distribution": {
+      "1": 10,
+      "2": 23,
+      "3": 15,
+      "4": 3,
+      "5": 2
+    }
+  },
+  "output": {
+    "quiz_questions": 20,
+    "html_files": [
+      "bash-learner-output/run-2026-02-05-155949/index.html"
+    ]
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "learn_bash_from_session_data",
-  "version": "1.0.4",
+  "version": "1.0.5",
   "description": "Learn bash from your Claude Code sessions - extracts commands and generates interactive HTML lessons",
   "main": "bin/learn-bash.js",
   "bin": {

package/scripts/html_generator.py

@@ -114,19 +114,52 @@ def _generate_html_impl(analysis_result: dict[str, Any], quizzes: list[dict[str,
 </html>'''
 
 
+def _generate_operators_html(operators_used: dict, operator_descriptions: dict) -> str:
+    """Generate HTML for the operators used section."""
+    if not operators_used:
+        return '<p class="empty-state">No bash operators detected in these commands</p>'
+
+    operators_html = ""
+    # Sort by count descending
+    sorted_ops = sorted(operators_used.items(), key=lambda x: -x[1])
+    max_count = sorted_ops[0][1] if sorted_ops else 1
+
+    for op, count in sorted_ops:
+        name, desc = operator_descriptions.get(op, (op, 'Bash operator'))
+        bar_width = (count / max_count) * 100
+        operators_html += f'''
+                                <div class="operator-item">
+                                    <div class="operator-symbol"><code>{html.escape(op)}</code></div>
+                                    <div class="operator-info">
+                                        <div class="operator-name">{html.escape(name)}</div>
+                                        <div class="operator-desc">{html.escape(desc)}</div>
+                                    </div>
+                                    <div class="operator-bar-container">
+                                        <div class="operator-bar" style="width: {bar_width}%"></div>
+                                    </div>
+                                    <div class="operator-count">{count}</div>
+                                </div>'''
+    return operators_html
+
+
 def render_overview_tab(stats: dict[str, Any], commands: list[dict], categories: dict) -> str:
     """Render the overview/dashboard tab content."""
     total_commands = stats.get("total_commands", 0)
     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"})
-    complexity_dist = stats.get("complexity_distribution", {"simple": 0, "intermediate": 0, "advanced": 0})
-
-    # Calculate percentages for complexity bars
-    total_for_pct = sum(complexity_dist.values()) or 1
-    simple_pct = (complexity_dist.get("simple", 0) / total_for_pct) * 100
-    intermediate_pct = (complexity_dist.get("intermediate", 0) / total_for_pct) * 100
-    advanced_pct = (complexity_dist.get("advanced", 0) / total_for_pct) * 100
+    # Get operators data for the "Bash Operators Used" section
+    operators_used = stats.get("operators_used", {})
+    operator_descriptions = {
+        '|': ('Pipe', 'Sends output of one command to input of another'),
+        '||': ('OR operator', 'Run next command if previous failed'),
+        '&&': ('AND operator', 'Run next command if previous succeeded'),
+        '2>&1': ('Redirect stderr', 'Combines error output with standard output'),
+        '2>/dev/null': ('Suppress errors', 'Discards error messages'),
+        '>': ('Redirect output', 'Writes output to a file (overwrites)'),
+        '>>': ('Append output', 'Appends output to a file'),
+        '<': ('Redirect input', 'Reads input from a file'),
+    }
 
     # Top 10 commands by frequency - use pre-computed data if available
     top_commands_data = stats.get("top_commands", [])
@@ -237,29 +270,9 @@ def render_overview_tab(stats: dict[str, Any], commands: list[dict], categories:
 
                     <div class="charts-row">
                         <div class="chart-card">
-                            <h3>Complexity Distribution</h3>
-                            <div class="complexity-bars">
-                                <div class="complexity-row">
-                                    <span class="complexity-label simple">Simple</span>
-                                    <div class="complexity-bar-bg">
-                                        <div class="complexity-bar simple" style="width: {simple_pct}%"></div>
-                                    </div>
-                                    <span class="complexity-count">{complexity_dist.get("simple", 0)}</span>
-                                </div>
-                                <div class="complexity-row">
-                                    <span class="complexity-label intermediate">Intermediate</span>
-                                    <div class="complexity-bar-bg">
-                                        <div class="complexity-bar intermediate" style="width: {intermediate_pct}%"></div>
-                                    </div>
-                                    <span class="complexity-count">{complexity_dist.get("intermediate", 0)}</span>
-                                </div>
-                                <div class="complexity-row">
-                                    <span class="complexity-label advanced">Advanced</span>
-                                    <div class="complexity-bar-bg">
-                                        <div class="complexity-bar advanced" style="width: {advanced_pct}%"></div>
-                                    </div>
-                                    <span class="complexity-count">{complexity_dist.get("advanced", 0)}</span>
-                                </div>
+                            <h3>Bash Operators Used</h3>
+                            <div class="operators-list">
+                                {_generate_operators_html(operators_used, operator_descriptions)}
                             </div>
                         </div>
 
@@ -385,11 +398,10 @@ def render_commands_tab(commands: list[dict]) -> str:
                             </div>'''
 
         commands_html += f'''
-                        <div class="command-card" data-category="{category}" data-complexity="{complexity}" data-frequency="{frequency}" data-name="{base_cmd}">
+                        <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="complexity-badge {complexity}">{complexity}</span>
                                     <span class="category-badge">{category}</span>
                                 </div>
                                 <div class="command-meta">
@@ -504,7 +516,6 @@ def render_lessons_tab(categories: dict, commands: list[dict]) -> str:
                             <div class="lesson-command">
                                 <div class="lesson-command-header">
                                     <code class="cmd">{base_cmd}</code>
-                                    <span class="complexity-badge {complexity}">{complexity}</span>
                                 </div>
                                 <pre class="syntax-highlighted">{highlighted}</pre>
                                 <p class="lesson-description">{description}</p>
@@ -990,6 +1001,77 @@ def get_inline_css() -> str:
             color: var(--text-secondary);
         }
 
+        /* Operators List */
+        .operators-list {
+            display: flex;
+            flex-direction: column;
+            gap: 12px;
+        }
+
+        .operator-item {
+            display: grid;
+            grid-template-columns: 80px 1fr 120px 50px;
+            align-items: center;
+            gap: 12px;
+            padding: 8px 0;
+            border-bottom: 1px solid var(--border-color);
+        }
+
+        .operator-item:last-child {
+            border-bottom: none;
+        }
+
+        .operator-symbol {
+            font-family: var(--font-mono);
+            font-size: 1rem;
+            font-weight: 600;
+            color: var(--accent-primary);
+        }
+
+        .operator-symbol code {
+            background: var(--bg-tertiary);
+            padding: 4px 8px;
+            border-radius: var(--radius-sm);
+        }
+
+        .operator-info {
+            display: flex;
+            flex-direction: column;
+            gap: 2px;
+        }
+
+        .operator-name {
+            font-size: 0.9rem;
+            font-weight: 600;
+            color: var(--text-primary);
+        }
+
+        .operator-desc {
+            font-size: 0.8rem;
+            color: var(--text-secondary);
+        }
+
+        .operator-bar-container {
+            height: 20px;
+            background: var(--bg-tertiary);
+            border-radius: var(--radius-sm);
+            overflow: hidden;
+        }
+
+        .operator-bar {
+            height: 100%;
+            background: var(--accent-primary);
+            border-radius: var(--radius-sm);
+            transition: width 0.5s ease;
+        }
+
+        .operator-count {
+            font-size: 0.9rem;
+            font-weight: 600;
+            text-align: right;
+            color: var(--text-secondary);
+        }
+
         /* Pie Chart */
         .pie-container {
             display: flex;
@@ -2081,6 +2163,7 @@ def generate_html_files(
             'complexity_avg': stats.get('average_complexity', 2),
             'complexity_distribution': complexity_distribution,
             'top_commands': top_10_commands,  # Pre-computed top commands with frequencies
+            'operators_used': analysis.get('operators_used', {}),  # Bash operators like ||, &&, |, 2>&1
         },
         'commands': formatted_commands,
         'categories': {cat: [c.get('command', '') for c in cmds] for cat, cmds in categories.items()},

package/scripts/main.py

@@ -319,11 +319,66 @@ def run_extraction_pipeline(
     parsed_commands = parse_commands(raw_commands)
     print(f"  -> Parsed {len(parsed_commands)} commands")
 
-    # Step 4: Count frequencies BEFORE deduplication
+    # Step 4: Expand compound commands into individual sub-commands
+    # Also count operators for tracking
     from collections import Counter
+    import re
+
+    operator_frequency = Counter()
+    expanded_commands = []
+
+    # Operator patterns to detect
+    operator_patterns = {
+        '||': r'\|\|',
+        '&&': r'&&',
+        '|': r'(?<!\|)\|(?!\|)',  # Single pipe, not ||
+        '2>&1': r'2>&1',
+        '2>/dev/null': r'2>/dev/null',
+        '>': r'(?<![2&])>(?!>|&)',  # Single >, not >> or 2> or >&
+        '>>': r'>>',
+        '<': r'<(?!<)',
+    }
+
+    for cmd in parsed_commands:
+        cmd_str = cmd.get('command', '') or cmd.get('raw', '')
+        if not cmd_str:
+            continue
+
+        # Count operators in this command
+        for op_name, op_pattern in operator_patterns.items():
+            matches = re.findall(op_pattern, cmd_str)
+            if matches:
+                operator_frequency[op_name] += len(matches)
+
+        # Check if this is a compound command
+        is_compound = any(op in cmd_str for op in ['||', '&&', ' | ', ';'])
+
+        if is_compound:
+            # Extract individual sub-commands from compound statement
+            sub_commands = extract_sub_commands(cmd_str)
+            for sub_cmd in sub_commands:
+                if sub_cmd.strip():
+                    expanded_commands.append({
+                        'command': sub_cmd.strip(),
+                        'raw': sub_cmd.strip(),
+                        'original_compound': cmd_str,
+                        'description': cmd.get('description', ''),
+                        'output': cmd.get('output', ''),
+                    })
+        else:
+            # Simple command - add as-is
+            expanded_commands.append(cmd)
+
+    print(f"  -> Expanded to {len(expanded_commands)} individual commands")
+
+    # Step 5: Re-parse expanded commands to get proper base_command for each
+    parsed_expanded = parse_commands(expanded_commands)
+
+    # Step 6: Count frequencies BEFORE deduplication
     cmd_frequency = Counter()
     base_cmd_frequency = Counter()
-    for cmd in parsed_commands:
+
+    for cmd in parsed_expanded:
         cmd_str = cmd.get('command', '') or cmd.get('raw', '')
         base_cmd = cmd.get('base_command', '')
         if cmd_str:
@@ -331,8 +386,8 @@ def run_extraction_pipeline(
         if base_cmd:
             base_cmd_frequency[base_cmd] += 1
 
-    # Step 5: Deduplicate and add frequency data
-    unique_commands = deduplicate_commands(parsed_commands)
+    # Step 7: Deduplicate and add frequency data
+    unique_commands = deduplicate_commands(parsed_expanded)
 
     # Add frequency to each unique command
     for cmd in unique_commands:
@@ -357,6 +412,7 @@ def run_extraction_pipeline(
     analysis['base_command_frequency'] = dict(base_cmd_frequency)
     analysis['top_commands'] = cmd_frequency.most_common(20)
     analysis['top_base_commands'] = base_cmd_frequency.most_common(20)
+    analysis['operators_used'] = dict(operator_frequency)
     print(f"  -> Generated analysis with {len(analysis.get('categories', {}))} categories")
 
     # Step 6: Generate quizzes
@@ -375,7 +431,7 @@ def run_extraction_pipeline(
         "metadata": {
             "generated_at": datetime.now().isoformat(),
             "run_id": output_dir.name,
-            "version": "1.0.4",
+            "version": "1.0.5",
         },
         "input": {
             "sessions_processed": len(sessions),
@@ -399,6 +455,7 @@ def run_extraction_pipeline(
                 {"command": cmd, "count": count}
                 for cmd, count in list(base_cmd_frequency.most_common(10))
             ],
+            "operators_used": dict(operator_frequency),
             "complexity_distribution": dict(analysis.get('complexity_distribution', {})),
         },
         "output": {
@@ -416,6 +473,54 @@ def run_extraction_pipeline(
     return True, f"Successfully generated learning materials in {output_dir}"
 
 
+def extract_sub_commands(cmd_str: str) -> List[str]:
+    """
+    Extract individual sub-commands from a compound command.
+
+    Splits commands by ||, &&, |, and ; while preserving each sub-command
+    as a learnable unit.
+
+    Args:
+        cmd_str: The compound command string
+
+    Returns:
+        List of individual sub-command strings
+    """
+    import re
+
+    # First, clean up redirections but keep them with their command
+    # We want "pip show pkg 2>/dev/null" to stay together
+
+    # Split by compound operators: ||, &&, |, ;
+    # Use regex to split while handling edge cases
+    # Note: | needs special handling to not match ||
+
+    sub_commands = []
+
+    # Split by || first (highest precedence for our purposes)
+    or_parts = re.split(r'\s*\|\|\s*', cmd_str)
+
+    for or_part in or_parts:
+        # Split each part by &&
+        and_parts = re.split(r'\s*&&\s*', or_part)
+
+        for and_part in and_parts:
+            # Split each part by ; (sequential)
+            seq_parts = re.split(r'\s*;\s*', and_part)
+
+            for seq_part in seq_parts:
+                # Split by single pipe |
+                # Use negative lookbehind/lookahead to avoid ||
+                pipe_parts = re.split(r'(?<!\|)\|(?!\|)', seq_part)
+
+                for pipe_part in pipe_parts:
+                    cleaned = pipe_part.strip()
+                    if cleaned:
+                        sub_commands.append(cleaned)
+
+    return sub_commands
+
+
 def deduplicate_commands(commands: List[Dict]) -> List[Dict]:
     """
     Remove duplicate commands while preserving order.

package/scripts/quiz_generator.py

@@ -397,37 +397,98 @@ def _generate_bash_description(cmd_string: str) -> str:
     Generate an educational description focusing on bash concepts.
 
     Explains what each part of the command does from a bash perspective.
+    Handles: &&, ||, |, 2>&1, 2>/dev/null, and combinations.
     """
     if not cmd_string:
         return "Runs a command"
 
+    # Clean up redirections for description (note them but don't clutter)
+    has_stderr_to_stdout = '2>&1' in cmd_string
+    has_stderr_to_null = '2>/dev/null' in cmd_string
+    has_stdout_redirect = re.search(r'>\s*\S+', cmd_string) and '2>' not in cmd_string
+
+    # Remove redirections for parsing (we'll note them separately)
+    clean_cmd = re.sub(r'\s*2>&1\s*', ' ', cmd_string)
+    clean_cmd = re.sub(r'\s*2>/dev/null\s*', ' ', clean_cmd)
+    clean_cmd = re.sub(r'\s*>\s*\S+\s*', ' ', clean_cmd)
+    clean_cmd = ' '.join(clean_cmd.split())  # normalize whitespace
+
     parts = []
 
-    # Check for command chaining
-    if ' && ' in cmd_string:
-        commands = cmd_string.split(' && ')
+    # Handle && (run if previous succeeds)
+    if ' && ' in clean_cmd:
+        commands = clean_cmd.split(' && ')
         for i, cmd in enumerate(commands):
-            base = cmd.strip().split()[0] if cmd.strip() else ''
-            if i == 0:
-                parts.append(_describe_single_command(cmd.strip()))
+            cmd = cmd.strip()
+            if not cmd:
+                continue
+            # Handle nested || or | within && segments
+            if ' || ' in cmd:
+                parts.append(_describe_or_chain(cmd))
+            elif ' | ' in cmd:
+                parts.append(_describe_pipe_chain(cmd))
+            elif i == 0:
+                parts.append(_describe_single_command(cmd))
             else:
-                parts.append(f"then {_describe_single_command(cmd.strip())}")
-        return ', '.join(parts)
-
-    if ' || ' in cmd_string:
-        commands = cmd_string.split(' || ')
-        parts.append(_describe_single_command(commands[0].strip()))
-        parts.append(f"or if that fails, {_describe_single_command(commands[1].strip())}")
-        return ', '.join(parts)
-
-    if ' | ' in cmd_string:
-        commands = cmd_string.split(' | ')
-        parts.append(_describe_single_command(commands[0].strip()))
-        for cmd in commands[1:]:
-            parts.append(f"pipes output to {_describe_single_command(cmd.strip())}")
-        return ', '.join(parts)
-
-    return _describe_single_command(cmd_string)
+                parts.append(f"then {_describe_single_command(cmd)}")
+
+    # Handle || (run if previous fails)
+    elif ' || ' in clean_cmd:
+        parts.append(_describe_or_chain(clean_cmd))
+
+    # Handle | (pipe)
+    elif ' | ' in clean_cmd:
+        parts.append(_describe_pipe_chain(clean_cmd))
+
+    else:
+        parts.append(_describe_single_command(clean_cmd))
+
+    result = ', '.join(parts)
+
+    # Add redirection notes
+    if has_stderr_to_null:
+        result += " (suppressing errors)"
+    elif has_stderr_to_stdout:
+        result += " (capturing all output)"
+
+    return result
+
+
+def _describe_or_chain(cmd_string: str) -> str:
+    """Describe an || chain (fallback pattern)."""
+    commands = cmd_string.split(' || ')
+    parts = []
+    for i, cmd in enumerate(commands):
+        cmd = cmd.strip()
+        if not cmd:
+            continue
+        # Handle pipes within || segments
+        if ' | ' in cmd:
+            desc = _describe_pipe_chain(cmd)
+        else:
+            desc = _describe_single_command(cmd)
+
+        if i == 0:
+            parts.append(desc)
+        else:
+            parts.append(f"or if that fails, {desc}")
+    return ', '.join(parts)
+
+
+def _describe_pipe_chain(cmd_string: str) -> str:
+    """Describe a pipe chain."""
+    commands = cmd_string.split(' | ')
+    parts = []
+    for i, cmd in enumerate(commands):
+        cmd = cmd.strip()
+        if not cmd:
+            continue
+        desc = _describe_single_command(cmd)
+        if i == 0:
+            parts.append(desc)
+        else:
+            parts.append(f"pipes to {desc}")
+    return ', '.join(parts)
 
 
 def _describe_single_command(cmd: str) -> str: