# Copilot instructions for this repo Purpose: Help AI coding agents (and contributors) quickly understand, modify, and extend the R&D Job Planner integration between a WordPress plugin and a TUC scraper that syncs Google Sheets. - **Big picture**: Two cooperating components: - `job-planner.php` — a WordPress plugin (intended at `wp-content/plugins/job-planner`) that reads Google Sheets and renders a FullCalendar UI + jobs table. Key constants: `SHEET_ID`, `TAB_MASTER = 'Master Calendar'`, `TAB_TEAM = 'Team Calendar'`. - `from tuc_scrape.py` — a Python scraper that logs into the TUC site, parses the calendar, and uploads rows into the Google Sheet (`SHEET_NAME = "R&D TUC Calendar"`, worksheet `WORKSHEET = "TUC Data"`). - Both use the same `service_account.json` credentials file for Google API access. - **Primary data flow** (use these files as the source of truth): - Scraper (`from tuc_scrape.py`) -> writes rows to Google Sheets worksheet `TUC Data`. - Plugin (`job-planner.php`) reads `Master Calendar`, `Team Calendar`, and optionally `TUC Data` to build events. - **Canonical row/column names** (these exact header strings are expected in Sheets): - `Date`, `Job Title`, `Job Number`, `Site`, `Postcode`, `Project Manager`, `Link`, `Notes`, `Status`, `CreatedBy`, `CreatedAt`. - The plugin maps these to FullCalendar events via `rows_to_events()` and stores extra info in `extendedProps` with keys: `site`, `pm`, `jobNo`, `postcode`, `link`. - **Important code patterns and conventions** (copy/paste examples when needed): - Date normalisation in `rows_to_events()` supports: - ISO `YYYY-MM-DD` strings - `dd/mm/yyyy` input from forms (converted to `YYYY-MM-DD`) - Excel serial dates (treated as numeric and converted) - When adding a job via the plugin form, `gs_append_row()` looks up the sheet header row and appends values in header order — modify headers carefully. - **Developer workflows / quick commands** - PHP plugin (local dev): - Place plugin folder at `wp-content/plugins/job-planner` of a WordPress instance. - Install PHP Google API client in plugin dir: `composer require google/apiclient` (so `vendor/autoload.php` exists). - Ensure `service_account.json` is in the plugin directory (file path referenced by `SERVICE_ACCOUNT_FILE`). - Python scraper (local or server): - Create venv: `python -m venv .venv` then `.\.venv\Scripts\Activate.ps1` (Windows PowerShell). - Install deps: `pip install playwright beautifulsoup4 pandas gspread google-auth schedule`. - Install browser binaries for Playwright: `python -m playwright install`. - Run one-off: `python "from tuc_scrape.py"` (script runs once by default and will schedule if `schedule` is installed). - Toggle headless: change `browser = p.chromium.launch(headless=False, ...)` to `headless=True` for headless runs. - **Integration points & configuration to check when editing** - `service_account.json` — keep this file secure (both PHP and Python expect local file access). Paths in both files assume the credentials file is colocated with the scripts. - `SHEET_ID` in `job-planner.php` and `SHEET_NAME`/`WORKSHEET` in the scraper must reference the same spreadsheet/worksheet names if you want the plugin and scraper to share data. - The plugin expects Composer's `vendor/autoload.php` at plugin root — do not remove or rename. - **Testing tips & quick validations** - PHP: Enable WP_DEBUG and load the page containing the `[rd_job_planner]` shortcode to validate that events render and no Google API errors appear. - Python: Run scraper locally with `headless=False` to visually verify login and parsed HTML. Check that the Google Sheet `TUC Data` receives rows with the canonical headers. - **What _not_ to assume** - There is no CI or test harness in this repo; do not expect automated tests. Changes to headers may break the plugin because `gs_append_row()` relies on header order. - If anything here is unclear or you want runnable setup scripts (Composer/Pip), example unit tests or a sample `README`, ask and I will add them.