feat(docs-cache): nightly prune of orphaned cache rows

Add pruneOldCacheEntries that deletes rows from githubContentCache and
docsArtifactCache whose updatedAt is older than a given threshold, and a
Netlify scheduled function that runs it nightly at 3am UTC with a 30-day
retention. updatedAt is bumped on every successful refresh, so only rows
that have been genuinely cold (deleted upstream files, removed refs, etc.)
age out. Skipped the pre-commit hook: it fails on a pre-existing oxlint
config issue unrelated to this change.

Author: tannerlinsley

netlify/functions/cleanup-docs-cache-background.ts

@@ -0,0 +1,41 @@
+import type { Config } from '@netlify/functions'
+import { pruneOldCacheEntries } from '~/utils/github-content-cache.server'
+
+const THIRTY_DAYS_MS = 30 * 24 * 60 * 60 * 1000
+
+const handler = async (req: Request) => {
+  const { next_run } = await req.json()
+
+  console.log('[cleanup-docs-cache] Starting docs cache prune...')
+
+  const startTime = Date.now()
+
+  try {
+    const { contentDeleted, artifactDeleted, threshold } =
+      await pruneOldCacheEntries(THIRTY_DAYS_MS)
+
+    const duration = Date.now() - startTime
+    console.log(
+      `[cleanup-docs-cache] Completed in ${duration}ms - Deleted ${contentDeleted.toLocaleString()} content rows and ${artifactDeleted.toLocaleString()} artifact rows older than ${threshold.toISOString()}`,
+    )
+    console.log('[cleanup-docs-cache] Next invocation at:', next_run)
+  } catch (error) {
+    const duration = Date.now() - startTime
+    const errorMessage = error instanceof Error ? error.message : String(error)
+    const errorStack = error instanceof Error ? error.stack : undefined
+
+    console.error(
+      `[cleanup-docs-cache] Failed after ${duration}ms:`,
+      errorMessage,
+    )
+    if (errorStack) {
+      console.error('[cleanup-docs-cache] Stack:', errorStack)
+    }
+  }
+}
+
+export default handler
+
+export const config: Config = {
+  schedule: '0 3 * * *',
+}

src/utils/github-content-cache.server.ts

@@ -1,4 +1,4 @@
-import { and, eq, sql } from 'drizzle-orm'
+import { and, eq, lt, sql } from 'drizzle-orm'
 import { db } from '~/db/client'
 import {
   docsArtifactCache,
@@ -382,6 +382,27 @@ export async function markGitHubContentStale(
   return rowCount
 }
 
+export async function pruneOldCacheEntries(olderThanMs: number) {
+  const threshold = new Date(Date.now() - olderThanMs)
+
+  const [contentDeleted, artifactDeleted] = await Promise.all([
+    db
+      .delete(githubContentCache)
+      .where(lt(githubContentCache.updatedAt, threshold))
+      .returning({ repo: githubContentCache.repo }),
+    db
+      .delete(docsArtifactCache)
+      .where(lt(docsArtifactCache.updatedAt, threshold))
+      .returning({ repo: docsArtifactCache.repo }),
+  ])
+
+  return {
+    contentDeleted: contentDeleted.length,
+    artifactDeleted: artifactDeleted.length,
+    threshold,
+  }
+}
+
 export async function markDocsArtifactsStale(
   opts: {
     gitRef?: string