jamdesk 1.0.0

package/vendored/lib/build/estimation.ts

@@ -0,0 +1,113 @@
+import fs from 'fs';
+import path from 'path';
+
+export type BuildEstimationType = 'full' | 'incremental';
+
+export interface BuildEstimate {
+  minutes: number;
+  type: BuildEstimationType;
+  fileCount: number;
+  changedFiles?: number; // For future incremental builds
+}
+
+/**
+ * Fixed overhead for all builds (in seconds):
+ * - Clone: ~1s
+ * - Validate: ~1s
+ * - Copy: ~0.5s
+ * - R2 upload: ~3-10s (depends on file count)
+ * - Cache wait: 30s
+ * - Cleanup: ~1s
+ * Total: ~45s fixed + variable upload time
+ */
+const FIXED_OVERHEAD_SECONDS = 45;
+
+export function countFilesRecursive(dirPath: string): number {
+  let count = 0;
+
+  try {
+    const items = fs.readdirSync(dirPath, { withFileTypes: true });
+
+    for (const item of items) {
+      if (item.name === 'node_modules' || item.name === '.git') {
+        continue; // Skip node_modules and .git
+      }
+
+      const fullPath = path.join(dirPath, item.name);
+
+      if (item.isFile()) {
+        count++;
+      } else if (item.isDirectory()) {
+        count += countFilesRecursive(fullPath);
+      }
+    }
+  } catch {
+    // If we can't read directory, just return current count
+  }
+
+  return count;
+}
+
+/**
+ * Calculate estimated build time based on build type and file counts
+ *
+ * This is the FALLBACK formula used when historical data is not available.
+ * For projects with build history, Firebase Functions uses actual historical
+ * averages instead (see functions/src/index.ts:getEstimatedMinutes).
+ *
+ * Full builds use a non-linear formula because:
+ * - Next.js build time scales worse than linear (dependency resolution, memory pressure)
+ * - Observed: acme (466 files) = ~100s, dodo (4277 files) = ~555s
+ * - That's 9x files but 5.5x time, showing sub-linear scaling at small sizes
+ *   but super-linear at larger sizes due to memory/CPU constraints
+ *
+ * Formula: baseSeconds + linear component + quadratic component + fixed overhead
+ * - Base: 30s minimum for Next.js
+ * - Linear: 25s per 1000 files
+ * - Quadratic: 8s per (1000 files)^2 (captures non-linear scaling)
+ * - Fixed: 60s (cache wait, clone, cleanup)
+ * - Buffer: +20% conservative estimate
+ *
+ * @param fileCount Total files in project
+ * @param changedFiles Number of changed files (for incremental builds)
+ * @param buildType 'full' or 'incremental'
+ */
+export function calculateBuildEstimate(
+  fileCount: number,
+  changedFiles?: number,
+  buildType: BuildEstimationType = 'full'
+): BuildEstimate {
+  let minutes: number;
+
+  if (buildType === 'incremental' && changedFiles !== undefined) {
+    // Incremental build: ~1 min per 500 changed files + 1 min overhead
+    minutes = Math.max(1, Math.ceil(changedFiles / 500) + 1);
+  } else {
+    // Non-linear formula for full builds (fallback when no history)
+    const filesIn1K = fileCount / 1000;
+
+    // Next.js build: base + linear + quadratic components
+    const nextjsSeconds = 30 + filesIn1K * 25 + filesIn1K * filesIn1K * 8;
+
+    // R2 upload scales roughly linearly (~0.002s per file)
+    const uploadSeconds = Math.max(3, fileCount * 0.002);
+
+    // Total with fixed overhead
+    const totalSeconds = nextjsSeconds + uploadSeconds + FIXED_OVERHEAD_SECONDS;
+
+    // Add 20% buffer for conservative estimate
+    const bufferedSeconds = totalSeconds * 1.2;
+
+    minutes = Math.ceil(bufferedSeconds / 60);
+
+    // Minimum 2 minutes for any build
+    minutes = Math.max(2, minutes);
+  }
+
+  return {
+    minutes,
+    type: buildType,
+    fileCount,
+    changedFiles,
+  };
+}

package/vendored/lib/build/index.ts

@@ -0,0 +1,17 @@
+export {
+  countFilesRecursive,
+  calculateBuildEstimate,
+  type BuildEstimate,
+  type BuildEstimationType,
+} from './estimation.js';
+
+export {
+  generateErrorRef,
+  extractErrorSource,
+  formatErrorLocation,
+  parseErrorDetails,
+} from './error-parser.js';
+
+export { purgeNextJsCache, purgeVercelCache } from './cache.js';
+
+export { runR2Upload, type R2UploadOptions, type R2UploadResult } from './r2-upload.js';

package/vendored/lib/build/page-file-map.ts

@@ -0,0 +1,48 @@
+/**
+ * Builds a mapping of URL paths to source MDX files.
+ * Used by error parser to show actual file names instead of URL paths.
+ */
+
+import fs from 'fs';
+import path from 'path';
+
+/**
+ * Build a mapping of URL paths to MDX file paths.
+ *
+ * @param contentDir - Path to the content directory
+ * @returns Map of URL path -> relative file path
+ */
+export function buildPageToFileMap(contentDir: string): Record<string, string> {
+  const map: Record<string, string> = {};
+
+  function traverseDir(dir: string, basePath: string = '') {
+    if (!fs.existsSync(dir)) return;
+
+    const files = fs.readdirSync(dir);
+
+    for (const file of files) {
+      if (file.startsWith('.')) continue;
+
+      const filePath = path.join(dir, file);
+      let stat;
+      try {
+        stat = fs.statSync(filePath);
+      } catch {
+        continue;
+      }
+
+      if (stat.isDirectory()) {
+        traverseDir(filePath, path.join(basePath, file));
+      } else if (file.endsWith('.mdx') || file.endsWith('.md')) {
+        const slug = path.join(basePath, file.replace(/\.mdx?$/, ''));
+        // Handle index files -> root path
+        const urlPath = slug === 'index' ? '/' : `/${slug.replace(/\\/g, '/')}`;
+        const relativePath = path.join(basePath, file).replace(/\\/g, '/');
+        map[urlPath] = relativePath;
+      }
+    }
+  }
+
+  traverseDir(contentDir);
+  return map;
+}

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

@@ -0,0 +1,179 @@
+/**
+ * R2 upload utilities
+ *
+ * Functions for uploading build output to Cloudflare R2.
+ */
+
+import { spawn } from 'child_process';
+
+export interface R2UploadOptions {
+  slug: string;
+  buildId: string;
+  commitSha: string;
+  fullRebuild: boolean;
+  appDir: string;
+}
+
+export interface R2UploadResult {
+  filesWereUploaded: boolean;
+}
+
+/**
+ * Upload build output to R2 with progress streaming
+ *
+ * Runs the upload-r2 script with parallel uploads and manifest-based
+ * incremental uploads (unless fullRebuild is true).
+ */
+export async function runR2Upload(options: R2UploadOptions): Promise<R2UploadResult> {
+  const { slug, buildId, commitSha, fullRebuild, appDir } = options;
+
+  // Build upload args - add --full flag for full rebuild (ignores manifest)
+  const uploadArgs = [
+    'run',
+    'upload-r2',
+    slug,
+    '--',
+    '--parallel',
+    '150',
+    '--buildId',
+    buildId,
+    '--commitSha',
+    commitSha || 'unknown',
+  ];
+  if (fullRebuild) {
+    uploadArgs.push('--full');
+  }
+
+  // Track whether files were actually uploaded (used to skip cache wait if no changes)
+  let filesWereUploaded = true; // Default to true for safety
+
+  await new Promise<void>((resolve, reject) => {
+    const uploadProcess = spawn('npm', uploadArgs, {
+      cwd: appDir,
+      env: process.env,
+    });
+
+    let lastProgress = '';
+    let stdoutBuffer = '';
+    let stderrBuffer = '';
+
+    uploadProcess.stdout.on('data', (data: Buffer) => {
+      const output = data.toString();
+      stdoutBuffer += output;
+
+      // Log progress updates (upload counts, manifest operations, diff summary)
+      const lines = output.split('\n');
+      for (const line of lines) {
+        // Capture progress lines AND individual file paths (indented with spaces)
+        const isProgressLine =
+          line.includes('Uploading...') ||
+          line.includes('files to upload') ||
+          line.includes('UPLOAD COMPLETE') ||
+          line.includes('Deleted') ||
+          line.includes('Cleaning') ||
+          line.includes('manifest') ||
+          line.includes('Fetching') ||
+          line.includes('Found') ||
+          line.includes('Diff') ||
+          line.includes('New files') ||
+          line.includes('Changed files') ||
+          line.includes('Unchanged') ||
+          line.includes('No changes') ||
+          line.includes('Full upload') ||
+          line.includes('INCREMENTAL') ||
+          line.includes('Hashed') ||
+          line.includes('Sample') ||
+          line.includes('_next/static') ||
+          line.includes('HTML files') ||
+          line.includes('Files to upload');
+        // Also capture indented file paths (lines starting with spaces followed by a path)
+        const isFilePath =
+          /^\s{4,}\S/.test(line) &&
+          (line.includes('.html') ||
+            line.includes('.xml') ||
+            line.includes('.json') ||
+            line.includes('.txt'));
+        if (isProgressLine || isFilePath) {
+          const trimmed = line.trim();
+          if (trimmed && trimmed !== lastProgress) {
+            lastProgress = trimmed;
+            console.log(
+              JSON.stringify({
+                severity: 'INFO',
+                message: 'R2 upload progress',
+                buildId,
+                output: trimmed,
+              })
+            );
+          }
+        }
+      }
+    });
+
+    uploadProcess.stderr.on('data', (data: Buffer) => {
+      stderrBuffer += data.toString();
+      console.log(
+        JSON.stringify({
+          severity: 'WARNING',
+          message: 'R2 upload stderr',
+          buildId,
+          output: data.toString().slice(0, 500),
+        })
+      );
+    });
+
+    // Timeout after 10 minutes (large projects have 35K+ files)
+    const timeout = setTimeout(() => {
+      uploadProcess.kill('SIGTERM');
+      reject(new Error('R2 upload timed out after 10 minutes'));
+    }, 600000);
+
+    uploadProcess.on('close', (code) => {
+      clearTimeout(timeout);
+      if (code === 0) {
+        // Check if files were actually uploaded by parsing the output
+        // The upload script outputs "No changes detected, skipping upload" when nothing changed
+        if (stdoutBuffer.includes('No changes detected')) {
+          filesWereUploaded = false;
+        }
+        console.log(
+          JSON.stringify({
+            severity: 'INFO',
+            message: 'R2 upload process completed',
+            buildId,
+            exitCode: code,
+            filesWereUploaded,
+          })
+        );
+        resolve();
+      } else {
+        console.log(
+          JSON.stringify({
+            severity: 'ERROR',
+            message: 'R2 upload failed',
+            buildId,
+            exitCode: code,
+            stdout: stdoutBuffer.slice(-2000),
+            stderr: stderrBuffer.slice(-2000),
+          })
+        );
+        reject(new Error(`R2 upload failed with exit code ${code}`));
+      }
+    });
+
+    uploadProcess.on('error', (err) => {
+      clearTimeout(timeout);
+      console.log(
+        JSON.stringify({
+          severity: 'ERROR',
+          message: 'R2 upload process error',
+          buildId,
+          error: err.message,
+        })
+      );
+      reject(err);
+    });
+  });
+
+  return { filesWereUploaded };
+}

package/vendored/lib/cache-keys.ts

@@ -0,0 +1,117 @@
+/**
+ * Cache Key Generation for Multi-Tenant ISR
+ *
+ * Ensures cache keys are properly namespaced by project to prevent
+ * cache bleed between tenants. All caches should use these functions
+ * for key generation.
+ */
+
+/**
+ * Generate a cache key for project-scoped resources.
+ *
+ * @param projectSlug - Project identifier
+ * @param resourcePath - Resource path within project
+ * @returns Namespaced cache key
+ */
+export function getCacheKey(projectSlug: string, resourcePath: string): string {
+  // Normalize path (remove leading/trailing slashes)
+  const normalizedPath = resourcePath.replace(/^\/+|\/+$/g, '');
+  return `${projectSlug}:${normalizedPath}`;
+}
+
+/**
+ * Generate a cache key for config resources.
+ *
+ * @param projectSlug - Project identifier
+ * @returns Namespaced cache key for docs.json
+ */
+export function getConfigCacheKey(projectSlug: string): string {
+  return `${projectSlug}:config`;
+}
+
+/**
+ * Generate a cache key for snippet resources.
+ *
+ * @param projectSlug - Project identifier
+ * @param snippetPath - Path to snippet file
+ * @returns Namespaced cache key
+ */
+export function getSnippetCacheKey(projectSlug: string, snippetPath: string): string {
+  return `${projectSlug}:snippet:${snippetPath}`;
+}
+
+/**
+ * Generate a cache key for OpenAPI specs.
+ *
+ * @param projectSlug - Project identifier
+ * @param specPath - Path or URL to OpenAPI spec
+ * @returns Namespaced cache key
+ */
+export function getOpenApiCacheKey(projectSlug: string, specPath: string): string {
+  // For URLs, include the full URL in the key
+  if (specPath.startsWith('http://') || specPath.startsWith('https://')) {
+    return `${projectSlug}:openapi:url:${specPath}`;
+  }
+  return `${projectSlug}:openapi:${specPath}`;
+}
+
+/**
+ * Generate a cache key for page content.
+ *
+ * @param projectSlug - Project identifier
+ * @param pagePath - Page path
+ * @returns Namespaced cache key
+ */
+export function getPageCacheKey(projectSlug: string, pagePath: string): string {
+  return `${projectSlug}:page:${pagePath}`;
+}
+
+/**
+ * Generate a Next.js revalidation tag for a project.
+ *
+ * @param projectSlug - Project identifier
+ * @returns Tag for use with revalidateTag()
+ */
+export function getProjectTag(projectSlug: string): string {
+  return `project:${projectSlug}`;
+}
+
+/**
+ * Generate a Next.js revalidation tag for a specific page.
+ *
+ * @param projectSlug - Project identifier
+ * @param pagePath - Page path
+ * @returns Tag for use with revalidateTag()
+ */
+export function getPageTag(projectSlug: string, pagePath: string): string {
+  return `page:${projectSlug}:${pagePath}`;
+}
+
+/**
+ * Parse a cache key back to its components.
+ *
+ * @param cacheKey - Cache key to parse
+ * @returns Project slug and resource path
+ */
+export function parseCacheKey(cacheKey: string): { projectSlug: string; resourcePath: string } {
+  const colonIndex = cacheKey.indexOf(':');
+  if (colonIndex === -1) {
+    throw new Error(`Invalid cache key format: ${cacheKey}`);
+  }
+
+  return {
+    projectSlug: cacheKey.slice(0, colonIndex),
+    resourcePath: cacheKey.slice(colonIndex + 1),
+  };
+}
+
+/**
+ * Check if a cache key belongs to a specific project.
+ *
+ * @param cacheKey - Cache key to check
+ * @param projectSlug - Project to check against
+ * @returns true if key belongs to project
+ */
+export function isProjectKey(cacheKey: string, projectSlug: string): boolean {
+  return cacheKey.startsWith(`${projectSlug}:`);
+}

package/vendored/lib/code-utils.ts

@@ -0,0 +1,42 @@
+/**
+ * Shared utilities for code block components
+ */
+import { ReactElement } from 'react';
+
+/**
+ * Language display name mapping
+ */
+const LANGUAGE_LABELS: Record<string, string> = {
+  bash: 'cURL',
+  javascript: 'JavaScript',
+  typescript: 'TypeScript',
+  python: 'Python',
+  php: 'PHP',
+  go: 'Go',
+  java: 'Java',
+  csharp: 'C#',
+  rust: 'Rust',
+  ruby: 'Ruby',
+  json: 'JSON',
+  shell: 'Shell',
+  html: 'HTML',
+  css: 'CSS',
+  sql: 'SQL',
+  yaml: 'YAML',
+  xml: 'XML',
+};
+
+/**
+ * Get display name for a programming language
+ */
+export function formatLanguage(lang: string): string {
+  return LANGUAGE_LABELS[lang.toLowerCase()] || lang.charAt(0).toUpperCase() + lang.slice(1);
+}
+
+/**
+ * Helper for accessing React element props
+ * Uses `any` to allow property access without type guards
+ */
+export function getElementProps(element: ReactElement): Record<string, any> {
+  return (element.props || {}) as Record<string, any>;
+}

package/vendored/lib/content-loader.ts

@@ -0,0 +1,176 @@
+/**
+ * Content Loader
+ *
+ * Unified interface for loading docs content in both static and ISR modes.
+ * Abstracts the difference between filesystem (static) and R2 (ISR) content sources.
+ *
+ * Usage:
+ *   const loader = getContentLoader(projectSlug); // projectSlug only used in ISR mode
+ *   const config = await loader.getConfig();
+ *   const content = await loader.getContent('api/auth');
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { parseFrontmatterLenient } from './frontmatter-utils';
+import { getDocsConfig as getStaticDocsConfig, getContentDir } from './docs';
+import {
+  getDocsConfig as getIsrDocsConfig,
+  getMdxContent,
+  getAllDocPaths as getIsrDocPaths,
+  type DocsConfig,
+} from './docs-isr';
+import { isIsrMode, ISR_REVALIDATE_SECONDS } from './page-isr-helpers';
+
+/**
+ * Content loader interface.
+ */
+export interface ContentLoader {
+  /** Get docs.json configuration */
+  getConfig(): Promise<DocsConfig> | DocsConfig;
+  /** Get raw MDX content for a page */
+  getContent(pagePath: string): Promise<string>;
+  /** Get all document paths */
+  getAllPaths(): Promise<string[]>;
+  /** Check if content exists for a path */
+  contentExists(pagePath: string): Promise<boolean>;
+}
+
+/**
+ * Static mode content loader (filesystem).
+ */
+class StaticContentLoader implements ContentLoader {
+  private contentDir: string;
+
+  constructor() {
+    this.contentDir = getContentDir();
+  }
+
+  getConfig(): DocsConfig {
+    return getStaticDocsConfig();
+  }
+
+  async getContent(pagePath: string): Promise<string> {
+    const filePath = path.join(this.contentDir, pagePath) + '.mdx';
+    return fs.readFileSync(filePath, 'utf8');
+  }
+
+  async getAllPaths(): Promise<string[]> {
+    const paths: string[] = [];
+
+    const traverseDir = (dir: string, basePath: string = '') => {
+      if (!fs.existsSync(dir)) return;
+
+      const files = fs.readdirSync(dir);
+
+      for (const file of files) {
+        if (file.startsWith('.')) continue;
+
+        const filePath = path.join(dir, file);
+
+        let stat;
+        try {
+          stat = fs.statSync(filePath);
+        } catch {
+          continue;
+        }
+
+        if (stat.isDirectory()) {
+          traverseDir(filePath, path.join(basePath, file));
+        } else if (file.endsWith('.mdx')) {
+          const slug = path.join(basePath, file.replace(/\.mdx$/, ''));
+          paths.push(slug);
+        }
+      }
+    };
+
+    traverseDir(this.contentDir);
+    return paths;
+  }
+
+  async contentExists(pagePath: string): Promise<boolean> {
+    const filePath = path.join(this.contentDir, pagePath) + '.mdx';
+    return fs.existsSync(filePath);
+  }
+}
+
+/**
+ * ISR mode content loader (R2).
+ */
+class IsrContentLoader implements ContentLoader {
+  private projectSlug: string;
+  private configCache: DocsConfig | null = null;
+
+  constructor(projectSlug: string) {
+    this.projectSlug = projectSlug;
+  }
+
+  async getConfig(): Promise<DocsConfig> {
+    if (!this.configCache) {
+      this.configCache = await getIsrDocsConfig(this.projectSlug);
+    }
+    return this.configCache;
+  }
+
+  async getContent(pagePath: string): Promise<string> {
+    return getMdxContent(this.projectSlug, pagePath);
+  }
+
+  async getAllPaths(): Promise<string[]> {
+    return getIsrDocPaths(this.projectSlug);
+  }
+
+  async contentExists(pagePath: string): Promise<boolean> {
+    try {
+      await this.getContent(pagePath);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+}
+
+/**
+ * Get appropriate content loader based on mode.
+ *
+ * @param projectSlug - Project identifier (only used in ISR mode)
+ * @returns Content loader instance
+ */
+export function getContentLoader(projectSlug?: string): ContentLoader {
+  if (isIsrMode()) {
+    if (!projectSlug) {
+      throw new Error('Project slug is required in ISR mode');
+    }
+    return new IsrContentLoader(projectSlug);
+  }
+
+  return new StaticContentLoader();
+}
+
+/**
+ * Get Next.js revalidate value based on mode.
+ *
+ * In static mode, returns false (no revalidation).
+ * In ISR mode, returns the revalidation interval in seconds.
+ */
+export function getRevalidateValue(): number | false {
+  return isIsrMode() ? ISR_REVALIDATE_SECONDS : false;
+}
+
+/**
+ * Parse frontmatter from raw MDX content.
+ * Uses lenient parsing to handle common YAML issues like colons in values.
+ */
+export function parseFrontmatter(content: string): {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  data: { [key: string]: any };
+  content: string;
+} {
+  return parseFrontmatterLenient(content);
+}
+
+// Re-export for convenience
+export { isIsrMode } from './page-isr-helpers';
+export { getProjectFromRequest, getHostAtDocs, normalizeSlugForContent } from './page-isr-helpers';
+export { projectExists } from './docs-isr';
+export type { DocsConfig };