gh-unstar 2.0.0

package/.env.example

@@ -0,0 +1,3 @@
+# Example .env file
+GITHUB_TOKEN=
+GITHUB_USERNAME=

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Chris Thomas
+
+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,95 @@
+# gh-unstar
+
+# gh-unstar
+
+[![npm version](https://img.shields.io/npm/v/gh-unstar?style=flat-square&color=blue)](https://www.npmjs.com/package/gh-unstar)
+[![license](https://img.shields.io/npm/l/gh-unstar?style=flat-square&color=green)](https://www.npmjs.com/package/gh-unstar)
+
+CLI to remove all starred repositories from a GitHub account
+
+## Features
+
+- Unstars all repositories for the authenticated user
+- Confirmation safety check
+- Dry-run support
+- Test mode
+- Additional configurable options (see below)
+
+## Requirements
+
+- Node.js 18+
+- A GitHub Personal Access Token (classic)
+
+## Usage
+
+npx:
+
+```bash
+npx gh-unstar
+```
+
+or install globally:
+
+```bash
+npm install -g gh-unstar
+```
+
+## Usage
+
+```bash
+gh-unstar
+```
+
+## Options
+
+- `-u, --username <username>`: GitHub username to target.
+- `-t, --token <token>`: GitHub personal access token to authenticate API calls.
+- `-y, --yes`: Skip the confirmation prompt.
+- `--dry-run`: Fetch starred repositories and report the count without changing anything.
+- `--delay <ms>`: Delay in milliseconds between unstar requests (default 100).
+- `--max-retries <n>`: Maximum retries for failed API requests with exponential backoff (default 5).
+- `--per-page <n>`: Results per page when fetching starred repos (max 100, default 100).
+- `--test`: Run without API calls or credentials.
+- `--test-count <n>`: Number of fake starred repositories in test mode (default 25).
+- `--test-fail-every <n>`: Every Nth unstar fails in test mode (0 disables).
+
+## Auth
+
+Create a Personal Access Token (classic) with at least `public_repo` scope
+(or `repo` to include private stars).
+
+Environment variables:
+
+- `GITHUB_TOKEN`
+- `GITHUB_USERNAME` (optional, auto-detected if missing)
+
+Example `.env`:
+
+```
+GITHUB_TOKEN=your_token_here
+GITHUB_USERNAME=your_username
+```
+
+## Safety
+
+This tool will unstar all repositories for the account. It **requires** typing
+`YES` unless `--yes` is provided.
+
+## Dev
+
+Install dependencies:
+
+```bash
+npm install
+```
+
+Available scripts:
+
+- `npm run start`: run the CLI entrypoint locally
+- `npm run lint`: run Biome lint checks
+- `npm run format`: format files in-place using Biome
+- `npm run check`: run Biome formatting and safe lint fixes in one pass
+
+## License
+
+MIT

package/bin/gh-unstar.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+
+const run = require("../src/index");
+
+run();

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "gh-unstar",
+  "version": "2.0.0",
+  "description": "Interactive CLI to remove all GitHub stars from your account",
+  "bin": {
+    "gh-unstar": "bin/gh-unstar.js"
+  },
+  "type": "commonjs",
+  "files": [
+    "bin/",
+    "src/",
+    "README.md",
+    "LICENSE",
+    ".env.example"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "start": "node bin/gh-unstar.js",
+    "lint": "biome lint .",
+    "format": "biome format --write .",
+    "check": "biome check --write ."
+  },
+  "keywords": [
+    "github",
+    "stars",
+    "repositories",
+    "api",
+    "cli",
+    "unstar",
+    "automation"
+  ],
+  "license": "MIT",
+  "author": {
+    "name": "Chris Thomas",
+    "url": "https://github.com/chris-c-thomas"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/chris-c-thomas/gh-unstar.git"
+  },
+  "bugs": {
+    "url": "https://github.com/chris-c-thomas/gh-unstar/issues"
+  },
+  "homepage": "https://github.com/chris-c-thomas/gh-unstar",
+  "dependencies": {
+    "chalk": "^5.6.2",
+    "commander": "^12.1.0",
+    "dotenv": "^17.2.3",
+    "inquirer": "^9.2.23",
+    "ora": "^8.0.1"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.3.11"
+  }
+}

package/src/config.js

@@ -0,0 +1,15 @@
+const dotenv = require("dotenv");
+
+dotenv.config();
+
+function getEnvConfig() {
+  return {
+    username:
+      process.env.GITHUB_USERNAME || process.env.GH_USERNAME || process.env.GITHUB_USER || "",
+    token: process.env.GITHUB_TOKEN || process.env.GH_TOKEN || process.env.GITHUB_PAT || "",
+  };
+}
+
+module.exports = {
+  getEnvConfig,
+};

package/src/github.js

@@ -0,0 +1,81 @@
+const { fetchWithRetry } = require("./retry");
+
+const GITHUB_API_URL = "https://api.github.com";
+
+function buildHeaders(token) {
+  return {
+    Authorization: `token ${token}`,
+    Accept: "application/vnd.github.v3+json",
+  };
+}
+
+async function fetchAuthenticatedUser(token, { maxRetries } = {}) {
+  const response = await fetchWithRetry(
+    () =>
+      fetch(`${GITHUB_API_URL}/user`, {
+        headers: buildHeaders(token),
+      }),
+    { maxRetries },
+  );
+
+  return response.json();
+}
+
+async function fetchAllStarredRepos({ token, perPage = 100, maxRetries, onProgress } = {}) {
+  const allRepos = [];
+  let page = 1;
+
+  while (true) {
+    const url = `${GITHUB_API_URL}/user/starred?per_page=${perPage}&page=${page}`;
+
+    const response = await fetchWithRetry(
+      () =>
+        fetch(url, {
+          headers: buildHeaders(token),
+        }),
+      { maxRetries },
+    );
+
+    const data = await response.json();
+
+    if (!Array.isArray(data) || data.length === 0) {
+      break;
+    }
+
+    const fullNames = data.map((repo) => repo.full_name).filter(Boolean);
+    allRepos.push(...fullNames);
+
+    if (typeof onProgress === "function") {
+      onProgress(allRepos.length, page);
+    }
+
+    page += 1;
+  }
+
+  return allRepos;
+}
+
+async function unstarRepository(fullRepoName, { token, maxRetries } = {}) {
+  const url = `${GITHUB_API_URL}/user/starred/${fullRepoName}`;
+
+  try {
+    const response = await fetchWithRetry(
+      () =>
+        fetch(url, {
+          method: "DELETE",
+          headers: buildHeaders(token),
+        }),
+      { maxRetries },
+    );
+
+    return response.status === 204;
+  } catch (_error) {
+    return false;
+  }
+}
+
+module.exports = {
+  fetchAuthenticatedUser,
+  fetchAllStarredRepos,
+  unstarRepository,
+};

package/src/index.js

@@ -0,0 +1,272 @@
+const { program } = require("commander");
+const { getEnvConfig } = require("./config");
+const { fetchAuthenticatedUser, fetchAllStarredRepos, unstarRepository } = require("./github");
+const { createSpinner, sleep, formatNumber } = require("./ui");
+
+let inquirerInstance;
+async function getInquirer() {
+  if (inquirerInstance) {
+    return inquirerInstance;
+  }
+
+  const inquirerModule = await import("inquirer");
+  inquirerInstance = inquirerModule.default || inquirerModule;
+  return inquirerInstance;
+}
+
+let chalkInstance;
+async function getChalk() {
+  if (chalkInstance) {
+    return chalkInstance;
+  }
+
+  const chalkModule = await import("chalk");
+  chalkInstance = chalkModule.default || chalkModule;
+  return chalkInstance;
+}
+
+function parsePositiveInt(value, fallback) {
+  const parsed = Number.parseInt(value, 10);
+  if (Number.isFinite(parsed) && parsed >= 0) {
+    return parsed;
+  }
+
+  return fallback;
+}
+
+function buildTestRepos(count) {
+  return Array.from({ length: count }, (_, index) => {
+    const repoNumber = String(index + 1).padStart(3, "0");
+    return `test-owner/repo-${repoNumber}`;
+  });
+}
+
+program
+  .name("gh-unstar")
+  .description("Remove all GitHub stars from your account")
+  .option("-u, --username <username>", "GitHub username")
+  .option("-t, --token <token>", "GitHub personal access token (classic)")
+  .option("-y, --yes", "Skip confirmation safety prompt")
+  .option("--dry-run", "Fetch and display count only")
+  .option(
+    "--delay <ms>",
+    "Delay between unstar requests (milliseconds)",
+    (value) => parsePositiveInt(value, 100),
+    100,
+  )
+  .option(
+    "--max-retries <n>",
+    "Max retries for failed requests",
+    (value) => parsePositiveInt(value, 5),
+    5,
+  )
+  .option(
+    "--per-page <n>",
+    "Results per page (max 100)",
+    (value) => parsePositiveInt(value, 100),
+    100,
+  )
+  .option("--test", "Run in test mode (no GitHub API calls)")
+  .option(
+    "--test-count <n>",
+    "Number of fake starred repos in test mode",
+    (value) => parsePositiveInt(value, 25),
+    25,
+  )
+  .option(
+    "--test-fail-every <n>",
+    "In test mode, every Nth unstar fails (0 disables)",
+    (value) => parsePositiveInt(value, 0),
+    0,
+  );
+
+async function resolveToken(options, env) {
+  let token = options.token || env.token;
+
+  if (!token) {
+    const inquirer = await getInquirer();
+    const answers = await inquirer.prompt([
+      {
+        type: "password",
+        name: "token",
+        message: "GitHub Personal Access Token (classic)",
+        mask: "*",
+        validate: (value) => (value && value.trim().length > 0 ? true : "Token is required."),
+      },
+    ]);
+
+    token = answers.token;
+  }
+
+  return token;
+}
+
+async function resolveUsername(options, env, token) {
+  let username = options.username || env.username;
+
+  if (!username) {
+    try {
+      const user = await fetchAuthenticatedUser(token, {
+        maxRetries: options.maxRetries,
+      });
+      if (user?.login) {
+        username = user.login;
+      }
+    } catch (_error) {
+      username = "";
+    }
+  }
+
+  if (!username) {
+    const inquirer = await getInquirer();
+    const answers = await inquirer.prompt([
+      {
+        type: "input",
+        name: "username",
+        message: "GitHub username",
+        validate: (value) => (value && value.trim().length > 0 ? true : "Username is required."),
+      },
+    ]);
+
+    username = answers.username;
+  }
+
+  return username;
+}
+
+async function confirmDestructive(username) {
+  const inquirer = await getInquirer();
+  const answers = await inquirer.prompt([
+    {
+      type: "input",
+      name: "confirmation",
+      message: `!!! WARNING !!! This will unstar ALL repos for user ${username}. Type 'YES' to proceed:`,
+      validate: (value) => (value.trim() === "YES" ? true : "Type 'YES' to continue."),
+    },
+  ]);
+
+  return answers.confirmation.trim() === "YES";
+}
+
+async function run() {
+  program.parse(process.argv);
+  const options = program.opts();
+  const env = getEnvConfig();
+  const chalk = await getChalk();
+
+  console.log(chalk.cyan("---------------------------------------------------------"));
+  console.log(chalk.cyan("     GitHub Star Clean-up CLI                            "));
+  console.log(chalk.cyan("---------------------------------------------------------"));
+
+  const isTestMode = Boolean(options.test);
+  let token = "";
+  let username = "";
+
+  if (isTestMode) {
+    token = options.token || env.token || "test-token";
+    username = options.username || env.username || "test-user";
+    console.log(chalk.yellow("Test mode enabled. No GitHub API calls will be made."));
+  } else {
+    token = await resolveToken(options, env);
+    username = await resolveUsername(options, env, token);
+  }
+
+  console.log(`\nPreparing to unstar repositories for ${chalk.bold(username)}.`);
+  const fetchSpinner = (
+    await createSpinner(
+      isTestMode
+        ? "Fetching starred repositories (test mode)..."
+        : "Fetching starred repositories...",
+    )
+  ).start();
+  let starredRepos = [];
+
+  try {
+    if (isTestMode) {
+      starredRepos = buildTestRepos(options.testCount);
+      fetchSpinner.succeed(
+        `Fetched ${formatNumber(starredRepos.length)} repositories (test mode).`,
+      );
+    } else {
+      starredRepos = await fetchAllStarredRepos({
+        token,
+        perPage: Math.min(options.perPage, 100),
+        maxRetries: options.maxRetries,
+        onProgress: (count, page) => {
+          fetchSpinner.text = `Fetched ${formatNumber(count)} repositories (Page ${page})`;
+        },
+      });
+      fetchSpinner.succeed(`Fetched ${formatNumber(starredRepos.length)} repositories.`);
+    }
+  } catch (error) {
+    fetchSpinner.fail(`Failed to fetch starred repositories: ${error.message}`);
+    return;
+  }
+
+  if (starredRepos.length === 0) {
+    console.log(chalk.green("No starred repositories found. Clean slate achieved!"));
+    return;
+  }
+
+  console.log(chalk.yellow(`Found ${formatNumber(starredRepos.length)} starred repositories.`));
+
+  if (options.dryRun) {
+    console.log(chalk.gray("Dry run enabled. No changes were made."));
+    return;
+  }
+
+  if (!options.yes && !isTestMode) {
+    const confirmed = await confirmDestructive(username);
+    if (!confirmed) {
+      console.log(chalk.gray("Unstar process cancelled by user."));
+      return;
+    }
+  }
+  console.log(chalk.cyan("\n--- Starting Unstarring Process ---"));
+
+  const unstarSpinner = (await createSpinner("Unstarring repositories...")).start();
+
+  let unstarredCount = 0;
+  const failedRepos = [];
+
+  for (let i = 0; i < starredRepos.length; i += 1) {
+    const repo = starredRepos[i];
+    unstarSpinner.text = `(${i + 1}/${starredRepos.length}) Unstarring ${repo}`;
+
+    let success = false;
+
+    if (isTestMode) {
+      const failEvery = options.testFailEvery || 0;
+      success = failEvery > 0 ? (i + 1) % failEvery !== 0 : true;
+    } else {
+      success = await unstarRepository(repo, {
+        token,
+        maxRetries: options.maxRetries,
+      });
+    }
+
+    if (success) {
+      unstarredCount += 1;
+    } else {
+      failedRepos.push(repo);
+    }
+
+    await sleep(options.delay);
+  }
+
+  unstarSpinner.succeed("Unstarring complete.");
+
+  console.log(chalk.cyan("\n--- Process Complete ---"));
+  console.log(`Total repositories processed: ${starredRepos.length}`);
+  console.log(chalk.green(`Successfully unstarred: ${unstarredCount}`));
+
+  if (failedRepos.length > 0) {
+    console.log(chalk.red(`Failed to unstar: ${failedRepos.length}`));
+  }
+}
+
+module.exports = run;
+
+if (require.main === module) {
+  run();
+}

package/src/retry.js

@@ -0,0 +1,49 @@
+const DEFAULT_MAX_RETRIES = 5;
+
+async function fetchWithRetry(apiCall, { maxRetries = DEFAULT_MAX_RETRIES } = {}) {
+  let retries = 0;
+
+  while (true) {
+    try {
+      const response = await apiCall();
+
+      if (response.status === 403 && response.headers.get("x-ratelimit-remaining") === "0") {
+        const resetTime = Number.parseInt(response.headers.get("x-ratelimit-reset"), 10) * 1000;
+        const delay = resetTime - Date.now();
+        const waitMs = delay > 0 ? delay : 1000;
+        console.warn("\n\n!!! GitHub Rate Limit Hit !!!");
+        console.log(
+          `Waiting ${Math.ceil(waitMs / 1000)} seconds until reset (${new Date(
+            resetTime,
+          ).toLocaleTimeString()}).`,
+        );
+        await new Promise((resolve) => setTimeout(resolve, waitMs));
+        continue;
+      }
+
+      if (response.status >= 400 && response.status !== 204) {
+        const errorBody = await response.json().catch(() => ({
+          message: "No content",
+        }));
+        throw new Error(
+          `API returned status ${response.status}: ${errorBody.message || "Unknown error"}`,
+        );
+      }
+
+      return response;
+    } catch (error) {
+      if (retries < maxRetries) {
+        const delay = 2 ** retries * 1000;
+        await new Promise((resolve) => setTimeout(resolve, delay));
+        retries += 1;
+        continue;
+      }
+
+      throw new Error(`Failed after ${maxRetries} attempts. Last error: ${error.message}`);
+    }
+  }
+}
+
+module.exports = {
+  fetchWithRetry,
+};

package/src/ui.js

@@ -0,0 +1,34 @@
+let oraInstance;
+
+async function getOra() {
+  if (oraInstance) {
+    return oraInstance;
+  }
+
+  const oraModule = await import("ora");
+  oraInstance = oraModule.default || oraModule;
+  return oraInstance;
+}
+
+function sleep(ms) {
+  if (!Number.isFinite(ms) || ms <= 0) {
+    return Promise.resolve();
+  }
+
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function formatNumber(value) {
+  return new Intl.NumberFormat("en-US").format(value);
+}
+
+async function createSpinner(text) {
+  const ora = await getOra();
+  return ora({ text, color: "cyan" });
+}
+
+module.exports = {
+  createSpinner,
+  sleep,
+  formatNumber,
+};