@fluid-app/fluid-cli-theme-dev 0.1.46 → 0.1.48

package/dist/index.mjs

@@ -6,12 +6,12 @@ import { createHash, randomBytes } from "node:crypto";
 import http from "node:http";
 import https from "node:https";
 import chokidar from "chokidar";
+import { execFileSync, spawn } from "node:child_process";
+import { tmpdir } from "node:os";
 import net from "node:net";
 import chalk from "chalk";
 import prompts from "prompts";
 import ora from "ora";
-import { execFileSync, spawn } from "node:child_process";
-import { tmpdir } from "node:os";
 import { fileURLToPath } from "node:url";
 //#region ../../platform/api-client-core/src/api-error-shape.ts
 /**
@@ -1487,6 +1487,15 @@ var ThemeAssetManifest = class {
 	entries() {
 		return Object.entries(this.assets).map(([key, link]) => [key, copyLink(link)]);
 	}
+	/**
+	* Stable digest of the URL references represented by this manifest.
+	* Pull baselines exclude pending entries because those belong only to an
+	* existing dev target and are deliberately absent from the pulled source.
+	*/
+	fingerprint(opts = {}) {
+		const entries = this.entries().filter(([, link]) => !opts.excludePending || !link.pending).toSorted(([left], [right]) => left < right ? -1 : left > right ? 1 : 0);
+		return createHash("sha256").update(JSON.stringify(entries)).digest("hex");
+	}
 	has(key) {
 		return this.assets[key] !== void 0;
 	}
@@ -2117,7 +2126,7 @@ var Syncer = class {
 			const response = await deleteThemeResource(this.api, this.themeId, body);
 			if (response.content_version_sha) this.lastKnownRemoteSha = response.content_version_sha;
 		} catch (e) {
-			throw this.rethrowIfConflict(e);
+			if (!isNotFoundError(e)) throw this.rethrowIfConflict(e);
 		}
 		this.removeRemoteResource(relativePath);
 	}
@@ -2279,8 +2288,8 @@ var Syncer = class {
 				return result;
 			}
 		}
-		await this.fetchChecksums();
-		await this.preflightPush(opts.baseSha);
+		if (!opts.diff) await this.fetchChecksums();
+		if (!opts.skipPreflight) await this.preflightPush(opts.baseSha);
 		let baseSha = opts.baseSha ?? null;
 		if (opts.linkManagedAssets) {
 			result.linked = await this.linkManagedAssets(opts.linkManagedAssets);
@@ -2289,7 +2298,7 @@ var Syncer = class {
 			this.assetManifest.reload();
 			this.ensureManagedAssetsAreResolved();
 		}
-		const toUpload = localFiles.filter((f) => f.exists && this.hasChanged(f));
+		const toUpload = opts.diff?.changed ?? localFiles.filter((f) => f.exists && this.hasChanged(f));
 		let done = 0;
 		for (const file of toUpload) {
 			try {
@@ -2303,9 +2312,11 @@ var Syncer = class {
 			opts.onProgress?.(++done, toUpload.length);
 		}
 		if (opts.delete) {
-			const localPaths = new Set(localFiles.map((f) => f.relativePath));
-			for (const key of this.assetManifest.keys()) localPaths.add(key);
-			const toDelete = this.remoteKeys().filter((key) => !localPaths.has(key) && !this.themeRoot.ignore.ignore(key));
+			const toDelete = opts.diff?.deleted ?? (() => {
+				const localPaths = new Set(localFiles.map((f) => f.relativePath));
+				for (const key of this.assetManifest.keys()) localPaths.add(key);
+				return this.remoteKeys().filter((key) => !localPaths.has(key) && !this.themeRoot.ignore.ignore(key));
+			})();
 			for (const key of toDelete) try {
 				await this.deleteRemoteFile(key, baseSha);
 				baseSha = this.lastKnownRemoteSha;
@@ -2459,1076 +2470,1158 @@ function isRecord(value) {
 	return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 //#endregion
-//#region src/theme/liquid-delimiters.ts
+//#region src/theme/shadow-repo.ts
 /**
-* Heuristic-only check for obviously unbalanced liquid delimiters
-* (`{% %}` and `{{ }}`). This is NOT a liquid parser — it only tracks
-* opening delimiters until they are closed. It exists to give watch-mode users a signal
-* when a save is liquid-syntax-broken: the server accepts
-* syntax-broken liquid silently on upload, and the storefront
-* renderer then serves stale content for that section with no error
-* anywhere else in the pipeline.
+* A bare git repo hidden under `.fluid-theme/repo` that stands in for
+* git's index+HEAD when talking to the Fluid server. Every pull commits
+* the incoming remote state onto a single branch (`refs/heads/main`);
+* every successful push commits the outgoing local state onto the same
+* branch. HEAD therefore represents "the last state the CLI and server
+* agreed on", and its tree is the natural three-way-merge base for the
+* next pull.
 *
-* Closing-looking tokens without a preceding Liquid opener are intentionally
-* ignored. Liquid files commonly contain CSS such as `width:100%}` or adjacent
-* block braces (`}}`), so treating every close token as Liquid creates noisy
-* false warnings on valid theme files.
+* We stay in git's plumbing layer — no working tree, no index file
+* next to the theme content — so the shadow repo cannot interfere
+* with the user's own git repo (if they have one) around the theme
+* dir. All state lives inside `.fluid-theme/`.
 *
-* Known false positive: delimiters written literally inside a
-* `{% raw %}...{% endraw %}` block are still counted and can trip
-* this check even though the liquid is valid. Acceptable for a
-* warn-only heuristic — a real fix requires parsing liquid, which is
-* out of scope here (see the server-side validation note in the PR).
+* The class only wraps the small handful of plumbing commands we
+* actually need: hash-object, cat-file, write-tree (via a temp index),
+* commit-tree, update-ref, and merge-file. Everything else stays out.
 */
-function hasUnbalancedLiquidDelimiters(content) {
-	let unclosedTags = 0;
-	let unclosedOutputs = 0;
-	for (const token of content.matchAll(/\{%|%\}|\{\{|\}\}/g)) switch (token[0]) {
-		case "{%":
-			unclosedTags += 1;
-			break;
-		case "%}":
-			if (unclosedTags > 0) unclosedTags -= 1;
-			break;
-		case "{{":
-			unclosedOutputs += 1;
-			break;
-		case "}}":
-			if (unclosedOutputs > 0) unclosedOutputs -= 1;
-			break;
+var ShadowRepo = class ShadowRepo {
+	headExists = void 0;
+	constructor(themeRoot, gitDir) {
+		this.themeRoot = themeRoot;
+		this.gitDir = gitDir;
 	}
-	return unclosedTags > 0 || unclosedOutputs > 0;
-}
-const BLOCK_TAGS = new Map([
-	["capture", "endcapture"],
-	["case", "endcase"],
-	["comment", "endcomment"],
-	["for", "endfor"],
-	["form", "endform"],
-	["if", "endif"],
-	["ifchanged", "endifchanged"],
-	["javascript", "endjavascript"],
-	["paginate", "endpaginate"],
-	["raw", "endraw"],
-	["schema", "endschema"],
-	["style", "endstyle"],
-	["stylesheet", "endstylesheet"],
-	["tablerow", "endtablerow"],
-	["unless", "endunless"]
-]);
-const CLOSING_TAGS = new Set(BLOCK_TAGS.values());
-const OPAQUE_BLOCK_TAGS = new Set([
-	"comment",
-	"javascript",
-	"raw",
-	"schema",
-	"style",
-	"stylesheet"
-]);
-/**
-* Find structurally unbalanced Liquid block tags such as an `{% if %}` with
-* no `{% endif %}`. This intentionally recognizes only established paired
-* tags; custom and inline tags are ignored rather than guessed at.
-*
-* Content inside raw/comment/schema/style/javascript blocks is opaque to
-* Liquid and therefore skipped until that block's matching close tag. This
-* prevents CSS, JSON, and examples containing Liquid-looking text from
-* producing false errors.
-*/
-function findLiquidBlockTagDiagnostics(content) {
-	const stack = [];
-	const diagnostics = [];
-	let line = 1;
-	let previousTagIndex = 0;
-	const processTag = (name, tagLine) => {
-		const open = stack.at(-1);
-		if (open && OPAQUE_BLOCK_TAGS.has(open.name)) {
-			if (name === open.expectedClose) stack.pop();
-			return;
-		}
-		const expectedClose = BLOCK_TAGS.get(name);
-		if (expectedClose) {
-			stack.push({
-				name,
-				expectedClose,
-				line: tagLine
+	/**
+	* Return a ShadowRepo bound to `themeId` for the given theme root.
+	* The shadow is initialized on first use and re-initialized when
+	* the caller passes a themeId different from the one previously
+	* recorded — the merge base is only meaningful for the theme it
+	* was captured against, so a cross-theme operation (pull A → push
+	* B, or two pulls of different themes into one dir) starts from a
+	* clean slate rather than pretending B's state matches A's HEAD.
+	*/
+	static async open(themeRoot, themeId) {
+		const shadowDir = join(themeRoot, ".fluid-theme");
+		const gitDir = join(shadowDir, "repo");
+		const themeIdFile = join(shadowDir, "theme-id");
+		if (existsSync(gitDir)) {
+			if (readStoredThemeId(themeIdFile) !== themeId) rmSync(gitDir, {
+				recursive: true,
+				force: true
 			});
-			return;
 		}
-		if (!CLOSING_TAGS.has(name)) return;
-		if (!open) {
-			diagnostics.push({
-				severity: "error",
-				message: `Unexpected Liquid tag '{% ${name} %}' on line ${tagLine}; there is no open block to close.`
-			});
-			return;
+		const repo = new ShadowRepo(themeRoot, gitDir);
+		if (!existsSync(gitDir)) {
+			mkdirSync(shadowDir, { recursive: true });
+			await repo.git([
+				"init",
+				"--bare",
+				"-b",
+				"main",
+				gitDir
+			], { cwd: themeRoot });
 		}
-		if (name !== open.expectedClose) {
-			diagnostics.push({
-				severity: "error",
-				message: `Mismatched Liquid tag '{% ${name} %}' on line ${tagLine}; '{% ${open.name} %}' from line ${open.line} must close with '{% ${open.expectedClose} %}'.`
-			});
-			return;
+		writeFileSync(themeIdFile, `${themeId}\n`, "utf-8");
+		const shadowIgnore = join(shadowDir, ".gitignore");
+		if (!existsSync(shadowIgnore)) writeFileSync(shadowIgnore, "# Fluid CLI shadow repo — internal state, not for version control.\n*\n");
+		await ensureRootGitignoreHidesShadow(themeRoot);
+		return repo;
+	}
+	/** True when the repo has at least one commit on `refs/heads/main`. */
+	async hasHead() {
+		if (this.headExists !== void 0) return this.headExists;
+		try {
+			await this.git([
+				"rev-parse",
+				"--verify",
+				"HEAD"
+			]);
+			this.headExists = true;
+		} catch {
+			this.headExists = false;
 		}
-		stack.pop();
-	};
-	for (const match of content.matchAll(/\{%-?\s*([a-zA-Z_][\w-]*)\b(?:(?!\{%)[\s\S])*?-?%\}/g)) {
-		const name = match[1]?.toLowerCase();
-		if (!name) continue;
-		const index = match.index ?? 0;
-		for (let cursor = previousTagIndex; cursor < index; cursor++) if (content.charCodeAt(cursor) === 10) line += 1;
-		previousTagIndex = index;
-		const open = stack.at(-1);
-		if (name === "liquid" && !(open && OPAQUE_BLOCK_TAGS.has(open.name))) {
-			const statements = match[0].replace(/^\{%-?\s*liquid\b/i, "").replace(/-?%\}$/, "").split("\n");
-			for (const [offset, statement] of statements.entries()) {
-				const statementName = /^\s*([a-zA-Z_][\w-]*)\b/.exec(statement)?.[1];
-				if (!statementName) continue;
-				processTag(statementName.toLowerCase(), line + offset);
-			}
-		} else processTag(name, line);
+		return this.headExists;
 	}
-	for (const open of stack.reverse()) diagnostics.push({
-		severity: "error",
-		message: `Unclosed Liquid tag '{% ${open.name} %}' on line ${open.line}; expected '{% ${open.expectedClose} %}'.`
-	});
-	return diagnostics;
-}
-//#endregion
-//#region src/theme/dev-server/port-preflight.ts
-/**
-* The dev command does real work before it ever binds a port: it resolves
-* (or creates) a server-side dev theme and runs a full initial sync, which
-* can take minutes on a large theme. If the requested port is already taken
-* — most commonly by another `fluid theme dev` or the Mist Desktop preview,
-* which both default to 9292 — all of that work is wasted and the process
-* used to die with a raw `EADDRINUSE` stack trace. Call this before any of
-* that work starts so we fail fast with a clear message instead.
-*/
-var PortInUseError = class extends Error {
-	constructor(host, port) {
-		super(formatPortConflictMessage(host, port));
-		this.host = host;
-		this.port = port;
-		this.name = "PortInUseError";
+	/**
+	* Every path recorded under HEAD's tree, recursively. Callers use
+	* this to detect local deletions (paths in HEAD, absent from the
+	* working tree). Returns [] when HEAD has never been committed.
+	*/
+	async headPaths() {
+		if (!await this.hasHead()) return [];
+		const { stdout } = await this.git([
+			"ls-tree",
+			"-r",
+			"-z",
+			"HEAD",
+			"--name-only"
+		]);
+		return stdout.toString("utf8").split("\0").filter((line) => line.length > 0);
 	}
-};
-function formatPortConflictMessage(host, port) {
-	return `Port ${port} on ${host} is already in use — likely another \`fluid theme dev\` or the Mist Desktop preview. Stop the other server or pass --port <number>.`;
-}
-/**
-* Attempt to bind `host:port`, then immediately release it. Resolves if the
-* port is free; rejects with `PortInUseError` on `EADDRINUSE`/`EACCES`, or
-* the raw error for anything else unexpected.
-*/
-function checkPortAvailable(host, port) {
-	return new Promise((resolve, reject) => {
-		const server = net.createServer();
-		server.once("error", (err) => {
-			if (err.code === "EADDRINUSE" || err.code === "EACCES") reject(new PortInUseError(host, port));
-			else reject(err);
-		});
-		server.once("listening", () => {
-			server.close(() => resolve());
-		});
-		server.listen(port, host);
-	});
-}
-//#endregion
-//#region src/theme/dev-server/index.ts
-function timestamp() {
-	return (/* @__PURE__ */ new Date()).toLocaleTimeString("en-US", { hour12: false });
-}
-async function startDevServer(api, theme, themeRoot, opts, onReady) {
-	const sse = new SSEStream();
-	const syncer = new Syncer(api, theme.id, themeRoot);
-	const pendingUpdates = /* @__PURE__ */ new Set();
-	console.log(`\nSyncing theme ${theme.name} (#${theme.id})…`);
-	const syncResult = await syncer.uploadTheme({
-		delete: true,
-		validate: opts.validate,
-		linkManagedAssets: { replace: true },
-		pendingBinaryAssets: true,
-		onProgress: (done, total) => {
-			process.stdout.write(`\r  Uploading ${done}/${total} files…`);
+	/**
+	* The content of `path` in HEAD's tree, or null when the path does
+	* not exist there. Callers use this as the merge base for pull
+	* conflict resolution.
+	*/
+	async blobAtHead(path) {
+		if (!await this.hasHead()) return null;
+		try {
+			const { stdout } = await this.git([
+				"cat-file",
+				"-p",
+				`HEAD:${path}`
+			]);
+			return stdout;
+		} catch {
+			return null;
 		}
-	});
-	process.stdout.write("\n");
-	if (syncResult.linked > 0) console.log(`  Saved ${syncResult.linked} remote asset reference(s).`);
-	if (syncResult.validationFailed) {
-		console.error(`\nSchema validation failed (${syncResult.errors.length} error(s)). Use --force to skip.\n`);
-		for (const e of syncResult.errors) console.error(`  ${e}`);
-		process.exit(1);
-	} else if (syncResult.errors.length > 0) {
-		for (const e of syncResult.errors) console.error(`  ${e}`);
-		if (syncResult.uploaded + syncResult.deleted === 0) process.exit(1);
 	}
-	const SYNC_IDLE_MS = 2e3;
-	let lastArrivedAt = 0;
-	let pendingSync = null;
-	let syncInFlight = Promise.resolve();
-	let askOwed = false;
-	const sendSync = () => {
-		syncInFlight = syncInFlight.then(async () => {
-			askOwed = !await syncer.requestSync();
-		});
-	};
-	const flushSyncNow = () => {
-		if (!pendingSync) return;
-		clearTimeout(pendingSync);
-		pendingSync = null;
-		sendSync();
-	};
-	const scheduleSync = () => {
-		if (pendingSync) clearTimeout(pendingSync);
-		pendingSync = setTimeout(() => {
-			pendingSync = null;
-			sendSync();
-		}, SYNC_IDLE_MS);
-	};
-	const stopWatcher = watchTheme(themeRoot, async (modified, added, removed, arrivedAt) => {
-		if (arrivedAt - lastArrivedAt > SYNC_IDLE_MS) flushSyncNow();
-		else if (pendingSync) {
-			clearTimeout(pendingSync);
-			pendingSync = null;
-		}
-		lastArrivedAt = arrivedAt;
-		await syncInFlight;
-		if (askOwed) {
-			sendSync();
-			await syncInFlight;
-		}
-		const changed = [...modified, ...added];
-		for (const file of changed) {
-			if (opts.validate && file.isLiquid) {
-				const diagnostics = file.validateSchema();
-				for (const d of diagnostics) {
-					const prefix = d.severity === "error" ? "Schema error" : "Schema warning";
-					console.warn(`\n[${prefix}] ${file.relativePath}: ${d.message}`);
-				}
-			}
-			pendingUpdates.add(file.relativePath);
-			try {
-				const uploadedContent = await syncer.uploadFile(file, void 0, { pendingAsset: true });
-				console.log(`  ✓ synced ${file.relativePath} (${timestamp()})`);
-				if (file.isLiquid && uploadedContent !== null && hasUnbalancedLiquidDelimiters(uploadedContent)) console.warn(`  ⚠ ${file.relativePath}: unbalanced liquid delimiters — the storefront may silently serve stale content for this section`);
-				if (file.isLiquid && uploadedContent !== null) for (const diagnostic of findLiquidBlockTagDiagnostics(uploadedContent)) console.warn(`  ⚠ ${file.relativePath}: ${diagnostic.message}`);
-			} catch (e) {
-				console.error(`\n[Watcher] Upload failed: ${file.relativePath}: ${e}`);
-			} finally {
-				pendingUpdates.delete(file.relativePath);
-			}
-		}
-		for (const file of removed) {
-			if (themeRoot.ignore.ignore(file.relativePath)) continue;
+	/**
+	* Write `content` as a blob in the shadow repo and return its sha.
+	* Used by `commitState` to stage each file's content before the
+	* `write-tree` call.
+	*/
+	async writeBlob(content) {
+		const buf = typeof content === "string" ? Buffer.from(content) : content;
+		const { stdout } = await this.git([
+			"hash-object",
+			"-w",
+			"--stdin"
+		], { input: buf });
+		return stdout.toString("utf8").trim();
+	}
+	/**
+	* Commit `files` as HEAD's new tree, threaded onto the current HEAD
+	* as the parent. Uses a per-call temp index so a partial run can't
+	* corrupt anything reachable from HEAD; the previous commit stays
+	* intact until `update-ref` at the end.
+	*
+	* Returns the new commit sha.
+	*/
+	async commitState(files, message) {
+		const indexPath = mkdtempSync(join(tmpdir(), "fluid-shadow-")) + "/index";
+		try {
+			const indexArgs = ["update-index", "--add"];
+			for (const { path, sha } of files) indexArgs.push("--cacheinfo", `100644,${sha},${path}`);
+			if (files.length > 0) await this.git(indexArgs, { env: { GIT_INDEX_FILE: indexPath } });
+			const treeSha = (await this.git(["write-tree"], { env: { GIT_INDEX_FILE: indexPath } })).stdout.toString("utf8").trim();
+			const parent = await this.hasHead() ? (await this.git(["rev-parse", "HEAD"])).stdout.toString("utf8").trim() : null;
+			const commitArgs = [
+				"commit-tree",
+				treeSha,
+				"-m",
+				message
+			];
+			if (parent) commitArgs.push("-p", parent);
+			const commitSha = (await this.git(commitArgs, { env: {
+				GIT_AUTHOR_NAME: "Fluid CLI",
+				GIT_AUTHOR_EMAIL: "cli@fluid.app",
+				GIT_COMMITTER_NAME: "Fluid CLI",
+				GIT_COMMITTER_EMAIL: "cli@fluid.app"
+			} })).stdout.toString("utf8").trim();
+			await this.git([
+				"update-ref",
+				"refs/heads/main",
+				commitSha
+			]);
+			this.headExists = true;
+			return commitSha;
+		} finally {
 			try {
-				await syncer.deleteRemoteFile(file.relativePath);
-				console.log(`  ✓ removed ${file.relativePath}`);
+				rmSync(indexPath, { force: true });
+				rmSync(indexPath.substring(0, indexPath.length - 6), {
+					recursive: true,
+					force: true
+				});
 			} catch {}
 		}
-		if (removed.length > 0) sse.broadcast(JSON.stringify({ reload_page: true }));
-		else if (changed.length > 0) sse.broadcast(JSON.stringify({ modified: changed.map((f) => f.relativePath) }));
-		scheduleSync();
-	});
-	const server = http.createServer(async (req, res) => {
-		if (req.url === "/hot-reload") {
-			sse.add(res);
-			return;
-		}
+	}
+	/**
+	* Three-way merge of `local` against `remote` with `base` as the
+	* common ancestor. Returns the merged bytes and a flag when
+	* `git merge-file` reported unresolved conflicts (i.e. the output
+	* contains `<<<<<<<` markers for the reader to resolve).
+	*
+	* `base` is null when HEAD has never seen this path; we merge
+	* against an empty base, which is what git itself does for a new
+	* file added on both sides.
+	*
+	* `favor` maps to `git merge-file`'s `--ours` / `--theirs`: instead
+	* of emitting `<<<<<<<` markers, conflicting hunks are resolved to
+	* the local (`"local"` → `--ours`, local is file1) or remote
+	* (`"remote"` → `--theirs`) side. The output then never contains
+	* markers, so the result is reported conflict-free even when
+	* merge-file's exit code still counts the auto-resolved hunks.
+	*/
+	async merge3(base, local, remote, favor) {
+		const dir = mkdtempSync(join(tmpdir(), "fluid-merge-"));
+		const localPath = join(dir, "local");
+		const basePath = join(dir, "base");
+		const remotePath = join(dir, "remote");
 		try {
-			await proxyRequest(req, res, {
-				company: theme.company,
-				themeId: theme.id,
-				reloadMode: opts.reloadMode,
-				pendingFiles: () => [...pendingUpdates].map((p) => themeRoot.file(p)).filter((f) => f.isText).map((f) => ({
-					relativePath: f.relativePath,
-					read: () => f.read()
-				}))
-			});
-		} catch (e) {
-			console.error(`[Proxy] ${req.method} ${req.url} → ${e}`);
-			if (!res.headersSent) {
-				const message = e instanceof Error ? e.message : String(e);
-				res.writeHead(502, { "content-type": "text/plain; charset=utf-8" });
-				res.end(`Bad Gateway — the local preview could not reach ${theme.company}.fluid.app: ${message}\nThis is the dev machine's network path to Fluid, not the theme. Common causes: TLS-inspecting security software (its root CA is in the OS keychain, which Node does not read — set NODE_EXTRA_CA_CERTS to its certificate), DNS, or a proxy. The same error is logged by the theme dev server process.`);
+			writeFileSync(localPath, local);
+			writeFileSync(basePath, base ?? Buffer.alloc(0));
+			writeFileSync(remotePath, remote);
+			try {
+				const { stdout } = await this.git([
+					"merge-file",
+					"-p",
+					...favor === "local" ? ["--ours"] : favor === "remote" ? ["--theirs"] : [],
+					"-L",
+					"local",
+					"-L",
+					"base",
+					"-L",
+					"remote",
+					localPath,
+					basePath,
+					remotePath
+				]);
+				return {
+					merged: stdout,
+					hasConflicts: false
+				};
+			} catch (err) {
+				const e = err;
+				const merged = e.stdout instanceof Buffer ? e.stdout : e.stdout != null ? Buffer.from(e.stdout) : Buffer.alloc(0);
+				const inConflictRange = typeof e.code === "number" && e.code >= 1 && e.code <= 127;
+				if (inConflictRange && favor) return {
+					merged,
+					hasConflicts: false
+				};
+				if (inConflictRange && merged.length > 0) return {
+					merged,
+					hasConflicts: true
+				};
+				throw err;
 			}
+		} finally {
+			try {
+				rmSync(dir, {
+					recursive: true,
+					force: true
+				});
+			} catch {}
 		}
-	});
-	await new Promise((resolve, reject) => {
-		server.once("error", (err) => {
-			if (err.code === "EADDRINUSE" || err.code === "EACCES") {
-				console.error(formatPortConflictMessage(opts.host, opts.port));
-				process.exit(1);
-			}
-			reject(err);
-		});
-		server.listen(opts.port, opts.host, () => resolve());
-	});
-	const address = `http://${opts.host}:${opts.port}`;
-	onReady?.(address);
-	return function stop() {
-		sse.close();
-		stopWatcher();
-		server.close();
-	};
-}
-//#endregion
-//#region src/theme-picker.ts
-const PAGE_SIZE = 50;
-const LOAD_MORE_VALUE = -1;
-function themeLabel(t) {
-	const active = t.status === "active" ? ` ${chalk.green("[active]")}` : "";
-	return `${t.name} (#${t.id})${active}`;
-}
-function themeChoices(themeList, hasMore) {
-	const choices = themeList.map((t) => ({
-		title: themeLabel(t),
-		value: t.id
-	}));
-	if (hasMore) choices.push({
-		title: chalk.dim(`── Load more themes ──`),
-		value: LOAD_MORE_VALUE
-	});
-	return choices;
-}
-async function fetchThemesPage(api, page, searchQuery) {
-	const body = await listApplicationThemes(api, {
-		per_page: PAGE_SIZE,
-		page,
-		...searchQuery ? { search_query: searchQuery } : {}
-	});
-	return {
-		themes: body.application_themes ?? [],
-		hasMore: page < (body.meta?.total_pages ?? 1)
-	};
-}
-async function selectTheme(api, message) {
-	const allThemes = [];
-	let page = 1;
-	let hasMore = true;
-	let initialIndex = 0;
-	let searchQuery = "";
-	let searchResults = [];
-	while (true) {
-		if (hasMore && allThemes.length < page * PAGE_SIZE) {
-			const result = await fetchThemesPage(api, page);
-			allThemes.push(...result.themes);
-			hasMore = result.hasMore;
-		}
-		if (!allThemes.length) {
-			console.error("No themes found.");
-			process.exit(1);
-		}
-		const choices = themeChoices(allThemes, hasMore);
-		const { id } = await prompts({
-			type: "autocomplete",
-			name: "id",
-			message,
-			initial: initialIndex,
-			choices,
-			suggest: async (input, choices) => {
-				if (!input) {
-					searchQuery = "";
-					searchResults = [];
-					return choices;
-				}
-				if (input !== searchQuery) {
-					searchQuery = input;
-					try {
-						searchResults = (await fetchThemesPage(api, 1, input)).themes;
-					} catch {
-						searchResults = [];
-					}
+	}
+	/**
+	* Snapshot the working-tree copy of `paths` into HEAD as a single
+	* commit. Intended for the migration path: on the first pull with
+	* the new CLI (no shadow repo yet, but a `.fluid-theme.json` with
+	* checksums exists) we seed HEAD with whatever is on disk before
+	* running the merge, so unmodified files fast-forward cleanly and
+	* modified files show a diff.
+	*/
+	async seedFromWorkingTree(files, message) {
+		const entries = [];
+		for (const { path, content } of files) entries.push({
+			path,
+			sha: await this.writeBlob(content)
+		});
+		await this.commitState(entries, message);
+	}
+	async git(args, opts = {}) {
+		const child = spawn("git", args[0] === "init" ? args : [
+			"--git-dir",
+			this.gitDir,
+			...args
+		], {
+			cwd: opts.cwd ?? this.themeRoot,
+			env: {
+				...process.env,
+				...opts.env
+			},
+			stdio: [
+				"pipe",
+				"pipe",
+				"pipe"
+			]
+		});
+		if (opts.input) child.stdin.write(opts.input);
+		child.stdin.end();
+		return new Promise((resolve, reject) => {
+			const stdout = [];
+			const stderr = [];
+			child.stdout.on("data", (chunk) => stdout.push(chunk));
+			child.stderr.on("data", (chunk) => stderr.push(chunk));
+			child.on("error", reject);
+			child.on("close", (code) => {
+				const out = Buffer.concat(stdout);
+				const err = Buffer.concat(stderr);
+				if (code === 0) resolve({
+					stdout: out,
+					stderr: err
+				});
+				else {
+					const e = /* @__PURE__ */ new Error(`git ${args.join(" ")} exited with ${code}: ${err.toString("utf8")}`);
+					e.code = code ?? -1;
+					e.stdout = out;
+					e.stderr = err;
+					reject(e);
 				}
-				return searchResults.map((t) => ({
-					title: themeLabel(t),
-					value: t.id
-				}));
-			}
-		}, { onCancel: () => process.exit(130) });
-		if (id === LOAD_MORE_VALUE) {
-			initialIndex = allThemes.length;
-			page++;
-			continue;
-		}
-		if (!id) {
-			console.error("No theme selected.");
-			process.exit(1);
-		}
-		const found = allThemes.find((t) => t.id === id) ?? searchResults.find((t) => t.id === id);
-		if (found) return found;
-		return (await getApplicationTheme(api, id)).application_theme;
+			});
+		});
 	}
+};
+/**
+* Content-type check the pull command uses to decide whether a file
+* is safe to run through `merge3` (line-based) or must fall back to
+* whole-file "either/or" resolution (binary).
+*/
+function looksBinary(content) {
+	return content.subarray(0, Math.min(content.length, 8e3)).includes(0);
 }
-async function findTheme(api, identifier) {
-	const idNum = Number(identifier);
-	if (Number.isInteger(idNum) && idNum > 0) try {
-		const body = await getApplicationTheme(api, idNum);
-		if (body.application_theme) return body.application_theme;
-	} catch {}
-	let page = 1;
-	let hasMore = true;
-	while (hasMore) {
-		const result = await fetchThemesPage(api, page, identifier);
-		const found = result.themes.find((t) => t.name.toLowerCase() === identifier.toLowerCase());
-		if (found) return found;
-		hasMore = result.hasMore;
-		page++;
+/** Best-effort readFile that returns null when the file does not exist. */
+function readIfExists(path) {
+	try {
+		return readFileSync(path);
+	} catch {
+		return null;
 	}
-	console.error(`No theme found with identifier: ${identifier}`);
-	process.exit(1);
 }
-//#endregion
-//#region src/workspace.ts
-const WORKSPACE_FILE = ".fluid-workspace.json";
 /**
-* Walk up from `startDir` looking for `.fluid-workspace.json`.
-* Returns the workspace info if found, or `null` if not in a workspace.
+* Parse the numeric theme id from `.fluid-theme/theme-id`. Returns
+* null when the file is missing or the contents don't parse cleanly;
+* `open` treats that as "unknown theme" and rebuilds the shadow.
 */
-function findWorkspace(startDir) {
-	let dir = resolve(startDir ?? process.cwd());
-	while (true) {
-		const candidate = join(dir, WORKSPACE_FILE);
-		if (existsSync(candidate)) try {
-			const raw = readFileSync(candidate, "utf-8");
-			const config = JSON.parse(raw);
-			return {
-				root: dir,
-				config
-			};
-		} catch {
-			return null;
-		}
-		const parent = dirname(dir);
-		if (parent === dir) break;
-		dir = parent;
+function readStoredThemeId(themeIdFile) {
+	try {
+		const stored = parseInt(readFileSync(themeIdFile, "utf-8").trim(), 10);
+		return Number.isFinite(stored) ? stored : null;
+	} catch {
+		return null;
 	}
-	return null;
 }
 /**
-* If cwd is already inside `{workspace}/local/{company}/...`, return that
-* theme root directory. Otherwise return null.
-*
-* Examples (workspace root = /code/fluid-theme-dev):
-*   cwd = /code/fluid-theme-dev/local/acme-co           → /code/fluid-theme-dev/local/acme-co
-*   cwd = /code/fluid-theme-dev/local/acme-co/templates  → /code/fluid-theme-dev/local/acme-co
-*   cwd = /code/fluid-theme-dev                          → null
-*   cwd = /code/fluid-theme-dev/local                    → null
+* Append `.fluid-theme/` to the theme root's `.gitignore` when the
+* theme dir sits inside a git working tree and the entry isn't
+* already there. Skipped when the user isn't in a git repo — no
+* point manufacturing a `.gitignore` for someone who doesn't use
+* git. Idempotent — a second call is a no-op.
 */
-function resolveThemeRootFromCwd(workspace) {
-	const cwd = resolve(process.cwd());
-	const localDir = join(workspace.root, "local");
-	const rel = relative(localDir, cwd);
-	if (rel.startsWith("..") || rel === ".") return null;
-	const firstSegment = rel.split(sep)[0];
-	if (!firstSegment) return null;
-	return join(localDir, firstSegment);
+async function ensureRootGitignoreHidesShadow(themeRoot) {
+	if (!await new Promise((resolve) => {
+		const child = spawn("git", ["rev-parse", "--is-inside-work-tree"], {
+			cwd: themeRoot,
+			stdio: [
+				"ignore",
+				"pipe",
+				"pipe"
+			]
+		});
+		child.on("close", (code) => resolve(code === 0));
+		child.on("error", () => resolve(false));
+	})) return;
+	const gitignorePath = join(themeRoot, ".gitignore");
+	let existing = "";
+	try {
+		existing = readFileSync(gitignorePath, "utf-8");
+	} catch {
+		existing = "";
+	}
+	const lines = existing.split("\n").map((line) => line.trim());
+	if (lines.includes(".fluid-theme/") || lines.includes(".fluid-theme")) return;
+	const separator = existing.length === 0 || existing.endsWith("\n") ? "" : "\n";
+	writeFileSync(gitignorePath, `${existing}${separator}.fluid-theme/\n`, "utf-8");
 }
 //#endregion
-//#region src/commands/dev.ts
+//#region src/theme/merge-push.ts
 /**
-* Create the isolated theme used by `theme dev`.
+* Compute what changed locally since the last time the shadow repo
+* committed a state. Replaces the sha256 `checksums` map: shadow HEAD
+* is the source of truth for "what the CLI last saw the server have".
 *
-* A checkout from `theme pull` has a source theme id. New servers clone that
-* source by reference, preserving its DAM/ImageKit assets without moving
-* bytes. A 404/405 keeps older deployments compatible with the established
-* empty-theme flow; other failures must remain visible to the developer.
+* Files whose local bytes are byte-identical to their HEAD blob are
+* skipped; anything else — new, modified, or a locally-deleted path
+* that HEAD still has — is included.
 */
-async function createDevelopmentTheme(api, sourceThemeId, name) {
-	if (sourceThemeId !== void 0) try {
-		return (await cloneApplicationThemeForDevelopment(api, sourceThemeId, { application_theme: { name } })).application_theme;
-	} catch (error) {
-		if (!isApiError(error) || error.status !== 404 && error.status !== 405) throw error;
-		console.warn("Server-side theme cloning is unavailable; falling back to an empty development theme. The first sync may take longer.");
+async function diffAgainstShadow(themeRoot, shadow) {
+	const changed = [];
+	const deleted = [];
+	const localFiles = themeRoot.files();
+	const localByKey = /* @__PURE__ */ new Map();
+	const assetManifest = new ThemeAssetManifest(themeRoot.root);
+	for (const file of localFiles) {
+		if (!file.exists) continue;
+		localByKey.set(file.relativePath, file);
+		const headBlob = await shadow.blobAtHead(file.relativePath);
+		const localBuf = file.isText ? Buffer.from(file.read()) : file.readBinary();
+		if (headBlob && headBlob.equals(localBuf)) continue;
+		changed.push(file);
 	}
-	return (await createApplicationTheme(api, { application_theme: {
-		name,
-		status: "development"
-	} })).application_theme;
-}
-async function ensureDevTheme(api, projectKey, identifier, sourceThemeId) {
-	if (identifier) {
-		const theme = await findTheme(api, identifier);
-		setLastDevThemeId(theme.id);
-		return theme;
+	if (await shadow.hasHead()) for (const key of await listHeadPaths(shadow)) {
+		if (localByKey.has(key)) continue;
+		if (themeRoot.ignore.ignore(key)) continue;
+		if (assetManifest.has(key)) continue;
+		if (isStylesheetKey(key)) continue;
+		deleted.push(key);
 	}
-	const stored = getDevTheme(projectKey);
-	if (stored && stored.sourceThemeId === sourceThemeId) {
-		try {
-			const existing = (await getApplicationTheme(api, stored.id)).application_theme;
-			if (existing && existing.status === "development") {
-				console.log(`Using existing dev theme #${existing.id}`);
-				setDevTheme(projectKey, {
-					id: existing.id,
-					name: existing.name,
-					...sourceThemeId === void 0 ? {} : { sourceThemeId }
-				});
-				return existing;
-			}
-		} catch {}
-		clearDevTheme(projectKey);
+	return {
+		changed,
+		deleted
+	};
+}
+/**
+* Read every path recorded under HEAD's tree. Used to detect local
+* deletions (paths in HEAD, absent from the working tree). Implemented
+* with `git ls-tree -r HEAD --name-only` piped through the shadow
+* repo's plumbing.
+*/
+async function listHeadPaths(shadow) {
+	return shadow.headPaths();
+}
+/**
+* Refuse a push when any working file still contains a conflict marker
+* from a previous pull. Mirrors git's "you have unresolved conflicts;
+* fix them and re-run" behavior — the whole point of writing markers
+* on pull was to hand resolution to the user, so we can't send them
+* upstream.
+*/
+function findUnresolvedConflicts(files) {
+	const flagged = [];
+	for (const file of files) {
+		if (!file.isText) continue;
+		const buf = readIfExists(file.absolutePath);
+		if (!buf) continue;
+		if (containsConflictMarker(buf)) flagged.push(file.relativePath);
 	}
-	const { hostname } = await import("node:os");
-	const theme = await createDevelopmentTheme(api, sourceThemeId, `Development (${hostname().split(".")[0] ?? "dev"}-${Math.random().toString(36).slice(2, 8)})`.slice(0, 50));
-	setDevTheme(projectKey, {
-		id: theme.id,
-		name: theme.name,
-		...sourceThemeId === void 0 ? {} : { sourceThemeId }
-	});
-	console.log(`Created dev theme: ${theme.name} (#${theme.id})`);
-	return theme;
+	return flagged;
 }
-function createDevCommand() {
-	return new Command("dev").description("Start the theme dev server with hot reload").option("--host <host>", "Local server host", "127.0.0.1").option("--port <port>", "Local server port", "9292").option("-t, --theme <name-or-id>", "Use an existing theme instead of dev theme").option("-f, --force", "Skip schema validation on upload").option("--live-reload <mode>", "Reload mode: full-page | off", "full-page").option("--navigate", "Open browser navigator after server starts").option("--root <path>", "Theme root directory", ".").action(async (opts) => {
-		requireToken();
-		let rootPath = opts.root;
-		if (rootPath === ".") {
-			const workspace = findWorkspace();
-			if (workspace) rootPath = resolveThemeRootFromCwd(workspace) ?? rootPath;
-		}
-		const themeRoot = new ThemeRoot(rootPath);
-		if (!themeRoot.isValid()) {
-			console.error(`'${rootPath}' does not look like a theme directory.`);
-			process.exit(1);
-		}
-		const port = Number(opts.port);
-		if (!Number.isInteger(port) || port < 1 || port > 65535) {
-			console.error(`Invalid port: '${opts.port}'. Must be an integer between 1 and 65535.`);
-			process.exit(1);
-		}
-		try {
-			await checkPortAvailable(opts.host, port);
-		} catch (e) {
-			if (e instanceof PortInUseError) console.error(e.message);
-			else console.error(`Failed to check port availability: ${e}`);
-			process.exit(1);
-		}
-		const reloadMode = opts.liveReload === "off" ? "off" : "full-page";
-		const api = createApiClient();
-		const config = readThemeConfig(themeRoot.root);
-		let company;
-		if (config?.company) company = config.company;
-		else {
-			company = (await api.get("/api/company/v1/companies/me")).data?.company?.subdomain ?? "";
-			if (!company) {
-				console.error("Could not determine company subdomain. Make sure your token is valid.");
-				process.exit(1);
-			}
-		}
-		const projectKey = devThemeKey(company, themeRoot.root);
-		const theme = opts.theme ? await ensureDevTheme(api, projectKey, opts.theme) : await ensureDevTheme(api, projectKey, void 0, config?.themeId);
-		const editorUrl = `https://admin.fluid.app/themes/${theme.id}/editor`;
-		let stop;
-		const cleanup = () => {
-			stop?.();
-			process.exit(0);
-		};
-		process.on("SIGINT", cleanup);
-		process.on("SIGTERM", cleanup);
-		stop = await startDevServer(api, {
-			id: theme.id,
-			name: theme.name,
-			company,
-			editorUrl
-		}, themeRoot, {
-			host: opts.host,
-			port,
-			reloadMode,
-			validate: !opts.force
-		}, (address) => {
-			console.log(`\n  Dev server: ${address}`);
-			console.log(`  Web editor: ${editorUrl}`);
-			console.log("\n  Watching for file changes…\n");
-			if (opts.navigate) import("open").then((m) => m.default(`${address}/home`));
+/**
+* Stable, machine-readable one-liner for non-interactive callers
+* (Mist Desktop's publish flow parses push output). Uploading marker-
+* bearing files to a live theme is never acceptable, so `--auto-
+* baseline` pushes still refuse — but they emit this line so the
+* desktop can surface WHICH files block the publish instead of a
+* dead-end wall of prose. Format:
+*
+*   FLUID_THEME_PUSH_BLOCKED code=conflict_markers files=a.liquid,b.json
+*/
+function conflictMarkerBlockLine(files) {
+	return `FLUID_THEME_PUSH_BLOCKED code=conflict_markers files=${files.join(",")}`;
+}
+const CONFLICT_START = Buffer.from("<<<<<<<");
+const CONFLICT_MID = Buffer.from("=======");
+const CONFLICT_END = Buffer.from(">>>>>>>");
+/**
+* A file counts as unresolved when it contains all three marker
+* shapes: `<<<<<<<`, `=======`, and `>>>>>>>`. Requiring all three
+* avoids false positives — a line of equals signs alone (e.g. inside
+* an ASCII table in a template comment) doesn't trip the guard.
+*/
+function containsConflictMarker(buf) {
+	return buf.includes(CONFLICT_START) && buf.includes(CONFLICT_MID) && buf.includes(CONFLICT_END);
+}
+/**
+* Commit the current working-tree state to shadow HEAD after a
+* successful push. Ensures the next pull's merge base is the state
+* we know the server just accepted.
+*/
+async function commitPushedState(themeRoot, shadow, message) {
+	const entries = [];
+	const assetManifest = new ThemeAssetManifest(themeRoot.root);
+	const localKeys = /* @__PURE__ */ new Set();
+	for (const file of themeRoot.files()) {
+		if (!file.exists) continue;
+		localKeys.add(file.relativePath);
+		const buf = file.isText ? Buffer.from(file.read()) : file.readBinary();
+		entries.push({
+			path: file.relativePath,
+			sha: await shadow.writeBlob(buf)
 		});
-		await new Promise(() => {});
-	});
+	}
+	let managedAssetSentinelSha;
+	for (const key of assetManifest.keys()) {
+		if (localKeys.has(key)) continue;
+		managedAssetSentinelSha ??= await shadow.writeBlob(MANAGED_ASSET_SHADOW_SENTINEL);
+		entries.push({
+			path: key,
+			sha: managedAssetSentinelSha
+		});
+	}
+	if (entries.length > 0 || await shadow.hasHead()) await shadow.commitState(entries, message);
+}
+/**
+* A target can already have every URL-backed FileResource (for example from a
+* reference clone), while this checkout's manifest still names its old source
+* theme. Adopt the target and clear any legacy binary from shadow even though
+* no remote write was necessary.
+*/
+async function finalizeManifestOnlyPush(syncer, themeRoot, shadow) {
+	syncer.repointManagedAssetsToCurrentTheme();
+	await commitPushedState(themeRoot, shadow, `push @ ${(/* @__PURE__ */ new Date()).toISOString()}`);
 }
 //#endregion
-//#region src/theme/shadow-repo.ts
+//#region src/theme/liquid-delimiters.ts
 /**
-* A bare git repo hidden under `.fluid-theme/repo` that stands in for
-* git's index+HEAD when talking to the Fluid server. Every pull commits
-* the incoming remote state onto a single branch (`refs/heads/main`);
-* every successful push commits the outgoing local state onto the same
-* branch. HEAD therefore represents "the last state the CLI and server
-* agreed on", and its tree is the natural three-way-merge base for the
-* next pull.
+* Heuristic-only check for obviously unbalanced liquid delimiters
+* (`{% %}` and `{{ }}`). This is NOT a liquid parser — it only tracks
+* opening delimiters until they are closed. It exists to give watch-mode users a signal
+* when a save is liquid-syntax-broken: the server accepts
+* syntax-broken liquid silently on upload, and the storefront
+* renderer then serves stale content for that section with no error
+* anywhere else in the pipeline.
 *
-* We stay in git's plumbing layer — no working tree, no index file
-* next to the theme content — so the shadow repo cannot interfere
-* with the user's own git repo (if they have one) around the theme
-* dir. All state lives inside `.fluid-theme/`.
+* Closing-looking tokens without a preceding Liquid opener are intentionally
+* ignored. Liquid files commonly contain CSS such as `width:100%}` or adjacent
+* block braces (`}}`), so treating every close token as Liquid creates noisy
+* false warnings on valid theme files.
 *
-* The class only wraps the small handful of plumbing commands we
-* actually need: hash-object, cat-file, write-tree (via a temp index),
-* commit-tree, update-ref, and merge-file. Everything else stays out.
+* Known false positive: delimiters written literally inside a
+* `{% raw %}...{% endraw %}` block are still counted and can trip
+* this check even though the liquid is valid. Acceptable for a
+* warn-only heuristic — a real fix requires parsing liquid, which is
+* out of scope here (see the server-side validation note in the PR).
 */
-var ShadowRepo = class ShadowRepo {
-	headExists = void 0;
-	constructor(themeRoot, gitDir) {
-		this.themeRoot = themeRoot;
-		this.gitDir = gitDir;
+function hasUnbalancedLiquidDelimiters(content) {
+	let unclosedTags = 0;
+	let unclosedOutputs = 0;
+	for (const token of content.matchAll(/\{%|%\}|\{\{|\}\}/g)) switch (token[0]) {
+		case "{%":
+			unclosedTags += 1;
+			break;
+		case "%}":
+			if (unclosedTags > 0) unclosedTags -= 1;
+			break;
+		case "{{":
+			unclosedOutputs += 1;
+			break;
+		case "}}":
+			if (unclosedOutputs > 0) unclosedOutputs -= 1;
+			break;
 	}
-	/**
-	* Return a ShadowRepo bound to `themeId` for the given theme root.
-	* The shadow is initialized on first use and re-initialized when
-	* the caller passes a themeId different from the one previously
-	* recorded — the merge base is only meaningful for the theme it
-	* was captured against, so a cross-theme operation (pull A → push
-	* B, or two pulls of different themes into one dir) starts from a
-	* clean slate rather than pretending B's state matches A's HEAD.
-	*/
-	static async open(themeRoot, themeId) {
-		const shadowDir = join(themeRoot, ".fluid-theme");
-		const gitDir = join(shadowDir, "repo");
-		const themeIdFile = join(shadowDir, "theme-id");
-		if (existsSync(gitDir)) {
-			if (readStoredThemeId(themeIdFile) !== themeId) rmSync(gitDir, {
-				recursive: true,
-				force: true
+	return unclosedTags > 0 || unclosedOutputs > 0;
+}
+const BLOCK_TAGS = new Map([
+	["capture", "endcapture"],
+	["case", "endcase"],
+	["comment", "endcomment"],
+	["for", "endfor"],
+	["form", "endform"],
+	["if", "endif"],
+	["ifchanged", "endifchanged"],
+	["javascript", "endjavascript"],
+	["paginate", "endpaginate"],
+	["raw", "endraw"],
+	["schema", "endschema"],
+	["style", "endstyle"],
+	["stylesheet", "endstylesheet"],
+	["tablerow", "endtablerow"],
+	["unless", "endunless"]
+]);
+const CLOSING_TAGS = new Set(BLOCK_TAGS.values());
+const OPAQUE_BLOCK_TAGS = new Set([
+	"comment",
+	"javascript",
+	"raw",
+	"schema",
+	"style",
+	"stylesheet"
+]);
+/**
+* Find structurally unbalanced Liquid block tags such as an `{% if %}` with
+* no `{% endif %}`. This intentionally recognizes only established paired
+* tags; custom and inline tags are ignored rather than guessed at.
+*
+* Content inside raw/comment/schema/style/javascript blocks is opaque to
+* Liquid and therefore skipped until that block's matching close tag. This
+* prevents CSS, JSON, and examples containing Liquid-looking text from
+* producing false errors.
+*/
+function findLiquidBlockTagDiagnostics(content) {
+	const stack = [];
+	const diagnostics = [];
+	let line = 1;
+	let previousTagIndex = 0;
+	const processTag = (name, tagLine) => {
+		const open = stack.at(-1);
+		if (open && OPAQUE_BLOCK_TAGS.has(open.name)) {
+			if (name === open.expectedClose) stack.pop();
+			return;
+		}
+		const expectedClose = BLOCK_TAGS.get(name);
+		if (expectedClose) {
+			stack.push({
+				name,
+				expectedClose,
+				line: tagLine
 			});
+			return;
 		}
-		const repo = new ShadowRepo(themeRoot, gitDir);
-		if (!existsSync(gitDir)) {
-			mkdirSync(shadowDir, { recursive: true });
-			await repo.git([
-				"init",
-				"--bare",
-				"-b",
-				"main",
-				gitDir
-			], { cwd: themeRoot });
+		if (!CLOSING_TAGS.has(name)) return;
+		if (!open) {
+			diagnostics.push({
+				severity: "error",
+				message: `Unexpected Liquid tag '{% ${name} %}' on line ${tagLine}; there is no open block to close.`
+			});
+			return;
 		}
-		writeFileSync(themeIdFile, `${themeId}\n`, "utf-8");
-		const shadowIgnore = join(shadowDir, ".gitignore");
-		if (!existsSync(shadowIgnore)) writeFileSync(shadowIgnore, "# Fluid CLI shadow repo — internal state, not for version control.\n*\n");
-		await ensureRootGitignoreHidesShadow(themeRoot);
-		return repo;
-	}
-	/** True when the repo has at least one commit on `refs/heads/main`. */
-	async hasHead() {
-		if (this.headExists !== void 0) return this.headExists;
-		try {
-			await this.git([
-				"rev-parse",
-				"--verify",
-				"HEAD"
-			]);
-			this.headExists = true;
-		} catch {
-			this.headExists = false;
+		if (name !== open.expectedClose) {
+			diagnostics.push({
+				severity: "error",
+				message: `Mismatched Liquid tag '{% ${name} %}' on line ${tagLine}; '{% ${open.name} %}' from line ${open.line} must close with '{% ${open.expectedClose} %}'.`
+			});
+			return;
 		}
-		return this.headExists;
+		stack.pop();
+	};
+	for (const match of content.matchAll(/\{%-?\s*([a-zA-Z_][\w-]*)\b(?:(?!\{%)[\s\S])*?-?%\}/g)) {
+		const name = match[1]?.toLowerCase();
+		if (!name) continue;
+		const index = match.index ?? 0;
+		for (let cursor = previousTagIndex; cursor < index; cursor++) if (content.charCodeAt(cursor) === 10) line += 1;
+		previousTagIndex = index;
+		const open = stack.at(-1);
+		if (name === "liquid" && !(open && OPAQUE_BLOCK_TAGS.has(open.name))) {
+			const statements = match[0].replace(/^\{%-?\s*liquid\b/i, "").replace(/-?%\}$/, "").split("\n");
+			for (const [offset, statement] of statements.entries()) {
+				const statementName = /^\s*([a-zA-Z_][\w-]*)\b/.exec(statement)?.[1];
+				if (!statementName) continue;
+				processTag(statementName.toLowerCase(), line + offset);
+			}
+		} else processTag(name, line);
 	}
-	/**
-	* Every path recorded under HEAD's tree, recursively. Callers use
-	* this to detect local deletions (paths in HEAD, absent from the
-	* working tree). Returns [] when HEAD has never been committed.
-	*/
-	async headPaths() {
-		if (!await this.hasHead()) return [];
-		const { stdout } = await this.git([
-			"ls-tree",
-			"-r",
-			"-z",
-			"HEAD",
-			"--name-only"
-		]);
-		return stdout.toString("utf8").split("\0").filter((line) => line.length > 0);
+	for (const open of stack.reverse()) diagnostics.push({
+		severity: "error",
+		message: `Unclosed Liquid tag '{% ${open.name} %}' on line ${open.line}; expected '{% ${open.expectedClose} %}'.`
+	});
+	return diagnostics;
+}
+//#endregion
+//#region src/theme/dev-server/port-preflight.ts
+/**
+* The dev command does real work before it ever binds a port: it resolves
+* (or creates) a server-side dev theme and runs a full initial sync, which
+* can take minutes on a large theme. If the requested port is already taken
+* — most commonly by another `fluid theme dev` or the Mist Desktop preview,
+* which both default to 9292 — all of that work is wasted and the process
+* used to die with a raw `EADDRINUSE` stack trace. Call this before any of
+* that work starts so we fail fast with a clear message instead.
+*/
+var PortInUseError = class extends Error {
+	constructor(host, port) {
+		super(formatPortConflictMessage(host, port));
+		this.host = host;
+		this.port = port;
+		this.name = "PortInUseError";
 	}
-	/**
-	* The content of `path` in HEAD's tree, or null when the path does
-	* not exist there. Callers use this as the merge base for pull
-	* conflict resolution.
-	*/
-	async blobAtHead(path) {
-		if (!await this.hasHead()) return null;
+};
+function formatPortConflictMessage(host, port) {
+	return `Port ${port} on ${host} is already in use — likely another \`fluid theme dev\` or the Mist Desktop preview. Stop the other server or pass --port <number>.`;
+}
+/**
+* Attempt to bind `host:port`, then immediately release it. Resolves if the
+* port is free; rejects with `PortInUseError` on `EADDRINUSE`/`EACCES`, or
+* the raw error for anything else unexpected.
+*/
+function checkPortAvailable(host, port) {
+	return new Promise((resolve, reject) => {
+		const server = net.createServer();
+		server.once("error", (err) => {
+			if (err.code === "EADDRINUSE" || err.code === "EACCES") reject(new PortInUseError(host, port));
+			else reject(err);
+		});
+		server.once("listening", () => {
+			server.close(() => resolve());
+		});
+		server.listen(port, host);
+	});
+}
+//#endregion
+//#region src/theme/dev-server/index.ts
+function timestamp() {
+	return (/* @__PURE__ */ new Date()).toLocaleTimeString("en-US", { hour12: false });
+}
+async function startDevServer(api, theme, themeRoot, opts, onReady) {
+	const sse = new SSEStream();
+	const syncer = new Syncer(api, theme.id, themeRoot);
+	const recordRemoteSha = () => {
+		const remoteSha = syncer.remoteSha();
+		if (remoteSha) opts.onRemoteSha?.(remoteSha);
+	};
+	const pendingUpdates = /* @__PURE__ */ new Set();
+	console.log(`\nSyncing theme ${theme.name} (#${theme.id})…`);
+	const progress = (done, total) => {
+		process.stdout.write(`\r  Uploading ${done}/${total} files…`);
+	};
+	const uploadFromRemoteIndex = () => syncer.uploadTheme({
+		delete: true,
+		validate: opts.validate,
+		linkManagedAssets: { replace: true },
+		pendingBinaryAssets: true,
+		onProgress: progress
+	});
+	let syncResult;
+	if (opts.initialSync) {
+		let shadowIsTrusted = false;
 		try {
-			const { stdout } = await this.git([
-				"cat-file",
-				"-p",
-				`HEAD:${path}`
-			]);
-			return stdout;
-		} catch {
-			return null;
+			await syncer.preflightPush(opts.initialSync.remoteSha);
+			shadowIsTrusted = true;
+		} catch (error) {
+			if (!(error instanceof PushConflictError)) throw error;
 		}
+		if (shadowIsTrusted) {
+			const diff = await diffAgainstShadow(themeRoot, opts.initialSync.shadow);
+			syncResult = await syncer.uploadTheme({
+				delete: true,
+				validate: opts.validate,
+				pendingBinaryAssets: true,
+				baseSha: syncer.remoteSha(),
+				diff,
+				skipPreflight: true,
+				onProgress: progress
+			});
+		} else syncResult = await uploadFromRemoteIndex();
+	} else syncResult = await uploadFromRemoteIndex();
+	process.stdout.write("\n");
+	if (syncResult.linked > 0) console.log(`  Saved ${syncResult.linked} remote asset reference(s).`);
+	if (syncResult.validationFailed) {
+		console.error(`\nSchema validation failed (${syncResult.errors.length} error(s)). Use --force to skip.\n`);
+		for (const e of syncResult.errors) console.error(`  ${e}`);
+		process.exit(1);
+	} else if (syncResult.errors.length > 0) {
+		for (const e of syncResult.errors) console.error(`  ${e}`);
+		if (syncResult.uploaded + syncResult.deleted === 0) process.exit(1);
 	}
-	/**
-	* Write `content` as a blob in the shadow repo and return its sha.
-	* Used by `commitState` to stage each file's content before the
-	* `write-tree` call.
-	*/
-	async writeBlob(content) {
-		const buf = typeof content === "string" ? Buffer.from(content) : content;
-		const { stdout } = await this.git([
-			"hash-object",
-			"-w",
-			"--stdin"
-		], { input: buf });
-		return stdout.toString("utf8").trim();
-	}
-	/**
-	* Commit `files` as HEAD's new tree, threaded onto the current HEAD
-	* as the parent. Uses a per-call temp index so a partial run can't
-	* corrupt anything reachable from HEAD; the previous commit stays
-	* intact until `update-ref` at the end.
-	*
-	* Returns the new commit sha.
-	*/
-	async commitState(files, message) {
-		const indexPath = mkdtempSync(join(tmpdir(), "fluid-shadow-")) + "/index";
-		try {
-			const indexArgs = ["update-index", "--add"];
-			for (const { path, sha } of files) indexArgs.push("--cacheinfo", `100644,${sha},${path}`);
-			if (files.length > 0) await this.git(indexArgs, { env: { GIT_INDEX_FILE: indexPath } });
-			const treeSha = (await this.git(["write-tree"], { env: { GIT_INDEX_FILE: indexPath } })).stdout.toString("utf8").trim();
-			const parent = await this.hasHead() ? (await this.git(["rev-parse", "HEAD"])).stdout.toString("utf8").trim() : null;
-			const commitArgs = [
-				"commit-tree",
-				treeSha,
-				"-m",
-				message
-			];
-			if (parent) commitArgs.push("-p", parent);
-			const commitSha = (await this.git(commitArgs, { env: {
-				GIT_AUTHOR_NAME: "Fluid CLI",
-				GIT_AUTHOR_EMAIL: "cli@fluid.app",
-				GIT_COMMITTER_NAME: "Fluid CLI",
-				GIT_COMMITTER_EMAIL: "cli@fluid.app"
-			} })).stdout.toString("utf8").trim();
-			await this.git([
-				"update-ref",
-				"refs/heads/main",
-				commitSha
-			]);
-			this.headExists = true;
-			return commitSha;
-		} finally {
-			try {
-				rmSync(indexPath, { force: true });
-				rmSync(indexPath.substring(0, indexPath.length - 6), {
-					recursive: true,
-					force: true
-				});
-			} catch {}
+	if (syncResult.errors.length === 0) recordRemoteSha();
+	const SYNC_IDLE_MS = 2e3;
+	let lastArrivedAt = 0;
+	let pendingSync = null;
+	let syncInFlight = Promise.resolve();
+	let askOwed = false;
+	const sendSync = () => {
+		syncInFlight = syncInFlight.then(async () => {
+			askOwed = !await syncer.requestSync();
+		});
+	};
+	const flushSyncNow = () => {
+		if (!pendingSync) return;
+		clearTimeout(pendingSync);
+		pendingSync = null;
+		sendSync();
+	};
+	const scheduleSync = () => {
+		if (pendingSync) clearTimeout(pendingSync);
+		pendingSync = setTimeout(() => {
+			pendingSync = null;
+			sendSync();
+		}, SYNC_IDLE_MS);
+	};
+	const stopWatcher = watchTheme(themeRoot, async (modified, added, removed, arrivedAt) => {
+		if (arrivedAt - lastArrivedAt > SYNC_IDLE_MS) flushSyncNow();
+		else if (pendingSync) {
+			clearTimeout(pendingSync);
+			pendingSync = null;
 		}
-	}
-	/**
-	* Three-way merge of `local` against `remote` with `base` as the
-	* common ancestor. Returns the merged bytes and a flag when
-	* `git merge-file` reported unresolved conflicts (i.e. the output
-	* contains `<<<<<<<` markers for the reader to resolve).
-	*
-	* `base` is null when HEAD has never seen this path; we merge
-	* against an empty base, which is what git itself does for a new
-	* file added on both sides.
-	*
-	* `favor` maps to `git merge-file`'s `--ours` / `--theirs`: instead
-	* of emitting `<<<<<<<` markers, conflicting hunks are resolved to
-	* the local (`"local"` → `--ours`, local is file1) or remote
-	* (`"remote"` → `--theirs`) side. The output then never contains
-	* markers, so the result is reported conflict-free even when
-	* merge-file's exit code still counts the auto-resolved hunks.
-	*/
-	async merge3(base, local, remote, favor) {
-		const dir = mkdtempSync(join(tmpdir(), "fluid-merge-"));
-		const localPath = join(dir, "local");
-		const basePath = join(dir, "base");
-		const remotePath = join(dir, "remote");
-		try {
-			writeFileSync(localPath, local);
-			writeFileSync(basePath, base ?? Buffer.alloc(0));
-			writeFileSync(remotePath, remote);
+		lastArrivedAt = arrivedAt;
+		await syncInFlight;
+		if (askOwed) {
+			sendSync();
+			await syncInFlight;
+		}
+		const changed = [...modified, ...added];
+		let wroteRemote = false;
+		for (const file of changed) {
+			if (opts.validate && file.isLiquid) {
+				const diagnostics = file.validateSchema();
+				for (const d of diagnostics) {
+					const prefix = d.severity === "error" ? "Schema error" : "Schema warning";
+					console.warn(`\n[${prefix}] ${file.relativePath}: ${d.message}`);
+				}
+			}
+			pendingUpdates.add(file.relativePath);
 			try {
-				const { stdout } = await this.git([
-					"merge-file",
-					"-p",
-					...favor === "local" ? ["--ours"] : favor === "remote" ? ["--theirs"] : [],
-					"-L",
-					"local",
-					"-L",
-					"base",
-					"-L",
-					"remote",
-					localPath,
-					basePath,
-					remotePath
-				]);
-				return {
-					merged: stdout,
-					hasConflicts: false
-				};
-			} catch (err) {
-				const e = err;
-				const merged = e.stdout instanceof Buffer ? e.stdout : e.stdout != null ? Buffer.from(e.stdout) : Buffer.alloc(0);
-				const inConflictRange = typeof e.code === "number" && e.code >= 1 && e.code <= 127;
-				if (inConflictRange && favor) return {
-					merged,
-					hasConflicts: false
-				};
-				if (inConflictRange && merged.length > 0) return {
-					merged,
-					hasConflicts: true
-				};
-				throw err;
+				const uploadedContent = await syncer.uploadFile(file, void 0, { pendingAsset: true });
+				wroteRemote = true;
+				console.log(`  ✓ synced ${file.relativePath} (${timestamp()})`);
+				if (file.isLiquid && uploadedContent !== null && hasUnbalancedLiquidDelimiters(uploadedContent)) console.warn(`  ⚠ ${file.relativePath}: unbalanced liquid delimiters — the storefront may silently serve stale content for this section`);
+				if (file.isLiquid && uploadedContent !== null) for (const diagnostic of findLiquidBlockTagDiagnostics(uploadedContent)) console.warn(`  ⚠ ${file.relativePath}: ${diagnostic.message}`);
+			} catch (e) {
+				console.error(`\n[Watcher] Upload failed: ${file.relativePath}: ${e}`);
+			} finally {
+				pendingUpdates.delete(file.relativePath);
 			}
-		} finally {
+		}
+		for (const file of removed) {
+			if (themeRoot.ignore.ignore(file.relativePath)) continue;
 			try {
-				rmSync(dir, {
-					recursive: true,
-					force: true
-				});
+				await syncer.deleteRemoteFile(file.relativePath);
+				wroteRemote = true;
+				console.log(`  ✓ removed ${file.relativePath}`);
 			} catch {}
 		}
-	}
-	/**
-	* Snapshot the working-tree copy of `paths` into HEAD as a single
-	* commit. Intended for the migration path: on the first pull with
-	* the new CLI (no shadow repo yet, but a `.fluid-theme.json` with
-	* checksums exists) we seed HEAD with whatever is on disk before
-	* running the merge, so unmodified files fast-forward cleanly and
-	* modified files show a diff.
-	*/
-	async seedFromWorkingTree(files, message) {
-		const entries = [];
-		for (const { path, content } of files) entries.push({
-			path,
-			sha: await this.writeBlob(content)
-		});
-		await this.commitState(entries, message);
-	}
-	async git(args, opts = {}) {
-		const child = spawn("git", args[0] === "init" ? args : [
-			"--git-dir",
-			this.gitDir,
-			...args
-		], {
-			cwd: opts.cwd ?? this.themeRoot,
-			env: {
-				...process.env,
-				...opts.env
-			},
-			stdio: [
-				"pipe",
-				"pipe",
-				"pipe"
-			]
-		});
-		if (opts.input) child.stdin.write(opts.input);
-		child.stdin.end();
-		return new Promise((resolve, reject) => {
-			const stdout = [];
-			const stderr = [];
-			child.stdout.on("data", (chunk) => stdout.push(chunk));
-			child.stderr.on("data", (chunk) => stderr.push(chunk));
-			child.on("error", reject);
-			child.on("close", (code) => {
-				const out = Buffer.concat(stdout);
-				const err = Buffer.concat(stderr);
-				if (code === 0) resolve({
-					stdout: out,
-					stderr: err
-				});
-				else {
-					const e = /* @__PURE__ */ new Error(`git ${args.join(" ")} exited with ${code}: ${err.toString("utf8")}`);
-					e.code = code ?? -1;
-					e.stdout = out;
-					e.stderr = err;
-					reject(e);
-				}
+		if (wroteRemote) recordRemoteSha();
+		if (removed.length > 0) sse.broadcast(JSON.stringify({ reload_page: true }));
+		else if (changed.length > 0) sse.broadcast(JSON.stringify({ modified: changed.map((f) => f.relativePath) }));
+		scheduleSync();
+	});
+	const server = http.createServer(async (req, res) => {
+		if (req.url === "/hot-reload") {
+			sse.add(res);
+			return;
+		}
+		try {
+			await proxyRequest(req, res, {
+				company: theme.company,
+				themeId: theme.id,
+				reloadMode: opts.reloadMode,
+				pendingFiles: () => [...pendingUpdates].map((p) => themeRoot.file(p)).filter((f) => f.isText).map((f) => ({
+					relativePath: f.relativePath,
+					read: () => f.read()
+				}))
 			});
+		} catch (e) {
+			console.error(`[Proxy] ${req.method} ${req.url} → ${e}`);
+			if (!res.headersSent) {
+				const message = e instanceof Error ? e.message : String(e);
+				res.writeHead(502, { "content-type": "text/plain; charset=utf-8" });
+				res.end(`Bad Gateway — the local preview could not reach ${theme.company}.fluid.app: ${message}\nThis is the dev machine's network path to Fluid, not the theme. Common causes: TLS-inspecting security software (its root CA is in the OS keychain, which Node does not read — set NODE_EXTRA_CA_CERTS to its certificate), DNS, or a proxy. The same error is logged by the theme dev server process.`);
+			}
+		}
+	});
+	await new Promise((resolve, reject) => {
+		server.once("error", (err) => {
+			if (err.code === "EADDRINUSE" || err.code === "EACCES") {
+				console.error(formatPortConflictMessage(opts.host, opts.port));
+				process.exit(1);
+			}
+			reject(err);
 		});
-	}
-};
-/**
-* Content-type check the pull command uses to decide whether a file
-* is safe to run through `merge3` (line-based) or must fall back to
-* whole-file "either/or" resolution (binary).
-*/
-function looksBinary(content) {
-	return content.subarray(0, Math.min(content.length, 8e3)).includes(0);
+		server.listen(opts.port, opts.host, () => resolve());
+	});
+	const address = `http://${opts.host}:${opts.port}`;
+	onReady?.(address);
+	return function stop() {
+		sse.close();
+		stopWatcher();
+		server.close();
+	};
 }
-/** Best-effort readFile that returns null when the file does not exist. */
-function readIfExists(path) {
-	try {
-		return readFileSync(path);
-	} catch {
-		return null;
-	}
+//#endregion
+//#region src/theme-picker.ts
+const PAGE_SIZE = 50;
+const LOAD_MORE_VALUE = -1;
+function themeLabel(t) {
+	const active = t.status === "active" ? ` ${chalk.green("[active]")}` : "";
+	return `${t.name} (#${t.id})${active}`;
 }
-/**
-* Parse the numeric theme id from `.fluid-theme/theme-id`. Returns
-* null when the file is missing or the contents don't parse cleanly;
-* `open` treats that as "unknown theme" and rebuilds the shadow.
-*/
-function readStoredThemeId(themeIdFile) {
-	try {
-		const stored = parseInt(readFileSync(themeIdFile, "utf-8").trim(), 10);
-		return Number.isFinite(stored) ? stored : null;
-	} catch {
-		return null;
-	}
+function themeChoices(themeList, hasMore) {
+	const choices = themeList.map((t) => ({
+		title: themeLabel(t),
+		value: t.id
+	}));
+	if (hasMore) choices.push({
+		title: chalk.dim(`── Load more themes ──`),
+		value: LOAD_MORE_VALUE
+	});
+	return choices;
 }
-/**
-* Append `.fluid-theme/` to the theme root's `.gitignore` when the
-* theme dir sits inside a git working tree and the entry isn't
-* already there. Skipped when the user isn't in a git repo — no
-* point manufacturing a `.gitignore` for someone who doesn't use
-* git. Idempotent — a second call is a no-op.
-*/
-async function ensureRootGitignoreHidesShadow(themeRoot) {
-	if (!await new Promise((resolve) => {
-		const child = spawn("git", ["rev-parse", "--is-inside-work-tree"], {
-			cwd: themeRoot,
-			stdio: [
-				"ignore",
-				"pipe",
-				"pipe"
-			]
-		});
-		child.on("close", (code) => resolve(code === 0));
-		child.on("error", () => resolve(false));
-	})) return;
-	const gitignorePath = join(themeRoot, ".gitignore");
-	let existing = "";
-	try {
-		existing = readFileSync(gitignorePath, "utf-8");
-	} catch {
-		existing = "";
-	}
-	const lines = existing.split("\n").map((line) => line.trim());
-	if (lines.includes(".fluid-theme/") || lines.includes(".fluid-theme")) return;
-	const separator = existing.length === 0 || existing.endsWith("\n") ? "" : "\n";
-	writeFileSync(gitignorePath, `${existing}${separator}.fluid-theme/\n`, "utf-8");
+async function fetchThemesPage(api, page, searchQuery) {
+	const body = await listApplicationThemes(api, {
+		per_page: PAGE_SIZE,
+		page,
+		...searchQuery ? { search_query: searchQuery } : {}
+	});
+	return {
+		themes: body.application_themes ?? [],
+		hasMore: page < (body.meta?.total_pages ?? 1)
+	};
 }
-//#endregion
-//#region src/theme/merge-push.ts
-/**
-* Compute what changed locally since the last time the shadow repo
-* committed a state. Replaces the sha256 `checksums` map: shadow HEAD
-* is the source of truth for "what the CLI last saw the server have".
-*
-* Files whose local bytes are byte-identical to their HEAD blob are
-* skipped; anything else — new, modified, or a locally-deleted path
-* that HEAD still has — is included.
-*/
-async function diffAgainstShadow(themeRoot, shadow) {
-	const changed = [];
-	const deleted = [];
-	const localFiles = themeRoot.files();
-	const localByKey = /* @__PURE__ */ new Map();
-	const assetManifest = new ThemeAssetManifest(themeRoot.root);
-	for (const file of localFiles) {
-		if (!file.exists) continue;
-		localByKey.set(file.relativePath, file);
-		const headBlob = await shadow.blobAtHead(file.relativePath);
-		const localBuf = file.isText ? Buffer.from(file.read()) : file.readBinary();
-		if (headBlob && headBlob.equals(localBuf)) continue;
-		changed.push(file);
-	}
-	if (await shadow.hasHead()) for (const key of await listHeadPaths(shadow)) {
-		if (localByKey.has(key)) continue;
-		if (themeRoot.ignore.ignore(key)) continue;
-		if (assetManifest.has(key)) continue;
-		if (isStylesheetKey(key)) continue;
-		deleted.push(key);
+async function selectTheme(api, message) {
+	const allThemes = [];
+	let page = 1;
+	let hasMore = true;
+	let initialIndex = 0;
+	let searchQuery = "";
+	let searchResults = [];
+	while (true) {
+		if (hasMore && allThemes.length < page * PAGE_SIZE) {
+			const result = await fetchThemesPage(api, page);
+			allThemes.push(...result.themes);
+			hasMore = result.hasMore;
+		}
+		if (!allThemes.length) {
+			console.error("No themes found.");
+			process.exit(1);
+		}
+		const choices = themeChoices(allThemes, hasMore);
+		const { id } = await prompts({
+			type: "autocomplete",
+			name: "id",
+			message,
+			initial: initialIndex,
+			choices,
+			suggest: async (input, choices) => {
+				if (!input) {
+					searchQuery = "";
+					searchResults = [];
+					return choices;
+				}
+				if (input !== searchQuery) {
+					searchQuery = input;
+					try {
+						searchResults = (await fetchThemesPage(api, 1, input)).themes;
+					} catch {
+						searchResults = [];
+					}
+				}
+				return searchResults.map((t) => ({
+					title: themeLabel(t),
+					value: t.id
+				}));
+			}
+		}, { onCancel: () => process.exit(130) });
+		if (id === LOAD_MORE_VALUE) {
+			initialIndex = allThemes.length;
+			page++;
+			continue;
+		}
+		if (!id) {
+			console.error("No theme selected.");
+			process.exit(1);
+		}
+		const found = allThemes.find((t) => t.id === id) ?? searchResults.find((t) => t.id === id);
+		if (found) return found;
+		return (await getApplicationTheme(api, id)).application_theme;
 	}
-	return {
-		changed,
-		deleted
-	};
 }
-/**
-* Read every path recorded under HEAD's tree. Used to detect local
-* deletions (paths in HEAD, absent from the working tree). Implemented
-* with `git ls-tree -r HEAD --name-only` piped through the shadow
-* repo's plumbing.
-*/
-async function listHeadPaths(shadow) {
-	return shadow.headPaths();
+async function findTheme(api, identifier) {
+	const idNum = Number(identifier);
+	if (Number.isInteger(idNum) && idNum > 0) try {
+		const body = await getApplicationTheme(api, idNum);
+		if (body.application_theme) return body.application_theme;
+	} catch {}
+	let page = 1;
+	let hasMore = true;
+	while (hasMore) {
+		const result = await fetchThemesPage(api, page, identifier);
+		const found = result.themes.find((t) => t.name.toLowerCase() === identifier.toLowerCase());
+		if (found) return found;
+		hasMore = result.hasMore;
+		page++;
+	}
+	console.error(`No theme found with identifier: ${identifier}`);
+	process.exit(1);
 }
+//#endregion
+//#region src/workspace.ts
+const WORKSPACE_FILE = ".fluid-workspace.json";
 /**
-* Refuse a push when any working file still contains a conflict marker
-* from a previous pull. Mirrors git's "you have unresolved conflicts;
-* fix them and re-run" behavior — the whole point of writing markers
-* on pull was to hand resolution to the user, so we can't send them
-* upstream.
+* Walk up from `startDir` looking for `.fluid-workspace.json`.
+* Returns the workspace info if found, or `null` if not in a workspace.
 */
-function findUnresolvedConflicts(files) {
-	const flagged = [];
-	for (const file of files) {
-		if (!file.isText) continue;
-		const buf = readIfExists(file.absolutePath);
-		if (!buf) continue;
-		if (containsConflictMarker(buf)) flagged.push(file.relativePath);
+function findWorkspace(startDir) {
+	let dir = resolve(startDir ?? process.cwd());
+	while (true) {
+		const candidate = join(dir, WORKSPACE_FILE);
+		if (existsSync(candidate)) try {
+			const raw = readFileSync(candidate, "utf-8");
+			const config = JSON.parse(raw);
+			return {
+				root: dir,
+				config
+			};
+		} catch {
+			return null;
+		}
+		const parent = dirname(dir);
+		if (parent === dir) break;
+		dir = parent;
 	}
-	return flagged;
+	return null;
 }
 /**
-* Stable, machine-readable one-liner for non-interactive callers
-* (Mist Desktop's publish flow parses push output). Uploading marker-
-* bearing files to a live theme is never acceptable, so `--auto-
-* baseline` pushes still refuse — but they emit this line so the
-* desktop can surface WHICH files block the publish instead of a
-* dead-end wall of prose. Format:
+* If cwd is already inside `{workspace}/local/{company}/...`, return that
+* theme root directory. Otherwise return null.
 *
-*   FLUID_THEME_PUSH_BLOCKED code=conflict_markers files=a.liquid,b.json
+* Examples (workspace root = /code/fluid-theme-dev):
+*   cwd = /code/fluid-theme-dev/local/acme-co           → /code/fluid-theme-dev/local/acme-co
+*   cwd = /code/fluid-theme-dev/local/acme-co/templates  → /code/fluid-theme-dev/local/acme-co
+*   cwd = /code/fluid-theme-dev                          → null
+*   cwd = /code/fluid-theme-dev/local                    → null
 */
-function conflictMarkerBlockLine(files) {
-	return `FLUID_THEME_PUSH_BLOCKED code=conflict_markers files=${files.join(",")}`;
+function resolveThemeRootFromCwd(workspace) {
+	const cwd = resolve(process.cwd());
+	const localDir = join(workspace.root, "local");
+	const rel = relative(localDir, cwd);
+	if (rel.startsWith("..") || rel === ".") return null;
+	const firstSegment = rel.split(sep)[0];
+	if (!firstSegment) return null;
+	return join(localDir, firstSegment);
 }
-const CONFLICT_START = Buffer.from("<<<<<<<");
-const CONFLICT_MID = Buffer.from("=======");
-const CONFLICT_END = Buffer.from(">>>>>>>");
+//#endregion
+//#region src/commands/dev.ts
 /**
-* A file counts as unresolved when it contains all three marker
-* shapes: `<<<<<<<`, `=======`, and `>>>>>>>`. Requiring all three
-* avoids false positives — a line of equals signs alone (e.g. inside
-* an ASCII table in a template comment) doesn't trip the guard.
+* Return the state needed to trust the source shadow for a dev sync.
+*
+* All three values must still describe the same world: the checkout has not
+* pulled a newer source, the dev theme has not changed outside this CLI, and
+* managed ImageKit references have not changed outside the shadow's file tree.
 */
-function containsConflictMarker(buf) {
-	return buf.includes(CONFLICT_START) && buf.includes(CONFLICT_MID) && buf.includes(CONFLICT_END);
+function devShadowTrust(config, devTheme, assetManifestSha) {
+	if (!config?.baseSha || !devTheme?.remoteSha || !devTheme.sourceBaseSha || !devTheme.assetManifestSha) return null;
+	if (devTheme.sourceThemeId !== config.themeId) return null;
+	if (devTheme.sourceBaseSha !== config.baseSha) return null;
+	if (devTheme.assetManifestSha !== assetManifestSha) return null;
+	return {
+		sourceThemeId: config.themeId,
+		remoteSha: devTheme.remoteSha
+	};
 }
 /**
-* Commit the current working-tree state to shadow HEAD after a
-* successful push. Ensures the next pull's merge base is the state
-* we know the server just accepted.
+* Create the isolated theme used by `theme dev`.
+*
+* A checkout from `theme pull` has a source theme id. New servers clone that
+* source by reference, preserving its DAM/ImageKit assets without moving
+* bytes. A 404/405 keeps older deployments compatible with the established
+* empty-theme flow; other failures must remain visible to the developer.
 */
-async function commitPushedState(themeRoot, shadow, message) {
-	const entries = [];
-	const assetManifest = new ThemeAssetManifest(themeRoot.root);
-	const localKeys = /* @__PURE__ */ new Set();
-	for (const file of themeRoot.files()) {
-		if (!file.exists) continue;
-		localKeys.add(file.relativePath);
-		const buf = file.isText ? Buffer.from(file.read()) : file.readBinary();
-		entries.push({
-			path: file.relativePath,
-			sha: await shadow.writeBlob(buf)
-		});
+async function createDevelopmentTheme(api, sourceThemeId, name) {
+	if (sourceThemeId !== void 0) try {
+		return (await cloneApplicationThemeForDevelopment(api, sourceThemeId, { application_theme: { name } })).application_theme;
+	} catch (error) {
+		if (!isApiError(error) || error.status !== 404 && error.status !== 405) throw error;
+		console.warn("Server-side theme cloning is unavailable; falling back to an empty development theme. The first sync may take longer.");
 	}
-	let managedAssetSentinelSha;
-	for (const key of assetManifest.keys()) {
-		if (localKeys.has(key)) continue;
-		managedAssetSentinelSha ??= await shadow.writeBlob(MANAGED_ASSET_SHADOW_SENTINEL);
-		entries.push({
-			path: key,
-			sha: managedAssetSentinelSha
-		});
+	return (await createApplicationTheme(api, { application_theme: {
+		name,
+		status: "development"
+	} })).application_theme;
+}
+async function ensureDevTheme(api, projectKey, identifier, sourceThemeId, sourceBaseSha, sourceAssetManifestSha) {
+	if (identifier) {
+		const theme = await findTheme(api, identifier);
+		setLastDevThemeId(theme.id);
+		return theme;
 	}
-	if (entries.length > 0 || await shadow.hasHead()) await shadow.commitState(entries, message);
+	const stored = getDevTheme(projectKey);
+	if (stored && stored.sourceThemeId === sourceThemeId) {
+		try {
+			const existing = (await getApplicationTheme(api, stored.id)).application_theme;
+			if (existing && existing.status === "development") {
+				console.log(`Using existing dev theme #${existing.id}`);
+				setDevTheme(projectKey, {
+					...stored,
+					id: existing.id,
+					name: existing.name,
+					...sourceThemeId === void 0 ? {} : { sourceThemeId }
+				});
+				return existing;
+			}
+		} catch {}
+		clearDevTheme(projectKey);
+	}
+	const { hostname } = await import("node:os");
+	const theme = await createDevelopmentTheme(api, sourceThemeId, `Development (${hostname().split(".")[0] ?? "dev"}-${Math.random().toString(36).slice(2, 8)})`.slice(0, 50));
+	setDevTheme(projectKey, {
+		id: theme.id,
+		name: theme.name,
+		...sourceThemeId === void 0 ? {} : { sourceThemeId },
+		...sourceThemeId !== void 0 && sourceBaseSha ? {
+			sourceBaseSha,
+			remoteSha: sourceBaseSha
+		} : {},
+		...sourceAssetManifestSha ? { assetManifestSha: sourceAssetManifestSha } : {}
+	});
+	console.log(`Created dev theme: ${theme.name} (#${theme.id})`);
+	return theme;
 }
-/**
-* A target can already have every URL-backed FileResource (for example from a
-* reference clone), while this checkout's manifest still names its old source
-* theme. Adopt the target and clear any legacy binary from shadow even though
-* no remote write was necessary.
-*/
-async function finalizeManifestOnlyPush(syncer, themeRoot, shadow) {
-	syncer.repointManagedAssetsToCurrentTheme();
-	await commitPushedState(themeRoot, shadow, `push @ ${(/* @__PURE__ */ new Date()).toISOString()}`);
+function createDevCommand() {
+	return new Command("dev").description("Start the theme dev server with hot reload").option("--host <host>", "Local server host", "127.0.0.1").option("--port <port>", "Local server port", "9292").option("-t, --theme <name-or-id>", "Use an existing theme instead of dev theme").option("-f, --force", "Skip schema validation on upload").option("--live-reload <mode>", "Reload mode: full-page | off", "full-page").option("--navigate", "Open browser navigator after server starts").option("--root <path>", "Theme root directory", ".").action(async (opts) => {
+		requireToken();
+		let rootPath = opts.root;
+		if (rootPath === ".") {
+			const workspace = findWorkspace();
+			if (workspace) rootPath = resolveThemeRootFromCwd(workspace) ?? rootPath;
+		}
+		const themeRoot = new ThemeRoot(rootPath);
+		if (!themeRoot.isValid()) {
+			console.error(`'${rootPath}' does not look like a theme directory.`);
+			process.exit(1);
+		}
+		const port = Number(opts.port);
+		if (!Number.isInteger(port) || port < 1 || port > 65535) {
+			console.error(`Invalid port: '${opts.port}'. Must be an integer between 1 and 65535.`);
+			process.exit(1);
+		}
+		try {
+			await checkPortAvailable(opts.host, port);
+		} catch (e) {
+			if (e instanceof PortInUseError) console.error(e.message);
+			else console.error(`Failed to check port availability: ${e}`);
+			process.exit(1);
+		}
+		const reloadMode = opts.liveReload === "off" ? "off" : "full-page";
+		const api = createApiClient();
+		const config = readThemeConfig(themeRoot.root);
+		let company;
+		if (config?.company) company = config.company;
+		else {
+			company = (await api.get("/api/company/v1/companies/me")).data?.company?.subdomain ?? "";
+			if (!company) {
+				console.error("Could not determine company subdomain. Make sure your token is valid.");
+				process.exit(1);
+			}
+		}
+		const projectKey = devThemeKey(company, themeRoot.root);
+		const theme = opts.theme ? await ensureDevTheme(api, projectKey, opts.theme) : await ensureDevTheme(api, projectKey, void 0, config?.themeId, config?.baseSha, config?.assetManifestSha);
+		const devTheme = opts.theme ? void 0 : getDevTheme(projectKey);
+		const assetManifest = new ThemeAssetManifest(themeRoot.root);
+		const trust = opts.theme ? null : devShadowTrust(config, devTheme, assetManifest.fingerprint());
+		let initialSync;
+		if (trust) {
+			const shadow = await ShadowRepo.open(themeRoot.root, trust.sourceThemeId);
+			if (await shadow.hasHead()) initialSync = {
+				shadow,
+				remoteSha: trust.remoteSha
+			};
+		}
+		let rememberRemoteSha;
+		if (!opts.theme && config?.baseSha && devTheme) {
+			const sourceBaseSha = config.baseSha;
+			let rememberedDevTheme = devTheme;
+			rememberRemoteSha = (remoteSha) => {
+				rememberedDevTheme = {
+					...rememberedDevTheme,
+					sourceBaseSha,
+					remoteSha,
+					assetManifestSha: new ThemeAssetManifest(themeRoot.root).fingerprint()
+				};
+				setDevTheme(projectKey, rememberedDevTheme);
+			};
+		}
+		const editorUrl = `https://admin.fluid.app/themes/${theme.id}/editor`;
+		let stop;
+		const cleanup = () => {
+			stop?.();
+			process.exit(0);
+		};
+		process.on("SIGINT", cleanup);
+		process.on("SIGTERM", cleanup);
+		stop = await startDevServer(api, {
+			id: theme.id,
+			name: theme.name,
+			company,
+			editorUrl
+		}, themeRoot, {
+			host: opts.host,
+			port,
+			reloadMode,
+			validate: !opts.force,
+			...initialSync ? { initialSync } : {},
+			...rememberRemoteSha ? { onRemoteSha: rememberRemoteSha } : {}
+		}, (address) => {
+			console.log(`\n  Dev server: ${address}`);
+			console.log(`  Web editor: ${editorUrl}`);
+			console.log("\n  Watching for file changes…\n");
+			if (opts.navigate) import("open").then((m) => m.default(`${address}/home`));
+		});
+		await new Promise(() => {});
+	});
 }
 //#endregion
 //#region src/theme/auto-baseline.ts
@@ -3917,7 +4010,8 @@ function createPushCommand() {
 					themeId: theme.id,
 					themeName: theme.name,
 					company: config.company,
-					baseSha: baseSha ?? void 0
+					baseSha: baseSha ?? void 0,
+					assetManifestSha: new ThemeAssetManifest(themeRoot.root).fingerprint({ excludePending: true })
 				});
 				return;
 			}
@@ -3929,7 +4023,8 @@ function createPushCommand() {
 					themeId: theme.id,
 					themeName: theme.name,
 					company: subdomain,
-					baseSha: baseSha ?? void 0
+					baseSha: baseSha ?? void 0,
+					assetManifestSha: new ThemeAssetManifest(themeRoot.root).fingerprint({ excludePending: true })
 				});
 			} catch {}
 		}
@@ -4252,7 +4347,8 @@ function createPullCommand() {
 			themeId: theme.id,
 			themeName: theme.name,
 			company: subdomain,
-			baseSha: remoteSha ?? existingConfig?.baseSha
+			baseSha: remoteSha ?? existingConfig?.baseSha,
+			assetManifestSha: new ThemeAssetManifest(absoluteRoot).fingerprint({ excludePending: true })
 		});
 		if (result.conflicts.length > 0) process.exit(1);
 	});