@sudocode-ai/cli 0.1.7 → 0.1.8

package/dist/watcher.js

@@ -13,20 +13,83 @@ import { listIssues, getIssue } from "./operations/issues.js";
 import { parseMarkdownFile } from "./markdown.js";
 import { listFeedback } from "./operations/feedback.js";
 import { getTags } from "./operations/tags.js";
+import { findExistingEntityFile, generateUniqueFilename, } from "./filename-generator.js";
+import { getOutgoingRelationships } from "./operations/relationships.js";
+import * as crypto from "crypto";
+// Guard against processing our own file writes (oscillation prevention)
+// Track files currently being processed to prevent same-file oscillation
+const filesBeingProcessed = new Set();
+// Content hash cache for detecting actual content changes (oscillation prevention)
+const contentHashCache = new Map();
+/**
+ * Compute SHA256 hash of file content for change detection
+ */
+function computeContentHash(filePath) {
+    try {
+        const content = fs.readFileSync(filePath, "utf8");
+        return crypto.createHash("sha256").update(content).digest("hex");
+    }
+    catch (error) {
+        // File doesn't exist or can't be read
+        return "";
+    }
+}
+/**
+ * Check if file content has actually changed since last processing
+ * Returns true if content changed, false if unchanged
+ */
+function hasContentChanged(filePath) {
+    const currentHash = computeContentHash(filePath);
+    const cachedHash = contentHashCache.get(filePath);
+    if (cachedHash && cachedHash === currentHash) {
+        // Content unchanged - skip processing
+        return false;
+    }
+    // Update cache with new hash
+    contentHashCache.set(filePath, currentHash);
+    return true;
+}
 /**
  * Start watching files for changes
  * Returns a control object to stop the watcher
  */
 export function startWatcher(options) {
-    const { db, baseDir, debounceDelay = 2000, onLog = console.log, onError = console.error, ignoreInitial = true, syncJSONLToMarkdown: enableReverseSync = false, } = options;
+    const { db, baseDir, onLog = console.log, onError = console.error, ignoreInitial = true, syncJSONLToMarkdown: enableReverseSync = false, onEntitySync, onFileChange, } = options;
     const stats = {
         filesWatched: 0,
-        changesPending: 0,
         changesProcessed: 0,
         errors: 0,
     };
-    // Map of file paths to pending timeout IDs
-    const pendingChanges = new Map();
+    // Cache of previous JSONL state (entity ID -> timestamp)
+    // This allows us to detect changes by comparing new JSONL against cached state
+    const jsonlStateCache = new Map(); // jsonlPath -> (entityId -> content_hash)
+    /**
+     * Compute a canonical content hash for an entity that's invariant to key ordering
+     * This ensures that {"id":"x","title":"y"} and {"title":"y","id":"x"} produce the same hash
+     */
+    function computeCanonicalHash(entity) {
+        // Sort keys recursively to ensure consistent ordering
+        const sortKeys = (obj) => {
+            if (obj === null || typeof obj !== "object") {
+                return obj;
+            }
+            if (Array.isArray(obj)) {
+                return obj.map(sortKeys);
+            }
+            const sorted = {};
+            Object.keys(obj)
+                .sort()
+                .forEach((key) => {
+                sorted[key] = sortKeys(obj[key]);
+            });
+            return sorted;
+        };
+        const canonical = sortKeys(entity);
+        return crypto
+            .createHash("sha256")
+            .update(JSON.stringify(canonical))
+            .digest("hex");
+    }
     /**
      * Check if markdown file content matches database content
      * Returns true if they match (no sync needed)
@@ -162,8 +225,7 @@ export function startWatcher(options) {
                 const dbTagsSet = new Set(dbTags);
                 if (jsonlTags.some((tag) => !dbTagsSet.has(tag)))
                     return true;
-                // Compare relationships
-                const { getOutgoingRelationships } = require("./operations/relationships.js");
+                // Compare relationships;
                 const dbRels = getOutgoingRelationships(db, entityId, entityType);
                 const jsonlRels = jsonlEntity.relationships || [];
                 if (jsonlRels.length !== dbRels.length)
@@ -211,172 +273,275 @@ export function startWatcher(options) {
      */
     async function processChange(filePath, event) {
         try {
-            const ext = path.extname(filePath);
-            const basename = path.basename(filePath);
-            if (ext === ".md") {
-                // Markdown file changed - sync to database and JSONL
-                onLog(`[watch] ${event} ${path.relative(baseDir, filePath)}`);
-                if (event === "unlink") {
-                    // File was deleted - remove from database and JSONL
-                    // Calculate relative file path
-                    const relPath = path.relative(baseDir, filePath);
-                    // Look up spec by file path
-                    const spec = getSpecByFilePath(db, relPath);
-                    if (spec) {
-                        // Delete from database
-                        const deleted = deleteSpec(db, spec.id);
-                        if (deleted) {
-                            onLog(`[watch] Deleted spec ${spec.id} (file removed)`);
-                            // Export to JSONL to reflect deletion
-                            await exportToJSONL(db, { outputDir: baseDir });
+            // Set re-entry guard for this specific file to prevent oscillation
+            filesBeingProcessed.add(filePath);
+            try {
+                const ext = path.extname(filePath);
+                const basename = path.basename(filePath);
+                if (ext === ".md") {
+                    // Markdown file changed - sync to database and JSONL
+                    onLog(`[watch] ${event} ${path.relative(baseDir, filePath)}`);
+                    if (event === "unlink") {
+                        // File was deleted - remove from database and JSONL
+                        // Calculate relative file path
+                        const relPath = path.relative(baseDir, filePath);
+                        // Look up spec by file path
+                        const spec = getSpecByFilePath(db, relPath);
+                        if (spec) {
+                            // Delete from database
+                            const deleted = deleteSpec(db, spec.id);
+                            if (deleted) {
+                                onLog(`[watch] Deleted spec ${spec.id} (file removed)`);
+                                // Export to JSONL to reflect deletion
+                                await exportToJSONL(db, { outputDir: baseDir });
+                            }
+                        }
+                        else {
+                            onLog(`[watch] File deleted but no spec found: ${relPath}`);
                         }
                     }
                     else {
-                        onLog(`[watch] File deleted but no spec found: ${relPath}`);
+                        // Parse markdown to get entity info
+                        try {
+                            const parsed = parseMarkdownFile(filePath, db, baseDir);
+                            const { data: frontmatter } = parsed;
+                            const entityId = frontmatter.id;
+                            // Determine entity type based on file location
+                            const relPath = path.relative(baseDir, filePath);
+                            const entityType = relPath.startsWith("specs/") || relPath.startsWith("specs\\")
+                                ? "spec"
+                                : "issue";
+                            // Skip if content already matches (prevents oscillation)
+                            if (entityId && contentMatches(filePath, entityId, entityType)) {
+                                return;
+                            }
+                            // Check timestamps to determine sync direction
+                            if (entityId) {
+                                const dbEntity = entityType === "spec"
+                                    ? getSpec(db, entityId)
+                                    : getIssue(db, entityId);
+                                if (dbEntity) {
+                                    // Get file modification time
+                                    const fileStat = fs.statSync(filePath);
+                                    const fileTime = fileStat.mtimeMs;
+                                    // Get database updated_at time
+                                    const dbTime = new Date(dbEntity.updated_at).getTime();
+                                    // If database is newer than file, skip markdown → database sync
+                                    if (dbTime > fileTime) {
+                                        onLog(`[watch] Skipping sync for ${entityType} ${entityId} (database is newer)`);
+                                        return;
+                                    }
+                                }
+                            }
+                        }
+                        catch (error) {
+                            // If parsing fails, continue with sync (might be a new file)
+                        }
+                        // Sync markdown to database
+                        const result = await syncMarkdownToJSONL(db, filePath, {
+                            outputDir: baseDir,
+                            autoExport: true,
+                            autoInitialize: true,
+                            writeBackFrontmatter: true,
+                        });
+                        if (result.success) {
+                            onLog(`[watch] Synced ${result.entityType} ${result.entityId} (${result.action})`);
+                            // Emit typed callback event for markdown sync
+                            if (onEntitySync) {
+                                // Get full entity data to include in event
+                                const entity = result.entityType === "spec"
+                                    ? getSpec(db, result.entityId)
+                                    : getIssue(db, result.entityId);
+                                await onEntitySync({
+                                    entityType: result.entityType,
+                                    entityId: result.entityId,
+                                    action: result.action,
+                                    filePath,
+                                    baseDir,
+                                    source: "markdown",
+                                    timestamp: new Date(),
+                                    entity: entity ?? undefined,
+                                    version: 1,
+                                });
+                            }
+                        }
+                        else {
+                            onError(new Error(`Failed to sync ${filePath}: ${result.error}`));
+                            stats.errors++;
+                        }
                     }
                 }
-                else {
-                    // Parse markdown to get entity info
-                    try {
-                        const parsed = parseMarkdownFile(filePath, db, baseDir);
-                        const { data: frontmatter } = parsed;
-                        const entityId = frontmatter.id;
-                        // Determine entity type based on file location
-                        const relPath = path.relative(baseDir, filePath);
-                        const entityType = relPath.startsWith("specs/") || relPath.startsWith("specs\\")
-                            ? "spec"
-                            : "issue";
-                        // Skip if content already matches (prevents oscillation)
-                        if (entityId && contentMatches(filePath, entityId, entityType)) {
-                            return;
+                else if (basename === "specs.jsonl" || basename === "issues.jsonl") {
+                    // JSONL file changed (e.g., from CLI update or git pull)
+                    onLog(`[watch] ${event} ${path.relative(baseDir, filePath)}`);
+                    if (event !== "unlink") {
+                        const entityType = basename === "specs.jsonl" ? "spec" : "issue";
+                        // Read JSONL file
+                        const jsonlContent = fs.readFileSync(filePath, "utf8");
+                        const jsonlLines = jsonlContent
+                            .trim()
+                            .split("\n")
+                            .filter((line) => line.trim());
+                        // Parse JSONL entities and build new state map
+                        const jsonlEntities = jsonlLines.map((line) => JSON.parse(line));
+                        const newStateMap = new Map();
+                        for (const entity of jsonlEntities) {
+                            // Use canonical content hash to detect any content changes
+                            // Canonical hash is invariant to JSON key ordering
+                            const contentHash = computeCanonicalHash(entity);
+                            newStateMap.set(entity.id, contentHash);
+                        }
+                        // Get cached state (previous JSONL state)
+                        const cachedStateMap = jsonlStateCache.get(filePath) || new Map();
+                        // Detect changed entities by comparing new state with cached state
+                        const changedEntities = [];
+                        for (const jsonlEntity of jsonlEntities) {
+                            const entityId = jsonlEntity.id;
+                            const newHash = newStateMap.get(entityId);
+                            const cachedHash = cachedStateMap.get(entityId);
+                            if (!cachedHash) {
+                                // Entity not in cache = created
+                                changedEntities.push({ entityId, action: "created" });
+                            }
+                            else if (newHash !== cachedHash) {
+                                // Content hash differs = entity changed
+                                changedEntities.push({ entityId, action: "updated" });
+                            }
                         }
-                        // Check timestamps to determine sync direction
-                        if (entityId) {
-                            const dbEntity = entityType === "spec"
-                                ? getSpec(db, entityId)
-                                : getIssue(db, entityId);
-                            if (dbEntity) {
-                                // Get file modification time
-                                const fileStat = fs.statSync(filePath);
-                                const fileTime = fileStat.mtimeMs;
-                                // Get database updated_at time
-                                const dbTime = new Date(dbEntity.updated_at).getTime();
-                                // If database is newer than file, skip markdown → database sync
-                                if (dbTime > fileTime) {
-                                    onLog(`[watch] Skipping sync for ${entityType} ${entityId} (database is newer)`);
-                                    return;
+                        // Update cache with new state
+                        jsonlStateCache.set(filePath, newStateMap);
+                        if (changedEntities.length > 0) {
+                            onLog(`[watch] Detected ${changedEntities.length} changed ${entityType}(s) in JSONL`);
+                            // Import from JSONL to sync database
+                            // Pass changed entity IDs to force update even if timestamp hasn't changed
+                            // (user may have manually edited JSONL content without updating timestamp)
+                            const changedIds = changedEntities.map((e) => e.entityId);
+                            await importFromJSONL(db, {
+                                inputDir: baseDir,
+                                forceUpdateIds: changedIds,
+                            });
+                            onLog(`[watch] Imported JSONL changes to database`);
+                            // Emit events for changed entities (after import, so we have fresh data)
+                            for (const { entityId, action } of changedEntities) {
+                                onLog(`[watch] Synced ${entityType} ${entityId} (${action})`);
+                                if (onEntitySync) {
+                                    // Get fresh entity data from database (after import)
+                                    const entity = entityType === "spec"
+                                        ? getSpec(db, entityId)
+                                        : getIssue(db, entityId);
+                                    // Find markdown file path
+                                    let entityFilePath;
+                                    if (entityType === "spec" && entity && "file_path" in entity) {
+                                        entityFilePath = path.join(baseDir, entity.file_path);
+                                    }
+                                    else if (entityType === "issue" &&
+                                        entity &&
+                                        "file_path" in entity) {
+                                        entityFilePath = path.join(baseDir, entity.file_path);
+                                    }
+                                    else {
+                                        // Fallback to default path
+                                        entityFilePath = path.join(baseDir, entityType === "spec" ? "specs" : "issues", `${entityId}.md`);
+                                    }
+                                    await onEntitySync({
+                                        entityType,
+                                        entityId: entityId,
+                                        action,
+                                        filePath: entityFilePath,
+                                        baseDir,
+                                        source: "jsonl",
+                                        timestamp: new Date(),
+                                        entity: entity ?? undefined,
+                                        version: 1,
+                                    });
                                 }
                             }
                         }
-                    }
-                    catch (error) {
-                        // If parsing fails, continue with sync (might be a new file)
-                    }
-                    // Sync markdown to database
-                    const result = await syncMarkdownToJSONL(db, filePath, {
-                        outputDir: baseDir,
-                        autoExport: true,
-                        autoInitialize: true,
-                        writeBackFrontmatter: true,
-                    });
-                    if (result.success) {
-                        onLog(`[watch] Synced ${result.entityType} ${result.entityId} (${result.action})`);
-                    }
-                    else {
-                        onError(new Error(`Failed to sync ${filePath}: ${result.error}`));
-                        stats.errors++;
-                    }
-                }
-            }
-            else if (basename === "specs.jsonl" || basename === "issues.jsonl") {
-                // JSONL file changed (e.g., from git pull) - check if import is needed
-                onLog(`[watch] ${event} ${path.relative(baseDir, filePath)}`);
-                if (event !== "unlink") {
-                    // Check if JSONL actually differs from database before importing
-                    if (jsonlNeedsImport(filePath)) {
-                        await importFromJSONL(db, {
-                            inputDir: baseDir,
-                        });
-                        onLog(`[watch] Imported JSONL changes to database`);
-                    }
-                    // Optionally sync database changes back to markdown files
-                    // Only sync entities where content actually differs (contentMatches check)
-                    if (enableReverseSync) {
-                        onLog(`[watch] Checking for entities that need markdown updates...`);
-                        let syncedCount = 0;
-                        // Get all specs and sync to markdown
-                        const specs = listSpecs(db);
-                        for (const spec of specs) {
-                            if (spec.file_path) {
-                                const mdPath = path.join(baseDir, spec.file_path);
-                                // Skip if content already matches (prevents oscillation)
-                                if (contentMatches(mdPath, spec.id, "spec")) {
+                        else {
+                            onLog(`[watch] No entity changes detected in ${basename}`);
+                        }
+                        // Optionally sync database changes back to markdown files
+                        // Only sync entities where content actually differs (contentMatches check)
+                        if (enableReverseSync) {
+                            onLog(`[watch] Checking for entities that need markdown updates...`);
+                            let syncedCount = 0;
+                            // Get all specs and sync to markdown
+                            const specs = listSpecs(db);
+                            for (const spec of specs) {
+                                if (spec.file_path) {
+                                    const mdPath = path.join(baseDir, spec.file_path);
+                                    // Skip if content already matches (prevents oscillation)
+                                    if (contentMatches(mdPath, spec.id, "spec")) {
+                                        continue;
+                                    }
+                                    const result = await syncJSONLToMarkdown(db, spec.id, "spec", mdPath);
+                                    if (result.success) {
+                                        syncedCount++;
+                                        onLog(`[watch] Synced spec ${spec.id} to ${spec.file_path} (${result.action})`);
+                                    }
+                                    else if (result.error) {
+                                        onError(new Error(`Failed to sync spec ${spec.id}: ${result.error}`));
+                                    }
+                                }
+                            }
+                            // Get all issues and check if any need syncing
+                            const issues = listIssues(db);
+                            const issuesDir = path.join(baseDir, "issues");
+                            for (const issue of issues) {
+                                // Find existing file or generate new filename using unified scheme
+                                let mdPath = findExistingEntityFile(issue.id, issuesDir, issue.title);
+                                if (!mdPath) {
+                                    // File doesn't exist, generate new filename
+                                    const fileName = generateUniqueFilename(issue.title, issue.id);
+                                    mdPath = path.join(issuesDir, fileName);
+                                }
+                                // Skip if content already matches (prevents unnecessary writes and oscillation)
+                                if (contentMatches(mdPath, issue.id, "issue")) {
                                     continue;
                                 }
-                                const result = await syncJSONLToMarkdown(db, spec.id, "spec", mdPath);
+                                const result = await syncJSONLToMarkdown(db, issue.id, "issue", mdPath);
                                 if (result.success) {
                                     syncedCount++;
-                                    onLog(`[watch] Synced spec ${spec.id} to ${spec.file_path} (${result.action})`);
+                                    onLog(`[watch] Synced issue ${issue.id} to markdown (${result.action})`);
                                 }
                                 else if (result.error) {
-                                    onError(new Error(`Failed to sync spec ${spec.id}: ${result.error}`));
+                                    onError(new Error(`Failed to sync issue ${issue.id}: ${result.error}`));
                                 }
                             }
-                        }
-                        // Get all issues and check if any need syncing
-                        const issues = listIssues(db);
-                        const issuesDir = path.join(baseDir, "issues");
-                        for (const issue of issues) {
-                            const fileName = `${issue.id}.md`;
-                            const mdPath = path.join(issuesDir, fileName);
-                            // Skip if content already matches (prevents unnecessary writes and oscillation)
-                            if (contentMatches(mdPath, issue.id, "issue")) {
-                                continue;
-                            }
-                            const result = await syncJSONLToMarkdown(db, issue.id, "issue", mdPath);
-                            if (result.success) {
-                                syncedCount++;
-                                onLog(`[watch] Synced issue ${issue.id} to markdown (${result.action})`);
+                            if (syncedCount > 0) {
+                                onLog(`[watch] Synced ${syncedCount} entities to markdown`);
                             }
-                            else if (result.error) {
-                                onError(new Error(`Failed to sync issue ${issue.id}: ${result.error}`));
+                            else {
+                                onLog(`[watch] All markdown files are up to date`);
                             }
                         }
-                        if (syncedCount > 0) {
-                            onLog(`[watch] Synced ${syncedCount} entities to markdown`);
-                        }
-                        else {
-                            onLog(`[watch] All markdown files are up to date`);
-                        }
                     }
                 }
+                stats.changesProcessed++;
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                onError(new Error(`Error processing ${filePath}: ${message}`));
+                stats.errors++;
             }
-            stats.changesProcessed++;
         }
-        catch (error) {
-            const message = error instanceof Error ? error.message : String(error);
-            onError(new Error(`Error processing ${filePath}: ${message}`));
-            stats.errors++;
+        finally {
+            // Always clear re-entry guard for this file, even on errors
+            filesBeingProcessed.delete(filePath);
         }
     }
     /**
-     * Debounced file change handler
+     * File change handler with oscillation guards
+     * Processes changes immediately (no debounce)
      */
     function handleFileChange(filePath, event) {
-        // Cancel pending change for this file
-        const existingTimeout = pendingChanges.get(filePath);
-        if (existingTimeout) {
-            clearTimeout(existingTimeout);
-            stats.changesPending--;
+        // Guard: Skip if we're currently processing this specific file (prevents oscillation)
+        // This is the primary defense against the oscillation loop
+        if (filesBeingProcessed.has(filePath)) {
+            return;
         }
-        // Schedule new change
-        stats.changesPending++;
-        const timeout = setTimeout(() => {
-            pendingChanges.delete(filePath);
-            stats.changesPending--;
-            processChange(filePath, event);
-        }, debounceDelay);
-        pendingChanges.set(filePath, timeout);
+        // Process change immediately
+        processChange(filePath, event);
     }
     // Set up event handlers
     watcher.on("add", (filePath) => handleFileChange(filePath, "add"));
@@ -386,6 +551,43 @@ export function startWatcher(options) {
         const watched = watcher.getWatched();
         stats.filesWatched = Object.keys(watched).reduce((total, dir) => total + watched[dir].length, 0);
         onLog(`[watch] Watching ${stats.filesWatched} files in ${baseDir}`);
+        // Initialize JSONL state cache on startup to avoid broadcasting all entities on first change
+        try {
+            // Initialize specs.jsonl cache
+            const specsJsonlPath = path.join(baseDir, "specs.jsonl");
+            if (fs.existsSync(specsJsonlPath)) {
+                const content = fs.readFileSync(specsJsonlPath, "utf8");
+                const lines = content.trim().split("\n").filter((line) => line.trim());
+                const stateMap = new Map();
+                for (const line of lines) {
+                    const entity = JSON.parse(line);
+                    // Use canonical content hash to match the change detection logic
+                    const contentHash = computeCanonicalHash(entity);
+                    stateMap.set(entity.id, contentHash);
+                }
+                jsonlStateCache.set(specsJsonlPath, stateMap);
+                onLog(`[watch] Initialized cache for specs.jsonl (${stateMap.size} entities)`);
+            }
+            // Initialize issues.jsonl cache
+            const issuesJsonlPath = path.join(baseDir, "issues.jsonl");
+            if (fs.existsSync(issuesJsonlPath)) {
+                const content = fs.readFileSync(issuesJsonlPath, "utf8");
+                const lines = content.trim().split("\n").filter((line) => line.trim());
+                const stateMap = new Map();
+                for (const line of lines) {
+                    const entity = JSON.parse(line);
+                    // Use canonical content hash to match the change detection logic
+                    const contentHash = computeCanonicalHash(entity);
+                    stateMap.set(entity.id, contentHash);
+                }
+                jsonlStateCache.set(issuesJsonlPath, stateMap);
+                onLog(`[watch] Initialized cache for issues.jsonl (${stateMap.size} entities)`);
+            }
+        }
+        catch (error) {
+            onLog(`[watch] Warning: Failed to initialize JSONL cache: ${error instanceof Error ? error.message : String(error)}`);
+            // Continue anyway - cache will be populated on first change
+        }
     });
     watcher.on("error", (error) => {
         onError(error);
@@ -395,12 +597,6 @@ export function startWatcher(options) {
     return {
         stop: async () => {
             onLog("[watch] Stopping watcher...");
-            // Cancel all pending changes
-            for (const timeout of pendingChanges.values()) {
-                clearTimeout(timeout);
-            }
-            pendingChanges.clear();
-            stats.changesPending = 0;
             // Close watcher
             await watcher.close();
             onLog("[watch] Watcher stopped");