WordpressGitSync/README.md

# Oribi Tech Sync

WordPress plugin that syncs pages and theme files from a remote Git repository.

## Features

- **Page sync (pull)** — Reads Gutenberg HTML files from the repo's `pages/` directory and creates/updates WordPress pages automatically.
- **Page push** — Push WordPress page content back to the repo as PHP page-data files. On conflict (remote file changed since last sync), automatically creates a branch and opens a pull request for review.
- **Theme file preview & apply** — Fetches files from the repo's `theme/` directory, shows a side-by-side preview against the active theme, and lets an admin selectively apply changes.
- **Encrypted PAT storage** — Personal Access Tokens are stored encrypted (AES-256-CBC) in the database with `autoload=false`.
- **Dry-run mode** — Preview what a sync would do without making any changes.
- **Sync log** — Keeps a history of the last 20 syncs with details on created, updated, trashed, and skipped pages.
- **REST API & webhook** — Trigger syncs and pushes programmatically or via Git host webhooks.
- **Trash policy** — Pages removed from the repo are moved to Trash for manual review.

## Repository Layout

The plugin expects the following structure in the remote Git repository:

```
repo/
├── pages/
│   ├── home.php
│   ├── about.php
│   ├── contact.php
│   ├── managed-it.php
│   └── ...
├── theme/
│   ├── style.css
│   ├── theme.json
│   └── assets/
│       ├── css/
│       │   └── main.css
│       └── js/
│           └── main.js
└── (other files — ignored)
```

### `pages/` directory
- **PHP files** (`.php`) — Use the `oribi_b()`, `oribi_b_open()`, and `oribi_b_close()` block helpers to build Gutenberg markup and `return` the result (same format as the theme's `page-data/*.php` files). Requires the **Oribi Tech Setup** plugin to be active for the helper functions.
- **HTML files** (`.html`) — Contain raw Gutenberg block markup (`<!-- wp:... -->`) and are used directly as page content.
- The filename (without extension) becomes the page slug: `home.php` → slug `home`.
- Page title is derived from the slug: `managed-it` → "Managed It".
- Only direct children of `pages/` are processed (no subdirectories).

### `theme/` directory
- Contains theme style/asset files (CSS, JS, JSON, PHP, HTML, SVG, TXT).
- Subdirectories are supported — e.g., `theme/assets/css/main.css` maps to `<active-theme>/assets/css/main.css`.
- Files are **not** applied automatically — they are fetched for preview.
- Admin can review each file, compare against the active theme, and selectively apply.
- Applied files are written directly into the active theme directory.

## Supported Git Providers

| Provider | Auth method | PAT format |
|---|---|---|
| **GitHub** (github.com + GHE) | `Bearer` token | Fine-grained PAT with `Contents: Read` |
| **GitLab** (gitlab.com + self-hosted) | `PRIVATE-TOKEN` header | Project/personal access token with `read_repository` |
| **Bitbucket Cloud** | Basic or Bearer | App password (`username:app_password`) or repository token |
| **Gitea / Forgejo** | `token` header | Application token with repo **read + write** access |
| **Azure DevOps** | Basic (`:PAT`) | Personal access token with `Code: Read` scope |

Select your provider on the settings page, or leave it on "Auto-detect" to infer from the URL.

## Setup

1. Install and activate the plugin on your WordPress site.
2. Go to **Settings → Oribi Sync**.
3. Enter the **Repository URL** (HTTPS format, e.g., `https://github.com/owner/repo`, `https://gitlab.com/owner/repo`, `https://bitbucket.org/owner/repo`, `https://gitea.example.com/owner/repo`, or `https://dev.azure.com/org/project/_git/repo`).
4. Select the **Provider** (or leave on auto-detect).
5. Enter the **Branch** (defaults to `main`).
6. Enter a **Personal Access Token** with read access to the repository (see table above for format).
7. Click **Save Settings**.

## Usage

### Manual Sync
- Click **Sync Now** on the settings page to sync pages immediately.
- Click **Dry Run** to preview changes without modifying anything.
- Click **Preview Theme Files** to fetch and review theme files from the repo.

### Push Pages to Repo
- The **Push Pages to Repo** section lists all synced pages with individual **Push** buttons and a **Push All Pages** button.
- Pushing converts the page's Gutenberg content into a PHP page-data file and commits it to the configured branch.
- **Conflict handling:** If the remote file has changed since the last sync (SHA mismatch), the plugin creates a branch named `oribi-sync/{slug}-{timestamp}` and opens a **pull request** for manual review. A link to the PR is shown in the admin UI.

### REST API

All REST endpoints require `manage_options` capability (authenticated admin).

```bash
# Trigger sync
curl -X POST https://yoursite.com/wp-json/oribi-sync/v1/sync \
  -H "X-WP-Nonce: <nonce>" \
  --cookie "wordpress_logged_in_...=..."

# Trigger dry-run
curl -X POST "https://yoursite.com/wp-json/oribi-sync/v1/sync?dry_run=1" \
  -H "X-WP-Nonce: <nonce>" \
  --cookie "wordpress_logged_in_...=..."

# Push a single page
curl -X POST https://yoursite.com/wp-json/oribi-sync/v1/push \
  -H "X-WP-Nonce: <nonce>" \
  -H "Content-Type: application/json" \
  -d '{"post_id": 123}' \
  --cookie "wordpress_logged_in_...=..."

# Push all synced pages
curl -X POST https://yoursite.com/wp-json/oribi-sync/v1/push-all \
  -H "X-WP-Nonce: <nonce>" \
  --cookie "wordpress_logged_in_...=..."

# Get status
curl https://yoursite.com/wp-json/oribi-sync/v1/status \
  -H "X-WP-Nonce: <nonce>" \
  --cookie "wordpress_logged_in_...=..."
```

### Webhook

Set up a webhook on your Git host to trigger syncs on push:

**Endpoint:** `POST https://yoursite.com/wp-json/oribi-sync/v1/webhook`

**Authentication** (one of):
- `Authorization: Bearer <secret>` header
- GitHub `X-Hub-Signature-256` header (HMAC-SHA256)

**Secret configuration** (one of):
- Define `ORIBI_SYNC_WEBHOOK_SECRET` in `wp-config.php`
- Store in WP option `oribi_sync_webhook_secret`

## Security

- PAT is encrypted with AES-256-CBC using a key derived from `AUTH_SALT`.
- All admin actions require `manage_options` capability and nonce verification.
- REST endpoints require authenticated admin user.
- Webhook endpoint validates shared secret or HMAC signature.
- Theme file writes are restricted to allowed extensions (CSS, JS, JSON, PHP, HTML, SVG, TXT).

## Sync Behavior

| Scenario | Action |
|---|---|
| New file in `pages/` | Create new WP page (published) |
| Changed file in `pages/` | Overwrite page content |
| Unchanged file in `pages/` | Skip (no unnecessary revisions) |
| File removed from `pages/` | Move corresponding WP page to Trash |
| New file in `theme/` | Available for preview & manual apply |
| Changed file in `theme/` | Available for preview & manual apply |
| **Push:** page not in repo | Create `.php` file on target branch |
| **Push:** page in repo, no conflict | Update `.php` file on target branch |
| **Push:** page in repo, SHA conflict | Create branch `oribi-sync/{slug}-{timestamp}`, commit, open PR |

## Requirements

- WordPress 6.0+
- PHP 7.4+ with `openssl` extension
- Git host with API access (GitHub or GitLab supported)