argusqa-os 9.7.5 → 9.8.0

package/src/utils/deploy-preview.js

@@ -0,0 +1,210 @@
+/**
+ * Deploy-preview URL auto-detection (PR Validator D3).
+ *
+ * Resolves the audit TARGET URL for a PR run, preferring a per-PR deploy preview
+ * (Vercel / Netlify / any GitHub Deployment) over the static TARGET_DEV_URL, and ALWAYS
+ * degrading gracefully to TARGET_DEV_URL when no preview is found or any detection step
+ * fails. Detection never throws and never blocks the run — a wrong/failed/missing preview
+ * must never silently audit the wrong app, so only a SUCCESS deploy-status URL for the PR's
+ * head SHA is ever adopted; everything else falls back.
+ *
+ * Resolution precedence (resolveTargetUrl):
+ *   1. explicitTarget    — an explicit per-call target (MCP tool `targetUrl` arg). Highest;
+ *                          passed through raw (explicit caller intent, like TARGET_DEV_URL).
+ *   2. ARGUS_PREVIEW_URL  — explicit env override (opt-in by being set). Provider env vars
+ *                          DEPLOY_PRIME_URL (Netlify) + VERCEL_URL (Vercel, bare host) are
+ *                          also recognized for convenience.
+ *   3. auto-detected preview from the PR head SHA's GitHub Deployments — OPT-IN:
+ *      ARGUS_PREVIEW_DETECT truthy + a token + a head SHA + a parseable PR URL. One+one
+ *      GitHub API call, fully fail-safe (any error → no preview → fallback).
+ *   4. TARGET_DEV_URL (or http://localhost:3000) — the conservative fallback, byte-identical
+ *      to the pre-D3 behaviour when nothing above matches.
+ *
+ * Pure helpers (Chrome-free, network-free) + one fail-safe async fetch. Imported (transitively)
+ * by the MCP server → nothing here writes to stdout (logs go to the injected/childLogger).
+ * No AI verdict — pure static/heuristic resolution (OSS side of the argus-pro boundary).
+ */
+
+import { parsePrUrl } from './pr-diff-analyzer.js';
+import { childLogger } from './logger.js';
+
+const logger = childLogger('deploy-preview');
+
+const GITHUB_API   = 'https://api.github.com';
+const FETCH_TIMEOUT = 10000;
+
+// Env vars (priority order) that may carry an explicit preview URL. ARGUS_PREVIEW_URL is the
+// portable, Argus-namespaced canonical; the rest are provider conventions surfaced for users
+// who forward them into the runner. VERCEL_URL is a bare host (no scheme) — normalized below.
+const ENV_PREVIEW_VARS = ['ARGUS_PREVIEW_URL', 'DEPLOY_PRIME_URL', 'VERCEL_URL'];
+
+/**
+ * Trim a candidate URL and accept it only if it carries an http(s) scheme.
+ * Returns the trimmed URL or null (never throws). Untrusted/auto-detected URLs flow through
+ * this; explicit caller targets (the MCP arg, TARGET_DEV_URL) are passed through raw.
+ * @param {*} raw
+ * @returns {string|null}
+ */
+export function normalizeUrl(raw) {
+  if (raw == null) return null;
+  const s = String(raw).trim();
+  if (!s) return null;
+  return /^https?:\/\//i.test(s) ? s : null;
+}
+
+/**
+ * Pick an explicit preview URL from the environment, honouring ENV_PREVIEW_VARS priority.
+ * VERCEL_URL is a bare host → prefixed with https:// before validation.
+ * @param {Record<string,string|undefined>} env
+ * @returns {{ url: string, source: string }|null}
+ */
+export function pickPreviewFromEnv(env = {}) {
+  for (const name of ENV_PREVIEW_VARS) {
+    let raw = env[name];
+    if (raw == null || String(raw).trim() === '') continue;
+    // VERCEL_URL is conventionally a bare host (e.g. my-app-git-pr.vercel.app).
+    if (name === 'VERCEL_URL' && !/^https?:\/\//i.test(String(raw).trim())) {
+      raw = `https://${String(raw).trim()}`;
+    }
+    const url = normalizeUrl(raw);
+    if (url) return { url, source: `env:${name}` };
+    logger.warn(`[ARGUS] D3: ${name} is set but not a valid http(s) URL — ignoring`);
+  }
+  return null;
+}
+
+/**
+ * Heuristic: is a GitHub Deployment object a PR/preview deployment (not production)?
+ * Recognizes Vercel ("Preview – <project>"), Netlify ("deploy-preview"), and any explicitly
+ * non-production / transient environment. Production deployments are excluded.
+ * @param {object} deployment
+ * @returns {boolean}
+ */
+export function isPreviewDeployment(deployment) {
+  if (!deployment || typeof deployment !== 'object') return false;
+  const env = String(deployment.environment ?? '');
+  // Explicit production → never a preview target.
+  if (deployment.production_environment === true || /production/i.test(env)) return false;
+  return (
+    /preview|deploy[\s-]?preview|staging/i.test(env) ||
+    deployment.transient_environment === true ||
+    deployment.production_environment === false
+  );
+}
+
+/**
+ * From a list of GitHub Deployments (newest-first, as the API returns them), pick the most
+ * recent preview deployment, or null when none qualify.
+ * @param {Array<object>} deployments
+ * @returns {object|null}
+ */
+export function pickPreviewDeployment(deployments) {
+  if (!Array.isArray(deployments)) return null;
+  return deployments.find(isPreviewDeployment) ?? null;
+}
+
+/**
+ * From a deployment's statuses (newest-first), return the live preview URL — the
+ * environment_url (preferred) or target_url of the most recent SUCCESS status — or null.
+ * Only a `success` status is adopted: a failed / error / pending / inactive deploy must
+ * never become the audit target (auditing a broken or stale preview would be a false result).
+ * @param {Array<object>} statuses
+ * @returns {string|null}
+ */
+export function previewUrlFromStatuses(statuses) {
+  if (!Array.isArray(statuses)) return null;
+  for (const s of statuses) {
+    if (!s || s.state !== 'success') continue;
+    const url = normalizeUrl(s.environment_url) ?? normalizeUrl(s.target_url);
+    if (url) return url;
+  }
+  return null;
+}
+
+async function ghGet(url, headers) {
+  const res = await fetch(url, { headers, signal: AbortSignal.timeout(FETCH_TIMEOUT) });
+  if (!res.ok) return null;
+  return res.json();
+}
+
+/**
+ * Fetch the live preview URL for a PR head SHA via the GitHub Deployments API. Fully
+ * fail-safe: ANY failure (no SHA, non-2xx, network error, no preview deployment, no success
+ * status) resolves to null so the caller degrades to TARGET_DEV_URL. Never throws.
+ *
+ * @param {object} opts
+ * @param {string} opts.owner
+ * @param {string} opts.repo
+ * @param {string} opts.sha    PR head SHA (NOT the merge commit)
+ * @param {string} [opts.token] GitHub token
+ * @returns {Promise<string|null>}
+ */
+export async function fetchPreviewUrlFromDeployments({ owner, repo, sha, token } = {}) {
+  try {
+    if (!owner || !repo || !sha) return null;
+    const headers = {
+      Accept: 'application/vnd.github+json',
+      'X-GitHub-Api-Version': '2022-11-28',
+      'User-Agent': 'argusqa-os',
+      ...(token ? { Authorization: `Bearer ${token}` } : {}),
+    };
+    const deployments = await ghGet(
+      `${GITHUB_API}/repos/${owner}/${repo}/deployments?sha=${encodeURIComponent(sha)}&per_page=30`,
+      headers,
+    );
+    const dep = pickPreviewDeployment(deployments);
+    if (!dep) return null;
+    const statuses = await ghGet(
+      `${GITHUB_API}/repos/${owner}/${repo}/deployments/${dep.id}/statuses?per_page=30`,
+      headers,
+    );
+    return previewUrlFromStatuses(statuses);
+  } catch (err) {
+    // Detection is best-effort — a probe failure must degrade to TARGET_DEV_URL, never break
+    // the run. The token never rides into the message (err.message is GitHub's text only).
+    logger.warn(`[ARGUS] D3: deploy-preview detection failed — ${err.message}`);
+    return null;
+  }
+}
+
+/**
+ * Resolve the audit target URL for a PR run (D3). See the module header for precedence.
+ * Always resolves (never throws); `source` records which rung won, for logging/visibility.
+ *
+ * @param {object} opts
+ * @param {Record<string,string|undefined>} opts.env  the process env (or a test object)
+ * @param {string} [opts.explicitTarget] an explicit per-call target (MCP `targetUrl` arg)
+ * @param {string} [opts.prUrl]
+ * @param {string} [opts.headSha]
+ * @param {string} [opts.token]
+ * @returns {Promise<{ url: string, source: string }>}
+ */
+export async function resolveTargetUrl({ env = {}, explicitTarget, prUrl, headSha, token } = {}) {
+  // The conservative fallback — passed through RAW (explicit operator intent), so the default
+  // path is byte-identical to the pre-D3 `TARGET_DEV_URL ?? 'http://localhost:3000'`.
+  const fallback = env.TARGET_DEV_URL ?? 'http://localhost:3000';
+
+  // 1. Explicit per-call target (MCP arg) — raw, highest precedence.
+  if (explicitTarget != null && String(explicitTarget).trim() !== '') {
+    return { url: explicitTarget, source: 'explicit' };
+  }
+
+  // 2. Explicit env override (ARGUS_PREVIEW_URL / provider env vars).
+  const envPick = pickPreviewFromEnv(env);
+  if (envPick) return envPick;
+
+  // 3. Auto-detect from GitHub Deployments — opt-in + fully fail-safe.
+  const detectOn = /^(1|true|yes|on)$/i.test(env.ARGUS_PREVIEW_DETECT || '');
+  if (detectOn && token && headSha && prUrl) {
+    try {
+      const { owner, repo } = parsePrUrl(prUrl);
+      const url = await fetchPreviewUrlFromDeployments({ owner, repo, sha: headSha, token });
+      if (url) return { url, source: 'deployment' };
+    } catch {
+      // parsePrUrl or detection threw — degrade silently to the fallback below.
+    }
+  }
+
+  // 4. Conservative fallback.
+  return { url: fallback, source: 'target-dev-url' };
+}

package/src/utils/github-api.js

@@ -0,0 +1,242 @@
+/**
+ * Shared resilient GitHub REST client for the PR Validator (Phase E2).
+ *
+ * One place that BOTH GitHub throw-path callers route through — fetchPrFiles
+ * (pr-diff-analyzer.js, the PR diff) and ghFetch (github-reporter.js, the PR
+ * comment / Check Run) — so the two paths can never diverge on resilience.
+ * Mirrors the "one shared decision" discipline of decidePrBlock (B1) /
+ * selectAnalyzers (D2) / resolveTargetUrl (D3) / routeResilienceFromEnv (D4).
+ *
+ * What it does:
+ *   - retries a 403 PRIMARY rate-limit (X-RateLimit-Remaining: 0), a 403/429
+ *     SECONDARY rate-limit (Retry-After), a transient 5xx, and a network error,
+ *     with backoff that honours Retry-After / X-RateLimit-Reset when present;
+ *   - NEVER retries a 401 / 404 / 422 / plain-403 (permissions) — those are
+ *     terminal and throw a structured, cause-carrying error immediately;
+ *   - keeps every thrown message SECRET-FREE: the token rides only in request
+ *     headers (never the response body), and scrubSecrets() defensively redacts
+ *     any Bearer / ghp_ / github_pat_ token that somehow appears in a body.
+ *
+ * deploy-preview.js's Deployments probe is deliberately NOT routed through here:
+ * it is fail-safe-to-null + opt-in (D3) and must degrade fast, not retry.
+ *
+ * Pure helpers + one fetch wrapper. No Chrome, no MCP, no AI verdict. Imported
+ * (transitively) by the MCP server → nothing here writes to stdout.
+ */
+
+/** Default per-request timeout (ms) — matches the prior ghFetch behaviour. */
+const DEFAULT_TIMEOUT_MS = 15000;
+/** Default backoff base (ms) for the exponential fallback. */
+const DEFAULT_BASE_MS = 1000;
+/**
+ * Cap on any single backoff wait (ms). A far-future X-RateLimit-Reset (the GitHub
+ * primary-limit window can be up to an hour) must NOT hang CI for the whole window —
+ * we cap, retry sooner, and fail loud if still limited. A capped retry that throws a
+ * clear "rate limit exceeded — retries exhausted" beats a multi-minute silent stall.
+ */
+const DEFAULT_MAX_MS = 8000;
+/** Default total attempts (1 initial + 2 retries). */
+const DEFAULT_MAX_ATTEMPTS = 3;
+
+/**
+ * Read a header case-insensitively from a Headers object (fetch Response.headers,
+ * which exposes .get()) OR a plain object (used by test stubs). Returns the string
+ * value or undefined — never throws on a missing/odd headers bag.
+ *
+ * @param {Headers|Record<string,string>|undefined} headers
+ * @param {string} name
+ * @returns {string|undefined}
+ */
+export function headerValue(headers, name) {
+  if (!headers) return undefined;
+  const key = String(name).toLowerCase();
+  if (typeof headers.get === 'function') {
+    return headers.get(name) ?? headers.get(key) ?? undefined;
+  }
+  for (const k of Object.keys(headers)) {
+    if (k.toLowerCase() === key) return headers[k];
+  }
+  return undefined;
+}
+
+/**
+ * Redact any GitHub token shape from a string. The token is sent only in request
+ * headers, so a response body never contains it — this is belt-and-suspenders so a
+ * thrown error message can NEVER leak a credential even if a body echoes one.
+ *
+ * @param {*} text
+ * @returns {string}
+ */
+export function scrubSecrets(text) {
+  return String(text ?? '')
+    .replace(/Bearer\s+[A-Za-z0-9._~+/=-]+/gi, 'Bearer ***')
+    .replace(/\bgithub_pat_[A-Za-z0-9_]{20,}/g, '***')   // fine-grained PAT (has underscores)
+    .replace(/\bgh[posru]_[A-Za-z0-9_]{10,}/g, '***');   // ghp_ gho_ ghs_ ghr_ ghu_
+}
+
+/**
+ * Classify a response as a GitHub rate-limit (so it should be retried with backoff).
+ *   - 429                                   → always a rate-limit (secondary).
+ *   - 403 with X-RateLimit-Remaining === 0  → primary rate-limit exhausted.
+ *   - 403 with a Retry-After header          → secondary rate-limit.
+ * A plain 403 with no rate-limit signal is a PERMISSIONS error — not retried.
+ *
+ * @param {number} status
+ * @param {Headers|Record<string,string>|undefined} headers
+ * @returns {boolean}
+ */
+export function isRateLimitResponse(status, headers) {
+  if (status === 429) return true;
+  if (status === 403) {
+    const remaining = headerValue(headers, 'x-ratelimit-remaining');
+    if (remaining !== undefined && remaining !== null && Number(remaining) === 0) return true;
+    if (headerValue(headers, 'retry-after') !== undefined) return true;
+  }
+  return false;
+}
+
+/**
+ * Compute the backoff (ms) before the next attempt. Honours GitHub's explicit
+ * signals first (Retry-After seconds, then X-RateLimit-Reset epoch seconds),
+ * falling back to exponential backoff. Every result is capped at maxMs.
+ *
+ * @param {number} status   HTTP status (0 for a network error)
+ * @param {Headers|Record<string,string>|undefined} headers
+ * @param {number} attempt  1-based attempt number that just failed
+ * @param {{ baseMs?: number, maxMs?: number, now?: () => number }} [opts]
+ * @returns {number}
+ */
+export function retryDelayMs(status, headers, attempt, opts = {}) {
+  const { baseMs = DEFAULT_BASE_MS, maxMs = DEFAULT_MAX_MS, now = Date.now } = opts;
+
+  const retryAfter = headerValue(headers, 'retry-after');
+  if (retryAfter !== undefined && retryAfter !== null && String(retryAfter).trim() !== '') {
+    const secs = Number(retryAfter);
+    if (Number.isFinite(secs) && secs >= 0) return Math.min(secs * 1000, maxMs);
+  }
+
+  if (isRateLimitResponse(status, headers)) {
+    const reset = headerValue(headers, 'x-ratelimit-reset');
+    if (reset !== undefined) {
+      const resetMs = Number(reset) * 1000 - now();
+      if (Number.isFinite(resetMs) && resetMs > 0) return Math.min(resetMs, maxMs);
+    }
+  }
+
+  const exp = baseMs * Math.pow(2, Math.max(0, attempt - 1));
+  return Math.min(exp, maxMs);
+}
+
+/**
+ * Build a structured, secret-free error message for a TERMINAL (non-retried)
+ * GitHub response. Carries the cause (status + a short, scrubbed body) and a
+ * human hint for the common cases — never the token, never "is not defined".
+ *
+ * @param {number} status
+ * @param {string} [statusText]
+ * @param {string} [bodyText]
+ * @param {string} [context]  e.g. "GET /repos/o/r/pulls/7/files"
+ * @returns {string}
+ */
+export function classifyGitHubError(status, statusText, bodyText, context) {
+  const ctx  = context ? ` (${context})` : '';
+  const body = scrubSecrets(String(bodyText ?? '').replace(/\s+/g, ' ').trim()).slice(0, 300);
+  const tail = body ? `: ${body}` : (statusText ? `: ${statusText}` : '');
+  switch (status) {
+    case 401:
+      return `GitHub API 401 (bad credentials)${ctx} — the token is missing, invalid, or expired${tail}`;
+    case 403:
+      return `GitHub API 403 (forbidden)${ctx} — the token lacks the required scope or resource access${tail}`;
+    case 404:
+      return `GitHub API 404 (not found)${ctx} — check the repository and PR exist and the token can access them${tail}`;
+    case 422:
+      return `GitHub API 422 (unprocessable)${ctx} — GitHub rejected the request${tail}`;
+    default:
+      return `GitHub API ${status}${ctx}${tail}`;
+  }
+}
+
+async function safeText(res) {
+  try {
+    return res && typeof res.text === 'function' ? await res.text() : '';
+  } catch {
+    return '';
+  }
+}
+
+/**
+ * Resilient GitHub REST request. Resolves to the OK Response (caller reads
+ * .json() / paginates) or THROWS a structured, secret-free Error. See the module
+ * header for the retry vs throw policy.
+ *
+ * @param {string} url
+ * @param {object} [opts]
+ * @param {string} [opts.method='GET']
+ * @param {Record<string,string>} [opts.headers]
+ * @param {string} [opts.body]              already-serialised body (or undefined)
+ * @param {number} [opts.maxAttempts=3]
+ * @param {number} [opts.baseMs=1000]
+ * @param {number} [opts.maxMs=8000]
+ * @param {number} [opts.timeoutMs=15000]   per-attempt timeout; <=0 disables
+ * @param {(ms:number)=>Promise<void>} [opts.sleep]  injectable for tests
+ * @param {()=>number} [opts.now]           injectable clock for backoff math
+ * @param {(url:string,init:object)=>Promise<Response>} [opts.fetchImpl]
+ * @param {string} [opts.context]           label woven into error messages
+ * @returns {Promise<Response>}
+ */
+export async function githubFetch(url, opts = {}) {
+  const {
+    method = 'GET', headers, body,
+    maxAttempts = DEFAULT_MAX_ATTEMPTS,
+    baseMs = DEFAULT_BASE_MS, maxMs = DEFAULT_MAX_MS, timeoutMs = DEFAULT_TIMEOUT_MS,
+    sleep = (ms) => new Promise(r => setTimeout(r, ms)),
+    now = Date.now,
+    fetchImpl,
+    context,
+  } = opts;
+
+  const doFetch = fetchImpl ?? ((u, init) => fetch(u, init));
+  const ctx = context ? ` (${context})` : '';
+
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    let res;
+    try {
+      res = await doFetch(url, {
+        method, headers, body,
+        signal: timeoutMs > 0 ? AbortSignal.timeout(timeoutMs) : undefined,
+      });
+    } catch (err) {
+      // Network error / timeout — retry with backoff, else fail loud (secret-free).
+      if (attempt < maxAttempts) {
+        await sleep(retryDelayMs(0, null, attempt, { baseMs, maxMs, now }));
+        continue;
+      }
+      throw new Error(scrubSecrets(`GitHub API request failed${ctx}: ${err.message}`));
+    }
+
+    if (res.ok) return res;
+
+    const status = res.status;
+    const rateLimited = isRateLimitResponse(status, res.headers);
+    const transient = rateLimited || status >= 500;
+
+    if (transient && attempt < maxAttempts) {
+      await sleep(retryDelayMs(status, res.headers, attempt, { baseMs, maxMs, now }));
+      continue;
+    }
+
+    // Terminal: read the body once and throw a structured, secret-free error.
+    const bodyText = await safeText(res);
+    if (rateLimited) {
+      const body = scrubSecrets(String(bodyText ?? '').replace(/\s+/g, ' ').trim()).slice(0, 300);
+      throw new Error(
+        `GitHub API ${status} (rate limit exceeded)${ctx} — retries exhausted after ${attempt} attempt(s)` +
+        (body ? `: ${body}` : ''),
+      );
+    }
+    throw new Error(classifyGitHubError(status, res.statusText, bodyText, context));
+  }
+
+  // Defensive — the loop above always returns or throws.
+  throw new Error(`GitHub API request failed${ctx} — retries exhausted`);
+}