jamdesk 1.1.157 → 1.1.158

package/vendored/lib/r2-upload-lock.ts

@@ -0,0 +1,277 @@
+/**
+ * Redis NX upload lock with heartbeat-and-steal semantics — TS-native.
+ *
+ * Mirrors `scripts/lib/upload-lock.cjs` semantics but uses the @upstash/redis
+ * SDK via `lib/redis.ts` so the production ISR build path (build.ts +
+ * scripts/upload-content-to-r2.ts) can reuse the same wire-level behaviour
+ * without shelling out to the CJS path.
+ *
+ * Defense-in-depth against concurrent ISR uploads for the same project. Two
+ * builds racing the manifest read/write would stamp the wrong deployId into
+ * Redis and point readers at a half-uploaded R2 prefix. The Firebase Functions
+ * queue is supposed to serialize these, but it lives in a separate process;
+ * this lock is the fallback that catches mistakes and orchestration drift.
+ *
+ *   Lock key:        r2UploadLock:<projectName>
+ *   Lock value:      <deployId>:<startedAtMs>:<lastHeartbeatMs>
+ *   TTL:             600s (absolute ceiling so SIGKILL self-cleans)
+ *   Heartbeat:       30s (refreshes value + EX TTL)
+ *   Stale threshold: 90s (a holder whose heartbeat is older may be stolen)
+ *
+ * Best-effort: when Redis isn't configured (no @upstash/redis client) or a
+ * call throws, `acquireUploadLock` returns `{ acquired: false }` plus either
+ * `skipped: true` (no client) or `errored: true` (Redis threw) so the caller
+ * can degrade to "no lock" rather than block uploads on Upstash availability.
+ */
+
+import { redis } from './redis.js';
+import { logger } from '../shared/logger.js';
+
+export const STALE_AFTER_MS = 90_000;
+export const HEARTBEAT_INTERVAL_MS = 30_000;
+export const TTL_SECONDS = 600;
+
+export function lockKeyFor(projectName: string): string {
+  return `r2UploadLock:${projectName}`;
+}
+
+export function buildLockValue(
+  deployId: string,
+  startedAtMs: number,
+  heartbeatMs: number,
+): string {
+  return `${deployId}:${startedAtMs}:${heartbeatMs}`;
+}
+
+export interface AcquireResult {
+  acquired: boolean;
+  /** Redis call threw (network blip, outage). Caller should warn and proceed. */
+  errored?: boolean;
+  /** No Redis client configured. Caller should treat as "skip locking". */
+  skipped?: boolean;
+  error?: string;
+}
+
+interface AcquireArgs {
+  projectName: string;
+  deployId: string;
+  startedAtMs?: number;
+  now?: () => number;
+}
+
+interface ReleaseArgs {
+  projectName: string;
+  deployId: string;
+}
+
+interface HeartbeatArgs {
+  projectName: string;
+  deployId: string;
+  startedAtMs: number;
+  /** Called on lock theft (GET returns null OR a value not prefixed with our deployId). */
+  onTheft?: (current: unknown) => void;
+  now?: () => number;
+}
+
+/**
+ * Coerce `redis.get`'s parsed return to a string for prefix comparisons.
+ * The Upstash SDK auto-JSON-parses bodies, so a stored value like
+ * "deploy-abc:1:2" round-trips as the JS string "deploy-abc:1:2", but a
+ * value like "1234:5678:9012" *might* round-trip as a number depending on
+ * how the writer encoded it. String-coercing keeps the prefix check honest.
+ */
+function asString(value: unknown): string | null {
+  if (value === null || value === undefined) return null;
+  return String(value);
+}
+
+/**
+ * Try to acquire the lock for ${projectName}.
+ *
+ * Behaviour by case:
+ *   1. Lock free                                → SET NX returns 'OK', acquired.
+ *   2. Lock held, fresh holder                  → returns false.
+ *   3. Lock vanished between SET NX & GET       → retry SET NX once.
+ *   4. Lock held, holder is stale (>90s)        → SET (no NX) steals it; warns.
+ *   5. Lock value malformed (non-numeric ts)    → treat as fresh, returns false.
+ *
+ * Returns acquired:false errored:true on Redis throw so the caller can
+ * proceed without the lock — best-effort defense-in-depth, not a hard
+ * dependency. An Upstash outage must NOT block all uploads.
+ *
+ * Returns acquired:false skipped:true when Redis isn't configured (e.g. local
+ * dev without KV credentials) — same degradation path as the CJS lockEnabled
+ * check.
+ */
+export async function acquireUploadLock(
+  args: AcquireArgs,
+): Promise<AcquireResult> {
+  if (!redis) {
+    return { acquired: false, skipped: true };
+  }
+
+  const now = args.now ?? Date.now;
+  const startedAtMs = args.startedAtMs ?? now();
+  const key = lockKeyFor(args.projectName);
+
+  try {
+    const initial = await redis.set(
+      key,
+      buildLockValue(args.deployId, startedAtMs, startedAtMs),
+      { nx: true, ex: TTL_SECONDS },
+    );
+    if (initial === 'OK') return { acquired: true };
+
+    const currentRaw = await redis.get(key);
+    const current = asString(currentRaw);
+    if (current === null) {
+      // Lock was released between the failed SET NX and the GET. Retry once
+      // — concurrent racer might have just finished a tiny upload.
+      const retry = await redis.set(
+        key,
+        buildLockValue(args.deployId, startedAtMs, now()),
+        { nx: true, ex: TTL_SECONDS },
+      );
+      return { acquired: retry === 'OK' };
+    }
+
+    const parts = current.split(':');
+    const lastHeartbeat = Number(parts[2]);
+    if (
+      Number.isFinite(lastHeartbeat) &&
+      now() - lastHeartbeat > STALE_AFTER_MS
+    ) {
+      // Steal the stale lock. SET without NX overwrites; preserves TTL.
+      await redis.set(
+        key,
+        buildLockValue(args.deployId, startedAtMs, now()),
+        { ex: TTL_SECONDS },
+      );
+      const ageSec = Math.round((now() - lastHeartbeat) / 1000);
+      logger.warn(
+        `Stole stale upload lock for ${args.projectName} (last heartbeat ${ageSec}s ago)`,
+      );
+      return { acquired: true };
+    }
+
+    // Lock held by a fresh, live holder — or value malformed (Number.isFinite
+    // false). In both cases we abort: malformed values are not stealable
+    // because we can't tell if the writer is alive.
+    return { acquired: false };
+  } catch (err) {
+    return {
+      acquired: false,
+      errored: true,
+      error: err instanceof Error ? err.message : String(err),
+    };
+  }
+}
+
+/**
+ * Release the lock if and only if we still hold it (compare-and-delete).
+ * Best-effort: never throws. Caller is responsible for stopping the
+ * heartbeat timer BEFORE calling this so the timer doesn't race the
+ * release and re-extend the TTL after DEL.
+ */
+export async function releaseUploadLock(args: ReleaseArgs): Promise<void> {
+  if (!redis) return;
+  try {
+    const key = lockKeyFor(args.projectName);
+    const currentRaw = await redis.get(key);
+    const current = asString(currentRaw);
+    if (current && current.startsWith(`${args.deployId}:`)) {
+      await redis.del(key);
+    }
+  } catch {
+    // best-effort
+  }
+}
+
+/**
+ * Handle returned by `startHeartbeat`. `stop()` MUST be called before
+ * `releaseUploadLock` — clearing the interval alone is insufficient because
+ * a tick that started before clearInterval can still be suspended on
+ * `await redis.get` and would re-extend TTL after the lock has been DEL'd
+ * (issue M1 from the Phase 4 QA pass — non-corrupting but ~90s self-recovery
+ * via stale-steal). `stop()` flips an `aborted` flag the tick re-checks at
+ * every async boundary AND clears the timer so no new ticks fire.
+ */
+export interface HeartbeatHandle {
+  stop: () => void;
+}
+
+/**
+ * Start the heartbeat interval. Returns a handle whose `stop()` aborts
+ * any in-flight tick AND clears the timer.
+ *
+ * Each tick:
+ *   1. GETs the lock value.
+ *   2. If the value is missing or no longer prefixed with our deployId,
+ *      the lock has been stolen (or expired + re-acquired) — call onTheft
+ *      with the observed value so the caller can throw / abort cleanly.
+ *   3. Otherwise, SET (no NX) refreshes the heartbeat ms and bumps TTL.
+ *
+ * Default `onTheft` logs an error — callers are expected to provide a
+ * theft handler that throws or sets a flag the upload phase reads, so
+ * theft cleanly aborts the build instead of relying on `process.exit(2)`
+ * (which would skip the build's failure-reporting path).
+ *
+ * Transient Redis errors during a tick are swallowed: a single missed
+ * heartbeat shouldn't kill the build, and the 600s TTL is the backstop.
+ */
+export function startHeartbeat(args: HeartbeatArgs): HeartbeatHandle {
+  const { projectName, deployId, startedAtMs } = args;
+  const now = args.now ?? Date.now;
+  const onTheft =
+    args.onTheft ??
+    ((current: unknown) => {
+      logger.error(
+        `[r2-upload] lock stolen by another build (was: ${current})`,
+      );
+    });
+  const key = lockKeyFor(projectName);
+
+  let aborted = false;
+
+  const tick = async (): Promise<void> => {
+    if (aborted || !redis) return;
+    try {
+      const currentRaw = await redis.get(key);
+      // After every async boundary, re-check the abort flag. The release
+      // path flips it; a tick that resumed mid-flight must not call
+      // onTheft (would surface a stale theft signal) or extend TTL
+      // (would defeat the DEL).
+      if (aborted) return;
+      const current = asString(currentRaw);
+      if (!current || !current.startsWith(`${deployId}:`)) {
+        onTheft(current);
+        return;
+      }
+      const heartbeatMs = now();
+      if (aborted) return;
+      await redis.set(
+        key,
+        buildLockValue(deployId, startedAtMs, heartbeatMs),
+        { ex: TTL_SECONDS },
+      );
+    } catch {
+      // Transient Redis error — swallow. TTL backstop covers worst case.
+    }
+  };
+
+  const timer = setInterval(() => {
+    tick().catch(() => {
+      // Already swallowed inside tick(); this catch is for the ESLint
+      // floating-promise rule on setInterval callbacks.
+    });
+  }, HEARTBEAT_INTERVAL_MS);
+  // Don't keep the event loop alive for the heartbeat alone.
+  if (typeof timer.unref === 'function') timer.unref();
+
+  return {
+    stop: () => {
+      aborted = true;
+      clearInterval(timer);
+    },
+  };
+}

package/vendored/lib/revalidation-helpers.ts

@@ -13,6 +13,7 @@ import { clearProjectCache as clearMcpProjectCache, clearCache as clearMcpCache
 import { clearNavigationCache } from './navigation-resolver';
 import { STATIC_REVALIDATION_PATHS } from './static-file-route';
 import { clearRedirectCache } from './redirect-matcher';
+import { clearProjectDeployIdCache } from './project-deploy-id';
 import { mdxCacheTag, projectCacheTag } from './cache-tags';
 
 /**
@@ -132,6 +133,11 @@ export async function executeRevalidation(
 
   if (isWholeProjectClear) {
     const project = request.project!;
+    // Evict the deployId pointer LRU first: cached fetchers key the Data
+    // Cache on the resolved deployId, so a ≤30s-stale pointer on this
+    // instance would otherwise keep reads pinned to the previous deploy's
+    // (dead) cache keys until the LRU TTL lapses.
+    clearProjectDeployIdCache(project);
     clearConfigCache(project);
     clearSnippetCache(project);
     clearOpenApiCache(project);
@@ -193,6 +199,7 @@ export async function executeRevalidation(
     clearOpenApiCache();
     clearMcpCache();
     clearNavigationCache();
+    clearProjectDeployIdCache();
     await clearRedirectCache();
     if (revalidatePath) {
       revalidatePath('/', 'layout');

package/vendored/lib/revalidation-trigger.ts

@@ -4,6 +4,9 @@
  */
 
 import { log } from './logger.js';
+import { redis } from './redis.js';
+
+export const DEPLOY_FLIP_TAG = '[deploy-flip]';
 
 export interface RevalidationOptions {
   projectSlug: string;
@@ -56,6 +59,115 @@ export async function triggerRevalidation(options: RevalidationOptions): Promise
   });
 }
 
+/**
+ * Permanent revalidation failure after all retry attempts.
+ *
+ * Signals to the build orchestrator that Vercel Data Cache may now be serving
+ * stale `DocsConfig` (which references the OLD `projectDeployId` for nested
+ * asset URLs). The build is marked `succeeded_with_warnings` rather than
+ * silently degrading — there's no automatic recovery because the cache key
+ * is `[config, slug]`, not deployId-keyed.
+ */
+export class RevalidationFailedError extends Error {
+  constructor(public readonly slug: string, public readonly cause: Error) {
+    super(`Revalidation failed permanently for ${slug}: ${cause.message}`);
+    this.name = 'RevalidationFailedError';
+  }
+}
+
+/**
+ * Wraps `triggerRevalidation` with bounded retry + escalation.
+ *
+ * On every successful flip of `projectDeployId` in Redis the build pipeline
+ * MUST flush Vercel Data Cache via `revalidateTag(projectCacheTag(slug))`,
+ * or readers keep serving the OLD config (asset URLs refer to the previous
+ * deployId, breaking the new build for cached pages).
+ *
+ * This wrapper:
+ *   1. Calls `triggerRevalidation`. On rejection, sleeps `1s * attemptIndex`
+ *      and retries up to `attempts` total.
+ *   2. On permanent failure, best-effort SETs `revalidationFailure:<slug>`
+ *      in Redis with a 24h TTL so dashboards/on-call can surface it.
+ *   3. Throws `RevalidationFailedError` so the build orchestrator can mark
+ *      the build `succeeded_with_warnings` instead of swallowing the error.
+ */
+export async function triggerRevalidationWithRetry(
+  options: RevalidationOptions,
+  attempts = 2,
+): Promise<void> {
+  log('info', `${DEPLOY_FLIP_TAG} revalidation triggered`, { projectSlug: options.projectSlug });
+
+  let lastError: Error | undefined;
+  for (let attempt = 1; attempt <= attempts; attempt++) {
+    try {
+      await triggerRevalidation(options);
+      // Success path: clear any prior `revalidationFailure:<slug>` flag so
+      // dashboards/on-call don't see stale alerts after the next clean build.
+      // Best-effort — the flag has a 24h TTL so it self-clears regardless.
+      await clearRevalidationFailureFlag(options.projectSlug);
+      return;
+    } catch (err) {
+      lastError = err instanceof Error ? err : new Error(String(err));
+      if (attempt < attempts) {
+        log('warn', `${DEPLOY_FLIP_TAG} revalidation failed, retrying`, {
+          projectSlug: options.projectSlug,
+          attempt,
+          error: lastError.message,
+        });
+        // Linear backoff: 1s before attempt 2, 2s before attempt 3, etc.
+        // Bounded retry — short sleep is fine; the orchestrator already
+        // gates this phase with a phase-level timer.
+        await new Promise((resolve) => setTimeout(resolve, 1000 * attempt));
+      }
+    }
+  }
+
+  // All attempts exhausted — escalate.
+  const cause = lastError ?? new Error('Revalidation failed (unknown cause)');
+  log('error', `${DEPLOY_FLIP_TAG} revalidation failed permanently — stale Data Cache risk`, {
+    projectSlug: options.projectSlug,
+    error: cause.message,
+  });
+
+  // Best-effort flag write: if Redis is unconfigured or throws, swallow —
+  // the throw below is the load-bearing escalation path.
+  try {
+    if (redis) {
+      const payload = JSON.stringify({
+        at: new Date().toISOString(),
+        error: cause.message,
+      });
+      await redis.set(`revalidationFailure:${options.projectSlug}`, payload, {
+        ex: 86400, // 24h TTL — dashboards/on-call can surface within a day.
+      });
+    }
+  } catch (flagErr) {
+    log('warn', `${DEPLOY_FLIP_TAG} failed to write revalidationFailure flag (non-fatal)`, {
+      projectSlug: options.projectSlug,
+      error: flagErr instanceof Error ? flagErr.message : String(flagErr),
+    });
+  }
+
+  throw new RevalidationFailedError(options.projectSlug, cause);
+}
+
+/**
+ * DEL the 24h `revalidationFailure:<slug>` alert flag. Called on the
+ * success path so a recovery build clears the alert from a prior failure.
+ * Best-effort: never throws. DEL on a non-existent key is a no-op.
+ */
+async function clearRevalidationFailureFlag(slug: string): Promise<void> {
+  if (!redis) return;
+  try {
+    await redis.del(`revalidationFailure:${slug}`);
+  } catch (err) {
+    log('warn', `${DEPLOY_FLIP_TAG} failed to clear revalidationFailure flag (non-fatal)`, {
+      projectSlug: slug,
+      error: err instanceof Error ? err.message : String(err),
+    });
+  }
+}
+
 async function revalidateIsrApp(
   isrAppUrl: string,
   secret: string,

package/vendored/shared/status-reporter.ts

@@ -29,6 +29,7 @@ export const BUILD_WARNING_TYPES = [
   'missing_image',
   'missing_page',
   'missing_openapi_ref',
+  'revalidation_failed',
   'inline_code_on_api_page',
   'invalid_openapi_spec',
   'missing_snippet',

package/vendored/themes/base.css

@@ -221,6 +221,28 @@
   margin-bottom: 0.8rem;
 }
 
+/* Card body typography — must apply at FIRST PAINT.
+   Keep in sync with the same rules in Card.tsx's styled-jsx (they exist there
+   so the styles travel with the vendored component; they exist here so they
+   apply at first paint — Next.js dev injects styled-jsx only AFTER first paint,
+   so card paragraphs would briefly inherit the looser .prose line-height/margins
+   and the card would visibly shrink on load). These bare selectors sit after
+   `.prose p` above, so they win by source order (margins) or specificity
+   (:last-child) and also cover cards rendered outside .prose. */
+.card-content > p {
+  line-height: 1.375;
+  margin: 0 0 0.75rem 0;
+}
+.card-content > p:last-child {
+  margin-bottom: 0;
+}
+.card-content > *:first-child {
+  margin-top: 0;
+}
+.card-content > *:last-child {
+  margin-bottom: 0;
+}
+
 /* Links */
 .prose a {
   color: var(--color-text-primary);

package/vendored/themes/jam/variables.css

@@ -372,7 +372,7 @@ html:not(.dark) body[data-theme="jam"]:not([data-decoration="none"]):not([data-d
 
 /* Prose body */
 body[data-theme="jam"] .prose {
-  font-family: var(--font-sans, 'Inter'), sans-serif;
+  font-family: var(--font-sans, var(--font-primary, 'Inter')), sans-serif;
   font-size: var(--prose-body-size);
   line-height: var(--prose-body-line-height);
   font-weight: var(--prose-body-weight);
@@ -382,7 +382,7 @@ body[data-theme="jam"] .prose {
 /* Prose headings */
 body[data-theme="jam"] .prose h1,
 body[data-theme="jam"] h1 {
-  font-family: var(--font-heading, var(--font-sans, 'Inter')), sans-serif;
+  font-family: var(--font-heading, var(--font-sans, var(--font-primary, 'Inter'))), sans-serif;
   font-size: var(--prose-h1-size);
   line-height: var(--prose-h1-line-height);
   font-weight: var(--prose-h1-weight);
@@ -391,7 +391,7 @@ body[data-theme="jam"] h1 {
 }
 
 body[data-theme="jam"] .prose h2 {
-  font-family: var(--font-heading, var(--font-sans, 'Inter')), sans-serif;
+  font-family: var(--font-heading, var(--font-sans, var(--font-primary, 'Inter'))), sans-serif;
   font-size: var(--prose-h2-size);
   line-height: var(--prose-h2-line-height);
   font-weight: var(--prose-h2-weight);
@@ -400,7 +400,7 @@ body[data-theme="jam"] .prose h2 {
 }
 
 body[data-theme="jam"] .prose h3 {
-  font-family: var(--font-heading, var(--font-sans, 'Inter')), sans-serif;
+  font-family: var(--font-heading, var(--font-sans, var(--font-primary, 'Inter'))), sans-serif;
   font-size: var(--prose-h3-size);
   line-height: var(--prose-h3-line-height);
   font-weight: var(--prose-h3-weight);
@@ -409,7 +409,7 @@ body[data-theme="jam"] .prose h3 {
 }
 
 body[data-theme="jam"] .prose h4 {
-  font-family: var(--font-heading, var(--font-sans, 'Inter')), sans-serif;
+  font-family: var(--font-heading, var(--font-sans, var(--font-primary, 'Inter'))), sans-serif;
   font-size: var(--prose-h4-size);
   line-height: var(--prose-h4-line-height);
   font-weight: var(--prose-h4-weight);

package/vendored/themes/pulsar/variables.css

@@ -175,7 +175,7 @@
 
 /* Prose body */
 .prose {
-  font-family: var(--font-sans, 'Inter'), sans-serif;
+  font-family: var(--font-sans, var(--font-primary, 'Inter')), sans-serif;
   font-size: var(--prose-body-size);
   line-height: var(--prose-body-line-height);
   font-weight: var(--prose-body-weight);
@@ -185,7 +185,7 @@
 /* Prose headings */
 .prose h1,
 h1 {
-  font-family: var(--font-heading, var(--font-sans, 'Inter')), sans-serif;
+  font-family: var(--font-heading, var(--font-sans, var(--font-primary, 'Inter'))), sans-serif;
   font-size: var(--prose-h1-size);
   line-height: var(--prose-h1-line-height);
   font-weight: var(--prose-h1-weight);
@@ -194,7 +194,7 @@ h1 {
 }
 
 .prose h2 {
-  font-family: var(--font-heading, var(--font-sans, 'Inter')), sans-serif;
+  font-family: var(--font-heading, var(--font-sans, var(--font-primary, 'Inter'))), sans-serif;
   font-size: var(--prose-h2-size);
   line-height: var(--prose-h2-line-height);
   font-weight: var(--prose-h2-weight);
@@ -203,7 +203,7 @@ h1 {
 }
 
 .prose h3 {
-  font-family: var(--font-heading, var(--font-sans, 'Inter')), sans-serif;
+  font-family: var(--font-heading, var(--font-sans, var(--font-primary, 'Inter'))), sans-serif;
   font-size: var(--prose-h3-size);
   line-height: var(--prose-h3-line-height);
   font-weight: var(--prose-h3-weight);
@@ -212,7 +212,7 @@ h1 {
 }
 
 .prose h4 {
-  font-family: var(--font-heading, var(--font-sans, 'Inter')), sans-serif;
+  font-family: var(--font-heading, var(--font-sans, var(--font-primary, 'Inter'))), sans-serif;
   font-size: var(--prose-h4-size);
   line-height: var(--prose-h4-line-height);
   font-weight: var(--prose-h4-weight);