laipower/wp-content/plugins/jetpack-protect/jetpack_vendor/automattic/jetpack-my-jetpack/AGENTS.md

AGENTS.md

This file provides guidance to AI coding agents when working with code in this repository.

Essential Documentation

Primary Reference: My Jetpack README.md - Complete architecture, development commands, and project structure

Additional Resources:

• Data Layer Documentation - API hooks and data management
• Automated Testing Overview - Testing patterns and strategies
• Coding Standards & Guidelines - Development best practices
• Jetpack HTTP API Documentation - REST API patterns
• Jetpack CLI Documentation - CLI commands and workflows

Project Overview

My Jetpack is a centralized WordPress admin page providing a unified interface for managing Jetpack products and services. Key architectural components:

• PHP Backend: Product management system, REST API endpoints (jetpack/v4/my-jetpack namespace)
• React Frontend: TypeScript application with React Router and TanStack React Query for data management
• Product System: Standardized Product class interface with status constants for lifecycle management

Code Patterns & Examples

PHP Patterns

Product Class Structure

<?php
namespace Automattic\Jetpack\My_Jetpack;

class My_New_Product extends Product {
    
    // Required static methods for product identification
    public static function get_name() {
        return 'my-new-product';
    }
    
    public static function get_title() {
        return __( 'My New Product', 'jetpack-my-jetpack' );
    }
    
    public static function get_description() {
        return __( 'Product description', 'jetpack-my-jetpack' );
    }
    
    // Core method - determines product status
    public function get_status() {
        // Use constants from Products class
        if ( ! $this->is_plugin_installed() ) {
            return self::STATUS_PLUGIN_ABSENT;
        }
        
        if ( ! $this->is_active() ) {
            return self::STATUS_INACTIVE;
        }
        
        return self::STATUS_ACTIVE;
    }
    
    // Optional: provide management URL
    public static function get_manage_url() {
        return admin_url( 'admin.php?page=my-product' );
    }
    
    // Override as needed: pricing, features, etc.
}

REST API Endpoint Pattern

For comprehensive REST API documentation and patterns, see Jetpack HTTP API Documentation.

My Jetpack endpoints follow the standard pattern:

• Namespace: jetpack/v4/my-jetpack
• Base: Extend WP_REST_Controller
• Registration: Via Initializer::register_rest_endpoints()

Product Status Constants

// Status constants are defined in class-products.php
// Use Products::STATUS_* constants instead of magic strings
// Common patterns: active, inactive, needs_plan, plugin_absent, etc.
// Check class-products.php for current complete list

React Patterns

Component Structure

import { useState, useEffect } from 'react';
import { __ } from '@wordpress/i18n';
import { useConnection } from '@automattic/jetpack-connection';
import styles from './style.module.scss';

const MyComponent = ({ productSlug, onAction }) => {
    const [isLoading, setIsLoading] = useState(false);
    const { isRegistered, isUserConnected } = useConnection();
    
    const handleAction = async () => {
        setIsLoading(true);
        try {
            await onAction();
        } finally {
            setIsLoading(false);
        }
    };
    
    return (
        <div className={styles.container}>
            <h2>{__('My Component', 'jetpack-my-jetpack')}</h2>
            <button 
                onClick={handleAction}
                disabled={isLoading}
                className={styles.button}
            >
                {isLoading ? __('Loading...', 'jetpack-my-jetpack') : __('Action', 'jetpack-my-jetpack')}
            </button>
        </div>
    );
};

export default MyComponent;

Product Component Pattern

import { useProduct } from '../hooks/use-product';

const ProductCard = ({ slug }) => {
    const { product, isLoading, error, activate, deactivate } = useProduct(slug);
    
    if (isLoading) return <LoadingSpinner />;
    if (error) return <ErrorMessage error={error} />;
    
    return (
        <div className={styles.productCard}>
            <h3>{product.title}</h3>
            <p>{product.description}</p>
            <ActionButton 
                status={product.status}
                onActivate={activate}
                onDeactivate={deactivate}
            />
        </div>
    );
};

Development Quick Reference

Key Technologies

Check package.json for current versions:

• React with TypeScript
• Data Management: @tanstack/react-query for server state
• Routing: react-router
• Charts: @automattic/charts (workspace package) for data visualization
• Styling: Sass modules with CSS Modules
• Testing: Jest with React Testing Library

TanStack Query Integration

Base Hook: useSimpleQuery - Wrapper around TanStack Query for common patterns

Styling Architecture

Sass Modules: .module.scss files with CSS Modules Base Styles: @automattic/jetpack-base-styles for common patterns Naming Convention: BEM methodology in SCSS modules

Key Style Files:

• _inc/style.module.scss: Main application styles
• Component-specific: component-name/style.module.scss

GitHub CLI for PR Management

When working with pull requests (e.g., #44191), use the GitHub CLI for efficient review and management:

gh pr view 44191                    # View PR details and description
gh pr view 44191 --comments         # View PR with all comments
gh pr diff 44191                    # View the diff/changes

Testing & Integration

Testing: PHPUnit for PHP, Jest + React Testing Library for JavaScript Integration: WordPress.com connection via @automattic/jetpack-connection, licensing via @automattic/jetpack-licensing Workflows: See README.md for adding products, API development, and feature implementation