Add client-only ability registration

[emdashcodes]

This PR follows up on #60 and introduces client-side only abilities. This allows for new integrations that deal with things like UI elements, navigation, and client-side data (such as the block editor). In addition to our AI efforts, it's also meant as a way that the command palette can execute client-side abilities in the future.

It adds two new methods to manage the client-only abilities registerAbility and unregisterAbility.

registerAbility takes the same shape as wp_register_ability in addition to a client side callback function. A callback can take the provided input_schema, do an action, and return the provided output_schema.

Here is a simple example:

registerAbility( {
	name: 'demo/navigate-admin',
	label: 'Navigate to Admin Page',
	description: 'Navigates to a specific WordPress admin page',
	location: 'client',
	meta: {
		type: 'tool',
	},
	input_schema: {
		type: 'object',
		properties: {
			page: {
				type: 'string',
				description: 'The admin page to navigate to (e.g., "users.php", "options-general.php")',
			},
			params: {
				type: 'object',
				description: 'Optional query parameters',
				additionalProperties: true,
			},
		},
		required: [ 'page' ],
	},
	output_schema: {
		type: 'object',
		properties: {
			success: { type: 'boolean' },
			url: { type: 'string' },
		},
		required: [ 'success', 'url' ],
	},
	callback: async function( input ) {
		const adminUrl = clientAbilitiesDemo.adminUrl || '/wp-admin/';
		let url = adminUrl + input.page;

		// Add query parameters if provided
		if ( input.params ) {
			const params = new URLSearchParams( input.params );
			url += '?' + params.toString();
		}

		// Navigate to the URL
		window.location.href = url;

		return {
			success: true,
			url: url,
		};
	},
} );

unregisterAbility is a convenience method for removing client-side only abilities.

Client-side abilities are saved in the store alongside server-side ones. They are marked specifically with a location property which is used to either call the callback or call the REST endpoint.

The input and output schemas are validated using Ajv and the ajv-formats plugin.

I have configured Ajv to support the intersection of rules that JSON Schema draft-04, WordPress (a subset of JSON Schema draft-04), and providers like OpenAI and Anthropic support.

Ajv is already in use by Gutenberg so it is already part of the ecosystem.

⚠️ Note: Tests and CI setup have been added in #70

Testing

cd packages/client

# Install dependencies
npm install

# Build the package
npm run build

I have created a dummy plugin that registers a few different abilities as an example: client-abilities-demo.zip

Open the developer console and paste the following:

await wp.abilities.listAbilities()

You should see the client side abilities (and any other server side abilities you registered) listed.

Paste in the following:

await wp.abilities.executeAbility('demo/get-current-user')

See that you get a simple user response object back.

Paste in the following:

await wp.abilities.executeAbility('demo/navigate-admin', { 
	page: 'users.php' 
});

See that you are redirected to the users.php screen.

Paste in the following:

wp.abilities.executeAbility('demo/show-notification', { 
	message: 'Hello from client ability!',
	type: 'success'
});

See that a UI notice briefly shows on the user page.

Now we can test registering and unregistering our own ability:

wp.abilities.registerAbility({
    name: 'demo/console-log',
    label: 'Console Logger',
    description: 'Logs messages to the browser console with different levels',
    location: 'client',
    input_schema: {
        type: 'object',
        properties: {
            message: {
                type: 'string',
                description: 'Message to log',
            },
            level: {
                type: 'string',
                enum: ['log', 'info', 'warn', 'error', 'debug'],
                description: 'Console log level',
                default: 'log'
            },
            data: {
                description: 'Additional data to log',
            }
        },
        required: ['message']
    },
    output_schema: {
        type: 'object',
        properties: {
            logged: { type: 'boolean' },
            timestamp: { type: 'string' },
            message: { type: 'string' }
        }
    },
    callback: async ({ message, level = 'log', data }) => {
        const timestamp = new Date().toISOString();
        const prefix = `[WP Ability ${timestamp}]`;

        switch (level) {
            case 'info':
                console.info(prefix, message, data || '');
                break;
            case 'warn':
                console.warn(prefix, message, data || '');
                break;
            case 'error':
                console.error(prefix, message, data || '');
                break;
            case 'debug':
                console.debug(prefix, message, data || '');
                break;
            default:
                console.log(prefix, message, data || '');
        }

        return {
            logged: true,
            timestamp: timestamp,
            message: message
        };
    }
});

Now test the ability:

// Simple log
await wp.abilities.executeAbility('demo/console-log', {
    message: 'Hello from WordPress abilities!'
});

// Warning with data
await wp.abilities.executeAbility('demo/console-log', {
    message: 'Low memory warning',
    level: 'warn',
    data: { available: '100MB', required: '500MB' }
});

// Error log
await wp.abilities.executeAbility('demo/console-log', {
    message: 'Failed to save settings',
    level: 'error',
    data: { code: 'NETWORK_ERROR', retry: true }
});

See that the various responses and different console types are executed.

To test the validation, you can change the return type and see what happens if you try to return a different type or something invalid against the schema.

Finally, you can unregister the client-side ability: wp.abilities.unregisterAbility('demo/console-log');. Trying to execute it again will throw an error.

Next Steps (not addressed in this PR)

Tests & CI setup for the whole client package have been added in #70

[github-actions]

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Co-authored-by: emdashcodes <[email protected]>
Co-authored-by: gziolo <[email protected]>
Co-authored-by: swissspidy <[email protected]>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

[codecov]

Codecov Report

❌ Patch coverage is 93.06358% with 12 lines in your changes missing coverage. Please review.
✅ Project coverage is 81.78%. Comparing base (d774d82) to head (3afbf71).
⚠️ Report is 1 commits behind head on add/client-library.

Files with missing lines	Patch %	Lines
packages/client/src/api.ts	87.50%	6 Missing ⚠️
packages/client/src/validation.ts	94.31%	5 Missing ⚠️
packages/client/src/store/resolvers.ts	91.66%	1 Missing ⚠️

Additional details and impacted files

@@                   Coverage Diff                    @@
##             add/client-library      #69      +/-   ##
========================================================
+ Coverage                 77.89%   81.78%   +3.88%     
  Complexity                  103      103              
========================================================
  Files                         9       15       +6     
  Lines                       552      741     +189     
  Branches                      0       75      +75     
========================================================
+ Hits                        430      606     +176     
- Misses                      122      135      +13     

Flag	Coverage Δ
javascript	93.12% <93.06%> (?)
unit	77.89% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[swissspidy]

Do we need permission callbacks on the client as well?

The input and output schemas are validated using Ajv and the ajv-formats plugin.

Probably the best choice.

Curious, how big does this make the bundle?

Ajv is already in use by Gutenberg so it is already part of the ecosystem.

What do mean with "already part of the ecosystem"? It's a mere dev dependency in Gutenberg for use in some tests. It's not in any of the published packages. That's a big difference and not really an argument for picking this dependency.

[emdashcodes]

What do mean with "already part of the ecosystem"? It's a mere dev dependency in Gutenberg for use in some tests. It's not in any of the published packages. That's a big difference and not really an argument for picking this dependency.

It's also used in WordPress Playground and a few other utils too. I included it to say we have opted to use it in other places, which to me is worth considering over another package. I haven't looked at the bundle size (yet), but I personally think it is worth it instead of needing to hit a /validate endpoint or something instead for client side abilities.

[emdashcodes]

Do we need permission callbacks on the client as well?

I was thinking about this as well and it's worth discussing. I think it would be nice to avoid needing to hit the REST API for running these, but maybe just providing a callback is enough? I'm open to ideas here!

[gziolo]

https://bundlephobia.com/package/[email protected]

It's a very reasonable size for the functionality it provides. In the long run we could reuse the logic in Gutenberg to validate block attributes schema in the development mode.

---

Do we need permission callbacks on the client as well?

It looks like on the server, we will enforce permission callbacks to increase the security as explained by @johnbillion in:

• Make the permission_callback argument required #68

It still might be valuable to have a way to define permission callbacks that checks whether a user can do something in the UI that's only for priviliged users so they have more streamlined experience. Otherwise we risk AI shows too often an message about failed attempe to do something it is not allowed to do. Similarily, @galatanovidiu in this comment #62 (comment) proposed a new property that does more high-level checks whether certain abilities should be filtered out if it's known upfront (without providing specific input) they aren't allowed to use them.

[gziolo]

This is shaping up nicely. I left my feedback for consideration and to better understand some decisions made.

[emdashcodes]

Regarding permissions, I have added a permissionCallback in f7a3dd2. It will run before an ability is executed. The implementation is intentionally left up to the user. This could be a simple JS based check, or they could hit the API or use nonces. The server permission callback will also still run when the REST API endpoint is called.

[emdashcodes]

All PR feedback has been handled correctly now. I'll continue fixing the tests and any other things pointed out in #70.

[gziolo]

All the feedback I shared was addressed. It looks good to land from my side.

[gziolo]

I merged #70 into this PR. If all CI checks still pass, I will merge everything together into #60 to review and test all the related changes integrated.