chore: add CI (PHP lint + WPCS) and contributor docs

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,41 @@
+<!--
+  Thanks for contributing to WP Puller! Please fill out the sections below.
+  Keep PRs focused: one logical change per PR is much easier to review and merge.
+-->
+
+## Summary
+
+<!-- What does this PR do, and why? -->
+
+## Type of change
+
+- [ ] Bug fix (non-breaking change that fixes an issue)
+- [ ] New feature (non-breaking change that adds functionality)
+- [ ] Security fix
+- [ ] Breaking change (fix or feature that changes existing behaviour)
+- [ ] Refactor / chore (no functional change)
+- [ ] Documentation
+
+## Related issues
+
+<!-- e.g. "Closes #123". If there is no issue, briefly explain the motivation. -->
+
+## How was this tested?
+
+<!--
+  Describe the steps you took to verify the change. For example:
+  - WordPress version(s) and PHP version(s) tested
+  - Steps to reproduce the original behaviour and confirm the fix
+  - `php -l` / `composer run lint` output
+-->
+
+## Checklist
+
+- [ ] My change is focused on a single concern (large rewrites are split into reviewable parts).
+- [ ] `php -l` passes on all changed files.
+- [ ] I ran `composer run lint` and did not introduce new coding-standards violations.
+- [ ] I have not committed secrets, tokens, or rebuilt binaries (e.g. `wp-puller.zip`) unless explicitly intended.
+- [ ] Security-sensitive code (auth, webhooks, encryption, file I/O, HTTP requests) has been reviewed for the project's hardening rules — see CONTRIBUTING.md.
+- [ ] User-facing strings are internationalised with the `wp-puller` text domain.
+
+## Screenshots / notes (optional)

.github/workflows/ci.yml

@@ -0,0 +1,81 @@
+name: CI
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  # ---------------------------------------------------------------------------
+  # PHP syntax lint — a hard gate. Every supported PHP version must parse the
+  # plugin without errors before anything can be merged.
+  # ---------------------------------------------------------------------------
+  php-lint:
+    name: PHP Lint (php ${{ matrix.php }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        php: ['7.4', '8.0', '8.1', '8.2', '8.3']
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup PHP
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: ${{ matrix.php }}
+          coverage: none
+
+      - name: Lint all PHP files
+        run: |
+          find wp-puller -name '*.php' -print0 \
+            | xargs -0 -n1 -P4 php -d display_errors=1 -l
+
+  # ---------------------------------------------------------------------------
+  # WordPress Coding Standards (PHPCS + WPCS).
+  #
+  # ADVISORY for now: the legacy codebase has a large backlog of formatting
+  # violations (~97% auto-fixable with `composer run lint:fix`). This job
+  # surfaces that debt on every PR without blocking merges. Once the backlog is
+  # cleared in a dedicated cleanup PR, remove `continue-on-error` below to make
+  # WPCS a required gate. Tracking: see CONTRIBUTING.md ("Coding standards").
+  # ---------------------------------------------------------------------------
+  coding-standards:
+    name: WordPress Coding Standards (advisory)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup PHP
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: '8.2'
+          coverage: none
+          tools: composer
+
+      - name: Install dependencies
+        run: composer install --no-interaction --no-progress --prefer-dist
+
+      - name: Run PHPCS
+        id: phpcs
+        continue-on-error: true
+        run: |
+          ./vendor/bin/phpcs --report-full --report-summary --runtime-set ignore_warnings_on_exit 0
+
+      - name: Note advisory status
+        if: steps.phpcs.outcome == 'failure'
+        run: |
+          echo "::warning::WPCS reported violations. This check is advisory for now — see CONTRIBUTING.md. Run 'composer run lint:fix' locally to auto-fix most of them."
+          {
+            echo "### WordPress Coding Standards (advisory)"
+            echo ""
+            echo "WPCS reported violations. This check does **not** block merges yet."
+            echo "Run \`composer run lint:fix\` locally to auto-fix most of them."
+          } >> "$GITHUB_STEP_SUMMARY"

.gitignore

@@ -0,0 +1,12 @@
+# Composer dev tooling
+/vendor/
+
+# PHPCS cache
+.phpcs.cache
+
+# OS / editor cruft
+.DS_Store
+Thumbs.db
+*.swp
+.idea/
+.vscode/

CONTRIBUTING.md

@@ -0,0 +1,98 @@
+# Contributing to WP Puller
+
+Thanks for your interest in improving WP Puller! This document explains how we
+work so that contributions are easy to review and merge.
+
+WP Puller is a WordPress plugin that updates a theme (or plugin) from a GitHub
+repository, with webhook-based real-time updates and encrypted token storage.
+Because it touches authentication, webhooks, encryption, and the filesystem, we
+hold contributions to a high security bar — see [Security](#security) below.
+
+## Getting started
+
+1. Fork the repository and create a branch off `main`:
+   ```bash
+   git checkout -b fix/short-description main
+   ```
+2. Install the development tooling (PHP 7.4+ and Composer required):
+   ```bash
+   composer install
+   ```
+3. Make your change, then run the checks described below.
+4. Open a pull request against `main` and fill out the PR template.
+
+The plugin code lives in `wp-puller/`. The repository also ships a built
+`wp-puller.zip`; **do not** rebuild or commit it in feature PRs unless that is
+the explicit purpose of the PR — release artifacts are handled separately.
+
+## Keep pull requests focused
+
+One logical change per PR. Small, scoped PRs get reviewed and merged quickly;
+large, multi-concern PRs (rewrites, sweeping refactors) are hard to review
+safely and tend to stall. If you are planning a large change or a change in
+product direction, please open an issue to discuss it first so we can agree on
+an approach and a way to split it into reviewable pieces.
+
+## Coding standards
+
+We follow the [WordPress Coding Standards](https://github.com/WordPress/WordPress-Coding-Standards)
+(WPCS) via PHP_CodeSniffer. The ruleset lives in `phpcs.xml.dist`.
+
+```bash
+composer run lint       # report violations
+composer run lint:fix   # auto-fix what can be fixed (phpcbf)
+php -l path/to/file.php  # syntax check a single file
+```
+
+> **Note on the current baseline.** The existing codebase predates this
+> ruleset and carries a backlog of (mostly auto-fixable) formatting
+> violations. The WPCS job in CI is therefore **advisory** for now: it reports
+> violations but does not block merges. Please do not introduce *new*
+> violations, and run `composer run lint:fix` on the files you touch. Once the
+> backlog is cleared in a dedicated cleanup PR, the WPCS job will become a
+> required gate.
+
+Other conventions:
+
+- Internationalise all user-facing strings with the `wp-puller` text domain.
+- Prefix global functions/classes/options with `wp_puller` / `WP_Puller`.
+- Escape on output (`esc_html`, `esc_attr`, `esc_url`) and sanitise on input.
+
+## Continuous integration
+
+Every push and pull request runs the [`CI`](.github/workflows/ci.yml) workflow:
+
+- **PHP Lint** — `php -l` on every PHP file across PHP 7.4–8.3. This is a
+  **required** check; PRs cannot merge while it is failing.
+- **WordPress Coding Standards** — PHPCS/WPCS, currently advisory (see above).
+
+## Security
+
+WP Puller handles GitHub tokens, signed webhooks, AES-256-CBC encryption, and
+writes to the WordPress filesystem. When changing security-sensitive code,
+please preserve the project's hardening rules:
+
+- **Webhooks**: verify the `X-Hub-Signature-256` HMAC signature *before* acting
+  on any event (including `ping`). Keep the IP-based rate limiting in place.
+- **Encryption**: tokens are stored with authenticated encryption (the `v2:`
+  format: AES-256-CBC + HMAC-SHA256). Do not weaken this or reintroduce a
+  hardcoded fallback key.
+- **HTTP**: use `wp_safe_remote_*` for outbound requests.
+- **Filesystem**: guard against path traversal (`..`) in user-supplied paths;
+  do not suppress filesystem errors with `@`.
+- **Secrets**: never log tokens, secrets, or token prefixes, and never echo
+  them unmasked in the admin UI.
+
+If you discover a security vulnerability, please **do not** open a public issue.
+Instead, report it privately to the maintainers (see the repository's security
+policy / contact) so it can be fixed before disclosure.
+
+## Reporting bugs and requesting features
+
+Open an issue with:
+
+- WordPress and PHP versions
+- Steps to reproduce (for bugs), expected vs. actual behaviour
+- Relevant log output (with any secrets redacted)
+
+Thanks again for contributing! 🎉

composer.json

@@ -0,0 +1,25 @@
+{
+    "name": "codician-team/wp-puller",
+    "description": "Automatically update your WordPress theme from GitHub. Supports public and private repositories with webhook-based real-time updates.",
+    "type": "wordpress-plugin",
+    "license": "GPL-2.0-or-later",
+    "homepage": "https://github.com/codician-team/wp-puller",
+    "require": {
+        "php": ">=7.4"
+    },
+    "require-dev": {
+        "squizlabs/php_codesniffer": "^3.9",
+        "wp-coding-standards/wpcs": "^3.1",
+        "phpcompatibility/phpcompatibility-wp": "^2.1",
+        "dealerdirect/phpcodesniffer-composer-installer": "^1.0"
+    },
+    "config": {
+        "allow-plugins": {
+            "dealerdirect/phpcodesniffer-composer-installer": true
+        }
+    },
+    "scripts": {
+        "lint": "phpcs",
+        "lint:fix": "phpcbf"
+    }
+}