jamdesk 1.1.213 → 1.1.214

package/dist/lib/deps.js

@@ -116,7 +116,7 @@ export const REQUIRED_DEPS = {
     'jose': '^6.2.3',
     // TypeScript (needed for Next.js to avoid auto-install breaking symlink)
     'typescript': 'npm:@typescript/typescript6@^6.0.2',
-    '@types/node': '^26.4.1',
+    '@types/node': '^26.6.3',
     '@types/react': '^19.2.18',
     '@types/react-dom': '^19.2.5',
     '@next/third-parties': '^16.3.4',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jamdesk",
-  "version": "1.1.213",
+  "version": "1.1.214",
   "description": "CLI for Jamdesk — build, preview, and deploy documentation sites from MDX. Dev server with hot reload, 50+ components, OpenAPI support, AI search, and Mintlify migration",
   "keywords": [
     "jamdesk",
@@ -106,7 +106,7 @@
     "@inquirer/prompts": "^8.7.2",
     "ajv": "^8.17.1",
     "ajv-formats": "^3.0.1",
-    "chalk": "^6.0.0",
+    "chalk": "^6.0.1",
     "commander": "^15.0.0",
     "dictionary-en": "^4.0.0",
     "estree-util-visit": "^2.0.0",
@@ -129,7 +129,7 @@
   "devDependencies": {
     "@mdx-js/mdx": "^3.1.1",
     "@types/fs-extra": "^11.0.0",
-    "@types/node": "^26.4.1",
+    "@types/node": "^26.6.3",
     "@typescript/native": "npm:typescript@^7.0.2",
     "typescript": "npm:@typescript/typescript6@^6.0.2",
     "vitest": "^4.1.11"

package/vendored/app/api/markdown-export/[project]/[...slug]/route.ts

@@ -20,6 +20,7 @@ import { apiSpecsMarkdownFooter } from '@/lib/api-specs-markdown-hint';
 import { collectLocalSpecPaths } from '@/lib/openapi/operation-description';
 import { operationMarkdownForRef } from '@/lib/openapi/enrich-page-infos';
 import { injectAgentDirective } from '@/lib/agent-directive';
+import { absolutizeMarkdownLinks } from '@/lib/markdown-absolute-links';
 import { resolveMarkdownFallbackPath } from '@/lib/root-page-slug';
 import { logger } from '@/shared/logger';
 import type { DocsConfig } from '@/lib/docs-types';
@@ -153,7 +154,9 @@ export async function GET(
   // path returns whatever the source MDX happened to end with. 107 of snag's
   // 115 exports shipped without it, so anything appending to or concatenating
   // these files ran the last line of one into the next.
-  const body = `${hinted.replace(/\s+$/, '')}\n`;
+  // Last, so links in the appended OpenAPI operation content are covered too.
+  const linked = absolutizeLinks(hinted, request.headers, project, hostAtDocs, linkPrefix);
+  const body = `${linked.replace(/\s+$/, '')}\n`;
 
   // Two paths reach this handler via proxy rewrite:
   //   (a) `.md` URL: unique CDN cache key, safe to share.
@@ -177,6 +180,33 @@ export async function GET(
   });
 }
 
+/**
+ * Root-relative links in the export become absolute URLs on the host the
+ * reader asked for (see absolutizeMarkdownLinks for why). ISR only: `jamdesk
+ * dev` serves from localhost over http, and getBaseUrl always builds https.
+ * The base comes from getBaseUrl, the same trusted-header resolution the
+ * api-specs footer and canonical tags use, so a custom domain's own prefix
+ * wins over the subdomain's. Never throws.
+ */
+function absolutizeLinks(
+  markdown: string,
+  headers: Headers,
+  project: string,
+  hostAtDocs: boolean,
+  linkPrefix: string,
+): string {
+  if (!isIsrMode()) return markdown;
+  try {
+    return absolutizeMarkdownLinks(markdown, getBaseUrl(headers, project, hostAtDocs), linkPrefix);
+  } catch (err) {
+    logger.warn('[markdown-export] link absolutize skipped', {
+      project,
+      error: err instanceof Error ? err.message : String(err),
+    });
+    return markdown;
+  }
+}
+
 /**
  * The two shapes fetchMdxContent throws for a missing page — the
  * `Page not found: …` message the S3 path builds and the error names the

package/vendored/components/mdx/Tooltip.tsx

@@ -26,6 +26,7 @@ export function Tooltip({
   const linkPrefix = useLinkPrefix();
   const [isVisible, setIsVisible] = useState(false);
   const [position, setPosition] = useState<'top' | 'bottom'>('top');
+  const [shiftX, setShiftX] = useState(0);
   const triggerRef = useRef<HTMLSpanElement>(null);
   const tooltipRef = useRef<HTMLSpanElement>(null);
   const tooltipId = useId();
@@ -39,6 +40,19 @@ export function Tooltip({
 
       // Show below if not enough space above
       setPosition(spaceAbove < tooltipHeight + 8 ? 'bottom' : 'top');
+
+      // The popover is centered on the trigger, so a trigger near the edge of
+      // the content column pushes half of it past the column's overflow edge,
+      // where it is clipped. Shift it back inside the nearest clipping
+      // ancestor (the viewport if there is none); the arrow counter-shifts so
+      // it still points at the trigger.
+      const bounds = clippingBounds(triggerRef.current);
+      const center = triggerRect.left + triggerRect.width / 2;
+      const halfWidth = tooltipRef.current.offsetWidth / 2;
+      const margin = 8;
+      const overflowLeft = bounds.left + margin - (center - halfWidth);
+      const overflowRight = center + halfWidth - (bounds.right - margin);
+      setShiftX(overflowLeft > 0 ? overflowLeft : overflowRight > 0 ? -overflowRight : 0);
     }
   }, [isVisible]);
 
@@ -64,7 +78,7 @@ export function Tooltip({
         ref={tooltipRef}
         id={tooltipId}
         role="tooltip"
-        style={{ boxShadow: 'var(--shadow-lg)', display: 'block' }}
+        style={{ boxShadow: 'var(--shadow-lg)', display: 'block', marginLeft: `${shiftX}px` }}
         className={`absolute z-50 w-64 p-3 rounded-lg border border-[var(--color-border)] bg-[var(--color-bg-primary)] transition-all duration-150 ${
           position === 'top'
             ? 'bottom-full left-1/2 -translate-x-1/2 mb-2'
@@ -99,6 +113,7 @@ export function Tooltip({
 
         {/* Arrow */}
         <span
+          style={{ marginLeft: `${-shiftX}px` }}
           className={`absolute left-1/2 -translate-x-1/2 w-2 h-2 rotate-45 border-[var(--color-border)] bg-[var(--color-bg-primary)] ${
             position === 'top'
               ? 'bottom-[-5px] border-r border-b'
@@ -109,3 +124,14 @@ export function Tooltip({
     </span>
   );
 }
+
+/** Left/right edges of the nearest ancestor that clips horizontally. */
+function clippingBounds(el: HTMLElement): { left: number; right: number } {
+  for (let node = el.parentElement; node; node = node.parentElement) {
+    if (getComputedStyle(node).overflowX !== 'visible') {
+      const rect = node.getBoundingClientRect();
+      return { left: rect.left, right: rect.right };
+    }
+  }
+  return { left: 0, right: document.documentElement.clientWidth };
+}

package/vendored/lib/email-notifier.ts

@@ -1,11 +1,11 @@
 /**
- * Email Notifier — sends internal build failure notifications via Resend.
+ * Email Notifier — sends internal build failure notifications via Mailfully.
  *
- * Env: BUILDER_RESEND_API_KEY, JAMDESK_REPORT_EMAIL
+ * Env: MAILFULLY_API_KEY, JAMDESK_REPORT_EMAIL
  */
 
 import { render } from '@react-email/render';
-import { Resend } from 'resend';
+import { sendMailfullyEmail } from './mailfully.js';
 import { BuildFailureEmail, type BuildFailureEmailProps } from './email-templates/index.js';
 
 export type BuildFailureEmailInfo = BuildFailureEmailProps;
@@ -15,13 +15,13 @@ export type BuildFailureEmailInfo = BuildFailureEmailProps;
  * Gracefully skips if environment variables are not configured.
  */
 export async function sendInternalBuildFailureEmail(info: BuildFailureEmailInfo): Promise<void> {
-  const apiKey = process.env.BUILDER_RESEND_API_KEY;
+  const apiKey = process.env.MAILFULLY_API_KEY;
   const reportEmail = process.env.JAMDESK_REPORT_EMAIL;
 
   if (!apiKey || !reportEmail) {
     console.log(JSON.stringify({
       severity: 'WARNING',
-      message: `Email notification skipped - ${!apiKey ? 'BUILDER_RESEND_API_KEY' : 'JAMDESK_REPORT_EMAIL'} not configured`,
+      message: `Email notification skipped - ${!apiKey ? 'MAILFULLY_API_KEY' : 'JAMDESK_REPORT_EMAIL'} not configured`,
       projectId: info.projectId,
       buildId: info.buildId,
     }));
@@ -29,13 +29,11 @@ export async function sendInternalBuildFailureEmail(info: BuildFailureEmailInfo)
   }
 
   try {
-    const resend = new Resend(apiKey);
-    
     const template = BuildFailureEmail(info);
     const html = await render(template);
     const text = await render(template, {plainText: true});
 
-    const result = await resend.emails.send({
+    const result = await sendMailfullyEmail(apiKey, {
       from: 'Jamdesk <support@jamdesk.com>',
       to: reportEmail,
       subject: `Jamdesk build failed: ${info.projectName || info.projectId}`,

package/vendored/lib/layout-helpers.tsx

@@ -114,7 +114,7 @@ export const figtree = Figtree({
 export const ibmPlexSerif = IBM_Plex_Serif({
   subsets: ['latin'],
   display: 'swap',
-  weight: ['400', '600'],
+  weight: ['400', '500', '600'],
   variable: '--font-serif',
   preload: false,
 });

package/vendored/lib/mailfully.ts

@@ -0,0 +1,86 @@
+// DO NOT EDIT — this file is auto-synced from shared/. Edit the source in shared/ and run ./scripts/sync-shared.sh
+
+/**
+ * Minimal Mailfully client — the one call Jamdesk makes (send an email).
+ * Not the `mailfully` npm SDK on purpose: it requires Node 24 and is
+ * ESM-only, and our Firebase Functions run Node 22. Never throws: every
+ * failure (transport, non-2xx, bad JSON) comes back on the error arm.
+ */
+
+export type MailfullySendInput = {
+  from: string;
+  to: string | string[];
+  cc?: string | string[];
+  bcc?: string | string[];
+  replyTo?: string | string[];
+  subject: string;
+  html?: string;
+  text?: string;
+  headers?: Record<string, string>;
+  tags?: { name: string; value: string }[];
+  type?: "transactional" | "marketing";
+};
+
+export type MailfullyResult =
+  | { data: { id: string; status: "queued" | "canceled" }; error: null }
+  | {
+      data: null;
+      error: {
+        statusCode: number | null;
+        type: string | null;
+        message: string;
+        retryAfter: number | null;
+      };
+    };
+
+const DEFAULT_BASE_URL = "https://api.mailfully.com";
+
+function fail(
+  statusCode: number | null,
+  type: string | null,
+  message: string,
+  retryAfter: number | null,
+): MailfullyResult {
+  return { data: null, error: { statusCode, type, message, retryAfter } };
+}
+
+export async function sendMailfullyEmail(
+  apiKey: string,
+  input: MailfullySendInput,
+  opts: { idempotencyKey?: string; baseUrl?: string } = {},
+): Promise<MailfullyResult> {
+  const { replyTo, ...rest } = input;
+  const body = { ...rest, ...(replyTo ? { reply_to: replyTo } : {}) };
+  let res: Response;
+  try {
+    res = await fetch(`${opts.baseUrl ?? DEFAULT_BASE_URL}/v1/emails`, {
+      method: "POST",
+      headers: {
+        "Authorization": `Bearer ${apiKey}`,
+        "Content-Type": "application/json",
+        ...(opts.idempotencyKey ?
+          { "Idempotency-Key": opts.idempotencyKey } : {}),
+      },
+      body: JSON.stringify(body),
+      // A hung request would otherwise hold a newsletter run or a function
+      // until its own timeout; a timeout comes back as a transport error.
+      signal: AbortSignal.timeout(15_000),
+    });
+  } catch (err) {
+    return fail(null, null, (err as Error).message, null);
+  }
+  const retryAfter = Number(res.headers.get("retry-after")) || null;
+  let json: unknown;
+  try {
+    json = await res.json();
+  } catch {
+    return fail(res.status, null, "Malformed JSON response", retryAfter);
+  }
+  if (!res.ok) {
+    const e = (json as { error?: { type?: string; message?: string } }).error;
+    return fail(res.status, e?.type ?? null,
+      e?.message ?? `HTTP ${res.status}`, retryAfter);
+  }
+  const { id, status } = json as { id: string; status: "queued" | "canceled" };
+  return { data: { id, status }, error: null };
+}

package/vendored/lib/markdown-absolute-links.ts

@@ -0,0 +1,197 @@
+import { unified, type Processor } from 'unified';
+import remarkParse from 'remark-parse';
+import remarkGfm from 'remark-gfm';
+import { visit } from 'unist-util-visit';
+import type { Root, Link, Definition, Html } from 'mdast';
+import { prefixRelativeHref } from './link-prefix-helpers';
+
+/**
+ * Rewrite root-relative page links in a served `.md` export to absolute URLs
+ * on the tenant's public host.
+ *
+ * Two reasons, both about agents reading the markdown away from the page:
+ *
+ *  - The export is the author's MDX, so links are written as the author typed
+ *    them (`/setup/access-control`). The HTML renderer adds the tenant's docs
+ *    prefix to those hrefs (prefixRelativeHref), the export never did. On a
+ *    subpath-mounted site such as jamdesk.com/docs, `/setup/access-control`
+ *    resolves to the marketing site, not the docs page.
+ *  - Agent pipelines drop the fetch URL (RAG chunks, summaries, pastes), so even
+ *    a correct root-relative link stops resolving. afdocs 0.22's
+ *    `markdown-link-portability` check warns on every page that has one.
+ *
+ * Only `[text](/path)` links and `[id]: /path` definitions are rewritten, with
+ * the same prefix rule the HTML renderer applies to `<a href>`. Images are left
+ * alone: custom-domain images are served through `/_jd/images`, not the docs
+ * prefix, so the anchor rule would point them at a 404. Code spans and fenced
+ * code are never touched because they are not link nodes in the parse tree.
+ *
+ * `baseUrl` is the public docs root (e.g. `https://jamdesk.com/docs`, from
+ * getBaseUrl). `linkPrefix` is the prefix the HTML renderer puts on anchors
+ * for this request. The two can differ: a subdomain served at the root whose
+ * custom domain serves at `/help`. So a link is first resolved the renderer's
+ * way, then the renderer's prefix is swapped for the base URL.
+ */
+export function absolutizeMarkdownLinks(
+  markdown: string,
+  baseUrl: string,
+  linkPrefix: string,
+): string {
+  // Cheap exit: most pages have no root-relative link at all, and the parse is
+  // the only non-trivial cost on this route.
+  if (!/\]\(\s*<?\/(?!\/)|\]:\s*<?\/(?!\/)/.test(markdown)) return markdown;
+
+  // Frontmatter is YAML, not markdown: blank it (same length, newlines kept)
+  // so offsets still line up with `markdown` but nothing in it is parsed.
+  const fm = markdown.match(FRONTMATTER_RE);
+  const source = blankTagLines(
+    fm ? blank(fm[0]) + markdown.slice(fm[0].length) : markdown,
+  );
+
+  const edits: Edit[] = [];
+  try {
+    collectEdits(source, 0, baseUrl.replace(/\/+$/, ''), linkPrefix, edits, 0);
+  } catch {
+    return markdown;
+  }
+  if (edits.length === 0) return markdown;
+
+  let out = markdown;
+  for (const e of edits.sort((a, b) => b.start - a.start)) {
+    out = out.slice(0, e.start) + e.url + out.slice(e.end);
+  }
+  return out;
+}
+
+interface Edit { start: number; end: number; url: string }
+
+/**
+ * The source is MDX, and MDX has no indented code blocks: prose indented
+ * inside `<Step>` or `<Tab>` is still prose, and the HTML page renders its
+ * links. Plain markdown would read it as code and skip the link, so turn the
+ * construct off the way remark-mdx does. Fenced code is unaffected.
+ */
+function mdxIndentation(this: Processor) {
+  const data = this.data();
+  const list = (data.micromarkExtensions ??= []) as unknown[];
+  list.push({ disable: { null: ['codeIndented'] } });
+}
+
+/** Built once: the export route runs this on every uncached `.md` request. */
+const parser = unified().use(remarkParse).use(remarkGfm).use(mdxIndentation);
+
+/** Same anchored frontmatter match as agent-directive.tsx. */
+const FRONTMATTER_RE = /^\uFEFF?---\r?\n[\s\S]*?\r?\n---(\r?\n|$)/;
+
+/** Replace every character except line breaks with a space. */
+function blank(text: string): string {
+  return text.replace(/[^\r\n]/g, ' ');
+}
+
+/** One opening or closing tag. `[^>]*` stops at the first `>`, which is fine: only offsets matter. */
+const TAG = /<\/?[A-Za-z][^>]*>/g;
+
+/** A line made only of tags: `<Tab title="Py">`, `</Steps>`, `<iframe ...></iframe>`. */
+const TAG_ONLY_LINE = /^[ \t]*(?:<\/?[A-Za-z][^>]*>[ \t]*)+$/;
+
+/**
+ * Blank every tag-only line (same length) before parsing.
+ *
+ * A component tag directly above a fence (`<CodeGroup>` then a code fence) parses
+ * as a CommonMark HTML block that ends at the first blank line in the code.
+ * The rest of the code is then read as prose and its links rewritten, and
+ * the closing fence opens a new fence that swallows the prose after it. MDX
+ * never reads the tag as HTML, so with the tag lines gone the plain parser
+ * sees the same fences and paragraphs MDX does. Only offsets matter here, and
+ * blanking keeps them.
+ */
+function blankTagLines(text: string): string {
+  return text
+    .split(/(\r?\n)/)
+    .map((part) => (TAG_ONLY_LINE.test(part) ? blank(part) : part))
+    .join('');
+}
+
+/**
+ * Walk one parse of `text` (which starts at `base` in the original string)
+ * and record a rewrite for every root-relative link or definition.
+ *
+ * Tag-only lines are blanked before the first pass, but a line that mixes a
+ * tag with text (`<li>See [a](/x).</li>`) still starts a raw HTML node that
+ * hides the links in it. MDX renders those as links, so such a node is parsed
+ * again with every tag in it blanked. One level of nesting per pass, capped
+ * so pathological input cannot recurse.
+ */
+function collectEdits(
+  text: string,
+  base: number,
+  baseUrl: string,
+  linkPrefix: string,
+  edits: Edit[],
+  depth: number,
+): void {
+  const tree = parser.parse(text) as Root;
+
+  visit(tree, (node) => {
+    if (node.type === 'html') {
+      const start = node.position?.start.offset;
+      if (start === undefined || depth >= 4) return;
+      const end = node.position?.end.offset;
+      const value = (node as Html).value;
+      if (end === undefined || value.trimStart().startsWith('<!--')) return;
+      // Inside a container (blockquote, list item) mdast strips the `> ` or
+      // indent from continuation lines, so `value` is no longer the source
+      // span and its offsets would land in the wrong place. Skip those.
+      if (text.slice(start, end) !== value) return;
+      const inner = value.replace(TAG, blank);
+      if (inner !== value) {
+        collectEdits(inner, base + start, baseUrl, linkPrefix, edits, depth + 1);
+      }
+      return;
+    }
+    if (node.type !== 'link' && node.type !== 'definition') return;
+    const n = node as Link | Definition;
+    const url = n.url;
+    if (!url.startsWith('/') || url.startsWith('//')) return;
+    const start = n.position?.start.offset;
+    const end = n.position?.end.offset;
+    if (start === undefined || end === undefined) return;
+
+    // The destination sits after the label: `](` for a link, `]:` for a
+    // definition. Search from the end of the label so link text that happens
+    // to contain the same path is never the match.
+    const labelEnd = n.type === 'link' && n.children.length > 0
+      ? n.children[n.children.length - 1].position?.end.offset ?? start
+      : start;
+    const opener = n.type === 'link' ? '](' : ']:';
+    const openAt = text.indexOf(opener, labelEnd);
+    if (openAt === -1 || openAt >= end) return;
+    let destAt = openAt + opener.length;
+    while (destAt < end && /\s/.test(text[destAt])) destAt++;
+    if (text[destAt] === '<') destAt++;
+
+    // The parser hands back the decoded URL. Skip anything whose source text
+    // differs (entities, escapes) rather than guess at the raw span.
+    if (text.slice(destAt, destAt + url.length) !== url) return;
+
+    edits.push({
+      start: base + destAt,
+      end: base + destAt + url.length,
+      url: toAbsolute(url, baseUrl, linkPrefix),
+    });
+  });
+}
+
+/**
+ * `/setup` → prefixRelativeHref gives the path the HTML page links to
+ * (`/docs/setup`); dropping that renderer prefix leaves the page path under
+ * the docs root, which is then joined to the public base URL.
+ */
+function toAbsolute(url: string, baseUrl: string, linkPrefix: string): string {
+  const rendered = prefixRelativeHref(url, linkPrefix);
+  const underPrefix = linkPrefix &&
+    (rendered === linkPrefix || rendered.startsWith(`${linkPrefix}/`) ||
+      rendered.startsWith(`${linkPrefix}?`) || rendered.startsWith(`${linkPrefix}#`));
+  const pagePath = underPrefix ? rendered.slice(linkPrefix.length) : rendered;
+  return `${baseUrl}${pagePath}`;
+}

package/vendored/lib/middleware-helpers.ts

@@ -347,6 +347,9 @@ export async function validateForwardedHost(
           mappedProject: mappedProject || 'not-registered',
           status: status || 'missing',
         });
+        // dashboard/functions/src/reports/domain-reachability.ts matches
+        // this text (REFUSED_HOST_TEXT) to auto-detach dead retained
+        // domains. Change both together.
         return {
           allowed: false,
           error: `Domain "${forwardedHost}" is not authorized to serve this content.`,
@@ -1190,6 +1193,27 @@ export function isPresentationAsset(pathname: string): boolean {
   return PRESENTATION_EXTENSIONS.some((ext) => p.endsWith(ext));
 }
 
+// Exact shape written by lib/screenshot-capture.ts: a Firestore auto-ID build
+// id, then a per-capture 128-bit random hex file name.
+const SITE_SCREENSHOT_RE = /^\/_screenshots\/[A-Za-z0-9]{20}\/[0-9a-f]{32}\.jpg$/;
+
+/**
+ * The dashboard site-preview screenshot, exempt from the password/JWT gate.
+ *
+ * The dashboard's <img> is a cross-site subresource that never carries the
+ * visitor's jd_auth cookie, so a gated site's preview always 401'd. The random
+ * file name is the capability: the full URL is stored only on the members-only
+ * build doc. The build ID is NOT secret (lastBuildId sits on the projects doc,
+ * readable by any signed-in user), which is why the legacy
+ * `/_screenshots/{buildId}/homepage.jpg` shape stays gated.
+ *
+ * The image is the REAL gated homepage (the capture mints an unlock cookie), so
+ * never widen this match or write the file name anywhere world-readable.
+ */
+export function isSiteScreenshotPath(pathname: string): boolean {
+  return SITE_SCREENSHOT_RE.test(pathname);
+}
+
 /**
  * Should this request be 404'd because the project serves from its custom
  * domain only? Returns the response to send, or null to continue.