jamdesk 1.1.155 → 1.1.157

package/vendored/lib/openapi/operation-description.ts

@@ -0,0 +1,110 @@
+// builder/build-service/lib/openapi/operation-description.ts
+//
+// Pure, dependency-free helpers for deriving a page meta description from an
+// OpenAPI operation. Used by the build-service (llms.txt, <meta>, warning
+// re-messaging) AND — vendored verbatim — by the dashboard Fix-with-AI
+// pipeline, so both surfaces agree on the exact text and the length gate.
+//
+// IMPORT-FREE of `@/` aliases: vendor-openapi.mjs (exit 1 on `@/`) copies this
+// file into dashboard/functions/src/editor/openapi/. Keep it self-contained.
+
+/** Frontmatter descriptions shorter than this flag `page_short_description`.
+ *  MUST equal MIN_DESCRIPTION_CHARS in validate-page-frontmatter.ts (asserted
+ *  by a test). A sourced description is WRITTEN into frontmatter (Slice 3) only
+ *  when its cleaned length is >= this, so the write never trades a "missing"
+ *  warning for a "too short" one. */
+export const MIN_FRONTMATTER_DESCRIPTION_CHARS = 110;
+
+/** Search engines truncate meta descriptions around 155-160 chars. */
+const MAX_META_DESCRIPTION_CHARS = 160;
+
+/** The two operation fields we read. Loose types: specs are untrusted input. */
+export interface OperationSummary {
+  summary?: unknown;
+  description?: unknown;
+}
+
+/** Minimum chars before a sentence/word boundary is worth cutting to (avoids
+ *  truncating to a tiny fragment like "OK."). Matches the word-boundary floor. */
+const MIN_TRUNCATION_CHARS = 40;
+
+/** Reduce markdown to plain prose fit for a <meta>/llms description: drop
+ *  fenced+inline code, images, links (keep the text), headings/list/blockquote
+ *  markers and emphasis; collapse whitespace. If over the limit, prefer ending
+ *  on a COMPLETE SENTENCE within the limit (no ellipsis — it's a whole thought);
+ *  else cut on a word boundary with an ellipsis. "" for empty input.
+ *  All scanning is O(n) char-by-char — deliberately no truncation regex, to
+ *  avoid the catastrophic-backtracking class this repo has been bitten by. */
+export function cleanMetaDescription(text: string): string {
+  let s = text;
+  s = s.replace(/```[\s\S]*?```/g, " "); // fenced code blocks
+  s = s.replace(/`([^`]+)`/g, "$1"); // inline code
+  s = s.replace(/!\[[^\]]*\]\([^)]*\)/g, " "); // images
+  s = s.replace(/\[([^\]]+)\]\([^)]*\)/g, "$1"); // links -> link text
+  s = s.replace(/^[ \t]*[#>*\-+]+[ \t]*/gm, ""); // heading/quote/list markers
+  s = s.replace(/[*_~]+/g, ""); // emphasis runs
+  s = s.replace(/\s+/g, " ").trim(); // collapse all whitespace
+  if (s.length <= MAX_META_DESCRIPTION_CHARS) return s;
+  const cut = s.slice(0, MAX_META_DESCRIPTION_CHARS);
+  // Last sentence terminator (.?!) that is followed by a space or end-of-cut.
+  let sentenceEnd = -1;
+  for (let i = 0; i < cut.length; i++) {
+    const c = cut[i];
+    if ((c === "." || c === "!" || c === "?") &&
+        (i + 1 >= cut.length || cut[i + 1] === " ")) {
+      sentenceEnd = i;
+    }
+  }
+  if (sentenceEnd >= MIN_TRUNCATION_CHARS) {
+    return cut.slice(0, sentenceEnd + 1).trimEnd(); // complete sentence, no ellipsis
+  }
+  const lastSpace = cut.lastIndexOf(" ");
+  return (lastSpace > MIN_TRUNCATION_CHARS ? cut.slice(0, lastSpace) : cut)
+    .trimEnd() + "…";
+}
+
+/** Operation description (preferred) or summary (fallback), cleaned. null when
+ *  neither yields non-empty text. No length gate — callers apply their own. */
+export function deriveOperationDescription(
+  op: OperationSummary,
+): string | null {
+  const desc =
+    typeof op.description === "string" ? cleanMetaDescription(op.description) : "";
+  if (desc) return desc;
+  const summary =
+    typeof op.summary === "string" ? cleanMetaDescription(op.summary) : "";
+  return summary || null;
+}
+
+/** Look up an operation by method+path in a parsed (not necessarily
+ *  dereferenced) OpenAPI document. Tolerant of unknown shapes. Method is
+ *  case-insensitive. null if not present. */
+export function findOperation(
+  spec: unknown,
+  method: string,
+  path: string,
+): OperationSummary | null {
+  if (!spec || typeof spec !== "object") return null;
+  const paths = (spec as {paths?: unknown}).paths;
+  if (!paths || typeof paths !== "object") return null;
+  const pathItem = (paths as Record<string, unknown>)[path];
+  if (!pathItem || typeof pathItem !== "object") return null;
+  const op = (pathItem as Record<string, unknown>)[method.toLowerCase()];
+  if (!op || typeof op !== "object") return null;
+  return op as OperationSummary;
+}
+
+/** Normalize `config.api.openapi` (string | string[] | undefined) to the list
+ *  of repo-relative spec paths a build/fix pipeline can read. Drops remote
+ *  `http(s)://` URLs — those are fetched by the renderer, never present as
+ *  local blobs. Lives here (shared, vendored) so the build-service and the
+ *  dashboard apply an identical remote-skip rule. */
+export function collectLocalSpecPaths(apiOpenapi: unknown): string[] {
+  const raw =
+    typeof apiOpenapi === "string"
+      ? [apiOpenapi]
+      : Array.isArray(apiOpenapi)
+        ? apiOpenapi.filter((s): s is string => typeof s === "string")
+        : [];
+  return raw.filter((p) => !/^https?:\/\//i.test(p));
+}

package/vendored/lib/r2-content.ts

@@ -77,3 +77,9 @@ export function withR2OpsContext<T>(fn: () => T): T { return fn(); }
 export function enterR2OpsContextForTest<T>(fn: () => T): T { return fn(); }
 export function emitR2OpsSummary(_phase: R2TimingPhase, _projectSlug?: string | null): void {}
 export async function withTimeout<T>(promise: Promise<T>, _operation: string): Promise<T> { return promise; }
+// Pure helper (no AWS SDK) — mirror the real impl so docs-config timeout parsing
+// behaves identically in CLI dev as in prod.
+export function resolveR2Timeout(raw: string | undefined): number {
+  const parsed = parseInt((raw ?? '').trim(), 10);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : 5000;
+}

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/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/themes/jam/variables.css

@@ -710,6 +710,17 @@ body[data-theme="jam"] .sidebar-scroll .sidebar-nav-groups > div:first-child {
   margin-top: 0 !important;
 }
 
+/* When the nav groups are the first thing in the sidebar (no left tabs / external
+   anchors), align the first group heading with the breadcrumb + "On this page" TOC
+   heading, both of which sit 40px down via the content/TOC `py-10` wrapper. The
+   base 16px above is the tabs→groups gap for the sidebar-tabs case, so only bump
+   the first-child, desktop-only path here. */
+@media (min-width: 1024px) {
+  body[data-theme="jam"] .sidebar-scroll nav > .sidebar-nav-groups:first-child {
+    padding-top: 2.5rem !important;
+  }
+}
+
 /* Sidebar scroll container positioning for header-logo layout */
 /* The sidebar-scroll div needs constrained height to scroll independently */
 /* When tabs exist at top, sidebar needs more top offset (header 57px + tabs 57px = 114px) */

package/vendored/themes/nebula/variables.css

@@ -294,3 +294,13 @@ body[data-theme="nebula"] .sidebar-scroll .sidebar-nav-groups > div.ml-6 {
   padding-top: 16px;
 }
 
+/* When the nav groups are the first thing in the sidebar (no left tabs / external
+   anchors), align the first group heading with the breadcrumb + "On this page" TOC
+   heading, both 40px down via the content/TOC `py-10` wrapper. The 16px above is the
+   inter-group gap, so only the first group on desktop gets the larger offset. */
+@media (min-width: 1024px) {
+  body[data-theme="nebula"] .sidebar-scroll nav > .sidebar-nav-groups:first-child > div.ml-6:first-child {
+    padding-top: 2.5rem;
+  }
+}
+