betterdocs / includes / Abilities / StubAbility.php

StubAbility.php in BetterDocs – AI Documentation, Knowledge Base, MCP Server, Docs, Wikis, FAQ & Chatbot 4.9.2, at includes/Abilities/StubAbility.php

202 lines 5.4 KB

Raw Download Zip

1	<?php
2	/**
3	* Placeholder ability for a tool that lives in BetterDocs Pro.
4	*
5	* @package BetterDocs
6	* @since 4.9.0
7	*/
8
9	namespace WPDeveloper\BetterDocs\Abilities;
10
11	if ( ! defined( 'ABSPATH' ) ) {
12	exit; // Exit if accessed directly.
13	}
14
15	/**
16	* A Pro tool as Free can describe it: real name, real label, real schema, real
17	* capability — and an execution that refuses with the reason.
18	*
19	* Registering these matters more than it looks. An agent that asks a Free site
20	* for its tools sees the whole BetterDocs surface, learns that knowledge bases
21	* exist, and is told in the tool's own description that Pro is what is missing.
22	* Without a stub the tool is simply absent and the agent concludes BetterDocs
23	* cannot do it at all. `tools/list` is therefore identical in shape on every
24	* site, and Pro replaces these instances by id — the name an agent
25	* learned never changes.
26	*
27	* The refusal is the same object the description promised:
28	* `pro_required` when Pro is missing or inactive, `setting_disabled` (with a
29	* literal `bd-update-settings` call the agent can make) when only the Multiple
30	* Knowledge Base setting is in the way, and `upstream_error` in the one case
31	* that means a broken install — Pro active, feature available, yet this stub
32	* still answering because Pro's registrar never replaced it.
33	*
34	* @since 4.9.0
35	*/
36	final class StubAbility extends AbilityBase {
37
38	/**
39	* Whether the tool needs the Multiple Knowledge Base feature, not just Pro.
40	*
41	* @since 4.9.0
42	*
43	* @var bool
44	*/
45	private $kb_feature = true;
46
47	/**
48	* Feature name used in the refusal sentence ("Knowledge bases need …").
49	*
50	* @since 4.9.0
51	*
52	* @var string
53	*/
54	private $feature = '';
55
56	/**
57	* Input schema from the spec.
58	*
59	* @since 4.9.0
60	*
61	* @var array
62	*/
63	private $input_schema = [];
64
65	/**
66	* Output schema from the spec.
67	*
68	* @since 4.9.0
69	*
70	* @var array
71	*/
72	private $output_schema = [];
73
74	/**
75	* Annotations from the spec.
76	*
77	* @since 4.9.0
78	*
79	* @var array
80	*/
81	private $annotations = [];
82
83	/**
84	* @since 4.9.0
85	*
86	* @param array $spec One entry from {@see ProStubs::specs()}: `id`, `label`,
87	* `description`, `feature`, `capability`, `kb_feature`,
88	* `input_schema`, `output_schema`, `annotations`.
89	*/
90	public function __construct( array $spec ) {
91	$this->id = isset( $spec['id'] ) ? (string) $spec['id'] : '';
92	$this->label = isset( $spec['label'] ) ? (string) $spec['label'] : '';
93	$this->description = isset( $spec['description'] ) ? (string) $spec['description'] : '';
94	$this->capability = isset( $spec['capability'] ) ? (string) $spec['capability'] : '';
95	$this->requires_pro = true;
96	$this->feature = isset( $spec['feature'] ) ? (string) $spec['feature'] : $this->label;
97	$this->kb_feature = isset( $spec['kb_feature'] ) ? (bool) $spec['kb_feature'] : true;
98
99	$this->input_schema = isset( $spec['input_schema'] ) && is_array( $spec['input_schema'] )
100	? $spec['input_schema']
101	: [
102	'type' => 'object',
103	'properties' => [],
104	'default' => []
105	];
106	$this->output_schema = isset( $spec['output_schema'] ) && is_array( $spec['output_schema'] )
107	? $spec['output_schema']
108	: [ 'type' => 'object' ];
109	$this->annotations = isset( $spec['annotations'] ) && is_array( $spec['annotations'] )
110	? $spec['annotations']
111	: parent::get_annotations();
112	}
113
114	/**
115	* @since 4.9.0
116	*
117	* @return array
118	*/
119	public function get_input_schema() {
120	return $this->input_schema;
121	}
122
123	/**
124	* @since 4.9.0
125	*
126	* @return array
127	*/
128	public function get_output_schema() {
129	return $this->output_schema;
130	}
131
132	/**
133	* @since 4.9.0
134	*
135	* @return array
136	*/
137	public function get_annotations() {
138	return $this->annotations;
139	}
140
141	/**
142	* Whether the tool needs Multiple Knowledge Base, not just Pro.
143	*
144	* @since 4.9.0
145	*
146	* @return bool
147	*/
148	public function needs_kb_feature() {
149	return $this->kb_feature;
150	}
151
152	/**
153	* The static description plus what is true on this site.
154	*
155	* @since 4.9.0
156	*
157	* @param array $pro_state Result of {@see ProState::get()}.
158	* @return string
159	*/
160	public function describe( array $pro_state ) {
161	return ProState::describe( $this->description, $pro_state );
162	}
163
164	/**
165	* Refuse, with the reason this site gives.
166	*
167	* @since 4.9.0
168	*
169	* @param array $input Validated input. Unused — a stub never does the work.
170	* @return \WP_Error Always.
171	*/
172	// phpcs:ignore Generic.CodeAnalysis.UnusedFunctionParameter.Found -- the signature is the contract; a stub refuses whatever it is given.
173	public function execute( $input ) {
174	$state = ProState::get( $this->kb_feature );
175
176	if ( 'pro_active_setting_off' === $state['state'] ) {
177	return AbilityError::setting_disabled(
178	'multiple_kb',
179	[ 'multiple_kb' => true ],
180	__( 'Multiple Knowledge Base', 'betterdocs' ),
181	$state['state']
182	);
183	}
184
185	if ( ProState::is_blocking( $state ) ) {
186	return AbilityError::pro_required( $state, $this->feature );
187	}
188
189	// Pro is active and the feature is available, yet Free's placeholder is
190	// still the thing answering: Pro's registrar did not replace it. That is
191	// a version mismatch, not a licensing or settings problem, so it must
192	// not be dressed up as one.
193	return AbilityError::upstream(
194	__( 'BetterDocs Pro is active but did not register this ability; update BetterDocs Pro.', 'betterdocs' ),
195	[
196	'ability' => $this->id,
197	'state' => $state['state']
198	]
199	);
200	}
201	}
202