@airscript/ghitgud 1.0.3 → 2.1.0

package/README.md

@@ -1,45 +1,139 @@
-# Ghitgud
-A simple CLI to give superpowers to GitHub.
+<h1 align="center">
+  Ghitgud
+</h1>
+
+<p align="center">
+  A simple CLI to give superpowers to GitHub.
+</p>
+
+<p align="center">
+  <img src="https://github.com/user-attachments/assets/57aac0c0-1bd2-4cb4-8445-36a161a7e2ee" alt="Usage GIF" />
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@airscript/ghitgud"><img src="https://img.shields.io/npm/v/@airscript/ghitgud" alt="npm" /></a>
+  <a href="https://github.com/airscripts/ghitgud/blob/main/LICENSE"><img src="https://img.shields.io/github/license/airscripts/ghitgud" alt="License" /></a>
+</p>
 
 ## Table of Contents
+
 - [Installation](#installation)
-- [Usage](#usage)
-- [Wiki](#wiki)
+- [Configuration](#configuration)
+- [Commands](#commands)
+- [Templates](#templates)
+- [Output Format](#output-format)
+- [Development](#development)
 - [Contributing](#contributing)
 - [Support](#support)
 - [License](#license)
 
 ## Installation
-Follow the steps below to make use of Ghitgud.
 
-Clone this repository:
 ```bash
 npm install -g @airscript/ghitgud
 ```
 
-## Usage
-After installing you'll be able to access the CLI and its relative help command:
+## Configuration
+
+Set a GitHub personal access token and repository (in `owner/repo` format):
+
+```bash
+ghitgud config set token <your-token>
+ghitgud config set repo owner/repository
+```
+
+Retrieve a configured value:
+
 ```bash
-ghitgud help
+ghitgud config get token
+ghitgud config get repo
+```
+
+> Create a token at: https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens
+
+## Commands
+
 ```
+ghitgud gh <args>              Pass through to the gh CLI
+ghitgud notifications list       List notifications
+ghitgud notifications list -a    Include read notifications
+ghitgud notifications list -p    Only participating
+ghitgud notifications list -r owner/repo  Filter by repository
+ghitgud notifications read <id>   Mark a notification as read
+ghitgud notifications done <id>   Mark a notification as done
+ghitgud activity                 Assigned issues, review requests, mentions
+ghitgud mentions                 Recent @mentions of you
+ghitgud ping                     Check if the CLI is working
+ghitgud labels list              List all labels for a repository
+ghitgud labels pull              Pull labels from a repository to local config
+ghitgud labels pull -t <name>   Pull labels from a built-in template
+ghitgud labels push              Push local labels to a repository
+ghitgud labels push -t <name>   Push a built-in template to a repository
+ghitgud labels prune             Delete all local labels from a repository
+ghitgud config set <key> <val>   Set a configuration value (token or repo)
+ghitgud config get <key>         Get a configuration value
+```
+
+## Templates
+
+Built-in label presets are available with the `--template` / `-t` flag:
+
+| Template       | Description                  |
+| -------------- | ---------------------------- |
+| `base`         | Minimal set: bug and feature |
+| `conventional` | Conventional Commits labels  |
+| `github`       | GitHub default labels        |
 
-Remember that to use the CLI you have to set a token and a repo with the format `username/repository` (e.g. airscripts/ghitgud):
 ```bash
-ghitgud config set token `your-token-here`
-ghitgud config set repo `username/repository`
+ghitgud labels pull -t conventional
+ghitgud labels push -t conventional
+```
+
+## Output Format
+
+All commands output JSON to stdout on success and JSON to stderr on failure.
+
+Success:
+
+```json
+{
+  "success": true,
+  "metadata": [...]
+}
+```
+
+Error:
+
+```json
+{
+  "success": false,
+  "error": "You must set the GHITGUD_GITHUB_REPO environment variable."
+}
 ```
-> You can create your token with: https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens
 
-## Wiki
-For more in-depth help with the usage of this CLI, just check the wiki: https://github.com/airscripts/ghitgud/wiki
+## Development
+
+```bash
+pnpm install            # install dependencies
+pnpm build              # build with Vite (single CJS bundle)
+pnpm start              # run the CLI locally
+pnpm test               # run tests (watch mode)
+pnpm test -- --run      # single test run (no watch)
+pnpm test:coverage      # run tests with coverage
+pnpm typecheck          # type check without emitting
+pnpm lint               # type check (alias for typecheck)
+pnpm clean              # remove build artifacts
+```
 
 ## Contributing
+
 Contributions and suggestions about how to improve this project are welcome!
 Please follow [our contribution guidelines](https://github.com/airscripts/ghitgud/blob/main/CONTRIBUTING.md).
 
 ## Support
-If you want to support my work you can do it by following me, leaving a star, sharing my projects or also donating at the links below.  
-Choose what you find more suitable for you:  
+
+If you want to support my work you can do it by following me, leaving a star, sharing my projects or also donating at the links below.
+Choose what you find more suitable for you:
 
 <a href="https://sponsor.airscript.it" target="blank">
   <img src="https://raw.githubusercontent.com/airscripts/assets/main/images/github-sponsors.svg" alt="GitHub Sponsors" width="30px" />
@@ -48,5 +142,6 @@ Choose what you find more suitable for you:
   <img src="https://raw.githubusercontent.com/airscripts/assets/main/images/kofi.svg" alt="Kofi" width="30px" />
 </a>
 
-## License  
+## License
+
 This repository is licensed under [GPL-3.0 License](https://github.com/airscripts/ghitgud/blob/main/LICENSE).

package/VERSION

@@ -1 +1 @@
-1.0.3
+2.1.0