gc-shell 0.1.0__tar.gz

gc_shell-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,158 @@
+# 🚀 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/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}")