feat(api): enhance route parameter handling with type-safe parsing and validation

Author: Marvin Zhang

package.json

@@ -62,5 +62,6 @@
     "better-sqlite3": "^11.10.0",
     "dotenv": "16.5.0",
     "tsx": "^4.0.0"
-  }
+  },
+  "packageManager": "[email protected]+sha512.37ebf1a5c7a30d5fabe0c5df44ee8da4c965ca0c5af3dbab28c3a1681b70a256218d05c81c9c0dcf767ef6b8551eb5b960042b9ed4300c59242336377e01cfad"
 }

packages/mcp/src/schemas/mcp-tool-schemas.ts

@@ -1,6 +1,6 @@
 /**
  * MCP Tool validation schemas
- * 
+ *
  * This module defines Zod schemas for validating MCP tool arguments.
  * It reuses business logic schemas from @codervisor/devlog-core and adds
  * MCP-specific validation layers.
@@ -12,7 +12,6 @@ import {
   UpdateDevlogEntrySchema,
   DevlogIdSchema,
   DevlogFilterSchema,
-
   CreateProjectRequestSchema,
   UpdateProjectRequestSchema,
   ProjectIdSchema,
@@ -21,25 +20,29 @@ import {
 /**
  * Devlog tool argument schemas
  */
-export const CreateDevlogArgsSchema = z.object({
-  title: z.string().min(1, 'Title is required').max(200, 'Title too long'),
-  type: z.enum(['feature', 'bugfix', 'task', 'refactor', 'docs']),
-  description: z.string().min(1, 'Description is required').max(2000, 'Description too long'),
-  priority: z.enum(['low', 'medium', 'high', 'critical']).optional(),
-  businessContext: z.string().max(1000).optional(),
-  technicalContext: z.string().max(1000).optional(),
-  acceptanceCriteria: z.array(z.string()).optional(),
-}).transform(data => ({
-  ...data,
-  priority: data.priority ?? 'medium' as const,
-}));
+export const CreateDevlogArgsSchema = z
+  .object({
+    title: z.string().min(1, 'Title is required').max(200, 'Title too long'),
+    type: z.enum(['feature', 'bugfix', 'task', 'refactor', 'docs']),
+    description: z.string().min(1, 'Description is required'),
+    priority: z.enum(['low', 'medium', 'high', 'critical']).optional(),
+    businessContext: z.string().optional(),
+    technicalContext: z.string().optional(),
+    acceptanceCriteria: z.array(z.string()).optional(),
+  })
+  .transform((data) => ({
+    ...data,
+    priority: data.priority ?? ('medium' as const),
+  }));
 
 export const UpdateDevlogArgsSchema = z.object({
   id: DevlogIdSchema,
-  status: z.enum(['new', 'in-progress', 'blocked', 'in-review', 'testing', 'done', 'cancelled']).optional(),
+  status: z
+    .enum(['new', 'in-progress', 'blocked', 'in-review', 'testing', 'done', 'cancelled'])
+    .optional(),
   priority: z.enum(['low', 'medium', 'high', 'critical']).optional(),
-  businessContext: z.string().max(1000).optional(),
-  technicalContext: z.string().max(1000).optional(),
+  businessContext: z.string().optional(),
+  technicalContext: z.string().optional(),
   acceptanceCriteria: z.array(z.string()).optional(),
 });
 
@@ -48,7 +51,9 @@ export const GetDevlogArgsSchema = z.object({
 });
 
 export const ListDevlogsArgsSchema = z.object({
-  status: z.enum(['new', 'in-progress', 'blocked', 'in-review', 'testing', 'done', 'cancelled']).optional(),
+  status: z
+    .enum(['new', 'in-progress', 'blocked', 'in-review', 'testing', 'done', 'cancelled'])
+    .optional(),
   type: z.enum(['feature', 'bugfix', 'task', 'refactor', 'docs']).optional(),
   priority: z.enum(['low', 'medium', 'high', 'critical']).optional(),
   archived: z.boolean().optional(),
@@ -60,35 +65,43 @@ export const ListDevlogsArgsSchema = z.object({
 
 export const SearchDevlogsArgsSchema = z.object({
   query: z.string().min(1, 'Search query is required'),
-  status: z.enum(['new', 'in-progress', 'blocked', 'in-review', 'testing', 'done', 'cancelled']).optional(),
+  status: z
+    .enum(['new', 'in-progress', 'blocked', 'in-review', 'testing', 'done', 'cancelled'])
+    .optional(),
   type: z.enum(['feature', 'bugfix', 'task', 'refactor', 'docs']).optional(),
   priority: z.enum(['low', 'medium', 'high', 'critical']).optional(),
   archived: z.boolean().optional(),
 });
 
-export const AddDevlogNoteArgsSchema = z.object({
-  id: DevlogIdSchema,
-  note: z.string().min(1, 'Note content is required'),
-  category: z.enum(['progress', 'issue', 'solution', 'idea', 'reminder', 'feedback']).optional(),
-  files: z.array(z.string()).optional(),
-  codeChanges: z.string().optional(),
-}).transform(data => ({
-  ...data,
-  category: data.category ?? 'progress' as const,
-}));
-
-export const UpdateDevlogWithNoteArgsSchema = z.object({
-  id: DevlogIdSchema,
-  status: z.enum(['new', 'in-progress', 'blocked', 'in-review', 'testing', 'done', 'cancelled']).optional(),
-  priority: z.enum(['low', 'medium', 'high', 'critical']).optional(),
-  note: z.string().min(1, 'Note content is required'),
-  category: z.enum(['progress', 'issue', 'solution', 'idea', 'reminder', 'feedback']).optional(),
-  files: z.array(z.string()).optional(),
-  codeChanges: z.string().optional(),
-}).transform(data => ({
-  ...data,
-  category: data.category ?? 'progress' as const,
-}));
+export const AddDevlogNoteArgsSchema = z
+  .object({
+    id: DevlogIdSchema,
+    note: z.string().min(1, 'Note content is required'),
+    category: z.enum(['progress', 'issue', 'solution', 'idea', 'reminder', 'feedback']).optional(),
+    files: z.array(z.string()).optional(),
+    codeChanges: z.string().optional(),
+  })
+  .transform((data) => ({
+    ...data,
+    category: data.category ?? ('progress' as const),
+  }));
+
+export const UpdateDevlogWithNoteArgsSchema = z
+  .object({
+    id: DevlogIdSchema,
+    status: z
+      .enum(['new', 'in-progress', 'blocked', 'in-review', 'testing', 'done', 'cancelled'])
+      .optional(),
+    priority: z.enum(['low', 'medium', 'high', 'critical']).optional(),
+    note: z.string().min(1, 'Note content is required'),
+    category: z.enum(['progress', 'issue', 'solution', 'idea', 'reminder', 'feedback']).optional(),
+    files: z.array(z.string()).optional(),
+    codeChanges: z.string().optional(),
+  })
+  .transform((data) => ({
+    ...data,
+    category: data.category ?? ('progress' as const),
+  }));
 
 export const CompleteDevlogArgsSchema = z.object({
   id: DevlogIdSchema,
@@ -153,17 +166,17 @@ export class McpToolValidator {
    */
   static validate<T>(
     schema: z.ZodSchema<T>,
-    data: unknown
+    data: unknown,
   ): { success: true; data: T } | { success: false; errors: string[] } {
     const result = schema.safeParse(data);
-    
+
     if (result.success) {
       return { success: true, data: result.data };
     }
 
     return {
       success: false,
-      errors: result.error.errors.map(err => `${err.path.join('.')}: ${err.message}`),
+      errors: result.error.errors.map((err) => `${err.path.join('.')}: ${err.message}`),
     };
   }
 

packages/web/app/devlogs/[id]/DevlogDetailsPage.tsx

@@ -7,23 +7,19 @@ import { useDevlogs } from '@/hooks/useDevlogs';
 import { useRouter } from 'next/navigation';
 import { Button } from '@/components/ui/button';
 import { Alert, AlertDescription } from '@/components/ui/alert';
+import { Popover, PopoverContent, PopoverTrigger } from '@/components/ui/popover';
 import {
-  Popover,
-  PopoverContent,
-  PopoverTrigger,
-} from '@/components/ui/popover';
-import { 
-  ArrowLeftIcon, 
-  TrashIcon, 
-  SaveIcon, 
-  UndoIcon, 
+  ArrowLeftIcon,
+  TrashIcon,
+  SaveIcon,
+  UndoIcon,
   AlertTriangleIcon,
-  InfoIcon
+  InfoIcon,
 } from 'lucide-react';
 import { toast } from 'sonner';
 
 interface DevlogDetailsPageProps {
-  id: string;
+  id: number;
 }
 
 export function DevlogDetailsPage({ id }: DevlogDetailsPageProps) {
@@ -68,16 +64,14 @@ export function DevlogDetailsPage({ id }: DevlogDetailsPageProps) {
 
   const handleDelete = async () => {
     try {
-      const numericId = parseInt(id);
-
       // Call both delete functions to ensure proper state synchronization:
       // 1. Delete from details hook (updates local state immediately)
-      await deleteDevlogFromDetails(numericId);
+      await deleteDevlogFromDetails(id);
 
       // 2. Delete from list context (ensures list state is updated even if SSE is delayed)
       // Note: This is a safety measure in case there are timing issues with real-time events
       try {
-        await deleteDevlogFromList(numericId);
+        await deleteDevlogFromList(id);
       } catch (error) {
         // This might fail if the item is already deleted, which is fine
         console.debug('List deletion failed (likely already removed by SSE):', error);

packages/web/app/devlogs/[id]/page.tsx

@@ -1,4 +1,5 @@
 import { DevlogDetailsPage } from './DevlogDetailsPage';
+import { RouteParamParsers } from '@/lib/route-params';
 
 // Disable static generation for this page since it uses client-side features
 export const dynamic = 'force-dynamic';
@@ -10,5 +11,6 @@ interface DevlogPageProps {
 }
 
 export default function DevlogPage({ params }: DevlogPageProps) {
-  return <DevlogDetailsPage id={params.id} />;
+  const { devlogId } = RouteParamParsers.parseDevlogId(params);
+  return <DevlogDetailsPage id={devlogId} />;
 }

packages/web/app/lib/api-utils.ts

@@ -35,38 +35,77 @@ export function parseParams<T extends Record<string, string>>(
 }
 
 /**
- * Type-safe parameter parser for specific route patterns
+ * Type-safe parameter parser for API routes
  */
 export const RouteParams = {
   /**
    * Parse project ID parameter
    * Usage: /api/projects/[id]
    */
   parseProjectId(params: { id: string }) {
-    const result = parseParams(params);
-    if (!result.success) return result;
+    try {
+      const projectId = parseInt(params.id, 10);
+      if (isNaN(projectId) || projectId <= 0) {
+        return {
+          success: false as const,
+          response: NextResponse.json(
+            { error: 'Invalid project ID: must be a positive integer' },
+            { status: 400 },
+          ),
+        };
+      }
 
-    return {
-      success: true as const,
-      data: { projectId: result.data.id },
-    };
+      return {
+        success: true as const,
+        data: { projectId },
+      };
+    } catch (error) {
+      return {
+        success: false as const,
+        response: NextResponse.json({ error: 'Invalid project ID format' }, { status: 400 }),
+      };
+    }
   },
 
   /**
    * Parse project ID and devlog ID parameters
    * Usage: /api/projects/[id]/devlogs/[devlogId]
    */
   parseProjectAndDevlogId(params: { id: string; devlogId: string }) {
-    const result = parseParams(params);
-    if (!result.success) return result;
-
-    return {
-      success: true as const,
-      data: {
-        projectId: result.data.id,
-        devlogId: result.data.devlogId,
-      },
-    };
+    try {
+      const projectId = parseInt(params.id, 10);
+      const devlogId = parseInt(params.devlogId, 10);
+
+      if (isNaN(projectId) || projectId <= 0) {
+        return {
+          success: false as const,
+          response: NextResponse.json(
+            { error: 'Invalid project ID: must be a positive integer' },
+            { status: 400 },
+          ),
+        };
+      }
+
+      if (isNaN(devlogId) || devlogId <= 0) {
+        return {
+          success: false as const,
+          response: NextResponse.json(
+            { error: 'Invalid devlog ID: must be a positive integer' },
+            { status: 400 },
+          ),
+        };
+      }
+
+      return {
+        success: true as const,
+        data: { projectId, devlogId },
+      };
+    } catch (error) {
+      return {
+        success: false as const,
+        response: NextResponse.json({ error: 'Invalid parameter format' }, { status: 400 }),
+      };
+    }
   },
 };