gdx 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Type-Delta
+
+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.
+
+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.

package/README.md

@@ -0,0 +1,254 @@
+# gdx (Git Developer Experience)
+
+**The git CLI wrapper that treats you like a human, not a compiler.**
+
+![License](https://img.shields.io/badge/license-MIT-blue.svg) ![Status](https://img.shields.io/badge/status-experimental-orange.svg)
+
+> [!WARNING]
+> **⚠️ PRE-ALPHA WARNING:** This project is currently in a "trial phase" (i.e., I'm dogfooding it daily). Expect breaking changes, missing features, and the occasional hiccup.
+
+---
+
+## What is gdx?
+
+`gdx` is a drop-in wrapper for the Git CLI. It doesn't replace Git; it just makes it less... unpleasant.
+
+It wraps standard git commands with intelligent shorthands and adds powerful new capabilities that Git is missing like safety rails for destructive actions (undoable `reset --hard`), introduces new workflows for parallel editing and local analytics.
+
+**Why gdx?**
+
+- **👍 Convenience:** Type less, do more. `git status`? how about `gdx s`?, `git reset HEAD~3`? why not `gdx res ~3`?
+- **🛡️ Safety:** `gdx clear` wipes your directory but saves a backup patch. No more "oops" moments.
+- **🧠 Logic:** Handles the things Git makes hard, like dropping a range of stashes (`drop 2..6`).
+- **📊 Local-First Stats:** Beautiful TrueColor graphs and stats generated from your local history.
+- **🤖 AI Integration:** Generate commit messages and roast your history with local or cloud LLMs.
+
+## Installation
+
+<details expanded>
+<summary><strong>With NPM</strong></summary>
+
+### Default (Recommended)
+
+Uses the bundled JS version. Works everywhere Node.js 18+ is installed.
+This is the easiest way to get started and ensures maximum compatibility.
+
+```bash
+npm i -g gdx
+```
+
+### Prebuilt Binary
+
+Downloads a precompiled native binary. No runtime dependency on Node/Bun for execution.
+
+```bash
+GDX_USE_PREBUILT=1 npm i -g gdx # bash / zsh
+# or
+$env:GDX_USE_PREBUILT='1'; npm i -g gdx # powershell / fish
+```
+
+### Build Locally
+
+Compiles a native binary on your machine during install. Requires [Bun](https://bun.sh) to be installed.
+
+```bash
+GDX_BUILD_NATIVE=1 npm i -g gdx # bash / zsh
+# or
+$env:GDX_BUILD_NATIVE='1'; npm i -g gdx # powershell / fish
+```
+
+> [!NOTE] If your environment sets `ignore-scripts=true`, the installation will succeed but default to the Node.js fallback.
+> Run `gdx doctor` to verify your installation status.
+
+</details>
+
+<details>
+<summary><strong>Download Manually</strong></summary>
+
+Prebuilt stand-alone binaries are available on the [Releases](https://github.com/Type-Delta/gdx/releases/download) page.
+
+</details>
+
+<details>
+<summary><strong>Build it yourself</strong></summary>
+
+Requires [Bun](https://bun.sh) to be installed.
+
+```bash
+git clone https://github.com/Type-Delta/gdx.git --depth 1
+cd gdx
+bun install
+bun run build
+```
+
+Your compiled binary will be in `./dist/gdx` (or `./dist/gdx.exe` on Windows).
+
+</details>
+
+### Optional: Shell Integration
+
+To enable features like `gdx parallel switch` (auto-cd into worktrees), you need to add shell integration.
+
+To do this add the following line to the **End** of your shell profile (`~/.bashrc`, `~/.zshrc`, etc.):
+
+#### For bash and zsh:
+
+```bash
+eval "$(gdx --init --shell bash)"  # for bash
+eval "$(gdx --init --shell zsh)"   # for zsh
+```
+
+#### For fish:
+
+```fish
+gdx --init --shell fish | source
+```
+
+#### For PowerShell:
+
+To find your profile path, run `$PROFILE` in PowerShell.
+
+```powershell
+Invoke-Expression (& { (gdx --init --shell pwsh | Out-String) })
+```
+
+## Core Features
+
+### 1. Intelligent Shorthands
+
+`gdx` isn't just a list of static aliases. It understands partial commands and expands them smartly.
+
+```bash
+gdx s             # -> git status
+gdx lg            # -> git log --oneline --graph --all --decorate
+gdx lg export     # -> Exports git log to a markdown file
+gdx pl -au        # -> git pull --allow-unrelated-histories
+gdx ps -fl        # -> git push --force-with-lease
+gdx reset ~2      # -> git reset HEAD~2
+```
+
+> [!NOTE]
+> This wrapper forwards unrecognized commands directly to `git`, so you can use it as a full git replacement.
+
+### 2. Smart Linting
+
+Catch issues before they reach the remote. `gdx lint` checks for:
+
+- Spelling errors in commit messages
+- Conflict markers left in code
+- Sensitive content (keys, tokens)
+- Large files
+
+You can configure `gdx` to run this automatically before every push.
+
+### 3. The Safety Net: `clear` vs `reset`
+
+We've all accidentally reset files we meant to keep. `gdx clear` is the solution.
+
+- **`gdx clear`**: Creates a timestamped patch backup in a temp folder, then effectively runs `reset --hard` & `clean -fd`.
+- **`gdx clear pardon`**: "Wait, I didn't mean to do that." Applies the backup patch and restores your changes.
+
+### 4. Parallel Worktrees (Experimental)
+
+Need to work on the **same branch** in multiple isolated environments without checking out new branches?
+
+```bash
+# Manage forked worktrees for the current branch
+gdx parallel fork    # Create a new temp-backed fork
+gdx parallel list    # See where your forks are
+gdx parallel switch  # Switch between forks (requires shell integration)
+gdx parallel open    # Open any fork in your default editor
+gdx parallel join    # Merge changes from a fork back to main
+```
+
+### 5. Advanced Stash Management
+
+Git stash is great until you need to clean it up.
+
+```bash
+gdx sta l           # git stash list
+gdx sta d 2..6      # Drops stashes 2 through 6.
+                    # (Drops high->low to prevent index shifting)
+```
+
+### 6. AI-Powered Commits
+
+Struggling to come up with a commit message? Let `gdx` do it for you.
+
+```bash
+gdx commit auto   # Generates a commit message based on staged changes, then commits them.
+# or
+# Generates a commit message based on staged changes, but does not commit them.
+# `--copy` also copies the message to clipboard.
+gdx commit auto --no-commit --copy
+# You can also configure which LLM to use with `gdx-config`
+```
+
+### 7. Fun & Analytics
+
+Tools to help you feel productive without leaving the terminal.
+
+- **`gdx stats`**: Shows fun contribution statistics and metrics for your current repo.
+- **`gdx graph`**: Renders a GitHub-style contribution heatmap in your terminal using TrueColor.
+- **`gdx nocap`**: Uses AI to roast your latest commit message.
+
+## Command Reference
+
+| Command      | Expansion / Function                                |
+| :----------- | :-------------------------------------------------- |
+| `s`, `stat`  | `git status`                                        |
+| `lg`, `lo`   | `git log --oneline --graph --all --decorate`        |
+| `sw`, `swit` | `git switch`                                        |
+| `br`, `bra`  | `git branch`                                        |
+| `cmi`, `com` | `git commit` (Try `gdx cmi auto` for AI messages!)  |
+| `res`        | `git reset` (supports `res ~3`, `res -h` expansion) |
+| `sta`, `st`  | `git stash`                                         |
+| `lint`       | Run pre-push checks (spelling, secrets, etc.)       |
+| `gdx-config` | Manage gdx configuration                            |
+
+_Run `gdx ghelp` to see the full list of expansions._
+
+## Development
+
+This project uses **Bun** for development because it's fast and the developer experience is great.
+
+1. Clone the repo
+2. Prepare the development environment:
+   ```bash
+   bun run prepare-dev
+   ```
+3. Run in dev mode:
+
+   ```bash
+   bun start -- # your gdx commands here
+
+   # for example:
+   bun start -- s # runs `gdx s` (git status)
+   ```
+
+## Roadmap
+
+Since this is currently a solo "scratch your own itch" project, the roadmap is fluid, but here is what is on the horizon:
+
+- [x] **Configurability:** Allow users to define their own shorthands in a `.gdxrc.toml` file.
+- [ ] **Shell Integration:** Auto-completion scripts for Zsh/Bash/Fish/Powershell.
+- [ ] **Commit with specified editor:** like, `gdx commit --vim` to open Vim for commit messages.
+- [ ] **Quick commit:** `add`, `commit`, and `push` in one command like `gdx qc -pa` (`git add . && gdx commit auto && git push`)
+- [x] **Quick linting before push:** `gdx lint` to run following checks before pushing:
+   - commit message spelling
+   - env or sensitive content scanning
+   - conflict markers
+   - abnormal file sizes
+     with an option to automatically run lint before every push (bypass with `gdx push --no-lint`)
+- [ ] **Undoable stash drop**
+- [x] **Parallel worktree switching** `gdx parallel switch` Jump between forks (auto-cd) (requires shell integration with `gdx --init --shell`)
+- [ ] **Seamless Integration with fzf and cloc**
+      automatically detect and use fzf and/or cloc if installed for:
+   - Interactive fuzzy search for branches, commits, stash, log and files instead of `less`
+   - Code line statistics in `gdx stats` using `cloc`
+- [ ] **gdx clear Untracked files support**: `gdx clear` currently only saves changes to tracked files. Add an option to back up untracked files as well.
+- [ ] **gdx migrate**: move dirty changes to another branch/worktree without committing.
+
+## License
+
+MIT © Type-Delta