Allow preserving file paths when including assets from config key entry

[vividviolet]

WHY are these changes introduced?

When multiple configKey entries reference different source directories or files that produce the same output-relative path, the last writer silently wins. This makes it impossible to detect accidental file collisions when directory structures need to be preserved in the output.

WHAT is this pull request doing?

Adds a preserveFilePaths option (default false) to configKey inclusion entries. When enabled:

• Files are written to the output directory preserving their relative paths from the source directory, rather than being flattened to unique basenames.
• A collision check is enforced across all entries in the same build: if two different sources would produce the same output-relative file path, an error is thrown immediately with a descriptive message indicating which file caused the conflict.
• A shared usedFiles set is threaded through all configKey entries so cross-entry collisions are detected, not just within-entry ones.
• The existing usedBasenames deduplication logic is preserved for entries where preserveFilePaths is false.

The collision check is extracted into a single assertNoCollision helper used by both the directory and single-file copy branches.

How to test your changes?

Unit tests should be sufficient

Checklist

• I've considered possible cross-platform impacts (Mac, Linux, Windows)
• I've considered possible documentation changes
• I've considered analytics changes to measure impact
• The change is user-facing — I've identified the correct bump type (patch for bug fixes · minor for new features · major for breaking changes) and added a changeset with pnpm changeset add

[vividviolet]

• Allow preserving file paths when including assets from config key entry #7389 👈 (View in Graphite)
• main

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

[melissaluu]

/snapit

[github-actions]

🫰✨ Thanks @melissaluu! Your snapshot has been published to npm.

Test the snapshot by installing your package globally:

pnpm i -g --@shopify:registry=https://registry.npmjs.org @shopify/cli@0.0.0-snapshot-20260424162325

Caution

After installing, validate the version by running shopify version in your terminal.
If the versions don't match, you might have multiple global instances installed.
Use which shopify to find out which one you are running and uninstall it.

[vividviolet]

/snapit

[github-actions]

🫰✨ Thanks @vividviolet! Your snapshot has been published to npm.

Test the snapshot by installing your package globally:

pnpm i -g --@shopify:registry=https://registry.npmjs.org @shopify/cli@0.0.0-snapshot-20260424215600

Caution

After installing, validate the version by running shopify version in your terminal.
If the versions don't match, you might have multiple global instances installed.
Use which shopify to find out which one you are running and uninstall it.

[github-actions]

Differences in type declarations

We detected differences in the type declarations generated by Typescript for this branch compared to the baseline ('main' branch). Please, review them to ensure they are backward-compatible. Here are some important things to keep in mind:

• Some seemingly private modules might be re-exported through public modules.
• If the branch is behind main you might see odd diffs, rebase main into this branch.

New type declarations

We found no new type declarations in this PR

Existing type declarations

packages/cli-kit/dist/public/node/cli-launcher.d.ts

@@ -1,8 +1,6 @@
-import type { LazyCommandLoader } from './custom-oclif-loader.js';
 interface Options {
     moduleURL: string;
     argv?: string[];
-    lazyCommandLoader?: LazyCommandLoader;
 }
 /**
  * Launches the CLI.

packages/cli-kit/dist/public/node/cli.d.ts

@@ -1,4 +1,3 @@
-import type { LazyCommandLoader } from './custom-oclif-loader.js';
 /**
  * IMPORTANT NOTE: Imports in this module are dynamic to ensure that "setupEnvironmentVariables" can dynamically
  * set the DEBUG environment variable before the 'debug' package sets up its configuration when modules
@@ -8,8 +7,6 @@ interface RunCLIOptions {
     /** The value of import.meta.url of the CLI executable module */
     moduleURL: string;
     development: boolean;
-    /** Optional lazy command loader for on-demand command loading */
-    lazyCommandLoader?: LazyCommandLoader;
 }
 /**
  * A function that abstracts away setting up the environment and running
@@ -20,7 +17,6 @@ export declare function runCLI(options: RunCLIOptions & {
     runInCreateMode?: boolean;
 }, launchCLI?: (options: {
     moduleURL: string;
-    lazyCommandLoader?: LazyCommandLoader;
 }) => Promise<void>, argv?: string[], env?: NodeJS.ProcessEnv, versions?: NodeJS.ProcessVersions): Promise<void>;
 /**
  * A function for create-x CLIs that automatically runs the "init" command.
@@ -42,5 +38,5 @@ export declare const jsonFlag: {
 /**
  * Clear the CLI cache, used to store some API responses and handle notifications status
  */
-export declare function clearCache(): Promise<void>;
+export declare function clearCache(): void;
 export {};
\ No newline at end of file

[vividviolet]

/snapit