Route theme mutations through requestThemeAdminDoc

[iaineh]

WHY are these changes introduced?

Theme reads (theme pull, theme list, theme info, ...) already go through requestThemeAdminDoc, which turns an ACCESS_DENIED GraphQL error into a friendly message that names the missing scope. Theme mutations still called adminRequestDoc directly, so the same error surfaced as a raw GraphQL failure.

This also creates the single wrapper that #8562 needs for Trust Battery challenge handling.

WHAT is this pull request doing?

• Moves themePublish from adminRequestDoc to requestThemeAdminDoc for the missing-scope message that theme reads already show.
• Moves themeDelete from adminRequestDoc to requestThemeAdminDoc for the missing-scope message that theme reads already show.
• Moves themeUpdate from adminRequestDoc to requestThemeAdminDoc for the missing-scope message that theme reads already show.
• Moves themeDuplicate from adminRequestDoc to requestThemeAdminDoc for the missing-scope message that theme reads already show.
• Moves deleteThemeAssets (ThemeFilesDelete) from adminRequestDoc to requestThemeAdminDoc for the missing-scope message that theme reads already show.
• Moves uploadFiles (ThemeFilesUpsert) from adminRequestDoc to requestThemeAdminDoc for the missing-scope message that theme reads already show.
• Changes abortIfMissingThemeAccessScope from ClientError only to ClientError or GraphQLClientError, because theme mutations keep the default Admin error handling, which maps the ClientError to a GraphQLClientError before the check runs. Without this, the six mutations above never show the missing-scope message.
• Adds tests for themePublish and themeDelete that assert the write_themes missing-scope abort. They reject with the output of the real errorHandler('Admin'), which is what a mutation gets. The existing read tests keep the raw ClientError, because reads pass handleErrors: false.
• Adds extractGraphQLErrors to private/node/api/graphql.ts, next to errorHandler, for one reader of the GraphQL errors before and after mapping. The scope check uses it, and Handle Trust Battery challenges in theme commands #8562's challenge check uses it too. A test proves that errorHandler keeps the errors that both checks read.

fetchTheme, metafieldDefinitionsByOwnerType, and passwordProtected stay on adminRequestDoc: their queries read no theme files, so no theme decision runs for them on Core's side.

Checklist

• I've considered possible cross-platform impacts (Mac, Linux, Windows)
• I've considered possible documentation changes
• I've considered analytics changes to measure impact
• The change is user-facing — I've identified the correct bump type (patch for bug fixes · minor for new features · major for breaking changes) and added a changeset with pnpm changeset add

[Copilot]

🟡 Changes recommended

Default error mapping prevents all six migrated requests from reaching the intended missing-scope handling.

1 open finding

• Disable GraphQL error mapping for migrated theme API calls · New

What changed in this PR

Routes theme mutations through the shared theme request wrapper to improve missing-scope errors and prepare for Trust Battery handling in #8562.

Changes:

• Migrates six mutation requests to requestThemeAdminDoc.
• Adds missing-scope tests for publishing and deletion.
• Adds a patch changeset.

File	Description
packages/​cli-kit/​src/​public/​node/​themes/​api.ts	Routes six mutations through the shared wrapper.
packages/​cli-kit/​src/​public/​node/​themes/​api.test.ts	Tests publishing and deletion scope errors.
.changeset/​theme-mutations-missing-scope.md	Documents the intended error-message improvement.

🧠 Review effort: Balanced

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[catlee]

Looks good. Two non-blocking notes inline.

---

Generated with Pi.

[github-actions]

Differences in type declarations

We detected differences in the type declarations generated by Typescript for this branch compared to the baseline ('main' branch). Please, review them to ensure they are backward-compatible. Here are some important things to keep in mind:

• Some seemingly private modules might be re-exported through public modules.
• If the branch is behind main you might see odd diffs, rebase main into this branch.

New type declarations

We found no new type declarations in this PR

Existing type declarations

packages/cli-kit/dist/private/node/api/graphql.d.ts

@@ -1,4 +1,4 @@
-import { Variables } from 'graphql-request';
+import { ClientError, Variables } from 'graphql-request';
 export declare function debugLogRequestInfo(api: string, query: string, url: string, variables?: Variables, headers?: Record<string, string>): void;
 export declare function sanitizeVariables(variables: Variables): string;
 /**
@@ -11,4 +11,5 @@ export declare function sanitizeVariables(variables: Variables): string;
  * the full JSON representation if no messages can be extracted.
  */
 export declare function extractGraphQLErrorMessages(errors: any[] | undefined): string | undefined;
-export declare function errorHandler(api: string): (error: unknown, requestId?: string) => unknown;
\ No newline at end of file
+export declare function errorHandler(api: string): (error: unknown, requestId?: string) => unknown;
+export declare function extractGraphQLErrors(error: unknown): NonNullable<ClientError['response']['errors']>;
\ No newline at end of file