jamdesk 1.1.156 → 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/render-doc-page.tsx

@@ -84,6 +84,7 @@ import {
   type AuthMethod,
 } from '@/lib/openapi';
 import { classifyOpenApiLoadError } from '@/lib/openapi/classify-load-error';
+import { findOperation, deriveOperationDescription, collectLocalSpecPaths } from '@/lib/openapi/operation-description';
 import { extractLanguageFromPath, isValidLanguageCode } from '@/lib/language-utils';
 import { findFirstNavPage } from '@/lib/find-first-nav-page';
 import { candidateSpecPaths } from '@/lib/openapi/lang-spec-path';
@@ -210,6 +211,47 @@ function resolveSlug(normalizedSlug: string[], config: DocsConfig): string[] {
   return normalizedSlug;
 }
 
+/**
+ * Resolve a page `<meta>`/og description from its OpenAPI operation when the
+ * page has no frontmatter `description`. Pure: the spec loader is injected so
+ * this is unit-testable independent of the render path (and so `buildDocMetadata`
+ * can hand it the SAME cached loader the renderer uses — no extra spec fetch).
+ *
+ * `loadSpec` MUST be a cached loader (see `buildDocMetadata` wiring): docs
+ * routes are `force-dynamic`, so this runs on every page view; an uncached
+ * fetch+parse here would add an R2 round-trip per render. Remote (`http(s)://`)
+ * spec entries are dropped — they are fetched by the renderer, never resolvable
+ * as a meta-time read. Returns null on any unresolvable/unparseable input so the
+ * caller degrades to `generateAutoDescription`.
+ */
+export async function resolveOpenApiMetaDescription(
+  openapiRef: string,
+  specPaths: string[],
+  loadSpec: (specPath: string) => Promise<unknown | null>,
+): Promise<string | null> {
+  const local = specPaths.filter((p) => !/^https?:\/\//i.test(p));
+  if (local.length === 0) return null;
+  let parsed;
+  try {
+    parsed = parseOpenApiFrontmatter(openapiRef, local);
+  } catch {
+    return null;
+  }
+  // Full-format ref carries its own spec path; short-format must try each
+  // configured spec until the operation resolves.
+  const candidates = parsed.isShortFormat ? local : [parsed.specPath];
+  for (const sp of candidates) {
+    if (!sp) continue;
+    const spec = await loadSpec(sp);
+    if (!spec) continue;
+    const op = findOperation(spec, parsed.method, parsed.path);
+    if (!op) continue;
+    const d = deriveOperationDescription(op);
+    if (d) return d;
+  }
+  return null;
+}
+
 export async function buildDocMetadata(input: RenderInput): Promise<Metadata> {
   const { slug: slugInput, projectSlug, hostAtDocs, requestHeaders } = input;
 
@@ -252,7 +294,44 @@ export async function buildDocMetadata(input: RenderInput): Promise<Metadata> {
   const data = parsed.data as FrontmatterData;
 
   if (!data.description) {
-    data.description = generateAutoDescription(parsed.content);
+    if (typeof data.openapi === 'string' && data.openapi && config.api?.openapi) {
+      // Source the description from the OpenAPI operation before falling back to
+      // first-paragraph extraction (which is empty for prose-less API pages).
+      // The spec loader REUSES the render path's cached loaders — the ISR module
+      // cache (`r2:${slug}:${specPath}`, 10-min TTL) that `renderDocPage`
+      // populates when it renders the page's <ApiEndpoint>, or the static
+      // `getCachedSpec`. So the spec is the same warm parse the render already
+      // did: the marginal cost of this lookup is a cache hit, never an uncached
+      // fetch+parse. That matters because docs routes are force-dynamic, so this
+      // metadata runs on EVERY page view (every human + crawler). Mirrors the
+      // `useIsr`/`projectDir` derivation in `renderDocPage`'s OpenAPI branch.
+      const specPaths = collectLocalSpecPaths(config.api.openapi);
+      const useIsr = isIsrMode() && !!projectSlug;
+      const projectDir = useIsr ? null : getContentDir();
+      const loadSpecForMeta = async (sp: string): Promise<unknown | null> => {
+        try {
+          if (useIsr && projectSlug) {
+            const { resolveOpenApiSpec } = await import('@/lib/openapi-isr');
+            return await resolveOpenApiSpec(projectSlug, sp);
+          }
+          if (projectDir) {
+            const { api } = await getCachedSpec(sp, projectDir);
+            return api;
+          }
+          return null;
+        } catch {
+          // Any load/parse error degrades to generateAutoDescription below.
+          return null;
+        }
+      };
+      const sourced = await resolveOpenApiMetaDescription(
+        data.openapi, specPaths, loadSpecForMeta,
+      );
+      if (sourced) data.description = sourced;
+    }
+    if (!data.description) {
+      data.description = generateAutoDescription(parsed.content);
+    }
   }
 
   const baseUrl = resolveBaseUrl(requestHeaders, projectSlug, hostAtDocs);

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/lib/static-artifacts.ts

@@ -436,14 +436,20 @@ export interface RawPageInfo {
  * @param pages - Array of raw page info
  * @returns Array of page metadata
  */
-export function extractPageMetadata(pages: RawPageInfo[]): PageMetadata[] {
+export function extractPageMetadata(
+  pages: RawPageInfo[],
+  sourced?: Map<string, {description: string}>,
+): PageMetadata[] {
   return pages.map(page => {
     const pathWithoutExt = page.path.replace(/\.mdx?$/, '');
 
     return {
       path: pathWithoutExt,
       title: page.frontmatter.title || pathWithoutExt,
-      description: page.frontmatter.description,
+      // Frontmatter wins; else fall back to a description sourced from the
+      // page's OpenAPI operation (keyed by the extension-ful page.path).
+      description:
+        page.frontmatter.description ?? sourced?.get(page.path)?.description,
       noindex: page.frontmatter.noindex || page.frontmatter.seo?.noindex,
       hidden: page.frontmatter.hidden,
       lastModified: page.frontmatter.lastModified,

package/vendored/lib/validate-page-frontmatter.ts

@@ -1,14 +1,20 @@
 import type { BuildWarning } from '../shared/status-reporter.js'; // vendored copy — NOT '../../shared'
+import { MIN_FRONTMATTER_DESCRIPTION_CHARS } from './openapi/operation-description.js';
 
 const MIN_DESCRIPTION_CHARS = 110; // matches the Ahrefs "too short" floor used elsewhere
+// Task 1 invariant: MIN_DESCRIPTION_CHARS must equal MIN_FRONTMATTER_DESCRIPTION_CHARS.
+// Asserted by test. Do NOT change either value without updating both.
 
 interface PageInfo {
   path: string;
-  frontmatter: { title?: unknown; description?: unknown; hidden?: unknown };
+  frontmatter: { title?: unknown; description?: unknown; hidden?: unknown; openapi?: unknown };
   content: string;
 }
 
-export function validatePageFrontmatter(pages: PageInfo[]): BuildWarning[] {
+export function validatePageFrontmatter(
+  pages: PageInfo[],
+  sourced?: Map<string, { description: string; length: number }>,
+): BuildWarning[] {
   const warnings: BuildWarning[] = [];
   for (const page of pages) {
     const fm = page.frontmatter ?? {};
@@ -21,7 +27,37 @@ export function validatePageFrontmatter(pages: PageInfo[]): BuildWarning[] {
       warnings.push({ type: 'page_missing_title', file: page.path, message: 'Page has no frontmatter title; navigation and llms.txt fall back to the file path.' });
     }
     if (!description) {
-      warnings.push({ type: 'page_missing_description', file: page.path, message: 'Page has no frontmatter description; add one for SEO and llms.txt.' });
+      const src = sourced?.get(page.path);
+      if (src) {
+        if (src.length >= MIN_FRONTMATTER_DESCRIPTION_CHARS) {
+          // Cat 1: OpenAPI-sourced description is long enough for Fix-with-AI to write
+          // into frontmatter — keep the warning but re-message it toward that action.
+          warnings.push({
+            type: 'page_missing_description',
+            file: page.path,
+            message: "No frontmatter description — your page's description is auto-sourced " +
+              "from your OpenAPI spec. Use Fix with AI to write it into the page for portability.",
+          });
+        } else {
+          // Cat 2: sourced text IS live in <meta>/llms, but too short to commit via
+          // Fix-with-AI. Do NOT suppress — the author still needs a longer description.
+          // A sourced-short description must warn no less than an authored-short one
+          // (else `summary: "TODO"` silently becomes the live meta + OG card with zero
+          // signal to fix it).
+          warnings.push({
+            type: 'page_missing_description',
+            file: page.path,
+            message:
+              `Description auto-sourced from your OpenAPI spec is only ` +
+              `${src.length} chars — add a longer frontmatter description ` +
+              `(aim for ${MIN_FRONTMATTER_DESCRIPTION_CHARS}–160; too short ` +
+              `for Fix with AI to write into the page).`,
+          });
+        }
+      } else {
+        // Cat 3: genuinely missing, nothing to source from the spec.
+        warnings.push({ type: 'page_missing_description', file: page.path, message: 'Page has no frontmatter description; add one for SEO and llms.txt.' });
+      }
     } else if (description.length < MIN_DESCRIPTION_CHARS) {
       warnings.push({ type: 'page_short_description', file: page.path, message: `Description is ${description.length} chars; aim for ${MIN_DESCRIPTION_CHARS}–160.` });
     }

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);