Summary

BREAKING CHANGE: Complete restructure of JSON output format, separating planning from execution results.

New Features

1. Separate Plan and Result Outputs

• --plan-json-file: Outputs the execution plan before any operations
• --result-json-file: Outputs actual execution results (not generated in dry-run mode)

2. Improved JSON Structure

Plan JSON (--plan-json-file)

{
  "files": [
    {
      "action": "create",     // "skip", "create", "update", "delete"
      "source": "/local/path/file.txt",
      "target": "s3://bucket/prefix/file.txt",
      "reason": "new file"    // Explanation for the action
    }
  ],
  "summary": {
    "skip": 5,      // Files unchanged (matching checksums)
    "create": 3,    // New files to upload
    "update": 2,    // Files to update
    "delete": 1     // Files to delete
  }
}

Result JSON (--result-json-file)

{
  "files": [
    {
      "action": "created",    // Past tense: "skipped", "created", "updated", "deleted"
      "source": "/local/path/file.txt",
      "target": "s3://bucket/prefix/file.txt"
    }
  ],
  "errors": [              // Always an array, even when empty
    {
      "action": "create",
      "source": "/local/path/failed.txt",
      "target": "s3://bucket/prefix/failed.txt",
      "error": "Permission denied"
    }
  ],
  "summary": {
    "skipped": 5,    // Successfully skipped (unchanged)
    "created": 3,    // Successfully created
    "updated": 2,    // Successfully updated
    "deleted": 1,    // Successfully deleted
    "failed": 1      // Failed operations (count of errors array)
  }
}

Key Changes

1. Plan vs Result Separation

   • Plan shows what will be done (present tense)
   • Result shows what was done (past tense)

2. Error Handling

   • Failed operations go to errors array with error messages
   • Failed operations do NOT count toward success metrics
   • Example: If update fails, it counts as failed, not updated
   • errors array is always present (empty array [] when no errors)

3. Simplified Structure

   • Removed total_files field (can be calculated from summary)
   • Consistent file representation across plan and result
   • Clear separation between successful and failed operations

4. Dry-run Behavior

   • --plan-json-file: Always generated when specified
   • --result-json-file: NOT generated in dry-run mode

5. Skip Tracking

   • Files with unchanged checksums are included as "skip" in plan
   • Successfully skipped files appear as "skipped" in result
   • Excluded files (via --exclude patterns) are NOT included in JSON output

Migration Guide

Before (v0.2.x)

{
  "changes": [...],
  "summary": {
    "total_files": 10,
    "created": 5,
    "updated": 3,
    "deleted": 2,
    "failed": 0
  }
}

After (v0.3.0)

• For planning: Use --plan-json-file
• For results: Use --result-json-file
• Structure completely changed (see examples above)

Testing

Tested with real S3 bucket (yuyat-strict-s3-sync-test):

• ✅ Plan JSON output with all action types
• ✅ Result JSON output with successful operations
• ✅ Empty errors array when no failures
• ✅ Skip tracking for unchanged files
• ✅ Create/Update/Delete operations
• ✅ Dry-run mode (no result JSON output)

Test Plan

• Unit tests pass
• Build successful
• Manual testing with real S3 bucket
• Verify plan output format
• Verify result output format
• Test error array initialization

🤖 Generated with Claude Code