@socketsecurity/lib 5.28.0 → 6.0.1

package/dist/releases/github-listing.d.ts

@@ -0,0 +1,105 @@
+/**
+ * @file GitHub release listing via REST + GraphQL. Split out of
+ *   `releases/github-api.ts` for size hygiene. Holds the "list all releases for
+ *   a repo" path (both transports + the latest-matching-tag picker that
+ *   composes them):
+ *
+ *   - `fetchReleasesViaRest` — canonical REST `/releases?per_page=100` listing
+ *   - `fetchReleasesViaGraphQL` — GraphQL fallback when REST's ES index is
+ *     degraded
+ *   - `getLatestRelease` — REST → GraphQL fallback + prefix/asset filter The
+ *     per-tag asset-URL lookup lives in `./github-asset-url`.
+ */
+import type { AssetPattern, RepoConfig } from './github-types';
+/**
+ * Internal release row shape used by the listing helpers and the filter
+ * pipeline in `getLatestRelease`. Both REST and GraphQL paths normalize their
+ * output to this shape so downstream code is unaware of which transport
+ * produced the data.
+ */
+interface ReleaseRow {
+    tag_name: string;
+    published_at: string;
+    assets: Array<{
+        name: string;
+    }>;
+}
+/**
+ * Fetch the latest 100 releases for a repo via GraphQL.
+ *
+ * Why this exists: `fetchReleasesViaRest` can return `[]` for two reasons (real
+ * empty repo vs. GitHub-incident-degraded backend). When REST returns nothing,
+ * the caller in `getLatestRelease` calls THIS to disambiguate — if we return >0
+ * here, REST was lying.
+ *
+ * Field shape diffs we normalize: GraphQL returns REST equivalent Why they
+ * differ `tagName` `tag_name` camelCase vs. snake_case `publishedAt`
+ * `published_at` camelCase vs. snake_case `releaseAssets.nodes` `assets`
+ * GraphQL connection wrapper unwrapped.
+ *
+ * We re-shape inside the `.map(...)` at the bottom so callers downstream can
+ * use the SAME code path regardless of which transport ran.
+ *
+ * Why we hit a different backend: GraphQL queries don't go through the same
+ * Elasticsearch index that REST listings rely on. During incidents that drop
+ * the ES index (or its connectivity), GraphQL's `repository.releases`
+ * connection keeps working because it reads from a different data path inside
+ * GitHub. That's the entire reason this fallback exists.
+ */
+export declare function fetchReleasesViaGraphQL(owner: string, repo: string): Promise<ReleaseRow[]>;
+/**
+ * Fetch the latest 100 releases for a repo via REST.
+ *
+ * Why this returns `[]` on TWO different cases:
+ *
+ * - HTTP 200 + zero-byte body. This is the documented GitHub "search degraded"
+ *   incident shape (see status.github.com). The releases listing endpoint
+ *   shares an Elasticsearch index with search; when that ES is degraded,
+ *   `/releases` returns a successful 200 OK but with NO BODY. There's no error
+ *   code, no Retry-After, no rate-limit header — just an empty payload.
+ * - HTTP 200 + literal `[]`. This is the _normal_ "the repo has no releases"
+ *   response — say a brand-new repo with no published versions.
+ *
+ * Both produce the same `[]` here because the helper can't tell them apart
+ * without context. The CALLER (getLatestRelease) does the cross-check: if REST
+ * returns `[]`, query GraphQL once. If GraphQL also returns `[]`, the repo
+ * really is empty. If it returns >0, REST was lying and we use GraphQL's
+ * answer.
+ *
+ * Why we throw on non-OK status: `pRetry` wraps this call and retries on thrown
+ * errors with exponential backoff. A 5xx is transient and worth retrying; we
+ * want it to throw so pRetry can do its job. Empty body is NOT thrown because
+ * pRetry can't help — a 200 OK is "done" as far as retry policy is concerned.
+ */
+export declare function fetchReleasesViaRest(owner: string, repo: string): Promise<ReleaseRow[]>;
+/**
+ * Get latest release tag matching a tool prefix. Optionally filter by releases
+ * containing a matching asset.
+ *
+ * @example
+ *   ;```typescript
+ *   const tag = await getLatestRelease('lief-', {
+ *     owner: 'SocketDev',
+ *     repo: 'socket-btm',
+ *   })
+ *   console.log(tag) // 'lief-2025-01-15-abc1234'
+ *   ```
+ *
+ * @param toolPrefix - Tool name prefix to search for (e.g., 'node-smol-')
+ * @param repoConfig - Repository configuration (owner/repo)
+ * @param options - Additional options.
+ * @param options.assetPattern - Optional pattern to filter releases by matching
+ *   asset.
+ * @param options.nothrow - If true, return undefined instead of throwing when
+ *   both REST and GraphQL backends are degraded. Default: false.
+ *
+ * @returns Latest release tag or undefined if not found
+ *
+ * @throws {Error} If both REST and GraphQL backends are degraded and nothrow is
+ *   false.
+ */
+export declare function getLatestRelease(toolPrefix: string, repoConfig: RepoConfig, options?: {
+    assetPattern?: AssetPattern;
+    nothrow?: boolean;
+}): Promise<string | undefined>;
+export {};

package/dist/releases/github-listing.js

@@ -0,0 +1,171 @@
+"use strict";
+/* Socket Lib - Built with esbuild */
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+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 __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var github_listing_exports = {};
+__export(github_listing_exports, {
+  fetchReleasesViaGraphQL: () => fetchReleasesViaGraphQL,
+  fetchReleasesViaRest: () => fetchReleasesViaRest,
+  getLatestRelease: () => getLatestRelease
+});
+module.exports = __toCommonJS(github_listing_exports);
+var import_request = require("../http-request/request");
+var import_retry = require("../promises/retry");
+var import_array = require("../primordials/array");
+var import_date = require("../primordials/date");
+var import_error = require("../primordials/error");
+var import_json = require("../primordials/json");
+var import_object = require("../primordials/object");
+var import_string = require("../primordials/string");
+var import_github_assets = require("./github-assets");
+var import_github_auth = require("./github-auth");
+const RETRY_CONFIG = (0, import_object.ObjectFreeze)({
+  __proto__: null,
+  // Exponential backoff: delay doubles with each retry (5s, 10s, 20s).
+  backoffFactor: 2,
+  // Initial delay before first retry.
+  baseDelayMs: 5e3,
+  // Maximum number of retry attempts (excluding initial request).
+  retries: 2
+});
+async function fetchReleasesViaGraphQL(owner, repo) {
+  const response = await (0, import_request.httpRequest)("https://api.github.com/graphql", {
+    body: (0, import_json.JSONStringify)({
+      query: `query($owner: String!, $repo: String!) {
+        repository(owner: $owner, name: $repo) {
+          releases(first: 100, orderBy: {field: CREATED_AT, direction: DESC}) {
+            nodes {
+              tagName
+              publishedAt
+              releaseAssets(first: 100) { nodes { name } }
+            }
+          }
+        }
+      }`,
+      variables: { owner, repo }
+    }),
+    headers: { ...(0, import_github_auth.getAuthHeaders)(), "Content-Type": "application/json" },
+    method: "POST"
+  });
+  if (!response.ok) {
+    throw new import_error.ErrorCtor(
+      `Failed to fetch ${owner}/${repo} releases (GraphQL): ${response.status}`
+    );
+  }
+  let parsed;
+  try {
+    parsed = (0, import_json.JSONParse)(response.body.toString("utf8"));
+  } catch (cause) {
+    throw new import_error.ErrorCtor(
+      `Failed to parse GitHub GraphQL response for ${owner}/${repo} releases`,
+      { cause }
+    );
+  }
+  if (parsed.errors?.length) {
+    throw new import_error.ErrorCtor(
+      `GraphQL repository.releases(${owner}/${repo}) returned errors: ${parsed.errors.map((e) => e.message).join("; ")}`
+    );
+  }
+  return (parsed.data?.repository?.releases?.nodes ?? []).map((n) => ({
+    tag_name: n.tagName,
+    published_at: n.publishedAt,
+    assets: n.releaseAssets?.nodes ?? []
+  }));
+}
+async function fetchReleasesViaRest(owner, repo) {
+  const response = await (0, import_request.httpRequest)(
+    `https://api.github.com/repos/${owner}/${repo}/releases?per_page=100`,
+    { headers: (0, import_github_auth.getAuthHeaders)() }
+  );
+  if (!response.ok) {
+    throw new import_error.ErrorCtor(
+      `Failed to fetch ${owner}/${repo} releases: ${response.status}`
+    );
+  }
+  const text = response.body.toString("utf8");
+  if (text.length === 0) {
+    return [];
+  }
+  let parsed;
+  try {
+    parsed = (0, import_json.JSONParse)(text);
+  } catch (cause) {
+    throw new import_error.ErrorCtor(`Failed to parse ${owner}/${repo} releases response`, {
+      cause
+    });
+  }
+  return (0, import_array.ArrayIsArray)(parsed) ? parsed : [];
+}
+async function getLatestRelease(toolPrefix, repoConfig, options = {}) {
+  const { assetPattern, nothrow = false } = options;
+  const { owner, repo } = repoConfig;
+  const isMatch = assetPattern ? (0, import_github_assets.createAssetMatcher)(assetPattern) : void 0;
+  return await (0, import_retry.pRetry)(async () => {
+    let releases = await fetchReleasesViaRest(owner, repo);
+    if (releases.length === 0) {
+      let graphqlReleases;
+      try {
+        graphqlReleases = await fetchReleasesViaGraphQL(owner, repo);
+      } catch (cause) {
+        if (nothrow) {
+          return void 0;
+        }
+        throw new import_error.ErrorCtor(
+          `Failed to list ${owner}/${repo} releases: both REST and GraphQL backends degraded`,
+          { cause }
+        );
+      }
+      if (graphqlReleases.length > 0) {
+        releases = graphqlReleases;
+      }
+    }
+    const matchingReleases = releases.filter((release) => {
+      const { assets, tag_name: tag } = release;
+      if (!(0, import_string.StringPrototypeStartsWith)(tag, toolPrefix)) {
+        return false;
+      }
+      if (!assets || assets.length === 0) {
+        return false;
+      }
+      if (isMatch) {
+        const hasMatchingAsset = assets.some(
+          (a) => isMatch(a.name)
+        );
+        if (!hasMatchingAsset) {
+          return false;
+        }
+      }
+      return true;
+    });
+    if (matchingReleases.length === 0) {
+      return void 0;
+    }
+    matchingReleases.sort(
+      (a, b) => (0, import_date.DateParse)(b.published_at) - (0, import_date.DateParse)(a.published_at)
+    );
+    const latestRelease = matchingReleases[0];
+    return latestRelease.tag_name;
+  }, RETRY_CONFIG) ?? void 0;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  fetchReleasesViaGraphQL,
+  fetchReleasesViaRest,
+  getLatestRelease
+});

package/dist/releases/github-types.d.ts

@@ -1,22 +1,24 @@
 /**
- * @fileoverview Public types for GitHub release download utilities.
+ * @file Public types for GitHub release download utilities.
  */
 /**
- * Pattern for matching release assets.
- * Can be either:
+ * Pattern for matching release assets. Can be either:
+ *
  * - A string with glob pattern syntax
  * - A prefix/suffix pair for explicit matching (backward compatible)
  * - A RegExp for complex patterns
  *
- * String patterns support full glob syntax via picomatch.
- * Examples:
+ * String patterns support full glob syntax via picomatch. Examples:
+ *
  * - Simple wildcard: yoga-sync-*.mjs matches yoga-sync-abc123.mjs
  * - Complex: models-*.tar.gz matches models-2024-01-15.tar.gz
  * - Prefix wildcard: *-models.tar.gz matches foo-models.tar.gz
  * - Suffix wildcard: yoga-* matches yoga-layout
- * - Brace expansion: {yoga,models}-*.{mjs,js} matches yoga-abc.mjs or models-xyz.js
+ * - Brace expansion: {yoga,models}-*.{mjs,js} matches yoga-abc.mjs or
+ *   models-xyz.js
  *
- * For backward compatibility, prefix/suffix objects are still supported but glob patterns are recommended.
+ * For backward compatibility, prefix/suffix objects are still supported but
+ * glob patterns are recommended.
  */
 export type AssetPattern = string | {
     prefix: string;
@@ -26,29 +28,53 @@ export type AssetPattern = string | {
  * Configuration for downloading a GitHub release.
  */
 export interface DownloadGitHubReleaseConfig {
-    /** Asset name on GitHub. */
+    /**
+     * Asset name on GitHub.
+     */
     assetName: string;
-    /** Binary filename (e.g., 'node', 'binject'). */
+    /**
+     * Binary filename (e.g., 'node', 'binject').
+     */
     binaryName: string;
-    /** Working directory (defaults to process.cwd()). */
+    /**
+     * Working directory (defaults to process.cwd()).
+     */
     cwd?: string;
-    /** Download destination directory. @default 'build/downloaded' */
+    /**
+     * Download destination directory. @default 'build/downloaded'
+     */
     downloadDir?: string;
-    /** GitHub repository owner/organization. */
+    /**
+     * GitHub repository owner/organization.
+     */
     owner: string;
-    /** Platform-arch identifier (e.g., 'linux-x64-musl'). */
+    /**
+     * Platform-arch identifier (e.g., 'linux-x64-musl').
+     */
     platformArch: string;
-    /** Suppress log messages. @default false */
+    /**
+     * Suppress log messages. @default false.
+     */
     quiet?: boolean;
-    /** Remove macOS quarantine attribute after download. @default true */
+    /**
+     * Remove macOS quarantine attribute after download. @default true.
+     */
     removeMacOSQuarantine?: boolean;
-    /** GitHub repository name. */
+    /**
+     * GitHub repository name.
+     */
     repo: string;
-    /** Specific release tag to download. */
+    /**
+     * Specific release tag to download.
+     */
     tag?: string;
-    /** Tool name for directory structure. */
+    /**
+     * Tool name for directory structure.
+     */
     toolName: string;
-    /** Tool prefix for finding latest release. */
+    /**
+     * Tool prefix for finding latest release.
+     */
     toolPrefix?: string;
 }
 /**