jamdesk 1.1.26 → 1.1.27

package/dist/lib/openapi/types.d.ts

@@ -139,6 +139,7 @@ export interface ParsedOpenApiFrontmatter {
     specPath: string;
     method: HttpMethod;
     path: string;
+    isShortFormat: boolean;
 }
 /**
  * Validation error types

package/dist/lib/openapi/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/lib/openapi/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/lib/openapi/types.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jamdesk",
-  "version": "1.1.26",
+  "version": "1.1.27",
   "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/app/[[...slug]]/page.tsx

@@ -27,6 +27,7 @@ import { PageNavigation } from '@/components/navigation/PageNavigation';
 import { SocialFooter } from '@/components/navigation/SocialFooter';
 import { ApiPageWrapper } from '@/components/mdx/ApiPage';
 import { OpenApiEndpoint } from '@/components/mdx/OpenApiEndpoint';
+import { OpenApiError } from '@/components/openapi/OpenApiError';
 import { getHighlighter } from '@/lib/shiki-highlighter';
 import { createShikiRehypePlugin } from '@/lib/shiki-config';
 import rehypeSlug from 'rehype-slug';
@@ -69,6 +70,7 @@ import {
   generateCodeExamples,
   formatOpenApiWarning,
   type OpenApiEndpointData,
+  type OpenApiValidationError,
   type CodeExample,
   type AuthMethod,
 } from '@/lib/openapi';
@@ -547,46 +549,76 @@ export default async function DocPage({ params }: PageProps) {
   // Parse OpenAPI endpoint data if openapi frontmatter is present
   let openApiEndpointData: OpenApiEndpointData | null = null;
   let openApiCodeExamples: CodeExample[] | null = null;
+  let openApiError: string | null = null;
 
   // OpenAPI spec parsing - supports both static and ISR modes
   if (data.openapi && typeof data.openapi === 'string') {
     try {
-      // Get default spec path from config if configured
-      const defaultSpecPath = typeof config.api?.openapi === 'string' ? config.api.openapi : undefined;
-
-      // Parse the frontmatter to get spec path, method, and endpoint path
-      const parsed = parseOpenApiFrontmatter(data.openapi, defaultSpecPath);
-
-      if (isIsrMode() && projectSlug) {
-        // ISR mode: fetch spec from R2 or URL
-        const { resolveOpenApiSpec } = await import('@/lib/openapi-isr');
-        const spec = await resolveOpenApiSpec(projectSlug, parsed.specPath);
-        // Cast to expected type - the ISR fetcher validates the spec structure
-        openApiEndpointData = parseEndpoint(
-          spec as Parameters<typeof parseEndpoint>[0],
-          parsed.method,
-          parsed.path,
-          parsed.specPath
-        );
-      } else {
-        // Static mode: fetch spec from filesystem
-        const contentDir = getContentDir();
-        const { api } = await getCachedSpec(parsed.specPath, contentDir);
-        openApiEndpointData = parseEndpoint(api, parsed.method, parsed.path, parsed.specPath);
+      // Normalize config to array (handles string, array, or undefined)
+      const openApiConfig = config.api?.openapi;
+      const allSpecPaths: string[] = typeof openApiConfig === 'string'
+        ? [openApiConfig]
+        : Array.isArray(openApiConfig)
+          ? openApiConfig
+          : [];
+
+      const parsed = parseOpenApiFrontmatter(
+        data.openapi,
+        allSpecPaths.length > 0 ? allSpecPaths : undefined
+      );
+
+      const specsToTry = parsed.isShortFormat && allSpecPaths.length > 1
+        ? allSpecPaths
+        : [parsed.specPath];
+
+      // Hoist mode-dependent values before the loop
+      const useIsr = isIsrMode() && !!projectSlug;
+      const resolveSpec = useIsr
+        ? (await import('@/lib/openapi-isr')).resolveOpenApiSpec
+        : null;
+      const contentDir = useIsr ? null : getContentDir();
+
+      let lastError: unknown = null;
+
+      for (const specPath of specsToTry) {
+        try {
+          if (resolveSpec && projectSlug) {
+            const spec = await resolveSpec(projectSlug, specPath);
+            openApiEndpointData = parseEndpoint(
+              spec as Parameters<typeof parseEndpoint>[0],
+              parsed.method,
+              parsed.path,
+              specPath
+            );
+          } else {
+            const { api } = await getCachedSpec(specPath, contentDir!);
+            openApiEndpointData = parseEndpoint(api, parsed.method, parsed.path, specPath);
+          }
+          lastError = null;
+          break;
+        } catch (err) {
+          lastError = err;
+        }
+      }
+
+      if (lastError) {
+        throw lastError;
       }
 
       // Generate code examples
-      const authMethod = config.api?.mdx?.auth?.method as AuthMethod | undefined;
-      const languages = config.api?.examples?.languages;
-      openApiCodeExamples = generateCodeExamples(openApiEndpointData, { authMethod, languages });
+      if (openApiEndpointData) {
+        const authMethod = config.api?.mdx?.auth?.method as AuthMethod | undefined;
+        const languages = config.api?.examples?.languages;
+        openApiCodeExamples = generateCodeExamples(openApiEndpointData, { authMethod, languages });
+      }
     } catch (err) {
-      // Log formatted warning to console (appears in CLI and build logs)
-      // Check if it's an OpenAPI validation error with our format
-      const error = err as { type?: string; specPath?: string; message?: string; suggestion?: string };
+      const error = err as Partial<OpenApiValidationError>;
       if (error.type && error.specPath && error.message) {
-        console.warn(formatOpenApiWarning(error as Parameters<typeof formatOpenApiWarning>[0]));
+        console.warn(formatOpenApiWarning(error as OpenApiValidationError));
+        openApiError = error.message;
       } else {
         console.error(`Failed to parse OpenAPI for ${slug.join('/')}:`, err);
+        openApiError = 'Unexpected error loading OpenAPI specification';
       }
     }
   }
@@ -712,6 +744,11 @@ export default async function DocPage({ params }: PageProps) {
               />
             )}
 
+            {/* OpenAPI error — shown when spec parsing fails */}
+            {!openApiEndpointData && openApiError && (
+              <OpenApiError message={openApiError} slug={slug.join('/')} />
+            )}
+
             {/* Additional MDX content — strip <ResponseExample> on OpenAPI pages
                 (auto-generated ResponseExamplePanel already handles responses) */}
             <ImagePriorityProvider>

package/vendored/app/api/docs-search/[project]/search/route.ts

@@ -0,0 +1,168 @@
+/**
+ * Docs Search API — Semantic Search Endpoint
+ *
+ * REST API for external integrations (Intercom, Zendesk, custom chatbots)
+ * to search project documentation via vector similarity.
+ *
+ * Security:
+ * - Opaque API key auth (SHA-256 hash lookup in Upstash Redis; revocation
+ *   is a Redis DEL, so there is no separate blocklist)
+ * - Per-key rate limiting (60 req/min)
+ * - CORS enabled (cross-origin access by design)
+ *
+ * Usage:
+ *   POST https://acme.jamdesk.app/_api/search
+ *   Authorization: Bearer jd_live_<32 hex>
+ *   {"query": "How do I authenticate?", "limit": 5}
+ */
+import { NextRequest, NextResponse } from 'next/server';
+import { querySimilarChunks } from '@/lib/vector-store';
+import { verifyApiKey } from '@/lib/docs-search-auth';
+import { getBaseUrl, trackServerAnalytics } from '@/lib/route-helpers';
+import { redis } from '@/lib/redis';
+
+export const runtime = 'nodejs';
+export const maxDuration = 30;
+
+const CORS_HEADERS = {
+  'Access-Control-Allow-Origin': '*',
+  'Access-Control-Allow-Methods': 'POST, OPTIONS',
+  'Access-Control-Allow-Headers': 'Content-Type, Authorization',
+};
+
+const MAX_LIMIT = 20;
+const DEFAULT_LIMIT = 5;
+const MAX_QUERY_LENGTH = 500;
+const RATE_LIMIT_PER_MIN = 60;
+
+export async function OPTIONS(_request: NextRequest) {
+  return new NextResponse(null, { status: 204, headers: CORS_HEADERS });
+}
+
+export async function POST(
+  request: NextRequest,
+  context: { params: Promise<{ project: string }> },
+): Promise<NextResponse> {
+  const { project } = await context.params;
+
+  // --- Auth: verify opaque key against Upstash ---
+  // A revoked key is a Redis DEL, so "not found" and "revoked" collapse
+  // into the same invalid_key reason — no separate blocklist check.
+  // RFC 7235: scheme is case-insensitive. Accept `Bearer`, `bearer`, etc.,
+  // and tolerate stray whitespace rather than 401-ing strict clients.
+  const token = (request.headers.get('Authorization') || '')
+    .replace(/^Bearer\s+/i, '')
+    .trim();
+  const verify = await verifyApiKey(token, project);
+
+  if (!verify.ok) {
+    const status =
+      verify.reason === 'wrong_project' ? 403 :
+      verify.reason === 'lookup_failed' ||
+      verify.reason === 'redis_unavailable' ? 503 :
+      401;
+    return NextResponse.json(
+      { error: verify.reason },
+      { status, headers: CORS_HEADERS },
+    );
+  }
+
+  // --- Rate limiting: per key ID ---
+  // Always-call expire (not just on count === 1) — otherwise a transient
+  // failure between INCR and EXPIRE leaves the bucket immortal, slowly
+  // leaking Upstash keys. EXPIRE is idempotent.
+  if (redis) {
+    try {
+      const rlKey = `docs_search_rl:${verify.id}:${Math.floor(Date.now() / 60000)}`;
+      const count = await redis.incr(rlKey);
+      await redis.expire(rlKey, 120);
+
+      if (count > RATE_LIMIT_PER_MIN) {
+        return NextResponse.json(
+          { error: 'Rate limit exceeded' },
+          { status: 429, headers: { ...CORS_HEADERS, 'Retry-After': '60' } },
+        );
+      }
+    } catch {
+      // Redis down — allow through
+    }
+  }
+
+  // --- Parse & validate request body ---
+  let body: { query?: string; limit?: number };
+  try {
+    body = await request.json();
+  } catch {
+    return NextResponse.json(
+      { error: 'Invalid JSON body' },
+      { status: 400, headers: CORS_HEADERS },
+    );
+  }
+
+  const { query, limit: rawLimit } = body;
+
+  if (!query || typeof query !== 'string' || query.trim().length === 0) {
+    return NextResponse.json(
+      { error: 'Missing or empty "query" field' },
+      { status: 400, headers: CORS_HEADERS },
+    );
+  }
+
+  if (query.length > MAX_QUERY_LENGTH) {
+    return NextResponse.json(
+      { error: `Query exceeds ${MAX_QUERY_LENGTH} characters` },
+      { status: 400, headers: CORS_HEADERS },
+    );
+  }
+
+  // Use Number.isFinite so limit=0 clamps to 1 instead of falling to default
+  const parsedLimit = Number(rawLimit);
+  const effectiveLimit = Number.isFinite(parsedLimit)
+    ? parsedLimit
+    : DEFAULT_LIMIT;
+  const limit = Math.min(
+    Math.max(1, Math.floor(effectiveLimit)),
+    MAX_LIMIT,
+  );
+
+  // --- Semantic vector search ---
+  const startMs = Date.now();
+  let chunks;
+  try {
+    chunks = await querySimilarChunks(project, query.trim(), limit);
+  } catch (err) {
+    console.error('Vector search failed:', err);
+    return NextResponse.json(
+      { error: 'Search temporarily unavailable' },
+      { status: 502, headers: CORS_HEADERS },
+    );
+  }
+  const durationMs = Date.now() - startMs;
+
+  const resolvedHost = request.headers.get('x-jamdesk-forwarded-host')
+    || request.headers.get('x-original-host') || '';
+  const baseUrl = getBaseUrl(project, resolvedHost);
+
+  const results = chunks.map(chunk => ({
+    title: chunk.pageTitle,
+    section: chunk.sectionHeading || undefined,
+    slug: chunk.pageSlug,
+    content: chunk.content.slice(0, 500),
+    url: `${baseUrl}/${chunk.pageSlug}`,
+    score: Math.round(chunk.score * 1000) / 1000,
+  }));
+
+  // --- Analytics (fire-and-forget) ---
+  trackServerAnalytics({
+    projectSlug: project,
+    type: 'docs_search',
+    query: query.trim(),
+    resultsCount: results.length,
+    source: `key:${verify.id}`,
+  });
+
+  return NextResponse.json(
+    { results, query: query.trim(), total: results.length, durationMs },
+    { status: 200, headers: CORS_HEADERS },
+  );
+}

package/vendored/components/openapi/OpenApiError.tsx

@@ -0,0 +1,35 @@
+/**
+ * OpenApiError — visible warning when OpenAPI spec resolution fails.
+ * Renders in all environments (dev, ISR, CLI) so users see the problem
+ * instead of a silently blank page.
+ */
+
+interface OpenApiErrorProps {
+  message: string;
+  slug: string;
+}
+
+export function OpenApiError({ message, slug }: OpenApiErrorProps) {
+  return (
+    <div
+      role="alert"
+      style={{
+        margin: '1.5rem 0',
+        padding: '1rem 1.25rem',
+        borderRadius: '8px',
+        border: '1px solid #f59e0b',
+        backgroundColor: 'rgba(245, 158, 11, 0.08)',
+        fontSize: '0.875rem',
+        lineHeight: 1.5,
+        color: 'var(--color-text-primary, #1e293b)',
+      }}
+    >
+      <div style={{ fontWeight: 600, marginBottom: '0.375rem' }}>
+        OpenAPI Error
+      </div>
+      <div style={{ color: 'var(--color-text-muted, #64748b)' }}>
+        Failed to load the OpenAPI specification for <code>{slug}</code>: {message}
+      </div>
+    </div>
+  );
+}

package/vendored/lib/docs-search-auth.ts

@@ -0,0 +1,95 @@
+/**
+ * Docs Search API key verification.
+ *
+ * Tokens are opaque: `jd_live_<32 hex chars>` (40 chars total, 128 bits
+ * of entropy from crypto.randomBytes). The `_live_` segment reserves
+ * namespace for a future `jd_test_` mode. The server hashes the token
+ * with SHA-256 and looks up `apikey:<hash>` in Upstash Redis — the
+ * dashboard function dual-writes this record on generate and deletes
+ * it on revoke. No JWT, no signing secret, no expiration.
+ */
+import {createHash} from 'crypto';
+import {redis} from './redis';
+import {parseRedisConfig} from './domain-helpers';
+
+const KEY_FORMAT = /^jd_live_[0-9a-f]{32}$/;
+
+export type VerifyResult =
+  | {ok: true; id: string}
+  | {ok: false; reason: VerifyFailure};
+
+export type VerifyFailure =
+  | 'invalid_key_format'
+  | 'invalid_key'
+  | 'wrong_project'
+  | 'lookup_failed'
+  | 'redis_unavailable';
+
+interface StoredKey {
+  projectSlug: string;
+  id: string;
+}
+
+function hashApiKey(rawKey: string): string {
+  return createHash('sha256').update(rawKey).digest('hex');
+}
+
+function parseStoredKey(raw: unknown): StoredKey | null {
+  let parsed: Record<string, unknown> | null;
+  try {
+    parsed = parseRedisConfig(raw);
+  } catch {
+    return null;
+  }
+  if (
+    parsed &&
+    typeof parsed.projectSlug === 'string' &&
+    typeof parsed.id === 'string'
+  ) {
+    return parsed as unknown as StoredKey;
+  }
+  return null;
+}
+
+/**
+ * Verify a bearer token against the expected project slug.
+ *
+ * @param rawKey   The bearer token exactly as received (no trimming — the
+ *                 caller is responsible for stripping the `Bearer ` prefix).
+ * @param projectSlug The slug from the URL path (`[project]` param).
+ * @returns        `{ok: true, id}` on success, `{ok: false, reason}` otherwise.
+ *                 `id` is the short identifier suitable for audit logging;
+ *                 do NOT log the raw token or the hash.
+ */
+export async function verifyApiKey(
+  rawKey: string,
+  projectSlug: string,
+): Promise<VerifyResult> {
+  if (typeof rawKey !== 'string' || !KEY_FORMAT.test(rawKey)) {
+    return {ok: false, reason: 'invalid_key_format'};
+  }
+
+  if (!redis) {
+    return {ok: false, reason: 'redis_unavailable'};
+  }
+
+  const hash = hashApiKey(rawKey);
+
+  let raw: unknown;
+  try {
+    raw = await redis.get(`apikey:${hash}`);
+  } catch {
+    return {ok: false, reason: 'lookup_failed'};
+  }
+
+  const stored = parseStoredKey(raw);
+  if (!stored) {
+    return {ok: false, reason: 'invalid_key'};
+  }
+
+  if (stored.projectSlug !== projectSlug) {
+    return {ok: false, reason: 'wrong_project'};
+  }
+
+  return {ok: true, id: stored.id};
+}

package/vendored/lib/mcp-search.ts

@@ -7,6 +7,7 @@
 import { create, insertMultiple, search as oramaSearch, type Orama } from '@orama/orama';
 import { restore } from '@orama/plugin-data-persistence';
 import { getFileBufferFromR2 } from './r2';
+import { querySimilarChunks } from './vector-store';
 
 // Types matching builder/build-service/lib/search-client.ts
 export interface SearchDocument {
@@ -28,6 +29,35 @@ export interface SearchResult {
   score: number;
 }
 
+/**
+ * Vector search adapter for MCP. Wraps querySimilarChunks()
+ * and maps to SearchResult[] format. Returns null if vector
+ * store is not configured (Orama fallback kicks in).
+ */
+export async function searchProjectWithVector(
+  project: string,
+  query: string,
+  limit: number,
+): Promise<SearchResult[] | null> {
+  if (!process.env.UPSTASH_VECTOR_REST_URL ||
+      !process.env.UPSTASH_VECTOR_REST_TOKEN) {
+    return null;
+  }
+
+  try {
+    const chunks = await querySimilarChunks(project, query, limit);
+    return chunks.map(chunk => ({
+      title: chunk.pageTitle,
+      url: chunk.pageSlug,
+      section: chunk.sectionHeading || undefined,
+      type: 'guide',
+      score: chunk.score,
+    }));
+  } catch {
+    return null; // Fall back to Orama on error
+  }
+}
+
 // Orama schema type
 type SearchSchema = {
   id: 'string';
@@ -74,6 +104,15 @@ export async function searchProject(
     return [];
   }
 
+  // Try vector search first for unfiltered queries
+  if (type === 'all') {
+    const vectorResults = await searchProjectWithVector(project, query, limit);
+    if (vectorResults) {
+      return vectorResults.map(r => ({ ...r, url: `${docsPath}/${r.url}` }));
+    }
+  }
+
+  // Fall back to Orama text search
   const db = await getOrCreateIndex(project, docsPath);
 
   // eslint-disable-next-line @typescript-eslint/no-explicit-any

package/vendored/lib/middleware-helpers.ts

@@ -7,7 +7,6 @@
 
 import { log } from './logger';
 import {
-  resolveProject,
   resolveProjectFromHostname,
   resolveCustomDomain,
   getProjectConfig,
@@ -315,6 +314,7 @@ export const INTERNAL_API_ROUTES = [
   '/api/indexnow',   // IndexNow key verification (app/api/indexnow/[key])
   '/api/isr-health', // Health check endpoint (app/api/isr-health)
   '/api/chat',       // Chat endpoint (app/api/chat/[project])
+  '/api/docs-search', // Docs Search API (app/api/docs-search/[project]/search)
   '/api/mcp',        // MCP endpoint (app/api/mcp/[project])
   '/api/og',         // OG image generation (app/api/og)
   '/api/playground', // API playground (token, proxy, demo) — must skip hostAtDocs redirect
@@ -447,6 +447,26 @@ export function getChatApiPath(projectSlug: string): string {
   return `/api/chat/${projectSlug}`;
 }
 
+/**
+ * Check if this is a docs search request that needs routing.
+ *
+ * @param pathname - Request pathname
+ * @returns true if this is a docs search request
+ */
+export function isDocsSearchRequest(pathname: string): boolean {
+  return pathname === '/_api/search' || pathname === '/docs/_api/search';
+}
+
+/**
+ * Get the docs search API path for a project.
+ *
+ * @param projectSlug - Project identifier
+ * @returns Docs search API route path
+ */
+export function getDocsSearchApiPath(projectSlug: string): string {
+  return `/api/docs-search/${projectSlug}/search`;
+}
+
 const PLAYGROUND_PREFIX = '/_jd/playground/';
 
 /**

package/vendored/lib/openapi/parser.ts

@@ -27,7 +27,7 @@ const VALID_METHODS: HttpMethod[] = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'H
  * Full format: "/path/to/spec.yaml METHOD /endpoint/path"
  * Short format (with defaultSpecPath): "METHOD /endpoint/path"
  */
-export function parseOpenApiFrontmatter(value: string, defaultSpecPath?: string): ParsedOpenApiFrontmatter {
+export function parseOpenApiFrontmatter(value: string, defaultSpecPath?: string | string[]): ParsedOpenApiFrontmatter {
   const trimmed = value.trim();
   const parts = trimmed.split(/\s+/);
 
@@ -38,7 +38,7 @@ export function parseOpenApiFrontmatter(value: string, defaultSpecPath?: string)
 
     if (isMethodFirst) {
       // Short format: "METHOD /endpoint/path"
-      if (!defaultSpecPath) {
+      if (!defaultSpecPath || (Array.isArray(defaultSpecPath) && defaultSpecPath.length === 0)) {
         throw createFrontmatterError(
           value,
           'Short format (e.g., "GET /users") requires api.openapi to be configured in docs.json.\n' +
@@ -46,6 +46,8 @@ export function parseOpenApiFrontmatter(value: string, defaultSpecPath?: string)
         );
       }
 
+      const resolvedDefault = Array.isArray(defaultSpecPath) ? defaultSpecPath[0] : defaultSpecPath;
+
       const [method, ...pathParts] = parts;
       const endpointPath = pathParts.join(' ');
 
@@ -58,9 +60,10 @@ export function parseOpenApiFrontmatter(value: string, defaultSpecPath?: string)
       }
 
       return {
-        specPath: defaultSpecPath.startsWith('/') ? defaultSpecPath : `/${defaultSpecPath}`,
+        specPath: resolvedDefault.startsWith('/') ? resolvedDefault : `/${resolvedDefault}`,
         method: method.toUpperCase() as HttpMethod,
         path: endpointPath,
+        isShortFormat: true,
       };
     }
   }
@@ -106,6 +109,7 @@ export function parseOpenApiFrontmatter(value: string, defaultSpecPath?: string)
     specPath,
     method: upperMethod,
     path: endpointPath,
+    isShortFormat: false,
   };
 }
 

package/vendored/lib/openapi/types.ts

@@ -164,6 +164,7 @@ export interface ParsedOpenApiFrontmatter {
   specPath: string;
   method: HttpMethod;
   path: string;
+  isShortFormat: boolean;
 }
 
 /**

package/vendored/workspace-package-lock.json

@@ -2980,9 +2980,9 @@
       "license": "MIT"
     },
     "node_modules/electron-to-chromium": {
-      "version": "1.5.336",
-      "resolved": "https://registry.npmjs.org/electron-to-chromium/-/electron-to-chromium-1.5.336.tgz",
-      "integrity": "sha512-AbH9q9J455r/nLmdNZes0G0ZKcRX73FicwowalLs6ijwOmCJSRRrLX63lcAlzy9ux3dWK1w1+1nsBJEWN11hcQ==",
+      "version": "1.5.338",
+      "resolved": "https://registry.npmjs.org/electron-to-chromium/-/electron-to-chromium-1.5.338.tgz",
+      "integrity": "sha512-KVQQ3xko9/coDX3qXLUEEbqkKT8L+1DyAovrtu0Khtrt9wjSZ+7CZV4GVzxFy9Oe1NbrIU1oVXCwHJruIA1PNg==",
       "license": "ISC"
     },
     "node_modules/enhanced-resolve": {
@@ -5586,9 +5586,9 @@
       }
     },
     "node_modules/postcss": {
-      "version": "8.5.9",
-      "resolved": "https://registry.npmjs.org/postcss/-/postcss-8.5.9.tgz",
-      "integrity": "sha512-7a70Nsot+EMX9fFU3064K/kdHWZqGVY+BADLyXc8Dfv+mTLLVl6JzJpPaCZ2kQL9gIJvKXSLMHhqdRRjwQeFtw==",
+      "version": "8.5.10",
+      "resolved": "https://registry.npmjs.org/postcss/-/postcss-8.5.10.tgz",
+      "integrity": "sha512-pMMHxBOZKFU6HgAZ4eyGnwXF/EvPGGqUr0MnZ5+99485wwW41kW91A4LOGxSHhgugZmSChL5AlElNdwlNgcnLQ==",
       "funding": [
         {
           "type": "opencollective",