Refactor extension build process to use modular build steps

[alfonso-noriega]

Wire extension specifications to use client steps

Summary

This PR wires all extension specifications to use the clientSteps contract introduced in #01-build-steps-infrastructure. The build() method in ExtensionInstance is refactored from a hard-coded mode switch to a generic step execution loop, and every spec now declares its own clientSteps array.

Depends on: 01-build-steps-infrastructure

---

What changed

ExtensionInstance.build() — mode switch replaced by step loop

Before:

async build(options: ExtensionBuildOptions): Promise<void> {
  const mode = this.specification.buildConfig.mode
  switch (mode) {
    case 'theme':
      await buildThemeExtension(this, options)
      return bundleThemeExtension(this, options)
    case 'function':
      return buildFunctionExtension(this, options)
    case 'ui':
      return buildUIExtension(this, options)
    case 'copy_files':
      return copyFilesForExtension(this, options)
    // ...
  }
}

After:

async build(options: ExtensionBuildOptions): Promise<void> {
  const {clientSteps} = this.specification

  const context: BuildContext = {
    extension: this,
    options,
    stepResults: new Map(),
  }

  const steps = clientSteps
    .filter((group) => group.lifecycle === 'deploy')
    .flatMap((group) => group.steps)

  for (const step of steps) {
    const result = await executeStep(step, context)
    context.stepResults.set(step.id, result)
  }
}

The mode switch and all its direct function call imports (buildThemeExtension, buildUIExtension, buildFunctionExtension, copyFilesForExtension) are removed. The step loop is uniform across all extension types.

extension.ts — buildThemeExtension removed

buildThemeExtension() and its runThemeCheck import are removed from extension.ts — the logic now lives exclusively in build-theme-step.ts.

---

Specs wired

All specs now declare clientSteps. The buildConfig.mode is kept as a transitional field.

UI extensions

// checkout_post_purchase, checkout_ui_extension, pos_ui_extension,
// product_subscription, web_pixel_extension, ui_extension
clientSteps: [{
  lifecycle: 'deploy',
  steps: [
    {id: 'bundle-ui',          name: 'Bundle UI Extension', type: 'bundle_ui',          config: {}},
    {id: 'copy-static-assets', name: 'Copy Static Assets',  type: 'copy_static_assets', config: {}},
  ],
}]

Theme

clientSteps: [{
  lifecycle: 'deploy',
  steps: [
    {id: 'build-theme',  name: 'Build Theme Extension',  type: 'build_theme',  config: {}},
    {id: 'bundle-theme', name: 'Bundle Theme Extension', type: 'bundle_theme', config: {}},
  ],
}]

Function

clientSteps: [{
  lifecycle: 'deploy',
  steps: [
    {id: 'build-function', name: 'Build Function', type: 'build_function', config: {}},
  ],
}]

Tax calculation

clientSteps: [{
  lifecycle: 'deploy',
  steps: [
    {id: 'create-tax-stub', name: 'Create Tax Stub', type: 'create_tax_stub', config: {}},
  ],
}]

Flow template

clientSteps: [{
  lifecycle: 'deploy',
  steps: [{
    id: 'copy-files', name: 'Copy Files', type: 'include_assets',
    config: {
      inclusions: [{
        type: 'pattern',
        include: ['**/*.flow', '**/*.json', '**/*.toml'],
      }],
    },
  }],
}]

Channel

clientSteps: [{
  lifecycle: 'deploy',
  steps: [{
    id: 'copy-files', name: 'Copy Files', type: 'include_assets',
    config: {
      inclusions: [{
        type: 'pattern',
        baseDir: 'specifications',
        destination: 'specifications',
        include: ['**/*.json', '**/*.toml', '**/*.yaml', '**/*.yml', '**/*.svg'],
      }],
    },
  }],
}]

---

Tests added

Each spec now has a dedicated build test file asserting:

• buildConfig.mode is correct
• clientSteps has the expected step structure
• The config is JSON-serializable
• extension.build() produces the correct output on disk (integration)

Test file	Covers
ui_extension_build.test.ts	bundle_ui + copy_static_assets steps
theme.test.ts	build_theme + bundle_theme steps
function_build.test.ts	build_function step delegates to buildFunctionExtension
tax_calculation_build.test.ts	create_tax_stub writes (()=>{})();
flow_template.test.ts	Copies .flow/.json/.toml, not .js/.ts; preserves subdirs
channel.test.ts	Copies from specifications/ subdirectory into output/specifications/; filters by extension

---

Files changed

File	Change
models/extensions/extension-instance.ts	build() rewritten to use executeStep loop
services/build/extension.ts	Removed buildThemeExtension + runThemeCheck import
specifications/ui_extension.ts	Added clientSteps
specifications/checkout_post_purchase.ts	Added clientSteps
specifications/checkout_ui_extension.ts	Added clientSteps
specifications/pos_ui_extension.ts	Added clientSteps
specifications/product_subscription.ts	Added clientSteps
specifications/web_pixel_extension.ts	Added clientSteps
specifications/theme.ts	Added clientSteps
specifications/function.ts	Added clientSteps
specifications/tax_calculation.ts	Added clientSteps
specifications/flow_template.ts	Added clientSteps with include_assets config
specifications/channel.ts	New spec — include_assets scoped to specifications/ subdirectory
Test files (6)	Build integration tests for all spec types

---

Measuring impact

How do we know this change was effective? Please choose one:

• n/a - this doesn't need measurement, e.g. a linting rule or a bug-fix
• Existing analytics will cater for this addition
• PR includes analytics changes to measure impact

Checklist

• I've considered possible cross-platform impacts (Mac, Linux, Windows)
• I've considered possible documentation changes

[alfonso-noriega]

Warning

This pull request is not mergeable via GitHub because a downstack PR is open. Once all requirements are satisfied, merge this PR as a stack on Graphite.
Learn more

• Refactor extension build process to use modular build steps #6867 : 2 dependent PRs (#6868 , #6869 ) 👈 (View in Graphite)
• Abstract build steps to externalize the build configuration #6866
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[github-actions]

Coverage report

St.❔	Category	Percentage	Covered / Total
🟡	Statements	78.94%	14596/18490
🟡	Branches	73.19%	7263/9923
🟡	Functions	79.17%	3717/4695
🟡	Lines	79.29%	13794/17396

Test suite run success

3860 tests passing in 1486 suites.

Report generated by 🧪jest coverage report action from 4061625

[binks-code-reviewer]

Import target for build steps points to non-existent module (runtime crash)

ExtensionInstance imports BuildContext/executeStep from ../../services/build/build-steps.js, but that file does not exist in the repo. The actual implementation is packages/app/src/cli/services/build/client-steps.ts, which exports executeStep and BuildContext. This will fail Node ESM module resolution at runtime, breaking any command path that loads extension-instance.ts (build, deploy, etc.).

[binks-code-reviewer]

Step shape mismatch: executor expects name, configs/build loop use displayName

The build loop references step.displayName for error messages, while the executor (client-steps.ts) expects a ClientStep with name and logs using step.name. Updated step specs appear to use displayName rather than name, which can result in logs like Executing step: undefined and unreliable routing/error reporting. If TypeScript is strictly enforced, this should fail typechecking; otherwise it degrades observability and debugging.

[binks-code-reviewer]

⚠️ Findings outside the diff

These findings are in files not modified by this PR and cannot be posted as inline comments.

---

packages/app/src/cli/models/extensions/extension-instance.ts:144 — outputFileName behavior changed for copy_files

outputFileName previously returned '' for mode === 'copy_files' || mode === 'theme'. Now it returns '' only for hosted_app_home and theme.

For copy_files extensions, outputFileName will now be ${handle}.js, which changes default outputPath calculation in the constructor (for non-esbuild types) and may affect bundling/copy destinations. Some code (like include_assets_step) has logic to treat outputPath as either a file or directory based on extname(outputPath), so a *.js outputPath can flip behavior from “directory output” to “file output’s parent directory”.

Impact:

• User impact: copy_files extensions may copy files into dist/ unexpectedly or into a parent dir rather than the intended folder, depending on how outputPath is used downstream.
• Scale: Affects all copy_files specs unless they override outputPath manually.
• Consequences: Missing files in uploaded bundles, incorrect directory structure in artifacts.

[binks-code-reviewer]

Crash when specification.clientSteps is missing/undefined

ExtensionInstance.build() now does:

const steps = clientSteps
  .filter((lifecycle) => lifecycle.lifecycle === 'deploy')
  .flatMap((lifecycle) => lifecycle.steps)

If this.specification.clientSteps is undefined for any extension type (including internal/legacy specs not updated in this PR), this will throw: TypeError: Cannot read properties of undefined (reading 'filter').

Impact:

• Extension builds/deploys will hard-fail for any extension type missing clientSteps, blocking development and deployments.
• CI/release pipelines that build extensions will fail; could break deploys for affected extension types.
• Potentially broad depending on how many specs are migrated; PR only updates some specs so risk is high.
• Could cause widespread deployment failures.