@shopify/hydrogen 2026.10.0-preview.2 → 2026.10.0-preview.4

package/dist/cli/index.mjs

@@ -1,10 +1,11 @@
 #!/usr/bin/env node
 import { createRequire } from "node:module";
-import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { cpSync, existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, realpathSync, renameSync, 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 { homedir, tmpdir } from "node:os";
+import { basename, dirname, isAbsolute, join, parse, relative, resolve, sep } from "node:path";
+import { createInterface } from "node:readline/promises";
 import { spawn } from "node:child_process";
 import { createHash, randomUUID } from "node:crypto";
 import { parseArgs } from "node:util";
@@ -444,14 +445,455 @@ function isObjectRecord(value) {
 }
 
 //#endregion
-//#region src/cli/setup.ts
-const PACKAGE_NAME = "@shopify/hydrogen";
-const PACKAGE_INSTALL_SPEC = `${PACKAGE_NAME}@preview`;
+//#region src/cli/terminal.ts
+function canPromptInTerminal(env = process.env) {
+	return Boolean(process.stdin.isTTY && process.stdout.isTTY) && !env.CI;
+}
+async function confirmInTerminal(question) {
+	const readline = createInterface({
+		input: process.stdin,
+		output: process.stdout
+	});
+	try {
+		const answer = (await readline.question(`${question} [Y/n] `)).trim().toLowerCase();
+		return answer === "" || answer === "y" || answer === "yes";
+	} finally {
+		readline.close();
+	}
+}
+
+//#endregion
+//#region src/cli/skills.ts
+const PACKAGE_NAME$1 = "@shopify/hydrogen";
 const PACKAGE_ROOT_FROM_CLI_MODULE = "../../";
 const SKILLS_DIRECTORY_NAME = "skills";
+const SKILL_FILE_NAME = "SKILL.md";
 const CLAUDE_DIRECTORY_NAME = ".claude";
 const AGENTS_DIRECTORY_NAME = ".agents";
-const NODE_MODULES_DIRECTORY_NAME = "node_modules";
+const PACKAGE_JSON_FILE_NAME$1 = "package.json";
+const HASH_ALGORITHM = "sha256";
+const STAGING_SUFFIX = ".hydrogen-sync";
+const FRONTMATTER_DELIMITER = "---";
+const FRONTMATTER_PATTERN = /^---\n([\s\S]*?)\n---(\n|$)/;
+const IGNORED_FILE_NAMES = new Set([
+	".DS_Store",
+	"Thumbs.db",
+	"desktop.ini"
+]);
+/**
+* The exact block `renderMetadataBlock` writes. Reading, verifying, and
+* stripping all go through this one pattern so writer and reader cannot drift.
+*/
+const METADATA_BLOCK_PATTERN = new RegExp(`^metadata:\\n {2}source: "${PACKAGE_NAME$1}"\\n {2}version: "([^"\\n]*)"\\n {2}hash: "([^"\\n]*)"\\n`, "m");
+/**
+* Hashing strips every occurrence, not just the first: a skill whose body
+* documents the block would otherwise hash differently before and after
+* injection and read as locally modified forever.
+*/
+const METADATA_BLOCK_GLOBAL_PATTERN = new RegExp(METADATA_BLOCK_PATTERN.source, "gm");
+function assertDirectory(directoryPath, message) {
+	if (!existsSync(directoryPath) || !statSync(directoryPath).isDirectory()) throw new Error(message);
+}
+function assertDirectoryIfPresent(directoryPath, label) {
+	if (existsSync(directoryPath)) assertDirectory(directoryPath, `${label} exists but is not a directory.`);
+}
+function getPackageRoot() {
+	return fileURLToPath(new URL(PACKAGE_ROOT_FROM_CLI_MODULE, import.meta.url));
+}
+/**
+* Resolves the Hydrogen the app actually depends on, walking up parent
+* node_modules the way Node itself would. This finds hoisted installs in
+* monorepos, which a plain `<appRoot>/node_modules` lookup misses.
+*/
+function getInstalledPackageRoot(appRoot) {
+	const require = createRequire(join(appRoot, PACKAGE_JSON_FILE_NAME$1));
+	try {
+		return dirname(require.resolve(`${PACKAGE_NAME$1}/${PACKAGE_JSON_FILE_NAME$1}`));
+	} catch {
+		return;
+	}
+}
+function readPackageVersion(packageRoot) {
+	const packageJsonPath = join(packageRoot, PACKAGE_JSON_FILE_NAME$1);
+	const parsed = JSON.parse(readFileSync(packageJsonPath, "utf8"));
+	if (!isObjectRecord(parsed) || typeof parsed.version !== "string") throw new Error(`${packageJsonPath} must declare a string version.`);
+	return parsed.version;
+}
+/**
+* Every harness dir is written unconditionally: Claude Code reads `.claude/skills`,
+* while Codex, Cursor, and OpenCode read `.agents/skills`. Writing both means no
+* project has to declare which agents it uses.
+*/
+function getSkillsDestinationRoots(appRoot) {
+	return [CLAUDE_DIRECTORY_NAME, AGENTS_DIRECTORY_NAME].map((harnessDirectory) => {
+		const skillsDirectory = join(harnessDirectory, SKILLS_DIRECTORY_NAME);
+		assertDirectoryIfPresent(join(appRoot, harnessDirectory), harnessDirectory);
+		assertDirectoryIfPresent(join(appRoot, skillsDirectory), skillsDirectory);
+		return join(appRoot, skillsDirectory);
+	});
+}
+function listDirectoryNames(root) {
+	if (!existsSync(root)) return [];
+	return readdirSync(root, { withFileTypes: true }).filter((entry) => entry.isDirectory()).map((entry) => entry.name);
+}
+function listFilesRecursively(root) {
+	const files = [];
+	const visit = (directory) => {
+		for (const entry of readdirSync(directory, { withFileTypes: true })) {
+			if (IGNORED_FILE_NAMES.has(entry.name)) continue;
+			const entryPath = join(directory, entry.name);
+			if (entry.isDirectory()) visit(entryPath);
+			else files.push(entryPath);
+		}
+	};
+	visit(root);
+	return files.map((filePath) => relative(root, filePath).split(sep).join("/")).toSorted((left, right) => left < right ? -1 : left > right ? 1 : 0);
+}
+function readNormalizedText(filePath) {
+	return readFileSync(filePath, "utf8").replaceAll("\r\n", "\n");
+}
+function renderMetadataBlock(metadata) {
+	return [
+		"metadata:",
+		`  source: "${PACKAGE_NAME$1}"`,
+		`  version: "${metadata.version}"`,
+		`  hash: "${metadata.hash}"`,
+		""
+	].join("\n");
+}
+/**
+* Hashes every file in a skill directory. Line endings are normalized so a skill
+* checked out through git autocrlf still verifies against the hash written on
+* another platform. The injected metadata block is stripped from SKILL.md so a
+* synced copy hashes to the same value as its shipped source.
+*/
+function hashSkillDirectory(skillRoot) {
+	const hash = createHash(HASH_ALGORITHM);
+	for (const relativePath of listFilesRecursively(skillRoot)) {
+		let content = readNormalizedText(join(skillRoot, relativePath));
+		if (relativePath === SKILL_FILE_NAME) content = content.replaceAll(METADATA_BLOCK_GLOBAL_PATTERN, "");
+		hash.update(relativePath);
+		hash.update("\0");
+		hash.update(content);
+		hash.update("\0");
+	}
+	return `${HASH_ALGORITHM}:${hash.digest("hex")}`;
+}
+function readShippedSkill(sourceSkillsRoot, skillName, version) {
+	const sourceRoot = join(sourceSkillsRoot, skillName);
+	const skillFilePath = join(sourceRoot, SKILL_FILE_NAME);
+	if (!existsSync(skillFilePath)) throw new Error(`${skillFilePath} is missing.`);
+	const content = readNormalizedText(skillFilePath);
+	const frontmatterMatch = FRONTMATTER_PATTERN.exec(content);
+	if (!frontmatterMatch) throw new Error(`${skillFilePath} has no frontmatter to record Hydrogen metadata in.`);
+	const [fullMatch, frontmatter, terminator] = frontmatterMatch;
+	if (/^metadata:/m.test(frontmatter)) throw new Error(`${skillFilePath} already declares frontmatter metadata.`);
+	const metadata = {
+		version,
+		hash: hashSkillDirectory(sourceRoot)
+	};
+	return {
+		skillName,
+		sourceRoot,
+		metadata,
+		skillFile: [
+			FRONTMATTER_DELIMITER,
+			frontmatter,
+			renderMetadataBlock(metadata) + FRONTMATTER_DELIMITER
+		].join("\n") + terminator + content.slice(fullMatch.length)
+	};
+}
+function readDestinationState(skillRoot) {
+	if (!existsSync(skillRoot)) return { kind: "absent" };
+	const skillFilePath = join(skillRoot, SKILL_FILE_NAME);
+	if (!existsSync(skillFilePath)) return { kind: "partial" };
+	const frontmatter = FRONTMATTER_PATTERN.exec(readNormalizedText(skillFilePath))?.[1];
+	const metadataMatch = frontmatter === void 0 ? null : METADATA_BLOCK_PATTERN.exec(frontmatter + "\n");
+	if (!metadataMatch) return { kind: "unmanaged" };
+	const metadata = {
+		version: metadataMatch[1] ?? "",
+		hash: metadataMatch[2] ?? ""
+	};
+	return {
+		kind: "managed",
+		metadata,
+		modified: hashSkillDirectory(skillRoot) !== metadata.hash
+	};
+}
+/** Returns undefined when the destination is user content that must not be touched. */
+function decideShippedAction(state, shipped, force) {
+	switch (state.kind) {
+		case "absent": return "add";
+		case "partial": return "update";
+		case "unmanaged": return force ? "update" : void 0;
+		case "managed": {
+			const current = state.metadata.hash === shipped.hash && state.metadata.version === shipped.version;
+			if (!state.modified) return current ? "unchanged" : "update";
+			if (force) return "update";
+			return current ? "unchanged" : "skip";
+		}
+	}
+}
+/** Returns undefined when the stale directory is user content that must not be touched. */
+function decideStaleAction(state, force) {
+	if (state.kind !== "managed") return void 0;
+	return !state.modified || force ? "remove" : "orphan";
+}
+function planDestination(destinationRoot, shippedSkills, force) {
+	const planned = [];
+	const conflicts = [];
+	const orphans = [];
+	for (const [skillName, shipped] of shippedSkills) {
+		const skillRoot = join(destinationRoot, skillName);
+		const action = decideShippedAction(readDestinationState(skillRoot), shipped.metadata, force);
+		if (!action) conflicts.push(skillRoot);
+		else if (action === "add" || action === "update") planned.push({
+			action,
+			skillName,
+			destinationRoot,
+			shipped
+		});
+		else planned.push({
+			action,
+			skillName,
+			destinationRoot
+		});
+	}
+	for (const skillName of listDirectoryNames(destinationRoot)) {
+		if (shippedSkills.has(skillName)) continue;
+		if (skillName.endsWith(STAGING_SUFFIX)) {
+			planned.push({
+				action: "remove",
+				skillName,
+				destinationRoot
+			});
+			continue;
+		}
+		const action = decideStaleAction(readDestinationState(join(destinationRoot, skillName)), force);
+		if (action === "orphan") orphans.push(skillName);
+		else if (action) planned.push({
+			action,
+			skillName,
+			destinationRoot
+		});
+	}
+	return {
+		destinationRoot,
+		planned,
+		conflicts,
+		orphans
+	};
+}
+/**
+* Asks once per skill name rather than once per harness directory, since both
+* copies came from the same shipped skill and the answer applies to both.
+*/
+async function planOrphans(plans, version, confirm) {
+	const orphanNames = new Set(plans.flatMap((plan) => plan.orphans));
+	for (const skillName of orphanNames) {
+		const action = await confirm(`Skill ${skillName} was edited locally and Hydrogen ${version} no longer ships it. Remove it?`) ? "remove" : "keep";
+		for (const plan of plans) if (plan.orphans.includes(skillName)) plan.planned.push({
+			action,
+			skillName,
+			destinationRoot: plan.destinationRoot
+		});
+	}
+}
+/** Never removes user edits without an answer, so no TTY means keep. */
+function confirmByDefault(question) {
+	return canPromptInTerminal() ? confirmInTerminal(question) : Promise.resolve(false);
+}
+/**
+* Stages the full copy next to the destination and swaps it in last, so an
+* interrupted run never leaves a half-written skill that a later sync would
+* mistake for user content.
+*/
+function installSkill(destinationRoot, skillRoot, shipped) {
+	const stagingRoot = skillRoot + STAGING_SUFFIX;
+	mkdirSync(destinationRoot, { recursive: true });
+	rmSync(stagingRoot, {
+		recursive: true,
+		force: true
+	});
+	cpSync(shipped.sourceRoot, stagingRoot, { recursive: true });
+	writeFileSync(join(stagingRoot, SKILL_FILE_NAME), shipped.skillFile);
+	rmSync(skillRoot, {
+		recursive: true,
+		force: true
+	});
+	renameSync(stagingRoot, skillRoot);
+}
+function executePlan(destinationRoot, planned) {
+	const result = {
+		root: destinationRoot,
+		added: 0,
+		updated: 0,
+		unchanged: 0,
+		removed: 0,
+		skipped: [],
+		kept: []
+	};
+	for (const skill of planned) {
+		const skillRoot = join(destinationRoot, skill.skillName);
+		switch (skill.action) {
+			case "skip":
+				result.skipped.push(skillRoot);
+				break;
+			case "keep":
+				result.kept.push(skillRoot);
+				break;
+			case "unchanged":
+				result.unchanged += 1;
+				break;
+			case "remove":
+				rmSync(skillRoot, {
+					recursive: true,
+					force: true
+				});
+				result.removed += 1;
+				break;
+			case "add":
+				installSkill(destinationRoot, skillRoot, skill.shipped);
+				result.added += 1;
+				break;
+			case "update":
+				installSkill(destinationRoot, skillRoot, skill.shipped);
+				result.updated += 1;
+				break;
+		}
+	}
+	return result;
+}
+function parseSkillsSyncArgs(args) {
+	const { values } = parseArgs({
+		args,
+		options: { force: {
+			type: "boolean",
+			default: false
+		} },
+		strict: true
+	});
+	return { force: values.force };
+}
+function planSkillsSync(appRoot, packageRoot, force) {
+	const resolvedPackageRoot = packageRoot ?? getInstalledPackageRoot(appRoot) ?? getPackageRoot();
+	const sourceSkillsRoot = join(resolvedPackageRoot, SKILLS_DIRECTORY_NAME);
+	assertDirectory(sourceSkillsRoot, `No packaged skills found at ${sourceSkillsRoot}.`);
+	const version = readPackageVersion(resolvedPackageRoot);
+	const shippedSkills = new Map(listDirectoryNames(sourceSkillsRoot).map((skillName) => [skillName, readShippedSkill(sourceSkillsRoot, skillName, version)]));
+	return {
+		version,
+		destinations: getSkillsDestinationRoots(appRoot).map((destinationRoot) => planDestination(destinationRoot, shippedSkills, force))
+	};
+}
+/** Reports what a sync would change without touching the filesystem. */
+function getSkillsSyncStatus(options = {}) {
+	const plan = planSkillsSync(options.cwd ?? process.cwd(), options.packageRoot, false);
+	const names = {
+		add: /* @__PURE__ */ new Set(),
+		update: /* @__PURE__ */ new Set(),
+		remove: /* @__PURE__ */ new Set(),
+		modified: /* @__PURE__ */ new Set()
+	};
+	for (const destination of plan.destinations) {
+		for (const skill of destination.planned) if (skill.action === "add" || skill.action === "update" || skill.action === "remove") names[skill.action].add(skill.skillName);
+		else if (skill.action === "skip") names.modified.add(skill.skillName);
+		for (const skillName of destination.orphans) names.modified.add(skillName);
+	}
+	return {
+		version: plan.version,
+		pending: {
+			add: names.add.size,
+			update: names.update.size,
+			remove: names.remove.size,
+			modified: names.modified.size
+		},
+		conflicts: plan.destinations.flatMap((destination) => destination.conflicts)
+	};
+}
+const SYNC_COMMAND = "npx @shopify/hydrogen skills sync";
+/** A plain sync clears everything except local edits, which only `--force` resets. */
+function describeNextStep(pending) {
+	const syncClears = pending.add + pending.update + pending.remove > 0;
+	if (pending.modified === 0) return `Run \`${SYNC_COMMAND}\`.`;
+	if (!syncClears) return `Run \`${SYNC_COMMAND} --force\` to reset them.`;
+	return `Run \`${SYNC_COMMAND}\`, or \`${SYNC_COMMAND} --force\` to also reset the locally modified ones.`;
+}
+/** Explains why a status is not up to date, or returns undefined when nothing needs doing. */
+function describeSkillsSyncStatus(status) {
+	if (status.conflicts.length > 0) return `Hydrogen skills cannot be synced: ${status.conflicts.join(", ")} were not created by Hydrogen. Remove them or run \`${SYNC_COMMAND} --force\`.`;
+	const { pending } = status;
+	const parts = [
+		pending.update > 0 && `${pending.update} to update`,
+		pending.add > 0 && `${pending.add} new`,
+		pending.remove > 0 && `${pending.remove} removed upstream`,
+		pending.modified > 0 && `${pending.modified} locally modified`
+	].filter((part) => typeof part === "string");
+	if (parts.length === 0) return void 0;
+	return `Hydrogen skills are out of date with @shopify/hydrogen ${status.version} (${parts.join(", ")}). ${describeNextStep(pending)}`;
+}
+const CHECK_MODES = ["error", "warn"];
+function isCheckSkillsMode(value) {
+	return CHECK_MODES.some((mode) => mode === value);
+}
+function parseSkillsCheckArgs(args) {
+	const { values } = parseArgs({
+		args,
+		options: { mode: {
+			type: "string",
+			default: "error"
+		} },
+		strict: true
+	});
+	if (!isCheckSkillsMode(values.mode)) throw new Error(`Unknown --mode '${values.mode}'. Expected one of: ${CHECK_MODES.join(", ")}.`);
+	return { mode: values.mode };
+}
+/**
+* Reports whether the synced skills match the installed package without writing.
+* A project with no synced skills counts as drift; running this command is the opt-in.
+*/
+function checkSkills(options = {}) {
+	const mode = options.mode ?? "error";
+	const log = options.log ?? console.log;
+	const warn = options.warn ?? console.warn;
+	const status = getSkillsSyncStatus(options);
+	const problem = describeSkillsSyncStatus(status);
+	if (problem) {
+		if (mode === "error") throw new Error(problem);
+		warn(problem);
+		return;
+	}
+	if (mode === "error") log(`Hydrogen skills are up to date with @shopify/hydrogen ${status.version}.`);
+}
+async function syncSkills(options = {}) {
+	const log = options.log ?? console.log;
+	const confirm = options.confirm ?? confirmByDefault;
+	const plan = planSkillsSync(options.cwd ?? process.cwd(), options.packageRoot, options.force ?? false);
+	const conflicts = plan.destinations.flatMap((destination) => destination.conflicts);
+	if (conflicts.length > 0) throw new Error(`Skill directories exist that Hydrogen did not create: ${conflicts.join(", ")}. Remove them or rerun with --force to overwrite.`);
+	await planOrphans(plan.destinations, plan.version, confirm);
+	const roots = plan.destinations.map((destination) => executePlan(destination.destinationRoot, destination.planned));
+	for (const root of roots) log(`Synced Hydrogen ${plan.version} skills to ${root.root}: ${root.added} added, ${root.updated} updated, ${root.unchanged} unchanged, ${root.removed} removed.`);
+	const skipped = roots.flatMap((root) => root.skipped);
+	if (skipped.length > 0) log(`Skipped ${skipped.length} locally modified skill(s): ${skipped.join(", ")}. Rerun with --force to overwrite.`);
+	const kept = roots.flatMap((root) => root.kept);
+	if (kept.length > 0) log([
+		"",
+		`WARNING: Hydrogen ${plan.version} no longer ships these skills, but they were edited locally so they were kept:`,
+		...kept.map((skillRoot) => `  - ${skillRoot}`),
+		"Delete them yourself, or rerun with --force to remove them.",
+		""
+	].join("\n"));
+	return {
+		version: plan.version,
+		roots
+	};
+}
+
+//#endregion
+//#region src/cli/setup.ts
+const PACKAGE_NAME = "@shopify/hydrogen";
+const PACKAGE_INSTALL_SPEC = `${PACKAGE_NAME}@preview`;
 const PACKAGE_JSON_FILE_NAME = "package.json";
 const SUCCESS_EXIT_CODE = 0;
 const PACKAGE_MANAGER_LOCKFILES = [
@@ -492,13 +934,14 @@ function parsePackageManager(value) {
 		if (value.startsWith(`${packageManager}/`)) return packageManager;
 	}
 }
+function detectPackageManagerFromEnv(env) {
+	return parsePackageManager(env.npm_config_user_agent);
+}
 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.");
+	return detectPackageManagerFromEnv(env) ?? "npm";
 }
 function hasHydrogenDependency(packageJson) {
 	return Boolean(packageJson.dependencies?.[PACKAGE_NAME] ?? packageJson.devDependencies?.[PACKAGE_NAME]);
@@ -506,70 +949,6 @@ function hasHydrogenDependency(packageJson) {
 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, {
@@ -586,19 +965,121 @@ function spawnRunCommand(command, args, options) {
 		});
 	});
 }
-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 TEMPLATE_TARBALL_URL = "https://codeload.github.com/Shopify/hydrogen/tar.gz/dist-preview";
+const TEMPLATE_TARBALL_PREFIX = "hydrogen-dist-preview/templates/react-router/";
+const TEMPLATE_TARBALL_STRIP_COMPONENTS = TEMPLATE_TARBALL_PREFIX.split("/").filter(Boolean).length;
+async function promptSetupChoice(log) {
+	log("\nNo project found in this directory.\n");
+	log("  1) Create a new Hydrogen storefront (React Router)");
+	log("  2) Just install Hydrogen skills\n");
+	const readline = createInterface({
+		input: process.stdin,
+		output: process.stdout
+	});
+	try {
+		while (true) {
+			const answer = (await readline.question("Your choice [1] ")).trim();
+			if (answer === "" || answer === "1") return "scaffold";
+			if (answer === "2") return "skills";
+			log("Please enter \"1\" or \"2\".");
+		}
+	} finally {
+		readline.close();
+	}
+}
+function hasPackageJson(appRoot) {
+	return existsSync(join(appRoot, PACKAGE_JSON_FILE_NAME));
+}
+async function downloadAndExtractTemplate(appRoot, runCommand) {
+	const response = await fetch(TEMPLATE_TARBALL_URL, { signal: AbortSignal.timeout(3e4) });
+	if (!response.ok) throw new Error(`Failed to download template (${response.status}). Check your internet connection.`);
+	const tempDir = mkdtempSync(join(tmpdir(), "hydrogen-template-"));
+	const tempFile = "template.tar.gz";
+	try {
+		writeFileSync(join(tempDir, tempFile), Buffer.from(await response.arrayBuffer()));
+		await runCommand("tar", [
+			"xzf",
+			tempFile,
+			`--strip-components=${TEMPLATE_TARBALL_STRIP_COMPONENTS}`,
+			"-C",
+			appRoot,
+			TEMPLATE_TARBALL_PREFIX
+		], { cwd: tempDir });
+	} finally {
+		rmSync(tempDir, {
+			recursive: true,
+			force: true
+		});
+	}
+}
+function updateScaffoldedPackageJson(appRoot) {
+	const packageJsonPath = join(appRoot, PACKAGE_JSON_FILE_NAME);
+	const raw = readFileSync(packageJsonPath, "utf8");
+	const parsed = JSON.parse(raw);
+	if (!isObjectRecord(parsed)) return;
+	parsed.name = basename(appRoot);
+	delete parsed.private;
+	delete parsed.packageManager;
+	writeFileSync(packageJsonPath, JSON.stringify(parsed, null, 2) + "\n");
+}
+async function scaffoldTemplate(appRoot, env, runCommand, log) {
+	log("Downloading Hydrogen template...");
+	await downloadAndExtractTemplate(appRoot, runCommand);
+	updateScaffoldedPackageJson(appRoot);
+	const packageManager = detectPackageManagerFromEnv(env) ?? "npm";
+	log(`Installing dependencies with ${packageManager}...`);
+	try {
+		await runCommand(packageManager, ["install"], { cwd: appRoot });
+	} catch (error) {
+		throw new Error(`Template was created but dependency install failed. Run \`${packageManager} install\` or re-run \`npx @shopify/hydrogen setup\` in ${appRoot} to finish.`, { cause: error });
+	}
+	return packageManager;
+}
+async function ensureHydrogenInstalled(appRoot, env, runCommand, log) {
 	const packageJson = readPackageJson(appRoot);
-	if (!hasHydrogenDependency(packageJson)) {
+	if (hasHydrogenDependency(packageJson) && getInstalledPackageRoot(appRoot)) return;
+	if (hasHydrogenDependency(packageJson)) {
 		const packageManager = detectPackageManager(appRoot, packageJson, env);
-		log(`Installing ${PACKAGE_NAME} with ${packageManager}...`);
-		await installHydrogen(appRoot, packageManager, runCommand);
+		log(`${PACKAGE_NAME} is declared but not installed. Running ${packageManager} install...`);
+		await runCommand(packageManager, ["install"], { cwd: appRoot });
+		return;
 	}
-	const result = copySkills(options.packageRoot ?? getLocalPackageRoot(appRoot) ?? getPackageRoot(), appRoot);
-	log(`Copied ${result.copiedCount} Hydrogen skills to ${result.destinationRoots.join(", ")}.`);
+	const packageManager = detectPackageManager(appRoot, packageJson, env);
+	log(`Installing ${PACKAGE_NAME} with ${packageManager}...`);
+	await installHydrogen(appRoot, packageManager, runCommand);
+}
+function resolveSetupOptions(options) {
+	const env = options.env ?? process.env;
+	return {
+		appRoot: options.cwd ?? process.cwd(),
+		env,
+		runCommand: options.runCommand ?? spawnRunCommand,
+		log: options.log ?? console.log,
+		prompt: options.prompt ?? (canPromptInTerminal(env) ? promptSetupChoice : void 0)
+	};
+}
+const IGNORED_DIRECTORY_ENTRIES = new Set([".git", ".DS_Store"]);
+function isEmptyDirectory(dir) {
+	return readdirSync(dir).every((entry) => IGNORED_DIRECTORY_ENTRIES.has(entry));
+}
+async function setupHydrogen(options = {}) {
+	const { appRoot, env, runCommand, log, prompt } = resolveSetupOptions(options);
+	if (hasPackageJson(appRoot)) await ensureHydrogenInstalled(appRoot, env, runCommand, log);
+	else if (isEmptyDirectory(appRoot)) {
+		let choice;
+		if (prompt) choice = await prompt(log);
+		else {
+			log("No package.json found and no terminal to prompt; installing skills only.");
+			choice = "skills";
+		}
+		if (choice === "scaffold") log(`\nHydrogen storefront created. Run \`${await scaffoldTemplate(appRoot, env, runCommand, log)} run dev\` to start (uses mock.shop by default).\n`);
+	} else throw new Error("No package.json found. Run this command from your project root.");
+	await syncSkills({
+		force: options.force,
+		cwd: appRoot,
+		packageRoot: options.packageRoot,
+		log
+	});
 }
 
 //#endregion
@@ -616,7 +1097,19 @@ const COMMANDS = [
 	},
 	{
 		path: ["setup"],
-		run: async (_args) => setupHydrogen()
+		run: async (args) => setupHydrogen(parseSkillsSyncArgs(args))
+	},
+	{
+		path: ["skills", "check"],
+		run: async (args) => {
+			checkSkills(parseSkillsCheckArgs(args));
+		}
+	},
+	{
+		path: ["skills", "sync"],
+		run: async (args) => {
+			await syncSkills(parseSkillsSyncArgs(args));
+		}
 	},
 	{
 		path: ["gql", "check"],