clawpress

Imported from bradvin/clawpress (AGENTS.md). Install upstream with npx skills add bradvin/clawpress. Copyright stays with the author.

AGENTS.md - AI Assistant Context

This is a WordPress plugin ClawPress. When working with this codebase, follow these patterns and conventions.

Project Overview

The plugin includes:

• React-based admin UI using DataViews
• REST API with namespaced endpoints
• Floating wp-admin panel UI (src/panel)
• wp-scripts build system

Architecture Patterns

PHP Structure

• Main file (clawpress.php): Only defines constants and requires modules
• Feature modules (includes/class-*.php): Each feature isolated in its own namespaced class file
• Strict types: All PHP files use declare( strict_types=1 )
• Namespace convention: ClawPress\FeatureName
• Coding standards: WordPress Coding Standards (WPCS) - use tabs, spaces inside parentheses
• Linting config: phpcs.xml.dist - run npm run lint:php to check

JavaScript Structure

• Entry point: src/js/admin/index.js - mounts React app on plugin admin page
• Panel entry point: src/panel/index.jsx - mounts floating admin panel
• Components: src/js/admin/components/ - React components
• Hooks: src/js/admin/hooks/ - Custom hooks (data fetching, state)
• Config: src/js/admin/config/ - Field definitions, actions, settings

JavaScript Formatting Rules

Apply these rules consistently to avoid large lint/fix churn:

• Use tabs for indentation in JS/JSX files.
• Use single quotes for JS strings/imports (unless escaping/template use makes that inappropriate).
• Let Prettier collapse JSX/expressions to single-line when short; do not force manual multi-line wrapping.
• Do not manually align tokens/spaces for visual columns; keep standard Prettier spacing.
• Keep object/array/function formatting Prettier-first; avoid hand-formatted stylistic layouts.
• Avoid nested ternaries; expand to clear if/else when logic branches.
• Keep ideas/ out of JS lint scope (ignored via .eslintignore and changed-file lint script).
• Before committing JS changes, run npm run lint:js -- --fix (or scoped equivalent) and then npm run lint:js.

REST API Pattern

Located in includes/class-rest-api.php:

• Namespace: clawpress/v1
• Always include permission_callback
• Use sanitize_callback and validate_callback for args
• Return WP_REST_Response with appropriate status codes

Note: The DataViews demo uses @wordpress/core-data which handles REST calls for post types internally. Custom endpoints are only needed for operations not covered by WordPress core (custom business logic, aggregations, etc.).

DataViews Pattern

The admin UI uses @wordpress/dataviews with the WordPress Data Layer:

• fields: Define columns in config/itemConfig.js
• actions: Define row actions (view, edit, trash) in same file
• useItems hook: Uses useEntityRecords from @wordpress/core-data

To switch post types, change 'page' to your CPT slug in useItems.js.

Key Files to Modify

When adding features:

Helper Class Reference

Use helpers in includes/helpers/ as the primary integration surface for shared logic.

Helper Guardrails

• Do not duplicate helper logic in controllers/commands.
• Do not add new direct memory storage access in commands/controllers/options.
• Memory data model is:
  • Daily memory files: memory-ddmmyyyy.md
  • Long-term memory file: memory.md
• Context assembly must read memory via Memory_Helper and not from legacy options.

Data Flow

The demo uses the WordPress Data Layer (@wordpress/core-data):

WordPress REST API (built-in /wp/v2/pages)
    ↓
useEntityRecords (src/js/admin/hooks/useItems.js)
    ↓
DataViews component (src/js/admin/components/App.js)

The Data Layer handles authentication, caching, and optimistic updates automatically. To use a custom post type, change 'page' to your CPT slug in useItems.js.

For custom endpoints (settings, business logic), use includes/class-rest-api.php with wp_localize_script in includes/class-admin-page.php. These endpoints can then be called from your React components using apiFetch.

Common Tasks

Changing the post type

// src/js/admin/hooks/useItems.js
// Change 'page' to your custom post type slug
useEntityRecords( 'postType', 'your_cpt_slug', { ... } );

Adding a new DataViews field

// src/js/admin/config/itemConfig.js
{
    id: 'new_field',
    label: 'New Field',
    type: 'text',
    enableSorting: true,
    getValue: ({ item }) => item.new_field,
}

Adding a REST endpoint

// includes/class-rest-api.php
register_rest_route(
	'clawpress/v1',
	'/new-endpoint',
	array(
		'methods'             => 'GET',
		'callback'            => __NAMESPACE__ . '\handle_new_endpoint',
		'permission_callback' => function () {
			return current_user_can( 'manage_options' );
		},
	)
);

Dependencies

Scripts rely on WordPress packages extracted at build time:

• @wordpress/element - React wrapper
• @wordpress/components - UI components
• @wordpress/core-data - Data layer (REST API abstraction)
• @wordpress/dataviews - Table/grid views
• @wordpress/icons - Icon library
• @wordpress/dom-ready - Admin app bootstrap
• @wordpress/element - React root rendering

Internationalization (Required)

All user-facing strings must be translatable.

• Never ship hardcoded UI text in PHP or JS.
• Always use text domain: clawpress.
• PHP strings: use __(), _x(), esc_html__(), esc_attr__(), sprintf() with translator comments when placeholders are used.
• JS strings: import from @wordpress/i18n and use __, _x, _n, sprintf as needed.
• Keep command identifiers/keys untranslated (e.g., /help, option keys, slugs), but translate labels/messages/descriptions shown to users.
• When adding new script entry points/handles, ensure script translations are loaded via wp_set_script_translations( $handle, 'clawpress', CLAWPRESS_DIR . 'languages' ).

Unit Tests And WordPress Stubs

When writing or refactoring PHPUnit tests:

• Never add test-only logic, boot contracts, or test-oriented exceptions/messages to plugin runtime code in includes/ or clawpress.php.
• Do not introduce production assert_* helpers, runtime throws, or function_exists() guards solely to make tests pass.
• If PHPUnit needs a missing WordPress API, add a deterministic stub in tests/Support/WordPressStubs.php instead of changing plugin behavior.
• When a stub needs state, store it in WordPress_Stubs and reset it in WordPress_Stubs::reset() so tests remain isolated.
• Keep stubs minimal and behavior-focused: enough for assertions without recreating WordPress internals.
• Tests must validate real plugin behavior and observable outcomes, not internal test scaffolding.
• Prefer exercising registered hooks with do_action()/apply_filters() and asserting side effects (registered menus/routes, enqueued assets, persisted meta/options, scheduler calls).
• Avoid low-value tests that only assert stub presence (for example function_exists() contract lists) or only test helper assertions without behavior coverage.
• If behavior is truly optional in production (version-gated or feature-detected APIs), keep runtime guards and cover both paths in tests.

Verification Expectations

• Run targeted PHPUnit tests for the changed module first.
• Run the full PHPUnit suite when shared test support files (like WordPressStubs.php) are changed.
• Prefer assertions that verify integration calls and state transitions happened (for example submenu registration/removal and metadata checks).

Local CI With Agent CI

• Install the agent-ci skill one time with npx skills add redwoodjs/agent-ci --skill agent-ci.
• Before completing substantial work, run npm run ci:agent:ci or npm run ci:agent and fix any failures before reporting the work as done.
• If Agent CI pauses on a failed step, fix the issue and resume with npm run ci:agent:retry -- --name <runner-name>.
• Keep local Agent CI secrets in .env.agent-ci. Never commit that file.

Important Notes

• Asset files (build/scripts/*.asset.php) are auto-generated - never edit manually
• The build/, node_modules/, and vendor/ directories are gitignored
• Always run composer install && npm install && npm run build after cloning
• After adding, renaming, or removing PHP class files in the plugin, run composer dump-autoload before testing.
• PHP must follow WordPress Coding Standards - run npm run lint:php before committing
• PHP namespaces must match directory structure for autoloading compatibility
• The Data Layer (@wordpress/core-data) handles REST auth automatically
• Admin page uses add_menu_page() and mounts the app into a dedicated root element
• Avoiding adding manual inline style overrides to components unless specifically requested.