@doccov/api 0.3.3 → 0.3.5

package/lib/plan-agent.ts

@@ -0,0 +1,252 @@
+/**
+ * AI-powered build plan generation agent.
+ * Uses Claude to analyze repository context and generate execution plans.
+ */
+
+import { createAnthropic } from '@ai-sdk/anthropic';
+import { generateObject } from 'ai';
+import { z } from 'zod';
+import type {
+  BuildPlan,
+  BuildPlanEnvironment,
+  BuildPlanStep,
+  BuildPlanTarget,
+  GitHubProjectContext,
+} from '@doccov/sdk';
+
+/**
+ * Zod schema for build plan validation.
+ */
+const BuildPlanStepSchema = z.object({
+  id: z.string().describe('Unique identifier (e.g., "install", "build-types")'),
+  name: z.string().describe('Human-readable step name'),
+  command: z.string().describe('Command to execute'),
+  args: z.array(z.string()).describe('Command arguments'),
+  cwd: z.string().optional().describe('Working directory relative to repo root'),
+  timeout: z.number().optional().describe('Timeout in milliseconds'),
+  optional: z.boolean().optional().describe('If true, failure does not stop execution'),
+});
+
+const BuildPlanEnvironmentSchema = z.object({
+  runtime: z.enum(['node22', 'node24']).describe('Runtime to use (node22 or node24)'),
+  packageManager: z.enum(['npm', 'yarn', 'pnpm', 'bun']).describe('Package manager'),
+  requiredTools: z.array(z.string()).optional().describe('Additional required tools'),
+});
+
+const BuildPlanReasoningSchema = z.object({
+  summary: z.string().describe('Brief summary of the approach (1-2 sentences)'),
+  rationale: z.string().describe('Why this approach was chosen'),
+  concerns: z.array(z.string()).describe('Potential issues or concerns'),
+});
+
+const AIBuildPlanSchema = z.object({
+  environment: BuildPlanEnvironmentSchema,
+  steps: z.array(BuildPlanStepSchema).describe('Steps to execute in order'),
+  entryPoints: z.array(z.string()).describe('Entry point files to analyze'),
+  reasoning: BuildPlanReasoningSchema,
+  confidence: z.enum(['high', 'medium', 'low']).describe('Confidence in this plan'),
+});
+
+type AIBuildPlanOutput = z.infer<typeof AIBuildPlanSchema>;
+
+/**
+ * Options for build plan generation.
+ */
+export interface GenerateBuildPlanOptions {
+  /** Target a specific package in a monorepo */
+  targetPackage?: string;
+  /** Override the default model */
+  model?: string;
+}
+
+/**
+ * Format project context for the AI prompt.
+ */
+function formatContext(context: GitHubProjectContext): string {
+  const sections: string[] = [];
+
+  // Repository metadata
+  sections.push(`=== Repository ===
+Owner: ${context.metadata.owner}
+Repo: ${context.metadata.repo}
+Language: ${context.metadata.language ?? 'unknown'}
+Topics: ${context.metadata.topics.join(', ') || 'none'}
+Description: ${context.metadata.description ?? 'none'}`);
+
+  // Environment detection
+  sections.push(`=== Environment ===
+Package Manager: ${context.packageManager}
+Is Monorepo: ${context.workspace.isMonorepo}
+Workspace Tool: ${context.workspace.tool ?? 'none'}
+Workspace Packages: ${context.workspace.packages?.join(', ') ?? 'none'}`);
+
+  // Build hints
+  sections.push(`=== Build Hints ===
+Has TypeScript: ${context.buildHints.hasTypeScript}
+Has WASM: ${context.buildHints.hasWasm}
+Has Native Modules: ${context.buildHints.hasNativeModules}
+Has Build Script: ${context.buildHints.hasBuildScript}
+Build Script: ${context.buildHints.buildScript ?? 'none'}
+Frameworks: ${context.buildHints.frameworks.join(', ') || 'none'}`);
+
+  // File contents
+  if (context.files.packageJson) {
+    const truncated =
+      context.files.packageJson.length > 3000
+        ? `${context.files.packageJson.slice(0, 3000)}\n... (truncated)`
+        : context.files.packageJson;
+    sections.push(`=== package.json ===\n${truncated}`);
+  }
+
+  if (context.files.tsconfigJson) {
+    sections.push(`=== tsconfig.json ===\n${context.files.tsconfigJson}`);
+  }
+
+  if (context.files.lockfile) {
+    // Only include first 500 chars of lockfile
+    const preview = context.files.lockfile.content.slice(0, 500);
+    sections.push(`=== ${context.files.lockfile.name} (preview) ===\n${preview}\n...`);
+  }
+
+  return sections.join('\n\n');
+}
+
+/**
+ * System prompt for build plan generation.
+ */
+const SYSTEM_PROMPT = `You are a build system expert. Your task is to analyze a GitHub repository and generate a build plan to analyze its TypeScript/JavaScript API.
+
+The goal is to:
+1. Install dependencies
+2. Build the project (if needed) to generate TypeScript declarations
+3. Identify entry points for API documentation analysis
+
+Package Manager Selection:
+- If a lockfile is detected (package-lock.json, yarn.lock, pnpm-lock.yaml, bun.lockb), use that package manager
+- If Package Manager is "unknown" (no lockfile), default to npm with "npm install" (NOT "npm ci")
+- IMPORTANT: "npm ci" and "--frozen-lockfile" flags ONLY work when a lockfile exists
+- When no lockfile: use "npm install", "yarn install", "pnpm install", or "bun install" (without frozen flags)
+
+Install Commands by Package Manager:
+- npm with lockfile: ["npm", "ci"]
+- npm without lockfile: ["npm", "install"]
+- yarn with lockfile: ["yarn", "install", "--frozen-lockfile"]
+- yarn without lockfile: ["yarn", "install"]
+- pnpm with lockfile: ["pnpm", "install", "--frozen-lockfile"]
+- pnpm without lockfile: ["pnpm", "install"]
+- bun with lockfile: ["bun", "install", "--frozen-lockfile"]
+- bun without lockfile: ["bun", "install"]
+
+General Guidelines:
+- For TypeScript projects, look for "types" or "exports" fields in package.json
+- For monorepos, focus on the target package if specified
+- Common entry points: src/index.ts, dist/index.d.ts, lib/index.ts, distribution/index.d.ts
+- WASM projects may need build steps before .d.ts files exist
+- Be conservative with timeouts (default 60000ms, increase for builds)
+- Installation is usually required first
+- Build step is needed if package.json has a "build" script and the types are in dist/distribution folder
+
+Step ID conventions:
+- "install" - install dependencies
+- "build" - main build step
+- "build-types" - generate type declarations
+- "analyze" - run doccov spec (added automatically)`;
+
+/**
+ * Generate a build plan prompt.
+ */
+function generatePrompt(
+  context: GitHubProjectContext,
+  options: GenerateBuildPlanOptions,
+): string {
+  let prompt = `Analyze this repository and generate a build plan:\n\n${formatContext(context)}`;
+
+  if (options.targetPackage) {
+    prompt += `\n\nTarget Package: ${options.targetPackage}
+Focus the plan on building and analyzing only this package within the monorepo.`;
+  }
+
+  prompt += `\n\nGenerate a build plan with:
+- environment: Runtime and package manager configuration
+- steps: Ordered build steps (install, build, etc.)
+- entryPoints: TypeScript entry files to analyze (relative paths)
+- reasoning: Explain your approach
+- confidence: How confident you are in this plan`;
+
+  return prompt;
+}
+
+/**
+ * Get the Anthropic model for plan generation.
+ */
+function getModel() {
+  const anthropic = createAnthropic();
+  return anthropic('claude-sonnet-4-20250514');
+}
+
+/**
+ * Generate a build plan for a GitHub repository.
+ */
+export async function generateBuildPlan(
+  context: GitHubProjectContext,
+  options: GenerateBuildPlanOptions = {},
+): Promise<BuildPlan> {
+  const model = getModel();
+  const prompt = generatePrompt(context, options);
+
+  const { object } = await generateObject({
+    model,
+    schema: AIBuildPlanSchema,
+    system: SYSTEM_PROMPT,
+    prompt,
+  });
+
+  return transformToBuildPlan(object, context, options);
+}
+
+/**
+ * Transform AI output to full BuildPlan.
+ */
+function transformToBuildPlan(
+  output: AIBuildPlanOutput,
+  context: GitHubProjectContext,
+  options: GenerateBuildPlanOptions,
+): BuildPlan {
+  const target: BuildPlanTarget = {
+    type: 'github',
+    repoUrl: `https://github.com/${context.metadata.owner}/${context.metadata.repo}`,
+    ref: context.ref,
+    rootPath: options.targetPackage,
+    entryPoints: output.entryPoints,
+  };
+
+  const environment: BuildPlanEnvironment = {
+    runtime: output.environment.runtime,
+    packageManager: output.environment.packageManager,
+    requiredTools: output.environment.requiredTools,
+  };
+
+  const steps: BuildPlanStep[] = output.steps.map((step) => ({
+    id: step.id,
+    name: step.name,
+    command: step.command,
+    args: step.args,
+    cwd: step.cwd,
+    timeout: step.timeout,
+    optional: step.optional,
+  }));
+
+  return {
+    version: '1.0.0',
+    generatedAt: new Date().toISOString(),
+    target,
+    environment,
+    steps,
+    reasoning: {
+      summary: output.reasoning.summary,
+      rationale: output.reasoning.rationale,
+      concerns: output.reasoning.concerns,
+    },
+    confidence: output.confidence,
+  };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@doccov/api",
-  "version": "0.3.3",
+  "version": "0.3.5",
   "description": "DocCov API - Badge endpoint and coverage services",
   "keywords": [
     "doccov",
@@ -18,17 +18,20 @@
   "license": "MIT",
   "author": "Ryan Waits",
   "type": "module",
-  "main": "./src/index.ts",
   "scripts": {
+    "build": "bunup",
     "dev": "bun run --hot src/index.ts",
     "start": "bun run src/index.ts",
-    "lint": "biome check src/",
-    "lint:fix": "biome check --write src/",
-    "format": "biome format --write src/"
+    "lint": "biome check src/ functions/ lib/",
+    "lint:fix": "biome check --write src/ functions/ lib/",
+    "format": "biome format --write src/ functions/ lib/"
   },
   "dependencies": {
-    "@openpkg-ts/spec": "^0.7.0",
+    "@ai-sdk/anthropic": "^2.0.55",
+    "@doccov/sdk": "^0.13.0",
+    "@openpkg-ts/spec": "^0.9.0",
     "@vercel/sandbox": "^1.0.3",
+    "ai": "^5.0.111",
     "hono": "^4.0.0",
     "ms": "^2.1.3",
     "zod": "^3.25.0"
@@ -38,6 +41,7 @@
     "@types/ms": "^0.7.34",
     "@types/node": "^20.0.0",
     "@vercel/node": "^3.0.0",
+    "bunup": "latest",
     "typescript": "^5.0.0"
   }
 }

package/src/index.ts

@@ -2,20 +2,20 @@ import { Hono } from 'hono';
 import { cors } from 'hono/cors';
 import { rateLimit } from './middleware/rate-limit';
 import { badgeRoute } from './routes/badge';
-import { scanRoute } from './routes/scan';
+import { planRoute } from './routes/plan';
 
 const app = new Hono();
 
 // Middleware
 app.use('*', cors());
 
-// Rate limit /scan endpoint: 10 requests per minute per IP
+// Rate limit /plan endpoint: 10 requests per minute per IP
 app.use(
-  '/scan/*',
+  '/plan',
   rateLimit({
     windowMs: 60 * 1000,
     max: 10,
-    message: 'Too many scan requests. Please try again in a minute.',
+    message: 'Too many plan requests. Please try again in a minute.',
   }),
 );
 
@@ -23,10 +23,12 @@ app.use(
 app.get('/', (c) => {
   return c.json({
     name: 'DocCov API',
-    version: '0.3.0',
+    version: '0.4.0',
     endpoints: {
       badge: '/badge/:owner/:repo',
-      scan: '/scan',
+      plan: '/plan',
+      execute: '/execute',
+      'execute-stream': '/execute-stream',
       health: '/health',
     },
   });
@@ -38,7 +40,7 @@ app.get('/health', (c) => {
 
 // Routes
 app.route('/badge', badgeRoute);
-app.route('/scan', scanRoute);
+app.route('/plan', planRoute);
 
 // Vercel serverless handler + Bun auto-serves this export
 export default app;

package/src/routes/plan.ts

@@ -0,0 +1,75 @@
+/**
+ * Plan route for local development (mirrors api/plan.ts)
+ * Does NOT use Vercel Sandbox - only GitHub API + Anthropic Claude
+ */
+
+import { fetchGitHubContext, parseScanGitHubUrl } from '@doccov/sdk';
+import { Hono } from 'hono';
+import { generateBuildPlan } from '../../lib/plan-agent';
+
+export const planRoute = new Hono();
+
+planRoute.post('/', async (c) => {
+  const body = await c.req.json<{ url: string; ref?: string; package?: string }>();
+
+  if (!body.url) {
+    return c.json({ error: 'url is required' }, 400);
+  }
+
+  // Validate URL format
+  let repoUrl: string;
+  try {
+    const parsed = parseScanGitHubUrl(body.url);
+    if (!parsed) {
+      return c.json({ error: 'Invalid GitHub URL' }, 400);
+    }
+    repoUrl = `https://github.com/${parsed.owner}/${parsed.repo}`;
+  } catch {
+    return c.json({ error: 'Invalid GitHub URL' }, 400);
+  }
+
+  try {
+    // Fetch project context from GitHub
+    const context = await fetchGitHubContext(repoUrl, body.ref);
+
+    // Check for private repos
+    if (context.metadata.isPrivate) {
+      return c.json({
+        error: 'Private repositories are not supported',
+        hint: 'Use a public repository or run doccov locally',
+      }, 403);
+    }
+
+    // Generate build plan using AI
+    const plan = await generateBuildPlan(context, {
+      targetPackage: body.package,
+    });
+
+    return c.json({
+      plan,
+      context: {
+        owner: context.metadata.owner,
+        repo: context.metadata.repo,
+        ref: context.ref,
+        packageManager: context.packageManager,
+        isMonorepo: context.workspace.isMonorepo,
+      },
+    });
+  } catch (error) {
+    console.error('Plan generation error:', error);
+
+    if (error instanceof Error) {
+      if (error.message.includes('404') || error.message.includes('not found')) {
+        return c.json({ error: 'Repository not found' }, 404);
+      }
+      if (error.message.includes('rate limit')) {
+        return c.json({ error: 'GitHub API rate limit exceeded' }, 429);
+      }
+    }
+
+    return c.json({
+      error: 'Failed to generate build plan',
+      message: error instanceof Error ? error.message : 'Unknown error',
+    }, 500);
+  }
+});

package/tsconfig.json

@@ -10,6 +10,6 @@
     "isolatedModules": true,
     "noEmit": true
   },
-  "include": ["api/**/*", "src/**/*"],
-  "exclude": ["node_modules"]
+  "include": ["api/**/*", "functions/**/*", "lib/**/*", "src/**/*"],
+  "exclude": ["node_modules", "dist"]
 }

package/vercel.json

@@ -1,10 +1,12 @@
 {
+  "installCommand": "bun install",
+  "buildCommand": "bun run build",
   "rewrites": [
     { "source": "/badge/:path*", "destination": "/api" },
     { "source": "/spec/:path*", "destination": "/api" },
-    { "source": "/scan-stream", "destination": "/api/scan-stream" },
-    { "source": "/scan/detect", "destination": "/api/scan/detect" },
-    { "source": "/scan", "destination": "/api/scan" },
+    { "source": "/plan", "destination": "/api/plan" },
+    { "source": "/execute", "destination": "/api/execute" },
+    { "source": "/execute-stream", "destination": "/api/execute-stream" },
     { "source": "/(.*)", "destination": "/api" }
   ]
 }

package/api/scan/detect.ts

@@ -1,121 +0,0 @@
-/**
- * Detect endpoint - uses SDK detection via SandboxFileSystem.
- * Detects monorepo structure and package manager for a GitHub repository.
- */
-
-import {
-  detectMonorepo as sdkDetectMonorepo,
-  detectPackageManager,
-  SandboxFileSystem,
-} from '@doccov/sdk';
-import type { VercelRequest, VercelResponse } from '@vercel/node';
-import { Sandbox } from '@vercel/sandbox';
-
-export const config = {
-  runtime: 'nodejs',
-  maxDuration: 60, // Quick detection, 1 minute max
-};
-
-interface DetectRequestBody {
-  url: string;
-  ref?: string;
-}
-
-interface PackageInfo {
-  name: string;
-  path: string;
-  description?: string;
-}
-
-interface DetectResponse {
-  isMonorepo: boolean;
-  packageManager: 'npm' | 'pnpm' | 'bun' | 'yarn';
-  packages?: PackageInfo[];
-  defaultPackage?: string;
-  error?: string;
-}
-
-export default async function handler(req: VercelRequest, res: VercelResponse) {
-  // CORS
-  res.setHeader('Access-Control-Allow-Origin', '*');
-  res.setHeader('Access-Control-Allow-Methods', 'POST, OPTIONS');
-  res.setHeader('Access-Control-Allow-Headers', 'Content-Type');
-
-  if (req.method === 'OPTIONS') {
-    return res.status(200).end();
-  }
-
-  if (req.method !== 'POST') {
-    return res.status(405).json({ error: 'Method not allowed' });
-  }
-
-  const body = req.body as DetectRequestBody;
-
-  if (!body.url) {
-    return res.status(400).json({ error: 'url is required' });
-  }
-
-  try {
-    const result = await detectRepoStructure(body.url);
-    return res.status(200).json(result);
-  } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
-    return res.status(500).json({
-      isMonorepo: false,
-      packageManager: 'npm',
-      error: message,
-    } as DetectResponse);
-  }
-}
-
-/**
- * Detect repository structure using SDK utilities via SandboxFileSystem.
- */
-async function detectRepoStructure(url: string): Promise<DetectResponse> {
-  const sandbox = await Sandbox.create({
-    source: {
-      url,
-      type: 'git',
-    },
-    resources: { vcpus: 2 },
-    timeout: 60 * 1000, // 1 minute
-    runtime: 'node22',
-  });
-
-  try {
-    // Create SDK FileSystem abstraction for sandbox
-    const fs = new SandboxFileSystem(sandbox);
-
-    // Use SDK detection functions
-    const [monoInfo, pmInfo] = await Promise.all([
-      sdkDetectMonorepo(fs),
-      detectPackageManager(fs),
-    ]);
-
-    if (!monoInfo.isMonorepo) {
-      return {
-        isMonorepo: false,
-        packageManager: pmInfo.name,
-      };
-    }
-
-    // Map SDK package info to API response format
-    const packages: PackageInfo[] = monoInfo.packages
-      .filter((p) => !p.private)
-      .map((p) => ({
-        name: p.name,
-        path: p.path,
-        description: p.description,
-      }))
-      .sort((a, b) => a.name.localeCompare(b.name));
-
-    return {
-      isMonorepo: true,
-      packageManager: pmInfo.name,
-      packages,
-      defaultPackage: packages[0]?.name,
-    };
-  } finally {
-    await sandbox.stop();
-  }
-}