jamdesk 1.1.37 → 1.1.39

package/vendored/lib/language-utils.ts

@@ -5,6 +5,21 @@
  */
 
 import type { LanguageCode, LanguageConfig } from './docs-types';
+import LANGUAGE_CODES_JSON from './language-codes.json';
+
+/**
+ * Canonical language code list, shared with the CJS build script via
+ * `lib/language-codes.json`. Updates to LANGUAGE_DISPLAY_NAMES below MUST
+ * also update language-codes.json. The sync test in
+ * __tests__/lib/language-codes-sync.test.ts catches drift.
+ */
+export const LANGUAGE_CODES = LANGUAGE_CODES_JSON as readonly LanguageCode[];
+
+/** BCP-47 syntax check (2-3 letter primary tag + optional 2-4 letter
+ *  region/script). Shared by the chat and docs-search REST endpoints to
+ *  keep their request-validation contracts identical. Limitation:
+ *  3-segment tags like `zh-Hant-HK` are rejected. */
+export const BCP47_LANGUAGE_RE = /^[a-zA-Z]{2,3}(?:[-_][a-zA-Z]{2,4})?$/;
 
 /**
  * Display names for each supported language code
@@ -275,21 +290,81 @@ export function isValidLanguageCode(code: string): code is LanguageCode {
   return code in LANGUAGE_DISPLAY_NAMES;
 }
 
+/** Lowercase → canonical lookup, built once. Lets `extractLanguageFromPath`
+ *  match URL segments regardless of case (`/pt-br/...` returns `'pt-BR'`).
+ *  Vercel and some CDN configs serve mixed-case folder paths under
+ *  lowercased URLs, so a strict case-sensitive match silently breaks
+ *  every locale-aware feature on those URL forms.
+ *  First insertion wins — iteration order MUST match the CJS map in
+ *  `scripts/build-search-index.cjs`, so we iterate the shared JSON list
+ *  (single source of truth) instead of `LANGUAGE_DISPLAY_NAMES` keys. */
+const LANGUAGE_CODE_BY_LOWER: Map<string, LanguageCode> = (() => {
+  const m = new Map<string, LanguageCode>();
+  for (const k of LANGUAGE_CODES) {
+    const lower = k.toLowerCase();
+    if (!m.has(lower)) m.set(lower, k);
+  }
+  return m;
+})();
+
 /**
  * Extract language code from a pathname
  *
  * @param pathname - The URL pathname (e.g., '/es/introduction' or '/docs/es/introduction')
- * @returns The language code if found, undefined otherwise
+ * @returns The canonical-cased language code if found, undefined otherwise
  */
 export function extractLanguageFromPath(pathname: string): LanguageCode | undefined {
   // Remove /docs prefix if present (for backward compatibility)
   const parts = pathname.replace(/^\/docs\/?/, '').replace(/^\//, '').split('/').filter(Boolean);
 
-  if (parts.length > 0 && isValidLanguageCode(parts[0])) {
-    return parts[0] as LanguageCode;
-  }
+  if (parts.length === 0) return undefined;
+  return LANGUAGE_CODE_BY_LOWER.get(parts[0].toLowerCase());
+}
 
-  return undefined;
+/**
+ * Resolve the active locale from a pathname, gated by the project's declared
+ * language whitelist.
+ *
+ * Returns:
+ *   - `''` when the path has no language prefix, OR the prefix is not in the
+ *     project's `navigation.languages[].language` whitelist (e.g. `dodo/de/foo`
+ *     where dodo only declares `en`).
+ *   - The canonical language code when the prefix matches the whitelist.
+ *
+ * Use this — not `extractLanguageFromPath` directly — for any feature that
+ * filters by language (search, language selector). The whitelist prevents
+ * false-positives on directories named after language codes but not actually
+ * translations.
+ */
+export function resolveLocaleFromPath(
+  pathname: string,
+  projectLanguages: readonly string[],
+): string {
+  return resolveLocaleWithLoweredSet(pathname, buildLoweredLocaleSet(projectLanguages));
+}
+
+/**
+ * Build the lowercase whitelist Set used by `resolveLocaleWithLoweredSet`.
+ * Hoist this out of hot paths (build-time per-page loops, runtime per-keystroke)
+ * to avoid re-allocating on every call.
+ */
+export function buildLoweredLocaleSet(
+  projectLanguages: readonly string[],
+): ReadonlySet<string> {
+  return new Set(projectLanguages.map((l) => l.toLowerCase()));
+}
+
+/**
+ * Hot-path variant of `resolveLocaleFromPath`: caller supplies a pre-built
+ * lowered Set. Same semantics; avoids per-call Set construction.
+ */
+export function resolveLocaleWithLoweredSet(
+  pathname: string,
+  loweredLanguageSet: ReadonlySet<string>,
+): string {
+  const candidate = extractLanguageFromPath(pathname);
+  if (!candidate) return '';
+  return loweredLanguageSet.has(candidate.toLowerCase()) ? candidate : '';
 }
 
 /**

package/vendored/lib/link-rewriter.ts

@@ -0,0 +1,67 @@
+/**
+ * Markdown link rewriter for chat responses.
+ *
+ * Rewrites two forms to absolute URLs from a `pageSlug → absoluteUrl` map:
+ *
+ * 1. Bare-slug:    `[Anchor](api-reference/foo)`     → `[Anchor](https://x/docs/api-reference/foo)`
+ * 2. Absolute URL: `[Anchor](https://anything/.../api-reference/foo)` → canonical absolute URL
+ *
+ * Both forms are needed because Haiku at temp 0.3 produces a mix:
+ * - Sometimes copies the `URL:` line from chunk context verbatim (form 2, correct host)
+ * - Sometimes emits the pageSlug (form 1)
+ * - Sometimes hallucinates a host (form 2, wrong host) — the slug suffix still resolves
+ * - Sometimes lowercases the leading segment of mixed-case locale folders
+ *   (`pt-BR/foo` → `pt-br/foo`) — hence the lowercase lookup map.
+ *
+ * Streaming note: this is NOT streaming-safe. Apply ONLY to a complete markdown
+ * string (the final tool input). The chat route streams the raw markdown live
+ * for typing-effect UX, then sends a `text_replace` SSE event with the
+ * rewritten string at end-of-stream.
+ */
+
+const MARKDOWN_LINK_RE = /\[([^\]]+)\]\(([^)]+)\)/g;
+
+export function rewriteSlugLinks(
+  text: string,
+  slugToUrl: Record<string, string>,
+): string {
+  const lookup: Record<string, string> = {};
+  for (const [key, value] of Object.entries(slugToUrl)) lookup[key.toLowerCase()] = value;
+
+  return text.replace(MARKDOWN_LINK_RE, (full, anchor: string, url: string, offset: number) => {
+    // Skip image syntax (![alt](url)). A leading "!" turns the same bracket
+    // pattern into an image — rewriting it would point the <img src> at a docs
+    // page if the URL happens to match a known slug.
+    if (offset > 0 && text[offset - 1] === '!') return full;
+    const resolved = resolveSlugFromUrl(url, lookup);
+    return resolved ? `[${anchor}](${resolved})` : full;
+  });
+}
+
+function resolveSlugFromUrl(
+  url: string,
+  lookup: Record<string, string>,
+): string | null {
+  let path = url;
+  let hash = '';
+
+  if (/^https?:\/\//i.test(url)) {
+    try {
+      const parsed = new URL(url);
+      path = parsed.pathname;
+      hash = parsed.hash;
+    } catch {
+      return null;
+    }
+  } else {
+    const hashIdx = path.indexOf('#');
+    if (hashIdx !== -1) {
+      hash = path.slice(hashIdx);
+      path = path.slice(0, hashIdx);
+    }
+  }
+
+  path = path.replace(/^\.?\/+/, '').toLowerCase();
+  const hit = lookup[path] ?? lookup[path.replace(/^docs\//, '')];
+  return hit ? hit + hash : null;
+}

package/vendored/lib/locale-helpers.ts

@@ -0,0 +1,62 @@
+/**
+ * Locale helpers for AI chat embedding + retrieval.
+ *
+ * The chunker uses these at build time to tag each EmbeddingChunk with the
+ * locale derived from the file path (using the project's i18n config). The
+ * chat API uses the same shape at query time to filter Upstash Vector
+ * results to a single locale, preventing cross-language pollution.
+ */
+
+export interface LanguageEntry {
+  code: string;
+  isDefault: boolean;
+}
+
+interface RawLanguageEntry {
+  language: string;
+  default?: boolean;
+}
+
+/**
+ * Normalize the raw `navigation.languages` array into a stable, lowercased shape.
+ *
+ * - If no entry has `default: true`, the first entry is treated as default
+ *   (matches resolveLanguageWithFallback() in language-utils.ts).
+ * - Codes are lowercased so `pt-BR` from docs.json matches `pt-br/...` paths.
+ */
+export function normalizeLanguageList(
+  raw: RawLanguageEntry[] | undefined,
+): LanguageEntry[] {
+  if (!raw || raw.length === 0) return [];
+  const hasExplicitDefault = raw.some((l) => l.default === true);
+  return raw.map((l, i) => ({
+    code: l.language.toLowerCase(),
+    isDefault: hasExplicitDefault ? l.default === true : i === 0,
+  }));
+}
+
+/**
+ * Derive the locale for a chunk from its file path.
+ *
+ * Returns:
+ * - `null` when no i18n config is present (single-language project) — the
+ *   filter must NOT be applied to chunks with no locale metadata, and a
+ *   blanket "en" default would silently mislabel Spanish-only docs sites.
+ * - The matching language code when the leading path segment is in the
+ *   configured allowlist.
+ * - The configured default language code otherwise.
+ *
+ * Critically, ONLY exact membership in the configured language list counts.
+ * Two-letter folders like `ai/`, `cn/`, `ui/`, `snippets/` are NOT treated as
+ * locales unless they are explicitly listed in `navigation.languages`.
+ */
+export function deriveChunkLocale(
+  filePath: string,
+  languages: LanguageEntry[],
+): string | null {
+  if (languages.length === 0) return null;
+  const defaultCode = languages.find((l) => l.isDefault)?.code ?? languages[0].code;
+  const firstSegment = filePath.replace(/\\/g, '/').split('/')[0].toLowerCase();
+  const match = languages.find((l) => l.code === firstSegment);
+  return match ? match.code : defaultCode;
+}

package/vendored/lib/openapi/code-examples.ts

@@ -11,11 +11,10 @@ import type {
   CodeExample,
   JsonSchema,
 } from './types';
+import type { ApiAuthMethod } from '../docs-types';
+import { resolveServerUrl } from './resolve-server-url';
 
-/**
- * Supported auth methods from docs.json
- */
-export type AuthMethod = 'bearer' | 'basic' | 'key' | 'cobo';
+export type AuthMethod = ApiAuthMethod;
 
 /**
  * Configuration for code example generation
@@ -194,7 +193,7 @@ export function buildGeneratorContext(
   config: CodeExampleConfig
 ): GeneratorContext {
   const { method, path, parameters, requestBody } = endpoint;
-  const baseUrl = endpoint.servers[0]?.url || DEFAULT_BASE_URL;
+  const baseUrl = resolveServerUrl(endpoint.servers[0]) || DEFAULT_BASE_URL;
   const formattedPath = formatPathWithParams(path, parameters);
   const queryString = formatQueryParams(parameters);
   const fullUrl = `${baseUrl}${formattedPath}${queryString}`;
@@ -257,7 +256,7 @@ export function generatePythonExample(
 
   // Python handles query params separately (params=params in request call),
   // so we build the URL without query string
-  const baseUrl = endpoint.servers[0]?.url || DEFAULT_BASE_URL;
+  const baseUrl = resolveServerUrl(endpoint.servers[0]) || DEFAULT_BASE_URL;
   const formattedPath = formatPathWithParams(endpoint.path, parameters);
   const pythonUrl = `${baseUrl}${formattedPath}`;
 

package/vendored/lib/openapi/derive-auth.ts

@@ -0,0 +1,46 @@
+import type { AuthMethod } from './code-examples';
+import type { SecurityRequirement } from './types';
+
+export interface DerivedAuth {
+  method?: AuthMethod;
+  headerName?: string;
+}
+
+/**
+ * Derive playground auth config from a parsed OpenAPI security list.
+ *
+ * Returns `{}` when no scheme is renderable in the playground (empty list,
+ * apiKey-in-query/cookie, etc). docs.json `api.mdx.auth` should still take
+ * precedence over this — callers in page.tsx merge with the docs.json value first.
+ *
+ * Falls through past schemes the playground can't render, so a spec offering
+ * "either apiKey-in-query or bearer" still works.
+ */
+export function deriveAuthFromSecurity(security: SecurityRequirement[]): DerivedAuth {
+  for (const req of security) {
+    const mapped = mapSingle(req);
+    if (mapped.method) return mapped;
+  }
+  return {};
+}
+
+function mapSingle(req: SecurityRequirement): DerivedAuth {
+  if (req.type === 'http') {
+    if (req.scheme === 'bearer') return { method: 'bearer' };
+    if (req.scheme === 'basic') return { method: 'basic' };
+    return {};
+  }
+
+  if (req.type === 'apiKey') {
+    if (req.in === 'header' && req.parameterName) {
+      return { method: 'key', headerName: req.parameterName };
+    }
+    return {};
+  }
+
+  if (req.type === 'oauth2' || req.type === 'openIdConnect') {
+    return { method: 'bearer' };
+  }
+
+  return {};
+}

package/vendored/lib/openapi/index.ts

@@ -90,3 +90,10 @@ export {
   generateNavigationGroups,
   getSpecStats,
 } from './generator';
+
+// Auth derivation
+export type { DerivedAuth } from './derive-auth';
+export { deriveAuthFromSecurity } from './derive-auth';
+
+// Server URL resolution
+export { resolveServerUrl } from './resolve-server-url';

package/vendored/lib/openapi/parser.ts

@@ -5,7 +5,7 @@
  * Extracts parameters, request bodies, responses, and security info.
  */
 
-import type { OpenAPI, OpenAPIV3, OpenAPIV3_1 } from 'openapi-types';
+import type { OpenAPI, OpenAPIV3 } from 'openapi-types';
 import type {
   HttpMethod,
   ParsedOpenApiFrontmatter,
@@ -219,10 +219,14 @@ function parseSecuritySchemes(api: OpenAPI.Document): Map<string, SecurityRequir
         scheme: 'scheme' in s ? s.scheme : undefined,
         in: 'in' in s ? s.in as SecurityRequirement['in'] : undefined,
         bearerFormat: 'bearerFormat' in s ? s.bearerFormat : undefined,
+        parameterName:
+          s.type === 'apiKey' && 'name' in s
+            ? (s as OpenAPIV3.ApiKeySecurityScheme).name
+            : undefined,
       });
     }
   }
-  
+
   // Swagger 2.0
   if ('securityDefinitions' in api) {
     const defs = (api as any).securityDefinitions;
@@ -233,6 +237,7 @@ function parseSecuritySchemes(api: OpenAPI.Document): Map<string, SecurityRequir
         type: s.type,
         scheme: s.scheme,
         in: s.in,
+        parameterName: s.type === 'apiKey' ? s.name : undefined,
       });
     }
   }

package/vendored/lib/openapi/resolve-server-url.ts

@@ -0,0 +1,14 @@
+import type { ServerInfo } from './types';
+
+/**
+ * Substitute `{varname}` placeholders in an OpenAPI server URL with the
+ * defaults declared in `server.variables`. Unknown placeholders are left
+ * intact so they remain visible to the user rather than producing a broken
+ * URL fragment.
+ */
+export function resolveServerUrl(server: ServerInfo | undefined): string | undefined {
+  if (!server) return undefined;
+  return server.url.replace(/\{(\w+)\}/g, (_, key: string) => {
+    return server.variables?.[key]?.default ?? `{${key}}`;
+  });
+}

package/vendored/lib/openapi/types.ts

@@ -120,6 +120,8 @@ export interface SecurityRequirement {
   scheme?: string;  // For http type: 'bearer', 'basic'
   in?: 'query' | 'header' | 'cookie';  // For apiKey type
   bearerFormat?: string;
+  /** For apiKey schemes: the header / query / cookie parameter name (e.g. 'X-Api-Key'). */
+  parameterName?: string;
 }
 
 /**

package/vendored/lib/path-safety.ts

@@ -97,6 +97,102 @@ export function validateDocsPath(
   return { valid: true, resolvedPath: resolved };
 }
 
+/**
+ * Validates a git ref (branch name) for use in `git clone --branch <ref>`.
+ *
+ * Combines two rule sets:
+ * 1. git's `check-ref-format` constraints (forbids `..`, `@{`, trailing `.lock`,
+ *    leading/trailing `/`, control chars, and a handful of ASCII punctuation).
+ * 2. A strict shell-safety allowlist — even though `cloneRepo` now uses
+ *    `execFileSync` with an argv array, this validator is defense-in-depth so
+ *    a future refactor that reintroduces a shell cannot be silently exploited.
+ *
+ * Allowed characters: A–Z, a–z, 0–9, and `._-/`.
+ *
+ * @param ref - Git ref received from a client (webhook payload / API request)
+ * @returns `{ valid: true }` or `{ valid: false, error }`
+ */
+export function validateGitRef(ref: unknown): SlugValidationResult {
+  if (typeof ref !== 'string') {
+    return { valid: false, error: 'Invalid git ref: must be a string' };
+  }
+
+  // Deliberately do NOT trim. The caller passes `ref` verbatim into argv, so
+  // the validator must judge the exact string the caller will use. If a
+  // consumer wants to allow trimming, they must trim before calling.
+  if (ref.length === 0) {
+    return { valid: false, error: 'Invalid git ref: cannot be empty' };
+  }
+  if (ref.length > 255) {
+    return { valid: false, error: 'Invalid git ref: exceeds 255 characters' };
+  }
+
+  // Allowlist: alphanumerics plus `._-/` only.
+  // Everything outside this set — including every shell metacharacter
+  // (`;`, backtick, `$`, `|`, `&`, `<`, `>`, `(`, `)`, `{`, `}`, `[`, `]`,
+  // single/double quotes, `\`, `#`, `!`, `*`, `?`, `~`, `^`, `:`, spaces,
+  // tabs, newlines, null bytes, and all other control chars) — is rejected.
+  if (!/^[A-Za-z0-9._\-\/]+$/.test(ref)) {
+    return { valid: false, error: 'Invalid git ref: contains disallowed characters' };
+  }
+
+  // The following enforce git check-ref-format rules that the allowlist
+  // cannot express positionally — characters like `.`, `/`, and `-` are
+  // permitted in general but disallowed in specific positions or sequences.
+  if (ref.includes('..')) {
+    return { valid: false, error: 'Invalid git ref: cannot contain ".." sequences' };
+  }
+  if (ref.startsWith('/') || ref.endsWith('/')) {
+    return { valid: false, error: 'Invalid git ref: cannot start or end with "/"' };
+  }
+  if (ref.startsWith('.') || ref.endsWith('.')) {
+    return { valid: false, error: 'Invalid git ref: cannot start or end with "."' };
+  }
+  if (ref.endsWith('.lock')) {
+    return { valid: false, error: 'Invalid git ref: cannot end with ".lock"' };
+  }
+  // Block leading `-` so git does not parse the ref as a CLI flag
+  // (e.g. `-oProxyCommand=...`, `--upload-pack=...`).
+  if (ref.startsWith('-')) {
+    return { valid: false, error: 'Invalid git ref: cannot start with "-"' };
+  }
+
+  return { valid: true };
+}
+
+/**
+ * Validates a GitHub `owner/repo` full-name string.
+ *
+ * Allowlist per segment: `[A-Za-z0-9][A-Za-z0-9_.-]*` with 1–100 chars each.
+ * Exactly one `/` separating owner and repo. Leading `-` is rejected so the
+ * value cannot be mistaken for a CLI flag even if it ever escapes argv to a
+ * shell (defense-in-depth).
+ *
+ * @param repoFullName - Full repo name from a webhook/API payload
+ * @returns `{ valid: true }` or `{ valid: false, error }`
+ */
+export function validateRepoFullName(repoFullName: unknown): SlugValidationResult {
+  if (typeof repoFullName !== 'string') {
+    return { valid: false, error: 'Invalid repoFullName: must be a string' };
+  }
+
+  // No trim: validate the exact string the caller will pass into argv.
+  if (!/^[A-Za-z0-9][A-Za-z0-9_.-]{0,99}\/[A-Za-z0-9][A-Za-z0-9_.-]{0,99}$/.test(repoFullName)) {
+    return {
+      valid: false,
+      error: 'Invalid repoFullName: must match owner/repo with alphanumerics, "_", ".", or "-"',
+    };
+  }
+
+  // Defense in depth against path traversal: `..` segments could resolve
+  // outside the intended repos dir if this value ever flows into a path-join.
+  if (repoFullName.includes('..')) {
+    return { valid: false, error: 'Invalid repoFullName: cannot contain ".." sequences' };
+  }
+
+  return { valid: true };
+}
+
 /**
  * Validates a project slug for use in file paths.
  * Defense-in-depth: slugs come from Firestore but should still be validated