swiftbar-github 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 jryom
+
+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

@@ -1,3 +1,19 @@
-# Temporary Holding Version
+# SwiftBar GitHub
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A macOS menu bar plugin for unread GitHub notifications and pending review requests. Refreshes every three minutes and sends desktop alerts for new activity. Hidden when there is nothing pending; the first run is silent.
+
+## Setup
+
+Requires macOS, SwiftBar, and Node.js 24.15+ (24.x). `node` and `npx` must be on SwiftBar's `PATH`. To reuse your GitHub CLI login, `gh` must be there too:
+
+```sh
+brew install --cask swiftbar
+brew install gh
+gh auth login --hostname github.com
+```
+
+Download [swiftbar-github.3m.sh](https://cdn.jsdelivr.net/npm/swiftbar-github@latest/swiftbar-github.3m.sh) into your SwiftBar plugin folder.
+
+Run `chmod +x swiftbar-github.3m.sh`. Updates resolve through `@latest` on each refresh; downloaded versions are cached. For authentication without `gh`, set `GH_TOKEN` or `GITHUB_TOKEN` in SwiftBar's environment.
+
+Allow notifications for the bundled terminal-notifier in macOS System Settings. Click entries to open them on GitHub.

package/assets/github.svg

@@ -0,0 +1,3 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24">
+  <path d="M12 .5C5.65.5.5 5.65.5 12c0 5.08 3.29 9.39 7.86 10.91.58.11.79-.25.79-.56v-2.14c-3.2.7-3.88-1.36-3.88-1.36-.52-1.33-1.28-1.68-1.28-1.68-1.04-.71.08-.7.08-.7 1.15.08 1.75 1.18 1.75 1.18 1.02 1.75 2.69 1.24 3.34.95.1-.74.4-1.24.73-1.53-2.55-.29-5.23-1.28-5.23-5.69 0-1.25.45-2.28 1.18-3.08-.12-.29-.51-1.46.11-3.04 0 0 .96-.31 3.16 1.18a11 11 0 0 1 5.75 0c2.2-1.49 3.16-1.18 3.16-1.18.62 1.58.23 2.75.11 3.04.73.8 1.18 1.83 1.18 3.08 0 4.42-2.69 5.4-5.25 5.68.41.36.78 1.06.78 2.14v3.17c0 .31.21.67.79.56A11.5 11.5 0 0 0 23.5 12C23.5 5.65 18.35.5 12 .5z"/>
+</svg>

package/bin/cli.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import "../dist/swiftbar-github.js";

package/dist/swiftbar-github.js

@@ -0,0 +1,233 @@
+import { execFile } from "node:child_process";
+import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { basename, join } from "node:path";
+import { promisify } from "node:util";
+import { Octokit } from "@octokit/rest";
+import nodeNotifier from "node-notifier";
+const exec = promisify(execFile);
+const notifier = new nodeNotifier.NotificationCenter({ withFallback: false });
+const inbox = "https://github.com/notifications";
+const launcher = process.env.SWIFTBAR_PLUGIN_PATH;
+const cache = process.env.SWIFTBAR_PLUGIN_CACHE_PATH ||
+    join(homedir(), ".cache/swiftbar", basename(launcher || "swiftbar-github.3m.sh"));
+const icon = (await readFile(new URL("../assets/github.svg", import.meta.url))).toString("base64");
+function text(value) {
+    if (typeof value !== "string")
+        throw new Error("GitHub returned invalid notification data.");
+    return value.replace(/[|\r\n\t]/g, " ");
+}
+async function token() {
+    const value = process.env.GH_TOKEN || process.env.GITHUB_TOKEN;
+    if (value)
+        return value;
+    try {
+        const { stdout } = await exec("gh", ["auth", "token", "--hostname", "github.com"], { timeout: 10000 });
+        if (stdout.trim())
+            return stdout.trim();
+    }
+    catch (error) {
+        // Child process errors can contain the token, so never surface them.
+        if (error instanceof Error && "code" in error && error.code === "ENOENT")
+            throw new Error("GitHub CLI (gh) is not installed.");
+    }
+    throw new Error("Sign in with gh auth login --hostname github.com.");
+}
+function webURL(notification) {
+    const { subject, repository } = notification;
+    if (subject.type === "Release")
+        return `${repository.html_url}/releases`;
+    if (!subject.url)
+        return inbox;
+    if (!["PullRequest", "Issue", "Discussion", "Commit"].includes(subject.type))
+        return inbox;
+    const url = new URL(subject.url);
+    if (url.origin !== "https://api.github.com" ||
+        !url.pathname.startsWith("/repos/"))
+        return inbox;
+    return `https://github.com/${url.pathname.slice("/repos/".length).replace("/pulls/", "/pull/").replace("/commits/", "/commit/")}`;
+}
+async function state(file) {
+    try {
+        return new Set((await readFile(file, "utf8")).split("\n"));
+    }
+    catch (error) {
+        if (error instanceof Error && "code" in error && error.code === "ENOENT")
+            return null;
+        throw error;
+    }
+}
+async function save(file, values) {
+    const temporary = `${file}.${process.pid}`;
+    try {
+        await writeFile(temporary, values.length ? `${values.join("\n")}\n` : "", {
+            mode: 0o600,
+        });
+        await rename(temporary, file);
+    }
+    finally {
+        await rm(temporary, { force: true });
+    }
+}
+function notify(item) {
+    return new Promise((resolve) => {
+        const notification = {
+            title: item.alertTitle,
+            subtitle: item.repository,
+            message: item.title,
+            open: item.url,
+            sound: "default",
+            group: item.group,
+            timeout: false,
+        };
+        notifier.notify(notification, (error) => resolve(!error));
+    });
+}
+function action(label, argument) {
+    if (!launcher)
+        return `${label} | href=${inbox}`;
+    return `${label} | bash="${launcher.replaceAll('"', '\\"')}" param1=${argument} terminal=false`;
+}
+async function fetchActivity(argument) {
+    const github = new Octokit({
+        auth: await token(),
+        userAgent: "swiftbar-github",
+        request: {
+            redirect: "error",
+            fetch: (url, options) => fetch(url, {
+                ...options,
+                signal: options?.signal
+                    ? AbortSignal.any([options.signal, AbortSignal.timeout(20000)])
+                    : AbortSignal.timeout(20000),
+            }),
+        },
+        log: { debug() { }, info() { }, warn() { }, error() { } },
+    });
+    const { data: user } = await github.rest.users.getAuthenticated();
+    const requested = await github.paginate(github.rest.search.issuesAndPullRequests, {
+        q: `is:pr is:open archived:false review-requested:${user.login}`,
+        per_page: 100,
+    }, (response) => {
+        if (response.data.incomplete_results)
+            throw new Error("GitHub returned incomplete review search results.");
+        if (response.data.total_count > 1000)
+            throw new Error("More than 1,000 review requests matched. GitHub search cannot return all of them.");
+        return response.data;
+    });
+    const reviews = requested.map((item) => {
+        const repository = new URL(item.repository_url).pathname.slice("/repos/".length);
+        const title = `#${item.number} ${text(item.title)}`;
+        return {
+            url: item.html_url,
+            repository,
+            title,
+            key: item.html_url,
+            group: `github-review-${item.html_url}`,
+            alertTitle: "Review requested",
+        };
+    });
+    if (argument === "open-reviews")
+        return { reviews, notifications: [] };
+    const reviewURLs = new Set(reviews.map((item) => item.url));
+    const unread = await github.paginate(github.rest.activity.listNotificationsForAuthenticatedUser, {
+        all: false,
+        participating: false,
+        per_page: 50,
+    });
+    const notifications = unread
+        .map((item) => ({ ...item, url: webURL(item) }))
+        .filter((item) => item.reason !== "review_requested" || !reviewURLs.has(item.url))
+        .map((item) => {
+        const repository = text(item.repository.full_name);
+        const reason = text(item.reason).replaceAll("_", " ");
+        const title = text(item.subject.title);
+        return {
+            key: `${item.id}:${item.updated_at}`,
+            repository,
+            title,
+            url: item.url,
+            group: `github-notification-${item.id}`,
+            alertTitle: `GitHub: ${reason}`,
+            reason,
+        };
+    });
+    return { reviews, notifications };
+}
+function renderMenu(reviews, notifications) {
+    const total = reviews.length + notifications.length;
+    if (!total)
+        return "";
+    const menu = [
+        `${total} | templateImage=${icon}`,
+        "---",
+        `Review requests (${reviews.length}) | color=gray`,
+    ];
+    if (reviews.length) {
+        for (const item of reviews)
+            menu.push(`${item.repository} ${item.title} | href=${item.url}`);
+        menu.push(action("Open all review requests", "open-reviews"));
+    }
+    else
+        menu.push("No reviews requested | color=gray");
+    menu.push("---", `Notifications (${notifications.length}) | color=gray`);
+    if (notifications.length) {
+        for (const item of notifications)
+            menu.push(`${item.repository} [${item.reason}]: ${item.title} | href=${item.url}`);
+        menu.push(action("Open all notifications", "open-notifications"));
+    }
+    else
+        menu.push("No unread notifications | color=gray");
+    return menu.join("\n");
+}
+async function deliverAlerts(file, items) {
+    await mkdir(cache, { recursive: true });
+    const path = join(cache, file);
+    const seen = await state(path);
+    const current = [];
+    for (const item of items) {
+        if (!seen || seen.has(item.key) || (await notify(item)))
+            current.push(item.key);
+    }
+    await save(path, current);
+}
+async function main() {
+    const argument = process.argv[2];
+    if (argument && !["open-reviews", "open-notifications"].includes(argument))
+        throw new Error("Usage: swiftbar-github");
+    const { reviews, notifications } = await fetchActivity(argument);
+    if (argument) {
+        const items = argument === "open-reviews" ? reviews : notifications;
+        for (const item of items)
+            await exec("/usr/bin/open", ["-g", item.url]);
+        return;
+    }
+    const menu = renderMenu(reviews, notifications);
+    await deliverAlerts("requested-prs", reviews);
+    await deliverAlerts("inbox-notifications", notifications);
+    if (menu)
+        console.log(menu);
+}
+try {
+    await main();
+}
+catch (error) {
+    const status = error instanceof Error &&
+        "status" in error &&
+        typeof error.status === "number"
+        ? error.status
+        : null;
+    const message = status === 401
+        ? "GitHub authentication expired. Sign in again with gh auth login."
+        : status
+            ? `GitHub request failed (HTTP ${status}). Check token permissions and rate limits.`
+            : error instanceof Error
+                ? error.message
+                : "Could not retrieve GitHub notifications.";
+    if (process.argv[2]) {
+        console.error(message);
+        process.exitCode = 1;
+    }
+    else {
+        console.log(`? | color=red templateImage=${icon} href=${inbox}\n---\n${text(message)}`);
+    }
+}

package/package.json

@@ -1,6 +1,33 @@
 {
-  "name": "swiftbar-github",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+	"name": "swiftbar-github",
+	"version": "1.0.0",
+	"description": "GitHub notifications and review requests in the macOS menu bar",
+	"license": "MIT",
+	"repository": "github:jryom/swiftbar-github",
+	"type": "module",
+	"bin": "bin/cli.js",
+	"engines": {
+		"node": "^22.22.2 || ^24.15.0 || >=26.0.0"
+	},
+	"files": [
+		"bin",
+		"dist",
+		"assets",
+		"swiftbar-github.3m.sh"
+	],
+	"scripts": {
+		"build": "tsc",
+		"format": "biome format --write .",
+		"prepack": "tsc"
+	},
+	"dependencies": {
+		"@octokit/rest": "^22.0.1",
+		"node-notifier": "^11.0.0"
+	},
+	"devDependencies": {
+		"@biomejs/biome": "^2.5.15",
+		"@types/node": "^26.6.5",
+		"@types/node-notifier": "^8.0.5",
+		"typescript": "^7.0.2"
+	}
+}

package/swiftbar-github.3m.sh

@@ -0,0 +1,10 @@
+#!/bin/bash
+
+if output=$(npx --yes swiftbar-github@latest "$@" 2>/dev/null); then
+  [[ -z "$output" ]] || printf '%s\n' "$output"
+elif [[ $# -eq 0 ]]; then
+  printf '%s\n' 'GitHub unavailable | color=red' '---' 'Could not start the plugin.'
+else
+  echo 'Could not start the plugin.' >&2
+  exit 1
+fi