Files

peptiderepo ca1a41f6f9 feat: peptide-geo-monitor v0.1.0 — AI-visibility dashboard

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

2026-06-13 08:18:56 +00:00

3.2 KiB

Raw Blame History

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_onces 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

Create includes/providers/class-pgm-{name}-provider.php.
Implement PGM_Probe_Provider (probe(), get_name(), is_configured()).
Add a branch in PGM_Probe_Runner::resolve_provider().
Update ARCHITECTURE.md §5 (Providers table).
Add a parse test in tests/unit/test-provider-parsing.php.

8. Adding a new collector/panel pair

Implement PGM_Data_Collector in includes/collector/.
Implement PGM_Dashboard_Panel in includes/panel/.
Register both in PGM_Plugin::init() via PGM_Collector_Registry::instance().
Update ARCHITECTURE.md §6 (Collector/Panel seam).

3.2 KiB Raw Blame History