@o4h8/oss-perks 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ozkan Hancioglu
+
+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,127 @@
+# oss-perks
+
+[![npm version](https://img.shields.io/npm/v/oss-perks.svg)](https://www.npmjs.com/package/oss-perks)
+[![CI](https://github.com/o4h8/oss-perks/actions/workflows/ci.yml/badge.svg)](https://github.com/o4h8/oss-perks/actions)
+[![license](https://img.shields.io/npm/l/oss-perks.svg)](./LICENSE)
+[![node](https://img.shields.io/node/v/oss-perks.svg)](https://nodejs.org)
+
+> **Am I eligible for open-source maintainer perks?** Check any GitHub user or package against the criteria for programs like [Claude for Open Source](https://claude.com/contact-sales/claude-for-oss) — in one command, right from your terminal.
+
+Maintainer reward programs list eligibility criteria in prose ("500+ dependent repos", "100+ merged PRs", "OpenSSF criticality ≥ 0.4"). Figuring out whether *you* actually qualify means manually digging through npm stats, GitHub search, and OpenSSF data. `oss-perks` does it in one command — no signup, no config, no dependencies.
+
+## How it works
+
+You give it a GitHub username (and optionally a package name). It then, in parallel:
+
+1. **Queries the [GitHub API](https://docs.github.com/rest)** for your merged-PR history, repos, and contributors.
+2. **Queries package registries** ([npm](https://api.npmjs.org) + [ecosyste.ms](https://ecosyste.ms)) for downloads and how many other packages/repos depend on yours.
+3. **Evaluates each program criterion** against those numbers and prints a clear ✓ / ✗ per rule, with the evidence behind every verdict.
+
+Everything is read-only public data. Nothing is stored or sent anywhere except those public APIs. It's a single ~15 KB CLI with **zero runtime dependencies**, so `npx oss-perks` starts instantly.
+
+```
+npx oss-perks sindresorhus -p npm:chalk
+```
+
+```
+  sindresorhus  https://github.com/sindresorhus
+──────────────────────────────────────────────────────────
+  ✓ PASS  Maintainer / library author
+         At least one package clears a maintainer threshold.
+           · npmjs:chalk — 1,795,989,333 monthly dl, 130085 dependent pkgs, 1291351 dependent repos  ✓
+  ? n/a   Core contributor (major foundation/project committer)  ~manual
+         Not machine-verifiable — cite it in your application.
+  ✗ fail  Active contributor (100+ merged PRs elsewhere / 12mo)
+         11 merged PRs in the last 12 months in repos sindresorhus doesn't own (need 100).
+  ✓ PASS  Community builder (20+ external contributors)  ~approx
+         sindresorhus/awesome has 199+ external contributors (all-time approximation).
+  ✓ PASS  Critical infrastructure (OpenSSF criticality >= 0.4)  ~approx
+──────────────────────────────────────────────────────────
+  Likely eligible — passes 3 of 5 criteria.
+```
+
+## Install
+
+Run without installing:
+
+```sh
+npx oss-perks <github-username>
+```
+
+Or install globally:
+
+```sh
+npm install -g oss-perks
+```
+
+**Set a GitHub token** to avoid rate limits (the GitHub Search API is 10 req/min unauthenticated):
+
+```sh
+export GITHUB_TOKEN=ghp_xxx   # a fine-grained token with public read scope is enough
+```
+
+## Usage
+
+```
+oss-perks <github-username> [options]
+
+  -p, --package <spec>   Package for the maintainer check. Repeatable.
+                         Prefix with a registry: npm: pypi: crates: gem:
+                         (a bare name defaults to npm).
+      --json             Machine-readable JSON output.
+      --repos <n>        Max owned repos to scan (default 100).
+  -h, --help             Help.
+  -v, --version          Version.
+```
+
+Examples:
+
+```sh
+oss-perks torvalds
+oss-perks sindresorhus -p npm:chalk -p npm:got
+oss-perks psf --package pypi:requests --json
+```
+
+Exit code is `0` when at least one criterion passes, `1` otherwise — handy in CI.
+
+## The criteria
+
+Rules mirror the **Claude for Open Source** program. You only need to meet **one**.
+
+| # | Criterion | Threshold | How `oss-perks` checks it | Confidence |
+|---|-----------|-----------|---------------------------|------------|
+| 1 | Maintainer / library author | 500+ dependent repos, or 100+ dependent packages, or 200k+ monthly downloads | npm downloads API + [ecosyste.ms](https://ecosyste.ms) dependents | exact |
+| 2 | Core contributor | Listed committer on a major foundation/project | Not machine-verifiable — flagged for manual citation | manual |
+| 3 | Active contributor | 100+ merged PRs in repos you don't own (12 mo) | GitHub Search API (`is:merged -user:you`) | exact |
+| 4 | Community builder | 20+ unique external contributors (1 yr) | GitHub contributors per repo, excluding owner | approximate¹ |
+| 5 | Critical infrastructure | OpenSSF criticality score ≥ 0.4 | ecosyste.ms score, else a stars/forks/age estimate | approximate² |
+
+¹ GitHub's contributors endpoint isn't time-windowed, so this is an all-time count (an upper bound on "last year"). It's also capped at 200 per repo by the API.
+² When ecosyste.ms doesn't expose a real [OpenSSF criticality score](https://github.com/ossf/criticality_score), a rough estimate from stars/forks/issues/age is shown and clearly labeled — run the official tool to confirm a borderline case.
+
+## Data sources
+
+- **GitHub REST API** — user, repos, contributors, merged-PR search.
+- **npm registry** (`api.npmjs.org`) — monthly downloads.
+- **[ecosyste.ms](https://ecosyste.ms)** — dependent-package/repo counts across npm, PyPI, crates.io, RubyGems, and OpenSSF criticality where available.
+
+No data is stored or transmitted anywhere except these public read-only APIs.
+
+## Programmatic use
+
+```ts
+import { check } from "oss-perks";
+
+const report = await check("sindresorhus", {
+  packages: [{ registry: "npmjs.org", name: "chalk" }],
+});
+console.log(report.eligible, report.passedCount);
+```
+
+## Contributing
+
+Issues and PRs welcome — especially adding new perk-program rulesets beyond Claude for OSS. See the criteria table above for where new checks plug in (`src/lib.ts`).
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,117 @@
+#!/usr/bin/env node
+// oss-perks — check open-source maintainer perk eligibility from the terminal.
+import { parseArgs } from "node:util";
+import { check, normalizeUser, parsePackageSpec } from "./lib.js";
+import { c } from "./util.js";
+const HELP = `${c.bold("oss-perks")} — check open-source maintainer perk eligibility
+
+${c.bold("USAGE")}
+  oss-perks <github-username> [options]
+
+${c.bold("OPTIONS")}
+  -p, --package <spec>   Package to check for the maintainer criterion.
+                         Repeatable. Prefix with a registry:
+                           npm:express  pypi:requests  crates:serde  gem:rails
+                         A bare name defaults to npm.
+      --json             Output machine-readable JSON.
+      --repos <n>        Max owned repos to scan (default 100).
+  -h, --help             Show this help.
+  -v, --version          Show version.
+
+${c.bold("EXAMPLES")}
+  oss-perks torvalds
+  oss-perks sindresorhus -p npm:chalk -p npm:got
+  oss-perks psf --package pypi:requests --json
+
+${c.bold("NOTES")}
+  Set ${c.cyan("GITHUB_TOKEN")} to raise GitHub API rate limits (recommended).
+  Rules mirror the Claude for Open Source program; see the README for sources.`;
+function statusBadge(s) {
+    if (s === "pass")
+        return c.green("✓ PASS");
+    if (s === "fail")
+        return c.red("✗ fail");
+    return c.yellow("? n/a ");
+}
+function confidenceTag(conf) {
+    if (conf === "exact")
+        return "";
+    if (conf === "approximate")
+        return c.dim(" ~approx");
+    return c.dim(" ~manual");
+}
+async function main() {
+    let parsed;
+    try {
+        parsed = parseArgs({
+            allowPositionals: true,
+            options: {
+                package: { type: "string", short: "p", multiple: true },
+                json: { type: "boolean" },
+                repos: { type: "string" },
+                help: { type: "boolean", short: "h" },
+                version: { type: "boolean", short: "v" },
+            },
+        });
+    }
+    catch (err) {
+        console.error(c.red(err.message));
+        console.error(`Run ${c.cyan("oss-perks --help")}.`);
+        process.exit(2);
+    }
+    const { values, positionals } = parsed;
+    if (values.version) {
+        const { createRequire } = await import("node:module");
+        const pkg = createRequire(import.meta.url)("../package.json");
+        console.log(pkg.version);
+        return;
+    }
+    if (values.help || positionals.length === 0) {
+        console.log(HELP);
+        process.exit(positionals.length === 0 && !values.help ? 1 : 0);
+    }
+    let username;
+    let packages;
+    try {
+        username = normalizeUser(positionals[0]);
+        packages = (values.package ?? []).map(parsePackageSpec);
+    }
+    catch (err) {
+        console.error(c.red(err.message));
+        process.exit(2);
+    }
+    const repoScan = values.repos ? Math.max(1, parseInt(values.repos, 10) || 100) : 100;
+    if (!values.json) {
+        process.stderr.write(c.dim(`Checking ${username}…\n`));
+    }
+    const report = await check(username, { packages, repoScan });
+    if (values.json) {
+        console.log(JSON.stringify(report, null, 2));
+        process.exit(report.eligible ? 0 : 1);
+    }
+    // Human-readable report
+    const line = c.gray("─".repeat(58));
+    console.log("");
+    console.log(`  ${c.bold(report.user)}${report.profileUrl ? c.dim("  " + report.profileUrl) : ""}`);
+    console.log(line);
+    for (const cr of report.criteria) {
+        console.log(`  ${statusBadge(cr.status)}  ${c.bold(cr.title)}${confidenceTag(cr.confidence)}`);
+        console.log(`         ${c.dim(cr.detail)}`);
+        for (const ev of cr.evidence ?? []) {
+            console.log(`           ${c.gray("· " + ev)}`);
+        }
+    }
+    console.log(line);
+    const verdict = report.eligible
+        ? c.green(c.bold(`Likely eligible — passes ${report.passedCount} of 5 criteria.`))
+        : c.yellow(`No criterion met automatically (passed ${report.passedCount}/5).`);
+    console.log(`  ${verdict}`);
+    console.log(c.dim("  You only need ONE criterion. The program also considers maintainers of\n" +
+        "  quietly-critical projects outside these bars — apply and make the case."));
+    console.log(c.dim("  Apply: https://claude.com/contact-sales/claude-for-oss\n"));
+    process.exit(report.eligible ? 0 : 1);
+}
+main().catch((err) => {
+    console.error(c.red(`Unexpected error: ${err?.message ?? err}`));
+    process.exit(3);
+});

package/dist/lib.d.ts

@@ -0,0 +1,45 @@
+import { type Registry } from "./sources.js";
+export type Status = "pass" | "fail" | "unknown";
+export interface CriterionResult {
+    id: string;
+    title: string;
+    status: Status;
+    /** Human-readable one-liner explaining the verdict. */
+    detail: string;
+    /** How confident the automated check is: exact | approximate | manual. */
+    confidence: "exact" | "approximate" | "manual";
+    /** Optional supporting bullet points. */
+    evidence?: string[];
+}
+export interface CheckReport {
+    user: string;
+    profileUrl?: string;
+    packages: {
+        registry: Registry;
+        name: string;
+    }[];
+    criteria: CriterionResult[];
+    eligible: boolean;
+    passedCount: number;
+}
+export interface CheckOptions {
+    /** Packages to evaluate for the maintainer criterion, e.g. "npm:express". */
+    packages?: {
+        registry: Registry;
+        name: string;
+    }[];
+    /** Cap how many of the user's repos we scan for community/criticality checks. */
+    repoScan?: number;
+}
+/**
+ * Normalize user input into a bare GitHub login.
+ * Accepts "octocat", "@octocat", "github.com/octocat",
+ * "https://github.com/octocat/", etc.
+ */
+export declare function normalizeUser(input: string): string;
+/** Parse "npm:express" / "pypi:requests" / bare "express" (defaults to npm). */
+export declare function parsePackageSpec(spec: string): {
+    registry: Registry;
+    name: string;
+};
+export declare function check(login: string, opts?: CheckOptions): Promise<CheckReport>;

package/dist/lib.js

@@ -0,0 +1,258 @@
+// Public API + the "Claude for Open Source" eligibility ruleset.
+//
+// Criteria (from https://claude.com/contact-sales/claude-for-oss):
+//   1. Maintainer / library author — a package with 500+ dependent repos,
+//      100+ dependent packages, or 200,000+ combined monthly downloads.
+//   2. Core contributor — listed committer on a major foundation/project.
+//   3. Active contributor — 100+ merged PRs in repos you don't own (12 months).
+//   4. Community builder — a repo with 20+ unique external contributors (1 year).
+//   5. Critical infrastructure — a repo with OpenSSF criticality score >= 0.4.
+//
+// Some criteria are cleanly measurable from public APIs (2 is not machine
+// verifiable and 4/5 use documented approximations — each result says so).
+import { countMergedPRsElsewhere, getContributors, getCriticalityScore, getPackageStats, getUser, getUserRepos, } from "./sources.js";
+const REGISTRY_ALIASES = {
+    npm: "npmjs.org",
+    "npmjs.org": "npmjs.org",
+    pypi: "pypi.org",
+    "pypi.org": "pypi.org",
+    pip: "pypi.org",
+    crates: "crates.io",
+    "crates.io": "crates.io",
+    cargo: "crates.io",
+    gem: "rubygems.org",
+    rubygems: "rubygems.org",
+    "rubygems.org": "rubygems.org",
+};
+/**
+ * Normalize user input into a bare GitHub login.
+ * Accepts "octocat", "@octocat", "github.com/octocat",
+ * "https://github.com/octocat/", etc.
+ */
+export function normalizeUser(input) {
+    let s = input.trim();
+    s = s.replace(/^https?:\/\//i, "").replace(/^www\./i, "");
+    if (s.toLowerCase().startsWith("github.com/"))
+        s = s.slice("github.com/".length);
+    s = s.replace(/^@/, "").replace(/[/?#].*$/, "").trim();
+    if (!/^[a-z\d](?:[a-z\d]|-(?=[a-z\d])){0,38}$/i.test(s)) {
+        throw new Error(`"${input}" is not a valid GitHub username.`);
+    }
+    return s;
+}
+/** Parse "npm:express" / "pypi:requests" / bare "express" (defaults to npm). */
+export function parsePackageSpec(spec) {
+    const idx = spec.indexOf(":");
+    if (idx === -1)
+        return { registry: "npmjs.org", name: spec };
+    const reg = REGISTRY_ALIASES[spec.slice(0, idx).toLowerCase()];
+    const name = spec.slice(idx + 1);
+    if (!reg)
+        throw new Error(`Unknown registry in "${spec}". Use npm:, pypi:, crates:, or gem:`);
+    return { registry: reg, name };
+}
+// --- individual criteria -------------------------------------------------
+async function checkMaintainer(specs) {
+    const base = {
+        id: "maintainer",
+        title: "Maintainer / library author",
+        status: "unknown",
+        confidence: "exact",
+        detail: "No package supplied. Re-run with --package npm:<name> (or pypi:/crates:/gem:) to check.",
+    };
+    if (specs.length === 0)
+        return base;
+    const stats = [];
+    for (const s of specs) {
+        try {
+            stats.push(await getPackageStats(s.registry, s.name));
+        }
+        catch {
+            /* skip unresolvable packages */
+        }
+    }
+    if (stats.length === 0) {
+        return { ...base, status: "unknown", detail: "Could not resolve any supplied package." };
+    }
+    const evidence = [];
+    let pass = false;
+    for (const s of stats) {
+        const dl = s.monthlyDownloads;
+        const dp = s.dependentPackages;
+        const dr = s.dependentRepos;
+        const hit = (dr != null && dr >= 500) ||
+            (dp != null && dp >= 100) ||
+            (dl != null && dl >= 200_000);
+        if (hit)
+            pass = true;
+        evidence.push(`${s.registry.split(".")[0]}:${s.name} — ` +
+            `${dl != null ? dl.toLocaleString() : "?"} monthly dl, ` +
+            `${dp ?? "?"} dependent pkgs, ${dr ?? "?"} dependent repos` +
+            (hit ? "  ✓" : ""));
+    }
+    const anyData = stats.some((s) => s.monthlyDownloads != null || s.dependentPackages != null || s.dependentRepos != null);
+    return {
+        ...base,
+        status: pass ? "pass" : anyData ? "fail" : "unknown",
+        detail: pass
+            ? "At least one package clears a maintainer threshold."
+            : anyData
+                ? "No supplied package reaches 500 dependent repos / 100 dependent packages / 200k monthly downloads."
+                : "Package stats unavailable from registries right now.",
+        evidence,
+    };
+}
+async function checkActiveContributor(login) {
+    const base = {
+        id: "active-contributor",
+        title: "Active contributor (100+ merged PRs elsewhere / 12mo)",
+        status: "unknown",
+        confidence: "exact",
+        detail: "",
+    };
+    try {
+        const n = await countMergedPRsElsewhere(login, 365);
+        return {
+            ...base,
+            status: n >= 100 ? "pass" : "fail",
+            detail: `${n} merged PR${n === 1 ? "" : "s"} in the last 12 months in repos ${login} doesn't own (need 100).`,
+        };
+    }
+    catch (err) {
+        return { ...base, detail: `GitHub search failed: ${err.message}` };
+    }
+}
+async function checkCommunityAndCriticality(login, repoScan) {
+    const community = {
+        id: "community-builder",
+        title: "Community builder (20+ external contributors)",
+        status: "unknown",
+        confidence: "approximate",
+        detail: "",
+    };
+    const criticality = {
+        id: "critical-infra",
+        title: "Critical infrastructure (OpenSSF criticality >= 0.4)",
+        status: "unknown",
+        confidence: "approximate",
+        detail: "",
+    };
+    let repos;
+    try {
+        repos = await getUserRepos(login, repoScan);
+    }
+    catch (err) {
+        const msg = `Could not list repos: ${err.message}`;
+        community.detail = msg;
+        criticality.detail = msg;
+        return { community, criticality };
+    }
+    if (repos.length === 0) {
+        community.detail = "No public non-fork repos found.";
+        community.status = "fail";
+        criticality.detail = "No public non-fork repos found.";
+        criticality.status = "fail";
+        return { community, criticality };
+    }
+    // Community: scan top repos by stars, count contributors excluding the owner.
+    const topForContributors = repos.slice(0, Math.min(8, repos.length));
+    let bestRepo = "";
+    let bestExternal = 0;
+    const communityEvidence = [];
+    for (const r of topForContributors) {
+        try {
+            const contribs = await getContributors(r.full_name);
+            const external = contribs.filter((c) => c.login && c.login.toLowerCase() !== login.toLowerCase() && c.type !== "Bot").length;
+            if (external > bestExternal) {
+                bestExternal = external;
+                bestRepo = r.full_name;
+            }
+            if (external > 0)
+                communityEvidence.push(`${r.full_name}: ${external} external contributors`);
+        }
+        catch {
+            /* skip repos we can't read */
+        }
+    }
+    community.status = bestExternal >= 20 ? "pass" : "fail";
+    community.detail =
+        bestExternal >= 20
+            ? `${bestRepo} has ${bestExternal}+ external contributors (all-time approximation).`
+            : `Best repo has ${bestExternal} external contributors (need 20). Note: all-time count, not strictly last 12 months.`;
+    community.evidence = communityEvidence.slice(0, 5);
+    // Criticality: try the real OpenSSF score for the top repo; else estimate.
+    const top = repos[0];
+    let score = await getCriticalityScore(top.full_name);
+    let confidence = "exact";
+    if (score == null) {
+        score = estimateCriticality(top);
+        confidence = "approximate";
+    }
+    criticality.confidence = confidence;
+    criticality.status = score >= 0.4 ? "pass" : "fail";
+    criticality.detail =
+        `${top.full_name}: criticality ${score.toFixed(2)} ` +
+            (confidence === "exact"
+                ? "(OpenSSF, need 0.4)."
+                : "(rough estimate from stars/forks/contributors — run the real openssf/criticality_score tool to confirm).");
+    return { community, criticality };
+}
+/**
+ * Very rough OpenSSF-criticality-style estimate in [0,1] from cheap signals.
+ * NOT the official algorithm — only a hint when the real score is unavailable.
+ */
+function estimateCriticality(r) {
+    const norm = (v, max) => Math.min(1, Math.log10(1 + v) / Math.log10(1 + max));
+    const stars = norm(r.stargazers_count, 40000);
+    const forks = norm(r.forks_count, 8000);
+    const issues = norm(r.open_issues_count, 2000);
+    const ageDays = (Date.now() - Date.parse(r.created_at)) / 86_400_000;
+    const age = norm(ageDays, 3650);
+    return Number((stars * 0.45 + forks * 0.25 + issues * 0.15 + age * 0.15).toFixed(3));
+}
+function coreContributorPlaceholder(login) {
+    return {
+        id: "core-contributor",
+        title: "Core contributor (major foundation/project committer)",
+        status: "unknown",
+        confidence: "manual",
+        detail: "Not machine-verifiable. If you're a listed committer on a major project " +
+            "(CPython, Rust, Node.js, Apache, Kubernetes, Django, Rails, …), cite it in your application.",
+        evidence: [
+            `Check your commit access / CONTRIBUTORS / MAINTAINERS listing and link it for ${login}.`,
+        ],
+    };
+}
+// --- orchestrator --------------------------------------------------------
+export async function check(login, opts = {}) {
+    const specs = opts.packages ?? [];
+    const repoScan = opts.repoScan ?? 100;
+    let profileUrl;
+    try {
+        profileUrl = (await getUser(login)).html_url;
+    }
+    catch {
+        /* user lookup is non-fatal */
+    }
+    const [maintainer, active, cc] = await Promise.all([
+        checkMaintainer(specs),
+        checkActiveContributor(login),
+        checkCommunityAndCriticality(login, repoScan),
+    ]);
+    const criteria = [
+        maintainer,
+        coreContributorPlaceholder(login),
+        active,
+        cc.community,
+        cc.criticality,
+    ];
+    const passedCount = criteria.filter((x) => x.status === "pass").length;
+    return {
+        user: login,
+        profileUrl,
+        packages: specs,
+        criteria,
+        eligible: passedCount > 0,
+        passedCount,
+    };
+}

package/dist/sources.d.ts

@@ -0,0 +1,54 @@
+export interface GhRepo {
+    name: string;
+    full_name: string;
+    owner: {
+        login: string;
+    };
+    fork: boolean;
+    archived: boolean;
+    stargazers_count: number;
+    forks_count: number;
+    open_issues_count: number;
+    pushed_at: string;
+    created_at: string;
+}
+export interface GhUser {
+    login: string;
+    name: string | null;
+    public_repos: number;
+    followers: number;
+    created_at: string;
+    html_url: string;
+}
+export declare function getUser(login: string): Promise<GhUser>;
+/** Public source repos owned by the user, sorted by stars desc. */
+export declare function getUserRepos(login: string, max?: number): Promise<GhRepo[]>;
+export interface SearchCount {
+    total_count: number;
+}
+/** Merged PRs authored by `login` in repos they do NOT own, in the last `days`. */
+export declare function countMergedPRsElsewhere(login: string, days?: number): Promise<number>;
+export interface Contributor {
+    login: string;
+    contributions: number;
+    type: string;
+}
+/** Contributors to a repo (paginated, capped). */
+export declare function getContributors(fullName: string, cap?: number): Promise<Contributor[]>;
+export type Registry = "npmjs.org" | "pypi.org" | "crates.io" | "rubygems.org";
+export interface PackageStats {
+    registry: Registry;
+    name: string;
+    monthlyDownloads: number | null;
+    dependentPackages: number | null;
+    dependentRepos: number | null;
+    criticalityScore: number | null;
+}
+/** ecosyste.ms unifies dependent counts across registries. */
+export declare function getPackageStats(registry: Registry, name: string): Promise<PackageStats>;
+/**
+ * Best-effort OpenSSF criticality score for a GitHub repo.
+ * ecosyste.ms exposes repo metadata but not always a criticality field, so
+ * this returns null when unavailable and the caller falls back to an estimate.
+ */
+export declare function getCriticalityScore(fullName: string): Promise<number | null>;

package/dist/sources.js

@@ -0,0 +1,143 @@
+// Data sources: GitHub REST API + package registry stats (npm, ecosyste.ms).
+// All functions are best-effort and throw HttpError on transport/API failures;
+// callers decide how to degrade.
+import { getJson, isoDaysAgo } from "./util.js";
+const GH = "https://api.github.com";
+function ghHeaders() {
+    const token = process.env.GITHUB_TOKEN || process.env.GH_TOKEN;
+    const headers = {
+        accept: "application/vnd.github+json",
+        "x-github-api-version": "2022-11-28",
+    };
+    if (token)
+        headers.authorization = `Bearer ${token}`;
+    return headers;
+}
+export async function getUser(login) {
+    return getJson(`${GH}/users/${encodeURIComponent(login)}`, {
+        headers: ghHeaders(),
+    });
+}
+/** Public source repos owned by the user, sorted by stars desc. */
+export async function getUserRepos(login, max = 100) {
+    const perPage = 100;
+    const out = [];
+    for (let page = 1; out.length < max; page++) {
+        const batch = await getJson(`${GH}/users/${encodeURIComponent(login)}/repos?per_page=${perPage}&page=${page}&sort=pushed`, { headers: ghHeaders() });
+        out.push(...batch);
+        if (batch.length < perPage)
+            break;
+        if (page >= 5)
+            break; // safety cap: 500 repos
+    }
+    return out
+        .filter((r) => !r.fork && !r.archived)
+        .sort((a, b) => b.stargazers_count - a.stargazers_count)
+        .slice(0, max);
+}
+/** Merged PRs authored by `login` in repos they do NOT own, in the last `days`. */
+export async function countMergedPRsElsewhere(login, days = 365) {
+    const q = [
+        "type:pr",
+        `author:${login}`,
+        "is:merged",
+        `-user:${login}`,
+        `created:>=${isoDaysAgo(days)}`,
+    ].join("+");
+    const res = await getJson(`${GH}/search/issues?q=${q}&per_page=1&advanced_search=true`, { headers: ghHeaders() });
+    return res.total_count;
+}
+/** Contributors to a repo (paginated, capped). */
+export async function getContributors(fullName, cap = 200) {
+    const perPage = 100;
+    const out = [];
+    for (let page = 1; out.length < cap; page++) {
+        const batch = await getJson(`${GH}/repos/${fullName}/contributors?per_page=${perPage}&page=${page}&anon=false`, { headers: ghHeaders() });
+        out.push(...batch);
+        if (batch.length < perPage)
+            break;
+        if (page >= 3)
+            break;
+    }
+    return out;
+}
+/** npm's own download endpoint is the most reliable source for npm packages. */
+async function npmMonthlyDownloads(name) {
+    try {
+        const res = await getJson(`https://api.npmjs.org/downloads/point/last-month/${encodeURIComponent(name)}`);
+        return typeof res.downloads === "number" ? res.downloads : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** pypistats.org exposes accurate last-month PyPI download counts. */
+async function pypiMonthlyDownloads(name) {
+    try {
+        const res = await getJson(`https://pypistats.org/api/packages/${encodeURIComponent(name.toLowerCase())}/recent`);
+        return res.data?.last_month ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+/** crates.io reports ~90-day "recent" downloads; approximate a monthly figure. */
+async function cratesMonthlyDownloads(name) {
+    try {
+        const res = await getJson(`https://crates.io/api/v1/crates/${encodeURIComponent(name)}`);
+        const recent = res.crate?.recent_downloads;
+        return typeof recent === "number" ? Math.round(recent / 3) : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** ecosyste.ms unifies dependent counts across registries. */
+export async function getPackageStats(registry, name) {
+    const stats = {
+        registry,
+        name,
+        monthlyDownloads: null,
+        dependentPackages: null,
+        dependentRepos: null,
+        criticalityScore: null,
+    };
+    try {
+        const pkg = await getJson(`https://packages.ecosyste.ms/api/v1/registries/${registry}/packages/${encodeURIComponent(name)}`);
+        stats.dependentPackages = pkg.dependent_packages_count ?? null;
+        stats.dependentRepos = pkg.dependent_repos_count ?? null;
+        // ecosyste.ms `downloads` period varies; only trust it as a monthly figure
+        // when explicitly labeled as such.
+        if (pkg.downloads != null && /month/i.test(pkg.downloads_period ?? "")) {
+            stats.monthlyDownloads = pkg.downloads;
+        }
+    }
+    catch {
+        /* fall through to per-registry sources */
+    }
+    // Prefer each registry's authoritative download source over ecosyste.ms.
+    if (stats.monthlyDownloads == null) {
+        if (registry === "npmjs.org")
+            stats.monthlyDownloads = await npmMonthlyDownloads(name);
+        else if (registry === "pypi.org")
+            stats.monthlyDownloads = await pypiMonthlyDownloads(name);
+        else if (registry === "crates.io")
+            stats.monthlyDownloads = await cratesMonthlyDownloads(name);
+    }
+    return stats;
+}
+/**
+ * Best-effort OpenSSF criticality score for a GitHub repo.
+ * ecosyste.ms exposes repo metadata but not always a criticality field, so
+ * this returns null when unavailable and the caller falls back to an estimate.
+ */
+export async function getCriticalityScore(fullName) {
+    try {
+        const repo = await getJson(`https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/${fullName}`);
+        const score = repo.metadata?.criticality_score;
+        return typeof score === "number" ? score : null;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/util.d.ts

@@ -0,0 +1,30 @@
+export declare const c: {
+    bold: (s: string | number) => string;
+    dim: (s: string | number) => string;
+    red: (s: string | number) => string;
+    green: (s: string | number) => string;
+    yellow: (s: string | number) => string;
+    blue: (s: string | number) => string;
+    magenta: (s: string | number) => string;
+    cyan: (s: string | number) => string;
+    gray: (s: string | number) => string;
+};
+export declare class HttpError extends Error {
+    readonly status: number;
+    readonly url: string;
+    /** True when the failure is a GitHub/registry rate limit (HTTP 403/429). */
+    readonly rateLimited: boolean;
+    constructor(message: string, status: number, url: string, 
+    /** True when the failure is a GitHub/registry rate limit (HTTP 403/429). */
+    rateLimited?: boolean);
+}
+export interface FetchOptions {
+    headers?: Record<string, string>;
+    timeoutMs?: number;
+}
+/** fetch JSON with a timeout and a descriptive error on non-2xx. */
+export declare function getJson<T = unknown>(url: string, opts?: FetchOptions): Promise<T>;
+export declare function fmtNumber(n: number): string;
+/** Compact number: 1234 -> 1.2k, 1200000 -> 1.2M */
+export declare function compact(n: number): string;
+export declare function isoDaysAgo(days: number): string;

package/dist/util.js

@@ -0,0 +1,77 @@
+// Small zero-dependency helpers: ANSI colors, fetch-with-timeout, formatting.
+const useColor = process.env.NO_COLOR === undefined &&
+    process.env.FORCE_COLOR !== "0" &&
+    (process.stdout.isTTY || process.env.FORCE_COLOR !== undefined);
+const wrap = (open, close) => (s) => useColor ? `[${open}m${s}[${close}m` : String(s);
+export const c = {
+    bold: wrap(1, 22),
+    dim: wrap(2, 22),
+    red: wrap(31, 39),
+    green: wrap(32, 39),
+    yellow: wrap(33, 39),
+    blue: wrap(34, 39),
+    magenta: wrap(35, 39),
+    cyan: wrap(36, 39),
+    gray: wrap(90, 39),
+};
+export class HttpError extends Error {
+    status;
+    url;
+    rateLimited;
+    constructor(message, status, url, 
+    /** True when the failure is a GitHub/registry rate limit (HTTP 403/429). */
+    rateLimited = false) {
+        super(message);
+        this.status = status;
+        this.url = url;
+        this.rateLimited = rateLimited;
+        this.name = "HttpError";
+    }
+}
+/** fetch JSON with a timeout and a descriptive error on non-2xx. */
+export async function getJson(url, opts = {}) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), opts.timeoutMs ?? 15000);
+    try {
+        const res = await fetch(url, {
+            headers: { "user-agent": "oss-perks", accept: "application/json", ...opts.headers },
+            signal: controller.signal,
+        });
+        if (!res.ok) {
+            const remaining = res.headers.get("x-ratelimit-remaining");
+            const rateLimited = res.status === 429 || (res.status === 403 && remaining === "0");
+            const hint = rateLimited
+                ? " — rate limited. Set GITHUB_TOKEN to raise the limit (see README)."
+                : "";
+            throw new HttpError(`HTTP ${res.status} for ${url}${hint}`, res.status, url, rateLimited);
+        }
+        return (await res.json());
+    }
+    catch (err) {
+        if (err instanceof HttpError)
+            throw err;
+        if (err instanceof Error && err.name === "AbortError") {
+            throw new HttpError(`Request timed out: ${url}`, 0, url);
+        }
+        throw err;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+export function fmtNumber(n) {
+    return n.toLocaleString("en-US");
+}
+/** Compact number: 1234 -> 1.2k, 1200000 -> 1.2M */
+export function compact(n) {
+    if (n < 1000)
+        return String(n);
+    if (n < 1_000_000)
+        return `${(n / 1000).toFixed(n < 10_000 ? 1 : 0)}k`;
+    return `${(n / 1_000_000).toFixed(1)}M`;
+}
+export function isoDaysAgo(days) {
+    // Deterministic ISO date `days` before now (UTC, date only).
+    const d = new Date(Date.now() - days * 24 * 60 * 60 * 1000);
+    return d.toISOString().slice(0, 10);
+}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@o4h8/oss-perks",
+  "version": "0.1.0",
+  "description": "Check whether a GitHub user or package qualifies for open-source maintainer perk programs (Claude for Open Source, and more). Zero-config CLI.",
+  "keywords": [
+    "open-source",
+    "oss",
+    "maintainer",
+    "eligibility",
+    "github",
+    "npm",
+    "criticality",
+    "cli",
+    "claude"
+  ],
+  "type": "module",
+  "bin": {
+    "oss-perks": "dist/index.js"
+  },
+  "exports": {
+    ".": "./dist/lib.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "start": "node dist/index.js",
+    "test": "npm run build && node --test",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "MIT",
+  "author": "Ozkan Hancioglu <hanciogluozkan@gmail.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/o4h8/oss-perks.git"
+  },
+  "homepage": "https://github.com/o4h8/oss-perks#readme",
+  "bugs": {
+    "url": "https://github.com/o4h8/oss-perks/issues"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "typescript": "^5.7.0"
+  }
+}