v-wordpress-plugin-updater/.github/copilot-instructions.md

# Copilot Instructions for V-WordPress-Plugin-Updater

## Architecture Overview

This repository contains a **dual-component WordPress updater system**:

1. **Update API Server** (`v-update-api/`): standalone PHP web service that hosts and serves plugin/theme ZIP updates.
2. **WordPress Client Plugin** (`v-wp-updater/`): WordPress plugin that checks the API and installs updates.

Both components are independently deployable.

### Namespaces (Do Not Mix)

- API server code uses `App\...`
- WordPress plugin code uses `VWPU\...`

## Current API Server Architecture (`v-update-api`)

### Core Classes

`v-update-api/app/Core/` currently contains:

- `DatabaseManager.php`
- `ErrorManager.php`
- `Request.php`
- `Response.php`
- `Router.php`

Important: there is **no** `SessionManager`, `ResponseManager`, or `Controller` base class in the current architecture.

### Request/Response Pattern

- `App\Core\Request::fromGlobals()` parses the URL path and builds a request object.
- `App\Core\Router::dispatch()` returns an `App\Core\Response`.
- `public/index.php` sends the returned response via `$response->send()`.
- Prefer `Response` static factories:
  - `Response::view()`
  - `Response::redirect()`
  - `Response::text()`
  - `Response::json()`
  - `Response::file()`
  - `Response::html()`

### Session and Security Helpers

Session/auth logic is implemented through `App\Helpers\SessionHelper` (static helper), not a singleton session manager.

- Initialize/access session values with `SessionHelper::get()` / `SessionHelper::set()`.
- Validate auth session with `SessionHelper::isValid()`.
- Regenerate session after successful login with `SessionHelper::regenerate()`.
- CSRF token is initialized in `public/index.php` if missing.

### Error Handling

`App\Core\ErrorManager` is a singleton that registers error/exception/shutdown handlers and provides centralized logging.

## Routing and Controller Conventions

### Router Behavior

`App\Core\Router`:

- Uses FastRoute (`FastRoute::recommendedSettings(...)`).
- Protects all non-login, non-API routes with auth checks.
- Applies CSRF checks to non-GET/HEAD/OPTIONS requests outside `/api`.
- Returns `Response` objects from dispatch.

### Registered Routes

- `/` → redirect to `/home`
- `/login` (`GET`, `POST`)
- `/home` (`GET`, `POST`)
- `/plupdate` (`GET`, `POST`)
- `/thupdate` (`GET`, `POST`)
- `/logs` (`GET`, `POST`)
- `/api` (router accepts multiple methods; `ApiController` enforces `GET`)

### Controller Contract

Controllers return `App\Core\Response` instances.
Do not use raw `echo`, `header()`, or `exit` for normal request flow.

## API Contract and Data Model

### Update API (`/api`)

Expected query parameters:

- `type` (`plugin` or `theme`)
- `domain`
- `key`
- `slug`
- `version`

`ApiController` behavior:

- `200`: newer ZIP available (streams file)
- `204`: no update available
- `400`: missing/invalid params
- `403`: authentication failure, blacklisted IP, or invalid/missing client IP
- `404`: authenticated request references unknown slug
- `405`: non-GET method
- `500`: update file unavailable/unreadable

### Storage and Sync

- SQLite DB: `v-update-api/storage/updater.sqlite`
- Key tables: `plugins`, `themes`, `hosts`, `logs`, `blacklist`
- `cron.php` syncs filesystem ZIP metadata to DB and cleans blacklist records

### Update Package Naming

ZIP filenames must use:

`{slug}_{version}.zip` (example: `my-plugin_1.2.3.zip`)

## Encryption and Auth Notes

- Host API keys are stored encrypted via `App\Helpers\EncryptionHelper`.
- Current implementation uses AES-256-GCM with legacy CBC migration support.
- `ENCRYPTION_KEY` is read from `v-update-api/config.php` constant.
- Blacklist behavior:
  - Blacklisted entries expire after 7 days.
  - Non-blacklisted stale entries are pruned after 3 days.

## WordPress Client Plugin (`v-wp-updater`)

### Options and Defaults

Plugin options are managed through `VWPU\Helpers\Options` with `vwpu_` prefix.

Canonical keys:

- `update_plugins`
- `update_themes`
- `update_key`
- `update_plugin_url`
- `update_theme_url`

Stored option names in WP are `vwpu_<key>` (for example, `vwpu_update_key`).

### Scheduled Hooks

- `vwpu_plugin_updater_check_updates`
- `vwpu_theme_updater_check_updates`

Both are scheduled daily on install; each handler checks enablement flags before running.

### Updater Behavior

`PluginUpdater` and `ThemeUpdater`:

- call the API with `type`, `domain`, `slug`, `version`, `key`
- handle statuses `200`, `204`, `403`, others as error
- prefetch ZIP bodies on `200` and reuse local temp file during install to avoid duplicate downloads

## Setup and Operations

### API Server Setup (Current)

1. Set `v-update-api/public/` as web root.
2. Configure `v-update-api/config.php` constants:
   - `VALID_USERNAME`
   - `VALID_PASSWORD`
   - `ENCRYPTION_KEY`
   - `SESSION_TIMEOUT_LIMIT`
3. Ensure `v-update-api/storage/` is writable.
4. Run `v-update-api/public/install.php` to initialize schema.
5. Schedule cron to run `php v-update-api/cron.php` (CLI only, no worker flag).

### Test and Quality Commands

From repository root:

- `vendor/bin/phpunit`
- `vendor/bin/phpcs`
- `vendor/bin/phpcbf`
- `vendor/bin/phpstan`

## Documentation Sync

When behavior changes, update in this order:

1. Code
2. Tests (`tests/`)
3. `CHANGELOG.md` (notable changes)
4. `README.md` (if setup/usage/API changed)
5. `.github/copilot-instructions.md` (architecture/conventions changes)

Also follow `AGENTS.md` checklist before submission.