Simplify `remote` and `file` to `sync`

[DavidWells]

I think there might be a way to simplify things with the different transforms. We can still keep the base transforms, but a lot of these really just come down to sync. So it's syncing from one of these sources. And yeah, if it's pointing to a file, it'd just be syncing from the file. If it's pointing to a URL, it'd be syncing from that URL. And then we probably need to allow for additional remote requests and different methods.

So TBD might be able to streamline this

[DavidWells]

What are your thoughts?

thanks @claude opus

[github-actions]

💬 Claude Code execution complete ✅

ℹ️ Analysis only (no code changes)

📊 Execution Info: Issue #116 | Next.js (124 files) | @DavidWells
ℹ️ Action Run: https://github.com/DavidWells/markdown-magic/actions/runs/20901160534

[github-actions]

Claude finished @DavidWells's task in 56s —— View job

---

Analysis: Unifying REMOTE and FILE into SYNC

• Read repository guidelines
• Explore current transform implementations
• Analyze remote and file transforms
• Provide thoughts on sync unification

---

After reviewing the codebase, I think this is a solid idea that could simplify the API. Here's my analysis:

Current State

You have three transforms that fetch content:

Transform	Source	Features
FILE	Local filesystem	textBefore/textAfter, markdown formatting
REMOTE	HTTP URLs	url/src options, markdown formatting
CODE	Both local & remote	Line ranges, sections, syntax highlighting, GitHub URL conversion

Interestingly, CODE already implements a unified pattern - it uses isLocalPath() to determine whether to read from disk or fetch remotely.

Benefits of SYNC

1. Simpler mental model - Users don't need to remember which transform to use based on source type
2. Consistent API - One src attribute that works everywhere
3. CODE already proves the pattern works - It handles both sources transparently

Proposed Design

Core options:

• src - Path or URL (auto-detected like in CODE)
• method - HTTP method for remote (default: GET)
• headers - Custom headers for authenticated requests
• textBefore/textAfter - Preserved from FILE

Implementation Approach

// Simplified logic
module.exports = async function SYNC(api) {
  const { options, srcPath, settings } = api
  const { src } = options
  
  let content
  if (isLocalPath(src)) {
    content = readLocalFile(src, srcPath)
  } else {
    content = await fetchRemote(src, options, settings)
  }
  
  return formatContent(content, options)
}

Key Questions

1. Should CODE also use SYNC internally? - This could reduce duplication, with CODE just wrapping SYNC and adding code block formatting

2. Remote request options - For different HTTP methods, consider:

3. Backward compatibility - Keep FILE and REMOTE as aliases that delegate to SYNC?

Suggested Approach

1. Create SYNC transform with unified source detection
2. Add support for HTTP method/headers options
3. Keep FILE/REMOTE as thin wrappers for backward compatibility
4. Consider having CODE use SYNC internally for content fetching

This would reduce code duplication and give users a more intuitive API while maintaining backward compatibility.

Would you like me to draft an implementation?

[DavidWells]

"Proposed Design" and "Remote request options - For different HTTP methods, consider:" block are empty

show me them as yaml or something the HTML comments are getting stripped here thanks @claude opus

[github-actions]

Claude finished @DavidWells's task in 28s —— View job

---

SYNC Transform Examples (YAML Format)

• Show proposed SYNC design examples
• Show remote request options examples

---

The HTML comments got stripped because GitHub renders them as actual comments. Here are the examples in YAML-style format:

Proposed Design

Local file sync:

# Transform: SYNC
# Options:
  src: ./path/to/file.md

Remote URL sync:

# Transform: SYNC
# Options:
  src: https://example.com/data.json

With text wrapping:

# Transform: SYNC
# Options:
  src: ./relative/path.md
  textBefore: ""
  textAfter: ""

Remote Request Options

Different HTTP methods:

# Transform: SYNC
# Options:
  src: https://api.example.com/data
  method: POST
  headers:
    Authorization: "Bearer ${TOKEN}"
    Content-Type: "application/json"
  body: '{"query": "data"}'

GET with custom headers:

# Transform: SYNC
# Options:
  src: https://api.github.com/repos/user/repo/readme
  headers:
    Accept: "application/vnd.github.v3.raw"

Actual markdown-magic Syntax (escaped)

For reference, here's what the actual syntax would look like in your markdown files:

---