Document theme info JSON schema

Assisted-By: devx/9dd3b67e-58e9-4a01-a721-43265d02ccd2

Author: dmerand

packages/cli/README.md

@@ -4922,6 +4922,38 @@ FLAGS
 DESCRIPTION
   Displays information about your theme environment, including your current store. Can also retrieve information about a
   specific theme.
+
+  Use `--json` for machine-readable output.
+
+  Output from `--json` conforms to the `ThemeInfoResult` schema.
+
+  Use `--json-schema` to print the schema directly:
+
+  ```ts
+  type ThemeInfoResult = ThemeInfoThemeResult | ThemeEnvironmentInfo
+
+  interface ThemeInfoTheme {
+    id: number
+    name: string
+    role: string
+    shop: string
+    preview_url: string
+    editor_url: string
+  }
+
+  interface ThemeInfoThemeResult {
+    theme: ThemeInfoTheme
+  }
+
+  interface ThemeEnvironmentInfo {
+    store: string
+    development_theme_id: number | null
+    cli_version: string
+    os: string
+    shell: string
+    node_version: string
+  }
+  ```
 ```
 
 ## `shopify theme init [name] [flags]`

packages/cli/oclif.manifest.json

@@ -9797,7 +9797,8 @@
       "args": {
       },
       "customPluginName": "@shopify/theme",
-      "description": "Displays information about your theme environment, including your current store. Can also retrieve information about a specific theme.",
+      "description": "Displays information about your theme environment, including your current store. Can also retrieve information about a specific theme.\n\nUse `--json` for machine-readable output.\n\nOutput from `--json` conforms to the `ThemeInfoResult` schema.\n\nUse `--json-schema` to print the schema directly:\n\n```ts\ntype ThemeInfoResult = ThemeInfoThemeResult | ThemeEnvironmentInfo\n\ninterface ThemeInfoTheme {\n  id: number\n  name: string\n  role: string\n  shop: string\n  preview_url: string\n  editor_url: string\n}\n\ninterface ThemeInfoThemeResult {\n  theme: ThemeInfoTheme\n}\n\ninterface ThemeEnvironmentInfo {\n  store: string\n  development_theme_id: number | null\n  cli_version: string\n  os: string\n  shell: string\n  node_version: string\n}\n```",
+      "descriptionWithMarkdown": "Displays information about your theme environment, including your current store. Can also retrieve information about a specific theme.\n\nUse `--json` for machine-readable output.",
       "enableJsonFlag": false,
       "flags": {
         "auth-alias": {

packages/theme/src/cli/commands/theme/info.test.ts

@@ -134,6 +134,11 @@ describe('Info', () => {
     expect(Info.jsonOutputSchema).toBe(themeInfoJsonOutputSchema)
   })
 
+  test('includes the JSON output schema in the help description', () => {
+    expect(Info.description).toContain('ThemeInfoResult')
+    expect(Info.description).toContain('--json-schema')
+  })
+
   test('is removed from the JSON legacy exemption list', () => {
     const legacyCommandPaths = readFileSync(
       new URL('../../../../../eslint-plugin-cli/rules/json-output-legacy-command-paths.js', import.meta.url),

packages/theme/src/cli/commands/theme/info.ts

@@ -13,8 +13,15 @@ import {recordTiming} from '@shopify/cli-kit/node/analytics'
 type InfoFlags = OutputFlags<typeof Info.flags>
 
 export default class Info extends ThemeCommand {
-  static description =
-    'Displays information about your theme environment, including your current store. Can also retrieve information about a specific theme.'
+  static get jsonOutputSchema() {
+    return themeInfoJsonOutputSchema
+  }
+
+  static descriptionWithMarkdown = `Displays information about your theme environment, including your current store. Can also retrieve information about a specific theme.
+
+Use \`--json\` for machine-readable output.`
+
+  static description = this.descriptionForHelp()
 
   static flags = {
     ...globalFlags,
@@ -34,10 +41,6 @@ export default class Info extends ThemeCommand {
 
   static multiEnvironmentsFlags = ['store', 'password']
 
-  static get jsonOutputSchema() {
-    return themeInfoJsonOutputSchema
-  }
-
   async command(flags: InfoFlags, adminSession: AdminSession): Promise<void> {
     recordTiming('theme-command:info')
     if (flags.theme || flags.development) {

packages/theme/src/cli/services/info.test.ts

@@ -71,9 +71,11 @@ describe('info', () => {
     })
   })
 
-  test('uses the JSON fallback values when no store or development theme is configured', () => {
+  test('uses the JSON fallback values without reading the development theme when no store is configured', () => {
     vi.mocked(getThemeStore).mockReturnValue(undefined)
-    vi.mocked(getDevelopmentTheme).mockReturnValue(undefined)
+    vi.mocked(getDevelopmentTheme).mockImplementation(() => {
+      throw new Error('The development theme needs a configured store')
+    })
 
     expect(themeEnvironmentInfoJSON({cliVersion: '3.91.0'})).toMatchObject({
       store: 'Not configured',
@@ -82,6 +84,7 @@ describe('info', () => {
       shell: process.env.SHELL ?? 'unknown',
       node_version: process.version,
     })
+    expect(getDevelopmentTheme).not.toHaveBeenCalled()
   })
 
   test('retains the raw development theme ID for text presentation', () => {
@@ -94,16 +97,6 @@ describe('info', () => {
     })
   })
 
-  test('retains the raw development theme ID for text presentation when no store is configured', () => {
-    vi.mocked(getThemeStore).mockReturnValue(undefined)
-    vi.mocked(getDevelopmentTheme).mockReturnValue('123')
-
-    expect(getThemeEnvironmentInfo({cliVersion: '3.91.0'})).toMatchObject({
-      result: {development_theme_id: null},
-      developmentTheme: '123',
-    })
-  })
-
   test('fetch theme info by id', async () => {
     // Given
     vi.mocked(findOrSelectTheme).mockResolvedValue(theme)

packages/theme/src/cli/services/info.ts

@@ -39,8 +39,8 @@ export function getThemeEnvironmentInfo(config: {cliVersion: string}): {
 } {
   const {platform, arch} = platformAndArch()
   const store = getThemeStore()
-  const developmentTheme = getDevelopmentTheme()
-  const developmentThemeID = store ? Number(developmentTheme) || null : null
+  const developmentTheme = store ? getDevelopmentTheme() : undefined
+  const developmentThemeID = Number(developmentTheme) || null
 
   return {
     result: {