gc-shell 0.1.0__py3-none-any.whl

commands/apps.py

@@ -0,0 +1,202 @@
+"""App management commands — open, close, list apps, list running."""
+
+import subprocess
+
+from rich.console import Console
+from rich.table import Table
+
+from registry.scanner import get_registry_path, load_registry
+
+
+# ---------------------------------------------------------------------------
+# Fuzzy matching
+# ---------------------------------------------------------------------------
+
+def _fuzzy_match(query: str, registry: dict) -> tuple | None:
+    """Find the best match for *query* in the registry.
+
+    Match precedence:
+      1. Exact key match  (e.g. "google chrome" → "google chrome")
+      2. Query is a substring of a key  (e.g. "chrome" → "google chrome")
+      3. Key is a substring of the query
+    When multiple candidates tie, the shortest key wins (most specific).
+    """
+    query = query.lower().strip()
+
+    # 1. Exact match
+    if query in registry:
+        return query, registry[query]
+
+    # 2/3. Substring matches
+    matches = [
+        (key, info)
+        for key, info in registry.items()
+        if query in key or key in query
+    ]
+
+    if len(matches) == 1:
+        return matches[0]
+    if len(matches) > 1:
+        matches.sort(key=lambda x: len(x[0]))
+        return matches[0]
+
+    return None
+
+
+# ---------------------------------------------------------------------------
+# Commands
+# ---------------------------------------------------------------------------
+
+def open_app(name: str, console: Console) -> bool:
+    """Open an application by name.
+
+    Returns True if the app was found (whether or not it launched successfully),
+    False if no match was found so the caller can fall through.
+    """
+    registry = load_registry()
+
+    if not registry:
+        console.print(
+            "[yellow]⚠  No app registry found. "
+            "Run [bold]scan[/bold] first.[/yellow]"
+        )
+        return True  # handled (with a warning), don't fall through
+
+    match = _fuzzy_match(name, registry)
+
+    if match:
+        _key, info = match
+        app_name = info["name"]
+        console.print(f"[green]▶[/green] Opening [bold]{app_name}[/bold]...")
+        try:
+            subprocess.run(
+                ["open", "-a", info["path"]],
+                check=True,
+                capture_output=True,
+                text=True,
+            )
+        except subprocess.CalledProcessError as e:
+            console.print(
+                f"[red]✗ Failed to open {app_name}:[/red] {e.stderr.strip()}"
+            )
+        return True
+
+    return False  # not in registry — let the executor fall through
+
+
+def close_app(name: str, console: Console) -> None:
+    """Close an application by name via AppleScript quit."""
+    registry = load_registry()
+
+    if not registry:
+        console.print(
+            "[yellow]⚠  No app registry found. "
+            "Run [bold]scan[/bold] first.[/yellow]"
+        )
+        return
+
+    match = _fuzzy_match(name, registry)
+
+    if match:
+        _key, info = match
+        app_name = info["name"]
+        console.print(f"[red]■[/red] Closing [bold]{app_name}[/bold]...")
+        try:
+            subprocess.run(
+                [
+                    "osascript",
+                    "-e",
+                    f'tell application "{app_name}" to quit',
+                ],
+                check=True,
+                capture_output=True,
+                text=True,
+            )
+        except subprocess.CalledProcessError:
+            # Fallback: SIGTERM via pkill
+            try:
+                subprocess.run(
+                    ["pkill", "-f", app_name], capture_output=True
+                )
+            except Exception:
+                console.print(f"[red]✗ Could not close {app_name}[/red]")
+    else:
+        console.print(f"[red]✗ App '{name}' not found in registry.[/red]")
+        console.print(
+            "[dim]Run [bold]scan[/bold] to update the app registry.[/dim]"
+        )
+
+
+def list_apps(console: Console) -> None:
+    """Print a table of all registered applications."""
+    registry = load_registry()
+
+    if not registry:
+        console.print(
+            "[yellow]⚠  No app registry found. "
+            "Run [bold]scan[/bold] first.[/yellow]"
+        )
+        return
+
+    table = Table(
+        title="Registered Applications",
+        show_lines=False,
+        border_style="dim",
+        title_style="bold cyan",
+    )
+    table.add_column("#", style="dim", justify="right", width=4)
+    table.add_column("Application", style="cyan bold", no_wrap=True)
+    table.add_column("Path", style="dim")
+
+    for i, key in enumerate(sorted(registry.keys()), 1):
+        info = registry[key]
+        table.add_row(str(i), info["name"], info["path"])
+
+    console.print()
+    console.print(table)
+    console.print(
+        f"\n[dim]{len(registry)} applications registered • "
+        f"Registry: {get_registry_path()}[/dim]\n"
+    )
+
+
+def list_running(console: Console) -> None:
+    """List currently running GUI applications via System Events."""
+    try:
+        result = subprocess.run(
+            [
+                "osascript",
+                "-e",
+                'tell application "System Events" to get name of '
+                "every process whose background only is false",
+            ],
+            capture_output=True,
+            text=True,
+            check=True,
+        )
+        app_names = sorted(
+            name.strip() for name in result.stdout.strip().split(", ")
+        )
+
+        table = Table(
+            title="Running Applications",
+            show_lines=False,
+            border_style="dim",
+            title_style="bold green",
+        )
+        table.add_column("#", style="dim", justify="right", width=4)
+        table.add_column("Application", style="green bold", no_wrap=True)
+
+        for i, name in enumerate(app_names, 1):
+            table.add_row(str(i), name)
+
+        console.print()
+        console.print(table)
+        console.print(f"\n[dim]{len(app_names)} applications running[/dim]\n")
+
+    except subprocess.CalledProcessError as e:
+        console.print(
+            f"[red]✗ Failed to list running apps:[/red] {e.stderr.strip()}"
+        )
+    except Exception as e:
+        console.print(f"[red]✗ Error:[/red] {e}")

commands/files.py

@@ -0,0 +1,310 @@
+"""File utility commands — tree, preview, mkp, search."""
+
+import os
+from pathlib import Path
+
+from rich.console import Console
+from rich.syntax import Syntax
+from rich.table import Table
+from rich.tree import Tree
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def _format_size(size: int) -> str:
+    """Return a human-readable file-size string."""
+    for unit in ("B", "KB", "MB", "GB"):
+        if size < 1024:
+            return f"{size:.0f}{unit}" if unit == "B" else f"{size:.1f}{unit}"
+        size /= 1024
+    return f"{size:.1f}TB"
+
+
+_LEXER_MAP: dict[str, str] = {
+    "py": "python", "js": "javascript", "ts": "typescript",
+    "jsx": "jsx", "tsx": "tsx", "rb": "ruby", "go": "go",
+    "rs": "rust", "java": "java", "c": "c", "cpp": "cpp",
+    "h": "c", "hpp": "cpp", "cs": "csharp", "swift": "swift",
+    "kt": "kotlin", "sh": "bash", "zsh": "bash", "bash": "bash",
+    "json": "json", "yaml": "yaml", "yml": "yaml",
+    "toml": "toml", "xml": "xml", "html": "html",
+    "css": "css", "scss": "scss", "md": "markdown",
+    "sql": "sql", "dockerfile": "dockerfile",
+    "makefile": "makefile", "mk": "makefile",
+    "r": "r", "lua": "lua", "pl": "perl", "php": "php",
+}
+
+
+# ---------------------------------------------------------------------------
+# tree
+# ---------------------------------------------------------------------------
+
+def handle_tree(args: list[str], cwd: str, console: Console) -> None:
+    """Display a directory tree using Rich's Tree widget.
+
+    Usage: tree [path] [--depth N]
+    Defaults to the current directory with a depth of 3.
+    """
+    target = cwd
+    max_depth = 3
+
+    i = 0
+    while i < len(args):
+        if args[i] == "--depth" and i + 1 < len(args):
+            try:
+                max_depth = int(args[i + 1])
+            except ValueError:
+                console.print("[red]✗ --depth requires a number[/red]")
+                return
+            i += 2
+        else:
+            target = (
+                args[i]
+                if os.path.isabs(args[i])
+                else str(Path(cwd) / args[i])
+            )
+            i += 1
+
+    target_path = Path(target).resolve()
+
+    if not target_path.exists():
+        console.print(f"[red]✗ Path not found: {target}[/red]")
+        return
+    if not target_path.is_dir():
+        console.print(f"[red]✗ Not a directory: {target}[/red]")
+        return
+
+    tree = Tree(
+        f"[bold cyan]📁 {target_path.name or str(target_path)}[/bold cyan]",
+        guide_style="dim",
+    )
+    _build_tree(target_path, tree, max_depth, current_depth=0)
+
+    console.print()
+    console.print(tree)
+    console.print()
+
+
+def _build_tree(
+    path: Path, tree: Tree, max_depth: int, current_depth: int
+) -> None:
+    """Recursively populate a Rich Tree, skipping hidden entries."""
+    if current_depth >= max_depth:
+        return
+
+    try:
+        entries = sorted(
+            path.iterdir(),
+            key=lambda p: (not p.is_dir(), p.name.lower()),
+        )
+    except PermissionError:
+        tree.add("[red]⚠ Permission denied[/red]")
+        return
+
+    # Skip hidden files/dirs
+    entries = [e for e in entries if not e.name.startswith(".")]
+
+    for entry in entries:
+        if entry.is_dir():
+            branch = tree.add(f"[bold blue]📁 {entry.name}[/bold blue]")
+            _build_tree(entry, branch, max_depth, current_depth + 1)
+        else:
+            try:
+                size_str = _format_size(entry.stat().st_size)
+            except OSError:
+                size_str = "?"
+            tree.add(f"[green]{entry.name}[/green] [dim]({size_str})[/dim]")
+
+
+# ---------------------------------------------------------------------------
+# preview
+# ---------------------------------------------------------------------------
+
+def handle_preview(args: list[str], cwd: str, console: Console) -> None:
+    """Preview a file with syntax highlighting.
+
+    Usage: preview <file> [--lines N]
+    Defaults to 30 lines.
+    """
+    if not args:
+        console.print("[red]✗ Usage: preview <file> [--lines N][/red]")
+        return
+
+    max_lines = 30
+    filepath = None
+
+    i = 0
+    while i < len(args):
+        if args[i] == "--lines" and i + 1 < len(args):
+            try:
+                max_lines = int(args[i + 1])
+            except ValueError:
+                console.print("[red]✗ --lines requires a number[/red]")
+                return
+            i += 2
+        else:
+            filepath = args[i]
+            i += 1
+
+    if not filepath:
+        console.print("[red]✗ No file specified[/red]")
+        return
+
+    target = (
+        Path(filepath)
+        if os.path.isabs(filepath)
+        else Path(cwd) / filepath
+    )
+
+    if not target.exists():
+        console.print(f"[red]✗ File not found: {filepath}[/red]")
+        return
+    if not target.is_file():
+        console.print(f"[red]✗ Not a file: {filepath}[/red]")
+        return
+
+    try:
+        content = target.read_text(errors="replace")
+        lines = content.splitlines()
+        total_lines = len(lines)
+        preview_content = "\n".join(lines[:max_lines])
+
+        ext = target.suffix.lstrip(".")
+        lexer = _LEXER_MAP.get(ext.lower(), "text")
+
+        syntax = Syntax(
+            preview_content,
+            lexer,
+            theme="monokai",
+            line_numbers=True,
+            word_wrap=False,
+        )
+
+        console.print()
+        console.print(
+            f"[bold cyan]📄 {target.name}[/bold cyan] "
+            f"[dim]({total_lines} lines total)[/dim]"
+        )
+        console.print(syntax)
+
+        if total_lines > max_lines:
+            console.print(
+                f"\n[dim]... showing {max_lines} of {total_lines} lines "
+                f"(use --lines N to show more)[/dim]"
+            )
+        console.print()
+
+    except Exception as e:
+        console.print(f"[red]✗ Error reading file:[/red] {e}")
+
+
+# ---------------------------------------------------------------------------
+# mkp  (mkdir -p)
+# ---------------------------------------------------------------------------
+
+def handle_mkp(args: list[str], cwd: str, console: Console) -> None:
+    """Create directories recursively (like mkdir -p).
+
+    Usage: mkp <dir> [dir ...]
+    """
+    if not args:
+        console.print("[red]✗ Usage: mkp <directory> [directory ...][/red]")
+        return
+
+    for dir_name in args:
+        target = (
+            Path(dir_name)
+            if os.path.isabs(dir_name)
+            else Path(cwd) / dir_name
+        )
+        try:
+            target.mkdir(parents=True, exist_ok=True)
+            console.print(f"[green]✓[/green] Created [bold]{target}[/bold]")
+        except Exception as e:
+            console.print(f"[red]✗ Failed to create {dir_name}:[/red] {e}")
+
+
+# ---------------------------------------------------------------------------
+# search  (recursive glob)
+# ---------------------------------------------------------------------------
+
+def handle_search(args: list[str], cwd: str, console: Console) -> None:
+    """Find files matching a glob pattern.
+
+    Usage: search <pattern> [--path <dir>]
+    Searches recursively from the current directory (or --path).
+    Named 'search' to avoid shadowing the system 'find' command.
+    """
+    if not args:
+        console.print("[red]✗ Usage: search <pattern> [--path <dir>][/red]")
+        return
+
+    pattern = args[0]
+    search_dir = cwd
+
+    i = 1
+    while i < len(args):
+        if args[i] == "--path" and i + 1 < len(args):
+            search_dir = (
+                args[i + 1]
+                if os.path.isabs(args[i + 1])
+                else str(Path(cwd) / args[i + 1])
+            )
+            i += 2
+        else:
+            i += 1
+
+    search_path = Path(search_dir)
+    if not search_path.exists():
+        console.print(f"[red]✗ Path not found: {search_dir}[/red]")
+        return
+
+    matches = list(search_path.rglob(pattern))
+
+    # Filter out entries inside hidden directories
+    matches = [
+        m
+        for m in matches
+        if not any(
+            part.startswith(".") for part in m.relative_to(search_path).parts
+        )
+    ]
+
+    if not matches:
+        console.print(f"[yellow]No files matching '{pattern}' found.[/yellow]")
+        return
+
+    table = Table(
+        title=f"Files matching '{pattern}'",
+        show_lines=False,
+        border_style="dim",
+        title_style="bold cyan",
+    )
+    table.add_column("#", style="dim", justify="right", width=4)
+    table.add_column("File", style="cyan", no_wrap=True)
+    table.add_column("Size", style="dim", justify="right")
+    table.add_column("Path", style="dim")
+
+    display_limit = 50
+    for i, match in enumerate(matches[:display_limit], 1):
+        try:
+            size = (
+                _format_size(match.stat().st_size)
+                if match.is_file()
+                else "[dir]"
+            )
+        except OSError:
+            size = "?"
+        rel = str(match.relative_to(search_path).parent)
+        table.add_row(str(i), match.name, size, rel if rel != "." else "")
+
+    console.print()
+    console.print(table)
+
+    if len(matches) > display_limit:
+        console.print(
+            f"\n[dim]... showing {display_limit} of {len(matches)} results[/dim]"
+        )
+    console.print(f"\n[dim]{len(matches)} files found[/dim]\n")

executor.py

@@ -0,0 +1,273 @@
+"""Command executor — routes input to custom handlers or forwards to system shell.
+
+This module is the brain of the routing layer.  It maintains shell state
+(current_directory, previous_directory) and decides whether a command is
+handled by our own code or forwarded to the user's real zsh shell.
+
+State is stored in module-level variables instead of a class.
+"""
+
+import os
+import subprocess
+from pathlib import Path
+
+from rich.console import Console
+from rich.table import Table
+
+from commands.apps import close_app, list_apps, list_running, open_app
+from commands.files import (
+    handle_mkp,
+    handle_preview,
+    handle_search,
+    handle_tree,
+)
+from registry.scanner import scan_applications
+
+
+# ---------------------------------------------------------------------------
+# Module-level state (instead of class attributes)
+# ---------------------------------------------------------------------------
+
+console: Console = None           # Set by init()
+current_directory: str = os.getcwd()
+previous_directory: str = None
+
+# Descriptions shown by the `help` command
+COMMAND_HELP = {
+    "cd":      "Change directory  (cd <path> | cd ~ | cd - | cd)",
+    "clear":   "Clear the terminal screen",
+    "scan":    "Scan /Applications and build the app registry",
+    "open":    "Open an application  (open <app_name>)",
+    "close":   "Close a running application  (close <app_name>)",
+    "apps":    "List all registered applications",
+    "running": "List currently running GUI applications",
+    "tree":    "Display directory tree  (tree [path] [--depth N])",
+    "preview": "Preview file with syntax highlighting  (preview <file> [--lines N])",
+    "mkp":     "Create directories recursively  (mkp <dir> [dir ...])",
+    "search":  "Find files by glob pattern  (search <pattern> [--path <dir>])",
+    "help":    "Show this help message",
+    "exit":    "Exit Goutham Shell  (also: quit)",
+}
+
+
+def init(shell_console: Console) -> None:
+    """Initialize the executor with a Rich console."""
+    global console
+    console = shell_console
+
+
+# ---------------------------------------------------------------------------
+# Main routing function
+# ---------------------------------------------------------------------------
+
+def execute(user_input: str) -> None:
+    """Parse the first token and route to the right handler."""
+    parts = user_input.strip().split()
+    if not parts:
+        return
+
+    cmd = parts[0]
+    args = parts[1:]
+    cmd_lower = cmd.lower()
+
+    handler = {
+        "cd":      lambda: handle_cd(args),
+        "clear":   lambda: handle_clear(),
+        "help":    lambda: handle_help(),
+        "scan":    lambda: handle_scan(),
+        "open":    lambda: handle_open(args, user_input),
+        "close":   lambda: handle_close(args),
+        "apps":    lambda: handle_apps(),
+        "running": lambda: handle_running(),
+        "tree":    lambda: handle_tree_cmd(args),
+        "preview": lambda: handle_preview_cmd(args),
+        "mkp":     lambda: handle_mkp_cmd(args),
+        "search":  lambda: handle_search_cmd(args),
+    }.get(cmd_lower)
+
+    if handler:
+        handler()
+    else:
+        forward_to_shell(user_input)
+
+
+# ---------------------------------------------------------------------------
+# Built-in handlers
+# ---------------------------------------------------------------------------
+
+def handle_cd(args: list) -> None:
+    """Change the shell's working directory.
+
+    Supports: cd, cd ~, cd ~/..., cd -, cd <relative>, cd <absolute>.
+    """
+    global current_directory, previous_directory
+
+    if not args:
+        target = Path.home()
+    elif args[0] == "-":
+        if previous_directory:
+            target = Path(previous_directory)
+            console.print(f"[dim]{target}[/dim]")
+        else:
+            console.print("[yellow]cd: no previous directory[/yellow]")
+            return
+    else:
+        raw = " ".join(args)
+        if raw.startswith("~"):
+            raw = str(Path.home()) + raw[1:]
+        target = Path(raw)
+        if not target.is_absolute():
+            target = Path(current_directory) / target
+
+    target = target.resolve()
+
+    if target.is_dir():
+        previous_directory = current_directory
+        current_directory = str(target)
+    else:
+        console.print(
+            f"[red]cd: no such directory: {args[0] if args else ''}[/red]"
+        )
+
+
+def handle_clear() -> None:
+    """Clear the terminal screen."""
+    os.system("clear")
+
+
+def handle_help() -> None:
+    """Show available custom commands."""
+    table = Table(
+        title="Goutham Shell Commands",
+        show_lines=False,
+        border_style="dim",
+        title_style="bold cyan",
+    )
+    table.add_column("Command", style="cyan bold", no_wrap=True, min_width=12)
+    table.add_column("Description", style="white")
+
+    for cmd, desc in COMMAND_HELP.items():
+        table.add_row(cmd, desc)
+
+    console.print()
+    console.print(table)
+    console.print(
+        "\n[dim]All other commands are forwarded transparently "
+        "to your system shell (zsh).[/dim]\n"
+    )
+
+
+def handle_scan() -> None:
+    """Scan for applications."""
+    scan_applications(console)
+
+
+def find_file(filename: str) -> Path | None:
+    """Search common locations for a file."""
+    search_dirs = [
+        Path(current_directory),
+        Path.home(),
+        Path.home() / "Downloads",
+        Path.home() / "Desktop",
+        Path.home() / "Documents",
+    ]
+
+    for directory in search_dirs:
+        candidate = directory / filename
+        if candidate.exists():
+            return candidate
+
+    return None
+
+def handle_open(args: list, raw_input: str) -> None:
+    """Open an application — or fall through to system open."""
+    name = " ".join(args)
+
+    # First try opening as an application
+    if open_app(name, console):
+        return
+
+    # Then try opening as a file
+    file_path = find_file(name)
+    if file_path:
+        subprocess.run(["open", str(file_path)])
+        return
+
+    # Otherwise let macOS handle it
+    forward_to_shell(raw_input)
+
+    first = args[0]
+    # If the argument looks like a path, URL, or flag → forward to system
+    if (
+        first.startswith("-")
+        or first.startswith("/")
+        or first.startswith("./")
+        or first.startswith("..")
+        or "://" in first
+        or first == "."
+    ):
+        forward_to_shell(raw_input)
+        return
+
+    # Try the app registry; fall through to system open if not found
+    app_name = " ".join(args)
+    if not open_app(app_name, console):
+        forward_to_shell(raw_input)
+
+
+def handle_close(args: list) -> None:
+    """Close an application."""
+    if not args:
+        console.print("[red]✗ Usage: close <app_name>[/red]")
+        return
+    close_app(" ".join(args), console)
+
+
+def handle_apps() -> None:
+    """List registered applications."""
+    list_apps(console)
+
+
+def handle_running() -> None:
+    """List running applications."""
+    list_running(console)
+
+
+def handle_tree_cmd(args: list) -> None:
+    """Display directory tree."""
+    handle_tree(args, current_directory, console)
+
+
+def handle_preview_cmd(args: list) -> None:
+    """Preview a file."""
+    handle_preview(args, current_directory, console)
+
+
+def handle_mkp_cmd(args: list) -> None:
+    """Create directories."""
+    handle_mkp(args, current_directory, console)
+
+
+def handle_search_cmd(args: list) -> None:
+    """Find files."""
+    handle_search(args, current_directory, console)
+
+
+# ---------------------------------------------------------------------------
+# System shell forwarding
+# ---------------------------------------------------------------------------
+
+def forward_to_shell(user_input: str) -> None:
+    """Forward a command verbatim to /bin/zsh with the shell's cwd."""
+    try:
+        subprocess.run(
+            user_input,
+            shell=True,
+            cwd=current_directory,
+            executable="/bin/zsh",
+            env={**os.environ, "CLICOLOR_FORCE": "1"},
+        )
+    except FileNotFoundError:
+        console.print("[red]✗ Command not found[/red]")
+    except Exception as e:
+        console.print(f"[red]✗ Error:[/red] {e}")

gc_shell-0.1.0.dist-info/METADATA

@@ -0,0 +1,169 @@
+Metadata-Version: 2.4
+Name: gc-shell
+Version: 0.1.0
+Summary: An intelligent macOS shell
+Author: Goutham Reddy
+License-Expression: MIT
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: rich>=13.0
+Requires-Dist: prompt_toolkit>=3.0
+
+# 🚀 Goutham Shell
+
+A custom interactive shell for macOS that combines the power of a standard terminal with personalized built-in commands.
+
+## Installation
+
+```bash
+# Clone the repository
+git clone <repo-url>
+cd goutham-shell
+
+# Install in development mode
+pip install -e .
+
+# Launch the shell
+goutham
+```
+
+## Quick Start
+
+```
+$ goutham
+🚀 Welcome to Goutham Shell v0.1.0
+   Type help for commands, exit to quit.
+
+💡 No app registry found. Run scan to discover installed applications.
+
+goutham ~ ❯ scan
+🔍 Scanning for applications...
+✓ Found 142 applications
+✓ Registry saved to ~/.goutham/apps.json
+
+goutham ~ ❯ open chrome
+▶ Opening Google Chrome...
+
+goutham ~ ❯ running
+┌──────────────────────────────┐
+│   Running Applications       │
+├────┬─────────────────────────┤
+│  # │ Application             │
+├────┼─────────────────────────┤
+│  1 │ Finder                  │
+│  2 │ Google Chrome           │
+│  3 │ Terminal                │
+└────┴─────────────────────────┘
+
+goutham ~ ❯ ls -la
+total 32
+drwxr-xr-x  8 user staff 256 Jun 26 12:00 .
+...
+```
+
+## Features
+
+### System Commands
+
+All standard terminal commands work transparently — they're forwarded to your system's `zsh` shell:
+
+- `ls`, `pwd`, `cat`, `grep`, `echo`
+- `git status`, `git commit`, `git push`
+- `python app.py`, `node server.js`
+- `docker ps`, `npm run dev`
+- Pipes (`|`), redirection (`>`), chaining (`&&`)
+
+### Custom Commands
+
+| Command | Description |
+|---------|-------------|
+| `scan` | Scan /Applications and build the app registry |
+| `open <app>` | Open an application by name (fuzzy matching) |
+| `close <app>` | Close a running application |
+| `apps` | List all registered applications |
+| `running` | List currently running GUI applications |
+| `tree [path]` | Display a directory tree (`--depth N`) |
+| `preview <file>` | Preview a file with syntax highlighting (`--lines N`) |
+| `mkp <dir>` | Create nested directories (like `mkdir -p`) |
+| `search <pattern>` | Find files by glob pattern (`--path <dir>`) |
+| `help` | Show all available commands |
+| `exit` / `quit` | Exit the shell |
+
+### App Management
+
+On first run, use `scan` to discover installed applications. Then use `open` and `close` with **fuzzy name matching** — no need to type the full name:
+
+```
+goutham ~ ❯ open chrome      # Opens "Google Chrome"
+goutham ~ ❯ open code        # Opens "Visual Studio Code"
+goutham ~ ❯ close spotify    # Closes "Spotify"
+```
+
+The `open` command is smart — paths, URLs, and flags are forwarded to the system `open`:
+
+```
+goutham ~ ❯ open .               # Opens current dir in Finder
+goutham ~ ❯ open https://x.com   # Opens URL in default browser
+goutham ~ ❯ open -a Safari       # System open with flags
+```
+
+## Architecture
+
+Goutham Shell is a **wrapper shell** — it intercepts custom commands while forwarding everything else transparently to `zsh`.
+
+```
+User Input → Command Parser → Custom Command? → Execute Handler
+                                    ↓ No
+                            Forward to zsh via subprocess
+```
+
+Key design decisions:
+
+- **Shell state is maintained in-process**: `cd` updates `current_directory` so subsequent commands run in the right place.
+- **No hardcoded paths**: All app paths come from the scanned registry at `~/.goutham/apps.json`.
+- **`shell=True` forwarding**: Preserves pipes, redirection, globbing, and chaining — users get the full power of `zsh`.
+
+## Requirements
+
+- macOS 10.15+
+- Python 3.9+
+- [Rich](https://github.com/Textualize/rich) (installed automatically)
+
+## Configuration
+
+All configuration is stored in `~/.goutham/`:
+
+| File | Purpose |
+|------|---------|
+| `apps.json` | Application registry (generated by `scan`) |
+
+## Project Structure
+
+```
+goutham-shell/
+├── main.py          # Entry point
+├── shell.py         # Interactive REPL loop
+├── executor.py      # Command routing & shell state
+├── commands/
+│   ├── apps.py      # open, close, apps, running
+│   └── files.py     # tree, preview, mkp, search
+├── registry/
+│   └── scanner.py   # macOS app scanner
+├── ai/              # Phase 5+ (AI commands)
+├── utils/
+├── pyproject.toml
+└── README.md
+```
+
+## Roadmap
+
+- [x] Phase 1 — Interactive shell skeleton
+- [x] Phase 2 — System command forwarding with persistent state
+- [x] Phase 3 — Custom built-in commands (app management)
+- [x] Phase 4 — File utility commands
+- [ ] Phase 5 — AI commands (`ai explain`, `ai generate`, `ai summarize`)
+- [ ] Phase 6 — LangGraph agent workflows
+
+## License
+
+MIT

gc_shell-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+executor.py,sha256=IhA5eNbJBHcS-WYcMM6Sis2KQ_RGXsRwzqfEsIpLTf0,8116
+main.py,sha256=5d9l7Ye0rK-yqIE7GyYrBvkM-nj1q5qEhKrcAcLBdN8,180
+shell.py,sha256=K-Ze0eRycFCQN2oPLvTZujP3Eu6h7FXSUrPHmNV0d6o,2951
+commands/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+commands/apps.py,sha256=5kADaULuJQZbvAvgfqP7UB8sO6Yyy-GM7Qjk5uxuhJg,6210
+commands/files.py,sha256=j5R-jQ3Z-SEZOlLeHTF9L7bx2IgKhIB9jJtT_DNCwgg,9406
+registry/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+registry/scanner.py,sha256=PBNqBsOSwIiZQ1WJu3Rdp4oEXhRJSLuE5QGFbhoPlwY,2851
+gc_shell-0.1.0.dist-info/METADATA,sha256=FYhWH4BuhMydZcS8DjmF7Js4hA0Gh3HI4k56h576z6I,5137
+gc_shell-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+gc_shell-0.1.0.dist-info/entry_points.txt,sha256=EIe5PhQA8eRMB3OuxrA7yHWpGYy6vJgNCu2NLIn8-CU,39
+gc_shell-0.1.0.dist-info/top_level.txt,sha256=PuwTqKOZ65P7DAM-AyyNdXuRMtneQC1NqGMSd3-BDqA,38
+gc_shell-0.1.0.dist-info/RECORD,,

gc_shell-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

gc_shell-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+gc-shell = main:main

gc_shell-0.1.0.dist-info/top_level.txt

@@ -0,0 +1,5 @@
+commands
+executor
+main
+registry
+shell

main.py

@@ -0,0 +1,12 @@
+"""Entry point for Goutham Shell."""
+
+from shell import run_shell
+
+
+def main():
+    """Create and run the Goutham Shell."""
+    run_shell()
+
+
+if __name__ == "__main__":
+    main()

registry/scanner.py

@@ -0,0 +1,96 @@
+"""Application scanner for macOS — discovers .app bundles and builds a registry."""
+
+import json
+import os
+from pathlib import Path
+
+from rich.console import Console
+from rich.table import Table
+
+
+REGISTRY_DIR = Path.home() / ".goutham"
+REGISTRY_FILE = REGISTRY_DIR / "apps.json"
+
+
+def get_registry_path() -> Path:
+    """Return the path to the app registry file."""
+    return REGISTRY_FILE
+
+
+def load_registry() -> dict:
+    """Load the app registry from disk. Returns empty dict if not found."""
+    if not REGISTRY_FILE.exists():
+        return {}
+    try:
+        with open(REGISTRY_FILE, "r") as f:
+            return json.load(f)
+    except (json.JSONDecodeError, IOError):
+        return {}
+
+
+def scan_applications(console: Console) -> dict:
+    """Scan /Applications and ~/Applications for .app bundles, write registry.
+
+    Walks both directories recursively, skipping .app bundles nested inside
+    other .app bundles (which are internal frameworks, not user-facing apps).
+    Results are written to ~/.goutham/apps.json keyed by lowercased app name.
+    """
+    console.print("\n[bold cyan]🔍 Scanning for applications...[/bold cyan]\n")
+
+    scan_dirs = [
+        Path("/Applications"),
+        Path("/System/Applications"),
+        Path("/System/Library/CoreServices"),
+        Path.home() / "Applications",
+    ]
+
+    apps: dict[str, dict[str, str]] = {}
+
+    for scan_dir in scan_dirs:
+        if not scan_dir.exists():
+            continue
+
+        for entry in scan_dir.rglob("*.app"):
+            # Skip .app bundles nested inside another .app bundle
+            relative = entry.relative_to(scan_dir)
+            is_nested = any(
+                part.endswith(".app") for part in relative.parts[:-1]
+            )
+            if is_nested:
+                continue
+
+            app_name = entry.stem  # strip .app extension
+            key = app_name.lower()
+            apps[key] = {
+                "name": app_name,
+                "path": str(entry),
+            }
+
+    # Ensure config directory exists and write registry
+    REGISTRY_DIR.mkdir(parents=True, exist_ok=True)
+    with open(REGISTRY_FILE, "w") as f:
+        json.dump(apps, f, indent=2, sort_keys=True)
+
+    # Display results in a Rich table
+    table = Table(
+        title="Discovered Applications",
+        show_lines=False,
+        border_style="dim",
+        title_style="bold cyan",
+    )
+    table.add_column("Application", style="cyan", no_wrap=True)
+    table.add_column("Path", style="dim")
+
+    for key in sorted(apps.keys()):
+        info = apps[key]
+        table.add_row(info["name"], info["path"])
+
+    console.print(table)
+    console.print(
+        f"\n[green]✓[/green] Found [bold]{len(apps)}[/bold] applications"
+    )
+    console.print(
+        f"[green]✓[/green] Registry saved to [dim]{REGISTRY_FILE}[/dim]\n"
+    )
+
+    return apps

shell.py

@@ -0,0 +1,110 @@
+"""Interactive shell loop — prompt, read input, delegate to executor.
+
+This module owns the UI (prompt, welcome banner, goodbye message) and
+nothing else.  All command logic lives in executor.py and the commands/
+package.
+"""
+
+from pathlib import Path
+
+from rich.console import Console
+from rich.panel import Panel
+from rich.text import Text
+
+import executor
+from registry.scanner import get_registry_path
+from prompt_toolkit import PromptSession
+from prompt_toolkit.history import FileHistory
+from prompt_toolkit.formatted_text import HTML
+
+
+# One shared console for the entire shell
+console = Console()
+
+history_file = str(Path.home() / ".gc_shell_history")
+
+session = PromptSession(
+    history=FileHistory(history_file)
+)
+
+
+def build_prompt() -> str:
+    """Build a Rich-styled prompt showing the current directory."""
+    cwd = executor.current_directory
+    home = str(Path.home())
+
+    if cwd == home:
+        display = "~"
+    elif cwd.startswith(home + "/"):
+        display = "~" + cwd[len(home):]
+    else:
+        display = cwd
+
+    return HTML(
+        f"<ansicyan><b>gc-shell</b></ansicyan> "
+        f"<ansigray>{display}</ansigray> "
+        f"<ansigreen><b>❯</b></ansigreen> "
+    )
+
+
+def print_welcome() -> None:
+    """Print the welcome banner."""
+    banner = Text()
+    banner.append("🚀 ", style="bold")
+    banner.append("Goutham Shell", style="bold cyan")
+    banner.append(" v0.1.0\n", style="dim")
+    banner.append("   Type ", style="dim")
+    banner.append("help", style="bold cyan")
+    banner.append(" for commands, ", style="dim")
+    banner.append("exit", style="bold cyan")
+    banner.append(" to quit.", style="dim")
+
+    console.print()
+    console.print(Panel(banner, border_style="cyan", padding=(0, 2)))
+    console.print()
+
+
+def check_first_run() -> None:
+    """If no app registry exists, suggest running scan."""
+    if not get_registry_path().exists():
+        console.print(
+            "[yellow]💡 No app registry found. "
+            "Run [bold]scan[/bold] to discover installed "
+            "applications.[/yellow]\n"
+        )
+
+
+def print_goodbye() -> None:
+    """Print the goodbye message."""
+    console.print("\n[bold cyan]👋 See you later![/bold cyan]\n")
+
+
+def run_shell() -> None:
+    """Start the interactive read-eval-print loop."""
+    # Initialize the executor with our console
+    executor.init(console)
+
+    print_welcome()
+    check_first_run()
+
+    while True:
+        try:
+            prompt = build_prompt()
+            user_input = session.prompt(prompt).strip()
+
+            if not user_input:
+                continue
+
+            if user_input.lower() in ("exit", "quit"):
+                print_goodbye()
+                break
+
+            executor.execute(user_input)
+
+        except KeyboardInterrupt:
+            console.print()  # newline after ^C
+            continue
+        except EOFError:
+            console.print()
+            print_goodbye()
+            break