the method that answers it. * * Registered one by one rather than by handing WP-CLI the whole class, * which would turn every public method into a subcommand — including * `register()` itself, and `wp acid-aeo register` is not a thing anybody * should be able to type. Naming them here also lets `static` keep its * name: it is a reserved word, so the method behind it cannot share it. * * @var array */ private const SUBCOMMANDS = [ 'audit' => 'audit', 'regenerate' => 'regenerate', 'indexnow' => 'indexnow', 'static' => 'static_files', 'export' => 'export', 'import' => 'import', 'citations' => 'citations', 'preview' => 'preview', ]; /** * Registers the commands with WP-CLI. * * @return void */ public function register(): void { if ( ! defined( 'WP_CLI' ) || ! WP_CLI || ! class_exists( 'WP_CLI' ) ) { return; } foreach ( self::SUBCOMMANDS as $name => $method ) { WP_CLI::add_command( 'acid-aeo ' . $name, [ $this, $method ] ); } } /** * Runs the AI readiness audit and prints what it found. * * Exits with status 1 when the score is below 50, so a deployment pipeline * can gate on it. * * ## OPTIONS * * [--fresh] * : Ignore the cached result and measure the site again. * * [--format=] * : Output format. * --- * default: table * options: * - table * - json * --- * * ## EXAMPLES * * # Show the findings as a table. * $ wp acid-aeo audit * * # Re-measure the site and hand the whole result to jq. * $ wp acid-aeo audit --fresh --format=json | jq .score * * @param array $args Positional arguments. * @param array $assoc_args Associative arguments. * @return void */ public function audit( array $args, array $assoc_args ): void { $fresh = (bool) \WP_CLI\Utils\get_flag_value( $assoc_args, 'fresh', false ); $format = (string) \WP_CLI\Utils\get_flag_value( $assoc_args, 'format', 'table' ); // `--fresh` settles which sitemap answers inside the run itself, after // the loopback cache is dropped. $result = Runner::run( $fresh ); $score = (int) ( $result['score'] ?? 0 ); if ( 'json' === $format ) { WP_CLI::line( (string) wp_json_encode( $result, JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE ) ); } else { \WP_CLI\Utils\format_items( 'table', Runner::summary_for_cli( $result ), [ 'id', 'status', 'label', 'message' ] ); WP_CLI::line( sprintf( 'Score: %d/100 (%s)', $score, (string) ( $result['band'] ?? '' ) ) ); } if ( $score < self::FAILING_SCORE ) { if ( 'json' !== $format ) { WP_CLI::warning( __( 'The site scores below 50. Fix the failing checks above.', 'acid-aeo' ) ); } WP_CLI::halt( 1 ); } } /** * Drops every cached file and rebuilds the rewrite rules. * * ## EXAMPLES * * $ wp acid-aeo regenerate * Success: Caches dropped and rewrite rules rebuilt. * * @param array $args Positional arguments. * @param array $assoc_args Associative arguments. * @return void */ public function regenerate( array $args, array $assoc_args ): void { unset( $args, $assoc_args ); Cache::invalidate_all(); Loopback::flush(); flush_rewrite_rules( false ); WP_CLI::success( __( 'Caches dropped and rewrite rules rebuilt.', 'acid-aeo' ) ); } /** * Submits URLs to IndexNow, or prints the submission history. * * ## OPTIONS * * * : What to do. * --- * options: * - submit * - log * --- * * [...] * : URLs to submit. Ignored by `log`. * * [--all] * : Queue every published post of the configured post types, then send the queue. * * ## EXAMPLES * * # Tell IndexNow about two pages. * $ wp acid-aeo indexnow submit https://example.com/a/ https://example.com/b/ * * # Resubmit the whole site, e.g. after rotating the key. * $ wp acid-aeo indexnow submit --all * * # What was sent, and how it went. * $ wp acid-aeo indexnow log * * @param array $args Positional arguments. * @param array $assoc_args Associative arguments. * @return void */ public function indexnow( array $args, array $assoc_args ): void { $action = (string) ( $args[0] ?? '' ); $module = new Modules\IndexNow(); if ( 'log' === $action ) { $this->print_indexnow_log( $module->log() ); return; } if ( 'submit' !== $action ) { WP_CLI::error( $this->unknown_action( $action, 'submit, log' ) ); } if ( ! $module->is_enabled() ) { WP_CLI::error( Modules\IndexNow::switched_off_message() ); } if ( (bool) \WP_CLI\Utils\get_flag_value( $assoc_args, 'all', false ) ) { $queued = $module->submit_all(); $module->flush_queue(); WP_CLI::success( sprintf( /* translators: %d: number of URLs. */ _n( '%d URL was queued and sent to IndexNow.', '%d URLs were queued and sent to IndexNow.', $queued, 'acid-aeo' ), $queued ) ); return; } $urls = array_values( array_filter( array_map( 'strval', array_slice( $args, 1 ) ) ) ); if ( [] === $urls ) { WP_CLI::error( __( 'Pass one or more URLs, or --all to submit every published post.', 'acid-aeo' ) ); } $entry = $module->submit( $urls ); if ( [] === $entry ) { WP_CLI::error( __( 'Nothing was sent. Check that the IndexNow module is configured.', 'acid-aeo' ) ); } $this->print_indexnow_log( [ $entry ] ); if ( 'error' === (string) ( $entry['status'] ?? '' ) ) { WP_CLI::error( (string) ( $entry['message'] ?? __( 'The submission failed.', 'acid-aeo' ) ) ); } WP_CLI::success( sprintf( /* translators: %d: number of URLs. */ _n( '%d URL was sent to IndexNow.', '%d URLs were sent to IndexNow.', count( $urls ), 'acid-aeo' ), count( $urls ) ) ); } /** * Writes the generated files to disk, or removes the ones this plugin wrote. * * Only files carrying the Acid AEO marker are ever overwritten or deleted, * and `robots.txt` is never touched. * * ## OPTIONS * * * : What to do. * --- * options: * - write * - remove * --- * * ## EXAMPLES * * # Publish llms.txt and friends as real files. * $ wp acid-aeo static write * * # Take them off disk again. * $ wp acid-aeo static remove * * @param array $args Positional arguments. * @param array $assoc_args Associative arguments. * @return void */ public function static_files( array $args, array $assoc_args ): void { unset( $assoc_args ); $action = (string) ( $args[0] ?? '' ); $module = new Modules\StaticFiles(); if ( 'write' === $action ) { $this->print_file_result( $module->write_all() ); return; } if ( 'remove' !== $action ) { WP_CLI::error( $this->unknown_action( $action, 'write, remove' ) ); } $this->print_file_result( $module->remove_all() ); } /** * Prints every setting as JSON, or writes it to a file. * * ## OPTIONS * * [--file=] * : Write the export to this path instead of printing it. * * ## EXAMPLES * * $ wp acid-aeo export --file=acid-aeo-settings.json * Success: Settings written to acid-aeo-settings.json. * * @param array $args Positional arguments. * @param array $assoc_args Associative arguments. * @return void */ public function export( array $args, array $assoc_args ): void { unset( $args ); $payload = wp_json_encode( Tools::export(), JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE ); if ( ! is_string( $payload ) ) { WP_CLI::error( __( 'The settings could not be encoded as JSON.', 'acid-aeo' ) ); } $path = (string) \WP_CLI\Utils\get_flag_value( $assoc_args, 'file', '' ); if ( '' === $path ) { WP_CLI::line( $payload ); return; } $filesystem = Filesystem::direct(); if ( null === $filesystem ) { WP_CLI::error( Filesystem::reason() ); } if ( ! $filesystem->put_contents( $path, $payload . "\n", Filesystem::file_mode() ) ) { WP_CLI::error( sprintf( /* translators: %s: file path. */ __( 'The export could not be written to %s.', 'acid-aeo' ), $path ) ); } WP_CLI::success( sprintf( /* translators: %s: file path. */ __( 'Settings written to %s.', 'acid-aeo' ), $path ) ); } /** * Replaces every setting with an export file. * * The file is sanitized against the settings schema on the way in, so an * export from an older version, or one edited by hand, cannot store a * value the settings screen could not have produced. * * ## OPTIONS * * * : Path to a file produced by `wp acid-aeo export`. * * ## EXAMPLES * * $ wp acid-aeo import acid-aeo-settings.json * Success: Settings imported. * * @param array $args Positional arguments. * @param array $assoc_args Associative arguments. * @return void */ public function import( array $args, array $assoc_args ): void { unset( $assoc_args ); $path = (string) ( $args[0] ?? '' ); $filesystem = Filesystem::direct(); if ( null === $filesystem ) { WP_CLI::error( Filesystem::reason() ); } $raw = $filesystem->exists( $path ) ? $filesystem->get_contents( $path ) : false; if ( ! is_string( $raw ) ) { WP_CLI::error( sprintf( /* translators: %s: file path. */ __( '%s could not be read.', 'acid-aeo' ), $path ) ); } $decoded = json_decode( $raw, true ); $settings = is_array( $decoded ) && isset( $decoded['settings'] ) && is_array( $decoded['settings'] ) ? $decoded['settings'] : $decoded; if ( ! is_array( $settings ) || [] === $settings ) { WP_CLI::error( __( 'The file does not contain a settings object.', 'acid-aeo' ) ); } Options::set_all( $settings ); Loopback::flush(); update_option( 'acid_aeo_flush_needed', 1 ); WP_CLI::success( __( 'Settings imported. The rewrite rules are rebuilt on the next request.', 'acid-aeo' ) ); } /** * Reports on tracked AI crawls and referrals, or prunes them. * * ## OPTIONS * * * : What to do. * --- * options: * - stats * - purge * --- * * [--days=] * : Window `stats` reports on, in days. * --- * default: 30 * --- * * [--older-than=] * : `purge` deletes only events older than this many days. Omit it to delete every event. * * ## EXAMPLES * * # Who read the site this week. * $ wp acid-aeo citations stats --days=7 * * # Keep the last 90 days. * $ wp acid-aeo citations purge --older-than=90 * * @param array $args Positional arguments. * @param array $assoc_args Associative arguments. * @return void */ public function citations( array $args, array $assoc_args ): void { $action = (string) ( $args[0] ?? '' ); if ( 'stats' === $action ) { $this->print_citation_stats( (int) \WP_CLI\Utils\get_flag_value( $assoc_args, 'days', 30 ) ); return; } if ( 'purge' !== $action ) { WP_CLI::error( $this->unknown_action( $action, 'stats, purge' ) ); } $older_than = \WP_CLI\Utils\get_flag_value( $assoc_args, 'older-than', null ); $deleted = Store::purge( null !== $older_than ? (int) $older_than : null ); WP_CLI::success( sprintf( /* translators: 1: number of events deleted, 2: number of events left. */ __( '%1$d events deleted, %2$d left.', 'acid-aeo' ), $deleted, Store::count() ) ); } /** * Prints what one of the generated files would say right now. * * Renders through the module, so a file whose module is switched off can * be previewed too — which is exactly when it is worth looking at. * * ## OPTIONS * * * : Which file to render. * --- * options: * - llms * - llms_full * - robots * - humans * - ai_txt * - ai_context * - security * --- * * ## EXAMPLES * * $ wp acid-aeo preview llms * * $ wp acid-aeo preview ai_context | jq .organization * * @param array $args Positional arguments. * @param array $assoc_args Associative arguments. * @return void */ public function preview( array $args, array $assoc_args ): void { unset( $assoc_args ); $file = sanitize_key( (string) ( $args[0] ?? '' ) ); if ( ! in_array( $file, Preview::FILES, true ) ) { WP_CLI::error( $this->unknown_action( $file, implode( ', ', Preview::FILES ) ) ); } $body = Preview::preview_body( $file ); if ( is_wp_error( $body ) ) { WP_CLI::error( $body->get_error_message() ); } WP_CLI::line( rtrim( (string) $body, "\n" ) ); } /** * Prints the outcome of a write or a removal. * * One printer for both, because a write removes things too: a file that is * no longer selected is pruned by the same pass that writes the rest. * * @param array $result Result of `write_all()` or `remove_all()`. * @return void */ private function print_file_result( array $result ): void { $written = is_array( $result['written'] ?? null ) ? $result['written'] : []; $removed = is_array( $result['removed'] ?? null ) ? $result['removed'] : []; $skipped = is_array( $result['skipped'] ?? null ) ? $result['skipped'] : []; $errors = is_array( $result['errors'] ?? null ) ? $result['errors'] : []; foreach ( $written as $path ) { WP_CLI::log( '+ ' . (string) $path ); } foreach ( $removed as $path ) { WP_CLI::log( '- ' . (string) $path ); } foreach ( $skipped as $path => $reason ) { WP_CLI::log( sprintf( '. %s (%s)', (string) $path, (string) $reason ) ); } foreach ( $errors as $path => $reason ) { WP_CLI::warning( sprintf( '%s: %s', (string) $path, (string) $reason ) ); } if ( [] !== $errors ) { WP_CLI::error( sprintf( /* translators: %d: number of files. */ _n( '%d file could not be handled.', '%d files could not be handled.', count( $errors ), 'acid-aeo' ), count( $errors ) ) ); } WP_CLI::success( sprintf( /* translators: 1: number of files written, 2: number removed, 3: number skipped. */ __( '%1$d written, %2$d removed, %3$d skipped.', 'acid-aeo' ), count( $written ), count( $removed ), count( $skipped ) ) ); } /** * Prints the IndexNow submission history as a table. * * @param array> $log Log entries, newest first. * @return void */ private function print_indexnow_log( array $log ): void { $rows = []; foreach ( $log as $entry ) { if ( ! is_array( $entry ) ) { continue; } $rows[] = [ 'time' => gmdate( 'Y-m-d H:i:s', (int) ( $entry['time'] ?? 0 ) ), 'count' => (string) ( $entry['count'] ?? 0 ), 'status' => (string) ( $entry['status'] ?? '' ), 'message' => (string) ( $entry['message'] ?? '' ), ]; } if ( [] === $rows ) { WP_CLI::log( __( 'Nothing has been submitted yet.', 'acid-aeo' ) ); return; } \WP_CLI\Utils\format_items( 'table', $rows, [ 'time', 'count', 'status', 'message' ] ); } /** * Prints the citation totals and the busiest agents. * * @param int $days Window in days. * @return void */ private function print_citation_stats( int $days ): void { $stats = Store::stats( $days ); $totals = is_array( $stats['totals'] ?? null ) ? $stats['totals'] : []; WP_CLI::log( sprintf( /* translators: 1: number of days, 2: number of crawls, 3: number of referrals. */ __( 'Last %1$d days: %2$d crawls, %3$d referrals.', 'acid-aeo' ), $days, (int) ( $totals['crawl'] ?? 0 ), (int) ( $totals['referral'] ?? 0 ) ) ); $rows = []; foreach ( is_array( $stats['by_agent'] ?? null ) ? $stats['by_agent'] : [] as $row ) { if ( is_array( $row ) ) { $rows[] = [ 'agent' => (string) ( $row['agent'] ?? '' ), 'type' => (string) ( $row['type'] ?? '' ), 'count' => (string) ( $row['count'] ?? 0 ), ]; } } if ( [] !== $rows ) { \WP_CLI\Utils\format_items( 'table', $rows, [ 'agent', 'type', 'count' ] ); } } /** * The message for an action this command does not know. * * @param string $action What the user typed. * @param string $expected Comma separated list of what it could have been. * @return string Translated message. */ private function unknown_action( string $action, string $expected ): string { return sprintf( /* translators: 1: what the user typed, 2: comma separated list of valid values. */ __( '"%1$s" is not one of: %2$s.', 'acid-aeo' ), $action, $expected ); } }