@backlog-md/core 0.2.1 → 0.3.0

package/dist/core/Core.js

@@ -5,8 +5,8 @@
  * by accepting adapter implementations for I/O operations.
  */
 import { parseBacklogConfig, serializeBacklogConfig } from "./config-parser";
-import { parseTaskMarkdown, extractTaskIndexFromPath } from "../markdown";
-import { sortTasks, sortTasksBy, groupTasksByStatus } from "../utils";
+import { parseTaskMarkdown, serializeTaskMarkdown, extractTaskIndexFromPath, parseMilestoneMarkdown, serializeMilestoneMarkdown, getMilestoneFilename, extractMilestoneIdFromFilename, } from "../markdown";
+import { sortTasks, sortTasksBy, groupTasksByStatus, groupTasksByMilestone, milestoneKey, } from "../utils";
 /**
  * Core class for Backlog.md operations
  *
@@ -239,23 +239,15 @@ export class Core {
             let entries = Array.from(this.taskIndex.values()).filter((e) => e.source === source);
             // Per-source limit
             const limit = source === "tasks" ? tasksLimit : completedLimit;
-            // Sort based on source type
-            if (source === "completed" && completedSortByIdDesc) {
-                // Sort completed by ID descending (higher ID = more recent)
-                entries = entries.sort((a, b) => {
-                    // Extract numeric part for comparison
-                    const aNum = parseInt(a.id.replace(/\D/g, ""), 10) || 0;
-                    const bNum = parseInt(b.id.replace(/\D/g, ""), 10) || 0;
-                    return bNum - aNum; // Descending
-                });
-            }
-            else {
-                // Sort by title
-                entries = entries.sort((a, b) => {
-                    const cmp = a.title.localeCompare(b.title);
-                    return tasksSortDirection === "asc" ? cmp : -cmp;
-                });
-            }
+            // Sort by ID (numeric)
+            entries = entries.sort((a, b) => {
+                const aNum = parseInt(a.id.replace(/\D/g, ""), 10) || 0;
+                const bNum = parseInt(b.id.replace(/\D/g, ""), 10) || 0;
+                // Completed: descending (most recent first), Active: ascending
+                return source === "completed" && completedSortByIdDesc
+                    ? bNum - aNum
+                    : aNum - bNum;
+            });
             const total = entries.length;
             const pageEntries = entries.slice(offset, offset + limit);
             // Load only the tasks for this page
@@ -290,22 +282,15 @@ export class Core {
         const completedSortByIdDesc = options?.completedSortByIdDesc ?? true;
         // Get index entries for this source
         let entries = Array.from(this.taskIndex.values()).filter((e) => e.source === source);
-        // Sort based on source type
-        if (source === "completed" && completedSortByIdDesc) {
-            // Sort completed by ID descending (higher ID = more recent)
-            entries = entries.sort((a, b) => {
-                const aNum = parseInt(a.id.replace(/\D/g, ""), 10) || 0;
-                const bNum = parseInt(b.id.replace(/\D/g, ""), 10) || 0;
-                return bNum - aNum;
-            });
-        }
-        else {
-            // Sort by title
-            entries = entries.sort((a, b) => {
-                const cmp = a.title.localeCompare(b.title);
-                return sortDirection === "asc" ? cmp : -cmp;
-            });
-        }
+        // Sort by ID (numeric)
+        entries = entries.sort((a, b) => {
+            const aNum = parseInt(a.id.replace(/\D/g, ""), 10) || 0;
+            const bNum = parseInt(b.id.replace(/\D/g, ""), 10) || 0;
+            // Completed: descending (most recent first), Active: ascending
+            return source === "completed" && completedSortByIdDesc
+                ? bNum - aNum
+                : aNum - bNum;
+        });
         const total = entries.length;
         const pageEntries = entries.slice(currentOffset, currentOffset + limit);
         // Load only the tasks for this page
@@ -345,6 +330,10 @@ export class Core {
         if (filter?.priority) {
             tasks = tasks.filter((t) => t.priority === filter.priority);
         }
+        if (filter?.milestone) {
+            const filterKey = milestoneKey(filter.milestone);
+            tasks = tasks.filter((t) => milestoneKey(t.milestone) === filterKey);
+        }
         if (filter?.labels && filter.labels.length > 0) {
             tasks = tasks.filter((t) => filter.labels.some((label) => t.labels.includes(label)));
         }
@@ -365,6 +354,231 @@ export class Core {
         const tasks = Array.from(this.tasks.values());
         return groupTasksByStatus(tasks, this.config.statuses);
     }
+    /**
+     * Get tasks grouped by milestone
+     *
+     * Returns a MilestoneSummary with:
+     * - milestones: List of milestone IDs in display order
+     * - buckets: Array of MilestoneBucket with tasks, progress, status counts
+     *
+     * The first bucket is always "Tasks without milestone".
+     * Each bucket includes progress percentage based on done status.
+     *
+     * @example
+     * ```typescript
+     * const summary = core.getTasksByMilestone();
+     * for (const bucket of summary.buckets) {
+     *   console.log(`${bucket.label}: ${bucket.progress}% complete`);
+     *   console.log(`  ${bucket.doneCount}/${bucket.total} tasks done`);
+     * }
+     * ```
+     */
+    getTasksByMilestone() {
+        this.ensureInitialized();
+        const tasks = Array.from(this.tasks.values());
+        return groupTasksByMilestone(tasks, this.config.milestones, this.config.statuses);
+    }
+    // =========================================================================
+    // Milestone CRUD Operations
+    // =========================================================================
+    /**
+     * Get the milestones directory path
+     */
+    getMilestonesDir() {
+        return this.fs.join(this.projectRoot, "backlog", "milestones");
+    }
+    /**
+     * List all milestones from the milestones directory
+     *
+     * @returns Array of Milestone objects sorted by ID
+     */
+    async listMilestones() {
+        const milestonesDir = this.getMilestonesDir();
+        // Check if directory exists
+        if (!(await this.fs.exists(milestonesDir))) {
+            return [];
+        }
+        const entries = await this.fs.readDir(milestonesDir);
+        const milestones = [];
+        for (const entry of entries) {
+            // Skip non-milestone files
+            if (!entry.endsWith(".md"))
+                continue;
+            if (entry.toLowerCase() === "readme.md")
+                continue;
+            const milestoneId = extractMilestoneIdFromFilename(entry);
+            if (!milestoneId)
+                continue;
+            const filepath = this.fs.join(milestonesDir, entry);
+            // Skip directories
+            if (await this.fs.isDirectory(filepath))
+                continue;
+            try {
+                const content = await this.fs.readFile(filepath);
+                milestones.push(parseMilestoneMarkdown(content));
+            }
+            catch (error) {
+                console.warn(`Failed to parse milestone file ${filepath}:`, error);
+            }
+        }
+        // Sort by ID for consistent ordering
+        return milestones.sort((a, b) => a.id.localeCompare(b.id, undefined, { numeric: true }));
+    }
+    /**
+     * Load a single milestone by ID
+     *
+     * @param id - Milestone ID (e.g., "m-0")
+     * @returns Milestone or null if not found
+     */
+    async loadMilestone(id) {
+        const milestonesDir = this.getMilestonesDir();
+        if (!(await this.fs.exists(milestonesDir))) {
+            return null;
+        }
+        const entries = await this.fs.readDir(milestonesDir);
+        // Find file matching the ID
+        const milestoneFile = entries.find((entry) => {
+            const fileId = extractMilestoneIdFromFilename(entry);
+            return fileId === id;
+        });
+        if (!milestoneFile) {
+            return null;
+        }
+        const filepath = this.fs.join(milestonesDir, milestoneFile);
+        try {
+            const content = await this.fs.readFile(filepath);
+            return parseMilestoneMarkdown(content);
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Create a new milestone
+     *
+     * @param input - Milestone creation input
+     * @returns Created milestone
+     */
+    async createMilestone(input) {
+        const milestonesDir = this.getMilestonesDir();
+        // Ensure milestones directory exists
+        await this.fs.createDir(milestonesDir, { recursive: true });
+        // Find next available milestone ID
+        const entries = await this.fs.readDir(milestonesDir).catch(() => []);
+        const existingIds = entries
+            .map((f) => {
+            const match = f.match(/^m-(\d+)/);
+            return match?.[1] ? parseInt(match[1], 10) : -1;
+        })
+            .filter((id) => id >= 0);
+        const nextId = existingIds.length > 0 ? Math.max(...existingIds) + 1 : 0;
+        const id = `m-${nextId}`;
+        const description = input.description || `Milestone: ${input.title}`;
+        // Create a temporary milestone to generate content
+        const tempMilestone = {
+            id,
+            title: input.title,
+            description,
+            rawContent: "",
+            tasks: [],
+        };
+        // Generate content
+        const content = serializeMilestoneMarkdown(tempMilestone);
+        // Create the final milestone with correct rawContent
+        const milestone = {
+            id,
+            title: input.title,
+            description,
+            rawContent: content,
+            tasks: [],
+        };
+        // Write file
+        const filename = getMilestoneFilename(id, input.title);
+        const filepath = this.fs.join(milestonesDir, filename);
+        await this.fs.writeFile(filepath, content);
+        return milestone;
+    }
+    /**
+     * Update an existing milestone
+     *
+     * @param id - Milestone ID to update
+     * @param input - Fields to update
+     * @returns Updated milestone or null if not found
+     */
+    async updateMilestone(id, input) {
+        const existing = await this.loadMilestone(id);
+        if (!existing) {
+            return null;
+        }
+        const milestonesDir = this.getMilestonesDir();
+        const entries = await this.fs.readDir(milestonesDir);
+        // Find the current file
+        const currentFile = entries.find((entry) => {
+            const fileId = extractMilestoneIdFromFilename(entry);
+            return fileId === id;
+        });
+        if (!currentFile) {
+            return null;
+        }
+        // Build updated values
+        const newTitle = input.title ?? existing.title;
+        const newDescription = input.description ?? existing.description;
+        // Create a temporary milestone to generate content
+        const tempMilestone = {
+            id: existing.id,
+            title: newTitle,
+            description: newDescription,
+            rawContent: "",
+            tasks: existing.tasks,
+        };
+        // Generate new content
+        const content = serializeMilestoneMarkdown(tempMilestone);
+        // Create the final updated milestone
+        const updated = {
+            id: existing.id,
+            title: newTitle,
+            description: newDescription,
+            rawContent: content,
+            tasks: existing.tasks,
+        };
+        // Delete old file
+        const oldPath = this.fs.join(milestonesDir, currentFile);
+        await this.fs.deleteFile(oldPath);
+        // Write new file (with potentially new filename if title changed)
+        const newFilename = getMilestoneFilename(id, updated.title);
+        const newPath = this.fs.join(milestonesDir, newFilename);
+        await this.fs.writeFile(newPath, content);
+        return updated;
+    }
+    /**
+     * Delete a milestone
+     *
+     * @param id - Milestone ID to delete
+     * @returns true if deleted, false if not found
+     */
+    async deleteMilestone(id) {
+        const milestonesDir = this.getMilestonesDir();
+        if (!(await this.fs.exists(milestonesDir))) {
+            return false;
+        }
+        const entries = await this.fs.readDir(milestonesDir);
+        // Find file matching the ID
+        const milestoneFile = entries.find((entry) => {
+            const fileId = extractMilestoneIdFromFilename(entry);
+            return fileId === id;
+        });
+        if (!milestoneFile) {
+            return false;
+        }
+        const filepath = this.fs.join(milestonesDir, milestoneFile);
+        try {
+            await this.fs.deleteFile(filepath);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
     /**
      * Get a single task by ID
      *
@@ -503,6 +717,10 @@ export class Core {
         if (filter.priority) {
             result = result.filter((t) => t.priority === filter.priority);
         }
+        if (filter.milestone) {
+            const filterKey = milestoneKey(filter.milestone);
+            result = result.filter((t) => milestoneKey(t.milestone) === filterKey);
+        }
         if (filter.labels && filter.labels.length > 0) {
             result = result.filter((t) => filter.labels.some((label) => t.labels.includes(label)));
         }
@@ -536,5 +754,293 @@ export class Core {
             }
         }
     }
+    // =========================================================================
+    // Milestone-Task Sync Helpers
+    // =========================================================================
+    /**
+     * Add a task ID to a milestone's tasks array
+     *
+     * @param taskId - Task ID to add
+     * @param milestoneId - Milestone ID to update
+     */
+    async addTaskToMilestone(taskId, milestoneId) {
+        const milestone = await this.loadMilestone(milestoneId);
+        if (!milestone) {
+            console.warn(`Milestone ${milestoneId} not found when adding task ${taskId}`);
+            return;
+        }
+        // Check if task already in milestone
+        if (milestone.tasks.includes(taskId)) {
+            return;
+        }
+        // Update milestone with new task
+        const updatedMilestone = {
+            ...milestone,
+            tasks: [...milestone.tasks, taskId],
+        };
+        await this.writeMilestoneFile(updatedMilestone);
+    }
+    /**
+     * Remove a task ID from a milestone's tasks array
+     *
+     * @param taskId - Task ID to remove
+     * @param milestoneId - Milestone ID to update
+     */
+    async removeTaskFromMilestone(taskId, milestoneId) {
+        const milestone = await this.loadMilestone(milestoneId);
+        if (!milestone) {
+            return;
+        }
+        // Check if task is in milestone
+        if (!milestone.tasks.includes(taskId)) {
+            return;
+        }
+        // Update milestone without the task
+        const updatedMilestone = {
+            ...milestone,
+            tasks: milestone.tasks.filter((id) => id !== taskId),
+        };
+        await this.writeMilestoneFile(updatedMilestone);
+    }
+    /**
+     * Write a milestone to disk
+     */
+    async writeMilestoneFile(milestone) {
+        const milestonesDir = this.getMilestonesDir();
+        const entries = await this.fs.readDir(milestonesDir).catch(() => []);
+        // Find and delete the current file
+        const currentFile = entries.find((entry) => {
+            const fileId = extractMilestoneIdFromFilename(entry);
+            return fileId === milestone.id;
+        });
+        if (currentFile) {
+            const oldPath = this.fs.join(milestonesDir, currentFile);
+            await this.fs.deleteFile(oldPath).catch(() => { });
+        }
+        // Write new file
+        const content = serializeMilestoneMarkdown(milestone);
+        const filename = getMilestoneFilename(milestone.id, milestone.title);
+        const filepath = this.fs.join(milestonesDir, filename);
+        await this.fs.writeFile(filepath, content);
+    }
+    /**
+     * Get the tasks directory path
+     */
+    getTasksDir() {
+        return this.fs.join(this.projectRoot, "backlog", "tasks");
+    }
+    // =========================================================================
+    // Task CRUD Operations
+    // =========================================================================
+    /**
+     * Create a new task
+     *
+     * @param input - Task creation input
+     * @returns Created task
+     */
+    async createTask(input) {
+        this.ensureInitialized();
+        const tasksDir = this.getTasksDir();
+        // Ensure tasks directory exists
+        await this.fs.createDir(tasksDir, { recursive: true });
+        // Generate next task ID
+        const existingIds = Array.from(this.tasks.keys())
+            .map((id) => parseInt(id.replace(/\D/g, ""), 10))
+            .filter((n) => !isNaN(n));
+        const nextId = existingIds.length > 0 ? Math.max(...existingIds) + 1 : 1;
+        const taskId = String(nextId);
+        // Build task object
+        const now = new Date().toISOString().split("T")[0];
+        const task = {
+            id: taskId,
+            title: input.title,
+            status: input.status || this.config.defaultStatus || "To Do",
+            priority: input.priority,
+            assignee: input.assignee || [],
+            createdDate: now,
+            labels: input.labels || [],
+            milestone: input.milestone,
+            dependencies: input.dependencies || [],
+            parentTaskId: input.parentTaskId,
+            description: input.description,
+            implementationPlan: input.implementationPlan,
+            implementationNotes: input.implementationNotes,
+            acceptanceCriteriaItems: input.acceptanceCriteria?.map((ac, i) => ({
+                index: i + 1,
+                text: ac.text,
+                checked: ac.checked || false,
+            })),
+            rawContent: input.rawContent,
+            source: "local",
+        };
+        // Serialize and write file
+        const content = serializeTaskMarkdown(task);
+        const safeTitle = input.title
+            .replace(/[<>:"/\\|?*]/g, "")
+            .replace(/\s+/g, " ")
+            .slice(0, 50);
+        const filename = `${taskId} - ${safeTitle}.md`;
+        const filepath = this.fs.join(tasksDir, filename);
+        await this.fs.writeFile(filepath, content);
+        // Update in-memory cache
+        task.filePath = filepath;
+        this.tasks.set(taskId, task);
+        // Sync milestone if specified
+        if (input.milestone) {
+            await this.addTaskToMilestone(taskId, input.milestone);
+        }
+        return task;
+    }
+    /**
+     * Update an existing task
+     *
+     * @param id - Task ID to update
+     * @param input - Fields to update
+     * @returns Updated task or null if not found
+     */
+    async updateTask(id, input) {
+        this.ensureInitialized();
+        const existing = this.tasks.get(id);
+        if (!existing) {
+            return null;
+        }
+        const oldMilestone = existing.milestone;
+        const newMilestone = input.milestone === null
+            ? undefined
+            : input.milestone !== undefined
+                ? input.milestone
+                : oldMilestone;
+        // Build updated task
+        const now = new Date().toISOString().split("T")[0];
+        const updated = {
+            ...existing,
+            title: input.title ?? existing.title,
+            status: input.status ?? existing.status,
+            priority: input.priority ?? existing.priority,
+            milestone: newMilestone,
+            updatedDate: now,
+            description: input.description ?? existing.description,
+            implementationPlan: input.clearImplementationPlan
+                ? undefined
+                : input.implementationPlan ?? existing.implementationPlan,
+            implementationNotes: input.clearImplementationNotes
+                ? undefined
+                : input.implementationNotes ?? existing.implementationNotes,
+            ordinal: input.ordinal ?? existing.ordinal,
+            dependencies: input.dependencies ?? existing.dependencies,
+        };
+        // Handle label operations
+        if (input.labels) {
+            updated.labels = input.labels;
+        }
+        else {
+            if (input.addLabels) {
+                updated.labels = [...new Set([...updated.labels, ...input.addLabels])];
+            }
+            if (input.removeLabels) {
+                updated.labels = updated.labels.filter((l) => !input.removeLabels.includes(l));
+            }
+        }
+        // Handle assignee
+        if (input.assignee) {
+            updated.assignee = input.assignee;
+        }
+        // Handle dependency operations
+        if (input.addDependencies) {
+            updated.dependencies = [
+                ...new Set([...updated.dependencies, ...input.addDependencies]),
+            ];
+        }
+        if (input.removeDependencies) {
+            updated.dependencies = updated.dependencies.filter((d) => !input.removeDependencies.includes(d));
+        }
+        // Handle acceptance criteria
+        if (input.acceptanceCriteria) {
+            updated.acceptanceCriteriaItems = input.acceptanceCriteria.map((ac, i) => ({
+                index: i + 1,
+                text: ac.text,
+                checked: ac.checked || false,
+            }));
+        }
+        // Serialize and write file
+        const content = serializeTaskMarkdown(updated);
+        // Delete old file if exists
+        if (existing.filePath) {
+            await this.fs.deleteFile(existing.filePath).catch(() => { });
+        }
+        // Write new file
+        const tasksDir = this.getTasksDir();
+        const safeTitle = updated.title
+            .replace(/[<>:"/\\|?*]/g, "")
+            .replace(/\s+/g, " ")
+            .slice(0, 50);
+        const filename = `${id} - ${safeTitle}.md`;
+        const filepath = this.fs.join(tasksDir, filename);
+        await this.fs.writeFile(filepath, content);
+        // Update in-memory cache
+        updated.filePath = filepath;
+        this.tasks.set(id, updated);
+        // Handle milestone sync
+        const milestoneChanged = milestoneKey(oldMilestone) !== milestoneKey(newMilestone);
+        if (milestoneChanged) {
+            // Remove from old milestone
+            if (oldMilestone) {
+                await this.removeTaskFromMilestone(id, oldMilestone);
+            }
+            // Add to new milestone
+            if (newMilestone) {
+                await this.addTaskToMilestone(id, newMilestone);
+            }
+        }
+        return updated;
+    }
+    /**
+     * Delete a task
+     *
+     * @param id - Task ID to delete
+     * @returns true if deleted, false if not found
+     */
+    async deleteTask(id) {
+        this.ensureInitialized();
+        const task = this.tasks.get(id);
+        if (!task) {
+            return false;
+        }
+        // Remove from milestone if assigned
+        if (task.milestone) {
+            await this.removeTaskFromMilestone(id, task.milestone);
+        }
+        // Delete file
+        if (task.filePath) {
+            try {
+                await this.fs.deleteFile(task.filePath);
+            }
+            catch {
+                // File may already be deleted
+            }
+        }
+        // Remove from in-memory cache
+        this.tasks.delete(id);
+        return true;
+    }
+    /**
+     * Load specific tasks by their IDs (for lazy loading milestone tasks)
+     *
+     * @param ids - Array of task IDs to load
+     * @returns Array of loaded tasks (missing tasks excluded)
+     */
+    async loadTasksByIds(ids) {
+        // If fully initialized, return from cache
+        if (this.initialized) {
+            return ids
+                .map((id) => this.tasks.get(id))
+                .filter((t) => t !== undefined);
+        }
+        // If lazy initialized, load on demand
+        if (this.lazyInitialized) {
+            return this.loadTasks(ids);
+        }
+        throw new Error("Core not initialized. Call initialize() or initializeLazy() first.");
+    }
 }
 //# sourceMappingURL=Core.js.map