backlog-mcp 0.2.1 → 0.6.5

package/README.md

@@ -4,29 +4,59 @@ Minimal task backlog MCP server for Claude and AI agents.
 
 > **Quick start**: Tell your LLM: `Add backlog-mcp to .mcp.json and use it to track tasks`
 
+## Web Viewer
+
+Start the server and open `http://localhost:3030` for a visual task browser.
+
+```bash
+npm run dev  # Starts MCP server + web viewer with hot reload
+```
+
+Features:
+- Split pane layout with task list and detail view
+- Filter by Active/Completed/All
+- GitHub-style markdown rendering
+- Click file path to open in editor
+- URL state persistence
+
 ## Task Schema
 
-```typescript
-{
-  id: string;           // TASK-0001
-  title: string;
-  description?: string;
-  status: 'open' | 'in_progress' | 'blocked' | 'done' | 'cancelled';
-  created_at: string;   // ISO8601
-  updated_at: string;   // ISO8601
-  blocked_reason?: string;
-  evidence?: string[];
-}
+Tasks are stored as individual markdown files with YAML frontmatter:
+
+```markdown
+---
+id: TASK-0001
+title: Fix bug in authentication
+status: open
+created_at: '2024-01-10T10:00:00Z'
+updated_at: '2024-01-10T10:00:00Z'
+blocked_reason: Waiting for API access
+evidence:
+  - Fixed in CR-12345
+  - Validated in beta
+---
+
+## Description
+
+The authentication flow has an issue where...
+
+## Context
+
+This came from Slack thread: https://...
 ```
 
+**Status values:** `open`, `in_progress`, `blocked`, `done`, `cancelled`
+
 ## MCP Tool
 
 Single unified tool with action parameter:
 
 ```
-backlog action="list"                         # List all tasks
+backlog action="list"                         # List all active tasks
 backlog action="list" summary=true            # Get counts by status
 backlog action="list" status=["open"]         # Filter by status
+backlog action="list" status=["done"]         # Show completed tasks (last 10)
+backlog action="list" status=["done"] archived_limit=20  # Show last 20 completed
 backlog action="get" id="TASK-0001"           # Get task details
 backlog action="create" title="Fix bug"       # Create task
 backlog action="update" id="TASK-0001" set_status="done"  # Update task
@@ -58,10 +88,9 @@ npm start
 
 ## Storage
 
-- Default: `data/backlog.json` (local to project)
+- Default: `data/tasks/` and `data/archive/` (local to project)
 - Global: Set `BACKLOG_DATA_DIR=~/.backlog` for cross-project persistence
-- Completed/cancelled tasks auto-archive to `archive.json`
-- Atomic writes via temp + rename
+- Completed/cancelled tasks auto-archive to `archive/`
 
 ## License
 

package/dist/index.d.ts

@@ -1,2 +1,3 @@
 export { isValidTaskId, parseTaskId, formatTaskId, nextTaskId, STATUSES, type Status, type Task, type CreateTaskInput, createTask, } from './schema.js';
-export { type Backlog, type StorageOptions, loadBacklog, saveBacklog, getTask, listTasks, addTask, saveTask, deleteTask, taskExists, getTaskCounts, } from './storage.js';
+export { type Backlog, type StorageOptions, loadBacklog, saveBacklog, getTask, listTasks, addTask, saveTask, deleteTask, taskExists, getTaskCounts, getTaskMarkdown, } from './storage.js';
+export { startViewer } from './viewer.js';

package/dist/index.js

@@ -1,5 +1,7 @@
 // Schema
 export { isValidTaskId, parseTaskId, formatTaskId, nextTaskId, STATUSES, createTask, } from './schema.js';
 // Storage
-export { loadBacklog, saveBacklog, getTask, listTasks, addTask, saveTask, deleteTask, taskExists, getTaskCounts, } from './storage.js';
+export { loadBacklog, saveBacklog, getTask, listTasks, addTask, saveTask, deleteTask, taskExists, getTaskCounts, getTaskMarkdown, } from './storage.js';
+// Viewer
+export { startViewer } from './viewer.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,SAAS;AACT,OAAO,EACL,aAAa,EACb,WAAW,EACX,YAAY,EACZ,UAAU,EACV,QAAQ,EAIR,UAAU,GACX,MAAM,aAAa,CAAC;AAErB,UAAU;AACV,OAAO,EAGL,WAAW,EACX,WAAW,EACX,OAAO,EACP,SAAS,EACT,OAAO,EACP,QAAQ,EACR,UAAU,EACV,UAAU,EACV,aAAa,GACd,MAAM,cAAc,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,SAAS;AACT,OAAO,EACL,aAAa,EACb,WAAW,EACX,YAAY,EACZ,UAAU,EACV,QAAQ,EAIR,UAAU,GACX,MAAM,aAAa,CAAC;AAErB,UAAU;AACV,OAAO,EAGL,WAAW,EACX,WAAW,EACX,OAAO,EACP,SAAS,EACT,OAAO,EACP,QAAQ,EACR,UAAU,EACV,UAAU,EACV,aAAa,EACb,eAAe,GAChB,MAAM,cAAc,CAAC;AAEtB,SAAS;AACT,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC"}

package/dist/server.js

@@ -4,7 +4,8 @@ import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
 import { z } from 'zod';
 import { createTask, STATUSES } from './schema.js';
 import { countTasks } from './summary.js';
-import { loadBacklog, getTask, listTasks, addTask, saveTask, getTaskCounts } from './storage.js';
+import { loadBacklog, getTask, getTaskMarkdown, listTasks, addTask, saveTask, getTaskCounts } from './storage.js';
+import { startViewer } from './viewer.js';
 // ============================================================================
 // Server
 // ============================================================================
@@ -24,8 +25,9 @@ server.registerTool('backlog', {
     inputSchema: {
         action: z.enum(ACTIONS).describe('Action to perform'),
         // list options
-        status: z.array(z.enum(STATUSES)).optional().describe('Filter by status (list)'),
+        status: z.array(z.enum(STATUSES)).optional().describe('Filter by status (list). Include "done" or "cancelled" to see archived tasks'),
         summary: z.boolean().optional().describe('Return counts instead of list (list)'),
+        archived_limit: z.number().optional().describe('Max archived tasks when status includes done/cancelled (list). Default: 10'),
         // get/update options
         id: z.string().optional().describe('Task ID (get, update)'),
         // create/update options
@@ -36,10 +38,11 @@ server.registerTool('backlog', {
         blocked_reason: z.string().optional().describe('Reason for blocked status (update)'),
         evidence: z.array(z.string()).optional().describe('Evidence of completion (update)'),
     },
-}, async ({ action, status, summary, id, title, description, set_status, blocked_reason, evidence }) => {
+}, async ({ action, status, summary, archived_limit, id, title, description, set_status, blocked_reason, evidence }) => {
     switch (action) {
         case 'list': {
-            const tasks = listTasks(status ? { status } : undefined, storageOptions);
+            const filter = status || archived_limit ? { status, archivedLimit: archived_limit } : undefined;
+            const tasks = listTasks(filter, storageOptions);
             if (summary) {
                 const counts = status ? countTasks(tasks) : getTaskCounts(storageOptions);
                 return { content: [{ type: 'text', text: JSON.stringify(counts, null, 2) }] };
@@ -51,11 +54,11 @@ server.registerTool('backlog', {
             if (!id) {
                 return { content: [{ type: 'text', text: 'Missing required: id' }], isError: true };
             }
-            const task = getTask(id, storageOptions);
-            if (!task) {
+            const markdown = getTaskMarkdown(id, storageOptions);
+            if (!markdown) {
                 return { content: [{ type: 'text', text: `Not found: ${id}` }], isError: true };
             }
-            return { content: [{ type: 'text', text: JSON.stringify(task, null, 2) }] };
+            return { content: [{ type: 'text', text: markdown }] };
         }
         case 'create': {
             if (!title) {
@@ -89,6 +92,10 @@ server.registerTool('backlog', {
 // Main
 // ============================================================================
 async function main() {
+    // Start HTTP viewer in background
+    const dataDir = storageOptions.dataDir ?? 'data';
+    const viewerPort = parseInt(process.env.BACKLOG_VIEWER_PORT || '3030');
+    startViewer(dataDir, viewerPort);
     const transport = new StdioServerTransport();
     await server.connect(transport);
 }

package/dist/server.js.map

@@ -1 +1 @@
-{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"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"}

package/dist/storage.d.ts

@@ -7,29 +7,32 @@ export interface StorageOptions {
     dataDir?: string;
 }
 /**
- * Load backlog from disk. Returns empty backlog if file doesn't exist.
+ * Load backlog from disk. Returns empty backlog if directory doesn't exist.
  */
 export declare function loadBacklog(options?: StorageOptions): Backlog;
 /**
- * Save backlog to disk atomically (write to temp, then rename).
+ * Save backlog to disk (no-op for file-based storage, kept for compatibility).
  */
 export declare function saveBacklog(backlog: Backlog, options?: StorageOptions): void;
 /**
- * Load archive from disk. Returns empty backlog if file doesn't exist.
+ * Load archive from disk. Returns empty backlog if directory doesn't exist.
  */
 export declare function loadArchive(options?: StorageOptions): Backlog;
 /**
  * Get a task by ID. Returns undefined if not found.
+ * Searches both active and archived tasks.
  */
 export declare function getTask(id: string, options?: StorageOptions): Task | undefined;
 /**
  * List all tasks. Optionally filter by status.
+ * If status includes 'done' or 'cancelled', includes archived tasks (limited to most recent).
  */
 export declare function listTasks(filter?: {
     status?: Task['status'][];
+    archivedLimit?: number;
 }, options?: StorageOptions): Task[];
 /**
- * Add a new task. Throws if task with same ID already exists.
+ * Add a new task. Throws if task with same ID already exists in active or archive.
  */
 export declare function addTask(task: Task, options?: StorageOptions): void;
 /**
@@ -49,3 +52,7 @@ export declare function taskExists(id: string, options?: StorageOptions): boolea
  * Get count of tasks by status.
  */
 export declare function getTaskCounts(options?: StorageOptions): Record<Task['status'], number>;
+/**
+ * Get raw markdown content for a task by ID.
+ */
+export declare function getTaskMarkdown(id: string, options?: StorageOptions): string | null;

package/dist/storage.js

@@ -1,150 +1,221 @@
-import { readFileSync, writeFileSync, mkdirSync, existsSync, renameSync } from 'node:fs';
+import { readFileSync, writeFileSync, mkdirSync, existsSync, readdirSync, unlinkSync } from 'node:fs';
 import { join } from 'node:path';
-import { randomUUID } from 'node:crypto';
+import matter from 'gray-matter';
+import { STATUSES } from './schema.js';
 // ============================================================================
 // Storage
 // ============================================================================
 const DEFAULT_DATA_DIR = 'data';
-const BACKLOG_FILE = 'backlog.json';
-const ARCHIVE_FILE = 'archive.json';
+const TASKS_DIR = 'tasks';
+const ARCHIVE_DIR = 'archive';
 const TERMINAL_STATUSES = ['done', 'cancelled'];
 function ensureDir(dir) {
     if (!existsSync(dir)) {
         mkdirSync(dir, { recursive: true });
     }
 }
-function getBacklogPath(dataDir) {
-    return join(dataDir, BACKLOG_FILE);
+function getTasksPath(dataDir) {
+    return join(dataDir, TASKS_DIR);
 }
 function getArchivePath(dataDir) {
-    return join(dataDir, ARCHIVE_FILE);
+    return join(dataDir, ARCHIVE_DIR);
 }
-function emptyBacklog() {
+function getTaskFilePath(dataDir, taskId, archived = false) {
+    const dir = archived ? getArchivePath(dataDir) : getTasksPath(dataDir);
+    return join(dir, `${taskId}.md`);
+}
+function taskToMarkdown(task) {
+    const { description, ...frontmatter } = task;
+    return matter.stringify(description || '', frontmatter);
+}
+function markdownToTask(content) {
+    const { data, content: description } = matter(content);
+    // Validate required fields
+    if (!data.id || typeof data.id !== 'string') {
+        throw new Error('Invalid task: missing or invalid id');
+    }
+    if (!data.title || typeof data.title !== 'string') {
+        throw new Error('Invalid task: missing or invalid title');
+    }
+    if (!data.status || typeof data.status !== 'string') {
+        throw new Error('Invalid task: missing or invalid status');
+    }
+    if (!STATUSES.includes(data.status)) {
+        throw new Error(`Invalid task: status must be one of ${STATUSES.join(', ')}`);
+    }
+    if (!data.created_at || typeof data.created_at !== 'string') {
+        throw new Error('Invalid task: missing or invalid created_at');
+    }
+    if (!data.updated_at || typeof data.updated_at !== 'string') {
+        throw new Error('Invalid task: missing or invalid updated_at');
+    }
+    // Validate optional fields
+    if (data.blocked_reason !== undefined && typeof data.blocked_reason !== 'string') {
+        throw new Error('Invalid task: blocked_reason must be a string');
+    }
+    if (data.evidence !== undefined && !Array.isArray(data.evidence)) {
+        throw new Error('Invalid task: evidence must be an array');
+    }
     return {
-        version: '1',
-        tasks: [],
+        ...data,
+        description: description.trim() || undefined,
     };
 }
+function readTaskFile(filePath) {
+    if (!existsSync(filePath)) {
+        return null;
+    }
+    try {
+        const content = readFileSync(filePath, 'utf-8');
+        return markdownToTask(content);
+    }
+    catch (error) {
+        console.error(`Failed to read task file ${filePath}:`, error instanceof Error ? error.message : error);
+        return null;
+    }
+}
+function writeTaskFile(filePath, task) {
+    const content = taskToMarkdown(task);
+    writeFileSync(filePath, content, 'utf-8');
+}
+function listTaskFiles(dir) {
+    if (!existsSync(dir)) {
+        return [];
+    }
+    return readdirSync(dir)
+        .filter(f => f.endsWith('.md'))
+        .map(f => join(dir, f));
+}
 /**
- * Load backlog from disk. Returns empty backlog if file doesn't exist.
+ * Read raw markdown content from task file.
  */
-export function loadBacklog(options = {}) {
-    const dataDir = options.dataDir ?? DEFAULT_DATA_DIR;
-    const path = getBacklogPath(dataDir);
-    if (!existsSync(path)) {
-        return emptyBacklog();
+function readTaskMarkdown(dataDir, taskId) {
+    const activePath = getTaskFilePath(dataDir, taskId, false);
+    if (existsSync(activePath)) {
+        return readFileSync(activePath, 'utf-8');
     }
-    const content = readFileSync(path, 'utf-8');
-    const data = JSON.parse(content);
-    // Basic version check
-    if (data.version !== '1') {
-        throw new Error(`Unsupported backlog version: ${data.version}`);
+    const archivePath = getTaskFilePath(dataDir, taskId, true);
+    if (existsSync(archivePath)) {
+        return readFileSync(archivePath, 'utf-8');
     }
-    return data;
+    return null;
 }
 /**
- * Save backlog to disk atomically (write to temp, then rename).
+ * Load backlog from disk. Returns empty backlog if directory doesn't exist.
  */
-export function saveBacklog(backlog, options = {}) {
+export function loadBacklog(options = {}) {
     const dataDir = options.dataDir ?? DEFAULT_DATA_DIR;
-    ensureDir(dataDir);
-    const path = getBacklogPath(dataDir);
-    const tempPath = join(dataDir, `.backlog.${randomUUID()}.tmp`);
-    const content = JSON.stringify(backlog, null, 2);
-    // Write to temp file first
-    writeFileSync(tempPath, content, 'utf-8');
-    // Atomic rename
-    renameSync(tempPath, path);
+    const tasksDir = getTasksPath(dataDir);
+    const taskFiles = listTaskFiles(tasksDir);
+    const tasks = taskFiles
+        .map(f => readTaskFile(f))
+        .filter((t) => t !== null);
+    return {
+        version: '1',
+        tasks,
+    };
 }
 /**
- * Load archive from disk. Returns empty backlog if file doesn't exist.
+ * Save backlog to disk (no-op for file-based storage, kept for compatibility).
  */
-export function loadArchive(options = {}) {
-    const dataDir = options.dataDir ?? DEFAULT_DATA_DIR;
-    const path = getArchivePath(dataDir);
-    if (!existsSync(path)) {
-        return emptyBacklog();
-    }
-    const content = readFileSync(path, 'utf-8');
-    const data = JSON.parse(content);
-    if (data.version !== '1') {
-        throw new Error(`Unsupported archive version: ${data.version}`);
-    }
-    return data;
+export function saveBacklog(backlog, options = {}) {
+    // No-op: tasks are saved individually
 }
 /**
- * Save archive to disk atomically.
+ * Load archive from disk. Returns empty backlog if directory doesn't exist.
  */
-function saveArchive(archive, options = {}) {
+export function loadArchive(options = {}) {
     const dataDir = options.dataDir ?? DEFAULT_DATA_DIR;
-    ensureDir(dataDir);
-    const path = getArchivePath(dataDir);
-    const tempPath = join(dataDir, `.archive.${randomUUID()}.tmp`);
-    const content = JSON.stringify(archive, null, 2);
-    writeFileSync(tempPath, content, 'utf-8');
-    renameSync(tempPath, path);
+    const archiveDir = getArchivePath(dataDir);
+    const taskFiles = listTaskFiles(archiveDir);
+    const tasks = taskFiles
+        .map(f => readTaskFile(f))
+        .filter((t) => t !== null);
+    return {
+        version: '1',
+        tasks,
+    };
 }
 /**
  * Move a task from backlog to archive.
  */
 function archiveTask(task, options = {}) {
-    const backlog = loadBacklog(options);
-    const archive = loadArchive(options);
-    // Remove from backlog
-    const index = backlog.tasks.findIndex((t) => t.id === task.id);
-    if (index !== -1) {
-        backlog.tasks.splice(index, 1);
-    }
-    // Add to archive (replace if exists)
-    const archiveIndex = archive.tasks.findIndex((t) => t.id === task.id);
-    if (archiveIndex !== -1) {
-        archive.tasks[archiveIndex] = task;
-    }
-    else {
-        archive.tasks.push(task);
+    const dataDir = options.dataDir ?? DEFAULT_DATA_DIR;
+    ensureDir(getTasksPath(dataDir));
+    ensureDir(getArchivePath(dataDir));
+    const activePath = getTaskFilePath(dataDir, task.id, false);
+    const archivePath = getTaskFilePath(dataDir, task.id, true);
+    // Remove from active if exists
+    if (existsSync(activePath)) {
+        unlinkSync(activePath);
     }
-    saveBacklog(backlog, options);
-    saveArchive(archive, options);
+    // Write to archive
+    writeTaskFile(archivePath, task);
 }
 // ============================================================================
 // Task Operations
 // ============================================================================
 /**
  * Get a task by ID. Returns undefined if not found.
+ * Searches both active and archived tasks.
  */
 export function getTask(id, options = {}) {
-    const backlog = loadBacklog(options);
-    return backlog.tasks.find((t) => t.id === id);
+    const dataDir = options.dataDir ?? DEFAULT_DATA_DIR;
+    // Try active first
+    const activePath = getTaskFilePath(dataDir, id, false);
+    const activeTask = readTaskFile(activePath);
+    if (activeTask)
+        return activeTask;
+    // Try archive
+    const archivePath = getTaskFilePath(dataDir, id, true);
+    return readTaskFile(archivePath) ?? undefined;
 }
 /**
  * List all tasks. Optionally filter by status.
+ * If status includes 'done' or 'cancelled', includes archived tasks (limited to most recent).
  */
 export function listTasks(filter, options = {}) {
     const backlog = loadBacklog(options);
+    let tasks = [...backlog.tasks];
+    // Check if we need archived tasks (when filtering for done/cancelled)
+    const needsArchive = filter?.status?.some(s => s === 'done' || s === 'cancelled');
+    if (needsArchive) {
+        const archive = loadArchive(options);
+        // Sort archived by updated_at descending (most recent first)
+        const sortedArchive = [...archive.tasks].sort((a, b) => new Date(b.updated_at).getTime() - new Date(a.updated_at).getTime());
+        // Apply limit to archived tasks (default 10)
+        const archiveLimit = filter?.archivedLimit ?? 10;
+        const limitedArchive = sortedArchive.slice(0, archiveLimit);
+        tasks = [...tasks, ...limitedArchive];
+    }
+    // Filter by status if specified
     if (filter?.status && filter.status.length > 0) {
-        return backlog.tasks.filter((t) => filter.status.includes(t.status));
+        tasks = tasks.filter((t) => filter.status.includes(t.status));
     }
-    return backlog.tasks;
+    return tasks;
 }
 /**
- * Add a new task. Throws if task with same ID already exists.
+ * Add a new task. Throws if task with same ID already exists in active or archive.
  */
 export function addTask(task, options = {}) {
-    const backlog = loadBacklog(options);
-    if (backlog.tasks.some((t) => t.id === task.id)) {
+    const dataDir = options.dataDir ?? DEFAULT_DATA_DIR;
+    ensureDir(getTasksPath(dataDir));
+    const activePath = getTaskFilePath(dataDir, task.id, false);
+    const archivePath = getTaskFilePath(dataDir, task.id, true);
+    if (existsSync(activePath) || existsSync(archivePath)) {
         throw new Error(`Task with ID '${task.id}' already exists`);
     }
-    backlog.tasks.push(task);
-    saveBacklog(backlog, options);
+    writeTaskFile(activePath, task);
 }
 /**
  * Update an existing task. Throws if task doesn't exist.
  * Automatically archives tasks with terminal status (done, cancelled).
  */
 export function saveTask(task, options = {}) {
-    const backlog = loadBacklog(options);
-    const index = backlog.tasks.findIndex((t) => t.id === task.id);
-    if (index === -1) {
+    const dataDir = options.dataDir ?? DEFAULT_DATA_DIR;
+    const activePath = getTaskFilePath(dataDir, task.id, false);
+    const archivePath = getTaskFilePath(dataDir, task.id, true);
+    if (!existsSync(activePath) && !existsSync(archivePath)) {
         throw new Error(`Task with ID '${task.id}' not found`);
     }
     // Archive if terminal status
@@ -152,27 +223,34 @@ export function saveTask(task, options = {}) {
         archiveTask(task, options);
         return;
     }
-    backlog.tasks[index] = task;
-    saveBacklog(backlog, options);
+    ensureDir(getTasksPath(dataDir));
+    writeTaskFile(activePath, task);
 }
 /**
  * Delete a task by ID. Throws if task doesn't exist.
  */
 export function deleteTask(id, options = {}) {
-    const backlog = loadBacklog(options);
-    const index = backlog.tasks.findIndex((t) => t.id === id);
-    if (index === -1) {
+    const dataDir = options.dataDir ?? DEFAULT_DATA_DIR;
+    const activePath = getTaskFilePath(dataDir, id, false);
+    const archivePath = getTaskFilePath(dataDir, id, true);
+    if (existsSync(activePath)) {
+        unlinkSync(activePath);
+    }
+    else if (existsSync(archivePath)) {
+        unlinkSync(archivePath);
+    }
+    else {
         throw new Error(`Task with ID '${id}' not found`);
     }
-    backlog.tasks.splice(index, 1);
-    saveBacklog(backlog, options);
 }
 /**
  * Check if a task exists.
  */
 export function taskExists(id, options = {}) {
-    const backlog = loadBacklog(options);
-    return backlog.tasks.some((t) => t.id === id);
+    const dataDir = options.dataDir ?? DEFAULT_DATA_DIR;
+    const activePath = getTaskFilePath(dataDir, id, false);
+    const archivePath = getTaskFilePath(dataDir, id, true);
+    return existsSync(activePath) || existsSync(archivePath);
 }
 /**
  * Get count of tasks by status.
@@ -191,4 +269,11 @@ export function getTaskCounts(options = {}) {
     }
     return counts;
 }
+/**
+ * Get raw markdown content for a task by ID.
+ */
+export function getTaskMarkdown(id, options = {}) {
+    const dataDir = options.dataDir ?? DEFAULT_DATA_DIR;
+    return readTaskMarkdown(dataDir, id);
+}
 //# sourceMappingURL=storage.js.map