gh-manager-cli 1.2.0

package/CHANGELOG.md

@@ -0,0 +1,52 @@
+# [1.2.0](https://github.com/wiiiimm/gh-manager-cli/compare/v1.1.1...v1.2.0) (2025-08-31)
+
+
+### Features
+
+* add npx support as primary installation method ([eeae1c8](https://github.com/wiiiimm/gh-manager-cli/commit/eeae1c8e60f0b4bd1f3076a16b65aec01cf5afdf))
+* re-enable NPM publishing and update installation docs ([e6d5cff](https://github.com/wiiiimm/gh-manager-cli/commit/e6d5cffc64678899ecc89cf294c4413fab4cdf66))
+
+## [1.1.1](https://github.com/wiiiimm/gh-manager-cli/compare/v1.1.0...v1.1.1) (2025-08-31)
+
+
+### Bug Fixes
+
+* temporarily disable NPM publishing due to 2FA requirement ([2ab09ca](https://github.com/wiiiimm/gh-manager-cli/commit/2ab09ca8d543c771f97c999ad6beb6ebf36747be))
+
+# [1.1.0](https://github.com/wiiiimm/gh-manager-cli/compare/v1.0.0...v1.1.0) (2025-08-31)
+
+
+### Features
+
+* re-enable NPM publishing with NPM_TOKEN configured ([a0c3520](https://github.com/wiiiimm/gh-manager-cli/commit/a0c3520ca53092941d4a761d6f94a66a500753dd))
+
+# 1.0.0 (2025-08-31)
+
+
+### Bug Fixes
+
+* **delete:** use GitHub REST API DELETE /repos/{owner}/{repo} with token; update UI and docs accordingly ([e921ab9](https://github.com/wiiiimm/gh-manager-cli/commit/e921ab9917e27d368fc73f326bbe98081386ca18))
+* resolve pnpm lockfile compatibility in CI workflow ([ece890f](https://github.com/wiiiimm/gh-manager-cli/commit/ece890f9b8d1b0c91dcb8cf1ab9275537483ea4f))
+* update GitHub Actions workflow to use pnpm instead of npm ([42a0269](https://github.com/wiiiimm/gh-manager-cli/commit/42a02698d1490cf9f562633eddca86f0c54d10a3))
+* update pkg targets to use node18 instead of node20 ([6302567](https://github.com/wiiiimm/gh-manager-cli/commit/6302567f15076e177dbad875f87c363ea5679486))
+
+
+### Features
+
+* add fork sync, improved error handling, and UI enhancements ([165e03e](https://github.com/wiiiimm/gh-manager-cli/commit/165e03e983feb15f2d08301b59d125717b3ba937))
+* add logout functionality with Ctrl+L shortcut ([f51c8b8](https://github.com/wiiiimm/gh-manager-cli/commit/f51c8b85c8890b063812a734a9c01651478fa4e2))
+* add repository visibility toggle TODO item ([0b42fa0](https://github.com/wiiiimm/gh-manager-cli/commit/0b42fa04721209add85dc2dca4339ed5b1ffd79e))
+* add server-side sorting and loading screens ([a082410](https://github.com/wiiiimm/gh-manager-cli/commit/a082410dcbd7125957b0fa9b3982d29eed53317a))
+* complete fork tracking system with comprehensive improvements ([4621e10](https://github.com/wiiiimm/gh-manager-cli/commit/4621e1025d603acf14defb031c4d36de21c11846))
+* disable NPM publishing temporarily to focus on binary releases ([df7718d](https://github.com/wiiiimm/gh-manager-cli/commit/df7718d324ec52e244b9176101aedc5f56a5a22d))
+* implement automated release workflow with compiled binaries ([195ca17](https://github.com/wiiiimm/gh-manager-cli/commit/195ca174857eeef9ce08b6bbfce03ab61f185aa8))
+* initial commit with semantic release setup ([62c4919](https://github.com/wiiiimm/gh-manager-cli/commit/62c4919c1c9061f7a5153c2a363398c9d571e9db))
+* **prefs:** persist UI preferences (s/d/t) in config; load on startup ([bba426a](https://github.com/wiiiimm/gh-manager-cli/commit/bba426a0321e652d74c0dd5d340ff26cc3b98283))
+* **ui:** add Delete Confirmation title and side-by-side buttons with shortcut hints in modal ([2073fd2](https://github.com/wiiiimm/gh-manager-cli/commit/2073fd277506c6f802c1dd46142900597a16c3f1))
+* **ui:** centered delete modal with dimmed list (B-center); increase padding; show confirmation code as placeholder ([04434ba](https://github.com/wiiiimm/gh-manager-cli/commit/04434ba92ad621b1c68985bf3a61e3094f21aa5d))
+* **ui:** density toggle, delete modal with 2-step confirm, centered modal; docs and TODOs updates; dim UI during modal ([27f90c7](https://github.com/wiiiimm/gh-manager-cli/commit/27f90c7e7ba096798bb0b930a3cf707f04218671))
+
+
+### Performance Improvements
+
+* reduce production page size from 25 to 15 ([168c79a](https://github.com/wiiiimm/gh-manager-cli/commit/168c79a0b69704c7c29fb8c95e039127e9b50d6d))

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 William Li
+
+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,193 @@
+# gh-manager-cli
+
+Interactive terminal app to browse and manage your personal GitHub repositories. Built with Ink (React for CLIs) and the GitHub GraphQL API.
+
+## Quick Start
+
+```bash
+# Option 1: Run with npx (no installation required)
+npx github:wiiiimm/gh-manager-cli
+
+# Option 2: Install globally via NPM
+npm install -g gh-manager-cli
+gh-manager
+```
+
+On first run, you'll be prompted for a GitHub Personal Access Token.
+
+## Features
+
+### Core Repository Management
+- **Token Authentication**: Secure PAT storage with validation and persistence
+- **Repository Listing**: Browse all your personal repositories with metadata (stars, forks, language, etc.)
+- **Live Pagination**: Infinite scroll with automatic page prefetching
+- **Real-time Sorting**: Server-side sorting by updated, pushed, name, or stars (with direction toggle)
+- **Smart Filtering**: Client-side search through repository names and descriptions
+- **Repository Actions**:
+  - Open in browser (Enter/`o`)
+  - Delete repository (`Del`/Backspace) with secure two-step confirmation
+  - Archive/unarchive repositories (`a`) with confirmation prompts
+
+### User Interface & Experience
+- **Keyboard Navigation**: Full keyboard control (arrow keys, PageUp/Down, `g`/`G`)
+- **Display Density**: Toggle between compact/cozy/comfy spacing (`t`)
+- **Visual Indicators**: Fork status, private/archived badges, language colors
+- **Loading States**: Contextual loading screens for sorting and refreshing operations
+- **Rate Limit Monitoring**: Live API usage display with visual warnings
+
+### Technical Features
+- **Preference Persistence**: UI settings (sort, density) saved between sessions
+- **Cross-platform**: Works on macOS, Linux, and Windows
+- **Secure Storage**: Token stored with proper file permissions (0600)
+- **Error Handling**: Graceful error recovery with retry mechanisms
+- **Performance**: Efficient GraphQL queries with virtualized rendering
+
+## Installation
+
+### NPX (Recommended - No Installation Required)
+
+Run instantly without installing:
+
+```bash
+# Run directly from GitHub
+npx github:wiiiimm/gh-manager-cli
+```
+
+### NPM Global Install
+
+Install globally for persistent `gh-manager` command:
+
+```bash
+npm install -g gh-manager-cli
+gh-manager
+```
+
+### Pre-built Binaries (No Node.js Required)
+
+Download standalone executables from [GitHub Releases](https://github.com/wiiiimm/gh-manager-cli/releases):
+
+- **Linux**: `gh-manager-linux-x64`
+- **macOS**: `gh-manager-macos-x64` 
+- **Windows**: `gh-manager-windows-x64.exe`
+
+Make the binary executable (Linux/macOS):
+```bash
+chmod +x gh-manager-*
+./gh-manager-*
+```
+
+### From Source
+
+Prerequisites:
+- Node.js 18+
+- pnpm
+
+Install and build:
+
+```bash
+pnpm install
+pnpm build
+```
+
+Run locally:
+
+```bash
+node dist/index.js
+# Or add to PATH for dev
+pnpm link
+gh-manager
+```
+
+## Token & Security
+
+The app needs a GitHub token to read your repositories.
+
+- Provide via env var: `GITHUB_TOKEN` or `GH_TOKEN`, or enter when prompted on first run.
+- Recommended: classic PAT with `repo` scope for listing both public and private repos (read is sufficient).
+- Validation: a minimal `viewer { login }` request verifies the token.
+- Storage: token is saved as JSON in your OS user config directory with POSIX perms `0600`.
+  - macOS: `~/Library/Preferences/gh-manager-cli/config.json`
+  - Linux: `~/.config/gh-manager-cli/config.json`
+  - Windows: `%APPDATA%\gh-manager-cli\config.json`
+- Revocation: you can revoke the PAT at any time in your GitHub settings.
+
+Note: Tokens are stored in plaintext on disk with restricted permissions. Future work may add OS keychain support.
+
+## Usage
+
+Launch the app, then use the keys below:
+
+- Navigation: Up/Down, PageUp/PageDown, `Ctrl+G` (top), `G` (bottom)
+- Refresh: `R`
+- Filter: `/` to enter, type query, Enter to apply (Esc cancels)
+- Sorting: `S` to cycle field (updated → pushed → name → stars → forks), `D` to toggle direction
+- Display density: `T` to toggle compact/cozy/comfy
+- Open in browser: Enter or `O`
+- Delete repository: `Del` or `Ctrl+Backspace` (with confirmation modal)
+  - Uses GitHub REST API (requires `delete_repo` scope and admin rights)
+  - Two-step confirm: type code → confirm (Y/Enter)
+  - Confirm: press `Y` or Enter
+  - Cancel: press `C` or Esc
+- Archive/Unarchive: `Ctrl+A`
+- Logout: `Ctrl+L`
+- Toggle fork metrics: `F`
+- Quit: `Q`
+- Esc: cancels modals or exits filter mode (does not quit)
+
+Status bar shows loaded count vs total. A rate-limit line displays `remaining/limit` and the reset time; it turns yellow when remaining ≤ 10% of the limit.
+
+## Pagination Details
+
+- Uses GitHub GraphQL `viewer.repositories` with `ownerAffiliations: OWNER`, ordered by `UPDATED_AT DESC`.
+- Fetches 50 repos per page and updates `totalCount` each time.
+- Prefetches the next page when your selection nears the end of the loaded list.
+
+## Development
+
+Stack:
+- UI: `ink`, `ink-text-input`, `ink-spinner`
+- API: `@octokit/graphql`
+- Config paths: `env-paths`
+- Language: TypeScript
+- Build: `tsup` (CJS output with shebang)
+
+Scripts:
+
+```bash
+pnpm build          # build to dist/
+pnpm build:binaries # build cross-platform binaries to ./binaries/
+pnpm dev            # watch mode
+pnpm start          # node dist/index.js
+```
+
+Notes:
+- In development mode (set `NODE_ENV=development` or `GH_MANAGER_DEV=1`), the app fetches 5 repos per page to speed iteration.
+
+Project layout:
+- `src/index.tsx` — CLI entry and error handling
+- `src/ui/App.tsx` — token bootstrap, renders `RepoList`
+- `src/ui/RepoList.tsx` — list UI, keys, filtering, sorting, infinite scroll
+- `src/github.ts` — GraphQL client and queries (repos + rateLimit)
+- `src/config.ts` — token read/write and file perms
+- `src/types.ts` — shared types
+
+## Troubleshooting
+
+- Invalid token: enter a valid PAT (recommended scope: `repo`).
+- Rate limited: wait for the reset shown in the banner or reduce navigation.
+- Network errors: check connectivity and press `r` to retry.
+
+## Todo & Roadmap
+
+For the up-to-date task board, see [TODOs.md](./TODOs.md).
+
+Highlights on deck:
+- Density toggle for row spacing (compact/cozy/comfy)
+- Repo actions (archive/unarchive, delete) with confirmations
+- Organization support and switching
+- Server-side search; cached first page for faster startup
+- Optional OS keychain storage via `keytar`
+
+## License
+
+MIT