@shopify/cli-hydrogen 4.1.1 → 4.1.2

package/dist/commands/hydrogen/dev.d.ts

@@ -7,6 +7,7 @@ declare class Dev extends Command {
         path: _oclif_core_lib_interfaces_parser_js.OptionFlag<string | undefined, _oclif_core_lib_interfaces_parser_js.CustomOptions>;
         port: _oclif_core_lib_interfaces_parser_js.OptionFlag<number, _oclif_core_lib_interfaces_parser_js.CustomOptions>;
         "disable-virtual-routes": _oclif_core_lib_interfaces_parser_js.BooleanFlag<boolean>;
+        debug: _oclif_core_lib_interfaces_parser_js.BooleanFlag<boolean>;
         host: _oclif_core_lib_interfaces_parser_js.OptionFlag<unknown, _oclif_core_lib_interfaces_parser_js.CustomOptions>;
     };
     run(): Promise<void>;

package/dist/commands/hydrogen/dev.js

@@ -25,6 +25,11 @@ class Dev extends Command {
       env: "SHOPIFY_HYDROGEN_FLAG_DISABLE_VIRTUAL_ROUTES",
       default: false
     }),
+    debug: Flags.boolean({
+      description: "Attaches a Node inspector",
+      env: "SHOPIFY_HYDROGEN_FLAG_DEBUG",
+      default: false
+    }),
     host: deprecated("--host")()
   };
   async run() {
@@ -36,11 +41,14 @@ class Dev extends Command {
 async function runDev({
   port,
   path: appPath,
+  debug = false,
   disableVirtualRoutes
 }) {
   if (!process.env.NODE_ENV)
     process.env.NODE_ENV = "development";
   muteDevLogs();
+  if (debug)
+    (await import('node:inspector')).open();
   console.time(LOG_INITIAL_BUILD);
   const { root, publicPath, buildPathClient, buildPathWorkerFile } = getProjectPaths(appPath);
   const checkingHydrogenVersion = checkHydrogenVersion(root);

package/dist/commands/hydrogen/env/pull.d.ts

@@ -0,0 +1,21 @@
+import * as _oclif_core_lib_interfaces_parser_js from '@oclif/core/lib/interfaces/parser.js';
+import Command from '@shopify/cli-kit/node/base-command';
+
+declare class Pull extends Command {
+    static description: string;
+    static hidden: boolean;
+    static flags: {
+        path: _oclif_core_lib_interfaces_parser_js.OptionFlag<string | undefined, _oclif_core_lib_interfaces_parser_js.CustomOptions>;
+        shop: _oclif_core_lib_interfaces_parser_js.OptionFlag<string | undefined, _oclif_core_lib_interfaces_parser_js.CustomOptions>;
+        force: _oclif_core_lib_interfaces_parser_js.BooleanFlag<boolean>;
+    };
+    run(): Promise<void>;
+}
+interface Flags {
+    force?: boolean;
+    path?: string;
+    shop?: string;
+}
+declare function pullVariables({ force, path, shop: flagShop }: Flags): Promise<void>;
+
+export { Pull as default, pullVariables };

package/dist/commands/hydrogen/env/pull.js

@@ -0,0 +1,115 @@
+import Command from '@shopify/cli-kit/node/base-command';
+import { renderFatalError, renderConfirmationPrompt } from '@shopify/cli-kit/node/ui';
+import { outputContent, outputToken, outputInfo, outputWarn, outputSuccess } from '@shopify/cli-kit/node/output';
+import { fileExists, writeFile } from '@shopify/cli-kit/node/fs';
+import { resolvePath } from '@shopify/cli-kit/node/path';
+import { linkStorefront } from '../link.js';
+import { adminRequest, parseGid } from '../../../lib/graphql.js';
+import { commonFlags } from '../../../lib/flags.js';
+import { getHydrogenShop } from '../../../lib/shop.js';
+import { getAdminSession } from '../../../lib/admin-session.js';
+import { PullVariablesQuery } from '../../../lib/graphql/admin/pull-variables.js';
+import { getConfig } from '../../../lib/shopify-config.js';
+import { hydrogenStorefrontsUrl } from '../../../lib/admin-urls.js';
+
+class Pull extends Command {
+  static description = "Populate your .env with variables from your Hydrogen storefront.";
+  static hidden = true;
+  static flags = {
+    path: commonFlags.path,
+    shop: commonFlags.shop,
+    force: commonFlags.force
+  };
+  async run() {
+    const { flags } = await this.parse(Pull);
+    await pullVariables(flags);
+  }
+}
+async function pullVariables({ force, path, shop: flagShop }) {
+  const shop = await getHydrogenShop({ path, shop: flagShop });
+  const adminSession = await getAdminSession(shop);
+  const actualPath = path ?? process.cwd();
+  let configStorefront = (await getConfig(actualPath)).storefront;
+  if (!configStorefront?.id) {
+    renderFatalError({
+      name: "NoLinkedStorefrontError",
+      type: 0,
+      message: `No linked Hydrogen storefront on ${adminSession.storeFqdn}`,
+      tryMessage: outputContent`To pull environment variables, link this project to a Hydrogen storefront. To select a storefront to link, run ${outputToken.genericShellCommand(
+        `npx shopify hydrogen link`
+      )}.`.value
+    });
+    const runLink = await renderConfirmationPrompt({
+      message: outputContent`Run ${outputToken.genericShellCommand(
+        `npx shopify hydrogen link`
+      )}?`.value
+    });
+    if (!runLink) {
+      return;
+    }
+    await linkStorefront({ force, path, shop: flagShop, silent: true });
+  }
+  configStorefront = (await getConfig(actualPath)).storefront;
+  if (!configStorefront) {
+    return;
+  }
+  outputInfo(
+    `Fetching Preview environment variables from ${configStorefront.title}...`
+  );
+  const result = await adminRequest(
+    PullVariablesQuery,
+    adminSession,
+    {
+      id: configStorefront.id
+    }
+  );
+  const hydrogenStorefront = result.hydrogenStorefront;
+  if (!hydrogenStorefront) {
+    renderFatalError({
+      name: "NoStorefrontError",
+      type: 0,
+      message: outputContent`${outputToken.errorText(
+        "Couldn\u2019t find Hydrogen storefront."
+      )}`.value,
+      tryMessage: outputContent`Couldn’t find ${configStorefront.title} (ID: ${parseGid(configStorefront.id)}) on ${adminSession.storeFqdn}. Check that the storefront exists and run ${outputToken.genericShellCommand(
+        `npx shopify hydrogen link`
+      )} to link this project to it.\n\n${outputToken.link(
+        "Hydrogen Storefronts Admin",
+        hydrogenStorefrontsUrl(adminSession)
+      )}`.value
+    });
+    return;
+  }
+  if (!hydrogenStorefront.environmentVariables.length) {
+    outputInfo(`No Preview environment variables found.`);
+    return;
+  }
+  const dotEnvPath = resolvePath(actualPath, ".env");
+  if (await fileExists(dotEnvPath) && !force) {
+    const overwrite = await renderConfirmationPrompt({
+      message: "Warning: .env file already exists. Do you want to overwrite it?"
+    });
+    if (!overwrite) {
+      return;
+    }
+  }
+  let hasSecretVariables = false;
+  const contents = hydrogenStorefront.environmentVariables.map(({ key, value, isSecret }) => {
+    let line = `${key}="${value}"`;
+    if (isSecret) {
+      hasSecretVariables = true;
+      line = `# ${key} is marked as secret and its value is hidden
+` + line;
+    }
+    return line;
+  }).join("\n") + "\n";
+  if (hasSecretVariables) {
+    outputWarn(
+      `${configStorefront.title} contains environment variables marked as secret, so their values weren\u2019t pulled.`
+    );
+  }
+  await writeFile(dotEnvPath, contents);
+  outputSuccess("Updated .env");
+}
+
+export { Pull as default, pullVariables };

package/dist/commands/hydrogen/env/pull.test.d.ts

@@ -0,0 +1 @@
+

package/dist/commands/hydrogen/env/pull.test.js

@@ -0,0 +1,205 @@
+import { vi, describe, beforeEach, afterEach, it, expect } from 'vitest';
+import { mockAndCaptureOutput } from '@shopify/cli-kit/node/testing/output';
+import { inTemporaryDirectory, fileExists, readFile, writeFile } from '@shopify/cli-kit/node/fs';
+import { joinPath } from '@shopify/cli-kit/node/path';
+import { renderConfirmationPrompt } from '@shopify/cli-kit/node/ui';
+import { PullVariablesQuery } from '../../../lib/graphql/admin/pull-variables.js';
+import { getAdminSession } from '../../../lib/admin-session.js';
+import { adminRequest } from '../../../lib/graphql.js';
+import { getConfig } from '../../../lib/shopify-config.js';
+import { linkStorefront } from '../link.js';
+import { pullVariables } from './pull.js';
+
+vi.mock("@shopify/cli-kit/node/ui", async () => {
+  const original = await vi.importActual("@shopify/cli-kit/node/ui");
+  return {
+    ...original,
+    renderConfirmationPrompt: vi.fn()
+  };
+});
+vi.mock("../link.js");
+vi.mock("../../../lib/admin-session.js");
+vi.mock("../../../lib/shopify-config.js");
+vi.mock("../../../lib/graphql.js", async () => {
+  const original = await vi.importActual("../../../lib/graphql.js");
+  return {
+    ...original,
+    adminRequest: vi.fn()
+  };
+});
+vi.mock("../../../lib/shop.js", () => ({
+  getHydrogenShop: () => "my-shop"
+}));
+describe("pullVariables", () => {
+  const ADMIN_SESSION = {
+    token: "abc123",
+    storeFqdn: "my-shop"
+  };
+  beforeEach(async () => {
+    vi.mocked(getAdminSession).mockResolvedValue(ADMIN_SESSION);
+    vi.mocked(getConfig).mockResolvedValue({
+      storefront: {
+        id: "gid://shopify/HydrogenStorefront/2",
+        title: "Existing Link"
+      }
+    });
+    vi.mocked(adminRequest).mockResolvedValue({
+      hydrogenStorefront: {
+        id: "gid://shopify/HydrogenStorefront/1",
+        environmentVariables: [
+          {
+            id: "gid://shopify/HydrogenStorefrontEnvironmentVariable/1",
+            key: "PUBLIC_API_TOKEN",
+            value: "abc123",
+            isSecret: false
+          },
+          {
+            id: "gid://shopify/HydrogenStorefrontEnvironmentVariable/1",
+            key: "PRIVATE_API_TOKEN",
+            value: "",
+            isSecret: true
+          }
+        ]
+      }
+    });
+  });
+  afterEach(() => {
+    vi.resetAllMocks();
+    mockAndCaptureOutput().clear();
+  });
+  it("makes a GraphQL call to fetch environment variables", async () => {
+    await inTemporaryDirectory(async (tmpDir) => {
+      await pullVariables({ path: tmpDir });
+      expect(adminRequest).toHaveBeenCalledWith(
+        PullVariablesQuery,
+        ADMIN_SESSION,
+        {
+          id: "gid://shopify/HydrogenStorefront/2"
+        }
+      );
+    });
+  });
+  it("writes environment variables to a .env file", async () => {
+    await inTemporaryDirectory(async (tmpDir) => {
+      const filePath = joinPath(tmpDir, ".env");
+      expect(await fileExists(filePath)).toBeFalsy();
+      await pullVariables({ path: tmpDir });
+      expect(await readFile(filePath)).toStrictEqual(
+        'PUBLIC_API_TOKEN="abc123"\n# PRIVATE_API_TOKEN is marked as secret and its value is hidden\nPRIVATE_API_TOKEN=""\n'
+      );
+    });
+  });
+  it("warns if there are any variables marked as secret", async () => {
+    vi.mocked(adminRequest).mockResolvedValue({
+      hydrogenStorefront: {
+        id: "gid://shopify/HydrogenStorefront/1",
+        environmentVariables: [
+          {
+            id: "gid://shopify/HydrogenStorefrontEnvironmentVariable/1",
+            key: "PRIVATE_API_TOKEN",
+            value: "",
+            isSecret: true
+          }
+        ]
+      }
+    });
+    await inTemporaryDirectory(async (tmpDir) => {
+      const outputMock = mockAndCaptureOutput();
+      await pullVariables({ path: tmpDir });
+      expect(outputMock.warn()).toStrictEqual(
+        "Existing Link contains environment variables marked as secret, so their values weren\u2019t pulled."
+      );
+    });
+  });
+  describe("when a .env file already exists", () => {
+    beforeEach(() => {
+      vi.mocked(renderConfirmationPrompt).mockResolvedValue(true);
+    });
+    it("prompts the user to confirm", async () => {
+      await inTemporaryDirectory(async (tmpDir) => {
+        const filePath = joinPath(tmpDir, ".env");
+        await writeFile(filePath, "EXISTING_TOKEN=1");
+        await pullVariables({ path: tmpDir });
+        expect(renderConfirmationPrompt).toHaveBeenCalledWith({
+          message: expect.stringMatching(
+            /Warning: \.env file already exists\. Do you want to overwrite it\?/
+          )
+        });
+      });
+    });
+    describe("and --force is enabled", () => {
+      it("does not prompt the user to confirm", async () => {
+        await inTemporaryDirectory(async (tmpDir) => {
+          const filePath = joinPath(tmpDir, ".env");
+          await writeFile(filePath, "EXISTING_TOKEN=1");
+          await pullVariables({ path: tmpDir, force: true });
+          expect(renderConfirmationPrompt).not.toHaveBeenCalled();
+        });
+      });
+    });
+  });
+  describe("when there are no environment variables to update", () => {
+    beforeEach(() => {
+      vi.mocked(adminRequest).mockResolvedValue({
+        hydrogenStorefront: {
+          id: "gid://shopify/HydrogenStorefront/1",
+          environmentVariables: []
+        }
+      });
+    });
+    it("renders a message", async () => {
+      await inTemporaryDirectory(async (tmpDir) => {
+        const outputMock = mockAndCaptureOutput();
+        await pullVariables({ path: tmpDir });
+        expect(outputMock.info()).toMatch(
+          /No Preview environment variables found\./
+        );
+      });
+    });
+  });
+  describe("when there is no linked storefront", () => {
+    beforeEach(() => {
+      vi.mocked(getConfig).mockResolvedValue({
+        storefront: void 0
+      });
+    });
+    it("renders an error message", async () => {
+      await inTemporaryDirectory(async (tmpDir) => {
+        const outputMock = mockAndCaptureOutput();
+        await pullVariables({ path: tmpDir });
+        expect(outputMock.error()).toMatch(
+          /No linked Hydrogen storefront on my-shop/
+        );
+      });
+    });
+    it("prompts the user to create a link", async () => {
+      vi.mocked(renderConfirmationPrompt).mockResolvedValue(true);
+      await inTemporaryDirectory(async (tmpDir) => {
+        await pullVariables({ path: tmpDir });
+        expect(renderConfirmationPrompt).toHaveBeenCalledWith({
+          message: expect.stringMatching(/Run .*npx shopify hydrogen link.*\?/)
+        });
+        expect(linkStorefront).toHaveBeenCalledWith({
+          path: tmpDir,
+          silent: true
+        });
+      });
+    });
+  });
+  describe("when there is no matching storefront in the shop", () => {
+    beforeEach(() => {
+      vi.mocked(adminRequest).mockResolvedValue({
+        hydrogenStorefront: null
+      });
+    });
+    it("renders an error message", async () => {
+      await inTemporaryDirectory(async (tmpDir) => {
+        const outputMock = mockAndCaptureOutput();
+        await pullVariables({ path: tmpDir });
+        expect(outputMock.error()).toMatch(
+          /Couldn’t find Hydrogen storefront\./
+        );
+      });
+    });
+  });
+});

package/dist/commands/hydrogen/init.js

@@ -152,7 +152,9 @@ async function runInit(options = parseProcessFlags(process.argv, FLAG_MAP)) {
       )} to start your local development server and start building`.value
     ].filter((step) => Boolean(step)),
     reference: [
-      "Building with Hydrogen: https://shopify.dev/docs/custom-storefronts/hydrogen/building/begin-development"
+      "Getting started with Hydrogen: https://shopify.dev/docs/custom-storefronts/hydrogen/building/begin-development",
+      "Hydrogen project structure: https://shopify.dev/docs/custom-storefronts/hydrogen/project-structure",
+      "Setting up Hydrogen environment variables: https://shopify.dev/docs/custom-storefronts/hydrogen/environment-variables"
     ]
   });
   if (appTemplate === "demo-store") {

package/dist/commands/hydrogen/link.d.ts

@@ -0,0 +1,24 @@
+import * as _oclif_core_lib_interfaces_parser_js from '@oclif/core/lib/interfaces/parser.js';
+import Command from '@shopify/cli-kit/node/base-command';
+
+declare class Link extends Command {
+    static description: string;
+    static hidden: boolean;
+    static flags: {
+        force: _oclif_core_lib_interfaces_parser_js.BooleanFlag<boolean>;
+        path: _oclif_core_lib_interfaces_parser_js.OptionFlag<string | undefined, _oclif_core_lib_interfaces_parser_js.CustomOptions>;
+        shop: _oclif_core_lib_interfaces_parser_js.OptionFlag<string | undefined, _oclif_core_lib_interfaces_parser_js.CustomOptions>;
+        storefront: _oclif_core_lib_interfaces_parser_js.OptionFlag<string | undefined, _oclif_core_lib_interfaces_parser_js.CustomOptions>;
+    };
+    run(): Promise<void>;
+}
+interface LinkStorefrontArguments {
+    force?: boolean;
+    path?: string;
+    shop?: string;
+    storefront?: string;
+    silent?: boolean;
+}
+declare function linkStorefront({ force, path, shop: flagShop, storefront: flagStorefront, silent, }: LinkStorefrontArguments): Promise<void>;
+
+export { LinkStorefrontArguments, Link as default, linkStorefront };

package/dist/commands/hydrogen/link.js

@@ -0,0 +1,102 @@
+import { Flags } from '@oclif/core';
+import Command from '@shopify/cli-kit/node/base-command';
+import { renderConfirmationPrompt, renderWarning, renderSelectPrompt } from '@shopify/cli-kit/node/ui';
+import { outputContent, outputToken, outputSuccess, outputInfo } from '@shopify/cli-kit/node/output';
+import { adminRequest, parseGid } from '../../lib/graphql.js';
+import { commonFlags } from '../../lib/flags.js';
+import { getHydrogenShop } from '../../lib/shop.js';
+import { getAdminSession } from '../../lib/admin-session.js';
+import { hydrogenStorefrontUrl } from '../../lib/admin-urls.js';
+import { LinkStorefrontQuery } from '../../lib/graphql/admin/link-storefront.js';
+import { getConfig, setStorefront } from '../../lib/shopify-config.js';
+import { logMissingStorefronts } from '../../lib/missing-storefronts.js';
+
+class Link extends Command {
+  static description = "Link a local project to one of your shop's Hydrogen storefronts.";
+  static hidden = true;
+  static flags = {
+    force: commonFlags.force,
+    path: commonFlags.path,
+    shop: commonFlags.shop,
+    storefront: Flags.string({
+      char: "h",
+      description: `The name of a Hydrogen Storefront (e.g. "Jane's Apparel")`,
+      env: "SHOPIFY_HYDROGEN_STOREFRONT"
+    })
+  };
+  async run() {
+    const { flags } = await this.parse(Link);
+    await linkStorefront(flags);
+  }
+}
+async function linkStorefront({
+  force,
+  path,
+  shop: flagShop,
+  storefront: flagStorefront,
+  silent = false
+}) {
+  const shop = await getHydrogenShop({ path, shop: flagShop });
+  const { storefront: configStorefront } = await getConfig(path ?? process.cwd());
+  if (configStorefront && !force) {
+    const overwriteLink = await renderConfirmationPrompt({
+      message: `Your project is currently linked to ${configStorefront.title}. Do you want to link to a different Hydrogen storefront on Shopify?`
+    });
+    if (!overwriteLink) {
+      return;
+    }
+  }
+  const adminSession = await getAdminSession(shop);
+  const result = await adminRequest(
+    LinkStorefrontQuery,
+    adminSession
+  );
+  if (!result.hydrogenStorefronts.length) {
+    logMissingStorefronts(adminSession);
+    return;
+  }
+  let selectedStorefront;
+  if (flagStorefront) {
+    selectedStorefront = result.hydrogenStorefronts.find(
+      (storefront) => storefront.title === flagStorefront
+    );
+    if (!selectedStorefront) {
+      renderWarning({
+        headline: `Couldn't find ${flagStorefront}`,
+        body: outputContent`There's no storefront matching ${flagStorefront} on your ${shop} shop. To see all available Hydrogen storefronts, run ${outputToken.genericShellCommand(
+          `npx shopify hydrogen list`
+        )}`.value
+      });
+      return;
+    }
+  } else {
+    const choices = result.hydrogenStorefronts.map((storefront) => ({
+      label: `${storefront.title} ${storefront.productionUrl}${storefront.id === configStorefront?.id ? " (Current)" : ""}`,
+      value: storefront.id
+    }));
+    const storefrontId = await renderSelectPrompt({
+      message: "Choose a Hydrogen storefront to link this project to:",
+      choices,
+      defaultValue: "true"
+    });
+    selectedStorefront = result.hydrogenStorefronts.find(
+      (storefront) => storefront.id === storefrontId
+    );
+  }
+  if (!selectedStorefront) {
+    return;
+  }
+  await setStorefront(path ?? process.cwd(), selectedStorefront);
+  outputSuccess(`Linked to ${selectedStorefront.title}`);
+  if (!silent) {
+    outputInfo(
+      `Admin URL: ${hydrogenStorefrontUrl(
+        adminSession,
+        parseGid(selectedStorefront.id)
+      )}`
+    );
+    outputInfo(`Site URL: ${selectedStorefront.productionUrl}`);
+  }
+}
+
+export { Link as default, linkStorefront };

package/dist/commands/hydrogen/link.test.d.ts

@@ -0,0 +1 @@
+

package/dist/commands/hydrogen/link.test.js

@@ -0,0 +1,137 @@
+import { vi, describe, beforeEach, afterEach, it, expect } from 'vitest';
+import { mockAndCaptureOutput } from '@shopify/cli-kit/node/testing/output';
+import { renderSelectPrompt, renderConfirmationPrompt } from '@shopify/cli-kit/node/ui';
+import { adminRequest } from '../../lib/graphql.js';
+import { LinkStorefrontQuery } from '../../lib/graphql/admin/link-storefront.js';
+import { getAdminSession } from '../../lib/admin-session.js';
+import { getConfig, setStorefront } from '../../lib/shopify-config.js';
+import { linkStorefront } from './link.js';
+
+vi.mock("@shopify/cli-kit/node/ui", async () => {
+  const original = await vi.importActual("@shopify/cli-kit/node/ui");
+  return {
+    ...original,
+    renderConfirmationPrompt: vi.fn(),
+    renderSelectPrompt: vi.fn()
+  };
+});
+vi.mock("../../lib/graphql.js");
+vi.mock("../../lib/shopify-config.js");
+vi.mock("../../lib/admin-session.js");
+vi.mock("../../lib/shop.js", () => ({
+  getHydrogenShop: () => "my-shop"
+}));
+const ADMIN_SESSION = {
+  token: "abc123",
+  storeFqdn: "my-shop"
+};
+describe("link", () => {
+  const outputMock = mockAndCaptureOutput();
+  beforeEach(async () => {
+    vi.mocked(getAdminSession).mockResolvedValue(ADMIN_SESSION);
+    vi.mocked(adminRequest).mockResolvedValue({
+      hydrogenStorefronts: [
+        {
+          id: "gid://shopify/HydrogenStorefront/1",
+          title: "Hydrogen",
+          productionUrl: "https://example.com"
+        }
+      ]
+    });
+    vi.mocked(getConfig).mockResolvedValue({});
+  });
+  afterEach(() => {
+    vi.resetAllMocks();
+    outputMock.clear();
+  });
+  it("makes a GraphQL call to fetch the storefronts", async () => {
+    await linkStorefront({});
+    expect(adminRequest).toHaveBeenCalledWith(
+      LinkStorefrontQuery,
+      ADMIN_SESSION
+    );
+  });
+  it("renders a list of choices and forwards the selection to setStorefront", async () => {
+    vi.mocked(renderSelectPrompt).mockResolvedValue(
+      "gid://shopify/HydrogenStorefront/1"
+    );
+    await linkStorefront({ path: "my-path" });
+    expect(setStorefront).toHaveBeenCalledWith("my-path", {
+      id: "gid://shopify/HydrogenStorefront/1",
+      title: "Hydrogen",
+      productionUrl: "https://example.com"
+    });
+  });
+  describe("when there are no Hydrogen storefronts", () => {
+    it("renders a message and returns early", async () => {
+      vi.mocked(adminRequest).mockResolvedValue({
+        hydrogenStorefronts: []
+      });
+      await linkStorefront({});
+      expect(outputMock.info()).toMatch(
+        /There are no Hydrogen storefronts on your Shop/g
+      );
+      expect(renderSelectPrompt).not.toHaveBeenCalled();
+      expect(setStorefront).not.toHaveBeenCalled();
+    });
+  });
+  describe("when no storefront gets selected", () => {
+    it("does not call setStorefront", async () => {
+      vi.mocked(renderSelectPrompt).mockResolvedValue("");
+      await linkStorefront({});
+      expect(setStorefront).not.toHaveBeenCalled();
+    });
+  });
+  describe("when a linked storefront already exists", () => {
+    beforeEach(() => {
+      vi.mocked(getConfig).mockResolvedValue({
+        storefront: {
+          id: "gid://shopify/HydrogenStorefront/2",
+          title: "Existing Link"
+        }
+      });
+    });
+    it("prompts the user to confirm", async () => {
+      vi.mocked(renderConfirmationPrompt).mockResolvedValue(true);
+      await linkStorefront({});
+      expect(renderConfirmationPrompt).toHaveBeenCalledWith({
+        message: expect.stringMatching(
+          /Do you want to link to a different Hydrogen storefront on Shopify\?/
+        )
+      });
+    });
+    describe("and the user cancels", () => {
+      it("returns early", async () => {
+        vi.mocked(renderConfirmationPrompt).mockResolvedValue(false);
+        await linkStorefront({});
+        expect(adminRequest).not.toHaveBeenCalled();
+        expect(setStorefront).not.toHaveBeenCalled();
+      });
+    });
+    describe("and the --force flag is provided", () => {
+      it("does not prompt the user to confirm", async () => {
+        await linkStorefront({ force: true });
+        expect(renderConfirmationPrompt).not.toHaveBeenCalled();
+      });
+    });
+  });
+  describe("when the --storefront flag is provided", () => {
+    it("does not prompt the user to make a selection", async () => {
+      await linkStorefront({ path: "my-path", storefront: "Hydrogen" });
+      expect(renderSelectPrompt).not.toHaveBeenCalled();
+      expect(setStorefront).toHaveBeenCalledWith("my-path", {
+        id: "gid://shopify/HydrogenStorefront/1",
+        title: "Hydrogen",
+        productionUrl: "https://example.com"
+      });
+    });
+    describe("and there is no matching storefront", () => {
+      it("renders a warning message and returns early", async () => {
+        const outputMock2 = mockAndCaptureOutput();
+        await linkStorefront({ storefront: "Does not exist" });
+        expect(setStorefront).not.toHaveBeenCalled();
+        expect(outputMock2.warn()).toMatch(/Couldn\'t find Does not exist/g);
+      });
+    });
+  });
+});

package/dist/commands/hydrogen/list.d.ts

@@ -0,0 +1,21 @@
+import * as _oclif_core_lib_interfaces_parser_js from '@oclif/core/lib/interfaces/parser.js';
+import Command from '@shopify/cli-kit/node/base-command';
+import { Deployment } from '../../lib/graphql/admin/list-storefronts.js';
+
+declare class List extends Command {
+    static description: string;
+    static hidden: boolean;
+    static flags: {
+        path: _oclif_core_lib_interfaces_parser_js.OptionFlag<string | undefined, _oclif_core_lib_interfaces_parser_js.CustomOptions>;
+        shop: _oclif_core_lib_interfaces_parser_js.OptionFlag<string | undefined, _oclif_core_lib_interfaces_parser_js.CustomOptions>;
+    };
+    run(): Promise<void>;
+}
+interface Flags {
+    path?: string;
+    shop?: string;
+}
+declare function listStorefronts({ path, shop: flagShop }: Flags): Promise<void>;
+declare function formatDeployment(deployment: Deployment | null): string;
+
+export { List as default, formatDeployment, listStorefronts };