@shopify/hydrogen 2026.4.5 → 2026.10.0-preview.2

package/dist/cli/index.mjs

@@ -0,0 +1,647 @@
+#!/usr/bin/env node
+import { createRequire } from "node:module";
+import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { chmod, mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, isAbsolute, join, parse, resolve } from "node:path";
+import { spawn } from "node:child_process";
+import { createHash, randomUUID } from "node:crypto";
+import { parseArgs } from "node:util";
+
+//#region src/core/logging/types.ts
+const DEFAULT_LOG_LEVEL = "info";
+const LOG_LEVEL_VALUES = {
+	trace: 10,
+	debug: 20,
+	info: 30,
+	warn: 40,
+	error: 50,
+	fatal: 60,
+	silent: Number.POSITIVE_INFINITY
+};
+function isLevelEnabled(level, threshold) {
+	return LOG_LEVEL_VALUES[level] >= LOG_LEVEL_VALUES[threshold];
+}
+
+//#endregion
+//#region src/core/logging/logging.ts
+const CONSOLE_METHODS = {
+	trace: "debug",
+	debug: "debug",
+	info: "info",
+	warn: "warn",
+	error: "error",
+	fatal: "error"
+};
+function formatLogPrefix(level, scope) {
+	return `[hydrogen:${level}:${scope}]`;
+}
+function writeToConsole(level, message, context) {
+	const { scope, error, ...rest } = context ?? {};
+	const args = [scope ? `${formatLogPrefix(level, scope)} ${message}` : message];
+	if (error !== void 0) args.push(error);
+	if (Object.keys(rest).length > 0) args.push(rest);
+	console[CONSOLE_METHODS[level]](...args);
+}
+/**
+* Built-in sink: writes `[hydrogen:<level>:<scope>] <message>` to a
+* level-specific `console` method, followed by `context.error` and any extra
+* context fields. `trace` uses `console.debug`; `fatal` uses `console.error`.
+*/
+const consoleLogger = {
+	trace: (message, context) => writeToConsole("trace", message, context),
+	debug: (message, context) => writeToConsole("debug", message, context),
+	info: (message, context) => writeToConsole("info", message, context),
+	warn: (message, context) => writeToConsole("warn", message, context),
+	error: (message, context) => writeToConsole("error", message, context),
+	fatal: (message, context) => writeToConsole("fatal", message, context)
+};
+const state = {
+	logger: consoleLogger,
+	level: DEFAULT_LOG_LEVEL
+};
+function emit(scope, level, message, context) {
+	if (!isLevelEnabled(level, state.level)) return;
+	try {
+		state.logger[level](message, {
+			...context,
+			scope
+		});
+	} catch (error) {
+		reportLoggerFailure(error, {
+			level,
+			scope,
+			message,
+			context
+		});
+	}
+}
+function reportLoggerFailure(error, failedEntry) {
+	if (state.logger === consoleLogger) return;
+	const fallbackContext = {
+		scope: "logging",
+		error,
+		originalLevel: failedEntry.level,
+		originalScope: failedEntry.scope,
+		originalMessage: failedEntry.message
+	};
+	if (failedEntry.context !== void 0) fallbackContext.originalContext = failedEntry.context;
+	try {
+		consoleLogger.error("configured logger failed", fallbackContext);
+	} catch {}
+}
+/** @internal Returns the lazily-resolved scoped logger for a Hydrogen subsystem. */
+function getLogger(scope) {
+	return {
+		trace: (message, context) => emit(scope, "trace", message, context),
+		debug: (message, context) => emit(scope, "debug", message, context),
+		info: (message, context) => emit(scope, "info", message, context),
+		warn: (message, context) => emit(scope, "warn", message, context),
+		error: (message, context) => emit(scope, "error", message, context),
+		fatal: (message, context) => emit(scope, "fatal", message, context)
+	};
+}
+
+//#endregion
+//#region src/vite/mkcert.ts
+const log = getLogger("local-https");
+function confirm(message) {
+	consoleLogger.info(`☑️ ${message}`);
+}
+const MKCERT_VERSION = "v1.4.4";
+const MKCERT_RELEASE_BASE_URL = `https://github.com/FiloSottile/mkcert/releases/download/${MKCERT_VERSION}`;
+const EXECUTABLE_MODE = 493;
+const SUCCESS_EXIT_CODE$2 = 0;
+const DOWNLOAD_TIMEOUT_MS = 6e4;
+const MKCERT_BINARIES = {
+	"darwin-arm64": {
+		assetName: `mkcert-${MKCERT_VERSION}-darwin-arm64`,
+		sha256: "c8af0df44bce04359794dad8ea28d750437411d632748049d08644ffb66a60c6"
+	},
+	"darwin-x64": {
+		assetName: `mkcert-${MKCERT_VERSION}-darwin-amd64`,
+		sha256: "a32dfab51f1845d51e810db8e47dcf0e6b51ae3422426514bf5a2b8302e97d4e"
+	},
+	"linux-arm64": {
+		assetName: `mkcert-${MKCERT_VERSION}-linux-arm64`,
+		sha256: "b98f2cc69fd9147fe4d405d859c57504571adec0d3611c3eefd04107c7ac00d0"
+	},
+	"linux-x64": {
+		assetName: `mkcert-${MKCERT_VERSION}-linux-amd64`,
+		sha256: "6d31c65b03972c6dc4a14ab429f2928300518b26503f58723e532d1b0a3bbb52"
+	},
+	"win32-arm64": {
+		assetName: `mkcert-${MKCERT_VERSION}-windows-arm64.exe`,
+		sha256: "793747256c562622d40127c8080df26add2fb44c50906ce9db63b42a5280582e"
+	},
+	"win32-x64": {
+		assetName: `mkcert-${MKCERT_VERSION}-windows-amd64.exe`,
+		sha256: "d2660b50a9ed59eada480750561c96abc2ed4c9a38c6a24d93e30e0977631398"
+	}
+};
+/** @internal Exported for tests. */
+function resolveMkcertBinary(platform, arch) {
+	const binary = MKCERT_BINARIES[`${platform}-${arch}`];
+	if (!binary) return void 0;
+	return {
+		...binary,
+		url: `${MKCERT_RELEASE_BASE_URL}/${binary.assetName}`
+	};
+}
+function sha256Hex(bytes) {
+	return createHash("sha256").update(bytes).digest("hex");
+}
+/** @internal Exported for tests. */
+async function downloadVerified(options) {
+	let bytes;
+	try {
+		const response = await fetch(options.url, { signal: AbortSignal.timeout(DOWNLOAD_TIMEOUT_MS) });
+		if (!response.ok) throw new Error(`mkcert download failed with status ${response.status}: ${options.url}`);
+		bytes = new Uint8Array(await response.arrayBuffer());
+	} catch (error) {
+		if (error instanceof Error && error.name === "TimeoutError") throw new Error(`mkcert download timed out after ${DOWNLOAD_TIMEOUT_MS / 1e3}s: ${options.url}`, { cause: error });
+		throw error;
+	}
+	const digest = sha256Hex(bytes);
+	if (digest !== options.sha256) throw new Error(`mkcert download did not match the pinned SHA-256 checksum; refusing to run it.\n  URL:      ${options.url}\n  Expected: ${options.sha256}\n  Received: ${digest}`);
+	await mkdir(dirname(options.destination), { recursive: true });
+	const temporaryPath = `${options.destination}.tmp-${process.pid}`;
+	try {
+		await writeFile(temporaryPath, bytes, { mode: EXECUTABLE_MODE });
+		await chmod(temporaryPath, EXECUTABLE_MODE);
+		await rename(temporaryPath, options.destination);
+	} catch (error) {
+		await rm(temporaryPath, { force: true });
+		throw error;
+	}
+}
+async function ensureMkcertBinary() {
+	const binary = resolveMkcertBinary(process.platform, process.arch);
+	if (!binary) throw new Error(`Automatic mkcert download is not available for ${process.platform}-${process.arch}. Install mkcert manually and generate the certificate.`);
+	const binaryPath = join(homedir(), ".shopify", "hydrogen", "mkcert", binary.assetName);
+	if (existsSync(binaryPath) && sha256Hex(await readFile(binaryPath)) === binary.sha256) return binaryPath;
+	log.info(`downloading mkcert ${MKCERT_VERSION}…`);
+	await downloadVerified({
+		url: binary.url,
+		sha256: binary.sha256,
+		destination: binaryPath
+	});
+	confirm(`mkcert ${MKCERT_VERSION} downloaded`);
+	return binaryPath;
+}
+function runMkcert(binaryPath, args) {
+	return new Promise((resolve, reject) => {
+		const child = spawn(binaryPath, args, { stdio: [
+			"inherit",
+			"pipe",
+			"pipe"
+		] });
+		let output = "";
+		const collect = (chunk) => {
+			output += chunk.toString();
+		};
+		child.stdout?.on("data", collect);
+		child.stderr?.on("data", collect);
+		child.on("error", reject);
+		child.on("close", (code, signal) => {
+			if (code === SUCCESS_EXIT_CODE$2) {
+				resolve(output);
+				return;
+			}
+			const reason = signal ? `mkcert was killed by ${signal}` : `mkcert exited with code ${code}`;
+			reject(new Error(output.trim() === "" ? reason : `${reason}\n${output.trim()}`));
+		});
+	});
+}
+async function provisionCertificates(settings) {
+	const binaryPath = await ensureMkcertBinary();
+	await mkdir(dirname(settings.certPath), { recursive: true });
+	await mkdir(dirname(settings.keyPath), { recursive: true });
+	log.info("generating a trusted local certificate; mkcert may prompt for your password.");
+	confirm((await runMkcert(binaryPath, [
+		"-install",
+		"-cert-file",
+		settings.certPath,
+		"-key-file",
+		settings.keyPath,
+		settings.host
+	])).includes("The local CA is already installed") ? "The local CA is already installed in the system trust store" : "The local CA is now installed in the system trust store");
+	confirm(`Created a new certificate for "${settings.host}"`);
+	log.info("verifying certificates…");
+	const missingPaths = [settings.certPath, settings.keyPath].filter((path) => !existsSync(path));
+	if (missingPaths.length > 0) throw new Error(`mkcert did not create the expected files: ${missingPaths.join(", ")}`);
+	confirm("local https certificates ready");
+}
+async function uninstallCertificateAuthority() {
+	const binaryPath = await ensureMkcertBinary();
+	log.info("removing the local certificate authority; mkcert may prompt for your password.");
+	await runMkcert(binaryPath, ["-uninstall"]);
+	confirm("The local CA was removed from the system trust stores");
+}
+
+//#endregion
+//#region src/vite/local-https.ts
+const LOCAL_HTTPS_DEFAULTS = {
+	host: "local.tryhydrogen.dev",
+	port: 5173
+};
+/**
+* Downloads a pinned, checksum-verified mkcert release and generates the
+* trusted local certificate files when they do not exist yet. The Vite plugin
+* runs this automatically on `vite dev`; call it directly for frameworks that
+* read certificate paths before Vite starts or from setup scripts.
+*/
+async function provisionLocalHttps(options = {}) {
+	const settings = resolveLocalHttpsSettings({
+		enabled: true,
+		...options
+	});
+	if (!certificateFilesExist(settings)) await provisionCertificates(settings);
+	return {
+		host: settings.host,
+		certPath: settings.certPath,
+		keyPath: settings.keyPath
+	};
+}
+function resolveLocalHttpsSettings(options) {
+	const host = options.host ?? LOCAL_HTTPS_DEFAULTS.host;
+	const certificateDirectory = join(homedir(), ".shopify", "hydrogen", "certs");
+	return {
+		host,
+		port: options.port ?? LOCAL_HTTPS_DEFAULTS.port,
+		certPath: resolveCertificatePath(options.certPath ?? join(certificateDirectory, `${host}.pem`)),
+		keyPath: resolveCertificatePath(options.keyPath ?? join(certificateDirectory, `${host}-key.pem`))
+	};
+}
+function resolveCertificatePath(path) {
+	if (path instanceof URL) return fileURLToPath(path);
+	if (path === "~") return homedir();
+	if (path.startsWith("~/")) return resolve(homedir(), path.slice(2));
+	return isAbsolute(path) ? path : resolve(path);
+}
+function certificateFilesExist(settings) {
+	return existsSync(settings.certPath) && existsSync(settings.keyPath);
+}
+
+//#endregion
+//#region src/cli/certs.ts
+const REMOVE_CA_FLAG = "--remove-ca";
+async function installLocalHttpsCertificates() {
+	const { host, certPath, keyPath } = await provisionLocalHttps();
+	console.log(`Local HTTPS is ready for https://${host}`);
+	console.log(`  Certificate: ${certPath}`);
+	console.log(`  Private key: ${keyPath}`);
+}
+async function uninstallLocalHttpsCertificates(args = []) {
+	const unknownArgument = args.find((argument) => argument !== REMOVE_CA_FLAG);
+	if (unknownArgument) throw new Error(`Unknown argument: ${unknownArgument}`);
+	const removeCertificateAuthority = args.includes(REMOVE_CA_FLAG);
+	if (removeCertificateAuthority) {
+		console.warn("Warning: removing mkcert's shared local CA will make certificates created by other projects untrusted.");
+		await uninstallCertificateAuthority();
+	}
+	const hydrogenDirectory = join(homedir(), ".shopify", "hydrogen");
+	const certificateDirectory = join(hydrogenDirectory, "certs");
+	const host = LOCAL_HTTPS_DEFAULTS.host;
+	const binary = resolveMkcertBinary(process.platform, process.arch);
+	const removals = [rm(join(certificateDirectory, `${host}.pem`), { force: true }), rm(join(certificateDirectory, `${host}-key.pem`), { force: true })];
+	if (binary) removals.push(rm(join(hydrogenDirectory, "mkcert", binary.assetName), { force: true }));
+	await Promise.all(removals);
+	console.log("Hydrogen's local HTTPS certificate files were removed.");
+	if (!removeCertificateAuthority) console.log(`The shared mkcert CA remains trusted. Pass ${REMOVE_CA_FLAG} to remove it.`);
+}
+
+//#endregion
+//#region src/graphql/plugin-config.ts
+const STOREFRONT_SCHEMA_FILE_NAME = "storefront.schema.json";
+const CUSTOMER_ACCOUNT_SCHEMA_FILE_NAME = "customer-account.schema.json";
+const STOREFRONT_OUTPUT_FILE_NAME = "storefront-graphql-env.d.ts";
+const CUSTOMER_ACCOUNT_OUTPUT_FILE_NAME = "customer-account-graphql-env.d.ts";
+function createGraphQLPluginConfig(schemaDirectory) {
+	return {
+		name: "gql.tada/ts-plugin",
+		schemas: [{
+			name: "storefront",
+			schema: join(schemaDirectory, STOREFRONT_SCHEMA_FILE_NAME),
+			tadaOutputLocation: STOREFRONT_OUTPUT_FILE_NAME
+		}, {
+			name: "customer-account",
+			schema: join(schemaDirectory, CUSTOMER_ACCOUNT_SCHEMA_FILE_NAME),
+			tadaOutputLocation: CUSTOMER_ACCOUNT_OUTPUT_FILE_NAME
+		}],
+		trackFieldUsage: false
+	};
+}
+
+//#endregion
+//#region src/cli/gql.ts
+const GQL_TADA_CLI_PATH_FROM_PACKAGE_ROOT = "bin/cli.js";
+const PACKAGE_ROOT_FROM_CLI_MODULE$1 = "../../";
+const SUCCESS_EXIT_CODE$1 = 0;
+const TSCONFIG_FILE_NAME = "tsconfig.json";
+const TEMPORARY_TSCONFIG_PREFIX = ".hydrogen-gql-";
+const CHECK_LEVELS = new Set([
+	"info",
+	"warn",
+	"error"
+]);
+function findTsconfig(cwd, configuredPath) {
+	if (configuredPath) return resolve(cwd, configuredPath);
+	let directory = cwd;
+	const root = parse(directory).root;
+	while (directory !== root) {
+		const candidate = join(directory, TSCONFIG_FILE_NAME);
+		if (existsSync(candidate)) return candidate;
+		directory = dirname(directory);
+	}
+	const rootCandidate = join(root, TSCONFIG_FILE_NAME);
+	if (existsSync(rootCandidate)) return rootCandidate;
+	throw new Error(`Could not find ${TSCONFIG_FILE_NAME}.`);
+}
+function spawnRunCommand$1(command, args, options) {
+	return new Promise((resolvePromise, reject) => {
+		const child = spawn(command, args, {
+			cwd: options.cwd,
+			stdio: "inherit"
+		});
+		child.on("error", reject);
+		child.on("close", (code) => {
+			if (code === SUCCESS_EXIT_CODE$1) {
+				resolvePromise();
+				return;
+			}
+			reject(/* @__PURE__ */ new Error(`Command failed with exit code ${code}: ${command} ${args.join(" ")}`));
+		});
+	});
+}
+function getPackageRoot$1() {
+	return resolve(import.meta.dirname, PACKAGE_ROOT_FROM_CLI_MODULE$1);
+}
+function getGqlTadaCliPath() {
+	return join(dirname(createRequire(import.meta.url).resolve("gql.tada/package.json")), GQL_TADA_CLI_PATH_FROM_PACKAGE_ROOT);
+}
+function parseCheckArgs(args) {
+	const { values } = parseArgs({
+		args,
+		options: {
+			"fail-on-warn": {
+				type: "boolean",
+				short: "w",
+				default: false
+			},
+			level: {
+				type: "string",
+				short: "l",
+				default: "info"
+			},
+			tsconfig: {
+				type: "string",
+				short: "c"
+			}
+		},
+		strict: true
+	});
+	if (!CHECK_LEVELS.has(values.level)) throw new Error(`Invalid diagnostic level: ${values.level}`);
+	return values;
+}
+async function checkGraphQL(options = {}) {
+	const cwd = options.cwd ?? process.cwd();
+	const packageRoot = options.packageRoot ?? getPackageRoot$1();
+	const gqlTadaCliPath = options.gqlTadaCliPath ?? getGqlTadaCliPath();
+	const runCommand = options.runCommand ?? spawnRunCommand$1;
+	const values = parseCheckArgs(options.args ?? []);
+	const tsconfigPath = findTsconfig(cwd, values.tsconfig);
+	const temporaryTsconfigPath = join(dirname(tsconfigPath), `${TEMPORARY_TSCONFIG_PREFIX}${randomUUID()}.json`);
+	const pluginConfig = createGraphQLPluginConfig(join(packageRoot, "dist"));
+	writeFileSync(temporaryTsconfigPath, JSON.stringify({
+		extends: tsconfigPath,
+		compilerOptions: { plugins: [pluginConfig] }
+	}), { flag: "wx" });
+	const cliArgs = [
+		gqlTadaCliPath,
+		"check",
+		"--tsconfig",
+		temporaryTsconfigPath,
+		"--level",
+		values.level
+	];
+	if (values["fail-on-warn"]) cliArgs.push("--fail-on-warn");
+	const cleanup = () => rmSync(temporaryTsconfigPath, { force: true });
+	process.once("exit", cleanup);
+	try {
+		await runCommand(process.execPath, cliArgs, { cwd });
+	} finally {
+		process.off("exit", cleanup);
+		cleanup();
+	}
+}
+
+//#endregion
+//#region src/core/utils/record.ts
+function isObjectRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+//#endregion
+//#region src/cli/setup.ts
+const PACKAGE_NAME = "@shopify/hydrogen";
+const PACKAGE_INSTALL_SPEC = `${PACKAGE_NAME}@preview`;
+const PACKAGE_ROOT_FROM_CLI_MODULE = "../../";
+const SKILLS_DIRECTORY_NAME = "skills";
+const CLAUDE_DIRECTORY_NAME = ".claude";
+const AGENTS_DIRECTORY_NAME = ".agents";
+const NODE_MODULES_DIRECTORY_NAME = "node_modules";
+const PACKAGE_JSON_FILE_NAME = "package.json";
+const SUCCESS_EXIT_CODE = 0;
+const PACKAGE_MANAGER_LOCKFILES = [
+	["pnpm", "pnpm-lock.yaml"],
+	["yarn", "yarn.lock"],
+	["npm", "package-lock.json"],
+	["bun", "bun.lockb"],
+	["bun", "bun.lock"]
+];
+const INSTALL_ARGS = {
+	pnpm: ["add", PACKAGE_INSTALL_SPEC],
+	npm: ["install", PACKAGE_INSTALL_SPEC],
+	yarn: ["add", PACKAGE_INSTALL_SPEC],
+	bun: ["add", PACKAGE_INSTALL_SPEC]
+};
+function getStringRecord(value) {
+	if (!isObjectRecord(value)) return void 0;
+	const entries = Object.entries(value);
+	if (entries.some(([, entryValue]) => typeof entryValue !== "string")) return void 0;
+	return Object.fromEntries(entries);
+}
+function readPackageJson(appRoot) {
+	const packageJsonPath = join(appRoot, PACKAGE_JSON_FILE_NAME);
+	if (!existsSync(packageJsonPath)) throw new Error(`No ${PACKAGE_JSON_FILE_NAME} found. Run this command from the app root.`);
+	const parsed = JSON.parse(readFileSync(packageJsonPath, "utf8"));
+	if (!isObjectRecord(parsed)) throw new Error(`${PACKAGE_JSON_FILE_NAME} must contain a JSON object.`);
+	return {
+		packageManager: typeof parsed.packageManager === "string" ? parsed.packageManager : void 0,
+		dependencies: getStringRecord(parsed.dependencies),
+		devDependencies: getStringRecord(parsed.devDependencies)
+	};
+}
+function parsePackageManager(value) {
+	if (!value) return void 0;
+	for (const packageManager of Object.keys(INSTALL_ARGS)) {
+		if (value === packageManager) return packageManager;
+		if (value.startsWith(`${packageManager}@`)) return packageManager;
+		if (value.startsWith(`${packageManager}/`)) return packageManager;
+	}
+}
+function detectPackageManager(appRoot, packageJson, env) {
+	const packageJsonManager = parsePackageManager(packageJson.packageManager);
+	if (packageJsonManager) return packageJsonManager;
+	for (const [packageManager, lockfile] of PACKAGE_MANAGER_LOCKFILES) if (existsSync(join(appRoot, lockfile))) return packageManager;
+	const userAgentManager = parsePackageManager(env.npm_config_user_agent);
+	if (userAgentManager) return userAgentManager;
+	throw new Error("Could not detect a package manager. Add a packageManager field or a lockfile before running setup.");
+}
+function hasHydrogenDependency(packageJson) {
+	return Boolean(packageJson.dependencies?.[PACKAGE_NAME] ?? packageJson.devDependencies?.[PACKAGE_NAME]);
+}
+async function installHydrogen(appRoot, packageManager, runCommand) {
+	await runCommand(packageManager, [...INSTALL_ARGS[packageManager]], { cwd: appRoot });
+}
+function assertDirectory(directoryPath, message) {
+	if (!existsSync(directoryPath) || !statSync(directoryPath).isDirectory()) throw new Error(message);
+}
+function getSkillsDestinationRoots(appRoot) {
+	const destinationRoots = [];
+	const claudeDirectory = join(appRoot, CLAUDE_DIRECTORY_NAME);
+	if (existsSync(claudeDirectory)) {
+		assertDirectory(claudeDirectory, `${CLAUDE_DIRECTORY_NAME} exists but is not a directory.`);
+		destinationRoots.push(join(claudeDirectory, SKILLS_DIRECTORY_NAME));
+	}
+	const agentsDirectory = join(appRoot, AGENTS_DIRECTORY_NAME);
+	if (existsSync(agentsDirectory)) {
+		assertDirectory(agentsDirectory, `${AGENTS_DIRECTORY_NAME} exists but is not a directory.`);
+		destinationRoots.push(join(agentsDirectory, SKILLS_DIRECTORY_NAME));
+	}
+	return destinationRoots.length > 0 ? destinationRoots : [join(appRoot, AGENTS_DIRECTORY_NAME, SKILLS_DIRECTORY_NAME)];
+}
+function getSkillNames(sourceSkillsRoot) {
+	assertDirectory(sourceSkillsRoot, `No packaged skills found at ${sourceSkillsRoot}.`);
+	return readdirSync(sourceSkillsRoot, { withFileTypes: true }).filter((entry) => entry.isDirectory()).map((entry) => entry.name);
+}
+function findConflictingSkills(destinationRoot, skillNames) {
+	return skillNames.filter((skillName) => existsSync(join(destinationRoot, skillName, "SKILL.md")));
+}
+function removeIncompleteSkills(destinationRoot, skillNames) {
+	for (const skillName of skillNames) {
+		const destinationPath = join(destinationRoot, skillName);
+		if (!existsSync(destinationPath)) continue;
+		if (existsSync(join(destinationPath, "SKILL.md"))) continue;
+		rmSync(destinationPath, {
+			recursive: true,
+			force: true
+		});
+	}
+}
+function copySkills(packageRoot, appRoot) {
+	const sourceSkillsRoot = join(packageRoot, SKILLS_DIRECTORY_NAME);
+	const destinationRoots = getSkillsDestinationRoots(appRoot);
+	const skillNames = getSkillNames(sourceSkillsRoot);
+	const conflictingSkills = destinationRoots.flatMap((destinationRoot) => findConflictingSkills(destinationRoot, skillNames).map((skillName) => join(destinationRoot, skillName)));
+	if (conflictingSkills.length > 0) throw new Error(`Skill directories already exist: ${conflictingSkills.join(", ")}. Remove them and rerun setup.`);
+	for (const destinationRoot of destinationRoots) {
+		removeIncompleteSkills(destinationRoot, skillNames);
+		mkdirSync(destinationRoot, { recursive: true });
+		for (const skillName of skillNames) cpSync(join(sourceSkillsRoot, skillName), join(destinationRoot, skillName), {
+			recursive: true,
+			errorOnExist: true,
+			force: false
+		});
+	}
+	return {
+		destinationRoots,
+		copiedCount: skillNames.length * destinationRoots.length
+	};
+}
+function getPackageRoot() {
+	return fileURLToPath(new URL(PACKAGE_ROOT_FROM_CLI_MODULE, import.meta.url));
+}
+function getLocalPackageRoot(appRoot) {
+	const localPackageRoot = join(appRoot, NODE_MODULES_DIRECTORY_NAME, PACKAGE_NAME);
+	if (!existsSync(localPackageRoot)) return void 0;
+	assertDirectory(localPackageRoot, `${localPackageRoot} exists but is not a directory.`);
+	return realpathSync(localPackageRoot);
+}
+function spawnRunCommand(command, args, options) {
+	return new Promise((resolve, reject) => {
+		const child = spawn(command, args, {
+			cwd: options.cwd,
+			stdio: "inherit"
+		});
+		child.on("error", reject);
+		child.on("close", (code) => {
+			if (code === SUCCESS_EXIT_CODE) {
+				resolve();
+				return;
+			}
+			reject(/* @__PURE__ */ new Error(`Command failed with exit code ${code}: ${command} ${args.join(" ")}`));
+		});
+	});
+}
+async function setupHydrogen(options = {}) {
+	const appRoot = options.cwd ?? process.cwd();
+	const env = options.env ?? process.env;
+	const runCommand = options.runCommand ?? spawnRunCommand;
+	const log = options.log ?? console.log;
+	const packageJson = readPackageJson(appRoot);
+	if (!hasHydrogenDependency(packageJson)) {
+		const packageManager = detectPackageManager(appRoot, packageJson, env);
+		log(`Installing ${PACKAGE_NAME} with ${packageManager}...`);
+		await installHydrogen(appRoot, packageManager, runCommand);
+	}
+	const result = copySkills(options.packageRoot ?? getLocalPackageRoot(appRoot) ?? getPackageRoot(), appRoot);
+	log(`Copied ${result.copiedCount} Hydrogen skills to ${result.destinationRoots.join(", ")}.`);
+}
+
+//#endregion
+//#region src/cli/index.ts
+const CLI_ARGUMENTS_INDEX = 2;
+const FAILURE_EXIT_CODE = 1;
+const COMMANDS = [
+	{
+		path: ["certs", "install"],
+		run: async (_args) => installLocalHttpsCertificates()
+	},
+	{
+		path: ["certs", "uninstall"],
+		run: async (args) => uninstallLocalHttpsCertificates(args)
+	},
+	{
+		path: ["setup"],
+		run: async (_args) => setupHydrogen()
+	},
+	{
+		path: ["gql", "check"],
+		run: async (args) => checkGraphQL({ args })
+	}
+];
+function commandMatches(path, args) {
+	return path.every((segment, index) => args[index] === segment);
+}
+function runCli() {
+	const args = process.argv.slice(CLI_ARGUMENTS_INDEX);
+	const command = COMMANDS.find(({ path }) => commandMatches(path, args));
+	if (!command) {
+		const commandName = args.join(" ");
+		const availableCommands = COMMANDS.map(({ path }) => path.join(" ")).join(", ");
+		console.error(commandName ? `Unknown command: ${commandName}` : "No command specified.");
+		console.error(`Available commands: ${availableCommands}`);
+		process.exit(FAILURE_EXIT_CODE);
+	}
+	command.run(args.slice(command.path.length)).catch((error) => {
+		console.error(error instanceof Error ? error.message : "An unexpected error occurred");
+		process.exit(FAILURE_EXIT_CODE);
+	});
+}
+if (process.argv[1] !== void 0 && fileURLToPath(import.meta.url) === realpathSync(process.argv[1])) runCli();
+
+//#endregion
+export { runCli };

package/dist/client/client.d.mts

@@ -0,0 +1,34 @@
+import { CachingStrategy } from "../core/cache/strategies.mjs";
+import { CacheInstance } from "../core/cache/run-with-cache.mjs";
+import { ShopifyRequestContext } from "../core/request-context.mjs";
+import { ClientType, CreateStorefrontClientArgs, StorefrontClient } from "./types.mjs";
+
+//#region src/client/client.d.ts
+/**
+ * Creates a type-safe Storefront API client.
+ *
+ * Pick a `type` based on where your code runs and whether buyer context is available:
+ *
+ * |                 | public                         | private                       | private_no_buyer_context |
+ * |-----------------|--------------------------------|-------------------------------|--------------------------|
+ * | Runs in         | Browser or mobile              | Server (SSR)                  | Server (background)      |
+ * | Token           | Public access token, or none   | Private access token          | Private access token     |
+ * | Buyer context   | Browser request context        | You forward trusted `buyerIp` | None                     |
+ * | Best for        | Client-side fetches            | SSR with buyer context        | Webhooks, background jobs |
+ *
+ * Pass `requestContext` so the client's SFAPI requests carry request-scoped
+ * headers, follow the incoming request's abort signal, and read the resolved
+ * `i18n` used for Storefront API variable injection and localized routes.
+ *
+ * Token-based access is required for some Storefront API fields, including
+ * product tags, metaobjects, metafields, menus, and customers. Use a private
+ * client only in trusted server code where the token cannot leak to browsers.
+ *
+ * @see {@link https://shopify.dev/docs/api/storefront#authentication | Storefront API authentication}
+ */
+declare function createStorefrontClient<const Type extends ClientType, const RequestContext extends ShopifyRequestContext, const CacheConfig extends CacheInstance | undefined = undefined>(args: CreateStorefrontClientArgs<RequestContext, Type, CacheConfig>): StorefrontClient<[CacheConfig] extends [CacheInstance] ? {
+  cache?: CachingStrategy;
+} : {}, Type, RequestContext>;
+//#endregion
+export { createStorefrontClient };
+//# sourceMappingURL=client.d.mts.map