Abstract build steps to externalize the build configuration

[alfonso-noriega]

WHY are these changes introduced?

Fixes #0000

Build steps pipeline infrastructure

Introduces a declarative, data-driven pipeline for executing extension build steps. This is the foundational layer that the next two PRs in the stack build on.

Problem

Previously, each extension's build logic was hardcoded imperatively inside extension-instance.ts:build() via a large switch on the extension type. Adding a new extension type meant touching
core infrastructure. Build behaviour was also untestable in isolation — you couldn't verify what an extension "would do" at build time without running the full build.

Solution

A typed pipeline where build logic is expressed as configuration, not code. Each extension declares an ordered list of BuildStep objects. The pipeline engine reads that config and
dispatches to the right executor. Because steps are plain data, they are:

• Serializable to JSON — build configs can be sent over the wire or stored externally
• Independently testable — each step executor is a pure function, tested in isolation
• Composable — extensions can combine steps (e.g. bundle then copy assets)
• Extensible — new step types are added to the router without touching existing specs

Architecture

BuildConfig (spec declares this)
  └─ steps: BuildStep[]          ← plain serializable config objects
       └─ type, id, config{...}

executeBuildSteps(extension, stepsConfig, options)
  └─ for each step: executeStep(step, context)
       └─ executeStepByType(step, context)   ← router/dispatcher
            ├─ 'copy_files'        → executeCopyFilesStep
            ├─ 'build_theme'       → executeBuildThemeStep
            ├─ 'bundle_theme'      → executeBundleThemeStep
            ├─ 'bundle_ui'         → executeBundleUIStep
            ├─ 'copy_static_assets'→ executeCopyStaticAssetsStep
            ├─ 'build_function'    → executeBuildFunctionStep
            └─ 'create_tax_stub'   → executeCreateTaxStubStep

The BuildContext is threaded through every step — it carries the extension instance, build options (stdout/stderr), an abort signal, and a stepResults map so later steps can read outputs
from earlier ones.

Step configuration reference

copy_files — the most flexible step

Supports two strategies, selected via the strategy field.

strategy: 'files' — explicit file list

Each entry is one of:

Entry shape	Behaviour
{source: 'path'}	Copy directory contents into the output root
{source: 'path', destination: 'out/file'}	Copy a single file to an explicit destination
{tomlKey: 'static_root'}	Resolve the path from the extension's TOML config, then copy that directory's contents

{
  id: 'copy-static-assets',
  type: 'copy_files',
  config: {
    strategy: 'files',
    definition: {
      files: [
        {tomlKey: 'static_root'},                          // path resolved from TOML at build time
        {source: 'icons', destination: 'assets/icons'},    // explicit destination
      ],
    },
  },
}

Dot-notation is supported for nested paths ('nested.field'), and array-of-tables are automatically plucked across all entries.

strategy: 'pattern' — glob-based selection from a source directory

Field	Type	Description
source	string	Subdirectory inside the extension dir to glob from
patterns	string[]	Glob patterns (default **/*)
ignore	string[]	Patterns to exclude
destination	string	Output subdirectory (default: output root)
preserveStructure	boolean	Keep relative paths (default true)

{
  id: 'copy-files',
  type: 'copy_files',
  config: {
    strategy: 'pattern',
    definition: {
      source: 'specifications',
      patterns: ['**/*.json', '**/*.toml', '**/*.yaml', '**/*.svg'],
    },
  },
}

Other step types

These wrap the existing build functions and require no additional config beyond {}:

Type	What it does
build_theme	Runs buildThemeExtension
bundle_theme	Runs bundleThemeExtension
bundle_ui	Runs buildUIExtension
copy_static_assets	Calls extension.copyStaticAssets()
build_function	Runs buildFunctionExtension
create_tax_stub	Writes the (()=>{})(); output stub

Step execution behaviour

BuildStep field	Default	Description
continueOnError	false	If true, a failed step is recorded but the pipeline continues
stopOnError (on BuildConfig)	true	If false, all steps run regardless of failures

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

• Add a build manifest build step #6869
• Replace hosted_app_home build mode with copy_files mode #6868
• Refactor extension build process to use modular build steps #6867
• Abstract build steps to externalize the build configuration #6866 👈 (View in Graphite)
• Asset pipeline flow for hosted static app #6806 : 2 other dependent PRs (#6842 , #6895 )
• 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.75%	14607/18549
🟡	Branches	73.07%	7263/9940
🟡	Functions	78.93%	3704/4693
🟡	Lines	79.09%	13811/17462

Test suite run success

3808 tests passing in 1466 suites.

Report generated by 🧪jest coverage report action from ef0c29e

[github-actions]

We detected some changes at packages/*/src and there are no updates in the .changeset.
If the changes are user-facing, run pnpm changeset add to track your changes and include them in the next release CHANGELOG.

Caution

DO NOT create changesets for features which you do not wish to be included in the public changelog of the next CLI release.

[binks-code-reviewer]

copy_files destination path can escape outputDir (arbitrary write)

copySourceEntry builds destPath via joinPath(outputDir, destination). If destination is absolute or contains .., the resolved path can escape outputDir, enabling a build config (notably described as serializable/externalizable) to overwrite arbitrary files on the machine.

Evidence:

const destPath = joinPath(outputDir, destination)
await mkdir(dirname(destPath))
await copyFile(sourcePath, destPath)

Impact includes overwriting repo/CI files, compromising developer/CI machines, supply-chain risk, and corrupted artifacts.

[binks-code-reviewer]

copy_files pattern destination directory can escape outputDir (arbitrary write)

In pattern mode, definition.destination is joined into outputDir without sanitization:

const destinationDir = definition.destination ? joinPath(outputDir, definition.destination) : outputDir

Absolute paths or .. segments can escape outputDir, after which copyByPattern will create directories and write files there—especially dangerous because it can write many files outside the build output.

[binks-code-reviewer]

Theme bundling writes under extension.outputPath and doesn’t ensure parent dirs exist

executeBundleThemeStep computes:

const outputFile = joinPath(extension.outputPath, relativePathName)
await copyFile(filepath, outputFile)

If extension.outputPath is a file path (e.g., .../extension.js), this produces .../extension.js/<relative> and fails. Also, it does not mkdir(dirname(outputFile)), so nested paths fail unless directories already exist.

[binks-code-reviewer]

Unbounded Promise.all copies can exhaust file descriptors on large file sets

Multiple places use Promise.all over potentially large arrays (copyFilesList, copyTomlKeyEntry, copyByPattern). For thousands of files, this can trigger EMFILE: too many open files, high memory usage, and flaky builds.

[binks-code-reviewer]

🤖 Code Review · #projects-dev-ai for questions
React with 👍/👎 or reply — all feedback helps improve the agent.

✅ Complete - 4 findings

📋 History

✅ 4 findings