Handle missing theme write access during theme creation

[mbarak]

WHY are these changes introduced?

When theme commands create a development theme with an account or Admin API token that cannot access themeCreate, the Admin GraphQL API returns an ACCESS_DENIED error with requiredAccess details. fetchThemes and related read paths already map this shape to a friendly AbortError, but themeCreate still called adminRequestDoc directly and surfaced the raw GraphQL ClientError payload.

This addresses the latest-version write_themes / themeCreate tail under the linked issue; the broader Observe grouping also contains unrelated GraphQL failures that should be re-scoped separately.

WHAT is this pull request doing?

• Routes themeCreate through the theme Admin request wrapper so missing theme access is reported with the existing friendly next steps.
• Normalizes requiredAccess text that starts with The user needs ... so the rendered error sentence reads cleanly.
• Adds a focused themeCreate regression test.

How to test your changes?

• pnpm --filter @shopify/cli-kit vitest run src/public/node/themes/api.test.ts
• pnpm --filter @shopify/cli-kit lint
• pnpm --filter @shopify/cli-kit type-check

Resolves: https://github.com/shop/issues/issues/32995

Co-authored-by: Pi AI noreply@pi.dev

[Copilot]

Pull request overview

This PR improves the UX for themeCreate failures when the authenticated identity lacks theme write access by routing the mutation through the existing theme Admin request wrapper that already converts ACCESS_DENIED + requiredAccess GraphQL errors into a friendly AbortError.

Changes:

• Route themeCreate through requestThemeAdminDoc so missing theme access produces the established friendly error/next-steps instead of a raw GraphQL ClientError.
• Normalize requiredAccess strings (strip trailing period and leading “The user needs …”) so the rendered error reads cleanly.
• Add a regression test covering the themeCreate access-denied path, and include a changeset documenting the user-visible behavior change.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated no comments.

File	Description
packages/cli-kit/src/public/node/themes/api.ts	Route themeCreate via the theme request wrapper and introduce requiredAccess formatting for cleaner abort messaging.
packages/cli-kit/src/public/node/themes/api.test.ts	Add a regression test for friendly access-denied messaging and extend the test helper to support non-themes fields.
.changeset/friendly-theme-create-access-error.md	Add a patch changeset describing the improved error behavior for denied theme creation.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[graygilmore]

/snapit

[github-actions]

🫰✨ Thanks @graygilmore! Your snapshot has been published to npm.

Test the snapshot by installing your package globally:

pnpm i -g --@shopify:registry=https://registry.npmjs.org @shopify/cli@0.0.0-snapshot-20260629170420

Caution

After installing, validate the version by running shopify version in your terminal.
If the versions don't match, you might have multiple global instances installed.
Use which shopify to find out which one you are running and uninstall it.

[graygilmore]

The formatting is a little off but I don't think that's the fault of this PR:

➜ ~/r/test-theme git:(main) shopify theme dev --store <SNIP> --password <SNIP>
╭─ error ──────────────────────────────────────────────────────────────────────────────────────────╮
│                                                                                                  │
│  The authenticated account or access token is missing write_themes and an exemption from         │
│  Shopify to modify themes.                                                                       │
│              If you think that your app is eligible for an exemption and should have access to   │
│  this API,                                                                                       │
│                then you can submit an exception request [1].                                     │
│                                                                                                  │
│  Next steps                                                                                      │
│    • If you authenticated with an Admin API access token, update the app or integration that     │
│      issued the token to include the required theme access scopes, then reauthorize it or        │
│      generate a new token.                                                                       │
│    • For `theme pull`, `theme list`, and `theme info`, add the `read_themes` scope.              │
│    • For `theme push` and `theme dev`, add both the `read_themes` and `write_themes` scopes.     │
│    • If you authenticated with your Shopify account, make sure your staff or collaborator        │
│      account can access Online Store themes, then run `shopify auth logout` and try again.       │
│    • See Shopify access scopes [2].                                                              │
│                                                                                                  │
╰──────────────────────────────────────────────────────────────────────────────────────────────────╯
[1] https://docs.google.com/forms/d/e/1FAIpQLSfZTB1vxFC5d1-GPdqYunWRGUoDcOheHQzfK2RoEFEHrknt5g/viewform
[2] https://shopify.dev/api/usage/access-scopes