desktop-mode / includes / migrations.php

migrations.php in OpenStation: Desktop Windows, Dock & Virtual Desktops for WP Admin 1.1.8, at includes/migrations.php

668 lines 24.0 KB

Raw Download Zip

1	<?php
2	/**
3	* OpenStation — one-time data migrations.
4	*
5	* A tiny, option-versioned migration runner modeled on the lazy schema
6	* installer in `includes/desktop-files/schema.php`: a stored option holds
7	* the highest migration version that has run; on every admin load we
8	* compare it against {@see OPENSTATION_MIGRATION_VERSION} and run any
9	* pending migrations exactly once. Guarded so it is a cheap no-op after
10	* the first successful pass.
11	*
12	* On a site with no history the runner fires at activation instead, so
13	* nothing here ever has to infer the past of a site from evidence that
14	* site wrote after it was installed. See
15	* {@see openstation_run_migrations_on_activation}.
16	*
17	* @package OpenStation
18	*/
19
20	defined( 'ABSPATH' ) \|\| exit;
21
22	/**
23	* Highest migration version shipped by the plugin.
24	*
25	* Bump this (and add a matching branch in
26	* {@see openstation_run_pending_migrations}) whenever a new one-time
27	* migration is needed.
28	*
29	* A new migration runs on every install, including brand-new ones: on a
30	* site with no history the runner fires at activation
31	* ({@see openstation_run_migrations_on_activation}) rather than on the
32	* first `admin_init`.
33	*
34	* - 1: native list windows flipped from opt-out (default ON) to opt-in
35	* Beta (default OFF). Clears the five `native*Enabled` flags from every
36	* user who had them persisted so the whole install reverts to opt-in.
37	* - 2: post & taxonomy-term AI analysis was removed (the copilot now only
38	* analyzes comments for spam, and the assistant finds content via native
39	* WordPress search). Unschedules any queued `desktop_mode_ai_analyze_post`
40	* / `desktop_mode_ai_analyze_term` cron events left over from prior versions.
41	* - 3: the copilot dropped its self-managed AI credentials in favour of
42	* WordPress 7.0 Connectors. Deletes the platform key option and strips the
43	* per-user `apiKey` / `apiKeys` / `provider` / `transport` fields from the
44	* stored OS settings so no provider secret lingers in the database.
45	* - 4: the OpenStation brand. Moves anyone still sitting on the PRE-brand
46	* defaults — accent `wp-blue`, wallpaper `dark` — onto the new ones,
47	* Pulse and Galaxy. Without it the rebrand only reaches fresh accounts:
48	* the stored snapshot is authoritative over the shipped default, so an
49	* existing desk keeps a blue accent on every focus ring, tab underline
50	* and sort arrow.
51	* - 5: flags the users who were using Desktop Mode before the rename, so
52	* the shell can explain the new name once to the people it happened
53	* to and to nobody else. Sets user meta and nothing else — see
54	* {@see openstation_migrate_flag_rebrand_notice} for why that is a
55	* separate migration from 4.
56	* - 6: the Trash stopped registering a desktop icon. Removes the
57	* placement the shell had auto-placed for it and closes the hole that
58	* leaves in the icon column.
59	*/
60	const OPENSTATION_MIGRATION_VERSION = 7;
61
62	/**
63	* Option storing the highest migration version that has run. autoload=no.
64	*
65	* The VALUE keeps its pre-rebrand spelling on purpose: it is a
66	* persisted or externally-visible identifier, so renaming it would
67	* orphan data already written by live installs (or break a live
68	* URL). The mismatch between this constant's name and its value is
69	* deliberate — it is NOT a half-finished rename.
70	*/
71	const OPENSTATION_MIGRATION_OPTION = 'desktop_mode_migration_version';
72
73	/**
74	* Runs any pending migrations, then records the new high-water mark.
75	*
76	* Idempotent: bails immediately when the stored version is already at
77	* or above the shipped version, so it is safe to fire on every request.
78	*
79	* @return void
80	*/
81	function openstation_maybe_run_migrations() {
82	$installed = (int) get_option( OPENSTATION_MIGRATION_OPTION, 0 );
83	if ( $installed >= OPENSTATION_MIGRATION_VERSION ) {
84	return;
85	}
86
87	openstation_run_pending_migrations( $installed );
88
89	update_option( OPENSTATION_MIGRATION_OPTION, OPENSTATION_MIGRATION_VERSION, false );
90	}
91	add_action( 'admin_init', 'openstation_maybe_run_migrations' );
92
93	/**
94	* Runs the pending migrations at activation, on a site with no history.
95	*
96	* Migration 5 infers who used the shell before the rename from user meta
97	* that a site can write to itself between activation and the first
98	* `admin_init` (the portal auto-enable). Running at activation is the
99	* one moment that window is still shut, so the same runner reaches the
100	* same conclusion about the same site and cannot be fooled by evidence
101	* that arrives later.
102	*
103	* The whole runner, not a subset: migrations 2 and 3 clear leftover AI
104	* cron events and a stored provider credential, neither of which any
105	* user meta predicts.
106	*
107	* @return void
108	*/
109	function openstation_run_migrations_on_activation() {
110	// Migrations have already run here; their high-water mark is the
111	// truth and the runner would be a no-op anyway.
112	if ( false !== get_option( OPENSTATION_MIGRATION_OPTION, false ) ) {
113	return;
114	}
115
116	// The site has history, so this is a reactivation and not a new
117	// install. Leave it to `admin_init`, where migration 5 reads meta
118	// that is genuinely older than this request.
119	$prior_users = openstation_users_with_prior_desktop_use();
120	if ( ! empty( $prior_users ) ) {
121	return;
122	}
123
124	openstation_maybe_run_migrations();
125	}
126	register_activation_hook( OPENSTATION_FILE, 'openstation_run_migrations_on_activation' );
127
128	/**
129	* Dispatches each migration whose version is newer than what has run.
130	*
131	* @param int $from The highest migration version already applied.
132	* @return void
133	*/
134	function openstation_run_pending_migrations( $from ) {
135	$from = (int) $from;
136
137	if ( $from < 1 ) {
138	openstation_migrate_os_settings_optin();
139	}
140
141	if ( $from < 2 ) {
142	openstation_migrate_unschedule_post_term_ai();
143	}
144
145	if ( $from < 3 ) {
146	openstation_migrate_delete_ai_keys();
147	}
148
149	if ( $from < 4 ) {
150	openstation_migrate_brand_defaults();
151	}
152
153	if ( $from < 5 ) {
154	openstation_migrate_flag_rebrand_notice( $from );
155	}
156
157	if ( $from < 6 ) {
158	openstation_migrate_close_recycle_bin_icon_gap();
159	}
160
161	if ( $from < 7 ) {
162	openstation_migrate_seed_agent_faces();
163	}
164	}
165
166	/**
167	* Migration 7 — give the agents that predate faces a seed to grow one
168	* from.
169	*
170	* Agents used to share a single grey robot glyph. They now carry a Mio
171	* look, and an agent created from here on gets a seed at birth. The
172	* ones already on the site do not, and without a seed there is nothing
173	* to derive a face from.
174	*
175	* This writes the seed and stops. It does not write the face. The
176	* face comes from `randomMioLook()`, which lives in TypeScript, and
177	* porting it is exactly the wrong trade: it is a taste filter with a
178	* dozen judgment calls in it, pinned by `mio-randomize.test.ts`, and a
179	* PHP twin of it would drift with nothing watching. So the shell fills
180	* the looks in on its next paint of the Agents section, rolling each
181	* one from the seed written here.
182	*
183	* That is a client writing on the server's behalf, which is worth
184	* naming rather than slipping past. It is safe because it is entirely
185	* derived: the seed is `crc32` of the login, so two admins racing the
186	* backfill produce byte-identical faces, and running it twice changes
187	* nothing.
188	*
189	* The five shipped agents are unaffected: their faces are written out
190	* in `default-definitions.php` and were never rolled.
191	*
192	* @return void
193	*/
194	function openstation_migrate_seed_agent_faces() {
195	// Agents is behind a feature flag, so on a site that has never
196	// turned it on there is nothing to seed, and none of the module's
197	// functions exist to call. A site that turns it on later creates
198	// its agents through `openstation_agent_create`, which seeds them
199	// at birth, so nothing is missed by returning here.
200	if (
201	! function_exists( 'openstation_agent_get_agents' )
202	\|\| ! function_exists( 'openstation_agent_get_face_seed' )
203	\|\| ! defined( 'OPENSTATION_AGENT_FACE_SEED_META' )
204	) {
205	return;
206	}
207
208	foreach ( openstation_agent_get_agents() as $agent ) {
209	$user_id = isset( $agent->ID ) ? (int) $agent->ID : 0;
210	if ( $user_id <= 0 ) {
211	continue;
212	}
213	if ( openstation_agent_get_face_seed( $user_id ) > 0 ) {
214	continue;
215	}
216	update_user_meta(
217	$user_id,
218	OPENSTATION_AGENT_FACE_SEED_META,
219	crc32( (string) $agent->user_login )
220	);
221	}
222	}
223
224	/**
225	* Grid the desktop auto-placer lays icons out on: 16px of padding, a
226	* 96px column, a 110px row. Mirrored from `src/desktop-files/grid.ts`
227	* via {@see openstation_files_auto_place_orphans}, which is what wrote
228	* the coordinates this migration edits.
229	*/
230	const OPENSTATION_DESKTOP_GRID_ROW_H = 110;
231
232	/**
233	* Migration 6 — take back the Trash's desktop icon, and close the hole.
234	*
235	* The bin used to register a desktop icon, and every viewer's first
236	* hydrate auto-placed it into the icon column. Now that the
237	* registration is gone the placement is dead weight: it is no longer
238	* served (`OpenStation_Shortcut_File::can_read()` is false without a
239	* registry entry), so the tile has already vanished on its own. What it
240	* leaves behind is an empty cell with the icons that were under it
241	* still sitting where they were.
242	*
243	* So: delete the row, and pull everything below it in the same column
244	* up by one. Same column only, because the auto-placer fills
245	* column-major, so a column is the run the bin was part of. This does
246	* move tiles a user may have arranged, which is the point — the shell
247	* put that icon there and the shell is taking it away, so the shell
248	* tidies up after itself rather than leaving a gap nobody chose.
249	*
250	* A user who wants the bin back on the wallpaper picks "On the desktop"
251	* in Preferences → Navigation, which promotes the dock tile and never
252	* touches these rows.
253	*
254	* @return void
255	*/
256	function openstation_migrate_close_recycle_bin_icon_gap() {
257	global $wpdb;
258
259	if ( ! function_exists( 'openstation_files_table_names' ) ) {
260	return;
261	}
262	$tables = openstation_files_table_names();
263	$tbl = $tables['placements'];
264
265	// The files schema installs lazily, so a site that never opened
266	// the desktop has no table to migrate.
267	$table_exists = (int) $wpdb->get_var(
268	$wpdb->prepare(
269	'SELECT COUNT(*) FROM INFORMATION_SCHEMA.TABLES
270	WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME = %s',
271	$tbl
272	)
273	);
274	if ( 0 === $table_exists ) {
275	return;
276	}
277
278	// Shift first, delete second: the derived table has to still find
279	// the bin's own row to know which cell is being vacated. It is
280	// materialized before the update runs, so reading and writing the
281	// same table in one statement is fine here.
282	//
283	// The UNIQUE index on (owner_id, parent_id, file_type, file_ref)
284	// guarantees at most one bin row per owner, so no row can be
285	// shifted twice.
286	$wpdb->query(
287	$wpdb->prepare(
288	// phpcs:ignore WordPress.DB.PreparedSQL.InterpolatedNotPrepared -- table name, not user input.
289	"UPDATE `{$tbl}` AS p
290	INNER JOIN (
291	SELECT owner_id, x, y FROM `{$tbl}`
292	WHERE parent_id = 0
293	AND file_type = 'shortcut'
294	AND file_ref = %s
295	) AS bin
296	ON p.owner_id = bin.owner_id
297	AND p.x = bin.x
298	AND p.y > bin.y
299	SET p.y = p.y - %d
300	WHERE p.parent_id = 0
301	AND p.trashed_at_ms IS NULL",
302	'desktop-mode-recycle-bin',
303	OPENSTATION_DESKTOP_GRID_ROW_H
304	)
305	);
306
307	$wpdb->delete(
308	$tbl,
309	array(
310	'parent_id' => 0,
311	'file_type' => 'shortcut',
312	'file_ref' => 'desktop-mode-recycle-bin',
313	),
314	array( '%d', '%s', '%s' )
315	);
316	}
317
318	/**
319	* User meta marking someone as a Desktop Mode user from before the rebrand.
320	*
321	* Present and truthy => the shell offers this user the one-off rebrand
322	* announcement, once. Absent => they never used the plugin under its old
323	* name, so there is no rename to explain to them. Written only by
324	* migration 5, and only for users who were actually using Desktop Mode
325	* at the moment it ran.
326	*
327	* The VALUE keeps the pre-rebrand spelling for the reason every other
328	* stored key does — see {@see OPENSTATION_MIGRATION_OPTION}.
329	*/
330	const OPENSTATION_REBRAND_NOTICE_META_KEY = 'desktop_mode_rebrand_notice';
331
332	/**
333	* Slug the rebrand announcement records in `desktop_mode_seen_intros`.
334	*
335	* A slug in the shared registry rather than a bespoke meta key, so the
336	* announcement is dismissed, reset and reasoned about exactly like the
337	* native-window intros beside it.
338	*/
339	const OPENSTATION_REBRAND_INTRO_SLUG = 'openstation-rebrand';
340
341	/**
342	* Every user who carries proof of having used the shell on this site:
343	* `desktop_mode_mode` (the per-user opt-in, tested for EXISTENCE rather
344	* than for being `'1'`, since switching back to classic empties the
345	* value but leaves the row) or a saved `desktop_mode_os_settings`.
346	*
347	* @return int[] User IDs, unsorted and deduplicated.
348	*/
349	function openstation_users_with_prior_desktop_use() {
350	return array_map(
351	'intval',
352	array_unique(
353	array_merge(
354	get_users(
355	array(
356	'fields' => 'ID',
357	'meta_key' => 'desktop_mode_mode', // phpcs:ignore WordPress.DB.SlowDBQuery.slow_db_query_meta_key -- runs once per install; the key is indexed in usermeta and both callers are guarded to a single pass.
358	'meta_compare' => 'EXISTS',
359	)
360	),
361	get_users(
362	array(
363	'fields' => 'ID',
364	'meta_key' => OPENSTATION_OS_SETTINGS_META_KEY, // phpcs:ignore WordPress.DB.SlowDBQuery.slow_db_query_meta_key -- see above.
365	'meta_compare' => 'EXISTS',
366	)
367	)
368	)
369	)
370	);
371	}
372
373	/**
374	* Migration 5 — remember who was using Desktop Mode before the rebrand.
375	*
376	* Migration 4 moved the pre-brand defaults onto the brand ones. This
377	* one answers a different question: not "what should this desk look
378	* like" but "does this person need to be told why it changed". Someone
379	* who has been running Desktop Mode for months opens wp-admin one
380	* morning to a differently-named, differently-coloured shell; without a
381	* word of explanation that reads as a compromised site, not a release.
382	*
383	* Two gates. The install gate is a bare "has the rebrand already
384	* happened here", and the user gate does the actual work.
385	*
386	* The install must not already be past the rebrand: `$from < 4`. A
387	* `4` means migration 4 has run, which today means a checkout tracking
388	* trunk between the two release tags. Not a surprised user.
389	*
390	* Note what is deliberately NOT tested: whether `$from` is zero. It is
391	* tempting to read `0` as "fresh install, nothing to explain", and that
392	* reading is wrong in the one direction that matters. The migration
393	* runner itself only shipped in 0.9.1, so an install still on 0.9.0 or
394	* earlier that updates straight to the rebrand release has no stored
395	* version at all and arrives here with `$from === 0`, indistinguishable
396	* from a brand new site. Those are the installs that update rarely,
397	* which makes them the ones most likely to be blindsided by a rename,
398	* and gating on `$from > 0` would have silenced precisely them.
399	*
400	* The user has to have actually used it — see
401	* {@see openstation_users_with_prior_desktop_use} for what counts as
402	* proof. That separates a long-dormant install from a genuinely new one
403	* without needing to date the install at all, and it keeps the
404	* announcement away from an editor who joined an old site last week and
405	* enabled OpenStation this morning.
406	*
407	* What that gate does NOT do on its own is prove the evidence is old.
408	* On a new install it can be written between activation and the first
409	* `admin_init`, and then read back here as history. That window is
410	* closed by {@see openstation_run_migrations_on_activation}, which runs
411	* this migration before anything can write it.
412	*
413	* Deliberately NOT folded into migration 4, even though the two ship
414	* together: 4 has already run on trunk checkouts, and a migration that
415	* has run does not run again. Extending it would have silently skipped
416	* the flag exactly where it was easiest to believe it had been set.
417	*
418	* Flags are never cleared. Dismissal lives in the seen-intros registry,
419	* so one admin dismissing the announcement does not silence it for
420	* their editors, and "Reset what's-new dialogs" in OpenStation Preferences
421	* → Features brings it back with every other intro.
422	*
423	* @param int $from The highest migration version already applied.
424	* @return void
425	*/
426	function openstation_migrate_flag_rebrand_notice( $from ) {
427	if ( (int) $from >= 4 ) {
428	return;
429	}
430
431	foreach ( openstation_users_with_prior_desktop_use() as $user_id ) {
432	update_user_meta( $user_id, OPENSTATION_REBRAND_NOTICE_META_KEY, 1 );
433	}
434	}
435
436	/**
437	* Whether the current user should be offered the rebrand announcement.
438	*
439	* Two gates: migration 5 flagged this user as one who was using Desktop
440	* Mode before the rename, and they have not already dismissed it. The
441	* seen-intros registry owns the second one, which is what makes the
442	* announcement behave like every other one-time dialog — including
443	* being brought back by "Reset what's-new dialogs".
444	*
445	* Only ever consulted while building the shell config, which is itself
446	* behind the `openstation_is_enabled()` / not-classic guard in
447	* `includes/render/assets.php`. So the announcement cannot reach the
448	* classic admin or a chromeless iframe: the bundle that would show it
449	* is not loaded there.
450	*
451	* @return bool
452	*/
453	function openstation_should_show_rebrand_notice() {
454	$user_id = get_current_user_id();
455	if ( ! $user_id ) {
456	return false;
457	}
458
459	if ( ! get_user_meta( $user_id, OPENSTATION_REBRAND_NOTICE_META_KEY, true ) ) {
460	return false;
461	}
462
463	return ! openstation_has_seen_intro( $user_id, OPENSTATION_REBRAND_INTRO_SLUG );
464	}
465
466	/**
467	* Migration 4 — move the pre-brand defaults onto the OpenStation ones.
468	*
469	* The stored OS-settings snapshot outranks the shipped default, so
470	* changing `openstation_default_os_settings()` reaches new accounts and
471	* nobody else. Every existing desk would keep `wp-blue` on its focus
472	* rings, tab underlines, sort arrows and selection washes, and keep the
473	* graphite `dark` desk under the station's chrome — a half-applied
474	* rebrand, which reads as a bug rather than as a choice.
475	*
476	* Only values still equal to the OLD default are touched. A user who
477	* picked Indigo, or the Snow wallpaper, expressed a preference and keeps
478	* it. The one unavoidable cost is the user who deliberately chose
479	* WordPress Blue — indistinguishable from never having chosen at all,
480	* because it WAS the default — and for them it is one click in
481	* OS Settings → Appearance to set it back.
482	*
483	* Users with no stored settings are skipped entirely: they read the new
484	* defaults already.
485	*
486	* @return void
487	*/
488	function openstation_migrate_brand_defaults() {
489	// The pre-brand => brand value map, keyed by OS-settings field.
490	// Deliberately not filterable: this runs once, against one release's
491	// stored defaults, and a third party rewriting which values get
492	// migrated would leave desks in a state no later migration accounts
493	// for.
494	$map = array(
495	'accent' => array(
496	'from' => 'wp-blue',
497	'to' => 'pulse',
498	),
499	'wallpaper' => array(
500	'from' => 'dark',
501	'to' => 'galaxy',
502	),
503	);
504
505	$user_ids = get_users(
506	array(
507	'fields' => 'ID',
508	'meta_key' => OPENSTATION_OS_SETTINGS_META_KEY, // phpcs:ignore WordPress.DB.SlowDBQuery.slow_db_query_meta_key -- one-time migration; the key is indexed in usermeta and the scan is guarded to run once.
509	'meta_compare' => 'EXISTS',
510	)
511	);
512
513	foreach ( $user_ids as $user_id ) {
514	$raw = get_user_meta( (int) $user_id, OPENSTATION_OS_SETTINGS_META_KEY, true );
515	if ( ! is_array( $raw ) ) {
516	continue;
517	}
518
519	$changed = false;
520	foreach ( $map as $key => $move ) {
521	if ( ! isset( $move['from'], $move['to'] ) ) {
522	continue;
523	}
524	// An absent key already resolves to the new default.
525	if ( isset( $raw[ $key ] ) && $move['from'] === $raw[ $key ] ) {
526	$raw[ $key ] = $move['to'];
527	$changed = true;
528	}
529	}
530
531	if ( $changed ) {
532	openstation_save_os_settings( (int) $user_id, $raw );
533	}
534	}
535	}
536
537	/**
538	* Migration 1 — reset the native list windows to opt-in.
539	*
540	* The native Posts/Pages/Users/Plugins/Comments windows used to default
541	* ON (opt-out). The shell persists the whole OS-settings object on every
542	* change, so most active users already have these flags stored as `true`
543	* and would keep the native UI even after the default flips. This clears
544	* the five flags from every user who has the meta, leaving the rest of
545	* their settings (wallpaper, accent, dock order, …) untouched. On the
546	* next read the cleared keys fall back to the new `false` default, so the
547	* whole install lands on opt-in and users re-enable each window from
548	* OS Settings → Features → Beta features.
549	*
550	* Only users who actually have the meta are queried — fresh accounts and
551	* users who never touched OS Settings are skipped entirely.
552	*
553	* @return void
554	*/
555	function openstation_migrate_os_settings_optin() {
556	$flags = array(
557	'nativePostsEnabled',
558	'nativePagesEnabled',
559	'nativeUsersEnabled',
560	'nativePluginsEnabled',
561	'nativeCommentsEnabled',
562	);
563
564	$user_ids = get_users(
565	array(
566	'fields' => 'ID',
567	'meta_key' => OPENSTATION_OS_SETTINGS_META_KEY, // phpcs:ignore WordPress.DB.SlowDBQuery.slow_db_query_meta_key -- one-time migration; the key is indexed in usermeta and the scan is guarded to run once.
568	'meta_compare' => 'EXISTS',
569	)
570	);
571
572	foreach ( $user_ids as $user_id ) {
573	$raw = get_user_meta( (int) $user_id, OPENSTATION_OS_SETTINGS_META_KEY, true );
574	if ( ! is_array( $raw ) ) {
575	continue;
576	}
577
578	$changed = false;
579	foreach ( $flags as $flag ) {
580	if ( array_key_exists( $flag, $raw ) ) {
581	unset( $raw[ $flag ] );
582	$changed = true;
583	}
584	}
585
586	if ( ! $changed ) {
587	continue;
588	}
589
590	// Re-save through the canonical sanitizer so the cleared flags are
591	// backfilled with the new `false` default and the rest of the
592	// settings array is normalized exactly as a client write would be.
593	openstation_save_os_settings( (int) $user_id, $raw );
594	}
595	}
596
597	/**
598	* Migration 2 — unschedule leftover post/term AI analysis jobs.
599	*
600	* Post and taxonomy-term analysis was removed: the copilot now only
601	* analyzes comments (for the spam score), and the AI assistant finds
602	* content with native WordPress keyword search. Their cron callbacks no
603	* longer exist, so any single-events still queued from a prior version
604	* would simply no-op — but we clear them so the cron array stays tidy and
605	* `wp cron event list` doesn't show orphaned hooks.
606	*
607	* Existing `_desktop_mode_ai_analysis` meta on posts/terms is left in place
608	* (hidden, harmless, and cheap to ignore).
609	*
610	* @return void
611	*/
612	function openstation_migrate_unschedule_post_term_ai() {
613	wp_unschedule_hook( 'desktop_mode_ai_analyze_post' );
614	wp_unschedule_hook( 'desktop_mode_ai_analyze_term' );
615	}
616
617	/**
618	* Migration 3 — delete self-managed AI credentials.
619	*
620	* WordPress 7.0 owns provider credentials (Settings → Connectors), so the
621	* copilot no longer stores keys of its own. Remove the platform key option and
622	* strip the now-unused key / provider / model / transport fields from every
623	* user's stored OS settings so no secret is left behind. The only `ai` field
624	* that remains is `enabled` (the per-user assistant toggle), backfilled from
625	* defaults on next read.
626	*
627	* @return void
628	*/
629	function openstation_migrate_delete_ai_keys() {
630	// Platform-wide key option (formerly `desktop_mode_ai_platform`).
631	delete_option( 'desktop_mode_ai_platform' );
632
633	$user_ids = get_users(
634	array(
635	'fields' => 'ID',
636	'meta_key' => OPENSTATION_OS_SETTINGS_META_KEY, // phpcs:ignore WordPress.DB.SlowDBQuery.slow_db_query_meta_key -- one-time migration; guarded to run once.
637	'meta_compare' => 'EXISTS',
638	)
639	);
640
641	foreach ( $user_ids as $user_id ) {
642	$raw = get_user_meta( (int) $user_id, OPENSTATION_OS_SETTINGS_META_KEY, true );
643	if ( ! is_array( $raw ) \|\| ! isset( $raw['ai'] ) \|\| ! is_array( $raw['ai'] ) ) {
644	continue;
645	}
646
647	// Strip every legacy AI field: the self-managed credentials/transport,
648	// plus the `provider` / `model` preferences — provider + model selection
649	// is now delegated entirely to the Core AI Client.
650	$changed = false;
651	foreach ( array( 'apiKey', 'apiKeys', 'transport', 'provider', 'model' ) as $stale ) {
652	if ( array_key_exists( $stale, $raw['ai'] ) ) {
653	unset( $raw['ai'][ $stale ] );
654	$changed = true;
655	}
656	}
657
658	if ( ! $changed ) {
659	continue;
660	}
661
662	openstation_save_os_settings( (int) $user_id, $raw );
663	}
664	}
665
666	// Presence owns a verified checkpoint so failures never advance unrelated migrations.
667	add_action( 'admin_init', 'openstation_presence_migration_tick', 20 );
668