loadout-ai 0.1.0

package/dist/src/core/skill-security.js

@@ -0,0 +1,340 @@
+import { createHash } from "node:crypto";
+import { lstat, readFile, readdir } from "node:fs/promises";
+import { basename, extname, join, relative, resolve, sep } from "node:path";
+const DEFAULT_MAX_FILES = 500;
+const DEFAULT_MAX_TOTAL_BYTES = 10_000_000;
+const DEFAULT_MAX_FILE_BYTES = 2_000_000;
+const SCRIPT_EXTENSIONS = new Set([
+    ".bat",
+    ".cmd",
+    ".fish",
+    ".js",
+    ".mjs",
+    ".cjs",
+    ".pl",
+    ".ps1",
+    ".py",
+    ".rb",
+    ".sh",
+    ".ts",
+    ".zsh",
+]);
+const DEPENDENCY_MANIFESTS = new Set([
+    "cargo.toml",
+    "composer.json",
+    "gemfile",
+    "go.mod",
+    "package.json",
+    "pipfile",
+    "pyproject.toml",
+    "requirements.txt",
+]);
+const UNICODE_CONTROL_PATTERN = /[\u061c\u200b-\u200f\u202a-\u202e\u2060-\u2069\ufeff]/u;
+const DOMAIN_PATTERN = /\bhttps?:\/\/([^\s/:'"`<>)}\]]+)/giu;
+const ENV_PATTERNS = [
+    /process\.env\.([A-Z_][A-Z0-9_]*)/g,
+    /process\.env\[['"]([A-Z_][A-Z0-9_]*)['"]\]/g,
+    /\$\{([A-Z_][A-Z0-9_]*)\}|\$([A-Z_][A-Z0-9_]*)/g,
+    /\b(?:environment|env(?:ironment)? variable)\s+([A-Z_][A-Z0-9_]*)/gi,
+];
+const REMOTE_INSTRUCTION_PATTERN = /(?:curl|wget|invoke-webrequest)\s+[^\n]*(?:\||>|-o\b)|(?:read|fetch|load|follow)\s+(?:the\s+)?instructions?\s+(?:at|from)\s+https?:\/\//i;
+const INJECTION_PATTERN = /\b(?:ignore|disregard|override)\b.{0,60}\b(?:previous|prior|system|developer|security|safety)\b.{0,30}\binstructions?\b/gi;
+const EXFILTRATION_PATTERN = /\b(?:send|post|upload|exfiltrate|transmit)\b.{0,100}\b(?:credentials?|secrets?|tokens?|api[_ -]?keys?|private keys?|\.ssh|\.aws|environment variables?)\b/gi;
+function digest(content) {
+    return createHash("sha256").update(content).digest("hex");
+}
+function normalizedPath(root, path) {
+    return relative(root, path).split(sep).join("/") || ".";
+}
+function finding(id, severity, category, message, paths, names) {
+    return {
+        id,
+        scanner: "deterministic",
+        severity,
+        category,
+        message,
+        paths: [...new Set(paths)].sort(),
+        ...(names?.length ? { names: [...new Set(names)].sort() } : {}),
+    };
+}
+function parseFrontmatter(content) {
+    const normalized = content.replace(/\r\n/g, "\n");
+    if (!normalized.startsWith("---\n"))
+        return { values: new Map(), body: normalized, valid: false };
+    const close = normalized.indexOf("\n---\n", 4);
+    if (close < 0)
+        return { values: new Map(), body: "", valid: false };
+    const values = new Map();
+    for (const line of normalized.slice(4, close).split("\n")) {
+        const match = line.match(/^([a-zA-Z][a-zA-Z0-9_-]*):\s*(.*?)\s*$/);
+        if (match)
+            values.set(match[1].toLowerCase(), match[2].replace(/^['"]|['"]$/g, ""));
+    }
+    return { values, body: normalized.slice(close + 5), valid: true };
+}
+function dependencyNames(path, content) {
+    const name = basename(path).toLowerCase();
+    if (name === "package.json" || name === "composer.json") {
+        try {
+            const parsed = JSON.parse(content);
+            const sections = [
+                "dependencies",
+                "devDependencies",
+                "optionalDependencies",
+                "require",
+            ];
+            return sections.flatMap((section) => {
+                const value = parsed[section];
+                return value && typeof value === "object" && !Array.isArray(value)
+                    ? Object.keys(value)
+                    : [];
+            });
+        }
+        catch {
+            return [];
+        }
+    }
+    if (name === "requirements.txt")
+        return content
+            .split(/\r?\n/)
+            .map((line) => line.trim().match(/^([A-Za-z0-9_.-]+)/)?.[1])
+            .filter((value) => Boolean(value));
+    return [];
+}
+function disagreementKey(item) {
+    return `${item.category}:${[...item.paths].sort().join(",")}`;
+}
+function compareFindings(deterministic, assisted) {
+    const left = new Map(deterministic.map((item) => [disagreementKey(item), item]));
+    const right = new Map(assisted.map((item) => [disagreementKey(item), item]));
+    const result = [];
+    for (const [key, item] of left) {
+        const other = right.get(key);
+        if (!other)
+            result.push({
+                key,
+                kind: "deterministic-only",
+                deterministicSeverity: item.severity,
+            });
+        else if (item.severity !== other.severity)
+            result.push({
+                key,
+                kind: "severity-mismatch",
+                deterministicSeverity: item.severity,
+                assistedSeverity: other.severity,
+            });
+    }
+    for (const [key, item] of right)
+        if (!left.has(key))
+            result.push({
+                key,
+                kind: "assisted-only",
+                assistedSeverity: item.severity,
+            });
+    return result.sort((a, b) => a.key.localeCompare(b.key));
+}
+function hasUnnegatedMatch(content, pattern) {
+    pattern.lastIndex = 0;
+    for (const match of content.matchAll(pattern)) {
+        const before = content.slice(Math.max(0, (match.index ?? 0) - 32), match.index);
+        if (!/(?:\bnever|\bdo not|\bdon't|\bmust not|\bshould not)\s*$/i.test(before))
+            return true;
+    }
+    return false;
+}
+/**
+ * Inspect an Agent Skill without executing it. Output contains hashes, paths and
+ * capability names only; instruction text and credential values never leave the scanner.
+ */
+export async function scanSkillSecurity(skillRoot, options = {}) {
+    const root = resolve(skillRoot);
+    const rootStat = await lstat(root);
+    if (!rootStat.isDirectory() || rootStat.isSymbolicLink())
+        throw new Error(`Skill path must be a real directory: ${skillRoot}`);
+    const maxFiles = options.maxFiles ?? DEFAULT_MAX_FILES;
+    const maxTotalBytes = options.maxTotalBytes ?? DEFAULT_MAX_TOTAL_BYTES;
+    const maxFileBytes = options.maxFileBytes ?? DEFAULT_MAX_FILE_BYTES;
+    const inventory = [];
+    const contents = new Map();
+    const findings = [];
+    let totalBytes = 0;
+    async function visit(directory, depth) {
+        if (depth > 12) {
+            findings.push(finding("tree-depth", "high", "size", "Skill tree exceeds the bounded inspection depth.", [normalizedPath(root, directory)]));
+            return;
+        }
+        const entries = await readdir(directory, { withFileTypes: true });
+        for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+            const absolute = join(directory, entry.name);
+            const path = normalizedPath(root, absolute);
+            const info = await lstat(absolute);
+            if (info.isSymbolicLink()) {
+                findings.push(finding("symlink", "critical", "symlink", "Symlinks are not permitted inside a reviewed skill.", [path]));
+                continue;
+            }
+            if (info.isDirectory()) {
+                await visit(absolute, depth + 1);
+                continue;
+            }
+            if (!info.isFile())
+                continue;
+            if (inventory.length >= maxFiles)
+                throw new Error(`Skill exceeds inspection file limit (${maxFiles})`);
+            if (info.size > maxFileBytes)
+                throw new Error(`Skill file exceeds inspection byte limit: ${path}`);
+            totalBytes += info.size;
+            if (totalBytes > maxTotalBytes)
+                throw new Error(`Skill exceeds inspection byte limit (${maxTotalBytes})`);
+            const content = await readFile(absolute);
+            const text = content.toString("utf8");
+            const lowerName = entry.name.toLowerCase();
+            const manifest = DEPENDENCY_MANIFESTS.has(lowerName);
+            const script = SCRIPT_EXTENSIONS.has(extname(entry.name).toLowerCase()) ||
+                path.startsWith("scripts/") ||
+                text.startsWith("#!");
+            const executable = (info.mode & 0o111) !== 0 || text.startsWith("#!");
+            inventory.push({
+                path,
+                bytes: info.size,
+                sha256: digest(content),
+                kind: path === "SKILL.md"
+                    ? "instruction"
+                    : manifest
+                        ? "dependency-manifest"
+                        : script
+                            ? "script"
+                            : "asset",
+                executable,
+            });
+            contents.set(path, text);
+        }
+    }
+    await visit(root, 0);
+    const skillText = contents.get("SKILL.md");
+    if (skillText === undefined)
+        findings.push(finding("skill-file", "critical", "specification", "SKILL.md is required.", ["SKILL.md"]));
+    const parsed = parseFrontmatter(skillText ?? "");
+    const name = parsed.values.get("name");
+    const description = parsed.values.get("description") ?? "";
+    const compatibility = parsed.values.get("compatibility") ?? "";
+    if (!parsed.valid)
+        findings.push(finding("frontmatter", "critical", "specification", "SKILL.md must contain closed YAML frontmatter.", ["SKILL.md"]));
+    if (!name || name.length > 64 || !/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(name))
+        findings.push(finding("name", "critical", "specification", "Skill name must be 1-64 lowercase letters, numbers, or single hyphens.", ["SKILL.md"]));
+    if (name && name !== basename(root))
+        findings.push(finding("directory-name", "medium", "specification", "Skill name does not match its parent directory.", ["SKILL.md"]));
+    if (!description || description.length > 1024)
+        findings.push(finding("description", "critical", "specification", "Skill description must contain 1-1024 characters.", ["SKILL.md"]));
+    if (compatibility.length > 500)
+        findings.push(finding("compatibility", "high", "specification", "Compatibility metadata exceeds 500 characters.", ["SKILL.md"]));
+    const lineCount = (skillText ?? "").split(/\r?\n/).length;
+    if (lineCount > 500)
+        findings.push(finding("progressive-disclosure", "medium", "size", "SKILL.md exceeds the recommended 500-line progressive-disclosure boundary.", ["SKILL.md"]));
+    const domains = new Set();
+    const envNames = new Set();
+    const executableFiles = [];
+    const dependencyManifests = [];
+    const dependencies = new Set();
+    for (const item of inventory) {
+        const text = contents.get(item.path) ?? "";
+        DOMAIN_PATTERN.lastIndex = 0;
+        for (const match of text.matchAll(DOMAIN_PATTERN))
+            if (match[1])
+                domains.add(match[1].toLowerCase());
+        for (const pattern of ENV_PATTERNS) {
+            pattern.lastIndex = 0;
+            for (const match of text.matchAll(pattern)) {
+                const envName = (match[1] ?? match[2] ?? "").toUpperCase();
+                if (envName)
+                    envNames.add(envName);
+            }
+        }
+        if (item.kind === "script" || item.executable)
+            executableFiles.push(item.path);
+        if (item.kind === "dependency-manifest") {
+            dependencyManifests.push(item.path);
+            for (const dependency of dependencyNames(item.path, text))
+                dependencies.add(dependency);
+        }
+        if (UNICODE_CONTROL_PATTERN.test(text))
+            findings.push(finding(`unicode:${item.path}`, "critical", "unicode-control", "File contains invisible or bidirectional Unicode controls.", [item.path]));
+        if (REMOTE_INSTRUCTION_PATTERN.test(text))
+            findings.push(finding(`remote:${item.path}`, "high", "remote-instruction", "Instructions load or execute mutable remote content.", [item.path]));
+        if (hasUnnegatedMatch(text, INJECTION_PATTERN))
+            findings.push(finding(`injection:${item.path}`, "critical", "prompt-injection", "Instructions attempt to override higher-priority or safety instructions.", [item.path]));
+        if (hasUnnegatedMatch(text, EXFILTRATION_PATTERN))
+            findings.push(finding(`exfiltration:${item.path}`, "critical", "exfiltration", "Instructions appear to transmit credential or secret material.", [item.path]));
+    }
+    if (executableFiles.length)
+        findings.push(finding("executables", "high", "executable", "Skill contains executable or script content that requires explicit review.", executableFiles));
+    if (dependencyManifests.length)
+        findings.push(finding("dependencies", "high", "dependency", "Skill declares external dependencies that require provenance review.", dependencyManifests, [...dependencies]));
+    if (domains.size)
+        findings.push(finding("domains", "high", "domain", "Skill references network domains that require explicit approval.", inventory
+            .filter((item) => [...domains].some((domain) => (contents.get(item.path) ?? "").toLowerCase().includes(domain)))
+            .map((item) => item.path), [...domains]));
+    if (envNames.size)
+        findings.push(finding("environment", "high", "environment", "Skill references environment-variable names; values were not read.", inventory
+            .filter((item) => [...envNames].some((envName) => (contents.get(item.path) ?? "").includes(envName)))
+            .map((item) => item.path), [...envNames]));
+    const declaredTools = (parsed.values.get("allowed-tools") ?? "")
+        .split(/\s+/)
+        .filter(Boolean);
+    if ((executableFiles.length || domains.size || envNames.size) &&
+        declaredTools.length === 0 &&
+        !compatibility)
+        findings.push(finding("capability-declaration", "medium", "capability", "Executable, network, or environment capabilities are not declared in frontmatter.", ["SKILL.md"]));
+    const deterministicFindings = findings.sort((a, b) => a.id.localeCompare(b.id));
+    const assistedFindings = (options.assistedFindings ?? []).map((item) => ({
+        ...item,
+        scanner: "assisted",
+    }));
+    const filesSorted = inventory.sort((a, b) => a.path.localeCompare(b.path));
+    const treeHash = digest(filesSorted
+        .map((item) => `${item.path}\0${item.bytes}\0${item.sha256}`)
+        .join("\n"));
+    const verdict = deterministicFindings.some((item) => item.severity === "critical")
+        ? "blocked"
+        : deterministicFindings.some((item) => item.severity === "high" || item.severity === "medium") || assistedFindings.length
+            ? "review-required"
+            : "pass";
+    return {
+        schemaVersion: 1,
+        policy: "agent-skills-security-v1",
+        rootName: basename(root),
+        specification: {
+            ...(name ? { name } : {}),
+            descriptionPresent: Boolean(description),
+            lineCount,
+            progressiveDisclosureRecommended: lineCount <= 500,
+        },
+        inventory: {
+            files: filesSorted,
+            totalFiles: filesSorted.length,
+            totalBytes,
+            treeHash,
+        },
+        capabilities: {
+            declaredTools,
+            executableFiles: executableFiles.sort(),
+            dependencyManifests: dependencyManifests.sort(),
+            dependencyNames: [...dependencies].sort(),
+            domains: [...domains].sort(),
+            environmentNames: [...envNames].sort(),
+        },
+        deterministicFindings,
+        assistedFindings,
+        disagreements: compareFindings(deterministicFindings, assistedFindings),
+        verdict,
+        limitations: [
+            "Static inspection cannot prove runtime safety or task quality.",
+            "Assisted findings are annotations and cannot clear a deterministic critical finding.",
+            "Dependency names are inventory evidence, not license or vulnerability approval.",
+        ],
+    };
+}
+export function assertSkillSecurity(report) {
+    const critical = report.deterministicFindings.filter((item) => item.severity === "critical");
+    if (critical.length)
+        throw new Error(`Skill security validation failed: ${critical.map((item) => item.id).join(", ")}`);
+}

package/dist/src/core/skills-sh-discovery.js

@@ -0,0 +1,336 @@
+import { join } from "node:path";
+import { ConnectorRequestError, fetchBoundedJson, rateLimitFromHeaders, readDiscoveryConnectorCache, writeDiscoveryConnectorCache, } from "./discovery-connector.js";
+import { loadoutHome } from "./paths.js";
+const SOURCE = "skills-sh";
+const API = "https://skills.sh/api/v1/skills";
+const ATTRIBUTION = "https://skills.sh/docs/api";
+const REPOSITORY_LIMITATION = "skills.sh leaderboard metadata identifies a mutable GitHub repository but supplies no Git commit; Loadout must resolve and inspect an immutable commit before review or installation.";
+function isRecord(value) {
+    return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}
+function safeInteger(value, options = {}) {
+    return (typeof value === "number" &&
+        Number.isSafeInteger(value) &&
+        (options.signed || value >= 0));
+}
+function boundedString(value, maximum, options = {}) {
+    return (typeof value === "string" &&
+        value.length <= maximum &&
+        (options.empty || value.length > 0) &&
+        !/[\0\r\n]/.test(value));
+}
+function githubRepository(value) {
+    const normalized = value.replace(/\.git$/i, "").replace(/\/$/, "");
+    return /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(normalized)
+        ? normalized
+        : undefined;
+}
+function validHttpsUrl(value, origin) {
+    try {
+        const url = new URL(value);
+        return (url.protocol === "https:" &&
+            !url.username &&
+            !url.password &&
+            (!origin || url.origin === origin));
+    }
+    catch {
+        return false;
+    }
+}
+function rankingMeaning(view) {
+    if (view === "all-time")
+        return "skills.sh all-time leaderboard position and total deduplicated installs";
+    if (view === "trending")
+        return "skills.sh recent-growth leaderboard position; installs remains a total install count, not a growth rate";
+    return "skills.sh hot leaderboard position; change compares the current hour with the same hour yesterday";
+}
+function normalizeSkill(value, view, position, observedAt) {
+    if (!isRecord(value))
+        return undefined;
+    const { id, slug, name, source, installs, sourceType, installUrl, url, isDuplicate, installsYesterday, change, } = value;
+    if (!boundedString(id, 512) ||
+        !boundedString(slug, 200) ||
+        !boundedString(name, 300) ||
+        !boundedString(source, 300) ||
+        id !== `${source}/${slug}` ||
+        !safeInteger(installs) ||
+        (sourceType !== "github" && sourceType !== "well-known") ||
+        (installUrl !== null && !boundedString(installUrl, 2_048)) ||
+        !boundedString(url, 2_048) ||
+        !validHttpsUrl(url, "https://skills.sh") ||
+        (isDuplicate !== undefined && typeof isDuplicate !== "boolean") ||
+        (installsYesterday !== undefined && !safeInteger(installsYesterday)) ||
+        (change !== undefined && !safeInteger(change, { signed: true })))
+        return undefined;
+    let repository;
+    let repositoryKey;
+    if (sourceType === "github") {
+        const normalized = githubRepository(source);
+        if (!normalized ||
+            typeof installUrl !== "string" ||
+            !validHttpsUrl(installUrl, "https://github.com"))
+            return undefined;
+        const installPath = new URL(installUrl).pathname
+            .replace(/^\//, "")
+            .replace(/\.git$/i, "")
+            .replace(/\/$/, "");
+        if (installPath.toLowerCase() !== normalized.toLowerCase())
+            return undefined;
+        repository = {
+            repository: normalized,
+            url: `https://github.com/${normalized}`,
+            immutable: false,
+            limitation: REPOSITORY_LIMITATION,
+        };
+        repositoryKey = `github:${normalized.toLowerCase()}`;
+    }
+    else if (installUrl !== null && !validHttpsUrl(installUrl))
+        return undefined;
+    return {
+        source: SOURCE,
+        kind: "skill",
+        identityKey: `skills-sh:${id.toLowerCase()}`,
+        ...(repositoryKey ? { repositoryKey } : {}),
+        externalId: id,
+        slug,
+        name,
+        sourceName: source,
+        sourceType,
+        installUrl,
+        sourceUrl: url,
+        installs,
+        isDuplicate: isDuplicate ?? false,
+        ...(repository ? { repository } : {}),
+        ranking: {
+            provider: "skills.sh",
+            view,
+            position,
+            installs,
+            ...(installsYesterday !== undefined ? { installsYesterday } : {}),
+            ...(change !== undefined ? { change } : {}),
+            meaning: rankingMeaning(view),
+            uncertainty: "Anonymous install telemetry is an adoption signal only; it is not safety, quality, compatibility, or performance evidence.",
+        },
+        attribution: {
+            source: SOURCE,
+            sourceUrl: ATTRIBUTION,
+            observedAt,
+            meaning: "Metadata and leaderboard order reported by skills.sh; Loadout did not install or execute the skill.",
+        },
+    };
+}
+function parsePage(value, expectedPage, pageSize) {
+    if (!isRecord(value) ||
+        !Array.isArray(value.data) ||
+        !isRecord(value.pagination))
+        throw new Error("skills.sh response envelope is invalid");
+    const page = value.pagination.page;
+    const perPage = value.pagination.perPage;
+    const total = value.pagination.total;
+    const hasMore = value.pagination.hasMore;
+    if (page !== expectedPage ||
+        !safeInteger(perPage) ||
+        perPage < 1 ||
+        perPage > 500 ||
+        !safeInteger(total) ||
+        typeof hasMore !== "boolean" ||
+        value.data.length > pageSize)
+        throw new Error("skills.sh pagination metadata is invalid");
+    return { data: value.data, hasMore, total };
+}
+export function isSkillsShDiscoveryRecord(value) {
+    if (!isRecord(value))
+        return false;
+    const record = value;
+    return (record.source === SOURCE &&
+        record.kind === "skill" &&
+        boundedString(record.identityKey, 1_024) &&
+        boundedString(record.externalId, 512) &&
+        boundedString(record.slug, 200) &&
+        boundedString(record.name, 300) &&
+        boundedString(record.sourceName, 300) &&
+        (record.sourceType === "github" || record.sourceType === "well-known") &&
+        safeInteger(record.installs) &&
+        typeof record.isDuplicate === "boolean" &&
+        boundedString(record.sourceUrl, 2_048) &&
+        isRecord(record.ranking) &&
+        isRecord(record.attribution) &&
+        record.attribution.source === SOURCE &&
+        boundedString(record.attribution.observedAt, 64) &&
+        Number.isFinite(Date.parse(record.attribution.observedAt)));
+}
+function issueFromError(error, page) {
+    if (error instanceof ConnectorRequestError) {
+        return {
+            code: error.status === 401
+                ? "authentication-required"
+                : error.status === 429
+                    ? "rate-limited"
+                    : "request-failed",
+            message: `skills.sh page ${page} failed: ${error.message}`,
+            page,
+            ...(error.retryAfterSeconds !== undefined
+                ? { retryAfterSeconds: error.retryAfterSeconds }
+                : {}),
+        };
+    }
+    return {
+        code: "invalid-response",
+        message: `skills.sh page ${page} was invalid: ${error instanceof Error ? error.message : String(error)}`,
+        page,
+    };
+}
+async function cachedOrUnavailable(cachePath, fetchedAt, issues) {
+    const cachedPath = cachePath === false ? undefined : cachePath;
+    const cache = cachedPath === undefined
+        ? undefined
+        : await readDiscoveryConnectorCache(cachedPath, SOURCE, isSkillsShDiscoveryRecord);
+    return cache
+        ? {
+            source: SOURCE,
+            status: "cached",
+            fetchedAt,
+            records: cache.records,
+            pagesFetched: 0,
+            issues,
+            cache: { path: cachedPath, cachedAt: cache.cachedAt },
+        }
+        : {
+            source: SOURCE,
+            status: "unavailable",
+            fetchedAt,
+            records: [],
+            pagesFetched: 0,
+            issues,
+        };
+}
+/**
+ * Read the authenticated skills.sh leaderboard. Candidate files are never
+ * downloaded; output remains metadata-only and requires later immutable review.
+ */
+export async function discoverSkillsSh(options = {}) {
+    const now = options.now ?? new Date();
+    const fetchedAt = now.toISOString();
+    const view = options.view ?? "trending";
+    const pageSize = Math.max(1, Math.min(options.pageSize ?? 100, 100));
+    const maxPages = Math.max(1, Math.min(options.maxPages ?? 5, 10));
+    const maxRecords = Math.max(1, Math.min(options.maxRecords ?? 500, 1_000));
+    const cachePath = options.cachePath === false
+        ? false
+        : (options.cachePath ??
+            join(loadoutHome(), "discovery-cache", `skills-sh-${view}.json`));
+    const token = (options.token ?? process.env.VERCEL_OIDC_TOKEN)?.trim();
+    if (!token || /[\0\r\n]/.test(token))
+        return cachedOrUnavailable(cachePath, fetchedAt, [
+            {
+                code: "authentication-required",
+                message: "skills.sh requires a request-scoped Vercel OIDC token; set VERCEL_OIDC_TOKEN or pass token without persisting it",
+            },
+        ]);
+    const records = [];
+    const identities = new Set();
+    const issues = [];
+    let pagesFetched = 0;
+    let hasMore = true;
+    let nextPage;
+    let stoppedByFailure = false;
+    let stoppedByRecordLimit = false;
+    let truncatedWithinPage = false;
+    let rateLimit;
+    for (let page = 0; page < maxPages && hasMore && records.length < maxRecords; page++) {
+        const url = new URL(API);
+        url.searchParams.set("view", view);
+        url.searchParams.set("page", String(page));
+        url.searchParams.set("per_page", String(pageSize));
+        try {
+            const response = await fetchBoundedJson(url.toString(), {
+                fetcher: options.fetcher,
+                timeoutMs: options.timeoutMs,
+                maximumBytes: 5 * 1024 * 1024,
+                headers: {
+                    accept: "application/json",
+                    authorization: `Bearer ${token}`,
+                    "user-agent": "loadout-ai-discovery",
+                },
+            });
+            pagesFetched++;
+            rateLimit = rateLimitFromHeaders(response.headers) ?? rateLimit;
+            const parsed = parsePage(response.value, page, pageSize);
+            hasMore = parsed.hasMore;
+            if (hasMore && parsed.data.length === 0)
+                throw new Error("skills.sh returned an empty page with hasMore=true");
+            for (const [index, value] of parsed.data.entries()) {
+                const normalized = normalizeSkill(value, view, page * pageSize + index + 1, fetchedAt);
+                if (!normalized) {
+                    issues.push({
+                        code: "invalid-record",
+                        message: `skills.sh page ${page} record ${index + 1} was skipped because it failed the bounded metadata schema`,
+                        page,
+                    });
+                    continue;
+                }
+                if (identities.has(normalized.identityKey)) {
+                    issues.push({
+                        code: "duplicate-record",
+                        message: `skills.sh repeated ${normalized.externalId}; the earliest leaderboard position was retained`,
+                        page,
+                    });
+                    continue;
+                }
+                identities.add(normalized.identityKey);
+                records.push(normalized);
+                if (records.length >= maxRecords) {
+                    truncatedWithinPage = index < parsed.data.length - 1;
+                    stoppedByRecordLimit = truncatedWithinPage || hasMore;
+                    break;
+                }
+            }
+            nextPage = hasMore && !truncatedWithinPage ? page + 1 : undefined;
+        }
+        catch (error) {
+            issues.push(issueFromError(error, page));
+            stoppedByFailure = true;
+            break;
+        }
+    }
+    if (!stoppedByFailure && stoppedByRecordLimit)
+        issues.push({
+            code: "pagination-limit",
+            message: `skills.sh pagination stopped at the configured ${maxRecords}-record limit${truncatedWithinPage ? "; no continuation is exposed because the limit was reached within a page" : ""}`,
+            ...(nextPage !== undefined ? { page: nextPage } : {}),
+        });
+    else if (!stoppedByFailure &&
+        hasMore &&
+        nextPage !== undefined &&
+        pagesFetched >= maxPages)
+        issues.push({
+            code: "pagination-limit",
+            message: `skills.sh pagination stopped at the configured ${maxPages}-page limit`,
+            page: nextPage,
+        });
+    if (!records.length && issues.length)
+        return cachedOrUnavailable(cachePath, fetchedAt, issues);
+    let status = issues.length ? "partial" : "complete";
+    if (status === "complete" && cachePath !== false) {
+        try {
+            await writeDiscoveryConnectorCache(cachePath, SOURCE, records, now);
+        }
+        catch (error) {
+            status = "partial";
+            issues.push({
+                code: "cache-write-failed",
+                message: `skills.sh metadata was fetched but its offline cache could not be written: ${error instanceof Error ? error.message : String(error)}`,
+            });
+        }
+    }
+    return {
+        source: SOURCE,
+        status,
+        fetchedAt,
+        records,
+        pagesFetched,
+        issues,
+        ...(nextPage !== undefined && hasMore ? { next: String(nextPage) } : {}),
+        ...(rateLimit ? { rateLimit } : {}),
+    };
+}