Refactor extension build process to use modular build steps

packages/app/src/cli/models/extensions/extension-instance.test.ts

@@ -148,8 +148,8 @@ describe('build', async () => {
       // Given
       const extensionInstance = await testTaxCalculationExtension(tmpDir)
       const options: ExtensionBuildOptions = {
-        stdout: new Writable(),
-        stderr: new Writable(),
+        stdout: new Writable({write(chunk, enc, cb) { cb() }}),
+        stderr: new Writable({write(chunk, enc, cb) { cb() }}),
         app: testApp(),
         environment: 'production',
       }

packages/app/src/cli/models/extensions/extension-instance.ts

@@ -14,14 +14,9 @@ import {WebhooksSpecIdentifier} from './specifications/app_config_webhook.js'
 import {WebhookSubscriptionSpecIdentifier} from './specifications/app_config_webhook_subscription.js'
 import {EventsSpecIdentifier} from './specifications/app_config_events.js'
 import {HostedAppHomeSpecIdentifier} from './specifications/app_config_hosted_app_home.js'
-import {
-  ExtensionBuildOptions,
-  buildFunctionExtension,
-  buildThemeExtension,
-  buildUIExtension,
-  bundleFunctionExtension,
-} from '../../services/build/extension.js'
-import {bundleThemeExtension, copyFilesForExtension} from '../../services/extensions/bundle.js'
+import {ExtensionBuildOptions, bundleFunctionExtension} from '../../services/build/extension.js'
+import {bundleThemeExtension} from '../../services/extensions/bundle.js'
+import {BuildContext, executeStep} from '../../services/build/build-steps.js'
 import {Identifiers} from '../app/identifiers.js'
 import {DeveloperPlatformClient} from '../../utilities/developer-platform-client.js'
 import {AppConfigurationWithoutPath} from '../app/app.js'
@@ -31,7 +26,7 @@ import {constantize, slugify} from '@shopify/cli-kit/common/string'
 import {hashString, nonRandomUUID} from '@shopify/cli-kit/node/crypto'
 import {partnersFqdn} from '@shopify/cli-kit/node/context/fqdn'
 import {joinPath, basename, normalizePath, resolvePath} from '@shopify/cli-kit/node/path'
-import {fileExists, touchFile, moveFile, writeFile, glob, copyFile, globSync} from '@shopify/cli-kit/node/fs'
+import {fileExists, moveFile, glob, copyFile, globSync} from '@shopify/cli-kit/node/fs'
 import {getPathValue} from '@shopify/cli-kit/common/object'
 import {outputDebug} from '@shopify/cli-kit/node/output'
 import {extractJSImports, extractImportPathsRecursively} from '@shopify/cli-kit/node/import-extractor'
@@ -347,34 +342,25 @@ export class ExtensionInstance<TConfiguration extends BaseConfigType = BaseConfi
   }
 
   async build(options: ExtensionBuildOptions): Promise<void> {
-    const mode = this.specification.buildConfig.mode
+    const {buildConfig} = this.specification
+
+    const context: BuildContext = {
+      extension: this,
+      options,
+      stepResults: new Map(),
+      signal: options.signal,
+    }
 
-    switch (mode) {
-      case 'theme':
-        await buildThemeExtension(this, options)
-        return bundleThemeExtension(this, options)
-      case 'function':
-        return buildFunctionExtension(this, options)
-      case 'ui':
-        await buildUIExtension(this, options)
-        // Copy static assets after build completes
-        return this.copyStaticAssets()
-      case 'tax_calculation':
-        await touchFile(this.outputPath)
-        await writeFile(this.outputPath, '(()=>{})();')
-        break
-      case 'copy_files':
-        return copyFilesForExtension(
-          this,
-          options,
-          this.specification.buildConfig.filePatterns,
-          this.specification.buildConfig.ignoredFilePatterns,
-        )
-      case 'hosted_app_home':
-        await this.copyStaticAssets()
-        break
-      case 'none':
-        break
+    const {steps = []} = buildConfig
+
+    for (const step of steps) {
+      // eslint-disable-next-line no-await-in-loop
+      const result = await executeStep(step, context)
+      context.stepResults.set(step.id, result)
+
+      if (!result.success && !step.continueOnError) {
+        throw new Error(`Build step "${step.displayName}" failed: ${result.error?.message}`)
+      }
     }
   }
 

packages/app/src/cli/models/extensions/specification.ts

@@ -2,6 +2,7 @@
 import {ZodSchemaType, BaseConfigType, BaseSchema} from './schemas.js'
 import {ExtensionInstance} from './extension-instance.js'
 import {blocks} from '../../constants.js'
+import {BuildStep} from '../../services/build/build-steps.js'
 
 import {Flag} from '../../utilities/developer-platform-client.js'
 import {AppConfigurationWithoutPath} from '../app/app.js'
@@ -54,9 +55,10 @@ export interface BuildAsset {
   static?: boolean
 }
 
-type BuildConfig =
-  | {mode: 'ui' | 'theme' | 'function' | 'tax_calculation' | 'none' | 'hosted_app_home'}
-  | {mode: 'copy_files'; filePatterns: string[]; ignoredFilePatterns?: string[]}
+interface BuildConfig {
+  mode: 'none' | 'ui' | 'theme' | 'function' | 'tax_calculation' | 'copy_files'
+  steps?: ReadonlyArray<BuildStep>
+}
 /**
  * Extension specification with all the needed properties and methods to load an extension.
  */

packages/app/src/cli/models/extensions/specifications/channel.test.ts

@@ -0,0 +1,156 @@
+import spec from './channel.js'
+import {ExtensionInstance} from '../extension-instance.js'
+import {ExtensionBuildOptions} from '../../../services/build/extension.js'
+import {describe, expect, test} from 'vitest'
+import {inTemporaryDirectory, writeFile, fileExists, mkdir} from '@shopify/cli-kit/node/fs'
+import {joinPath} from '@shopify/cli-kit/node/path'
+import {Writable} from 'stream'
+
+const SUBDIRECTORY = 'specifications'
+
+describe('channel_config', () => {
+  describe('buildConfig', () => {
+    test('uses build_steps mode', () => {
+      expect(spec.buildConfig.mode).toBe('copy_files')
+    })
+
+    test('has a single copy-files step scoped to the specifications subdirectory', () => {
+      if (spec.buildConfig.mode === 'none') throw new Error('Expected build_steps mode')
+
+      expect(spec.buildConfig.steps).toHaveLength(1)
+      expect(spec.buildConfig.steps![0]).toMatchObject({
+        id: 'copy-files',
+        type: 'copy_files',
+        config: {
+          strategy: 'pattern',
+          definition: {source: '.'},
+        },
+      })
+
+      const {patterns} = (spec.buildConfig.steps![0]!.config as {definition: {patterns: string[]}}).definition
+
+      expect(patterns).toEqual(
+        expect.arrayContaining([
+          `${SUBDIRECTORY}/**/*.json`,
+          `${SUBDIRECTORY}/**/*.toml`,
+          `${SUBDIRECTORY}/**/*.yaml`,
+          `${SUBDIRECTORY}/**/*.yml`,
+          `${SUBDIRECTORY}/**/*.svg`,
+        ]),
+      )
+    })
+
+    test('config is serializable to JSON', () => {
+      if (spec.buildConfig.mode === 'none') throw new Error('Expected build_steps mode')
+
+      const serialized = JSON.stringify(spec.buildConfig)
+      const deserialized = JSON.parse(serialized)
+
+      expect(deserialized.steps).toHaveLength(1)
+      expect(deserialized.steps[0].config.strategy).toBe('pattern')
+    })
+  })
+
+  describe('build integration', () => {
+    test('copies specification files to output, preserving subdirectory structure', async () => {
+      await inTemporaryDirectory(async (tmpDir) => {
+        // Given
+        const extensionDir = joinPath(tmpDir, 'extension')
+        const specsDir = joinPath(extensionDir, SUBDIRECTORY)
+        const outputDir = joinPath(tmpDir, 'output')
+
+        await mkdir(specsDir)
+        await mkdir(outputDir)
+
+        await writeFile(joinPath(specsDir, 'product.json'), '{}')
+        await writeFile(joinPath(specsDir, 'order.toml'), '[spec]')
+        await writeFile(joinPath(specsDir, 'logo.svg'), '<svg/>')
+        // Root-level files should NOT be copied
+        await writeFile(joinPath(extensionDir, 'README.md'), '# readme')
+        await writeFile(joinPath(extensionDir, 'index.js'), 'ignored')
+
+        const extension = new ExtensionInstance({
+          configuration: {name: 'my-channel', type: 'channel'},
+          configurationPath: '',
+          directory: extensionDir,
+          specification: spec,
+        })
+        extension.outputPath = outputDir
+
+        const buildOptions: ExtensionBuildOptions = {
+          stdout: new Writable({
+            write(chunk, enc, cb) {
+              cb()
+            },
+          }),
+          stderr: new Writable({
+            write(chunk, enc, cb) {
+              cb()
+            },
+          }),
+          app: {} as any,
+          environment: 'production',
+        }
+
+        // When
+        await extension.build(buildOptions)
+
+        // Then — specification files copied with path preserved
+        await expect(fileExists(joinPath(outputDir, SUBDIRECTORY, 'product.json'))).resolves.toBe(true)
+        await expect(fileExists(joinPath(outputDir, SUBDIRECTORY, 'order.toml'))).resolves.toBe(true)
+        await expect(fileExists(joinPath(outputDir, SUBDIRECTORY, 'logo.svg'))).resolves.toBe(true)
+
+        // Root-level files not in specifications/ are not copied
+        await expect(fileExists(joinPath(outputDir, 'README.md'))).resolves.toBe(false)
+        await expect(fileExists(joinPath(outputDir, 'index.js'))).resolves.toBe(false)
+      })
+    })
+
+    test('does not copy files with non-matching extensions inside specifications/', async () => {
+      await inTemporaryDirectory(async (tmpDir) => {
+        // Given
+        const extensionDir = joinPath(tmpDir, 'extension')
+        const specsDir = joinPath(extensionDir, SUBDIRECTORY)
+        const outputDir = joinPath(tmpDir, 'output')
+
+        await mkdir(specsDir)
+        await mkdir(outputDir)
+
+        await writeFile(joinPath(specsDir, 'spec.json'), '{}')
+        await writeFile(joinPath(specsDir, 'ignored.ts'), 'const x = 1')
+        await writeFile(joinPath(specsDir, 'ignored.js'), 'const x = 1')
+
+        const extension = new ExtensionInstance({
+          configuration: {name: 'my-channel', type: 'channel'},
+          configurationPath: '',
+          directory: extensionDir,
+          specification: spec,
+        })
+        extension.outputPath = outputDir
+
+        const buildOptions: ExtensionBuildOptions = {
+          stdout: new Writable({
+            write(chunk, enc, cb) {
+              cb()
+            },
+          }),
+          stderr: new Writable({
+            write(chunk, enc, cb) {
+              cb()
+            },
+          }),
+          app: {} as any,
+          environment: 'production',
+        }
+
+        // When
+        await extension.build(buildOptions)
+
+        // Then
+        await expect(fileExists(joinPath(outputDir, SUBDIRECTORY, 'spec.json'))).resolves.toBe(true)
+        await expect(fileExists(joinPath(outputDir, SUBDIRECTORY, 'ignored.ts'))).resolves.toBe(false)
+        await expect(fileExists(joinPath(outputDir, SUBDIRECTORY, 'ignored.js'))).resolves.toBe(false)
+      })
+    })
+  })
+})

packages/app/src/cli/models/extensions/specifications/channel.ts

@@ -8,7 +8,20 @@ const channelSpecificationSpec = createContractBasedModuleSpecification({
   identifier: 'channel_config',
   buildConfig: {
     mode: 'copy_files',
-    filePatterns: FILE_EXTENSIONS.map((ext) => joinPath(SUBDIRECTORY_NAME, '**', `*.${ext}`)),
+    steps: [
+      {
+        id: 'copy-files',
+        displayName: 'Copy Files',
+        type: 'copy_files',
+        config: {
+          strategy: 'pattern',
+          definition: {
+            source: '.',
+            patterns: FILE_EXTENSIONS.map((ext) => joinPath(SUBDIRECTORY_NAME, '**', `*.${ext}`)),
+          },
+        },
+      },
+    ],
   },
   appModuleFeatures: () => [],
 })

packages/app/src/cli/models/extensions/specifications/checkout_post_purchase.ts

@@ -14,7 +14,13 @@ const checkoutPostPurchaseSpec = createExtensionSpecification({
   partnersWebIdentifier: 'post_purchase',
   schema: CheckoutPostPurchaseSchema,
   appModuleFeatures: (_) => ['ui_preview', 'cart_url', 'esbuild', 'single_js_entry_path'],
-  buildConfig: {mode: 'ui'},
+  buildConfig: {
+    mode: 'ui',
+    steps: [
+      {id: 'bundle-ui', displayName: 'Bundle UI Extension', type: 'bundle_ui', config: {}},
+      {id: 'copy-static-assets', displayName: 'Copy Static Assets', type: 'copy_static_assets', config: {}},
+    ],
+  },
   deployConfig: async (config, _) => {
     return {metafields: config.metafields ?? []}
   },

packages/app/src/cli/models/extensions/specifications/checkout_ui_extension.ts

@@ -21,7 +21,13 @@ const checkoutSpec = createExtensionSpecification({
   dependency,
   schema: CheckoutSchema,
   appModuleFeatures: (_) => ['ui_preview', 'cart_url', 'esbuild', 'single_js_entry_path', 'generates_source_maps'],
-  buildConfig: {mode: 'ui'},
+  buildConfig: {
+    mode: 'ui',
+    steps: [
+      {id: 'bundle-ui', displayName: 'Bundle UI Extension', type: 'bundle_ui', config: {}},
+      {id: 'copy-static-assets', displayName: 'Copy Static Assets', type: 'copy_static_assets', config: {}},
+    ],
+  },
   deployConfig: async (config, directory) => {
     return {
       extension_points: config.extension_points,