jamdesk 1.1.157 → 1.1.158

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jamdesk",
-  "version": "1.1.157",
+  "version": "1.1.158",
   "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",

package/vendored/components/mdx/Card.tsx

@@ -134,6 +134,10 @@ export const Card = memo(function Card({ title, icon, img, href, children, horiz
         .group:hover .cta-text {
           color: var(--color-primary) !important;
         }
+        /* Card body typography. The height-affecting subset below (line-height
+           + margins on > p and first/last-child) is mirrored in themes/base.css
+           so it also applies at first paint — Next.js dev injects styled-jsx
+           only after first paint. Keep both copies in sync. */
         .card-content > p {
           margin: 0 0 0.75rem 0;
           font-weight: 300;

package/vendored/components/theme/ThemeToggle.tsx

@@ -15,30 +15,38 @@ const NEXT_THEME: Record<string, (typeof THEMES)[number]['name']> = {
   system: 'light',
 };
 
-interface ThemeToggleProps {
-  size?: 'default' | 'large';
-}
-
-export function ThemeToggle({ size = 'default' }: ThemeToggleProps) {
+export function ThemeToggle() {
   const [mounted, setMounted] = useState(false);
   const { theme, setTheme } = useTheme();
 
-  const isLarge = size === 'large';
-  const containerClass = isLarge
-    ? 'flex items-center gap-1 bg-[var(--color-bg-secondary)] rounded-xl px-1.5 py-1.5 border border-[var(--color-border)]'
-    : 'flex items-center gap-1 bg-[var(--color-bg-secondary)]/50 rounded-md px-0.5 py-0.5 border border-[var(--color-border)]/50';
-  const buttonClass = isLarge ? 'px-5 py-3 rounded-lg cursor-pointer' : 'px-1.5 py-0.5 rounded cursor-pointer';
-  const iconClass = isLarge ? 'text-[20px]' : 'text-[12px]';
+  const containerClass =
+    'flex items-center gap-1 bg-[var(--color-bg-secondary)]/50 rounded-md px-0.5 py-0.5 border border-[var(--color-border)]/50';
+  const buttonClass = 'px-1.5 py-0.5 rounded cursor-pointer';
+  const iconClass = 'text-[12px]';
+  // Fixed-size icon slot shared by the pre-mount placeholder and the mounted
+  // buttons. Without it the control changes width when the FontAwesome icon font
+  // swaps in (font-display: swap), reflowing the header nav horizontally (CLS).
+  // overflow-hidden caps a wide fallback glyph.
+  const iconSlot = 'inline-flex items-center justify-center w-4 h-4 overflow-hidden';
 
   useEffect(() => {
     setMounted(true);
   }, []);
 
+  // The placeholder MUST mirror the mounted markup exactly — same [data-theme-toggle]
+  // attribute AND <button> tag — because themes style the toggle through both
+  // selectors: Pulsar HIDES the header copy via `header [data-theme-toggle]` and
+  // shrinks the sidebar copy's cells via `[data-theme-toggle] button { width:16px }`.
+  // If the placeholder used a <div>, that button rule wouldn't match it, so the
+  // cells would render wide then collapse to 16px when the real buttons mount —
+  // shifting the toggle (and its neighbors) sideways on load.
   if (!mounted) {
     return (
-      <div className={containerClass}>
+      <div className={containerClass} data-theme-toggle aria-hidden="true">
         {THEMES.map((t) => (
-          <div key={t.name} className={isLarge ? 'w-8 h-8' : 'w-5 h-4'} />
+          <button key={t.name} type="button" disabled className={buttonClass}>
+            <span className={iconSlot} />
+          </button>
         ))}
       </div>
     );
@@ -66,7 +74,9 @@ export function ThemeToggle({ size = 'default' }: ThemeToggleProps) {
             aria-pressed={active}
             title={title}
           >
-            <i className={`fa-solid ${icon} ${iconClass}`} aria-hidden="true" />
+            <span className={iconSlot}>
+              <i className={`fa-solid ${icon} ${iconClass}`} aria-hidden="true" />
+            </span>
           </button>
         );
       })}

package/vendored/lib/auth-resolver.ts

@@ -104,3 +104,39 @@ export async function resolveAuth(
 // for backwards compatibility. The split keeps the matcher (a pure
 // function with no Redis dependency) importable from build-time modules
 // like public-paths-resolver without dragging in the Redis client.
+
+/**
+ * Quick boolean check: is this project password-gated right now?
+ * Used by R2 read paths to CHOOSE WHICH FETCH MECHANISM to use:
+ *   - true  → S3 SDK (HMAC-authed, slower)
+ *   - false → CF public domain (fast, cached)
+ *
+ * NOT an access-control function. Real password gating is upstream in
+ * proxy.ts via resolveAuth + the unlock cookie. By the time r2-content.ts
+ * calls this, access has already been authorized; we're only picking the
+ * fetch mechanism. Therefore: fail OPEN (return false) on Redis error so
+ * brownouts don't nullify the CDN-cache latency win.
+ *
+ * Reads go through cached-redis (getProjectAuthSecret/getProjectAuthPublic) —
+ * the same wrappers resolveAuth uses — so the two share per-instance cache
+ * entries for these keys instead of each holding its own copy. cached-redis
+ * does NOT cache fetch errors, so the fail-open path below still retries on
+ * the next call rather than pinning `false`.
+ */
+export async function isProjectGated(slug: string): Promise<boolean> {
+  if (!redis) return false;
+
+  try {
+    const [secret, pub] = await Promise.all([
+      getProjectAuthSecret(slug),
+      getProjectAuthPublic(slug),
+    ]);
+    return !!secret && typeof secret.hash === 'string' && pub?.enabled === true;
+  } catch {
+    // Fail OPEN: this is a read-mechanism choice, not access control.
+    // Gating already happened upstream in proxy.ts. Failing closed here
+    // would route every read through S3 SDK during Redis brownouts,
+    // nullifying the CDN-cache latency win precisely when it matters most.
+    return false;
+  }
+}

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

@@ -39,6 +39,8 @@ export async function runR2Upload(options: R2UploadOptions): Promise<R2UploadRes
     buildId,
     '--commitSha',
     commitSha || 'unknown',
+    '--deployId',
+    buildId,
   ];
   if (fullRebuild) {
     uploadArgs.push('--full');

package/vendored/lib/project-deploy-id.ts

@@ -0,0 +1,197 @@
+/**
+ * Per-project deployId pointer with in-process LRU cache.
+ *
+ * Reads/writes `projectDeployId:<slug>` in Redis. The deployId is the prefix
+ * we use under each project's R2 bucket path (`<slug>/<deployId>/<rest>`) so
+ * we can swap to a new build atomically without purging CF cache.
+ *
+ * Cache rules:
+ *   - Positive entries (string deployId) cached for 30s.
+ *   - Negative entries (no deployId in Redis) cached for 5s — short enough
+ *     that a brand-new project's first build appears promptly, long enough
+ *     to prevent thundering-herd Redis reads on cold slugs.
+ *   - Transient Redis errors are NOT cached. Returns null for the current
+ *     call but lets the next call retry.
+ *   - LRU evicts oldest at 500 entries; a successful get reorders to MRU.
+ */
+import type { Redis } from '@upstash/redis';
+import { redis } from './redis';
+import { logger } from '../shared/logger';
+
+const REDIS_KEY = (slug: string): string => `projectDeployId:${slug}`;
+const PROJECT_DEPLOY_HISTORY_PREFIX = 'projectDeployHistory:';
+const DEPLOY_HISTORY_RETENTION = 10; // GC protects the most recent N deployIds
+const LRU_MAX = 500;
+const LRU_TTL_MS = 30_000;
+const LRU_NULL_TTL_MS = 5_000;
+
+interface CacheEntry {
+  value: string | null;
+  expires: number;
+}
+
+const lru = new Map<string, CacheEntry>();
+
+function lruGet(slug: string): CacheEntry | undefined {
+  const entry = lru.get(slug);
+  if (!entry) return undefined;
+  if (entry.expires < Date.now()) {
+    lru.delete(slug);
+    return undefined;
+  }
+  // Recency refresh: reorder to most-recently-used.
+  lru.delete(slug);
+  lru.set(slug, entry);
+  return entry;
+}
+
+function lruSet(slug: string, value: string | null): void {
+  if (lru.size >= LRU_MAX) {
+    const oldest = lru.keys().next().value;
+    if (oldest !== undefined) lru.delete(oldest);
+  }
+  const ttl = value === null ? LRU_NULL_TTL_MS : LRU_TTL_MS;
+  lru.set(slug, { value, expires: Date.now() + ttl });
+}
+
+/**
+ * Clear the in-process LRU. With a slug, evicts just that project's entry —
+ * whole-project revalidation calls this so the next read re-resolves the
+ * pointer from Redis instead of serving a ≤30s-stale deployId into freshly
+ * purged Data Cache entries. Without a slug, clears everything (tests,
+ * bare `{all: true}` revalidation).
+ */
+export function clearProjectDeployIdCache(slug?: string): void {
+  if (slug === undefined) {
+    lru.clear();
+    return;
+  }
+  lru.delete(slug);
+}
+
+/**
+ * Read the current deployId for a project. Returns null when the slug has
+ * no pointer yet (brand-new project, or pre-rollout) or when Redis read
+ * throws (we fail open to the legacy non-prefixed path; see r2-content.ts
+ * branch for the migration story).
+ */
+export async function getProjectDeployId(slug: string): Promise<string | null> {
+  const cached = lruGet(slug);
+  if (cached !== undefined) return cached.value;
+
+  if (!redis) {
+    lruSet(slug, null);
+    return null;
+  }
+
+  try {
+    const value = await redis.get(REDIS_KEY(slug));
+    if (typeof value === 'string' && value.length > 0) {
+      lruSet(slug, value);
+      return value;
+    }
+    lruSet(slug, null);
+    return null;
+  } catch (err) {
+    // Do NOT cache failures — next call must retry Redis. Caching a
+    // transient error would extend a 5s blip into a 30s outage for
+    // every slug that happened to miss during the window.
+    logger.warn('[project-deploy-id] redis read failed', {
+      slug,
+      error: (err as Error).message,
+    });
+    return null;
+  }
+}
+
+/**
+ * Write the current deployId pointer. Called by upload-to-r2 after the new
+ * deployId's content is fully uploaded — atomic swap to the new prefix.
+ *
+ * Throws on empty/non-string deployId (caller bug — better to fail loudly
+ * than silently corrupt the pointer) and when Redis isn't configured
+ * (shouldn't happen in prod; throwing surfaces the misconfig fast).
+ */
+export async function setProjectDeployId(
+  slug: string,
+  deployId: string,
+  // Injectable so recordProjectDeploy's history writes and pointer write
+  // go through the SAME client its caller provided; defaults to the
+  // module singleton for direct callers.
+  client: Redis | null = redis,
+): Promise<void> {
+  if (typeof deployId !== 'string' || deployId.length === 0) {
+    throw new Error('deployId must be a non-empty string');
+  }
+  if (!client) {
+    throw new Error('Redis not configured');
+  }
+  await client.set(REDIS_KEY(slug), deployId);
+  lruSet(slug, deployId);
+}
+
+/**
+ * Publish a new deployId: records into history FIRST, then writes the
+ * current pointer.
+ *
+ * Ordering invariant — load-bearing for `r2-deploy-gc`:
+ *   `history MUST contain the deployId before the pointer references it`
+ *
+ * Otherwise GC could observe `pointer = X` while `X ∉ history`, classify
+ * X's R2 prefix as orphaned, and delete the live deploy. Concretely:
+ *   - LPUSH first. If it throws, we re-throw without ever setting the
+ *     pointer — readers keep serving the previous deploy.
+ *   - SET pointer + LTRIM history then fan out in parallel. They're
+ *     independent (different keys, no causal dependency on each other).
+ *     - SET failure after LPUSH succeeded: the new deploy's prefix is
+ *       protected (it's in history) but the pointer didn't flip. Caller
+ *       sees the throw and surfaces a build warning.
+ *     - LTRIM failure is best-effort — history grows by 1 entry, GC still
+ *       walks the LRANGE correctly. Logged at WARN, NOT re-thrown.
+ *
+ * Net cost vs the prior parallel-everything design: one extra Redis
+ * round-trip on the happy path. Worth it — the alternative is silent
+ * data loss when GC lands in Phase 6.
+ */
+export async function recordProjectDeploy(
+  slug: string,
+  deployId: string,
+  redisClient: Redis,
+): Promise<void> {
+  const historyKey = `${PROJECT_DEPLOY_HISTORY_PREFIX}${slug}`;
+
+  await redisClient.lpush(historyKey, deployId);
+
+  await Promise.all([
+    setProjectDeployId(slug, deployId, redisClient),
+    redisClient
+      .ltrim(historyKey, 0, DEPLOY_HISTORY_RETENTION - 1)
+      .catch((err: unknown) => {
+        logger.warn('[project-deploy-id] ltrim failed (non-fatal)', {
+          slug,
+          error: err instanceof Error ? err.message : String(err),
+        });
+      }),
+  ]);
+}
+
+/**
+ * Delete a project's deployId pointer AND history. Called when a project
+ * becomes password-gated (legacy-only writes): after its versioned prefixes are
+ * purged there is no versioned deploy to reference, and leaving a stale pointer
+ * would make r2-deploy-gc eternally "protect" a deployId whose prefix no longer
+ * exists. Idempotent — a no-op for a project that never published a pointer.
+ */
+export async function clearProjectDeploy(
+  slug: string,
+  client: Redis | null = redis,
+): Promise<void> {
+  if (!client) {
+    throw new Error('Redis not configured');
+  }
+  await Promise.all([
+    client.del(REDIS_KEY(slug)),
+    client.del(`${PROJECT_DEPLOY_HISTORY_PREFIX}${slug}`),
+  ]);
+  clearProjectDeployIdCache(slug);
+}

package/vendored/lib/project-deploy-publisher.ts

@@ -0,0 +1,95 @@
+import type { Redis } from '@upstash/redis';
+import { logger } from '../shared/logger.js';
+import { recordProjectDeploy } from './project-deploy-id.js';
+import { isPublicFetchEnabled } from './r2-feature-flags.js';
+import { DEPLOY_FLIP_TAG } from './revalidation-trigger.js';
+
+const PUBLISH_ATTEMPTS = 3;
+const PUBLISH_RETRY_BASE_MS = 250;
+
+const sleep = (ms: number): Promise<void> =>
+  new Promise((resolve) => setTimeout(resolve, ms));
+
+interface PublishArgs {
+  slug: string;
+  deployId: string;
+  redisClient: Redis | null;
+  recordProjectDeploy?: typeof recordProjectDeploy;
+}
+
+/**
+ * Publish the deployId pointer with retries. Fatality is flag-aware:
+ *
+ *   - USE_R2_PUBLIC_FETCH off (current prod): no reader resolves the
+ *     pointer — every read goes to legacy keys — so a Redis outage here
+ *     must NOT fail customer builds for a pointer nothing consumes yet.
+ *     Log at error (greppable for the rollout preflight) and continue.
+ *   - USE_R2_PUBLIC_FETCH on: a pointer that doesn't flip means readers
+ *     keep serving the previous deploy even though new content uploaded,
+ *     with no fallback exposing the fresh writes. That's fatal — the
+ *     build must not report success.
+ *
+ * Transient Upstash blips were the failure mode that motivated retries:
+ * a single 503 during the one-shot publish would have failed an
+ * otherwise-complete build.
+ */
+export async function publishProjectDeployIdOrThrow({
+  slug,
+  deployId,
+  redisClient,
+  recordProjectDeploy: record = recordProjectDeploy,
+}: PublishArgs): Promise<void> {
+  if (!redisClient) {
+    const message =
+      '[r2-upload] KV not configured; cannot publish projectDeployId pointer';
+    if (isPublicFetchEnabled()) {
+      throw new Error(message);
+    }
+    logger.error(
+      `${message} (non-fatal: USE_R2_PUBLIC_FETCH off, readers use legacy keys)`,
+      { slug, deployId },
+    );
+    return;
+  }
+
+  let lastErr: unknown;
+  for (let attempt = 1; attempt <= PUBLISH_ATTEMPTS; attempt++) {
+    try {
+      await record(slug, deployId, redisClient);
+      logger.info(
+        `${DEPLOY_FLIP_TAG} projectDeployId set, revalidation should follow`,
+        { projectName: slug, deployId, ...(attempt > 1 ? { attempt } : {}) },
+      );
+      return;
+    } catch (err) {
+      lastErr = err;
+      if (attempt < PUBLISH_ATTEMPTS) {
+        const delayMs = PUBLISH_RETRY_BASE_MS * attempt;
+        logger.warn('[r2-upload] projectDeployId publish failed, retrying', {
+          slug,
+          deployId,
+          attempt,
+          delayMs,
+          error: err instanceof Error ? err.message : String(err),
+        });
+        await sleep(delayMs);
+      }
+    }
+  }
+
+  if (isPublicFetchEnabled()) {
+    throw new Error(
+      `Failed to publish projectDeployId pointer for ${slug}/${deployId}`,
+      { cause: lastErr },
+    );
+  }
+  logger.error(
+    '[r2-upload] projectDeployId publish failed after retries (non-fatal: USE_R2_PUBLIC_FETCH off, readers use legacy keys)',
+    {
+      slug,
+      deployId,
+      attempts: PUBLISH_ATTEMPTS,
+      error: lastErr instanceof Error ? lastErr.message : String(lastErr),
+    },
+  );
+}