Stop reporting expected Admin API failures from store execute as CLI bugs

Two error shapes from the Admin API were being misclassified as
`BugError` and reported to Observe (issue shop/issues#32996):

- HTTP 402 "Unavailable Shop" \u2014 the shop is frozen / on hold; this is a
  store-state issue, not a CLI bug.
- "The user aborted a request." \u2014 surfaces from node-fetch when an
  AbortController signal fires (CLI-side fetch timeout or user cancel).

Both were getting wrapped by `fetchApiVersions`'s "unknown error" catch
in cli-kit, which destroys the original error type. To classify them
locally without reaching past the public API, `store execute` now drives
its API-version lookup directly via `graphqlRequest` against an inline
`publicApiVersions` query \u2014 the same primitive `admin-transport.ts` uses
for the user's query. Both phases now see raw `ClientError` /
`Error` shapes and share a single classifier in `admin-errors.ts`.

Other commands that hit the Admin API on startup are unaffected; cli-kit
is untouched.

- `packages/store/.../execute/admin-errors.ts` (new): structural
  `ClientError` shape check, abort detection, and `classifyAdminApiError`
  that maps known non-bug shapes to user-facing `AbortError`s.
- `packages/store/.../execute/admin-context.ts`: drives the version
  lookup via `graphqlRequest` directly. 401/404 still trigger the
  re-auth path (now via structural status check rather than parsing
  message strings); 402 and aborts go through the shared classifier.
- `packages/store/.../execute/admin-transport.ts`: same shared
  classifier covers aborts on the execute-phase request.

New `admin-errors.test.ts` covers the classifier; existing context and
transport tests updated to mock `graphqlRequest` directly.

Author: dmerand

packages/store/src/cli/services/store/execute/admin-context.test.ts

@@ -1,22 +1,16 @@
 import {prepareAdminStoreGraphQLContext} from './admin-context.js'
-import {clearStoredStoreAppSession} from '../auth/session-store.js'
+import {fetchPublicApiVersions} from './admin-transport.js'
 import {loadStoredStoreSession} from '../auth/session-lifecycle.js'
 import {STORE_AUTH_APP_CLIENT_ID} from '../auth/config.js'
 import {AbortError} from '@shopify/cli-kit/node/error'
-import {fetchApiVersions} from '@shopify/cli-kit/node/api/admin'
 import {beforeEach, describe, expect, test, vi} from 'vitest'
 
-vi.mock('../auth/session-store.js')
 vi.mock('../auth/session-lifecycle.js', () => ({loadStoredStoreSession: vi.fn()}))
-vi.mock('@shopify/cli-kit/node/api/admin', async () => {
-  const actual = await vi.importActual<typeof import('@shopify/cli-kit/node/api/admin')>(
-    '@shopify/cli-kit/node/api/admin',
-  )
-  return {
-    ...actual,
-    fetchApiVersions: vi.fn(),
-  }
-})
+vi.mock('./admin-transport.js', () => ({
+  fetchPublicApiVersions: vi.fn(),
+  // runAdminStoreGraphQLOperation isn't exercised here, but we re-export it for type completeness.
+  runAdminStoreGraphQLOperation: vi.fn(),
+}))
 
 describe('prepareAdminStoreGraphQLContext', () => {
   const store = 'shop.myshopify.com'
@@ -32,26 +26,23 @@ describe('prepareAdminStoreGraphQLContext', () => {
 
   beforeEach(() => {
     vi.mocked(loadStoredStoreSession).mockResolvedValue(storedSession)
-    vi.mocked(fetchApiVersions).mockResolvedValue([
+    vi.mocked(fetchPublicApiVersions).mockResolvedValue([
       {handle: '2025-10', supported: true},
       {handle: '2025-07', supported: true},
       {handle: 'unstable', supported: false},
-    ] as any)
+    ])
   })
 
   test('returns the stored admin session, version, and full auth session', async () => {
     const result = await prepareAdminStoreGraphQLContext({store})
 
     expect(loadStoredStoreSession).toHaveBeenCalledWith(store)
-    expect(fetchApiVersions).toHaveBeenCalledWith({
-      token: 'token',
-      storeFqdn: store,
+    expect(fetchPublicApiVersions).toHaveBeenCalledWith({
+      adminSession: {token: 'token', storeFqdn: store},
+      session: storedSession,
     })
     expect(result).toEqual({
-      adminSession: {
-        token: 'token',
-        storeFqdn: store,
-      },
+      adminSession: {token: 'token', storeFqdn: store},
       version: '2025-10',
       session: storedSession,
     })
@@ -68,9 +59,9 @@ describe('prepareAdminStoreGraphQLContext', () => {
 
     const result = await prepareAdminStoreGraphQLContext({store})
 
-    expect(fetchApiVersions).toHaveBeenCalledWith({
-      token: 'fresh-token',
-      storeFqdn: store,
+    expect(fetchPublicApiVersions).toHaveBeenCalledWith({
+      adminSession: {token: 'fresh-token', storeFqdn: store},
+      session: refreshedSession,
     })
     expect(result.adminSession.token).toBe('fresh-token')
     expect(result.session).toEqual(refreshedSession)
@@ -82,36 +73,27 @@ describe('prepareAdminStoreGraphQLContext', () => {
     expect(result.version).toBe('2025-07')
   })
 
-  test('allows unstable without validating against fetched versions', async () => {
+  test('allows unstable without consulting the transport, but still loads the stored session', async () => {
     const result = await prepareAdminStoreGraphQLContext({store, userSpecifiedVersion: 'unstable'})
 
-    expect(result.version).toBe('unstable')
-    expect(fetchApiVersions).not.toHaveBeenCalled()
-  })
-
-  test('clears the current stored auth and prompts re-auth with real scopes when API version lookup gets invalid auth', async () => {
-    vi.mocked(fetchApiVersions).mockRejectedValue(
-      new AbortError(`Error connecting to your store ${store}: unauthorized 401 {}`),
-    )
-
-    await expect(prepareAdminStoreGraphQLContext({store})).rejects.toMatchObject({
-      message: `Stored app authentication for ${store} is no longer valid.`,
-      tryMessage: 'To re-authenticate, run:',
-      nextSteps: [[{command: `shopify store auth --store ${store} --scopes read_products,write_orders`}]],
+    expect(loadStoredStoreSession).toHaveBeenCalledWith(store)
+    expect(result).toEqual({
+      adminSession: {token: 'token', storeFqdn: store},
+      version: 'unstable',
+      session: storedSession,
     })
-    expect(clearStoredStoreAppSession).toHaveBeenCalledWith(store, '42')
-  })
-
-  test('rethrows unrelated API version lookup failures', async () => {
-    vi.mocked(fetchApiVersions).mockRejectedValue(new AbortError('upstream exploded'))
-
-    await expect(prepareAdminStoreGraphQLContext({store})).rejects.toThrow('upstream exploded')
-    expect(clearStoredStoreAppSession).not.toHaveBeenCalled()
+    expect(fetchPublicApiVersions).not.toHaveBeenCalled()
   })
 
   test('throws when the requested API version is invalid', async () => {
     await expect(prepareAdminStoreGraphQLContext({store, userSpecifiedVersion: '1999-01'})).rejects.toThrow(
       'Invalid API version',
     )
   })
+
+  test('rethrows whatever the transport raises (errors are owned by the transport)', async () => {
+    vi.mocked(fetchPublicApiVersions).mockRejectedValue(new AbortError('upstream exploded'))
+
+    await expect(prepareAdminStoreGraphQLContext({store})).rejects.toThrow('upstream exploded')
+  })
 })

packages/store/src/cli/services/store/execute/admin-context.ts

@@ -1,7 +1,5 @@
-import {throwReauthenticateStoreAuthError} from '../auth/recovery.js'
-import {clearStoredStoreAppSession} from '../auth/session-store.js'
+import {fetchPublicApiVersions} from './admin-transport.js'
 import {loadStoredStoreSession} from '../auth/session-lifecycle.js'
-import {fetchApiVersions} from '@shopify/cli-kit/node/api/admin'
 import {AbortError} from '@shopify/cli-kit/node/error'
 import type {AdminSession} from '@shopify/cli-kit/node/session'
 import type {StoredStoreAppSession} from '../auth/session-store.js'
@@ -21,25 +19,7 @@ async function resolveApiVersion(options: {
 
   if (userSpecifiedVersion === 'unstable') return userSpecifiedVersion
 
-  let availableVersions
-  try {
-    availableVersions = await fetchApiVersions(adminSession)
-  } catch (error) {
-    if (
-      error instanceof AbortError &&
-      error.message.includes(`Error connecting to your store ${adminSession.storeFqdn}:`) &&
-      /\b(?:401|404)\b/.test(error.message)
-    ) {
-      clearStoredStoreAppSession(session.store, session.userId)
-      throwReauthenticateStoreAuthError(
-        `Stored app authentication for ${session.store} is no longer valid.`,
-        session.store,
-        session.scopes.join(','),
-      )
-    }
-
-    throw error
-  }
+  const availableVersions = await fetchPublicApiVersions({adminSession, session})
 
   if (!userSpecifiedVersion) {
     const supportedVersions = availableVersions.filter((version) => version.supported).map((version) => version.handle)