updating tutorial api reader

Author: afterrburn

app/api/tutorials/[id]/route.ts

@@ -1,7 +1,7 @@
 import { NextRequest, NextResponse } from 'next/server';
-import { join } from 'path';
 import { parseTutorialMDXCached } from '@/lib/tutorial/mdx-parser';
 import { TutorialIdParamsSchema } from '@/lib/tutorial/schemas';
+import { getTutorialFilePath } from '@/lib/tutorial';
 
 interface RouteParams {
   params: Promise<{ id: string }>;
@@ -21,7 +21,13 @@ export async function GET(request: NextRequest, { params }: RouteParams) {
     }
 
     const { id } = validationResult.data;
-    const filePath = join(process.cwd(), 'content', 'Tutorial', `${id}.mdx`);
+    const filePath = await getTutorialFilePath(id);
+    if (!filePath) {
+      return NextResponse.json(
+        { success: false, error: 'Tutorial not found' },
+        { status: 404 }
+      );
+    }
 
     const parsed = await parseTutorialMDXCached(filePath);
 

app/api/tutorials/[id]/steps/[stepNumber]/route.ts

@@ -1,7 +1,7 @@
 import { NextRequest, NextResponse } from 'next/server';
-import { join } from 'path';
 import { parseTutorialMDXCached } from '@/lib/tutorial/mdx-parser';
 import { StepParamsSchema } from '@/lib/tutorial/schemas';
+import { getTutorialFilePath } from '@/lib/tutorial';
 
 interface RouteParams {
   params: Promise<{ id: string; stepNumber: string }>;
@@ -10,29 +10,34 @@ interface RouteParams {
 export async function GET(request: NextRequest, { params }: RouteParams) {
   try {
     const rawParams = await params;
-    
-    // Validate and transform parameters with Zod
+
     const validationResult = StepParamsSchema.safeParse(rawParams);
     if (!validationResult.success) {
       return NextResponse.json(
         { success: false, error: 'Invalid parameters', details: validationResult.error.format() },
         { status: 400 }
       );
     }
-    
+
     const { id, stepNumber: stepNum } = validationResult.data;
-    
-    const filePath = join(process.cwd(), 'content', 'Tutorial', `${id}.mdx`);
+
+    const filePath = await getTutorialFilePath(id);
+    if (!filePath) {
+      return NextResponse.json(
+        { success: false, error: 'Tutorial not found' },
+        { status: 404 }
+      );
+    }
     const parsed = await parseTutorialMDXCached(filePath);
-    
+
     const step = parsed.steps.find(s => s.stepNumber === stepNum);
     if (!step) {
       return NextResponse.json(
         { success: false, error: 'Step not found' },
         { status: 404 }
       );
     }
-    
+
     return NextResponse.json({
       success: true,
       data: {

app/api/tutorials/route.ts

@@ -1,57 +1,46 @@
 import { NextResponse } from 'next/server';
-import { readdir } from 'fs/promises';
 import { join } from 'path';
 import { parseTutorialMDXCached } from '@/lib/tutorial/mdx-parser';
 import { TutorialListItemSchema, type TutorialListItem } from '@/lib/tutorial/schemas';
+import { getTutorialsConfig } from '@/lib/tutorial';
 
 export async function GET() {
   try {
-    const tutorialsDir = join(process.cwd(), 'content', 'Tutorial');
-    
-    // Check if Tutorial directory exists, if not create it for future use
-    let entries: string[];
-    try {
-      entries = await readdir(tutorialsDir);
-    } catch (error) {
-      // Return empty array if Tutorial directory doesn't exist yet
-      return NextResponse.json([]);
-    }
-    
-    const mdxFiles = entries.filter(file => file.endsWith('.mdx'));
-    
+    const config = await getTutorialsConfig();
+
     const tutorials = await Promise.all(
-      mdxFiles.map(async (file): Promise<TutorialListItem | null> => {
+      config.tutorials.map(async (tutorialMeta): Promise<TutorialListItem | null> => {
         try {
-          const filePath = join(tutorialsDir, file);
+          const filePath = join(process.cwd(), 'content', tutorialMeta.path);
           const parsed = await parseTutorialMDXCached(filePath);
-          
+
           const tutorialItem = {
-            id: file.replace('.mdx', ''),
-            title: parsed.metadata.title,
-            description: parsed.metadata.description,
-            totalSteps: parsed.metadata.totalSteps,
-            difficulty: parsed.metadata.difficulty,
-            estimatedTime: parsed.metadata.estimatedTime,
+            id: tutorialMeta.id,
+            title: tutorialMeta.title,
+            description: tutorialMeta.description,
+            totalSteps: parsed.metadata.totalSteps || parsed.steps.length,
+            difficulty: tutorialMeta.difficulty,
+            estimatedTime: tutorialMeta.estimatedTime,
           };
 
           // Validate the tutorial list item
           const validationResult = TutorialListItemSchema.safeParse(tutorialItem);
           if (!validationResult.success) {
-            console.warn(`Invalid tutorial item ${file}:`, validationResult.error.message);
+            console.warn(`Invalid tutorial item ${tutorialMeta.id}:`, validationResult.error.message);
             return null;
           }
 
           return validationResult.data;
         } catch (error) {
-          console.warn(`Failed to parse tutorial ${file}:`, error);
+          console.warn(`Failed to parse tutorial ${tutorialMeta.id} at ${tutorialMeta.path}:`, error);
           return null;
         }
       })
     );
-    
+
     // Filter out failed tutorials
     const validTutorials = tutorials.filter(tutorial => tutorial !== null);
-    
+
     return NextResponse.json(validTutorials);
   } catch (error) {
     console.error('Failed to load tutorials:', error);

content/tutorials.json

@@ -0,0 +1,61 @@
+{
+    "_comment": "This file defines all available tutorials for the tutorial API endpoints. The tutorial API (/api/tutorials) reads from this file to determine which MDX files to process as tutorials, ensuring only intentionally marked files are included. Each tutorial entry must have a corresponding MDX file at the specified path.",
+    "tutorials": [
+        {
+            "id": "01-introduction-to-agents",
+            "title": "Module 1: Introduction to Agents",
+            "description": "Understanding AI agents and the $47B opportunity",
+            "path": "Training/developers/01-introduction-to-agents.mdx",
+            "difficulty": "beginner",
+            "estimatedTime": "15 minutes"
+        },
+        {
+            "id": "02-anatomy-of-an-agent",
+            "title": "Module 2: The Anatomy of an Agent",
+            "description": "Understanding how agents work - planning, reasoning, tools, and memory",
+            "path": "Training/developers/02-anatomy-of-an-agent.mdx",
+            "difficulty": "beginner",
+            "estimatedTime": "20 minutes"
+        },
+    {
+      "id": "03-agent-memory",
+      "title": "Module 3: Agent Memory", 
+      "description": "How agents remember, learn, and build context over time",
+      "path": "Training/developers/03-agent-memory.mdx",
+      "difficulty": "beginner",
+      "estimatedTime": "55 minutes"
+    },
+        {
+            "id": "04-agent-collaboration",
+            "title": "Module 4: Agent-to-Agent Collaboration",
+            "description": "Building multi-agent systems that work together",
+            "path": "Training/developers/04-agent-collaboration.mdx",
+            "difficulty": "intermediate",
+            "estimatedTime": "30 minutes"
+        },
+        {
+            "id": "05-observability-guardrails-evals",
+            "title": "Module 5: Observability, Guardrails, & Evals",
+            "description": "Making agents reliable, safe, and production-ready",
+            "path": "Training/developers/05-observability-guardrails-evals.mdx",
+            "difficulty": "intermediate",
+            "estimatedTime": "25 minutes"
+        },
+        {
+            "id": "06-deployment-environments",
+            "title": "Module 6: Deployment Environments",
+            "description": "From local development to global production",
+            "path": "Training/developers/06-deployment-environments.mdx",
+            "difficulty": "intermediate",
+            "estimatedTime": "20 minutes"
+        },
+        {
+            "id": "07-sandbox-capstone",
+            "title": "Module 7: Advanced Multi-Agent Research System",
+            "description": "Building sophisticated agent coordination with recursive research",
+            "path": "Training/developers/07-sandbox-capstone.mdx",
+            "difficulty": "advanced",
+            "estimatedTime": "45 minutes"
+        }
+    ]
+}

lib/tutorial/index.ts

@@ -1,3 +1,43 @@
 // Tutorial state management exports
 export * from './types';
 export * from './state-manager';
+
+// Tutorial configuration utilities
+import { join } from 'path';
+import { readFile } from 'fs/promises';
+
+interface TutorialMeta {
+  id: string;
+  title: string;
+  description: string;
+  path: string;
+  difficulty?: string;
+  estimatedTime?: string;
+}
+
+interface TutorialsConfig {
+  tutorials: TutorialMeta[];
+}
+
+/**
+ * Reads the tutorials.json configuration file
+ */
+export async function getTutorialsConfig(): Promise<TutorialsConfig> {
+  const configPath = join(process.cwd(), 'content', 'tutorials.json');
+  const configContent = await readFile(configPath, 'utf-8');
+  return JSON.parse(configContent);
+}
+
+/**
+ * Gets the full file path for a specific tutorial based on tutorials.json
+ */
+export async function getTutorialFilePath(tutorialId: string): Promise<string | null> {
+  const config = await getTutorialsConfig();
+  const tutorial = config.tutorials.find(t => t.id === tutorialId);
+  
+  if (!tutorial) {
+    return null;
+  }
+  
+  return join(process.cwd(), 'content', tutorial.path);
+}

lib/tutorial/schemas.ts

@@ -4,7 +4,7 @@ import { z } from 'zod';
 export const TutorialMetadataSchema = z.object({
   title: z.string().min(1, 'Title is required'),
   description: z.string().min(1, 'Description is required'),
-  totalSteps: z.number().positive('Total steps must be a positive number'),
+  totalSteps: z.number().positive('Total steps must be a positive number').optional(),
   difficulty: z.enum(['beginner', 'intermediate', 'advanced']).optional(),
   estimatedTime: z.string().optional()
 });