@kazoottt/github-repo-cleaner 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 KazooTTT
+
+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,113 @@
+# github-repo-cleaner
+
+Local terminal UI for cleaning GitHub repositories.
+
+The tool reuses GitHub CLI authentication, loads repositories for the active GitHub user, makes forks easy to identify, and supports archive/delete workflows with a page-level second confirmation.
+
+## Install
+
+```bash
+npm install -g @kazoottt/github-repo-cleaner
+```
+
+Run either command:
+
+```bash
+repo-cleaner
+github-repo-cleaner
+```
+
+## Authentication
+
+This tool expects `gh` to own credentials:
+
+```bash
+gh auth login
+gh auth refresh -h github.com -s delete_repo
+```
+
+The app reads the active token from `gh auth token` and does not store PATs or GitHub tokens.
+
+## Usage
+
+```bash
+repo-cleaner
+repo-cleaner --owner KazooTTT
+```
+
+Keys:
+
+```text
+up/down  move
+space    select repository
+f        toggle forks-only
+s        toggle sort oldest/newest
+/        search
+a        archive mode
+d        delete mode
+enter    review selected repositories
+esc      cancel review
+q        quit
+```
+
+## Development
+
+```bash
+npm install
+npm run dev
+npm test
+npm run typecheck
+npm run build
+```
+
+## Release
+
+Releases are created locally with `bumpp` and published by GitHub Actions when a `v*` tag is pushed.
+
+```bash
+npm run release
+```
+
+The release script runs tests, typecheck, and build before `bumpp` creates the version commit and tag.
+
+## npm trusted publishing setup
+
+This project is configured for npm trusted publishing with provenance. No `NPM_TOKEN` secret is required.
+
+Expected identities:
+
+```text
+GitHub owner: KazooTTT
+GitHub repository: github-repo-cleaner
+npm package: @kazoottt/github-repo-cleaner
+Workflow filename: publish.yml
+```
+
+Setup steps:
+
+1. Push this repository to GitHub as `KazooTTT/github-repo-cleaner`.
+2. Sign in to npm as the owner of the `@kazoottt` scope.
+3. Open the npm package settings for `@kazoottt/github-repo-cleaner`.
+4. Add a trusted publisher with:
+   - Owner: `KazooTTT`
+   - Repository: `github-repo-cleaner`
+   - Workflow filename: `publish.yml`
+   - Environment name: leave empty unless the workflow is changed to use one
+5. For the first publish only, run `npm publish --access public` locally to create the package.
+6. Add the trusted publisher in the package settings.
+7. For later releases, run `npm run release` locally.
+8. Confirm the pushed tag triggers the `Publish` workflow in GitHub Actions.
+
+After trusted publishing is configured, the publish workflow runs:
+
+```bash
+npm ci
+npm test
+npm run typecheck
+npm run build
+npm publish --provenance --access public
+```
+
+## Issue Tracker
+
+Local implementation issues live under `.scratch/issues/`.

package/dist/auth.js

@@ -0,0 +1,35 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+const execFileAsync = promisify(execFile);
+export class AuthError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+    }
+}
+export async function getGhToken(runCommand = execFileAsync) {
+    try {
+        await runCommand("gh", ["auth", "status", "--hostname", "github.com"]);
+    }
+    catch (error) {
+        const nodeError = error;
+        if (nodeError.code === "ENOENT") {
+            throw new AuthError("missing-gh", "GitHub CLI is not installed. Install gh, then run gh auth login.");
+        }
+        throw new AuthError("not-authenticated", "GitHub CLI is not authenticated. Run gh auth login.");
+    }
+    try {
+        const { stdout } = await runCommand("gh", ["auth", "token", "--hostname", "github.com"]);
+        const token = stdout.trim();
+        if (!token) {
+            throw new AuthError("token-unavailable", "GitHub CLI did not return a token.");
+        }
+        return token;
+    }
+    catch (error) {
+        if (error instanceof AuthError)
+            throw error;
+        throw new AuthError("token-unavailable", "Unable to read a GitHub token from gh. Try gh auth refresh -h github.com -s delete_repo.");
+    }
+}

package/dist/cli.js

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+import { jsx as _jsx } from "react/jsx-runtime";
+import { render } from "ink";
+import { getGhToken, AuthError } from "./auth.js";
+import { OctokitGitHubApi } from "./github.js";
+import { App } from "./ui.js";
+function parseOwner(argv) {
+    const ownerIndex = argv.indexOf("--owner");
+    if (ownerIndex === -1)
+        return undefined;
+    return argv[ownerIndex + 1];
+}
+try {
+    const token = await getGhToken();
+    const api = new OctokitGitHubApi(token);
+    render(_jsx(App, { api: api, owner: parseOwner(process.argv.slice(2)) }));
+}
+catch (error) {
+    if (error instanceof AuthError) {
+        console.error(error.message);
+        process.exitCode = 1;
+    }
+    else {
+        throw error;
+    }
+}

package/dist/domain.js

@@ -0,0 +1,67 @@
+export function sortByPushedAt(repositories, direction = "oldest") {
+    return [...repositories].sort((a, b) => {
+        const aTime = a.pushedAt ? Date.parse(a.pushedAt) : 0;
+        const bTime = b.pushedAt ? Date.parse(b.pushedAt) : 0;
+        return direction === "oldest" ? aTime - bTime : bTime - aTime;
+    });
+}
+export function formatPushedAt(value) {
+    if (!value)
+        return "never";
+    const date = new Date(value);
+    if (Number.isNaN(date.getTime()))
+        return value;
+    const formatter = new Intl.DateTimeFormat("sv-SE", {
+        year: "numeric",
+        month: "2-digit",
+        day: "2-digit",
+        hour: "2-digit",
+        minute: "2-digit",
+        hour12: false
+    });
+    return formatter.format(date);
+}
+export function filterRepositories(repositories, options) {
+    const normalizedQuery = options.query.trim().toLowerCase();
+    return repositories.filter((repository) => {
+        if (options.forksOnly && !repository.fork)
+            return false;
+        if (!normalizedQuery)
+            return true;
+        return repository.fullName.toLowerCase().includes(normalizedQuery);
+    });
+}
+export function baseRiskFlags(repositories) {
+    return repositories.flatMap((repository) => {
+        const flags = [];
+        if (repository.private) {
+            flags.push({
+                kind: "private",
+                repoFullName: repository.fullName,
+                message: `${repository.fullName} is private`
+            });
+        }
+        if (!repository.fork) {
+            flags.push({
+                kind: "non-fork",
+                repoFullName: repository.fullName,
+                message: `${repository.fullName} is not a fork`
+            });
+        }
+        if (repository.archived) {
+            flags.push({
+                kind: "archived",
+                repoFullName: repository.fullName,
+                message: `${repository.fullName} is already archived`
+            });
+        }
+        if (repository.fork && repository.upstreamMissing) {
+            flags.push({
+                kind: "upstream-missing",
+                repoFullName: repository.fullName,
+                message: `${repository.fullName} has missing upstream metadata`
+            });
+        }
+        return flags;
+    });
+}

package/dist/github.js

@@ -0,0 +1,130 @@
+import { Octokit } from "@octokit/rest";
+export class OctokitGitHubApi {
+    octokit;
+    constructor(token) {
+        this.octokit = new Octokit({ auth: token, userAgent: "github-repo-cleaner" });
+    }
+    async getDefaultOwner() {
+        const { data } = await this.octokit.rest.users.getAuthenticated();
+        return data.login;
+    }
+    async listRepositories(owner) {
+        const defaultOwner = await this.getDefaultOwner();
+        const activeOwner = owner ?? defaultOwner;
+        const repositories = !owner || activeOwner.toLowerCase() === defaultOwner.toLowerCase()
+            ? await this.octokit.paginate(this.octokit.rest.repos.listForAuthenticatedUser, {
+                affiliation: "owner",
+                per_page: 100,
+                sort: "pushed",
+                direction: "desc"
+            })
+            : await this.listForExplicitOwner(activeOwner);
+        return {
+            owner: activeOwner,
+            repositories: repositories
+                .filter((repository) => repository.owner.login.toLowerCase() === activeOwner.toLowerCase())
+                .map(toRepositorySummary)
+        };
+    }
+    async countOpenPullRequests(repository) {
+        const { data } = await this.octokit.rest.search.issuesAndPullRequests({
+            q: `repo:${repository.fullName} is:pr is:open`,
+            per_page: 1
+        });
+        return data.total_count;
+    }
+    async archiveRepository(repository) {
+        return this.execute("archive", repository, async () => {
+            const response = await this.octokit.rest.repos.update({
+                owner: repository.owner,
+                repo: repository.name,
+                archived: true
+            });
+            return response.status;
+        });
+    }
+    async deleteRepository(repository) {
+        return this.execute("delete", repository, async () => {
+            const response = await this.octokit.rest.repos.delete({
+                owner: repository.owner,
+                repo: repository.name
+            });
+            return response.status;
+        });
+    }
+    async listForExplicitOwner(owner) {
+        const { data: user } = await this.octokit.rest.users.getByUsername({ username: owner });
+        if (user.type === "Organization") {
+            return this.octokit.paginate(this.octokit.rest.repos.listForOrg, {
+                org: owner,
+                type: "all",
+                per_page: 100,
+                sort: "pushed",
+                direction: "desc"
+            });
+        }
+        return this.octokit.paginate(this.octokit.rest.repos.listForUser, {
+            username: owner,
+            type: "owner",
+            per_page: 100,
+            sort: "pushed",
+            direction: "desc"
+        });
+    }
+    async execute(action, repository, call) {
+        try {
+            const httpStatus = await call();
+            return { fullName: repository.fullName, action, status: "success", httpStatus };
+        }
+        catch (error) {
+            const apiError = error;
+            return {
+                fullName: repository.fullName,
+                action,
+                status: "failed",
+                httpStatus: apiError.status,
+                message: formatGitHubApiErrorMessage(apiError)
+            };
+        }
+    }
+}
+function toRepositorySummary(repository) {
+    const parent = repository.parent;
+    return {
+        id: repository.id,
+        name: repository.name,
+        fullName: repository.full_name,
+        owner: repository.owner.login,
+        private: repository.private ?? false,
+        fork: repository.fork ?? false,
+        archived: repository.archived ?? false,
+        pushedAt: repository.pushed_at ?? null,
+        upstreamFullName: parent?.full_name ?? undefined,
+        upstreamMissing: (repository.fork ?? false) && !parent?.full_name
+    };
+}
+export async function computeRiskFlags(api, repositories, mode) {
+    const { baseRiskFlags } = await import("./domain.js");
+    const flags = baseRiskFlags(repositories);
+    if (mode !== "delete")
+        return flags;
+    const openPrCounts = await Promise.all(repositories
+        .filter((repository) => repository.fork)
+        .map(async (repository) => ({ repository, count: await api.countOpenPullRequests(repository) })));
+    for (const { repository, count } of openPrCounts) {
+        if (count > 0) {
+            flags.push({
+                kind: "open-prs",
+                repoFullName: repository.fullName,
+                message: `${repository.fullName} has ${count} open pull request${count === 1 ? "" : "s"}`
+            });
+        }
+    }
+    return flags;
+}
+export function formatGitHubApiErrorMessage(error) {
+    const permissionHint = error.status === 403
+        ? " Try gh auth refresh -h github.com -s delete_repo if this is a permission issue."
+        : "";
+    return `${error.message ?? "Unknown GitHub API error"}${permissionHint}`;
+}

package/dist/session-log.js

@@ -0,0 +1,34 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+export function defaultSessionLogDirectory() {
+    return join(homedir(), ".local", "state", "github-repo-cleaner", "sessions");
+}
+export async function writeSessionLog(options) {
+    const directory = options.directory ?? defaultSessionLogDirectory();
+    await mkdir(directory, { recursive: true });
+    const resultByName = new Map(options.results.map((result) => [result.fullName, result]));
+    const log = {
+        owner: options.owner,
+        mode: options.mode,
+        startedAt: options.startedAt.toISOString(),
+        completedAt: options.completedAt.toISOString(),
+        items: options.repositories.map((repository) => {
+            const result = resultByName.get(repository.fullName);
+            return {
+                fullName: repository.fullName,
+                fork: repository.fork,
+                private: repository.private,
+                archived: repository.archived,
+                action: options.mode,
+                status: result?.status ?? "failed",
+                httpStatus: result?.httpStatus,
+                message: result?.message
+            };
+        })
+    };
+    const fileName = `${options.startedAt.toISOString().replace(/[:.]/g, "-")}.json`;
+    const path = join(directory, fileName);
+    await writeFile(path, `${JSON.stringify(log, null, 2)}\n`, "utf8");
+    return path;
+}

package/dist/ui.js

@@ -0,0 +1,170 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useMemo, useRef, useState } from "react";
+import { Box, Text, useApp, useInput } from "ink";
+import { computeRiskFlags } from "./github.js";
+import { filterRepositories, formatPushedAt, sortByPushedAt } from "./domain.js";
+import { writeSessionLog } from "./session-log.js";
+export function App({ api, owner: requestedOwner, writeLog = writeSessionLog }) {
+    const { exit } = useApp();
+    const [view, setView] = useState("loading");
+    const [owner, setOwner] = useState(requestedOwner ?? "");
+    const [repositories, setRepositories] = useState([]);
+    const [cursor, setCursor] = useState(0);
+    const [selectedIds, setSelectedIds] = useState(new Set());
+    const [forksOnly, setForksOnly] = useState(false);
+    const [sortDirection, setSortDirection] = useState("oldest");
+    const [query, setQuery] = useState("");
+    const [searching, setSearching] = useState(false);
+    const [mode, setMode] = useState("archive");
+    const [riskFlags, setRiskFlags] = useState([]);
+    const [riskFlagsLoading, setRiskFlagsLoading] = useState(false);
+    const [results, setResults] = useState([]);
+    const [logPath, setLogPath] = useState();
+    const [error, setError] = useState();
+    useEffect(() => {
+        let active = true;
+        api
+            .listRepositories(requestedOwner)
+            .then((response) => {
+            if (!active)
+                return;
+            setOwner(response.owner);
+            setRepositories(response.repositories);
+            setView("list");
+        })
+            .catch((loadError) => {
+            if (!active)
+                return;
+            const message = loadError instanceof Error ? loadError.message : "Unable to load repositories";
+            setError(message);
+            setView("error");
+        });
+        return () => {
+            active = false;
+        };
+    }, [api, requestedOwner]);
+    const visibleRepositories = useMemo(() => filterRepositories(sortByPushedAt(repositories, sortDirection), { query, forksOnly }), [repositories, sortDirection, query, forksOnly]);
+    const selectedRepositories = useMemo(() => repositories.filter((repository) => selectedIds.has(repository.id)), [repositories, selectedIds]);
+    const selectedRepositoriesRef = useRef([]);
+    const viewRef = useRef(view);
+    const modeRef = useRef(mode);
+    const ownerRef = useRef(owner);
+    const riskFlagsLoadingRef = useRef(riskFlagsLoading);
+    useEffect(() => {
+        selectedRepositoriesRef.current = selectedRepositories;
+        viewRef.current = view;
+        modeRef.current = mode;
+        ownerRef.current = owner;
+        riskFlagsLoadingRef.current = riskFlagsLoading;
+    }, [selectedRepositories, view, mode, owner, riskFlagsLoading]);
+    useInput((input, key) => {
+        if (input === "q") {
+            exit();
+            return;
+        }
+        const isReturn = key.return || input === "\r" || input === "\n";
+        if (viewRef.current === "list") {
+            if (searching) {
+                if (isReturn) {
+                    setSearching(false);
+                }
+                else if (key.backspace || key.delete) {
+                    setQuery((current) => current.slice(0, -1));
+                }
+                else if (input && !key.ctrl && !key.meta) {
+                    setQuery((current) => `${current}${input}`);
+                }
+                return;
+            }
+            if (key.upArrow)
+                setCursor((current) => Math.max(0, current - 1));
+            if (key.downArrow)
+                setCursor((current) => Math.min(visibleRepositories.length - 1, current + 1));
+            if (input === "f")
+                setForksOnly((current) => !current);
+            if (input === "s")
+                setSortDirection((current) => current === "oldest" ? "newest" : "oldest");
+            if (input === "/")
+                setSearching(true);
+            if (input === "a")
+                setMode("archive");
+            if (input === "d")
+                setMode("delete");
+            if (input === " " && visibleRepositories[cursor]) {
+                const repository = visibleRepositories[cursor];
+                setSelectedIds((current) => {
+                    const next = new Set(current);
+                    if (next.has(repository.id))
+                        next.delete(repository.id);
+                    else
+                        next.add(repository.id);
+                    return next;
+                });
+            }
+            if (isReturn && selectedRepositoriesRef.current.length > 0) {
+                setRiskFlags([]);
+                setRiskFlagsLoading(true);
+                setView("review");
+                void computeRiskFlags(api, selectedRepositoriesRef.current, modeRef.current).then((flags) => {
+                    setRiskFlags(flags);
+                    setRiskFlagsLoading(false);
+                });
+            }
+            return;
+        }
+        if (viewRef.current === "review") {
+            if (key.escape) {
+                setView("list");
+                return;
+            }
+            if (isReturn && !riskFlagsLoadingRef.current) {
+                void execute();
+            }
+        }
+    });
+    async function execute() {
+        const startedAt = new Date();
+        setView("executing");
+        const operationResults = [];
+        const repositoriesToExecute = selectedRepositoriesRef.current;
+        const modeToExecute = modeRef.current;
+        for (const repository of repositoriesToExecute) {
+            const result = modeToExecute === "archive" ? await api.archiveRepository(repository) : await api.deleteRepository(repository);
+            operationResults.push(result);
+            setResults([...operationResults]);
+        }
+        const completedAt = new Date();
+        const path = await writeLog({
+            owner: ownerRef.current,
+            mode: modeToExecute,
+            startedAt,
+            completedAt,
+            repositories: repositoriesToExecute,
+            results: operationResults
+        });
+        setLogPath(path);
+        setResults(operationResults);
+        setView("result");
+    }
+    if (view === "loading")
+        return _jsx(Text, { children: "Loading repositories..." });
+    if (view === "error")
+        return _jsx(Text, { color: "red", children: error });
+    if (view === "review")
+        return _jsx(ReviewView, { mode: mode, repositories: selectedRepositories, riskFlags: riskFlags, loading: riskFlagsLoading });
+    if (view === "executing")
+        return _jsxs(Text, { children: ["Executing ", mode, " for ", selectedRepositories.length, " repositories..."] });
+    if (view === "result")
+        return _jsx(ResultView, { results: results, logPath: logPath });
+    return (_jsxs(Box, { flexDirection: "column", children: [_jsxs(Text, { children: ["github-repo-cleaner owner:", owner, " mode:", mode, " sort:", sortDirection, " selected:", selectedIds.size] }), _jsxs(Text, { children: ["[up/down] move  [space] select  [f] forks only:", forksOnly ? "on" : "off", "  [s] sort  [/] search  [a] archive  [d] delete  [enter] review  [q] quit"] }), _jsxs(Text, { children: ["search:", searching ? `${query}_` : query || "-"] }), visibleRepositories.slice(Math.max(0, cursor - 5), cursor + 15).map((repository) => {
+                const active = visibleRepositories[cursor]?.id === repository.id;
+                const selected = selectedIds.has(repository.id);
+                return (_jsxs(Text, { color: active ? "cyan" : undefined, children: [active ? ">" : " ", " ", selected ? "[x]" : "[ ]", " ", repository.fork ? "fork" : "own ", " ", repository.fullName, " pushed:", formatPushedAt(repository.pushedAt), " ", repository.fork ? `upstream:${repository.upstreamFullName ?? "missing"}` : ""] }, repository.id));
+            }), visibleRepositories.length === 0 ? _jsx(Text, { children: "No repositories match the current filters." }) : null] }));
+}
+function ReviewView({ mode, repositories, riskFlags, loading }) {
+    return (_jsxs(Box, { flexDirection: "column", children: [_jsxs(Text, { children: [mode.toUpperCase(), " ", repositories.length, " repositories"] }), repositories.slice(0, 12).map((repository) => _jsxs(Text, { children: ["- ", repository.fullName] }, repository.id)), repositories.length > 12 ? _jsxs(Text, { children: ["... ", repositories.length - 12, " more"] }) : null, _jsx(Text, { children: "Risk flags:" }), loading ? _jsx(Text, { children: "Checking risks..." }) : riskFlags.length === 0 ? _jsx(Text, { children: "None" }) : riskFlags.map((flag) => _jsxs(Text, { color: "yellow", children: ["! ", flag.message] }, `${flag.kind}:${flag.repoFullName}`)), _jsx(Text, { children: loading ? "[enter] waiting for risk check   [esc] cancel" : "[enter] confirm   [esc] cancel" })] }));
+}
+function ResultView({ results, logPath }) {
+    return (_jsxs(Box, { flexDirection: "column", children: [_jsx(Text, { children: "Results" }), results.map((result) => (_jsxs(Text, { color: result.status === "success" ? "green" : "red", children: [result.status === "success" ? "ok" : "fail", " ", result.action, " ", result.fullName, " ", result.httpStatus ?? "", " ", result.message ?? ""] }, result.fullName))), logPath ? _jsxs(Text, { children: ["Log: ", logPath] }) : null] }));
+}

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@kazoottt/github-repo-cleaner",
+  "version": "0.1.0",
+  "description": "Local TUI for cleaning GitHub repositories with gh authentication.",
+  "type": "module",
+  "bin": {
+    "github-repo-cleaner": "dist/cli.js",
+    "repo-cleaner": "dist/cli.js"
+  },
+  "scripts": {
+    "dev": "tsx src/cli.tsx",
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepack": "npm run build",
+    "release": "npm test && npm run typecheck && npm run build && bumpp --commit \"chore(release): v%s\" --tag \"v%s\" --push"
+  },
+  "dependencies": {
+    "@octokit/rest": "latest",
+    "ink": "latest",
+    "react": "latest"
+  },
+  "devDependencies": {
+    "@types/node": "latest",
+    "@types/react": "latest",
+    "bumpp": "^11.1.0",
+    "ink-testing-library": "latest",
+    "tsx": "latest",
+    "typescript": "latest",
+    "vitest": "latest"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/KazooTTT/github-repo-cleaner.git"
+  },
+  "homepage": "https://github.com/KazooTTT/github-repo-cleaner#readme",
+  "bugs": {
+    "url": "https://github.com/KazooTTT/github-repo-cleaner/issues"
+  },
+  "license": "MIT"
+}