feat: Enhance devlog management with integer ID system and semantic key generation

Marvin Zhang · Marvin Zhang · commit e9ae80e7563b · 2025-06-25T14:34:54.000+08:00
diff --git a/.gitignore b/.gitignore
@@ -141,6 +141,7 @@ build/
 
 # Devlog directory - contains local development notes
 .devlog/
+.devlog*
 
 # Devlog configuration with credentials
 devlog.config.json
diff --git a/devlog.config.json.backup b/devlog.config.json.backup
diff --git a/packages/core/src/devlog-manager.ts b/packages/core/src/devlog-manager.ts
@@ -124,10 +124,14 @@ export class DevlogManager {
       return existing;
     }
 
+    // Generate semantic key for reference
+    const key = this.generateKey(request.title, request.type);
+
     // Create new entry
     const now = new Date().toISOString();
     const entry: DevlogEntry = {
       id,
+      key,
       title: request.title,
       type: request.type,
       description: request.description,
@@ -474,9 +478,7 @@ export class DevlogManager {
    */
   async syncDevlog(id: DevlogId): Promise<DevlogEntry | null> {
     await this.ensureInitialized();
-    // Convert ID to string for integration service compatibility
-    const idStr = IdManager.idToString(id);
-    return await this.integrationService.syncEntry(idStr);
+    return await this.integrationService.syncEntry(id);
   }
 
   /**
@@ -513,17 +515,29 @@ export class DevlogManager {
       // Use integer ID system
       return await this.idManager.generateNextId();
     } else {
-      // Fall back to legacy hash-based system
-      const slug = title
-        .toLowerCase()
-        .replace(/[^a-z0-9]+/g, "-")
-        .replace(/^-+|-+$/g, "")
-        .substring(0, 50);
-
-      // Create hash from title and type for consistency
+      // Legacy system no longer supported - always use integers
+      throw new Error("Legacy string IDs are no longer supported. Use integer ID system.");
+    }
+  }
+
+  /**
+   * Generate semantic key for the entry (used for referencing and legacy compatibility)
+   */
+  private generateKey(title: string, type?: DevlogType): string {
+    const slug = title
+      .toLowerCase()
+      .replace(/[^a-z0-9]+/g, "-")
+      .replace(/^-+|-+$/g, "")
+      .substring(0, 50);
+
+    // For consistency with legacy system, optionally include type-based hash
+    if (type && this.useIntegerIds) {
+      // Clean key without hash for new system
+      return slug;
+    } else {
+      // Legacy format with hash
       const content = type ? `${title}:${type}` : title;
       const hash = crypto.createHash("sha256").update(content).digest("hex").substring(0, 8);
-
       return `${slug}--${hash}`;
     }
   }
diff --git a/packages/core/src/integration-service.ts b/packages/core/src/integration-service.ts
@@ -2,7 +2,7 @@
  * Integration service that handles synchronization between local storage and external systems
  */
 
-import { DevlogEntry, EnterpriseIntegration, ExternalReference } from "@devlog/types";
+import { DevlogEntry, EnterpriseIntegration, ExternalReference, DevlogId } from "@devlog/types";
 import { StorageProvider } from "./storage/storage-provider.js";
 import { EnterpriseSync } from "./integrations/enterprise-sync.js";
 import { SyncStrategy } from "./configuration-manager.js";
@@ -86,7 +86,7 @@ export class IntegrationService {
   /**
    * Manually sync an entry to external systems
    */
-  async syncEntry(entryId: string): Promise<DevlogEntry | null> {
+  async syncEntry(entryId: DevlogId): Promise<DevlogEntry | null> {
     const entry = await this.storage.get(entryId);
     if (!entry || !this.enterpriseSync) {
       return entry;
diff --git a/packages/core/src/utils/devlog-utils.ts b/packages/core/src/utils/devlog-utils.ts
@@ -1,56 +1,46 @@
 import * as crypto from "crypto";
-import { DevlogType, DevlogEntry, DevlogFilter, DevlogNote } from "@devlog/types";
+import { DevlogType, DevlogEntry, DevlogFilter, DevlogNote, DevlogId } from "@devlog/types";
 
 export class DevlogUtils {
-  static generateId(title: string, type?: DevlogType): string {
+  /**
+   * Generate semantic key for devlog entry (used for the key field)
+   */
+  static generateKey(title: string, type?: DevlogType): string {
     // Create a clean slug from the title
     const slug = title
       .toLowerCase()
       .replace(/[^a-z0-9]+/g, "-")
       .replace(/^-+|-+$/g, "")
       .substring(0, 50); // Limit length
 
-    // Add type prefix if provided
-    const prefix = type ? `${type}-` : "";
-    
-    // Create a hash of the full input for uniqueness
-    const hash = crypto.createHash('md5')
-      .update(`${type || 'unknown'}-${title}`)
-      .digest('hex')
-      .substring(0, 8);
-
-    return `${prefix}${slug}-${hash}`;
+    return slug;
+  }
+  
+  /**
+   * Legacy method for backward compatibility - now generates keys instead of IDs
+   * @deprecated Use generateKey instead
+   */
+  static generateId(title: string, type?: DevlogType): string {
+    return DevlogUtils.generateKey(title, type);
   }
 
+  /**
+   * Generate unique key (deprecated - integer IDs handle uniqueness automatically)
+   * @deprecated No longer needed with integer ID system
+   */
   static async generateUniqueId(
     title: string, 
     type: DevlogType | undefined, 
     checkExisting: (id: string) => Promise<DevlogEntry | null>
   ): Promise<string> {
-    const baseId = DevlogUtils.generateId(title, type);
-    const existing = await checkExisting(baseId);
-    if (!existing) {
-      return baseId;
-    }
-    
-    // If it exists, add a counter suffix
-    let counter = 1;
-    let uniqueId: string;
-    
-    do {
-      uniqueId = `${baseId}-${counter}`;
-      counter++;
-    } while (await checkExisting(uniqueId) && counter < 100); // Prevent infinite loop
-    
-    // Fallback to timestamp if we can't find a unique ID
-    return counter >= 100 ? `${baseId}-${Date.now()}` : uniqueId;
+    return DevlogUtils.generateKey(title, type);
   }
 
   static async checkForDuplicateTitle(
     title: string, 
     type: DevlogType | undefined, 
     getAllEntries: () => Promise<DevlogEntry[]>,
-    excludeId?: string
+    excludeId?: DevlogId
   ): Promise<DevlogEntry | null> {
     const entries = await getAllEntries();
     const normalizedTitle = title.toLowerCase().trim();
diff --git a/packages/core/src/utils/id-manager.ts b/packages/core/src/utils/id-manager.ts
@@ -22,15 +22,14 @@ export class IdManager {
   }
 
   /**
-   * Convert string ID back to appropriate type (detect if it's a number)
+   * Convert string ID back to integer (since all IDs are now integers)
    */
   static stringToId(idStr: string): DevlogId {
-    // Check if it's a pure integer
     const parsed = parseInt(idStr, 10);
-    if (!isNaN(parsed) && String(parsed) === idStr) {
-      return parsed;
+    if (isNaN(parsed)) {
+      throw new Error(`Invalid integer ID: ${idStr}`);
     }
-    return idStr;
+    return parsed;
   }
 
   /**
diff --git a/packages/mcp/src/ai-context-demo.ts b/packages/mcp/src/ai-context-demo.ts
@@ -24,10 +24,12 @@ export class AIContextManager {
   }): Promise<DevlogEntry> {
     
     const now = new Date().toISOString();
-    const id = `task-${Date.now()}`;
+    // Generate integer ID using timestamp-based approach
+    const id = parseInt(Date.now().toString().slice(-8), 10);
     
     const entry: DevlogEntry = {
       id,
+      key: `task-${Date.now()}`, // Use string for the key field
       title: taskData.title,
       type: "feature",
       description: taskData.description,
diff --git a/packages/mcp/src/mcp-adapter.ts b/packages/mcp/src/mcp-adapter.ts
@@ -17,6 +17,15 @@ export class MCPDevlogAdapter {
     this.devlogManager = new DevlogManager();
   }
 
+  // Helper function to parse string ID to number
+  private parseId(idStr: string): number {
+    const id = parseInt(idStr, 10);
+    if (isNaN(id)) {
+      throw new Error(`Invalid devlog ID "${idStr}". Must be a number.`);
+    }
+    return id;
+  }
+
   /**
    * Initialize the adapter with appropriate storage configuration
    */
@@ -63,7 +72,8 @@ export class MCPDevlogAdapter {
   async getDevlog(args: { id: string }): Promise<CallToolResult> {
     await this.ensureInitialized();
     
-    const entry = await this.devlogManager.getDevlog(args.id);
+    const id = this.parseId(args.id);
+    const entry = await this.devlogManager.getDevlog(id);
     
     if (!entry) {
       return {
@@ -156,8 +166,9 @@ export class MCPDevlogAdapter {
   async addDevlogNote(args: { id: string; note: string; category?: string }): Promise<CallToolResult> {
     await this.ensureInitialized();
     
+    const id = this.parseId(args.id);
     const category = args.category as any || "progress";
-    const entry = await this.devlogManager.addNote(args.id, args.note, category);
+    const entry = await this.devlogManager.addNote(id, args.note, category);
     
     return {
       content: [
@@ -172,7 +183,8 @@ export class MCPDevlogAdapter {
   async addDecision(args: { id: string; decision: string; rationale: string; decisionMaker: string; alternatives?: string[] }): Promise<CallToolResult> {
     await this.ensureInitialized();
     
-    const entry = await this.devlogManager.getDevlog(args.id);
+    const id = this.parseId(args.id);
+    const entry = await this.devlogManager.getDevlog(id);
     if (!entry) {
       return {
         content: [
@@ -198,7 +210,7 @@ export class MCPDevlogAdapter {
     
     // Update the entry to trigger save
     const updated = await this.devlogManager.updateDevlog({
-      id: args.id,
+      id: id,
       // Use a field that exists in UpdateDevlogRequest to trigger save
       tags: entry.tags
     });
@@ -216,7 +228,8 @@ export class MCPDevlogAdapter {
   async completeDevlog(args: { id: string; summary?: string }): Promise<CallToolResult> {
     await this.ensureInitialized();
     
-    const entry = await this.devlogManager.completeDevlog(args.id, args.summary);
+    const id = this.parseId(args.id);
+    const entry = await this.devlogManager.completeDevlog(id, args.summary);
     
     return {
       content: [
@@ -271,7 +284,8 @@ export class MCPDevlogAdapter {
   async getContextForAI(args: { id: string }): Promise<CallToolResult> {
     await this.ensureInitialized();
     
-    const entry = await this.devlogManager.getContextForAI(args.id);
+    const id = this.parseId(args.id);
+    const entry = await this.devlogManager.getContextForAI(id);
     
     if (!entry) {
       return {
@@ -320,6 +334,7 @@ export class MCPDevlogAdapter {
   }): Promise<CallToolResult> {
     await this.ensureInitialized();
     
+    const id = this.parseId(args.id);
     const contextUpdate: any = {};
     
     if (args.summary) contextUpdate.currentSummary = args.summary;
@@ -331,7 +346,7 @@ export class MCPDevlogAdapter {
     contextUpdate.lastAIUpdate = new Date().toISOString();
     contextUpdate.contextVersion = (contextUpdate.contextVersion || 0) + 1;
 
-    const entry = await this.devlogManager.updateAIContext(args.id, contextUpdate);
+    const entry = await this.devlogManager.updateAIContext(id, contextUpdate);
     
     return {
       content: [
diff --git a/packages/web/src/server/routes/devlog-routes.ts b/packages/web/src/server/routes/devlog-routes.ts
@@ -2,6 +2,15 @@ import { Router } from 'express';
 import { DevlogManager } from '@devlog/core';
 import { CreateDevlogRequest, UpdateDevlogRequest, DevlogFilter } from '@devlog/types';
 
+// Utility function to parse ID from string parameter
+function parseDevlogId(idParam: string): number {
+  const id = parseInt(idParam, 10);
+  if (isNaN(id)) {
+    throw new Error(`Invalid devlog ID: ${idParam}`);
+  }
+  return id;
+}
+
 export function devlogRoutes(devlogManager: DevlogManager): Router {
   const router = Router();
 
@@ -26,7 +35,8 @@ export function devlogRoutes(devlogManager: DevlogManager): Router {
   // Get devlog by ID
   router.get('/:id', async (req, res) => {
     try {
-      const devlog = await devlogManager.getDevlog(req.params.id);
+      const id = parseDevlogId(req.params.id);
+      const devlog = await devlogManager.getDevlog(id);
       if (!devlog) {
         return res.status(404).json({ error: 'Devlog not found' });
       }
@@ -64,7 +74,8 @@ export function devlogRoutes(devlogManager: DevlogManager): Router {
   // Delete devlog
   router.delete('/:id', async (req, res) => {
     try {
-      await devlogManager.deleteDevlog(req.params.id);
+      const id = parseDevlogId(req.params.id);
+      await devlogManager.deleteDevlog(id);
       res.status(204).send();
     } catch (error) {
       console.error('Error deleting devlog:', error);
@@ -75,8 +86,9 @@ export function devlogRoutes(devlogManager: DevlogManager): Router {
   // Add note to devlog
   router.post('/:id/notes', async (req, res) => {
     try {
+      const id = parseDevlogId(req.params.id);
       const { note } = req.body;
-      const devlog = await devlogManager.addNote(req.params.id, note);
+      const devlog = await devlogManager.addNote(id, note);
       res.json(devlog);
     } catch (error) {
       console.error('Error adding note:', error);

Original file line number	Diff line number	Diff line change
`@@ -22,15 +22,14 @@ export class IdManager {`
`22`	`22`	`}`
`23`	`23`
`24`	`24`	`/**`
`25`		`- * Convert string ID back to appropriate type (detect if it's a number)`
	`25`	`+ * Convert string ID back to integer (since all IDs are now integers)`
`26`	`26`	`*/`
`27`	`27`	`static stringToId(idStr: string): DevlogId {`
`28`		`- // Check if it's a pure integer`
`29`	`28`	`const parsed = parseInt(idStr, 10);`
`30`		`- if (!isNaN(parsed) && String(parsed) === idStr) {`
`31`		`- return parsed;`
	`29`	`+ if (isNaN(parsed)) {`
	`30`	+ throw new Error(`Invalid integer ID: ${idStr}`);
`32`	`31`	`}`
`33`		`- return idStr;`
	`32`	`+ return parsed;`
`34`	`33`	`}`
`35`	`34`
`36`	`35`	`/**`