Share connected WP.com sites between Studio app and CLI (#3227)

## Related issues

- Related to #

## How AI was used in this PR

Opus 4.7 scoped the refactor, wrote the new shared helpers, the
migration, and the Desktop/CLI wiring. I (the author) steered the
data-model decision (cli.json sites property, per-user keying preserved)
and reviewed each hunk. The diff is roughly 520 lines added / 135
removed across 12 files — mostly mechanical once the data layout was
settled.

## Proposed Changes

Connected WP.com sites used to live in `app.json` as a top-level
`connectedWpcomSites: { [userId]: SyncSite[] }` — Desktop-only state.
This moves the list into per-site entries in `cli.json` so both Desktop
and the CLI share a single source of truth, and wires up the CLI
push/pull flows to auto-connect on success.

- **Shared data layer** (`tools/common/`)
- `syncSiteSchema` zod schema added next to the `SyncSite` type, which
is now inferred from it.
- New `tools/common/lib/connected-sites.ts` with read/write helpers
against `cli.json`: `getConnectedWpcomSitesForLocalSite`,
`getAllConnectedWpcomSitesForCurrentUser`, `addConnectedWpcomSite`,
`removeConnectedWpcomSite`, `updateConnectedWpcomSites`,
`markConnectedWpcomSiteSynced`. Uses the existing `cli.json.lock`
lockfile and a permissive passthrough schema so Desktop and CLI can
evolve their `cli.json` site entries independently without corrupting
each other's fields.
- **Storage schemas**
- CLI `siteSchema` now carries an optional `connectedWpcomSites: {
[userId]: SyncSite[] }` map per site.
  - `connectedWpcomSites` removed from the `app.json` `UserData` type.
- **Migration 04** copies
`app.json.connectedWpcomSites[userId][].{localSiteId}` into `cli.json
sites[].connectedWpcomSites[userId]`, deduping by remote id. It stamps
`connectedWpcomSitesMigratedToCli: true` on `app.json` and leaves the
legacy field in place for this release so older Studio versions keep
working — a follow-up migration will strip it.
- **Desktop IPC handlers** now delegate through the shared helpers
instead of reading/writing `app.json`:
- `connectWpcomSites`, `disconnectWpcomSites`,
`updateConnectedWpcomSites`, `getConnectedWpcomSites` in
`apps/studio/src/modules/sync/lib/ipc-handlers.ts`
- `reconcileSessionEnvironmentBeforeRun` and `setSessionEnvironment` in
`apps/studio/src/ipc-handlers.ts`
- **CLI auto-connect**: `apps/cli/commands/push.ts` and
`apps/cli/commands/pull.ts` call `addConnectedWpcomSite` +
`markConnectedWpcomSiteSynced` after a successful run.
- **AI agent push workflow**: the `studio code` agent gained a
`site_connected_remote_sites` MCP tool plus a new system-prompt section
instructing it to resolve the target before pushing — 1 attached site →
confirm, many → `AskUserQuestion` list, 0 → open-ended question.

## Testing Instructions

- Back up `~/.studio/app.json` and `~/.studio/cli.json`.
- **Migration:** with `app.json.connectedWpcomSites` populated, launch
the Desktop app. Expect `cli.json sites[].connectedWpcomSites[userId]`
to be populated, and `app.json.connectedWpcomSitesMigratedToCli: true`
to be added. The legacy `app.json.connectedWpcomSites` should still be
present.
- **Desktop:** open a site with a connection — publish picker + site
dropdown + session environment switcher should show the connection as
before.
- **Desktop connect/disconnect:** from the sync modal, connect and
disconnect a WordPress.com site — the entry should appear/disappear in
`cli.json` without further app.json writes.
- **CLI auto-connect:** run `studio push` or `studio pull` for a site
with no connections yet — after success, verify the remote site shows up
under `cli.json sites[].connectedWpcomSites` and that Desktop's site
dropdown reflects it.
- **CLI AI agent:** run `studio code`, ask it to "push my site". It
should call `site_connected_remote_sites`, then either confirm (single
attached), show a picker (many), or ask open-ended (none) before calling
`site_push`.

## Pre-merge Checklist

- [x] Have you checked for TypeScript, React or other console errors?
(`npm run typecheck` clean across workspaces; `npm test -- apps/cli
apps/studio` — 1042 passing)
- [ ] Manual Desktop smoke test of connect/disconnect UI
- [ ] Manual CLI push/pull to verify auto-connect

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Co-authored-by: Fredrik Rombach Ekelund <fredrik.rombach.ekelund@automattic.com>

Author: 3 people

apps/cli/ai/system-prompt.ts

@@ -183,6 +183,7 @@ One \`Write\` or \`Edit\` per turn (read-only \`site_info\`, \`site_list\`, \`wp
 - take_screenshot: Take a full-page screenshot of a URL (supports desktop and mobile viewports). Use this to visually check the site after building it.
 - need_for_speed: Measure frontend performance metrics (TTFB, FCP, LCP, CLS, page weight, DOM size, JS/CSS/image/font asset breakdown) for a running site. Use this to identify performance bottlenecks and guide optimization.
 - rank_me_up: Run an on-page SEO audit (title/meta tags, headings, image alt text, OpenGraph/Twitter cards, JSON-LD structured data, robots.txt and sitemap.xml availability) for a running site. Use this to identify on-page SEO issues and guide fixes.
+- site_connected_remote_sites: List the WordPress.com sites already attached to a local site. Call this before site_push to decide how to ask the user which remote site to target.
 - site_push: Push a local site to a WordPress.com site. Requires authentication (studio auth login). Specify the remote site URL or ID and sync options (all, sqls, uploads, plugins, themes, contents).
 - site_pull: Pull a WordPress.com site to a local site. Requires authentication. Specify the remote site URL or ID and sync options.
 - site_import: Import a backup file (.zip, .tar.gz, .sql, .wpress) into a local site.
@@ -198,7 +199,18 @@ One \`Write\` or \`Edit\` per turn (read-only \`site_info\`, \`site_list\`, \`wp
 - Always enqueue the theme's style.css on the frontend from functions.php.
 - For theme and page content custom CSS, put the styles in the main style.css of the theme. No custom stylesheets.
 - Scroll animations must use progressive enhancement: CSS defines elements in their **final visible state** by default (full opacity, final position). JavaScript on the frontend adds the initial hidden state (e.g. \`opacity: 0\`, \`transform\`) and scroll-triggered transitions. This ensures elements are fully visible in the block editor (which loads theme CSS but not custom JS).
-- All animations and transitions must respect \`prefers-reduced-motion\`. Add a \`@media (prefers-reduced-motion: reduce)\` block that disables or simplifies animations (e.g. \`animation: none; transition: none; scroll-behavior: auto;\`).`;
+- All animations and transitions must respect \`prefers-reduced-motion\`. Add a \`@media (prefers-reduced-motion: reduce)\` block that disables or simplifies animations (e.g. \`animation: none; transition: none; scroll-behavior: auto;\`).
+
+## Push workflow
+
+When the user asks to push a site to WordPress.com, you MUST resolve the target remote site before calling \`site_push\`:
+
+1. Call \`site_connected_remote_sites\` with the local site's name or path to get the list of already-attached WordPress.com sites.
+2. Branch on how many remote sites are attached:
+   - **Exactly one attached site**: Use \`AskUserQuestion\` to confirm pushing to that site. Present two options labeled "Yes" and "No" with a description that includes the remote site's name and URL. Only call \`site_push\` if the user confirms.
+   - **Multiple attached sites**: Use \`AskUserQuestion\` with one question whose options are the attached sites (label = site name, description = URL). Then call \`site_push\` with the chosen site's ID or URL as \`remoteSite\`.
+   - **No attached sites**: Do NOT use \`AskUserQuestion\`. Ask an open-ended question in plain text for the URL or ID of the WordPress.com site to push to, then wait for the user's reply before calling \`site_push\`.
+3. Never call \`site_push\` without explicit user confirmation of the target — even when only one site is attached.`;
 }
 
 const REMOTE_SESSION_GUIDANCE = `## Telegram remote session

apps/cli/ai/tools/index.ts

@@ -7,6 +7,7 @@ import { deleteSiteTool } from './delete-site';
 import { exportSiteTool } from './export-site';
 import { importSiteTool } from './import-site';
 import { installTaxonomyScriptsTool } from './install-taxonomy-scripts';
+import { listConnectedRemoteSitesTool } from './list-connected-remote-sites';
 import { listPreviewsTool } from './list-previews';
 import { listSitesTool } from './list-sites';
 import { auditPerformanceTool } from './need-for-speed';
@@ -52,6 +53,7 @@ export const studioToolDefinitions = [
 	installTaxonomyScriptsTool,
 	auditPerformanceTool,
 	auditSeoTool,
+	listConnectedRemoteSitesTool,
 	pushSiteTool,
 	pullSiteTool,
 	importSiteTool,

apps/cli/ai/tools/list-connected-remote-sites.ts

@@ -0,0 +1,36 @@
+import { tool } from '@anthropic-ai/claude-agent-sdk';
+import { getConnectedWpcomSitesForLocalSite } from '@studio/common/lib/connected-sites';
+import { z } from 'zod/v4';
+import { errorResult, resolveSite, textResult } from './utils';
+
+export const listConnectedRemoteSitesTool = tool(
+	'site_connected_remote_sites',
+	'Lists the WordPress.com sites that are already connected/attached to a local Studio site. ' +
+		'Use this before calling site_push to determine how to ask the user which remote site to push to. ' +
+		'Returns an empty array when the user has no connections for that local site.',
+	{
+		nameOrPath: z.string().describe( 'The local site name or file system path' ),
+	},
+	async ( args ) => {
+		try {
+			const site = await resolveSite( args.nameOrPath );
+			const connected = await getConnectedWpcomSitesForLocalSite( site.id );
+			const summary = connected.map( ( s ) => ( {
+				id: s.id,
+				name: s.name,
+				url: s.url,
+				isStaging: s.isStaging,
+				syncSupport: s.syncSupport,
+				lastPushTimestamp: s.lastPushTimestamp,
+				lastPullTimestamp: s.lastPullTimestamp,
+			} ) );
+			return textResult( JSON.stringify( summary, null, 2 ) );
+		} catch ( error ) {
+			return errorResult(
+				`Failed to list connected remote sites: ${
+					error instanceof Error ? error.message : String( error )
+				}`
+			);
+		}
+	}
+);

apps/cli/commands/pull.ts

@@ -2,6 +2,10 @@ import fs from 'fs';
 import os from 'os';
 import path from 'path';
 import { confirm } from '@inquirer/prompts';
+import {
+	addConnectedWpcomSite,
+	markConnectedWpcomSiteSynced,
+} from '@studio/common/lib/connected-sites';
 import { readAuthToken } from '@studio/common/lib/shared-config';
 import {
 	SYNC_MAX_STALLED_ATTEMPTS,
@@ -189,6 +193,15 @@ export async function runCommand(
 			const siteUrl = getSiteUrl( site );
 			await fetch( siteUrl ).catch( () => {} );
 
+			// Remember this connection so future push/pull runs (and the Desktop UI)
+			// can surface it without re-selecting from the full site list.
+			try {
+				await addConnectedWpcomSite( site.id, { ...remoteSite, localSiteId: site.id } );
+				await markConnectedWpcomSiteSynced( site.id, remoteSite.id, 'pull' );
+			} catch ( error ) {
+				logger.reportError( new LoggerError( 'Failed to save connected site', error ), false );
+			}
+
 			logger.reportSuccess(
 				sprintf( __( 'Pulled from %s (%s)' ), remoteSite.name, remoteSite.url )
 			);

apps/cli/commands/push.ts

@@ -1,6 +1,10 @@
 import fs from 'fs';
 import os from 'os';
 import path from 'path';
+import {
+	addConnectedWpcomSite,
+	markConnectedWpcomSiteSynced,
+} from '@studio/common/lib/connected-sites';
 import { createDeployIgnoreFilter } from '@studio/common/lib/deploy-ignore';
 import { readAuthToken } from '@studio/common/lib/shared-config';
 import {
@@ -251,6 +255,15 @@ export async function runCommand(
 			);
 		}
 
+		// Remember this connection so future push/pull runs (and the Desktop UI)
+		// can surface it without re-selecting from the full site list.
+		try {
+			await addConnectedWpcomSite( site.id, { ...remoteSite, localSiteId: site.id } );
+			await markConnectedWpcomSiteSynced( site.id, remoteSite.id, 'push' );
+		} catch ( error ) {
+			logger.reportError( new LoggerError( 'Failed to save connected site', error ), false );
+		}
+
 		logger.reportSuccess(
 			sprintf( __( 'Successfully pushed to %s (%s)' ), remoteSite.name, remoteSite.url )
 		);

apps/cli/migrations/05-migrate-connected-sites-to-shared.ts

@@ -0,0 +1,78 @@
+/**
+ * Copies `connectedWpcomSites` from the Desktop-owned `app.json` into the
+ * shared `shared.json` so the CLI can read and write it through the helpers
+ * in `tools/common/lib/connected-sites.ts`.
+ *
+ * Runs only when app.json carries the legacy field AND shared.json does not
+ * already have it — the CLI must never modify app.json. The Studio app runs
+ * its own migration to strip the field once it boots; until then the legacy
+ * copy in app.json is harmless because both the new Studio and the new CLI
+ * read connections from shared.json.
+ */
+
+import fs from 'node:fs';
+import {
+	lockSharedConfig,
+	readSharedConfig,
+	saveSharedConfig,
+	unlockSharedConfig,
+} from '@studio/common/lib/shared-config';
+import { getAppConfigPath } from '@studio/common/lib/well-known-paths';
+import { syncSiteSchema } from '@studio/common/types/sync';
+import { readFile } from 'atomically';
+import { z } from 'zod';
+import type { Migration } from '@studio/common/lib/migration';
+
+const appConnectedShapeSchema = z
+	.object( {
+		connectedWpcomSites: z.record( z.string(), z.array( syncSiteSchema ) ).optional(),
+	} )
+	.loose();
+
+async function readAppConnectedSites(): Promise< Record<
+	string,
+	z.infer< typeof syncSiteSchema >[]
+> | null > {
+	const appPath = getAppConfigPath();
+	if ( ! fs.existsSync( appPath ) ) {
+		return null;
+	}
+	try {
+		const raw = await readFile( appPath, { encoding: 'utf8' } );
+		const parsed = appConnectedShapeSchema.safeParse( JSON.parse( raw ) );
+		if ( ! parsed.success ) {
+			return null;
+		}
+		return parsed.data.connectedWpcomSites ?? null;
+	} catch {
+		return null;
+	}
+}
+
+export const migrateConnectedSitesToShared: Migration = {
+	async needsToRun() {
+		const appConnected = await readAppConnectedSites();
+		if ( ! appConnected || Object.keys( appConnected ).length === 0 ) {
+			return false;
+		}
+		const shared = await readSharedConfig().catch( () => null );
+		return ! shared?.connectedWpcomSites;
+	},
+
+	async run() {
+		const appConnected = await readAppConnectedSites();
+		if ( ! appConnected || Object.keys( appConnected ).length === 0 ) {
+			return;
+		}
+		try {
+			await lockSharedConfig();
+			const shared = await readSharedConfig();
+			if ( shared.connectedWpcomSites ) {
+				return;
+			}
+			await saveSharedConfig( { ...shared, connectedWpcomSites: appConnected } );
+		} finally {
+			await unlockSharedConfig();
+		}
+	},
+};

apps/cli/migrations/index.ts

@@ -2,11 +2,13 @@ import { checkStudioCompatibilityForInitialMigration } from './00-check-studio-c
 import { hideStudioDirWindows } from './01-hide-studio-dir-windows';
 import { renameProcessManagerHome } from './03-rename-pm-home';
 import { cleanupObsoleteServerFiles } from './04-cleanup-obsolete-server-files';
+import { migrateConnectedSitesToShared } from './05-migrate-connected-sites-to-shared';
 import type { Migration } from '@studio/common/lib/migration';
 
 export const migrations: Migration[] = [
 	checkStudioCompatibilityForInitialMigration,
 	hideStudioDirWindows,
 	renameProcessManagerHome,
 	cleanupObsoleteServerFiles,
+	migrateConnectedSitesToShared,
 ];

apps/cli/package.json

@@ -65,6 +65,7 @@
 		"build:npm": "vite build --config ./vite.config.npm.ts",
 		"install:bundle": "npm install --omit=dev --no-package-lock --no-progress --install-links --no-workspaces && patch-package && node ../../scripts/remove-fs-ext-other-platform-binaries.mjs",
 		"package": "npm run install:bundle && npm run build:prod",
+		"lint": "eslint .",
 		"watch": "vite build --config ./vite.config.dev.ts --watch",
 		"prepublishOnly": "npm run build:npm",
 		"postinstall": "node scripts/postinstall-npm.mjs",

apps/studio/package.json

@@ -21,6 +21,7 @@
 		"make:linux-x64": "electron-vite build --config ./electron.vite.config.ts --outDir=dist && electron-forge make . --arch=x64 --platform=linux",
 		"make:linux-arm64": "electron-vite build --config ./electron.vite.config.ts --outDir=dist && electron-forge make . --arch=arm64 --platform=linux",
 		"install:bundle": "npm install --no-package-lock --no-progress --install-links --no-workspaces && patch-package && node ../../scripts/remove-fs-ext-other-platform-binaries.mjs",
+		"lint": "eslint src e2e",
 		"package": "electron-vite build --config ./electron.vite.config.ts --outDir=dist && electron-forge package .",
 		"publish": "electron-forge publish .",
 		"start-wayland": "npm -w wp-studio run build && electron-forge start . -- --enable-features=UseOzonePlatform --ozone-platform=wayland",

apps/studio/src/ipc-handlers.ts

@@ -35,6 +35,7 @@ import {
 } from '@studio/common/lib/agent-skills';
 import { validateBlueprintData } from '@studio/common/lib/blueprint-validation';
 import { parseCliError, errorMessageContains } from '@studio/common/lib/cli-error';
+import { getConnectedWpcomSitesForLocalSite } from '@studio/common/lib/connected-sites';
 import { createDeployIgnoreFilter } from '@studio/common/lib/deploy-ignore';
 import { extractZip } from '@studio/common/lib/extract-zip';
 import {
@@ -52,11 +53,7 @@ import { isMultisite } from '@studio/common/lib/is-multisite';
 import { getAuthenticationUrl } from '@studio/common/lib/oauth';
 import { decodePassword, encodePassword } from '@studio/common/lib/passwords';
 import { sanitizeFolderName } from '@studio/common/lib/sanitize-folder-name';
-import {
-	getCurrentUserId,
-	readSharedConfig,
-	updateSharedConfig,
-} from '@studio/common/lib/shared-config';
+import { readSharedConfig, updateSharedConfig } from '@studio/common/lib/shared-config';
 import { SYNC_IGNORE_DEFAULTS } from '@studio/common/lib/sync/constants';
 import { shouldExcludeFromSync } from '@studio/common/lib/sync/exclude-from-sync';
 import { shouldLimitDepth } from '@studio/common/lib/sync/tree-utils';
@@ -270,12 +267,7 @@ async function reconcileSessionEnvironmentBeforeRun( sessionId: string ): Promis
 		return;
 	}
 
-	const currentUserId = await getCurrentUserId();
-	const userData = currentUserId ? await loadUserData() : undefined;
-	const connected = userData?.connectedWpcomSites?.[ currentUserId! ] ?? [];
-	const connectedForOwner = connected.filter(
-		( site ) => site.localSiteId === ownerServer.details.id
-	);
+	const connectedForOwner = await getConnectedWpcomSitesForLocalSite( ownerServer.details.id );
 	const connectedIds = new Set( connectedForOwner.map( ( site ) => site.id ) );
 
 	const effective = deriveEffectiveEnvironment( summary, ( blogId ) => connectedIds.has( blogId ) );
@@ -376,10 +368,7 @@ export async function setSessionEnvironment(
 	const timestamp = new Date().toISOString();
 
 	if ( environment === 'live' ) {
-		const currentUserId = await getCurrentUserId();
-		const userData = currentUserId ? await loadUserData() : undefined;
-		const connected = userData?.connectedWpcomSites?.[ currentUserId! ] ?? [];
-		const candidates = connected.filter( ( s ) => s.localSiteId === ownerServer.details.id );
+		const candidates = await getConnectedWpcomSitesForLocalSite( ownerServer.details.id );
 		// Prefer the production (non-staging) site to match the UI's
 		// `pickLiveSite` behavior in the site dropdown.
 		const liveSite = candidates.find( ( s ) => ! s.isStaging ) ?? candidates[ 0 ];