Migrate appdata to ~/.studio/appdata.json with versioned migrations by bcotrim · Pull Request #2836 · Automattic/studio

bcotrim · 2026-03-17T19:28:21Z

Related issues

How AI was used in this PR

All code was generated via Claude Code (Opus + Haiku). Changes were reviewed and validated through iterative conversation with the user.

Proposed Changes

CLI _migrate command — Hidden command that copies appdata-v1.json from platform-specific Electron path to ~/.studio/appdata.json
Desktop bootstrap — Triggers CLI migration on boot before other data operations
Updated primary paths — Desktop and CLI both read from ~/.studio/appdata.json with CLI fallback to old platform-specific location
Generic migration framework — New ConfigMigrator in tools/common/lib/ that applies versioned migrations based on file version field
Wired into config readers — Appdata, CLI config, and shared config all use the migration runner for future extensibility

Testing Instructions

npm run typecheck — Verify no type errors
npm test — All 1314 tests pass (7 new tests for config migrator)
Manual: Launch Desktop with existing appdata-v1.json → Verify ~/.studio/appdata.json is created and Desktop reads from it
Manual: Add/modify a site → Verify ~/.studio/appdata.json is updated
Manual: CLI studio site list → Verify reads from ~/.studio/appdata.json
Manual: Restart Desktop → Verify migration is idempotent (no errors)

Pre-merge Checklist

Have you checked for TypeScript, React or other console errors?

…ramework

fredrikekelund · 2026-03-18T15:07:58Z

apps/cli/index.ts

+		.middleware( async () => {
+			try {
+				const { migrateAppdata } = await import( 'cli/commands/_migrate' );
+				await migrateAppdata();
+			} catch ( error ) {
+				// Migration failure should not block CLI usage
+				console.error( 'Appdata migration failed:', error );
+			}
+		} )


The Studio app should be responsible for migrating the data (or at least pushing the trigger). If the standalone CLI does it automatically, then we cannot guarantee that the installed version of Studio can handle the current config setup. That's because theoretically, someone can have Studio 1.7.6 installed and install and run the standalone CLI. This code will make the standalone CLI run the migration on every run.

I think this logic should be a check rather than a migration. It should run for every command except _migrate. If the Studio app is installed and ~/.studio/shared.json is missing, it should return an error message prompting the user to update Studio. If Studio isn't installed, just proceed. If Studio is installed and the shared config exists, just proceed.

…nto stu-1350-decoupled-config-dev-v3 # Conflicts: # apps/cli/lib/appdata.ts # apps/cli/lib/tests/appdata.test.ts

…pdata.json

fredrikekelund

The basics of the migration works, but we need to address the fact that we still expect the appdata file to contain a sites array in some places.

fredrikekelund · 2026-03-19T13:26:33Z

apps/studio/src/storage/paths.ts

 		return process.env.DEV_APP_DATA_PATH;
 	}
-	return path.join( getAppDataPath(), getAppName(), 'appdata-v1.json' );
+	return path.join( getStudioHome(), 'appdata.json' );


Do we want to keep calling it "appdata" or maybe just "app"? I don't really have a preference, but since we're calling the CLI config file "cli.json", I guess there's an argument for "app.json" being a good fit…

fredrikekelund · 2026-03-19T14:04:08Z

apps/studio/src/storage/storage-types.ts

@@ -28,7 +28,7 @@ export interface UserData {
 }

 export interface PersistedUserData extends Omit< UserData, 'sites' > {


I commented about this on Slack, too, but appdata.json no longer contains any sites.

fredrikekelund · 2026-03-19T14:11:18Z

apps/studio/src/migrations/migrate-appdata-via-cli.ts

+function pickAppdataSiteFields( site: Record< string, unknown > ): Record< string, unknown > {
+	const result: Record< string, unknown > = {};
+	for ( const key of Object.keys( site ) ) {
+		if ( ! excludedSiteFields.has( key ) ) {
+			result[ key ] = site[ key ];
+		}
+	}
+	// Always keep id so we can correlate with cli.json sites
+	if ( site.id ) {
+		result.id = site.id;
+	}
+	return result;
+}


I don't understand what this function is for

fredrikekelund · 2026-03-19T14:12:25Z

apps/studio/src/migrations/migrate-appdata-via-cli.ts

+	if ( Array.isArray( oldData.sites ) ) {
+		const sitesWithDesktopFields = oldData.sites
+			.map( ( site: Record< string, unknown > ) => pickAppdataSiteFields( site ) )
+			.filter( ( site: Record< string, unknown > ) =>
+				Object.keys( site ).some( ( key ) => key !== 'id' && site[ key ] !== undefined )
+			);
+
+		if ( sitesWithDesktopFields.length > 0 ) {
+			config.sites = sitesWithDesktopFields;
+		}
+	}


The appdata file shouldn't contain any sites, though, right?

fredrikekelund · 2026-03-19T14:14:01Z

apps/studio/src/migrations/00-migrate-to-split-config.ts

+function buildSharedConfig( oldData: Record< string, unknown > ): Record< string, unknown > {
+	return { version: 1, ...pick( oldData, sharedConfigFields ) };
+}


Suggested change

function buildSharedConfig( oldData: Record< string, unknown > ): Record< string, unknown > {

return { version: 1, ...pick( oldData, sharedConfigFields ) };

}

function buildSharedConfig( oldData: Record< string, unknown > ): Record< string, unknown > {

const schema = z.object( { ...sharedConfigSchema.omit( { version: true } ).shape } );

const parsed = schema.parse( oldData );

return { version: 1, ...parsed };

}

I think it'd be a good idea to lean into zod parsing here, too. If oldData doesn't pass validation, then it would cause an error the next time the CLI or the app tries to read that file.

I had to play around with the schema definition a little, but this suggestion works. We want to get rid of the .loose() call from the original definition – that's why we jump through the extra hoops

fredrikekelund · 2026-03-19T14:14:51Z

apps/studio/src/migrations/00-migrate-to-split-config.ts

+	if ( Array.isArray( oldData.sites ) ) {
+		config.sites = oldData.sites.map( ( site: Record< string, unknown > ) =>
+			pick( site, cliSiteFields )
+		);
+	}


Suggested change

if ( Array.isArray( oldData.sites ) ) {

config.sites = oldData.sites.map( ( site: Record< string, unknown > ) =>

pick( site, cliSiteFields )

);

}

const cliSiteSchema = siteDetailsSchema.extend( {

url: z.string().optional(),

latestCliPid: z.number().optional(),

} );

if ( Array.isArray( oldData.sites ) ) {

config.sites = oldData.sites.map( ( site: Record< string, unknown > ) =>

cliSiteSchema.parse( site )

);

}

Same thing here about leaning into zod parsing, because that's the schema we expect the file to conform to later, anyway.

fredrikekelund · 2026-03-19T14:37:11Z

apps/studio/src/migrations/migrate-appdata-via-cli.ts

+/**
+ * Fields from the old appdata that stay in the new appdata.json.
+ * Sites keep only Desktop-specific fields (themeDetails, sortOrder).
+ *
+ * We derive the "keep" set by excluding fields that moved to shared.json or cli.json.
+ */
+const movedTopLevelFields = new Set( [ ...sharedConfigFields, 'sites', 'snapshots', 'version' ] );
+
+// Per-site fields that stay in appdata.json: anything NOT in the CLI site schema,
+// NOT in the snapshot schema, and NOT runtime state.
+const excludedSiteFields = new Set( [
+	...cliSiteFields,
+	...Object.keys( snapshotSchema.shape ),
+	'running',
+] );


I don't believe running was ever stored anywhere – it comes from the runtime type. As for themeDetails, we need to figure something out…

We might consider adding an array or a record of themeDetails entries to appdata.json. WDYT? It would take some plumbing to get right and to ensure we clean it up when a site is deleted, but it shouldn't be overly complex.

…ecord<id, AppdataSiteData>

…sing in migration

bcotrim · 2026-03-19T17:06:27Z

@fredrikekelund thanks for the review!
We still need to store some sites information in the app.json file (themeDetails and sortOrder)
I renamed the field to siteMetadata to make the intention clearer. Let me know how it looks.

…nto stu-1350-decoupled-config-dev-v3

bcotrim · 2026-03-19T20:09:26Z

@fredrikekelund E2E tests should be fixed now. I intentionally left the appdata-v1 setup logic in E2E tests so the migration is tested on all tests. We can later decide to keep it or update the E2E to setup the new config files instead.

…ants

…config-dev-v3

Migrate appdata to ~/.studio/appdata.json with extensible migration f…

cfa000f

…ramework

bcotrim self-assigned this Mar 17, 2026

Merge stu-1350-decoupled-config-dev and resolve conflicts

9d5ead9

fredrikekelund reviewed Mar 18, 2026

View reviewed changes

bcotrim added 3 commits March 18, 2026 21:12

Move appdata migration from CLI to Studio Desktop

aeb2e3a

Merge remote-tracking branch 'origin/stu-1350-decoupled-config-dev' i…

7a34728

…nto stu-1350-decoupled-config-dev-v3 # Conflicts: # apps/cli/lib/appdata.ts # apps/cli/lib/tests/appdata.test.ts

Rewrite appdata migration to split into shared.json, cli.json, and ap…

a6a3838

…pdata.json

bcotrim marked this pull request as ready for review March 18, 2026 23:23

bcotrim added 3 commits March 18, 2026 23:24

trigger ci

63b8b8e

Ensure .studio directory exists before lockfile and fix import order

46b0358

Fix readFile mock type to return Buffer instead of string

4dd6080

fredrikekelund reviewed Mar 19, 2026

View reviewed changes

bcotrim added 2 commits March 19, 2026 16:17

Refactor appdata to store only Desktop-specific state with sites as R…

852cdc9

…ecord<id, AppdataSiteData>

Address PR feedback: rename to app.json and siteMetadata, use zod par…

92d5be2

…sing in migration

bcotrim added 3 commits March 19, 2026 17:09

Fix prettier formatting in user-data test

29fa739

Fix e2e migration by respecting E2E_APP_DATA_PATH in getOldAppdataPath

a317a82

Merge remote-tracking branch 'origin/stu-1350-decoupled-config-dev' i…

6db60dd

…nto stu-1350-decoupled-config-dev-v3

bcotrim added 6 commits March 20, 2026 13:57

new migration interface

0bd4c58

studio migrations

f8e9258

studio migrations

aca873d

cli migrations

ef52842

Rename appdata references, centralize config paths and lockfile const…

cea5b56

…ants

Isolate e2e config directory to fix test failures

f211f3a

bcotrim requested a review from fredrikekelund March 20, 2026 17:23

Merge branch 'stu-1350-decoupled-config-dev' into stu-1350-decoupled-…

e58b6d4

…config-dev-v3

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Migrate appdata to ~/.studio/appdata.json with versioned migrations#2836

Migrate appdata to ~/.studio/appdata.json with versioned migrations#2836
bcotrim wants to merge 20 commits intostu-1350-decoupled-config-devfrom
stu-1350-decoupled-config-dev-v3

bcotrim commented Mar 17, 2026

Uh oh!

fredrikekelund Mar 18, 2026

Uh oh!

fredrikekelund left a comment

Uh oh!

fredrikekelund Mar 19, 2026

Uh oh!

fredrikekelund Mar 19, 2026

Uh oh!

fredrikekelund Mar 19, 2026

Uh oh!

fredrikekelund Mar 19, 2026

Uh oh!

fredrikekelund Mar 19, 2026

Uh oh!

fredrikekelund Mar 19, 2026

Uh oh!

fredrikekelund Mar 19, 2026

Uh oh!

bcotrim commented Mar 19, 2026

Uh oh!

bcotrim commented Mar 19, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

		@@ -28,7 +28,7 @@ export interface UserData {
		}

		export interface PersistedUserData extends Omit< UserData, 'sites' > {

Conversation

bcotrim commented Mar 17, 2026

Related issues

How AI was used in this PR

Proposed Changes

Testing Instructions

Pre-merge Checklist

Uh oh!

Choose a reason for hiding this comment

Uh oh!

fredrikekelund left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bcotrim commented Mar 19, 2026

Uh oh!

bcotrim commented Mar 19, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants