tailormade-eu_obsidian-task-export-plugin/docs/COPILOT-PROMPT.md

Task Export Tool - Iteration 2 (Obsidian Plugin)

Create an Obsidian plugin that extracts outstanding tasks from Markdown files and exports them to a CSV file for ManicTime time tracking.

Overview

This iteration builds upon Iteration 1 (C# Console App) by integrating the task export functionality directly into Obsidian as a plugin, providing on-demand and automatic export capabilities.

Related Repository: markdown-task-export - C# Console Application (Iteration 1)

⚠️ IMPORTANT FOR IMPLEMENTATION: The C# console application is a fully working reference implementation with:

• ✅ Complete task extraction logic (MarkdownParser.cs)
• ✅ Hierarchical header parsing with unlimited depth
• ✅ CSV generation with compression support (CsvExporter.cs)
• ✅ Customer/Project name extraction (TaskExtractor.cs)
• ✅ All edge cases handled (nested tasks, special characters, escaping)

Use the C# code as a reference for implementing the TypeScript plugin. The logic should be identical, just ported to TypeScript/Obsidian API.

📋 Detailed Specifications: See docs/REQUIREMENTS.md for comprehensive technical requirements, API usage, cross-platform considerations, and project structure.

Requirements

1. Plugin Features

• Manual Export: Add a command to the command palette to export tasks on demand
• Automatic Export: Watch for file changes and automatically regenerate the CSV when markdown files are modified
• Settings Panel: Allow users to configure:
  • Output file location
  • Customers folder path
  • Enable/disable automatic export
  • Export trigger options (on save, on file change, manual only)

2. Task Detection (Same as Iteration 1)

Find all unchecked tasks marked with - [ ] (checkbox syntax in markdown)

• Ignore completed tasks marked with - [x]
• Ignore tasks with checkmarks like ✅ 2025-11-11

3. Hierarchical Structure Parsing (Same as Iteration 1)

• Extract markdown headers (##, ###, ####) as Header1, Header2, Header3
• Associate each task with its parent headers in the hierarchy
• Handle nested/indented tasks (sub-bullets under parent tasks)
• When a task has sub-tasks (indented bullets), treat the parent task text as an additional header level

4. Customer and Project Name Extraction (Same as Iteration 1)

• CustomerName = the folder name directly under Customers/ (e.g., "Belgian Recycling Network (BRN)", "I.Deeds", "Cetec")
• ProjectName = the markdown filename without extension (e.g., "Billit implementation", "Webshop")
• Handle nested customer folders (e.g., Customers/I.Deeds/Cetec/ → Customer: "I.Deeds", look in subfolder for projects)

5. CSV Output Format (Same as Iteration 1)

• Header row: CustomerName,ProjectName,Level1,Level2,Level3,...,Task
• Dynamic columns: Automatically adapts to maximum header depth
• Compression mode: Optional removal of empty hierarchy columns (--compress-levels equivalent)
• Header control: Option to include or exclude CSV header row
• Handle commas within task text by properly escaping with quotes
• Handle quotes within task text by doubling them
• UTF-8 with BOM encoding for Excel compatibility

6. Output File

Create outstanding_tasks.csv in the configurable location (default: vault root)

Plugin-Specific Features

Commands

1. Export Outstanding Tasks: Manually trigger task export
2. Toggle Auto-Export: Enable/disable automatic export on file changes

Settings

interface TaskExportSettings {
    outputPath: string;              // Path for CSV output (relative to vault)
    customersFolder: string;         // Root folder for customer files
    autoExport: boolean;             // Enable automatic export
    exportOnSave: boolean;           // Export when files are saved
    exportOnModify: boolean;         // Export when files are modified
    showNotifications: boolean;      // Show notifications on export
    compressLevels: boolean;         // Compress empty levels (like --compress-levels)
    includeHeader: boolean;          // Include CSV header row (like --no-header)
    debounceDelay: number;           // Debounce delay in seconds (1-30)
}

User Interface

• Add ribbon icon for quick export
• Show status bar item with last export time
• Display notice/notification on successful export
• Show error notifications if export fails

File Watching

• Monitor the Customers/ folder for changes
• Debounce file changes (wait 2-3 seconds after last change before exporting)
• Only trigger export for .md files
• Handle bulk operations efficiently

Technical Details

Cross-Platform Support

Platform Compatibility:

• ✅ Windows, macOS, Linux (desktop)
• ✅ Android, iOS (mobile)
• ✅ Web version
• One codebase works everywhere - Obsidian uses web technologies on all platforms

Technology Stack:

• TypeScript - Primary language
• Obsidian Plugin API - Use exclusively for file operations
• Node.js - Development only (not required by users)
• esbuild - Fast bundling

Important API Usage:

• ✅ Use this.app.vault.adapter.write() for file operations
• ✅ Use this.app.vault.adapter.read() for reading files
• ✅ Use normalizePath() for cross-platform path handling
• ❌ Avoid Node.js modules (fs, path, os) - desktop only
• ❌ Never use absolute paths outside vault on mobile

Platform Detection:

if (Platform.isMobile) {
    // Mobile: limit to vault directory
} else {
    // Desktop: allow custom paths
}

Best Practices

• Follow Obsidian plugin development best practices
• Properly handle file system operations through Obsidian's API only
• Implement proper error handling and logging
• Add progress indicators for large exports
• Test on multiple platforms before release

Plugin Structure

obsidian-task-export-plugin/
├── src/
│   ├── main.ts                 // Plugin entry point
│   ├── settings.ts             // Settings interface and tab
│   ├── exporter.ts             // Core export logic
│   ├── parser.ts               // Markdown parsing logic
│   ├── csv-writer.ts           // CSV generation
│   ├── file-watcher.ts         // File monitoring
│   └── types.ts                // TypeScript interfaces
├── manifest.json               // Plugin metadata
├── versions.json               // Version compatibility
├── package.json                // Dependencies
├── tsconfig.json               // TypeScript config
├── esbuild.config.mjs          // Build configuration
├── styles.css                  // Optional styling
├── README.md
└── LICENSE

Example User Workflows

Workflow 1: Manual Export

1. User opens command palette (Ctrl/Cmd + P)
2. Types "Export Outstanding Tasks"
3. Plugin scans Customers folder
4. CSV is generated and saved
5. Notification shows "Exported 49 tasks to outstanding_tasks.csv"

Workflow 2: Automatic Export

1. User enables auto-export in settings
2. User edits a markdown file in Customers folder
3. User saves the file
4. Plugin automatically regenerates CSV in background
5. Status bar updates to show last export time

Error Handling

• Handle missing Customers folder gracefully
• Show helpful error messages for invalid file paths
• Log errors to console for debugging
• Don't block Obsidian if export fails
• Validate CSV output before saving

Performance Considerations

• Cache parsed files to avoid re-parsing unchanged files
• Use debouncing for file change events
• Process files asynchronously to avoid blocking UI
• Consider limiting auto-export to files in Customers folder only

Future Enhancements (Iteration 3?)

• Filter tasks by date range
• Support custom task formats beyond - [ ]
• Export to multiple formats (JSON, XML, etc.)
• Integration with ManicTime API for direct import
• Task statistics dashboard in Obsidian
• Support for task priorities and tags