feat: refactor docs implementation to use deno vercel microservice instead of subprocess

Author: devdumpling

PLAN_MICRO.md

@@ -48,74 +48,62 @@ docs-api/
 ```typescript
 #!/usr/bin/env deno run --allow-net --allow-env
 
-import { doc } from "jsr:@deno/doc";
+import { doc } from 'jsr:@deno/doc'
 
 interface GenerateRequest {
-  package: string;
-  version: string;
+  package: string
+  version: string
 }
 
 function validateAuth(req: Request): boolean {
-  const authHeader = req.headers.get("Authorization");
-  const expectedToken = Deno.env.get("API_SECRET");
-  if (!expectedToken) return true;
-  return authHeader === `Bearer ${expectedToken}`;
+  const authHeader = req.headers.get('Authorization')
+  const expectedToken = Deno.env.get('API_SECRET')
+  if (!expectedToken) return true
+  return authHeader === `Bearer ${expectedToken}`
 }
 
 export default async function handler(req: Request): Promise<Response> {
   const headers = {
-    "Access-Control-Allow-Origin": "https://npmx.dev",
-    "Access-Control-Allow-Methods": "POST, OPTIONS",
-    "Access-Control-Allow-Headers": "Content-Type, Authorization",
-    "Content-Type": "application/json",
-  };
-
-  if (req.method === "OPTIONS") {
-    return new Response(null, { status: 204, headers });
+    'Access-Control-Allow-Origin': 'https://npmx.dev',
+    'Access-Control-Allow-Methods': 'POST, OPTIONS',
+    'Access-Control-Allow-Headers': 'Content-Type, Authorization',
+    'Content-Type': 'application/json',
+  }
+
+  if (req.method === 'OPTIONS') {
+    return new Response(null, { status: 204, headers })
   }
 
-  if (req.method !== "POST") {
-    return new Response(
-      JSON.stringify({ error: "method_not_allowed" }),
-      { status: 405, headers }
-    );
+  if (req.method !== 'POST') {
+    return new Response(JSON.stringify({ error: 'method_not_allowed' }), { status: 405, headers })
   }
 
   if (!validateAuth(req)) {
-    return new Response(
-      JSON.stringify({ error: "unauthorized" }),
-      { status: 401, headers }
-    );
+    return new Response(JSON.stringify({ error: 'unauthorized' }), { status: 401, headers })
   }
 
   try {
-    const body: GenerateRequest = await req.json();
-    
+    const body: GenerateRequest = await req.json()
+
     if (!body.package || !body.version) {
-      return new Response(
-        JSON.stringify({ error: "bad_request" }),
-        { status: 400, headers }
-      );
+      return new Response(JSON.stringify({ error: 'bad_request' }), { status: 400, headers })
     }
 
-    const specifier = `https://esm.sh/${body.package}@${body.version}?target=deno`;
-    const nodes = await doc(specifier);
-    
-    return new Response(JSON.stringify({ nodes }), { status: 200, headers });
+    const specifier = `https://esm.sh/${body.package}@${body.version}?target=deno`
+    const nodes = await doc(specifier)
+
+    return new Response(JSON.stringify({ nodes }), { status: 200, headers })
   } catch (error) {
-    const message = error instanceof Error ? error.message : "Unknown error";
-    
-    if (message.includes("Could not find")) {
-      return new Response(
-        JSON.stringify({ error: "not_found" }),
-        { status: 404, headers }
-      );
+    const message = error instanceof Error ? error.message : 'Unknown error'
+
+    if (message.includes('Could not find')) {
+      return new Response(JSON.stringify({ error: 'not_found' }), { status: 404, headers })
     }
-    
-    return new Response(
-      JSON.stringify({ error: "generation_failed", message }),
-      { status: 500, headers }
-    );
+
+    return new Response(JSON.stringify({ error: 'generation_failed', message }), {
+      status: 500,
+      headers,
+    })
   }
 }
 ```
@@ -139,7 +127,7 @@ async function runDenoDoc(packageName: string, version: string): Promise<DenoDoc
   const headers: Record<string, string> = {
     'Content-Type': 'application/json',
   }
-  
+
   if (DOCS_API_SECRET) {
     headers['Authorization'] = `Bearer ${DOCS_API_SECRET}`
   }
@@ -158,7 +146,7 @@ async function runDenoDoc(packageName: string, version: string): Promise<DenoDoc
     throw new Error(`Docs API error: ${error.message}`)
   }
 
-  return await response.json() as DenoDocResult
+  return (await response.json()) as DenoDocResult
 }
 
 export async function generateDocsWithDeno(
@@ -186,6 +174,7 @@ export async function generateDocsWithDeno(
 #### Remove Unused Code
 
 Delete from `server/utils/docs.ts`:
+
 - `execFileAsync` import
 - `DENO_DOC_TIMEOUT_MS`, `DENO_DOC_MAX_BUFFER` constants
 - `denoCheckPromise`, `isDenoInstalled()`, `verifyDenoInstalled()`
@@ -198,7 +187,7 @@ Keep subprocess as fallback for local dev:
 
 ```typescript
 async function runDenoDoc(packageName: string, version: string): Promise<DenoDocResult> {
-  if (process.dev && await isDenoInstalled()) {
+  if (process.dev && (await isDenoInstalled())) {
     return runLocalDenoDoc(packageName, version)
   }
   return runRemoteDenoDoc(packageName, version)

PLAN_WASM.md

@@ -74,14 +74,14 @@ export async function generateDocsWithWasm(
   version: string,
 ): Promise<DocsGenerationResult | null> {
   const typesUrl = await getTypesUrl(packageName, version)
-  
+
   if (!typesUrl) {
     return null
   }
 
-  const nodes = await doc(typesUrl, {
+  const nodes = (await doc(typesUrl, {
     resolve: createResolver(),
-  }) as DenoDocNode[]
+  })) as DenoDocNode[]
 
   if (!nodes || nodes.length === 0) {
     return null

app/components/AppHeader.vue

@@ -12,7 +12,10 @@ withDefaults(
 </script>
 
 <template>
-  <header aria-label="Site header" class="sticky top-0 z-50 bg-bg/80 backdrop-blur-md border-b border-border">
+  <header
+    aria-label="Site header"
+    class="sticky top-0 z-50 bg-bg/80 backdrop-blur-md border-b border-border"
+  >
     <nav aria-label="Main navigation" class="container h-14 flex items-center justify-between">
       <NuxtLink
         v-if="showLogo"

app/components/DocsVersionSelector.vue

@@ -112,7 +112,11 @@ function handleKeydown(event: KeyboardEvent) {
               v-for="tag in tags"
               :key="tag"
               class="text-[10px] px-1.5 py-0.5 rounded font-sans font-medium"
-              :class="tag === 'latest' ? 'bg-emerald-500/10 text-emerald-400' : 'bg-bg-muted text-fg-subtle'"
+              :class="
+                tag === 'latest'
+                  ? 'bg-emerald-500/10 text-emerald-400'
+                  : 'bg-bg-muted text-fg-subtle'
+              "
             >
               {{ tag }}
             </span>

app/pages/docs/[...path].vue

@@ -93,7 +93,10 @@ const showEmptyState = computed(() => docsData.value?.status !== 'ok')
     <h1 class="sr-only">{{ packageName }} API Documentation</h1>
 
     <!-- Sticky header - positioned below AppHeader -->
-    <header aria-label="Package documentation header" class="docs-header sticky z-10 bg-bg/95 backdrop-blur border-b border-border">
+    <header
+      aria-label="Package documentation header"
+      class="docs-header sticky z-10 bg-bg/95 backdrop-blur border-b border-border"
+    >
       <div class="px-4 sm:px-6 lg:px-8 py-4">
         <div class="flex items-center justify-between gap-4">
           <div class="flex items-center gap-3 min-w-0">
@@ -116,7 +119,9 @@ const showEmptyState = computed(() => docsData.value?.status !== 'ok')
             </span>
           </div>
           <div class="flex items-center gap-3 shrink-0">
-            <span class="text-xs px-2 py-1 rounded bg-emerald-500/10 text-emerald-400 border border-emerald-500/20">
+            <span
+              class="text-xs px-2 py-1 rounded bg-emerald-500/10 text-emerald-400 border border-emerald-500/20"
+            >
               API Docs
             </span>
           </div>
@@ -257,14 +262,30 @@ const showEmptyState = computed(() => docsData.value?.status !== 'ok')
   @apply text-xs px-2 py-0.5 rounded-full font-medium;
 }
 
-.docs-content .docs-badge--function { @apply bg-blue-500/15 text-blue-400; }
-.docs-content .docs-badge--class { @apply bg-amber-500/15 text-amber-400; }
-.docs-content .docs-badge--interface { @apply bg-emerald-500/15 text-emerald-400; }
-.docs-content .docs-badge--typeAlias { @apply bg-violet-500/15 text-violet-400; }
-.docs-content .docs-badge--variable { @apply bg-orange-500/15 text-orange-400; }
-.docs-content .docs-badge--enum { @apply bg-pink-500/15 text-pink-400; }
-.docs-content .docs-badge--namespace { @apply bg-cyan-500/15 text-cyan-400; }
-.docs-content .docs-badge--async { @apply bg-purple-500/15 text-purple-400; }
+.docs-content .docs-badge--function {
+  @apply bg-blue-500/15 text-blue-400;
+}
+.docs-content .docs-badge--class {
+  @apply bg-amber-500/15 text-amber-400;
+}
+.docs-content .docs-badge--interface {
+  @apply bg-emerald-500/15 text-emerald-400;
+}
+.docs-content .docs-badge--typeAlias {
+  @apply bg-violet-500/15 text-violet-400;
+}
+.docs-content .docs-badge--variable {
+  @apply bg-orange-500/15 text-orange-400;
+}
+.docs-content .docs-badge--enum {
+  @apply bg-pink-500/15 text-pink-400;
+}
+.docs-content .docs-badge--namespace {
+  @apply bg-cyan-500/15 text-cyan-400;
+}
+.docs-content .docs-badge--async {
+  @apply bg-purple-500/15 text-purple-400;
+}
 
 /* Signature code block - now uses Shiki */
 .docs-content .docs-signature {

docs-api/README.md

@@ -0,0 +1,56 @@
+# docs-api
+
+A Deno-based microservice for generating API documentation from npm packages.
+
+## Overview
+
+This service uses `@deno/doc` to generate documentation nodes from npm package types via esm.sh. It's designed to run on Vercel using the `vercel-deno` community runtime.
+
+## Deployment
+
+1. Deploy as a separate Vercel project
+2. Configure custom domain (e.g., `docs-api.npmx.dev`)
+3. Optionally set `API_SECRET` environment variable for authentication
+
+## API
+
+### POST /api/generate
+
+Generate documentation for an npm package.
+
+**Request:**
+
+```json
+{
+  "package": "ufo",
+  "version": "1.5.0"
+}
+```
+
+**Response (success):**
+
+```json
+{
+  "nodes": [...]
+}
+```
+
+**Response (error):**
+
+```json
+{
+  "error": "not_found",
+  "message": "Package types not found"
+}
+```
+
+## Local Development
+
+```bash
+cd docs-api
+deno run --allow-net --allow-env api/generate.ts
+```
+
+## Environment Variables
+
+- `API_SECRET` (optional): Bearer token for authentication