learn_bash_from_session_data 1.0.2 → 1.0.4

package/package.json

@@ -1,16 +1,23 @@
 {
   "name": "learn_bash_from_session_data",
-  "version": "1.0.2",
+  "version": "1.0.4",
   "description": "Learn bash from your Claude Code sessions - extracts commands and generates interactive HTML lessons",
   "main": "bin/learn-bash.js",
   "bin": {
-    "learn-bash": "./bin/learn-bash.js",
-    "bash-learner": "./bin/learn-bash.js"
+    "learn-bash": "bin/learn-bash.js",
+    "bash-learner": "bin/learn-bash.js"
   },
   "scripts": {
     "test": "node tests/test-runner.js"
   },
-  "keywords": ["bash", "learning", "claude", "cli", "terminal", "shell"],
+  "keywords": [
+    "bash",
+    "learning",
+    "claude",
+    "cli",
+    "terminal",
+    "shell"
+  ],
   "author": "",
   "license": "MIT",
   "engines": {
@@ -18,6 +25,6 @@
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/bjpl/learn_bash_from_session_data"
+    "url": "git+https://github.com/bjpl/learn_bash_from_session_data.git"
   }
 }

package/scripts/html_generator.py

@@ -128,16 +128,37 @@ def render_overview_tab(stats: dict[str, Any], commands: list[dict], categories:
     intermediate_pct = (complexity_dist.get("intermediate", 0) / total_for_pct) * 100
     advanced_pct = (complexity_dist.get("advanced", 0) / total_for_pct) * 100
 
-    # Top 10 commands by frequency
-    sorted_commands = sorted(commands, key=lambda x: x.get("frequency", 0), reverse=True)[:10]
+    # Top 10 commands by frequency - use pre-computed data if available
+    top_commands_data = stats.get("top_commands", [])
     top_commands_html = ""
-    max_freq = sorted_commands[0].get("frequency", 1) if sorted_commands else 1
 
-    for cmd in sorted_commands:
-        freq = cmd.get("frequency", 0)
-        bar_width = (freq / max_freq) * 100
-        cmd_name = html.escape(cmd.get("base_command", "unknown"))
-        top_commands_html += f'''
+    if top_commands_data:
+        max_freq = top_commands_data[0].get("count", 1) if top_commands_data else 1
+        for item in top_commands_data[:10]:
+            cmd_str = item.get("command", "")
+            freq = item.get("count", 1)
+            bar_width = (freq / max_freq) * 100
+            # Extract base command from full command
+            cmd_name = html.escape(cmd_str.split()[0] if cmd_str else "unknown")
+            top_commands_html += f'''
+                        <div class="top-command-item">
+                            <div class="top-command-name">
+                                <code class="cmd">{cmd_name}</code>
+                            </div>
+                            <div class="top-command-bar-container">
+                                <div class="top-command-bar" style="width: {bar_width}%"></div>
+                            </div>
+                            <div class="top-command-count">{freq}</div>
+                        </div>'''
+    else:
+        # Fallback to sorting commands by frequency
+        sorted_commands = sorted(commands, key=lambda x: x.get("frequency", 0), reverse=True)[:10]
+        max_freq = sorted_commands[0].get("frequency", 1) if sorted_commands else 1
+        for cmd in sorted_commands:
+            freq = cmd.get("frequency", 0)
+            bar_width = (freq / max_freq) * 100
+            cmd_name = html.escape(cmd.get("base_command", "unknown"))
+            top_commands_html += f'''
                         <div class="top-command-item">
                             <div class="top-command-name">
                                 <code class="cmd">{cmd_name}</code>
@@ -1986,6 +2007,27 @@ def generate_html_files(
     categories = analysis.get('categories', {})
     analyzed_commands = analysis.get('commands', commands)
 
+    # Build frequency map from top_commands (full command strings)
+    top_commands_data = analysis.get('top_commands', [])
+    frequency_map = {}
+    for item in top_commands_data:
+        if isinstance(item, (list, tuple)) and len(item) >= 2:
+            cmd_str, count = item[0], item[1]
+            frequency_map[cmd_str] = count
+
+    # Get base command frequency for the "Top 10 Most-Used Commands" chart
+    # This aggregates by base command (cd, git, mkdir) not full command strings
+    top_base_commands_data = analysis.get('top_base_commands', [])
+
+    # Map complexity scores (1-5) to string labels for CSS
+    def complexity_to_label(score):
+        if score <= 2:
+            return 'simple'
+        elif score == 3:
+            return 'intermediate'
+        else:
+            return 'advanced'
+
     # Transform commands to expected format
     formatted_commands = []
     for cmd in analyzed_commands:
@@ -1998,23 +2040,47 @@ def generate_html_files(
             elif isinstance(f, str):
                 formatted_flags.append({'flag': f, 'description': ''})
 
+        cmd_str = cmd.get('command', '')
+        complexity_score = cmd.get('complexity', 1)
+
         formatted_commands.append({
-            'base_command': cmd.get('base_command', cmd.get('command', '').split()[0] if cmd.get('command') else ''),
-            'full_command': cmd.get('command', ''),
+            'base_command': cmd.get('base_command', cmd_str.split()[0] if cmd_str else ''),
+            'full_command': cmd_str,
             'category': cmd.get('category', 'Other'),
-            'complexity': cmd.get('complexity', 1),
-            'frequency': cmd.get('frequency', 1),
+            'complexity': complexity_to_label(complexity_score),
+            'complexity_score': complexity_score,
+            'frequency': frequency_map.get(cmd_str, 1),
             'description': cmd.get('description', ''),
             'flags': formatted_flags,
             'is_new': False,
         })
 
+    # Transform complexity distribution from numeric keys to string labels
+    raw_complexity = stats.get('complexity_distribution', {})
+    complexity_distribution = {
+        'simple': raw_complexity.get(1, 0) + raw_complexity.get(2, 0),
+        'intermediate': raw_complexity.get(3, 0),
+        'advanced': raw_complexity.get(4, 0) + raw_complexity.get(5, 0),
+    }
+
+    # Build top commands list with proper frequencies (by base command)
+    top_10_commands = []
+    for item in top_base_commands_data[:10]:
+        if isinstance(item, (list, tuple)) and len(item) >= 2:
+            top_10_commands.append({
+                'command': item[0],  # base command like "cd", "git"
+                'count': item[1]
+            })
+
     analysis_result = {
         'stats': {
             'total_commands': stats.get('total_commands', len(commands)),
             'unique_commands': stats.get('unique_commands', len(commands)),
+            'unique_utilities': stats.get('unique_base_commands', 0),
             'total_categories': len(categories),
             'complexity_avg': stats.get('average_complexity', 2),
+            'complexity_distribution': complexity_distribution,
+            'top_commands': top_10_commands,  # Pre-computed top commands with frequencies
         },
         'commands': formatted_commands,
         'categories': {cat: [c.get('command', '') for c in cmds] for cat, cmds in categories.items()},

package/scripts/main.py

@@ -20,10 +20,24 @@ if sys.version_info < (3, 8):
              f"{sys.version_info.major}.{sys.version_info.minor}")
 
 # Constants
-DEFAULT_OUTPUT_DIR = "./bash-learner-output/"
+DEFAULT_OUTPUT_BASE = "./bash-learner-output"
 MAX_UNIQUE_COMMANDS = 500
 
 
+def generate_timestamped_output_dir(base_dir: str = DEFAULT_OUTPUT_BASE) -> Path:
+    """
+    Generate a timestamped output directory.
+
+    Args:
+        base_dir: Base directory for outputs
+
+    Returns:
+        Path to timestamped output directory (e.g., ./bash-learner-output/run-2026-02-05-143052/)
+    """
+    timestamp = datetime.now().strftime("%Y-%m-%d-%H%M%S")
+    return Path(base_dir) / f"run-{timestamp}"
+
+
 def get_sessions_base_path() -> Path:
     """
     Get the base path for Claude session files.
@@ -305,8 +319,28 @@ def run_extraction_pipeline(
     parsed_commands = parse_commands(raw_commands)
     print(f"  -> Parsed {len(parsed_commands)} commands")
 
-    # Step 4: Deduplicate and cap
+    # Step 4: Count frequencies BEFORE deduplication
+    from collections import Counter
+    cmd_frequency = Counter()
+    base_cmd_frequency = Counter()
+    for cmd in parsed_commands:
+        cmd_str = cmd.get('command', '') or cmd.get('raw', '')
+        base_cmd = cmd.get('base_command', '')
+        if cmd_str:
+            cmd_frequency[cmd_str] += 1
+        if base_cmd:
+            base_cmd_frequency[base_cmd] += 1
+
+    # Step 5: Deduplicate and add frequency data
     unique_commands = deduplicate_commands(parsed_commands)
+
+    # Add frequency to each unique command
+    for cmd in unique_commands:
+        cmd_str = cmd.get('command', '') or cmd.get('raw', '')
+        base_cmd = cmd.get('base_command', '')
+        cmd['frequency'] = cmd_frequency.get(cmd_str, 1)
+        cmd['base_frequency'] = base_cmd_frequency.get(base_cmd, 1)
+
     if len(unique_commands) > MAX_UNIQUE_COMMANDS:
         print(f"\nCapping at {MAX_UNIQUE_COMMANDS} unique commands "
               f"(found {len(unique_commands)})")
@@ -314,9 +348,15 @@ def run_extraction_pipeline(
     else:
         print(f"\n{len(unique_commands)} unique commands")
 
-    # Step 5: Analyze commands
+    # Step 6: Analyze commands
     print("\nAnalyzing commands...")
     analysis = analyze_commands(unique_commands)
+
+    # Inject pre-computed frequency data into analysis
+    analysis['command_frequency'] = dict(cmd_frequency)
+    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)
     print(f"  -> Generated analysis with {len(analysis.get('categories', {}))} categories")
 
     # Step 6: Generate quizzes
@@ -330,16 +370,41 @@ def run_extraction_pipeline(
     html_files = generate_html(unique_commands, analysis, quizzes, output_dir)
     print(f"  -> Created {len(html_files)} HTML files")
 
-    # Write summary JSON
+    # Write summary JSON with comprehensive metadata
     summary = {
-        "generated_at": datetime.now().isoformat(),
-        "sessions_processed": len(sessions),
-        "total_entries": len(all_entries),
-        "raw_commands": len(raw_commands),
-        "unique_commands": len(unique_commands),
-        "categories": list(analysis.get('categories', {}).keys()),
-        "quiz_count": quiz_count,
-        "html_files": [str(f) for f in html_files],
+        "metadata": {
+            "generated_at": datetime.now().isoformat(),
+            "run_id": output_dir.name,
+            "version": "1.0.4",
+        },
+        "input": {
+            "sessions_processed": len(sessions),
+            "session_files": [
+                {
+                    "filename": s['filename'],
+                    "path": str(s['path']),
+                    "size": s['size_human'],
+                    "modified": s['modified_str']
+                }
+                for s in sessions
+            ],
+            "total_entries": len(all_entries),
+        },
+        "analysis": {
+            "raw_commands_found": len(raw_commands),
+            "unique_commands": len(unique_commands),
+            "categories": list(analysis.get('categories', {}).keys()),
+            "category_counts": {cat: len(cmds) for cat, cmds in analysis.get('categories', {}).items()},
+            "top_base_commands": [
+                {"command": cmd, "count": count}
+                for cmd, count in list(base_cmd_frequency.most_common(10))
+            ],
+            "complexity_distribution": dict(analysis.get('complexity_distribution', {})),
+        },
+        "output": {
+            "quiz_questions": quiz_count,
+            "html_files": [str(f) for f in html_files],
+        },
     }
 
     summary_path = output_dir / "summary.json"
@@ -405,8 +470,8 @@ Examples:
     parser.add_argument(
         '-o', '--output',
         type=str,
-        default=DEFAULT_OUTPUT_DIR,
-        help=f'Output directory (default: {DEFAULT_OUTPUT_DIR})'
+        default=None,
+        help=f'Output directory (default: timestamped folder in {DEFAULT_OUTPUT_BASE}/)'
     )
 
     parser.add_argument(
@@ -487,8 +552,11 @@ def main() -> int:
 
         sessions_to_process = sessions
 
-    # Run the pipeline
-    output_dir = Path(args.output)
+    # Run the pipeline with timestamped output directory
+    if args.output:
+        output_dir = Path(args.output)
+    else:
+        output_dir = generate_timestamped_output_dir()
     success, message = run_extraction_pipeline(sessions_to_process, output_dir)
 
     if success:

package/scripts/quiz_generator.py

@@ -392,6 +392,170 @@ def _get_related_commands(cmd: str) -> list[str]:
     return []
 
 
+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.
+    """
+    if not cmd_string:
+        return "Runs a command"
+
+    parts = []
+
+    # Check for command chaining
+    if ' && ' in cmd_string:
+        commands = cmd_string.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()))
+            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)
+
+
+def _describe_single_command(cmd: str) -> str:
+    """Generate description for a single command (no pipes/chains)."""
+    if not cmd:
+        return "runs a command"
+
+    tokens = cmd.split()
+    base_cmd = tokens[0] if tokens else ''
+
+    # Common command descriptions with bash focus
+    descriptions = {
+        'cd': lambda args: f"changes directory to {args[0] if args else 'specified path'}",
+        'ls': lambda args: f"lists {'files in ' + args[0] if args else 'directory contents'}",
+        'mkdir': lambda args: f"creates directory {args[0] if args else ''}",
+        'rm': lambda args: f"removes {args[0] if args else 'files'}",
+        'cp': lambda args: f"copies files{' to ' + args[-1] if len(args) > 1 else ''}",
+        'mv': lambda args: f"moves/renames files{' to ' + args[-1] if len(args) > 1 else ''}",
+        'cat': lambda args: f"displays contents of {args[0] if args else 'file'}",
+        'echo': lambda args: f"prints {'text' if not args else repr(' '.join(args)[:30])}",
+        'grep': lambda args: f"searches for pattern in {'files' if len(args) > 1 else 'input'}",
+        'find': lambda args: f"finds files{' in ' + args[0] if args else ''} matching criteria",
+        'git': lambda args: f"runs git {args[0] if args else 'command'}" + _describe_git_subcommand(args),
+        'python': lambda args: "executes Python script" + (' from heredoc' if '<<' in cmd else ''),
+        'python3': lambda args: "executes Python 3 script" + (' from heredoc' if '<<' in cmd else ''),
+        'npm': lambda args: f"runs npm {args[0] if args else 'command'}",
+        'pip': lambda args: f"runs pip {args[0] if args else 'command'}",
+        'docker': lambda args: f"runs docker {args[0] if args else 'command'}",
+        'chmod': lambda args: f"changes permissions{' to ' + args[0] if args else ''}",
+        'chown': lambda args: "changes file ownership",
+        'curl': lambda args: "fetches URL content",
+        'wget': lambda args: "downloads file from URL",
+        'tar': lambda args: "archives/extracts tar files",
+        'ssh': lambda args: f"connects via SSH{' to ' + args[0] if args else ''}",
+        'sudo': lambda args: f"runs as superuser: {_describe_single_command(' '.join(args))}",
+        'export': lambda args: f"sets environment variable {args[0].split('=')[0] if args else ''}",
+        'source': lambda args: f"loads {args[0] if args else 'script'} into current shell",
+        '.': lambda args: f"loads {args[0] if args else 'script'} into current shell",
+        'touch': lambda args: f"creates/updates timestamp of {args[0] if args else 'file'}",
+        'head': lambda args: f"shows first lines of {args[-1] if args else 'file'}",
+        'tail': lambda args: f"shows last lines of {args[-1] if args else 'file'}",
+        'sort': lambda args: "sorts input lines",
+        'uniq': lambda args: "filters duplicate lines",
+        'wc': lambda args: "counts lines/words/bytes",
+        'awk': lambda args: "processes text with patterns",
+        'sed': lambda args: "transforms text with patterns",
+        'xargs': lambda args: "builds commands from input",
+        'tee': lambda args: "splits output to file and stdout",
+        'jq': lambda args: "processes JSON data",
+        'less': lambda args: f"pages through {args[0] if args else 'input'}",
+        'more': lambda args: f"pages through {args[0] if args else 'input'}",
+        'node': lambda args: "executes Node.js script",
+        'npx': lambda args: f"runs npm package {args[0] if args else 'command'}",
+        'make': lambda args: f"runs make {args[0] if args else 'target'}",
+        'cmake': lambda args: "configures CMake build",
+        'cargo': lambda args: f"runs Cargo {args[0] if args else 'command'}",
+        'rustc': lambda args: "compiles Rust code",
+        'go': lambda args: f"runs Go {args[0] if args else 'command'}",
+        'java': lambda args: "runs Java program",
+        'javac': lambda args: "compiles Java source",
+        'gcc': lambda args: "compiles C/C++ code",
+        'clang': lambda args: "compiles code with Clang",
+        'vim': lambda args: f"edits {args[0] if args else 'file'} in Vim",
+        'nano': lambda args: f"edits {args[0] if args else 'file'} in nano",
+        'emacs': lambda args: f"edits {args[0] if args else 'file'} in Emacs",
+        'which': lambda args: f"locates {args[0] if args else 'command'} executable",
+        'whereis': lambda args: f"finds {args[0] if args else 'command'} locations",
+        'man': lambda args: f"shows manual for {args[0] if args else 'command'}",
+        'pwd': lambda args: "prints current working directory",
+        'whoami': lambda args: "prints current username",
+        'date': lambda args: "displays current date/time",
+        'env': lambda args: "displays environment variables",
+        'set': lambda args: "sets shell options",
+        'unset': lambda args: f"removes variable {args[0] if args else ''}",
+        'read': lambda args: "reads input into variable",
+        'test': lambda args: "evaluates conditional expression",
+        '[': lambda args: "evaluates conditional expression",
+        'if': lambda args: "conditional statement",
+        'for': lambda args: "loop over items",
+        'while': lambda args: "loop while condition true",
+        'case': lambda args: "pattern matching statement",
+        'start': lambda args: f"opens {args[0] if args else 'file/URL'} (Windows)",
+        'open': lambda args: f"opens {args[0] if args else 'file/URL'} (macOS)",
+        'xdg-open': lambda args: f"opens {args[0] if args else 'file/URL'} (Linux)",
+        'code': lambda args: f"opens {args[0] if args else 'path'} in VS Code",
+        'claude': lambda args: f"runs Claude CLI {args[0] if args else 'command'}",
+    }
+
+    # Get args (skip flags)
+    args = [t for t in tokens[1:] if not t.startswith('-')]
+
+    if base_cmd in descriptions:
+        return descriptions[base_cmd](args)
+
+    # Default description
+    return f"executes {base_cmd} command"
+
+
+def _describe_git_subcommand(args: list) -> str:
+    """Describe git subcommands in detail."""
+    if not args:
+        return ""
+
+    subcommand = args[0]
+    git_descriptions = {
+        'init': ' to initialize a new repository',
+        'clone': ' to copy a remote repository',
+        'add': ' to stage changes',
+        'commit': ' to save staged changes',
+        'push': ' to upload commits to remote',
+        'pull': ' to download and merge remote changes',
+        'fetch': ' to download remote changes',
+        'merge': ' to combine branches',
+        'rebase': ' to replay commits on new base',
+        'checkout': ' to switch branches or restore files',
+        'branch': ' to manage branches',
+        'status': ' to show working tree status',
+        'log': ' to show commit history',
+        'diff': ' to show changes',
+        'stash': ' to temporarily store changes',
+        'reset': ' to undo changes',
+        'remote': ' to manage remote connections',
+        'tag': ' to manage tags',
+    }
+
+    return git_descriptions.get(subcommand, '')
+
+
 def _parse_command(cmd_string: str) -> dict:
     """Parse a command string into components."""
     parts = cmd_string.strip().split()
@@ -489,18 +653,23 @@ def generate_what_does_quiz(
     parsed = _parse_command(cmd_string)
     base_cmd = parsed["base"]
 
-    # Build the correct description
+    # Build the correct description using educational bash-focused generator
     correct_desc = description
     if not correct_desc:
-        # Generate from flags
+        # Use the educational bash description generator
+        correct_desc = _generate_bash_description(cmd_string)
+        # Capitalize first letter for consistent formatting
+        if correct_desc:
+            correct_desc = correct_desc[0].upper() + correct_desc[1:]
+
+        # Add flag details if available
         flag_descs = []
         for flag in parsed["flags"]:
             fd = _get_flag_description(base_cmd, flag)
             if fd:
-                flag_descs.append(fd)
-        correct_desc = f"Runs {base_cmd}"
+                flag_descs.append(f"{flag} ({fd.lower()})")
         if flag_descs:
-            correct_desc += " with: " + ", ".join(flag_descs)
+            correct_desc += " using " + ", ".join(flag_descs)
 
     # Generate distractors
     distractor_descriptions = _generate_distractor_descriptions(correct_desc, 3)
@@ -709,7 +878,14 @@ def generate_build_command_quiz(
 
     question_id = _generate_id(f"build_{cmd_string}")
 
-    task_description = intent if intent else f"perform the operation: {description}"
+    # Use educational bash description for task if no intent/description available
+    if intent:
+        task_description = intent
+    elif description:
+        task_description = description
+    else:
+        # Generate educational description from the command
+        task_description = _generate_bash_description(cmd_string)
 
     return QuizQuestion(
         id=question_id,