ca1a41f6f9
Add initial plugin implementation per the CTO engineering handoff (geomonitor/threads/2026-06-ai-visibility-v1/01-cto-eng-handoff.md). ## What - PGM_Probe_Provider interface + PGM_Probe_Result value object - PGM_Perplexity_Provider (sonar via OpenRouter/CF AI Gateway) - PGM_OpenRouter_Provider (GPT-search + Gemini-search, generic parameterised) - PGM_Gateway_Client: shared HTTP + exponential-backoff retry (mirrors PRAB) - PGM_Citation_Detector: domain extraction, is_cited(), get_our_position() - PGM_Cost_Ledger: MTD cost from DB, can_afford() pre-check, hard monthly cap - PGM_Probe_Runner: peptides×intents×models run, budget abort, in-run cache - PGM_Table_Manager: pgm_ai_visibility dbDelta, schema-version, drop_table() - PGM_Config: typed getters, seed_defaults() (12 peptides, 3 intents, 3 models) - PGM_Cron: weekly pgm_weekly_probe schedule/clear - PGM_Data_Collector + PGM_Dashboard_Panel interfaces (seam for future panels) - PGM_Collector_Registry: singleton registry - PGM_Ai_Visibility_Collector: trendline, standings, MTD cost (score formula) - PGM_Ai_Visibility_Panel: proxy note, Chart.js trendline, standings table - PGM_Admin_Page: GEO Monitor menu, Run now POST handler (nonce+capability) - uninstall.php: DROP TABLE + DELETE pgm_* options + wp_clear_scheduled_hook - Unit tests (6 files): citation detection, score calc, cost ledger + budget abort, provider response parsing (mock HTTP), cron, uninstall purge - ARCHITECTURE.md, CONVENTIONS.md, CONTEXT.md (score formula), README.md, CHANGELOG.md — same-commit per DoD - CI workflow: PHP lint (8.1/8.2/8.3) + PHPCS + 300-line check ## Security - Secrets from wp-config constants only; none hardcoded - manage_options + nonce on every admin action - Input sanitized; output escaped Agent-Session: geomonitor v0.1.0
85 lines
3.2 KiB
Markdown
85 lines
3.2 KiB
Markdown
# Conventions — Peptide GEO Monitor
|
|
|
|
**Version:** 0.1.0 | **Last updated:** 2026-06-13
|
|
|
|
Applies to all contributors and AI agents working in this repo. Where this document and `AGENT-OPERATING-STANDARD.md` conflict on process, the Standard wins; this document wins on code style.
|
|
|
|
---
|
|
|
|
## 1. PHP style
|
|
|
|
- **Standard:** WordPress Coding Standards (PHPCS `ruleset ref="WordPress"`).
|
|
- **Declare:** `declare(strict_types=1);` at the top of every PHP file.
|
|
- **Formatting:** Tabs for indentation (WP standard).
|
|
|
|
## 2. Naming
|
|
|
|
| Concept | Convention | Example |
|
|
|---------|-----------|---------|
|
|
| Class | `PGM_` prefix + PascalCase | `PGM_Cost_Ledger` |
|
|
| Interface | `PGM_` prefix + PascalCase | `PGM_Probe_Provider` |
|
|
| File | `class-pgm-*.php` or `interface-pgm-*.php` | `class-pgm-probe-runner.php` |
|
|
| Option | `pgm_` prefix | `pgm_monthly_budget_usd` |
|
|
| Hook / cron | `pgm_` prefix | `pgm_weekly_probe` |
|
|
| Constant | `PGM_` prefix | `PGM_TARGET_DOMAIN` |
|
|
| wp-config key | `PGM_` prefix | `PGM_OPENROUTER_API_KEY` |
|
|
| Test file | `test-*.php` | `test-citation-detector.php` |
|
|
|
|
## 3. File structure
|
|
|
|
- **One class per file.** Interfaces get their own file.
|
|
- **300-line limit** (enforced by CI). Split at the method boundary when approaching the limit.
|
|
- Autoloader resolves `PGM_Foo_Bar` → `class-pgm-foo-bar.php` via a search across `includes/` subdirectories.
|
|
|
|
## 4. Docblocks
|
|
|
|
Every class must have a preamble docblock:
|
|
```
|
|
/**
|
|
* <One-sentence what>.
|
|
*
|
|
* Who triggers: <which class/hook calls this>.
|
|
* Dependencies: <what this class needs to exist>.
|
|
*
|
|
* @see <cross-reference 1>
|
|
* @see <cross-reference 2>
|
|
* @package PeptideGeoMonitor
|
|
*/
|
|
```
|
|
|
|
Every public method must have:
|
|
- `@param` with type + description.
|
|
- `@return` with type.
|
|
- A sentence listing side effects (DB writes, HTTP calls, option writes).
|
|
|
|
## 5. Security rules
|
|
|
|
- **Sanitize** all input at the boundary (`sanitize_text_field()`, `absint()`, `wp_unslash()`).
|
|
- **Escape** all output at render (`esc_html()`, `esc_url()`, `wp_json_encode()`, `wp_kses_post()`).
|
|
- **Nonce** every admin form action.
|
|
- **Capability** check (`manage_options`) every admin action handler.
|
|
- **No secrets in code** — read from wp-config constants at runtime.
|
|
|
|
## 6. Tests
|
|
|
|
- Tests live in `tests/unit/test-*.php` and are run by the CI `lint-php` job via `php $test`.
|
|
- Each test file `require_once`s `tests/bootstrap.php` and calls `exit( pgm_test_summary() )`.
|
|
- Use `pgm_assert()`, `pgm_assert_equals()`, `pgm_assert_throws()`.
|
|
- Mock HTTP via `$GLOBALS['pgm_test_state']['remote_posts']` (queued responses).
|
|
- No PHPUnit dependency.
|
|
|
|
## 7. Adding a new provider
|
|
|
|
1. Create `includes/providers/class-pgm-{name}-provider.php`.
|
|
2. Implement `PGM_Probe_Provider` (`probe()`, `get_name()`, `is_configured()`).
|
|
3. Add a branch in `PGM_Probe_Runner::resolve_provider()`.
|
|
4. Update `ARCHITECTURE.md` §5 (Providers table).
|
|
5. Add a parse test in `tests/unit/test-provider-parsing.php`.
|
|
|
|
## 8. Adding a new collector/panel pair
|
|
|
|
1. Implement `PGM_Data_Collector` in `includes/collector/`.
|
|
2. Implement `PGM_Dashboard_Panel` in `includes/panel/`.
|
|
3. Register both in `PGM_Plugin::init()` via `PGM_Collector_Registry::instance()`.
|
|
4. Update `ARCHITECTURE.md` §6 (Collector/Panel seam).
|