'blocks/list-block-templates', 'args' => array( 'label' => __( 'List Block Templates', 'acrossai-abilities-manager' ), 'description' => __( 'Lists block templates across the database (wp_template), the active theme\'s /templates/*.html, the parent theme, and installed plugin /templates dirs. Filter by source, theme_type, plugin_slug, or exact slug.', 'acrossai-abilities-manager' ), 'category' => 'acrossai-block', 'execute_callback' => array( $this, 'execute' ), 'permission_callback' => static function (): bool { return current_user_can( 'manage_options' ); }, 'input_schema' => array( 'type' => 'object', 'properties' => array( 'source' => array( 'type' => 'string', 'enum' => array( 'all', 'db', 'theme', 'plugin' ), 'default' => 'all', ), 'theme_type' => array( 'type' => 'string', 'enum' => array( '', 'child', 'parent', 'theme' ), 'default' => '', ), 'theme_slug' => array( 'type' => 'string', 'default' => '', 'description' => __( 'Restrict file scan to a specific theme folder. Defaults to active theme.', 'acrossai-abilities-manager' ), ), 'plugin_slug' => array( 'type' => 'string', 'default' => '', 'description' => __( 'Restrict plugin scan to one plugin folder name.', 'acrossai-abilities-manager' ), ), 'slug' => array( 'type' => 'string', 'default' => '', 'description' => __( 'Optional exact slug to look up.', 'acrossai-abilities-manager' ), ), 'include_content' => array( 'type' => 'boolean', 'default' => false, ), ), 'additionalProperties' => false, ), 'output_schema' => array( 'type' => 'object', 'properties' => array( 'success' => array( 'type' => 'boolean' ), 'templates' => array( 'type' => 'array' ), 'total' => array( 'type' => 'integer' ), 'theme' => array( 'type' => 'string' ), 'message' => array( 'type' => 'string' ), ), 'required' => array( 'success' ), 'additionalProperties' => false, ), 'meta' => array( 'acrossai' => array( 'tab_group' => 'appearance', 'sub_group' => 'templates', 'sub_group_label' => __( 'Templates', 'acrossai-abilities-manager' ), ), 'show_in_rest' => true, 'mcp' => array( 'public' => false, 'type' => 'tool', ), 'annotations' => array( 'readonly' => true, 'destructive' => false, 'idempotent' => true, ), ), ), ); } /** * Feature 095 follow-up — hint that known-slug reads should skip the * cross-source enumeration. * * @return array> */ protected function suggested_abilities(): array { return array( array( 'slug' => 'blocks/read-block-template', 'reason' => __( 'If you already know the template slug, a targeted read-block-template is far cheaper than enumerating templates across every source (db + theme + plugin). List is for discovery; read is for retrieval.', 'acrossai-abilities-manager' ), 'saves' => __( '~5-15x fewer tokens for known-slug reads', 'acrossai-abilities-manager' ), ), ); } /** * Execute the ability. * * @param array $input Ability input payload. * @return array */ public function execute( array $input = array() ): array { $source = sanitize_text_field( $input['source'] ?? 'all' ); $theme_type = sanitize_text_field( $input['theme_type'] ?? '' ); $theme_slug = sanitize_key( $input['theme_slug'] ?? '' ); $plugin_slug = sanitize_key( $input['plugin_slug'] ?? '' ); $slug_filter = sanitize_title( $input['slug'] ?? '' ); $include_content = ! empty( $input['include_content'] ); $active_theme = '' !== $theme_slug ? $theme_slug : (string) get_stylesheet(); $rows = array(); if ( 'all' === $source || 'db' === $source ) { $rows = array_merge( $rows, $this->collect_db( $active_theme, $slug_filter, $include_content ) ); } if ( 'all' === $source || 'theme' === $source ) { $rows = array_merge( $rows, $this->collect_theme( $theme_type, $theme_slug, $slug_filter, $include_content ) ); } if ( 'all' === $source || 'plugin' === $source ) { $rows = array_merge( $rows, $this->collect_plugins( $plugin_slug, $slug_filter, $include_content ) ); } $rows = $this->mark_effective( $rows ); return array( 'success' => true, 'templates' => $rows, 'total' => count( $rows ), 'theme' => $active_theme, ); } /** * Collect db. * * @param string $theme * @param string $slug_filter * @param bool $include_content * @return array */ private function collect_db( string $theme, string $slug_filter, bool $include_content ): array { $posts = Template_Db::list_all( $theme, 500 ); $rows = array(); foreach ( $posts as $post ) { if ( '' !== $slug_filter && (string) $post->post_name !== $slug_filter ) { continue; } $row = Template_Db::to_row( $post ); if ( ! $include_content ) { unset( $row['content'] ); } $rows[] = $row; } return $rows; } /** * Collect theme. * * @param string $theme_type * @param string $theme_slug * @param string $slug_filter * @param bool $include_content * @return array */ private function collect_theme( string $theme_type, string $theme_slug, string $slug_filter, bool $include_content ): array { $rows = array(); $child_dir = Template_File::get_child_theme_dir(); $is_child = null !== $child_dir; if ( '' === $theme_type || 'child' === $theme_type ) { if ( $is_child ) { $rows = array_merge( $rows, $this->scan_dir( $child_dir, 'child', basename( $child_dir ), $slug_filter, $include_content ) ); } } if ( '' === $theme_type || 'parent' === $theme_type || 'theme' === $theme_type ) { $parent_dir = '' !== $theme_slug ? get_theme_root() . '/' . $theme_slug : Template_File::get_parent_theme_dir(); $tt = $is_child ? 'parent' : 'theme'; $rows = array_merge( $rows, $this->scan_dir( $parent_dir, $tt, basename( $parent_dir ), $slug_filter, $include_content ) ); } return $rows; } /** * Collect plugins. * * @param string $plugin_slug * @param string $slug_filter * @param bool $include_content * @return array */ private function collect_plugins( string $plugin_slug, string $slug_filter, bool $include_content ): array { $rows = array(); foreach ( Template_File::scan_plugins_with_templates() as $plugin ) { if ( '' !== $plugin_slug && $plugin['slug'] !== $plugin_slug ) { continue; } $files = glob( $plugin['path'] . '/*.html' ); if ( ! is_array( $files ) ) { continue; } foreach ( $files as $file ) { $bare = preg_replace( '/\.html$/i', '', basename( $file ) ); if ( '' !== $slug_filter && $bare !== $slug_filter ) { continue; } $rows[] = $this->file_row( 'plugin', '', $bare, $file, $plugin['slug'], (bool) $plugin['active'], $include_content ); } } return $rows; } /** * Scan dir. * * @param string $container * @param string $theme_type * @param string $theme * @param string $slug_filter * @param bool $include_content * @return array */ private function scan_dir( string $container, string $theme_type, string $theme, string $slug_filter, bool $include_content ): array { $rows = array(); $dir = Template_File::templates_dir( $container ); if ( ! is_dir( $dir ) ) { return $rows; } $files = glob( $dir . '/*.html' ); if ( ! is_array( $files ) ) { return $rows; } foreach ( $files as $file ) { $bare = preg_replace( '/\.html$/i', '', basename( $file ) ); if ( '' !== $slug_filter && $bare !== $slug_filter ) { continue; } $rows[] = $this->file_row( 'theme', $theme_type, $bare, $file, $theme, true, $include_content ); } return $rows; } /** * File row. * * @param string $source * @param string $theme_type * @param string $slug * @param string $path * @param string $owner * @param bool $active * @param bool $include_content * @return array */ private function file_row( string $source, string $theme_type, string $slug, string $path, string $owner, bool $active, bool $include_content ): array { $row = array( 'source' => $source, 'slug' => (string) $slug, 'path' => $path, 'writable' => is_writable( $path ), ); if ( 'theme' === $source ) { $row['theme'] = $owner; $row['theme_type'] = $theme_type; $row['full_slug'] = $owner . '//' . $slug; } else { $row['plugin'] = $owner; $row['plugin_active'] = $active; } if ( $include_content ) { $contents = Template_File::read_file( $path ); if ( ! is_wp_error( $contents ) ) { $row['content'] = $contents; } } return $row; } /** * Marks one row per slug as "effective" — the location WordPress actually * serves at runtime (DB → child → parent → plugin). */ private function mark_effective( array $rows ): array { $by_slug = array(); foreach ( $rows as $row ) { $slug = (string) ( $row['slug'] ?? '' ); if ( '' === $slug ) { continue; } $by_slug[ $slug ][] = $row; } $priority = static function ( array $row ): int { if ( 'db' === ( $row['source'] ?? '' ) ) { return 0; } if ( 'theme' === ( $row['source'] ?? '' ) ) { return 'child' === ( $row['theme_type'] ?? '' ) ? 1 : 2; } if ( 'plugin' === ( $row['source'] ?? '' ) ) { return 3; } return 4; }; $out = array(); foreach ( $by_slug as $candidates ) { usort( $candidates, static function ( $a, $b ) use ( $priority ): int { return $priority( $a ) <=> $priority( $b ); } ); $winner = $candidates[0]; foreach ( $candidates as $i => $candidate ) { $candidate['effective'] = ( $i === 0 ); if ( false === $candidate['effective'] ) { $candidate['overridden_by'] = ( $winner['source'] ?? '' ) . ( isset( $winner['theme_type'] ) ? ':' . $winner['theme_type'] : '' ); } $out[] = $candidate; } } return $out; } }