refactor: update Devlog API client and schemas for improved filter handling; remove deprecated filter types and enhance pagination support

Author: Marvin Zhang

.github/copilot-instructions.md

@@ -19,13 +19,13 @@
 ## 📁 Development Workflow
 
 - **Temp files**: Use `tmp/` folder for experiments (gitignored)
-- **Build testing**: Use `pnpm build:test` (doesn't break dev servers)
+- **Build packages**: Use `pnpm build` (builds all packages)
 - **Containers**: `docker compose -f docker-compose.dev.yml up web-dev -d --wait`
-- **Build order**: Core → MCP → Web (dependency chain)
+- **Testing**: Use `pnpm test`
 
 ### Task Tracking
 - **Always start by checking**: Search related devlogs before starting ANY new work
-- **Must create devlogs**: For features, refactoring, or multi-step work (>30min)
+- **Must create devlogs**: For features, refactoring, or multistep work (>30min)
 - **Required progress updates**: Add notes after successful builds, major changes, or blockers
 - **Always complete**: Document learnings and close devlogs when work is finished
 

packages/core/src/services/devlog-service.ts

@@ -390,7 +390,12 @@ export class DevlogService {
     return await this.handleList(projectFilter, queryBuilder, pagination, sortOptions);
   }
 
-  async search(query: string, filter?: DevlogFilter): Promise<PaginatedResult<DevlogEntry>> {
+  async search(
+    query: string,
+    filter?: DevlogFilter,
+    pagination?: PaginationMeta,
+    sortOptions?: SortOptions,
+  ): Promise<PaginatedResult<DevlogEntry>> {
     await this.ensureInitialized();
 
     const { projectFilter, queryBuilder } = this.prepareListQuery(filter);
@@ -402,7 +407,7 @@ export class DevlogService {
       .orWhere('devlog.businessContext LIKE :query', { query: `%${query}%` })
       .orWhere('devlog.technicalContext LIKE :query', { query: `%${query}%` });
 
-    return await this.handleList(projectFilter, queryBuilder);
+    return await this.handleList(projectFilter, queryBuilder, pagination, sortOptions);
   }
 
   /**
@@ -838,53 +843,53 @@ export class DevlogService {
    */
   private async applySearchFilters(
     queryBuilder: SelectQueryBuilder<DevlogEntryEntity>,
-    projectFilter: DevlogFilter,
+    filter: DevlogFilter,
   ): Promise<void> {
     // Apply project filter
-    if (projectFilter.projectId !== undefined) {
+    if (filter.projectId !== undefined) {
       queryBuilder.andWhere('devlog.projectId = :projectId', {
-        projectId: projectFilter.projectId,
+        projectId: filter.projectId,
       });
     }
 
     // Apply status filter
-    if (projectFilter.status && projectFilter.status.length > 0) {
-      queryBuilder.andWhere('devlog.status IN (:...statuses)', { statuses: projectFilter.status });
+    if (filter.status && filter.status.length > 0) {
+      queryBuilder.andWhere('devlog.status IN (:...statuses)', { statuses: filter.status });
     }
 
     // Apply type filter
-    if (projectFilter.type && projectFilter.type.length > 0) {
-      queryBuilder.andWhere('devlog.type IN (:...types)', { types: projectFilter.type });
+    if (filter.type && filter.type.length > 0) {
+      queryBuilder.andWhere('devlog.type IN (:...types)', { types: filter.type });
     }
 
     // Apply priority filter
-    if (projectFilter.priority && projectFilter.priority.length > 0) {
+    if (filter.priority && filter.priority.length > 0) {
       queryBuilder.andWhere('devlog.priority IN (:...priorities)', {
-        priorities: projectFilter.priority,
+        priorities: filter.priority,
       });
     }
 
     // Apply assignee filter
-    if (projectFilter.assignee !== undefined) {
-      if (projectFilter.assignee === null) {
+    if (filter.assignee !== undefined) {
+      if (filter.assignee === null) {
         queryBuilder.andWhere('devlog.assignee IS NULL');
       } else {
-        queryBuilder.andWhere('devlog.assignee = :assignee', { assignee: projectFilter.assignee });
+        queryBuilder.andWhere('devlog.assignee = :assignee', { assignee: filter.assignee });
       }
     }
 
     // Apply archived filter
-    if (projectFilter.archived !== undefined) {
-      queryBuilder.andWhere('devlog.archived = :archived', { archived: projectFilter.archived });
+    if (filter.archived !== undefined) {
+      queryBuilder.andWhere('devlog.archived = :archived', { archived: filter.archived });
     }
 
     // Apply date range filters
-    if (projectFilter.fromDate) {
-      queryBuilder.andWhere('devlog.createdAt >= :fromDate', { fromDate: projectFilter.fromDate });
+    if (filter.fromDate) {
+      queryBuilder.andWhere('devlog.createdAt >= :fromDate', { fromDate: filter.fromDate });
     }
 
-    if (projectFilter.toDate) {
-      queryBuilder.andWhere('devlog.createdAt <= :toDate', { toDate: projectFilter.toDate });
+    if (filter.toDate) {
+      queryBuilder.andWhere('devlog.createdAt <= :toDate', { toDate: filter.toDate });
     }
   }
 

packages/core/src/types/core.ts

@@ -197,6 +197,9 @@ export interface Dependency {
 }
 
 export interface DevlogFilter {
+  /**
+   * @deprecated
+   */
   filterType?: FilterType; // New filter dimension for status grouping
   status?: DevlogStatus[];
   type?: DevlogType[];

packages/core/src/utils/filter-mapping.ts

@@ -10,6 +10,7 @@ import type { DevlogStatus, FilterType } from '../types/index.js';
 
 /**
  * Mapping of filter types to their corresponding status arrays
+ * @deprecated
  *
  * This is the single source of truth for status groupings:
  * - 'open': Statuses representing active/in-progress work
@@ -35,6 +36,7 @@ export const FILTER_TYPE_TO_STATUSES: Record<FilterType, DevlogStatus[]> = {
 
 /**
  * Get the status array for a given filter type
+ * @deprecated
  *
  * @param filterType - The filter type to map to statuses
  * @returns Array of DevlogStatus values corresponding to the filter type
@@ -54,6 +56,7 @@ export function getStatusesForFilterType(filterType: FilterType): DevlogStatus[]
 
 /**
  * Check if a status belongs to a specific filter type category
+ * @deprecated
  *
  * @param status - The DevlogStatus to check
  * @param filterType - The FilterType category to check against
@@ -121,6 +124,7 @@ export function isClosedStatus(status: DevlogStatus): boolean {
 
 /**
  * Get the filter type category for a given status
+ * @deprecated
  *
  * @param status - The DevlogStatus to categorize
  * @returns The FilterType category ('open' or 'closed') for the status
@@ -141,6 +145,7 @@ export function getFilterTypeForStatus(status: DevlogStatus): 'open' | 'closed'
 /**
  * Convert a FilterType to an appropriate status array for filtering operations
  * This is the main function to use when applying filters in storage/manager layers
+ * @deprecated
  *
  * @param filterType - The FilterType to convert
  * @returns Array of DevlogStatus values for filtering, or undefined if 'total' (no filtering needed)

packages/core/src/validation/devlog-schemas.ts

@@ -94,20 +94,6 @@ export const DevlogIdSchema = z.number().int().positive('Devlog ID must be a pos
  * Devlog filter validation schema
  */
 export const DevlogFilterSchema = z.object({
-  filterType: z
-    .enum([
-      'new',
-      'in-progress',
-      'blocked',
-      'in-review',
-      'testing',
-      'done',
-      'cancelled',
-      'total',
-      'open',
-      'closed',
-    ])
-    .optional(),
   status: z
     .array(z.enum(['new', 'in-progress', 'blocked', 'in-review', 'testing', 'done', 'cancelled']))
     .optional(),
@@ -121,7 +107,7 @@ export const DevlogFilterSchema = z.object({
   projectId: z.number().int().positive().optional(),
   pagination: z
     .object({
-      page: z.number().int().min(1).optional(),
+      page: z.number().int().min(1).default(20).optional(),
       limit: z.number().int().min(1).max(100).optional(),
     })
     .optional(),

packages/mcp/src/adapters/mcp-adapter.ts

@@ -216,7 +216,8 @@ export class MCPAdapter {
         status: args.status ? [args.status] : undefined,
         type: args.type ? [args.type] : undefined,
         priority: args.priority ? [args.priority] : undefined,
-        pagination: args.limit ? { limit: args.limit } : undefined,
+        page: args.page || 1,
+        limit: args.limit || 10,
       });
 
       const entries = result.items.map((entry: any) => ({
@@ -274,8 +275,10 @@ export class MCPAdapter {
 
     try {
       const searchTerms = [args.description, ...(args.keywords || [])].join(' ');
-      const result = await this.apiClient.searchDevlogs(searchTerms, {
+      const result = await this.apiClient.searchDevlogs({
+        query: searchTerms,
         type: args.type ? [args.type] : undefined,
+        limit: args.limit,
       });
 
       const hasRelated = result.items.length > 0;

packages/mcp/src/api/devlog-api-client.ts

@@ -8,6 +8,8 @@ import type {
   DevlogEntry,
   DevlogFilter,
   PaginatedResult,
+  PaginationMeta,
+  SortOptions,
   UpdateDevlogRequest,
 } from '@codervisor/devlog-core';
 
@@ -232,25 +234,36 @@ export class DevlogApiClient {
     return this.unwrapApiResponse<void>(response);
   }
 
-  async listDevlogs(filter?: DevlogFilter): Promise<PaginatedResult<DevlogEntry>> {
+  async listDevlogs(
+    args?: Partial<DevlogFilter & PaginationMeta & SortOptions>,
+  ): Promise<PaginatedResult<DevlogEntry>> {
     const params = new URLSearchParams();
 
-    if (filter) {
-      this.applyFilterToURLSearchParams(filter, params);
-      if (filter.pagination?.sortBy) params.append('sortBy', filter.pagination.sortBy);
-      if (filter.pagination?.sortOrder) params.append('sortOrder', filter.pagination.sortOrder);
+    if (args) {
+      this.applyFilterToURLSearchParams(args, params);
+
+      if (args.page) params.append('page', args.page.toString());
+      if (args.limit) params.append('limit', args.limit.toString());
+
+      if (args.sortBy) params.append('sortBy', args.sortBy);
+      if (args.sortOrder) params.append('sortOrder', args.sortOrder);
     }
 
     const query = params.toString() ? `?${params.toString()}` : '';
     const response = await this.get(`${this.getProjectEndpoint()}/devlogs${query}`);
     return this.unwrapApiResponse<PaginatedResult<DevlogEntry>>(response);
   }
 
-  async searchDevlogs(query: string, filter?: DevlogFilter): Promise<PaginatedResult<DevlogEntry>> {
+  async searchDevlogs({
+    query,
+    ...args
+  }: { query: string } & Partial<DevlogFilter & PaginationMeta>): Promise<
+    PaginatedResult<DevlogEntry>
+  > {
     const params = new URLSearchParams({ q: query });
 
-    if (filter) {
-      this.applyFilterToURLSearchParams(filter, params);
+    if (args) {
+      this.applyFilterToURLSearchParams(args, params);
     }
 
     const response = await this.get(
@@ -319,7 +332,5 @@ export class DevlogApiClient {
     if (filter.type?.length) params.append('type', filter.type.join(','));
     if (filter.priority?.length) params.append('priority', filter.priority.join(','));
     if (filter.archived !== undefined) params.append('archived', String(filter.archived));
-    if (filter.pagination?.page) params.append('page', String(filter.pagination.page));
-    if (filter.pagination?.limit) params.append('limit', String(filter.pagination.limit));
   }
 }

packages/mcp/src/schemas/base.ts

@@ -52,16 +52,8 @@ export const LimitSchema = z.number().int().min(1).max(50).default(10).optional(
 
 export const PageSchema = z.number().int().min(1).optional();
 
-export const SortBySchema = z
+export const DevlogsSortBySchema = z
   .enum(['createdAt', 'updatedAt', 'priority', 'status', 'title'])
   .optional();
 
 export const SortOrderSchema = z.enum(['asc', 'desc']).optional();
-
-// === TYPE EXPORTS ===
-export type DevlogId = z.infer<typeof DevlogIdSchema>;
-export type ProjectId = z.infer<typeof ProjectIdSchema>;
-export type DevlogType = z.infer<typeof DevlogTypeSchema>;
-export type DevlogStatus = z.infer<typeof DevlogStatusSchema>;
-export type DevlogPriority = z.infer<typeof DevlogPrioritySchema>;
-export type NoteCategory = z.infer<typeof NoteCategorySchema>;

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

@@ -18,6 +18,9 @@ import {
   BusinessContextSchema,
   TechnicalContextSchema,
   AcceptanceCriteriaSchema,
+  PageSchema,
+  DevlogsSortBySchema,
+  SortOrderSchema,
 } from './base.js';
 
 // === CREATE DEVLOG ===
@@ -53,7 +56,10 @@ export const ListDevlogSchema = z.object({
   status: DevlogStatusSchema.optional(),
   type: DevlogTypeSchema.optional(),
   priority: DevlogPrioritySchema.optional(),
+  page: PageSchema,
   limit: LimitSchema,
+  sortBy: DevlogsSortBySchema,
+  sortOrder: SortOrderSchema,
 });
 
 // === ADD NOTE ===
@@ -75,6 +81,7 @@ export const FindRelatedSchema = z.object({
   description: DescriptionSchema,
   type: DevlogTypeSchema.optional(),
   keywords: KeywordsSchema,
+  limit: LimitSchema,
 });
 
 // === TYPE EXPORTS ===