kintone-migrator 0.34.4 → 0.34.6

package/dist/index.mjs

@@ -10,6 +10,7 @@ import { realpathSync } from "node:fs";
 import * as v from "valibot";
 import * as p from "@clack/prompts";
 import pc from "picocolors";
+import { createHash } from "node:crypto";
 //#region src/lib/error.ts
 var AnyError = class extends Error {
 	constructor(message, cause) {
@@ -2739,6 +2740,7 @@ function printThreeWayDiffResult(result, printTwoWay) {
 		printTwoWay(result.diff);
 		return;
 	}
+	for (const note of result.notes ?? []) p.log.warn(note);
 	if (result.isEmpty) {
 		p.log.info("No changes detected (local, remote, and base are in sync).");
 		return;
@@ -3443,7 +3445,7 @@ function resolveActionMerge(merge, resolution) {
 * record-keyed merge (view / report / action / plugin). The caller supplies a
 * `label` extractor (e.g. the view's name) for display.
 */
-function buildRecordThreeWayDiff(merge, label, extras = []) {
+function buildRecordThreeWayDiff(merge, label, extras = [], notes = []) {
 	const localChanges = [];
 	const remoteDrift = [];
 	const conflicts = [];
@@ -3471,13 +3473,15 @@ function buildRecordThreeWayDiff(merge, label, extras = []) {
 			break;
 		default: break;
 	}
+	const isEmpty = localChanges.length === 0 && remoteDrift.length === 0 && conflicts.length === 0 && extras.length === 0;
 	return {
 		mode: "three-way",
 		localChanges,
 		remoteDrift,
 		conflicts,
 		extras,
-		isEmpty: localChanges.length === 0 && remoteDrift.length === 0 && conflicts.length === 0 && extras.length === 0
+		...notes.length > 0 ? { notes } : {},
+		isEmpty
 	};
 }
 /**
@@ -3606,7 +3610,7 @@ async function saveSnapshotState(storage, codec, serialize, snapshot) {
 * Loads the base snapshot, the base app revision, the local config, and the
 * remote config in parallel for a 3-way sync. Generic over the snapshot
 * (`TSnapshot`) and remote (`TRemote`) shapes so every config domain reuses one
-* loader (generalization of schema step1's `loadThreeWayInputs`).
+* loader.
 */
 async function loadThreeWayInputs$1(args) {
 	const [state, appRevision, local, remote] = await Promise.all([
@@ -3980,9 +3984,13 @@ function buildDriftMessage(pullCommand) {
 * The CLI distinguishes this snapshot drift from API optimistic-lock (TOCTOU)
 * conflicts by the `ConfigDrift` code, not by the message string, so the
 * message stays a free-form, domain-specific hint.
+*
+* `extraHint` appends a domain-specific caveat (e.g. customization's "this
+* drift may be inferred") on its own line; omitted, the message is unchanged.
 */
-function buildDriftConflict(pullCommand) {
-	return new ConflictError(ConflictErrorCode.ConfigDrift, buildDriftMessage(pullCommand));
+function buildDriftConflict(pullCommand, extraHint) {
+	const message = buildDriftMessage(pullCommand);
+	return new ConflictError(ConflictErrorCode.ConfigDrift, extraHint === void 0 ? message : `${message}\n${extraHint}`);
 }
 //#endregion
 //#region src/core/application/action/pushAction.ts
@@ -10398,36 +10406,284 @@ function createCliCaptureContainers(input) {
 }
 //#endregion
 //#region src/core/domain/customization/services/configSerializer.ts
-function serializeResource(resource) {
-	if (resource.type === "FILE") return {
+function serializeResource(resource, platform, category, decorate) {
+	const serialized = resource.type === "FILE" ? {
 		type: "FILE",
 		path: resource.path
-	};
-	return {
+	} : {
 		type: "URL",
 		url: resource.url
 	};
+	const extra = decorate?.(platform, category, resource);
+	return extra === void 0 ? serialized : {
+		...extra,
+		...serialized
+	};
 }
-function serializeResourceList(resources) {
-	return resources.map(serializeResource);
+function serializeResourceList(resources, platform, category, decorate) {
+	return resources.map((resource) => serializeResource(resource, platform, category, decorate));
 }
 function hasPlatformResources(platform) {
 	return platform.js.length > 0 || platform.css.length > 0;
 }
-function serializePlatform(platform) {
+function serializePlatform(platform, platformName, decorate) {
 	return {
-		...platform.js.length > 0 ? { js: serializeResourceList(platform.js) } : {},
-		...platform.css.length > 0 ? { css: serializeResourceList(platform.css) } : {}
+		...platform.js.length > 0 ? { js: serializeResourceList(platform.js, platformName, "js", decorate) } : {},
+		...platform.css.length > 0 ? { css: serializeResourceList(platform.css, platformName, "css", decorate) } : {}
 	};
 }
-const CustomizationConfigSerializer = { serialize: (config) => {
+const CustomizationConfigSerializer = { serialize: (config, decorate) => {
 	return {
 		...config.scope !== void 0 ? { scope: config.scope } : {},
-		...hasPlatformResources(config.desktop) ? { desktop: serializePlatform(config.desktop) } : {},
-		...hasPlatformResources(config.mobile) ? { mobile: serializePlatform(config.mobile) } : {}
+		...hasPlatformResources(config.desktop) ? { desktop: serializePlatform(config.desktop, "desktop", decorate) } : {},
+		...hasPlatformResources(config.mobile) ? { mobile: serializePlatform(config.mobile, "mobile", decorate) } : {}
 	};
 } };
 //#endregion
+//#region src/core/domain/customization/services/customizationMerge.ts
+/**
+* Per-side placeholder for "no content digest for this key". Distinct per side
+* so an untracked key never compares equal across sides by accident.
+*/
+const UNTRACKED = {
+	base: "untracked:base",
+	local: "untracked:local",
+	remote: "untracked:remote"
+};
+/**
+* The bucket space every walk over a customization config must agree on.
+*
+* Shared rather than redeclared per module: the merge keys, the snapshot's
+* digest keys and the locally/remotely computed digest keys are only comparable
+* while they enumerate the same buckets, and a bucket missing from one walk
+* would not be a type error — it would silently leave digests unrecorded and
+* degrade the classification to an estimate.
+*/
+const PLATFORMS = ["desktop", "mobile"];
+const CATEGORIES = ["js", "css"];
+/**
+* The merge key holding the customization scope rather than a resource.
+*
+* Exported so every consumer branches on the same literal: the CLI's conflict
+* prompt tells scope conflicts and file conflicts apart by this key alone, and a
+* private copy drifting from this one would describe overwriting a file that
+* does not exist.
+*/
+const SCOPE_KEY = "config:scope";
+/**
+* Bucket-qualified resource identity: `platform:category:name`. Shared with the
+* force/firstTime pull path (`preservePaths`) so path preservation matches the
+* merge on the same identity and cross-bucket same-basename files stay distinct.
+*
+* The bucket parameters are the bucket types rather than `string` so a typo or a
+* stale literal at a call site is a compile error instead of a key nobody ever
+* looks up.
+*/
+function resourceKey(platform, category, name) {
+	return `${platform}:${category}:${name}`;
+}
+/**
+* The {@link resourceKey} of a remote FILE, from the name kintone reports.
+*
+* The remote name is normalized exactly like a local declared path, because the
+* remote config the merge is built from carries `file.name` as its `path`: a
+* name containing `/` becomes its trailing segment there, and a lookup keyed by
+* the raw name would miss the very entry it describes.
+*/
+function remoteFileResourceKey(platform, category, fileName) {
+	return resourceKey(platform, category, resourceName({
+		type: "FILE",
+		path: fileName
+	}));
+}
+/**
+* Walks every (platform, category) bucket, tagging each resource with the bucket
+* it belongs to. Generic over the resource so the local config, the raw remote
+* shape and a merged config are all walked by the same code.
+*
+* Key-producing walks over a typed config go through here: a hand-written
+* enumeration that misses a bucket is not a type error, and the symptom —
+* digests silently left unrecorded, downloads silently skipped — surfaces far
+* from the cause. Walks over raw `unknown` data (the state parser) cannot be
+* typed as {@link BucketedResources} and instead iterate {@link PLATFORMS} and
+* {@link CATEGORIES} directly, which keeps them on the same bucket space.
+*/
+function* walkCustomizationBuckets(resources) {
+	for (const platform of PLATFORMS) for (const category of CATEGORIES) for (const resource of resources[platform][category]) yield {
+		platform,
+		category,
+		resource
+	};
+}
+function platformList(config, platform, category) {
+	const p = config[platform];
+	return category === "js" ? p.js : p.css;
+}
+/**
+* Builds the per-side map keyed by `platform:category:name`. A FILE's tag is its
+* content digest for this side, falling back to the side's untracked sentinel so
+* an unknown content never compares equal to another side's unknown content.
+*/
+function toMap(config, tags, side) {
+	const map = /* @__PURE__ */ new Map();
+	for (const { platform, category, resource } of walkCustomizationBuckets(config)) {
+		const key = resourceKey(platform, category, resourceName(resource));
+		const tag = resource.type === "FILE" ? `FILE:${tags.get(key) ?? UNTRACKED[side]}` : "URL";
+		map.set(key, {
+			resource,
+			tag
+		});
+	}
+	const scope = config.scope ?? "ALL";
+	map.set(SCOPE_KEY, { scope });
+	return map;
+}
+/** The `resourceKey` set of every FILE resource in a config. */
+function fileResourceKeys(config) {
+	const keys = /* @__PURE__ */ new Set();
+	for (const { platform, category, resource } of walkCustomizationBuckets(config)) if (resource.type === "FILE") keys.add(resourceKey(platform, category, resourceName(resource)));
+	return keys;
+}
+function isScopeValue(v) {
+	return "scope" in v;
+}
+function eq(a, b) {
+	if (isScopeValue(a) || isScopeValue(b)) return isScopeValue(a) && isScopeValue(b) && a.scope === b.scope;
+	return a.tag === b.tag;
+}
+/**
+* Computes the resource-key-keyed 3-way merge of base/local/remote customization.
+*
+* `tags` carries each side's FILE content tokens (digests, or the base tags
+* produced by {@link resolveBaseFileDigests}). A key whose base tag equals the
+* local tag but not the remote tag is `remoteOnly`, and vice versa — so editing
+* a file locally is a local change, not a conflict.
+*/
+function computeCustomizationThreeWayMerge(base, local, remote, tags) {
+	return classifyThreeWay(toMap(base, tags.base, "base"), toMap(local, tags.local, "local"), toMap(remote, tags.remote, "remote"), eq);
+}
+/**
+* Determines the base-side comparison tag of every FILE key in the base
+* snapshot, filling in the keys whose digest was never recorded.
+*
+* Rules, highest priority first:
+*
+* 1. a recorded digest wins — the classification is exact;
+* 2. otherwise, for a legacy state (no digest at all) whose app revision has not
+*    moved, the remote digest is assumed to still be the base content, so a
+*    purely local edit is `localOnly` instead of a spurious conflict;
+* 3. otherwise, when the key exists on exactly one side, the base takes that
+*    side's tag, so the classification is decided by existence alone;
+* 4. otherwise, when both sides carry the same tag, the base takes it
+*    (`unchanged`);
+* 5. otherwise the base gets its own sentinel — both sides diverged
+*    (`conflict`), or the key exists on neither side (`bothSame`).
+*
+* Rules 3-5 decide from the two sides alone, which is all a snapshot without
+* digests allows.
+*/
+function resolveBaseFileDigests(baseConfig, baseDigests, localDigests, remoteDigests, options) {
+	const tags = /* @__PURE__ */ new Map();
+	const optimistic = /* @__PURE__ */ new Set();
+	const conservative = /* @__PURE__ */ new Set();
+	for (const key of fileResourceKeys(baseConfig)) {
+		const recorded = baseDigests.get(key);
+		if (recorded !== void 0) {
+			tags.set(key, recorded);
+			continue;
+		}
+		const inLocal = options.localKeys.has(key);
+		const inRemote = options.remoteKeys.has(key);
+		const classifiable = inLocal || inRemote;
+		const remoteDigest = remoteDigests.get(key);
+		if (options.legacyState && options.remoteUnchanged && remoteDigest !== void 0) {
+			tags.set(key, remoteDigest);
+			if (classifiable) optimistic.add(key);
+			continue;
+		}
+		const localTag = localDigests.get(key) ?? UNTRACKED.local;
+		const remoteTag = remoteDigest ?? UNTRACKED.remote;
+		if (inLocal !== inRemote) tags.set(key, inLocal ? localTag : remoteTag);
+		else if (inLocal && localTag === remoteTag) tags.set(key, localTag);
+		else tags.set(key, UNTRACKED.base);
+		if (classifiable) conservative.add(key);
+	}
+	return {
+		tags,
+		estimatedKeys: {
+			optimistic,
+			conservative
+		}
+	};
+}
+/**
+* Applies a resolved 3-way merge, returning the merged customization config.
+*
+* Auto-merged entries take their `merged` value; conflicts take the chosen
+* side. The resulting resources are flattened back into per-platform js/css
+* lists, preserving the order they appear in the chosen/merged side. Throws a
+* BusinessRuleError when a conflict is left unresolved (programmer invariant).
+*/
+function resolveCustomizationMerge(merge, resolution, local, remote) {
+	const chosen = /* @__PURE__ */ new Map();
+	let scope = "ALL";
+	for (const entry of merge.entries) {
+		let value;
+		if (entry.change.kind === "conflict") {
+			const choice = resolution.get(entry.key);
+			if (choice === void 0) throw new BusinessRuleError(CustomizationErrorCode.CzUnresolvedConflict, `Unresolved conflict for "${entry.key}"`);
+			value = choice === "local" ? entry.local : entry.remote;
+		} else value = entry.merged;
+		if (value === void 0) continue;
+		if (isScopeValue(value)) scope = value.scope;
+		else chosen.set(entry.key, value.resource);
+	}
+	return rebuild(chosen, scope, local, remote);
+}
+/**
+* Rebuilds the config from the chosen resource keys, ordering each bucket by the
+* resource's position in local first, then any remote-only resources, so the
+* resulting list is stable and matches the user's local ordering intent.
+*
+* `path` is a local-owned concern (the build-output location) that is orthogonal
+* to which content wins the merge: whenever a key exists locally, the local
+* resource (its declared path) is kept regardless of the chosen content side.
+* Only remote-only keys fall back to the chosen (remote/basename) resource.
+*/
+function rebuild(chosen, scope, local, remote) {
+	function bucket(platform, category) {
+		const seen = /* @__PURE__ */ new Set();
+		const out = [];
+		const localByKey = /* @__PURE__ */ new Map();
+		for (const resource of platformList(local, platform, category)) localByKey.set(resourceKey(platform, category, resourceName(resource)), resource);
+		const append = (resources) => {
+			for (const resource of resources) {
+				const key = resourceKey(platform, category, resourceName(resource));
+				if (seen.has(key)) continue;
+				const picked = chosen.get(key);
+				if (picked !== void 0) {
+					out.push(localByKey.get(key) ?? picked);
+					seen.add(key);
+				}
+			}
+		};
+		append(platformList(local, platform, category));
+		append(platformList(remote, platform, category));
+		return out;
+	}
+	return {
+		scope,
+		desktop: {
+			js: bucket("desktop", "js"),
+			css: bucket("desktop", "css")
+		},
+		mobile: {
+			js: bucket("mobile", "js"),
+			css: bucket("mobile", "css")
+		}
+	};
+}
+//#endregion
 //#region src/lib/deduplicateName.ts
 const DEFAULT_MAX_COUNTER = 1e4;
 /**
@@ -10475,8 +10731,6 @@ function sanitizeFileName(name) {
 * Unlike {@link deduplicateName} from `@/lib/deduplicateName`, this function is
 * file-name-aware: it inserts the counter before the extension (e.g. `file_1.js`)
 * rather than appending it at the end (which would produce `file.js_1`).
-* This extension-aware behavior cannot be achieved by the generic lib utility,
-* so a local implementation is necessary.
 */
 function deduplicateFileName(baseName, usedNames) {
 	if (!usedNames.has(baseName)) {
@@ -10500,7 +10754,7 @@ function usedStemsFor(usedNames, ext) {
 	for (const name of usedNames) if (name.endsWith(ext)) stems.add(name.slice(0, name.length - ext.length));
 	return stems;
 }
-function planResources(resources, platformDir, resourceType, relativeBaseDir) {
+function planResources(resources, platformName, platformDir, resourceType, relativeBaseDir, contentBase, preservePaths) {
 	const planned = [];
 	const filesToDownload = [];
 	const dir = join(platformDir, resourceType);
@@ -10511,28 +10765,42 @@ function planResources(resources, platformDir, resourceType, relativeBaseDir) {
 	});
 	else {
 		const fileName = deduplicateFileName(sanitizeFileName(resource.file.name), usedNames);
-		const absolutePath = join(dir, fileName);
-		const relativePath = join(relativeBaseDir, resourceType, fileName);
-		planned.push({
-			type: "FILE",
-			path: relativePath
-		});
-		filesToDownload.push({
-			fileName,
-			fileKey: resource.file.fileKey,
-			absolutePath
-		});
+		const declaredPath = preservePaths?.get(remoteFileResourceKey(platformName, resourceType, resource.file.name));
+		if (declaredPath !== void 0) {
+			planned.push({
+				type: "FILE",
+				path: declaredPath
+			});
+			filesToDownload.push({
+				fileName,
+				fileKey: resource.file.fileKey,
+				absolutePath: resolve(contentBase, declaredPath)
+			});
+		} else {
+			const absolutePath = join(dir, fileName);
+			const relativePath = join(relativeBaseDir, resourceType, fileName);
+			planned.push({
+				type: "FILE",
+				path: relativePath
+			});
+			filesToDownload.push({
+				fileName,
+				fileKey: resource.file.fileKey,
+				absolutePath
+			});
+		}
 	}
 	return {
 		resources: planned,
 		filesToDownload
 	};
 }
-function planPlatform(remotePlatform, platformName, basePath, filePrefix) {
-	const platformDir = join(basePath, filePrefix, platformName);
+function planPlatform(remotePlatform, platformName, basePath, filePrefix, preservePaths) {
+	const contentBase = join(basePath, filePrefix);
+	const platformDir = join(contentBase, platformName);
 	const platformPrefix = platformName;
-	const jsPlan = planResources(remotePlatform.js, platformDir, "js", platformPrefix);
-	const cssPlan = planResources(remotePlatform.css, platformDir, "css", platformPrefix);
+	const jsPlan = planResources(remotePlatform.js, platformName, platformDir, "js", platformPrefix, contentBase, preservePaths);
+	const cssPlan = planResources(remotePlatform.css, platformName, platformDir, "css", platformPrefix, contentBase, preservePaths);
 	const fileCount = remotePlatform.js.filter((r) => r.type === "FILE").length + remotePlatform.css.filter((r) => r.type === "FILE").length;
 	return {
 		platform: {
@@ -10560,8 +10828,8 @@ async function downloadFiles(files, container) {
 async function captureCustomization({ container, input }) {
 	const existing = await container.customizationStorage.get();
 	const { scope, desktop, mobile } = await container.customizationConfigurator.getCustomization();
-	const desktopPlan = planPlatform(desktop, "desktop", input.basePath, input.filePrefix);
-	const mobilePlan = planPlatform(mobile, "mobile", input.basePath, input.filePrefix);
+	const desktopPlan = planPlatform(desktop, "desktop", input.basePath, input.filePrefix, input.preservePaths);
+	const mobilePlan = planPlatform(mobile, "mobile", input.basePath, input.filePrefix, input.preservePaths);
 	const config = {
 		scope,
 		desktop: desktopPlan.platform,
@@ -10571,6 +10839,7 @@ async function captureCustomization({ container, input }) {
 	await downloadFiles([...desktopPlan.filesToDownload, ...mobilePlan.filesToDownload], container);
 	return {
 		configText,
+		config,
 		hasExistingConfig: existing.exists,
 		fileResourceCount: desktopPlan.fileCount + mobilePlan.fileCount
 	};
@@ -11565,115 +11834,214 @@ var apply_default$9 = define({
 	}
 });
 //#endregion
-//#region src/core/domain/customization/services/customizationMerge.ts
-const PLATFORMS = ["desktop", "mobile"];
-const CATEGORIES = ["js", "css"];
-const SCOPE_KEY = "config:scope";
-function resourceKey(platform, category, name) {
-	return `${platform}:${category}:${name}`;
+//#region src/lib/contentDigest.ts
+const PREFIX = "sha256:";
+const DIGEST_PATTERN = /^sha256:[0-9a-f]{64}$/;
+/**
+* Computes the digest of raw bytes.
+*
+* The bytes are hashed as-is: no newline / BOM / trailing-newline normalization.
+* kintone stores the uploaded byte sequence verbatim, so normalizing here would
+* report "no changes" for content that actually changes once uploaded. A
+* zero-byte input is a normal input and yields the sha256 of the empty string,
+* so "no digest recorded" stays distinguishable from "the content is empty".
+*/
+function computeContentDigest(data) {
+	const bytes = data instanceof Uint8Array ? data : new Uint8Array(data);
+	return `${PREFIX}${createHash("sha256").update(bytes).digest("hex")}`;
 }
-function platformList(config, platform, category) {
-	const p = config[platform];
-	return category === "js" ? p.js : p.css;
+/**
+* Narrows an untrusted value (e.g. a parsed state file) to a {@link ContentDigest}.
+*
+* The full `sha256:<64 lowercase hex chars>` shape is enforced, not just the
+* prefix: state files are hand-editable, and a truncated or otherwise malformed
+* digest would be adopted as a comparison token and silently report the remote
+* as changed. Every value {@link computeContentDigest} produces matches.
+*/
+function isContentDigest(value) {
+	return typeof value === "string" && DIGEST_PATTERN.test(value);
 }
+//#endregion
+//#region src/core/application/customization/customizationDigests.ts
 /**
-* Builds the per-side map keyed by `platform:category:name`. `contentTag`
-* returns the content marker for a same-name FILE so divergent content surfaces
-* as a conflict. `side` distinguishes local vs remote tags for modified files.
+* Digests the given local FILE resources.
+*
+* Paths resolve with `resolve(basePath, path)` — the same resolution push
+* uploads from and pull writes downloads to — so the digest always describes the
+* bytes that actually travel to kintone, including when an absolute path is
+* declared.
+*
+* `keys` restricts the read to the resource keys the caller needs; keys whose
+* body cannot be read are simply absent from the result (see
+* {@link readLocalDigest}).
 */
-function toMap(config, contentTag) {
-	const map = /* @__PURE__ */ new Map();
-	for (const platform of PLATFORMS) for (const category of CATEGORIES) for (const resource of platformList(config, platform, category)) {
-		const name = resourceName(resource);
-		const tag = resource.type === "FILE" ? `FILE:${contentTag(name)}` : "URL";
-		map.set(resourceKey(platform, category, name), {
-			resource,
-			tag
+async function computeFileDigests(config, basePath, reader, keys) {
+	return digestLocalFiles(config, basePath, reader, keys);
+}
+/**
+* Digests every local FILE resource of a config about to be persisted as the new
+* base snapshot. Same path resolution and same failure handling as
+* {@link computeFileDigests}; unreadable files stay untracked in the snapshot.
+*/
+async function computeSnapshotFileDigests(config, basePath, reader) {
+	return digestLocalFiles(config, basePath, reader, void 0);
+}
+async function digestLocalFiles(config, basePath, reader, keys) {
+	const targets = [];
+	for (const { platform, category, resource } of walkCustomizationBuckets(config)) {
+		if (resource.type !== "FILE") continue;
+		const key = resourceKey(platform, category, resourceName(resource));
+		if (keys !== void 0 && !keys.has(key)) continue;
+		targets.push({
+			key,
+			absolutePath: resolve(basePath, resource.path)
 		});
 	}
-	const scope = config.scope ?? "ALL";
-	map.set(SCOPE_KEY, { scope });
-	return map;
-}
-function isScopeValue(v) {
-	return "scope" in v;
-}
-function eq(a, b) {
-	if (isScopeValue(a) || isScopeValue(b)) return isScopeValue(a) && isScopeValue(b) && a.scope === b.scope;
-	return a.tag === b.tag;
+	const results = await Promise.all(targets.map(async ({ key, absolutePath }) => ({
+		key,
+		digest: await readLocalDigest(reader, absolutePath)
+	})));
+	const digests = /* @__PURE__ */ new Map();
+	for (const { key, digest } of results) if (digest !== void 0) digests.set(key, digest);
+	return digests;
 }
 /**
-* Computes the file-name-keyed 3-way merge of base/local/remote customization.
+* Reads and digests one local file, or reports "unknown" when it cannot be read.
 *
-* `modifiedFileNames` is the set of same-name FILE basenames whose local
-* content differs from the remote content (reused from the diffDetector flow).
-* Such files get distinct local/remote tags so they classify as conflicts; all
-* other matched files share the `"same"` tag and classify as unchanged.
+* The swallow is deliberate (the one try/catch of this flow): a config may
+* declare a build artifact that has not been generated yet, and neither `diff`
+* nor `pull` nor drift detection should fail because of it. The key stays
+* untracked and the merge falls back to its conservative classification.
 */
-function computeCustomizationThreeWayMerge(base, local, remote, modifiedFileNames) {
-	const tagFor = (side) => (name) => modifiedFileNames.has(name) ? side : "same";
-	return classifyThreeWay(toMap(base, () => "same"), toMap(local, tagFor("local")), toMap(remote, tagFor("remote")), eq);
+async function readLocalDigest(reader, absolutePath) {
+	try {
+		return computeContentDigest(await reader.read(absolutePath));
+	} catch {
+		return;
+	}
 }
 /**
-* Applies a resolved 3-way merge, returning the merged customization config.
+* Downloads and digests the given remote FILE resources.
 *
-* Auto-merged entries take their `merged` value; conflicts take the chosen
-* side. The resulting resources are flattened back into per-platform js/css
-* lists, preserving the order they appear in the chosen/merged side. Throws a
-* BusinessRuleError when a conflict is left unresolved (programmer invariant).
+* The resource key and the fileKey are paired in a single walk of the raw remote
+* shape: an index keyed by the remote file name could not be looked up when a
+* name contains `/`, because the merge key uses the trailing segment only. A
+* download failure propagates — a transient network error must not silently
+* degrade into "the remote has no content for this key" and change the
+* classification.
 */
-function resolveCustomizationMerge(merge, resolution, local, remote) {
-	const chosen = /* @__PURE__ */ new Map();
-	let scope = "ALL";
-	for (const entry of merge.entries) {
-		let value;
-		if (entry.change.kind === "conflict") {
-			const choice = resolution.get(entry.key);
-			if (choice === void 0) throw new BusinessRuleError(CustomizationErrorCode.CzUnresolvedConflict, `Unresolved conflict for "${entry.key}"`);
-			value = choice === "local" ? entry.local : entry.remote;
-		} else value = entry.merged;
-		if (value === void 0) continue;
-		if (isScopeValue(value)) scope = value.scope;
-		else chosen.set(entry.key, value.resource);
+async function computeRemoteFileDigests(remote, downloader, keys) {
+	const targets = [];
+	for (const { platform, category, resource } of walkCustomizationBuckets(remote)) {
+		if (resource.type !== "FILE") continue;
+		const key = remoteFileResourceKey(platform, category, resource.file.name);
+		if (!keys.has(key)) continue;
+		targets.push({
+			key,
+			fileKey: resource.file.fileKey
+		});
 	}
-	return rebuild(chosen, scope, local, remote);
+	const results = await Promise.all(targets.map(async ({ key, fileKey }) => [key, computeContentDigest(await downloader.download(fileKey))]));
+	return new Map(results);
 }
+//#endregion
+//#region src/core/application/customization/customizationThreeWayMerge.ts
 /**
-* Rebuilds the config from the chosen resource keys, ordering each bucket by the
-* resource's position in local first, then any remote-only resources, so the
-* resulting list is stable and matches the user's local ordering intent.
+* Assembles the customization 3-way merge shared by `diff`, `push` and `pull`.
+*
+* Only the contents that can change a classification are fetched: a key present
+* on one side alone is decided by existence, so local reads are limited to
+* `local ∩ (base ∪ remote)` and downloads to `remote ∩ (base ∪ local)`. Base
+* tags come from the snapshot's recorded digests, with
+* {@link resolveBaseFileDigests} filling in whatever was never recorded.
 */
-function rebuild(chosen, scope, local, remote) {
-	function bucket(platform, category) {
-		const seen = /* @__PURE__ */ new Set();
-		const out = [];
-		const append = (resources) => {
-			for (const resource of resources) {
-				const key = resourceKey(platform, category, resourceName(resource));
-				if (seen.has(key)) continue;
-				const picked = chosen.get(key);
-				if (picked !== void 0) {
-					out.push(picked);
-					seen.add(key);
-				}
-			}
-		};
-		append(platformList(local, platform, category));
-		append(platformList(remote, platform, category));
-		return out;
-	}
+async function buildCustomizationThreeWayMerge({ container, state, baseRevision, local, remote, basePath, localDigests: precomputedLocalDigests }) {
+	const baseKeys = fileResourceKeys(state.config);
+	const localKeys = fileResourceKeys(local);
+	const remoteKeys = fileResourceKeys(remote.config);
+	const localNeeded = intersect(localKeys, union(baseKeys, remoteKeys));
+	const remoteNeeded = intersect(remoteKeys, union(baseKeys, localKeys));
+	const [localDigests, remoteDigests] = await Promise.all([precomputedLocalDigests !== void 0 ? Promise.resolve(subset(precomputedLocalDigests, localNeeded)) : computeFileDigests(local, basePath, container.fileContentReader, localNeeded), computeRemoteFileDigests(remote.raw, container.fileDownloader, remoteNeeded)]);
+	const { tags: baseTags, estimatedKeys } = resolveBaseFileDigests(state.config, state.fileDigests, localDigests, remoteDigests, {
+		localKeys,
+		remoteKeys,
+		legacyState: state.fileDigests.size === 0,
+		remoteUnchanged: baseRevision !== void 0 && baseRevision === remote.revision
+	});
 	return {
-		scope,
-		desktop: {
-			js: bucket("desktop", "js"),
-			css: bucket("desktop", "css")
-		},
-		mobile: {
-			js: bucket("mobile", "js"),
-			css: bucket("mobile", "css")
-		}
+		merge: computeCustomizationThreeWayMerge(state.config, local, remote.config, {
+			base: baseTags,
+			local: localDigests,
+			remote: remoteDigests
+		}),
+		estimatedKeys,
+		remoteDigests,
+		unreadableLocalKeys: difference(localNeeded, localDigests)
 	};
 }
+function difference(keys, digests) {
+	return new Set([...keys].filter((key) => !digests.has(key)));
+}
+function union(a, b) {
+	return new Set([...a, ...b]);
+}
+function intersect(a, b) {
+	const result = /* @__PURE__ */ new Set();
+	for (const key of a) if (b.has(key)) result.add(key);
+	return result;
+}
+function subset(digests, keys) {
+	return new Map([...digests].filter(([key]) => keys.has(key)));
+}
+//#endregion
+//#region src/core/domain/customization/services/customizationStateParser.ts
+/**
+* Collects the per-FILE `digest` entries into the merge's key space. The
+* structure itself is already validated by {@link CustomizationConfigParser},
+* so this pass only reads the extra key and rejects malformed values. A missing
+* `digest` means "untracked", not an error: a state file carrying no digest at
+* all parses into an empty map.
+*/
+function parseFileDigests(parsed) {
+	const digests = /* @__PURE__ */ new Map();
+	if (!isRecord(parsed)) return digests;
+	for (const platform of PLATFORMS) {
+		const platformValue = parsed[platform];
+		if (!isRecord(platformValue)) continue;
+		for (const category of CATEGORIES) {
+			const list = platformValue[category];
+			if (!Array.isArray(list)) continue;
+			for (const raw of list) {
+				const entry = digestEntry(raw, platform, category);
+				if (entry !== void 0) digests.set(entry[0], entry[1]);
+			}
+		}
+	}
+	return digests;
+}
+/** The `[resourceKey, digest]` pair of one serialized resource, if it has one. */
+function digestEntry(raw, platform, category) {
+	if (!isRecord(raw) || raw.type !== "FILE" || typeof raw.path !== "string") return;
+	const digest = raw.digest;
+	if (digest === void 0 || digest === null) return;
+	if (!isContentDigest(digest)) throw new BusinessRuleError(CustomizationErrorCode.CzInvalidConfigStructure, `FILE resource "${raw.path}" has an invalid "digest": ${String(digest)}. Must be a "sha256:<64 lowercase hex chars>" string`);
+	return [resourceKey(platform, category, resourceName({
+		type: "FILE",
+		path: raw.path
+	})), digest];
+}
+/**
+* Parses pre-parsed (codec-decoded) data into a {@link CustomizationState}.
+*
+* The inverse of {@link CustomizationStateSerializer}: the captured config is
+* parsed via the same {@link CustomizationConfigParser} as the local YAML, so
+* the base snapshot is validated identically, then the per-FILE `digest` keys
+* are collected into the snapshot's digest map.
+*/
+const CustomizationStateParser = { parse: (parsed) => ({
+	config: CustomizationConfigParser.parse(parsed),
+	fileDigests: parseFileDigests(parsed)
+}) };
 //#endregion
 //#region src/core/application/customization/customizationRemote.ts
 /**
@@ -11703,59 +12071,6 @@ function toResource(resource) {
 		path: resource.file.name
 	};
 }
-/**
-* Computes the set of same-name FILE basenames whose local content differs from
-* the remote content, across all platforms/categories — the same signal the
-* 2-way `detectCustomizationDiff` uses for the `modified` entries. Reused here so
-* the 3-way merge marks divergent same-name files as conflicts.
-*/
-async function computeModifiedFileNames(local, remote, basePath, container) {
-	const pairs = [
-		...matchedPairs(local.desktop.js, remote.desktop.js),
-		...matchedPairs(local.desktop.css, remote.desktop.css),
-		...matchedPairs(local.mobile.js, remote.mobile.js),
-		...matchedPairs(local.mobile.css, remote.mobile.css)
-	];
-	const modified = /* @__PURE__ */ new Set();
-	if (pairs.length === 0) return modified;
-	const results = await Promise.all(pairs.map(async ({ localResource, remoteFileKey }) => {
-		const localPath = join(basePath, localResource.path);
-		const [localContent, remoteContent] = await Promise.all([container.fileContentReader.read(localPath), container.fileDownloader.download(remoteFileKey)]);
-		const isEqual = Buffer.from(localContent).equals(Buffer.from(remoteContent));
-		return {
-			name: resourceName(localResource),
-			isEqual
-		};
-	}));
-	for (const { name, isEqual } of results) if (!isEqual) modified.add(name);
-	return modified;
-}
-/** Finds matched local-FILE + remote-FILE pairs by basename. */
-function matchedPairs(localResources, remoteResources) {
-	const remoteFileMap = /* @__PURE__ */ new Map();
-	for (const r of remoteResources) if (r.type === "FILE") remoteFileMap.set(remoteResourceName(r), r.file.fileKey);
-	const pairs = [];
-	for (const local of localResources) {
-		if (local.type !== "FILE") continue;
-		const remoteFileKey = remoteFileMap.get(resourceName(local));
-		if (remoteFileKey !== void 0) pairs.push({
-			localResource: local,
-			remoteFileKey
-		});
-	}
-	return pairs;
-}
-//#endregion
-//#region src/core/domain/customization/services/customizationStateParser.ts
-/**
-* Parses pre-parsed (codec-decoded) data into a {@link CustomizationState}.
-*
-* The inverse of {@link CustomizationStateSerializer}: the captured config is
-* parsed via the same {@link CustomizationConfigParser} as the local YAML, so
-* the base snapshot is validated identically. The domain layer does not depend
-* on YAML; the application layer handles codec decoding before calling this.
-*/
-const CustomizationStateParser = { parse: (parsed) => ({ config: CustomizationConfigParser.parse(parsed) }) };
 //#endregion
 //#region src/core/application/customization/loadCustomizationThreeWayInputs.ts
 /**
@@ -11769,7 +12084,7 @@ async function loadCustomizationThreeWayInputs(container) {
 		codec: container.configCodec,
 		stateStorage: container.customizationStateStorage,
 		appRevisionStorage: container.appRevisionStorage,
-		parseState: (parsed) => CustomizationStateParser.parse(parsed).config,
+		parseState: (parsed) => CustomizationStateParser.parse(parsed),
 		stateLabel: "Customization state",
 		loadLocal: async () => {
 			const result = await container.customizationStorage.get();
@@ -11793,17 +12108,58 @@ async function loadCustomizationThreeWayInputs(container) {
 }
 //#endregion
 //#region src/core/application/customization/detectCustomizationThreeWayDiff.ts
+/** How many resource keys a note lists inline before summarizing the rest. */
+const MAX_LISTED_KEYS = 10;
+/**
+* Renders the affected resource keys so the note identifies its subjects.
+*
+* The counts alone cannot be acted on: neither the diff lines nor `customize
+* push` mark which entries were inferred, so "N file(s)" leaves the user with no
+* way to tell them apart from the exactly-compared ones.
+*/
+function formatKeys(keys) {
+	const listed = keys.slice(0, MAX_LISTED_KEYS).join(", ");
+	const rest = keys.length - MAX_LISTED_KEYS;
+	return rest > 0 ? `${listed}, and ${rest} more` : listed;
+}
+function optimisticNote(keys) {
+	return [`Base snapshot has no content digest for ${keys.length} file(s); they were classified by assuming the remote still matches the base (app revision unchanged): ${formatKeys(keys)}.`, "A normal (non-force) `customize push` or `customize pull` records the baseline. If the remote may have been edited outside this tool, run `customize pull --force` first to take the remote side — that replaces every local customization file and your customization config file with the remote copy, discarding the local edits listed above, so save them elsewhere first."].join("\n");
+}
+function conservativeNote(keys) {
+	return [`Base snapshot has no content digest for ${keys.length} file(s); their classification is inferred: ${formatKeys(keys)}.`, "Run `customize pull` once (resolve the entries, or use `--ours` to keep every local copy) to record the baseline for files that exist on the remote or can be read from disk. Subsequent runs use exact content comparison for those files. `--theirs` records the baseline too, but it replaces the local files on disk with the remote copies wherever the remote side has a body, so save the local edits elsewhere first."].join("\n");
+}
+function unreadableNote(keys) {
+	return [`${keys.length} file(s) declared in the customization config file could not be read from disk, so their content counted as unknown and they are listed as changed: ${formatKeys(keys)}.`, "Build or restore those files (or fix the declared paths) and run `customize diff` again to see the real classification."].join("\n");
+}
+/**
+* Builds the caveats for keys the classification could not compare exactly:
+* those whose base content was inferred rather than read from the snapshot, and
+* those whose local body was unreadable. Only keys that actually surfaced as a
+* diff line are reported: such a key classified as `unchanged` tells the user
+* nothing, and over-reporting would train them to ignore the note.
+*/
+function buildNotes(estimatedKeys, unreadableLocalKeys, changedKeys) {
+	const changedIn = (keys) => [...keys].filter((key) => changedKeys.has(key));
+	const notes = [];
+	const optimistic = changedIn(estimatedKeys.optimistic);
+	if (optimistic.length > 0) notes.push(optimisticNote(optimistic));
+	const conservative = changedIn(estimatedKeys.conservative);
+	if (conservative.length > 0) notes.push(conservativeNote(conservative));
+	const unreadable = changedIn(unreadableLocalKeys);
+	if (unreadable.length > 0) notes.push(unreadableNote(unreadable));
+	return notes;
+}
 /**
 * Detects customization differences with 3-way awareness.
 *
 * When a state (base snapshot) exists, classifies changes into local-only,
-* remote drift, and conflicts via the file-name-keyed merge. Same-name files
-* whose content diverges are conflicts. When no state exists, falls back to the
-* existing 2-way `detectCustomizationDiff` (the CLI renders it with its 2-way
-* printer).
+* remote drift, and conflicts via the resource-key-keyed merge, comparing FILE
+* contents by digest against the base snapshot. When no state exists, falls back
+* to the existing 2-way `detectCustomizationDiff` (the CLI renders it with its
+* 2-way printer).
 */
 async function detectCustomizationThreeWayDiff({ container, input }) {
-	const { state, local, remote } = await loadCustomizationThreeWayInputs(container);
+	const { state, baseRevision, local, remote } = await loadCustomizationThreeWayInputs(container);
 	if (state === void 0 || local === void 0) return {
 		mode: "two-way",
 		diff: await detectCustomizationDiff({
@@ -11811,8 +12167,15 @@ async function detectCustomizationThreeWayDiff({ container, input }) {
 			input: { basePath: input.basePath }
 		})
 	};
-	const modifiedFileNames = await computeModifiedFileNames(local, remote.raw, input.basePath, container);
-	return buildRecordThreeWayDiff(computeCustomizationThreeWayMerge(state, local, remote.config, modifiedFileNames), (entry) => entry.key);
+	const { merge, estimatedKeys, unreadableLocalKeys } = await buildCustomizationThreeWayMerge({
+		container,
+		state,
+		baseRevision,
+		local,
+		remote,
+		basePath: input.basePath
+	});
+	return buildRecordThreeWayDiff(merge, (entry) => entry.key, [], buildNotes(estimatedKeys, unreadableLocalKeys, new Set(merge.entries.filter((entry) => entry.change.kind === "localOnly" || entry.change.kind === "remoteOnly" || entry.change.kind === "conflict").map((entry) => entry.key))));
 }
 //#endregion
 //#region src/cli/commands/customize/diff.ts
@@ -11867,20 +12230,37 @@ var diff_default$10 = define({
 * stringification (via the codec port in the application layer).
 *
 * The snapshot is serialized through the exact same path as `capture`
-* ({@link CustomizationConfigSerializer}) so the state file is round-trip
-* compatible with the captured config. The app revision is NOT written here; it
-* is persisted separately via `AppRevisionStorage`.
+* ({@link CustomizationConfigSerializer}), with the recorded content digest
+* injected into each FILE entry via the serializer's decorate hook. URL
+* resources and FILE resources with no recorded digest are written unchanged,
+* so the state file stays round-trip compatible with the captured config. The
+* app revision is NOT written here; it is persisted separately via
+* `AppRevisionStorage`.
 */
-const CustomizationStateSerializer = { serialize: (state) => CustomizationConfigSerializer.serialize(state.config) };
+const CustomizationStateSerializer = { serialize: (state) => CustomizationConfigSerializer.serialize(state.config, (platform, category, resource) => {
+	if (resource.type !== "FILE") return;
+	const digest = state.fileDigests.get(resourceKey(platform, category, resourceName(resource)));
+	return digest === void 0 ? void 0 : { digest };
+}) };
 //#endregion
 //#region src/core/application/customization/customizationStateIo.ts
 /**
-* Persists the new base: the customization snapshot (state file) and the app
-* revision (`state/<appName>/revision.yaml`) side by side. The two writes are
-* kept together so they always advance as a pair (snapshot → revision).
+* Persists the new base: the customization snapshot (config + FILE content
+* digests) and the app revision (`state/<appName>/revision.yaml`) side by side.
+* The two writes are kept together so they always advance as a pair
+* (snapshot → revision).
+*
+* `fileDigests` is computed by the caller rather than here: this function runs
+* after `updateCustomization` (it needs the resulting revision), while push must
+* digest its files *before* uploading them, and pull's merge path records the
+* remote's digests rather than what is on disk. Keeping the parameter required
+* still makes a digest-less snapshot impossible to write by accident.
 */
-async function saveCustomizationSnapshotAndRevision(container, config, revision) {
-	await saveSnapshotState(container.customizationStateStorage, container.configCodec, CustomizationStateSerializer.serialize, { config });
+async function saveCustomizationSnapshotAndRevision(container, config, fileDigests, revision) {
+	await saveSnapshotState(container.customizationStateStorage, container.configCodec, CustomizationStateSerializer.serialize, {
+		config,
+		fileDigests
+	});
 	await saveAppRevision(container.appRevisionStorage, container.configCodec, revision);
 }
 //#endregion
@@ -11897,27 +12277,40 @@ async function saveCustomizationSnapshotAndRevision(container, config, revision)
 *   resolution, so an aborted resolution leaves the working copy untouched.
 */
 async function pullCustomization({ container, input }) {
-	const { state, local, remote } = await loadCustomizationThreeWayInputs(container);
+	const { state, baseRevision, local, remote } = await loadCustomizationThreeWayInputs(container);
 	if (input.force || state === void 0 || local === void 0) {
+		const preservePaths = local !== void 0 ? buildPreservePaths(local) : void 0;
 		const captured = await captureCustomization({
 			container,
 			input: {
 				basePath: input.captureBasePath,
-				filePrefix: input.filePrefix
+				filePrefix: input.filePrefix,
+				preservePaths
 			}
 		});
 		await container.customizationStorage.update(captured.configText);
-		await saveCustomizationSnapshotAndRevision(container, remote.config, remote.revision);
+		const fileDigests = await computeSnapshotFileDigests(captured.config, input.basePath, container.fileContentReader);
+		await saveCustomizationSnapshotAndRevision(container, captured.config, fileDigests, remote.revision);
 		return { mode: input.force ? "force" : "firstTime" };
 	}
-	const modifiedFileNames = await computeModifiedFileNames(local, remote.raw, input.basePath, container);
+	const { merge, remoteDigests, estimatedKeys, unreadableLocalKeys } = await buildCustomizationThreeWayMerge({
+		container,
+		state,
+		baseRevision,
+		local,
+		remote,
+		basePath: input.basePath
+	});
 	return {
 		mode: "merged",
-		merge: computeCustomizationThreeWayMerge(state, local, remote.config, modifiedFileNames),
+		merge,
 		local,
 		remote: remote.raw,
 		remoteConfig: remote.config,
-		remoteRevision: remote.revision
+		remoteRevision: remote.revision,
+		remoteDigests,
+		estimatedKeys,
+		unreadableLocalKeys
 	};
 }
 /**
@@ -11933,18 +12326,15 @@ async function pullCustomization({ container, input }) {
 async function applyPulledCustomizationMerge({ container, input }) {
 	const merged = wrapBusinessRuleError(() => resolveCustomizationMerge(input.merge, input.resolution, input.local, input.remoteConfig));
 	const fromRemote = /* @__PURE__ */ new Set();
-	for (const entry of input.merge.entries) {
-		const name = nameFromKey(entry.key);
-		if (name === void 0) continue;
-		if (entry.change.kind === "remoteOnly") fromRemote.add(name);
-		else if (entry.change.kind === "conflict" && input.resolution.get(entry.key) === "remote") fromRemote.add(name);
-	}
+	for (const entry of input.merge.entries) if (entry.change.kind === "remoteOnly") fromRemote.add(entry.key);
+	else if (entry.change.kind === "conflict" && input.resolution.get(entry.key) === "remote") fromRemote.add(entry.key);
 	const remoteFileKeys = remoteFileKeyMap(input.remote);
 	const downloads = [];
-	for (const resource of allFileResources(merged)) {
-		const name = resourceName(resource);
-		if (!fromRemote.has(name)) continue;
-		const fileKey = remoteFileKeys.get(name);
+	for (const { platform, category, resource } of walkCustomizationBuckets(merged)) {
+		if (resource.type !== "FILE") continue;
+		const key = resourceKey(platform, category, resourceName(resource));
+		if (!fromRemote.has(key)) continue;
+		const fileKey = remoteFileKeys.get(key);
 		if (fileKey === void 0) continue;
 		const absolutePath = resolve(input.basePath, resource.path);
 		downloads.push((async () => {
@@ -11955,38 +12345,111 @@ async function applyPulledCustomizationMerge({ container, input }) {
 	await Promise.all(downloads);
 	const configText = stringifyConfig(container.configCodec, CustomizationConfigSerializer.serialize(merged));
 	await container.customizationStorage.update(configText);
-	await saveCustomizationSnapshotAndRevision(container, input.remoteConfig, input.remoteRevision);
+	await saveCustomizationSnapshotAndRevision(container, merged, await buildMergedBaseDigests(merged, input.basePath, input.remoteDigests, container), input.remoteRevision);
 }
-function allFileResources(config) {
-	return [
-		...config.desktop.js,
-		...config.desktop.css,
-		...config.mobile.js,
-		...config.mobile.css
-	].filter((r) => r.type === "FILE");
+/**
+* Base digests for a merge that was just applied.
+*
+* A key the remote still holds records the *remote's* digest, even when the
+* local side won the merge: the base means "what local and remote last agreed
+* on", and content that stayed local was never uploaded. Recording the on-disk
+* bytes instead would make the very next diff report the local edit as remote
+* drift and block the push. Keys the remote does not have (locally added files,
+* or remote-only files freshly downloaded) take the on-disk digest.
+*/
+async function buildMergedBaseDigests(merged, basePath, remoteDigests, container) {
+	const mergedKeys = fileResourceKeys(merged);
+	const fromDisk = new Set([...mergedKeys].filter((key) => !remoteDigests.has(key)));
+	const diskDigests = await computeFileDigests(merged, basePath, container.fileContentReader, fromDisk);
+	const digests = /* @__PURE__ */ new Map();
+	for (const key of mergedKeys) {
+		const digest = remoteDigests.get(key) ?? diskDigests.get(key);
+		if (digest !== void 0) digests.set(key, digest);
+	}
+	return digests;
 }
 /**
-* Extracts the file/resource name from a merge key. Resource keys are
-* `platform:category:name`; the `config:scope` key has no resource name.
+* Builds the path-preservation map for `captureCustomization`: bucket-qualified
+* key (`resourceKey(platform, category, FILE basename)`) → declared local
+* relative path. The composite key matches the merge identity so cross-bucket
+* same-basename files (e.g. `app/desktop/js/main.js` vs `app/mobile/js/main.js`)
+* stay distinct instead of colliding under a flat basename map. Only FILE
+* resources carry a path.
 */
-function nameFromKey(key) {
-	const parts = key.split(":");
-	if (parts.length < 3) return void 0;
-	return parts.slice(2).join(":");
+function buildPreservePaths(config) {
+	const map = /* @__PURE__ */ new Map();
+	for (const { platform, category, resource } of walkCustomizationBuckets(config)) if (resource.type === "FILE") map.set(resourceKey(platform, category, resourceName(resource)), resource.path);
+	return map;
 }
+/**
+* Remote FILE `fileKey`s under the merge identity, so a body is looked up by the
+* same key the merge decided to take from the remote. A flat basename map would
+* make cross-bucket same-basename files (e.g. `desktop/js/main.js` and
+* `mobile/js/main.js`) resolve to whichever bucket was registered last,
+* overwriting one bucket's body with the other's.
+*/
 function remoteFileKeyMap(remote) {
 	const map = /* @__PURE__ */ new Map();
-	const add = (resources) => {
-		for (const r of resources) if (r.type === "FILE") map.set(remoteResourceName(r), r.file.fileKey);
-	};
-	add(remote.desktop.js);
-	add(remote.desktop.css);
-	add(remote.mobile.js);
-	add(remote.mobile.css);
+	for (const { platform, category, resource } of walkCustomizationBuckets(remote)) if (resource.type === "FILE") map.set(remoteFileResourceKey(platform, category, resource.file.name), resource.file.fileKey);
 	return map;
 }
 //#endregion
 //#region src/cli/commands/customize/pull.ts
+/**
+* Derives the path bases `runPull` feeds to the application layer.
+*
+* - `basePath` (= push's {@link computeBasePath}) is where merged/downloaded
+*   content resolves and push uploads from.
+* - `captureBasePath` + `filePrefix` are passed to the capture-equivalent
+*   (force / first-time) path.
+*
+* Invariant: `join(captureBasePath, filePrefix) === basePath`, so pull writes
+* exactly where push uploads from. Exported so the invariant test pins these
+* exact derivations rather than a hand-mirrored copy.
+*/
+function derivePullPaths(customizeFilePath) {
+	return {
+		basePath: computeBasePath(customizeFilePath),
+		captureBasePath: dirname(resolve(customizeFilePath)),
+		filePrefix: deriveFilePrefix(customizeFilePath)
+	};
+}
+/**
+* What each choice does. `pull` never writes to kintone, so the destruction is
+* one-directional: only the copy on disk can be lost here, and the wording says
+* which choice loses it.
+*
+* The scope is a single value in the customization config file, so no file moves
+* either way. A resource whose remote side is a URL — or gone — carries no body
+* to write over the local copy, hence "wherever the remote side has a body"
+* rather than a flat promise that the file on disk is replaced.
+*/
+const SCOPE_EFFECT = "remote takes the remote scope; local keeps the local one, and the remote stays untouched until the next `customize push`";
+const RESOURCE_EFFECT = "remote replaces the local file on disk wherever the remote side has a body; local keeps the copy on disk, and the remote stays untouched until the next `customize push`";
+/**
+* Why the divergence may not be real, when it may not be.
+*
+* An unreadable local file counts as unknown content, so it conflicts with any
+* remote change even where a baseline was recorded — a separate case from a
+* missing baseline, and the only one where picking `local` leaves the merge
+* pointing at a file that is not on disk.
+*/
+function conflictCaveat(context, key) {
+	if (context.unreadableLocalKeys.has(key)) return "the local file could not be read, so this may not be a real conflict";
+	if (context.estimatedKeys.conservative.has(key)) return "no recorded baseline for this file, so this may not be a real conflict";
+}
+/**
+* The conflict prompt. Exported so its wording is pinned by a test: this prompt
+* is the only place where picking the wrong side discards content, and both the
+* caveat and the effect are chosen here.
+*/
+function buildConflictPrompt(context, key) {
+	const isScope = key === SCOPE_KEY;
+	const effect = isScope ? SCOPE_EFFECT : RESOURCE_EFFECT;
+	const caveat = conflictCaveat(context, key);
+	const detail = caveat === void 0 ? effect : `${caveat}; ${effect}`;
+	return `Conflict on ${isScope ? "scope" : `entry "${key}"`}. Keep which side? (${detail})`;
+}
 async function resolveConflicts$1(merged, options) {
 	const resolution = /* @__PURE__ */ new Map();
 	for (const conflict of merged.merge.conflicts) {
@@ -11999,7 +12462,7 @@ async function resolveConflicts$1(merged, options) {
 			continue;
 		}
 		const selected = await p.select({
-			message: `Conflict on file "${conflict.key}". Keep which side?`,
+			message: buildConflictPrompt(merged, conflict.key),
 			options: [{
 				value: "local",
 				label: "local (ours)"
@@ -12015,9 +12478,7 @@ async function resolveConflicts$1(merged, options) {
 }
 async function runPull$1(containerConfig, options) {
 	const container = createCustomizationCliContainer(containerConfig);
-	const basePath = computeBasePath(containerConfig.customizeFilePath);
-	const captureBasePath = dirname(resolve(containerConfig.customizeFilePath));
-	const filePrefix = deriveFilePrefix(containerConfig.customizeFilePath);
+	const { basePath, captureBasePath, filePrefix } = derivePullPaths(containerConfig.customizeFilePath);
 	const s = p.spinner();
 	s.start("Pulling customization from kintone...");
 	let result;
@@ -12055,7 +12516,8 @@ async function runPull$1(containerConfig, options) {
 				local: result.local,
 				remote: result.remote,
 				remoteConfig: result.remoteConfig,
-				remoteRevision: result.remoteRevision
+				remoteRevision: result.remoteRevision,
+				remoteDigests: result.remoteDigests
 			}
 		});
 		p.log.success("Local customization merged and written.");
@@ -12077,7 +12539,8 @@ async function runPull$1(containerConfig, options) {
 			local: result.local,
 			remote: result.remote,
 			remoteConfig: result.remoteConfig,
-			remoteRevision: result.remoteRevision
+			remoteRevision: result.remoteRevision,
+			remoteDigests: result.remoteDigests
 		}
 	});
 	p.log.success("Conflicts resolved. Local customization written.");
@@ -12131,6 +12594,9 @@ var pull_default$10 = define({
 //#region src/core/application/customization/pushCustomization.ts
 /** Pull command name surfaced in the drift hint message. */
 const CUSTOMIZE_PULL_COMMAND = "customize pull";
+function inferredDriftHint(count) {
+	return `Drift possibly inferred: no recorded content baseline for ${count} of the drifted file(s). Run \`customize diff\` for the affected file(s); the pull above also records the baseline.`;
+}
 async function resolvePlatform(platform, basePath, fileUploader) {
 	const resolveList = async (resources) => Promise.all(resources.map(async (resource) => {
 		if (resource.type === "URL") return resource;
@@ -12151,10 +12617,11 @@ async function resolvePlatform(platform, basePath, fileUploader) {
 /**
 * Applies the local customization config to the remote with drift detection.
 *
-* - Loads base/local/remote and computes the file-name-keyed 3-way merge. drift
-*   (remoteOnly or conflict entries) && !force → {@link buildDriftConflict}
-*   tagged with `ConfigDrift`. Same-name files whose content
-*   diverges count as conflicts and block a non-forced push.
+* - Loads base/local/remote and computes the resource-key-keyed 3-way merge.
+*   drift (remoteOnly or conflict entries) && !force → {@link buildDriftConflict}
+*   tagged with `ConfigDrift`. A file edited only locally is a local change, not
+*   drift, so it pushes without `--force`; a file whose remote body moved away
+*   from the base blocks the push.
 * - Replaces the full js/css lists with the local config's resolved (uploaded)
 *   resources via `updateAppCustomize`, so renames are expressed as old-name
 *   removal + new-name add (full-list replace — NOT an inexpressible
@@ -12165,12 +12632,25 @@ async function resolvePlatform(platform, basePath, fileUploader) {
 * post-apply revision as the new base (snapshot → revision).
 */
 async function pushCustomization({ container, input }) {
-	const { state, local, remote } = await loadCustomizationThreeWayInputs(container);
+	const { state, baseRevision, local, remote } = await loadCustomizationThreeWayInputs(container);
 	if (local === void 0) throw new ValidationError(ValidationErrorCode.InvalidInput, "Customization config file not found");
 	const firstTime = state === void 0;
-	if (!firstTime && !input.force) {
-		const modifiedFileNames = await computeModifiedFileNames(local, remote.raw, input.basePath, container);
-		if (computeCustomizationThreeWayMerge(state, local, remote.config, modifiedFileNames).entries.some((e) => e.change.kind === "remoteOnly" || e.change.kind === "conflict")) throw buildDriftConflict(CUSTOMIZE_PULL_COMMAND);
+	const localDigests = await computeSnapshotFileDigests(local, input.basePath, container.fileContentReader);
+	if (state !== void 0 && !input.force) {
+		const { merge, estimatedKeys } = await buildCustomizationThreeWayMerge({
+			container,
+			state,
+			baseRevision,
+			local,
+			remote,
+			basePath: input.basePath,
+			localDigests
+		});
+		const driftKeys = merge.entries.filter((e) => e.change.kind === "remoteOnly" || e.change.kind === "conflict").map((e) => e.key);
+		if (driftKeys.length > 0) {
+			const inferred = driftKeys.filter((key) => estimatedKeys.conservative.has(key)).length;
+			throw buildDriftConflict(CUSTOMIZE_PULL_COMMAND, inferred > 0 ? inferredDriftHint(inferred) : void 0);
+		}
 	}
 	const [desktop, mobile] = await Promise.all([resolvePlatform(local.desktop, input.basePath, container.fileUploader), resolvePlatform(local.mobile, input.basePath, container.fileUploader)]);
 	ResourceMerger.assertResourceCount("desktop.js", desktop.js);
@@ -12194,7 +12674,7 @@ async function pushCustomization({ container, input }) {
 		scope: local.scope,
 		desktop: local.desktop,
 		mobile: local.mobile
-	}, newRevision);
+	}, localDigests, newRevision);
 	return {
 		mode: firstTime ? "firstTime" : "push",
 		revision: newRevision
@@ -15600,7 +16080,8 @@ function buildTasks(args) {
 						local: result.local,
 						remote: result.remote,
 						remoteConfig: result.remoteConfig,
-						remoteRevision: result.remoteRevision
+						remoteRevision: result.remoteRevision,
+						remoteDigests: result.remoteDigests
 					}
 				});
 				return "merged";