Fix deploy failures: Python global annotation + conditional Clerk

API: Remove type annotation from global _client in supabase_client.py
(Python 3.11 disallows annotated names declared global).

Web: Make Clerk integration conditional so builds succeed without a
valid publishableKey at SSG time. ConditionalClerkProvider checks for
pk_ prefix before initializing. SafeSignInButton, useAuthentication,
AuthButtons, and middleware all handle the Clerk-disabled case.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: 2 people

api/supabase_client.py

@@ -60,7 +60,7 @@ def _get_client():
             "Install it with: pip install supabase"
         )
 
-    _client: Client = create_client(_SUPABASE_URL, _SUPABASE_KEY)
+    _client = create_client(_SUPABASE_URL, _SUPABASE_KEY)
     logger.info(f"Supabase client initialised for {_SUPABASE_URL}")
     return _client
 

src/app/[owner]/[repo]/page.tsx

@@ -29,7 +29,7 @@ import { useWikiCache } from '@/hooks/useWikiCache';
 import { useRepoStructure } from '@/hooks/useRepoStructure';
 import { useWikiExport } from '@/hooks/useWikiExport';
 import { wikiStyles } from '@/styles/wikiStyles';
-import { SignInButton } from '@clerk/nextjs';
+import SafeSignInButton from '@/components/SafeSignInButton';
 
 export default function RepoWikiPage() {
   // Get route parameters and search params
@@ -560,11 +560,11 @@ export default function RepoWikiPage() {
               This repository doesn&apos;t have a cached wiki yet. Sign in to generate an AI-powered wiki for <strong>{owner}/{repo}</strong>.
             </p>
             <div className="flex flex-col gap-3 items-center">
-              <SignInButton mode="modal">
+              <SafeSignInButton mode="modal">
                 <button className="inline-flex items-center justify-center rounded-md text-sm font-medium bg-primary text-primary-foreground hover:bg-primary/90 h-10 px-6 py-2 transition-colors">
                   Sign In to Generate
                 </button>
-              </SignInButton>
+              </SafeSignInButton>
               <button
                 onClick={() => setIsWaitlistModalOpen(true)}
                 className="text-sm text-muted-foreground hover:text-foreground transition-colors underline underline-offset-4"
@@ -971,11 +971,11 @@ export default function RepoWikiPage() {
                 <p className="text-sm text-muted-foreground mb-6">
                   Sign in to ask questions and chat with this codebase using AI.
                 </p>
-                <SignInButton mode="modal">
+                <SafeSignInButton mode="modal">
                   <button className="inline-flex items-center justify-center rounded-md text-sm font-medium bg-primary text-primary-foreground hover:bg-primary/90 h-10 px-6 py-2 transition-colors">
                     Sign In
                   </button>
-                </SignInButton>
+                </SafeSignInButton>
               </div>
             )}
           </div>

src/app/layout.tsx

@@ -1,7 +1,7 @@
 import type { Metadata } from "next";
 import { Inter, Noto_Serif_JP, Plus_Jakarta_Sans, JetBrains_Mono } from "next/font/google";
 import "./globals.css";
-import { ClerkProvider } from "@clerk/nextjs";
+import ConditionalClerkProvider from "@/components/ConditionalClerkProvider";
 import { ThemeProvider } from "next-themes";
 import { LanguageProvider } from "@/contexts/LanguageContext";
 
@@ -56,13 +56,13 @@ export default function RootLayout({
         >
           Skip to content
         </a>
-        <ClerkProvider>
+        <ConditionalClerkProvider>
           <ThemeProvider attribute="class" defaultTheme="system" enableSystem>
             <LanguageProvider>
               {children}
             </LanguageProvider>
           </ThemeProvider>
-        </ClerkProvider>
+        </ConditionalClerkProvider>
       </body>
     </html>
   );

src/components/AuthButtons.tsx

@@ -2,11 +2,29 @@
 
 import { SignInButton, SignedIn, SignedOut, UserButton } from "@clerk/nextjs";
 
+const clerkPubKey = process.env.NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY ?? "";
+const isClerkEnabled = clerkPubKey.startsWith("pk_");
+
 interface AuthButtonsProps {
   onWaitlistClick?: () => void;
 }
 
 export default function AuthButtons({ onWaitlistClick }: AuthButtonsProps) {
+  // When Clerk is not configured, only show the waitlist button (if provided)
+  if (!isClerkEnabled) {
+    return onWaitlistClick ? (
+      <div className="flex items-center gap-3">
+        <button
+          type="button"
+          onClick={onWaitlistClick}
+          className="px-4 py-2 text-label-lg text-primary-foreground bg-primary rounded-lg hover:bg-primary/90 transition-colors"
+        >
+          Join Waitlist
+        </button>
+      </div>
+    ) : null;
+  }
+
   return (
     <div className="flex items-center gap-3">
       <SignedOut>

src/components/ConditionalClerkProvider.tsx

@@ -0,0 +1,28 @@
+import { ClerkProvider } from "@clerk/nextjs";
+
+/**
+ * Wraps children in ClerkProvider only when a valid publishable key is available.
+ *
+ * During Docker builds, NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY may be empty or
+ * unavailable. The Clerk SDK validates the key eagerly and throws if it's
+ * invalid, which breaks Next.js static page prerendering (e.g. /_not-found).
+ *
+ * This component checks for a key that looks valid (starts with "pk_")
+ * before mounting ClerkProvider. When the key is missing or empty, children
+ * render without Clerk — auth features simply won't be available.
+ */
+
+const clerkPubKey = process.env.NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY ?? "";
+const isClerkEnabled = clerkPubKey.startsWith("pk_");
+
+export default function ConditionalClerkProvider({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
+  if (!isClerkEnabled) {
+    return <>{children}</>;
+  }
+
+  return <ClerkProvider>{children}</ClerkProvider>;
+}

src/components/SafeSignInButton.tsx

@@ -0,0 +1,30 @@
+"use client";
+
+import React from "react";
+
+const clerkPubKey = process.env.NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY ?? "";
+const isClerkEnabled = clerkPubKey.startsWith("pk_");
+
+/**
+ * A wrapper around Clerk's SignInButton that gracefully degrades when
+ * Clerk is not configured. When Clerk is unavailable, it renders
+ * nothing (the children button is hidden since sign-in would not work).
+ */
+export default function SafeSignInButton({
+  mode,
+  children,
+}: {
+  mode?: "modal" | "redirect";
+  children: React.ReactNode;
+}) {
+  if (!isClerkEnabled) {
+    // Without Clerk, sign-in is not available — render nothing
+    return null;
+  }
+
+  // Lazily require to avoid context errors when ClerkProvider is absent
+  // eslint-disable-next-line @typescript-eslint/no-require-imports
+  const { SignInButton } = require("@clerk/nextjs");
+
+  return <SignInButton mode={mode}>{children}</SignInButton>;
+}

src/hooks/useAuthentication.ts

@@ -1,7 +1,18 @@
 'use client';
 
 import { useState, useEffect, useCallback } from 'react';
-import { useAuth } from '@clerk/nextjs';
+
+// Clerk is only available when a valid publishable key is configured.
+const clerkPubKey = process.env.NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY ?? "";
+const isClerkEnabled = clerkPubKey.startsWith("pk_");
+
+// Conditionally resolve the useAuth hook at module scope.
+// When Clerk is not configured, we use a no-op stub that returns safe defaults.
+const useAuth: () => { isLoaded: boolean; isSignedIn: boolean; getToken: (() => Promise<string | null>) | null } =
+  isClerkEnabled
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    ? require('@clerk/nextjs').useAuth
+    : () => ({ isLoaded: true, isSignedIn: false, getToken: null });
 
 interface UseAuthenticationReturn {
   /** Whether the backend requires auth codes (legacy) */
@@ -21,7 +32,8 @@ interface UseAuthenticationReturn {
 }
 
 export function useAuthentication(): UseAuthenticationReturn {
-  // Clerk auth state
+  // useAuth is always the same function reference per build — either Clerk's
+  // hook or the no-op stub — so this satisfies the Rules of Hooks.
   const { isLoaded, isSignedIn, getToken: clerkGetToken } = useAuth();
 
   // Legacy backend auth status
@@ -53,7 +65,7 @@ export function useAuthentication(): UseAuthenticationReturn {
 
   // Wrapper around Clerk's getToken that handles edge cases
   const getToken = useCallback(async (): Promise<string | null> => {
-    if (!isLoaded || !isSignedIn) return null;
+    if (!isLoaded || !isSignedIn || !clerkGetToken) return null;
     try {
       return await clerkGetToken();
     } catch (err) {

src/middleware.ts

@@ -1,33 +1,34 @@
 import { clerkMiddleware, createRouteMatcher } from "@clerk/nextjs/server";
-import { NextResponse } from 'next/server';
+import { NextResponse, type NextRequest } from 'next/server';
 
 const PLATFORMS = new Set(['github', 'gitlab', 'bitbucket']);
 
 // Reserved paths that should NOT be treated as platform prefixes
 const RESERVED_PATHS = new Set(['api', 'wiki', '_next', 'favicon.ico', 'embed']);
 
+// Check whether Clerk is configured with a valid publishable key
+const clerkPubKey = process.env.NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY ?? "";
+const isClerkEnabled = clerkPubKey.startsWith("pk_");
+
 // Define public routes that don't require authentication
-const isPublicRoute = createRouteMatcher([
-  "/",                    // Landing page
-  "/wiki/projects",       // Cached project browser
-  "/api/(.*)",            // API rewrites to backend
-  "/webhooks/(.*)",       // Webhook endpoints
-  "/_next/(.*)",          // Next.js internals
-  "/favicon.ico",         // Favicon
-  "/.*\\..*",             // Static assets (files with extensions)
-]);
-
-export default clerkMiddleware(async (auth, request) => {
-  // Public routes pass through without auth checks.
-  // All other routes (e.g. /[owner]/[repo]) go through Clerk's auth
-  // middleware which attaches auth info but does not block access.
-  // Feature gating is handled at the component level.
-  if (!isPublicRoute(request)) {
-    // Don't call auth.protect() — we just let Clerk attach auth info.
-    // The wiki viewer components will check auth status themselves.
-  }
+const isPublicRoute = isClerkEnabled
+  ? createRouteMatcher([
+      "/",                    // Landing page
+      "/wiki/projects",       // Cached project browser
+      "/api/(.*)",            // API rewrites to backend
+      "/webhooks/(.*)",       // Webhook endpoints
+      "/_next/(.*)",          // Next.js internals
+      "/favicon.ico",         // Favicon
+      "/.*\\..*",             // Static assets (files with extensions)
+    ])
+  : null;
 
-  // Platform prefix rewriting: /github/owner/repo → /owner/repo?type=github
+/**
+ * Shared platform-prefix rewrite logic.
+ * Rewrites /github/owner/repo → /owner/repo?type=github (and likewise for gitlab/bitbucket).
+ * Returns a NextResponse rewrite if applicable, otherwise null.
+ */
+function handlePlatformRewrite(request: NextRequest): NextResponse | null {
   const { pathname, searchParams } = request.nextUrl;
   const segments = pathname.split('/').filter(Boolean);
 
@@ -46,8 +47,33 @@ export default clerkMiddleware(async (auth, request) => {
     return NextResponse.rewrite(url);
   }
 
-  return NextResponse.next();
-});
+  return null;
+}
+
+// When Clerk is enabled, wrap platform rewriting inside clerkMiddleware so
+// auth info is attached to every request.
+const clerkHandler = isClerkEnabled
+  ? clerkMiddleware(async (auth, request) => {
+      // Public routes pass through without auth checks.
+      // All other routes (e.g. /[owner]/[repo]) go through Clerk's auth
+      // middleware which attaches auth info but does not block access.
+      // Feature gating is handled at the component level.
+      if (isPublicRoute && !isPublicRoute(request)) {
+        // Don't call auth.protect() — we just let Clerk attach auth info.
+        // The wiki viewer components will check auth status themselves.
+      }
+
+      return handlePlatformRewrite(request) ?? NextResponse.next();
+    })
+  : null;
+
+// When Clerk is NOT available (e.g. during Docker build or when key is not
+// configured), use a plain middleware that only handles platform rewrites.
+function plainMiddleware(request: NextRequest) {
+  return handlePlatformRewrite(request) ?? NextResponse.next();
+}
+
+export default isClerkEnabled ? clerkHandler! : plainMiddleware;
 
 export const config = {
   matcher: [