loadout-ai 0.1.0

package/dist/src/core/evaluate.js

@@ -0,0 +1,72 @@
+import { inspectPackage } from "./package.js";
+import { analyzeUpdateSafety } from "./safety.js";
+function statusFor(findings) {
+    if (findings.some((finding) => finding.category === "secret" || finding.category === "instruction"))
+        return "blocked";
+    return findings.length ? "needs-review" : "ready";
+}
+/**
+ * Deterministically assesses static package evidence. It never starts an MCP
+ * server, executes a script, calls a model, or claims a performance benchmark.
+ */
+export async function evaluatePackage(root) {
+    const inspection = await inspectPackage(root);
+    const safety = await analyzeUpdateSafety(undefined, root);
+    const sharedSafety = safety.findings.map((finding) => finding.message);
+    const names = inspection.skills.map((skill) => skill.name.toLowerCase());
+    const duplicateNames = names.filter((name, index) => names.indexOf(name) !== index);
+    const skillFindings = [
+        ...(duplicateNames.length
+            ? [`Duplicate skill names: ${[...new Set(duplicateNames)].join(", ")}`]
+            : []),
+        ...inspection.warnings,
+        ...sharedSafety,
+    ];
+    const mcpWarnings = inspection.mcpServers.flatMap((server) => server.warnings.map((warning) => `${server.name}: ${warning}`));
+    const invalidMcp = inspection.mcpServers.filter((server) => server.transport === "unknown");
+    const mcpFindings = [
+        ...mcpWarnings,
+        ...invalidMcp.map((server) => `${server.name}: no usable transport`),
+        ...sharedSafety,
+    ];
+    const invalidSkillEvidence = inspection.warnings.some((warning) => /skill (?:security validation failed|package|path|SKILL\.md)/i.test(warning));
+    const hasSkillEvidence = inspection.skills.length > 0 || invalidSkillEvidence;
+    return {
+        evaluatorVersion: 1,
+        root: inspection.root,
+        categories: [
+            {
+                category: "skills",
+                status: invalidSkillEvidence
+                    ? "blocked"
+                    : hasSkillEvidence
+                        ? statusFor(safety.findings)
+                        : "not-applicable",
+                findings: hasSkillEvidence ? skillFindings : [],
+            },
+            {
+                category: "mcp",
+                status: inspection.counts.manifests === 0
+                    ? "not-applicable"
+                    : invalidMcp.length ||
+                        safety.findings.some((item) => item.category === "secret")
+                        ? "blocked"
+                        : mcpFindings.length
+                            ? "needs-review"
+                            : "ready",
+                findings: inspection.counts.manifests ? mcpFindings : [],
+            },
+        ],
+        uncertainty: "Static evidence only. This does not measure model quality, MCP uptime, permissions at runtime, or task performance.",
+    };
+}
+export function formatPackageEvaluation(evaluation) {
+    const lines = [`Evaluation: ${evaluation.root}`];
+    for (const category of evaluation.categories) {
+        lines.push(`${category.category}: ${category.status}`);
+        for (const finding of category.findings)
+            lines.push(`  - ${finding}`);
+    }
+    lines.push(`Uncertainty: ${evaluation.uncertainty}`);
+    return lines.join("\n");
+}

package/dist/src/core/file-lock.js

@@ -0,0 +1,140 @@
+import { randomUUID } from "node:crypto";
+import { mkdir, open, readFile, rename, rm, stat, utimes, } from "node:fs/promises";
+import { dirname } from "node:path";
+import { ensureDirectory } from "./paths.js";
+const wait = (milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds));
+function parseOwner(content) {
+    try {
+        const value = JSON.parse(content);
+        if (typeof value.token === "string" &&
+            typeof value.pid === "number" &&
+            Number.isInteger(value.pid) &&
+            value.pid > 0 &&
+            typeof value.acquiredAt === "string")
+            return value;
+    }
+    catch {
+        /* an incomplete owner file is handled only after it becomes stale */
+    }
+    return undefined;
+}
+function processIsAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return !(error &&
+            typeof error === "object" &&
+            "code" in error &&
+            error.code === "ESRCH");
+    }
+}
+async function reclaimIfAbandoned(path, staleMs, maximumLeaseMs) {
+    const reclaim = `${path}.reclaim`;
+    try {
+        await mkdir(reclaim);
+    }
+    catch {
+        return;
+    }
+    try {
+        let info;
+        let owner;
+        try {
+            [info, owner] = await Promise.all([
+                stat(path),
+                readFile(path, "utf8").then(parseOwner),
+            ]);
+        }
+        catch {
+            return;
+        }
+        const heartbeatAge = Date.now() - info.mtimeMs;
+        // PID liveness protects a delayed event loop or short machine sleep. The
+        // hard ceiling prevents a reused PID from owning an orphan forever;
+        // healthy owners refresh mtime and never approach this ceiling.
+        if (owner && processIsAlive(owner.pid) && heartbeatAge <= maximumLeaseMs)
+            return;
+        if (!owner && heartbeatAge <= staleMs)
+            return;
+        const quarantine = `${path}.abandoned-${randomUUID()}`;
+        try {
+            await rename(path, quarantine);
+            await rm(quarantine, { force: true });
+        }
+        catch {
+            /* another contender changed the lock; retry through normal acquisition */
+        }
+    }
+    finally {
+        await rm(reclaim, { recursive: true, force: true });
+    }
+}
+/** Acquire a token-owned, heartbeating cross-process lock. */
+export async function acquireFileLock(path, options = {}) {
+    const timeoutMs = options.timeoutMs ?? 5_000;
+    const staleMs = options.staleMs ?? 60_000;
+    const maximumLeaseMs = options.maximumLeaseMs ?? Math.max(24 * 60 * 60 * 1_000, staleMs * 10);
+    const started = Date.now();
+    await ensureDirectory(dirname(path));
+    while (true) {
+        const token = randomUUID();
+        try {
+            const handle = await open(path, "wx", 0o600);
+            try {
+                await handle.writeFile(`${JSON.stringify({ token, pid: process.pid, acquiredAt: new Date().toISOString() })}\n`);
+            }
+            catch (error) {
+                await handle.close().catch(() => undefined);
+                await rm(path, { force: true }).catch(() => undefined);
+                throw error;
+            }
+            await handle.close();
+            const heartbeat = setInterval(() => {
+                const now = new Date();
+                void utimes(path, now, now).catch(() => undefined);
+            }, Math.max(1_000, Math.floor(staleMs / 3)));
+            heartbeat.unref();
+            let released = false;
+            return {
+                path,
+                token,
+                async release() {
+                    if (released)
+                        return;
+                    released = true;
+                    clearInterval(heartbeat);
+                    try {
+                        const owner = parseOwner(await readFile(path, "utf8"));
+                        if (owner?.token === token)
+                            await rm(path, { force: true });
+                    }
+                    catch {
+                        /* ownership changed or the lock was already removed */
+                    }
+                },
+            };
+        }
+        catch (error) {
+            if (!error ||
+                typeof error !== "object" ||
+                !("code" in error) ||
+                error.code !== "EEXIST")
+                throw error;
+        }
+        await reclaimIfAbandoned(path, staleMs, maximumLeaseMs);
+        if (Date.now() - started >= timeoutMs)
+            throw new Error(`Timed out waiting for Loadout state lock: ${path}`);
+        await wait(50);
+    }
+}
+export async function withFileLock(path, operation, options = {}) {
+    const lock = await acquireFileLock(path, options);
+    try {
+        return await operation();
+    }
+    finally {
+        await lock.release();
+    }
+}

package/dist/src/core/freshness-alerts.js

@@ -0,0 +1,230 @@
+import { createHash } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { writeFileAtomically } from "./atomic-file.js";
+import { loadEffectiveCatalog } from "./catalog.js";
+import { ensureDirectory, loadoutHome } from "./paths.js";
+import { readInstallState } from "./state.js";
+import { buildUpdatePlan } from "./update.js";
+const decisionsPath = () => join(loadoutHome(), "alert-decisions.json");
+function alertId(packageId, kind, evidence) {
+    return `${packageId}-${kind}-${createHash("sha256")
+        .update(evidence)
+        .digest("hex")
+        .slice(0, 10)}`;
+}
+async function readDecisions() {
+    try {
+        const value = JSON.parse(await readFile(decisionsPath(), "utf8"));
+        if (value.schemaVersion !== 1 ||
+            !Array.isArray(value.ignored) ||
+            value.ignored.some((item) => !item ||
+                typeof item.id !== "string" ||
+                typeof item.ignoredAt !== "string") ||
+            (value.replacementPins !== undefined &&
+                (!Array.isArray(value.replacementPins) ||
+                    value.replacementPins.some((item) => !item ||
+                        typeof item.packageId !== "string" ||
+                        typeof item.replacementPackageId !== "string" ||
+                        typeof item.pinnedAt !== "string"))))
+            throw new Error("alert decision schema is invalid");
+        return { ...value, replacementPins: value.replacementPins ?? [] };
+    }
+    catch (error) {
+        if (error &&
+            typeof error === "object" &&
+            "code" in error &&
+            error.code === "ENOENT")
+            return { schemaVersion: 1, ignored: [], replacementPins: [] };
+        throw error;
+    }
+}
+function packageAlerts(state, catalog, updates, replacementEvidence, now) {
+    const catalogById = new Map(catalog.map((item) => [item.id, item]));
+    const catalogByRepository = new Map(catalog.map((item) => [item.repository.toLowerCase(), item]));
+    return state.installs.flatMap((install) => {
+        const pkg = catalogById.get(install.packageId) ??
+            (install.repository
+                ? catalogByRepository.get(install.repository.toLowerCase())
+                : undefined);
+        if (!pkg)
+            return [];
+        const alerts = [];
+        if (pkg.archived) {
+            const evidence = `${pkg.repository} is archived in current GitHub metadata`;
+            alerts.push({
+                id: alertId(install.packageId, "archived", evidence),
+                packageId: install.packageId,
+                kind: "archived",
+                severity: "critical",
+                message: "The installed source is archived.",
+                evidence: [evidence],
+                actions: [
+                    `loadout compare ${install.packageId}`,
+                    `loadout disable ${install.packageId}`,
+                ],
+                ignored: false,
+            });
+        }
+        if (pkg.pushedAt) {
+            const ageDays = Math.floor((now.getTime() - Date.parse(pkg.pushedAt)) / 86_400_000);
+            if (ageDays >= 365 && !pkg.archived) {
+                const evidence = `last code push was ${ageDays} days ago (${pkg.pushedAt})`;
+                alerts.push({
+                    id: alertId(install.packageId, "materially-stale", evidence),
+                    packageId: install.packageId,
+                    kind: "materially-stale",
+                    severity: "warning",
+                    message: "The installed source is materially stale by the disclosed one-year heuristic.",
+                    evidence: [evidence],
+                    actions: [
+                        `loadout compare ${install.packageId}`,
+                        `loadout alert-ignore <alert-id>`,
+                    ],
+                    ignored: false,
+                });
+            }
+        }
+        if (install.resolvedCommit &&
+            pkg.source?.commit &&
+            install.resolvedCommit.toLowerCase() !== pkg.source.commit.toLowerCase()) {
+            const evidence = `installed ${install.resolvedCommit.slice(0, 12)}; reviewed catalog ${pkg.source.commit.slice(0, 12)}`;
+            alerts.push({
+                id: alertId(install.packageId, "reviewed-commit-changed", evidence),
+                packageId: install.packageId,
+                kind: "reviewed-commit-changed",
+                severity: "info",
+                message: "A different reviewed catalog commit is available.",
+                evidence: [evidence],
+                actions: [
+                    `loadout update --package ${install.packageId}`,
+                    `loadout compare ${install.packageId}`,
+                ],
+                ignored: false,
+            });
+        }
+        const update = updates.find((item) => item.packageId === install.packageId &&
+            item.status === "update-available" &&
+            item.approvalRequired);
+        if (update) {
+            const categories = [
+                ...new Set((update.safetyFindings ?? []).map((item) => item.category)),
+            ];
+            const evidence = `update safety findings: ${categories.join(", ") || "manual approval required"}`;
+            alerts.push({
+                id: alertId(install.packageId, "permission-expansion", evidence),
+                packageId: install.packageId,
+                kind: "permission-expansion",
+                severity: "warning",
+                message: "The available update adds or changes safety-sensitive behavior.",
+                evidence: [evidence],
+                actions: [`loadout update --package ${install.packageId}`],
+                ignored: false,
+            });
+        }
+        for (const evidence of replacementEvidence.filter((item) => item.installedPackageId === install.packageId && item.scoreDelta > 0)) {
+            const replacement = catalogById.get(evidence.replacementPackageId);
+            if (!replacement)
+                continue;
+            const proof = `signed evidence ${evidence.evidenceId} reports ${replacement.id} ahead by ${evidence.scoreDelta.toFixed(2)} points in its declared category`;
+            alerts.push({
+                id: alertId(install.packageId, "outperformed", proof),
+                packageId: install.packageId,
+                kind: "outperformed",
+                severity: "info",
+                message: `${replacement.displayName} has stronger reviewed evaluation evidence for a declared category.`,
+                evidence: [proof],
+                actions: [
+                    `loadout compare ${install.packageId}`,
+                    `loadout alert-pin ${install.packageId} ${replacement.id}`,
+                ],
+                ignored: false,
+            });
+        }
+        return alerts;
+    });
+}
+export async function buildFreshnessAlerts(options = {}) {
+    const [catalog, state, updates, decisions] = await Promise.all([
+        options.catalog ?? loadEffectiveCatalog(),
+        options.state ?? readInstallState(),
+        options.updates ??
+            (options.checkUpdates ? buildUpdatePlan() : Promise.resolve([])),
+        readDecisions(),
+    ]);
+    const ignored = new Set(decisions.ignored.map((item) => item.id));
+    return packageAlerts(state, catalog, updates, options.replacementEvidence ?? [], options.now ?? new Date()).map((alert) => ({ ...alert, ignored: ignored.has(alert.id) }));
+}
+export async function ignoreFreshnessAlert(id) {
+    if (!/^[a-zA-Z0-9._-]+$/.test(id))
+        throw new Error("Invalid alert id");
+    const decisions = await readDecisions();
+    decisions.ignored = [
+        ...decisions.ignored.filter((item) => item.id !== id),
+        { id, ignoredAt: new Date().toISOString() },
+    ].slice(-1000);
+    await ensureDirectory(dirname(decisionsPath()));
+    await writeFileAtomically(decisionsPath(), `${JSON.stringify(decisions, null, 2)}\n`);
+}
+function validPackageId(value) {
+    if (!/^[a-z0-9][a-z0-9._-]{0,127}$/i.test(value))
+        throw new Error("Invalid package id");
+}
+/** Record an explicit local replacement preference; this never changes an active set. */
+export async function pinReplacement(packageId, replacementPackageId, options = {}) {
+    validPackageId(packageId);
+    validPackageId(replacementPackageId);
+    if (packageId === replacementPackageId)
+        throw new Error("A package cannot replace itself");
+    const [catalog, state] = await Promise.all([
+        options.catalog ?? loadEffectiveCatalog(),
+        options.state ?? readInstallState(),
+    ]);
+    if (!state.installs.some((install) => install.packageId === packageId))
+        throw new Error(`Package '${packageId}' is not installed`);
+    const current = catalog.find((pkg) => pkg.id === packageId);
+    const replacement = catalog.find((pkg) => pkg.id === replacementPackageId);
+    if (!current)
+        throw new Error(`Installed package '${packageId}' is not in the reviewed catalog`);
+    if (!replacement)
+        throw new Error(`Replacement '${replacementPackageId}' is not in the reviewed catalog`);
+    if (current.category !== replacement.category)
+        throw new Error(`Replacement categories differ (${current.category} vs ${replacement.category}); compare related capabilities only`);
+    const decisions = await readDecisions();
+    decisions.replacementPins = [
+        ...decisions.replacementPins.filter((item) => item.packageId !== packageId),
+        { packageId, replacementPackageId, pinnedAt: new Date().toISOString() },
+    ];
+    await ensureDirectory(dirname(decisionsPath()));
+    await writeFileAtomically(decisionsPath(), `${JSON.stringify(decisions, null, 2)}\n`);
+}
+export async function unpinReplacement(packageId) {
+    validPackageId(packageId);
+    const decisions = await readDecisions();
+    const replacementPins = decisions.replacementPins.filter((item) => item.packageId !== packageId);
+    const changed = replacementPins.length !== decisions.replacementPins.length;
+    if (!changed)
+        return false;
+    decisions.replacementPins = replacementPins;
+    await ensureDirectory(dirname(decisionsPath()));
+    await writeFileAtomically(decisionsPath(), `${JSON.stringify(decisions, null, 2)}\n`);
+    return true;
+}
+export async function readReplacementPins() {
+    return (await readDecisions()).replacementPins;
+}
+export function formatFreshnessAlerts(alerts) {
+    const visible = alerts.filter((alert) => !alert.ignored);
+    if (!visible.length)
+        return alerts.length
+            ? "No unignored freshness alerts."
+            : "No freshness or replacement alert is supported by current evidence.";
+    return [
+        `Freshness alerts: ${visible.length}`,
+        ...visible.flatMap((alert) => [
+            `${alert.severity === "critical" ? "✗" : alert.severity === "warning" ? "!" : "•"} ${alert.id}: ${alert.packageId} — ${alert.message}`,
+            `  Evidence: ${alert.evidence.join("; ")}`,
+            `  Actions: ${alert.actions.join(" | ")}`,
+        ]),
+    ].join("\n");
+}

package/dist/src/core/github-discovery.js

@@ -0,0 +1,97 @@
+/** A rolling window prevents the default discovery query from aging in place. */
+export function defaultGitHubDiscoveryQuery(now = new Date()) {
+    return defaultGitHubDiscoveryQueries(now)[0];
+}
+/**
+ * GitHub repository search does not interpret parenthesized topic OR clauses
+ * as three independent topic searches. Keep the built-in sweep broad with a
+ * small number of valid queries, then merge them deterministically.
+ */
+export function defaultGitHubDiscoveryQueries(now = new Date()) {
+    const start = new Date(now.getTime() - 180 * 86_400_000)
+        .toISOString()
+        .slice(0, 10);
+    return ["mcp", "ai-agent", "agent-skills"].map((topic) => `topic:${topic} created:>=${start}`);
+}
+/** Search public GitHub repositories through the documented REST API. */
+export async function discoverGitHubRepositories(options) {
+    if (options.query !== undefined && options.queries !== undefined)
+        throw new Error("GitHub discovery accepts either query or queries, not both");
+    const queries = (options.queries ??
+        (options.query === undefined
+            ? defaultGitHubDiscoveryQueries()
+            : [options.query]))
+        .map((query) => query.trim())
+        .filter(Boolean);
+    if (!queries.length)
+        throw new Error("GitHub discovery requires a non-empty query");
+    const limit = Math.max(1, Math.min(options.limit ?? 20, 100));
+    const token = options.token ?? process.env.GITHUB_TOKEN;
+    const headers = {
+        accept: "application/vnd.github+json",
+        "user-agent": "loadout-discovery",
+    };
+    if (token)
+        headers.authorization = `Bearer ${token}`;
+    const leads = [];
+    for (const query of queries) {
+        const params = new URLSearchParams({
+            q: query,
+            sort: "stars",
+            order: "desc",
+            per_page: String(limit),
+        });
+        const response = await (options.fetcher ?? fetch)(`https://api.github.com/search/repositories?${params}`, { headers });
+        if (!response.ok) {
+            const remaining = response.headers.get("x-ratelimit-remaining");
+            const reset = response.headers.get("x-ratelimit-reset");
+            const retryAfter = response.headers.get("retry-after");
+            const resetAt = reset && /^\d+$/.test(reset)
+                ? new Date(Number(reset) * 1000).toISOString()
+                : undefined;
+            throw new Error(`GitHub repository discovery failed (${response.status})${remaining === "0" ? `; rate limit exhausted${resetAt ? ` until ${resetAt}` : ""}` : retryAfter ? `; retry after ${retryAfter} second(s)` : ""}`);
+        }
+        const value = await response.json();
+        if (!value || typeof value !== "object")
+            throw new Error("GitHub repository discovery response is invalid");
+        const items = value.items;
+        if (!Array.isArray(items))
+            throw new Error("GitHub discovery items are invalid");
+        leads.push(...items.flatMap((item) => {
+            if (!item || typeof item !== "object")
+                return [];
+            const record = item;
+            if (typeof record.full_name !== "string" ||
+                typeof record.html_url !== "string")
+                return [];
+            return [
+                {
+                    source: "github-search",
+                    repository: record.full_name,
+                    title: record.full_name,
+                    description: typeof record.description === "string" ? record.description : "",
+                    url: record.html_url,
+                    stars: typeof record.stargazers_count === "number"
+                        ? record.stargazers_count
+                        : 0,
+                    forks: typeof record.forks_count === "number" ? record.forks_count : 0,
+                    createdAt: typeof record.created_at === "string" ? record.created_at : "",
+                    updatedAt: typeof record.updated_at === "string" ? record.updated_at : "",
+                    query,
+                },
+            ];
+        }));
+    }
+    const unique = new Map();
+    for (const lead of leads) {
+        const key = lead.repository.toLowerCase();
+        const existing = unique.get(key);
+        if (!existing || lead.stars > existing.stars)
+            unique.set(key, lead);
+    }
+    return [...unique.values()]
+        .sort((a, b) => b.stars - a.stars ||
+        b.forks - a.forks ||
+        a.repository.localeCompare(b.repository))
+        .slice(0, limit);
+}

package/dist/src/core/github.js

@@ -0,0 +1,148 @@
+import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { loadoutHome } from "./paths.js";
+function normalizeRepository(input) {
+    const value = input
+        .trim()
+        .replace(/^https?:\/\/github\.com\//i, "")
+        .replace(/\.git$/, "")
+        .replace(/\/$/, "");
+    if (!/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(value))
+        throw new Error(`Invalid GitHub repository: ${input}`);
+    return value;
+}
+function cachePath(repository) {
+    return join(loadoutHome(), "cache", "github-metadata", `${repository.replace("/", "__")}.json`);
+}
+function releaseCachePath(repository) {
+    return join(loadoutHome(), "cache", "github-releases", `${repository.replace("/", "__")}.json`);
+}
+async function readCache(path) {
+    try {
+        return JSON.parse(await readFile(path, "utf8"));
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Fetches real repository metadata from GitHub, with a local cache and stale fallback. */
+export async function fetchGitHubMetadata(input, options = {}) {
+    const repository = normalizeRepository(input);
+    const path = cachePath(repository);
+    const cached = await readCache(path);
+    const maxAgeMs = options.maxAgeMs ?? 6 * 60 * 60 * 1000;
+    if (cached &&
+        !options.forceRefresh &&
+        Date.now() - Date.parse(cached.fetchedAt) < maxAgeMs)
+        return cached;
+    const fetcher = options.fetcher ?? fetch;
+    const headers = {
+        accept: "application/vnd.github+json",
+        "user-agent": "loadout-discovery",
+    };
+    if (process.env.GITHUB_TOKEN)
+        headers.authorization = `Bearer ${process.env.GITHUB_TOKEN}`;
+    let response;
+    try {
+        response = await fetcher(`https://api.github.com/repos/${repository}`, {
+            headers,
+        });
+    }
+    catch (error) {
+        if (cached)
+            return cached;
+        throw new Error(`Unable to reach GitHub for ${repository}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (!response.ok) {
+        const rateLimited = response.status === 403 || response.status === 429;
+        if (cached)
+            return cached;
+        throw new Error(`GitHub metadata request failed (${response.status}${rateLimited ? ", rate limit exceeded" : ""}) for ${repository}`);
+    }
+    const value = (await response.json());
+    const metadata = {
+        repository,
+        stars: typeof value.stargazers_count === "number" ? value.stargazers_count : 0,
+        description: typeof value.description === "string" ? value.description : "",
+        defaultBranch: typeof value.default_branch === "string" ? value.default_branch : "main",
+        topics: Array.isArray(value.topics)
+            ? value.topics.filter((topic) => typeof topic === "string")
+            : [],
+        openIssues: typeof value.open_issues_count === "number" ? value.open_issues_count : 0,
+        archived: value.archived === true,
+        lastUpdatedAt: typeof value.updated_at === "string"
+            ? value.updated_at
+            : new Date().toISOString(),
+        pushedAt: typeof value.pushed_at === "string" ? value.pushed_at : null,
+        fetchedAt: new Date().toISOString(),
+    };
+    await mkdir(join(loadoutHome(), "cache", "github-metadata"), {
+        recursive: true,
+    });
+    const temporary = `${path}.${process.pid}.tmp`;
+    await writeFile(temporary, JSON.stringify(metadata, null, 2), "utf8");
+    await rename(temporary, path);
+    return metadata;
+}
+/**
+ * Read the latest public GitHub release and aggregate its asset downloads.
+ * Repositories without releases return explicit null/zero values. Drafts are
+ * never exposed by GitHub's public release listing.
+ */
+export async function fetchGitHubReleaseMetadata(input, options = {}) {
+    const repository = normalizeRepository(input);
+    const path = releaseCachePath(repository);
+    const cached = await readCache(path);
+    const maxAgeMs = options.maxAgeMs ?? 6 * 60 * 60 * 1000;
+    if (cached &&
+        !options.forceRefresh &&
+        Date.now() - Date.parse(cached.fetchedAt) < maxAgeMs)
+        return cached;
+    const fetcher = options.fetcher ?? fetch;
+    const headers = {
+        accept: "application/vnd.github+json",
+        "user-agent": "loadout-discovery",
+    };
+    if (process.env.GITHUB_TOKEN)
+        headers.authorization = `Bearer ${process.env.GITHUB_TOKEN}`;
+    let response;
+    try {
+        response = await fetcher(`https://api.github.com/repos/${repository}/releases?per_page=1`, { headers });
+    }
+    catch (error) {
+        if (cached)
+            return cached;
+        throw new Error(`Unable to reach GitHub releases for ${repository}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (!response.ok) {
+        if (cached)
+            return cached;
+        throw new Error(`GitHub release request failed (${response.status}) for ${repository}`);
+    }
+    const releases = (await response.json());
+    const release = Array.isArray(releases) ? releases[0] : undefined;
+    const record = release && typeof release === "object" ? release : {};
+    const assets = Array.isArray(record.assets)
+        ? record.assets
+        : [];
+    const metadata = {
+        tag: typeof record.tag_name === "string"
+            ? record.tag_name
+            : null,
+        publishedAt: typeof record.published_at === "string"
+            ? record.published_at
+            : null,
+        downloadCount: assets.reduce((total, asset) => total +
+            (typeof asset.download_count === "number" && asset.download_count >= 0
+                ? asset.download_count
+                : 0), 0),
+        fetchedAt: new Date().toISOString(),
+    };
+    await mkdir(join(loadoutHome(), "cache", "github-releases"), {
+        recursive: true,
+    });
+    const temporary = `${path}.${process.pid}.tmp`;
+    await writeFile(temporary, JSON.stringify(metadata, null, 2), "utf8");
+    await rename(temporary, path);
+    return metadata;
+}