@mytechtoday/augment-extensions 0.1.1 → 0.2.0

package/augment-extensions/domain-rules/wordpress/rules/directory-structure.md

@@ -0,0 +1,270 @@
+# WordPress Directory Structure Patterns
+
+## Overview
+
+This document defines the standard directory structures for WordPress projects: full installations, themes, plugins, and blocks.
+
+## Standard WordPress Installation
+
+### Complete Structure
+
+```
+wordpress/
+├── wp-admin/                    # WordPress admin area
+│   ├── css/
+│   ├── images/
+│   ├── includes/
+│   ├── js/
+│   ├── maint/
+│   ├── network/
+│   ├── user/
+│   └── *.php                    # Admin pages
+├── wp-content/                  # User content (themes, plugins, uploads)
+│   ├── themes/                  # Themes directory
+│   │   ├── twentytwentyfour/   # Default theme
+│   │   └── [custom-theme]/     # Custom themes
+│   ├── plugins/                 # Plugins directory
+│   │   ├── akismet/
+│   │   ├── hello.php
+│   │   └── [custom-plugin]/    # Custom plugins
+│   ├── mu-plugins/              # Must-use plugins (auto-loaded)
+│   ├── uploads/                 # Media uploads
+│   │   └── [year]/
+│   │       └── [month]/
+│   ├── languages/               # Translation files
+│   └── upgrade/                 # Temporary upgrade files
+├── wp-includes/                 # WordPress core files
+│   ├── blocks/
+│   ├── certificates/
+│   ├── css/
+│   ├── customize/
+│   ├── fonts/
+│   ├── images/
+│   ├── js/
+│   ├── pomo/
+│   ├── rest-api/
+│   ├── theme-compat/
+│   ├── widgets/
+│   └── *.php                    # Core PHP files
+├── .htaccess                    # Apache configuration
+├── index.php                    # Main entry point
+├── license.txt                  # GPL license
+├── readme.html                  # WordPress readme
+├── wp-activate.php              # Multisite activation
+├── wp-blog-header.php           # Blog header loader
+├── wp-comments-post.php         # Comment handler
+├── wp-config.php                # WordPress configuration (CRITICAL)
+├── wp-config-sample.php         # Sample configuration
+├── wp-cron.php                  # Cron handler
+├── wp-links-opml.php            # OPML export
+├── wp-load.php                  # Bootstrap loader
+├── wp-login.php                 # Login page
+├── wp-mail.php                  # Email handler
+├── wp-settings.php              # Settings loader
+├── wp-signup.php                # Multisite signup
+├── wp-trackback.php             # Trackback handler
+└── xmlrpc.php                   # XML-RPC handler
+```
+
+### Key Directories
+
+**wp-admin/**
+- WordPress administration interface
+- DO NOT modify core files
+- Use hooks and filters instead
+
+**wp-content/**
+- User-generated content
+- Safe to modify
+- Version control this directory
+
+**wp-includes/**
+- WordPress core library
+- DO NOT modify
+- Use plugins/themes for customization
+
+## Theme Structure
+
+### Classic Theme
+
+```
+theme-name/
+├── style.css                    # Required: Theme stylesheet with header
+├── functions.php                # Required: Theme functions
+├── index.php                    # Required: Main template
+├── header.php                   # Header template
+├── footer.php                   # Footer template
+├── sidebar.php                  # Sidebar template
+├── single.php                   # Single post template
+├── page.php                     # Page template
+├── archive.php                  # Archive template
+├── category.php                 # Category archive
+├── tag.php                      # Tag archive
+├── author.php                   # Author archive
+├── date.php                     # Date archive
+├── search.php                   # Search results
+├── 404.php                      # 404 error page
+├── comments.php                 # Comments template
+├── front-page.php               # Front page template
+├── home.php                     # Blog home template
+├── attachment.php               # Attachment template
+├── image.php                    # Image attachment
+├── template-parts/              # Reusable template parts
+│   ├── content.php
+│   ├── content-single.php
+│   └── content-page.php
+├── inc/                         # Include files
+│   ├── customizer.php
+│   ├── template-tags.php
+│   └── template-functions.php
+├── assets/                      # Theme assets
+│   ├── css/
+│   │   ├── main.css
+│   │   └── editor-style.css
+│   ├── js/
+│   │   ├── main.js
+│   │   └── customizer.js
+│   └── images/
+│       └── *.png, *.jpg, *.svg
+├── languages/                   # Translation files
+│   └── theme-slug.pot
+├── screenshot.png               # Theme screenshot (880x660px)
+└── readme.txt                   # Theme documentation
+```
+
+### Block Theme (FSE)
+
+```
+theme-name/
+├── style.css                    # Required: Theme stylesheet with header
+├── functions.php                # Theme functions (minimal)
+├── theme.json                   # Required: Theme configuration
+├── templates/                   # Required: Block templates
+│   ├── index.html              # Required: Main template
+│   ├── single.html             # Single post
+│   ├── page.html               # Page
+│   ├── archive.html            # Archive
+│   ├── search.html             # Search results
+│   ├── 404.html                # 404 error
+│   ├── front-page.html         # Front page
+│   └── home.html               # Blog home
+├── parts/                       # Template parts
+│   ├── header.html
+│   ├── footer.html
+│   ├── sidebar.html
+│   └── comments.html
+├── patterns/                    # Block patterns
+│   ├── hero.php
+│   ├── call-to-action.php
+│   └── testimonials.php
+├── assets/                      # Theme assets
+│   ├── css/
+│   ├── js/
+│   └── images/
+├── inc/                         # Include files
+│   └── block-patterns.php
+├── languages/                   # Translation files
+├── screenshot.png               # Theme screenshot
+└── readme.txt                   # Theme documentation
+```
+
+## Plugin Structure
+
+### Standard Plugin
+
+```
+plugin-name/
+├── plugin-name.php              # Required: Main plugin file with header
+├── uninstall.php                # Cleanup on uninstall
+├── readme.txt                   # WordPress.org readme
+├── LICENSE                      # License file
+├── includes/                    # Core functionality
+│   ├── class-plugin-name.php
+│   ├── class-loader.php
+│   ├── class-i18n.php
+│   └── functions.php
+├── admin/                       # Admin-specific functionality
+│   ├── class-admin.php
+│   ├── partials/
+│   │   └── admin-display.php
+│   ├── css/
+│   │   └── admin.css
+│   └── js/
+│       └── admin.js
+├── public/                      # Public-facing functionality
+│   ├── class-public.php
+│   ├── partials/
+│   │   └── public-display.php
+│   ├── css/
+│   │   └── public.css
+│   └── js/
+│       └── public.js
+├── assets/                      # Shared assets
+│   ├── images/
+│   └── fonts/
+├── languages/                   # Translation files
+│   └── plugin-slug.pot
+└── tests/                       # PHPUnit tests
+    ├── bootstrap.php
+    └── test-*.php
+```
+
+### Block Plugin
+
+```
+block-plugin/
+├── plugin-name.php              # Main plugin file
+├── block.json                   # Block metadata
+├── package.json                 # Build dependencies
+├── src/                         # Source files
+│   ├── index.js                # Block registration
+│   ├── edit.js                 # Editor component
+│   ├── save.js                 # Save function
+│   ├── style.scss              # Frontend styles
+│   └── editor.scss             # Editor styles
+├── build/                       # Compiled files (gitignored)
+│   ├── index.js
+│   ├── index.asset.php
+│   ├── style-index.css
+│   └── index.css
+└── languages/
+```
+
+## Gutenberg Block Development
+
+### Standalone Block
+
+```
+block-name/
+├── block.json                   # Block metadata
+├── package.json                 # Dependencies
+├── src/                         # Source files
+│   ├── index.js
+│   ├── edit.js
+│   ├── save.js
+│   ├── style.scss
+│   └── editor.scss
+├── build/                       # Build output
+└── readme.md
+```
+
+## Best Practices
+
+### DO
+
+✅ Keep themes in `wp-content/themes/`
+✅ Keep plugins in `wp-content/plugins/`
+✅ Use `mu-plugins/` for critical plugins
+✅ Organize assets in dedicated directories
+✅ Use `inc/` or `includes/` for PHP includes
+✅ Separate admin and public code
+✅ Use `languages/` for translations
+
+### DON'T
+
+❌ Modify `wp-admin/` or `wp-includes/`
+❌ Store uploads outside `wp-content/uploads/`
+❌ Mix theme and plugin code
+❌ Put sensitive data in public directories
+❌ Hardcode paths (use WordPress functions)
+

package/augment-extensions/domain-rules/wordpress/rules/file-patterns.md

@@ -0,0 +1,423 @@
+# WordPress File Patterns
+
+## Overview
+
+This document defines key WordPress file patterns, their purposes, and usage guidelines.
+
+## Theme Files
+
+### Required Files
+
+#### style.css
+**Purpose**: Theme stylesheet and metadata  
+**Location**: Theme root  
+**Required**: Yes
+
+**Structure**:
+```css
+/*
+Theme Name: Twenty Twenty-Four
+Theme URI: https://wordpress.org/themes/twentytwentyfour/
+Author: the WordPress team
+Author URI: https://wordpress.org
+Description: A modern block theme
+Requires at least: 6.4
+Tested up to: 6.4
+Requires PHP: 7.0
+Version: 1.0
+License: GNU General Public License v2 or later
+License URI: http://www.gnu.org/licenses/gpl-2.0.html
+Text Domain: twentytwentyfour
+Tags: blog, one-column, custom-colors, custom-menu, editor-style
+*/
+
+/* Theme styles go here */
+```
+
+**Key Points**:
+- Must be in theme root
+- Header comment is required
+- Contains theme metadata
+- Can contain CSS or be empty (if using separate CSS files)
+
+#### functions.php
+**Purpose**: Theme functions and hooks  
+**Location**: Theme root  
+**Required**: Yes (recommended)
+
+**Common Uses**:
+```php
+<?php
+// Theme setup
+function mytheme_setup() {
+    // Add theme support
+    add_theme_support( 'title-tag' );
+    add_theme_support( 'post-thumbnails' );
+    add_theme_support( 'html5', array( 'search-form', 'comment-form' ) );
+    
+    // Register menus
+    register_nav_menus( array(
+        'primary' => __( 'Primary Menu', 'mytheme' ),
+        'footer'  => __( 'Footer Menu', 'mytheme' ),
+    ) );
+}
+add_action( 'after_setup_theme', 'mytheme_setup' );
+
+// Enqueue scripts and styles
+function mytheme_scripts() {
+    wp_enqueue_style( 'mytheme-style', get_stylesheet_uri() );
+    wp_enqueue_script( 'mytheme-script', get_template_directory_uri() . '/js/main.js', array(), '1.0', true );
+}
+add_action( 'wp_enqueue_scripts', 'mytheme_scripts' );
+```
+
+#### index.php
+**Purpose**: Main template fallback  
+**Location**: Theme root  
+**Required**: Yes (classic themes)
+
+**Template Hierarchy**: Lowest priority fallback for all template types
+
+### Block Theme Files
+
+#### theme.json
+**Purpose**: Theme configuration for block themes  
+**Location**: Theme root  
+**Required**: Yes (block themes)
+
+**Structure**:
+```json
+{
+  "$schema": "https://schemas.wp.org/trunk/theme.json",
+  "version": 2,
+  "settings": {
+    "color": {
+      "palette": [
+        {
+          "slug": "primary",
+          "color": "#0073aa",
+          "name": "Primary"
+        }
+      ]
+    },
+    "typography": {
+      "fontSizes": [
+        {
+          "slug": "small",
+          "size": "14px",
+          "name": "Small"
+        }
+      ]
+    }
+  },
+  "styles": {
+    "color": {
+      "background": "#ffffff",
+      "text": "#000000"
+    }
+  }
+}
+```
+
+#### templates/*.html
+**Purpose**: Block templates  
+**Location**: `templates/` directory  
+**Required**: `index.html` is required
+
+**Common Templates**:
+- `index.html` - Main template (required)
+- `single.html` - Single post
+- `page.html` - Page
+- `archive.html` - Archive
+- `404.html` - 404 error
+- `front-page.html` - Front page
+- `home.html` - Blog home
+
+#### parts/*.html
+**Purpose**: Reusable template parts  
+**Location**: `parts/` directory  
+**Required**: No
+
+**Common Parts**:
+- `header.html` - Site header
+- `footer.html` - Site footer
+- `sidebar.html` - Sidebar
+- `comments.html` - Comments section
+
+### Classic Theme Templates
+
+#### Template Hierarchy Files
+
+**Single Post**:
+- `single-{post-type}-{slug}.php`
+- `single-{post-type}.php`
+- `single.php`
+- `singular.php`
+- `index.php`
+
+**Page**:
+- `page-{slug}.php`
+- `page-{id}.php`
+- `page.php`
+- `singular.php`
+- `index.php`
+
+**Archive**:
+- `archive-{post-type}.php`
+- `archive.php`
+- `index.php`
+
+**Category**:
+- `category-{slug}.php`
+- `category-{id}.php`
+- `category.php`
+- `archive.php`
+- `index.php`
+
+**Tag**:
+- `tag-{slug}.php`
+- `tag-{id}.php`
+- `tag.php`
+- `archive.php`
+- `index.php`
+
+**Author**:
+- `author-{nicename}.php`
+- `author-{id}.php`
+- `author.php`
+- `archive.php`
+- `index.php`
+
+**Date**:
+- `date.php`
+- `archive.php`
+- `index.php`
+
+**Search**:
+- `search.php`
+- `index.php`
+
+**404**:
+- `404.php`
+- `index.php`
+
+**Front Page**:
+- `front-page.php`
+- `home.php`
+- `index.php`
+
+## Plugin Files
+
+### Main Plugin File
+
+**Purpose**: Plugin entry point with header  
+**Location**: Plugin root  
+**Naming**: `plugin-name.php` or `plugin-slug.php`
+
+**Structure**:
+```php
+<?php
+/**
+ * Plugin Name: My Plugin
+ * Plugin URI: https://example.com/my-plugin
+ * Description: Plugin description
+ * Version: 1.0.0
+ * Requires at least: 6.0
+ * Requires PHP: 7.4
+ * Author: Author Name
+ * Author URI: https://example.com
+ * License: GPL v2 or later
+ * License URI: https://www.gnu.org/licenses/gpl-2.0.html
+ * Text Domain: my-plugin
+ * Domain Path: /languages
+ */
+
+// Prevent direct access
+if ( ! defined( 'ABSPATH' ) ) {
+    exit;
+}
+
+// Plugin code here
+```
+
+### uninstall.php
+
+**Purpose**: Cleanup on plugin deletion  
+**Location**: Plugin root  
+**Required**: No (recommended)
+
+**Structure**:
+```php
+<?php
+// If uninstall not called from WordPress, exit
+if ( ! defined( 'WP_UNINSTALL_PLUGIN' ) ) {
+    exit;
+}
+
+// Delete options
+delete_option( 'my_plugin_option' );
+
+// Delete custom tables
+global $wpdb;
+$wpdb->query( "DROP TABLE IF EXISTS {$wpdb->prefix}my_plugin_table" );
+
+// Clear scheduled hooks
+wp_clear_scheduled_hook( 'my_plugin_cron' );
+```
+
+## Block Files
+
+### block.json
+
+**Purpose**: Block metadata  
+**Location**: Block root  
+**Required**: Yes (blocks)
+
+**Structure**:
+```json
+{
+  "$schema": "https://schemas.wp.org/trunk/block.json",
+  "apiVersion": 2,
+  "name": "namespace/block-name",
+  "title": "Block Title",
+  "category": "widgets",
+  "icon": "smiley",
+  "description": "Block description",
+  "keywords": ["keyword1", "keyword2"],
+  "version": "1.0.0",
+  "textdomain": "block-slug",
+  "attributes": {
+    "content": {
+      "type": "string",
+      "source": "html",
+      "selector": "p"
+    }
+  },
+  "supports": {
+    "html": false,
+    "align": true
+  },
+  "example": {
+    "attributes": {
+      "content": "Example content"
+    }
+  },
+  "editorScript": "file:./index.js",
+  "editorStyle": "file:./index.css",
+  "style": "file:./style-index.css"
+}
+```
+
+## Configuration Files
+
+### wp-config.php
+
+**Purpose**: WordPress configuration  
+**Location**: WordPress root  
+**Required**: Yes
+
+**CRITICAL SAFETY RULES**:
+- ❌ NEVER modify database credentials
+- ❌ NEVER commit to version control
+- ✅ READ ONLY for AI operations
+- ✅ Only modify debug settings or add constants
+
+**Common Constants**:
+```php
+// Database (READ ONLY)
+define( 'DB_NAME', 'database_name' );
+define( 'DB_USER', 'database_user' );
+define( 'DB_PASSWORD', 'database_password' );
+define( 'DB_HOST', 'localhost' );
+
+// Debug (SAFE TO MODIFY)
+define( 'WP_DEBUG', true );
+define( 'WP_DEBUG_LOG', true );
+define( 'WP_DEBUG_DISPLAY', false );
+
+// Custom constants (SAFE TO ADD)
+define( 'CUSTOM_CONSTANT', 'value' );
+```
+
+### .htaccess
+
+**Purpose**: Apache configuration  
+**Location**: WordPress root  
+**Required**: No (Apache only)
+
+**Common Rules**:
+```apache
+# BEGIN WordPress
+<IfModule mod_rewrite.c>
+RewriteEngine On
+RewriteBase /
+RewriteRule ^index\.php$ - [L]
+RewriteCond %{REQUEST_FILENAME} !-f
+RewriteCond %{REQUEST_FILENAME} !-d
+RewriteRule . /index.php [L]
+</IfModule>
+# END WordPress
+```
+
+### composer.json
+
+**Purpose**: PHP dependency management  
+**Location**: Theme/plugin root  
+**Required**: No (if using Composer)
+
+### package.json
+
+**Purpose**: JavaScript dependency management  
+**Location**: Theme/plugin/block root  
+**Required**: No (if using npm/yarn)
+
+**Block Development**:
+```json
+{
+  "name": "block-name",
+  "version": "1.0.0",
+  "scripts": {
+    "build": "wp-scripts build",
+    "start": "wp-scripts start"
+  },
+  "devDependencies": {
+    "@wordpress/scripts": "^26.0.0"
+  }
+}
+```
+
+## Translation Files
+
+### .pot (Template)
+**Purpose**: Translation template  
+**Location**: `languages/` directory  
+**Generated**: Yes (using WP-CLI or tools)
+
+### .po (Translation)
+**Purpose**: Human-readable translations  
+**Location**: `languages/` directory
+
+### .mo (Compiled)
+**Purpose**: Machine-readable translations  
+**Location**: `languages/` directory  
+**Generated**: Yes (from .po files)
+
+## Best Practices
+
+### File Naming
+
+✅ Use lowercase with hyphens: `my-plugin.php`  
+✅ Match text domain: `my-plugin` → `my-plugin.php`  
+✅ Be descriptive: `class-admin-settings.php`  
+❌ Avoid spaces: `My Plugin.php`  
+❌ Avoid underscores in slugs: `my_plugin.php`
+
+### File Organization
+
+✅ Group related files in directories  
+✅ Separate admin and public code  
+✅ Use `inc/` or `includes/` for PHP includes  
+✅ Keep assets in `assets/` or dedicated directories  
+❌ Don't mix concerns in single files  
+❌ Don't create deeply nested structures
+