@openhoo/hoopilot 0.2.3 → 0.3.0

package/README.md

@@ -7,19 +7,79 @@ OpenAI-compatible local proxy for GitHub Copilot accounts. It runs on Bun and ex
 
 This project uses GitHub Copilot's service endpoints and is not an official GitHub product. The upstream API can change without notice. Use it only with accounts and usage patterns you are allowed to use.
 
-## Run
+## Install
+
+### npm (recommended when the registry is reachable)
 
 ```sh
 npx @openhoo/hoopilot
 ```
 
-Before the npm package is published, run the same binary directly from GitHub:
+Or install it globally:
+
+```sh
+npm install -g @openhoo/hoopilot
+# or
+bun add -g @openhoo/hoopilot
+```
+
+### Standalone binary (no npm, no runtime required)
+
+When the npm registry is unreachable but GitHub is, install a prebuilt,
+self-contained binary straight from the latest GitHub release. No Node.js or Bun
+is needed to run it.
+
+Linux / macOS:
+
+```sh
+curl -fsSL https://raw.githubusercontent.com/openhoo/hoopilot/main/scripts/install.sh | sh
+```
+
+Windows (PowerShell):
+
+```powershell
+irm https://raw.githubusercontent.com/openhoo/hoopilot/main/scripts/install.ps1 | iex
+```
+
+The installer detects your OS, CPU architecture (x64/arm64), and libc (glibc or
+musl), downloads the matching binary, verifies its SHA-256 checksum, and installs
+it to `~/.local/bin` (Linux/macOS) or `%LOCALAPPDATA%\Programs\hoopilot`
+(Windows). Override the location with `HOOPILOT_INSTALL_DIR`, or pin a version:
 
 ```sh
-npx github:openhoo/hoopilot
+curl -fsSL .../install.sh | sh -s -- --version 0.2.5 --dir ~/bin
 ```
 
-By default Hoopilot listens on `127.0.0.1:4141`, reads a GitHub token from `COPILOT_GITHUB_TOKEN`, `GITHUB_TOKEN`, `GH_TOKEN`, or `gh auth token`, and exchanges it for a Copilot API token when GitHub supports the exchange endpoint for the account.
+```powershell
+& ([scriptblock]::Create((irm .../install.ps1))) -Version 0.2.5
+```
+
+Prebuilt binaries are available for Linux (x64/arm64, glibc and musl), macOS
+(Intel/Apple Silicon), and Windows (x64/arm64).
+
+## Update
+
+Standalone binaries update themselves in place from the latest GitHub release
+(checksum-verified):
+
+```sh
+hoopilot update
+```
+
+npm installs report when a newer version is available and print the right command
+(`npm install -g @openhoo/hoopilot@latest`). Either way, Hoopilot checks GitHub at
+most once a day in the background and prints a one-line notice to stderr when an
+update exists. Disable the check with `--no-update-check`, or by setting
+`HOOPILOT_NO_UPDATE_CHECK` / `NO_UPDATE_NOTIFIER`; it is also skipped in CI and
+when output is not a terminal.
+
+## Run
+
+```sh
+npx @openhoo/hoopilot
+```
+
+By default Hoopilot listens on `127.0.0.1:4141`, uses `COPILOT_API_TOKEN` when provided, otherwise reads a GitHub CLI OAuth token from `COPILOT_GITHUB_TOKEN` or `gh auth token`, and uses that token with Copilot.
 
 For a local API key:
 
@@ -61,15 +121,11 @@ or:
 COPILOT_GITHUB_TOKEN=$(gh auth token) npx @openhoo/hoopilot
 ```
 
-You can also [create a fine-grained personal access token](https://github.com/settings/personal-access-tokens/new) for the GitHub account that has Copilot access. GitHub's [personal access token documentation](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens) explains how fine-grained tokens and permissions work.
-
-```sh
-COPILOT_GITHUB_TOKEN=github_pat_... HOOPILOT_API_KEY=local-key npx @openhoo/hoopilot
-```
+Personal access tokens are not supported by GitHub Copilot's token exchange or chat endpoints. Hoopilot rejects classic and fine-grained PAT prefixes. Use `gh auth token` for the GitHub CLI OAuth path, or pass a short-lived Copilot bearer token with `COPILOT_API_TOKEN`.
 
 Supported credential environment variables:
 
-- `COPILOT_GITHUB_TOKEN`, `GITHUB_COPILOT_GITHUB_TOKEN`, `GITHUB_TOKEN`, or `GH_TOKEN`: GitHub OAuth token for an account with Copilot access.
+- `COPILOT_GITHUB_TOKEN` or `GITHUB_COPILOT_GITHUB_TOKEN`: GitHub CLI OAuth token for an account with Copilot access. Personal access tokens are rejected.
 - `COPILOT_API_TOKEN`, `GITHUB_COPILOT_API_TOKEN`, or `GITHUB_COPILOT_TOKEN`: short-lived Copilot API bearer token.
 - `COPILOT_API_BASE_URL`: upstream Copilot API base URL override.
 - `COPILOT_TOKEN_EXCHANGE_URL`: GitHub token exchange endpoint override.
@@ -78,12 +134,10 @@ Auth modes:
 
 ```sh
 npx @openhoo/hoopilot --auth-mode auto
-npx @openhoo/hoopilot --auth-mode github-token
-npx @openhoo/hoopilot --auth-mode direct-github-token
 npx @openhoo/hoopilot --auth-mode copilot-token
 ```
 
-`auto` first tries the GitHub Copilot token exchange endpoint, then falls back to direct GitHub-token mode against the individual Copilot API base URL. Use `github-token` when you want exchange failures to fail fast.
+`auto` uses a direct Copilot token when one is configured, otherwise it uses GitHub's Copilot token exchange endpoint and falls back to the GitHub CLI OAuth token when the exchange endpoint is unavailable.
 
 ## CLI
 
@@ -97,8 +151,8 @@ Options:
 -p, --port <port>                 Port to listen on. Default: 4141
     --host <host>                 Host to listen on. Default: 127.0.0.1
     --api-key <key>               Require clients to send Authorization: Bearer <key>
-    --auth-mode <mode>            auto, github-token, direct-github-token, copilot-token
-    --github-token <token>        GitHub OAuth token for a Copilot account
+    --auth-mode <mode>            auto, copilot-token
+    --github-token <token>        GitHub CLI OAuth token for a Copilot account. PATs are rejected.
     --github-token-command <cmd>  Command used to read a GitHub token. Default: gh auth token
     --copilot-token <token>       Short-lived Copilot API bearer token
     --copilot-api-base-url <url>  Copilot API base URL override
@@ -135,7 +189,7 @@ bun run biome:fix
 
 ## Release
 
-Commits merged to `main` are evaluated by hooversion after CI passes. When a release is produced, the release workflow creates the release commit, tag, and GitHub release automatically, then publishes the package through npm trusted publishing.
+Commits merged to `main` are evaluated by hooversion after CI passes. When a release is produced, the release workflow creates the release commit, tag, and GitHub release automatically, publishes the package through npm trusted publishing, then cross-compiles standalone binaries for every supported platform (`scripts/build-binaries.sh`) and attaches them — plus a `SHA256SUMS` manifest — to the GitHub release. Build all binaries locally with `bun run build:binaries`.
 
 Configure npm trusted publishing for `@openhoo/hoopilot` on npmjs.com before relying on automatic publication. The workflow uses GitHub Actions OIDC with `npm publish --access public --provenance`.