v0.7.0 - Enhanced User Experience & Visibility

🎯 Major Features: Configuration Verification & Enhanced Pull Visibility

This release significantly improves the user experience by adding essential verification tools and making sync operations more transparent. Users can now easily verify their setup is ready and see exactly what's happening during pull operations.

✅ New Verify Command

Check if your setup is ready to sync:

notion-md-sync verify

Example output when properly configured:

✅ Configuration Status: READY
   Parent Page ID: 123e4567-e89b-12d3-a456-426614174000
   Markdown Root: ./docs
   Sync Direction: bidirectional
   Conflict Resolution: diff

Example output when configuration has issues:

❌ Configuration Status: INCOMPLETE
   - Missing Notion API token
   - Missing parent page ID

Please create a configuration file to use notion-md-sync.
See config.example.yaml for reference.

🔍 What Verify Checks

• Configuration File: Validates config.yaml exists and is properly formatted
• Required Settings: Ensures all essential fields are present
• API Token: Verifies Notion integration token is configured
• Parent Page ID: Confirms target Notion page is specified
• Directory Settings: Validates markdown root directory configuration
• Sync Settings: Shows current sync direction and conflict resolution strategy

📊 Enhanced Status Command with Parent Page Context

See file status with Notion context:

notion-md-sync status

Example output:

On parent page: My Project Documentation

Changes not staged for sync:
  (use "notion-md-sync add <file>..." to stage changes)

        modified: docs/api-guide.md
        modified: docs/user-manual.md
        deleted:  docs/old-notes.md

Changes staged for sync:
  (use "notion-md-sync reset <file>..." to unstage)

        staged:   docs/overview.md
        staged:   docs/quickstart.md

Use "notion-md-sync push" to sync staged changes to Notion.

🏷️ New Status Features

• Parent Page Title: Shows the actual title of your Notion parent page (not just "On branch main")
• Real-time Fetching: Dynamically retrieves page title from Notion API
• Fallback Handling: Gracefully handles cases where page can't be fetched
• Context Awareness: Provides immediate context about which Notion workspace you're syncing with

📈 Dramatically Improved Pull Command Visibility

Enhanced pull operations with detailed progress:

notion-md-sync pull --verbose

Example output for pulling all pages:

Pulling all pages from Notion parent page: 123e4567-e89b-12d3-a456-426614174000
Found 3 pages under parent 123e4567-e89b-12d3-a456-426614174000

[1/3] Pulling page: Project Overview
  Notion ID: abc123-def456-789012
  Page title: Project Overview
  Saving to: docs/Project Overview.md
  ✓ Successfully pulled

[2/3] Pulling page: API Documentation
  Notion ID: def456-ghi789-012345
  Page title: API Documentation
  Saving to: docs/API Documentation.md
  ✓ Successfully pulled

[3/3] Pulling page: Getting Started Guide
  Notion ID: ghi789-jkl012-345678
  Page title: Getting Started Guide
  Saving to: docs/Getting Started Guide.md
  ✓ Successfully pulled

✓ Pull completed successfully

Example output for pulling a single page:

Pulling page from Notion...
  Page ID: abc123-def456-789012
  Output: docs/my-document.md
  Page title: Project Overview

✓ Successfully pulled page to docs/my-document.md

🎯 Pull Command Improvements

• Progress Counter: Shows "[1/3]" style progress for multiple pages
• Page Titles: Displays actual Notion page titles as they're processed
• Notion IDs: Shows page IDs for reference and debugging
• File Paths: Clear indication of where each file will be saved
• Success Confirmation: Individual success messages for each page
• Parent Page Context: Shows which parent page is being processed
• Total Count: Displays total number of pages found before processing

🚀 Workflow Benefits

For New Users

• Setup Verification: verify command ensures everything is configured correctly before first use
• Clear Feedback: Know immediately if your credentials or configuration have issues
• Guided Setup: Helpful error messages guide users to fix configuration problems

For Daily Users

• Context Awareness: Always know which Notion workspace you're working with
• Pull Transparency: See exactly what pages are being downloaded and where
• Progress Tracking: Monitor progress during large pull operations
• Debugging Support: Page IDs and paths help troubleshoot any issues

For Team Workflows

• Workspace Identification: Status shows parent page title to confirm correct workspace
• Batch Operations: Clear progress indicators for team documentation pulls
• Audit Trail: Detailed output helps track what content was synchronized

💻 Usage Examples

Quick Setup Verification

# Check if ready to use
notion-md-sync verify

# If issues found, fix config and verify again
notion-md-sync verify

# Check current workspace and file status
notion-md-sync status

Enhanced Pull Workflow

# Verify setup first
notion-md-sync verify

# Pull with full visibility
notion-md-sync pull --verbose
# Shows: parent page, page count, individual progress, titles, paths

# Check what was pulled
notion-md-sync status
# Shows: parent page context and new file status

Daily Workflow

# Morning setup check
notion-md-sync verify           # ✅ Ready to sync
notion-md-sync status          # On parent page: Team Documentation
notion-md-sync pull --verbose  # Pull latest from team
notion-md-sync add .           # Stage local changes
notion-md-sync push            # Push to Notion

🔧 Technical Implementation

Verify Command

• Configuration Validation: Comprehensive checks for all required settings
• API Integration: Live validation with Notion API when possible
• Error Categorization: Clear separation of configuration vs. connectivity issues
• Helpful Guidance: Specific instructions for fixing common problems

Enhanced Status

• Notion API Integration: Real-time page title fetching with caching
• Fallback Strategy: Graceful handling when API calls fail
• Performance Optimization: Efficient API calls with timeouts
• User Experience: Familiar Git-like interface with Notion context

Improved Pull Output

• Progress Tracking: Accurate counters and completion indicators
• Information Rich: Maximum useful information without clutter
• Error Handling: Clear error messages with context
• Performance: No impact on sync speed despite enhanced output

⚡ Performance & Reliability

• Minimal Overhead: Verify and status commands are fast and lightweight
• Timeout Protection: API calls have reasonable timeouts to prevent hanging
• Error Recovery: Graceful handling of network issues or API problems
• Caching Strategy: Intelligent caching where appropriate to reduce API calls

🎉 Developer Experience Improvements

This release makes notion-md-sync significantly more user-friendly:

• 🔍 Transparent: Always know what's happening and why
• 🛡️ Reliable: Verify setup before running into issues
• 📊 Informative: Rich feedback during all operations
• 🎯 Professional: Enterprise-grade visibility and error handling
• 📚 Documented: Clear examples and usage patterns

⚠️ No Breaking Changes

This release is fully backward compatible:

• All existing commands work exactly as before
• New commands are purely additive
• Enhanced output is opt-in via existing --verbose flag
• Configuration files require no changes