@fluid-app/fluid-cli-theme-dev 0.1.34 → 0.1.36

package/dist/index.mjs

@@ -1,15 +1,17 @@
 import { Command } from "commander";
 import { getAuthToken, readConfig, updateConfig } from "@fluid-app/fluid-cli";
-import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { cpSync, existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync } from "node:fs";
 import { basename, dirname, extname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { createHash } from "node:crypto";
 import http from "node:http";
 import https from "node:https";
 import chokidar from "chokidar";
+import net from "node:net";
 import chalk from "chalk";
 import prompts from "prompts";
 import ora from "ora";
-import { execFileSync } from "node:child_process";
+import { execFileSync, spawn } from "node:child_process";
+import { tmpdir } from "node:os";
 import { fileURLToPath } from "node:url";
 //#region ../../platform/api-client-core/src/fetch-client.ts
 /**
@@ -276,6 +278,21 @@ function readThemeConfig(themeRoot) {
 		return null;
 	}
 }
+/**
+* Read a legacy config (pre-shadow-repo). Used only by the migration
+* path on first new-CLI pull to seed shadow HEAD from files whose
+* local content still matches their stored sha256 checksum.
+*/
+function readLegacyThemeConfig(themeRoot) {
+	const path = configPath(themeRoot);
+	if (!existsSync(path)) return null;
+	try {
+		const raw = readFileSync(path, "utf-8");
+		return JSON.parse(raw);
+	} catch {
+		return null;
+	}
+}
 /** Write `.fluid-theme.json` to a theme directory. */
 function writeThemeConfig(themeRoot, config) {
 	writeFileSync(configPath(themeRoot), JSON.stringify(config, null, 2) + "\n", "utf-8");
@@ -1605,6 +1622,46 @@ var Syncer = class {
 	}
 };
 //#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";
+	}
+};
+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
 async function startDevServer(api, theme, themeRoot, opts, onReady) {
 	const sse = new SSEStream();
@@ -1673,8 +1730,14 @@ async function startDevServer(api, theme, themeRoot, opts, onReady) {
 		}
 	});
 	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());
-		server.on("error", reject);
 	});
 	const address = `http://${opts.host}:${opts.port}`;
 	onReady?.(address);
@@ -1889,6 +1952,13 @@ function createDevCommand() {
 			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);
@@ -1931,24 +2001,444 @@ function createDevCommand() {
 	});
 }
 //#endregion
-//#region src/commands/push.ts
+//#region src/theme/shadow-repo.ts
 /**
-* Detect files where the remote has changed since the last pull,
-* and we also have local changes (i.e. we'd overwrite someone else's work).
+* 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.
+*
+* 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/`.
+*
+* 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 detectRemoteDrift(storedChecksums, remoteChecksums, themeRoot) {
-	const conflicts = [];
-	for (const [key, storedChecksum] of Object.entries(storedChecksums)) {
-		const remoteChecksum = remoteChecksums[key];
-		if (remoteChecksum === void 0) continue;
-		if (remoteChecksum === storedChecksum) continue;
-		const file = themeRoot.file(key);
+var ShadowRepo = class ShadowRepo {
+	headExists = void 0;
+	constructor(themeRoot, gitDir) {
+		this.themeRoot = themeRoot;
+		this.gitDir = gitDir;
+	}
+	/**
+	* 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
+			});
+		}
+		const repo = new ShadowRepo(themeRoot, gitDir);
+		if (!existsSync(gitDir)) {
+			mkdirSync(shadowDir, { recursive: true });
+			await repo.git([
+				"init",
+				"--bare",
+				"-b",
+				"main",
+				gitDir
+			], { cwd: themeRoot });
+		}
+		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;
+		}
+		return this.headExists;
+	}
+	/**
+	* 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",
+			"HEAD",
+			"--name-only"
+		]);
+		return stdout.toString("utf8").split("\n").filter((line) => line.length > 0);
+	}
+	/**
+	* 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;
+		}
+	}
+	/**
+	* 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 {
+			for (const { path, sha } of files) await this.git([
+				"update-index",
+				"--add",
+				"--cacheinfo",
+				`100644,${sha},${path}`
+			], { 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 {}
+		}
+	}
+	/**
+	* 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.
+	*/
+	async merge3(base, local, remote) {
+		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);
+			try {
+				const { stdout } = await this.git([
+					"merge-file",
+					"-p",
+					"-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);
+				if (typeof e.code === "number" && e.code >= 1 && e.code <= 127 && merged.length > 0) return {
+					merged,
+					hasConflicts: true
+				};
+				throw err;
+			}
+		} finally {
+			try {
+				rmSync(dir, {
+					recursive: true,
+					force: true
+				});
+			} 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);
+				}
+			});
+		});
+	}
+};
+/**
+* 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);
+}
+/** Best-effort readFile that returns null when the file does not exist. */
+function readIfExists(path) {
+	try {
+		return readFileSync(path);
+	} catch {
+		return null;
+	}
+}
+/**
+* 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;
+	}
+}
+/**
+* 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");
+}
+//#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();
+	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 (isStylesheetKey(key)) continue;
+		deleted.push(key);
+	}
+	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);
+	}
+	return flagged;
+}
+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 = [];
+	for (const file of themeRoot.files()) {
 		if (!file.exists) continue;
-		if (file.checksum() === remoteChecksum) continue;
-		conflicts.push(key);
+		const buf = file.isText ? Buffer.from(file.read()) : file.readBinary();
+		entries.push({
+			path: file.relativePath,
+			sha: await shadow.writeBlob(buf)
+		});
 	}
-	return conflicts;
+	if (entries.length > 0) await shadow.commitState(entries, message);
 }
+//#endregion
+//#region src/commands/push.ts
 function createPushCommand() {
 	return new Command("push").description("Push local theme files to a remote theme").option("-t, --theme <name-or-id>", "Theme name or ID to push to").option("-n, --nodelete", "Do not delete remote files missing locally").option("-f, --force", "Skip schema validation and the server-side merge check").option("-p, --publish", "Publish the theme after pushing").option("-u, --unpublished", "Create a new unpublished theme and push to it").option("--root <path>", "Theme root directory", ".").action(async (opts) => {
 		requireToken();
@@ -1985,88 +2475,107 @@ function createPushCommand() {
 			console.log(`  Using theme from .fluid-theme.json: ${chalk.bold(config.themeName)} (#${config.themeId})`);
 			theme = (await getApplicationTheme(api, config.themeId)).application_theme;
 		} else theme = await selectTheme(api, "Select a theme to push to");
-		let overrideMergeCheck = false;
-		if (config?.checksums && !opts.force) {
-			const driftSpinner = ora("Checking for remote changes…").start();
-			const driftSyncer = new Syncer(api, theme.id, themeRoot);
-			await driftSyncer.fetchChecksums();
-			const remoteChecksums = driftSyncer.remoteChecksums();
-			const conflicts = detectRemoteDrift(config.checksums, remoteChecksums, themeRoot);
-			driftSpinner.stop();
-			if (conflicts.length > 0) {
-				console.log(chalk.yellow(`\n⚠ ${conflicts.length} file(s) changed on remote since last pull:\n`));
-				for (const key of conflicts) console.log(`  ${key}`);
-				console.log();
-				const { resolution } = await prompts({
-					type: "select",
-					name: "resolution",
-					message: "How do you want to handle this?",
-					choices: [
-						{
-							title: "Push anyway (overwrite remote changes)",
-							value: "push"
-						},
-						{
-							title: "Pull first, then push",
-							value: "pull-first"
-						},
-						{
-							title: "Abort",
-							value: "abort"
-						}
-					]
-				}, { onCancel: () => process.exit(130) });
-				if (resolution === "abort") {
-					console.log("Aborted.");
-					process.exit(0);
-				}
-				if (resolution === "pull-first") {
-					console.log(`Run ${chalk.cyan("fluid theme pull")} first, then push again.`);
-					process.exit(0);
-				}
-				if (resolution === "push") overrideMergeCheck = true;
-			}
+		const shadow = await ShadowRepo.open(themeRoot.root, theme.id);
+		const unresolved = findUnresolvedConflicts(themeRoot.files().filter((f) => f.exists));
+		if (unresolved.length > 0) {
+			console.log();
+			console.log(chalk.red(`✗ ${unresolved.length} file(s) still contain unresolved conflict markers:`));
+			for (const key of unresolved) console.log(`  ${key}`);
+			console.log();
+			console.log(`  Edit each file to reconcile the ${chalk.cyan("<<<<<<<")} / ${chalk.cyan(">>>>>>>")} sections,`);
+			console.log(`  then re-run ${chalk.cyan("fluid theme push")}.`);
+			console.log();
+			process.exit(1);
+		}
+		const { changed, deleted } = await diffAgainstShadow(themeRoot, shadow);
+		if (changed.length === 0 && deleted.length === 0) {
+			console.log("Nothing to push — local matches the last synced state.");
+			return;
 		}
-		const syncer = new Syncer(api, theme.id, themeRoot);
 		const spinner = ora(`Pushing to ${theme.name} (#${theme.id})…`).start();
-		const baseSha = opts.force || overrideMergeCheck ? null : config?.baseSha ?? null;
-		let result;
+		const syncer = new Syncer(api, theme.id, themeRoot);
+		const configMatchesTheme = config?.themeId === theme.id;
+		let baseSha = opts.force || !configMatchesTheme ? null : config?.baseSha ?? null;
+		if (!opts.force && !opts.unpublished && !baseSha) {
+			console.error();
+			console.error(chalk.red(`No local baseline for theme "${theme.name}" (#${theme.id}).`));
+			console.error();
+			console.error(`  Run ${chalk.cyan(`fluid theme pull -t ${theme.id}`)} first to sync down the current server state,`);
+			console.error(`  then push — this way you see what would change before it goes live.`);
+			console.error();
+			console.error(`  Or, if you know what you're doing and want to overwrite the server's current`);
+			console.error(`  contents wholesale, re-run with ${chalk.cyan("--force")}.`);
+			console.error();
+			process.exit(1);
+		}
 		try {
-			result = await syncer.uploadTheme({
-				delete: !opts.nodelete,
-				validate: !opts.force,
-				baseSha,
-				onProgress: (d, total) => {
-					spinner.text = `Pushing ${d}/${total} files…`;
-				}
-			});
+			await syncer.preflightPush(baseSha);
+			baseSha = syncer.remoteSha() ?? baseSha;
 		} catch (e) {
 			if (e instanceof PushConflictError) {
-				spinner.fail("Server has changed since your last pull. Push aborted.");
-				console.log();
-				console.log(`  ${chalk.cyan("Run `fluid theme pull` first")} to sync down the remote changes,`);
-				console.log(`  then push again. Use ${chalk.cyan("fluid theme push --force")} to overwrite anyway.`);
-				console.log();
+				renderPullFirst(spinner);
 				process.exit(1);
 			}
 			throw e;
 		}
-		if (result.validationFailed) {
-			spinner.fail(`Schema validation failed (${result.errors.length} error(s)). Use --force to skip.`);
-			for (const e of result.errors) console.error(`  ${e}`);
-			process.exit(1);
-		} else if (result.errors.length) {
-			spinner.warn(`Pushed with ${result.errors.length} error(s).`);
-			for (const e of result.errors) console.error(`  ${e}`);
-		} else spinner.succeed(`Pushed ${result.uploaded} file(s), deleted ${result.deleted} remote file(s).`);
-		if (config) {
-			const remoteSha = syncer.remoteSha();
-			writeThemeConfig(themeRoot.root, {
-				...config,
-				checksums: syncer.remoteChecksums(),
-				baseSha: remoteSha ?? config.baseSha
-			});
+		if (!opts.force) {
+			const errors = [];
+			for (const file of changed) {
+				if (!file.isLiquid) continue;
+				for (const d of file.validateSchema()) if (d.severity === "error") errors.push(`${file.relativePath}: ${d.message}`);
+			}
+			if (errors.length > 0) {
+				spinner.fail(`Schema validation failed (${errors.length} error(s)). Use --force to skip.`);
+				for (const err of errors) console.error(`  ${err}`);
+				process.exit(1);
+			}
+		}
+		let uploaded = 0;
+		let deletedCount = 0;
+		const errors = [];
+		let progress = 0;
+		const total = changed.length + (opts.nodelete ? 0 : deleted.length);
+		for (const file of changed) {
+			try {
+				await syncer.uploadFile(file, baseSha);
+				baseSha = syncer.remoteSha() ?? baseSha;
+				uploaded++;
+			} catch (e) {
+				if (e instanceof PushConflictError) {
+					spinner.stop();
+					renderPullFirst(ora());
+					process.exit(1);
+				}
+				errors.push(`Upload ${file.relativePath}: ${formatError(e)}`);
+			}
+			spinner.text = `Pushing ${++progress}/${total} files…`;
+		}
+		if (!opts.nodelete) for (const key of deleted) {
+			try {
+				await syncer.deleteRemoteFile(key, baseSha);
+				baseSha = syncer.remoteSha() ?? baseSha;
+				deletedCount++;
+			} catch (e) {
+				if (e instanceof PushConflictError) {
+					spinner.stop();
+					renderPullFirst(ora());
+					process.exit(1);
+				}
+				errors.push(`Delete ${key}: ${formatError(e)}`);
+			}
+			spinner.text = `Pushing ${++progress}/${total} files…`;
 		}
+		if (errors.length) {
+			spinner.warn(`Pushed with ${errors.length} error(s).`);
+			for (const err of errors) console.error(`  ${err}`);
+		} else spinner.succeed(`Pushed ${uploaded} file(s)` + (deletedCount > 0 ? `, deleted ${deletedCount} remote file(s).` : "."));
+		if (errors.length === 0) await commitPushedState(themeRoot, shadow, `push @ ${(/* @__PURE__ */ new Date()).toISOString()}`);
+		if (config) writeThemeConfig(themeRoot.root, {
+			themeId: theme.id,
+			themeName: theme.name,
+			company: config.company,
+			baseSha: baseSha ?? void 0
+		});
 		if (opts.publish) {
 			const pubSpinner = ora("Publishing theme…").start();
 			try {
@@ -2078,6 +2587,176 @@ function createPushCommand() {
 		}
 	});
 }
+function renderPullFirst(spinner) {
+	spinner.fail("Server has changed since your last pull. Push aborted.");
+	console.log();
+	console.log(`  ${chalk.cyan("Run `fluid theme pull` first")} to merge the remote changes,`);
+	console.log(`  then re-run push. Use ${chalk.cyan("fluid theme push --force")} to overwrite anyway.`);
+	console.log();
+}
+//#endregion
+//#region src/theme/merge-pull.ts
+/**
+* Reconcile the just-downloaded remote tree against the working tree,
+* using the shadow repo's HEAD as the merge base. Text files that
+* diverge on both sides get run through `git merge-file`; the result
+* — clean or with `<<<<<<<` markers — is written to disk. Binary
+* files fall back to "take remote" because there is no principled
+* three-way merge for them.
+*
+* HEAD advances to reflect the remote state we just materialized,
+* even when unresolved conflict markers remain in the working tree.
+* The user resolves markers in their editor and re-runs push; push
+* refuses to send files whose content still starts with a marker,
+* so a half-resolved push cannot silently ship broken content.
+*/
+async function mergePull(input) {
+	const { themeRoot, shadow, remote, fetchBinary, onProgress } = input;
+	const doDelete = input.delete;
+	const result = {
+		written: 0,
+		merged: 0,
+		conflicts: [],
+		deleted: 0,
+		skipped: 0,
+		errors: []
+	};
+	const remoteContent = /* @__PURE__ */ new Map();
+	const remoteKeys = /* @__PURE__ */ new Set();
+	let done = 0;
+	for (const resource of remote) {
+		remoteKeys.add(resource.key);
+		try {
+			const buf = await materialize(resource, fetchBinary);
+			if (buf) remoteContent.set(resource.key, buf);
+		} catch (e) {
+			result.errors.push(`Download ${resource.key}: ${errMsg(e)}`);
+		}
+		onProgress?.(++done, remote.length);
+	}
+	for (const [key, remoteBuf] of remoteContent) {
+		const file = themeRoot.file(key);
+		if (!file.absolutePath.startsWith(themeRoot.root + sep)) {
+			result.errors.push(`Reconcile ${key}: path traversal detected`);
+			continue;
+		}
+		if (input.force) {
+			file.write(remoteBuf);
+			result.written++;
+			continue;
+		}
+		const localBuf = readIfExists(file.absolutePath);
+		const baseBuf = await shadow.blobAtHead(key);
+		if (localBuf == null) {
+			file.write(remoteBuf);
+			result.written++;
+			continue;
+		}
+		if (localBuf.equals(remoteBuf)) {
+			result.skipped++;
+			continue;
+		}
+		if (baseBuf && localBuf.equals(baseBuf)) {
+			file.write(remoteBuf);
+			result.written++;
+			continue;
+		}
+		if (baseBuf && remoteBuf.equals(baseBuf)) {
+			result.skipped++;
+			continue;
+		}
+		if (looksBinary(localBuf) || looksBinary(remoteBuf) || (baseBuf ? looksBinary(baseBuf) : false)) {
+			file.write(remoteBuf);
+			result.conflicts.push(`${key} (binary — kept remote)`);
+			continue;
+		}
+		const { merged, hasConflicts } = await shadow.merge3(baseBuf, localBuf, remoteBuf);
+		file.write(merged);
+		if (hasConflicts) result.conflicts.push(key);
+		else result.merged++;
+	}
+	if (doDelete && await shadow.hasHead()) for (const file of themeRoot.files()) {
+		if (remoteKeys.has(file.relativePath)) continue;
+		if (isStylesheetKey(file.relativePath)) continue;
+		const baseBuf = await shadow.blobAtHead(file.relativePath);
+		if (!baseBuf) continue;
+		const localBuf = readIfExists(file.absolutePath);
+		if (!localBuf) continue;
+		if (!localBuf.equals(baseBuf)) continue;
+		try {
+			unlinkSync(file.absolutePath);
+			result.deleted++;
+		} catch {}
+	}
+	const commitEntries = [];
+	for (const [key, buf] of remoteContent) commitEntries.push({
+		path: key,
+		sha: await shadow.writeBlob(buf)
+	});
+	for (const key of remoteKeys) {
+		if (remoteContent.has(key)) continue;
+		const prevBlob = await shadow.blobAtHead(key);
+		if (prevBlob == null) continue;
+		commitEntries.push({
+			path: key,
+			sha: await shadow.writeBlob(prevBlob)
+		});
+	}
+	if (commitEntries.length > 0) await shadow.commitState(commitEntries, `pull @ ${(/* @__PURE__ */ new Date()).toISOString()}`);
+	return result;
+}
+async function materialize(resource, fetchBinary) {
+	if (resource.resource_type === "FileResource" && resource.url) return fetchBinary(resource.url);
+	if (resource.content == null) return null;
+	const text = typeof resource.content === "string" ? resource.content : JSON.stringify(resource.content);
+	return Buffer.from(text);
+}
+function errMsg(e) {
+	return e instanceof Error ? e.message : String(e);
+}
+//#endregion
+//#region src/theme/legacy-migration.ts
+/**
+* On first pull after upgrading from a checksum-era CLI, the shadow
+* repo starts with no HEAD. `mergePull` would then run every diverged
+* file through a null-base merge — even files the user never touched
+* locally — producing spurious `<<<<<<<` markers for every file the
+* server updated since the last pull.
+*
+* Recover a real merge base by trusting the legacy sha256 checksums:
+* any local file whose content still matches its stored checksum is
+* "unmodified since last pull" and can be committed as HEAD. Files
+* whose local sha256 diverges from the stored checksum stay
+* unseeded — we don't have their pre-modification content, so a
+* null-base merge (marker-first UX) is the honest fallback for them.
+*
+* Idempotent: no-op when HEAD already exists, when there is no
+* legacy config, when the config is for a different theme, or when
+* the checksums map is empty. Runs before `mergePull` so its base
+* lookups see the seeded tree.
+*/
+async function migrateLegacyChecksumsIntoShadow(input) {
+	const { shadow, themeRoot, absoluteRoot, themeId } = input;
+	if (await shadow.hasHead()) return;
+	const legacy = readLegacyThemeConfig(absoluteRoot);
+	if (!legacy) return;
+	if (legacy.themeId !== themeId) return;
+	if (!legacy.checksums || Object.keys(legacy.checksums).length === 0) return;
+	const seed = [];
+	for (const file of themeRoot.files()) {
+		if (!file.exists) continue;
+		const stored = legacy.checksums[file.relativePath];
+		if (!stored) continue;
+		if (file.checksum() !== stored) continue;
+		const content = file.isText ? Buffer.from(file.read()) : file.readBinary();
+		seed.push({
+			path: file.relativePath,
+			content
+		});
+	}
+	if (seed.length === 0) return;
+	await shadow.seedFromWorkingTree(seed, `migrate from checksum-era CLI @ ${(/* @__PURE__ */ new Date()).toISOString()}`);
+}
 //#endregion
 //#region src/commands/pull.ts
 async function fetchCompanySubdomain(api) {
@@ -2088,42 +2767,8 @@ async function fetchCompanySubdomain(api) {
 	}
 	return subdomain;
 }
-function formatRelativeTime(iso) {
-	const diff = Date.now() - new Date(iso).getTime();
-	const minutes = Math.floor(diff / 6e4);
-	if (minutes < 1) return "just now";
-	if (minutes < 60) return `${minutes}m ago`;
-	const hours = Math.floor(minutes / 60);
-	if (hours < 24) return `${hours}h ago`;
-	const days = Math.floor(hours / 24);
-	if (days === 1) return "yesterday";
-	return `${days}d ago (${new Date(iso).toLocaleDateString("en-US", {
-		month: "short",
-		day: "numeric",
-		year: "numeric"
-	})})`;
-}
-/**
-* Detect files where both local and remote have changed since the last pull.
-* Returns the set of conflicting resource keys.
-*/
-function detectConflicts(storedChecksums, remoteChecksums, themeRoot) {
-	const conflicts = [];
-	for (const [key, storedChecksum] of Object.entries(storedChecksums)) {
-		const remoteChecksum = remoteChecksums[key];
-		if (remoteChecksum === void 0) continue;
-		if (remoteChecksum === storedChecksum) continue;
-		const file = themeRoot.file(key);
-		if (!file.exists) continue;
-		const localChecksum = file.checksum();
-		if (localChecksum === storedChecksum) continue;
-		if (localChecksum === remoteChecksum) continue;
-		conflicts.push(key);
-	}
-	return conflicts;
-}
 function createPullCommand() {
-	return new Command("pull").description("Pull a remote theme to your local directory").option("-t, --theme <name-or-id>", "Theme name or ID to pull").option("-n, --nodelete", "Do not delete local files missing on remote").option("--root <path>", "Theme root directory").option("-y, --yes", "Skip confirmation prompt").option("-f, --force", "Overwrite local changes without prompting on conflicts").action(async (opts) => {
+	return new Command("pull").description("Pull a remote theme to your local directory").option("-t, --theme <name-or-id>", "Theme name or ID to pull").option("-n, --nodelete", "Do not delete local files missing on remote").option("--root <path>", "Theme root directory").option("-y, --yes", "Skip confirmation prompt").option("-f, --force", "Overwrite local without merging (skip conflict markers)").action(async (opts) => {
 		requireToken();
 		const api = createApiClient();
 		const workspace = findWorkspace();
@@ -2139,48 +2784,8 @@ function createPullCommand() {
 		console.log(`  Theme:   ${chalk.bold(theme.name)} (#${theme.id})`);
 		console.log(`  Company: ${chalk.bold(subdomain)}`);
 		console.log(`  Target:  ${chalk.bold(absoluteRoot)}`);
-		if (existingConfig?.lastPulledAt) console.log(`  Last pulled: ${formatRelativeTime(existingConfig.lastPulledAt)}`);
 		console.log();
-		const themeRoot = new ThemeRoot(root);
-		let skipKeys;
-		if (existingConfig?.checksums && !opts.force) {
-			const fetchSpinner = ora("Checking for conflicts…").start();
-			const syncer = new Syncer(api, theme.id, themeRoot);
-			await syncer.fetchChecksums();
-			const remoteChecksums = syncer.remoteChecksums();
-			const conflicts = detectConflicts(existingConfig.checksums, remoteChecksums, themeRoot);
-			fetchSpinner.stop();
-			if (conflicts.length > 0) {
-				console.log(chalk.yellow(`⚠ ${conflicts.length} conflict(s) detected:\n`));
-				for (const key of conflicts) console.log(`  ${key}`);
-				console.log();
-				const { resolution } = await prompts({
-					type: "select",
-					name: "resolution",
-					message: "How do you want to handle conflicts?",
-					choices: [
-						{
-							title: "Keep local (skip conflicting files)",
-							value: "keep-local"
-						},
-						{
-							title: "Use remote (overwrite local changes)",
-							value: "use-remote"
-						},
-						{
-							title: "Abort",
-							value: "abort"
-						}
-					]
-				}, { onCancel: () => process.exit(130) });
-				if (resolution === "abort") {
-					console.log("Aborted.");
-					process.exit(0);
-				}
-				if (resolution === "keep-local") skipKeys = new Set(conflicts);
-			}
-		}
-		if (!opts.yes && !skipKeys) {
+		if (!opts.yes) {
 			const { confirmed } = await prompts({
 				type: "confirm",
 				name: "confirmed",
@@ -2192,36 +2797,52 @@ function createPullCommand() {
 				process.exit(0);
 			}
 		}
+		const themeRoot = new ThemeRoot(root);
+		const shadow = await ShadowRepo.open(absoluteRoot, theme.id);
+		await migrateLegacyChecksumsIntoShadow({
+			shadow,
+			themeRoot,
+			absoluteRoot,
+			themeId: theme.id
+		});
 		const syncer = new Syncer(api, theme.id, themeRoot);
 		const spinner = ora(`Pulling ${theme.name} (#${theme.id})…`).start();
-		const result = await syncer.downloadTheme({
+		const result = await mergePull({
+			themeRoot,
+			shadow,
+			remote: await syncer.downloadAll(),
+			fetchBinary: (url) => syncer.downloadBinaryAsset(url),
 			delete: !opts.nodelete,
-			skip: skipKeys,
-			onProgress: (d, total) => {
-				spinner.text = `Downloading ${d}/${total} files…`;
+			force: opts.force ?? false,
+			onProgress: (done, total) => {
+				spinner.text = `Downloading ${done}/${total} files…`;
 			}
 		});
-		const newChecksums = syncer.remoteChecksums();
-		if (skipKeys && existingConfig?.checksums) for (const key of skipKeys) {
-			const oldChecksum = existingConfig.checksums[key];
-			if (oldChecksum) newChecksums[key] = oldChecksum;
-		}
+		const parts = [];
+		if (result.written > 0) parts.push(`wrote ${result.written} file(s)`);
+		if (result.merged > 0) parts.push(`merged ${result.merged} file(s) cleanly`);
+		if (result.deleted > 0) parts.push(`deleted ${result.deleted} local file(s)`);
+		if (result.skipped > 0) parts.push(`${result.skipped} already in sync`);
+		if (result.errors.length) {
+			spinner.warn(`Pulled with ${result.errors.length} error(s): ${parts.join(", ")}.`);
+			for (const e of result.errors) console.error(`  ${e}`);
+		} else if (result.conflicts.length > 0) {
+			spinner.warn(`${result.conflicts.length} conflict(s) — resolve markers before pushing: ${parts.join(", ")}.`);
+			console.log();
+			for (const c of result.conflicts) console.log(`  ${chalk.yellow("CONFLICT")} ${c}`);
+			console.log();
+			console.log(`  Edit each file above to reconcile the ${chalk.cyan("<<<<<<<")} / ${chalk.cyan(">>>>>>>")} markers,`);
+			console.log(`  then run ${chalk.cyan("fluid theme push")} once your resolution is in place.`);
+			console.log();
+		} else spinner.succeed(parts.join(", ") || "Already up to date.");
 		const remoteSha = syncer.remoteSha();
 		writeThemeConfig(absoluteRoot, {
 			themeId: theme.id,
 			themeName: theme.name,
 			company: subdomain,
-			lastPulledAt: (/* @__PURE__ */ new Date()).toISOString(),
-			checksums: newChecksums,
 			baseSha: remoteSha ?? existingConfig?.baseSha
 		});
-		const parts = [`Downloaded ${result.downloaded} file(s)`];
-		if (result.deleted > 0) parts.push(`deleted ${result.deleted} local file(s)`);
-		if (result.skipped > 0) parts.push(`skipped ${result.skipped} conflict(s)`);
-		if (result.errors.length) {
-			spinner.warn(`Pulled with ${result.errors.length} error(s).`);
-			for (const e of result.errors) console.error(`  ${e}`);
-		} else spinner.succeed(`${parts.join(", ")}.`);
+		if (result.conflicts.length > 0) process.exit(1);
 	});
 }
 //#endregion