@repodeckhz/core 0.6.0

package/dist/index.cjs

@@ -0,0 +1,1096 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  Cache: () => Cache,
+  CardBuilder: () => CardBuilder,
+  GitHubClient: () => GitHubClient,
+  GraphQLClient: () => GraphQLClient,
+  RepoDeckError: () => RepoDeckError,
+  assignBentoSpans: () => assignBentoSpans,
+  buildCacheKey: () => buildCacheKey,
+  buildCardData: () => buildCardData,
+  buildRawUrl: () => buildRawUrl,
+  checkRateLimit: () => checkRateLimit,
+  clearCache: () => clearCache,
+  defaultPresets: () => defaultPresets,
+  fetchDirectoryListing: () => fetchDirectoryListing,
+  fetchFileContent: () => fetchFileContent,
+  fetchMultipleReposViaGraphQL: () => fetchMultipleReposViaGraphQL,
+  fetchRepoStats: () => fetchRepoStats,
+  getCached: () => getCached,
+  getPreset: () => getPreset,
+  listPresets: () => listPresets,
+  mergePresetWithUserConfig: () => mergePresetWithUserConfig,
+  parseReadme: () => parseReadme,
+  parseReadmeFrontmatter: () => parseReadmeFrontmatter,
+  parseResume: () => parseResume,
+  prefetchCardData: () => prefetchCardData,
+  registerPreset: () => registerPreset,
+  repodeckError: () => repodeckError,
+  resolveRadiusTokens: () => resolveRadiusTokens,
+  resolveScreenshotLayout: () => resolveScreenshotLayout,
+  resolveScreenshots: () => resolveScreenshots,
+  setCached: () => setCached,
+  validateConfig: () => validateConfig
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/errors.ts
+var RepoDeckError = class extends Error {
+  constructor(code, message, opts) {
+    super(message);
+    this.name = "RepoDeckError";
+    this.code = code;
+    if (opts?.status !== void 0) this.status = opts.status;
+    if (opts?.field !== void 0) this.field = opts.field;
+    if (opts?.cause !== void 0) this.cause = opts.cause;
+  }
+  toJSON() {
+    return {
+      name: this.name,
+      code: this.code,
+      message: this.message,
+      status: this.status,
+      field: this.field
+    };
+  }
+};
+var repodeckError = RepoDeckError;
+
+// src/cache.ts
+var DEFAULT_TTL_MS = 5 * 60 * 1e3;
+var Cache = class {
+  constructor(defaultTtlMs = DEFAULT_TTL_MS) {
+    this.defaultTtlMs = defaultTtlMs;
+    this.store = /* @__PURE__ */ new Map();
+  }
+  get(key) {
+    const entry = this.store.get(key);
+    if (!entry) return void 0;
+    if (Date.now() > entry.expiresAt) {
+      this.store.delete(key);
+      return void 0;
+    }
+    return entry.value;
+  }
+  set(key, value, ttlMs = this.defaultTtlMs) {
+    this.store.set(key, { value, expiresAt: Date.now() + ttlMs });
+  }
+  /** Returns the cached entry including its expiry (for introspection). */
+  getEntry(key) {
+    const entry = this.store.get(key);
+    if (!entry) return void 0;
+    if (Date.now() > entry.expiresAt) {
+      this.store.delete(key);
+      return void 0;
+    }
+    return entry;
+  }
+  delete(key) {
+    this.store.delete(key);
+  }
+  clear() {
+    this.store.clear();
+  }
+  get size() {
+    return this.store.size;
+  }
+  /** Builds a deterministic cache key from card request parameters. */
+  static buildKey(parts) {
+    return `rc:${parts.owner}/${parts.repo}@${parts.branch}:${parts.configPath}:${parts.include}`;
+  }
+};
+var sharedCache = new Cache();
+function getCached(key) {
+  return sharedCache.getEntry(key);
+}
+function setCached(key, value, ttlMs = DEFAULT_TTL_MS) {
+  sharedCache.set(key, value, ttlMs);
+}
+function clearCache(key) {
+  if (key) sharedCache.delete(key);
+  else sharedCache.clear();
+}
+function buildCacheKey(parts) {
+  return Cache.buildKey(parts);
+}
+
+// src/presets.ts
+var defaultPresets = {
+  /** title + 1 screenshot cover */
+  minimal: {
+    include: { readme: false, resume: false, screenshots: true },
+    readmePreview: false,
+    showTitle: true
+  },
+  /** title + resume + screenshot cover */
+  standard: {
+    include: { readme: true, resume: true, screenshots: true },
+    readmePreview: false,
+    showTitle: true
+  },
+  /** title + resume + screenshots + README preview line */
+  detailed: {
+    include: { readme: true, resume: true, screenshots: true },
+    readmePreview: true,
+    readmePreviewChars: 140,
+    showTitle: true
+  }
+};
+var registry = new Map(Object.entries(defaultPresets));
+function registerPreset(name, definition) {
+  registry.set(name, definition);
+}
+function getPreset(name) {
+  const def = registry.get(name);
+  if (!def) {
+    throw new repodeckError(
+      "INVALID_CONFIG",
+      `Unknown preset "${name}". Available: ${[...registry.keys()].join(", ")}`
+    );
+  }
+  return def;
+}
+function listPresets() {
+  return [...registry.keys()];
+}
+function mergePresetWithUserConfig(preset, overrides, name = "custom") {
+  return {
+    name,
+    ...preset,
+    ...overrides,
+    include: { ...preset.include, ...overrides.include ?? {} }
+  };
+}
+
+// src/radius.ts
+var PRESET_VALUES = {
+  sharp: { card: "2px", button: "2px", modal: "2px" },
+  soft: { card: "12px", button: "8px", modal: "16px" },
+  round: { card: "22px", button: "999px", modal: "24px" }
+};
+function isPresetName(v) {
+  return v === "sharp" || v === "soft" || v === "round";
+}
+function looksLikeCssLength(v) {
+  return /^-?\d*\.?\d+(px|rem|em|%|vh|vw|vmin|vmax|ch|ex|pt|pc|in|cm|mm)?$/.test(v.trim());
+}
+function resolveRadiusTokens(radiusAttr) {
+  const trimmed = (radiusAttr ?? "").trim();
+  if (trimmed === "") return PRESET_VALUES.soft;
+  if (isPresetName(trimmed)) return PRESET_VALUES[trimmed];
+  if (looksLikeCssLength(trimmed)) {
+    return { card: trimmed, button: trimmed, modal: trimmed };
+  }
+  return PRESET_VALUES.soft;
+}
+
+// src/layout.ts
+function assignBentoSpans(count) {
+  if (count <= 0) return [];
+  if (count === 1) return [{ colSpan: 2, rowSpan: 2, hero: true }];
+  if (count === 2) {
+    return [
+      { colSpan: 2, rowSpan: 2, hero: true },
+      { colSpan: 2, rowSpan: 2, hero: false }
+    ];
+  }
+  if (count === 3) {
+    return [
+      { colSpan: 2, rowSpan: 2, hero: true },
+      { colSpan: 2, rowSpan: 1, hero: false },
+      { colSpan: 2, rowSpan: 1, hero: false }
+    ];
+  }
+  const spans = [
+    { colSpan: 2, rowSpan: 2, hero: true }
+  ];
+  for (let i = 1; i < count; i++) {
+    spans.push({ colSpan: 1, rowSpan: 1, hero: false });
+  }
+  return spans;
+}
+function resolveScreenshotLayout(screenshots, context) {
+  if (screenshots.length === 0) {
+    return { mode: "single", items: [], total: 0, hidden: 0 };
+  }
+  const total = screenshots.length;
+  if (context === "modal") {
+    if (total === 1) {
+      return {
+        mode: "single",
+        items: [{ screenshot: screenshots[0], colSpan: 1, rowSpan: 1, hero: true }],
+        total,
+        hidden: 0
+      };
+    }
+    const spans = assignBentoSpans(total);
+    return {
+      mode: "bento",
+      items: screenshots.map((s, i) => ({
+        screenshot: s,
+        colSpan: spans[i].colSpan,
+        rowSpan: spans[i].rowSpan,
+        hero: spans[i].hero
+      })),
+      total,
+      hidden: 0
+    };
+  }
+  const hidden = total - 1;
+  const items = [
+    { screenshot: screenshots[0], colSpan: 2, rowSpan: 2, hero: true }
+  ];
+  if (hidden > 0) items[0].overflow = hidden;
+  return { mode: "single", items, total, hidden };
+}
+
+// src/debug.ts
+function isDebugEnabled(flag) {
+  if (flag) return true;
+  const env = process.env.REPODECK_DEBUG;
+  return env === "1" || env === "true" || env === "TRUE" || env === "yes";
+}
+function dbgLog(enabled, scope, ...args) {
+  if (!enabled) return;
+  console.log(`[repodeck:${scope}]`, ...args);
+}
+
+// src/github-client.ts
+var API_BASE = "https://api.github.com";
+var GitHubClient = class _GitHubClient {
+  constructor(options = {}) {
+    this.token = options.token;
+    this.timeoutMs = options.timeoutMs ?? 12e3;
+    this.retries = options.retries ?? 2;
+    this.debug = isDebugEnabled(options.debug);
+  }
+  /** Creates a client from `FetchOptions` (backward-compatible with the old API). */
+  static from(options = {}) {
+    return new _GitHubClient(options);
+  }
+  headers() {
+    const h = {
+      Accept: "application/vnd.github+json",
+      "X-GitHub-Api-Version": "2022-11-28",
+      "User-Agent": "repodeck-core"
+    };
+    if (this.token) h.Authorization = `Bearer ${this.token}`;
+    return h;
+  }
+  /** Retry wrapper — only retries on network errors / 5xx, never on 404/401/403. */
+  async fetchWithRetry(url) {
+    const path = urlPath(url);
+    const started = Date.now();
+    let lastErr;
+    for (let attempt = 0; attempt <= this.retries; attempt++) {
+      const controller = new AbortController();
+      const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+      try {
+        const res = await fetch(url, { headers: this.headers(), signal: controller.signal });
+        clearTimeout(timer);
+        const ms = Date.now() - started;
+        const rate = res.headers.get("x-ratelimit-remaining") ? `${res.headers.get("x-ratelimit-remaining")}/${res.headers.get("x-ratelimit-limit")}` : "n/a";
+        if (res.status >= 500 && attempt < this.retries) {
+          dbgLog(this.debug, "http", `${path} \u2192 ${res.status} (retry ${attempt + 1}/${this.retries}) ${ms}ms rl=${rate}`);
+          await sleep(2 ** attempt * 250);
+          continue;
+        }
+        dbgLog(this.debug, "http", `${path} \u2192 ${res.status} ${ms}ms rl=${rate} attempt=${attempt + 1}`);
+        return res;
+      } catch (err) {
+        clearTimeout(timer);
+        lastErr = err;
+        const ms = Date.now() - started;
+        dbgLog(this.debug, "http", `${path} \u2192 network error after ${ms}ms (retry ${attempt + 1}/${this.retries})`);
+        if (attempt < this.retries) {
+          await sleep(2 ** attempt * 250);
+          continue;
+        }
+      }
+    }
+    throw new repodeckError("NETWORK_ERROR", `Network error fetching ${url}`, { cause: lastErr });
+  }
+  static decodeBase64(b64) {
+    const clean = b64.replace(/\n/g, "");
+    if (typeof Buffer !== "undefined") {
+      return Buffer.from(clean, "base64").toString("utf-8");
+    }
+    const binary = atob(clean);
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
+    return new TextDecoder().decode(bytes);
+  }
+  /** Fetches a single file's content. 404 → null (not an error). */
+  async fetchFileContent(owner, repo, path, ref) {
+    const url = `${API_BASE}/repos/${enc(owner)}/${enc(repo)}/contents/${enc(path)}?ref=${enc(ref ?? "main")}`;
+    const res = await this.fetchWithRetry(url);
+    if (res.status === 404) return null;
+    this.assertOk(res, path);
+    const data = await res.json();
+    if (data.encoding === "base64" && typeof data.content === "string") {
+      return _GitHubClient.decodeBase64(data.content);
+    }
+    return typeof data.content === "string" ? data.content : null;
+  }
+  /** Lists files in a directory. 404 → empty array. */
+  async fetchDirectoryListing(owner, repo, path, ref) {
+    const url = `${API_BASE}/repos/${enc(owner)}/${enc(repo)}/contents/${enc(path)}?ref=${enc(ref ?? "main")}`;
+    const res = await this.fetchWithRetry(url);
+    if (res.status === 404) return [];
+    this.assertOk(res, path);
+    const data = await res.json();
+    return data.filter((e) => e.type === "file").map((e) => ({ name: e.name, path: e.path, download_url: e.download_url, size: e.size }));
+  }
+  /** Fetches repo metadata and statistics in a single API call. */
+  async fetchRepoStats(owner, repo) {
+    const url = `${API_BASE}/repos/${enc(owner)}/${enc(repo)}`;
+    const res = await this.fetchWithRetry(url);
+    if (res.status === 404) {
+      throw new repodeckError("NOT_FOUND", `Repository ${owner}/${repo} not found.`, { status: 404 });
+    }
+    this.assertOk(res, "repo stats");
+    const data = await res.json();
+    return {
+      stars: data.stargazers_count ?? 0,
+      forks: data.forks_count ?? 0,
+      watchers: data.watchers_count ?? 0,
+      openIssues: data.open_issues_count ?? 0,
+      defaultBranch: data.default_branch ?? "main",
+      pushedAt: data.pushed_at ? Date.parse(data.pushed_at) : 0,
+      // Metadata — replaces manual frontmatter fields
+      repoName: data.name,
+      repoDescription: data.description ?? null,
+      topics: Array.isArray(data.topics) ? data.topics : [],
+      language: data.language ?? null,
+      homepage: data.homepage || null,
+      ownerLogin: data.owner?.login ?? owner,
+      ownerAvatarUrl: data.owner?.avatar_url ?? ""
+    };
+  }
+  /** Checks the current rate-limit budget. */
+  async checkRateLimit() {
+    const res = await this.fetchWithRetry(`${API_BASE}/rate_limit`);
+    if (!res.ok) {
+      throw new repodeckError("NETWORK_ERROR", `rate_limit endpoint returned ${res.status}`, { status: res.status });
+    }
+    const data = await res.json();
+    return { remaining: data.resources.core.remaining, limit: data.resources.core.limit, resetAt: data.resources.core.reset * 1e3 };
+  }
+  assertOk(res, context) {
+    if (res.status === 401) {
+      throw new repodeckError("UNAUTHORIZED", "GitHub token is invalid or expired.", { status: 401 });
+    }
+    if (res.status === 403) {
+      const remaining = res.headers.get("x-ratelimit-remaining");
+      if (remaining === "0") {
+        throw new repodeckError("RATE_LIMITED", "GitHub API rate limit exceeded.", { status: 403 });
+      }
+      throw new repodeckError("UNAUTHORIZED", "GitHub API returned 403 Forbidden.", { status: 403 });
+    }
+    if (!res.ok) {
+      throw new repodeckError("NETWORK_ERROR", `GitHub API ${res.status} for ${context}`, { status: res.status });
+    }
+  }
+};
+function buildRawUrl(owner, repo, branch, path) {
+  return `https://raw.githubusercontent.com/${enc(owner)}/${enc(repo)}/${enc(branch)}/${path.split("/").map(enc).join("/")}`;
+}
+async function fetchFileContent(owner, repo, path, options = {}) {
+  return GitHubClient.from(options).fetchFileContent(owner, repo, path, options.branch);
+}
+async function fetchDirectoryListing(owner, repo, path, options = {}) {
+  return GitHubClient.from(options).fetchDirectoryListing(owner, repo, path, options.branch);
+}
+async function fetchRepoStats(owner, repo, options = {}) {
+  return GitHubClient.from(options).fetchRepoStats(owner, repo);
+}
+async function checkRateLimit(options = {}) {
+  return GitHubClient.from(options).checkRateLimit();
+}
+function enc(s) {
+  return encodeURIComponent(s);
+}
+function sleep(ms) {
+  return new Promise((r) => setTimeout(r, ms));
+}
+function urlPath(url) {
+  try {
+    return new URL(url).pathname;
+  } catch {
+    return url;
+  }
+}
+
+// src/parser.ts
+var IMAGE_EXTENSIONS = [".png", ".jpg", ".jpeg", ".webp", ".gif", ".svg"];
+var _marked = null;
+var _DOMPurify = null;
+async function loadMarked() {
+  if (!_marked) {
+    const mod = await import("marked");
+    _marked = mod.marked;
+  }
+  return _marked;
+}
+async function loadDOMPurify() {
+  if (!_DOMPurify) {
+    const mod = await import("isomorphic-dompurify");
+    _DOMPurify = mod.default;
+  }
+  installLinkHardeningHook();
+  return _DOMPurify;
+}
+var _linkHookInstalled = false;
+function installLinkHardeningHook() {
+  if (_linkHookInstalled || !_DOMPurify) return;
+  _linkHookInstalled = true;
+  _DOMPurify.addHook("afterSanitizeAttributes", (node) => {
+    if (node.tagName === "A") {
+      node.setAttribute("target", "_blank");
+      node.setAttribute("rel", "noopener noreferrer");
+    }
+  });
+}
+var DEFAULT_RESUME_MAX = 280;
+function parseReadmeFrontmatter(rawMarkdown) {
+  const m = String(rawMarkdown ?? "").match(/^---\s*\n([\s\S]*?)\n---\s*\n?/);
+  if (!m) return { metadata: {}, content: rawMarkdown ?? "" };
+  const yamlBlock = m[1];
+  const content = (rawMarkdown ?? "").slice(m[0].length);
+  const metadata = {};
+  yamlBlock.split("\n").forEach((line) => {
+    const kv = line.match(/^([a-zA-Z_][a-zA-Z0-9_]*)\s*:\s*(.+)$/);
+    if (!kv) return;
+    const key = kv[1].trim();
+    const val = kv[2].trim().replace(/^["']|["']$/g, "");
+    if (key === "accent" && !/^#[0-9a-fA-F]{3}([0-9a-fA-F]{3})?$/.test(val)) return;
+    if (key === "order") {
+      const n = Number(val);
+      if (!isNaN(n)) metadata[key] = n;
+      return;
+    }
+    if (["title", "accent", "order", "description", "tags", "topics", "author"].includes(key)) {
+      metadata[key] = val;
+    }
+  });
+  return { metadata, content };
+}
+function parseResume(rawText, options) {
+  const maxChars = options?.maxChars ?? DEFAULT_RESUME_MAX;
+  const normalised = rawText.replace(/\r\n/g, "\n").replace(/[ \t]+/g, " ").replace(/ *\n */g, "\n").replace(/\n{3,}/g, "\n\n").trim();
+  if (normalised.length <= maxChars) {
+    return { text: normalised, truncated: false };
+  }
+  let cut = normalised.slice(0, maxChars);
+  const lastSpace = cut.lastIndexOf(" ");
+  if (lastSpace > maxChars * 0.6) cut = cut.slice(0, lastSpace);
+  return { text: cut, truncated: true };
+}
+async function parseReadme(rawMarkdown) {
+  const { metadata, content } = parseReadmeFrontmatter(rawMarkdown ?? "");
+  const marked = await loadMarked();
+  const DOMPurify = await loadDOMPurify();
+  marked.setOptions({ gfm: true, breaks: false });
+  const dirtyHtml = marked.parse(content, { async: false });
+  const html = DOMPurify.sanitize(dirtyHtml, {
+    ALLOWED_TAGS: [
+      "h1",
+      "h2",
+      "h3",
+      "h4",
+      "h5",
+      "h6",
+      "p",
+      "br",
+      "hr",
+      "blockquote",
+      "pre",
+      "code",
+      "ul",
+      "ol",
+      "li",
+      "a",
+      "strong",
+      "em",
+      "del",
+      "s",
+      "sup",
+      "sub",
+      "table",
+      "thead",
+      "tbody",
+      "tr",
+      "th",
+      "td",
+      "img",
+      "span",
+      "div",
+      "details",
+      "summary"
+    ],
+    ALLOWED_ATTR: [
+      "href",
+      "title",
+      "alt",
+      "src",
+      "width",
+      "height",
+      "colspan",
+      "rowspan",
+      "target",
+      "rel",
+      "align"
+    ],
+    ALLOW_DATA_ATTR: false
+  });
+  return {
+    html,
+    raw: rawMarkdown ?? "",
+    frontmatter: Object.keys(metadata).length > 0 ? metadata : void 0
+  };
+}
+function resolveScreenshots(entries, owner, repo, branch) {
+  return entries.filter((e) => IMAGE_EXTENSIONS.some((ext) => e.name.toLowerCase().endsWith(ext))).sort((a, b) => a.name.localeCompare(b.name, "en", { numeric: true, sensitivity: "base" })).map((e) => {
+    const path = e.path;
+    return {
+      url: buildRawUrl(owner, repo, branch, path),
+      filename: e.name,
+      alt: e.name.replace(/\.[^.]+$/, "").replace(/[-_]+/g, " ")
+    };
+  });
+}
+
+// src/builder.ts
+function validateConfig(owner, repo, options) {
+  if (typeof owner !== "string" || !owner.trim()) {
+    throw new repodeckError("INVALID_CONFIG", "`owner` is required.");
+  }
+  if (typeof repo !== "string" || !repo.trim()) {
+    throw new repodeckError("INVALID_CONFIG", "`repo` is required.");
+  }
+  const cp = options?.configPath;
+  if (cp !== void 0 && (typeof cp !== "string" || cp.includes(".."))) {
+    throw new repodeckError("INVALID_CONFIG", "`configPath` must be a safe string.");
+  }
+}
+function joinPath(configPath, file) {
+  return `${configPath.replace(/^\/+|\/+$/g, "")}/${file}`;
+}
+var CardBuilder = class {
+  constructor(client = new GitHubClient(), cache) {
+    this.client = client;
+    this.cache = cache;
+  }
+  async build(owner, repo, options = {}) {
+    validateConfig(owner, repo, options);
+    const debug = isDebugEnabled(options.debug);
+    const started = Date.now();
+    const branch = options.branch ?? "main";
+    const configPath = options.configPath ?? "config-repodeck";
+    const include = options.include ?? { readme: true, resume: true, screenshots: true };
+    const cacheKey = Cache.buildKey({ owner, repo, branch, configPath, include: includeKey(include) });
+    if (this.cache) {
+      const cached = this.cache.get(cacheKey);
+      if (cached) {
+        dbgLog(debug, "builder", `${owner}/${repo} cache HIT`);
+        return cached;
+      }
+    }
+    dbgLog(debug, "builder", `${owner}/${repo} build start branch=${branch} configPath=${configPath} include=${includeKey(include)}`);
+    const tasks = [];
+    if (include.resume) tasks.push(this.fetchResume(owner, repo, branch, configPath, options));
+    if (include.readme) tasks.push(this.fetchReadme(owner, repo, branch, configPath));
+    if (include.screenshots) tasks.push(this.fetchScreenshots(owner, repo, branch, configPath));
+    if (include.stats) tasks.push(this.fetchStats(owner, repo));
+    const results = await Promise.allSettled(tasks);
+    const card = {
+      meta: { owner, repo, url: `https://github.com/${owner}/${repo}`, branch, configPath, fetchedAt: Date.now() },
+      resume: null,
+      readme: null,
+      screenshots: null,
+      stats: null
+    };
+    for (const r of results) {
+      if (r.status !== "fulfilled") continue;
+      const { key, data } = r.value;
+      if (data === null) continue;
+      card[key] = data;
+    }
+    dbgLog(debug, "builder", `${owner}/${repo} done in ${Date.now() - started}ms resume=${ok(card.resume)} readme=${ok(card.readme)} screenshots=${ok(card.screenshots)} stats=${ok(card.stats)}`);
+    if (this.cache) this.cache.set(cacheKey, card);
+    return card;
+  }
+  // --- per-field fetchers (each isolates errors) --------------------------
+  async fetchResume(owner, repo, branch, configPath, options) {
+    const debug = isDebugEnabled(options.debug);
+    return this.safeFetch("resume", async () => {
+      let raw = null;
+      let usedLocale;
+      if (options.locale) {
+        raw = await this.client.fetchFileContent(owner, repo, joinPath(configPath, `RESUME.${options.locale}.txt`), branch);
+        if (raw !== null) usedLocale = options.locale;
+        else dbgLog(debug, "builder", `${owner}/${repo} RESUME.${options.locale}.txt missing \u2192 falling back to RESUME.txt`);
+      }
+      if (raw === null) {
+        raw = await this.client.fetchFileContent(owner, repo, joinPath(configPath, "RESUME.txt"), branch);
+      }
+      if (raw === null) throw new repodeckError("NOT_FOUND", "RESUME.txt not found in config folder.", { field: "resume" });
+      return { ...parseResume(raw, { maxChars: options.resumeMaxChars }), locale: usedLocale };
+    });
+  }
+  async fetchReadme(owner, repo, branch, configPath) {
+    return this.safeFetch("readme", async () => {
+      const raw = await this.client.fetchFileContent(owner, repo, joinPath(configPath, "README.md"), branch);
+      if (raw === null) throw new repodeckError("NOT_FOUND", "README.md not found in config folder.", { field: "readme" });
+      return await parseReadme(raw);
+    });
+  }
+  async fetchScreenshots(owner, repo, branch, configPath) {
+    return this.safeFetch("screenshots", async () => {
+      const entries = await this.client.fetchDirectoryListing(owner, repo, joinPath(configPath, "screenshots"), branch);
+      return resolveScreenshots(entries, owner, repo, branch);
+    });
+  }
+  async fetchStats(owner, repo) {
+    return this.safeFetch("stats", async () => {
+      return await this.client.fetchRepoStats(owner, repo);
+    });
+  }
+  /** Wraps a fetcher in try/catch, converting errors to per-field repodeckError. */
+  async safeFetch(key, fn) {
+    try {
+      return { key, data: await fn() };
+    } catch (err) {
+      const e = err instanceof repodeckError ? err : new repodeckError("NETWORK_ERROR", String(err), { field: key, cause: err });
+      return { key, data: { error: e } };
+    }
+  }
+};
+function ok(v) {
+  if (v === null || v === void 0) return "missing";
+  if (typeof v === "object" && v.code) return `ERR:${v.code}`;
+  return "ok";
+}
+function includeKey(include) {
+  return `${Number(!!include.readme)}${Number(!!include.resume)}${Number(!!include.screenshots)}${Number(!!include.stats)}`;
+}
+async function buildCardData(owner, repo, options = {}) {
+  const client = GitHubClient.from({ token: options.token, timeoutMs: options.timeoutMs, retries: options.retries });
+  const builder = new CardBuilder(client);
+  return builder.build(owner, repo, options);
+}
+
+// src/prefetch.ts
+var DEFAULT_INCLUDE = {
+  readme: true,
+  resume: true,
+  screenshots: true
+};
+async function prefetchCardData(targets, options = {}) {
+  if (!Array.isArray(targets) || targets.length === 0) {
+    return /* @__PURE__ */ new Map();
+  }
+  const concurrency = clamp(options.concurrency ?? 4, 1, 16);
+  const debug = isDebugEnabled(options.debug);
+  const client = new GitHubClient({
+    token: options.token,
+    timeoutMs: options.timeoutMs,
+    retries: options.retries,
+    debug
+  });
+  const cache = options.cache;
+  const defaultInclude = options.include ?? DEFAULT_INCLUDE;
+  const results = /* @__PURE__ */ new Map();
+  const errors = /* @__PURE__ */ new Map();
+  dbgLog(debug, "prefetch", `${targets.length} target(s), concurrency=${concurrency}`);
+  const queue = targets.slice();
+  async function startNextWorker() {
+    const target = queue.shift();
+    if (!target) return;
+    const key = `${target.owner}/${target.repo}`;
+    try {
+      const card = await buildOne(target, client, cache, defaultInclude);
+      results.set(key, card);
+    } catch (err) {
+      errors.set(key, err);
+      dbgLog(debug, "prefetch", `${key} fatal error: ${err instanceof Error ? err.message : String(err)}`);
+    }
+  }
+  const workers = [];
+  for (let i = 0; i < concurrency; i++) {
+    const chain = (async () => {
+      while (queue.length > 0) {
+        await startNextWorker();
+      }
+    })();
+    workers.push(chain);
+  }
+  await Promise.allSettled(workers);
+  if (errors.size > 0) {
+    attachErrors(results, errors);
+  }
+  return results;
+}
+function attachErrors(map, errors) {
+  Object.defineProperty(map, "errors", {
+    value: errors,
+    enumerable: false,
+    writable: false,
+    configurable: false
+  });
+}
+async function buildOne(target, client, cache, defaultInclude) {
+  const include = { ...defaultInclude, ...target.include ?? {} };
+  const builder = new CardBuilder(client, cache);
+  return builder.build(target.owner, target.repo, {
+    include,
+    branch: target.branch,
+    configPath: target.configPath
+  });
+}
+function clamp(value, min, max) {
+  if (Number.isNaN(value)) return min;
+  return Math.max(min, Math.min(max, value));
+}
+
+// src/graphql.ts
+var GRAPHQL_ENDPOINT = "https://api.github.com/graphql";
+var DEFAULT_INCLUDE2 = {
+  readme: true,
+  resume: true,
+  screenshots: true
+};
+var DEFAULT_BATCH_SIZE = 10;
+var DEFAULT_TIMEOUT_MS = 3e4;
+var GraphQLClient = class {
+  constructor(opts) {
+    if (!opts.token) {
+      throw new RepoDeckError("UNAUTHORIZED", "GraphQL requires a GitHub token.", {});
+    }
+    this.token = opts.token;
+    this.timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    this.retries = opts.retries ?? 2;
+    this.debug = isDebugEnabled(opts.debug);
+  }
+  /**
+   * POSTs a GraphQL query. Returns the `data` field of the response (already
+   * stripped of `errors`). Throws `RepoDeckError('NETWORK_ERROR', …)` on a
+   * non-2xx response, or `RepoDeckError` carrying the GraphQL errors when
+   * the response is 200 but carries `errors: [...]`.
+   */
+  async request(query, variables) {
+    let body = JSON.stringify({ query });
+    if (variables !== void 0) body = JSON.stringify({ query, variables });
+    const started = Date.now();
+    let lastErr;
+    for (let attempt = 0; attempt <= this.retries; attempt++) {
+      const controller = new AbortController();
+      const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+      try {
+        const res = await fetch(GRAPHQL_ENDPOINT, {
+          method: "POST",
+          headers: {
+            Authorization: `Bearer ${this.token}`,
+            "Content-Type": "application/json",
+            Accept: "application/vnd.github+json",
+            "User-Agent": "repodeck-core"
+          },
+          body,
+          signal: controller.signal
+        });
+        clearTimeout(timer);
+        const ms = Date.now() - started;
+        const rate = res.headers.get("x-ratelimit-remaining") ? `${res.headers.get("x-ratelimit-remaining")}/${res.headers.get("x-ratelimit-limit")}` : "n/a";
+        if (res.status >= 500 && attempt < this.retries) {
+          dbgLog(this.debug, "graphql", `POST /graphql \u2192 ${res.status} (retry ${attempt + 1}/${this.retries}) ${ms}ms rl=${rate}`);
+          await sleep2(2 ** attempt * 250);
+          continue;
+        }
+        dbgLog(this.debug, "graphql", `POST /graphql \u2192 ${res.status} ${ms}ms rl=${rate} attempt=${attempt + 1}`);
+        if (res.status === 401) {
+          throw new RepoDeckError("UNAUTHORIZED", "GitHub token is invalid or expired.", { status: 401 });
+        }
+        if (res.status === 403) {
+          throw new RepoDeckError("RATE_LIMITED", "GitHub GraphQL rate limit exceeded.", { status: 403 });
+        }
+        if (!res.ok) {
+          throw new RepoDeckError("NETWORK_ERROR", `GraphQL HTTP ${res.status}`, { status: res.status });
+        }
+        const json = await res.json();
+        if (json.errors && json.errors.length > 0 && json.data === void 0) {
+          const msg = json.errors.map((e) => e.message).join("; ");
+          dbgLog(this.debug, "graphql", `GraphQL errors: ${msg}`);
+          throw new RepoDeckError("NETWORK_ERROR", `GraphQL errors: ${msg}`);
+        }
+        if (json.data === void 0) {
+          throw new RepoDeckError("NETWORK_ERROR", "GraphQL returned no data and no errors.");
+        }
+        return json.data;
+      } catch (err) {
+        clearTimeout(timer);
+        if (err instanceof RepoDeckError) throw err;
+        lastErr = err;
+        if (attempt < this.retries) {
+          await sleep2(2 ** attempt * 250);
+          continue;
+        }
+      }
+    }
+    throw new RepoDeckError("NETWORK_ERROR", `Network error posting to GraphQL endpoint`, { cause: lastErr });
+  }
+};
+function planAliases(batch) {
+  return batch.map((target, i) => ({ alias: `r${i}`, target }));
+}
+function buildQuery(plan) {
+  const fragments = plan.map(({ alias, target }) => {
+    const owner = JSON.stringify(target.owner);
+    const name = JSON.stringify(target.repo);
+    const branchVal = target.branch ?? "main";
+    const configPath = (target.configPath ?? "config-repodeck").replace(/\/+$/, "");
+    const readmePath = `${configPath}/README.md`;
+    const resumeDefault = `${configPath}/RESUME.txt`;
+    const resumeLocalized = target.locale ? `${configPath}/RESUME.${target.locale}.txt` : null;
+    const expr = (p) => JSON.stringify(`${branchVal}:${p}`);
+    const fragments2 = [];
+    fragments2.push(`${alias}_meta: repository(owner: ${owner}, name: ${name}) {
+      name
+      description
+      url
+      homepageUrl
+      primaryLanguage { name }
+      repositoryTopics(first: 16) { nodes { topic { name } } }
+      stargazerCount
+      forkCount
+      watchers { totalCount }
+      issues(states: OPEN) { totalCount }
+      defaultBranchRef { name }
+      pushedAt
+      owner { login avatarUrl }
+    }`);
+    fragments2.push(`${alias}_readme: repository(owner: ${owner}, name: ${name}) {
+      object(expression: ${expr(readmePath)}) {
+        ... on Blob { text }
+      }
+    }`);
+    if (resumeLocalized) {
+      fragments2.push(`${alias}_resume: repository(owner: ${owner}, name: ${name}) {
+        object(expression: ${expr(resumeLocalized)}) {
+          ... on Blob { text }
+        }
+      }`);
+    } else {
+      fragments2.push(`${alias}_resume: repository(owner: ${owner}, name: ${name}) {
+        object(expression: ${expr(resumeDefault)}) {
+          ... on Blob { text }
+        }
+      }`);
+    }
+    return fragments2.join("\n");
+  });
+  return `query repodeckBatch { ${fragments.join("\n")} }`;
+}
+function metaToStats(meta, fallbackOwner) {
+  return {
+    stars: meta.stargazerCount ?? 0,
+    forks: meta.forkCount ?? 0,
+    watchers: meta.watchers?.totalCount ?? 0,
+    openIssues: meta.issues?.totalCount ?? 0,
+    defaultBranch: meta.defaultBranchRef?.name ?? "main",
+    pushedAt: meta.pushedAt ? Date.parse(meta.pushedAt) : 0,
+    repoName: meta.name,
+    repoDescription: meta.description,
+    topics: Array.isArray(meta.repositoryTopics?.nodes) ? meta.repositoryTopics.nodes.map((n) => n?.topic?.name).filter((t) => Boolean(t)) : [],
+    language: meta.primaryLanguage?.name ?? null,
+    homepage: meta.homepageUrl || null,
+    ownerLogin: meta.owner?.login ?? fallbackOwner,
+    ownerAvatarUrl: meta.owner?.avatarUrl ?? ""
+  };
+}
+async function fetchMultipleReposViaGraphQL(targets, options) {
+  if (!Array.isArray(targets) || targets.length === 0) {
+    return /* @__PURE__ */ new Map();
+  }
+  if (!options.token) {
+    throw new RepoDeckError("UNAUTHORIZED", "GraphQL batch requires a GitHub token.", {});
+  }
+  const batchSize = Math.max(1, Math.min(options.batchSize ?? DEFAULT_BATCH_SIZE, 50));
+  const defaultInclude = options.include ?? DEFAULT_INCLUDE2;
+  const debug = isDebugEnabled(options.debug);
+  const restClient = options.restClient ?? new GitHubClient({
+    token: options.token,
+    timeoutMs: 12e3,
+    retries: options.retries ?? 0,
+    debug
+  });
+  const results = /* @__PURE__ */ new Map();
+  const batchCount = Math.ceil(targets.length / batchSize);
+  dbgLog(debug, "graphql", `${targets.length} target(s), batchSize=${batchSize} \u2192 ${batchCount} request(s)`);
+  for (let i = 0; i < targets.length; i += batchSize) {
+    const slice = targets.slice(i, i + batchSize);
+    await runBatch(slice, options, defaultInclude, restClient, results, debug);
+  }
+  return results;
+}
+async function runBatch(batch, options, defaultInclude, restClient, results, debug) {
+  const plan = planAliases(batch);
+  const query = buildQuery(plan);
+  dbgLog(debug, "graphql", `request for ${plan.map((p) => `${p.alias}=${p.target.owner}/${p.target.repo}`).join(", ")} (query ${query.length} chars)`);
+  const client = new GraphQLClient({
+    token: options.token,
+    timeoutMs: options.timeoutMs,
+    retries: options.retries,
+    debug
+  });
+  let responseData;
+  try {
+    responseData = await client.request(query);
+  } catch (err) {
+    const isUnauthorized = err instanceof RepoDeckError && err.code === "UNAUTHORIZED";
+    const code = isUnauthorized ? "UNAUTHORIZED" : "NETWORK_ERROR";
+    const message = err instanceof Error ? err.message : "GraphQL request failed.";
+    dbgLog(debug, "graphql", `batch failed (${code}): ${message}`);
+    for (const { target } of plan) {
+      const key = `${target.owner}/${target.repo}`;
+      const branch = target.branch ?? "main";
+      const configPath = target.configPath ?? "config-repodeck";
+      const errInstance = new RepoDeckError(code, message);
+      results.set(key, {
+        meta: { owner: target.owner, repo: target.repo, url: `https://github.com/${target.owner}/${target.repo}`, branch, configPath, fetchedAt: Date.now() },
+        resume: { error: errInstance },
+        readme: { error: errInstance },
+        screenshots: { error: errInstance },
+        stats: { error: errInstance }
+      });
+    }
+    return;
+  }
+  const cardPromises = plan.map(async ({ alias, target }) => {
+    const key = `${target.owner}/${target.repo}`;
+    const branch = target.branch ?? "main";
+    const configPath = target.configPath ?? "config-repodeck";
+    const include = { ...defaultInclude, ...target.include ?? {} };
+    const meta = responseData[`${alias}_meta`];
+    const readmeBlob = responseData[`${alias}_readme`];
+    const resumeBlob = responseData[`${alias}_resume`];
+    const card = {
+      meta: { owner: target.owner, repo: target.repo, url: `https://github.com/${target.owner}/${target.repo}`, branch, configPath, fetchedAt: Date.now() },
+      resume: null,
+      readme: null,
+      screenshots: null,
+      stats: null
+    };
+    if (include.stats) {
+      if (meta) {
+        card.stats = metaToStats(meta, target.owner);
+      } else {
+        card.stats = { error: new RepoDeckError("NOT_FOUND", `Repository ${target.owner}/${target.repo} not accessible.`, { field: "stats" }) };
+      }
+    } else if (meta) {
+      card.stats = metaToStats(meta, target.owner);
+    }
+    if (include.readme) {
+      const raw = readmeBlob?.object?.text;
+      if (raw !== null && raw !== void 0) {
+        try {
+          card.readme = await parseReadme(raw);
+        } catch (err) {
+          card.readme = { error: new RepoDeckError("NETWORK_ERROR", `Could not parse README: ${String(err)}`, { field: "readme" }) };
+        }
+      } else {
+        card.readme = { error: new RepoDeckError("NOT_FOUND", "README.md not found in config folder.", { field: "readme" }) };
+      }
+    }
+    if (include.resume) {
+      const raw = resumeBlob?.object?.text;
+      if (raw !== null && raw !== void 0) {
+        const parsed = parseResume(raw, { maxChars: options.resumeMaxChars });
+        card.resume = { ...parsed, locale: target.locale };
+      } else {
+        card.resume = { error: new RepoDeckError("NOT_FOUND", "RESUME.txt not found in config folder.", { field: "resume" }) };
+      }
+    }
+    if (include.screenshots) {
+      try {
+        const screenshotsPath = `${configPath.replace(/^\/+|\/+$/g, "")}/screenshots`;
+        const entries = await restClient.fetchDirectoryListing(target.owner, target.repo, screenshotsPath, branch);
+        card.screenshots = resolveScreenshots(entries, target.owner, target.repo, branch);
+      } catch (err) {
+        const e = err instanceof RepoDeckError ? err : new RepoDeckError("NETWORK_ERROR", String(err), { field: "screenshots", cause: err });
+        card.screenshots = { error: e };
+      }
+    }
+    return { key, card };
+  });
+  const settled = await Promise.allSettled(cardPromises);
+  for (const r of settled) {
+    if (r.status === "fulfilled") results.set(r.value.key, r.value.card);
+  }
+}
+function sleep2(ms) {
+  return new Promise((r) => setTimeout(r, ms));
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  Cache,
+  CardBuilder,
+  GitHubClient,
+  GraphQLClient,
+  RepoDeckError,
+  assignBentoSpans,
+  buildCacheKey,
+  buildCardData,
+  buildRawUrl,
+  checkRateLimit,
+  clearCache,
+  defaultPresets,
+  fetchDirectoryListing,
+  fetchFileContent,
+  fetchMultipleReposViaGraphQL,
+  fetchRepoStats,
+  getCached,
+  getPreset,
+  listPresets,
+  mergePresetWithUserConfig,
+  parseReadme,
+  parseReadmeFrontmatter,
+  parseResume,
+  prefetchCardData,
+  registerPreset,
+  repodeckError,
+  resolveRadiusTokens,
+  resolveScreenshotLayout,
+  resolveScreenshots,
+  setCached,
+  validateConfig
+});