Feature: PushMD - Media upload & upsert support for push-only staging workflow

Start with the push synchronization path and the mentioned export_media_content() behavior, then trace how WordPress uploads are handled. Use the proposed media/ workflow, validation rules, URL rewriting, upsert behavior, and pull cleanup as acceptance criteria; the issue names no implementation files or tests, so project discovery is required.

Summary / Context

Currently, Push MD allows Markdown-first teams and AI coding agents to clone, edit, and push WordPress posts, pages, and templates. However, there is no support for managing post image assets through Git. When an author or agent creates a new post locally that includes diagrams, screenshots, quote cards, or a featured image, they must manually upload those images via WP-Admin and copy the resulting URLs back into Markdown before pushing.

I propose adding native Git media support to Push MD using a push-only staging directory (media/). Authors can drop image binaries into media/, reference them using relative paths in Markdown or Gutenberg blocks, and push via Git. Push MD handles fail-closed image validation, uploads/upserts the files into the WordPress Media Library, rewrites all inline content & block references to absolute WordPress attachment URLs, and cleans up the staging files on git pull to keep local checkouts lightweight.

Why Media Upload Support is Useful

1. Complete Offline & Agent Workflows: Coding agents and local Markdown editors (Obsidian, VS Code, Cursor) can create complete posts - text and images - in a single Git commit without requiring manual WP-Admin file uploads.
2. Lean Local Repositories (Push-Only Staging): By operating media/ as a push-only staging area, binary image blobs do not accumulate in Git history or bloat local checkouts over time.
3. In-Place Image Versioning: Updating an existing image via Git overwrites the file on disk and regenerates WordPress image metadata without creating duplicate attachment records (image-1.png, image-2.png).
4. Automatic Attachment Metadata: Alt text, image titles, and <figcaption> captions written in Markdown or HTML automatically populate WordPress attachment metadata.

Proposed Architecture & Workflow

1. The media/ Staging Directory

• A media/ directory is present in the repository tree (maintained via a media/.gitkeep placeholder).
• Authors place image files directly under media/ (e.g. media/architecture-diagram.png).
• In post Markdown, images are referenced using standard relative syntax:

---
title: "New Product Launch"
featured_image: "../media/hero.webp"
---
![Architecture Diagram](../media/architecture-diagram.png "System Architecture")

2. Push-Time Ingestion & URL Rewriting

When a commit is pushed to trunk:

1. Upfront Payload Ingestion: Push MD detects files in media/, validates them, and uploads them to the WordPress Uploads folder, creating or updating attachment records.
2. Contextual Metadata Assignment: Alt text (![Alt Text](...)), titles ("Title Text"), and figure captions (<figcaption>...</figcaption>) in post markup populate _wp_attachment_image_alt, post_title, and post_excerpt on the corresponding attachment.
3. Multi-Format Content Rewriting: Relative media/ paths are rewritten to absolute WordPress upload URLs across:
   • Markdown image syntax: ![alt](url "title")
   • HTML attributes: src, href, poster, srcset across <img>, <source>, <figure>, and <a> tags
   • Gutenberg Block comment JSON metadata: <!-- wp:image {"id":0,"url":"../media/chart.png"} --> (updates id, mediaId, and url fields)
   • Front matter featured_image (assigns post thumbnail attachment ID)
4. Filename-Based Re-Linking: If a Markdown post is pushed in a later commit referencing media/existing-chart.png (where the binary is no longer in the commit tree), Push MD resolves existing-chart.png against existing Media Library attachments by filename and links it cleanly.

3. Automatic Working Tree Cleanup (git pull)

• Binary images are ingested into the WordPress Media Library on push.
• To prevent binary bloat, Push MD does not export the Media Library into Git on clone/fetch (export_media_content() returns an empty array).
• On the next git pull, repository synchronization notices the pushed image files are no longer exported by WordPress and creates a sync commit that deletes the staging image files from the Git tree while preserving media/.gitkeep.
• Git fast-forwards the local working directory, automatically deleting the local media/image.png file while keeping the media/ folder intact.

4. In-Place Upserts (Image Versioning)

• Standard WordPress wp_upload_bits() renames same-named uploads to image-1.png, image-2.png, creating duplicate attachment records.
• Push MD checks if an attachment with the exact filename already exists. If found:
  • Overwrites the file on disk (get_attached_file()) in-place.
  • Regenerates image metadata (dimensions, thumbnails) via wp_generate_attachment_metadata().
  • Returns the existing attachment ID and URL, preserving existing post references.

Security, Validation & Safety Model

Push MD operates on a strict fail-closed safety model:

1. Extension Whitelist: Only .png, .jpg, .jpeg, .gif, and .webp extensions are accepted.
2. Binary MIME Type Detection: Validates raw binary headers using finfo_buffer with fallback magic-number inspection (\x89PNG\r\n\x1a\n, \xFF\xD8\xFF, GIF87a/GIF89a, RIFF...WEBP) to prevent extension spoofing or execution of non-image payloads.
3. Path Traversal Protection: Rejects paths containing .. or attempted directory escapes outside media/.
4. WordPress Capability Checks: Media upload processing runs within the authenticated user session, respecting WordPress editorial capabilities.
5. Non-Image Filtering: Non-image placeholder files in media/ (such as .gitkeep) are skipped during ingestion without raising validation errors.

Why not WordPress media REST API?

I implemented this using REST API initially, but that requires additional maintenance, authentication and integration. Doing it via PushMD is much cleaner approach.