codebase-extractor 1.0.0__tar.gz

codebase_extractor-1.0.0/LICENCE

@@ -0,0 +1,11 @@
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+If you use, copy, or modify any part of this software, you must include a clear and visible attribution to the original author and project in your derivative work. This attribution must include:
+
+A link back to the original GitHub repository: https://github.com/lukaszlekowski/codebase-extractor
+
+A link to the author's LinkedIn profile: https://www.linkedin.com/in/lukasz-lekowski
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

codebase_extractor-1.0.0/PKG-INFO

@@ -0,0 +1,143 @@
+Metadata-Version: 2.4
+Name: codebase-extractor
+Version: 1.0.0
+Summary: A CLI tool to extract project source code into structured Markdown files for LLM & AI context.
+Author: Lukasz Lekowski
+Project-URL: Homepage, https://github.com/lukaszlekowski/codebase-extractor
+Project-URL: Bug Tracker, https://github.com/lukaszlekowski/codebase-extractor/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Software Development :: Documentation
+Classifier: Topic :: Utilities
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENCE
+Requires-Dist: questionary
+Requires-Dist: halo
+Requires-Dist: termcolor
+Dynamic: license-file
+
+# Codebase Extractor
+
+<p align="center">
+  <strong>A user-friendly CLI tool to extract project source code into structured Markdown files.</strong>
+</p>
+
+<p align="center">
+  <img src="https://img.shields.io/badge/License-MIT%20(Modified)-yellow.svg" alt="License: MIT (Modified)">
+  <img src="https://img.shields.io/badge/python-3.9%2B-blue.svg" alt="Python Version">
+  <img src="https://img.shields.io/github/stars/lukaszlekowski/codebase-extractor?style=social" alt="GitHub Stars">
+</p>
+<p align="center">
+  💡 <b>Love this tool?</b> Found a bug or have an idea? Share it on <a href="https://github.com/lukaszlekowski/codebase-extractor">GitHub</a>! <br>
+  🤝 <b>Connect with me</b> on <a href="https://www.linkedin.com/in/lukasz-lekowski">LinkedIn</a>. <br>
+  ☕ <b>Enjoying it?</b> Support development with a <a href="https://www.buymeacoffee.com/lukaszlekowski">coffee</a>!
+</p>
+
+</p>
+
+---
+
+## 🚀 Overview
+
+Codebase Extractor is a command-line interface (CLI) tool designed to scan a project directory and consolidate all relevant source code into neatly organized Markdown files. It's perfect for creating a complete project snapshot for analysis, documentation, or providing context to Large Language Models (LLMs) like GPT-4, Gemini, or Claude.
+
+The tool is highly configurable, allowing you to select specific folders, exclude large files, and intelligently ignore common directories like `node_modules` and `.git`.
+
+---
+
+## ✨ Key Features
+
+- **Interactive & User-Friendly:** A guided, multi-step CLI experience that makes selecting options simple and clear.
+- **Smart Filtering:** Automatically excludes common dependency folders, build artifacts, version control directories, and IDE configuration files.
+- **Flexible Selection Modes:** Choose to extract the entire project with one command, or dive into a specific selection mode.
+- **🌳 Nested Folder Selection:** Interactively browse and select specific sub-folders from a tree-like view.
+- **🔢 Configurable Scan Depth:** You decide how many levels deep the script should look for folders when building the selection tree.
+- **YAML Metadata:** Each generated Markdown file is prepended with a YAML front matter block containing useful metadata like a unique run ID, timestamp, and file count for easy tracking and parsing.
+- **🚀 Quick Start Mode:** Use the `--no-instructions` flag to skip the detailed intro guide on subsequent runs.
+- **Safe & Robust:** Features graceful exit handling (`Ctrl+C`) and provides clear feedback during the extraction process.
+
+---
+
+## 📦 Installation
+
+To get started with Codebase Extractor, follow these steps.
+
+1.  **Clone the Repository**
+
+    ```bash
+    git clone [https://github.com/lukaszlekowski/codebase-extractor.git](https://github.com/lukaszlekowski/codebase-extractor.git)
+    cd codebase-extractor
+    ```
+
+2.  **Set Up a Virtual Environment** (Recommended)
+    This keeps the dependencies for this project isolated from your system's Python installation.
+
+    ```bash
+    # For macOS/Linux
+    python3 -m venv venv
+    source venv/bin/activate
+
+    # For Windows
+    python -m venv venv
+    venv\Scripts\activate
+    ```
+
+3.  **Install Dependencies**
+    The required Python packages are listed in `requirements.txt`.
+    ```bash
+    pip install -r requirements.txt
+    ```
+
+---
+
+## ▶️ Usage
+
+### Basic Usage
+
+Once installed, simply run the script from the root of the project you wish to extract:
+
+```bash
+python3 codebase_extractor.py
+```
+
+# Quick Start
+
+For repeat usage, you can skip the detailed introductory guide by using the `--no-instructions` or `-ni` flag:
+
+```bash
+python3 codebase_extractor.py --no-instructions
+```
+
+## The Process
+
+The tool will guide you through a series of prompts:
+
+- **Initial Setup [1/2]**: A yes/no question to skip files larger than 1MB.
+- **Extraction Mode [2/2]**: Choose whether to extract the entire project (`Everything`) or select specific folders.
+
+### Specific Selection (if chosen):
+
+- **Scan Depth**: You'll be asked how many sub-folder levels to scan for the selection list (defaults to 3).
+- **Folder Tree**: You'll see a checklist of available folders and sub-folders to extract. The script handles selections intelligently:
+  - Selecting a parent folder automatically includes all its sub-folders, so you don’t need to select them individually.
+  - To extract only a sub-folder’s contents, select the sub-folder but not its parent.
+  - The special `root [...]` option extracts only the files in your project's main directory, ignoring all sub-folders.
+
+## Output Details
+
+All output files are saved in a `CODEBASE_EXTRACTS` directory within your project folder. Each generated Markdown file includes a YAML metadata header with a unique reference ID, timestamp, and file count for easy tracking and parsing.
+
+## 📜 License
+
+This project is licensed under a modified MIT License. Please see the [LICENSE](LICENSE) file for the full text.
+
+The standard MIT License has been amended with a single, important attribution requirement:
+
+If you use, copy, or modify any part of this software, you must include a clear and visible attribution to the original author and project in your derivative work.
+
+This attribution must include:
+
+- A link back to this original GitHub repository: [https://github.com/lukaszlekowski/codebase-extractor](https://github.com/lukaszlekowski/codebase-extractor)
+- A link to the author's LinkedIn profile: [https://www.linkedin.com/in/lukasz-lekowski](https://www.linkedin.com/in/lukasz-lekowski)

codebase_extractor-1.0.0/README.md

@@ -0,0 +1,123 @@
+# Codebase Extractor
+
+<p align="center">
+  <strong>A user-friendly CLI tool to extract project source code into structured Markdown files.</strong>
+</p>
+
+<p align="center">
+  <img src="https://img.shields.io/badge/License-MIT%20(Modified)-yellow.svg" alt="License: MIT (Modified)">
+  <img src="https://img.shields.io/badge/python-3.9%2B-blue.svg" alt="Python Version">
+  <img src="https://img.shields.io/github/stars/lukaszlekowski/codebase-extractor?style=social" alt="GitHub Stars">
+</p>
+<p align="center">
+  💡 <b>Love this tool?</b> Found a bug or have an idea? Share it on <a href="https://github.com/lukaszlekowski/codebase-extractor">GitHub</a>! <br>
+  🤝 <b>Connect with me</b> on <a href="https://www.linkedin.com/in/lukasz-lekowski">LinkedIn</a>. <br>
+  ☕ <b>Enjoying it?</b> Support development with a <a href="https://www.buymeacoffee.com/lukaszlekowski">coffee</a>!
+</p>
+
+</p>
+
+---
+
+## 🚀 Overview
+
+Codebase Extractor is a command-line interface (CLI) tool designed to scan a project directory and consolidate all relevant source code into neatly organized Markdown files. It's perfect for creating a complete project snapshot for analysis, documentation, or providing context to Large Language Models (LLMs) like GPT-4, Gemini, or Claude.
+
+The tool is highly configurable, allowing you to select specific folders, exclude large files, and intelligently ignore common directories like `node_modules` and `.git`.
+
+---
+
+## ✨ Key Features
+
+- **Interactive & User-Friendly:** A guided, multi-step CLI experience that makes selecting options simple and clear.
+- **Smart Filtering:** Automatically excludes common dependency folders, build artifacts, version control directories, and IDE configuration files.
+- **Flexible Selection Modes:** Choose to extract the entire project with one command, or dive into a specific selection mode.
+- **🌳 Nested Folder Selection:** Interactively browse and select specific sub-folders from a tree-like view.
+- **🔢 Configurable Scan Depth:** You decide how many levels deep the script should look for folders when building the selection tree.
+- **YAML Metadata:** Each generated Markdown file is prepended with a YAML front matter block containing useful metadata like a unique run ID, timestamp, and file count for easy tracking and parsing.
+- **🚀 Quick Start Mode:** Use the `--no-instructions` flag to skip the detailed intro guide on subsequent runs.
+- **Safe & Robust:** Features graceful exit handling (`Ctrl+C`) and provides clear feedback during the extraction process.
+
+---
+
+## 📦 Installation
+
+To get started with Codebase Extractor, follow these steps.
+
+1.  **Clone the Repository**
+
+    ```bash
+    git clone [https://github.com/lukaszlekowski/codebase-extractor.git](https://github.com/lukaszlekowski/codebase-extractor.git)
+    cd codebase-extractor
+    ```
+
+2.  **Set Up a Virtual Environment** (Recommended)
+    This keeps the dependencies for this project isolated from your system's Python installation.
+
+    ```bash
+    # For macOS/Linux
+    python3 -m venv venv
+    source venv/bin/activate
+
+    # For Windows
+    python -m venv venv
+    venv\Scripts\activate
+    ```
+
+3.  **Install Dependencies**
+    The required Python packages are listed in `requirements.txt`.
+    ```bash
+    pip install -r requirements.txt
+    ```
+
+---
+
+## ▶️ Usage
+
+### Basic Usage
+
+Once installed, simply run the script from the root of the project you wish to extract:
+
+```bash
+python3 codebase_extractor.py
+```
+
+# Quick Start
+
+For repeat usage, you can skip the detailed introductory guide by using the `--no-instructions` or `-ni` flag:
+
+```bash
+python3 codebase_extractor.py --no-instructions
+```
+
+## The Process
+
+The tool will guide you through a series of prompts:
+
+- **Initial Setup [1/2]**: A yes/no question to skip files larger than 1MB.
+- **Extraction Mode [2/2]**: Choose whether to extract the entire project (`Everything`) or select specific folders.
+
+### Specific Selection (if chosen):
+
+- **Scan Depth**: You'll be asked how many sub-folder levels to scan for the selection list (defaults to 3).
+- **Folder Tree**: You'll see a checklist of available folders and sub-folders to extract. The script handles selections intelligently:
+  - Selecting a parent folder automatically includes all its sub-folders, so you don’t need to select them individually.
+  - To extract only a sub-folder’s contents, select the sub-folder but not its parent.
+  - The special `root [...]` option extracts only the files in your project's main directory, ignoring all sub-folders.
+
+## Output Details
+
+All output files are saved in a `CODEBASE_EXTRACTS` directory within your project folder. Each generated Markdown file includes a YAML metadata header with a unique reference ID, timestamp, and file count for easy tracking and parsing.
+
+## 📜 License
+
+This project is licensed under a modified MIT License. Please see the [LICENSE](LICENSE) file for the full text.
+
+The standard MIT License has been amended with a single, important attribution requirement:
+
+If you use, copy, or modify any part of this software, you must include a clear and visible attribution to the original author and project in your derivative work.
+
+This attribution must include:
+
+- A link back to this original GitHub repository: [https://github.com/lukaszlekowski/codebase-extractor](https://github.com/lukaszlekowski/codebase-extractor)
+- A link to the author's LinkedIn profile: [https://www.linkedin.com/in/lukasz-lekowski](https://www.linkedin.com/in/lukasz-lekowski)

codebase_extractor-1.0.0/pyproject.toml

@@ -0,0 +1,34 @@
+[build-system]
+requires = ["setuptools"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "codebase-extractor"
+version = "1.0.0"
+authors = [
+  { name="Lukasz Lekowski" },
+]
+description = "A CLI tool to extract project source code into structured Markdown files for LLM & AI context."
+readme = "README.md"
+license = { file="LICENSE" }
+requires-python = ">=3.9"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Topic :: Software Development :: Documentation",
+    "Topic :: Utilities",
+]
+dependencies = [
+    "questionary",
+    "halo",
+    "termcolor",
+]
+
+# This creates the `code-extractor` command in the user's terminal
+[project.scripts]
+code-extractor = "codebase_extractor.main_logic:main"
+
+[project.urls]
+"Homepage" = "https://github.com/lukaszlekowski/codebase-extractor"
+"Bug Tracker" = "https://github.com/lukaszlekowski/codebase-extractor/issues"

codebase_extractor-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

codebase_extractor-1.0.0/src/codebase_extractor/__init__.py

@@ -0,0 +1 @@
+__version__ = "1.0.0"

codebase_extractor-1.0.0/src/codebase_extractor/config.py

@@ -0,0 +1,41 @@
+from pathlib import Path
+import sys
+
+# --- CONFIGURATION ---
+SCRIPT_VERSION = "1.0.0"
+GITHUB_URL = "https://github.com/lukaszlekowski/codebase-extractor"
+LINKEDIN_URL = "https://www.linkedin.com/in/lukasz-lekowski"
+SCRIPT_FILENAME = Path(sys.argv[0]).name
+OUTPUT_DIR_NAME = "CODEBASE_EXTRACTS"
+
+# --- FILE/FOLDER LISTS ---
+EXCLUDED_DIRS = {
+    "node_modules", "vendor", "__pycache__", "dist", "build", "target", ".next",
+    ".git", ".svn", ".hg", ".vscode", ".idea", "venv", ".venv",
+    OUTPUT_DIR_NAME,
+}
+EXCLUDED_FILENAMES = {
+    "package-lock.json", "yarn.lock", "composer.lock", ".env"
+}
+ALLOWED_FILENAMES = {
+    "dockerfile", ".gitignore", ".htaccess", "makefile"
+}
+ALLOWED_EXTENSIONS = {
+    ".php", ".html", ".css", ".js", ".jsx", ".ts", ".tsx", ".vue", ".svelte",
+    ".py", ".rb", ".java", ".c", ".cpp", ".cs", ".go", ".rs", ".json", ".xml",
+    ".yaml", ".yml", ".toml", ".ini", ".conf", ".md", ".txt", ".rst", ".twig",
+    ".blade", ".handlebars", ".mustache", ".ejs", ".sql", ".graphql", ".gql", ".tf",
+}
+
+# --- MAPPINGS & CONSTANTS ---
+EXTENSION_LANG_MAP = {
+    ".js": "javascript", ".ts": "typescript", ".tsx": "tsx", ".py": "python",
+    ".html": "html", ".css": "css", ".json": "json", ".md": "markdown", ".txt": "",
+    ".sh": "bash", ".yml": "yaml", ".yaml": "yaml", ".php": "php", ".rb": "ruby",
+    ".java": "java", ".c": "c", ".cpp": "cpp", ".cs": "csharp", ".go": "go",
+    ".rs": "rust", ".vue": "vue", ".svelte": "svelte", ".sql": "sql",
+    ".graphql": "graphql", ".gql": "graphql",
+}
+MAX_FILE_SIZE_MB = 1
+FILE_COUNT_WARNING_THRESHOLD = 1000
+LOGO_BREAKPOINT = 144

codebase_extractor-1.0.0/src/codebase_extractor/file_handler.py

@@ -0,0 +1,133 @@
+import os
+import datetime
+import uuid
+from pathlib import Path
+from termcolor import colored
+from . import config
+import questionary
+
+def get_folder_choices(root_path: Path, max_depth: int) -> list:
+    """Recursively finds folders up to a max depth and prepares them for questionary."""
+    choices = []
+    
+    def scanner(current_path: Path, depth: int):
+        if depth > max_depth:
+            return
+            
+        relative_path = current_path.relative_to(root_path)
+        prefix = "  " * (depth - 1)
+        display_name = f"{prefix}{current_path.name}"
+        choices.append(questionary.Choice(title=display_name, value=relative_path))
+        
+        try:
+            subdirs = sorted([p for p in current_path.iterdir() if p.is_dir() and p.name not in config.EXCLUDED_DIRS])
+            for subdir in subdirs:
+                scanner(subdir, depth + 1)
+        except PermissionError:
+            pass
+
+    top_level_folders = sorted([p for p in root_path.iterdir() if p.is_dir() and p.name not in config.EXCLUDED_DIRS])
+    for folder in top_level_folders:
+        scanner(folder, 1)
+        
+    root_option_name = f"root [{root_path.name}] (files in root folder only, excl. sub-folders)"
+    choices.insert(0, questionary.Choice(title=root_option_name, value="ROOT_SENTINEL"))
+    
+    return choices
+
+
+def is_allowed_file(path: Path, exclude_large: bool) -> bool:
+    """Checks if a file should be included based on its name, extension, and size."""
+    if path.name == config.SCRIPT_FILENAME:
+        return False
+    if path.name.lower() in config.ALLOWED_FILENAMES:
+        return True
+    if not path.is_file():
+        return False
+    if path.name.lower() in config.EXCLUDED_FILENAMES:
+        return False
+    if path.suffix not in config.ALLOWED_EXTENSIONS:
+        return False
+    if exclude_large and path.stat().st_size > config.MAX_FILE_SIZE_MB * 1024 * 1024:
+        return False
+    return True
+
+
+def extract_code_from_folder(folder: Path, exclude_large: bool) -> (str, int):
+    """Extracts code from a given folder, respecting EXCLUDED_DIRS at all depths."""
+    content = f"# Folder: {folder.relative_to(Path.cwd())}\n\n"
+    extracted_files = 0
+    dirs_to_visit = [folder]
+    while dirs_to_visit:
+        current_dir = dirs_to_visit.pop(0)
+        for item in sorted(current_dir.iterdir()):
+            if item.is_dir() and item.name not in config.EXCLUDED_DIRS:
+                dirs_to_visit.append(item)
+            elif item.is_file() and is_allowed_file(item, exclude_large):
+                try:
+                    rel_path = item.relative_to(Path.cwd())
+                    ext = item.suffix
+                    lang = config.EXTENSION_LANG_MAP.get(ext, "")
+                    content += f"## {rel_path}\n\n```{lang}\n"
+                    content += item.read_text(errors="ignore")
+                    content += "\n```\n\n"
+                    extracted_files += 1
+                except Exception as e:
+                    content += f"\n\n"
+    if extracted_files > config.FILE_COUNT_WARNING_THRESHOLD:
+        print(colored(f"> Caution: Large file count in '{folder.name}' ({extracted_files} files).", "yellow"))
+    return content, extracted_files
+
+
+def extract_code_from_root(root_path: Path, exclude_large: bool) -> (str, int):
+    """Extracts code only from files present in the root directory."""
+    content = f"# Root Files: {root_path.name}\n\n"
+    extracted_files = 0
+    for filepath in sorted(root_path.iterdir()):
+        if filepath.is_file() and is_allowed_file(filepath, exclude_large):
+            ext = filepath.suffix
+            lang = config.EXTENSION_LANG_MAP.get(ext, "")
+            content += f"## {filepath.name}\n\n```{lang}\n"
+            content += filepath.read_text(errors="ignore")
+            content += "\n```\n\n"
+            extracted_files += 1
+    if extracted_files > config.FILE_COUNT_WARNING_THRESHOLD:
+        print(colored(f"> Caution: Large file count in root ({extracted_files} files).", "yellow"))
+    return content, extracted_files
+
+
+def write_to_markdown_file(content: str, metadata: dict, root_path: Path):
+    """Constructs a YAML header and writes the full content to a timestamped Markdown file."""
+    output_dir = Path(config.OUTPUT_DIR_NAME)
+    output_dir.mkdir(exist_ok=True)
+    
+    timestamp = datetime.datetime.fromisoformat(metadata['run_timestamp']).strftime("%Y%m%d_%H%M%S")
+    output_name = str(metadata['folder_name'])
+    
+    if output_name.startswith(f"root [{root_path.name}]"):
+        file_base_name = f"root_{root_path.name}"
+    else:
+        file_base_name = str(output_name).replace(os.sep, "_")
+    
+    filename = f"{file_base_name}_{timestamp}.md"
+    full_filepath = output_dir / filename
+
+    yaml_header = f"""---
+extraction_details:
+  reference: {metadata['run_ref']}
+  timestamp_utc: "{metadata['run_timestamp']}"
+  source_folder: "{metadata['folder_name']}"
+  file_count: {metadata['file_count']}
+tool_details:
+  name: "Codebase Extractor"
+  version: "{config.SCRIPT_VERSION}"
+  source: "{config.GITHUB_URL}"
+---
+
+"""
+    full_content = yaml_header + content
+    with open(full_filepath, "w", encoding="utf-8") as f:
+        f.write(full_content)
+    
+    print(f"\n💾 Saved to {colored(str(full_filepath), 'cyan')}")
+    return str(full_filepath)

codebase_extractor-1.0.0/src/codebase_extractor/main_logic.py

@@ -0,0 +1,197 @@
+import os
+import sys
+import time
+import datetime
+import uuid
+import shutil
+import argparse
+from pathlib import Path
+from typing import List, Optional
+
+import questionary
+from halo import Halo
+from termcolor import colored
+from prompt_toolkit.styles import Style
+from questionary import Validator, ValidationError
+
+# Import from our new modules
+from . import config
+from . import ui
+from . import file_handler
+
+class NumberValidator(Validator):
+    """Validates that the input is a positive integer."""
+    def validate(self, document):
+        try:
+            value = int(document.text)
+            if value <= 0:
+                raise ValidationError(
+                    message="Please enter a positive number.",
+                    cursor_position=len(document.text))
+        except ValueError:
+            raise ValidationError(
+                message="Please enter a valid number.",
+                cursor_position=len(document.text))
+
+def main():
+    """Main function to run the CLI application."""
+    parser = argparse.ArgumentParser(add_help=False)
+    parser.add_argument(
+        '-ni', '--no-instructions',
+        action='store_true'
+    )
+    args, _ = parser.parse_known_args()
+    
+    ui.clear_screen()
+    ui.print_banner()
+    
+    if not args.no_instructions:
+        ui.show_instructions()
+    else:
+        input(colored("\nPress Enter to begin...", "green"))
+        ui.clear_screen()
+
+    root_path = Path.cwd()
+    
+    select_style = Style([('qmark', 'fg:#FFA500'), ('pointer', 'fg:#FFA500'), ('highlighted', 'fg:black bg:#FFA500'), ('selected', 'fg:black bg:#FFA500')])
+    checkbox_style = Style([('qmark', 'fg:#FFA500'), ('pointer', 'fg:#FFA500'), ('highlighted', 'fg:#FFA500'), ('selected', 'fg:#FFA500'), ('checkbox-selected', 'fg:#FFA500')])
+    
+    exit_message = colored("\nExtraction aborted by user. Closing Code Extractor. Goodbye.", "red")
+
+    print("=== Extraction Settings ===")
+    exclude_large = questionary.select("[1/2] -- Exclude files larger than 1MB?", choices=["yes", "no"], style=select_style, instruction=" ").ask()
+    if exclude_large is None:
+        print(exit_message)
+        return
+    exclude_large = exclude_large == "yes"
+    print()
+
+    folders_to_process = set()
+    process_root_files = False
+    
+    run_ref = str(uuid.uuid4())
+    run_timestamp = datetime.datetime.now(datetime.timezone.utc).isoformat()
+
+    selection_mode = questionary.select("[2/2] -- What do you want to extract?", choices=["Everything (all folders and root files)", "Specific folders/root from a list"], style=select_style, instruction=" ").ask()
+    if selection_mode is None:
+        print(exit_message)
+        return
+
+    if selection_mode == "Everything (all folders and root files)":
+        folders_to_process.update([p for p in root_path.iterdir() if p.is_dir() and p.name not in config.EXCLUDED_DIRS])
+        process_root_files = True
+    else:
+        depth_str = questionary.text(
+            "-- How many levels deep should we scan for folders?",
+            default="3",
+            validate=NumberValidator,
+            style=select_style
+        ).ask()
+        if depth_str is None:
+            print(exit_message)
+            return
+        scan_depth = int(depth_str)
+
+        folder_choices = file_handler.get_folder_choices(root_path, max_depth=scan_depth)
+        selected_options = None
+        confirm_exit = False
+        
+        checkbox_instruction = "(Arrows to move, Space to select, A to toggle, I to invert)"
+
+        while not selected_options:
+            selection = questionary.checkbox(
+                "-- Select folders/sub-folders to extract (must select at least one):", 
+                choices=folder_choices, 
+                style=checkbox_style,
+                instruction=checkbox_instruction
+            ).ask()
+            
+            if selection is None:
+                if confirm_exit:
+                    print(exit_message)
+                    return
+                else:
+                    confirm_exit = True
+                    print(colored("\n[!] Press Ctrl+C again to exit.", "yellow"))
+                    continue
+            
+            confirm_exit = False
+            
+            if not selection:
+                print(colored("[!] Error: You must make a selection.", "red"))
+                continue
+                
+            selected_options = selection
+            break
+        
+        if "ROOT_SENTINEL" in selected_options:
+            process_root_files = True
+            selected_options.remove("ROOT_SENTINEL")
+
+        selected_paths = [root_path / p for p in selected_options]
+        sorted_paths = sorted(selected_paths, key=lambda p: len(p.parts))
+        
+        final_paths = set()
+        for path in sorted_paths:
+            if not any(path.is_relative_to(parent) for parent in final_paths):
+                final_paths.add(path)
+        
+        folders_to_process.update(final_paths)
+
+    print()
+    total_files_extracted = 0
+
+    for folder_path in sorted(list(folders_to_process)):
+        with Halo(text=f"Extracting {folder_path.relative_to(root_path)}...", spinner="dots"):
+            time.sleep(0.1)
+            folder_md, folder_count = file_handler.extract_code_from_folder(folder_path, exclude_large)
+            if folder_count > 0:
+                metadata = {"run_ref": run_ref, "run_timestamp": run_timestamp, "folder_name": str(folder_path.relative_to(root_path)), "file_count": folder_count}
+                file_handler.write_to_markdown_file(folder_md, metadata, root_path)
+                total_files_extracted += folder_count
+                print(f"✅ Extracted {folder_count} file(s) from: {folder_path.relative_to(root_path)}")
+            else:
+                print(f"[!] No extractable files in: {folder_path.relative_to(root_path)}")
+        print("")
+
+    if process_root_files:
+        root_display_name = f"root [{root_path.name}] (files in root folder only, excl. sub-folders)"
+        with Halo(text=f"Extracting {root_display_name}...", spinner="dots"):
+            time.sleep(0.1)
+            root_md, root_count = file_handler.extract_code_from_root(root_path, exclude_large)
+            if root_count > 0:
+                metadata = {"run_ref": run_ref, "run_timestamp": run_timestamp, "folder_name": root_display_name, "file_count": root_count}
+                file_handler.write_to_markdown_file(root_md, metadata, root_path)
+                total_files_extracted += root_count
+                print(f"✅ Extracted {root_count} file(s) from the root directory")
+            else:
+                print("[!] No extractable files in the root directory")
+        print("")
+        
+    try:
+        width = shutil.get_terminal_size((80, 20)).columns
+    except OSError:
+        width = 80
+
+    if total_files_extracted > 0:
+        output_dir_path = Path(config.OUTPUT_DIR_NAME).resolve()
+        print(colored(f"Success! A total of {total_files_extracted} file(s) have been extracted.", "grey", "on_green"))
+        print(f"Files saved in: {colored(str(output_dir_path), 'cyan')}")
+    else:
+        print(colored("Extraction complete, but no files matched the criteria.", "yellow"))
+    
+    print("\n")
+    print("-" * width)
+    print("💡 Love this tool? Found a bug? Share your feedback on GitHub:")
+    print(config.GITHUB_URL + "\n")
+    print("🤝 Connect with the author on LinkedIn:")
+    print(config.LINKEDIN_URL + "\n")
+    print("☕ Enjoying this tool? You can support its development with a coffee!")
+    print("https://www.buymeacoffee.com/lukaszlekowski\n")
+
+
+if __name__ == "__main__":
+    try:
+        main()
+    except KeyboardInterrupt:
+        print(colored("\nExtraction aborted by user. Closing Code Extractor. Goodbye.", "red"))

codebase_extractor-1.0.0/src/codebase_extractor/ui.py

@@ -0,0 +1,84 @@
+import os
+import shutil
+from . import config
+from termcolor import colored
+
+LOGO_LARGE = """
+ ██████╗ ██████╗ ██████╗ ███████╗██████╗  █████╗ ███████╗███████╗    ███████╗██╗  ██╗████████╗██████╗  █████╗  ██████╗████████╗ ██████╗ ██████╗ 
+██╔════╝██╔═══██╗██╔══██╗██╔════╝██╔══██╗██╔══██╗██╔════╝██╔════╝    ██╔════╝╚██╗██╔╝╚══██╔══╝██╔══██╗██╔══██╗██╔════╝╚══██╔══╝██╔═══██╗██╔══██╗
+██║     ██║   ██║██║  ██║█████╗  ██████╔╝███████║███████╗█████╗      █████╗   ╚███╔╝    ██║   ██████╔╝███████║██║        ██║   ██║   ██║██████╔╝
+██║     ██║   ██║██║  ██║██╔══╝  ██╔══██╗██╔══██║╚════██║██╔══╝      ██╔══╝   ██╔██╗    ██║   ██╔══██╗██╔══██║██║        ██║   ██║   ██║██╔══██╗
+╚██████╗╚██████╔╝██████╔╝███████╗██████╔╝██║  ██║███████║███████╗    ███████╗██╔╝ ██╗   ██║   ██║  ██║██║  ██║╚██████╗   ██║   ╚██████╔╝██║  ██║
+ ╚═════╝ ╚═════╝ ╚═════╝ ╚══════╝╚═════╝ ╚═╝  ╚═╝╚══════╝╚══════╝    ╚══════╝╚═╝  ╚═╝   ╚═╝   ╚═╝  ╚═╝╚═╝  ╚═╝ ╚═════╝   ╚═╝    ╚═════╝ ╚═╝  ╚═╝
+"""
+
+LOGO_SMALL = """
+ ██████╗ ██████╗ ██████╗ ███████╗██████╗  █████╗ ███████╗███████╗          
+██╔════╝██╔═══██╗██╔══██╗██╔════╝██╔══██╗██╔══██╗██╔════╝██╔════╝          
+██║     ██║   ██║██║  ██║█████╗  ██████╔╝███████║███████╗█████╗            
+██║     ██║   ██║██║  ██║██╔══╝  ██╔══██╗██╔══██║╚════██║██╔══╝            
+╚██████╗╚██████╔╝██████╔╝███████╗██████╔╝██║  ██║███████║███████╗          
+ ╚═════╝ ╚═════╝ ╚═════╝ ╚══════╝╚═════╝ ╚═╝  ╚═╝╚══════╝╚══════╝          
+                                                                           
+███████╗██╗  ██╗████████╗██████╗  █████╗  ██████╗████████╗ ██████╗ ██████╗ 
+██╔════╝╚██╗██╔╝╚══██╔══╝██╔══██╗██╔══██╗██╔════╝╚══██╔══╝██╔═══██╗██╔══██╗
+█████╗   ╚███╔╝    ██║   ██████╔╝███████║██║        ██║   ██║   ██║██████╔╝
+██╔══╝   ██╔██╗    ██║   ██╔══██╗██╔══██║██║        ██║   ██║   ██║██╔══██╗
+███████╗██╔╝ ██╗   ██║   ██║  ██║██║  ██║╚██████╗   ██║   ╚██████╔╝██║  ██║
+╚══════╝╚═╝  ╚═╝   ╚═╝   ╚═╝  ╚═╝╚═╝  ╚═╝ ╚═════╝   ╚═╝    ╚═════╝ ╚═╝  ╚═╝
+"""
+
+def clear_screen():
+    """Clears the terminal screen."""
+    os.system('cls' if os.name == 'nt' else 'clear')
+
+def print_banner():
+    """Prints a banner that adjusts to the terminal width."""
+    try:
+        width = shutil.get_terminal_size((80, 20)).columns
+    except OSError:
+        width = 80
+
+    if width > config.LOGO_BREAKPOINT:
+        print(LOGO_LARGE)
+    else:
+        print(LOGO_SMALL)
+
+    print(colored(f" Welcome to Code Extractor v{config.SCRIPT_VERSION} by Lukasz Lekowski ".center(width, "="), "white", "on_magenta"))
+
+def show_instructions():
+    """Clears screen and shows detailed instructions, pausing for user input."""
+    try:
+        width = shutil.get_terminal_size((80, 20)).columns
+    except OSError:
+        width = 80
+        
+    input(colored("\nPress Enter to view detailed instructions...", "dark_grey"))
+    clear_screen()
+    print(colored("--- How It Works ---", "yellow"))
+    print("The script will guide you through a series of steps:\n")
+
+    print(colored("Step 1: General Settings", "cyan"))
+    print("You will first be asked about basic settings, such as whether to exclude files larger than 1MB to keep the output clean.\n")
+
+    print(colored("Step 2: Extraction Mode", "cyan"))
+    print("You have two main modes to choose from:")
+    print("  - 'Everything': This automatically finds and processes every valid folder and all root files. You will get one Markdown file for each top-level folder, plus one for the root files.")
+    print("  - 'Specific folders/root': This lets you hand-pick exactly what you want to extract.\n")
+
+    print(colored("Step 3: Detailed Selection (If you chose 'Specific')", "cyan"))
+    print("If you choose to be specific, you'll be presented with more options:")
+    print("  - Scan Depth: First, you'll decide how many sub-folder levels to scan and display.")
+    print("  - Selection Tree: You'll see a tree-like list of your project's folders. The script handles parent/child selections intelligently:")
+    print("    - If you select a parent folder, all of its sub-folders are automatically included. You don't need to check them individually.")
+    print("    - To get a file for *only* a sub-folder, select the sub-folder but *not* its parent.")
+    print("  - The 'root [...]' option specifically extracts *only* the files in your project's main directory.\n")
+    
+    print(colored("--- Output Details ---", "yellow"))
+    print(f"All extracted content is saved into the '{config.OUTPUT_DIR_NAME}' directory. Each Markdown file generated will contain a YAML metadata header at the top with a unique reference ID, a timestamp, and more.\n")
+    
+    tip = "TIP: Run this script with the --no-instructions or -ni flag to skip this guide next time."
+    print(colored(tip, "black", "on_yellow"))
+
+    input(colored("\nReady? Press Enter to begin...", "green"))
+    clear_screen()

codebase_extractor-1.0.0/src/codebase_extractor.egg-info/PKG-INFO

@@ -0,0 +1,143 @@
+Metadata-Version: 2.4
+Name: codebase-extractor
+Version: 1.0.0
+Summary: A CLI tool to extract project source code into structured Markdown files for LLM & AI context.
+Author: Lukasz Lekowski
+Project-URL: Homepage, https://github.com/lukaszlekowski/codebase-extractor
+Project-URL: Bug Tracker, https://github.com/lukaszlekowski/codebase-extractor/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Software Development :: Documentation
+Classifier: Topic :: Utilities
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENCE
+Requires-Dist: questionary
+Requires-Dist: halo
+Requires-Dist: termcolor
+Dynamic: license-file
+
+# Codebase Extractor
+
+<p align="center">
+  <strong>A user-friendly CLI tool to extract project source code into structured Markdown files.</strong>
+</p>
+
+<p align="center">
+  <img src="https://img.shields.io/badge/License-MIT%20(Modified)-yellow.svg" alt="License: MIT (Modified)">
+  <img src="https://img.shields.io/badge/python-3.9%2B-blue.svg" alt="Python Version">
+  <img src="https://img.shields.io/github/stars/lukaszlekowski/codebase-extractor?style=social" alt="GitHub Stars">
+</p>
+<p align="center">
+  💡 <b>Love this tool?</b> Found a bug or have an idea? Share it on <a href="https://github.com/lukaszlekowski/codebase-extractor">GitHub</a>! <br>
+  🤝 <b>Connect with me</b> on <a href="https://www.linkedin.com/in/lukasz-lekowski">LinkedIn</a>. <br>
+  ☕ <b>Enjoying it?</b> Support development with a <a href="https://www.buymeacoffee.com/lukaszlekowski">coffee</a>!
+</p>
+
+</p>
+
+---
+
+## 🚀 Overview
+
+Codebase Extractor is a command-line interface (CLI) tool designed to scan a project directory and consolidate all relevant source code into neatly organized Markdown files. It's perfect for creating a complete project snapshot for analysis, documentation, or providing context to Large Language Models (LLMs) like GPT-4, Gemini, or Claude.
+
+The tool is highly configurable, allowing you to select specific folders, exclude large files, and intelligently ignore common directories like `node_modules` and `.git`.
+
+---
+
+## ✨ Key Features
+
+- **Interactive & User-Friendly:** A guided, multi-step CLI experience that makes selecting options simple and clear.
+- **Smart Filtering:** Automatically excludes common dependency folders, build artifacts, version control directories, and IDE configuration files.
+- **Flexible Selection Modes:** Choose to extract the entire project with one command, or dive into a specific selection mode.
+- **🌳 Nested Folder Selection:** Interactively browse and select specific sub-folders from a tree-like view.
+- **🔢 Configurable Scan Depth:** You decide how many levels deep the script should look for folders when building the selection tree.
+- **YAML Metadata:** Each generated Markdown file is prepended with a YAML front matter block containing useful metadata like a unique run ID, timestamp, and file count for easy tracking and parsing.
+- **🚀 Quick Start Mode:** Use the `--no-instructions` flag to skip the detailed intro guide on subsequent runs.
+- **Safe & Robust:** Features graceful exit handling (`Ctrl+C`) and provides clear feedback during the extraction process.
+
+---
+
+## 📦 Installation
+
+To get started with Codebase Extractor, follow these steps.
+
+1.  **Clone the Repository**
+
+    ```bash
+    git clone [https://github.com/lukaszlekowski/codebase-extractor.git](https://github.com/lukaszlekowski/codebase-extractor.git)
+    cd codebase-extractor
+    ```
+
+2.  **Set Up a Virtual Environment** (Recommended)
+    This keeps the dependencies for this project isolated from your system's Python installation.
+
+    ```bash
+    # For macOS/Linux
+    python3 -m venv venv
+    source venv/bin/activate
+
+    # For Windows
+    python -m venv venv
+    venv\Scripts\activate
+    ```
+
+3.  **Install Dependencies**
+    The required Python packages are listed in `requirements.txt`.
+    ```bash
+    pip install -r requirements.txt
+    ```
+
+---
+
+## ▶️ Usage
+
+### Basic Usage
+
+Once installed, simply run the script from the root of the project you wish to extract:
+
+```bash
+python3 codebase_extractor.py
+```
+
+# Quick Start
+
+For repeat usage, you can skip the detailed introductory guide by using the `--no-instructions` or `-ni` flag:
+
+```bash
+python3 codebase_extractor.py --no-instructions
+```
+
+## The Process
+
+The tool will guide you through a series of prompts:
+
+- **Initial Setup [1/2]**: A yes/no question to skip files larger than 1MB.
+- **Extraction Mode [2/2]**: Choose whether to extract the entire project (`Everything`) or select specific folders.
+
+### Specific Selection (if chosen):
+
+- **Scan Depth**: You'll be asked how many sub-folder levels to scan for the selection list (defaults to 3).
+- **Folder Tree**: You'll see a checklist of available folders and sub-folders to extract. The script handles selections intelligently:
+  - Selecting a parent folder automatically includes all its sub-folders, so you don’t need to select them individually.
+  - To extract only a sub-folder’s contents, select the sub-folder but not its parent.
+  - The special `root [...]` option extracts only the files in your project's main directory, ignoring all sub-folders.
+
+## Output Details
+
+All output files are saved in a `CODEBASE_EXTRACTS` directory within your project folder. Each generated Markdown file includes a YAML metadata header with a unique reference ID, timestamp, and file count for easy tracking and parsing.
+
+## 📜 License
+
+This project is licensed under a modified MIT License. Please see the [LICENSE](LICENSE) file for the full text.
+
+The standard MIT License has been amended with a single, important attribution requirement:
+
+If you use, copy, or modify any part of this software, you must include a clear and visible attribution to the original author and project in your derivative work.
+
+This attribution must include:
+
+- A link back to this original GitHub repository: [https://github.com/lukaszlekowski/codebase-extractor](https://github.com/lukaszlekowski/codebase-extractor)
+- A link to the author's LinkedIn profile: [https://www.linkedin.com/in/lukasz-lekowski](https://www.linkedin.com/in/lukasz-lekowski)

codebase_extractor-1.0.0/src/codebase_extractor.egg-info/SOURCES.txt

@@ -0,0 +1,14 @@
+LICENCE
+README.md
+pyproject.toml
+src/codebase_extractor/__init__.py
+src/codebase_extractor/config.py
+src/codebase_extractor/file_handler.py
+src/codebase_extractor/main_logic.py
+src/codebase_extractor/ui.py
+src/codebase_extractor.egg-info/PKG-INFO
+src/codebase_extractor.egg-info/SOURCES.txt
+src/codebase_extractor.egg-info/dependency_links.txt
+src/codebase_extractor.egg-info/entry_points.txt
+src/codebase_extractor.egg-info/requires.txt
+src/codebase_extractor.egg-info/top_level.txt

codebase_extractor-1.0.0/src/codebase_extractor.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

codebase_extractor-1.0.0/src/codebase_extractor.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+code-extractor = codebase_extractor.main_logic:main

codebase_extractor-1.0.0/src/codebase_extractor.egg-info/requires.txt

@@ -0,0 +1,3 @@
+questionary
+halo
+termcolor

codebase_extractor-1.0.0/src/codebase_extractor.egg-info/top_level.txt

@@ -0,0 +1 @@
+codebase_extractor