@fluid-app/fluid-cli-theme-dev 0.1.55 → 0.1.56

package/dist/index.mjs

@@ -1,6 +1,6 @@
 import { Command } from "commander";
 import { getAuthToken, gitSyncActorFromMe, gitSyncCommitSubject, readConfig, resolveGitSyncActor, summarizeChanges, updateConfig } from "@fluid-app/fluid-cli";
-import { cpSync, existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import { cpSync, existsSync, lstatSync, 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, randomBytes } from "node:crypto";
 import http from "node:http";
@@ -285,10 +285,16 @@ function createFetchClient(config) {
 function getApiBase() {
 	return process.env["FLUID_API_BASE"] ?? "https://api.fluid.app";
 }
+let backgroundGate = Promise.resolve();
+async function backgroundToken(tokenOverride) {
+	backgroundGate = backgroundGate.then(() => new Promise((resolve) => setTimeout(resolve, 1e3)));
+	await backgroundGate;
+	return tokenOverride ?? getAuthToken() ?? null;
+}
 function createApiClient(tokenOverride) {
 	return createFetchClient({
 		baseUrl: getApiBase(),
-		getAuthToken: () => tokenOverride ?? getAuthToken() ?? null
+		getAuthToken: () => process.env["FLUID_BACKGROUND_SYNC"] === "1" ? backgroundToken(tokenOverride) : tokenOverride ?? getAuthToken() ?? null
 	});
 }
 function requireToken() {
@@ -1455,6 +1461,75 @@ function watchTheme(root, handler) {
 	return () => watcher.close();
 }
 //#endregion
+//#region src/theme/background-pull-guard.ts
+const METADATA = [
+	".fluid-assets.json",
+	".fluid-theme.json",
+	".fluidignore"
+];
+var BackgroundPullChangedError = class extends Error {
+	constructor() {
+		super("Local files changed during background pull; remaining updates skipped.");
+	}
+};
+/** Keep the preflight snapshot across asynchronous download/merge work. Each
+* mutation checks its original bytes synchronously and records only our writes.
+* This prevents an edit made after preflight from becoming a merge input or
+* being overwritten by a deferred write, asset cleanup, or metadata update. */
+var BackgroundPullGuard = class {
+	root;
+	expected;
+	constructor(root) {
+		this.root = resolve(root);
+		this.expected = this.snapshot();
+	}
+	assertUnchanged() {
+		const current = this.snapshot();
+		for (const key of new Set([...current.keys(), ...this.expected.keys()])) if ((current.get(key) ?? null) !== (this.expected.get(key) ?? null)) throw new BackgroundPullChangedError();
+	}
+	mutate(keys, action) {
+		for (const key of keys) if (this.fingerprint(key) !== (this.expected.get(key) ?? null)) throw new BackgroundPullChangedError();
+		action();
+		for (const key of keys) this.expected.set(key, this.fingerprint(key));
+	}
+	fingerprint(key) {
+		const path = resolve(this.root, key);
+		if (!path.startsWith(this.root + sep)) throw new BackgroundPullChangedError();
+		for (let cursor = path;; cursor = dirname(cursor)) {
+			try {
+				if (lstatSync(cursor).isSymbolicLink()) throw new BackgroundPullChangedError();
+			} catch (error) {
+				if (!(typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT")) throw error;
+			}
+			if (cursor === this.root) break;
+		}
+		try {
+			return createHash("sha256").update(readFileSync(path)).digest("hex");
+		} catch (error) {
+			if (typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT") return null;
+			throw error;
+		}
+	}
+	snapshot() {
+		const result = /* @__PURE__ */ new Map();
+		const visit = (directory) => {
+			for (const entry of readdirSync(directory, { withFileTypes: true })) {
+				if (entry.name.startsWith(".") || entry.name === "node_modules") continue;
+				if (entry.isSymbolicLink()) throw new BackgroundPullChangedError();
+				const path = join(directory, entry.name);
+				if (entry.isDirectory()) visit(path);
+				else {
+					const key = relative(this.root, path).split(sep).join("/");
+					result.set(key, this.fingerprint(key));
+				}
+			}
+		};
+		visit(this.root);
+		for (const key of METADATA) result.set(key, this.fingerprint(key));
+		return result;
+	}
+};
+//#endregion
 //#region src/theme/case-collisions.ts
 var CaseCollisionError = class extends Error {
 	constructor(collisions) {
@@ -2228,6 +2303,7 @@ var Syncer = class {
 			try {
 				assetMetadata = await this.fetchThemeAssetMetadata(this.themeId);
 			} catch (error) {
+				if (error instanceof BackgroundPullChangedError) throw error;
 				errors.push(`Read remote asset metadata: ${formatError(error)}`);
 				for (const resource of resourcesNeedingMetadata) if (resource.key) unresolvedMetadataKeys.add(resource.key);
 			}
@@ -2238,6 +2314,7 @@ var Syncer = class {
 				errors.push(`Could not find usable metadata for ${key} in theme #${this.themeId}`);
 			}
 		}
+		opts.backgroundGuard?.assertUnchanged();
 		for (const resource of resources) {
 			const key = resource.key;
 			if (!key) continue;
@@ -2277,6 +2354,7 @@ var Syncer = class {
 				managedKeys.add(key);
 				filesToRemove.set(key, file);
 			} catch (error) {
+				if (error instanceof BackgroundPullChangedError) throw error;
 				errors.push(`Externalize ${key}: ${formatError(error)}`);
 			}
 		}
@@ -2286,8 +2364,10 @@ var Syncer = class {
 			manifestChanged = true;
 		}
 		if (manifestChanged) try {
-			this.assetManifest.write();
+			if (opts.backgroundGuard) opts.backgroundGuard.mutate([".fluid-assets.json"], () => this.assetManifest.write());
+			else this.assetManifest.write();
 		} catch (error) {
+			if (error instanceof BackgroundPullChangedError) throw error;
 			errors.push(`Persist remote asset manifest: ${formatError(error)}`);
 			for (const key of changedManifestKeys) managedKeys.delete(key);
 			return {
@@ -2298,9 +2378,11 @@ var Syncer = class {
 		}
 		let linked = 0;
 		for (const [key, file] of filesToRemove) try {
-			if (file.exists) unlinkSync(file.absolutePath);
+			if (file.exists) if (opts.backgroundGuard) opts.backgroundGuard.mutate([key], () => unlinkSync(file.absolutePath));
+			else unlinkSync(file.absolutePath);
 			linked++;
 		} catch (error) {
+			if (error instanceof BackgroundPullChangedError) throw error;
 			errors.push(`Externalize ${key}: ${formatError(error)}`);
 		}
 		return {
@@ -3137,6 +3219,17 @@ var ShadowRepo = class ShadowRepo {
 		}
 		return this.headExists;
 	}
+	/** Desktop snapshots deliberately use a different author. They are local
+	* recovery points, not proof that those bytes were synced to the server. */
+	async hasSyncedHead() {
+		if (!await this.hasHead()) return false;
+		const { stdout } = await this.git([
+			"log",
+			"-1",
+			"--format=%ae"
+		]);
+		return stdout.toString("utf8").trim() === "cli@fluid.app";
+	}
 	/**
 	* Every path recorded under HEAD's tree, recursively. Callers use
 	* this to detect local deletions (paths in HEAD, absent from the
@@ -4280,6 +4373,38 @@ function renderPullFirst(spinner) {
 	console.log();
 }
 //#endregion
+//#region src/theme/background-pull.ts
+function containsSymlink(directory) {
+	return readdirSync(directory, { withFileTypes: true }).some((entry) => {
+		if (entry.name.startsWith(".") || entry.name === "node_modules") return false;
+		return entry.isSymbolicLink() || entry.isDirectory() && containsSymlink(join(directory, entry.name));
+	});
+}
+/** Fail closed for unattended updates. Desktop snapshots can advance shadow
+* HEAD with local work, so only a CLI sync baseline is eligible. */
+async function canPullThemeInBackground(root, themeId) {
+	try {
+		if (containsSymlink(root)) return false;
+		const config = readThemeConfig(root);
+		if (!config || config.themeId !== themeId || !existsSync(join(root, ".fluid-theme", "repo", "HEAD"))) return false;
+		if (readFileSync(join(root, ".fluid-theme", "theme-id"), "utf8").trim() !== String(themeId)) return false;
+		const manifestPath = join(root, ".fluid-assets.json");
+		if (existsSync(manifestPath)) {
+			const raw = JSON.parse(readFileSync(manifestPath, "utf8"));
+			if (!raw || typeof raw !== "object" || !("version" in raw) || raw.version !== 1 || !("assets" in raw) || !raw.assets || typeof raw.assets !== "object" || Array.isArray(raw.assets)) return false;
+			const manifest = new ThemeAssetManifest(root);
+			if (manifest.entries().some(([, link]) => link.pending)) return false;
+			if (!config.assetManifestSha || config.assetManifestSha !== manifest.fingerprint()) return false;
+		} else if (config.assetManifestSha && config.assetManifestSha !== new ThemeAssetManifest(root).fingerprint()) return false;
+		const shadow = await ShadowRepo.open(root, themeId);
+		if (!await shadow.hasSyncedHead()) return false;
+		const diff = await diffAgainstShadow(new ThemeRoot(root), shadow);
+		return diff.changed.length === 0 && diff.deleted.length === 0;
+	} catch {
+		return false;
+	}
+}
+//#endregion
 //#region src/theme/merge-pull.ts
 /** `write(..., RESOLVES_CONFLICT)`: this write is the chosen side of a conflict. */
 const RESOLVES_CONFLICT = true;
@@ -4321,9 +4446,11 @@ async function mergePull(input) {
 	const unwrittenKeys = /* @__PURE__ */ new Set();
 	const tryWrite = (key, file, content) => {
 		try {
-			file.write(content);
+			if (input.backgroundGuard) input.backgroundGuard.mutate([key], () => file.write(content));
+			else file.write(content);
 			return true;
 		} catch (e) {
+			if (e instanceof BackgroundPullChangedError) throw e;
 			unwrittenKeys.add(key);
 			result.errors.push(`Reconcile ${key}: ${errMsg(e)}. ${RENAME_REMEDY}`);
 			return false;
@@ -4366,6 +4493,7 @@ async function mergePull(input) {
 		}
 		onProgress?.(++done, remote.length);
 	}
+	input.backgroundGuard?.assertUnchanged();
 	for (const [key, remoteBuf] of remoteContent) {
 		const file = themeRoot.file(key);
 		if (!file.absolutePath.startsWith(themeRoot.root + sep)) {
@@ -4422,6 +4550,7 @@ async function mergePull(input) {
 	}
 	if (input.resolve) {
 		if (pendingWrites.some((w) => w.resolvesConflict)) await commitPushedState(themeRoot, shadow, syncCommitSubject("Snapshot before pull", input.actor ?? null));
+		input.backgroundGuard?.assertUnchanged();
 		for (const { key, file, content, record } of pendingWrites) if (tryWrite(key, file, content)) record();
 	}
 	if (doDelete && await shadow.hasHead()) for (const file of themeRoot.files()) {
@@ -4433,9 +4562,12 @@ async function mergePull(input) {
 		if (!localBuf) continue;
 		if (!localBuf.equals(baseBuf)) continue;
 		try {
-			unlinkSync(file.absolutePath);
+			if (input.backgroundGuard) input.backgroundGuard.mutate([file.relativePath], () => unlinkSync(file.absolutePath));
+			else unlinkSync(file.absolutePath);
 			result.deleted++;
-		} catch {}
+		} catch (error) {
+			if (error instanceof BackgroundPullChangedError) throw error;
+		}
 	}
 	const commitEntries = [];
 	for (const [key, buf] of remoteContent) {
@@ -4465,7 +4597,10 @@ async function mergePull(input) {
 			sha: managedAssetSentinelSha
 		});
 	}
-	if (commitEntries.length > 0 || remoteKeys.size === 0 && await shadow.hasHead()) await shadow.commitState(commitEntries, syncCommitSubject("Pull", input.actor ?? null));
+	if (commitEntries.length > 0 || remoteKeys.size === 0 && await shadow.hasHead()) {
+		input.backgroundGuard?.assertUnchanged();
+		await shadow.commitState(commitEntries, syncCommitSubject("Pull", input.actor ?? null));
+	}
 	return result;
 }
 function hasGeneratedConflictMarkers(content) {
@@ -4492,101 +4627,127 @@ async function fetchCompanySubdomain(api) {
 	return subdomain;
 }
 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 without merging (skip conflict markers)").option("--resolve <side>", "Auto-resolve merge conflicts to one side instead of writing conflict markers: 'local' keeps your files' hunks, 'remote' takes the server's (for non-interactive use)").action(async (opts) => {
-		requireToken();
-		if (opts.resolve !== void 0 && opts.resolve !== "local" && opts.resolve !== "remote") {
-			console.error(`Invalid --resolve value "${opts.resolve}" — use "local" or "remote".`);
-			process.exit(1);
-		}
-		const resolveSide = opts.resolve;
-		const api = createApiClient();
-		const workspace = findWorkspace();
-		const theme = opts.theme ? await findTheme(api, opts.theme) : await selectTheme(api, "Select a theme to pull");
-		const subdomain = await fetchCompanySubdomain(api);
-		let root;
-		if (opts.root) root = opts.root;
-		else if (workspace) root = resolveThemeRootFromCwd(workspace) ?? join(workspace.root, "local", subdomain);
-		else root = `.`;
-		const absoluteRoot = resolve(root);
-		const existingConfig = readThemeConfig(absoluteRoot);
-		console.log();
-		console.log(`  Theme:   ${chalk.bold(theme.name)} (#${theme.id})`);
-		console.log(`  Company: ${chalk.bold(subdomain)}`);
-		console.log(`  Target:  ${chalk.bold(absoluteRoot)}`);
-		console.log();
-		if (!opts.yes) {
-			const { confirmed } = await prompts({
-				type: "confirm",
-				name: "confirmed",
-				message: "Pull theme to this directory?",
-				initial: true
-			}, { onCancel: () => process.exit(130) });
-			if (!confirmed) {
-				console.log("Aborted.");
-				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 actorPromise = fetchSyncActor(api);
-		const spinner = ora(`Pulling ${theme.name} (#${theme.id})…`).start();
-		const resources = await syncer.downloadAll().catch((error) => {
-			if (!(error instanceof CaseCollisionError)) throw error;
-			spinner.fail(error.message);
-			process.exit(1);
-		});
-		const externalizedAssets = await syncer.externalizePulledAssets(resources, { delete: !opts.nodelete });
-		const result = await mergePull({
-			themeRoot,
-			shadow,
-			remote: resources,
-			fetchBinary: (url) => syncer.downloadBinaryAsset(url),
-			delete: !opts.nodelete,
-			force: opts.force ?? false,
-			skipRemoteKeys: externalizedAssets.managedKeys,
-			resolve: resolveSide,
-			actor: await actorPromise,
-			onProgress: (done, total) => {
-				spinner.text = `Downloading ${done}/${total} files…`;
+	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("--only-if-clean", "Skip with exit code 3 when local work cannot be proven synced").option("-f, --force", "Overwrite local without merging (skip conflict markers)").option("--resolve <side>", "Auto-resolve merge conflicts to one side instead of writing conflict markers: 'local' keeps your files' hunks, 'remote' takes the server's (for non-interactive use)").action(async (opts) => {
+		let spinner;
+		try {
+			requireToken();
+			if (opts.resolve !== void 0 && opts.resolve !== "local" && opts.resolve !== "remote") {
+				console.error(`Invalid --resolve value "${opts.resolve}" — use "local" or "remote".`);
+				process.exit(1);
 			}
-		});
-		result.errors.push(...externalizedAssets.errors);
-		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 (externalizedAssets.linked > 0) parts.push(`kept ${externalizedAssets.linked} binary asset(s) remote`);
-		if (result.autoResolved.length > 0) parts.push(`auto-resolved ${result.autoResolved.length} conflict(s) (kept ${resolveSide})`);
-		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}`);
-			process.exitCode = 1;
-		} 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}`);
+			const resolveSide = opts.resolve;
+			const api = createApiClient();
+			const workspace = findWorkspace();
+			const theme = opts.theme ? await findTheme(api, opts.theme) : await selectTheme(api, "Select a theme to pull");
+			const subdomain = await fetchCompanySubdomain(api);
+			let root;
+			if (opts.root) root = opts.root;
+			else if (workspace) root = resolveThemeRootFromCwd(workspace) ?? join(workspace.root, "local", subdomain);
+			else root = `.`;
+			const absoluteRoot = resolve(root);
+			const existingConfig = readThemeConfig(absoluteRoot);
+			const backgroundGuard = opts.onlyIfClean ? new BackgroundPullGuard(absoluteRoot) : void 0;
 			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(`  Theme:   ${chalk.bold(theme.name)} (#${theme.id})`);
+			console.log(`  Company: ${chalk.bold(subdomain)}`);
+			console.log(`  Target:  ${chalk.bold(absoluteRoot)}`);
 			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,
-			baseSha: remoteSha ?? existingConfig?.baseSha,
-			assetManifestSha: new ThemeAssetManifest(absoluteRoot).fingerprint({ excludePending: true })
-		});
-		if (result.conflicts.length > 0) process.exit(1);
+			if (!opts.yes) {
+				const { confirmed } = await prompts({
+					type: "confirm",
+					name: "confirmed",
+					message: "Pull theme to this directory?",
+					initial: true
+				}, { onCancel: () => process.exit(130) });
+				if (!confirmed) {
+					console.log("Aborted.");
+					process.exit(0);
+				}
+			}
+			if (opts.onlyIfClean && !await canPullThemeInBackground(absoluteRoot, theme.id)) {
+				console.log("Skipped: local changes or an unknown sync baseline.");
+				process.exit(3);
+			}
+			backgroundGuard?.assertUnchanged();
+			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 actorPromise = fetchSyncActor(api);
+			spinner = ora(`Pulling ${theme.name} (#${theme.id})…`).start();
+			const resources = await syncer.downloadAll().catch((error) => {
+				if (!(error instanceof CaseCollisionError)) throw error;
+				if (spinner) spinner.fail(error.message);
+				process.exit(1);
+			});
+			if (opts.onlyIfClean && !await canPullThemeInBackground(absoluteRoot, theme.id)) {
+				spinner.stop();
+				console.log("Skipped: local files changed while downloading.");
+				process.exit(3);
+			}
+			const externalizedAssets = await syncer.externalizePulledAssets(resources, {
+				delete: !opts.nodelete,
+				backgroundGuard
+			});
+			const result = await mergePull({
+				themeRoot,
+				shadow,
+				backgroundGuard,
+				remote: resources,
+				fetchBinary: (url) => syncer.downloadBinaryAsset(url),
+				delete: !opts.nodelete,
+				force: opts.force ?? false,
+				skipRemoteKeys: externalizedAssets.managedKeys,
+				resolve: resolveSide,
+				actor: await actorPromise,
+				onProgress: (done, total) => {
+					if (spinner) spinner.text = `Downloading ${done}/${total} files…`;
+				}
+			});
+			result.errors.push(...externalizedAssets.errors);
+			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 (externalizedAssets.linked > 0) parts.push(`kept ${externalizedAssets.linked} binary asset(s) remote`);
+			if (result.autoResolved.length > 0) parts.push(`auto-resolved ${result.autoResolved.length} conflict(s) (kept ${resolveSide})`);
+			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}`);
+				process.exitCode = 1;
+			} 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();
+			backgroundGuard?.assertUnchanged();
+			const updateConfig = () => writeThemeConfig(absoluteRoot, {
+				themeId: theme.id,
+				themeName: theme.name,
+				company: subdomain,
+				baseSha: remoteSha ?? existingConfig?.baseSha,
+				assetManifestSha: new ThemeAssetManifest(absoluteRoot).fingerprint({ excludePending: true })
+			});
+			if (backgroundGuard) backgroundGuard.mutate([".fluid-theme.json"], updateConfig);
+			else updateConfig();
+			if (result.conflicts.length > 0) process.exit(1);
+		} catch (error) {
+			if (!(error instanceof BackgroundPullChangedError)) throw error;
+			spinner?.stop();
+			console.log(error.message);
+			process.exitCode = 3;
+		}
 	});
 }
 //#endregion